manifold-cli 0.0.39__py3-none-any.whl

manifold_cli/commands/policy.py

@@ -0,0 +1,749 @@
+"""The `manifold policy` command group."""
+
+import asyncio
+import contextlib
+import functools
+import os
+import signal
+import socket
+import time
+from pathlib import Path
+from typing import Annotated, Any
+from uuid import uuid4
+
+import typer
+from pydantic import ValidationError
+from rich.console import Console
+from rich.markup import escape
+from rich.table import Table
+from rich.text import Text
+
+from manifold_cli.bridge import run_bridge
+from manifold_cli.clients.manifold import ManifoldApiClient
+from manifold_cli.commands.organization import (
+    ORGANIZATION_CALL_ERRORS,
+    exit_for_call_error,
+    resolve_owner,
+)
+from manifold_cli.commands.table import catalog_table, print_table, terminal_width
+from manifold_cli.dependencies import Dependencies, make_in_memory_runner_client
+from manifold_cli.models.catalog import (
+    CatalogRegisterError,
+    InvalidImageError,
+    InvalidReferenceError,
+    Visibility,
+    join_versioned_ref,
+    split_ref,
+    split_versioned_ref,
+)
+from manifold_cli.models.errors import RunnerCredentialRejectedError
+from manifold_cli.models.policy import PolicyNotFoundError
+from manifold_cli.models.run import AssignmentDispatch
+from manifold_cli.models.runner import (
+    MintedRunner,
+    RunnerNameTakenError,
+    RunnerSource,
+)
+from manifold_cli.models.runner_home import BoxFacts, PolicyTransport
+from manifold_cli.runner.current_dispatch import CurrentDispatch
+from manifold_cli.runner.daemon import (
+    BRIDGE_POLL_SECONDS,
+    POLL_TIMEOUT_SECONDS,
+    run_daemon,
+)
+from manifold_cli.runner.gpu import gpu_facts
+from manifold_cli.runner.policy import run_served_policy_side
+from manifold_cli.runner.process import AsyncioSpawner
+from manifold_cli.runner.resource_usage import reporting_resource_usage
+from manifold_cli.runner.served import ServedPolicy
+from manifold_cli.runner.signature import read_signature
+from manifold_cli.runner.source import serve_source
+from manifold_cli.runner.stages import (
+    callout,
+    failed,
+    finished,
+    started,
+    stopped,
+)
+from manifold_cli.transport import DEFAULT_TRANSPORTS, TcpConnector, TransportError
+from manifold_cli.transport.diagnostics import serve_echo
+from manifold_cli.transport.tcp import split_host_port
+
+DEFAULT_SERVE_TARGET = "tcp:127.0.0.1:0"
+
+# Length of the random suffix added when the hostname is already taken.
+SERVE_NAME_SUFFIX_LENGTH = 6
+
+
+def register(app: typer.Typer, deps: Dependencies) -> None:
+    console = Console()
+    policy_app = typer.Typer(help="Serve and manage policies.", no_args_is_help=True)
+
+    @policy_app.command("list")
+    def list_policies() -> None:
+        """List the policies you can see."""
+        try:
+            policies = deps.policy_service.list_policies()
+        except ORGANIZATION_CALL_ERRORS as exc:
+            raise exit_for_call_error(console, exc) from exc
+        if len(policies) == 0:
+            console.print("There are no policies yet.")
+            return
+        print_table(console, catalog_table(policies, terminal_width(console)))
+
+    @policy_app.command()
+    def versions(
+        policy: Annotated[
+            str,
+            typer.Argument(
+                help="Policy identifier, or <org>/<identifier> to specify its owner."
+            ),
+        ],
+    ) -> None:
+        """List the versions of a policy, newest first."""
+        try:
+            owner, slug = split_ref(policy)
+        except InvalidReferenceError as exc:
+            console.print(f"[red]{escape(str(exc))}[/red]")
+            raise typer.Exit(1) from exc
+        # A qualified reference names its owner outright. A bare slug resolves
+        # the way `run submit` resolves one: the caller's own policy first, then
+        # a public policy of that slug.
+        list_versions = (
+            deps.policy_service.list_versions
+            if owner is not None
+            else deps.policy_service.list_own_or_public_versions
+        )
+        if owner is None:
+            try:
+                owner = resolve_owner(console, deps.organization_service)
+            except ORGANIZATION_CALL_ERRORS as exc:
+                raise exit_for_call_error(console, exc) from exc
+        try:
+            found = list_versions(slug, owner)
+        except PolicyNotFoundError as exc:
+            console.print(f"[red]{escape(str(exc))}[/red]")
+            raise typer.Exit(1) from exc
+        except ORGANIZATION_CALL_ERRORS as exc:
+            raise exit_for_call_error(console, exc) from exc
+        if len(found) == 0:
+            console.print(f"'{escape(policy)}' has no versions yet.")
+            return
+        table = Table(box=None, pad_edge=False)
+        table.add_column("Version")
+        table.add_column("Adapter", style="dim")
+        for version in found:
+            table.add_row(Text(version.version, style="bold"), version.adapter.value)
+        print_table(console, table)
+
+    @policy_app.command()
+    def init(
+        policy: Annotated[
+            str,
+            typer.Argument(
+                help="Policy identifier to register the image under, "
+                "or <org>/<identifier> to specify the organization that owns it."
+            ),
+        ],
+        image: Annotated[
+            str,
+            typer.Option(
+                "--image",
+                help="Container image, e.g. ghcr.io/bifrost/smolvla:0.1.0. "
+                "Its tag is the version this registers.",
+            ),
+        ],
+        minimum_gpu_memory_gb: Annotated[
+            int,
+            typer.Option(
+                "--minimum-gpu-memory-gb",
+                min=0,
+                help="Minimum memory required on one GPU. Set to 0 to allow "
+                "placement on runners without a GPU.",
+            ),
+        ],
+        env: Annotated[
+            list[str] | None,
+            typer.Option(
+                "--env",
+                help="Environment variable as KEY=VALUE. Repeat for each variable.",
+            ),
+        ] = None,
+        minimum_driver_major: Annotated[
+            int | None,
+            typer.Option(
+                "--minimum-driver-major",
+                min=1,
+                help="Minimum NVIDIA driver major version required on a "
+                "runner. Omit to leave the lower bound open.",
+            ),
+        ] = None,
+        maximum_driver_major: Annotated[
+            int | None,
+            typer.Option(
+                "--maximum-driver-major",
+                min=1,
+                help="Maximum NVIDIA driver major version allowed on a "
+                "runner. Omit to leave the upper bound open.",
+            ),
+        ] = None,
+        minimum_gpu_count: Annotated[
+            int | None,
+            typer.Option(
+                "--minimum-gpu-count",
+                min=0,
+                help="Minimum number of GPUs required on one runner. If omitted, "
+                "the default is 1, or 0 when --minimum-gpu-memory-gb is 0.",
+            ),
+        ] = None,
+        display_name: Annotated[
+            str | None,
+            typer.Option(
+                "--display-name",
+                help="Name shown in `policy list`. Left off, an existing "
+                "policy keeps the name it has and a new one uses its identifier.",
+            ),
+        ] = None,
+        visibility: Annotated[
+            Visibility | None,
+            typer.Option(
+                "--visibility",
+                help="Who can read the policy. Left off, an existing policy "
+                "keeps the visibility it has and a new one is visible to its "
+                "organization.",
+            ),
+        ] = None,
+    ) -> None:
+        """Register a container image as a version of a policy."""
+        environment = _parse_environment(env)
+        try:
+            owner, slug = split_ref(policy)
+        except InvalidReferenceError as exc:
+            console.print(f"[red]{escape(str(exc))}[/red]")
+            raise typer.Exit(1) from exc
+        try:
+            if owner is None:
+                owner = resolve_owner(console, deps.organization_service)
+            version = deps.policy_service.register_container_version(
+                slug,
+                owner,
+                image=image,
+                environment=environment,
+                minimum_gpu_memory_gb=minimum_gpu_memory_gb,
+                minimum_driver_major=minimum_driver_major,
+                maximum_driver_major=maximum_driver_major,
+                minimum_gpu_count=minimum_gpu_count,
+                display_name=display_name,
+                visibility=visibility,
+            )
+        except (
+            InvalidImageError,
+            CatalogRegisterError,
+            PolicyNotFoundError,
+        ) as exc:
+            console.print(f"[red]{escape(str(exc))}[/red]")
+            raise typer.Exit(1) from exc
+        except ORGANIZATION_CALL_ERRORS as exc:
+            raise exit_for_call_error(console, exc) from exc
+        console.print(
+            f"[green]✓ Registered[/green] [bold]{escape(policy)}[/bold] "
+            f"[bold]{escape(version.version)}[/bold] "
+            f"[dim]{version.adapter.value}[/dim]"
+        )
+        console.print(f"  {escape(image)}")
+        console.print(
+            f"Run it with: manifold run submit {escape(policy)} <benchmark> --name NAME"
+        )
+
+    @policy_app.command()
+    def delete(
+        policy: Annotated[
+            str,
+            typer.Argument(
+                help="Policy to delete, as [<org>/]<identifier>[:<version>], for "
+                "example my-policy:0.0.1. With a version, only that "
+                "version is deleted."
+            ),
+        ],
+    ) -> None:
+        """Delete a policy, or one version of it.
+
+        A deleted policy or version is left out of listings and cannot be used
+        in new runs. `run get` still shows it on the runs that used it.
+        Registering it again restores it. A restored policy takes the display
+        name and visibility of that registration, not its earlier ones.
+        """
+        try:
+            owner, slug, version = split_versioned_ref(policy)
+        except InvalidReferenceError as exc:
+            console.print(f"[red]{escape(str(exc))}[/red]")
+            raise typer.Exit(1) from exc
+        try:
+            if owner is None:
+                owner = resolve_owner(console, deps.organization_service)
+            deps.policy_service.delete(slug, owner, version)
+        except PolicyNotFoundError as exc:
+            console.print(f"[red]{escape(str(exc))}[/red]")
+            raise typer.Exit(1) from exc
+        except ORGANIZATION_CALL_ERRORS as exc:
+            raise exit_for_call_error(console, exc) from exc
+        deleted = "Policy deleted" if version is None else "Policy version deleted"
+        console.print(
+            f"[green]✓ {deleted}[/green] "
+            f"[bold]{escape(join_versioned_ref(owner, slug, version))}[/bold]"
+        )
+
+    @policy_app.command(
+        context_settings={"allow_extra_args": True, "ignore_unknown_options": True}
+    )
+    def serve(
+        context: typer.Context,
+        policy: Annotated[
+            str | None,
+            typer.Argument(
+                help="Policy to serve, as [<org>/]<identifier>:<version>, for "
+                "example my-policy:0.0.1."
+            ),
+        ] = None,
+        echo: Annotated[
+            bool,
+            typer.Option("--echo", help="Serve a built-in echo policy (echoes bytes)."),
+        ] = False,
+        target: Annotated[
+            str,
+            typer.Option(
+                "--target",
+                help="Address for --echo to listen on, e.g. tcp:0.0.0.0:9000 or iroh.",
+            ),
+        ] = DEFAULT_SERVE_TARGET,
+    ) -> None:
+        """Serve a policy from this machine.
+
+        Put the command that starts your policy after `--`:
+
+            manifold policy serve pi05-libero:0.0.1 -- uv run serve.py
+
+        This starts the command and waits until your policy accepts
+        connections. Then it registers the policy version and this machine
+        with Manifold. The runs of this version that you submit go to this
+        machine, and the policy loads only once.
+
+        Press Ctrl-C to stop. This unregisters the machine and stops the
+        command.
+        """
+        if echo:
+            _serve_echo(console, target)
+            return
+        if policy is None:
+            console.print("[red]Name the policy to serve.[/red] For example:")
+            console.print("  manifold policy serve my-policy:0.0.1 -- COMMAND")
+            raise typer.Exit(1)
+        command = list(context.args)
+        if len(command) == 0:
+            console.print(
+                "[red]No command given.[/red] Put the command that starts your "
+                "policy after `--`, for example `-- uv run scripts/eval.py`."
+            )
+            raise typer.Exit(1)
+        _serve_policy(console, deps, policy, command=command)
+
+    @policy_app.command(hidden=True)
+    def bridge(
+        transport: Annotated[
+            str,
+            typer.Argument(
+                help="Listen target for our transport, e.g. tcp:0.0.0.0:9500 or iroh."
+            ),
+        ],
+        upstream: Annotated[
+            str,
+            typer.Option(
+                "--upstream", help="Local policy server to dial, as HOST:PORT."
+            ),
+        ],
+    ) -> None:
+        """Bridge a local policy server so it is reachable over our transport."""
+
+        async def run() -> None:
+            host, port = split_host_port(upstream)
+            listen_transport, rest = DEFAULT_TRANSPORTS.resolve(transport)
+            listener = await listen_transport.open_listener(rest)
+            console.print(
+                f"[green]Policy bridge up.[/green] "
+                f"Dial it at: [bold]{escape(listener.target)}[/bold]"
+            )
+            console.print(
+                f"Forwarding to policy server at [bold]{escape(host)}:{port}[/bold]."
+            )
+            console.print("Bridging... (press Ctrl-C to stop)")
+            await run_bridge(listener, TcpConnector(host, port))
+
+        try:
+            asyncio.run(run())
+        except KeyboardInterrupt:
+            console.print("\n[yellow]Policy bridge stopped.[/yellow]")
+        except (TransportError, OSError) as exc:
+            console.print(f"[red]Bridge failed:[/red] {escape(str(exc))}")
+            raise typer.Exit(1) from exc
+
+    app.add_typer(policy_app, name="policy")
+
+
+def _serve_echo(console: Console, target: str) -> None:
+    """Serve a policy that echoes bytes back, to test the transport."""
+
+    async def run() -> None:
+        transport, rest = DEFAULT_TRANSPORTS.resolve(target)
+        listener = await transport.open_listener(rest)
+        console.print(
+            "[green]Echo policy serving.[/green] In another shell, reach it with:"
+        )
+        console.print(
+            f"  [bold]manifold benchmark run {escape(listener.target)} --ping[/bold]"
+        )
+        console.print("Waiting for connections... (press Ctrl-C to stop)")
+        await serve_echo(listener, on_event=console.print)
+
+    try:
+        asyncio.run(run())
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Policy server stopped.[/yellow]")
+    except (TransportError, OSError) as exc:
+        console.print(f"[red]Serve failed:[/red] {escape(str(exc))}")
+        raise typer.Exit(1) from exc
+
+
+def _serve_policy(
+    console: Console,
+    deps: Dependencies,
+    policy: str,
+    *,
+    command: list[str],
+) -> None:
+    """Register the version, start the policy, then take runs once it is ready.
+
+    The version is registered first, so that a conflict fails before the
+    model loads, and so that a submit during the load says that the version
+    is not ready yet. Serve stops the policy process whenever it exits.
+    """
+    try:
+        owner, slug, version = split_versioned_ref(policy)
+    except InvalidReferenceError as exc:
+        console.print(f"[red]{escape(str(exc))}[/red]")
+        raise typer.Exit(1) from exc
+    if version is None:
+        console.print("[red]Name the version to serve.[/red] For example:")
+        console.print(f"  manifold policy serve {escape(policy)}:0.0.1 -- COMMAND")
+        raise typer.Exit(1)
+    try:
+        if owner is None:
+            owner = resolve_owner(console, deps.organization_service)
+        deps.policy_service.register_served_version(slug, owner, version=version)
+    except (CatalogRegisterError, PolicyNotFoundError) as exc:
+        console.print(f"[red]{escape(str(exc))}[/red]")
+        raise typer.Exit(1) from exc
+    except ORGANIZATION_CALL_ERRORS as exc:
+        raise exit_for_call_error(console, exc) from exc
+    name = f"[bold]{escape(slug)}:{escape(version)}[/bold]"
+    console.print(finished(f"Registered {name}"))
+    # A shell without a terminal starts a background command with SIGINT
+    # ignored, and Python keeps that setting. Serve stops on SIGINT: on
+    # Ctrl-C, on `kill -INT`, and when the policy process exits. So it puts
+    # the default handler back.
+    if signal.getsignal(signal.SIGINT) == signal.SIG_IGN:
+        signal.signal(signal.SIGINT, signal.default_int_handler)
+    console.print(started(f"Starting {name}"))
+    try:
+        served = ServedPolicy.start(command)
+    except OSError as exc:
+        console.print(failed("Could not start your command", detail=escape(str(exc))))
+        raise typer.Exit(1) from exc
+    try:
+        _serve_started_policy(
+            console,
+            deps,
+            served,
+            policy,
+            owner=owner,
+            slug=slug,
+            version=version,
+            source=serve_source(command, Path.cwd()),
+        )
+    finally:
+        served.stop()
+
+
+def _serve_started_policy(
+    console: Console,
+    deps: Dependencies,
+    served: ServedPolicy,
+    policy: str,
+    *,
+    owner: str,
+    slug: str,
+    version: str,
+    source: RunnerSource,
+) -> None:
+    """Wait until the policy is ready, register this machine, then take runs.
+
+    The runner is registered only after the policy accepts connections. So
+    when a submit finds a registered runner, the policy behind it is ready.
+    """
+    began = time.monotonic()
+    try:
+        ready = asyncio.run(served.wait_until_ready())
+    except TimeoutError as exc:
+        console.print(failed(escape(str(exc))))
+        raise typer.Exit(1) from exc
+    except KeyboardInterrupt:
+        console.print("\n" + stopped("Policy server stopped"))
+        return
+    loading_s = time.monotonic() - began
+    if not ready:
+        console.print(
+            failed(
+                f"Your policy process exited with code {served.exit_code} "
+                "before it was ready",
+                elapsed_s=loading_s,
+            )
+        )
+        raise typer.Exit(1)
+    console.print(
+        finished(
+            "Policy loaded",
+            elapsed_s=loading_s,
+            detail=f"Listening on {served.wire.address}",
+        )
+    )
+    try:
+        served_signature = asyncio.run(read_signature(served.wire))
+    except ValidationError as exc:
+        console.print(
+            failed(
+                "Your policy sent its serving script in the wrong format",
+                detail=escape(str(exc)),
+            )
+        )
+        raise typer.Exit(1) from exc
+    signature = None
+    if served_signature is not None:
+        signature = served_signature.signature
+        source = source.model_copy(
+            update={
+                "sdk_version": served_signature.sdk_version,
+                "script": served_signature.script,
+            }
+        )
+    try:
+        minted = _register_serving_runner(
+            console,
+            deps,
+            owner,
+            policy=slug,
+            version=version,
+            source=source,
+            signature=signature,
+        )
+    except (CatalogRegisterError, PolicyNotFoundError) as exc:
+        console.print(f"[red]{escape(str(exc))}[/red]")
+        raise typer.Exit(1) from exc
+    except ORGANIZATION_CALL_ERRORS as exc:
+        raise exit_for_call_error(console, exc) from exc
+    console.print(
+        finished(
+            "Registered this machine as runner "
+            f"[bold]{escape(minted.runner.name)}[/bold]"
+        )
+    )
+    console.print(
+        finished(f"Ready. Serving [bold]{escape(slug)}:{escape(version)}[/bold]")
+    )
+    console.print(
+        callout(
+            "To submit a run, in another shell:",
+            f"  [bold]manifold run submit {escape(policy)} <benchmark> "
+            "--name NAME[/bold]",
+        )
+    )
+    console.print("[dim]Waiting for work... (press Ctrl-C to stop)[/dim]")
+    _run_until_stopped(console, deps, minted, served)
+
+
+def _register_serving_runner(
+    console: Console,
+    deps: Dependencies,
+    owner: str,
+    *,
+    policy: str,
+    version: str,
+    source: RunnerSource,
+    signature: dict[str, Any] | None,
+) -> MintedRunner:
+    """Register this machine as a runner named after its hostname.
+
+    If the name is taken, retry once with a random suffix. The name is taken
+    when another `manifold policy serve` runs on this machine, when an earlier
+    one was killed before it unregistered, or when a runner in another
+    organization uses the name.
+    """
+    name = socket.gethostname() or "workstation"
+    gpu_devices = gpu_facts().devices
+    try:
+        return deps.runner_service.register_serving(
+            name,
+            owner,
+            policy=policy,
+            version=version,
+            gpu_devices=gpu_devices,
+            source=source,
+            signature=signature,
+        )
+    except RunnerNameTakenError:
+        unique = f"{name}-{uuid4().hex[:SERVE_NAME_SUFFIX_LENGTH]}"
+        return deps.runner_service.register_serving(
+            unique,
+            owner,
+            policy=policy,
+            version=version,
+            gpu_devices=gpu_devices,
+            source=source,
+            signature=signature,
+        )
+
+
+def _run_until_stopped(
+    console: Console, deps: Dependencies, minted: MintedRunner, served: ServedPolicy
+) -> None:
+    """Run the runner loop until Ctrl-C or until the policy exits, then unregister.
+
+    When the policy process exits, serve sends itself SIGINT. The runner loop
+    may be waiting on a long poll, and SIGINT is what interrupts that wait.
+
+    Ctrl-C during a run cancels the run. When the policy process exited, the
+    policy side reports the exit instead.
+    """
+    client = make_in_memory_runner_client(minted.token, deps.manifold_api_url)
+    current_dispatch = CurrentDispatch()
+    try:
+        # A SIGINT outside the loop's waits for work and its sides raises
+        # KeyboardInterrupt. The policy may already have exited during
+        # registration, and then on_exit sends SIGINT immediately, so call
+        # `served.on_exit` inside the `suppress`.
+        with (
+            contextlib.suppress(KeyboardInterrupt),
+            reporting_resource_usage(
+                client=client,
+                current_dispatch=current_dispatch,
+                docker=None,
+                log=console.print,
+            ),
+        ):
+            served.on_exit(lambda _code: os.kill(os.getpid(), signal.SIGINT))
+            run_daemon(
+                client=client,
+                spawner=AsyncioSpawner(),
+                box=BoxFacts(
+                    gpu_devices=[],
+                    cache_dir=None,
+                    advertise_host=None,
+                    # IROH, because the benchmark runner may not be able to reach
+                    # this machine.
+                    # TODO: This fixes the transport when the runner is created.
+                    # That only suits one-time runners like this one, which last
+                    # for one CLI process. Do not do this for registered runners.
+                    # Pick their transport when a run starts, so that a box can
+                    # move to TCP once the fleet can reach it, for example over a
+                    # VPN.
+                    policy_transport=PolicyTransport.IROH,
+                ),
+                poll_timeout_s=POLL_TIMEOUT_SECONDS,
+                bridge_poll_s=BRIDGE_POLL_SECONDS,
+                current_dispatch=current_dispatch,
+                stop_signal=signal.SIGINT,
+                start_runner=_send_nothing,
+                stop_runner=_send_nothing,
+                stop_side=functools.partial(
+                    _cancel_served_run, console=console, client=client, served=served
+                ),
+                # The runner copies its lines into the run's log, and the app shows
+                # when a run starts and ends. So the terminal skips them.
+                log=_discard,
+                policy_side=functools.partial(run_served_policy_side, served=served),
+            )
+        exit_code = served.exit_code
+        if exit_code is None:
+            console.print("\n" + stopped("Policy server stopped"))
+    except RunnerCredentialRejectedError as exc:
+        console.print(f"[red]{escape(str(exc))}[/red]")
+        console.print("This runner was revoked while serving.")
+        raise typer.Exit(1) from exc
+    finally:
+        # Serve is stopping, so a policy that exits from here on is expected.
+        served.ignore_exit()
+        _release(console, client)
+        client.close()
+    if exit_code is not None:
+        console.print(failed(f"Your policy process exited with code {exit_code}"))
+        raise typer.Exit(1)
+
+
+def _send_nothing() -> None:
+    """Stand in for the start and stop requests. A serving runner does not
+    send them: placement chooses it by the version it serves."""
+
+
+def _cancel_served_run(
+    dispatch: AssignmentDispatch,
+    *,
+    console: Console,
+    client: ManifoldApiClient,
+    served: ServedPolicy,
+) -> None:
+    """Cancel the dispatch's run, unless the policy process exited.
+
+    Print the error from a failed cancel instead of raising it: the policy
+    side's own failed report then ends the side.
+    """
+    if served.exit_code is not None:
+        return
+    try:
+        client.cancel_run(dispatch.run.id)
+    except Exception as exc:
+        console.print(
+            "[yellow]Could not cancel the run:[/yellow] "
+            f"{escape(str(exc) or type(exc).__name__)}"
+        )
+    else:
+        console.print(
+            "\n" + stopped(f"Canceled run [bold]{escape(dispatch.run.name)}[/bold]")
+        )
+
+
+def _discard(message: str) -> None:
+    """Drop a line from the runner loop."""
+
+
+def _release(console: Console, client: ManifoldApiClient) -> None:
+    """Unregister this runner, printing any error instead of raising it.
+
+    This runs in a `finally`, where raising would hide the original exception.
+    """
+    try:
+        client.release_runner()
+    except Exception as exc:
+        console.print(
+            "[yellow]Could not unregister this runner:[/yellow] "
+            f"{escape(str(exc) or type(exc).__name__)}. Manifold stops sending "
+            "it runs once it stops polling. An operator can remove it with "
+            "`manifold runner revoke`."
+        )
+
+
+def _parse_environment(values: list[str] | None) -> dict[str, str]:
+    environment: dict[str, str] = {}
+    for value in values or []:
+        key, separator, setting = value.partition("=")
+        if not separator or not key:
+            raise typer.BadParameter("must be KEY=VALUE", param_hint="--env")
+        environment[key] = setting
+    return environment