flashnode 0.2.0__py3-none-any.whl

flashnode/__init__.py

@@ -0,0 +1,7 @@
+"""FlashNode: the open host agent of the FlashML system.
+
+Installed by resource contributors to safely execute distributed ML tasks.
+See README.md and docs/SYSTEM_OVERVIEW.md.
+"""
+
+__version__ = "0.1.0"

flashnode/agent/__init__.py

@@ -0,0 +1,6 @@
+"""Control connection and lifecycle.
+
+Maintains the outbound authenticated WebSocket to the control plane (no
+inbound ports required), handles registration, lease acceptance, heartbeat
+renewal, and graceful drain/shutdown.
+"""

flashnode/agent/cli.py

@@ -0,0 +1,285 @@
+"""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)
+  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}.")
+    print("Start contributing with:  flashnode work --runner docker")
+    return 0
+
+
+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",
+        default=os.environ.get("FLASHNODE_COORDINATOR_URL", "http://localhost:8100"),
+        help="FlashRuntime coordinator base URL",
+    )
+    parser.add_argument(
+        "--runner",
+        choices=["subprocess", "docker", "argv"],
+        default=os.environ.get("FLASHNODE_RUNNER", "subprocess"),
+        help="task execution tier (docker/argv need the docker CLI on PATH)",
+    )
+    parser.add_argument("--max-tasks", type=int, default=None)
+    parser.add_argument("--poll-seconds", type=float, default=1.0)
+    opts = parser.parse_args(args)
+
+    runner = None
+    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()
+        )
+        # 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. Check for it
+        # here, at startup, rather than let the agent die on the first task.
+        if shutil.which("docker") is None:
+            print(
+                f"flashnode work: --runner {opts.runner} requires the `docker` CLI "
+                "on PATH — refusing to start without it",
+                file=sys.stderr,
+            )
+            return 2
+        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))
+                ),
+            )
+
+    workdir_base = os.environ.get("FLASHNODE_WORKDIR") or None
+
+    from flashnode.identity.credentials import load_token
+
+    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.
+        module_capable=(opts.runner != "argv"),
+    )
+    client.register(registration)
+    loop = ExecutorLoop(
+        client, node_id, runner=runner,
+        poll_seconds=opts.poll_seconds, workdir_base=workdir_base,
+        registration=registration,  # survives coordinator restarts
+    )
+
+    def _stop(signum, frame):  # noqa: ARG001
+        loop.stop_event.set()
+
+    signal.signal(signal.SIGTERM, _stop)
+    signal.signal(signal.SIGINT, _stop)
+    accepted = loop.run(max_tasks=opts.max_tasks)
+    print(f"flashnode work: {accepted} task(s) accepted", file=sys.stderr)
+    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] == "login":
+        return _login(args[1:])
+    if args and args[0] == "logout":
+        return _logout(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())

flashnode/agent/daemon.py

@@ -0,0 +1,108 @@
+"""FlashNode agent loop for the Kubernetes profile.
+
+One agent per node (DaemonSet). It never launches workload containers, never
+touches a container runtime socket, and only makes *outbound* HTTP calls to
+FlashML Cloud: register once, then heartbeat. On SIGTERM it reports
+`terminating` and exits.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import signal
+import sys
+import time
+import urllib.error
+import urllib.request
+
+from flashruntime.protocol.v1alpha1 import NodeHeartbeat, NodeRegistration
+
+from flashnode.agent.kube import get_own_node
+from flashnode.identity.store import load_or_create_node_id
+from flashnode.inventory.capabilities import discover
+
+log = logging.getLogger("flashnode")
+logging.basicConfig(
+    level=logging.INFO,
+    format='{"ts":"%(asctime)s","level":"%(levelname)s","service":"flashnode","msg":%(message)s}',
+)
+
+
+def _jlog(msg: str, **kv) -> str:
+    return json.dumps({"text": msg, **kv})
+
+
+def _post(url: str, payload: str, timeout: float = 10) -> None:
+    req = urllib.request.Request(
+        url, data=payload.encode(), headers={"Content-Type": "application/json"}
+    )
+    with urllib.request.urlopen(req, timeout=timeout):
+        pass
+
+
+class Agent:
+    def __init__(self) -> None:
+        self.cloud_url = os.environ.get("FLASHNODE_CLOUD_URL", "http://localhost:8000").rstrip("/")
+        self.heartbeat_seconds = float(os.environ.get("FLASHNODE_HEARTBEAT_SECONDS", "10"))
+        self.node_id = load_or_create_node_id()
+        self.kubernetes_node = os.environ.get("K8S_NODE_NAME", "")
+        self._stop = False
+
+    def registration(self) -> NodeRegistration:
+        node_meta = get_own_node(self.kubernetes_node)
+        return discover(self.node_id, self.kubernetes_node, node_meta)
+
+    def register(self) -> None:
+        reg = self.registration()
+        backoff = 1.0
+        while not self._stop:
+            try:
+                _post(f"{self.cloud_url}/v1alpha1/nodes/register", reg.model_dump_json())
+                log.info(_jlog("registered", node_id=self.node_id,
+                               k8s_node=self.kubernetes_node,
+                               pool=reg.pool, arch=reg.capabilities.architecture))
+                return
+            except (urllib.error.URLError, OSError) as exc:
+                log.warning(_jlog("registration failed; retrying",
+                                  error=str(exc), backoff_s=backoff))
+                time.sleep(backoff)
+                backoff = min(backoff * 2, 30)
+
+    def heartbeat_once(self, status: str = "online") -> bool:
+        hb = NodeHeartbeat(node_id=self.node_id, status=status)
+        try:
+            _post(f"{self.cloud_url}/v1alpha1/nodes/{self.node_id}/heartbeat",
+                  hb.model_dump_json())
+            return True
+        except (urllib.error.URLError, OSError) as exc:
+            log.warning(_jlog("heartbeat failed", error=str(exc)))
+            return False
+
+    def _handle_term(self, signum, frame) -> None:  # noqa: ARG002
+        self._stop = True
+
+    def run(self) -> int:
+        signal.signal(signal.SIGTERM, self._handle_term)
+        signal.signal(signal.SIGINT, self._handle_term)
+        log.info(_jlog("flashnode agent starting", node_id=self.node_id,
+                       cloud=self.cloud_url, k8s_node=self.kubernetes_node))
+        self.register()
+        while not self._stop:
+            self.heartbeat_once()
+            deadline = time.monotonic() + self.heartbeat_seconds
+            while not self._stop and time.monotonic() < deadline:
+                time.sleep(0.25)
+        # Graceful goodbye — best effort, one attempt.
+        self.heartbeat_once(status="terminating")
+        log.info(_jlog("flashnode agent stopped", node_id=self.node_id))
+        return 0
+
+
+def main() -> int:
+    return Agent().run()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

