# Runs, Jobs, Todos, And Scheduled Work

## Endpoint Summary

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/v1/run` | Submit an agentic task |
| `GET` | `/v1/runs` | List runs |
| `GET` | `/v1/runs/{id}` | Get run details |
| `DELETE` | `/v1/runs/{id}` | Abort a run |
| `GET` | `/v1/todos` | List sessions with todo lists |
| `GET` | `/v1/todos/{session_id}` | Get todos for a session |
| `POST` | `/v1/todos/{session_id}` | Replace or update todos for a session |
| `POST` | `/v1/evaluate` | Evaluate a run by ID |
| `POST` | `/v1/index` | Trigger repository indexing |
| `GET` | `/v1/scheduled` | List scheduled jobs |
| `GET` | `/v1/scheduled/all` | List all scheduled jobs |
| `GET` | `/v1/scheduled/status` | Scheduled runner status |
| `POST` | `/v1/scheduled/kill` | Kill a scheduled job |
| `POST` | `/v1/scheduled/fixup` | Reconcile scheduled job state |
| `POST` | `/v1/scheduled/reconcile` | Force reconciliation |

## `/v1/run`

Submits a long-running task to the daemon and returns an accepted job record. Runs are tracked under `.omnius/jobs/`.

Common body fields:

| Field | Purpose |
| --- | --- |
| `task` | Natural language task |
| `repo` or `working_dir` | Workspace root |
| `model` | Optional model override |
| `sandbox` | Execution sandbox mode |
| `profile` | Tool profile |
| `timeout_s` | Wall-clock timeout |

Profiles are enforced twice:

- before model exposure, so disallowed tools are absent from tool schemas and prompts
- at execution time, so emitted disallowed tool calls are denied

The active profile name, source, search order, and allowed tool list are included in the accepted run metadata and persisted run record. `GET /v1/runs/{id}` is the canonical status source and includes output tail metadata when available. `/v1/runs/{id}/output` remains a raw log/delta endpoint.

For bookkeeping integrations, prefer direct calls instead of `/v1/run`:

```bash
curl -s -X POST "$OMNIUS/v1/tools/todo_write/call" \
  -H 'content-type: application/json' \
  -H 'x-omnius-session-id: tracking-turn-123' \
  -d '{"profile":"bookkeeping-tracking","args":{"todos":[{"content":"Create report","status":"in_progress"}]}}'
```

## Abort

`DELETE /v1/runs/{id}` aborts the job. The daemon signals the process group, escalates if needed, updates the job record, and decrements per-key active job counters.

## Handoff And Adoption

When a daemon restarts gracefully, live child runs can be adopted from the handoff file. The daemon polls foreign PIDs, re-arms timeouts, and finalizes job records when those processes exit.

## Todos

Todo endpoints expose the same checklist state the TUI and agent loop use. They are useful for dashboards and run supervision.

## Scheduled Jobs

Scheduled endpoints report and repair the long-running scheduler state. Use admin-scoped controls for kill or reconciliation operations.
