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

# Remote-First Runtime State

> How Onyx separates server-owned research state from local runtime files.

Onyx research is remote-first. Supabase and the `/api/v1` API own projects,
campaigns, sessions, hypotheses, worker leases, lifecycle state, experiment
acceptance, summaries, knowledge, best projections, stop state, and git
verification. Local workers still run in your checkout, but they report directly
to the API instead of writing a local research database and replaying events
later.

`.git/onyx/` remains important, but it is runtime storage, not the product source
of truth. It keeps logs, workflow files, manifests, lock files, and recovery
hints that help humans understand or salvage local work.

## Local Runtime Files

Onyx stores local runtime artifacts under `.git/onyx/`.

| File or directory                        | Purpose                                                                                                                                |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `state.json`                             | Convenience pointers for the active project, campaign, session, profile hints, and supervisor metadata. The API remains authoritative. |
| `workflow-runs/<workflowRunId>/`         | Step logs, metrics, and status files for a local measured workflow attempt.                                                            |
| `attempts/<runRef>/`                     | Local terminal attempt metadata used by worker finalization and recovery.                                                              |
| `worker-logs/<sessionId>/`               | Raw provider logs, readable activity logs, structured activity events, latest-state snapshots, and worker manifests.                   |
| `worker-runtime/<sessionId>/<workerId>/` | Isolated worker context, temporary files, and per-worker command wrappers.                                                             |
| `resource-locks/`                        | Atomic local resource lock files with owner, pid, expiry, and stale-lock cleanup.                                                      |
| `events.jsonl`                           | Best-effort debug activity feed. It must never be treated as the source of truth.                                                      |

These files are safe to delete when you intentionally reset local runtime state,
although doing so may remove useful recovery information for in-flight workers.
They are not an offline campaign ledger.

## Online Requirement

Research product commands require API access. Campaign setup, session creation,
worker lease acquisition, worker heartbeat, experiment reporting, summaries,
knowledge, status, stop, and list commands read or write server state directly.
If the API is unavailable, the command fails visibly instead of hiding the work
behind a durable pending queue.

Workers still preserve local evidence when something goes wrong. For example, if
a worker successfully commits but cannot push the immutable result ref, its
manifest records the branch, commit, intended ref, and recovery instructions. If
it pushes the ref but the API report fails, the manifest records the pushed ref
so an operator can inspect or repair it.

## Worker Leases and Acceptance

The server owns worker slots and accepted experiment ordering.

* Before launching provider processes, the supervisor asks the API for worker
  leases in idempotent batches. Each grant includes the worker id, lease token,
  expiry, assigned hypothesis, campaign/session context, and project/git context.
* The supervisor owns normal batch heartbeat renewal. Direct worker heartbeats
  remain available as a fallback/debug primitive; terminal heartbeats release
  slots.
* Workers push `HEAD` to an immutable ref such as
  `refs/onyx/experiments/<campaignId>/<runRef>` before reporting an experiment.
* Experiment reports never choose `acceptedIndex`. Report requests record or
  deduplicate quickly; server settlement later assigns accepted/discarded
  disposition and accepted indexes.
* Late reports are preserved as discarded diagnostics for lineage/debugging but
  do not count toward session targets, rankings, or best projections.

## GitHub Repository Sync

The word "sync" still appears in one place: repository metadata refresh through
the GitHub App. That process updates installation metadata, repository access,
default branch heads, and code-read availability. It is separate from research
state reporting and is not the old research event-replay layer.

## Useful Commands

```bash theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
onyx status
onyx research status
onyx listen
onyx-worker workflow status
onyx-worker exp list --limit 20
```

* `status` shows the active profile, API target, and cached project/campaign
  pointers.
* `research status` and `listen` read live server state plus local supervisor
  runtime files when available.
* `workflow status` shows local workflow runs, step summaries, metrics, block
  reasons, and log paths.
* `exp list`, `knowledge list`, and `summary list` read remote API state.