# AGENTS.md: browser kcp + socialweb (iPhone) test handoff This fork (`origin` https://github.com/johnandersen777/kcp, branch `kcp-wasm-memory-storage`, tag `iphone-working-v0`) runs real kcp and the socialweb control plane compiled to js/wasm in a browser tab. The page requests a VM from the socialweb market (bidders run by the lead), waits for it to be Held, and opens a shell on it: `ssh` over WebRTC from the page's terminal (primary), or the wootty web shell over opentunnel (fallback). State at `iphone-working-v0` (2026-10-25): on an iPhone in Firehose mode (no ingress), request -> Held 40-72 s, ssh datachannel open 4-5 s after the offer (host/udp on the home LAN), release through the tab's EphemeralInfra. Idle allocation ~100-150 MiB/min, 3-4 GCs/min. Open: 1-3 GB/min while a contract runs, from socialweb re-applying unchanged ComponentLinks/EventSources/ EventStreams (~900 no-op applies/min); the lead is fixing it. ## Layout | Path | What | | --- | --- | | `~/src/kcp/kcp-wasm` | main checkout on the lead's host (hat-8, Fedora, user johnandersen777), branch `kcp-wasm-memory-storage`; the dev server serves this tree (page JS from `scripts/browser/`, wasm from `bin/wasm/`) | | `~/src/kcp/kcp-wasm/.claude/worktrees/` | worktrees (agents get one each): edit and build here, then fast-forward the main checkout | | `bin/wasm/` | built wasm, not in git; a fresh worktree copies it from the main checkout (`cp -a ~/src/kcp/kcp-wasm/bin/wasm/. bin/wasm/`) | | `~/src/kcp/socialweb-computer-kcp` | socialweb source (the lead's; read only for agents; `git -c safe.directory='*'`) | | `~/.tmp/claude-kcpwasm` | dev-server debug files (`debug.log`, `control.ndjson`, profiles) and the lead's helpers: `takeover.sh`, `tunnel-watchdog.sh`, `page-hold.ts`, `boot-smoke.ts` | | `scripts/browser/` | the page: `app.js`, `kcp_worker.js`, `oauth_refresh_worker.js`, `vmshell.js`, `webrtc_guest.js`, `ssh_cmd.js`, `identity_ui.js`, `debug_link.js` (debug log + control stream) | | `socialweb-wasm/` | Go glue: `cmd/kcp-wasm` (wasm main, refresher bridge, memstats), `internal/socialweb/orchestrator.go` (MarketRequester `app`, comms mode, events.Register) | | `contrib/wasm/storage` | kcp's in-memory storage for wasm (per-resource update counters live here) | | `scripts/prepare-kcp-patched-modules.sh` | patches k8s modules for wasm (incl. the JSON fast path for apply bodies) | | `scripts/kubectl_wasm_web.ts` | dev server (static files + `/debug/*` hooks) | | `scripts/browser-demo.ts` | drives a phone through the whole VM test and records it to `demos/` | | `scripts/browser-dev/{build-page.sh,phone.sh}` | build/deploy and one-shot page commands | | `contrib/wasm/FUTURE_WORK.md` | open items (build-time snapshot secrets, Firehose on a phone) | ## Build and deploy ```sh export TMPDIR=~/.tmp # never /tmp cd ~/src/kcp/kcp-wasm/.claude/worktrees/ REV= DEPLOY=1 scripts/browser-dev/build-page.sh # ~1 min incremental git add ...; git commit # commit in the worktree git -C ~/src/kcp/kcp-wasm merge --ff-only # page JS is live now git -C ~/src/kcp/kcp-wasm push origin kcp-wasm-memory-storage # helper modules (kubectl, kubectl-slim, goat, yq, ssh) into bin/wasm, rarely needed: make build-kubectl-wasm build-goat-wasm build-yq-wasm build-sshclient-wasm # goat/yq: GO_CLI_TOOLCHAIN=go1.27.3 (the default) ``` Notes: - `build-page.sh` defaults: `SOCIALWEB_SRC=~/src/kcp/socialweb-computer-kcp`, `MAIN_CHECKOUT=~/src/kcp/kcp-wasm` (DEPLOY target), `TMPDIR=~/.tmp`. - The build mirrors socialweb at REV into `.work/socialweb-mirror`, 3-way merges the compose.go overlay onto it and syncs `socialweb-wasm/manifests` (commit those). A new socialweb schema needs that sync or the page logs `field not declared in schema`. - Merging into the main checkout deploys page JS immediately; `bin/wasm/kcp.wasm` is only replaced by `DEPLOY=1`. Do not merge half-finished page changes while a phone test runs. - The page re-applies the socialweb manifests when the kcp.wasm ETag changes (recorded only after a full boot). - Commit the user's own uncommitted edits in the main checkout before merging (small commit of their diff), never discard them. - Browser unit tests: `cd scripts/browser && deno test --allow-read --allow-net`. - Policy suite, page half (`always-run/page/...`, names shared with socialweb's policy tests): `scripts/browser-dev/policy-suite.sh` (deno tests, the headless Chrome fence check, the js/wasm browsersandbox Go tests; needs `.work`). Storage tests: `cd contrib/wasm/storage && GOTOOLCHAIN=go1.26.9 go test ./`. ## Dev server, public URL, phone The lead runs the :8090 server and the tunnel; agents do not touch them and start their own server on a free port for tests (no `--origin`, page at `http://127.0.0.1:/?debuglog=1`, debug files under `~/.tmp/`). ```sh D=~/.tmp/claude-kcpwasm; mkdir -p $D cd ~/src/kcp/kcp-wasm && deno run --allow-read --allow-net --allow-write=$D \ scripts/kubectl_wasm_web.ts --port=8090 \ --origin=https://kcpwasm--johnandersen777-bsky-social.fedproxy.com \ --debug-log=$D/debug.log --debug-control=$D/control.ndjson \ 2>&1 | tee $D/server8090.log # run in the background bash $D/takeover.sh 2>&1 | tee -a $D/tunnel.log # public tunnel, background bash $D/tunnel-watchdog.sh 2>&1 | tee -a $D/watchdog.log # background ``` - `takeover.sh` waits until the public URL fails twice (60 s apart), then loops `ssh -NnT -p 2222 ... -R kcpwasm:80:127.0.0.1:8090 johnandersen777.bsky.social@fedproxy.com`. - The fedproxy legacy ssh relay drops the whole forward after one failed forwarded-tcpip channel open while ssh stays connected, so `tunnel-watchdog.sh` kills that ssh when the public URL fails twice (checked every 60 s) and the takeover loop reconnects it. - Phone/desktop URL: https://kcpwasm--johnandersen777-bsky-social.fedproxy.com ("no route configured for host", a 404, from fedproxy = the tunnel is down). - Production is static files; the `/debug/*` hooks exist only on this dev server. Profiles turn on only when `HEAD /debug/control` answers 204. `scripts/deploy.sh` builds `public/` from `bin/wasm`, writes the OAuth client metadata for https://console.socialweb.computer and ships it to the socialweb.computer host (`root@socialweb.computer -p 1997`, Caddy site `/etc/caddy/sites/console.socialweb.computer.caddy`). Another origin is another OAuth client and browser storage: sign in again there. - iOS gets low-memory mode automatically (no snapshot, lazy kubectl, GOGC 25, watch cache off). iOS kills the tab near ~630 MiB of wasm memory. ## Debug log and remote control of a page - Every page served by the dev server streams its console, worker logs, Go logs (`kcp: go:` lines), terminal output (`term`) and command results to `~/.tmp/claude-kcpwasm/debug.log`, one line each: `