feat(cli): wire all Budget dimensions into grapharc run (#14)

--max-tokens was the only reachable ceiling. Operators can now also set
--max-iterations, --max-seconds, and --max-concurrency; unset flags stay
unlimited. Values appear in the --json payload and optional grapharc.toml keys.

Author: Matthew

README.md

@@ -493,7 +493,7 @@ Re-derived on 2026-07-28 by running each item, not by reading the commit log.
 - **A session turn is synchronous**, and a runner claim is a claim rather than a lease — nothing reclaims a session whose runner died holding it.
 - **A bare model spec resolves to the paid `claude-cli` backend.** `--model mock` does not reach the scripted double; it becomes the model name `mock` on the subscription backend. Only the slash form (`mock/anything`) reaches the double. A mistyped backend *with* a slash is rejected properly, exit 2.
 - **`.env` is found by walking up parent directories; `grapharc.toml` is not.** The config layer refuses an upward search on purpose — a run must not be governed by a file you did not know about. The credential loader predates that decision and still searches upward, so the thing that *spends money* is discovered more eagerly than the thing that *constrains* it.
-- **`grapharc run` has no budget unless you give it one.** `--max-tokens` is the only ceiling; without it the gate's budget dimension is unlimited and admits a topology of any worst-case cost.
+- **`grapharc run` has no budget unless you give it one.** Set any of `--max-tokens`, `--max-iterations`, `--max-seconds`, or `--max-concurrency`; without them each dimension is unlimited and the gate admits a topology of any worst-case cost.
 
 **Verified this pass:** `pytest` → 1,533 passed, 12 deselected (the live ones); `ruff check .` clean; all eight `grapharc demo` stages green, plus `grapharc plan` and `grapharc run`; the wheel builds and imports all 103 submodules in a clean virtualenv with `[all]`. The test count is a snapshot, not a property of the project — `pytest` re-derives it in one command, which is the only reason it is quoted.
 

grapharc/cli/config.py

@@ -55,6 +55,9 @@
     "memory": str,
     "max_rounds": int,
     "max_tokens": int,
+    "max_iterations": int,
+    "max_seconds": float,
+    "max_concurrency": int,
 }
 
 

grapharc/cli/graphrun.py

