feat(cli)(#48): sphere trader spawn/stop wrapper + sphere host local-* primitives

[vrogojin]

Summary

Wraps the per-user local host-manager + trader-agent bring-up into a single command. Closes unicity-sphere/sphere-cli#48.

Before this PR, each developer who wants to run an autonomous trader had to hand-orchestrate two docker containers (an agentic-hosting HM with their wallet whitelisted, then a trader-agent tenant on that HM with synthesized HM env vars) and scrape the tenant address from {event: 'sphere_initialized'} log lines. After this PR:

sphere wallet use alice
sphere trader spawn
# → prints { instance_name, tenant_direct_address, hm_container, ... }
sphere trader create-intent --tenant <addr> ...
sphere trader stop  # tears down trader + HM together

What lands

• sphere host local-spawn / local-stop / local-status — primitive HM container lifecycle, scoped to the current wallet. Idempotent.
• sphere trader spawn / stop — ergonomic wrapper that chains ensureLocalHM + HMCP hm.spawn against the local HM, then prints the tenant's reachable address as JSON or human-readable text.

Implementation notes

• Two-shot bootstrap. The agentic-hosting drift guard (host-manager/main.ts:502) fails the very first boot — intentional protection against pointing the manager at the wrong data dir post-misdeploy — embedding the real wallet pubkey in the error message. The wrapper scrapes that, restarts the container with corrected MANAGER_PUBKEY / MANAGER_DIRECT_ADDRESS, and waits for the success marker (sphere_initialized). The wallet persists in the bind-mounted volume so subsequent invocations skip the bootstrap entirely.
• Per-controller scoping. Container names use sphere-hm-<wallet-prefix>, data dirs live under ./.sphere-cli/local-hm/<wallet-prefix>/, and the diagnostics health port is derived deterministically from the wallet prefix. Two developers on the same host don't collide.
• Canonical launch pattern. buildTraderEnv() mirrors trader-service/test/e2e-live/helpers/tenant-fixture.ts:300-365 — UNICITY_CONTROLLER_PUBKEY, UNICITY_TRUSTED_ESCROWS, TRADER_SCAN_INTERVAL_MS, and the TRADER_TEST_FUND + TRADER_FAULT_INJECTION_ALLOWED=1 pair for testnet self-mint. The ACP boot envelope (UNICITY_MANAGER_PUBKEY, UNICITY_BOOT_TOKEN, UNICITY_INSTANCE_ID, UNICITY_INSTANCE_NAME, UNICITY_TEMPLATE_ID) is injected by the HM — the wrapper deliberately does NOT shadow those.
• Idempotent re-spawn. On a second sphere trader spawn call with the same wallet + name, the wrapper does hm.list first and returns the existing tenant's info instead of attempting a duplicate-name spawn (which the HM rejects with INVALID_PARAMS).
• Ref-count-aware tear-down. sphere trader stop checks via hm.list whether any other tenants remain CREATED / BOOTING / RUNNING on the local HM. Tears the HM down only when no live tenants remain. --keep-hm overrides.
• No new dependencies. Shells out to the docker CLI via child_process.execFile rather than adding dockerode. Keeps the surface narrow and audit-friendly.
• Mainnet guard. --test-fund is refused on --network mainnet — self-mint funding only makes sense on testnet/dev.

Bundled templates.json

Ships DEFAULT_TEMPLATES covering trader-agent (ghcr.io/vrogojin/agentic-hosting/trader:v0.1) and escrow-service (ghcr.io/vrogojin/agentic-hosting/escrow:v0.3) so a fresh sphere trader spawn doesn't need the operator to write a templates.json by hand. Overridable with --templates-file. Bumps to the trader image follow vrogojin/agentic_hosting#26 → CLI follow-up PR.

Test plan

• npx tsc --noEmit — clean
• npx eslint <new files> — zero warnings, zero errors
• npm test — 187 / 187 pass (45 new tests across 3 files: local-hm.test.ts, spawn.test.ts, trader-commands.test.ts)
• npm run build — tsup produces 341 KB ESM + 344 KB CJS, no errors
• node bin/sphere.mjs trader spawn --help, … trader stop --help, … host local-spawn --help render correct usage
• Out of scope: docker-touching end-to-end (covered by sphere-sdk#477 — soak reshape — once trader-agent:v0.2 from agentic_hosting#26 is published)

Related

• Closes sphere trader local-spawn / local-stop: ergonomic launch of per-user local HM + trader tenant #48
• Consumed by trader-roundtrip soak: reshape to per-user local-HM pattern sphere-sdk#477 (trader-roundtrip soak reshape)
• Requires vrogojin/agentic_hosting#26 (trader-agent:v0.2 image rebuild) to actually run end-to-end
• Indirectly serves Trader roundtrip soak + demo playbook + verify trader-agent end-to-end on testnet (Alice ↔ Bob via market intents) sphere-sdk#474 (trader-roundtrip walkthrough)