Eve library

Eve worker and reviewer operation

Runbook

Revision 5

On this page

Eve worker and reviewer operation

This runbook describes the separate worker and reviewer roles. Tasks, review reports and documents live in Eve. This document is a draft for independent review; it does not enable automation or authorize a publication.

Interactive operation

Codex and Claude Code both support interactive worker or reviewer sessions. Select the appropriate scoped Eve credential with EVE_API_CONFIG before starting the interactive session. Use the registered oshun-eve MCP tools or ./eve. Do not change the author credential into a reviewer credential.

On the coding server, the unattended worker credential is /srv/eve-codex/worker/.config/oshun/eve-api.json and the separate reviewer credential is /srv/eve-codex/reviewer/.config/oshun/eve-api.json. These files are private. Do not print or copy their contents into conversations, source files or reports.

A worker checks ./eve reviews --author <identity> --state changes-requested, implements one task, runs relevant checks, commits and pushes to origin/main, then uses ./eve done with its fencing token, full pushed commit SHA and verification evidence. Do not edit historical tracker checkboxes.

A reviewer runs ./eve reviews sync, then ./eve reviews claim [review-id]. Read the exact task commit or submitted document revision and its evidence. Renew the ten-minute review lease with ./eve reviews renew <id> --token <token>. Complete using ./eve reviews complete <id> --token <token> --report-file <private-json-file>, or the equivalent eve_review_command MCP tool. Use a new UUID request ID for each logical mutation, and retain that ID when retrying the same operation. Use ./eve reviews reconcile <id> if a document outcome needs reconciliation after an interruption.

Review findings must identify the problem, its location, evidence and required fix. Decisions are approve, request-changes or needs-evidence. A task review checks acceptance criteria, the exact diff, tests, regressions and linked documentation. Content reviews check the appropriate requirements, reasoning, accuracy, sources, links, diagrams and rendering evidence. Record the interactive engine in the report model field.

A reviewer does not implement fixes. Requested task changes reopen the original task and preserve its history; authors fix, test and resubmit with a new pushed commit. Requested document changes return the document to draft. Resubmission pins a new revision. PRD, ADR and architecture approvals require an independent human. Neither reviewer approval nor a worker completion publishes content or promotes UAT.

Unattended operation

Only Codex runs unattended. Dev administrators control Automatic worker and Automatic reviewer independently in https://docs.dev.oshunsynthetics.com/workspace?view=reviews. Both default off. Off prevents new unattended claims while the current job may finish. Interactive sessions remain independent. Agent API keys cannot change these switches.

The runner host is 204.168.220.77. Linux accounts eve-codex-worker and eve-codex-reviewer have separate private homes and API credentials. The worker uses /srv/eve-codex/worker/repository. The reviewer reads a root-owned Git mirror and cannot write implementation code. Codex authentication reuses the existing server login with the owner’s authorization. Root’s existing login file is preserved.

The systemd timers eve-codex-worker.timer and eve-codex-reviewer.timer poll approximately once a minute and start after reboot. Their services process one job at a time under non-root accounts and memory/CPU limits. The eve-codex-source.timer refreshes the read-only origin/main evidence mirror. Polling while switches are off does not launch Codex. Check systemctl status and journalctl for the corresponding service as the operator.

The worker has board:read, board:work, board:author, content:read and content:write. The reviewer has board:read, board:review, content:read and content:review. Neither has publication or key-administration privileges. Initial runner keys expire on 2026-12-20; renew before expiry using the operator key-management workflow.

The unattended reviewer accepts only bounded evidence-backed reports. It records missing or oversized evidence rather than approving unsupported conclusions. Code review requires a trusted successful Dev CI receipt for the exact submitted commit; a main-poll deployment can skip intermediate commits, so a missing receipt may require an operator-directed test or interactive review. Presentation approval still requires independent rendering and accessibility evidence.

Recovery and maintenance

If the worker cannot confirm a clean checkout, a pushed commit and a completed Eve submission, it preserves its checkout and /srv/eve-codex/worker/.local/state/oshun/worker/worker-recovery.json, writes a task note when possible, and refuses another task. Turn the worker off, inspect the task journal, Git status and pending API requests, resolve or preserve the interrupted work, then remove the recovery record only after the operator has confirmed a consistent state.

The reviewer saves an interrupted completion in /srv/eve-codex/reviewer/.local/state/oshun/reviewer/pending-review.json. It retries that same outcome and request identity, including after Off, without another model invocation. Do not discard that record before reconciling the Eve result.

If Codex authentication expires, sign in or renew the dedicated account’s login before enabling it; the runner checks login status before claiming work. If the worker loses GitHub access, restore its repository-scoped deploy key. Do not replace it with a personal private key. Do not prune /srv/eve-codex/source.git: the dedicated worker checkout borrows its Git objects.

Install or upgrade the reviewed runner source using infra/hetzner/eve/install-agent-runner.py. Keep both dashboard switches off during setup and verification. The installer does not change them. Its Codex-specific Ubuntu namespace profile enables sandbox creation without disabling the host-wide namespace restriction. The worker sandbox permits only its checkout Git metadata and build caches in addition to the normal workspace.

Verified setup and publication controls

The runner connection and both Off switches were verified against deployed Dev commit d66a77abadeb0b237fe6c733046930afa82473ac. Polling is enabled after reboot; neither worker nor reviewer was enabled for unattended work during setup. Turn on only the role you want in Eve’s Review workspace.

Reviewer approval makes a revision eligible for publication. It does not publish it. An administrator explicitly freezes a content publication in Eve’s Publications workspace. Automatic main deployments preserve that selected set of document revisions, media and source paths as the application code changes. Newly reviewed content enters a site only after a separate content selection.

UAT requires explicitly promoting an exact Dev publication with passing deployment evidence. UAT content is a read-only tested snapshot. Its tasks and reviews cannot mutate canonical Dev work, and it has no unattended-runner switches.

Application, Docs Center and Presentation Center hosting is on Hetzner under oshunsynthetics.com. GitHub stores repository code and runs checks; it does not host or publish a separate site.

Content CI on the coding-worker server

Checks that read authored documents run in the Eve content CI on the coding-worker server, not in GitHub: the recovery drills (disaster-recovery and runbook suites, game-day rotation, acceptance drill, follow-up retests) and the 190 V1 workbench inventory commands registered in tools/eve-content/workbench-checks.json. The eve-content-ci account holds only a board:read/content:read key and its own rootless Docker daemon. For each new Dev publication it checks out the exact pinned commit, exports and verifies the publication, and runs tools/eve-content/content_ci.py inside check_workspace.py; the timer runs every 30 minutes. Reports and receipts: /srv/eve-content-ci/state/runs; status: python3 /usr/local/lib/eve-content-ci/content-ci.py status.