feat(standard): stop a run at a spending cap

.claude/rules/running.md

@@ -16,8 +16,9 @@ through the execution backend (`docs/builder.md`).
   are included; configuration and credential stores are excluded. Several
   machines run one shard each.
 - **Keys**: a run gets only its provider's key and endpoint, as environment
-  (over stdin to a host), never written; logs are redacted. The standard's
-  agents and upstream scripts get only the relay's word, never a key.
+  (over stdin to a host, and the key to a docker relay as a file); logs are
+  redacted. The standard's agents and upstream scripts get only the relay's
+  word, never a key.
 - What a recipe needs of each machine is asked before Run and again as it
   starts (`nullius/prerequisites.py`). `runs/<name>/run.json` lets a
   restarted Nullius pick a run up again.

AGENTS.md

@@ -61,7 +61,7 @@ and its resources. The source layout stays under `app/`.
   `feed`: the live feed any Harbor writes, from its own trial hooks),
   `importers/` (`atif` ATIF, `otel` OpenTelemetry, and the `cli`), `judge/` (`questions`, `state`, `client`, `store`, `batch`, `reconcile`, `lanes`),
   `standard/` (the Nullius standard, `docs/standard.md`: `ports`, `names` (capability vocabulary and legacy aliases), `definitions` (with an agent's or capability's versions), `match`,
-  `jsonl`, `acp`, `cancellation` (interruptible protocol waits), `relay`, `install`, `run`, `container` (the docker backend), `forward` (a licence server's one door from it, or a benchmark's MCP server's), `mcp_machine` and `mcp_bridge` (a benchmark's MCP server run on the machine, in its driver's environment, and the agent's bridge to it), `hostreq` (what a benchmark's options need of the machine its driver runs on: the check and the install) and `egress` (an own image's check's proxy to public addresses), `job`, `conform`, `fidelity` (ACP against the agent's own CLI), `prove` (a benchmark's controls and proofs), `shard` and `merge` (one run over many machines), `recipe` (the builder's standard recipe), `howto` (the How to add steps) and the `cli`; its
+  `jsonl`, `acp`, `cancellation` (interruptible protocol waits), `relay`, `ledger` (a run's spending cap: each call booked before it is sent), `install`, `run`, `container` (the docker backend), `forward` (a licence server's one door from it, or a benchmark's MCP server's), `mcp_machine` and `mcp_bridge` (a benchmark's MCP server run on the machine, in its driver's environment, and the agent's bridge to it), `hostreq` (what a benchmark's options need of the machine its driver runs on: the check and the install) and `egress` (an own image's check's proxy to public addresses), `job`, `conform`, `fidelity` (ACP against the agent's own CLI), `prove` (a benchmark's controls and proofs), `shard` and `merge` (one run over many machines), `recipe` (the builder's standard recipe), `howto` (the How to add steps) and the `cli`; its
   `payload` snapshots the running backend and effective catalogue for a remote host;
   conformance kits under `standard/kits/`, each a benchmark: a `driver` and, for the
   tools kit, an MCP server `mcp_kit`) - the definitions it reads are in the catalogue:

app/nullius/catalogue/capabilities/mem0/capability.py

@@ -12,7 +12,8 @@
 
 ``add {session}``     - the session's turns as Mem0 messages (a role other than
                         user or assistant is a user turn naming its speaker),
-                        added for one user, the session's id and date as metadata
+                        added for one user, the session's id and date as metadata,
+                        the date also as ``timestamp``
 ``recall {question}`` - ``{memory}``: what Mem0's search returns, best first,
                         each memory headed by its session's date
 
@@ -111,8 +112,10 @@ def add(self, s):
         self.dates[sid] = str(s.get("date") or "")
         self.warnings.take()
         t0 = time.time()
