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
@@ -0,0 +1,2099 @@
1
+ """Measurement and gates: unfiltered git, size, gate coverage, review artefacts, merge checks.
2
+
3
+ A part of src/polyctl/lib.py (#44): moved out byte for byte and run in its namespace by `_part`,
4
+ where it stood; it is not importable on its own.
5
+ """
6
+
7
+
8
+ # ---- polyctl's own measurements are not read through a filter (#51) ------------------------
9
+
10
+ # ELF, Mach-O (fat and thin, either byte order) and PE: a compiled program, not a script.
11
+ _NATIVE_MAGIC = (b"\x7fELF", b"\xca\xfe\xba\xbe", b"\xbe\xba\xfe\xca", b"\xcf\xfa\xed\xfe",
12
+ b"\xce\xfa\xed\xfe", b"\xfe\xed\xfa\xcf", b"\xfe\xed\xfa\xce", b"MZ")
13
+ # What polyctl treats as evidence; the doctor names them when something could filter them.
14
+ MEASUREMENTS = ("candidate size and paths", "git status", "rev-parse", "write-tree", "hash-object",
15
+ "gate output")
16
+ _REWRITING_HOOK = re.compile(r"\brtk\b|\bproxy\b|rewrit|compress|condens", re.I)
17
+ _GIT_BINARIES = {}
18
+
19
+
20
+ def _native_executable(path):
21
+ try:
22
+ with open(path, "rb") as fh:
23
+ head = fh.read(4)
24
+ except OSError:
25
+ return False
26
+ return any(head.startswith(magic) for magic in _NATIVE_MAGIC)
27
+
28
+
29
+ # The one git that is an xcrun stub: macOS's own. An xcrun beside any other compiled git was run once a process
30
+ # on every platform but Windows, a program polyctl had no reason to start (SUITE-SPEED-2).
31
+ _XCRUN_STUB = "/usr/bin/git"
32
+
33
+
34
+ def _xcrun_git(candidate):
35
+ """The git an xcrun stub runs, or None when `candidate` is not such a stub.
36
+
37
+ /usr/bin/git on macOS is a compiled stub: on every call it asks xcrun for the
38
+ selected developer directory and runs the git there, which costs more than
39
+ git's own start, and a hook or a gate makes hundreds of git calls. The stub is
40
+ told from a real git by the xcrun beside it, and `xcrun --find git` names the
41
+ binary it would run. That answer is taken only when it is itself a compiled
42
+ git, so it can never put a script in front of git.
43
+ """
44
+ stub = os.path.realpath(candidate)
45
+ if stub != _XCRUN_STUB:
46
+ return None
47
+ xcrun = os.path.join(os.path.dirname(stub), "xcrun")
48
+ if not (_native_executable(stub) and os.path.isfile(xcrun) and os.access(xcrun, os.X_OK)):
49
+ return None
50
+ import errno
51
+ result = None
52
+ for attempt in range(5):
53
+ try:
54
+ result = subprocess.run([xcrun, "--find", "git"], stdin=subprocess.DEVNULL, stdout=subprocess.PIPE,
55
+ stderr=subprocess.DEVNULL, timeout=60)
56
+ break
57
+ except subprocess.TimeoutExpired:
58
+ return None
59
+ except OSError as exc:
60
+ if attempt == 4 or exc.errno not in (errno.EAGAIN, errno.ENOMEM, getattr(errno, "ETXTBSY", None)):
61
+ return None
62
+ time.sleep(0.02)
63
+ found = result.stdout.decode(UTF8, "replace").strip()
64
+ if result.returncode == 0 and os.path.isabs(found) and os.path.basename(found) == "git" \
65
+ and os.path.isfile(found) and os.access(found, os.X_OK) \
66
+ and os.path.realpath(found) != stub and _native_executable(os.path.realpath(found)):
67
+ return found
68
+ return None
69
+
70
+
71
+ def _find_git_binary():
72
+ explicit = os.environ.get("POLYCTL_GIT")
73
+ if explicit and os.path.isfile(explicit) and os.access(explicit, os.X_OK):
74
+ return explicit
75
+ names = ("git.exe", "git") if os.name == "nt" else ("git",)
76
+ directories = search_directories()
77
+ installed = os.path.join(os.environ.get("ProgramFiles", r"C:\Program Files"), "Git", "cmd")
78
+ if os.name == "nt":
79
+ directories.append(installed)
80
+ else:
81
+ directories += ["/usr/bin", "/bin", "/usr/local/bin", "/opt/homebrew/bin"]
82
+ for directory in directories:
83
+ for name in names:
84
+ candidate = os.path.join(directory, name)
85
+ if os.path.isfile(candidate) and os.access(candidate, os.X_OK) \
86
+ and _native_executable(os.path.realpath(candidate)):
87
+ return _xcrun_git(candidate) or candidate
88
+ # With no compiled git, the git PATH holds, of whatever kind. Never the bare name: Windows looks for it in the
89
+ # current directory first, and POSIX's execvp through every PATH entry, an empty one - the current directory -
90
+ # among them. The last resort is where git is installed, which fails to start rather than start a git an agent
91
+ # left in the tree (WINDOWS-NO-CWD-EXEC, and its review for POSIX).
92
+ return program_path("git") or (os.path.join(installed, "git.exe") if os.name == "nt" else "/usr/bin/git")
93
+
94
+
95
+ def git_binary():
96
+ """The git polyctl measures with (#51).
97
+
98
+ A token-saving proxy in an agent's shell reported a 5,844-line staged diff as
99
+ 533 lines, and the number nearly sized a decision. polyctl reads its measurements
100
+ itself, never from an agent's terminal, and it does not take a wrapper for git
101
+ either: POLYCTL_GIT when that names an executable, otherwise the first git on PATH,
102
+ then in the system directories, that is a compiled program rather than a
103
+ script in front of one; the first git PATH holds of any kind only when there
104
+ is none, and where git is installed when PATH holds none either - never the
105
+ bare name, which Windows looks for in the current directory first and POSIX
106
+ through an empty PATH entry (WINDOWS-NO-CWD-EXEC).
107
+ When that git is macOS's xcrun stub, the git xcrun names instead, asked once
108
+ per process.
109
+ """
110
+ key = (os.environ.get("POLYCTL_GIT"), os.environ.get("PATH", ""), os.name, os.environ.get("DEVELOPER_DIR"), _XCRUN_STUB)
111
+ found = _GIT_BINARIES.get(key)
112
+ if found is None or (found != "git" and not os.path.isfile(found)):
113
+ found = _GIT_BINARIES[key] = _find_git_binary()
114
+ return found
115
+
116
+
117
+ def measured_by():
118
+ """How the measurements in a record were taken: which git, no shell, read by polyctl (#51)."""
119
+ return {"git": git_binary(), "candidate_via_shell": False, "captured_by": "polyctl"}
120
+
121
+
122
+ def command_hook_sources(root):
123
+ """(settings file, the adapter's declaration, whether the file is user-level) for each hook file (#76, #52).
124
+
125
+ A user-level file is one an adapter names under `~`, outside every repository. The
126
+ project's own files are writable by the agents polyctl governs, so the filter probe runs
127
+ no command they name.
128
+ """
129
+ out, seen = [], set()
130
+ for adapter in package_adapters().values():
131
+ hooks = (adapter.get("directives") or {}).get("command_hooks") or {}
132
+ if hooks.get("format") != "pre-tool-use":
133
+ continue
134
+ for rel in hooks.get("files") or []:
135
+ user = str(rel).startswith("~")
136
+ path = _home_path(rel) if user else os.path.join(root, *str(rel).split("/"))
137
+ if path not in seen:
138
+ seen.add(path)
139
+ out.append((path, hooks, user))
140
+ return out
141
+
142
+
143
+ def command_hook_files(root):
144
+ """Settings files whose pre-tool-use hooks can rewrite an agent's shell commands, as adapters declare them (#76)."""
145
+ return [path for path, _, _ in command_hook_sources(root)]
146
+
147
+
148
+ def _matcher_matches(matcher, tool):
149
+ """A hook matcher read as the harness reads it: empty or `*` is every tool, plain words exact names, else a regex."""
150
+ text = "" if matcher is None else str(matcher)
151
+ if text in ("", "*"):
152
+ return True
153
+ if re.fullmatch(r"[A-Za-z0-9_\- ,|]+", text):
154
+ return tool in {name.strip() for name in re.split(r"[|,]", text)}
155
+ try:
156
+ return re.search(text, tool) is not None
157
+ except re.error:
158
+ return True # a matcher polyctl cannot read is counted, not passed over
159
+
160
+
161
+ def _shell_hooks(path, declaration):
162
+ """The command hooks a settings file runs before the harness's shell tool, in the order it declares them."""
163
+ try:
164
+ with open(path, encoding=UTF8) as fh:
165
+ hooks = json.load(fh).get("hooks")
166
+ except (OSError, ValueError, AttributeError):
167
+ return []
168
+ tool = str(declaration.get("shell_tool") or "Bash")
169
+ entries = hooks.get("PreToolUse") if isinstance(hooks, dict) else None
170
+ return [hook for entry in (entries if isinstance(entries, list) else [])
171
+ if isinstance(entry, dict) and _matcher_matches(entry.get("matcher"), tool)
172
+ for hook in (entry.get("hooks") if isinstance(entry.get("hooks"), list) else [])
173
+ if isinstance(hook, dict) and hook.get("type", "command") == "command"]
174
+
175
+
176
+ def _hook_text(hook):
177
+ """A command hook as one line: its command, and its arguments when it declares them apart."""
178
+ args = hook.get("args") if isinstance(hook.get("args"), list) else []
179
+ return " ".join(word for word in [str(hook.get("command") or ""), *map(str, args)] if word)
180
+
181
+
182
+ def measurement_filters(root):
183
+ """What could stand between a number and its source, one sentence each (#51).
184
+
185
+ A script named git ahead of any compiled git on PATH, POLYCTL_GIT naming no compiled
186
+ executable, and shell PreToolUse hooks. Unknown hooks are unverified: a command
187
+ without the recognised keywords used to disappear here (TRIAGE-2-LOW).
188
+ `probe_filters` asks eligible hooks what they do (#52).
189
+ """
190
+ found = []
191
+ explicit = os.environ.get("POLYCTL_GIT")
192
+ if explicit and not (os.path.isfile(explicit) and os.access(explicit, os.X_OK)):
193
+ found.append(f"POLYCTL_GIT names {explicit}, which is not an executable file; polyctl measures with {git_binary()}")
194
+ elif explicit and not _native_executable(os.path.realpath(explicit)):
195
+ found.append(f"POLYCTL_GIT names {explicit}, which is not a compiled program; polyctl measures through it: "
196
+ "set POLYCTL_GIT to a compiled git for unfiltered measurements")
197
+ first = program_path("git")
198
+ if first and not _native_executable(os.path.realpath(first)):
199
+ chosen = git_binary()
200
+ found.append(f"git on PATH is {first}, a script in front of git; " + (
201
+ f"polyctl measures with {chosen}" if _native_executable(os.path.realpath(chosen)) else
202
+ "no compiled git was found, so polyctl's own measurements go through it too: set POLYCTL_GIT"))
203
+ for path, declaration, _ in command_hook_sources(root):
204
+ for hook in _shell_hooks(path, declaration):
205
+ command = _hook_text(hook)
206
+ if _REWRITING_HOOK.search(command):
207
+ found.append(f"{path}: the PreToolUse hook `{command}` can rewrite the shell commands an "
208
+ f"agent runs, so what an agent reads of {', '.join(MEASUREMENTS)} may be "
209
+ "compressed; take such numbers from polyctl's records, which do not pass through it")
210
+ else:
211
+ found.append(f"{path}: the PreToolUse shell hook `{command}` is unverified; inspect it before "
212
+ "trusting measurements read through the agent's shell")
213
+ return found
214
+
215
+
216
+ # ---- a filter's exclusions are proved by asking it, not read from its configuration (#52) --
217
+
218
+ # The shell commands through which an agent reads a measurement - candidate size and paths, git
219
+ # status, history, rev-parse, write-tree, hash-object and polyctl's own records - that a filter's
220
+ # exclusion list must leave alone. `measurement_commands` adds the project's gate commands.
221
+ MEASUREMENT_COMMANDS = ("git diff", "git diff --cached", "git diff --stat", "git diff --numstat",
222
+ "git diff --cached --numstat", "git diff --name-only", "git status",
223
+ "git status --porcelain", "git log", "git log --oneline", "git show --stat",
224
+ "git rev-parse HEAD", "git write-tree", "git hash-object --stdin",
225
+ "polyctl status", "polyctl verify", "polyctl review", "polyctl board")
226
+ # All a probed hook sees of polyctl's environment: where programs, its home and its own configuration
227
+ # are. No credential, no GIT_* binding, no loader or interpreter start-up variable.
228
+ _PROBE_ENVIRONMENT = ("PATH", "HOME", "USER", "LOGNAME", "USERNAME", "USERPROFILE", "APPDATA", "LOCALAPPDATA",
229
+ "XDG_CONFIG_HOME", "XDG_DATA_HOME", "TMPDIR", "TMP", "TEMP", "LANG", "LC_ALL",
230
+ "SYSTEMROOT", "WINDIR", "PATHEXT")
231
+ _PROBE_OUTPUT_BYTES = 65_536
232
+ _PROBE_GATE_COMMANDS = 12
233
+ # What makes a command more than words to split: expansion, substitution, redirection, globs,
234
+ # chaining and escapes. Such a command needs a shell, and the probe runs none.
235
+ _SHELL_SYNTAX = re.compile(r"[$`|&;<>(){}\[\]*?!#\\\r\n]")
236
+
237
+
238
+ def measurement_commands(root):
239
+ """The commands the filter probe asks a hook about: MEASUREMENT_COMMANDS, then the project's gates (#52).
240
+
241
+ The gate commands are what an agent runs to read a count. They come from a file the
242
+ agents can write, so they are taken as data only - the payload a hook reads - and
243
+ at most _PROBE_GATE_COMMANDS of them.
244
+ """
245
+ commands = list(MEASUREMENT_COMMANDS)
246
+ try:
247
+ with open(os.path.join(root, ".polyctl", "gates.json"), encoding=UTF8) as fh:
248
+ gates = json.load(fh).get("gates")
249
+ except (OSError, ValueError, AttributeError):
250
+ gates = None
251
+ for gate in (gates.values() if isinstance(gates, dict) else []):
252
+ run = gate.get("run").strip() if isinstance(gate, dict) and isinstance(gate.get("run"), str) else ""
253
+ if run and len(run) <= 1000 and run not in commands:
254
+ commands.append(run)
255
+ if len(commands) >= len(MEASUREMENT_COMMANDS) + _PROBE_GATE_COMMANDS:
256
+ break
257
+ return commands
258
+
259
+
260
+ def _within(path, root):
261
+ """Whether a path, followed through its links, lies inside root."""
262
+ real, top = (os.path.normcase(os.path.realpath(p)) for p in (path, root))
263
+ try:
264
+ return os.path.commonpath([real, top]) == top
265
+ except ValueError:
266
+ return False # another drive
267
+
268
+
269
+ def _hook_argv(hook):
270
+ """The argument vector a command hook runs as without a shell, or (None, why only a shell could run it)."""
271
+ import shlex
272
+ command = hook.get("command")
273
+ if not isinstance(command, str) or not command.strip():
274
+ return None, "it names no command"
275
+ if "args" in hook:
276
+ # Exec form: the harness runs `command` with `args`, no shell, placeholders filled in.
277
+ args = hook["args"]
278
+ if not isinstance(args, list) or not all(isinstance(arg, str) for arg in args):
279
+ return None, "its args are not a list of strings"
280
+ if any("${" in word for word in [command, *args]):
281
+ return None, "it names a placeholder only the harness fills in"
282
+ return [command, *args], None
283
+ if str(hook.get("shell") or "bash").lower() not in ("bash", "sh"):
284
+ return None, f"it runs under {hook['shell']}, which polyctl does not imitate"
285
+ words = None
286
+ if not _SHELL_SYNTAX.search(command):
287
+ try:
288
+ words = shlex.split(command)
289
+ except ValueError:
290
+ words = None
291
+ if not words or "=" in words[0] or any("~" in word and word != "~" and not word.startswith("~/")
292
+ for word in words):
293
+ return None, "it needs a shell to run, and polyctl runs none; declare it as command and args"
294
+ return [_home_path(word) for word in words], None
295
+
296
+
297
+ # A word that names a file whether or not it is there yet: a separator in it, or a name with an extension
298
+ # (FILTER-EXCLUSIONS-2). A decimal or a version - 1.5, v2 - is no file name.
299
+ _PATH_WORD = re.compile(r"[/\\]")
300
+ _FILE_WORD = re.compile(r"[\w.-]*\.[A-Za-z]\w*")
301
+ # An address on another host names no file here; a file: URL names the path after it.
302
+ _URL_WORD = re.compile(r"[A-Za-z][A-Za-z0-9+.-]*://")
303
+ # A file address with no authority, `file:/C:/x` or `file:x`, which Node and Rust read as a path (FILTER-EXCLUSIONS-5).
304
+ _FILE_URL_BARE = re.compile(r"file:(?!//)", re.I)
305
+ # What a URL reader drops before it reads the scheme, as the WHATWG URL standard says and Node, Rust's url and
306
+ # Python's urlsplit do: C0 controls and spaces at either end, and a tab, CR or LF anywhere (FILTER-EXCLUSIONS-8).
307
+ _URL_READER_DROPS = re.compile(r"\A[\x00-\x20]+|[\x00-\x20]+\Z|[\t\r\n]")
308
+
309
+
310
+ def _probe_program(argv, root, programs, search_path):
311
+ """The argv polyctl may run for a user-level hook, its program resolved, or (None, the rule it fails) (#52).
312
+
313
+ A filter is itself a program that runs commands, so the rule is about who chose the
314
+ words as much as which program they name: the program must be one the machine
315
+ allows, found where the agents' PATH finds it, outside the project, and no argument
316
+ may name a path the agents can write.
317
+ """
318
+ name = _program_name(argv[0])
319
+ if name not in programs:
320
+ return None, f"{name} is not in filters.probe_programs, the programs polyctl may run to ask"
321
+ if os.path.isabs(argv[0]):
322
+ found = argv[0] if os.path.isfile(argv[0]) and os.access(argv[0], os.X_OK) else None
323
+ elif "/" in argv[0] or os.sep in argv[0]:
324
+ return None, f"its program {argv[0]} is named relative to the directory it runs in, the project"
325
+ else:
326
+ found = program_path(argv[0], path=search_path)
327
+ if not found:
328
+ return None, f"{argv[0]} is not an executable on the agents' PATH"
329
+ if os.path.splitext(found)[1].lower() in (".bat", ".cmd"):
330
+ return None, f"{found} is a batch file, which only a shell runs"
331
+ for word in [found, *argv[1:]]:
332
+ for piece in {word, word.split("=", 1)[-1]}:
333
+ # `<TAB>file:///repo/.polyctl/filter.toml#/../..` is the project's file to a URL reader, and to polyctl it was a
334
+ # relative path climbing out of the project (FILTER-EXCLUSIONS-8).
335
+ read = _URL_READER_DROPS.sub("", piece)
336
+ if read != piece and (_URL_WORD.match(read) or _FILE_URL_BARE.match(read)):
337
+ return None, (f"{word!r} is an address once a URL reader drops its spaces and control characters, "
338
+ "and a path to a program that keeps them, which programs read differently")
339
+ url = _URL_WORD.match(piece) or _FILE_URL_BARE.match(piece)
340
+ if url and piece[:url.end()].lower() not in ("file://", "file:"):
341
+ continue
342
+ if url:
343
+ # The path a file address names, as a program opening it reads it: percent-decoded, and on
344
+ # Windows `/C:/x` as `C:\x`; the text after the scheme alone let an encoded project path pass
345
+ # (FILTER-EXCLUSIONS-3).
346
+ from urllib.request import url2pathname
347
+ address = piece[url.end():]
348
+ # A program reading the address as a URL - Node's fileURLToPath, Rust's url, url2pathname from
349
+ # Python 3.14 - drops a query and a fragment, reads a `\` as `/` and drops a tab, CR or LF; one
350
+ # decoding the text after the scheme, as url2pathname did before 3.14, keeps them as path, `?/../..`
351
+ # and all. polyctl cannot tell which reads it, and judged whichever its own Python is (FILTER-EXCLUSIONS-6).
352
+ # `file:x/y` names no root: a URL reader takes it from the root, and polyctl took it under the project
353
+ # (FILTER-EXCLUSIONS-7).
354
+ bare = piece[:url.end()].lower() == "file:"
355
+ if bare and not address.startswith("/") \
356
+ or any(mark in address for mark in ("?", "#", "\\", "\t", "\r", "\n")):
357
+ return None, (f"{word!r} is a file address with no root, or holding a query or fragment, a "
358
+ "backslash or a control character, which programs read differently")
359
+ if address[:10].lower() == "localhost/":
360
+ address = address[9:] # this machine, as a program reads it: no directory of the path
361
+ try:
362
+ piece = url2pathname(address)
363
+ except (OSError, ValueError):
364
+ return None, f"{word} is a file address polyctl cannot read as a path"
365
+ # url2pathname looks for a drive before it decodes: `/C%3A/x` is `\C:\x` to it and C:\x to Node's
366
+ # fileURLToPath and Rust's url, which decode first. A NUL ends the path a C program opens short of
367
+ # the one polyctl would judge (FILTER-EXCLUSIONS-4).
368
+ if os.name == "nt" and re.match(r"[\\/][A-Za-z]:", piece):
369
+ piece = piece[1:]
370
+ if "\0" in piece:
371
+ return None, f"{word} is a file address polyctl cannot read as a path"
372
+ candidate = piece if os.path.isabs(piece) else os.path.join(root, piece)
373
+ # A path inside the project counts whether or not it exists yet: an agent could write it between this
374
+ # check and the hook's run, once per command measured, and remove it again (FILTER-EXCLUSIONS-2). An
375
+ # option is read by its program, not opened: its value after `=` is the piece that can name a file.
376
+ looks = not piece.startswith("-") and bool(_PATH_WORD.search(piece) or _FILE_WORD.fullmatch(piece))
377
+ named = os.path.isabs(piece) or os.path.lexists(candidate) or looks
378
+ if not (piece and named):
379
+ continue
380
+ # A path that cannot be followed to an absolute one is not known to lie outside: Windows' realpath of
381
+ # `f::$DATA`, the stream of a file not yet written, came back relative to the drive (FILTER-EXCLUSIONS-5).
382
+ try:
383
+ followed = os.path.realpath(candidate)
384
+ except (OSError, ValueError):
385
+ followed = None
386
+ if not followed or not os.path.isabs(followed):
387
+ return None, f"{piece} names a path polyctl cannot follow to where it lies"
388
+ if _within(candidate, root):
389
+ return None, f"{piece} lies inside the project, where the agents polyctl governs can write"
390
+ return [found, *argv[1:]], None
391
+
392
+
393
+ def _probe_environment(root, declaration, search_path):
394
+ """What a probed hook is given: _PROBE_ENVIRONMENT, the agents' PATH and the project directory variable."""
395
+ env = {name: os.environ[name] for name in _PROBE_ENVIRONMENT if os.environ.get(name)}
396
+ env["PATH"] = search_path
397
+ variable = declaration.get("project_dir_env")
398
+ if isinstance(variable, str) and re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", variable):
399
+ env[variable] = root
400
+ return env
401
+
402
+
403
+ def _run_hook(argv, payload, cwd, env, timeout):
404
+ """Run one hook with one payload as the harness would, inside a time and an output bound (#52).
405
+
406
+ Returns (exit code, stdout, stderr, None), or (None, b"", b"", what cut it off). The hook
407
+ leads its own process group, so a timeout ends whatever it started; a child still
408
+ holding its output open is still answering.
409
+ """
410
+ import signal
411
+ import threading
412
+ group = ({"creationflags": getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)} if os.name == "nt"
413
+ else {"start_new_session": True})
414
+ try:
415
+ proc = subprocess.Popen(argv, cwd=cwd, env=env, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
416
+ stderr=subprocess.PIPE, **group)
417
+ except OSError as exc:
418
+ return None, b"", b"", f"it could not be started ({exc.strerror or exc})"
419
+ output, flooded = {"out": bytearray(), "err": bytearray()}, threading.Event()
420
+
421
+ def feed():
422
+ try:
423
+ proc.stdin.write(payload)
424
+ except OSError:
425
+ pass # a hook may exit without reading what it was given
426
+ try:
427
+ proc.stdin.close()
428
+ except OSError:
429
+ pass
430
+
431
+ def drain(stream, into):
432
+ try:
433
+ for block in iter(lambda: stream.read1(65536), b""):
434
+ into.extend(block)
435
+ if len(into) > _PROBE_OUTPUT_BYTES:
436
+ flooded.set()
437
+ return
438
+ except (OSError, ValueError):
439
+ pass
440
+
441
+ readers = [threading.Thread(target=drain, args=(proc.stdout, output["out"]), daemon=True),
442
+ threading.Thread(target=drain, args=(proc.stderr, output["err"]), daemon=True)]
443
+ for thread in [threading.Thread(target=feed, daemon=True), *readers]:
444
+ thread.start()
445
+ deadline, cut = time.monotonic() + timeout, None
446
+ while cut is None and (proc.poll() is None or any(reader.is_alive() for reader in readers)):
447
+ if flooded.is_set():
448
+ cut = f"it wrote more than {_PROBE_OUTPUT_BYTES} bytes"
449
+ elif time.monotonic() >= deadline:
450
+ cut = f"it did not answer within {timeout}s"
451
+ else:
452
+ time.sleep(0.01)
453
+ if cut is None and flooded.is_set():
454
+ cut = f"it wrote more than {_PROBE_OUTPUT_BYTES} bytes"
455
+ if cut and (proc.poll() is None or any(reader.is_alive() for reader in readers)):
456
+ if os.name == "nt":
457
+ left = stop_windows_tree(proc.pid)
458
+ if left:
459
+ # What taskkill left of it is named, not taken as stopped (WINDOWS-STOP-PROVEN).
460
+ cut += f" - and {len(left)} process(es) of it still run after it was stopped, {left} -"
461
+ else:
462
+ try:
463
+ os.killpg(proc.pid, signal.SIGKILL)
464
+ except OSError:
465
+ pass
466
+ try:
467
+ proc.kill()
468
+ except OSError:
469
+ pass
470
+ try:
471
+ proc.wait(timeout=5)
472
+ except subprocess.TimeoutExpired:
473
+ pass
474
+ for reader in readers:
475
+ reader.join(1)
476
+ if not any(reader.is_alive() for reader in readers):
477
+ for stream in (proc.stdout, proc.stderr):
478
+ stream.close()
479
+ if cut:
480
+ return None, b"", b"", cut
481
+ return proc.returncode, bytes(output["out"]), bytes(output["err"]), None
482
+
483
+
484
+ def _hook_answer(command, code, out, err):
485
+ """What a pre-tool-use hook's answer does to one command, read as the harness reads it (#52).
486
+
487
+ (None, None) passes it through unchanged. ("rewrites", the new command or None) and
488
+ ("blocks", how) change what an agent reads; ("unreadable", why) is an answer polyctl can
489
+ vouch for neither way. A rewrite counts whether or not the answer also allows the
490
+ command: harness versions have differed on applying a rewrite that carries no decision,
491
+ and keeping measurements out of the filter is its exclusion list's job, not theirs.
492
+ """
493
+ if code == 2:
494
+ lines = err.decode(UTF8, "replace").strip().splitlines()
495
+ return "blocks", "is blocked" + (f" ({lines[0][:160]})" if lines else "")
496
+ text = out.decode(UTF8, "replace").strip()
497
+ answer = None
498
+ if text.startswith("{") and text.endswith("}"):
499
+ try:
500
+ answer = json.loads(text)
501
+ except ValueError:
502
+ return "unreadable", "its answer is not JSON"
503
+ if isinstance(answer, dict):
504
+ specific = answer.get("hookSpecificOutput") if isinstance(answer.get("hookSpecificOutput"), dict) else {}
505
+ decision = specific.get("permissionDecision")
506
+ reason = str(specific.get("permissionDecisionReason") or answer.get("reason")
507
+ or answer.get("stopReason") or "")[:160]
508
+ why = f" ({reason})" if reason else ""
509
+ if answer.get("continue") is False:
510
+ return "blocks", "stops the agent before it runs" + why
511
+ if decision == "deny" or answer.get("decision") == "block":
512
+ return "blocks", "is blocked" + why
513
+ if "updatedInput" in specific:
514
+ updated = specific["updatedInput"]
515
+ rewritten = updated.get("command") if isinstance(updated, dict) else None
516
+ if rewritten != command:
517
+ return "rewrites", rewritten if isinstance(rewritten, str) else None
518
+ if decision == "ask":
519
+ return "blocks", "is held for a person's approval" + why
520
+ if code != 0:
521
+ return "unreadable", f"it exited {code}"
522
+ return None, None
523
+
524
+
525
+ def probe_filters(root):
526
+ """Ask each hook that could filter an agent's shell what it does to every measurement command (#52).
527
+
528
+ #51 names such a hook by its command. #52 installs one on purpose, with an exclusion
529
+ list covering every measurement path, and asks the doctor to prove the list is in
530
+ force rather than trust it: a release of one such filter kept rewriting what its
531
+ exclusion list named, the list being read on only one of its two rewrite paths. So
532
+ each hook is run as the harness runs it, once per command in `measurement_commands`,
533
+ with the payload the harness sends, and its answer is read as the harness reads it.
534
+ The command it answers with is never run.
535
+
536
+ `polyctl doctor --check` runs unattended, and a settings file the agents can write would
537
+ make this a way to run anything. A hook is run only when it is declared in a
538
+ user-level file outside the project and `_probe_program` allows its program; then
539
+ without a shell, in the project directory as the harness runs it, with
540
+ `_probe_environment`, `filters.probe_timeout_seconds` for each answer and bounded
541
+ output. Any other hook that could filter is reported unverified, with the rule it
542
+ fails. Returns a dict per hook: file, user, command, program, verdict (in-force,
543
+ filters, unverified), changed [(command, "rewrites" or "blocks", detail)], why, asked.
544
+ """
545
+ root = os.path.abspath(root)
546
+ programs = {_program_name(name) for name in settings.get(None, "filters.probe_programs")}
547
+ timeout = settings.get(None, "filters.probe_timeout_seconds")
548
+ results, search_path, commands = [], None, None
549
+ for path, declaration, user in command_hook_sources(root):
550
+ for hook in _shell_hooks(path, declaration):
551
+ shown = _hook_text(hook)
552
+ argv, why = _hook_argv(hook)
553
+ program = _program_name(argv[0] if argv else (shown.split() or ["hook"])[0])
554
+ if not (_REWRITING_HOOK.search(shown) or program in programs):
555
+ continue
556
+ result = {"file": path, "user": user, "command": shown, "program": program, "verdict": "unverified",
557
+ "changed": [], "why": None, "asked": 0}
558
+ results.append(result)
559
+ if not user or _within(path, root):
560
+ result["why"] = ("it is declared in the project's own settings, which the agents polyctl governs can "
561
+ "write, and polyctl runs no command such a file names")
562
+ continue
563
+ if argv:
564
+ if search_path is None:
565
+ from .watchdog import child_path
566
+ search_path = os.pathsep.join(d for d in child_path().split(os.pathsep)
567
+ if d and os.path.isabs(d) and not _within(d, root))
568
+ argv, why = _probe_program(argv, root, programs, search_path)
569
+ if why:
570
+ result["why"] = why
571
+ continue
572
+ env = _probe_environment(root, declaration, search_path)
573
+ tool = str(declaration.get("shell_tool") or "Bash")
574
+ commands = measurement_commands(root) if commands is None else commands
575
+ for index, command in enumerate(commands):
576
+ payload = json.dumps({
577
+ "session_id": "polyctl-filter-probe", "transcript_path": "", "cwd": root,
578
+ "permission_mode": "default", "hook_event_name": "PreToolUse", "tool_name": tool,
579
+ "tool_input": {"command": command, "description": "polyctl doctor: does a filter change this?"},
580
+ "tool_use_id": f"polyctl-filter-probe-{index}"}).encode(UTF8)
581
+ code, out, err, cut = _run_hook(argv, payload, root, env, timeout)
582
+ result["asked"] += 1
583
+ kind, detail = (None, cut) if cut else _hook_answer(command, code, out, err)
584
+ if cut or kind == "unreadable":
585
+ result["why"] = f"{detail} when asked about `{_clip(command)}`"
586
+ break
587
+ if kind:
588
+ result["changed"].append((command, kind, detail))
589
+ result["verdict"] = "filters" if result["changed"] else "unverified" if result["why"] else "in-force"
590
+ return results
591
+
592
+
593
+ def _clip(text, limit=200):
594
+ """Text a settings file or a hook supplied, on one line and no longer than limit, for a doctor line."""
595
+ line = " ".join(str(text).split())
596
+ return line if len(line) <= limit else line[:limit - 3] + "..."
597
+
598
+
599
+ def filter_probe_text(result):
600
+ """One sentence for one probed hook: in force, every measurement command it changes, or why it is unverified."""
601
+ where = f"`{_clip(result['command'])}` ({result['file']})"
602
+ if result["verdict"] == "in-force":
603
+ return f"{where} passes all {result['asked']} measurement commands through unchanged: its exclusions are in force"
604
+ changes = [(f"`{_clip(command)}` becomes `{_clip(detail)}`" if detail is not None
605
+ else f"`{_clip(command)}` loses its command")
606
+ if kind == "rewrites" else f"`{_clip(command)}` {detail}" for command, kind, detail in result["changed"]]
607
+ parts = [f"changes {len(changes)} of the {result['asked']} measurement commands it was asked about: "
608
+ + "; ".join(changes)] if changes else []
609
+ if result["why"]:
610
+ parts.append(f"is not verified: {result['why']}")
611
+ return f"{where} " + ", and ".join(parts)
612
+
613
+
614
+ # A check holds one repository for its whole lifetime, including a nested call; no process-wide environment
615
+ # is changed and a planted project .git cannot move a later measurement (NESTED-GIT).
616
+ from contextlib import contextmanager as _git_contextmanager
617
+ from contextvars import ContextVar as _GitContextVar
618
+
619
+ _COMMIT_GIT_CONTEXT = _GitContextVar("polyctl_commit_git", default=None)
620
+
621
+
622
+ @_git_contextmanager
623
+ def bound_git_repository(top, git_dir, index):
624
+ """Pin the hook's repository and active index until the check returns, even on failure (NESTED-GIT)."""
625
+ token = _COMMIT_GIT_CONTEXT.set((top, git_dir, index))
626
+ try:
627
+ yield
628
+ finally:
629
+ _COMMIT_GIT_CONTEXT.reset(token)
630
+
631
+
632
+ def bound_git_environment(env):
633
+ """Git reads the pinned repository, never a .git rediscovered from the project cwd (NESTED-GIT)."""
634
+ binding = _COMMIT_GIT_CONTEXT.get()
635
+ if binding is None:
636
+ return env
637
+ top, git_dir, index = binding
638
+ clean = {name: value for name, value in env.items()
639
+ if name not in _GIT_BINDING and not name.startswith("GIT_CONFIG")}
640
+ clean.update(GIT_DIR=git_dir, GIT_WORK_TREE=top, GIT_INDEX_FILE=index)
641
+ return clean
642
+
643
+
644
+ def _git_output(root, *args, timeout=60, env=None):
645
+ """Run git without a shell and return bytes, failing closed on an unreadable tree.
646
+
647
+ In a process group of its own, as every Git query of authority's is: a timeout stops git with what it started -
648
+ a hook or a filter a repository configures - where it stopped git alone (LEADS-GATE-RUNS).
649
+ """
650
+ try:
651
+ merged = dict(os.environ, **env) if env else os.environ.copy()
652
+ result = run_as_group([git_binary(), *args], timeout, cwd=root, stdout=subprocess.PIPE,
653
+ stderr=subprocess.PIPE, env=bound_git_environment(merged))
654
+ except (OSError, subprocess.TimeoutExpired) as exc:
655
+ left, unasked = getattr(exc, "left", None), getattr(exc, "unasked", None)
656
+ raise RuntimeError(f"cannot measure git tree: {exc}"
657
+ + (f"; {len(left)} process(es) it started still run after it was stopped: {left}"
658
+ if left else "") + (f"; {unasked}" if unasked else "")) from exc
659
+ if result.returncode:
660
+ detail = result.stderr.decode(UTF8, "replace").strip()[:240]
661
+ raise RuntimeError(f"cannot measure git tree: {detail or 'git failed'}")
662
+ return result.stdout
663
+
664
+
665
+ def _git_text(cwd, *args, timeout=20, env=None):
666
+ """What `sh("git …", cwd=cwd)` returned, from the same git without a shell started in front of it.
667
+
668
+ A status read and every watchdog cycle asked the shell for their git queries, and each
669
+ paid for a shell before git ran. The answer is unchanged: standard output decoded as
670
+ UTF-8 with replacement, newlines normalised and stripped, whatever a failing git
671
+ printed there, and "" when git cannot be started or runs past the timeout.
672
+ """
673
+ argv = [git_binary(), *args]
674
+ try:
675
+ # In a process group of its own, as every Git query is: a timeout stops git with what it started (LEADS-GATE-RUNS).
676
+ merged = dict(os.environ, **env) if env else os.environ.copy()
677
+ merged.setdefault("GIT_OPTIONAL_LOCKS", "0")
678
+ result = run_as_group(argv, timeout, cwd=cwd, capture_output=True, text=True, encoding=UTF8,
679
+ errors="replace", env=bound_git_environment(merged))
680
+ except Exception:
681
+ return ""
682
+ return result.stdout.strip()
683
+
684
+
685
+ def _digest_field(digest, label, value):
686
+ """Length-frame one digest field so path/content boundaries cannot collide."""
687
+ digest.update(len(label).to_bytes(2, "big"))
688
+ digest.update(label)
689
+ digest.update(len(value).to_bytes(8, "big"))
690
+ digest.update(value)
691
+
692
+
693
+ def tree_digest(root, cfg=None):
694
+ """A staging-independent fingerprint of tracked and untracked product state.
695
+
696
+ HEAD already identifies every unchanged tracked file. We therefore hash the
697
+ current bytes, type and executable bit of each path that differs from HEAD,
698
+ plus every non-ignored untracked path. The representation is identical before
699
+ and after `git add`, including for newly added files.
700
+
701
+ polyctl's own ledgers, reviews, mail and agent coordination directories are
702
+ deliberately excluded. Verification and review must be able to persist their
703
+ evidence without immediately making that evidence stale.
704
+ """
705
+ cfg = load_config(root) if cfg is None else cfg
706
+ changed = _git_output(
707
+ root, "diff", "--name-only", "-z", "--no-renames", "HEAD", "--"
708
+ ).split(b"\0")
709
+ untracked = _git_output(
710
+ root, "ls-files", "--others", "--exclude-standard", "-z", "--"
711
+ ).split(b"\0")
712
+ paths = {
713
+ os.fsdecode(raw)
714
+ for raw in changed + untracked
715
+ if raw and not _is_coordination_path(os.fsdecode(raw), cfg)
716
+ }
717
+
718
+ digest = hashlib.sha256()
719
+ _digest_field(digest, b"format", b"polyctl-product-tree-v2")
720
+ _digest_field(digest, b"head", _git_output(root, "rev-parse", "HEAD").strip())
721
+
722
+ for rel in sorted(paths, key=os.fsencode):
723
+ full = os.path.join(root, rel)
724
+ _digest_field(digest, b"path", os.fsencode(rel))
725
+ try:
726
+ st = os.lstat(full)
727
+ except OSError:
728
+ _digest_field(digest, b"entry", b"missing")
729
+ continue
730
+
731
+ if os.path.islink(full):
732
+ _digest_field(digest, b"entry", b"symlink")
733
+ _digest_field(digest, b"target", os.fsencode(os.readlink(full)))
734
+ continue
735
+ if os.path.isfile(full):
736
+ content = hashlib.sha256()
737
+ with open(full, "rb") as fh:
738
+ for chunk in iter(lambda: fh.read(1024 * 1024), b""):
739
+ content.update(chunk)
740
+ _digest_field(digest, b"entry", b"file")
741
+ _digest_field(digest, b"executable", b"1" if st.st_mode & 0o111 else b"0")
742
+ _digest_field(digest, b"content", content.digest())
743
+ continue
744
+ if os.path.isdir(full):
745
+ # A directory here is normally a changed gitlink. Recurse so a dirty
746
+ # submodule is measured by content rather than by index state.
747
+ try:
748
+ sub = tree_digest(full, {})
749
+ except RuntimeError:
750
+ sub = "unreadable-directory"
751
+ _digest_field(digest, b"entry", b"directory")
752
+ _digest_field(digest, b"content", sub.encode(UTF8, "surrogateescape"))
753
+ continue
754
+ _digest_field(digest, b"entry", f"special:{st.st_mode}".encode())
755
+
756
+ return "sha256:" + digest.hexdigest()
757
+
758
+
759
+ CANDIDATE_FORMAT = "polyctl-index-candidate-v1"
760
+ REVIEW_EVIDENCE_PREFIX = "<!-- polyctl-evidence: "
761
+
762
+
763
+ def index_candidate(root):
764
+ """Measure the exact tree Git would commit from the active index.
765
+
766
+ ``git write-tree`` honors ``GIT_INDEX_FILE``, so this also measures the
767
+ temporary index exposed by ``git commit -a`` and path-limited commits. The
768
+ resulting tree object is immutable even if the live index changes later.
769
+ """
770
+ head = _git_output(root, "rev-parse", "HEAD").strip()
771
+ index_tree = _git_output(root, "write-tree").strip()
772
+ if not head or not index_tree:
773
+ raise RuntimeError("cannot measure index candidate: missing object id")
774
+ head_s = head.decode("ascii", "strict")
775
+ tree_s = index_tree.decode("ascii", "strict")
776
+ status = _git_output(
777
+ root, "diff-tree", "-r", "--no-commit-id", "--name-status", "-z",
778
+ "--no-renames", head_s, tree_s, "--",
779
+ )
780
+ names = _git_output(
781
+ root, "diff-tree", "-r", "--no-commit-id", "--name-only", "-z",
782
+ "--no-renames", head_s, tree_s, "--",
783
+ )
784
+ changed_paths = sorted(
785
+ {os.fsdecode(raw) for raw in names.split(b"\0") if raw}, key=os.fsencode
786
+ )
787
+ digest = hashlib.sha256()
788
+ _digest_field(digest, b"format", CANDIDATE_FORMAT.encode("ascii"))
789
+ _digest_field(digest, b"head", head)
790
+ _digest_field(digest, b"index-tree", index_tree)
791
+ _digest_field(digest, b"status", status)
792
+ return {
793
+ "format": CANDIDATE_FORMAT,
794
+ "digest": "sha256:" + digest.hexdigest(),
795
+ "head": head_s,
796
+ "index_tree": tree_s,
797
+ "changed_paths": changed_paths,
798
+ "changed_count": len(changed_paths),
799
+ "status_digest": "sha256:" + hashlib.sha256(status).hexdigest(),
800
+ }
801
+
802
+
803
+ # ---- a tree written out of the repository, for a reader that must not run what it holds (REVIEW-TREE-3) ------------
804
+
805
+ def working_tree_snapshot(root, index):
806
+ """The working tree as it stands, as a git tree object: each tracked file as it is now and each untracked one git
807
+ does not ignore, written through `index`, a file of the caller's, so the index git commits from is never touched
808
+ (CODEBASE-COPY).
809
+
810
+ A question about the code is about the code as it is, committed or not, and the index can hold a candidate the
811
+ implementer staged for review. The index's own entries are copied in first, so a tracked file that .gitignore
812
+ names is kept; `git add -A` then records every change, deletion and untracked file over them. Raises RuntimeError
813
+ naming the git step that failed.
814
+ """
815
+ entries = _git_output(root, "ls-files", "--stage", "-z")
816
+ env = dict(os.environ, GIT_INDEX_FILE=index)
817
+ written = b""
818
+ for args, given in ((("update-index", "-z", "--index-info"), entries), (("add", "-A"), b""),
819
+ (("write-tree",), b"")):
820
+ try:
821
+ done = subprocess.run([git_binary(), *args], cwd=root, env=env, input=given, capture_output=True,
822
+ timeout=300)
823
+ except (OSError, subprocess.TimeoutExpired) as exc:
824
+ raise RuntimeError(f"git {args[0]} could not run: {exc}") from exc
825
+ if done.returncode:
826
+ detail = done.stderr.decode(UTF8, "replace").strip()[:240]
827
+ raise RuntimeError(f"git {args[0]} failed: {detail or 'exit ' + str(done.returncode)}")
828
+ written = done.stdout.strip()
829
+ return written.decode("ascii", "strict")
830
+
831
+
832
+ def _lands_inside(home, name, path=os.path):
833
+ """Whether a tar member called `name` lands inside `home` once the platform has read its separators.
834
+
835
+ Judged by where the name resolves, never by its spelling: on Windows `..\\x` climbs out of the
836
+ directory, and a check that splits on '/' reads it as one harmless word.
837
+ """
838
+ root = path.realpath(home)
839
+ return path.realpath(path.join(root, name)).startswith(root.rstrip(path.sep) + path.sep)
840
+
841
+
842
+ def unpack_tree(root, tree, target):
843
+ """Write git tree `tree` of the repository at `root` into `target`, a folder this makes; `target` once the tree is
844
+ written whole, else None with nothing of `target` left (REVIEW-TREE-3).
845
+
846
+ `git archive` writes exactly the tree named, and what lands in `target` is a copy of it: no history, no index,
847
+ nothing a reader does there reaches the repository. A member naming an absolute path or a parent is dropped rather
848
+ than trusted, and so is a link, since what is unpacked comes from files an agent wrote. What any adapter declares
849
+ its harness reads from a project - `project_config` and its steering files - is not unpacked at all, wherever it
850
+ is: a harness started in a tree reads its hooks, plugins, MCP servers and instructions from there, and Claude Code
851
+ ran a SessionStart hook from a candidate's .claude/settings.json, agy the commands of its .agents/hooks.json and
852
+ OpenCode a plugin and an MCP server from .opencode/ and opencode.json, each though it only read. A member the
853
+ platform cannot write - a name longer than its file system takes, a name Windows reserves - can stop the
854
+ extraction after the members before it were written; `target` is then removed whole.
855
+
856
+ A review unpacks the candidate it pinned where its reviewer runs; `polyctl ask --codebase` unpacks the working tree
857
+ where its provider runs, and the unpacking moved here from the review's part so both make the same copy
858
+ (CODEBASE-COPY).
859
+ """
860
+ import shutil
861
+ if not tree:
862
+ return None
863
+ made = False
864
+ try:
865
+ archive = subprocess.run([git_binary(), "archive", "--format=tar", str(tree)], cwd=root,
866
+ capture_output=True, timeout=120)
867
+ if archive.returncode != 0 or not archive.stdout:
868
+ return None
869
+ import io
870
+ import tarfile
871
+ names = project_config_names()
872
+ with tarfile.open(fileobj=io.BytesIO(archive.stdout)) as tar:
873
+ safe = [member for member in tar.getmembers()
874
+ if (member.isfile() or member.isdir()) and _lands_inside(target, member.name)
875
+ and project_config_member(member.name, names) is None]
876
+ os.mkdir(target)
877
+ made = True
878
+ extra = {"filter": "data"} if hasattr(tarfile, "data_filter") else {}
879
+ tar.extractall(target, members=safe, **extra)
880
+ except Exception:
881
+ if made:
882
+ shutil.rmtree(target, ignore_errors=True)
883
+ return None
884
+ return target
885
+
886
+
887
+ def _normal_scope_paths(paths):
888
+ out = []
889
+ for value in paths or []:
890
+ raw = str(value or "").replace("\\", "/")
891
+ if not raw or raw.startswith("/") or re.match(r"^[A-Za-z]:/", raw):
892
+ raise ValueError(f"scope path must be repository-relative: {value}")
893
+ normal = os.path.normpath(raw).replace("\\", "/")
894
+ if normal in ("", ".", "..") or normal.startswith("../"):
895
+ raise ValueError(f"scope path escapes the repository: {value}")
896
+ if normal not in out:
897
+ out.append(normal)
898
+ return sorted(out, key=os.fsencode)
899
+
900
+
901
+ def _path_in_scope(path, scope_paths):
902
+ return any(path == base or path.startswith(base.rstrip("/") + "/")
903
+ for base in scope_paths)
904
+
905
+
906
+ def candidate_scope(candidate, paths=None):
907
+ """Bind a literal review scope to a candidate, rejecting staged extras."""
908
+ scope_paths = _normal_scope_paths(paths)
909
+ kind = "paths" if scope_paths else "full-index"
910
+ outside = [p for p in candidate["changed_paths"]
911
+ if scope_paths and not _path_in_scope(p, scope_paths)]
912
+ digest = hashlib.sha256()
913
+ _digest_field(digest, b"format", b"polyctl-candidate-scope-v1")
914
+ _digest_field(digest, b"candidate", candidate["digest"].encode("ascii"))
915
+ _digest_field(digest, b"kind", kind.encode("ascii"))
916
+ for path in scope_paths:
917
+ _digest_field(digest, b"path", os.fsencode(path))
918
+ return {
919
+ "kind": kind,
920
+ "paths": scope_paths,
921
+ "digest": "sha256:" + digest.hexdigest(),
922
+ "outside_paths": outside,
923
+ }
924
+
925
+
926
+ def candidate_diff(root, candidate, scope=None):
927
+ """Render the immutable staged candidate, never the mutable worktree."""
928
+ scope = scope or candidate_scope(candidate)
929
+ args = [
930
+ "--literal-pathspecs", "diff-tree", "-p", "--binary", "--full-index",
931
+ "--no-ext-diff", "--no-renames", "--no-commit-id",
932
+ candidate["head"], candidate["index_tree"], "--",
933
+ ]
934
+ args.extend(scope.get("paths") or [])
935
+ return _git_output(root, *args, timeout=60)
936
+
937
+
938
+ # ---- size is a tripwire that asks a question, not a gate that reshapes work (#34) ------
939
+
940
+ SIZE_KINDS = ("product", "tests", "fixtures", "generated", "deletion")
941
+ _GENERATED_PATH = re.compile(r"(^|/)(dist|build|generated|__generated__|vendor|node_modules)/|\.min\.(js|css)$|"
942
+ r"\.pb\.go$|_pb2\.py$|(^|/)(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|"
943
+ r"poetry\.lock|Cargo\.lock|go\.sum|uv\.lock|Gemfile\.lock)$")
944
+ _FIXTURE_PATH = re.compile(r"(^|/)(fixtures?|testdata|__snapshots__|snapshots)/|\.snap$")
945
+
946
+
947
+ def size_kind(path):
948
+ """What a changed path is, for counting: generated, fixtures, tests or product."""
949
+ path = str(path).replace("\\", "/")
950
+ if _GENERATED_PATH.search(path):
951
+ return "generated"
952
+ if _FIXTURE_PATH.search(path):
953
+ return "fixtures"
954
+ name = path.rsplit("/", 1)[-1]
955
+ if _is_test_path(path) or "__tests__" in path.split("/") or "spec" in path.split("/")[:-1] \
956
+ or re.search(r"_test\.go$|\.(test|spec)\.[cm]?[jt]sx?$", name):
957
+ return "tests"
958
+ return "product"
959
+
960
+
961
+ def candidate_size(root, candidate):
962
+ """The staged candidate's size by kind and by path, never as one number (#34).
963
+
964
+ A single total conflated 400 lines of fixtures with 400 lines of concurrency.
965
+ Lines are what git counts between HEAD and the pinned index tree; a file
966
+ whose change only removes lines is a deletion, whatever its path.
967
+ """
968
+ listed = _git_output(root, "diff-tree", "-r", "--numstat", "-z", "--no-renames",
969
+ candidate["head"], candidate["index_tree"])
970
+ kinds = {kind: {"paths": 0, "added": 0, "deleted": 0} for kind in SIZE_KINDS}
971
+ for entry in listed.split(b"\0"):
972
+ added, _, rest = entry.partition(b"\t")
973
+ deleted, _, path = rest.partition(b"\t")
974
+ if not path:
975
+ continue
976
+ plus = int(added) if added.isdigit() else 0
977
+ minus = int(deleted) if deleted.isdigit() else 0
978
+ kind = "deletion" if plus == 0 and minus > 0 else size_kind(os.fsdecode(path))
979
+ kinds[kind]["paths"] += 1
980
+ kinds[kind]["added"] += plus
981
+ kinds[kind]["deleted"] += minus
982
+ return {"paths": sum(k["paths"] for k in kinds.values()), "kinds": kinds}
983
+
984
+
985
+ def size_text(size):
986
+ """One line naming each kind that changed: paths and lines, product first."""
987
+ parts = [f"{kind} {k['paths']} path(s) +{k['added']}/-{k['deleted']}"
988
+ for kind, k in size["kinds"].items() if k["paths"]]
989
+ return ", ".join(parts) or "nothing changed"
990
+
991
+
992
+ def size_tripwire(cfg, size):
993
+ """Where a candidate's size stands against the guideline, and what that asks for (#34).
994
+
995
+ Within it, nothing. Over it, a question: the boundary must say why the slice
996
+ is one invariant that cannot be split without leaving a seam unreviewed, and
997
+ that statement goes to the reviewer. Only far above it, where no review is
998
+ credible at any length, a refusal. Generated files and pure deletions count
999
+ toward no limit.
1000
+ """
1001
+ lines = size["kinds"]["product"]["added"] + size["kinds"]["product"]["deleted"]
1002
+ paths = sum(size["kinds"][kind]["paths"] for kind in ("product", "tests", "fixtures"))
1003
+ guide_lines = settings.get(cfg, "size.guideline_product_lines")
1004
+ guide_paths = settings.get(cfg, "size.guideline_paths")
1005
+ refuse_lines = settings.get(cfg, "size.refuse_product_lines")
1006
+ measured = f"{lines} product line(s) across {paths} path(s)"
1007
+ guideline = f"the guideline is {guide_lines} product lines and {guide_paths} paths"
1008
+ if lines > refuse_lines:
1009
+ return {"state": "refuse", "lines": lines, "paths": paths, "overshoot_pct": None,
1010
+ "text": f"{measured} is far above what a review can credibly judge ({refuse_lines} product "
1011
+ f"lines, size.refuse_product_lines); {guideline}. Split it."}
1012
+ if lines <= guide_lines and paths <= guide_paths:
1013
+ return {"state": "within", "lines": lines, "paths": paths, "overshoot_pct": 0, "text": measured}
1014
+ overshoot = max(100 * (lines - guide_lines) / guide_lines, 100 * (paths - guide_paths) / guide_paths)
1015
+ return {"state": "over", "lines": lines, "paths": paths, "overshoot_pct": round(overshoot),
1016
+ "text": f"{measured} is over the guideline ({guideline})"}
1017
+
1018
+
1019
+ def one_slice_statement(item, boundary=None):
1020
+ """Why an oversized slice is one invariant, as its boundary states it (#34): a file section or `one slice:`."""
1021
+ if boundary and (boundary.get("sections") or {}).get("why one slice", "").strip():
1022
+ return boundary["sections"]["why one slice"].strip()
1023
+ return ((((item or {}).get("notes") or {}).get("one slice")) or "").strip()
1024
+
1025
+
1026
+ # What a review prompt's claims and context may take together, as review.context_bytes defaults to (REVIEW-BUDGET).
1027
+ REVIEW_CONTEXT_BUDGET = settings.default("review.context_bytes")
1028
+
1029
+
1030
+ def _is_test_path(path):
1031
+ parts = str(path).replace("\\", "/").split("/")
1032
+ name = parts[-1]
1033
+ return (any(part in ("tests", "test") for part in parts[:-1])
1034
+ or name.startswith("test_") or name.endswith("_test.py") or name == "conftest.py")
1035
+
1036
+
1037
+ def _review_definitions(root, rev, path, cache):
1038
+ """Committed definitions and static part loads: (lines, name -> (start, end), parts)."""
1039
+ import ast
1040
+ if path not in cache:
1041
+ cache[path] = None
1042
+ try:
1043
+ source = _git_output(root, "show", f"{rev}:{path}", timeout=30).decode(UTF8, "replace")
1044
+ tree = ast.parse(source)
1045
+ except (RuntimeError, SyntaxError, ValueError):
1046
+ return None
1047
+ spans = {}
1048
+ for node in tree.body:
1049
+ if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
1050
+ spans[node.name] = (min([node.lineno] + [d.lineno for d in node.decorator_list]),
1051
+ node.end_lineno)
1052
+ elif isinstance(node, (ast.Assign, ast.AnnAssign)):
1053
+ for target in (node.targets if isinstance(node, ast.Assign) else [node.target]):
1054
+ if isinstance(target, ast.Name):
1055
+ spans[target.id] = (node.lineno, node.end_lineno)
1056
+ cache[path] = (source.splitlines(), spans, top_level_statements(source)[2])
1057
+ return cache[path]
1058
+
1059
+
1060
+ def review_context(root, paths, read_rev, context_rev, budget=REVIEW_CONTEXT_BUDGET):
1061
+ """Committed source a test-only candidate exercises, for the reviewer to read (#97).
1062
+
1063
+ The candidate is what may land; this is what it is judged against. None of it
1064
+ enters the diff or the candidate digest, so supplying it widens the authority
1065
+ binding by nothing. Context is attached only when every Python file in the
1066
+ candidate is a test: a test cannot be judged without the code it runs, while
1067
+ a source change carries its own subject.
1068
+
1069
+ The tests are read at ``read_rev`` (the index tree for a staged candidate) and
1070
+ the source at ``context_rev``. A definition the tests name through an import -
1071
+ an attribute of an imported module, an imported name, or a name handed to
1072
+ ``setattr`` as a string - is copied whole, in the order the tests first name
1073
+ it, while the budget lasts. What does not fit is named, never cut, and the
1074
+ whole text, including its header and names, stays within the budget. Python only.
1075
+ """
1076
+ import ast
1077
+ if budget <= 0:
1078
+ return None
1079
+ py = [path for path in paths or [] if path.endswith(".py")]
1080
+ if not py or not all(_is_test_path(path) for path in py):
1081
+ return None
1082
+ try:
1083
+ listing = _git_output(root, "ls-tree", "-r", "--name-only", "-z", context_rev, "--")
1084
+ except RuntimeError:
1085
+ return None
1086
+ committed = {os.fsdecode(raw) for raw in listing.split(b"\0") if raw}
1087
+ refs = []
1088
+ for path in py:
1089
+ try:
1090
+ tree = ast.parse(_git_output(root, "show", f"{read_rev}:{path}", timeout=30))
1091
+ except (RuntimeError, SyntaxError, ValueError):
1092
+ continue
1093
+ modules, names = {}, {}
1094
+ for node in ast.walk(tree):
1095
+ if isinstance(node, ast.Import):
1096
+ for alias in node.names:
1097
+ modules[alias.asname or alias.name] = alias.name
1098
+ elif isinstance(node, ast.ImportFrom):
1099
+ package = path.split("/")[:-1]
1100
+ if package and package[0] == "src":
1101
+ package = package[1:]
1102
+ if node.level > len(package):
1103
+ continue
1104
+ relative = package[:len(package) - node.level + 1] if node.level else []
1105
+ module = ".".join(relative + ([node.module] if node.module else []))
1106
+ for alias in node.names:
1107
+ bound = alias.asname or alias.name
1108
+ modules[bound] = f"{module}.{alias.name}"
1109
+ names[bound] = (module, alias.name)
1110
+ for node in ast.walk(tree):
1111
+ at = (path, getattr(node, "lineno", 0), getattr(node, "col_offset", 0))
1112
+ if isinstance(node, ast.Attribute):
1113
+ parts, base = [], node
1114
+ while isinstance(base, ast.Attribute):
1115
+ parts.insert(0, base.attr)
1116
+ base = base.value
1117
+ if isinstance(base, ast.Name):
1118
+ parts.insert(0, base.id)
1119
+ for end in range(len(parts) - 1, 0, -1):
1120
+ prefix = ".".join(parts[:end])
1121
+ if prefix in modules:
1122
+ refs.append((at, modules[prefix], parts[end]))
1123
+ break
1124
+ elif isinstance(node, ast.Name) and isinstance(node.ctx, ast.Load) and node.id in names:
1125
+ refs.append((at, *names[node.id]))
1126
+ elif (isinstance(node, ast.Call) and len(node.args) >= 2
1127
+ and isinstance(node.args[0], ast.Name) and node.args[0].id in modules
1128
+ and isinstance(node.args[1], ast.Constant) and isinstance(node.args[1].value, str)):
1129
+ refs.append((at, modules[node.args[0].id], node.args[1].value))
1130
+ cache, seen, order, blocks = {}, set(), [], {}
1131
+ for _, module, name in sorted(refs):
1132
+ qualified = f"{module}.{name}"
1133
+ if qualified in seen:
1134
+ continue
1135
+ seen.add(qualified)
1136
+ base = module.replace(".", "/")
1137
+ path = next((candidate for candidate in (f"src/{base}.py", f"{base}.py",
1138
+ f"src/{base}/__init__.py", f"{base}/__init__.py")
1139
+ if candidate in committed), None)
1140
+ waiting, visited = [path] if path else [], set()
1141
+ while waiting:
1142
+ path = waiting.pop(0)
1143
+ if path in visited or path not in committed:
1144
+ continue
1145
+ visited.add(path)
1146
+ found = _review_definitions(root, context_rev, path, cache)
1147
+ if not found:
1148
+ continue
1149
+ if name in found[1]:
1150
+ break
1151
+ # polyctl's own public definitions live in statically named parts (TRIAGE-1-MEDIUM).
1152
+ waiting += [_part_file(path, part) for part in found[2]]
1153
+ else:
1154
+ continue
1155
+ start, end = found[1][name]
1156
+ order.append(qualified)
1157
+ blocks[qualified] = (path, f"# {path}:{start}-{end} {qualified}\n"
1158
+ + "\n".join(found[0][start - 1:end]) + "\n")
1159
+ files = list(dict.fromkeys(blocks[qualified][0] for qualified in order))
1160
+
1161
+ def render(kept):
1162
+ omitted = [qualified for qualified in order if qualified not in kept]
1163
+ lines = [f"committed at {context_rev[:12]}; read-only; not under review",
1164
+ "files: " + (", ".join(files) or "none resolved from the tests' imports")]
1165
+ if omitted:
1166
+ shown = []
1167
+ for qualified in omitted:
1168
+ if sum(len(name) + 2 for name in shown) + len(qualified) > 2_000:
1169
+ break
1170
+ shown.append(qualified)
1171
+ more = len(omitted) - len(shown)
1172
+ lines.append("not inlined for size, read them from the committed tree: "
1173
+ + ", ".join(shown) + (f" and {more} more" if more else ""))
1174
+ return {"rev": context_rev, "paths": files, "names": list(kept), "omitted": omitted,
1175
+ "text": "\n".join(lines) + "".join("\n\n" + blocks[q][1] for q in kept)}
1176
+
1177
+ kept, spent = [], 0
1178
+ for qualified in order:
1179
+ size = len(blocks[qualified][1].encode(UTF8)) + 2
1180
+ if spent + size <= budget:
1181
+ kept.append(qualified)
1182
+ spent += size
1183
+ result = render(kept)
1184
+ while kept and len(result["text"].encode(UTF8)) > budget:
1185
+ kept.pop()
1186
+ result = render(kept)
1187
+ if len(result["text"].encode(UTF8)) > budget:
1188
+ # Even the names can exceed a small remaining argument budget (TRIAGE-1-MEDIUM).
1189
+ result["text"] = f"committed at {context_rev[:12]}; read-only; not under review"
1190
+ if len(result["text"].encode(UTF8)) > budget:
1191
+ return None
1192
+ return result
1193
+
1194
+
1195
+ def range_end_tree(root, commits):
1196
+ """The tree a retrospective range ends on, which its reviewer reads; None where there is none (REVIEW-RANGE-TREE)."""
1197
+ if ".." not in str(commits or ""):
1198
+ return None
1199
+ end = str(commits).split("..", 1)[1].lstrip(".") or "HEAD"
1200
+ if end.startswith("-"):
1201
+ return None
1202
+ try:
1203
+ return _git_output(root, "rev-parse", "--verify", "--quiet", end + "^{tree}").decode("ascii").strip() or None
1204
+ except (RuntimeError, UnicodeError):
1205
+ return None
1206
+
1207
+
1208
+ def review_range_context(root, commits, budget=REVIEW_CONTEXT_BUDGET):
1209
+ """The same context for a retrospective range, read at the range's end commit."""
1210
+ if ".." not in commits:
1211
+ return None
1212
+ end = commits.split("..", 1)[1].lstrip(".") or "HEAD"
1213
+ if end.startswith("-"):
1214
+ return None
1215
+ try:
1216
+ rev = _git_output(root, "rev-parse", "--verify", "--quiet",
1217
+ end + "^{commit}").decode("ascii").strip()
1218
+ names = _git_output(root, "diff", "--name-only", "-z", "--no-renames", commits, "--")
1219
+ except (RuntimeError, UnicodeError):
1220
+ return None
1221
+ paths = sorted({os.fsdecode(raw) for raw in names.split(b"\0") if raw}, key=os.fsencode)
1222
+ return review_context(root, paths, rev, rev, budget)
1223
+
1224
+
1225
+ def review_context_line(context):
1226
+ files = review_header_value(", ".join(context["paths"])) \
1227
+ or "none resolved from the tests' imports"
1228
+ line = (f"- context: read-only at `{context['rev'][:12]}`: {files}; "
1229
+ f"{len(context['names'])} definitions")
1230
+ if context["omitted"]:
1231
+ line += f", {len(context['omitted'])} not inlined for size"
1232
+ return line
1233
+
1234
+
1235
+ REVIEW_CLAIMS_MAX_COMMITS = 500
1236
+ REVIEW_CLAIMS_INDENT = " "
1237
+
1238
+
1239
+ def review_range_claims(root, commits, budget=REVIEW_CONTEXT_BUDGET):
1240
+ """What the commits of a landed range say they did, for its retrospective review to verify.
1241
+
1242
+ A waived range's boundary is the owner's reason for waiving it, the same for every
1243
+ slice, while each commit message states what was wrong, what changed and what the
1244
+ tests prove. Oldest first, a message goes in whole while the budget lasts; one that
1245
+ does not fit is named by its commit and subject, never cut. Each is scanned for
1246
+ credentials as evidence is (#48). A subject is written as a review header value is
1247
+ (#55) and every body line is indented, so no line of a message starts at the margin,
1248
+ where the prompt's markers stand. The newest REVIEW_CLAIMS_MAX_COMMITS are read.
1249
+
1250
+ Returns None when `commits` is not a two-dot range git can list, otherwise commits
1251
+ (how many the range holds), inlined, subjects, redacted (the rules that hit), text and
1252
+ its digest.
1253
+ """
1254
+ commits = str(commits)
1255
+ if commits.startswith("-") or "..." in commits or ".." not in commits:
1256
+ return None
1257
+ try:
1258
+ total = int(_git_output(root, "rev-list", "--count", commits, "--").strip() or 0)
1259
+ raw = _git_output(root, "log", f"--max-count={REVIEW_CLAIMS_MAX_COMMITS}", "-z",
1260
+ "--format=%H%n%B", commits, "--")
1261
+ except (RuntimeError, ValueError):
1262
+ return None
1263
+ blocks, hits = [], set() # (commit, how a list names it, the message as the prompt holds it)
1264
+ for record in reversed(raw.split(b"\0")):
1265
+ ident, _, message = record.decode(UTF8, "replace").lstrip("\n").partition("\n")
1266
+ if not re.fullmatch(r"[0-9a-f]{40}|[0-9a-f]{64}", ident):
1267
+ continue
1268
+ message, found = scan_evidence(message)
1269
+ hits.update(found)
1270
+ lines = message.splitlines() or [""]
1271
+ body = lines[1:]
1272
+ while body and not body[0].strip():
1273
+ body.pop(0)
1274
+ while body and not body[-1].strip():
1275
+ body.pop()
1276
+ block = "\n".join([f"commit {ident[:12]} {review_header_value(lines[0])}"]
1277
+ + [REVIEW_CLAIMS_INDENT + line if line.strip() else "" for line in body])
1278
+ blocks.append((ident, f"{ident[:12]} {review_header_value(lines[0][:120])}", block))
1279
+
1280
+ def render(kept, room=2_000):
1281
+ named = [name for ident, name, _ in blocks if ident not in kept]
1282
+ missing = len(named) + max(0, total - len(blocks))
1283
+ parts = [block for ident, _, block in blocks if ident in kept]
1284
+ shown = []
1285
+ for name in named:
1286
+ if sum(len(item) + 2 for item in shown) + len(name) > room:
1287
+ break
1288
+ shown.append(name)
1289
+ if shown:
1290
+ parts.append("not inlined for size: " + "; ".join(shown)
1291
+ + (f" and {missing - len(shown)} more commit(s)" if missing > len(shown) else ""))
1292
+ elif missing:
1293
+ parts.append(f"not inlined for size: {missing} commit(s)")
1294
+ return "\n\n".join(parts)
1295
+
1296
+ def fits(text):
1297
+ return len(text.encode(UTF8)) <= budget
1298
+
1299
+ kept = {ident for ident, _, _ in blocks}
1300
+ if not fits(render(kept)):
1301
+ kept = set()
1302
+ for ident, _, _ in blocks:
1303
+ if fits(render(kept | {ident})):
1304
+ kept.add(ident)
1305
+ text = render(kept)
1306
+ if not fits(text):
1307
+ text = render(kept, room=0) # where even the names do not fit, their count stands for them
1308
+ return {"commits": total, "inlined": len(kept), "subjects": [name for _, name, _ in blocks],
1309
+ "redacted": sorted(hits), "text": text, "digest": "sha256:" + hashlib.sha256(text.encode(UTF8)).hexdigest()}
1310
+
1311
+
1312
+ def review_claims_line(claims):
1313
+ """The header line of a review told what its range's commits claim: which, and what was left out."""
1314
+ shown = claims["subjects"][:3]
1315
+ line = (f"- claims: {claims['commits']} commit message(s), given to the reviewer as claims to verify: "
1316
+ + "; ".join(shown))
1317
+ if claims["commits"] > len(shown):
1318
+ line += f" and {claims['commits'] - len(shown)} more"
1319
+ if claims["inlined"] < claims["commits"]:
1320
+ line += f"; {claims['commits'] - claims['inlined']} not inlined for size"
1321
+ if claims["redacted"]:
1322
+ line += "; redacted: " + ", ".join(claims["redacted"])
1323
+ return line
1324
+
1325
+
1326
+ # ---- gate coverage: a source tree no gate exercises (#5) ------------------------------
1327
+
1328
+ TOOLCHAINS = {
1329
+ "python": {"ext": (".py",), "runners": ("pytest", "python", "python3", "ruff", "mypy", "tox", "uv")},
1330
+ "node": {"ext": (".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs"),
1331
+ "runners": ("npm", "npx", "pnpm", "yarn", "node", "vitest", "jest", "tsc", "bun", "deno")},
1332
+ "dotnet": {"ext": (".cs", ".fs", ".vb"), "runners": ("dotnet", "msbuild")},
1333
+ "go": {"ext": (".go",), "runners": ("go",)},
1334
+ "rust": {"ext": (".rs",), "runners": ("cargo",)},
1335
+ "jvm": {"ext": (".java", ".kt", ".scala"), "runners": ("mvn", "gradle", "gradlew", "sbt")},
1336
+ "swift": {"ext": (".swift",), "runners": ("swift", "xcodebuild")},
1337
+ }
1338
+
1339
+
1340
+ def source_trees(root, minimum):
1341
+ """{top-level tree: {toolchain: files}} for every tree holding at least `minimum` of one toolchain's files.
1342
+
1343
+ Tracked and untracked-but-not-ignored files, as git lists them; files at the top
1344
+ level count as the tree ".".
1345
+ """
1346
+ try:
1347
+ listed = _git_output(root, "ls-files", "-z", "--cached", "--others", "--exclude-standard")
1348
+ except RuntimeError:
1349
+ return {}
1350
+ counts = {}
1351
+ for raw in listed.split(b"\0"):
1352
+ path = os.fsdecode(raw)
1353
+ if not path:
1354
+ continue
1355
+ tree = path.split("/", 1)[0] if "/" in path else "."
1356
+ chain = next((name for name, spec in TOOLCHAINS.items() if path.endswith(spec["ext"])), None)
1357
+ if chain:
1358
+ counts.setdefault(tree, {}).setdefault(chain, 0)
1359
+ counts[tree][chain] += 1
1360
+ return {tree: {chain: n for chain, n in chains.items() if n >= minimum}
1361
+ for tree, chains in counts.items() if any(n >= minimum for n in chains.values())}
1362
+
1363
+
1364
+ # A word of a gate's command line that launches the program after it: `python -m pytest`, `npx vitest`, `uv run pytest`.
1365
+ _GATE_LAUNCHERS = {"python": "-m", "python3": "-m", "py": "-m", "npx": None, "pnpx": None, "bunx": None, "uv": "run",
1366
+ "poetry": "run", "pipenv": "run"}
1367
+
1368
+
1369
+ def _gate_programs(run):
1370
+ """The programs a gate's command line starts: the first word of each command in it - after `&&`, `||`, `;`, `|`
1371
+ or `&`, a `NAME=value` aside - and the one a launcher such as `python -m` or `npx` starts after it, each named as
1372
+ a runner is (TRIAGE-HIGHS).
1373
+
1374
+ A runner was matched anywhere in the line, so `echo pytest` read as running pytest and covered every Python
1375
+ tree."""
1376
+ import shlex
1377
+ # Tokenize before splitting commands: a quoted separator never starts a runner (TRIAGE-2-MEDIUM).
1378
+ try:
1379
+ lexer = shlex.shlex(str(run or ""), posix=False, punctuation_chars=";&|()\n")
1380
+ lexer.whitespace = " \t\r"
1381
+ lexer.whitespace_split = True
1382
+ tokens = list(lexer)
1383
+ except ValueError:
1384
+ return set()
1385
+ found = set()
1386
+ commands, words = [], []
1387
+ for token in tokens:
1388
+ if token and all(char in ";&|()\n" for char in token):
1389
+ commands.append(words)
1390
+ words = []
1391
+ else:
1392
+ words.append(token)
1393
+ commands.append(words)
1394
+ for words in commands:
1395
+ words = [word.strip("\"'") for word in words]
1396
+ while words and re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*=.*", words[0]):
1397
+ words.pop(0)
1398
+ names = [re.sub(r"\.(exe|cmd|bat)$", "", re.split(r"[\\/]", word)[-1].lower()) for word in words]
1399
+ if not names:
1400
+ continue
1401
+ # A wrapper is itself a runner, including when flags precede its package (TRIAGE-2-MEDIUM).
1402
+ found.add(names[0])
1403
+ after = _GATE_LAUNCHERS.get(names[0], "")
1404
+ if after is None and len(names) > 1:
1405
+ found.add(names[1])
1406
+ elif after and len(names) > 2 and names[1] == after:
1407
+ found.add(names[2])
1408
+ return found
1409
+
1410
+
1411
+ def _gate_covers(gate, tree, chain):
1412
+ """Whether one gate exercises a toolchain's files in one tree: it runs that toolchain's
1413
+ runner where a command starts and, when it declares inputs, one of them reaches into the tree."""
1414
+ import fnmatch
1415
+ if not isinstance(gate, dict):
1416
+ return False # no gate polyctl reads; the doctor names the file (TRIAGE-HIGHS)
1417
+ if not _gate_programs(gate.get("run")) & set(TOOLCHAINS[chain]["runners"]):
1418
+ return False
1419
+ inputs = gate.get("inputs")
1420
+ if not isinstance(inputs, list) or not inputs:
1421
+ return True
1422
+ probe = "x" + TOOLCHAINS[chain]["ext"][0] if tree == "." else f"{tree}/x{TOOLCHAINS[chain]['ext'][0]}"
1423
+ return any(fnmatch.fnmatchcase(probe, str(glob)) or str(glob).startswith(f"{tree}/") for glob in inputs)
1424
+
1425
+
1426
+ def gate_coverage_gaps(root, spec, minimum, names=None):
1427
+ """(tree, toolchain, files) for every tree's toolchain that no gate - or none of `names` - exercises."""
1428
+ gates = spec.get("gates") if isinstance(spec, dict) else None
1429
+ gates = gates if isinstance(gates, dict) else {}
1430
+ chosen = [gate for name, gate in gates.items() if isinstance(gate, dict)
1431
+ and (names is None or name in names)]
1432
+ gaps = []
1433
+ for tree, chains in sorted(source_trees(root, minimum).items()):
1434
+ for chain, files in sorted(chains.items()):
1435
+ if not any(_gate_covers(gate, tree, chain) for gate in chosen):
1436
+ gaps.append((tree, chain, files))
1437
+ return gaps
1438
+
1439
+
1440
+ def gate_inputs(root):
1441
+ """The paths the declared gates read, as globs, or None for the whole tree (#16).
1442
+
1443
+ A gate may name its `inputs`. Only when every gate in `.polyctl/gates.json` does can
1444
+ a dirty path outside all of them be known not to reach a gate; one gate without
1445
+ inputs reads the whole tree, and so does a file that cannot be read.
1446
+ """
1447
+ try:
1448
+ with open(os.path.join(root, ".polyctl", "gates.json"), encoding=UTF8) as fh:
1449
+ spec = json.load(fh)
1450
+ except (OSError, ValueError):
1451
+ return None
1452
+ return gate_inputs_of(spec)
1453
+
1454
+
1455
+ def gate_inputs_of(spec):
1456
+ """gate_inputs of one reading of `.polyctl/gates.json`, `spec`: the one `polyctl verify` runs its gates from (TRIAGE-HIGHS).
1457
+
1458
+ Verify judged isolation by the file read again after it had waited for the machine lock: inputs narrowed
1459
+ in that wait, and put back once the run was recorded, left an untracked file a gate read out of the
1460
+ check, and the recorded digest still matched the file."""
1461
+ gates = spec.get("gates") if isinstance(spec, dict) else None
1462
+ if not isinstance(gates, dict) or not gates:
1463
+ return None
1464
+ globs = set()
1465
+ for gate in gates.values():
1466
+ declared = gate.get("inputs") if isinstance(gate, dict) else None
1467
+ if not isinstance(declared, list) or not declared \
1468
+ or not all(isinstance(item, str) and item.strip() for item in declared):
1469
+ return None
1470
+ globs.update(item.strip() for item in declared)
1471
+ return sorted(globs)
1472
+
1473
+
1474
+ def coordination_candidate(candidate, cfg):
1475
+ """Whether a staged candidate holds only coordination paths (COORDINATION-COMMIT)."""
1476
+ paths = (candidate or {}).get("changed_paths") or []
1477
+ return bool(paths) and all(_is_coordination_path(path, cfg) for path in paths)
1478
+
1479
+
1480
+ def candidate_worktree_issues(root, cfg, candidate=None, inputs="declared"):
1481
+ """State that would make gates execute bytes other than the staged candidate.
1482
+
1483
+ Only a dirty path that is part of the candidate or that a gate reads refuses (#16).
1484
+ On 2026-09-06 seven untracked files outside the slice withheld commit authority
1485
+ until a person moved them. A path no gate reads is listed as `worktree_noise`,
1486
+ never fatal; while any gate declares no inputs, every dirty path counts.
1487
+ A candidate that holds only coordination paths shares no product commit, so its
1488
+ staged coordination paths are not a product-isolation issue (COORDINATION-COMMIT).
1489
+ """
1490
+ candidate = candidate or index_candidate(root)
1491
+ if inputs == "declared":
1492
+ inputs = gate_inputs(root)
1493
+ unstaged = {
1494
+ os.fsdecode(raw)
1495
+ for raw in _git_output(
1496
+ root, "diff", "--name-only", "-z", "--no-renames", "--"
1497
+ ).split(b"\0")
1498
+ if raw and not _is_coordination_path(os.fsdecode(raw), cfg)
1499
+ }
1500
+ untracked = {
1501
+ os.fsdecode(raw)
1502
+ for raw in _git_output(
1503
+ root, "ls-files", "--others", "--exclude-standard", "-z", "--"
1504
+ ).split(b"\0")
1505
+ if raw and not _is_coordination_path(os.fsdecode(raw), cfg)
1506
+ }
1507
+ coordination = set() if coordination_candidate(candidate, cfg) else {
1508
+ path for path in candidate["changed_paths"] if _is_coordination_path(path, cfg)
1509
+ }
1510
+ if inputs is None:
1511
+ noise = set()
1512
+ else:
1513
+ import fnmatch
1514
+ mine = set(candidate["changed_paths"])
1515
+ noise = {path for path in unstaged | untracked
1516
+ if path not in mine and not any(fnmatch.fnmatchcase(path, glob) for glob in inputs)}
1517
+ return {
1518
+ "unstaged": sorted(unstaged - noise, key=os.fsencode),
1519
+ "untracked": sorted(untracked - noise, key=os.fsencode),
1520
+ "staged_coordination": sorted(coordination, key=os.fsencode),
1521
+ "worktree_noise": sorted(noise, key=os.fsencode),
1522
+ }
1523
+
1524
+
1525
+ def candidate_issue_messages(issues):
1526
+ labels = (
1527
+ ("unstaged", "unstaged product changes differ from the index"),
1528
+ ("untracked", "untracked product files are outside the index"),
1529
+ ("staged_coordination", "coordination paths must not share a product commit"),
1530
+ )
1531
+ return [f"{label}: {', '.join(issues[key])}" for key, label in labels
1532
+ if issues.get(key)]
1533
+
1534
+
1535
+ def review_evidence(body):
1536
+ """Structured evidence embedded in a human-readable review artifact."""
1537
+ for line in str(body or "").splitlines():
1538
+ if line.startswith(REVIEW_EVIDENCE_PREFIX) and line.endswith(" -->"):
1539
+ try:
1540
+ value = json.loads(line[len(REVIEW_EVIDENCE_PREFIX):-4])
1541
+ except (TypeError, ValueError):
1542
+ return None
1543
+ return value if isinstance(value, dict) else None
1544
+ return None
1545
+
1546
+
1547
+ def review_evidence_line(value):
1548
+ return REVIEW_EVIDENCE_PREFIX + json.dumps(
1549
+ value, ensure_ascii=True, sort_keys=True, separators=(",", ":")
1550
+ ) + " -->"
1551
+
1552
+
1553
+ def review_header_value(value):
1554
+ """One header value on one line, whatever the implementer or the config supplied (#55).
1555
+
1556
+ A review artefact's header echoes the boundary, the commit range, labels and
1557
+ file names. A value holding a line break, or any other character
1558
+ ``str.splitlines`` breaks on (``\\x1c``, ``\\x85``, ``\\u2028`` ...), would start a
1559
+ line of its own, and a line reading ``VERDICT: APPROVED`` there is a verdict to
1560
+ every reader. Such a value is written as a JSON string; a printable one as it is.
1561
+ """
1562
+ text = str(value)
1563
+ return text if text.isprintable() else json.dumps(text, ensure_ascii=True)
1564
+
1565
+
1566
+ REVIEWER_OUTPUT_HEADING = "## Reviewer output, verbatim"
1567
+ REVIEWER_OUTPUT_INDENT = " "
1568
+
1569
+
1570
+ def review_verbatim_lines(text):
1571
+ """The reviewer's own output for the artefact, below polyctl's adjudication (#54).
1572
+
1573
+ Indented, so none of its lines starts at the margin, where the verdict and the
1574
+ evidence line are read. It is split with the ``splitlines`` those readers use,
1575
+ so a separator inside a line cannot lift the rest of it back to the margin.
1576
+ """
1577
+ return ["", REVIEWER_OUTPUT_HEADING, ""] + [
1578
+ REVIEWER_OUTPUT_INDENT + line if line else ""
1579
+ for line in str(text or "").splitlines()
1580
+ ]
1581
+
1582
+
1583
+ def candidate_review_integrity(root, candidate, evidence):
1584
+ """Return the canonical reviewed scope and any exact-candidate refusals."""
1585
+ reasons = []
1586
+ if not isinstance(evidence, dict):
1587
+ return None, ["review evidence is not a structured object"]
1588
+ if evidence.get("candidate") != candidate:
1589
+ reasons.append(
1590
+ "review evidence candidate does not exactly match the current index candidate"
1591
+ )
1592
+
1593
+ recorded_scope = evidence.get("scope")
1594
+ if not isinstance(recorded_scope, dict):
1595
+ reasons.append("review evidence has no structured candidate scope")
1596
+ return None, reasons
1597
+ paths = recorded_scope.get("paths")
1598
+ if not isinstance(paths, list):
1599
+ reasons.append("review evidence candidate scope paths must be a list")
1600
+ return None, reasons
1601
+ try:
1602
+ scope = candidate_scope(candidate, paths)
1603
+ except (KeyError, TypeError, ValueError, UnicodeError) as exc:
1604
+ reasons.append(f"review evidence has an invalid candidate scope: {exc}")
1605
+ return None, reasons
1606
+
1607
+ if scope["outside_paths"]:
1608
+ reasons.append(
1609
+ "review evidence scope excludes staged paths: "
1610
+ + ", ".join(scope["outside_paths"])
1611
+ )
1612
+ if recorded_scope != scope:
1613
+ reasons.append(
1614
+ "review evidence scope does not exactly match the current candidate"
1615
+ )
1616
+
1617
+ try:
1618
+ diff_digest = "sha256:" + hashlib.sha256(
1619
+ candidate_diff(root, candidate, scope)
1620
+ ).hexdigest()
1621
+ except (KeyError, OSError, RuntimeError, TypeError, ValueError, UnicodeError) as exc:
1622
+ reasons.append(f"review evidence candidate diff cannot be reproduced: {exc}")
1623
+ else:
1624
+ if evidence.get("diff_digest") != diff_digest:
1625
+ reasons.append(
1626
+ "review evidence diff digest does not match the exact candidate diff: "
1627
+ f"expected {diff_digest}, got {evidence.get('diff_digest') or '<missing>'}"
1628
+ )
1629
+ return scope, reasons
1630
+
1631
+
1632
+ # ---- a boundary's criteria, each with a verdict of its own (CRITERIA-VERDICTS) ---------
1633
+
1634
+ # The line a reviewer gives one criterion, spelled the same in every language because polyctl reads it back:
1635
+ # `CRITERION <n>: MET` or `CRITERION <n>: NOT MET`, then its evidence. A list bullet and bold are allowed.
1636
+ CRITERION_ANSWER = re.compile(r"""
1637
+ (?:[-*][ \t]+)? # a list bullet
1638
+ (?:\*\*)?CRITERION[ \t]+(\d{1,3})[ \t]*:(?:\*\*)?[ \t]*
1639
+ (?:\*\*)?(NOT[ \t]+MET|MET)(?:\*\*)?(?!\w)
1640
+ [ \t]*[—–:-]*[ \t]*(.*) # the evidence, after a dash or a colon
1641
+ """, re.I | re.X)
1642
+ CRITERION_EVIDENCE_CHARS = 300
1643
+ CRITERION_UNSUPPORTED = "it was said to be met with no evidence"
1644
+
1645
+
1646
+ def criterion_verdicts(criteria, answers):
1647
+ """Each criterion with what a review's answers found of it: met, not met, or no verdict (None).
1648
+
1649
+ `answers` are the reviewer's own words: a review's one answer, or each of its
1650
+ sections'. A criterion's line counts only at the margin, where the verdict and the
1651
+ counts are read, so an indented line - a quotation, an example - decides nothing. A
1652
+ MET line that gives no evidence is no verdict, since the evidence is what the line is
1653
+ for, and the record says so. Across the sections of one review a criterion is met
1654
+ when a section judged it and none found it not met: a scenario's section judges its
1655
+ own, and one section's NOT MET stands however many others found it met.
1656
+ """
1657
+ from .verdicts import CriterionVerdict
1658
+ said = {str(criterion.get("id")): [] for criterion in criteria}
1659
+ for answer in answers:
1660
+ for line in str(answer or "").splitlines():
1661
+ found = None if line[:1].isspace() else CRITERION_ANSWER.fullmatch(line.rstrip())
1662
+ if not found or str(int(found.group(1))) not in said:
1663
+ continue
1664
+ evidence = found.group(3).strip()[:CRITERION_EVIDENCE_CHARS]
1665
+ if found.group(2).upper() != "MET":
1666
+ verdict = CriterionVerdict.NOT_MET.value
1667
+ elif evidence:
1668
+ verdict = CriterionVerdict.MET.value
1669
+ else:
1670
+ verdict, evidence = None, CRITERION_UNSUPPORTED
1671
+ said[str(int(found.group(1)))].append((verdict, evidence))
1672
+ # Not met outranks met, and met outranks a line that was no verdict; among equals the first line said stands.
1673
+ rank = (CriterionVerdict.NOT_MET.value, CriterionVerdict.MET.value, None)
1674
+ out = []
1675
+ for criterion in criteria:
1676
+ heard = sorted(said[str(criterion.get("id"))], key=lambda entry: rank.index(entry[0]))
1677
+ verdict, evidence = heard[0] if heard else (None, "")
1678
+ out.append({"id": criterion.get("id"), "text": criterion.get("text"), "verdict": verdict,
1679
+ "evidence": evidence})
1680
+ return out
1681
+
1682
+
1683
+ def criteria_refusals(evidence):
1684
+ """Each criterion of a review that keeps it from authorising, named: not met, or with no verdict.
1685
+
1686
+ What the review recorded is read, never worked out again from the boundary, which
1687
+ may have moved since. A review of a boundary that lists no criteria records none,
1688
+ and nothing is refused here: a single sentence grants as it always did.
1689
+ """
1690
+ from .verdicts import CriterionVerdict
1691
+ criteria = evidence.get("criteria") if isinstance(evidence, dict) else None
1692
+ if criteria is None:
1693
+ return []
1694
+ if not isinstance(criteria, list) or not all(isinstance(criterion, dict) for criterion in criteria):
1695
+ return ["review evidence records criteria that are not a list of criteria"]
1696
+ out = []
1697
+ for criterion in criteria:
1698
+ verdict = criterion.get("verdict")
1699
+ if verdict == CriterionVerdict.MET.value:
1700
+ continue
1701
+ state = "is not met" if verdict == CriterionVerdict.NOT_MET.value else "has no verdict"
1702
+ why = f" — {criterion['evidence']}" if criterion.get("evidence") else ""
1703
+ out.append(review_header_value(f"criterion {criterion.get('id')} {state}: {criterion.get('text')}{why}"))
1704
+ return out
1705
+
1706
+
1707
+ def review_criteria_lines(criteria):
1708
+ """The artefact's header line for each criterion: its number and words, its verdict, the reviewer's evidence."""
1709
+ return [f"- criterion {criterion['id']} ({review_header_value(criterion['text'])}): "
1710
+ + review_header_value((criterion["verdict"] or "no verdict")
1711
+ + (f" — {criterion['evidence']}" if criterion["evidence"] else ""))
1712
+ for criterion in criteria or []]
1713
+
1714
+
1715
+ REVIEW_CHAIN = "polyctl-review-row-v1"
1716
+
1717
+
1718
+ def review_requests_dir(root, key=None):
1719
+ """Where a project's stand-in review requests are kept: ~/.polyctl/review-requests/<project>/, outside the tree an agent
1720
+ writes, named by `key` or the project's key (REVIEW-PATH-HIGHS).
1721
+
1722
+ A request binds a person's carried answer to the candidate it was made for, and holds the text the person carries
1723
+ to a session. In .polyctl/review-requests/ both were the implementer's to rewrite: a `candidate` turned to bytes it
1724
+ staged after had a person's genuine approval recorded for bytes no session was shown, emptied `criteria` let it
1725
+ land past a criterion the session found not met, and a text changed while a person copied it had the session judge
1726
+ another diff than the one polyctl bound.
1727
+ """
1728
+ return os.path.join(HOME, ".polyctl", "review-requests", key or project_key(root))
1729
+
1730
+
1731
+ def tree_review_request(root, nonce):
1732
+ """Whether the tree holds a request by this nonce where polyctl kept them before REVIEW-PATH-HIGHS; one found there is
1733
+ named, never read."""
1734
+ return bool(re.fullmatch(r"[0-9a-f]{32}", str(nonce or ""))) and os.path.lexists(
1735
+ os.path.join(root, ".polyctl", "review-requests", f"{nonce}.json"))
1736
+
1737
+
1738
+ STANDIN_LIMITS = (
1739
+ "polyctl cannot verify which model wrote this answer; it records the model the person declared",
1740
+ "a same-user actor could have written the answer; the nonce binds it to one candidate, nothing more",
1741
+ )
1742
+
1743
+
1744
+ def write_review_request(root, cfg, candidate, scope, diff_digest, boundary, slice_id, paths, prompt,
1745
+ criteria=None, threat_model=None, boundary_file=None):
1746
+ """A review request a person can carry to a session polyctl cannot reach (#75).
1747
+
1748
+ Written when no reviewer could be reached for a staged candidate: the prompt the
1749
+ reviewer would have received - as `polyctl review` hands it here, without the note about
1750
+ a tree the session a person carries it to does not hold (REVIEW-TREE-2) - and a
1751
+ nonce the answer must lead with, asked for in the project's language
1752
+ (LANGUAGE-PROMPTS). The metadata beside it binds the request to that candidate, and
1753
+ keeps the criteria the prompt asks about, if any: the answer is read against those
1754
+ when it is collected, although the boundary kept beside them is only a boundary
1755
+ file's name (CRITERIA-VERDICTS).
1756
+
1757
+ Both are kept outside the tree (review_requests_dir), and the metadata holds the digest of the text: a collect
1758
+ reads the binding from there alone, and the text a person carries is the one polyctl wrote (REVIEW-PATH-HIGHS).
1759
+ """
1760
+ import secrets
1761
+ from .storage import replace_file_durably
1762
+ nonce = secrets.token_hex(16)
1763
+ directory = review_requests_dir(root)
1764
+ text = (f"# polyctl review request {nonce}\n\n"
1765
+ "No reviewer could be reached for the staged candidate below. Paste everything\n"
1766
+ "under the line into a session running a different model family from the\n"
1767
+ "implementer's, save its whole answer to a file, and then a person runs:\n\n"
1768
+ f" polyctl collect-review {nonce} --response <file> --model <the model that answered> --by <your name>\n\n"
1769
+ f"The request binds to candidate `{candidate['digest']}`; if the staged bytes change,\n"
1770
+ "it no longer applies.\n\n---\n\n"
1771
+ + language.text(cfg, "prompt.review-request", nonce=nonce) + f"\n\n{prompt}\n").encode(UTF8)
1772
+ meta = {"nonce": nonce, "at": int(time.time()), "candidate": candidate["digest"],
1773
+ "index_tree": candidate["index_tree"], "scope": scope, "diff_digest": diff_digest,
1774
+ "boundary": boundary, "slice": slice_id, "paths": paths, "collected": None,
1775
+ "text": "sha256:" + hashlib.sha256(text).hexdigest()}
1776
+ if boundary_file:
1777
+ meta["boundary_file"] = boundary_file
1778
+ if criteria:
1779
+ meta["criteria"] = criteria
1780
+ if threat_model:
1781
+ meta["threat_model"] = threat_model # the one its prompt carries, which an answer is judged under
1782
+ path = os.path.join(directory, f"{nonce}.md")
1783
+ replace_file_durably(os.path.join(directory, f"{nonce}.json"),
1784
+ json.dumps(meta, indent=1, sort_keys=True).encode(UTF8))
1785
+ replace_file_durably(path, text)
1786
+ return dict(meta, path=path)
1787
+
1788
+
1789
+ def review_request(root, nonce):
1790
+ """A request's metadata by its nonce, or None."""
1791
+ if not re.fullmatch(r"[0-9a-f]{32}", str(nonce or "")):
1792
+ return None
1793
+ try:
1794
+ with open(os.path.join(review_requests_dir(root), f"{nonce}.json"), encoding=UTF8) as fh:
1795
+ data = json.load(fh)
1796
+ except (OSError, ValueError):
1797
+ return None
1798
+ return data if isinstance(data, dict) and data.get("nonce") == nonce else None
1799
+
1800
+
1801
+ def mark_review_request_collected(root, nonce, artefact, by):
1802
+ """A request answers once: record which artefact its answer became and who carried it."""
1803
+ from .storage import replace_file_durably
1804
+ meta = review_request(root, nonce)
1805
+ if meta is None:
1806
+ return None
1807
+ meta["collected"] = {"at": int(time.time()), "artefact": artefact, "by": by}
1808
+ replace_file_durably(os.path.join(review_requests_dir(root), f"{nonce}.json"),
1809
+ json.dumps(meta, indent=1, sort_keys=True).encode(UTF8))
1810
+ return meta
1811
+
1812
+
1813
+ def review_ledger_path(root):
1814
+ return os.path.join(root, ".polyctl", "ledger", "reviews.jsonl")
1815
+
1816
+
1817
+ def review_artefact_name(root, reviews_dir, head):
1818
+ """A review artefact name no earlier review has, so no record points at a rewritten file."""
1819
+ stem = f"{datetime.now():%Y-%m-%d-%H%M%S}-{head}"
1820
+ name, n = f"{stem}.md", 2
1821
+ while os.path.lexists(os.path.join(root, reviews_dir, name)):
1822
+ name, n = f"{stem}-{n}.md", n + 1
1823
+ return name
1824
+
1825
+
1826
+ def record_review(root, name, data, evidence, verdict, reviewer=None, fallback=False):
1827
+ """Append one review to the chained review ledger: which file, which bytes, what it decided (#63)."""
1828
+ from .storage import append_chained_jsonl
1829
+ evidence = evidence if isinstance(evidence, dict) else {}
1830
+ candidate = evidence.get("candidate") if isinstance(evidence.get("candidate"), dict) else {}
1831
+ row = {
1832
+ "at": int(time.time()),
1833
+ "artefact": name,
1834
+ "sha256": "sha256:" + hashlib.sha256(data).hexdigest(),
1835
+ "kind": evidence.get("kind"),
1836
+ "candidate": candidate.get("digest"),
1837
+ "verdict": verdict,
1838
+ "authorizable": evidence.get("authorizable") is True,
1839
+ "fallback": bool(fallback),
1840
+ "reviewer": reviewer,
1841
+ "slice": evidence.get("slice"),
1842
+ }
1843
+ if row["kind"] == "commit-range":
1844
+ row["commits"] = evidence.get("commits")
1845
+ if evidence.get("author") is not None:
1846
+ # Whose range a catch-up reviewed it as, so its waiver closes on its own review (CATCHUP-READY-2).
1847
+ row["author"] = evidence["author"]
1848
+ if evidence.get("review_tier"):
1849
+ # The tier the review stands in, so a grant, `polyctl reviews` and `polyctl stats` label it (REVIEW-TIERS).
1850
+ row["tier"] = evidence["review_tier"]
1851
+ if evidence.get("nonce"):
1852
+ # The request a carried answer came back for, so a collect cut off before it marked the request finds
1853
+ # the review it already recorded (JOURNAL-7).
1854
+ row["nonce"] = evidence["nonce"]
1855
+ return append_chained_jsonl(review_ledger_path(root), row, REVIEW_CHAIN)
1856
+
1857
+
1858
+ def write_review_artefact(root, reviews_dir, name, text, *, evidence, verdict,
1859
+ reviewer=None, fallback=False):
1860
+ """Record a review, then write exactly the recorded bytes, whole (#63, #65).
1861
+
1862
+ The row comes first. A write that dies after it leaves a newest review that
1863
+ cannot be read, and that refuses; written first, a file whose row was never
1864
+ appended left the older recorded approval of the candidate deciding (audit).
1865
+
1866
+ Returns the row as the ledger holds it, so the caller knows which review is its own: one found by
1867
+ counting the rows before it could be a review of the same bytes that ran beside it (LEADS-REVIEW).
1868
+ """
1869
+ from .storage import replace_file_durably
1870
+ directory = os.path.join(root, reviews_dir)
1871
+ os.makedirs(directory, exist_ok=True)
1872
+ data = scan_evidence(text)[0].encode(UTF8) # scanned before it is recorded or written (#48)
1873
+ row = record_review(root, name, data, evidence, verdict, reviewer=reviewer, fallback=fallback)
1874
+ replace_file_durably(os.path.join(directory, name), data)
1875
+ return row
1876
+
1877
+
1878
+ # ---- review artefacts: kept while anything rests on them, pruned by age (#38) ----------
1879
+
1880
+ # Files whose text names the review artefacts they rest on, and what each one is.
1881
+ REVIEW_REFERENCE_FILES = (
1882
+ ("grant", (".polyctl", "ledger", "authority.jsonl")),
1883
+ ("verification", (".polyctl", "ledger", "verifications.jsonl")),
1884
+ ("board", (".polyctl", "board.md")),
1885
+ ("waiver", (".polyctl", "ledger", "waivers.jsonl")),
1886
+ ("decision", (".polyctl", "ledger", "decisions.jsonl")),
1887
+ )
1888
+
1889
+
1890
+ # ---- a merge is verified on its result, before it is made (#39) ------------------------
1891
+
1892
+ MERGE_CHAIN = "polyctl-merge-check-row-v1"
1893
+
1894
+
1895
+ def merge_checks_path(root):
1896
+ return os.path.join(root, ".polyctl", "ledger", "merges.jsonl")
1897
+
1898
+
1899
+ def merge_checks(root):
1900
+ """Recorded runs of merge results, oldest first; raises on a broken chain."""
1901
+ from .storage import read_chained_jsonl
1902
+ return [row for row in read_chained_jsonl(merge_checks_path(root), MERGE_CHAIN) if isinstance(row, dict)]
1903
+
1904
+
1905
+ def record_merge_check(root, row):
1906
+ from .storage import append_chained_jsonl
1907
+ return append_chained_jsonl(merge_checks_path(root), scan_record(row), MERGE_CHAIN)
1908
+
1909
+
1910
+ def merge_result_tree(root, into, branch):
1911
+ """(tree, conflict): the tree `git merge` would make of two commits, computed without touching a worktree.
1912
+
1913
+ RuntimeError when git cannot compute it at all (merge-tree --write-tree needs git 2.38).
1914
+ """
1915
+ try:
1916
+ # In a process group of its own, as every Git query of authority's is: a merge driver the repository
1917
+ # configures can start a worker that holds git's pipes past its time (LEADS-GATE).
1918
+ result = run_as_group([git_binary(), "merge-tree", "--write-tree", "--name-only", "--no-messages",
1919
+ into, branch], 120, cwd=root, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
1920
+ except (OSError, subprocess.TimeoutExpired) as exc:
1921
+ unasked = getattr(exc, "unasked", None)
1922
+ raise RuntimeError(f"cannot compute the merge: {exc}" + (f"; {unasked}" if unasked else "")) from exc
1923
+ lines = result.stdout.decode(UTF8, "replace").splitlines()
1924
+ if result.returncode == 0 and lines:
1925
+ return lines[0].strip(), None
1926
+ if result.returncode == 1 and lines:
1927
+ return None, "conflicts in " + ", ".join(line.strip() for line in lines[1:] if line.strip())
1928
+ detail = result.stderr.decode(UTF8, "replace").strip()
1929
+ raise RuntimeError(f"cannot compute the merge: {detail or f'git merge-tree exit {result.returncode}'}")
1930
+
1931
+
1932
+ def unverified_merges(root, cfg):
1933
+ """(merge commit, why) for each recent merge on HEAD's first-parent line no passing run vouches for (#39).
1934
+
1935
+ A run vouches for a merge only when it names both parents and the tree the
1936
+ merge made, so a run of an older pair, or of a result that was changed while
1937
+ merging, vouches for nothing.
1938
+ """
1939
+ days = settings.get(cfg, "merge.check_days")
1940
+ log = git_text(root, "log", "--merges", "--first-parent", f"--since={days}.days", "--format=%H %T %P", "HEAD")
1941
+ runs = {(row.get("into"), row.get("branch"), row.get("tree")): row for row in merge_checks(root)}
1942
+ out = []
1943
+ for line in log.splitlines():
1944
+ parts = line.split()
1945
+ if len(parts) < 4:
1946
+ continue
1947
+ sha, tree, first, second = parts[:4]
1948
+ run = runs.get((first, second, tree))
1949
+ if run is None:
1950
+ out.append((sha, "no run of its merge result was recorded"))
1951
+ elif run.get("passed") is not True:
1952
+ out.append((sha, f"the recorded run of its merge result, {run.get('id')}, failed"))
1953
+ else:
1954
+ try:
1955
+ spec = json.loads(_git_output(root, "show", f"{tree}:.polyctl/gates.json"))
1956
+ digest = gate_definitions_digest_of(spec, run.get("profile"))
1957
+ except (OSError, ValueError, RuntimeError, TypeError, AttributeError) as exc:
1958
+ out.append((sha, f"the merge's gate definitions cannot be read: {exc}; run merge-check again"))
1959
+ continue
1960
+ if not digest or run.get("gates_digest") != digest:
1961
+ out.append((sha, "the recorded run used different gate definitions; run merge-check again"))
1962
+ return out
1963
+
1964
+
1965
+ def _review_artefact_directory(root, reviews_dir):
1966
+ """Pruning follows no directory link and never leaves the project (TRIAGE-3-MEDIUM)."""
1967
+ base = os.path.abspath(root)
1968
+ directory = os.path.abspath(os.path.join(base, reviews_dir))
1969
+ if not _within(directory, base) or directory == base:
1970
+ raise RuntimeError("review directory leaves the project; configure a directory inside it before pruning")
1971
+ part = directory
1972
+ while part != base:
1973
+ if os.path.islink(part):
1974
+ raise RuntimeError("review directory contains a link; replace it with a directory before pruning")
1975
+ parent = os.path.dirname(part)
1976
+ if parent == part:
1977
+ raise RuntimeError("review directory leaves the project; correct it before pruning")
1978
+ part = parent
1979
+ return directory
1980
+
1981
+
1982
+ def review_artefact_names(root, reviews_dir):
1983
+ """The regular review files on disk, excluding links (TRIAGE-3-MEDIUM)."""
1984
+ import stat
1985
+ directory = _review_artefact_directory(root, reviews_dir)
1986
+ try:
1987
+ return sorted(name for name in os.listdir(directory)
1988
+ if not name.startswith(".") and stat.S_ISREG(os.lstat(os.path.join(directory, name)).st_mode))
1989
+ except FileNotFoundError:
1990
+ return []
1991
+
1992
+
1993
+ def tracked_review_names(root, reviews_dir):
1994
+ """The review artefacts git tracks, by name; RuntimeError when git cannot say."""
1995
+ listed = _git_output(root, "ls-files", "-z", "--", reviews_dir)
1996
+ return {os.path.basename(os.fsdecode(path)) for path in listed.split(b"\0") if path}
1997
+
1998
+
1999
+ def review_artefact_references(root, cfg):
2000
+ """{artefact: [what rests on it]} for every review artefact polyctl must keep (#38).
2001
+
2002
+ A grant, a verification, the board, a waiver or a decision that names the
2003
+ file; a submitted review's state; a review of a slice that is neither done nor
2004
+ rejected, or of the candidate staged now; and a file git tracks, which moving
2005
+ would turn into a deletion in the tree. The review ledger is the catalogue of
2006
+ every review, not a reason to keep one. Whatever cannot be read raises, so
2007
+ nothing is pruned on a guess.
2008
+ """
2009
+ from .storage import read_chained_history
2010
+ names = review_artefact_names(root, cfg["reviews"])
2011
+ kept = {}
2012
+
2013
+ def keep(name, why):
2014
+ reasons = kept.setdefault(name, [])
2015
+ if why not in reasons:
2016
+ reasons.append(why)
2017
+
2018
+ texts = []
2019
+ chains = {"grant": (AUTHORITY_CHAIN, False), "verification": (VERIFICATION_CHAIN, True),
2020
+ "waiver": (WAIVER_CHAIN, True), "decision": (DECISION_CHAIN, True)}
2021
+ for why, parts in REVIEW_REFERENCE_FILES:
2022
+ if why in chains:
2023
+ chain, legacy = chains[why]
2024
+ rows = read_chained_history(os.path.join(root, *parts), chain, legacy_prefix=legacy)
2025
+ texts.append((why, json.dumps(rows, ensure_ascii=False)))
2026
+ continue
2027
+ try:
2028
+ with open(os.path.join(root, *parts), encoding=UTF8, errors="replace") as fh:
2029
+ texts.append((why, fh.read()))
2030
+ except FileNotFoundError:
2031
+ continue
2032
+ states = os.path.join(root, ".polyctl", "reviews")
2033
+ for entry in sorted(os.listdir(states)) if os.path.isdir(states) else []:
2034
+ if entry.startswith("R-") and entry.endswith(".json"):
2035
+ with open(os.path.join(states, entry), encoding=UTF8, errors="replace") as fh:
2036
+ texts.append(("submitted review", fh.read()))
2037
+ for why, text in texts:
2038
+ for name in names:
2039
+ if name in text:
2040
+ keep(name, why)
2041
+ open_slices = {item["id"] for state, items in board(root).items() if state not in ("done", "rejected")
2042
+ for item in items}
2043
+ staged = index_candidate(root)["digest"]
2044
+ for row in read_chained_history(review_ledger_path(root), REVIEW_CHAIN):
2045
+ name = row.get("artefact") if isinstance(row, dict) else None
2046
+ if name not in names:
2047
+ continue
2048
+ if row.get("slice") in open_slices:
2049
+ keep(name, "open slice")
2050
+ if staged and row.get("candidate") == staged:
2051
+ keep(name, "staged candidate")
2052
+ tracked = tracked_review_names(root, cfg["reviews"])
2053
+ for name in names:
2054
+ if name in tracked:
2055
+ keep(name, "tracked in git")
2056
+ return kept
2057
+
2058
+
2059
+ def prune_review_artefacts(root, cfg, days, apply=False, now=None):
2060
+ """Move the review artefacts nothing rests on, older than `days`, out of the repository (#38).
2061
+
2062
+ Age is the later of the file's time and its ledger row's, so neither alone
2063
+ makes a review old. They move to ~/.polyctl/archive/<project>/, not away: a review
2064
+ is evidence someone may still ask for. Returns what was kept and why, how many
2065
+ were recent, what was moved (or would be), its bytes and where it went.
2066
+ """
2067
+ import shutil
2068
+ import stat
2069
+ from .storage import read_chained_history
2070
+ now = time.time() if now is None else now
2071
+ kept = review_artefact_references(root, cfg)
2072
+ written = {}
2073
+ for row in read_chained_history(review_ledger_path(root), REVIEW_CHAIN):
2074
+ if isinstance(row, dict) and row.get("artefact"):
2075
+ written[row["artefact"]] = max(written.get(row["artefact"], 0), int(row.get("at") or 0))
2076
+ directory = os.path.join(root, cfg["reviews"])
2077
+ cutoff = now - days * 86400
2078
+ recent, moving, size = 0, [], 0
2079
+ for name in review_artefact_names(root, cfg["reviews"]):
2080
+ if name in kept:
2081
+ continue
2082
+ path = os.path.join(directory, name)
2083
+ if max(os.path.getmtime(path), written.get(name, 0)) >= cutoff:
2084
+ recent += 1
2085
+ else:
2086
+ moving.append(name)
2087
+ size += os.path.getsize(path)
2088
+ folder = f"{os.path.basename(os.path.normpath(cfg['reviews']))}-{datetime.fromtimestamp(now):%Y%m%d-%H%M%S}"
2089
+ archive = os.path.join(HOME, ".polyctl", "archive", project_key(root), folder)
2090
+ if apply and moving:
2091
+ os.makedirs(archive, exist_ok=True)
2092
+ for name in moving:
2093
+ # Recheck after reading the references, before each move (TRIAGE-3-MEDIUM).
2094
+ directory = _review_artefact_directory(root, cfg["reviews"])
2095
+ if not stat.S_ISREG(os.lstat(os.path.join(directory, name)).st_mode):
2096
+ raise RuntimeError("review artefacts changed during pruning; inspect them and retry")
2097
+ shutil.move(os.path.join(directory, name), os.path.join(archive, name))
2098
+ record_archived(root, name, archive) # where it went stays on the record (#47)
2099
+ return {"kept": kept, "recent": recent, "moved": moving, "bytes": size, "archive": archive}