loopmath 0.2.3__tar.gz → 0.2.4__tar.gz

{loopmath-0.2.3/src/loopmath.egg-info → loopmath-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loopmath
-Version: 0.2.3
+Version: 0.2.4
 Summary: Plan agent workflows, record how they went, and learn from your own Claude Code and Codex logs
 Author: QKV Labs
 License-Expression: MIT
@@ -42,7 +42,7 @@ loopmath helps an orchestrator agent choose how to run a coding task, and learns
 
 Before a task, it predicts how the user's usual agent workflow will do: the chance of an accepted result, and the cost in tokens and dollars. It shows the other workflows on a success-cost curve and offers two exploration picks. Each pick comes with its gain on every future similar run, its one-time price, and the number of runs it takes to pay back. After the task, the orchestrator records what ran and what came of it. loopmath fills in the token costs from the Claude Code and Codex logs, writes a receipt of predicted against actual, and refits.
 
-loopmath never starts or coordinates agents. Claude Code, Codex, herdr or your own tool does that; loopmath is a CLI they call. Everything runs locally. No command opens a network connection, the logs are opened read only, and loopmath writes only to its store (`~/.loopmath`) and to paths you name.
+loopmath never starts or coordinates agents. Claude Code, Codex, herdr or your own tool does that; loopmath is a CLI they call. Everything runs locally. loopmath connects to no other machine: `loopmath builder` serves its page on 127.0.0.1 only, and no other command opens a network connection. The logs are opened read only, and loopmath writes only to its store (`~/.loopmath`, which holds its caches too), to the skill folders `skill install` names, and to paths you name.
 
 The package installs two commands: `loopmath` and its short alias `loop`. If another `loop` is already on your PATH, use `loopmath`.
 
@@ -65,12 +65,13 @@ python3 -m venv .venv
 ## First run
 
 ```sh
-loopmath skill install      # teach your coding agents how to use loopmath
+loopmath skill install --dry-run   # every file it would write, and where; writes nothing
+loopmath skill install             # teach your coding agents how to use loopmath
 ```
 
 Then ask your agent to onboard, for example "onboard loopmath". The agent runs a dry run, asks you one question (which model labels your sessions, with the cost of each option), onboards, fits, and opens the results page.
 
-`skill install` writes six skills, one per job, and a shared `reference.md` with every command and JSON field they use. An agent loads only the skill for the job at hand, and each phrase belongs to one skill:
+`skill install` writes six skills, one per job. Each skill's folder also gets its own copy of the shared `reference.md`, with every command and JSON field the skills use, so each skill works on its own. An agent loads only the skill for the job at hand, and each phrase belongs to one skill:
 
 | Skill | Ask your agent |
 |---|---|
@@ -83,7 +84,7 @@ Then ask your agent to onboard, for example "onboard loopmath". The agent runs a
 
 By default the skills go to every agent whose home exists: Claude Code (`~/.claude/skills/<name>/`, or under `$CLAUDE_CONFIG_DIR`) and Codex (`~/.codex/skills/<name>/`, or under `$CODEX_HOME`). `--target claude-code`, `codex` or `both` picks them yourself. If your Codex has no skills folder, the files go to `~/.codex/loopmath/<name>/` instead, with a short marked block in `~/.codex/AGENTS.md` that lists them. Add `--scope project` to install into the current repository (or `--dir PATH` for another one).
 
-It is safe to run again. It records the files it wrote, with their hashes, in `.loopmath-skills.json` beside the skill folders, and it replaces or removes only those. A skill file you changed is kept, with a note. Any other file where a skill goes stops the install before it writes anything, and names the path to move aside. The single skill that 0.1 installed is replaced when it is as 0.1 wrote it. `loopmath skill show NAME` prints one skill, and `loopmath skill uninstall` removes the files it wrote. `loopmath doctor` shows what loopmath can see: logs, agents, store, fit, prices and skills.
+It is safe to run again. It records the files it wrote, with their hashes, in `.loopmath-skills.json` beside the skill folders, and it replaces or removes only those. A skill file you changed is kept, with a note. Any other file where a skill goes stops the install before it writes anything, and names the path to move aside. The single skill that 0.1 installed is replaced when it is as 0.1 wrote it. `loopmath skill show NAME` prints one skill, and `loopmath skill uninstall` removes the files it wrote. `loopmath doctor` shows what loopmath can see: logs, agents, store, fit, prices and skills. To read the logs it builds the log parse cache in the store and keeps it, so the next read is fast, and it says how big the cache is; it changes nothing else in the store.
 
 To onboard by hand instead:
 
@@ -92,7 +93,9 @@ loopmath onboard --dry-run                                  # what it found, and
 loopmath onboard --labeler claude:claude-haiku-4-5 --yes    # record it and run a first fit
 ```
 
-`onboard` reads your recent Claude Code and Codex sessions (the last 90 days unless you pass `--since`). It groups them into runs, labels each group's task type with a model you choose, names your usual workflow per task type and repository, and fits. loopmath never picks the labelling model for you. `--labeler` takes one of:
+The dry run makes no labelling call and writes no runs or fit; like `doctor`, it keeps the log parse cache in the store and says how big it is. The first read of a long history takes several minutes; with the cache, the next one is quick.
+
+`onboard` reads your recent Claude Code and Codex sessions (the last 90 days unless you pass `--since`). It groups them into runs, labels each group's task type with a model you choose, names your usual workflow per task type and repository (sessions outside a git repository go under `(no repo)`), and fits. loopmath never picks the labelling model for you. `--labeler` takes one of:
 
 - `claude:<model>`, through your `claude` CLI;
 - `codex:<model>`, through your `codex` CLI;
@@ -115,6 +118,8 @@ loopmath run start --rec REC --choice goal --base-commit SHA --json      # the h
 loopmath run record --run RUN --session UUID --verified tests=pass --json  # costs from the logs, the outcome, the receipt
 ```
 
+With `--run`, a session that started before the run counts from the run's start (a Codex session counts whole). Give `--since TS` and `--until TS` when the task's work began or ended at another time; `--since` before `run start` moves the run's start back. When no commit is found after the base commit, the record says where it looked; pass `--commit SHA`. `loopmath run sessions` lists the recent Claude Code and Codex sessions in this folder with their ids, for `--session ID`. Outside a Claude Code tool shell, `--session self` uses the one Claude Code session in this folder active in the last 10 minutes.
+
 The same loop step by step, for a tool of your own:
 
 ```sh
@@ -142,37 +147,41 @@ loopmath run finish --run RUN
 loopmath outcome --commit SHA --signal incident=INC-42 --kind event --source tracker
 ```
 
-A pair runs the goal workflow and an exploration pick from the same base commit, in separate worktrees. Save the recommendation (`recommend ... --json > rec.json`) and start both runs from it with `run start --task-file rec.json`, so they share one task: the first with `--new-slate`, the second with `--slate SLT`. A blinded referee then picks the better change, which you record with `loopmath outcome --slate SLT --prefer RUN --judge referee --blinded`.
+The usual workflow is the one most of your habit runs used: the runs onboard brought in, and runs started with `--source habit`. Runs of a recommended alternative or an exploration pick are recorded but never make a workflow your usual; `recommend --usual CFG` names one. Under the reference, `recommend` says where it comes from; each alternative shows its own chance and costs and what it changes from the pick, and an exploration pick says after how many similar runs it pays back. When the text would run past 25 lines it lists fewer alternatives and says how many more `recommend --json` has.
+
+A pair runs the goal workflow and an exploration pick from the same base commit, in separate worktrees. `loopmath run start --rec REC --choice pair` starts both, on a new slate. To start them one at a time, save the recommendation (`recommend ... --json > rec.json`) and start each run from it, so they share one task: `loopmath run start --task-file rec.json --config CFG --source alternative --new-slate` for the goal, then the same with the pick's configuration, `--source exploration` and `--slate SLT`. A blinded referee then picks the better change, which you record with `loopmath outcome --slate SLT --prefer RUN --judge referee --blinded`. `loopmath runs --slate SLT` says which run the referee preferred.
 
-A run counts as a success when it is accepted under your rule. By default that means the task's tests pass. A rule can also be a score target: `loopmath recommend ... --target 'heldout_perf>=2400'` or `--target 'runtime_s<=200'` gives the expected score and the chance of reaching the target. Set standing rules and other options with `loopmath config set KEY VALUE`, and the spending cap with `loopmath budget --usd X --period month`.
+A run counts as a success when it is accepted under your rule. By default that means the task's tests pass. A rule can also be a score target: `loopmath recommend ... --target 'heldout_perf>=2400'` or `--target 'runtime_s<=200'` gives the expected score and the chance of reaching the target. Set standing rules and other options with `loopmath config set KEY VALUE` (`loopmath config get` lists every key, set or not, and `config set` refuses a key loopmath does not read), and the spending cap with `loopmath budget --usd X --period month`. Spend counts your runs and onboard's labelling calls; runs onboard brought in from your logs are shown apart and not counted. A run you record with `--source habit` counts.
 
-Runs recorded by another tool that writes OCP v0.3, such as an experiment runner, come in with `loopmath run import DIR --finish`: several files or a directory, with one refit at the end (`--no-fit` skips it). Runs in your store always count as yours, whatever source their documents name. `loopmath fit --without SOURCE` leaves out one shipped prior source, and `loopmath status` names the options of the current fit.
+Runs recorded by another tool that writes OCP v0.3, such as an experiment runner, come in with `loopmath run import DIR --finish`: several files or a directory, with one refit at the end (`--no-fit` skips it). It says how many runs were new and how many were already in the store; importing finished runs into a store with no fit starts a fit. Runs in your store always count as yours, whatever source their documents name. `loopmath fit --without SOURCE` leaves out one shipped prior source, and `loopmath status` names the options of the current fit.
 
 ## The three views
 
-Each view is a self-contained HTML file written by a command; there is no server. The same numbers are available with `--json`.
+Each view is a self-contained HTML file written by a command; opening one needs no server. The same numbers are available with `--json`.
 
 - **Previous runs:** `loopmath runs --html`. Every recorded run with its workflow graph, costs, signals and receipt.
 - **Plans for a task:** `loopmath recommend ... --html`. The candidates on a success-cost chart. Click one to see its workflow graph with per-piece predictions.
-- **Current estimates:** `loopmath posterior --html`. What loopmath believes at each level (model, effort, role, topology, task type, repository, feature), each with a range. Add `--workflow CFG` (a configuration id from `loopmath recommend` or your runs) to see the estimate for each piece of one workflow.
+- **Current estimates:** `loopmath posterior --html`. What loopmath believes at each level (model, effort, role, topology, task type, repository, feature), each with a range. Add `--workflow CFG` (a configuration id from `loopmath recommend` or your runs) to see the estimate for each piece of one workflow, on the task its runs were for, or, if it never ran, the task it was recommended for; `--type` and `--repo` pick another.
 
 Without a path, `--html` writes the page under `~/.loopmath/views/` and prints where it went.
 
+The workflow builder is the one page that is served: `loopmath builder --type bug_fix --repo acme/api` serves it on 127.0.0.1 and opens it in your browser (`--no-open` prints the address instead); Ctrl+C stops it. Pick a shape, change models, efforts, widths and pieces, and see the estimated numbers for the task, the same ones `recommend` gives.
+
 ## Commands
 
 | Group | Commands |
 |---|---|
-| Plan | `task-types`, `workflows` (list, show, validate, diff), `recommend` |
-| Record | `run` (start, attempt, artifact, finish, import), `outcome`, `budget`, `config` (get, set) |
+| Plan | `task-types`, `workflows` (list, show, validate, diff), `recommend`, `builder` |
+| 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` |
+| View | `runs`, `posterior`, `status`, `report`, `doctor`, `verify-receipts` |
 | Skill | `skill` (install, uninstall, show) |
 | OCP | `ocp` (validate, migrate) |
-| Log analysis | `analyze`, `graph`, `adapt`, `prices`, `validate-prices`, `scan`, `verify-receipts` |
+| Log analysis | `analyze`, `graph`, `adapt`, `prices`, `validate-prices`, `scan` |
 
-Each command prints a short summary by default. With `--json`, it prints exactly one JSON object instead. 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.
+Each command prints a short summary by default. With `--json`, it prints exactly one JSON object instead. 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`.
 
-A workflow is a TOML file. `loopmath workflows list` shows the catalog and yours, which live in `~/.loopmath/workflows/`. This one implements, then sends a rejected change back once or twice:
+A workflow is a TOML file. `loopmath workflows list` shows the catalog and yours, which live in `~/.loopmath/workflows/`. It also lists the shapes loopmath composes from catalog pieces, such as `team`; `loopmath workflows show team` says what one is and that `recommend` does not offer it. This one implements, then sends a rejected change back once or twice:
 
 ```toml
 id = "implement_review_mine"
@@ -222,7 +231,7 @@ model = "gpt-5.6-sol"
 effort = "high"
 ```
 
-Check it with `loopmath workflows validate FILE`, compare it with `loopmath workflows diff implement_review FILE`, and pass it to `recommend --workflow FILE` to have it considered, or to `run start --workflow FILE` to record a run with its settings (`--set PIECE=HARNESS:MODEL:EFFORT` overrides a piece).
+Check it with `loopmath workflows validate FILE`, compare it with `loopmath workflows diff implement_review FILE`, and pass it to `recommend --workflow FILE` to have it considered, or to `run start --workflow FILE --source user_edit` to record a run with its settings (`--set PIECE=HARNESS:MODEL:EFFORT` overrides a piece).
 
 ## The store and privacy
 
@@ -232,13 +241,15 @@ The store is `~/.loopmath`. Set `LOOPMATH_HOME` or pass `--home` to put it elsew
 - signals, receipts and fits;
 - your config and your workflows;
 - the views you write;
-- the log parse cache.
+- the caches: the log parse cache, and the folder where `fit --full` compiles its model (when that compile fails, it also leaves the C code it tried in the system temp folder and prints where).
 
-Do not edit the store by hand; use the commands.
+Do not edit the store by hand; use the commands. `loopmath verify-receipts` checks the receipts in your store; give a file to verify a research receipt ledger instead.
 
 Run files use the `metadata_only` privacy profile. They keep structure, models, tokens, dollars, paths and verdicts, but not transcript text.
 
-`loopmath share --out FILE` writes a reduced copy you can send to us. It keeps task types, workflows, models, tokens, dollars and outcomes. Repository names are hashed. Titles, paths, commands, session ids and commit shas are removed. `loopmath share --preview` prints exactly what would leave.
+`loopmath share --out FILE` writes a reduced copy you can send to us. It keeps task types, workflows, models, tokens, dollars and outcomes. Repository names are hashed. Titles, paths, commands, session ids and commit shas are removed. `loopmath share --preview` prints exactly what would leave. `--out FILE.json` writes plain JSON you can read; any other name, such as `share.json.gz`, writes gzip.
+
+`loopmath prior import-shared FILE` adds a file another organization shared with you to your priors (either format; not one this store shared itself), and `loopmath prior remove-shared ORG` takes it out again; run `loopmath fit` after either.
 
 ## Analyzing logs without recording
 
@@ -249,13 +260,15 @@ loopmath analyze                 # cost per accepted run from the last 14 days o
 loopmath graph --workspace NAME --format html --out graph.html
 ```
 
-`analyze` reads `~/.claude/projects` and `~/.codex/sessions`. It grades the outcome evidence it finds, prices known models, and prints cost per accepted run with an 80% band. It also lists what it could not use and why.
+`analyze` reads `~/.claude/projects` and `~/.codex/sessions`. It grades the outcome evidence it finds, prices known models, and prints cost per accepted run with an 80% band. It also lists what it could not use and why; when no workflow configuration has enough runs to compare, it says how many runs it read and what kept each out, and what to try (`--min-n`, `--grading`). `loopmath analyze --json` prints the same as one JSON object, and `--home PATH` keeps its parse cache in that store.
+
+`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`. See the [workflow graph guide](docs/graph.md) and [adapters](docs/adapters.md).
+`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 fit|transfer-test` and `loopmath analyze-e0` read data folders that are not part of the package. Name them 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`). The research verbs need the `bayes` extra (`pip install 'loopmath[bayes]'`).
+`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.
 
 ## More
 

{loopmath-0.2.3 → loopmath-0.2.4}/README.md

@@ -4,7 +4,7 @@ loopmath helps an orchestrator agent choose how to run a coding task, and learns
 
 Before a task, it predicts how the user's usual agent workflow will do: the chance of an accepted result, and the cost in tokens and dollars. It shows the other workflows on a success-cost curve and offers two exploration picks. Each pick comes with its gain on every future similar run, its one-time price, and the number of runs it takes to pay back. After the task, the orchestrator records what ran and what came of it. loopmath fills in the token costs from the Claude Code and Codex logs, writes a receipt of predicted against actual, and refits.
 
-loopmath never starts or coordinates agents. Claude Code, Codex, herdr or your own tool does that; loopmath is a CLI they call. Everything runs locally. No command opens a network connection, the logs are opened read only, and loopmath writes only to its store (`~/.loopmath`) and to paths you name.
+loopmath never starts or coordinates agents. Claude Code, Codex, herdr or your own tool does that; loopmath is a CLI they call. Everything runs locally. loopmath connects to no other machine: `loopmath builder` serves its page on 127.0.0.1 only, and no other command opens a network connection. The logs are opened read only, and loopmath writes only to its store (`~/.loopmath`, which holds its caches too), to the skill folders `skill install` names, and to paths you name.
 
 The package installs two commands: `loopmath` and its short alias `loop`. If another `loop` is already on your PATH, use `loopmath`.
 
@@ -27,12 +27,13 @@ python3 -m venv .venv
 ## First run
 
 ```sh
