cdx-manager 0.21.5 → 0.22.0

package/src/notify.py

@@ -215,8 +215,13 @@ def windows_aumid(env=None):
     return _POWERSHELL_AUMID
 
 
+# PowerShell also ends a single-quoted string on the typographic quotes
+# U+2018..U+201B, so each must be doubled like ASCII ' (French "l’agent").
+_POWERSHELL_QUOTES = "'\u2018\u2019\u201a\u201b"
+
+
 def _escape_powershell(value):
-    return str(value).replace("'", "''")
+    return "".join(ch * 2 if ch in _POWERSHELL_QUOTES else ch for ch in str(value))
 
 
 def _escape_applescript(value):
@@ -370,23 +375,23 @@ def _schedule_linux(parsed, event, argv, spawn_sync, env):
 def _schedule_windows_task(parsed, event, argv, spawn_sync, env):
     name = _schedule_id("cdx-manager-notify", parsed, event)
     target = datetime.fromtimestamp(event["target_timestamp"]).astimezone()
-    command = subprocess.list2cmdline([str(part) for part in argv])
-    result = _run_scheduler_command([
-        "schtasks",
-        "/Create",
-        "/SC",
-        "ONCE",
-        "/TN",
-        name,
-        "/TR",
-        command,
-        "/ST",
-        target.strftime("%H:%M"),
-        "/SD",
-        target.strftime("%m/%d/%Y"),
-        "/F",
-        "/Z",
-    ], spawn_sync, env)
+    # Not `schtasks /SD`: it reads the date in the user's locale format, so
+    # mm/dd/yyyy is refused on a dd/MM/yyyy (French) Windows. An invariant
+    # ISO date through Register-ScheduledTask works on every locale.
+    start = target.strftime("%Y-%m-%dT%H:%M")
+    end = (target + timedelta(hours=1)).strftime("%Y-%m-%dT%H:%M")
+    arguments = subprocess.list2cmdline([str(part) for part in argv[1:]])
+    script = (
+        "$c = [Globalization.CultureInfo]::InvariantCulture; "
+        f"$t = New-ScheduledTaskTrigger -Once -At ([datetime]::ParseExact('{start}', 'yyyy-MM-ddTHH:mm', $c)); "
+        f"$t.EndBoundary = ([datetime]::ParseExact('{end}', 'yyyy-MM-ddTHH:mm', $c)).ToString('s'); "
+        f"$a = New-ScheduledTaskAction -Execute '{_escape_powershell(argv[0])}' -Argument '{_escape_powershell(arguments)}'; "
+        "$s = New-ScheduledTaskSettingsSet -DeleteExpiredTaskAfter (New-TimeSpan -Seconds 1); "
+        f"Register-ScheduledTask -TaskName '{_escape_powershell(name)}' -Action $a -Trigger $t -Settings $s -Force | Out-Null"
+    )
+    result = _run_scheduler_command(
+        ["powershell", "-NoProfile", "-NonInteractive", "-Command", script], spawn_sync, env,
+    )
     if not result["ok"]:
         raise CdxError(f"Failed to schedule notification with Task Scheduler: {result['error']}")
     return {"scheduled": True, "existing": False, "backend": "schtasks", "id": name}

package/src/provider_background.py

@@ -72,12 +72,13 @@ def supports_native_background(provider, env=None, spawn_sync=None):
     1. A delegated run cannot honour the `cdx run --json` contract. The
        in-house path runs `claude --print --output-format json` and gets a
        structured result, token usage, and a final payload. `--bg` runs the
-       interactive TUI; `claude logs <id>` returns an ANSI screen dump. So
-       usage accounting, the final payload, and the rate-limit classification
-       that `--failover` depends on all have no source.
-    2. Nothing yet drives a delegated run to a terminal status. `agent_terminal_status`
-       exists but no caller consults the provider, so the record relies on pid
-       liveness and a blocked agent reads as running indefinitely.
+       interactive TUI; `claude logs <id>` returns an ANSI screen dump. Usage
+       and the final text are read back from the session transcript, but the
+       rate-limit classification that `--failover` depends on has no source.
+    2. A delegated run only reaches a terminal status when a caller reads it:
+       `_reconcile_background_runs` in commands/runs.py consults the
+       transcript, then `agent_terminal_status`, on `cdx runs`, `run-status`
+       and `run-report`. Until one of those runs, the record stays `running`.
     3. cdx's own launch spec makes the agent block. A hand-run
        `claude --bg --permission-mode bypassPermissions "..."` reaches
        `state: done`; the same task launched through cdx sits at
