@andespindola/crow-skills 0.11.0 → 0.12.0

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.
@@ -10,7 +10,10 @@ coordinator records the transition.
10
10
  crow_ledger.py unit ID --run RUN [--title T] [--phase P] [--owner O] [--status S] [--progress 0..1] [--summary TXT]
11
11
  crow_ledger.py resources --run RUN [--from-probe FILE|-] [--mode M] [--agents N] [--heavy N] [--workers N]
12
12
  [--pressure L] [--source probe|os|assumed] [--note TXT] # parallelism decision before a fan-out
13
- crow_ledger.py finish --run RUN [--status done|failed|cancelled]
13
+ crow_ledger.py proc add --run RUN --pid PID [--unit U] [--owner O] [--adopt] # register a process this run started
14
+ crow_ledger.py proc stop --run RUN (--pid PID ... | --unit U | --all) [--grace S] # stop its whole tree
15
+ crow_ledger.py proc check --run RUN # registered processes still alive (exit 1 when any)
16
+ crow_ledger.py finish --run RUN [--status done|failed|cancelled] # warns when registered processes live
14
17
  crow_ledger.py show [--run RUN] # process list for the chat (● main / ○ owner activity)
15
18
  crow_ledger.py show --tree [--run RUN] # phase tree with ASCII bars, when the user asks for detail
16
19
  crow_ledger.py path [--run RUN] # where the ledger lives
@@ -34,7 +37,9 @@ import os
34
37
  from pathlib import Path
35
38
  import re
36
39
  import sys
40
+ import subprocess
37
41
  import tempfile
42
+ import time
38
43
 
39
44
  SCHEMA = "crow-run/1"
40
45
  UNIT_STATUSES = ("pending", "running", "done", "failed", "skipped")
@@ -151,6 +156,461 @@ def locate(run_id=None, write=False):
151
156
  return best[1], best[2]
152
157
 
153
158
 
