flashnode 0.3.3__tar.gz → 0.3.5__tar.gz

{flashnode-0.3.3 → flashnode-0.3.5}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: flashnode
-Version: 0.3.3
+Version: 0.3.5
 Summary: Open host agent for the FlashML fragmented-compute network: join, benchmark, execute sandboxed ML tasks, earn contribution credits.
 License: Apache-2.0
 Project-URL: Homepage, https://github.com/Zolli-Labs/flashnode
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: flashruntime<0.5,>=0.4.2
+Requires-Dist: flashruntime<0.6,>=0.4.3
 Requires-Dist: psutil>=5.9
 Requires-Dist: websockets>=12
 Requires-Dist: cryptography>=42

flashnode-0.3.5/flashnode/agent/cli.py

@@ -0,0 +1,653 @@
+"""Command-line entry point for the FlashNode agent.
+
+Target surface (see docs/SYSTEM_OVERVIEW.md §10):
+
+    flashnode join --code <one-time-code>
+    flashnode status
+    flashnode leave
+"""
+
+from __future__ import annotations
+
+import sys
+
+from flashnode import __version__
+
+USAGE = """\
+flashnode {version} — FlashML open host agent (pre-release scaffold)
+
+usage: flashnode <command>
+
+commands:
+  agent     run the node agent loop (register with FlashML Cloud + heartbeat)
+  work      register with a FlashRuntime coordinator and execute leased tasks
+            (--coordinator URL | FLASHNODE_COORDINATOR_URL; --max-tasks N)
+  login     enrol this machine — prints a code to approve in a browser
+            (--coordinator URL; --token TOKEN to skip the browser step)
+  logout    remove the saved bearer token for a FlashRuntime coordinator
+            (--coordinator URL)
+  doctor    check this machine can run tasks (docker engine, images, mounts)
+  env       see and reclaim disk held by cached dependency environments
+            (list | purge — purge never touches node-id or credentials.json)
+  join      connect this machine to a FlashML control plane (not yet implemented)
+  status    show node identity, capabilities, and active leases (not yet implemented)
+  leave     drain and disconnect (not yet implemented)
+"""
+
+
+def _login(args: list[str]) -> int:
+    """Enrol this machine.
+
+    The default path is device-code: print a short code, wait for a
+    signed-in human to approve it in a browser, save the token that comes
+    back. That is what the console tells volunteers to run, and until now it
+    could not work — `--token` was REQUIRED, and the enrolment flow issues
+    no token for anyone to paste. The API half (/v1alpha1/device/code,
+    /v1alpha1/device/token) had been built and simply had no client.
+
+    `--token` stays supported for a credential you already hold: CI, a
+    self-hosted coordinator, or re-pointing a machine with no browser to
+    hand.
+    """
+    import argparse
+
+    from flashnode.identity.credentials import save_token
+
+    parser = argparse.ArgumentParser(
+        prog="flashnode login",
+        description="Enrol this machine with FlashML.",
+    )
+    parser.add_argument(
+        "--coordinator",
+        required=True,
+        help="FlashML Cloud API base URL (e.g. https://flashml-api.onrender.com)",
+    )
+    parser.add_argument(
+        "--token",
+        help="skip the browser step and save a token you already have",
+    )
+    opts = parser.parse_args(args)
+
+    if opts.token:
+        path = save_token(opts.coordinator, opts.token)
+        print(f"flashnode login: credential saved to {path}", file=sys.stderr)
+        return 0
+
+    from flashnode.identity.enrol import (
+        EnrolmentError,
+        describe_this_machine,
+        poll_for_token,
+        request_device_code,
+    )
+    from flashnode.identity.store import load_or_create_node_id
+
+    try:
+        node_id = load_or_create_node_id()
+    except OSError as exc:
+        print(
+            f"flashnode login: cannot write this machine's identity: {exc}\n"
+            "Set FLASHNODE_STATE_DIR to a directory you can write to.",
+            file=sys.stderr,
+        )
+        return 1
+
+    hostname, platform_name = describe_this_machine()
+
+    try:
+        start = request_device_code(
+            opts.coordinator, node_id, hostname, platform_name
+        )
+    except EnrolmentError as exc:
+        print(f"flashnode login: {exc}", file=sys.stderr)
+        return 1
+
+    # stdout, not stderr: this is the output the person is here for, and it
+    # should survive being piped.
+    #
+    # flush=True is load-bearing. Python block-buffers stdout when it is not
+    # a terminal, so piping `flashnode login` anywhere — tee, a log, a setup
+    # script — showed nothing at all while the process sat waiting for an
+    # approval of a code it had never displayed.
+    print(flush=True)
+    print(f"  Your code:  {start.user_code}", flush=True)
+    print(f"  Approve at: {start.verification_uri}", flush=True)
+    print(flush=True)
+    print(
+        "Open that on any device you're signed in on — your phone is fine.",
+        flush=True,
+    )
+    print("Waiting for approval… (Ctrl-C to cancel)", flush=True)
+
+    try:
+        token = poll_for_token(
+            opts.coordinator, start.device_code, interval=start.interval
+        )
+    except EnrolmentError as exc:
+        print(f"\nflashnode login: {exc}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        # Cancelling is a normal act, not a crash. The code expires unused.
+        print("\nflashnode login: cancelled.", file=sys.stderr)
+        return 130
+
+    path = save_token(opts.coordinator, token)
+    print(f"\nApproved. This machine is enrolled — credential saved to {path}.")
+    # The coordinator has to be IN the printed command. A volunteer pastes
+    # this line verbatim; without it `work` defaults to localhost:8100,
+    # looks up a credential that was saved under a different key, and dies
+    # on a bare 401 running the exact command the CLI just gave them.
+    # Lazy import, matching this file's existing style (see the imports a few
+    # lines up): health.py pulls CheckResult/default_workdir/run_checks from
+    # flashnode.doctor at module scope, and this keeps that import graph from
+    # having to resolve until a login actually happens.
+    from flashnode.doctor import check_cli_on_path
+    from flashnode.executor.health import suggested_runner
+
+    # `shutil.which`, not the full docker set: suggested_runner reads only
+    # the CLI-on-PATH verdict, and probing the daemon here would make
+    # `flashnode login` hang for up to 30s against a wedged docker install
+    # to answer a question a PATH lookup already settles.
+    hint = suggested_runner([check_cli_on_path()])
+    print(
+        "Start contributing with:  "
+        f"flashnode work --runner {hint} --coordinator {opts.coordinator}"
+    )
+    return 0
+
+
+#: Tiers that shell out to the `docker` binary. Everything else runs the
+#: workload on the host directly and has no container to diagnose.
+_CONTAINER_TIERS = ("docker", "argv")
+
+
+def _next_step(runner: str, *, restarting: bool = False, docker_absent: bool = False) -> str:
+    """What to tell an operator whose host just refused to work, in terms
+    their tier can actually act on.
+
+    `flashnode doctor` runs `run_checks(pull=True)` — the DOCKER set. Telling
+    a host that has no Docker, which is the entire reason it is on a
+    no-container tier, to run it hands back `[FAIL] docker CLI on PATH` and a
+    non-zero exit: the same misleading verdict this tier exists to remove,
+    reached one hop later. That is what a real pod was told on 2026-08-09.
+    The "image pull this skipped" clause is meaningless there too — the
+    no-container tiers never pull anything.
+
+    `docker_absent=True` is the narrower case: `runner` IS a container tier
+    (docker/argv), but the `docker` CLI itself was not found — the same
+    2026-08-09 shape one tier over. `flashnode doctor` is still the right
+    command here (this host really does need Docker), but "including the
+    image pull this skipped" is false on it: there was never going to be a
+    pull, because the CLI check that gates one already failed. Set by the
+    caller from the same startup check set this trailer follows, never
+    guessed here.
+
+    `restarting=True` is the quarantine path, where the host had already
+    started and the operator is being told what to do before starting again.
+    """
+    if runner in _CONTAINER_TIERS:
+        if restarting:
+            return "Fix the above, then `flashnode doctor` to confirm before restarting."
+        if docker_absent:
+            return ("Run `flashnode doctor` for the full check. There is no "
+                     "`docker` here at all, so there is no image pull to skip.")
+        return ("Run `flashnode doctor` for the full check, including the "
+                "image pull this skipped.")
+    verb = "start" if restarting else "run"
+    return (
+        f"Fix the above, then {verb} `flashnode work --runner {runner}` again.\n"
+        f"Do not run `flashnode doctor` here: it checks the Docker tier, which\n"
+        f"--runner {runner} never uses, so on this machine it fails by design."
+    )
+
+
+def _logout(args: list[str]) -> int:
+    import argparse
+
+    from flashnode.identity.credentials import clear_token, credentials_path
+
+    parser = argparse.ArgumentParser(prog="flashnode logout")
+    parser.add_argument("--coordinator", required=True, help="FlashRuntime coordinator base URL")
+    opts = parser.parse_args(args)
+
+    removed = clear_token(opts.coordinator)
+    if removed:
+        print(f"flashnode logout: credential removed from {credentials_path()}", file=sys.stderr)
+    else:
+        print(f"flashnode logout: no saved credential for {opts.coordinator}", file=sys.stderr)
+    return 0
+
+
+def _work(args: list[str]) -> int:
+    import argparse
+    import logging
+    import os
+    import shutil
+    import signal
+
+    from flashnode.executor import CoordinatorClient, ExecutorLoop
+    from flashnode.identity.store import load_or_create_node_id
+    from flashnode.inventory.capabilities import discover
+
+    logging.basicConfig(
+        level=logging.INFO,
+        format='{"ts":"%(asctime)s","level":"%(levelname)s","service":"flashnode","msg":%(message)s}',
+    )
+    parser = argparse.ArgumentParser(prog="flashnode work")
+    parser.add_argument(
+        "--coordinator",
+        # No default here: an omitted --coordinator is resolved below from
+        # the credentials this machine actually holds. Baking localhost in
+        # made every enrolled volunteer's first command 401.
+        default=os.environ.get("FLASHNODE_COORDINATOR_URL"),
+        help="FlashRuntime coordinator base URL (default: the one this "
+             "machine enrolled against with `flashnode login`)",
+    )
+    parser.add_argument(
+        "--runner",
+        choices=["subprocess", "docker", "argv", "trusted"],
+        default=os.environ.get("FLASHNODE_RUNNER", "subprocess"),
+        help="task execution tier (docker/argv need the docker CLI on PATH; "
+             "trusted runs pool jobs unsandboxed — opt-in only — and is the "
+             "only tier leased jobs that declare dependencies)",
+    )
+    parser.add_argument("--max-tasks", type=int, default=None)
+    parser.add_argument("--poll-seconds", type=float, default=1.0)
+    parser.add_argument(
+        "--log-json", action="store_true",
+        help="keep the machine-readable JSON log instead of the live status view",
+    )
+    parser.add_argument(
+        "--max-consecutive-failures", type=int,
+        default=int(os.environ.get("FLASHNODE_MAX_CONSECUTIVE_FAILURES", "3")),
+        help="host-side failures in a row before re-checking this machine and "
+             "stopping if it is broken (0 disables)",
+    )
+    opts = parser.parse_args(args)
+
+    # Resolved BEFORE the runner branch so the one health binding below can
+    # hand it to whichever tier's check set applies — the directory a check
+    # asks about must be the directory the loop will actually stage tasks in.
+    workdir_base = os.environ.get("FLASHNODE_WORKDIR") or None
+
+    # Every branch below assigns a runner — there is no `runner = None`
+    # fallthrough any more, because the health binding after them has to have
+    # something to ask.
+    if opts.runner in ("docker", "argv"):
+        # OPTIONAL, and additive. The built-in namespace allowlist
+        # (executor/images.py DEFAULT_ALLOWED_IMAGE_PREFIXES) is what a
+        # volunteer runs on, so this env var is no longer required and an
+        # empty value is no longer a refusal to start.
+        #
+        # It used to be mandatory, which quietly capped the project at the
+        # number of machines whose owners would hand-maintain a list of image
+        # references: every image we published stranded every host until its
+        # owner edited the variable, so security fixes would reach a fraction
+        # of the fleet. Setting it now means "also allow these", for
+        # self-hosting the stack or for integration tests.
+        images = frozenset(
+            i.strip() for i in os.environ.get("FLASHNODE_ALLOWED_IMAGES", "").split(",") if i.strip()
+        )
+        if opts.runner == "docker":
+            from flashnode.executor.docker_runner import DockerRunner
+
+            runner = DockerRunner(allowed_images=images)
+        else:
+            from flashnode.executor.argv_runner import ArgvDockerRunner
+
+            runner = ArgvDockerRunner(
+                allowed_images=images,
+                cpus=float(os.environ.get("FLASHNODE_MAX_CPUS", "2.0")),
+                memory_gb=float(os.environ.get("FLASHNODE_MAX_MEMORY_GB", "2.0")),
+                timeout_seconds=float(os.environ.get("FLASHNODE_TASK_TIMEOUT_S", "3600")),
+                max_output_bytes=int(
+                    os.environ.get("FLASHNODE_MAX_OUTPUT_BYTES", str(2 * 1024**3))
+                ),
+            )
+    elif opts.runner == "trusted":
+        # This tier exists for hosts that ARE a container already — a RunPod
+        # pod, a Colab VM — and so can never nest a Docker daemon. The docker
+        # checks are not merely unnecessary here, they are unsatisfiable.
+        from flashnode.executor.trusted_runner import TrustedArgvRunner
+
+        print(
+            "trusted runner: pool jobs from your team run UNSANDBOXED on this\n"
+            "machine — no container, no network isolation. Only continue if\n"
+            "every member of your pool is someone you trust to run code here."
+        )
+        runner = TrustedArgvRunner()
+    else:
+        # Constructed HERE rather than left to ExecutorLoop's own default, so
+        # that every tier reaches the health binding below with a runner to
+        # ask. The instance is what the loop would have built for itself.
+        from flashnode.executor.runner import SubprocessRunner
+
+        runner = SubprocessRunner()
+
+    # The tier is resolved ONCE, here, by asking the runner we just built.
+    # Two call sites each deciding their own tier is precisely the bug this
+    # replaced: the startup gate exempted `trusted` and the loop's
+    # post-failure re-check did not, so three failures of any cause
+    # quarantined a pod and blamed Docker for it (2026-08-09).
+    #
+    # What the docker tier asks is unchanged, and deliberately so. Both
+    # sandboxed tiers shell out to the `docker` binary directly
+    # (subprocess.run(["docker", ...])); if it isn't installed that call
+    # raises FileNotFoundError deep inside a task attempt. And a `docker`
+    # binary on PATH says nothing about the daemon behind it, the credential
+    # helper Docker consults when it pulls, or whether this machine's work
+    # directory is even visible inside the VM. Both hosts that stopped the
+    # 2026-08-02 §10 run-through passed the old `shutil.which` check and then
+    # failed every task they claimed — docker_runner raises
+    # TaskExecutionError, loop.py calls fail() and claims the next one,
+    # forever, silently. `docker_tier_checks` still runs with pull=False: an
+    # agent is a long-running daemon on someone else's machine, and a
+    # transient registry blip must not stop one whose images are already
+    # cached. `flashnode doctor` does the pull.
+    from flashnode.doctor import NON_BLOCKING_STATUSES, format_results
+
+    def _blocking_problems() -> list:
+        """What the loop calls after a streak of host-side failures.
+
+        Bound to the same runner as the startup gate below, so the two
+        cannot disagree about which tier this host is in — and so `loop.py`
+        never has to import the doctor (which would close a
+        loop -> doctor -> executor -> loop cycle).
+
+        Filtered HERE with doctor's own NON_BLOCKING_STATUSES rather than a
+        `!= "ok"` test: the GPU check reports "info" and never fails,
+        because most volunteers have no GPU and blocking on it would lock
+        the entire existing fleet out of the CPU work they signed up for.
+        Keeping that predicate in one place is what stops `flashnode work`
+        and `flashnode doctor` disagreeing about which verdicts are fatal.
+        The membership test is the way round that makes an unknown status
+        BLOCK, matching doctor.exit_code.
+        """
+        return [r for r in runner.health_checks(workdir=workdir_base)
+                if r.status not in NON_BLOCKING_STATUSES]
+
+    startup_problems = _blocking_problems()
+    if startup_problems:
+        # Read off the SAME check set the trailer follows, never guessed:
+        # a host whose `docker CLI on PATH` check failed has no image pull
+        # to have skipped, and the trailer below must not claim it did.
+        docker_absent = any(
+            r.name == "docker CLI on PATH" and r.status == "fail"
+            for r in startup_problems
+        )
+        # next_step="" because the trailer below IS the next step, and it is
+        # chosen by tier. Leaving format_results' default in place printed
+        # "re-run `flashnode doctor`" to a host the doctor cannot certify.
+        print(
+            f"flashnode work: this machine cannot run tasks with "
+            f"--runner {opts.runner}.\n"
+            + format_results(startup_problems, next_step="")
+            + "\n\n" + _next_step(opts.runner, docker_absent=docker_absent),
+            file=sys.stderr,
+        )
+        return 2
+
+    from flashnode.identity.credentials import load_token, resolve_coordinator
+
+    try:
+        opts.coordinator = resolve_coordinator(opts.coordinator)
+    except ValueError as exc:
+        print(f"flashnode work: {exc}", file=sys.stderr)
+        return 1
+
+    node_id = load_or_create_node_id()
+    client = CoordinatorClient(
+        opts.coordinator,
+        join_code=os.environ.get("FLASHNODE_JOIN_CODE") or None,
+        token=load_token(opts.coordinator),
+    )
+    registration = discover(
+        node_id, kubernetes_node="", node_meta=None,
+        argv_capable=(opts.runner == "argv"),
+        # An argv-only volunteer has no module runner behind it: advertise
+        # module_capable=False so the coordinator's placement gate stops
+        # routing "python -m <module>" tasks here (F1) — otherwise those
+        # tasks burn every attempt against ArgvDockerRunner's payload
+        # rejection before the job ever fails for real.
+        # `trusted` runs argv through TrustedArgvRunner, which refuses
+        # `python -m <module>` payloads exactly as the argv tier does. Both
+        # must advertise module_capable=False, or this machine is eligible
+        # for public MODULE tasks it fails every attempt of — burning the
+        # volunteer's electricity and the job's retries on a mismatch the
+        # registration already knew about.
+        module_capable=(opts.runner not in ("argv", "trusted")),
+        # Set true ONLY by the explicit --runner trusted opt-in, never
+        # inferred — the scheduler's placement gate treats this field as
+        # fail-closed (flashruntime.scheduler), so a node that merely has a
+        # shell available must not advertise it.
+        unsandboxed_argv_capable=(opts.runner == "trusted"),
+        # `trusted` ONLY, and deliberately narrower than "the tiers that
+        # could technically run pip".
+        #
+        # The feature exists for hosts that cannot run a container — a
+        # RunPod pod, a Colab notebook — and must execute the submitter's
+        # own argv; that is the trusted tier, and only there does the job's
+        # venv hold everything the job runs.
+        #
+        # `subprocess` is excluded even though it also runs on the host: it
+        # executes the AGENT's allowlisted `flashml_workloads.*` modules,
+        # which live in the agent's environment, not the job's. Sending it
+        # into a job venv built from the job's declared dependencies alone
+        # produces ModuleNotFoundError — the exact failure this feature
+        # exists to eliminate. Giving that venv access to the agent's own
+        # environment is not the fix either: a declared dependency would
+        # then shadow the agent's.
+        #
+        # The container tiers cannot install at all — --network none and a
+        # read-only rootfs. Physics, not policy.
+        #
+        # Fail closed and narrow. Widening this to another tier is a
+        # deliberate change that must arrive with its own tests.
+        can_install_dependencies=(opts.runner == "trusted"),
+    )
+    client.register(registration)
+    loop = ExecutorLoop(
+        client, node_id, runner=runner,
+        poll_seconds=opts.poll_seconds, workdir_base=workdir_base,
+        registration=registration,  # survives coordinator restarts
+        health_check=_blocking_problems,
+        max_consecutive_failures=opts.max_consecutive_failures,
+    )
+
+    def _stop(signum, frame):  # noqa: ARG001
+        loop.stop_event.set()
+
+    signal.signal(signal.SIGTERM, _stop)
+    signal.signal(signal.SIGINT, _stop)
+    view = None
+    if sys.stdout.isatty() and not opts.log_json:
+        # Two writers redrawing one terminal is unreadable, so the JSON
+        # handler goes when the view arrives. --log-json keeps it, and a
+        # non-TTY never gets here — ANSI cursor movement into a pipe or a
+        # systemd journal is corruption, not output.
+        from flashnode.status import StatusView
+
+        logging.getLogger().handlers.clear()
+        view = StatusView(loop, coordinator=opts.coordinator,
+                          version=__version__, stream=sys.stdout)
+        view.start()
+    try:
+        accepted = loop.run(max_tasks=opts.max_tasks)
+    finally:
+        if view is not None:
+            view.stop()
+
+    if getattr(loop, "quarantined", False):
+        from flashnode.doctor import format_results
+
+        print(
+            "\nflashnode work: stopping — this machine can no longer run "
+            "tasks.\n"
+            + format_results(loop.health_report or [], next_step="")
+            + "\n\n" + _next_step(opts.runner, restarting=True),
+            file=sys.stderr,
+        )
+        return 2
+    print(f"flashnode work: {accepted} task(s) accepted", file=sys.stderr)
+    return 0
+
+
+def _human_bytes(n: int) -> str:
+    """`n` bytes, rendered the way a volunteer reads disk usage — whole B,
+    one decimal place from KB up."""
+    size = float(n)
+    for unit in ("B", "KB", "MB", "GB"):
+        if size < 1024 or unit == "GB":
+            return f"{size:.0f} {unit}" if unit == "B" else f"{size:.1f} {unit}"
+        size /= 1024
+    return f"{size:.1f} GB"  # pragma: no cover - unreachable, GB always returns above
+
+
+def _env(args: list[str]) -> int:
+    """`flashnode env list|purge` — the disk cached dependency environments
+    hold, and a way to give it back without `rm -rf ~/.flashnode`.
+
+    `purge` deletes only what `EnvironmentCache.entries()` reports — the
+    contents of `$FLASHNODE_STATE_DIR/envs/`. It never touches the state
+    directory itself, so `node-id` and `credentials.json`, its siblings, are
+    untouched: that is the entire difference between this command and
+    un-enrolling the machine.
+    """
+    import argparse
+    import shutil
+    from datetime import datetime
+
+    from flashnode.executor.environments import EnvironmentCache
+
+    parser = argparse.ArgumentParser(prog="flashnode env")
+    sub = parser.add_subparsers(dest="subcommand", required=True)
+    sub.add_parser("list", help="show cached environments, their size, and last use")
+    sub.add_parser(
+        "purge",
+        help="delete all cached environments (identity and credentials "
+             "survive; stop `flashnode work` first — this can break a task "
+             "in flight)",
+    )
+    opts = parser.parse_args(args)
+
+    cache = EnvironmentCache()
+    entries = cache.entries()  # most recently used first
+
+    # Scratch directories from builds that were KILLED — SIGKILL, the OOM
+    # killer, a power cut. `entries()` skips dotted names, so without this
+    # the two commands whose whole job is to account for disk were the two
+    # that could not see a multi-GB directory.
+    stale_bytes = cache.stale_build_bytes()
+
+    if opts.subcommand == "list":
+        if not entries and not stale_bytes:
+            print("flashnode env: no environments cached — nothing is using disk yet.")
+            return 0
+        for entry in entries:
+            when = datetime.fromtimestamp(entry.last_used).strftime("%Y-%m-%d %H:%M")
+            print(f"  {entry.key}  {_human_bytes(entry.size_bytes):>8}  last used {when}")
+        total = sum(e.size_bytes for e in entries) + stale_bytes
+        if stale_bytes:
+            print(
+                f"  leftover build directories  {_human_bytes(stale_bytes):>8}  "
+                "from interrupted builds"
+            )
+        print(
+            f"total: {_human_bytes(total)} across {len(entries)} environment(s) "
+            f"at {cache.root}"
+        )
+        if stale_bytes:
+            print(
+                "  the leftover build directories are swept by the next build, "
+                "or now by `flashnode env purge`"
+            )
+        return 0
+
+    # purge
+    #
+    # This runs in a SEPARATE process from the agent. The in-process
+    # eviction path is safe only because ExecutorLoop holds one lease at a
+    # time and `_evict` protects the entry it just handed out; purge
+    # sidesteps both and can delete the venv a running task's interpreter
+    # lives in. Refusing would beat warning, but nothing in the state
+    # directory records a running agent — no pidfile, no lock — and a
+    # guessed signal (a stale pid, an mtime heuristic) would refuse on a
+    # machine with no agent at all. So: say it, plainly, every time, and
+    # before the deletion rather than after it.
+    print(
+        "flashnode env purge: warning — if `flashnode work` is running on "
+        "this machine, this can delete the environment a task is running in "
+        "and fail that task. This command cannot tell whether an agent is "
+        "running. Stop the agent first if you are not sure."
+    )
+    # Counted AFTER each removal, never before. The old version totalled the
+    # entries up front and deleted with `ignore_errors=True`, so a
+    # permission error printed the full figure as reclaimed — on the one
+    # command whose entire value is that number, and which a volunteer has
+    # no other way to check.
+    freed = 0
+    removed = 0
+    survivors = []
+    for entry in entries:
+        shutil.rmtree(entry.path, ignore_errors=True)
+        if entry.path.exists():
+            survivors.append(entry.path)
+        else:
+            freed += entry.size_bytes
+            removed += 1
+    stale_freed = cache.sweep_stale_builds()  # counts only what actually went
+    freed += stale_freed
+    survivors.extend(cache.stale_build_dirs())
+    leftovers = (
+        f" (including {_human_bytes(stale_freed)} of leftover build "
+        "directories from interrupted builds)"
+        if stale_freed
+        else ""
+    )
+    print(
+        f"flashnode env purge: freed {_human_bytes(freed)} across "
+        f"{removed} environment(s){leftovers}. node-id and credentials.json "
+        "were not touched."
+    )
+    if survivors:
+        noun = "directory" if len(survivors) == 1 else "directories"
+        print(
+            f"flashnode env purge: could not remove {len(survivors)} {noun} "
+            "— the disk it holds was NOT reclaimed:"
+        )
+        for path in survivors:
+            print(f"  {path}")
+        print(
+            "  check the permissions on those paths, or whether another "
+            "process is holding them open, and run purge again."
+        )
+        return 1
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = sys.argv[1:] if argv is None else argv
+    if args and args[0] == "agent":
+        from flashnode.agent.daemon import main as agent_main
+
+        return agent_main()
+    if args and args[0] == "work":
+        return _work(args[1:])
+    if args and args[0] == "doctor":
+        from flashnode.doctor import doctor_main
+
+        return doctor_main(args[1:])
+    if args and args[0] == "login":
+        return _login(args[1:])
+    if args and args[0] == "logout":
+        return _logout(args[1:])
+    if args and args[0] == "env":
+        return _env(args[1:])
+    print(USAGE.format(version=__version__), end="")
+    if args and args[0] in {"join", "status", "leave"}:
+        print(f"\nerror: '{args[0]}' is not implemented yet in this scaffold.", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())