Skip to main content
@obversa/runner starts a graph in a worker process. The calling process watches the worker, cleans up discoverable child processes, and restarts work within declared limits. It loads a host module that supplies graph and engine bindings. @obversa/runtime executes those bindings and records graph events.

​
Install

Node.js 22.12 or later is required. The package depends on the public @obversa/runtime and @obversa/engine APIs.

​
Public entry points

From @obversa/runner:
  • Start and resume: startSupervisedRun starts a stored graph with a watchdog in the calling process. resumeSupervisedRun reopens an exact recorded graph pause using its stored definition and run limits.
  • readSupervisedRunStatus: read recorded progress and inspect worker liveness.
  • SupervisedRunError: report a runner failure with a typed code.
  • Run types: SupervisedRunOptions describes the stored run, host module, workspace, and limits. ResumeSupervisedRunOptions identifies the stored run and paused position to reopen. SupervisedRunStatus describes progress, cleanup scope, and retained workspace ownership.
  • SupervisedRunHandle: exposes done, status(), and stop() for the supervised run.
Worker-crash recovery requires a live watchdog. A new watchdog does not take over a dead watchdog’s lock or held workspace lease. Token budgets apply per worker process and do not enforce a shared token cap across worker restarts.

​
Runnable example

From a built Obversa checkout, run:
The example creates a disposable Git repository, runs two data nodes without an engine or network access, checks their saved results, and removes its temporary directory after cleanup succeeds. See Supervised local runs for the host module contract, crash recovery boundaries, and process-cleanup limits.