lab-kit-cli 0.1.0__py3-none-any.whl

lab_kit/checks/results.py

@@ -0,0 +1,172 @@
+"""Checks on results and scores: numbers re-derive, results rest on finished runs, scores match the lock."""
+
+from __future__ import annotations
+
+from pathlib import PurePosixPath
+
+from .. import protocol as protocol_mod
+from .. import records
+from .. import rederive as rederive_mod
+from ..errors import LabError
+from ..lab import Lab
+from .base import Reporter
+
+SCORE_KEYS = ("protocol", "lock", "review", "scores", "record")
+# The journal kinds that can say why a scored experiment has no report.
+EXPLAINING_KINDS = ("lesson", "kill", "decision", "pivot")
+
+
+def _doc_path(lab: Lab, doc) -> str:
+    return lab.doc_path(doc.meta_file.path) if doc.meta_file else doc.key
+
+
+def rederive(lab: Lab, rep: Reporter) -> None:
+    """Every live result's re-derive command prints its number exactly."""
+    for doc in rederive_mod.live_results(lab):
+        outcome = rederive_mod.run(lab, doc)
+        if not outcome.ok:
+            rep.add(_doc_path(lab, doc), f"{doc.id} does not re-derive: {outcome.detail}")
+
+
+def read_score(lab: Lab, slug: str) -> dict | None:
+    path = records.score_path(lab, slug)
+    if not path.is_file():
+        return None
+    data = records.read_yaml(path, lab.rel(path))
+    missing = [k for k in SCORE_KEYS if k not in data]
+    if missing:
+        raise LabError(f"{lab.rel(path)}: missing {', '.join(missing)}")
+    return data
+
+
+def review_passed(lab: Lab, score: dict) -> str | None:
+    """None when the score records a reviewer pass, or why it does not."""
+    review = score.get("review")
+    if not isinstance(review, dict):
+        return "`review` must hold `verdict` and `record`"
+    if review.get("verdict") != "pass":
+        return f"`review.verdict` is `{review.get('verdict') or ''}`, not `pass`"
+    pointer = str(review.get("record") or "").split("#", 1)[0]
+    if not pointer:
+        return "`review.record` points nowhere: it names the file where the reviewer's verdict is recorded"
+    if not (lab.root / pointer).is_file():
+        return f"`review.record` points to {pointer}, which does not exist"
+    return None
+
+
+def _inside_finished_run(lab: Lab, slug: str, evidence: str) -> str | None:
+    """None when the evidence lies in the out/ folder of a finished run of this experiment, or why not."""
+    parts = PurePosixPath(evidence).parts
+    if len(parts) < 6 or parts[:2] != ("experiments", slug) or parts[2] != "runs" or parts[4] != "out":
+        return f"its evidence `{evidence}` is not inside experiments/{slug}/runs/<run>/out/"
+    for run in records.runs(lab, slug):
+        if run.run_id == parts[3]:
+            if run.state != "finished":
+                return f"its evidence is in run {run.run_id}, which is {run.state}, not finished"
+            return None
+    return f"its evidence names run {parts[3]}, which has no {records.RUN}"
+
+
+def result_grounded(lab: Lab, rep: Reporter) -> None:
+    """Every live result names a locked protocol, its evidence sits in a finished run, and a reviewer passed it."""
+    for doc in rederive_mod.live_results(lab):
+        where = _doc_path(lab, doc)
+
+        def one(doc=doc, where=where) -> None:
+            slug = str(doc.meta.get("protocol", ""))
+            proto = protocol_mod.find(lab, slug)
+            if proto is None or proto.status not in ("locked", "abandoned"):
+                rep.add(where, f"{doc.id} names protocol `{slug}`, which is not a locked protocol")
+                return
+            slug = proto.slug
+            if records.read_lock(lab, slug) is None:
+                rep.add(where, f"{doc.id} names protocol `{slug}`, which has no {records.LOCK}")
+            why = _inside_finished_run(lab, slug, PurePosixPath(str(doc.meta.get("evidence", ""))).as_posix())
+            if why:
+                rep.add(where, f"{doc.id}: {why}")
+            score = read_score(lab, slug)
+            if score is None:
+                rep.add(where, f"{doc.id}: experiments/{slug}/{records.SCORE} does not exist, so no reviewer "
+                               "pass is recorded")
+                return
+            why = review_passed(lab, score)
+            if why:
+                rep.add(where, f"{doc.id}: experiments/{slug}/{records.SCORE} records no reviewer pass: {why}")
+        rep.guard(where, one)
+
+
+def score_exact(lab: Lab, rep: Reporter) -> None:
+    """A score names the lock's hash and scores exactly the lock's prediction and rule ids."""
+    for slug in lab.experiment_slugs():
+        path = f"experiments/{slug}/{records.SCORE}"
+
+        def one(slug=slug, path=path) -> None:
+            score = read_score(lab, slug)
+            if score is None:
+                return
+            lock = records.read_lock(lab, slug)
+            if lock is None:
+                rep.add(path, f"scores experiment `{slug}`, which has no {records.LOCK}")
+                return
+            if score.get("protocol") != lock.protocol:
+                rep.add(path, f"names protocol `{score.get('protocol')}`, not `{lock.protocol}`")
+            if score.get("lock") != lock.sha256:
+                rep.add(path, "names a lock hash that is not the one in its lock.json")
+            proto = protocol_mod.find(lab, lock.protocol)
+            if proto is None:
+                return
+            wanted = protocol_mod.scored_ids(proto.text(), proto.path)
+            scores = score.get("scores")
+            if not isinstance(scores, dict):
+                rep.add(path, "`scores` must map each prediction and rule id to its verdict")
+                return
+            for ident in wanted:
+                if ident not in scores:
+                    rep.add(path, f"does not score {ident}, which the lock names")
+            for ident, entry in scores.items():
+                if ident not in wanted:
+                    rep.add(path, f"scores {ident}, which the lock does not name")
+                    continue
+                allowed = records.PREDICTION_VERDICTS if str(ident).startswith("P") else records.RULE_VERDICTS
+                if not isinstance(entry, dict):
+                    rep.add(path, f"{ident} must hold `verdict`, `value` and `evidence`")
+                    continue
+                if entry.get("verdict") not in allowed:
+                    rep.add(path, f"{ident} has verdict `{entry.get('verdict') or ''}`; "
+                                  f"allowed: {', '.join(allowed)}")
+                evidence = str(entry.get("evidence") or "")
+                if not evidence:
+                    rep.add(path, f"{ident} names no evidence")
+                elif not (lab.root / evidence).exists():
+                    rep.add(path, f"{ident} names evidence {evidence}, which does not exist")
+        rep.guard(path, one)
+
+
+def scored_reported(lab: Lab, rep: Reporter) -> None:
+    """Every scored experiment has a report citing its results, or a journal entry about it saying why not."""
+    lib = lab.library()
+    for slug in lab.experiment_slugs():
+        if not records.score_path(lab, slug).is_file():
+            continue
+        proto = protocol_mod.find(lab, slug)
+        name = proto.slug if proto else slug
+        results = [d for d in lib.documents if d.is_a("result")
+                   and str(d.meta.get("protocol", "")).casefold() == name.casefold()]
+        reported = any(
+            any(target in results for link in lib.doc_links(doc) for target in link.docs)
+            for doc in lib.documents if doc.is_a("report"))
+        if reported:
+            continue
+        explained = False
+        for doc in lib.documents:
+            if not doc.is_a("journal") or doc.meta.get("kind") not in EXPLAINING_KINDS:
+                continue
+            about = doc.meta.get("about") or []
+            about = about if isinstance(about, list) else [about]
+            if any(str(a).casefold() == name.casefold() for a in about):
+                explained = True
+                break
+        if not explained:
+            rep.add(f"experiments/{slug}/{records.SCORE}",
+                    f"experiment `{slug}` is scored, but no report cites its results and no journal entry "
+                    "about its protocol says why not")

