polyctl 0.7.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. polyctl/__init__.py +7 -0
  2. polyctl/__main__.py +5 -0
  3. polyctl/a2a.py +226 -0
  4. polyctl/a2a_mcp.py +546 -0
  5. polyctl/acp.py +417 -0
  6. polyctl/adapters/README.md +101 -0
  7. polyctl/adapters/aider.json +32 -0
  8. polyctl/adapters/amazon-q.json +15 -0
  9. polyctl/adapters/amp.json +16 -0
  10. polyctl/adapters/antigravity.json +120 -0
  11. polyctl/adapters/claude-code.json +229 -0
  12. polyctl/adapters/cloud-generic.json +57 -0
  13. polyctl/adapters/codex.json +47 -0
  14. polyctl/adapters/command-code.json +45 -0
  15. polyctl/adapters/copilot.json +17 -0
  16. polyctl/adapters/cursor-agent.json +29 -0
  17. polyctl/adapters/deepseek.json +13 -0
  18. polyctl/adapters/droid.json +34 -0
  19. polyctl/adapters/gemini.json +30 -0
  20. polyctl/adapters/grok.json +22 -0
  21. polyctl/adapters/hermes.json +34 -0
  22. polyctl/adapters/kilocode.json +30 -0
  23. polyctl/adapters/kimi.json +23 -0
  24. polyctl/adapters/kiro.json +332 -0
  25. polyctl/adapters/ollama.json +29 -0
  26. polyctl/adapters/omp.json +34 -0
  27. polyctl/adapters/openai-api.json +68 -0
  28. polyctl/adapters/opencode.json +162 -0
  29. polyctl/adapters/pi.json +24 -0
  30. polyctl/adapters/pr-agent.json +54 -0
  31. polyctl/adapters/profiles.json +9 -0
  32. polyctl/adapters/qoder.json +163 -0
  33. polyctl/adapters/qwen.json +27 -0
  34. polyctl/adapters/reasonix.json +25 -0
  35. polyctl/adapters/rewriters/rtk.json +24 -0
  36. polyctl/adapters/trae.json +31 -0
  37. polyctl/adapters/vendors.json +42 -0
  38. polyctl/adapters/warp.json +88 -0
  39. polyctl/allowlist.py +1756 -0
  40. polyctl/api_review.py +920 -0
  41. polyctl/cli.py +835 -0
  42. polyctl/conformance_harness.py +9 -0
  43. polyctl/demo.py +503 -0
  44. polyctl/drivers.py +146 -0
  45. polyctl/email.py +160 -0
  46. polyctl/features.py +98 -0
  47. polyctl/journal.py +144 -0
  48. polyctl/language.py +945 -0
  49. polyctl/lib.py +1296 -0
  50. polyctl/matrix.py +660 -0
  51. polyctl/mcp.py +1362 -0
  52. polyctl/ntfy.py +169 -0
  53. polyctl/outbound.py +39 -0
  54. polyctl/parts/__init__.py +5 -0
  55. polyctl/parts/cli_authority.py +2615 -0
  56. polyctl/parts/cli_channels.py +1325 -0
  57. polyctl/parts/cli_checks.py +2293 -0
  58. polyctl/parts/cli_completion.py +686 -0
  59. polyctl/parts/cli_evidence.py +141 -0
  60. polyctl/parts/cli_gain.py +375 -0
  61. polyctl/parts/cli_harness.py +392 -0
  62. polyctl/parts/cli_hooks.py +1816 -0
  63. polyctl/parts/cli_install.py +638 -0
  64. polyctl/parts/cli_lanes.py +106 -0
  65. polyctl/parts/cli_maintenance.py +2536 -0
  66. polyctl/parts/cli_next.py +248 -0
  67. polyctl/parts/cli_pr.py +53 -0
  68. polyctl/parts/cli_project.py +2857 -0
  69. polyctl/parts/cli_review.py +5158 -0
  70. polyctl/parts/cli_status.py +898 -0
  71. polyctl/parts/lib_adapters.py +2933 -0
  72. polyctl/parts/lib_alarms.py +2106 -0
  73. polyctl/parts/lib_events.py +224 -0
  74. polyctl/parts/lib_evidence.py +412 -0
  75. polyctl/parts/lib_gates.py +2099 -0
  76. polyctl/parts/lib_lanes.py +829 -0
  77. polyctl/parts/lib_mail.py +1541 -0
  78. polyctl/parts/lib_next.py +652 -0
  79. polyctl/parts/lib_pr.py +331 -0
  80. polyctl/parts/lib_slices.py +3337 -0
  81. polyctl/parts/lib_state.py +2415 -0
  82. polyctl/parts/lib_transcript.py +4118 -0
  83. polyctl/pressure.py +325 -0
  84. polyctl/prices.json +47 -0
  85. polyctl/procs.py +1194 -0
  86. polyctl/settings.py +505 -0
  87. polyctl/skill/SKILL.md +365 -0
  88. polyctl/skillkit.py +503 -0
  89. polyctl/storage.py +2055 -0
  90. polyctl/telegram.py +327 -0
  91. polyctl/tiers.py +123 -0
  92. polyctl/verdicts.py +41 -0
  93. polyctl/watchdog.py +3887 -0
  94. polyctl/web.py +337 -0
  95. polyctl-0.7.0.dist-info/METADATA +235 -0
  96. polyctl-0.7.0.dist-info/RECORD +99 -0
  97. polyctl-0.7.0.dist-info/WHEEL +4 -0
  98. polyctl-0.7.0.dist-info/entry_points.txt +5 -0
  99. polyctl-0.7.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,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