loopmath 0.3.0__tar.gz → 0.3.1__tar.gz

{loopmath-0.3.0 → loopmath-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loopmath
-Version: 0.3.0
+Version: 0.3.1
 Summary: Plan agent workflows, record how they went, and learn from your own Claude Code and Codex logs
 Author: QKV Labs
 License-Expression: MIT
@@ -177,9 +177,12 @@ The workflow builder is the one page that is served: `loopmath builder --type bu
 | Record | `run` (start, record, import, attempt, artifact, finish, sessions), `outcome`, `budget`, `config` (get, set) |
 | Learn | `fit`, `onboard`, `share`, `prior` |
 | View | `runs`, `posterior`, `status`, `report`, `doctor`, `verify-receipts` |
+| Harness testing | `check-change`, `gate` (experimental) |
 | Skill | `skill` (install, uninstall, show) |
 | OCP | `ocp` (validate, migrate) |
-| Log analysis | `analyze`, `graph`, `adapt`, `prices`, `validate-prices`, `scan` |
+| Log analysis | `analyze`, `graph`, `adapt`, `prices`, `validate-prices` |
+
+These are experimental: `gate`, the harness-part estimates (`recommend --harness-variants` and `--harness`, `posterior --level harness` and its `factors`), `adapt harness2` and the ADE adapters (`adapt NAME`). Each works and has tests, but has had little use on real work so far, and its output may change. Their help says so too.
 
 Each command prints a short summary by default. With `--json`, it prints exactly one JSON object instead. One exception: `loopmath adapt harness2` and `adapt harness-runs` without `--out` print the run documents on stdout, one per line, so their `--json` summary goes to stderr. Exit codes: 0 ok, 1 user error, 2 not found, 3 not implemented, 4 store locked, 5 no fit yet. For flags, `loopmath <command> --help` is the source of truth. Commands, pages and the `runs` table show times in your local time with the zone; the store and `--json` keep UTC. A cost under a cent shows one significant digit (`$0.004`), and an exact zero is `$0`.
 
@@ -255,21 +258,21 @@ A run can record the harness it ran with: the prompt files, skills, plugins, MCP
   `cost` is the multiplier on an attempt's dollars when the part is present; `success` is percentage points.
 - `loopmath recommend --harness-variants` prices the trees your runs used most, and `--harness PATH` prices one more, against the bare harness label on the same draws.
 
-An estimate is the change when a named part is present, pooled over its versions. It is not the effect of one edit, and a part on every run cannot be told apart from its harness. The cost ranges met their stated coverage in simulation. **The success ranges did not:** they pull effects toward 0, and their 80% ranges held 60% of nonzero effects. So they are marked `calibrated: false`, and so are the success-side numbers of a priced variant. With no record anywhere, every number is what it was before. The record, the digest, the factor map and the limits are in [`spec/harness.md`](spec/harness.md).
+An estimate is the change when a named part is present, pooled over its versions. It is not the effect of one edit, and a part on every run cannot be told apart from its harness. The cost ranges met their stated coverage in simulation. **The success ranges did not:** they pull effects toward 0, and their 80% ranges held 60% of nonzero effects. So they are marked `calibrated: false`, and so are the success-side numbers of a priced variant, and the harness-part estimates are experimental. With no record anywhere, every number is what it was before. The record, the digest, the factor map and the limits are in [`spec/harness.md`](spec/harness.md).
 
 ## Testing a harness change
 
 These commands are for changing the harness your agents run with and finding out whether the change paid off.
 
 - **Harness parts and `--harness`.** Record the tree each run used (`run finish --harness auto` or `PATH`), and the fit learns each named part's effect, as in the section above. `recommend --harness-variants` prices the trees your runs used on the configurations those runs used, and on the recommendation's own when their harness has data on the parts; `--harness PATH` prices one more tree. Where a tree is not priced, `not_priced` in `--json` says why. The record, the factor map and the limits are in [`spec/harness.md`](spec/harness.md).
-- **`adapt harness-runs` and `adapt harness2`.** These bring in runs another tool made. `loopmath adapt harness-runs FILE --out DIR` reads a `loopmath.harness-runs/0.1` file, one JSON line per rollout, as an auto-research loop, a plugin eval suite or a hand A/B writes it. `loopmath adapt harness2 RUNS --out DIR` reads a harness2 runs folder. Then `loopmath run import DIR --finish` stores the runs. The row format, outcomes, costs and worked examples are in [`spec/harness-runs.md`](spec/harness-runs.md).
+- **`adapt harness-runs` and `adapt harness2`.** These bring in runs another tool made; `adapt harness2` is experimental, since its input format is read from harness2's code and it has not yet read a real runs folder. `loopmath adapt harness-runs FILE --out DIR` reads a `loopmath.harness-runs/0.1` file, one JSON line per rollout, as an auto-research loop, a plugin eval suite or a hand A/B writes it. `loopmath adapt harness2 RUNS --out DIR` reads a harness2 runs folder. Then `loopmath run import DIR --finish` stores the runs. The row format, outcomes, costs and worked examples are in [`spec/harness-runs.md`](spec/harness-runs.md).
 - **`check-change`.** It decides whether a change beats what it replaces, on paired runs:
   - `check-change start --base LABEL|PATH --cand LABEL|PATH --n N` plans the pairs and each pair's arm order;
-  - `check-change status` gives the comparison, the verdict once there is one (adopt or reject) and the next pair worth running;
+  - `check-change status` gives the comparison, the verdict once there is one (adopt or reject) and the next pair worth running. A check that reaches its cap or spends its budget before the evidence decides keeps the base and says `not decided`. The next pair's value and price are shown at each look and stop nothing; `--value-stop` also stops a check, not decided, when the next pair is worth less than its price, from 4 scored pairs on (`--min-pairs K`); `--json` keeps `verdict: reject` there, with `comparison.stop` and `comparison.decided: false`;
   - `check-change from-runs --base-label SEL --cand-label SEL` compares finished runs already in the store, picked by a run label, a configuration id, a harness digest (a prefix of one digest will do) or `arm:NAME`.
 
   `--rule` names what counts as accepted, and `loopmath check-change --help` lists the rest. A run with no dollar cost leaves the decision to the outcomes alone, and the cost reads unknown; a budget or `--objective cpar` then refuses, naming the runs without one.
-- **`gate`.** For a loop that adopts changes on its own, it answers: adopt the candidate, reject it and keep the base, or replicate N more pairs first. `loopmath gate --base SEL --cand SEL` reads the finished runs in the store, or `--runs FILE` reads `loopmath.harness-runs/0.1` rows; an arm is a harness digest (`sha256:<hex>` or `digest:sha256:<hex>`, a prefix of one digest will do), a configuration id, or `arm=NAME` or `arm:NAME`; `check-change from-runs` takes the same forms. `--rule` takes the built-in rules or a rule defined under `[rules.NAME]` in the store's config, which the gate reads as `check-change` does, also with `--runs`. The comparison of the paired runs is `check-change`'s, and the gate adds the loop's policy to it: no adoption before `--r-min` pairs, looks at 1, 2, 4 and so on pairs up to `--r-max`, a `--floor` (the smallest gain worth adopting, 0 or more; under an acceptance rule it applies to the cut in cost per accepted result, a fraction, or to the gain in the chance of acceptance when a cost is unknown), and the dollars, `--budget-usd` for both arms (0 buys no further pair) and `--max-cost-ratio`. With no evidence, an arm that matches no run or a rule that scores no pair, it exits 1 and names the arms or the rules that are there. Both dollar flags need every run's cost and refuse, naming the runs without one; with neither flag, a run with no recorded cost leaves the decision to the outcomes alone, and the cost reads unknown, never $0. When nothing resolves within the cap or the budget, it keeps the base and says where it stopped. In Python, `loopmath.gate.decide(base_runs, cand_runs, GatePolicy(...))` gives the same answer and writes nothing; `loopmath gate --help` lists the rest.
+- **`gate` (experimental).** For a loop that adopts changes on its own, it answers: adopt the candidate, reject it and keep the base, or replicate N more pairs first. `loopmath gate --base SEL --cand SEL` reads the finished runs in the store, or `--runs FILE` reads `loopmath.harness-runs/0.1` rows; an arm is a harness digest (`sha256:<hex>` or `digest:sha256:<hex>`, a prefix of one digest will do), a configuration id, or `arm=NAME` or `arm:NAME`; `check-change from-runs` takes the same forms. `--rule` takes the built-in rules or a rule defined under `[rules.NAME]` in the store's config, which the gate reads as `check-change` does, also with `--runs`. The comparison of the paired runs is `check-change`'s, and the gate adds the loop's policy to it: no adoption before `--r-min` pairs, looks at 1, 2, 4 and so on pairs up to `--r-max`, a `--floor` (the smallest gain worth adopting, 0 or more; under an acceptance rule it applies to the cut in cost per accepted result, a fraction, or to the gain in the chance of acceptance when a cost is unknown), and the dollars, `--budget-usd` for both arms (0 buys no further pair) and `--max-cost-ratio`. With no evidence, an arm that matches no run or a rule that scores no pair, it exits 1 and names the arms or the rules that are there. Both dollar flags need every run's cost and refuse, naming the runs without one; with neither flag, a run with no recorded cost leaves the decision to the outcomes alone, and the cost reads unknown, never $0. When nothing resolves within the cap or the budget, it keeps the base and says where it stopped. In Python, `loopmath.gate.decide(base_runs, cand_runs, GatePolicy(...))` gives the same answer and writes nothing; `loopmath gate --help` lists the rest.
 
 ## The store and privacy
 
@@ -302,11 +305,7 @@ loopmath graph --workspace NAME --format html --out graph.html
 
 `loopmath prices` lists the packaged prices with the source of each. A rate marked "rate not confirmed" is a best public-price guess, and every dollar figure priced with one says so.
 
-`graph` rebuilds which agent launched which, and which session read what another wrote. Its formats are `ocp`, `json`, `dot`, `run` and `html`. `graph --out FILE` and `adapt NAME --out FILE` write to any path you name: missing folders are created, an existing file is replaced, and a directory is refused. `graph` prints a short summary on stderr; `--verbose` adds every count of what was skipped or could not be placed. See the [workflow graph guide](docs/graph.md) and [adapters](docs/adapters.md).
-
-## Research data
-
-`loopmath research --help` lists the verbs that read research data folders, which are not part of the package: `research fit` and `research transfer-test` read sweep run records, and `research analyze-e0` reads a session corpus. Name the folders with a flag (`--sweep-dir`, `--corpus`), an environment variable (`LOOPMATH_SWEEP_DIR`, `LOOPMATH_E0_CORPUS`), or config (`loopmath config set research.sweep_dir PATH`, `research.e0_corpus`). `research fit` and `research transfer-test` need the `bayes` extra (`pip install 'loopmath[bayes]'`), and `research analyze-e0` the `e0` extra. `loopmath prior build --out DIR` rebuilds the packaged prior bundle from research data folders like these; `loopmath prior build --help` names them.
+`graph` rebuilds which agent launched which, and which session read what another wrote. Its formats are `ocp`, `json`, `dot`, `run` and `html`. `graph --out FILE` and `adapt NAME --out FILE` write to any path you name: missing folders are created, an existing file is replaced, and a directory is refused. `graph` prints a short summary on stderr; `--verbose` adds every count of what was skipped or could not be placed. See the [workflow graph guide](docs/graph.md) and [adapters](docs/adapters.md). The ADE adapters (`adapt NAME`) are experimental: each is tested on a synthetic fixture written from its tool's format, not yet on a real store.
 
 ## More
 

{loopmath-0.3.0 → loopmath-0.3.1}/README.md

@@ -139,9 +139,12 @@ The workflow builder is the one page that is served: `loopmath builder --type bu
 | Record | `run` (start, record, import, attempt, artifact, finish, sessions), `outcome`, `budget`, `config` (get, set) |
 | Learn | `fit`, `onboard`, `share`, `prior` |
 | View | `runs`, `posterior`, `status`, `report`, `doctor`, `verify-receipts` |
+| Harness testing | `check-change`, `gate` (experimental) |
 | Skill | `skill` (install, uninstall, show) |
 | OCP | `ocp` (validate, migrate) |
-| Log analysis | `analyze`, `graph`, `adapt`, `prices`, `validate-prices`, `scan` |
+| Log analysis | `analyze`, `graph`, `adapt`, `prices`, `validate-prices` |
+
+These are experimental: `gate`, the harness-part estimates (`recommend --harness-variants` and `--harness`, `posterior --level harness` and its `factors`), `adapt harness2` and the ADE adapters (`adapt NAME`). Each works and has tests, but has had little use on real work so far, and its output may change. Their help says so too.
 
 Each command prints a short summary by default. With `--json`, it prints exactly one JSON object instead. One exception: `loopmath adapt harness2` and `adapt harness-runs` without `--out` print the run documents on stdout, one per line, so their `--json` summary goes to stderr. Exit codes: 0 ok, 1 user error, 2 not found, 3 not implemented, 4 store locked, 5 no fit yet. For flags, `loopmath <command> --help` is the source of truth. Commands, pages and the `runs` table show times in your local time with the zone; the store and `--json` keep UTC. A cost under a cent shows one significant digit (`$0.004`), and an exact zero is `$0`.
 
@@ -217,21 +220,21 @@ A run can record the harness it ran with: the prompt files, skills, plugins, MCP
   `cost` is the multiplier on an attempt's dollars when the part is present; `success` is percentage points.
 - `loopmath recommend --harness-variants` prices the trees your runs used most, and `--harness PATH` prices one more, against the bare harness label on the same draws.
 
-An estimate is the change when a named part is present, pooled over its versions. It is not the effect of one edit, and a part on every run cannot be told apart from its harness. The cost ranges met their stated coverage in simulation. **The success ranges did not:** they pull effects toward 0, and their 80% ranges held 60% of nonzero effects. So they are marked `calibrated: false`, and so are the success-side numbers of a priced variant. With no record anywhere, every number is what it was before. The record, the digest, the factor map and the limits are in [`spec/harness.md`](spec/harness.md).
+An estimate is the change when a named part is present, pooled over its versions. It is not the effect of one edit, and a part on every run cannot be told apart from its harness. The cost ranges met their stated coverage in simulation. **The success ranges did not:** they pull effects toward 0, and their 80% ranges held 60% of nonzero effects. So they are marked `calibrated: false`, and so are the success-side numbers of a priced variant, and the harness-part estimates are experimental. With no record anywhere, every number is what it was before. The record, the digest, the factor map and the limits are in [`spec/harness.md`](spec/harness.md).
 
 ## Testing a harness change
 
 These commands are for changing the harness your agents run with and finding out whether the change paid off.
 
 - **Harness parts and `--harness`.** Record the tree each run used (`run finish --harness auto` or `PATH`), and the fit learns each named part's effect, as in the section above. `recommend --harness-variants` prices the trees your runs used on the configurations those runs used, and on the recommendation's own when their harness has data on the parts; `--harness PATH` prices one more tree. Where a tree is not priced, `not_priced` in `--json` says why. The record, the factor map and the limits are in [`spec/harness.md`](spec/harness.md).
-- **`adapt harness-runs` and `adapt harness2`.** These bring in runs another tool made. `loopmath adapt harness-runs FILE --out DIR` reads a `loopmath.harness-runs/0.1` file, one JSON line per rollout, as an auto-research loop, a plugin eval suite or a hand A/B writes it. `loopmath adapt harness2 RUNS --out DIR` reads a harness2 runs folder. Then `loopmath run import DIR --finish` stores the runs. The row format, outcomes, costs and worked examples are in [`spec/harness-runs.md`](spec/harness-runs.md).
+- **`adapt harness-runs` and `adapt harness2`.** These bring in runs another tool made; `adapt harness2` is experimental, since its input format is read from harness2's code and it has not yet read a real runs folder. `loopmath adapt harness-runs FILE --out DIR` reads a `loopmath.harness-runs/0.1` file, one JSON line per rollout, as an auto-research loop, a plugin eval suite or a hand A/B writes it. `loopmath adapt harness2 RUNS --out DIR` reads a harness2 runs folder. Then `loopmath run import DIR --finish` stores the runs. The row format, outcomes, costs and worked examples are in [`spec/harness-runs.md`](spec/harness-runs.md).
 - **`check-change`.** It decides whether a change beats what it replaces, on paired runs:
   - `check-change start --base LABEL|PATH --cand LABEL|PATH --n N` plans the pairs and each pair's arm order;
-  - `check-change status` gives the comparison, the verdict once there is one (adopt or reject) and the next pair worth running;
+  - `check-change status` gives the comparison, the verdict once there is one (adopt or reject) and the next pair worth running. A check that reaches its cap or spends its budget before the evidence decides keeps the base and says `not decided`. The next pair's value and price are shown at each look and stop nothing; `--value-stop` also stops a check, not decided, when the next pair is worth less than its price, from 4 scored pairs on (`--min-pairs K`); `--json` keeps `verdict: reject` there, with `comparison.stop` and `comparison.decided: false`;
   - `check-change from-runs --base-label SEL --cand-label SEL` compares finished runs already in the store, picked by a run label, a configuration id, a harness digest (a prefix of one digest will do) or `arm:NAME`.
 
   `--rule` names what counts as accepted, and `loopmath check-change --help` lists the rest. A run with no dollar cost leaves the decision to the outcomes alone, and the cost reads unknown; a budget or `--objective cpar` then refuses, naming the runs without one.
-- **`gate`.** For a loop that adopts changes on its own, it answers: adopt the candidate, reject it and keep the base, or replicate N more pairs first. `loopmath gate --base SEL --cand SEL` reads the finished runs in the store, or `--runs FILE` reads `loopmath.harness-runs/0.1` rows; an arm is a harness digest (`sha256:<hex>` or `digest:sha256:<hex>`, a prefix of one digest will do), a configuration id, or `arm=NAME` or `arm:NAME`; `check-change from-runs` takes the same forms. `--rule` takes the built-in rules or a rule defined under `[rules.NAME]` in the store's config, which the gate reads as `check-change` does, also with `--runs`. The comparison of the paired runs is `check-change`'s, and the gate adds the loop's policy to it: no adoption before `--r-min` pairs, looks at 1, 2, 4 and so on pairs up to `--r-max`, a `--floor` (the smallest gain worth adopting, 0 or more; under an acceptance rule it applies to the cut in cost per accepted result, a fraction, or to the gain in the chance of acceptance when a cost is unknown), and the dollars, `--budget-usd` for both arms (0 buys no further pair) and `--max-cost-ratio`. With no evidence, an arm that matches no run or a rule that scores no pair, it exits 1 and names the arms or the rules that are there. Both dollar flags need every run's cost and refuse, naming the runs without one; with neither flag, a run with no recorded cost leaves the decision to the outcomes alone, and the cost reads unknown, never $0. When nothing resolves within the cap or the budget, it keeps the base and says where it stopped. In Python, `loopmath.gate.decide(base_runs, cand_runs, GatePolicy(...))` gives the same answer and writes nothing; `loopmath gate --help` lists the rest.
+- **`gate` (experimental).** For a loop that adopts changes on its own, it answers: adopt the candidate, reject it and keep the base, or replicate N more pairs first. `loopmath gate --base SEL --cand SEL` reads the finished runs in the store, or `--runs FILE` reads `loopmath.harness-runs/0.1` rows; an arm is a harness digest (`sha256:<hex>` or `digest:sha256:<hex>`, a prefix of one digest will do), a configuration id, or `arm=NAME` or `arm:NAME`; `check-change from-runs` takes the same forms. `--rule` takes the built-in rules or a rule defined under `[rules.NAME]` in the store's config, which the gate reads as `check-change` does, also with `--runs`. The comparison of the paired runs is `check-change`'s, and the gate adds the loop's policy to it: no adoption before `--r-min` pairs, looks at 1, 2, 4 and so on pairs up to `--r-max`, a `--floor` (the smallest gain worth adopting, 0 or more; under an acceptance rule it applies to the cut in cost per accepted result, a fraction, or to the gain in the chance of acceptance when a cost is unknown), and the dollars, `--budget-usd` for both arms (0 buys no further pair) and `--max-cost-ratio`. With no evidence, an arm that matches no run or a rule that scores no pair, it exits 1 and names the arms or the rules that are there. Both dollar flags need every run's cost and refuse, naming the runs without one; with neither flag, a run with no recorded cost leaves the decision to the outcomes alone, and the cost reads unknown, never $0. When nothing resolves within the cap or the budget, it keeps the base and says where it stopped. In Python, `loopmath.gate.decide(base_runs, cand_runs, GatePolicy(...))` gives the same answer and writes nothing; `loopmath gate --help` lists the rest.
 
 ## The store and privacy
 
@@ -264,11 +267,7 @@ loopmath graph --workspace NAME --format html --out graph.html
 
 `loopmath prices` lists the packaged prices with the source of each. A rate marked "rate not confirmed" is a best public-price guess, and every dollar figure priced with one says so.
 
-`graph` rebuilds which agent launched which, and which session read what another wrote. Its formats are `ocp`, `json`, `dot`, `run` and `html`. `graph --out FILE` and `adapt NAME --out FILE` write to any path you name: missing folders are created, an existing file is replaced, and a directory is refused. `graph` prints a short summary on stderr; `--verbose` adds every count of what was skipped or could not be placed. See the [workflow graph guide](docs/graph.md) and [adapters](docs/adapters.md).
-
-## Research data
-
-`loopmath research --help` lists the verbs that read research data folders, which are not part of the package: `research fit` and `research transfer-test` read sweep run records, and `research analyze-e0` reads a session corpus. Name the folders with a flag (`--sweep-dir`, `--corpus`), an environment variable (`LOOPMATH_SWEEP_DIR`, `LOOPMATH_E0_CORPUS`), or config (`loopmath config set research.sweep_dir PATH`, `research.e0_corpus`). `research fit` and `research transfer-test` need the `bayes` extra (`pip install 'loopmath[bayes]'`), and `research analyze-e0` the `e0` extra. `loopmath prior build --out DIR` rebuilds the packaged prior bundle from research data folders like these; `loopmath prior build --help` names them.
+`graph` rebuilds which agent launched which, and which session read what another wrote. Its formats are `ocp`, `json`, `dot`, `run` and `html`. `graph --out FILE` and `adapt NAME --out FILE` write to any path you name: missing folders are created, an existing file is replaced, and a directory is refused. `graph` prints a short summary on stderr; `--verbose` adds every count of what was skipped or could not be placed. See the [workflow graph guide](docs/graph.md) and [adapters](docs/adapters.md). The ADE adapters (`adapt NAME`) are experimental: each is tested on a synthetic fixture written from its tool's format, not yet on a real store.
 
 ## More
 

{loopmath-0.3.0 → loopmath-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "loopmath"
-version = "0.3.0"
+version = "0.3.1"
 description = "Plan agent workflows, record how they went, and learn from your own Claude Code and Codex logs"
 readme = "README.md"
 license = "MIT"

{loopmath-0.3.0 → loopmath-0.3.1}/src/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.3.0"
+__version__ = "0.3.1"

{loopmath-0.3.0 → loopmath-0.3.1}/src/loopmath/cli.py

@@ -245,11 +245,8 @@ def _add_prices(sub) -> None:
 
 
 def _add_scan(sub) -> None:
-    p = sub.add_parser(
-        "scan",
-        help="explain the implicit scan used by graph and analyze",
-        description="Scanning is implicit in loopmath graph and loopmath analyze.",
-    )
+    # Hidden: no help= keeps it off `loopmath --help`, and HIDDEN keeps it off the usage line.
+    p = sub.add_parser("scan", description="Scanning is implicit in loopmath graph and loopmath analyze.")
     p.set_defaults(func=_cli_support.scan_verb)
 
 
@@ -328,7 +325,7 @@ def adapt_verb(args: argparse.Namespace) -> int:
         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"):
+    if not doc.get("nodes") and not doc.get("attempts") and not doc.get("events"):  # atrium emits events only
         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)
@@ -350,12 +347,16 @@ 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), or import runs",
+        "adapt", help="emit OCP v0.2 from an ADE store (experimental; loopmath ocp migrate converts it to v0.3), "
+                      "or import runs",
         description="Emit OCP v0.2 from an ADE store, or import rollouts as OCP v0.3 runs with a run importer: "
                     "`loopmath adapt harness2 RUNS --out DIR` reads a harness2 runs folder, and "
                     "`loopmath adapt harness-runs FILE --out DIR` reads a loopmath.harness-runs/0.1 file "
