fix: report curated command name in X-Wherobots-Client (WBC-182)

Curated `job-runs` commands reuse the shared api-subtree operations
returned by findOperation (e.g. `POST /runs`), whose CommandPath was
assigned the api-tree name (`runs.<verb>`) in builder.go. Deriving the
header's cmd= field from op.CommandPath therefore misattributed curated
traffic as `runs.create` / `runs.list` instead of the user-facing
`job-runs.create` / `job-runs.list`.

Thread the invoked command name through the request context: the
`job-runs` parent's PersistentPreRunE stamps the leaf command's dotted
user-facing path (curatedCommandName) onto the context, and BuildRequest
prefers that over op.CommandPath (falling back to op.CommandPath for the
dynamic api subtree, which is already correct). Context propagation
covers every request a curated command issues, including internal helper
calls (org lookup, upload-url, run polling) without touching their
signatures, and avoids mutating the shared operation pointers.

Add end-to-end tests exercising the curated path through BuildRootCommand
+ httptest asserting `cmd=job-runs.create` / `cmd=job-runs.list` on the
wire, a guard that `api runs list` still reports `runs.list`, and
executor unit tests for the context override and its fallback.

Claude-Session: https://claude.ai/code/session_01QP5saxNQTUTJpMRRxZXhzR

Author: ClayMav

internal/commands/jobs.go

@@ -68,6 +68,17 @@ func addJobsCustomCommands(root *cobra.Command, cfg config.Config, runtimeSpec *
 		Short:         "Custom job-runs workflows",
 		SilenceUsage:  true,
 		SilenceErrors: true,
+		// Curated commands reuse shared api-subtree operations whose CommandPath
+		// is the api-tree name (e.g. runs.create). Stamp the invoked user-facing
+		// command name onto the context so BuildRequest reports it (e.g.
+		// job-runs.create) in the advisory X-Wherobots-Client header instead.
+		// PersistentPreRunE runs for the invoked subcommand, so `cmd` is the leaf
+		// (create/logs/list/metrics), and the context propagates to every request
+		// those commands issue, including internal helper calls.
+		PersistentPreRunE: func(cmd *cobra.Command, _ []string) error {
+			cmd.SetContext(executor.WithCommand(cmd.Context(), curatedCommandName(cmd)))
+			return nil
+		},
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			return cmd.Help()
 		},
@@ -111,6 +122,25 @@ func newJobsRunner(cfg config.Config, runtimeSpec *spec.RuntimeSpec, client *htt
 	return r, true
 }
 
