trader-roundtrip soak: reshape to per-user local-HM pattern

[vrogojin]

Why

The current manual-test-trader-roundtrip.sh (PR #475 / issue #474) is written against a shared host manager: it assumes HOST_MANAGER (or SPHERE_HOST_MANAGER) points to one HM that both alice and bob can spawn trader tenants on. Two problems with that:

1. Auth model mismatch. A host manager whitelists AUTHORIZED_CONTROLLERS at boot; the public HM allows exactly one controller pubkey at a time. The soak creates two fresh wallets each run, neither of which is on the whitelist. To run the soak end-to-end against a shared HM, the operator has to edit manager.env and restart the HM container per run — impractical.

2. Architectural intent. Per project owner guidance, the design is for each developer to run their own local HM scoped to their controller pubkey. The public HM is reserved for shared services (escrow, faucet, etc.). The soak should mirror that — alice brings up her own local HM, bob brings up his.

What changes

Once sphere trader spawn / stop lands in sphere-cli (unicity-sphere/sphere-cli#47-or-similar), reshape §3 / §11 of manual-test-trader-roundtrip.sh:

Today (§3):

sphere host spawn alice-trader-$SUFFIX \
  --template trader-agent --nametag alice-trader-$SUFFIX \
  --env UNICITY_CONTROLLER_PUBKEY=<alice-pubkey> ...

After the wrapper lands:

cd "$PEER_ALICE"
sphere wallet use alice
ALICE_TRADER_ADDR=$(sphere trader spawn --name alice-trader-$SUFFIX --json | jq -r .agent_address)

cd "$PEER_BOB"
sphere wallet use bob
BOB_TRADER_ADDR=$(sphere trader spawn --name bob-trader-$SUFFIX --json | jq -r .agent_address)

Each sphere trader spawn brings up its own HM + tenant scoped to the current wallet's controller pubkey. No shared HM. No HOST_MANAGER env var. No AUTHORIZED_CONTROLLERS editing.

§11 cleanup becomes:

cd "$PEER_ALICE" && sphere wallet use alice && sphere trader stop --name alice-trader-$SUFFIX
cd "$PEER_BOB"   && sphere wallet use bob   && sphere trader stop --name bob-trader-$SUFFIX

Everything in between (§4 ready-check, §5 fund, §6/§7 post intents, §8 wait for completion, §9 assert deltas) stays the same — the wrapper makes the tenant's address available, but post-spawn the existing sphere trader create-intent --tenant <addr> flow is unchanged.

Acceptance

• Soak script's # KNOWN LIMITATIONS block updated to remove the controller-auth caveat.
• Soak script drops HOST_MANAGER and SPHERE_HOST_MANAGER env contracts; replaces with --name slugs.
• §11 cleanup uses sphere trader stop; the KEEP_TENANTS=1 flag forwards to --keep-hm --keep-data.
• Soak's wall-time budget revised — local-HM-per-user adds startup time vs shared HM. Bumping TRADER_DEAL_DEADLINE_S default from 600 to 900 s likely necessary.
• End-to-end testnet validation: 3-of-3 consecutive runs of the reshaped soak pass.
• Demo playbook (docs/DEMO-PLAYBOOK-TRADER-ROUNDTRIP.md) §3 narrative updated — "alice spins up her own trader" is a stronger demo beat than "alice issues a spawn against the shared HM."

Out of scope

• The wrapper itself (sphere trader spawn / stop) — tracked in sphere-cli.
• The trader image rebuild — tracked in agentic_hosting.
• Integration of the trader engine into sphere-sdk as a MarketModule extension — separate conversation.

Related

• sphere-sdk#474 / PR feat(trader)(sphere-sdk#474): roundtrip soak + demo playbook + spec drift audit + #473 investigation #475 — the original soak; this reshape comes on top.
• unicity-sphere/sphere-cli wrapper issue (just filed; will link once URL known).
• vrogojin/agentic_hosting#26 — trader-agent:v0.2 image rebuild (also a prerequisite).

[vrogojin]

Reshape committed

The soak script + demo playbook reshape per this issue is now committed on feat/474-trader-roundtrip-soak (commit a66b63f), pushed up to PR #475.

What changed in this commit

manual-test-trader-roundtrip.sh

• §3 now uses sphere trader spawn --name <slug> --trusted-escrows $ESCROW --json per peer (replaces sphere host spawn --manager $HOST_MANAGER --template trader-agent --env UNICITY_CONTROLLER_PUBKEY=... --env SPHERE_NAMETAG=... --env ESCROW_ADDRESS=...).
• §4 simplifies to a single ACP smoke probe; the wrapper's --ready-timeout-ms covers the container-running wait the old sphere host inspect did.
• §11 cleanup switches to sphere trader stop --name <slug> [--keep-hm]. KEEP_TENANTS=1 forwards --keep-hm; the wrapper auto-tears down the per-user HM when the last tenant stops.
• TRADER_DEAL_DEADLINE_S default bumped 600 → 900s to cover per-user HM bootstrap (two-shot drift-guard restart).
• Env contract pruned: HOST_MANAGER / SPHERE_HOST_MANAGER / TRADER_TEMPLATE_ID / TRADER_IMAGE_OVERRIDE / UNICITY_CONTROLLER_PUBKEY all removed. Preamble now documents the sphere-cli#49 wrapper + docker prerequisites.
• KNOWN LIMITATIONS block: dropped the controller-auth whitelist caveat and the host-CLI-no-image-flag caveat. Image-staleness caveat now points at vrogojin/agentic_hosting#26.

docs/DEMO-PLAYBOOK-TRADER-ROUNDTRIP.md

• §3 narrative rewritten as "each peer spins up its OWN local trader tenant" — stronger demo and accurate to the per-user local-HM design.
• Pre-flight checklist swaps sphere host list for docker info.
• §7.5 sidebar switches from sphere host cmd TAIL_LOGS to direct docker logs -f sphere-trader-<wallet>-<name>.
• Cheat sheet + command quick reference + exit-codes table all updated.

Acceptance checklist

• # KNOWN LIMITATIONS updated — dropped controller-auth caveat
• Dropped HOST_MANAGER/SPHERE_HOST_MANAGER env contracts; replaced with --name slugs
• §11 cleanup uses sphere trader stop; KEEP_TENANTS=1 forwards --keep-hm
• TRADER_DEAL_DEADLINE_S default 600 → 900s
• Demo playbook §3 narrative updated
• bash -n manual-test-trader-roundtrip.sh parses cleanly
• End-to-end 3-of-3 verification — pending wrapper + image prerequisites

Outstanding (out of scope for this commit)

End-to-end verification is gated on:

1. feat(cli)(#48): sphere trader spawn/stop wrapper + sphere host local-* primitives sphere-cli#49 merging into sphere-cli main (the sphere trader spawn / sphere trader stop wrapper)
2. vrogojin/agentic_hosting#26 landing (trader-agent:v0.2 image rebuild against post-@escrow-testnet nametag does not resolve on testnet relay (swap soak blocked) #456/swap: proposeSwap silently falls back to chainPubkey when transportPubkey missing — DM lost into black hole #457/transport(mux): MuxAdapter.dispatchTokenTransfer (and siblings) discard async-handler Promise — receive() resolves before handleIncomingTransfer completes #464 sphere-sdk)

Once both prerequisites ship I'll run the full 3-of-3 round-trip and post results back here.