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
polyctl/cli.py ADDED
@@ -0,0 +1,835 @@
1
+ #!/usr/bin/env python3
2
+ """polyctl — polyctl's command line.
3
+
4
+ Every command is in build_parser(), with its code in a part under src/polyctl/parts/ that runs in
5
+ this module's namespace; the playbook, src/polyctl/skill/SKILL.md, lists each one.
6
+
7
+ Standard library only. Observation of an agent's session is strictly read-only.
8
+ """
9
+ import argparse
10
+ import json
11
+ import os
12
+ import shutil
13
+ import subprocess
14
+ import signal
15
+ import sys
16
+ import textwrap
17
+ import time
18
+ from datetime import datetime
19
+
20
+ from . import __version__
21
+ from . import language
22
+ from . import lib as A
23
+ from . import matrix as M
24
+ from . import settings as S
25
+ from .procs import TableUnreadable
26
+ from .storage import LedgerLockTimeout
27
+ from .verdicts import REVIEWER_VERDICTS
28
+ UTF8 = "utf-8" # every text file polyctl writes or reads; Windows would otherwise use cp1252
29
+
30
+ C = A.C
31
+
32
+
33
+ A._part("cli_status", globals())
34
+
35
+
36
+ A._part("cli_authority", globals())
37
+
38
+
39
+ A._part("cli_channels", globals())
40
+ A._part("cli_gain", globals())
41
+ A._part("cli_evidence", globals())
42
+ A._part("cli_next", globals())
43
+
44
+
45
+ A._part("cli_review", globals())
46
+
47
+
48
+ A._part("cli_project", globals())
49
+
50
+
51
+ A._part("cli_checks", globals())
52
+
53
+
54
+ A._part("cli_hooks", globals())
55
+
56
+
57
+ A._part("cli_maintenance", globals())
58
+
59
+
60
+ A._part("cli_lanes", globals())
61
+ A._part("cli_pr", globals())
62
+ A._part("cli_harness", globals())
63
+ A._part("cli_install", globals())
64
+ A._part("cli_completion", globals())
65
+
66
+
67
+ def _prog_name(prog=None):
68
+ """The command the person typed (`pctl` or `polyctl`), or `polyctl` when run from Python or pytest."""
69
+ raw = os.path.basename(str(prog if prog is not None else (sys.argv[0] if sys.argv else "polyctl"))).lower()
70
+ for suffix in ("-script.py", ".exe", ".ps1", ".cmd", ".bat", ".py"):
71
+ if raw.endswith(suffix):
72
+ raw = raw[:-len(suffix)]
73
+ break
74
+ return "pctl" if raw == "pctl" else "polyctl"
75
+
76
+
77
+ def build_parser(root=None, prog=None):
78
+ """The whole `polyctl` command line, built without running a command.
79
+
80
+ main parses with it, and tests/test_docs_commands.py walks it, so a document that shows
81
+ an invocation this parser refuses fails there rather than in a reader's terminal. Building
82
+ it reads the adapter catalog once, for the --agent names init and skill share, the project's
83
+ own adapters among them where `root` names the project (HARNESS-SETUP-3). `prog` names the
84
+ command the person typed (`pctl` or `polyctl`) in help and error messages, while `--version`
85
+ prints `polyctl <version>` for both (POLYCTL-AFTER-RENAME).
86
+ """
87
+ p = argparse.ArgumentParser(prog=_prog_name(prog), description="polyctl (observation layer)")
88
+ p.add_argument("-C", "--root", help="project directory (default: nearest .polyctl/ or git root)")
89
+ p.add_argument("--version", action="version", version=f"polyctl {__version__}")
90
+ sub = p.add_subparsers(dest="cmd")
91
+
92
+ s = sub.add_parser("status", help="one-shot summary")
93
+ s.add_argument("-m", "--messages", type=int, default=6)
94
+ s.add_argument("--window", type=A.time_arg("h"), default=24.0,
95
+ help="throughput window: hours (24), or 30m, 1d, today, a date (default 24)")
96
+ s.add_argument("--json", action="store_true", help="print what the panel shows as one JSON document")
97
+ s.set_defaults(fn=cmd_status)
98
+
99
+ w = sub.add_parser("watch", help="live panel; leave it in a background terminal")
100
+ w.add_argument("-i", "--interval", type=int, default=15, help="seconds between refreshes (default 15)")
101
+ w.add_argument("-m", "--messages", type=int, default=8)
102
+ w.add_argument("--all", action="store_true", help="one row per project instead of one panel")
103
+ w.add_argument("--web", action="store_true",
104
+ help="serve the panel, the board, the pipeline and the fleet as read-only pages and /api/* JSON "
105
+ "on 127.0.0.1 instead")
106
+ w.add_argument("--port", type=int,
107
+ help=f"with --web: the port on 127.0.0.1 (default {WEB_PORT}; 0 takes a free one)")
108
+ w.set_defaults(fn=cmd_watch)
109
+
110
+ fl = sub.add_parser("fleet", help="one-shot view of every project")
111
+ fl.add_argument("--json", action="store_true", help="print the rows as one JSON document")
112
+ fl.set_defaults(fn=cmd_fleet)
113
+
114
+ t = sub.add_parser("tail", help="recent messages from the implementer's transcript")
115
+ t.add_argument("-n", type=int, default=5)
116
+ t.set_defaults(fn=cmd_tail)
117
+
118
+ ev = sub.add_parser("events", help="what polyctl did on this machine, one line an event; --follow as it happens")
119
+ ev.add_argument("-f", "--follow", action="store_true", help="then print each event as it is written, until Ctrl+C")
120
+ ev.add_argument("--project", help="one project's events: its key, the name its files in ~/.polyctl carry")
121
+ ev.add_argument("--since", type=A.time_arg(), help="written at or after: 30m, 2h, today, a date (2026-09-26)")
122
+ ev.add_argument("-n", type=int, default=20, help="the newest N before following (default 20; 0: every one)")
123
+ ev.add_argument("--json", action="store_true", help="each event as a line of JSON, in the shape the log holds")
124
+ ev.set_defaults(fn=cmd_events)
125
+
126
+ m = sub.add_parser("mail", help="list, read or send coordination messages")
127
+ m.add_argument("action", choices=["list", "read", "send", "log", "search", "ack", "compact", "sync"])
128
+ m.add_argument("type", nargs="?", default="INFO")
129
+ m.add_argument("topic", nargs="?")
130
+ m.add_argument("--body")
131
+ m.add_argument("--class", dest="mail_class", choices=A.MAIL_CLASSES,
132
+ help="what the message asks of its reader; needs-decision escalates while unseen")
133
+ m.set_defaults(fn=cmd_mail)
134
+
135
+ v = sub.add_parser("verify", help="run the declared gates and record the result")
136
+ v.add_argument("-p", "--profile")
137
+ v.add_argument("--wait", type=int, default=900,
138
+ help="seconds to wait if another run, of any project, holds the machine gate lock, and as long "
139
+ "again while the machine is short of memory, paging or disk")
140
+ v.set_defaults(fn=cmd_verify)
141
+
142
+ mc = sub.add_parser("merge-check", help="run the gates on a merge's result before merging, and record it")
143
+ mc.add_argument("branch", help="the branch or commit to be merged")
144
+ mc.add_argument("--into", default="HEAD", help="what it is merged into (default HEAD)")
145
+ mc.add_argument("-p", "--profile", help="gate profile (default full, when declared)")
146
+ mc.add_argument("--wait", type=int, default=900,
147
+ help="seconds to wait if another run, of any project, holds the machine gate lock, and as long "
148
+ "again while the machine is short of memory, paging or disk")
149
+ mc.set_defaults(fn=cmd_merge_check)
150
+
151
+ wd = sub.add_parser("watchdog", help="the scheduled job that restarts a stalled agent: launchd, "
152
+ "a user systemd on Linux, Task Scheduler on Windows")
153
+ wd.add_argument("action", choices=["install", "uninstall", "status", "explain", "trace"])
154
+ wd.add_argument("--interval", type=int, default=120)
155
+ wd.add_argument("--idle-minutes", type=float, default=None,
156
+ help="default: the watchdog.idle_minutes setting, read when installed")
157
+ wd.add_argument("--last", type=int, default=20)
158
+ wd.set_defaults(fn=cmd_watchdog)
159
+
160
+ bd = sub.add_parser("board", help="where each pre-authorised item is")
161
+ bd.add_argument("view", nargs="?", choices=["ready", "add"],
162
+ help="ready: exactly the items that may start now, exit 1 on a broken edge; "
163
+ "add: admit one item, with the boundary it is judged against")
164
+ bd.add_argument("id", nargs="?", help="add: the item's id, one word")
165
+ bd.add_argument("title", nargs="?", help="add: what the item is, on one line")
166
+ bd.add_argument("--acceptance", help="add: what the work must meet, written before it starts")
167
+ bd.add_argument("--needs", help="add: the ids this item waits for, comma-separated")
168
+ bd.add_argument("--role", help="add: the role that takes it, when that is not the implementer")
169
+ bd.set_defaults(fn=cmd_board)
170
+ sl = sub.add_parser("slice", help="start, block or abandon a slice, each move a line in the slice ledger; "
171
+ "status: where one stands and how it got there")
172
+ sl.add_argument("action", nargs="?", choices=["start", "block", "abandon", "status"], default="status")
173
+ sl.add_argument("text", nargs="?", help="start, status, abandon: the item's id; block: what it waits on")
174
+ sl.add_argument("--slice", help="block, abandon, status: the item (default: the running slice)")
175
+ sl.add_argument("--why", help="abandon: why it is dropped, required; start: why, kept with the move")
176
+ sl.add_argument("--waiting", help="block: who it waits on - human, architect, decision or external")
177
+ sl.add_argument("--boundary-file", dest="boundary_file",
178
+ help="start: a file committed in the repository that the slice is judged against, in place of "
179
+ "its acceptance sentence; the architect's or a person's")
180
+ sl.set_defaults(fn=cmd_slice)
181
+ sls = sub.add_parser("slices", help="every slice on the board, its state and since when; --open leaves out "
182
+ "the done and the rejected")
183
+ sls.add_argument("--open", action="store_true", help="only the open ones: running, blocked, queued, inbox, "
184
+ "verified")
185
+ sls.set_defaults(fn=cmd_slices)
186
+ ak = sub.add_parser("ask", help="pose a decision, answerable in one tap")
187
+ ak.add_argument("question", nargs="?")
188
+ ak.add_argument("options", nargs="*")
189
+ ak.add_argument("--context")
190
+ ak.add_argument("--slice")
191
+ ak.add_argument("--codebase", action="store_true",
192
+ help="ask the code, through codebase.provider run in a copy of the working tree; the answer must "
193
+ "cite files and lines")
194
+ ak.set_defaults(fn=cmd_ask)
195
+ an = sub.add_parser("answer", help="answer a pending decision")
196
+ an.add_argument("id")
197
+ an.add_argument("value", nargs="+", help="an option's key; after the free-text key, your own words")
198
+ an.add_argument("--change", action="store_true",
199
+ help="replace an answer already given; both stay in the decision's record")
200
+ an.set_defaults(fn=cmd_answer)
201
+ dc = sub.add_parser("decisions", help="open and answered questions")
202
+ dc.add_argument("-n", type=int, default=10)
203
+ dc.set_defaults(fn=cmd_decisions)
204
+ po = sub.add_parser("propose", help="propose a change to a rule you work under, for a person to accept or "
205
+ "reject, instead of editing it")
206
+ po.add_argument("text", nargs="+", help="the change: what the rule would say, or what would change")
207
+ po.add_argument("--why", help="what went wrong under the rule as it stands; required")
208
+ po.add_argument("--rule-file", dest="rule_file",
209
+ help="the file that holds the rule, as a path in the project (relative to its root)")
210
+ po.set_defaults(fn=cmd_propose)
211
+ pp = sub.add_parser("proposals", help="rule proposals waiting for a person; --all adds the decided ones")
212
+ pp.add_argument("--all", action="store_true", help="also the accepted, rejected and otherwise answered ones")
213
+ pp.add_argument("-n", type=int, default=20, help="at most this many, newest first (default 20)")
214
+ pp.set_defaults(fn=cmd_proposals)
215
+ st_ = sub.add_parser("stats", help="slice outcomes: rounds, first-pass rate, time, size, defects found later")
216
+ st_.add_argument("--all", action="store_true", help="every project registered on this machine")
217
+ st_.add_argument("--since", type=A.time_arg(), help="landed at or after: a date (2026-09-10), 7d, yesterday")
218
+ st_.add_argument("--until", type=A.time_arg(), help="landed before: a date (2026-09-17), 2h, today")
219
+ st_.add_argument("--slices", action="store_true", help="one line per slice")
220
+ st_.set_defaults(fn=cmd_stats)
221
+ gn = sub.add_parser("gain", help="what polyctl measured: slices, spend, reviews, activity, lane evidence and "
222
+ "their daily trend, read from the ledgers and never estimated")
223
+ gn.add_argument("--all", action="store_true", help="every project registered on this machine")
224
+ gn.add_argument("--since", type=A.time_arg(),
225
+ help="window: 30m, 2h, 7d, yesterday or a date (default: everything recorded)")
226
+ gn.add_argument("--days", type=int, default=14, help="days the daily trend shows (default 14)")
227
+ gn.add_argument("--slices", action="store_true", help="one line per landed slice")
228
+ gn.add_argument("--json", action="store_true", help="print one JSON document")
229
+ gn.add_argument("--sources", action="store_true", help="name the files the numbers were read from")
230
+ gn.add_argument("--quota", action="store_true",
231
+ help="also read the implementer's account (one request; nothing is guessed for an adapter "
232
+ "that declares no lookup)")
233
+ gn.set_defaults(fn=cmd_gain)
234
+ ex = sub.add_parser("export", help="the project's ledger as OpenTelemetry traces in the OTLP/JSON encoding")
235
+ ex.add_argument("format", choices=["otlp"], help="the export encoding: otlp (one ExportTraceServiceRequest)")
236
+ ex.add_argument("--attested", action="store_true",
237
+ help="export only the rows this machine's checkpoint store attests and mark the output accordingly")
238
+ ex.add_argument("--out", metavar="FILE", help="write to FILE instead of standard output")
239
+ ex.set_defaults(fn=cmd_export)
240
+ ev = sub.add_parser("evidence", help="platform lane runs recorded from CI as evidence, and what each "
241
+ "platform's newest run still vouches for")
242
+ ev.add_argument("action", nargs="?", default="show", choices=["record", "show"])
243
+ ev.add_argument("--platform", help="record: the lane that ran, such as windows, macos or linux")
244
+ ev.add_argument("--run", help="record: the CI run's id, read through gh")
245
+ ev.add_argument("--all", action="store_true", help="show: every recorded row, not only each platform's newest")
246
+ ev.add_argument("--json", action="store_true", help="show: the same readings as one JSON document")
247
+ ev.set_defaults(fn=cmd_evidence)
248
+ nx = sub.add_parser("next", help="what needs doing now, and whose hand does it: a person's items first, then the "
249
+ "staged candidate's landing chain, each with the command that closes it")
250
+ nx.add_argument("--json", action="store_true", help="print one JSON document, for the panel and a script")
251
+ nx.add_argument("--short", action="store_true",
252
+ help="menu-bar output for SwiftBar or xbar: one summary line, then --- and the dropdown lines")
253
+ nx.set_defaults(fn=cmd_next)
254
+ sf = sub.add_parser("surfaces",
255
+ help="install or remove a desktop surface plugin in the folder you name; never guessed")
256
+ sf.add_argument("action", choices=["install", "uninstall"])
257
+ sf.add_argument("surface", choices=["swiftbar"])
258
+ sf.add_argument("--dir", required=True, metavar="DIR",
259
+ help="the plugin folder to write into or remove from; required")
260
+ sf.set_defaults(fn=cmd_surfaces)
261
+ rc = sub.add_parser("recall", help="what was decided, found or learned before, across projects")
262
+ rc.add_argument("text", nargs="+")
263
+ rc.add_argument("-n", "--limit", type=int, default=10)
264
+ rc.set_defaults(fn=cmd_recall)
265
+ wt = sub.add_parser("worktrees", help="every worktree and whether it may go; prune retires those that may")
266
+ wt.add_argument("action", nargs="?", choices=["list", "prune"], default="list")
267
+ wt.add_argument("--yes", action="store_true", help="apply the prune (default is a dry run)")
268
+ wt.set_defaults(fn=cmd_worktrees)
269
+ ln = sub.add_parser("lane", help="one worktree per READY board item, prepared from the lane settings")
270
+ ln.add_argument("action", nargs="?", choices=["start", "list", "remove"], default="list")
271
+ ln.add_argument("item", nargs="?", help="start, remove: the board item's id")
272
+ ln.set_defaults(fn=cmd_lane)
273
+ ro = sub.add_parser("role", help="the role table: show, or reassign a role to an actor")
274
+ ro.add_argument("action", nargs="?", choices=["show", "set", "swap"], default="show")
275
+ ro.add_argument("role", nargs="?", choices=list(A.ROLE_BLOCKS))
276
+ ro.add_argument("actor", nargs="?", help="set: an actor; swap: the other role")
277
+ ro.add_argument("--model", help="with set reviewer <adapter>: the model the composed reviewer runs")
278
+ ro.add_argument("--effort", help="with set reviewer <adapter>: its effort, where the adapter takes one")
279
+ ro.add_argument("--family", help="with set reviewer <adapter>: the model's family; a tool reviewer needs one")
280
+ ro.add_argument("--hotfix", action="store_true",
281
+ help="on a product repository: let the architect implement, named as a hotfix")
282
+ ro.set_defaults(fn=cmd_role)
283
+ spl = sub.add_parser("split-check", help="is the staged candidate a pure move between files?")
284
+ spl.set_defaults(fn=cmd_split_check)
285
+ ht = sub.add_parser("hunt", help="a bounded read-only bug hunt; leads go to the architect")
286
+ ht.add_argument("action", nargs="?", choices=["run", "discard", "status"], default="run")
287
+ ht.add_argument("fingerprint", nargs="?", help="discard: the lead's id")
288
+ ht.set_defaults(fn=cmd_hunt)
289
+ pw = sub.add_parser("pr", help="read this checkout's pull requests through gh and mail the implementer what "
290
+ "needs it; never writes to GitHub")
291
+ pw.add_argument("action", choices=["watch"])
292
+ pw.add_argument("--once", action="store_true", help="one pass, then exit; the watchdog does not run it yet")
293
+ pw.set_defaults(fn=cmd_pr)
294
+ hs = sub.add_parser("harness", help="probe: ask each harness that speaks ACP what it supports, sending no prompt; "
295
+ "seen: a person reads the harness configuration an agent changed here, and "
296
+ "records it as seen")
297
+ hs.add_argument("action", choices=["probe", "seen"])
298
+ hs.add_argument("ids", nargs="*", help="probe: the adapters to ask; every one that declares acp.argv when none is "
299
+ "named")
300
+ hs.add_argument("--sessions", action="store_true", help="probe: also ask how many sessions it lists for this "
301
+ "directory")
302
+ hs.add_argument("--timeout", type=float, default=20.0, help="probe: seconds each harness has to answer")
303
+ hs.add_argument("--by", help="seen: the person who reads the changes; never an agent or a role")
304
+ hs.add_argument("--digest", help="seen: record the changes as seen, while they are the bytes shown with this "
305
+ "digest; without it they are shown and nothing is recorded")
306
+ hs.add_argument("--ask", action="store_true", help="seen: at a terminal, show the changes and record exactly "
307
+ "them on a yes; one step for a person's own tool approvals")
308
+ hs.set_defaults(fn=cmd_harness)
309
+ ah = sub.add_parser("agent-hook", help="what a harness's lifecycle hook runs: record one event of its session")
310
+ ah.add_argument("event", help="the event in polyctl's words: " + ", ".join(A.AGENT_EVENTS))
311
+ ah.add_argument("--harness", help="the adapter the hook belongs to")
312
+ ah.set_defaults(fn=cmd_agent_hook)
313
+ ag = sub.add_parser("agents", help="the sessions this project's harness hooks spoke of, and what each is doing")
314
+ ag.set_defaults(fn=cmd_agents)
315
+ bk = sub.add_parser("backup", help="write the governance to a directory, a ref or a private remote")
316
+ bk.add_argument("--to", help="a directory, `ref`, or `remote:<name>`; default backup.to in the config")
317
+ bk.set_defaults(fn=cmd_backup)
318
+ rsr = sub.add_parser("restore", help="reconstruct the governance from a backup directory")
319
+ rsr.add_argument("source", help="a backup directory with its manifest.json")
320
+ rsr.add_argument("--by", help="the person who attests the restored ledgers on this machine; never an agent or a role")
321
+ rsr.add_argument("--ask", action="store_true",
322
+ help="at a terminal, show what would be attested and attest it on a yes")
323
+ rsr.set_defaults(fn=cmd_restore)
324
+ ct = sub.add_parser("content", help="borrow third-party skills, steering and agent definitions pinned to a "
325
+ "commit, text only; verify them")
326
+ ct.add_argument("action", choices=["add", "verify"])
327
+ ct.add_argument("spec", nargs="?", help="add: <source>@<40-character commit>")
328
+ ct.add_argument("--skills", help="add: the skills to borrow, comma-separated")
329
+ ct.add_argument("--steering", help="add: the steering files to borrow, comma-separated")
330
+ ct.add_argument("--agents", help="add: the agent definitions to borrow, comma-separated")
331
+ ct.add_argument("--from", dest="base", help="add: the directory in the source that holds skills/, steering/, "
332
+ "agents/ and hooks/ (default: its root)")
333
+ ct.add_argument("--harness", help="add: harness adapters to install into (default: those detected)")
334
+ ct.add_argument("--dry-run", action="store_true", help="add: say what would be written where; write nothing")
335
+ ct.set_defaults(fn=cmd_content)
336
+ rm_ = sub.add_parser("room", help="messages across every registered project")
337
+ rm_.add_argument("action", choices=["search"])
338
+ rm_.add_argument("text", nargs="+")
339
+ rm_.set_defaults(fn=cmd_room)
340
+ dg = sub.add_parser("digest", help="what happened, read from the ledgers")
341
+ dg.add_argument("--days", type=A.time_arg("d"), default=1.0,
342
+ help="how far back: days (7), or 12h, today, a date (default 1)")
343
+ dg.add_argument("-n", type=int, default=6)
344
+ dg.set_defaults(fn=cmd_digest)
345
+ ini = sub.add_parser("init", help="put polyctl on this project (idempotent)")
346
+ ini.add_argument("--name")
347
+ from . import skillkit as _skillkit
348
+ agents = _skillkit.agent_choices(root) # init and skill offer the same names: one read of the adapter catalog
349
+ ini.add_argument("--agent", choices=agents, default="auto")
350
+ ini.add_argument("--mcp", action="store_true", help="(default) register the MCP server for detected agents")
351
+ ini.add_argument("--no-mcp", action="store_true", help="skip the MCP registration")
352
+ ini.add_argument("--rules", action="store_true", help="also write the pointer into the owner's rule files")
353
+ ini.add_argument("--profile", choices=sorted(A.profiles(root)),
354
+ help="write the role blocks: who implements, reviews, judges")
355
+ ini.add_argument("--implementer", help="implementer adapter id (`polyctl adapters` lists them); overrides the profile")
356
+ ini.add_argument("--model", help="implementer model, passed through the adapter's --model option")
357
+ ini.add_argument("--effort", help="implementer effort, where its adapter takes one (options.effort_values)")
358
+ ini.add_argument("--reviewer-model", dest="reviewer_model", help="reviewer model (default: its adapter's models.review)")
359
+ ini.add_argument("--watchdog", action="store_true", help="also install the watchdog")
360
+ ini.add_argument("--allow-uncovered-gates", action="store_true",
361
+ help="write quick gates that exercise none of the detected toolchains")
362
+ ini.add_argument("--prove", action="store_true", help="finish by running polyctl prove")
363
+ ini.add_argument("--no-review", action="store_true", help="with --prove: skip the throwaway review")
364
+ from . import tiers as _tiers
365
+ ini.add_argument("--review-tier", dest="review_tier", choices=list(_tiers.TIERS),
366
+ help="independent (default): a reviewer of another model family; same-family: another model of "
367
+ "the implementer's family, labeled weaker independence, which needs --by; person: no model "
368
+ "reviewer, a person reviews each candidate with polyctl person-review")
369
+ ini.add_argument("--by", help="with --review-tier same-family: the person who opts in, recorded with the login")
370
+ ini.add_argument("--language", choices=list(S.CHOICES["language"]),
371
+ help="the project's language, set in its config before init writes a file: en (the default) "
372
+ "or tr; what polyctl writes into the project and for its people follows it")
373
+ ini.add_argument("--adopt", action="store_true",
374
+ help="adopt polyctl state no tracked .polyctl-project covers, such as a project an older polyctl set up: keep "
375
+ "all of it, write and stage the marker, install the current hooks, and name the commit left")
376
+ ini.add_argument("--allow-shared-hooks", action="store_true",
377
+ help="with --adopt: authorize the hook install where Git routes hooks through shared, external, "
378
+ "or global/system configuration")
379
+ ini.set_defaults(fn=_init_then_prove)
380
+ pv = sub.add_parser("prove", help="run the guarantees: the hook refuses, the reviewer answers, a slice lands")
381
+ pv.add_argument("--no-review", action="store_true",
382
+ help="skip the throwaway slice, which spends one short review")
383
+ pv.set_defaults(fn=cmd_prove)
384
+ dm = sub.add_parser("demo", help="see the guarantee in about a minute: a change with a bug refused, its fix landed, "
385
+ "on a scratch project with a stand-in reviewer")
386
+ dm.add_argument("--keep", action="store_true", help="keep the scratch folder and say where it is")
387
+ dm.set_defaults(fn=cmd_demo)
388
+ st = sub.add_parser("start", help="first-run wizard from nothing to a working, governed project")
389
+ st.add_argument("--yes", action="store_true",
390
+ help="run only the steps that need no person without asking before each")
391
+ st.set_defaults(fn=cmd_start)
392
+ de = sub.add_parser("decide", help="record an architect decision durably")
393
+ de.add_argument("decision", nargs="?")
394
+ de.add_argument("--why")
395
+ de.add_argument("--answers", help="open decision id this settles, e.g. D-123")
396
+ de.add_argument("--scope")
397
+ de.add_argument("--to", default=None, help="a name; default: whoever holds the implementer role")
398
+ de.add_argument("--urgent", action="store_true")
399
+ de.add_argument("--list", action="store_true")
400
+ de.add_argument("-n", type=int, default=10)
401
+ de.set_defaults(fn=cmd_decide)
402
+ si = sub.add_parser("since", help="what changed since you last looked")
403
+ si.add_argument("ref", nargs="?",
404
+ help="last | 30m | 2h | 1d | today | yesterday | a date | <git ref>: a ref is given to git "
405
+ "as a single argument, never an option")
406
+ si.add_argument("--no-mark", action="store_true")
407
+ si.set_defaults(fn=cmd_since)
408
+ nt = sub.add_parser("note", help="write an architect message into the mailbox")
409
+ nt.add_argument("title")
410
+ nt.add_argument("--body")
411
+ nt.add_argument("--to", default=None, help="a name; default: whoever holds the implementer role")
412
+ nt.add_argument("--urgent", action="store_true")
413
+ nt.add_argument("--stdin", action="store_true", help="read the body from stdin")
414
+ nt.set_defaults(fn=cmd_note)
415
+ hf = sub.add_parser("handoff", help="write and send everything a successor needs")
416
+ hf.add_argument("--reason")
417
+ hf.add_argument("--no-send", action="store_true")
418
+ hf.set_defaults(fn=cmd_handoff)
419
+ rw = sub.add_parser("review", help="review an exact staged candidate with an independent actor")
420
+ rw.add_argument("action", nargs="?", choices=["submit", "collect", "cancel"],
421
+ help="submit: pin the staged candidate and review it in the background; "
422
+ "collect: take a finished review; cancel: stop a submitted review and its reviewer")
423
+ rw.add_argument("rid", nargs="?", help="collect, cancel: the review id")
424
+ rw.add_argument("--any", action="store_true", help="collect: the oldest finished review")
425
+ rw.add_argument("--run", help=argparse.SUPPRESS)
426
+ rw.add_argument("--boundary", help="acceptance boundary; defaults to the running slice")
427
+ rw.add_argument("--paths", nargs="*", help="narrow a prospective review to these staged paths")
428
+ rw.add_argument("--commits", help="review landed work retrospectively; never authorizes a commit")
429
+ rw.add_argument("--reviewer", metavar="ACTOR",
430
+ help="with --commits: a reviewer actor of the project's table reviews the range in place of the "
431
+ "reviewer role, as `polyctl catchup --reviewer` does; the table is not changed")
432
+ rw.add_argument("--slice", dest="range_slice", metavar="ID",
433
+ help="with --commits: the slice that landed the range; the review is recorded as that slice's and, "
434
+ "without --boundary, judged against the range's commit messages, as a catch-up review is")
435
+ # Accepted so existing callers keep working, and ignored: the timeout is
436
+ # `review_timeout` in .polyctl/config.json (#63).
437
+ rw.add_argument("--timeout", type=int, help=argparse.SUPPRESS)
438
+ rw.set_defaults(fn=cmd_review)
439
+ rs = sub.add_parser("reviews", help="submitted reviews: state, slice, elapsed and verdict")
440
+ rs.set_defaults(fn=cmd_reviews)
441
+ cr = sub.add_parser("collect-review",
442
+ help="a person records a stand-in session's answer to polyctl's review request")
443
+ cr.add_argument("nonce")
444
+ cr.add_argument("--response", required=True, help="file holding the session's whole answer")
445
+ cr.add_argument("--model", required=True, help="the model the session ran, as you know it")
446
+ cr.add_argument("--by", required=True, help="the person who carried the answer")
447
+ cr.set_defaults(fn=cmd_collect_review)
448
+ pr = sub.add_parser("person-review",
449
+ help="a person reads the staged candidate's diff and records APPROVED or NEEDS_CHANGES")
450
+ pr.add_argument("--by", required=True, help="the person who reads the diff; never an agent or a role")
451
+ pr.add_argument("--verdict", choices=list(REVIEWER_VERDICTS),
452
+ help="record this verdict; without it the diff and its digest are shown and nothing is recorded")
453
+ pr.add_argument("--digest", help="with --verdict: the whole digest shown beside the diff you read")
454
+ pr.add_argument("--findings", help="a file of findings, one a line: - [BLOCKER|HIGH|MEDIUM|LOW] file:line - what "
455
+ "breaks; NEEDS_CHANGES needs a BLOCKER or HIGH one. A boundary's criteria are "
456
+ "answered there too: CRITERION <n>: MET|NOT MET - the evidence")
457
+ pr.add_argument("--boundary", help="acceptance boundary; defaults to the running slice")
458
+ pr.add_argument("--paths", nargs="*", help="narrow the review to these staged paths")
459
+ pr.add_argument("--commits", help="a landed range instead of the staged candidate: what catch-up closes a waiver on")
460
+ pr.set_defaults(fn=cmd_person_review)
461
+ ci = sub.add_parser("ci", help="a pull request's change reviewed in CI by a model of another family, with no "
462
+ "setup; it grants nothing")
463
+ ci.add_argument("action", choices=["review"])
464
+ ci.add_argument("--base", required=True,
465
+ help="the revision the change is measured from, such as the pull request's base; the review "
466
+ "starts at its merge base with --head")
467
+ ci.add_argument("--head", default="HEAD", help="the change's last commit (default HEAD)")
468
+ ci.add_argument("--reviewer", required=True, metavar="ADAPTER",
469
+ help="the reviewer's adapter, composed for this run alone as polyctl role set reviewer composes one")
470
+ ci.add_argument("--model", help="the model the reviewer runs; a tool reviewer needs one")
471
+ ci.add_argument("--family", help="the reviewer model's family, as you know it; a tool reviewer needs one")
472
+ ci.add_argument("--author-family", dest="author_family", required=True,
473
+ help="the family of the model that wrote the change, or unknown: a statement, not a measurement; "
474
+ "a reviewer of that family is refused")
475
+ ci.add_argument("--boundary", help="what the change says it does, such as the pull request's title; judged as its "
476
+ "author's claim")
477
+ ci.add_argument("--summary", help="a Markdown file to append the verdict and the findings to, such as "
478
+ "$GITHUB_STEP_SUMMARY")
479
+ ci.add_argument("--outputs", help="a file to append name=value lines to, such as $GITHUB_OUTPUT: verdict, "
480
+ "artefact, tier, base, head and the four counts")
481
+ ci.set_defaults(fn=cmd_ci)
482
+ tg = sub.add_parser("telegram", help="phone channel: alerts out, decisions in")
483
+ tg.add_argument("action", nargs="?", default="status",
484
+ choices=["status", "setup", "test", "poll", "install", "uninstall"])
485
+ tg.add_argument("--once", action="store_true", help="poll: one pass then exit")
486
+ tg.add_argument("--chat", action="append", metavar="ID",
487
+ help="setup: a chat the bot takes messages from, by its id; again for each. Without one, polyctl lists "
488
+ "the chats that wrote to the bot and asks")
489
+ tg.add_argument("--token-env", metavar="NAME",
490
+ help="setup: the environment variable holding the bot token, where no terminal is attached to "
491
+ "ask for it at")
492
+ tg.set_defaults(fn=cmd_telegram)
493
+ nt = sub.add_parser("ntfy", help="phone channel: alerts out via ntfy.sh or a self-hosted ntfy server")
494
+ nt.add_argument("action", nargs="?", default="status", choices=["status", "setup", "test"])
495
+ nt.add_argument("--topic-url", metavar="URL", help="setup: the topic's https URL (ntfy.sh or your own server)")
496
+ nt.add_argument("--token-env", metavar="NAME",
497
+ help="setup: the environment variable holding the access token, when the server needs one")
498
+ # Kept so `--token VALUE` is refused in polyctl's words without argparse quoting the token back.
499
+ nt.add_argument("--token", help=argparse.SUPPRESS)
500
+ nt.set_defaults(fn=cmd_ntfy)
501
+ cr = sub.add_parser("credits", help="credit spend measured from local transcripts")
502
+ cr.add_argument("--offline", action="store_true", help="skip the account lookup")
503
+ cr.add_argument("--local", action="store_true", help="also show this machine's share")
504
+ cr.add_argument("--all", action="store_true",
505
+ help="every shipped adapter's account and local estimate, one block each")
506
+ cr.add_argument("--reset-day", type=int, help="fallback: override the renewal day")
507
+ cr.set_defaults(fn=cmd_credits)
508
+ cm = sub.add_parser("commit", help="commit the staged candidate after polyctl commit-ok, naming its grant in Polyctl- "
509
+ "trailers; never skips hooks")
510
+ source = cm.add_mutually_exclusive_group(required=True)
511
+ source.add_argument("-m", "--message")
512
+ source.add_argument("-F", "--file")
513
+ cm.set_defaults(fn=cmd_commit)
514
+ ck = sub.add_parser("commit-ok", help="grant authority for the exact staged index candidate")
515
+ ck.add_argument("--verify", action="store_true", help="run the quick gates first when the verification is stale")
516
+ ck.add_argument("-p", "--profile", help="gate profile for --verify (default quick)")
517
+ ck.add_argument("--review", help="grant only if the staged tree is the tree this submitted review pinned")
518
+ ck.add_argument("--by", help="person authorising a coordination-only commit (never an agent)")
519
+ ck.add_argument("--ask", action="store_true",
520
+ help="with --by: show the coordination candidate and ask at this terminal before granting")
521
+ ck.add_argument("--digest", metavar="SHA256",
522
+ help="with --by: the staged candidate digest polyctl printed to confirm")
523
+ ck.set_defaults(fn=cmd_commit_ok)
524
+ cc = sub.add_parser(
525
+ "commit-check",
526
+ help="pre-commit check: revalidate the recorded grant against the active index; "
527
+ "--range checks landed commits instead",
528
+ )
529
+ cc.add_argument("--range", metavar="A..B",
530
+ help="check each commit of a revision range instead, or of one commit's whole history: it "
531
+ "carries the Polyctl- trailers polyctl commit writes and has the tree they name; read-only, and "
532
+ "it needs no .polyctl/, as in CI")
533
+ cc.add_argument("--since-first-trailer", action="store_true",
534
+ help="with --range: leave out the commits older than the first one carrying Polyctl- trailers")
535
+ cc.set_defaults(fn=cmd_commit_check)
536
+ lk = sub.add_parser("lock", help="run a heavy command under the machine-wide lock")
537
+ lk.add_argument("--wait", type=int, default=1800,
538
+ help="seconds to wait if another run holds the machine gate lock, and as long again while the "
539
+ "machine is short of memory, paging or disk")
540
+ lk.add_argument("command", nargs=argparse.REMAINDER)
541
+ lk.set_defaults(fn=cmd_lock)
542
+ mc = sub.add_parser("mcp", help="serve project state to MCP clients (stdio)")
543
+ mc.add_argument("action", choices=["serve", "config"], nargs="?", default="config")
544
+ mc.add_argument("--allow-verify", action="store_true", help="expose the gate runner too")
545
+ # A role the server does not know is refused here, naming the roles, and by the server itself: it was served every
546
+ # tool, so a mistyped reviewer could report and acknowledge mail as the architect (HUNT-LEADS-SEC). Read without
547
+ # case or surrounding space, as the server reads it (MCP-ROLES).
548
+ mc.add_argument("--role", type=lambda given: given.strip().lower(), choices=sorted(A.ROLE_BLOCKS),
549
+ help="the role this server serves: architect, implementer or reviewer, each only its own tools "
550
+ "(default: every tool)")
551
+ mc.add_argument("--project", type=lambda given: given.strip().lower(), choices=["all"],
552
+ help="all: serve every project in polyctl's project registry on one server, refusing any outside it")
553
+ mc.set_defaults(fn=cmd_mcp)
554
+ am = sub.add_parser("a2a-mcp", help="reach A2A agents from an MCP client (stdio)")
555
+ am.add_argument("action", choices=["serve", "config"], nargs="?", default="config")
556
+ am.set_defaults(fn=cmd_a2a_mcp)
557
+
558
+ a2 = sub.add_parser("a2a", help="serve the board as A2A tasks (loopback HTTP)")
559
+ a2.add_argument("action", choices=["serve", "info"], nargs="?", default="info")
560
+ a2.add_argument("--port", type=int, default=8731)
561
+ a2.set_defaults(fn=cmd_a2a)
562
+ n = sub.add_parser("notices", help="alerts this project raised; with an id, what it was raised on")
563
+ n.add_argument("ident", nargs="?", help="a notice id: print its evidence")
564
+ n.add_argument("-n", type=int, default=12)
565
+ n.add_argument("--all", action="store_true", help="include rate-limited ones")
566
+ n.add_argument("--json", action="store_true", help="print the notices as one JSON document")
567
+ n.set_defaults(fn=cmd_notices)
568
+ pr = sub.add_parser("prune", help="trim accumulated records and logs")
569
+ pr.add_argument("--days", type=A.time_arg("d"), default=7,
570
+ help="records older than this: days (7), or 12h, yesterday, a date (default 7)")
571
+ pr.add_argument("--keep-kb", type=int, default=64, help="log tail to keep")
572
+ pr.add_argument("--evidence", action="store_true", help="also prune verifications and plans")
573
+ pr.add_argument("--review-days", type=A.time_arg("d"), default=None,
574
+ help="age at which review artefacts nothing rests on move to the archive "
575
+ "(default: review.prune_after_days)")
576
+ pr.add_argument("--yes", action="store_true", help="apply (default is a dry run)")
577
+ pr.set_defaults(fn=cmd_prune)
578
+ h = sub.add_parser("hold", help="stop this project's agents and keep them stopped")
579
+ h.add_argument("action", choices=["hold", "release", "status"], nargs="?", default="hold")
580
+ h.add_argument("reason", nargs="?")
581
+ h.add_argument("--by", default="architect")
582
+ h.add_argument("--note", help="on release: what changed while the agent was stopped")
583
+ h.add_argument("--grace", type=float, default=10, help="seconds before SIGKILL")
584
+ h.set_defaults(fn=cmd_hold)
585
+ em = sub.add_parser("email", help="the red alarm channel: e-mail via formsubmit.co or an SMTP server")
586
+ em.add_argument("action", choices=["setup", "test", "status"], nargs="?", default="status")
587
+ em.add_argument("--provider", choices=["formsubmit", "smtp"])
588
+ em.add_argument("--token", help="formsubmit: the alias it hands back after verification")
589
+ em.add_argument("--to")
590
+ em.add_argument("--host", help="smtp: the server")
591
+ em.add_argument("--port", type=int, help="smtp: 587 for starttls, 465 for implicit")
592
+ em.add_argument("--user", help="smtp: the account")
593
+ em.add_argument("--password-env", help="smtp: the environment variable holding the password")
594
+ em.add_argument("--from", dest="sender", help="smtp: the sender, if not --to")
595
+ em.add_argument("--tls", choices=["starttls", "implicit", "none"])
596
+ em.set_defaults(fn=cmd_email)
597
+ al = sub.add_parser("alarms", help="live alarm episodes (yellow/orange/red); test rings the channels")
598
+ al.add_argument("action", choices=["list", "test", "snooze", "unsnooze"], nargs="?", default="list")
599
+ al.add_argument("key", nargs="?", help="snooze/unsnooze: the alarm key as polyctl alarms lists it")
600
+ al.add_argument("--level", choices=["yellow", "orange", "red"])
601
+ al.add_argument("--until", type=A.time_arg(),
602
+ help="snooze: a date (2026-10-01) or a span from now (3d); the alarm rings again from then")
603
+ al.add_argument("--why", help="snooze: why nobody can act on it before then")
604
+ al.add_argument("--by", default="human", help="snooze: who decided it")
605
+ al.set_defaults(fn=cmd_alarms)
606
+ co = sub.add_parser("cost", help="what the coordination spends: implementer turns by class (product/analysis/ceremony/coordination)")
607
+ co.add_argument("--since", type=A.time_arg(),
608
+ help="window: 24h, 7d, today, a date (default: whole transcript)")
609
+ view = co.add_mutually_exclusive_group()
610
+ view.add_argument("--features", action="store_true", help="what each feature switch spent, measured")
611
+ view.add_argument("--usd", action="store_true",
612
+ help="the spend in US dollars: an estimate from the price table polyctl ships, unknown for a "
613
+ "model it does not price")
614
+ co.set_defaults(fn=cmd_cost)
615
+ cf = sub.add_parser("config", help="what a person can set: list, get, set, unset")
616
+ cf.add_argument("action", choices=["list", "get", "set", "unset"], nargs="?", default="list")
617
+ cf.add_argument("key", nargs="?")
618
+ cf.add_argument("value", nargs="?")
619
+ cf.add_argument("--machine", action="store_true", help="the machine's settings, not the project's")
620
+ cf.add_argument("--by", help="the person who changes a setting that weakens a guarantee (review.same_family), "
621
+ "recorded with the login")
622
+ cf.set_defaults(fn=cmd_config)
623
+ ft = sub.add_parser("features", help="the switches and what each costs; all off = deterministic polyctl")
624
+ ft.add_argument("action", choices=["list", "on", "off"], nargs="?", default="list")
625
+ ft.add_argument("key", nargs="?")
626
+ ft.add_argument("--by", help="off, for a switch that weakens a guarantee (review, inventory_review): the person "
627
+ "who turns it off, on the record; required")
628
+ ft.set_defaults(fn=cmd_features)
629
+ wv = sub.add_parser("waive", help="a person bypasses a gate for a slice, on the record")
630
+ wv.add_argument("gate", choices=["review", "inventory", "gates"])
631
+ wv.add_argument("--slice")
632
+ wv.add_argument("--why")
633
+ wv.add_argument("--by", help="the person who authorises it; required")
634
+ wv.add_argument("--gates", "--gate", dest="gates", default=None,
635
+ help="for `gates`: comma-separated gate names this waiver covers (every gate of the profile "
636
+ "when omitted)")
637
+ wv.add_argument("--hours", type=float, default=None,
638
+ help="how long it may stand in for the gate (settings waivers.default_hours "
639
+ "and waivers.max_hours; 24 and 168 unless changed)")
640
+ wv.set_defaults(fn=cmd_waive)
641
+ cu = sub.add_parser("catchup", help="replay what could not run: waived reviews and gates, deferred wakes and nudges",
642
+ description="Replay what could not run: waived reviews and gates, deferred wakes and nudges. "
643
+ "A run exits 3 when the reviews it started decided nothing, 1 when a waived gate "
644
+ "failed or something could not be written or read, 2 when it is refused, and "
645
+ "otherwise 0, whether it made progress or had nothing to do.")
646
+ cu.add_argument("--boundary", help="replace the range's commit claims with a person's boundary; needs --by")
647
+ cu.add_argument("--plan", action="store_true",
648
+ help="list each open review or gates waiver, its range, commits and changed lines or waived gates, "
649
+ "whether it closes by proof, and the totals; run nothing and write nothing")
650
+ cu.add_argument("--limit", type=int, help="start at most this many gate re-runs and reviews in this run; what needs "
651
+ "neither is still done")
652
+ cu.add_argument("--slice", help="only the waivers for this slice")
653
+ cu.add_argument("--author-family", dest="author_family",
654
+ help="a person names the model family that wrote the waived ranges, for those whose grant "
655
+ "recorded none; a reviewer of a family named either way is refused. Needs --by")
656
+ cu.add_argument("--move-only", dest="move_only",
657
+ help="a person states that these waived slices, separated by commas, only moved code; each "
658
+ "closes only if the move proof holds on what it landed, never on the statement. Needs --by")
659
+ cu.add_argument("--by", help="with --author-family, --move-only or --boundary: the person who states it, recorded with "
660
+ "what it decides")
661
+ cu.add_argument("--reviewer", metavar="ACTOR",
662
+ help="a reviewer actor of the project's table reviews this run in place of the reviewer role, "
663
+ "so runs over different slices can each have their own; the table is not changed")
664
+ cu.set_defaults(fn=cmd_catchup)
665
+ pg = sub.add_parser("pings", help="dead man's switch: external pings that alarm when they stop")
666
+ pg.add_argument("action", choices=["status", "setup", "test"], nargs="?", default="status")
667
+ # Kept so a script's `--url VALUE` is refused in polyctl's words: argparse's would quote the URL back (SECRETS-2).
668
+ pg.add_argument("--url", help=argparse.SUPPRESS)
669
+ pg.add_argument("--url-env", metavar="NAME",
670
+ help="setup: the environment variable holding the ping URL, where no terminal is attached to ask "
671
+ "for it at")
672
+ pg.add_argument("--all", action="store_true", help="setup: the URL of every project that has none of its own")
673
+ pg.set_defaults(fn=cmd_pings)
674
+ hk = sub.add_parser(
675
+ "hooks",
676
+ help="inspect/install static polyctl hook intent at Git's effective path; shared/external/global mutation needs explicit authorization",
677
+ )
678
+ hk.add_argument("action", choices=["install", "uninstall", "status"], nargs="?", default="status")
679
+ hk.add_argument(
680
+ "--allow-shared-hooks", action="store_true",
681
+ help="authorize the whole mutation set when Git routes hooks through shared, external, or global/system configuration",
682
+ )
683
+ hk.set_defaults(fn=cmd_hooks)
684
+ ps_ = sub.add_parser("push", help="allow a human push for N minutes; check is what the hook runs")
685
+ ps_.add_argument("action", choices=["status", "allow", "check"], nargs="?", default="status")
686
+ ps_.add_argument("--minutes", type=int, default=30)
687
+ ps_.set_defaults(fn=cmd_push)
688
+ rm = sub.add_parser(
689
+ "remove",
690
+ help="take polyctl off this repository after a full hook-topology preflight; protected hooks stay untouched",
691
+ )
692
+ rm.add_argument("--yes", action="store_true")
693
+ rm.add_argument(
694
+ "--allow-shared-hooks", action="store_true",
695
+ help="authorize the whole hook-removal set when Git routes hooks through shared, external, or global/system configuration",
696
+ )
697
+ rm.set_defaults(fn=cmd_remove)
698
+ up = sub.add_parser("update", help="update polyctl the way it was installed (git clone, Homebrew, pipx, uv or pip), "
699
+ "saying what it runs first")
700
+ up_when = up.add_mutually_exclusive_group()
701
+ up_when.add_argument("--yes", action="store_true", help="run the update without asking")
702
+ up_when.add_argument("--dry-run", action="store_true", help="say what would run, and run nothing")
703
+ up.set_defaults(fn=cmd_update)
704
+ un = sub.add_parser("uninstall", help="take polyctl's scheduled jobs, hooks and MCP entries off this machine; "
705
+ "a dry run unless --yes")
706
+ un.add_argument("--yes", action="store_true", help="take them (default is a dry run)")
707
+ un.add_argument("--purge", action="store_true",
708
+ help="also delete ~/.polyctl: settings, channel credentials, logs, archived reviews, the registry")
709
+ un.add_argument(
710
+ "--allow-shared-hooks", action="store_true",
711
+ help="authorize removing hooks where Git routes them through shared, external, or global/system configuration",
712
+ )
713
+ un.set_defaults(fn=cmd_uninstall)
714
+ fo = sub.add_parser("fanout", help="may a fan-out of N sub-agents start now; record what one cost")
715
+ fo.add_argument("action", choices=["ok", "record", "history"], nargs="?", default="ok")
716
+ fo.add_argument("--agents", type=int)
717
+ fo.add_argument("--roots", type=int, help="pipeline: number of first-stage agents")
718
+ fo.add_argument("--per-root", type=int, dest="per_root", help="pipeline: at most this many second-stage agents per root")
719
+ fo.add_argument("--per-agent-tokens", type=int, dest="per_agent_tokens")
720
+ fo.add_argument("--provider", help="keyflip provider; default: the architect's")
721
+ fo.add_argument("--done", type=int)
722
+ fo.add_argument("--errors", type=int)
723
+ fo.add_argument("--tokens", type=int)
724
+ fo.add_argument("--note")
725
+ fo.add_argument("--limit", type=int, default=20)
726
+ fo.add_argument("--json", action="store_true")
727
+ fo.set_defaults(fn=cmd_fanout)
728
+ w = sub.add_parser("writers", help="live turns in this tree (not processes); orphans set aside")
729
+ w.add_argument("--clean", action="store_true", help="stop orphaned processes left by ended turns")
730
+ w.add_argument("--json", action="store_true")
731
+ w.set_defaults(fn=cmd_writers)
732
+ sr = sub.add_parser("source", help="external work queues feeding the board")
733
+ sr.add_argument("action", choices=["list", "status", "import"], nargs="?", default="status")
734
+ sr.set_defaults(fn=cmd_source)
735
+ sub.add_parser("projects", help="workspaces with a local agent session").set_defaults(fn=cmd_projects)
736
+ adp = sub.add_parser("adapters", help="adapter registry: list, validate a candidate, run conformance")
737
+ adp.add_argument("action", nargs="?", choices=["list", "validate", "conform"], default="list")
738
+ adp.add_argument("target", nargs="?", help="an adapter id or a JSON file")
739
+ adp.set_defaults(fn=cmd_adapters)
740
+ md = sub.add_parser("mode", help="the project's mode: full (enforced) or lite (basic setup without enforcement)")
741
+ md.add_argument("action", choices=["show", "lite", "full"], nargs="?", default="show")
742
+ md.add_argument("--by", help="lite: the person who switches enforcement off, on the record; required")
743
+ md.add_argument(
744
+ "--allow-shared-hooks", action="store_true",
745
+ help="authorize hook install or uninstall where Git routes hooks through shared, external, "
746
+ "or global/system configuration",
747
+ )
748
+ md.set_defaults(fn=cmd_mode)
749
+ dr = sub.add_parser("doctor", help="check this workspace's wiring")
750
+ dr.add_argument("--check", action="store_true",
751
+ help="quiet: one line per problem, exit 1 if any; pages nobody without --notify")
752
+ dr.add_argument("--notify", action="store_true",
753
+ help="with --check, for the scheduled job only: page red findings, record advisories")
754
+ dr.add_argument("--consistency", action="store_true",
755
+ help="check the board, the ledgers, the review artefacts and git against each other")
756
+ dr.add_argument("--repair", action="store_true",
757
+ help="with --consistency: fix only mechanical disagreements, on the record")
758
+ dr.set_defaults(fn=cmd_doctor)
759
+ sk = sub.add_parser("skill", help="the playbook, rendered for the agents this repository uses")
760
+ sk.add_argument("action", choices=["install", "show"], nargs="?", default="install")
761
+ sk.add_argument("--agent", choices=agents, default="auto")
762
+ sk.set_defaults(fn=cmd_skill)
763
+ cp = sub.add_parser("completion", help="print a script that completes polyctl's commands, options and choices "
764
+ "in bash, zsh, fish or PowerShell")
765
+ cp.add_argument("shell", choices=list(COMPLETION_SHELLS), help="the shell the script is for")
766
+ cp.set_defaults(fn=cmd_completion)
767
+ return p
768
+
769
+
770
+ def main(argv=None, prog=None):
771
+ """Run one `polyctl` command and return its exit status.
772
+
773
+ Ordinary trouble ends in a line, not a traceback (CLI-ROBUST): an argument polyctl cannot read
774
+ exits 2 naming what it takes, and so does a project directory that does not exist; a
775
+ ledger lock another process holds names the lock and what to do; Ctrl+C exits 130, as a
776
+ shell's own commands do; anything unexpected prints its type and message, and POLYCTL_DEBUG=1
777
+ keeps its traceback for whoever has to find where it came from. The standard streams are
778
+ UTF-8 before anything is read or printed, whatever the platform's code page (#71). A
779
+ process table the platform could not read stops the command where it was asked, and says
780
+ so: what the command decides from it is not decided (WINDOWS-TABLE-CLOSED). A board that
781
+ changed while a command read it is named with what to do, and nothing was moved
782
+ (SLICE-LIFECYCLE-2). Help and error messages name the command the person typed (`pctl` or
783
+ `polyctl`), while `--version` prints `polyctl <version>` for both (POLYCTL-AFTER-RENAME).
784
+ """
785
+ A.utf8_streams()
786
+ prog = _prog_name(prog)
787
+ command, root = prog, None
788
+ try:
789
+ # The project the command is for, read before the rest, so --agent knows its own adapters (HARNESS-SETUP-3).
790
+ early = argparse.ArgumentParser(add_help=False, exit_on_error=False)
791
+ early.add_argument("-C", "--root")
792
+ try:
793
+ given = early.parse_known_args(argv)[0].root
794
+ except argparse.ArgumentError:
795
+ given = None # the parser proper names what is wrong, as `prog`
796
+ p = build_parser(A.find_root(given if given and os.path.isdir(os.path.expanduser(given)) else None), prog=prog)
797
+ args = p.parse_args(argv)
798
+ if args.root and not os.path.isdir(os.path.expanduser(args.root)):
799
+ # Taken at face value, a missing directory showed an empty panel and exited 0.
800
+ what = "not a directory" if os.path.exists(os.path.expanduser(args.root)) else "no such directory"
801
+ p.exit(2, f"{prog}: error: -C {args.root}: {what}\n")
802
+ if not getattr(args, "fn", None):
803
+ p.print_help()
804
+ return 0
805
+ command = f"{prog} {args.cmd}"
806
+ root = A.find_root(args.root)
807
+ record = args.cmd != "export" and not (args.cmd == "watch" and getattr(args, "web", False))
808
+ return args.fn(A.load_config(root, record=record), args) or 0
809
+ except KeyboardInterrupt:
810
+ return 130
811
+ except LedgerLockTimeout as exc:
812
+ lock = exc.path or str(exc)
813
+ if root and lock.startswith(os.path.join(root, "")):
814
+ lock = os.path.relpath(lock, root)
815
+ waited = f" for {exc.timeout:g}s" if exc.timeout is not None else ""
816
+ print(f"{command}: another process held the ledger lock {lock}{waited}; "
817
+ "let it finish, then run this again", file=sys.stderr)
818
+ return 1
819
+ except TableUnreadable as exc:
820
+ print(f"{command} stopped: {exc}. It decides nothing from processes it cannot see; "
821
+ "run it again once the table can be read", file=sys.stderr)
822
+ return 1
823
+ except A.BoardChanged as exc:
824
+ print(f"{command}: {exc}", file=sys.stderr)
825
+ return 1
826
+ except Exception as exc:
827
+ if os.environ.get("POLYCTL_DEBUG", "") not in ("", "0"):
828
+ raise
829
+ print(f"{command}: {type(exc).__name__}: {' '.join(str(exc).split())} "
830
+ "(run it again with POLYCTL_DEBUG=1 for the traceback)", file=sys.stderr)
831
+ return 1
832
+
833
+
834
+ if __name__ == "__main__":
835
+ sys.exit(main())