# Claude as a workbench agent (EVE_EVERYWHERE 8.1)

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.
