> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nika.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Run and cancel

> Stream a local run, await its settled outcome and pass caller-owned cancellation.

export const LocalContract = () => <Tip>
    <strong>Live surface.</strong> <code>@supernovae-st/nika-client/local</code>
    drives the released <code>nika</code> binary through its versioned machine
    contracts. It is the production path today.
  </Tip>;

<LocalContract />

A local run exposes two truths at once: the journal while work is happening
and the outcome after the child process settles.

## Stream and settle

```ts theme={"system"}
const handle = nika.run('workflows/release.nika.yaml', {
  maxCostUsd: 0.25,
})

for await (const event of handle) {
  timeline.accept(event)
}

const outcome = await handle.outcome
if (!outcome.ok) process.exit(outcome.exitCode)
```

The handle is an `AsyncIterable` and owns an `outcome` promise. Keep both.
A UI can ignore an event kind it does not render, but it must not infer
success from the last kind it recognized.

## Buffer when progress is not visible

```ts theme={"system"}
const outcome = await nika.runToEnd('workflows/release.nika.yaml', {
  model: 'mock/echo',
  maxCostUsd: 0,
})

console.log(outcome.events)
```

`runToEnd()` drains the same iterator and returns the accumulated events.
It is convenient for a worker, test or command whose interface does not need
live progress.

## Let the caller cancel

```ts theme={"system"}
const controller = new AbortController()
const timer = setTimeout(() => controller.abort(), 30_000)

try {
  await nika.runToEnd('workflows/release.nika.yaml', {
    signal: controller.signal,
  })
} finally {
  clearTimeout(timer)
}
```

Pass the request or job owner's signal. Do not create a hidden process timeout
that the caller cannot observe or cancel.

## Exit contract

| Exit | Meaning                   |
| ---- | ------------------------- |
| `0`  | Completed                 |
| `1`  | Workflow ran and failed   |
| `2`  | Findings or start refusal |
| `3`  | Environment failure       |
| `4`  | Durable pause             |

## Continue

<CardGroup cols={2}>
  <Card title="Run events" icon="wave-pulse" href="/sdk/runtime/events">
    Design an additive event reducer.
  </Card>

  <Card title="Errors and exits" icon="triangle-exclamation" href="/sdk/runtime/errors">
    Keep refusal classes separate.
  </Card>

  <Card title="Receipts" icon="link" href="/sdk/runtime/receipts">
    Preserve proof after the stream closes.
  </Card>

  <Card title="Method index" icon="list" href="/sdk/reference/methods">
    Scan every local and remote method.
  </Card>
</CardGroup>