-loopmath skill install      # teach your coding agents how to use loopmath
+loopmath skill install --dry-run   # every file it would write, and where; writes nothing
+loopmath skill install             # teach your coding agents how to use loopmath
 ```
 
 Then ask your agent to onboard, for example "onboard loopmath". The agent runs a dry run, asks you one question (which model labels your sessions, with the cost of each option), onboards, fits, and opens the results page.
 
-`skill install` writes six skills, one per job, and a shared `reference.md` with every command and JSON field they use. An agent loads only the skill for the job at hand, and each phrase belongs to one skill:
+`skill install` writes six skills, one per job. Each skill's folder also gets its own copy of the shared `reference.md`, with every command and JSON field the skills use, so each skill works on its own. An agent loads only the skill for the job at hand, and each phrase belongs to one skill:
 
 | Skill | Ask your agent |
 |---|---|
@@ -45,7 +46,7 @@ Then ask your agent to onboard, for example "onboard loopmath". The agent runs a
 
 By default the skills go to every agent whose home exists: Claude Code (`~/.claude/skills/<name>/`, or under `$CLAUDE_CONFIG_DIR`) and Codex (`~/.codex/skills/<name>/`, or under `$CODEX_HOME`). `--target claude-code`, `codex` or `both` picks them yourself. If your Codex has no skills folder, the files go to `~/.codex/loopmath/<name>/` instead, with a short marked block in `~/.codex/AGENTS.md` that lists them. Add `--scope project` to install into the current repository (or `--dir PATH` for another one).
 
-It is safe to run again. It records the files it wrote, with their hashes, in `.loopmath-skills.json` beside the skill folders, and it replaces or removes only those. A skill file you changed is kept, with a note. Any other file where a skill goes stops the install before it writes anything, and names the path to move aside. The single skill that 0.1 installed is replaced when it is as 0.1 wrote it. `loopmath skill show NAME` prints one skill, and `loopmath skill uninstall` removes the files it wrote. `loopmath doctor` shows what loopmath can see: logs, agents, store, fit, prices and skills.
+It is safe to run again. It records the files it wrote, with their hashes, in `.loopmath-skills.json` beside the skill folders, and it replaces or removes only those. A skill file you changed is kept, with a note. Any other file where a skill goes stops the install before it writes anything, and names the path to move aside. The single skill that 0.1 installed is replaced when it is as 0.1 wrote it. `loopmath skill show NAME` prints one skill, and `loopmath skill uninstall` removes the files it wrote. `loopmath doctor` shows what loopmath can see: logs, agents, store, fit, prices and skills. To read the logs it builds the log parse cache in the store and keeps it, so the next read is fast, and it says how big the cache is; it changes nothing else in the store.
 
 To onboard by hand instead:
 
@@ -54,7 +55,9 @@ loopmath onboard --dry-run                                  # what it found, and
 loopmath onboard --labeler claude:claude-haiku-4-5 --yes    # record it and run a first fit
 ```
 
