# Class LittleGhost::Execution

Documentation version: Edge

Canonical HTML: https://littleghostai.org/docs/LittleGhost/Execution.html

Runs one dormant Run in the background while the caller remains free to serve
health checks, deliver interjections, or coordinate shutdown.

    execution = agent.start_execution(message: "Investigate transfer 481") do |event|
      event_buffer << event
    end

    execution.interject(message: "Include the latest ledger entry")
    execution.wait(deadline: Time.now + 30)
    execution.run.completed? # => true

The Runtime selects a scheduled fiber or worker thread for the execution.
LittleGhost copies the caller's ExecutionState, but not other application
fiber-local or thread-local values. The Run continues to own its workspace,
sandbox, session, entrypoint, and registered resources. `close` requests
cooperative cancellation and waits for the execution and any in-flight
interjection calls.

## Inheritance

`LittleGhost::Execution < Object`

## Attributes

<a id="attribute-i-run"></a>
### `run` (R)

The supervised Run.

## Class methods

<a id="method-c-start"></a>
### `.start`

```ruby
.start(run, &event_consumer)
```

Starts `run` immediately and returns its supervising Execution. If the work
cannot start, this method closes `run` before raising.

The optional block receives each StreamEvent from the fiber or thread running
the Execution. It must not depend on a particular thread and should not pause
the scheduler or retain sensitive event content longer than the application
requires.

## Instance methods

<a id="method-i-active-3F"></a>
### `#active?`

```ruby
#active?()
```

Indicates that the Execution or an interjection call is still active.

<a id="method-i-cancel"></a>
### `#cancel`

```ruby
#cancel()
```

Requests cooperative cancellation and returns `self`.

<a id="method-i-close"></a>
### `#close`

```ruby
#close(deadline: nil)
```

Prevents new interjections, requests cancellation, and waits for shutdown. The
operation is idempotent. `deadline` has the same meaning as in #wait.

<a id="method-i-error"></a>
### `#error`

```ruby
#error()
```

Returns an event-delivery or cleanup exception raised by the Execution.

<a id="method-i-finished-3F"></a>
### `#finished?`

```ruby
#finished?()
```

Indicates that the Execution and all interjection calls have finished.

<a id="method-i-interject"></a>
### `#interject`

```ruby
#interject(payload = nil, **options)
```

Prepares and delivers one interjection to the active run.

`payload` may be a message or a Hash containing `message` and the options
accepted by Run#interject. Runtime hooks receive the Hash before delivery,
allowing them to materialize trusted application attachments. Calls may
overlap, but `close` prevents new calls and waits for calls that have already
begun.

<a id="method-i-state"></a>
### `#state`

```ruby
#state()
```

Returns `:pending`, `:running`, or
`:finished`.

<a id="method-i-wait"></a>
### `#wait`

```ruby
#wait(deadline: nil)
```

Waits for the Execution and in-flight interjections, then returns the Run.

`deadline` is an absolute Time. Reaching it raises DeadlineExceededError
without cancelling the run. An event-delivery or cleanup failure raised by the
Execution is re-raised after all supervised work finishes.