task-pipeline-skill 1.99.1 → 1.100.0

package/plugins/task-pipeline/skills/task-pipeline/scripts/resource_guard.py

@@ -0,0 +1,338 @@
+#!/usr/bin/env python3
+"""The machine a browser run borrows: check its load, record what the run starts, close
+exactly that, and prove nothing is left. Stdlib only; macOS and Linux.
+
+    resource_guard.py check  [--max-load-ratio 1.0] [--min-free-gb 5]
+                             [--max-memory-pressure normal|warn] [--json]
+        before a run and between scenarios: load average against cores, memory pressure,
+        free disk. Exit 0 go; 4 wait (over a line: wait, then run with fewer pages).
+    resource_guard.py record <ledger.json> <pid> <what> [--cap-kind browser|page|server]
+                             [--max-browsers 2] [--max-pages 4] [--max-servers 1]
+        after starting a process: append it with its command line. Exit 5 when the cap for
+        its kind is already reached; the caller closes something first.
+    resource_guard.py close  <ledger.json> [--grace 5]
+        at the end: SIGTERM, then SIGKILL after the grace, every RECORDED process that is
+        still alive and still the same process (its start time is compared, which survives
+        an exec, so a reused pid is never touched), and the descendants it spawned (browser
+        helpers, a launcher's child). Nothing else is ever signalled.
+    resource_guard.py verify <ledger.json> [--json]
+        exit 0 when every recorded process is gone; 1 naming the live ones; 2 when a process
+        cannot be inspected (no `ps`): never silently clean. Prints the receipt the
+        design-review report carries (`resources`).
+
+The operator's own browser windows are never in the ledger, so they are never touched.
+Exit codes: 0 ok · 1 live processes · 2 usage · 4 wait · 5 cap reached.
+"""
+from __future__ import annotations
+
+import argparse
+import fcntl
+import json
+import os
+import tempfile
+import shutil
+import signal
+import subprocess
+import sys
+import time
+
+
+def cpu_count():
+    return os.cpu_count() or 1
+
+
+def load_avg():
+    try:
+        return os.getloadavg()[0]
+    except OSError:
+        return None
+
+
+def memory_pressure():
+    """'normal' | 'warn' | 'critical' | None (unknown)."""
+    if sys.platform == "darwin":
+        try:
+            out = subprocess.run(["sysctl", "-n", "kern.memorystatus_vm_pressure_level"],
+                                 capture_output=True, text=True, timeout=5).stdout.strip()
+            return {"1": "normal", "2": "warn", "4": "critical"}.get(out)
+        except (OSError, subprocess.SubprocessError):
+            return None
+    try:
+        with open("/proc/meminfo") as fh:
+            info = {l.split(":")[0]: int(l.split()[1]) for l in fh if ":" in l}
+        avail = info.get("MemAvailable", 0) / max(info.get("MemTotal", 1), 1)
+        return "critical" if avail < 0.05 else "warn" if avail < 0.15 else "normal"
+    except (OSError, ValueError, IndexError):
+        return None
+
+
+LEVELS = ("normal", "warn", "critical")
+
+
+def check(max_load_ratio, min_free_gb, max_memory="normal"):
+    la, cores = load_avg(), cpu_count()
+    mem = memory_pressure()
+    free_gb = shutil.disk_usage(os.path.expanduser("~")).free / 1e9
+    reasons = []
+    if la is not None and la > cores * max_load_ratio:
+        reasons.append("load %.1f over %d cores × %.1f" % (la, cores, max_load_ratio))
+    if mem in LEVELS and LEVELS.index(mem) > LEVELS.index(max_memory):
+        reasons.append("memory pressure %s over %s" % (mem, max_memory))
+    if free_gb < min_free_gb:
+        reasons.append("free disk %.1f GB under %.0f GB" % (free_gb, min_free_gb))
+    return dict(go=not reasons, load=la, cores=cores, memory=mem or "unknown",
+                free_gb=round(free_gb, 1), reasons=reasons)
+
+
+class Uninspectable(Exception):
+    pass
+
+
+def exists(pid):
+    try:
+        os.kill(int(pid), 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+
+
+# Every ps runs in one locale and one zone: `lstart` is a different string under each, and a
+# start time read under another TZ would make a live process look like a stranger.
+PS_ENV = dict(os.environ, LC_ALL="C", LANG="C", TZ="UTC")
+
+
+def ps_field(pid, field):
+    """A `ps -o <field>=` value for one pid; None when the pid is gone; Uninspectable when
+    `ps` itself cannot run (the caller must not read that as gone)."""
+    try:
+        out = subprocess.run(["ps", "-o", field + "=", "-p", str(pid)], capture_output=True,
+                             text=True, timeout=5, env=PS_ENV)
+    except (OSError, subprocess.SubprocessError) as exc:
+        raise Uninspectable("ps unavailable (%s)" % exc)
+    if out.returncode not in (0, 1):
+        raise Uninspectable("ps exited %s" % out.returncode)
+    return out.stdout.strip() or None
+
+
+def started(pid):
+    return ps_field(pid, "lstart")
+
+
+def alive_same(entry):
+    """True: the recorded process is still running (same pid, same start time). False: it is
+    gone, or the pid now belongs to another process. Uninspectable: cannot tell."""
+    if not exists(entry["pid"]):
+        return False
+    now = started(entry["pid"])
+    if now is None:
+        return False
+    return now == entry.get("started")
+
+
+def descendants(pids):
+    """Every live descendant of the given pids, from one `ps -A -o pid=,ppid=` table."""
+    try:
+        out = subprocess.run(["ps", "-A", "-o", "pid=,ppid="], capture_output=True, text=True, timeout=5,
+                             env=PS_ENV).stdout
+    except (OSError, subprocess.SubprocessError) as exc:
+        raise Uninspectable("ps unavailable (%s)" % exc)
+    kids = {}
+    for line in out.splitlines():
+        parts = line.split()
+        if len(parts) == 2 and parts[0].isdigit() and parts[1].isdigit():
+            kids.setdefault(int(parts[1]), []).append(int(parts[0]))
+    seen, todo = set(), list(pids)
+    while todo:
+        p = todo.pop()
+        for c in kids.get(p, []):
+            if c not in seen:
+                seen.add(c)
+                todo.append(c)
+    return sorted(seen)
+
+
+def load_ledger(path):
+    if not os.path.exists(path):
+        return {"schema": "resource-ledger/1", "started": []}
+    with open(path, encoding="utf-8") as fh:
+        doc = json.load(fh)
+    if doc.get("schema") != "resource-ledger/1" or not isinstance(doc.get("started"), list):
+        raise ValueError("not a resource-ledger/1 file")
+    return doc
+
+
+def save_ledger(path, doc):
+    d = os.path.dirname(os.path.abspath(path))
+    os.makedirs(d, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=d, prefix=".resource-ledger.", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            json.dump(doc, fh, indent=2)
+            fh.write("\n")
+        os.replace(tmp, path)
+    finally:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+
+
+class locked:
+    """An exclusive lock on the ledger's sidecar for a whole read-modify-write: two agents
+    recording at once both land."""
+    def __init__(self, path):
+        self.lock = os.path.abspath(path) + ".lock"
+
+    def __enter__(self):
+        os.makedirs(os.path.dirname(self.lock), exist_ok=True)
+        self.fh = open(self.lock, "a")
+        fcntl.flock(self.fh, fcntl.LOCK_EX)
+        return self
+
+    def __exit__(self, *exc):
+        fcntl.flock(self.fh, fcntl.LOCK_UN)
+        self.fh.close()
+
+
+def ancestors():
+    """This process and every ancestor up to pid 1: never recorded, never signalled."""
+    out, p = {os.getpid()}, os.getpid()
+    for _ in range(64):
+        try:
+            pp = int(ps_field(p, "ppid") or 0)
+        except ValueError:
+            break
+        if pp <= 1 or pp in out:
+            break
+        out.add(pp)
+        p = pp
+    return out | {1}
+
+
+def record(path, pid, what, kind, caps):
+    if int(pid) in ancestors():
+        return 2, "pid %s is this process, one of its ancestors or pid 1: never recorded" % pid
+    with locked(path):
+        doc = load_ledger(path)
+        live = [e for e in doc["started"] if e.get("kind") == kind and alive_same(e)]
+        if len(live) >= caps[kind]:
+            return 5, "cap reached: %d live %s(s), the cap is %d; close one first" % (len(live), kind, caps[kind])
+        if not exists(pid):
+            return 2, "pid %s is not running; nothing to record" % pid
+        st = started(pid)
+        if not st:
+            return 2, "pid %s is not running; nothing to record" % pid
+        doc["started"].append(dict(pid=int(pid), what=what, kind=kind, started=st,
+                                   command=ps_field(pid, "command") or "", at=int(time.time())))
+        save_ledger(path, doc)
+        return 0, "recorded %s %s (%s)" % (kind, pid, what)
+
+
+def close(path, grace):
+    with locked(path):
+        doc = load_ledger(path)
+    keep = ancestors()
+    alive = [e for e in doc["started"] if alive_same(e)]
+    # A protected pid (this process, an ancestor, pid 1) in the ledger is refused with its whole
+    # subtree: its descendants are the operator's session, never this run's.
+    protected = [e["pid"] for e in alive if e["pid"] in keep]
+    targets = [e for e in alive if e["pid"] not in keep]
+    # Children first are found while their parents still live; each keeps its own start time
+    # so a pid reused during the grace is not signalled.
+    kids = [dict(pid=k, started=started(k)) for k in descendants([e["pid"] for e in targets])]
+    victims = [dict(pid=e["pid"], started=e["started"]) for e in targets] + \
+              [k for k in kids if k["started"] and k["pid"] not in keep]
+    refused = list(protected)
+    for v in victims:
+        try:
+            os.kill(v["pid"], signal.SIGTERM)
+        except ProcessLookupError:
+            pass
+        except PermissionError:
+            refused.append(v["pid"])
+    deadline = time.time() + grace
+    while time.time() < deadline and any(alive_same(v) for v in victims):
+        time.sleep(0.2)
+    for v in victims:
+        if v["pid"] not in refused and alive_same(v):
+            try:
+                os.kill(v["pid"], signal.SIGKILL)
+            except ProcessLookupError:
+                pass
+            except PermissionError:
+                refused.append(v["pid"])
+    skipped = [e["pid"] for e in doc["started"] if e not in targets]
+    return [e["pid"] for e in targets], [k["pid"] for k in kids], skipped, refused
+
+
+def verify(path):
+    doc = load_ledger(path)
+    live = [e["pid"] for e in doc["started"] if alive_same(e)]
+    return dict(started=[dict(pid=e["pid"], what=e["what"], kind=e.get("kind")) for e in doc["started"]],
+                live=live, closed=not live)
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    c = sub.add_parser("check")
+    c.add_argument("--max-load-ratio", type=float, default=1.0)
+    c.add_argument("--min-free-gb", type=float, default=5)
+    c.add_argument("--max-memory-pressure", default="normal", choices=("normal", "warn"))
+    c.add_argument("--json", action="store_true")
+    r = sub.add_parser("record")
+    r.add_argument("ledger")
+    r.add_argument("pid", type=int)
+    r.add_argument("what")
+    r.add_argument("--cap-kind", dest="kind", default="browser", choices=("browser", "page", "server"))
+    r.add_argument("--max-browsers", type=int, default=2)
+    r.add_argument("--max-pages", type=int, default=4)
+    r.add_argument("--max-servers", type=int, default=1)
+    k = sub.add_parser("close")
+    k.add_argument("ledger")
+    k.add_argument("--grace", type=float, default=5)
+    v = sub.add_parser("verify")
+    v.add_argument("ledger")
+    v.add_argument("--json", action="store_true")
+    a = ap.parse_args(argv)
+    try:
+        if a.cmd == "check":
+            res = check(a.max_load_ratio, a.min_free_gb, a.max_memory_pressure)
+            if a.json:
+                print(json.dumps(res, indent=2))
+            else:
+                print("resource_guard: %s · load %s/%d cores · memory %s · free %.1f GB%s" % (
+                    "go" if res["go"] else "wait", res["load"], res["cores"], res["memory"], res["free_gb"],
+                    "" if res["go"] else " · " + "; ".join(res["reasons"])))
+            return 0 if res["go"] else 4
+        if a.cmd == "record":
+            caps = dict(browser=a.max_browsers, page=a.max_pages, server=a.max_servers)
+            code, msg = record(a.ledger, a.pid, a.what, a.kind, caps)
+            print("resource_guard: %s" % msg, file=sys.stderr if code else sys.stdout)
+            return code
+        if a.cmd == "close":
+            closed, kids, skipped, refused = close(a.ledger, a.grace)
+            print("resource_guard: closed %d recorded process(es) and %d descendant(s); %d already gone"
+                  % (len(closed), len(kids), len(skipped))
+                  + ("; refused (permission): %s" % ", ".join(map(str, refused)) if refused else ""))
+            return 1 if refused else 0
+        res = verify(a.ledger)
+        # The zero-byte lock sidecar stays: unlinking it while another agent holds it would let
+        # two writers in. It lives beside the ledger in .task-pipeline/, outside the tracked tree.
+        if a.json:
+            print(json.dumps(res, indent=2))
+        else:
+            print("resource_guard: %s · %d started · live: %s" % (
+                "clean" if res["closed"] else "LIVE", len(res["started"]), ", ".join(map(str, res["live"])) or "none"))
+        return 0 if res["closed"] else 1
+    except Uninspectable as exc:
+        print("resource_guard: NOT_RUN: %s; a process that cannot be inspected is never reported gone" % exc,
+              file=sys.stderr)
+        return 2
+    except (ValueError, OSError) as exc:
+        print("resource_guard: %s" % exc, file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/plugins/task-pipeline/skills/task-pipeline/scripts/waves.py

@@ -32,7 +32,7 @@ reviewed; a table and a re-run can. This script is that re-run:
         (a plan that spans several repositories' graphs).
     waves.py finish --inventory FILE --max-rounds N --max-releases M (--rounds K | --ledger RUN.md)
                     --checks K/M --artefact NAME@SHA [--releases R] [--operator-go]
-                    [--clean-rounds 1|2]
+                    [--clean-rounds 1|2] [--max-agents 2]
         the finish-line verdict (`references/finish-line.md`) from the triaged items, and the
         finish block printed. Only `triage: blocking` items count, less those closed as
         duplicate, stale or not-reproduced; deferred and noise never change the verdict. The
@@ -47,7 +47,10 @@ reviewed; a table and a re-run can. This script is that re-run:
         self-inflicted >= new, from round 2 on); 3 continue (including no --checks); 1
         malformed (a schema error, a blocking item without `test` or `round`, B3 with
         base_repro yes, a round past the rounds run, no round count, a ledger that disagrees,
-        --max-rounds below 2, an artefact that is not NAME@SHA).
+        --max-rounds below 2, an artefact that is not NAME@SHA). Since 1.100.0 the ledger's
+        `agents: <N> — <k>` lines (the most sub-agents running at once in round N) are read
+        too: a round over --max-agents (run.finish.maxAgents, 2 by default) is a budget
+        verdict, exit 5, unless --operator-go.
 
 **The plan** is any JSON whose `nodes` list `{id, wave, closes}` — a work graph that carries
 `closes` on its nodes is one, and so is a short hand-written table. A node may carry
@@ -559,6 +562,7 @@ def cmd_sync_graph(a) -> int:
 # A blocking item closed as one of these was never a blocker: it counts in no round.
 NOT_COUNTED = ("duplicate", "stale", "not-reproduced")
 ROUND_LINE = re.compile(r"^round:\s*(\d+)\s*[—-]\s*(.*?)\s*[—-]\s*new blocking\s*(\d+)\s*$")
+AGENTS_LINE = re.compile(r"^agents:\s*(\d+)\s*[—-]\s*(\d+)\b")
 ARTEFACT = re.compile(r"^[^@\s]+@[0-9a-f]{7,40}$")
 
 
@@ -598,6 +602,27 @@ def ledger_rounds(path: pathlib.Path) -> dict[int, int]:
     return out
 
 
+def ledger_agents(path: pathlib.Path) -> dict[int, int]:
+    """{round: most sub-agents at once} from the run ledger's `agents:` lines (since 1.100.0).
+    A round written twice keeps its larger count: the budget is about the peak."""
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as exc:
+        raise Fail(1, [f"the run ledger {path} cannot be read ({type(exc).__name__})"])
+    out, errs = {}, []
+    for n, line in enumerate(text.splitlines(), 1):
+        if not line.startswith("agents:"):
+            continue
+        m = AGENTS_LINE.match(line.strip())
+        if not m:
+            errs.append(f"{path}:{n}: not `agents: <N> — <k>`")
+            continue
+        out[int(m[1])] = max(out.get(int(m[1]), 0), int(m[2]))
+    if errs:
+        raise Fail(1, errs)
+    return out
+
+
 def finish_verdict(items: list[dict], rounds: int, max_rounds: int, max_releases: int,
                    releases: int, checks: tuple[int, int] | None,
                    operator_go: bool = False, clean_rounds: int = 1) -> tuple[int, str, dict]:
@@ -693,12 +718,31 @@ def cmd_finish(a) -> int:
         raise Fail(1, [f"--artefact {a.artefact!r} is not NAME@SHA (a commit of 7-40 hex digits)"])
     code, word, f = finish_verdict(items, rounds, a.max_rounds, a.max_releases, a.releases, checks,
                                    a.operator_go, a.clean_rounds)
+    # The parallel-agent budget (run.finish.maxAgents): a round that ran more sub-agents at
+    # once than the budget allows stops the iteration like any other budget, said with the
+    # numbers; the operator's go lifts it, out loud.
+    agents = ledger_agents(pathlib.Path(a.ledger)) if a.ledger else {}
+    if a.max_agents < 1:
+        raise Fail(1, [f"--max-agents {a.max_agents} is below 1"])
+    stray = sorted(r for r in agents if r < 1 or r > rounds)
+    if stray:
+        raise Fail(1, [f"{a.ledger}: an `agents:` line names round {r}, and only rounds 1..{rounds} ran"
+                       for r in stray])
+    over = sorted((r, k) for r, k in agents.items() if k > a.max_agents)
+    named = ", ".join(f"round {r}: {k}/{a.max_agents}" for r, k in over)
+    if over and not a.operator_go and code in (0, 3):
+        code, word = 5, "budget"
+        f = dict(f, why="agents over budget — " + named)
+    elif over and a.operator_go and code in (0, 3):
+        f = dict(f, why=((f.get("why") + "; ") if f.get("why") else "") + "agents over budget on the operator's go — " + named)
     deferred = sorted((x for x in items if x.get("triage") == "deferred"), key=_priority)
     noise = [x for x in items if x.get("triage") == "noise"]
     risks = [x for x in deferred if x.get("blast") == 3 or x.get("rung") in ("I4", "I5")]
     pool = sorted((x for x in items if x.get("triage") != "blocking" and _needs_node(x)
                    and x.get("triage") != "noise"), key=_priority)
-    budget = f"rounds {f['rounds']}/{a.max_rounds} — releases {a.releases}/{a.max_releases}"
+    peak = max(agents.values()) if agents else None
+    budget = (f"rounds {f['rounds']}/{a.max_rounds} — releases {a.releases}/{a.max_releases} — agents "
+              + (f"{peak}/{a.max_agents}" if peak is not None else f"unrecorded/{a.max_agents}"))
     if word == "continue":
         print(f"next round: {f['rounds'] + 1}/{a.max_rounds} — {f['why']} — {budget}")
     else:
@@ -756,8 +800,11 @@ def main(argv: list[str]) -> int:
     f.add_argument("--rounds", type=int, help="rounds run, clean ones included")
     f.add_argument("--ledger", help="the run ledger; its `round:` lines are the round count")
     f.add_argument("--operator-go", action="store_true",
-                   help="the operator's recorded go for rounds past --max-rounds")
+                   help="the operator's recorded go for rounds past --max-rounds and sub-agents past "
+                        "--max-agents; the block says which budget it lifted")
     f.add_argument("--checks", help="K/M — exit checks green on the artefact")
+    f.add_argument("--max-agents", type=int, default=2,
+                   help="run.finish.maxAgents: sub-agents running at once in one round (default 2)")
     f.add_argument("--artefact", help="what they ran on, as NAME@SHA")
     a = p.parse_args(argv)
     verbs = {"merge": cmd_merge, "assign": cmd_assign, "count": cmd_count, "validate": cmd_validate,

package/plugins/task-pipeline/skills/task-pipeline/templates/run.md

@@ -20,7 +20,7 @@ Run: `<topic>` · started `<YYYY-MM-DD>` · module map: `<path or "none">`
 
 ## `read:` — which doctrine this run actually opened
 
-The bundle is 53 reference files and nothing recorded which of them a run read, so **a
+The bundle is 54 reference files and nothing recorded which of them a run read, so **a
 skipped file and a read one were indistinguishable** — the class every guard in this
 pipeline exists to catch, left standing over the doctrine itself.
 
@@ -48,7 +48,7 @@ same claim one level down.
 |---|---|---|
 | `unmeasured — no run ledger` | there is no ledger | nothing to read from |
 | `unmeasured — the ledger carries no read: lines` | the hook is absent, **or** the run opened no doctrine | two opposite facts, and the ledger cannot separate them, so neither is claimed |
-| `N of 53 reference files read — unattested`, then each unread one | the hook is installed and fired | the count alone says there is a gap, not where — and `unattested` says the ledger cannot name who wrote the lines |
+| `N of 54 reference files read — unattested`, then each unread one | the hook is installed and fired | the count alone says there is a gap, not where — and `unattested` says the ledger cannot name who wrote the lines |
 
 **It is a disclosure: no floor, no direction, never a target.** A run that needs four files
 and reads four is not worse than one that reads thirty — and the moment the number becomes
@@ -73,7 +73,8 @@ event: <compact|session-end|subagent|memory> — <detail> — <ISO-8601>
 review: <stage id> — surface <name> — rounds <N> — <returned|approved|unresolved> — <ISO-8601>
 finding: <id> — blocking:B<n> | deferred:B-NNN | noise — round <N> — base-repro yes|no|n/a
 round: <N> — <reading> — new blocking <k>
-finish: done|budget|blocked — rounds <n>/<max> — releases <n>/<max>
+agents: <N> — <most sub-agents running at once in round N>
+finish: done|budget|blocked — rounds <n>/<max> — releases <n>/<max> — agents <n>/<max>
 read:  references/<file>.md            # hook-appended, deduped, UNATTESTED (no writer field)
 ```
 
@@ -161,6 +162,7 @@ review: 6 — surface landing — rounds 1 — returned — 2026-08-10T12:02Z
 finding: F-021 — blocking:B3 — round 1 — base-repro no
 finding: F-022 — deferred:B-118 — round 1 — base-repro yes
 round: 1 — exit checks + audit axis seams — new blocking 1
+agents: 1 — 2
 finding: F-023 — noise — round 2 — base-repro n/a
 round: 2 — exit checks + observer — new blocking 0
 round: 3 — exit checks + post-release readback — new blocking 0
@@ -169,7 +171,7 @@ hand:  3 — task "add CSV export to the orders table" — done 2 — surfaced 1
        scope 5f21ac3/node-24-linux/REQ-001,REQ-004 — unverified 1 (XLSX path: no fixture)
 holds: 5 — 2 (worktree: build-csv-export, this run; container: pg-test, this run) — enumerated 8/8 classes
 holds: 10 — none — enumerated 7/8 classes, unlooked: containers (no docker on this host)
-finish: done — rounds 3/3 — releases 1/2
+finish: done — rounds 3/3 — releases 1/2 — agents 2/2
 ```
 
 The last two lines are a **trip**: the same file, two consecutive passes, the same