+// curatedCommandName returns the invoked command's user-facing dotted path,
+// excluding the root application name — e.g. `wherobots job-runs create`
+// becomes "job-runs.create". It walks the parent chain, so the value reflects
+// the actually-invoked command regardless of which shared operation it reuses.
+func curatedCommandName(cmd *cobra.Command) string {
+	if cmd == nil {
+		return ""
+	}
+	var segments []string
+	for c := cmd; c != nil && c.Parent() != nil; c = c.Parent() {
+		segments = append(segments, c.Name())
+	}
+	// Reverse into root-to-leaf order.
+	for i, j := 0, len(segments)-1; i < j; i, j = i+1, j-1 {
+		segments[i], segments[j] = segments[j], segments[i]
+	}
+	return strings.Join(segments, ".")
+}
+
 func findOperation(runtimeSpec *spec.RuntimeSpec, method, path string) *spec.Operation {
 	if runtimeSpec == nil {
 		return nil

internal/commands/jobs_test.go

@@ -644,6 +644,112 @@ func TestJobsListDefaultsToText(t *testing.T) {
 	}
 }
 
+func TestJobsListEmitsCuratedCommandInClientHeader(t *testing.T) {
+	t.Parallel()
+
+	var gotClientHeader string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method == http.MethodGet && r.URL.Path == "/runs" {
+			gotClientHeader = r.Header.Get("X-Wherobots-Client")
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = io.WriteString(w, `{"items":[],"total":0,"next_page":null}`)
+			return
+		}
+		http.NotFound(w, r)
+	}))
+	defer server.Close()
+
+	root := buildJobsTestRoot(server.URL)
+	root.SetOut(&bytes.Buffer{})
+	root.SetErr(&bytes.Buffer{})
+	root.SetArgs([]string{"job-runs", "list"})
+
+	if err := root.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+
+	// The curated `job-runs list` command reuses the shared `GET /runs`
+	// operation, whose api-subtree CommandPath is `runs.<verb>`. The client
+	// header must report the user-facing curated command, not the shared op.
+	if !strings.HasSuffix(gotClientHeader, "cmd=job-runs.list") {
+		t.Fatalf("X-Wherobots-Client = %q, want cmd=job-runs.list", gotClientHeader)
+	}
+}
+
+func TestJobsCreateEmitsCuratedCommandInClientHeader(t *testing.T) {
+	t.Parallel()
+
+	var runsClientHeader string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch {
+		case r.Method == http.MethodGet && r.URL.Path == "/organization":
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = io.WriteString(w, `{"fileStore":{"bucketName":"managed-bucket"}}`)
+		case r.Method == http.MethodPost && r.URL.Path == "/files/upload-url":
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = io.WriteString(w, `{"uploadUrl":"https://example.com/upload"}`)
+		case r.Method == http.MethodGet && r.URL.Path == "/files/dir":
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = io.WriteString(w, `{"name":"root","path":"s3://managed-bucket/customer/root"}`)
+		case r.Method == http.MethodPost && r.URL.Path == "/runs":
+			runsClientHeader = r.Header.Get("X-Wherobots-Client")
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = io.WriteString(w, `{"id":"run-123","name":"test-job-001","status":"PENDING","createTime":"2026-01-01T00:00:00Z","payload":{}}`)
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	defer server.Close()
+
+	root := buildJobsTestRoot(server.URL)
+	root.SetOut(&bytes.Buffer{})
+	root.SetErr(&bytes.Buffer{})
+	root.SetArgs([]string{
+		"job-runs", "create", "s3://bucket/script.py",
+		"--name", "test-job-001",
+		"--upload-path", "s3://override-bucket/custom/prefix",
+	})
+
+	if err := root.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+
+	if !strings.HasSuffix(runsClientHeader, "cmd=job-runs.create") {
+		t.Fatalf("X-Wherobots-Client on POST /runs = %q, want cmd=job-runs.create", runsClientHeader)
+	}
+}
+
+func TestApiSubtreeEmitsDottedResourceCommandInClientHeader(t *testing.T) {
+	t.Parallel()
+
+	var gotClientHeader string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method == http.MethodGet && r.URL.Path == "/runs" {
+			gotClientHeader = r.Header.Get("X-Wherobots-Client")
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = io.WriteString(w, `{"items":[],"total":0,"next_page":null}`)
+			return
+		}
+		http.NotFound(w, r)
+	}))
+	defer server.Close()
+
+	root := buildJobsTestRoot(server.URL)
+	root.SetOut(&bytes.Buffer{})
+	root.SetErr(&bytes.Buffer{})
+	// The dynamic api subtree keeps its own operation CommandPath; invoking
+	// it directly must still report the api-tree command name.
+	root.SetArgs([]string{"api", "runs", "list"})
+
+	if err := root.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+
+	if !strings.HasSuffix(gotClientHeader, "cmd=runs.list") {
+		t.Fatalf("X-Wherobots-Client = %q, want cmd=runs.list", gotClientHeader)
+	}
+}
+
 func TestJobsRunningAliasFiltersStatus(t *testing.T) {
 	t.Parallel()
 

internal/executor/request.go

@@ -25,6 +25,32 @@ type QueryPair struct {
 	Value string
 }
 
+// commandContextKey carries the user-facing command name for the
+// X-Wherobots-Client header's cmd= field. Curated commands (e.g. `job-runs`)
+// reuse shared api-subtree operations whose CommandPath is the api-tree name
+// (e.g. runs.create), so they inject the invoked command name here to override
+// it. Dynamic api commands leave it unset and fall back to op.CommandPath.
+type commandContextKey struct{}
+
+// WithCommand returns a context that carries the user-facing command name
+// (dotted, e.g. "job-runs.create") for the X-Wherobots-Client header. An empty
+// name leaves the context unchanged so the op.CommandPath fallback applies.
+func WithCommand(ctx context.Context, command string) context.Context {
+	if command == "" {
+		return ctx
+	}
+	return context.WithValue(ctx, commandContextKey{}, command)
+}
+
+// commandFromContext returns the command name set by WithCommand, or "".
+func commandFromContext(ctx context.Context) string {
+	if ctx == nil {
+		return ""
+	}
+	name, _ := ctx.Value(commandContextKey{}).(string)
+	return name
+}
+
 // clientHeaderName is the ordered, append-only client-identification header.
 // The CLI is an ORIGIN client, so it emits a single hop and never appends to
 // an existing value. The header is advisory only and never affects auth.
@@ -279,7 +305,14 @@ func BuildRequest(
 		req.Header.Set("Content-Type", contentType)
 	}
 	req.Header.Set("x-api-key", cfg.APIKey)
-	req.Header.Set(clientHeaderName, buildClientHeader(Version, strings.Join(op.CommandPath, ".")))
+	// Prefer the invoked command name carried on the context (set by curated
+	// commands whose shared op.CommandPath is the api-tree name); fall back to
+	// the operation's own CommandPath for dynamic api commands.
+	command := commandFromContext(ctx)
+	if command == "" {
+		command = strings.Join(op.CommandPath, ".")
+	}
+	req.Header.Set(clientHeaderName, buildClientHeader(Version, command))
 
 	return req, nil
 }

