loopmath 0.2.3__py3-none-any.whl → 0.2.4__py3-none-any.whl

loopmath/__init__.py

@@ -5,4 +5,4 @@ The command line (`loopmath`, or its alias `loop`) is the interface; see the
 README and `loopmath --help`.
 """
 
-__version__ = "0.2.3"
+__version__ = "0.2.4"

loopmath/adapters/atrium.py

@@ -470,7 +470,7 @@ class AtriumAdapter(Adapter):
         return {
             "ocp": "0.2",
             "producer": {
-                "name": "dagr-adapter-atrium",
+                "name": "loopmath/adapter-atrium",
                 "framework": "atrium",
                 "source_contract": "atrium/timeline+task-run-segments",
                 "capabilities": {

loopmath/adapters/bb.py

@@ -408,7 +408,7 @@ class BbAdapter(Adapter):
         )
         ignored_snapshots = sum(thread["ignored_token_snapshots"] for thread in selected)
         producer: dict[str, Any] = {
-            "name": "dagr-adapter-bb",
+            "name": "loopmath/adapter-bb",
             "framework": "bb",
             "source_contract": "bb/sqlite",
             "capabilities": {

loopmath/adapters/opencode.py

@@ -386,7 +386,7 @@ def _emit_document(
     else:
         source_contract = "opencode export"
     producer: dict[str, Any] = {
-        "name": "dagr-adapter-opencode",
+        "name": "loopmath/adapter-opencode",
         "framework": "opencode",
         "source_contract": source_contract,
         "capabilities": {

loopmath/adapters/orca.py

@@ -458,7 +458,7 @@ class OrcaAdapter(Adapter):
         return {
             "ocp": "0.2",
             "producer": {
-                "name": "dagr-adapter-orca",
+                "name": "loopmath/adapter-orca",
                 "framework": "orca",
                 "source_contract": "orca/orchestration.db",
                 "capabilities": {

loopmath/adapters/otel_genai.py

@@ -383,7 +383,7 @@ class OtelGenAIAdapter(Adapter):
         return {
             "ocp": "0.2",
             "producer": {
-                "name": "dagr-adapter-otel-genai",
+                "name": "loopmath/adapter-otel-genai",
                 "framework": "+".join(harnesses) if harnesses else "unknown",
                 "source_contract": "OTLP/JSON file exporter",
                 "capabilities": {

loopmath/adapters/paseo.py

@@ -418,7 +418,7 @@ class PaseoAdapter(Adapter):
         return {
             "ocp": "0.2",
             "producer": {
-                "name": "dagr-adapter-paseo",
+                "name": "loopmath/adapter-paseo",
                 "framework": "paseo",
                 "source_contract": "paseo/agent-json",
                 "capabilities": {

loopmath/belief/check_pymc.py

@@ -21,9 +21,13 @@ from __future__ import annotations
 import time
 
 import numpy as np
-import pymc as pm
-import pytensor
-import pytensor.tensor as pt
+
+from ..fit_bayes import use_store_compiledir
+
+use_store_compiledir()  # before pytensor is imported: its compile folder goes in the store's cache
+import pymc as pm  # noqa: E402
+import pytensor  # noqa: E402
+import pytensor.tensor as pt  # noqa: E402
 
 from .gaussian import HYPER_SD, SIGMA_PRIOR_SD, GaussianHead
 

loopmath/belief/commands.py

@@ -121,6 +121,36 @@ def _print_summary(s: dict) -> None:
                   f"(table in pymc_check.json)")
 
 
+def _in_pymc_check(exc: BaseException) -> bool:
+    """Whether `exc` was raised inside the `--full` PyMC check (check_pymc, pymc or pytensor)."""
+    tb = exc.__traceback__
+    while tb is not None:
+        if tb.tb_frame.f_globals.get("__name__") == "loopmath.belief.check_pymc":
+            return True
+        tb = tb.tb_next
+    return False
+
+
+def _pymc_check_failed(home: Path, exc: BaseException) -> int:
+    """`fit --full` whose PyMC check failed (a compiler error, say): remove the unfinished fit
+    folder and say what happened in one line, without a traceback."""
+    from .fit import FitBusy, fit_lock, remove_partials
+
+    try:
+        with fit_lock(home, LOCK_WAIT_S):  # under the lock every .partial is from a fit that stopped
+            remove_partials(home)
+    except FitBusy:
+        pass  # the next fit removes it
+    lines = [ln.strip() for ln in str(exc).splitlines() if ln.strip()]
+    said = ([ln for ln in lines if ln.startswith("ld:")]  # the linker's reason, then the first compiler error
+            or [ln for ln in lines if ln.startswith("error:") or " error: " in ln])
+    detail = (said[0] if said else (lines or [type(exc).__name__])[-1])[:200]
+    kind = "could not compile its model on this machine" if type(exc).__name__ == "CompileError" else "stopped"
+    return output.fail(f"fit --full: the PyMC check {kind} ({type(exc).__name__}: {detail}). No fit was "
+                       "written and fits/latest did not move; loopmath fit without --full fits as usual.",
+                       output.EXIT_USER)
+
+
 def fit(args: argparse.Namespace) -> int:
     home = output.home(getattr(args, "home", None))
     without = tuple(getattr(args, "without", None) or ())
@@ -140,10 +170,16 @@ def fit(args: argparse.Namespace) -> int:
         else:
             print(f"fit queued: {started.get('reason', 'a fit is running')}")
         return output.EXIT_OK
+    import contextlib
+    import sys
+
     from .fit import FitBusy, NothingToFit, UnknownSource, fit as run_fit
 
+    # --full: a failed compile makes pytensor print where it left the C code on stdout, which is for the result
+    quiet = contextlib.redirect_stdout(sys.stderr) if full else contextlib.nullcontext()
     try:
-        path = run_fit(home, no_prior=no_prior, without=without, full=full, wait_s=LOCK_WAIT_S)
+        with quiet:
+            path = run_fit(home, no_prior=no_prior, without=without, full=full, wait_s=LOCK_WAIT_S)
     except FitBusy:
         return output.fail(f"another fit has held {home / 'fits'} for more than {int(LOCK_WAIT_S)} s; "
                            "try again later or use --background", output.EXIT_LOCKED)
@@ -151,6 +187,10 @@ def fit(args: argparse.Namespace) -> int:
         return output.fail(str(exc), output.EXIT_NOT_FOUND)
     except NothingToFit as exc:
         return output.fail(str(exc), output.EXIT_USER)
+    except Exception as exc:
+        if not (full and _in_pymc_check(exc)):
+            raise
+        return _pymc_check_failed(home, exc)
     summary = _summary(path)
     if as_json:
         output.emit_json(SCHEMA, summary)

loopmath/belief/fit.py

@@ -72,7 +72,7 @@ REASON_NOTES = {
     "attempt without usable cost": "crashed or no usage reported",
     "attempt outside the workflow": "a model attempt at no piece of the run's workflow",
     "duplicate run id": "the same run found twice",
-    SHIPPED_COPY: "your store has the same run id; your copy is used",
+    SHIPPED_COPY: "this run ships with loopmath and is also in your store, so it counts once, as yours",
     "no configuration": "the run records no workflow and settings",
     "workflow ref not resolved": "a workflow this version does not know",
     "workflow has no pieces": "an empty workflow",

loopmath/builder/context.py

@@ -21,6 +21,7 @@ from typing import Any
 from ..output import EXIT_NOT_FOUND, EXIT_OK, fail, home as home_dir
 from ..recommend import commands as C
 from ..recommend import engine, storeread
+from ..store import run_names
 from ..recommend.curve import accepted_within
 from ..recommend.engine import Recommendation, r6
 from ..recommend.storeread import Conf
@@ -221,7 +222,7 @@ def recorded_runs(home: Any) -> list[tuple[Configuration, int]]:
                 run_of[str(cfg)] = str(row["run"])
     out = []
     for cfg_id, n in counts.items():
-        doc = storeread.read_json(home / "runs" / f"{run_of[cfg_id]}.ocp.json") if cfg_id in run_of else None
+        doc = storeread.read_json(home / "runs" / run_names.file_name(run_of[cfg_id])) if cfg_id in run_of else None
         conf = doc.get("run", {}).get("configuration") if isinstance(doc, dict) else None
         cfg = storeread.config_from_any(conf) if conf else None
         if cfg is not None:

loopmath/builder/predict.py

@@ -136,6 +136,12 @@ def clean(obj: dict[str, Any]) -> tuple[dict[str, Any], list[dict[str, Any]]]:
     return {**obj, "id": None, "settings": settings}, notes
 
 
+# P3-21 (0.2.4): a review gate that names a repairer at a round limit of 1 is one of loopmath's own shapes (reviewed
+# once; the search builds it and may recommend it). The workflow file check warns about it; the builder page instead
+# says on the gate what 1 round means, so that warning is not shown here.
+REVIEW_ONCE = "budget_rounds is 1"
+
+
 def parse_config(obj: Any, models: dict[str, int]
                  ) -> tuple[Configuration | None, list[dict[str, Any]], list[dict[str, Any]]]:
     """(configuration, errors, warnings); the configuration is None when it does not read at all."""
@@ -158,7 +164,8 @@ def parse_config(obj: Any, models: dict[str, int]
             errors.append(err(p.id, f"piece {p.id!r}: model {s.model!r} is a retired or unknown model; "
                                     f"pick one of {known}"))
     if not errors:
-        warnings += notes_of(workflow_warnings(cfg.workflow) + settings_warnings(cfg.settings), cfg)
+        shown = [w for w in workflow_warnings(cfg.workflow) if REVIEW_ONCE not in w]
+        warnings += notes_of(shown + settings_warnings(cfg.settings), cfg)
     return cfg, errors, warnings
 
 

loopmath/cli.py

@@ -5,27 +5,26 @@ Verbs:
   scan             explain where implicit scanning occurs
   adapt            emit OCP v0.2 from a registered ADE adapter
   validate-prices  check a price table's schema, staleness and todo flags
-  analyze-e0       the frozen E0 corpus walkdown
   prices           show the active price table
   graph            the workflow graph of one or more workspaces (ocp, json, dot, run, html: self-contained interactive HTML viewer)
-  research         E1 v2 cost model: research fit, research transfer-test (needs the [bayes] extra)
-  verify-receipts  verify an E2 spend ledger and frozen preregistration
+  research         research data folders: research fit, research transfer-test (the bayes extra), research analyze-e0 (the e0 extra)
+  verify-receipts  check that the receipts in your store are whole and scored right (or give a research ledger file)
 
 0.1.0 verbs (design/0.1/02-commands.md, registered in cli_registry.py):
-  plan:    task-types  workflows  recommend  plan
-  record:  run start|attempt|artifact|finish|import  outcome  budget  config
+  plan:    task-types  workflows  recommend  builder  plan
+  record:  run start|record|import|attempt|artifact|finish|sessions  outcome  budget  config
   learn:   fit  onboard  share
   view:    runs  posterior  status  report  doctor  skill  ocp
 
-No verb in this CLI makes a network call. Verbs write only to the store
-($LOOPMATH_HOME, default ~/.loopmath, which also holds the parse cache) and to
-paths the user names.
+No verb in this CLI connects to another machine; builder serves on 127.0.0.1 only.
+Verbs write only to the store ($LOOPMATH_HOME, default ~/.loopmath, which also
+holds the parse cache and the fit --full compile folder), to the skill folders
+skill install names, and to paths the user names.
 """
 
 from __future__ import annotations
 
 import argparse
