# 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 |
| `GET` | `/v1/runs/{id}/output` | Read captured run output and status |
| `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` | Replace or update todos for a session |
| `DELETE` | `/v1/todos/{session_id}` | Delete todos for a session |
| `POST` | `/v1/evaluate` | Evaluate a run by ID |
| `POST` | `/v1/index` | Trigger repository indexing |
| `GET` | `/v1/scheduled` | List scheduled jobs |
| `DELETE` | `/v1/scheduled/all` | Remove all scheduled tasks, timers, cron entries, and sources |
| `GET` | `/v1/scheduled/status` | Scheduled runner status |
| `POST` | `/v1/scheduled/{id}` | Enable or disable one task/timer |
| `DELETE` | `/v1/scheduled/{id}` | Delete one task/timer |
| `POST` | `/v1/scheduled/kill` | Kill a scheduled job |
| `POST` | `/v1/scheduled/fixup` | Reconcile scheduled job state |
| `GET`/`POST` | `/v1/scheduled/reconcile` | Preview or apply reconciliation |
| `GET` | `/v1/services/systemd` | List user-level services |
| `POST` | `/v1/services/systemd/{unit}` | Act on one user-level unit |
| `GET`/`POST` | `/v1/update` | Inspect or start a verified exact-version global update |

## `/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. Concrete
actions (`kill`, `fixup`, and `reconcile`) are matched before the generic
`/{id}` enable/disable route. Use admin-scoped controls for destructive actions.

`POST /v1/update` starts the same durable install/verify/restart transaction used
by the TUI, dashboard, and tray. Poll the GET form for live output and exact
package, executable, daemon, hash, and tray verification.