internal/executor/request_test.go

@@ -207,6 +207,55 @@ func TestBuildRequestInjectsWherobotsClientHeader(t *testing.T) {
 	}
 }
 
+func TestBuildRequestClientHeaderPrefersContextCommand(t *testing.T) {
+	// Not parallel: mutates the package-level Version var.
+	prev := Version
+	Version = "1.2.3"
+	t.Cleanup(func() { Version = prev })
+
+	cfg := config.Config{APIKey: "abc123"}
+	runtimeSpec := &spec.RuntimeSpec{BaseURL: "https://api.example.com"}
+	// op.CommandPath is the shared api-tree name; the context override must win.
+	op := &spec.Operation{
+		Method:      "POST",
+		Path:        "/runs",
+		CommandPath: []string{"runs", "create"},
+	}
+
+	ctx := WithCommand(context.Background(), "job-runs.create")
+	req, err := BuildRequest(ctx, cfg, runtimeSpec, op, nil, nil, `{}`)
+	if err != nil {
+		t.Fatalf("BuildRequest() error = %v", err)
+	}
+	if got, want := req.Header.Get("X-Wherobots-Client"), "client=cli;ver=1.2.3;cmd=job-runs.create"; got != want {
+		t.Fatalf("X-Wherobots-Client = %q, want %q", got, want)
+	}
+}
+
+func TestBuildRequestClientHeaderFallsBackToCommandPathWithoutContext(t *testing.T) {
+	// Not parallel: mutates the package-level Version var.
+	prev := Version
+	Version = "1.2.3"
+	t.Cleanup(func() { Version = prev })
+
+	cfg := config.Config{APIKey: "abc123"}
+	runtimeSpec := &spec.RuntimeSpec{BaseURL: "https://api.example.com"}
+	op := &spec.Operation{
+		Method:      "POST",
+		Path:        "/runs",
+		CommandPath: []string{"runs", "create"},
+	}
+
+	// No context command set: fall back to op.CommandPath.
+	req, err := BuildRequest(context.Background(), cfg, runtimeSpec, op, nil, nil, `{}`)
+	if err != nil {
+		t.Fatalf("BuildRequest() error = %v", err)
+	}
+	if got, want := req.Header.Get("X-Wherobots-Client"), "client=cli;ver=1.2.3;cmd=runs.create"; got != want {
+		t.Fatalf("X-Wherobots-Client = %q, want %q", got, want)
+	}
+}
+
 func TestBuildRequestWherobotsClientHeaderOmitsCommandWhenEmpty(t *testing.T) {
 	// Not parallel: mutates the package-level Version var.
 	prev := Version