Federation step 1: peers + strut/run-workflow (dispatch-through first, for a local strut calling a cloud explorer agent)

[Evanfeenstra]

Two commits: the plan amendment, then the build of its step 1.

1. plans/federation.md — the 2026-10-08 rulings

The use case in hand is a local (desktop) strut asking a swarm's strut to walk that swarm's knowledge graph and return what is relevant. That flips the plan's order: peers + strut/run-workflow + @slug in the builder come first; read-through follows on the same peer record.

• The step waits on the peer's SSE tail, reattaching with ?skip=N, never a callback: a strut behind NAT can reach a cloud strut but cannot receive a POST, and no strut knows its own public URL.
• A peer is named by the hive workspace slug, what a person types as @slug.
• A local strut gets its peers through a paste door (STRUT_PEERS, a Peers dialog), since hive cannot push to it. New Local tier row.
• job is an explicit field on the step, never forwarded from ctx.job: no shared directory across struts.
• The pushed scope is lab:peer (read, launch, control what it launched); lab:read stays for a central that only reads.
• Billing across the call and actor secrets are deferred. The org fan-out of plans/org-gateway.md §3 is not built in hive, and an explorer needs neither.

2. Step 1 built

• src/peers.ts. A peer is { id, baseUrl, token, label? } in a fourth encrypted file, peers.json, behind PUT / DELETE / GET /peers (the GET returns ids, labels and base URLs, never a token). STRUT_PEERS and createStrut({ peers }) are the paste door. ctx.services.peers names a peer and makes a request with the token injected; the token is readable by nothing. The client the step and the builder share: launchOnPeer, tailPeerRun (reattach with ?skip=N, backoff, abort), cancelOnPeer, runOnPeer.
• strut/run-workflow. POST …/run on the peer with this run's principal as x-strut-actor, then the tail. Cancelling the caller's run POSTs cancel to the peer. wait: false returns the handle. job is explicit only. Output: { peer, workflow, runId, status, output?, error?, durationMs }; an artifact path in it is the peer's.
• The builder. list_peers, and peer on list_workflows / get_workflow / run_workflow; the prompt says @<id> names a peer and a peer run is awaited, never detached.
• Docs. specs/API.md §10, AGENTS.md (layout, env row, key concept), the plan's step 1 marked built.

Two calls that differ from the plan text, both written into it: the capability sits on the services bag (the step has to reach the peer somehow; the token stays inside the process, and the token's scope bounds what a step can do through it), and GET /peers includes baseUrl.

Tests: src/peers.test.ts — the store, the capability, launch/tail/cancel against a fake peer (reattach, backoff, abort, refusals), the routes, and two struts over real HTTP (listen(0)): result and actor forwarded, job only when named, wait: false, cancel propagation, unknown peer, refused launch. Three AI tool tests. The route-sweep test covers the new routes behind the key. 1360 tests pass.

Not in this slice: a Peers dialog, pause/resume forwarding to the peer, the lab:peer scope in mcp, read-through. A peer token today is the peer's whole key, so a laptop should not hold one until the scope lands.