-        got = self.mem.add(messages, user_id=USER, metadata={"session": sid, "date": self.dates[sid]},
-                           infer=setting("MEM0_INFER", "on") != "off")
+        meta = {"session": sid, "date": self.dates[sid]}
+        if self.dates[sid]:
+            meta["timestamp"] = self.dates[sid]
+        got = self.mem.add(messages, user_id=USER, metadata=meta, infer=setting("MEM0_INFER", "on") != "off")
         items = got.get("results") if isinstance(got, dict) else got
         return {"trace": {"messages": len(messages), "seconds": round(time.time() - t0, 3),
                           "written": [{k: it.get(k) for k in ("id", "event", "memory", "previous_memory") if it.get(k) is not None}

app/nullius/execution.py

@@ -78,9 +78,9 @@
 run without that endpoint fails before it starts.
 They are read on this machine and handed to the run as environment
 (API_TOKEN, OPENAI_API_KEY, LLM_API_KEY; API_URL, OPENAI_BASE_URL,
-LLM_BASE_URL) - over stdin to the launcher, never in argv, never written
-anywhere; a stdin cut short starts nothing and fails the run at that part
-(``_launch``), and one that holds a line break is never sent
+LLM_BASE_URL) - over stdin to the launcher, never in argv (the key to a
+docker relay as a file); a stdin cut short starts nothing and fails the
+run at that part (``_launch``), and one that holds a line break is never sent
 (``_line_break``) - and they are the only credentials it has: its commands get this
 process's environment less every secret in Settings, whichever provider it
 belongs to (``withheld``); a host gets nothing of it but stdin.

app/nullius/runs/classify.py

@@ -57,6 +57,7 @@
     "modelnotfounderror",         # the model name is wrong; the agent never ran
     "networkconnectionerror",     # DNS, refused connection, TLS — transport, not skill
     "unknownapierror",            # Harbor's own "some provider error"; an ApiError without the prefix
+    "spendingcaperror",           # the run's own spending cap refused the call (the standard's relay): no attempt was had
 }
 
 # What Harbor's agents raise when the agent itself fails — its budget spent,
@@ -131,7 +132,8 @@
     ),
     API_ERROR: (
         "The model API failed some other way — overloaded, unreachable, out of "
-        "quota, or the key was rejected. The agent never got a fair attempt, so "
+        "quota, or the key was rejected — or the run's own spending cap refused "
+        "the call. The agent never got a fair attempt, so "
         "this is infrastructure too and is excluded from the adjusted rate."
     ),
     SETUP_ERROR: (

app/nullius/standard/cli.py

@@ -6,7 +6,7 @@
     PYTHONPATH=app python3 -m nullius.standard.cli new benchmark|agent|capability KEY [--family F] [--port P]
     PYTHONPATH=app python3 -m nullius.standard.cli new version KEY VERSION
     PYTHONPATH=app python3 -m nullius.standard.cli conform AGENT|CAPABILITY --model M [--provider P] [--port PORT ...] [--repeat K] [--option NAME=VALUE ...] [--unsandboxed | --backend docker]
-    PYTHONPATH=app python3 -m nullius.standard.cli run BENCHMARK[@VERSION] AGENT|CAPABILITY --model M [--provider P] [--limit N] [-j N] [--option NAME=VALUE ...] [--bench-option NAME=VALUE ...] [--price MODEL=INPUT,OUTPUT[,CACHED] ...] [--unsandboxed | --backend docker]
+    PYTHONPATH=app python3 -m nullius.standard.cli run BENCHMARK[@VERSION] AGENT|CAPABILITY --model M [--provider P] [--limit N] [-j N] [--option NAME=VALUE ...] [--bench-option NAME=VALUE ...] [--price MODEL=INPUT,OUTPUT[,CACHED] ...] [--max-usd USD] [--unsandboxed | --backend docker]
     PYTHONPATH=app python3 -m nullius.standard.cli run BENCHMARK[@VERSION] nop|oracle [--dataset D] [--limit N]
     PYTHONPATH=app python3 -m nullius.standard.cli prove BENCHMARK[@VERSION] [--dataset D] [--limit N]
     PYTHONPATH=app python3 -m nullius.standard.cli run ... --shard I/N [--launch ID]
@@ -469,7 +469,7 @@ def cmd_run(a):
                       concurrency=a.concurrency, jobs_root=a.jobs, name=a.name, unsandboxed=a.unsandboxed, judge_model=a.judge_model, backend=a.backend,
                       simulator_model=a.simulator_model, options=options(a.option), shard=_shard(a.shard), launch=a.launch,
                       licences=held, bench_options=options(a.bench_option), repeat=a.repeat, remove_images=a.remove_images,
-                      prices=prices(a.price), **({"env": run_env(a.provider)} if a.from_run else {}))
+                      prices=prices(a.price), max_usd=a.max_usd, **({"env": run_env(a.provider)} if a.from_run else {}))
     except run.Refused as e:
         print("refused:", e)
         return 2
@@ -624,6 +624,8 @@ def main(argv=None):
                            help="one of the benchmark's own options (repeatable: a search, a mode); the rest keep their defaults")
             p.add_argument("--price", action="append", metavar="MODEL=INPUT,OUTPUT[,CACHED]",
                            help="this run's price for a model in USD per million tokens, over your price list (repeatable; nullius prices)")
+            p.add_argument("--max-usd", type=float, metavar="USD",
+                           help="the run's spending cap: no call goes out once the spend plus the calls in flight would pass it")
     v = sub.add_parser("prove", help="prove a benchmark: its controls, its units, no leak; record what passed")
     v.add_argument("benchmark")
     v.add_argument("--dataset", help="one dataset (default: each)")