-                    "(spec/harness-runs.md). Then `loopmath run import DIR --finish` stores them.")
-    p.add_argument("name", metavar="NAME", help="registered adapter name, or a run importer: harness2, harness-runs")
+                    "(spec/harness-runs.md). Then `loopmath run import DIR --finish` stores them. "
+                    "Experimental: the ADE adapters and the harness2 importer, which are tested on synthetic "
+                    "fixtures written from each tool's format, not yet on real data.")
+    p.add_argument("name", metavar="NAME", help="registered adapter name (experimental), or a run importer: "
+                   "harness2 (experimental), harness-runs")
     p.add_argument("path", nargs="?", default=None, metavar="PATH",
                    help="the input: the same as --store PATH for an adapter; the runs folder (harness2) or rows file (harness-runs) for a run importer")
     p.add_argument("--out", default=None, help="write here instead of stdout (any path; missing folders are created; an existing file is replaced). Run importers: a folder, one <run id>.ocp.json per rollout")
@@ -429,9 +430,9 @@ def _add_validate_prices(sub) -> None:
 def _add_fit(sub) -> None:
     from .research_defaults import E1A_OBSERVE, SEED
 
+    # Hidden: no help= keeps it off `loopmath --help`, and HIDDEN keeps it off the usage line.
     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, "