flashnode/agent/kube.py

@@ -0,0 +1,41 @@
+"""Minimal in-cluster Kubernetes API access — stdlib only.
+
+The agent needs exactly one call (GET its own Node object) so it can report
+allocatable resources and allow-listed labels. A full kubernetes client
+would be attack surface and megabytes of dependencies on a contributor's
+machine; a 30-line REST call is inspectable.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import ssl
+import urllib.request
+
+SA_DIR = "/var/run/secrets/kubernetes.io/serviceaccount"
+
+
+def in_cluster() -> bool:
+    return os.path.exists(f"{SA_DIR}/token")
+
+
+def get_own_node(node_name: str) -> dict | None:
+    """Fetch this agent's Node object; None when not in-cluster or on any
+    failure (the agent then degrades to host-level probes)."""
+    if not in_cluster() or not node_name:
+        return None
+    try:
+        with open(f"{SA_DIR}/token") as f:
+            token = f.read().strip()
+        host = os.environ["KUBERNETES_SERVICE_HOST"]
+        port = os.environ.get("KUBERNETES_SERVICE_PORT", "443")
+        ctx = ssl.create_default_context(cafile=f"{SA_DIR}/ca.crt")
+        req = urllib.request.Request(
+            f"https://{host}:{port}/api/v1/nodes/{node_name}",
+            headers={"Authorization": f"Bearer {token}"},
+        )
+        with urllib.request.urlopen(req, timeout=10, context=ctx) as resp:
+            return json.load(resp)
+    except Exception:
+        return None

flashnode/artifacts/__init__.py

@@ -0,0 +1,5 @@
+"""Input/output/checkpoint staging.
+
+Downloads task inputs, uploads outputs and checkpoint pieces with content
+hashes; commits are idempotent so retries never double-count.
+"""

flashnode/benchmark/__init__.py

@@ -0,0 +1,100 @@
+"""Admission and workload probes: measured capability, never self-reported.
+
+Short benchmarks run at join time (and periodically after) so the
+coordinator's placement/capability decisions rest on measurements, not on
+what a host *claims* (the Vast.ai lesson — master report §9.1: hosts earn
+eligibility through measurement). Results ride the existing
+`NodeRegistration.capabilities`/`labels` — raw numbers each, NEVER a
+single synthetic score (§9.2: a composite hides exactly the bottleneck
+that matters for a given workload).
+
+Standard probe names (implement as separate AdmissionProbe subclasses so
+each stays independently budgeted and independently failable):
+  cpu_hash_mbps       — sustained single-core throughput (sha256 over RAM)
+  mem_bandwidth_mbps  — large-buffer copy rate
+  disk_write_mbps     — workdir sequential write (the checkpoint path!)
+  net_down_mbps       — artifact-download rate from the coordinator
+  gpu_*               — deferred to the GPU tier (nvml presence first)
+
+Budget discipline: probes must respect their `budget_seconds` — admission
+runs while a human waits on `flashnode work` startup; the whole suite gets
+a few seconds, not minutes. Re-probing cadence (daily? on capability
+change?) is a coordinator policy, not the agent's.
+
+Status: interface + orchestration complete; concrete probes land with the
+GPU/community tier (HANDBOOK missing-list; flashnode AGENTS §profiles).
+"""
+
+from __future__ import annotations
+
+import time
+from abc import ABC, abstractmethod
+from typing import ClassVar
+
+from pydantic import BaseModel, Field
+
+__all__ = ["ProbeResult", "AdmissionProbe", "run_admission"]
+
+
+class ProbeResult(BaseModel):
+    """One raw measurement. `value=None` means the probe failed — recorded
+    honestly (with `detail`), never fabricated and never fatal to the
+    node's admission (a laptop with a broken disk probe can still serve
+    CPU tasks; the *coordinator* decides what a missing number implies)."""
+
+    name: str
+    value: float | None = None
+    unit: str = ""
+    duration_s: float = Field(ge=0, default=0.0)
+    detail: str = ""
+
+
+class AdmissionProbe(ABC):
+    """One benchmark, one number.
+
+    Contract: `run` must (a) finish within `budget_seconds` or return its
+    best partial measurement, (b) touch only its own scratch space, (c) be
+    safe to re-run at any time on a live node — probes may execute while
+    tasks run, so they must be gentle (no cache-thrashing full-RAM sweeps).
+    """
+
+    #: Stable name from the standard list above — it becomes the
+    #: capability key the planner/scheduler reads; renaming one is a
+    #: protocol-level event, treat with the same care as a schema field.
+    name: ClassVar[str]
+
+    @abstractmethod
+    def run(self, budget_seconds: float) -> ProbeResult:
+        """Measure and return. Should not raise — but `run_admission`
+        guards anyway, because one broken probe must never sink a node's
+        whole admission."""
+
+
+def run_admission(
+    probes: list[AdmissionProbe], total_budget_seconds: float = 10.0
+) -> dict[str, ProbeResult]:
+    """Run a probe suite under a shared budget; return name → result.
+
+    Budget is split evenly across remaining probes and re-balanced as
+    probes finish early. Failures are captured as `value=None` results
+    (isolation rule) so callers always get one entry per probe — the
+    difference between "not measured" and "measured badly" stays visible.
+    """
+    results: dict[str, ProbeResult] = {}
+    remaining = list(probes)
+    deadline = time.monotonic() + total_budget_seconds
+    while remaining:
+        probe = remaining.pop(0)
+        per_probe = max(0.1, (deadline - time.monotonic()) / (len(remaining) + 1))
+        started = time.monotonic()
+        try:
+            result = probe.run(budget_seconds=per_probe)
+        except Exception as exc:  # isolation: a broken probe is a data point
+            result = ProbeResult(
+                name=probe.name,
+                value=None,
+                duration_s=time.monotonic() - started,
+                detail=f"probe failed: {exc}",
+            )
+        results[probe.name] = result
+    return results

flashnode/config/__init__.py

@@ -0,0 +1,103 @@
+"""Host-owner policy: the machine's owner has the last word.
+
+`HostPolicy` is the contract between FlashNode and the person whose
+machine it runs on: which resources tasks may use, which code may run,
+and how much of the machine FlashML may occupy. It loads from
+`<state_dir>/policy.json` (the same state dir that holds the node id) so
+the owner edits one file, and `flashnode status` *(planned)* can show
+exactly which limits apply — AGENTS hard rule 4: the owner sees what a
+workload may do before it runs.
+
+Safety rules baked into this module:
+- **Conservative defaults**: a policy-less install is the *most*
+  restrictive configuration, not the least (1 task at a time, no network
+  for tasks, modest quotas). Generosity is always an explicit owner act.
+- **Fail closed on garbage**: an unparseable/invalid policy.json raises —
+  the agent refuses to start rather than silently running with defaults
+  the owner believes they overrode.
+- **Owner overrides only narrow, never widen, safety**: `allowed_modules`
+  /`allowed_images` = None defers to the built-in allowlists; a non-None
+  value INTERSECTS with them at enforcement time (an owner can forbid
+  more, never permit code the build doesn't trust).
+
+Wiring points for the implementer (each a small, separate slice):
+- `agent/cli.py _work`: load_host_policy(state_dir) → cap ExecutorLoop
+  concurrency, pass quotas to runners;
+- runners: enforce `max_task_cpus`/`max_task_memory_gb` (docker flags
+  already exist; the subprocess tier gains rlimits);
+- executor workdir: enforce `workdir_quota_gb` before download (fixes the
+  "no disk-space guard" debt in HANDBOOK §6).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from pydantic import BaseModel, Field, ValidationError
+
+__all__ = ["HostPolicy", "load_host_policy"]
+
+
+class HostPolicy(BaseModel):
+    """Everything a host owner may restrict. All defaults are deliberately
+    tight — see module notes."""
+
+    max_concurrent_tasks: int = Field(
+        default=1, ge=1, description="Parallel task slots this machine offers"
+    )
+    max_task_cpus: float = Field(
+        default=2.0, gt=0, description="CPU cores any single task may use"
+    )
+    max_task_memory_gb: float = Field(
+        default=2.0, gt=0, description="RAM any single task may use"
+    )
+    workdir_quota_gb: float = Field(
+        default=5.0,
+        gt=0,
+        description="Max disk per task workdir (inputs + outputs + checkpoints)",
+    )
+    allow_network_tasks: bool = Field(
+        default=False,
+        description="Whether tasks may have network access. False keeps the "
+        "docker tier's --network none and (once enforced) sandboxes the "
+        "subprocess tier; flipping this is a real trust decision",
+    )
+    allowed_modules: list[str] | None = Field(
+        default=None,
+        description="None = defer to the built-in module allowlist; a list "
+        "INTERSECTS with it (owner can only narrow)",
+    )
+    allowed_images: list[str] | None = Field(
+        default=None,
+        description="Same narrowing rule as allowed_modules, for the docker tier",
+    )
+    active_hours: tuple[int, int] | None = Field(
+        default=None,
+        description="Optional (start_hour, end_hour) local-time window in "
+        "which the agent claims work — outside it the loop idles but keeps "
+        "heartbeating so the node shows as present-but-unavailable",
+    )
+
+
+def load_host_policy(state_dir: str | Path) -> HostPolicy:
+    """Load `<state_dir>/policy.json`, defaults when absent, loud when broken.
+
+    Returns: the owner's HostPolicy, or `HostPolicy()` if no file exists
+    (defaults ARE the no-file behavior — documented, conservative).
+    Raises: ValueError naming policy.json for unparseable JSON or invalid
+    fields — never silently substitutes defaults over an owner's broken
+    edit (they believed they had set limits; honoring that belief matters
+    more than starting up).
+    """
+    path = Path(state_dir) / "policy.json"
+    if not path.exists():
+        return HostPolicy()
+    try:
+        raw = json.loads(path.read_text())
+        return HostPolicy.model_validate(raw)
+    except (json.JSONDecodeError, ValidationError) as exc:
+        raise ValueError(
+            f"invalid host policy at {path}: {exc} — fix or delete the file "
+            "(deleting restores the conservative defaults)"
+        ) from exc

flashnode/executor/__init__.py

@@ -0,0 +1,27 @@
+"""Task execution: the device profile's pull-based work cycle.
+
+`ExecutorLoop` claims leases from a FlashRuntime coordinator (outbound
+only), downloads shared input artifacts, runs the task through a runner,
+uploads outputs, and commits — with attempt heartbeats renewing the lease
+throughout.
+
+Runner tiers behind one interface:
+- Tier 1 `SubprocessRunner` (implemented): allowlisted Python modules in a
+  fresh subprocess with a wall-clock timeout. Dev/trusted-pool profile —
+  not a security boundary.
+- Tier 2 Docker (next): allowlisted images, cpu/memory limits,
+  `--network none`, non-root, read-only rootfs. No host Docker socket
+  exposure to workloads, no privileged mode. gVisor/Kata tiers later.
+"""
+
+from flashnode.executor.client import CoordinatorClient, LeaseLost
+from flashnode.executor.loop import ExecutorLoop
+from flashnode.executor.runner import SubprocessRunner, TaskExecutionError
+
+__all__ = [
+    "CoordinatorClient",
+    "ExecutorLoop",
+    "LeaseLost",
+    "SubprocessRunner",
+    "TaskExecutionError",
+]