lucen-cli 0.1.2__tar.gz → 0.1.4__tar.gz

{lucen_cli-0.1.2 → lucen_cli-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lucen-cli
-Version: 0.1.2
+Version: 0.1.4
 Summary: MouseMouse CLI (`lucen`): push robot data, train and sim-test policies, hand them to a robot through a consent gate
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -129,7 +129,7 @@ AI agent are [`lucen-mcp`](https://pypi.org/project/lucen-mcp/).
   `lucen-sdk` 0.1.1.
 - **0.1.1** (2026-10-13): the built-in `ppo_mujoco` trainer's `velocity` preset
   trains under the sim tests' own conditions (the action delay, the rate limit
-  and the pushes), so a quick run on Laika stands at about 2° of tilt instead
+  and the pushes), so a quick run on Lucen Biped stands at about 2° of tilt instead
   of a crouch; ONNX Runtime's start-up messages stay out of a run's log; every
   "install the extra" hint names the PyPI line.
 - **0.1.0**: the first release on PyPI.

{lucen_cli-0.1.2 → lucen_cli-0.1.4}/README.md

@@ -93,7 +93,7 @@ AI agent are [`lucen-mcp`](https://pypi.org/project/lucen-mcp/).
   `lucen-sdk` 0.1.1.
 - **0.1.1** (2026-10-13): the built-in `ppo_mujoco` trainer's `velocity` preset
   trains under the sim tests' own conditions (the action delay, the rate limit
-  and the pushes), so a quick run on Laika stands at about 2° of tilt instead
+  and the pushes), so a quick run on Lucen Biped stands at about 2° of tilt instead
   of a crouch; ONNX Runtime's start-up messages stay out of a run's log; every
   "install the extra" hint names the PyPI line.
 - **0.1.0**: the first release on PyPI.