@@ -101,6 +101,9 @@ def run_graph(
     registry_target: str | None = None,
     policy_path: Path | None = None,
     max_tokens: int | None = None,
+    max_iterations: int | None = None,
+    max_seconds: float | None = None,
+    max_concurrency: int | None = None,
     tenant: str | None = None,
     trace_path: Path | None = None,
     run_id: str | None = None,
@@ -131,6 +134,9 @@ def run_graph(
         policy_path = settings.resolve_path("policy", policy_path)
         tenant = settings.resolve("tenant", tenant, "default")
         max_tokens = settings.resolve("max_tokens", max_tokens)
+        max_iterations = settings.resolve("max_iterations", max_iterations)
+        max_seconds = settings.resolve("max_seconds", max_seconds)
+        max_concurrency = settings.resolve("max_concurrency", max_concurrency)
         document = load_topology(Path(graph_path))
         proposal = build_proposal(document)
         bundle = resolve_registry(registry_target)
@@ -153,10 +159,15 @@ def run_graph(
     checker = AdmissionChecker(registry=registry, edge_policy=edge_policy, trace=trace)
 
     # `Budget()` is genuinely unlimited on every dimension, so with no
-    # `--max-tokens` the budget check passes anything. An earlier comment here
-    # claimed the opposite; an adversarial run admitted a 200-node chain whose
-    # worst case was 400,000 tokens. The meter is real only when a ceiling is.
-    meter = BudgetMeter(Budget(max_tokens=max_tokens) if max_tokens else Budget())
+    # ceilings the budget check passes anything. The meter is real only when
+    # at least one dimension is set.
+    budget = Budget(
+        max_tokens=max_tokens,
+        max_iterations=max_iterations,
+        max_seconds=max_seconds,
+        max_concurrency=max_concurrency,
+    )
+    meter = BudgetMeter(budget)
     # D2: the admission event has to carry the run id the operator chose, or
     # `grapharc metrics <trace> <run-id>` finds nothing under that id.
     rid = run_id or uuid.uuid4().hex[:12]
@@ -179,6 +190,9 @@ def run_graph(
         ],
         "run_id": rid,
         "max_tokens": max_tokens,
+        "max_iterations": max_iterations,
+        "max_seconds": max_seconds,
+        "max_concurrency": max_concurrency,
         "trace": str(trace_path),
         **settings.provenance(policy_source=policy_source),
     }

grapharc/cli/main.py

@@ -313,6 +313,9 @@ def _cmd_run(args: argparse.Namespace) -> int:
         trace_path=args.trace,
         run_id=args.run_id,
         max_tokens=args.max_tokens,
+        max_iterations=args.max_iterations,
+        max_seconds=args.max_seconds,
+        max_concurrency=args.max_concurrency,
         check_only=args.check_only,
         config_path=args.config,
         as_json=args.json,
@@ -630,11 +633,33 @@ def build_parser() -> argparse.ArgumentParser:
         "--max-tokens",
         type=int,
         default=None,
+        metavar="N",
         help=(
             "refuse a topology whose worst case exceeds this many tokens. "
-            "Without it the budget dimension is unlimited and admits anything"
+            "Without it this budget dimension is unlimited"
         ),
     )
+    run.add_argument(
+        "--max-iterations",
+        type=int,
+        default=None,
+        metavar="N",
+        help="stop the run after this many node iterations (unlimited if omitted)",
+    )
+    run.add_argument(
+        "--max-seconds",
+        type=float,
+        default=None,
+        metavar="SEC",
+        help="wall-clock run ceiling; interrupts a running node (unlimited if omitted)",
+    )
+    run.add_argument(
+        "--max-concurrency",
+        type=int,
+        default=None,
+        metavar="N",
+        help="max concurrent node executions (unlimited if omitted)",
+    )
     run.add_argument(
         "--check-only",
         action="store_true",

tests/test_cli.py

@@ -1376,6 +1376,48 @@ def test_run_can_be_given_a_token_ceiling(tmp_path, capsys):
     assert "over_token_budget" in [r["code"] for r in bounded["rejections"]]
 
 
+
+
+def test_run_budget_flags_reach_json_payload(tmp_path, capsys):
+    """All four Budget dimensions are settable from `grapharc run` (#5)."""
+    graph = _write_graph(tmp_path, _LEGAL_GRAPH)
+    code, payload, _ = call_json(
+        [
+            "run",
+            str(graph),
+            "--check-only",
+            "--trace",
+            str(tmp_path / "t.jsonl"),
+            "--max-tokens",
+            "5000",
+            "--max-iterations",
+            "12",
+            "--max-seconds",
+            "3.5",
+            "--max-concurrency",
+            "2",
+        ],
+        capsys,
+    )
+    assert code == 0
+    assert payload["max_tokens"] == 5000
+    assert payload["max_iterations"] == 12
+    assert payload["max_seconds"] == 3.5
+    assert payload["max_concurrency"] == 2
+
+
+def test_run_unset_budget_flags_stay_unlimited_in_json(tmp_path, capsys):
+    graph = _write_graph(tmp_path, _LEGAL_GRAPH)
+    code, payload, _ = call_json(
+        ["run", str(graph), "--check-only", "--trace", str(tmp_path / "t.jsonl")],
+        capsys,
+    )
+    assert code == 0
+    assert payload["max_tokens"] is None
+    assert payload["max_iterations"] is None
+    assert payload["max_seconds"] is None
+    assert payload["max_concurrency"] is None
+
 def test_viz_answers_an_unknown_run_id_as_a_document(tmp_path, capsys):
     """Every other reading command did; `viz` let `ReplayError` out raw."""
     graph = _write_graph(tmp_path, _LEGAL_GRAPH)