polyctl 0.7.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. polyctl/__init__.py +7 -0
  2. polyctl/__main__.py +5 -0
  3. polyctl/a2a.py +226 -0
  4. polyctl/a2a_mcp.py +546 -0
  5. polyctl/acp.py +417 -0
  6. polyctl/adapters/README.md +101 -0
  7. polyctl/adapters/aider.json +32 -0
  8. polyctl/adapters/amazon-q.json +15 -0
  9. polyctl/adapters/amp.json +16 -0
  10. polyctl/adapters/antigravity.json +120 -0
  11. polyctl/adapters/claude-code.json +229 -0
  12. polyctl/adapters/cloud-generic.json +57 -0
  13. polyctl/adapters/codex.json +47 -0
  14. polyctl/adapters/command-code.json +45 -0
  15. polyctl/adapters/copilot.json +17 -0
  16. polyctl/adapters/cursor-agent.json +29 -0
  17. polyctl/adapters/deepseek.json +13 -0
  18. polyctl/adapters/droid.json +34 -0
  19. polyctl/adapters/gemini.json +30 -0
  20. polyctl/adapters/grok.json +22 -0
  21. polyctl/adapters/hermes.json +34 -0
  22. polyctl/adapters/kilocode.json +30 -0
  23. polyctl/adapters/kimi.json +23 -0
  24. polyctl/adapters/kiro.json +332 -0
  25. polyctl/adapters/ollama.json +29 -0
  26. polyctl/adapters/omp.json +34 -0
  27. polyctl/adapters/openai-api.json +68 -0
  28. polyctl/adapters/opencode.json +162 -0
  29. polyctl/adapters/pi.json +24 -0
  30. polyctl/adapters/pr-agent.json +54 -0
  31. polyctl/adapters/profiles.json +9 -0
  32. polyctl/adapters/qoder.json +163 -0
  33. polyctl/adapters/qwen.json +27 -0
  34. polyctl/adapters/reasonix.json +25 -0
  35. polyctl/adapters/rewriters/rtk.json +24 -0
  36. polyctl/adapters/trae.json +31 -0
  37. polyctl/adapters/vendors.json +42 -0
  38. polyctl/adapters/warp.json +88 -0
  39. polyctl/allowlist.py +1756 -0
  40. polyctl/api_review.py +920 -0
  41. polyctl/cli.py +835 -0
  42. polyctl/conformance_harness.py +9 -0
  43. polyctl/demo.py +503 -0
  44. polyctl/drivers.py +146 -0
  45. polyctl/email.py +160 -0
  46. polyctl/features.py +98 -0
  47. polyctl/journal.py +144 -0
  48. polyctl/language.py +945 -0
  49. polyctl/lib.py +1296 -0
  50. polyctl/matrix.py +660 -0
  51. polyctl/mcp.py +1362 -0
  52. polyctl/ntfy.py +169 -0
  53. polyctl/outbound.py +39 -0
  54. polyctl/parts/__init__.py +5 -0
  55. polyctl/parts/cli_authority.py +2615 -0
  56. polyctl/parts/cli_channels.py +1325 -0
  57. polyctl/parts/cli_checks.py +2293 -0
  58. polyctl/parts/cli_completion.py +686 -0
  59. polyctl/parts/cli_evidence.py +141 -0
  60. polyctl/parts/cli_gain.py +375 -0
  61. polyctl/parts/cli_harness.py +392 -0
  62. polyctl/parts/cli_hooks.py +1816 -0
  63. polyctl/parts/cli_install.py +638 -0
  64. polyctl/parts/cli_lanes.py +106 -0
  65. polyctl/parts/cli_maintenance.py +2536 -0
  66. polyctl/parts/cli_next.py +248 -0
  67. polyctl/parts/cli_pr.py +53 -0
  68. polyctl/parts/cli_project.py +2857 -0
  69. polyctl/parts/cli_review.py +5158 -0
  70. polyctl/parts/cli_status.py +898 -0
  71. polyctl/parts/lib_adapters.py +2933 -0
  72. polyctl/parts/lib_alarms.py +2106 -0
  73. polyctl/parts/lib_events.py +224 -0
  74. polyctl/parts/lib_evidence.py +412 -0
  75. polyctl/parts/lib_gates.py +2099 -0
  76. polyctl/parts/lib_lanes.py +829 -0
  77. polyctl/parts/lib_mail.py +1541 -0
  78. polyctl/parts/lib_next.py +652 -0
  79. polyctl/parts/lib_pr.py +331 -0
  80. polyctl/parts/lib_slices.py +3337 -0
  81. polyctl/parts/lib_state.py +2415 -0
  82. polyctl/parts/lib_transcript.py +4118 -0
  83. polyctl/pressure.py +325 -0
  84. polyctl/prices.json +47 -0
  85. polyctl/procs.py +1194 -0
  86. polyctl/settings.py +505 -0
  87. polyctl/skill/SKILL.md +365 -0
  88. polyctl/skillkit.py +503 -0
  89. polyctl/storage.py +2055 -0
  90. polyctl/telegram.py +327 -0
  91. polyctl/tiers.py +123 -0
  92. polyctl/verdicts.py +41 -0
  93. polyctl/watchdog.py +3887 -0
  94. polyctl/web.py +337 -0
  95. polyctl-0.7.0.dist-info/METADATA +235 -0
  96. polyctl-0.7.0.dist-info/RECORD +99 -0
  97. polyctl-0.7.0.dist-info/WHEEL +4 -0
  98. polyctl-0.7.0.dist-info/entry_points.txt +5 -0
  99. polyctl-0.7.0.dist-info/licenses/LICENSE +21 -0