@@ -463,21 +464,38 @@ def _add_fit(sub) -> None:
 
 def verify_receipts_verb(args: argparse.Namespace) -> int:
     """No ledger: check the store's receipts. A ledger path: verify that research receipt ledger."""
+    from .output import emit_json
+
+    schema = "loopmath.verify-receipts/1"
     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
+        lines = verify_lines(res)
+        code = 1 if res["failed"] else 0
+        if args.json:
+            emit_json(schema, {"ok": not code, **res, "message": "\n".join(lines), **({"exit": code} if code else {})})
+        else:
+            print("\n".join(lines))
+        return code
     from .receipts import ReceiptViolation, verify_receipts
 
     try:
         result = verify_receipts(args.ledger, args.frozen)
     except ReceiptViolation as exc:
-        print(f"FAIL: {exc}")
+        if args.json:
+            emit_json(schema, {"ok": False, "ledger_path": str(args.ledger), "message": f"FAIL: {exc}",
+                               "error": str(exc), "exit": 1})
+        else:
+            print(f"FAIL: {exc}")
         return 1
-    print(result.message())
+    if args.json:
+        emit_json(schema, {"ok": True, "ledger_path": str(args.ledger), "message": result.message(),
+                           "ledger": {"receipts": result.receipts, "task_arms": result.task_arms,
+                                      "spend_usd": float(result.spend_usd), "prereg": str(result.prereg)}})
+    else:
+        print(result.message())
     return 0
 
 