{lucen_cli-0.1.2 → lucen_cli-0.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lucen-cli"
-version = "0.1.2"
+version = "0.1.4"
 description = "MouseMouse CLI (`lucen`): push robot data, train and sim-test policies, hand them to a robot through a consent gate"
 # R1: `readme`, `license`, `license-files` and `[project.urls]` are what PyPI
 # renders; the LICENSE beside this file is Apache-2.0 verbatim (docs/DECISIONS.md "R1").

{lucen_cli-0.1.2 → lucen_cli-0.1.4}/src/lucen_cli/__init__.py

@@ -1,3 +1,3 @@
 """MouseMouse CLI."""
 
-__version__ = "0.1.2"
+__version__ = "0.1.4"

{lucen_cli-0.1.2 → lucen_cli-0.1.4}/src/lucen_cli/client.py

@@ -36,6 +36,8 @@ from typing import Any, Final
 import httpx
 from lucen_sdk import AuthenticatedClient
 from lucen_sdk.api.auth import get_me
+from lucen_sdk.api.campaigns import get_campaign as get_campaign_api
+from lucen_sdk.api.campaigns import update_campaign as update_campaign_api
 from lucen_sdk.api.datasets import list_dataset_episodes as list_dataset_episodes_api
 from lucen_sdk.api.datasets import put_dataset_meta as put_dataset_meta_api
 from lucen_sdk.api.devices import get_device_signing_key as get_device_signing_key_api
@@ -61,6 +63,7 @@ from lucen_sdk.api.files import (
 from lucen_sdk.api.files import (
     presign_upload as presign_upload_api,
 )
+from lucen_sdk.api.meta import get_capabilities as get_capabilities_api
 from lucen_sdk.api.meta import healthz as healthz_api
 from lucen_sdk.api.models import put_model_meta as put_model_meta_api
 from lucen_sdk.api.orgs import create_org as create_org_api
@@ -123,15 +126,24 @@ from lucen_sdk.api.runs import (
 from lucen_sdk.api.runs import (
     claim_run as claim_run_api,
 )
+from lucen_sdk.api.runs import (
+    compare_checkpoints as compare_checkpoints_api,
+)
 from lucen_sdk.api.runs import (
     create_run as create_run_api,
 )
 from lucen_sdk.api.runs import (
     estimate_run as estimate_run_api,
 )
+from lucen_sdk.api.runs import (
+    fork_run as fork_run_api,
+)
 from lucen_sdk.api.runs import (
     get_run as get_run_api,
 )
+from lucen_sdk.api.runs import (
+    get_run_curves as get_run_curves_api,
+)
 from lucen_sdk.api.runs import (
     import_run as import_run_api,
 )
@@ -155,6 +167,9 @@ from lucen_sdk.api.spend import get_spend_hold as get_spend_hold_api
 from lucen_sdk.api.spend import list_spend_holds as list_spend_holds_api
 from lucen_sdk.api.workspace import get_my_overview as get_my_overview_api
 from lucen_sdk.models import (
+    Campaign,
+    CampaignUpdate,
+    CheckpointComparison,
     CheckpointGateTable,
     CheckpointList,
     CompletedUpload,
@@ -227,8 +242,11 @@ from lucen_sdk.models import (
     Run,
     RunClaim,
     RunCreate,
+    RunCurves,
     RunEstimate,
     RunExecutor,
+    RunFork,
+    RunForkResult,
     RunImport,
     RunImportArtifacts,
     RunImportArtifactsScorecardJsonType0,
@@ -639,6 +657,22 @@ class HubClient:
         response = healthz_api.sync_detailed(client=self._sdk)
         return self._expect(response, HealthResponse, action="Reaching the hub")
 
+    def studio_stills(self) -> str:
+        """S2: `getCapabilities.studio_stills` — `hosted` | `local` | `none`.
+
+        `none` for a hub that predates the field, or one that cannot be asked:
+        the publisher then draws its own still, as before.
+        """
+        try:
+            response = get_capabilities_api.sync_detailed(client=self._sdk)
+        except Exception:  # a still is never worth failing a publish over
+            return "none"
+        parsed = response.parsed if int(response.status_code) == 200 else None
+        value = getattr(parsed, "studio_stills", None)
+        if value is None or isinstance(value, Unset):
+            return "none"
+        return str(getattr(value, "value", value))
+
     def overview(self) -> MyOverview:
         """`GET /v1/me/overview` (UI-API): what is yours right now, in counts (`key:read`)."""
         response = get_my_overview_api.sync_detailed(client=self._sdk)
@@ -1215,6 +1249,21 @@ class HubClient:
             cursor = page.next_cursor
         return out[:limit]
 
+    def get_campaign(self, campaign: str) -> Campaign:
+        response = get_campaign_api.sync_detailed(campaign, client=self._sdk)
+        return self._expect(
+            response, Campaign, action=f"Reading campaign {campaign}", needs_scope="read"
+        )
+
+    def update_campaign(self, campaign: str, body: dict[str, Any]) -> Campaign:
+        """`updateCampaign` (C5's `unattended`): a key may narrow or switch off, never widen."""
+        response = update_campaign_api.sync_detailed(
+            campaign, client=self._sdk, body=CampaignUpdate.from_dict(body)
+        )
+        return self._expect(
+            response, Campaign, action=f"Changing campaign {campaign}", needs_scope="write"
+        )
+
     def cancel_spend_hold(self, hold_id: str) -> SpendHold:
         response = cancel_spend_hold_api.sync_detailed(hold_id, client=self._sdk)
         return self._expect(
@@ -1364,6 +1413,65 @@ class HubClient:
             needs_scope="read",
         )
 
+    def get_run_curves(
+        self,
+        run_id: str,
+        *,
+        keys: str | None = None,
+        max_points: int = 500,
+        parent: bool = False,
+    ) -> RunCurves:
+        """`GET /v1/runs/{id}/curves` (I1a): the run's curves, summaries and flags."""
+        response = get_run_curves_api.sync_detailed(
+            run_id,
+            client=self._sdk,
+            keys=keys if keys else UNSET,
+            max_points=max_points,
+            parent=parent,
+        )
+        return self._expect(
+            response, RunCurves, action=f"Reading the curves of run {run_id}", needs_scope="read"
+        )
+
+    def compare_checkpoints(
+        self, run_id: str, step: int, other_run_id: str, other_step: int
+    ) -> CheckpointComparison:
+        """`GET /v1/runs/{id}/compare` (AG4): two checkpoints side by side."""
+        response = compare_checkpoints_api.sync_detailed(
+            run_id, client=self._sdk, step=step, other_run_id=other_run_id, other_step=other_step
+        )
+        return self._expect(
+            response,
+            CheckpointComparison,
+            action=f"Comparing {run_id}@{step} with {other_run_id}@{other_step}",
+            needs_scope="read",
+        )
+
+    def fork_run(
+        self,
+        run_id: str,
+        body: dict[str, Any],
+        *,
+        dry_run: bool,
+        idempotency_key: str | None = None,
+    ) -> RunForkResult:
+        """`POST /v1/runs/{id}/fork` (AG4): a child with one declared change."""
+        response = fork_run_api.sync_detailed(
+            run_id,
+            client=self._sdk,
+            body=RunFork.from_dict(body),
+            dry_run=dry_run,
+            idempotency_key=idempotency_key if idempotency_key else UNSET,
+        )
+        if int(response.status_code) == 202 and isinstance(response.parsed, SpendHold):
+            raise SpendHeld(response.parsed, web=self.hold_url(response.parsed.id))
+        return self._expect(
+            response,
+            RunForkResult,
+            action=f"Forking run {run_id}" + (" (dry run)" if dry_run else ""),
+            needs_scope="train",
+        )
+
     # -- kind-specific reads/writes the runner needs ------------------------
 
     # -- endpoints (M15): create / estimate / list / get / stop, and the serve protocol

lucen_cli-0.1.4/src/lucen_cli/cmd_campaigns.py

@@ -0,0 +1,119 @@
+"""`lucen campaigns` — what a key may do to a campaign's unattended rounds (C5).
+
+A person switches a campaign's unattended rounds on, for a stretch of rounds
+and hours, on the campaign's page; continuing a stretch the hub paused is
+theirs too. Both are a signed-in person's decision, so this command does
+neither. It can only **narrow** the stretch (fewer rounds, fewer hours) or
+switch it **off** — what any key with write access may do — and print where it
+stands.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+import typer
+
+from lucen_cli.context import AppState
+from lucen_cli.errors import EXIT_REFUSED, CLIError
+from lucen_cli.group import LucenGroup
+from lucen_cli.output import emit_json, stdout
+
+app = typer.Typer(
+    cls=LucenGroup,
+    help="A campaign's unattended rounds: see where the stretch stands, narrow it, or turn it off.",
+    no_args_is_help=True,
+)
+
+JsonOpt = Annotated[bool, typer.Option("--json", help="Machine-readable output.")]
+
+PERSON_ONLY = (
+    "Turning unattended rounds on, giving the stretch more rounds or hours, and continuing a "
+    "paused stretch are a signed-in person's decisions."
+)
+
+
+def stretch_line(unattended: dict[str, Any], predictions: dict[str, Any]) -> str:
+    """`Unattended: round 3 of 8 · paused (no_pass): …` — one line, as the page says it."""
+    hits = predictions.get("hits", 0)
+    misses = predictions.get("misses", 0)
+    scored = f"predictions {hits} hit, {misses} missed"
+    if not unattended.get("enabled"):
+        return f"Unattended rounds are off (stretch {unattended.get('max_rounds')} rounds, " + (
+            f"{unattended.get('max_hours'):g} hours when a person turns them on); {scored}."
+        )
+    line = (
+        f"Unattended: round {unattended.get('rounds_this_stretch', 0)} of "
+        f"{unattended.get('max_rounds')}, at most {unattended.get('max_hours'):g} hours"
+    )
+    paused = unattended.get("paused")
+    if paused:
+        return f"{line}; paused ({paused.get('code')}): {paused.get('reason')} {scored}."
+    return f"{line}; {scored}."
+
+
+@app.command("unattended")
+def unattended(
+    ctx: typer.Context,
+    campaign: Annotated[str, typer.Argument(metavar="CAMPAIGN", help="Its id or slug.")],
+    off: Annotated[bool, typer.Option("--off", help="Switch unattended rounds off.")] = False,
+    max_rounds: Annotated[
+        int | None,
+        typer.Option("--max-rounds", min=1, max=100, help="Fewer rounds per stretch."),
+    ] = None,
+    max_hours: Annotated[
+        float | None,
+        typer.Option("--max-hours", min=0.01, max=168, help="Fewer hours per stretch."),
+    ] = None,
+    as_json: JsonOpt = False,
+) -> None:
+    """Show a campaign's unattended stretch, narrow it, or switch it off.
+
+    With no option it prints where the stretch stands. A key may lower
+    `--max-rounds` / `--max-hours` or pass `--off`; turning it on, raising
+    either number and continuing a paused stretch happen on the campaign's
+    page, signed in.
+    """
+    state = ctx.ensure_object(AppState)
+    with state.client(require_auth=True) as client:
+        found = client.get_campaign(campaign).to_dict()
+        current = dict(found.get("unattended") or {})
+        body: dict[str, Any] = {}
+        if off:
+            body["enabled"] = False
+        if max_rounds is not None:
+            if max_rounds > int(current.get("max_rounds") or 0):
+                raise CLIError(
+                    f"`--max-rounds {max_rounds}` is more than the stretch's "
+                    f"{current.get('max_rounds')}: that widens it.",
+                    hint=f"{PERSON_ONLY} Do it on the campaign's page.",
+                    exit_code=EXIT_REFUSED,
+                )
+            body["max_rounds"] = max_rounds
+        if max_hours is not None:
+            if max_hours > float(current.get("max_hours") or 0):
+                raise CLIError(
+                    f"`--max-hours {max_hours:g}` is more than the stretch's "
+                    f"{current.get('max_hours'):g}: that widens it.",
+                    hint=f"{PERSON_ONLY} Do it on the campaign's page.",
+                    exit_code=EXIT_REFUSED,
+                )
+            body["max_hours"] = max_hours
+        if body:
+            found = client.update_campaign(found["id"], {"unattended": body}).to_dict()
+    mode = dict(found.get("unattended") or {})
+    if as_json:
+        emit_json(
+            {
+                "campaign": found.get("id"),
+                "slug": found.get("slug"),
+                "unattended": mode,
+                "predictions": found.get("predictions") or {},
+                "changed": bool(body),
+            }
+        )
+        return
+    stdout.print(f"{found.get('slug')} ({found.get('id')})", markup=False)
+    stdout.print("  " + stretch_line(mode, dict(found.get("predictions") or {})), markup=False)
+    if mode.get("paused"):
+        stdout.print(f"  {PERSON_ONLY}", markup=False)

{lucen_cli-0.1.2 → lucen_cli-0.1.4}/src/lucen_cli/cmd_datasets.py

@@ -183,8 +183,10 @@ def render_import(result: ImportResult, *, as_json: bool) -> None:
     if result.readme_written:
         notes.append("README.md written with the provenance (the dataset shipped none)")
     if result.description_set:
-        notes.append("description set to the provenance")
+        notes.append("description set")
     if notes:
         stdout.print("  " + "; ".join(notes) + ".", markup=False)
+    if result.description_set:
+        stdout.print(f"  Description: {result.plan.description}", markup=False)
     page = f"/{result.repo}?tab=episodes"
     stdout.print((result.url + "?tab=episodes") if result.url else no_link(page), markup=False)

{lucen_cli-0.1.2 → lucen_cli-0.1.4}/src/lucen_cli/cmd_model.py

@@ -165,7 +165,7 @@ def stamp(
     stdout.print(
         f"  contract                obs {contract['obs_dim']} = "
         f"{' + '.join(b['name'] for b in contract['obs_spec'])}; action "
-        f"{contract['action_dim']} ({contract['action_semantics']}); "
+        f"{contract['action_dim']} ({_semantics_line(contract)}); "
         f"{contract['control_rate_hz']:g} Hz; control_class {manifest['control_class']}"
     )
     if unchecked:
@@ -173,3 +173,14 @@ def stamp(
             f"  [yellow]not checked[/yellow]            the ONNX's {' and '.join(unchecked)} "
             "width is symbolic, so it could not be compared with the contract"
         )
+
+
+def _semantics_line(contract: dict[str, Any]) -> str:
+    """`position_offset`, or `mixed: 8 position_offset, 2 torque` (T2)."""
+    layout = contract.get("action_semantics_vec")
+    if not isinstance(layout, list):
+        return str(contract["action_semantics"])
+    counts: dict[str, int] = {}
+    for semantics in layout:
+        counts[str(semantics)] = counts.get(str(semantics), 0) + 1
+    return f"{contract['action_semantics']}: " + ", ".join(f"{n} {s}" for s, n in counts.items())

{lucen_cli-0.1.2 → lucen_cli-0.1.4}/src/lucen_cli/cmd_quickstart.py

@@ -195,12 +195,12 @@ def plan_no_file() -> list[Step]:
     return [
         Step(
             "lucen repo ls --kind robot",
-            "The hub's robots (Laika, Go2, UR5e, SO-101 and more), each with a validated "
+            "The hub's robots (Lucen Biped, Go2, UR5e, SO-101 and more), each with a validated "
             "card and interface; pick one.",
         ),
         Step(
             "lucen runs create --template ppo_mujoco --robot lucen/laika --executor worker",
-            "Queue a PPO run on Laika, the hub's own biped; it waits for a runner.",
+            "Queue a PPO run on Lucen Biped, the hub's own biped; it waits for a runner.",
         ),
         Step(
             "lucen worker run",

{lucen_cli-0.1.2 → lucen_cli-0.1.4}/src/lucen_cli/cmd_robot.py

@@ -795,7 +795,9 @@ def card_get(
         card = get_card(client, RepoTarget.parse(repo))
     if output is not None and not as_json:
         editable = {
-            k: v for k, v in card.items() if k not in ("interface_fingerprint", "updated_at")
+            k: v
+            for k, v in card.items()
+            if k not in ("interface_fingerprint", "updated_at", "stills")
         }
         output.write_text(
             json.dumps(editable, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"
@@ -831,7 +833,7 @@ def card_set(
             f"{file} must hold a JSON object.",
             hint="`lucen robot card get OWNER/SLUG -o card.json` writes one in the right shape.",
         )
-    for key in ("needs_you", "interface_fingerprint", "updated_at"):
+    for key in ("needs_you", "interface_fingerprint", "updated_at", "stills"):
         card.pop(key, None)
     target = RepoTarget.parse(repo)
     try:

{lucen_cli-0.1.2 → lucen_cli-0.1.4}/src/lucen_cli/cmd_runs.py

@@ -513,6 +513,221 @@ def list_checkpoints(
     render_checkpoints(page, as_json=as_json)
 
 
+@app.command("curves")
+def run_curves(
+    ctx: typer.Context,
+    run_id: Annotated[str, typer.Argument(metavar="RUN_ID")],
+    keys: Annotated[
+        str | None,
+        typer.Option(
+            "--keys",
+            help="Comma-separated series: the hub's names (return, reward/action_rate) or the "
+            "logged ones (Train/mean_reward). Default: every known series.",
+        ),
+    ] = None,
+    parent: Annotated[
+        bool, typer.Option("--parent/--no-parent", help="Compare with the parent run.")
+    ] = True,
+    max_points: Annotated[
+        int, typer.Option("--max-points", min=2, max=5000, help="Points per series (--json).")
+    ] = 500,
+    as_json: JsonOpt = False,
+) -> None:
+    """A run's learning curves: last value, slope, plateau, the change against its parent."""
+    from lucen_cli.curves_view import render_curves
+
+    state = ctx.ensure_object(AppState)
+    with state.client(require_auth=True) as client:
+        curves = client.get_run_curves(run_id, keys=keys, max_points=max_points, parent=parent)
+    render_curves(curves, as_json=as_json)
+
+
+@app.command("gates")
+def run_gates(
+    ctx: typer.Context,
+    run_id: Annotated[str, typer.Argument(metavar="RUN_ID")],
+    step: Annotated[int | None, typer.Option("--step", min=0, help="One checkpoint.")] = None,
+    cells: Annotated[
+        bool, typer.Option("--cells", help="Each test's result, measured value and seeds upright.")
+    ] = False,
+    as_json: JsonOpt = False,
+) -> None:
+    """The sim tests a run's checkpoints got while it trained: one line per checkpoint."""
+    from lucen_cli.gates_view import render_gates
+
+    state = ctx.ensure_object(AppState)
+    with state.client(require_auth=True) as client:
+        table = client.get_run_gates(run_id).to_dict()
+    render_gates(table, step=step, cells=cells or step is not None, as_json=as_json)
+
+
+@app.command("wait")
+def run_wait(
+    ctx: typer.Context,
+    run_id: Annotated[str, typer.Argument(metavar="RUN_ID")],
+    until: Annotated[
+        str,
+        typer.Option(
+            "--for",
+            help="`gate`: the next sim test (or the one at --step). `finish`: the run's end.",
+        ),
+    ] = "gate",
+    step: Annotated[
+        int | None, typer.Option("--step", min=0, help="Wait for this checkpoint's test.")
+    ] = None,
+    timeout: Annotated[
+        float, typer.Option("--timeout", min=1, help="Seconds before giving up.")
+    ] = 600,
+    poll: Annotated[
+        float, typer.Option("--poll", min=1, max=60, help="Seconds between reads.")
+    ] = 5,
+    as_json: JsonOpt = False,
+) -> None:
+    """Wait for a run's sim test or its end. Exit 0 when it happened, 2 canceled, 1 otherwise.
+
+    The sentence says which: the gate landed (with its line), the run ended with no
+    test still coming, or the timeout passed.
+    """
+    from lucen_cli.gates_view import wait, wait_exit_code
+
+    if until not in ("gate", "finish"):
+        raise CLIError(
+            f"--for is `gate` or `finish`, not {until!r}.",
+            hint="`gate` waits for a sim test; `finish` for the run's end.",
+        )
+    if step is not None and until != "gate":
+        raise CLIError("--step goes with --for gate.", hint="Drop --step, or wait for a gate.")
+    state = ctx.ensure_object(AppState)
+    with state.client(require_auth=True) as client:
+        result = wait(client, run_id, until=until, step=step, timeout_s=timeout, poll_s=poll)
+    if as_json:
+        emit_json(result)
+    else:
+        stdout.print(str(result["said"]), markup=False)
+    code = wait_exit_code(result)
+    if code:
+        raise typer.Exit(code)
+
+
+@app.command("compare")
+def run_compare(
+    ctx: typer.Context,
+    a: Annotated[str, typer.Argument(metavar="RUN@STEP", help="Checkpoint A.")],
+    b: Annotated[str, typer.Argument(metavar="RUN@STEP", help="Checkpoint B (any run).")],
+    as_json: JsonOpt = False,
+) -> None:
+    """Two checkpoints side by side: sim tests, reward terms, the config diff, a card scored."""
+    from lucen_cli.gates_view import parse_ref, render_compare
+
+    run_a, step_a = parse_ref(a, "A")
+    run_b, step_b = parse_ref(b, "B")
+    state = ctx.ensure_object(AppState)
+    with state.client(require_auth=True) as client:
+        body = client.compare_checkpoints(run_a, step_a, run_b, step_b).to_dict()
+    render_compare(body, as_json=as_json)
+
+
+def _parse_set(value: str) -> tuple[str, Any]:
+    path, sep, raw = value.partition("=")
+    if not sep or not path.strip():
+        raise CLIError(
+            f"--set is PATH=VALUE, e.g. task.rewards.action_rate=-0.02; got {value!r}.",
+            hint="The path is a resolved-config key, as the run page's Config tab prints it.",
+        )
+    try:
+        parsed: Any = json.loads(raw)
+    except ValueError:
+        parsed = raw
+    return path.strip(), parsed
+
+
+def _parse_prediction(value: str) -> dict[str, Any]:
+    parts = value.split(":")
+    if len(parts) not in (2, 3) or parts[1] not in ("up", "same", "down"):
+        raise CLIError(
+            f"--predict is METRIC:DIRECTION[:VALUE], e.g. gates_passed:up:3; got {value!r}.",
+            hint="METRIC is gates_passed or one of the parent's sim tests; DIRECTION up|same|down.",
+        )
+    out: dict[str, Any] = {"metric": parts[0], "direction": parts[1]}
+    if len(parts) == 3:
+        try:
+            out["value"] = float(parts[2])
+        except ValueError as exc:
+            raise CLIError(f"--predict's value {parts[2]!r} is not a number.") from exc
+    return out
+
+
+@app.command("fork")
+def run_fork(
+    ctx: typer.Context,
+    run_id: Annotated[str, typer.Argument(metavar="RUN_ID")],
+    set_: Annotated[
+        str, typer.Option("--set", help="The ONE change, PATH=VALUE (VALUE is JSON or text).")
+    ],
+    step: Annotated[
+        int | None, typer.Option("--step", min=0, help="The checkpoint to resume from.")
+    ] = None,
+    scratch: Annotated[
+        bool, typer.Option("--from-scratch", help="Keep the contract, not the weights.")
+    ] = False,
+    predict: Annotated[
+        str | None, typer.Option("--predict", help="The card: METRIC:DIRECTION[:VALUE].")
+    ] = None,
+    hypothesis: Annotated[
+        str | None, typer.Option("--hypothesis", help="The card's one sentence.")
+    ] = None,
+    iterations: Annotated[
+        int | None, typer.Option("--iterations", min=1, help="How long the child trains.")
+    ] = None,
+    executor: Annotated[
+        str | None,
+        typer.Option(
+            "--executor", help="Where the child runs: worker or modal. Default: the parent's."
+        ),
+    ] = None,
+    gpu: Annotated[str | None, typer.Option("--gpu", help="The GPU tier on modal.")] = None,
+    dry_run: Annotated[
+        bool, typer.Option("--dry-run", help="Compose and check the child; create nothing.")
+    ] = False,
+    idempotency_key: Annotated[
+        str | None, typer.Option("--idempotency-key", help="Retry safely with the same key.")
+    ] = None,
+    as_json: JsonOpt = False,
+) -> None:
+    """A child of RUN with ONE config change, composed and checked by the hub."""
+    from lucen_cli.gates_view import render_fork
+
+    if (step is None) == (not scratch):
+        raise CLIError(
+            "Name the checkpoint with --step N, or start over with --from-scratch.",
+            hint="`lucen runs gates RUN` lists the tested steps.",
+        )
+    path, value = _parse_set(set_)
+    body: dict[str, Any] = {"checkpoint_step": step, "set": {path: value}}
+    if predict is not None:
+        body["card"] = {
+            "hypothesis": hypothesis or f"{path} -> {value}",
+            "prediction": _parse_prediction(predict),
+        }
+    for key, chosen in (("iterations", iterations), ("executor", executor), ("gpu", gpu)):
+        if chosen is not None:
+            body[key] = chosen
+    state = ctx.ensure_object(AppState)
+    client = state.client(require_auth=True)
+    try:
+        result = client.fork_run(
+            run_id, body, dry_run=dry_run, idempotency_key=idempotency_key
+        ).to_dict()
+    except SpendHeld as held:
+        render_hold(held.hold, web=held.web, as_json=as_json, held=True)
+        return
+    finally:
+        client.close()
+    render_fork(result, as_json=as_json)
+    if dry_run and result.get("refusals"):
+        raise typer.Exit(2)
+
+
 @app.command("import")
 def import_run(
     ctx: typer.Context,