159
+ # --- processes started by the run ------------------------------------------------------------
160
+ #
161
+ # The helpers below are a verbatim copy of crow_skills/resources.py (the skill must work without
162
+ # the CLI; tests/test_orphans.py fails when the copies drift). A registered process keeps only
163
+ # pid, pgid, start time and the redacted command (executable plus package/script name): never
164
+ # arguments or credentials. Stopping kills the WHOLE tree from a snapshot taken before the first
165
+ # signal (agent CLIs and test runners start children in their own process groups, so a group
166
+ # kill leaks grandchildren to init/launchd).
167
+
168
+ PROC_STATUSES = ("running", "stopped", "exited", "survived")
169
+ LEDGER_TOLERANCE = 10 # seconds: start-time match between registration and a later check (clock, ps latency)
170
+
171
+
172
+ def table_is_fixture():
173
+ return bool(os.environ.get("CROW_PS_FIXTURE"))
174
+
175
+
176
+ def read_table():
177
+ fixture = os.environ.get("CROW_PS_FIXTURE")
178
+ if fixture:
179
+ try:
180
+ return parse_table(Path(fixture).read_text(encoding="utf-8"))
181
+ except OSError:
182
+ return None
183
+ try:
184
+ done = subprocess.run(ps_argv(), capture_output=True, text=True, timeout=5.0,
185
+ env={"PATH": "/usr/sbin:/usr/bin:/sbin:/bin", "LC_ALL": "C"})
186
+ except (OSError, subprocess.SubprocessError, ValueError):
187
+ return None
188
+ return parse_table(done.stdout) if done.stdout else None
189
+
190
+
191
+ # >>> shared with crow_skills/resources.py (generated copy; do not edit here)
192
+ START_TOLERANCE = 3 # seconds between two estimates of a process start time (etime has 1 s resolution)
193
+
194
+
195
+ PS_COLUMNS = "pid=,ppid=,pgid=,uid=,rss=,etime=,stat=,args="
196
+
197
+
198
+ SHELLS = ("sh", "bash", "zsh", "dash", "ksh", "fish")
199
+
200
+
201
+ NPM_LIKE = ("npm", "pnpm", "yarn", "bun")
202
+
203
+
204
+ PACKAGE_RUNNERS = ("npx", "pnpx", "bunx", "uvx", "pipx")
205
+
206
+
207
+ INTERPRETER = re.compile(r"(node|nodejs|bun|deno|tsx|ts-node|python[0-9.]*|ruby|perl|php)", re.IGNORECASE)
208
+
209
+
210
+ SUBCOMMANDS = ("test", "run", "build", "check", "dev", "serve", "start", "watch", "exec", "x", "dlx", "bench", "clippy", "install")
211
+
212
+
213
+ TOKENISH = re.compile(r"(?i)token|secret|passw|apikey|api[_-]key|bearer|credential|authorization|private[_-]?key"
214
+ r"|(gh[pousr]_|github_pat_|glpat-|xox[abprs]-|AKIA[A-Z0-9]|AIza)|^sk-"
215
+ r"|^(?=.*[0-9])(?=.*[A-Za-z])[A-Za-z0-9+/_=.-]{32,}$|^(?=.*[0-9])[0-9a-fA-F]{20,}$")
216
+
217
+
218
+ SAFE_WORD = re.compile(r"[^A-Za-z0-9@._/:+=-]")
219
+
220
+
221
+ SHOWN_WORD = re.compile(r"(@[A-Za-z0-9._-]+/)?[A-Za-z0-9._/+-]+(@[A-Za-z0-9._^~+-]+)?")
222
+
223
+
224
+ RUN_SCRIPT = re.compile(r"[A-Za-z0-9._-]{1,30}(:[A-Za-z0-9._-]{1,30}){0,3}") # npm run test:unit (only there)
225
+
226
+
227
+ ASSIGNMENT = re.compile(r"[A-Za-z_][A-Za-z0-9_]*=")
228
+
229
+
230
+ VALUE_OPTIONS = ("--from", "--spec", "-p", "--with", "--registry", "--cache", "--prefix", "-r", "--require", "--import",
231
+ "--loader", "--experimental-loader", "-w", "--workspace", "--userconfig", "-C", "--cwd", "--dir", "--python")
232
+
233
+
234
+ INLINE_OPTIONS = ("-c", "--call", "-e", "--eval") # everything after them is inline code or a command line: never shown
235
+
236
+
237
+ ENV_VALUE_OPTIONS = ("-u", "--unset", "-C", "--chdir", "-S", "--split-string") # env's own options with a value
238
+
239
+
240
+ SCRIPT_LIKE = re.compile(r"\S*/\S*|[^/\s]+\.(m?[jt]sx?|c[jt]s|py|rb|pl|php|sh|bash|zsh|lua)", re.IGNORECASE)
241
+
242
+
243
+ def parse_etime(text):
244
+ """ps etime ([[dd-]hh:]mm:ss) -> seconds, or None."""
245
+ match = re.fullmatch(r"\s*(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)\s*", text or "")
246
+ if not match:
247
+ return None
248
+ days, hours, minutes, seconds = (int(x) if x else 0 for x in match.groups())
249
+ return ((days * 24 + hours) * 60 + minutes) * 60 + seconds
250
+
251
+
252
+ def parse_table(text):
253
+ """``ps -o pid=,ppid=,pgid=,uid=,rss=,etime=,stat=,args=`` (macOS or procps) -> rows:
254
+ {pid, ppid, pgid, uid, rssKb, age (s), stat, command}. The command stays in memory only."""
255
+ rows = []
256
+ for line in (text or "").splitlines():
257
+ parts = line.split(None, 7)
258
+ if len(parts) < 7 or not all(p.isdigit() for p in parts[:5]):
259
+ continue
260
+ age = parse_etime(parts[5])
261
+ if age is None:
262
+ continue
263
+ rows.append({"pid": int(parts[0]), "ppid": int(parts[1]), "pgid": int(parts[2]), "uid": int(parts[3]),
264
+ "rssKb": int(parts[4]), "age": age, "stat": parts[6], "command": parts[7].strip() if len(parts) > 7 else ""})
265
+ return rows
266
+
267
+
268
+ def ps_argv(platform=None):
269
+ platform = platform or sys.platform
270
+ if platform.startswith("linux"):
271
+ return ["ps", "-e", "-ww", "-o", PS_COLUMNS]
272
+ # BSD/macOS: never -e there (it prints the environment).
273
+ return ["ps", "-axww", "-o", PS_COLUMNS]
274
+
275
+
276
+ def zombie(row):
277
+ return row["stat"][:1] in ("Z", "X")
278
+
279
+
280
+ def start_of(row, now):
281
+ return now - row["age"]
282
+
283
+
284
+ def _basename(word):
285
+ return os.path.basename(word.rstrip("/")) or word
286
+
287
+
288
+ def _mask(word, limit=60, shape=SHOWN_WORD):
289
+ raw = word.strip("'\"")
290
+ word = SAFE_WORD.sub("", raw)
291
+ if not word:
292
+ return ""
293
+ if word != raw or "://" in word or "=" in word or not shape.fullmatch(word) or TOKENISH.search(word):
294
+ return "***"
295
+ return word[:limit]
296
+
297
+
298
+ def _script(words):
299
+ """First operand that looks like a script (skipping option values)."""
300
+ skip = False
301
+ for word in words:
302
+ if skip:
303
+ skip = False
304
+ continue
305
+ if word in INLINE_OPTIONS:
306
+ return None
307
+ if word in VALUE_OPTIONS:
308
+ skip = True
309
+ continue
310
+ if word == "--" or word.startswith("-"):
311
+ continue
312
+ if SCRIPT_LIKE.fullmatch(word.strip("'\"")):
313
+ return word
314
+ return None
315
+
316
+
317
+ def _operand(words):
318
+ """First non-option word (``--package=X`` and ``--package X`` give X; values of VALUE_OPTIONS are skipped)."""
319
+ skip = False
320
+ for index, word in enumerate(words):
321
+ if skip:
322
+ skip = False
323
+ continue
324
+ if word.startswith("--package="):
325
+ return word.split("=", 1)[1]
326
+ if word == "--package" and index + 1 < len(words):
327
+ return words[index + 1]
328
+ if word in INLINE_OPTIONS:
329
+ return None
330
+ if word in VALUE_OPTIONS:
331
+ skip = True
332
+ continue
333
+ if word == "--" or word.startswith("-"):
334
+ continue
335
+ return word
336
+ return None
337
+
338
+
339
+ def redact(command):
340
+ """Executable + package/script name only, anything token-like masked: what may be shown."""
341
+ words = (command or "").split()
342
+ while words and ASSIGNMENT.match(words[0].strip("'\"")):
343
+ words = words[1:] # NAME=value prefixes are never shown
344
+ if not words:
345
+ return "?"
346
+ exe = _mask(_basename(words[0]), 40) or "?"
347
+ rest = words[1:]
348
+ parts = [exe]
349
+ if exe in SHELLS and "-c" in rest:
350
+ inner = " ".join(rest[rest.index("-c") + 1:]).strip("'\"")
351
+ inner = re.sub(r"^\s*exec\s+", "", inner)
352
+ return (exe + " -c " + redact(inner))[:80]
353
+ if exe == "env":
354
+ while rest and (rest[0].startswith("-") or ASSIGNMENT.match(rest[0])):
355
+ rest = rest[2:] if rest[0] in ENV_VALUE_OPTIONS else rest[1:]
356
+ return ("env " + redact(" ".join(rest)))[:80] if rest else "env"
357
+ if exe in NPM_LIKE and rest and rest[0] in SUBCOMMANDS:
358
+ parts.append(rest[0])
359
+ package = _operand(rest[1:])
360
+ if package and rest[0] in ("exec", "x", "dlx"):
361
+ parts.append(_mask(package))
362
+ elif package and rest[0] in ("run", "run-script"):
363
+ parts.append(_mask(package, shape=RUN_SCRIPT))
364
+ elif exe in SHELLS:
365
+ script = _script(rest)
366
+ if script:
367
+ parts.append(_mask(_basename(script)))
368
+ elif exe in PACKAGE_RUNNERS:
369
+ package = _operand(rest)
370
+ if package:
371
+ parts.append(_mask(package))
372
+ elif INTERPRETER.fullmatch(exe):
373
+ if "-c" in rest or "-e" in rest or "--eval" in rest:
374
+ parts.append("-c" if "-c" in rest else "-e") # inline code is never shown
375
+ elif "-m" in rest and rest.index("-m") + 1 < len(rest):
376
+ parts += ["-m", _mask(rest[rest.index("-m") + 1])]
377
+ else:
378
+ script = _script(rest)
379
+ if script:
380
+ name = _mask(_basename(script))
381
+ parts.append(name)
382
+ if name in ("npx-cli.js", "npm-cli.js"):
383
+ package = _operand(rest[rest.index(script) + 1:])
384
+ if package:
385
+ parts.append(_mask(package))
386
+ else:
387
+ operand = _operand(rest)
388
+ if operand in SUBCOMMANDS:
389
+ parts.append(operand)
390
+ return " ".join(p for p in parts if p)[:80]
391
+
392
+
393
+ AGENT_NAMES = {"claude": "claude", "codex": "codex", "gemini": "gemini", "agy": "agy", "antigravity": "agy", "devin": "devin"}
394
+
395
+
396
+ AGENT_PATHS = re.compile(r"@anthropic-ai/claude-code|@openai/codex|@google/gemini-cli|/claude-code/|/codex-cli/", re.IGNORECASE)
397
+
398
+
399
+ def agent_cli(command):
400
+ words = (command or "").split()
401
+ while words and ASSIGNMENT.match(words[0]):
402
+ words = words[1:]
403
+ if not words:
404
+ return False
405
+ exe = _basename(words[0]).lower()
406
+ if exe in AGENT_NAMES or AGENT_PATHS.search(command or ""):
407
+ return True
408
+ if INTERPRETER.fullmatch(exe):
409
+ script = _script(words[1:])
410
+ if script and re.sub(r"\.(m?js|cjs)$", "", _basename(script).lower()) in AGENT_NAMES:
411
+ return True
412
+ return False
413
+
414
+
415
+ def children_of(rows):
416
+ kids = {}
417
+ for row in rows:
418
+ kids.setdefault(row["ppid"], []).append(row["pid"])
419
+ return kids
420
+
421
+
422
+ def tree_pids(root, kids):
423
+ """root and every descendant (parents before children)."""
424
+ order, seen = [root], {root}
425
+ for pid in order:
426
+ for child in kids.get(pid, ()):
427
+ if child not in seen:
428
+ seen.add(child)
429
+ order.append(child)
430
+ return order
431
+
432
+
433
+ def ancestry(pid, rows):
434
+ """pid and its ancestors present in rows (stops at pid 1 or a loop)."""
435
+ parent = {r["pid"]: r["ppid"] for r in rows}
436
+ chain, current = [], pid
437
+ while current and current not in chain:
438
+ chain.append(current)
439
+ if current <= 1:
440
+ break
441
+ current = parent.get(current)
442
+ return chain
443
+
444
+
445
+ def kill_trees(entries, grace=5.0, rows_reader=None, kill=None, sleep=time.sleep, clock=time.monotonic,
446
+ interval=0.2, uid=None, self_pid=None):
447
+ """Stop process trees from a snapshot taken before the first signal.
448
+
449
+ entries: [{pid, pgid, uid, command, start}] (find_orphans ``_entries`` or a ledger snapshot).
450
+ TERM every process (and each group it leads when every member of that group is in the
451
+ snapshot), re-snapshot every ``interval`` during ``grace`` to catch new children, recheck
452
+ each pid's command and start time before any later signal (a reused pid is never signalled),
453
+ KILL what is still alive after the grace, and verify. Returns [{pid, command, result}] with
454
+ result terminated, killed, gone (already dead), reused (pid now another process), refused
455
+ (pid 1, this process or an ancestor, another user), denied or survived."""
456
+ if kill is None:
457
+ if table_is_fixture():
458
+ raise RuntimeError("CROW_PS_FIXTURE: a fixture table is never signalled")
459
+ kill = os.kill
460
+ rows_reader = rows_reader or read_table
461
+ uid = (os.getuid() if hasattr(os, "getuid") else 0) if uid is None else uid
462
+ self_pid = os.getpid() if self_pid is None else self_pid
463
+ rows = rows_reader()
464
+ if rows is None:
465
+ return [{"pid": e["pid"], "command": redact(e.get("command")), "result": "unverified"} for e in entries]
466
+ mine = set(ancestry(self_pid, rows)) | {self_pid}
467
+ forbidden_groups = {r["pgid"] for r in rows if r["pid"] in mine}
468
+ try:
469
+ forbidden_groups.add(os.getpgrp())
470
+ except OSError:
471
+ pass
472
+ tracked, results, signalled = {}, {}, {}
473
+ for entry in entries:
474
+ pid = entry.get("pid")
475
+ if not isinstance(pid, int) or pid <= 1 or pid in mine or entry.get("uid", uid) != uid:
476
+ results[pid] = "refused"
477
+ else:
478
+ tracked[pid] = entry
479
+
480
+ def identity(pid, by_pid, now):
481
+ row, entry = by_pid.get(pid), tracked[pid]
482
+ if row is None or zombie(row):
483
+ return "dead"
484
+ if row["command"] != entry["command"] or row["uid"] != uid or abs(start_of(row, now) - entry["start"]) > START_TOLERANCE:
485
+ return "other"
486
+ return "same"
487
+
488
+ def send(pids, sig, rows):
489
+ groups = {}
490
+ for row in rows:
491
+ groups.setdefault(row["pgid"], set()).add(row["pid"])
492
+ for pid in pids:
493
+ entry = tracked[pid]
494
+ owned = {p for p in tracked if results.get(p) not in ("reused", "refused", "denied")}
495
+ if entry.get("pgid") == pid and pid not in forbidden_groups and groups.get(pid, set()) <= owned:
496
+ try:
497
+ kill(-pid, sig)
498
+ for member in groups[pid]: # reached by the group signal: may be gone before its own
499
+ signalled[member] = sig
500
+ except OSError:
501
+ pass
502
+ try:
503
+ kill(pid, sig)
504
+ signalled[pid] = sig
505
+ except ProcessLookupError:
506
+ signalled.setdefault(pid, sig) # alive at the last snapshot: it ended during this stop
507
+ except PermissionError:
508
+ results[pid] = "denied"
509
+
510
+ def settle(rows, now):
511
+ by_pid = {r["pid"]: r for r in rows}
512
+ alive = []
513
+ for pid in list(tracked):
514
+ if pid in results:
515
+ continue
516
+ state = identity(pid, by_pid, now)
517
+ if state == "same":
518
+ alive.append(pid)
519
+ elif pid not in signalled:
520
+ results[pid] = "gone" if state == "dead" else "reused"
521
+ else:
522
+ results[pid] = "killed" if signalled[pid] == signal_kill else "terminated"
523
+ return alive
524
+
525
+ import signal as _signal
526
+ signal_kill = getattr(_signal, "SIGKILL", 9)
527
+ now = time.time()
528
+ alive = settle(rows, now)
529
+ send(alive, _signal.SIGTERM, rows)
530
+ deadline = clock() + max(0.0, grace)
531
+ while alive and clock() < deadline:
532
+ sleep(interval)
533
+ rows, now = rows_reader(), time.time()
534
+ if rows is None:
535
+ break
536
+ alive = settle(rows, now)
537
+ fresh = []
538
+ for row in rows: # children started during the grace (a TERM handler, a respawning wrapper)
539
+ if row["ppid"] in alive and row["pid"] not in tracked and row["uid"] == uid and row["pid"] not in mine and not zombie(row):
540
+ tracked[row["pid"]] = {"pid": row["pid"], "pgid": row["pgid"], "uid": row["uid"], "command": row["command"],
541
+ "start": start_of(row, now)}
542
+ fresh.append(row["pid"])
543
+ if fresh:
544
+ send(fresh, _signal.SIGTERM, rows)
545
+ alive += fresh
546
+ rows, now = rows_reader(), time.time()
547
+ if rows is not None:
548
+ alive = settle(rows, now)
549
+ send(alive, signal_kill, rows)
550
+ for _ in range(20):
551
+ if not alive:
552
+ break
553
+ sleep(min(interval, 0.1))
554
+ rows, now = rows_reader(), time.time()
555
+ if rows is None:
556
+ break
557
+ alive = settle(rows, now)
558
+ for pid in tracked:
559
+ results.setdefault(pid, "survived" if rows is not None else "unverified")
560
+ commands = {e.get("pid"): e.get("command") for e in entries}
561
+ commands.update({pid: e["command"] for pid, e in tracked.items()})
562
+ return [{"pid": pid, "command": redact(commands.get(pid)), "result": result} for pid, result in results.items()]
563
+ # <<< shared
564
+
565
+
566
+ def registered_tree(entry, rows, now):
567
+ """Snapshot (full commands, in memory only) of a registered process and its descendants.
568
+
569
+ Identity is pid + start time (commands change: npm and test workers rename themselves); the
570
+ snapshot carries the command seen NOW, which kill_trees rechecks before every signal. When
571
+ the process itself is gone and its pid not reused, the leftovers of the group it led that
572
+ were reparented (ppid 1) and started while it was last seen alive (``lastSeen``, refreshed by
573
+ add, check, stop and finish) still count: a group id is not reused while any member lives,
574
+ and a later group under a reused pid only has members started after that."""
575
+ alive = [r for r in rows if not zombie(r)]
576
+ by_pid = {r["pid"]: r for r in alive}
577
+ kids = children_of(alive)
578
+ start = entry.get("start") if isinstance(entry.get("start"), (int, float)) else None
579
+ row = by_pid.get(entry.get("pid"))
580
+ roots = []
581
+ if row and start is not None and abs(start_of(row, now) - start) <= LEDGER_TOLERANCE:
582
+ roots = [row["pid"]]
583
+ entry["lastSeen"] = int(now)
584
+ elif row is None and start is not None and entry.get("pgid") == entry.get("pid"):
585
+ seen_alive = entry.get("lastSeen") if isinstance(entry.get("lastSeen"), (int, float)) else start
586
+ roots = [r["pid"] for r in alive if r["pgid"] == entry["pgid"] and r["ppid"] == 1
587
+ and start - LEDGER_TOLERANCE <= start_of(r, now) <= seen_alive + LEDGER_TOLERANCE]
588
+ seen, snapshot = set(), []
589
+ for root in roots:
590
+ for pid in tree_pids(root, kids):
591
+ if pid not in seen and pid in by_pid:
592
+ seen.add(pid)
593
+ r = by_pid[pid]
594
+ snapshot.append({"pid": pid, "pgid": r["pgid"], "uid": r["uid"], "command": r["command"], "start": start_of(r, now)})
595
+ return snapshot
596
+
597
+
598
+ def live_registered(data, rows, now):
599
+ """[(entry, snapshot)] for registered processes whose tree is still alive."""
600
+ result = []
601
+ for entry in data.get("processes") or []:
602
+ if isinstance(entry, dict) and entry.get("status", "running") in ("running", "survived"):
603
+ snapshot = registered_tree(entry, rows, now)
604
+ if snapshot:
605
+ result.append((entry, snapshot))
606
+ return result
607
+
608
+
609
+ def proc_line(entry, state):
610
+ unit = " [" + clean(entry.get("unit"), 30) + "]" if entry.get("unit") else ""
611
+ return str(entry.get("pid")) + " " + clean(entry.get("command"), 80) + unit + ": " + state
612
+
613
+
154
614
  def probe_decision(text):