lab_kit/checks/run.py

@@ -0,0 +1,63 @@
+"""The lab gate: `folio check` on the library, then every lab check, in one report."""
+
+from __future__ import annotations
+
+from folio.checks.problems import Problem
+from folio.checks.run import run as folio_run
+
+from ..errors import LabError
+from ..lab import Lab
+from . import files, locks, results
+from .base import LabCheck, Reporter
+
+FOLIO = "folio"
+
+CHECKS: tuple[LabCheck, ...] = (
+    LabCheck("lab-lock-recorded", "error", locks.lock_recorded),
+    LabCheck("lab-lock-intact", "error", locks.lock_intact),
+    LabCheck("lab-run-after-lock", "error", locks.run_after_lock),
+    LabCheck("lab-roster-frozen", "error", locks.roster_frozen),
+    LabCheck("lab-evidence-sealed", "error", locks.evidence_sealed),
+    LabCheck("lab-rederive", "error", results.rederive),
+    LabCheck("lab-result-grounded", "error", results.result_grounded),
+    LabCheck("lab-score-exact", "error", results.score_exact),
+    LabCheck("lab-ids-resolve", "error", files.ids_resolve),
+    LabCheck("lab-frozen-intact", "error", files.frozen_intact),
+    LabCheck("lab-selftest", "error", files.selftest),
+    LabCheck("lab-mission-approved", "error", files.mission_approved),
+    LabCheck("lab-spend-recorded", "error", files.spend_recorded),
+    LabCheck("lab-append-only", "error", files.append_only),
+    LabCheck("lab-method-current", "error", files.method_current),
+    LabCheck("lab-state-pointer", "warning", files.state_pointer),
+    LabCheck("lab-scored-reported", "warning", results.scored_reported),
+)
+BY_NAME = {c.name: c for c in CHECKS}
+
+
+def names() -> list[str]:
+    return [FOLIO, *BY_NAME]
+
+
+def folio_problems(lab: Lab) -> list[Problem]:
+    """folio's own gate on the library, with paths from the lab root."""
+    lib = lab.library()
+    return [Problem(lab.doc_path(p.path), p.severity, p.check, p.message) for p in folio_run(lib)]
+
+
+def run(lab: Lab, only: list[str] | None = None) -> list[Problem]:
+    """Every problem, folio's first, then the lab checks' in the order of the spec."""
+    wanted = only or names()
+    unknown = [n for n in wanted if n not in names()]
+    if unknown:
+        raise LabError(f"no check named {', '.join(unknown)}; the checks are: {', '.join(names())}")
+    lab.library()  # fail loud, once, when the library does not load
+    problems: list[Problem] = []
+    if FOLIO in wanted:
+        problems.extend(folio_problems(lab))
+    for check in CHECKS:
+        if check.name not in wanted:
+            continue
+        rep = Reporter(check.name, check.severity)
+        check.fn(lab, rep)
+        problems.extend(sorted(set(rep.problems)))
+    return problems

