docs: upstream reconciliation triage (fork is 278 behind / 139 ahead of beam-cloud/beta9)

[Wingie]

Analysis only — no code changes, nothing merged or rebased. This is the
input to a merge @Wingie will perform.

Adds docs/upstream-reconciliation-2026-08.md.

Headline

Upstream independently built the external-agent system this fork exists to provide.

The fork was created because, delivering beta9 for a client, a part "was not
written or pushed from their side." That part was the external/remote worker
agent. beam-cloud/beta9 has since written it — and written more of it than we did.

	this fork (43800352)	upstream/main (e13aa4eb)
pkg/agent/	16 files	42 files
entrypoint	cmd/b9agent/	cmd/agent/ with install/join/vast
transport	our Tailscale wiring in pkg/gateway + pkg/network	pkg/agent/transport.go, tsnet
pool controller	pkg/scheduler/pool_external.go	pkg/scheduler/pool_agent.go
GPU reporting	gpu_type bolted onto our HTTP keepalive	joinRequest.GPU/GPUIDs/GPUCount + NormalizeGPUType()
service install	none	systemd + launchd (pkg/agent/service/)

43 upstream commits, from 4850eff8 (beam-cloud#1595) through beam-cloud#1663 fix keepalives,
beam-cloud#1661 improve gpu offerings, beam-cloud#1676 clean up gpu assignment logic, beam-cloud#1738 vast sidecar.

Triage summary

SUPERSEDED (drop): our agent + cmd/b9agent; GPU-type keepalive propagation
(this is fork PR #5 — recommend closing); the Tailscale/external-worker config
surface (directRedisHost, External*Port, External*Registry, K3S_HOST_IP);
pool_external.go (upstream renamed it to pool_provider.go and replaced its role);
~9 commits of Go/tailscale version churn; 20 MB of committed Go binaries
(b9agent 11.2 MB, bin/agent-go 9.1 MB) still tracked despite two commits
claiming removal.

STILL NEEDED (carry): the Ollama / native-MPS inference stack — git grep -il ollama
over upstream returns nothing; GPU_MPS (upstream added 29 GPU types, none Metal);
Sentry init; the agentosaurus k3d/ARM64/registry manifests + CI; SDK dep bumps
(rich<15, websockets<17); the PR #4 security fixes, which mostly guard our code.

UNCLEAR — needs your call: (1) is the MPS/Ollama inference stack still a product
requirement? It is the only substantial thing upstream lacks — if it's retired, the
whole fork can be replaced by vanilla upstream + a manifests overlay. (2) Does
upstream's agent cover the client deployment? (3) Should GPU_MPS go upstream instead?
(4) Does upstream now build multi-arch cleanly (would drop ~10 more commits)?
(5) Close PR #5? (6) OK to regenerate the 14 protobuf client files via make protocol?

Recommendation: rebuild on upstream, don't merge

A merge lands two rival agent implementations in one Go package — git surfaces this
as add/add conflicts on pkg/agent/{agent,state,state_test}.go. (They share zero
top-level identifiers, so a "keep both" resolution might even compile. That's a trap.)

Measured merge cost: 18 conflicted files, but 66 of ~91 hunks are
go.mod/go.sum/uv.lock — regenerate, don't hand-merge. The remaining ~25 hunks
are small; all three pkg/gateway/gateway.go conflicts are just our inference
registry vs upstream's changed signatures. The conflicts are not the hard part.

Full ordered plan, verification commands (from upstream's Makefile + ci.yml),
and rollback are in the doc.

Safety artifacts pushed

• tag fork-pre-upstream-sync-20260818 → 43800352 (current parent submodule pin)
• branch upstream-main-snapshot-20260818 → upstream main, so upstream history is
  in the fork without configuring a remote (this fork had no upstream remote)

Caveats

• No build, no test, no lint was run — no Go toolchain on the analysis host.
  The verification commands in the doc were read from upstream's CI, not executed.
• The parent submodule pointer was not moved; nothing was committed in the
  FlowState parent repo; main here was not touched; no containers or the k3s
  cluster were touched.
• Gateway pods have been in Init:Error for 26 days, so there is no healthy
  baseline to regress against — worth fixing before the sync so post-merge
  failures are attributable.

Co-Authored-By: Claudistrator savetheplanet@agentosaurus.com