@@ -496,11 +514,17 @@ def _add_verify_receipts(sub) -> None:
         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.add_argument("--json", action="store_true", help="print one JSON object on stdout")
     p.set_defaults(func=verify_receipts_verb)
 
 
 def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(
+    from .cli_errors import JsonErrorParser, run_guarded, wants_json
+
+    raw_args = sys.argv[1:] if argv is None else argv
+    JsonErrorParser.json_mode = wants_json(raw_args)  # under --json a usage error is a JSON object on stdout too
+    JsonErrorParser.argv = list(raw_args)
+    parser = JsonErrorParser(
         prog="loopmath", description="loopmath: which agent workflow to run next, priced from your own logs"
     )
     parser.add_argument("--version", action="version", version=f"loopmath {__version__}")
@@ -537,7 +561,6 @@ def main(argv: list[str] | None = None) -> int:
 
     sub.metavar = _registry.command_metavar(sub)  # hidden commands stay callable, off the usage line
 
-    raw_args = sys.argv[1:] if argv is None else argv
     if raw_args and raw_args[0] == "view":
         parser.error(
             "loopmath view is unavailable; use 'loopmath graph --format dot' with "
@@ -550,6 +573,9 @@ def main(argv: list[str] | None = None) -> int:
     from .ingest.base import use_home
 
     use_home(getattr(args, "home", None))  # the caches follow --home as the store does
+    if getattr(args, "json", False) is True:
+        words = [args.command] + [str(v) for k, v in vars(args).items() if k.endswith("_command") and v]
+        return run_guarded(args.func, args, " ".join(words))
     return args.func(args)
 
 

loopmath-0.3.1/src/loopmath/cli_errors.py

@@ -0,0 +1,121 @@
+"""With `--json`, an error is one JSON object on stdout too.
+
+A command that fails under `--json` without printing anything on stdout gets one object there,
+`{"schema": "loopmath.error/1", "ok": false, "command": ..., "error": ..., "exit": ...}`, with the same
+exit code and the same message on stderr as before. That covers a usage error from the parser (exit 2),
+a handler that reports its error on stderr only, and an uncaught exception (the traceback still prints).
+A command that printed its own JSON error, as `run import`, `check-change` and `gate` do, is left alone.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any, Callable
+
+from .output import emit_json
+
+SCHEMA = "loopmath.error/1"
+_MAX_KEPT = 64_000  # characters of stderr kept for the message
+
+
+def wants_json(argv: list[str]) -> bool:
+    """`--json` among the options, before any `--`."""
+    for token in argv:
+        if token == "--":
+            return False
+        if token == "--json":
+            return True
+    return False
+
+
+def emit_error(command: str, message: str, code: int, hint: str | None = None) -> None:
+    emit_json(SCHEMA, {"ok": False, "command": command, "error": message, **({"hint": hint} if hint else {}),
+                       "exit": code})
+
+
+class JsonErrorParser(argparse.ArgumentParser):
+    """An ArgumentParser whose usage errors, under --json, also print one JSON object on stdout."""
+
+    json_mode = False  # set by cli.main for each command line
+    argv: list[str] = []
+
+    def error(self, message: str):  # type: ignore[override]
+        if JsonErrorParser.json_mode:
+            self.print_usage(sys.stderr)
+            print(f"{self.prog}: error: {message}", file=sys.stderr)
+            emit_error(_command(self.prog, JsonErrorParser.argv), message, 2)
+            sys.exit(2)
+        super().error(message)
+
+
+def _command(prog: str, argv: list[str]) -> str:
+    """The command a usage error belongs to: the parser's words after `loopmath`, else the first word given."""
+    words = prog.split()[1:]
+    if not words and argv and not argv[0].startswith("-"):
+        words = [argv[0]]
+    return " ".join(words) or "loopmath"
+
+
+class _Watch:
+    """A pass-through text stream that remembers whether anything was written, and keeps what was."""
+
+    def __init__(self, inner, keep: bool) -> None:
+        self._inner = inner
+        self._keep = keep
+        self.wrote = False
+        self.kept: list[str] = []
+        self._size = 0
+
+    def write(self, text: str) -> int:
+        if text:
+            self.wrote = True
+            if self._keep and self._size < _MAX_KEPT:
+                self.kept.append(text)
+                self._size += len(text)
+        return self._inner.write(text)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._inner, name)
+
+
+def _message(stderr_text: str, command: str, code: int) -> tuple[str, str | None]:
+    """The error lines on stderr (else its last line), and its `hint:` lines."""
+    lines = [line.strip() for line in stderr_text.splitlines() if line.strip()]
+    errors = [line.split("error: ", 1)[1] for line in lines if line.startswith("error: ") or ": error: " in line]
+    hints = [line[len("hint: "):] for line in lines if line.startswith("hint: ")]
+    hint = "; ".join(hints) or None
+    if errors:
+        return "; ".join(errors), hint
+    rest = [line for line in lines if not line.startswith("hint: ")]
+    if rest:
+        return rest[-1], hint
+    return f"loopmath {command} stopped with exit {code}", hint
+
+
+def run_guarded(func: Callable[[argparse.Namespace], int], args: argparse.Namespace, command: str) -> int:
+    """Run a handler under --json: when it fails and stdout stayed empty, print the error object there."""
+    out_watch, err_watch = _Watch(sys.stdout, keep=False), _Watch(sys.stderr, keep=True)
+    old_out, old_err = sys.stdout, sys.stderr
+    sys.stdout, sys.stderr = out_watch, err_watch
+    try:
+        code = func(args)
+    except SystemExit as exc:
+        sys.stdout, sys.stderr = old_out, old_err
+        code = exc.code if isinstance(exc.code, int) else (0 if exc.code is None else 1)
+        if code and not out_watch.wrote:
+            text = "".join(err_watch.kept) or (exc.code if isinstance(exc.code, str) else "")
+            message, hint = _message(text, command, code)
+            emit_error(command, message, code, hint)
+        raise
+    except Exception as exc:
+        sys.stdout, sys.stderr = old_out, old_err
+        if not out_watch.wrote:
+            emit_error(command, f"{type(exc).__name__}: {exc}", 1)
+        raise
+    finally:
+        sys.stdout, sys.stderr = old_out, old_err
+    if code and not out_watch.wrote:
+        message, hint = _message("".join(err_watch.kept), command, code)
+        emit_error(command, message, code, hint)
+    return code

{loopmath-0.3.0 → loopmath-0.3.1}/src/loopmath/cli_registry.py

@@ -66,7 +66,9 @@ def _check_args(p: argparse.ArgumentParser) -> None:
 
 
 def _add_compare(sub) -> None:
-    p = sub.add_parser("check-change", help="paired A/B check of a change: start, status, from-runs")
+    p = sub.add_parser("check-change", help="paired A/B check of a change: start, status, from-runs",
+                       description="A paired A/B check of a change. Start a check, record its pairs, and read its "
+                                   "comparison and verdict.")
     cs = p.add_subparsers(dest="check_command", required=True, metavar="{start,status,from-runs}")
 
     def decision(q: argparse.ArgumentParser) -> None:
@@ -85,6 +87,11 @@ def _add_compare(sub) -> None:
                        "long-lived change)")
         q.add_argument("--value-usd", type=float, default=None, metavar="USD", help="dollars per point of gain "
                        "(default: the base's cost per accepted result)")