-`onboard` reads your recent Claude Code and Codex sessions (the last 90 days unless you pass `--since`). It groups them into runs, labels each group's task type with a model you choose, names your usual workflow per task type and repository, and fits. loopmath never picks the labelling model for you. `--labeler` takes one of:
+The dry run makes no labelling call and writes no runs or fit; like `doctor`, it keeps the log parse cache in the store and says how big it is. The first read of a long history takes several minutes; with the cache, the next one is quick.
+
+`onboard` reads your recent Claude Code and Codex sessions (the last 90 days unless you pass `--since`). It groups them into runs, labels each group's task type with a model you choose, names your usual workflow per task type and repository (sessions outside a git repository go under `(no repo)`), and fits. loopmath never picks the labelling model for you. `--labeler` takes one of:
 
 - `claude:<model>`, through your `claude` CLI;
 - `codex:<model>`, through your `codex` CLI;
@@ -77,6 +80,8 @@ loopmath run start --rec REC --choice goal --base-commit SHA --json      # the h
 loopmath run record --run RUN --session UUID --verified tests=pass --json  # costs from the logs, the outcome, the receipt
 ```
 
+With `--run`, a session that started before the run counts from the run's start (a Codex session counts whole). Give `--since TS` and `--until TS` when the task's work began or ended at another time; `--since` before `run start` moves the run's start back. When no commit is found after the base commit, the record says where it looked; pass `--commit SHA`. `loopmath run sessions` lists the recent Claude Code and Codex sessions in this folder with their ids, for `--session ID`. Outside a Claude Code tool shell, `--session self` uses the one Claude Code session in this folder active in the last 10 minutes.
+
 The same loop step by step, for a tool of your own:
 
 ```sh
