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.
- polyctl/__init__.py +7 -0
- polyctl/__main__.py +5 -0
- polyctl/a2a.py +226 -0
- polyctl/a2a_mcp.py +546 -0
- polyctl/acp.py +417 -0
- polyctl/adapters/README.md +101 -0
- polyctl/adapters/aider.json +32 -0
- polyctl/adapters/amazon-q.json +15 -0
- polyctl/adapters/amp.json +16 -0
- polyctl/adapters/antigravity.json +120 -0
- polyctl/adapters/claude-code.json +229 -0
- polyctl/adapters/cloud-generic.json +57 -0
- polyctl/adapters/codex.json +47 -0
- polyctl/adapters/command-code.json +45 -0
- polyctl/adapters/copilot.json +17 -0
- polyctl/adapters/cursor-agent.json +29 -0
- polyctl/adapters/deepseek.json +13 -0
- polyctl/adapters/droid.json +34 -0
- polyctl/adapters/gemini.json +30 -0
- polyctl/adapters/grok.json +22 -0
- polyctl/adapters/hermes.json +34 -0
- polyctl/adapters/kilocode.json +30 -0
- polyctl/adapters/kimi.json +23 -0
- polyctl/adapters/kiro.json +332 -0
- polyctl/adapters/ollama.json +29 -0
- polyctl/adapters/omp.json +34 -0
- polyctl/adapters/openai-api.json +68 -0
- polyctl/adapters/opencode.json +162 -0
- polyctl/adapters/pi.json +24 -0
- polyctl/adapters/pr-agent.json +54 -0
- polyctl/adapters/profiles.json +9 -0
- polyctl/adapters/qoder.json +163 -0
- polyctl/adapters/qwen.json +27 -0
- polyctl/adapters/reasonix.json +25 -0
- polyctl/adapters/rewriters/rtk.json +24 -0
- polyctl/adapters/trae.json +31 -0
- polyctl/adapters/vendors.json +42 -0
- polyctl/adapters/warp.json +88 -0
- polyctl/allowlist.py +1756 -0
- polyctl/api_review.py +920 -0
- polyctl/cli.py +835 -0
- polyctl/conformance_harness.py +9 -0
- polyctl/demo.py +503 -0
- polyctl/drivers.py +146 -0
- polyctl/email.py +160 -0
- polyctl/features.py +98 -0
- polyctl/journal.py +144 -0
- polyctl/language.py +945 -0
- polyctl/lib.py +1296 -0
- polyctl/matrix.py +660 -0
- polyctl/mcp.py +1362 -0
- polyctl/ntfy.py +169 -0
- polyctl/outbound.py +39 -0
- polyctl/parts/__init__.py +5 -0
- polyctl/parts/cli_authority.py +2615 -0
- polyctl/parts/cli_channels.py +1325 -0
- polyctl/parts/cli_checks.py +2293 -0
- polyctl/parts/cli_completion.py +686 -0
- polyctl/parts/cli_evidence.py +141 -0
- polyctl/parts/cli_gain.py +375 -0
- polyctl/parts/cli_harness.py +392 -0
- polyctl/parts/cli_hooks.py +1816 -0
- polyctl/parts/cli_install.py +638 -0
- polyctl/parts/cli_lanes.py +106 -0
- polyctl/parts/cli_maintenance.py +2536 -0
- polyctl/parts/cli_next.py +248 -0
- polyctl/parts/cli_pr.py +53 -0
- polyctl/parts/cli_project.py +2857 -0
- polyctl/parts/cli_review.py +5158 -0
- polyctl/parts/cli_status.py +898 -0
- polyctl/parts/lib_adapters.py +2933 -0
- polyctl/parts/lib_alarms.py +2106 -0
- polyctl/parts/lib_events.py +224 -0
- polyctl/parts/lib_evidence.py +412 -0
- polyctl/parts/lib_gates.py +2099 -0
- polyctl/parts/lib_lanes.py +829 -0
- polyctl/parts/lib_mail.py +1541 -0
- polyctl/parts/lib_next.py +652 -0
- polyctl/parts/lib_pr.py +331 -0
- polyctl/parts/lib_slices.py +3337 -0
- polyctl/parts/lib_state.py +2415 -0
- polyctl/parts/lib_transcript.py +4118 -0
- polyctl/pressure.py +325 -0
- polyctl/prices.json +47 -0
- polyctl/procs.py +1194 -0
- polyctl/settings.py +505 -0
- polyctl/skill/SKILL.md +365 -0
- polyctl/skillkit.py +503 -0
- polyctl/storage.py +2055 -0
- polyctl/telegram.py +327 -0
- polyctl/tiers.py +123 -0
- polyctl/verdicts.py +41 -0
- polyctl/watchdog.py +3887 -0
- polyctl/web.py +337 -0
- polyctl-0.7.0.dist-info/METADATA +235 -0
- polyctl-0.7.0.dist-info/RECORD +99 -0
- polyctl-0.7.0.dist-info/WHEEL +4 -0
- polyctl-0.7.0.dist-info/entry_points.txt +5 -0
- 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]
|