From 8cc9b00638f5c6f65b5535c0ef997e525aeaacb4 Mon Sep 17 00:00:00 2001
From: Zaki <zaki@iqlusion.io>
Date: Tue, 19 May 2026 14:48:23 -0700
Subject: [PATCH 1/7] Add trace-commons-operator-client foundation crate

New workspace member that holds the shared HTTP transport + foundational
types for the upcoming operator binaries (trace-commons-review,
trace-commons-worker, trace-commons-admin, trace-commons-tenant). These
binaries take over the operator-side CLI surface that was pruned from
Ironclaw's reborn trace client in nearai/ironclaw#3738.

Surface in this PR:
- Client with bearer-token resolution from an env var (never logged),
  host-allowlist enforcement, and typed error mapping for the server's
  {"error": "<Label>"} refusal envelope.
- Error taxonomy: BearerMissing, InvalidEndpoint, HostNotAllowed,
  Transport, HttpFailure, ServerLabel, MalformedResponse. Each carries
  a user_diagnostic() that strips query strings + fragments.
- HostAllowlist with exact-match semantics, case-insensitive, sourced
  from --allowed-hosts or TRACE_COMMONS_ALLOWED_HOSTS.
- Output helpers: JsonEnvelope wrapper for --json mode, ASCII table
  renderer, key-value renderer for single-record commands.

Per-endpoint typed request/response structs land in PR #2 (reviewer +
admin) and PR #3 (worker + tenant). When a struct turns out to be
shared across binaries it migrates back here.

Verification:
- cargo check --workspace --all-targets under -D warnings: clean
- cargo test -p trace-commons-operator-client: 30 passed
- cargo clippy -p trace-commons-operator-client --all-targets -- -D warnings: clean
---
 Cargo.lock                                    |  15 +
 Cargo.toml                                    |   1 +
 .../trace-commons-operator-client/Cargo.toml  |  22 +
 .../src/client.rs                             | 432 ++++++++++++++++++
 .../src/error.rs                              | 262 +++++++++++
 .../src/format.rs                             | 210 +++++++++
 .../src/host_allowlist.rs                     | 158 +++++++
 .../trace-commons-operator-client/src/lib.rs  |  24 +
 8 files changed, 1124 insertions(+)
 create mode 100644 crates/trace-commons-operator-client/Cargo.toml
 create mode 100644 crates/trace-commons-operator-client/src/client.rs
 create mode 100644 crates/trace-commons-operator-client/src/error.rs
 create mode 100644 crates/trace-commons-operator-client/src/format.rs
 create mode 100644 crates/trace-commons-operator-client/src/host_allowlist.rs
 create mode 100644 crates/trace-commons-operator-client/src/lib.rs

diff --git a/Cargo.lock b/Cargo.lock
index b08212d6a..02d924d19 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -7041,6 +7041,21 @@ dependencies = [
  "uuid 1.23.1",
 ]
 
+[[package]]
+name = "trace-commons-operator-client"
+version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "chrono",
+ "reqwest 0.12.28",
+ "serde",
+ "serde_json",
+ "thiserror 2.0.18",
+ "tokio",
+ "url",
+ "wiremock",
+]
+
 [[package]]
 name = "trace-commons-protocol"
 version = "0.1.0"
diff --git a/Cargo.toml b/Cargo.toml
index 112279c8f..b5d8328f4 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,7 @@
 [workspace]
 members = [
     "crates/trace-commons-gate-enclave",
+    "crates/trace-commons-operator-client",
     "crates/trace-commons-protocol",
     "crates/trace-commons-server",
 ]
diff --git a/crates/trace-commons-operator-client/Cargo.toml b/crates/trace-commons-operator-client/Cargo.toml
new file mode 100644
index 000000000..ce6b6c69c
--- /dev/null
+++ b/crates/trace-commons-operator-client/Cargo.toml
@@ -0,0 +1,22 @@
+[package]
+name = "trace-commons-operator-client"
+version = "0.1.0"
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+description = "Shared HTTP client + typed request/response surface for trace-commons-server operator binaries (reviewer / worker / admin / tenant)."
+
+[dependencies]
+anyhow = "1"
+chrono = { version = "0.4", features = ["serde"] }
+reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls-native-roots"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+thiserror = "2"
+tokio = { version = "1", features = ["macros", "rt-multi-thread", "time"] }
+url = "2"
+
+[dev-dependencies]
+tokio = { version = "1", features = ["macros", "rt-multi-thread", "time", "test-util"] }
+wiremock = "0.6"
diff --git a/crates/trace-commons-operator-client/src/client.rs b/crates/trace-commons-operator-client/src/client.rs
new file mode 100644
index 000000000..0f686cc20
--- /dev/null
+++ b/crates/trace-commons-operator-client/src/client.rs
@@ -0,0 +1,432 @@
+//! HTTP transport for trace-commons-server operator binaries.
+//!
+//! [`Client`] wraps `reqwest::Client` with:
+//!   - Bearer-token resolution from an env var (never logged).
+//!   - Host allowlist enforcement (see [`crate::host_allowlist`]).
+//!   - Typed error mapping for the server's `{"error": "<Label>"}` envelope.
+//!
+//! Each operator binary constructs one `Client` per audience-scoped bearer
+//! token. The worker binary's `--bearer-token-env` flag varies per
+//! subcommand, so worker code builds the client lazily per subcommand.
+
+use std::time::Duration;
+
+use reqwest::Method;
+use serde::de::DeserializeOwned;
+use serde::Serialize;
+
+use crate::error::{parse_error_label, Error, Result};
+use crate::host_allowlist::HostAllowlist;
+
+const DEFAULT_TIMEOUT: Duration = Duration::from_secs(30);
+
+#[derive(Debug, Clone)]
+pub struct Client {
+    inner: reqwest::Client,
+    endpoint: url::Url,
+    bearer_token: String,
+    host_allowlist: HostAllowlist,
+}
+
+pub struct ClientBuilder {
+    endpoint: String,
+    bearer_token_env: String,
+    host_allowlist: HostAllowlist,
+    timeout: Duration,
+}
+
+impl Client {
+    pub fn builder(endpoint: impl Into<String>, bearer_token_env: impl Into<String>) -> ClientBuilder {
+        ClientBuilder {
+            endpoint: endpoint.into(),
+            bearer_token_env: bearer_token_env.into(),
+            host_allowlist: HostAllowlist::permissive(),
+            timeout: DEFAULT_TIMEOUT,
+        }
+    }
+
+    /// Endpoint as configured at construction. Query strings and fragments
+    /// are stripped because this value gets logged in error diagnostics.
+    pub fn endpoint(&self) -> String {
+        let mut endpoint = self.endpoint.clone();
+        endpoint.set_query(None);
+        endpoint.set_fragment(None);
+        endpoint.to_string()
+    }
+
+    /// Issue a typed JSON request and deserialize the response body.
+    ///
+    /// The path is joined onto the configured endpoint. Query parameters
+    /// are appended verbatim. The bearer token is attached as `Authorization:
+    /// Bearer <token>`. Non-success status codes produce [`Error::ServerLabel`]
+    /// if the body carries a typed label, otherwise [`Error::HttpFailure`].
+    pub async fn call_json<Req, Resp>(
+        &self,
+        method: Method,
+        path: &str,
+        query: &[(&str, &str)],
+        body: Option<&Req>,
+    ) -> Result<Resp>
+    where
+        Req: Serialize + ?Sized,
+        Resp: DeserializeOwned,
+    {
+        let response_body = self.call_raw(method, path, query, body).await?;
+        let url = self.compose_url(path, query)?.to_string();
+        if response_body.trim().is_empty() {
+            // The caller asked for a typed Resp but got an empty body. This
+            // is a server contract violation worth surfacing.
+            let source = serde_json::from_str::<serde_json::Value>("")
+                .expect_err("empty input is not valid JSON");
+            return Err(Error::MalformedResponse {
+                url,
+                body: response_body,
+                source,
+            });
+        }
+        serde_json::from_str(&response_body).map_err(|source| Error::MalformedResponse {
+            url,
+            body: response_body,
+            source,
+        })
+    }
+
+    /// Issue an untyped JSON request and return the raw response body.
+    /// Used by binaries that need the unparsed JSON for `--json` output or
+    /// for endpoints whose response shape varies.
+    pub async fn call_raw<Req>(
+        &self,
+        method: Method,
+        path: &str,
+        query: &[(&str, &str)],
+        body: Option<&Req>,
+    ) -> Result<String>
+    where
+        Req: Serialize + ?Sized,
+    {
+        let url = self.compose_url(path, query)?;
+        self.host_allowlist.check(&url)?;
+
+        let mut request = self.inner.request(method, url.clone());
+        request = request.bearer_auth(&self.bearer_token);
+        if let Some(body) = body {
+            request = request.json(body);
+        }
+        let response = request.send().await.map_err(|source| Error::Transport {
+            url: url.to_string(),
+            source,
+        })?;
+        let status = response.status();
+        let response_body = response.text().await.map_err(|source| Error::Transport {
+            url: url.to_string(),
+            source,
+        })?;
+
+        if status.is_success() {
+            return Ok(response_body);
+        }
+
+        match parse_error_label(&response_body) {
+            Some(label) => Err(Error::ServerLabel {
+                url: url.to_string(),
+                status,
+                label,
+                body: response_body,
+            }),
+            None => Err(Error::HttpFailure {
+                url: url.to_string(),
+                status,
+                body: response_body,
+            }),
+        }
+    }
+
+    fn compose_url(&self, path: &str, query: &[(&str, &str)]) -> Result<url::Url> {
+        let mut url = self.endpoint.clone();
+        // Replace path with the operator-requested one. The endpoint's
+        // configured path is the API prefix (e.g. `/`); we don't try to
+        // concatenate because that interacts badly with trailing slashes.
+        url.set_path(path);
+        url.set_query(None);
+        if !query.is_empty() {
+            let mut pairs = url.query_pairs_mut();
+            for (k, v) in query {
+                pairs.append_pair(k, v);
+            }
+            drop(pairs);
+        }
+        Ok(url)
+    }
+}
+
+impl ClientBuilder {
+    pub fn host_allowlist(mut self, allowlist: HostAllowlist) -> Self {
+        self.host_allowlist = allowlist;
+        self
+    }
+
+    pub fn timeout(mut self, timeout: Duration) -> Self {
+        self.timeout = timeout;
+        self
+    }
+
+    pub fn build(self) -> Result<Client> {
+        let endpoint = url::Url::parse(&self.endpoint).map_err(|source| Error::InvalidEndpoint {
+            endpoint: self.endpoint.clone(),
+            source,
+        })?;
+        // Pre-flight the allowlist before we even hand back a Client, so
+        // operators see the rejection at startup rather than at first request.
+        self.host_allowlist.check(&endpoint)?;
+
+        let bearer_token = std::env::var(&self.bearer_token_env)
+            .ok()
+            .filter(|t| !t.trim().is_empty())
+            .ok_or(Error::BearerMissing {
+                env_var: self.bearer_token_env.clone(),
+            })?;
+
+        let inner = reqwest::Client::builder()
+            .timeout(self.timeout)
+            .build()
+            .map_err(|source| Error::Transport {
+                url: endpoint.to_string(),
+                source,
+            })?;
+        Ok(Client {
+            inner,
+            endpoint,
+            bearer_token,
+            host_allowlist: self.host_allowlist,
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde::Deserialize;
+    use std::sync::atomic::{AtomicU64, Ordering};
+    use wiremock::matchers::{header, method, path, query_param};
+    use wiremock::{Mock, MockServer, ResponseTemplate};
+
+    /// Tests that touch the process env share global state. Each test gets a
+    /// unique env-var name to avoid races under parallel execution.
+    fn unique_bearer_env() -> String {
+        static SEQ: AtomicU64 = AtomicU64::new(0);
+        let n = SEQ.fetch_add(1, Ordering::Relaxed);
+        format!("TC_OPERATOR_CLIENT_TEST_BEARER_{n}")
+    }
+
+    struct EnvGuard {
+        name: String,
+    }
+
+    impl EnvGuard {
+        fn set(name: String, value: &str) -> Self {
+            // SAFETY: edition 2024 marks env mutation unsafe. We use a unique
+            // name per test so no other thread reads or writes this variable.
+            unsafe {
+                std::env::set_var(&name, value);
+            }
+            EnvGuard { name }
+        }
+    }
+
+    impl Drop for EnvGuard {
+        fn drop(&mut self) {
+            // SAFETY: see EnvGuard::set.
+            unsafe {
+                std::env::remove_var(&self.name);
+            }
+        }
+    }
+
+    #[tokio::test]
+    async fn builder_resolves_bearer_from_env() {
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "secret-token");
+        let client = Client::builder("https://api.example", env)
+            .build()
+            .expect("client builds");
+        assert!(client.endpoint().starts_with("https://api.example"));
+    }
+
+    #[tokio::test]
+    async fn builder_refuses_when_bearer_env_missing() {
+        let env = unique_bearer_env();
+        // Not set.
+        let err = Client::builder("https://api.example", env)
+            .build()
+            .unwrap_err();
+        assert_eq!(err.kind(), "bearer-missing");
+    }
+
+    #[tokio::test]
+    async fn builder_refuses_when_bearer_env_is_empty() {
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "");
+        let err = Client::builder("https://api.example", env)
+            .build()
+            .unwrap_err();
+        assert_eq!(err.kind(), "bearer-missing");
+    }
+
+    #[tokio::test]
+    async fn builder_refuses_when_endpoint_blocked_by_allowlist() {
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "secret");
+        let err = Client::builder("https://evil.example", env)
+            .host_allowlist(HostAllowlist::from_csv("api.example"))
+            .build()
+            .unwrap_err();
+        assert_eq!(err.kind(), "host-not-allowed");
+    }
+
+    #[derive(Debug, Deserialize, PartialEq, Eq)]
+    struct ListResponse {
+        items: Vec<String>,
+    }
+
+    #[derive(Debug, Serialize)]
+    struct DecisionBody {
+        decision: String,
+    }
+
+    #[tokio::test]
+    async fn call_json_round_trips_typed_response() {
+        let server = MockServer::start().await;
+        Mock::given(method("GET"))
+            .and(path("/v1/traces/quarantine"))
+            .and(query_param("state", "leased"))
+            .and(header("authorization", "Bearer secret"))
+            .respond_with(
+                ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                    "items": ["sub-1", "sub-2"],
+                })),
+            )
+            .expect(1)
+            .mount(&server)
+            .await;
+
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "secret");
+        let client = Client::builder(server.uri(), env)
+            .build()
+            .expect("client builds");
+        let resp: ListResponse = client
+            .call_json::<(), ListResponse>(
+                Method::GET,
+                "/v1/traces/quarantine",
+                &[("state", "leased")],
+                None,
+            )
+            .await
+            .expect("typed response");
+        assert_eq!(
+            resp,
+            ListResponse {
+                items: vec!["sub-1".into(), "sub-2".into()],
+            }
+        );
+    }
+
+    #[tokio::test]
+    async fn call_json_surfaces_server_label_on_403() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/v1/traces/sub-1/review"))
+            .respond_with(
+                ResponseTemplate::new(403)
+                    .set_body_json(serde_json::json!({"error": "ReviewerNotAuthorized"})),
+            )
+            .expect(1)
+            .mount(&server)
+            .await;
+
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "secret");
+        let client = Client::builder(server.uri(), env)
+            .build()
+            .expect("client builds");
+        let err = client
+            .call_json::<DecisionBody, serde_json::Value>(
+                Method::POST,
+                "/v1/traces/sub-1/review",
+                &[],
+                Some(&DecisionBody {
+                    decision: "approve".into(),
+                }),
+            )
+            .await
+            .unwrap_err();
+        assert_eq!(err.kind(), "server-label");
+        assert_eq!(err.server_label(), Some("ReviewerNotAuthorized"));
+    }
+
+    #[tokio::test]
+    async fn call_json_falls_back_to_http_failure_when_body_has_no_label() {
+        let server = MockServer::start().await;
+        Mock::given(method("GET"))
+            .and(path("/v1/traces/foo"))
+            .respond_with(ResponseTemplate::new(500).set_body_string("internal server error"))
+            .expect(1)
+            .mount(&server)
+            .await;
+
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "secret");
+        let client = Client::builder(server.uri(), env)
+            .build()
+            .expect("client builds");
+        let err = client
+            .call_json::<(), serde_json::Value>(Method::GET, "/v1/traces/foo", &[], None)
+            .await
+            .unwrap_err();
+        assert_eq!(err.kind(), "http-failure");
+    }
+
+    #[tokio::test]
+    async fn call_json_surfaces_malformed_response_when_body_isnt_valid_for_type() {
+        let server = MockServer::start().await;
+        Mock::given(method("GET"))
+            .and(path("/v1/traces/foo"))
+            .respond_with(ResponseTemplate::new(200).set_body_string("not json at all"))
+            .expect(1)
+            .mount(&server)
+            .await;
+
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "secret");
+        let client = Client::builder(server.uri(), env)
+            .build()
+            .expect("client builds");
+        let err = client
+            .call_json::<(), ListResponse>(Method::GET, "/v1/traces/foo", &[], None)
+            .await
+            .unwrap_err();
+        assert_eq!(err.kind(), "malformed-response");
+    }
+
+    #[tokio::test]
+    async fn call_raw_returns_unparsed_body_on_success() {
+        let server = MockServer::start().await;
+        Mock::given(method("GET"))
+            .and(path("/v1/traces/raw"))
+            .respond_with(ResponseTemplate::new(200).set_body_string(r#"{"a":1}"#))
+            .expect(1)
+            .mount(&server)
+            .await;
+
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "secret");
+        let client = Client::builder(server.uri(), env)
+            .build()
+            .expect("client builds");
+        let body = client
+            .call_raw::<()>(Method::GET, "/v1/traces/raw", &[], None)
+            .await
+            .expect("raw body");
+        assert_eq!(body, r#"{"a":1}"#);
+    }
+}
diff --git a/crates/trace-commons-operator-client/src/error.rs b/crates/trace-commons-operator-client/src/error.rs
new file mode 100644
index 000000000..ac0733a3f
--- /dev/null
+++ b/crates/trace-commons-operator-client/src/error.rs
@@ -0,0 +1,262 @@
+//! Typed errors surfaced by the operator HTTP client.
+//!
+//! The server speaks a `{"error": "<Label>"}` envelope on non-success status.
+//! Operator binaries should map each label to a human-actionable diagnostic;
+//! [`Error::ServerLabel`] preserves the raw label so callers can pattern-match.
+
+use thiserror::Error;
+
+pub type Result<T> = std::result::Result<T, Error>;
+
+#[derive(Debug, Error)]
+pub enum Error {
+    /// Bearer-token env var not set or empty.
+    #[error("{env_var} is not set; refusing to call trace-commons API without credentials")]
+    BearerMissing { env_var: String },
+
+    /// Endpoint URL did not parse.
+    #[error("invalid trace-commons endpoint {endpoint}: {source}")]
+    InvalidEndpoint {
+        endpoint: String,
+        #[source]
+        source: url::ParseError,
+    },
+
+    /// Endpoint host is not on the operator's allowlist.
+    #[error("trace-commons endpoint host {host} is not on the allowed-hosts list ({allowed})")]
+    HostNotAllowed { host: String, allowed: String },
+
+    /// Network or transport-level failure (DNS, TLS, timeout, connection reset).
+    #[error("trace-commons API request to {url} failed: {source}")]
+    Transport {
+        url: String,
+        #[source]
+        source: reqwest::Error,
+    },
+
+    /// Server returned non-success status WITHOUT a structured `{"error": ...}` body.
+    #[error("trace-commons API request to {url} failed with {status}: {body}")]
+    HttpFailure {
+        url: String,
+        status: reqwest::StatusCode,
+        body: String,
+    },
+
+    /// Server returned non-success status WITH a typed label in the body.
+    /// Binary code should match on `label` to produce audience-specific diagnostics.
+    #[error("trace-commons API request to {url} failed with {status} ({label})")]
+    ServerLabel {
+        url: String,
+        status: reqwest::StatusCode,
+        label: String,
+        body: String,
+    },
+
+    /// Server returned a success status but the response body didn't deserialize
+    /// into the expected type.
+    #[error("trace-commons API at {url} returned malformed response: {source}")]
+    MalformedResponse {
+        url: String,
+        body: String,
+        #[source]
+        source: serde_json::Error,
+    },
+}
+
+/// Strip query strings + fragments from a URL for safe inclusion in error
+/// messages and logs. The host allowlist + bearer-token gate are enforced
+/// before any request leaves the process, so credentials should never reach
+/// query strings — but defense-in-depth.
+pub(crate) fn sanitize_url_for_display(url: &str) -> String {
+    match url::Url::parse(url) {
+        Ok(mut parsed) => {
+            parsed.set_query(None);
+            parsed.set_fragment(None);
+            parsed.to_string()
+        }
+        Err(_) => url.split(['?', '#']).next().unwrap_or(url).to_string(),
+    }
+}
+
+/// Parse a `{"error": "<Label>"}` envelope out of a non-success response body.
+/// Returns `None` if the body isn't valid JSON or doesn't have a string `error`
+/// field — caller falls back to [`Error::HttpFailure`].
+pub(crate) fn parse_error_label(body: &str) -> Option<String> {
+    let value: serde_json::Value = serde_json::from_str(body.trim()).ok()?;
+    value
+        .get("error")
+        .and_then(|v| v.as_str())
+        .map(|s| s.to_string())
+}
+
+impl Error {
+    /// Returns the typed server label if this is a [`Error::ServerLabel`].
+    pub fn server_label(&self) -> Option<&str> {
+        match self {
+            Error::ServerLabel { label, .. } => Some(label.as_str()),
+            _ => None,
+        }
+    }
+}
+
+impl Error {
+    /// Convenience for tests + diagnostics: short kind tag.
+    pub fn kind(&self) -> &'static str {
+        match self {
+            Error::BearerMissing { .. } => "bearer-missing",
+            Error::InvalidEndpoint { .. } => "invalid-endpoint",
+            Error::HostNotAllowed { .. } => "host-not-allowed",
+            Error::Transport { .. } => "transport",
+            Error::HttpFailure { .. } => "http-failure",
+            Error::ServerLabel { .. } => "server-label",
+            Error::MalformedResponse { .. } => "malformed-response",
+        }
+    }
+}
+
+// Display-only safe accessors for use in user-facing CLI output.
+impl Error {
+    /// Returns a one-line user-facing diagnostic that strips query strings
+    /// and bodies. Operator binaries should prefer this for `stderr` output;
+    /// the full Debug form is for verbose logging only.
+    pub fn user_diagnostic(&self) -> String {
+        match self {
+            Error::BearerMissing { env_var } => format!(
+                "credential refused: ${env_var} not set"
+            ),
+            Error::InvalidEndpoint { endpoint, .. } => format!(
+                "endpoint URL is malformed: {}",
+                sanitize_url_for_display(endpoint)
+            ),
+            Error::HostNotAllowed { host, allowed } => format!(
+                "host {host} blocked by allowed-hosts list ({allowed})"
+            ),
+            Error::Transport { url, source } => format!(
+                "request to {} failed: {source}",
+                sanitize_url_for_display(url)
+            ),
+            Error::HttpFailure { url, status, .. } => format!(
+                "{} returned HTTP {status}",
+                sanitize_url_for_display(url)
+            ),
+            Error::ServerLabel {
+                url, status, label, ..
+            } => format!(
+                "{} refused with HTTP {status} ({label})",
+                sanitize_url_for_display(url)
+            ),
+            Error::MalformedResponse { url, .. } => format!(
+                "{} returned a response the operator client could not parse",
+                sanitize_url_for_display(url)
+            ),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn sanitize_url_drops_query_and_fragment() {
+        assert_eq!(
+            sanitize_url_for_display("https://api.example/v1/traces?token=secret"),
+            "https://api.example/v1/traces"
+        );
+        assert_eq!(
+            sanitize_url_for_display("https://api.example/v1/traces#frag"),
+            "https://api.example/v1/traces"
+        );
+        assert_eq!(
+            sanitize_url_for_display("https://api.example/v1/traces?a=1&b=2#frag"),
+            "https://api.example/v1/traces"
+        );
+    }
+
+    #[test]
+    fn sanitize_url_preserves_path_on_invalid_input() {
+        assert_eq!(
+            sanitize_url_for_display("not-a-url?token=secret"),
+            "not-a-url"
+        );
+    }
+
+    #[test]
+    fn parse_error_label_extracts_label_from_well_formed_envelope() {
+        let body = r#"{"error":"PilotAllowlistNotMatched"}"#;
+        assert_eq!(
+            parse_error_label(body).as_deref(),
+            Some("PilotAllowlistNotMatched")
+        );
+    }
+
+    #[test]
+    fn parse_error_label_returns_none_for_non_json_body() {
+        assert_eq!(parse_error_label("Internal Server Error"), None);
+    }
+
+    #[test]
+    fn parse_error_label_returns_none_when_error_field_missing() {
+        let body = r#"{"detail":"oops"}"#;
+        assert_eq!(parse_error_label(body), None);
+    }
+
+    #[test]
+    fn parse_error_label_returns_none_when_error_field_not_string() {
+        let body = r#"{"error":42}"#;
+        assert_eq!(parse_error_label(body), None);
+    }
+
+    #[test]
+    fn server_label_accessor_returns_label_only_for_server_label_variant() {
+        let labeled = Error::ServerLabel {
+            url: "https://api.example/v1/traces".into(),
+            status: reqwest::StatusCode::FORBIDDEN,
+            label: "PilotAllowlistNotMatched".into(),
+            body: "{}".into(),
+        };
+        assert_eq!(labeled.server_label(), Some("PilotAllowlistNotMatched"));
+
+        let bearer = Error::BearerMissing {
+            env_var: "TRACE_COMMONS_REVIEWER_BEARER".into(),
+        };
+        assert_eq!(bearer.server_label(), None);
+    }
+
+    #[test]
+    fn user_diagnostic_strips_query_strings() {
+        let err = Error::HttpFailure {
+            url: "https://api.example/v1/traces?token=secret".into(),
+            status: reqwest::StatusCode::INTERNAL_SERVER_ERROR,
+            body: "...".into(),
+        };
+        let diag = err.user_diagnostic();
+        assert!(
+            !diag.contains("token=secret"),
+            "diagnostic leaked query string: {diag}"
+        );
+        assert!(diag.contains("https://api.example/v1/traces"));
+    }
+
+    #[test]
+    fn kind_tags_are_stable() {
+        let cases = [
+            (
+                Error::BearerMissing {
+                    env_var: "X".into(),
+                },
+                "bearer-missing",
+            ),
+            (
+                Error::HostNotAllowed {
+                    host: "evil.example".into(),
+                    allowed: "api.example".into(),
+                },
+                "host-not-allowed",
+            ),
+        ];
+        for (err, want) in cases {
+            assert_eq!(err.kind(), want);
+        }
+    }
+}
diff --git a/crates/trace-commons-operator-client/src/format.rs b/crates/trace-commons-operator-client/src/format.rs
new file mode 100644
index 000000000..306a42997
--- /dev/null
+++ b/crates/trace-commons-operator-client/src/format.rs
@@ -0,0 +1,210 @@
+//! Output formatting helpers for operator binaries.
+//!
+//! Every operator binary exposes a `--json` flag. When set, the binary
+//! emits a uniform envelope:
+//!
+//! ```json
+//! { "request": { "method": "GET", "url": "<sanitized>" }, "data": <server-response> }
+//! ```
+//!
+//! When `--json` is not set, the binary prints a human-readable rendering
+//! that varies per command. The helpers here cover the common patterns:
+//!
+//! - [`emit_json`] — write the wrapper envelope to a writer.
+//! - [`print_table`] — render a fixed-column ASCII table for list endpoints.
+//! - [`print_kv`] — render a "label: value" block for single-item endpoints.
+
+use std::io::{self, Write};
+
+use serde::Serialize;
+
+/// Wrapper envelope for `--json` output. Generic over the server payload
+/// so each command can describe its own response shape statically.
+#[derive(Debug, Serialize)]
+pub struct JsonEnvelope<'a, T: Serialize> {
+    pub request: JsonRequestSummary<'a>,
+    pub data: &'a T,
+}
+
+#[derive(Debug, Serialize)]
+pub struct JsonRequestSummary<'a> {
+    pub method: &'a str,
+    /// URL with query string + fragment stripped.
+    pub url: String,
+}
+
+/// Write the JSON envelope to `out`, pretty-printed for human inspection.
+pub fn emit_json<T: Serialize, W: Write>(
+    out: &mut W,
+    method: &str,
+    url: &str,
+    data: &T,
+) -> io::Result<()> {
+    let envelope = JsonEnvelope {
+        request: JsonRequestSummary {
+            method,
+            url: crate::error::sanitize_url_for_display(url),
+        },
+        data,
+    };
+    serde_json::to_writer_pretty(&mut *out, &envelope).map_err(io::Error::other)?;
+    out.write_all(b"\n")
+}
+
+/// Render a list of rows as a fixed-column ASCII table. Each row is a
+/// `Vec<String>` matching `headers.len()`. Columns are sized to the longest
+/// cell (header or data) and separated by two spaces.
+///
+/// Rows that don't match `headers.len()` are skipped with a warning written
+/// to `out`'s sibling stderr-equivalent — callers should validate row shape
+/// before calling.
+pub fn print_table<W: Write>(
+    out: &mut W,
+    headers: &[&str],
+    rows: &[Vec<String>],
+) -> io::Result<()> {
+    if headers.is_empty() {
+        return Ok(());
+    }
+    let mut widths: Vec<usize> = headers.iter().map(|h| h.len()).collect();
+    for row in rows {
+        if row.len() != headers.len() {
+            continue;
+        }
+        for (i, cell) in row.iter().enumerate() {
+            widths[i] = widths[i].max(cell.len());
+        }
+    }
+
+    write_row(out, headers, &widths)?;
+    // Underline.
+    let underline: Vec<String> = widths.iter().map(|w| "-".repeat(*w)).collect();
+    let underline_refs: Vec<&str> = underline.iter().map(|s| s.as_str()).collect();
+    write_row(out, &underline_refs, &widths)?;
+
+    for row in rows {
+        if row.len() != headers.len() {
+            continue;
+        }
+        let row_refs: Vec<&str> = row.iter().map(|s| s.as_str()).collect();
+        write_row(out, &row_refs, &widths)?;
+    }
+    Ok(())
+}
+
+fn write_row<W: Write>(out: &mut W, cells: &[&str], widths: &[usize]) -> io::Result<()> {
+    for (i, cell) in cells.iter().enumerate() {
+        if i > 0 {
+            out.write_all(b"  ")?;
+        }
+        write!(out, "{:<width$}", cell, width = widths[i])?;
+    }
+    out.write_all(b"\n")
+}
+
+/// Render a `(label, value)` block where labels are right-padded to a uniform
+/// width. Useful for "show single record" commands.
+pub fn print_kv<W: Write>(out: &mut W, pairs: &[(&str, &str)]) -> io::Result<()> {
+    if pairs.is_empty() {
+        return Ok(());
+    }
+    let width = pairs.iter().map(|(k, _)| k.len()).max().unwrap_or(0);
+    for (k, v) in pairs {
+        writeln!(out, "{:<width$}  {}", k, v, width = width)?;
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde::Serialize;
+
+    #[derive(Debug, Serialize)]
+    struct Sample {
+        id: String,
+        approved: bool,
+    }
+
+    #[test]
+    fn emit_json_writes_envelope_with_sanitized_url() {
+        let mut buf = Vec::new();
+        emit_json(
+            &mut buf,
+            "GET",
+            "https://api.example/v1/traces?token=secret",
+            &Sample {
+                id: "sub-1".into(),
+                approved: true,
+            },
+        )
+        .unwrap();
+        let out = String::from_utf8(buf).unwrap();
+        assert!(out.contains(r#""method": "GET""#));
+        assert!(out.contains(r#""url": "https://api.example/v1/traces""#));
+        assert!(!out.contains("token=secret"));
+        assert!(out.contains(r#""id": "sub-1""#));
+        assert!(out.contains(r#""approved": true"#));
+    }
+
+    #[test]
+    fn print_table_renders_header_underline_and_rows() {
+        let mut buf = Vec::new();
+        print_table(
+            &mut buf,
+            &["id", "status"],
+            &[
+                vec!["sub-1".into(), "leased".into()],
+                vec!["sub-22".into(), "approved".into()],
+            ],
+        )
+        .unwrap();
+        let out = String::from_utf8(buf).unwrap();
+        let lines: Vec<&str> = out.lines().collect();
+        assert_eq!(lines.len(), 4);
+        assert_eq!(lines[0], "id      status  ");
+        assert_eq!(lines[1], "------  --------");
+        assert_eq!(lines[2], "sub-1   leased  ");
+        assert_eq!(lines[3], "sub-22  approved");
+    }
+
+    #[test]
+    fn print_table_skips_rows_with_wrong_arity() {
+        let mut buf = Vec::new();
+        print_table(
+            &mut buf,
+            &["id", "status"],
+            &[
+                vec!["sub-1".into()], // skipped
+                vec!["sub-2".into(), "approved".into(), "extra".into()], // skipped
+                vec!["sub-3".into(), "leased".into()],
+            ],
+        )
+        .unwrap();
+        let out = String::from_utf8(buf).unwrap();
+        assert!(out.contains("sub-3"));
+        assert!(!out.contains("sub-1"));
+        assert!(!out.contains("sub-2"));
+    }
+
+    #[test]
+    fn print_kv_pads_labels_uniformly() {
+        let mut buf = Vec::new();
+        print_kv(
+            &mut buf,
+            &[("id", "sub-1"), ("submission_status", "approved")],
+        )
+        .unwrap();
+        let out = String::from_utf8(buf).unwrap();
+        let lines: Vec<&str> = out.lines().collect();
+        assert_eq!(lines[0], "id                 sub-1");
+        assert_eq!(lines[1], "submission_status  approved");
+    }
+
+    #[test]
+    fn print_kv_handles_empty_input() {
+        let mut buf = Vec::new();
+        print_kv(&mut buf, &[]).unwrap();
+        assert!(buf.is_empty());
+    }
+}
diff --git a/crates/trace-commons-operator-client/src/host_allowlist.rs b/crates/trace-commons-operator-client/src/host_allowlist.rs
new file mode 100644
index 000000000..15ccd9a2c
--- /dev/null
+++ b/crates/trace-commons-operator-client/src/host_allowlist.rs
@@ -0,0 +1,158 @@
+//! Defense-in-depth host allowlist.
+//!
+//! Operator binaries that talk to trace-commons-server endpoints may also be
+//! invoked against staging or testnet deployments. To avoid an operator
+//! accidentally pointing a production-credentialed binary at an attacker-
+//! controlled URL (e.g. via a poisoned env var), the [`Client`] enforces
+//! that the target endpoint's host is on an explicit allowlist before any
+//! request leaves the process.
+//!
+//! The allowlist is sourced from:
+//!   1. The `--allowed-hosts <CSV>` CLI flag, or
+//!   2. The `TRACE_COMMONS_ALLOWED_HOSTS` env var, or
+//!   3. `None`, in which case host enforcement is OFF (legacy behavior).
+//!
+//! When the allowlist is set, host matching is exact (case-insensitive ASCII).
+//! Wildcards and CIDRs are not supported — we want this list reviewable at a
+//! glance.
+//!
+//! [`Client`]: crate::Client
+
+use std::collections::BTreeSet;
+
+use crate::error::{Error, Result};
+
+#[derive(Debug, Clone, Default)]
+pub struct HostAllowlist {
+    hosts: Option<BTreeSet<String>>,
+}
+
+impl HostAllowlist {
+    /// Allowlist that lets every host through. Equivalent to legacy behavior.
+    pub fn permissive() -> Self {
+        Self { hosts: None }
+    }
+
+    /// Construct from a CSV string like `"api.example,staging.example"`.
+    /// Empty entries are dropped. If the resulting set is empty, returns
+    /// a permissive allowlist (callers can detect via [`Self::is_enforcing`]).
+    pub fn from_csv(csv: &str) -> Self {
+        let hosts: BTreeSet<String> = csv
+            .split(',')
+            .map(|h| h.trim().to_ascii_lowercase())
+            .filter(|h| !h.is_empty())
+            .collect();
+        if hosts.is_empty() {
+            Self::permissive()
+        } else {
+            Self { hosts: Some(hosts) }
+        }
+    }
+
+    /// Read the allowlist from the `TRACE_COMMONS_ALLOWED_HOSTS` env var.
+    /// Returns a permissive allowlist if the var is unset or empty.
+    pub fn from_env() -> Self {
+        match std::env::var("TRACE_COMMONS_ALLOWED_HOSTS") {
+            Ok(csv) => Self::from_csv(&csv),
+            Err(_) => Self::permissive(),
+        }
+    }
+
+    pub fn is_enforcing(&self) -> bool {
+        self.hosts.is_some()
+    }
+
+    /// Confirm that a target URL's host is on the allowlist. No-op when the
+    /// allowlist is permissive.
+    pub fn check(&self, url: &url::Url) -> Result<()> {
+        let Some(allowed) = &self.hosts else {
+            return Ok(());
+        };
+        let host = url
+            .host_str()
+            .ok_or_else(|| Error::InvalidEndpoint {
+                endpoint: url.to_string(),
+                source: url::ParseError::EmptyHost,
+            })?
+            .to_ascii_lowercase();
+        if allowed.contains(&host) {
+            Ok(())
+        } else {
+            Err(Error::HostNotAllowed {
+                host,
+                allowed: allowed
+                    .iter()
+                    .cloned()
+                    .collect::<Vec<_>>()
+                    .join(","),
+            })
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn url(s: &str) -> url::Url {
+        url::Url::parse(s).expect("valid url in test")
+    }
+
+    #[test]
+    fn permissive_allowlist_lets_anything_through() {
+        let allowlist = HostAllowlist::permissive();
+        assert!(!allowlist.is_enforcing());
+        allowlist.check(&url("https://evil.example/v1/traces")).unwrap();
+    }
+
+    #[test]
+    fn csv_allowlist_enforces_exact_match() {
+        let allowlist = HostAllowlist::from_csv("api.example,staging.example");
+        assert!(allowlist.is_enforcing());
+        allowlist.check(&url("https://api.example/v1/traces")).unwrap();
+        allowlist
+            .check(&url("https://staging.example/v1/traces"))
+            .unwrap();
+    }
+
+    #[test]
+    fn csv_allowlist_rejects_unlisted_host() {
+        let allowlist = HostAllowlist::from_csv("api.example");
+        let err = allowlist
+            .check(&url("https://evil.example/v1/traces"))
+            .unwrap_err();
+        assert_eq!(err.kind(), "host-not-allowed");
+    }
+
+    #[test]
+    fn csv_allowlist_is_case_insensitive() {
+        let allowlist = HostAllowlist::from_csv("API.Example");
+        allowlist
+            .check(&url("https://api.example/v1/traces"))
+            .unwrap();
+    }
+
+    #[test]
+    fn empty_csv_yields_permissive_allowlist() {
+        let allowlist = HostAllowlist::from_csv("");
+        assert!(!allowlist.is_enforcing());
+    }
+
+    #[test]
+    fn csv_drops_empty_and_whitespace_entries() {
+        let allowlist = HostAllowlist::from_csv(" , api.example , ,");
+        assert!(allowlist.is_enforcing());
+        allowlist
+            .check(&url("https://api.example/v1/traces"))
+            .unwrap();
+    }
+
+    #[test]
+    fn subdomain_is_not_a_wildcard_match() {
+        let allowlist = HostAllowlist::from_csv("api.example");
+        let err = allowlist
+            .check(&url("https://sub.api.example/v1/traces"))
+            .unwrap_err();
+        assert_eq!(err.kind(), "host-not-allowed");
+    }
+}
diff --git a/crates/trace-commons-operator-client/src/lib.rs b/crates/trace-commons-operator-client/src/lib.rs
new file mode 100644
index 000000000..d14068ef9
--- /dev/null
+++ b/crates/trace-commons-operator-client/src/lib.rs
@@ -0,0 +1,24 @@
+//! Shared HTTP client surface for trace-commons-server operator binaries.
+//!
+//! This crate is consumed by the four operator binaries
+//! (`trace-commons-review`, `trace-commons-worker`, `trace-commons-admin`,
+//! `trace-commons-tenant`). It owns:
+//!
+//! - The HTTP transport ([`Client`]), including bearer-token resolution,
+//!   defense-in-depth host allowlist enforcement, and typed error mapping
+//!   for the server's `{"error": "<Label>"}` refusal envelope.
+//! - Foundational types shared across all operator audiences (scopes,
+//!   pagination, JSON-or-text rendering).
+//!
+//! Per-endpoint typed request/response structs land in the binary PRs
+//! (#2 reviewer + admin, #3 worker + tenant). Each binary's `Cargo.toml`
+//! adds the structs it needs in its own module; structs that are reused
+//! across binaries migrate here.
+
+pub mod client;
+pub mod error;
+pub mod format;
+pub mod host_allowlist;
+
+pub use client::Client;
+pub use error::{Error, Result};

From 0fef936a66511303fff6b818dd89a1587fbac727 Mon Sep 17 00:00:00 2001
From: Zaki <zaki@iqlusion.io>
Date: Tue, 19 May 2026 15:07:53 -0700
Subject: [PATCH 2/7] Add trace-commons-review and trace-commons-admin operator
 binaries

Wire up the reviewer-audience (8 subcommands) and admin-audience
(12 subcommands) CLI binaries on top of the trace-commons-operator-client
foundation crate. Each binary takes a top-level --endpoint, --bearer-token-env,
--allowed-hosts, and --json flag and delegates per-endpoint typing to the
foundation Client. A shared operator_common module exposes table / kv / map
rendering helpers consumed by both bins via #[path = ...].

Coverage matches the Ironclaw reference handlers in
crates/ironclaw_reborn_cli/src/commands/traces.rs at the same paths
(/v1/review/*, /v1/admin/*, /v1/benchmarks/*, /v1/datasets/replay,
/v1/analytics/summary).
---
 Cargo.lock                                    |    1 +
 crates/trace-commons-server/Cargo.toml        |    9 +
 .../src/bin/operator_common/mod.rs            |  190 +++
 .../src/bin/trace-commons-admin.rs            | 1458 +++++++++++++++++
 .../src/bin/trace-commons-review.rs           |  897 ++++++++++
 5 files changed, 2555 insertions(+)
 create mode 100644 crates/trace-commons-server/src/bin/operator_common/mod.rs
 create mode 100644 crates/trace-commons-server/src/bin/trace-commons-admin.rs
 create mode 100644 crates/trace-commons-server/src/bin/trace-commons-review.rs

diff --git a/Cargo.lock b/Cargo.lock
index 02d924d19..33f1b9f75 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -7113,6 +7113,7 @@ dependencies = [
  "toml 1.1.2+spec-1.1.0",
  "tower 0.5.3",
  "trace-commons-gate-enclave",
+ "trace-commons-operator-client",
  "trace-commons-protocol",
  "tracing",
  "tracing-subscriber",
diff --git a/crates/trace-commons-server/Cargo.toml b/crates/trace-commons-server/Cargo.toml
index 58797fe1d..2449014c0 100644
--- a/crates/trace-commons-server/Cargo.toml
+++ b/crates/trace-commons-server/Cargo.toml
@@ -37,6 +37,7 @@ toml = "1"
 zstd = "0.13"
 tokio-postgres = { version = "0.7", features = ["with-uuid-1", "with-chrono-0_4", "with-serde_json-1"] }
 trace-commons-gate-enclave = { path = "../trace-commons-gate-enclave" }
+trace-commons-operator-client = { path = "../trace-commons-operator-client" }
 trace-commons-protocol = { path = "../trace-commons-protocol" }
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] }
@@ -88,6 +89,14 @@ required-features = ["local-gpu-models"]
 name = "trace-commons-pilot-bootstrap"
 path = "src/bin/trace-commons-pilot-bootstrap.rs"
 
+[[bin]]
+name = "trace-commons-review"
+path = "src/bin/trace-commons-review.rs"
+
+[[bin]]
+name = "trace-commons-admin"
+path = "src/bin/trace-commons-admin.rs"
+
 [dev-dependencies]
 tower = { version = "0.5", features = ["util"] }
 wiremock = "0.6"
diff --git a/crates/trace-commons-server/src/bin/operator_common/mod.rs b/crates/trace-commons-server/src/bin/operator_common/mod.rs
new file mode 100644
index 000000000..717a74261
--- /dev/null
+++ b/crates/trace-commons-server/src/bin/operator_common/mod.rs
@@ -0,0 +1,190 @@
+//! Helpers shared by the operator binaries (`trace-commons-review`,
+//! `trace-commons-admin`). Brought into each binary via
+//! `#[path = "operator_common/mod.rs"] mod operator_common;`.
+//!
+//! The functions here are intentionally small and concern themselves with
+//! rendering JSON values produced by the trace-commons-server API. They never
+//! log bearer tokens or query strings. URL sanitization happens inside the
+//! foundation crate.
+//!
+//! Each binary uses a subset of these helpers, so we tag the module with
+//! `#![allow(dead_code)]` to silence per-bin warnings for the helpers that
+//! aren't exercised in one of the two surfaces.
+
+#![allow(dead_code)]
+
+use std::io::Write;
+
+use serde_json::Value;
+use trace_commons_operator_client::format;
+
+/// Print an `{"items": [...]}` (or top-level array) list response as a
+/// fixed-column table. `columns` is the ordered list of JSON field names; the
+/// header row uses the same names verbatim so operators can correlate the
+/// rendered output with the server schema.
+pub fn render_items<W: Write>(
+    out: &mut W,
+    label: &str,
+    value: &Value,
+    columns: &[&str],
+) -> std::io::Result<()> {
+    let items_value = value.get("items").unwrap_or(value);
+    let items = items_value.as_array();
+    writeln!(out, "{label}:")?;
+    let Some(items) = items else {
+        writeln!(out, "  (no items)")?;
+        return Ok(());
+    };
+    if items.is_empty() {
+        writeln!(out, "  (no items)")?;
+        return Ok(());
+    }
+    let rows: Vec<Vec<String>> = items
+        .iter()
+        .map(|item| {
+            columns
+                .iter()
+                .map(|col| stringify_field(item.get(col)))
+                .collect()
+        })
+        .collect();
+    format::print_table(out, columns, &rows)
+}
+
+/// Print an object's fields as a "label: value" block. Each entry is rendered
+/// only if the field is present and non-null. Indentation matches the
+/// Ironclaw CLI conventions ("  label").
+pub fn render_kv_fields<W: Write>(
+    out: &mut W,
+    value: &Value,
+    pairs: &[(&str, &str)],
+) -> std::io::Result<()> {
+    let mut rendered: Vec<(String, String)> = Vec::new();
+    for (label, field) in pairs {
+        if let Some(child) = value.get(field) {
+            if !child.is_null() {
+                rendered.push(((*label).to_string(), stringify_field(Some(child))));
+            }
+        }
+    }
+    if rendered.is_empty() {
+        return Ok(());
+    }
+    let refs: Vec<(&str, &str)> = rendered
+        .iter()
+        .map(|(k, v)| (k.as_str(), v.as_str()))
+        .collect();
+    format::print_kv(out, &refs)
+}
+
+/// Render a JSON object's keys as a simple "k=v" map. Used by analytics
+/// summary's `by_status`, `by_privacy_risk`, etc.
+pub fn render_json_map<W: Write>(
+    out: &mut W,
+    label: &str,
+    value: Option<&Value>,
+) -> std::io::Result<()> {
+    let Some(value) = value else {
+        return Ok(());
+    };
+    let Some(obj) = value.as_object() else {
+        return Ok(());
+    };
+    if obj.is_empty() {
+        return Ok(());
+    }
+    writeln!(out, "{label}:")?;
+    for (k, v) in obj {
+        writeln!(out, "    {k}: {}", stringify_field(Some(v)))?;
+    }
+    Ok(())
+}
+
+fn stringify_field(value: Option<&Value>) -> String {
+    match value {
+        None | Some(Value::Null) => String::new(),
+        Some(Value::String(s)) => s.clone(),
+        Some(Value::Bool(b)) => b.to_string(),
+        Some(Value::Number(n)) => n.to_string(),
+        Some(other) => other.to_string(),
+    }
+}
+
+/// Compose the sanitized URL that `format::emit_json` should record. The
+/// foundation `format::emit_json` re-sanitizes via `sanitize_url_for_display`,
+/// so we only need to pass the endpoint + path here without a query string.
+pub fn sanitized_url(endpoint: &str, path: &str) -> String {
+    let endpoint = endpoint.trim_end_matches('/');
+    format!("{endpoint}{path}")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn render_items_handles_top_level_array() {
+        let mut buf = Vec::new();
+        let value = json!([{"id": "a", "status": "ok"}, {"id": "b", "status": "bad"}]);
+        render_items(&mut buf, "Items", &value, &["id", "status"]).unwrap();
+        let out = String::from_utf8(buf).unwrap();
+        assert!(out.contains("Items:"));
+        assert!(out.contains("id"));
+        assert!(out.contains("a"));
+        assert!(out.contains("bad"));
+    }
+
+    #[test]
+    fn render_items_handles_items_envelope() {
+        let mut buf = Vec::new();
+        let value = json!({"items": [{"id": "x", "status": "ok"}]});
+        render_items(&mut buf, "Items", &value, &["id", "status"]).unwrap();
+        let out = String::from_utf8(buf).unwrap();
+        assert!(out.contains("x"));
+    }
+
+    #[test]
+    fn render_items_handles_empty() {
+        let mut buf = Vec::new();
+        let value = json!({"items": []});
+        render_items(&mut buf, "Items", &value, &["id"]).unwrap();
+        let out = String::from_utf8(buf).unwrap();
+        assert!(out.contains("(no items)"));
+    }
+
+    #[test]
+    fn render_kv_fields_skips_missing_and_null() {
+        let mut buf = Vec::new();
+        let value = json!({"a": "alpha", "b": null});
+        render_kv_fields(
+            &mut buf,
+            &value,
+            &[("a label", "a"), ("b label", "b"), ("c label", "c")],
+        )
+        .unwrap();
+        let out = String::from_utf8(buf).unwrap();
+        assert!(out.contains("alpha"));
+        assert!(!out.contains("b label"));
+        assert!(!out.contains("c label"));
+    }
+
+    #[test]
+    fn render_json_map_writes_entries() {
+        let mut buf = Vec::new();
+        let value = json!({"approved": 4, "rejected": 1});
+        render_json_map(&mut buf, "  by status", Some(&value)).unwrap();
+        let out = String::from_utf8(buf).unwrap();
+        assert!(out.contains("by status:"));
+        assert!(out.contains("approved: 4"));
+        assert!(out.contains("rejected: 1"));
+    }
+
+    #[test]
+    fn sanitized_url_trims_trailing_slash() {
+        assert_eq!(
+            sanitized_url("https://api.example/", "/v1/foo"),
+            "https://api.example/v1/foo"
+        );
+    }
+}
diff --git a/crates/trace-commons-server/src/bin/trace-commons-admin.rs b/crates/trace-commons-server/src/bin/trace-commons-admin.rs
new file mode 100644
index 000000000..c45cf78a7
--- /dev/null
+++ b/crates/trace-commons-server/src/bin/trace-commons-admin.rs
@@ -0,0 +1,1458 @@
+//! `trace-commons-admin` — admin-audience operator CLI.
+//!
+//! Twelve subcommands matching the admin-bearer endpoints on
+//! trace-commons-server. All requests are issued through the foundation
+//! `trace_commons_operator_client::Client`.
+
+#[path = "operator_common/mod.rs"]
+mod operator_common;
+
+use std::io::{stdout, Write};
+use std::path::PathBuf;
+
+use anyhow::Result;
+use clap::{Parser, Subcommand, ValueEnum};
+use reqwest::Method;
+use serde_json::Value;
+use trace_commons_operator_client::{format as oc_format, host_allowlist::HostAllowlist, Client};
+use uuid::Uuid;
+
+use operator_common::{render_items, render_json_map, render_kv_fields, sanitized_url};
+
+const DEFAULT_BEARER_ENV: &str = "TRACE_COMMONS_ADMIN_BEARER";
+
+#[derive(Debug, Parser)]
+#[command(
+    name = "trace-commons-admin",
+    about = "Admin-audience CLI for trace-commons-server.",
+    version
+)]
+pub(crate) struct Cli {
+    #[arg(long, env = "TRACE_COMMONS_ENDPOINT")]
+    pub endpoint: String,
+    #[arg(long, default_value = DEFAULT_BEARER_ENV)]
+    pub bearer_token_env: String,
+    #[arg(long, env = "TRACE_COMMONS_ALLOWED_HOSTS")]
+    pub allowed_hosts: Option<String>,
+    #[arg(long, global = true)]
+    pub json: bool,
+    #[command(subcommand)]
+    pub command: AdminSubcommand,
+}
+
+#[derive(Debug, Subcommand)]
+pub(crate) enum AdminSubcommand {
+    MaintenanceRun(MaintenanceRunArgs),
+    RetentionJobsList(RetentionJobsListArgs),
+    RetentionJobItems(RetentionJobItemsArgs),
+    ExportAccessGrantsList(ExportAccessGrantsListArgs),
+    ExportJobsList(ExportJobsListArgs),
+    BenchmarkConvert(BenchmarkConvertArgs),
+    BenchmarkLifecycleUpdate(BenchmarkLifecycleArgs),
+    ReplayDatasetExport(ReplayDatasetExportArgs),
+    ReplayExportManifests,
+    AnalyticsSummary,
+    OperationalSummary,
+    ConfigStatus,
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct MaintenanceRunArgs {
+    #[arg(long)]
+    pub purpose: String,
+    #[arg(long)]
+    pub dry_run: bool,
+    #[arg(long)]
+    pub backfill_db_mirror: bool,
+    #[arg(long)]
+    pub index_vectors: bool,
+    #[arg(long)]
+    pub reconcile_db_mirror: bool,
+    #[arg(long)]
+    pub verify_audit_chain: bool,
+    /// Prune the export cache as part of this run (default: true).
+    #[arg(long, default_value_t = true)]
+    pub prune_export_cache: bool,
+    #[arg(long)]
+    pub max_export_age_hours: Option<i64>,
+    #[arg(long)]
+    pub purge_expired_before: Option<String>,
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct RetentionJobsListArgs {
+    #[arg(long)]
+    pub limit: Option<usize>,
+    #[arg(long, value_enum)]
+    pub status: Option<RetentionJobStatus>,
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct RetentionJobItemsArgs {
+    #[arg(long)]
+    pub retention_job_id: Uuid,
+    #[arg(long)]
+    pub limit: Option<usize>,
+    #[arg(long, value_enum)]
+    pub action: Option<RetentionJobItemAction>,
+    #[arg(long, value_enum)]
+    pub status: Option<RetentionJobItemStatus>,
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct ExportAccessGrantsListArgs {
+    #[arg(long)]
+    pub limit: Option<usize>,
+    #[arg(long, value_enum)]
+    pub status: Option<ExportAccessGrantStatus>,
+    #[arg(long)]
+    pub dataset_kind: Option<String>,
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct ExportJobsListArgs {
+    #[arg(long)]
+    pub limit: Option<usize>,
+    #[arg(long, value_enum)]
+    pub status: Option<ExportJobStatus>,
+    #[arg(long)]
+    pub dataset_kind: Option<String>,
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct BenchmarkConvertArgs {
+    #[arg(long)]
+    pub purpose: String,
+    #[arg(long)]
+    pub limit: Option<usize>,
+    #[arg(long, value_enum)]
+    pub consent_scope: Option<ConsentScope>,
+    #[arg(long, value_enum)]
+    pub status: Option<CorpusStatus>,
+    #[arg(long, value_enum)]
+    pub privacy_risk: Option<PrivacyRisk>,
+    #[arg(long)]
+    pub external_ref: Option<String>,
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct BenchmarkLifecycleArgs {
+    #[arg(long)]
+    pub conversion_id: Uuid,
+    #[arg(long, value_enum)]
+    pub registry_status: Option<BenchmarkRegistryStatus>,
+    #[arg(long)]
+    pub registry_ref: Option<String>,
+    #[arg(long)]
+    pub published_at: Option<String>,
+    #[arg(long, value_enum)]
+    pub evaluation_status: Option<BenchmarkEvaluationStatus>,
+    #[arg(long)]
+    pub evaluator_ref: Option<String>,
+    #[arg(long)]
+    pub evaluated_at: Option<String>,
+    #[arg(long)]
+    pub score: Option<f32>,
+    #[arg(long)]
+    pub pass_count: Option<u32>,
+    #[arg(long)]
+    pub fail_count: Option<u32>,
+    #[arg(long)]
+    pub reason: Option<String>,
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct ReplayDatasetExportArgs {
+    #[arg(long)]
+    pub purpose: Option<String>,
+    #[arg(long, value_enum)]
+    pub consent_scope: Option<ConsentScope>,
+    #[arg(long, value_enum)]
+    pub status: Option<CorpusStatus>,
+    #[arg(long, value_enum)]
+    pub privacy_risk: Option<PrivacyRisk>,
+    #[arg(long)]
+    pub limit: Option<usize>,
+    /// If set, write the raw JSON response to this path.
+    #[arg(long)]
+    pub output: Option<PathBuf>,
+}
+
+// --- value enums ---
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub(crate) enum PrivacyRisk {
+    Low,
+    Medium,
+    High,
+}
+
+impl PrivacyRisk {
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::Low => "low",
+            Self::Medium => "medium",
+            Self::High => "high",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub(crate) enum RetentionJobStatus {
+    Planned,
+    Running,
+    DryRun,
+    Complete,
+    Failed,
+    Paused,
+}
+
+impl RetentionJobStatus {
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::Planned => "planned",
+            Self::Running => "running",
+            Self::DryRun => "dry_run",
+            Self::Complete => "complete",
+            Self::Failed => "failed",
+            Self::Paused => "paused",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub(crate) enum RetentionJobItemAction {
+    Revoke,
+    Expire,
+    Purge,
+}
+
+impl RetentionJobItemAction {
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::Revoke => "revoke",
+            Self::Expire => "expire",
+            Self::Purge => "purge",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub(crate) enum RetentionJobItemStatus {
+    Pending,
+    Done,
+    Failed,
+    Skipped,
+}
+
+impl RetentionJobItemStatus {
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::Pending => "pending",
+            Self::Done => "done",
+            Self::Failed => "failed",
+            Self::Skipped => "skipped",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub(crate) enum ExportAccessGrantStatus {
+    Active,
+    Consumed,
+    Revoked,
+    Expired,
+}
+
+impl ExportAccessGrantStatus {
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::Active => "active",
+            Self::Consumed => "consumed",
+            Self::Revoked => "revoked",
+            Self::Expired => "expired",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub(crate) enum ExportJobStatus {
+    Queued,
+    Running,
+    Complete,
+    Failed,
+    Cancelled,
+    Expired,
+}
+
+impl ExportJobStatus {
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::Queued => "queued",
+            Self::Running => "running",
+            Self::Complete => "complete",
+            Self::Failed => "failed",
+            Self::Cancelled => "cancelled",
+            Self::Expired => "expired",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub(crate) enum ConsentScope {
+    DebuggingEvaluation,
+    BenchmarkOnly,
+    RankingTraining,
+    ModelTraining,
+}
+
+impl ConsentScope {
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::DebuggingEvaluation => "debugging-evaluation",
+            Self::BenchmarkOnly => "benchmark-only",
+            Self::RankingTraining => "ranking-training",
+            Self::ModelTraining => "model-training",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub(crate) enum CorpusStatus {
+    Accepted,
+    Quarantined,
+    Rejected,
+    Revoked,
+    Expired,
+    Purged,
+}
+
+impl CorpusStatus {
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::Accepted => "accepted",
+            Self::Quarantined => "quarantined",
+            Self::Rejected => "rejected",
+            Self::Revoked => "revoked",
+            Self::Expired => "expired",
+            Self::Purged => "purged",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub(crate) enum BenchmarkRegistryStatus {
+    Candidate,
+    Published,
+    Revoked,
+}
+
+impl BenchmarkRegistryStatus {
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::Candidate => "candidate",
+            Self::Published => "published",
+            Self::Revoked => "revoked",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub(crate) enum BenchmarkEvaluationStatus {
+    NotRun,
+    Queued,
+    Running,
+    Passed,
+    Failed,
+    Inconclusive,
+}
+
+impl BenchmarkEvaluationStatus {
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::NotRun => "not_run",
+            Self::Queued => "queued",
+            Self::Running => "running",
+            Self::Passed => "passed",
+            Self::Failed => "failed",
+            Self::Inconclusive => "inconclusive",
+        }
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let cli = Cli::parse();
+    let client = build_client(&cli)?;
+    dispatch(&client, &cli.endpoint, cli.command, cli.json).await
+}
+
+fn build_client(cli: &Cli) -> Result<Client> {
+    let mut builder = Client::builder(&cli.endpoint, &cli.bearer_token_env);
+    if let Some(csv) = cli.allowed_hosts.as_deref() {
+        builder = builder.host_allowlist(HostAllowlist::from_csv(csv));
+    }
+    Ok(builder.build()?)
+}
+
+async fn dispatch(
+    client: &Client,
+    endpoint: &str,
+    cmd: AdminSubcommand,
+    json: bool,
+) -> Result<()> {
+    match cmd {
+        AdminSubcommand::MaintenanceRun(args) => maintenance_run(client, endpoint, args, json).await,
+        AdminSubcommand::RetentionJobsList(args) => {
+            retention_jobs_list(client, endpoint, args, json).await
+        }
+        AdminSubcommand::RetentionJobItems(args) => {
+            retention_job_items(client, endpoint, args, json).await
+        }
+        AdminSubcommand::ExportAccessGrantsList(args) => {
+            export_access_grants_list(client, endpoint, args, json).await
+        }
+        AdminSubcommand::ExportJobsList(args) => {
+            export_jobs_list(client, endpoint, args, json).await
+        }
+        AdminSubcommand::BenchmarkConvert(args) => {
+            benchmark_convert(client, endpoint, args, json).await
+        }
+        AdminSubcommand::BenchmarkLifecycleUpdate(args) => {
+            benchmark_lifecycle_update(client, endpoint, args, json).await
+        }
+        AdminSubcommand::ReplayDatasetExport(args) => {
+            replay_dataset_export(client, endpoint, args, json).await
+        }
+        AdminSubcommand::ReplayExportManifests => {
+            replay_export_manifests(client, endpoint, json).await
+        }
+        AdminSubcommand::AnalyticsSummary => analytics_summary(client, endpoint, json).await,
+        AdminSubcommand::OperationalSummary => operational_summary(client, endpoint, json).await,
+        AdminSubcommand::ConfigStatus => config_status(client, endpoint, json).await,
+    }
+}
+
+async fn maintenance_run(
+    client: &Client,
+    endpoint: &str,
+    args: MaintenanceRunArgs,
+    json: bool,
+) -> Result<()> {
+    let trimmed = args.purpose.trim();
+    if trimmed.is_empty() {
+        anyhow::bail!("--purpose must be non-empty");
+    }
+    let path = "/v1/admin/maintenance";
+    let mut body = serde_json::json!({
+        "purpose": trimmed,
+        "dry_run": args.dry_run,
+    });
+    if args.backfill_db_mirror {
+        body["backfill_db_mirror"] = Value::Bool(true);
+    }
+    if args.index_vectors {
+        body["index_vectors"] = Value::Bool(true);
+    }
+    if args.reconcile_db_mirror {
+        body["reconcile_db_mirror"] = Value::Bool(true);
+    }
+    if args.verify_audit_chain {
+        body["verify_audit_chain"] = Value::Bool(true);
+    }
+    if !args.prune_export_cache {
+        body["prune_export_cache"] = Value::Bool(false);
+    }
+    if let Some(hours) = args.max_export_age_hours {
+        body["max_export_age_hours"] = Value::Number(hours.into());
+    }
+    if let Some(before) = args.purge_expired_before {
+        body["purge_expired_before"] = Value::String(before);
+    }
+    let value: Value = client
+        .call_json::<Value, Value>(Method::POST, path, &[], Some(&body))
+        .await?;
+    if json {
+        emit_json(endpoint, "POST", path, &value)?;
+    } else {
+        let mut out = stdout();
+        writeln!(out, "Trace Commons maintenance run requested.")?;
+        render_kv_fields(
+            &mut out,
+            &value,
+            &[
+                ("  audit event id", "audit_event_id"),
+                ("  purpose", "purpose"),
+                ("  dry run", "dry_run"),
+                ("  revoked submissions", "revoked_submission_count"),
+                ("  expired submissions", "expired_submission_count"),
+                ("  records marked revoked", "records_marked_revoked"),
+                ("  records marked expired", "records_marked_expired"),
+                ("  records marked purged", "records_marked_purged"),
+                ("  derived marked revoked", "derived_marked_revoked"),
+                ("  derived marked expired", "derived_marked_expired"),
+                ("  export cache files pruned", "export_cache_files_pruned"),
+                ("  export provenance invalidated", "export_provenance_invalidated"),
+                ("  benchmark artifacts invalidated", "benchmark_artifacts_invalidated"),
+                ("  trace object files deleted", "trace_object_files_deleted"),
+                ("  encrypted artifacts deleted", "encrypted_artifacts_deleted"),
+                ("  DB mirror backfilled", "db_mirror_backfilled"),
+                ("  vectors indexed", "vector_entries_indexed"),
+            ],
+        )?;
+    }
+    Ok(())
+}
+
+async fn retention_jobs_list(
+    client: &Client,
+    endpoint: &str,
+    args: RetentionJobsListArgs,
+    json: bool,
+) -> Result<()> {
+    let path = "/v1/admin/retention/jobs";
+    let mut owned: Vec<(&str, String)> = Vec::new();
+    if let Some(limit) = args.limit {
+        owned.push(("limit", limit.to_string()));
+    }
+    if let Some(status) = args.status {
+        owned.push(("status", status.as_str().to_string()));
+    }
+    let query = borrow_query(&owned);
+    let value: Value = client.call_json::<(), Value>(Method::GET, path, &query, None).await?;
+    if json {
+        emit_json(endpoint, "GET", path, &value)?;
+    } else {
+        render_items(
+            &mut stdout(),
+            "Central retention maintenance jobs",
+            &value,
+            &[
+                "retention_job_id",
+                "status",
+                "purpose",
+                "dry_run",
+                "selected_revoked_count",
+                "selected_expired_count",
+                "started_at",
+                "completed_at",
+                "created_at",
+            ],
+        )?;
+    }
+    Ok(())
+}
+
+async fn retention_job_items(
+    client: &Client,
+    endpoint: &str,
+    args: RetentionJobItemsArgs,
+    json: bool,
+) -> Result<()> {
+    let path = format!("/v1/admin/retention/jobs/{}/items", args.retention_job_id);
+    let mut owned: Vec<(&str, String)> = Vec::new();
+    if let Some(limit) = args.limit {
+        owned.push(("limit", limit.to_string()));
+    }
+    if let Some(action) = args.action {
+        owned.push(("action", action.as_str().to_string()));
+    }
+    if let Some(status) = args.status {
+        owned.push(("status", status.as_str().to_string()));
+    }
+    let query = borrow_query(&owned);
+    let value: Value = client.call_json::<(), Value>(Method::GET, &path, &query, None).await?;
+    if json {
+        emit_json(endpoint, "GET", &path, &value)?;
+    } else {
+        render_items(
+            &mut stdout(),
+            "Central retention maintenance job items",
+            &value,
+            &[
+                "submission_id",
+                "action",
+                "status",
+                "reason",
+                "verified_at",
+                "updated_at",
+            ],
+        )?;
+    }
+    Ok(())
+}
+
+async fn export_access_grants_list(
+    client: &Client,
+    endpoint: &str,
+    args: ExportAccessGrantsListArgs,
+    json: bool,
+) -> Result<()> {
+    let path = "/v1/admin/export/access-grants";
+    let mut owned: Vec<(&str, String)> = Vec::new();
+    if let Some(limit) = args.limit {
+        owned.push(("limit", limit.to_string()));
+    }
+    if let Some(status) = args.status {
+        owned.push(("status", status.as_str().to_string()));
+    }
+    if let Some(kind) = args.dataset_kind {
+        owned.push(("dataset_kind", kind));
+    }
+    let query = borrow_query(&owned);
+    let value: Value = client.call_json::<(), Value>(Method::GET, path, &query, None).await?;
+    if json {
+        emit_json(endpoint, "GET", path, &value)?;
+    } else {
+        render_items(
+            &mut stdout(),
+            "Central export access grants",
+            &value,
+            &[
+                "grant_id",
+                "export_job_id",
+                "status",
+                "requested_dataset_kind",
+                "purpose",
+                "max_item_cap",
+                "requested_at",
+                "expires_at",
+            ],
+        )?;
+    }
+    Ok(())
+}
+
+async fn export_jobs_list(
+    client: &Client,
+    endpoint: &str,
+    args: ExportJobsListArgs,
+    json: bool,
+) -> Result<()> {
+    let path = "/v1/admin/export/jobs";
+    let mut owned: Vec<(&str, String)> = Vec::new();
+    if let Some(limit) = args.limit {
+        owned.push(("limit", limit.to_string()));
+    }
+    if let Some(status) = args.status {
+        owned.push(("status", status.as_str().to_string()));
+    }
+    if let Some(kind) = args.dataset_kind {
+        owned.push(("dataset_kind", kind));
+    }
+    let query = borrow_query(&owned);
+    let value: Value = client.call_json::<(), Value>(Method::GET, path, &query, None).await?;
+    if json {
+        emit_json(endpoint, "GET", path, &value)?;
+    } else {
+        render_items(
+            &mut stdout(),
+            "Central export jobs",
+            &value,
+            &[
+                "export_job_id",
+                "status",
+                "requested_dataset_kind",
+                "purpose",
+                "item_count",
+                "result_manifest_id",
+                "started_at",
+                "finished_at",
+            ],
+        )?;
+    }
+    Ok(())
+}
+
+async fn benchmark_convert(
+    client: &Client,
+    endpoint: &str,
+    args: BenchmarkConvertArgs,
+    json: bool,
+) -> Result<()> {
+    let trimmed = args.purpose.trim();
+    if trimmed.is_empty() {
+        anyhow::bail!("--purpose must be non-empty");
+    }
+    let path = "/v1/benchmarks/convert";
+    let mut body = serde_json::json!({ "purpose": trimmed });
+    if let Some(limit) = args.limit {
+        body["limit"] = serde_json::json!(limit);
+    }
+    if let Some(scope) = args.consent_scope {
+        body["consent_scope"] = Value::String(scope.as_str().to_string());
+    }
+    if let Some(status) = args.status {
+        body["status"] = Value::String(status.as_str().to_string());
+    }
+    if let Some(risk) = args.privacy_risk {
+        body["privacy_risk"] = Value::String(risk.as_str().to_string());
+    }
+    if let Some(external_ref) = args.external_ref {
+        body["external_ref"] = Value::String(external_ref);
+    }
+    let value: Value = client
+        .call_json::<Value, Value>(Method::POST, path, &[], Some(&body))
+        .await?;
+    if json {
+        emit_json(endpoint, "POST", path, &value)?;
+    } else {
+        let mut out = stdout();
+        writeln!(out, "Trace Commons benchmark conversion requested.")?;
+        render_kv_fields(
+            &mut out,
+            &value,
+            &[
+                ("  conversion id", "conversion_id"),
+                ("  audit event id", "audit_event_id"),
+                ("  item count", "item_count"),
+                ("  purpose", "purpose"),
+            ],
+        )?;
+    }
+    Ok(())
+}
+
+async fn benchmark_lifecycle_update(
+    client: &Client,
+    endpoint: &str,
+    args: BenchmarkLifecycleArgs,
+    json: bool,
+) -> Result<()> {
+    if let Some(score) = args.score {
+        if !(0.0..=1.0).contains(&score) {
+            anyhow::bail!("--score must be between 0.0 and 1.0");
+        }
+    }
+    let mut body = serde_json::Map::new();
+    let mut registry = serde_json::Map::new();
+    if let Some(status) = args.registry_status {
+        registry.insert("status".into(), Value::String(status.as_str().to_string()));
+    }
+    if let Some(rref) = args.registry_ref {
+        registry.insert("registry_ref".into(), Value::String(rref));
+    }
+    if let Some(at) = args.published_at {
+        registry.insert("published_at".into(), Value::String(at));
+    }
+    if !registry.is_empty() {
+        body.insert("registry".into(), Value::Object(registry));
+    }
+    let mut evaluation = serde_json::Map::new();
+    if let Some(status) = args.evaluation_status {
+        evaluation.insert("status".into(), Value::String(status.as_str().to_string()));
+    }
+    if let Some(eref) = args.evaluator_ref {
+        evaluation.insert("evaluator_ref".into(), Value::String(eref));
+    }
+    if let Some(at) = args.evaluated_at {
+        evaluation.insert("evaluated_at".into(), Value::String(at));
+    }
+    if let Some(score) = args.score {
+        evaluation.insert("score".into(), serde_json::json!(score));
+    }
+    if let Some(pc) = args.pass_count {
+        evaluation.insert("pass_count".into(), serde_json::json!(pc));
+    }
+    if let Some(fc) = args.fail_count {
+        evaluation.insert("fail_count".into(), serde_json::json!(fc));
+    }
+    if !evaluation.is_empty() {
+        body.insert("evaluation".into(), Value::Object(evaluation));
+    }
+    if body.is_empty() {
+        anyhow::bail!("benchmark lifecycle update requires at least one registry or evaluation field");
+    }
+    if let Some(reason) = args.reason {
+        body.insert("reason".into(), Value::String(reason));
+    }
+    let body = Value::Object(body);
+    let path = format!("/v1/benchmarks/{}/lifecycle", args.conversion_id);
+    let value: Value = client
+        .call_json::<Value, Value>(Method::POST, &path, &[], Some(&body))
+        .await?;
+    if json {
+        emit_json(endpoint, "POST", &path, &value)?;
+    } else {
+        let mut out = stdout();
+        writeln!(out, "Trace Commons benchmark lifecycle updated.")?;
+        render_kv_fields(
+            &mut out,
+            &value,
+            &[
+                ("  conversion id", "conversion_id"),
+                ("  purpose", "purpose"),
+            ],
+        )?;
+        if let Some(registry) = value.get("registry") {
+            render_kv_fields(
+                &mut out,
+                registry,
+                &[
+                    ("  registry status", "status"),
+                    ("  registry ref", "registry_ref"),
+                ],
+            )?;
+        }
+        if let Some(evaluation) = value.get("evaluation") {
+            render_kv_fields(
+                &mut out,
+                evaluation,
+                &[
+                    ("  evaluation status", "status"),
+                    ("  evaluator ref", "evaluator_ref"),
+                    ("  score", "score"),
+                ],
+            )?;
+        }
+    }
+    Ok(())
+}
+
+async fn replay_dataset_export(
+    client: &Client,
+    endpoint: &str,
+    args: ReplayDatasetExportArgs,
+    json: bool,
+) -> Result<()> {
+    let path = "/v1/datasets/replay";
+    let mut owned: Vec<(&str, String)> = Vec::new();
+    if let Some(limit) = args.limit {
+        owned.push(("limit", limit.to_string()));
+    }
+    if let Some(purpose) = args.purpose {
+        let trimmed = purpose.trim();
+        if trimmed.is_empty() {
+            anyhow::bail!("--purpose must be non-empty");
+        }
+        owned.push(("purpose", trimmed.to_string()));
+    }
+    if let Some(scope) = args.consent_scope {
+        owned.push(("consent_scope", scope.as_str().to_string()));
+    }
+    if let Some(status) = args.status {
+        owned.push(("status", status.as_str().to_string()));
+    }
+    if let Some(risk) = args.privacy_risk {
+        owned.push(("privacy_risk", risk.as_str().to_string()));
+    }
+    let query = borrow_query(&owned);
+    let raw = client
+        .call_raw::<()>(Method::GET, path, &query, None)
+        .await?;
+    let value: Value = serde_json::from_str(&raw).unwrap_or(Value::Null);
+
+    if let Some(output) = args.output.as_ref() {
+        let pretty = if value.is_null() {
+            raw.clone()
+        } else {
+            serde_json::to_string_pretty(&value)?
+        };
+        std::fs::write(output, pretty).map_err(|e| {
+            anyhow::anyhow!(
+                "failed to write replay dataset export {}: {}",
+                output.display(),
+                e
+            )
+        })?;
+        if json {
+            emit_json(endpoint, "GET", path, &value)?;
+        } else {
+            let mut out = stdout();
+            writeln!(
+                out,
+                "Wrote central replay dataset export to {}",
+                output.display()
+            )?;
+            render_kv_fields(
+                &mut out,
+                &value,
+                &[
+                    ("  export id", "export_id"),
+                    ("  manifest id", "manifest_id"),
+                    ("  audit event id", "audit_event_id"),
+                    ("  item count", "item_count"),
+                ],
+            )?;
+        }
+        return Ok(());
+    }
+
+    emit_json(endpoint, "GET", path, &value)
+}
+
+async fn replay_export_manifests(client: &Client, endpoint: &str, json: bool) -> Result<()> {
+    let path = "/v1/datasets/replay/manifests";
+    let value: Value = client.call_json::<(), Value>(Method::GET, path, &[], None).await?;
+    if json {
+        emit_json(endpoint, "GET", path, &value)?;
+    } else {
+        render_items(
+            &mut stdout(),
+            "Central replay export manifests",
+            &value,
+            &[
+                "export_manifest_id",
+                "purpose_code",
+                "item_count",
+                "source_submission_ids_hash",
+                "generated_at",
+                "invalidated_at",
+            ],
+        )?;
+    }
+    Ok(())
+}
+
+async fn analytics_summary(client: &Client, endpoint: &str, json: bool) -> Result<()> {
+    let path = "/v1/analytics/summary";
+    let value: Value = client.call_json::<(), Value>(Method::GET, path, &[], None).await?;
+    if json {
+        emit_json(endpoint, "GET", path, &value)?;
+    } else {
+        let mut out = stdout();
+        writeln!(out, "Trace Commons analytics summary:")?;
+        render_kv_fields(
+            &mut out,
+            &value,
+            &[
+                ("  tenant", "tenant_id"),
+                ("  submissions", "submissions_total"),
+                ("  min cell count", "min_cell_count"),
+                ("  suppressed cells", "suppressed_cell_count"),
+                ("  duplicate groups", "duplicate_groups"),
+                ("  average novelty", "average_novelty_score"),
+            ],
+        )?;
+        render_json_map(&mut out, "  by status", value.get("by_status"))?;
+        render_json_map(&mut out, "  by privacy risk", value.get("by_privacy_risk"))?;
+        render_json_map(&mut out, "  by task success", value.get("by_task_success"))?;
+        if let Some(pe) = value.get("process_evaluation") {
+            render_kv_fields(
+                &mut out,
+                pe,
+                &[("  process evaluated traces", "evaluated_traces")],
+            )?;
+            render_json_map(&mut out, "  process labels", pe.get("by_label"))?;
+            render_json_map(&mut out, "  process ratings", pe.get("by_rating"))?;
+            render_json_map(&mut out, "  process score bands", pe.get("by_score_band"))?;
+        }
+    }
+    Ok(())
+}
+
+async fn operational_summary(client: &Client, endpoint: &str, json: bool) -> Result<()> {
+    let path = "/v1/admin/operational-summary";
+    let value: Value = client.call_json::<(), Value>(Method::GET, path, &[], None).await?;
+    if json {
+        emit_json(endpoint, "GET", path, &value)?;
+    } else {
+        let mut out = stdout();
+        writeln!(out, "Trace Commons operational summary:")?;
+        render_kv_fields(
+            &mut out,
+            &value,
+            &[
+                ("  tenant", "tenant_id"),
+                ("  tenant storage ref", "tenant_storage_ref"),
+                ("  generated at", "generated_at"),
+            ],
+        )?;
+        render_subsection(&mut out, "  submissions", value.get("submissions"))?;
+        render_subsection(&mut out, "  review sla", value.get("review_sla"))?;
+        render_subsection(
+            &mut out,
+            "  export",
+            value.get("exports").or_else(|| value.get("export")),
+        )?;
+        render_subsection(&mut out, "  retention", value.get("retention"))?;
+        render_subsection(&mut out, "  vectors", value.get("vectors"))?;
+        render_subsection(&mut out, "  delayed credit", value.get("delayed_credit"))?;
+        render_subsection(&mut out, "  promotion gates", value.get("promotion_gates"))?;
+    }
+    Ok(())
+}
+
+async fn config_status(client: &Client, endpoint: &str, _json: bool) -> Result<()> {
+    let path = "/v1/admin/config-status";
+    let value: Value = client.call_json::<(), Value>(Method::GET, path, &[], None).await?;
+    emit_json(endpoint, "GET", path, &value)
+}
+
+// --- helpers ---
+
+fn borrow_query<'a>(owned: &'a [(&'a str, String)]) -> Vec<(&'a str, &'a str)> {
+    owned.iter().map(|(k, v)| (*k, v.as_str())).collect()
+}
+
+/// Render a subsection of the operational summary as a list of `field = value`
+/// scalar lines plus any nested maps rendered via [`render_json_map`].
+fn render_subsection<W: Write>(
+    out: &mut W,
+    heading: &str,
+    value: Option<&Value>,
+) -> std::io::Result<()> {
+    let Some(obj) = value.and_then(Value::as_object) else {
+        return Ok(());
+    };
+    if obj.is_empty() {
+        return Ok(());
+    }
+    writeln!(out, "{heading}:")?;
+    for (k, v) in obj {
+        if v.is_object() {
+            render_json_map(out, &format!("    {k}"), Some(v))?;
+        } else if let Some(arr) = v.as_array() {
+            let items: Vec<String> = arr
+                .iter()
+                .filter_map(|v| {
+                    v.as_str()
+                        .map(ToString::to_string)
+                        .or_else(|| v.as_i64().map(|n| n.to_string()))
+                        .or_else(|| v.as_u64().map(|n| n.to_string()))
+                        .or_else(|| v.as_bool().map(|b| b.to_string()))
+                })
+                .collect();
+            if !items.is_empty() {
+                writeln!(out, "    {k}: {}", items.join(" "))?;
+            }
+        } else if !v.is_null() {
+            let s = match v {
+                Value::String(s) => s.clone(),
+                other => other.to_string(),
+            };
+            writeln!(out, "    {k}: {s}")?;
+        }
+    }
+    Ok(())
+}
+
+fn emit_json(endpoint: &str, method: &str, path: &str, value: &Value) -> Result<()> {
+    let url = sanitized_url(endpoint, path);
+    oc_format::emit_json(&mut stdout(), method, &url, value)?;
+    Ok(())
+}
+
+// --- tests ---
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::atomic::{AtomicU64, Ordering};
+    use wiremock::matchers::{body_json, header, method, path, query_param};
+    use wiremock::{Mock, MockServer, ResponseTemplate};
+
+    fn unique_bearer_env() -> String {
+        static SEQ: AtomicU64 = AtomicU64::new(0);
+        let n = SEQ.fetch_add(1, Ordering::Relaxed);
+        format!("TC_ADMIN_TEST_BEARER_{n}")
+    }
+
+    struct EnvGuard {
+        name: String,
+    }
+    impl EnvGuard {
+        fn set(name: String, value: &str) -> Self {
+            unsafe { std::env::set_var(&name, value) };
+            EnvGuard { name }
+        }
+    }
+    impl Drop for EnvGuard {
+        fn drop(&mut self) {
+            unsafe { std::env::remove_var(&self.name) };
+        }
+    }
+
+    #[test]
+    fn cli_parses_analytics_summary() {
+        let cli = Cli::try_parse_from([
+            "trace-commons-admin",
+            "--endpoint",
+            "https://api.example",
+            "analytics-summary",
+        ])
+        .unwrap();
+        assert!(matches!(cli.command, AdminSubcommand::AnalyticsSummary));
+    }
+
+    #[test]
+    fn cli_parses_operational_summary() {
+        Cli::try_parse_from([
+            "trace-commons-admin",
+            "--endpoint",
+            "https://api.example",
+            "operational-summary",
+        ])
+        .unwrap();
+    }
+
+    #[test]
+    fn cli_parses_config_status() {
+        Cli::try_parse_from([
+            "trace-commons-admin",
+            "--endpoint",
+            "https://api.example",
+            "config-status",
+        ])
+        .unwrap();
+    }
+
+    #[test]
+    fn cli_parses_maintenance_run_full() {
+        let cli = Cli::try_parse_from([
+            "trace-commons-admin",
+            "--endpoint",
+            "https://api.example",
+            "maintenance-run",
+            "--purpose",
+            "monthly retention",
+            "--dry-run",
+            "--backfill-db-mirror",
+            "--index-vectors",
+            "--reconcile-db-mirror",
+            "--verify-audit-chain",
+            "--max-export-age-hours",
+            "48",
+        ])
+        .unwrap();
+        match cli.command {
+            AdminSubcommand::MaintenanceRun(args) => {
+                assert_eq!(args.purpose, "monthly retention");
+                assert!(args.dry_run);
+                assert!(args.backfill_db_mirror);
+                assert!(args.index_vectors);
+                assert!(args.reconcile_db_mirror);
+                assert!(args.verify_audit_chain);
+                assert_eq!(args.max_export_age_hours, Some(48));
+            }
+            other => panic!("unexpected variant: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn cli_parses_retention_jobs_list() {
+        Cli::try_parse_from([
+            "trace-commons-admin",
+            "--endpoint",
+            "https://api.example",
+            "retention-jobs-list",
+            "--limit",
+            "10",
+            "--status",
+            "running",
+        ])
+        .unwrap();
+    }
+
+    #[test]
+    fn cli_parses_retention_job_items() {
+        let id = Uuid::new_v4();
+        Cli::try_parse_from([
+            "trace-commons-admin",
+            "--endpoint",
+            "https://api.example",
+            "retention-job-items",
+            "--retention-job-id",
+            &id.to_string(),
+            "--action",
+            "purge",
+            "--status",
+            "done",
+        ])
+        .unwrap();
+    }
+
+    #[test]
+    fn cli_parses_export_access_grants_list() {
+        Cli::try_parse_from([
+            "trace-commons-admin",
+            "--endpoint",
+            "https://api.example",
+            "export-access-grants-list",
+            "--status",
+            "active",
+            "--dataset-kind",
+            "ranking",
+        ])
+        .unwrap();
+    }
+
+    #[test]
+    fn cli_parses_export_jobs_list() {
+        Cli::try_parse_from([
+            "trace-commons-admin",
+            "--endpoint",
+            "https://api.example",
+            "export-jobs-list",
+            "--status",
+            "complete",
+        ])
+        .unwrap();
+    }
+
+    #[test]
+    fn cli_parses_benchmark_convert() {
+        Cli::try_parse_from([
+            "trace-commons-admin",
+            "--endpoint",
+            "https://api.example",
+            "benchmark-convert",
+            "--purpose",
+            "weekly",
+            "--limit",
+            "50",
+            "--consent-scope",
+            "benchmark-only",
+            "--status",
+            "accepted",
+            "--privacy-risk",
+            "low",
+        ])
+        .unwrap();
+    }
+
+    #[test]
+    fn cli_parses_benchmark_lifecycle_update() {
+        let id = Uuid::new_v4();
+        Cli::try_parse_from([
+            "trace-commons-admin",
+            "--endpoint",
+            "https://api.example",
+            "benchmark-lifecycle-update",
+            "--conversion-id",
+            &id.to_string(),
+            "--registry-status",
+            "published",
+            "--evaluation-status",
+            "passed",
+            "--score",
+            "0.85",
+        ])
+        .unwrap();
+    }
+
+    #[test]
+    fn cli_parses_replay_dataset_export() {
+        Cli::try_parse_from([
+            "trace-commons-admin",
+            "--endpoint",
+            "https://api.example",
+            "replay-dataset-export",
+            "--purpose",
+            "ranking",
+            "--consent-scope",
+            "ranking-training",
+            "--status",
+            "accepted",
+            "--privacy-risk",
+            "medium",
+            "--limit",
+            "100",
+        ])
+        .unwrap();
+    }
+
+    #[test]
+    fn cli_parses_replay_export_manifests() {
+        Cli::try_parse_from([
+            "trace-commons-admin",
+            "--endpoint",
+            "https://api.example",
+            "replay-export-manifests",
+        ])
+        .unwrap();
+    }
+
+    #[test]
+    fn cli_rejects_unknown_subcommand() {
+        let err = Cli::try_parse_from([
+            "trace-commons-admin",
+            "--endpoint",
+            "https://api.example",
+            "bogus-subcommand",
+        ])
+        .unwrap_err();
+        assert!(!err.to_string().is_empty());
+    }
+
+    #[test]
+    fn cli_rejects_maintenance_run_missing_purpose() {
+        let err = Cli::try_parse_from([
+            "trace-commons-admin",
+            "--endpoint",
+            "https://api.example",
+            "maintenance-run",
+        ])
+        .unwrap_err();
+        assert!(!err.to_string().is_empty());
+    }
+
+    #[test]
+    fn cli_rejects_benchmark_lifecycle_bad_score() {
+        // The lifecycle args themselves accept any f32; the > 1.0 check is at
+        // runtime. So this only verifies the parser is wired.
+        let id = Uuid::new_v4();
+        Cli::try_parse_from([
+            "trace-commons-admin",
+            "--endpoint",
+            "https://api.example",
+            "benchmark-lifecycle-update",
+            "--conversion-id",
+            &id.to_string(),
+            "--score",
+            "2.0",
+        ])
+        .unwrap();
+    }
+
+    #[tokio::test]
+    async fn analytics_summary_happy_path() {
+        let server = MockServer::start().await;
+        Mock::given(method("GET"))
+            .and(path("/v1/analytics/summary"))
+            .and(header("authorization", "Bearer admin-secret"))
+            .respond_with(
+                ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                    "tenant_id": "tenant-1",
+                    "submissions_total": 42,
+                    "by_status": {"accepted": 30, "rejected": 12},
+                })),
+            )
+            .expect(1)
+            .mount(&server)
+            .await;
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "admin-secret");
+        let client = Client::builder(server.uri(), env).build().unwrap();
+        analytics_summary(&client, &server.uri(), true).await.unwrap();
+    }
+
+    #[tokio::test]
+    async fn benchmark_convert_posts_expected_body() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/v1/benchmarks/convert"))
+            .and(body_json(serde_json::json!({
+                "purpose": "weekly",
+                "limit": 50,
+            })))
+            .respond_with(
+                ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                    "conversion_id": "conv-1",
+                    "item_count": 5,
+                })),
+            )
+            .expect(1)
+            .mount(&server)
+            .await;
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "admin-secret");
+        let client = Client::builder(server.uri(), env).build().unwrap();
+        benchmark_convert(
+            &client,
+            &server.uri(),
+            BenchmarkConvertArgs {
+                purpose: "weekly".into(),
+                limit: Some(50),
+                consent_scope: None,
+                status: None,
+                privacy_risk: None,
+                external_ref: None,
+            },
+            true,
+        )
+        .await
+        .unwrap();
+    }
+
+    #[tokio::test]
+    async fn retention_jobs_list_attaches_query_params() {
+        let server = MockServer::start().await;
+        Mock::given(method("GET"))
+            .and(path("/v1/admin/retention/jobs"))
+            .and(query_param("limit", "5"))
+            .and(query_param("status", "running"))
+            .respond_with(
+                ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                    "items": []
+                })),
+            )
+            .expect(1)
+            .mount(&server)
+            .await;
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "admin-secret");
+        let client = Client::builder(server.uri(), env).build().unwrap();
+        retention_jobs_list(
+            &client,
+            &server.uri(),
+            RetentionJobsListArgs {
+                limit: Some(5),
+                status: Some(RetentionJobStatus::Running),
+            },
+            true,
+        )
+        .await
+        .unwrap();
+    }
+
+    #[tokio::test]
+    async fn benchmark_lifecycle_update_rejects_out_of_range_score() {
+        let server = MockServer::start().await;
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "secret");
+        let client = Client::builder(server.uri(), env).build().unwrap();
+        let err = benchmark_lifecycle_update(
+            &client,
+            &server.uri(),
+            BenchmarkLifecycleArgs {
+                conversion_id: Uuid::new_v4(),
+                registry_status: None,
+                registry_ref: None,
+                published_at: None,
+                evaluation_status: None,
+                evaluator_ref: None,
+                evaluated_at: None,
+                score: Some(2.0),
+                pass_count: None,
+                fail_count: None,
+                reason: None,
+            },
+            true,
+        )
+        .await
+        .unwrap_err();
+        assert!(err.to_string().contains("score"));
+    }
+
+    #[tokio::test]
+    async fn benchmark_lifecycle_update_rejects_empty_body() {
+        let server = MockServer::start().await;
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "secret");
+        let client = Client::builder(server.uri(), env).build().unwrap();
+        let err = benchmark_lifecycle_update(
+            &client,
+            &server.uri(),
+            BenchmarkLifecycleArgs {
+                conversion_id: Uuid::new_v4(),
+                registry_status: None,
+                registry_ref: None,
+                published_at: None,
+                evaluation_status: None,
+                evaluator_ref: None,
+                evaluated_at: None,
+                score: None,
+                pass_count: None,
+                fail_count: None,
+                reason: None,
+            },
+            true,
+        )
+        .await
+        .unwrap_err();
+        assert!(err
+            .to_string()
+            .contains("registry or evaluation"));
+    }
+}
diff --git a/crates/trace-commons-server/src/bin/trace-commons-review.rs b/crates/trace-commons-server/src/bin/trace-commons-review.rs
new file mode 100644
index 000000000..6ebcc4f42
--- /dev/null
+++ b/crates/trace-commons-server/src/bin/trace-commons-review.rs
@@ -0,0 +1,897 @@
+//! `trace-commons-review` — reviewer-audience operator CLI.
+//!
+//! Eight subcommands matching the reviewer-bearer endpoints on
+//! trace-commons-server. All requests are issued through the foundation
+//! `trace_commons_operator_client::Client`, which enforces the host
+//! allowlist and never logs bearer tokens or query strings.
+
+#[path = "operator_common/mod.rs"]
+mod operator_common;
+
+use std::io::{stdout, Write};
+
+use anyhow::Result;
+use clap::{Parser, Subcommand, ValueEnum};
+use reqwest::Method;
+use serde_json::Value;
+use trace_commons_operator_client::{format as oc_format, Client, host_allowlist::HostAllowlist};
+use uuid::Uuid;
+
+use operator_common::{render_items, render_kv_fields, sanitized_url};
+
+const DEFAULT_BEARER_ENV: &str = "TRACE_COMMONS_REVIEWER_BEARER";
+
+#[derive(Debug, Parser)]
+#[command(
+    name = "trace-commons-review",
+    about = "Reviewer-audience CLI for trace-commons-server.",
+    version
+)]
+pub(crate) struct Cli {
+    /// Hosted endpoint. Reads `TRACE_COMMONS_ENDPOINT` when unset on the CLI.
+    #[arg(long, env = "TRACE_COMMONS_ENDPOINT")]
+    pub endpoint: String,
+
+    /// Name of the env var holding the reviewer bearer token.
+    #[arg(long, default_value = DEFAULT_BEARER_ENV)]
+    pub bearer_token_env: String,
+
+    /// Defense-in-depth host allowlist (CSV). Empty means permissive.
+    #[arg(long, env = "TRACE_COMMONS_ALLOWED_HOSTS")]
+    pub allowed_hosts: Option<String>,
+
+    /// Emit the server response as JSON (with a sanitized request envelope).
+    #[arg(long, global = true)]
+    pub json: bool,
+
+    #[command(subcommand)]
+    pub command: ReviewSubcommand,
+}
+
+#[derive(Debug, Subcommand)]
+pub(crate) enum ReviewSubcommand {
+    /// List quarantined submissions.
+    QuarantineList(QuarantineListArgs),
+    /// List the active-learning review queue (404-tolerant).
+    ActiveLearningReviewQueue(ActiveLearningArgs),
+    /// Record an approve/reject decision for a submission.
+    ReviewDecision(ReviewDecisionArgs),
+    /// Claim the review lease for a specific submission.
+    ReviewLeaseClaim(LeaseClaimArgs),
+    /// Claim the next available review lease.
+    ReviewLeaseClaimNext(LeaseClaimNextArgs),
+    /// Claim up to `limit` review leases atomically.
+    ReviewLeaseClaimBatch(LeaseClaimBatchArgs),
+    /// Release the review lease for a submission.
+    ReviewLeaseRelease(LeaseReleaseArgs),
+    /// Append a delayed credit event for a submission.
+    AppendCreditEvent(AppendCreditEventArgs),
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct QuarantineListArgs {
+    #[arg(long, value_enum)]
+    pub lease_filter: Option<ReviewLeaseFilter>,
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct ActiveLearningArgs {
+    #[arg(long)]
+    pub limit: Option<usize>,
+    #[arg(long, value_enum)]
+    pub privacy_risk: Option<PrivacyRisk>,
+    #[arg(long, value_enum)]
+    pub lease_filter: Option<ReviewLeaseFilter>,
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct ReviewDecisionArgs {
+    #[arg(long)]
+    pub submission_id: Uuid,
+    #[arg(long, value_enum)]
+    pub decision: ReviewDecision,
+    #[arg(long)]
+    pub reason: Option<String>,
+    #[arg(long)]
+    pub credit_points_pending: Option<f32>,
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct LeaseClaimArgs {
+    #[arg(long)]
+    pub submission_id: Uuid,
+    #[arg(long)]
+    pub lease_ttl_seconds: Option<i64>,
+    #[arg(long)]
+    pub review_due_at: Option<String>,
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct LeaseClaimNextArgs {
+    #[arg(long)]
+    pub lease_ttl_seconds: Option<i64>,
+    #[arg(long)]
+    pub review_due_at: Option<String>,
+    #[arg(long, value_enum)]
+    pub privacy_risk: Option<PrivacyRisk>,
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct LeaseClaimBatchArgs {
+    #[arg(long)]
+    pub limit: Option<usize>,
+    #[arg(long)]
+    pub lease_ttl_seconds: Option<i64>,
+    #[arg(long)]
+    pub review_due_at: Option<String>,
+    #[arg(long, value_enum)]
+    pub privacy_risk: Option<PrivacyRisk>,
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct LeaseReleaseArgs {
+    #[arg(long)]
+    pub submission_id: Uuid,
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct AppendCreditEventArgs {
+    #[arg(long)]
+    pub submission_id: Uuid,
+    #[arg(long, value_enum)]
+    pub event_type: CreditEventType,
+    #[arg(long)]
+    pub credit_points_delta: f32,
+    #[arg(long)]
+    pub reason: String,
+    #[arg(long)]
+    pub external_ref: Option<String>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub(crate) enum ReviewLeaseFilter {
+    All,
+    Mine,
+    Available,
+    Active,
+    Expired,
+}
+
+impl ReviewLeaseFilter {
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::All => "all",
+            Self::Mine => "mine",
+            Self::Available => "available",
+            Self::Active => "active",
+            Self::Expired => "expired",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub(crate) enum PrivacyRisk {
+    Low,
+    Medium,
+    High,
+}
+
+impl PrivacyRisk {
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::Low => "low",
+            Self::Medium => "medium",
+            Self::High => "high",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub(crate) enum ReviewDecision {
+    Approve,
+    Reject,
+}
+
+impl ReviewDecision {
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::Approve => "approve",
+            Self::Reject => "reject",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub(crate) enum CreditEventType {
+    BenchmarkConversion,
+    RegressionCatch,
+    TrainingUtility,
+    RankingUtility,
+    ReviewerBonus,
+    AbusePenalty,
+}
+
+impl CreditEventType {
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::BenchmarkConversion => "benchmark_conversion",
+            Self::RegressionCatch => "regression_catch",
+            Self::TrainingUtility => "training_utility",
+            Self::RankingUtility => "ranking_utility",
+            Self::ReviewerBonus => "reviewer_bonus",
+            Self::AbusePenalty => "abuse_penalty",
+        }
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let cli = Cli::parse();
+    let client = build_client(&cli)?;
+    dispatch(&client, &cli.endpoint, cli.command, cli.json).await
+}
+
+fn build_client(cli: &Cli) -> Result<Client> {
+    let mut builder = Client::builder(&cli.endpoint, &cli.bearer_token_env);
+    if let Some(csv) = cli.allowed_hosts.as_deref() {
+        builder = builder.host_allowlist(HostAllowlist::from_csv(csv));
+    }
+    Ok(builder.build()?)
+}
+
+async fn dispatch(
+    client: &Client,
+    endpoint: &str,
+    cmd: ReviewSubcommand,
+    json: bool,
+) -> Result<()> {
+    match cmd {
+        ReviewSubcommand::QuarantineList(args) => quarantine_list(client, endpoint, args, json).await,
+        ReviewSubcommand::ActiveLearningReviewQueue(args) => {
+            active_learning(client, endpoint, args, json).await
+        }
+        ReviewSubcommand::ReviewDecision(args) => review_decision(client, endpoint, args, json).await,
+        ReviewSubcommand::ReviewLeaseClaim(args) => lease_claim(client, endpoint, args, json).await,
+        ReviewSubcommand::ReviewLeaseClaimNext(args) => {
+            lease_claim_next(client, endpoint, args, json).await
+        }
+        ReviewSubcommand::ReviewLeaseClaimBatch(args) => {
+            lease_claim_batch(client, endpoint, args, json).await
+        }
+        ReviewSubcommand::ReviewLeaseRelease(args) => {
+            lease_release(client, endpoint, args, json).await
+        }
+        ReviewSubcommand::AppendCreditEvent(args) => {
+            append_credit_event(client, endpoint, args, json).await
+        }
+    }
+}
+
+async fn quarantine_list(
+    client: &Client,
+    endpoint: &str,
+    args: QuarantineListArgs,
+    json: bool,
+) -> Result<()> {
+    let path = "/v1/review/quarantine";
+    let mut owned: Vec<(&str, String)> = Vec::new();
+    if let Some(filter) = args.lease_filter {
+        owned.push(("lease_filter", filter.as_str().to_string()));
+    }
+    let query = borrow_query(&owned);
+    let value: Value = client.call_json::<(), Value>(Method::GET, path, &query, None).await?;
+    if json {
+        emit_json(endpoint, "GET", path, &value)?;
+    } else {
+        render_items(
+            &mut stdout(),
+            "Central quarantined traces",
+            &value,
+            &[
+                "submission_id",
+                "privacy_risk",
+                "submission_score",
+                "review_escalation_state",
+                "review_age_hours",
+                "review_escalation_reasons",
+                "review_assigned_to_principal_ref",
+                "review_lease_expires_at",
+                "review_due_at",
+                "received_at",
+                "canonical_summary",
+            ],
+        )?;
+    }
+    Ok(())
+}
+
+async fn active_learning(
+    client: &Client,
+    endpoint: &str,
+    args: ActiveLearningArgs,
+    json: bool,
+) -> Result<()> {
+    let path = "/v1/review/active-learning";
+    let mut owned: Vec<(&str, String)> = Vec::new();
+    if let Some(limit) = args.limit {
+        owned.push(("limit", limit.to_string()));
+    }
+    if let Some(privacy_risk) = args.privacy_risk {
+        owned.push(("privacy_risk", privacy_risk.as_str().to_string()));
+    }
+    if let Some(filter) = args.lease_filter {
+        owned.push(("lease_filter", filter.as_str().to_string()));
+    }
+    let query = borrow_query(&owned);
+    let value: Value = client.call_json::<(), Value>(Method::GET, path, &query, None).await?;
+    if json {
+        emit_json(endpoint, "GET", path, &value)?;
+    } else {
+        render_items(
+            &mut stdout(),
+            "Central active-learning review queue",
+            &value,
+            &[
+                "submission_id",
+                "status",
+                "privacy_risk",
+                "priority_score",
+                "priority_reasons",
+                "review_escalation_state",
+                "review_age_hours",
+                "review_escalation_reasons",
+                "review_assigned_to_principal_ref",
+                "review_lease_expires_at",
+                "review_due_at",
+                "received_at",
+            ],
+        )?;
+    }
+    Ok(())
+}
+
+async fn review_decision(
+    client: &Client,
+    endpoint: &str,
+    args: ReviewDecisionArgs,
+    json: bool,
+) -> Result<()> {
+    let path = format!("/v1/review/{}/decision", args.submission_id);
+    let mut body = serde_json::json!({ "decision": args.decision.as_str() });
+    if let Some(reason) = args.reason.as_ref() {
+        body["reason"] = Value::String(reason.clone());
+    }
+    if let Some(credit) = args.credit_points_pending {
+        body["credit_points_pending"] = serde_json::json!(credit);
+    }
+    let value: Value = client
+        .call_json::<Value, Value>(Method::POST, &path, &[], Some(&body))
+        .await?;
+    if json {
+        emit_json(endpoint, "POST", &path, &value)?;
+    } else {
+        let mut out = stdout();
+        writeln!(out, "Recorded central review decision for {}", args.submission_id)?;
+        render_kv_fields(
+            &mut out,
+            &value,
+            &[
+                ("  status", "status"),
+                ("  pending credit", "credit_points_pending"),
+                ("  final credit", "credit_points_final"),
+            ],
+        )?;
+    }
+    Ok(())
+}
+
+async fn lease_claim(
+    client: &Client,
+    endpoint: &str,
+    args: LeaseClaimArgs,
+    json: bool,
+) -> Result<()> {
+    let path = format!("/v1/review/{}/lease", args.submission_id);
+    let body = lease_body(args.lease_ttl_seconds, args.review_due_at.as_deref(), None)?;
+    let value: Value = client
+        .call_json::<Value, Value>(Method::POST, &path, &[], Some(&body))
+        .await?;
+    if json {
+        emit_json(endpoint, "POST", &path, &value)?;
+    } else {
+        let mut out = stdout();
+        writeln!(out, "Claimed central review lease for {}", args.submission_id)?;
+        render_lease_fields(&mut out, &value)?;
+    }
+    Ok(())
+}
+
+async fn lease_claim_next(
+    client: &Client,
+    endpoint: &str,
+    args: LeaseClaimNextArgs,
+    json: bool,
+) -> Result<()> {
+    let path = "/v1/review/leases/claim-next";
+    let body = lease_body(
+        args.lease_ttl_seconds,
+        args.review_due_at.as_deref(),
+        args.privacy_risk,
+    )?;
+    let value: Value = client
+        .call_json::<Value, Value>(Method::POST, path, &[], Some(&body))
+        .await?;
+    if json {
+        emit_json(endpoint, "POST", path, &value)?;
+    } else {
+        let mut out = stdout();
+        if let Some(submission_id) = value.get("submission_id").and_then(Value::as_str) {
+            writeln!(out, "Claimed next central review lease for {submission_id}")?;
+        } else {
+            writeln!(out, "Claimed next central review lease")?;
+        }
+        render_lease_fields(&mut out, &value)?;
+    }
+    Ok(())
+}
+
+async fn lease_claim_batch(
+    client: &Client,
+    endpoint: &str,
+    args: LeaseClaimBatchArgs,
+    json: bool,
+) -> Result<()> {
+    if let Some(limit) = args.limit {
+        if limit == 0 {
+            anyhow::bail!("--limit must be greater than 0");
+        }
+    }
+    let path = "/v1/review/leases/claim-batch";
+    let mut body = lease_body(
+        args.lease_ttl_seconds,
+        args.review_due_at.as_deref(),
+        args.privacy_risk,
+    )?;
+    if let Some(limit) = args.limit {
+        body["limit"] = serde_json::json!(limit);
+    }
+    let value: Value = client
+        .call_json::<Value, Value>(Method::POST, path, &[], Some(&body))
+        .await?;
+    if json {
+        emit_json(endpoint, "POST", path, &value)?;
+    } else {
+        let mut out = stdout();
+        let count = value
+            .get("claim_count")
+            .and_then(Value::as_u64)
+            .unwrap_or(0);
+        writeln!(out, "Claimed {count} central review leases")?;
+        if let Some(claimed) = value.get("claimed").and_then(Value::as_array) {
+            for claim in claimed {
+                render_lease_fields(&mut out, claim)?;
+            }
+        }
+    }
+    Ok(())
+}
+
+async fn lease_release(
+    client: &Client,
+    endpoint: &str,
+    args: LeaseReleaseArgs,
+    json: bool,
+) -> Result<()> {
+    let path = format!("/v1/review/{}/lease", args.submission_id);
+    let value: Value = client
+        .call_json::<(), Value>(Method::DELETE, &path, &[], None)
+        .await?;
+    if json {
+        emit_json(endpoint, "DELETE", &path, &value)?;
+    } else {
+        let mut out = stdout();
+        writeln!(out, "Released central review lease for {}", args.submission_id)?;
+        render_lease_fields(&mut out, &value)?;
+    }
+    Ok(())
+}
+
+async fn append_credit_event(
+    client: &Client,
+    endpoint: &str,
+    args: AppendCreditEventArgs,
+    json: bool,
+) -> Result<()> {
+    let path = format!("/v1/review/{}/credit-events", args.submission_id);
+    let mut body = serde_json::json!({
+        "event_type": args.event_type.as_str(),
+        "credit_points_delta": args.credit_points_delta,
+        "reason": args.reason,
+    });
+    if let Some(external_ref) = args.external_ref.as_ref() {
+        body["external_ref"] = Value::String(external_ref.clone());
+    }
+    let value: Value = client
+        .call_json::<Value, Value>(Method::POST, &path, &[], Some(&body))
+        .await?;
+    if json {
+        emit_json(endpoint, "POST", &path, &value)?;
+    } else {
+        let mut out = stdout();
+        writeln!(out, "Appended central delayed credit event for {}", args.submission_id)?;
+        render_kv_fields(
+            &mut out,
+            &value,
+            &[
+                ("  event id", "event_id"),
+                ("  event type", "event_type"),
+                ("  delta", "credit_points_delta"),
+                ("  reason", "reason"),
+            ],
+        )?;
+    }
+    Ok(())
+}
+
+// --- helpers ---
+
+fn borrow_query<'a>(owned: &'a [(&'a str, String)]) -> Vec<(&'a str, &'a str)> {
+    owned.iter().map(|(k, v)| (*k, v.as_str())).collect()
+}
+
+fn lease_body(
+    lease_ttl_seconds: Option<i64>,
+    review_due_at: Option<&str>,
+    privacy_risk: Option<PrivacyRisk>,
+) -> Result<Value> {
+    let mut body = serde_json::Map::new();
+    if let Some(ttl) = lease_ttl_seconds {
+        if ttl <= 0 {
+            anyhow::bail!("--lease-ttl-seconds must be greater than 0");
+        }
+        body.insert("lease_ttl_seconds".into(), serde_json::json!(ttl));
+    }
+    if let Some(due_at) = review_due_at {
+        let trimmed = due_at.trim();
+        if !trimmed.is_empty() {
+            chrono::DateTime::parse_from_rfc3339(trimmed)
+                .map_err(|e| anyhow::anyhow!("--review-due-at must be RFC3339: {e}"))?;
+            body.insert("review_due_at".into(), Value::String(trimmed.to_string()));
+        }
+    }
+    if let Some(privacy_risk) = privacy_risk {
+        body.insert(
+            "privacy_risk".into(),
+            Value::String(privacy_risk.as_str().to_string()),
+        );
+    }
+    Ok(Value::Object(body))
+}
+
+fn render_lease_fields<W: Write>(out: &mut W, value: &Value) -> std::io::Result<()> {
+    render_kv_fields(
+        out,
+        value,
+        &[
+            ("  tenant id", "tenant_id"),
+            ("  tenant storage ref", "tenant_storage_ref"),
+            ("  trace id", "trace_id"),
+            ("  status", "status"),
+            ("  assigned principal", "review_assigned_to_principal_ref"),
+            ("  assigned at", "review_assigned_at"),
+            ("  lease expires at", "review_lease_expires_at"),
+            ("  review due at", "review_due_at"),
+        ],
+    )
+}
+
+fn emit_json(endpoint: &str, method: &str, path: &str, value: &Value) -> Result<()> {
+    let url = sanitized_url(endpoint, path);
+    oc_format::emit_json(&mut stdout(), method, &url, value)?;
+    Ok(())
+}
+
+// --- tests ---
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::atomic::{AtomicU64, Ordering};
+    use wiremock::matchers::{body_json, header, method, path, query_param};
+    use wiremock::{Mock, MockServer, ResponseTemplate};
+
+    fn unique_bearer_env() -> String {
+        static SEQ: AtomicU64 = AtomicU64::new(0);
+        let n = SEQ.fetch_add(1, Ordering::Relaxed);
+        format!("TC_REVIEW_TEST_BEARER_{n}")
+    }
+
+    struct EnvGuard {
+        name: String,
+    }
+
+    impl EnvGuard {
+        fn set(name: String, value: &str) -> Self {
+            unsafe { std::env::set_var(&name, value) };
+            EnvGuard { name }
+        }
+    }
+
+    impl Drop for EnvGuard {
+        fn drop(&mut self) {
+            unsafe { std::env::remove_var(&self.name) };
+        }
+    }
+
+    #[test]
+    fn cli_parses_quarantine_list_minimal() {
+        let cli = Cli::try_parse_from([
+            "trace-commons-review",
+            "--endpoint",
+            "https://api.example",
+            "quarantine-list",
+        ])
+        .unwrap();
+        match cli.command {
+            ReviewSubcommand::QuarantineList(args) => assert!(args.lease_filter.is_none()),
+            other => panic!("unexpected variant: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn cli_parses_quarantine_list_with_filter() {
+        let cli = Cli::try_parse_from([
+            "trace-commons-review",
+            "--endpoint",
+            "https://api.example",
+            "quarantine-list",
+            "--lease-filter",
+            "mine",
+        ])
+        .unwrap();
+        match cli.command {
+            ReviewSubcommand::QuarantineList(args) => {
+                assert_eq!(args.lease_filter, Some(ReviewLeaseFilter::Mine));
+            }
+            other => panic!("unexpected variant: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn cli_rejects_unknown_subcommand() {
+        let err = Cli::try_parse_from([
+            "trace-commons-review",
+            "--endpoint",
+            "https://api.example",
+            "bogus",
+        ])
+        .unwrap_err();
+        assert!(!err.to_string().is_empty());
+    }
+
+    #[test]
+    fn cli_parses_review_decision() {
+        let id = Uuid::new_v4();
+        let cli = Cli::try_parse_from([
+            "trace-commons-review",
+            "--endpoint",
+            "https://api.example",
+            "review-decision",
+            "--submission-id",
+            &id.to_string(),
+            "--decision",
+            "approve",
+        ])
+        .unwrap();
+        match cli.command {
+            ReviewSubcommand::ReviewDecision(args) => {
+                assert_eq!(args.submission_id, id);
+                assert_eq!(args.decision, ReviewDecision::Approve);
+            }
+            other => panic!("unexpected variant: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn cli_rejects_review_decision_invalid_choice() {
+        let id = Uuid::new_v4();
+        let err = Cli::try_parse_from([
+            "trace-commons-review",
+            "--endpoint",
+            "https://api.example",
+            "review-decision",
+            "--submission-id",
+            &id.to_string(),
+            "--decision",
+            "maybe",
+        ])
+        .unwrap_err();
+        assert!(!err.to_string().is_empty());
+    }
+
+    #[test]
+    fn cli_parses_active_learning_full() {
+        let cli = Cli::try_parse_from([
+            "trace-commons-review",
+            "--endpoint",
+            "https://api.example",
+            "active-learning-review-queue",
+            "--limit",
+            "10",
+            "--privacy-risk",
+            "low",
+            "--lease-filter",
+            "active",
+        ])
+        .unwrap();
+        match cli.command {
+            ReviewSubcommand::ActiveLearningReviewQueue(args) => {
+                assert_eq!(args.limit, Some(10));
+                assert_eq!(args.privacy_risk, Some(PrivacyRisk::Low));
+                assert_eq!(args.lease_filter, Some(ReviewLeaseFilter::Active));
+            }
+            other => panic!("unexpected variant: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn cli_parses_lease_claim() {
+        let id = Uuid::new_v4();
+        Cli::try_parse_from([
+            "trace-commons-review",
+            "--endpoint",
+            "https://api.example",
+            "review-lease-claim",
+            "--submission-id",
+            &id.to_string(),
+            "--lease-ttl-seconds",
+            "120",
+        ])
+        .unwrap();
+    }
+
+    #[test]
+    fn cli_parses_lease_claim_next() {
+        Cli::try_parse_from([
+            "trace-commons-review",
+            "--endpoint",
+            "https://api.example",
+            "review-lease-claim-next",
+            "--privacy-risk",
+            "high",
+        ])
+        .unwrap();
+    }
+
+    #[test]
+    fn cli_parses_lease_claim_batch() {
+        Cli::try_parse_from([
+            "trace-commons-review",
+            "--endpoint",
+            "https://api.example",
+            "review-lease-claim-batch",
+            "--limit",
+            "5",
+        ])
+        .unwrap();
+    }
+
+    #[test]
+    fn cli_parses_lease_release() {
+        let id = Uuid::new_v4();
+        Cli::try_parse_from([
+            "trace-commons-review",
+            "--endpoint",
+            "https://api.example",
+            "review-lease-release",
+            "--submission-id",
+            &id.to_string(),
+        ])
+        .unwrap();
+    }
+
+    #[test]
+    fn cli_parses_append_credit_event() {
+        let id = Uuid::new_v4();
+        Cli::try_parse_from([
+            "trace-commons-review",
+            "--endpoint",
+            "https://api.example",
+            "append-credit-event",
+            "--submission-id",
+            &id.to_string(),
+            "--event-type",
+            "benchmark-conversion",
+            "--credit-points-delta",
+            "1.5",
+            "--reason",
+            "good trace",
+        ])
+        .unwrap();
+    }
+
+    #[test]
+    fn lease_body_rejects_non_positive_ttl() {
+        let err = lease_body(Some(0), None, None).unwrap_err();
+        assert!(err.to_string().contains("greater than 0"));
+    }
+
+    #[test]
+    fn lease_body_rejects_bad_due_at() {
+        let err = lease_body(None, Some("yesterday"), None).unwrap_err();
+        assert!(err.to_string().contains("RFC3339"));
+    }
+
+    #[tokio::test]
+    async fn quarantine_list_happy_path_hits_expected_route() {
+        let server = MockServer::start().await;
+        Mock::given(method("GET"))
+            .and(path("/v1/review/quarantine"))
+            .and(query_param("lease_filter", "mine"))
+            .and(header("authorization", "Bearer reviewer-secret"))
+            .respond_with(
+                ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                    "items": [
+                        {"submission_id": "sub-1", "privacy_risk": "low"}
+                    ]
+                })),
+            )
+            .expect(1)
+            .mount(&server)
+            .await;
+
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "reviewer-secret");
+        let mut builder = Client::builder(server.uri(), env);
+        builder = builder.host_allowlist(HostAllowlist::permissive());
+        let client = builder.build().unwrap();
+        quarantine_list(
+            &client,
+            &server.uri(),
+            QuarantineListArgs {
+                lease_filter: Some(ReviewLeaseFilter::Mine),
+            },
+            true,
+        )
+        .await
+        .expect("happy path");
+    }
+
+    #[tokio::test]
+    async fn review_decision_posts_expected_body() {
+        let id = Uuid::new_v4();
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path(format!("/v1/review/{id}/decision")))
+            .and(body_json(serde_json::json!({
+                "decision": "approve",
+                "reason": "looks fine",
+            })))
+            .respond_with(
+                ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                    "status": "approved",
+                    "credit_points_final": 1.0,
+                })),
+            )
+            .expect(1)
+            .mount(&server)
+            .await;
+
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "secret");
+        let client = Client::builder(server.uri(), env).build().unwrap();
+        review_decision(
+            &client,
+            &server.uri(),
+            ReviewDecisionArgs {
+                submission_id: id,
+                decision: ReviewDecision::Approve,
+                reason: Some("looks fine".into()),
+                credit_points_pending: None,
+            },
+            true,
+        )
+        .await
+        .expect("decision posted");
+    }
+}

From dbf6105e280d0e8d1a8b0f3cb9017f9a42910fce Mon Sep 17 00:00:00 2001
From: Zaki <zaki@iqlusion.io>
Date: Tue, 19 May 2026 15:29:55 -0700
Subject: [PATCH 3/7] Add trace-commons-worker and trace-commons-tenant
 operator binaries

---
 crates/trace-commons-server/Cargo.toml        |    8 +
 .../src/bin/trace-commons-tenant.rs           | 1584 ++++++++++++++++
 .../src/bin/trace-commons-worker.rs           | 1681 +++++++++++++++++
 3 files changed, 3273 insertions(+)
 create mode 100644 crates/trace-commons-server/src/bin/trace-commons-tenant.rs
 create mode 100644 crates/trace-commons-server/src/bin/trace-commons-worker.rs

diff --git a/crates/trace-commons-server/Cargo.toml b/crates/trace-commons-server/Cargo.toml
index 2449014c0..a5643fac1 100644
--- a/crates/trace-commons-server/Cargo.toml
+++ b/crates/trace-commons-server/Cargo.toml
@@ -97,6 +97,14 @@ path = "src/bin/trace-commons-review.rs"
 name = "trace-commons-admin"
 path = "src/bin/trace-commons-admin.rs"
 
+[[bin]]
+name = "trace-commons-worker"
+path = "src/bin/trace-commons-worker.rs"
+
+[[bin]]
+name = "trace-commons-tenant"
+path = "src/bin/trace-commons-tenant.rs"
+
 [dev-dependencies]
 tower = { version = "0.5", features = ["util"] }
 wiremock = "0.6"
diff --git a/crates/trace-commons-server/src/bin/trace-commons-tenant.rs b/crates/trace-commons-server/src/bin/trace-commons-tenant.rs
new file mode 100644
index 000000000..35920281f
--- /dev/null
+++ b/crates/trace-commons-server/src/bin/trace-commons-tenant.rs
@@ -0,0 +1,1584 @@
+//! `trace-commons-tenant` — tenant-audience operator CLI.
+//!
+//! Eleven subcommands covering tenant-policy management, tenant access-grant
+//! lifecycle, ranker training exports, audit-event listing, trace listing,
+//! and a local privacy-filter canary helper. All HTTP-backed subcommands
+//! share a single `--bearer-token-env` defaulting to
+//! `TRACE_COMMONS_TENANT_BEARER`. Two subcommands (`tenant-principal-ref`,
+//! `privacy-filter-canary`) do not hit the server: the first derives a
+//! principal ref locally; the second is intentionally stubbed in this
+//! operator binary because the underlying privacy-filter sidecar is not yet
+//! ported off the Ironclaw runtime.
+
+#[path = "operator_common/mod.rs"]
+mod operator_common;
+
+use std::io::{stdout, Write};
+use std::path::PathBuf;
+
+use anyhow::Result;
+use clap::{Parser, Subcommand, ValueEnum};
+use reqwest::Method;
+use serde_json::Value;
+use sha2::{Digest, Sha256};
+use trace_commons_operator_client::{format as oc_format, host_allowlist::HostAllowlist, Client};
+use uuid::Uuid;
+
+use operator_common::{render_items, render_kv_fields, sanitized_url};
+
+const DEFAULT_BEARER_ENV: &str = "TRACE_COMMONS_TENANT_BEARER";
+
+#[derive(Debug, Parser)]
+#[command(
+    name = "trace-commons-tenant",
+    about = "Tenant-audience CLI for trace-commons-server.",
+    version
+)]
+pub(crate) struct Cli {
+    /// Hosted endpoint. Reads `TRACE_COMMONS_ENDPOINT` when unset on the CLI.
+    /// Not required for `tenant-principal-ref` or `privacy-filter-canary`.
+    #[arg(long, env = "TRACE_COMMONS_ENDPOINT")]
+    pub endpoint: Option<String>,
+
+    /// Name of the env var holding the tenant bearer token.
+    #[arg(long, default_value = DEFAULT_BEARER_ENV)]
+    pub bearer_token_env: String,
+
+    /// Defense-in-depth host allowlist (CSV). Empty means permissive.
+    #[arg(long, env = "TRACE_COMMONS_ALLOWED_HOSTS")]
+    pub allowed_hosts: Option<String>,
+
+    /// Emit the server response as JSON (with a sanitized request envelope).
+    #[arg(long, global = true)]
+    pub json: bool,
+
+    #[command(subcommand)]
+    pub command: TenantSubcommand,
+}
+
+#[derive(Debug, Subcommand)]
+pub(crate) enum TenantSubcommand {
+    /// Read the DB-backed tenant contribution policy.
+    TenantPolicyGet,
+    /// Write the DB-backed tenant contribution policy.
+    TenantPolicySet(TenantPolicySetArgs),
+    /// List DB-backed tenant access grants for hosted-agent permissioning.
+    TenantAccessGrantsList(TenantAccessGrantsListArgs),
+    /// Derive the stored principal_ref used by tenant access grants.
+    TenantPrincipalRef(TenantPrincipalRefArgs),
+    /// Create a DB-backed tenant access grant for an issuer-authorized principal.
+    TenantAccessGrantCreate(TenantAccessGrantCreateArgs),
+    /// Revoke a DB-backed tenant access grant.
+    TenantAccessGrantRevoke(TenantAccessGrantRevokeArgs),
+    /// Export approved ranker training candidates.
+    RankerTrainingCandidates(RankerTrainingArgs),
+    /// Export approved ranker training pairs.
+    RankerTrainingPairs(RankerTrainingArgs),
+    /// List central Trace Commons audit events.
+    AuditEvents(AuditEventsArgs),
+    /// List central trace metadata with optional reviewer filters.
+    ListTraces(ListTracesArgs),
+    /// Run a local Privacy Filter sidecar canary check (stub in operator binary).
+    PrivacyFilterCanary(PrivacyFilterCanaryArgs),
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct TenantPolicySetArgs {
+    #[arg(long)]
+    pub policy_version: String,
+    #[arg(long, value_enum, value_delimiter = ',')]
+    pub allowed_consent_scopes: Vec<ConsentScope>,
+    #[arg(long, value_enum, value_delimiter = ',')]
+    pub allowed_uses: Vec<AllowedUse>,
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct TenantAccessGrantsListArgs {
+    #[arg(long)]
+    pub limit: Option<usize>,
+    #[arg(long, value_enum)]
+    pub status: Option<TenantAccessGrantStatus>,
+    #[arg(long, value_enum)]
+    pub role: Option<TenantAccessGrantRole>,
+    #[arg(long)]
+    pub principal_ref: Option<String>,
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct TenantPrincipalRefArgs {
+    /// Env var name holding a static Trace Commons bearer token. Mutually
+    /// exclusive with the signed-claim flags below.
+    #[arg(long)]
+    pub token_env: Option<String>,
+    /// Tenant ID for a signed-claim principal.
+    #[arg(long)]
+    pub signed_tenant_id: Option<String>,
+    /// Signed-claim principal_ref or `sub` value.
+    #[arg(long)]
+    pub signed_actor_ref: Option<String>,
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct TenantAccessGrantCreateArgs {
+    #[arg(long)]
+    pub principal_ref: String,
+    #[arg(long, value_enum)]
+    pub role: TenantAccessGrantRole,
+    #[arg(long)]
+    pub grant_id: Option<Uuid>,
+    #[arg(long, value_enum, value_delimiter = ',')]
+    pub allowed_consent_scopes: Vec<ConsentScope>,
+    #[arg(long, value_enum, value_delimiter = ',')]
+    pub allowed_uses: Vec<AllowedUse>,
+    #[arg(long)]
+    pub issuer: Option<String>,
+    #[arg(long)]
+    pub audience: Option<String>,
+    #[arg(long)]
+    pub subject: Option<String>,
+    #[arg(long)]
+    pub issued_at: Option<String>,
+    #[arg(long)]
+    pub expires_at: Option<String>,
+    #[arg(long)]
+    pub reason: String,
+    /// Safe grant metadata as KEY=VALUE, repeatable.
+    #[arg(long = "metadata", value_name = "KEY=VALUE")]
+    pub metadata: Vec<String>,
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct TenantAccessGrantRevokeArgs {
+    #[arg(long)]
+    pub grant_id: Uuid,
+    #[arg(long)]
+    pub reason: String,
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct RankerTrainingArgs {
+    #[arg(long)]
+    pub purpose: Option<String>,
+    #[arg(long, value_enum)]
+    pub consent_scope: Option<ConsentScope>,
+    #[arg(long, value_enum)]
+    pub status: Option<CorpusStatus>,
+    #[arg(long, value_enum)]
+    pub privacy_risk: Option<PrivacyRisk>,
+    #[arg(long)]
+    pub limit: Option<usize>,
+    #[arg(long)]
+    pub output: Option<PathBuf>,
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct AuditEventsArgs {
+    #[arg(long)]
+    pub limit: Option<usize>,
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct ListTracesArgs {
+    #[arg(long)]
+    pub purpose: Option<String>,
+    #[arg(long, value_enum)]
+    pub consent_scope: Option<ConsentScope>,
+    #[arg(long, value_enum)]
+    pub status: Option<CorpusStatus>,
+    #[arg(long)]
+    pub limit: Option<usize>,
+    #[arg(long)]
+    pub coverage_tag: Option<String>,
+    #[arg(long)]
+    pub tool: Option<String>,
+    #[arg(long, value_enum)]
+    pub privacy_risk: Option<PrivacyRisk>,
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct PrivacyFilterCanaryArgs {
+    #[arg(
+        long,
+        default_value = "Canary email alice@example.com with key sk-test-123 and path /Users/alice/private.txt"
+    )]
+    pub text: String,
+    #[arg(long, default_value_t = 10)]
+    pub timeout_seconds: u64,
+}
+
+// --- value enums ---
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub(crate) enum PrivacyRisk {
+    Low,
+    Medium,
+    High,
+}
+
+impl PrivacyRisk {
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::Low => "low",
+            Self::Medium => "medium",
+            Self::High => "high",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub(crate) enum CorpusStatus {
+    Accepted,
+    Quarantined,
+    Rejected,
+    Revoked,
+    Expired,
+    Purged,
+}
+
+impl CorpusStatus {
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::Accepted => "accepted",
+            Self::Quarantined => "quarantined",
+            Self::Rejected => "rejected",
+            Self::Revoked => "revoked",
+            Self::Expired => "expired",
+            Self::Purged => "purged",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub(crate) enum ConsentScope {
+    DebuggingEvaluation,
+    BenchmarkOnly,
+    RankingTraining,
+    ModelTraining,
+}
+
+impl ConsentScope {
+    /// Server wire value (snake_case).
+    fn server_value(self) -> &'static str {
+        match self {
+            Self::DebuggingEvaluation => "debugging_evaluation",
+            Self::BenchmarkOnly => "benchmark_only",
+            Self::RankingTraining => "ranking_training",
+            Self::ModelTraining => "model_training",
+        }
+    }
+    /// Query-string value (kebab-case, matches reviewer/admin filters).
+    fn query_value(self) -> &'static str {
+        match self {
+            Self::DebuggingEvaluation => "debugging-evaluation",
+            Self::BenchmarkOnly => "benchmark-only",
+            Self::RankingTraining => "ranking-training",
+            Self::ModelTraining => "model-training",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub(crate) enum AllowedUse {
+    Debugging,
+    Evaluation,
+    BenchmarkGeneration,
+    RankingModelTraining,
+    ModelTraining,
+    AggregateAnalytics,
+}
+
+impl AllowedUse {
+    fn server_value(self) -> &'static str {
+        match self {
+            Self::Debugging => "debugging",
+            Self::Evaluation => "evaluation",
+            Self::BenchmarkGeneration => "benchmark_generation",
+            Self::RankingModelTraining => "ranking_model_training",
+            Self::ModelTraining => "model_training",
+            Self::AggregateAnalytics => "aggregate_analytics",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub(crate) enum TenantAccessGrantStatus {
+    Active,
+    Revoked,
+    Expired,
+}
+
+impl TenantAccessGrantStatus {
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::Active => "active",
+            Self::Revoked => "revoked",
+            Self::Expired => "expired",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub(crate) enum TenantAccessGrantRole {
+    Contributor,
+    Reviewer,
+    Admin,
+    Benchmarker,
+    Exporter,
+}
+
+impl TenantAccessGrantRole {
+    fn server_value(self) -> &'static str {
+        match self {
+            Self::Contributor => "contributor",
+            Self::Reviewer => "reviewer",
+            Self::Admin => "admin",
+            Self::Benchmarker => "benchmarker",
+            Self::Exporter => "exporter",
+        }
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let cli = Cli::parse();
+    dispatch(cli).await
+}
+
+fn build_client(cli: &Cli) -> Result<Client> {
+    let endpoint = cli
+        .endpoint
+        .as_deref()
+        .ok_or_else(|| anyhow::anyhow!("--endpoint (or TRACE_COMMONS_ENDPOINT) is required"))?;
+    let mut builder = Client::builder(endpoint, &cli.bearer_token_env);
+    if let Some(csv) = cli.allowed_hosts.as_deref() {
+        builder = builder.host_allowlist(HostAllowlist::from_csv(csv));
+    }
+    Ok(builder.build()?)
+}
+
+async fn dispatch(cli: Cli) -> Result<()> {
+    // Subcommands that don't hit the server: handle first so we don't require
+    // an endpoint to be configured.
+    match &cli.command {
+        TenantSubcommand::TenantPrincipalRef(args) => {
+            return tenant_principal_ref(args, cli.json);
+        }
+        TenantSubcommand::PrivacyFilterCanary(_args) => {
+            anyhow::bail!(
+                "privacy-filter-canary is not yet ported to the operator binary; run the local sidecar canary via legacy Ironclaw tooling"
+            );
+        }
+        _ => {}
+    }
+    let client = build_client(&cli)?;
+    let endpoint = cli.endpoint.clone().unwrap();
+    let json = cli.json;
+    match cli.command {
+        TenantSubcommand::TenantPolicyGet => tenant_policy_get(&client, &endpoint, json).await,
+        TenantSubcommand::TenantPolicySet(args) => {
+            tenant_policy_set(&client, &endpoint, args, json).await
+        }
+        TenantSubcommand::TenantAccessGrantsList(args) => {
+            tenant_access_grants_list(&client, &endpoint, args, json).await
+        }
+        TenantSubcommand::TenantAccessGrantCreate(args) => {
+            tenant_access_grant_create(&client, &endpoint, args, json).await
+        }
+        TenantSubcommand::TenantAccessGrantRevoke(args) => {
+            tenant_access_grant_revoke(&client, &endpoint, args, json).await
+        }
+        TenantSubcommand::RankerTrainingCandidates(args) => {
+            ranker_training_export(
+                &client,
+                &endpoint,
+                args,
+                "/v1/ranker/training-candidates",
+                "ranker training candidates",
+                "candidates",
+                json,
+            )
+            .await
+        }
+        TenantSubcommand::RankerTrainingPairs(args) => {
+            ranker_training_export(
+                &client,
+                &endpoint,
+                args,
+                "/v1/ranker/training-pairs",
+                "ranker training pairs",
+                "pairs",
+                json,
+            )
+            .await
+        }
+        TenantSubcommand::AuditEvents(args) => audit_events(&client, &endpoint, args, json).await,
+        TenantSubcommand::ListTraces(args) => list_traces(&client, &endpoint, args, json).await,
+        TenantSubcommand::TenantPrincipalRef(_) | TenantSubcommand::PrivacyFilterCanary(_) => {
+            unreachable!("handled above")
+        }
+    }
+}
+
+// --- handlers ---
+
+async fn tenant_policy_get(client: &Client, endpoint: &str, json: bool) -> Result<()> {
+    let path = "/v1/admin/tenant-policy";
+    let value: Value = client.call_json::<(), Value>(Method::GET, path, &[], None).await?;
+    if json {
+        emit_json(endpoint, "GET", path, &value)?;
+    } else {
+        render_tenant_policy(&value)?;
+    }
+    Ok(())
+}
+
+async fn tenant_policy_set(
+    client: &Client,
+    endpoint: &str,
+    args: TenantPolicySetArgs,
+    json: bool,
+) -> Result<()> {
+    let version = args.policy_version.trim();
+    if version.is_empty() {
+        anyhow::bail!("--policy-version must not be empty");
+    }
+    let path = "/v1/admin/tenant-policy";
+    let body = serde_json::json!({
+        "policy_version": version,
+        "allowed_consent_scopes": args
+            .allowed_consent_scopes
+            .iter()
+            .map(|s| s.server_value())
+            .collect::<Vec<_>>(),
+        "allowed_uses": args
+            .allowed_uses
+            .iter()
+            .map(|u| u.server_value())
+            .collect::<Vec<_>>(),
+    });
+    let value: Value = client
+        .call_json::<Value, Value>(Method::PUT, path, &[], Some(&body))
+        .await?;
+    if json {
+        emit_json(endpoint, "PUT", path, &value)?;
+    } else {
+        render_tenant_policy(&value)?;
+    }
+    Ok(())
+}
+
+fn render_tenant_policy(value: &Value) -> Result<()> {
+    let mut out = stdout();
+    writeln!(out, "Trace Commons tenant policy:")?;
+    render_kv_fields(
+        &mut out,
+        value,
+        &[
+            ("  tenant", "tenant_id"),
+            ("  policy version", "policy_version"),
+            ("  allowed consent scopes", "allowed_consent_scopes"),
+            ("  allowed uses", "allowed_uses"),
+            ("  updated by", "updated_by_principal_ref"),
+            ("  updated at", "updated_at"),
+        ],
+    )?;
+    Ok(())
+}
+
+async fn tenant_access_grants_list(
+    client: &Client,
+    endpoint: &str,
+    args: TenantAccessGrantsListArgs,
+    json: bool,
+) -> Result<()> {
+    let path = "/v1/admin/tenant-access-grants";
+    let mut owned: Vec<(&str, String)> = Vec::new();
+    if let Some(limit) = args.limit {
+        owned.push(("limit", limit.to_string()));
+    }
+    if let Some(status) = args.status {
+        owned.push(("status", status.as_str().to_string()));
+    }
+    if let Some(role) = args.role {
+        owned.push(("role", role.server_value().to_string()));
+    }
+    if let Some(principal_ref) = args.principal_ref {
+        let trimmed = principal_ref.trim();
+        if !trimmed.is_empty() {
+            owned.push(("principal_ref", trimmed.to_string()));
+        }
+    }
+    let query = borrow_query(&owned);
+    let value: Value = client
+        .call_json::<(), Value>(Method::GET, path, &query, None)
+        .await?;
+    if json {
+        emit_json(endpoint, "GET", path, &value)?;
+    } else {
+        render_items(
+            &mut stdout(),
+            "Central tenant access grants",
+            &value,
+            &[
+                "grant_id",
+                "principal_ref",
+                "role",
+                "status",
+                "allowed_consent_scopes",
+                "allowed_uses",
+                "issuer",
+                "subject",
+                "expires_at",
+                "revoked_at",
+            ],
+        )?;
+    }
+    Ok(())
+}
+
+async fn tenant_access_grant_create(
+    client: &Client,
+    endpoint: &str,
+    args: TenantAccessGrantCreateArgs,
+    json: bool,
+) -> Result<()> {
+    let principal_ref = args.principal_ref.trim();
+    if principal_ref.is_empty() {
+        anyhow::bail!("--principal-ref must not be empty");
+    }
+    let reason = args.reason.trim();
+    if reason.is_empty() {
+        anyhow::bail!("--reason must not be empty");
+    }
+    if let Some(at) = args.issued_at.as_deref() {
+        require_rfc3339("--issued-at", at)?;
+    }
+    if let Some(at) = args.expires_at.as_deref() {
+        require_rfc3339("--expires-at", at)?;
+    }
+    let mut body = serde_json::json!({
+        "principal_ref": principal_ref,
+        "role": args.role.server_value(),
+        "allowed_consent_scopes": args
+            .allowed_consent_scopes
+            .iter()
+            .map(|s| s.server_value())
+            .collect::<Vec<_>>(),
+        "allowed_uses": args
+            .allowed_uses
+            .iter()
+            .map(|u| u.server_value())
+            .collect::<Vec<_>>(),
+        "reason": reason,
+    });
+    if let Some(grant_id) = args.grant_id {
+        body["grant_id"] = Value::String(grant_id.to_string());
+    }
+    if let Some(s) = trimmed(args.issuer.as_deref()) {
+        body["issuer"] = Value::String(s);
+    }
+    if let Some(s) = trimmed(args.audience.as_deref()) {
+        body["audience"] = Value::String(s);
+    }
+    if let Some(s) = trimmed(args.subject.as_deref()) {
+        body["subject"] = Value::String(s);
+    }
+    if let Some(s) = trimmed(args.issued_at.as_deref()) {
+        body["issued_at"] = Value::String(s);
+    }
+    if let Some(s) = trimmed(args.expires_at.as_deref()) {
+        body["expires_at"] = Value::String(s);
+    }
+    let metadata = parse_metadata(&args.metadata)?;
+    if !metadata.is_empty() {
+        body["metadata"] = serde_json::to_value(metadata)
+            .map_err(|e| anyhow::anyhow!("failed to encode grant metadata: {e}"))?;
+    }
+    let path = "/v1/admin/tenant-access-grants";
+    let value: Value = client
+        .call_json::<Value, Value>(Method::POST, path, &[], Some(&body))
+        .await?;
+    if json {
+        emit_json(endpoint, "POST", path, &value)?;
+    } else {
+        let mut out = stdout();
+        writeln!(out, "Trace Commons tenant access grant created.")?;
+        render_grant_fields(&mut out, &value)?;
+    }
+    Ok(())
+}
+
+async fn tenant_access_grant_revoke(
+    client: &Client,
+    endpoint: &str,
+    args: TenantAccessGrantRevokeArgs,
+    json: bool,
+) -> Result<()> {
+    let reason = args.reason.trim();
+    if reason.is_empty() {
+        anyhow::bail!("--reason must not be empty");
+    }
+    let path = format!("/v1/admin/tenant-access-grants/{}/revoke", args.grant_id);
+    let body = serde_json::json!({ "reason": reason });
+    let value: Value = client
+        .call_json::<Value, Value>(Method::POST, &path, &[], Some(&body))
+        .await?;
+    if json {
+        emit_json(endpoint, "POST", &path, &value)?;
+    } else {
+        let mut out = stdout();
+        writeln!(out, "Trace Commons tenant access grant revoked.")?;
+        render_grant_fields(&mut out, &value)?;
+    }
+    Ok(())
+}
+
+fn render_grant_fields<W: Write>(out: &mut W, value: &Value) -> std::io::Result<()> {
+    render_kv_fields(
+        out,
+        value,
+        &[
+            ("  tenant", "tenant_id"),
+            ("  grant id", "grant_id"),
+            ("  principal", "principal_ref"),
+            ("  role", "role"),
+            ("  status", "status"),
+            ("  allowed consent scopes", "allowed_consent_scopes"),
+            ("  allowed uses", "allowed_uses"),
+            ("  issuer", "issuer"),
+            ("  audience", "audience"),
+            ("  subject", "subject"),
+            ("  expires at", "expires_at"),
+            ("  revoked at", "revoked_at"),
+        ],
+    )
+}
+
+#[allow(clippy::too_many_arguments)]
+async fn ranker_training_export(
+    client: &Client,
+    endpoint: &str,
+    args: RankerTrainingArgs,
+    path: &str,
+    output_label: &str,
+    item_field: &str,
+    json: bool,
+) -> Result<()> {
+    let mut owned: Vec<(&str, String)> = Vec::new();
+    if let Some(limit) = args.limit {
+        owned.push(("limit", limit.to_string()));
+    }
+    if let Some(purpose) = args.purpose {
+        let trimmed = purpose.trim();
+        if trimmed.is_empty() {
+            anyhow::bail!("--purpose must be non-empty");
+        }
+        owned.push(("purpose", trimmed.to_string()));
+    }
+    if let Some(scope) = args.consent_scope {
+        owned.push(("consent_scope", scope.query_value().to_string()));
+    }
+    if let Some(status) = args.status {
+        owned.push(("status", status.as_str().to_string()));
+    }
+    if let Some(risk) = args.privacy_risk {
+        owned.push(("privacy_risk", risk.as_str().to_string()));
+    }
+    let query = borrow_query(&owned);
+    let raw = client.call_raw::<()>(Method::GET, path, &query, None).await?;
+    let value: Value = serde_json::from_str(&raw).unwrap_or(Value::Null);
+
+    if let Some(output) = args.output.as_ref() {
+        let pretty = if value.is_null() {
+            raw.clone()
+        } else {
+            serde_json::to_string_pretty(&value)?
+        };
+        std::fs::write(output, pretty).map_err(|e| {
+            anyhow::anyhow!(
+                "failed to write ranker training export {}: {}",
+                output.display(),
+                e
+            )
+        })?;
+        if json {
+            emit_json(endpoint, "GET", path, &value)?;
+        } else {
+            let mut out = stdout();
+            writeln!(
+                out,
+                "Wrote central {} export to {}",
+                output_label,
+                output.display()
+            )?;
+            render_kv_fields(
+                &mut out,
+                &value,
+                &[
+                    ("  export id", "export_id"),
+                    ("  audit event id", "audit_event_id"),
+                    ("  purpose", "purpose"),
+                    ("  item count", "item_count"),
+                ],
+            )?;
+        }
+        return Ok(());
+    }
+
+    if json {
+        emit_json(endpoint, "GET", path, &value)
+    } else {
+        let items = value.get(item_field).cloned().unwrap_or(Value::Null);
+        let envelope = serde_json::json!({ "items": items });
+        render_items(
+            &mut stdout(),
+            &format!("Central {output_label}"),
+            &envelope,
+            &[
+                "submission_id",
+                "trace_id",
+                "ranker_score",
+                "preferred_submission_id",
+                "rejected_submission_id",
+                "reason",
+            ],
+        )?;
+        Ok(())
+    }
+}
+
+async fn audit_events(
+    client: &Client,
+    endpoint: &str,
+    args: AuditEventsArgs,
+    json: bool,
+) -> Result<()> {
+    let path = "/v1/audit/events";
+    let mut owned: Vec<(&str, String)> = Vec::new();
+    if let Some(limit) = args.limit {
+        owned.push(("limit", limit.to_string()));
+    }
+    let query = borrow_query(&owned);
+    let value: Value = client
+        .call_json::<(), Value>(Method::GET, path, &query, None)
+        .await?;
+    if json {
+        emit_json(endpoint, "GET", path, &value)?;
+    } else {
+        render_items(
+            &mut stdout(),
+            "Central audit events",
+            &value,
+            &["created_at", "kind", "submission_id", "status", "reason"],
+        )?;
+    }
+    Ok(())
+}
+
+async fn list_traces(
+    client: &Client,
+    endpoint: &str,
+    args: ListTracesArgs,
+    json: bool,
+) -> Result<()> {
+    let path = "/v1/traces";
+    let mut owned: Vec<(&str, String)> = Vec::new();
+    if let Some(purpose) = args.purpose {
+        let trimmed = purpose.trim();
+        if trimmed.is_empty() {
+            anyhow::bail!("--purpose must be non-empty");
+        }
+        owned.push(("purpose", trimmed.to_string()));
+    }
+    if let Some(scope) = args.consent_scope {
+        owned.push(("consent_scope", scope.query_value().to_string()));
+    }
+    if let Some(status) = args.status {
+        owned.push(("status", status.as_str().to_string()));
+    }
+    if let Some(limit) = args.limit {
+        owned.push(("limit", limit.to_string()));
+    }
+    if let Some(tag) = args.coverage_tag {
+        owned.push(("coverage_tag", tag));
+    }
+    if let Some(tool) = args.tool {
+        owned.push(("tool", tool));
+    }
+    if let Some(risk) = args.privacy_risk {
+        owned.push(("privacy_risk", risk.as_str().to_string()));
+    }
+    let query = borrow_query(&owned);
+    let value: Value = client
+        .call_json::<(), Value>(Method::GET, path, &query, None)
+        .await?;
+    if json {
+        emit_json(endpoint, "GET", path, &value)?;
+    } else {
+        render_items(
+            &mut stdout(),
+            "Central traces",
+            &value,
+            &[
+                "submission_id",
+                "status",
+                "privacy_risk",
+                "submission_score",
+                "credit_points_pending",
+                "review_assigned_to_principal_ref",
+                "review_lease_expires_at",
+                "review_due_at",
+                "received_at",
+            ],
+        )?;
+    }
+    Ok(())
+}
+
+fn tenant_principal_ref(args: &TenantPrincipalRefArgs, json: bool) -> Result<()> {
+    let token_env = trimmed(args.token_env.as_deref());
+    let signed_tenant_id = trimmed(args.signed_tenant_id.as_deref());
+    let signed_actor_ref = trimmed(args.signed_actor_ref.as_deref());
+    let has_token = token_env.is_some();
+    let has_signed = signed_tenant_id.is_some() || signed_actor_ref.is_some();
+    if has_token == has_signed {
+        anyhow::bail!(
+            "provide either --token-env or both --signed-tenant-id and --signed-actor-ref"
+        );
+    }
+    let (mode, principal_ref) = if let Some(token_env) = token_env {
+        let token = std::env::var(&token_env).map_err(|_| {
+            anyhow::anyhow!(
+                "{} is not set; refusing to derive a principal_ref from a missing token",
+                token_env
+            )
+        })?;
+        if token.trim().is_empty() {
+            anyhow::bail!("{token_env} is empty; refusing to derive a principal_ref");
+        }
+        ("static_token", principal_storage_ref(&token))
+    } else {
+        let tenant_id = signed_tenant_id
+            .ok_or_else(|| anyhow::anyhow!("--signed-tenant-id is required with --signed-actor-ref"))?;
+        let actor_ref = signed_actor_ref
+            .ok_or_else(|| anyhow::anyhow!("--signed-actor-ref is required with --signed-tenant-id"))?;
+        ("signed_claim", signed_claim_principal_ref(&tenant_id, &actor_ref))
+    };
+
+    if json {
+        let value = serde_json::json!({
+            "mode": mode,
+            "principal_ref": principal_ref,
+        });
+        oc_format::emit_json(&mut stdout(), "LOCAL", "trace-commons-tenant/principal-ref", &value)?;
+    } else {
+        println!("{principal_ref}");
+    }
+    Ok(())
+}
+
+fn principal_storage_ref(value: &str) -> String {
+    format!("principal_{}", sha256_prefixed(value))
+}
+
+fn signed_claim_principal_ref(tenant_id: &str, actor_ref: &str) -> String {
+    let composed = format!("{}:{}", tenant_id.trim(), actor_ref.trim());
+    principal_storage_ref(&composed)
+}
+
+fn sha256_prefixed(value: &str) -> String {
+    let digest = Sha256::digest(value.as_bytes());
+    format!("sha256:{}", hex::encode(digest))
+}
+
+// --- helpers ---
+
+fn borrow_query<'a>(owned: &'a [(&'a str, String)]) -> Vec<(&'a str, &'a str)> {
+    owned.iter().map(|(k, v)| (*k, v.as_str())).collect()
+}
+
+fn trimmed(value: Option<&str>) -> Option<String> {
+    value
+        .map(str::trim)
+        .filter(|s| !s.is_empty())
+        .map(str::to_string)
+}
+
+fn require_rfc3339(label: &str, value: &str) -> Result<()> {
+    let trimmed_v = value.trim();
+    if trimmed_v.is_empty() {
+        anyhow::bail!("{label} must not be empty");
+    }
+    chrono::DateTime::parse_from_rfc3339(trimmed_v)
+        .map_err(|e| anyhow::anyhow!("{label} must be RFC3339: {e}"))?;
+    Ok(())
+}
+
+fn parse_metadata(values: &[String]) -> Result<std::collections::BTreeMap<String, String>> {
+    let mut metadata = std::collections::BTreeMap::new();
+    for value in values {
+        let Some((key, raw)) = value.split_once('=') else {
+            anyhow::bail!("--metadata values must use KEY=VALUE");
+        };
+        let key = key.trim();
+        if key.is_empty() {
+            anyhow::bail!("--metadata keys must not be empty");
+        }
+        metadata.insert(key.to_string(), raw.trim().to_string());
+    }
+    Ok(metadata)
+}
+
+fn emit_json(endpoint: &str, method: &str, path: &str, value: &Value) -> Result<()> {
+    let url = sanitized_url(endpoint, path);
+    oc_format::emit_json(&mut stdout(), method, &url, value)?;
+    Ok(())
+}
+
+// --- tests ---
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::atomic::{AtomicU64, Ordering};
+    use wiremock::matchers::{body_json, header, method, path as wm_path, query_param};
+    use wiremock::{Mock, MockServer, ResponseTemplate};
+
+    fn unique_bearer_env() -> String {
+        static SEQ: AtomicU64 = AtomicU64::new(0);
+        let n = SEQ.fetch_add(1, Ordering::Relaxed);
+        format!("TC_TENANT_TEST_BEARER_{n}")
+    }
+
+    struct EnvGuard {
+        name: String,
+    }
+    impl EnvGuard {
+        fn set(name: String, value: &str) -> Self {
+            unsafe { std::env::set_var(&name, value) };
+            EnvGuard { name }
+        }
+    }
+    impl Drop for EnvGuard {
+        fn drop(&mut self) {
+            unsafe { std::env::remove_var(&self.name) };
+        }
+    }
+
+    fn parse(args: &[&str]) -> Cli {
+        Cli::try_parse_from(
+            ["trace-commons-tenant", "--endpoint", "https://api.example"]
+                .iter()
+                .chain(args.iter())
+                .copied(),
+        )
+        .expect("parse cli")
+    }
+
+    fn parse_no_endpoint(args: &[&str]) -> Cli {
+        Cli::try_parse_from(["trace-commons-tenant"].iter().chain(args.iter()).copied())
+            .expect("parse cli")
+    }
+
+    #[test]
+    fn cli_parses_tenant_policy_get() {
+        let cli = parse(&["tenant-policy-get"]);
+        assert!(matches!(cli.command, TenantSubcommand::TenantPolicyGet));
+        assert_eq!(cli.bearer_token_env, DEFAULT_BEARER_ENV);
+    }
+
+    #[test]
+    fn cli_parses_tenant_policy_set() {
+        let cli = parse(&[
+            "tenant-policy-set",
+            "--policy-version",
+            "v1",
+            "--allowed-consent-scopes",
+            "benchmark-only,model-training",
+            "--allowed-uses",
+            "benchmark-generation,model-training",
+        ]);
+        match cli.command {
+            TenantSubcommand::TenantPolicySet(args) => {
+                assert_eq!(args.policy_version, "v1");
+                assert_eq!(args.allowed_consent_scopes.len(), 2);
+                assert_eq!(args.allowed_uses.len(), 2);
+            }
+            other => panic!("unexpected variant: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn cli_parses_tenant_access_grants_list() {
+        let cli = parse(&[
+            "tenant-access-grants-list",
+            "--limit",
+            "10",
+            "--status",
+            "active",
+            "--role",
+            "reviewer",
+            "--principal-ref",
+            "principal_xyz",
+        ]);
+        match cli.command {
+            TenantSubcommand::TenantAccessGrantsList(args) => {
+                assert_eq!(args.limit, Some(10));
+                assert_eq!(args.status, Some(TenantAccessGrantStatus::Active));
+                assert_eq!(args.role, Some(TenantAccessGrantRole::Reviewer));
+                assert_eq!(args.principal_ref.as_deref(), Some("principal_xyz"));
+            }
+            other => panic!("unexpected variant: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn cli_parses_tenant_principal_ref_with_token_env() {
+        // No --endpoint required for this subcommand.
+        let cli = parse_no_endpoint(&[
+            "tenant-principal-ref",
+            "--token-env",
+            "SOME_TOKEN_VAR",
+        ]);
+        match cli.command {
+            TenantSubcommand::TenantPrincipalRef(args) => {
+                assert_eq!(args.token_env.as_deref(), Some("SOME_TOKEN_VAR"));
+            }
+            other => panic!("unexpected variant: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn cli_parses_tenant_access_grant_create() {
+        let cli = parse(&[
+            "tenant-access-grant-create",
+            "--principal-ref",
+            "principal_xyz",
+            "--role",
+            "reviewer",
+            "--allowed-consent-scopes",
+            "benchmark-only",
+            "--allowed-uses",
+            "benchmark-generation",
+            "--reason",
+            "rotate",
+            "--metadata",
+            "issued_by=ops",
+        ]);
+        match cli.command {
+            TenantSubcommand::TenantAccessGrantCreate(args) => {
+                assert_eq!(args.role, TenantAccessGrantRole::Reviewer);
+                assert_eq!(args.metadata.len(), 1);
+            }
+            other => panic!("unexpected variant: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn cli_rejects_tenant_access_grant_create_missing_reason() {
+        let err = Cli::try_parse_from([
+            "trace-commons-tenant",
+            "--endpoint",
+            "https://api.example",
+            "tenant-access-grant-create",
+            "--principal-ref",
+            "p",
+            "--role",
+            "reviewer",
+        ])
+        .unwrap_err();
+        assert!(!err.to_string().is_empty());
+    }
+
+    #[test]
+    fn cli_parses_tenant_access_grant_revoke() {
+        let id = Uuid::new_v4();
+        let cli = parse(&[
+            "tenant-access-grant-revoke",
+            "--grant-id",
+            &id.to_string(),
+            "--reason",
+            "key compromise",
+        ]);
+        match cli.command {
+            TenantSubcommand::TenantAccessGrantRevoke(args) => {
+                assert_eq!(args.grant_id, id);
+                assert_eq!(args.reason, "key compromise");
+            }
+            other => panic!("unexpected variant: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn cli_parses_ranker_training_candidates() {
+        let cli = parse(&[
+            "ranker-training-candidates",
+            "--limit",
+            "5",
+            "--status",
+            "accepted",
+            "--privacy-risk",
+            "low",
+        ]);
+        match cli.command {
+            TenantSubcommand::RankerTrainingCandidates(args) => {
+                assert_eq!(args.limit, Some(5));
+                assert_eq!(args.status, Some(CorpusStatus::Accepted));
+            }
+            other => panic!("unexpected variant: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn cli_parses_ranker_training_pairs() {
+        let cli = parse(&["ranker-training-pairs", "--limit", "5"]);
+        assert!(matches!(cli.command, TenantSubcommand::RankerTrainingPairs(_)));
+    }
+
+    #[test]
+    fn cli_parses_audit_events() {
+        let cli = parse(&["audit-events", "--limit", "50"]);
+        match cli.command {
+            TenantSubcommand::AuditEvents(args) => assert_eq!(args.limit, Some(50)),
+            other => panic!("unexpected variant: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn cli_parses_list_traces() {
+        let cli = parse(&[
+            "list-traces",
+            "--purpose",
+            "review",
+            "--consent-scope",
+            "debugging-evaluation",
+            "--status",
+            "accepted",
+            "--limit",
+            "20",
+            "--coverage-tag",
+            "ops",
+            "--tool",
+            "shell",
+            "--privacy-risk",
+            "low",
+        ]);
+        match cli.command {
+            TenantSubcommand::ListTraces(args) => {
+                assert_eq!(args.consent_scope, Some(ConsentScope::DebuggingEvaluation));
+                assert_eq!(args.privacy_risk, Some(PrivacyRisk::Low));
+                assert_eq!(args.coverage_tag.as_deref(), Some("ops"));
+            }
+            other => panic!("unexpected variant: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn cli_parses_privacy_filter_canary_defaults() {
+        let cli = parse_no_endpoint(&["privacy-filter-canary"]);
+        match cli.command {
+            TenantSubcommand::PrivacyFilterCanary(args) => {
+                assert!(args.text.contains("Canary"));
+                assert_eq!(args.timeout_seconds, 10);
+            }
+            other => panic!("unexpected variant: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn cli_rejects_unknown_subcommand() {
+        let err = Cli::try_parse_from([
+            "trace-commons-tenant",
+            "--endpoint",
+            "https://api.example",
+            "bogus",
+        ])
+        .unwrap_err();
+        assert!(!err.to_string().is_empty());
+    }
+
+    #[test]
+    fn tenant_principal_ref_token_env_mode_derives_stable_hash() {
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "secret-token-abc");
+        let args = TenantPrincipalRefArgs {
+            token_env: Some(env.clone()),
+            signed_tenant_id: None,
+            signed_actor_ref: None,
+        };
+        tenant_principal_ref(&args, true).expect("derive works");
+        // Re-derive directly to confirm format.
+        let p = principal_storage_ref("secret-token-abc");
+        assert!(p.starts_with("principal_sha256:"));
+    }
+
+    #[test]
+    fn tenant_principal_ref_signed_claim_mode_derives() {
+        let args = TenantPrincipalRefArgs {
+            token_env: None,
+            signed_tenant_id: Some("tenant-1".into()),
+            signed_actor_ref: Some("actor-xyz".into()),
+        };
+        tenant_principal_ref(&args, false).expect("derive works");
+        let p = signed_claim_principal_ref("tenant-1", "actor-xyz");
+        assert!(p.starts_with("principal_sha256:"));
+    }
+
+    #[test]
+    fn tenant_principal_ref_rejects_both_modes() {
+        let args = TenantPrincipalRefArgs {
+            token_env: Some("X".into()),
+            signed_tenant_id: Some("t".into()),
+            signed_actor_ref: Some("a".into()),
+        };
+        let err = tenant_principal_ref(&args, false).unwrap_err();
+        assert!(err.to_string().contains("either"));
+    }
+
+    #[test]
+    fn tenant_principal_ref_rejects_neither_mode() {
+        let args = TenantPrincipalRefArgs {
+            token_env: None,
+            signed_tenant_id: None,
+            signed_actor_ref: None,
+        };
+        let err = tenant_principal_ref(&args, false).unwrap_err();
+        assert!(err.to_string().contains("either"));
+    }
+
+    #[test]
+    fn tenant_principal_ref_rejects_missing_actor_ref() {
+        let args = TenantPrincipalRefArgs {
+            token_env: None,
+            signed_tenant_id: Some("t".into()),
+            signed_actor_ref: None,
+        };
+        let err = tenant_principal_ref(&args, false).unwrap_err();
+        assert!(err.to_string().contains("signed-actor-ref"));
+    }
+
+    #[test]
+    fn parse_metadata_round_trips_pairs() {
+        let m = parse_metadata(&["k=v".to_string(), "a=b".to_string()]).unwrap();
+        assert_eq!(m.get("k").map(String::as_str), Some("v"));
+        assert_eq!(m.get("a").map(String::as_str), Some("b"));
+    }
+
+    #[test]
+    fn parse_metadata_rejects_missing_equals() {
+        let err = parse_metadata(&["nokey".to_string()]).unwrap_err();
+        assert!(err.to_string().contains("KEY=VALUE"));
+    }
+
+    #[test]
+    fn require_rfc3339_accepts_valid_and_rejects_garbage() {
+        require_rfc3339("--issued-at", "2026-05-19T00:00:00Z").unwrap();
+        let err = require_rfc3339("--issued-at", "yesterday").unwrap_err();
+        assert!(err.to_string().contains("RFC3339"));
+    }
+
+    #[tokio::test]
+    async fn tenant_policy_get_happy_path() {
+        let server = MockServer::start().await;
+        Mock::given(method("GET"))
+            .and(wm_path("/v1/admin/tenant-policy"))
+            .and(header("authorization", "Bearer tenant-secret"))
+            .respond_with(
+                ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                    "tenant_id": "t-1",
+                    "policy_version": "v1",
+                    "allowed_consent_scopes": ["benchmark_only"],
+                    "allowed_uses": ["benchmark_generation"],
+                })),
+            )
+            .expect(1)
+            .mount(&server)
+            .await;
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "tenant-secret");
+        let client = Client::builder(server.uri(), env).build().unwrap();
+        tenant_policy_get(&client, &server.uri(), true).await.unwrap();
+    }
+
+    #[tokio::test]
+    async fn tenant_policy_set_puts_body() {
+        let server = MockServer::start().await;
+        Mock::given(method("PUT"))
+            .and(wm_path("/v1/admin/tenant-policy"))
+            .and(body_json(serde_json::json!({
+                "policy_version": "v2",
+                "allowed_consent_scopes": ["benchmark_only", "model_training"],
+                "allowed_uses": ["benchmark_generation"],
+            })))
+            .respond_with(
+                ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                    "policy_version": "v2",
+                })),
+            )
+            .expect(1)
+            .mount(&server)
+            .await;
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "secret");
+        let client = Client::builder(server.uri(), env).build().unwrap();
+        tenant_policy_set(
+            &client,
+            &server.uri(),
+            TenantPolicySetArgs {
+                policy_version: "v2".into(),
+                allowed_consent_scopes: vec![
+                    ConsentScope::BenchmarkOnly,
+                    ConsentScope::ModelTraining,
+                ],
+                allowed_uses: vec![AllowedUse::BenchmarkGeneration],
+            },
+            true,
+        )
+        .await
+        .unwrap();
+    }
+
+    #[tokio::test]
+    async fn tenant_policy_set_rejects_empty_version() {
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "secret");
+        let client = Client::builder("https://api.example", env).build().unwrap();
+        let err = tenant_policy_set(
+            &client,
+            "https://api.example",
+            TenantPolicySetArgs {
+                policy_version: "  ".into(),
+                allowed_consent_scopes: vec![],
+                allowed_uses: vec![],
+            },
+            true,
+        )
+        .await
+        .unwrap_err();
+        assert!(err.to_string().contains("policy-version"));
+    }
+
+    #[tokio::test]
+    async fn tenant_access_grants_list_passes_query() {
+        let server = MockServer::start().await;
+        Mock::given(method("GET"))
+            .and(wm_path("/v1/admin/tenant-access-grants"))
+            .and(query_param("limit", "10"))
+            .and(query_param("status", "active"))
+            .and(query_param("role", "reviewer"))
+            .respond_with(
+                ResponseTemplate::new(200).set_body_json(serde_json::json!({ "items": [] })),
+            )
+            .expect(1)
+            .mount(&server)
+            .await;
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "secret");
+        let client = Client::builder(server.uri(), env).build().unwrap();
+        tenant_access_grants_list(
+            &client,
+            &server.uri(),
+            TenantAccessGrantsListArgs {
+                limit: Some(10),
+                status: Some(TenantAccessGrantStatus::Active),
+                role: Some(TenantAccessGrantRole::Reviewer),
+                principal_ref: None,
+            },
+            true,
+        )
+        .await
+        .unwrap();
+    }
+
+    #[tokio::test]
+    async fn tenant_access_grant_create_posts_body() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(wm_path("/v1/admin/tenant-access-grants"))
+            .respond_with(
+                ResponseTemplate::new(200).set_body_json(serde_json::json!({ "grant_id": "g-1" })),
+            )
+            .expect(1)
+            .mount(&server)
+            .await;
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "secret");
+        let client = Client::builder(server.uri(), env).build().unwrap();
+        tenant_access_grant_create(
+            &client,
+            &server.uri(),
+            TenantAccessGrantCreateArgs {
+                principal_ref: "principal_xyz".into(),
+                role: TenantAccessGrantRole::Reviewer,
+                grant_id: None,
+                allowed_consent_scopes: vec![],
+                allowed_uses: vec![],
+                issuer: None,
+                audience: None,
+                subject: None,
+                issued_at: None,
+                expires_at: None,
+                reason: "rotate".into(),
+                metadata: vec![],
+            },
+            true,
+        )
+        .await
+        .unwrap();
+    }
+
+    #[tokio::test]
+    async fn tenant_access_grant_create_rejects_bad_rfc3339() {
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "secret");
+        let client = Client::builder("https://api.example", env).build().unwrap();
+        let err = tenant_access_grant_create(
+            &client,
+            "https://api.example",
+            TenantAccessGrantCreateArgs {
+                principal_ref: "p".into(),
+                role: TenantAccessGrantRole::Reviewer,
+                grant_id: None,
+                allowed_consent_scopes: vec![],
+                allowed_uses: vec![],
+                issuer: None,
+                audience: None,
+                subject: None,
+                issued_at: Some("yesterday".into()),
+                expires_at: None,
+                reason: "rotate".into(),
+                metadata: vec![],
+            },
+            true,
+        )
+        .await
+        .unwrap_err();
+        assert!(err.to_string().contains("RFC3339"));
+    }
+
+    #[tokio::test]
+    async fn tenant_access_grant_revoke_posts_body() {
+        let server = MockServer::start().await;
+        let id = Uuid::new_v4();
+        Mock::given(method("POST"))
+            .and(wm_path(format!("/v1/admin/tenant-access-grants/{id}/revoke")))
+            .and(body_json(serde_json::json!({ "reason": "key compromise" })))
+            .respond_with(
+                ResponseTemplate::new(200).set_body_json(serde_json::json!({ "status": "revoked" })),
+            )
+            .expect(1)
+            .mount(&server)
+            .await;
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "secret");
+        let client = Client::builder(server.uri(), env).build().unwrap();
+        tenant_access_grant_revoke(
+            &client,
+            &server.uri(),
+            TenantAccessGrantRevokeArgs {
+                grant_id: id,
+                reason: "key compromise".into(),
+            },
+            true,
+        )
+        .await
+        .unwrap();
+    }
+
+    #[tokio::test]
+    async fn audit_events_happy_path() {
+        let server = MockServer::start().await;
+        Mock::given(method("GET"))
+            .and(wm_path("/v1/audit/events"))
+            .and(query_param("limit", "25"))
+            .respond_with(
+                ResponseTemplate::new(200).set_body_json(serde_json::json!({ "items": [] })),
+            )
+            .expect(1)
+            .mount(&server)
+            .await;
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "secret");
+        let client = Client::builder(server.uri(), env).build().unwrap();
+        audit_events(
+            &client,
+            &server.uri(),
+            AuditEventsArgs { limit: Some(25) },
+            true,
+        )
+        .await
+        .unwrap();
+    }
+
+    #[tokio::test]
+    async fn list_traces_passes_query() {
+        let server = MockServer::start().await;
+        Mock::given(method("GET"))
+            .and(wm_path("/v1/traces"))
+            .and(query_param("status", "accepted"))
+            .and(query_param("limit", "5"))
+            .respond_with(
+                ResponseTemplate::new(200).set_body_json(serde_json::json!({ "items": [] })),
+            )
+            .expect(1)
+            .mount(&server)
+            .await;
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "secret");
+        let client = Client::builder(server.uri(), env).build().unwrap();
+        list_traces(
+            &client,
+            &server.uri(),
+            ListTracesArgs {
+                purpose: None,
+                consent_scope: None,
+                status: Some(CorpusStatus::Accepted),
+                limit: Some(5),
+                coverage_tag: None,
+                tool: None,
+                privacy_risk: None,
+            },
+            true,
+        )
+        .await
+        .unwrap();
+    }
+
+    #[tokio::test]
+    async fn ranker_training_candidates_renders_envelope() {
+        let server = MockServer::start().await;
+        Mock::given(method("GET"))
+            .and(wm_path("/v1/ranker/training-candidates"))
+            .respond_with(
+                ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                    "candidates": [
+                        {"submission_id": "s-1", "ranker_score": 0.9}
+                    ]
+                })),
+            )
+            .expect(1)
+            .mount(&server)
+            .await;
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "secret");
+        let client = Client::builder(server.uri(), env).build().unwrap();
+        ranker_training_export(
+            &client,
+            &server.uri(),
+            RankerTrainingArgs {
+                purpose: None,
+                consent_scope: None,
+                status: None,
+                privacy_risk: None,
+                limit: None,
+                output: None,
+            },
+            "/v1/ranker/training-candidates",
+            "ranker training candidates",
+            "candidates",
+            true,
+        )
+        .await
+        .unwrap();
+    }
+}
diff --git a/crates/trace-commons-server/src/bin/trace-commons-worker.rs b/crates/trace-commons-server/src/bin/trace-commons-worker.rs
new file mode 100644
index 000000000..b208c8361
--- /dev/null
+++ b/crates/trace-commons-server/src/bin/trace-commons-worker.rs
@@ -0,0 +1,1681 @@
+//! `trace-commons-worker` — worker-audience operator CLI.
+//!
+//! Eight subcommands matching the worker-route endpoints on
+//! trace-commons-server. Each subcommand carries its own `--bearer-token-env`
+//! flag with a per-route default, because every worker route has its own
+//! bearer-token gate on the server. There is intentionally no top-level
+//! `--bearer-token-env`: an operator running e.g. `worker-retention-maintenance`
+//! must not be able to silently reuse the utility-credit token. All requests
+//! flow through the foundation `trace_commons_operator_client::Client`, which
+//! enforces the host allowlist and never logs bearer tokens.
+
+#[path = "operator_common/mod.rs"]
+mod operator_common;
+
+use std::io::{stdout, Write};
+use std::path::PathBuf;
+
+use anyhow::Result;
+use clap::{Parser, Subcommand, ValueEnum};
+use reqwest::Method;
+use serde_json::Value;
+use trace_commons_operator_client::{format as oc_format, host_allowlist::HostAllowlist, Client};
+use uuid::Uuid;
+
+use operator_common::{render_items, render_kv_fields, sanitized_url};
+
+// --- per-route bearer env defaults (one per worker route gate) ---
+const UTILITY_CREDIT_BEARER_ENV: &str = "TRACE_COMMONS_UTILITY_CREDIT_WORKER_BEARER";
+const RETENTION_WORKER_BEARER_ENV: &str = "TRACE_COMMONS_RETENTION_WORKER_BEARER";
+const VECTOR_WORKER_BEARER_ENV: &str = "TRACE_COMMONS_VECTOR_WORKER_BEARER";
+const BENCHMARK_WORKER_BEARER_ENV: &str = "TRACE_COMMONS_BENCHMARK_WORKER_BEARER";
+const EXPORT_WORKER_BEARER_ENV: &str = "TRACE_COMMONS_EXPORT_WORKER_BEARER";
+const RANKER_WORKER_BEARER_ENV: &str = "TRACE_COMMONS_RANKER_WORKER_BEARER";
+const PROCESS_EVALUATION_WORKER_BEARER_ENV: &str =
+    "TRACE_COMMONS_PROCESS_EVALUATION_WORKER_BEARER";
+
+#[derive(Debug, Parser)]
+#[command(
+    name = "trace-commons-worker",
+    about = "Worker-audience CLI for trace-commons-server.",
+    version
+)]
+pub(crate) struct Cli {
+    /// Hosted endpoint. Reads `TRACE_COMMONS_ENDPOINT` when unset on the CLI.
+    #[arg(long, env = "TRACE_COMMONS_ENDPOINT")]
+    pub endpoint: String,
+
+    /// Defense-in-depth host allowlist (CSV). Empty means permissive.
+    #[arg(long, env = "TRACE_COMMONS_ALLOWED_HOSTS")]
+    pub allowed_hosts: Option<String>,
+
+    /// Emit the server response as JSON (with a sanitized request envelope).
+    #[arg(long, global = true)]
+    pub json: bool,
+
+    #[command(subcommand)]
+    pub command: WorkerSubcommand,
+}
+
+#[derive(Debug, Subcommand)]
+pub(crate) enum WorkerSubcommand {
+    /// Append delayed utility-credit events through the worker route.
+    WorkerUtilityCredit(WorkerUtilityCreditArgs),
+    /// Run scoped central retention maintenance through the worker route.
+    WorkerRetentionMaintenance(WorkerRetentionMaintenanceArgs),
+    /// Index scoped vector metadata through the worker route.
+    WorkerVectorIndex(WorkerVectorIndexArgs),
+    /// Start benchmark conversion through the worker route.
+    WorkerBenchmarkConvert(WorkerBenchmarkConvertArgs),
+    /// Export an approved replay dataset slice through the worker route.
+    WorkerReplayDatasetExport(WorkerReplayDatasetExportArgs),
+    /// Export approved ranker training candidates through the worker route.
+    WorkerRankerTrainingCandidates(WorkerRankerTrainingArgs),
+    /// Export approved ranker training pairs through the worker route.
+    WorkerRankerTrainingPairs(WorkerRankerTrainingArgs),
+    /// Submit process-evaluation metadata through the worker route.
+    ProcessEvaluationSubmit(ProcessEvaluationSubmitArgs),
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct WorkerUtilityCreditArgs {
+    #[arg(long, value_enum)]
+    pub event_type: UtilityCreditEventType,
+    #[arg(long)]
+    pub credit_points_delta: f32,
+    #[arg(long)]
+    pub reason: String,
+    #[arg(long)]
+    pub external_ref: String,
+    #[arg(value_name = "SUBMISSION_ID", num_args = 1..)]
+    pub submission_ids: Vec<Uuid>,
+    #[arg(long, default_value = UTILITY_CREDIT_BEARER_ENV)]
+    pub bearer_token_env: String,
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct WorkerRetentionMaintenanceArgs {
+    #[arg(long)]
+    pub purpose: Option<String>,
+    #[arg(long)]
+    pub dry_run: bool,
+    #[arg(long)]
+    pub purge_expired_before: Option<String>,
+    #[arg(long)]
+    pub max_export_age_hours: Option<i64>,
+    /// Leave invalid export-cache files in place (default: prune).
+    #[arg(long)]
+    pub skip_export_cache_prune: bool,
+    #[arg(long, default_value = RETENTION_WORKER_BEARER_ENV)]
+    pub bearer_token_env: String,
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct WorkerVectorIndexArgs {
+    #[arg(long)]
+    pub purpose: Option<String>,
+    #[arg(long)]
+    pub dry_run: bool,
+    #[arg(long, default_value = VECTOR_WORKER_BEARER_ENV)]
+    pub bearer_token_env: String,
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct WorkerBenchmarkConvertArgs {
+    #[arg(long)]
+    pub purpose: String,
+    #[arg(long)]
+    pub limit: Option<usize>,
+    #[arg(long, value_enum)]
+    pub consent_scope: Option<ConsentScope>,
+    #[arg(long, value_enum)]
+    pub status: Option<CorpusStatus>,
+    #[arg(long, value_enum)]
+    pub privacy_risk: Option<PrivacyRisk>,
+    #[arg(long)]
+    pub external_ref: Option<String>,
+    #[arg(long, default_value = BENCHMARK_WORKER_BEARER_ENV)]
+    pub bearer_token_env: String,
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct WorkerReplayDatasetExportArgs {
+    #[arg(long)]
+    pub purpose: Option<String>,
+    #[arg(long, value_enum)]
+    pub consent_scope: Option<ConsentScope>,
+    #[arg(long, value_enum)]
+    pub status: Option<CorpusStatus>,
+    #[arg(long, value_enum)]
+    pub privacy_risk: Option<PrivacyRisk>,
+    #[arg(long)]
+    pub limit: Option<usize>,
+    /// If set, write the raw JSON response to this path.
+    #[arg(long)]
+    pub output: Option<PathBuf>,
+    #[arg(long, default_value = EXPORT_WORKER_BEARER_ENV)]
+    pub bearer_token_env: String,
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct WorkerRankerTrainingArgs {
+    #[arg(long)]
+    pub purpose: Option<String>,
+    #[arg(long, value_enum)]
+    pub consent_scope: Option<ConsentScope>,
+    #[arg(long, value_enum)]
+    pub status: Option<CorpusStatus>,
+    #[arg(long, value_enum)]
+    pub privacy_risk: Option<PrivacyRisk>,
+    #[arg(long)]
+    pub limit: Option<usize>,
+    /// If set, write the raw JSON response to this path.
+    #[arg(long)]
+    pub output: Option<PathBuf>,
+    #[arg(long, default_value = RANKER_WORKER_BEARER_ENV)]
+    pub bearer_token_env: String,
+}
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct ProcessEvaluationSubmitArgs {
+    #[arg(long)]
+    pub submission_id: Uuid,
+    #[arg(long)]
+    pub reason: String,
+    #[arg(long)]
+    pub evaluator_name: Option<String>,
+    #[arg(long)]
+    pub evaluator_version: String,
+    #[arg(long = "label")]
+    pub labels: Vec<String>,
+    #[arg(long, value_enum)]
+    pub tool_selection: Option<ProcessEvaluationRating>,
+    #[arg(long, value_enum)]
+    pub tool_argument_quality: Option<ProcessEvaluationRating>,
+    #[arg(long, value_enum)]
+    pub tool_ordering: Option<ProcessEvaluationRating>,
+    #[arg(long, value_enum)]
+    pub verification: Option<ProcessEvaluationRating>,
+    #[arg(long, value_enum)]
+    pub side_effect_safety: Option<ProcessEvaluationRating>,
+    #[arg(long)]
+    pub overall_score: Option<f32>,
+    #[arg(long)]
+    pub utility_credit_points_delta: Option<f32>,
+    #[arg(long)]
+    pub utility_external_ref: Option<String>,
+    #[arg(long, default_value = PROCESS_EVALUATION_WORKER_BEARER_ENV)]
+    pub bearer_token_env: String,
+}
+
+// --- value enums ---
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub(crate) enum UtilityCreditEventType {
+    BenchmarkConversion,
+    RegressionCatch,
+    TrainingUtility,
+    RankingUtility,
+    ReviewerBonus,
+    AbusePenalty,
+}
+
+impl UtilityCreditEventType {
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::BenchmarkConversion => "benchmark_conversion",
+            Self::RegressionCatch => "regression_catch",
+            Self::TrainingUtility => "training_utility",
+            Self::RankingUtility => "ranking_utility",
+            Self::ReviewerBonus => "reviewer_bonus",
+            Self::AbusePenalty => "abuse_penalty",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub(crate) enum PrivacyRisk {
+    Low,
+    Medium,
+    High,
+}
+
+impl PrivacyRisk {
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::Low => "low",
+            Self::Medium => "medium",
+            Self::High => "high",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub(crate) enum ConsentScope {
+    DebuggingEvaluation,
+    BenchmarkOnly,
+    RankingTraining,
+    ModelTraining,
+}
+
+impl ConsentScope {
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::DebuggingEvaluation => "debugging-evaluation",
+            Self::BenchmarkOnly => "benchmark-only",
+            Self::RankingTraining => "ranking-training",
+            Self::ModelTraining => "model-training",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub(crate) enum CorpusStatus {
+    Accepted,
+    Quarantined,
+    Rejected,
+    Revoked,
+    Expired,
+    Purged,
+}
+
+impl CorpusStatus {
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::Accepted => "accepted",
+            Self::Quarantined => "quarantined",
+            Self::Rejected => "rejected",
+            Self::Revoked => "revoked",
+            Self::Expired => "expired",
+            Self::Purged => "purged",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub(crate) enum ProcessEvaluationRating {
+    Good,
+    Acceptable,
+    Poor,
+    Failing,
+}
+
+impl ProcessEvaluationRating {
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::Good => "good",
+            Self::Acceptable => "acceptable",
+            Self::Poor => "poor",
+            Self::Failing => "failing",
+        }
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let cli = Cli::parse();
+    dispatch(cli).await
+}
+
+/// Return the per-subcommand bearer-env name so the dispatcher can build the
+/// right `Client`. Each worker route has its own gate, so we plumb the env
+/// name from the matched subcommand variant rather than from a shared
+/// top-level flag.
+fn bearer_env(cmd: &WorkerSubcommand) -> &str {
+    match cmd {
+        WorkerSubcommand::WorkerUtilityCredit(a) => &a.bearer_token_env,
+        WorkerSubcommand::WorkerRetentionMaintenance(a) => &a.bearer_token_env,
+        WorkerSubcommand::WorkerVectorIndex(a) => &a.bearer_token_env,
+        WorkerSubcommand::WorkerBenchmarkConvert(a) => &a.bearer_token_env,
+        WorkerSubcommand::WorkerReplayDatasetExport(a) => &a.bearer_token_env,
+        WorkerSubcommand::WorkerRankerTrainingCandidates(a) => &a.bearer_token_env,
+        WorkerSubcommand::WorkerRankerTrainingPairs(a) => &a.bearer_token_env,
+        WorkerSubcommand::ProcessEvaluationSubmit(a) => &a.bearer_token_env,
+    }
+}
+
+fn build_client(endpoint: &str, bearer_token_env: &str, allowed_hosts: Option<&str>) -> Result<Client> {
+    let mut builder = Client::builder(endpoint, bearer_token_env);
+    if let Some(csv) = allowed_hosts {
+        builder = builder.host_allowlist(HostAllowlist::from_csv(csv));
+    }
+    Ok(builder.build()?)
+}
+
+async fn dispatch(cli: Cli) -> Result<()> {
+    let bearer = bearer_env(&cli.command).to_string();
+    let client = build_client(&cli.endpoint, &bearer, cli.allowed_hosts.as_deref())?;
+    let endpoint = cli.endpoint;
+    let json = cli.json;
+    match cli.command {
+        WorkerSubcommand::WorkerUtilityCredit(args) => {
+            worker_utility_credit(&client, &endpoint, args, json).await
+        }
+        WorkerSubcommand::WorkerRetentionMaintenance(args) => {
+            worker_retention_maintenance(&client, &endpoint, args, json).await
+        }
+        WorkerSubcommand::WorkerVectorIndex(args) => {
+            worker_vector_index(&client, &endpoint, args, json).await
+        }
+        WorkerSubcommand::WorkerBenchmarkConvert(args) => {
+            worker_benchmark_convert(&client, &endpoint, args, json).await
+        }
+        WorkerSubcommand::WorkerReplayDatasetExport(args) => {
+            worker_replay_dataset_export(&client, &endpoint, args, json).await
+        }
+        WorkerSubcommand::WorkerRankerTrainingCandidates(args) => {
+            worker_ranker_training_export(
+                &client,
+                &endpoint,
+                args,
+                "/v1/workers/ranker/training-candidates",
+                "ranker training candidates",
+                "candidates",
+                json,
+            )
+            .await
+        }
+        WorkerSubcommand::WorkerRankerTrainingPairs(args) => {
+            worker_ranker_training_export(
+                &client,
+                &endpoint,
+                args,
+                "/v1/workers/ranker/training-pairs",
+                "ranker training pairs",
+                "pairs",
+                json,
+            )
+            .await
+        }
+        WorkerSubcommand::ProcessEvaluationSubmit(args) => {
+            process_evaluation_submit(&client, &endpoint, args, json).await
+        }
+    }
+}
+
+// --- handlers ---
+
+async fn worker_utility_credit(
+    client: &Client,
+    endpoint: &str,
+    args: WorkerUtilityCreditArgs,
+    json: bool,
+) -> Result<()> {
+    if args.submission_ids.is_empty() {
+        anyhow::bail!("at least one SUBMISSION_ID positional is required");
+    }
+    let reason = args.reason.trim();
+    if reason.is_empty() {
+        anyhow::bail!("--reason must not be empty");
+    }
+    let external_ref = args.external_ref.trim();
+    if external_ref.is_empty() {
+        anyhow::bail!("--external-ref must not be empty");
+    }
+    let path = "/v1/workers/utility-credit";
+    let body = serde_json::json!({
+        "event_type": args.event_type.as_str(),
+        "credit_points_delta": args.credit_points_delta,
+        "reason": reason,
+        "external_ref": external_ref,
+        "submission_ids": args.submission_ids,
+    });
+    let value: Value = client
+        .call_json::<Value, Value>(Method::POST, path, &[], Some(&body))
+        .await?;
+    if json {
+        emit_json(endpoint, "POST", path, &value)?;
+    } else {
+        let mut out = stdout();
+        writeln!(out, "Trace Commons utility credit worker complete.")?;
+        render_kv_fields(
+            &mut out,
+            &value,
+            &[
+                ("  appended", "appended_count"),
+                ("  skipped existing", "skipped_existing_count"),
+            ],
+        )?;
+    }
+    Ok(())
+}
+
+async fn worker_retention_maintenance(
+    client: &Client,
+    endpoint: &str,
+    args: WorkerRetentionMaintenanceArgs,
+    json: bool,
+) -> Result<()> {
+    let path = "/v1/workers/retention-maintenance";
+    let mut body = serde_json::json!({ "dry_run": args.dry_run });
+    if let Some(purpose) = args.purpose {
+        let trimmed = purpose.trim();
+        if trimmed.is_empty() {
+            anyhow::bail!("--purpose must not be empty");
+        }
+        body["purpose"] = Value::String(trimmed.to_string());
+    }
+    if args.skip_export_cache_prune {
+        body["prune_export_cache"] = Value::Bool(false);
+    }
+    if let Some(hours) = args.max_export_age_hours {
+        body["max_export_age_hours"] = Value::Number(hours.into());
+    }
+    if let Some(before) = args.purge_expired_before {
+        body["purge_expired_before"] = Value::String(before);
+    }
+    let value: Value = client
+        .call_json::<Value, Value>(Method::POST, path, &[], Some(&body))
+        .await?;
+    if json {
+        emit_json(endpoint, "POST", path, &value)?;
+    } else {
+        let mut out = stdout();
+        writeln!(out, "Trace Commons retention maintenance requested.")?;
+        render_kv_fields(
+            &mut out,
+            &value,
+            &[
+                ("  audit event id", "audit_event_id"),
+                ("  purpose", "purpose"),
+                ("  dry run", "dry_run"),
+                ("  records marked revoked", "records_marked_revoked"),
+                ("  records marked expired", "records_marked_expired"),
+                ("  records marked purged", "records_marked_purged"),
+                ("  export cache files pruned", "export_cache_files_pruned"),
+                ("  export provenance invalidated", "export_provenance_invalidated"),
+                ("  benchmark artifacts invalidated", "benchmark_artifacts_invalidated"),
+            ],
+        )?;
+    }
+    Ok(())
+}
+
+async fn worker_vector_index(
+    client: &Client,
+    endpoint: &str,
+    args: WorkerVectorIndexArgs,
+    json: bool,
+) -> Result<()> {
+    let path = "/v1/workers/vector-index";
+    let mut body = serde_json::json!({ "dry_run": args.dry_run });
+    if let Some(purpose) = args.purpose {
+        let trimmed = purpose.trim();
+        if trimmed.is_empty() {
+            anyhow::bail!("--purpose must not be empty");
+        }
+        body["purpose"] = Value::String(trimmed.to_string());
+    }
+    let value: Value = client
+        .call_json::<Value, Value>(Method::POST, path, &[], Some(&body))
+        .await?;
+    if json {
+        emit_json(endpoint, "POST", path, &value)?;
+    } else {
+        let mut out = stdout();
+        writeln!(out, "Trace Commons vector index requested.")?;
+        render_kv_fields(
+            &mut out,
+            &value,
+            &[
+                ("  audit event id", "audit_event_id"),
+                ("  purpose", "purpose"),
+                ("  dry run", "dry_run"),
+                ("  vectors indexed", "vector_entries_indexed"),
+            ],
+        )?;
+    }
+    Ok(())
+}
+
+async fn worker_benchmark_convert(
+    client: &Client,
+    endpoint: &str,
+    args: WorkerBenchmarkConvertArgs,
+    json: bool,
+) -> Result<()> {
+    let trimmed = args.purpose.trim();
+    if trimmed.is_empty() {
+        anyhow::bail!("--purpose must be non-empty");
+    }
+    let path = "/v1/workers/benchmark-convert";
+    let mut body = serde_json::json!({ "purpose": trimmed });
+    if let Some(limit) = args.limit {
+        body["limit"] = serde_json::json!(limit);
+    }
+    if let Some(scope) = args.consent_scope {
+        body["consent_scope"] = Value::String(scope.as_str().to_string());
+    }
+    if let Some(status) = args.status {
+        body["status"] = Value::String(status.as_str().to_string());
+    }
+    if let Some(risk) = args.privacy_risk {
+        body["privacy_risk"] = Value::String(risk.as_str().to_string());
+    }
+    if let Some(external_ref) = args.external_ref {
+        body["external_ref"] = Value::String(external_ref);
+    }
+    let value: Value = client
+        .call_json::<Value, Value>(Method::POST, path, &[], Some(&body))
+        .await?;
+    if json {
+        emit_json(endpoint, "POST", path, &value)?;
+    } else {
+        let mut out = stdout();
+        writeln!(out, "Trace Commons benchmark conversion (worker) requested.")?;
+        render_kv_fields(
+            &mut out,
+            &value,
+            &[
+                ("  conversion id", "conversion_id"),
+                ("  audit event id", "audit_event_id"),
+                ("  item count", "item_count"),
+                ("  purpose", "purpose"),
+            ],
+        )?;
+    }
+    Ok(())
+}
+
+async fn worker_replay_dataset_export(
+    client: &Client,
+    endpoint: &str,
+    args: WorkerReplayDatasetExportArgs,
+    json: bool,
+) -> Result<()> {
+    let path = "/v1/workers/replay-export";
+    let mut owned: Vec<(&str, String)> = Vec::new();
+    if let Some(limit) = args.limit {
+        owned.push(("limit", limit.to_string()));
+    }
+    if let Some(purpose) = args.purpose {
+        let trimmed = purpose.trim();
+        if trimmed.is_empty() {
+            anyhow::bail!("--purpose must be non-empty");
+        }
+        owned.push(("purpose", trimmed.to_string()));
+    }
+    if let Some(scope) = args.consent_scope {
+        owned.push(("consent_scope", scope.as_str().to_string()));
+    }
+    if let Some(status) = args.status {
+        owned.push(("status", status.as_str().to_string()));
+    }
+    if let Some(risk) = args.privacy_risk {
+        owned.push(("privacy_risk", risk.as_str().to_string()));
+    }
+    let query = borrow_query(&owned);
+    let raw = client.call_raw::<()>(Method::GET, path, &query, None).await?;
+    let value: Value = serde_json::from_str(&raw).unwrap_or(Value::Null);
+
+    if let Some(output) = args.output.as_ref() {
+        let pretty = if value.is_null() {
+            raw.clone()
+        } else {
+            serde_json::to_string_pretty(&value)?
+        };
+        std::fs::write(output, pretty).map_err(|e| {
+            anyhow::anyhow!(
+                "failed to write replay dataset export {}: {}",
+                output.display(),
+                e
+            )
+        })?;
+        if json {
+            emit_json(endpoint, "GET", path, &value)?;
+        } else {
+            let mut out = stdout();
+            writeln!(
+                out,
+                "Wrote central replay dataset export to {}",
+                output.display()
+            )?;
+            render_kv_fields(
+                &mut out,
+                &value,
+                &[
+                    ("  export id", "export_id"),
+                    ("  manifest id", "manifest_id"),
+                    ("  audit event id", "audit_event_id"),
+                    ("  item count", "item_count"),
+                ],
+            )?;
+        }
+        return Ok(());
+    }
+    emit_json(endpoint, "GET", path, &value)
+}
+
+#[allow(clippy::too_many_arguments)]
+async fn worker_ranker_training_export(
+    client: &Client,
+    endpoint: &str,
+    args: WorkerRankerTrainingArgs,
+    path: &str,
+    output_label: &str,
+    item_field: &str,
+    json: bool,
+) -> Result<()> {
+    let mut owned: Vec<(&str, String)> = Vec::new();
+    if let Some(limit) = args.limit {
+        owned.push(("limit", limit.to_string()));
+    }
+    if let Some(purpose) = args.purpose {
+        let trimmed = purpose.trim();
+        if trimmed.is_empty() {
+            anyhow::bail!("--purpose must be non-empty");
+        }
+        owned.push(("purpose", trimmed.to_string()));
+    }
+    if let Some(scope) = args.consent_scope {
+        owned.push(("consent_scope", scope.as_str().to_string()));
+    }
+    if let Some(status) = args.status {
+        owned.push(("status", status.as_str().to_string()));
+    }
+    if let Some(risk) = args.privacy_risk {
+        owned.push(("privacy_risk", risk.as_str().to_string()));
+    }
+    let query = borrow_query(&owned);
+    let raw = client.call_raw::<()>(Method::GET, path, &query, None).await?;
+    let value: Value = serde_json::from_str(&raw).unwrap_or(Value::Null);
+
+    if let Some(output) = args.output.as_ref() {
+        let pretty = if value.is_null() {
+            raw.clone()
+        } else {
+            serde_json::to_string_pretty(&value)?
+        };
+        std::fs::write(output, pretty).map_err(|e| {
+            anyhow::anyhow!(
+                "failed to write ranker training export {}: {}",
+                output.display(),
+                e
+            )
+        })?;
+        if json {
+            emit_json(endpoint, "GET", path, &value)?;
+        } else {
+            let mut out = stdout();
+            writeln!(
+                out,
+                "Wrote central {} export to {}",
+                output_label,
+                output.display()
+            )?;
+            render_kv_fields(
+                &mut out,
+                &value,
+                &[
+                    ("  export id", "export_id"),
+                    ("  audit event id", "audit_event_id"),
+                    ("  purpose", "purpose"),
+                    ("  item count", "item_count"),
+                ],
+            )?;
+        }
+        return Ok(());
+    }
+
+    if json {
+        emit_json(endpoint, "GET", path, &value)
+    } else {
+        let items_value = value
+            .get(item_field)
+            .cloned()
+            .unwrap_or(Value::Null);
+        let envelope = serde_json::json!({ "items": items_value });
+        render_items(
+            &mut stdout(),
+            &format!("Central {output_label}"),
+            &envelope,
+            &[
+                "submission_id",
+                "trace_id",
+                "ranker_score",
+                "preferred_submission_id",
+                "rejected_submission_id",
+                "reason",
+            ],
+        )?;
+        Ok(())
+    }
+}
+
+async fn process_evaluation_submit(
+    client: &Client,
+    endpoint: &str,
+    args: ProcessEvaluationSubmitArgs,
+    json: bool,
+) -> Result<()> {
+    let reason = args.reason.trim();
+    if reason.is_empty() {
+        anyhow::bail!("--reason must not be empty");
+    }
+    let evaluator_version = args.evaluator_version.trim();
+    if evaluator_version.is_empty() {
+        anyhow::bail!("--evaluator-version must not be empty");
+    }
+    if let Some(overall_score) = args.overall_score {
+        if !(0.0..=1.0).contains(&overall_score) {
+            anyhow::bail!("--overall-score must be between 0.0 and 1.0");
+        }
+    }
+    let utility_external_ref = if let Some(delta) = args.utility_credit_points_delta {
+        if !delta.is_finite() || delta.abs() > 100.0 {
+            anyhow::bail!("--utility-credit-points-delta must be finite with abs <= 100.0");
+        }
+        let external_ref = args
+            .utility_external_ref
+            .as_deref()
+            .map(str::trim)
+            .filter(|s| !s.is_empty())
+            .ok_or_else(|| {
+                anyhow::anyhow!(
+                    "--utility-external-ref must be non-empty when --utility-credit-points-delta is set"
+                )
+            })?;
+        Some(external_ref.to_string())
+    } else {
+        if args
+            .utility_external_ref
+            .as_deref()
+            .is_some_and(|s| !s.trim().is_empty())
+        {
+            anyhow::bail!("--utility-external-ref requires --utility-credit-points-delta");
+        }
+        None
+    };
+
+    let labels: Vec<String> = args
+        .labels
+        .iter()
+        .map(|s| s.trim().to_string())
+        .filter(|s| !s.is_empty())
+        .collect();
+    let mut process_evaluation = serde_json::json!({
+        "evaluator_version": evaluator_version,
+        "labels": labels,
+    });
+    if let Some(name) = args.evaluator_name.as_ref() {
+        let trimmed = name.trim();
+        if !trimmed.is_empty() {
+            process_evaluation["evaluator_name"] = Value::String(trimmed.to_string());
+        }
+    }
+    if let Some(v) = args.tool_selection {
+        process_evaluation["tool_selection"] = Value::String(v.as_str().to_string());
+    }
+    if let Some(v) = args.tool_argument_quality {
+        process_evaluation["tool_argument_quality"] = Value::String(v.as_str().to_string());
+    }
+    if let Some(v) = args.tool_ordering {
+        process_evaluation["tool_ordering"] = Value::String(v.as_str().to_string());
+    }
+    if let Some(v) = args.verification {
+        process_evaluation["verification"] = Value::String(v.as_str().to_string());
+    }
+    if let Some(v) = args.side_effect_safety {
+        process_evaluation["side_effect_safety"] = Value::String(v.as_str().to_string());
+    }
+    if let Some(score) = args.overall_score {
+        process_evaluation["overall_score"] = serde_json::json!(score);
+    }
+
+    let mut body = serde_json::json!({
+        "submission_id": args.submission_id,
+        "process_evaluation": process_evaluation,
+        "reason": reason,
+    });
+    if let (Some(delta), Some(external_ref)) =
+        (args.utility_credit_points_delta, utility_external_ref)
+    {
+        body["utility_credit_points_delta"] = serde_json::json!(delta);
+        body["utility_external_ref"] = Value::String(external_ref);
+    }
+
+    let path = "/v1/workers/process-evaluation";
+    let value: Value = client
+        .call_json::<Value, Value>(Method::POST, path, &[], Some(&body))
+        .await?;
+    if json {
+        emit_json(endpoint, "POST", path, &value)?;
+    } else {
+        let mut out = stdout();
+        writeln!(
+            out,
+            "Trace Commons process evaluation submitted for {}.",
+            args.submission_id
+        )?;
+        render_kv_fields(
+            &mut out,
+            &value,
+            &[
+                ("  tenant", "tenant_id"),
+                ("  tenant storage ref", "tenant_storage_ref"),
+                ("  trace id", "trace_id"),
+                ("  status", "status"),
+                ("  process eval value", "process_eval_value"),
+                ("  review scorecard", "review_scorecard"),
+                ("  output object ref", "output_object_ref_id"),
+                (
+                    "  utility credit appended",
+                    "utility_credit_appended_count",
+                ),
+                (
+                    "  utility credit skipped existing",
+                    "utility_credit_skipped_existing_count",
+                ),
+            ],
+        )?;
+    }
+    Ok(())
+}
+
+// --- helpers ---
+
+fn borrow_query<'a>(owned: &'a [(&'a str, String)]) -> Vec<(&'a str, &'a str)> {
+    owned.iter().map(|(k, v)| (*k, v.as_str())).collect()
+}
+
+fn emit_json(endpoint: &str, method: &str, path: &str, value: &Value) -> Result<()> {
+    let url = sanitized_url(endpoint, path);
+    oc_format::emit_json(&mut stdout(), method, &url, value)?;
+    Ok(())
+}
+
+// --- tests ---
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::atomic::{AtomicU64, Ordering};
+    use wiremock::matchers::{body_json, header, method, path as wm_path};
+    use wiremock::{Mock, MockServer, ResponseTemplate};
+
+    fn unique_bearer_env() -> String {
+        static SEQ: AtomicU64 = AtomicU64::new(0);
+        let n = SEQ.fetch_add(1, Ordering::Relaxed);
+        format!("TC_WORKER_TEST_BEARER_{n}")
+    }
+
+    struct EnvGuard {
+        name: String,
+    }
+    impl EnvGuard {
+        fn set(name: String, value: &str) -> Self {
+            unsafe { std::env::set_var(&name, value) };
+            EnvGuard { name }
+        }
+    }
+    impl Drop for EnvGuard {
+        fn drop(&mut self) {
+            unsafe { std::env::remove_var(&self.name) };
+        }
+    }
+
+    fn parse(args: &[&str]) -> Cli {
+        Cli::try_parse_from(
+            ["trace-commons-worker", "--endpoint", "https://api.example"]
+                .iter()
+                .chain(args.iter())
+                .copied(),
+        )
+        .expect("parse cli")
+    }
+
+    #[test]
+    fn cli_parses_worker_utility_credit_minimal() {
+        let sub = Uuid::new_v4().to_string();
+        let cli = parse(&[
+            "worker-utility-credit",
+            "--event-type",
+            "training-utility",
+            "--credit-points-delta",
+            "1.5",
+            "--reason",
+            "delayed training utility",
+            "--external-ref",
+            "job-1",
+            &sub,
+        ]);
+        match cli.command {
+            WorkerSubcommand::WorkerUtilityCredit(args) => {
+                assert_eq!(args.event_type, UtilityCreditEventType::TrainingUtility);
+                assert_eq!(args.credit_points_delta, 1.5);
+                assert_eq!(args.submission_ids.len(), 1);
+                assert_eq!(args.bearer_token_env, UTILITY_CREDIT_BEARER_ENV);
+            }
+            other => panic!("unexpected variant: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn cli_parses_worker_utility_credit_multiple_submissions() {
+        let s1 = Uuid::new_v4().to_string();
+        let s2 = Uuid::new_v4().to_string();
+        let cli = parse(&[
+            "worker-utility-credit",
+            "--event-type",
+            "ranking-utility",
+            "--credit-points-delta",
+            "0.5",
+            "--reason",
+            "x",
+            "--external-ref",
+            "y",
+            &s1,
+            &s2,
+        ]);
+        match cli.command {
+            WorkerSubcommand::WorkerUtilityCredit(args) => {
+                assert_eq!(args.submission_ids.len(), 2);
+            }
+            other => panic!("unexpected variant: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn cli_rejects_worker_utility_credit_invalid_event() {
+        let err = Cli::try_parse_from([
+            "trace-commons-worker",
+            "--endpoint",
+            "https://api.example",
+            "worker-utility-credit",
+            "--event-type",
+            "bogus",
+            "--credit-points-delta",
+            "0.0",
+            "--reason",
+            "x",
+            "--external-ref",
+            "y",
+            &Uuid::new_v4().to_string(),
+        ])
+        .unwrap_err();
+        assert!(!err.to_string().is_empty());
+    }
+
+    #[test]
+    fn cli_parses_worker_retention_maintenance_full() {
+        let cli = parse(&[
+            "worker-retention-maintenance",
+            "--purpose",
+            "weekly",
+            "--dry-run",
+            "--max-export-age-hours",
+            "48",
+            "--skip-export-cache-prune",
+        ]);
+        match cli.command {
+            WorkerSubcommand::WorkerRetentionMaintenance(args) => {
+                assert_eq!(args.purpose.as_deref(), Some("weekly"));
+                assert!(args.dry_run);
+                assert_eq!(args.max_export_age_hours, Some(48));
+                assert!(args.skip_export_cache_prune);
+                assert_eq!(args.bearer_token_env, RETENTION_WORKER_BEARER_ENV);
+            }
+            other => panic!("unexpected variant: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn cli_parses_worker_vector_index() {
+        let cli = parse(&["worker-vector-index", "--purpose", "p", "--dry-run"]);
+        match cli.command {
+            WorkerSubcommand::WorkerVectorIndex(args) => {
+                assert_eq!(args.bearer_token_env, VECTOR_WORKER_BEARER_ENV);
+                assert!(args.dry_run);
+            }
+            other => panic!("unexpected variant: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn cli_parses_worker_benchmark_convert() {
+        let cli = parse(&[
+            "worker-benchmark-convert",
+            "--purpose",
+            "weekly",
+            "--limit",
+            "10",
+            "--consent-scope",
+            "benchmark-only",
+            "--status",
+            "accepted",
+            "--privacy-risk",
+            "low",
+        ]);
+        match cli.command {
+            WorkerSubcommand::WorkerBenchmarkConvert(args) => {
+                assert_eq!(args.bearer_token_env, BENCHMARK_WORKER_BEARER_ENV);
+                assert_eq!(args.consent_scope, Some(ConsentScope::BenchmarkOnly));
+                assert_eq!(args.status, Some(CorpusStatus::Accepted));
+                assert_eq!(args.privacy_risk, Some(PrivacyRisk::Low));
+            }
+            other => panic!("unexpected variant: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn cli_rejects_worker_benchmark_convert_missing_purpose() {
+        let err = Cli::try_parse_from([
+            "trace-commons-worker",
+            "--endpoint",
+            "https://api.example",
+            "worker-benchmark-convert",
+        ])
+        .unwrap_err();
+        assert!(!err.to_string().is_empty());
+    }
+
+    #[test]
+    fn cli_parses_worker_replay_dataset_export() {
+        let cli = parse(&[
+            "worker-replay-dataset-export",
+            "--limit",
+            "50",
+            "--consent-scope",
+            "model-training",
+            "--privacy-risk",
+            "medium",
+            "--output",
+            "/tmp/replay.json",
+        ]);
+        match cli.command {
+            WorkerSubcommand::WorkerReplayDatasetExport(args) => {
+                assert_eq!(args.bearer_token_env, EXPORT_WORKER_BEARER_ENV);
+                assert_eq!(args.limit, Some(50));
+                assert!(args.output.is_some());
+            }
+            other => panic!("unexpected variant: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn cli_parses_worker_ranker_training_candidates() {
+        let cli = parse(&[
+            "worker-ranker-training-candidates",
+            "--limit",
+            "10",
+            "--status",
+            "accepted",
+        ]);
+        match cli.command {
+            WorkerSubcommand::WorkerRankerTrainingCandidates(args) => {
+                assert_eq!(args.bearer_token_env, RANKER_WORKER_BEARER_ENV);
+            }
+            other => panic!("unexpected variant: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn cli_parses_worker_ranker_training_pairs() {
+        let cli = parse(&["worker-ranker-training-pairs", "--limit", "10"]);
+        match cli.command {
+            WorkerSubcommand::WorkerRankerTrainingPairs(args) => {
+                assert_eq!(args.bearer_token_env, RANKER_WORKER_BEARER_ENV);
+            }
+            other => panic!("unexpected variant: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn cli_parses_process_evaluation_submit_minimal() {
+        let sub = Uuid::new_v4().to_string();
+        let cli = parse(&[
+            "process-evaluation-submit",
+            "--submission-id",
+            &sub,
+            "--reason",
+            "manual review",
+            "--evaluator-version",
+            "v1",
+        ]);
+        match cli.command {
+            WorkerSubcommand::ProcessEvaluationSubmit(args) => {
+                assert_eq!(args.evaluator_version, "v1");
+                assert_eq!(args.bearer_token_env, PROCESS_EVALUATION_WORKER_BEARER_ENV);
+            }
+            other => panic!("unexpected variant: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn cli_parses_process_evaluation_submit_full() {
+        let sub = Uuid::new_v4().to_string();
+        let cli = parse(&[
+            "process-evaluation-submit",
+            "--submission-id",
+            &sub,
+            "--reason",
+            "manual review",
+            "--evaluator-version",
+            "v1",
+            "--evaluator-name",
+            "frontier-lab",
+            "--label",
+            "good-trace",
+            "--label",
+            "tools-correct",
+            "--tool-selection",
+            "good",
+            "--tool-argument-quality",
+            "acceptable",
+            "--tool-ordering",
+            "poor",
+            "--verification",
+            "good",
+            "--side-effect-safety",
+            "good",
+            "--overall-score",
+            "0.85",
+            "--utility-credit-points-delta",
+            "0.3",
+            "--utility-external-ref",
+            "job-x",
+        ]);
+        match cli.command {
+            WorkerSubcommand::ProcessEvaluationSubmit(args) => {
+                assert_eq!(args.labels.len(), 2);
+                assert_eq!(args.overall_score, Some(0.85));
+                assert_eq!(args.utility_credit_points_delta, Some(0.3));
+            }
+            other => panic!("unexpected variant: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn cli_rejects_unknown_subcommand() {
+        let err = Cli::try_parse_from([
+            "trace-commons-worker",
+            "--endpoint",
+            "https://api.example",
+            "bogus-subcommand",
+        ])
+        .unwrap_err();
+        assert!(!err.to_string().is_empty());
+    }
+
+    #[test]
+    fn bearer_env_resolves_per_subcommand() {
+        // Build one CLI per subcommand and confirm `bearer_env()` returns the
+        // correct per-route default for each. This protects against future
+        // edits that accidentally collapse them onto a shared top-level flag.
+        let sub = Uuid::new_v4().to_string();
+        let cases: Vec<(&str, Vec<&str>, &str)> = vec![
+            (
+                "worker-utility-credit",
+                vec![
+                    "worker-utility-credit",
+                    "--event-type",
+                    "training-utility",
+                    "--credit-points-delta",
+                    "1.0",
+                    "--reason",
+                    "r",
+                    "--external-ref",
+                    "x",
+                    &sub,
+                ],
+                UTILITY_CREDIT_BEARER_ENV,
+            ),
+            (
+                "worker-retention-maintenance",
+                vec!["worker-retention-maintenance"],
+                RETENTION_WORKER_BEARER_ENV,
+            ),
+            (
+                "worker-vector-index",
+                vec!["worker-vector-index"],
+                VECTOR_WORKER_BEARER_ENV,
+            ),
+            (
+                "worker-benchmark-convert",
+                vec!["worker-benchmark-convert", "--purpose", "p"],
+                BENCHMARK_WORKER_BEARER_ENV,
+            ),
+            (
+                "worker-replay-dataset-export",
+                vec!["worker-replay-dataset-export"],
+                EXPORT_WORKER_BEARER_ENV,
+            ),
+            (
+                "worker-ranker-training-candidates",
+                vec!["worker-ranker-training-candidates"],
+                RANKER_WORKER_BEARER_ENV,
+            ),
+            (
+                "worker-ranker-training-pairs",
+                vec!["worker-ranker-training-pairs"],
+                RANKER_WORKER_BEARER_ENV,
+            ),
+            (
+                "process-evaluation-submit",
+                vec![
+                    "process-evaluation-submit",
+                    "--submission-id",
+                    &sub,
+                    "--reason",
+                    "r",
+                    "--evaluator-version",
+                    "v1",
+                ],
+                PROCESS_EVALUATION_WORKER_BEARER_ENV,
+            ),
+        ];
+        for (label, args, expected_env) in cases {
+            let cli = parse(&args);
+            assert_eq!(
+                bearer_env(&cli.command),
+                expected_env,
+                "subcommand {label} resolved wrong bearer env"
+            );
+        }
+    }
+
+    #[tokio::test]
+    async fn worker_per_route_bearer_resolution_uses_distinct_envs() {
+        // Each worker subcommand pulls its bearer from its OWN env. We set 8
+        // distinct env vars to distinct tokens and confirm each handler sends
+        // the right one to the mock server.
+        let server = MockServer::start().await;
+
+        let envs = [
+            unique_bearer_env(),
+            unique_bearer_env(),
+            unique_bearer_env(),
+            unique_bearer_env(),
+            unique_bearer_env(),
+            unique_bearer_env(),
+            unique_bearer_env(),
+            unique_bearer_env(),
+        ];
+        let tokens = [
+            "utility-token-1",
+            "retention-token-2",
+            "vector-token-3",
+            "benchmark-token-4",
+            "export-token-5",
+            "ranker-candidates-token-6",
+            "ranker-pairs-token-7",
+            "process-eval-token-8",
+        ];
+        let _guards: Vec<EnvGuard> = envs
+            .iter()
+            .zip(tokens.iter())
+            .map(|(e, t)| EnvGuard::set(e.clone(), t))
+            .collect();
+
+        // Each route accepts any POST/GET and checks the authorization header
+        // matches the expected token.
+        let routes: [(&str, &str, &str); 8] = [
+            ("POST", "/v1/workers/utility-credit", tokens[0]),
+            ("POST", "/v1/workers/retention-maintenance", tokens[1]),
+            ("POST", "/v1/workers/vector-index", tokens[2]),
+            ("POST", "/v1/workers/benchmark-convert", tokens[3]),
+            ("GET", "/v1/workers/replay-export", tokens[4]),
+            ("GET", "/v1/workers/ranker/training-candidates", tokens[5]),
+            ("GET", "/v1/workers/ranker/training-pairs", tokens[6]),
+            ("POST", "/v1/workers/process-evaluation", tokens[7]),
+        ];
+        for (m, p, tok) in routes {
+            Mock::given(method(m))
+                .and(wm_path(p))
+                .and(header("authorization", format!("Bearer {tok}").as_str()))
+                .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({})))
+                .expect(1)
+                .mount(&server)
+                .await;
+        }
+
+        // Fire each subcommand handler with its own env name.
+        let endpoint = server.uri();
+
+        let c0 = build_client(&endpoint, &envs[0], None).unwrap();
+        worker_utility_credit(
+            &c0,
+            &endpoint,
+            WorkerUtilityCreditArgs {
+                event_type: UtilityCreditEventType::TrainingUtility,
+                credit_points_delta: 1.0,
+                reason: "r".into(),
+                external_ref: "x".into(),
+                submission_ids: vec![Uuid::new_v4()],
+                bearer_token_env: envs[0].clone(),
+            },
+            true,
+        )
+        .await
+        .expect("utility credit");
+
+        let c1 = build_client(&endpoint, &envs[1], None).unwrap();
+        worker_retention_maintenance(
+            &c1,
+            &endpoint,
+            WorkerRetentionMaintenanceArgs {
+                purpose: None,
+                dry_run: false,
+                purge_expired_before: None,
+                max_export_age_hours: None,
+                skip_export_cache_prune: false,
+                bearer_token_env: envs[1].clone(),
+            },
+            true,
+        )
+        .await
+        .expect("retention");
+
+        let c2 = build_client(&endpoint, &envs[2], None).unwrap();
+        worker_vector_index(
+            &c2,
+            &endpoint,
+            WorkerVectorIndexArgs {
+                purpose: None,
+                dry_run: true,
+                bearer_token_env: envs[2].clone(),
+            },
+            true,
+        )
+        .await
+        .expect("vector");
+
+        let c3 = build_client(&endpoint, &envs[3], None).unwrap();
+        worker_benchmark_convert(
+            &c3,
+            &endpoint,
+            WorkerBenchmarkConvertArgs {
+                purpose: "p".into(),
+                limit: None,
+                consent_scope: None,
+                status: None,
+                privacy_risk: None,
+                external_ref: None,
+                bearer_token_env: envs[3].clone(),
+            },
+            true,
+        )
+        .await
+        .expect("benchmark");
+
+        let c4 = build_client(&endpoint, &envs[4], None).unwrap();
+        worker_replay_dataset_export(
+            &c4,
+            &endpoint,
+            WorkerReplayDatasetExportArgs {
+                purpose: None,
+                consent_scope: None,
+                status: None,
+                privacy_risk: None,
+                limit: None,
+                output: None,
+                bearer_token_env: envs[4].clone(),
+            },
+            true,
+        )
+        .await
+        .expect("replay");
+
+        let c5 = build_client(&endpoint, &envs[5], None).unwrap();
+        worker_ranker_training_export(
+            &c5,
+            &endpoint,
+            WorkerRankerTrainingArgs {
+                purpose: None,
+                consent_scope: None,
+                status: None,
+                privacy_risk: None,
+                limit: None,
+                output: None,
+                bearer_token_env: envs[5].clone(),
+            },
+            "/v1/workers/ranker/training-candidates",
+            "ranker training candidates",
+            "candidates",
+            true,
+        )
+        .await
+        .expect("ranker candidates");
+
+        let c6 = build_client(&endpoint, &envs[6], None).unwrap();
+        worker_ranker_training_export(
+            &c6,
+            &endpoint,
+            WorkerRankerTrainingArgs {
+                purpose: None,
+                consent_scope: None,
+                status: None,
+                privacy_risk: None,
+                limit: None,
+                output: None,
+                bearer_token_env: envs[6].clone(),
+            },
+            "/v1/workers/ranker/training-pairs",
+            "ranker training pairs",
+            "pairs",
+            true,
+        )
+        .await
+        .expect("ranker pairs");
+
+        let c7 = build_client(&endpoint, &envs[7], None).unwrap();
+        process_evaluation_submit(
+            &c7,
+            &endpoint,
+            ProcessEvaluationSubmitArgs {
+                submission_id: Uuid::new_v4(),
+                reason: "r".into(),
+                evaluator_name: None,
+                evaluator_version: "v1".into(),
+                labels: vec![],
+                tool_selection: None,
+                tool_argument_quality: None,
+                tool_ordering: None,
+                verification: None,
+                side_effect_safety: None,
+                overall_score: None,
+                utility_credit_points_delta: None,
+                utility_external_ref: None,
+                bearer_token_env: envs[7].clone(),
+            },
+            true,
+        )
+        .await
+        .expect("process evaluation");
+    }
+
+    #[tokio::test]
+    async fn worker_utility_credit_posts_expected_body() {
+        let server = MockServer::start().await;
+        let sub = Uuid::new_v4();
+        Mock::given(method("POST"))
+            .and(wm_path("/v1/workers/utility-credit"))
+            .and(body_json(serde_json::json!({
+                "event_type": "training_utility",
+                "credit_points_delta": 1.5,
+                "reason": "delayed training",
+                "external_ref": "job-1",
+                "submission_ids": [sub],
+            })))
+            .respond_with(
+                ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                    "appended_count": 1,
+                    "skipped_existing_count": 0,
+                })),
+            )
+            .expect(1)
+            .mount(&server)
+            .await;
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "utility-secret");
+        let client = Client::builder(server.uri(), env.clone()).build().unwrap();
+        worker_utility_credit(
+            &client,
+            &server.uri(),
+            WorkerUtilityCreditArgs {
+                event_type: UtilityCreditEventType::TrainingUtility,
+                credit_points_delta: 1.5,
+                reason: "delayed training".into(),
+                external_ref: "job-1".into(),
+                submission_ids: vec![sub],
+                bearer_token_env: env,
+            },
+            true,
+        )
+        .await
+        .expect("happy path");
+    }
+
+    #[tokio::test]
+    async fn worker_utility_credit_rejects_empty_reason() {
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "secret");
+        let client = Client::builder("https://api.example", env.clone())
+            .build()
+            .unwrap();
+        let err = worker_utility_credit(
+            &client,
+            "https://api.example",
+            WorkerUtilityCreditArgs {
+                event_type: UtilityCreditEventType::TrainingUtility,
+                credit_points_delta: 1.0,
+                reason: "  ".into(),
+                external_ref: "x".into(),
+                submission_ids: vec![Uuid::new_v4()],
+                bearer_token_env: env,
+            },
+            true,
+        )
+        .await
+        .unwrap_err();
+        assert!(err.to_string().contains("reason"));
+    }
+
+    #[tokio::test]
+    async fn worker_utility_credit_rejects_no_submissions() {
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "secret");
+        let client = Client::builder("https://api.example", env.clone())
+            .build()
+            .unwrap();
+        let err = worker_utility_credit(
+            &client,
+            "https://api.example",
+            WorkerUtilityCreditArgs {
+                event_type: UtilityCreditEventType::TrainingUtility,
+                credit_points_delta: 1.0,
+                reason: "r".into(),
+                external_ref: "x".into(),
+                submission_ids: vec![],
+                bearer_token_env: env,
+            },
+            true,
+        )
+        .await
+        .unwrap_err();
+        assert!(err.to_string().contains("SUBMISSION_ID"));
+    }
+
+    #[tokio::test]
+    async fn process_evaluation_submit_rejects_bad_overall_score() {
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "secret");
+        let client = Client::builder("https://api.example", env.clone())
+            .build()
+            .unwrap();
+        let err = process_evaluation_submit(
+            &client,
+            "https://api.example",
+            ProcessEvaluationSubmitArgs {
+                submission_id: Uuid::new_v4(),
+                reason: "r".into(),
+                evaluator_name: None,
+                evaluator_version: "v1".into(),
+                labels: vec![],
+                tool_selection: None,
+                tool_argument_quality: None,
+                tool_ordering: None,
+                verification: None,
+                side_effect_safety: None,
+                overall_score: Some(2.0),
+                utility_credit_points_delta: None,
+                utility_external_ref: None,
+                bearer_token_env: env,
+            },
+            true,
+        )
+        .await
+        .unwrap_err();
+        assert!(err.to_string().contains("overall-score"));
+    }
+
+    #[tokio::test]
+    async fn process_evaluation_submit_requires_external_ref_with_delta() {
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "secret");
+        let client = Client::builder("https://api.example", env.clone())
+            .build()
+            .unwrap();
+        let err = process_evaluation_submit(
+            &client,
+            "https://api.example",
+            ProcessEvaluationSubmitArgs {
+                submission_id: Uuid::new_v4(),
+                reason: "r".into(),
+                evaluator_name: None,
+                evaluator_version: "v1".into(),
+                labels: vec![],
+                tool_selection: None,
+                tool_argument_quality: None,
+                tool_ordering: None,
+                verification: None,
+                side_effect_safety: None,
+                overall_score: None,
+                utility_credit_points_delta: Some(0.2),
+                utility_external_ref: None,
+                bearer_token_env: env,
+            },
+            true,
+        )
+        .await
+        .unwrap_err();
+        assert!(err.to_string().contains("utility-external-ref"));
+    }
+
+    #[tokio::test]
+    async fn worker_vector_index_posts_dry_run_body() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(wm_path("/v1/workers/vector-index"))
+            .and(body_json(serde_json::json!({
+                "dry_run": true,
+                "purpose": "reindex",
+            })))
+            .respond_with(
+                ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                    "audit_event_id": "a-1",
+                    "purpose": "reindex",
+                    "dry_run": true,
+                    "vector_entries_indexed": 0,
+                })),
+            )
+            .expect(1)
+            .mount(&server)
+            .await;
+        let env = unique_bearer_env();
+        let _g = EnvGuard::set(env.clone(), "vector-secret");
+        let client = Client::builder(server.uri(), env.clone()).build().unwrap();
+        worker_vector_index(
+            &client,
+            &server.uri(),
+            WorkerVectorIndexArgs {
+                purpose: Some("reindex".into()),
+                dry_run: true,
+                bearer_token_env: env,
+            },
+            true,
+        )
+        .await
+        .expect("vector index dry run");
+    }
+}

From 592711c3e0bb83fe366ad57e9b80d013b0bcd0df Mon Sep 17 00:00:00 2001
From: Zaki <zaki@iqlusion.io>
Date: Tue, 19 May 2026 15:35:28 -0700
Subject: [PATCH 4/7] Add operator-binaries runbook and CI smoke

---
 .github/workflows/ci.yml           |  23 ++++
 docs/operator/README.md            |   5 +
 docs/operator/operator-binaries.md | 214 +++++++++++++++++++++++++++++
 scripts/operator/operator-smoke.sh | 132 ++++++++++++++++++
 4 files changed, 374 insertions(+)
 create mode 100644 docs/operator/operator-binaries.md
 create mode 100755 scripts/operator/operator-smoke.sh

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index a4737d437..feeaab61c 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -188,3 +188,26 @@ jobs:
       # with a `SmokePilotBootstrapFailure:<label>` diagnostic.
       - name: Run pilot-bootstrap smoke
         run: bash scripts/operator/pilot-bootstrap-smoke.sh
+
+  operator-binaries-smoke:
+    name: operator-binaries smoke
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v6
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cargo/registry/index
+            ~/.cargo/registry/cache
+            ~/.cargo/git/db
+            target
+          key: ${{ runner.os }}-cargo-operator-binaries-smoke-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-operator-binaries-smoke-
+      # Builds and exercises the four operator CLIs (review, admin, worker,
+      # tenant), confirming --version + --help + per-binary subcommand counts.
+      # See docs/operator/operator-binaries.md.
+      - name: Run operator-binaries smoke
+        run: bash scripts/operator/operator-smoke.sh
diff --git a/docs/operator/README.md b/docs/operator/README.md
index bfa4cd24e..0c2c02467 100644
--- a/docs/operator/README.md
+++ b/docs/operator/README.md
@@ -43,6 +43,7 @@ the link.
 | Interpreting `/v1/admin/operational-summary` | [`./operational-summary.md`](./operational-summary.md) |
 | Running or scheduling admin drills | [`./drills.md`](./drills.md) |
 | Looking up an env var | [`./env-reference.md`](./env-reference.md) |
+| Driving review / admin / worker / tenant workflows from a CLI | [`./operator-binaries.md`](./operator-binaries.md) |
 | Diagnosing a stuck or failing service | [`./troubleshooting.md`](./troubleshooting.md) |
 | Understanding the deployment topology | [`./architecture.md`](./architecture.md) |
 
@@ -88,6 +89,10 @@ Every runbook in this directory, with a one-line description.
   perplexity model or embedder and the gate-version implications.
 - [`./operational-summary.md`](./operational-summary.md) — field-by-field
   meaning and alarm guidance for `/v1/admin/operational-summary`.
+- [`./operator-binaries.md`](./operator-binaries.md) — operator CLI
+  workflows for `trace-commons-{review,admin,worker,tenant}`: install,
+  env-var matrix, common sequences, defense-in-depth notes, and an
+  error-variant troubleshooting table.
 - [`./pilot-bootstrap.md`](./pilot-bootstrap.md) — operator runbook for the
   HF-trace replay harness used to seed pilot calibration data.
 - [`./pilot-bootstrap-dryrun-notes.md`](./pilot-bootstrap-dryrun-notes.md) —
diff --git a/docs/operator/operator-binaries.md b/docs/operator/operator-binaries.md
new file mode 100644
index 000000000..ca907f455
--- /dev/null
+++ b/docs/operator/operator-binaries.md
@@ -0,0 +1,214 @@
+# Operator Binaries — `trace-commons-{review,admin,worker,tenant}`
+
+Four CLI binaries ship with `trace-commons-server` for operator-side workflows
+against a deployed hosted ingest. Each binary speaks the same JSON envelope
+over the same `trace_commons_operator_client::Client` (host-allowlisted,
+never logs bearer tokens or query strings), but is audience-scoped and gated
+by a different bearer-token surface. Together they replace the slice of the
+old Ironclaw `ironclaw traces …` surface that operators reach for during
+review, admin, worker, and tenant-management work.
+
+This runbook is intended to be readable end-to-end in under ten minutes.
+
+## Binaries at a glance
+
+| Binary | Audience | Default bearer env | Subcommands |
+|---|---|---|---|
+| `trace-commons-review` | Reviewers | `TRACE_COMMONS_REVIEWER_BEARER` | 8 |
+| `trace-commons-admin` | Hosted-service admins | `TRACE_COMMONS_ADMIN_BEARER` | 12 |
+| `trace-commons-worker` | Per-route worker operators | one per subcommand (see below) | 8 |
+| `trace-commons-tenant` | Tenant-policy operators | `TRACE_COMMONS_TENANT_BEARER` | 11 |
+
+Each binary takes:
+
+- `--endpoint <URL>` (or `TRACE_COMMONS_ENDPOINT`) — hosted ingest base URL.
+- `--bearer-token-env <NAME>` — env var holding the bearer token (the
+  binary reads the value at call time; the env *name* travels on the CLI
+  but the *value* never appears in logs).
+- `--allowed-hosts <CSV>` (or `TRACE_COMMONS_ALLOWED_HOSTS`) — defense-in-depth
+  host allowlist. Empty = permissive; populated = the foundation client
+  refuses any URL whose host is not in the list.
+- `--json` — emit a sanitized request envelope plus the raw server JSON
+  instead of a human-readable summary.
+
+## Install
+
+```bash
+cargo build --release \
+  --bin trace-commons-review \
+  --bin trace-commons-admin \
+  --bin trace-commons-worker \
+  --bin trace-commons-tenant
+```
+
+The resulting binaries live in `target/release/`. There are no required
+features; the binaries are buildable in hermetic CI.
+
+## Env-var matrix
+
+Each row lists a single ingest-server route gate. The binary subcommands
+that target that gate read the bearer from the listed env var by default;
+an operator can override via `--bearer-token-env <CUSTOM_NAME>` if they
+keep their tokens under non-default names.
+
+| Bearer env (default) | Gate (server side) | Consumed by |
+|---|---|---|
+| `TRACE_COMMONS_REVIEWER_BEARER` | reviewer role | `trace-commons-review` (all 8 subcommands) |
+| `TRACE_COMMONS_ADMIN_BEARER` | admin role | `trace-commons-admin` (all 12 subcommands) |
+| `TRACE_COMMONS_TENANT_BEARER` | admin role (tenant ops use the same gate) | `trace-commons-tenant` (9 server-backed subcommands) |
+| `TRACE_COMMONS_UTILITY_CREDIT_WORKER_BEARER` | utility-credit worker | `trace-commons-worker worker-utility-credit` |
+| `TRACE_COMMONS_RETENTION_WORKER_BEARER` | retention worker | `trace-commons-worker worker-retention-maintenance` |
+| `TRACE_COMMONS_VECTOR_WORKER_BEARER` | vector-index worker | `trace-commons-worker worker-vector-index` |
+| `TRACE_COMMONS_BENCHMARK_WORKER_BEARER` | benchmark-conversion worker | `trace-commons-worker worker-benchmark-convert` |
+| `TRACE_COMMONS_EXPORT_WORKER_BEARER` | export worker | `trace-commons-worker worker-replay-dataset-export` |
+| `TRACE_COMMONS_RANKER_WORKER_BEARER` | export worker (shared with ranker training routes) | `trace-commons-worker worker-ranker-training-candidates`, `worker-ranker-training-pairs` |
+| `TRACE_COMMONS_PROCESS_EVALUATION_WORKER_BEARER` | process-evaluation worker | `trace-commons-worker process-evaluation-submit` |
+
+The ingest server enforces these gates through per-role tokens carried in
+`TRACE_COMMONS_TENANT_TOKENS`; on the operator side the per-route env names
+are intentionally distinct so an operator cannot accidentally reuse a
+broader-scoped token where a narrower one is sufficient.
+
+Two `trace-commons-tenant` subcommands do not hit the server and so do not
+consume a bearer:
+
+- `tenant-principal-ref` — derives the stored `principal_ref` locally from
+  either a static token or a signed-claim `(tenant_id, actor_ref)` pair.
+- `privacy-filter-canary` — stubbed in the operator binary; the underlying
+  local sidecar is not yet ported off the Ironclaw runtime. The subcommand
+  fails fast with a clear message; run the canary via legacy local tooling
+  until A2.8 ports the sidecar.
+
+## Common workflows
+
+### Reviewer: claim → decide → release
+
+```bash
+export TRACE_COMMONS_ENDPOINT=https://trace-commons.example.com
+export TRACE_COMMONS_REVIEWER_BEARER=...
+
+# 1. See what's open.
+trace-commons-review quarantine-list --lease-filter available
+
+# 2. Claim the next one (or a specific submission_id).
+trace-commons-review review-lease-claim-next --privacy-risk medium
+
+# 3. Inspect, then approve or reject.
+trace-commons-review review-decision \
+  --submission-id <UUID> --decision approve \
+  --reason "tools verified, side effects OK"
+
+# 4. If you need to walk away, release the lease.
+trace-commons-review review-lease-release --submission-id <UUID>
+```
+
+### Retention maintenance: admin vs worker
+
+Two paths target similar effects but enforce different roles:
+
+- `trace-commons-admin maintenance-run` exercises the admin gate at
+  `/v1/admin/maintenance` and supports the full set of toggles
+  (`--backfill-db-mirror`, `--reconcile-db-mirror`, `--verify-audit-chain`,
+  `--index-vectors`, in addition to the retention flags).
+- `trace-commons-worker worker-retention-maintenance` exercises the
+  retention-worker gate at `/v1/workers/retention-maintenance` and is
+  scoped to retention behaviors only.
+
+Use the admin entry point for cross-cutting maintenance runs that mix
+retention with mirror reconciliation or audit-chain verification; use the
+worker entry point for scheduled retention sweeps from a service account
+that should not hold admin scope.
+
+### Tenant rotation: policy + access grants
+
+```bash
+export TRACE_COMMONS_ENDPOINT=https://trace-commons.example.com
+export TRACE_COMMONS_TENANT_BEARER=...
+
+# Inspect the current policy.
+trace-commons-tenant tenant-policy-get --json
+
+# Roll forward to a new policy version.
+trace-commons-tenant tenant-policy-set \
+  --policy-version 2026-05-19-pilot \
+  --allowed-consent-scopes benchmark-only,model-training \
+  --allowed-uses benchmark-generation,model-training
+
+# Derive the principal_ref for a new reviewer's static token.
+trace-commons-tenant tenant-principal-ref --token-env REVIEWER_BOB_TOKEN
+
+# Grant it. The grant_id is server-allocated unless --grant-id is passed.
+trace-commons-tenant tenant-access-grant-create \
+  --principal-ref principal_sha256:... \
+  --role reviewer \
+  --allowed-consent-scopes benchmark-only,model-training \
+  --allowed-uses benchmark-generation,model-training \
+  --reason "rotate reviewer bob into the pilot"
+
+# Revoke an old grant.
+trace-commons-tenant tenant-access-grant-revoke \
+  --grant-id <UUID> --reason "key compromise rotation"
+```
+
+### Benchmark conversion: convert then lifecycle
+
+```bash
+export TRACE_COMMONS_ADMIN_BEARER=...
+
+# Kick off a conversion run for approved replay-eligible traces.
+trace-commons-admin benchmark-convert \
+  --purpose "2026-05 pilot weekly" \
+  --consent-scope benchmark-only \
+  --status accepted \
+  --limit 50
+
+# Once the registry and evaluator have run, record their outcomes.
+trace-commons-admin benchmark-lifecycle-update \
+  --conversion-id <UUID> \
+  --registry-status published \
+  --evaluation-status passed \
+  --score 0.87 \
+  --reason "weekly registry run"
+```
+
+## Defense-in-depth: host allowlist and JSON envelopes
+
+`TRACE_COMMONS_ALLOWED_HOSTS` is a CSV of hostnames the foundation client
+will accept; any other host raises `Error::HostNotAllowed` before the
+request is dispatched. Use it whenever the operator host has any chance of
+running against the wrong endpoint (CI, dev, etc.).
+
+`--json` emits a two-part envelope per request:
+
+```json
+{
+  "request": {"method": "GET", "url": "https://…/v1/audit/events?limit=25"},
+  "data":    {"items": [ … ]}
+}
+```
+
+The `url` field is sanitized — query-string values get stripped to
+keys-only before logging. Bearer tokens never appear in the envelope; they
+travel only as an `Authorization` header and are never echoed.
+
+## Troubleshooting
+
+The foundation client returns one of the following error variants. The
+binary surfaces each as `Error: <variant-name>: <message>`.
+
+| Variant | Typical cause | Fix |
+|---|---|---|
+| `bearer-missing` | The env var named by `--bearer-token-env` is unset or empty. | Export the env var; double-check you're using the per-route default for `trace-commons-worker`. |
+| `host-not-allowed` | The endpoint hostname is not in `TRACE_COMMONS_ALLOWED_HOSTS`. | Add the host to the CSV, or unset the env to go permissive. Never paste tokens into a permissive shell. |
+| `server-label:<class>` | The server returned a non-2xx with a hash-only error class. | Cross-reference the class against [`./hash-only-logging.md`](./hash-only-logging.md). |
+| `http-failure` | The server returned a non-2xx without a class (most often a 4xx body the operator must read). | Re-run with `--json` and read the `data` field. |
+| `malformed-response` | The server returned 2xx but the body did not parse as JSON. | The hosted service is mis-deployed or behind an HTML interstitial. Confirm `--endpoint` is correct and reachable. |
+| `transport` | Network failure: DNS, TLS, refused connection. | Standard network triage. Check the endpoint URL, then the host allowlist, then DNS, then TLS roots. |
+
+## When to update this runbook
+
+- New subcommand in any binary: add a row to the binaries-at-a-glance
+  table and (if it introduces a new bearer surface) the env-var matrix.
+- New foundation `Error` variant: add a row to the troubleshooting table.
+- The `privacy-filter-canary` stub is replaced by a real port: remove
+  the deferred-note from the binaries section and add a workflow row.
diff --git a/scripts/operator/operator-smoke.sh b/scripts/operator/operator-smoke.sh
new file mode 100755
index 000000000..42dd66fc4
--- /dev/null
+++ b/scripts/operator/operator-smoke.sh
@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+#
+# Local smoke harness for the four operator binaries:
+#   trace-commons-review, trace-commons-admin,
+#   trace-commons-worker, trace-commons-tenant.
+#
+# Builds each binary in debug mode (release if SMOKE_OPERATOR_RELEASE=1)
+# and exercises --version and --help on each, then runs a few representative
+# parse-through invocations (no network — uses --help on a subcommand to
+# exercise the clap derive end-to-end). Asserts:
+#
+#   1. Each binary builds.
+#   2. --version prints non-empty output.
+#   3. --help lists the expected number of subcommands.
+#   4. A representative subcommand on each binary parses cleanly.
+#
+# Exits 0 with `SmokeOperatorBinariesOK: <details>` on success;
+# exits 1 with `SmokeOperatorBinariesFailure:<label>` on first failure.
+# Stdlib only, bash 3 compatible (works on macOS); safe to re-run.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+if [[ "${SMOKE_OPERATOR_RELEASE:-0}" == "1" ]]; then
+    PROFILE_FLAG="--release"
+    PROFILE_DIR="release"
+else
+    PROFILE_FLAG=""
+    PROFILE_DIR="debug"
+fi
+
+BIN_DIR="$REPO_ROOT/target/$PROFILE_DIR"
+
+# Parallel arrays: BINARIES[i] expects EXPECTED_COUNTS[i] subcommands.
+# If a binary gains or loses a subcommand, update both here and the
+# operator-binaries.md doc.
+BINARIES=(
+    "trace-commons-review"
+    "trace-commons-admin"
+    "trace-commons-worker"
+    "trace-commons-tenant"
+)
+EXPECTED_COUNTS=(
+    "8"
+    "12"
+    "8"
+    "11"
+)
+REPRESENTATIVE_SUBCMDS=(
+    "quarantine-list"
+    "maintenance-run"
+    "worker-utility-credit"
+    "tenant-policy-get"
+)
+
+fail() {
+    echo "SmokeOperatorBinariesFailure:$1" >&2
+    exit 1
+}
+
+build_one() {
+    local name
+    name="$1"
+    # shellcheck disable=SC2086
+    cargo build -p trace-commons-server $PROFILE_FLAG --bin "$name" \
+        > /dev/null 2>&1 || fail "build:$name"
+}
+
+check_help_subcmd_count() {
+    local name want out count
+    name="$1"
+    want="$2"
+    out="$("$BIN_DIR/$name" --help 2>&1)" || fail "help-failed:$name"
+    count="$(printf '%s\n' "$out" | awk '
+        /^Commands:/ { in_cmds=1; next }
+        in_cmds && /^Options:/ { exit }
+        in_cmds && /^[[:space:]]*$/ { exit }
+        in_cmds && /^  help[[:space:]]/ { next }
+        in_cmds && /^  [a-z]/ { count++ }
+        END { print count+0 }
+    ')"
+    if [[ "$count" != "$want" ]]; then
+        fail "subcmd-count:$name:want=$want:got=$count"
+    fi
+}
+
+check_version() {
+    local name out
+    name="$1"
+    out="$("$BIN_DIR/$name" --version 2>&1)" || fail "version-failed:$name"
+    if [[ -z "$out" ]]; then
+        fail "empty-version:$name"
+    fi
+}
+
+check_subcommand_help() {
+    local name sub
+    name="$1"
+    sub="$2"
+    "$BIN_DIR/$name" "$sub" --help > /dev/null 2>&1 || fail "subcmd-help:$name:$sub"
+}
+
+main() {
+    local i n
+    n="${#BINARIES[@]}"
+
+    echo "Building operator binaries..."
+    for ((i = 0; i < n; i++)); do
+        build_one "${BINARIES[$i]}"
+    done
+
+    echo "Checking --version on each binary..."
+    for ((i = 0; i < n; i++)); do
+        check_version "${BINARIES[$i]}"
+    done
+
+    echo "Checking subcommand counts via --help..."
+    for ((i = 0; i < n; i++)); do
+        check_help_subcmd_count "${BINARIES[$i]}" "${EXPECTED_COUNTS[$i]}"
+    done
+
+    echo "Checking representative subcommand --help on each binary..."
+    for ((i = 0; i < n; i++)); do
+        check_subcommand_help "${BINARIES[$i]}" "${REPRESENTATIVE_SUBCMDS[$i]}"
+    done
+
+    echo "SmokeOperatorBinariesOK: review=8 admin=12 worker=8 tenant=11"
+}
+
+main "$@"

From 9ed702066e75308ac43eaccf2a83cbf279305108 Mon Sep 17 00:00:00 2001
From: Zaki <zaki@iqlusion.io>
Date: Tue, 19 May 2026 16:39:50 -0700
Subject: [PATCH 5/7] port privacy-filter-canary into
 trace-commons-operator-client

Adds a privacy_filter module to the operator-client foundation crate
holding the subprocess sidecar adapter, safe-summary parser, env-var
configuration reader, and canary-leak helper. The wire shapes
(PrivacyFilterSidecarRequest, SafePrivacyFilterRedaction, RedactionReport,
SafePrivacyFilterSummary) match the Ironclaw types byte-for-byte so
operators can repoint existing sidecar binaries unchanged.

Environment variables prefer the canonical TRACE_COMMONS_PRIVACY_FILTER_*
names and fall back to the Ironclaw-era IRONCLAW_TRACE_PRIVACY_FILTER_*
names with a one-shot warn log on fallback.

The trace-commons-tenant privacy-filter-canary subcommand now drives the
real adapter: it spawns the configured sidecar, verifies no canary token
survives redaction, and renders either a human-readable result or the
operator JSON envelope. The old anyhow::bail! stub is gone.

operator-binaries.md drops the deferred-port note and documents the env
vars (canonical + legacy) plus the failure modes.
---
 Cargo.lock                                    |   4 +
 .../trace-commons-operator-client/Cargo.toml  |   6 +-
 .../trace-commons-operator-client/src/lib.rs  |   5 +
 .../src/privacy_filter.rs                     | 625 ++++++++++++++++++
 .../src/bin/trace-commons-tenant.rs           | 224 +++++--
 docs/operator/operator-binaries.md            |  27 +-
 6 files changed, 837 insertions(+), 54 deletions(-)
 create mode 100644 crates/trace-commons-operator-client/src/privacy_filter.rs

diff --git a/Cargo.lock b/Cargo.lock
index 33f1b9f75..7478b60e2 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -7046,12 +7046,16 @@ name = "trace-commons-operator-client"
 version = "0.1.0"
 dependencies = [
  "anyhow",
+ "async-trait",
  "chrono",
+ "hex",
  "reqwest 0.12.28",
  "serde",
  "serde_json",
+ "sha2 0.10.9",
  "thiserror 2.0.18",
  "tokio",
+ "tracing",
  "url",
  "wiremock",
 ]
diff --git a/crates/trace-commons-operator-client/Cargo.toml b/crates/trace-commons-operator-client/Cargo.toml
index ce6b6c69c..6aeda9d92 100644
--- a/crates/trace-commons-operator-client/Cargo.toml
+++ b/crates/trace-commons-operator-client/Cargo.toml
@@ -9,12 +9,16 @@ description = "Shared HTTP client + typed request/response surface for trace-com
 
 [dependencies]
 anyhow = "1"
+async-trait = "0.1"
 chrono = { version = "0.4", features = ["serde"] }
+hex = "0.4"
 reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls-native-roots"] }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
+sha2 = "0.10"
 thiserror = "2"
-tokio = { version = "1", features = ["macros", "rt-multi-thread", "time"] }
+tokio = { version = "1", features = ["macros", "process", "rt-multi-thread", "time", "io-util"] }
+tracing = "0.1"
 url = "2"
 
 [dev-dependencies]
diff --git a/crates/trace-commons-operator-client/src/lib.rs b/crates/trace-commons-operator-client/src/lib.rs
index d14068ef9..86a5ef38e 100644
--- a/crates/trace-commons-operator-client/src/lib.rs
+++ b/crates/trace-commons-operator-client/src/lib.rs
@@ -19,6 +19,11 @@ pub mod client;
 pub mod error;
 pub mod format;
 pub mod host_allowlist;
+pub mod privacy_filter;
 
 pub use client::Client;
 pub use error::{Error, Result};
+pub use privacy_filter::{
+    CommandPrivacyFilterAdapter, PrivacyFilterAdapter, SafePrivacyFilterRedaction,
+    adapter_from_env, canary_leaked_tokens,
+};
diff --git a/crates/trace-commons-operator-client/src/privacy_filter.rs b/crates/trace-commons-operator-client/src/privacy_filter.rs
new file mode 100644
index 000000000..f42fafb97
--- /dev/null
+++ b/crates/trace-commons-operator-client/src/privacy_filter.rs
@@ -0,0 +1,625 @@
+//! Privacy-filter sidecar adapter — ported from Ironclaw.
+//!
+//! Provides a small, wire-compatible client for the Privacy Filter sidecar
+//! protocol used by the trace contribution pipeline. The sidecar is a
+//! standalone subprocess that reads a JSON `PrivacyFilterSidecarRequest`
+//! from stdin and writes a JSON response on stdout. The response is parsed
+//! into a [`SafePrivacyFilterRedaction`], which carries only label-level
+//! summary information (no raw spans) so that operator binaries can run a
+//! local canary check without ever logging the raw text.
+//!
+//! Wire shapes match the Ironclaw `ironclaw_reborn_traces::contribution`
+//! types byte-for-byte. Operators who already have an Ironclaw sidecar
+//! configured can point it at this client unchanged.
+//!
+//! Env vars (canonical names first, Ironclaw fallbacks second):
+//!
+//! - `TRACE_COMMONS_PRIVACY_FILTER_COMMAND` /
+//!   `IRONCLAW_TRACE_PRIVACY_FILTER_COMMAND` — sidecar executable path.
+//! - `..._ARGS` — whitespace-separated argv.
+//! - `..._TIMEOUT_MS` — wall-clock timeout in milliseconds.
+//! - `..._MAX_INPUT_BYTES`, `..._MAX_STDOUT_BYTES`, `..._MAX_STDERR_BYTES`.
+
+use std::collections::BTreeMap;
+use std::path::PathBuf;
+use std::process::Stdio;
+use std::sync::{Arc, Once};
+use std::time::Duration;
+
+use async_trait::async_trait;
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use sha2::{Digest, Sha256};
+use tokio::io::AsyncWriteExt;
+
+pub const PRIVACY_FILTER_SIDECAR_DEFAULT_MAX_INPUT_BYTES: usize = 1024 * 1024;
+pub const PRIVACY_FILTER_SIDECAR_DEFAULT_MAX_STDOUT_BYTES: usize = 1024 * 1024;
+pub const PRIVACY_FILTER_SIDECAR_DEFAULT_MAX_STDERR_BYTES: usize = 64 * 1024;
+
+/// Label-only summary of a privacy-filter redaction. Mirrors the Ironclaw
+/// `SafePrivacyFilterSummary` wire shape.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
+pub struct SafePrivacyFilterSummary {
+    pub schema_version: u16,
+    pub output_mode: String,
+    pub span_count: u32,
+    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
+    pub by_label: BTreeMap<String, u32>,
+    pub decoded_mismatch: bool,
+}
+
+/// Label-only redaction-report counts. Mirrors the Ironclaw
+/// `RedactionReport` wire shape.
+#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
+pub struct RedactionReport {
+    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
+    pub counts: BTreeMap<String, u32>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub pii_labels_present: Vec<String>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub warnings: Vec<String>,
+    pub blocked_secret_detected: bool,
+}
+
+impl RedactionReport {
+    fn increment(&mut self, label: impl Into<String>) {
+        *self.counts.entry(label.into()).or_insert(0) += 1;
+    }
+
+    fn add_warning(&mut self, warning: impl Into<String>) {
+        let warning = warning.into();
+        if !self.warnings.contains(&warning) {
+            self.warnings.push(warning);
+        }
+    }
+}
+
+/// Parsed sidecar response: the redacted text, plus label-only summary +
+/// report. Carries no raw spans.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct SafePrivacyFilterRedaction {
+    pub redacted_text: String,
+    pub summary: SafePrivacyFilterSummary,
+    pub report: RedactionReport,
+}
+
+/// The JSON request body the sidecar reads from stdin.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct PrivacyFilterSidecarRequest {
+    pub text: String,
+}
+
+impl PrivacyFilterSidecarRequest {
+    pub fn new(text: impl Into<String>) -> Self {
+        Self { text: text.into() }
+    }
+}
+
+/// Trait alias for sidecar adapters. Implementors run the privacy filter
+/// (locally, via subprocess, or via a stub) and return a safe summary.
+#[async_trait]
+pub trait PrivacyFilterAdapter: Send + Sync {
+    async fn redact_text(&self, text: &str) -> anyhow::Result<Option<SafePrivacyFilterRedaction>>;
+}
+
+/// No-op adapter for tests and for callers that want to thread a sidecar
+/// dependency without actually configuring one.
+pub struct NoopPrivacyFilterAdapter;
+
+#[async_trait]
+impl PrivacyFilterAdapter for NoopPrivacyFilterAdapter {
+    async fn redact_text(&self, _text: &str) -> anyhow::Result<Option<SafePrivacyFilterRedaction>> {
+        Ok(None)
+    }
+}
+
+/// Subprocess-driven sidecar adapter. Spawns the configured command,
+/// pipes the JSON request to stdin, captures stdout/stderr under byte
+/// limits, and parses the response into a [`SafePrivacyFilterRedaction`].
+#[derive(Debug, Clone)]
+pub struct CommandPrivacyFilterAdapter {
+    command: PathBuf,
+    args: Vec<String>,
+    timeout: Duration,
+    max_input_bytes: usize,
+    max_stdout_bytes: usize,
+    max_stderr_bytes: usize,
+}
+
+impl CommandPrivacyFilterAdapter {
+    pub fn new(command: impl Into<PathBuf>) -> Self {
+        Self {
+            command: command.into(),
+            args: Vec::new(),
+            timeout: Duration::from_secs(10),
+            max_input_bytes: PRIVACY_FILTER_SIDECAR_DEFAULT_MAX_INPUT_BYTES,
+            max_stdout_bytes: PRIVACY_FILTER_SIDECAR_DEFAULT_MAX_STDOUT_BYTES,
+            max_stderr_bytes: PRIVACY_FILTER_SIDECAR_DEFAULT_MAX_STDERR_BYTES,
+        }
+    }
+
+    pub fn with_args(mut self, args: impl IntoIterator<Item = impl Into<String>>) -> Self {
+        self.args = args.into_iter().map(Into::into).collect();
+        self
+    }
+
+    pub fn with_timeout(mut self, timeout: Duration) -> Self {
+        self.timeout = timeout;
+        self
+    }
+
+    pub fn with_input_limit(mut self, max_input_bytes: usize) -> Self {
+        self.max_input_bytes = max_input_bytes;
+        self
+    }
+
+    pub fn with_output_limits(mut self, max_stdout_bytes: usize, max_stderr_bytes: usize) -> Self {
+        self.max_stdout_bytes = max_stdout_bytes;
+        self.max_stderr_bytes = max_stderr_bytes;
+        self
+    }
+}
+
+#[async_trait]
+impl PrivacyFilterAdapter for CommandPrivacyFilterAdapter {
+    async fn redact_text(&self, text: &str) -> anyhow::Result<Option<SafePrivacyFilterRedaction>> {
+        if text.trim().is_empty() {
+            return Ok(None);
+        }
+        if text.len() > self.max_input_bytes {
+            anyhow::bail!(
+                "privacy filter sidecar input exceeded limit: input_len={} max_input_bytes={}",
+                text.len(),
+                self.max_input_bytes
+            );
+        }
+
+        let mut command = tokio::process::Command::new(&self.command);
+        command.env_clear();
+        for name in ["PATH", "LANG", "LC_ALL"] {
+            if let Ok(value) = std::env::var(name) {
+                command.env(name, value);
+            }
+        }
+        command
+            .args(&self.args)
+            .stdin(Stdio::piped())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::piped())
+            .kill_on_drop(true);
+        let mut child = command.spawn().map_err(|error| {
+            anyhow::anyhow!(
+                "failed to spawn privacy filter sidecar {}: {}",
+                self.command.display(),
+                error
+            )
+        })?;
+
+        let mut stdin = child
+            .stdin
+            .take()
+            .ok_or_else(|| anyhow::anyhow!("privacy filter sidecar stdin was not available"))?;
+        let request = PrivacyFilterSidecarRequest::new(text);
+        let request_body = serde_json::to_vec(&request).map_err(|error| {
+            anyhow::anyhow!("failed to serialize privacy filter request: {error}")
+        })?;
+        stdin
+            .write_all(&request_body)
+            .await
+            .map_err(|error| anyhow::anyhow!("failed to write privacy filter request: {error}"))?;
+        drop(stdin);
+
+        let output = tokio::time::timeout(self.timeout, child.wait_with_output())
+            .await
+            .map_err(|_| {
+                anyhow::anyhow!(
+                    "privacy filter sidecar timed out after {}ms",
+                    self.timeout.as_millis()
+                )
+            })?
+            .map_err(|error| anyhow::anyhow!("privacy filter sidecar failed: {error}"))?;
+
+        if output.stdout.len() > self.max_stdout_bytes {
+            anyhow::bail!(
+                "stdout exceeded privacy filter sidecar limit: stdout_len={} max_stdout_bytes={}",
+                output.stdout.len(),
+                self.max_stdout_bytes
+            );
+        }
+        if output.stderr.len() > self.max_stderr_bytes {
+            anyhow::bail!(
+                "stderr exceeded privacy filter sidecar limit: stderr_len={} stderr_hash={} max_stderr_bytes={}",
+                output.stderr.len(),
+                privacy_filter_bytes_hash(&output.stderr),
+                self.max_stderr_bytes
+            );
+        }
+
+        if !output.status.success() {
+            anyhow::bail!(
+                "privacy filter sidecar exited with {}; stderr_len={} stderr_hash={}",
+                output.status,
+                output.stderr.len(),
+                privacy_filter_bytes_hash(&output.stderr)
+            );
+        }
+
+        let value: Value = serde_json::from_slice(&output.stdout)
+            .map_err(|error| anyhow::anyhow!("failed to parse privacy filter output: {error}"))?;
+        safe_privacy_filter_redaction_from_output(&value).map(Some)
+    }
+}
+
+/// Parse a sidecar stdout JSON value into a [`SafePrivacyFilterRedaction`].
+/// Drops raw spans; keeps only label-level counts.
+pub fn safe_privacy_filter_redaction_from_output(
+    output: &Value,
+) -> anyhow::Result<SafePrivacyFilterRedaction> {
+    let redacted_text = output
+        .get("redacted_text")
+        .and_then(Value::as_str)
+        .ok_or_else(|| anyhow::anyhow!("privacy filter output is missing redacted_text"))?
+        .to_string();
+    let detected_spans = output
+        .get("detected_spans")
+        .and_then(Value::as_array)
+        .cloned()
+        .unwrap_or_default();
+
+    let mut by_label = BTreeMap::new();
+    let mut report = RedactionReport::default();
+    for span in &detected_spans {
+        let raw_label = span
+            .get("label")
+            .or_else(|| span.get("type"))
+            .or_else(|| span.get("entity_type"))
+            .and_then(Value::as_str);
+        let label = safe_privacy_filter_label(raw_label, &mut report);
+        *by_label.entry(label.clone()).or_insert(0) += 1;
+        report.increment(format!("privacy_filter:{label}"));
+        if label.eq_ignore_ascii_case("secret") {
+            report.blocked_secret_detected = true;
+        }
+        if !report.pii_labels_present.contains(&label) {
+            report.pii_labels_present.push(label);
+        }
+    }
+
+    let schema_version = output
+        .get("schema_version")
+        .and_then(Value::as_u64)
+        .and_then(|value| u16::try_from(value).ok())
+        .unwrap_or(1);
+    let decoded_mismatch = output
+        .get("decoded_mismatch")
+        .and_then(Value::as_bool)
+        .unwrap_or(false);
+
+    Ok(SafePrivacyFilterRedaction {
+        redacted_text,
+        summary: SafePrivacyFilterSummary {
+            schema_version,
+            output_mode: "redacted_text_only".to_string(),
+            span_count: detected_spans.len() as u32,
+            by_label,
+            decoded_mismatch,
+        },
+        report,
+    })
+}
+
+fn safe_privacy_filter_label(raw_label: Option<&str>, report: &mut RedactionReport) -> String {
+    let Some(raw_label) = raw_label else {
+        return "unknown".to_string();
+    };
+    let normalized = raw_label
+        .trim()
+        .chars()
+        .map(|character| {
+            if character == '-' {
+                '_'
+            } else {
+                character.to_ascii_lowercase()
+            }
+        })
+        .collect::<String>();
+    let allowed = matches!(
+        normalized.as_str(),
+        "account_number"
+            | "credit_card"
+            | "ip_address"
+            | "private_address"
+            | "private_date"
+            | "private_email"
+            | "private_location"
+            | "private_name"
+            | "private_person"
+            | "private_phone"
+            | "private_url"
+            | "secret"
+            | "secret_like"
+            | "ssn"
+    );
+    if allowed {
+        return normalized;
+    }
+    report.add_warning("Privacy Filter sidecar emitted unsupported span label; mapped to unknown.");
+    "unknown".to_string()
+}
+
+/// Hash arbitrary bytes for hash-only logging surfaces.
+pub fn privacy_filter_bytes_hash(bytes: &[u8]) -> String {
+    let digest = Sha256::digest(bytes);
+    format!("sha256:{}", hex::encode(digest))
+}
+
+/// SHA-256 a UTF-8 string for canary attestation.
+pub fn canonical_hash(content: &str) -> String {
+    privacy_filter_bytes_hash(content.as_bytes())
+}
+
+/// Identify naive token leaks: any whitespace-separated token in `original`
+/// that re-appears verbatim in `redacted` is considered leaked. Returns the
+/// `sha256:<hex>` hashes of leaked tokens (never the raw token value).
+pub fn canary_leaked_tokens(original: &str, redacted: &str) -> Vec<String> {
+    let mut leaked = Vec::new();
+    for token in original.split_whitespace() {
+        if token.len() < 4 {
+            continue;
+        }
+        if redacted.contains(token) {
+            let hash = canonical_hash(token);
+            if !leaked.contains(&hash) {
+                leaked.push(hash);
+            }
+        }
+    }
+    leaked
+}
+
+/// Build an adapter from environment variables, preferring the canonical
+/// `TRACE_COMMONS_PRIVACY_FILTER_*` names and falling back to the
+/// Ironclaw-era `IRONCLAW_TRACE_PRIVACY_FILTER_*` names. Returns `None` when
+/// no command is configured.
+pub fn adapter_from_env() -> Option<Arc<dyn PrivacyFilterAdapter>> {
+    let command = env_with_fallback("PRIVACY_FILTER_COMMAND")?;
+    let command = command.trim();
+    if command.is_empty() {
+        return None;
+    }
+
+    let args = env_with_fallback("PRIVACY_FILTER_ARGS")
+        .map(|raw| {
+            raw.split_whitespace()
+                .map(ToOwned::to_owned)
+                .collect::<Vec<_>>()
+        })
+        .unwrap_or_default();
+    let mut adapter = CommandPrivacyFilterAdapter::new(command).with_args(args);
+    if let Some(timeout_ms) = parse_usize_env("PRIVACY_FILTER_TIMEOUT_MS") {
+        adapter = adapter.with_timeout(Duration::from_millis(timeout_ms as u64));
+    }
+    if let Some(max_input_bytes) = parse_usize_env("PRIVACY_FILTER_MAX_INPUT_BYTES") {
+        adapter = adapter.with_input_limit(max_input_bytes);
+    }
+    let max_stdout = parse_usize_env("PRIVACY_FILTER_MAX_STDOUT_BYTES");
+    let max_stderr = parse_usize_env("PRIVACY_FILTER_MAX_STDERR_BYTES");
+    if max_stdout.is_some() || max_stderr.is_some() {
+        adapter = adapter.with_output_limits(
+            max_stdout.unwrap_or(PRIVACY_FILTER_SIDECAR_DEFAULT_MAX_STDOUT_BYTES),
+            max_stderr.unwrap_or(PRIVACY_FILTER_SIDECAR_DEFAULT_MAX_STDERR_BYTES),
+        );
+    }
+    Some(Arc::new(adapter))
+}
+
+fn env_with_fallback(suffix: &str) -> Option<String> {
+    let canonical = format!("TRACE_COMMONS_{suffix}");
+    if let Ok(value) = std::env::var(&canonical) {
+        if !value.is_empty() {
+            return Some(value);
+        }
+    }
+    let legacy = format!("IRONCLAW_TRACE_{suffix}");
+    match std::env::var(&legacy) {
+        Ok(value) if !value.is_empty() => {
+            warn_legacy_env_once(&legacy, &canonical);
+            Some(value)
+        }
+        _ => None,
+    }
+}
+
+fn warn_legacy_env_once(legacy: &str, canonical: &str) {
+    static WARN: Once = Once::new();
+    WARN.call_once(|| {
+        tracing::warn!(
+            target: "trace_commons::privacy_filter",
+            legacy = legacy,
+            canonical = canonical,
+            "privacy-filter sidecar configured via legacy Ironclaw env var; migrate to TRACE_COMMONS_* names"
+        );
+    });
+}
+
+fn parse_usize_env(suffix: &str) -> Option<usize> {
+    env_with_fallback(suffix).and_then(|value| value.trim().parse::<usize>().ok())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    /// Guard env vars used by `adapter_from_env` tests; ensures we restore
+    /// the prior process state even on panic. Used serially to avoid
+    /// cross-test races on shared environment.
+    fn env_test_lock() -> std::sync::MutexGuard<'static, ()> {
+        static LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
+        LOCK.lock().unwrap_or_else(|p| p.into_inner())
+    }
+
+    struct EnvGuard {
+        keys: Vec<(String, Option<String>)>,
+        _lock: std::sync::MutexGuard<'static, ()>,
+    }
+    impl EnvGuard {
+        fn capture(keys: &[&str]) -> Self {
+            let lock = env_test_lock();
+            let snapshot = keys
+                .iter()
+                .map(|k| (k.to_string(), std::env::var(k).ok()))
+                .collect();
+            for key in keys {
+                unsafe { std::env::remove_var(key) };
+            }
+            EnvGuard {
+                keys: snapshot,
+                _lock: lock,
+            }
+        }
+        fn set(&self, key: &str, value: &str) {
+            unsafe { std::env::set_var(key, value) };
+        }
+    }
+    impl Drop for EnvGuard {
+        fn drop(&mut self) {
+            for (key, prior) in &self.keys {
+                match prior {
+                    Some(value) => unsafe { std::env::set_var(key, value) },
+                    None => unsafe { std::env::remove_var(key) },
+                }
+            }
+        }
+    }
+
+    const ENV_KEYS: &[&str] = &[
+        "TRACE_COMMONS_PRIVACY_FILTER_COMMAND",
+        "TRACE_COMMONS_PRIVACY_FILTER_ARGS",
+        "TRACE_COMMONS_PRIVACY_FILTER_TIMEOUT_MS",
+        "TRACE_COMMONS_PRIVACY_FILTER_MAX_INPUT_BYTES",
+        "TRACE_COMMONS_PRIVACY_FILTER_MAX_STDOUT_BYTES",
+        "TRACE_COMMONS_PRIVACY_FILTER_MAX_STDERR_BYTES",
+        "IRONCLAW_TRACE_PRIVACY_FILTER_COMMAND",
+        "IRONCLAW_TRACE_PRIVACY_FILTER_ARGS",
+        "IRONCLAW_TRACE_PRIVACY_FILTER_TIMEOUT_MS",
+        "IRONCLAW_TRACE_PRIVACY_FILTER_MAX_INPUT_BYTES",
+        "IRONCLAW_TRACE_PRIVACY_FILTER_MAX_STDOUT_BYTES",
+        "IRONCLAW_TRACE_PRIVACY_FILTER_MAX_STDERR_BYTES",
+    ];
+
+    #[test]
+    fn parses_safe_redaction_from_output() {
+        let value = json!({
+            "redacted_text": "Hello [REDACTED]",
+            "detected_spans": [
+                {"label": "private_email"},
+                {"label": "Secret"},
+                {"label": "weird-label"}
+            ],
+            "schema_version": 2,
+            "decoded_mismatch": false,
+        });
+        let red = safe_privacy_filter_redaction_from_output(&value).unwrap();
+        assert_eq!(red.redacted_text, "Hello [REDACTED]");
+        assert_eq!(red.summary.schema_version, 2);
+        assert_eq!(red.summary.span_count, 3);
+        assert_eq!(red.summary.by_label.get("private_email"), Some(&1));
+        assert_eq!(red.summary.by_label.get("secret"), Some(&1));
+        assert_eq!(red.summary.by_label.get("unknown"), Some(&1));
+        assert!(red.report.blocked_secret_detected);
+        assert!(
+            red.report
+                .warnings
+                .iter()
+                .any(|w| w.contains("unsupported span label"))
+        );
+    }
+
+    #[test]
+    fn parser_rejects_missing_redacted_text() {
+        let value = json!({"detected_spans": []});
+        assert!(safe_privacy_filter_redaction_from_output(&value).is_err());
+    }
+
+    #[test]
+    fn canary_leaked_tokens_detects_residual_canary() {
+        let original = "trace-canary.person@example.invalid tc_canary_secret_0123456789abcdef";
+        let redacted_clean = "[REDACTED_EMAIL] [REDACTED_SECRET]";
+        assert!(canary_leaked_tokens(original, redacted_clean).is_empty());
+
+        let redacted_leak = "[REDACTED] tc_canary_secret_0123456789abcdef";
+        let leaks = canary_leaked_tokens(original, redacted_leak);
+        assert_eq!(leaks.len(), 1);
+        assert!(leaks[0].starts_with("sha256:"));
+    }
+
+    #[tokio::test]
+    async fn noop_adapter_returns_none() {
+        let adapter = NoopPrivacyFilterAdapter;
+        assert!(adapter.redact_text("anything").await.unwrap().is_none());
+    }
+
+    #[test]
+    fn adapter_from_env_returns_none_when_unset() {
+        let _guard = EnvGuard::capture(ENV_KEYS);
+        assert!(adapter_from_env().is_none());
+    }
+
+    #[test]
+    fn adapter_from_env_prefers_canonical_over_legacy() {
+        let guard = EnvGuard::capture(ENV_KEYS);
+        guard.set("TRACE_COMMONS_PRIVACY_FILTER_COMMAND", "/usr/bin/canonical");
+        guard.set("IRONCLAW_TRACE_PRIVACY_FILTER_COMMAND", "/usr/bin/legacy");
+        let adapter = adapter_from_env().expect("adapter built");
+        drop(adapter);
+        // Sanity: rebuild via the concrete constructor with the same envs to
+        // exercise the timeout/limit parsing branch.
+        guard.set("TRACE_COMMONS_PRIVACY_FILTER_TIMEOUT_MS", "2500");
+        guard.set("TRACE_COMMONS_PRIVACY_FILTER_MAX_INPUT_BYTES", "1024");
+        guard.set("TRACE_COMMONS_PRIVACY_FILTER_MAX_STDOUT_BYTES", "2048");
+        guard.set("TRACE_COMMONS_PRIVACY_FILTER_MAX_STDERR_BYTES", "512");
+        guard.set("TRACE_COMMONS_PRIVACY_FILTER_ARGS", "--mode redact");
+        let adapter2 = adapter_from_env().expect("adapter built with overrides");
+        drop(adapter2);
+    }
+
+    #[test]
+    fn adapter_from_env_falls_back_to_legacy() {
+        let guard = EnvGuard::capture(ENV_KEYS);
+        guard.set("IRONCLAW_TRACE_PRIVACY_FILTER_COMMAND", "/usr/bin/legacy");
+        assert!(adapter_from_env().is_some());
+    }
+
+    #[cfg(unix)]
+    #[tokio::test]
+    async fn command_adapter_round_trip_via_shell() {
+        // Use a tiny shell pipeline that ignores stdin and emits a known
+        // sidecar response. The adapter must parse it into a safe summary.
+        let stdout = serde_json::json!({
+            "redacted_text": "[REDACTED]",
+            "detected_spans": [{"label": "private_email"}],
+            "schema_version": 1,
+            "decoded_mismatch": false,
+        })
+        .to_string();
+        let script = format!(
+            "cat >/dev/null; printf '%s' '{}'",
+            stdout.replace('\'', "'\\''")
+        );
+        let adapter = CommandPrivacyFilterAdapter::new("/bin/sh")
+            .with_args(["-c", &script])
+            .with_timeout(Duration::from_secs(5));
+        let red = adapter.redact_text("hello").await.unwrap().expect("some");
+        assert_eq!(red.redacted_text, "[REDACTED]");
+        assert_eq!(red.summary.span_count, 1);
+        assert_eq!(red.summary.by_label.get("private_email"), Some(&1));
+    }
+
+    #[test]
+    fn canonical_hash_format() {
+        let h = canonical_hash("hello");
+        assert!(h.starts_with("sha256:"));
+        assert_eq!(h.len(), "sha256:".len() + 64);
+    }
+}
diff --git a/crates/trace-commons-server/src/bin/trace-commons-tenant.rs b/crates/trace-commons-server/src/bin/trace-commons-tenant.rs
index 35920281f..ee89043c3 100644
--- a/crates/trace-commons-server/src/bin/trace-commons-tenant.rs
+++ b/crates/trace-commons-server/src/bin/trace-commons-tenant.rs
@@ -6,22 +6,25 @@
 //! share a single `--bearer-token-env` defaulting to
 //! `TRACE_COMMONS_TENANT_BEARER`. Two subcommands (`tenant-principal-ref`,
 //! `privacy-filter-canary`) do not hit the server: the first derives a
-//! principal ref locally; the second is intentionally stubbed in this
-//! operator binary because the underlying privacy-filter sidecar is not yet
-//! ported off the Ironclaw runtime.
+//! principal ref locally; the second spawns a locally configured
+//! privacy-filter sidecar subprocess and confirms it scrubs canary tokens.
+//! See `docs/operator/operator-binaries.md` for the sidecar env-var
+//! contract.
 
 #[path = "operator_common/mod.rs"]
 mod operator_common;
 
-use std::io::{stdout, Write};
+use std::io::{Write, stdout};
 use std::path::PathBuf;
+use std::time::Duration;
 
 use anyhow::Result;
 use clap::{Parser, Subcommand, ValueEnum};
 use reqwest::Method;
 use serde_json::Value;
 use sha2::{Digest, Sha256};
-use trace_commons_operator_client::{format as oc_format, host_allowlist::HostAllowlist, Client};
+use trace_commons_operator_client::privacy_filter;
+use trace_commons_operator_client::{Client, format as oc_format, host_allowlist::HostAllowlist};
 use uuid::Uuid;
 
 use operator_common::{render_items, render_kv_fields, sanitized_url};
@@ -78,7 +81,7 @@ pub(crate) enum TenantSubcommand {
     AuditEvents(AuditEventsArgs),
     /// List central trace metadata with optional reviewer filters.
     ListTraces(ListTracesArgs),
-    /// Run a local Privacy Filter sidecar canary check (stub in operator binary).
+    /// Run a local Privacy Filter sidecar canary check.
     PrivacyFilterCanary(PrivacyFilterCanaryArgs),
 }
 
@@ -363,10 +366,8 @@ async fn dispatch(cli: Cli) -> Result<()> {
         TenantSubcommand::TenantPrincipalRef(args) => {
             return tenant_principal_ref(args, cli.json);
         }
-        TenantSubcommand::PrivacyFilterCanary(_args) => {
-            anyhow::bail!(
-                "privacy-filter-canary is not yet ported to the operator binary; run the local sidecar canary via legacy Ironclaw tooling"
-            );
+        TenantSubcommand::PrivacyFilterCanary(args) => {
+            return privacy_filter_canary(args, cli.json).await;
         }
         _ => {}
     }
@@ -423,7 +424,9 @@ async fn dispatch(cli: Cli) -> Result<()> {
 
 async fn tenant_policy_get(client: &Client, endpoint: &str, json: bool) -> Result<()> {
     let path = "/v1/admin/tenant-policy";
-    let value: Value = client.call_json::<(), Value>(Method::GET, path, &[], None).await?;
+    let value: Value = client
+        .call_json::<(), Value>(Method::GET, path, &[], None)
+        .await?;
     if json {
         emit_json(endpoint, "GET", path, &value)?;
     } else {
@@ -685,7 +688,9 @@ async fn ranker_training_export(
         owned.push(("privacy_risk", risk.as_str().to_string()));
     }
     let query = borrow_query(&owned);
-    let raw = client.call_raw::<()>(Method::GET, path, &query, None).await?;
+    let raw = client
+        .call_raw::<()>(Method::GET, path, &query, None)
+        .await?;
     let value: Value = serde_json::from_str(&raw).unwrap_or(Value::Null);
 
     if let Some(output) = args.output.as_ref() {
@@ -858,11 +863,16 @@ fn tenant_principal_ref(args: &TenantPrincipalRefArgs, json: bool) -> Result<()>
         }
         ("static_token", principal_storage_ref(&token))
     } else {
-        let tenant_id = signed_tenant_id
-            .ok_or_else(|| anyhow::anyhow!("--signed-tenant-id is required with --signed-actor-ref"))?;
-        let actor_ref = signed_actor_ref
-            .ok_or_else(|| anyhow::anyhow!("--signed-actor-ref is required with --signed-tenant-id"))?;
-        ("signed_claim", signed_claim_principal_ref(&tenant_id, &actor_ref))
+        let tenant_id = signed_tenant_id.ok_or_else(|| {
+            anyhow::anyhow!("--signed-tenant-id is required with --signed-actor-ref")
+        })?;
+        let actor_ref = signed_actor_ref.ok_or_else(|| {
+            anyhow::anyhow!("--signed-actor-ref is required with --signed-tenant-id")
+        })?;
+        (
+            "signed_claim",
+            signed_claim_principal_ref(&tenant_id, &actor_ref),
+        )
     };
 
     if json {
@@ -870,7 +880,12 @@ fn tenant_principal_ref(args: &TenantPrincipalRefArgs, json: bool) -> Result<()>
             "mode": mode,
             "principal_ref": principal_ref,
         });
-        oc_format::emit_json(&mut stdout(), "LOCAL", "trace-commons-tenant/principal-ref", &value)?;
+        oc_format::emit_json(
+            &mut stdout(),
+            "LOCAL",
+            "trace-commons-tenant/principal-ref",
+            &value,
+        )?;
     } else {
         println!("{principal_ref}");
     }
@@ -891,6 +906,91 @@ fn sha256_prefixed(value: &str) -> String {
     format!("sha256:{}", hex::encode(digest))
 }
 
+async fn privacy_filter_canary(args: &PrivacyFilterCanaryArgs, json: bool) -> Result<()> {
+    let adapter = privacy_filter::adapter_from_env().ok_or_else(|| {
+        anyhow::anyhow!(
+            "TRACE_COMMONS_PRIVACY_FILTER_COMMAND is not set; no local privacy filter sidecar is configured"
+        )
+    })?;
+    let timeout = Duration::from_secs(args.timeout_seconds.max(1));
+    let redaction = tokio::time::timeout(timeout, adapter.redact_text(&args.text))
+        .await
+        .map_err(|_| anyhow::anyhow!("privacy filter canary timed out after {:?}", timeout))?
+        .map_err(|e| anyhow::anyhow!("privacy filter canary failed: {e}"))?;
+    let Some(redaction) = redaction else {
+        anyhow::bail!("privacy filter sidecar returned no redaction for canary text");
+    };
+    let leaked_tokens = privacy_filter::canary_leaked_tokens(&args.text, &redaction.redacted_text);
+    let passed = leaked_tokens.is_empty();
+    let input_hash = privacy_filter::canonical_hash(&args.text);
+    let redacted_hash = privacy_filter::canonical_hash(&redaction.redacted_text);
+
+    if json {
+        let value = serde_json::json!({
+            "canary_version": "trace-commons-privacy-filter-canary-v1",
+            "passed": passed,
+            "input_hash": input_hash,
+            "redacted_output_hash": redacted_hash,
+            "summary": redaction.summary,
+            "report": redaction.report,
+            "leaked_token_hashes": leaked_tokens,
+        });
+        oc_format::emit_json(
+            &mut stdout(),
+            "LOCAL",
+            "trace-commons-tenant/privacy-filter-canary",
+            &value,
+        )?;
+    } else {
+        let mut out = stdout();
+        writeln!(
+            out,
+            "privacy-filter canary: {}",
+            if passed { "PASS" } else { "FAIL" }
+        )?;
+        writeln!(out, "  input_hash:           {input_hash}")?;
+        writeln!(out, "  redacted_output_hash: {redacted_hash}")?;
+        writeln!(
+            out,
+            "  span_count:           {}",
+            redaction.summary.span_count
+        )?;
+        writeln!(
+            out,
+            "  schema_version:       {}",
+            redaction.summary.schema_version
+        )?;
+        writeln!(
+            out,
+            "  decoded_mismatch:     {}",
+            redaction.summary.decoded_mismatch
+        )?;
+        if !redaction.summary.by_label.is_empty() {
+            writeln!(out, "  by_label:")?;
+            for (label, count) in &redaction.summary.by_label {
+                writeln!(out, "    {label}: {count}")?;
+            }
+        }
+        if redaction.report.blocked_secret_detected {
+            writeln!(out, "  blocked_secret_detected: true")?;
+        }
+        for warning in &redaction.report.warnings {
+            writeln!(out, "  warning: {warning}")?;
+        }
+        if !leaked_tokens.is_empty() {
+            writeln!(out, "  leaked_token_hashes:")?;
+            for h in &leaked_tokens {
+                writeln!(out, "    {h}")?;
+            }
+        }
+    }
+
+    if !passed {
+        anyhow::bail!("privacy filter canary failed: sidecar output retained canary token(s)");
+    }
+    Ok(())
+}
+
 // --- helpers ---
 
 fn borrow_query<'a>(owned: &'a [(&'a str, String)]) -> Vec<(&'a str, &'a str)> {
@@ -1035,11 +1135,7 @@ mod tests {
     #[test]
     fn cli_parses_tenant_principal_ref_with_token_env() {
         // No --endpoint required for this subcommand.
-        let cli = parse_no_endpoint(&[
-            "tenant-principal-ref",
-            "--token-env",
-            "SOME_TOKEN_VAR",
-        ]);
+        let cli = parse_no_endpoint(&["tenant-principal-ref", "--token-env", "SOME_TOKEN_VAR"]);
         match cli.command {
             TenantSubcommand::TenantPrincipalRef(args) => {
                 assert_eq!(args.token_env.as_deref(), Some("SOME_TOKEN_VAR"));
@@ -1132,7 +1228,10 @@ mod tests {
     #[test]
     fn cli_parses_ranker_training_pairs() {
         let cli = parse(&["ranker-training-pairs", "--limit", "5"]);
-        assert!(matches!(cli.command, TenantSubcommand::RankerTrainingPairs(_)));
+        assert!(matches!(
+            cli.command,
+            TenantSubcommand::RankerTrainingPairs(_)
+        ));
     }
 
     #[test]
@@ -1185,6 +1284,38 @@ mod tests {
         }
     }
 
+    #[tokio::test]
+    async fn privacy_filter_canary_errors_when_unconfigured() {
+        // Capture and clear the env vars the adapter reads so this test
+        // is hermetic regardless of operator-level configuration.
+        let keys = [
+            "TRACE_COMMONS_PRIVACY_FILTER_COMMAND",
+            "IRONCLAW_TRACE_PRIVACY_FILTER_COMMAND",
+        ];
+        let prior: Vec<_> = keys.iter().map(|k| (*k, std::env::var(k).ok())).collect();
+        for k in &keys {
+            unsafe { std::env::remove_var(k) };
+        }
+        let args = PrivacyFilterCanaryArgs {
+            text: "trace-canary.person@example.invalid".to_string(),
+            timeout_seconds: 2,
+        };
+        let err = privacy_filter_canary(&args, true).await.unwrap_err();
+        let msg = err.to_string();
+        assert!(
+            msg.contains("TRACE_COMMONS_PRIVACY_FILTER_COMMAND"),
+            "expected env-var error, got: {msg}"
+        );
+        // Confirm we no longer emit the legacy stub message.
+        assert!(!msg.contains("not yet ported"), "stub message must be gone");
+        for (k, v) in prior {
+            match v {
+                Some(value) => unsafe { std::env::set_var(k, value) },
+                None => unsafe { std::env::remove_var(k) },
+            }
+        }
+    }
+
     #[test]
     fn cli_rejects_unknown_subcommand() {
         let err = Cli::try_parse_from([
@@ -1283,21 +1414,21 @@ mod tests {
         Mock::given(method("GET"))
             .and(wm_path("/v1/admin/tenant-policy"))
             .and(header("authorization", "Bearer tenant-secret"))
-            .respond_with(
-                ResponseTemplate::new(200).set_body_json(serde_json::json!({
-                    "tenant_id": "t-1",
-                    "policy_version": "v1",
-                    "allowed_consent_scopes": ["benchmark_only"],
-                    "allowed_uses": ["benchmark_generation"],
-                })),
-            )
+            .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                "tenant_id": "t-1",
+                "policy_version": "v1",
+                "allowed_consent_scopes": ["benchmark_only"],
+                "allowed_uses": ["benchmark_generation"],
+            })))
             .expect(1)
             .mount(&server)
             .await;
         let env = unique_bearer_env();
         let _g = EnvGuard::set(env.clone(), "tenant-secret");
         let client = Client::builder(server.uri(), env).build().unwrap();
-        tenant_policy_get(&client, &server.uri(), true).await.unwrap();
+        tenant_policy_get(&client, &server.uri(), true)
+            .await
+            .unwrap();
     }
 
     #[tokio::test]
@@ -1310,11 +1441,9 @@ mod tests {
                 "allowed_consent_scopes": ["benchmark_only", "model_training"],
                 "allowed_uses": ["benchmark_generation"],
             })))
-            .respond_with(
-                ResponseTemplate::new(200).set_body_json(serde_json::json!({
-                    "policy_version": "v2",
-                })),
-            )
+            .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                "policy_version": "v2",
+            })))
             .expect(1)
             .mount(&server)
             .await;
@@ -1461,10 +1590,13 @@ mod tests {
         let server = MockServer::start().await;
         let id = Uuid::new_v4();
         Mock::given(method("POST"))
-            .and(wm_path(format!("/v1/admin/tenant-access-grants/{id}/revoke")))
+            .and(wm_path(format!(
+                "/v1/admin/tenant-access-grants/{id}/revoke"
+            )))
             .and(body_json(serde_json::json!({ "reason": "key compromise" })))
             .respond_with(
-                ResponseTemplate::new(200).set_body_json(serde_json::json!({ "status": "revoked" })),
+                ResponseTemplate::new(200)
+                    .set_body_json(serde_json::json!({ "status": "revoked" })),
             )
             .expect(1)
             .mount(&server)
@@ -1549,13 +1681,11 @@ mod tests {
         let server = MockServer::start().await;
         Mock::given(method("GET"))
             .and(wm_path("/v1/ranker/training-candidates"))
-            .respond_with(
-                ResponseTemplate::new(200).set_body_json(serde_json::json!({
-                    "candidates": [
-                        {"submission_id": "s-1", "ranker_score": 0.9}
-                    ]
-                })),
-            )
+            .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                "candidates": [
+                    {"submission_id": "s-1", "ranker_score": 0.9}
+                ]
+            })))
             .expect(1)
             .mount(&server)
             .await;
diff --git a/docs/operator/operator-binaries.md b/docs/operator/operator-binaries.md
index ca907f455..04c548ef6 100644
--- a/docs/operator/operator-binaries.md
+++ b/docs/operator/operator-binaries.md
@@ -74,10 +74,25 @@ consume a bearer:
 
 - `tenant-principal-ref` — derives the stored `principal_ref` locally from
   either a static token or a signed-claim `(tenant_id, actor_ref)` pair.
-- `privacy-filter-canary` — stubbed in the operator binary; the underlying
-  local sidecar is not yet ported off the Ironclaw runtime. The subcommand
-  fails fast with a clear message; run the canary via legacy local tooling
-  until A2.8 ports the sidecar.
+- `privacy-filter-canary` — spawns the locally configured privacy-filter
+  sidecar, pipes a canary string through it, and verifies no canary token
+  survives the redaction. The subcommand reads its configuration from
+  environment variables:
+
+  | Canonical | Legacy fallback | Purpose |
+  |---|---|---|
+  | `TRACE_COMMONS_PRIVACY_FILTER_COMMAND` | `IRONCLAW_TRACE_PRIVACY_FILTER_COMMAND` | Sidecar executable path. Required. |
+  | `TRACE_COMMONS_PRIVACY_FILTER_ARGS` | `IRONCLAW_TRACE_PRIVACY_FILTER_ARGS` | Whitespace-separated argv. |
+  | `TRACE_COMMONS_PRIVACY_FILTER_TIMEOUT_MS` | `IRONCLAW_TRACE_PRIVACY_FILTER_TIMEOUT_MS` | Wall-clock timeout (ms). |
+  | `TRACE_COMMONS_PRIVACY_FILTER_MAX_INPUT_BYTES` | `IRONCLAW_TRACE_PRIVACY_FILTER_MAX_INPUT_BYTES` | Refuse oversized inputs. |
+  | `TRACE_COMMONS_PRIVACY_FILTER_MAX_STDOUT_BYTES` | `IRONCLAW_TRACE_PRIVACY_FILTER_MAX_STDOUT_BYTES` | Cap captured stdout. |
+  | `TRACE_COMMONS_PRIVACY_FILTER_MAX_STDERR_BYTES` | `IRONCLAW_TRACE_PRIVACY_FILTER_MAX_STDERR_BYTES` | Cap captured stderr. |
+
+  When both names are set, the canonical `TRACE_COMMONS_*` value wins; a
+  one-shot `tracing::warn!` is emitted whenever the legacy name is used so
+  operators know to migrate. The subcommand exits non-zero if no command is
+  configured, the sidecar times out, or the redacted output retains a
+  canary token (hash-only diagnostics, never the raw token).
 
 ## Common workflows
 
@@ -210,5 +225,5 @@ binary surfaces each as `Error: <variant-name>: <message>`.
 - New subcommand in any binary: add a row to the binaries-at-a-glance
   table and (if it introduces a new bearer surface) the env-var matrix.
 - New foundation `Error` variant: add a row to the troubleshooting table.
-- The `privacy-filter-canary` stub is replaced by a real port: remove
-  the deferred-note from the binaries section and add a workflow row.
+- New `TRACE_COMMONS_PRIVACY_FILTER_*` env var added to the sidecar
+  contract: add a row to the table under `privacy-filter-canary` above.

From 4191101dd384e4607e4e1bfa4d5c79c99aeff7c5 Mon Sep 17 00:00:00 2001
From: Zaki <zaki@iqlusion.io>
Date: Tue, 19 May 2026 17:17:36 -0700
Subject: [PATCH 6/7] cargo fmt across operator-client and operator binaries

CI on PR #124 surfaced fmt diffs across the operator-client foundation
and the review/admin/worker binaries. Applied cargo fmt --all to bring
the stack into compliance. Pure formatting; zero behavior change.
---
 .../src/client.rs                             |  26 +++--
 .../src/error.rs                              |  17 ++-
 .../src/format.rs                             |   2 +-
 .../src/host_allowlist.rs                     |  14 +--
 .../src/bin/trace-commons-admin.rs            | 104 ++++++++++--------
 .../src/bin/trace-commons-review.rs           |  66 +++++++----
 .../src/bin/trace-commons-worker.rs           |  70 ++++++------
 7 files changed, 171 insertions(+), 128 deletions(-)

diff --git a/crates/trace-commons-operator-client/src/client.rs b/crates/trace-commons-operator-client/src/client.rs
index 0f686cc20..e729cdc66 100644
--- a/crates/trace-commons-operator-client/src/client.rs
+++ b/crates/trace-commons-operator-client/src/client.rs
@@ -12,10 +12,10 @@
 use std::time::Duration;
 
 use reqwest::Method;
-use serde::de::DeserializeOwned;
 use serde::Serialize;
+use serde::de::DeserializeOwned;
 
-use crate::error::{parse_error_label, Error, Result};
+use crate::error::{Error, Result, parse_error_label};
 use crate::host_allowlist::HostAllowlist;
 
 const DEFAULT_TIMEOUT: Duration = Duration::from_secs(30);
@@ -36,7 +36,10 @@ pub struct ClientBuilder {
 }
 
 impl Client {
-    pub fn builder(endpoint: impl Into<String>, bearer_token_env: impl Into<String>) -> ClientBuilder {
+    pub fn builder(
+        endpoint: impl Into<String>,
+        bearer_token_env: impl Into<String>,
+    ) -> ClientBuilder {
         ClientBuilder {
             endpoint: endpoint.into(),
             bearer_token_env: bearer_token_env.into(),
@@ -171,10 +174,11 @@ impl ClientBuilder {
     }
 
     pub fn build(self) -> Result<Client> {
-        let endpoint = url::Url::parse(&self.endpoint).map_err(|source| Error::InvalidEndpoint {
-            endpoint: self.endpoint.clone(),
-            source,
-        })?;
+        let endpoint =
+            url::Url::parse(&self.endpoint).map_err(|source| Error::InvalidEndpoint {
+                endpoint: self.endpoint.clone(),
+                source,
+            })?;
         // Pre-flight the allowlist before we even hand back a Client, so
         // operators see the rejection at startup rather than at first request.
         self.host_allowlist.check(&endpoint)?;
@@ -300,11 +304,9 @@ mod tests {
             .and(path("/v1/traces/quarantine"))
             .and(query_param("state", "leased"))
             .and(header("authorization", "Bearer secret"))
-            .respond_with(
-                ResponseTemplate::new(200).set_body_json(serde_json::json!({
-                    "items": ["sub-1", "sub-2"],
-                })),
-            )
+            .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                "items": ["sub-1", "sub-2"],
+            })))
             .expect(1)
             .mount(&server)
             .await;
diff --git a/crates/trace-commons-operator-client/src/error.rs b/crates/trace-commons-operator-client/src/error.rs
index ac0733a3f..252b37665 100644
--- a/crates/trace-commons-operator-client/src/error.rs
+++ b/crates/trace-commons-operator-client/src/error.rs
@@ -121,24 +121,21 @@ impl Error {
     /// the full Debug form is for verbose logging only.
     pub fn user_diagnostic(&self) -> String {
         match self {
-            Error::BearerMissing { env_var } => format!(
-                "credential refused: ${env_var} not set"
-            ),
+            Error::BearerMissing { env_var } => format!("credential refused: ${env_var} not set"),
             Error::InvalidEndpoint { endpoint, .. } => format!(
                 "endpoint URL is malformed: {}",
                 sanitize_url_for_display(endpoint)
             ),
-            Error::HostNotAllowed { host, allowed } => format!(
-                "host {host} blocked by allowed-hosts list ({allowed})"
-            ),
+            Error::HostNotAllowed { host, allowed } => {
+                format!("host {host} blocked by allowed-hosts list ({allowed})")
+            }
             Error::Transport { url, source } => format!(
                 "request to {} failed: {source}",
                 sanitize_url_for_display(url)
             ),
-            Error::HttpFailure { url, status, .. } => format!(
-                "{} returned HTTP {status}",
-                sanitize_url_for_display(url)
-            ),
+            Error::HttpFailure { url, status, .. } => {
+                format!("{} returned HTTP {status}", sanitize_url_for_display(url))
+            }
             Error::ServerLabel {
                 url, status, label, ..
             } => format!(
diff --git a/crates/trace-commons-operator-client/src/format.rs b/crates/trace-commons-operator-client/src/format.rs
index 306a42997..923377ef6 100644
--- a/crates/trace-commons-operator-client/src/format.rs
+++ b/crates/trace-commons-operator-client/src/format.rs
@@ -175,7 +175,7 @@ mod tests {
             &mut buf,
             &["id", "status"],
             &[
-                vec!["sub-1".into()], // skipped
+                vec!["sub-1".into()],                                    // skipped
                 vec!["sub-2".into(), "approved".into(), "extra".into()], // skipped
                 vec!["sub-3".into(), "leased".into()],
             ],
diff --git a/crates/trace-commons-operator-client/src/host_allowlist.rs b/crates/trace-commons-operator-client/src/host_allowlist.rs
index 15ccd9a2c..651e398e2 100644
--- a/crates/trace-commons-operator-client/src/host_allowlist.rs
+++ b/crates/trace-commons-operator-client/src/host_allowlist.rs
@@ -80,11 +80,7 @@ impl HostAllowlist {
         } else {
             Err(Error::HostNotAllowed {
                 host,
-                allowed: allowed
-                    .iter()
-                    .cloned()
-                    .collect::<Vec<_>>()
-                    .join(","),
+                allowed: allowed.iter().cloned().collect::<Vec<_>>().join(","),
             })
         }
     }
@@ -102,14 +98,18 @@ mod tests {
     fn permissive_allowlist_lets_anything_through() {
         let allowlist = HostAllowlist::permissive();
         assert!(!allowlist.is_enforcing());
-        allowlist.check(&url("https://evil.example/v1/traces")).unwrap();
+        allowlist
+            .check(&url("https://evil.example/v1/traces"))
+            .unwrap();
     }
 
     #[test]
     fn csv_allowlist_enforces_exact_match() {
         let allowlist = HostAllowlist::from_csv("api.example,staging.example");
         assert!(allowlist.is_enforcing());
-        allowlist.check(&url("https://api.example/v1/traces")).unwrap();
+        allowlist
+            .check(&url("https://api.example/v1/traces"))
+            .unwrap();
         allowlist
             .check(&url("https://staging.example/v1/traces"))
             .unwrap();
diff --git a/crates/trace-commons-server/src/bin/trace-commons-admin.rs b/crates/trace-commons-server/src/bin/trace-commons-admin.rs
index c45cf78a7..6f384b847 100644
--- a/crates/trace-commons-server/src/bin/trace-commons-admin.rs
+++ b/crates/trace-commons-server/src/bin/trace-commons-admin.rs
@@ -7,14 +7,14 @@
 #[path = "operator_common/mod.rs"]
 mod operator_common;
 
-use std::io::{stdout, Write};
+use std::io::{Write, stdout};
 use std::path::PathBuf;
 
 use anyhow::Result;
 use clap::{Parser, Subcommand, ValueEnum};
 use reqwest::Method;
 use serde_json::Value;
-use trace_commons_operator_client::{format as oc_format, host_allowlist::HostAllowlist, Client};
+use trace_commons_operator_client::{Client, format as oc_format, host_allowlist::HostAllowlist};
 use uuid::Uuid;
 
 use operator_common::{render_items, render_json_map, render_kv_fields, sanitized_url};
@@ -395,14 +395,11 @@ fn build_client(cli: &Cli) -> Result<Client> {
     Ok(builder.build()?)
 }
 
-async fn dispatch(
-    client: &Client,
-    endpoint: &str,
-    cmd: AdminSubcommand,
-    json: bool,
-) -> Result<()> {
+async fn dispatch(client: &Client, endpoint: &str, cmd: AdminSubcommand, json: bool) -> Result<()> {
     match cmd {
-        AdminSubcommand::MaintenanceRun(args) => maintenance_run(client, endpoint, args, json).await,
+        AdminSubcommand::MaintenanceRun(args) => {
+            maintenance_run(client, endpoint, args, json).await
+        }
         AdminSubcommand::RetentionJobsList(args) => {
             retention_jobs_list(client, endpoint, args, json).await
         }
@@ -492,10 +489,19 @@ async fn maintenance_run(
                 ("  derived marked revoked", "derived_marked_revoked"),
                 ("  derived marked expired", "derived_marked_expired"),
                 ("  export cache files pruned", "export_cache_files_pruned"),
-                ("  export provenance invalidated", "export_provenance_invalidated"),
-                ("  benchmark artifacts invalidated", "benchmark_artifacts_invalidated"),
+                (
+                    "  export provenance invalidated",
+                    "export_provenance_invalidated",
+                ),
+                (
+                    "  benchmark artifacts invalidated",
+                    "benchmark_artifacts_invalidated",
+                ),
                 ("  trace object files deleted", "trace_object_files_deleted"),
-                ("  encrypted artifacts deleted", "encrypted_artifacts_deleted"),
+                (
+                    "  encrypted artifacts deleted",
+                    "encrypted_artifacts_deleted",
+                ),
                 ("  DB mirror backfilled", "db_mirror_backfilled"),
                 ("  vectors indexed", "vector_entries_indexed"),
             ],
@@ -519,7 +525,9 @@ async fn retention_jobs_list(
         owned.push(("status", status.as_str().to_string()));
     }
     let query = borrow_query(&owned);
-    let value: Value = client.call_json::<(), Value>(Method::GET, path, &query, None).await?;
+    let value: Value = client
+        .call_json::<(), Value>(Method::GET, path, &query, None)
+        .await?;
     if json {
         emit_json(endpoint, "GET", path, &value)?;
     } else {
@@ -561,7 +569,9 @@ async fn retention_job_items(
         owned.push(("status", status.as_str().to_string()));
     }
     let query = borrow_query(&owned);
-    let value: Value = client.call_json::<(), Value>(Method::GET, &path, &query, None).await?;
+    let value: Value = client
+        .call_json::<(), Value>(Method::GET, &path, &query, None)
+        .await?;
     if json {
         emit_json(endpoint, "GET", &path, &value)?;
     } else {
@@ -600,7 +610,9 @@ async fn export_access_grants_list(
         owned.push(("dataset_kind", kind));
     }
     let query = borrow_query(&owned);
-    let value: Value = client.call_json::<(), Value>(Method::GET, path, &query, None).await?;
+    let value: Value = client
+        .call_json::<(), Value>(Method::GET, path, &query, None)
+        .await?;
     if json {
         emit_json(endpoint, "GET", path, &value)?;
     } else {
@@ -641,7 +653,9 @@ async fn export_jobs_list(
         owned.push(("dataset_kind", kind));
     }
     let query = borrow_query(&owned);
-    let value: Value = client.call_json::<(), Value>(Method::GET, path, &query, None).await?;
+    let value: Value = client
+        .call_json::<(), Value>(Method::GET, path, &query, None)
+        .await?;
     if json {
         emit_json(endpoint, "GET", path, &value)?;
     } else {
@@ -761,7 +775,9 @@ async fn benchmark_lifecycle_update(
         body.insert("evaluation".into(), Value::Object(evaluation));
     }
     if body.is_empty() {
-        anyhow::bail!("benchmark lifecycle update requires at least one registry or evaluation field");
+        anyhow::bail!(
+            "benchmark lifecycle update requires at least one registry or evaluation field"
+        );
     }
     if let Some(reason) = args.reason {
         body.insert("reason".into(), Value::String(reason));
@@ -883,7 +899,9 @@ async fn replay_dataset_export(
 
 async fn replay_export_manifests(client: &Client, endpoint: &str, json: bool) -> Result<()> {
     let path = "/v1/datasets/replay/manifests";
-    let value: Value = client.call_json::<(), Value>(Method::GET, path, &[], None).await?;
+    let value: Value = client
+        .call_json::<(), Value>(Method::GET, path, &[], None)
+        .await?;
     if json {
         emit_json(endpoint, "GET", path, &value)?;
     } else {
@@ -906,7 +924,9 @@ async fn replay_export_manifests(client: &Client, endpoint: &str, json: bool) ->
 
 async fn analytics_summary(client: &Client, endpoint: &str, json: bool) -> Result<()> {
     let path = "/v1/analytics/summary";
-    let value: Value = client.call_json::<(), Value>(Method::GET, path, &[], None).await?;
+    let value: Value = client
+        .call_json::<(), Value>(Method::GET, path, &[], None)
+        .await?;
     if json {
         emit_json(endpoint, "GET", path, &value)?;
     } else {
@@ -943,7 +963,9 @@ async fn analytics_summary(client: &Client, endpoint: &str, json: bool) -> Resul
 
 async fn operational_summary(client: &Client, endpoint: &str, json: bool) -> Result<()> {
     let path = "/v1/admin/operational-summary";
-    let value: Value = client.call_json::<(), Value>(Method::GET, path, &[], None).await?;
+    let value: Value = client
+        .call_json::<(), Value>(Method::GET, path, &[], None)
+        .await?;
     if json {
         emit_json(endpoint, "GET", path, &value)?;
     } else {
@@ -975,7 +997,9 @@ async fn operational_summary(client: &Client, endpoint: &str, json: bool) -> Res
 
 async fn config_status(client: &Client, endpoint: &str, _json: bool) -> Result<()> {
     let path = "/v1/admin/config-status";
-    let value: Value = client.call_json::<(), Value>(Method::GET, path, &[], None).await?;
+    let value: Value = client
+        .call_json::<(), Value>(Method::GET, path, &[], None)
+        .await?;
     emit_json(endpoint, "GET", path, &value)
 }
 
@@ -1311,20 +1335,20 @@ mod tests {
         Mock::given(method("GET"))
             .and(path("/v1/analytics/summary"))
             .and(header("authorization", "Bearer admin-secret"))
-            .respond_with(
-                ResponseTemplate::new(200).set_body_json(serde_json::json!({
-                    "tenant_id": "tenant-1",
-                    "submissions_total": 42,
-                    "by_status": {"accepted": 30, "rejected": 12},
-                })),
-            )
+            .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                "tenant_id": "tenant-1",
+                "submissions_total": 42,
+                "by_status": {"accepted": 30, "rejected": 12},
+            })))
             .expect(1)
             .mount(&server)
             .await;
         let env = unique_bearer_env();
         let _g = EnvGuard::set(env.clone(), "admin-secret");
         let client = Client::builder(server.uri(), env).build().unwrap();
-        analytics_summary(&client, &server.uri(), true).await.unwrap();
+        analytics_summary(&client, &server.uri(), true)
+            .await
+            .unwrap();
     }
 
     #[tokio::test]
@@ -1336,12 +1360,10 @@ mod tests {
                 "purpose": "weekly",
                 "limit": 50,
             })))
-            .respond_with(
-                ResponseTemplate::new(200).set_body_json(serde_json::json!({
-                    "conversion_id": "conv-1",
-                    "item_count": 5,
-                })),
-            )
+            .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                "conversion_id": "conv-1",
+                "item_count": 5,
+            })))
             .expect(1)
             .mount(&server)
             .await;
@@ -1372,11 +1394,9 @@ mod tests {
             .and(path("/v1/admin/retention/jobs"))
             .and(query_param("limit", "5"))
             .and(query_param("status", "running"))
-            .respond_with(
-                ResponseTemplate::new(200).set_body_json(serde_json::json!({
-                    "items": []
-                })),
-            )
+            .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                "items": []
+            })))
             .expect(1)
             .mount(&server)
             .await;
@@ -1451,8 +1471,6 @@ mod tests {
         )
         .await
         .unwrap_err();
-        assert!(err
-            .to_string()
-            .contains("registry or evaluation"));
+        assert!(err.to_string().contains("registry or evaluation"));
     }
 }
diff --git a/crates/trace-commons-server/src/bin/trace-commons-review.rs b/crates/trace-commons-server/src/bin/trace-commons-review.rs
index 6ebcc4f42..5e9801f75 100644
--- a/crates/trace-commons-server/src/bin/trace-commons-review.rs
+++ b/crates/trace-commons-server/src/bin/trace-commons-review.rs
@@ -8,13 +8,13 @@
 #[path = "operator_common/mod.rs"]
 mod operator_common;
 
-use std::io::{stdout, Write};
+use std::io::{Write, stdout};
 
 use anyhow::Result;
 use clap::{Parser, Subcommand, ValueEnum};
 use reqwest::Method;
 use serde_json::Value;
-use trace_commons_operator_client::{format as oc_format, Client, host_allowlist::HostAllowlist};
+use trace_commons_operator_client::{Client, format as oc_format, host_allowlist::HostAllowlist};
 use uuid::Uuid;
 
 use operator_common::{render_items, render_kv_fields, sanitized_url};
@@ -246,11 +246,15 @@ async fn dispatch(
     json: bool,
 ) -> Result<()> {
     match cmd {
-        ReviewSubcommand::QuarantineList(args) => quarantine_list(client, endpoint, args, json).await,
+        ReviewSubcommand::QuarantineList(args) => {
+            quarantine_list(client, endpoint, args, json).await
+        }
         ReviewSubcommand::ActiveLearningReviewQueue(args) => {
             active_learning(client, endpoint, args, json).await
         }
-        ReviewSubcommand::ReviewDecision(args) => review_decision(client, endpoint, args, json).await,
+        ReviewSubcommand::ReviewDecision(args) => {
+            review_decision(client, endpoint, args, json).await
+        }
         ReviewSubcommand::ReviewLeaseClaim(args) => lease_claim(client, endpoint, args, json).await,
         ReviewSubcommand::ReviewLeaseClaimNext(args) => {
             lease_claim_next(client, endpoint, args, json).await
@@ -279,7 +283,9 @@ async fn quarantine_list(
         owned.push(("lease_filter", filter.as_str().to_string()));
     }
     let query = borrow_query(&owned);
-    let value: Value = client.call_json::<(), Value>(Method::GET, path, &query, None).await?;
+    let value: Value = client
+        .call_json::<(), Value>(Method::GET, path, &query, None)
+        .await?;
     if json {
         emit_json(endpoint, "GET", path, &value)?;
     } else {
@@ -323,7 +329,9 @@ async fn active_learning(
         owned.push(("lease_filter", filter.as_str().to_string()));
     }
     let query = borrow_query(&owned);
-    let value: Value = client.call_json::<(), Value>(Method::GET, path, &query, None).await?;
+    let value: Value = client
+        .call_json::<(), Value>(Method::GET, path, &query, None)
+        .await?;
     if json {
         emit_json(endpoint, "GET", path, &value)?;
     } else {
@@ -371,7 +379,11 @@ async fn review_decision(
         emit_json(endpoint, "POST", &path, &value)?;
     } else {
         let mut out = stdout();
-        writeln!(out, "Recorded central review decision for {}", args.submission_id)?;
+        writeln!(
+            out,
+            "Recorded central review decision for {}",
+            args.submission_id
+        )?;
         render_kv_fields(
             &mut out,
             &value,
@@ -400,7 +412,11 @@ async fn lease_claim(
         emit_json(endpoint, "POST", &path, &value)?;
     } else {
         let mut out = stdout();
-        writeln!(out, "Claimed central review lease for {}", args.submission_id)?;
+        writeln!(
+            out,
+            "Claimed central review lease for {}",
+            args.submission_id
+        )?;
         render_lease_fields(&mut out, &value)?;
     }
     Ok(())
@@ -490,7 +506,11 @@ async fn lease_release(
         emit_json(endpoint, "DELETE", &path, &value)?;
     } else {
         let mut out = stdout();
-        writeln!(out, "Released central review lease for {}", args.submission_id)?;
+        writeln!(
+            out,
+            "Released central review lease for {}",
+            args.submission_id
+        )?;
         render_lease_fields(&mut out, &value)?;
     }
     Ok(())
@@ -518,7 +538,11 @@ async fn append_credit_event(
         emit_json(endpoint, "POST", &path, &value)?;
     } else {
         let mut out = stdout();
-        writeln!(out, "Appended central delayed credit event for {}", args.submission_id)?;
+        writeln!(
+            out,
+            "Appended central delayed credit event for {}",
+            args.submission_id
+        )?;
         render_kv_fields(
             &mut out,
             &value,
@@ -829,13 +853,11 @@ mod tests {
             .and(path("/v1/review/quarantine"))
             .and(query_param("lease_filter", "mine"))
             .and(header("authorization", "Bearer reviewer-secret"))
-            .respond_with(
-                ResponseTemplate::new(200).set_body_json(serde_json::json!({
-                    "items": [
-                        {"submission_id": "sub-1", "privacy_risk": "low"}
-                    ]
-                })),
-            )
+            .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                "items": [
+                    {"submission_id": "sub-1", "privacy_risk": "low"}
+                ]
+            })))
             .expect(1)
             .mount(&server)
             .await;
@@ -867,12 +889,10 @@ mod tests {
                 "decision": "approve",
                 "reason": "looks fine",
             })))
-            .respond_with(
-                ResponseTemplate::new(200).set_body_json(serde_json::json!({
-                    "status": "approved",
-                    "credit_points_final": 1.0,
-                })),
-            )
+            .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                "status": "approved",
+                "credit_points_final": 1.0,
+            })))
             .expect(1)
             .mount(&server)
             .await;
diff --git a/crates/trace-commons-server/src/bin/trace-commons-worker.rs b/crates/trace-commons-server/src/bin/trace-commons-worker.rs
index b208c8361..a59b69eda 100644
--- a/crates/trace-commons-server/src/bin/trace-commons-worker.rs
+++ b/crates/trace-commons-server/src/bin/trace-commons-worker.rs
@@ -12,14 +12,14 @@
 #[path = "operator_common/mod.rs"]
 mod operator_common;
 
-use std::io::{stdout, Write};
+use std::io::{Write, stdout};
 use std::path::PathBuf;
 
 use anyhow::Result;
 use clap::{Parser, Subcommand, ValueEnum};
 use reqwest::Method;
 use serde_json::Value;
-use trace_commons_operator_client::{format as oc_format, host_allowlist::HostAllowlist, Client};
+use trace_commons_operator_client::{Client, format as oc_format, host_allowlist::HostAllowlist};
 use uuid::Uuid;
 
 use operator_common::{render_items, render_kv_fields, sanitized_url};
@@ -31,8 +31,7 @@ const VECTOR_WORKER_BEARER_ENV: &str = "TRACE_COMMONS_VECTOR_WORKER_BEARER";
 const BENCHMARK_WORKER_BEARER_ENV: &str = "TRACE_COMMONS_BENCHMARK_WORKER_BEARER";
 const EXPORT_WORKER_BEARER_ENV: &str = "TRACE_COMMONS_EXPORT_WORKER_BEARER";
 const RANKER_WORKER_BEARER_ENV: &str = "TRACE_COMMONS_RANKER_WORKER_BEARER";
-const PROCESS_EVALUATION_WORKER_BEARER_ENV: &str =
-    "TRACE_COMMONS_PROCESS_EVALUATION_WORKER_BEARER";
+const PROCESS_EVALUATION_WORKER_BEARER_ENV: &str = "TRACE_COMMONS_PROCESS_EVALUATION_WORKER_BEARER";
 
 #[derive(Debug, Parser)]
 #[command(
@@ -334,7 +333,11 @@ fn bearer_env(cmd: &WorkerSubcommand) -> &str {
     }
 }
 
-fn build_client(endpoint: &str, bearer_token_env: &str, allowed_hosts: Option<&str>) -> Result<Client> {
+fn build_client(
+    endpoint: &str,
+    bearer_token_env: &str,
+    allowed_hosts: Option<&str>,
+) -> Result<Client> {
     let mut builder = Client::builder(endpoint, bearer_token_env);
     if let Some(csv) = allowed_hosts {
         builder = builder.host_allowlist(HostAllowlist::from_csv(csv));
@@ -483,8 +486,14 @@ async fn worker_retention_maintenance(
                 ("  records marked expired", "records_marked_expired"),
                 ("  records marked purged", "records_marked_purged"),
                 ("  export cache files pruned", "export_cache_files_pruned"),
-                ("  export provenance invalidated", "export_provenance_invalidated"),
-                ("  benchmark artifacts invalidated", "benchmark_artifacts_invalidated"),
+                (
+                    "  export provenance invalidated",
+                    "export_provenance_invalidated",
+                ),
+                (
+                    "  benchmark artifacts invalidated",
+                    "benchmark_artifacts_invalidated",
+                ),
             ],
         )?;
     }
@@ -562,7 +571,10 @@ async fn worker_benchmark_convert(
         emit_json(endpoint, "POST", path, &value)?;
     } else {
         let mut out = stdout();
-        writeln!(out, "Trace Commons benchmark conversion (worker) requested.")?;
+        writeln!(
+            out,
+            "Trace Commons benchmark conversion (worker) requested."
+        )?;
         render_kv_fields(
             &mut out,
             &value,
@@ -605,7 +617,9 @@ async fn worker_replay_dataset_export(
         owned.push(("privacy_risk", risk.as_str().to_string()));
     }
     let query = borrow_query(&owned);
-    let raw = client.call_raw::<()>(Method::GET, path, &query, None).await?;
+    let raw = client
+        .call_raw::<()>(Method::GET, path, &query, None)
+        .await?;
     let value: Value = serde_json::from_str(&raw).unwrap_or(Value::Null);
 
     if let Some(output) = args.output.as_ref() {
@@ -677,7 +691,9 @@ async fn worker_ranker_training_export(
         owned.push(("privacy_risk", risk.as_str().to_string()));
     }
     let query = borrow_query(&owned);
-    let raw = client.call_raw::<()>(Method::GET, path, &query, None).await?;
+    let raw = client
+        .call_raw::<()>(Method::GET, path, &query, None)
+        .await?;
     let value: Value = serde_json::from_str(&raw).unwrap_or(Value::Null);
 
     if let Some(output) = args.output.as_ref() {
@@ -720,10 +736,7 @@ async fn worker_ranker_training_export(
     if json {
         emit_json(endpoint, "GET", path, &value)
     } else {
-        let items_value = value
-            .get(item_field)
-            .cloned()
-            .unwrap_or(Value::Null);
+        let items_value = value.get(item_field).cloned().unwrap_or(Value::Null);
         let envelope = serde_json::json!({ "items": items_value });
         render_items(
             &mut stdout(),
@@ -858,10 +871,7 @@ async fn process_evaluation_submit(
                 ("  process eval value", "process_eval_value"),
                 ("  review scorecard", "review_scorecard"),
                 ("  output object ref", "output_object_ref_id"),
-                (
-                    "  utility credit appended",
-                    "utility_credit_appended_count",
-                ),
+                ("  utility credit appended", "utility_credit_appended_count"),
                 (
                     "  utility credit skipped existing",
                     "utility_credit_skipped_existing_count",
@@ -1497,12 +1507,10 @@ mod tests {
                 "external_ref": "job-1",
                 "submission_ids": [sub],
             })))
-            .respond_with(
-                ResponseTemplate::new(200).set_body_json(serde_json::json!({
-                    "appended_count": 1,
-                    "skipped_existing_count": 0,
-                })),
-            )
+            .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                "appended_count": 1,
+                "skipped_existing_count": 0,
+            })))
             .expect(1)
             .mount(&server)
             .await;
@@ -1651,14 +1659,12 @@ mod tests {
                 "dry_run": true,
                 "purpose": "reindex",
             })))
-            .respond_with(
-                ResponseTemplate::new(200).set_body_json(serde_json::json!({
-                    "audit_event_id": "a-1",
-                    "purpose": "reindex",
-                    "dry_run": true,
-                    "vector_entries_indexed": 0,
-                })),
-            )
+            .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                "audit_event_id": "a-1",
+                "purpose": "reindex",
+                "dry_run": true,
+                "vector_entries_indexed": 0,
+            })))
             .expect(1)
             .mount(&server)
             .await;

From 7dae23097d3f8a1ead32f7df5fa100eb1ae24110 Mon Sep 17 00:00:00 2001
From: Zaki <zaki@iqlusion.io>
Date: Tue, 19 May 2026 17:24:39 -0700
Subject: [PATCH 7/7] trigger ci on retargeted base