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,2933 @@
1
+ """Roles and adapters: the role table, adapter layers, the vendor list and profiles, composed
2
+ reviewers.
3
+
4
+ A part of src/polyctl/lib.py (#44): moved out byte for byte and run in its namespace by `_part`,
5
+ where it stood; it is not importable on its own.
6
+ """
7
+
8
+
9
+ # ---- the role table is real, and messages are addressed to roles (#79, #31) -------------
10
+
11
+ ROLE_BLOCKS = ("implementer", "architect", "reviewer")
12
+
13
+
14
+ def effective_roles(root, cfg):
15
+ """The role → actor assignment in force: `roles`, or `roles_next` once the slice it waits on left running (#79)."""
16
+ roles = dict(cfg.get("roles") or {})
17
+ pending = cfg.get("roles_next")
18
+ if isinstance(pending, dict) and isinstance(pending.get("roles"), dict):
19
+ running = {item["id"] for item in board(root)["running"]} if root else set()
20
+ if pending.get("after") not in running:
21
+ roles.update(pending["roles"])
22
+ return roles
23
+
24
+
25
+ def pending_roles(root, cfg):
26
+ """(the roles `roles_next` assigns that still wait for their slice to leave running, that slice), or ({}, None).
27
+
28
+ Until the slice leaves, every reader sees each role as it was, and a role nobody held
29
+ reads as unconfigured: rehearsing the catch-up planned for 2026-10-01, a reviewer named
30
+ while a slice ran left catch-up saying that no reviewer was configured (OCT1-FIXES).
31
+ """
32
+ pending = cfg.get("roles_next")
33
+ if not isinstance(pending, dict) or not isinstance(pending.get("roles"), dict) or not root:
34
+ return {}, None
35
+ if pending.get("after") not in {item["id"] for item in board(root)["running"]}:
36
+ return {}, None
37
+ return dict(pending["roles"]), pending.get("after")
38
+
39
+
40
+ def resolve_roles(root, cfg):
41
+ """Fill each role's block from the actor table, when the project keeps one (#79).
42
+
43
+ `docs/roles.md` described actors, roles and `polyctl role set` long before any of it
44
+ existed. The table lives in `.polyctl/config.json` as `actors` and `roles`; every
45
+ reader keeps reading the role blocks it always read, now resolved from it.
46
+ """
47
+ actors = cfg.get("actors")
48
+ if not isinstance(actors, dict) or not isinstance(cfg.get("roles"), dict):
49
+ return cfg
50
+ for role, actor in effective_roles(root, cfg).items():
51
+ if role in ROLE_BLOCKS and isinstance(actors.get(actor), dict):
52
+ cfg[role] = dict(actors[actor], actor=actor)
53
+ return cfg
54
+
55
+
56
+ def role_table(cfg):
57
+ """(actors, roles, pending) as configured, or bootstrapped from the role blocks when there is no table yet."""
58
+ actors = {name: dict(block) for name, block in (cfg.get("actors") or {}).items() if isinstance(block, dict)}
59
+ roles = dict(cfg.get("roles") or {})
60
+ if not actors:
61
+ for role in ROLE_BLOCKS:
62
+ block = cfg.get(role)
63
+ if isinstance(block, dict) and block:
64
+ name = str(block.get("actor") or block.get("name") or block.get("id") or role)
65
+ actors[name] = {key: value for key, value in block.items() if key != "actor"}
66
+ roles[role] = name
67
+ return actors, roles, cfg.get("roles_next")
68
+
69
+
70
+ def assignment_problem(actors, roles, repository="tool", hotfix=False):
71
+ """Why an assignment would break separation of duties, or None (#79, #13).
72
+
73
+ Roles may rotate per slice on a tool repository. On a product repository the
74
+ architect does not implement, except a hotfix a person names as one. Wherever
75
+ roles stand, the reviewer is never the implementer's actor. Whether it may review
76
+ the implementer's work at all - another family, another model of the same family
77
+ where a person opted in, or neither - is its review tier, which `polyctl role set` asks
78
+ with the rule `polyctl review` applies (REVIEW-TIERS).
79
+ """
80
+ implementer, reviewer = roles.get("implementer"), roles.get("reviewer")
81
+ if repository != "tool" and not hotfix and implementer and implementer == roles.get("architect"):
82
+ return (f"on a product repository the architect does not implement ({implementer} holds both); roles rotate "
83
+ "on a tool repository (repository.kind tool), or name a hotfix with --hotfix")
84
+ if implementer and reviewer and implementer == reviewer:
85
+ return f"the reviewer and the implementer would both be {implementer}; no actor reviews its own work"
86
+ return None
87
+
88
+
89
+ def role_of(name, cfg):
90
+ """The role a mail name stands for, including the reviewer actor (TRIAGE-3-LOW)."""
91
+ implementer, _ = mail_names(cfg)
92
+ lowered = str(name or "").strip().lower()
93
+ if lowered in {arch.lower() for arch in architect_mail_names(cfg)}:
94
+ return "architect"
95
+ if lowered in (implementer.lower(), "implementer"):
96
+ return "implementer"
97
+ if lowered in {name.lower() for name in reviewer_mail_names(cfg)}:
98
+ return "reviewer"
99
+ if lowered == "watchdog":
100
+ return "watchdog"
101
+ return "human" if lowered in ("human", "person", "owner") else None
102
+
103
+
104
+ def block_adapter(block):
105
+ """The adapter a role block or reviewer route runs: the one it names, else the shipped one whose command it runs.
106
+
107
+ None when it names none and its command is no shipped adapter's, or more than one's.
108
+ """
109
+ block = block if isinstance(block, dict) else {}
110
+ named = str(block.get("adapter") or "").strip()
111
+ if named:
112
+ return named
113
+ argv = block.get("argv") or []
114
+ program = _program_name(argv[0]) if argv and isinstance(argv[0], str) else ""
115
+ if not program:
116
+ return None
117
+ found = [ident for ident, adapter in package_adapters().items()
118
+ if program in {_program_name(name) for name in
119
+ [ident, *adapter_binaries(adapter), *((adapter.get("detect") or {}).get("processes") or [])]
120
+ if name}]
121
+ return found[0] if len(found) == 1 else None
122
+
123
+
124
+ def declared_family(block):
125
+ """(family, None) as a role block or reviewer route declares it, lowercased, or (None, why none can be named).
126
+
127
+ Its own `family`, or the family its shipped adapter declares. Two that disagree name
128
+ no family: one of the statements is wrong and polyctl cannot tell which. A model name is
129
+ never read as a family (#86).
130
+ """
131
+ block = block if isinstance(block, dict) else {}
132
+ own = str(block.get("family") or "").strip().lower()
133
+ ident = block_adapter(block)
134
+ theirs = str((package_adapters().get(ident) or {}).get("family") or "").strip().lower() if ident else ""
135
+ if own and theirs and own != theirs:
136
+ return None, f"it declares the {own} family and its adapter {ident} the {theirs} family"
137
+ if own or theirs:
138
+ return own or theirs, None
139
+ return None, "it declares no model family, and neither does its adapter"
140
+
141
+
142
+ def grant_author(cfg, matrix_identity=None):
143
+ """Who lands a candidate under a review waiver, as far as polyctl can establish it: role, actor, adapter, family.
144
+
145
+ The grant records it because the waived range is reviewed later against whoever wrote
146
+ it, and the implementer configured by then need not be that actor, nor any (#65). A
147
+ turn polyctl started names its role (POLYCTL_ROLE); that role's block names the actor, its
148
+ adapter and the family declared for it. In a capability-matrix project the
149
+ implementer's family is its binding's, and a family written inline names none. A
150
+ caller polyctl did not start - a person, or a session someone opened - names no role polyctl
151
+ can check, so every field stays None and the retrospective review waits for a person
152
+ to name the family.
153
+ """
154
+ role = invoking_role()
155
+ author = {"role": role, "actor": None, "adapter": None, "family": None}
156
+ if role is None:
157
+ return author
158
+ block = cfg.get(role) if isinstance(cfg.get(role), dict) else {}
159
+ implementer, architect = mail_names(cfg)
160
+ author["actor"] = str(block.get("actor") or block.get("name")
161
+ or (implementer if role == "implementer" else architect))
162
+ author["adapter"] = block_adapter(block)
163
+ if matrix_identity is None:
164
+ author["family"] = declared_family(block)[0]
165
+ elif role == "implementer":
166
+ author.update(adapter=matrix_identity.get("adapter") or author["adapter"],
167
+ family=str(matrix_identity.get("family") or "").strip().lower() or None)
168
+ return author
169
+
170
+
171
+ def write_project_config(root, text):
172
+ """Write `.polyctl/config.json` whole, within the reader's byte and depth limits (TRIAGE-3-LOW)."""
173
+ from .storage import replace_file_durably
174
+ raw = text.encode(UTF8)
175
+ if len(raw) > PROJECT_CONFIG_MAX_BYTES:
176
+ raise ValueError(f".polyctl/config.json exceeds the {PROJECT_CONFIG_MAX_BYTES:,}-byte limit; reduce it first")
177
+ problem = _json_container_depth_problem(raw)
178
+ if problem:
179
+ raise ValueError(problem + "; reduce its nesting first")
180
+ replace_file_durably(os.path.join(root, ".polyctl", "config.json"), raw)
181
+
182
+
183
+ # ---- adapters load from outside the package too (#77) ------------------------------------
184
+
185
+ ADAPTER_CONTRACT = 1
186
+ ADAPTER_VERIFIED = ("full", "partial", "documented", "untested", "planned")
187
+ ADAPTER_PLACEHOLDERS = ("prompt", "session", "model", "effort", "mode", "cwd", "escaped_cwd", "workspace_hash",
188
+ "timeout", "tools", "schema", "max_steps", "provider", "name", "n", "tokens", "dir", "path",
189
+ "agent", "agent_login", "branch", "issue", "lane", "pr", "url", "diff_file", "output", "tree")
190
+
191
+
192
+ def adapter_layers(root=None):
193
+ """[(source, directory)] searched for adapters, lowest first: the package, the user's, the project's (#77)."""
194
+ layers = [("package", adapters_dir()),
195
+ ("user", os.environ.get("POLYCTL_USER_ADAPTERS") or os.path.join(HOME, ".polyctl", "adapters"))]
196
+ if root:
197
+ layers.append(("project", os.path.join(root, ".polyctl", "adapters")))
198
+ return layers
199
+
200
+
201
+ def adapter_catalog(root=None):
202
+ """{id: {"source", "path", "adapter", "problem"}} for every adapter found, a later layer overriding by id.
203
+
204
+ An adapter that declares a contract this polyctl does not implement is listed with
205
+ the problem and never loaded half-way.
206
+ """
207
+ found = {}
208
+ for source, directory in adapter_layers(root):
209
+ try:
210
+ names = sorted(os.listdir(directory))
211
+ except OSError:
212
+ continue
213
+ for name in names:
214
+ if not name.endswith(".json") or name in DATA_FILES:
215
+ continue
216
+ path = os.path.join(directory, name)
217
+ try:
218
+ with open(path, encoding=UTF8) as fh:
219
+ adapter = json.load(fh)
220
+ except (OSError, ValueError) as exc:
221
+ found[name[:-5]] = {"source": source, "path": path, "adapter": {}, "problem": f"unreadable: {exc}"}
222
+ continue
223
+ if not isinstance(adapter, dict):
224
+ continue
225
+ ident = str(adapter.get("id") or name[:-5])
226
+ contract = adapter.get("contract", ADAPTER_CONTRACT)
227
+ problem = None if contract == ADAPTER_CONTRACT else (
228
+ f"declares adapter contract {contract!r}; this polyctl implements contract {ADAPTER_CONTRACT}")
229
+ found[ident] = {"source": source, "path": path, "adapter": adapter, "problem": problem}
230
+ return found
231
+
232
+
233
+ def load_adapter(adapter_id, root=None):
234
+ entry = adapter_catalog(root).get(adapter_id)
235
+ if entry is not None:
236
+ return {} if entry["problem"] else entry["adapter"]
237
+ return dict(package_adapters().get(adapter_id) or {})
238
+
239
+
240
+ # ---- the adapter set derives from one canonical vendor list (#89) ------------------------
241
+
242
+ VENDORS_FILE = "vendors.json"
243
+
244
+
245
+ PROFILES_FILE = "profiles.json"
246
+ DATA_FILES = (VENDORS_FILE, PROFILES_FILE) # beside the adapters, and not adapters
247
+
248
+
249
+ _PROFILE_DOCUMENT = {}
250
+
251
+
252
+ def _layer_profile_document(path):
253
+ """One profiles.json layer, read once per state of the file: mail names consult it for every message."""
254
+ import stat
255
+ try:
256
+ st = os.lstat(path)
257
+ except OSError:
258
+ _PROFILE_DOCUMENT.pop(path, None)
259
+ return {}
260
+ if stat.S_ISLNK(st.st_mode) or not stat.S_ISREG(st.st_mode) or getattr(st, "st_file_attributes", 0) & 0x400:
261
+ _PROFILE_DOCUMENT.pop(path, None)
262
+ return {}
263
+ mtime = st.st_mtime_ns
264
+ cached = _PROFILE_DOCUMENT.get(path)
265
+ if not cached or cached[0] != mtime:
266
+ try:
267
+ with open(path, encoding=UTF8) as fh:
268
+ document = json.load(fh)
269
+ except (OSError, ValueError):
270
+ document = {}
271
+ cached = (mtime, document if isinstance(document, dict) else {})
272
+ _PROFILE_DOCUMENT[path] = cached
273
+ return cached[1]
274
+
275
+
276
+ def _profile_document(root=None):
277
+ """Merged adapters/profiles.json across package, user and project layers."""
278
+ merged = {"profiles": {}}
279
+ for _, folder in adapter_layers(root):
280
+ doc = _layer_profile_document(os.path.join(folder, PROFILES_FILE))
281
+ if doc.get("init"):
282
+ merged["init"] = doc["init"]
283
+ found = doc.get("profiles")
284
+ if isinstance(found, dict):
285
+ for name, roles in found.items():
286
+ if isinstance(roles, dict):
287
+ merged["profiles"][name] = {k: v for k, v in roles.items()
288
+ if k in ("implementer", "reviewer", "architect")}
289
+ return merged
290
+
291
+
292
+ def user_profiles_path():
293
+ """Where `polyctl start` records a chosen profile so `polyctl init --profile` and `A.profiles()` know it."""
294
+ return os.path.join(os.environ.get("POLYCTL_USER_ADAPTERS") or os.path.join(HOME, ".polyctl", "adapters"), PROFILES_FILE)
295
+
296
+
297
+ def write_profile(name, roles, default=True, path=None, check_only=False):
298
+ """Record a profile `{implementer, reviewer, architect}` in profiles.json without touching shipped files.
299
+
300
+ Opened and replaced in its folder held through no link, and refused when a link, a non-regular file or a hard link
301
+ stands at its name or on its way: `POLYCTL_USER_ADAPTERS` can name a folder in the tree an agent writes (ONBOARD).
302
+ """
303
+ import stat
304
+ import tempfile
305
+ from . import storage
306
+ target = path or user_profiles_path()
307
+ absolute = os.path.abspath(target)
308
+ parent, leaf = os.path.dirname(absolute), os.path.basename(absolute)
309
+ if not leaf or leaf in (".", ".."):
310
+ raise storage.InTheWay(target, "names no profile file")
311
+ trusted = set()
312
+ for root_dir in (HOME, tempfile.gettempdir()):
313
+ cur = os.path.dirname(os.path.abspath(root_dir))
314
+ while True:
315
+ trusted.add(cur)
316
+ up = os.path.dirname(cur)
317
+ if up == cur:
318
+ break
319
+ cur = up
320
+ if os.sep == "/":
321
+ trusted.add("/tmp")
322
+ anchors = (os.path.abspath(os.getcwd()), os.path.abspath(HOME))
323
+
324
+ def _under_anchor(folder):
325
+ for anchor in anchors:
326
+ try:
327
+ if folder != anchor and os.path.commonpath([folder, anchor]) == anchor:
328
+ return True
329
+ except ValueError:
330
+ continue
331
+ return False
332
+
333
+ def _untrusted_link_on_way(folder):
334
+ cur = folder
335
+ while True:
336
+ if cur not in trusted and storage.not_a_folder_of_its_own(cur):
337
+ return True
338
+ up = os.path.dirname(cur)
339
+ if up == cur:
340
+ return False
341
+ cur = up
342
+
343
+ base, folder_parts = parent, []
344
+ while os.path.dirname(base) != base and (
345
+ not folder_parts
346
+ or not os.path.exists(base)
347
+ or storage.not_a_folder_of_its_own(base)
348
+ or _under_anchor(base)
349
+ or _untrusted_link_on_way(base)
350
+ ):
351
+ folder_parts.insert(0, os.path.basename(base))
352
+ base = os.path.dirname(base)
353
+ if storage.not_a_folder_of_its_own(base):
354
+ raise storage.InTheWay(base, "is a link or a file where a folder goes")
355
+ with storage._tree_folder(base, folder_parts, make=not check_only) as folder:
356
+ if folder is None:
357
+ return target
358
+ try:
359
+ info = storage._tree_stat(folder, leaf)
360
+ except FileNotFoundError:
361
+ raw = None
362
+ else:
363
+ if stat.S_ISLNK(info.st_mode) or getattr(info, "st_file_attributes", 0) & 0x400:
364
+ raise storage.InTheWay(target, "is a link, and polyctl reads and writes through none")
365
+ if not stat.S_ISREG(info.st_mode):
366
+ raise storage.InTheWay(target, "is no regular file")
367
+ if info.st_nlink != 1:
368
+ raise storage.InTheWay(target, "is a file with another name")
369
+ if not check_only:
370
+ raw = storage._tree_bytes(folder, leaf)
371
+ if check_only:
372
+ return target
373
+ try:
374
+ loaded = json.loads(raw.decode(UTF8)) if raw is not None else {}
375
+ except (UnicodeDecodeError, ValueError):
376
+ loaded = {}
377
+ doc = dict(loaded) if isinstance(loaded, dict) else {}
378
+ existing = doc.get("profiles")
379
+ table = {k: dict(v) for k, v in existing.items() if isinstance(v, dict)} if isinstance(existing, dict) else {}
380
+ clean = {k: roles[k] for k in ("implementer", "reviewer", "architect") if roles.get(k)}
381
+ table[name] = dict(clean)
382
+ pair_name = f"{clean.get('implementer', '')}-{clean.get('reviewer', '')}".strip("-")
383
+ if pair_name and pair_name not in table:
384
+ table[pair_name] = dict(clean)
385
+ doc["profiles"] = table
386
+ if default:
387
+ doc["init"] = name
388
+ data = (json.dumps(doc, indent=2) + "\n").encode(UTF8)
389
+ storage._tree_replace_bytes(folder, leaf, data)
390
+ _PROFILE_DOCUMENT.pop(target, None)
391
+ return target
392
+
393
+
394
+ def profiles(root=None):
395
+ """{name: {role: adapter id}}: the presets `polyctl init --profile` offers, from adapters/profiles.json (#76)."""
396
+ found = _profile_document(root).get("profiles")
397
+ return {name: dict(roles) for name, roles in found.items() if isinstance(roles, dict)} \
398
+ if isinstance(found, dict) else {}
399
+
400
+
401
+ def default_profile(root=None):
402
+ """The profile a new project is pointed at."""
403
+ doc = _profile_document(root)
404
+ found = doc.get("profiles") if isinstance(doc.get("profiles"), dict) else {}
405
+ init = str(doc.get("init") or "")
406
+ return init if init in found else next(iter(sorted(found)), init)
407
+
408
+
409
+ def implementer_actor_name(cfg):
410
+ """The implementer's name when none is set: its adapter's `actor_name`, else the default profile's (#76).
411
+
412
+ A project with no implementer block keeps the name its mail was always written
413
+ under, because the default profile's implementer declares that name.
414
+ """
415
+ ident = ((cfg or {}).get("implementer") or {}).get("adapter") \
416
+ or (profiles().get(default_profile()) or {}).get("implementer") or ""
417
+ return str(package_adapters().get(ident, {}).get("actor_name") or ident or "implementer")
418
+
419
+
420
+ def implementer_adapter_id(cfg=None):
421
+ """The id of the implementer's adapter: the one its block names, else the default profile's implementer; "".
422
+
423
+ The id is the configuration's, not a field of whichever layer's adapter answers to it:
424
+ what an account reader asks the package for must not change with a copy of the adapter
425
+ that declares no id (ACCOUNT-READERS).
426
+ """
427
+ return str(((cfg or {}).get("implementer") or {}).get("adapter")
428
+ or (profiles().get(default_profile()) or {}).get("implementer") or "")
429
+
430
+
431
+ def implementer_adapter(cfg=None):
432
+ """The implementer's adapter: the one its block names, else the default profile's implementer (#76).
433
+
434
+ A transcript reader asked without an adapter reads what the implementer's adapter
435
+ declares, never one harness's record shape written into the reader.
436
+ """
437
+ ident = implementer_adapter_id(cfg)
438
+ return load_adapter(ident, (cfg or {}).get("root")) if ident else {}
439
+
440
+
441
+ def vendor_list():
442
+ """Every vendor polyctl knows, with the adapter that drives it or why none does (#89)."""
443
+ try:
444
+ with open(os.path.join(adapters_dir(), VENDORS_FILE), encoding=UTF8) as fh:
445
+ vendors = json.load(fh).get("vendors")
446
+ except (OSError, ValueError, AttributeError):
447
+ return []
448
+ return [vendor for vendor in vendors if isinstance(vendor, dict) and vendor.get("id")] \
449
+ if isinstance(vendors, list) else []
450
+
451
+
452
+ def shipped_adapter_ids():
453
+ """The ids of the adapters in the package itself, whatever a user or a project layers over them."""
454
+ ids = set()
455
+ try:
456
+ names = os.listdir(adapters_dir())
457
+ except OSError:
458
+ return ids
459
+ for name in names:
460
+ if not name.endswith(".json") or name in DATA_FILES:
461
+ continue
462
+ try:
463
+ with open(os.path.join(adapters_dir(), name), encoding=UTF8) as fh:
464
+ ids.add(str(json.load(fh).get("id") or name[:-5]))
465
+ except (OSError, ValueError, AttributeError):
466
+ ids.add(name[:-5])
467
+ return ids
468
+
469
+
470
+ def vendor_problems():
471
+ """Where the shipped adapters and the vendor list disagree; empty when they agree (#89).
472
+
473
+ An adapter no vendor names, a vendor naming an adapter that is not shipped, and a
474
+ vendor with neither an adapter nor a reason are each an error here rather than a
475
+ silent gap on whichever surface met it first.
476
+ """
477
+ vendors = vendor_list()
478
+ if not vendors:
479
+ return [f"adapters/{VENDORS_FILE} is missing or unreadable"]
480
+ shipped = shipped_adapter_ids()
481
+ problems, named = [], {}
482
+ for vendor in vendors:
483
+ adapter = vendor.get("adapter")
484
+ if adapter:
485
+ if adapter in named:
486
+ problems.append(f"adapter {adapter} is named by both {named[adapter]} and {vendor['id']}")
487
+ named[adapter] = vendor["id"]
488
+ if adapter not in shipped:
489
+ problems.append(f"vendor {vendor['id']} names adapter {adapter}, which is not shipped")
490
+ elif not str(vendor.get("why") or "").strip():
491
+ problems.append(f"vendor {vendor['id']} has no adapter and no reason for having none")
492
+ for ident in sorted(shipped - set(named)):
493
+ problems.append(f"adapter {ident} is shipped, but no vendor in adapters/{VENDORS_FILE} names it")
494
+ return problems
495
+
496
+
497
+ def adapter_binaries(adapter):
498
+ """The command names an adapter runs as: `detect.binaries` where it declares them, else what `send` runs."""
499
+ adapter = adapter or {}
500
+ declared = (adapter.get("detect") or {}).get("binaries") if isinstance(adapter.get("detect"), dict) else None
501
+ if isinstance(declared, list) and declared:
502
+ return [str(name) for name in declared if name]
503
+ send = adapter.get("send")
504
+ argv = send.get("argv") if isinstance(send, dict) else None
505
+ return [os.path.basename(str(argv[0]))] if isinstance(argv, list) and argv else []
506
+
507
+
508
+ def tool_beside_interpreter(name):
509
+ """The command an optional extra installed beside the interpreter polyctl runs on, or None (#86).
510
+
511
+ An extra lands in polyctl's own environment, whose scripts directory need not be on PATH: beside the
512
+ interpreter in a virtual environment, and on Windows in the Scripts directory of an interpreter
513
+ installed for everyone, which is not beside it (API-REVIEWER). A review and `polyctl doctor` look for it
514
+ alike: the doctor looked beside the interpreter alone, and named a reviewer a review would find
515
+ absent (API-REVIEWER-2).
516
+ """
517
+ import sys
518
+ import sysconfig
519
+ name = str(name)
520
+ if not name or os.path.basename(name) != name:
521
+ return None
522
+ try:
523
+ scripts = sysconfig.get_path("scripts")
524
+ except (KeyError, TypeError, ValueError):
525
+ scripts = None
526
+ for here in dict.fromkeys(place for place in (os.path.dirname(sys.executable or ""), scripts) if place):
527
+ for extension in ((".exe", "") if os.name == "nt" else ("",)):
528
+ candidate = os.path.join(here, name + extension)
529
+ if os.path.isfile(candidate) and os.access(candidate, os.X_OK):
530
+ return candidate
531
+ return None
532
+
533
+
534
+ def absent_adapter_binaries(cfg):
535
+ """(actor, adapter, binaries) for each configured actor whose adapter's command this machine lacks (#89).
536
+
537
+ A command an optional extra installed beside the interpreter polyctl runs on is there too (#86).
538
+ """
539
+ def present(name):
540
+ return bool(binary_candidates(name)) or tool_beside_interpreter(name) is not None
541
+
542
+ actors, _, _ = role_table(cfg)
543
+ out = []
544
+ for actor, block in sorted(actors.items()):
545
+ ident = block.get("adapter")
546
+ if not ident:
547
+ continue
548
+ names = adapter_binaries(load_adapter(ident, cfg.get("root")))
549
+ if names and not any(present(name) for name in names):
550
+ out.append((actor, ident, names))
551
+ return out
552
+
553
+
554
+ # ---- a reviewer invocation is built from its adapter (#88) --------------------------------
555
+
556
+ def reviewer_eligibility(adapter):
557
+ """(eligible, why not) for the reviewer role, from what an adapter declares about denying tools (#88).
558
+
559
+ A reviewer must not be able to write. An adapter declares `options.trust_none`:
560
+ the flags that leave the harness only reading, or null with `trust_none_why`,
561
+ which makes it ineligible rather than silently unsafe. An empty list is an answer
562
+ only from a tool reviewer with a sound review contract (#86): polyctl runs it over a
563
+ file it wrote, outside any repository, and there is nothing left to deny.
564
+ """
565
+ options = (adapter or {}).get("options") or {}
566
+ if "trust_none" not in options:
567
+ return False, "it does not declare how to run without tools (options.trust_none)"
568
+ # A harness no flag leaves reading runs as an agent of polyctl's own whose tools only read (AGY-REVIEWER).
569
+ if options["trust_none"] == [] and options.get("reviewer_agent") is not None:
570
+ problems = reviewer_agent_problems(adapter)
571
+ return (False, "its reviewer agent is not sound: " + "; ".join(problems)) if problems else (True, None)
572
+ if options["trust_none"] == [] and (adapter or {}).get("review") is not None:
573
+ problems = tool_review_problems(adapter)
574
+ return (False, "its review contract is not sound: " + "; ".join(problems)) if problems else (True, None)
575
+ if not options["trust_none"]:
576
+ return False, str(options.get("trust_none_why") or ((adapter.get("roles") or {}).get("reviewer"))
577
+ or "it cannot be run without tools")
578
+ return True, None
579
+
580
+
581
+ def compose_reviewer(adapter_id, model=None, effort=None, root=None, family=None):
582
+ """A reviewer route from an adapter's send, model, effort and trust_none; never a hand-written argv (#88).
583
+
584
+ A tool reviewer (#86) reaches many models through its own provider. Its route
585
+ carries the model, which the adapter's review contract pins when polyctl runs it, and
586
+ the family only a person can name: polyctl never infers one from a model name.
587
+
588
+ Composed from the adapter the package ships alone, never a user's or a project's layer: `polyctl ci review` composes
589
+ on a pull request's checkout, whose `.polyctl/adapters/` its author wrote, and a route that names an adapter runs that
590
+ harness's program wherever it starts (ROUTE-ARGV). `root` only tells a layer's adapter from one nobody declares,
591
+ so the refusal says which.
592
+ """
593
+ adapter = turn_adapter(adapter_id)
594
+ if not adapter:
595
+ if load_adapter(adapter_id, root):
596
+ raise ValueError(f"{adapter_id} is no adapter polyctl ships, and a reviewer is composed from one the package "
597
+ "ships, never one a user's or a project's layer declares")
598
+ raise ValueError(f"no adapter {adapter_id}")
599
+ eligible, why = reviewer_eligibility(adapter)
600
+ if not eligible:
601
+ raise ValueError(f"{adapter_id} is ineligible for the reviewer role: {why}")
602
+ argv = list((adapter.get("send") or {}).get("argv") or [])
603
+ if not argv:
604
+ raise ValueError(f"{adapter_id} declares no send.argv")
605
+ declared = str(adapter.get("family") or "").strip()
606
+ if family and declared and family.strip().lower() != declared.lower():
607
+ raise ValueError(f"{adapter_id} declares the {declared} family")
608
+ if tool_review_contract(adapter) is not None:
609
+ if not model:
610
+ raise ValueError(f"{adapter_id} reaches many models; name the one it runs with --model")
611
+ if effort:
612
+ raise ValueError(f"{adapter_id} takes no effort")
613
+ route = {"id": f"{adapter_id}-reviewer-{model}", "adapter": adapter_id, "kind": "tool", "argv": argv,
614
+ "composed": True, "model": model}
615
+ if family:
616
+ route["family"] = family.strip()
617
+ return route
618
+ options = adapter.get("options") or {}
619
+ if model:
620
+ if not options.get("model"):
621
+ raise ValueError(f"{adapter_id} declares no way to choose a model")
622
+ argv += [part.replace("{model}", model) for part in options["model"]]
623
+ if effort:
624
+ values = options.get("effort_values") or []
625
+ if not options.get("effort") or (values and effort not in values):
626
+ raise ValueError(f"{adapter_id} does not take effort {effort}" + (f"; it takes {', '.join(values)}" if values else ""))
627
+ argv += [part.replace("{effort}", effort) for part in options["effort"]]
628
+ argv += list(options["trust_none"])
629
+ route = {"id": f"{adapter_id}-reviewer" + (f"-{model}" if model else ""), "adapter": adapter_id, "argv": argv,
630
+ "composed": True}
631
+ if model:
632
+ route["model"] = model
633
+ if family:
634
+ route["family"] = family.strip()
635
+ return route
636
+
637
+
638
+ def reading_problems(argv, prompt=None):
639
+ """What keeps a command from one that only reads, by the rule a reviewer's and the hunter's meet
640
+ (BUG-HUNTER-2, REVIEWER-REACH-2).
641
+
642
+ A reviewer is composed with the flags its adapter declares leave it only reading; a route written by
643
+ hand, an older one, or an implementer's reassigned to review carries what it carries. `reviewer_problems`
644
+ names a flag that widens; with none of these, `pi -p`, `omp -p` and `hermes -z` edit and run commands,
645
+ `kilo run` edits, and qwen, qoder, reasonix and kiro run in whatever mode a person's settings or another
646
+ flag names. So the command must run a harness polyctl ships, one able to review, with every flag its
647
+ `options.trust_none` names. `prompt` is the text polyctl hands it in place of `{prompt}`.
648
+ """
649
+ adapter = command_adapter(argv)
650
+ if not adapter:
651
+ return ["polyctl ships no adapter for its command, so nothing declares how it runs without tools"]
652
+ eligible, why = reviewer_eligibility(adapter)
653
+ if not eligible:
654
+ return [f"{adapter.get('id')} cannot review: {why}"]
655
+ if tool_review_contract(adapter) is not None:
656
+ return [f"{adapter.get('id')} is a tool reviewer, which reads a file polyctl writes for it, not a tree"]
657
+ args = [str(arg) for arg in argv or []]
658
+ # What follows `--` is no option, though a word there spelled like one was found (REVIEWER-REACH-3).
659
+ args = args[:args.index("--")] if "--" in args else args
660
+ declared = adapter["options"]["trust_none"]
661
+ missing = [token for token in dict.fromkeys(declared) if token not in args]
662
+ if missing:
663
+ return [f"its command lacks {' '.join(missing)}, which {adapter.get('id')} declares leaves it only reading"]
664
+ # A harness polyctl runs as a reviewer agent of its own takes no other: one a command names could hold any tool
665
+ # (KIRO-READONLY).
666
+ agent = adapter["options"].get("reviewer_agent")
667
+ # The flag's name: agy's `--agent={agent}` names it with its value (AGY-REVIEWER).
668
+ flag = str(agent["argv"][0]).split("=", 1)[0] if isinstance(agent, dict) and agent.get("argv") else None
669
+ if flag and any(arg == flag or arg.startswith(flag + "=") for arg in args):
670
+ return [f"it names {flag}, where polyctl runs {adapter.get('id')} as an agent of its own that only reads"]
671
+ # A flag of them given again with another value is asked too, as a pinned flag is: a harness that takes
672
+ # the last of two runs with it (`--trust-tools= --trust-tools=fs_write`, or `--approval-mode plan`
673
+ # then `--approval-mode auto-edit`).
674
+ found = []
675
+ for flag, value in _flag_pairs(part for token in declared
676
+ for part in (token.split("=", 1) if token.startswith("--") and "=" in token
677
+ else [token])):
678
+ if value is None:
679
+ continue
680
+ for at, arg in enumerate(args):
681
+ if arg == flag:
682
+ given = args[at + 1] if at + 1 < len(args) and not args[at + 1].startswith("-") else None
683
+ after = at + 2
684
+ elif arg.startswith(flag + "="):
685
+ given, after = arg.split("=", 1)[1], at + 1
686
+ else:
687
+ continue
688
+ # A flag that takes a list may take every word after it: `--tools Read,Grep,Glob Edit` reads Edit as a
689
+ # tool, where only the first word was asked (REVIEWER-REACH-3), and a parser such as yargs reads
690
+ # `--tools=Read,Grep,Glob Edit` so too (REVIEWER-REACH-4).
691
+ # polyctl's own words - its prompt, a placeholder it fills - are no value smuggled after a flag, wherever a
692
+ # route puts them: kiro takes its prompt as the word after its options.
693
+ if given is not None and after < len(args) and not args[after].startswith("-") \
694
+ and not (args[after] == prompt or re.fullmatch(r"\{[a-z_]+\}", args[after])):
695
+ found.append(f"it gives {flag} more than one value ({given or '(empty)'} {args[after]}), and "
696
+ f"{adapter.get('id')} may read them all")
697
+ continue
698
+ if given == value or (given is not None and (flag in GRANT_FLAGS + ("--tools", "--trust-tools") or "," in value)
699
+ and set(split_tool_list(given)) <= set(split_tool_list(value))):
700
+ continue
701
+ found.append(f"it runs with {flag} {given if given is not None else '(no value)'}, where "
702
+ f"{adapter.get('id')} declares {flag} {value or '(empty)'} leaves it only reading")
703
+ return found
704
+
705
+
706
+ # ---- a turn holds the grant polyctl composes, never a person's default or an unnamed bypass (GRANTS-PINNED) ----
707
+
708
+ def split_tool_list(value):
709
+ """Read Name or Name(body) rules separated by commas/whitespace.
710
+
711
+ Harnesses disagree about commas and nested rules inside a body. Reject those,
712
+ adjacent rules without a separator, and unbalanced parentheses as every Bash
713
+ command. Auditing, rewriting and pin comparisons use this same strict grammar.
714
+ """
715
+ outside, tool, in_body, closed = [], [], False, False
716
+ for char in value + ",":
717
+ if in_body:
718
+ if char in ",(": # Also rejects any embedded Bash( text, even in another tool's body.
719
+ return ["Bash(*)"]
720
+ if char == ")":
721
+ in_body, closed = False, True
722
+ elif char == "," or char.isspace():
723
+ if tool:
724
+ outside.append("".join(tool))
725
+ tool, closed = [], False
726
+ continue
727
+ elif closed or char == ")":
728
+ return ["Bash(*)"]
729
+ elif char == "(":
730
+ if not tool:
731
+ return ["Bash(*)"]
732
+ in_body = True
733
+ tool.append(char)
734
+ return ["Bash(*)"] if in_body else list(dict.fromkeys(outside))
735
+
736
+
737
+ # Flags whose values are tool lists in the shared grammar (#58).
738
+ GRANT_FLAGS = ("--allowedTools", "--allowed-tools")
739
+ # An argv that carries one of these carries a tool scope of its own, and polyctl appends no grant to it (#58, #69).
740
+ SCOPE_FLAGS = GRANT_FLAGS + ("--trust-tools", "--trust-all-tools")
741
+ # Spellings with which a harness approves everything, sandboxes nothing or checks no permission: a yolo or a
742
+ # "dangerously" flag, a trust or an allow of every tool, a standing yes, a forced or automatic run, a mode of
743
+ # full access. Each one a command polyctl starts carries is declared, with why, in its adapter's `options.bypass`.
744
+ BYPASS_FLAG = re.compile(r"--?(yolo|dangerously(-[a-z]+)+|(trust|allow)-all(-[a-z]+)*|yes(-always)?|y|full-auto|"
745
+ r"skip-permissions(-[a-z]+)*|auto(-approve)?|force|f|no-sandbox|not-so-yolo|approve-for-me)",
746
+ re.I)
747
+ BYPASS_VALUE = re.compile(r"yolo|bypass[-_]?permissions|danger-full-access|full-access|always-proceed|unrestricted",
748
+ re.I)
749
+
750
+
751
+ def carries_scope(argv):
752
+ """Whether an argv grants its tools through an allowlist or a trust flag of its own."""
753
+ return any(str(arg) in SCOPE_FLAGS or str(arg).startswith(tuple(flag + "=" for flag in SCOPE_FLAGS))
754
+ for arg in argv or [])
755
+
756
+
757
+ def _holds(argv, run):
758
+ """Whether a run of arguments occurs in argv."""
759
+ args, run = [str(arg) for arg in argv or []], [str(part) for part in run or []]
760
+ return bool(run) and any(args[at:at + len(run)] == run for at in range(len(args) - len(run) + 1))
761
+
762
+
763
+ def unattended_flags(adapter, argv):
764
+ """(flags, why) polyctl appends to an implementer turn nobody attends, started from `argv`; ([], None) for none (#69).
765
+
766
+ An argv that carries a tool scope of its own is left as it is: a grant of every tool on
767
+ top of an allowlist silently overrides the narrower grant. Otherwise the adapter's
768
+ `options.unattended`, the narrower grant its documentation gives a turn nobody can
769
+ approve, with what a command rewriter makes of each command it names (GRANTS-RTK), and
770
+ where it declares none its `trust_all`.
771
+ """
772
+ options = (adapter or {}).get("options") or {}
773
+ if carries_scope(argv):
774
+ return [], None
775
+ if isinstance(options.get("unattended"), list):
776
+ flags, rewritten = admit_rewrites([str(flag) for flag in options["unattended"]])
777
+ why = "the adapter declares the grant of a turn nobody attends (options.unattended)"
778
+ if rewritten:
779
+ why += ("; it also admits each command it names in the form a command rewriter runs it as "
780
+ "(adapters/rewriters)")
781
+ return flags, (why if flags else None)
782
+ if options.get("trust_all"):
783
+ return ([str(flag) for flag in options["trust_all"]],
784
+ "the adapter's resume argv carries no tool scope, so polyctl appends its trust_all")
785
+ return [], None
786
+
787
+
788
+ def _flag_pairs(parts):
789
+ """[(flag, value or None)] of an argv fragment: each flag, with the word after it when that is no flag."""
790
+ parts = [str(part) for part in parts or []]
791
+ return [(part, parts[at + 1] if at + 1 < len(parts) and not parts[at + 1].startswith("-") else None)
792
+ for at, part in enumerate(parts) if part.startswith("-")]
793
+
794
+
795
+ def _named(argv, flag):
796
+ """(named, value): whether an argv carries `flag` - alone, before its value, or as flag=value - and the value."""
797
+ args = [str(arg) for arg in argv or []]
798
+ for at, arg in enumerate(args):
799
+ if arg == flag:
800
+ return True, args[at + 1] if at + 1 < len(args) and not args[at + 1].startswith("-") else None
801
+ if arg.startswith(flag + "="):
802
+ return True, arg.split("=", 1)[1]
803
+ return False, None
804
+
805
+
806
+ def command_adapter(argv):
807
+ """The adapter polyctl ships whose command an argv runs, when exactly one runs it; else None.
808
+
809
+ Read from the package's adapters alone: a layer an agent can write must not choose the
810
+ arguments its own turn, or its reviewer's, starts with.
811
+ """
812
+ if not argv or not isinstance(argv[0], str):
813
+ return None
814
+ program = _program_name(argv[0])
815
+ found = [adapter for ident, adapter in sorted(package_adapters().items())
816
+ if program in {_program_name(name) for name in [ident, *adapter_binaries(adapter)] if name}]
817
+ return found[0] if len(found) == 1 else None
818
+
819
+
820
+ def _config_part(part):
821
+ """A path component as a file system that ignores case, a trailing dot or space, or an NTFS stream names it."""
822
+ return part.split(":", 1)[0].rstrip(". ").casefold()
823
+
824
+
825
+ def project_config_names():
826
+ """{(component, ...): the name as declared} of every file and folder an adapter polyctl ships says its harness reads from
827
+ a project as configuration or instructions, in `project_config` (REVIEW-TREE-3).
828
+
829
+ A harness started in a folder reads its hooks, plugins, MCP servers and instructions from there: Claude Code ran a
830
+ SessionStart hook from the candidate's .claude/settings.json, agy its .agents/hooks.json, and OpenCode a plugin and
831
+ an MCP server from its .opencode/ and opencode.json, each before or while it reviewed. Every adapter's names are
832
+ withheld from every reviewer, since a harness reads others' too - OpenCode reads CLAUDE.md and .claude/skills. Read
833
+ from the package's adapters alone, as `command_adapter` is: a layer an agent can write must not say what its
834
+ reviewer is handed.
835
+ """
836
+ names = {}
837
+ for adapter in package_adapters().values():
838
+ # The instruction files it reads from a project, `directives.steering_files`, are among them; its own home's
839
+ # are no tree's.
840
+ steering = [name for name in (adapter.get("directives") or {}).get("steering_files") or []
841
+ if isinstance(name, str) and not name.startswith(("~", "/"))]
842
+ for declared in list(adapter.get("project_config") or []) + steering:
843
+ parts = tuple(_config_part(part) for part in str(declared).split("/") if part)
844
+ if parts and all(parts):
845
+ names.setdefault(parts, str(declared))
846
+ return names
847
+
848
+
849
+ def project_config_member(path, names=None):
850
+ """The `project_config` name a tree member's path holds or falls under, wherever in the tree it is; else None
851
+ (REVIEW-TREE-3)."""
852
+ names = project_config_names() if names is None else names
853
+ parts = [_config_part(part) for part in str(path).replace("\\", "/").split("/") if part not in ("", ".")]
854
+ for entry, declared in names.items():
855
+ width = len(entry)
856
+ if any(tuple(parts[at:at + width]) == entry for at in range(len(parts) - width + 1)):
857
+ return declared
858
+ return None
859
+
860
+
861
+ # REVIEW-TREE-3 keeps a candidate's hooks, plugins, MCP servers and instructions from its reviewer, but the same files
862
+ # act wherever else a harness starts in a tree an agent writes: a hook the implementer puts in .claude/settings.json
863
+ # runs in its own next session, outside the permissions that hold its commands, and in the architect's when polyctl wakes it
864
+ # in the same checkout - each before a review has seen it (#112). So every change to what an adapter declares its
865
+ # harness reads from a project is named, and nothing polyctl starts in the tree runs until a person has seen it
866
+ # (HARNESS-CONFIG).
867
+
868
+ # How each state project_config_changes gives a change reads to a person.
869
+ HARNESS_CONFIG_STATES = {"modified": "modified", "added": "added", "deleted": "deleted", "untracked": "untracked",
870
+ "ignored": "ignored by git", "hidden": "modified, hidden from git status",
871
+ "linked": "a tracked link, read through to what it leads to",
872
+ "committed": "committed with no grant",
873
+ "python": "run by Python as it starts there"}
874
+ # The changes polyctl reads before it stops and says it cannot tell what changed: a folder it walks itself - one git lists
875
+ # without descending, a repository of its own, a link's target - can hold any number of files.
876
+ HARNESS_CONFIG_LIMIT = 5000
877
+ # What polyctl keeps of a file to show a person; a larger one is named by its size alone.
878
+ HARNESS_CONFIG_SHOW_BYTES = 1 << 20
879
+ # What a terminal acts on rather than shows: control characters, a carriage return among them, and the zero-width and
880
+ # bidirectional ones that make text read otherwise than it runs. Shown escaped, so a change cannot hide in them. A line
881
+ # feed and the line and paragraph separators are among them: a name or a session's id holding one started a line of
882
+ # its own, which read as one polyctl wrote (LEADS-MCP). So is a tab: in a title it moved what followed it to another
883
+ # column, where a person read it as another field.
884
+ _UNSHOWN = re.compile("[\x00-\x1f\x7f-\x9f\u200b-\u200f\u2028-\u202e\u2060-\u2069\ufeff]")
885
+
886
+
887
+ def shown_text(text):
888
+ """Text as a person must read it to see what it does: each character of _UNSHOWN escaped, and a name that is not
889
+ UTF-8 shown with replacement characters rather than failing the line it is in (HARNESS-CONFIG). It is one line:
890
+ text of several is shown a line at a time (LEADS-MCP)."""
891
+ return _UNSHOWN.sub(lambda m: "\\x%02x" % ord(m.group()) if ord(m.group()) < 0x100 else "\\u%04x" % ord(m.group()),
892
+ str(text).encode(UTF8, "surrogatepass").decode(UTF8, "replace"))
893
+
894
+
895
+ def _kind_digest(kind, data):
896
+ """The digest of what stands where a harness reads that is no regular file's bytes - a link, a FIFO, a socket or a
897
+ device, a link to nothing - which names its kind before the sha256 of `data` (LEADS-ADAPTERS).
898
+
899
+ A regular file's digest is the sha256 of its bytes alone, 64 hex digits, and these were the sha256 of a marker polyctl
900
+ wrote: a file holding `special:a FIFO` read like a FIFO, so a person who saw that file had seen the FIFO an agent
901
+ put in its place, whose writer sends a harness whatever it likes; and a file holding a link's marker read like the
902
+ link. No file's bytes can be given a digest that starts with its kind."""
903
+ return f"{kind}:{hashlib.sha256(data).hexdigest()}"
904
+
905
+
906
+ def _harness_read(full):
907
+ """(sha256, view) of what a harness reads at `full`, through a link where one stands (HARNESS-CONFIG).
908
+
909
+ Only a regular file is read. A FIFO or a device there - or a link to one, /dev/zero - would hold the reader for as
910
+ long as its writer liked, so it is opened without waiting and named for what it is. The view is ("file", its bytes
911
+ or None past HARNESS_CONFIG_SHOW_BYTES, its size), ("special", what it is) or ("missing",) for a link to nothing;
912
+ the digest of each but a file names its kind (_kind_digest).
913
+ """
914
+ import stat
915
+ try:
916
+ fd = os.open(full, os.O_RDONLY | getattr(os, "O_NONBLOCK", 0) | getattr(os, "O_BINARY", 0))
917
+ except FileNotFoundError:
918
+ return _kind_digest("missing", b""), ("missing",)
919
+ except OSError as exc:
920
+ raise RuntimeError(f"{full} cannot be read ({exc.strerror or exc})") from None
921
+ try:
922
+ mode = os.fstat(fd).st_mode
923
+ except OSError as exc:
924
+ os.close(fd)
925
+ raise RuntimeError(f"{full} cannot be read ({exc.strerror or exc})") from None
926
+ if not stat.S_ISREG(mode):
927
+ os.close(fd)
928
+ kind = ("a folder" if stat.S_ISDIR(mode) else "a FIFO" if stat.S_ISFIFO(mode)
929
+ else "a socket" if stat.S_ISSOCK(mode) else "a device")
930
+ return _kind_digest("special", kind.encode(UTF8)), ("special", kind)
931
+ digest, kept, size = hashlib.sha256(), [], 0
932
+ with os.fdopen(fd, "rb") as fh:
933
+ for chunk in iter(lambda: fh.read(1 << 16), b""):
934
+ digest.update(chunk)
935
+ size += len(chunk)
936
+ if size <= HARNESS_CONFIG_SHOW_BYTES:
937
+ kept.append(chunk)
938
+ return digest.hexdigest(), ("file", b"".join(kept) if size <= HARNESS_CONFIG_SHOW_BYTES else None, size)
939
+
940
+
941
+ def harness_baseline(root, key=None):
942
+ """The HEAD this project's harness configuration was first read at - `polyctl init`'s, or the first reading's - kept in
943
+ ~/.polyctl and never moved by polyctl again; None before one is recorded (HARNESS-CONFIG)."""
944
+ try:
945
+ with open(project_file(root, "harness-base", key=key), encoding=UTF8) as fh:
946
+ record = json.load(fh)
947
+ except (OSError, ValueError):
948
+ return None
949
+ return record.get("head") if isinstance(record, dict) and isinstance(record.get("head"), str) else None
950
+
951
+
952
+ def record_harness_baseline(root, why):
953
+ """Keep HEAD as the commit this project's harness configuration is measured from when no grant or person says
954
+ later, once: the first record stands, so code that runs `polyctl init` again moves nothing (HARNESS-CONFIG).
955
+
956
+ Two first readings at once - `polyctl init` and a watchdog cycle - each found no record and wrote one, the later over
957
+ the earlier; the record is looked for again and written under the project's harness lock (LEADS-ADAPTERS)."""
958
+ from .storage import _exclusive_lock, replace_file_durably
959
+ path = project_file(root, "harness-base")
960
+ head = _git_text(root, "rev-parse", "--verify", "-q", "HEAD")
961
+ if os.path.exists(path) or not re.fullmatch(r"[0-9a-f]{40}|[0-9a-f]{64}", head):
962
+ return None
963
+ os.makedirs(os.path.dirname(path), exist_ok=True)
964
+ with _exclusive_lock(project_file(root, "harness-lock")):
965
+ if os.path.exists(path):
966
+ return None
967
+ record = {"head": head, "at": int(time.time()), "why": why}
968
+ replace_file_durably(path, (json.dumps(record) + "\n").encode(UTF8))
969
+ return head
970
+
971
+
972
+ def _nearest_ancestor(root, marks):
973
+ """Of `marks`, the commit nearest HEAD that HEAD descends from; None when none is."""
974
+ best, git_env = None, {"GIT_OPTIONAL_LOCKS": "0"}
975
+ for mark in dict.fromkeys(mark for mark in marks if mark):
976
+ try:
977
+ _git_output(root, "merge-base", "--is-ancestor", mark, "HEAD", env=git_env)
978
+ distance = int(_git_output(root, "rev-list", "--count", f"{mark}..HEAD",
979
+ env=git_env).decode("ascii").strip())
980
+ except (RuntimeError, ValueError, UnicodeError):
981
+ continue
982
+ if best is None or distance < best[0]:
983
+ best = (distance, mark)
984
+ return best[1] if best else None
985
+
986
+
987
+ def harness_config_base(root, key=None):
988
+ """The commit harness configuration is measured from when HEAD's own is not to be trusted: the one below the
989
+ oldest commit with no grant on HEAD's first-parent line, after the newest of the first grant's base, the HEAD a
990
+ person last recorded as seen, and the HEAD the configuration was first read at. None when every commit since is
991
+ granted, or when there is nothing to measure from.
992
+
993
+ What differs from HEAD is what no commit holds yet. A change committed with no grant - `git commit --no-verify` -
994
+ is in HEAD and differed from nothing, so a hook committed so ran in the next nudge; and in a project that had made
995
+ no grant at all, or one where a granted commit came after it, it went unseen all the same (the reviews of
996
+ HARNESS-CONFIG). Measured from below the oldest ungranted commit, it is a change until a person sees it."""
997
+ trees, base, rows = _granted_trees(root)
998
+ if rows:
999
+ product = [row for row in rows if not row.get("coordination")]
1000
+ trees = {(row.get("candidate") or {}).get("index_tree") for row in product}
1001
+ trees.discard(None)
1002
+ base = next(((row.get("candidate") or {}).get("head") for row in product
1003
+ if (row.get("candidate") or {}).get("head")), None)
1004
+ lower = _nearest_ancestor(root, [base, (harness_seen_record(root, key=key) or {}).get("head"),
1005
+ harness_baseline(root, key=key)])
1006
+ if lower is None and rows:
1007
+ lower = _nearest_ancestor(root, [next(((row.get("candidate") or {}).get("head") for row in rows
1008
+ if (row.get("candidate") or {}).get("head")), None)])
1009
+ if lower is None:
1010
+ return None
1011
+ try:
1012
+ log = _git_output(root, "log", "--first-parent", "--format=%H %T", f"{lower}..HEAD", "--",
1013
+ env={"GIT_OPTIONAL_LOCKS": "0"}).decode("ascii")
1014
+ except (RuntimeError, UnicodeError):
1015
+ return None
1016
+ commits = [line.split() for line in log.splitlines() if line.strip()]
1017
+ ungranted = [index for index, (_, tree) in enumerate(commits) if tree not in trees]
1018
+ if not ungranted:
1019
+ return None
1020
+ oldest = ungranted[-1]
1021
+ return commits[oldest + 1][0] if oldest + 1 < len(commits) else lower
1022
+
1023
+
1024
+ def harness_worktree_dirs():
1025
+ """The folders the shipped adapters' harnesses keep the worktrees they make in - `.claude/worktrees` - as tuples of
1026
+ path components read as a file system would: a worktree of this repository there is a tree of its own, which no
1027
+ harness started at the root reads as configuration (HARNESS-CONFIG). Anywhere else a worktree is read like any
1028
+ folder: one made at `.claude` itself is configuration through and through (the review of HARNESS-CONFIG)."""
1029
+ dirs = set()
1030
+ for adapter in package_adapters().values():
1031
+ for name in adapter.get("worktree_dirs") or []:
1032
+ if _within_its_folder(name):
1033
+ dirs.add(tuple(_config_part(part) for part in name.split("/") if part not in ("", ".")))
1034
+ return dirs
1035
+
1036
+
1037
+ # What `site` runs whenever Python starts: each .pth file of a site directory, whose lines that begin with `import` are
1038
+ # run as code, and a module by each of these names wherever it lies on the import path (PYTHON-ENV).
1039
+ PYTHON_STARTUP_MODULES = ("sitecustomize", "usercustomize")
1040
+ # The variables polyctl reads that name a program it runs, the adapters it trusts as a person's, or a record it keeps
1041
+ # outside the tree on purpose; one that names a path inside the tree hands it to whoever writes there (PYTHON-ENV).
1042
+ POLYCTL_PATH_VARIABLES = ("POLYCTL_GIT", "POLYCTL_USER_ADAPTERS", "POLYCTL_SETTINGS", "POLYCTL_LEDGER_CHECKPOINTS", "POLYCTL_PROJECT_REGISTRY",
1043
+ "POLYCTL_EVENTS")
1044
+
1045
+
1046
+ def _children(folder):
1047
+ """The names in a folder, sorted; none where it cannot be listed (PYTHON-ENV)."""
1048
+ try:
1049
+ return sorted(os.listdir(folder))
1050
+ except OSError:
1051
+ return []
1052
+
1053
+
1054
+ def _python_startup_names(folder, site_dir):
1055
+ """The names in `folder` that Python runs as it starts: each .pth file where it is a site directory, and
1056
+ sitecustomize and usercustomize in any form the import system loads - a source, a sourceless .pyc, an extension, a
1057
+ package - with their compiled copies in __pycache__, which Python runs in a source's place while the stamp they
1058
+ carry matches it (PYTHON-ENV)."""
1059
+ names = _children(folder)
1060
+ found = [name for name in names if (site_dir and name.casefold().endswith(".pth"))
1061
+ or name.split(".", 1)[0].casefold() in PYTHON_STARTUP_MODULES]
1062
+ if "__pycache__" in names:
1063
+ found += ["__pycache__/" + name for name in _children(os.path.join(folder, "__pycache__"))
1064
+ if name.split(".", 1)[0].casefold() in PYTHON_STARTUP_MODULES]
1065
+ return found
1066
+
1067
+
1068
+ def _own_standard_library(prefix):
1069
+ """Why the environment at `prefix` holds a standard library of its own, or None: a conda environment, or a lib folder
1070
+ holding anything beside site-packages - a venv's comes from outside it, and holds nothing else there (PYTHON-ENV).
1071
+
1072
+ Such an environment runs from itself, as it starts, whatever modules of its standard library it imports, in any
1073
+ form the import system loads: naming some of them let a package or a sourceless file stand in for the rest (the
1074
+ reviews of PYTHON-ENV). polyctl reads no installation file by file; one inside the tree is moved out."""
1075
+ if os.path.isdir(os.path.join(prefix, "conda-meta")):
1076
+ return "a conda environment"
1077
+ if _python_installation(prefix) and not os.path.isfile(os.path.join(prefix, "pyvenv.cfg")):
1078
+ return "a Python installation's own standard library"
1079
+ for lib in [name for name in _children(prefix) if name.casefold() in ("lib", "lib64")]:
1080
+ base = os.path.join(prefix, lib)
1081
+ folders = [base] + [os.path.join(base, name) for name in _children(base)
1082
+ if name.casefold().startswith(("python", "pypy"))
1083
+ and os.path.isdir(os.path.join(base, name))]
1084
+ for folder in folders:
1085
+ extra = [name for name in _children(folder) if name.casefold() not in ("site-packages", "__pycache__")
1086
+ and not (folder == base and os.path.join(base, name) in folders)]
1087
+ if extra:
1088
+ return f"a standard library of its own ({os.path.basename(folder)}/{sorted(extra)[0]})"
1089
+ return None
1090
+
1091
+
1092
+ def _site_directories(prefix):
1093
+ """The site directories of the Python environment at `prefix`: lib/pythonX.Y/site-packages and its kin on POSIX,
1094
+ Lib/site-packages on Windows, each by the name its folder has, whatever case a file system ignores (PYTHON-ENV)."""
1095
+ # PyPy keeps its site-packages at the environment's top on some platforms (the review of PYTHON-ENV).
1096
+ found = [os.path.join(prefix, name) for name in _children(prefix) if name.casefold() == "site-packages"]
1097
+ for lib in [name for name in _children(prefix) if name.casefold() in ("lib", "lib64")]:
1098
+ base = os.path.join(prefix, lib)
1099
+ for name in _children(base):
1100
+ if name.casefold() == "site-packages":
1101
+ found.append(os.path.join(base, name))
1102
+ else:
1103
+ inner = os.path.join(base, name)
1104
+ found += [os.path.join(inner, sub) for sub in _children(inner) if sub.casefold() == "site-packages"]
1105
+ return [path for path in found if os.path.isdir(path)]
1106
+
1107
+
1108
+ def _in_tree(path, top):
1109
+ """Whether `path`, its links followed, is the folder `top` or lies inside it (PYTHON-ENV). The root itself counts:
1110
+ `PYTHONPATH=.` or an environment made at the root was read as outside the tree (the review of PYTHON-ENV). Named
1111
+ apart from lib_transcript's `_inside`, a part loaded later into the same namespace, whose stricter reading - links
1112
+ not followed, the folder itself outside - had replaced this one's."""
1113
+ real, top = (os.path.normcase(os.path.realpath(each)) for each in (path, top))
1114
+ return real == top or real.startswith(top.rstrip(os.sep) + os.sep)
1115
+
1116
+
1117
+ # Where a standard library of a Python's own sits: lib/pythonX.Y/os.py or lib/pypyX.Y/os.py; Windows' Lib/os.py is one
1118
+ # only beside a python.exe, since a project's own lib/os.py is a module of the project's.
1119
+ _STDLIB_SIGNATURE = re.compile(r"^(?:(.*)/)?(?:[Ll]ib(?:64)?/(?:[Pp]ython|[Pp]y[Pp]y)[^/]*|Lib)/os\.py$")
1120
+
1121
+
1122
+ def _python_installation(prefix):
1123
+ """Whether a folder holds a Python installation of its own, by its standard library's signature (PYTHON-ENV)."""
1124
+ names = _children(prefix)
1125
+ if "Lib" in names and os.path.isfile(os.path.join(prefix, "Lib", "os.py")) \
1126
+ and any(name.casefold() in ("python.exe", "pythonw.exe") for name in names):
1127
+ return True
1128
+ for lib in [name for name in names if name.casefold() in ("lib", "lib64")]:
1129
+ base = os.path.join(prefix, lib)
1130
+ if any(os.path.isfile(os.path.join(base, name, "os.py")) for name in _children(base)
1131
+ if name.casefold().startswith(("python", "pypy"))):
1132
+ return True
1133
+ return False
1134
+
1135
+
1136
+ # The names a Python's own standard library folder has, probed one by one so an ignored folder is never listed.
1137
+ _STDLIB_FOLDERS = tuple(f"{name}3.{minor}" for name in ("python", "pypy") for minor in range(30)) + ("python2.7",)
1138
+
1139
+
1140
+ def _python_installation_probe(prefix):
1141
+ """_python_installation by asking for each path it would find, never listing `prefix`: what git did not descend
1142
+ into - build/, node_modules/ - is not read through (PYTHON-ENV)."""
1143
+ if os.path.isfile(os.path.join(prefix, "Lib", "os.py")) and any(
1144
+ os.path.isfile(os.path.join(prefix, name)) for name in ("python.exe", "pythonw.exe")):
1145
+ return True
1146
+ return any(os.path.isfile(os.path.join(prefix, lib, name, "os.py"))
1147
+ for lib in ("lib", "lib64") for name in _STDLIB_FOLDERS)
1148
+
1149
+
1150
+ def _venv_home(root):
1151
+ """The `home` a venv's pyvenv.cfg names for its Python, or None (PYTHON-ENV)."""
1152
+ try:
1153
+ with open(os.path.join(root, "pyvenv.cfg"), encoding=UTF8, errors="replace") as fh:
1154
+ text = fh.read()
1155
+ except OSError:
1156
+ return None
1157
+ for line in text.splitlines():
1158
+ key, sep, value = line.partition("=")
1159
+ if sep and key.strip().casefold() == "home":
1160
+ return value.strip() or None
1161
+ return None
1162
+
1163
+
1164
+ def python_startup_files(top, listed=(), folders_out=None):
1165
+ """The paths, relative to the tree at `top`, of each file Python runs as it starts from inside the tree
1166
+ (PYTHON-ENV).
1167
+
1168
+ A .venv in the repository is ignored, so an implementer can put a .pth file or a sitecustomize.py into its
1169
+ site-packages, and every polyctl that environment runs - the commit hook through the polyctl on the committer's PATH, the
1170
+ watchdog's job, a person's own command - runs it first, before any review (#113). What is read: each environment
1171
+ git names in the tree, by the pyvenv.cfg a venv, virtualenv or uv writes or the conda-meta/ conda keeps, with the
1172
+ folders `listed`, git status's names, holding one; the environment and the site directories of the interpreter
1173
+ running this polyctl, where they lie inside the tree; and every other folder of this interpreter's import path inside
1174
+ it, where only a sitecustomize or usercustomize runs. Nothing else of an environment is read.
1175
+ """
1176
+ import site
1177
+ roots = [sys.prefix]
1178
+ # An environment the repository tracks is found by its marker too: git status names only what changed, and a .pth
1179
+ # added to a tracked environment changed nothing of its pyvenv.cfg (the review of PYTHON-ENV).
1180
+ try:
1181
+ tracked = _git_output(top, "ls-files", "-z", "--", "*pyvenv.cfg", "*conda-meta/*", "*os.py",
1182
+ env={"GIT_OPTIONAL_LOCKS": "0"}).split(b"\0")
1183
+ except RuntimeError:
1184
+ tracked = []
1185
+ for item in tracked:
1186
+ rel = os.fsdecode(item)
1187
+ if rel.split("/")[-1] == "os.py":
1188
+ continue # read by its signature below
1189
+ if rel.split("/")[-1] == "pyvenv.cfg":
1190
+ roots.append(os.path.join(top, *rel.split("/")[:-1]))
1191
+ elif "/conda-meta/" in "/" + rel:
1192
+ parts = rel.split("/")
1193
+ roots.append(os.path.join(top, *parts[:parts.index("conda-meta")]))
1194
+ # A Python installation with no marker at all - no pyvenv.cfg, no conda-meta - is found by its standard library's
1195
+ # signature: among what git status names, file by file or as a folder it did not descend into, asked for without
1196
+ # listing it, and among what the repository tracks (the review of PYTHON-ENV). What lies deeper in an ignored
1197
+ # folder is not searched: a person who runs a program an agent left in the tree runs the agent's code.
1198
+ for rel in list(listed) + [os.fsdecode(item) for item in tracked if item]:
1199
+ if "node_modules" in rel.split("/"):
1200
+ continue
1201
+ found = _STDLIB_SIGNATURE.match(rel.rstrip("/"))
1202
+ prefix = os.path.join(top, *(found.group(1) or ".").split("/")) if found else None
1203
+ if prefix and (rel.rstrip("/").split("/")[-2:-1] != ["Lib"] or _python_installation(prefix)):
1204
+ roots.append(prefix)
1205
+ elif rel.endswith("/"):
1206
+ folder = os.path.join(top, *rel.rstrip("/").split("/"))
1207
+ if _python_installation_probe(folder):
1208
+ roots.append(folder)
1209
+ for rel in listed:
1210
+ folder = os.path.join(top, *rel.rstrip("/").split("/"))
1211
+ if rel.endswith("/") and (os.path.isfile(os.path.join(folder, "pyvenv.cfg"))
1212
+ or os.path.isdir(os.path.join(folder, "conda-meta"))):
1213
+ roots.append(folder)
1214
+ elif rel.split("/")[-1] == "pyvenv.cfg":
1215
+ roots.append(os.path.dirname(folder))
1216
+ elif "/conda-meta/" in "/" + rel:
1217
+ # An untracked conda environment is listed file by file, conda-meta/history among them (the review of
1218
+ # PYTHON-ENV).
1219
+ parts = rel.split("/")
1220
+ roots.append(os.path.join(top, *parts[:parts.index("conda-meta")]))
1221
+ for root in roots:
1222
+ why = _own_standard_library(root) if _in_tree(root, top) else None
1223
+ home = _venv_home(root) if _in_tree(root, top) else None
1224
+ if home and _in_tree(home, top):
1225
+ # pyvenv.cfg names where its Python and that Python's standard library are: a home in the tree is one an
1226
+ # agent writes (the review of PYTHON-ENV).
1227
+ why = f"its pyvenv.cfg makes {os.path.relpath(os.path.realpath(home), os.path.realpath(top))}, inside the " \
1228
+ "tree, its Python's home"
1229
+ if why:
1230
+ raise RuntimeError(f"{os.path.relpath(os.path.realpath(root), os.path.realpath(top)) or '.'} is a Python "
1231
+ f"installation inside the tree - {why} - which an agent can write and which runs from "
1232
+ "itself as it starts: move it outside the tree (PYTHON-ENV)")
1233
+ sites = [path for root in roots if _in_tree(root, top) for path in _site_directories(root)]
1234
+ sites += list(site.getsitepackages()) if hasattr(site, "getsitepackages") else []
1235
+ if site.ENABLE_USER_SITE and hasattr(site, "getusersitepackages"):
1236
+ sites.append(site.getusersitepackages())
1237
+ # One folder each, by what it is: lib64 is often a link to lib, and a file system that ignores case reaches one
1238
+ # folder by two spellings.
1239
+ folders = {}
1240
+ for path, site_dir in [(path, True) for path in sites] + [(path, False) for path in sys.path if path]:
1241
+ if not (os.path.isdir(path) and _in_tree(path, top)):
1242
+ continue
1243
+ try:
1244
+ stat = os.stat(path)
1245
+ except OSError:
1246
+ continue
1247
+ # A file system that numbers no folder, as FAT does, is told them apart by name.
1248
+ key = (stat.st_dev, stat.st_ino) if stat.st_ino else os.path.normcase(os.path.realpath(path))
1249
+ held = folders.setdefault(key, [os.path.realpath(path), site_dir])
1250
+ held[1] = held[1] or site_dir
1251
+ real_top = os.path.realpath(top)
1252
+
1253
+ def tree_rel(path):
1254
+ # The tree's root is "", never "./": git names a file at the root `pyvenv.cfg` (the review of PYTHON-ENV).
1255
+ rel = os.path.relpath(os.path.realpath(path), real_top).replace(os.sep, "/")
1256
+ return "" if rel == "." else rel
1257
+
1258
+ def joined(folder, name):
1259
+ return f"{folder}/{name}" if folder else name
1260
+
1261
+ if folders_out is not None:
1262
+ folders_out.update({tree_rel(folder): site_dir for folder, site_dir in folders.values()})
1263
+ found = {joined(tree_rel(folder), name)
1264
+ for folder, site_dir in folders.values() for name in _python_startup_names(folder, site_dir)}
1265
+ # A venv's pyvenv.cfg says where its Python is, and so what that Python runs: configuration as much (PYTHON-ENV).
1266
+ found |= {joined(tree_rel(root), "pyvenv.cfg") for root in dict.fromkeys(roots)
1267
+ if _in_tree(root, top) and os.path.isfile(os.path.join(root, "pyvenv.cfg"))}
1268
+ return found
1269
+
1270
+
1271
+ def _names_python_startup(rel):
1272
+ """Whether a path's own name says Python runs it as it starts, wherever it stands and whether it is there or not:
1273
+ a pyvenv.cfg, a .pth file in a site-packages folder, a sitecustomize or usercustomize in any form. A whole
1274
+ environment deleted takes its folders with it, and what it held back went unnamed (the review of PYTHON-ENV)."""
1275
+ parts = rel.split("/")
1276
+ name = parts[-1].casefold()
1277
+ if name == "pyvenv.cfg" or (name.endswith(".pth") and len(parts) > 1 and parts[-2].casefold() == "site-packages"):
1278
+ return True
1279
+ return any(part.split(".", 1)[0].casefold() in PYTHON_STARTUP_MODULES for part in parts[-3:])
1280
+
1281
+
1282
+ def environment_in_tree(root):
1283
+ """[(what, path)] for each thing this polyctl runs from, loads or trusts that lies inside the tree an agent writes: the
1284
+ Python environment it runs from, its own code, each PYTHONPATH folder, and each path a POLYCTL_ variable names
1285
+ (PYTHON-ENV).
1286
+
1287
+ A .pth file or a module in any of them has run before polyctl can name it, so naming is all polyctl can do for the run that
1288
+ finds it: the place is the person's to move outside the tree. Read from this process's own environment, which is
1289
+ the person's shell for `polyctl doctor` and the job's for the watchdog.
1290
+ """
1291
+ try:
1292
+ top = os.fsdecode(_git_output(root, "rev-parse", "--show-toplevel")).strip()
1293
+ except RuntimeError:
1294
+ top = root
1295
+ found = []
1296
+ if _in_tree(sys.prefix, top):
1297
+ found.append(("the Python environment polyctl runs from", sys.prefix))
1298
+ if _in_tree(_HERE, top):
1299
+ found.append(("polyctl's own code", _HERE))
1300
+ for entry in (os.environ.get("PYTHONPATH") or "").split(os.pathsep):
1301
+ if entry and _in_tree(entry, top):
1302
+ found.append(("PYTHONPATH", entry))
1303
+ for name in POLYCTL_PATH_VARIABLES:
1304
+ value = os.environ.get(name)
1305
+ if value and _in_tree(value, top):
1306
+ found.append((name, value))
1307
+ return found
1308
+
1309
+
1310
+ def project_config_changes(root, names=None, shown=None, key=None):
1311
+ """[(path, state, sha256 or None)], sorted by path: each path in the working tree that a harness reads from a
1312
+ project as its configuration or instructions - `project_config_member` names it - and that differs from HEAD
1313
+ (HARNESS-CONFIG).
1314
+
1315
+ The state is one of HARNESS_CONFIG_STATES, the digest is of the bytes a harness reads there, through a link where
1316
+ one stands, and None for a path deleted. Staged or not, git status names each change, an untracked file one by
1317
+ one, and an ignored one too: a harness reads a gitignored .claude/settings.local.json all the same. An ignored
1318
+ folder git names without descending is read here only when it is configuration itself, or the start of a declared
1319
+ name such as `.github` of `.github/hooks`, so a node_modules/ is never walked. A folder that holds a repository of
1320
+ its own is read like any other - a plugin cloned into .opencode/plugin/ is configuration - unless it is a worktree
1321
+ of this repository at the path where a harness keeps its lanes. A configuration alias to that worktree is read
1322
+ under the alias, where the harness reaches it (LEADS-ADAPTERS). A tracked file git is told to skip
1323
+ (`update-index --assume-unchanged` or `--skip-worktree`) is left out of git status, so it is compared with HEAD's
1324
+ blob by content; one a sparse checkout leaves out of the tree is no change. What Python runs as it starts from
1325
+ inside the tree - a .pth file, a sitecustomize or usercustomize - is configuration in the same way, under the state
1326
+ "python" (python_startup_files, PYTHON-ENV).
1327
+
1328
+ `shown`, when given, is filled with {path: view} of the bytes each digest was taken of (_harness_read), so what a
1329
+ person is shown is what they record. Raises RuntimeError when git or a file cannot be read, and past
1330
+ HARNESS_CONFIG_LIMIT changes.
1331
+ """
1332
+ git_env = {"GIT_OPTIONAL_LOCKS": "0"}
1333
+ names = project_config_names() if names is None else names
1334
+ firsts = {entry[0] for entry in names}
1335
+ worktree_dirs = harness_worktree_dirs()
1336
+ top = os.fsdecode(_git_output(root, "rev-parse", "--show-toplevel", env=git_env)).strip()
1337
+ changes, visited, walking, worktrees, startup, startup_folders = {}, set(), set(), [], set(), {}
1338
+
1339
+ def parts_of(rel):
1340
+ return [_config_part(part) for part in rel.split("/") if part not in ("", ".")]
1341
+
1342
+ def member(rel):
1343
+ return (bool(firsts.intersection(parts_of(rel))) and project_config_member(rel, names) is not None) \
1344
+ or starts_python(rel)
1345
+
1346
+ def starts_python(rel):
1347
+ # What Python runs as it starts from inside the tree is configuration too, a sitecustomize package's own
1348
+ # files among it (PYTHON-ENV); and a name of that kind in a folder Python starts from, there or not - a
1349
+ # deleted sitecustomize took what it held back with it (the review of PYTHON-ENV).
1350
+ if rel in startup or any(rel.startswith(path + "/") for path in startup) or _names_python_startup(rel):
1351
+ return True
1352
+ folder, _, name = rel.rpartition("/")
1353
+ cached = folder.rpartition("/")[2] == "__pycache__"
1354
+ site_dir = startup_folders.get(folder.rpartition("/")[0] if cached else folder)
1355
+ if site_dir is None:
1356
+ return False
1357
+ return name.split(".", 1)[0].casefold() in PYTHON_STARTUP_MODULES \
1358
+ or (site_dir and not cached and name.casefold().endswith(".pth"))
1359
+
1360
+ def leads_to(rel):
1361
+ # A folder no name is declared for that a longer declared name starts with: `.github` of `.github/hooks`.
1362
+ parts = parts_of(rel)
1363
+ return any(len(parts) >= width and tuple(parts[-width:]) == entry[:width]
1364
+ for entry in names for width in range(1, len(entry)))
1365
+
1366
+ def full_path(rel):
1367
+ return os.path.join(top, *rel.split("/"))
1368
+
1369
+ def record(rel, state, sha, view):
1370
+ if rel in changes:
1371
+ return
1372
+ if len(changes) >= HARNESS_CONFIG_LIMIT:
1373
+ raise RuntimeError(f"more than {HARNESS_CONFIG_LIMIT} changes to what a harness reads here, more than polyctl "
1374
+ f"reads to tell what changed; {rel} is past them")
1375
+ changes[rel] = (state, sha)
1376
+ if shown is not None:
1377
+ shown[rel] = view
1378
+
1379
+ def own_worktree(full):
1380
+ if not worktrees:
1381
+ worktrees.append({os.path.normcase(os.path.realpath(tree["path"])) for tree in worktree_list(top)})
1382
+ return os.path.normcase(os.path.realpath(full)) in worktrees[0]
1383
+
1384
+ def take(rel, state, everything=True):
1385
+ full = full_path(rel)
1386
+ if os.path.islink(full):
1387
+ target = os.readlink(full)
1388
+ link = b"link\0" + os.fsencode(target)
1389
+ if os.path.isdir(full):
1390
+ record(rel, state, _kind_digest("link", link), ("link", target, None))
1391
+ walk(rel, state, everything=everything)
1392
+ return
1393
+ inner, view = _harness_read(full)
1394
+ record(rel, state, _kind_digest("link", link + b"\0" + inner.encode(UTF8)), ("link", target, view))
1395
+ elif os.path.isdir(full):
1396
+ walk(rel, state, everything=everything) # a submodule, or a folder git named
1397
+ elif not os.path.lexists(full):
1398
+ record(rel, "deleted", None, ("deleted",))
1399
+ else:
1400
+ record(rel, state, *_harness_read(full))
1401
+
1402
+ def walk(rel, state, everything):
1403
+ full = full_path(rel)
1404
+ real = os.path.normcase(os.path.realpath(full))
1405
+ # A completed walk stands only for its declared path: another harness name can read the same directory,
1406
+ # even a worktree skipped at its lane path. Active walks keep their scope too: .github/hooks -> . must
1407
+ # read the whole directory while its .github parent is reading declared names only (LEADS-ADAPTERS).
1408
+ if (real, everything) in walking or (rel, True) in visited or (rel, everything) in visited:
1409
+ return
1410
+ if os.path.lexists(os.path.join(full, ".git")) and tuple(parts_of(rel)[:-1]) in worktree_dirs \
1411
+ and own_worktree(full):
1412
+ return
1413
+ walking.add((real, everything))
1414
+ try:
1415
+ try:
1416
+ entries = sorted(os.listdir(full))
1417
+ except OSError as exc:
1418
+ raise RuntimeError(f"{rel}/ cannot be read ({exc.strerror or exc})") from None
1419
+ for name in entries:
1420
+ sub = f"{rel}/{name}"
1421
+ if name == ".git":
1422
+ continue
1423
+ if os.path.isdir(os.path.join(full, name)) and not os.path.islink(os.path.join(full, name)):
1424
+ if _config_part(name) == "node_modules":
1425
+ continue
1426
+ if everything or member(sub):
1427
+ walk(sub, state, everything=True)
1428
+ elif leads_to(sub):
1429
+ walk(sub, state, everything=False)
1430
+ elif everything or member(sub):
1431
+ take(sub, state)
1432
+ elif leads_to(sub) and os.path.islink(full_path(sub)):
1433
+ take(sub, state, everything=False)
1434
+ finally:
1435
+ walking.remove((real, everything))
1436
+ visited.add((rel, everything))
1437
+
1438
+ listed = {}
1439
+ for item in _git_output(top, "status", "--porcelain=v1", "-z", "--untracked-files=all", "--ignored=matching",
1440
+ "--no-renames", env=git_env).split(b"\0"):
1441
+ if len(item) > 3:
1442
+ listed.setdefault(os.fsdecode(item[3:]), []).append(item[:2].decode("ascii", "replace"))
1443
+ startup.update(python_startup_files(top, listed, startup_folders))
1444
+ for rel, codes in sorted(listed.items()):
1445
+ tracked = [code for code in codes if code not in ("??", "!!")]
1446
+ state = ("ignored" if "!!" in codes else "untracked" if not tracked
1447
+ else "added" if any(code[0] == "A" for code in tracked) else "modified")
1448
+ if rel.endswith("/"):
1449
+ # A folder git does not descend into: ignored as a whole, or a repository of its own.
1450
+ folder = rel.rstrip("/")
1451
+ if member(folder):
1452
+ walk(folder, state, everything=True)
1453
+ elif leads_to(folder):
1454
+ walk(folder, state, everything=False)
1455
+ elif member(rel):
1456
+ take(rel, "python" if starts_python(rel) else state)
1457
+ elif leads_to(rel) and os.path.islink(full_path(rel)):
1458
+ # A declared prefix can itself be a link: .github -> settings still exposes its hooks, though the
1459
+ # prefix is no configuration name of its own (LEADS-ADAPTERS).
1460
+ take(rel, state, everything=False)
1461
+ # What Python runs as it starts, in a folder git names without descending into it - an ignored environment's
1462
+ # site-packages - is read there; one git tracks unchanged is HEAD's, and no change (PYTHON-ENV).
1463
+ folders = [rel for rel in listed if rel.endswith("/")]
1464
+ for rel in sorted(startup):
1465
+ if rel not in changes and any(rel.startswith(folder) for folder in folders):
1466
+ take(rel, "python")
1467
+ # What was committed since the last granted tree is no review's either: it is read as it stands now.
1468
+ since = harness_config_base(top, key=key)
1469
+ if since:
1470
+ for item in _git_output(top, "diff", "--name-only", "-z", "--no-renames", since, "HEAD", "--",
1471
+ env=git_env).split(b"\0"):
1472
+ rel = os.fsdecode(item)
1473
+ if item and rel not in changes and member(rel):
1474
+ # what Python runs as it starts says so, as it does uncommitted (the review of PYTHON-ENV)
1475
+ take(rel, "python" if starts_python(rel) else "committed")
1476
+ # A link git tracks unchanged is read through as well: what it leads to can change while the link does not, and git
1477
+ # names that change at the target's own path, which may be no configuration at all (the review of HARNESS-CONFIG).
1478
+ for item in _git_output(top, "ls-files", "-s", "-z", env=git_env).split(b"\0"):
1479
+ meta, _, path = item.partition(b"\t")
1480
+ rel = os.fsdecode(path)
1481
+ if meta.startswith(b"120000 ") and rel not in changes and (member(rel) or leads_to(rel)):
1482
+ take(rel, "linked", everything=member(rel))
1483
+ # A tracked ordinary file at a prefix can become a directory link while assume-unchanged hides it from
1484
+ # status; its declared children still count, without reading the rest of its target (LEADS-ADAPTERS).
1485
+ _hidden_config_changes(top, lambda rel: member(rel) or (leads_to(rel) and os.path.islink(full_path(rel))),
1486
+ lambda rel, state: take(rel, state, everything=member(rel)), record, changes)
1487
+ return sorted(((rel, state, sha) for rel, (state, sha) in changes.items()), key=lambda change: change[0])
1488
+
1489
+
1490
+ def _hidden_config_changes(top, member, take, record, changes):
1491
+ """Add every tracked file a harness reads whose content is not HEAD's, whatever git status said (HARNESS-CONFIG).
1492
+
1493
+ git status trusts its stat cache: a file rewritten at its old size with its modification time put back - where the
1494
+ change time is not checked, as on Windows - reads as unchanged (the review of HARNESS-CONFIG); and one marked
1495
+ assume-unchanged (`h`, any lower-case tag of `git ls-files -v`) or skip-worktree (`S`) is left out of it
1496
+ altogether. Each is hashed as git would store it and compared with HEAD's blob."""
1497
+ hidden, git_env = [], {"GIT_OPTIONAL_LOCKS": "0"}
1498
+ for item in _git_output(top, "ls-files", "-v", "-z", env=git_env).split(b"\0"):
1499
+ tag, rel = item[:1].decode("ascii", "replace"), os.fsdecode(item[2:])
1500
+ if len(item) > 2 and rel not in changes and member(rel):
1501
+ hidden.append((rel, tag))
1502
+ if not hidden:
1503
+ return
1504
+ heads = {}
1505
+ try:
1506
+ listed = _git_output(top, "--literal-pathspecs", "ls-tree", "-r", "-z", "HEAD", "--",
1507
+ *[rel for rel, _ in hidden], env=git_env)
1508
+ except RuntimeError:
1509
+ listed = b"" # no commit yet: each of them is new to HEAD
1510
+ for item in listed.split(b"\0"):
1511
+ meta, _, path = item.partition(b"\t")
1512
+ fields = meta.split()
1513
+ if len(fields) == 3:
1514
+ heads[os.fsdecode(path)] = (fields[0].decode("ascii"), fields[2].decode("ascii"))
1515
+ full = {rel: os.path.join(top, *rel.split("/")) for rel, _ in hidden}
1516
+ files = [rel for rel, _ in hidden if os.path.isfile(full[rel]) and not os.path.islink(full[rel])]
1517
+ # Hashed as git would store them, filters and line endings applied, so a checkout's CRLF is no change.
1518
+ work = dict(zip(files, _git_output(top, "hash-object", "--", *files, env=git_env).decode("ascii").split())) \
1519
+ if files else {}
1520
+ sparse = None
1521
+ for rel, tag in hidden:
1522
+ head = heads.get(rel)
1523
+ if not os.path.lexists(full[rel]):
1524
+ if head is None:
1525
+ continue
1526
+ if tag in "Ss":
1527
+ # A sparse checkout keeps out of the tree what lies outside its cone, and marks it skip-worktree.
1528
+ if sparse is None:
1529
+ sparse = _git_text(top, "config", "--bool", "core.sparseCheckout", env=git_env) == "true"
1530
+ if sparse:
1531
+ continue
1532
+ record(rel, "deleted", None, ("deleted",))
1533
+ elif os.path.islink(full[rel]):
1534
+ if head is None or head[0] != "120000" \
1535
+ or _git_output(top, "cat-file", "blob", head[1], env=git_env) != os.fsencode(os.readlink(full[rel])):
1536
+ take(rel, "hidden" if tag == "S" or tag.islower() else "modified")
1537
+ elif head is None or work.get(rel) != head[1]:
1538
+ take(rel, "hidden" if tag == "S" or tag.islower() else "modified")
1539
+
1540
+
1541
+ def harness_config_digest(changes):
1542
+ """The digest of a list of changes: each path and the digest of what stands there, never its state, so a change
1543
+ staged after it was seen is the change that was seen (HARNESS-CONFIG)."""
1544
+ digest = hashlib.sha256()
1545
+ _digest_field(digest, b"format", b"polyctl-harness-config-v1")
1546
+ for path, _, sha in sorted(changes, key=lambda change: change[0]):
1547
+ _digest_field(digest, b"path", path.encode(UTF8, "surrogatepass"))
1548
+ _digest_field(digest, b"content", (sha or "deleted").encode("ascii"))
1549
+ return "sha256:" + digest.hexdigest()
1550
+
1551
+
1552
+ def harness_seen_record(root, key=None):
1553
+ """What a person last recorded as seen of this project's harness configuration, or None (HARNESS-CONFIG)."""
1554
+ try:
1555
+ with open(project_file(root, "harness-seen", key=key), encoding=UTF8) as fh:
1556
+ record = json.load(fh)
1557
+ except (OSError, ValueError):
1558
+ return None
1559
+ return record if isinstance(record, dict) else None
1560
+
1561
+
1562
+ def harness_unseen(changes, record):
1563
+ """The changes a person's record does not hold as they stand: each is seen by its path and its content, so a seen
1564
+ change that lands leaves the others seen (HARNESS-CONFIG). What polyctl wrote itself is seen as it wrote it
1565
+ (HARNESS-SEEN-OWN)."""
1566
+ record = record or {}
1567
+ seen = {(item.get("path"), item.get("sha256")) for item in list(record.get("changes") or [])
1568
+ + list(record.get("written") or []) if isinstance(item, dict)}
1569
+ return [change for change in changes if (change[0], change[2]) not in seen]
1570
+
1571
+
1572
+ def record_harness_written(root, files, by):
1573
+ """Record as seen each file polyctl wrote into what a harness reads whose bytes are polyctl's own rendering and nothing else;
1574
+ the paths recorded, relative to the repository (HARNESS-SEEN-OWN).
1575
+
1576
+ `files` is [(path, the bytes polyctl's write leaves there)]. After HARNESS-CONFIG the playbook, the coordination steering
1577
+ and the MCP entry `polyctl init` and `polyctl skill install` write held every turn until a person ran `polyctl harness seen`,
1578
+ though no agent wrote a byte of them. A file is recorded only while it holds exactly what polyctl renders - a fresh
1579
+ write, or one an earlier run left as it was - and by the digest of that rendering, never of what is read back: a
1580
+ person's rule file polyctl adds its pointer to holds other text, and one an agent changed before or after the write
1581
+ reads as other bytes, so neither is seen. Kept beside what a person recorded, in the same file in ~/.polyctl, and only
1582
+ for a polyctl project: a folder with no .polyctl/ shares a key with whatever project bears its name. What cannot be read or
1583
+ written is not recorded, and the files read as unseen, which holds until a person sees them.
1584
+ """
1585
+ from .storage import _exclusive_lock, replace_file_durably
1586
+ if not os.path.isdir(os.path.join(root, ".polyctl")):
1587
+ return []
1588
+ try:
1589
+ top = os.path.realpath(os.fsdecode(_git_output(root, "rev-parse", "--show-toplevel")).strip())
1590
+ except RuntimeError:
1591
+ return []
1592
+ names, now, ours = project_config_names(), int(time.time()), {}
1593
+ for path, data in files:
1594
+ rel = os.path.relpath(os.path.realpath(path), top).replace(os.sep, "/")
1595
+ if rel.startswith("../") or rel == ".." or os.path.islink(path) or project_config_member(rel, names) is None:
1596
+ continue
1597
+ expected = hashlib.sha256(data).hexdigest()
1598
+ try:
1599
+ sha, view = _harness_read(path)
1600
+ except RuntimeError:
1601
+ continue
1602
+ if view[0] == "file" and sha == expected:
1603
+ ours[rel] = {"path": rel, "sha256": expected, "by": by, "at": now}
1604
+ if not ours:
1605
+ return []
1606
+ target = project_file(root, "harness-seen")
1607
+ try:
1608
+ # Init and a person's acceptance shared an unlocked read-modify-write and lost each other's entries
1609
+ # (LEADS-OPEN). Only the record merge needs the lock, not reading the project's files.
1610
+ with _exclusive_lock(project_file(root, "harness-seen-lock")):
1611
+ record = harness_seen_record(root) or {}
1612
+ record["written"] = [item for item in record.get("written") or []
1613
+ if isinstance(item, dict) and item.get("path") not in ours] + list(ours.values())
1614
+ os.makedirs(os.path.dirname(target), exist_ok=True)
1615
+ replace_file_durably(target, (json.dumps(record, indent=1, sort_keys=True) + "\n").encode(UTF8))
1616
+ except OSError:
1617
+ return []
1618
+ return sorted(ours)
1619
+
1620
+
1621
+ def unseen_harness_config(root):
1622
+ """The changes to what a harness reads from this tree that no person has seen as they stand; [] when nothing
1623
+ differs from HEAD (HARNESS-CONFIG), and each role's command is the one last accepted (TURN-ARGV). Raises
1624
+ RuntimeError when they cannot be read."""
1625
+ # The first reading keeps HEAD to measure from, where `polyctl init` left none: a project adopted before polyctl kept one.
1626
+ record_harness_baseline(root, "first reading")
1627
+ # And each role's command as it stands, where none is accepted yet (TURN-ARGV).
1628
+ record_turn_baseline(root, "first reading")
1629
+ changes = harness_config_changes(root)
1630
+ return harness_unseen(changes, harness_seen_record(root)) if changes else []
1631
+
1632
+
1633
+ def record_harness_seen(root, changes, by, digest):
1634
+ """Record that a person has seen each of `changes` as it stands (HARNESS-CONFIG).
1635
+
1636
+ Kept in this project's file in ~/.polyctl, outside the tree an agent writes, and written whole. `digest` is of what the
1637
+ person was shown; beside the name they gave, polyctl records what it can check, the login and whether a terminal was
1638
+ attached, as a waiver does.
1639
+ """
1640
+ from .storage import _exclusive_lock, replace_file_durably
1641
+ user, interactive = _login_and_terminal()
1642
+ # The HEAD it was seen at is measured from after it: what is committed later is a change again (HARNESS-CONFIG).
1643
+ head = _git_text(root, "rev-parse", "--verify", "-q", "HEAD")
1644
+ # Keep polyctl's own writes beside the person's snapshot, read under the same lock (LEADS-OPEN).
1645
+ with _exclusive_lock(project_file(root, "harness-seen-lock")):
1646
+ record = {"digest": digest, "by": by, "at": int(time.time()), "user": user, "interactive": interactive,
1647
+ "head": head if re.fullmatch(r"[0-9a-f]{40}|[0-9a-f]{64}", head) else None,
1648
+ "changes": [{"path": path, "state": state, "sha256": sha} for path, state, sha in changes],
1649
+ # What polyctl wrote itself stays seen beside it (HARNESS-SEEN-OWN).
1650
+ "written": list((harness_seen_record(root) or {}).get("written") or [])}
1651
+ path = project_file(root, "harness-seen")
1652
+ os.makedirs(os.path.dirname(path), exist_ok=True)
1653
+ replace_file_durably(path, (json.dumps(record, indent=1, sort_keys=True) + "\n").encode(UTF8))
1654
+ # A role's command seen is the one accepted from now on, and a change from it is measured from there (TURN-ARGV).
1655
+ record_turns_seen(root, changes, by)
1656
+ return record
1657
+
1658
+
1659
+ def harness_config_line(changes, limit=None):
1660
+ """`a (modified), b (untracked)`, and `and N more` past `limit`, for a line a person reads (HARNESS-CONFIG)."""
1661
+ named = [f"{shown_text(path)} ({HARNESS_CONFIG_STATES.get(state, state)})" for path, state, _ in changes]
1662
+ if limit is not None and len(named) > limit:
1663
+ return ", ".join(named[:limit]) + f" and {len(named) - limit} more"
1664
+ return ", ".join(named)
1665
+
1666
+
1667
+ def role_pin(argv, role, adapter=None):
1668
+ """[(flag, value)] an adapter pins on every turn polyctl starts in `role` (`options.pin`); a hunter holds the reviewer's."""
1669
+ adapter = command_adapter(argv) if adapter is None else adapter
1670
+ declared = ((adapter or {}).get("options") or {}).get("pin")
1671
+ pin = declared.get(role) if isinstance(declared, dict) else None
1672
+ return _flag_pairs(pin) if isinstance(pin, list) else []
1673
+
1674
+
1675
+ def pinned_argv(argv, role, adapter=None):
1676
+ """(argv, added): `argv` with each flag its adapter pins for `role` that it does not name, appended (GRANTS-PINNED).
1677
+
1678
+ A harness that takes its permission mode from a person's settings when a command names
1679
+ none lets a default there widen every turn polyctl starts. A command composed before the pin,
1680
+ or written by hand, gets it when its turn starts. One that names the flag keeps its own
1681
+ value, which `pin_conflicts` reports; one that grants every tool is reported as that and
1682
+ left as it is.
1683
+ """
1684
+ argv = list(argv or [])
1685
+ adapter = command_adapter(argv) if adapter is None else adapter
1686
+ trust_all = ((adapter or {}).get("options") or {}).get("trust_all") or []
1687
+ if not adapter or _holds(argv, trust_all):
1688
+ return argv, []
1689
+ added = []
1690
+ for flag, value in role_pin(argv, role, adapter):
1691
+ if not _named(argv + added, flag)[0]:
1692
+ added += [flag] + ([value] if value is not None else [])
1693
+ return argv + added, added
1694
+
1695
+
1696
+ def pin_conflicts(argv, role, adapter=None):
1697
+ """What an argv sets otherwise than its adapter pins for `role`, as phrases; empty when it holds the pin (GRANTS-PINNED).
1698
+
1699
+ A tool list that names no more than the pinned list is narrower, and no conflict.
1700
+ """
1701
+ out = []
1702
+ args = [str(arg) for arg in argv or []]
1703
+ for flag, value in role_pin(argv, role, adapter):
1704
+ if value is None:
1705
+ continue
1706
+ # Every occurrence is asked: a harness takes the last of two, or refuses them, and the first said nothing.
1707
+ for at, arg in enumerate(args):
1708
+ if arg == flag:
1709
+ given = args[at + 1] if at + 1 < len(args) and not args[at + 1].startswith("-") else None
1710
+ elif arg.startswith(flag + "="):
1711
+ given = arg.split("=", 1)[1]
1712
+ else:
1713
+ continue
1714
+ if given == value:
1715
+ continue
1716
+ if (given is not None and (flag in GRANT_FLAGS + ("--tools", "--trust-tools") or "," in value)
1717
+ and set(split_tool_list(given)) <= set(split_tool_list(value))):
1718
+ continue
1719
+ out.append(f"it runs with {flag} {given if given is not None else '(no value)'}, where polyctl pins {value}")
1720
+ return out
1721
+
1722
+
1723
+ def bypass_arguments(argv):
1724
+ """The arguments of an argv that approve everything, sandbox nothing or check no permission, as
1725
+ `options.bypass` names them: the argument itself, or a flag and the value after it."""
1726
+ args = [str(arg) for arg in argv or []]
1727
+ found = []
1728
+ for at, arg in enumerate(args):
1729
+ flag, equals, value = arg.partition("=")
1730
+ if not flag.startswith("-"):
1731
+ continue
1732
+ if BYPASS_FLAG.fullmatch(flag) or (equals and BYPASS_VALUE.fullmatch(value)):
1733
+ found.append(arg)
1734
+ elif not equals and at + 1 < len(args) and BYPASS_VALUE.fullmatch(args[at + 1]):
1735
+ found.append(f"{arg} {args[at + 1]}")
1736
+ return found
1737
+
1738
+
1739
+ def role_commands(adapter):
1740
+ """{role: argv} for each role polyctl starts from an adapter's own declarations, as it starts them (GRANTS-PINNED).
1741
+
1742
+ The implementer's nudge is its resume with what polyctl appends to a turn nobody attends; the
1743
+ architect's wake is its resume, whose tool grant polyctl replaces with the architect's own; a
1744
+ reviewer route is its send with trust_none, where the adapter may review. Each carries its pin,
1745
+ and the grant of a nudge or a wake admits what a command rewriter makes of each command it
1746
+ names, as the watchdog starts them (GRANTS-RTK).
1747
+ """
1748
+ adapter = adapter or {}
1749
+ options = adapter.get("options") or {}
1750
+ commands = {}
1751
+ resume = (adapter.get("resume") or {}).get("argv") if isinstance(adapter.get("resume"), dict) else None
1752
+ if isinstance(resume, list) and resume:
1753
+ own = admit_rewrites(resume)[0]
1754
+ commands["implementer"] = pinned_argv(own + unattended_flags(adapter, resume)[0], "implementer", adapter)[0]
1755
+ commands["architect"] = pinned_argv(own, "architect", adapter)[0]
1756
+ send = (adapter.get("send") or {}).get("argv") if isinstance(adapter.get("send"), dict) else None
1757
+ if isinstance(send, list) and send and reviewer_eligibility(adapter)[0]:
1758
+ denied = [] if tool_review_contract(adapter) is not None else list(options.get("trust_none") or [])
1759
+ commands["reviewer"] = pinned_argv(list(send) + denied, "reviewer", adapter)[0]
1760
+ return commands
1761
+
1762
+
1763
+ def declared_bypass(adapter):
1764
+ """{argument: {roles, why, sandbox}} an adapter declares in `options.bypass`, the well-formed entries only."""
1765
+ declared = ((adapter or {}).get("options") or {}).get("bypass")
1766
+ return {str(argument): entry for argument, entry in declared.items() if isinstance(entry, dict)} \
1767
+ if isinstance(declared, dict) else {}
1768
+
1769
+
1770
+ def bypass_problems(adapter):
1771
+ """Each argument that approves everything, sandboxes nothing or checks no permission in a command polyctl starts
1772
+ from an adapter with no reason in `options.bypass` for that role, and each reason no command needs (GRANTS-PINNED).
1773
+
1774
+ A new flag of that kind is refused until someone writes down why it is there, and a reason
1775
+ outlives no flag.
1776
+ """
1777
+ options = (adapter or {}).get("options") or {}
1778
+ if options.get("bypass") is not None and not isinstance(options["bypass"], dict):
1779
+ return ["`options.bypass` must be an object: each argument, the roles whose command carries it, and why"]
1780
+ declared = declared_bypass(adapter)
1781
+ carried = {}
1782
+ for role, argv in role_commands(adapter).items():
1783
+ for argument in bypass_arguments(argv):
1784
+ carried.setdefault(argument, set()).add(role)
1785
+
1786
+ def commands(roles):
1787
+ return f"the {' and the '.join(roles)} command" + ("s" if len(roles) > 1 else "")
1788
+
1789
+ problems = []
1790
+ for argument, roles in sorted(carried.items()):
1791
+ entry = declared.get(argument) or {}
1792
+ unexplained = sorted(roles if not str(entry.get("why") or "").strip()
1793
+ else roles - set(entry.get("roles") or []))
1794
+ if unexplained:
1795
+ problems.append(f"{commands(unexplained)} {'carry' if len(unexplained) > 1 else 'carries'} `{argument}`, "
1796
+ "and `options.bypass` gives no reason for it there")
1797
+ for argument, entry in sorted(declared.items()):
1798
+ stale = sorted(set(entry.get("roles") or []) - carried.get(argument, set()))
1799
+ if stale:
1800
+ problems.append(f"`options.bypass` gives a reason for `{argument}` in {commands(stale)}, which "
1801
+ f"{'do' if len(stale) > 1 else 'does'} not carry it")
1802
+ return problems
1803
+
1804
+
1805
+ def sandbox_bypass(adapter, flags):
1806
+ """The arguments among `flags` that turn off the sandbox a harness runs in by default (`options.bypass` →
1807
+ `sandbox`), as a shipped adapter or this one declares them: a layer an agent can write cannot take one away."""
1808
+ sandboxed = {argument for source in [*package_adapters().values(), adapter]
1809
+ for argument, entry in declared_bypass(source).items() if entry.get("sandbox")}
1810
+ return [argument for argument in bypass_arguments(flags) if argument in sandboxed]
1811
+
1812
+
1813
+ def bypass_refusal(adapter, flags, cfg=None):
1814
+ """Why an unattended turn may not start with these flags, or None (GRANTS-PINNED).
1815
+
1816
+ A flag that turns off the sandbox its harness runs in by default starts a turn only for
1817
+ an adapter a person named in `watchdog.bypass_adapters`. That is a machine setting: a
1818
+ project's own files are writable by the agents it governs.
1819
+ """
1820
+ ident = str((adapter or {}).get("id") or "")
1821
+ found = sandbox_bypass(adapter, flags)
1822
+ if not found or ident in settings.get(cfg, "watchdog.bypass_adapters"):
1823
+ return None
1824
+ return (f"its unattended turn would run with {found[0]}, which turns off {ident}'s sandbox and its approvals, "
1825
+ f"and no person has allowed that on this machine (polyctl config set watchdog.bypass_adapters {ident} "
1826
+ "--machine)")
1827
+
1828
+
1829
+ # ---- the command a turn starts with is the package's, not the tree's (TURN-ARGV) ----------------
1830
+
1831
+ # The watchdog composed the implementer's nudge from its adapter as every layer loads it - the project's .polyctl/adapters/
1832
+ # among them - and started the architect's wake and refill with the argv its block in .polyctl/config.json names: files an
1833
+ # agent writes, so a change to either could start a command the agent chose, another program or a grant that admits a
1834
+ # hook bypass (#116). A turn polyctl starts unattended is composed from the adapter the package ships and checked against
1835
+ # it before it starts, and what its role's block says of it holds every turn, as harness configuration does, until a
1836
+ # person has seen it as it stands.
1837
+
1838
+ # The roles whose turns the watchdog starts, and the turns each one's command starts.
1839
+ TURN_ROLES = {"implementer": "a nudge", "architect": "a wake and a refill"}
1840
+ # A review and a hunt start a command a project's configuration names too - the reviewer's routes, `hunter.argv` -
1841
+ # in a file an agent writes, and each is held as a role's is (ROUTE-ARGV).
1842
+ ROUTE_KINDS = {"reviewer": "a review", "hunter": "a hunt"}
1843
+ # Every command polyctl starts whose change waits for a person, and what starts it.
1844
+ HELD_COMMANDS = dict(TURN_ROLES, **ROUTE_KINDS)
1845
+
1846
+
1847
+ def turn_adapter(ident):
1848
+ """The adapter a turn polyctl starts unattended is composed from and checked against: the one the package ships under
1849
+ `ident`, else None. Never a user's layer or a project's, which the agents they describe can write (TURN-ARGV)."""
1850
+ ident = str(ident or "").strip()
1851
+ adapter = package_adapters().get(ident) if ident else None
1852
+ return adapter if isinstance(adapter, dict) else None
1853
+
1854
+
1855
+ def turn_path(role):
1856
+ """How a role's command is named among the changes a person reads, beside the files they name (TURN-ARGV)."""
1857
+ return f"the {role}'s command"
1858
+
1859
+
1860
+ def turn_config(root, config=None):
1861
+ """The role blocks a turn's command is composed from, as load_config resolves them - the actor table, and the
1862
+ implementer a project that names none is found to run - from `config` or .polyctl/config.json, with no session read
1863
+ (TURN-ARGV)."""
1864
+ cfg = dict((project_config_document(root)["config"] if config is None else config) or {})
1865
+ resolve_roles(root, cfg)
1866
+ if "implementer" not in cfg:
1867
+ architect = cfg.get("architect") if isinstance(cfg.get("architect"), dict) else {}
1868
+ pinned = _concrete_session(architect.get("session"))
1869
+ found = discover_session(root, exclude={pinned} if pinned else ())
1870
+ if found:
1871
+ cfg["implementer"] = found
1872
+ return cfg
1873
+
1874
+
1875
+ def turn_identity(cfg, role):
1876
+ """What a role's block says of the command a turn of it starts - its adapter, and the implementer's model and effort
1877
+ or the architect's argv and refill prompt - or None for a role polyctl starts no turn of. The rest of the command is the
1878
+ shipped adapter's, or polyctl's (TURN-ARGV)."""
1879
+ if role == "hunter":
1880
+ argv = settings.get(cfg, "hunter.argv")
1881
+ return {"argv": argv} if argv else None
1882
+ block = cfg.get(role) if isinstance(cfg.get(role), dict) else None
1883
+ if role == "reviewer":
1884
+ # Every route a review can start, the fallbacks among them, and the capability matrix a strict project's
1885
+ # reviewers come from (ROUTE-ARGV).
1886
+ routes = [_route_fields(route) for route in reviewer_routes(cfg) if route]
1887
+ matrix = cfg.get("capability_matrix")
1888
+ if not routes and matrix is None:
1889
+ return None
1890
+ identity = {"routes": routes, "capability_matrix": matrix}
1891
+ # And how a review reaches them, once that is not by spawning each: set to acp, a route answers through its
1892
+ # adapter's ACP command, which carries none of the route's own flags, and the setting sat in the file the
1893
+ # implementer writes, outside what a person accepted. Spawn, the default, adds nothing, so a reviewer accepted
1894
+ # before is still the one accepted (REVIEW-PATH-HIGHS).
1895
+ transport = settings.get(cfg, "review.transport")
1896
+ if transport != settings.default("review.transport"):
1897
+ identity["transport"] = transport
1898
+ return identity
1899
+ if not block:
1900
+ return None
1901
+ if role == "implementer":
1902
+ return {"adapter": block.get("adapter"), "model": block.get("model"), "effort": block.get("effort")}
1903
+ if not block.get("argv"):
1904
+ return None
1905
+ return {"adapter": block.get("adapter"), "argv": block.get("argv"), "prompt": block.get("prompt")}
1906
+
1907
+
1908
+ def reviewer_routes(cfg):
1909
+ """The reviewer routes a project's configuration names, as dicts: its reviewer, then each of its fallbacks
1910
+ (ROUTE-ARGV)."""
1911
+ primary = cfg.get("reviewer") if isinstance(cfg.get("reviewer"), dict) else None
1912
+ if primary is None:
1913
+ return []
1914
+ fallbacks = primary.get("fallbacks") if isinstance(primary.get("fallbacks"), list) else []
1915
+ return [primary] + [route for route in fallbacks if isinstance(route, dict)]
1916
+
1917
+
1918
+ def _route_fields(route):
1919
+ """What a reviewer route says of itself, every field but its fallbacks and the marks polyctl puts beside it
1920
+ (ROUTE-ARGV)."""
1921
+ return {key: value for key, value in route.items() if not str(key).startswith("_") and key != "fallbacks"}
1922
+
1923
+
1924
+ def turn_digest(role, identity):
1925
+ """The digest a role's command is accepted by, of the role and what its block says; None where it says nothing."""
1926
+ if identity is None:
1927
+ return None
1928
+ return hashlib.sha256(json.dumps({"role": role, "turn": identity}, sort_keys=True).encode(UTF8)).hexdigest()
1929
+
1930
+
1931
+ def turn_record(root, key=None):
1932
+ """{role: {sha256, identity, by, at}}: each role's command as last accepted - by `polyctl init`, at the first reading, or
1933
+ by a person who saw it - kept in ~/.polyctl, outside the tree an agent writes; {} before any is (TURN-ARGV)."""
1934
+ try:
1935
+ with open(project_file(root, "harness-turns", key=key), encoding=UTF8) as fh:
1936
+ record = json.load(fh)
1937
+ except (OSError, ValueError):
1938
+ return {}
1939
+ if not isinstance(record, dict):
1940
+ return {}
1941
+ return {role: entry for role, entry in record.items() if role in HELD_COMMANDS and isinstance(entry, dict)}
1942
+
1943
+
1944
+ def _keep_turns(root, accepted, by, only_new=False):
1945
+ """Accept each role of `accepted`, {role: (digest, what its block says)}, by `by`, beside the roles accepted before,
1946
+ and with `only_new` only a role none is accepted for yet, as a first reading accepts; the roles kept, [] when they
1947
+ could not be written (TURN-ARGV).
1948
+
1949
+ Read and written under the project's harness lock. Two acceptances at once - `polyctl harness seen` and a watchdog's
1950
+ first reading - each read the record, added its roles and wrote it back, and the later dropped the earlier's; and a
1951
+ first reading that wrote a role accepted meanwhile put the command as it stood over a person's acceptance
1952
+ (LEADS-ADAPTERS)."""
1953
+ from .storage import _exclusive_lock, replace_file_durably
1954
+ target = project_file(root, "harness-turns")
1955
+ try:
1956
+ os.makedirs(os.path.dirname(target), exist_ok=True)
1957
+ with _exclusive_lock(project_file(root, "harness-lock")):
1958
+ record, now = turn_record(root), int(time.time())
1959
+ kept = [role for role in accepted if not (only_new and role in record)]
1960
+ for role in kept:
1961
+ digest, identity = accepted[role]
1962
+ record[role] = {"sha256": digest, "identity": identity, "by": by, "at": now}
1963
+ if kept:
1964
+ replace_file_durably(target, (json.dumps(record, indent=1, sort_keys=True) + "\n").encode(UTF8))
1965
+ except OSError:
1966
+ return []
1967
+ return [role for role in HELD_COMMANDS if role in kept]
1968
+
1969
+
1970
+ def _as_composed(cfg, roles):
1971
+ """{role: (digest, what its block says)} for each of `roles`, as `cfg` holds it (TURN-ARGV)."""
1972
+ return {role: (turn_digest(role, identity), identity) for role in roles for identity in [turn_identity(cfg, role)]}
1973
+
1974
+
1975
+ def record_turn_baseline(root, why):
1976
+ """Accept each role's command as it stands where none is accepted for it yet - `polyctl init`'s, or the first reading's
1977
+ in a project adopted before polyctl kept one - and a role with no command as having none, so a block added later is a
1978
+ change. Only in a polyctl project, as what polyctl writes is (HARNESS-SEEN-OWN), and not while a .polyctl/config.json that is
1979
+ there cannot be read, as load_config reads one; the roles recorded (TURN-ARGV)."""
1980
+ if not os.path.isdir(os.path.join(root, ".polyctl")):
1981
+ return []
1982
+ missing = [role for role in HELD_COMMANDS if role not in turn_record(root)]
1983
+ document = project_config_document(root) if missing else None
1984
+ if not missing or (document["problem"] and os.path.lexists(os.path.join(root, ".polyctl", "config.json"))):
1985
+ return []
1986
+ return _keep_turns(root, _as_composed(turn_config(root, document["config"]), missing), why, only_new=True)
1987
+
1988
+
1989
+ def record_turns_written(root, cfg, roles, by):
1990
+ """Accept the command of each of `roles` whose block polyctl composed itself - those `polyctl init` wrote - by the blocks it
1991
+ composed, `cfg`, never by what is read back, nor through an actor table it did not write: a block an agent changed
1992
+ before or after the write is another command, and stays unseen (HARNESS-SEEN-OWN, TURN-ARGV)."""
1993
+ roles = [role for role in roles if role in HELD_COMMANDS]
1994
+ if not roles or not os.path.isdir(os.path.join(root, ".polyctl")):
1995
+ return []
1996
+ return _keep_turns(root, _as_composed(cfg, roles), by)
1997
+
1998
+
1999
+ def record_turns_seen(root, changes, by):
2000
+ """Accept each role's command among `changes` that a person was shown, by the digest they were shown, with what its
2001
+ block says while that is still what stands (TURN-ARGV)."""
2002
+ paths = {turn_path(role): role for role in HELD_COMMANDS}
2003
+ seen = {paths[path]: sha for path, _, sha in changes if path in paths}
2004
+ if not seen:
2005
+ return []
2006
+ standing = _as_composed(turn_config(root), seen)
2007
+ return _keep_turns(root, {role: (sha, standing[role][1] if standing[role][0] == sha else None)
2008
+ for role, sha in seen.items()}, by)
2009
+
2010
+
2011
+ def turn_command(cfg, role):
2012
+ """(adapter, argv) of the command a turn of `role` starts, composed as the watchdog composes it, with its prompt and
2013
+ session left as placeholders; argv is None where nothing polyctl ships composes one (TURN-ARGV). A review's is its
2014
+ reviewer route's and a hunt's the hunter's, each with the flags a reviewer is pinned to (ROUTE-ARGV)."""
2015
+ if role in ROUTE_KINDS:
2016
+ routes = reviewer_routes(cfg) if role == "reviewer" else [{"argv": settings.get(cfg, "hunter.argv")}]
2017
+ route = routes[0] if routes else {}
2018
+ argv = route.get("argv")
2019
+ if not isinstance(argv, list) or not argv:
2020
+ return (block_adapter(route) if route else None), None
2021
+ return block_adapter(route), pinned_argv([str(part) for part in argv], "reviewer")[0]
2022
+ block = cfg.get(role) if isinstance(cfg.get(role), dict) else {}
2023
+ if role != "implementer":
2024
+ argv = block.get("argv")
2025
+ if not isinstance(argv, list) or not argv:
2026
+ return block_adapter(block), None
2027
+ return block_adapter(block), pinned_argv(admit_rewrites([str(part) for part in argv])[0], "architect")[0]
2028
+ ident = str(block.get("adapter") or "").strip() or None
2029
+ shipped = turn_adapter(ident) or {}
2030
+ resume = (shipped.get("resume") or {}).get("argv") if isinstance(shipped.get("resume"), dict) else None
2031
+ if not isinstance(resume, list) or not resume:
2032
+ return ident, None
2033
+ argv = admit_rewrites([str(part) for part in resume])[0]
2034
+ argv = pinned_argv(argv + unattended_flags(shipped, argv)[0], "implementer")[0]
2035
+ options = shipped.get("options") or {}
2036
+ for key in ("model", "effort"):
2037
+ value = block.get(key)
2038
+ if value and isinstance(options.get(key), list) and not any(str(arg).startswith(f"--{key}") for arg in argv):
2039
+ if key == "effort" and options.get("effort_values") and value not in options["effort_values"]:
2040
+ continue
2041
+ argv += [str(part).replace("{" + key + "}", str(value)) for part in options[key]]
2042
+ return ident, argv
2043
+
2044
+
2045
+ def turn_changes(root, shown=None, key=None):
2046
+ """[(path, "changed", digest)] for each role whose block says otherwise of its command than the one last accepted,
2047
+ the path `the architect's command`; with `shown`, what a person is shown of each, by its path (TURN-ARGV)."""
2048
+ record = turn_record(root) if key is None else turn_record(root, key=key)
2049
+ cfg, out = turn_config(root), []
2050
+ for role in HELD_COMMANDS:
2051
+ identity = turn_identity(cfg, role)
2052
+ accepted = record.get(role) or {}
2053
+ if identity is None or (role in record and accepted.get("sha256") == turn_digest(role, identity)):
2054
+ continue
2055
+ out.append((turn_path(role), "changed", turn_digest(role, identity)))
2056
+ if shown is not None:
2057
+ shown[turn_path(role)] = ("turn", role, identity, accepted.get("identity"), turn_command(cfg, role))
2058
+ return out
2059
+
2060
+
2061
+ def harness_config_changes(root, shown=None, key=None):
2062
+ """Every change that holds what polyctl starts in this tree until a person has seen it: each to what a harness reads from
2063
+ the tree (project_config_changes), and each role's command its block changed (turn_changes) (TURN-ARGV)."""
2064
+ changes = (project_config_changes(root, shown=shown) if key is None
2065
+ else project_config_changes(root, shown=shown, key=key))
2066
+ return changes + turn_changes(root, shown=shown, key=key)
2067
+
2068
+
2069
+ def unseen_turn(root, cfg, role):
2070
+ """The change no person has seen that a turn of `role` would start with, judged by `cfg`, the configuration its
2071
+ command was composed from: the file read again later can be put back between the two readings. None when its
2072
+ command is the one last accepted (TURN-ARGV)."""
2073
+ record_turn_baseline(root, "first reading")
2074
+ identity = turn_identity(cfg, role)
2075
+ if identity is None:
2076
+ return None
2077
+ digest = turn_digest(role, identity)
2078
+ if (turn_record(root).get(role) or {}).get("sha256") == digest:
2079
+ return None
2080
+ unseen = harness_unseen([(turn_path(role), "changed", digest)], harness_seen_record(root))
2081
+ return unseen[0] if unseen else None
2082
+
2083
+
2084
+ def _same_program(path, other):
2085
+ """Whether two paths, followed through their links, are one file (TURN-ARGV)."""
2086
+ return os.path.normcase(os.path.realpath(path)) == os.path.normcase(os.path.realpath(other))
2087
+
2088
+
2089
+ def turn_refusal(role, ident, argv, root=None, resolved=None, search=None, values=None, prompt=None):
2090
+ """Why the watchdog refuses to start a turn of `role` with `argv`, as a person reads it; None when it may
2091
+ (TURN-ARGV).
2092
+
2093
+ `argv` is the command as it would start, its program as the command names it, composed from adapter `ident`;
2094
+ `resolved` the file polyctl found for that program on `search`, once it has looked; `values` what polyctl fills into it from
2095
+ the role's block and its session, by name. The adapter is one the package ships; the program is its harness's,
2096
+ named alone or by where polyctl finds that harness, and never inside this repository; no value reads as a flag; and the
2097
+ grant admits nothing polyctl forbids the role that the command polyctl composes for it from the shipped adapter does not. No
2098
+ person's record lets a refused turn start: its configuration must change.
2099
+ """
2100
+ from . import allowlist as AL
2101
+ head = f"the watchdog refuses the {role}'s command:"
2102
+ shipped = turn_adapter(ident)
2103
+ program = str(argv[0]) if argv else ""
2104
+ if shipped is None:
2105
+ if ident:
2106
+ return (f"{head} its adapter {shown_text(ident)} is no adapter polyctl ships, and a turn polyctl starts unattended "
2107
+ "is composed from one the package ships, never one a user's or a project's layer declares")
2108
+ return f"{head} no adapter polyctl ships runs `{shown_text(program)}`" if program else f"{head} it names no adapter"
2109
+ binaries = _harness_programs(shipped)
2110
+ listed = ", ".join(binaries)
2111
+ if _program_name(program) not in {_program_name(name) for name in binaries}:
2112
+ return f"{head} it runs `{shown_text(program)}`, which is not {ident}'s program ({listed})"
2113
+ if not os.path.isabs(program) and os.path.dirname(program):
2114
+ return (f"{head} it names its program by a path from where it starts, `{shown_text(program)}`, where an agent "
2115
+ "can leave a program of its own")
2116
+ for name, value in sorted((values or {}).items()):
2117
+ if isinstance(value, str) and value.startswith("-"):
2118
+ return f"{head} its {name} `{shown_text(value)}` would be read as a flag, not as a {name}"
2119
+ if resolved and root and _within(resolved, root):
2120
+ return f"{head} its program would be {shown_text(resolved)}, inside this repository, which an agent writes"
2121
+ if resolved and os.path.isabs(program) and not any(
2122
+ _same_program(resolved, found) for name in binaries for found in binary_candidates(name, search)):
2123
+ return (f"{head} it runs {shown_text(program)}, which is not where polyctl finds {ident}'s program ({listed}) on "
2124
+ "the path it searches")
2125
+ own = {(reason, command) for reason, command, _ in AL.problems(role_commands(shipped).get(role) or [], {}, role)}
2126
+ for reason, command, rule in AL.problems(list(argv), {}, role, prompt=prompt):
2127
+ if (reason, command) not in own:
2128
+ return (f"{head} its grant admits `{command}` ({reason}) through {shown_text(rule)}, which {ident}'s own "
2129
+ f"{role} command does not")
2130
+ return None
2131
+
2132
+
2133
+ def _harness_programs(adapter):
2134
+ """The names a shipped adapter's harness runs as: those it detects, and the programs its send and resume start
2135
+ (TURN-ARGV, ROUTE-ARGV)."""
2136
+ names = list(adapter_binaries(adapter))
2137
+ for capability in ("send", "resume"):
2138
+ argv = (adapter.get(capability) or {}).get("argv") if isinstance(adapter.get(capability), dict) else None
2139
+ if isinstance(argv, list) and argv:
2140
+ names.append(os.path.basename(str(argv[0])))
2141
+ return list(dict.fromkeys(name for name in names if name))
2142
+
2143
+
2144
+ def route_refusal(kind, ident, argv, root=None, resolved=None, values=None):
2145
+ """Why polyctl refuses to start a review's or a hunt's command `argv`, as a person reads it; None when it may
2146
+ (ROUTE-ARGV).
2147
+
2148
+ `kind` is reviewer or hunter, `ident` the adapter the route names, if any; `resolved` the file polyctl found for its
2149
+ program, once it has looked, and `values` what polyctl fills into the command from the configuration, by name. A route
2150
+ is held to what turn_refusal holds a turn to, as each rule applies to one a project names. The adapter it names
2151
+ and the harness it runs agree: a route that names an adapter polyctl ships runs that adapter's own program, and one
2152
+ that runs a shipped harness's program names that harness or none, since the adapter a route names says its family,
2153
+ its prompt channel and its ACP command. No program is named by a path from where it starts, or lies inside this
2154
+ repository, and no value reads as a flag. A route that runs a program no adapter ships is written by hand, the
2155
+ exception docs/adapters.md keeps, whatever label it gives itself - a capability matrix names its tools' adapters
2156
+ in its own words: it is not refused here, and starts only as a person accepted it (hold_unseen_routes). An
2157
+ absolute program is taken as written, as `_reviewer_resolve_binary` takes it: a person accepted the route that
2158
+ names it. Whether it can write is allowlist.reviewer_problems' and reading_problems' to say, where it starts. No
2159
+ person's record lets a refused route start: its configuration must change.
2160
+ """
2161
+ from . import allowlist as AL
2162
+ head = f"polyctl refuses the {kind}'s command:"
2163
+ program = str(argv[0]) if argv else ""
2164
+ # A wrapper hid both the reviewer's engine and its tool permissions (TRIAGE-3-MEDIUM).
2165
+ if _program_name(program) in AL.WRAPPERS:
2166
+ return f"{head} a wrapper hides its harness; name the harness program directly"
2167
+ if not program:
2168
+ return f"{head} it names no program"
2169
+ named = str(ident or "").strip()
2170
+ shipped = turn_adapter(named) if named else None
2171
+ runs = command_adapter(argv)
2172
+ adapter = shipped or runs
2173
+ if named and shipped is None and runs is not None:
2174
+ return (f"{head} it runs `{shown_text(program)}`, {runs.get('id')}'s program, under adapter "
2175
+ f"{shown_text(named)}, which polyctl does not ship; name {runs.get('id')} or none")
2176
+ if adapter is not None:
2177
+ programs = _harness_programs(adapter)
2178
+ if _program_name(program) not in {_program_name(name) for name in programs}:
2179
+ return (f"{head} it runs `{shown_text(program)}`, which is not {adapter.get('id')}'s program "
2180
+ f"({', '.join(programs)})")
2181
+ if not os.path.isabs(program) and os.path.dirname(program):
2182
+ return (f"{head} it names its program by a path from where it starts, `{shown_text(program)}`, where an agent "
2183
+ "can leave a program of its own")
2184
+ for name, value in sorted((values or {}).items()):
2185
+ if isinstance(value, str) and value.startswith("-"):
2186
+ return f"{head} its {name} `{shown_text(value)}` would be read as a flag, not as a {name}"
2187
+ if resolved and program_in_repository(resolved, root):
2188
+ return f"{head} its program would be {shown_text(resolved)}, inside this repository, which an agent writes"
2189
+ return None
2190
+
2191
+
2192
+ def program_in_repository(path, root):
2193
+ """Whether a program lies inside the repository at `root`, where an agent can write it (ROUTE-ARGV).
2194
+
2195
+ polyctl's own install - the folder of the interpreter it runs on, and that interpreter's scripts folder, where an
2196
+ optional extra such as the API reviewer lands - is not asked, wherever it lies: the threat model leaves polyctl's
2197
+ install to the person, and a virtual environment kept in a tree holds polyctl itself too.
2198
+ """
2199
+ import sysconfig
2200
+ if not path or not root or not _within(path, root):
2201
+ return False
2202
+ try:
2203
+ scripts = sysconfig.get_path("scripts")
2204
+ except (KeyError, TypeError, ValueError):
2205
+ scripts = None
2206
+ own = {os.path.normcase(os.path.realpath(place)) for place in (os.path.dirname(sys.executable or ""), scripts)
2207
+ if place}
2208
+ return os.path.normcase(os.path.realpath(os.path.dirname(os.path.abspath(path)))) not in own
2209
+
2210
+
2211
+ def outside_repository(path, root):
2212
+ """A search path less each folder inside the repository at `root`, for finding a program polyctl starts: resolving one
2213
+ asks each candidate its version, which runs it, and an agent can leave a program under any name in a folder a
2214
+ PATH entry leads to inside the tree (ROUTE-ARGV). A path left with no folder names none, never the process's own
2215
+ PATH."""
2216
+ kept = os.pathsep.join(entry for entry in str(path or "").split(os.pathsep)
2217
+ if entry and not program_in_repository(os.path.join(entry, "program"), root))
2218
+ return kept or os.pathsep
2219
+
2220
+
2221
+ def note_routes_read(cfg):
2222
+ """Keep in `cfg`, as load_config read it, the digest of each command a review or a hunt would start, and return
2223
+ it (ROUTE-ARGV). Computed from `cfg` alone, so loading a configuration writes nothing; hold_unseen_routes judges
2224
+ what it notes."""
2225
+ cfg.pop("_routes_judged", None)
2226
+ cfg["_routes_read"] = {kind: turn_digest(kind, turn_identity(cfg, kind)) for kind in ROUTE_KINDS}
2227
+ return cfg
2228
+
2229
+
2230
+ def hold_unseen_routes(root, cfg):
2231
+ """Mark in `cfg` each command a review or a hunt would start, as the project's configuration was read, that no
2232
+ person has accepted, and return it (ROUTE-ARGV). A review, a probe and a hunt ask it where they start.
2233
+
2234
+ `cfg["_unseen"]` names each such kind with its change, and each reviewer route of an unseen reviewer carries the
2235
+ change itself, as `_unseen`, wherever polyctl takes it: a route starts only unmarked. Only what note_routes_read noted
2236
+ is judged, and only while it is still what `cfg` holds: never the file read again, since `polyctl review` is the
2237
+ implementer's to run and a route it wrote could be put back between polyctl reading it and the reviewer starting, and
2238
+ never a route polyctl composes in memory - `polyctl ci review`'s, or a test's - which is no project's configuration. Judged
2239
+ once for a `cfg`, against the record of the project at `root`. What cannot be compared is held, as harness
2240
+ configuration that cannot be read is.
2241
+ """
2242
+ if cfg.get("_routes_judged"):
2243
+ return cfg
2244
+ read = cfg.get("_routes_read") if isinstance(cfg.get("_routes_read"), dict) else {}
2245
+ cfg.pop("_unseen", None)
2246
+ for route in reviewer_routes(cfg):
2247
+ route.pop("_unseen", None)
2248
+ unseen = {}
2249
+ for kind in ROUTE_KINDS:
2250
+ if kind not in read or read[kind] != turn_digest(kind, turn_identity(cfg, kind)):
2251
+ continue
2252
+ try:
2253
+ change = unseen_turn(root, cfg, kind)
2254
+ except Exception as exc:
2255
+ change = (turn_path(kind), f"it cannot be compared with the one accepted "
2256
+ f"({' '.join(str(exc).split())[:160]})", None)
2257
+ if change:
2258
+ unseen[kind] = change
2259
+ if unseen:
2260
+ cfg["_unseen"] = unseen
2261
+ if unseen.get("reviewer"):
2262
+ for route in reviewer_routes(cfg):
2263
+ route["_unseen"] = unseen["reviewer"]
2264
+ cfg["_routes_judged"] = True
2265
+ return cfg
2266
+
2267
+
2268
+ def unseen_route_text(kind, change):
2269
+ """What a person reads of a route held because its change is unseen: what it is, and what lets it start
2270
+ (ROUTE-ARGV)."""
2271
+ return (f"{harness_config_line([change])}: {ROUTE_KINDS[kind]} starts no command a person has not accepted, and "
2272
+ f"no person has seen this one - a person reads it with polyctl harness seen --by <name>")
2273
+
2274
+
2275
+ # ---- a grant admits what a command rewriter makes of the commands it names (GRANTS-RTK) ----------
2276
+
2277
+ # Where the package declares its command rewriters, one file each: beside the adapters, not among them.
2278
+ REWRITERS_DIR = "rewriters"
2279
+ # How a rule names a command with any arguments after it, in the syntaxes the shipped grants are written in.
2280
+ RULE_WILDCARDS = (":*", " *")
2281
+ # A form is its rewriter's command and at least one more word, each of letters, digits, `_` and `-` only: a
2282
+ # wildcard would widen the rule the form becomes, a comma or a bracket would write another rule into the
2283
+ # grant, and a path would name a program the agent may have written.
2284
+ REWRITE_FORM = re.compile(r"[\w-]+(?: [\w-]+)+")
2285
+
2286
+
2287
+ def command_rewriters():
2288
+ """The command rewriters the package declares in adapters/rewriters/, one JSON file each (GRANTS-RTK).
2289
+
2290
+ A rewriter is a program a harness's hook hands an agent's shell commands to, and runs them
2291
+ rewritten: rtk turns `git diff` into `rtk git diff`. What it rewrites, and into what, is measured
2292
+ on one of its releases and written there rather than in any harness's adapter, since which
2293
+ harness runs the hook is the machine's business. Read from the package alone, as a review
2294
+ contract is: a layer an agent can write must not choose what its own grant admits. A file that
2295
+ cannot be read, or names no command, declares nothing: a grant then gains no rule for it, so
2296
+ what that rewriter rewrites stays blocked, as it was, rather than admitted wider. A file that is
2297
+ there and cannot be read is not the same as no file, though: the allowlist check reads the same
2298
+ declarations to know which grants admit a forbidden command in a rewriter's form, and a check
2299
+ that quietly lost them would pass a grant it exists to refuse. So a package file that does not
2300
+ parse raises, naming itself; only a package with no rewriters directory declares none.
2301
+ tests/test_grants_rtk.py reads the package's own files, so a broken one fails there first.
2302
+ """
2303
+ directory = os.path.join(adapters_dir(), REWRITERS_DIR)
2304
+ try:
2305
+ names = sorted(name for name in os.listdir(directory) if name.endswith(".json"))
2306
+ except OSError:
2307
+ return []
2308
+ found = []
2309
+ for name in names:
2310
+ try:
2311
+ with open(os.path.join(directory, name), encoding=UTF8) as fh:
2312
+ rewriter = json.load(fh)
2313
+ except (OSError, ValueError) as exc:
2314
+ raise ValueError(f"the package's command rewriter {name} cannot be read ({exc}); "
2315
+ "reinstall polyctl, or restore that file from the release") from exc
2316
+ if isinstance(rewriter, dict) and isinstance(rewriter.get("command"), str) and rewriter["command"].strip():
2317
+ found.append(rewriter)
2318
+ return found
2319
+
2320
+
2321
+ def rewriter_forms(rewriter):
2322
+ """{command: form} a rewriter declares, keeping each form that is its own command and plain words after it."""
2323
+ command = str(rewriter.get("command") or "").strip()
2324
+ forms = rewriter.get("forms") if isinstance(rewriter.get("forms"), dict) else {}
2325
+ return {str(words): form for words, form in forms.items()
2326
+ if isinstance(form, str) and REWRITE_FORM.fullmatch(form) and form.split(" ", 1)[0] == command}
2327
+
2328
+
2329
+ def rewritten_rules(rule, rewriters=None):
2330
+ """The rules admitting what each rewriter makes of the commands `rule` admits; [] for most rules (GRANTS-RTK).
2331
+
2332
+ Only a rule naming a command a rewriter declares, with any arguments after it - `Bash(git diff:*)`,
2333
+ or `Bash(git diff *)` as another harness spells it - has one: the same rule for the form every
2334
+ rewrite of that command begins with, `Bash(rtk git diff:*)`. An exact rule, a rule that names
2335
+ arguments of its own and every other tool have none: a rewriter need not keep a command's
2336
+ arguments in place (`head -n 5 x` becomes `rtk read x --head-lines 5`), so no narrower rule can be
2337
+ read off them, and none is guessed.
2338
+ """
2339
+ rule = str(rule).strip()
2340
+ if not (rule.startswith("Bash(") and rule.endswith(")")):
2341
+ return []
2342
+ body = rule[len("Bash("):-1]
2343
+ wildcard = next((end for end in RULE_WILDCARDS if body.endswith(end)), None)
2344
+ if wildcard is None:
2345
+ return []
2346
+ words = body[:-len(wildcard)]
2347
+ found = []
2348
+ for rewriter in command_rewriters() if rewriters is None else rewriters:
2349
+ form = rewriter_forms(rewriter).get(words)
2350
+ if form and f"Bash({form}{wildcard})" not in found:
2351
+ found.append(f"Bash({form}{wildcard})")
2352
+ return found
2353
+
2354
+
2355
+ def admit_rewrites(argv, rewriters=None, prompt=None):
2356
+ """(argv, added): `argv` with each rule of its tool grant followed by those of its `rewritten_rules` the
2357
+ grant does not hold yet, and the rules added (GRANTS-RTK).
2358
+
2359
+ A harness's hook rewrote `git diff` to `rtk git diff` before the harness checked its rules, and a
2360
+ grant naming `Bash(git diff:*)` does not admit `rtk git diff`: an unattended turn was denied the
2361
+ commands its grant named (measured on qodercli). A rule added follows the rule it comes from and
2362
+ admits that rule's commands only, as the rewriter runs them. The grant is the value after each of
2363
+ GRANT_FLAGS, as allowlist.rules reads it, and admitting twice adds nothing the second time.
2364
+ """
2365
+ rewriters = command_rewriters() if rewriters is None else rewriters
2366
+ args, added = list(argv or []), []
2367
+
2368
+ values, active = [], False
2369
+ for at, arg in enumerate(args):
2370
+ flag, equals, value = str(arg).partition("=")
2371
+ if str(arg).startswith("-"):
2372
+ active = flag in GRANT_FLAGS
2373
+ if active and equals:
2374
+ values.append((at, flag + "=", value))
2375
+ elif active:
2376
+ values.append((at, "", str(arg)))
2377
+ values = [(at, prefix, value) for at, prefix, value in values
2378
+ if value != prompt and not re.fullmatch(r"\{[a-z_]+\}", value)]
2379
+ held = {rule for _, _, value in values for rule in split_tool_list(value)}
2380
+ for at, prefix, value in values:
2381
+ out, changed = [], False
2382
+ for part in split_tool_list(value):
2383
+ out.append(part)
2384
+ for rule in rewritten_rules(part, rewriters):
2385
+ if rule not in held:
2386
+ held.add(rule)
2387
+ out.append(rule)
2388
+ added.append(rule)
2389
+ changed = True
2390
+ if changed:
2391
+ args[at] = prefix + ",".join(out)
2392
+ return args, added
2393
+
2394
+
2395
+ # ---- a reviewer can be a tool polyctl runs over the candidate, on its own provider (#86) -------
2396
+
2397
+ TOOL_REVIEW_PLACEHOLDERS = ("prompt", "diff_file", "output", "model", "timeout", "tree")
2398
+ TOOL_REVIEW_ENV_PLACEHOLDERS = ("model", "timeout")
2399
+
2400
+
2401
+ def tool_review_problems(adapter, argv=None):
2402
+ """What a tool reviewer's review contract is missing or gets wrong; empty when there is none (#86).
2403
+
2404
+ The contract says how polyctl hands the tool the candidate (a diff file polyctl writes), where
2405
+ the answer comes back, and which of the inherited environment the tool must not read:
2406
+ for a tool configured through its environment, whoever runs `polyctl review` could otherwise
2407
+ choose the reviewer's model or its instructions. `argv` is the template a configured
2408
+ route runs, `send.argv` when none is given. A model the contract does not pin is one polyctl
2409
+ could not honestly record, so a contract that never names {model} is refused.
2410
+ """
2411
+ review = (adapter or {}).get("review")
2412
+ if review is None:
2413
+ return []
2414
+ if not isinstance(review, dict):
2415
+ return ["`review` must be an object"]
2416
+ problems = []
2417
+ if review.get("candidate") != "diff-file":
2418
+ problems.append("`review.candidate` must be diff-file: polyctl hands a tool reviewer the candidate as a file")
2419
+ if "encoding" in review:
2420
+ try:
2421
+ "".encode(review["encoding"])
2422
+ except (LookupError, TypeError):
2423
+ problems.append(f"`review.encoding` is {review['encoding']!r}, which is not an encoding")
2424
+ if "release" in review and not re.fullmatch(r"\d+(?:\.\d+)*", str(review["release"])):
2425
+ problems.append("`review.release` names the release the contract was measured against, in dotted digits")
2426
+ tree_flag = review.get("tree")
2427
+ if tree_flag is not None and not (
2428
+ isinstance(tree_flag, list) and tree_flag and all(isinstance(part, str) for part in tree_flag)
2429
+ and str(tree_flag[0]).startswith("-")
2430
+ and [name for part in tree_flag for name in re.findall(r"\{([a-z_]+)\}", part)] == ["tree"]):
2431
+ problems.append("`review.tree` must be a flag, carrying {tree} in exactly one argument")
2432
+ answer = review.get("answer")
2433
+ if not isinstance(answer, dict) or answer.get("from") != "output":
2434
+ problems.append("`review.answer.from` must be output: the file polyctl names in {output}")
2435
+ elif "after_prompt" in answer and not (isinstance(answer["after_prompt"], str) and answer["after_prompt"].strip()
2436
+ and "\n" not in answer["after_prompt"]):
2437
+ problems.append("`review.answer.after_prompt` must be one line of text")
2438
+ if argv is None:
2439
+ send = adapter.get("send")
2440
+ argv = send.get("argv") if isinstance(send, dict) else None
2441
+ if not isinstance(argv, list) or not argv or not all(isinstance(part, str) for part in argv):
2442
+ return problems + ["a tool reviewer's argv must be a list of strings"]
2443
+ used = [name for part in argv for name in re.findall(r"\{([a-z_]+)\}", part)]
2444
+ unknown = sorted(set(used) - set(TOOL_REVIEW_PLACEHOLDERS))
2445
+ if unknown:
2446
+ problems.append(f"a tool reviewer's argv uses placeholders polyctl does not fill: {', '.join(unknown)}")
2447
+ for name in ("prompt", "diff_file", "output"):
2448
+ if used.count(name) != 1:
2449
+ problems.append(f"a tool reviewer's argv must carry {{{name}}} exactly once")
2450
+ if "tree" in used and (tree_flag is None or used.count("tree") != 1):
2451
+ problems.append("a tool reviewer's argv may carry {tree} once only when `review.tree` is declared")
2452
+ # Null is no environment, and so is nothing; any other value that is no object is refused, not read as one: an
2453
+ # empty list or string was taken for no rules (LEADS-ADAPTERS).
2454
+ environment = {} if review.get("environment") is None else review["environment"]
2455
+ if not isinstance(environment, dict):
2456
+ return problems + ["`review.environment` must be an object"]
2457
+ for key in ("remove", "keep"):
2458
+ patterns = [] if environment.get(key) is None else environment[key]
2459
+ if not isinstance(patterns, list) or not all(isinstance(pattern, str) for pattern in patterns):
2460
+ problems.append(f"`review.environment.{key}` must be a list of regular expressions")
2461
+ continue
2462
+ for pattern in patterns:
2463
+ try:
2464
+ re.compile(pattern)
2465
+ except re.error as exc:
2466
+ problems.append(f"`review.environment.{key}` holds {pattern!r}, which does not compile: {exc}")
2467
+ pinned = {} if environment.get("set") is None else environment["set"]
2468
+ if not isinstance(pinned, dict) or not all(isinstance(name, str) and re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", name)
2469
+ and isinstance(value, str) for name, value in pinned.items()):
2470
+ return problems + ["`review.environment.set` must map variable names to strings"]
2471
+ values = [name for value in pinned.values() for name in re.findall(r"\{([a-z_]+)\}", value)]
2472
+ unknown = sorted(set(values) - set(TOOL_REVIEW_ENV_PLACEHOLDERS))
2473
+ if unknown:
2474
+ problems.append(f"`review.environment.set` uses placeholders polyctl does not fill: {', '.join(unknown)}")
2475
+ if "model" not in used and "model" not in values:
2476
+ problems.append("the review contract never pins {model}, so polyctl could not record which model answered")
2477
+ return problems
2478
+
2479
+
2480
+ def tool_review_contract(adapter):
2481
+ """An adapter's review contract when it is a sound tool reviewer's, else None (#86)."""
2482
+ review = (adapter or {}).get("review")
2483
+ return review if isinstance(review, dict) and not tool_review_problems(adapter) else None
2484
+
2485
+
2486
+ def acp_problems(adapter):
2487
+ """What is wrong with an adapter's ACP command, if it declares one (ACP-PROBE).
2488
+
2489
+ `acp.argv` starts the harness speaking ACP on its standard streams: a list of strings with no
2490
+ placeholder, since the protocol carries the prompt and the session, and `acp.measured` names the
2491
+ release and the day it was seen to answer `initialize`.
2492
+ """
2493
+ block = adapter.get("acp")
2494
+ if block is None:
2495
+ return []
2496
+ if not isinstance(block, dict):
2497
+ return ["`acp` must be an object"]
2498
+ problems = []
2499
+ argv = block.get("argv")
2500
+ if not isinstance(argv, list) or not argv or not all(isinstance(a, str) and a for a in argv):
2501
+ problems.append("`acp.argv` must be a list of strings")
2502
+ elif any("{" in a for a in argv):
2503
+ problems.append("`acp.argv` carries no placeholder: the protocol carries the prompt and the session")
2504
+ if not isinstance(block.get("measured"), str) or not block["measured"].strip():
2505
+ problems.append("`acp.measured` must say which release answered, and when")
2506
+ return problems
2507
+
2508
+
2509
+ def _within_its_folder(name):
2510
+ """Whether a path an adapter declares stays in the folder it is read against, by its words: relative, with no `~`,
2511
+ `..`, backslash or drive. `C:/outside` reads as relative on POSIX and is absolute on Windows, where a folder joined
2512
+ to it is `C:/outside` alone (LEADS-ADAPTERS)."""
2513
+ import ntpath
2514
+ return isinstance(name, str) and bool(name.strip()) and not name.startswith(("/", "~")) and "\\" not in name \
2515
+ and ".." not in name.split("/") and not ntpath.splitdrive(name)[0]
2516
+
2517
+
2518
+ def reviewer_agent_problems(adapter):
2519
+ """What keeps polyctl from writing the reviewer agent an adapter declares in `options.reviewer_agent` (KIRO-READONLY).
2520
+ Options that are no object declare none, and `validate_adapter` names them (LEADS-ADAPTERS)."""
2521
+ options = (adapter or {}).get("options")
2522
+ agent = options.get("reviewer_agent") if isinstance(options, dict) else None
2523
+ if agent is None:
2524
+ return []
2525
+ if not isinstance(agent, dict):
2526
+ return ["`options.reviewer_agent` must be an object"]
2527
+ problems = []
2528
+ argv, path, config = agent.get("argv"), agent.get("path"), agent.get("config")
2529
+ if not (isinstance(argv, list) and argv and all(isinstance(part, str) for part in argv)
2530
+ and str(argv[0]).startswith("-") and sum("{agent}" in part for part in argv) == 1):
2531
+ problems.append("`options.reviewer_agent.argv` must be a flag, carrying {agent} in exactly one argument")
2532
+ if not (isinstance(path, str) and "{agent}" in path and _within_its_folder(path)):
2533
+ problems.append("`options.reviewer_agent.path` must be a path within the reviewer's directory, carrying {agent}")
2534
+ # A harness names an agent's tools as a list, or as permissions by tool, as opencode does (OPENCODE-REVIEWER).
2535
+ if not (isinstance(config, dict) and (isinstance(config.get("tools"), list) or isinstance(config.get("permission"), dict))):
2536
+ problems.append("`options.reviewer_agent.config` must be an object that names its `tools` or its `permission`")
2537
+ # An agent file is JSON, or a markdown body under the config as front matter (AGY-REVIEWER).
2538
+ if agent.get("format", "json") not in ("json", "frontmatter"):
2539
+ problems.append("`options.reviewer_agent.format` must be json or frontmatter")
2540
+ if agent.get("format") == "frontmatter" and not isinstance(agent.get("body"), str):
2541
+ problems.append("`options.reviewer_agent.body` must be the text under the front matter")
2542
+ if agent.get("acp") not in (None, True, False):
2543
+ problems.append("`options.reviewer_agent.acp` must say whether the agent was measured to hold over ACP too")
2544
+ release = agent.get("release")
2545
+ if release is not None and not (isinstance(release, str) and re.fullmatch(r"\d+(\.\d+)*", release)):
2546
+ problems.append("`options.reviewer_agent.release` must be the release the agent was measured on, as 1.3")
2547
+ settings = agent.get("settings")
2548
+ if settings is not None and not (
2549
+ isinstance(settings, dict) and isinstance(settings.get("path"), str) and settings["path"].startswith("~/")
2550
+ and isinstance(settings.get("allow"), list) and settings["allow"]
2551
+ and all(isinstance(key, str) for key in settings["allow"])
2552
+ and isinstance(settings.get("reads"), list) and all(isinstance(rule, str) for rule in settings["reads"])):
2553
+ problems.append("`options.reviewer_agent.settings` must name a file under the home folder, the keys of its "
2554
+ "allow rules, and the rules that only read")
2555
+ return problems
2556
+
2557
+
2558
+ def validate_adapter(adapter):
2559
+ """What an adapter is missing or gets wrong, before anyone relies on it (#77)."""
2560
+ problems = []
2561
+ if not isinstance(adapter, dict):
2562
+ return ["an adapter is a JSON object"]
2563
+ for field in ("id", "name", "verified"):
2564
+ if not isinstance(adapter.get(field), str) or not adapter[field].strip():
2565
+ problems.append(f"`{field}` is missing")
2566
+ if adapter.get("verified") and adapter["verified"] not in ADAPTER_VERIFIED:
2567
+ problems.append(f"`verified` is {adapter['verified']!r}; one of {', '.join(ADAPTER_VERIFIED)}")
2568
+ if adapter.get("options") is not None and not isinstance(adapter["options"], dict):
2569
+ # Every check below reads them as an object: `polyctl adapters validate` ended in a traceback (LEADS-ADAPTERS).
2570
+ problems.append("`options` must be an object")
2571
+ adapter = {key: value for key, value in adapter.items() if key != "options"}
2572
+ config = adapter.get("project_config")
2573
+ if config is not None and not (isinstance(config, list) and all(_within_its_folder(name) for name in config)):
2574
+ problems.append("`project_config` must list the files and folders its harness reads from a project, each a "
2575
+ "path within it")
2576
+ worktrees = adapter.get("worktree_dirs")
2577
+ if worktrees is not None and not (isinstance(worktrees, list) and all(_within_its_folder(name) for name in worktrees)):
2578
+ problems.append("`worktree_dirs` must list the folders its harness keeps the worktrees it makes in, each a "
2579
+ "path within the project")
2580
+ if "contract" not in adapter:
2581
+ problems.append(f"`contract` is missing; this polyctl implements contract {ADAPTER_CONTRACT}")
2582
+ elif adapter["contract"] != ADAPTER_CONTRACT:
2583
+ problems.append(f"declares contract {adapter['contract']!r}; this polyctl implements contract {ADAPTER_CONTRACT}")
2584
+ for capability in ("send", "resume"):
2585
+ block = adapter.get(capability)
2586
+ if block is None:
2587
+ if capability == "send":
2588
+ problems.append("`send` is missing: an adapter must say how to run one prompt")
2589
+ continue
2590
+ argv = (block or {}).get("argv") if isinstance(block, dict) else None
2591
+ if not isinstance(argv, list) or not argv or not all(isinstance(a, str) for a in argv):
2592
+ problems.append(f"`{capability}.argv` must be a list of strings")
2593
+ continue
2594
+ if sum("{prompt}" in a for a in argv) != 1:
2595
+ problems.append(f"`{capability}.argv` must carry {{prompt}} in exactly one argument")
2596
+ if capability == "resume" and not any("{session}" in a for a in argv):
2597
+ problems.append("`resume.argv` must carry {session}")
2598
+ filled = {"prompt", "session"}
2599
+ if capability == "send" and isinstance(adapter.get("review"), dict):
2600
+ filled.update(TOOL_REVIEW_PLACEHOLDERS)
2601
+ unknown = sorted({p for a in argv for p in re.findall(r"\{([a-z_]+)\}", a)} - filled)
2602
+ if unknown:
2603
+ problems.append(f"`{capability}.argv` uses placeholders polyctl does not fill: {', '.join(unknown)}")
2604
+ return (problems + prompt_channel_problems(adapter) + tool_review_problems(adapter) + subagent_problems(adapter)
2605
+ + acp_problems(adapter) + reviewer_agent_problems(adapter)
2606
+ + bypass_problems(adapter) + quota_stop_problems(adapter)
2607
+ + token_problems(_block(_block(adapter, "telemetry"), "cost")))
2608
+
2609
+
2610
+ def conform_adapter(adapter, harness, workdir):
2611
+ """Run an adapter's send and resume through a fixture harness: does each prompt and session arrive whole? (#77)
2612
+
2613
+ `harness` is the program that takes the place of the adapter's, or the words that start it: `polyctl adapters
2614
+ conform` starts the fixture with this interpreter, since Windows runs no script by its first line
2615
+ (LEADS-INSTALL). Returns [(capability, "pass" | "fail" | "absent", detail)] for the five capabilities.
2616
+ """
2617
+ results = []
2618
+ prompt = "conformance prompt: spaces, 'quotes', \"double\", = signs and a\nsecond line"
2619
+ for capability in ("send", "resume"):
2620
+ argv = ((adapter.get(capability) or {}).get("argv") if isinstance(adapter.get(capability), dict) else None)
2621
+ if not argv:
2622
+ results.append((capability, "absent", "not declared"))
2623
+ continue
2624
+ rendered = (list(harness) if isinstance(harness, (list, tuple)) else [harness]) \
2625
+ + [a.replace("{prompt}", prompt).replace("{session}", "sess-conformance") for a in argv[1:]]
2626
+ record = os.path.join(workdir, f"{capability}.json")
2627
+ try:
2628
+ subprocess.run(rendered, cwd=workdir, env=dict(os.environ, POLYCTL_HARNESS_RECORD=record), timeout=30,
2629
+ stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
2630
+ with open(record, encoding=UTF8) as fh:
2631
+ received = json.load(fh)["argv"]
2632
+ except (OSError, ValueError, KeyError, subprocess.TimeoutExpired) as exc:
2633
+ results.append((capability, "fail", f"the harness did not run: {exc}"))
2634
+ continue
2635
+ whole = [a for a in received if a == prompt or a.endswith("=" + prompt)]
2636
+ if len(whole) != 1:
2637
+ results.append((capability, "fail", "the prompt did not arrive whole in exactly one argument"))
2638
+ elif capability == "resume" and any("{session}" in a for a in argv) \
2639
+ and not any("sess-conformance" in a for a in received):
2640
+ results.append((capability, "fail", "the session did not arrive"))
2641
+ elif capability == "resume" and not any("{session}" in a for a in argv):
2642
+ results.append((capability, "pass", "prompt whole; it resumes the most recent session, no id"))
2643
+ else:
2644
+ results.append((capability, "pass", f"{len(received)} argument(s), prompt whole"))
2645
+ for capability in ("transcript", "busy", "directives"):
2646
+ block = adapter.get(capability)
2647
+ if not block:
2648
+ results.append((capability, "absent", "not declared"))
2649
+ elif capability == "transcript" and block.get("kind") not in ("jsonl", "sqlite", "json", "markdown",
2650
+ "call-return", "unknown", None):
2651
+ results.append((capability, "fail", f"unknown transcript kind {block.get('kind')!r}"))
2652
+ elif capability == "transcript" and not session_store_reachable(adapter):
2653
+ results.append((capability, "declared", "no store polyctl can resolve, so nothing is read from it"))
2654
+ else:
2655
+ results.append((capability, "pass", "declared"))
2656
+ return results
2657
+
2658
+
2659
+ def session_store_reachable(adapter):
2660
+ """Can polyctl reach this adapter's records at all, from what it declares?
2661
+
2662
+ A record is read from a place polyctl resolves: a role's session id names it in one of the stores
2663
+ this polyctl dispatches on. An adapter may describe its transcript precisely - its shape, its kinds,
2664
+ where a tool call keeps its name - and still name no place polyctl can find it, and then every
2665
+ reader of it returns nothing while a check that only looked for a declaration said it was
2666
+ sound. So a declaration is reported as one, and a resolution as the other.
2667
+ """
2668
+ return isinstance((adapter or {}).get("sessions"), dict) \
2669
+ and (adapter["sessions"].get("kind") in SESSION_STORE_KINDS)
2670
+
2671
+
2672
+ # ---- a prompt too long for one argument reaches its command another way (PROMPT-CHANNEL) -----
2673
+
2674
+ # Linux refuses one argument longer than 32 pages, its terminating NUL counted (MAX_ARG_STRLEN), however much
2675
+ # the whole command line may hold; Windows refuses a command line longer than 32,767 UTF-16 units, its NUL
2676
+ # counted. Linux and macOS both bound the arguments and the environment together (ARG_MAX).
2677
+ LINUX_ARGUMENT_BYTES = 131_072
2678
+ WINDOWS_COMMAND_UNITS = 32_767
2679
+ # Kept free beside what is measured: the program's resolved path, a launcher that starts the real program
2680
+ # with a path, a script and variables of its own, and what the kernel stores beside the strings.
2681
+ ARGUMENT_MARGIN_BYTES = 65_536
2682
+ ARGUMENT_MARGIN_UNITS = 1_024
2683
+ PROMPT_CHANNELS = ("stdin", "file")
2684
+
2685
+
2686
+ def argument_overflow(argv, env=None):
2687
+ """What starting `argv` here would exceed, as a phrase; None when it fits with room to spare (PROMPT-CHANNEL).
2688
+
2689
+ A review prompt carries a diff of up to 400 KB and its context, and it travelled as one argument:
2690
+ past what one argument carries the reviewer could not start, and the spawn error read as a reviewer
2691
+ that was unavailable. Every string is counted with its NUL and its pointer, and the environment
2692
+ (`os.environ` unless one is given) with the arguments. Where the platform's own bound cannot be
2693
+ read, the Linux bound on one argument stands in for it.
2694
+ """
2695
+ import sys
2696
+ args = [str(arg) for arg in argv]
2697
+ if os.name == "nt":
2698
+ units = len(subprocess.list2cmdline(args).encode("utf-16-le")) // 2 + 1
2699
+ if units + ARGUMENT_MARGIN_UNITS <= WINDOWS_COMMAND_UNITS:
2700
+ return None
2701
+ return (f"a command line on {sys.platform} carries at most {WINDOWS_COMMAND_UNITS - 1} characters; this one "
2702
+ f"takes {units - 1}, and {ARGUMENT_MARGIN_UNITS} are kept free")
2703
+ sizes = [len(os.fsencode(arg)) + 1 for arg in args]
2704
+ try:
2705
+ whole = int(os.sysconf("SC_ARG_MAX"))
2706
+ except (AttributeError, OSError, TypeError, ValueError):
2707
+ whole = 0
2708
+ if (sys.platform.startswith("linux") or whole <= 0) and max(sizes, default=0) > LINUX_ARGUMENT_BYTES:
2709
+ return (f"one argument on {sys.platform} carries at most {LINUX_ARGUMENT_BYTES - 1} bytes"
2710
+ + ("" if whole > 0 else ", as polyctl assumes where the platform's bound cannot be read"))
2711
+ if whole <= 0:
2712
+ return None
2713
+ environment = os.environ if env is None else env
2714
+ taken = sum(size + 8 for size in sizes) + sum(len(os.fsencode(key)) + len(os.fsencode(value)) + 2 + 8
2715
+ for key, value in environment.items())
2716
+ if taken + ARGUMENT_MARGIN_BYTES <= whole:
2717
+ return None
2718
+ return (f"arguments and environment on {sys.platform} carry at most {whole} bytes together; this command takes "
2719
+ f"{taken}, and {ARGUMENT_MARGIN_BYTES} are kept free")
2720
+
2721
+
2722
+ def _argument_run(argv, run):
2723
+ """Where a run of arguments starts in argv when it occurs there exactly once, else None."""
2724
+ if not isinstance(argv, list) or not isinstance(run, list) or not run:
2725
+ return None
2726
+ found = [at for at in range(len(argv) - len(run) + 1) if argv[at:at + len(run)] == run]
2727
+ return found[0] if len(found) == 1 else None
2728
+
2729
+
2730
+ def prompt_channel_problems(adapter):
2731
+ """What an adapter's prompt channels get wrong; empty when it declares none, or sound ones (PROMPT-CHANNEL).
2732
+
2733
+ A channel is declared under `send` or `resume` and replaces, once, the run of that capability's own
2734
+ arguments that carries {prompt}: `stdin` with arguments that leave the prompt to standard input,
2735
+ `file` with arguments that name the prompt's file in {prompt_file}, once.
2736
+ """
2737
+ problems = []
2738
+ for capability in ("send", "resume"):
2739
+ block = (adapter or {}).get(capability)
2740
+ if not isinstance(block, dict):
2741
+ continue
2742
+ for channel in PROMPT_CHANNELS:
2743
+ if channel not in block:
2744
+ continue
2745
+ spec, where = block[channel], f"{capability}.{channel}"
2746
+ replaces = spec.get("replaces") if isinstance(spec, dict) else None
2747
+ replacement = spec.get("with") if isinstance(spec, dict) else None
2748
+ if not isinstance(replaces, list) or not all(isinstance(part, str) for part in replaces) \
2749
+ or sum("{prompt}" in part for part in replaces) != 1:
2750
+ problems.append(f"`{where}.replaces` must list the arguments that carry {{prompt}}, one of them "
2751
+ "holding it")
2752
+ elif _argument_run(block.get("argv"), replaces) is None:
2753
+ problems.append(f"`{where}.replaces` must occur exactly once in `{capability}.argv`")
2754
+ if not isinstance(replacement, list) or not all(isinstance(part, str) for part in replacement):
2755
+ problems.append(f"`{where}.with` must be a list of strings")
2756
+ continue
2757
+ used = [name for part in replacement for name in re.findall(r"\{([a-z_]+)\}", part)]
2758
+ if set(used) - {"prompt_file"}:
2759
+ problems.append(f"`{where}.with` fills no placeholder but {{prompt_file}}")
2760
+ if used.count("prompt_file") != (1 if channel == "file" else 0):
2761
+ problems.append(f"`{where}.with` must carry {{prompt_file}} "
2762
+ + ("exactly once" if channel == "file" else "nowhere: the prompt is on standard input"))
2763
+ return problems
2764
+
2765
+
2766
+ def batch_program(program):
2767
+ """Whether `program` is a batch file, which Windows runs through cmd.exe: `.cmd` or `.bat` (WINDOWS-CMD-CHANNEL).
2768
+
2769
+ An agent CLI installed with npm on Windows is a `.cmd` file, and cmd.exe reads each argument it is
2770
+ handed as its own syntax: it ends the command at a line break, replaces `%NAME%`, and a double quote
2771
+ in the text changes what `&` and `|` mean. No quoting carries a line break through it, so such a
2772
+ program is handed its prompt on standard input, never in an argument (`prompt_input`). The suffix is
2773
+ read in any case, as Windows reads it; elsewhere nothing runs a program through cmd.exe.
2774
+ """
2775
+ return os.name == "nt" and str(program or "").lower().endswith((".cmd", ".bat"))
2776
+
2777
+
2778
+ def _batch_stdin(template, ident, adapter, capability):
2779
+ """How a batch program is handed the prompt `template` carries: ((start, stop, arguments), None), the run
2780
+ of the template the adapter's standard input replaces and the arguments put in its place, or (None, why
2781
+ none can be) (WINDOWS-CMD-CHANNEL).
2782
+
2783
+ Only standard input counts. A prompt file is handed over by its path, which is an argument cmd.exe
2784
+ reads like any other.
2785
+ """
2786
+ if not isinstance(adapter, dict):
2787
+ return None, ((f"{ident} is no adapter polyctl ships" if ident else "no adapter polyctl ships runs this command")
2788
+ + ", and only a shipped adapter declares standard input")
2789
+ block = adapter.get(capability) if isinstance(adapter.get(capability), dict) else {}
2790
+ if not isinstance(block.get("stdin"), dict):
2791
+ return None, f"adapter {ident} declares no standard input for `{capability}`"
2792
+ replaces, replacement = block["stdin"].get("replaces"), block["stdin"].get("with")
2793
+ at = _argument_run(template, replaces)
2794
+ if at is None or not isinstance(replacement, list):
2795
+ named = " ".join(str(part) for part in replaces) if isinstance(replaces, list) else ""
2796
+ return None, (f"this command does not carry the arguments adapter {ident} replaces with standard input "
2797
+ f"for `{capability}` ({named})")
2798
+ return (at, at + len(replaces), [str(part) for part in replacement]), None
2799
+
2800
+
2801
+ def _batch_argv(plan, argv):
2802
+ """`argv` with its prompt moved to standard input, for a batch program: (argv, None), or (None, why it
2803
+ cannot be) (WINDOWS-CMD-CHANNEL).
2804
+
2805
+ The command is rendered from the plan's template part for part, and what a caller adds follows it,
2806
+ so the arguments the adapter's standard input replaces stand where the template holds them. They are
2807
+ cut only where they carry the prompt: a command that does not carry it there is refused, since what a
2808
+ cut would take from it is not known.
2809
+ """
2810
+ switch, why = plan.get("batch") or (None, "no standard input was planned for it")
2811
+ if switch is None:
2812
+ return None, why
2813
+ start, stop, arguments = switch
2814
+ carried = [str(part).replace("{prompt}", plan["prompt"]) for part in plan["argv"][start:stop]]
2815
+ if plan.get("channel") != "argument" or list(argv[start:stop]) != carried:
2816
+ return None, "this command does not carry its prompt where its template does"
2817
+ return list(argv[:start]) + list(arguments) + list(argv[stop:]), None
2818
+
2819
+
2820
+ def prompt_plan(template, prompt, adapter_id=None, detached=False, env=None):
2821
+ """How a prompt reaches the command an argv template runs: (plan, None), or (None, why it cannot) (PROMPT-CHANNEL).
2822
+
2823
+ The prompt stays in its argument while the command fits (`argument_overflow`). Past that it goes where
2824
+ the adapter declares, in place of the arguments that carried it: `resume`'s channels for a command that
2825
+ carries {session}, `send`'s for any other, standard input before a file. A file is removed when its
2826
+ process ends and polyctl does not wait on a detached turn, so a detached turn takes standard input or
2827
+ nothing. Channels are read from the package's adapters only, as a review contract is: a layer an agent
2828
+ can write must not choose the arguments a reviewer runs with. With no channel nothing may start, and
2829
+ the reason says how large the prompt is, what the platform carries and what the adapter declares.
2830
+ The plan holds the argv template, the channel ("argument", "stdin" or "file"), the run (start, stop)
2831
+ of the arguments the channel put in, and the prompt. It also holds `batch`, how a batch program on
2832
+ Windows is handed the prompt whatever its size, as `_batch_stdin` reads it from the same adapter: the
2833
+ program is known only once the command is resolved, so `prompt_input` decides (WINDOWS-CMD-CHANNEL).
2834
+ """
2835
+ template = list(template or [])
2836
+ text = str(prompt)
2837
+ capability = "resume" if any("{session}" in str(part) for part in template) else "send"
2838
+ ident = str(adapter_id or "").strip()
2839
+ adapter = package_adapters().get(ident) if ident else None
2840
+ plan = {"argv": template, "channel": "argument", "run": None, "prompt": text,
2841
+ "batch": _batch_stdin(template, ident, adapter, capability)}
2842
+ overflow = argument_overflow([str(part).replace("{prompt}", text) for part in template], env)
2843
+ if overflow is None:
2844
+ return plan, None
2845
+ size = f"the prompt is {len(text.encode(UTF8, 'replace'))} bytes, and {overflow}"
2846
+ if not isinstance(adapter, dict):
2847
+ return None, (f"{size}; " + (f"{ident} is no adapter polyctl ships" if ident else "no adapter polyctl ships runs this "
2848
+ "command") + ", and only a shipped adapter declares another channel")
2849
+ block = adapter.get(capability) if isinstance(adapter.get(capability), dict) else {}
2850
+ declared = [channel for channel in PROMPT_CHANNELS if isinstance(block.get(channel), dict)]
2851
+ for channel in declared:
2852
+ replaces, replacement = block[channel].get("replaces"), block[channel].get("with")
2853
+ at = _argument_run(template, replaces)
2854
+ if (detached and channel == "file") or at is None or not isinstance(replacement, list):
2855
+ continue
2856
+ argv = template[:at] + [str(part) for part in replacement] + template[at + len(replaces):]
2857
+ return dict(plan, argv=argv, channel=channel, run=(at, at + len(replacement))), None
2858
+ if not declared:
2859
+ return None, f"{size}; adapter {ident} declares no other channel for `{capability}` (`stdin` or `file`)"
2860
+ if detached and declared == ["file"]:
2861
+ return None, (f"{size}; adapter {ident} declares only a prompt file for `{capability}`, which is removed when "
2862
+ "its process ends, and polyctl does not wait on a detached turn")
2863
+ return None, (f"{size}; this command does not carry the arguments adapter {ident} replaces for `{capability}` ("
2864
+ + "; ".join(" ".join(str(part) for part in block[channel].get("replaces") or [])
2865
+ for channel in declared) + ")")
2866
+
2867
+
2868
+ def prompt_input(plan, root=None, argv=None):
2869
+ """What hands a planned prompt to its process: (given, None), or (None, why it cannot) (PROMPT-CHANNEL).
2870
+
2871
+ `argv` is the command rendered from the plan, the plan's template when none is given. For a channel
2872
+ the prompt's bytes are written to a file of mode 0600 in a directory of its own, never inside
2873
+ `root`: standard input is that file, opened for reading, or the file's path fills the {prompt_file}
2874
+ the channel put in, and nowhere else. A file read as standard input loses its name before the
2875
+ process starts where the platform allows it, so nothing named is left whatever becomes of polyctl;
2876
+ `release_prompt` removes the rest once the process has ended. `given` holds the argv, standard input
2877
+ (None when the prompt is not on it) and the directory.
2878
+
2879
+ A batch program on Windows is handed its prompt on standard input whatever its size, where its adapter
2880
+ declares it, and nothing starts where it does not (WINDOWS-CMD-CHANNEL). The watchdog handed the
2881
+ implementer and the architect their prompts as an argument, and cmd.exe would have ended the
2882
+ architect's wake, several paragraphs long, at its first line. It is decided here, on the command that
2883
+ starts, because the watchdog resolves the program only after the prompt's plan is made.
2884
+ """
2885
+ given = {"argv": list(plan["argv"] if argv is None else argv), "stdin": None, "directory": None}
2886
+ channel = plan.get("channel")
2887
+ if channel != "stdin" and given["argv"] and batch_program(given["argv"][0]):
2888
+ switched, why = _batch_argv(plan, given["argv"])
2889
+ if switched is None:
2890
+ return None, (f"{given['argv'][0]} is a batch file, which Windows runs through cmd.exe, and cmd.exe "
2891
+ "reads a prompt in an argument as its own syntax, ending it at a line break and "
2892
+ f"replacing %NAME% in it, so it takes its prompt on standard input alone (#71); {why}")
2893
+ given["argv"], channel = switched, "stdin"
2894
+ if channel not in PROMPT_CHANNELS:
2895
+ return given, None
2896
+ import tempfile
2897
+ binary = getattr(os, "O_BINARY", 0)
2898
+ try:
2899
+ given["directory"] = tempfile.mkdtemp(prefix="polyctl-prompt-")
2900
+ if root and _within(given["directory"], root):
2901
+ release_prompt(given)
2902
+ return None, "the prompt's private directory would lie inside the repository"
2903
+ path = os.path.join(given["directory"], "prompt")
2904
+ with os.fdopen(os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL | binary, 0o600), "wb") as fh:
2905
+ fh.write(plan["prompt"].encode(UTF8))
2906
+ if channel == "stdin":
2907
+ # On Windows the file goes when the last handle on it closes, the process's included.
2908
+ given["stdin"] = os.fdopen(os.open(path, os.O_RDONLY | binary | getattr(os, "O_TEMPORARY", 0)), "rb")
2909
+ if os.name != "nt":
2910
+ os.remove(path)
2911
+ os.rmdir(given["directory"])
2912
+ given["directory"] = None
2913
+ else:
2914
+ start, stop = plan["run"]
2915
+ given["argv"][start:stop] = [str(part).replace("{prompt_file}", path) for part in given["argv"][start:stop]]
2916
+ except (OSError, UnicodeError) as exc:
2917
+ release_prompt(given)
2918
+ return None, f"the prompt could not be written for its process ({type(exc).__name__}: {exc})"
2919
+ return given, None
2920
+
2921
+
2922
+ def release_prompt(given):
2923
+ """Close polyctl's handle on a handed prompt and remove its private directory; a second call does nothing."""
2924
+ import shutil
2925
+ handle, given["stdin"] = given.get("stdin"), None
2926
+ if handle is not None:
2927
+ try:
2928
+ handle.close()
2929
+ except OSError:
2930
+ pass
2931
+ directory, given["directory"] = given.get("directory"), None
2932
+ if directory:
2933
+ shutil.rmtree(directory, ignore_errors=True)