polyctl/procs.py ADDED
@@ -0,0 +1,1194 @@
1
+ """Process introspection without a dependency.
2
+
3
+ psutil answers "which processes exist, what is each one's exact argv, its cwd,
4
+ its parent and group, does it have a terminal" — and polyctl needs exactly those
5
+ answers to tell an agent turn from a shell that mentions one. We do not install
6
+ packages, so this borrows psutil's *method*: on macOS the public libproc calls
7
+ (`proc_listpids`, `proc_pidinfo` with PROC_PIDTBSDINFO and PROC_PIDVNODEPATHINFO)
8
+ and `sysctl(KERN_PROCARGS2)` for the argument vector, through ctypes; on Linux
9
+ the /proc files. Both give the argv as a vector, so a path with a space in it
10
+ ("…/Application Support/kiro-cli/node") is one argument and not two — the bug
11
+ class that whitespace-splitting `ps` output produced. Both answer in
12
+ milliseconds where `pgrep -f` plus one `lsof` per pid took seconds.
13
+
14
+ Every function falls back to the platform's `ps` and `lsof` when the native path is
15
+ unavailable or fails its self-check, so nothing here can make polyctl blind. No tool here
16
+ is started through a shell. Where the table itself cannot be read - the reader fails,
17
+ does not answer in time, or answers nothing a table can be made of - the readers raise
18
+ TableUnreadable rather than answer an empty one: an empty table reads as no process at
19
+ all, and a guard that asks whether anything runs passed when it could not look.
20
+ """
21
+ import contextlib
22
+ import ctypes
23
+ import ctypes.util
24
+ import os
25
+ import struct
26
+ import subprocess
27
+ import sys
28
+ import time
29
+ UTF8 = "utf-8" # every text file polyctl writes or reads; Windows would otherwise use cp1252
30
+
31
+ _NATIVE = None # decided on first use: "darwin" | "linux" | None (ps and lsof fallbacks)
32
+
33
+
34
+ class TableUnreadable(Exception):
35
+ """The process table could not be read on this platform; the message names the platform and why.
36
+
37
+ On Windows the table is one PowerShell query, and a PowerShell that was missing, failed or did
38
+ not answer in time gave an empty table: every caller read that as fact - no agent turn running,
39
+ no reviewer alive, nothing holding a session - and a guard that asks "is anything running?"
40
+ passed when it could not look. It is an error its callers see now, and each that decides
41
+ something from the table refuses or holds; one that only shows it says it could not look
42
+ (WINDOWS-TABLE-CLOSED).
43
+ """
44
+
45
+ def __init__(self, why, platform=None):
46
+ self.why = why
47
+ self.platform = platform or platform_name()
48
+ super().__init__(f"the process table could not be read on {self.platform}: {why}")
49
+
50
+
51
+ def platform_name():
52
+ """The platform as a person names it, for a message that says where something could not be done."""
53
+ if sys.platform == "win32":
54
+ return "Windows"
55
+ if sys.platform == "darwin":
56
+ return "macOS"
57
+ return "Linux" if sys.platform.startswith("linux") else sys.platform
58
+
59
+
60
+ class _Unanswered(str):
61
+ """A tool's empty answer that knows why it is empty: "" to every reader, `why` to the one that asks
62
+ (WINDOWS-TABLE-CLOSED)."""
63
+
64
+ def __new__(cls, why):
65
+ empty = super().__new__(cls, "")
66
+ empty.why = why
67
+ return empty
68
+
69
+
70
+ def _run(argv):
71
+ """A platform tool's standard output; an empty answer that says why when it gives none.
72
+
73
+ Started without a shell and found where polyctl finds every program (lib.binary_candidates),
74
+ so a launchd job whose PATH is minimal still finds it; it reads nothing from standard
75
+ input. Every reader takes the answer as text, and "" when the tool could not be run, as
76
+ the shell helper this replaced gave; its first line of standard error, its exit status or
77
+ its silence says why, for the reader that must not take nothing for an answer: the process
78
+ table read an empty PowerShell answer as no process at all (WINDOWS-TABLE-CLOSED).
79
+ """
80
+ from . import lib
81
+ program = lib.runnable_binary(argv[0])
82
+ if program is None:
83
+ return _Unanswered(f"{argv[0]} was not found")
84
+ try:
85
+ done = subprocess.run([program, *argv[1:]], stdin=subprocess.DEVNULL, stdout=subprocess.PIPE,
86
+ stderr=subprocess.PIPE, text=True, encoding=UTF8, errors="replace", timeout=30)
87
+ except subprocess.TimeoutExpired:
88
+ return _Unanswered(f"{argv[0]} did not answer within 30 seconds")
89
+ except Exception as exc:
90
+ return _Unanswered(f"{argv[0]} could not be started ({type(exc).__name__}: {exc})")
91
+ if (done.stdout or "").strip():
92
+ return done.stdout
93
+ said = next((line.strip() for line in (getattr(done, "stderr", None) or "").splitlines() if line.strip()), "")
94
+ status = getattr(done, "returncode", 0)
95
+ why = f"{argv[0]} exited with status {status}" if status else f"{argv[0]} printed nothing"
96
+ return _Unanswered(f"{why}: {said[:200]}" if said else why)
97
+
98
+
99
+ def system_directory():
100
+ """Windows' system directory as Windows names it (GetSystemDirectoryW), or None where it cannot be asked.
101
+
102
+ For lib.windows_system_directory when SystemRoot names none: the lib's parts may not load ctypes
103
+ (WINDOWS-NO-CWD-EXEC).
104
+ """
105
+ try:
106
+ answer = ctypes.create_unicode_buffer(32768)
107
+ size = ctypes.windll.kernel32.GetSystemDirectoryW(answer, len(answer))
108
+ except (AttributeError, OSError):
109
+ return None
110
+ return answer.value if size else None
111
+
112
+
113
+ def oem_encoding():
114
+ """The codec of Windows' OEM code page, which its console programs write to a pipe in - "cp857" on a Turkish
115
+ Windows, "cp437" on an American one - or None where there is none to ask (WINDOWS-SAY-WHY).
116
+
117
+ For lib.console_text: the lib's parts may not load ctypes. GetOEMCP is asked, and a code page
118
+ Python has no codec for is none.
119
+ """
120
+ import codecs
121
+ try:
122
+ name = f"cp{int(ctypes.windll.kernel32.GetOEMCP())}"
123
+ codecs.lookup(name)
124
+ except (AttributeError, OSError, LookupError, ValueError):
125
+ return None
126
+ return name
127
+
128
+
129
+ def _clock_seconds(text):
130
+ """Seconds in a `ps -o etime` reading, [[dd-]hh:]mm:ss, or None."""
131
+ days, _, clock = text.strip().rpartition("-")
132
+ try:
133
+ seconds = 0
134
+ for part in clock.split(":"):
135
+ seconds = seconds * 60 + int(part)
136
+ return seconds + int(days or 0) * 86400
137
+ except ValueError:
138
+ return None
139
+
140
+
141
+ def _cim_epoch(value):
142
+ """Epoch seconds of a Win32_Process CreationDate as it reaches polyctl, or None.
143
+
144
+ Windows PowerShell's ConvertTo-Json writes a date as /Date(<milliseconds>)/; WMI's own
145
+ form is DMTF, yyyymmddHHMMSS.ffffff followed by the offset from UTC in minutes.
146
+ """
147
+ import calendar
148
+ import re as _re
149
+ text = str(value or "")
150
+ m = _re.fullmatch(r"/Date\((-?\d+)[^)]*\)/", text)
151
+ if m:
152
+ return int(m.group(1)) / 1000
153
+ m = _re.fullmatch(r"(\d{14})\.\d+([+-])(\d{3})", text)
154
+ if m:
155
+ local = calendar.timegm(time.strptime(m.group(1), "%Y%m%d%H%M%S"))
156
+ return local - int(m.group(2) + m.group(3)) * 60
157
+ return None
158
+
159
+
160
+ def group_cpu_seconds(pgid):
161
+ """CPU seconds spent so far by every process in one process group, or None when unreadable (#25).
162
+
163
+ A reviewer thinking spends CPU as its answer streams in; one that has hung
164
+ spends none. Windows exposes no process group here, so it answers None.
165
+ """
166
+ if os.name == "nt":
167
+ return None
168
+ total, found = 0.0, False
169
+ if sys.platform.startswith("linux"):
170
+ tick = os.sysconf("SC_CLK_TCK")
171
+ for entry in os.listdir("/proc"):
172
+ if not entry.isdigit():
173
+ continue
174
+ try:
175
+ with open(f"/proc/{entry}/stat", "rb") as fh:
176
+ fields = fh.read().rsplit(b")", 1)[1].split()
177
+ except (OSError, IndexError):
178
+ continue
179
+ if len(fields) > 12 and int(fields[2]) == pgid:
180
+ total += (int(fields[11]) + int(fields[12])) / tick
181
+ found = True
182
+ return total if found else None
183
+ for line in _run(["ps", "-A", "-o", "pgid=,time="]).splitlines():
184
+ parts = line.split()
185
+ if len(parts) != 2 or not parts[0].isdigit() or int(parts[0]) != pgid:
186
+ continue
187
+ seconds = 0.0
188
+ try:
189
+ for piece in parts[1].split(":"):
190
+ seconds = seconds * 60 + float(piece)
191
+ except ValueError:
192
+ continue
193
+ total += seconds
194
+ found = True
195
+ return total if found else None
196
+
197
+
198
+ # ---------------------------------------------------------------- macOS (libproc)
199
+ class _Darwin:
200
+ CTL_KERN, KERN_ARGMAX, KERN_PROCARGS2 = 1, 8, 49
201
+ PROC_ALL_PIDS, PROC_PIDTBSDINFO, PROC_PIDVNODEPATHINFO = 1, 3, 9
202
+ BSDINFO_SIZE, VNODEPATHINFO_SIZE, VNODE_INFO_SIZE, MAXPATHLEN = 136, 2352, 152, 1024
203
+ NODEV = 0xFFFFFFFF
204
+
205
+ def __init__(self):
206
+ self.libc = ctypes.CDLL(ctypes.util.find_library("c"), use_errno=True)
207
+ self.libproc = ctypes.CDLL("/usr/lib/libproc.dylib", use_errno=True)
208
+ self.argmax = self._sysctl_int([self.CTL_KERN, self.KERN_ARGMAX])
209
+
210
+ def _sysctl_int(self, mib):
211
+ arr = (ctypes.c_int * len(mib))(*mib)
212
+ out = ctypes.c_int()
213
+ sz = ctypes.c_size_t(ctypes.sizeof(out))
214
+ if self.libc.sysctl(arr, len(mib), ctypes.byref(out), ctypes.byref(sz), None, 0) != 0:
215
+ raise OSError(ctypes.get_errno())
216
+ return out.value
217
+
218
+ def all_pids(self):
219
+ # A failed proc_listpids answers -1, and the slice of the buffer it gave then held no pid: no process at
220
+ # all, where it could not look (WINDOWS-TABLE-CLOSED).
221
+ n = self.libproc.proc_listpids(self.PROC_ALL_PIDS, 0, None, 0)
222
+ if n <= 0:
223
+ raise TableUnreadable(f"proc_listpids answered {n} (errno {ctypes.get_errno()})", "macOS")
224
+ buf = (ctypes.c_int * (n // 4 + 64))()
225
+ n = self.libproc.proc_listpids(self.PROC_ALL_PIDS, 0, buf, ctypes.sizeof(buf))
226
+ pids = [p for p in buf[:max(n, 0) // 4] if p > 0]
227
+ if not pids:
228
+ raise TableUnreadable(f"proc_listpids listed no process (it answered {n})", "macOS")
229
+ return pids
230
+
231
+ def argv(self, pid):
232
+ mib = (ctypes.c_int * 3)(self.CTL_KERN, self.KERN_PROCARGS2, pid)
233
+ buf = ctypes.create_string_buffer(self.argmax)
234
+ sz = ctypes.c_size_t(self.argmax)
235
+ if self.libc.sysctl(mib, 3, buf, ctypes.byref(sz), None, 0) != 0:
236
+ return None
237
+ raw = buf.raw[:sz.value]
238
+ if len(raw) < 4:
239
+ return None
240
+ argc = struct.unpack("i", raw[:4])[0]
241
+ rest = raw[4:]
242
+ if b"\0" not in rest:
243
+ return None
244
+ rest = rest[rest.index(b"\0"):].lstrip(b"\0") # skip the exec path and its padding
245
+ parts = rest.split(b"\0")
246
+ return [p.decode("utf-8", "replace") for p in parts[:max(argc, 0)]]
247
+
248
+ def cwd(self, pid):
249
+ buf = ctypes.create_string_buffer(self.VNODEPATHINFO_SIZE * 2)
250
+ n = self.libproc.proc_pidinfo(pid, self.PROC_PIDVNODEPATHINFO, ctypes.c_uint64(0), buf, ctypes.sizeof(buf))
251
+ if n <= 0:
252
+ return None
253
+ p = buf.raw[self.VNODE_INFO_SIZE:self.VNODE_INFO_SIZE + self.MAXPATHLEN]
254
+ return p.split(b"\0", 1)[0].decode("utf-8", "replace") or None
255
+
256
+ def info(self, pid):
257
+ buf = ctypes.create_string_buffer(self.BSDINFO_SIZE * 2)
258
+ n = self.libproc.proc_pidinfo(pid, self.PROC_PIDTBSDINFO, ctypes.c_uint64(0), buf, ctypes.sizeof(buf))
259
+ if n < self.BSDINFO_SIZE:
260
+ return None
261
+ r = buf.raw
262
+ ppid, = struct.unpack_from("I", r, 16)
263
+ pgid, = struct.unpack_from("I", r, 100)
264
+ tdev, = struct.unpack_from("I", r, 108)
265
+ start, = struct.unpack_from("Q", r, 120)
266
+ comm = r[48:64].split(b"\0", 1)[0].decode("utf-8", "replace")
267
+ return {"ppid": ppid, "pgid": pgid, "tty": None if tdev == self.NODEV else tdev,
268
+ "start": start, "comm": comm}
269
+
270
+ def elapsed(self, pid):
271
+ # `start` is the start time's whole seconds; ps subtracts them from its own clock's.
272
+ info = self.info(pid)
273
+ return None if info is None else max(0, int(time.time()) - info["start"])
274
+
275
+ SZOMB = 5
276
+
277
+ def zombie(self, pid):
278
+ buf = ctypes.create_string_buffer(self.BSDINFO_SIZE * 2)
279
+ n = self.libproc.proc_pidinfo(pid, self.PROC_PIDTBSDINFO, ctypes.c_uint64(0), buf, ctypes.sizeof(buf))
280
+ if n < self.BSDINFO_SIZE:
281
+ return None
282
+ status, = struct.unpack_from("I", buf.raw, 4)
283
+ return status == self.SZOMB
284
+
285
+
286
+ # ---------------------------------------------------------------- Linux (/proc)
287
+ class _Linux:
288
+ def all_pids(self):
289
+ try:
290
+ pids = [int(d) for d in os.listdir("/proc") if d.isdigit()]
291
+ except OSError as exc:
292
+ raise TableUnreadable(f"/proc could not be listed ({exc})", "Linux") from None
293
+ if not pids:
294
+ raise TableUnreadable("/proc lists no process", "Linux") # this one runs (WINDOWS-TABLE-CLOSED)
295
+ return pids
296
+
297
+ def argv(self, pid):
298
+ try:
299
+ raw = open(f"/proc/{pid}/cmdline", "rb").read()
300
+ except OSError:
301
+ return None
302
+ return [p.decode("utf-8", "replace") for p in raw.split(b"\0") if p] or None
303
+
304
+ def cwd(self, pid):
305
+ try:
306
+ return os.readlink(f"/proc/{pid}/cwd")
307
+ except OSError:
308
+ return None
309
+
310
+ def zombie(self, pid):
311
+ try:
312
+ stat = open(f"/proc/{pid}/stat", encoding=UTF8).read()
313
+ except OSError:
314
+ return None
315
+ return stat[stat.rindex(")") + 2:stat.rindex(")") + 3] == "Z"
316
+
317
+ def info(self, pid):
318
+ try:
319
+ stat = open(f"/proc/{pid}/stat", encoding=UTF8).read()
320
+ except OSError:
321
+ return None
322
+ rest = stat[stat.rindex(")") + 2:].split()
323
+ # fields after comm: state ppid pgrp session tty_nr … starttime(22nd overall = index 19 here)
324
+ ppid, pgid, tty = int(rest[1]), int(rest[2]), int(rest[4])
325
+ return {"ppid": ppid, "pgid": pgid, "tty": None if tty == 0 else tty,
326
+ "start": int(rest[19]) if len(rest) > 19 else 0,
327
+ "comm": stat[stat.index("(") + 1:stat.rindex(")")]}
328
+
329
+ def elapsed(self, pid):
330
+ # `start` counts clock ticks since boot; ps takes whole seconds of both, as here.
331
+ info = self.info(pid)
332
+ try:
333
+ with open("/proc/uptime", encoding=UTF8) as fh:
334
+ since_boot = int(float(fh.read().split()[0]))
335
+ except (OSError, ValueError, IndexError):
336
+ return None
337
+ return None if info is None else max(0, since_boot - info["start"] // os.sysconf("SC_CLK_TCK"))
338
+
339
+
340
+ # ---------------------------------------------------------------- Windows (CIM via PowerShell, JSON)
341
+ class _Windows:
342
+ """Win32_Process through PowerShell, as JSON — structured, not parsed text.
343
+
344
+ CommandLine is one string on Windows; it is split with the platform's own
345
+ quoting rules here. The working directory is not exposed by CIM; it is read from
346
+ the process environment block, as psutil reads it (#9), and where that cannot be
347
+ read agent matching falls back to the repository path on the command line.
348
+ """
349
+ _cache = None
350
+ _cache_at = 0.0
351
+ # PowerShell writes what a script outputs to a pipe in the console's code page, so a command line
352
+ # holding a letter outside it - a repository under C:\Users\<a Turkish name>, a prompt in Turkish -
353
+ # arrived as "?" or as bytes that are not UTF-8, and a turn named by its repository's path was not
354
+ # placed. The JSON goes to the standard output handle as UTF-8 bytes, past any code page (#71).
355
+ SNAPSHOT = ("$json = Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,CommandLine,"
356
+ "ExecutablePath,Name,SessionId,CreationDate | ConvertTo-Json -Compress; "
357
+ "$bytes = [System.Text.Encoding]::UTF8.GetBytes([string]$json); "
358
+ "$out = [Console]::OpenStandardOutput(); $out.Write($bytes, 0, $bytes.Length); $out.Flush()")
359
+
360
+ def invalidate(self):
361
+ self._cache = None
362
+ self._cache_at = 0.0
363
+
364
+ def _snapshot(self):
365
+ """{pid: Win32_Process row} for every process, kept two seconds; TableUnreadable when there is none.
366
+
367
+ A PowerShell that was missing, failed, did not answer in time, or printed something that is
368
+ not the table gave an empty snapshot, and every reader took that for no process at all: no
369
+ turn in the tree, no reviewer, no session in use (WINDOWS-TABLE-CLOSED). Only the length of
370
+ an answer that is not JSON is told, since the command lines in it can hold a secret.
371
+ """
372
+ import json as _json
373
+ import time as _time
374
+ if self._cache is not None and _time.time() - self._cache_at < 2.0:
375
+ return self._cache
376
+ query = "PowerShell's Get-CimInstance Win32_Process"
377
+ out = _run(["powershell", "-NoProfile", "-NonInteractive", "-Command", self.SNAPSHOT])
378
+ if not out.strip():
379
+ raise TableUnreadable(getattr(out, "why", None) or f"{query} printed nothing", "Windows")
380
+ try:
381
+ data = _json.loads(out)
382
+ except ValueError:
383
+ raise TableUnreadable(f"{query} printed {len(out)} characters that are not JSON", "Windows") from None
384
+ snap = {}
385
+ for r in data if isinstance(data, list) else [data]:
386
+ try:
387
+ pid = int(r.get("ProcessId"))
388
+ except (AttributeError, TypeError, ValueError):
389
+ continue
390
+ snap[pid] = r
391
+ # A snapshot that lists no process is no reading - this one runs - so it is not kept for the next
392
+ # two seconds' readers; the next one asks again (WINDOWS-LANE-4), and this one is told it could not look.
393
+ if not snap:
394
+ raise TableUnreadable(f"{query} listed no process", "Windows")
395
+ self._cache, self._cache_at = snap, _time.time()
396
+ return snap
397
+
398
+ @staticmethod
399
+ def _split(cmdline):
400
+ # Windows argument splitting: quoted segments keep their spaces.
401
+ import re as _re
402
+ return [t.strip('"') for t in _re.findall(r'"[^"]*"|\S+', cmdline or "")]
403
+
404
+ def all_pids(self):
405
+ return list(self._snapshot())
406
+
407
+ def argv(self, pid):
408
+ r = self._snapshot().get(pid)
409
+ if not r:
410
+ return None
411
+ av = self._split(r.get("CommandLine") or "")
412
+ if not av and r.get("ExecutablePath"):
413
+ av = [r["ExecutablePath"]]
414
+ return av or None
415
+
416
+ def cwd(self, pid):
417
+ """The working directory from the process's environment block, as psutil reads it (#9).
418
+
419
+ CIM does not expose it. OpenProcess with query and read rights, the PEB
420
+ address from NtQueryInformationProcess, then ProcessParameters and its
421
+ CurrentDirectory. Only a 64-bit process is read by a 64-bit interpreter:
422
+ a 32-bit process, one this user may not open, or a read that comes back
423
+ short is None, which every caller handles on the record (#71).
424
+ """
425
+ try:
426
+ return self._environment_cwd(pid)
427
+ except Exception:
428
+ return None
429
+
430
+ @staticmethod
431
+ def _environment_cwd(pid):
432
+ from ctypes import wintypes
433
+ if ctypes.sizeof(ctypes.c_void_p) != 8:
434
+ return None
435
+ kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
436
+ ntdll = ctypes.WinDLL("ntdll")
437
+ kernel32.OpenProcess.restype = wintypes.HANDLE
438
+ kernel32.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
439
+ kernel32.ReadProcessMemory.restype = wintypes.BOOL
440
+ kernel32.ReadProcessMemory.argtypes = [wintypes.HANDLE, ctypes.c_void_p, ctypes.c_void_p, ctypes.c_size_t,
441
+ ctypes.POINTER(ctypes.c_size_t)]
442
+ kernel32.IsWow64Process.restype = wintypes.BOOL
443
+ kernel32.IsWow64Process.argtypes = [wintypes.HANDLE, ctypes.POINTER(wintypes.BOOL)]
444
+ kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
445
+ ntdll.NtQueryInformationProcess.restype = ctypes.c_long
446
+ ntdll.NtQueryInformationProcess.argtypes = [wintypes.HANDLE, ctypes.c_ulong, ctypes.c_void_p, ctypes.c_ulong,
447
+ ctypes.POINTER(ctypes.c_ulong)]
448
+ PROCESS_QUERY_INFORMATION, PROCESS_VM_READ = 0x0400, 0x0010
449
+ handle = kernel32.OpenProcess(PROCESS_QUERY_INFORMATION | PROCESS_VM_READ, False, pid)
450
+ if not handle:
451
+ return None
452
+ try:
453
+ wow64 = wintypes.BOOL()
454
+ if not kernel32.IsWow64Process(handle, ctypes.byref(wow64)) or wow64.value:
455
+ return None
456
+ basic = (ctypes.c_void_p * 6)() # PROCESS_BASIC_INFORMATION; PebBaseAddress is the second
457
+ returned = ctypes.c_ulong(0)
458
+ if ntdll.NtQueryInformationProcess(handle, 0, basic, ctypes.sizeof(basic), ctypes.byref(returned)) != 0:
459
+ return None
460
+
461
+ def read(address, length):
462
+ buffer = ctypes.create_string_buffer(length)
463
+ got = ctypes.c_size_t(0)
464
+ if not kernel32.ReadProcessMemory(handle, address, buffer, length, ctypes.byref(got)) \
465
+ or got.value != length:
466
+ raise OSError("short read of another process's memory")
467
+ return buffer.raw
468
+
469
+ peb = basic[1]
470
+ if not peb:
471
+ return None
472
+ parameters, = struct.unpack_from("<Q", read(peb + 0x20, 8)) # PEB.ProcessParameters
473
+ length, _, text = struct.unpack_from("<HH4xQ", read(parameters + 0x38, 16)) # CurrentDirectory.DosPath
474
+ if not length or not text:
475
+ return None
476
+ path = read(text, length).decode("utf-16-le")
477
+ return path[:-1] if len(path) > 3 and path.endswith("\\") else path
478
+ finally:
479
+ kernel32.CloseHandle(handle)
480
+
481
+ @staticmethod
482
+ def alive(pid, kernel32=None, last_error=None):
483
+ """Whether `pid` runs, asked of the process itself: opened and waited on for no time (WINDOWS-PID-ALIVE).
484
+
485
+ A wait that times out is a running process, and a signalled one has exited, its pid held only by a
486
+ handle someone keeps. Access is denied only to a process that exists, one this user may not open;
487
+ a pid no process has is an invalid parameter. Anything else is None. `kernel32` and `last_error`
488
+ stand in for the platform's where there is none.
489
+ """
490
+ if kernel32 is None:
491
+ from ctypes import wintypes
492
+ kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
493
+ kernel32.OpenProcess.restype = wintypes.HANDLE
494
+ kernel32.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
495
+ kernel32.WaitForSingleObject.restype = wintypes.DWORD
496
+ kernel32.WaitForSingleObject.argtypes = [wintypes.HANDLE, wintypes.DWORD]
497
+ kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
498
+ last_error = ctypes.get_last_error
499
+ SYNCHRONIZE, PROCESS_QUERY_LIMITED_INFORMATION = 0x00100000, 0x1000
500
+ handle = kernel32.OpenProcess(SYNCHRONIZE | PROCESS_QUERY_LIMITED_INFORMATION, False, pid)
501
+ if not handle:
502
+ error = last_error()
503
+ return True if error == 5 else False if error == 87 else None # ACCESS_DENIED, INVALID_PARAMETER
504
+ try:
505
+ state = kernel32.WaitForSingleObject(handle, 0)
506
+ return True if state == 0x102 else False if state == 0 else None # WAIT_TIMEOUT, WAIT_OBJECT_0
507
+ finally:
508
+ kernel32.CloseHandle(handle)
509
+
510
+ def ppid(self, pid):
511
+ """The parent pid from a Toolhelp snapshot of the process list (ANCESTOR-WINDOWS).
512
+
513
+ The CIM snapshot the rest of this backend reads is a PowerShell run, a second or more, and it
514
+ answers nothing where PowerShell does not run; a parent read from it for `polyctl lock -- polyctl verify`
515
+ was then unknown, and the verify waited out the lock its own parent held. Toolhelp is the
516
+ process list the kernel keeps, read in-process. None when it cannot be read or holds no `pid`.
517
+ """
518
+ from ctypes import wintypes
519
+
520
+ class Entry(ctypes.Structure): # PROCESSENTRY32W
521
+ _fields_ = [("dwSize", wintypes.DWORD), ("cntUsage", wintypes.DWORD),
522
+ ("th32ProcessID", wintypes.DWORD), ("th32DefaultHeapID", ctypes.c_size_t),
523
+ ("th32ModuleID", wintypes.DWORD), ("cntThreads", wintypes.DWORD),
524
+ ("th32ParentProcessID", wintypes.DWORD), ("pcPriClassBase", wintypes.LONG),
525
+ ("dwFlags", wintypes.DWORD), ("szExeFile", wintypes.WCHAR * 260)]
526
+
527
+ kernel32 = ctypes.WinDLL("kernel32")
528
+ kernel32.CreateToolhelp32Snapshot.restype = wintypes.HANDLE
529
+ kernel32.CreateToolhelp32Snapshot.argtypes = [wintypes.DWORD, wintypes.DWORD]
530
+ for name in ("Process32FirstW", "Process32NextW"):
531
+ getattr(kernel32, name).restype = wintypes.BOOL
532
+ getattr(kernel32, name).argtypes = [wintypes.HANDLE, ctypes.POINTER(Entry)]
533
+ kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
534
+ snapshot = kernel32.CreateToolhelp32Snapshot(0x2, 0) # TH32CS_SNAPPROCESS
535
+ if snapshot is None or snapshot == ctypes.c_void_p(-1).value: # INVALID_HANDLE_VALUE
536
+ return None
537
+ try:
538
+ entry = Entry()
539
+ entry.dwSize = ctypes.sizeof(Entry)
540
+ found = kernel32.Process32FirstW(snapshot, ctypes.byref(entry))
541
+ while found:
542
+ if entry.th32ProcessID == pid:
543
+ return int(entry.th32ParentProcessID)
544
+ found = kernel32.Process32NextW(snapshot, ctypes.byref(entry))
545
+ return None
546
+ finally:
547
+ kernel32.CloseHandle(snapshot)
548
+
549
+ def info(self, pid):
550
+ r = self._snapshot().get(pid)
551
+ if not r:
552
+ return None
553
+ ppid = int(r.get("ParentProcessId") or 0)
554
+ return {"ppid": ppid, "pgid": pid, "tty": None if int(r.get("SessionId") or 0) == 0 else int(r["SessionId"]),
555
+ "start": r.get("CreationDate") or 0, "comm": r.get("Name") or ""}
556
+
557
+ def elapsed(self, pid):
558
+ started = _cim_epoch((self._snapshot().get(pid) or {}).get("CreationDate"))
559
+ return None if started is None else max(0, int(time.time() - started))
560
+
561
+
562
+ # ---------------------------------------------------------------- Windows job objects (WIN-JOB)
563
+ JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE = 0x2000
564
+ CREATE_SUSPENDED = 0x00000004
565
+ EXTENDED_STARTUPINFO_PRESENT = 0x00080000
566
+ CREATE_UNICODE_ENVIRONMENT = 0x00000400
567
+ PROC_THREAD_ATTRIBUTE_HANDLE_LIST = 0x00020002
568
+ PROC_THREAD_ATTRIBUTE_JOB_LIST = 0x0002000D
569
+ _JOB_OBJECT_EXTENDED_LIMIT_INFORMATION = 9
570
+ _PROCESS_SET_QUOTA, _PROCESS_TERMINATE = 0x0100, 0x0001
571
+ _TH32CS_SNAPTHREAD = 0x00000004
572
+ _THREAD_SUSPEND_RESUME = 0x0002
573
+ _READ_CONTROL = 0x00020000
574
+ _SE_DACL_PRESENT = 0x0004
575
+ _ACL_REVISION = 2
576
+ _SPAWN_OS_ERRORS = (2, 3, 193, 267)
577
+ _ACTIVE_JOB = None
578
+
579
+
580
+ class _JobBasicLimitInformation(ctypes.Structure):
581
+ """JOBOBJECT_BASIC_LIMIT_INFORMATION, as the Windows headers lay it out."""
582
+ _fields_ = [
583
+ ("PerProcessUserTimeLimit", ctypes.c_int64),
584
+ ("PerJobUserTimeLimit", ctypes.c_int64),
585
+ ("LimitFlags", ctypes.c_uint32),
586
+ ("MinimumWorkingSetSize", ctypes.c_size_t),
587
+ ("MaximumWorkingSetSize", ctypes.c_size_t),
588
+ ("ActiveProcessLimit", ctypes.c_uint32),
589
+ ("Affinity", ctypes.c_size_t),
590
+ ("PriorityClass", ctypes.c_uint32),
591
+ ("SchedulingClass", ctypes.c_uint32),
592
+ ]
593
+
594
+
595
+ class _IoCounters(ctypes.Structure):
596
+ """IO_COUNTERS, six unsigned 64-bit counts."""
597
+ _fields_ = [(name, ctypes.c_uint64) for name in
598
+ ("ReadOperationCount", "WriteOperationCount", "OtherOperationCount",
599
+ "ReadTransferCount", "WriteTransferCount", "OtherTransferCount")]
600
+
601
+
602
+ class _JobExtendedLimitInformation(ctypes.Structure):
603
+ """JOBOBJECT_EXTENDED_LIMIT_INFORMATION: 144 bytes on 64-bit Windows, 112 on 32-bit."""
604
+ _fields_ = [
605
+ ("BasicLimitInformation", _JobBasicLimitInformation),
606
+ ("IoInfo", _IoCounters),
607
+ ("ProcessMemoryLimit", ctypes.c_size_t),
608
+ ("JobMemoryLimit", ctypes.c_size_t),
609
+ ("PeakProcessMemoryUsed", ctypes.c_size_t),
610
+ ("PeakJobMemoryUsed", ctypes.c_size_t),
611
+ ]
612
+
613
+
614
+ class _ThreadEntry32(ctypes.Structure):
615
+ """THREADENTRY32, as Windows' tlhelp32.h lays it out."""
616
+ _fields_ = [
617
+ ("dwSize", ctypes.c_uint32),
618
+ ("cntUsage", ctypes.c_uint32),
619
+ ("th32ThreadID", ctypes.c_uint32),
620
+ ("th32OwnerProcessID", ctypes.c_uint32),
621
+ ("tpBasePri", ctypes.c_int32),
622
+ ("tpDeltaPri", ctypes.c_int32),
623
+ ("dwFlags", ctypes.c_uint32),
624
+ ]
625
+
626
+
627
+ class _OwnerRightsReadControlAcl(ctypes.Structure):
628
+ """An ACL with one ACCESS_ALLOWED_ACE granting OWNER_RIGHTS (S-1-3-4) READ_CONTROL only.
629
+
630
+ A thread started with NULL lpThreadAttributes receives the creator token's default DACL, which
631
+ grants THREAD_SUSPEND_RESUME to any same-user process. With an explicit OWNER_RIGHTS ACE for
632
+ READ_CONTROL alone, OpenThread for THREAD_SUSPEND_RESUME or WRITE_DAC is denied while the direct
633
+ hThread handle from CreateProcessW keeps THREAD_ALL_ACCESS (WIN-JOB).
634
+ """
635
+ _fields_ = [
636
+ ("AclRevision", ctypes.c_uint8),
637
+ ("Sbz1", ctypes.c_uint8),
638
+ ("AclSize", ctypes.c_uint16),
639
+ ("AceCount", ctypes.c_uint16),
640
+ ("Sbz2", ctypes.c_uint16),
641
+ ("AceType", ctypes.c_uint8),
642
+ ("AceFlags", ctypes.c_uint8),
643
+ ("AceSize", ctypes.c_uint16),
644
+ ("Mask", ctypes.c_uint32),
645
+ ("SidRevision", ctypes.c_uint8),
646
+ ("SubAuthorityCount", ctypes.c_uint8),
647
+ ("IdentifierAuthority", ctypes.c_uint8 * 6),
648
+ ("SubAuthority", ctypes.c_uint32),
649
+ ]
650
+
651
+
652
+ class _SecurityDescriptor(ctypes.Structure):
653
+ """Absolute SECURITY_DESCRIPTOR (winnt.h) with an explicit DACL."""
654
+ _fields_ = [
655
+ ("Revision", ctypes.c_uint8),
656
+ ("Sbz1", ctypes.c_uint8),
657
+ ("Control", ctypes.c_uint16),
658
+ ("Owner", ctypes.c_void_p),
659
+ ("Group", ctypes.c_void_p),
660
+ ("Sacl", ctypes.c_void_p),
661
+ ("Dacl", ctypes.c_void_p),
662
+ ]
663
+
664
+
665
+ class _SecurityAttributes(ctypes.Structure):
666
+ """SECURITY_ATTRIBUTES (wtypesbase.h)."""
667
+ _fields_ = [
668
+ ("nLength", ctypes.c_uint32),
669
+ ("lpSecurityDescriptor", ctypes.c_void_p),
670
+ ("bInheritHandle", ctypes.c_int32),
671
+ ]
672
+
673
+
674
+ class _StartupInfoW(ctypes.Structure):
675
+ """STARTUPINFOW (processthreadsapi.h): 104 bytes on 64-bit Windows, 68 on 32-bit."""
676
+ _fields_ = [
677
+ ("cb", ctypes.c_uint32),
678
+ ("lpReserved", ctypes.c_void_p),
679
+ ("lpDesktop", ctypes.c_void_p),
680
+ ("lpTitle", ctypes.c_void_p),
681
+ ("dwX", ctypes.c_uint32),
682
+ ("dwY", ctypes.c_uint32),
683
+ ("dwXSize", ctypes.c_uint32),
684
+ ("dwYSize", ctypes.c_uint32),
685
+ ("dwXCountChars", ctypes.c_uint32),
686
+ ("dwYCountChars", ctypes.c_uint32),
687
+ ("dwFillAttribute", ctypes.c_uint32),
688
+ ("dwFlags", ctypes.c_uint32),
689
+ ("wShowWindow", ctypes.c_uint16),
690
+ ("cbReserved2", ctypes.c_uint16),
691
+ ("lpReserved2", ctypes.c_void_p),
692
+ ("hStdInput", ctypes.c_void_p),
693
+ ("hStdOutput", ctypes.c_void_p),
694
+ ("hStdError", ctypes.c_void_p),
695
+ ]
696
+
697
+
698
+ class _StartupInfoExW(ctypes.Structure):
699
+ """STARTUPINFOEXW (winbase.h): STARTUPINFOW followed by LPPROC_THREAD_ATTRIBUTE_LIST."""
700
+ _fields_ = [
701
+ ("StartupInfo", _StartupInfoW),
702
+ ("lpAttributeList", ctypes.c_void_p),
703
+ ]
704
+
705
+
706
+ class _ProcessInformation(ctypes.Structure):
707
+ """PROCESS_INFORMATION (processthreadsapi.h)."""
708
+ _fields_ = [
709
+ ("hProcess", ctypes.c_void_p),
710
+ ("hThread", ctypes.c_void_p),
711
+ ("dwProcessId", ctypes.c_uint32),
712
+ ("dwThreadId", ctypes.c_uint32),
713
+ ]
714
+
715
+
716
+ def _locked_thread_acl():
717
+ return _OwnerRightsReadControlAcl(
718
+ AclRevision=_ACL_REVISION, AclSize=ctypes.sizeof(_OwnerRightsReadControlAcl), AceCount=1,
719
+ AceType=0, AceSize=20, Mask=_READ_CONTROL,
720
+ SidRevision=1, SubAuthorityCount=1, IdentifierAuthority=(0, 0, 0, 0, 0, 3), SubAuthority=4,
721
+ )
722
+
723
+
724
+ def _windows_error(call, code):
725
+ """What a Windows call refused with, in a message a person reads: the call, the code, a common name."""
726
+ known = {5: "access denied", 6: "invalid handle", 8: "not enough memory", 87: "invalid parameter"}
727
+ return f"{call} failed (error {code}{', ' + known[code] if code in known else ''})"
728
+
729
+
730
+ def _job_kernel32():
731
+ """kernel32 with the job, creation and thread-resume calls' restype and argtypes set."""
732
+ from ctypes import wintypes
733
+ kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
734
+ kernel32.CreateJobObjectW.restype = wintypes.HANDLE
735
+ kernel32.CreateJobObjectW.argtypes = [ctypes.c_void_p, wintypes.LPCWSTR]
736
+ kernel32.SetInformationJobObject.restype = wintypes.BOOL
737
+ kernel32.SetInformationJobObject.argtypes = [wintypes.HANDLE, ctypes.c_int, ctypes.c_void_p, wintypes.DWORD]
738
+ kernel32.InitializeProcThreadAttributeList.restype = wintypes.BOOL
739
+ kernel32.InitializeProcThreadAttributeList.argtypes = [
740
+ ctypes.c_void_p, wintypes.DWORD, wintypes.DWORD, ctypes.POINTER(ctypes.c_size_t)]
741
+ kernel32.UpdateProcThreadAttribute.restype = wintypes.BOOL
742
+ kernel32.UpdateProcThreadAttribute.argtypes = [
743
+ ctypes.c_void_p, wintypes.DWORD, ctypes.c_size_t, ctypes.c_void_p,
744
+ ctypes.c_size_t, ctypes.c_void_p, ctypes.c_void_p]
745
+ kernel32.DeleteProcThreadAttributeList.restype = None
746
+ kernel32.DeleteProcThreadAttributeList.argtypes = [ctypes.c_void_p]
747
+ kernel32.CreateProcessW.restype = wintypes.BOOL
748
+ kernel32.CreateProcessW.argtypes = [
749
+ wintypes.LPCWSTR, wintypes.LPWSTR, ctypes.c_void_p, ctypes.c_void_p,
750
+ wintypes.BOOL, wintypes.DWORD, ctypes.c_void_p, wintypes.LPCWSTR,
751
+ ctypes.c_void_p, ctypes.POINTER(_ProcessInformation)]
752
+ kernel32.AssignProcessToJobObject.restype = wintypes.BOOL
753
+ kernel32.AssignProcessToJobObject.argtypes = [wintypes.HANDLE, wintypes.HANDLE]
754
+ kernel32.OpenProcess.restype = wintypes.HANDLE
755
+ kernel32.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
756
+ kernel32.CreateToolhelp32Snapshot.restype = wintypes.HANDLE
757
+ kernel32.CreateToolhelp32Snapshot.argtypes = [wintypes.DWORD, wintypes.DWORD]
758
+ for name in ("Thread32First", "Thread32Next"):
759
+ getattr(kernel32, name).restype = wintypes.BOOL
760
+ getattr(kernel32, name).argtypes = [wintypes.HANDLE, ctypes.POINTER(_ThreadEntry32)]
761
+ kernel32.OpenThread.restype = wintypes.HANDLE
762
+ kernel32.OpenThread.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
763
+ kernel32.ResumeThread.restype = wintypes.DWORD
764
+ kernel32.ResumeThread.argtypes = [wintypes.HANDLE]
765
+ kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
766
+ return kernel32
767
+
768
+
769
+ class JobObject:
770
+ """A Windows job holding one reviewer's process tree, ended when its handle closes (WIN-JOB).
771
+
772
+ Windows has no process group for `_stop_reviewer_leftovers` to stop, so what a reviewer started
773
+ and left behind ran on. A job with JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE ends every process assigned
774
+ to it - and every process they start - when the last handle closes. When `_winapi.CreateProcess`
775
+ is hooked through `creating`, the child is placed in the job at `CreateProcessW` via
776
+ `PROC_THREAD_ATTRIBUTE_JOB_LIST` and its suspended primary thread is given an `OWNER_RIGHTS`
777
+ `READ_CONTROL`-only DACL so no concurrent same-user process can resume it; `resume` checks that
778
+ `ResumeThread` found a suspend count of 1; `close` may be called more than once.
779
+ """
780
+
781
+ def __init__(self, kernel32=None, last_error=None):
782
+ self._kernel32 = kernel32 if kernel32 is not None else _job_kernel32()
783
+ self._last_error = last_error if last_error is not None else getattr(ctypes, "get_last_error", lambda: 0)
784
+ self._held = set()
785
+ self._threads = {}
786
+ self._deferred_threads = set()
787
+ self.why = None
788
+ self.handle = self._kernel32.CreateJobObjectW(None, None)
789
+ if not self.handle:
790
+ self.why = _windows_error("CreateJobObjectW", self._last_error())
791
+ self.handle = None
792
+ return
793
+ limits = _JobExtendedLimitInformation()
794
+ limits.BasicLimitInformation.LimitFlags = JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE
795
+ if not self._kernel32.SetInformationJobObject(self.handle, _JOB_OBJECT_EXTENDED_LIMIT_INFORMATION,
796
+ ctypes.byref(limits), ctypes.sizeof(limits)):
797
+ self.why = _windows_error("SetInformationJobObject", self._last_error())
798
+ self.close()
799
+
800
+ def _create_process(self, executable, args, proc_attrs, thread_attrs,
801
+ inherit_handles, creationflags, env, cwd, startupinfo):
802
+ """Start `args` via `CreateProcessW` already in this job and with a locked thread DACL (WIN-JOB)."""
803
+ if self.why:
804
+ raise OSError(self.why)
805
+ if self.handle is None:
806
+ self.why = "the job is closed"
807
+ raise OSError(self.why)
808
+ attr_dict = getattr(startupinfo, "lpAttributeList", None) or {}
809
+ handle_list = [int(h) for h in (attr_dict.get("handle_list") or [])]
810
+ attr_count = 2 if handle_list else 1
811
+ attr_size = ctypes.c_size_t(0)
812
+ self._kernel32.InitializeProcThreadAttributeList(None, attr_count, 0, ctypes.byref(attr_size))
813
+ if not attr_size.value:
814
+ self.why = _windows_error("InitializeProcThreadAttributeList", self._last_error())
815
+ raise OSError(self.why)
816
+ attr_buf = ctypes.create_string_buffer(attr_size.value)
817
+ if not self._kernel32.InitializeProcThreadAttributeList(attr_buf, attr_count, 0, ctypes.byref(attr_size)):
818
+ self.why = _windows_error("InitializeProcThreadAttributeList", self._last_error())
819
+ raise OSError(self.why)
820
+ try:
821
+ job_list = (ctypes.c_void_p * 1)(self.handle)
822
+ if not self._kernel32.UpdateProcThreadAttribute(
823
+ attr_buf, 0, PROC_THREAD_ATTRIBUTE_JOB_LIST,
824
+ ctypes.byref(job_list), ctypes.sizeof(job_list), None, None,
825
+ ):
826
+ self.why = _windows_error("UpdateProcThreadAttribute", self._last_error())
827
+ raise OSError(self.why)
828
+ handles = None
829
+ if handle_list:
830
+ handles = (ctypes.c_void_p * len(handle_list))(*handle_list)
831
+ if not self._kernel32.UpdateProcThreadAttribute(
832
+ attr_buf, 0, PROC_THREAD_ATTRIBUTE_HANDLE_LIST,
833
+ ctypes.byref(handles), ctypes.sizeof(handles), None, None,
834
+ ):
835
+ self.why = _windows_error("UpdateProcThreadAttribute", self._last_error())
836
+ raise OSError(self.why)
837
+ si_ex = _StartupInfoExW()
838
+ si_ex.StartupInfo.cb = ctypes.sizeof(_StartupInfoExW)
839
+ if startupinfo is not None:
840
+ si_ex.StartupInfo.dwFlags = int(getattr(startupinfo, "dwFlags", 0) or 0)
841
+ si_ex.StartupInfo.wShowWindow = int(getattr(startupinfo, "wShowWindow", 0) or 0)
842
+ si_ex.StartupInfo.hStdInput = int(getattr(startupinfo, "hStdInput", 0) or 0)
843
+ si_ex.StartupInfo.hStdOutput = int(getattr(startupinfo, "hStdOutput", 0) or 0)
844
+ si_ex.StartupInfo.hStdError = int(getattr(startupinfo, "hStdError", 0) or 0)
845
+ si_ex.lpAttributeList = ctypes.cast(attr_buf, ctypes.c_void_p).value
846
+ acl = _locked_thread_acl()
847
+ sd = _SecurityDescriptor(Revision=1, Control=_SE_DACL_PRESENT, Dacl=ctypes.addressof(acl))
848
+ thread_sa = _SecurityAttributes(
849
+ nLength=ctypes.sizeof(_SecurityAttributes),
850
+ lpSecurityDescriptor=ctypes.addressof(sd),
851
+ bInheritHandle=0,
852
+ )
853
+ flags = int(creationflags) | CREATE_SUSPENDED | EXTENDED_STARTUPINFO_PRESENT
854
+ env_buf = None
855
+ if env is not None:
856
+ items = sorted(((os.fsdecode(k), os.fsdecode(v)) for k, v in env.items()),
857
+ key=lambda item: item[0].upper())
858
+ env_text = "".join(f"{k}={v}\0" for k, v in items) + "\0"
859
+ env_buf = ctypes.create_unicode_buffer(env_text)
860
+ flags |= CREATE_UNICODE_ENVIRONMENT
861
+ cmd_buf = ctypes.create_unicode_buffer(args) if args is not None else None
862
+ pi = _ProcessInformation()
863
+ if not self._kernel32.CreateProcessW(
864
+ executable, cmd_buf, None, ctypes.byref(thread_sa),
865
+ bool(inherit_handles), flags,
866
+ ctypes.cast(env_buf, ctypes.c_void_p) if env_buf is not None else None,
867
+ cwd, ctypes.byref(si_ex), ctypes.byref(pi),
868
+ ):
869
+ code = self._last_error()
870
+ msg = _windows_error("CreateProcessW", code)
871
+ if code in (2, 3):
872
+ raise FileNotFoundError(2, msg)
873
+ if code in _SPAWN_OS_ERRORS:
874
+ raise OSError(code, msg)
875
+ self.why = msg
876
+ raise OSError(self.why)
877
+ pid, ht = int(pi.dwProcessId), int(pi.hThread)
878
+ self._held.add(pid)
879
+ self._threads[pid] = ht
880
+ self._deferred_threads.add(ht)
881
+ return int(pi.hProcess), ht, pid, int(pi.dwThreadId)
882
+ finally:
883
+ self._kernel32.DeleteProcThreadAttributeList(attr_buf)
884
+
885
+ @contextlib.contextmanager
886
+ def creating(self, winapi=None):
887
+ """Hook `_winapi.CreateProcess` so `Popen` puts the child in this job at creation (WIN-JOB)."""
888
+ if winapi is None:
889
+ winapi = getattr(subprocess, "_winapi", None)
890
+ if winapi is None or self.why or self.handle is None:
891
+ yield self
892
+ return
893
+ orig_create = winapi.CreateProcess
894
+ orig_close = getattr(winapi, "CloseHandle", None)
895
+
896
+ def close_handle(handle):
897
+ if int(handle) in self._deferred_threads:
898
+ self._deferred_threads.discard(int(handle))
899
+ return None
900
+ return orig_close(handle)
901
+
902
+ winapi.CreateProcess = self._create_process
903
+ if orig_close is not None:
904
+ winapi.CloseHandle = close_handle
905
+ try:
906
+ yield self
907
+ finally:
908
+ winapi.CreateProcess = orig_create
909
+ if orig_close is not None:
910
+ winapi.CloseHandle = orig_close
911
+
912
+ def hold(self, pid):
913
+ """Assign `pid` to the job; None when it is held, or the platform's reason."""
914
+ if self.why:
915
+ return self.why
916
+ if self.handle is None:
917
+ return "the job is closed"
918
+ if int(pid) in self._held:
919
+ return None
920
+ process = self._kernel32.OpenProcess(_PROCESS_SET_QUOTA | _PROCESS_TERMINATE, False, int(pid))
921
+ if not process:
922
+ return _windows_error(f"OpenProcess for {pid}", self._last_error())
923
+ try:
924
+ if not self._kernel32.AssignProcessToJobObject(self.handle, process):
925
+ return _windows_error(f"AssignProcessToJobObject for {pid}", self._last_error())
926
+ finally:
927
+ self._kernel32.CloseHandle(process)
928
+ self._held.add(int(pid))
929
+ return None
930
+
931
+ def _thread_id(self, pid):
932
+ """The one primary thread id of `pid` from a Toolhelp thread snapshot, or (None, why)."""
933
+ snapshot = self._kernel32.CreateToolhelp32Snapshot(_TH32CS_SNAPTHREAD, 0)
934
+ if not snapshot or snapshot == ctypes.c_void_p(-1).value:
935
+ return None, _windows_error(f"CreateToolhelp32Snapshot for {pid}", self._last_error())
936
+ try:
937
+ entry = _ThreadEntry32()
938
+ entry.dwSize = ctypes.sizeof(_ThreadEntry32)
939
+ tids = []
940
+ found = self._kernel32.Thread32First(snapshot, ctypes.byref(entry))
941
+ while found:
942
+ if entry.th32OwnerProcessID == int(pid):
943
+ tids.append(int(entry.th32ThreadID))
944
+ found = self._kernel32.Thread32Next(snapshot, ctypes.byref(entry))
945
+ if not tids:
946
+ return None, f"no thread found for {pid}"
947
+ if len(tids) > 1:
948
+ return None, f"process {pid} already has {len(tids)} threads before resume"
949
+ return tids[0], None
950
+ finally:
951
+ self._kernel32.CloseHandle(snapshot)
952
+
953
+ def resume(self, pid):
954
+ """Resume `pid`'s primary thread after `CREATE_SUSPENDED`, once `hold` put it in the job (WIN-JOB)."""
955
+ if self.why:
956
+ return self.why
957
+ if self.handle is None:
958
+ return "the job is closed"
959
+ pid = int(pid)
960
+ if pid not in self._held:
961
+ return f"process {pid} is not in the job"
962
+ thread = self._threads.pop(pid, None)
963
+ if thread is not None:
964
+ self._deferred_threads.discard(thread)
965
+ else:
966
+ tid, why = self._thread_id(pid)
967
+ if why:
968
+ return why
969
+ thread = self._kernel32.OpenThread(_THREAD_SUSPEND_RESUME, False, tid)
970
+ if not thread:
971
+ return _windows_error(f"OpenThread for {pid}", self._last_error())
972
+ try:
973
+ previous = self._kernel32.ResumeThread(thread)
974
+ if previous == 0xFFFFFFFF:
975
+ return _windows_error(f"ResumeThread for {pid}", self._last_error())
976
+ if previous != 1:
977
+ return f"ResumeThread for {pid} found suspend count {previous}, expected 1"
978
+ finally:
979
+ self._kernel32.CloseHandle(thread)
980
+ return None
981
+
982
+ def close(self):
983
+ """Close the job's handle: whatever of its tree still runs ends (KILL_ON_JOB_CLOSE)."""
984
+ while self._threads:
985
+ _, thread = self._threads.popitem()
986
+ self._deferred_threads.discard(thread)
987
+ self._kernel32.CloseHandle(thread)
988
+ if self.handle is not None:
989
+ self._kernel32.CloseHandle(self.handle)
990
+ self.handle = None
991
+
992
+
993
+ # ---------------------------------------------------------------- tool fallbacks (ps, lsof)
994
+ class _Shell:
995
+ def all_pids(self):
996
+ out = _run(["ps", "-eo", "pid="])
997
+ pids = [int(x) for x in out.split() if x.isdigit()]
998
+ if not pids:
999
+ # A ps that could not run listed no process, which read as none running (WINDOWS-TABLE-CLOSED).
1000
+ raise TableUnreadable(getattr(out, "why", None) or "ps listed no process")
1001
+ return pids
1002
+
1003
+ def argv(self, pid):
1004
+ out = _run(["ps", "-o", "args=", "-p", str(pid)]).strip()
1005
+ return out.split() if out else None # lossy: spaces in paths split
1006
+
1007
+ def cwd(self, pid):
1008
+ for line in _run(["lsof", "-w", "-n", "-P", "-a", "-d", "cwd", "-Fn", "-p", str(pid)]).split("\n"):
1009
+ if line.startswith("n"):
1010
+ return line[1:]
1011
+ return None
1012
+
1013
+ def info(self, pid):
1014
+ out = _run(["ps", "-o", "ppid=,pgid=,tty=,lstart=,comm=", "-p", str(pid)]).strip().split(None, 3)
1015
+ if len(out) < 3:
1016
+ return None
1017
+ return {"ppid": int(out[0]), "pgid": int(out[1]), "tty": None if out[2] in ("??", "?", "-") else out[2],
1018
+ "start": 0, "comm": out[3] if len(out) > 3 else ""}
1019
+
1020
+ def elapsed(self, pid):
1021
+ return _clock_seconds(_run(["ps", "-o", "etime=", "-p", str(pid)]))
1022
+
1023
+
1024
+ def _backend():
1025
+ global _NATIVE
1026
+ if _NATIVE is not None:
1027
+ return _NATIVE
1028
+ if sys.platform == "win32":
1029
+ # Windows has no ps or lsof to fall back on, and the ps of Git for Windows numbers its own
1030
+ # processes: its backend stays, whatever its first reading gave. That reading is a PowerShell
1031
+ # run, and one taken while a test stood in for subprocess failed, so every process read after it
1032
+ # in that suite went unread (WINDOWS-LANE-4).
1033
+ _NATIVE = _Windows()
1034
+ return _NATIVE
1035
+ cand = None
1036
+ try:
1037
+ if sys.platform == "darwin":
1038
+ cand = _Darwin()
1039
+ elif sys.platform.startswith("linux") and os.path.isdir("/proc"):
1040
+ cand = _Linux()
1041
+ # Self-check against the one process we know everything about: this one.
1042
+ if cand is not None:
1043
+ me = os.getpid()
1044
+ info = cand.info(me) or {}
1045
+ here = cand.cwd(me)
1046
+ ok = info.get("ppid") == os.getppid() and bool(cand.argv(me)) and \
1047
+ (here is None or os.path.normcase(os.path.normpath(here))
1048
+ == os.path.normcase(os.path.normpath(os.getcwd())))
1049
+ if not ok:
1050
+ cand = None
1051
+ except Exception:
1052
+ cand = None
1053
+ _NATIVE = cand or _Shell()
1054
+ return _NATIVE
1055
+
1056
+
1057
+ def refresh():
1058
+ """Invalidate a cached process snapshot before observing a just-spawned pid."""
1059
+ invalidate = getattr(_backend(), "invalidate", None)
1060
+ if invalidate:
1061
+ invalidate()
1062
+
1063
+
1064
+ def native():
1065
+ """True when the platform API answers (not the ps and lsof fallback)."""
1066
+ return not isinstance(_backend(), _Shell)
1067
+
1068
+
1069
+ def all_pids():
1070
+ return _backend().all_pids()
1071
+
1072
+
1073
+ def argv(pid):
1074
+ return _backend().argv(pid)
1075
+
1076
+
1077
+ def cwd(pid):
1078
+ return _backend().cwd(pid)
1079
+
1080
+
1081
+ def zombie(pid):
1082
+ """Has this process exited and only waits to be reaped? It holds a pid and no work.
1083
+
1084
+ A container whose first process never reaps, or a parent that has not yet waited,
1085
+ leaves one behind, and `kill(pid, 0)` still succeeds on it. Windows has none.
1086
+ """
1087
+ if os.name == "nt":
1088
+ return False
1089
+ probe = getattr(_backend(), "zombie", None)
1090
+ try:
1091
+ answer = probe(pid) if probe else None
1092
+ except Exception:
1093
+ answer = None
1094
+ if answer is None:
1095
+ answer = _run(["ps", "-o", "stat=", "-p", str(int(pid))]).strip().startswith("Z")
1096
+ return answer
1097
+
1098
+
1099
+ def info(pid):
1100
+ return _backend().info(pid)
1101
+
1102
+
1103
+ def alive(pid):
1104
+ """Whether process `pid` runs, as Windows answers for the process itself; None where it does not answer.
1105
+
1106
+ Only Windows asks here (WINDOWS-PID-ALIVE): signal 0 is no probe there, and the snapshot its backend
1107
+ reads is kept two seconds, so a process started inside them was not in it and read as gone. None
1108
+ elsewhere, where `kill(pid, 0)` asks the process.
1109
+ """
1110
+ if sys.platform != "win32":
1111
+ return None
1112
+ try:
1113
+ pid = int(pid)
1114
+ return _Windows.alive(pid) if pid > 0 else False
1115
+ except Exception:
1116
+ return None
1117
+
1118
+
1119
+ @contextlib.contextmanager
1120
+ def creating_in_job(enabled=True, kernel32=None, last_error=None, winapi=None):
1121
+ """Create the Windows job before `Popen` and hook `_winapi.CreateProcess` so the child starts inside it (WIN-JOB)."""
1122
+ global _ACTIVE_JOB
1123
+ if not enabled or sys.platform != "win32":
1124
+ yield None
1125
+ return
1126
+ job = JobObject(kernel32, last_error)
1127
+ previous = _ACTIVE_JOB
1128
+ _ACTIVE_JOB = job
1129
+ try:
1130
+ with job.creating(winapi=winapi):
1131
+ yield job
1132
+ finally:
1133
+ _ACTIVE_JOB = previous
1134
+ if _ACTIVE_JOB is None and job.handle is not None and not job._held and not job._threads:
1135
+ job.close()
1136
+
1137
+
1138
+ def hold_in_job(pid, kernel32=None, last_error=None):
1139
+ """A job holding `pid` and what it starts, resumed after assignment and killed when it closes (WIN-JOB), or (None, why).
1140
+
1141
+ None and None where this is not Windows: there a process group is stopped instead, by
1142
+ `_stop_reviewer_leftovers`. When started under `creating_in_job`, the process is placed in the job at
1143
+ `CreateProcessW` with `PROC_THREAD_ATTRIBUTE_JOB_LIST` and a locked thread DACL, then resumed here from
1144
+ its direct thread handle. A job the platform refused - or whose process was already resumed or could not
1145
+ be resumed - is closed, ending the process and leaking no handle, and the reason is the caller's to say.
1146
+ """
1147
+ if sys.platform != "win32":
1148
+ return None, None
1149
+ job = (_ACTIVE_JOB if (_ACTIVE_JOB is not None and kernel32 is None and last_error is None)
1150
+ else JobObject(kernel32, last_error))
1151
+ why = job.hold(pid) or job.resume(pid)
1152
+ if why:
1153
+ job.close()
1154
+ return None, why
1155
+ return job, None
1156
+
1157
+
1158
+ def ppid(pid):
1159
+ """The pid of the process that started `pid`, or None where the platform does not say (ANCESTOR-WINDOWS)."""
1160
+ reader = getattr(_backend(), "ppid", None)
1161
+ try:
1162
+ parent = reader(int(pid)) if reader else None
1163
+ if parent is None:
1164
+ parent = (info(int(pid)) or {}).get("ppid")
1165
+ except Exception:
1166
+ return None
1167
+ return None if parent is None else int(parent)
1168
+
1169
+
1170
+ def elapsed(pid):
1171
+ """Whole seconds since the process started, as `ps -o etime` counts them; None when that cannot be read."""
1172
+ try:
1173
+ return _backend().elapsed(pid)
1174
+ except Exception:
1175
+ return None
1176
+
1177
+
1178
+ def table():
1179
+ """{pid: (ppid, pgid, tty)} for every process; tty is "??" when there is none,
1180
+ matching the shape the older ps-based code produced.
1181
+
1182
+ TableUnreadable where the platform lists no process, or lists processes of which none can be
1183
+ read: either is a table it could not read, never one in which nothing runs (WINDOWS-TABLE-CLOSED).
1184
+ """
1185
+ out = {}
1186
+ b = _backend()
1187
+ pids = b.all_pids()
1188
+ for pid in pids:
1189
+ i = b.info(pid)
1190
+ if i:
1191
+ out[pid] = (i["ppid"], i["pgid"], "??" if i["tty"] is None else str(i["tty"]))
1192
+ if pids and not out:
1193
+ raise TableUnreadable(f"it lists {len(pids)} processes and none of them could be read")
1194
+ return out