-import importlib.util as _importlib_util
 import sys
 import time
 from types import ModuleType
@@ -79,6 +78,7 @@ class _CliModule(ModuleType):
 sys.modules[__name__].__class__ = _CliModule
 
 DEFAULT_SINCE_DAYS = 14.0
+_ANALYZE_SCHEMA = "loopmath.analyze/1"
 
 
 def _counted_noun(count: int, singular: str, plural: str | None = None) -> str:
@@ -185,6 +185,18 @@ def analyze(args: argparse.Namespace) -> int:
         ci=args.ci,
     )
     result["ratio_pair"] = _extremes_ratio(df, result, price_mod)
+    result["min_n"] = args.min_n
+
+    if getattr(args, "json", False):
+        from .output import emit_json
+
+        grading = list(grade_mod.grading_report(records, coverage)) if args.grading else None
+        emit_json(_ANALYZE_SCHEMA, _cli_support.analyze_payload(
+            result, diag=diag, coverage=coverage, price_lines=price_lines, grading=grading,
+            walkdown=surface_mod.walkdown(result)))
+        if not args.quiet:
+            print(f"ran in {time.time() - t0:.1f} s", file=sys.stderr)
+        return 0
 
     print(
         terminal.render(
@@ -246,7 +258,7 @@ def _add_graph(sub) -> None:
     p.add_argument("--workspace", action="append", default=[], help="native workspace name to include (repeatable; required unless --ocp is used)")
     p.add_argument("--ocp", action="append", default=[], metavar="FILE", help="read an OCP document (v0.2 or later) as a graph source (repeatable)")
     p.add_argument("--format", type=_cli_support._graph_format, choices=GRAPH_FORMATS, default="ocp", help="ocp (OCP v0.3, default), json (internal dagr_graph), dot (Graphviz), run (herdr-dagr contract v3 run file), html (self-contained interactive HTML viewer)")
-    p.add_argument("--out", default=None, help="write here instead of stdout (must be inside the git worktree of the current directory; parent directories are created)")
+    p.add_argument("--out", default=None, help="write here instead of stdout (any path; missing folders are created; an existing file is replaced)")
     p.add_argument("--privacy", choices=("metadata_only", "full"), default="metadata_only", help="OCP privacy profile (default metadata_only)")
     p.add_argument("--logs", default=None, help="parse this path instead of the default log roots")
     p.add_argument(
@@ -259,7 +271,8 @@ def _add_graph(sub) -> None:
     p.add_argument("--limit", type=int, default=None, help="stop after N files per harness")
     p.add_argument("--no-cache", action="store_true", help="reparse everything, ignoring the cache")
     p.add_argument("--prices", default=None, help="price table to use instead of the packaged one")
-    p.add_argument("--quiet", action="store_true", help="suppress progress output on stderr; exclusion counters always print")
+    p.add_argument("--quiet", action="store_true", help="suppress progress output on stderr")
+    p.add_argument("--verbose", action="store_true", help="also print every count of what was skipped, excluded or could not be placed")
     p.set_defaults(func=graph_verb)
 
 
@@ -279,7 +292,7 @@ def adapt_verb(args: argparse.Namespace) -> int:
 
     out_path = None
     if args.out:
-        out_path, err = _resolve_out(args.out)
+        out_path, err = _resolve_out(args.out, "out.ocp.json")
         if err:
             print(err, file=sys.stderr)
             return 2
@@ -302,9 +315,18 @@ def adapt_verb(args: argparse.Namespace) -> int:
 
     adapter = adapter_type()
     adapter.configure_services(default_adapter_services())
-    doc = adapter.emit(selection)
+    try:
+        doc = adapter.emit(selection)
+    except (OSError, ValueError) as exc:  # a store path it cannot read: say so, no traceback
+        print(f"error: adapt {args.name}: {exc}", file=sys.stderr)
+        return 1
     if not isinstance(doc, dict):
         raise TypeError(f"adapter {args.name!r} emit() must return a dict")
+    if not doc.get("nodes") and not doc.get("attempts"):
+        where = ", ".join(str(p) for p in selection.stores) if selection.stores else "its default location"
+        print(f"error: adapt {args.name} found no sessions in {where}; nothing written. Point --store at the "
+              f"{args.name} data, or widen --since, --until, --session and --workspace", file=sys.stderr)
+        return 1
     from .ocp import version_at_least
 
     if not version_at_least(doc, "0.2"):
@@ -323,7 +345,7 @@ def adapt_verb(args: argparse.Namespace) -> int:
 def _add_adapt(sub) -> None:
     p = sub.add_parser("adapt", help="emit OCP v0.2 from an ADE store (loopmath ocp migrate converts it to v0.3)")
     p.add_argument("name", metavar="NAME", help="registered adapter name")
-    p.add_argument("--out", default=None, help="write here instead of stdout (must be inside the git worktree of the current directory; parent directories are created)")
+    p.add_argument("--out", default=None, help="write here instead of stdout (any path; missing folders are created; an existing file is replaced)")
     p.add_argument("--store", action="append", default=[], metavar="PATH", help="use this store path instead of discovery (repeatable)")
     p.add_argument("--session", action="append", default=[], metavar="ID", help="include this session id (repeatable; default: all)")
     p.add_argument("--workspace", action="append", default=[], metavar="WORKSPACE", help="include this workspace (repeatable; default: all)")
@@ -371,6 +393,9 @@ def _add_analyze(sub) -> None:
     p.add_argument("--tokens", action="store_true", help="rank by output tokens instead of dollars")
     p.add_argument("--grading", action="store_true", help="print which rule graded what")
     p.add_argument("--quiet", action="store_true", help="suppress progress and timing on stderr")
+    p.add_argument("--home", default=None, metavar="PATH", help="store root whose cache/ holds the log parse cache "
+                   "(default: $LOOPMATH_HOME or ~/.loopmath; LOOPMATH_CACHE_DIR wins); analyze writes nothing else")
+    p.add_argument("--json", action="store_true", help="print one JSON object on stdout")
     p.set_defaults(func=analyze)
 
 
@@ -385,11 +410,18 @@ def _add_validate_prices(sub) -> None:
 def _add_fit(sub) -> None:
     from .research_defaults import E1A_OBSERVE, SEED
 
-    research = sub.add_parser("research", help="E1 research verbs: fit, transfer-test (needs the [bayes] extra)")
+    research = sub.add_parser(
+        "research",
+        help="verbs for research data folders that are not part of the package (loopmath research --help)",
+        description="Verbs for research data folders that are not part of the package: sweep run records "
+                    "(research fit, research transfer-test; they need the bayes extra) and a session corpus "
+                    "(research analyze-e0; it needs the e0 extra). Name a folder with --sweep-dir or --corpus, "
+                    "LOOPMATH_SWEEP_DIR or LOOPMATH_E0_CORPUS, or config research.sweep_dir or research.e0_corpus.",
+    )
     rsub = research.add_subparsers(dest="research_command", required=True)
     for name, fn, helptext in (
-        ("fit", fit_verb, "fit the E1 cost model on the sweep data"),
-        ("transfer-test", transfer_test_verb, "score held-out cells from a fit"),
+        ("fit", fit_verb, "fit the research cost model on sweep run records"),
+        ("transfer-test", transfer_test_verb, "fit on some cells of the sweep and score the held-out ones"),
     ):
         p = rsub.add_parser(name, help=helptext)
         p.add_argument("--sweep-dir", default=None, help="sweep run records directory (default: LOOPMATH_SWEEP_DIR, then research.sweep_dir in config)")
@@ -405,10 +437,20 @@ def _add_fit(sub) -> None:
         else:
             p.add_argument("--ci", type=float, default=0.80, help="central interval for held-out coverage (default 0.80)")
         p.set_defaults(func=fn)
+    from .e0 import verb as _e0_verb
+
+    _e0_verb.register(rsub)
 
 
 def verify_receipts_verb(args: argparse.Namespace) -> int:
-    """Verify an E2 receipt ledger and print one machine-friendly result."""
+    """No ledger: check the store's receipts. A ledger path: verify that research receipt ledger."""
+    if args.ledger is None:
+        from .store.home import Store
+        from .store.verify import verify_lines, verify_store
+
+        res = verify_store(Store(args.home))
+        print("\n".join(verify_lines(res)))
+        return 1 if res["failed"] else 0
     from .receipts import ReceiptViolation, verify_receipts
 
     try:
@@ -421,18 +463,20 @@ def verify_receipts_verb(args: argparse.Namespace) -> int:
 
 
 def _add_verify_receipts(sub) -> None:
-    p = sub.add_parser("verify-receipts", help="verify an E2 receipt ledger")
+    p = sub.add_parser("verify-receipts", help="check that the receipts in your store are whole and scored right "
+                       "(or give a research ledger file)")
     p.add_argument(
         "ledger",
         nargs="?",
-        default="e2-receipts.jsonl",
-        help="receipt ledger (default: e2-receipts.jsonl)",
+        default=None,
+        help="a research receipt ledger to verify instead (e.g. e2-receipts.jsonl)",
     )
     p.add_argument(
         "--frozen",
         default=None,
-        help="checksum file (default: FROZEN.txt beside the ledger)",
+        help="with a ledger: its checksum file (default: FROZEN.txt beside the ledger)",
     )
+    p.add_argument("--home", default=None, metavar="PATH", help="the store (default: $LOOPMATH_HOME or ~/.loopmath)")
     p.set_defaults(func=verify_receipts_verb)
 
 
@@ -455,15 +499,14 @@ def main(argv: list[str] | None = None) -> int:
 
     _registry.register(sub)
 
-    if _importlib_util.find_spec("matplotlib") is not None:
-        # The E0 walkdown verb draws figures, so running it needs matplotlib.
-        # SPEC section 2's light-core rule says `analyze` runs on numpy and
-        # pandas, so matplotlib lives in the `e0` extra and this verb is simply
-        # absent without it. It registers from e0/verb.py without importing the
-        # walkdown, so no other command pays for pandas and matplotlib.
-        from .e0 import verb as _e0_verb
+    # The E0 walkdown draws figures, so running it needs matplotlib (the `e0`
+    # extra; SPEC section 2's light core is numpy and pandas). It is listed under
+    # `loopmath research`; the old top-level name stays callable, off the list.
+    # It registers from e0/verb.py without importing the walkdown, so no other
+    # command pays for pandas and matplotlib.
+    from .e0 import verb as _e0_verb
 
-        _e0_verb.register(sub)
+    _e0_verb.register(sub, listed=False)
 
     try:
         _add_fit(sub)

loopmath/cli_graph.py

@@ -10,6 +10,8 @@ from .cli_support import _pipeline_counters, _scan_snapshot_id
 
 
 GRAPH_FORMATS = ("ocp", "json", "dot", "run", "html")
+# The file name a refused directory `--out` suggests, by format.
+_OUT_EXAMPLES = {"ocp": "out.ocp.json", "json": "out.json", "dot": "out.dot", "run": "out.run.json", "html": "out.html"}
 # Graph.meta keys that are totals, not exclusions: printed in the headline, not the list.
 _GRAPH_META_TOTALS = (
     "n_nodes",
@@ -47,21 +49,21 @@ def _worktree_root():
     return Path(r.stdout.strip()).resolve()
 
 
-def _resolve_out(out: str):
-    """`--out` resolved against the worktree root (the git top level of the
-    current directory); anything outside it is refused, and so is any `--out`
-    when the current directory is not inside a git worktree. Returns (path, None)
-    or (None, error message); nothing is written on refusal."""
+def _resolve_out(out: str, example: str = "out.json"):
+    """`--out` as the user named it: any path, relative to the current directory,
+    with `~` expanded. A path that is an existing directory is refused (writing
+    would replace it), and so is one under an existing file, which cannot be a
+    folder. Returns (path, None) or (None, error message); nothing is written on
+    refusal. Missing parent folders are created when the file is written.
+    `example` is the file name the directory refusal suggests."""
     from pathlib import Path
 
-    root = _worktree_root()
     target = Path(out).expanduser().resolve()
-    if root is None:
-        return None, f"error: --out {out} refused: {Path.cwd()} is not inside a git worktree (git rev-parse --show-toplevel failed), so there is no worktree to write into; run from inside one or drop --out"
-    try:
-        target.relative_to(root)
-    except ValueError:
-        return None, f"error: --out {out} resolves to {target}, outside the worktree {root}; the extractor writes only inside it"
+    if target.is_dir():
+        return None, f"error: --out {out} is a directory; name a file, for example {Path(out) / example}"
+    blocker = next((p for p in target.parents if p.exists()), None)
+    if blocker is not None and not blocker.is_dir():
+        return None, f"error: --out {out} cannot be written: {blocker} is a file, not a folder"
     return target, None
 
 
@@ -106,9 +108,9 @@ def graph_verb(args: argparse.Namespace) -> int:
     self-contained interactive visualizer. Everything the
     pipeline excluded (files skipped, cut by `--limit` or the time window,
     records ungraded or unpriced) and everything the extractor could not place
-    is counted in the graph's meta, which every format carries, and printed on
-    stderr. `--quiet` silences progress
-    only; the counters always print.
+    is counted in the graph's meta, which every format carries; `--verbose`
+    prints every counter on stderr, and by default only a summary prints.
+    `--quiet` silences progress only.
     """
     import json
 
@@ -125,7 +127,7 @@ def graph_verb(args: argparse.Namespace) -> int:
 
     out_path = None
     if args.out:
-        out_path, err = _resolve_out(args.out)
+        out_path, err = _resolve_out(args.out, _OUT_EXAMPLES.get(args.format, "out.json"))
         if err:
             print(err, file=sys.stderr)
             return 2
@@ -317,24 +319,31 @@ def graph_verb(args: argparse.Namespace) -> int:
             f"  imported {len(args.ocp)} OCP document(s); "
             "costs and evidence tiers kept as supplied"
         )
+    counters: list[str] = []
     for key in sorted(m):
         value = m[key]
         if key.endswith("_reason"):
             continue
         if value is None and f"{key}_reason" in m:
-            say(f"  {key}: unknown ({m[f'{key}_reason']})")
+            counters.append(f"  {key}: unknown ({m[f'{key}_reason']})")
         elif (
             isinstance(value, (int, float))
             and not isinstance(value, bool)
             and value
             and key not in _GRAPH_META_TOTALS
         ):
-            say(f"  {key}: {value}")
+            counters.append(f"  {key}: {value}")
     for key in sorted(emitter):
         # The run exporter is a full honesty ledger: print every one of its
         # counters, including zero, so a collision class is never silent.
         if emitter[key] or (args.format == "run" and key.startswith("run.")):
-            say(f"  emitter.{key}: {emitter[key]}")
+            counters.append(f"  emitter.{key}: {emitter[key]}")
+    # The counters are for whoever debugs the extractor; every format carries them in its meta.
+    if getattr(args, "verbose", False):
+        for line in counters:
+            say(line)
+    elif counters:
+        say(f"  {len(counters)} more counts of what was skipped or could not be placed: add --verbose")
     if out_path is not None:
         say(f"wrote {out_path} ({args.format}) in {time.time() - t0:.1f} s")
     return 0

loopmath/cli_registry.py

@@ -146,7 +146,7 @@ TIER_CHOICES = ["verified", "reported", "heuristic", "asserted"]
 
 
 def _add_recording(sub) -> None:
-    p = sub.add_parser("run", help="record a run: start, record, import, attempt, artifact, finish")
+    p = sub.add_parser("run", help="record a run: start, record, import, attempt, artifact, finish, sessions")
     rs = p.add_subparsers(dest="run_command", required=True)
 
     q = rs.add_parser("start", help="open a run (OCP v0.3 skeleton in the store)")
@@ -178,7 +178,7 @@ def _add_recording(sub) -> None:
     q.add_argument("--model", default=None, metavar="M", help="model name")
     q.add_argument("--effort", default=None, metavar="E", help="reasoning effort")
     q.add_argument("--cwd", default=None, metavar="PATH", help="the folder the agent works in; with no --session its log is matched by this folder, a session that started in the attempt's window, and the model")
-    q.add_argument("--session", default=None, metavar="ID", help="session id, or self for the orchestrator's own Claude Code session, counted only inside this attempt's started-at to ended-at window")
+    q.add_argument("--session", default=None, metavar="ID", help="session id, or self for the orchestrator's own Claude Code session, counted only inside this attempt's started-at to ended-at window (outside Claude Code: the one Claude Code session in this folder active in the last 10 minutes; run sessions lists the ids)")
     q.add_argument("--round", type=int, default=1, metavar="K", help="round of this piece, 1 for the first try")
     q.add_argument("--cause", default="initial", choices=["initial", "sent_back", "gate_failed", "followup", "other"],
                    help="why this attempt was started")
@@ -225,10 +225,13 @@ def _add_recording(sub) -> None:
                    "it replaces the rule the recommendation was made for")
     q.add_argument("--session", action="append", default=[], metavar="[PIECE=]ID", help="a session that worked on the run: a "
                    "Claude Code session id, a Codex thread id, or self for this Claude Code session (repeatable); "
-                   "PIECE= names its piece")
+                   "PIECE= names its piece; run sessions lists the ids. Only the part of a session inside the window "
+                   "counts (a Codex session counts whole)")
     q.add_argument("--cwd", action="append", default=[], metavar="[PIECE=]PATH", help="a folder an agent with no session id "
                    "worked in; its log is matched at finish by folder and time (repeatable)")
-    q.add_argument("--since", default=None, metavar="TS", help="when the work began, without --run (e.g. 2h or an ISO time)")
+    q.add_argument("--since", default=None, metavar="TS", help="when the work began (e.g. 2h or a local ISO time); with "
+                   "--run the default is the run's start")
+    q.add_argument("--until", default=None, metavar="TS", help="when the work ended (e.g. 1h or a local ISO time; default now)")
     q.add_argument("--verified", action="append", default=[], metavar="NAME=VALUE", help="a verdict you observed yourself "
                    "(pass, fail, accept, reject, error)")
     q.add_argument("--reported", action="append", default=[], metavar="NAME=VALUE", help="a verdict someone reported")
@@ -240,6 +243,13 @@ def _add_recording(sub) -> None:
     _common(q)
     q.set_defaults(slate=None, new_slate=False, func=_lazy("loopmath.store.record:run_record"))
 
+    q = rs.add_parser("sessions", help="list the recent Claude Code and Codex sessions in this folder, with their ids")
+    q.add_argument("--cwd", default=None, metavar="PATH", help="the folder the sessions ran in (default: this one)")
+    q.add_argument("--days", type=float, default=7, metavar="N", help="how far back to look (default 7)")
+    q.add_argument("--limit", type=int, default=10, metavar="N", help="at most this many, newest first (default 10)")
+    _common(q)
+    q.set_defaults(func=_lazy("loopmath.store.commands:run_sessions"))
+
     p = sub.add_parser("outcome", help="record a verdict, score, late event or pair preference")
     target = p.add_mutually_exclusive_group(required=True)
     target.add_argument("--run", default=None, metavar="RUN", help="the run the signal is about")
@@ -329,16 +339,16 @@ def _add_learning(sub) -> None:
     p = sub.add_parser("share", help="write the shareable part of your store to a file",
                        description="Keeps task types, features, workflows, settings, tokens, dollars and outcomes; "
                                    "repos, tasks and runs only as salted hashes; no titles, paths, commands, session ids or commits.")
-    p.add_argument("--out", default=None, metavar="FILE", help="the share file to write (gzip JSON; check it first with --preview)")
+    p.add_argument("--out", default=None, metavar="FILE", help="the share file to write: plain JSON for FILE.json, gzip JSON for FILE.json.gz or any other name (check it first with --preview)")
     p.add_argument("--since", default=None, metavar="D", help="only runs since then: 90d, 4w, 12h or a date")
     p.add_argument("--preview", action="store_true", help="print exactly what would leave; writes no share file")
     _common(p)
     p.set_defaults(func=_lazy("loopmath.share.commands:share"))
 
-    p = sub.add_parser("prior", help="the shipped prior bundle: show, build, import-shared")
+    p = sub.add_parser("prior", help="the shipped prior bundle: show, build, import-shared, remove-shared")
     ps = p.add_subparsers(dest="prior_command", required=True)
     q = ps.add_parser("build", help="rebuild the packaged prior bundle from the sweep, E0 and RQ1 inputs")
-    q.add_argument("--out", default=None, metavar="DIR", help="where to write the bundle (default: the packaged bundle folder, which it replaces)")
+    q.add_argument("--out", default=None, metavar="DIR", help="where to write the bundle (required)")
     q.add_argument("--sweep-dir", action="append", default=None, metavar="PATH", help="sweep results, one folder per batch; repeatable (default: LOOPMATH_SWEEP_DIR, one folder)")
     q.add_argument("--e0-corpus", default=None, metavar="PATH", help="E0 corpus (default: LOOPMATH_E0_CORPUS)")
     q.add_argument("--rq1-dir", default=None, metavar="PATH", help="RQ1 OCP documents (default: LOOPMATH_PRIOR_RQ1)")
@@ -352,6 +362,10 @@ def _add_learning(sub) -> None:
     q.add_argument("file", metavar="FILE", help="a loopmath.share/1 file written by loopmath share (gzip or plain JSON)")
     _common(q)
     q.set_defaults(func=_lazy("loopmath.share.commands:import_shared"))
+    q = ps.add_parser("remove-shared", help="take an imported organization's runs out of your priors")
+    q.add_argument("org", metavar="ORG", help="the organization import-shared named, as shared:HASH or HASH")
+    _common(q)
+    q.set_defaults(func=_lazy("loopmath.share.commands:remove_shared"))
 
 
 # ---------------------------------------------------------------- viewing
@@ -408,6 +422,9 @@ def _add_viewing(sub) -> None:
                        help="for you in every folder (user), or for this repository only (project)")
         q.add_argument("--dir", default=None, metavar="PATH", help="the project folder for --scope project "
                        "(default: this folder)")
+        if verb == "install":
+            q.add_argument("--dry-run", action="store_true", help="print every file install would write or "
+                           "change, and write nothing")
         _common(q)
         q.set_defaults(func=_lazy(f"loopmath.skill.commands:{verb}"))
     q = ss.add_parser("show", help="print one skill (default loopmath, the start-here skill) or the shared reference")
@@ -429,7 +446,7 @@ def _add_viewing(sub) -> None:
     q.set_defaults(func=_lazy("loopmath.ocp.commands:migrate"))
 
 
-HIDDEN = frozenset({"plan"})  # callable, but not listed by `loopmath --help`
+HIDDEN = frozenset({"plan", "analyze-e0"})  # callable, but not listed by `loopmath --help`
 
 
 def command_metavar(sub) -> str: