@giamme/forge 0.0.0-stage → 0.8.0

package/scripts/forge_jev/verify.py

@@ -0,0 +1,453 @@
+"""Verify-command discovery and failure triage: select, never generate, and judge flakes."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import re
+
+from . import enabled, load_config, threshold
+from .client import ask, choice, noul, probabilities, score
+from .questions import failure_triage, runs_tests, verify_runtime, verify_selection
+
+CANDIDATE_CAP = 25  # keeps one discover() request small; deterministic order means the
+                    # cap always drops the same (least-likely) tail, never a random one.
+LOG_TAIL_CHARS = 4000  # the failure signature (assertion, traceback) is at the end of a
+                       # log; the setup/build noise at the start is not needed to triage it.
+
+_PKG_SCRIPT_RE = re.compile(r'^(test|check|ci|verify)(?:[:\-]|$)', re.I)
+_MAKE_TARGETS = ('test', 'tests', 'check', 'verify', 'ci')
+_RUNNER_DIR_RE = re.compile(r'(test|check|ci|verify)', re.I)
+_WORKFLOW_RUN_RE = re.compile(r'^\s*(?:-\s*)?run:\s*(.+?)\s*$')
+_WORKFLOW_TEST_HINT_RE = re.compile(
+    r'\b(pytest|npm (?:test|run\s+test\S*)|yarn (?:test|run\s+test\S*)|go test|cargo test|'
+    r'make test|tox\b|jest|vitest|mvn test|gradle test|rspec|phpunit|ctest|go\s+vet\s+&&\s+go\s+test)\b',
+    re.I)
+_MEMORY_CMD_RES = (
+    re.compile(r'\bpytest(?:\s+-{1,2}\S+)*'),
+    re.compile(r'\bmake\s+\w[\w-]*'),
+    re.compile(r'\bnpm run\s+[\w:_-]+'),
+    re.compile(r'\bnpm test\b'),
+    re.compile(r'\byarn(?:\s+run)?\s+[\w:_-]+'),
+    re.compile(r'\bgo test(?:\s+\S+)*'),
+    re.compile(r'\bcargo test(?:\s+\S+)*'),
+    re.compile(r'\btox\b'),
+    re.compile(r'\bnox\b'),
+)
+
+
+def _add(found: list[dict], seen: set[str], command: str, source: str, evidence: str) -> None:
+    command = command.strip()
+    if not command or command in seen or len(found) >= CANDIDATE_CAP:
+        return
+    seen.add(command)
+    found.append(dict(command=command, source=source, evidence=evidence))
+
+
+def _forge_verify(repo: Path, found, seen) -> None:
+    path = repo / '.forge' / 'verify'
+    if not path.is_file():
+        return
+    text = path.read_text(errors='replace').strip()
+    if text:
+        _add(found, seen, text, 'forge/verify', str(path))
+
+
+def _package_json(repo: Path, found, seen) -> None:
+    path = repo / 'package.json'
+    if not path.is_file():
+        return
+    try:
+        data = json.loads(path.read_text())
+    except (OSError, ValueError):
+        return
+    scripts = data.get('scripts') if isinstance(data, dict) else None
+    if not isinstance(scripts, dict):
+        return
+    names = [n for n in scripts if isinstance(n, str) and _PKG_SCRIPT_RE.match(n)]
+    order = {name: i for i, name in enumerate(names)}
+    # A bare 'test' is the most likely full-suite entry point; put it and its siblings
+    # ('check', 'ci', 'verify') first, then the rest in file order for determinism.
+    names = sorted(names, key=lambda n: (n not in ('test', 'check', 'ci', 'verify'), order[n]))
+    for name in names:
+        _add(found, seen, f'npm run {name}', 'package.json', str(path))
+
+
+def _makefile(repo: Path, found, seen) -> None:
+    path = repo / 'Makefile'
+    if not path.is_file():
+        return
+    for line in path.read_text(errors='replace').splitlines():
+        m = re.match(r'^([A-Za-z0-9_-]+)\s*:(?!=)', line)
+        if m and m.group(1).lower() in _MAKE_TARGETS:
+            _add(found, seen, f'make {m.group(1)}', 'Makefile', str(path))
+
+
+def _tox_and_nox(repo: Path, found, seen) -> None:
+    tox = repo / 'tox.ini'
+    if tox.is_file():
+        _add(found, seen, 'tox', 'tox.ini', str(tox))
+    nox = repo / 'noxfile.py'
+    if nox.is_file():
+        _add(found, seen, 'nox', 'noxfile.py', str(nox))
+
+
+# test_foo.py / foo_test.py are individual test modules, not suite runners. Offering
+# each one would bury the single real runner under a dozen near-duplicates and eat the
+# candidate cap on a repo with many test files.
+_MODULE_RE = re.compile(r'^test_.*\.py$|^.*_test\.py$')
+
+
+def _runner_scripts(repo: Path, found, seen) -> None:
+    for sub in ('tests', 'scripts', 'bin'):
+        directory = repo / sub
+        if not directory.is_dir():
+            continue
+        for entry in sorted(directory.iterdir()):
+            if not entry.is_file() or not _RUNNER_DIR_RE.search(entry.name):
+                continue
+            try:
+                executable = entry.stat().st_mode & 0o111 != 0
+            except OSError:
+                continue
+            rel = entry.relative_to(repo).as_posix()
+            if executable and entry.suffix in ('', '.sh', '.py'):
+                _add(found, seen, rel, sub + '/', str(entry))
+            # A runner script that was never chmod +x is still the project's real
+            # verify command -- forge's own tests/check.sh is mode 644 and its README
+            # says to run `bash tests/check.sh`. Naming the interpreter for a file that
+            # exists is still selection, not invention, so the candidate is offered and
+            # Jev decides. Skipping it left repos like that permanently UNVERIFIED.
+            elif not executable and entry.suffix in ('.sh', '.py') and not _MODULE_RE.match(entry.name):
+                interpreter = 'bash' if entry.suffix == '.sh' else 'python3'
+                _add(found, seen, interpreter + ' ' + rel, sub + '/', str(entry))
+
+
+def _pytest_configured(repo: Path, found, seen) -> None:
+    candidates = (
+        (repo / 'pytest.ini', True),
+        (repo / 'tox.ini', '[pytest]'),
+        (repo / 'setup.cfg', '[tool:pytest]'),
+        (repo / 'pyproject.toml', '[tool.pytest.ini_options]'),
+    )
+    for path, marker in candidates:
+        if not path.is_file():
+            continue
+        if marker is True:
+            _add(found, seen, 'pytest -q', path.name, str(path))
+            return
+        try:
+            if marker in path.read_text(errors='replace'):
+                _add(found, seen, 'pytest -q', path.name, str(path))
+                return
+        except OSError:
+            continue
+
+
+def _go_and_cargo(repo: Path, found, seen) -> None:
+    go = repo / 'go.mod'
+    if go.is_file():
+        _add(found, seen, 'go test ./...', 'go.mod', str(go))
+    cargo = repo / 'Cargo.toml'
+    if cargo.is_file():
+        _add(found, seen, 'cargo test', 'Cargo.toml', str(cargo))
+
+
+def _workflows(repo: Path, found, seen) -> None:
+    directory = repo / '.github' / 'workflows'
+    if not directory.is_dir():
+        return
+    for path in sorted(directory.glob('*.yml')) + sorted(directory.glob('*.yaml')):
+        try:
+            lines = path.read_text(errors='replace').splitlines()
+        except OSError:
+            continue
+        # Plain-text scan on purpose (no YAML dependency): only single-line `run: <cmd>`
+        # steps are recognised, which is the common case for a test invocation step. A
+        # malformed file just yields no matches rather than raising.
+        for line in lines:
+            m = _WORKFLOW_RUN_RE.match(line)
+            if not m:
+                continue
+            command = m.group(1).strip().strip('"\'')
+            if command and command != '|' and _WORKFLOW_TEST_HINT_RE.search(command):
+                _add(found, seen, command, 'workflow', str(path))
+
+
+def _memory_verify(repo: Path, found, seen) -> None:
+    path = repo / '.forge' / 'memory.md'
+    if not path.is_file():
+        return
+    for line in path.read_text(errors='replace').splitlines():
+        if 'verify |' not in line:
+            continue
+        text = line.split('verify |', 1)[1]
+        # A memory entry is prose ("pytest -q runs the suite; make test also lints and
+        # is 4x slower"), not a bare command -- pull out anything that looks like a
+        # known runner invocation rather than treating the whole sentence as a command.
+        for pattern in _MEMORY_CMD_RES:
+            for match in pattern.finditer(text):
+                _add(found, seen, match.group(0), 'memory:verify', str(path))
+
+
+def candidates(repo) -> list[dict]:
+    """Real, existing verify commands. Each: {'command': str, 'source': str, 'evidence': str}.
+
+    Deterministic order, deduplicated, capped at CANDIDATE_CAP. Never executes anything --
+    this only enumerates what plausibly exists so Jev can select among real options.
+    """
+    repo = Path(repo)
+    found: list[dict] = []
+    seen: set[str] = set()
+    for step in (_forge_verify, _package_json, _makefile, _tox_and_nox, _runner_scripts,
+                _pytest_configured, _go_and_cargo, _workflows, _memory_verify):
+        if len(found) >= CANDIDATE_CAP:
+            break
+        step(repo, found, seen)
+    return found[:CANDIDATE_CAP]
+
+
+def _repo_files(repo: Path, limit: int = 200) -> list[str]:
+    try:
+        entries = sorted(e.name for e in repo.iterdir())
+    except OSError:
+        return []
+    return entries[:limit]
+
+
+# The headings forge-memory.sh:93 renders. Both readers below looked for the LEDGER row
+# format instead -- `verify |` and `trap |` -- which is what ledger.tsv holds, not what
+# `rebuild` writes into memory.md. No line in a rendered memory.md has ever contained
+# either, so both lists were empty for every repo, always, while jev.md documented them
+# as working. Verification discovery never saw a recorded verify command, and
+# known_traps never corroborated anything -- which made the flake re-run unreachable,
+# since its third condition is a trap sharing a distinctive token with the failure.
+_MEMORY_SECTIONS = {'verify': '## Verify', 'trap': '## Known traps',
+                    'finding': '## Recurring QA findings'}
+
+
+def _memory_facts(repo: Path, category: str) -> list[str]:
+    """The `- ` bullets under one heading of a rendered .forge/memory.md."""
+    heading = _MEMORY_SECTIONS.get(category)
+    path = Path(repo) / '.forge' / 'memory.md'
+    if not heading or not path.is_file():
+        return []
+    try:
+        lines = path.read_text(errors='replace').splitlines()
+    except OSError:
+        return []
+    facts, inside = [], False
+    for line in lines:
+        stripped = line.strip()
+        if stripped.startswith('## '):
+            inside = stripped == heading
+            continue
+        if inside and stripped.startswith('- '):
+            fact = stripped[2:].strip()
+            # `rebuild` prefixes a recurring finding with its count ("3x: ..."), which is
+            # bookkeeping about the fact rather than part of it.
+            if fact[:1].isdigit() and 'x: ' in fact[:6]:
+                fact = fact.split('x: ', 1)[1].strip()
+            if fact:
+                facts.append(fact)
+    return facts
+
+
+def _memory_verify_lines(repo: Path) -> list[str]:
+    return _memory_facts(repo, 'verify')
+
+
+def known_traps(repo) -> list[str]:
+    """Recorded 'trap' facts from .forge/memory.md (flaky tests, generated files, sharp
+    edges), for the CLI to hand to triage() -- see references/memory.md."""
+    path = Path(repo) / '.forge' / 'memory.md'
+    if not path.is_file():
+        return []
+    try:
+        lines = path.read_text(errors='replace').splitlines()
+    except OSError:
+        return []
+    return _memory_facts(path.parent.parent, 'trap')
+
+
+# Enough of an evidence file to tell a test command from a build one, and no more: the
+# request already carries one Choice and two Nouls per candidate.
+EVIDENCE_CHARS = 400
+
+
+def _evidence_excerpt(candidate: dict) -> str:
+    """What the command actually runs, read off the file that produced the candidate.
+
+    Without this the model is handed the string 'make test' plus the repo's top-level
+    file list and asked whether it runs the suite. It cannot know: the answer is inside
+    the Makefile. Measured on a repo with a textbook `test:` target, discovery picked
+    `make test` at 0.58 while leaving 0.40 on `none`, for a Choice confidence of 0.37
+    against a 0.70 gate -- so it declined, and a verifiable repo reported UNVERIFIED.
+    """
+    path = candidate.get('evidence') or ''
+    try:
+        text = Path(path).read_text(errors='replace')
+    except OSError:
+        return ''
+    command = candidate.get('command') or ''
+    # A make target's recipe is the only part of a Makefile that answers the question,
+    # and it is rarely near the top of the file.
+    if command.startswith('make ') and Path(path).name.lower().startswith('makefile'):
+        target = command.split(None, 1)[1].strip()
+        recipe, collecting = [], False
+        for line in text.splitlines():
+            if collecting:
+                if line.startswith(('\t', ' ')) or not line.strip():
+                    recipe.append(line.strip())
+                    continue
+                break
+            if ':' in line and line.split(':')[0].strip() == target:
+                collecting = True
+        joined = '\n'.join(x for x in recipe if x)
+        if joined:
+            return joined[:EVIDENCE_CHARS]
+    return text[:EVIDENCE_CHARS]
+
+
+def discover(repo, *, config=None, run_dir=None) -> dict | None:
+    """Ask Jev which candidate actually verifies this repo. None when Jev is
+    unavailable, no candidates exist, or it picks `none`.
+    -> {'command', 'confidence', 'verifiable', 'runs_tests', 'runtime_level', 'source',
+        'evidence'}
+    """
+    config = config or load_config()
+    if not enabled('tests', config=config):
+        return None
+    repo_path = Path(repo)
+    cand = candidates(repo_path)
+    if not cand:
+        return None
+    commands = [c['command'] for c in cand]
+
+    # One request covers the Choice and a runs_tests/verify_runtime pair per candidate --
+    # they all evaluate in parallel server-side, so asking about every candidate here
+    # costs exactly one call, not one per candidate.
+    questions = {'choice': verify_selection(commands)}
+    for i in range(len(cand)):
+        questions[f'runs_{i}'] = runs_tests(commands[i])
+        questions[f'runtime_{i}'] = verify_runtime(commands[i])
+
+    # The candidates carry where they came from and what they run. Sending only the
+    # command strings threw away the single thing that answers the question being asked.
+    described = [dict(command=c['command'], source=c.get('source', ''),
+                      runs=_evidence_excerpt(c)) for c in cand]
+    state = dict(repo_files=_repo_files(repo_path), candidates=described,
+                memory_verify=_memory_verify_lines(repo_path))
+    result = ask(state, questions, site='jev-verify-discover', run_dir=run_dir, config=config)
+    if result is None:
+        return None
+
+    picked, confidence = choice(result, 'choice')
+    if picked is None or picked == 'none':
+        return None
+
+    # Gate on "is this repo verifiable at all", not on "which command wins".
+    #
+    # Choice confidence answers the second question, and for a selection among several
+    # ACCEPTABLE options it is the wrong quantity: a repo offering both `bash
+    # tests/check.sh` and `python3 -m unittest discover -s tests` splits the mass
+    # 0.62/0.31 with only 0.07 on `none`, for a confidence of 0.49 against a 0.70 gate.
+    # The model is 93% sure the repo is verifiable and forge reported UNVERIFIED --
+    # because two right answers look exactly like doubt to a rubric that measures
+    # agreement on one.
+    #
+    # 1 - P(none) is the quantity `tests_act` was always meant to gate. A split between
+    # correct commands leaves it high; genuine doubt piles onto `none` and drops it.
+    # Ties are then broken by the winner, which is what Choice is for.
+    distribution = probabilities(result, 'choice')
+    act_at = threshold('tests_act', config=config)
+    if distribution:
+        if (1.0 - distribution.get('none', 0.0)) < act_at:
+            return None
+    elif confidence < act_at:
+        # No distribution in the response: fall back to the old gate rather than treat a
+        # missing field as certainty.
+        return None
+    try:
+        idx = commands.index(picked)
+    except ValueError:
+        # Choice is constrained to the options we sent, so this should not happen -- but
+        # a command we never enumerated must never be reported as "selected", so bail.
+        return None
+
+    runs_probability = noul(result, f'runs_{idx}')
+    if runs_probability is None or runs_probability < 0.5:
+        # A command that only builds or lints must not be presented as verification,
+        # even if the Choice rubric itself scored it confidently.
+        return None
+
+    runtime_score, _runtime_conf = score(result, f'runtime_{idx}')
+    runtime_levels = questions[f'runtime_{idx}']['criteria']
+    runtime_level = None
+    if runtime_score is not None and 0 <= int(runtime_score) < len(runtime_levels):
+        runtime_level = runtime_levels[int(runtime_score)]
+
+    picked_candidate = cand[idx]
+    # `verifiable` is the quantity the gate actually used; `confidence` is kept beside it
+    # because they answer different questions and a future re-measurement needs both.
+    verifiable = (1.0 - distribution.get('none', 0.0)) if distribution else None
+    return dict(command=picked, confidence=confidence, verifiable=verifiable,
+               runs_tests=runs_probability,
+               runtime_level=runtime_level, source=picked_candidate['source'],
+               evidence=picked_candidate['evidence'])
+
+
+# A token is distinctive enough to corroborate only if it looks like an identifier or a
+# path -- `test_timeout`, `tests/test_api.py`, `CamelCase` -- rather than an English word
+# that any failure log would contain.
+_TOKEN_RE = re.compile(r'[A-Za-z_][A-Za-z0-9_./:-]{3,}')
+
+
+def _distinctive(text: str) -> set[str]:
+    tokens = set()
+    for match in _TOKEN_RE.findall(text or ''):
+        # Split on path and node-id separators: a trap says `test_api.py::test_timeout`
+        # while the log says `tests/test_api.py::test_timeout`, which never compare equal
+        # as whole tokens. Atoms do.
+        for token in re.split(r'[/:]+', match):
+            token = token.strip('.-_')
+            if len(token) < 4:
+                continue
+            # A bare short word like `tests` matches every repo; require either an
+            # identifier/path shape or enough length to be specific.
+            if '_' in token or '.' in token or len(token) >= 8:
+                tokens.add(token)
+    return tokens
+
+
+def corroborating_traps(log_tail: str, traps) -> list[str]:
+    """Traps that share a distinctive token with the failure output.
+
+    The re-run gate needs evidence that THIS failure matches a recorded trap, not merely
+    that the repo has recorded some trap at some point. Without that, one flaky test
+    noted months ago would excuse every future failure in the repo -- which is precisely
+    how a real regression gets waved through.
+    """
+    haystack = _distinctive(log_tail)
+    return [trap for trap in (traps or []) if _distinctive(trap) & haystack]
+
+
+def triage(repo, *, command, log_tail, traps, config=None, run_dir=None) -> dict | None:
+    """Classify a verification failure. -> {'verdict', 'confidence'} or None."""
+    config = config or load_config()
+    if not enabled('tests', config=config):
+        return None
+    tail = (log_tail or '')[-LOG_TAIL_CHARS:]
+    # The diff is never sent: recognising a flake needs the failure signature (timeout,
+    # ordering, port-in-use, a named trap), not the change itself, and the diff is a
+    # larger payload for no benefit here.
+    state = dict(command=command, log_tail=tail, known_traps=list(traps or []))
+    result = ask(state, {'triage': failure_triage(list(traps or []))}, site='jev-verify-triage',
+                run_dir=run_dir, config=config)
+    if result is None:
+        return None
+    verdict, confidence = choice(result, 'triage')
+    if verdict is None:
+        return None
+    matched = corroborating_traps(tail, traps)
+    return dict(verdict=verdict, confidence=confidence,
+                corroborated=bool(matched), corroborating_traps=matched)

package/scripts/forge_registry.py

@@ -0,0 +1,140 @@
+"""Where a repo's run directories live, outside the repo.
+
+``$XDG_CONFIG_HOME/forge/runs/<sha256(realpath(repo))[:16]>.txt`` holds one absolute
+run-dir path per line, with a ``#`` header on a new file. ``forge jev``, ``forge
+dataset import --registry`` and the forge-ui launcher all use it, so it does not
+live inside the Jev package.
+
+Run as a script, ``forge_registry.py register <run-dir>`` records a run dir from the
+shell runners (forge-ui-options.sh ``forge_ui_register``): every plan, run and solo run
+is registered, not only the ones opened with ``--ui``, because forge-ui's map of a
+repo's runs reads this registry. ``FORGE_RUN_REGISTRY=off`` turns that off.
+"""
+from __future__ import annotations
+
+import hashlib
+import os
+import stat
+import sys
+from pathlib import Path
+
+
+def registry_dir() -> Path:
+    """The ``runs`` directory under forge's config home.
+
+    Resolved the same way ``forge_jev.config_path()`` resolves ``jev.json``:
+    ``XDG_CONFIG_HOME`` when set and not empty, otherwise ``~/.config``, then
+    ``expanduser()``. An empty value counts as unset, as the XDG spec says and as
+    forge-ui's run list reads it; taken literally it named a directory below the
+    current one, usually the user's repo. ``config_path()`` is
+    ``<that>/forge/jev.json``; the registry is the sibling ``runs`` directory.
+    """
+    config = (Path(os.environ.get('XDG_CONFIG_HOME') or str(Path.home() / '.config')).expanduser()
+              / 'forge/jev.json')
+    return config.parent / 'runs'
+
+
+def repo_key(repo) -> str:
+    """16 hex chars of ``sha256(realpath(repo))``. The registry file name and the dataset key."""
+    return hashlib.sha256(str(Path(repo).resolve()).encode()).hexdigest()[:16]
+
+
+def runs_registry(repo) -> Path:
+    """Where this repo's run-dir list lives -- beside the forge config, never in the repo.
+
+    The first version of this wrote <repo>/.forge/jev-runs.txt, which left the user's
+    working tree dirty and made `integrate` refuse to run: "working tree is dirty --
+    commit or stash before integrating". Forge's contract is that it does not touch the
+    user's tree, and a file recording where forge keeps its own data is forge's
+    bookkeeping, not the project's.
+    """
+    return registry_dir() / (repo_key(repo) + '.txt')
+
+
+def register_run_dir(repo: Path, run_dir: Path) -> None:
+    """Record an absolute run-dir path for this repo, deduplicated.
+
+    Never raises and never blocks: failing to note where a run lives must not fail the run,
+    and ``forge ui open`` calls this before any of its own timeouts.
+    """
+    try:
+        # A relative XDG_CONFIG_HOME resolves below the current directory -- for a runner or
+        # `forge ui open`, usually the user's repo. Forge does not write into the user's tree.
+        if not registry_dir().is_absolute():
+            return
+        registry = runs_registry(repo)
+        registry.parent.mkdir(parents=True, exist_ok=True)
+        line = str(Path(run_dir).resolve())
+        existing = []
+        if registry.is_file():
+            existing = [x.strip() for x in registry.read_text(errors='replace').splitlines()]
+        if line in existing:
+            return
+        header = [] if existing else ['# forge run dirs for ' + str(Path(repo).resolve())]
+        # O_NONBLOCK: a FIFO with no reader fails at once (ENXIO) instead of blocking the
+        # open, and anything that is not a regular file is left alone.
+        fd = os.open(registry, os.O_WRONLY | os.O_APPEND | os.O_CREAT | os.O_NONBLOCK, 0o644)
+        with os.fdopen(fd, 'a') as handle:
+            if not stat.S_ISREG(os.fstat(fd).st_mode):
+                return
+            for entry in header:
+                handle.write(entry + '\n')
+            handle.write(line + '\n')
+    except (OSError, ValueError, RuntimeError):
+        # ValueError: a NUL byte in a path; RuntimeError: a symlink loop (pathlib before 3.13)
+        pass
+
+
+# A path, not a file's worth of data: the first line of <run-dir>/repo is all that is read.
+_REPO_LINE_MAX = 64 * 1024
+
+
+def _repo_of(run_dir: Path) -> Path | None:
+    """The repo named on the first line of ``<run-dir>/repo``, or None. Never blocks.
+
+    The runners write that file themselves, but a run dir is any directory a user passes,
+    so the read is as careful as forge-ui's: O_NONBLOCK so a FIFO with no writer cannot
+    hold the open, and nothing but a regular file is read (a FIFO, a device or a directory
+    named ``repo`` is ignored).
+    """
+    fd = os.open(run_dir / 'repo', os.O_RDONLY | os.O_NONBLOCK)
+    with os.fdopen(fd, 'rb') as handle:
+        if not stat.S_ISREG(os.fstat(fd).st_mode):
+            return None
+        line = handle.readline(_REPO_LINE_MAX).decode(errors='replace').strip()
+    # Empty, or text no path can hold, or relative: a relative repo would be resolved
+    # against whatever directory the runner happened to start in, and keyed to the wrong repo.
+    if not line or '\x00' in line or not os.path.isabs(line):
+        return None
+    return Path(line)
+
+
+def _register(run_dir_arg: str) -> None:
+    if os.environ.get('FORGE_RUN_REGISTRY', '').strip().lower() == 'off':
+        return
+    run_dir = Path(run_dir_arg).resolve()
+    repo = _repo_of(run_dir)
+    if repo is not None:
+        register_run_dir(repo, run_dir)
+
+
+def main() -> int:
+    """``register <run-dir>``: record the run dir under the repo its ``repo`` file names.
+
+    Always exits 0 and prints nothing. The runners call it on every plan, run and solo run,
+    and noting where a run lives must never fail, block, slow or change one: a missing
+    run dir, an unreadable or hostile ``repo`` file, an unwritable registry and arguments
+    it does not understand are all silently nothing. Ctrl-C is not swallowed, so an
+    interrupted runner still stops.
+    """
+    try:
+        args = sys.argv[1:]
+        if len(args) == 2 and args[0] == 'register':
+            _register(args[1])
+    except Exception:  # noqa: BLE001  -- see the docstring: nothing here may reach the run
+        pass
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())