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,2415 @@
1
+ """State that must agree: consistency across stores, repository signals.
2
+
3
+ A part of src/polyctl/lib.py (#44): moved out byte for byte and run in its namespace by `_part`,
4
+ where it stood; it is not importable on its own.
5
+ """
6
+
7
+
8
+ # ---- the stores agree with each other, and a repair is on the record (#47) --------------
9
+
10
+ REPAIR_CHAIN = "polyctl-repair-row-v1"
11
+
12
+
13
+ def archived_path(root):
14
+ return os.path.join(root, ".polyctl", "ledger", "archived.jsonl")
15
+
16
+
17
+ def archived_artefacts(root):
18
+ """{artefact: archive directory} for review artefacts polyctl moved out of the repository (#38, #47)."""
19
+ from .storage import read_jsonl
20
+ if not os.path.exists(archived_path(root)):
21
+ return {}
22
+ try:
23
+ return {row["artefact"]: row.get("archive") for row in read_jsonl(archived_path(root))
24
+ if isinstance(row, dict) and row.get("artefact")}
25
+ except Exception:
26
+ return {}
27
+
28
+
29
+ def record_archived(root, name, archive):
30
+ from .storage import append_jsonl
31
+ append_jsonl(archived_path(root), {"at": int(time.time()), "artefact": name, "archive": archive})
32
+
33
+
34
+ def _in_archive(root, reviews_dir, name):
35
+ folder = os.path.join(HOME, ".polyctl", "archive", project_key(root))
36
+ try:
37
+ for entry in sorted(os.listdir(folder)):
38
+ if entry.startswith(os.path.basename(os.path.normpath(reviews_dir)) + "-") \
39
+ and os.path.exists(os.path.join(folder, entry, name)):
40
+ return os.path.join(folder, entry)
41
+ except OSError:
42
+ pass
43
+ return None
44
+
45
+
46
+ def consistency_findings(root, cfg):
47
+ """Every disagreement between the board, the ledgers, the review artefacts and git (#47).
48
+
49
+ On 2026-09-07 the architect hand-edited three state files with no way for the
50
+ tool to confirm the result was coherent. Each finding names both sides. A
51
+ finding carries a repair only when the state is mechanical - a checkpoint for a
52
+ ledger whose checkout is gone, a lock whose holder is dead, an archived review
53
+ with no pointer to where it went; what was authorised, reviewed or verified is
54
+ reported and never changed.
55
+ """
56
+ from .storage import _load_committed_lengths, read_chained_jsonl
57
+ out = []
58
+
59
+ def found(kind, text, repair=None):
60
+ out.append({"kind": kind, "text": text, "repair": repair})
61
+
62
+ reviews_dir = cfg.get("reviews", "semantic-review")
63
+ # What was ever granted and verified, the rows a seal retired included, held to the seal (LEDGER-HISTORY).
64
+ try:
65
+ grants = [row for row in authority_history(root) if isinstance(row, dict) and row.get("granted") is True]
66
+ except Exception as exc:
67
+ grants = []
68
+ found("authority", f"the authority ledger cannot be read: {exc}")
69
+ try:
70
+ verifications = {row.get("id") for row in verification_history(root) if isinstance(row, dict)}
71
+ except Exception as exc:
72
+ verifications = None
73
+ found("verifications", f"the verification ledger cannot be read: {exc}")
74
+ try:
75
+ waivers = {row.get("id") for row in waiver_rows(root) if isinstance(row, dict)}
76
+ except Exception as exc:
77
+ waivers = None
78
+ found("waivers", f"the waiver ledger cannot be read: {exc}")
79
+ archived = archived_artefacts(root)
80
+ for row in grants:
81
+ token = row.get("token") or "a grant"
82
+ review = row.get("review")
83
+ if review and not os.path.isfile(os.path.join(root, reviews_dir, review)) and not (
84
+ archived.get(review) and os.path.isfile(os.path.join(archived[review], review))):
85
+ found("grant-review", f"grant {token} rests on review {review}, which is neither in {reviews_dir}/ "
86
+ "nor present at its recorded archive")
87
+ if verifications is not None and row.get("verification") and row["verification"] not in verifications:
88
+ found("grant-verification", f"grant {token} names verification {row['verification']}, which the "
89
+ "verification ledger does not hold")
90
+ for wkey in ("waiver", "gates_waiver"):
91
+ if waivers is not None and row.get(wkey) and row[wkey] not in waivers:
92
+ found("grant-waiver", f"grant {token} stood on waiver {row[wkey]}, which the waiver ledger does not hold")
93
+ try:
94
+ review_rows = read_chained_jsonl(review_ledger_path(root), REVIEW_CHAIN)
95
+ except Exception as exc:
96
+ review_rows = []
97
+ found("reviews", f"the review ledger cannot be read: {exc}")
98
+ for row in review_rows:
99
+ name = row.get("artefact") if isinstance(row, dict) else None
100
+ if not name:
101
+ continue
102
+ path = os.path.join(root, reviews_dir, name)
103
+ where = None
104
+ if not os.path.isfile(path):
105
+ where = archived.get(name) or _in_archive(root, reviews_dir, name)
106
+ if where:
107
+ path = os.path.join(where, name)
108
+ try:
109
+ with open(path, "rb") as fh:
110
+ digest = "sha256:" + hashlib.sha256(fh.read()).hexdigest()
111
+ except OSError:
112
+ found("review-missing", f"{reviews_dir}/{name} has a review row but its file cannot be read at {path}; "
113
+ "restore the recorded bytes")
114
+ continue
115
+ if digest != row.get("sha256"):
116
+ found("review-bytes", f"{path} is not the bytes its review row recorded; restore the recorded bytes")
117
+ elif where and name not in archived:
118
+ found("archive-pointer", f"{name} was moved to {where} and nothing records where",
119
+ repair=("archive-pointer", name, where))
120
+ for state, items in board(root).items():
121
+ for item in items:
122
+ for key in ("landed", "commit"):
123
+ sha = (item["notes"].get(key) or "").split(" ")[0].strip()
124
+ if re.fullmatch(r"[0-9a-f]{7,40}", sha) and \
125
+ not git_text(root, "rev-parse", "--verify", "--quiet", f"{sha}^{{commit}}"):
126
+ found("board-commit", f"the board says {item['id']} {key} {sha}, which is not a commit here")
127
+ for ledger in sorted(_load_committed_lengths()):
128
+ checkout = os.path.dirname(os.path.dirname(os.path.dirname(ledger)))
129
+ if os.path.basename(os.path.dirname(ledger)) == "ledger" and not os.path.isdir(checkout):
130
+ found("checkpoint", f"a committed length is recorded for {ledger}, whose checkout is gone",
131
+ repair=("checkpoint", ledger))
132
+ lock = architect_lock_path(root)
133
+ try:
134
+ with open(lock, encoding=UTF8) as fh:
135
+ holder = json.load(fh)
136
+ except (OSError, ValueError):
137
+ holder = None
138
+ if isinstance(holder, dict) and holder.get("pid") and not _pid_alive(holder["pid"]):
139
+ found("architect-lock", f"the architect lock names pid {holder['pid']}, which is not running",
140
+ repair=("architect-lock", lock, holder))
141
+ return out
142
+
143
+
144
+ def repair_consistency(root, findings):
145
+ """Apply only the mechanical repairs, and record each in .polyctl/ledger/repairs.jsonl (#47).
146
+
147
+ A repair is itself evidence. It never touches the authority, verification,
148
+ review or waiver ledgers.
149
+ """
150
+ from .storage import (_exclusive_lock, _load_committed_lengths, _write_committed_lengths, append_chained_jsonl,
151
+ checkpoint_path, read_chained_jsonl)
152
+ ledger = os.path.join(root, ".polyctl", "ledger", "repairs.jsonl")
153
+ read_chained_jsonl(ledger, REPAIR_CHAIN)
154
+ done = []
155
+
156
+ def intent(finding, repair):
157
+ # An interrupted repair must leave its reason before it changes state (TRIAGE-1-MEDIUM).
158
+ append_chained_jsonl(ledger, {"at": int(time.time()), "event": "intent", "kind": repair[0],
159
+ "target": list(repair[1:]), "finding": finding["text"]}, REPAIR_CHAIN)
160
+
161
+ for finding in findings:
162
+ repair = finding.get("repair")
163
+ if not repair:
164
+ continue
165
+ kind = repair[0]
166
+ if kind == "checkpoint":
167
+ intent(finding, repair)
168
+ store = checkpoint_path()
169
+ with _exclusive_lock(store + ".lock"):
170
+ data = _load_committed_lengths()
171
+ if repair[1] not in data:
172
+ continue
173
+ del data[repair[1]]
174
+ # The same replace every ledger append makes, retried where Windows holds the store (#71).
175
+ _write_committed_lengths(data)
176
+ elif kind == "architect-lock":
177
+ with _exclusive_lock(project_file(root, "architect-lock-guard")):
178
+ try:
179
+ with open(repair[1], encoding=UTF8) as fh:
180
+ holder = json.load(fh)
181
+ except (OSError, ValueError):
182
+ continue
183
+ if len(repair) < 3 or holder != repair[2] or _pid_alive(holder["pid"]):
184
+ continue
185
+ intent(finding, repair)
186
+ os.remove(repair[1])
187
+ elif kind == "archive-pointer":
188
+ intent(finding, repair)
189
+ record_archived(root, repair[1], repair[2])
190
+ else:
191
+ continue
192
+ done.append(finding)
193
+ return done
194
+
195
+
196
+ def grant_artefacts_at_risk(root, cfg):
197
+ """(name, "untracked" or "missing") for each review a grant rests on that git does not hold (#38).
198
+
199
+ Every grant's, the sealed ones too (LEDGER-HISTORY).
200
+ """
201
+ granted = sorted({row["review"] for row in authority_history(root)
202
+ if isinstance(row, dict) and row.get("granted") is True and row.get("review")})
203
+ if not granted:
204
+ return []
205
+ tracked = tracked_review_names(root, cfg["reviews"])
206
+ directory = os.path.join(root, cfg["reviews"])
207
+ return [(name, "untracked" if os.path.exists(os.path.join(directory, name)) else "missing")
208
+ for name in granted if name not in tracked]
209
+
210
+
211
+ def candidate_review_decision(root, review_dir, candidate_digest):
212
+ """What the newest recorded review of one candidate decides (#63).
213
+
214
+ Returns ``{"match": (name, verdict, body, evidence) or None, "problem": text or None}``.
215
+ Reviews are taken in the order polyctl recorded them in the chained review ledger,
216
+ never by file time, which anyone can touch. A review that did not take place
217
+ (UNAVAILABLE) masks nothing. Otherwise the newest review of the candidate
218
+ decides: a missing, unreadable, emptied or rewritten artefact is a refusal and
219
+ never a step back to an older approval, and a fallback's approval cannot
220
+ supersede a completed rejection of the same candidate.
221
+ """
222
+ from .storage import read_chained_jsonl
223
+ rows = [row for row in read_chained_jsonl(review_ledger_path(root), REVIEW_CHAIN)
224
+ if isinstance(row, dict) and row.get("kind") == "index-candidate"
225
+ and row.get("candidate") == candidate_digest]
226
+ for position in range(len(rows) - 1, -1, -1):
227
+ row = rows[position]
228
+ if row.get("verdict") == "UNAVAILABLE":
229
+ continue
230
+ name = row.get("artefact")
231
+ try:
232
+ with open(os.path.join(root, review_dir, str(name)), "rb") as fh:
233
+ data = fh.read()
234
+ except OSError:
235
+ return {"match": None,
236
+ "problem": f"the newest review of this candidate, {name}, cannot be read"}
237
+ if "sha256:" + hashlib.sha256(data).hexdigest() != row.get("sha256"):
238
+ return {"match": None,
239
+ "problem": f"the newest review of this candidate, {name}, is not the file "
240
+ "polyctl recorded: emptied, cut short or rewritten"}
241
+ body = data.decode(UTF8, "replace")
242
+ evidence = review_evidence(body)
243
+ verdict = _review_verdict(body)
244
+ if isinstance(evidence, dict) and "verdict" in evidence and evidence["verdict"] != verdict:
245
+ verdict = "INVALID"
246
+ if verdict != "APPROVED" or not isinstance(evidence, dict) \
247
+ or evidence.get("authorizable") is not True:
248
+ return {"match": None, "problem": None}
249
+ rejection = next((earlier for earlier in reversed(rows[:position])
250
+ if earlier.get("verdict") == "NEEDS_CHANGES"), None)
251
+ if row.get("fallback") and rejection:
252
+ # A person's own review is not the configured reviewer either (REVIEW-TIERS).
253
+ who = "a person's" if row.get("tier") == "person" else "a fallback reviewer's"
254
+ return {"match": None,
255
+ "problem": f"{name} is {who} approval; it cannot supersede "
256
+ f"the rejection of this candidate in {rejection.get('artefact')}"}
257
+ return {"match": (name, verdict, body, evidence), "problem": None}
258
+ return {"match": None, "problem": None}
259
+
260
+
261
+ def range_review(root, commits, since=0, author=None):
262
+ """The ledger row of a retrospective review of exactly this range, recorded after `since` rows, or None.
263
+
264
+ Given `author`, only a review of the range as that author's: another review of the same range that
265
+ ran meanwhile - `polyctl review --commits`, judged against the implementer configured now - recorded no
266
+ author, and a catch-up closed its waiver on it (CATCHUP-READY-2).
267
+ """
268
+ from .storage import read_chained_jsonl
269
+ rows = read_chained_jsonl(review_ledger_path(root), REVIEW_CHAIN)
270
+ for row in reversed(rows[since:]):
271
+ if isinstance(row, dict) and row.get("kind") == "commit-range" \
272
+ and row.get("commits") == commits and (author is None or row.get("author") == author):
273
+ return row
274
+ return None
275
+
276
+
277
+ def review_row_count(root):
278
+ """How many committed rows the review ledger holds when polyctl may append to it; refuses up front when rows past
279
+ the attested prefix or an in-tree checkpoint store would refuse the append, from one locked read of the
280
+ file with its handle closed (CATCHUP-ROW, LEDGER-ATTESTED)."""
281
+ from .storage import read_chained_jsonl
282
+ return len(read_chained_jsonl(review_ledger_path(root), REVIEW_CHAIN, for_append=True))
283
+
284
+
285
+ def latest_candidate_review(root, review_dir, candidate_digest, limit=40):
286
+ """Return approval only when the newest recorded review of the candidate approves."""
287
+ return candidate_review_decision(root, review_dir, candidate_digest)["match"]
288
+
289
+
290
+ AUTHORITY_CHAIN = "polyctl-authority-row-v1"
291
+
292
+
293
+ def authority_rows(root):
294
+ """All committed authority rows after validating the complete hash chain.
295
+
296
+ A non-empty legacy ledger without predecessor fields is deliberately
297
+ unreadable. Rewriting old authority in place would turn an append-only audit
298
+ trail into evidence manufactured by the reader.
299
+ """
300
+ from .storage import read_chained_jsonl
301
+ path = os.path.join(root, ".polyctl", "ledger", "authority.jsonl")
302
+ return read_chained_jsonl(path, AUTHORITY_CHAIN)
303
+
304
+
305
+ def authority_history(root):
306
+ """Every authority row ever committed, oldest first: those a seal retired, then the live ones, as one chain.
307
+
308
+ What was ever granted is asked here - the candidates a waiver authorised, the trees and the
309
+ first head the landed-tree check measures from, the reviews a grant rests on - and the newest
310
+ decision from `authority_rows`. Asked of the live rows, a seal made a spent waiver look unused,
311
+ so it stood in for a review of other bytes, and moved the landed-tree check's first grant past
312
+ commits it had not measured (the review of BOUNDED-STORES, LEDGER-HISTORY).
313
+ """
314
+ from .storage import read_chained_history
315
+ return read_chained_history(os.path.join(root, ".polyctl", "ledger", "authority.jsonl"), AUTHORITY_CHAIN)
316
+
317
+
318
+ def latest_authority_decision(root):
319
+ """Newest real boolean decision, only after the full chain validates."""
320
+ rows = authority_rows(root)
321
+ return next(
322
+ (row for row in reversed(rows)
323
+ if isinstance(row, dict) and type(row.get("granted")) is bool),
324
+ None,
325
+ )
326
+
327
+
328
+ VERIFICATION_CHAIN = "polyctl-verification-row-v1"
329
+
330
+
331
+ GATE_SUMMARY_TAIL_LINES = 30
332
+
333
+
334
+ def gate_counts(output, summary=None):
335
+ """Pass and fail counts from the summary a test runner ends with, or None (#70).
336
+
337
+ Only the last lines are read, and the last summary in them counts: a test name,
338
+ a log line or a fixture the implementer wrote can print "# pass 900" anywhere
339
+ earlier. A gate can name its runner's summary with `summary`, a regex with `pass`
340
+ and `fail` groups. Nothing found is None - unparsed, never a number. Both groups
341
+ must capture numbers; an unmatched group is not zero. A pytest closing line with
342
+ errors alone counts them as failures (TRIAGE-2-LOW).
343
+ """
344
+ tail = "\n".join(str(output or "").splitlines()[-GATE_SUMMARY_TAIL_LINES:])
345
+ if summary:
346
+ try:
347
+ found = list(re.finditer(summary, tail, re.M))
348
+ except re.error:
349
+ return None
350
+ if not found:
351
+ return None
352
+ groups = found[-1].groupdict()
353
+ try:
354
+ return int(groups["pass"]), int(groups["fail"])
355
+ except (KeyError, TypeError, ValueError):
356
+ return None
357
+ # Each summary a runner closes with is found where it ends, and the one that ends last counts. A node
358
+ # pair was taken before any pytest line wherever it stood, so a `# pass 900` / `# fail 0` a test printed
359
+ # above pytest's own closing line was read as the run's result (GATE-SUMMARY-2).
360
+ found = []
361
+ # node --test closes with "# pass N" / "# fail N" (TAP) or "ℹ pass N" / "ℹ fail N".
362
+ for mark in ("#", "ℹ"):
363
+ passes = list(re.finditer(rf"^{mark} pass (\d+)[ \t]*$", tail, re.M))
364
+ fails = list(re.finditer(rf"^{mark} fail (\d+)[ \t]*$", tail, re.M))
365
+ if passes and fails:
366
+ found.append((max(passes[-1].end(), fails[-1].end()),
367
+ (int(passes[-1].group(1)), int(fails[-1].group(1)))))
368
+ # pytest closes with "3 failed, 461 passed, 2 skipped in 12.30s".
369
+ for closing in re.finditer(r"^=*[ \t]*((?:\d+ [a-z]+(?:, )?)+) in [\d.]+s\b", tail, re.M):
370
+ counts = {word: int(n) for n, word in re.findall(r"(\d+) ([a-z]+)", closing.group(1))}
371
+ if {"passed", "failed", "error", "errors"}.intersection(counts):
372
+ found.append((closing.end(), (counts.get("passed", 0),
373
+ counts.get("failed", 0) + counts.get("error", 0) + counts.get("errors", 0))))
374
+ return max(found)[1] if found else None
375
+
376
+
377
+ def gate_summary_line(output, summary=None):
378
+ """The closing line gate_counts read its numbers from, or None (#6).
379
+
380
+ Kept in the verification beside the exit code, so a report can quote what the
381
+ runner said rather than a number the reporter typed.
382
+ """
383
+ tail = str(output or "").splitlines()[-GATE_SUMMARY_TAIL_LINES:]
384
+ if summary:
385
+ try:
386
+ found = [line for line in tail if re.search(summary, line)]
387
+ except re.error:
388
+ return None
389
+ return found[-1].strip()[:200] if found else None
390
+ for line in reversed(tail):
391
+ text = line.strip()
392
+ if re.match(r"^[#ℹ] (pass|fail) \d+$", text) or \
393
+ re.match(r"^=*[ \t]*(?:\d+ [a-z]+(?:, )?)+ in [\d.]+s\b", text):
394
+ return text.strip("= ")[:200]
395
+ return None
396
+
397
+
398
+ def verification_evidence(root):
399
+ """One line naming the newest verification: its id, each gate's exit and closing line (#6)."""
400
+ try:
401
+ record = latest_verification(root)
402
+ except Exception:
403
+ return None
404
+ if not record:
405
+ return None
406
+ gates = [f"{g.get('name')} exit {g.get('exit')}" + (f" ({g['summary']})" if g.get("summary") else "")
407
+ for g in record.get("gates") or [] if isinstance(g, dict)]
408
+ return (f"{record.get('id')} {'passed' if record.get('passed') else 'FAILED'}: "
409
+ + ("; ".join(gates) if gates else "no gates"))
410
+
411
+
412
+ # Read in whichever language a report is written (LANGUAGE-FILES).
413
+ _GREEN_CLAIM = re.compile(r"\b\d+\s+passed\b|\ball\s+(?:tests|gates|checks)\s+(?:pass|passed|green)\b|"
414
+ + "|".join(rf"\b{re.escape(word)}\b" for word in language.words("green")), re.I)
415
+ _RED_ADMISSION = re.compile(r"\b[1-9]\d*\s+(?:failed|errors?)\b|"
416
+ + "|".join(rf"\b{re.escape(word)}\b" for word in language.words("red")))
417
+
418
+
419
+ def report_inconsistency(root, text):
420
+ """Why a report that claims green contradicts the newest verification, or None (#6).
421
+
422
+ A report said "159 passed" while the suite had exited 1. The claim is read from
423
+ the report's words; the fact from the verification ledger. A report that admits
424
+ a failure, or a project with no verification, is not inconsistent.
425
+ """
426
+ body = str(text or "")
427
+ if not _GREEN_CLAIM.search(body) or _RED_ADMISSION.search(body):
428
+ return None
429
+ try:
430
+ record = latest_verification(root)
431
+ except Exception:
432
+ return None
433
+ if not record or record.get("passed") is not False:
434
+ return None
435
+ failed = [f"{g.get('name')} exit {g.get('exit')}" for g in record.get("gates") or []
436
+ if isinstance(g, dict) and not g.get("passed")]
437
+ return (f"the report claims green, but the newest verification {record.get('id')} failed"
438
+ + (f": {', '.join(failed)}" if failed else ""))
439
+
440
+
441
+ def gate_definitions_digest_of(spec, profile):
442
+ """Canonical digest of the gate definitions one profile runs, or None when it has none (#61).
443
+
444
+ `.polyctl/gates.json` is a file the implementer can write. A verification that does
445
+ not name the definitions it ran lets a gate weakened after the run inherit the
446
+ pass measured under the stronger one.
447
+ """
448
+ try:
449
+ ran = [[name, spec["gates"][name]] for name in spec["profiles"][profile]]
450
+ canonical = json.dumps({"profile": profile, "gates": ran}, ensure_ascii=True,
451
+ sort_keys=True, separators=(",", ":"))
452
+ except (KeyError, TypeError, ValueError):
453
+ return None
454
+ return "sha256:" + hashlib.sha256(canonical.encode("ascii")).hexdigest()
455
+
456
+
457
+ def gate_definitions_digest(root, profile):
458
+ """The digest of the definitions in force now, read from `.polyctl/gates.json`."""
459
+ try:
460
+ with open(os.path.join(root, ".polyctl", "gates.json"), encoding=UTF8) as fh:
461
+ spec = json.load(fh)
462
+ except (OSError, ValueError):
463
+ return None
464
+ return gate_definitions_digest_of(spec, profile)
465
+
466
+
467
+ def latest_verification(root):
468
+ """The newest complete, chained `polyctl verify` record, or None.
469
+
470
+ The ledger is chained like the authority ledger (#61), so a row appended
471
+ without a valid link makes it unreadable. Rows written before it was chained
472
+ carry no link; they stay readable as history and never count.
473
+ """
474
+ from .storage import CHAIN_PREVIOUS_FIELD, read_chained_jsonl
475
+ rows = read_chained_jsonl(os.path.join(root, ".polyctl", "ledger", "verifications.jsonl"),
476
+ VERIFICATION_CHAIN, legacy_prefix=True)
477
+ chained = [row for row in rows if CHAIN_PREVIOUS_FIELD in row]
478
+ return chained[-1] if chained else None
479
+
480
+
481
+ def verification_history(root):
482
+ """Every verification row ever committed, oldest first, the sealed ones held to their seal (LEDGER-HISTORY)."""
483
+ from .storage import read_chained_history
484
+ return read_chained_history(os.path.join(root, ".polyctl", "ledger", "verifications.jsonl"), VERIFICATION_CHAIN,
485
+ legacy_prefix=True)
486
+
487
+
488
+ def verification_by_id(root, vid):
489
+ """One verification row by id, the newest of that id, from the ledger or the rows a seal retired from it (#50).
490
+
491
+ The retired rows are held to their seal: an archived row edited after it was returned as edited (LEDGER-HISTORY).
492
+ """
493
+ return next((row for row in reversed(verification_history(root))
494
+ if isinstance(row, dict) and row.get("id") == vid), None)
495
+
496
+
497
+ def record_verification(root, record):
498
+ """Durably append one chained verification before reporting its result.
499
+
500
+ The machine's event log hears of it once the row is down (EVENTS-LOG).
501
+ """
502
+ from .storage import append_chained_jsonl
503
+ path = os.path.join(root, ".polyctl", "ledger", "verifications.jsonl")
504
+
505
+ def above_every_recorded(rows):
506
+ # Under the ledger's lock, where writers take turns: two runs that minted one id outside it - under one held
507
+ # machine lock, in one millisecond - recorded two verifications under it, which a grant names (LEADS-GATE).
508
+ taken = [int(found.group(1)) for found in (re.fullmatch(r"V-([0-9]+)", str(row.get("id") or ""))
509
+ for row in rows if isinstance(row, dict)) if found]
510
+ mine = re.fullmatch(r"V-([0-9]+)", str(record.get("id") or ""))
511
+ return {"id": f"V-{max(taken) + 1}"} if mine and taken and int(mine.group(1)) <= max(taken) else {}
512
+
513
+ record.setdefault("slice", (running_slice(root) or {}).get("id"))
514
+ row = append_chained_jsonl(path, scan_record(record), VERIFICATION_CHAIN, legacy_prefix=True,
515
+ prepare=above_every_recorded)
516
+ record["id"] = row.get("id") # the id it went under, which its caller reports
517
+ emit_event(root, "verification", {"id": row.get("id"), "passed": row.get("passed"), "profile": row.get("profile")})
518
+ return row
519
+
520
+
521
+ def _granted_trees(root, include_coordination=True):
522
+ """The index trees authority was granted for, and the commit the first grant built on, from the whole history.
523
+
524
+ Read from the live rows, a seal moved the first grant forward, and every commit between the
525
+ two went unmeasured (the review of BOUNDED-STORES, LEDGER-HISTORY). A coordination grant carries
526
+ no product review and must not make `harness_config_base` skip a commit's harness configuration
527
+ (the review of COORDINATION-COMMIT).
528
+ """
529
+ rows = [row for row in authority_history(root)
530
+ if isinstance(row, dict) and row.get("granted") is True
531
+ and (include_coordination or not row.get("coordination"))]
532
+ trees = {(row.get("candidate") or {}).get("index_tree") for row in rows}
533
+ trees.discard(None)
534
+ base = next(((row.get("candidate") or {}).get("head") for row in rows
535
+ if (row.get("candidate") or {}).get("head")), None)
536
+ return trees, base, rows
537
+
538
+
539
+ def landed_commit_problem(root, commit="HEAD"):
540
+ """Why a landed commit is not the tree its grant bound, or None when it is (#64).
541
+
542
+ commit-check measures the index when the pre-commit hook runs, and Git writes
543
+ the commit's tree from the index after hooks return, so a process that stages
544
+ a path in between lands it inside an authorised commit. A hook cannot prevent
545
+ that; comparing the tree that landed with the tree that was granted detects it.
546
+ """
547
+ try:
548
+ sha = _git_output(root, "rev-parse", "--verify", commit).decode("ascii").strip()
549
+ tree = _git_output(root, "rev-parse", "--verify", f"{commit}^{{tree}}").decode("ascii").strip()
550
+ except (RuntimeError, UnicodeError) as exc:
551
+ return f"cannot read {commit}: {exc}"
552
+ # The newest grant is a newest decision, read from the live rows; the history only when a seal retired it
553
+ # with nothing but refusals after it, so a commit does not wait on reading every archive (LEDGER-HISTORY).
554
+ rows = [row for row in authority_rows(root) if isinstance(row, dict) and row.get("granted") is True] \
555
+ or _granted_trees(root)[2]
556
+ grant = rows[-1] if rows else None
557
+ granted = ((grant or {}).get("candidate") or {}).get("index_tree")
558
+ if not granted:
559
+ return f"commit {sha[:12]} landed with no grant on record"
560
+ if granted != tree:
561
+ return (f"commit {sha[:12]} landed tree {tree[:12]}, but grant "
562
+ f"{grant.get('token') or '<unnamed>'} bound tree {granted[:12]}")
563
+ return None
564
+
565
+
566
+ def commits_without_grant(root, why=None):
567
+ """Landed commits, newest first, whose tree no grant bound (#64).
568
+
569
+ Only commits on top of the one the first grant was built on are measured;
570
+ history from before the authority ledger has nothing to be compared with.
571
+
572
+ Every one of them is measured. The doctor read the newest 50 and the watchdog the
573
+ newest 20, without merges: an ungranted commit with more granted ones on top fell
574
+ out of the window for good, and a merge whose tree was not its parents' - an edit
575
+ made while merging, or a tree committed with `git commit-tree` - was not read at
576
+ all (the reviews of LANDED-TREE and ATTACK-SUITE). A merge is named, whatever it
577
+ carries, as `polyctl commit-check --range` names it (`_merge_problems`): a grant binds one
578
+ parent, and polyctl lands no merge; nothing is merged to say so. The grants are every one
579
+ in the history, sealed ones too. `why`, a dict, is given the reason each commit is named. A ledger
580
+ or a git that cannot be read raises: a check that cannot run passes nothing
581
+ (LEDGER-HISTORY).
582
+
583
+ On polyctl's own history, 428 commits from the first grant's head with no merge, the
584
+ walk took about 25 ms of git.
585
+ """
586
+ trees, base, _ = _granted_trees(root)
587
+ if base is None:
588
+ return []
589
+ if not _OBJECT_ID.fullmatch(str(base)):
590
+ # A head comes from a ledger an agent can write; it reaches git as a revision, never as an option.
591
+ raise ValueError(f"the first grant names {str(base)[:80]!r} as the commit it was built on, which is no "
592
+ "commit id")
593
+ stray = []
594
+ for commit in landed_commits(root, f"{base}..HEAD"):
595
+ if len(commit["parents"]) > 1:
596
+ reason = _merge_problems(commit)[0]
597
+ elif commit["tree"] in trees:
598
+ continue
599
+ else:
600
+ reason = "no grant bound its tree"
601
+ stray.append(commit["sha"])
602
+ if why is not None:
603
+ why[commit["sha"]] = reason
604
+ return stray[::-1]
605
+
606
+
607
+ def landed_without_grant(root):
608
+ """What the landed-tree check finds, in the one line `polyctl doctor` and the watchdog say it in, or None (LEDGER-HISTORY).
609
+
610
+ The doctor names it as `landed-without-grant` and the watchdog raises the alarm of that name
611
+ with these words as what it says, so the one alarm both raise rings once for the commits it
612
+ names, and again when others land. A check that cannot run says so: it is never a pass.
613
+ """
614
+ why = {}
615
+ try:
616
+ stray = commits_without_grant(root, why)
617
+ except Exception as exc:
618
+ return ("the landed-tree check cannot run, so no commit since the first grant is known to have been granted: "
619
+ f"{' '.join(str(exc).split())[:300]} — polyctl doctor --consistency names what does not read")
620
+ if not stray:
621
+ return None
622
+ merges = sum(1 for sha in stray if why.get(sha) != "no grant bound its tree")
623
+ return (f"{len(stray)} commit(s) landed with a tree no grant bound: "
624
+ + ", ".join(sha[:12] for sha in stray[:5]) + (f" and {len(stray) - 5} more" if len(stray) > 5 else "")
625
+ + (f", {merges} of them a merge, which polyctl lands none of" if merges else "")
626
+ + " — made outside polyctl commit, or with a path staged after commit-check; read each with git show, then "
627
+ "revert it or have it reviewed (polyctl review --commits <sha>^..<sha>)")
628
+
629
+
630
+ # ---- a commit names the grant it was made under (COMMIT-TRAILER) --------------------------------
631
+
632
+ # The trailers `polyctl commit` ends a message with, in this order: the grant, the index tree it names, the
633
+ # verification it stood on, and the review or the waiver it rested on. A grant made with the review
634
+ # switch off rested on neither, and its Polyctl-Review says `off`. Git reads a trailer's key without case.
635
+ COMMIT_TRAILERS = ("Polyctl-Grant", "Polyctl-Tree", "Polyctl-Verification", "Polyctl-Review", "Polyctl-Waiver")
636
+ TRAILER_PREFIX = "polyctl-"
637
+ REVIEW_OFF = "off"
638
+ COORDINATION_TRAILER = "coordination"
639
+ # A trailer as git finds one with its default separator: letters, digits and hyphens, then the colon,
640
+ # spaces or tabs allowed before it.
641
+ _TRAILER_LINE = re.compile(r"[A-Za-z0-9-]+[ \t]*:")
642
+ _OBJECT_ID = re.compile(r"[0-9a-f]{40}|[0-9a-f]{64}")
643
+
644
+
645
+ def grant_trailers(grant):
646
+ """[(key, value)] naming the grant a commit is made under, read from its authority row (COMMIT-TRAILER).
647
+
648
+ Nothing is worked out again: the tree is the candidate's index tree the grant names, and the review
649
+ or the waiver is the one it recorded resting on. A coordination commit has no product verification or
650
+ review, and its trailers name `coordination` and the person who granted it (COORDINATION-COMMIT).
651
+ ValueError when the row is not a grant, or holds a value one line of a message cannot carry.
652
+ """
653
+ token = grant.get("token") if isinstance(grant, dict) else None
654
+ if not isinstance(grant, dict) or grant.get("granted") is not True:
655
+ raise ValueError(f"{token or 'the authority decision'} is not a grant")
656
+ candidate = grant.get("candidate") if isinstance(grant.get("candidate"), dict) else {}
657
+ coordination = grant.get("coordination")
658
+ if coordination:
659
+ by = (coordination.get("by") if isinstance(coordination, dict) else None) or grant.get("by")
660
+ review_val = (f"{COORDINATION_TRAILER} ({by})"
661
+ if isinstance(by, str) and by and by == by.strip() else None)
662
+ named = [("Polyctl-Grant", token), ("Polyctl-Tree", candidate.get("index_tree")),
663
+ ("Polyctl-Verification", COORDINATION_TRAILER), ("Polyctl-Review", review_val)]
664
+ else:
665
+ named = [("Polyctl-Grant", token), ("Polyctl-Tree", candidate.get("index_tree")),
666
+ ("Polyctl-Verification", grant.get("verification"))]
667
+ waivers = ", ".join(dict.fromkeys(w for w in (grant.get("waiver"), grant.get("gates_waiver"))
668
+ if isinstance(w, str) and w.strip()))
669
+ rested = ([("Polyctl-Review", grant["review"])] if grant.get("review") else []) \
670
+ + ([("Polyctl-Waiver", waivers)] if waivers else [])
671
+ named += rested or [("Polyctl-Review", REVIEW_OFF)]
672
+ for key, value in named:
673
+ if not isinstance(value, str) or not value or value != value.strip() \
674
+ or any(ch in value for ch in "\r\n\0"):
675
+ raise ValueError(f"grant {token or '<unnamed>'} records no {key} a trailer can carry")
676
+ return named
677
+
678
+
679
+ def _trailer_block(lines):
680
+ """Whether a paragraph is trailers alone as git reads them: each line one, or the continuation of one."""
681
+ return bool(lines) and bool(_TRAILER_LINE.match(lines[0])) \
682
+ and all(_TRAILER_LINE.match(line) or line[:1] in (" ", "\t") for line in lines[1:])
683
+
684
+
685
+ def with_trailers(message, trailers):
686
+ """`message` ending with `trailers`, in git's conventions (COMMIT-TRAILER).
687
+
688
+ Git reads a message's trailers from its last paragraph, and never from the first, its subject. A
689
+ message whose last paragraph is trailers alone - the Co-Authored-By it ends with - takes these after
690
+ its own, in one block; any other gets them as a paragraph of their own. Either way every line of the
691
+ last paragraph is a trailer, so `git interpret-trailers --parse` and `%(trailers)` read each one.
692
+ Blank lines at either end are dropped, as git drops them. ValueError for a message with nothing in
693
+ it, and for one whose last paragraph already holds a Polyctl- trailer: that would be a second set.
694
+ """
695
+ lines = message.split("\n")
696
+ while lines and not lines[0].strip():
697
+ lines.pop(0)
698
+ while lines and not lines[-1].strip():
699
+ lines.pop()
700
+ if not lines:
701
+ raise ValueError("the message is empty")
702
+ blank = [at for at, line in enumerate(lines) if not line.strip()]
703
+ block = [line.rstrip() for line in lines[blank[-1] + 1:]] if blank else []
704
+ joined = _trailer_block(block)
705
+ keys = [line.split(":", 1)[0].strip() for line in block if joined and _TRAILER_LINE.match(line)]
706
+ carried = sorted({key for key in keys if key.lower().startswith(TRAILER_PREFIX)})
707
+ if carried:
708
+ raise ValueError(f"the message already ends with {', '.join(carried)}: polyctl commit writes the Polyctl- trailers "
709
+ "itself, from the grant it checked, so take those lines out")
710
+ return "\n".join(lines + ([] if joined else [""]) + [f"{key}: {value}" for key, value in trailers]) + "\n"
711
+
712
+
713
+ def _polyctl_trailers(trailers):
714
+ """{key: [values]} of the Polyctl- trailers among [(key, value)], each key spelled as polyctl writes it."""
715
+ carried = {}
716
+ for key, value in trailers:
717
+ if key.lower().startswith(TRAILER_PREFIX):
718
+ name = next((known for known in COMMIT_TRAILERS if known.lower() == key.lower()), key)
719
+ carried.setdefault(name, []).append(value)
720
+ return carried
721
+
722
+
723
+ def landed_commits(root, revisions):
724
+ """[{sha, tree, parents, trailers, at}] of the commits `revisions` names, parents first (COMMIT-TRAILER).
725
+
726
+ Git reads the trailers itself, through `%(trailers)`: the last paragraph of the message, never its
727
+ subject, continuations unfolded, one (key, value) a trailer. `revisions` reaches git as one
728
+ argument. RuntimeError when git cannot list them.
729
+ """
730
+ raw = _git_output(root, "log", "--no-show-signature", "--topo-order", "--reverse", "-z",
731
+ "--format=%H%n%T%n%P%n%ct%n%(trailers:only,unfold)", revisions, "--", timeout=300)
732
+ commits = []
733
+ for record in raw.decode(UTF8, "replace").split("\0"):
734
+ lines = record.lstrip("\n").split("\n")
735
+ if not lines[0]:
736
+ continue
737
+ if len(lines) < 4 or not lines[3].isdigit() or not _OBJECT_ID.fullmatch(lines[0]) or not _OBJECT_ID.fullmatch(lines[1]):
738
+ raise RuntimeError(f"git listed a commit polyctl cannot read: {lines[0][:40]!r}")
739
+ trailers = [(key.strip(), value.strip()) for key, colon, value in
740
+ (line.partition(":") for line in lines[4:]) if colon and key.strip()]
741
+ commits.append({"sha": lines[0], "tree": lines[1], "parents": lines[2].split(), "trailers": trailers,
742
+ "at": int(lines[3])})
743
+ return commits
744
+
745
+
746
+ def ledger_grants(root):
747
+ """({token: authority row} this checkout's ledger holds, live and sealed, or None, why it cannot be read).
748
+
749
+ (None, None) where there is no authority ledger at all: a clone, as in CI (COMMIT-TRAILER).
750
+ """
751
+ path = os.path.join(root, ".polyctl", "ledger", "authority.jsonl")
752
+ try:
753
+ # The sealed rows held to their seal: an archived grant edited after it was taken as recorded (LEDGER-HISTORY).
754
+ rows = authority_history(root)
755
+ except Exception as exc:
756
+ return None, str(exc)
757
+ if not rows and not os.path.exists(path):
758
+ return None, None
759
+ return {row["token"]: row for row in rows if isinstance(row, dict) and isinstance(row.get("token"), str)}, None
760
+
761
+
762
+ def trailer_problems(commit, grants=None):
763
+ """Why a landed commit does not match the grant its Polyctl- trailers name; [] when it does (COMMIT-TRAILER).
764
+
765
+ Each trailer `polyctl commit` writes must be there once, and the commit's tree must be the tree Polyctl-Tree
766
+ names: a commit amended, rebased or rewritten after its grant has another. `grants`, {token: row},
767
+ is the checkout's authority ledger where it can be read, and a grant on record that names another
768
+ tree, verification, review or waiver fails the commit too. A grant it does not hold fails nothing:
769
+ a grant stays in the ledger of the checkout that made it, a lane's in the lane's own.
770
+ """
771
+ carried = _polyctl_trailers(commit["trailers"])
772
+ if not carried:
773
+ return ["carries no Polyctl- trailers, which polyctl commit writes"]
774
+ problems = [f"carries {len(values)} {key} trailers" for key, values in carried.items() if len(values) > 1]
775
+ problems += [f"has no {key} trailer" for key in COMMIT_TRAILERS[:3] if key not in carried]
776
+ if "Polyctl-Review" not in carried and "Polyctl-Waiver" not in carried:
777
+ problems.append("names no review or waiver its grant rested on")
778
+ problems += [f"carries {key}, which polyctl commit does not write"
779
+ for key in sorted(set(carried) - set(COMMIT_TRAILERS))]
780
+ if problems:
781
+ return problems
782
+ said = {key: values[0] for key, values in carried.items()}
783
+ if said["Polyctl-Tree"] != commit["tree"]:
784
+ problems.append(f"its tree {commit['tree'][:12]} is not {said['Polyctl-Tree'][:12]}, the tree its grant names: "
785
+ "it changed after the grant")
786
+ review_trailer = said.get("Polyctl-Review") or ""
787
+ if (said["Polyctl-Verification"] == COORDINATION_TRAILER
788
+ or review_trailer == COORDINATION_TRAILER
789
+ or review_trailer.startswith(f"{COORDINATION_TRAILER} (")):
790
+ prefix = f"{COORDINATION_TRAILER} ("
791
+ by_part = (review_trailer[len(prefix):-1].strip()
792
+ if review_trailer.startswith(prefix) and review_trailer.endswith(")") else "")
793
+ if said["Polyctl-Verification"] != COORDINATION_TRAILER or not by_part or "Polyctl-Waiver" in carried:
794
+ problems.append("carries an incomplete coordination grant in its Polyctl-Verification / Polyctl-Review trailers")
795
+ grant = (grants or {}).get(said["Polyctl-Grant"])
796
+ if grant is not None:
797
+ try:
798
+ recorded = dict(grant_trailers(grant))
799
+ except ValueError as exc:
800
+ problems.append(f"the ledger's record of it does not hold: {exc}")
801
+ else:
802
+ problems += [f"its {key} is {said.get(key) or 'missing'}, where the ledger's {said['Polyctl-Grant']} "
803
+ f"records {recorded.get(key) or 'none'}"
804
+ for key in COMMIT_TRAILERS if said.get(key) != recorded.get(key)]
805
+ return problems
806
+
807
+
808
+ def trailer_audit(root, revisions, since_first=False):
809
+ """Each commit of a revision range held to the grant its Polyctl- trailers name (COMMIT-TRAILER).
810
+
811
+ Read-only, and it needs no .polyctl/: `revisions` is `<a>..<b>`, or one commit for all of its history,
812
+ and each commit in it is judged by `trailer_problems`, against the checkout's authority ledger where
813
+ one can be read - except a merge, which `_merge_problems` refuses whatever it carries, without
814
+ merging anything (LEADS-GATE). `since_first` leaves out the commits older than the
815
+ first one carrying Polyctl- trailers - those it descends from - and every commit while none carries them:
816
+ history from before polyctl wrote them. Returns {commits, end, first, ledger, unreadable}; each commit
817
+ also holds merge, exempt, grant, problems and on_record (None where no ledger was read).
818
+ ValueError for a range polyctl does not hand to git; RuntimeError when git cannot read it.
819
+ """
820
+ spec = str(revisions or "")
821
+ _, dots, end = spec.partition("..")
822
+ end = (end or "HEAD") if dots else spec
823
+ if not spec or "..." in spec or spec.startswith("-") or end.startswith("-") \
824
+ or any(ch.isspace() or ch == "\0" for ch in spec):
825
+ raise ValueError(f"{spec!r} is not a range polyctl reads: give <a>..<b>, or one commit for all of its history")
826
+ commits = landed_commits(root, spec)
827
+ first, older = None, set()
828
+ if since_first:
829
+ history = landed_commits(root, end)
830
+ first = next((commit["sha"] for commit in history if _polyctl_trailers(commit["trailers"])), None)
831
+ parents = {commit["sha"]: commit["parents"] for commit in history}
832
+ if first is None:
833
+ older = set(parents)
834
+ else:
835
+ reach = list(parents.get(first, ()))
836
+ while reach:
837
+ sha = reach.pop()
838
+ if sha not in older:
839
+ older.add(sha)
840
+ reach.extend(parents.get(sha, ()))
841
+ grants, unreadable = ledger_grants(root)
842
+ for commit in commits:
843
+ commit["merge"] = len(commit["parents"]) > 1
844
+ commit["exempt"] = commit["sha"] in older
845
+ held = not commit["exempt"] and not commit["merge"]
846
+ if held:
847
+ commit["problems"] = trailer_problems(commit, grants)
848
+ elif not commit["exempt"]:
849
+ commit["problems"] = _merge_problems(commit)
850
+ else:
851
+ commit["problems"] = []
852
+ commit["grant"] = (_polyctl_trailers(commit["trailers"]).get("Polyctl-Grant") or [None])[0]
853
+ commit["on_record"] = commit["grant"] in grants if held and grants is not None else None
854
+ return {"commits": commits, "end": end, "first": first, "ledger": grants is not None, "unreadable": unreadable}
855
+
856
+
857
+ def _merge_problems(commit):
858
+ """Why a merge is no grant's: always, after the first commit that carries Polyctl- trailers, whatever it carries
859
+ (LEADS-GATE).
860
+
861
+ A merge was skipped as git's, and a merge's tree is whatever was committed: a conflict resolved by hand, or an
862
+ edit made while merging, landed unreviewed and passed the range check CI runs. Even git's own merge of two
863
+ reviewed parents is no grant's, since two changes each reviewed alone can act together where neither review
864
+ looked; and a grant binds one parent, the commit its candidate was built on, so trailers on a merge - copied, or
865
+ written by a commit of the granted tree - say nothing of what else it merges. A lane lands squashed
866
+ (`git merge --squash`), as one commit on one parent, which `polyctl commit` lands as any commit. Nothing is merged
867
+ again to say more: `git merge-tree` runs the merge drivers a repository configures, an implementer's choice among
868
+ them, and a range check reads and runs nothing.
869
+ """
870
+ return [f"it merges {len(commit['parents'])} parents, and a grant binds one: polyctl lands no merge - land a lane "
871
+ "squashed (git merge --squash), which polyctl commit lands as any commit"]
872
+
873
+
874
+ def record_authority(root, granted, reasons, tree, verification, token=None,
875
+ review=None, reviewer=None, candidate=None, scope=None,
876
+ matrix=None, role_bindings=None, implementer_identity=None,
877
+ reviewer_identity=None, waiver=None, gates_waiver=None,
878
+ waived_gates=None, author=None, move_only=None,
879
+ coordination=None):
880
+ """Persist one hash-chained authority decision, raising on any broken prefix."""
881
+ from .storage import append_chained_jsonl
882
+ record = {"at": int(time.time()), "granted": bool(granted),
883
+ "token": token, "reasons": reasons, "tree": tree,
884
+ "verification": verification, "review": review,
885
+ "reviewer": reviewer}
886
+ if matrix is not None:
887
+ record.update({
888
+ "schema": 3,
889
+ "candidate": candidate,
890
+ "scope": scope,
891
+ "matrix": matrix,
892
+ "role_bindings": role_bindings,
893
+ "implementer_identity": implementer_identity,
894
+ "reviewer_identity": reviewer_identity,
895
+ })
896
+ elif candidate is not None:
897
+ record.update({"schema": 2, "candidate": candidate, "scope": scope})
898
+ if waiver is not None:
899
+ # The waiver a grant stood on; it covers no other candidate after this (#67).
900
+ record["waiver"] = waiver
901
+ if gates_waiver is not None:
902
+ # When both review and gates are waived on one candidate, the second waiver is recorded beside the first.
903
+ record["gates_waiver"] = gates_waiver
904
+ if waived_gates is not None:
905
+ record["waived_gates"] = list(waived_gates)
906
+ if author is not None:
907
+ # Who landed work a waiver stood in for; its later review is held to that family (#65).
908
+ record["author"] = author
909
+ if move_only is not None:
910
+ # The move proof a move-only grant stood on; catch-up runs it again on what landed (#44).
911
+ record["move_only"] = move_only
912
+ if coordination is not None:
913
+ # A person's grant for a candidate that holds only coordination paths (COORDINATION-COMMIT).
914
+ record["coordination"] = coordination
915
+ if isinstance(coordination, dict) and coordination.get("by"):
916
+ record["by"] = coordination["by"]
917
+ path = os.path.join(root, ".polyctl", "ledger", "authority.jsonl")
918
+ # Keep the reviewer's identity here, not only in the review file. A grant is
919
+ # not real until the chain prefix validates and the locked append, file
920
+ # fsync and (on first creation) directory fsync have all completed.
921
+ row = append_chained_jsonl(path, record, AUTHORITY_CHAIN)
922
+ if row.get("granted"):
923
+ # The machine's event log hears of a grant once it is real; a refusal stays in this ledger (EVENTS-LOG).
924
+ emit_event(root, "authority-granted", {
925
+ "token": token, "verification": verification, "review": review, "waiver": waiver,
926
+ "coordination": True if coordination else None,
927
+ "index_tree": candidate.get("index_tree") if isinstance(candidate, dict) else None})
928
+ return row
929
+
930
+
931
+ GATE_LOCK = os.path.join(HOME, ".polyctl", "gate.lock")
932
+
933
+
934
+ def gate_lock_holder():
935
+ """Which project is running its gates right now, if any."""
936
+ if not os.path.exists(GATE_LOCK):
937
+ return None
938
+ try:
939
+ st = json.load(open(GATE_LOCK, encoding=UTF8))
940
+ except Exception:
941
+ return None
942
+ if not _pid_alive(st.get("pid", -1)): # stale lock from a killed run
943
+ try:
944
+ os.remove(GATE_LOCK)
945
+ except OSError:
946
+ pass
947
+ return None
948
+ st["minutes"] = int((time.time() - st.get("at", time.time())) / 60)
949
+ return st
950
+
951
+
952
+ def acquire_gate_lock(root, timeout=0):
953
+ """Serialise the expensive work across every project on this machine.
954
+
955
+ Roles split who decides; this splits who spends the machine. Each project's
956
+ watchdog is independent, so without a machine-wide lock N projects run N test
957
+ suites at once — and on a shared laptop that is not N times the throughput, it
958
+ is one suite that no longer finishes. This project watched an agent burn five
959
+ review rounds walking a concurrency setting down from 8 to 1 while fighting
960
+ exactly that.
961
+
962
+ Advisory and best-effort: a lock nobody can steal becomes a lock that wedges
963
+ the machine, so a holder whose process is gone is cleared on sight.
964
+ """
965
+ os.makedirs(os.path.dirname(GATE_LOCK), exist_ok=True)
966
+ deadline = time.time() + timeout
967
+ while True:
968
+ holder = gate_lock_holder()
969
+ if not holder:
970
+ try:
971
+ fd = os.open(GATE_LOCK, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
972
+ with os.fdopen(fd, "w", encoding=UTF8) as fh:
973
+ json.dump({"root": root, "pid": os.getpid(),
974
+ "at": int(time.time())}, fh)
975
+ return True
976
+ except FileExistsError:
977
+ pass
978
+ if time.time() >= deadline:
979
+ return False
980
+ time.sleep(2)
981
+
982
+
983
+ def release_gate_lock():
984
+ holder = gate_lock_holder()
985
+ if holder and holder.get("pid") == os.getpid():
986
+ try:
987
+ os.remove(GATE_LOCK)
988
+ except OSError:
989
+ pass
990
+
991
+
992
+ def self_or_ancestor(pid):
993
+ """Whether `pid` is this process or one of the processes that started it, parent after parent.
994
+
995
+ A process that holds the gate lock holds it for what it starts: `polyctl lock -- polyctl verify` runs
996
+ its verify as a child, and a child that waited for the lock its own parent holds would wait
997
+ until it gave up. Pid 1 is never counted, since every process descends from it; a walk that
998
+ meets a pid twice, or a parent the platform cannot read, stops there and answers no.
999
+ `ancestry` says which of the two it was.
1000
+ """
1001
+ return ancestry(pid)[0] is True
1002
+
1003
+
1004
+ def ancestry(pid):
1005
+ """(True, None) when `pid` is this process or started it; (False, None) when the walk reached the
1006
+ top without meeting it; (None, pid) naming the process whose parent the platform would not give,
1007
+ where the answer is not known (ANCESTOR-WINDOWS).
1008
+
1009
+ On Windows a parent pid can outlive its process and be given to another one, so a walk there
1010
+ can go on through a process that started nothing of this one; it still ends, at a pid met twice
1011
+ or at the top.
1012
+ """
1013
+ try:
1014
+ wanted = int(pid)
1015
+ except (TypeError, ValueError):
1016
+ return False, None
1017
+ from . import procs
1018
+ current, seen = os.getpid(), set()
1019
+ while current > 1 and current not in seen:
1020
+ if current == wanted:
1021
+ return True, None
1022
+ seen.add(current)
1023
+ parent = os.getppid() if current == os.getpid() else procs.ppid(current)
1024
+ if parent is None:
1025
+ return None, current
1026
+ current = parent
1027
+ return False, None
1028
+
1029
+
1030
+ def process_trees(pids, parent=None):
1031
+ """Group pids into independent trees — how many *turns*, not how many processes.
1032
+
1033
+ One turn is several processes: a wrapper spawns a runtime which spawns
1034
+ children. Counting processes therefore reports four concurrent writers where
1035
+ there is one, and an alarm that fires on normal operation is an alarm people
1036
+ learn to ignore. Count only the roots: a pid whose parent is not itself in the
1037
+ set.
1038
+ """
1039
+ if not pids:
1040
+ return []
1041
+ if parent is None:
1042
+ # The platform's process table (procs.py), as writers() reads it: `ps` through a shell
1043
+ # answered the same parents and does not exist on Windows.
1044
+ parent = {pid: row[0] for pid, row in _proc_table().items()}
1045
+ known = set(pids)
1046
+ return sorted(p for p in pids if parent.get(p) not in known)
1047
+
1048
+
1049
+ def anomalies(root, cfg, adapter, age, idle_seconds, exclude_pids=()):
1050
+ """Conditions a watchdog cannot resolve, reported as facts rather than verdicts.
1051
+
1052
+ A guard chain is good at mechanical questions — is a turn running, is there
1053
+ quota, has this nudge already failed. It is bad at everything else, and the
1054
+ failures of this project came from letting it try: it decided a provider
1055
+ outage was a stuck agent, decided a hung process was a live writer, decided a
1056
+ finished slice was work in progress. Each decision was defensible from the one
1057
+ signal it had and wrong given the others.
1058
+
1059
+ So it stops deciding. It collects what it can see and hands that to the
1060
+ architect, who has the context to weigh it. Crucially the facts carry no
1061
+ conclusion — "four processes, transcript moved 12s ago, HEAD unchanged for
1062
+ three hours" is useful; "there is a concurrent writer" is the guess that cost
1063
+ seven hours the last time something made it.
1064
+ """
1065
+ out = []
1066
+ groups = {}
1067
+
1068
+ # An explicit request outranks every heuristic here. When the implementer
1069
+ # writes to the architect it has already decided it is blocked, and waiting
1070
+ # for a detector to independently notice is absurd — this project spent half a
1071
+ # day doing exactly that while a message saying "decision required" sat
1072
+ # unread. Fire on the next cycle, not after a threshold.
1073
+ for m in mailbox(root, cfg.get("mailbox", "agent-mail")):
1074
+ if not to_architect(m, cfg):
1075
+ continue
1076
+ # The watchdog must not read its own outbox as an inbox. Its anomaly
1077
+ # reports are addressed to the architect ("watchdog-to-<architect>-…"), so they
1078
+ # matched this filter and were re-escalated as fresh "report-waiting"
1079
+ # anomalies — each new report's name concatenating the last, a runaway
1080
+ # that filled the mailbox with names hundreds of characters long. What
1081
+ # needs a decision is what the implementer or a human sent, never what
1082
+ # this detector emitted.
1083
+ # The hunter's leads wait for triage; they are not the implementer asking (#45).
1084
+ if m.startswith(("watchdog-to-", "hunter-to-")) or "-watchdog-to-" in m or "-hunter-to-" in m:
1085
+ continue
1086
+ # The architect's notes to itself are not the implementer asking (#18).
1087
+ if from_architect(m, cfg):
1088
+ continue
1089
+ try:
1090
+ body = open(os.path.join(root, cfg.get("mailbox", "agent-mail"), m),
1091
+ errors="replace", encoding=UTF8).read(4000)
1092
+ except OSError:
1093
+ continue
1094
+ first = next((l for l in body.split("\n") if l.strip().startswith("#")), m)
1095
+ # "I am blocked" and "I finished" both want the architect eventually, but
1096
+ # only one of them stops work. Treating a completion report as urgent is
1097
+ # how an urgent channel becomes background noise.
1098
+ # Match structure, not substrings. The implementer's report template ends
1099
+ # with a "Blockers:" line on every message, including "Blockers: none", so
1100
+ # a bare `"blocker" in body` test classified every routine status report
1101
+ # as urgent and re-raised it every ten minutes: twenty-eight false alarms
1102
+ # in one hour, produced by a line that said the opposite of what matched.
1103
+ # In every language a project may choose, whichever this one writes (LANGUAGE-FILES).
1104
+ low = language.folded(body)
1105
+ asking = any(h in low for h in language.lowered("decision", "urgent") + ("## blocked",))
1106
+ if not asking:
1107
+ for line in low.split("\n"):
1108
+ t = line.strip().lstrip("-*# ").strip()
1109
+ if not t.startswith(language.words("blockers")):
1110
+ continue
1111
+ value = t.split(":", 1)[1].strip(" .`")
1112
+ # An empty value, or one that opens by saying there are none, is
1113
+ # the template reporting health — not a request for anything.
1114
+ asking = bool(value) and not value.startswith(language.words("no-blockers"))
1115
+ break
1116
+ kind = "decision-requested" if asking else "report-waiting"
1117
+ contradiction = report_inconsistency(root, body)
1118
+ if contradiction:
1119
+ out.append({"kind": "inconsistent-report", "key": m, "reports": [m],
1120
+ "facts": [f"{m}: {contradiction}"]})
1121
+ g = groups.setdefault(kind, {"n": 0, "first": m, "reports": []})
1122
+ g["n"] += 1
1123
+ g["latest"] = m
1124
+ g["title"] = first.lstrip("# ").strip()[:200]
1125
+ g["reports"].append(m)
1126
+ # A review that came back and nobody took is a slice left unattended (#28, W1).
1127
+ waited = settings.get(cfg, "review.unhandled_minutes") * 60
1128
+ for state in returned_reviews(root):
1129
+ # Its own name: `age` is the transcript's, which the checks below read, and the loop wrote a returned
1130
+ # review's wait over it (PIPELINE-HANDLE-2).
1131
+ unattended = time.time() - float(state.get("finished_at") or time.time())
1132
+ if unattended >= waited:
1133
+ out.append({"kind": "review-returned", "key": state["id"],
1134
+ "facts": [f"{state['id']} for slice {state.get('slice')} "
1135
+ + (f"returned {state['verdict']}" if state.get("verdict") else
1136
+ f"ended {state.get('state')} with no verdict")
1137
+ + f" {int(unattended / 60)}m ago and has not been collected"]})
1138
+ # A question asked with `polyctl ask` wants the architect as much as a report does,
1139
+ # and may have no mail at all (#20). Each open one is its own anomaly.
1140
+ for decision in decisions(root, "open"):
1141
+ asked = decision.get("asked_at") or 0
1142
+ out.append({"kind": "decision-requested", "key": decision.get("id"),
1143
+ "facts": [f"{decision.get('id')} is open since "
1144
+ f"{time.strftime('%d %b %H:%M', time.localtime(asked)) if asked else '?'}",
1145
+ str(decision.get("question") or "")[:200]]})
1146
+ # One anomaly per kind, however many reports carry it. Eighty "queue empty"
1147
+ # reports in eleven hours became eighty anomaly files and forty wake attempts;
1148
+ # the architect needed one line saying "eighty, since 06:31". It carries the
1149
+ # reports it stands for, so what tells a person of it can name them and nothing
1150
+ # else tells a person of them again (WAITING-ONE-ALARM).
1151
+ for kind, g in groups.items():
1152
+ since = g["first"][:13] if re.match(r"\d{8}-\d{4}", g["first"]) else g["first"][:20]
1153
+ head = f"the implementer wrote {g['latest']}"
1154
+ if g["n"] > 1:
1155
+ head += f" — {g['n']} report(s) of this kind standing, the first since {since}"
1156
+ out.append({"kind": kind, "key": "implementer", "reports": g["reports"],
1157
+ "facts": [head, g["title"],
1158
+ "an explicit request — not a symptom needing corroboration"
1159
+ if kind == "decision-requested" else "a report, not a blocker"]})
1160
+
1161
+ # Exclude pids the caller knows are not implementer writers — above all the
1162
+ # architect the watchdog itself spawned, which resumes with this repo as its
1163
+ # cwd and would otherwise read as a second turn. The watchdog knows its pid;
1164
+ # the detector should not have to guess.
1165
+ # What a finished turn left behind is not a turn. Orphans are cleared by the
1166
+ # watchdog before it counts; here they are simply not counted.
1167
+ # Where the process table cannot be read no turn is counted here, and none is
1168
+ # guessed: the cycle's writer guard stands down on the same error and says why,
1169
+ # and the other conditions are still reported (WINDOWS-TABLE-CLOSED).
1170
+ from . import procs
1171
+ try:
1172
+ pids = [p for p in agent_pids(root, adapter) if p not in set(exclude_pids)]
1173
+ trees = process_trees([p for p in pids if p not in set(orphans(root, adapter))])
1174
+ except procs.TableUnreadable:
1175
+ pids, trees = [], []
1176
+ dirty = len([l for l in _git_text(root, "status", "--porcelain").split("\n") if l.strip()])
1177
+ head = _git_text(root, "rev-parse", "--short", "HEAD")
1178
+
1179
+ if len(trees) > 1 and age < idle_seconds:
1180
+ out.append({"kind": "several-turns-active", "roots": trees,
1181
+ "facts": [f"{len(trees)} independent process trees with this repo as "
1182
+ f"cwd, roots {trees} (of {len(pids)} processes)",
1183
+ f"transcript last written {int(age)}s ago",
1184
+ "separate roots mean separate turns, not one turn's children"]})
1185
+ spin = spinning(root)
1186
+ if spin:
1187
+ out.append({"kind": "busy-without-progress",
1188
+ "facts": [f"transcript growing for {spin}m",
1189
+ f"HEAD unchanged at {head}", f"{dirty} files dirty, unchanged"]})
1190
+ rn = rounds(root, cfg["reviews"])
1191
+ budget = settings.get(cfg, "round_budget")
1192
+ if rn > budget:
1193
+ revs = reviews(root, cfg["reviews"], limit=3)
1194
+ out.append({"kind": "over-round-budget",
1195
+ "facts": [f"round {rn} of {budget} on the current slice"] +
1196
+ [f"{f}: {v}" for f, v in revs]})
1197
+ # The same finding returning review after review. A round count cannot see
1198
+ # it; this is the actual shape of a slice that is not converging.
1199
+ loops = review_loop(root, cfg.get("reviews", "semantic-review"))
1200
+ if loops:
1201
+ out.append({"kind": "review-loop",
1202
+ "facts": [f"[{l['sev']}] {l['file']} — \"{l['clause']}\" has come back "
1203
+ f"{l['count']} reviews running" for l in loops[:4]] +
1204
+ ["more rounds will not converge this; it needs re-specifying "
1205
+ "or a different actor"]})
1206
+ err = last_nudge_error(root, parked=False)
1207
+ if err and time.time() - err.get("at", 0) < 3600:
1208
+ out.append({"kind": "restart-failed",
1209
+ "facts": [f"exit {err.get('code')} "
1210
+ f"{int((time.time() - err.get('at', 0)) / 60)}m ago",
1211
+ (err.get("tail") or "")[:300]]})
1212
+ return out
1213
+
1214
+
1215
+ def write_report(root, cfg, kind, facts, key=None):
1216
+ """A watchdog-to-architect message: observations, no interpretation.
1217
+
1218
+ Deduplicated by what the anomaly is *about*, not by wall-clock time. The name
1219
+ once carried a minute stamp, so the exists-guard only caught collisions inside
1220
+ the same minute and a standing condition produced a fresh file every cycle —
1221
+ twenty-five copies of one unread status report in an hour. Key the filename on
1222
+ (kind, source) instead: while an anomaly for that pair sits unprocessed, no
1223
+ second one is written. The architect deleting it is what re-arms the report,
1224
+ which is correct — a condition that recurs after it was judged is genuinely
1225
+ new.
1226
+ """
1227
+ box = os.path.join(root, cfg.get("mailbox", "agent-mail"))
1228
+ try:
1229
+ os.makedirs(box, exist_ok=True)
1230
+ # A stable key from the source the facts name (e.g. "the implementer wrote
1231
+ # X.md"), falling back to the kind alone for anomalies with no single
1232
+ # source. This is what makes the exists-guard actually guard.
1233
+ src = "-" + re.sub(r"[^A-Za-z0-9]+", "-", key).strip("-") if key else ""
1234
+ for f in [] if key else facts:
1235
+ mrk = re.search(r"wrote\s+(\S+\.md)", f)
1236
+ if mrk:
1237
+ src = "-" + re.sub(r"[^A-Za-z0-9]+", "-", mrk.group(1)[:-3]).strip("-")
1238
+ break
1239
+ _, arch = mail_names(cfg)
1240
+ name = f"watchdog-to-{arch}-ANOMALY-{kind}{src}.md"
1241
+ # A handled delivery keeps its ID; the next gets a suffix. Match the anomaly's
1242
+ # original name, not that delivery's ID, without conflating numbered keys (TRIAGE-2-MEDIUM).
1243
+ identities = {f"watchdog-to-{other}-ANOMALY-{kind}{src}.md" for other in architect_mail_names(cfg)}
1244
+ if any(mail_meta(os.path.join(box, pending)).get("anomaly", pending) in identities
1245
+ for pending in os.listdir(box) if pending.endswith(".md")):
1246
+ return None
1247
+ text = (f"# ANOMALY — {kind}\n\n"
1248
+ f"Watchdog observation at {time.strftime('%Y-%m-%d %H:%M:%S')}. "
1249
+ f"Facts only; the watchdog draws no conclusion and took no action "
1250
+ f"beyond standing down.\n\n"
1251
+ + "".join(f"- {f}\n" for f in facts)
1252
+ + "\n## Asked of the architect\n\n"
1253
+ "Decide whether this needs intervention, and what. If it is normal, "
1254
+ "delete this message; if not, act and record what you did.\n")
1255
+ return write_mail(root, cfg, name, text, {"kind": "anomaly", "from": "watchdog", "to": arch, "anomaly": name})
1256
+ except OSError:
1257
+ return None
1258
+
1259
+
1260
+ def usage_api(adapter_id):
1261
+ """The account lookup the shipped adapter of this id declares, when polyctl has its driver; {} (#76).
1262
+
1263
+ Only that adapter's own lookup answers: an implementer whose harness bills no account
1264
+ polyctl can read has none, not the first harness's that does. There is no first harness to
1265
+ fall back on: a reader that names no adapter reads no account (ACCOUNT-READERS). Read
1266
+ from the package's adapters only, since a lookup runs the command its adapter names,
1267
+ and a layer an agent can write must not name that command.
1268
+ """
1269
+ from . import drivers
1270
+ adapter = package_adapters().get(adapter_id) if isinstance(adapter_id, str) else None
1271
+ api = ((adapter or {}).get("billing") or {}).get("api") or {}
1272
+ return api if api.get("driver") in drivers.USAGE else {}
1273
+
1274
+
1275
+ def account_usage(timeout=20, adapter_id=None):
1276
+ """Real usage from the provider, through the driver an adapter's billing names; None when none can.
1277
+
1278
+ The protocol lives in drivers.py and every path, key, command and endpoint in
1279
+ the adapter, so this core function names no harness (#76). The account is the one
1280
+ `adapter_id`'s own lookup reads (`usage_api`): a call that names no adapter, or an
1281
+ adapter that declares no lookup, reads none (ACCOUNT-READERS).
1282
+ """
1283
+ from . import drivers
1284
+ api = usage_api(adapter_id)
1285
+ return drivers.USAGE[api["driver"]](api, timeout=timeout) if api else None
1286
+
1287
+
1288
+ def _marked_records(path, marks):
1289
+ """The records of a transcript's lines that hold one of `marks`; a line holding none is never parsed."""
1290
+ try:
1291
+ with open(path, errors="replace", encoding=UTF8) as fh:
1292
+ for line in fh:
1293
+ if not any(mark in line for mark in marks):
1294
+ continue
1295
+ try:
1296
+ rec = json.loads(line)
1297
+ except Exception:
1298
+ continue
1299
+ yield rec
1300
+ except OSError:
1301
+ return
1302
+
1303
+
1304
+ def credit_usage(adapter_id, monthly_budget=None):
1305
+ """Credit spend read from local transcripts, by billing month.
1306
+
1307
+ There is no endpoint for this. A Kiro API key authenticates the CLI
1308
+ (`KIRO_API_KEY`); it is not a REST credential, and the published docs
1309
+ describe no usage or quota route. The dashboard in the app is the authority.
1310
+
1311
+ The estimate stands in for one account: the one `adapter_id`'s shipped adapter bills.
1312
+ Another harness's transcripts are not that account's spend, nor in its unit, and they
1313
+ were added in whatever the implementer ran (ACCOUNT-READERS); a call that names no
1314
+ adapter reads nothing.
1315
+
1316
+ Locally, a session's usage records are read through what that shipped adapter
1317
+ declares (#76): which transcripts (`billing.fallback.transcripts`), which records
1318
+ carry usage and where its values are (`telemetry.cost`, `transcript.record`), and
1319
+ the reading that adds them up (`billing.fallback.reading`) - `sum` when a record is
1320
+ the whole cost of the turn it reports, `peak-per-turn` when it is the running total
1321
+ of the turn in progress, `per-response` when a response repeats its usage in several
1322
+ records and is charged once, whichever of the adapter's transcripts holds a copy. A
1323
+ fallback declaring no reading, or one polyctl does not implement, is not read rather than
1324
+ misread. The turns are the ones `polyctl cost` counts (`next_turn`), under the reading it
1325
+ applies too.
1326
+
1327
+ The reading is measured, not assumed. Kiro's records were once read as running
1328
+ totals, with a drop between two records taken for a new turn; in one machine's
1329
+ store (July to September 2026, 455 records) no turn wrote two, consecutive records
1330
+ never shared a request id, and taking peaks merged every run of turns whose cost
1331
+ rose into its last, reading 79% of what the records add up to. Every record there
1332
+ is a whole turn's cost.
1333
+
1334
+ What a record adds is charged to the day it was written, not to whenever the session
1335
+ was last touched: a long session crosses billing periods, and charging all of it to
1336
+ its final month is how a month reads as full while the previous one reads as empty.
1337
+
1338
+ A subagent a session started is that session's spend (`transcript.subagents`): its
1339
+ records are read after the record that starts it, charged to that turn and to the day
1340
+ each was written, under the same reading. A reply the harness wrote in the model's place
1341
+ with no usage (`in_place_reply`) is not read, so a turn holding no other is no session turn.
1342
+ """
1343
+ import glob
1344
+ from collections import defaultdict
1345
+ months, days, sessions = defaultdict(float), defaultdict(float), []
1346
+ sources = []
1347
+ for ident, adapter in sorted(package_adapters().items()):
1348
+ if ident != adapter_id:
1349
+ continue
1350
+ fallback = (adapter.get("billing") or {}).get("fallback") or {}
1351
+ shape = transcript_shape(adapter)
1352
+ if fallback.get("transcripts") and fallback.get("reading") in USAGE_READINGS and shape["usage"]:
1353
+ # A line naming neither the usage field nor a kind that opens or ends a turn is never parsed,
1354
+ # unless it may start a subagent: a field that names one, or the kind of a tool call.
1355
+ starts = [entry["named_by"] for entry in (shape["subagents"] or {}).get("transcripts") or []]
1356
+ calls = [shape["tool"]["type"]] if shape["subagents"] and shape["tool"] else []
1357
+ marks = sorted({'"' + field.split(".")[0].split("[")[0] + '"'
1358
+ for field in shape["usage"]["fields"] + [path for path in starts if path]}
1359
+ | {'"' + kind + '"' for kind in shape["start"] + shape["prompt"] + shape["end"]
1360
+ + [when["type"] for when in shape["end_when"]] + calls})
1361
+ counted = {} # one reading of this adapter's transcripts: a response is charged once
1362
+ sources += [(path, shape, marks, counted) for path in glob.glob(_home_path(fallback["transcripts"]))]
1363
+ for f, shape, marks, counted in sources:
1364
+ usage, turn, turns, credits, day, month = shape["usage"], None, 0, 0.0, "", ""
1365
+ for rec, subagent in with_subagents(_marked_records(f, marks), shape, f,
1366
+ lambda path, marks=marks: _marked_records(path, marks)):
1367
+ kind = record_kind(rec, shape)
1368
+ turn, _ = next_turn(turn, rec, shape, subagent)
1369
+ pl = record_body(rec, shape)
1370
+ if pl is None or kind != usage["type"] or in_place_reply(rec, shape):
1371
+ continue
1372
+ turn = {} if turn is None else turn # usage before any turn opens is a turn of its own
1373
+ if "usage" not in turn:
1374
+ turns += 1
1375
+ grown = add_usage(turn, pl, usage, counted, subagent)
1376
+ credits += grown
1377
+ day = record_time(rec, shape)[:10] or day
1378
+ if day:
1379
+ days[day] += grown
1380
+ months[day[:7]] += grown
1381
+ month = day[:7]
1382
+ if turns:
1383
+ sessions.append({"session": os.path.basename(os.path.dirname(f)),
1384
+ "month": month, "turns": turns, "credits": round(credits, 2),
1385
+ "mtime": os.path.getmtime(f)})
1386
+ sessions.sort(key=lambda r: r["mtime"], reverse=True)
1387
+ this_month = time.strftime("%Y-%m")
1388
+ # Billing periods are not calendar months — a subscription renews on its own
1389
+ # day — so return the daily series and let the caller cut it wherever the
1390
+ # user's period actually starts.
1391
+ return {"sessions": sessions, "days": {d: round(v, 2) for d, v in sorted(days.items())},
1392
+ "months": {m: round(v, 2) for m, v in sorted(months.items())},
1393
+ "this_month": round(months.get(this_month, 0.0), 2),
1394
+ "budget": monthly_budget,
1395
+ "remaining": (round(monthly_budget - months.get(this_month, 0.0), 2)
1396
+ if monthly_budget else None)}
1397
+
1398
+
1399
+ # Every language's urgent and stop headings, whichever the project writes (LANGUAGE-FILES). Compared in
1400
+ # capitals, so `## ACİL` keeps its dotted İ.
1401
+ URGENT_MARKERS = language.forms("urgent", "stop")
1402
+
1403
+
1404
+ ROLES = ("implementer", "architect")
1405
+
1406
+
1407
+ def invoking_role():
1408
+ """The role this polyctl process runs for, from POLYCTL_ROLE, or None for a person or an unknown caller (#29)."""
1409
+ role = (os.environ.get("POLYCTL_ROLE") or "").strip().lower()
1410
+ return role if role in ROLES else None
1411
+
1412
+
1413
+ def returned_reviews(root):
1414
+ """Submitted reviews that have ended and that nobody has collected yet (#28)."""
1415
+ directory = os.path.join(root, ".polyctl", "reviews")
1416
+ try:
1417
+ names = sorted(os.listdir(directory))
1418
+ except OSError:
1419
+ return []
1420
+ out = []
1421
+ for name in names:
1422
+ if not (name.startswith("R-") and name.endswith(".json")):
1423
+ continue
1424
+ try:
1425
+ with open(os.path.join(directory, name), encoding=UTF8) as fh:
1426
+ state = json.load(fh)
1427
+ except (OSError, ValueError):
1428
+ continue
1429
+ if isinstance(state, dict) and state.get("state") not in (None, "running") \
1430
+ and not state.get("collected_at"):
1431
+ # Named by its file where the record names nothing: every reader indexes the id, and one record
1432
+ # without it stopped `polyctl status` and the watchdog's anomalies (PIPELINE-HANDLE-2).
1433
+ rid = state.get("id")
1434
+ out.append(state if isinstance(rid, str) and rid else dict(state, id=name[:-len(".json")]))
1435
+ return out
1436
+
1437
+
1438
+ def urgent_messages(root, cfg, role="implementer"):
1439
+ """Unacknowledged messages the implementer must see before it does anything big.
1440
+
1441
+ MCP cannot interrupt. Its tools fire only when the agent chooses to call them,
1442
+ so an urgent message sits unread until the agent's next `polyctl_inbox` — which may
1443
+ be a turn away, or never if it is stuck. A2A agents get an inbound push; an
1444
+ MCP-only agent does not, and no amount of protocol design changes that.
1445
+
1446
+ What we do control is the boundary the agent crosses on its own: it runs `polyctl`
1447
+ to take the machine lock, to verify, and to ask whether it may commit. Those
1448
+ are precisely the moments before something expensive or irreversible, which is
1449
+ exactly when an urgent message needs to land. So the CLI carries it.
1450
+
1451
+ Marked messages only. Everything routine waits for `polyctl_inbox`, or the channel
1452
+ becomes noise and gets skimmed — which is how it fails.
1453
+
1454
+ Urgency follows inbox addressing, including the reviewer, and role None takes
1455
+ all recipients. Reviewer mail otherwise blocked commits while the implementer
1456
+ could neither see nor acknowledge it (TRIAGE-3-LOW).
1457
+ """
1458
+ box = cfg.get("mailbox", "agent-mail")
1459
+ out = []
1460
+ for m in mailbox(root, box):
1461
+ addressed = "architect" if to_architect(m, cfg) else "reviewer" if to_reviewer(m, cfg) else "implementer"
1462
+ if role and (addressed != role or not addressed_to(m, cfg, role)):
1463
+ continue
1464
+ try:
1465
+ body = open(os.path.join(root, box, m), errors="replace", encoding=UTF8).read(8000)
1466
+ except OSError:
1467
+ continue
1468
+ upper = body.upper()
1469
+ if any(k.upper() in upper for k in URGENT_MARKERS):
1470
+ title = next((l for l in body.split("\n") if l.strip().startswith("# ")), m)
1471
+ out.append({"id": m, "title": title.lstrip("# ").strip()[:120], "body": body,
1472
+ "to": addressed})
1473
+ return out
1474
+
1475
+
1476
+ def escaped_cwd_dir(store, cwd):
1477
+ """The directory an escaped-cwd store keeps a working directory's sessions in (#71, #76).
1478
+
1479
+ On macOS and Linux the name is the absolute path with "/" and "." made
1480
+ dashes. polyctl built it that way everywhere, and on Windows `C:\\repo` kept its
1481
+ drive: os.path.join took it as an absolute path, dropped the store's directory,
1482
+ and the watchdog found no transcript and ended every cycle there. On Windows
1483
+ every character outside letters, digits and dashes is made a dash. A
1484
+ directory that already exists under either name is used as found.
1485
+ """
1486
+ base = _home_path((store or {}).get("dir"))
1487
+ posix, portable = escaped_cwd_names(cwd)
1488
+ for name in (posix, portable):
1489
+ if name and "/" not in name and "\\" not in name and ":" not in name \
1490
+ and os.path.isdir(os.path.join(base, name)):
1491
+ return os.path.join(base, name)
1492
+ return os.path.join(base, portable if os.name == "nt" else posix)
1493
+
1494
+
1495
+ def escaped_cwd_names(cwd):
1496
+ """(posix, portable): the names an escaped-cwd store may give a working directory's directory.
1497
+
1498
+ "/" and "." made dashes, as polyctl named it on macOS and Linux; and every character that is
1499
+ not a letter, a digit or a dash made one, as Windows needs and as the store's own
1500
+ documentation describes it.
1501
+ """
1502
+ cwd = str(cwd or "")
1503
+ return cwd.replace("/", "-").replace(".", "-"), re.sub(r"[^A-Za-z0-9-]", "-", cwd)
1504
+
1505
+
1506
+ def session_in_use(session, architect=None):
1507
+ """Pids whose command line resumes `session`: as an argument of its own, or after `=` (JOURNAL-2).
1508
+
1509
+ Only the architect's own harness resumes its session: a `grep`, a `jq --arg` or a tmux named for the id
1510
+ carries it too, and held every wake while it ran. procs.TableUnreadable where the process table cannot
1511
+ be read: a session nobody could be seen holding read as free, and a wake could resume it beside its
1512
+ holder (WINDOWS-TABLE-CLOSED).
1513
+ """
1514
+ from . import procs
1515
+ if not session:
1516
+ return []
1517
+ names = _architect_names(architect)
1518
+ found = []
1519
+ for pid in procs.all_pids():
1520
+ if pid == os.getpid():
1521
+ continue
1522
+ av = procs.argv(pid) or []
1523
+ if names and not _is_configured_agent_process(names, av):
1524
+ continue
1525
+ if any(str(arg) == session or str(arg).endswith("=" + session) for arg in av[1:]):
1526
+ found.append(pid)
1527
+ return found
1528
+
1529
+
1530
+ def unplaced_agent_pids(root, adapter):
1531
+ """Agent processes that may be working in this tree but cannot be placed (#71).
1532
+
1533
+ On Windows a process's working directory is read from its own memory, which
1534
+ another user's or an elevated process does not open to polyctl, and no shipped
1535
+ adapter's command line names the repository: such a turn in this tree was no
1536
+ writer at all, `polyctl hold` stopped nothing and the watchdog started a second
1537
+ turn. The guards that must not miss a writer count these and say why. Where
1538
+ every process's directory can be read this is empty (WINDOWS-CWD-2); where the
1539
+ table itself cannot be read it raises procs.TableUnreadable, as agent_pids does
1540
+ (WINDOWS-TABLE-CLOSED).
1541
+ """
1542
+ if os.name != "nt":
1543
+ return []
1544
+ from . import procs
1545
+ names = set()
1546
+ for key in ("send", "resume"):
1547
+ argv = (adapter.get(key) or {}).get("argv") or []
1548
+ if argv:
1549
+ names.add(os.path.basename(argv[0]))
1550
+ names.update(agent_process_names())
1551
+ want = os.path.realpath(root)
1552
+ me = os.getpid()
1553
+ helpers = helper_pids(root)
1554
+ table = _proc_table() if helpers else {}
1555
+
1556
+ def under_helper(pid):
1557
+ seen, current = set(), pid
1558
+ while current > 1 and current not in seen:
1559
+ if current in helpers:
1560
+ return True
1561
+ seen.add(current)
1562
+ current = table.get(current, (0, 0, ""))[0]
1563
+ return False
1564
+
1565
+ out = []
1566
+ for pid in procs.all_pids():
1567
+ if pid == me:
1568
+ continue
1569
+ av = procs.argv(pid)
1570
+ if not av or not _is_agent_process(pid, names, av) or procs.cwd(pid) is not None:
1571
+ continue
1572
+ if any(os.path.isabs(a) and os.path.realpath(a.rstrip("/\\")) == want for a in av):
1573
+ continue # it names this tree: agent_pids placed it
1574
+ if helpers and under_helper(pid):
1575
+ continue
1576
+ out.append(pid)
1577
+ return sorted(out)
1578
+
1579
+
1580
+ def git_text(root, *args, timeout=60):
1581
+ """git's output as text without a shell, or "" when git fails (#71).
1582
+
1583
+ cmd.exe treats neither single quotes nor `2>/dev/null` as a POSIX shell does:
1584
+ the quoted `--pretty` format was split at its "|" and the log came back empty.
1585
+ """
1586
+ try:
1587
+ return _git_output(root, *args, timeout=timeout).decode(UTF8, "replace").strip()
1588
+ except RuntimeError:
1589
+ return ""
1590
+
1591
+
1592
+ def discover_architect(cwd):
1593
+ """The newest session an escaped-cwd store keeps for a directory, by transcript mtime.
1594
+
1595
+ Pinning a session id in config goes stale the moment the human opens a new
1596
+ conversation, and a watchdog that wakes a dead session fails silently — the
1597
+ worst shape of failure, because everything still looks configured. Resolve it
1598
+ from disk instead, the same way the implementer's session is resolved.
1599
+
1600
+ The newest is the architect's only where no other role's sessions are kept there:
1601
+ where the implementer runs the same harness in the same directory, the newest was
1602
+ the implementer's own session, and a wake resumed it as the architect. `sessions`
1603
+ names every session found, newest first, for resolve_session to choose among
1604
+ (SESSION-IDENTITY).
1605
+ """
1606
+ # The store flattens the path into a directory name - a worktree under a
1607
+ # dot-directory gets a doubled dash where "/." was - and on Windows the drive
1608
+ # and backslashes go the same way (#71).
1609
+ found = sorted((row for ident, _ in session_stores("escaped-cwd") for row in store_sessions(ident, cwd)),
1610
+ key=lambda row: row["mtime"], reverse=True)
1611
+ if not found:
1612
+ return None
1613
+ best = found[0]
1614
+ return {"session": best["session"], "transcript": best["transcript"], "age": int(time.time() - best["mtime"]),
1615
+ "adapter": best["adapter"], "sessions": [row["session"] for row in found]}
1616
+
1617
+
1618
+ # The name of a program no process has: an architect whose program cannot be named is proven by none (JOURNAL-2-5).
1619
+ _NO_PROGRAM = "<no program>"
1620
+
1621
+
1622
+ def _architect_names(architect):
1623
+ """The program names the configured architect runs as: its command and that adapter's other names (#76)."""
1624
+ configured = (architect or {}).get("argv") or []
1625
+ command = _program_name(configured[0]) if configured else ""
1626
+ if runtime_family(command):
1627
+ # A runtime runs many programs: an architect run as `node /opt/claude-code/cli.js` is that program, where
1628
+ # `node` alone let any node process naming the session hold every wake (JOURNAL-2-3), and `python -m claude`
1629
+ # is claude, where its second word, `-m`, was taken for the program (JOURNAL-2-4). One whose program has no
1630
+ # name - code given inline - is proven by no process, where the runtime alone matched every one of it
1631
+ # (JOURNAL-2-5).
1632
+ program = runtime_program_word(configured)
1633
+ command = _program_name(program) if program and "{" not in program else _NO_PROGRAM
1634
+ names = {command} if command else set()
1635
+ for ident, adapter in package_adapters().items():
1636
+ known = {_program_name(name) for name in [ident, *adapter_binaries(adapter),
1637
+ *((adapter.get("detect") or {}).get("processes") or [])] if name}
1638
+ if command in known:
1639
+ names.update(known)
1640
+ return names
1641
+
1642
+
1643
+ def _architect_process_roots(root, architect=None, helper_only=False):
1644
+ """Configured architect roots, optionally restricted to proven polyctl helpers."""
1645
+ from . import procs
1646
+
1647
+ if architect is None:
1648
+ try:
1649
+ architect = (load_config(root).get("architect") or {})
1650
+ except (OSError, TypeError, ValueError):
1651
+ architect = {}
1652
+ architect = architect or {}
1653
+ configured = architect.get("argv") or []
1654
+ if not configured:
1655
+ return []
1656
+
1657
+ # The architect's names are its command's and that adapter's other names - an implementer on one harness
1658
+ # must not become an architect on another merely because both are interactive in the same tree (#76) - and
1659
+ # a runtime's architect is the program it runs. They were worked out here a second time, without the
1660
+ # runtime, so any `python` process in the tree was the architect of one run as `python -m claude`
1661
+ # (JOURNAL-2-5).
1662
+ names = _architect_names(architect)
1663
+ if not names:
1664
+ return []
1665
+
1666
+ def normal_path(path):
1667
+ raw = str(path).replace("\\", "/")
1668
+ if re.match(r"^[A-Za-z]:/", raw):
1669
+ return raw.rstrip("/").lower()
1670
+ return os.path.normcase(os.path.realpath(raw))
1671
+
1672
+ def absolute_path(path):
1673
+ raw = str(path).replace("\\", "/")
1674
+ return os.path.isabs(raw) or bool(re.match(r"^[A-Za-z]:/", raw))
1675
+
1676
+ targets = {normal_path(architect.get("cwd") or root)}
1677
+ if helper_only:
1678
+ # Watchdog helpers are spawned in the project root even when the human
1679
+ # architect works in a configured worktree.
1680
+ targets.add(normal_path(root))
1681
+ table = _proc_table()
1682
+ parents = {pid: row[0] for pid, row in table.items()}
1683
+ helpers = helper_pids(root, "architect" if helper_only else None)
1684
+
1685
+ def under_helper(pid):
1686
+ current = pid
1687
+ seen = set()
1688
+ while current > 1 and current not in seen:
1689
+ if current in helpers:
1690
+ return True
1691
+ seen.add(current)
1692
+ current = parents.get(current, 0)
1693
+ return False
1694
+
1695
+ candidates = set()
1696
+ vectors = {}
1697
+ for pid in procs.all_pids():
1698
+ helper = under_helper(pid)
1699
+ if pid == os.getpid() or (helper_only and not helper) \
1700
+ or (not helper_only and helper):
1701
+ continue
1702
+ argv = procs.argv(pid)
1703
+ if not argv or not _is_configured_agent_process(names, argv):
1704
+ continue
1705
+ cwd = procs.cwd(pid)
1706
+ if cwd is None:
1707
+ # A cwd the platform cannot read (a 32-bit or protected process on
1708
+ # Windows, #9). Keep the same fail-closed fallback as agent_pids():
1709
+ # an exact absolute repository argument is required.
1710
+ in_project = any(
1711
+ normal_path(arg.rstrip("/\\")) in targets
1712
+ for arg in argv if absolute_path(arg)
1713
+ )
1714
+ else:
1715
+ in_project = normal_path(cwd) in targets
1716
+ if not in_project:
1717
+ continue
1718
+ candidates.add(pid)
1719
+ vectors[pid] = argv
1720
+
1721
+ # Preserve ancestry through nonmatching intermediaries. Filtering first and
1722
+ # looking only at an immediate parent turns `claude -p -> shell -> runtime`
1723
+ # into two roots; the flagless runtime then looks interactive. Walk the full
1724
+ # parent graph and assign every matching process to its highest matching
1725
+ # ancestor, with cycle detection for a corrupt or racing process snapshot.
1726
+ roots = set()
1727
+ for pid in candidates:
1728
+ root_pid = pid
1729
+ current = pid
1730
+ seen = set()
1731
+ while current not in seen:
1732
+ seen.add(current)
1733
+ parent = parents.get(current, 0)
1734
+ if parent in candidates:
1735
+ root_pid = parent
1736
+ if parent <= 1 or parent not in parents:
1737
+ break
1738
+ current = parent
1739
+ roots.add(root_pid)
1740
+ return [(pid, vectors[pid]) for pid in sorted(roots)]
1741
+
1742
+
1743
+ def architect_present(root, architect=None):
1744
+ """Is a human-driven architect process alive for this project?
1745
+
1746
+ Presence is a process fact, not transcript recency. Match only the configured
1747
+ architect command in its configured cwd, exclude polyctl helpers and descendants,
1748
+ and classify headlessness at the full process-tree root, by the arguments the
1749
+ harness it runs as declares (`_headless_argv`). No positive result is cached,
1750
+ so process exit releases presence on the next scan. procs.TableUnreadable where
1751
+ the process table cannot be read: absence that was not measured is not absence
1752
+ (WINDOWS-TABLE-CLOSED).
1753
+ """
1754
+ return any(
1755
+ not _headless_argv(argv)
1756
+ for _, argv in _architect_process_roots(root, architect)
1757
+ )
1758
+
1759
+
1760
+ def architect_turn_present(root, architect=None):
1761
+ """Is a configured architect process alive in a proven polyctl helper tree?
1762
+
1763
+ This is the duplicate-wake guard. It revalidates the registered helper's
1764
+ process-start identity and current process tree; an unrelated same-binary
1765
+ implementer, remembered pid, or lock file cannot postpone a wake. Where the
1766
+ process table cannot be read it raises procs.TableUnreadable, and no wake
1767
+ starts beside one it could not see (WINDOWS-TABLE-CLOSED).
1768
+ """
1769
+ return bool(_architect_process_roots(root, architect, helper_only=True))
1770
+
1771
+
1772
+ DECISION_DIR = ".polyctl/decisions"
1773
+ # The state of a rule proposal's question until a person answers it (RULE-PROPOSALS). Not "open": every
1774
+ # reader of an open question reads one that parks a slice, and a proposal parks none.
1775
+ PROPOSED = "proposed"
1776
+
1777
+
1778
+ def decisions(root, state=None):
1779
+ """Open questions the implementer cannot answer for itself.
1780
+
1781
+ A blocker written as prose costs minutes to answer from a phone: read it,
1782
+ work out what is being asked, type a paragraph. The same blocker written as
1783
+ a question with options costs one tap. That difference decides whether a run
1784
+ survives the hours when nobody is at a desk.
1785
+ """
1786
+ d = os.path.join(root, DECISION_DIR)
1787
+ out = []
1788
+ if not os.path.isdir(d):
1789
+ return out
1790
+ for f in sorted(os.listdir(d)):
1791
+ if not f.endswith(".json"):
1792
+ continue
1793
+ try:
1794
+ rec = json.load(open(os.path.join(d, f), encoding=UTF8))
1795
+ except Exception:
1796
+ continue
1797
+ rec["id"] = f[:-5]
1798
+ if state and rec.get("state") != state:
1799
+ continue
1800
+ out.append(rec)
1801
+ return out
1802
+
1803
+
1804
+ def ask(root, question, options, context=None, slice_id=None, cfg=None, proposal=False, after=0):
1805
+ """Record a question. Free text is always the last option.
1806
+
1807
+ Options are a convenience, never a cage: the answer that matters is often the
1808
+ one nobody listed, and a form that cannot express it produces a wrong answer
1809
+ chosen because it was available.
1810
+
1811
+ The free-text option is labeled in the project's language, read from `cfg` or, without one,
1812
+ from the project's config on disk (LANGUAGE-OUTPUT).
1813
+
1814
+ A rule proposal's question (`proposal`) waits in the state `proposed` and names its
1815
+ proposal, `P-` with the question's number (RULE-PROPOSALS). It parks no slice, so nothing
1816
+ that waits on an open question waits on it: a nudge standing down, the alarm ladder, a
1817
+ wake of the architect, a handoff's list of what unblocks the work.
1818
+
1819
+ Each question is a file of its own, created and never replaced. Two asked in one second
1820
+ shared an id and the second overwrote the first; the later now takes the next free number.
1821
+ The number also exceeds `after`: a number stays taken where a ledger names it after its
1822
+ question's file is gone, as a rule proposal's does.
1823
+ """
1824
+ d = os.path.join(root, DECISION_DIR)
1825
+ os.makedirs(d, exist_ok=True)
1826
+ opts = [{"key": chr(ord('a') + i), "label": o} for i, o in enumerate(options[:8])]
1827
+ written = cfg if cfg is not None else project_config_document(root)["config"]
1828
+ opts.append({"key": "x", "label": language.marker(written, "free-text"), "free_text": True})
1829
+ # The same question answered before, here or in another project, travels with it (#43).
1830
+ try:
1831
+ precedents = [{key: found.get(key) for key in ("project", "kind", "id", "at", "outcome", "source")}
1832
+ for found in recall(f"{question} {context or ''}", root, limit=3, share=0.4)]
1833
+ except Exception:
1834
+ precedents = []
1835
+ rec = scan_record({"asked_at": int(time.time()), "question": question, "context": context,
1836
+ "slice": slice_id, "options": opts, "state": PROPOSED if proposal else "open",
1837
+ "answer": None, "answered_at": None, "answered_by": None,
1838
+ "precedents": precedents})
1839
+ number = max(rec["asked_at"], int(after) + 1)
1840
+ while True:
1841
+ did = f"D-{number}"
1842
+ if proposal:
1843
+ rec["proposal"] = f"P-{number}"
1844
+ try:
1845
+ with open(os.path.join(d, did + ".json"), "x", encoding=UTF8) as fh:
1846
+ json.dump(rec, fh, ensure_ascii=False, indent=2)
1847
+ break
1848
+ except FileExistsError:
1849
+ number += 1
1850
+ rec["id"] = did
1851
+ return rec
1852
+
1853
+
1854
+ class AnswerRefused(ValueError):
1855
+ """An answer a question does not take: a key it does not offer, or a second answer given as a first."""
1856
+
1857
+
1858
+ def free_text_option(option):
1859
+ """Whether a decision's option takes the answer in one's own words: flagged so, or ask's `x` labeled so.
1860
+
1861
+ ask flags the option it appends as `x`. Its label is read as well, as a marker is (LANGUAGE-OUTPUT):
1862
+ an `x` that carries the label and no flag is answered in words, whichever language labeled it. An
1863
+ option a person named so under another key stays one to choose.
1864
+ """
1865
+ return isinstance(option, dict) and (bool(option.get("free_text")) or (
1866
+ option.get("key") == "x" and option.get("label") in language.forms("free-text")))
1867
+
1868
+
1869
+ def answer(root, did, key_or_text, by="human", change=False, user=None, interactive=None):
1870
+ """Answer one question. Returns the updated record, or None if unknown.
1871
+
1872
+ The first word is the key of an option the question offers; a free-text option takes the
1873
+ words after it as the answer. Anything else raises AnswerRefused naming the options, where
1874
+ `z` to a question offering a, b and x was recorded as the answer (CLI-ROBUST), and so does a
1875
+ second answer, which silently replaced the first, unless `change` says it replaces it. Each
1876
+ answer is a row of its own under `answers` and the record's answer is the newest, so a change
1877
+ leaves what was answered before on the record.
1878
+
1879
+ A rule proposal's question is a person's to answer (RULE-PROPOSALS): an architect's decision
1880
+ (`by` architect, what `polyctl decide --answers` passes) and a turn polyctl started for either role are
1881
+ refused, since both are agents working under the rules the proposal would change.
1882
+ """
1883
+ p = os.path.join(root, DECISION_DIR, did + ".json")
1884
+ if not os.path.exists(p):
1885
+ return None
1886
+ from .storage import _exclusive_lock, replace_file_durably
1887
+ # One answer at a time: the terminal and the phone answering at once each read the record unanswered,
1888
+ # and the later write dropped the earlier answer. The record is read inside the lock, which lives
1889
+ # beside the decisions, not among them, whose listing is how a change is noticed (CLI-ROBUST-2).
1890
+ with _exclusive_lock(os.path.join(root, ".polyctl", "decisions.lock")):
1891
+ rec = json.load(open(p, encoding=UTF8))
1892
+ if rec.get("proposal"):
1893
+ agent = invoking_role() or ("architect" if by == "architect" else None)
1894
+ if agent:
1895
+ raise AnswerRefused(f"{did} asks about rule proposal {rec['proposal']}, which a person decides, not the "
1896
+ f"{agent}: polyctl answer {did} <key> in a person's terminal, or a tap on the phone")
1897
+ given = str(key_or_text).split(None, 1)
1898
+ key, words = (given[0].lower() if given else ""), (given[1].strip() if len(given) > 1 else "")
1899
+ options = [o for o in rec.get("options") or [] if isinstance(o, dict)]
1900
+ chosen = next((o for o in options if o.get("key") == key), None)
1901
+ free = next((o for o in options if free_text_option(o)), None)
1902
+ if chosen is None:
1903
+ offered = ", ".join(f"{o.get('key')}) {o.get('label')}" for o in options)
1904
+ raise AnswerRefused(f"{did} offers {offered or 'no options'}; {key!r} is not one of them")
1905
+ if free_text_option(chosen) and not words:
1906
+ raise AnswerRefused(f"{key} is answered in your own words: polyctl answer {did} {key} <text>")
1907
+ if words and not free_text_option(chosen):
1908
+ raise AnswerRefused(f"{key}) {chosen.get('label')} takes no words after it"
1909
+ + (f"; answer in your own words with {free.get('key')} <text>" if free else ""))
1910
+ if rec.get("state") == "answered" and not change:
1911
+ raise AnswerRefused(f"{did} is already answered: {rec.get('answer')}; "
1912
+ f"polyctl answer {did} <key> --change replaces it, and both stay on the record")
1913
+ row = {"answer": words if free_text_option(chosen) else chosen.get("label"), "answer_key": chosen.get("key"),
1914
+ "answered_at": int(time.time()), "answered_by": by}
1915
+ if user is not None or interactive is not None:
1916
+ # The login and the terminal, as every other act polyctl attributes to a person keeps them (RULE-PROPOSALS-2).
1917
+ row.update(answered_user=user, answered_interactive=bool(interactive))
1918
+ rows = rec.get("answers")
1919
+ if not isinstance(rows, list):
1920
+ # Answered before each answer was a row: that answer becomes the first, so a change keeps it.
1921
+ rows = [{name: rec.get(name) for name in row}] if rec.get("state") == "answered" else []
1922
+ rec.update(row, state="answered", answers=rows + [row])
1923
+ rec = scan_record(rec)
1924
+ replace_file_durably(p, json.dumps(rec, ensure_ascii=False, indent=2).encode(UTF8))
1925
+ rec["id"] = did
1926
+ return rec
1927
+
1928
+
1929
+ # ── rule proposals: an agent proposes, a person decides (RULE-PROPOSALS) ──────
1930
+
1931
+ PROPOSAL_EVIDENCE_SLICES = 10 # the project's last landed slices a proposal is measured beside
1932
+ # What a person decided, by the key of the option they chose: `ask` keys options a, b, … in the order
1933
+ # given, and `propose` offers accept, then reject. The free-text key is an answer in their own words.
1934
+ PROPOSAL_OUTCOMES = {"a": "accepted", "b": "rejected"}
1935
+
1936
+
1937
+ class ProposalRefused(ValueError):
1938
+ """A proposal polyctl does not record: it names no change, gives no reason, or names a file outside the project."""
1939
+
1940
+
1941
+ def proposal_rule_file(root, path):
1942
+ """(the rule file as a path in the project, the digest of its bytes now), or ProposalRefused.
1943
+
1944
+ A relative path is read from the project's root, as a path polyctl records is. The file must be
1945
+ the project's own: a link out of it is followed and refused, so nothing outside the project
1946
+ is read, and nothing outside it is named in a ledger the project keeps.
1947
+ """
1948
+ full = path if os.path.isabs(path) else os.path.join(root, path)
1949
+ if not _within(full, root):
1950
+ raise ProposalRefused(f"{path} is outside the project; name the rule file as a path in it")
1951
+ if not os.path.isfile(full):
1952
+ raise ProposalRefused(f"{path} is no file in the project; name the file that holds the rule")
1953
+ digest = hashlib.sha256()
1954
+ with open(full, "rb") as fh:
1955
+ for chunk in iter(lambda: fh.read(1 << 16), b""):
1956
+ digest.update(chunk)
1957
+ relative = os.path.relpath(os.path.realpath(full), os.path.realpath(root))
1958
+ return relative.replace(os.sep, "/"), "sha256:" + digest.hexdigest()
1959
+
1960
+
1961
+ def proposal_evidence(root):
1962
+ """What a proposal is judged beside: the outcomes of the project's last landed slices, as `polyctl stats` reads them.
1963
+
1964
+ Measured from the ledgers, never typed by the proposer (#49): which slices, and their rounds,
1965
+ first-pass rate, time, size and the defects found in them later. A review ledger that cannot be read
1966
+ is said so under "unread", where it was read as no slice having landed (RULE-PROPOSALS-2).
1967
+ """
1968
+ from .storage import read_chained_jsonl
1969
+ try:
1970
+ read_chained_jsonl(review_ledger_path(root), REVIEW_CHAIN)
1971
+ landed = sorted((o for o in slice_outcomes(root) if o.get("landed_at")), key=lambda o: o["landed_at"])
1972
+ except Exception as exc:
1973
+ return {"slices": [], "stats": outcome_stats([]), "unread": f"{type(exc).__name__}: {exc}"[:200]}
1974
+ recent = landed[-PROPOSAL_EVIDENCE_SLICES:]
1975
+ return {"slices": [o["slice"] for o in recent], "stats": outcome_stats(recent)}
1976
+
1977
+
1978
+ def _proposal_context(cfg, author, via, why, path, evidence):
1979
+ """What a person reads beside a proposal's question, in the project's language: who, why, the file, the evidence."""
1980
+ if author.get("role"):
1981
+ who = f"{author['actor']} ({author['role']})"
1982
+ else:
1983
+ who = language.text(cfg, "proposal.unknown", via=via)
1984
+ lines = [language.text(cfg, "proposal.by", who=who, why=why)]
1985
+ if path:
1986
+ lines.append(language.text(cfg, "proposal.rule-file", path=path))
1987
+ stats = evidence["stats"]
1988
+ if evidence.get("unread"):
1989
+ lines.append(language.text(cfg, "proposal.unread", why=evidence["unread"]))
1990
+ elif stats["slices"]:
1991
+ def shown(value):
1992
+ return "—" if value is None else value
1993
+ lines.append(language.text(cfg, "proposal.evidence", n=stats["slices"],
1994
+ reviewed=stats["slices"] - stats["waived"],
1995
+ first_pass=shown(stats["first_pass_pct"]),
1996
+ rounds=shown((stats["rounds"] or {}).get("median")),
1997
+ defects=shown(stats["defects_pct"])))
1998
+ else:
1999
+ lines.append(language.text(cfg, "proposal.no-evidence"))
2000
+ return "\n".join(lines)
2001
+
2002
+
2003
+ def _proposed_change(text, path):
2004
+ """What makes two proposals one: the change in any spacing and case, and the file it names."""
2005
+ return " ".join(str(text or "").split()).lower(), path
2006
+
2007
+
2008
+ def proposals(root):
2009
+ """Every rule proposal, oldest first, with what its question says now (RULE-PROPOSALS).
2010
+
2011
+ The proposal is its row in the decision ledger. What a person decided is its question's
2012
+ answer, recorded by the decision flow as every answer is and read from there, so the ledger
2013
+ holds no second copy of it to disagree with. `state` is open, accepted, rejected, answered
2014
+ (in the person's own words), or missing when its question's file is gone. A ledger that
2015
+ cannot be read raises, as it does for every reader: it is never read as no proposals.
2016
+ """
2017
+ asked = {rec["id"]: rec for rec in decisions(root)}
2018
+ out = []
2019
+ for row in decision_rows(root):
2020
+ if row.get("kind") != "proposal":
2021
+ continue
2022
+ question = asked.get(row.get("question"))
2023
+ if question is None:
2024
+ state = "missing"
2025
+ elif question.get("state") != "answered":
2026
+ state = "open"
2027
+ else:
2028
+ state = PROPOSAL_OUTCOMES.get(question.get("answer_key"), "answered")
2029
+ out.append(dict(row, state=state, answer=(question or {}).get("answer"),
2030
+ answered_by=(question or {}).get("answered_by"),
2031
+ answered_user=(question or {}).get("answered_user"),
2032
+ answered_interactive=(question or {}).get("answered_interactive"),
2033
+ answered_at=(question or {}).get("answered_at")))
2034
+ return out
2035
+
2036
+
2037
+ def propose(root, cfg, text, why, rule_file=None, via="cli"):
2038
+ """Record a change an agent proposes to a rule it works under, and ask a person to decide it (RULE-PROPOSALS).
2039
+
2040
+ An agent that edits its own playbook, steering or authority has rewritten the rules it is
2041
+ held to, and nobody decided it. Proposed instead, the change is a row of the decision
2042
+ ledger, chained as `polyctl decide` chains its rows: who proposed it (the role of a turn polyctl
2043
+ started, as a waived grant records its author, and `via` the CLI or MCP), the change, why,
2044
+ the file that holds the rule with the digest of its bytes then, and the outcomes of the
2045
+ project's last landed slices. Beside it goes a question a person answers through the
2046
+ decision flow, `polyctl answer` or a tap on the phone: accept, reject or their own words.
2047
+ Nothing here, and nothing an answer does, writes a rule file.
2048
+
2049
+ Returns (the proposal, its question, True), or (the open proposal of the same change, None,
2050
+ False) when that one stands: the same change proposed twice is one proposal. Raises
2051
+ ProposalRefused for a proposal with no change, no reason or a rule file outside the project.
2052
+ """
2053
+ text, why = str(text or "").strip(), str(why or "").strip()
2054
+ if not text:
2055
+ raise ProposalRefused("a proposal names the change: what the rule would say, or what would change")
2056
+ if not why:
2057
+ raise ProposalRefused("a proposal gives its reason: what went wrong under the rule as it stands")
2058
+ path, digest = proposal_rule_file(root, str(rule_file)) if rule_file else (None, None)
2059
+ made = proposals(root)
2060
+ for standing in made:
2061
+ if standing["state"] == "open" and _proposed_change(standing.get("text"), standing.get("rule_file")) \
2062
+ == _proposed_change(text, path):
2063
+ return standing, None, False
2064
+ author = grant_author(cfg)
2065
+ evidence = proposal_evidence(root)
2066
+ # Numbered past every proposal the ledger holds, so none takes the id of one whose question file is gone.
2067
+ taken = [int(p["id"][2:]) for p in made if str(p.get("id") or "")[:2] == "P-" and p["id"][2:].isdigit()]
2068
+ question = ask(root, language.text(cfg, "proposal.question", text=text),
2069
+ [language.text(cfg, "proposal.accept"), language.text(cfg, "proposal.reject")],
2070
+ context=_proposal_context(cfg, author, via, why, path, evidence), cfg=cfg, proposal=True,
2071
+ after=max(taken, default=0))
2072
+ row = scan_record({"id": question["proposal"], "at": question["asked_at"], "kind": "proposal", "text": text,
2073
+ "why": why, "rule_file": path, "rule_digest": digest, "question": question["id"],
2074
+ "by": author, "via": via, "evidence": evidence})
2075
+ from .storage import append_chained_jsonl
2076
+ try:
2077
+ append_chained_jsonl(decisions_path(root), row, DECISION_CHAIN, legacy_prefix=True)
2078
+ except BaseException:
2079
+ # A question the ledger holds no proposal for would be answered for nothing: it is taken back.
2080
+ try:
2081
+ os.remove(os.path.join(root, DECISION_DIR, question["id"] + ".json"))
2082
+ except OSError:
2083
+ pass
2084
+ raise
2085
+ return dict(row, state="open", answer=None, answered_by=None, answered_at=None), question, True
2086
+
2087
+
2088
+ def last_nudge_error(root, parked=True):
2089
+ """The most recent failed nudge, if the watchdog recorded one.
2090
+
2091
+ `parked=False` leaves out a failure while the implementer's slice is parked on its usage limit,
2092
+ and one no newer than the stop a park has ended for: the park's own alarm tells a person, and an
2093
+ architect woken to judge it spends a window on a condition that waits on a clock (QUOTA-PARK).
2094
+ """
2095
+ try:
2096
+ st = json.load(open(project_file(root, "watchdog-state", key=next_project_key(root)), encoding=UTF8))
2097
+ except Exception:
2098
+ return None
2099
+ err = st.get("last_error")
2100
+ if not parked and isinstance(err, dict) and (isinstance(st.get("quota_park"), dict)
2101
+ or float(st.get("quota_resumed") or 0) >= (err.get("at") or 0)):
2102
+ return None
2103
+ return err
2104
+
2105
+
2106
+ def recent_errors(recs, limit=3, adapter=None):
2107
+ """Tool calls the agent itself marked as failed.
2108
+
2109
+ Use the structural verdict the store already carries — Kiro records
2110
+ `success: true|false` on every tool_result — never a text search. Matching on
2111
+ words like "failed" surfaces the agent's own search patterns and passing test
2112
+ names, which is worse than showing nothing: a panel that cries wolf gets
2113
+ ignored exactly when it is right.
2114
+
2115
+ The record, the verdict field, the value that means failed and where the output
2116
+ is are the adapter's `telemetry.failure`; asked without an adapter, the
2117
+ implementer's adapter declares them.
2118
+
2119
+ A subagent's failed calls are not read (`transcript.subagents`). They are steps the
2120
+ subagent recovers from inside - nearly every subagent that failed a call still returned
2121
+ a result - and what the implementer is told is how the subagent ended, in its own
2122
+ transcript: the result of the call that waited for it, read here when it failed, or the
2123
+ notification of its end. Read beside the implementer's own failures, the subagents'
2124
+ would crowd them out of the panel's two lines.
2125
+
2126
+ A task the implementer ran in the background - a subagent, a command - ends after the call
2127
+ that started it returned, and the session is told in a record of its own: an end whose
2128
+ status the adapter declares a failure (`telemetry.failure.ends`) is read here as its failed
2129
+ result would be, once however many times the session was told of it.
2130
+ """
2131
+ shape = transcript_shape(implementer_adapter() if adapter is None else adapter)
2132
+ failure = shape["failure"]
2133
+ if not failure and not shape["ends"]:
2134
+ return []
2135
+ out, told = [], set()
2136
+ for r in reversed(recs):
2137
+ raws = []
2138
+ for task, text in failed_ends(r, shape):
2139
+ if task not in told:
2140
+ told.add(task)
2141
+ raws.append(text)
2142
+ pl = record_body(r, shape)
2143
+ if failure and pl is not None and record_kind(r, shape) == failure["type"]:
2144
+ failed = [item for item in declared_items(pl, failure)
2145
+ if _declared_value(_path_value(item, failure["field"]), failure["failed_when"])]
2146
+ # Results nested in a message are each a call that failed, its verdict and output the block's;
2147
+ # read newest first, as the records are.
2148
+ raws.extend(str(_path_value(item, failure["text"]) or "") if failure["text"] else ""
2149
+ for item in reversed(failed))
2150
+ for raw in raws:
2151
+ # Failed tool output is usually a wall of passing lines with the real
2152
+ # cause buried in it. Lead with the line that actually failed.
2153
+ lines = [ln.strip() for ln in raw.split("\n") if ln.strip()]
2154
+ def is_signal(ln):
2155
+ low = ln.lower()
2156
+ if ln.startswith("✔") or low.startswith("output:"):
2157
+ return False
2158
+ return (ln.startswith("✖") or "error ts" in low or "error:" in low
2159
+ or low.startswith("fail") or " failing tests" in low
2160
+ or "exit code: 1" in low or low.startswith("✗"))
2161
+ signal = next((ln for ln in lines if is_signal(ln)), None)
2162
+ if not signal:
2163
+ signal = next((ln for ln in lines if not ln.lower().startswith("output:")
2164
+ and not ln.startswith("✔")), lines[0] if lines else raw)
2165
+ text = " ".join(str(signal)[:260].split())
2166
+ out.append((local_hhmm(record_time(r, shape)) or "--:--", text))
2167
+ if len(out) >= limit:
2168
+ break
2169
+ if raws and len(out) >= limit:
2170
+ break
2171
+ return list(reversed(out))
2172
+
2173
+
2174
+ # ── repository signals ────────────────────────────────────────────────────────
2175
+
2176
+ def _review_verdict(body):
2177
+ """Return one explicit top-level verdict value, otherwise INVALID."""
2178
+ from .verdicts import VERDICTS
2179
+ allowed = set(VERDICTS)
2180
+ values = []
2181
+ malformed = False
2182
+ for line in str(body or "").splitlines():
2183
+ if line.startswith((" ", "\t")):
2184
+ continue
2185
+ if not re.match(r"^(?:\*\*)?verdict\b", line, re.I):
2186
+ continue
2187
+ prefix = re.match(
2188
+ r"^(?:\*\*verdict[ \t]*:\*\*|verdict[ \t]*:)", line, re.I
2189
+ )
2190
+ if not prefix:
2191
+ malformed = True
2192
+ continue
2193
+ value = line[prefix.end():].strip(" \t")
2194
+ if value.startswith("**") and value.endswith("**") and len(value) >= 4:
2195
+ value = value[2:-2].strip(" \t")
2196
+ if not re.fullmatch(r"[A-Za-z_]+", value or ""):
2197
+ malformed = True
2198
+ continue
2199
+ value = value.upper()
2200
+ if value not in allowed:
2201
+ malformed = True
2202
+ continue
2203
+ if value not in values:
2204
+ values.append(value)
2205
+ return values[0] if not malformed and len(values) == 1 else "INVALID"
2206
+
2207
+
2208
+ def _has_verdict_marker(body):
2209
+ """Whether output contains any verdict-like marker; authority stays stricter."""
2210
+ return bool(re.search(r"\bverdict\b", str(body or ""), re.I))
2211
+
2212
+
2213
+ def reviews(root, reviews_dir, limit=4):
2214
+ d = os.path.join(root, reviews_dir)
2215
+ if not os.path.isdir(d):
2216
+ return []
2217
+ # Review artefacts only. `polyctl init` leaves semantic-review/.gitkeep, and as the
2218
+ # newest file it was reported as an INVALID review and written into every
2219
+ # verification record as the review the tree had been measured against.
2220
+ # One removed after it was listed - a prune running beside the reader - is not
2221
+ # one: its time was read for the order, and `polyctl cost` ended on it (LEADS-OPS).
2222
+ dated = []
2223
+ for f in os.listdir(d):
2224
+ if f.startswith(".") or not os.path.isfile(os.path.join(d, f)):
2225
+ continue
2226
+ try:
2227
+ dated.append((os.path.getmtime(os.path.join(d, f)), f))
2228
+ except OSError:
2229
+ continue
2230
+ files = [f for _, f in sorted(dated, key=lambda pair: pair[0], reverse=True)[:limit]]
2231
+ out = []
2232
+ for f in files:
2233
+ verdict = "INVALID"
2234
+ try:
2235
+ body = open(os.path.join(d, f), errors="ignore", encoding=UTF8).read()
2236
+ verdict = _review_verdict(body)
2237
+ evidence = review_evidence(body)
2238
+ # polyctl records the verdict it adjudicated in the evidence line too; a
2239
+ # margin verdict that disagrees was changed after polyctl wrote it (#60).
2240
+ if isinstance(evidence, dict) and "verdict" in evidence \
2241
+ and evidence["verdict"] != verdict:
2242
+ verdict = "INVALID"
2243
+ # Preserve legacy one-line quota/auth artifacts written before reviews
2244
+ # carried evidence. An artefact with an evidence line records how the
2245
+ # reviewer's process ended as its verdict line, so words in it — a
2246
+ # finding about authentication or a rate limit — never decide it (#57).
2247
+ has_verdict_line = _has_verdict_marker(body)
2248
+ if verdict == "INVALID" and not has_verdict_line \
2249
+ and evidence is None \
2250
+ and REVIEW_UNAVAILABLE_RE.search(body):
2251
+ verdict = "UNAVAILABLE"
2252
+ except Exception:
2253
+ pass
2254
+ out.append((f, verdict))
2255
+ return out
2256
+
2257
+
2258
+ REVIEW_UNAVAILABLE_RE = re.compile(
2259
+ r"hit your (?:session|usage|weekly|monthly) limit|usage limit|rate limit|"
2260
+ r"out of (?:credits|quota)|API Error: (?:401|403|429|5\d\d)|"
2261
+ r"Not logged in|login required|authentication", re.I)
2262
+
2263
+
2264
+ def reviewer_state_path(root):
2265
+ return project_file(root, "reviewer")
2266
+
2267
+
2268
+ def reviewer_state(root):
2269
+ try:
2270
+ return json.load(open(reviewer_state_path(root), encoding=UTF8))
2271
+ except (OSError, ValueError):
2272
+ return {}
2273
+
2274
+
2275
+ def set_reviewer_state(root, **fields):
2276
+ st = reviewer_state(root)
2277
+ st.update(fields)
2278
+ try:
2279
+ os.makedirs(os.path.dirname(reviewer_state_path(root)), exist_ok=True)
2280
+ json.dump(st, open(reviewer_state_path(root), "w", encoding=UTF8))
2281
+ except OSError:
2282
+ pass
2283
+ return st
2284
+
2285
+
2286
+ def _edge_ids(item, field):
2287
+ """Board ids a note names; a parenthesised remark is not one, however many words it has.
2288
+
2289
+ Only a word that began with `(` was dropped, so `needs: A (see ticket 12)` needed `ticket` and `12)`
2290
+ and was never READY (READY-GRAPH-2). An unclosed remark runs to the end of the note.
2291
+ """
2292
+ text = re.sub(r"\([^)]*(?:\)|$)", " ", item["notes"].get(field, ""))
2293
+ return [token for token in re.split(r"[,\s]+", text) if token]
2294
+
2295
+
2296
+ def board_graph(root, data=None):
2297
+ """READY, derived from the board's dependency edges, and what is wrong with them (#33).
2298
+
2299
+ A dependency graph, not a handoff mechanism. The valuable part of "backend
2300
+ done, now the frontend" is that the second item becomes eligible the moment
2301
+ the first lands, and putting the edge on the board keeps the implementer from
2302
+ choosing its own scope, the one authority it must not hold.
2303
+
2304
+ `needs: B3, B4` on a queued item names the board items it waits for;
2305
+ `unlocks:` on any item is the same edge written from the other end. `needs:`
2306
+ on a blocked item stays its reason in words. On 2026-09-07 the architect
2307
+ decided what was actionable by reading the board as prose, and a dependency
2308
+ named there was never checked against anything. So an id that is not on the
2309
+ board, an id listed twice and a cycle are problems naming both ends, never a
2310
+ silent skip, and no item they touch is READY; neither is one `waiting:` on
2311
+ someone. READY is derived here and nowhere else: a hand-written `## ready`
2312
+ section is a problem too.
2313
+
2314
+ `data` is the board's bytes as one reading took them (BoardEdit), so a move is decided on the board it is
2315
+ made on (SLICE-LIFECYCLE-2).
2316
+
2317
+ Returns {"ready": [item with its role], "problems": [text]}.
2318
+ """
2319
+ b = board(root, data)
2320
+ # What a problem touches is not READY: an id listed twice and an item that unlocks what is not on the
2321
+ # board were named and still returned READY (READY-GRAPH-2).
2322
+ problems, where, broken = [], {}, set()
2323
+ for state in BOARD_STATES:
2324
+ for item in b[state]:
2325
+ if item["id"] in where:
2326
+ problems.append(f"{item['id']} is on the board twice, under {where[item['id']]} and {state}")
2327
+ broken.add(item["id"])
2328
+ where.setdefault(item["id"], state)
2329
+ try:
2330
+ if data is None:
2331
+ with open(os.path.join(root, ".polyctl", "board.md"), encoding=UTF8, errors="replace") as fh:
2332
+ lines = fh.readlines()
2333
+ else:
2334
+ import io
2335
+ lines = io.TextIOWrapper(io.BytesIO(data), encoding=UTF8, errors="replace").readlines()
2336
+ if any(re.match(r"^\s*##\s+ready\s*$", line, re.I) for line in lines):
2337
+ problems.append("the board has a hand-written READY section; READY is derived from `needs:`, "
2338
+ "so its items belong under `## queued`")
2339
+ except OSError:
2340
+ pass
2341
+ edges = {item["id"]: set(_edge_ids(item, "needs")) for item in b["queued"]}
2342
+ for state in BOARD_STATES:
2343
+ for item in b[state]:
2344
+ for target in _edge_ids(item, "unlocks"):
2345
+ if target not in where:
2346
+ problems.append(f"{item['id']} unlocks {target}, which is not on the board")
2347
+ broken.add(item["id"])
2348
+ else:
2349
+ edges.setdefault(target, set()).add(item["id"])
2350
+ for item_id in sorted(edges):
2351
+ for dep in sorted(edges[item_id]):
2352
+ if dep not in where:
2353
+ problems.append(f"{item_id} needs {dep}, which is not on the board")
2354
+ broken.add(item_id)
2355
+ colour, trail, cycles = {}, [], set()
2356
+
2357
+ def visit(node):
2358
+ colour[node] = "open"
2359
+ trail.append(node)
2360
+ for dep in sorted(edges.get(node, ())):
2361
+ if colour.get(dep) == "open":
2362
+ cycle = trail[trail.index(dep):]
2363
+ if frozenset(cycle) not in cycles:
2364
+ cycles.add(frozenset(cycle))
2365
+ problems.append("a cycle: " + ", ".join(
2366
+ f"{first} needs {then}" for first, then in zip(cycle, cycle[1:] + [dep])))
2367
+ broken.update(cycle)
2368
+ elif dep not in colour and dep in edges:
2369
+ visit(dep)
2370
+ trail.pop()
2371
+ colour[node] = "closed"
2372
+
2373
+ for node in sorted(edges):
2374
+ if node not in colour:
2375
+ visit(node)
2376
+ # A duplicate's done copy cannot satisfy another item's dependency (TRIAGE-3-LOW).
2377
+ done = {item["id"] for state in ("done", "verified") for item in b[state]} - broken
2378
+ ready_items = [{**item, "role": item["notes"].get("role", "")} for item in b["queued"]
2379
+ if item["id"] not in broken and "waiting" not in item["notes"]
2380
+ and all(dep in done for dep in edges.get(item["id"], ()))]
2381
+ return {"ready": ready_items, "problems": problems}
2382
+
2383
+
2384
+ def ready(root):
2385
+ """Queued items whose dependencies are all done and which wait on no one (#33)."""
2386
+ return board_graph(root)["ready"]
2387
+
2388
+
2389
+ def review_loop(root, reviews_dir, min_repeats=3):
2390
+ """The same finding coming back review after review.
2391
+
2392
+ A round budget counts rounds. It cannot see that round four's blocker is
2393
+ round two's blocker with the line numbers moved — which is the actual
2394
+ failure: the implementer is not converging, and more rounds will not help.
2395
+ Fingerprint each finding on its file and its first clause, and report any
2396
+ that recurs across consecutive NEEDS_CHANGES reviews.
2397
+ """
2398
+ seen = {}
2399
+ d = os.path.join(root, reviews_dir)
2400
+ for f, v in reviews(root, reviews_dir, limit=12):
2401
+ if "APPROVED" in (v or "").upper():
2402
+ break
2403
+ try:
2404
+ body = open(os.path.join(d, f), errors="replace", encoding=UTF8).read()
2405
+ except OSError:
2406
+ continue
2407
+ # Findings sit in the reviewer's verbatim block, indented (#54).
2408
+ for m in re.finditer(r"^(?: )?- \[(BLOCKER|HIGH|MEDIUM|LOW)\]\s*([^\s:]+)[:\d]*\s*[—-]\s*(.{0,60})",
2409
+ body, re.M):
2410
+ key = (m.group(2), re.sub(r"\W+", " ", m.group(3).lower()).strip()[:40])
2411
+ seen.setdefault(key, {"sev": m.group(1), "count": 0, "reviews": []})
2412
+ seen[key]["count"] += 1
2413
+ seen[key]["reviews"].append(f)
2414
+ return [{"file": k[0], "clause": k[1], **v}
2415
+ for k, v in seen.items() if v["count"] >= min_repeats]