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:
verifiedis 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 whosetenantIdand globally stableprincipalIdare 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):
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):
{
"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:
{
"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):
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#
queue→ pick ONE ready item (never bulk-lease; the machine rules allow one heavy job at a time on this Mac).leasewith a 1–86,400 second TTL you will outlive; repeatleaseto renew while leased or in-progress, or let it lapse — never squat.brief→ do the ACTUAL work in the repo → commit it (the sha must be a real commit containing the work).reportprogress at real checkpoints — reports are ledger history, write them for the next reader.shippedwith the observed sha only when the work is genuinely in that commit.verifyand READ the outcome:verifiedis the only closure; aship-verify-gapon 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:
- 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-processpgrepfromAGENTS.md; on the original Mac host usememory_pressure | tail -2and tear down below 35% free. Confirm the BFF is up with the workbench token, then callworkbench_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. - 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 →
shippedwith the observed sha →verify→ READ the verdict before touching the next item. A gap or refusal on item k stops the drain: triage withget_verification_failure— do not carry a broken claim forward into item k+1's context. - 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. - 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).
- 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.