@callback effective_timeout(timeout :: timeout() | nil) :: timeout() | nil

The timeout the runner will actually enforce for a caller's timeout.

Callers pass nil for "no timeout", but a runner may substitute a bound of its own (Runner.Forcola does, since forcola requires a finite one). Command.run/3 uses this to report the timeout that actually elapsed. Optional; defaults to the caller's timeout unchanged.

@callback run_evidenced(
  String.t(),
  [String.t()],
  opts(),
  pos_integer(),
  {pid(), reference()}
) ::
  {term(), map()}

Optional evidenced one-shot transport. Uses the same raw chunk observer as run_observed/5. Returns {legacy_outcome, evidence_map}; missing facts remain unknown. Evidence keys are documented in CodexWrapper.ExecutionObservation. The evidence map carries :stdout / :stderr bounded prefixes plus native :child_status, :child_signal, :termination, :reason, :output_truncated, :cleanup, :scope, and :guard_close when known. No raw child exit may be synthesized for a pre-spawn failure. Notifications must come from the calling process before return, preserving message order. timeout is a finite positive wall bound computed from the config. Forcola uses the snapshotted :forcola_default_timeout_ms (300,000 ms unless configured) when no explicit limit is set; other runners default to 300,000 ms. Idle and combined output defaults are 300,000 ms and 1 MiB. :idle_timeout_ms and :max_output_bytes are included in opts. Implementations must bound output and execution, preserve partial output on failure, and finish native cleanup before returning. No fallback is allowed.

@callback run_observed(
  String.t(),
  [String.t()],
  opts(),
  timeout() | nil,
  {pid(), reference()}
) ::
  {:ok, {binary(), non_neg_integer(), binary()}} | {:error, error()}

Optional observed one-shot transport. Send raw stdout/stderr chunks as {reference, {:stdout | :stderr, bytes}} to the given target directly from the process calling this function, before returning its terminal outcome. Preserve all bytes and keep stderr separate regardless of legacy opts. CodexWrapper.ObservedExecution owns the calling helper and forwards typed identity from the execution caller. No runner fallback is allowed.

@callback stream_lines(
  binary :: String.t(),
  args :: [String.t()],
  opts :: opts(),
  timeout :: timeout() | nil
) :: Enumerable.t()

Run binary with args and stream its stdout as lines.

Returns a lazy Enumerable of lines without their trailing newlines. Opening the process is deferred until the stream is consumed, and the process is signalled for termination when the stream halts (including an early Enum.take/2); Runner.Port and Runner.Forcola differ in how far that reaches.

timeout bounds the whole run. The independent opts[:idle_timeout_ms] bounds gaps between output frames; nil disables the idle bound. When timeout is nil, Runner.Port has no whole-run bound and Runner.Forcola uses its configurable default. Both built-in runners default to a 300,000 ms idle bound.

Optional. CodexWrapper.Runner.stream_lines/4 warns and falls back to Runner.Port for runners that do not implement it.

@callback validate_evidence() :: :ok | {:error, term()}

Optional capability preflight, checked before invoking run_evidenced/5.

@callback validate_options(keyword()) :: :ok | {:error, term()}

Validate supported per-config requirements before any subprocess is opened.