Eve library

Claude as a workbench agent (EVE_EVERYWHERE 8.1)

Guide

Revision 1

On this page

The second attributed lane on the intent plane: Claude Code working queue items through the SAME contract tools/eve-codex-agent.mjs uses — leases, briefs, reports, shipped claims — with its own agent id, so every action in the ledger says who did it. Two invariants carry over unchanged from the codex lane and are not negotiable:

  • verified is independently granted. Legacy graph work is closed only by the artifact-diff verifier (POST /v1/workbench/verify). Planning-backed work uses its registered verification plan and requires either a separately authenticated human verifier or the internal artifact-verifier capability. The authenticated verifier principal must differ from the credential owner that implemented the exact lease attempt.
  • Attribution is per-request. Every call carries x-workbench-agent: claude-code. For planning work, use a per-agent credential object whose tenantId and globally stable principalId are set by the trusted service configuration. Request headers cannot choose either value.

Wiring#

Environment (the BFF serves the agent surface only when a token is set):

bash
OSHUN_WORKBENCH_URL=http://127.0.0.1:4010     # the BFF
OSHUN_WORKBENCH_TOKEN=<token>                 # the claude-code entry's token
OSHUN_WORKBENCH_AGENT_ID=claude-code
OSHUN_WORKBENCH_TENANT_ID=<tenant-id>

The BFF-side map for a planning-capable agent has this shape (use a secret manager, not a tracked file):

json
{
  "claude-code": {
    "token": "<token>",
    "tenantId": "<tenant-id>",
    "principalId": "<authenticated-subject-id>"
  }
}

principalId identifies the credential owner across authentication modes. If that owner also signs in through application auth, use the same subject id; this is what makes the implementer/verifier separation check meaningful. A legacy string entry or the shared-token mode can still operate on legacy queue items but cannot lease planning-backed work.

Keep the token in the session environment or the repo-external secret file; never add it to .mcp.json or another tracked file. The MCP process inherits the parent environment, while the checked-in configuration names only the URL and attributed agent id.

Preferred: register the existing MCP server in .mcp.json so the tools (workbench_queue, workbench_lease, workbench_brief, workbench_report, workbench_shipped, workbench_verify) load directly:

json
{
  "mcpServers": {
    "oshun-workbench": {
      "command": "node",
      "args": ["tools/workbench-mcp/server.mjs"],
      "env": {
        "OSHUN_WORKBENCH_URL": "http://127.0.0.1:4010",
        "OSHUN_WORKBENCH_AGENT_ID": "claude-code"
      }
    }
  }
}

Equivalent raw contract (the MCP server is a thin wrapper over these; curl works when the MCP server is not registered):