@@ -104,37 +109,41 @@ loopmath run finish --run RUN
 loopmath outcome --commit SHA --signal incident=INC-42 --kind event --source tracker
 ```
 
-A pair runs the goal workflow and an exploration pick from the same base commit, in separate worktrees. Save the recommendation (`recommend ... --json > rec.json`) and start both runs from it with `run start --task-file rec.json`, so they share one task: the first with `--new-slate`, the second with `--slate SLT`. A blinded referee then picks the better change, which you record with `loopmath outcome --slate SLT --prefer RUN --judge referee --blinded`.
+The usual workflow is the one most of your habit runs used: the runs onboard brought in, and runs started with `--source habit`. Runs of a recommended alternative or an exploration pick are recorded but never make a workflow your usual; `recommend --usual CFG` names one. Under the reference, `recommend` says where it comes from; each alternative shows its own chance and costs and what it changes from the pick, and an exploration pick says after how many similar runs it pays back. When the text would run past 25 lines it lists fewer alternatives and says how many more `recommend --json` has.
+
+A pair runs the goal workflow and an exploration pick from the same base commit, in separate worktrees. `loopmath run start --rec REC --choice pair` starts both, on a new slate. To start them one at a time, save the recommendation (`recommend ... --json > rec.json`) and start each run from it, so they share one task: `loopmath run start --task-file rec.json --config CFG --source alternative --new-slate` for the goal, then the same with the pick's configuration, `--source exploration` and `--slate SLT`. A blinded referee then picks the better change, which you record with `loopmath outcome --slate SLT --prefer RUN --judge referee --blinded`. `loopmath runs --slate SLT` says which run the referee preferred.
 
-A run counts as a success when it is accepted under your rule. By default that means the task's tests pass. A rule can also be a score target: `loopmath recommend ... --target 'heldout_perf>=2400'` or `--target 'runtime_s<=200'` gives the expected score and the chance of reaching the target. Set standing rules and other options with `loopmath config set KEY VALUE`, and the spending cap with `loopmath budget --usd X --period month`.
+A run counts as a success when it is accepted under your rule. By default that means the task's tests pass. A rule can also be a score target: `loopmath recommend ... --target 'heldout_perf>=2400'` or `--target 'runtime_s<=200'` gives the expected score and the chance of reaching the target. Set standing rules and other options with `loopmath config set KEY VALUE` (`loopmath config get` lists every key, set or not, and `config set` refuses a key loopmath does not read), and the spending cap with `loopmath budget --usd X --period month`. Spend counts your runs and onboard's labelling calls; runs onboard brought in from your logs are shown apart and not counted. A run you record with `--source habit` counts.
 
-Runs recorded by another tool that writes OCP v0.3, such as an experiment runner, come in with `loopmath run import DIR --finish`: several files or a directory, with one refit at the end (`--no-fit` skips it). Runs in your store always count as yours, whatever source their documents name. `loopmath fit --without SOURCE` leaves out one shipped prior source, and `loopmath status` names the options of the current fit.
+Runs recorded by another tool that writes OCP v0.3, such as an experiment runner, come in with `loopmath run import DIR --finish`: several files or a directory, with one refit at the end (`--no-fit` skips it). It says how many runs were new and how many were already in the store; importing finished runs into a store with no fit starts a fit. Runs in your store always count as yours, whatever source their documents name. `loopmath fit --without SOURCE` leaves out one shipped prior source, and `loopmath status` names the options of the current fit.
 
 ## The three views
 
-Each view is a self-contained HTML file written by a command; there is no server. The same numbers are available with `--json`.
+Each view is a self-contained HTML file written by a command; opening one needs no server. The same numbers are available with `--json`.
 
 - **Previous runs:** `loopmath runs --html`. Every recorded run with its workflow graph, costs, signals and receipt.
 - **Plans for a task:** `loopmath recommend ... --html`. The candidates on a success-cost chart. Click one to see its workflow graph with per-piece predictions.
-- **Current estimates:** `loopmath posterior --html`. What loopmath believes at each level (model, effort, role, topology, task type, repository, feature), each with a range. Add `--workflow CFG` (a configuration id from `loopmath recommend` or your runs) to see the estimate for each piece of one workflow.
+- **Current estimates:** `loopmath posterior --html`. What loopmath believes at each level (model, effort, role, topology, task type, repository, feature), each with a range. Add `--workflow CFG` (a configuration id from `loopmath recommend` or your runs) to see the estimate for each piece of one workflow, on the task its runs were for, or, if it never ran, the task it was recommended for; `--type` and `--repo` pick another.
 
 Without a path, `--html` writes the page under `~/.loopmath/views/` and prints where it went.
 
+The workflow builder is the one page that is served: `loopmath builder --type bug_fix --repo acme/api` serves it on 127.0.0.1 and opens it in your browser (`--no-open` prints the address instead); Ctrl+C stops it. Pick a shape, change models, efforts, widths and pieces, and see the estimated numbers for the task, the same ones `recommend` gives.
+
 ## Commands
 
 | Group | Commands |
 |---|---|
-| Plan | `task-types`, `workflows` (list, show, validate, diff), `recommend` |
-| Record | `run` (start, attempt, artifact, finish, import), `outcome`, `budget`, `config` (get, set) |
+| Plan | `task-types`, `workflows` (list, show, validate, diff), `recommend`, `builder` |
+| 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` |
+| View | `runs`, `posterior`, `status`, `report`, `doctor`, `verify-receipts` |
 | Skill | `skill` (install, uninstall, show) |
 | OCP | `ocp` (validate, migrate) |