+        q.add_argument("--value-stop", action="store_true", default=None, help="stop the check, keeping the base, "
+                       "when the next pair is worth less than its price (by default the value and the price are "
+                       "shown at each look and the check goes on to a decision, its cap or its budget)")
+        q.add_argument("--min-pairs", type=int, default=None, metavar="K", help="with --value-stop, the scored "
+                       "pairs before the value may stop the check (default 4; 1 stops from the first pair)")
 
     q = cs.add_parser("start", help="start a check: its pairs, each pair's arm order, and the next pair to run")
     q.add_argument("--base", required=True, metavar="LABEL|PATH", help="the base arm: a label, or its harness tree")
@@ -186,10 +193,10 @@ def _add_planning(sub) -> None:
     p.add_argument("--brief", action="store_true", help="with --json: a short object for agents (task, reference, "
                    "goal, rescue, choices, message, rec, and page with --html); the stored recommendation keeps everything")
     p.add_argument("--harness-variants", nargs="?", const=5, type=int, default=None, metavar="N",
-                   help="also price the N harness trees recorded on your runs that the fit saw most (default 5), for the "
-                   "default pick and the goal, against the bare harness label on the same draws")
-    p.add_argument("--harness", default=None, metavar="PATH|auto", help="also price this harness tree as the first "
-                   "variant (auto: the git working tree of this folder), even when no run recorded it")
+                   help="experimental: also price the N harness trees recorded on your runs that the fit saw most "
+                   "(default 5), for the default pick and the goal, against the bare harness label on the same draws")
+    p.add_argument("--harness", default=None, metavar="PATH|auto", help="experimental: also price this harness tree "
+                   "as the first variant (auto: the git working tree of this folder), even when no run recorded it")
     _common(p, html=True)
     p.set_defaults(func=_lazy("loopmath.recommend.commands:recommend"))
 