bash
URL=${OSHUN_WORKBENCH_URL:-http://127.0.0.1:4010}
H=(-H "authorization: Bearer $OSHUN_WORKBENCH_TOKEN" -H "x-workbench-agent: claude-code" -H "content-type: application/json")
curl -s "${H[@]}" $URL/v1/workbench/queue                          # ready items
curl -s "${H[@]}" -X POST $URL/v1/workbench/items/$ID/lease -d '{"ttlSeconds":3600}'
curl -s "${H[@]}" $URL/v1/workbench/items/$ID/brief                # the work, briefed
curl -s "${H[@]}" -X POST $URL/v1/workbench/items/$ID/report \
  -d '{"phase":"progress","notes":"…"}'                            # leased → in-progress
curl -s "${H[@]}" -X POST $URL/v1/workbench/items/$ID/report \
  -d '{"phase":"completion","branch":"…","commits":["<sha>"],"notes":"…"}'  # → in-review
curl -s "${H[@]}" -X POST $URL/v1/workbench/items/$ID/shipped -d '{"observedCommitSha":"<real sha>"}'
curl -s "${H[@]}" -X POST $URL/v1/workbench/verify                 # machine judgment

The lifecycle has no shortcut: shipped refuses (illegal_transition) unless the item is in-review, which only the completion report grants. A report and its lifecycle transition commit atomically; completion also releases the active lease, so a finished item cannot appear as stale queue ownership. Lease TTLs are whole seconds from 60 through 86,400. Repeating lease as the same live holder renews either a leased or in-progress item; an expired or malformed lease is reclaimable when the queue sweeps. When OSHUN_WORKBENCH_REPO_DIR is set the shipped sha is CHECKED against origin/main (409 sha_not_on_main) — so push before you claim. Verify returns one of three honest outcomes per shipped item: verified (the expectation is met in the graph artifact), ship-verify-gap (claim and artifact disagree — recorded, never quietly closed), or not-machine-checkable (no expectation; the item stays honestly at shipped with the gap stated). Expectations speak the PRODUCT-GRAPH vocabulary only (catalog-change, e2e-suite-exists, doc-page-exists, nodes-exist) — work outside the graph (agent docs, tooling) has no honest expectation, and its terminal state is shipped-not-verified.

The loop, honestly#

  1. queue → pick ONE ready item (never bulk-lease; the machine rules allow one heavy job at a time on this Mac).
  2. lease with a 1–86,400 second TTL you will outlive; repeat lease to renew while leased or in-progress, or let it lapse — never squat.
  3. brief → do the ACTUAL work in the repo → commit it (the sha must be a real commit containing the work).
  4. report progress at real checkpoints — reports are ledger history, write them for the next reader.
  5. shipped with the observed sha only when the work is genuinely in that commit.
  6. verify and READ the outcome: verified is the only closure; a ship-verify-gap on your item means the claim and the artifact disagree — fix the work or the claim, never the gap record.

Session limits (CLAUDE.md, binding)#

At most one concurrent subagent; sequential items; checkpoint progress in reports so a killed session's successor can resume from the ledger alone.

Queue-drain recipe (EVE_EVERYWHERE 8.4)#

Draining N items in one sitting is the single-item loop run in series — the recipe is mostly about what NOT to do between items:

  1. Preflight once: use the resource checks required by the active host instructions. On Linux that is free -h, df -h / /tmp, the top-RSS process list, and the heavy-process pgrep from AGENTS.md; on the original Mac host use memory_pressure | tail -2 and tear down below 35% free. Confirm the BFF is up with the workbench token, then call workbench_queue. Pick the ORDER now — smallest-risk first — and write it into the first item's progress report so a successor session inherits the plan.
  2. Per item, strictly sequential (never lease two at once, never a parallel subagent): lease with a TTL sized to the work (renew before it lapses) → brief → do the work → commit → push (both lines, per CLAUDE.md) → completion report naming branch + commits → shipped with the observed sha → verify → READ the verdict before touching the next item. A gap or refusal on item k stops the drain: triage with get_verification_failure — do not carry a broken claim forward into item k+1's context.
  3. Checkpoint between items: the completion report is the checkpoint — a successor session resumes from workbench_queue + the ledger alone, with no memory of this one. Completion releases the lease atomically. If the session dies mid-item, the leased or in-progress hold lapses and the next queue sweep returns the item to ready; nothing to clean.
  4. Machine limits bind INSIDE the drain: one heavy job at a time (an item whose work needs a Playwright run or a build waits for the eval or dev-server slot); dev servers die with the session, and the BFF must be DOWN when an eval chunk starts (its global setup clones the dev database and refuses while connections hold it — measured 2026-08-20).
  5. Stop honestly: session/usage limit → note the reset time in a progress report and stop; NEVER mark shipped for undone work to "finish the drain". An honest half-drained queue beats a fabricated empty one.

First live traversal (2026-08-20)#

Item wi-13f2615d-5605-422b-b107-464f435df222 ("Record the Claude workbench lane runbook" — the work was writing THIS file) flowed lease → progress report → completion report → in-review → shipped (observed sha 1c80abf55bb5, pushed to origin/main first) → verify, every agent row in workbench_event attributed coding-agent | claude-code, and the verifier answered not-machine-checkable — the honest terminal for out-of-graph work, recorded here exactly as returned.