155
615
  """Fields of a resources decision from `crow-skills resources --json` (envelope or bare document)."""
156
616
  try:
@@ -300,6 +760,15 @@ def main(argv=None):
300
760
  res.add_argument("--pressure", choices=RESOURCE_LEVELS)
301
761
  res.add_argument("--source", choices=RESOURCE_SOURCES, help="probe (crow-skills), os (comandos do sistema) ou assumed")
302
762
  res.add_argument("--note", help="uma linha: o que foi decidido e por quê")
763
+ proc = sub.add_parser("proc", help="registra, confere ou encerra (árvore inteira) processos que esta execução iniciou")
764
+ proc.add_argument("action", choices=("add", "stop", "check"))
765
+ proc.add_argument("--pid", type=int, action="append", default=[], help="add: o pid iniciado; stop: repetir para vários")
766
+ proc.add_argument("--unit", help="add: unidade dona; stop: todos os processos desta unidade")
767
+ proc.add_argument("--owner", help="add: dono (main, subagent:<nome>, workflow:<id>)")
768
+ proc.add_argument("--all", action="store_true", help="stop: todos os processos registrados ainda vivos")
769
+ proc.add_argument("--grace", type=float, default=5.0, help="stop: segundos entre TERM e KILL (padrão 5)")
770
+ proc.add_argument("--adopt", action="store_true",
771
+ help="add: aceitar um processo que começou antes desta execução (decisão explícita; padrão: recusa)")
303
772
  finish = sub.add_parser("finish")
