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,2106 @@
|
|
|
1
|
+
"""Alarms and records: alarms, project keys, review scope, helpers, costs, deferrals, waivers,
|
|
2
|
+
credits, pings, locks.
|
|
3
|
+
|
|
4
|
+
A part of src/polyctl/lib.py (#44): moved out byte for byte and run in its namespace by `_part`,
|
|
5
|
+
where it stood; it is not importable on its own.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
# ---- alarms -------------------------------------------------------------------
|
|
10
|
+
#
|
|
11
|
+
# Three levels, named by who acts: yellow is the architect's (an anomaly and a
|
|
12
|
+
# wake), orange is the human's (desktop + Telegram), red is the human's *now*
|
|
13
|
+
# (e-mail). The ladder is what turns a standing orange into a red: on 2026-09-05
|
|
14
|
+
# every alert went to a notification centre nobody looked at for eleven hours.
|
|
15
|
+
|
|
16
|
+
# The defaults, from the settings registry (#74); the functions below read the values in force.
|
|
17
|
+
ALARM_RED_AFTER = settings.default("alarms.red_after_minutes") * 60
|
|
18
|
+
ALARM_RED_REPEAT = settings.default("alarms.red_repeat_hours") * 3600
|
|
19
|
+
ALARM_RESET_AFTER = settings.default("alarms.reset_after_hours") * 3600
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def _alarm_reset_after():
|
|
23
|
+
return settings.get(None, "alarms.reset_after_hours") * 3600
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def alarms_path():
|
|
27
|
+
return os.path.join(HOME, ".polyctl", "alarms.json")
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def load_alarms():
|
|
31
|
+
try:
|
|
32
|
+
return json.load(open(alarms_path(), encoding=UTF8))
|
|
33
|
+
except (OSError, ValueError):
|
|
34
|
+
return {}
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def save_alarms(d):
|
|
38
|
+
"""Write the episodes whole: written over in place, a write cut off left a file that read as none (JOURNAL-7)."""
|
|
39
|
+
from .storage import replace_file_durably
|
|
40
|
+
try:
|
|
41
|
+
os.makedirs(os.path.dirname(alarms_path()), exist_ok=True)
|
|
42
|
+
replace_file_durably(alarms_path(), json.dumps(d, indent=1).encode(UTF8))
|
|
43
|
+
except OSError:
|
|
44
|
+
pass
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def _alarm_store_locked(when_busy):
|
|
48
|
+
"""Run one read-modify-write of the alarm files under their lock (JOURNAL-7).
|
|
49
|
+
|
|
50
|
+
Every project's watchdog, its doctor and `polyctl alarms` share ~/.polyctl/alarms.json, and each read
|
|
51
|
+
the file, changed it and wrote it back: two at once lost one's change. A change holds the lock
|
|
52
|
+
for about a millisecond; one that cannot have it in ten seconds stands behind a stalled writer,
|
|
53
|
+
whose stale copy would overwrite whatever was written past it. Nothing is written without the
|
|
54
|
+
lock: `when_busy(change, *args, **kwargs)` is what the caller gets instead, and None raises.
|
|
55
|
+
|
|
56
|
+
What is not written is not kept: a raise is recorded by the next raise and an expiry by the next
|
|
57
|
+
cycle, but a mark that a notice went is lost, and the next raise may send that notice again
|
|
58
|
+
(JOURNAL-7-3).
|
|
59
|
+
"""
|
|
60
|
+
import contextlib
|
|
61
|
+
import functools
|
|
62
|
+
|
|
63
|
+
def wrap(change):
|
|
64
|
+
@functools.wraps(change)
|
|
65
|
+
def locked(*args, **kwargs):
|
|
66
|
+
from .storage import LedgerLockTimeout, _exclusive_lock
|
|
67
|
+
held = contextlib.ExitStack()
|
|
68
|
+
try:
|
|
69
|
+
held.enter_context(_exclusive_lock(alarms_path() + ".lock", timeout=10))
|
|
70
|
+
except LedgerLockTimeout:
|
|
71
|
+
if when_busy is None:
|
|
72
|
+
raise
|
|
73
|
+
print(f"polyctl: the alarm store was held past ten seconds; {change.__name__} was not written, and "
|
|
74
|
+
"the next cycle reckons from the store as it stands", file=sys.stderr)
|
|
75
|
+
return when_busy(change, *args, **kwargs)
|
|
76
|
+
with held:
|
|
77
|
+
return change(*args, **kwargs)
|
|
78
|
+
return locked
|
|
79
|
+
return wrap
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
def _as_preview(change, *args, **kwargs):
|
|
83
|
+
"""A raise reckoned from the episodes as they stand and not written: the notice still goes (JOURNAL-7).
|
|
84
|
+
|
|
85
|
+
Until the next raise records it, a mark made for a new episode has no episode to go on, and is lost as a
|
|
86
|
+
busy one is (JOURNAL-7-3).
|
|
87
|
+
"""
|
|
88
|
+
return change(*args, **dict(kwargs, persist=False))
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def _not_kept(change, *args, **kwargs):
|
|
92
|
+
"""A mark that a notice went - mailed, rang, named - is not written and not kept (JOURNAL-7-3).
|
|
93
|
+
|
|
94
|
+
The next raise finds the episode untold and may tell it again: a red is mailed at the next cycle, a ring
|
|
95
|
+
goes again once its window has passed, a red a resume notice named is mailed at its next raise. Told
|
|
96
|
+
twice is the price of never writing blind.
|
|
97
|
+
"""
|
|
98
|
+
return None
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def _none_expired(change, *args, **kwargs):
|
|
102
|
+
return []
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
def alarm_snoozes_path():
|
|
106
|
+
return os.path.join(HOME, ".polyctl", "alarm-snoozes.json")
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
def load_alarm_snoozes():
|
|
110
|
+
try:
|
|
111
|
+
return json.load(open(alarm_snoozes_path(), encoding=UTF8))
|
|
112
|
+
except (OSError, ValueError):
|
|
113
|
+
return {}
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
def _save_alarm_snoozes(d):
|
|
117
|
+
from .storage import replace_file_durably
|
|
118
|
+
os.makedirs(os.path.dirname(alarm_snoozes_path()), exist_ok=True)
|
|
119
|
+
replace_file_durably(alarm_snoozes_path(), json.dumps(d, indent=1).encode(UTF8))
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
@_alarm_store_locked(None)
|
|
123
|
+
def alarm_snooze(project, key, until, by="human", why=""):
|
|
124
|
+
"""Keep one alarm off the human channels until a date; it stays on the record.
|
|
125
|
+
|
|
126
|
+
A snooze is for a condition that is real, known and waiting on someone. The
|
|
127
|
+
doctor check once reported a project's legacy commit hook, whose fix only the
|
|
128
|
+
owner could make, and not before a date already set; left alone it would ring
|
|
129
|
+
red and mail every six hours about something nobody could act on yet. The
|
|
130
|
+
snooze names who set it and why, and it ends by itself on the date.
|
|
131
|
+
"""
|
|
132
|
+
d = load_alarm_snoozes()
|
|
133
|
+
d[f"{project}:{key}"] = {"until": int(until), "by": by, "why": why, "at": int(time.time())}
|
|
134
|
+
_save_alarm_snoozes(d)
|
|
135
|
+
return d[f"{project}:{key}"]
|
|
136
|
+
|
|
137
|
+
|
|
138
|
+
@_alarm_store_locked(None)
|
|
139
|
+
def alarm_unsnooze(project, key):
|
|
140
|
+
d = load_alarm_snoozes()
|
|
141
|
+
gone = d.pop(f"{project}:{key}", None)
|
|
142
|
+
if gone is not None:
|
|
143
|
+
_save_alarm_snoozes(d)
|
|
144
|
+
return gone
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
def alarm_snoozed(project, key, now=None):
|
|
148
|
+
"""The snooze standing for this alarm, or None; an expired snooze is no snooze."""
|
|
149
|
+
entry = load_alarm_snoozes().get(f"{project}:{key}")
|
|
150
|
+
if isinstance(entry, dict) and float(entry.get("until") or 0) > (now or time.time()):
|
|
151
|
+
return entry
|
|
152
|
+
return None
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
@_alarm_store_locked(_as_preview)
|
|
156
|
+
def alarm_touch(project, key, level, now=None, red_after=ALARM_RED_AFTER, title=None,
|
|
157
|
+
persist=True, quiet_until=None, evidence=None, what=None):
|
|
158
|
+
"""Calculate a raise of `key` at `level`; return (level to ring at, episode).
|
|
159
|
+
|
|
160
|
+
An orange raised repeatedly for `red_after` seconds rings red. `red_due` on
|
|
161
|
+
the episode says whether a mail should go now (once per ALARM_RED_REPEAT).
|
|
162
|
+
``persist=False`` runs the identical calculation against the current ledger
|
|
163
|
+
without writing it, so watchdog explain can preview the live verdict safely.
|
|
164
|
+
|
|
165
|
+
`what` names what the raise says, when its caller can. The episode keeps what it
|
|
166
|
+
last told (`told_what`); a raise that says something else is `news` on the returned
|
|
167
|
+
episode, and news is mailed at once when the episode is red, past the repeat and
|
|
168
|
+
past a known end: a projection told on Monday does not hold back the day the credits
|
|
169
|
+
actually run out (NOTICE-NOISE).
|
|
170
|
+
"""
|
|
171
|
+
now = now or time.time()
|
|
172
|
+
d = load_alarms()
|
|
173
|
+
k = f"{project}:{key}"
|
|
174
|
+
e = d.get(k) or {}
|
|
175
|
+
if e and now - e.get("last", 0) > _alarm_reset_after():
|
|
176
|
+
e = {}
|
|
177
|
+
e.setdefault("first", now)
|
|
178
|
+
e["last"] = now
|
|
179
|
+
e["level"] = level
|
|
180
|
+
e["count"] = e.get("count", 0) + 1
|
|
181
|
+
if title:
|
|
182
|
+
e["title"] = title
|
|
183
|
+
if quiet_until:
|
|
184
|
+
e["quiet_until"] = float(quiet_until)
|
|
185
|
+
else:
|
|
186
|
+
# Each raise's own end is the only one that holds: a reading that names none - another account's,
|
|
187
|
+
# after keyflip moved to it - was held until the reset of the one before (NOTICE-NOISE-2).
|
|
188
|
+
e.pop("quiet_until", None)
|
|
189
|
+
if evidence:
|
|
190
|
+
e["evidence"] = evidence # the ladder shows what the notice was raised on (#37)
|
|
191
|
+
news = what is not None and e.get("told_what") is not None and e["told_what"] != what
|
|
192
|
+
if what is not None and e.get("told_what") is None \
|
|
193
|
+
and any(e.get(field) is not None for field in ("rang_at", "red_sent", "named_at")):
|
|
194
|
+
e["told_what"] = what # told by a raise that named nothing, a resume notice's: this is what it told
|
|
195
|
+
ring = level
|
|
196
|
+
e["red_due"] = False
|
|
197
|
+
if level == "red" or (level == "orange" and now - e["first"] >= red_after):
|
|
198
|
+
ring = "red"
|
|
199
|
+
# A red a resume notice named is told from then, as a mailed one is from its mail (RESUME-QUIET).
|
|
200
|
+
told = e.get("red_sent") if e.get("red_sent") is not None else e.get("named_at")
|
|
201
|
+
e["red_due"] = told is None or news or now - told >= settings.get(None, "alarms.red_repeat_hours") * 3600
|
|
202
|
+
# A standing red with a known end is mailed once, then held until that end (#40).
|
|
203
|
+
if told is not None and not news and now < float(e.get("quiet_until") or 0):
|
|
204
|
+
e["red_due"] = False
|
|
205
|
+
e["ring"] = ring
|
|
206
|
+
d[k] = e
|
|
207
|
+
if persist:
|
|
208
|
+
save_alarms(d)
|
|
209
|
+
return ring, dict(e, news=news)
|
|
210
|
+
|
|
211
|
+
|
|
212
|
+
@_alarm_store_locked(_not_kept)
|
|
213
|
+
def alarm_mailed(project, key, now=None, what=None):
|
|
214
|
+
d = load_alarms()
|
|
215
|
+
k = f"{project}:{key}"
|
|
216
|
+
if k in d:
|
|
217
|
+
d[k]["red_sent"] = now or time.time()
|
|
218
|
+
d[k]["red_due"] = False
|
|
219
|
+
if what is not None:
|
|
220
|
+
d[k]["told_what"] = what
|
|
221
|
+
save_alarms(d)
|
|
222
|
+
|
|
223
|
+
|
|
224
|
+
@_alarm_store_locked(_not_kept)
|
|
225
|
+
def alarm_rang(project, key, now=None, what=None):
|
|
226
|
+
"""Record that the orange channels told this episode, and what they told (NOTICE-NOISE).
|
|
227
|
+
|
|
228
|
+
A condition raised with a `what` rings those channels once for what it says: the
|
|
229
|
+
raises after this record and do not ring again until they say something else, and
|
|
230
|
+
red's mail keeps its own schedule. A resume notice that named an episode rang it too.
|
|
231
|
+
"""
|
|
232
|
+
d = load_alarms()
|
|
233
|
+
k = f"{project}:{key}"
|
|
234
|
+
if k in d:
|
|
235
|
+
d[k]["rang_at"] = now or time.time()
|
|
236
|
+
if what is not None:
|
|
237
|
+
d[k]["told_what"] = what
|
|
238
|
+
save_alarms(d)
|
|
239
|
+
|
|
240
|
+
|
|
241
|
+
@_alarm_store_locked(_not_kept)
|
|
242
|
+
def alarm_named(project, key, now=None):
|
|
243
|
+
"""Record that a resume notice named a red episode instead of mailing it (RESUME-QUIET).
|
|
244
|
+
|
|
245
|
+
Its repeat counts from here, as a mailed red's counts from its mail, so the notice that
|
|
246
|
+
has just named it is not followed by a mail about the same thing at the next raise.
|
|
247
|
+
"""
|
|
248
|
+
d = load_alarms()
|
|
249
|
+
k = f"{project}:{key}"
|
|
250
|
+
if k in d:
|
|
251
|
+
d[k]["named_at"] = now or time.time()
|
|
252
|
+
d[k]["red_due"] = False
|
|
253
|
+
save_alarms(d)
|
|
254
|
+
|
|
255
|
+
|
|
256
|
+
def active_alarms(project=None, now=None):
|
|
257
|
+
now = now or time.time()
|
|
258
|
+
out = []
|
|
259
|
+
for k, e in load_alarms().items():
|
|
260
|
+
proj, _, key = k.partition(":")
|
|
261
|
+
if project and proj != project:
|
|
262
|
+
continue
|
|
263
|
+
if now - e.get("last", 0) > _alarm_reset_after():
|
|
264
|
+
continue
|
|
265
|
+
out.append(dict(e, project=proj, key=key, age_s=int(now - e.get("first", now))))
|
|
266
|
+
return sorted(out, key=lambda e: -e["age_s"])
|
|
267
|
+
|
|
268
|
+
|
|
269
|
+
# ---- heartbeat ------------------------------------------------------------------
|
|
270
|
+
|
|
271
|
+
# ---- one name for what a project keeps outside its tree (#66) -----------------------
|
|
272
|
+
|
|
273
|
+
PROJECT_KEY_FILE = "project-key"
|
|
274
|
+
|
|
275
|
+
|
|
276
|
+
def project_registry_path():
|
|
277
|
+
"""Which path holds which project name on this machine."""
|
|
278
|
+
return os.environ.get("POLYCTL_PROJECT_REGISTRY") or os.path.join(HOME, ".polyctl", "projects.json")
|
|
279
|
+
|
|
280
|
+
|
|
281
|
+
def project_registry():
|
|
282
|
+
try:
|
|
283
|
+
with open(project_registry_path(), encoding=UTF8) as fh:
|
|
284
|
+
data = json.load(fh)
|
|
285
|
+
except (OSError, ValueError):
|
|
286
|
+
return {}
|
|
287
|
+
if not isinstance(data, dict):
|
|
288
|
+
return {}
|
|
289
|
+
return {name: row for name, row in data.items() if isinstance(row, dict) and row.get("root")}
|
|
290
|
+
|
|
291
|
+
|
|
292
|
+
def _usable_key(name):
|
|
293
|
+
return (isinstance(name, str) and 0 < len(name) <= 200 and name not in (".", "..")
|
|
294
|
+
and not any(ch in name for ch in "/\\\0\n\r"))
|
|
295
|
+
|
|
296
|
+
|
|
297
|
+
def project_key(root):
|
|
298
|
+
"""The name a project's files outside its tree are kept under (#66).
|
|
299
|
+
|
|
300
|
+
Push windows, watchdog state and logs, heartbeats, locks, the reviewer and
|
|
301
|
+
helper records and alarms were named by the directory's basename, so two
|
|
302
|
+
checkouts called `api` shared them: a push allowed in one opened the other,
|
|
303
|
+
and one project's watchdog state overwrote the other's.
|
|
304
|
+
|
|
305
|
+
A project's name belongs to its resolved path in the machine registry. A new
|
|
306
|
+
project takes its basename - the name its files already had, so an existing
|
|
307
|
+
install keeps them - unless a path that is still a polyctl project holds that
|
|
308
|
+
name, compared without case because launchd labels are lower-cased; then it
|
|
309
|
+
takes the basename and at least eight hex digits of its resolved path,
|
|
310
|
+
lengthened until no live project holds it (TRIAGE-2-MEDIUM). The name is
|
|
311
|
+
also written to `.polyctl/project-key` with the path, so a lost registry gives
|
|
312
|
+
each project its own name back and a copied `.polyctl/` does not claim another's.
|
|
313
|
+
A directory with no `.polyctl/` is not a polyctl project: it gets its basename and
|
|
314
|
+
nothing is written.
|
|
315
|
+
"""
|
|
316
|
+
base = os.path.basename(os.path.abspath(root).rstrip("/\\")) or "root"
|
|
317
|
+
real = os.path.realpath(root)
|
|
318
|
+
if not os.path.isdir(os.path.join(real, ".polyctl")):
|
|
319
|
+
return base
|
|
320
|
+
mine = next((name for name, row in project_registry().items() if row.get("root") == real), None)
|
|
321
|
+
if mine:
|
|
322
|
+
return mine
|
|
323
|
+
from .storage import _exclusive_lock, replace_file_durably, replace_in_tree
|
|
324
|
+
registry = project_registry_path()
|
|
325
|
+
recorded = os.path.join(real, ".polyctl", PROJECT_KEY_FILE)
|
|
326
|
+
registered = False
|
|
327
|
+
try:
|
|
328
|
+
with _exclusive_lock(registry + ".lock"):
|
|
329
|
+
known = project_registry()
|
|
330
|
+
mine = next((name for name, row in known.items() if row.get("root") == real), None)
|
|
331
|
+
registered = mine is not None
|
|
332
|
+
if mine is None:
|
|
333
|
+
held = {name.lower() for name, row in known.items()
|
|
334
|
+
if row.get("root") != real and os.path.isdir(os.path.join(row["root"], ".polyctl"))}
|
|
335
|
+
try:
|
|
336
|
+
with open(recorded, encoding=UTF8) as fh:
|
|
337
|
+
mark = json.load(fh)
|
|
338
|
+
except (OSError, ValueError):
|
|
339
|
+
mark = {}
|
|
340
|
+
wanted = mark.get("key") if isinstance(mark, dict) and mark.get("root") == real else None
|
|
341
|
+
if _usable_key(wanted) and wanted.lower() not in held:
|
|
342
|
+
mine = wanted
|
|
343
|
+
elif base.lower() not in held:
|
|
344
|
+
mine = base
|
|
345
|
+
else:
|
|
346
|
+
digest = hashlib.sha256(real.encode(UTF8)).hexdigest()
|
|
347
|
+
mine = next((f"{base}-{digest[:length]}" for length in (8, 12, 16, 64)
|
|
348
|
+
if f"{base}-{digest[:length]}".lower() not in held), None)
|
|
349
|
+
suffix = 2
|
|
350
|
+
while mine is None or mine.lower() in held:
|
|
351
|
+
mine = f"{base}-{digest}-{suffix}"
|
|
352
|
+
suffix += 1
|
|
353
|
+
known = {name: row for name, row in known.items() if name.lower() != mine.lower()}
|
|
354
|
+
known[mine] = {"root": real, "at": int(time.time())}
|
|
355
|
+
replace_file_durably(registry, json.dumps(known, indent=1, sort_keys=True).encode("utf-8"))
|
|
356
|
+
registered = True
|
|
357
|
+
# In the tree an agent writes, through no link: a `.polyctl` made one after the look above had the first
|
|
358
|
+
# command to name the project - `polyctl init` - write this file wherever it led (LEADS-ADAPTERS). One refused
|
|
359
|
+
# is an OSError, and the name the registry holds stands.
|
|
360
|
+
replace_in_tree(real, f".polyctl/{PROJECT_KEY_FILE}", json.dumps({"key": mine, "root": real}).encode("utf-8"))
|
|
361
|
+
except OSError:
|
|
362
|
+
# A name the registry did not record is one another project may hold or take: the bare basename came
|
|
363
|
+
# back here, and a push window allowed in one project of that name opened the other's. The path's
|
|
364
|
+
# own name is no other project's (PROJECT-KEY-2).
|
|
365
|
+
if registered or (mine and mine != base):
|
|
366
|
+
return mine
|
|
367
|
+
return f"{base}-{hashlib.sha256(real.encode('utf-8')).hexdigest()[:8]}"
|
|
368
|
+
return mine
|
|
369
|
+
|
|
370
|
+
|
|
371
|
+
def project_key_collisions():
|
|
372
|
+
"""Registered projects that share a directory name, and the name each is kept under."""
|
|
373
|
+
groups = {}
|
|
374
|
+
for name, row in sorted(project_registry().items()):
|
|
375
|
+
if not os.path.isdir(os.path.join(row["root"], ".polyctl")):
|
|
376
|
+
continue
|
|
377
|
+
base = os.path.basename(str(row["root"]).rstrip("/\\")).lower()
|
|
378
|
+
groups.setdefault(base, []).append((name, row["root"]))
|
|
379
|
+
return {base: rows for base, rows in groups.items() if len(rows) > 1}
|
|
380
|
+
|
|
381
|
+
|
|
382
|
+
# Every file a project keeps in ~/.polyctl, named under its key (SAFE-REMOVE). The code that writes one takes its name
|
|
383
|
+
# from here, and `polyctl remove` deletes exactly these. It deleted every file whose name merely held the key:
|
|
384
|
+
# removing `proj` took the machine's projects.json and its lock with the logs and push windows of `bigproject`
|
|
385
|
+
# and `myproj`, and removing a project called `email` would take the e-mail channel's settings. What polyctl archived
|
|
386
|
+
# for a project, ~/.polyctl/archive/<key>/, is not a file of this table: a review moved there is the record, and
|
|
387
|
+
# remove keeps it.
|
|
388
|
+
PROJECT_FILES = {
|
|
389
|
+
"heartbeat": "heartbeat-{key}",
|
|
390
|
+
"watchdog-state": "watchdog-{key}.json",
|
|
391
|
+
"watchdog-cycle-lock": "watchdog-{key}.cycle.lock",
|
|
392
|
+
"watchdog-log": "watchdog-{key}.log",
|
|
393
|
+
"cycles": "cycles-{key}.jsonl",
|
|
394
|
+
"nudge-log": "nudge-{key}.log",
|
|
395
|
+
"escalate-log": "escalate-{key}.log",
|
|
396
|
+
"refill-log": "refill-{key}.log",
|
|
397
|
+
"hunt-log": "hunt-{key}.log",
|
|
398
|
+
"doctor-log": "doctor-{key}.log",
|
|
399
|
+
"doctor-runs": "doctor-{key}.json",
|
|
400
|
+
"telegram-log": "telegram-{key}.log",
|
|
401
|
+
"push-window": "push-{key}.ok",
|
|
402
|
+
"helpers": "helpers-{key}.json",
|
|
403
|
+
"helpers-lock": "helpers-{key}.json.lock",
|
|
404
|
+
"reviewer": "reviewer-{key}.json",
|
|
405
|
+
"architect-lock": "architect-{key}.lock",
|
|
406
|
+
"architect-lock-guard": "architect-{key}.lock.guard",
|
|
407
|
+
# What the watchdog starts, claimed before its process does (JOURNAL-2), and the files SQLite keeps beside it.
|
|
408
|
+
"journal": "journal-{key}.db",
|
|
409
|
+
"journal-wal": "journal-{key}.db-wal",
|
|
410
|
+
"journal-shm": "journal-{key}.db-shm",
|
|
411
|
+
# The harness configuration a person has seen, outside the tree an agent writes (HARNESS-CONFIG).
|
|
412
|
+
"harness-seen": "harness-seen-{key}.json",
|
|
413
|
+
"harness-seen-lock": "harness-seen-{key}.lock", # orders that record's two writers (LEADS-OPEN)
|
|
414
|
+
"harness-base": "harness-base-{key}.json",
|
|
415
|
+
# Each role's turn command as last accepted, by polyctl init, the first reading or a person (TURN-ARGV).
|
|
416
|
+
"harness-turns": "harness-turns-{key}.json",
|
|
417
|
+
# Held while the baseline or the accepted commands are read and written, so two writers never cross
|
|
418
|
+
# (LEADS-ADAPTERS).
|
|
419
|
+
"harness-lock": "harness-{key}.lock",
|
|
420
|
+
}
|
|
421
|
+
|
|
422
|
+
|
|
423
|
+
def project_file_name(what, key):
|
|
424
|
+
"""The name one of a project's files has in ~/.polyctl, from PROJECT_FILES."""
|
|
425
|
+
return PROJECT_FILES[what].format(key=key)
|
|
426
|
+
|
|
427
|
+
|
|
428
|
+
def project_file(root, what, key=None):
|
|
429
|
+
"""Where one of this project's files is kept in ~/.polyctl, under `key` or the project's key."""
|
|
430
|
+
return os.path.join(HOME, ".polyctl", project_file_name(what, key or project_key(root)))
|
|
431
|
+
|
|
432
|
+
|
|
433
|
+
def project_file_names(key):
|
|
434
|
+
"""Every name one project's files can have in ~/.polyctl: each PROJECT_FILES name under its key, and in lower case.
|
|
435
|
+
|
|
436
|
+
A launchd label is lower-cased and a job's log is named from it; on a case-sensitive
|
|
437
|
+
filesystem that log is another file than one named from the key as it is.
|
|
438
|
+
"""
|
|
439
|
+
return sorted({project_file_name(what, name) for what in PROJECT_FILES for name in (key, key.lower())})
|
|
440
|
+
|
|
441
|
+
|
|
442
|
+
def registered_key(root):
|
|
443
|
+
"""The name the machine registry holds for this project's resolved path, or None."""
|
|
444
|
+
real = os.path.realpath(root)
|
|
445
|
+
return next((name for name, row in project_registry().items() if row.get("root") == real), None)
|
|
446
|
+
|
|
447
|
+
|
|
448
|
+
# What binds git to a repository other than the one it is asked about, from polyctl's own environment (LEADS-GATE-HOOK).
|
|
449
|
+
_GIT_BINDING = ("GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_COMMON_DIR", "GIT_PREFIX", "GIT_OBJECT_DIRECTORY",
|
|
450
|
+
"GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_CEILING_DIRECTORIES", "GIT_DISCOVERY_ACROSS_FILESYSTEM")
|
|
451
|
+
|
|
452
|
+
|
|
453
|
+
def repository_identity(root):
|
|
454
|
+
"""The repository a working tree belongs to, the same for each of its linked worktrees: its common git
|
|
455
|
+
directory, resolved (LEADS-GATE). RuntimeError where git cannot name it.
|
|
456
|
+
|
|
457
|
+
Asked with no repository binding inherited, as the hook inventory asks: `GIT_DIR=/other polyctl -C /victim hooks
|
|
458
|
+
install` recorded /other as enrolled while the hook went into /victim (LEADS-GATE-HOOK).
|
|
459
|
+
"""
|
|
460
|
+
env = {name: value for name, value in os.environ.items()
|
|
461
|
+
if name not in _GIT_BINDING and not name.startswith("GIT_CONFIG")}
|
|
462
|
+
# A commit check has already pinned its repository; enrollment reads and writes share it (NESTED-GIT).
|
|
463
|
+
env = bound_git_environment(env)
|
|
464
|
+
try:
|
|
465
|
+
done = run_as_group([git_binary(), "--literal-pathspecs", "-C", str(root), "rev-parse", "--git-common-dir"],
|
|
466
|
+
20, env=env, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
|
|
467
|
+
except (OSError, subprocess.TimeoutExpired) as exc:
|
|
468
|
+
raise RuntimeError(f"cannot ask git for the repository: {exc}") from exc
|
|
469
|
+
if done.returncode:
|
|
470
|
+
detail = done.stderr.decode(UTF8, "replace").strip()[:200]
|
|
471
|
+
raise RuntimeError(f"cannot ask git for the repository: {detail or 'git exit ' + str(done.returncode)}")
|
|
472
|
+
common = os.fsdecode(done.stdout.strip())
|
|
473
|
+
return os.path.realpath(os.path.join(root, common))
|
|
474
|
+
|
|
475
|
+
|
|
476
|
+
# The record that a repository is enrolled, in its common git directory (LEADS-GATE-HOOK).
|
|
477
|
+
ENROLLMENT_RECORD = "polyctl-enrolled.json"
|
|
478
|
+
|
|
479
|
+
|
|
480
|
+
def enrollment_record_path(root):
|
|
481
|
+
"""(where the record that the repository `root` belongs to is enrolled is kept, that repository): in the
|
|
482
|
+
repository's own common git directory, beside its refs, outside the tree an agent writes (LEADS-GATE-HOOK).
|
|
483
|
+
|
|
484
|
+
It was kept in `~/.polyctl`, found through `HOME`: `HOME=<empty> git commit` had the hook's polyctl read a home with
|
|
485
|
+
no record in it, and under a project key, which a `.polyctl/project-key` in a tree claims once the project's `.polyctl/`
|
|
486
|
+
is gone. The git directory is the repository's, the one every linked worktree of it shares, and no
|
|
487
|
+
environment the commit is given names another. RuntimeError where git cannot name the repository.
|
|
488
|
+
"""
|
|
489
|
+
identity = repository_identity(root)
|
|
490
|
+
return os.path.join(identity, ENROLLMENT_RECORD), identity
|
|
491
|
+
|
|
492
|
+
|
|
493
|
+
def enrollment_record(root):
|
|
494
|
+
"""What this machine recorded of the repository `root` belongs to being enrolled, or None (LEADS-GATE-HOOK).
|
|
495
|
+
|
|
496
|
+
The record is kept in the repository's common git directory, so a linked worktree of an enrolled
|
|
497
|
+
repository finds it too, and it is never read through a `.polyctl/` an agent can empty, nor through `HOME`. One
|
|
498
|
+
that cannot be read, or names another repository, is one all the same: {"unreadable": why}.
|
|
499
|
+
"""
|
|
500
|
+
try:
|
|
501
|
+
path, identity = enrollment_record_path(root)
|
|
502
|
+
except (RuntimeError, OSError) as exc:
|
|
503
|
+
return {"unreadable": f"git cannot name the repository: {' '.join(str(exc).split())[:160]}"}
|
|
504
|
+
try:
|
|
505
|
+
with open(path, encoding=UTF8) as fh:
|
|
506
|
+
data = json.load(fh)
|
|
507
|
+
except FileNotFoundError:
|
|
508
|
+
return None
|
|
509
|
+
except (OSError, ValueError) as exc:
|
|
510
|
+
return {"unreadable": " ".join(str(exc).split())[:160]}
|
|
511
|
+
if not isinstance(data, dict):
|
|
512
|
+
return {"unreadable": "it is not a JSON object"}
|
|
513
|
+
if data.get("repository") != identity:
|
|
514
|
+
return {"unreadable": f"it names another repository, {str(data.get('repository'))[:160]!r}"}
|
|
515
|
+
return data
|
|
516
|
+
|
|
517
|
+
|
|
518
|
+
def record_enrollment(root):
|
|
519
|
+
"""Record outside the tree, once, that the repository `root` belongs to is enrolled: None once it is, or why it
|
|
520
|
+
could not be (LEADS-GATE-HOOK).
|
|
521
|
+
|
|
522
|
+
A branch not born yet asks for it: an implementer that deleted every ref whose history tracked the
|
|
523
|
+
marker left Git no answer that the repository was ever enrolled, and the hook stood aside. Written by
|
|
524
|
+
`polyctl hooks install`, which puts the hook that asks for it in place, and by each commit check of an
|
|
525
|
+
enrolled project; each refuses where it cannot be written, since a record missing is that branch read
|
|
526
|
+
as a new repository's. A record of another repository under the same name is never written over.
|
|
527
|
+
"""
|
|
528
|
+
try:
|
|
529
|
+
path, identity = enrollment_record_path(root)
|
|
530
|
+
except (RuntimeError, OSError) as exc:
|
|
531
|
+
return f"git cannot name the repository: {' '.join(str(exc).split())[:160]}"
|
|
532
|
+
try:
|
|
533
|
+
with open(path, encoding=UTF8) as fh:
|
|
534
|
+
kept = json.load(fh)
|
|
535
|
+
except FileNotFoundError:
|
|
536
|
+
kept = None
|
|
537
|
+
except (OSError, ValueError) as exc:
|
|
538
|
+
return f"{path} cannot be read: {' '.join(str(exc).split())[:160]}"
|
|
539
|
+
if isinstance(kept, dict) and kept.get("repository") == identity:
|
|
540
|
+
return None
|
|
541
|
+
if kept is not None:
|
|
542
|
+
return f"{path} names another repository, {str((kept or {}).get('repository'))[:160]!r}, and stays"
|
|
543
|
+
from .storage import replace_file_durably
|
|
544
|
+
try:
|
|
545
|
+
replace_file_durably(path, json.dumps({"root": os.path.realpath(root), "repository": identity,
|
|
546
|
+
"at": int(time.time())}).encode(UTF8))
|
|
547
|
+
except OSError as exc:
|
|
548
|
+
return f"{path} could not be written: {' '.join(str(exc).split())[:160]}"
|
|
549
|
+
return None
|
|
550
|
+
|
|
551
|
+
|
|
552
|
+
def forget_project(root):
|
|
553
|
+
"""Take this project's rows out of the machine registry, under its lock; the names they held (SAFE-REMOVE).
|
|
554
|
+
|
|
555
|
+
The registry names every project on this machine, so it is never deleted: only the rows
|
|
556
|
+
holding this project's resolved path go, and every other row is written back as it was
|
|
557
|
+
read. Raises OSError or ValueError when the registry cannot be read or replaced.
|
|
558
|
+
"""
|
|
559
|
+
from .storage import _exclusive_lock, replace_file_durably
|
|
560
|
+
real = os.path.realpath(root)
|
|
561
|
+
registry = project_registry_path()
|
|
562
|
+
if not os.path.exists(registry):
|
|
563
|
+
return []
|
|
564
|
+
with _exclusive_lock(registry + ".lock"):
|
|
565
|
+
with open(registry, encoding=UTF8) as fh:
|
|
566
|
+
known = json.load(fh)
|
|
567
|
+
if not isinstance(known, dict):
|
|
568
|
+
raise ValueError(f"{registry} holds no JSON object")
|
|
569
|
+
gone = sorted(name for name, row in known.items() if isinstance(row, dict) and row.get("root") == real)
|
|
570
|
+
if gone:
|
|
571
|
+
kept = {name: row for name, row in known.items() if name not in gone}
|
|
572
|
+
replace_file_durably(registry, json.dumps(kept, indent=1, sort_keys=True).encode("utf-8"))
|
|
573
|
+
return gone
|
|
574
|
+
|
|
575
|
+
|
|
576
|
+
def heartbeat_path(root):
|
|
577
|
+
return project_file(root, "heartbeat")
|
|
578
|
+
|
|
579
|
+
|
|
580
|
+
def heartbeat(root):
|
|
581
|
+
"""The watchdog touching this each cycle is the only proof it is alive."""
|
|
582
|
+
try:
|
|
583
|
+
p = heartbeat_path(root)
|
|
584
|
+
os.makedirs(os.path.dirname(p), exist_ok=True)
|
|
585
|
+
with open(p, "w", encoding=UTF8) as fh:
|
|
586
|
+
fh.write(str(int(time.time())))
|
|
587
|
+
except OSError:
|
|
588
|
+
pass
|
|
589
|
+
|
|
590
|
+
|
|
591
|
+
def heartbeat_age(root):
|
|
592
|
+
try:
|
|
593
|
+
return int(time.time() - os.path.getmtime(heartbeat_path(root)))
|
|
594
|
+
except OSError:
|
|
595
|
+
return None
|
|
596
|
+
|
|
597
|
+
|
|
598
|
+
@_alarm_store_locked(_none_expired)
|
|
599
|
+
def expire_alarms(project, now=None, quiet_for=None):
|
|
600
|
+
"""Episodes that went quiet are over; return them once and forget them.
|
|
601
|
+
|
|
602
|
+
`quiet_for` is a shorter quiet that ends one: a resume closes every episode its silence
|
|
603
|
+
carried, which nothing watched, instead of letting them age on (RESUME-QUIET).
|
|
604
|
+
"""
|
|
605
|
+
now = now or time.time()
|
|
606
|
+
quiet = _alarm_reset_after() if quiet_for is None else quiet_for
|
|
607
|
+
d = load_alarms()
|
|
608
|
+
done = []
|
|
609
|
+
for k in list(d):
|
|
610
|
+
proj, _, key = k.partition(":")
|
|
611
|
+
e = d[k]
|
|
612
|
+
if proj == project and now - e.get("last", 0) > quiet:
|
|
613
|
+
done.append(dict(e, project=proj, key=key, age_s=int(e.get("last", now) - e.get("first", now))))
|
|
614
|
+
del d[k]
|
|
615
|
+
if done:
|
|
616
|
+
save_alarms(d)
|
|
617
|
+
return done
|
|
618
|
+
|
|
619
|
+
|
|
620
|
+
RETIRED_HEARTBEAT_AGE = settings.default("heartbeat.retired_days") * 86400
|
|
621
|
+
|
|
622
|
+
|
|
623
|
+
def stale_siblings(root, max_age=900):
|
|
624
|
+
"""Other projects whose watchdog once had a heartbeat and now has none.
|
|
625
|
+
|
|
626
|
+
A dead watchdog cannot report itself; the ones next to it can. Only projects
|
|
627
|
+
with a heartbeat file count — a project that never ran one is not late."""
|
|
628
|
+
me = project_key(root)
|
|
629
|
+
out = {}
|
|
630
|
+
try:
|
|
631
|
+
for f in os.listdir(os.path.join(HOME, ".polyctl")):
|
|
632
|
+
if not f.startswith("heartbeat-") or f == f"heartbeat-{me}":
|
|
633
|
+
continue
|
|
634
|
+
age = int(time.time() - os.path.getmtime(os.path.join(HOME, ".polyctl", f)))
|
|
635
|
+
# A week of silence is a project that was retired, not a watchdog that
|
|
636
|
+
# just died; ringing a person about it every cycle never ended (audit).
|
|
637
|
+
if max_age < age <= settings.get(None, "heartbeat.retired_days") * 86400:
|
|
638
|
+
out[f[len("heartbeat-"):]] = age
|
|
639
|
+
except OSError:
|
|
640
|
+
pass
|
|
641
|
+
return out
|
|
642
|
+
|
|
643
|
+
|
|
644
|
+
def scheduler_hint():
|
|
645
|
+
"""Where a person looks into a watchdog that stopped, on this platform: launchd's `launchctl` on macOS, a user
|
|
646
|
+
systemd's `systemctl --user` on Linux, Task Scheduler on Windows (WINDOWS-SAY-WHY).
|
|
647
|
+
|
|
648
|
+
A silent watchdog was told "launchctl / polyctl watchdog status" on every platform, and the tool it
|
|
649
|
+
named is not there on Windows or Linux.
|
|
650
|
+
"""
|
|
651
|
+
if os.name == "nt":
|
|
652
|
+
return "Task Scheduler"
|
|
653
|
+
return "systemctl --user" if sys.platform.startswith("linux") else "launchctl"
|
|
654
|
+
|
|
655
|
+
|
|
656
|
+
# ---- review scope ----------------------------------------------------------------
|
|
657
|
+
|
|
658
|
+
COORDINATION_DIRS = (".polyctl/", "agent-mail/") # and each shipped harness's own, from harness_dirs()
|
|
659
|
+
|
|
660
|
+
|
|
661
|
+
def harness_dirs():
|
|
662
|
+
"""What the shipped harnesses keep in a repository (`detect.dirs`), each ending in a slash (#76)."""
|
|
663
|
+
return tuple(sorted({str(d).strip("/") + "/" for adapter in package_adapters().values()
|
|
664
|
+
for d in (adapter.get("detect") or {}).get("dirs") or [] if str(d).strip("/")}))
|
|
665
|
+
|
|
666
|
+
|
|
667
|
+
def review_diff(root, cfg, paths=None, budget=1_500_000):
|
|
668
|
+
"""What the reviewer sees: the slice's changes, and nothing else.
|
|
669
|
+
|
|
670
|
+
`git diff HEAD` carried every tracked change in the tree, so an unrelated
|
|
671
|
+
steering edit polluted a review of a credential lifecycle; untracked files
|
|
672
|
+
were capped at the first twenty, and thirty review artefacts consumed the
|
|
673
|
+
cap before the one untracked file that mattered — the inventory under
|
|
674
|
+
review — was reached. Two rounds of a five-round budget went to that.
|
|
675
|
+
|
|
676
|
+
Coordination directories are never product. Untracked product files are
|
|
677
|
+
included newest first within a byte budget. `paths` narrows both sides.
|
|
678
|
+
"""
|
|
679
|
+
skip = _coordination_dirs(cfg)
|
|
680
|
+
# Git without a shell: the pathspecs were single-quoted for sh, cmd.exe hands the quotes
|
|
681
|
+
# to git as part of each path, and a scoped diff held none of the changes it named (#71).
|
|
682
|
+
spec = ["--", *paths] if paths else []
|
|
683
|
+
diff = _git_text(root, "diff", "HEAD", *spec, timeout=60) or ""
|
|
684
|
+
if not paths:
|
|
685
|
+
parts = re.split(r"(?m)^(?=diff --git )", diff)
|
|
686
|
+
diff = "".join(pt for pt in parts if not any(
|
|
687
|
+
f" b/{d}" in pt.split("\n", 1)[0] for d in skip))
|
|
688
|
+
untracked = [l[3:].strip().strip('"') for l in (_git_text(root, "status", "--porcelain") or "").split("\n")
|
|
689
|
+
if l.startswith("?? ")]
|
|
690
|
+
untracked = [f for f in untracked if not _is_coordination_path(f, cfg)]
|
|
691
|
+
if paths:
|
|
692
|
+
untracked = [f for f in untracked if any(f == p or f.startswith(p.rstrip("/") + "/")
|
|
693
|
+
or p.startswith(f.rstrip("/") + "/") for p in paths)]
|
|
694
|
+
files = []
|
|
695
|
+
for f in untracked:
|
|
696
|
+
p = os.path.join(root, f)
|
|
697
|
+
if os.path.isdir(p):
|
|
698
|
+
for dp, _, fn in os.walk(p):
|
|
699
|
+
for x in fn:
|
|
700
|
+
rel = os.path.relpath(os.path.join(dp, x), root).replace(os.sep, "/")
|
|
701
|
+
if _is_coordination_path(rel, cfg):
|
|
702
|
+
continue
|
|
703
|
+
if not paths or any(rel == q or rel.startswith(q.rstrip("/") + "/") for q in paths):
|
|
704
|
+
files.append(rel)
|
|
705
|
+
elif os.path.isfile(p):
|
|
706
|
+
files.append(f)
|
|
707
|
+
files.sort(key=lambda f: -os.path.getmtime(os.path.join(root, f)))
|
|
708
|
+
included, used = [], 0
|
|
709
|
+
for f in files:
|
|
710
|
+
p = os.path.join(root, f)
|
|
711
|
+
try:
|
|
712
|
+
size = os.path.getsize(p)
|
|
713
|
+
if size > 400_000 or used + size > budget:
|
|
714
|
+
continue
|
|
715
|
+
raw = open(p, "rb").read()
|
|
716
|
+
if b"\0" in raw[:4000]:
|
|
717
|
+
continue
|
|
718
|
+
diff += f"\n--- NEW FILE {f} ---\n" + raw.decode("utf-8", "replace")
|
|
719
|
+
used += size
|
|
720
|
+
included.append(f)
|
|
721
|
+
except OSError:
|
|
722
|
+
pass
|
|
723
|
+
return diff, included
|
|
724
|
+
|
|
725
|
+
|
|
726
|
+
# ---- helpers: processes polyctl starts that are not writers -------------------------
|
|
727
|
+
|
|
728
|
+
def helpers_path(root):
|
|
729
|
+
return project_file(root, "helpers")
|
|
730
|
+
|
|
731
|
+
|
|
732
|
+
def _helpers_update(root, change):
|
|
733
|
+
"""Change the helper registry under its lock and replace it whole (#68).
|
|
734
|
+
|
|
735
|
+
It was read, changed and written back unlocked, and the read path wrote too, so
|
|
736
|
+
a status call overwrote a helper registered a moment before and the watchdog
|
|
737
|
+
counted a running reviewer as a second writer.
|
|
738
|
+
"""
|
|
739
|
+
from .storage import _exclusive_lock, replace_file_durably
|
|
740
|
+
path = helpers_path(root)
|
|
741
|
+
os.makedirs(os.path.dirname(path), exist_ok=True)
|
|
742
|
+
with _exclusive_lock(project_file(root, "helpers-lock")):
|
|
743
|
+
try:
|
|
744
|
+
with open(path, encoding=UTF8) as fh:
|
|
745
|
+
d = json.load(fh)
|
|
746
|
+
except (OSError, ValueError):
|
|
747
|
+
d = {}
|
|
748
|
+
if not isinstance(d, dict):
|
|
749
|
+
d = {}
|
|
750
|
+
change(d)
|
|
751
|
+
replace_file_durably(path, json.dumps(d).encode(UTF8))
|
|
752
|
+
|
|
753
|
+
|
|
754
|
+
def helper_register(root, pid, what):
|
|
755
|
+
"""A reviewer, a probe: started by polyctl inside the repo, never a writer.
|
|
756
|
+
|
|
757
|
+
Bind the declaration to process start identity. PID existence alone is not
|
|
758
|
+
identity: after reuse it would exclude an unrelated process indefinitely.
|
|
759
|
+
"""
|
|
760
|
+
start = _process_start(pid, refresh=True)
|
|
761
|
+
|
|
762
|
+
def change(d):
|
|
763
|
+
# Dead, reused or unprovable entries go here, under the lock, never on a read.
|
|
764
|
+
for key in list(d):
|
|
765
|
+
recorded = d.get(key) if isinstance(d.get(key), dict) else {}
|
|
766
|
+
try:
|
|
767
|
+
current = _process_start(int(key))
|
|
768
|
+
except (TypeError, ValueError):
|
|
769
|
+
current = None
|
|
770
|
+
if current is None or current != recorded.get("start"):
|
|
771
|
+
d.pop(key, None)
|
|
772
|
+
d[str(pid)] = {"what": what, "at": int(time.time()), "start": start}
|
|
773
|
+
|
|
774
|
+
try:
|
|
775
|
+
_helpers_update(root, change)
|
|
776
|
+
except OSError:
|
|
777
|
+
pass
|
|
778
|
+
|
|
779
|
+
|
|
780
|
+
def helper_release(root, pid):
|
|
781
|
+
try:
|
|
782
|
+
_helpers_update(root, lambda d: d.pop(str(pid), None))
|
|
783
|
+
except OSError:
|
|
784
|
+
pass
|
|
785
|
+
|
|
786
|
+
|
|
787
|
+
def helper_pids(root, what=None):
|
|
788
|
+
"""Registered helpers still running as the process that registered; reading writes nothing."""
|
|
789
|
+
try:
|
|
790
|
+
with open(helpers_path(root), encoding=UTF8) as fh:
|
|
791
|
+
d = json.load(fh)
|
|
792
|
+
except (OSError, ValueError):
|
|
793
|
+
return set()
|
|
794
|
+
if not isinstance(d, dict):
|
|
795
|
+
return set()
|
|
796
|
+
live = set()
|
|
797
|
+
for key, recorded in d.items():
|
|
798
|
+
try:
|
|
799
|
+
pid = int(key)
|
|
800
|
+
except (TypeError, ValueError):
|
|
801
|
+
continue
|
|
802
|
+
recorded = recorded if isinstance(recorded, dict) else {}
|
|
803
|
+
current_start = _process_start(pid)
|
|
804
|
+
# Dead, reused, or legacy/unprovable pid: never let declaration alone
|
|
805
|
+
# exclude a process. Conservative writer checks may count it once.
|
|
806
|
+
if current_start is not None and recorded.get("start") == current_start:
|
|
807
|
+
if what is None or recorded.get("what") == what:
|
|
808
|
+
live.add(pid)
|
|
809
|
+
return live
|
|
810
|
+
|
|
811
|
+
|
|
812
|
+
# ---- cost: what the coordination itself spends ----------------------------------
|
|
813
|
+
#
|
|
814
|
+
# "How much quota does polyctl cost, and is it bureaucracy?" is answerable only from
|
|
815
|
+
# the transcript. Every turn is classified by what it did — wrote product, ran
|
|
816
|
+
# the review/gate ceremony, only coordinated, or read and thought — and its
|
|
817
|
+
# spend is summed per class, so the overhead is a number and not an opinion.
|
|
818
|
+
|
|
819
|
+
_PRODUCT_PATH = re.compile(r"(^|/)(src|lib|app|apps|test|tests|spec|fixtures|evidence|docs|plugins|site|"
|
|
820
|
+
r"package\.json|pyproject\.toml|tsconfig)")
|
|
821
|
+
def _coord_path():
|
|
822
|
+
"""A path under a coordination directory, the shipped harnesses' own included (#76)."""
|
|
823
|
+
names = ["agent-mail", r"\.polyctl", "semantic-review"] + [re.escape(d.rstrip("/")) for d in harness_dirs()]
|
|
824
|
+
return re.compile(r"(^|/)(" + "|".join(names) + r")(/|$)")
|
|
825
|
+
|
|
826
|
+
|
|
827
|
+
# ---- what each feature costs, measured rather than estimated (#10) ------------------------
|
|
828
|
+
|
|
829
|
+
SPAWN_LOGS = {"nudge": "nudge-log", "architect_wake": "escalate-log", "refill": "refill-log"} # PROJECT_FILES
|
|
830
|
+
|
|
831
|
+
|
|
832
|
+
def spawn_times(root, what, since=None):
|
|
833
|
+
"""When the watchdog started a nudge, an architect wake or a refill, read from its own logs (#10)."""
|
|
834
|
+
from .watchdog import STATE_DIR
|
|
835
|
+
path = os.path.join(STATE_DIR, project_file_name(SPAWN_LOGS[what], project_key(root)))
|
|
836
|
+
times = []
|
|
837
|
+
try:
|
|
838
|
+
with open(path, encoding=UTF8, errors="replace") as fh:
|
|
839
|
+
for line in fh:
|
|
840
|
+
found = re.match(r"^=== (\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}) ", line)
|
|
841
|
+
if found:
|
|
842
|
+
at = time.mktime(time.strptime(found.group(1), "%Y-%m-%d %H:%M:%S"))
|
|
843
|
+
if since is None or at >= since:
|
|
844
|
+
times.append(at)
|
|
845
|
+
except OSError:
|
|
846
|
+
pass
|
|
847
|
+
return times
|
|
848
|
+
|
|
849
|
+
|
|
850
|
+
def feature_costs(cfg, since=None):
|
|
851
|
+
"""The implementer's spend attributed to each feature switch, and the window it was measured over (#10).
|
|
852
|
+
|
|
853
|
+
`review`: turns that ran `polyctl review`. `reports`: turns that only coordinated -
|
|
854
|
+
inbox, report, board, writers. `nudge`: turns a nudge started, within five
|
|
855
|
+
minutes of it, that wrote no product; a nudge that started real work is the
|
|
856
|
+
work, not overhead. The architect's wakes and refills spend the architect's
|
|
857
|
+
pool, not this transcript, so they are counted and not priced, and an
|
|
858
|
+
inventory review cannot be told from a review in a transcript, so it is
|
|
859
|
+
counted with review. A turn the model never answered (`UNANSWERED`) is no turn
|
|
860
|
+
of the implementer's.
|
|
861
|
+
"""
|
|
862
|
+
root = cfg["root"]
|
|
863
|
+
costs = turn_costs(cfg, since)
|
|
864
|
+
turns = [turn for turn in costs["turns"] if turn.get("cls") not in (None, UNANSWERED)]
|
|
865
|
+
nudges = spawn_times(root, "nudge", since)
|
|
866
|
+
features = {name: {"turns": 0, "usage": 0.0} for name in ("review", "reports", "nudge")}
|
|
867
|
+
for turn in turns:
|
|
868
|
+
start = turn.get("start") or 0
|
|
869
|
+
if turn.get("reviews"):
|
|
870
|
+
key = "review"
|
|
871
|
+
elif turn["cls"] == "coordination":
|
|
872
|
+
key = "reports"
|
|
873
|
+
elif turn["cls"] != "product" and any(0 <= start - at <= 300 for at in nudges):
|
|
874
|
+
key = "nudge"
|
|
875
|
+
else:
|
|
876
|
+
continue
|
|
877
|
+
features[key]["turns"] += 1
|
|
878
|
+
features[key]["usage"] += float(turn.get("usage") or 0)
|
|
879
|
+
starts = [turn["start"] for turn in turns if turn.get("start")]
|
|
880
|
+
return {"unit": costs["unit"], "total": sum(float(turn.get("usage") or 0) for turn in turns),
|
|
881
|
+
"turns": len(turns), "from": min(starts) if starts else None, "to": max(starts) if starts else None,
|
|
882
|
+
"features": features,
|
|
883
|
+
"counted": dict({what: len(spawn_times(root, what, since)) for what in ("architect_wake", "refill")},
|
|
884
|
+
hunter=sum(1 for row in hunter_rows(root) if row.get("event") == "run"
|
|
885
|
+
and (since is None or row.get("at", 0) >= since)))}
|
|
886
|
+
|
|
887
|
+
|
|
888
|
+
# The class of a turn the model never answered: every reply in it the harness wrote in the model's place,
|
|
889
|
+
# with no usage (`in_place_reply`). It spent nothing and did nothing, and is counted apart from the classes
|
|
890
|
+
# of the implementer's work.
|
|
891
|
+
UNANSWERED = "unanswered"
|
|
892
|
+
|
|
893
|
+
|
|
894
|
+
def turn_costs(cfg, since=None, by_model=False):
|
|
895
|
+
"""Per-turn cost and class from the implementer's transcript.
|
|
896
|
+
|
|
897
|
+
Returns {"unit", "turns": [ {start, usage, delegated, cls, tool_calls, product_writes,
|
|
898
|
+
reviews, commits, blocked_report} ], "by_class": {cls: {turns, usage, delegated}},
|
|
899
|
+
"polyctl_commands": Counter, "total", "delegated"}. Classes: product (wrote product files or
|
|
900
|
+
committed), ceremony (review / verify / lock / commit-ok, nothing written),
|
|
901
|
+
coordination (only inbox/report/writers/board, few calls), analysis (read and
|
|
902
|
+
reasoned, wrote nothing). A turn whose every reply the harness wrote in the model's
|
|
903
|
+
place, with no usage (`in_place_reply`) - an error of the model's service, a reply to a
|
|
904
|
+
note that asked the model nothing - is `UNANSWERED`: counted, and counted apart.
|
|
905
|
+
|
|
906
|
+
A subagent the implementer started works for it: the records of its transcript
|
|
907
|
+
(`transcript.subagents`) are read after the record that starts it, its spend is in the
|
|
908
|
+
usage of the turn that started it and in that turn's `delegated`, and its tool calls,
|
|
909
|
+
writes and commits are that turn's (`with_subagents`).
|
|
910
|
+
|
|
911
|
+
Which records open and close a turn, carry usage or call a tool is the
|
|
912
|
+
implementer's adapter's to declare (`transcript.turn`, `transcript.messages`,
|
|
913
|
+
`transcript.tool_call`, `telemetry.cost`), and so is the reading that adds usage
|
|
914
|
+
up (`billing.fallback.reading`), the one the credit estimate applies. A turn opens
|
|
915
|
+
at a start record, or at a prompt when none is open or the open one ended; the
|
|
916
|
+
start record that follows a turn's prompt is that turn's start, not a second turn
|
|
917
|
+
(`next_turn`). Counting both doubled every turn count and left spend where it was.
|
|
918
|
+
|
|
919
|
+
With `by_model`, the same records are also read for the tokens the adapter prices
|
|
920
|
+
(`telemetry.cost.tokens`), by model, rate and kind, under the same reading (`add_tokens`):
|
|
921
|
+
each turn holds its own in `tokens`, and the result's `tokens` adds up those of the turns
|
|
922
|
+
in the window, as `total` adds up their usage - what `polyctl cost --usd` prices (USD-COST). The
|
|
923
|
+
result's `tokens` is None when the adapter declares no tokens polyctl can price.
|
|
924
|
+
"""
|
|
925
|
+
import collections
|
|
926
|
+
msgs, _ = session_paths(cfg)
|
|
927
|
+
shape = transcript_shape(implementer_adapter(cfg))
|
|
928
|
+
usage, tool = shape["usage"], shape["tool"]
|
|
929
|
+
priced = shape["tokens"] if by_model else None
|
|
930
|
+
out = {"unit": shape["unit"], "turns": [], "by_class": {}, "polyctl_commands": collections.Counter(), "total": 0.0,
|
|
931
|
+
"delegated": 0.0}
|
|
932
|
+
if by_model:
|
|
933
|
+
out["tokens"] = {} if priced else None
|
|
934
|
+
if not msgs or not os.path.exists(msgs):
|
|
935
|
+
return out
|
|
936
|
+
recs = read_tail(msgs, 400_000_000)
|
|
937
|
+
cur, counted, counted_tokens = None, {}, {}
|
|
938
|
+
in_place, answered = set(), set() # the turns holding a reply written in the model's place, or its own
|
|
939
|
+
|
|
940
|
+
def ts(d):
|
|
941
|
+
raw = record_time(d, shape)
|
|
942
|
+
try:
|
|
943
|
+
import datetime as _dt
|
|
944
|
+
return _dt.datetime.fromisoformat(raw.replace("Z", "+00:00")).timestamp()
|
|
945
|
+
except Exception:
|
|
946
|
+
return None
|
|
947
|
+
for d, subagent in with_subagents(recs, shape, msgs):
|
|
948
|
+
pl = record_body(d, shape) or {}
|
|
949
|
+
t = record_kind(d, shape)
|
|
950
|
+
cur, opened = next_turn(cur, d, shape, subagent)
|
|
951
|
+
if opened:
|
|
952
|
+
cur.update({"start": ts(d), "usage": 0.0, "delegated": 0.0, "product_writes": 0, "coord_writes": 0,
|
|
953
|
+
"tool_calls": 0, "reviews": 0, "commits": 0, "blocked_report": False,
|
|
954
|
+
"polyctl": collections.Counter()})
|
|
955
|
+
out["turns"].append(cur)
|
|
956
|
+
continue
|
|
957
|
+
if cur is None:
|
|
958
|
+
continue
|
|
959
|
+
if subagent is None and t in shape["reply"]:
|
|
960
|
+
(in_place if in_place_reply(d, shape) else answered).add(id(cur))
|
|
961
|
+
if usage and t == usage["type"]:
|
|
962
|
+
add_usage(cur, pl, usage, counted, subagent)
|
|
963
|
+
if priced:
|
|
964
|
+
add_tokens(cur, pl, usage, priced, counted_tokens, subagent)
|
|
965
|
+
# Not an elif: one record of a store that nests its calls carries a response's usage and its tool calls.
|
|
966
|
+
if tool and t == tool["type"]:
|
|
967
|
+
for name, args in tool_calls(pl, tool):
|
|
968
|
+
cur["tool_calls"] += 1
|
|
969
|
+
args = args or {}
|
|
970
|
+
text = json.dumps(args, ensure_ascii=False) if not isinstance(args, str) else args
|
|
971
|
+
if name.endswith("polyctl_report") and "blocked" in text: # MCP clients prefix tool names
|
|
972
|
+
cur["blocked_report"] = True
|
|
973
|
+
if tool_writes_file(name, tool):
|
|
974
|
+
# A harness on Windows names the file with backslashes, and a turn that wrote product or
|
|
975
|
+
# coordination files was counted as analysis; the classes are read with slashes (#71).
|
|
976
|
+
path = str(tool_path(args, tool) or "").replace("\\", "/")
|
|
977
|
+
if _coord_path().search(path):
|
|
978
|
+
cur["coord_writes"] += 1
|
|
979
|
+
elif _PRODUCT_PATH.search(path) or (path and "/" in path):
|
|
980
|
+
cur["product_writes"] += 1
|
|
981
|
+
m = re.search(r"\bpolyctl\s+(?:-C\s+\S+\s+)?([a-z][a-z-]+)", text)
|
|
982
|
+
if m:
|
|
983
|
+
cur["polyctl"][m.group(1)] += 1
|
|
984
|
+
out["polyctl_commands"][m.group(1)] += 1
|
|
985
|
+
if re.search(r"\bpolyctl\s+(?:-C\s+\S+\s+)?review\b", text):
|
|
986
|
+
cur["reviews"] += 1
|
|
987
|
+
if re.search(r"git\s+commit\b", text):
|
|
988
|
+
cur["commits"] += 1
|
|
989
|
+
for tn in out["turns"]:
|
|
990
|
+
if since and (not tn["start"] or tn["start"] < since):
|
|
991
|
+
tn["cls"] = None
|
|
992
|
+
continue
|
|
993
|
+
if id(tn) in in_place and id(tn) not in answered and not tn["usage"]:
|
|
994
|
+
cls = UNANSWERED
|
|
995
|
+
elif tn["product_writes"] or tn["commits"]:
|
|
996
|
+
cls = "product"
|
|
997
|
+
elif tn["reviews"] or any(c in tn["polyctl"] for c in ("verify", "lock", "commit-ok")):
|
|
998
|
+
cls = "ceremony"
|
|
999
|
+
elif tn["blocked_report"] or (tn["tool_calls"] <= 8 and (tn["polyctl"] or tn["coord_writes"])):
|
|
1000
|
+
cls = "coordination"
|
|
1001
|
+
else:
|
|
1002
|
+
cls = "analysis"
|
|
1003
|
+
tn["cls"] = cls
|
|
1004
|
+
b = out["by_class"].setdefault(cls, {"turns": 0, "usage": 0.0, "wasted": 0, "wasted_usage": 0.0,
|
|
1005
|
+
"delegated": 0.0})
|
|
1006
|
+
b["turns"] += 1
|
|
1007
|
+
b["usage"] += tn["usage"]
|
|
1008
|
+
b["delegated"] += tn["delegated"]
|
|
1009
|
+
if tn["blocked_report"] and not tn["product_writes"]:
|
|
1010
|
+
b["wasted"] += 1
|
|
1011
|
+
b["wasted_usage"] += tn["usage"]
|
|
1012
|
+
out["total"] += tn["usage"]
|
|
1013
|
+
out["delegated"] += tn["delegated"]
|
|
1014
|
+
if priced:
|
|
1015
|
+
for key, count in tn.get("tokens", {}).items():
|
|
1016
|
+
out["tokens"][key] = out["tokens"].get(key, 0) + count
|
|
1017
|
+
return out
|
|
1018
|
+
|
|
1019
|
+
|
|
1020
|
+
# ---- the spend in US dollars: an estimate from a price table polyctl ships (USD-COST) ----------------
|
|
1021
|
+
#
|
|
1022
|
+
# A vendor bills tokens by model and by kind, at list prices it publishes and changes. polyctl ships
|
|
1023
|
+
# those prices as data, src/polyctl/prices.json, with the day each vendor's were read and where, and
|
|
1024
|
+
# prices the tokens `turn_costs(by_model=True)` reads with them. A figure the table cannot back
|
|
1025
|
+
# is unknown, never zero: a model or a kind of token it does not price, or a response at a rate
|
|
1026
|
+
# it does not list. Only an entry that lists a model at zero prices it free.
|
|
1027
|
+
|
|
1028
|
+
PRICES_FILE = os.path.join(_HERE, "prices.json")
|
|
1029
|
+
|
|
1030
|
+
|
|
1031
|
+
def _price(value):
|
|
1032
|
+
"""Is a value a price polyctl can quote: a finite number of zero or more, and not a truth value?"""
|
|
1033
|
+
return isinstance(value, (int, float)) and not isinstance(value, bool) and 0 <= value < float("inf")
|
|
1034
|
+
|
|
1035
|
+
|
|
1036
|
+
def _day(text):
|
|
1037
|
+
"""Is a value a calendar day written YYYY-MM-DD?"""
|
|
1038
|
+
try:
|
|
1039
|
+
return isinstance(text, str) and bool(re.fullmatch(r"\d{4}-\d{2}-\d{2}", text)) \
|
|
1040
|
+
and bool(datetime.strptime(text, "%Y-%m-%d"))
|
|
1041
|
+
except ValueError:
|
|
1042
|
+
return False
|
|
1043
|
+
|
|
1044
|
+
|
|
1045
|
+
def price_problems(table):
|
|
1046
|
+
"""What makes a price table one polyctl cannot quote from, as sentences; [] when it can (USD-COST).
|
|
1047
|
+
|
|
1048
|
+
One mistake can price every row wrong - a price in cents, a kind misspelt and so never
|
|
1049
|
+
charged, one id under two vendors - so a table holding any is used for nothing at all.
|
|
1050
|
+
"""
|
|
1051
|
+
if not isinstance(table, dict):
|
|
1052
|
+
return ["the price table is not a JSON object"]
|
|
1053
|
+
problems = []
|
|
1054
|
+
version = table.get("version")
|
|
1055
|
+
if not isinstance(version, int) or isinstance(version, bool) or version < 1:
|
|
1056
|
+
problems.append("`version` must be a whole number from 1, raised whenever a price changes")
|
|
1057
|
+
if table.get("currency") != "USD":
|
|
1058
|
+
problems.append("`currency` must be USD: `polyctl cost --usd` estimates US dollars")
|
|
1059
|
+
if not _price(table.get("per_tokens")) or not table.get("per_tokens"):
|
|
1060
|
+
problems.append("`per_tokens` must be how many tokens each price is for")
|
|
1061
|
+
kinds = table.get("kinds")
|
|
1062
|
+
if not isinstance(kinds, dict) or not kinds or not all(isinstance(text, str) and text.strip()
|
|
1063
|
+
for text in kinds.values()):
|
|
1064
|
+
problems.append("`kinds` must name each kind of token a price is for, with what it is")
|
|
1065
|
+
kinds = {}
|
|
1066
|
+
vendors = table.get("vendors")
|
|
1067
|
+
if not isinstance(vendors, dict) or not vendors:
|
|
1068
|
+
return problems + ["`vendors` must hold the vendors whose prices the table lists"]
|
|
1069
|
+
seen = {}
|
|
1070
|
+
for vendor, block in vendors.items():
|
|
1071
|
+
if not isinstance(block, dict):
|
|
1072
|
+
problems.append(f"vendor {vendor} is not an object")
|
|
1073
|
+
continue
|
|
1074
|
+
if not _day(block.get("as_of")):
|
|
1075
|
+
problems.append(f"vendor {vendor}: `as_of` must be the day its prices were read, as YYYY-MM-DD")
|
|
1076
|
+
if not isinstance(block.get("source"), str) or not block["source"].strip():
|
|
1077
|
+
problems.append(f"vendor {vendor}: `source` must say where its prices were read")
|
|
1078
|
+
models = block.get("models")
|
|
1079
|
+
if not isinstance(models, dict) or not models:
|
|
1080
|
+
problems.append(f"vendor {vendor}: `models` must list the models it prices")
|
|
1081
|
+
continue
|
|
1082
|
+
for model, entry in models.items():
|
|
1083
|
+
if not isinstance(entry, dict):
|
|
1084
|
+
problems.append(f"{model}: its prices are not an object")
|
|
1085
|
+
continue
|
|
1086
|
+
ids = entry.get("ids", [])
|
|
1087
|
+
if not isinstance(ids, list) or not all(isinstance(ident, str) and ident.strip() for ident in ids):
|
|
1088
|
+
problems.append(f"{model}: `ids` must list the other ids it is written as")
|
|
1089
|
+
ids = []
|
|
1090
|
+
strays = sorted(set(entry) - set(kinds) - {"ids", "note"})
|
|
1091
|
+
if strays:
|
|
1092
|
+
problems.append(f"{model}: {', '.join(strays)} is no kind of token `kinds` names")
|
|
1093
|
+
problems += [f"{model}: `{kind}` must be a price of zero or more" for kind in kinds
|
|
1094
|
+
if kind in entry and not _price(entry[kind])]
|
|
1095
|
+
if not any(kind in entry for kind in kinds):
|
|
1096
|
+
problems.append(f"{model}: it prices no kind of token")
|
|
1097
|
+
for ident in [model] + ids:
|
|
1098
|
+
if ident in seen:
|
|
1099
|
+
problems.append(f"{ident} is priced twice, under {seen[ident]} and {vendor}")
|
|
1100
|
+
seen[ident] = vendor
|
|
1101
|
+
return problems
|
|
1102
|
+
|
|
1103
|
+
|
|
1104
|
+
def price_table(path=None):
|
|
1105
|
+
"""(the price table, its problems): the one polyctl ships unless `path` names another; None when it has any."""
|
|
1106
|
+
try:
|
|
1107
|
+
with open(path or PRICES_FILE, encoding=UTF8) as fh:
|
|
1108
|
+
table = json.load(fh)
|
|
1109
|
+
except (OSError, ValueError) as exc:
|
|
1110
|
+
return None, [f"the price table could not be read: {exc}"]
|
|
1111
|
+
problems = price_problems(table)
|
|
1112
|
+
return (None if problems else table), problems
|
|
1113
|
+
|
|
1114
|
+
|
|
1115
|
+
def usd_estimate(tokens, table):
|
|
1116
|
+
"""Tokens by model, rate and kind, priced from a sound price table: an estimate in US dollars (USD-COST).
|
|
1117
|
+
|
|
1118
|
+
`tokens` is what `turn_costs(by_model=True)` adds up. Each row is one model at one rate: its
|
|
1119
|
+
tokens by kind, and its dollars, or `usd` None and `why` they are unknown - the transcript
|
|
1120
|
+
names no model, the table does not list the model or gives no price for a kind of token it
|
|
1121
|
+
spent, or the rate is not the one the table lists (`rate` names the field that said so).
|
|
1122
|
+
Unknown is never zero: `total` is None when any row is unknown, and `priced` adds up the rows
|
|
1123
|
+
that are not, a floor under it. A model the table lists at zero is priced at zero, and only
|
|
1124
|
+
then is it free. `vendors` holds the as-of day and source of each vendor whose prices a row
|
|
1125
|
+
used, for the label.
|
|
1126
|
+
"""
|
|
1127
|
+
listed = {ident: (vendor, entry) for vendor, block in table["vendors"].items()
|
|
1128
|
+
for model, entry in block["models"].items() for ident in [model] + entry.get("ids", [])}
|
|
1129
|
+
rows = {}
|
|
1130
|
+
for (model, rate, kind), count in tokens.items():
|
|
1131
|
+
if count:
|
|
1132
|
+
row = rows.setdefault((model, rate), {"model": model, "rate": rate, "tokens": {}})
|
|
1133
|
+
row["tokens"][kind] = row["tokens"].get(kind, 0) + count
|
|
1134
|
+
out = {"version": table["version"], "rows": [], "priced": 0.0, "total": None, "vendors": {}}
|
|
1135
|
+
for model, rate in sorted(rows, key=lambda pair: (pair[0] is None, pair[0] or "", pair[1] or "")):
|
|
1136
|
+
row = rows[(model, rate)]
|
|
1137
|
+
vendor, entry = listed.get(model, (None, {}))
|
|
1138
|
+
unpriced = sorted(kind for kind in row["tokens"] if kind not in table["kinds"] or kind not in entry)
|
|
1139
|
+
if rate is not None:
|
|
1140
|
+
row["why"] = "a rate the table does not price"
|
|
1141
|
+
elif model is None:
|
|
1142
|
+
row["why"] = "the transcript names no model"
|
|
1143
|
+
elif vendor is None:
|
|
1144
|
+
row["why"] = "a model the table does not price"
|
|
1145
|
+
elif unpriced:
|
|
1146
|
+
row["why"] = f"the table gives it no price for {', '.join(unpriced)}"
|
|
1147
|
+
else:
|
|
1148
|
+
row["why"] = None
|
|
1149
|
+
row["usd"] = None if row["why"] else \
|
|
1150
|
+
sum(count * entry[kind] for kind, count in row["tokens"].items()) / table["per_tokens"]
|
|
1151
|
+
if row["usd"] is not None:
|
|
1152
|
+
out["priced"] += row["usd"]
|
|
1153
|
+
out["vendors"][vendor] = {field: table["vendors"][vendor][field] for field in ("as_of", "source")}
|
|
1154
|
+
out["rows"].append(row)
|
|
1155
|
+
out["total"] = out["priced"] if all(row["usd"] is not None for row in out["rows"]) else None
|
|
1156
|
+
return out
|
|
1157
|
+
|
|
1158
|
+
|
|
1159
|
+
# ---- ids: a clock reading names one record, even where the clock is coarse (#71) --------
|
|
1160
|
+
|
|
1161
|
+
_ID_CLOCK = {}
|
|
1162
|
+
|
|
1163
|
+
|
|
1164
|
+
def _unique_clock(unit):
|
|
1165
|
+
"""Nanoseconds since the epoch in whole `unit`s, never the same value twice in this process (#71).
|
|
1166
|
+
|
|
1167
|
+
Windows advanced the clock about every 15.6 ms before Python 3.13, so every id
|
|
1168
|
+
minted within one tick - two notices in one watchdog cycle, two merge checks, two
|
|
1169
|
+
grants - was one id. A repeat takes the next value up: an id keeps its shape and
|
|
1170
|
+
still sorts by the time it was minted. Two processes can still read one tick; where
|
|
1171
|
+
a shared id would overwrite a record, the store claims it (a review's state file is
|
|
1172
|
+
created exclusively), and two ledger rows that share one stay two rows.
|
|
1173
|
+
"""
|
|
1174
|
+
import threading
|
|
1175
|
+
with _ID_CLOCK.setdefault("lock", threading.Lock()): # the first lock stored is the one used
|
|
1176
|
+
value = max(time.time_ns() // unit, _ID_CLOCK.get(unit, 0) + 1)
|
|
1177
|
+
_ID_CLOCK[unit] = value
|
|
1178
|
+
return value
|
|
1179
|
+
|
|
1180
|
+
|
|
1181
|
+
def unique_ms():
|
|
1182
|
+
"""Milliseconds since the epoch for an id: a notice, a submitted review, a merge check."""
|
|
1183
|
+
return _unique_clock(1_000_000)
|
|
1184
|
+
|
|
1185
|
+
|
|
1186
|
+
def unique_ns():
|
|
1187
|
+
"""Nanoseconds since the epoch for an id: a commit grant's token."""
|
|
1188
|
+
return _unique_clock(1)
|
|
1189
|
+
|
|
1190
|
+
|
|
1191
|
+
# ---- deferred work: what could not run, so it can run later ----------------------
|
|
1192
|
+
#
|
|
1193
|
+
# A quota window closing must not lose anything. Every action polyctl could not take
|
|
1194
|
+
# — a nudge, a wake, a review — is written down with why, and `polyctl catchup`
|
|
1195
|
+
# replays the queue when the way is clear. This is the "bypass now, reconcile
|
|
1196
|
+
# later" the human asked for: the run degrades, it never forgets.
|
|
1197
|
+
|
|
1198
|
+
def _deferred_write(root, row):
|
|
1199
|
+
"""One row of the deferred queue, appended under its lock and synced before it returns (JOURNAL-4)."""
|
|
1200
|
+
from .storage import append_jsonl
|
|
1201
|
+
try:
|
|
1202
|
+
os.makedirs(os.path.join(root, ".polyctl", "ledger"), exist_ok=True)
|
|
1203
|
+
append_jsonl(os.path.join(root, ".polyctl", "ledger", "deferred.jsonl"), row)
|
|
1204
|
+
except OSError:
|
|
1205
|
+
pass
|
|
1206
|
+
|
|
1207
|
+
|
|
1208
|
+
def deferred_append(root, kind, **fields):
|
|
1209
|
+
"""Defer one kind of work; an open deferral of that kind is the one that stands (#87).
|
|
1210
|
+
|
|
1211
|
+
A wake is state, not a queue of attempts: fourteen deferred wakes piled up over
|
|
1212
|
+
one outage and replayed in a burst when it ended. A later end the work waits for
|
|
1213
|
+
moves the standing one's: it was dropped, and the queue kept the first (JOURNAL-4).
|
|
1214
|
+
"""
|
|
1215
|
+
standing = next((row for row in deferred_open(root) if row.get("kind") == kind), None)
|
|
1216
|
+
if standing:
|
|
1217
|
+
until = fields.get("until")
|
|
1218
|
+
if isinstance(until, (int, float)) and until > float(standing.get("until") or 0):
|
|
1219
|
+
_deferred_write(root, {"event": "until", "id": standing["id"], "until": until, "at": int(time.time())})
|
|
1220
|
+
standing = dict(standing, until=until)
|
|
1221
|
+
return standing
|
|
1222
|
+
now = time.time()
|
|
1223
|
+
rec = {"event": "deferred", "id": f"DF-{int(now)}-{kind}", "kind": kind, "at": now}
|
|
1224
|
+
rec.update(fields)
|
|
1225
|
+
_deferred_write(root, rec)
|
|
1226
|
+
return rec
|
|
1227
|
+
|
|
1228
|
+
|
|
1229
|
+
def deferred_close(root, did, outcome="done"):
|
|
1230
|
+
_deferred_write(root, {"event": "closed", "id": did, "at": int(time.time()), "outcome": outcome})
|
|
1231
|
+
|
|
1232
|
+
|
|
1233
|
+
|
|
1234
|
+
def deferred_open(root):
|
|
1235
|
+
p = os.path.join(root, ".polyctl", "ledger", "deferred.jsonl")
|
|
1236
|
+
if not os.path.exists(p):
|
|
1237
|
+
return []
|
|
1238
|
+
rows, closed = {}, set()
|
|
1239
|
+
for line in open(p, errors="replace", encoding=UTF8):
|
|
1240
|
+
try:
|
|
1241
|
+
r = json.loads(line)
|
|
1242
|
+
except ValueError:
|
|
1243
|
+
continue
|
|
1244
|
+
if r.get("event") == "deferred":
|
|
1245
|
+
rows[r["id"]] = r
|
|
1246
|
+
elif r.get("event") == "until" and r.get("id") in rows:
|
|
1247
|
+
rows[r["id"]] = dict(rows[r["id"]], until=r.get("until"))
|
|
1248
|
+
elif r.get("event") == "closed":
|
|
1249
|
+
closed.add(r["id"])
|
|
1250
|
+
return [r for i, r in rows.items() if i not in closed]
|
|
1251
|
+
|
|
1252
|
+
|
|
1253
|
+
def recently_deferred(root, kind, within=3600):
|
|
1254
|
+
cut = time.time() - within
|
|
1255
|
+
return any(r["kind"] == kind and r["at"] >= cut for r in deferred_open(root))
|
|
1256
|
+
|
|
1257
|
+
|
|
1258
|
+
# ---- waivers: the human's bypass, on the record ---------------------------------
|
|
1259
|
+
|
|
1260
|
+
WAIVER_CHAIN = "polyctl-waiver-row-v1"
|
|
1261
|
+
WAIVER_HOURS_DEFAULT = settings.default("waivers.default_hours")
|
|
1262
|
+
WAIVER_HOURS_MAX = settings.default("waivers.max_hours")
|
|
1263
|
+
|
|
1264
|
+
|
|
1265
|
+
def waivers_path(root):
|
|
1266
|
+
return os.path.join(root, ".polyctl", "ledger", "waivers.jsonl")
|
|
1267
|
+
|
|
1268
|
+
|
|
1269
|
+
def waiver_rows(root):
|
|
1270
|
+
"""Every waiver row once the chain validates (#67).
|
|
1271
|
+
|
|
1272
|
+
Rows written before the ledger was chained may stand first. An unlinked row
|
|
1273
|
+
after them, or a broken link, makes the ledger unreadable, and every reader
|
|
1274
|
+
fails closed.
|
|
1275
|
+
"""
|
|
1276
|
+
from .storage import read_chained_jsonl
|
|
1277
|
+
return read_chained_jsonl(waivers_path(root), WAIVER_CHAIN, legacy_prefix=True)
|
|
1278
|
+
|
|
1279
|
+
|
|
1280
|
+
def _login_and_terminal():
|
|
1281
|
+
"""The login a command ran under and whether a terminal was attached."""
|
|
1282
|
+
try:
|
|
1283
|
+
import getpass
|
|
1284
|
+
user = getpass.getuser()
|
|
1285
|
+
except Exception:
|
|
1286
|
+
user = None
|
|
1287
|
+
try:
|
|
1288
|
+
interactive = os.isatty(0)
|
|
1289
|
+
except OSError:
|
|
1290
|
+
interactive = False
|
|
1291
|
+
return user, bool(interactive)
|
|
1292
|
+
|
|
1293
|
+
|
|
1294
|
+
def _normalize_waived_gates(gates):
|
|
1295
|
+
"""A deduplicated list of gate names a `gates` waiver covers, or None when it covers every gate of the profile."""
|
|
1296
|
+
if gates is None:
|
|
1297
|
+
return None
|
|
1298
|
+
parts = gates.split(",") if isinstance(gates, str) else list(gates)
|
|
1299
|
+
named = list(dict.fromkeys(str(part).strip() for part in parts if str(part).strip()))
|
|
1300
|
+
if not named or not all(re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._:-]{0,63}", name) for name in named):
|
|
1301
|
+
raise ValueError("--gates names one or more gates separated by commas (for example: focused,lint)")
|
|
1302
|
+
return named
|
|
1303
|
+
|
|
1304
|
+
|
|
1305
|
+
def waive(root, gate, slice_id, why, by, hours=WAIVER_HOURS_DEFAULT, gates=None):
|
|
1306
|
+
"""Record that a person waived a gate for one slice, for a bounded time (#67).
|
|
1307
|
+
|
|
1308
|
+
A chained append like an authority row. It carries an expiry, the name the
|
|
1309
|
+
person gave, and beside it what polyctl can check: the login and whether a terminal
|
|
1310
|
+
was attached. Only gates `polyctl commit-ok` actually checks (`review` and `gates`)
|
|
1311
|
+
may be waived; `inventory` is refused rather than recorded and ignored (WAIVE-GATES).
|
|
1312
|
+
"""
|
|
1313
|
+
from .storage import append_chained_jsonl
|
|
1314
|
+
if gate == "inventory":
|
|
1315
|
+
raise ValueError("`inventory` is not a gate `polyctl commit-ok` checks; nothing reads an inventory waiver")
|
|
1316
|
+
if gate not in ("review", "gates"):
|
|
1317
|
+
raise ValueError(f"unknown gate {gate!r}: choose review or gates")
|
|
1318
|
+
if gates is not None and gate != "gates":
|
|
1319
|
+
raise ValueError(f"--gates applies only to `polyctl waive gates`, not `{gate}`")
|
|
1320
|
+
named_gates = _normalize_waived_gates(gates) if gate == "gates" else None
|
|
1321
|
+
now = int(time.time())
|
|
1322
|
+
taken = {row.get("id") for row in waiver_rows(root) if isinstance(row, dict)}
|
|
1323
|
+
wid, n = f"W-{now}", 2
|
|
1324
|
+
while wid in taken:
|
|
1325
|
+
wid, n = f"W-{now}-{n}", n + 1
|
|
1326
|
+
user, interactive = _login_and_terminal()
|
|
1327
|
+
record = {"event": "waived", "id": wid, "gate": gate, "slice": slice_id, "why": why,
|
|
1328
|
+
"by": by, "at": now, "expires": now + int(float(hours) * 3600),
|
|
1329
|
+
"user": user, "interactive": interactive,
|
|
1330
|
+
"head": _git_text(root, "rev-parse", "HEAD"), "tree": tree_digest(root)}
|
|
1331
|
+
if named_gates:
|
|
1332
|
+
record["gates"] = named_gates
|
|
1333
|
+
return append_chained_jsonl(waivers_path(root), record, WAIVER_CHAIN, legacy_prefix=True)
|
|
1334
|
+
|
|
1335
|
+
|
|
1336
|
+
def close_waiver(root, wid, outcome, evidence=None):
|
|
1337
|
+
"""Retire a waiver with a durable chained append; a failure raises rather than leaving it open unseen (#67).
|
|
1338
|
+
|
|
1339
|
+
`evidence` is what a close stood on when no review decided it: a move proof, and what it read (#44).
|
|
1340
|
+
"""
|
|
1341
|
+
from .storage import append_chained_jsonl
|
|
1342
|
+
row = {"event": "closed", "id": wid, "at": int(time.time()), "outcome": outcome}
|
|
1343
|
+
if evidence is not None:
|
|
1344
|
+
row["evidence"] = evidence
|
|
1345
|
+
return append_chained_jsonl(waivers_path(root), row, WAIVER_CHAIN, legacy_prefix=True)
|
|
1346
|
+
|
|
1347
|
+
|
|
1348
|
+
def fail_waiver(root, wid, detail):
|
|
1349
|
+
"""Record that catch-up failed to close a waiver, so doctor and status say catchup fails on it (LOWS-0.7)."""
|
|
1350
|
+
from .storage import append_chained_jsonl
|
|
1351
|
+
latest = None
|
|
1352
|
+
for r in waiver_rows(root):
|
|
1353
|
+
if isinstance(r, dict) and r.get("id") == wid and r.get("event") in ("waived", "failed", "closed"):
|
|
1354
|
+
latest = r
|
|
1355
|
+
if latest and latest.get("event") == "failed" and latest.get("detail") == detail:
|
|
1356
|
+
return latest
|
|
1357
|
+
row = {"event": "failed", "id": wid, "at": int(time.time()), "detail": detail}
|
|
1358
|
+
return append_chained_jsonl(waivers_path(root), row, WAIVER_CHAIN, legacy_prefix=True)
|
|
1359
|
+
|
|
1360
|
+
|
|
1361
|
+
# ---- opt-ins: a person weakens a guarantee, on the record (REVIEW-TIERS) -----------------
|
|
1362
|
+
|
|
1363
|
+
OPT_IN_CHAIN = "polyctl-opt-in-row-v1"
|
|
1364
|
+
|
|
1365
|
+
|
|
1366
|
+
def opt_ins_path(root):
|
|
1367
|
+
return os.path.join(root, ".polyctl", "ledger", "opt-ins.jsonl")
|
|
1368
|
+
|
|
1369
|
+
|
|
1370
|
+
def record_opt_in(root, setting, value, by):
|
|
1371
|
+
"""Record that a person set or cleared a setting that weakens a guarantee (settings.RECORDED).
|
|
1372
|
+
|
|
1373
|
+
A chained append like a waiver: the value, the name the person gave, and beside it
|
|
1374
|
+
what polyctl can check - the login and whether a terminal was attached. A value of None
|
|
1375
|
+
is the setting cleared.
|
|
1376
|
+
"""
|
|
1377
|
+
from .storage import append_chained_in_tree
|
|
1378
|
+
user, interactive = _login_and_terminal()
|
|
1379
|
+
row = {"at": int(time.time()), "setting": setting, "value": value, "by": by,
|
|
1380
|
+
"user": user, "interactive": interactive}
|
|
1381
|
+
return append_chained_in_tree(root, ".polyctl/ledger/opt-ins.jsonl", row, OPT_IN_CHAIN)
|
|
1382
|
+
|
|
1383
|
+
|
|
1384
|
+
def recorded_opt_in(root, setting):
|
|
1385
|
+
"""The newest recorded row for one setting, or None; raises when the ledger cannot be read."""
|
|
1386
|
+
from .storage import read_chained_in_tree
|
|
1387
|
+
rows = [row for row in read_chained_in_tree(root, ".polyctl/ledger/opt-ins.jsonl", OPT_IN_CHAIN)
|
|
1388
|
+
if isinstance(row, dict) and row.get("setting") == setting]
|
|
1389
|
+
return rows[-1] if rows else None
|
|
1390
|
+
|
|
1391
|
+
|
|
1392
|
+
def open_waivers(root, gate=None, slice_id=None):
|
|
1393
|
+
rows, closed = {}, set()
|
|
1394
|
+
for r in waiver_rows(root):
|
|
1395
|
+
if not isinstance(r, dict):
|
|
1396
|
+
continue
|
|
1397
|
+
if r.get("event") == "waived" and r.get("id"):
|
|
1398
|
+
rows[r["id"]] = r
|
|
1399
|
+
elif r.get("event") == "closed":
|
|
1400
|
+
closed.add(r.get("id"))
|
|
1401
|
+
out = [r for i, r in rows.items() if i not in closed]
|
|
1402
|
+
if gate:
|
|
1403
|
+
out = [r for r in out if r.get("gate") == gate]
|
|
1404
|
+
if slice_id:
|
|
1405
|
+
out = [r for r in out if r.get("slice") in (slice_id, "*")]
|
|
1406
|
+
return out
|
|
1407
|
+
|
|
1408
|
+
|
|
1409
|
+
def _waiver_candidates(root):
|
|
1410
|
+
"""Candidate digests each waiver has already authorised, from the grants that used it.
|
|
1411
|
+
|
|
1412
|
+
Every grant, the sealed ones too: read from the live rows, a waiver whose grant a seal retired
|
|
1413
|
+
looked unused and stood in for the review of other bytes (the review of BOUNDED-STORES,
|
|
1414
|
+
LEDGER-HISTORY). Both `waiver` and `gates_waiver` bind the waiver they name to the grant's
|
|
1415
|
+
candidate (WAIVE-GATES).
|
|
1416
|
+
"""
|
|
1417
|
+
bound = {}
|
|
1418
|
+
for row in authority_history(root):
|
|
1419
|
+
if not isinstance(row, dict) or row.get("granted") is not True:
|
|
1420
|
+
continue
|
|
1421
|
+
digest = (row.get("candidate") or {}).get("digest")
|
|
1422
|
+
for key in ("waiver", "gates_waiver"):
|
|
1423
|
+
if row.get(key):
|
|
1424
|
+
bound.setdefault(row[key], set()).add(digest)
|
|
1425
|
+
return bound
|
|
1426
|
+
|
|
1427
|
+
|
|
1428
|
+
def _matching_waiver_for(root, gate, running, candidate_digest, failed_gates=None, now=None, wanted=None):
|
|
1429
|
+
"""The open waiver for `gate` that may stand in for this candidate, and why others may not (#67, WAIVE-GATES)."""
|
|
1430
|
+
now = time.time() if now is None else now
|
|
1431
|
+
# The whole authority history is read only for a waiver that could stand in: `polyctl commit-ok` asks every time.
|
|
1432
|
+
bound = None
|
|
1433
|
+
notes = []
|
|
1434
|
+
for waiver in reversed(open_waivers(root, gate=gate)):
|
|
1435
|
+
wid, slice_id = waiver.get("id"), waiver.get("slice")
|
|
1436
|
+
if wanted is not None and wid != wanted:
|
|
1437
|
+
continue
|
|
1438
|
+
if slice_id not in running:
|
|
1439
|
+
if slice_id == "*":
|
|
1440
|
+
notes.append(f"waiver {wid} names every slice; a waiver covers one")
|
|
1441
|
+
continue
|
|
1442
|
+
expires = waiver.get("expires")
|
|
1443
|
+
if not isinstance(expires, (int, float)) or isinstance(expires, bool):
|
|
1444
|
+
notes.append(f"waiver {wid} for {slice_id} predates waiver expiry; a person opens a new one")
|
|
1445
|
+
continue
|
|
1446
|
+
if expires <= now:
|
|
1447
|
+
notes.append(f"waiver {wid} for {slice_id} expired "
|
|
1448
|
+
f"{time.strftime('%d %b %H:%M', time.localtime(expires))}")
|
|
1449
|
+
continue
|
|
1450
|
+
if gate == "gates" and failed_gates is not None:
|
|
1451
|
+
named = waiver.get("gates")
|
|
1452
|
+
if isinstance(named, list) and named:
|
|
1453
|
+
unwaived = [name for name in failed_gates if name not in named]
|
|
1454
|
+
if unwaived:
|
|
1455
|
+
notes.append(f"waiver {wid} covers {', '.join(named)}, not {', '.join(unwaived)}")
|
|
1456
|
+
continue
|
|
1457
|
+
bound = _waiver_candidates(root) if bound is None else bound
|
|
1458
|
+
used = bound.get(wid, set())
|
|
1459
|
+
if used and candidate_digest not in used:
|
|
1460
|
+
notes.append(f"waiver {wid} already authorised other bytes; it covers one candidate")
|
|
1461
|
+
continue
|
|
1462
|
+
return waiver, notes
|
|
1463
|
+
return None, notes
|
|
1464
|
+
|
|
1465
|
+
|
|
1466
|
+
def review_waiver_for(root, running, candidate_digest, now=None, wanted=None):
|
|
1467
|
+
"""The review waiver that may stand in for a review of this candidate, and why others may not (#67).
|
|
1468
|
+
|
|
1469
|
+
It names a running slice exactly, has not expired, and has authorised no other
|
|
1470
|
+
candidate. A waiver for every slice, one from before waivers expired, and one
|
|
1471
|
+
already spent on other bytes stand in for nothing. With `wanted`, only that waiver
|
|
1472
|
+
is asked: a grant is checked against the waiver it stood on, and a second one opened
|
|
1473
|
+
for the same slice since read as a different waiver and refused it (WAIVER-BOUND-2).
|
|
1474
|
+
"""
|
|
1475
|
+
return _matching_waiver_for(root, "review", running, candidate_digest, now=now, wanted=wanted)
|
|
1476
|
+
|
|
1477
|
+
|
|
1478
|
+
def verification_waivable_gates(root, ver):
|
|
1479
|
+
"""(failed gate names, None) when `ver` ran every gate of its profile and failed only declared gates,
|
|
1480
|
+
or (None, why a gates waiver cannot stand in for `ver`) (WAIVE-GATES)."""
|
|
1481
|
+
if not isinstance(ver, dict):
|
|
1482
|
+
return None, "no verification record"
|
|
1483
|
+
gates = [g for g in (ver.get("gates") or []) if isinstance(g, dict)]
|
|
1484
|
+
if not gates:
|
|
1485
|
+
return None, f"{ver.get('id') or 'verification'} recorded no gate results"
|
|
1486
|
+
synthetic = [g.get("name") for g in gates
|
|
1487
|
+
if g.get("name") in ("candidate-isolation", "candidate-integrity", "plan-integrity")]
|
|
1488
|
+
if synthetic:
|
|
1489
|
+
return None, f"{ver.get('id') or 'verification'} did not run every gate of the profile ({', '.join(synthetic)})"
|
|
1490
|
+
ran = [g.get("name") for g in gates]
|
|
1491
|
+
if not all(isinstance(name, str) and name for name in ran):
|
|
1492
|
+
return None, f"{ver.get('id') or 'verification'} has an unnamed gate entry"
|
|
1493
|
+
gates_file = os.path.join(root, ".polyctl", "gates.json")
|
|
1494
|
+
try:
|
|
1495
|
+
with open(gates_file, encoding=UTF8) as fh:
|
|
1496
|
+
spec = json.load(fh)
|
|
1497
|
+
except (OSError, ValueError) as exc:
|
|
1498
|
+
return None, f"cannot read .polyctl/gates.json to verify the profile's gates: {exc}"
|
|
1499
|
+
profiles = (spec.get("profiles") if isinstance(spec, dict) else None) or {}
|
|
1500
|
+
profile = ver.get("profile")
|
|
1501
|
+
profile_gates = profiles.get(profile) if isinstance(profiles, dict) else None
|
|
1502
|
+
if not isinstance(profile_gates, list) or not profile_gates:
|
|
1503
|
+
return None, f"{ver.get('id') or 'verification'} did not run a declared gate profile ({profile})"
|
|
1504
|
+
missing = [name for name in profile_gates if name not in ran]
|
|
1505
|
+
if missing:
|
|
1506
|
+
return None, (f"{ver.get('id') or 'verification'} did not run every gate of profile {profile}: "
|
|
1507
|
+
f"missing {', '.join(missing)}")
|
|
1508
|
+
outside = [g.get("name") for g in gates if not g.get("passed") and g.get("name") not in profile_gates]
|
|
1509
|
+
if outside:
|
|
1510
|
+
return None, (f"{ver.get('id') or 'verification'} failed outside profile {profile}: "
|
|
1511
|
+
f"{', '.join(outside)}")
|
|
1512
|
+
failed = [g.get("name") for g in gates if not g.get("passed")]
|
|
1513
|
+
if not failed:
|
|
1514
|
+
return None, None
|
|
1515
|
+
return failed, None
|
|
1516
|
+
|
|
1517
|
+
|
|
1518
|
+
def gates_waiver_for(root, running, candidate_digest, failed_gates=None, now=None, wanted=None):
|
|
1519
|
+
"""The gates waiver that may stand in for the failed gates of this candidate's verification, and why others
|
|
1520
|
+
may not (WAIVE-GATES)."""
|
|
1521
|
+
return _matching_waiver_for(root, "gates", running, candidate_digest, failed_gates=failed_gates,
|
|
1522
|
+
now=now, wanted=wanted)
|
|
1523
|
+
|
|
1524
|
+
|
|
1525
|
+
def open_waiver_report(root, now=None):
|
|
1526
|
+
"""One line per open waiver with its age and expiry, for `polyctl doctor` and `polyctl status` (#67, WAIVE-GATES)."""
|
|
1527
|
+
now = time.time() if now is None else now
|
|
1528
|
+
failed = {}
|
|
1529
|
+
for r in waiver_rows(root):
|
|
1530
|
+
if not isinstance(r, dict) or not r.get("id"):
|
|
1531
|
+
continue
|
|
1532
|
+
if r.get("event") == "failed":
|
|
1533
|
+
failed[r["id"]] = r.get("detail")
|
|
1534
|
+
elif r.get("event") in ("waived", "closed"):
|
|
1535
|
+
failed.pop(r["id"], None)
|
|
1536
|
+
lines = []
|
|
1537
|
+
for waiver in open_waivers(root):
|
|
1538
|
+
wid = waiver.get("id")
|
|
1539
|
+
age = max(0, int(now - (waiver.get("at") or now)))
|
|
1540
|
+
expires = waiver.get("expires")
|
|
1541
|
+
state = ("no expiry (legacy)" if not isinstance(expires, (int, float))
|
|
1542
|
+
else "expired" if expires <= now
|
|
1543
|
+
else f"expires in {int((expires - now) // 3600)}h")
|
|
1544
|
+
if wid in failed:
|
|
1545
|
+
why = failed[wid]
|
|
1546
|
+
state += f", catchup fails on it ({why})" if why else ", catchup fails on it"
|
|
1547
|
+
named = waiver.get("gates")
|
|
1548
|
+
gate_label = (f"{waiver.get('gate')} ({', '.join(named)})"
|
|
1549
|
+
if waiver.get("gate") == "gates" and isinstance(named, list) and named
|
|
1550
|
+
else waiver.get("gate"))
|
|
1551
|
+
lines.append(f"{wid} {gate_label} for {waiver.get('slice')}, "
|
|
1552
|
+
f"open {age // 86400}d {age % 86400 // 3600}h, {state}, by {waiver.get('by')}")
|
|
1553
|
+
return lines
|
|
1554
|
+
|
|
1555
|
+
|
|
1556
|
+
# How long before a waiver was opened a commit landed under it may say it was committed: a clock
|
|
1557
|
+
# that disagreed, on this machine or on the one the commit was made on (CATCHUP-POLISH).
|
|
1558
|
+
WAIVER_CLOCK_ALLOWANCE = 86400
|
|
1559
|
+
|
|
1560
|
+
|
|
1561
|
+
def _waiver_history(root, waiver, grants):
|
|
1562
|
+
"""The `git log` revisions that hold the commit a bounded waiver's grant landed, or None (CATCHUP-POLISH).
|
|
1563
|
+
|
|
1564
|
+
The newest 500 commits were searched, and a repository that lands dozens of commits a day
|
|
1565
|
+
would soon have called every older waiver UNRESOLVED. The commit that lands a granted tree
|
|
1566
|
+
descends from the head the grant was built on, so the search runs from the first recorded
|
|
1567
|
+
head git still has on HEAD's line, whatever came before it. A head comes from a ledger
|
|
1568
|
+
anyone on the machine can edit, so it must be a full object id; a history rewritten since
|
|
1569
|
+
can have left it off that line, and then the waiver's own date bounds the walk: git stops
|
|
1570
|
+
walking where the commits grow older than that. With neither, nothing is searched: the
|
|
1571
|
+
whole history of a long-lived repository is no bound.
|
|
1572
|
+
"""
|
|
1573
|
+
seen = set()
|
|
1574
|
+
for row in grants:
|
|
1575
|
+
head = str((row.get("candidate") or {}).get("head") or "")
|
|
1576
|
+
if head in seen or not _OBJECT_ID.fullmatch(head):
|
|
1577
|
+
continue
|
|
1578
|
+
seen.add(head)
|
|
1579
|
+
try:
|
|
1580
|
+
ancestor = subprocess.run(
|
|
1581
|
+
[git_binary(), "merge-base", "--is-ancestor", head, "HEAD"], cwd=root,
|
|
1582
|
+
stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=60,
|
|
1583
|
+
).returncode
|
|
1584
|
+
except (OSError, subprocess.TimeoutExpired):
|
|
1585
|
+
ancestor = 2
|
|
1586
|
+
if ancestor == 0:
|
|
1587
|
+
return ["--ancestry-path", f"{head}..HEAD"]
|
|
1588
|
+
at = waiver.get("at")
|
|
1589
|
+
if isinstance(at, (int, float)) and not isinstance(at, bool) and at > WAIVER_CLOCK_ALLOWANCE:
|
|
1590
|
+
return [f"--since=@{int(at) - WAIVER_CLOCK_ALLOWANCE}", "HEAD"]
|
|
1591
|
+
return None
|
|
1592
|
+
|
|
1593
|
+
|
|
1594
|
+
def _bound_waiver_target(root, waiver, grants):
|
|
1595
|
+
"""The one landed commit a bounded waiver covers, found by the tree granted under it (#17).
|
|
1596
|
+
|
|
1597
|
+
A waiver that nothing was granted under covers no commit; one whose granted tree
|
|
1598
|
+
never landed is UNRESOLVED rather than reviewed by guess. The newest grant of the
|
|
1599
|
+
tree that landed says who landed it, where it recorded that (#65), and the move
|
|
1600
|
+
proof it stood on, where it recorded one (#44). The commit is looked for where it can
|
|
1601
|
+
have landed, and it is the first there to carry a granted tree: a later commit of the
|
|
1602
|
+
same tree landed under another grant (CATCHUP-POLISH).
|
|
1603
|
+
"""
|
|
1604
|
+
trees = {(row.get("candidate") or {}).get("index_tree") for row in grants}
|
|
1605
|
+
item = {"waiver": waiver, "start": "", "end": "", "landed": 0,
|
|
1606
|
+
"newest": False, "problem": None, "unused": not trees, "author": None, "grant": None,
|
|
1607
|
+
"move_only": None, "expired": (waiver.get("expires") or 0) <= time.time()}
|
|
1608
|
+
if not trees:
|
|
1609
|
+
return item
|
|
1610
|
+
span = _waiver_history(root, waiver, grants)
|
|
1611
|
+
if span is None:
|
|
1612
|
+
item["problem"] = ("UNRESOLVED: no grant under it records a head on HEAD's line, and it records no date "
|
|
1613
|
+
"to search from")
|
|
1614
|
+
return item
|
|
1615
|
+
try:
|
|
1616
|
+
log = _git_output(root, "log", "--format=%H %T", *span, "--").decode("ascii")
|
|
1617
|
+
except (RuntimeError, UnicodeError):
|
|
1618
|
+
item["problem"] = "UNRESOLVED: git cannot list the landed commits"
|
|
1619
|
+
return item
|
|
1620
|
+
carried = [(parts[0], parts[1]) for parts in (line.split() for line in log.splitlines())
|
|
1621
|
+
if len(parts) == 2 and parts[1] in trees]
|
|
1622
|
+
if not carried:
|
|
1623
|
+
item["problem"] = "UNRESOLVED: no landed commit carries the tree granted under it"
|
|
1624
|
+
return item
|
|
1625
|
+
sha, tree = carried[-1] # git lists the newest first
|
|
1626
|
+
try:
|
|
1627
|
+
parent = _git_output(root, "rev-parse", "--verify", f"{sha}^").decode("ascii").strip()
|
|
1628
|
+
except (RuntimeError, UnicodeError):
|
|
1629
|
+
item["problem"] = "UNRESOLVED: its landed commit has no parent to review against"
|
|
1630
|
+
return item
|
|
1631
|
+
grant = next((row for row in reversed(grants) if (row.get("candidate") or {}).get("index_tree") == tree), {})
|
|
1632
|
+
waived_gates = grant.get("waived_gates") if isinstance(grant.get("waived_gates"), list) else None
|
|
1633
|
+
profile, gates_digest, vid = None, None, None
|
|
1634
|
+
if waiver.get("gate") == "gates":
|
|
1635
|
+
vid = grant.get("verification")
|
|
1636
|
+
if vid:
|
|
1637
|
+
try:
|
|
1638
|
+
ver = next((row for row in reversed(verification_history(root))
|
|
1639
|
+
if isinstance(row, dict) and row.get("id") == vid), None)
|
|
1640
|
+
except Exception:
|
|
1641
|
+
ver = None
|
|
1642
|
+
if isinstance(ver, dict):
|
|
1643
|
+
profile = ver.get("profile")
|
|
1644
|
+
gates_digest = ver.get("gates_digest")
|
|
1645
|
+
if waived_gates is None:
|
|
1646
|
+
waived_gates = [g.get("name") for g in (ver.get("gates") or [])
|
|
1647
|
+
if isinstance(g, dict) and not g.get("passed") and isinstance(g.get("name"), str)]
|
|
1648
|
+
if not waived_gates and isinstance(waiver.get("gates"), list):
|
|
1649
|
+
waived_gates = list(waiver["gates"])
|
|
1650
|
+
item.update(start=parent, end=sha, landed=1, grant=grant.get("token"),
|
|
1651
|
+
author=grant.get("author") if isinstance(grant.get("author"), dict) else None,
|
|
1652
|
+
move_only=grant.get("move_only") if isinstance(grant.get("move_only"), dict) else None,
|
|
1653
|
+
waived_gates=waived_gates, profile=profile, gates_digest=gates_digest, verification=vid)
|
|
1654
|
+
return item
|
|
1655
|
+
|
|
1656
|
+
|
|
1657
|
+
def _waiver_ranges_for_gate(root, gate):
|
|
1658
|
+
"""Each open waiver for `gate` with the commits that landed under it (#17, WAIVE-GATES)."""
|
|
1659
|
+
waived, closed = [], set()
|
|
1660
|
+
for r in waiver_rows(root):
|
|
1661
|
+
if not isinstance(r, dict):
|
|
1662
|
+
continue
|
|
1663
|
+
if r.get("event") == "waived" and r.get("gate") == gate:
|
|
1664
|
+
waived.append(r)
|
|
1665
|
+
elif r.get("event") == "closed":
|
|
1666
|
+
closed.add(r.get("id"))
|
|
1667
|
+
if not waived:
|
|
1668
|
+
return []
|
|
1669
|
+
granted = {}
|
|
1670
|
+
# A grant a seal retired is still the one its waiver stood in for: read from the live rows, the waiver
|
|
1671
|
+
# read as unused and catch-up closed it with no review (the review of BOUNDED-STORES, LEDGER-HISTORY).
|
|
1672
|
+
for row in authority_history(root):
|
|
1673
|
+
if not isinstance(row, dict) or row.get("granted") is not True:
|
|
1674
|
+
continue
|
|
1675
|
+
for key in ("waiver", "gates_waiver"):
|
|
1676
|
+
if row.get(key):
|
|
1677
|
+
granted.setdefault(row[key], []).append(row)
|
|
1678
|
+
try:
|
|
1679
|
+
current = _git_output(root, "rev-parse", "--verify", "HEAD").decode("ascii").strip()
|
|
1680
|
+
except (RuntimeError, UnicodeError):
|
|
1681
|
+
current = None
|
|
1682
|
+
out = []
|
|
1683
|
+
for i, w in enumerate(waived):
|
|
1684
|
+
if w.get("id") in closed:
|
|
1685
|
+
continue
|
|
1686
|
+
if "expires" in w:
|
|
1687
|
+
out.append(_bound_waiver_target(root, w, granted.get(w["id"], [])))
|
|
1688
|
+
continue
|
|
1689
|
+
later = waived[i + 1] if i + 1 < len(waived) else None
|
|
1690
|
+
start = str(w.get("head") or "")
|
|
1691
|
+
end = str(later.get("head") or "") if later else (current or "")
|
|
1692
|
+
item = {"waiver": w, "start": start, "end": end, "landed": 0,
|
|
1693
|
+
"newest": later is None, "problem": None, "author": None, "grant": None, "move_only": None}
|
|
1694
|
+
if not _OBJECT_ID.fullmatch(start):
|
|
1695
|
+
item["problem"] = "its recorded head is not a full object id"
|
|
1696
|
+
elif not _OBJECT_ID.fullmatch(end):
|
|
1697
|
+
item["problem"] = ("the next waiver's recorded head is not a full object id"
|
|
1698
|
+
if later else "HEAD cannot be resolved")
|
|
1699
|
+
else:
|
|
1700
|
+
try:
|
|
1701
|
+
ancestor = subprocess.run(
|
|
1702
|
+
[git_binary(), "merge-base", "--is-ancestor", start, end], cwd=root,
|
|
1703
|
+
stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=60,
|
|
1704
|
+
).returncode
|
|
1705
|
+
except (OSError, subprocess.TimeoutExpired):
|
|
1706
|
+
ancestor = 2
|
|
1707
|
+
if ancestor == 1:
|
|
1708
|
+
item["problem"] = "its head is not an ancestor of the range end; history was rewritten"
|
|
1709
|
+
elif ancestor:
|
|
1710
|
+
item["problem"] = "git cannot compare its head with the range end"
|
|
1711
|
+
else:
|
|
1712
|
+
try:
|
|
1713
|
+
item["landed"] = int(_git_output(root, "rev-list", "--count", f"{start}..{end}").strip() or 0)
|
|
1714
|
+
except (RuntimeError, ValueError):
|
|
1715
|
+
item["problem"] = "git cannot count the commits in its range"
|
|
1716
|
+
out.append(item)
|
|
1717
|
+
return out
|
|
1718
|
+
|
|
1719
|
+
|
|
1720
|
+
def review_waiver_ranges(root):
|
|
1721
|
+
"""Each open review waiver with the commits that landed while it was the newest."""
|
|
1722
|
+
return _waiver_ranges_for_gate(root, "review")
|
|
1723
|
+
|
|
1724
|
+
|
|
1725
|
+
def gates_waiver_ranges(root):
|
|
1726
|
+
"""Each open gates waiver with the landed commit granted under it (WAIVE-GATES)."""
|
|
1727
|
+
return _waiver_ranges_for_gate(root, "gates")
|
|
1728
|
+
|
|
1729
|
+
|
|
1730
|
+
def range_changed_lines(root, start, end):
|
|
1731
|
+
"""Lines a landed range adds and removes, as git counts them for its diff; None when git cannot say.
|
|
1732
|
+
|
|
1733
|
+
A binary file counts none. `polyctl catchup --plan` sizes a sitting of retrospective
|
|
1734
|
+
reviews from these before any reviewer is asked.
|
|
1735
|
+
"""
|
|
1736
|
+
try:
|
|
1737
|
+
out = _git_output(root, "diff", "--numstat", "--no-ext-diff", f"{start}..{end}", "--").decode(UTF8, "replace")
|
|
1738
|
+
except RuntimeError:
|
|
1739
|
+
return None
|
|
1740
|
+
total = 0
|
|
1741
|
+
for line in out.splitlines():
|
|
1742
|
+
added, _, rest = line.partition("\t")
|
|
1743
|
+
removed = rest.partition("\t")[0]
|
|
1744
|
+
if added.isdigit() and removed.isdigit():
|
|
1745
|
+
total += int(added) + int(removed)
|
|
1746
|
+
return total
|
|
1747
|
+
|
|
1748
|
+
|
|
1749
|
+
def range_unchanged(root, start, end):
|
|
1750
|
+
"""Whether a landed range ends on the tree it starts from: True, False, or None when git cannot say.
|
|
1751
|
+
|
|
1752
|
+
No net change is a fact about trees, not about the lines a diff counts: a binary file counts
|
|
1753
|
+
none, and a textconv driver that reads two versions alike, or a submodule set to `ignore =
|
|
1754
|
+
all`, shows a changed range as no diff at all (WAIVER-BOUND-3).
|
|
1755
|
+
"""
|
|
1756
|
+
try:
|
|
1757
|
+
trees = _git_output(root, "rev-parse", f"{start}^{{tree}}", f"{end}^{{tree}}").decode(UTF8, "replace").split()
|
|
1758
|
+
except RuntimeError:
|
|
1759
|
+
return None
|
|
1760
|
+
return trees[0] == trees[1] if len(trees) == 2 else None
|
|
1761
|
+
|
|
1762
|
+
|
|
1763
|
+
def range_move_proof(root, start, end):
|
|
1764
|
+
"""(moved, problems): `polyctl split-check`'s proof, taken on a landed range rather than a candidate (#44).
|
|
1765
|
+
|
|
1766
|
+
A move-only grant recorded that proof for the tree it granted. What landed is proven
|
|
1767
|
+
again, from the commit it landed on: a proof taken against another parent says nothing
|
|
1768
|
+
about this diff. The proof reads Python definitions only, so every other changed path is
|
|
1769
|
+
a problem too - a closure on the proof must cover the whole range. The commits come from
|
|
1770
|
+
ledgers anyone on the machine can edit, so each must be a full object id.
|
|
1771
|
+
"""
|
|
1772
|
+
if not (_OBJECT_ID.fullmatch(str(start)) and _OBJECT_ID.fullmatch(str(end))):
|
|
1773
|
+
return [], ["the range is not two full object ids"]
|
|
1774
|
+
try:
|
|
1775
|
+
names = _git_output(root, "diff", "--name-only", "--no-renames", "-z", start, end, "--")
|
|
1776
|
+
result = split_moves(root, start, end)
|
|
1777
|
+
except (RuntimeError, ValueError) as exc:
|
|
1778
|
+
return [], [f"the landed range cannot be read: {exc}"]
|
|
1779
|
+
unread = sorted({os.fsdecode(raw) for raw in names.split(b"\0") if raw and not raw.endswith(b".py")})
|
|
1780
|
+
return result["moved"], result["problems"] + [f"{path} changed, and the proof reads Python definitions only"
|
|
1781
|
+
for path in unread]
|
|
1782
|
+
|
|
1783
|
+
|
|
1784
|
+
# ---- credits: burn rate and the day the work stops -------------------------------
|
|
1785
|
+
|
|
1786
|
+
def credit_account(profile):
|
|
1787
|
+
"""A stable name for the account a reading came from; the profile itself is not kept (#36)."""
|
|
1788
|
+
if not profile:
|
|
1789
|
+
return None
|
|
1790
|
+
return "acct-" + hashlib.sha256(str(profile).encode("utf-8")).hexdigest()[:12]
|
|
1791
|
+
|
|
1792
|
+
|
|
1793
|
+
def record_credit_sample(root, used, limit, reset_at=None, account=None, at=None, adapter=None):
|
|
1794
|
+
"""One credit reading, with the account it is of (#36) and the adapter whose lookup took it (ACCOUNT-READERS)."""
|
|
1795
|
+
d = os.path.join(root, ".polyctl", "ledger")
|
|
1796
|
+
try:
|
|
1797
|
+
os.makedirs(d, exist_ok=True)
|
|
1798
|
+
with open(os.path.join(d, "credits.jsonl"), "a", encoding=UTF8) as fh:
|
|
1799
|
+
fh.write(json.dumps({"at": int(at if at is not None else time.time()), "used": float(used),
|
|
1800
|
+
"limit": float(limit), "reset_at": reset_at,
|
|
1801
|
+
"account": account, "adapter": adapter}) + "\n")
|
|
1802
|
+
except OSError:
|
|
1803
|
+
pass
|
|
1804
|
+
|
|
1805
|
+
|
|
1806
|
+
def credit_samples(root, adapter, limit=500):
|
|
1807
|
+
"""The newest credit readings taken through this adapter's lookup; none for a call that names no adapter.
|
|
1808
|
+
|
|
1809
|
+
A reading is the account of the adapter that read it (ACCOUNT-READERS). One ledger can
|
|
1810
|
+
hold another harness's readings - an implementer that moved to another harness leaves
|
|
1811
|
+
its old one's behind - and an implementer does not bill that account, so no reader
|
|
1812
|
+
takes them for its own. A reading written before readings named their adapter is
|
|
1813
|
+
nobody's, as one that does not name its account projects nothing (#36).
|
|
1814
|
+
"""
|
|
1815
|
+
p = os.path.join(root, ".polyctl", "ledger", "credits.jsonl")
|
|
1816
|
+
if not adapter or not os.path.exists(p):
|
|
1817
|
+
return []
|
|
1818
|
+
rows = []
|
|
1819
|
+
for line in open(p, errors="replace", encoding=UTF8):
|
|
1820
|
+
try:
|
|
1821
|
+
row = json.loads(line)
|
|
1822
|
+
except ValueError:
|
|
1823
|
+
continue
|
|
1824
|
+
if isinstance(row, dict) and row.get("adapter") == adapter:
|
|
1825
|
+
rows.append(row)
|
|
1826
|
+
return rows[-limit:]
|
|
1827
|
+
|
|
1828
|
+
|
|
1829
|
+
def burn_rate(root, adapter, window=72 * 3600, now=None):
|
|
1830
|
+
"""From the samples this adapter's lookup took: credits per day, days left, and whether
|
|
1831
|
+
the plan runs out before it resets. None when there are not two samples a few hours apart."""
|
|
1832
|
+
now = now or time.time()
|
|
1833
|
+
rows = [r for r in credit_samples(root, adapter) if r["at"] >= now - window]
|
|
1834
|
+
# One account's series only (#36). An owner who switched accounts left the old
|
|
1835
|
+
# account's cumulative `used` in the ledger, and the projection ran across both:
|
|
1836
|
+
# exhaustion declared against an account that was 4% used. A reading that does
|
|
1837
|
+
# not say whose it is projects nothing.
|
|
1838
|
+
account = rows[-1].get("account") if rows else None
|
|
1839
|
+
if not account:
|
|
1840
|
+
return None
|
|
1841
|
+
rows = [r for r in rows if r.get("account") == account]
|
|
1842
|
+
if len(rows) < 2:
|
|
1843
|
+
return None
|
|
1844
|
+
first, last = rows[0], rows[-1]
|
|
1845
|
+
span = last["at"] - first["at"]
|
|
1846
|
+
if span < 3 * 3600:
|
|
1847
|
+
return None
|
|
1848
|
+
per_day = max(0.0, (last["used"] - first["used"]) / span * 86400)
|
|
1849
|
+
remaining = max(0.0, last["limit"] - last["used"])
|
|
1850
|
+
days_left = remaining / per_day if per_day > 0 else None
|
|
1851
|
+
exhausts_at = now + days_left * 86400 if days_left is not None else None
|
|
1852
|
+
reset_at = last.get("reset_at")
|
|
1853
|
+
before_reset = bool(exhausts_at and reset_at and exhausts_at < reset_at)
|
|
1854
|
+
return {"per_day": per_day, "remaining": remaining, "days_left": days_left,
|
|
1855
|
+
"exhausts_at": exhausts_at, "reset_at": reset_at, "before_reset": before_reset,
|
|
1856
|
+
"used": last["used"], "limit": last["limit"], "account": account,
|
|
1857
|
+
"samples": [first, last]}
|
|
1858
|
+
|
|
1859
|
+
|
|
1860
|
+
# ---- external ping: the dead man's switch --------------------------------------------
|
|
1861
|
+
|
|
1862
|
+
def pings_path():
|
|
1863
|
+
return os.path.join(HOME, ".polyctl", "pings.json")
|
|
1864
|
+
|
|
1865
|
+
|
|
1866
|
+
def ping_url(root):
|
|
1867
|
+
try:
|
|
1868
|
+
d = json.load(open(pings_path(), encoding=UTF8))
|
|
1869
|
+
except (OSError, ValueError):
|
|
1870
|
+
return None
|
|
1871
|
+
key = project_key(root)
|
|
1872
|
+
return d.get(key) or d.get("*")
|
|
1873
|
+
|
|
1874
|
+
|
|
1875
|
+
def set_ping_url(root, url, all_projects=False):
|
|
1876
|
+
try:
|
|
1877
|
+
d = json.load(open(pings_path(), encoding=UTF8))
|
|
1878
|
+
except (OSError, ValueError):
|
|
1879
|
+
d = {}
|
|
1880
|
+
d["*" if all_projects else project_key(root)] = url
|
|
1881
|
+
# The URL stands for the watchdog being alive: whoever holds it can ping in its place. The file is 0600 from its
|
|
1882
|
+
# creation and replaces the one before whole, as ~/.polyctl/email.json does; written in place and chmod-ed after, it
|
|
1883
|
+
# was readable meanwhile, and a write cut short lost every project's URL (HUNT-LEADS-SEC).
|
|
1884
|
+
from .storage import replace_file_durably
|
|
1885
|
+
replace_file_durably(pings_path(), json.dumps(d, indent=2).encode(UTF8), mode=0o600)
|
|
1886
|
+
return d
|
|
1887
|
+
|
|
1888
|
+
|
|
1889
|
+
def ping(root, opener=None):
|
|
1890
|
+
"""One GET to the project's ping URL. A service that expects it every N
|
|
1891
|
+
minutes alarms when it stops — which is the only way anyone learns that both
|
|
1892
|
+
the watchdog and its doctor job have died."""
|
|
1893
|
+
url = ping_url(root)
|
|
1894
|
+
if not url:
|
|
1895
|
+
return None
|
|
1896
|
+
import urllib.request
|
|
1897
|
+
try:
|
|
1898
|
+
(opener or urllib.request.urlopen)(url, timeout=5)
|
|
1899
|
+
return True
|
|
1900
|
+
except Exception:
|
|
1901
|
+
return False
|
|
1902
|
+
|
|
1903
|
+
|
|
1904
|
+
# ---- architect lock: one judge at a time --------------------------------------------
|
|
1905
|
+
|
|
1906
|
+
def architect_lock_path(root):
|
|
1907
|
+
return project_file(root, "architect-lock")
|
|
1908
|
+
|
|
1909
|
+
|
|
1910
|
+
def architect_lock_holder(root):
|
|
1911
|
+
try:
|
|
1912
|
+
d = json.load(open(architect_lock_path(root), encoding=UTF8))
|
|
1913
|
+
except (OSError, ValueError):
|
|
1914
|
+
return None
|
|
1915
|
+
if d.get("pid") and not _pid_alive(int(d["pid"])):
|
|
1916
|
+
return None # stale: holder died
|
|
1917
|
+
if time.time() - d.get("at", 0) > 3 * 3600:
|
|
1918
|
+
return None # stale: forgotten
|
|
1919
|
+
return d
|
|
1920
|
+
|
|
1921
|
+
|
|
1922
|
+
def acquire_architect(root, pid, who):
|
|
1923
|
+
"""Take the lock unless a live holder has it. Two architect copies deciding at
|
|
1924
|
+
once — a desktop resume beside a watchdog wake — contradict each other."""
|
|
1925
|
+
from .storage import _exclusive_lock
|
|
1926
|
+
with _exclusive_lock(project_file(root, "architect-lock-guard")):
|
|
1927
|
+
holder = architect_lock_holder(root)
|
|
1928
|
+
if holder and holder.get("pid") != pid:
|
|
1929
|
+
return None
|
|
1930
|
+
d = {"pid": pid, "who": who, "at": int(time.time())}
|
|
1931
|
+
try:
|
|
1932
|
+
with open(architect_lock_path(root), "w", encoding=UTF8) as fh:
|
|
1933
|
+
json.dump(d, fh)
|
|
1934
|
+
except OSError:
|
|
1935
|
+
return None
|
|
1936
|
+
return d
|
|
1937
|
+
|
|
1938
|
+
|
|
1939
|
+
def release_architect(root, pid=None):
|
|
1940
|
+
from .storage import _exclusive_lock
|
|
1941
|
+
with _exclusive_lock(project_file(root, "architect-lock-guard")):
|
|
1942
|
+
try:
|
|
1943
|
+
with open(architect_lock_path(root), encoding=UTF8) as fh:
|
|
1944
|
+
d = json.load(fh)
|
|
1945
|
+
if pid is None or d.get("pid") == pid:
|
|
1946
|
+
os.remove(architect_lock_path(root))
|
|
1947
|
+
except (OSError, ValueError):
|
|
1948
|
+
pass
|
|
1949
|
+
|
|
1950
|
+
|
|
1951
|
+
# ---- foreign edits: a person in the same files -------------------------------------
|
|
1952
|
+
|
|
1953
|
+
def implementer_recent_writes(cfg, minutes=15):
|
|
1954
|
+
"""Paths the implementer's tools wrote in the last N minutes, from its transcript.
|
|
1955
|
+
|
|
1956
|
+
A tool call, the argument naming its file and the tools that write one are what the
|
|
1957
|
+
implementer's adapter declares in `transcript.tool_call` (`write_tools`, `write_words`),
|
|
1958
|
+
as `polyctl cost` reads them; one that declares none has written nothing polyctl can see. Every
|
|
1959
|
+
call naming a file was taken for a write, reads and directory listings too, so a person
|
|
1960
|
+
editing a file the implementer had only read was never told apart from the implementer.
|
|
1961
|
+
A subagent's calls are the implementer's too: every subagent transcript beside the
|
|
1962
|
+
session's written in the window is read (`transcript.subagents`), whichever turn started it.
|
|
1963
|
+
"""
|
|
1964
|
+
msgs, _ = session_paths(cfg)
|
|
1965
|
+
if not msgs or not os.path.exists(msgs):
|
|
1966
|
+
return set()
|
|
1967
|
+
shape = transcript_shape(implementer_adapter(cfg))
|
|
1968
|
+
tool = shape["tool"]
|
|
1969
|
+
if not tool:
|
|
1970
|
+
return set()
|
|
1971
|
+
cut = time.time() - minutes * 60
|
|
1972
|
+
out = set()
|
|
1973
|
+
for d in read_tail(msgs, 3_000_000) + subagent_tails(msgs, shape, cut, 3_000_000):
|
|
1974
|
+
if record_kind(d, shape) != tool["type"]:
|
|
1975
|
+
continue
|
|
1976
|
+
try:
|
|
1977
|
+
import datetime as _dt
|
|
1978
|
+
at = _dt.datetime.fromisoformat(record_time(d, shape).replace("Z", "+00:00")).timestamp()
|
|
1979
|
+
except Exception:
|
|
1980
|
+
continue
|
|
1981
|
+
if at < cut:
|
|
1982
|
+
continue
|
|
1983
|
+
for name, args in tool_calls(record_body(d, shape), tool):
|
|
1984
|
+
path = tool_path(args, tool) if tool_writes_file(name, tool) else None
|
|
1985
|
+
if path:
|
|
1986
|
+
out.add(os.path.realpath(str(path)))
|
|
1987
|
+
return out
|
|
1988
|
+
|
|
1989
|
+
|
|
1990
|
+
def foreign_edits(root, cfg, minutes=15):
|
|
1991
|
+
"""Product files changed in the last N minutes that the implementer did not write.
|
|
1992
|
+
|
|
1993
|
+
`polyctl writers` sees agents; it cannot see a person in an editor. This is the
|
|
1994
|
+
nearest thing: a dirty product file whose mtime is recent and which the
|
|
1995
|
+
implementer's own tool calls never touched. Named in the nudge so the
|
|
1996
|
+
implementer keeps away from it."""
|
|
1997
|
+
mine = implementer_recent_writes(cfg, minutes)
|
|
1998
|
+
cut = time.time() - minutes * 60
|
|
1999
|
+
out = []
|
|
2000
|
+
for line in product_dirty(root, cfg):
|
|
2001
|
+
rel = line[3:].strip().strip('"')
|
|
2002
|
+
p = os.path.join(root, rel)
|
|
2003
|
+
files = []
|
|
2004
|
+
if os.path.isdir(p): # git lists an untracked dir as one entry
|
|
2005
|
+
for dp, _, fn in os.walk(p):
|
|
2006
|
+
files += [os.path.join(dp, x) for x in fn]
|
|
2007
|
+
elif os.path.isfile(p):
|
|
2008
|
+
files = [p]
|
|
2009
|
+
for f in files:
|
|
2010
|
+
try:
|
|
2011
|
+
if os.path.getmtime(f) >= cut and os.path.realpath(f) not in mine:
|
|
2012
|
+
out.append(os.path.relpath(f, root).replace(os.sep, "/")) # git's slashes, everywhere
|
|
2013
|
+
except OSError:
|
|
2014
|
+
pass
|
|
2015
|
+
return sorted(out)
|
|
2016
|
+
|
|
2017
|
+
|
|
2018
|
+
# ---- fleet reserve: the machine's shared windows ----------------------------------
|
|
2019
|
+
|
|
2020
|
+
def fleet_reserve():
|
|
2021
|
+
return settings.get(None, "fleet.window_reserve_pct")
|
|
2022
|
+
|
|
2023
|
+
|
|
2024
|
+
def window_headroom(provider):
|
|
2025
|
+
"""(left_pct, reserve_pct) or (None, reserve) when the window is unreadable or no provider is known."""
|
|
2026
|
+
w = provider_window(provider) if provider else None
|
|
2027
|
+
return (100 - w["pct"]) if w else None, fleet_reserve()
|
|
2028
|
+
|
|
2029
|
+
|
|
2030
|
+
def turn_ended(cfg):
|
|
2031
|
+
"""Has the implementer's transcript closed its last turn?
|
|
2032
|
+
|
|
2033
|
+
A process that is alive after its transcript wrote `turn_end` is not
|
|
2034
|
+
working; it is a runtime that forgot to exit. Waiting the full silence
|
|
2035
|
+
threshold for it (three times the idle window) cost twenty minutes per
|
|
2036
|
+
occurrence. The transcript's own word is enough to reap at the idle window.
|
|
2037
|
+
|
|
2038
|
+
Which kinds close a turn and which are bookkeeping that may follow it is the
|
|
2039
|
+
implementer's adapter's to declare (`transcript.turn`).
|
|
2040
|
+
|
|
2041
|
+
A session may end its turn while a subagent it started works on in the background
|
|
2042
|
+
(`transcript.subagents`, or `transcript.subagent_sessions` where a store keeps each subagent as
|
|
2043
|
+
a session of its own), and its runtime then lingers for the subagent, not because it forgot to
|
|
2044
|
+
exit. A subagent that wrote after the session's own last write holds work the session has not
|
|
2045
|
+
taken back, so the turn has not ended. The session takes a finished subagent back with a record
|
|
2046
|
+
of its own - the result of the call that waited for it, or the notification of its end - so a
|
|
2047
|
+
finished subagent leaves the turn to what the session says. Only the two last writes are read,
|
|
2048
|
+
both from one clock (`session_write`): a subagent's own records cannot say it finished, since an
|
|
2049
|
+
agent a workflow started ends on the result of a call, not on a response that ends a turn."""
|
|
2050
|
+
msgs, _ = session_paths(cfg)
|
|
2051
|
+
if not msgs or not os.path.exists(msgs):
|
|
2052
|
+
return False
|
|
2053
|
+
shape = transcript_shape(implementer_adapter(cfg))
|
|
2054
|
+
tail = read_tail(msgs, 200_000)
|
|
2055
|
+
skipped = False
|
|
2056
|
+
for d in reversed(tail):
|
|
2057
|
+
t = record_kind(d, shape)
|
|
2058
|
+
if is_bookkeeping(t, shape):
|
|
2059
|
+
skipped = True
|
|
2060
|
+
continue # bookkeeping after the turn
|
|
2061
|
+
if not closes_turn(d, shape):
|
|
2062
|
+
return False
|
|
2063
|
+
written = session_write(msgs)
|
|
2064
|
+
if skipped:
|
|
2065
|
+
# Bookkeeping written after the turn closed - a Stop hook's summary, a title - moved the file's time
|
|
2066
|
+
# past a subagent's write the session had not taken back, and the watchdog reaped it at the idle
|
|
2067
|
+
# window: the closing record's own time is when the session last spoke (SUBAGENT-LIVENESS-2).
|
|
2068
|
+
closed = _ledger_time(record_time(d, shape))
|
|
2069
|
+
if closed:
|
|
2070
|
+
written = min(written, closed)
|
|
2071
|
+
return all(mtime <= written for mtime, _ in subagent_writes(msgs, shape))
|
|
2072
|
+
return False
|
|
2073
|
+
|
|
2074
|
+
|
|
2075
|
+
def last_message(cfg):
|
|
2076
|
+
"""Who spoke last in the implementer's transcript, or None: {"at", "text", "in_place", "record", "spoken"}.
|
|
2077
|
+
|
|
2078
|
+
The newest prompt or reply that holds words, in the kinds its adapter declares; a record of
|
|
2079
|
+
neither kind, or one whose words are none - a tool's call or result, a note the harness keeps
|
|
2080
|
+
- is passed over. `in_place` says the harness wrote the reply in the model's place
|
|
2081
|
+
(`in_place_reply`): what its service returned where the model gave no answer, a usage limit
|
|
2082
|
+
among them, so its words are the harness's and never the model's prose, and `record` is the
|
|
2083
|
+
record itself, for what the harness keeps beside its words. `spoken` is when the newest words
|
|
2084
|
+
the harness did not write in the model's place were written: a person's, or the model's. Words
|
|
2085
|
+
of any length count, since a person who resumes a session with "go on" has spoken. `at` and
|
|
2086
|
+
`spoken` are epoch seconds, None where a time cannot be read or nobody spoke (QUOTA-PARK).
|
|
2087
|
+
"""
|
|
2088
|
+
msgs, _ = session_paths(cfg)
|
|
2089
|
+
if not msgs or not os.path.exists(msgs):
|
|
2090
|
+
return None
|
|
2091
|
+
shape = transcript_shape(implementer_adapter(cfg))
|
|
2092
|
+
kinds = set(shape["prompt"]) | set(shape["reply"])
|
|
2093
|
+
last = None
|
|
2094
|
+
for rec in reversed(read_tail(msgs, 200_000)):
|
|
2095
|
+
if record_kind(rec, shape) not in kinds:
|
|
2096
|
+
continue
|
|
2097
|
+
text = message_words(record_body(rec, shape), shape, shortest=1)
|
|
2098
|
+
if not text:
|
|
2099
|
+
continue
|
|
2100
|
+
at, in_place = _ledger_time(record_time(rec, shape)) or None, in_place_reply(rec, shape)
|
|
2101
|
+
if last is None:
|
|
2102
|
+
last = {"at": at, "text": text, "in_place": in_place, "record": rec, "spoken": None}
|
|
2103
|
+
if not in_place:
|
|
2104
|
+
last["spoken"] = at
|
|
2105
|
+
break
|
|
2106
|
+
return last
|