-| Log analysis | `analyze`, `graph`, `adapt`, `prices`, `validate-prices`, `scan`, `verify-receipts` |
+| Log analysis | `analyze`, `graph`, `adapt`, `prices`, `validate-prices`, `scan` |
 
-Each command prints a short summary by default. With `--json`, it prints exactly one JSON object instead. 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.
+Each command prints a short summary by default. With `--json`, it prints exactly one JSON object instead. 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`.
 
-A workflow is a TOML file. `loopmath workflows list` shows the catalog and yours, which live in `~/.loopmath/workflows/`. This one implements, then sends a rejected change back once or twice:
+A workflow is a TOML file. `loopmath workflows list` shows the catalog and yours, which live in `~/.loopmath/workflows/`. It also lists the shapes loopmath composes from catalog pieces, such as `team`; `loopmath workflows show team` says what one is and that `recommend` does not offer it. This one implements, then sends a rejected change back once or twice:
 
 ```toml
 id = "implement_review_mine"
@@ -184,7 +193,7 @@ model = "gpt-5.6-sol"
 effort = "high"
 ```
 
-Check it with `loopmath workflows validate FILE`, compare it with `loopmath workflows diff implement_review FILE`, and pass it to `recommend --workflow FILE` to have it considered, or to `run start --workflow FILE` to record a run with its settings (`--set PIECE=HARNESS:MODEL:EFFORT` overrides a piece).
+Check it with `loopmath workflows validate FILE`, compare it with `loopmath workflows diff implement_review FILE`, and pass it to `recommend --workflow FILE` to have it considered, or to `run start --workflow FILE --source user_edit` to record a run with its settings (`--set PIECE=HARNESS:MODEL:EFFORT` overrides a piece).
 
 ## The store and privacy
 
@@ -194,13 +203,15 @@ The store is `~/.loopmath`. Set `LOOPMATH_HOME` or pass `--home` to put it elsew
 - signals, receipts and fits;
 - your config and your workflows;
 - the views you write;
-- the log parse cache.
+- the caches: the log parse cache, and the folder where `fit --full` compiles its model (when that compile fails, it also leaves the C code it tried in the system temp folder and prints where).
 
-Do not edit the store by hand; use the commands.
+Do not edit the store by hand; use the commands. `loopmath verify-receipts` checks the receipts in your store; give a file to verify a research receipt ledger instead.
 
 Run files use the `metadata_only` privacy profile. They keep structure, models, tokens, dollars, paths and verdicts, but not transcript text.
 
-`loopmath share --out FILE` writes a reduced copy you can send to us. It keeps task types, workflows, models, tokens, dollars and outcomes. Repository names are hashed. Titles, paths, commands, session ids and commit shas are removed. `loopmath share --preview` prints exactly what would leave.
+`loopmath share --out FILE` writes a reduced copy you can send to us. It keeps task types, workflows, models, tokens, dollars and outcomes. Repository names are hashed. Titles, paths, commands, session ids and commit shas are removed. `loopmath share --preview` prints exactly what would leave. `--out FILE.json` writes plain JSON you can read; any other name, such as `share.json.gz`, writes gzip.
+
+`loopmath prior import-shared FILE` adds a file another organization shared with you to your priors (either format; not one this store shared itself), and `loopmath prior remove-shared ORG` takes it out again; run `loopmath fit` after either.
 
 ## Analyzing logs without recording
 
@@ -211,13 +222,15 @@ loopmath analyze                 # cost per accepted run from the last 14 days o
 loopmath graph --workspace NAME --format html --out graph.html
 ```
 