lab_kit/cli.py

@@ -0,0 +1,174 @@
+"""The `lab-kit` command line. Only skills call it, the way an agent calls git."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__, frozen
+from . import lab as lab_mod
+from . import rederive as rederive_mod
+from .checks import run as checks_run
+from .commands import experiments, runs, setup, status
+from .errors import LabError
+
+
+def _lab() -> lab_mod.Lab:
+    return lab_mod.load(Path.cwd())
+
+
+def _print(lines: list[str]) -> None:
+    for line in lines:
+        print(line)
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    _print(setup.init(Path.cwd(), args.library))
+    return 0
+
+
+def cmd_check(args: argparse.Namespace) -> int:
+    lab = _lab()
+    problems = checks_run.run(lab, args.only)
+    errors = sum(1 for p in problems if p.severity == "error")
+    warnings = sum(1 for p in problems if p.severity == "warning")
+    if args.json:
+        print(json.dumps({"problems": [p.as_dict() for p in problems], "errors": errors, "warnings": warnings},
+                         indent=2, ensure_ascii=False))
+    else:
+        _print([p.line() for p in problems])
+        print(f"lab-kit check: {errors} errors, {warnings} warnings")
+    return 1 if errors else 0
+
+
+def cmd_experiment(args: argparse.Namespace) -> int:
+    _print(experiments.experiment(_lab(), args.slug))
+    return 0
+
+
+def cmd_lock(args: argparse.Namespace) -> int:
+    _print(experiments.lock(_lab(), args.slug))
+    return 0
+
+
+def cmd_run(args: argparse.Namespace) -> int:
+    command = list(args.command or [])
+    changed, code = runs.start(_lab(), args.slug, command, mission=args.mission, spend=args.spend, wait=args.wait)
+    _print(changed)
+    return 0 if code == 0 else 1
+
+
+def cmd_runs(args: argparse.Namespace) -> int:
+    _print(runs.listing(_lab(), live=args.live))
+    return 0
+
+
+def cmd_score(args: argparse.Namespace) -> int:
+    _print(experiments.score(_lab(), args.slug))
+    return 0
+
+
+def cmd_rederive(args: argparse.Namespace) -> int:
+    lab = _lab()
+    doc = rederive_mod.result_doc(lab, args.id)
+    outcome = rederive_mod.run(lab, doc)
+    if outcome.ok:
+        print(f"{doc.id}: re-derived `{outcome.printed}`, its number")
+        return 0
+    print(f"{doc.id}: does not re-derive: {outcome.detail}")
+    return 1
+
+
+def cmd_freeze(args: argparse.Namespace) -> int:
+    _print(frozen.freeze(_lab(), args.path))
+    return 0
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    _print(status.status(_lab()))
+    return 0
+
+
+def cmd_version(args: argparse.Namespace) -> int:
+    print(f"lab-kit {__version__}")
+    return 0
+
+
+def parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="lab-kit", description="A research lab's method and machinery on folio.")
+    sub = p.add_subparsers(dest="command_name")
+
+    s = sub.add_parser("init", help="Write lab.yaml, ops/, experiments/, .lab/, the skills and the roles. "
+                       "Before a library exists, only the method, the skills and the roles.")
+    s.add_argument("--library", help="the folder holding folio.yaml, from the lab root (default: the lab root)")
+    s.set_defaults(func=cmd_init)
+
+    s = sub.add_parser("check", help="The lab gate: folio check, then the lab checks. Changes nothing.")
+    s.add_argument("--only", action="append", metavar="ID", help="run only this check (repeatable); "
+                   "`folio` names folio's gate")
+    s.add_argument("--json", action="store_true")
+    s.set_defaults(func=cmd_check)
+
+    s = sub.add_parser("experiment", help="Create experiments/<slug>/ with bin/, runs/ and a gitignore.")
+    s.add_argument("slug")
+    s.set_defaults(func=cmd_experiment)
+
+    s = sub.add_parser("lock", help="Write lock.json for a locked protocol whose gate is green.")
+    s.add_argument("slug")
+    s.set_defaults(func=cmd_lock)
+
+    s = sub.add_parser("run", usage="lab-kit run <slug> [--mission <file>] [--spend] [--wait] -- <command>",
+                       help="Check the lock, write run.json, and run the command in the background.")
+    s.add_argument("slug")
+    s.add_argument("--mission", help="the mission file this run belongs to")
+    s.add_argument("--spend", action="store_true", help="the run spends tokens or money")
+    s.add_argument("--wait", action="store_true", help="wait for the command to end")
+    s.set_defaults(func=cmd_run)
+
+    s = sub.add_parser("runs", help="List runs and their state: running, finished, failed, orphaned.")
+    s.add_argument("--live", action="store_true", help="only running and orphaned runs")
+    s.set_defaults(func=cmd_runs)
+
+    s = sub.add_parser("score", help="Create score.yaml from the lock's prediction and rule ids.")
+    s.add_argument("slug")
+    s.set_defaults(func=cmd_score)
+
+    s = sub.add_parser("rederive", help="Run one result's re-derive command against its number.")
+    s.add_argument("id")
+    s.set_defaults(func=cmd_rederive)
+
+    s = sub.add_parser("freeze", help="Record a frozen surface's hashes. Only the operator asks for this.")
+    s.add_argument("path")
+    s.set_defaults(func=cmd_freeze)
+
+    s = sub.add_parser("status", help="The state, the active mission, live runs, and protocols by status.")
+    s.set_defaults(func=cmd_status)
+
+    s = sub.add_parser("version", help="The lab-kit version.")
+    s.set_defaults(func=cmd_version)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = parser()
+    argv = list(sys.argv[1:] if argv is None else argv)
+    command: list[str] | None = None
+    if "--" in argv:  # what follows `--` is the lab's own command, passed on untouched
+        cut = argv.index("--")
+        argv, command = argv[:cut], argv[cut + 1:]
+    args = p.parse_args(argv)
+    args.command = command
+    if args.command_name is None:
+        p.print_help()
+        return 2
+    try:
+        return args.func(args)
+    except LabError as exc:
+        print(f"lab-kit: error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

lab_kit/commands/__init__.py

@@ -0,0 +1 @@
+"""The `lab-kit` commands that change files, and the ones that report."""

lab_kit/commands/experiments.py

@@ -0,0 +1,89 @@
+"""`lab-kit experiment`, `lab-kit lock` and `lab-kit score`: an experiment's folder, its lock and its scorecard."""
+
+from __future__ import annotations
+
+from folio.checks.run import run as folio_run
+from folio.util import is_slug
+
+from .. import protocol as protocol_mod
+from .. import records
+from ..errors import LabError
+from ..lab import Lab
+
+GITIGNORE = "# A run's scratch and log stay out of git; out/ is committed once, at the end.\nruns/*/work/\nruns/*/run.log\n"
+
+
+def experiment(lab: Lab, slug: str) -> list[str]:
+    if not is_slug(slug):
+        raise LabError(f"`{slug}` is not a slug: lowercase letters, digits and single hyphens")
+    proto = protocol_mod.require(lab, slug)
+    folder = lab.experiments / proto.slug
+    if folder.exists():
+        raise LabError(f"experiments/{proto.slug}/ exists already")
+    (folder / "bin").mkdir(parents=True)
+    (folder / "runs").mkdir()
+    (folder / "bin" / ".gitkeep").touch()
+    (folder / "runs" / ".gitkeep").touch()
+    (folder / ".gitignore").write_text(GITIGNORE, encoding="utf-8")
+    base = f"experiments/{proto.slug}"
+    return [f"created {base}/bin/", f"created {base}/runs/", f"created {base}/.gitignore"]
+
+
+def lock(lab: Lab, slug: str) -> list[str]:
+    proto = protocol_mod.require(lab, slug)
+    if proto.status != "locked":
+        raise LabError(f"{proto.path} has status `{proto.status}`; set it to `locked` through folio's write "
+                       "skill first")
+    folder = lab.experiments / proto.slug
+    if not folder.is_dir():
+        raise LabError(f"experiments/{proto.slug}/ does not exist; run `lab-kit experiment {proto.slug}` first")
+    path = records.lock_path(lab, proto.slug)
+    if path.exists():
+        raise LabError(f"experiments/{proto.slug}/{records.LOCK} exists already: a protocol is locked once")
+    main = proto.doc.main
+    errors = [p for p in folio_run(lab.library()) if p.severity == "error" and main is not None
+              and p.path == main.path]
+    if errors:
+        raise LabError(f"{proto.path} does not pass the gate:\n" + "\n".join(f"  {p.line()}" for p in errors))
+    protocol_mod.pinned_config(proto.text(), proto.path)
+    protocol_mod.scored_ids(proto.text(), proto.path)
+    records.write_json(path, {
+        "protocol": proto.slug,
+        "path": proto.path,
+        "sha256": protocol_mod.hash_text(proto.text()),
+        "locked": records.now(),
+    })
+    return [f"created experiments/{proto.slug}/{records.LOCK}"]
+
+
+
+def score(lab: Lab, slug: str) -> list[str]:
+    lock_record = records.read_lock(lab, slug)
+    if lock_record is None:
+        raise LabError(f"experiments/{slug}/{records.LOCK} does not exist: only a locked experiment is scored")
+    proto = protocol_mod.require(lab, lock_record.protocol)
+    path = records.score_path(lab, slug)
+    if path.exists():
+        raise LabError(f"experiments/{slug}/{records.SCORE} exists already")
+    ids = protocol_mod.scored_ids(proto.text(), proto.path)
+    lines = [
+        f"# The scorecard of experiment {slug}, against its lock.",
+        f"# A prediction's verdict: {', '.join(records.PREDICTION_VERDICTS)}.",
+        f"# A decision rule's verdict: {', '.join(records.RULE_VERDICTS)}.",
+        "# `evidence` is a path from the lab root, inside a finished run.",
+        f"protocol: {proto.slug}",
+        f"lock: {lock_record.sha256}",
+        "review:            # the independent reviewer's pass: `pass` or `fail`, and where its verdict is recorded",
+        '  verdict: ""',
+        '  record: ""',
+        "scores:",
+    ]
+    for ident in ids:
+        lines += [f"  {ident}:", '    verdict: ""', '    value: ""', '    evidence: ""']
+    lines += [
+        "# The numbers to record as results, each keyed by a short name, with the result's fields:",
+        "# title, protocol, number, baseline, bound, evidence, rederive.",
+        "record: {}",
+    ]
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    return [f"created experiments/{slug}/{records.SCORE} with {len(ids)} ids to score: {', '.join(ids)}"]

lab_kit/commands/runs.py

@@ -0,0 +1,105 @@
+"""`lab-kit run` and `lab-kit runs`: start a run against the lock, and list the runs."""
+
+from __future__ import annotations
+
+import datetime as _dt
+import os
+import subprocess
+import sys
+
+from .. import ops
+from .. import protocol as protocol_mod
+from .. import records
+from ..errors import LabError
+from ..lab import Lab
+
+
+def _run_id(lab: Lab, slug: str) -> str:
+    stamp = _dt.datetime.now(_dt.timezone.utc).strftime("%Y%m%d-%H%M%S")
+    run_id, n = stamp, 1
+    while (lab.experiments / slug / "runs" / run_id).exists():
+        n += 1
+        run_id = f"{stamp}-{n}"
+    return run_id
+
+
+def _check_mission(lab: Lab, mission: str | None, spend: bool) -> str | None:
+    if mission is None:
+        if spend:
+            raise LabError("a run that spends names its mission: --mission ops/missions/<file>.md")
+        return None
+    target = (lab.root / mission).resolve()
+    if not target.is_file():
+        raise LabError(f"mission {mission} does not exist")
+    rel = lab.rel(target)
+    record = ops.read_mission(lab, target)
+    problem = record.approval_problem()
+    if problem is not None:
+        raise LabError(problem)
+    if spend and record.cap is None:
+        raise LabError(f"{rel} records no numeric `cap:`; no run spends without the operator's approval and a cap")
+    return rel
+
+
+def start(lab: Lab, slug: str, command: list[str], mission: str | None = None, spend: bool = False,
+          wait: bool = False) -> tuple[list[str], int]:
+    """Start a run; with `wait`, block until it ends. Returns what changed and the command's exit code."""
+    if not command:
+        raise LabError("name the command after `--`: lab-kit run <slug> -- <command>")
+    lock = records.read_lock(lab, slug)
+    if lock is None:
+        raise LabError(f"experiments/{slug}/{records.LOCK} does not exist: no run starts before the lock")
+    proto = protocol_mod.require(lab, lock.protocol)
+    if proto.status != "locked":
+        raise LabError(f"{proto.path} has status `{proto.status}`, not `locked`")
+    if protocol_mod.hash_text(proto.text()) != lock.sha256:
+        raise LabError(f"{proto.path} changed since its lock; no run starts against a broken lock")
+    config = protocol_mod.pinned_config(proto.text(), proto.path)
+    mission_rel = _check_mission(lab, mission, spend)
+    run_id = _run_id(lab, slug)
+    run_dir = lab.experiments / slug / "runs" / run_id
+    (run_dir / "out").mkdir(parents=True)
+    (run_dir / "work").mkdir()
+    records.write_json(run_dir / records.RUN, {
+        "protocol": lock.protocol, "lock": lock.sha256, "config": config, "mission": mission_rel,
+        "spend": spend, "command": command, "started": records.now(), "ended": None, "exit": None,
+        "pid": None, "spent": None,
+    })
+    base = f"experiments/{slug}/runs/{run_id}"
+    changed = [f"created {base}/{records.RUN}", f"created {base}/out/", f"started {' '.join(command)}",
+               f"log: {base}/run.log"]
+    child = subprocess.Popen([sys.executable, "-m", "lab_kit.supervise", str(run_dir), str(lab.root)],
+                             cwd=lab.root, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
+                             stderr=subprocess.DEVNULL, start_new_session=True, env=_child_env())
+    data = records.read_json(run_dir / records.RUN, f"{base}/{records.RUN}")
+    data["pid"] = child.pid
+    records.write_json(run_dir / records.RUN, data)
+    if not wait:
+        return changed + [f"running in the background; `lab-kit runs --live` shows it"], 0
+    code = child.wait()
+    data = records.read_json(run_dir / records.RUN, f"{base}/{records.RUN}")
+    changed.append(f"wrote {base}/{records.MANIFEST}")
+    changed.append(f"ended with exit code {data.get('exit')}")
+    return changed, code
+
+
+def _child_env() -> dict[str, str]:
+    """The environment for the supervisor, with this package importable the way it is here."""
+    env = dict(os.environ)
+    here = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    env["PYTHONPATH"] = here + (os.pathsep + env["PYTHONPATH"] if env.get("PYTHONPATH") else "")
+    return env
+
+
+def listing(lab: Lab, live: bool = False) -> list[str]:
+    rows = []
+    for run in records.runs(lab):
+        state = run.state
+        if live and state not in ("running", "orphaned"):
+            continue
+        exit_code = run.data.get("exit")
+        rows.append(f"{run.slug}/{run.run_id}  {state:<9} started {run.data.get('started')}"
+                    + (f"  exit {exit_code}" if exit_code is not None else ""))
+    if not rows:
+        return ["No live runs." if live else "No runs."]
+    return rows