# Trusted-cluster remote execution

BeamAgent can place a run on a connected, trusted BEAM node running the same
library and compatible application configuration:

```elixir
{:ok, run} =
  BeamAgent.API.run("...",
    llm: {MyModelClient, []},
    placement: {:node, :worker@host}
  )

{:ok, handle} =
  BeamAgent.API.start("...",
    llm: {MyModelClient, []},
    placement: {:node, :worker@host}
  )

{:ok, %{status: :running}} =
  BeamAgent.API.lookup_active_at(:worker@host, handle.run_key)

result = BeamAgent.API.await(handle)
```

`run/2` and `start/2` default to local placement. Both generate the opaque
`run_key` on the caller node before contacting the target. The target executes
through its ordinary API, RunSupervisor, Runner, guardrails, verifier, and
optional trace store. `start/2` returns after the remote runner registers;
its handle remains owned by the original calling process. Run telemetry is
emitted on the executing node. Active Registry lookup and the dashboard remain
node-local; `lookup_active_at/2` explicitly queries another node.

If the target is unreachable before startup, the caller receives
`{:error, run}` with `run.error == :node_unavailable`. A lost connection after
contact produces `:node_lost`; a remote RPC deadline produces
`:remote_timeout`. Other remote RPC failures produce
`:remote_execution_failed`. Every such Run keeps the original key and reports
unknown model usage. These results do not prove that the remote runner or an
external tool did not execute. BeamAgent does **not** replay, migrate, or
resume an interrupted run, and a sanitized stored trace is not a checkpoint.
Remote telemetry can have a start event without a terminal event if its node
disappears.

This first version assumes trusted Erlang distribution and compatible code on
all nodes. Each node has its own active Registry, rate limiter, circuit
breaker, and dashboard. Use a shared, application-managed trace store such as
PostgreSQL when completed history must be visible from multiple nodes. Run
keys are correlation identifiers, not access credentials; protect cluster
connections and any exposed lookup API at the application boundary.