test(inspect): close remaining PR #136 review gaps

- Security headers (CSP, nosniff) on all inspector HTTP responses
- Panic on broken embed layout; sync.RWMutex for BoundAddr (Port 0 reserved)
- CLI↔API contract test: logs -o json events vs /api/runs/{id}
- Integration test: init/apply/run then inspector API over httptest
- statejson run empty-input contract test

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: leo-aa88

internal/cli/logs_inspect_contract_test.go

@@ -0,0 +1,92 @@
+package cli
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"testing"
+
+	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/inspect"
+	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/state/sqlite"
+	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/statejson"
+)
+
+// TestLogsInspectContract_eventsJSON verifies agentctl logs -o json events match inspector /api/runs/{id}.
+func TestLogsInspectContract_eventsJSON(t *testing.T) {
+	db := filepath.Join(t.TempDir(), "contract.db")
+	root := runProjRoot(t)
+
+	ResetGlobalsForTest()
+	runCmd := NewRootCmd()
+	runCmd.SetOut(io.Discard)
+	runCmd.SetErr(io.Discard)
+	runCmd.SetArgs([]string{
+		"run", "workflow/demo",
+		"--project", root,
+		"--state", db,
+		"--input", "topic=contract-test",
+	})
+	var runOut bytes.Buffer
+	runCmd.SetOut(&runOut)
+	if err := runCmd.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	runID := extractRunID(runOut.String())
+	if runID == "" {
+		t.Fatal("no run id")
+	}
+
+	ResetGlobalsForTest()
+	var logsOut bytes.Buffer
+	logsCmd := NewRootCmd()
+	logsCmd.SetOut(&logsOut)
+	logsCmd.SetErr(&logsOut)
+	logsCmd.SetArgs([]string{"logs", "--run", runID, "--project", root, "--state", db, "-o", "json"})
+	if err := logsCmd.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	var logsPayload statejson.RunEventsPayload
+	if err := json.Unmarshal(logsOut.Bytes(), &logsPayload); err != nil {
+		t.Fatalf("logs json: %v\n%s", err, logsOut.String())
+	}
+
+	ctx := context.Background()
+	st, err := sqlite.OpenReadOnly(ctx, db)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = st.Close() })
+
+	srv, err := inspect.NewServer(st, inspect.Config{StatePath: db, Env: "staging"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	ts := httptest.NewServer(srv.Handler())
+	t.Cleanup(ts.Close)
+
+	res, err := http.Get(ts.URL + "/api/runs/" + runID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer res.Body.Close()
+	var api inspect.RunDetailResponse
+	if err := json.NewDecoder(res.Body).Decode(&api); err != nil {
+		t.Fatal(err)
+	}
+
+	logsEvents, err := json.Marshal(logsPayload.Events)
+	if err != nil {
+		t.Fatal(err)
+	}
+	apiEvents, err := json.Marshal(api.Events)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(logsEvents) != string(apiEvents) {
+		t.Fatalf("events mismatch:\nlogs %s\napi %s", logsEvents, apiEvents)
+	}
+}

internal/inspect/embed.go

@@ -9,12 +9,18 @@ import (
 //go:embed web/*
 var webEmbed embed.FS
 
-func (s *Server) staticFS() http.Handler {
+var staticAssets http.FileSystem
+
+func init() {
 	sub, err := fs.Sub(webEmbed, "web/static")
 	if err != nil {
-		return http.FileServer(http.FS(webEmbed))
+		panic("inspect: embed web/static: " + err.Error())
 	}
-	return http.FileServer(http.FS(sub))
+	staticAssets = http.FS(sub)
+}
+
+func (s *Server) staticFS() http.Handler {
+	return http.FileServer(staticAssets)
 }
 
 func (s *Server) staticHandler(name string) http.Handler {

internal/inspect/middleware.go

@@ -0,0 +1,12 @@
+package inspect
+
+import "net/http"
+
+// securityHeaders sets baseline headers for the embedded localhost UI.
+func securityHeaders(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("X-Content-Type-Options", "nosniff")
+		w.Header().Set("Content-Security-Policy", "default-src 'self'; script-src 'self'; style-src 'self'; connect-src 'self'")
+		next.ServeHTTP(w, r)
+	})
+}

internal/inspect/server.go

@@ -9,6 +9,7 @@ import (
 	"net"
 	"net/http"
 	"strings"
+	"sync"
 	"time"
 
 	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/state"
@@ -45,9 +46,11 @@ type Config struct {
 
 // Server serves read-only JSON and static UI over HTTP.
 type Server struct {
-	store *sqlite.Store
-	cfg   Config
-	mux   *http.ServeMux
+	store     *sqlite.Store
+	cfg       Config
+	mux       *http.ServeMux
+	mu        sync.RWMutex
+	boundAddr string // set after Listen; use [Server.BoundAddr] when Port is 0
 }
 
 // NewServer wires handlers for a read-only SQLite store opened via [sqlite.OpenReadOnly].
@@ -58,7 +61,7 @@ func NewServer(st *sqlite.Store, cfg Config) (*Server, error) {
 	if strings.TrimSpace(cfg.StatePath) == "" {
 		return nil, errors.New("inspect: empty state path")
 	}
-	if cfg.Port <= 0 {
+	if cfg.Port < 0 {
 		cfg.Port = DefaultPort
 	}
 	s := &Server{store: st, cfg: cfg, mux: http.NewServeMux()}
@@ -75,16 +78,31 @@ func (s *Server) registerRoutes() {
 	s.mux.Handle("GET /static/", http.StripPrefix("/static/", s.staticFS()))
 }
 
-// Handler returns the root HTTP handler (GET/HEAD only).
+// Handler returns the root HTTP handler (GET/HEAD only, security headers on responses).
 func (s *Server) Handler() http.Handler {
-	return RejectMutation(s.mux)
+	return securityHeaders(RejectMutation(s.mux))
+}
+
+// BoundAddr returns the address the server is listening on after [Server.ListenAndServe] starts.
+// When Port is 0, this is the kernel-assigned port (127.0.0.1:NNNN).
+func (s *Server) BoundAddr() string {
+	s.mu.RLock()
+	ba := s.boundAddr
+	s.mu.RUnlock()
+	if ba != "" {
+		return ba
+	}
+	return s.ListenAddr()
 }
 
 // ListenAddr returns the address this server will bind when [Server.ListenAndServe] is called.
 func (s *Server) ListenAddr() string {
 	if a := strings.TrimSpace(s.cfg.Addr); a != "" {
 		return a
 	}
+	if s.cfg.Port == 0 {
+		return "127.0.0.1:0"
+	}
 	return fmt.Sprintf("127.0.0.1:%d", s.cfg.Port)
 }
 
@@ -94,6 +112,9 @@ func (s *Server) ListenAndServe(ctx context.Context) error {
 	if err != nil {
 		return fmt.Errorf("inspect: listen %s: %w", s.ListenAddr(), err)
 	}
+	s.mu.Lock()
+	s.boundAddr = ln.Addr().String()
+	s.mu.Unlock()
 
 	srv := &http.Server{
 		Handler:           s.Handler(),

internal/inspect/server_test.go

@@ -193,6 +193,44 @@ func TestServer_API_readOnly(t *testing.T) {
 	})
 }
 
+func TestServer_ListenAddr(t *testing.T) {
+	path, st := seedInspectorDB(t)
+	t.Cleanup(func() { _ = st.Close() })
+	srv, err := NewServer(st, Config{StatePath: path, Port: 8787})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := srv.ListenAddr(); got != "127.0.0.1:8787" {
+		t.Fatalf("ListenAddr=%q", got)
+	}
+	srv.cfg.Port = 0
+	if got := srv.ListenAddr(); got != "127.0.0.1:0" {
+		t.Fatalf("ListenAddr port0=%q", got)
+	}
+}
+
+func TestServer_Handler_securityHeaders(t *testing.T) {
+	path, st := seedInspectorDB(t)
+	t.Cleanup(func() { _ = st.Close() })
+	srv, err := NewServer(st, Config{StatePath: path, Env: "local"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	ts := httptest.NewServer(srv.Handler())
+	t.Cleanup(ts.Close)
+	res, err := http.Get(ts.URL + "/")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer res.Body.Close()
+	if res.Header.Get("X-Content-Type-Options") != "nosniff" {
+		t.Fatalf("headers=%v", res.Header)
+	}
+	if csp := res.Header.Get("Content-Security-Policy"); csp == "" || !strings.Contains(csp, "default-src 'self'") {
+		t.Fatalf("csp=%q", csp)
+	}
+}
+
 func TestServer_readOnlyStoreCannotMutate(t *testing.T) {
 	_, st := seedInspectorDB(t)
 	t.Cleanup(func() { _ = st.Close() })

internal/statejson/contract_test.go

@@ -48,6 +48,17 @@ func TestContract_runRecord_matchesLogsFields(t *testing.T) {
 	}
 }
 
+func TestContract_run_emptyInputDefaultsToObject(t *testing.T) {
+	r := state.Run{
+		RunID: "r", WorkflowName: "w", Env: "local", Status: "running",
+		StartedAt: time.Now().UTC(), InputJSON: "",
+	}
+	rec := Run(r)
+	if string(rec.Input) != `{}` {
+		t.Fatalf("input=%s want {}", rec.Input)
+	}
+}
+
 func TestContract_appliedResource_matchesStateCLI(t *testing.T) {
 	at := time.Date(2026, 6, 4, 8, 0, 0, 0, time.UTC)
 	row := state.AppliedResource{

test/integration/inspect_web_test.go

@@ -0,0 +1,72 @@
+package integration_test
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"testing"
+
+	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/inspect"
+	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/state/sqlite"
+)
+
+// TestIntegration_inspectWeb_API_afterRun seeds state via CLI run, then hits inspector HTTP API.
+func TestIntegration_inspectWeb_API_afterRun(t *testing.T) {
+	parent := t.TempDir()
+	projName := "inspectweb"
+	projDir := filepath.Join(parent, projName)
+	db := filepath.Join(t.TempDir(), "inspect-web.db")
+
+	out, err := runCLI(t, "init", projName, "--parent-dir", parent)
+	if err != nil {
+		t.Fatalf("init: %v\n%s", err, out)
+	}
+	out, err = runCLI(t, "apply", "--project", projDir, "--state", db, "--auto-approve")
+	if err != nil {
+		t.Fatalf("apply: %v\n%s", err, out)
+	}
+	out, err = runCLI(t, "run", "workflow/hello", "--project", projDir, "--state", db, "--input", "topic=web-int")
+	if err != nil {
+		t.Fatalf("run: %v\n%s", err, out)
+	}
+	runID := extractRunID(out)
+	if runID == "" {
+		t.Fatalf("no run id in:\n%s", out)
+	}
+
+	st, err := sqlite.OpenReadOnly(t.Context(), db)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = st.Close() })
+
+	srv, err := inspect.NewServer(st, inspect.Config{StatePath: db, Env: "local"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	ts := httptest.NewServer(srv.Handler())
+	t.Cleanup(ts.Close)
+
+	res, err := http.Get(ts.URL + "/api/runs/" + runID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer res.Body.Close()
+	if res.StatusCode != http.StatusOK {
+		t.Fatalf("status=%d", res.StatusCode)
+	}
+	if res.Header.Get("X-Content-Type-Options") != "nosniff" {
+		t.Fatalf("missing security headers: %v", res.Header)
+	}
+	var body inspect.RunDetailResponse
+	if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
+		t.Fatal(err)
+	}
+	if body.Run.RunID != runID {
+		t.Fatalf("run=%+v", body.Run)
+	}
+	if len(body.Events) == 0 {
+		t.Fatal("expected trace events")
+	}
+}