-`analyze` reads `~/.claude/projects` and `~/.codex/sessions`. It grades the outcome evidence it finds, prices known models, and prints cost per accepted run with an 80% band. It also lists what it could not use and why.
+`analyze` reads `~/.claude/projects` and `~/.codex/sessions`. It grades the outcome evidence it finds, prices known models, and prints cost per accepted run with an 80% band. It also lists what it could not use and why; when no workflow configuration has enough runs to compare, it says how many runs it read and what kept each out, and what to try (`--min-n`, `--grading`). `loopmath analyze --json` prints the same as one JSON object, and `--home PATH` keeps its parse cache in that store.
+
+`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`. See the [workflow graph guide](docs/graph.md) and [adapters](docs/adapters.md).
+`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 fit|transfer-test` and `loopmath analyze-e0` read data folders that are not part of the package. Name them 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`). The research verbs need the `bayes` extra (`pip install 'loopmath[bayes]'`).
+`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.
 
 ## More
 

{loopmath-0.2.3 → loopmath-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "loopmath"
-version = "0.2.3"
+version = "0.2.4"
 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.2.3 → loopmath-0.2.4}/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.2.3"
+__version__ = "0.2.4"

{loopmath-0.2.3 → loopmath-0.2.4}/src/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-0.2.3 → loopmath-0.2.4}/src/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-0.2.3 → loopmath-0.2.4}/src/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-0.2.3 → loopmath-0.2.4}/src/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-0.2.3 → loopmath-0.2.4}/src/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-0.2.3 → loopmath-0.2.4}/src/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-0.2.3 → loopmath-0.2.4}/src/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-0.2.3 → loopmath-0.2.4}/src/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-0.2.3 → loopmath-0.2.4}/src/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-0.2.3 → loopmath-0.2.4}/src/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-0.2.3 → loopmath-0.2.4}/src/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