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,829 @@
1
+ """Lanes: one git worktree per board item, so parallel work never shares a checkout (LANE-START).
2
+
3
+ A part of src/polyctl/lib.py, run in its namespace by `_part` as the parts split out of it are; it is
4
+ not importable on its own.
5
+ """
6
+
7
+
8
+ # ---- a lane: one worktree per READY board item (LANE-START) -------------------------------
9
+
10
+ LANE_BRANCH = "lane/"
11
+ LANE_SETTINGS = ("lane.link_paths", "lane.env", "lane.env_file", "lane.post_create", "lane.post_create_timeout")
12
+ # Above the lines polyctl adds to the repository's exclude file, so whoever reads that file knows why they are there.
13
+ LANE_EXCLUDE_HEADING = "# polyctl lane start: links and files it puts in a lane, never to be committed (LANE-START)"
14
+ # How long a lane's stopped post-create command may take to be gone.
15
+ LANE_STOP_SECONDS = 5
16
+ _LANE_UNSAFE = re.compile(r"[^A-Za-z0-9._-]+")
17
+ _ENV_NAME = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
18
+
19
+
20
+ class LaneRefused(Exception):
21
+ """What polyctl will not do with a lane, as the sentence a person reads; nothing was made or removed."""
22
+
23
+
24
+ def lane_name(item):
25
+ """The name a board item's lane goes by: its directory, its branch and its record in .polyctl/lanes/.
26
+
27
+ A board id may hold what no directory or branch name can - `ACME-187/1` - so each run of
28
+ other characters becomes one hyphen. Two ids that come to one name would share a lane,
29
+ and the second is refused as a lane that already exists.
30
+ """
31
+ return _LANE_UNSAFE.sub("-", str(item or "")).strip(".-")
32
+
33
+
34
+ def _real_path(path):
35
+ return os.path.normcase(os.path.realpath(path))
36
+
37
+
38
+ def _lanes_beside(trees):
39
+ """(the main checkout, the directory its lanes are made in), from git's list of worktrees.
40
+
41
+ Beside the main checkout, not the checkout asking: a linked worktree often lives inside the
42
+ main one, and a lane made beside it would sit in the main checkout's tree, where that
43
+ checkout's `git status`, tests and tools would read the lane's files as their own.
44
+ """
45
+ main = os.path.normpath(trees[0]["path"])
46
+ return main, os.path.join(os.path.dirname(main), os.path.basename(main) + "-lanes")
47
+
48
+
49
+ def lane_home(root):
50
+ """(the main checkout, the directory its lanes are made in): `<main checkout>-lanes`, beside it."""
51
+ trees = worktree_list(root)
52
+ if not trees:
53
+ raise LaneRefused("git lists no worktree here, and a lane is one")
54
+ return _lanes_beside(trees)
55
+
56
+
57
+ def lane_record_path(root, name):
58
+ return os.path.join(root, ".polyctl", "lanes", f"{name}.json")
59
+
60
+
61
+ def lane_log_path(root, name):
62
+ return os.path.join(root, ".polyctl", "lanes", f"{name}.log")
63
+
64
+
65
+ def lane_records(root):
66
+ """Every lane this checkout started, by name, each with `name`; one that cannot be read says so."""
67
+ directory = os.path.join(root, ".polyctl", "lanes")
68
+ try:
69
+ entries = sorted(os.listdir(directory))
70
+ except OSError:
71
+ return []
72
+ out = []
73
+ for entry in entries:
74
+ # A record is replaced through a hidden temporary file beside it; that file is no lane.
75
+ if entry.startswith(".") or not entry.endswith(".json"):
76
+ continue
77
+ try:
78
+ with open(os.path.join(directory, entry), encoding=UTF8) as fh:
79
+ record = json.load(fh)
80
+ except (OSError, ValueError, RecursionError):
81
+ record = None
82
+ out.append(dict(record if isinstance(record, dict) else {"state": "unreadable"}, name=entry[:-5]))
83
+ return out
84
+
85
+
86
+ def lane_record(root, item):
87
+ """The lane an item, or a lane's own name, has in this checkout, or None."""
88
+ name = lane_name(item)
89
+ return next((record for record in lane_records(root) if record["name"] == name), None)
90
+
91
+
92
+ def lane_not_ready(root, item, data=None):
93
+ """Why a board item may not start now, as a sentence; None when it is READY (#33).
94
+
95
+ READY is board_graph's alone. This only says which of its reasons holds, so a refusal
96
+ names what to do: land a dependency, answer who it waits on, or mend an edge. `data` is
97
+ the board as one reading took it, which `polyctl slice start` moves the item on
98
+ (SLICE-LIFECYCLE-2).
99
+ """
100
+ graph = board_graph(root, data)
101
+ if any(entry["id"] == item for entry in graph["ready"]):
102
+ return None
103
+ b = board(root, data)
104
+ state, entry = next(((column, row) for column in BOARD_STATES for row in b[column] if row["id"] == item),
105
+ (None, None))
106
+ if state is None:
107
+ return f"{item} is not on the board"
108
+ if state != "queued":
109
+ return f"{item} is {state} on the board, and only a queued item can be READY"
110
+ broken = [problem for problem in graph["problems"]
111
+ if re.search(rf"(?<![\w-]){re.escape(item)}(?![\w-])", problem)]
112
+ if broken:
113
+ return f"{item} stands on a broken edge of the board: {'; '.join(broken)}"
114
+ if "waiting" in entry["notes"]:
115
+ return f"{item} is waiting on {entry['notes']['waiting'] or 'someone'}"
116
+ landed = {row["id"] for column in ("done", "verified") for row in b[column]}
117
+ needs = set(_edge_ids(entry, "needs")) | {row["id"] for column in BOARD_STATES for row in b[column]
118
+ if item in _edge_ids(row, "unlocks")}
119
+ unmet = sorted(needs - landed)
120
+ if unmet:
121
+ return f"{item} needs {', '.join(unmet)}, which {'has' if len(unmet) == 1 else 'have'} not landed"
122
+ return f"{item} is not READY"
123
+
124
+
125
+ def _lane_relative(named):
126
+ """A path inside a checkout as a setting names it, with forward slashes, or None.
127
+
128
+ Relative, never climbing out with `..`, never into `.git`: a lane is prepared inside
129
+ itself, from inside the main checkout, and nowhere else. No control character either: the
130
+ path becomes one line of git's exclude file (_lane_ignore).
131
+ """
132
+ text = str(named or "").replace("\\", "/").strip()
133
+ if not text or text.startswith("/") or re.match(r"^[A-Za-z]:", text) or any(ord(ch) < 32 for ch in text):
134
+ return None
135
+ parts = [part for part in text.split("/") if part not in ("", ".")]
136
+ if not parts or ".." in parts or parts[0] == ".git":
137
+ return None
138
+ return "/".join(parts)
139
+
140
+
141
+ def lane_settings(cfg):
142
+ """The lane.* settings a start prepares a lane with, by their last word; LaneRefused names any polyctl cannot use.
143
+
144
+ settings.get passes a value it cannot use over for the default, and the default of a list
145
+ is nothing: `"make setup && npm ci"` as lane.post_create - one shell string where a list of
146
+ words belongs - ran nothing, and the lane was called ready unprepared. So a start reads
147
+ each setting's problem as well, and every value is checked here, before anything is made.
148
+ """
149
+ wanted, problems = {}, []
150
+ for key in LANE_SETTINGS:
151
+ value, _, problem = settings.resolve(cfg, key)
152
+ wanted[key.split(".", 1)[1]] = value
153
+ if problem:
154
+ problems.append(problem)
155
+ problems += [f"lane.link_paths names {named!r}, which is not a path inside a checkout"
156
+ for named in wanted["link_paths"] if _lane_relative(named) is None]
157
+ for entry in wanted["env"]:
158
+ key, equals, value = entry.partition("=")
159
+ if not equals or not _ENV_NAME.fullmatch(key) or any(ch in value for ch in "\r\n\0"):
160
+ problems.append(f"lane.env holds {entry!r}, which is not one NAME=value line")
161
+ if wanted["env"] and _lane_relative(wanted["env_file"]) is None:
162
+ problems.append(f"lane.env_file is {wanted['env_file']!r}, which names no file in the lane")
163
+ if problems:
164
+ raise LaneRefused("; ".join(problems) + "; a lane is prepared as its settings say or not started, and "
165
+ "`polyctl config list` says what each one takes")
166
+ return wanted
167
+
168
+
169
+ def _lanes_directory(root):
170
+ """.polyctl/lanes/, made on first use with a .gitignore of its own that ignores all of it.
171
+
172
+ A record names directories on this machine, and a log holds whatever a post-create command
173
+ printed, a DATABASE_URL among it. A project set up before lanes existed has no line for
174
+ them in its own .gitignore, and `git add -A` there would commit both.
175
+ """
176
+ directory = os.path.join(root, ".polyctl", "lanes")
177
+ os.makedirs(directory, exist_ok=True)
178
+ ignore = os.path.join(directory, ".gitignore")
179
+ if not os.path.exists(ignore):
180
+ with open(ignore, "w", encoding=UTF8, newline="\n") as fh:
181
+ fh.write("# what polyctl lane start records here names this machine's directories (LANE-START)\n*\n")
182
+ return directory
183
+
184
+
185
+ def _write_lane(root, name, record):
186
+ from .storage import replace_file_durably
187
+ replace_file_durably(lane_record_path(root, name),
188
+ (json.dumps(record, indent=2, ensure_ascii=False) + "\n").encode(UTF8))
189
+
190
+
191
+ def _forget_lane(root, name):
192
+ for path in (lane_record_path(root, name), lane_log_path(root, name)):
193
+ try:
194
+ os.remove(path)
195
+ except FileNotFoundError:
196
+ pass
197
+
198
+
199
+ def _process_of(pid):
200
+ """A process as a lane's record names it: its pid, and when it started, so a pid handed on is not taken for it."""
201
+ try:
202
+ start = _process_start(pid, refresh=True)
203
+ except Exception:
204
+ start = None
205
+ return {"pid": pid, "start": start}
206
+
207
+
208
+ def _polyctl_alive(process):
209
+ """Whether the polyctl a record names as preparing its lane still runs as that process."""
210
+ pid = (process or {}).get("pid")
211
+ if not isinstance(pid, int) or isinstance(pid, bool) or pid <= 0 or not _pid_alive(pid):
212
+ return False
213
+ started, now = process.get("start"), _process_start(pid)
214
+ return started is None or now is None or started == now
215
+
216
+
217
+ def _command_state(command):
218
+ """Whether a lane's post-create command, or what it started, still runs: "running", "unknown" or "gone".
219
+
220
+ The command leads a process group of its own, and what it started stays in that group
221
+ after it exits. It is "running" only while its own process answers and started when the
222
+ record says: then it is the command, and stopping its group is stopping the command. A
223
+ group that answers without that process may be what the command left behind or a stranger's
224
+ that took its number, and a process that answers with no start to compare may be either:
225
+ "unknown", which a remove refuses on and never stops.
226
+ """
227
+ pid = (command or {}).get("pid")
228
+ if not isinstance(pid, int) or isinstance(pid, bool) or pid <= 0:
229
+ return "gone"
230
+ if _pid_alive(pid):
231
+ started, now = command.get("start"), _process_start(pid)
232
+ if started is None or now is None:
233
+ return "unknown"
234
+ return "running" if started == now else "gone"
235
+ if os.name == "nt":
236
+ return "gone"
237
+ try:
238
+ os.killpg(pid, 0)
239
+ except OSError:
240
+ return "gone"
241
+ return "unknown"
242
+
243
+
244
+ def lane_holder(lane):
245
+ """Who is still preparing a lane, as a sentence, or None when nothing is.
246
+
247
+ The polyctl that started it while it runs, or the post-create command that polyctl started, which
248
+ runs on once that polyctl is killed outright - nothing can catch that - with nobody holding it to
249
+ lane.post_create_timeout.
250
+ """
251
+ if lane.get("state") != "preparing":
252
+ return None
253
+ process, command = lane.get("process") or {}, lane.get("command") or {}
254
+ if _polyctl_alive(process):
255
+ return f"polyctl, process {process['pid']}, is preparing it"
256
+ state = _command_state(command)
257
+ if state == "running":
258
+ return (f"its post-create command, process {command['pid']}, runs on with no polyctl waiting on it; "
259
+ f"`polyctl lane remove {lane.get('item') or lane['name']}` stops it")
260
+ if state == "unknown":
261
+ return f"process group {command['pid']} may still run its post-create command"
262
+ return None
263
+
264
+
265
+ def _settle_lane(root, name, record, problem):
266
+ """Record how a start ended - ready, or failed and why - and return the lane with its name."""
267
+ for key in ("process", "command"):
268
+ record.pop(key, None)
269
+ record["state"] = "failed" if problem else "ready"
270
+ if problem:
271
+ record["problem"] = problem
272
+ _write_lane(root, name, record)
273
+ return dict(record, name=name)
274
+
275
+
276
+ def _drop_lane_branch(root, branch, base):
277
+ """Delete the branch a start made when git then could not make its worktree; None, or what stays and why.
278
+
279
+ `git worktree add -b` makes the branch before the checkout, and when the checkout fails - a
280
+ required filter such as a missing git-lfs - git removes the worktree and keeps the branch.
281
+ The start found no such branch and made it at base, so while it stands there it holds
282
+ nothing of anyone's; left, it would refuse every later start of the item.
283
+ """
284
+ head = git_text(root, "rev-parse", "--verify", "--quiet", f"refs/heads/{branch}")
285
+ if not head:
286
+ return None
287
+ if head != base:
288
+ return f"the branch {branch} stays: it has moved to {head[:10]} since this start made it"
289
+ for attempt in range(2):
290
+ try:
291
+ _git_output(root, "branch", "-D", branch)
292
+ return None
293
+ except RuntimeError as exc:
294
+ if attempt:
295
+ return f"the branch {branch} stays ({exc}); `git branch -D {branch}` removes it"
296
+ # A worktree git gave up on may still be listed, and git keeps a listed worktree's branch.
297
+ try:
298
+ _git_worktree_cleanup(root, "prune")
299
+ except RuntimeError as exc:
300
+ return f"the branch {branch} stays: {exc}"
301
+
302
+
303
+ def lane_harness_hold(root):
304
+ """Why no lane may start from this checkout now, as the sentence a person reads; None when nothing holds it
305
+ (HARNESS-CONFIG).
306
+
307
+ What a harness reads from a project - hooks, plugins, MCP servers, instructions - and an agent changed here acts
308
+ wherever a harness starts on it, and a lane links its paths from this checkout and runs its post-create command, an
309
+ agent's own among the commands it can name, in what it made. So, as no wake, refill, nudge or hunt starts here
310
+ while a change to it stands unseen, no lane does either, nor while it cannot be read.
311
+ """
312
+ try:
313
+ unseen = unseen_harness_config(root)
314
+ except Exception as exc:
315
+ return (f"what a harness reads from this checkout cannot be read ({' '.join(str(exc).split())[:200]}), and "
316
+ "nothing polyctl starts here runs until it can")
317
+ if not unseen:
318
+ return None
319
+ return (f"this checkout holds harness configuration nobody has seen: {harness_config_line(unseen, limit=20)}; "
320
+ "nothing polyctl starts here runs until a person reads it with `polyctl harness seen --by <name>`")
321
+
322
+
323
+ def lane_cap_hold(root, cfg, name=None):
324
+ """Why this checkout may start no further lane, as a person reads it; None while it may (MACHINE-PRESSURE).
325
+
326
+ Five lanes each running a suite swap a laptop into uselessness while each looks reasonable, so
327
+ `limits.max_write_lanes` caps them. It counts every lane .polyctl/lanes/ records, whatever its state: a
328
+ failed lane's worktree stands until `polyctl lane remove` retires it, as its item is refused a second
329
+ one until then. Two starts at once both find room before either has a record, so a start asks
330
+ again once its own record, `name`, is made, counting every other: whichever of two asks second
331
+ sees the first, so two never both go on past the cap, though both may give way.
332
+ """
333
+ cap = settings.get(cfg, "limits.max_write_lanes")
334
+ lanes = [lane for lane in lane_records(root) if lane["name"] != name]
335
+ if len(lanes) < cap:
336
+ return None
337
+ named = ", ".join(f"{lane.get('item') or lane['name']} ({lane.get('state') or 'unreadable'})" for lane in lanes)
338
+ return (f"this checkout has {len(lanes)} lane{'' if len(lanes) == 1 else 's'} already, as many as "
339
+ f"limits.max_write_lanes allows: {named}; `polyctl lane remove <item>` retires one, or "
340
+ "`polyctl config set limits.max_write_lanes <n>` changes the cap")
341
+
342
+
343
+ def start_lane(root, cfg, item, now=None):
344
+ """Start a READY board item's lane: a worktree of its own on a branch of its own, prepared from the settings.
345
+
346
+ Everything that can refuse is asked before anything is made, the settings among it, and the
347
+ record in .polyctl/lanes/ is created exclusively, so two starts of one item cannot both make it.
348
+ The worktree is `<main checkout>-lanes/<name>` on the new branch `lane/<name>`, from this
349
+ checkout's HEAD, and prepare_lane prepares it. Returns the record: `ready`, or `failed` with
350
+ its problem and the worktree left where it is for a person to inspect. Raises LaneRefused
351
+ for a lane polyctl will not start, and RuntimeError when git could not add it; then neither the
352
+ record nor the branch is left. Stopped while it works - Ctrl-C, SIGTERM, SIGHUP - it records
353
+ the lane failed, or leaves nothing where git had not made the worktree yet, and stops too.
354
+
355
+ A lane past `limits.max_write_lanes` is refused, and so is one the machine has no room for: after
356
+ every other question, the machine is read once - memory, paging and disk - and a start, which
357
+ waits for no lock, is refused at once when one is past its limit (MACHINE-PRESSURE).
358
+ """
359
+ name = lane_name(item)
360
+ if not name:
361
+ raise LaneRefused(f"{item!r} cannot name a lane: it holds no letter or digit")
362
+ held = lane_record(root, item)
363
+ if held is not None:
364
+ raise LaneRefused(f"{item} already has a lane, {held.get('state') or 'unreadable'}, at "
365
+ f"{held.get('path') or 'an unrecorded path'}; `polyctl lane remove {item}` retires it")
366
+ crowded = lane_cap_hold(root, cfg)
367
+ if crowded:
368
+ raise LaneRefused(crowded)
369
+ why = lane_not_ready(root, item)
370
+ if why:
371
+ raise LaneRefused(f"{why}; a lane starts only for a READY item, and `polyctl board ready` lists them")
372
+ wanted = lane_settings(cfg)
373
+ unseen = lane_harness_hold(root)
374
+ if unseen:
375
+ raise LaneRefused(unseen)
376
+ branch = LANE_BRANCH + name
377
+ if subprocess.run([git_binary(), "check-ref-format", "--branch", branch], cwd=root,
378
+ capture_output=True).returncode:
379
+ raise LaneRefused(f"{item} cannot name a branch: git refuses {branch}")
380
+ try:
381
+ trees = worktree_list(root)
382
+ except RuntimeError as exc:
383
+ raise LaneRefused(f"a lane is a git worktree, and this checkout's worktrees cannot be read ({exc})") from None
384
+ if not trees:
385
+ raise LaneRefused("git lists no worktree here, and a lane is one")
386
+ main, home = _lanes_beside(trees)
387
+ path = os.path.join(home, name)
388
+ taken = next((tree for tree in trees if _real_path(tree["path"]) == _real_path(path)), None)
389
+ if taken:
390
+ raise LaneRefused(f"{path} is already a worktree of this repository, on {taken['branch'] or 'no branch'}: "
391
+ "a lane another checkout started, or one made by hand, and `polyctl lane list` in the "
392
+ "checkout that started it shows it")
393
+ inside = next((tree["path"] for tree in trees if _within(path, tree["path"])), None)
394
+ if inside:
395
+ raise LaneRefused(f"{path} would lie inside the worktree {inside}, and a lane never nests in another")
396
+ if os.path.lexists(path):
397
+ raise LaneRefused(f"{path} already exists, and a lane is never made over what is there")
398
+ if git_text(root, "rev-parse", "--verify", "--quiet", f"refs/heads/{branch}"):
399
+ raise LaneRefused(f"the branch {branch} already exists, and a lane starts on a branch of its own")
400
+ base = git_text(root, "rev-parse", "--verify", "--quiet", "HEAD^{commit}")
401
+ if not base:
402
+ raise LaneRefused("this checkout has no commit to start a lane from")
403
+ from . import pressure
404
+ short = pressure.wait_for_room(cfg, 0, "the lane")
405
+ if short:
406
+ raise LaneRefused(short)
407
+ record = {"item": item, "branch": branch, "path": path, "base": base,
408
+ "started_at": int(time.time() if now is None else now), "state": "preparing",
409
+ "process": _process_of(os.getpid()), "prepared": [], "steps": []}
410
+ _lanes_directory(root)
411
+ try:
412
+ with open(lane_record_path(root, name), "x", encoding=UTF8) as fh:
413
+ json.dump(record, fh, indent=2, ensure_ascii=False)
414
+ except FileExistsError:
415
+ raise LaneRefused(f"{item} already has a lane; `polyctl lane list` shows it") from None
416
+ crowded = lane_cap_hold(root, cfg, name)
417
+ if crowded: # another start made its record meanwhile
418
+ _forget_lane(root, name)
419
+ raise LaneRefused(crowded)
420
+ try:
421
+ made = subprocess.run([git_binary(), "worktree", "add", "-b", branch, path, base], cwd=root,
422
+ capture_output=True)
423
+ except BaseException:
424
+ # Git removes a worktree it could not finish when it hears the interrupt too.
425
+ if os.path.isdir(path):
426
+ _settle_lane(root, name, record, "polyctl was stopped while git added the worktree")
427
+ else:
428
+ _drop_lane_branch(root, branch, base)
429
+ _forget_lane(root, name)
430
+ raise
431
+ said = "; ".join(line.strip() for line in made.stderr.decode(UTF8, "replace").splitlines() if line.strip()) \
432
+ or f"exit {made.returncode}"
433
+ if made.returncode and not os.path.isdir(path):
434
+ left = _drop_lane_branch(root, branch, base)
435
+ _forget_lane(root, name)
436
+ raise RuntimeError(f"git could not add the worktree: {said}" + (f"; {left}" if left else ""))
437
+ if made.returncode:
438
+ # A post-checkout hook fails after git made the worktree: it stands, and it is no lane ready.
439
+ return _settle_lane(root, name, record, f"git worktree add failed after making the worktree: {said}")
440
+ try:
441
+ problem = prepare_lane(root, name, record, main, wanted)
442
+ except KeyboardInterrupt:
443
+ _settle_lane(root, name, record, "polyctl was stopped before the lane was prepared"
444
+ + ("; its post-create command was stopped with it" if record.get("command") else ""))
445
+ raise
446
+ except Exception as exc:
447
+ # A lane stuck at `preparing` would read as another start still running: say it failed.
448
+ problem = f"preparation stopped: {type(exc).__name__}: {exc}"
449
+ return _settle_lane(root, name, record, problem)
450
+
451
+
452
+ def prepare_lane(root, name, record, main, wanted):
453
+ """Prepare a new lane as its settings say (lane_settings), stopping at the first step that fails.
454
+
455
+ `lane.link_paths` are linked from the main checkout, `lane.env` is written into
456
+ `lane.env_file` as NAME=value lines, and `lane.post_create` runs in the lane with those
457
+ variables. `{item}`, `{lane}` and `{path}` in a value or an argument stand for the lane's
458
+ own. Nothing is put over what the lane already has: a link over a path its branch tracks
459
+ would hide it, and a file written through a link would change the main checkout. Git ignores
460
+ all polyctl puts there (_lane_ignore). Each path polyctl put in the lane goes into record["prepared"]
461
+ and each step into record["steps"] as it is done, so a start that is stopped still names
462
+ them. Returns None, or what failed.
463
+ """
464
+ words = {"{item}": record["item"], "{lane}": name, "{path}": record["path"]}
465
+
466
+ def fill(text):
467
+ for word, value in words.items():
468
+ text = text.replace(word, value)
469
+ return text
470
+
471
+ prepared, steps = record["prepared"], record["steps"]
472
+ for rel in (_lane_relative(named) for named in wanted["link_paths"]):
473
+ if rel in prepared:
474
+ continue # named twice: linked once
475
+ source, target = os.path.join(main, *rel.split("/")), os.path.join(record["path"], *rel.split("/"))
476
+ if not os.path.lexists(source):
477
+ return f"lane.link_paths names {rel}, which the main checkout {main} does not have"
478
+ if os.path.lexists(target):
479
+ return f"lane.link_paths names {rel}, which the lane's branch already has, and a link would hide it"
480
+ problem = _lane_ignore(record["path"], rel)
481
+ if problem:
482
+ return problem
483
+ try:
484
+ os.makedirs(os.path.dirname(target), exist_ok=True)
485
+ os.symlink(source, target, target_is_directory=os.path.isdir(source))
486
+ except OSError as exc:
487
+ return f"{rel} could not be linked from the main checkout ({exc.strerror or exc})"
488
+ prepared.append(rel)
489
+ steps.append(f"linked {rel}")
490
+ variables = {}
491
+ for entry in wanted["env"]:
492
+ key, _, value = entry.partition("=")
493
+ value = fill(value)
494
+ if any(ch in value for ch in "\r\n\0"):
495
+ return f"lane.env holds {entry!r}, which with this lane's own words is more than one line"
496
+ variables[key] = value
497
+ if variables:
498
+ rel = _lane_relative(wanted["env_file"])
499
+ target = os.path.join(record["path"], rel)
500
+ if os.path.lexists(target):
501
+ return f"the lane already has {rel}, and lane.env is never written over a file"
502
+ problem = _lane_ignore(record["path"], rel)
503
+ if problem:
504
+ return problem
505
+ try:
506
+ # "x" creates or fails, and never follows a link that stands at the name.
507
+ with open(target, "x", encoding=UTF8, newline="\n") as fh:
508
+ fh.write("".join(f"{key}={value}\n" for key, value in variables.items()))
509
+ except FileExistsError:
510
+ return f"the lane already has {rel}, and lane.env is never written over a file"
511
+ except OSError as exc:
512
+ return f"lane.env could not be written to {rel} ({exc.strerror or exc})"
513
+ prepared.append(rel)
514
+ steps.append(f"wrote {len(variables)} variable(s) to {rel}")
515
+ argv = [fill(word) for word in wanted["post_create"]]
516
+ if argv:
517
+ problem = _lane_post_create(root, name, record, argv, variables, wanted["post_create_timeout"])
518
+ if problem:
519
+ return problem
520
+ steps.append(f"ran {' '.join(argv)}")
521
+ return None
522
+
523
+
524
+ def _exclude_line(rel):
525
+ """The line of an exclude file that matches rel, and nothing else, from the top of a checkout."""
526
+ line = "/" + re.sub(r"([\\*?\[])", r"\\\1", rel)
527
+ kept = line.rstrip(" ")
528
+ return kept + "\\ " * (len(line) - len(kept)) # a trailing space is kept only escaped
529
+
530
+
531
+ def _lane_ignore(path, rel):
532
+ """Make git ignore rel in a lane before polyctl puts a link or a file there; None, or why it cannot.
533
+
534
+ What polyctl puts in a lane is untracked, and `git add -A` there commits whatever git does not
535
+ ignore: a link whose target is the main checkout on this machine, or a file holding the
536
+ lane's port and secrets. The usual `node_modules/` ignores a directory, never a link at
537
+ that name. So where git would not ignore rel, a line naming exactly it goes into the
538
+ repository's own exclude file - read by every worktree of the repository, committed by
539
+ none - and the main checkout ignores that name too, as it should. Asked before rel exists,
540
+ git answers as it will for a link or a file there: a pattern for directories matches neither.
541
+ """
542
+ def ignored():
543
+ return subprocess.run([git_binary(), "check-ignore", "-q", "--", rel], cwd=path, capture_output=True)
544
+
545
+ if ignored().returncode == 0:
546
+ return None
547
+ exclude = git_text(path, "rev-parse", "--git-path", "info/exclude")
548
+ if not exclude:
549
+ return f"git cannot name the repository's exclude file, and {rel} would be committed from the lane"
550
+ exclude = os.path.join(path, exclude)
551
+ line = _exclude_line(rel)
552
+ try:
553
+ try:
554
+ with open(exclude, encoding=UTF8, errors="replace") as fh:
555
+ text = fh.read()
556
+ except FileNotFoundError:
557
+ text = ""
558
+ lines = text.split("\n")
559
+ if line not in lines:
560
+ os.makedirs(os.path.dirname(exclude), exist_ok=True)
561
+ with open(exclude, "a", encoding=UTF8, newline="\n") as fh:
562
+ fh.write(("" if not text or text.endswith("\n") else "\n")
563
+ + ("" if LANE_EXCLUDE_HEADING in lines else LANE_EXCLUDE_HEADING + "\n") + line + "\n")
564
+ except OSError as exc:
565
+ return f"{rel} could not be added to git's exclude file {exclude} ({exc.strerror or exc})"
566
+ asked = ignored()
567
+ if asked.returncode == 0:
568
+ return None
569
+ why = ("a .gitignore of the branch names it again with `!`" if asked.returncode == 1 else
570
+ " ".join(asked.stderr.decode(UTF8, "replace").split()) or f"git check-ignore exited {asked.returncode}")
571
+ return (f"git would not ignore {rel} in the lane even with {line} in {exclude}, and a commit there would "
572
+ f"carry it: {why}")
573
+
574
+
575
+ def _raise_interrupt(signum, frame):
576
+ raise KeyboardInterrupt(f"signal {signum}")
577
+
578
+
579
+ def _hear_stop_signals():
580
+ """Make SIGTERM and SIGHUP interrupt polyctl as Ctrl-C does, while a lane's post-create command runs.
581
+
582
+ Returns what _restore_signals puts back. The command leads a process group of its own, so no
583
+ signal the terminal sends reaches it, and by default either signal ends polyctl on the spot and
584
+ leaves the command running in a lane nobody prepares. As an interrupt, it stops the command
585
+ first. A signal polyctl was set to ignore, as nohup ignores SIGHUP, stays ignored, and only the
586
+ main thread may set a handler at all.
587
+ """
588
+ import signal
589
+ import threading
590
+ saved = {}
591
+ if threading.current_thread() is not threading.main_thread():
592
+ return saved
593
+ for signum in (getattr(signal, "SIGTERM", None), getattr(signal, "SIGHUP", None)):
594
+ if signum is not None and signal.getsignal(signum) is signal.SIG_DFL:
595
+ saved[signum] = signal.signal(signum, _raise_interrupt)
596
+ return saved
597
+
598
+
599
+ def _restore_signals(saved):
600
+ import signal
601
+ for signum, handler in saved.items():
602
+ signal.signal(signum, handler)
603
+
604
+
605
+ def _kill_lane_group(pid):
606
+ """Stop a lane's post-create command and everything it started: its process group, or on Windows its tree.
607
+
608
+ Returns what of it still runs on Windows, each process asked, where taskkill can be refused
609
+ (WINDOWS-STOP-PROVEN); a group sent SIGKILL returns [].
610
+ """
611
+ import signal
612
+ if os.name == "nt":
613
+ return kill_turn(pid, signal.SIGTERM) or [] # taskkill /T /F, whatever the signal
614
+ try:
615
+ os.killpg(pid, signal.SIGKILL)
616
+ except OSError:
617
+ pass
618
+ return []
619
+
620
+
621
+ def _lane_post_create(root, name, record, argv, variables, timeout):
622
+ """Run a new lane's post-create command in the lane; None when it exited 0, else what went wrong.
623
+
624
+ Never through a shell: the setting is a list of words, and no word is read as shell text.
625
+ A program named bare is looked for where polyctl looks for any (runnable_binary); one named with
626
+ a path is taken from the lane. It reads nothing, it leads its own process group so a
627
+ timeout stops whatever it started, and what it prints goes to .polyctl/lanes/<name>.log. The
628
+ record names it while it runs, so a list or a remove still finds it should polyctl be killed
629
+ outright, and a Ctrl-C, SIGTERM or SIGHUP stops it before polyctl stops.
630
+ """
631
+ program, command = argv[0], " ".join(argv)
632
+ # Asked again as late as the watchdog asks before a turn: an agent can change what a harness reads while git makes
633
+ # the worktree (HARNESS-CONFIG).
634
+ unseen = lane_harness_hold(root)
635
+ if unseen:
636
+ return f"lane.post_create `{command}` was not run: {unseen}"
637
+ if os.path.isabs(program):
638
+ found = program
639
+ elif "/" in program or os.sep in program:
640
+ found = os.path.join(record["path"], program)
641
+ else:
642
+ found = runnable_binary(program)
643
+ if not found or not os.path.isfile(found):
644
+ return f"lane.post_create runs {program}, which is not a program polyctl can find"
645
+ log = f".polyctl/lanes/{name}.log"
646
+ group = ({"creationflags": getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)} if os.name == "nt"
647
+ else {"start_new_session": True})
648
+ saved = _hear_stop_signals()
649
+ try:
650
+ with open(lane_log_path(root, name), "wb") as out:
651
+ try:
652
+ proc = subprocess.Popen([found, *argv[1:]], cwd=record["path"], env=dict(os.environ, **variables),
653
+ stdin=subprocess.DEVNULL, stdout=out, stderr=subprocess.STDOUT, **group)
654
+ except OSError as exc:
655
+ return f"lane.post_create `{command}` could not be started ({exc.strerror or exc})"
656
+ try:
657
+ record["command"] = _process_of(proc.pid)
658
+ _write_lane(root, name, record)
659
+ code = proc.wait(timeout=timeout)
660
+ except BaseException as exc:
661
+ # Its group is its pid, and no other process can hold that pid until this one is reaped.
662
+ left = _kill_lane_group(proc.pid)
663
+ try:
664
+ proc.wait(timeout=LANE_STOP_SECONDS)
665
+ except subprocess.TimeoutExpired:
666
+ pass
667
+ if not isinstance(exc, subprocess.TimeoutExpired):
668
+ raise
669
+ if left:
670
+ # It said the command was stopped whatever taskkill did (WINDOWS-STOP-PROVEN).
671
+ return (f"lane.post_create `{command}` ran past {timeout} seconds, and {len(left)} process(es) "
672
+ f"of it still run after it was stopped: {left} - stop them by hand before the lane is "
673
+ f"removed; its output is in {log}")
674
+ return (f"lane.post_create `{command}` ran past {timeout} seconds and was stopped; "
675
+ f"its output is in {log}")
676
+ finally:
677
+ _restore_signals(saved)
678
+ if code:
679
+ return f"lane.post_create `{command}` exited {code}; its output is in {log}"
680
+ return None
681
+
682
+
683
+ def lane_changes(path, lane):
684
+ """What a lane's worktree holds that nobody committed, as `git status` names it, less what polyctl put there.
685
+
686
+ Every untracked file is named, not its directory, so a link polyctl made inside a directory it
687
+ made is still told from a file someone wrote beside it. What polyctl put there is passed over
688
+ only while it is untracked, as polyctl made it: once it is staged or tracked, it is a change.
689
+ Git ignores all of it (_lane_ignore); this holds should the exclude file lose its lines.
690
+ """
691
+ raw = _git_output(path, "status", "--porcelain", "-z", "--untracked-files=all")
692
+ ours = set(lane.get("prepared") or [])
693
+ fields, out, index = os.fsdecode(raw).split("\0"), [], 0
694
+ while index < len(fields):
695
+ entry = fields[index]
696
+ index += 1
697
+ if len(entry) < 4:
698
+ continue
699
+ status, name = entry[:2], entry[3:]
700
+ if "R" in status or "C" in status:
701
+ index += 1 # the name it had before follows
702
+ if not (status == "??" and name in ours):
703
+ out.append(f"{status.strip()} {name}")
704
+ return out
705
+
706
+
707
+ def lane_rows(root):
708
+ """Every lane this checkout started, with where its item stands on the board and what its worktree holds."""
709
+ b = board(root)
710
+ where = {entry["id"]: state for state in BOARD_STATES for entry in b[state]}
711
+ lanes = lane_records(root)
712
+ try:
713
+ home = lane_home(root)[1] if lanes else None
714
+ except (LaneRefused, RuntimeError):
715
+ home = None
716
+ rows = []
717
+ for lane in lanes:
718
+ state = lane.get("state") or "unreadable"
719
+ held = lane_holder(lane)
720
+ if state == "preparing" and not held:
721
+ state = "interrupted" # its start ended before it could say how
722
+ # A record that cannot be read still names its lane by its file: the lane is where polyctl makes it.
723
+ path = lane.get("path") or (os.path.join(home, lane["name"]) if home else None)
724
+ exists = bool(path) and os.path.isdir(path)
725
+ try:
726
+ changes = lane_changes(path, lane) if exists else []
727
+ except RuntimeError:
728
+ changes = None
729
+ rows.append(dict(lane, state=state, held=held, path=path, exists=exists, changes=changes,
730
+ board=where.get(lane.get("item"))))
731
+ return rows
732
+
733
+
734
+ def lane_keeps(root, trees):
735
+ """{real path: why it stays} for each worktree that is a lane: `polyctl worktrees` never retires one.
736
+
737
+ A lane starts at its base, so it reads as merged the moment it starts, and pruning it took
738
+ the worktree an agent had just been given. Each lane this checkout started is known by its
739
+ record; one another checkout started, by where it stands and the branch it is on.
740
+ """
741
+ out = {}
742
+ for lane in lane_records(root):
743
+ item = lane.get("item") or lane["name"]
744
+ if lane.get("path"):
745
+ out[_real_path(lane["path"])] = f"the lane of {item}: `polyctl lane remove {item}` retires it"
746
+ if trees:
747
+ home = _real_path(_lanes_beside(trees)[1])
748
+ for tree in trees[1:]:
749
+ real = _real_path(tree["path"])
750
+ # The name as git gives the path: the compared path is case-folded on Windows, and a lane's
751
+ # branch keeps the case of its item, so lane/B was no lane there (WINDOWS-LANE-4).
752
+ name = os.path.basename(os.path.normpath(tree["path"]))
753
+ if (real not in out and os.path.dirname(real) == home
754
+ and tree["branch"] == LANE_BRANCH + name):
755
+ out[real] = "a lane another checkout started: `polyctl lane remove` there retires it"
756
+ return out
757
+
758
+
759
+ def remove_lane(root, item, now=None):
760
+ """Retire an item's lane as `polyctl worktrees prune` retires a worktree (#42), refusing while it holds work.
761
+
762
+ Refused while its worktree holds changes nobody committed - other than the links and the
763
+ file polyctl put there to prepare it - or a review in flight, or while the polyctl that started it is
764
+ still preparing it. A post-create command that polyctl left running when it was killed is
765
+ stopped first, once it is certain to be that command. Then polyctl's own links go, so no removal
766
+ can reach through one into the main checkout, and prune_worktree archives the lane's .polyctl/
767
+ state and its branch tip and removes the worktree and the branch. Returns the steps done.
768
+
769
+ The record is a file under .polyctl/, which the agents polyctl governs can write, so it is not taken
770
+ at its word: polyctl removes only the path where it makes this lane, and only when git lists it
771
+ as a worktree of this repository, and the branch it removes is always `lane/<name>`.
772
+ """
773
+ lane = lane_record(root, item)
774
+ if lane is None:
775
+ raise LaneRefused(f"{item} has no lane here; `polyctl lane list` shows the lanes this checkout started")
776
+ name = lane["name"]
777
+ preparing = lane.get("state") == "preparing"
778
+ process, command = lane.get("process") or {}, lane.get("command") or {}
779
+ if preparing and process.get("pid") != os.getpid() and _polyctl_alive(process):
780
+ raise LaneRefused(f"lane {name} is still being prepared by polyctl, process {process['pid']}")
781
+ try:
782
+ home = lane_home(root)[1]
783
+ trees = worktree_list(root)
784
+ except RuntimeError as exc:
785
+ raise LaneRefused(f"this checkout's worktrees cannot be read ({exc}), so lane {name} stays") from None
786
+ path = os.path.join(home, name)
787
+ if lane.get("path") and _real_path(lane["path"]) != _real_path(path):
788
+ raise LaneRefused(f"the record of lane {name} names {lane['path']}, and polyctl makes it at {path}; it stays")
789
+ if os.path.lexists(path) and not any(_real_path(tree["path"]) == _real_path(path) for tree in trees[1:]):
790
+ raise LaneRefused(f"{path} is not a worktree of this repository, and polyctl removes only a lane it made")
791
+ steps = []
792
+ state = _command_state(command) if preparing else "gone"
793
+ if state == "unknown":
794
+ raise LaneRefused(f"process group {command['pid']} may still run lane {name}'s post-create command, and "
795
+ "polyctl cannot tell that it is the one it started; stop that group, then remove the lane")
796
+ if state == "running":
797
+ _kill_lane_group(command["pid"])
798
+ deadline = time.monotonic() + LANE_STOP_SECONDS
799
+ while _command_state(command) != "gone" and time.monotonic() < deadline:
800
+ time.sleep(0.1)
801
+ if _command_state(command) != "gone":
802
+ raise LaneRefused(f"lane {name}'s post-create command, process {command['pid']}, did not stop")
803
+ steps.append(f"stop the post-create command polyctl left running (process {command['pid']})")
804
+ if os.path.lexists(path):
805
+ try:
806
+ changes = lane_changes(path, lane)
807
+ except RuntimeError as exc:
808
+ raise LaneRefused(f"what lane {name} holds at {path} cannot be read ({exc}), so it stays") from None
809
+ if changes:
810
+ shown = ", ".join(changes[:5]) + (f" and {len(changes) - 5} more" if len(changes) > 5 else "")
811
+ raise LaneRefused(f"lane {name} holds {len(changes)} uncommitted change(s) at {path}: {shown}; "
812
+ "commit or discard them, then remove it")
813
+ flying = reviews_in_flight(path)
814
+ if flying:
815
+ raise LaneRefused(f"lane {name} has a review in flight: {', '.join(flying)}")
816
+ for rel in lane.get("prepared") or []:
817
+ target = os.path.join(path, *str(rel).split("/"))
818
+ if _lane_relative(rel) == rel and os.path.islink(target):
819
+ os.unlink(target)
820
+ branch = LANE_BRANCH + name
821
+ head = git_text(root, "rev-parse", "--verify", "--quiet", f"refs/heads/{branch}")
822
+ steps += prune_worktree(root, {"path": path, "branch": branch if head else None, "head": head},
823
+ apply=True, now=now, lane=lane)
824
+ _forget_lane(root, name)
825
+ try:
826
+ os.rmdir(home) # only once it is empty: polyctl made it for its lanes, and the last one is gone
827
+ except OSError:
828
+ pass
829
+ return steps