@@ -107,7 +108,7 @@ def _default_spawn_sync(argv, env=None):
         completed = subprocess.run(
             argv,
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
             timeout=_CAPABILITY_PROBE_TIMEOUT_SECONDS,
             env=env,
             check=False,
@@ -223,6 +224,7 @@ def read_transcript_outcome(path):
     if not path:
         return outcome
     totals = {"input_tokens": 0, "cache_creation_tokens": 0, "cache_read_tokens": 0, "output_tokens": 0}
+    long_ttl = None
     # This path had no de-duplication at all, so a transcript that records the
     # same billed response more than once inflated the total outright.
     counted = set()
@@ -268,10 +270,13 @@ def read_transcript_outcome(path):
                     totals["cache_creation_tokens"] += usage.get("cache_creation_input_tokens") or 0
                     totals["cache_read_tokens"] += usage.get("cache_read_input_tokens") or 0
                     totals["output_tokens"] += usage.get("output_tokens") or 0
+                    split = usage.get("cache_creation")
+                    if isinstance(split, dict) and "ephemeral_1h_input_tokens" in split:
+                        long_ttl = (long_ttl or 0) + (split["ephemeral_1h_input_tokens"] or 0)
     except OSError:
         return outcome
     if seen:
-        outcome["usage"] = normalize_usage(**totals)
+        outcome["usage"] = normalize_usage(**totals, cache_creation_1h_tokens=long_ttl)
         if len(models) == 1:
             outcome["usage_model"] = next(iter(models))
     return outcome

package/src/provider_runtime.py

@@ -150,6 +150,10 @@ CLAUDE_PARENT_SESSION_ENV = (
     "CLAUDE_CODE_MESSAGING_SOCKET",
     "CLAUDE_CODE_MESSAGING_TOKEN",
     "CLAUDE_PID",
+    # Credentials: a profile launched from inside another profile's session must
+    # not inherit that account's token. The profile's own token is set after.
+    "CLAUDE_CODE_OAUTH_TOKEN",
+    "ANTHROPIC_API_KEY",
 )
 CLAUDE_CLI_MODEL_ALIASES = {
     "claude-sonnet": "sonnet",
@@ -208,6 +212,40 @@ def _shared_tool_cache_overrides(env):
     }
 
 
+def operator_rtk_history_path(env=None):
+    """The rtk history database of the operator's real home.
+
+    rtk files its savings under the data dir of HOME, and a profile launch
+    swaps HOME, so each account kept its own history.db and `rtk gain` in the
+    operator's shell saw none of what the agents saved. Read from the passwd
+    entry rather than HOME, which is already a profile home when cdx runs
+    inside a session.
+    """
+    env = os.environ if env is None else env
+    if os.name == "nt":
+        base = env.get("LOCALAPPDATA")
+        return os.path.join(base, "rtk", "history.db") if base else None
+    import pwd
+
+    try:
+        home = pwd.getpwuid(os.getuid()).pw_dir
+    except KeyError:
+        # A uid without a passwd entry (common in containers): no better
+        # answer than HOME.
+        home = env.get("HOME") or os.path.expanduser("~")
+    if sys.platform == "darwin":
+        return os.path.join(home, "Library", "Application Support", "rtk", "history.db")
+    data_home = env.get("XDG_DATA_HOME") or os.path.join(home, ".local", "share")
+    return os.path.join(data_home, "rtk", "history.db")
+
+
+def _shared_rtk_history(env):
+    """Point every profile's rtk at one history, unless the operator chose one."""
+    path = None if env.get("RTK_DB_PATH") else operator_rtk_history_path(env)
+    if path:
+        env["RTK_DB_PATH"] = path
+
+
 def _anthropic_profile_name():
     return "default"
 
@@ -419,11 +457,11 @@ def _normalize_reasoning_effort(reasoning_effort=None, power=None, usage="Unsupp
     if alias == "":
         raise CdxError(usage)
     if effort and effort not in REASONING_EFFORT_VALUES:
-        raise CdxError(f"Unsupported reasoning effort: {reasoning_effort}")
+        raise CdxError(f"Unsupported reasoning effort: {reasoning_effort}", code="invalid_reasoning_effort")
     if alias and alias not in REASONING_EFFORT_VALUES:
         raise CdxError(f"Unsupported power: {power}")
     if effort and alias and effort != alias:
-        raise CdxError("--reasoning-effort and --power must match when both are provided.")
+        raise CdxError("--reasoning-effort and --power must match when both are provided.", code="invalid_reasoning_effort")
     resolved = effort or alias
     if not resolved:
         return {}
@@ -542,6 +580,9 @@ def _wrap_launch_with_transcript(session, spec, capture_transcript=True, env=Non
     script_args = env.get("CDX_SCRIPT_ARGS")
     transcript_path = _build_launch_transcript_path(session)
     os.makedirs(os.path.dirname(transcript_path), exist_ok=True)
+    if os.name != "nt":
+        # script(1) keeps an existing file's mode, and a transcript can hold a token.
+        os.close(os.open(transcript_path, os.O_CREAT | os.O_WRONLY, 0o600))
     if script_args:
         args = shlex.split(script_args)
         if "{transcript}" in args:
@@ -573,6 +614,19 @@ def _rtk_enabled(session):
     return (session.get("launch") or {}).get("rtk") is True
 
 
+# Claude Code passes credentials (including the setup-token cdx injects) to
+# the Bash commands, hooks and MCP servers it starts unless this is set. Opt-in:
+# it also strips other secrets an agent may need and, on Linux, isolates Bash
+# from host processes (`ps`, `kill`).
+CLAUDE_SCRUB_ENV = "CLAUDE_CODE_SUBPROCESS_ENV_SCRUB"
+
+
+def _scrub_env(session):
+    if session.get("provider") == PROVIDER_CLAUDE and (session.get("launch") or {}).get("scrub_env") is True:
+        return {CLAUDE_SCRUB_ENV: "1"}
+    return {}
+
+
 def _logics_manager_available(path=None):
     return shutil.which("logics-manager", path=path) is not None
 
@@ -661,11 +715,15 @@ def _build_launch_spec(session, cwd=None, env_override=None, initial_prompt=None
     env = {**os.environ, **env_override}
     for key, value in _shared_tool_cache_overrides(env).items():
         env.setdefault(key, value)
+    _shared_rtk_history(env)
     env.update(launch_notify_env(session, notifications_enabled(session)))
+    env.update(_scrub_env(session))
     preference_args = _launch_preference_args(session, env=env)
     if session["provider"] == PROVIDER_CLAUDE:
         launch = session.get("launch") or {}
-        args = ["--name", session["name"]]
+        # No --name: it would title every conversation after the account in
+        # the /resume picker. The account already shows in cdx's terminal title.
+        args = []
         conversation_id = _conversation_id(session)
         if conversation_id:
             args += ["--session-id", conversation_id]
@@ -836,6 +894,7 @@ def _build_resume_spec(session, cwd=None, env_override=None, capture_transcript=
     cwd = cwd or os.getcwd()
     env_override = env_override or {}
     env = {**os.environ, **env_override}
+    _shared_rtk_history(env)
     capability = get_resume_capability(session, cwd=cwd)
     if not capability["resumable"]:
         raise CdxError(f"Provider {session.get('provider')} does not support native resume through cdx.")
@@ -855,7 +914,7 @@ def _build_resume_spec(session, cwd=None, env_override=None, capture_transcript=
             if capability["strategy"] == "provider_conversation_id"
             else ["--continue"]
         )
-        args += ["--name", session["name"]]
+        # No --name: on a resume it would overwrite the user's /rename.
         if launch.get("model"):
             args += ["--model", _claude_cli_model(launch["model"])]
         args += _launch_config_args(session)
@@ -912,9 +971,11 @@ def _build_headless_launch_spec(session, cwd=None, env_override=None, initial_pr
     _validate_initial_prompt(initial_prompt)
     cwd = cwd or os.getcwd()
     env = {**os.environ, **(env_override or {})}
+    _shared_rtk_history(env)
     # Headless runs read the same home, and so the same hooks, as an interactive
     # launch. Their caller already learns of completion from the return value.
     env.update(launch_notify_env(session, enabled=False))
+    env.update(_scrub_env(session))
     preference_args = _launch_preference_args(session, env=env)
     launch = session.get("launch") or {}
     power = _launch_power(session)
@@ -922,7 +983,7 @@ def _build_headless_launch_spec(session, cwd=None, env_override=None, initial_pr
     model = launch.get("model")
 
     if session["provider"] == PROVIDER_CLAUDE:
-        args = ["--print", "--output-format", "json", "--name", session["name"]]
+        args = ["--print", "--output-format", "json"]
         conversation_id = _conversation_id(session)
         if conversation_id:
             args += ["--session-id", conversation_id]
@@ -1056,6 +1117,32 @@ def _signal_child_group(child, sig):
         return False
 
 
+def _raise_keyboard_interrupt(_signum, _frame):
+    raise KeyboardInterrupt
+
+
+def _route_termination_to_interrupt():
+    """Make SIGTERM and SIGHUP raise KeyboardInterrupt; returns what to restore."""
+    previous = {}
+    for name in ("SIGTERM", "SIGHUP"):
+        sig = getattr(signal, name, None)
+        if sig is None:
+            continue
+        try:
+            previous[sig] = signal.signal(sig, _raise_keyboard_interrupt)
+        except (ValueError, OSError):  # not the main thread, or not settable here
+            pass
+    return previous
+
+
+def _restore_signal_handlers(previous):
+    for sig, handler in previous.items():
+        try:
+            signal.signal(sig, handler)
+        except (ValueError, OSError):
+            pass
+
+
 def _terminate_child_tree(child):
     if not _signal_child_group(child, signal.SIGTERM):
         try:
@@ -1111,14 +1198,18 @@ def _run_headless_provider_command(session, cwd=None, env_override=None, initial
             )
         except FileNotFoundError as error:
             _combine_headless_transcript(paths)
-            cdx_error = CdxError(f"{spec['label']} CLI not found on PATH: {spec['command']}", 127)
+            cdx_error = CdxError(f"{spec['label']} CLI not found on PATH: {spec['command']}", 127, code="provider_cli_not_found")
             cdx_error.run_info = _headless_run_info(paths, spec, start_time, 127)
             raise cdx_error from error
         except OSError as error:
             _combine_headless_transcript(paths)
-            cdx_error = CdxError(f"Failed to start {spec['label']}: {error}", 126)
+            cdx_error = CdxError(f"Failed to start {spec['label']}: {error}", 126, code="provider_start_failed")
             cdx_error.run_info = _headless_run_info(paths, spec, start_time, 126)
             raise cdx_error from error
+        # SIGTERM/SIGHUP (kill, systemctl stop, a closed SSH session) unwind
+        # like Ctrl+C: the provider's own process group would otherwise outlive
+        # this supervisor and keep its run "running" forever.
+        previous_handlers = _route_termination_to_interrupt()
         try:
             if timeout_seconds is None:
                 child.wait()
@@ -1136,6 +1227,8 @@ def _run_headless_provider_command(session, cwd=None, env_override=None, initial
             # the run still gets a terminal record.
             cancelled = True
             _terminate_child_tree(child)
+        finally:
+            _restore_signal_handlers(previous_handlers)
 
     if cancelled:
         _combine_headless_transcript(paths)
@@ -1283,7 +1376,7 @@ def _probe_provider_auth_status(session, spawn_sync=None, env_override=None, tru
             result = subprocess.run(
                 [command] + spec["args"],
                 env=spec["env"],
-                capture_output=True, text=True,
+                capture_output=True, text=True, encoding="utf-8", errors="replace",
                 timeout=AUTH_PROBE_TIMEOUT_SECONDS,
             )
             output = (result.stdout or "") + (result.stderr or "")

package/src/retro.py

@@ -0,0 +1,131 @@
+"""Session retrospectives: what the user had to correct, so the next session knows it.
+
+With `cdx set <name> --retro on`, the end of an interactive session starts a
+detached, read-only `cdx run --kind retro` on a ready account. It reads the
+session's transcript and reports the corrections the user made and the lessons
+worth keeping, each with where it belongs (memory, runbook, skill, CLAUDE.md).
+It changes nothing: `cdx retro` shows the reports, and the user decides.
+"""
+
+import json
+import os
+import shutil
+import subprocess
+
+#: A session with fewer prompts than this rarely holds a correction worth a model call.
+MIN_USER_PROMPTS = 3
+
+PROMPT = """You are writing a retrospective of one finished coding-agent session. Do not modify any file.
+
+Transcript (JSONL, possibly large; read it in bounded portions, never all at once): {transcript}
+Project folder: {cwd}
+
+Find the moments where the user corrected, redirected or overruled the agent, and the
+non-obvious facts the session had to discover. Ignore routine back-and-forth.
+
+Answer in Markdown with exactly these sections:
+## Corrections
+One bullet per correction: what the agent did, what the user wanted, in one line each.
+## Lessons
+One bullet per lesson worth keeping for future sessions, each starting with where it belongs:
+`memory:`, `runbook:`, `skill:` or `CLAUDE.md:`, followed by the exact text to add.
+## Verdict
+One line: "nothing to learn" if both sections are empty, else the single most useful lesson.
+"""
+
+
+def enabled(session):
+    return (session.get("launch") or {}).get("retro") is True
+
+
+def start(session, cwd, transcript, env=None, popen=subprocess.Popen):
+    """Start the retro run in the background; returns the argv, or None when skipped."""
+    env = {**os.environ, **(env or {})}
+    if not enabled(session) or not transcript or not os.path.isfile(transcript):
+        return None
+    if env.get("CDX_RETRO") == "1" or _user_prompts(transcript) < MIN_USER_PROMPTS:
+        return None
+    executable = env.get("CDX_BIN") or shutil.which("cdx", path=env.get("PATH")) or "cdx"
+    argv = [
+        executable, "run", "--provider", session["provider"], "--cwd", cwd, "--kind", "retro",
+        "--permission", "read-only", "--power", "low", "--detach", "--json",
+        "--prompt", PROMPT.format(transcript=transcript, cwd=cwd),
+    ]
+    env["CDX_RETRO"] = "1"  # a retro never asks for a retro of itself
+    try:
+        popen(argv, env=env, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
+              stderr=subprocess.DEVNULL, start_new_session=True)
+    except OSError:
+        return None
+    return argv
+
+
+def _user_prompts(transcript):
+    """Prompts the user typed: Claude `user` records that are not tool results, Codex `user_message` events.
+
+    Size is no proxy: one long handoff prompt makes a large transcript of a session
+    that never started.
+    """
+    count = 0
+    try:
+        with open(transcript, encoding="utf-8", errors="replace") as handle:
+            for line in handle:
+                if ('"type":"user"' in line and '"tool_result"' not in line) or '"type":"user_message"' in line:
+                    count += 1
+                    if count >= MIN_USER_PROMPTS:
+                        break
+    except OSError:
+        return 0
+    return count
+
+
+def reports(registry, limit=5):
+    """The newest retro runs, newest first, with their text when finished."""
+    found = []
+    for run in registry.list(limit=200):
+        if run.get("kind") != "retro":
+            continue
+        payload = run.get("final_payload") if isinstance(run.get("final_payload"), dict) else {}
+        found.append({"run_id": run.get("run_id"), "status": run.get("status"), "cwd": run.get("cwd"),
+                      "started_at": run.get("started_at"), "session": run.get("session"),
+                      "report": _result_text(payload.get("stdout_path"))})
+        if len(found) >= limit:
+            break
+    return found
+
+
+def _result_text(stdout_path):
+    """The answer of a finished run: Claude's `result`, else where to read it."""
+    if not stdout_path or not os.path.isfile(stdout_path):
+        return None
+    try:
+        with open(stdout_path, encoding="utf-8") as handle:
+            document = json.load(handle)
+    except (OSError, ValueError):
+        return f"(see {stdout_path})"
+    result = document.get("result") if isinstance(document, dict) else None
+    return result if isinstance(result, str) else f"(see {stdout_path})"
+
+
+def handle_retro(rest, ctx):
+    from .cli_helpers import _json_success, _write_json
+    from .errors import CdxError
+    from .run_registry import RunRegistry
+
+    json_flag = "--json" in rest
+    args = [arg for arg in rest if arg != "--json"]
+    limit = 5
+    if args[:1] == ["--limit"] and len(args) == 2 and args[1].isdigit():
+        limit = int(args[1])
+    elif args:
+        raise CdxError("Usage: cdx retro [--limit N] [--json]")
+    found = reports(RunRegistry(ctx["service"]["base_dir"]), limit=limit)
+    if json_flag:
+        _write_json(ctx, _json_success("retro", f"{len(found)} retro(s)", retros=found))
+        return 0
+    if not found:
+        ctx["out"]("No session retro yet. Turn them on with `cdx set <name> --retro on`.\n")
+        return 0
+    for item in found:
+        ctx["out"](f"## {item['started_at']} · {item['cwd']} · {item['status']}\n{item['report'] or '(still running)'}\n\n")
+    return 0

package/src/rtk_savings.py

@@ -0,0 +1,68 @@
+"""What rtk saved, for the period `cdx stats` reports on.
+
+Launches share the operator's rtk history (RTK_DB_PATH), but profiles used before
+that kept their own `history.db` under their home; both are read so older
+savings are not lost. rtk itself does the reading (`rtk gain --daily --format
+json`), so this never depends on its database schema.
+"""
+
+import glob
+import json
+import os
+import shutil
+import subprocess
+from datetime import datetime
+
+from .provider_runtime import operator_rtk_history_path
+
+_PROFILE_DBS = (
+    ("*", "Library", "Application Support", "rtk", "history.db"),
+    ("*", "*-home", "Library", "Application Support", "rtk", "history.db"),
+    ("*", ".local", "share", "rtk", "history.db"),
+    ("*", "*-home", ".local", "share", "rtk", "history.db"),
+)
+
+
+def history_databases(base_dir, env=None):
+    """Every rtk history this operator's sessions wrote to, the shared one first."""
+    env = os.environ if env is None else env
+    found = []
+    for path in [env.get("RTK_DB_PATH") or operator_rtk_history_path(env)] + [
+        match for pattern in _PROFILE_DBS
+        for match in sorted(glob.glob(os.path.join(glob.escape(os.path.join(base_dir, "profiles")), *pattern)))
+    ]:
+        if path and os.path.isfile(path) and os.path.realpath(path) not in {os.path.realpath(p) for p in found}:
+            found.append(path)
+    return found
+
+
+def _in_period(day, period):
+    for key, keep in (("from", lambda d, edge: d >= edge), ("to", lambda d, edge: d <= edge)):
+        edge = (period or {}).get(key)
+        if edge and not keep(day, datetime.fromisoformat(edge).date().isoformat()):
+            return False
+    return True
+
+
+def rtk_saved(base_dir, period=None, env=None, run=subprocess.run):
+    """{commands, input_tokens, saved_tokens, databases} over the period, or None without rtk."""
+    env = {**os.environ, **(env or {})}
+    rtk = shutil.which("rtk", path=env.get("PATH"))
+    databases = history_databases(base_dir, env)
+    if not rtk or not databases:
+        return None
+    totals = {"commands": 0, "input_tokens": 0, "saved_tokens": 0, "databases": 0}
+    for database in databases:
+        try:
+            result = run([rtk, "gain", "--daily", "--format", "json"], env={**env, "RTK_DB_PATH": database},
+                         capture_output=True, text=True, timeout=15, check=False)
+            days = json.loads(result.stdout).get("daily") or []
+        except (OSError, ValueError, AttributeError, subprocess.TimeoutExpired):
+            continue
+        totals["databases"] += 1
+        for day in days:
+            if isinstance(day, dict) and _in_period(str(day.get("date")), period):
+                totals["commands"] += int(day.get("commands") or 0)
+                totals["input_tokens"] += int(day.get("input_tokens") or 0)
+                totals["saved_tokens"] += int(day.get("saved_tokens") or 0)
+    return totals if totals["databases"] else None

package/src/run_registry.py

@@ -219,15 +219,41 @@ def _base_record(run_id, *, kind, session, provider, model, cwd, artifacts=None)
     }
 
 
+def _check_capacity(data, max_parallel):
+    _refresh_stale_runs(data)
+    running = sum(1 for run in data["runs"] if run.get("status") == "running")
+    if running >= max_parallel:
+        raise CdxError(
+            f"{running} run(s) already running, the limit is {max_parallel}. "
+            "Wait for one to finish (cdx runs --json) or raise --max-parallel.",
+            code="too_many_runs",
+        )
+
+
 class RunRegistry:
     def __init__(self, base_dir):
         self.path = registry_path(base_dir)
 
-    def start(self, run_id, *, kind, session, provider, model, cwd, artifacts=None):
+    def check_capacity(self, max_parallel):
+        """Raise too_many_runs now, before a refused run changes any session state.
+
+        `start()` checks again under the same lock, so a run that slips in
+        between is still refused there.
+        """
+        with _registry_lock(self.path):
+            _check_capacity(_read_registry(self.path), max_parallel)
+
+    def start(self, run_id, *, kind, session, provider, model, cwd, artifacts=None, label=None, max_parallel=None):
         with _registry_lock(self.path):
             data = _read_registry(self.path)
             data["runs"] = [run for run in data["runs"] if run.get("run_id") != run_id]
+            if max_parallel:
+                # Counted under the lock and without this run's own record, which a
+                # detached child writes a second time under the same id.
+                _check_capacity(data, max_parallel)
             record = _base_record(run_id, kind=kind, session=session, provider=provider, model=model, cwd=cwd, artifacts=artifacts)
+            if label:
+                record["label"] = label
             data["runs"].insert(0, record)
             _prune_finished_runs(data)
             _write_registry(self.path, data)