304
773
  finish.add_argument("--status", choices=RUN_STATUSES[1:], default="done")
305
774
  for name in ("show", "path"):
@@ -308,7 +777,7 @@ def main(argv=None):
308
777
  if name == "show":
309
778
  child.add_argument("--tree", action="store_true", help="árvore de fases com barras, em vez da lista de processos")
310
779
  child.add_argument("--ascii", action="store_true", help="lista de processos só com ASCII")
311
- for child in (phase, unit, res, finish):
780
+ for child in (phase, unit, res, proc, finish):
312
781
  child.add_argument("--run")
313
782
  args = p.parse_args(argv)
314
783
 
@@ -327,7 +796,7 @@ def main(argv=None):
327
796
  save(path, data)
328
797
  print(run_id + " " + str(path))
329
798
  return 0
330
- path, data = locate(getattr(args, "run", None), write=args.command in ("phase", "unit", "resources", "finish"))
799
+ path, data = locate(getattr(args, "run", None), write=args.command in ("phase", "unit", "resources", "proc", "finish"))
331
800
  if args.command == "path":
332
801
  print(path)
333
802
  return 0
@@ -390,12 +859,159 @@ def main(argv=None):
390
859
  decision["note"] = clean(args.note, 160)
391
860
  decision["checkedAt"] = now()
