feat(0.3.0): HTTP transport + OpenAPI via huma; auth guard for non-loopback

Adds a REST surface alongside the unix socket. One daemon serves both; the
repo's own locks serialize concurrent mutations across transports.

internal/api/http.go (huma v2 + humago adapter)
- Typed Input/Output structs → OpenAPI 3.1 spec at /openapi.json + interactive
  docs at /docs, both always in sync with the running code.
- 12 endpoints (head/log/branches/show/diff/commit/checkout/delete/tags
  get+set/tournament/gc). Streaming exec stays socket-only (SSE follow-up).
- isLoopback(): bare ":PORT" treated as non-loopback (Go binds all
  interfaces) so the no-token guard does the safer thing. Unit test pins
  the rule.
- bearerAuth: /v1/* requires Authorization: Bearer <AGENTENV_HTTP_TOKEN>;
  /openapi.json + /docs stay open for discoverability. Unit-tested.

cmdDaemon takes --http :PORT (or AGENTENV_HTTP), opens the HTTP listener in a
goroutine. AGENTENV_HTTP_TOKEN required for any non-loopback bind, checked at
startup (won't quietly expose itself).

examples/http_client.sh: curl walkthrough.

README + examples/README + CHANGELOG updated to call out the new transport,
the discoverability of /docs, and the headline use case (curl/Postman/SDK
generation, all without a socket library).

Author: css521

CHANGELOG.md

@@ -4,9 +4,30 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/), and the project aims to follow
 [Semantic Versioning](https://semver.org/).
 
-## [Unreleased]
+## [0.3.0] - 2026-06-17
 
 ### Added
+- **HTTP transport + OpenAPI**: `agentenv daemon --http :PORT` (or
+  `AGENTENV_HTTP=":PORT"`) opens a REST surface alongside the unix socket.
+  Built on `huma` v2 — every typed handler signature contributes to an
+  OpenAPI 3.1 spec served at `/openapi.json`, with interactive docs at
+  `/docs`. 12 endpoints grouped into 4 tags (History / Mutation / Branching /
+  Tags) cover head/log/branches/show/diff/commit/checkout/delete/tags(get,
+  set)/tournament/gc; streaming `exec` stays socket-only (SSE port is
+  follow-up). Loopback is no-auth; non-loopback binds require
+  `AGENTENV_HTTP_TOKEN` (verified at startup — won't quietly expose itself).
+  See `examples/http_client.sh` for a curl walkthrough.
+- `docs/openapi.json` — pretty-printed snapshot of the live spec, so GitHub /
+  reviewers / SDK generators can read it without running the daemon.
+  `make openapi-snapshot` regenerates it from a one-off daemon (run before
+  tagging a release).
+- `examples/mcp_client.py`: drive `agentenv mcp` over JSON-RPC stdio from any
+  language (no Claude Code needed) — covers `agentenv__log` / `__branches` /
+  `__delete`.
+- `examples/goclient/main.go`: rewritten around the high-level `tournament`
+  socket op (one round-trip, parallel workspaces) + the new `delete` op.
+- `examples/branch_explore.py`: kept the manual-loop exploration pattern,
+  added a `delete` pass that prunes the losing branches.
 - New README hero GIF: real Claude Code, running inside `rewindable-claude`,
   deletes its own binary then calls `agentenv__checkout` MCP tool to roll the
   whole environment back — the binary is restored, the Claude session keeps
@@ -18,6 +39,9 @@ All notable changes to this project are documented here. The format is based on
   pure `COPY` over `rewindable-claude` — seconds to build.
 
 ### Removed
+- `examples/Client.java` — three near-identical socket clients was noise;
+  the goclient + python pair plus the new mcp_client / http_client cover the
+  patterns that matter.
 - Obsolete shell-scripted demos and recorders that the real Claude Code GIF
   supersedes: `examples/demo/` (killer-demo + self-rollback-demo + README),
   `scripts/make-demo-gif.sh`, `scripts/make-claude-gif.sh`,
@@ -200,6 +224,7 @@ drive rollback natively.
   incremental checkout (copy only the diff); `AGENTENV_IGNORE` excludes ephemeral
   paths; auto-snapshot labels list the changed files.
 
+[0.3.0]: https://github.com/css521/agentenv/releases/tag/v0.3.0
 [0.2.0]: https://github.com/css521/agentenv/releases/tag/v0.2.0
 [0.1.1]: https://github.com/css521/agentenv/releases/tag/v0.1.1
 [0.1.0]: https://github.com/css521/agentenv/releases/tag/v0.1.0

Makefile

@@ -15,7 +15,7 @@ GOOS_LINUX ?= linux
 GOARCH     ?= $(shell uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/;s/arm64/arm64/')
 GOPROXY    ?= $(shell go env GOPROXY)
 
-.PHONY: help build test vet verify-rootless verify-btrfs verify-supervise verify-mcp verify-rollback dev-shell dev-shell-stop clean
+.PHONY: help build test vet verify-rootless verify-btrfs verify-supervise verify-mcp verify-rollback openapi-snapshot dev-shell dev-shell-stop clean
 
 help:
 	@awk 'BEGIN{FS=":.*##"; printf "Targets:\n"} /^[a-zA-Z_-]+:.*##/ { printf "  %-22s %s\n", $$1, $$2 }' $(MAKEFILE_LIST)
@@ -66,6 +66,9 @@ verify-rollback: ## MCP-driven end-to-end rollback (asserts files actually rever
 	  --security-opt seccomp=unconfined --security-opt apparmor=unconfined \
 	  agentenv-rollback-smoke
 
+openapi-snapshot: ## regenerate docs/openapi.json from a one-off daemon (run before tagging)
+	bash scripts/snapshot-openapi.sh
+
 # --- Persistent dev container: fast inner loop on macOS -----------------------
 # `make dev-shell` starts (or reattaches to) a long-running container with the
 # source bind-mounted; rebuilds and verifies inside are seconds (no setup tax).

README.md

@@ -82,7 +82,8 @@ CGO_ENABLED=1 go build -tags btrfs -o agentenv .
 # run modes
 agentenv supervise -- <agent>   run an UNMODIFIED agent inside the env; auto-snapshot;
                                 rollback (out-of-band) kills + restarts it  ← primary
-agentenv daemon [--socket p]    serve the JSON API over a unix socket (for orchestrators)
+agentenv daemon [--socket p] [--http :PORT]
+                                serve the JSON API over a unix socket (default) and/or HTTP+OpenAPI
 agentenv mcp [--socket p]       MCP server over stdio (Claude Code & other MCP hosts)
 agentenv shell                  interactive shell inside the env (human/debug)
 agentenv exec -- <cmd...>       run one command in the env (scripting/CI)
@@ -105,6 +106,7 @@ agentenv show <ref> | diff <a> <b>      what changed (confirm a change / rollbac
 agentenv gc                     reclaim disk from sparsified snapshots
 
 Env: AGENTENV_ROOT (default /agentfs), AGENTENV_SOCKET, AGENTENV_BACKEND,
+     AGENTENV_HTTP (=":PORT" / "127.0.0.1:PORT"), AGENTENV_HTTP_TOKEN (required for non-loopback HTTP),
      AGENTENV_KEEP_RECENT, AGENTENV_IGNORE.
 ```
 
@@ -174,6 +176,35 @@ silent for 10 minutes), then ends with a terminal frame:
 Clients keep reading frames until they see `"ok":true` or `"error":"..."` — see
 `examples/branch_explore.py` for the streaming client pattern.
 
+## HTTP + OpenAPI (REST surface)
+
+Prefer `curl`, Postman, or a generated SDK over a raw unix socket? Enable the
+HTTP transport — it lives alongside the socket on the same daemon:
+
+```bash
+# loopback, no auth (local development)
+agentenv daemon --http 127.0.0.1:8911
+
+# exposed; a Bearer token is REQUIRED for any non-loopback bind
+AGENTENV_HTTP_TOKEN=secret agentenv daemon --http :8911
+```
+
+Auto-served:
+- `GET /v1/head` `GET /v1/log` `GET /v1/branches` `GET /v1/nodes/{id}`
+  `GET /v1/diff?a=&b=` `GET /v1/tags`
+- `POST /v1/commit` `POST /v1/checkout` `POST /v1/tags` `POST /v1/tournament`
+  `POST /v1/gc`
+- `DELETE /v1/nodes/{id}` (the v0.2.0 node-delete op, RESTful)
+- `GET /openapi.json` — OpenAPI 3.1 spec generated by `huma` from the typed
+  handler signatures (always in sync with the running code). A pretty-printed
+  snapshot for offline viewing lives at [`docs/openapi.json`](./docs/openapi.json);
+  regenerate it with `make openapi-snapshot` before tagging a release.
+- `GET /docs` — interactive API docs, one URL to open in a browser
+
+`exec` is still socket-only (it's a stdout/stderr stream — Server-Sent Events
+support is a follow-up). Everything else is on HTTP. See
+[`examples/http_client.sh`](./examples/http_client.sh) for a curl walkthrough.
+
 ## MCP (Claude Code & other MCP hosts)
 
 `agentenv mcp` is a Model Context Protocol server over stdio. It exposes six

docs/README.md

@@ -2,6 +2,10 @@
 
 Shareable assets:
 
+- `openapi.json` — pretty-printed snapshot of the HTTP daemon's `/openapi.json`
+  (regenerated by `make openapi-snapshot`; authoritative source is whatever a
+  live `agentenv daemon --http :PORT` serves at runtime).
+
 - `claude-rewind.cast` — asciinema recording of a real Claude Code session
   (running inside the `rewindable-claude` image) deleting its own binary,
   then calling the `agentenv__checkout` MCP tool to roll the WHOLE environment