@@ -445,9 +452,11 @@ def _add_learning(sub) -> None:
     _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, 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")
+    p = sub.add_parser("prior", help="the shipped prior bundle: show, import-shared, remove-shared")
+    ps = p.add_subparsers(dest="prior_command", required=True, metavar="{show,import-shared,remove-shared}")
+    # Hidden, as `plan` is: no help= keeps `build` out of `loopmath prior --help`; it stays callable by name.
+    q = ps.add_parser("build", description="Rebuild the packaged prior bundle from the sweep, E0 and RQ1 inputs. "
+                                           "It needs research data folders that do not ship with the package.")
     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)")
@@ -483,7 +492,7 @@ def _add_viewing(sub) -> None:
 
     p = sub.add_parser("posterior", help="current estimates by level and by workflow graph")
     p.add_argument("--level", default="all",
-                   choices=["model", "effort", "role", "topology", "type", "repo", "feature", "harness", "all"], help="which level of estimates (default all; harness: the harness labels and their parts)")
+                   choices=["model", "effort", "role", "topology", "type", "repo", "feature", "harness", "all"], help="which level of estimates (default all; harness: the harness labels and their parts, experimental)")
     p.add_argument("--head", default=None, metavar="cost|tokens|success|gate|score:NAME", help="which quantity to show")
     p.add_argument("--target", default=None, metavar="NAME>=X", help="score target for the chance to reach and the cost per accepted result, as for recommend (default: the latest recommendation's target for this type and repo)")
     p.add_argument("--workflow", default=None, metavar="CFG|FILE.toml", help="also draw this configuration with each piece's estimate: a cfg_ id from loopmath recommend --json or your runs, or FILE.toml with settings")
@@ -546,7 +555,7 @@ def _add_viewing(sub) -> None:
     q.set_defaults(func=_lazy("loopmath.ocp.commands:migrate"))
 
 
-HIDDEN = frozenset({"plan", "analyze-e0"})  # callable, but not listed by `loopmath --help`
+HIDDEN = frozenset({"plan", "analyze-e0", "scan", "research"})  # callable, but not listed by `loopmath --help`
 
 
 def command_metavar(sub) -> str:
@@ -555,7 +564,9 @@ def command_metavar(sub) -> str:
 
 
 def _add_gate(sub) -> None:
-    p = sub.add_parser("gate", help="adopt or reject a harness change: compare base and candidate runs")
+    p = sub.add_parser("gate", help="experimental: adopt or reject a harness change: compare base and candidate runs",
+                       description="Experimental: adopt or reject a harness change, comparing base and candidate "
+                                   "runs, for a loop that adopts changes on its own.")
     p.add_argument("--base", required=True, metavar="SEL",
                    help="the base arm: digest:sha256:<hex> or sha256:<hex> (the harness record's digest; a prefix of "
                         "one digest will do), a cfg_ configuration id, or arm:<name> or arm=<name>")