392
861
  data["resources"] = {k: v for k, v in decision.items() if v is not None}
862
+ elif args.command == "proc":
863
+ args.ledger_path = path
864
+ code = proc_command(args, data)
865
+ save(path, data) # check too: it refreshes lastSeen of the registered processes still alive
866
+ return code
393
867
  elif args.command == "finish":
868
+ rows = read_table() if data.get("processes") else None
869
+ alive = live_registered(data, rows, time.time()) if rows is not None else []
870
+ if alive:
871
+ print("crow_ledger: aviso: " + str(len(alive)) + " processo(s) registrado(s) ainda vivo(s): " +
872
+ "; ".join(proc_line(entry, str(len(snap)) + " na árvore") for entry, snap in alive) +
873
+ ". Encerre com: proc stop --run " + str(data.get("id")) + " --all", file=sys.stderr)
394
874
  data["status"] = args.status
395
875
  data["endedAt"] = now()
876
+ for entry in data.get("processes") or []: # the run is over: its processes are no longer protected
877
+ if isinstance(entry, dict):
878
+ drop_registration(data, entry.get("pid"))
396
879
  save(path, data)
397
880
  return 0
398
881
 
399
882
 
883
+ def registrations_dir():
884
+ """Cwd-independent pointers to registrations (same place as crow_skills/broadcast.py reads):
885
+ an orphan check run from any directory or repository sees this run's processes."""
886
+ return Path.home() / ".local" / "state" / "crow-skills" / "registrations"
887
+
888
+
889
+ def registration_path(run_id, pid):
890
+ return registrations_dir() / (re.sub(r"[^A-Za-z0-9_.-]", "-", str(run_id))[:80] + "-" + str(int(pid)) + ".json")
891
+
892
+
893
+ def write_registration(data, ledger_path, entry):
894
+ """Best effort: a failure only means the pointer is missing (the ledger itself still protects
895
+ the process from its own directory)."""
896
+ try:
897
+ directory = registrations_dir()
898
+ for part in (Path.home() / ".local", Path.home() / ".local" / "state", directory.parent, directory):
899
+ if part.is_symlink():
900
+ return False
901
+ directory.mkdir(parents=True, exist_ok=True, mode=0o700)
902
+ pointer = {"schema": "crow-registration/1", "run": data.get("id"), "ledger": str(Path(ledger_path).resolve()),
903
+ "pid": entry["pid"], "start": entry["start"], "registeredAt": entry["registeredAt"]}
904
+ for key in ("cliPid", "cliStart"):
905
+ if key in entry:
906
+ pointer[key] = entry[key]
907
+ path = registration_path(data.get("id"), entry["pid"])
908
+ fd, temp = tempfile.mkstemp(dir=directory, prefix="." + path.name + ".")
909
+ try:
910
+ with os.fdopen(fd, "w", encoding="utf-8") as handle:
911
+ json.dump(pointer, handle)
912
+ os.chmod(temp, 0o600)
913
+ os.replace(temp, path)
914
+ finally:
915
+ if os.path.exists(temp):
916
+ os.unlink(temp)
917
+ return True
918
+ except OSError:
919
+ return False
920
+
921
+
922
+ def drop_registration(data, pid):
923
+ try:
924
+ os.unlink(registration_path(data.get("id"), pid))
925
+ except (OSError, TypeError, ValueError):
926
+ pass
927
+
928
+
929
+ def caller_cli(rows, now_ts):
930
+ """The agent CLI this script runs under: the nearest ancestor that is an agent CLI, or None."""
931
+ by_pid = {r["pid"]: r for r in rows}
932
+ for pid in ancestry(os.getpid(), rows)[1:]:
933
+ row = by_pid.get(pid)
934
+ if row and pid > 1 and agent_cli(row["command"]):
935
+ return row["pid"], int(round(start_of(row, now_ts)))
936
+ return None
937
+
938
+
939
+ def parse_iso(value):
940
+ try:
941
+ return datetime.fromisoformat(str(value)).timestamp()
942
+ except (TypeError, ValueError):
943
+ return None
944
+
945
+
946
+ def proc_command(args, data):
947
+ processes = data.setdefault("processes", [])
948
+ rows = read_table()
949
+ if rows is None:
950
+ raise SystemExit("crow_ledger: tabela de processos indisponível (ps).")
951
+ current = time.time()
952
+ if args.action == "add":
953
+ if len(args.pid) != 1:
954
+ raise SystemExit("crow_ledger: proc add exige exatamente um --pid.")
955
+ row = next((r for r in rows if r["pid"] == args.pid[0] and not zombie(r)), None)
956
+ uid = os.getuid() if hasattr(os, "getuid") else None
957
+ if row is None or args.pid[0] <= 1 or (uid is not None and row["uid"] != uid):
958
+ raise SystemExit("crow_ledger: pid " + str(args.pid[0]) + " não está vivo ou não é deste usuário.")
959
+ start = start_of(row, current)
960
+ run_start = parse_iso(data.get("startedAt"))
961
+ if run_start is not None and start < run_start - LEDGER_TOLERANCE and not args.adopt:
962
+ raise SystemExit("crow_ledger: pid " + str(row["pid"]) + " começou antes desta execução; não foi ela que o iniciou. "
963
+ "Registre só o que a execução iniciou (--adopt só com decisão explícita de assumir esse processo).")
964
+ processes[:] = [p for p in processes if not (isinstance(p, dict) and p.get("pid") == row["pid"] and p.get("status") == "running")]
965
+ entry = {"pid": row["pid"], "pgid": row["pgid"], "command": redact(row["command"]), "start": int(round(start)),
966
+ "startedAt": datetime.fromtimestamp(start, timezone.utc).isoformat(timespec="seconds"),
967
+ "registeredAt": now(), "status": "running", "lastSeen": int(current)}
968
+ if run_start is not None and start < run_start - LEDGER_TOLERANCE:
969
+ entry["adopted"] = True
970
+ cli = caller_cli(rows, current)
971
+ if cli: # protected from orphan checks exactly while this CLI lives
972
+ entry["cliPid"], entry["cliStart"] = cli
973
+ if args.unit:
974
+ entry["unit"] = clean(args.unit, 60)
975
+ if args.owner:
976
+ entry["owner"] = clean(args.owner, 60)
977
+ processes.append(entry)
978
+ pointer = write_registration(data, args.ledger_path, entry)
979
+ print(proc_line(entry, "registrado (pgid " + str(row["pgid"]) + ")" + ("" if pointer else "; sem ponteiro de registro")))
980
+ return 0
981
+ alive = live_registered(data, rows, current)
982
+ if args.action == "check":
983
+ for entry in processes:
984
+ if isinstance(entry, dict):
985
+ snap = next((s for e, s in alive if e is entry), None)
986
+ state = ("vivo, " + str(len(snap)) + " processo(s) na árvore") if snap else clean(entry.get("status") if entry.get("status") not in ("running", "survived") else "encerrado")
987
+ print(proc_line(entry, state))
988
+ if not processes:
989
+ print("nenhum processo registrado")
990
+ return 1 if alive else 0
991
+ chosen = [(e, s) for e, s in alive if args.all or e.get("pid") in args.pid or (args.unit and e.get("unit") == args.unit)]
992
+ if not (args.all or args.pid or args.unit):
993
+ raise SystemExit("crow_ledger: proc stop exige --pid, --unit ou --all.")
994
+ if table_is_fixture():
995
+ raise SystemExit("crow_ledger: CROW_PS_FIXTURE definido; uma tabela de teste nunca é sinalizada.")
996
+ for entry in processes: # selected but already gone: record it
997
+ if isinstance(entry, dict) and entry.get("status") == "running" and all(entry is not e for e, _ in alive) and \
998
+ (args.all or entry.get("pid") in args.pid or (args.unit and entry.get("unit") == args.unit)):
999
+ entry.update(status="exited", stoppedAt=now())
1000
+ drop_registration(data, entry.get("pid"))
1001
+ print(proc_line(entry, "já tinha saído"))
1002
+ failed = 0
1003
+ for entry, snapshot in chosen:
1004
+ results = kill_trees(snapshot, grace=max(0.1, min(args.grace, 120.0)))
1005
+ left = [r for r in results if r["result"] in ("survived", "denied", "unverified")]
1006
+ if not left:
1007
+ drop_registration(data, entry.get("pid"))
1008
+ entry.update(status="survived" if left else "stopped", stoppedAt=now(),
1009
+ result={k: sum(1 for r in results if r["result"] == k) for k in sorted({r["result"] for r in results})})
1010
+ failed += bool(left)
1011
+ print(proc_line(entry, ("sobreviveram " + str(len(left))) if left else
1012
+ "encerrado (" + ", ".join(str(v) + " " + k for k, v in entry["result"].items()) + ")"))
1013
+ return 1 if failed else 0
1014
+
1015
+
400
1016
  if __name__ == "__main__":
401
1017
  sys.exit(main())