From 8497953890239793ae0878603d2aac1dd6e1f7d1 Mon Sep 17 00:00:00 2001
From: Matthew Slipper <me@matthewslipper.com>
Date: Tue, 18 Aug 2026 19:24:48 +0000
Subject: [PATCH 01/36] feat: run workflow agents in parallel (#1420)

* feat: run workflow agents in parallel

* docs: align parallel agent result example
---
 docs/pages/extend/workflows-v2.mdx            |  17 +
 docs/pages/extend/workflows.mdx               |  51 ++-
 .../crates/centaur-workflows/src/lib.rs       | 372 +++++++++++++++++-
 .../api-rs/rfcs/0003-python-workflow-host.md  |  18 +-
 .../workflow-python/api/workflow_engine.py    |  24 ++
 .../tests/test_workflow_host.py               | 149 +++++++
 6 files changed, 615 insertions(+), 16 deletions(-)

diff --git a/docs/pages/extend/workflows-v2.mdx b/docs/pages/extend/workflows-v2.mdx
index 95a736142..8149ce104 100644
--- a/docs/pages/extend/workflows-v2.mdx
+++ b/docs/pages/extend/workflows-v2.mdx
@@ -59,6 +59,7 @@ Supported v2 primitives:
 | `handler(inp, ctx)` | Supported |
 | `ctx.step(name, fn)` | Supported |
 | `ctx.agent_turn(...)` / `ctx.run_agent(...)` | Supported |
+| `ctx.run_agents(...)` | Supported for bounded concurrent agent turns with ordered outcomes |
 | `ctx.call_tool(...)` | Supported through the generated `centaur-tools call` bridge in the workflow-host sandbox |
 | `ctx.post_to_slack(...)` | Supported |
 | `ctx._pool` | Supported when the workflow-host sandbox receives `DATABASE_URL` |
@@ -134,6 +135,22 @@ session runtime.
 }
 ```
 
+Use `ctx.run_agents(...)` for independent work that should run concurrently:
+
+```python
+reviews = await ctx.run_agents(
+    [
+        {"name": "correctness", "text": "Review the PR for correctness."},
+        {"name": "security", "text": "Review the PR for security issues."},
+    ],
+    max_concurrency=2,
+)
+```
+
+Each item uses a separate workflow-owned session. Results stay in input order.
+An individual agent failure produces an item with `ok: false`; it does not fail
+the whole batch or discard successful results.
+
 #### Declare Workflow-Host Permissions
 
 When a workflow calls tools directly from the workflow host with
diff --git a/docs/pages/extend/workflows.mdx b/docs/pages/extend/workflows.mdx
index e349e4132..0f03e6966 100644
--- a/docs/pages/extend/workflows.mdx
+++ b/docs/pages/extend/workflows.mdx
@@ -83,10 +83,8 @@ disabled.
 | `ctx.sleep_until(name, when)` | Resume at a specific time. |
 | `ctx.wait_for_event(name, event_type, correlation_id)` | Wait for an external event. |
 | `ctx.start_workflow(...)` | Start a child workflow and continue immediately. |
-| `ctx.wait_for_workflow(...)` | Wait for a child workflow to finish. |
-| `ctx.run_workflow(...)` | Start and wait in one call. |
-| `ctx.start_agent(...)` | Start an agent turn. |
-| `ctx.run_agent(...)` | Start an agent turn and wait for the result. |
+| `ctx.agent_turn(...)` / `ctx.run_agent(...)` / `ctx.start_agent(...)` | Run one agent turn and wait for the result. |
+| `ctx.run_agents(...)` | Run a bounded group of named agent turns concurrently and wait for every outcome. |
 
 The handler may re-execute after a restart. Put external side effects behind
 `ctx.step(...)` so completed work is not repeated.
@@ -99,11 +97,52 @@ These primitives compose into larger automations:
   billing state, deploy health, or vendor exports.
 - **Event-driven flows**: wait for a webhook, approval, upload, or callback and
   continue from the last checkpoint.
-- **Fan-out/fan-in orchestration**: start child workflows for independent work
-  and wait for all of them before producing a final result.
+- **Fan-out/fan-in orchestration**: run independent named agents concurrently,
+  then combine their successful results into one final result.
 - **Agent orchestration**: use agents for judgment-heavy steps while the
   workflow owns timing, retries, state, and final delivery.
 
+### Run Agents Concurrently
+
+Use `ctx.run_agents(...)` when independent reviewers or researchers should run
+at the same time:
+
+```python
+reviews = await ctx.run_agents(
+    [
+        {"name": "correctness", "text": "Review the PR for correctness."},
+        {"name": "security", "text": "Review the PR for security issues."},
+        {"name": "tests", "text": "Review the PR's test coverage."},
+    ],
+    max_concurrency=3,
+)
+```
+
+Every agent needs a unique, non-empty `name`. Centaur assigns each one a
+separate workflow-owned session and stable idempotency keys. The maximum
+concurrency defaults to 4 and may be set from 1 through 16. A batch supports up
+to 32 agents.
+
+The result preserves input order and reports individual failures without
+discarding successful reviews:
+
+```json
+{
+  "results": [
+    {"index": 0, "name": "correctness", "ok": true, "result": {"result_text": "..."}},
+    {"index": 1, "name": "security", "ok": false, "error": "agent unavailable"},
+    {"index": 2, "name": "tests", "ok": true, "result": {"result_text": "..."}}
+  ],
+  "succeeded": 2,
+  "failed": 1
+}
+```
+
+Batch items accept the same model, provider, reasoning, harness, persona,
+prompt, content, idle timeout, maximum duration, and metadata options as
+`ctx.agent_turn(...)`. Session and idempotency fields are reserved because the
+batch runtime assigns them independently for each agent.
+
 ## Run a workflow
 
 Direct administrative API calls need a short-lived Console service token. Mint
diff --git a/services/api-rs/crates/centaur-workflows/src/lib.rs b/services/api-rs/crates/centaur-workflows/src/lib.rs
index f6887ba02..e1ba67302 100644
--- a/services/api-rs/crates/centaur-workflows/src/lib.rs
+++ b/services/api-rs/crates/centaur-workflows/src/lib.rs
@@ -1,6 +1,7 @@
 use std::{
     collections::{BTreeMap, BTreeSet},
     env,
+    future::Future,
     path::PathBuf,
     str::FromStr,
     sync::{Arc, RwLock},
@@ -22,7 +23,7 @@ use centaur_session_sqlx::PgSessionStore;
 use chrono::{DateTime, Utc};
 use chrono_tz::Tz;
 use cron::Schedule;
-use futures_util::{TryStreamExt, pin_mut};
+use futures_util::{StreamExt, TryStreamExt, pin_mut, stream};
 use serde::{Deserialize, Serialize};
 use serde_json::{Value, json};
 use sqlx::Row;
@@ -47,6 +48,10 @@ const PYTHON_HOST_INTERPRETER_ENV: &str = "PYTHON_WORKFLOW_HOST_PYTHON";
 const WORKFLOW_TOOL_API_URL_ENV: &str = "WORKFLOW_TOOL_API_URL";
 const DEFAULT_AGENT_IDLE_TIMEOUT_MS: u64 = 60_000;
 const DEFAULT_AGENT_MAX_DURATION_MS: u64 = 30 * 60 * 1_000;
+const DEFAULT_AGENT_BATCH_CONCURRENCY: usize = 4;
+const MAX_AGENT_BATCH_CONCURRENCY: usize = 16;
+const MAX_AGENT_BATCH_SIZE: usize = 32;
+const MAX_AGENT_BATCH_NAME_BYTES: usize = 128;
 const WORKFLOW_HOST_CLAIM_EXTENSION: Duration = Duration::from_secs(5 * 60);
 const WORKFLOW_HOST_HEARTBEAT_INTERVAL: Duration = Duration::from_secs(60);
 const WORKFLOW_RECONCILE_INTERVAL_SECS_ENV: &str = "WORKFLOW_RECONCILE_INTERVAL_SECS";
@@ -3348,7 +3353,22 @@ async fn handle_python_context_request(
         }
         Some("ctx.agent_turn") => {
             let args = message.get("args").cloned().unwrap_or_else(|| json!({}));
-            match run_python_agent_turn(session_runtime.clone(), ctx, input, args, &request_id)
+            match run_python_agent_turn(
+                session_runtime.clone(),
+                ctx,
+                input,
+                args,
+                &request_id,
+                None,
+            )
+            .await
+            {
+                Ok(value) => Ok(value),
+                Err(error) => Err(error.to_string()),
+            }
+        }
+        Some("ctx.run_agents") => {
+            match run_python_agent_batch(session_runtime.clone(), ctx, input, message, &request_id)
                 .await
             {
                 Ok(value) => Ok(value),
@@ -3505,6 +3525,7 @@ async fn run_python_agent_turn(
     input: &WorkflowTaskInput,
     args: Value,
     request_id: &str,
+    default_thread_key: Option<String>,
 ) -> Result<Value, WorkflowRuntimeError> {
     let text = args
         .get("text")
@@ -3535,11 +3556,13 @@ async fn run_python_agent_turn(
         .map(ToOwned::to_owned);
     let workflow_owned_thread = explicit_thread_key.is_none();
     let thread_key = explicit_thread_key.unwrap_or_else(|| {
-        format!(
-            "wf:{}:agent:{}",
-            ctx.task_id().replace('-', ""),
-            input.workflow_name
-        )
+        default_thread_key.unwrap_or_else(|| {
+            format!(
+                "wf:{}:agent:{}",
+                ctx.task_id().replace('-', ""),
+                input.workflow_name
+            )
+        })
     });
     let harness_type = parse_agent_harness(&args)?.unwrap_or_else(|| input.harness_type.clone());
     let persona_id = args
@@ -3625,6 +3648,214 @@ async fn run_python_agent_turn(
     serde_json::to_value(result).map_err(WorkflowRuntimeError::from)
 }
 
+#[derive(Debug, Clone, PartialEq)]
+struct PythonAgentBatchItem {
+    index: usize,
+    name: String,
+    args: Value,
+}
+
+fn parse_python_agent_batch(
+    message: &Value,
+    request_id: &str,
+) -> Result<(Vec<PythonAgentBatchItem>, usize), WorkflowRuntimeError> {
+    let raw_agents = message
+        .get("agents")
+        .and_then(Value::as_array)
+        .ok_or_else(|| {
+            WorkflowRuntimeError::BadRequest("ctx.run_agents requires an agents array".to_owned())
+        })?;
+    if raw_agents.is_empty() {
+        return Err(WorkflowRuntimeError::BadRequest(
+            "ctx.run_agents requires at least one agent".to_owned(),
+        ));
+    }
+    if raw_agents.len() > MAX_AGENT_BATCH_SIZE {
+        return Err(WorkflowRuntimeError::BadRequest(format!(
+            "ctx.run_agents supports at most {MAX_AGENT_BATCH_SIZE} agents"
+        )));
+    }
+
+    let max_concurrency = match message.get("max_concurrency") {
+        Some(value) => value.as_u64().ok_or_else(|| {
+            WorkflowRuntimeError::BadRequest(
+                "ctx.run_agents max_concurrency must be an integer".to_owned(),
+            )
+        })? as usize,
+        None => DEFAULT_AGENT_BATCH_CONCURRENCY,
+    };
+    if !(1..=MAX_AGENT_BATCH_CONCURRENCY).contains(&max_concurrency) {
+        return Err(WorkflowRuntimeError::BadRequest(format!(
+            "ctx.run_agents max_concurrency must be between 1 and {MAX_AGENT_BATCH_CONCURRENCY}"
+        )));
+    }
+
+    let reserved_fields = [
+        "thread_key",
+        "message_id",
+        "client_message_id",
+        "idempotency_key",
+        "execution_idempotency_key",
+    ];
+    let mut names = BTreeSet::new();
+    let mut agents = Vec::with_capacity(raw_agents.len());
+    for (index, raw_agent) in raw_agents.iter().enumerate() {
+        let mut args = raw_agent.as_object().cloned().ok_or_else(|| {
+            WorkflowRuntimeError::BadRequest(format!(
+                "ctx.run_agents agent at index {index} must be an object"
+            ))
+        })?;
+        let name = args
+            .get("name")
+            .and_then(Value::as_str)
+            .map(str::trim)
+            .filter(|name| !name.is_empty())
+            .ok_or_else(|| {
+                WorkflowRuntimeError::BadRequest(format!(
+                    "ctx.run_agents agent at index {index} requires a non-empty name"
+                ))
+            })?
+            .to_owned();
+        if name.len() > MAX_AGENT_BATCH_NAME_BYTES {
+            return Err(WorkflowRuntimeError::BadRequest(format!(
+                "ctx.run_agents agent name at index {index} must be at most {MAX_AGENT_BATCH_NAME_BYTES} bytes"
+            )));
+        }
+        if !names.insert(name.clone()) {
+            return Err(WorkflowRuntimeError::BadRequest(format!(
+                "ctx.run_agents agent names must be unique; duplicate {name:?}"
+            )));
+        }
+        if let Some(field) = reserved_fields
+            .iter()
+            .find(|field| args.contains_key(**field))
+        {
+            return Err(WorkflowRuntimeError::BadRequest(format!(
+                "ctx.run_agents agent {name:?} cannot set reserved field {field:?}"
+            )));
+        }
+
+        let metadata = args
+            .entry("metadata".to_owned())
+            .or_insert_with(|| json!({}));
+        if !metadata.is_object() {
+            *metadata = json!({});
+        }
+        object_insert(metadata, "workflow_agent_batch_name", json!(name));
+        object_insert(metadata, "workflow_agent_batch_index", json!(index));
+        object_insert(
+            metadata,
+            "workflow_agent_batch_request_id",
+            json!(request_id),
+        );
+
+        agents.push(PythonAgentBatchItem {
+            index,
+            name,
+            args: Value::Object(args),
+        });
+    }
+    Ok((agents, max_concurrency))
+}
+
+async fn run_bounded_ordered<T, R, F, Fut>(
+    items: Vec<T>,
+    max_concurrency: usize,
+    mut run: F,
+) -> Vec<R>
+where
+    F: FnMut(T) -> Fut,
+    Fut: Future<Output = R>,
+{
+    let item_count = items.len();
+    let futures = items
+        .into_iter()
+        .enumerate()
+        .map(|(index, item)| {
+            let future = run(item);
+            async move { (index, future.await) }
+        })
+        .collect::<Vec<_>>();
+    let completed = stream::iter(futures)
+        .buffer_unordered(max_concurrency)
+        .collect::<Vec<_>>()
+        .await;
+    let mut ordered = (0..item_count).map(|_| None).collect::<Vec<_>>();
+    for (index, result) in completed {
+        ordered[index] = Some(result);
+    }
+    ordered
+        .into_iter()
+        .map(|result| result.expect("every bounded batch future must produce one result"))
+        .collect()
+}
+
+async fn run_python_agent_batch(
+    session_runtime: SessionRuntime,
+    ctx: &TaskContext,
+    input: &WorkflowTaskInput,
+    message: &Value,
+    request_id: &str,
+) -> Result<Value, WorkflowRuntimeError> {
+    let (agents, max_concurrency) = parse_python_agent_batch(message, request_id)?;
+    let task_id = ctx.task_id().replace('-', "");
+    let batch_request_id = request_id.to_owned();
+    let outcomes = run_bounded_ordered(agents, max_concurrency, |agent| {
+        let session_runtime = session_runtime.clone();
+        let agent_slug = slugify(&agent.name);
+        let default_thread_key = format!(
+            "wf:{task_id}:agent-batch:{batch_request_id}:{}:{agent_slug}",
+            agent.index,
+        );
+        let agent_request_id = format!("{batch_request_id}:{}", agent.index);
+        async move {
+            let result = run_python_agent_turn(
+                session_runtime,
+                ctx,
+                input,
+                agent.args.clone(),
+                &agent_request_id,
+                Some(default_thread_key),
+            )
+            .await;
+            (agent, result)
+        }
+    })
+    .await;
+
+    let mut succeeded = 0;
+    let mut failed = 0;
+    let results = outcomes
+        .into_iter()
+        .map(|(agent, result)| match result {
+            Ok(result) => {
+                succeeded += 1;
+                json!({
+                    "index": agent.index,
+                    "name": agent.name,
+                    "ok": true,
+                    "result": result,
+                })
+            }
+            Err(error) => {
+                failed += 1;
+                json!({
+                    "index": agent.index,
+                    "name": agent.name,
+                    "ok": false,
+                    "error": error.to_string(),
+                })
+            }
+        })
+        .collect::<Vec<_>>();
+
+    Ok(json!({
+        "results": results,
+        "succeeded": succeeded,
+        "failed": failed,
+    }))
+}
+
 /// Returns the first arg key that holds a non-empty (trimmed) string, owned.
 fn first_str_arg(args: &Value, keys: &[&str]) -> Option<String> {
     keys.iter()
@@ -4200,6 +4431,133 @@ mod tests {
         assert_eq!(first_str_arg(&json!({"model": "   "}), &["model"]), None);
     }
 
+    #[test]
+    fn parse_agent_batch_requires_unique_names_and_adds_metadata() {
+        let message = json!({
+            "type": "ctx.run_agents",
+            "max_concurrency": 2,
+            "agents": [
+                {
+                    "name": "correctness",
+                    "text": "Review correctness",
+                    "metadata": {"pr": 42}
+                },
+                {"name": "security", "text": "Review security"}
+            ]
+        });
+
+        let (agents, max_concurrency) = parse_python_agent_batch(&message, "7").unwrap();
+
+        assert_eq!(max_concurrency, 2);
+        assert_eq!(
+            agents
+                .iter()
+                .map(|agent| agent.name.as_str())
+                .collect::<Vec<_>>(),
+            vec!["correctness", "security"]
+        );
+        assert_eq!(agents[0].args.pointer("/metadata/pr"), Some(&json!(42)));
+        assert_eq!(
+            agents[0]
+                .args
+                .pointer("/metadata/workflow_agent_batch_name"),
+            Some(&json!("correctness"))
+        );
+        assert_eq!(
+            agents[1]
+                .args
+                .pointer("/metadata/workflow_agent_batch_index"),
+            Some(&json!(1))
+        );
+        assert_eq!(
+            agents[1]
+                .args
+                .pointer("/metadata/workflow_agent_batch_request_id"),
+            Some(&json!("7"))
+        );
+    }
+
+    #[test]
+    fn parse_agent_batch_rejects_duplicate_names_and_identity_overrides() {
+        let duplicate = json!({
+            "agents": [
+                {"name": "security", "text": "first"},
+                {"name": "security", "text": "second"}
+            ]
+        });
+        let error = parse_python_agent_batch(&duplicate, "1").unwrap_err();
+        assert!(error.to_string().contains("names must be unique"));
+
+        let overridden_identity = json!({
+            "agents": [{
+                "name": "security",
+                "text": "review",
+                "thread_key": "workflow:shared"
+            }]
+        });
+        let error = parse_python_agent_batch(&overridden_identity, "1").unwrap_err();
+        assert!(error.to_string().contains("reserved field \"thread_key\""));
+    }
+
+    #[test]
+    fn parse_agent_batch_enforces_size_and_concurrency_bounds() {
+        let empty = json!({"agents": []});
+        let error = parse_python_agent_batch(&empty, "1").unwrap_err();
+        assert!(error.to_string().contains("at least one agent"));
+
+        for max_concurrency in [0, MAX_AGENT_BATCH_CONCURRENCY + 1] {
+            let message = json!({
+                "agents": [{"name": "correctness", "text": "review"}],
+                "max_concurrency": max_concurrency,
+            });
+            let error = parse_python_agent_batch(&message, "1").unwrap_err();
+            assert!(
+                error
+                    .to_string()
+                    .contains("max_concurrency must be between")
+            );
+        }
+
+        let too_many = json!({
+            "agents": (0..=MAX_AGENT_BATCH_SIZE)
+                .map(|index| json!({"name": format!("reviewer-{index}"), "text": "review"}))
+                .collect::<Vec<_>>(),
+        });
+        let error = parse_python_agent_batch(&too_many, "1").unwrap_err();
+        assert!(error.to_string().contains("supports at most"));
+    }
+
+    #[tokio::test]
+    async fn bounded_batch_limits_concurrency_and_restores_input_order() {
+        use std::sync::atomic::{AtomicUsize, Ordering};
+
+        let active = Arc::new(AtomicUsize::new(0));
+        let peak = Arc::new(AtomicUsize::new(0));
+        let results = run_bounded_ordered(vec![0_u64, 1, 2, 3], 2, {
+            let active = active.clone();
+            let peak = peak.clone();
+            move |item| {
+                let active = active.clone();
+                let peak = peak.clone();
+                async move {
+                    let now_active = active.fetch_add(1, Ordering::SeqCst) + 1;
+                    peak.fetch_max(now_active, Ordering::SeqCst);
+                    tokio::time::sleep(Duration::from_millis(4 * (4 - item))).await;
+                    active.fetch_sub(1, Ordering::SeqCst);
+                    if item == 2 {
+                        Err("review failed")
+                    } else {
+                        Ok(item)
+                    }
+                }
+            }
+        })
+        .await;
+
+        assert_eq!(results, vec![Ok(0), Ok(1), Err("review failed"), Ok(3)]);
+        assert_eq!(peak.load(Ordering::SeqCst), 2);
+    }
+
     #[test]
     fn parse_worker_concurrency_uses_override_or_default() {
         // Override wins.
diff --git a/services/api-rs/rfcs/0003-python-workflow-host.md b/services/api-rs/rfcs/0003-python-workflow-host.md
index 3b01e93b8..f7b1dfa00 100644
--- a/services/api-rs/rfcs/0003-python-workflow-host.md
+++ b/services/api-rs/rfcs/0003-python-workflow-host.md
@@ -96,6 +96,7 @@ Absurd queue: centaur_workflows
                  |
                  +--> ctx.step       -> api-rs / Absurd checkpoint RPC
                  +--> ctx.agent_turn -> api-rs SessionRuntime
+                 +--> ctx.run_agents -> bounded parallel SessionRuntime turns
                  +--> ctx.call_tool  -> api-rs tool route
                  +--> ctx.post_to_slack
                  +--> ctx._pool      -> direct Postgres
@@ -200,9 +201,10 @@ While a workflow is running, the host may send requests:
 {"type":"ctx.step.get","request_id":"1","step":"load_state"}
 {"type":"ctx.step.put","request_id":"2","step":"load_state","value":{}}
 {"type":"ctx.agent_turn","request_id":"3","args":{}}
-{"type":"ctx.call_tool","request_id":"4","tool":"slack","method":"send_message","args":{}}
-{"type":"ctx.post_to_slack","request_id":"5","channel":"C123","text":"hello","args":{}}
-{"type":"ctx.log","request_id":"6","message":"workflow_event","fields":{}}
+{"type":"ctx.run_agents","request_id":"4","agents":[{"name":"security","text":"Review security"}],"max_concurrency":4}
+{"type":"ctx.call_tool","request_id":"5","tool":"slack","method":"send_message","args":{}}
+{"type":"ctx.post_to_slack","request_id":"6","channel":"C123","text":"hello","args":{}}
+{"type":"ctx.log","request_id":"7","message":"workflow_event","fields":{}}
 ```
 
 api-rs responds:
@@ -229,6 +231,7 @@ class WorkflowContext:
 
     async def step(self, name, fn, *, retry=None, timeout=None): ...
     async def agent_turn(self, text=None, **kwargs): ...
+    async def run_agents(self, agents, *, max_concurrency=None): ...
     async def call_tool(self, tool, method, args=None): ...
     async def post_to_slack(self, channel, text, **kwargs): ...
     def log(self, message, **fields): ...
@@ -275,6 +278,15 @@ Rules:
 - wait for terminal session result and return the same result shape existing
   workflows expect
 
+### `ctx.run_agents`
+
+api-rs handles a named batch as bounded concurrent `ctx.agent_turn` operations.
+Each item receives its own workflow-owned thread key, message id, execution
+idempotency key, and batch metadata. Results preserve input order and report
+individual failures without failing the entire batch. The runtime rejects
+duplicate names and caller-supplied session or idempotency fields so two batch
+items cannot accidentally serialize through the same session.
+
 ### `ctx.call_tool`
 
 api-rs should call the tool runtime and return JSON output. If api-rs tool
diff --git a/services/workflow-python/api/workflow_engine.py b/services/workflow-python/api/workflow_engine.py
index b9e9c5a61..9e6d426ce 100644
--- a/services/workflow-python/api/workflow_engine.py
+++ b/services/workflow-python/api/workflow_engine.py
@@ -138,6 +138,30 @@ async def run_agent(self, *args: Any, text: str | None = None, **kwargs: Any) ->
     async def start_agent(self, *args: Any, text: str | None = None, **kwargs: Any) -> Any:
         return await self.run_agent(*args, text=text, **kwargs)
 
+    async def run_agents(
+        self,
+        agents: list[dict[str, Any]],
+        *,
+        max_concurrency: int | None = None,
+    ) -> dict[str, Any]:
+        """Run named agent turns concurrently and return every outcome in input order."""
+        if not isinstance(agents, list):
+            raise TypeError("run_agents agents must be a list")
+
+        normalized_agents: list[dict[str, Any]] = []
+        for index, agent in enumerate(agents):
+            if not isinstance(agent, dict):
+                raise TypeError(f"run_agents agent at index {index} must be a dict")
+            normalized_agents.append({**self._agent_defaults, **agent})
+
+        request: dict[str, Any] = {
+            "type": "ctx.run_agents",
+            "agents": normalized_agents,
+        }
+        if max_concurrency is not None:
+            request["max_concurrency"] = max_concurrency
+        return await self._rpc.request(request)
+
     async def start_workflow(
         self,
         workflow_name: str,
diff --git a/services/workflow-python/tests/test_workflow_host.py b/services/workflow-python/tests/test_workflow_host.py
index a80a91f1c..590915e40 100644
--- a/services/workflow-python/tests/test_workflow_host.py
+++ b/services/workflow-python/tests/test_workflow_host.py
@@ -65,6 +65,20 @@ async def request(self, payload):
             }
         if message_type == "ctx.agent_turn":
             return payload["args"]
+        if message_type == "ctx.run_agents":
+            return {
+                "results": [
+                    {
+                        "index": index,
+                        "name": agent["name"],
+                        "ok": True,
+                        "result": agent,
+                    }
+                    for index, agent in enumerate(payload["agents"])
+                ],
+                "succeeded": len(payload["agents"]),
+                "failed": 0,
+            }
         if message_type == "ctx.workflow.start":
             return {
                 "workflow_name": payload["workflow_name"],
@@ -298,6 +312,77 @@ def test_agent_turn_per_call_kwargs_override_agent_defaults(self) -> None:
             {"model": "claude-opus-4-8", "reasoning": "low", "text": "cheap step"},
         )
 
+    def test_run_agents_applies_defaults_and_preserves_input_order(self) -> None:
+        host = load_workflow_host()
+        rpc = RequestRpc()
+        ctx = host.WorkflowContext(
+            rpc,
+            run_id="run-123",
+            task_id="task-456",
+            workflow_name="sample",
+            agent_defaults={"harness": "codex", "reasoning": "high"},
+        )
+
+        result = asyncio.run(
+            ctx.run_agents(
+                [
+                    {"name": "correctness", "text": "Review correctness"},
+                    {
+                        "name": "security",
+                        "text": "Review security",
+                        "reasoning": "medium",
+                    },
+                ],
+                max_concurrency=2,
+            )
+        )
+
+        self.assertEqual(rpc.requests[-1]["type"], "ctx.run_agents")
+        self.assertEqual(rpc.requests[-1]["max_concurrency"], 2)
+        self.assertEqual(
+            rpc.requests[-1]["agents"],
+            [
+                {
+                    "harness": "codex",
+                    "reasoning": "high",
+                    "name": "correctness",
+                    "text": "Review correctness",
+                },
+                {
+                    "harness": "codex",
+                    "reasoning": "medium",
+                    "name": "security",
+                    "text": "Review security",
+                },
+            ],
+        )
+        self.assertEqual(
+            [item["name"] for item in result["results"]],
+            ["correctness", "security"],
+        )
+
+    def test_run_agents_rejects_non_mapping_items_before_rpc(self) -> None:
+        host = load_workflow_host()
+        rpc = RequestRpc()
+        ctx = host.WorkflowContext(
+            rpc,
+            run_id="run-123",
+            task_id="task-456",
+            workflow_name="sample",
+        )
+
+        with self.assertRaisesRegex(TypeError, "agent at index 1 must be a dict"):
+            asyncio.run(
+                ctx.run_agents(
+                    [
+                        {"name": "correctness", "text": "Review correctness"},
+                        "not-an-agent",  # type: ignore[list-item]
+                    ]
+                )
+            )
+
+        self.assertEqual(rpc.requests, [])
+
     def test_start_workflow_enqueues_durable_child_with_idempotency_key(self) -> None:
         host = load_workflow_host()
         rpc = RequestRpc()
@@ -654,6 +739,70 @@ def test_workflow_host_returns_result_after_context_response(self) -> None:
             assert proc.stderr is not None
             self.assertEqual(proc.stderr.read(), "")
 
+    def test_workflow_host_round_trips_agent_batch_result(self) -> None:
+        source = (
+            "WORKFLOW_NAME = 'review_workflow'\n"
+            "async def handler(inp, ctx):\n"
+            "    return await ctx.run_agents([\n"
+            "        {'name': 'correctness', 'text': 'Review correctness'},\n"
+            "        {'name': 'security', 'text': 'Review security'},\n"
+            "    ], max_concurrency=2)\n"
+        )
+        with self.workflow_host(source) as proc:
+            self.send_host_message(
+                proc,
+                {
+                    "type": "workflow.start",
+                    "run_id": "run-123",
+                    "task_id": "task-456",
+                    "workflow_name": "review_workflow",
+                    "input": {},
+                },
+            )
+
+            request = self.read_host_message(proc)
+            self.assertEqual(request["type"], "ctx.run_agents")
+            self.assertEqual(request["max_concurrency"], 2)
+            self.assertEqual(
+                [agent["name"] for agent in request["agents"]],
+                ["correctness", "security"],
+            )
+            result = {
+                "results": [
+                    {
+                        "index": 0,
+                        "name": "correctness",
+                        "ok": True,
+                        "result": {"result_text": "looks good"},
+                    },
+                    {
+                        "index": 1,
+                        "name": "security",
+                        "ok": False,
+                        "error": "agent unavailable",
+                    },
+                ],
+                "succeeded": 1,
+                "failed": 1,
+            }
+            self.send_host_message(
+                proc,
+                {
+                    "type": "ctx.response",
+                    "request_id": request["request_id"],
+                    "ok": True,
+                    "value": result,
+                },
+            )
+
+            response = self.read_host_message(proc)
+            self.assertEqual(response["type"], "workflow.result")
+            self.assertEqual(response["result"], result)
+            proc.wait(timeout=2)
+            self.assertEqual(proc.returncode, 0)
+            assert proc.stderr is not None
+            self.assertEqual(proc.stderr.read(), "")
+
     def test_workflow_host_returns_error_after_failed_context_response(self) -> None:
         source = (
             "WORKFLOW_NAME = 'agent_workflow'\n"

From be75196a39a0e4dda4a487d872a8d7b9ba69015f Mon Sep 17 00:00:00 2001
From: Derek Cofausper <256792747+decofe@users.noreply.github.com>
Date: Tue, 18 Aug 2026 19:25:25 +0000
Subject: [PATCH 02/36] fix(slack): omit default upload comments (#1422)

---
 tools/productivity/slack/client.py            |  2 --
 tools/productivity/slack/tests/test_client.py | 16 ++++++++++++++++
 2 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/tools/productivity/slack/client.py b/tools/productivity/slack/client.py
index 9ef63125d..12f5e0f50 100644
--- a/tools/productivity/slack/client.py
+++ b/tools/productivity/slack/client.py
@@ -1991,8 +1991,6 @@ def upload_file(
             )
             if comment:
                 kwargs["initial_comment"] = comment
-            elif effective_filename:
-                kwargs["initial_comment"] = f"Uploaded `{effective_filename}`."
             if effective_thread_ts:
                 kwargs["thread_ts"] = effective_thread_ts
             # We intentionally do NOT forward alt_text to Slack. Passing alt_txt
diff --git a/tools/productivity/slack/tests/test_client.py b/tools/productivity/slack/tests/test_client.py
index eef5c598b..3b94791e2 100644
--- a/tools/productivity/slack/tests/test_client.py
+++ b/tools/productivity/slack/tests/test_client.py
@@ -1355,6 +1355,22 @@ def test_upload_file_accepts_channel_id_alias_and_returns_preview() -> None:
         "csv_rows_sampled": 1,
         "csv_columns": 2,
     }
+    assert "initial_comment" not in fake_web_client.last_kwargs
+
+
+def test_upload_file_preserves_explicit_comment() -> None:
+    client, fake_web_client = _make_client()
+
+    client.upload_file(
+        channel_id="C123",
+        thread_ts="1780035646.228899",
+        content_base64="dGVzdA==",
+        filename="chart.png",
+        comment="Here is the chart.",
+    )
+
+    assert fake_web_client.last_kwargs is not None
+    assert fake_web_client.last_kwargs["initial_comment"] == "Here is the chart."
 
 
 def test_upload_file_uses_explicit_destination() -> None:

From b28604bef17268ddd3d8aa7d8907712a2054fecd Mon Sep 17 00:00:00 2001
From: Oliver Ponder <oliver.ponder@gmail.com>
Date: Tue, 18 Aug 2026 19:28:17 +0000
Subject: [PATCH 03/36] feat(githubbot): ack review-feedback turns with
 reactions on the review (#1414)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat(githubbot): ack owned-PR management turns with a working reaction (PE-8082)

Review-request and issue-work turns already ack instantly (eyes on the
subject, settled to rocket/confused when the turn finishes), but owned-PR
management turns — address-review, CI-fix, conflict resolution — gave no
signal until the agent pushed or replied. A reviewer leaving feedback on a
bot-owned PR saw silence while the turn ran.

Fire the same subject-reaction lifecycle from fireManagementTurn, the choke
point all management turns flow through: eyes before the turn starts (not
awaited, so the ack can't delay the turn), settled in the background chain.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat(githubbot): move the review ack onto the review itself via GraphQL

Live testing showed the PR-top-post ack goes unnoticed — reviewers look at
their own review, and a reaction on the PR description isn't clearly tied to
anything. The REST reactions API has no endpoint for reviews, so the ack now
goes through the GraphQL addReaction mutation with the review's node id:
eyes lands on the reviewer's review, settled to rocket/confused there.

Turns with no triggering review (CI-fix, conflict resolution) no longer
react at all.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
---
 services/githubbot/src/pr-manager.ts       | 53 ++++++++++++---
 services/githubbot/src/reactions.ts        | 44 ++++++++++++
 services/githubbot/test/pr-manager.test.ts | 79 ++++++++++++++++++++++
 3 files changed, 166 insertions(+), 10 deletions(-)

diff --git a/services/githubbot/src/pr-manager.ts b/services/githubbot/src/pr-manager.ts
index ebabc3cd0..98edf4743 100644
--- a/services/githubbot/src/pr-manager.ts
+++ b/services/githubbot/src/pr-manager.ts
@@ -1,6 +1,7 @@
 import type { GitHubAdapter } from "@chat-adapter/github";
 import type { StateAdapter } from "chat";
 import { backgroundWaitUntil } from "./context";
+import { reactWorkingOnReview, settleReviewReaction } from "./reactions";
 import { runTurnStream } from "./turn";
 import {
   fetchCiEvaluation,
@@ -369,7 +370,11 @@ export async function handleReviewEvent(
     return;
   }
   if (reviewState === "changes_requested" || reviewState === "commented") {
-    fireAddressReviewTurn(ctx, repo.owner, repo.repo, pr, reviewer ?? "the reviewer", reviewId);
+    fireAddressReviewTurn(ctx, repo.owner, repo.repo, pr, {
+      reviewer: reviewer ?? "the reviewer",
+      reviewId,
+      reviewNodeId: stringValue(reviewNode.node_id),
+    });
   }
 }
 
@@ -633,9 +638,9 @@ function fireAddressReviewTurn(
   owner: string,
   repo: string,
   pr: PullRequestSummary,
-  reviewer: string,
-  reviewId: number,
+  review: { reviewer: string; reviewId: number; reviewNodeId?: string },
 ): void {
+  const { reviewer, reviewId, reviewNodeId } = review;
   const preamble =
     `A review was submitted on pull request ${owner}/${repo}#${pr.number} ` +
     `(head ${pr.headSha}). Address it as the PR author, working in your sandbox:\n` +
@@ -647,11 +652,19 @@ function fireAddressReviewTurn(
     `explain why, briefly and respectfully. Resolve the threads you've addressed.\n` +
     `- Re-request review from @${reviewer} once you've pushed.\n` +
     `- If a request is unclear or you can't address it, say so in the thread and ask.`;
-  fireManagementTurn(ctx, owner, repo, pr, preamble, {
-    id: `review-resp-${owner}/${repo}#${pr.number}-${reviewId}`,
-    label: "address-review",
-    text: `Address the review on ${owner}/${repo}#${pr.number} from @${reviewer}.`,
-  });
+  fireManagementTurn(
+    ctx,
+    owner,
+    repo,
+    pr,
+    preamble,
+    {
+      id: `review-resp-${owner}/${repo}#${pr.number}-${reviewId}`,
+      label: "address-review",
+      text: `Address the review on ${owner}/${repo}#${pr.number} from @${reviewer}.`,
+    },
+    reviewNodeId,
+  );
 }
 
 function fireConflictTurn(
@@ -680,6 +693,7 @@ function fireManagementTurn(
   pr: PullRequestSummary,
   preamble: string,
   message: { id: string; label: string; text: string },
+  reviewNodeId?: string,
 ): void {
   const threadKey = managementThreadKey(owner, repo, pr.number);
   const trace = makeTrace(threadKey, message.id);
@@ -707,19 +721,38 @@ function fireManagementTurn(
     pr: `${owner}/${repo}#${pr.number}`,
     work: message.label,
   });
+  // Review-triggered turns ack on the reviewer's own review — instant 👀,
+  // settled to 🚀/😕 when the turn finishes (same lifecycle as @-mention acks).
+  // Not awaited: the ack must not delay the turn, and a failed reaction is only
+  // a missing ack. Turns with no triggering review (CI-fix, conflicts) stay
+  // silent — a reaction on the PR's top post isn't clearly tied to anything.
+  if (reviewNodeId) {
+    void reactWorkingOnReview(ctx.octokit, reviewNodeId, logger(ctx));
+  }
   backgroundWaitUntil(
     runTurnStream(ctx.options, forwardInput)
-      .then((result) => {
+      .then(async (result) => {
         traceLog(ctx.options, "githubbot_management_turn_complete", trace, {
           failed: result.failed,
           work: message.label,
         });
+        if (reviewNodeId) {
+          await settleReviewReaction(
+            ctx.octokit,
+            reviewNodeId,
+            result.failed,
+            logger(ctx),
+          );
+        }
       })
-      .catch((error) => {
+      .catch(async (error) => {
         logger(ctx).warn("githubbot_management_turn_failed", {
           error: errorMessage(error),
           work: message.label,
         });
+        if (reviewNodeId) {
+          await settleReviewReaction(ctx.octokit, reviewNodeId, true, logger(ctx));
+        }
       }),
   );
 }
diff --git a/services/githubbot/src/reactions.ts b/services/githubbot/src/reactions.ts
index 330fd432e..b5b38e183 100644
--- a/services/githubbot/src/reactions.ts
+++ b/services/githubbot/src/reactions.ts
@@ -57,3 +57,47 @@ export async function settleSubjectReaction(
     });
   }
 }
+
+// The REST reactions API has no endpoint for PR reviews, so the review-feedback
+// ack goes through GraphQL with the review's node id — the reaction lands on
+// the reviewer's own review in the timeline, where they look for it.
+const ADD_REACTION_MUTATION = `mutation($subjectId: ID!, $content: ReactionContent!) {
+  addReaction(input: { subjectId: $subjectId, content: $content }) {
+    clientMutationId
+  }
+}`;
+
+export async function reactWorkingOnReview(
+  octokit: Octokit,
+  reviewNodeId: string,
+  logger?: Logger,
+): Promise<void> {
+  try {
+    await octokit.graphql(ADD_REACTION_MUTATION, {
+      subjectId: reviewNodeId,
+      content: "EYES",
+    });
+  } catch (error) {
+    (logger ?? noopLogger).debug("githubbot_review_react_failed", {
+      error: errorMessage(error),
+    });
+  }
+}
+
+export async function settleReviewReaction(
+  octokit: Octokit,
+  reviewNodeId: string,
+  failed: boolean,
+  logger?: Logger,
+): Promise<void> {
+  try {
+    await octokit.graphql(ADD_REACTION_MUTATION, {
+      subjectId: reviewNodeId,
+      content: failed ? "CONFUSED" : "ROCKET",
+    });
+  } catch (error) {
+    (logger ?? noopLogger).debug("githubbot_review_react_settle_failed", {
+      error: errorMessage(error),
+    });
+  }
+}
diff --git a/services/githubbot/test/pr-manager.test.ts b/services/githubbot/test/pr-manager.test.ts
index d9d618b59..d4606a528 100644
--- a/services/githubbot/test/pr-manager.test.ts
+++ b/services/githubbot/test/pr-manager.test.ts
@@ -871,3 +871,82 @@ describe("workflow event emission", () => {
     expect(attempts).toBe(2);
   });
 });
+
+describe("management turn reaction ack", () => {
+  const submittedReview = (state: string, nodeId?: string) =>
+    JSON.stringify({
+      action: "submitted",
+      repository: { full_name: "base/repo" },
+      pull_request: { number: 7 },
+      review: {
+        id: 55,
+        node_id: nodeId,
+        state,
+        user: { login: "reviewer" },
+      },
+    });
+
+  function reviewCtx(reactions: { subjectId: string; content: string }[]) {
+    return {
+      octokit: {
+        graphql: async (
+          _query: string,
+          vars: { subjectId: string; content: string },
+        ) => {
+          reactions.push({ subjectId: vars.subjectId, content: vars.content });
+          return {};
+        },
+        rest: {
+          pulls: {
+            get: async () => ({
+              data: prPayload({ headRepoFullName: "base/repo" }),
+            }),
+            merge: async () => ({ data: {} }),
+          },
+          git: { deleteRef: async () => ({ data: {} }) },
+        },
+      },
+      options: {
+        apiUrl: "http://localhost",
+        deleteBranchOnMerge: false,
+        logger: quietLogger,
+        // Non-retryable so the backgrounded turn settles off the network.
+        fetch: () => Promise.resolve(new Response("no", { status: 400 })),
+      },
+      state: makeState(),
+      userName: "centaur-bot",
+    } as unknown as PrManagerContext;
+  }
+
+  test("acks a changes-requested review with eyes on the review itself, settling when the turn fails", async () => {
+    const reactions: { subjectId: string; content: string }[] = [];
+    await handleReviewEvent(
+      reviewCtx(reactions),
+      submittedReview("changes_requested", "PRR_test55"),
+    );
+    // The working ack lands before the management turn runs.
+    expect(reactions).toContainEqual({ subjectId: "PRR_test55", content: "EYES" });
+    await drainBackgroundWork(5_000);
+    expect(reactions).toContainEqual({
+      subjectId: "PRR_test55",
+      content: "CONFUSED",
+    });
+  });
+
+  test("does not react on an approved review (deterministic merge, no work turn)", async () => {
+    const reactions: { subjectId: string; content: string }[] = [];
+    await handleReviewEvent(
+      reviewCtx(reactions),
+      submittedReview("approved", "PRR_test55"),
+    );
+    await drainBackgroundWork(5_000);
+    expect(reactions).toEqual([]);
+  });
+
+  test("stays quiet when the payload carries no review node id", async () => {
+    const reactions: { subjectId: string; content: string }[] = [];
+    await handleReviewEvent(reviewCtx(reactions), submittedReview("changes_requested"));
+    await drainBackgroundWork(5_000);
+    expect(reactions).toEqual([]);
+  });
+});

From 7bc72e74d6391f03766cd9c27d097b8cf3acd9d9 Mon Sep 17 00:00:00 2001
From: Matthew Slipper <me@matthewslipper.com>
Date: Tue, 18 Aug 2026 20:27:20 +0000
Subject: [PATCH 04/36] feat: allow workflows to select principals (#1423)

* feat: allow workflows to select principals

* fix: prevent session principal rebinding
---
 docs/pages/extend/workflows-v2.mdx            |  28 ++-
 docs/pages/extend/workflows.mdx               |  33 +++-
 docs/pages/secrets/advanced-permissioning.mdx |  10 +-
 .../crates/centaur-api-server/src/error.rs    |  35 ++++
 .../crates/centaur-session-runtime/src/lib.rs | 118 +++++++++++--
 .../crates/centaur-session-sqlx/src/lib.rs    |  47 ++++++
 .../crates/centaur-workflows/src/lib.rs       | 159 ++++++++++++++----
 .../tests/test_workflow_host.py               |  34 ++++
 services/workflow-python/workflow_host.py     |   9 +-
 9 files changed, 417 insertions(+), 56 deletions(-)

diff --git a/docs/pages/extend/workflows-v2.mdx b/docs/pages/extend/workflows-v2.mdx
index 8149ce104..d0bddd89d 100644
--- a/docs/pages/extend/workflows-v2.mdx
+++ b/docs/pages/extend/workflows-v2.mdx
@@ -171,9 +171,16 @@ cargo run -p centaur-perms -- \
   --tool slack
 ```
 
-The principal id is always `workflow-` plus the slugged `WORKFLOW_NAME`.
-Workflow code cannot choose another principal id, display name, or labels.
-`WORKFLOW_PRINCIPAL = True` requires `apiRs.workflowHostSandbox=true`, which
+To use an existing principal instead, declare its foreign ID:
+
+```python
+WORKFLOW_PRINCIPAL = "finance-automation"
+```
+
+The string form resolves the existing principal and fails startup when it does
+not exist. It does not create or update the principal. The `True` form remains
+`workflow-` plus the slugged `WORKFLOW_NAME`. Any `WORKFLOW_PRINCIPAL` value
+requires `apiRs.workflowHostSandbox=true`, which
 renders `WORKFLOW_HOST_SANDBOX=true`; startup fails if a workflow declares a
 principal while workflow-host sandboxing is disabled.
 
@@ -205,6 +212,21 @@ Keep `harness` and `model` together — a model is only meaningful within its
 harness, and because kwargs override `AGENT_DEFAULTS` key by key, overriding one
 without the other can strand a model on the wrong harness.
 
+Agent turns can also select an existing principal by foreign ID. This applies
+to `ctx.agent_turn(...)`, its aliases, and each `ctx.run_agents(...)` item:
+
+```python
+result = await ctx.agent_turn(
+    "Prepare the finance report.",
+    principal="finance-automation",
+)
+```
+
+Principal lookup failures fail the turn. Put `principal` in `AGENT_DEFAULTS`
+when every agent turn in the workflow should use the same principal. An
+existing session bound to another principal returns a conflict and is not
+rebound.
+
 ### Declare webhook metadata in the workflow
 
 Expose a workflow through `WEBHOOKS`:
diff --git a/docs/pages/extend/workflows.mdx b/docs/pages/extend/workflows.mdx
index 0f03e6966..c9f5ed1a2 100644
--- a/docs/pages/extend/workflows.mdx
+++ b/docs/pages/extend/workflows.mdx
@@ -66,11 +66,13 @@ async def handler(inp: Input, ctx: WorkflowContext) -> dict[str, Any]:
 
 `WORKFLOW_PRINCIPAL` is optional. Use it when the workflow host calls tools
 directly with `ctx.call_tool(...)` and should have its own credential boundary.
-The API derives and registers the `workflow-nightly-report` principal from
-`WORKFLOW_NAME` and runs that workflow-host sandbox under it. Workflow code
-cannot choose another principal id, display name, or labels. Grant the required
-tool roles or secrets to the derived principal. `WORKFLOW_PRINCIPAL = True`
-requires `apiRs.workflowHostSandbox=true`, which renders
+Set it to `True` to have the API derive and register the
+`workflow-nightly-report` principal from `WORKFLOW_NAME`. Set it to an existing
+principal foreign ID, such as `WORKFLOW_PRINCIPAL = "finance-automation"`, to
+run the workflow-host sandbox under that principal instead. An unknown foreign
+ID fails startup. Grant the required tool roles or secrets to the selected
+principal. Any `WORKFLOW_PRINCIPAL` value requires
+`apiRs.workflowHostSandbox=true`, which renders
 `WORKFLOW_HOST_SANDBOX=true`; startup fails if workflow-host sandboxing is
 disabled.
 
@@ -139,9 +141,24 @@ discarding successful reviews:
 ```
 
 Batch items accept the same model, provider, reasoning, harness, persona,
-prompt, content, idle timeout, maximum duration, and metadata options as
-`ctx.agent_turn(...)`. Session and idempotency fields are reserved because the
-batch runtime assigns them independently for each agent.
+principal, prompt, content, idle timeout, maximum duration, and metadata
+options as `ctx.agent_turn(...)`. Session and idempotency fields are reserved
+because the batch runtime assigns them independently for each agent.
+
+Set `principal` to an existing principal foreign ID when an agent turn needs a
+specific credential boundary:
+
+```python
+result = await ctx.agent_turn(
+    "Prepare the finance report.",
+    principal="finance-automation",
+)
+```
+
+The principal is resolved before the session is created. An unknown or empty
+foreign ID fails the turn instead of using the thread-derived principal. If the
+session already exists under another principal, the turn returns a conflict
+instead of rebinding it.
 
 ## Run a workflow
 
diff --git a/docs/pages/secrets/advanced-permissioning.mdx b/docs/pages/secrets/advanced-permissioning.mdx
index 2eefbbe4e..83064acf2 100644
--- a/docs/pages/secrets/advanced-permissioning.mdx
+++ b/docs/pages/secrets/advanced-permissioning.mdx
@@ -63,6 +63,7 @@ The stable principal ids follow these rules:
 | Teams personal chat | `teams-user-<user-id>` | That Teams user |
 | Teams channel or group conversation | `teams-conversation-<conversation-id>` | Everyone using Centaur in that conversation |
 | Workflow with `WORKFLOW_PRINCIPAL = True` | `workflow-<workflow-name>` | Runs of that workflow |
+| Workflow with `WORKFLOW_PRINCIPAL = "<foreign-id>"` | The selected existing principal | Runs of that workflow |
 | Other session key | `thread-<session-key>` | That session key |
 
 Values are lowercased and converted to URL-safe slugs. The team scope is
@@ -405,9 +406,12 @@ credential. Grant that wrapper secret to a user, channel, or role like any
 other secret. See [OAuth Apps](/secrets/oauth-apps) for registration and
 consent.
 
-Workflows opt into isolated permissions with `WORKFLOW_PRINCIPAL = True`.
-Centaur derives `workflow-<workflow-name>` and does not let workflow code choose
-another identity. Grant the workflow only the roles or secrets it needs. See
+Workflows opt into isolated permissions with `WORKFLOW_PRINCIPAL = True`, which
+derives `workflow-<workflow-name>`. They can instead set `WORKFLOW_PRINCIPAL` to
+an existing principal foreign ID. Agent turns can select an existing principal
+with `ctx.agent_turn(..., principal="<foreign-id>")`. Unknown foreign IDs fail
+instead of falling back to a broader identity. Grant workflows and agent turns
+only the roles or secrets they need. See
 [Creating Workflows](/extend/workflows#define-a-workflow).
 
 ## Operational Checklist
diff --git a/services/api-rs/crates/centaur-api-server/src/error.rs b/services/api-rs/crates/centaur-api-server/src/error.rs
index 5bc5af127..beb43ba95 100644
--- a/services/api-rs/crates/centaur-api-server/src/error.rs
+++ b/services/api-rs/crates/centaur-api-server/src/error.rs
@@ -67,6 +67,9 @@ impl IntoResponse for ApiError {
             Self::Runtime(SessionRuntimeError::Store(SessionStoreError::PersonaConflict {
                 ..
             })) => StatusCode::CONFLICT,
+            Self::Runtime(SessionRuntimeError::Store(SessionStoreError::PrincipalConflict {
+                ..
+            })) => StatusCode::CONFLICT,
             Self::Runtime(SessionRuntimeError::IronControl(
                 centaur_iron_control::IronControlError::PrincipalDerivation(_),
             )) => StatusCode::BAD_REQUEST,
@@ -109,6 +112,16 @@ impl IntoResponse for ApiError {
             body["existing_harness"] = json!(existing);
             body["requested_harness"] = json!(requested);
         }
+        if let Self::Runtime(SessionRuntimeError::Store(SessionStoreError::PrincipalConflict {
+            existing,
+            requested,
+            ..
+        })) = &self
+        {
+            body["code"] = json!("principal_conflict");
+            body["existing_principal"] = json!(existing);
+            body["requested_principal"] = json!(requested);
+        }
         let mut response = (status, Json(body)).into_response();
         if status == StatusCode::UNAUTHORIZED {
             response
@@ -138,6 +151,7 @@ pub(crate) fn error_chain(error: &dyn std::error::Error) -> String {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use axum::body::to_bytes;
     use centaur_iron_control::{IronControlError, PrincipalDerivationError};
 
     #[test]
@@ -149,4 +163,25 @@ mod tests {
 
         assert_eq!(response.status(), StatusCode::BAD_REQUEST);
     }
+
+    #[tokio::test]
+    async fn principal_conflicts_include_structured_details() {
+        let response = ApiError::Runtime(SessionRuntimeError::Store(
+            SessionStoreError::PrincipalConflict {
+                thread_key: "workflow:report".to_owned(),
+                existing: "prn_finance".to_owned(),
+                requested: "prn_support".to_owned(),
+            },
+        ))
+        .into_response();
+
+        assert_eq!(response.status(), StatusCode::CONFLICT);
+        let body = to_bytes(response.into_body(), usize::MAX)
+            .await
+            .expect("read response body");
+        let body: serde_json::Value = serde_json::from_slice(&body).expect("decode response body");
+        assert_eq!(body["code"], json!("principal_conflict"));
+        assert_eq!(body["existing_principal"], json!("prn_finance"));
+        assert_eq!(body["requested_principal"], json!("prn_support"));
+    }
 }
diff --git a/services/api-rs/crates/centaur-session-runtime/src/lib.rs b/services/api-rs/crates/centaur-session-runtime/src/lib.rs
index 59f8b878e..ad3fbf9d9 100644
--- a/services/api-rs/crates/centaur-session-runtime/src/lib.rs
+++ b/services/api-rs/crates/centaur-session-runtime/src/lib.rs
@@ -1356,6 +1356,38 @@ impl SessionRuntime {
         metadata: Option<Value>,
         on_harness_conflict: HarnessConflictPolicy,
     ) -> Result<CreateOrGetSessionOutcome, SessionRuntimeError> {
+        self.create_or_get_session_with_principal(
+            thread_key,
+            harness_type,
+            persona_id,
+            metadata,
+            on_harness_conflict,
+            None,
+        )
+        .await
+    }
+
+    /// Create or load a session and bind it to an existing iron-control
+    /// principal selected by foreign ID. When no foreign ID is supplied, the
+    /// session keeps the normal principal derived from its thread key.
+    pub async fn create_or_get_session_with_principal(
+        &self,
+        thread_key: &ThreadKey,
+        harness_type: &HarnessType,
+        persona_id: Option<&str>,
+        metadata: Option<Value>,
+        on_harness_conflict: HarnessConflictPolicy,
+        principal_foreign_id: Option<&str>,
+    ) -> Result<CreateOrGetSessionOutcome, SessionRuntimeError> {
+        let principal_foreign_id = match principal_foreign_id {
+            Some(foreign_id) if foreign_id.trim().is_empty() => {
+                return Err(SessionRuntimeError::BadRequest(
+                    "principal must be a non-empty foreign ID".to_owned(),
+                ));
+            }
+            Some(foreign_id) => Some(foreign_id.trim()),
+            None => None,
+        };
         let span = info_span!(
             "centaur.api_rs.session.create_or_get",
             component = COMPONENT_SESSION_RUNTIME,
@@ -1382,17 +1414,21 @@ impl SessionRuntime {
             let mut harness_switched = false;
             let mut session_metadata = default_metadata(metadata);
             let proxy_labels = proxy_labels_from_session_metadata(thread_key, &session_metadata);
-            let registered_principal = self
-                .iron_control
-                .register_session(thread_key.as_str(), Some(&session_metadata))
-                .await?;
+            let registered_principal = match principal_foreign_id {
+                Some(foreign_id) => self.iron_control.get_principal(foreign_id).await?,
+                None => {
+                    self.iron_control
+                        .register_session(thread_key.as_str(), Some(&session_metadata))
+                        .await?
+                }
+            };
             let desired_capabilities = sandbox_capabilities_from_principal(&registered_principal);
             let persona_resolution =
                 self.resolve_persona_for_create(persona_id, &desired_capabilities)?;
             if let Some(context) = persona_resolution.context.as_ref() {
                 add_persona_metadata(&mut session_metadata, context);
             }
-            let session = match self
+            match self
                 .store
                 .create_or_get_session(
                     thread_key,
@@ -1428,6 +1464,14 @@ impl SessionRuntime {
                 }
                 Err(error) => return Err(error.into()),
             };
+            // Persist the principal OID on the session row so a resumed session
+            // can recreate its sandbox after a restart without re-deriving it.
+            // Existing sessions are immutable at this boundary: changing their
+            // credential identity requires a different session.
+            let session = self
+                .store
+                .bind_iron_control_principal(thread_key, &registered_principal.id)
+                .await?;
             if let Some(context) = self.resolve_stored_persona(
                 session.persona_id.as_deref(),
                 harness_type,
@@ -1446,12 +1490,6 @@ impl SessionRuntime {
                     )
                     .await?;
             }
-            // Persist the principal OID on the session row so a resumed session
-            // can recreate its sandbox after a restart without re-deriving it.
-            let session = self
-                .store
-                .set_iron_control_principal(thread_key, Some(&registered_principal.id))
-                .await?;
             info!(
                 component = COMPONENT_SESSION_RUNTIME,
                 event = "session_create_or_get_completed",
@@ -9173,6 +9211,64 @@ mod adoption_tests {
         )
     }
 
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn create_session_can_select_principal_by_foreign_id() {
+        let Some(store) = test_store().await else {
+            return;
+        };
+        let _serial = TEST_LOCK.lock().await;
+        let thread_key =
+            ThreadKey::parse(format!("test:principal-{}", uuid::Uuid::new_v4())).unwrap();
+        let backend = Arc::new(MockBackend::new(SandboxStatus::Running, Vec::new()));
+        let runtime = runtime_with(&store, backend);
+
+        let outcome = runtime
+            .create_or_get_session_with_principal(
+                &thread_key,
+                &HarnessType::Codex,
+                None,
+                Some(json!({})),
+                HarnessConflictPolicy::Reject,
+                Some(" finance-automation "),
+            )
+            .await
+            .expect("create session with selected principal");
+
+        assert_eq!(
+            outcome.session.iron_control_principal.as_deref(),
+            Some("finance-automation")
+        );
+
+        let error = runtime
+            .create_or_get_session_with_principal(
+                &thread_key,
+                &HarnessType::Codex,
+                None,
+                Some(json!({})),
+                HarnessConflictPolicy::Reject,
+                Some("support-automation"),
+            )
+            .await
+            .expect_err("existing session principal must not be rebound");
+        assert!(matches!(
+            error,
+            SessionRuntimeError::Store(SessionStoreError::PrincipalConflict {
+                existing,
+                requested,
+                ..
+            }) if existing == "finance-automation" && requested == "support-automation"
+        ));
+        assert_eq!(
+            store
+                .get_session(&thread_key)
+                .await
+                .expect("get session after conflict")
+                .iron_control_principal
+                .as_deref(),
+            Some("finance-automation")
+        );
+    }
+
     #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
     async fn enqueue_returns_after_durable_commit_without_waiting_for_sandbox() {
         let Some(store) = test_store().await else {
diff --git a/services/api-rs/crates/centaur-session-sqlx/src/lib.rs b/services/api-rs/crates/centaur-session-sqlx/src/lib.rs
index a71bc44b3..fc97d8f11 100644
--- a/services/api-rs/crates/centaur-session-sqlx/src/lib.rs
+++ b/services/api-rs/crates/centaur-session-sqlx/src/lib.rs
@@ -1372,6 +1372,47 @@ impl PgSessionStore {
         row.try_into()
     }
 
+    /// Bind a principal to a session without allowing an existing binding to
+    /// change. The conditional update makes concurrent first bindings atomic:
+    /// one caller wins, and a caller selecting a different principal receives
+    /// a conflict instead of rebinding the session.
+    pub async fn bind_iron_control_principal(
+        &self,
+        thread_key: &ThreadKey,
+        iron_control_principal: &str,
+    ) -> Result<Session, SessionStoreError> {
+        let row = sqlx::query_as::<_, SessionRow>(
+            r#"
+            update sessions
+            set iron_control_principal = $2, updated_at = now()
+            where thread_key = $1
+              and (iron_control_principal is null or iron_control_principal = $2)
+            returning thread_key, title, sandbox_id, sandbox_repo_cache_enabled, sandbox_repo_cache_access, sandbox_observability_enabled, harness_type, harness_thread_id, persona_id, status, iron_control_principal, proxy_labels, sandbox_last_active_at, created_at, updated_at
+            "#,
+        )
+        .bind(thread_key.as_str())
+        .bind(iron_control_principal)
+        .fetch_optional(&self.pool)
+        .await?;
+
+        if let Some(row) = row {
+            return row.try_into();
+        }
+
+        let session = self.get_session(thread_key).await?;
+        match session.iron_control_principal {
+            Some(existing) => Err(SessionStoreError::PrincipalConflict {
+                thread_key: thread_key.as_str().to_owned(),
+                existing,
+                requested: iron_control_principal.to_owned(),
+            }),
+            None => Err(SessionStoreError::InvalidPersistedValue(format!(
+                "session {} remained unbound after principal binding",
+                thread_key.as_str()
+            ))),
+        }
+    }
+
     pub async fn insert_ready_warm_sandbox(
         &self,
         sandbox_id: &str,
@@ -1650,6 +1691,12 @@ pub enum SessionStoreError {
         existing: Option<String>,
         requested: Option<String>,
     },
+    #[error("session {thread_key} already exists with principal {existing}, requested {requested}")]
+    PrincipalConflict {
+        thread_key: String,
+        existing: String,
+        requested: String,
+    },
     #[error("invalid persisted value: {0}")]
     InvalidPersistedValue(String),
     #[error("session execution not found for execution_id {execution_id}")]
diff --git a/services/api-rs/crates/centaur-workflows/src/lib.rs b/services/api-rs/crates/centaur-workflows/src/lib.rs
index e1ba67302..b12fc6f10 100644
--- a/services/api-rs/crates/centaur-workflows/src/lib.rs
+++ b/services/api-rs/crates/centaur-workflows/src/lib.rs
@@ -195,7 +195,7 @@ impl WorkflowEnablement {
         });
         metadata
             .principals
-            .retain(|workflow_name| self.is_enabled(workflow_name));
+            .retain(|workflow_name, _| self.is_enabled(workflow_name));
     }
 }
 
@@ -229,6 +229,12 @@ struct WorkflowPrincipalAssignments {
     registered: BTreeMap<String, String>,
 }
 
+#[derive(Clone, Debug, Eq, PartialEq)]
+enum WorkflowPrincipalDeclaration {
+    Managed,
+    Existing(String),
+}
+
 impl WorkflowPrincipalAssignments {
     fn principal_for_workflow(
         &self,
@@ -298,24 +304,30 @@ impl WorkflowPrincipalRegistrar {
 
     async fn register_workflow_principals(
         &self,
-        principals: &BTreeSet<String>,
+        principals: &BTreeMap<String, WorkflowPrincipalDeclaration>,
     ) -> Result<BTreeMap<String, String>, WorkflowRuntimeError> {
         let mut registered = BTreeMap::new();
-        for workflow_name in principals {
-            let foreign_id = canonical_workflow_principal_foreign_id(workflow_name);
-            let record = self
-                .client
-                .upsert_principal(&PrincipalInput {
-                    foreign_id,
-                    name: format!("Workflow {workflow_name}"),
-                    labels: workflow_principal_labels(workflow_name),
-                    kind: Some("workflow".to_owned()),
-                    slack_user_id: None,
-                    slack_channel_id: None,
-                    slack_team_id: None,
-                    slack_email: None,
-                })
-                .await?;
+        for (workflow_name, declaration) in principals {
+            let record = match declaration {
+                WorkflowPrincipalDeclaration::Managed => {
+                    let foreign_id = canonical_workflow_principal_foreign_id(workflow_name);
+                    self.client
+                        .upsert_principal(&PrincipalInput {
+                            foreign_id,
+                            name: format!("Workflow {workflow_name}"),
+                            labels: workflow_principal_labels(workflow_name),
+                            kind: Some("workflow".to_owned()),
+                            slack_user_id: None,
+                            slack_channel_id: None,
+                            slack_team_id: None,
+                            slack_email: None,
+                        })
+                        .await?
+                }
+                WorkflowPrincipalDeclaration::Existing(foreign_id) => {
+                    self.client.get_principal(foreign_id).await?
+                }
+            };
             registered.insert(workflow_name.clone(), record.id);
         }
         Ok(registered)
@@ -1657,7 +1669,14 @@ struct PythonWorkflowDiscovery {
     #[serde(default)]
     schedule: Option<Value>,
     #[serde(default)]
-    principal: Option<bool>,
+    principal: Option<PythonWorkflowPrincipal>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(untagged)]
+enum PythonWorkflowPrincipal {
+    Enabled(bool),
+    ForeignId(String),
 }
 
 #[derive(Debug, Deserialize)]
@@ -1670,7 +1689,7 @@ struct PythonWorkflowMetadata {
     webhooks: Vec<RegisteredWorkflowWebhook>,
     schedules: Vec<Value>,
     workflow_names: BTreeSet<String>,
-    principals: BTreeSet<String>,
+    principals: BTreeMap<String, WorkflowPrincipalDeclaration>,
 }
 
 fn metadata_from_discovery_payload(
@@ -1693,8 +1712,22 @@ fn metadata_from_discovery_payload(
             }
             metadata.schedules.push(schedule);
         }
-        if workflow.principal.unwrap_or(false) {
-            metadata.principals.insert(workflow.workflow_name);
+        match workflow.principal {
+            Some(PythonWorkflowPrincipal::Enabled(true)) => {
+                metadata.principals.insert(
+                    workflow.workflow_name,
+                    WorkflowPrincipalDeclaration::Managed,
+                );
+            }
+            Some(PythonWorkflowPrincipal::ForeignId(foreign_id))
+                if !foreign_id.trim().is_empty() =>
+            {
+                metadata.principals.insert(
+                    workflow.workflow_name,
+                    WorkflowPrincipalDeclaration::Existing(foreign_id.trim().to_owned()),
+                );
+            }
+            _ => {}
         }
     }
     metadata
@@ -1710,7 +1743,7 @@ async fn prepare_workflow_host_sandbox(
         if !discovery.principals.is_empty() {
             let workflow_names = discovery
                 .principals
-                .iter()
+                .keys()
                 .cloned()
                 .collect::<Vec<_>>()
                 .join(", ");
@@ -1737,15 +1770,16 @@ async fn reconcile_workflow_principals(
     enablement: &WorkflowEnablement,
 ) -> Result<(), WorkflowRuntimeError> {
     let mut principals = discovery.principals.clone();
-    principals.retain(|workflow_name| enablement.is_enabled(workflow_name));
+    principals.retain(|workflow_name, _| enablement.is_enabled(workflow_name));
+    let required = principals.keys().cloned().collect();
     let registered = match registrar.register_workflow_principals(&principals).await {
         Ok(registered) => registered,
         Err(error) => {
-            sandbox.update_workflow_principals(BTreeMap::new(), principals);
+            sandbox.update_workflow_principals(BTreeMap::new(), required);
             return Err(error);
         }
     };
-    sandbox.update_workflow_principals(registered, principals);
+    sandbox.update_workflow_principals(registered, required);
     Ok(())
 }
 
@@ -2661,6 +2695,7 @@ async fn run_centaur_workflow_inner(
                 .get("max_duration_ms")
                 .and_then(Value::as_u64)
                 .unwrap_or(DEFAULT_AGENT_MAX_DURATION_MS);
+            let principal_foreign_id = parse_agent_principal(&input.input).map_err(absurd_error)?;
             let agent = ctx
                 .step("agent_turn", || {
                     let session_runtime = session_runtime.clone();
@@ -2683,6 +2718,7 @@ async fn run_centaur_workflow_inner(
                                 thread_key,
                                 harness_type,
                                 persona_id: None,
+                                principal_foreign_id,
                                 parts: vec![json!({"type": "text", "text": prompt})],
                                 client_message_id: client_message_id.clone(),
                                 session_metadata: metadata.clone(),
@@ -3570,6 +3606,7 @@ async fn run_python_agent_turn(
         .or_else(|| args.get("persona"))
         .and_then(Value::as_str)
         .map(ToOwned::to_owned);
+    let principal_foreign_id = parse_agent_principal(&args)?;
     let client_message_id = args
         .get("message_id")
         .or_else(|| args.get("client_message_id"))
@@ -3599,6 +3636,13 @@ async fn run_python_agent_turn(
     if let Some(engine) = args.get("engine").and_then(Value::as_str) {
         object_insert(&mut execution_metadata, "engine", json!(engine));
     }
+    if let Some(principal) = principal_foreign_id.as_deref() {
+        object_insert(
+            &mut execution_metadata,
+            "principal_foreign_id",
+            json!(principal),
+        );
+    }
     let idle_timeout_ms = args
         .get("idle_timeout_ms")
         .and_then(Value::as_u64)
@@ -3630,6 +3674,7 @@ async fn run_python_agent_turn(
             thread_key,
             harness_type,
             persona_id,
+            principal_foreign_id,
             parts,
             client_message_id,
             session_metadata,
@@ -3865,6 +3910,26 @@ fn first_str_arg(args: &Value, keys: &[&str]) -> Option<String> {
         .map(ToOwned::to_owned)
 }
 
+fn parse_agent_principal(args: &Value) -> Result<Option<String>, WorkflowRuntimeError> {
+    let Some(value) = args
+        .get("principal")
+        .or_else(|| args.get("principal_foreign_id"))
+    else {
+        return Ok(None);
+    };
+    let foreign_id = value.as_str().map(str::trim).ok_or_else(|| {
+        WorkflowRuntimeError::BadRequest(
+            "ctx.agent_turn principal must be a non-empty foreign ID".to_owned(),
+        )
+    })?;
+    if foreign_id.is_empty() {
+        return Err(WorkflowRuntimeError::BadRequest(
+            "ctx.agent_turn principal must be a non-empty foreign ID".to_owned(),
+        ));
+    }
+    Ok(Some(foreign_id.to_owned()))
+}
+
 fn parse_agent_harness(args: &Value) -> Result<Option<HarnessType>, WorkflowRuntimeError> {
     let Some(raw) = args
         .get("harness_type")
@@ -4130,6 +4195,7 @@ struct AgentTurnRequest {
     thread_key: String,
     harness_type: HarnessType,
     persona_id: Option<String>,
+    principal_foreign_id: Option<String>,
     parts: Vec<Value>,
     client_message_id: String,
     session_metadata: Value,
@@ -4185,6 +4251,7 @@ async fn run_agent_session_turn(
         thread_key,
         harness_type,
         persona_id,
+        principal_foreign_id,
         parts,
         client_message_id,
         session_metadata,
@@ -4204,12 +4271,13 @@ async fn run_agent_session_turn(
         object_insert(&mut session_metadata, "workflow_owned_thread", json!(true));
     }
     session_runtime
-        .create_or_get_session(
+        .create_or_get_session_with_principal(
             &thread_key,
             &harness_type,
             persona_id.as_deref(),
             Some(session_metadata),
             HarnessConflictPolicy::Reject,
+            principal_foreign_id.as_deref(),
         )
         .await?;
     session_runtime
@@ -4431,6 +4499,21 @@ mod tests {
         assert_eq!(first_str_arg(&json!({"model": "   "}), &["model"]), None);
     }
 
+    #[test]
+    fn parse_agent_principal_accepts_foreign_id_and_rejects_invalid_values() {
+        assert_eq!(
+            parse_agent_principal(&json!({"principal": " finance-automation "})).unwrap(),
+            Some("finance-automation".to_owned())
+        );
+        assert_eq!(
+            parse_agent_principal(&json!({"principal_foreign_id": "support"})).unwrap(),
+            Some("support".to_owned())
+        );
+        assert_eq!(parse_agent_principal(&json!({})).unwrap(), None);
+        assert!(parse_agent_principal(&json!({"principal": "  "})).is_err());
+        assert!(parse_agent_principal(&json!({"principal": true})).is_err());
+    }
+
     #[test]
     fn parse_agent_batch_requires_unique_names_and_adds_metadata() {
         let message = json!({
@@ -4440,6 +4523,7 @@ mod tests {
                 {
                     "name": "correctness",
                     "text": "Review correctness",
+                    "principal": "security-reviewers",
                     "metadata": {"pr": 42}
                 },
                 {"name": "security", "text": "Review security"}
@@ -4457,6 +4541,10 @@ mod tests {
             vec!["correctness", "security"]
         );
         assert_eq!(agents[0].args.pointer("/metadata/pr"), Some(&json!(42)));
+        assert_eq!(
+            agents[0].args.get("principal"),
+            Some(&json!("security-reviewers"))
+        );
         assert_eq!(
             agents[0]
                 .args
@@ -4836,6 +4924,7 @@ mod tests {
                 {
                     "workflow_name": "manual_workflow",
                     "source_path": "workflows/manual_workflow.py",
+                    "principal": "finance-automation",
                 },
             ],
         }))
@@ -4853,7 +4942,16 @@ mod tests {
             metadata.schedules[0].get("workflow_name"),
             Some(&json!("scheduled_workflow"))
         );
-        assert!(metadata.principals.contains("scheduled_workflow"));
+        assert_eq!(
+            metadata.principals.get("scheduled_workflow"),
+            Some(&WorkflowPrincipalDeclaration::Managed)
+        );
+        assert_eq!(
+            metadata.principals.get("manual_workflow"),
+            Some(&WorkflowPrincipalDeclaration::Existing(
+                "finance-automation".to_owned()
+            ))
+        );
     }
 
     #[test]
@@ -4911,7 +5009,10 @@ mod tests {
     #[tokio::test]
     async fn workflow_principal_requires_workflow_host_sandbox() {
         let discovery = PythonWorkflowMetadata {
-            principals: BTreeSet::from(["nightly_report".to_owned()]),
+            principals: BTreeMap::from([(
+                "nightly_report".to_owned(),
+                WorkflowPrincipalDeclaration::Managed,
+            )]),
             workflow_names: BTreeSet::from(["nightly_report".to_owned()]),
             ..PythonWorkflowMetadata::default()
         };
@@ -5123,7 +5224,7 @@ mod tests {
         assert_eq!(metadata.webhooks.len(), 1);
         assert_eq!(metadata.webhooks[0].workflow_name, "allowed_workflow");
         assert_eq!(
-            metadata.principals.iter().cloned().collect::<Vec<_>>(),
+            metadata.principals.keys().cloned().collect::<Vec<_>>(),
             vec!["allowed_workflow".to_owned()]
         );
     }
diff --git a/services/workflow-python/tests/test_workflow_host.py b/services/workflow-python/tests/test_workflow_host.py
index 590915e40..f894a1a5b 100644
--- a/services/workflow-python/tests/test_workflow_host.py
+++ b/services/workflow-python/tests/test_workflow_host.py
@@ -312,6 +312,25 @@ def test_agent_turn_per_call_kwargs_override_agent_defaults(self) -> None:
             {"model": "claude-opus-4-8", "reasoning": "low", "text": "cheap step"},
         )
 
+    def test_agent_turn_forwards_principal_foreign_id(self) -> None:
+        host = load_workflow_host()
+        rpc = RequestRpc()
+        ctx = host.WorkflowContext(
+            rpc,
+            run_id="run-123",
+            task_id="task-456",
+            workflow_name="sample",
+        )
+
+        result = asyncio.run(
+            ctx.agent_turn("do the thing", principal="finance-automation")
+        )
+
+        self.assertEqual(
+            result,
+            {"principal": "finance-automation", "text": "do the thing"},
+        )
+
     def test_run_agents_applies_defaults_and_preserves_input_order(self) -> None:
         host = load_workflow_host()
         rpc = RequestRpc()
@@ -578,6 +597,21 @@ def test_load_workflow_file_reads_workflow_principal(self) -> None:
         assert registered is not None
         self.assertEqual(host.normalize_principal(registered), True)
 
+    def test_load_workflow_file_reads_workflow_principal_foreign_id(self) -> None:
+        host = load_workflow_host()
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "principal_workflow.py"
+            path.write_text(
+                "WORKFLOW_NAME = 'principal_workflow'\n"
+                "WORKFLOW_PRINCIPAL = ' finance-automation '\n"
+                "def handler(inp, ctx):\n"
+                "    return None\n"
+            )
+            registered = host.load_workflow_file(path)
+
+        assert registered is not None
+        self.assertEqual(host.normalize_principal(registered), "finance-automation")
+
     def test_workflow_name_from_source_reads_string_constant(self) -> None:
         host = load_workflow_host()
         with tempfile.TemporaryDirectory() as tmp:
diff --git a/services/workflow-python/workflow_host.py b/services/workflow-python/workflow_host.py
index fae51bd2e..755e5c5ca 100644
--- a/services/workflow-python/workflow_host.py
+++ b/services/workflow-python/workflow_host.py
@@ -356,9 +356,14 @@ def normalize_schedule(workflow: RegisteredWorkflow) -> dict[str, Any] | None:
     return schedule
 
 
-def normalize_principal(workflow: RegisteredWorkflow) -> bool | None:
+def normalize_principal(workflow: RegisteredWorkflow) -> bool | str | None:
     raw = workflow.principal
-    return raw if isinstance(raw, bool) and raw else None
+    if isinstance(raw, bool):
+        return raw or None
+    if isinstance(raw, str):
+        foreign_id = raw.strip()
+        return foreign_id or None
+    return None
 
 
 async def run_workflow(message: dict[str, Any], rpc: RpcClient) -> dict[str, Any]:

From 98fba269ce0b87a7642499d8d6dee2f909e949e5 Mon Sep 17 00:00:00 2001
From: Oliver Ponder <oliver.ponder@gmail.com>
Date: Tue, 18 Aug 2026 20:38:15 +0000
Subject: [PATCH 05/36] fix(sentry): expose read-only client commands through
 the CLI (#1419)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

fix(sentry): expose read-only client commands (fork patch)

Re-applies the fork's one genuine change (#13) on top of upstream main
b985a365 — the replace-with-upstream sync recipe from #15.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
---
 tools/infra/sentry/cli.py      | 126 ++++++++++++++++++++++++++++++--
 tools/infra/sentry/test_cli.py | 129 +++++++++++++++++++++++++++++++++
 2 files changed, 248 insertions(+), 7 deletions(-)
 create mode 100644 tools/infra/sentry/test_cli.py

diff --git a/tools/infra/sentry/cli.py b/tools/infra/sentry/cli.py
index 6dc939e1d..15cd2a664 100644
--- a/tools/infra/sentry/cli.py
+++ b/tools/infra/sentry/cli.py
@@ -1,15 +1,18 @@
-"""CLI for Sentry issues."""
+"""CLI for browsing Sentry issues and events (read-only)."""
 
+import json
+from collections.abc import Callable
+from typing import Any
+
+import typer
 from dotenv import load_dotenv
 
 load_dotenv()
 
-import json
-import typer
-
 app = typer.Typer(
     name="sentry",
     help="Sentry issues — list/search issues, issue details, events, stacktraces, and tag values (read-only)",
+    no_args_is_help=True,
 )
 
 
@@ -18,12 +21,30 @@ def main() -> None:
     """sentry CLI."""
 
 
+def get_client():
+    from .client import _client
+
+    return _client()
+
+
+def _emit(result: Any) -> None:
+    print(json.dumps(result, indent=2, ensure_ascii=False, default=str))
+
+
+def _run(operation: Callable[[Any], Any]) -> None:
+    client = get_client()
+    try:
+        _emit(operation(client))
+    finally:
+        close = getattr(client, "close", None)
+        if callable(close):
+            close()
+
+
 @app.command("health")
 def health():
     """Assert sentry connectivity and auth with a safe read-only check."""
-    from .client import _client
-
-    client = _client()
+    client = get_client()
     try:
         details = client.list_organizations()
         payload = {"ok": True, "tool": "sentry", "error": None, "details": details}
@@ -38,5 +59,96 @@ def health():
     print(json.dumps(payload, indent=2, ensure_ascii=False, default=str))
 
 
+@app.command("list-organizations")
+def list_organizations() -> None:
+    """List Sentry organizations available to the configured token."""
+    _run(lambda client: client.list_organizations())
+
+
+@app.command("list-projects")
+def list_projects(
+    organization_slug: str = typer.Argument(..., help="Sentry organization slug"),
+) -> None:
+    """List projects in a Sentry organization."""
+    _run(lambda client: client.list_projects(organization_slug))
+
+
+@app.command("list-issues")
+def list_issues(
+    organization_slug: str = typer.Argument(..., help="Sentry organization slug"),
+    project_slug: str | None = typer.Option(
+        None, "--project", "-p", help="Restrict results to this project slug"
+    ),
+    query: str = typer.Option(
+        "is:unresolved", "--query", "-q", help="Native Sentry issue search query"
+    ),
+    sort: str = typer.Option("date", "--sort", help="Sort by date, new, freq, user, or priority"),
+    stats_period: str = typer.Option(
+        "14d", "--stats-period", help="Relative search window, e.g. 24h, 14d, or 90d"
+    ),
+    limit: int = typer.Option(25, "--limit", "-n", min=1, help="Maximum issues to return"),
+) -> None:
+    """List or search issues using Sentry's native query syntax."""
+    _run(
+        lambda client: client.list_issues(
+            organization_slug=organization_slug,
+            project_slug=project_slug,
+            query=query,
+            sort=sort,
+            stats_period=stats_period,
+            limit=limit,
+        )
+    )
+
+
+@app.command("get-issue")
+def get_issue(
+    organization_slug: str = typer.Argument(..., help="Sentry organization slug"),
+    issue_id: str = typer.Argument(..., help="Numeric issue id or short id"),
+) -> None:
+    """Get details for one Sentry issue."""
+    _run(lambda client: client.get_issue(organization_slug, issue_id))
+
+
+@app.command("list-issue-events")
+def list_issue_events(
+    organization_slug: str = typer.Argument(..., help="Sentry organization slug"),
+    issue_id: str = typer.Argument(..., help="Numeric issue id or short id"),
+    full: bool = typer.Option(False, "--full", help="Include each full event payload"),
+    limit: int = typer.Option(25, "--limit", "-n", min=1, help="Maximum events to return"),
+) -> None:
+    """List individual events for a Sentry issue."""
+    _run(
+        lambda client: client.list_issue_events(
+            organization_slug=organization_slug,
+            issue_id=issue_id,
+            full=full,
+            limit=limit,
+        )
+    )
+
+
+@app.command("get-event")
+def get_event(
+    organization_slug: str = typer.Argument(..., help="Sentry organization slug"),
+    issue_id: str = typer.Argument(..., help="Numeric issue id or short id"),
+    event_id: str = typer.Option(
+        "latest", "--event-id", "-e", help="Specific event id, latest, or oldest"
+    ),
+) -> None:
+    """Get one full event, including stacktrace and breadcrumbs."""
+    _run(lambda client: client.get_event(organization_slug, issue_id, event_id=event_id))
+
+
+@app.command("get-issue-tag-values")
+def get_issue_tag_values(
+    organization_slug: str = typer.Argument(..., help="Sentry organization slug"),
+    issue_id: str = typer.Argument(..., help="Numeric issue id or short id"),
+    tag_key: str = typer.Argument(..., help="Tag key, e.g. release or browser"),
+) -> None:
+    """Get the value distribution for one tag on a Sentry issue."""
+    _run(lambda client: client.get_issue_tag_values(organization_slug, issue_id, tag_key))
+
+
 if __name__ == "__main__":
     app()
diff --git a/tools/infra/sentry/test_cli.py b/tools/infra/sentry/test_cli.py
new file mode 100644
index 000000000..77cef000e
--- /dev/null
+++ b/tools/infra/sentry/test_cli.py
@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import importlib.util
+import json
+import sys
+import types
+from pathlib import Path
+
+from typer.testing import CliRunner
+
+package = types.ModuleType("centaur_tool_sentry")
+package.__path__ = [str(Path(__file__).parent)]
+sys.modules.setdefault("centaur_tool_sentry", package)
+
+spec = importlib.util.spec_from_file_location(
+    "centaur_tool_sentry.cli", Path(__file__).with_name("cli.py")
+)
+assert spec and spec.loader
+cli = importlib.util.module_from_spec(spec)
+sys.modules[spec.name] = cli
+spec.loader.exec_module(cli)
+
+
+class FakeClient:
+    def __init__(self) -> None:
+        self.calls: list[tuple[str, tuple, dict]] = []
+        self.closed = 0
+
+    def _record(self, method: str, *args, **kwargs):
+        self.calls.append((method, args, kwargs))
+        return {"method": method}
+
+    def list_organizations(self):
+        return self._record("list_organizations")
+
+    def list_projects(self, organization_slug: str):
+        return self._record("list_projects", organization_slug)
+
+    def list_issues(self, **kwargs):
+        return self._record("list_issues", **kwargs)
+
+    def get_issue(self, organization_slug: str, issue_id: str):
+        return self._record("get_issue", organization_slug, issue_id)
+
+    def list_issue_events(self, **kwargs):
+        return self._record("list_issue_events", **kwargs)
+
+    def get_event(self, organization_slug: str, issue_id: str, event_id: str):
+        return self._record("get_event", organization_slug, issue_id, event_id=event_id)
+
+    def get_issue_tag_values(self, organization_slug: str, issue_id: str, tag_key: str):
+        return self._record("get_issue_tag_values", organization_slug, issue_id, tag_key)
+
+    def close(self) -> None:
+        self.closed += 1
+
+
+def test_commands_wrap_existing_client_methods(monkeypatch) -> None:
+    client = FakeClient()
+    monkeypatch.setattr(cli, "get_client", lambda: client)
+    runner = CliRunner()
+
+    invocations = [
+        (["list-organizations"], "list_organizations"),
+        (["list-projects", "splits"], "list_projects"),
+        (
+            [
+                "list-issues",
+                "splits",
+                "--project",
+                "server",
+                "--query",
+                "is:resolved level:error",
+                "--sort",
+                "freq",
+                "--stats-period",
+                "24h",
+                "--limit",
+                "10",
+            ],
+            "list_issues",
+        ),
+        (["get-issue", "splits", "SERVER-1"], "get_issue"),
+        (
+            ["list-issue-events", "splits", "SERVER-1", "--full", "--limit", "5"],
+            "list_issue_events",
+        ),
+        (["get-event", "splits", "SERVER-1", "--event-id", "deadbeef"], "get_event"),
+        (
+            ["get-issue-tag-values", "splits", "SERVER-1", "release"],
+            "get_issue_tag_values",
+        ),
+    ]
+
+    for args, expected_method in invocations:
+        result = runner.invoke(cli.app, args)
+        assert result.exit_code == 0, result.output
+        assert json.loads(result.output) == {"method": expected_method}
+
+    assert client.calls == [
+        ("list_organizations", (), {}),
+        ("list_projects", ("splits",), {}),
+        (
+            "list_issues",
+            (),
+            {
+                "organization_slug": "splits",
+                "project_slug": "server",
+                "query": "is:resolved level:error",
+                "sort": "freq",
+                "stats_period": "24h",
+                "limit": 10,
+            },
+        ),
+        ("get_issue", ("splits", "SERVER-1"), {}),
+        (
+            "list_issue_events",
+            (),
+            {
+                "organization_slug": "splits",
+                "issue_id": "SERVER-1",
+                "full": True,
+                "limit": 5,
+            },
+        ),
+        ("get_event", ("splits", "SERVER-1"), {"event_id": "deadbeef"}),
+        ("get_issue_tag_values", ("splits", "SERVER-1", "release"), {}),
+    ]
+    assert client.closed == len(invocations)

From 2514c4ece86c66ad4af3f3149881328160fe3fe7 Mon Sep 17 00:00:00 2001
From: Ksawery <ksawerywr@gmail.com>
Date: Tue, 18 Aug 2026 20:39:30 +0000
Subject: [PATCH 06/36] feat: add an option to configure OpenAI base URL
 (#1370)

* feat: add an option to configure openAI base url

* fix: preserve activity summary endpoint overrides

* fix: remove ineffective Codex base URL config

* refactor: remove unused OpenAI URL re-export

* chore(chart): bump chart version to 0.1.117

---------

Co-authored-by: Matthew Slipper <me@matthewslipper.com>
---
 contrib/chart/Chart.yaml                      |  2 +-
 contrib/chart/values.yaml                     |  1 +
 docs/pages/reference/configuration.mdx        |  2 +
 services/api-rs/Cargo.lock                    |  1 +
 services/api-rs/Cargo.toml                    |  1 +
 .../src/activity_summary.rs                   |  2 +-
 .../crates/centaur-api-server/src/args.rs     | 68 ++++++++++++++++++-
 .../crates/centaur-iron-proxy/Cargo.toml      |  1 +
 .../crates/centaur-iron-proxy/src/error.rs    |  2 +
 .../crates/centaur-iron-proxy/src/fragment.rs | 61 ++++++++++++++++-
 .../src/title_generator.rs                    | 13 +++-
 11 files changed, 146 insertions(+), 8 deletions(-)

diff --git a/contrib/chart/Chart.yaml b/contrib/chart/Chart.yaml
index 938aef849..073bd07ef 100644
--- a/contrib/chart/Chart.yaml
+++ b/contrib/chart/Chart.yaml
@@ -2,7 +2,7 @@ apiVersion: v2
 name: centaur
 description: Helm chart for the trusted Centaur control plane
 type: application
-version: 0.1.119
+version: 0.1.120
 appVersion: "0.1.0"
 dependencies:
   - name: connect
diff --git a/contrib/chart/values.yaml b/contrib/chart/values.yaml
index d8a9a6509..0c97eb736 100644
--- a/contrib/chart/values.yaml
+++ b/contrib/chart/values.yaml
@@ -485,6 +485,7 @@ apiRs:
   activitySummary:
     enabled: false
     model: gpt-5.4-nano
+    # Deprecated compatibility fallback. Prefer OPENAI_BASE_URL in apiRs.extraEnv.
     openaiBaseUrl: https://api.openai.com/v1
     minIntervalSecs: 20
     timeoutSecs: 5
diff --git a/docs/pages/reference/configuration.mdx b/docs/pages/reference/configuration.mdx
index bc7a42cf5..c9ed75475 100644
--- a/docs/pages/reference/configuration.mdx
+++ b/docs/pages/reference/configuration.mdx
@@ -119,6 +119,8 @@ created. Changing a default does not rewrite existing principals.
 | `apiRs.activitySummary.*` | Helm values, default disabled. | Enables API-RS to summarize live session activity into durable `session.activity_summary` events. |
 | `SLACK_BOT_TOKEN` | Explicit `secretKeyRef` from `secretManager.existingSecretName`. | Slack Web API access for api-rs Slack proxy and workflow Slack helpers. |
 | `OPENAI_API_KEY` | Secret mounted into api-rs, or `apiRs.extraEnv` for local/dev overrides. | OpenAI credential for activity summaries; the feature stays disabled when no key is present. |
+| `OPENAI_BASE_URL` | `apiRs.extraEnv`; default `https://api.openai.com/v1`. | OpenAI-compatible Responses API base URL for every api-rs OpenAI caller: Codex, generated session titles, and activity summaries. API-RS passes it into Codex sandboxes and derives iron-proxy's `OPENAI_API_KEY` host scope from it. |
+| `SESSION_ACTIVITY_SUMMARY_OPENAI_BASE_URL` | Deprecated `apiRs.activitySummary.openaiBaseUrl` compatibility setting. | Existing activity-summary endpoint override. `OPENAI_BASE_URL` takes precedence when both are set. |
 | `SESSION_ACTIVITY_SUMMARY_MODEL` | `apiRs.activitySummary.model`, default `gpt-5.4-nano`. | Model used for the short live activity sentence. |
 
 Sandbox lifecycle:
diff --git a/services/api-rs/Cargo.lock b/services/api-rs/Cargo.lock
index ea31e6f9f..27dab10bc 100644
--- a/services/api-rs/Cargo.lock
+++ b/services/api-rs/Cargo.lock
@@ -939,6 +939,7 @@ dependencies = [
  "serde_yaml",
  "strum",
  "thiserror 2.0.19",
+ "url",
 ]
 
 [[package]]
diff --git a/services/api-rs/Cargo.toml b/services/api-rs/Cargo.toml
index c0354323d..6631c1129 100644
--- a/services/api-rs/Cargo.toml
+++ b/services/api-rs/Cargo.toml
@@ -89,6 +89,7 @@ strum = { version = "0.28", features = ["derive"] }
 subtle = "2"
 test-case = "3.3.1"
 thiserror = "2"
+url = "2"
 time = { version = "0.3", features = ["serde", "serde-well-known"] }
 tokio = "1"
 tokio-util = "0.7"
diff --git a/services/api-rs/crates/centaur-api-server/src/activity_summary.rs b/services/api-rs/crates/centaur-api-server/src/activity_summary.rs
index 6f63dff11..df255cb60 100644
--- a/services/api-rs/crates/centaur-api-server/src/activity_summary.rs
+++ b/services/api-rs/crates/centaur-api-server/src/activity_summary.rs
@@ -865,7 +865,7 @@ impl ActivitySummaryClient {
             .timeout(config.timeout)
             .build()
             .map_err(ActivitySummaryError::Http)?;
-        let responses_url = format!("{}/responses", config.base_url.trim_end_matches('/'));
+        let responses_url = format!("{}/responses", config.base_url);
         Ok(Self {
             api_key: config.api_key.clone(),
             client,
diff --git a/services/api-rs/crates/centaur-api-server/src/args.rs b/services/api-rs/crates/centaur-api-server/src/args.rs
index 014063013..86393ce6e 100644
--- a/services/api-rs/crates/centaur-api-server/src/args.rs
+++ b/services/api-rs/crates/centaur-api-server/src/args.rs
@@ -148,6 +148,8 @@ struct ActivitySummaryArgs {
         default_value = "gpt-5.4-nano"
     )]
     model: String,
+    /// Deprecated activity-summary-specific endpoint. `OPENAI_BASE_URL` takes
+    /// precedence when set, but this remains supported for existing deployments.
     #[arg(
         long = "session-activity-summary-openai-base-url",
         env = "SESSION_ACTIVITY_SUMMARY_OPENAI_BASE_URL",
@@ -196,8 +198,11 @@ impl ActivitySummaryArgs {
             );
             return None;
         };
+        let base_url = clean_optional_value(env::var("OPENAI_BASE_URL").ok().as_deref())
+            .map(|value| value.trim_end_matches('/').to_owned())
+            .unwrap_or_else(|| self.openai_base_url.trim_end_matches('/').to_owned());
         Some(ActivitySummaryConfig {
-            base_url: self.openai_base_url.clone(),
+            base_url,
             api_key,
             max_facts: usize::try_from(self.max_facts).unwrap_or(usize::MAX),
             max_output_tokens: u16::try_from(self.max_output_tokens).unwrap_or(u16::MAX),
@@ -1012,6 +1017,12 @@ impl SandboxArgs {
         let codex_auth_mode = clean_optional_value(env::var("CODEX_AUTH_MODE").ok().as_deref())
             .unwrap_or_else(|| "api_key".to_owned());
         envs.push(("CODEX_AUTH_MODE".to_owned(), codex_auth_mode.clone()));
+        if codex_auth_mode == "api_key"
+            && let Some(base_url) =
+                clean_optional_value(env::var("OPENAI_BASE_URL").ok().as_deref())
+        {
+            envs.push(("OPENAI_BASE_URL".to_owned(), base_url));
+        }
         if let Some(mode) = clean_optional_value(env::var("CLAUDE_CODE_AUTH_MODE").ok().as_deref())
         {
             envs.push(("CLAUDE_CODE_AUTH_MODE".to_owned(), mode));
@@ -1020,8 +1031,8 @@ impl SandboxArgs {
         // Inject the infra/harness placeholder credentials so env-based
         // consumers send the proxy_value iron-proxy replaces with the real
         // secret: codex's OPENAI_API_KEY (api_key mode -> codex logs in and
-        // hits api.openai.com instead of falling back to the ChatGPT
-        // auth.json), git/gh's GITHUB_TOKEN, the slack tool's
+        // hits OPENAI_BASE_URL (api.openai.com by default) instead of falling
+        // back to the ChatGPT auth.json), git/gh's GITHUB_TOKEN, the slack tool's
         // SLACK_BOT_TOKEN, and the rest of the infra set.
         for (name, value) in self.iron_proxy.sandbox_placeholder_env()? {
             if !envs.iter().any(|(existing, _)| existing == &name) {
@@ -2193,6 +2204,52 @@ mod tests {
         assert_eq!(config.api_key, "sk-test");
     }
 
+    #[test]
+    fn activity_summary_preserves_legacy_base_url_when_global_url_is_unset() {
+        let _lock = ENV_LOCK.lock().unwrap();
+        let _env = EnvGuard::set(&[
+            ("OPENAI_API_KEY", "sk-test"),
+            ("OPENAI_BASE_URL", ""),
+            (
+                "SESSION_ACTIVITY_SUMMARY_OPENAI_BASE_URL",
+                "https://legacy-compatible.example/v1/",
+            ),
+        ]);
+        let args = Args::try_parse_from([
+            "centaur-api-server",
+            "--database-url",
+            "postgres://postgres:postgres@localhost/centaur",
+            "--session-activity-summary-enabled",
+            "true",
+        ])
+        .unwrap();
+
+        let config = args.activity_summary_config().unwrap();
+        assert_eq!(config.base_url, "https://legacy-compatible.example/v1");
+    }
+
+    #[test]
+    fn activity_summary_global_base_url_overrides_legacy_base_url() {
+        let _lock = ENV_LOCK.lock().unwrap();
+        let _env = EnvGuard::set(&[
+            ("OPENAI_API_KEY", "sk-test"),
+            ("OPENAI_BASE_URL", "https://global-compatible.example/v1/"),
+        ]);
+        let args = Args::try_parse_from([
+            "centaur-api-server",
+            "--database-url",
+            "postgres://postgres:postgres@localhost/centaur",
+            "--session-activity-summary-enabled",
+            "true",
+            "--session-activity-summary-openai-base-url",
+            "https://legacy-compatible.example/v1",
+        ])
+        .unwrap();
+
+        let config = args.activity_summary_config().unwrap();
+        assert_eq!(config.base_url, "https://global-compatible.example/v1");
+    }
+
     #[test]
     fn activity_summary_uses_mounted_openai_key_even_with_onepassword_connect_source() {
         let _lock = ENV_LOCK.lock().unwrap();
@@ -2652,6 +2709,8 @@ mod tests {
 
     #[test]
     fn codex_app_server_env_template_injects_auth_mode_and_placeholder() {
+        let _lock = ENV_LOCK.lock().unwrap();
+        let _env = EnvGuard::set(&[("OPENAI_BASE_URL", "https://compatible-api.example/v1")]);
         let args = Args::try_parse_from([
             "centaur-api-server",
             "--database-url",
@@ -2675,6 +2734,9 @@ mod tests {
         // The codex auth mode is propagated so the sandbox agent matches the
         // proxy's registered credential.
         assert!(env.iter().any(|(name, _)| name == "CODEX_AUTH_MODE"));
+        assert!(env.iter().any(|(name, value)| {
+            name == "OPENAI_BASE_URL" && value == "https://compatible-api.example/v1"
+        }));
         // api_key mode (the default) injects the placeholder the egress proxy
         // replaces, so codex logs in and hits api.openai.com instead of
         // falling back to the ChatGPT auth.json.
diff --git a/services/api-rs/crates/centaur-iron-proxy/Cargo.toml b/services/api-rs/crates/centaur-iron-proxy/Cargo.toml
index d0741eae3..0e083ccb9 100644
--- a/services/api-rs/crates/centaur-iron-proxy/Cargo.toml
+++ b/services/api-rs/crates/centaur-iron-proxy/Cargo.toml
@@ -10,6 +10,7 @@ serde.workspace = true
 serde_yaml.workspace = true
 strum.workspace = true
 thiserror.workspace = true
+url.workspace = true
 
 [lints]
 workspace = true
diff --git a/services/api-rs/crates/centaur-iron-proxy/src/error.rs b/services/api-rs/crates/centaur-iron-proxy/src/error.rs
index a4c689106..6d9f902ab 100644
--- a/services/api-rs/crates/centaur-iron-proxy/src/error.rs
+++ b/services/api-rs/crates/centaur-iron-proxy/src/error.rs
@@ -9,6 +9,8 @@ pub enum IronProxyConfigError {
         path: PathBuf,
         source: serde_yaml::Error,
     },
+    #[error("invalid OPENAI_BASE_URL {value:?}: {reason}")]
+    InvalidOpenAiBaseUrl { value: String, reason: String },
 }
 
 pub type Result<T> = std::result::Result<T, IronProxyConfigError>;
diff --git a/services/api-rs/crates/centaur-iron-proxy/src/fragment.rs b/services/api-rs/crates/centaur-iron-proxy/src/fragment.rs
index eafb52612..c6a28d7f1 100644
--- a/services/api-rs/crates/centaur-iron-proxy/src/fragment.rs
+++ b/services/api-rs/crates/centaur-iron-proxy/src/fragment.rs
@@ -28,8 +28,10 @@ pub fn harness_auth_fragment(engine: &str, auth_mode: &str) -> Result<Option<Pro
     if engine == "amazon-bedrock" && normalize_auth_mode(auth_mode) == "api_key" {
         return bedrock_aws_auth_fragment().map(Some);
     }
+    if engine == "codex" && normalize_auth_mode(auth_mode) == "api_key" {
+        return codex_api_key_fragment().map(Some);
+    }
     let yaml = match (engine, normalize_auth_mode(auth_mode).as_str()) {
-        ("codex", "api_key") => CODEX_API_KEY_FRAGMENT,
         ("codex", "access_token") => CODEX_ACCESS_TOKEN_FRAGMENT,
         ("hermes", "api_key") => HERMES_API_KEY_FRAGMENT,
         ("openrouter", "api_key") => OPENROUTER_API_KEY_FRAGMENT,
@@ -41,6 +43,39 @@ pub fn harness_auth_fragment(engine: &str, auth_mode: &str) -> Result<Option<Pro
     load_fragment_str(yaml).map(Some)
 }
 
+fn codex_api_key_fragment() -> Result<ProxyFragment> {
+    codex_api_key_fragment_for_base_url(std::env::var("OPENAI_BASE_URL").ok().as_deref())
+}
+
+fn codex_api_key_fragment_for_base_url(configured_base_url: Option<&str>) -> Result<ProxyFragment> {
+    let base_url = configured_base_url
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .unwrap_or("https://api.openai.com/v1");
+    let parsed =
+        url::Url::parse(base_url).map_err(|error| IronProxyConfigError::InvalidOpenAiBaseUrl {
+            value: base_url.to_owned(),
+            reason: error.to_string(),
+        })?;
+    if !matches!(parsed.scheme(), "http" | "https") {
+        return Err(IronProxyConfigError::InvalidOpenAiBaseUrl {
+            value: base_url.to_owned(),
+            reason: "scheme must be http or https".to_owned(),
+        });
+    }
+    let host = parsed
+        .host_str()
+        .ok_or_else(|| IronProxyConfigError::InvalidOpenAiBaseUrl {
+            value: base_url.to_owned(),
+            reason: "URL must include a host".to_owned(),
+        })?;
+
+    let mut fragment = load_fragment_str(CODEX_API_KEY_FRAGMENT)?;
+    fragment.transforms[0].config.secrets[0].rules[0]["host"] =
+        serde_yaml::Value::String(host.to_owned());
+    Ok(fragment)
+}
+
 /// The deployment's Bedrock region. iron-proxy re-signs Bedrock requests for
 /// this region only, and codex's `amazon-bedrock` provider talks to the
 /// region-specific `bedrock-mantle.<region>.api.aws` endpoint, so both the
@@ -167,7 +202,7 @@ transforms:
           replace:
             proxy_value: OPENAI_API_KEY
             match_headers: ["Authorization"]
-          rules: [{ host: api.openai.com }]
+          rules: [{ host: OPENAI_API_HOST }]
 "#;
 
 const OPENROUTER_API_KEY_FRAGMENT: &str = r#"
@@ -362,3 +397,25 @@ mod bedrock_tests {
         )));
     }
 }
+
+#[cfg(test)]
+mod openai_tests {
+    use super::*;
+
+    #[test]
+    fn codex_api_key_fragment_derives_host_from_configured_base_url() {
+        let fragment =
+            codex_api_key_fragment_for_base_url(Some(" https://us.api.openai.com/v1/ ")).unwrap();
+        assert_eq!(
+            fragment.transforms[0].config.secrets[0].rules[0]["host"].as_str(),
+            Some("us.api.openai.com")
+        );
+    }
+
+    #[test]
+    fn codex_api_key_fragment_rejects_invalid_base_url() {
+        let error =
+            codex_api_key_fragment_for_base_url(Some("api.example.com\n- injected")).unwrap_err();
+        assert!(error.to_string().contains("invalid OPENAI_BASE_URL"));
+    }
+}
diff --git a/services/api-rs/crates/centaur-session-runtime/src/title_generator.rs b/services/api-rs/crates/centaur-session-runtime/src/title_generator.rs
index f8c80c16e..d10767d36 100644
--- a/services/api-rs/crates/centaur-session-runtime/src/title_generator.rs
+++ b/services/api-rs/crates/centaur-session-runtime/src/title_generator.rs
@@ -11,6 +11,7 @@ const SESSION_TITLE_REQUEST_TIMEOUT: Duration = Duration::from_secs(4);
 #[derive(Clone)]
 pub(crate) struct OpenAiSessionTitleGenerator {
     api_key: Arc<str>,
+    responses_url: Arc<str>,
     client: reqwest::Client,
 }
 
@@ -21,12 +22,14 @@ impl OpenAiSessionTitleGenerator {
         if api_key.is_empty() || api_key == "OPENAI_API_KEY" {
             return None;
         }
+        let responses_url = format!("{}/responses", openai_base_url());
         let client = reqwest::Client::builder()
             .timeout(SESSION_TITLE_REQUEST_TIMEOUT)
             .build()
             .ok()?;
         Some(Self {
             api_key: Arc::from(api_key.to_owned()),
+            responses_url: Arc::from(responses_url),
             client,
         })
     }
@@ -43,7 +46,7 @@ impl OpenAiSessionTitleGenerator {
         });
         let response = self
             .client
-            .post("https://api.openai.com/v1/responses")
+            .post(self.responses_url.as_ref())
             .bearer_auth(self.api_key.as_ref())
             .json(&body)
             .send()
@@ -57,6 +60,14 @@ impl OpenAiSessionTitleGenerator {
     }
 }
 
+pub fn openai_base_url() -> String {
+    env::var("OPENAI_BASE_URL")
+        .ok()
+        .map(|value| value.trim().trim_end_matches('/').to_owned())
+        .filter(|value| !value.is_empty())
+        .unwrap_or_else(|| "https://api.openai.com/v1".to_owned())
+}
+
 pub(crate) fn session_title_source_from_parts(parts: &[Value]) -> Option<String> {
     let mut text_blocks = Vec::new();
     let mut slack_thread_source = None;

From 31620b52166c18cf843cac21d1d419eaed61c9b1 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Tue, 18 Aug 2026 21:24:48 +0000
Subject: [PATCH 07/36] chore(deps): bump the api-rs-dependencies group across
 1 directory with 6 updates (#1424)

Bumps the api-rs-dependencies group with 6 updates in the /services/api-rs directory:

| Package | From | To |
| --- | --- | --- |
| [async-trait](https://github.com/dtolnay/async-trait) | `0.1.91` | `0.1.92` |
| [aws-smithy-types](https://github.com/smithy-lang/smithy-rs) | `1.6.1` | `1.6.2` |
| [eyre](https://github.com/eyre-rs/eyre) | `0.6.12` | `0.6.14` |
| [thiserror](https://github.com/dtolnay/thiserror) | `2.0.19` | `2.0.20` |
| [uuid](https://github.com/uuid-rs/uuid) | `1.24.0` | `1.24.1` |
| [futures](https://github.com/rust-lang/futures-rs) | `0.3.33` | `0.3.34` |



Updates `async-trait` from 0.1.91 to 0.1.92
- [Release notes](https://github.com/dtolnay/async-trait/releases)
- [Commits](https://github.com/dtolnay/async-trait/compare/0.1.91...0.1.92)

Updates `aws-smithy-types` from 1.6.1 to 1.6.2
- [Release notes](https://github.com/smithy-lang/smithy-rs/releases)
- [Changelog](https://github.com/smithy-lang/smithy-rs/blob/main/CHANGELOG.md)
- [Commits](https://github.com/smithy-lang/smithy-rs/commits)

Updates `eyre` from 0.6.12 to 0.6.14
- [Commits](https://github.com/eyre-rs/eyre/compare/eyre-v0.6.12...v0.6.14)

Updates `thiserror` from 2.0.19 to 2.0.20
- [Release notes](https://github.com/dtolnay/thiserror/releases)
- [Commits](https://github.com/dtolnay/thiserror/compare/2.0.19...2.0.20)

Updates `uuid` from 1.24.0 to 1.24.1
- [Release notes](https://github.com/uuid-rs/uuid/releases)
- [Commits](https://github.com/uuid-rs/uuid/compare/v1.24.0...v1.24.1)

Updates `futures` from 0.3.33 to 0.3.34
- [Release notes](https://github.com/rust-lang/futures-rs/releases)
- [Changelog](https://github.com/rust-lang/futures-rs/blob/main/CHANGELOG.md)
- [Commits](https://github.com/rust-lang/futures-rs/compare/0.3.33...0.3.34)

---
updated-dependencies:
- dependency-name: async-trait
  dependency-version: 0.1.92
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: api-rs-dependencies
- dependency-name: aws-smithy-types
  dependency-version: 1.6.2
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: api-rs-dependencies
- dependency-name: eyre
  dependency-version: 0.6.14
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: api-rs-dependencies
- dependency-name: thiserror
  dependency-version: 2.0.20
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: api-rs-dependencies
- dependency-name: uuid
  dependency-version: 1.24.1
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: api-rs-dependencies
- dependency-name: futures
  dependency-version: 0.3.34
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: api-rs-dependencies
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 services/api-rs/Cargo.lock | 144 ++++++++++++++++++-------------------
 1 file changed, 68 insertions(+), 76 deletions(-)

diff --git a/services/api-rs/Cargo.lock b/services/api-rs/Cargo.lock
index 27dab10bc..8678d3087 100644
--- a/services/api-rs/Cargo.lock
+++ b/services/api-rs/Cargo.lock
@@ -11,7 +11,7 @@ dependencies = [
  "serde",
  "serde_json",
  "sqlx",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "tokio",
 ]
 
@@ -144,9 +144,9 @@ checksum = "7d902e3d592a523def97af8f317b08ce16b7ab854c1985a0c671e6f15cebc236"
 
 [[package]]
 name = "async-trait"
-version = "0.1.91"
+version = "0.1.92"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ae36dc4177970ef04fde5178d3e2429882def40e57a451f919c098f72baa6cec"
+checksum = "82f6aeea286b8eb4dd3431a1be1b59d290ace00f5bfd8e2a159bc2a05e2c1667"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -609,9 +609,9 @@ dependencies = [
 
 [[package]]
 name = "aws-smithy-types"
-version = "1.6.1"
+version = "1.6.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d6dc683efb34b9e755675b37fedbe0103141e5b6df7bdc9eb6967756a8c167d8"
+checksum = "fce83ce9abbb198d25bc7131e468d0f9fe1257125e58c39f3f9fc9f5098c9647"
 dependencies = [
  "base64-simd",
  "bytes",
@@ -905,7 +905,7 @@ dependencies = [
  "sha2 0.11.0",
  "sqlx",
  "subtle",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "time",
  "tokio",
  "toml",
@@ -926,7 +926,7 @@ dependencies = [
  "serde",
  "serde_json",
  "serde_yaml",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "tokio",
  "urlencoding",
 ]
@@ -938,7 +938,7 @@ dependencies = [
  "serde",
  "serde_yaml",
  "strum",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "url",
 ]
 
@@ -982,7 +982,7 @@ version = "0.1.0"
 dependencies = [
  "async-trait",
  "serde",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "tokio",
 ]
 
@@ -1021,7 +1021,7 @@ dependencies = [
  "centaur-session-sqlx",
  "centaur-telemetry",
  "sqlx",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "tokio",
  "tracing",
 ]
@@ -1049,7 +1049,7 @@ dependencies = [
  "serde",
  "serde_json",
  "strum",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "time",
 ]
 
@@ -1072,7 +1072,7 @@ dependencies = [
  "serde_json",
  "sha2 0.11.0",
  "sqlx",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "time",
  "tokio",
  "tokio-util",
@@ -1088,7 +1088,7 @@ dependencies = [
  "serde",
  "serde_json",
  "sqlx",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "time",
  "tokio",
  "uuid",
@@ -1106,7 +1106,7 @@ dependencies = [
  "opentelemetry_sdk",
  "prost",
  "serde_json",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "tokio",
  "tracing",
  "tracing-opentelemetry",
@@ -1132,7 +1132,7 @@ dependencies = [
  "serde",
  "serde_json",
  "sqlx",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "time",
  "tokio",
  "tracing",
@@ -1559,7 +1559,7 @@ version = "1.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "10d60334b3b2e7c9d91ef8150abfb6fa4c1c39ebbcf4a81c2e346aad939fee3e"
 dependencies = [
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
 ]
 
 [[package]]
@@ -1746,7 +1746,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
 dependencies = [
  "libc",
- "windows-sys 0.59.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -1804,10 +1804,11 @@ dependencies = [
 
 [[package]]
 name = "eyre"
-version = "0.6.12"
+version = "0.6.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7cd915d99f24784cdc19fd37ef22b97e3ff0ae756c7e492e9fbfe897d61e2aec"
+checksum = "c08309dbcc659c5549a24ddb9b27027640641b282ef5768267c7e675558986a3"
 dependencies = [
+ "autocfg",
  "indenter",
  "once_cell",
 ]
@@ -1919,9 +1920,9 @@ checksum = "42703706b716c37f96a77aea830392ad231f44c9e9a67872fa5548707e11b11c"
 
 [[package]]
 name = "futures"
-version = "0.3.33"
+version = "0.3.34"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a88cf1f829d945f548cf8fec32c61b1f202b6d93b45848602fc02af4b12ad218"
+checksum = "9a31d2a3fbaaeb2af2368bbdd904aa8e812d3c04a1ee10d3171f52d556e5d0a3"
 dependencies = [
  "futures-channel",
  "futures-core",
@@ -1934,9 +1935,9 @@ dependencies = [
 
 [[package]]
 name = "futures-channel"
-version = "0.3.33"
+version = "0.3.34"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "262590f4fe6afeb0bc83be1daa64e52657fe185690a958af7f3ad0e92085c5ae"
+checksum = "b1f9e3d69d39e4862ffed03ed071a76f9a13ba1d9109d355b0f0aa6b15e393c4"
 dependencies = [
  "futures-core",
  "futures-sink",
@@ -1944,15 +1945,15 @@ dependencies = [
 
 [[package]]
 name = "futures-core"
-version = "0.3.33"
+version = "0.3.34"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2cd50c473c80f6d7c3670a752354b8e569b1a7cbfdc0419ec88e5edad85e0dc7"
+checksum = "92d699e522242e69e3003b94ecc1f960f3a5e015aa7c5d7486e65ad01dd94f5e"
 
 [[package]]
 name = "futures-executor"
-version = "0.3.33"
+version = "0.3.34"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6754879cc9f2c66f88c6e5c35344bb0bdb0708b0352b1201815667c7eabc7458"
+checksum = "031b47cf1a3c6cc8bc2fc76cd437f521619387907d469316e7c0bc278f1f5432"
 dependencies = [
  "futures-core",
  "futures-task",
@@ -1972,38 +1973,38 @@ dependencies = [
 
 [[package]]
 name = "futures-io"
-version = "0.3.33"
+version = "0.3.34"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4577ecaa3c4f96589d473f679a71b596316f6641bc350038b962a5daf0085d7a"
+checksum = "53c0fa8157de1303bfffdaa1cc2a673bfffb60102f76b0ef4441659124373fed"
 
 [[package]]
 name = "futures-macro"
-version = "0.3.33"
+version = "0.3.34"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2d6d3cde68c518367be28956066ddfef33813991b77a55005a69dae04bf3b10b"
+checksum = "9fb9654ba8355388abeb8dcb4fc62f511300867002afc858860463bdd9fe0c44"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.117",
+ "syn 3.0.3",
 ]
 
 [[package]]
 name = "futures-sink"
-version = "0.3.33"
+version = "0.3.34"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e34418ac499d6305c2fb5ad0ed2f6ac998c5f8ca209b4510f7f94242c647e307"
+checksum = "1944426bf7d03f1d14f708785e4b33efd750b36d48a157b836b3efc15ede8e1d"
 
 [[package]]
 name = "futures-task"
-version = "0.3.33"
+version = "0.3.34"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b231ed28831efb4a61a08580c4bc233ec56bc009f4cd8f52da2c3cb97df0c109"
+checksum = "cd417de3d1d015fc3bfd2b1ea46dfc7bab72ef86f1cc7cc9c78e728b34a6d1fd"
 
 [[package]]
 name = "futures-util"
-version = "0.3.33"
+version = "0.3.34"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a77a90a256fce34da66415271e30f94ee91c57b04b8a2c042d9cf3220179deaa"
+checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc"
 dependencies = [
  "futures-channel",
  "futures-core",
@@ -2704,7 +2705,7 @@ dependencies = [
  "jni-sys",
  "log",
  "simd_cesu8",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "walkdir",
  "windows-link",
 ]
@@ -2772,7 +2773,7 @@ dependencies = [
  "pest_derive",
  "regex",
  "serde_json",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
 ]
 
 [[package]]
@@ -2811,7 +2812,7 @@ checksum = "bde5057d6143cc94e861d90f591b9303d6716c6b9602309150bd068853c10899"
 dependencies = [
  "hashbrown 0.16.1",
  "portable-atomic",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
 ]
 
 [[package]]
@@ -2854,7 +2855,7 @@ dependencies = [
  "serde",
  "serde-saphyr",
  "serde_json",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "tokio",
  "tokio-tungstenite",
  "tokio-util",
@@ -2878,7 +2879,7 @@ dependencies = [
  "serde",
  "serde-value",
  "serde_json",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
 ]
 
 [[package]]
@@ -3128,7 +3129,7 @@ dependencies = [
  "metrics",
  "metrics-util",
  "quanta",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
 ]
 
 [[package]]
@@ -3207,7 +3208,7 @@ version = "0.50.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7957b9740744892f114936ab4a57b3f487491bbeafaf8083688b16841a4240e5"
 dependencies = [
- "windows-sys 0.59.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -3310,7 +3311,7 @@ dependencies = [
  "futures-sink",
  "js-sys",
  "pin-project-lite",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "tracing",
 ]
 
@@ -3340,7 +3341,7 @@ dependencies = [
  "opentelemetry_sdk",
  "prost",
  "reqwest",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
 ]
 
 [[package]]
@@ -3367,7 +3368,7 @@ dependencies = [
  "percent-encoding",
  "portable-atomic",
  "rand 0.9.4",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
 ]
 
 [[package]]
@@ -3761,7 +3762,7 @@ dependencies = [
  "rustc-hash",
  "rustls 0.23.43",
  "socket2 0.6.4",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "tokio",
  "tracing",
  "web-time",
@@ -3783,7 +3784,7 @@ dependencies = [
  "rustls 0.23.43",
  "rustls-pki-types",
  "slab",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "tinyvec",
  "tracing",
  "web-time",
@@ -3800,7 +3801,7 @@ dependencies = [
  "once_cell",
  "socket2 0.6.4",
  "tracing",
- "windows-sys 0.59.0",
+ "windows-sys 0.52.0",
 ]
 
 [[package]]
@@ -3933,7 +3934,7 @@ dependencies = [
  "palette",
  "serde",
  "strum",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "unicode-segmentation",
  "unicode-truncate",
  "unicode-width",
@@ -4195,7 +4196,7 @@ dependencies = [
  "errno",
  "libc",
  "linux-raw-sys",
- "windows-sys 0.59.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -4266,7 +4267,7 @@ dependencies = [
  "security-framework",
  "security-framework-sys",
  "webpki-root-certs",
- "windows-sys 0.59.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -4790,7 +4791,7 @@ dependencies = [
  "serde_json",
  "sha2 0.10.9",
  "smallvec",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "time",
  "tokio",
  "tokio-stream",
@@ -4875,7 +4876,7 @@ dependencies = [
  "smallvec",
  "sqlx-core",
  "stringprep",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "time",
  "tracing",
  "whoami",
@@ -4914,7 +4915,7 @@ dependencies = [
  "smallvec",
  "sqlx-core",
  "stringprep",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "time",
  "tracing",
  "whoami",
@@ -4940,7 +4941,7 @@ dependencies = [
  "serde",
  "serde_urlencoded",
  "sqlx-core",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "time",
  "tracing",
  "url",
@@ -5175,11 +5176,11 @@ dependencies = [
 
 [[package]]
 name = "thiserror"
-version = "2.0.19"
+version = "2.0.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "09a43598840e33d5b0331f38c5e30d13bb11c11210a4b58f0d9b18a5a5eefcd9"
+checksum = "ec86235f5fcc2a73650310756d2ac5b138a5780bbbdfae3eeccec992c435ba4f"
 dependencies = [
- "thiserror-impl 2.0.19",
+ "thiserror-impl 2.0.20",
 ]
 
 [[package]]
@@ -5195,9 +5196,9 @@ dependencies = [
 
 [[package]]
 name = "thiserror-impl"
-version = "2.0.19"
+version = "2.0.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "43cbfe0cf76104d42a574802844187e84a305e531ed54455f11fbde0f10541cd"
+checksum = "bc04cd3e1236dd4a98afca4569f2deb3f120e5422a4023be2cb683f8486292af"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -5570,7 +5571,7 @@ dependencies = [
  "log",
  "rand 0.9.4",
  "sha1 0.10.6",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
 ]
 
 [[package]]
@@ -5691,9 +5692,9 @@ checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
 
 [[package]]
 name = "uuid"
-version = "1.24.0"
+version = "1.24.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bf3923a6f5c4c6382e0b653c4117f48d631ea17f38ed86e2a828e6f7412f5239"
+checksum = "2cefc03fd367c0c6d4305de1b312cf00248c4114f4a0418ce6a6af769e3b0bd9"
 dependencies = [
  "atomic",
  "getrandom 0.4.2",
@@ -6038,7 +6039,7 @@ version = "0.1.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22"
 dependencies = [
- "windows-sys 0.48.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -6124,15 +6125,6 @@ dependencies = [
  "windows-targets 0.52.6",
 ]
 
-[[package]]
-name = "windows-sys"
-version = "0.59.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b"
-dependencies = [
- "windows-targets 0.52.6",
-]
-
 [[package]]
 name = "windows-sys"
 version = "0.61.2"

From c05693fd60f983116d4ef5748f99ccf40ff7f77a Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Tue, 18 Aug 2026 21:25:06 +0000
Subject: [PATCH 08/36] chore(deps): bump the github-actions group with 3
 updates (#1405)

Bumps the github-actions group with 3 updates: [dtolnay/rust-toolchain](https://github.com/dtolnay/rust-toolchain), [astral-sh/setup-uv](https://github.com/astral-sh/setup-uv) and [actions/github-script](https://github.com/actions/github-script).


Updates `dtolnay/rust-toolchain` from e97e2d8cc328f1b50210efc529dca0028893a2d9 to 6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772
- [Commits](https://github.com/dtolnay/rust-toolchain/compare/e97e2d8cc328f1b50210efc529dca0028893a2d9...6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772)

Updates `astral-sh/setup-uv` from 9.0.0 to 10.0.1
- [Commits](https://github.com/astral-sh/setup-uv/compare/c771a70e6277c0a99b617c7a806ffedaca235ff9...20cfd1bf945f4377ade1205e4dbc17946fc9a30d)

Updates `actions/github-script` from d746ffe35508b1917358783b479e04febd2b8f71 to 3a2844b7e9c422d3c10d287c895573f7108da1b3
- [Commits](https://github.com/actions/github-script/compare/d746ffe35508b1917358783b479e04febd2b8f71...3a2844b7e9c422d3c10d287c895573f7108da1b3)

---
updated-dependencies:
- dependency-name: dtolnay/rust-toolchain
  dependency-version: 6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772
  dependency-type: direct:production
  dependency-group: github-actions
- dependency-name: astral-sh/setup-uv
  dependency-version: 10.0.1
  dependency-type: direct:production
  update-type: version-update:semver-major
  dependency-group: github-actions
- dependency-name: actions/github-script
  dependency-version: 3a2844b7e9c422d3c10d287c895573f7108da1b3
  dependency-type: direct:production
  dependency-group: github-actions
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/ci.yml                    | 8 ++++----
 .github/workflows/close-stale-draft-prs.yml | 2 +-
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 25ae53482..85e3c2693 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -140,7 +140,7 @@ jobs:
         with:
           persist-credentials: false
 
-      - uses: dtolnay/rust-toolchain@e97e2d8cc328f1b50210efc529dca0028893a2d9 # v1
+      - uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # v1
         with:
           toolchain: stable
           components: rustfmt, clippy
@@ -183,7 +183,7 @@ jobs:
           working-directory: services/console
           bundler-cache: true
 
-      - uses: dtolnay/rust-toolchain@e97e2d8cc328f1b50210efc529dca0028893a2d9 # v1
+      - uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # v1
         with:
           toolchain: stable
           components: rustfmt, clippy
@@ -322,7 +322,7 @@ jobs:
         with:
           python-version: "3.11"
 
-      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           enable-cache: true
           prune-cache: true
@@ -354,7 +354,7 @@ jobs:
         with:
           python-version: "3.11"
 
-      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           enable-cache: true
           prune-cache: true
diff --git a/.github/workflows/close-stale-draft-prs.yml b/.github/workflows/close-stale-draft-prs.yml
index 212175e3b..1e390c81e 100644
--- a/.github/workflows/close-stale-draft-prs.yml
+++ b/.github/workflows/close-stale-draft-prs.yml
@@ -15,7 +15,7 @@ jobs:
     timeout-minutes: 5
     steps:
       - name: Close inactive draft pull requests
-        uses: actions/github-script@d746ffe35508b1917358783b479e04febd2b8f71 # v9.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
             const inactivityCutoff = Date.now() - 14 * 24 * 60 * 60 * 1000;

From 0a3e82ca541df57b68692251f2f4d69e5921da26 Mon Sep 17 00:00:00 2001
From: Matthew Slipper <me@matthewslipper.com>
Date: Tue, 18 Aug 2026 21:26:07 +0000
Subject: [PATCH 09/36] feat: add githubkit workflow dependency (#1426)

---
 services/sandbox/Dockerfile             | 1 +
 services/workflow-python/pyproject.toml | 1 +
 2 files changed, 2 insertions(+)

diff --git a/services/sandbox/Dockerfile b/services/sandbox/Dockerfile
index e2f114643..56a509178 100644
--- a/services/sandbox/Dockerfile
+++ b/services/sandbox/Dockerfile
@@ -57,6 +57,7 @@ RUN --mount=type=cache,target=/root/.cache/pip,sharing=locked \
     "openai>=2.53.0" \
     opentelemetry-proto==1.42.1 \
     "psycopg[binary]>=3.2.0" \
+    "githubkit>=0.16.1" \
     pysocks>=1.7.1 \
     rich>=13.0.0 \
     slack-sdk==3.39.0 \
diff --git a/services/workflow-python/pyproject.toml b/services/workflow-python/pyproject.toml
index 4f2eb2dfa..57685682a 100644
--- a/services/workflow-python/pyproject.toml
+++ b/services/workflow-python/pyproject.toml
@@ -14,6 +14,7 @@ dependencies = [
     "httpx>=0.28.0",
     "openai>=2.53.0",
     "psycopg[binary]>=3.2.0",
+    "githubkit>=0.16.1",
     "pysocks>=1.7.1",
     "rich>=13.0.0",
     "slack-sdk>=3.39.0",

From 300b760c27fa7b08ed79275968c24d29d8015ba6 Mon Sep 17 00:00:00 2001
From: Derek Cofausper <256792747+decofe@users.noreply.github.com>
Date: Tue, 18 Aug 2026 22:11:50 +0000
Subject: [PATCH 10/36] fix(slack): stop injecting ETL token in CLI (#628)

Co-authored-by: Matthew Slipper <me@matthewslipper.com>
---
 tools/productivity/slack/pyproject.toml | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/tools/productivity/slack/pyproject.toml b/tools/productivity/slack/pyproject.toml
index 92c1c4ee3..c552c5960 100644
--- a/tools/productivity/slack/pyproject.toml
+++ b/tools/productivity/slack/pyproject.toml
@@ -28,9 +28,8 @@ packages = ["."]
 [tool.centaur]
 module = "client.py"
 secrets = [
-    {type = "http", name = "SLACK_BOT_TOKEN", match_headers = ["Authorization"], hosts = ["slack.com"]},
+    {type = "http", name = "SLACK_BOT_TOKEN", match_headers = ["Authorization"], hosts = ["slack.com", "files.slack.com"]},
 ]
 optional_secrets = [
-    {type = "http", name = "SLACK_SEARCH_TOKEN", match_headers = ["Authorization"], hosts = ["slack.com"]},
-    {type = "http", name = "SLACK_ETL_TOKEN", match_headers = ["Authorization"], hosts = ["slack.com", "files.slack.com"]},
+    {type = "http", name = "SLACK_SEARCH_TOKEN", mode = "inject", inject_header = "Authorization", inject_formatter = "Bearer {{ .Value }}", hosts = ["files.slack.com"]}
 ]

From e24bacf0a0b3456a5b8256e4a5c85c27ab77acc1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jos=C3=A9=20Ribeiro?= <me@joseribeiro.dev>
Date: Wed, 19 Aug 2026 03:54:38 +0000
Subject: [PATCH 11/36] fix(slack): send DMs without im:write scope (#1145)

fix: send Slack DMs without im:write scope
---
 tools/productivity/slack/client.py            | 10 +++++++---
 tools/productivity/slack/tests/test_client.py | 15 ++++++++-------
 2 files changed, 15 insertions(+), 10 deletions(-)

diff --git a/tools/productivity/slack/client.py b/tools/productivity/slack/client.py
index 12f5e0f50..2dc1868bc 100644
--- a/tools/productivity/slack/client.py
+++ b/tools/productivity/slack/client.py
@@ -586,7 +586,10 @@ def _open_dm_channel(self, user_id: str) -> str:
     def _resolve_message_destination(self, channel: str) -> str:
         """Resolve a send_message destination from channel, channel ID, or user ID."""
         if self._looks_like_user_id(channel):
-            return self._open_dm_channel(channel)
+            # chat.postMessage accepts a user ID directly and opens the bot's
+            # one-on-one DM when needed. Calling conversations.open first adds
+            # an unnecessary im:write scope requirement.
+            return self._clean_user_ref(channel).upper()
         return self._resolve_channel(channel)
 
     def _resolve_mentions(self, text: str, user_cache: dict[str, str]) -> str:
@@ -1848,10 +1851,11 @@ def send_message(
             if unfurl_media is not None:
                 kwargs["unfurl_media"] = unfurl_media
             response = self._client.chat_postMessage(**kwargs)
+            response_channel = str(response.get("channel") or channel_id)
             return {
-                "channel": channel_id,
+                "channel": response_channel,
                 "ts": response.get("ts", ""),
-                "permalink": f"https://slack.com/archives/{channel_id}/p{response.get('ts', '').replace('.', '')}",
+                "permalink": f"https://slack.com/archives/{response_channel}/p{response.get('ts', '').replace('.', '')}",
             }
         except SlackApiError as e:
             raise RuntimeError(f"Slack API error: {e.response['error']}") from e
diff --git a/tools/productivity/slack/tests/test_client.py b/tools/productivity/slack/tests/test_client.py
index 3b94791e2..f12a54ed6 100644
--- a/tools/productivity/slack/tests/test_client.py
+++ b/tools/productivity/slack/tests/test_client.py
@@ -49,7 +49,8 @@ def __init__(self) -> None:
 
     def chat_postMessage(self, **kwargs):
         self.last_kwargs = kwargs
-        return {"ts": "123.456"}
+        channel = "D123" if kwargs["channel"].startswith("U") else kwargs["channel"]
+        return {"channel": channel, "ts": "123.456"}
 
     def conversations_history(self, **kwargs):
         self.history_calls.append(kwargs)
@@ -180,27 +181,27 @@ def test_send_message_normalizes_escaped_line_breaks() -> None:
     assert fake_web_client.last_kwargs["text"] == "*Title*\n- one\n- two"
 
 
-def test_send_message_opens_dm_for_user_id_destination() -> None:
+def test_send_message_posts_directly_to_user_id_without_im_write_scope() -> None:
     client, fake_web_client = _make_client()
 
     result = client.send_message("<@U123ABC>", "hello", no_attribution=True)
 
-    assert fake_web_client.open_calls == [{"users": "U123ABC"}]
+    assert fake_web_client.open_calls == []
     assert fake_web_client.last_kwargs is not None
-    assert fake_web_client.last_kwargs["channel"] == "D123"
+    assert fake_web_client.last_kwargs["channel"] == "U123ABC"
     assert fake_web_client.last_kwargs["text"] == "hello"
     assert result["channel"] == "D123"
     assert result["permalink"] == "https://slack.com/archives/D123/p123456"
 
 
-def test_send_dm_opens_dm_and_posts_message() -> None:
+def test_send_dm_posts_directly_to_user_id() -> None:
     client, fake_web_client = _make_client()
 
     client.send_dm("U234ABC", "hello", no_attribution=True, unfurl_links=False)
 
-    assert fake_web_client.open_calls == [{"users": "U234ABC"}]
+    assert fake_web_client.open_calls == []
     assert fake_web_client.last_kwargs is not None
-    assert fake_web_client.last_kwargs["channel"] == "D123"
+    assert fake_web_client.last_kwargs["channel"] == "U234ABC"
     assert fake_web_client.last_kwargs["unfurl_links"] is False
 
 

From 46363a0d2fd5ac31c07776d146f2f05d5161b448 Mon Sep 17 00:00:00 2001
From: Osraka <98612432+Osraka@users.noreply.github.com>
Date: Wed, 19 Aug 2026 03:59:14 +0000
Subject: [PATCH 12/36] fix(mcp): include tool-host correlation context in
 errors (#992)

Co-authored-by: Matthew Slipper <me@matthewslipper.com>
---
 .../crates/centaur-api-server/src/mcp.rs      | 78 +++++++++++++++++--
 .../crates/centaur-session-runtime/src/lib.rs | 39 ++++++++--
 2 files changed, 105 insertions(+), 12 deletions(-)

diff --git a/services/api-rs/crates/centaur-api-server/src/mcp.rs b/services/api-rs/crates/centaur-api-server/src/mcp.rs
index aaa92d51e..691c8947c 100644
--- a/services/api-rs/crates/centaur-api-server/src/mcp.rs
+++ b/services/api-rs/crates/centaur-api-server/src/mcp.rs
@@ -13,7 +13,7 @@ use axum::{
     response::{IntoResponse, Response},
 };
 use base64::{Engine as _, engine::general_purpose};
-use centaur_session_runtime::{SessionRuntime, ToolHostCallInput};
+use centaur_session_runtime::{SessionRuntime, ToolHostCallInput, ToolHostCallOutput};
 use hmac::{Hmac, KeyInit, Mac};
 use serde::Deserialize;
 use serde_json::{Value, json};
@@ -433,8 +433,10 @@ async fn run_tool_host_centaur_tool(
     if output.timed_out {
         return Ok(mcp_text_result(
             format!(
-                "centaur tool {}.{method} timed out in sandbox {}: {}",
-                tool.name, output.sandbox_id, output.stderr
+                "centaur tool {}.{method} timed out in {}: {}",
+                tool.name,
+                tool_host_error_context(&output),
+                output.stderr
             ),
             true,
         ));
@@ -448,8 +450,11 @@ async fn run_tool_host_centaur_tool(
         let detail = mcp_tool_failure_detail(raw);
         return Ok(mcp_text_result(
             format!(
-                "centaur tool {}.{method} failed in sandbox {} with status {:?}: {detail}\n\nCall the {} tool with method \"help\" to list available methods and their signatures.",
-                tool.name, output.sandbox_id, output.exit_status, tool.name
+                "centaur tool {}.{method} failed in {} with status {:?}: {detail}\n\nCall the {} tool with method \"help\" to list available methods and their signatures.",
+                tool.name,
+                tool_host_error_context(&output),
+                output.exit_status,
+                tool.name
             ),
             true,
         ));
@@ -465,14 +470,37 @@ async fn run_tool_host_centaur_tool(
         )),
         Err(error) => Ok(mcp_text_result(
             format!(
-                "centaur tool {}.{method} returned non-json output in sandbox {}: {error}: {stdout}",
-                tool.name, output.sandbox_id
+                "centaur tool {}.{method} returned non-json output in {}: {error}: {stdout}",
+                tool.name,
+                tool_host_error_context(&output)
             ),
             true,
         )),
     }
 }
 
+fn tool_host_error_context(output: &ToolHostCallOutput) -> String {
+    let mut parts = Vec::new();
+    let sandbox_id = output.sandbox_id.trim();
+    parts.push(if sandbox_id.is_empty() {
+        "sandbox unknown".to_owned()
+    } else {
+        format!("sandbox {sandbox_id}")
+    });
+
+    let execution_id = output.execution_id.trim();
+    if !execution_id.is_empty() {
+        parts.push(format!("execution {execution_id}"));
+    }
+
+    let request_id = output.request_id.trim();
+    if !request_id.is_empty() {
+        parts.push(format!("request {request_id}"));
+    }
+
+    parts.join(", ")
+}
+
 /// Reduce a Python traceback to its final exception message: agents act on
 /// the error line, not on stack frames or build noise, so keep everything
 /// from the last traceback's exception message to the end.
@@ -994,6 +1022,42 @@ RuntimeError: X API error: 401 - {
         assert_eq!(mcp_tool_failure_detail(plain), plain);
     }
 
+    #[test]
+    fn mcp_tool_host_error_context_includes_correlation_ids() {
+        let output = ToolHostCallOutput {
+            request_id: "mcp-call-123".to_owned(),
+            execution_id: "exe-456".to_owned(),
+            sandbox_id: "sbx-789".to_owned(),
+            stdout: String::new(),
+            stderr: "boom".to_owned(),
+            exit_status: Some(1),
+            timed_out: false,
+        };
+
+        assert_eq!(
+            tool_host_error_context(&output),
+            "sandbox sbx-789, execution exe-456, request mcp-call-123"
+        );
+    }
+
+    #[test]
+    fn mcp_tool_host_error_context_handles_missing_sandbox_id() {
+        let output = ToolHostCallOutput {
+            request_id: "mcp-call-123".to_owned(),
+            execution_id: "exe-456".to_owned(),
+            sandbox_id: String::new(),
+            stdout: String::new(),
+            stderr: "boom".to_owned(),
+            exit_status: None,
+            timed_out: true,
+        };
+
+        assert_eq!(
+            tool_host_error_context(&output),
+            "sandbox unknown, execution exe-456, request mcp-call-123"
+        );
+    }
+
     #[tokio::test]
     async fn mcp_unknown_method_returns_available_methods_without_running_tool() {
         let temp = temp_dir("centaur-api-rs-mcp-unknown-method");
diff --git a/services/api-rs/crates/centaur-session-runtime/src/lib.rs b/services/api-rs/crates/centaur-session-runtime/src/lib.rs
index ad3fbf9d9..7a7f4f25d 100644
--- a/services/api-rs/crates/centaur-session-runtime/src/lib.rs
+++ b/services/api-rs/crates/centaur-session-runtime/src/lib.rs
@@ -383,6 +383,8 @@ pub struct ToolHostCallInput {
 
 #[derive(Debug)]
 pub struct ToolHostCallOutput {
+    pub request_id: String,
+    pub execution_id: String,
     pub sandbox_id: String,
     pub stdout: String,
     pub stderr: String,
@@ -1051,7 +1053,7 @@ impl SessionRuntime {
                     idempotency_key: Some(request_id.clone()),
                     metadata: Some(json!({
                         "mcp_tool_host_call": true,
-                        "request_id": request_id,
+                        "request_id": request_id.clone(),
                         "tool": tool_name,
                         "method": method,
                         "timeout_ms": duration_millis_u64(timeout),
@@ -1062,8 +1064,13 @@ impl SessionRuntime {
                 },
             )
             .await?;
-        self.wait_for_tool_host_call(thread_key, &execution.execution_id, response_timeout)
-            .await
+        self.wait_for_tool_host_call(
+            thread_key,
+            &execution.execution_id,
+            &request_id,
+            response_timeout,
+        )
+        .await
     }
 
     async fn create_or_get_tool_host_session(
@@ -1093,6 +1100,7 @@ impl SessionRuntime {
         &self,
         thread_key: &ThreadKey,
         execution_id: &str,
+        request_id: &str,
         response_timeout: Duration,
     ) -> Result<ToolHostCallOutput, SessionRuntimeError> {
         let events = self
@@ -1104,10 +1112,19 @@ impl SessionRuntime {
                 let event = event?;
                 match event.event_type.as_str() {
                     "session.execution_completed" => {
-                        return self.tool_host_completed_output(thread_key, &event).await;
+                        return self
+                            .tool_host_completed_output(
+                                thread_key,
+                                &event,
+                                execution_id,
+                                request_id,
+                            )
+                            .await;
                     }
                     "session.execution_failed" => {
-                        return self.tool_host_failed_output(thread_key, &event).await;
+                        return self
+                            .tool_host_failed_output(thread_key, &event, execution_id, request_id)
+                            .await;
                     }
                     _ => {}
                 }
@@ -1122,6 +1139,8 @@ impl SessionRuntime {
             // Best-effort sandbox id: a store error must not replace the
             // timeout result with an internal error.
             Err(_) => Ok(ToolHostCallOutput {
+                request_id: request_id.to_owned(),
+                execution_id: execution_id.to_owned(),
                 sandbox_id: self
                     .current_sandbox_id(thread_key)
                     .await
@@ -1141,10 +1160,14 @@ impl SessionRuntime {
         &self,
         thread_key: &ThreadKey,
         event: &SessionEvent,
+        execution_id: &str,
+        request_id: &str,
     ) -> Result<ToolHostCallOutput, SessionRuntimeError> {
         let sandbox_id = self.current_sandbox_id(thread_key).await?;
         let Some(result_text) = event.payload.get("result_text").and_then(Value::as_str) else {
             return Ok(ToolHostCallOutput {
+                request_id: request_id.to_owned(),
+                execution_id: execution_id.to_owned(),
                 sandbox_id,
                 stdout: String::new(),
                 stderr: String::new(),
@@ -1159,6 +1182,8 @@ impl SessionRuntime {
             ))
         })?;
         Ok(ToolHostCallOutput {
+            request_id: request_id.to_owned(),
+            execution_id: execution_id.to_owned(),
             sandbox_id,
             stdout: response.stdout,
             stderr: response.stderr,
@@ -1171,6 +1196,8 @@ impl SessionRuntime {
         &self,
         thread_key: &ThreadKey,
         event: &SessionEvent,
+        execution_id: &str,
+        request_id: &str,
     ) -> Result<ToolHostCallOutput, SessionRuntimeError> {
         let error = event
             .payload
@@ -1184,6 +1211,8 @@ impl SessionRuntime {
             .and_then(Value::as_str)
             .is_some_and(|reason| reason == "max_duration_exceeded");
         Ok(ToolHostCallOutput {
+            request_id: request_id.to_owned(),
+            execution_id: execution_id.to_owned(),
             sandbox_id: self.current_sandbox_id(thread_key).await?,
             stdout: String::new(),
             stderr: error,

From e084069b9b5ab81b1c2d3957d4c08209d73faa65 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jos=C3=A9=20Ribeiro?= <me@joseribeiro.dev>
Date: Wed, 19 Aug 2026 04:29:03 +0000
Subject: [PATCH 13/36] fix(chart): allow explicit Console service hosts
 (#1144)

fix: allow explicit Console service hosts

Co-authored-by: Matthew Slipper <me@matthewslipper.com>
---
 contrib/chart/Chart.yaml             | 2 +-
 contrib/chart/templates/console.yaml | 4 ++++
 contrib/chart/values.schema.json     | 5 +++++
 contrib/chart/values.yaml            | 4 ++++
 4 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/contrib/chart/Chart.yaml b/contrib/chart/Chart.yaml
index 073bd07ef..d4a0885e5 100644
--- a/contrib/chart/Chart.yaml
+++ b/contrib/chart/Chart.yaml
@@ -2,7 +2,7 @@ apiVersion: v2
 name: centaur
 description: Helm chart for the trusted Centaur control plane
 type: application
-version: 0.1.120
+version: 0.1.121
 appVersion: "0.1.0"
 dependencies:
   - name: connect
diff --git a/contrib/chart/templates/console.yaml b/contrib/chart/templates/console.yaml
index 1d7fe9847..6b4cbb4ca 100644
--- a/contrib/chart/templates/console.yaml
+++ b/contrib/chart/templates/console.yaml
@@ -186,6 +186,10 @@ spec:
             - name: CENTAUR_CONSOLE_PUBLIC_URL
               value: {{ $console.publicUrl | quote }}
 {{- end }}
+{{- with $console.allowedHosts }}
+            - name: CENTAUR_CONSOLE_ALLOWED_HOSTS
+              value: {{ join "," . | quote }}
+{{- end }}
 {{- with $console.sentryDsn }}
             - name: SENTRY_DSN
               value: {{ . | quote }}
diff --git a/contrib/chart/values.schema.json b/contrib/chart/values.schema.json
index 95a6c0878..4b66d6859 100644
--- a/contrib/chart/values.schema.json
+++ b/contrib/chart/values.schema.json
@@ -7,6 +7,11 @@
       "properties": {
         "replicaCount": { "type": "integer" },
         "publicUrl": { "type": "string" },
+        "allowedHosts": {
+          "type": "array",
+          "items": { "type": "string" },
+          "uniqueItems": true
+        },
         "sentryDsn": { "type": "string" },
         "railsEnv": { "type": "string" },
         "image": {
diff --git a/contrib/chart/values.yaml b/contrib/chart/values.yaml
index 0c97eb736..9e270efd1 100644
--- a/contrib/chart/values.yaml
+++ b/contrib/chart/values.yaml
@@ -107,6 +107,10 @@ console:
   # When set, the slackbotv2 deployment also links the first assistant message
   # in a Slack thread to the Console session view; leave empty to omit the link.
   publicUrl: ""
+  # Additional exact Host headers accepted by Rails Host Authorization. Use for
+  # service DNS names that differ from the chart's short in-cluster URL;
+  # publicUrl and the short service host are already included.
+  allowedHosts: []
   # Optional Sentry DSN for Console web requests and background jobs. Empty by
   # default, so the Sentry SDK remains disabled unless explicitly configured.
   sentryDsn: ""

From 80450d07b19d55b35cec3754abc2823954350641 Mon Sep 17 00:00:00 2001
From: akandic47 <57039429+akandic47@users.noreply.github.com>
Date: Wed, 19 Aug 2026 04:37:02 +0000
Subject: [PATCH 14/36] docs: drop dead secret keys; fix stale proxy-fallback
 comment (#998)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* docs: drop dead secret keys; fix stale proxy-fallback comment

SANDBOX_SIGNING_KEY, LOCAL_DEV_API_KEY, and IRON_BROKER_TOKEN have no
consumers left on main — they are python-era / standalone-token-broker
leftovers. Remove them from the secret tables and examples in the docs
(and the matching lines in the docs/public/md mirrors) and stop seeding
them in bootstrap-k8s-secrets.sh.

Also fix the IRON_CONTROL_URL comment in the api-rs template: there is
no static-proxy-config fallback; api-rs fails fast when iron-proxy is
configured without iron-control.

Closes #996

* docs: correct broker credential setup

---------

Co-authored-by: Matthew Slipper <me@matthewslipper.com>
---
 contrib/scripts/bootstrap-k8s-secrets.sh |  8 ---
 docs/pages/deploying-in-production.mdx   | 85 +++++++++++-------------
 docs/pages/extend/tools.mdx              | 23 ++++---
 docs/pages/reference/configuration.mdx   |  6 +-
 docs/pages/secrets/environment.mdx       |  1 -
 docs/pages/secrets/onepassword.mdx       |  1 -
 services/sandbox/entrypoint.sh           |  4 +-
 7 files changed, 52 insertions(+), 76 deletions(-)

diff --git a/contrib/scripts/bootstrap-k8s-secrets.sh b/contrib/scripts/bootstrap-k8s-secrets.sh
index b1cb61abe..510f4140e 100755
--- a/contrib/scripts/bootstrap-k8s-secrets.sh
+++ b/contrib/scripts/bootstrap-k8s-secrets.sh
@@ -198,12 +198,6 @@ if secret_exists centaur-infra-env; then
   if [[ -n "${OP_CONNECT_TOKEN:-}" ]]; then
     patch_data+=("\"OP_CONNECT_TOKEN\":\"$(printf '%s' "$OP_CONNECT_TOKEN" | base64 | tr -d '\n')\"")
   fi
-  # Top-up IRON_BROKER_TOKEN for clusters bootstrapped before iron-token-broker
-  # support landed. Only generated when absent so we don't rotate it out from
-  # under cached iron-proxy access tokens on every script run.
-  if ! secret_key_present IRON_BROKER_TOKEN; then
-    patch_data+=("\"IRON_BROKER_TOKEN\":\"$(rand_hex | base64 | tr -d '\n')\"")
-  fi
   # GITHUB_TOKEN for the repo-cache DaemonSet. Set whenever present so it can be
   # rotated; harmless when repoCache is disabled.
   if [[ -n "${GITHUB_TOKEN:-}" ]]; then
@@ -315,8 +309,6 @@ else
   secret_args=(
     -n "$NAMESPACE" create secret generic centaur-infra-env
     --from-literal=IRON_MANAGEMENT_API_KEY="$(rand_hex)"
-    --from-literal=IRON_BROKER_TOKEN="$(rand_hex)"
-    --from-literal=SANDBOX_SIGNING_KEY="$(rand_hex)"
     --from-literal=OP_SERVICE_ACCOUNT_TOKEN="$OP_SERVICE_ACCOUNT_TOKEN"
     --from-literal=OP_VAULT="$OP_VAULT"
     --from-literal=SLACK_BOT_TOKEN="$SLACK_BOT_TOKEN"
diff --git a/docs/pages/deploying-in-production.mdx b/docs/pages/deploying-in-production.mdx
index 319744bd5..3431a804e 100644
--- a/docs/pages/deploying-in-production.mdx
+++ b/docs/pages/deploying-in-production.mdx
@@ -62,7 +62,6 @@ Minimum keys:
 | `DATABASE_URL` | API | Postgres connection string. Make sure the password is URL-encoded. |
 | `POSTGRES_PASSWORD` | Bundled Postgres | Password used when the chart manages Postgres. |
 | `IRON_MANAGEMENT_API_KEY` | [iron-proxy](https://docs.iron.sh) management API | Generate with `openssl rand -hex 32`. |
-| `SANDBOX_SIGNING_KEY` | Sandbox API tokens | Generate with `openssl rand -hex 32`; keeps sandbox tokens valid across API restarts. |
 | `SLACK_BOT_TOKEN` | Slackbot/API | Bot User OAuth Token from the Slack app. |
 | `SLACK_SIGNING_SECRET` | Slackbot/API | Used to verify Slack webhook signatures. |
 | `SLACKBOT_API_KEY` | Slackbot to API | Dedicated static service token restricted to Slack session routes and workflow event emission. |
@@ -155,32 +154,26 @@ Codex supports two authentication modes, selected per deployment with the
 | Mode | Upstream | Secrets required |
 |------|----------|------------------|
 | `api_key` (default) | `api.openai.com` | `OPENAI_API_KEY` |
-| `access_token` | `chatgpt.com` | `OPENAI_CODEX_CLIENT_ID`, `OPENAI_CODEX_BLOB`, `OPENAI_CODEX_ACCOUNT_ID` |
+| `access_token` | `chatgpt.com` | Console broker credential `openai-codex`; `OPENAI_CODEX_ACCOUNT_ID` |
 
 `access_token` mode routes Codex through a ChatGPT account rather than a raw
-API key. [iron-token-broker](https://docs.iron.sh) holds the refresh token
-and mints short-lived access tokens, which iron-proxy injects on outbound
-requests so the sandbox never sees them.
-
-Store these three items in your secrets backend (1Password vault, Kubernetes
-Secret, etc.) when running in `access_token` mode:
-
-- `OPENAI_CODEX_CLIENT_ID`: the Codex CLI's OAuth client id. This is a
-  fixed, publicly known constant: `app_EMoamEEZ73f0CkXaXp7hrann`. It is
-  the same for every Codex install and never rotates, but the broker
-  still resolves it through your secrets backend, so store the literal
-  value as-is.
-- `OPENAI_CODEX_BLOB`: a JSON document `{"refresh_token": "..."}`. The
-  broker rotates this in place on every refresh, so the backing item must
-  be writable.
-- `OPENAI_CODEX_ACCOUNT_ID`: the ChatGPT account UUID the credential is
-  bound to. It is static, but iron-proxy injects it as the
-  `chatgpt-account-id` header so the backend can route to the right
-  workspace. Store it alongside the other two, not in code.
-
-To bootstrap, run `codex login` locally, then copy the refresh token and
-account id from `~/.codex/auth.json` into the matching secret items. Use
-the constant above for `OPENAI_CODEX_CLIENT_ID`.
+API key. The Console holds the refresh token and its background worker mints
+and refreshes short-lived access tokens. Proxy sync delivers the current token
+to iron-proxy, which injects it on outbound requests so the sandbox never sees
+it.
+
+Run `codex login` locally, then create a Console broker credential with:
+
+- Foreign ID: `openai-codex`.
+- Token endpoint: `https://auth.openai.com/oauth/token`.
+- Client ID: `app_EMoamEEZ73f0CkXaXp7hrann`.
+- Refresh token: the value from `~/.codex/auth.json`.
+
+The Console encrypts the refresh token at rest and updates it after every
+rotation. Store `OPENAI_CODEX_ACCOUNT_ID`, the ChatGPT account UUID from the
+same login file, in the configured secrets backend. iron-proxy injects it as
+the `chatgpt-account-id` header so the backend can route to the correct
+workspace.
 
 ### Claude Auth Modes
 
@@ -201,31 +194,27 @@ with the `CLAUDE_CODE_AUTH_MODE` env var on the sandbox (set it via
 | Mode | Upstream | Secrets required |
 |------|----------|------------------|
 | `api_key` (default) | `api.anthropic.com` | `ANTHROPIC_API_KEY` |
-| `access_token` | `api.anthropic.com` | `CLAUDE_CODE_CLIENT_ID`, `CLAUDE_CODE_BLOB` |
+| `access_token` | `api.anthropic.com` | Console broker credential `anthropic-claude` |
 
 `access_token` mode routes Claude Code through a Claude.ai Pro or Max
-subscription rather than a raw API key. [iron-token-broker](https://docs.iron.sh)
-holds the refresh token and mints short-lived access tokens, which iron-proxy
-injects on outbound requests so the sandbox never sees them. The entrypoint
-plants a dummy `~/.claude/.credentials.json` so the CLI emits OAuth-shaped
-requests; the broker overwrites the Bearer at request time.
-
-Store these two items in your secrets backend (1Password vault, Kubernetes
-Secret, etc.) when running in `access_token` mode:
-
-- `CLAUDE_CODE_CLIENT_ID`: the Claude Code CLI's OAuth client id. This
-  is a fixed, publicly known constant:
-  `9d1c250a-e61b-44d9-88ed-5944d1962f5e`. It is the same for every Claude
-  Code install and never rotates, but the broker still resolves it through
-  your secrets backend, so store the literal value as-is.
-- `CLAUDE_CODE_BLOB`: a JSON document `{"refresh_token": "..."}`. The
-  broker rotates this in place on every refresh, so the backing item must be
-  writable.
-
-To bootstrap, run `claude login` locally, then copy the refresh token from
-`~/.claude/.credentials.json` (or from the `Claude Code-credentials` keychain
-item on macOS) into `CLAUDE_CODE_BLOB`. Use the constant above for
-`CLAUDE_CODE_CLIENT_ID`.
+subscription rather than a raw API key. The Console holds the refresh token and
+its background worker mints and refreshes short-lived access tokens. Proxy sync
+delivers the current token to iron-proxy, which injects it on outbound requests
+so the sandbox never sees it. The entrypoint plants a dummy
+`~/.claude/.credentials.json` so the CLI emits OAuth-shaped requests;
+iron-proxy overwrites the Bearer at request time.
+
+Run `claude login` locally, then create a Console broker credential with:
+
+- Foreign ID: `anthropic-claude`.
+- Token endpoint: `https://console.anthropic.com/v1/oauth/token`.
+- Client ID: `9d1c250a-e61b-44d9-88ed-5944d1962f5e`.
+- Refresh token: the value from `~/.claude/.credentials.json`, or from the
+  `Claude Code-credentials` keychain item on macOS.
+
+The Console encrypts the refresh token at rest and updates it after every
+rotation. No Claude OAuth credential needs to be copied into the deployment's
+environment or 1Password secret source.
 
 ## 4. Configure Advanced Permissioning
 
diff --git a/docs/pages/extend/tools.mdx b/docs/pages/extend/tools.mdx
index 2be4df45d..a0098636f 100644
--- a/docs/pages/extend/tools.mdx
+++ b/docs/pages/extend/tools.mdx
@@ -67,17 +67,18 @@ Each entry in `secrets` declares one credential the tool can request with
   auth). For `jwt_bearer` (RFC 7523), supply `issuer`, `subject`, and
   `private_key` (an RSA PEM) in `fields`, plus a top-level `audience`; an
   optional `private_key_id` field is emitted as the JWT `kid` header.
-- `type = "brokered_token"` routes OAuth2 refresh-token rotation through
-  iron-token-broker instead of iron-proxy. Use this when the upstream IdP
-  rotates refresh tokens with strict reuse detection (OpenAI Codex, Anthropic
-  Claude Code OAuth, modern Okta or Auth0 with rotation enabled) and more
-  than one proxy shares the credential. Required `fields`: `client_id`,
-  `refresh_token`. Optional: `client_secret`. The `refresh_token` field names
-  the writable credential blob the broker rewrites on every rotation; the
-  other fields are read-only. Read-side fields and `token_endpoint_headers`
-  entries accept `json_key` to pluck a value out of a JSON-encoded secret;
-  the `refresh_token` field does not (the broker rewrites the whole
-  document).
+- `type = "brokered_token"` routes OAuth2 refresh-token rotation through the
+  Console's broker credential system instead of through each iron-proxy. Use
+  this when the upstream IdP rotates refresh tokens with strict reuse detection
+  (OpenAI Codex, Anthropic Claude Code OAuth, modern Okta or Auth0 with rotation
+  enabled) and more than one proxy shares the credential. The entry is only the
+  consumer side: `name` identifies the injected secret, `hosts` defines its
+  request rules, and optional `credential` names the Console broker credential
+  by foreign ID (defaulting to `name`). Create that credential separately in
+  the Console or with `centaur-perms broker create`. Optional `inject_header`
+  and `inject_formatter` override the default Bearer authorization injection.
+  Legacy `fields`, `token_endpoint`, and `scopes` keys are ignored and should
+  not be declared.
 - `type = "gcp_auth"` is for Google service-account JSON. iron-proxy resolves
   the keyfile, mints Google OAuth tokens for `scopes`, and injects them for the
   configured Google API `hosts`. If omitted, hosts default to
diff --git a/docs/pages/reference/configuration.mdx b/docs/pages/reference/configuration.mdx
index c9ed75475..e87106f0c 100644
--- a/docs/pages/reference/configuration.mdx
+++ b/docs/pages/reference/configuration.mdx
@@ -37,9 +37,7 @@ These must exist for the normal Helm deployment. For local development,
 | `SLACK_SIGNING_SECRET` | `secretManager.existingSecretName`; local bootstrap reads shell env. | Slack request signature verification. |
 | `SLACKBOT_API_KEY` | `secretManager.existingSecretName`; local bootstrap reads shell env. | Dedicated Slackbot key accepted by api-rs for the Slack session namespace and workflow events. |
 | `SLACK_BOT_TOKEN` | `secretManager.existingSecretName`; local bootstrap reads shell env. | Slack Web API access for Slackbot and api-rs Slack helpers. |
-| `SANDBOX_SIGNING_KEY` | `secretManager.existingSecretName`; local bootstrap generates it. | Signing key for short-lived sandbox API tokens. |
 | `IRON_MANAGEMENT_API_KEY` | `secretManager.existingSecretName`; local bootstrap generates it. | Management key for API-created iron-proxy pods. |
-| `IRON_BROKER_TOKEN` | `secretManager.existingSecretName`; required when `tokenBroker.enabled=true`. | Bearer token iron-proxy presents to iron-token-broker and the broker enforces on its HTTP API. |
 | `OP_SERVICE_ACCOUNT_TOKEN` | Local shell, then `centaur-infra-env`; production Secret. | 1Password service-account auth when using `onepassword` secret source. |
 | `OP_VAULT` | Local shell, then `centaur-infra-env`; defaults to `ai-agents` in code. | 1Password vault used for `op://...` secret refs. |
 
@@ -226,9 +224,7 @@ Kubernetes backend:
 | `KUBERNETES_FIREWALL_CA_SECRET_NAME`, `KUBERNETES_FIREWALL_CA_KEY_SECRET_NAME` | `firewall.existingCa*` or generated CA Secrets. | CA material for sandbox/proxy TLS interception. |
 | `KUBERNETES_SECRET_ENV_NAME`, `KUBERNETES_SECRET_ENV_PREFIX`, `KUBERNETES_BOOTSTRAP_SECRET_NAME` | `secretManager.*`, `secrets.bootstrapSecretName`. | Secrets read by API-created proxy/sandbox pods. |
 | `KUBERNETES_IRON_PROXY_IMAGE`, `KUBERNETES_IRON_PROXY_IMAGE_PULL_POLICY`, `KUBERNETES_IRON_PROXY_PORT`, `KUBERNETES_IRON_PROXY_MANAGEMENT_PORT`, `KUBERNETES_IRON_PROXY_HEALTH_PORT` | `ironProxy.*`. | Per-sandbox iron-proxy image and ports. |
-| `FIREWALL_MANAGER_SECRET_SOURCE`, `FIREWALL_MANAGER_SECRET_TTL`, `KUBERNETES_FIREWALL_MANAGER_SECRET_SOURCE` | `ironProxy.secretSource`, `ironProxy.secretTtl`. | Secret source and cache TTL for rendered proxy config. |
-| `FIREWALL_MANAGER_TOKEN_BROKER_TTL` | `tokenBroker.ttl`. | Proxy-side cache TTL for access tokens minted by iron-token-broker. Applied to every `brokered_token` secret. |
-| `KUBERNETES_TOKEN_BROKER_NAME`, `KUBERNETES_TOKEN_BROKER_URL` | `tokenBroker.*`. | iron-token-broker Deployment name and ClusterIP URL. The chart owns the broker Deployment, Service, and NetworkPolicies; the API reconciles its ConfigMap and triggers a rolling restart when the rendered content changes. |
+| `FIREWALL_MANAGER_SECRET_SOURCE`, `FIREWALL_MANAGER_SECRET_TTL` | `ironProxy.secretSource`, `ironProxy.secretTtl`. | Secret source and cache TTL for rendered proxy config. |
 | `KUBERNETES_OP_CONNECT_HOST`, `KUBERNETES_OP_CONNECT_APP_NAME`, `KUBERNETES_OP_CONNECT_PORT` | Chart helper or `api.extraEnv`. | 1Password Connect endpoint details. |
 | `KUBERNETES_API_POD_LABEL_SELECTOR` | Chart-rendered labels or `api.extraEnv`. | API pod selector for API-managed proxy policies. |
 | `KUBERNETES_EGRESS_DISCOVERY_ENABLED`, `KUBERNETES_EGRESS_SERVICE_NAMESPACE`, `KUBERNETES_CLUSTER_DOMAIN`, `KUBERNETES_EGRESS_TAILNET_FQDN_ANNOTATION` | `api.egressDiscovery.*`. | Egress service discovery for sandbox NetworkPolicies. |
diff --git a/docs/pages/secrets/environment.mdx b/docs/pages/secrets/environment.mdx
index b632c68f8..46ef11323 100644
--- a/docs/pages/secrets/environment.mdx
+++ b/docs/pages/secrets/environment.mdx
@@ -34,7 +34,6 @@ kubectl create secret generic centaur-infra-env \
   --from-literal=SLACKBOT_API_KEY='...' \
   --from-literal=SLACK_BOT_TOKEN='xoxb-...' \
   --from-literal=SLACK_SIGNING_SECRET='...' \
-  --from-literal=SANDBOX_SIGNING_KEY="$(openssl rand -hex 32)" \
   --from-literal=IRON_MANAGEMENT_API_KEY="$(openssl rand -hex 32)" \
   --from-literal=OPENAI_API_KEY='...' \
   --from-literal=AMP_API_KEY='...' \
diff --git a/docs/pages/secrets/onepassword.mdx b/docs/pages/secrets/onepassword.mdx
index 0b3766953..a61765dc0 100644
--- a/docs/pages/secrets/onepassword.mdx
+++ b/docs/pages/secrets/onepassword.mdx
@@ -75,7 +75,6 @@ CENTAUR_JWT_SIGNING_SECRET
 SLACKBOT_API_KEY
 SLACK_BOT_TOKEN
 SLACK_SIGNING_SECRET
-SANDBOX_SIGNING_KEY
 IRON_MANAGEMENT_API_KEY
 ```
 
diff --git a/services/sandbox/entrypoint.sh b/services/sandbox/entrypoint.sh
index 81998ad5c..a16720554 100644
--- a/services/sandbox/entrypoint.sh
+++ b/services/sandbox/entrypoint.sh
@@ -324,8 +324,8 @@ fi
 #   - access_token: Claude Code runs as a Claude.ai Pro or Max subscription
 #     user. We install a dummy ~/.claude/.credentials.json so the CLI emits
 #     OAuth-shaped requests, unset the API-key stub so it does not fall back
-#     to X-Api-Key, and let iron-token-broker mint a real Bearer at request
-#     time via the anthropic-claude brokered_token secret.
+#     to X-Api-Key, and let iron-proxy inject the current Console-managed
+#     Bearer via the anthropic-claude brokered_token secret.
 CLAUDE_CODE_AUTH_MODE="${CLAUDE_CODE_AUTH_MODE:-api_key}"
 case "$CLAUDE_CODE_AUTH_MODE" in
     api_key)

From 25bf7e26c27f9a09de6eae7176132d98b1070a0a Mon Sep 17 00:00:00 2001
From: Adam Nieslanik <101835132+kreplik@users.noreply.github.com>
Date: Wed, 19 Aug 2026 04:44:05 +0000
Subject: [PATCH 15/36] fix(chart): roll repo-cache when its GitHub token
 secret changes (#1322)

* fix(chart): roll repo-cache when its GitHub token secret changes

repo-cache authenticates to GitHub from a token file mounted off
repoCache.githubToken, but its pod template carries no annotation tied to
that secret. Every other component in the chart has checksum/infra-secrets,
so repo-cache is the only workload that keeps running against a stale
token after the secret is rotated or recreated. Recovering means noticing
that repos have stopped syncing and deleting the pod by hand.

Add checksum/github-token, built from the same centaur.secretResourceVersion
helper the other components use. Recreating a Secret changes its
resourceVersion, so the next upgrade rolls the pod. Rendered only when a
token is configured, so token-less deployments see no change.

* chore(chart): bump release to 0.1.122

---------

Co-authored-by: Matthew Slipper <me@matthewslipper.com>
---
 contrib/chart/Chart.yaml                | 2 +-
 contrib/chart/templates/repo-cache.yaml | 4 ++++
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/contrib/chart/Chart.yaml b/contrib/chart/Chart.yaml
index d4a0885e5..d783fe669 100644
--- a/contrib/chart/Chart.yaml
+++ b/contrib/chart/Chart.yaml
@@ -2,7 +2,7 @@ apiVersion: v2
 name: centaur
 description: Helm chart for the trusted Centaur control plane
 type: application
-version: 0.1.121
+version: 0.1.122
 appVersion: "0.1.0"
 dependencies:
   - name: connect
diff --git a/contrib/chart/templates/repo-cache.yaml b/contrib/chart/templates/repo-cache.yaml
index 474e2448d..f457321bb 100644
--- a/contrib/chart/templates/repo-cache.yaml
+++ b/contrib/chart/templates/repo-cache.yaml
@@ -89,6 +89,10 @@ spec:
 {{ include "centaur.componentSelectorLabels" (dict "root" . "component" "repo-cache") | nindent 6 }}
   template:
     metadata:
+{{- if $repoCacheHasGithubToken }}
+      annotations:
+        checksum/github-token: {{ include "centaur.secretResourceVersion" (dict "root" . "name" (include "centaur.repoCacheGithubTokenSecretName" .)) | sha256sum }}
+{{- end }}
       labels:
 {{ include "centaur.componentSelectorLabels" (dict "root" . "component" "repo-cache") | nindent 8 }}
     spec:

From b6bea3b155e68544abe0efb1074f5d855dc8a17f Mon Sep 17 00:00:00 2001
From: akandic47 <57039429+akandic47@users.noreply.github.com>
Date: Wed, 19 Aug 2026 04:45:08 +0000
Subject: [PATCH 16/36] docs: document access-token broker credential bootstrap
 (#997)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* docs: document the access-token broker credential bootstrap; hint at it from api-rs

In access_token mode the harness proxy fragment references a console
broker credential (openai-codex / anthropic-claude) that must be created
out of band with 'centaur-perms broker create'. The production guide
never mentioned it, and instead described the removed standalone
token-broker flow (OPENAI_CODEX_BLOB / CLAUDE_CODE_BLOB items in the
secrets backend that nothing reads anymore), so a fresh deployment ends
in an api-rs crash-loop on the console's 422.

- rewrite the Codex/Claude Auth Modes sections around the real
  bootstrap: codex/claude login, store OPENAI_CODEX_ACCOUNT_ID (codex
  only), create the broker credential, restart api-rs; keep the
  token-family reuse warnings
- select the mode via sandbox.codexAuthMode / sandbox.claudeCodeAuthMode
  instead of sandbox.extraEnv — extraEnv only reaches sandbox pods, not
  api-rs, which is the component that acts on the mode
- point at the out-of-band step from the bootstrap script usage text
- api-rs: when the registration 422 names a missing broker credential,
  append a 'centaur-perms broker create' hint to the startup error

Closes #995

* docs: correct broker bootstrap instructions

---------

Co-authored-by: Matthew Slipper <me@matthewslipper.com>
---
 contrib/scripts/bootstrap-k8s-secrets.sh |   6 +
 docs/pages/deploying-in-production.mdx   | 161 ++++++++++++++++-------
 docs/pages/reference/configuration.mdx   |   4 +-
 3 files changed, 120 insertions(+), 51 deletions(-)

diff --git a/contrib/scripts/bootstrap-k8s-secrets.sh b/contrib/scripts/bootstrap-k8s-secrets.sh
index 510f4140e..b5f0a22ca 100755
--- a/contrib/scripts/bootstrap-k8s-secrets.sh
+++ b/contrib/scripts/bootstrap-k8s-secrets.sh
@@ -81,6 +81,12 @@ Console bootstrap:
                                initial admin email (default admin@centaur.local)
   The initial password, API key, the three ActiveRecord encryption keys, and
   SECRET_KEY_BASE are auto-generated when absent (never rotated in place).
+
+Note: harness access-token modes (sandbox.codexAuthMode / claudeCodeAuthMode
+set to access_token) also need a console broker credential (openai-codex /
+anthropic-claude) created out of band with `centaur-perms broker create`;
+without it api-rs fails registration at startup. This script cannot seed it.
+See the Codex/Claude Auth Modes sections in docs/pages/deploying-in-production.mdx.
 EOF
 }
 
diff --git a/docs/pages/deploying-in-production.mdx b/docs/pages/deploying-in-production.mdx
index 3431a804e..294800a97 100644
--- a/docs/pages/deploying-in-production.mdx
+++ b/docs/pages/deploying-in-production.mdx
@@ -148,32 +148,67 @@ token family is revoked, logging both sides out at random. Use a separate
 ChatGPT account for any non-Centaur Codex work.
 :::
 
-Codex supports two authentication modes, selected per deployment with the
-`CODEX_AUTH_MODE` env var on the sandbox (set it via `sandbox.extraEnv`):
-
-| Mode | Upstream | Secrets required |
-|------|----------|------------------|
-| `api_key` (default) | `api.openai.com` | `OPENAI_API_KEY` |
-| `access_token` | `chatgpt.com` | Console broker credential `openai-codex`; `OPENAI_CODEX_ACCOUNT_ID` |
+Codex supports two authentication modes, selected per deployment with
+`sandbox.codexAuthMode` in the chart values. api-rs reads the resulting
+`CODEX_AUTH_MODE` env var to register the matching proxy credential with the
+console and propagates it into each sandbox, so the agent's `auth.json` and
+the injected credential always agree. Do not set `CODEX_AUTH_MODE` through
+`sandbox.extraEnv`: that reaches sandbox pods but not api-rs, which is the
+component that acts on the mode.
+
+| Mode | Upstream | Credentials required |
+|------|----------|----------------------|
+| `api_key` (default) | `api.openai.com` | `OPENAI_API_KEY` in the secrets backend |
+| `access_token` | `chatgpt.com` | `OPENAI_CODEX_ACCOUNT_ID` in the secrets backend, plus the `openai-codex` broker credential in the console |
 
 `access_token` mode routes Codex through a ChatGPT account rather than a raw
-API key. The Console holds the refresh token and its background worker mints
-and refreshes short-lived access tokens. Proxy sync delivers the current token
-to iron-proxy, which injects it on outbound requests so the sandbox never sees
-it.
-
-Run `codex login` locally, then create a Console broker credential with:
-
-- Foreign ID: `openai-codex`.
-- Token endpoint: `https://auth.openai.com/oauth/token`.
-- Client ID: `app_EMoamEEZ73f0CkXaXp7hrann`.
-- Refresh token: the value from `~/.codex/auth.json`.
-
-The Console encrypts the refresh token at rest and updates it after every
-rotation. Store `OPENAI_CODEX_ACCOUNT_ID`, the ChatGPT account UUID from the
-same login file, in the configured secrets backend. iron-proxy injects it as
-the `chatgpt-account-id` header so the backend can route to the correct
-workspace.
+API key. The console owns the refresh token as the `openai-codex` broker
+credential: its background worker refreshes it and mints short-lived access
+tokens, which the per-sandbox proxy injects on outbound requests so the
+sandbox never sees them. The refresh token is stored encrypted in the
+console's own database. It is not read from or synced to your secrets
+backend.
+
+The commands below assume you are at the root of a Centaur checkout and have
+configured `IRON_CONTROL_URL` and `IRON_CONTROL_API_KEY` as described in
+[Configure the Operator CLI](/secrets/advanced-permissioning#configure-the-operator-cli).
+
+To bootstrap `access_token` mode:
+
+1. Log in locally with the dedicated ChatGPT account and force this login to
+   use a file-backed credential store:
+
+   ```bash
+   codex login -c 'cli_auth_credentials_store="file"'
+   CODEX_AUTH_FILE="${CODEX_HOME:-$HOME/.codex}/auth.json"
+   export OPENAI_CODEX_ACCOUNT_ID="$(jq -er '.tokens.account_id' "$CODEX_AUTH_FILE")"
+   export OPENAI_CODEX_REFRESH_TOKEN="$(jq -er '.tokens.refresh_token' "$CODEX_AUTH_FILE")"
+   ```
+
+   The credential-store override is intentional. Codex can otherwise use the
+   operating system keyring, which leaves no `auth.json` file to read.
+2. Store `OPENAI_CODEX_ACCOUNT_ID` in your secrets backend (1Password vault,
+   Kubernetes Secret, etc.). iron-proxy injects this ChatGPT account UUID as
+   the `chatgpt-account-id` header so the backend routes to the right
+   workspace.
+3. Create the broker credential with the refresh token from the same login:
+
+   ```bash
+   cargo run --manifest-path services/api-rs/Cargo.toml -p centaur-perms -- \
+     broker create --foreign-id openai-codex \
+     --token-endpoint https://auth.openai.com/oauth/token \
+     --client-id app_EMoamEEZ73f0CkXaXp7hrann \
+     --refresh-token "$OPENAI_CODEX_REFRESH_TOKEN"
+   unset OPENAI_CODEX_REFRESH_TOKEN
+   ```
+
+   The client id is the Codex CLI's fixed, publicly known OAuth client id:
+   the same for every Codex install; it is passed here, not stored in the
+   secrets backend.
+4. Start (or restart) api-rs. At startup it registers the access-token
+   fragment with the console; if the `openai-codex` broker credential does
+   not exist yet, the console rejects the registration with a 422 and api-rs
+   fails fast, so create the credential first.
 
 ### Claude Auth Modes
 
@@ -187,34 +222,62 @@ entire token family is revoked, logging both sides out at random. Use a
 separate Claude.ai account for any non-Centaur Claude Code work.
 :::
 
-Claude Code supports two authentication modes, selected per deployment
-with the `CLAUDE_CODE_AUTH_MODE` env var on the sandbox (set it via
-`sandbox.extraEnv`):
+Claude Code supports two authentication modes, selected per deployment with
+`sandbox.claudeCodeAuthMode` in the chart values. It has the same contract as
+`sandbox.codexAuthMode` above: api-rs registers the matching proxy credential
+and propagates `CLAUDE_CODE_AUTH_MODE` into each sandbox, so do not set the
+env var through `sandbox.extraEnv`.
 
-| Mode | Upstream | Secrets required |
-|------|----------|------------------|
-| `api_key` (default) | `api.anthropic.com` | `ANTHROPIC_API_KEY` |
-| `access_token` | `api.anthropic.com` | Console broker credential `anthropic-claude` |
+| Mode | Upstream | Credentials required |
+|------|----------|----------------------|
+| `api_key` (default) | `api.anthropic.com` | `ANTHROPIC_API_KEY` in the secrets backend |
+| `access_token` | `api.anthropic.com` | the `anthropic-claude` broker credential in the console |
 
 `access_token` mode routes Claude Code through a Claude.ai Pro or Max
-subscription rather than a raw API key. The Console holds the refresh token and
-its background worker mints and refreshes short-lived access tokens. Proxy sync
-delivers the current token to iron-proxy, which injects it on outbound requests
-so the sandbox never sees it. The entrypoint plants a dummy
-`~/.claude/.credentials.json` so the CLI emits OAuth-shaped requests;
-iron-proxy overwrites the Bearer at request time.
-
-Run `claude login` locally, then create a Console broker credential with:
-
-- Foreign ID: `anthropic-claude`.
-- Token endpoint: `https://console.anthropic.com/v1/oauth/token`.
-- Client ID: `9d1c250a-e61b-44d9-88ed-5944d1962f5e`.
-- Refresh token: the value from `~/.claude/.credentials.json`, or from the
-  `Claude Code-credentials` keychain item on macOS.
-
-The Console encrypts the refresh token at rest and updates it after every
-rotation. No Claude OAuth credential needs to be copied into the deployment's
-environment or 1Password secret source.
+subscription rather than a raw API key. The console owns the refresh token as
+the `anthropic-claude` broker credential and mints short-lived access tokens,
+which the per-sandbox proxy injects as the Bearer on outbound requests so the
+sandbox never sees them. The sandbox entrypoint plants a dummy
+`~/.claude/.credentials.json` so the CLI emits OAuth-shaped requests; the
+proxy overwrites the Bearer at request time. This mode needs no
+secrets-backend items.
+
+The commands below assume you are at the root of a Centaur checkout and have
+configured `IRON_CONTROL_URL` and `IRON_CONTROL_API_KEY` as described in
+[Configure the Operator CLI](/secrets/advanced-permissioning#configure-the-operator-cli).
+
+To bootstrap, run `claude login` locally with the dedicated Claude.ai
+account, then export the refresh token. On systems where Claude Code writes a
+credentials file, run:
+
+```bash
+export CLAUDE_CODE_REFRESH_TOKEN="$(
+  jq -er '.claudeAiOauth.refreshToken' "$HOME/.claude/.credentials.json"
+)"
+```
+
+If Claude Code used the macOS keychain instead, run:
+
+```bash
+export CLAUDE_CODE_REFRESH_TOKEN="$(
+  security find-generic-password -s 'Claude Code-credentials' -w |
+    jq -er '.claudeAiOauth.refreshToken'
+)"
+```
+
+Create the broker credential from the root of the checkout:
+
+```bash
+cargo run --manifest-path services/api-rs/Cargo.toml -p centaur-perms -- \
+  broker create --foreign-id anthropic-claude \
+  --token-endpoint https://platform.claude.com/v1/oauth/token \
+  --client-id 9d1c250a-e61b-44d9-88ed-5944d1962f5e \
+  --refresh-token "$CLAUDE_CODE_REFRESH_TOKEN"
+unset CLAUDE_CODE_REFRESH_TOKEN
+```
+
+The client id is Claude Code's fixed, publicly known OAuth client id. As with
+Codex, api-rs fails fast at startup if the broker credential is missing.
 
 ## 4. Configure Advanced Permissioning
 
diff --git a/docs/pages/reference/configuration.mdx b/docs/pages/reference/configuration.mdx
index e87106f0c..abf705192 100644
--- a/docs/pages/reference/configuration.mdx
+++ b/docs/pages/reference/configuration.mdx
@@ -239,12 +239,12 @@ Sandbox entrypoint and wrappers:
 | `AGENT_REPO`, `AGENT_PERSONA` | Runtime assignment metadata. | Workspace repo clone and persona prompt. |
 | `GOOGLE_APPLICATION_CREDENTIALS` | Sandbox entrypoint or `sandbox.extraEnv`. | Google ADC path; entrypoint creates a local stub when unset. |
 | `CODEX_API_KEY`, `CODEX_HOME`, `CODEX_CONTINUE_THREAD_ID` | `sandbox.extraEnv` or runtime resume. | Codex auth/config/resume behavior. |
-| `CODEX_AUTH_MODE` | `sandbox.extraEnv`. | Codex auth flow: `api_key` (default, hits `api.openai.com`) or `access_token` (hits `chatgpt.com` via the brokered ChatGPT login). See [Codex Auth Modes](/deploying-in-production#codex-auth-modes). |
+| `CODEX_AUTH_MODE` | `sandbox.codexAuthMode`. | Codex auth flow: `api_key` (default, hits `api.openai.com`) or `access_token` (hits `chatgpt.com` via the brokered ChatGPT login). The chart sets this on api-rs, which propagates it into sandboxes. See [Codex Auth Modes](/deploying-in-production#codex-auth-modes). |
 | `META_AI_API_KEY` | Secret mounted into api-rs. | Meta AI direct credential for Codex provider `responses` and Slack or Linear `--meta` selection. |
 | `CODEX_MODEL_REASONING_SUMMARY` | `sandbox.extraEnv`. | Sets `model_reasoning_summary` in the Codex config (`auto`, `concise`, `detailed`, `none`). Codex >= 0.139 emits no reasoning summaries unless this is set, so renderers show no thinking trace. |
 | `CODEX_MODEL_REASONING_EFFORT` | `sandbox.extraEnv`. | Overrides the Codex `model_reasoning_effort` (baked into `harness/codex/config.toml`) and Nanocodex's default thinking effort. It is mirrored into Slackbot so the first response footer displays the effective level. One of `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`; an unknown value is ignored (the config default stands). |
 | `CLAUDE_MODEL`, `CLAUDE_CONTINUE_SESSION_ID` | `sandbox.extraEnv` or runtime resume. | Claude model and resume behavior. |
-| `CLAUDE_CODE_AUTH_MODE` | `sandbox.extraEnv`. | Claude Code auth flow: `api_key` (default, uses `ANTHROPIC_API_KEY`) or `access_token` (Claude.ai Pro or Max via the brokered OAuth login). See [Claude Auth Modes](/deploying-in-production#claude-auth-modes). |
+| `CLAUDE_CODE_AUTH_MODE` | `sandbox.claudeCodeAuthMode`. | Claude Code auth flow: `api_key` (default, uses `ANTHROPIC_API_KEY`) or `access_token` (Claude.ai Pro or Max via the brokered OAuth login). The chart sets this on api-rs, which propagates it into sandboxes. See [Claude Auth Modes](/deploying-in-production#claude-auth-modes). |
 | `DEPLOY_ENV`, `ENVIRONMENT`, `TRACEPARENT` | Deployment env or wrapper-generated. | Runtime environment and trace context. |
 | `CALL_TIMEOUT_SECONDS` | Sandbox env before running `call`. | Curl watchdog for API tool calls. |
 | `SLACK_CHANNEL`, `SLACK_THREAD_TS` | Sandbox env. | File-upload helper target. |

From ae185c2086f79dfe4ea43494f11d580b8a0118ee Mon Sep 17 00:00:00 2001
From: Jaume Alavedra <jamalavedra@gmail.com>
Date: Wed, 19 Aug 2026 04:46:29 +0000
Subject: [PATCH 17/36] fix(sandbox): seed brokered Codex auth for Hermes
 (#1368)

---
 services/sandbox/Dockerfile                   |  1 +
 services/sandbox/entrypoint.sh                |  1 +
 services/sandbox/seed_hermes_codex_auth.py    | 49 +++++++++++++++++++
 .../sandbox/test_seed_hermes_codex_auth.py    | 37 ++++++++++++++
 4 files changed, 88 insertions(+)
 create mode 100644 services/sandbox/seed_hermes_codex_auth.py
 create mode 100644 services/sandbox/test_seed_hermes_codex_auth.py

diff --git a/services/sandbox/Dockerfile b/services/sandbox/Dockerfile
index 56a509178..f09624381 100644
--- a/services/sandbox/Dockerfile
+++ b/services/sandbox/Dockerfile
@@ -294,6 +294,7 @@ COPY --link --chmod=755 services/workflow-python/workflow_host.py /usr/local/bin
 COPY --link services/workflow-python/api/ /usr/local/bin/api/
 COPY --link --chmod=755 services/sandbox/git-branch.sh /usr/local/bin/git-branch
 COPY --link --chmod=755 services/sandbox/install_tool_shims.py /usr/local/bin/install-tool-shims
+COPY --link --chmod=755 services/sandbox/seed_hermes_codex_auth.py /usr/local/bin/seed-hermes-codex-auth
 COPY --link --chmod=755 services/sandbox/centaur_tool_host.py /usr/local/bin/centaur-tool-host
 COPY --link --chmod=755 services/sandbox/compose_system_prompt.py /usr/local/bin/compose-system-prompt
 COPY --link --chmod=755 services/sandbox/repo_cache_sync.py /usr/local/bin/repo-cache-sync
diff --git a/services/sandbox/entrypoint.sh b/services/sandbox/entrypoint.sh
index a16720554..479e31cd8 100644
--- a/services/sandbox/entrypoint.sh
+++ b/services/sandbox/entrypoint.sh
@@ -128,6 +128,7 @@ mkdir -p "$HOME_DIR/.codex"
 if [ "$CODEX_AUTH_MODE" = "access_token" ] && [ -f /etc/centaur/codex-auth.default.json ]; then
     cp /etc/centaur/codex-auth.default.json "$HOME_DIR/.codex/auth.json"
     chmod 600 "$HOME_DIR/.codex/auth.json"
+    seed-hermes-codex-auth "$HOME_DIR/.codex/auth.json" "$HOME_DIR/.hermes/auth.json"
 elif [ ! -f "$HOME_DIR/.codex/auth.json" ] && [ -f /etc/centaur/codex-auth.default.json ]; then
     cp /etc/centaur/codex-auth.default.json "$HOME_DIR/.codex/auth.json"
     chmod 600 "$HOME_DIR/.codex/auth.json"
diff --git a/services/sandbox/seed_hermes_codex_auth.py b/services/sandbox/seed_hermes_codex_auth.py
new file mode 100644
index 000000000..afb9115d3
--- /dev/null
+++ b/services/sandbox/seed_hermes_codex_auth.py
@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+"""Seed Hermes with Centaur's broker-only Codex credential placeholder."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+
+def seed(codex_auth_path: Path, hermes_auth_path: Path) -> None:
+    codex = json.loads(codex_auth_path.read_text(encoding="utf-8"))
+    tokens = codex.get("tokens")
+    if not isinstance(tokens, dict) or not all(tokens.get(key) for key in ("access_token", "refresh_token")):
+        raise ValueError("Codex auth must contain access_token and refresh_token placeholders")
+
+    try:
+        auth = json.loads(hermes_auth_path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        auth = {"version": 1, "providers": {}}
+    if not isinstance(auth, dict) or not isinstance(auth.setdefault("providers", {}), dict):
+        raise ValueError("Hermes auth must be a JSON object with a providers object")
+
+    auth["providers"]["openai-codex"] = {
+        "tokens": {
+            "access_token": tokens["access_token"],
+            "refresh_token": tokens["refresh_token"],
+        },
+        "last_refresh": codex.get("last_refresh"),
+        "auth_mode": "chatgpt",
+    }
+
+    hermes_auth_path.parent.mkdir(parents=True, exist_ok=True)
+    fd, temporary = tempfile.mkstemp(dir=hermes_auth_path.parent, prefix="auth.json.")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(auth, handle, indent=2)
+            handle.write("\n")
+        os.chmod(temporary, 0o600)
+        os.replace(temporary, hermes_auth_path)
+    finally:
+        if os.path.exists(temporary):
+            os.unlink(temporary)
+
+
+if __name__ == "__main__":
+    seed(Path(sys.argv[1]), Path(sys.argv[2]))
diff --git a/services/sandbox/test_seed_hermes_codex_auth.py b/services/sandbox/test_seed_hermes_codex_auth.py
new file mode 100644
index 000000000..55959d929
--- /dev/null
+++ b/services/sandbox/test_seed_hermes_codex_auth.py
@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import json
+import stat
+import tempfile
+import unittest
+from pathlib import Path
+
+from seed_hermes_codex_auth import seed
+
+
+class SeedHermesCodexAuthTest(unittest.TestCase):
+    def test_seeds_placeholder_and_preserves_other_providers(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            codex = root / "codex.json"
+            hermes = root / ".hermes" / "auth.json"
+            codex.write_text(json.dumps({
+                "tokens": {"access_token": "dummy-access", "refresh_token": "dummy-refresh"},
+                "last_refresh": "2025-01-01T00:00:00Z",
+            }))
+            hermes.parent.mkdir()
+            hermes.write_text(json.dumps({"version": 1, "providers": {"other": {"api_key": "placeholder"}}}))
+
+            seed(codex, hermes)
+
+            auth = json.loads(hermes.read_text())
+            self.assertEqual(auth["providers"]["other"]["api_key"], "placeholder")
+            self.assertEqual(auth["providers"]["openai-codex"]["tokens"], {
+                "access_token": "dummy-access",
+                "refresh_token": "dummy-refresh",
+            })
+            self.assertEqual(stat.S_IMODE(hermes.stat().st_mode), 0o600)
+
+
+if __name__ == "__main__":
+    unittest.main()

From fdd87278acf261f6cb902a62a41c199f814069cd Mon Sep 17 00:00:00 2001
From: Derek Cofausper <256792747+decofe@users.noreply.github.com>
Date: Wed, 19 Aug 2026 04:50:00 +0000
Subject: [PATCH 18/36] fix(attio): harden CRM mutations and pagination (#1306)

* fix(attio): support replacing record values

Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com>

* fix(attio): harden CRM mutations and pagination

Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com>

* fix(attio): parse rate-limit reset dates

Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com>
---
 tools/business/attio/cli.py         |  42 ++++++++++-
 tools/business/attio/client.py      | 111 ++++++++++++++++++++++++---
 tools/business/attio/test_client.py | 112 ++++++++++++++++++++++++++++
 3 files changed, 252 insertions(+), 13 deletions(-)

diff --git a/tools/business/attio/cli.py b/tools/business/attio/cli.py
index b5482e7f9..1d47a7a65 100644
--- a/tools/business/attio/cli.py
+++ b/tools/business/attio/cli.py
@@ -208,12 +208,17 @@ def records(
     limit: int = typer.Option(25, "--limit", "-n", help="Max results"),
     filter_json: str = typer.Option(None, "--filter", "-f", help="Filter as JSON"),
     json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
+    all_results: bool = typer.Option(False, "--all", help="Fetch all result pages"),
 ):
     """Query records for any object."""
     client = _get_client()
 
     filter_obj = json.loads(filter_json) if filter_json else None
-    records_list = client.query_records(object_slug, filter_obj=filter_obj, limit=limit)
+    records_list = (
+        client.query_all_records(object_slug, filter_obj=filter_obj, page_size=limit)
+        if all_results
+        else client.query_records(object_slug, filter_obj=filter_obj, limit=limit)
+    )
 
     if json_output:
         print(json.dumps(records_list, indent=2, ensure_ascii=False), file=sys.stdout)
@@ -280,19 +285,43 @@ def update(
     object_slug: str = typer.Argument(..., help="Object slug"),
     record_id: str = typer.Argument(..., help="Record ID"),
     values_json: str = typer.Argument(..., help="Values to update as JSON"),
+    json_output: bool = typer.Option(False, "--json", "-j", help="Output canonical response"),
 ):
-    """Update an existing record.
+    """Update a record, appending rather than replacing multiselect values.
 
     Examples:
         attio update people abc123 '{"email_addresses": [{"email_address": "new@email.com"}]}'
     """
     client = _get_client()
     values = json.loads(values_json)
-    client.update_record(object_slug, record_id, values)
+    record = client.update_record(object_slug, record_id, values)
+
+    if json_output:
+        print(json.dumps(record, indent=2, ensure_ascii=False), file=sys.stdout)
+        raise typer.Exit()
 
     console.print(f"[green]✓ Updated {object_slug} record {record_id[:8]}...[/]")
 
 
+@app.command()
+def replace(
+    object_slug: str = typer.Argument(..., help="Object slug"),
+    record_id: str = typer.Argument(..., help="Record ID"),
+    values_json: str = typer.Argument(..., help="Values to replace as JSON"),
+    json_output: bool = typer.Option(False, "--json", "-j", help="Output canonical response"),
+):
+    """Replace supplied attribute values, including multi-value relationships."""
+    client = _get_client()
+    values = json.loads(values_json)
+    record = client.replace_record_values(object_slug, record_id, values)
+
+    if json_output:
+        print(json.dumps(record, indent=2, ensure_ascii=False), file=sys.stdout)
+        raise typer.Exit()
+
+    console.print(f"[green]✓ Replaced values on {object_slug} record {record_id[:8]}...[/]")
+
+
 @app.command()
 def delete(
     object_slug: str = typer.Argument(..., help="Object slug"),
@@ -390,10 +419,15 @@ def notes(
     object_slug: str = typer.Argument(..., help="Parent object slug"),
     record_id: str = typer.Argument(..., help="Parent record ID"),
     json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
+    all_results: bool = typer.Option(False, "--all", help="Fetch all result pages"),
 ):
     """List notes for a record."""
     client = _get_client()
-    notes_list = client.list_notes(object_slug, record_id)
+    notes_list = (
+        client.list_all_notes(object_slug, record_id)
+        if all_results
+        else client.list_notes(object_slug, record_id)
+    )
 
     if json_output:
         print(json.dumps(notes_list, indent=2, ensure_ascii=False), file=sys.stdout)
diff --git a/tools/business/attio/client.py b/tools/business/attio/client.py
index fb40be70f..7480e6309 100644
--- a/tools/business/attio/client.py
+++ b/tools/business/attio/client.py
@@ -1,6 +1,9 @@
 """Attio API client."""
 
 import mimetypes
+import time
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
 from pathlib import Path
 from typing import Any
 
@@ -12,9 +15,10 @@
 class AttioClient:
     """Authenticated Attio CRM API client."""
 
-    def __init__(self, api_key: str | None = None):
+    def __init__(self, api_key: str | None = None, max_rate_limit_retries: int = 2):
         self._api_key_override = api_key
         self._client: httpx.Client | None = None
+        self.max_rate_limit_retries = max_rate_limit_retries
 
     def _http(self) -> httpx.Client:
         """Return the cached HTTP client, building it after secrets are injected."""
@@ -37,7 +41,12 @@ def _http(self) -> httpx.Client:
 
     def _request(self, method: str, path: str, **kwargs) -> dict[str, Any]:
         """Make authenticated request to Attio API."""
-        response = self._http().request(method, path, **kwargs)
+        for attempt in range(self.max_rate_limit_retries + 1):
+            response = self._http().request(method, path, **kwargs)
+            if response.status_code != 429 or attempt == self.max_rate_limit_retries:
+                break
+            retry_after = response.headers.get("Retry-After", "1")
+            time.sleep(self._retry_delay(retry_after))
         if response.status_code >= 400:
             try:
                 error = response.json()
@@ -47,6 +56,20 @@ def _request(self, method: str, path: str, **kwargs) -> dict[str, Any]:
             raise RuntimeError(f"Attio API error ({response.status_code}): {msg}")
         return response.json()
 
+    def _retry_delay(self, retry_after: str, now: datetime | None = None) -> float:
+        """Parse Retry-After as delta seconds or an HTTP date, bounded to one minute."""
+        try:
+            delay = float(retry_after)
+        except ValueError:
+            try:
+                retry_at = parsedate_to_datetime(retry_after)
+                if retry_at.tzinfo is None:
+                    retry_at = retry_at.replace(tzinfo=UTC)
+                delay = (retry_at - (now or datetime.now(UTC))).total_seconds()
+            except (TypeError, ValueError, OverflowError):
+                delay = 1.0
+        return min(max(delay, 0.0), 60.0)
+
     def _clean_params(self, params: dict[str, Any]) -> dict[str, Any]:
         """Remove unset values and encode list query params the way Attio expects."""
         cleaned: dict[str, Any] = {}
@@ -140,6 +163,31 @@ def query_records(
         data = self._request("POST", f"/objects/{object_slug}/records/query", json=body)
         return data.get("data", [])
 
+    def query_all_records(
+        self,
+        object_slug: str,
+        filter_obj: dict | None = None,
+        sorts: list[dict] | None = None,
+        page_size: int = 500,
+    ) -> list[dict]:
+        """Query every matching record using Attio's limit/offset pagination."""
+        if not 1 <= page_size <= 500:
+            raise ValueError("page_size must be between 1 and 500")
+        records: list[dict] = []
+        offset = 0
+        while True:
+            page = self.query_records(
+                object_slug,
+                filter_obj=filter_obj,
+                sorts=sorts,
+                limit=page_size,
+                offset=offset,
+            )
+            records.extend(page)
+            if len(page) < page_size:
+                return records
+            offset += page_size
+
     def get_record(self, object_slug: str, record_id: str) -> dict:
         """Get a specific record by ID."""
         data = self._request("GET", f"/objects/{object_slug}/records/{record_id}")
@@ -163,14 +211,30 @@ def create_record(self, object_slug: str, values: dict) -> dict:
         return data.get("data", {})
 
     def update_record(self, object_slug: str, record_id: str, values: dict) -> dict:
-        """Update an existing record.
+        """Update a record, appending rather than replacing multiselect values.
 
         values format is the same as create_record — attribute slugs mapping to
         lists of typed value objects.
         """
         body = {"data": {"values": values}}
         data = self._request("PATCH", f"/objects/{object_slug}/records/{record_id}", json=body)
-        return data.get("data", {})
+        return self._validated_record_response(data, record_id)
+
+    def replace_record_values(self, object_slug: str, record_id: str, values: dict) -> dict:
+        """Replace the supplied record attribute values instead of appending them."""
+        body = {"data": {"values": values}}
+        data = self._request("PUT", f"/objects/{object_slug}/records/{record_id}", json=body)
+        return self._validated_record_response(data, record_id)
+
+    def _validated_record_response(self, response: dict[str, Any], record_id: str) -> dict:
+        """Require Attio to return the record that was mutated."""
+        record = response.get("data", {})
+        returned_id = record.get("id", {}).get("record_id")
+        if returned_id != record_id:
+            raise RuntimeError(
+                f"Attio mutation response did not confirm record {record_id}; got {returned_id!r}"
+            )
+        return record
 
     def delete_record(self, object_slug: str, record_id: str) -> bool:
         """Delete a record."""
@@ -217,9 +281,7 @@ def query_entries(
         data = self._request("POST", f"/lists/{list_id}/entries/query", json=body)
         return data.get("data", [])
 
-    def create_entry(
-        self, list_id: str, parent_record_id: str, values: dict | None = None
-    ) -> dict:
+    def create_entry(self, list_id: str, parent_record_id: str, values: dict | None = None) -> dict:
         """Create a new entry in a list."""
         body: dict[str, Any] = {"data": {"parent_record_id": parent_record_id}}
         if values:
@@ -227,15 +289,46 @@ def create_entry(
         data = self._request("POST", f"/lists/{list_id}/entries", json=body)
         return data.get("data", {})
 
-    def list_notes(self, parent_object: str, parent_record_id: str) -> list[dict]:
+    def list_notes(
+        self,
+        parent_object: str,
+        parent_record_id: str,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[dict]:
         """List notes for a record."""
         data = self._request(
             "GET",
             "/notes",
-            params={"parent_object": parent_object, "parent_record_id": parent_record_id},
+            params={
+                "parent_object": parent_object,
+                "parent_record_id": parent_record_id,
+                "limit": limit,
+                "offset": offset,
+            },
         )
         return data.get("data", [])
 
+    def list_all_notes(
+        self, parent_object: str, parent_record_id: str, page_size: int = 50
+    ) -> list[dict]:
+        """List every note for a record using Attio's limit/offset pagination."""
+        if not 1 <= page_size <= 50:
+            raise ValueError("page_size must be between 1 and 50")
+        notes: list[dict] = []
+        offset = 0
+        while True:
+            page = self.list_notes(
+                parent_object,
+                parent_record_id,
+                limit=page_size,
+                offset=offset,
+            )
+            notes.extend(page)
+            if len(page) < page_size:
+                return notes
+            offset += page_size
+
     def upload_file(
         self,
         object_slug: str,
diff --git a/tools/business/attio/test_client.py b/tools/business/attio/test_client.py
index 1451126f8..c7491210d 100644
--- a/tools/business/attio/test_client.py
+++ b/tools/business/attio/test_client.py
@@ -1,4 +1,7 @@
+import json
+from datetime import UTC, datetime
 from pathlib import Path
+from unittest.mock import patch
 
 import httpx
 import pytest
@@ -47,3 +50,112 @@ def test_upload_file_rejects_missing_path(tmp_path: Path) -> None:
 
     with pytest.raises(ValueError, match="does not exist"):
         client.upload_file("companies", "record-id", str(tmp_path / "missing.pdf"))
+
+
+def test_replace_record_values_uses_put() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.method == "PUT"
+        assert request.url.path == "/v2/objects/deals/records/deal-123"
+        assert request.read() == b'{"data":{"values":{"dependencies_4":[]}}}'
+        return httpx.Response(200, json={"data": {"id": {"record_id": "deal-123"}}})
+
+    client = AttioClient(api_key="test-key")
+    client._client = httpx.Client(
+        base_url="https://api.attio.com/v2",
+        headers={"Authorization": "Bearer test-key"},
+        transport=httpx.MockTransport(handler),
+    )
+
+    result = client.replace_record_values("deals", "deal-123", {"dependencies_4": []})
+
+    assert result == {"id": {"record_id": "deal-123"}}
+
+
+def test_update_record_rejects_unconfirmed_response() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json={"data": {"id": {"record_id": "wrong-record"}}})
+
+    client = AttioClient(api_key="test-key")
+    client._client = httpx.Client(
+        base_url="https://api.attio.com/v2",
+        headers={"Authorization": "Bearer test-key"},
+        transport=httpx.MockTransport(handler),
+    )
+
+    with pytest.raises(RuntimeError, match="did not confirm record deal-123"):
+        client.update_record("deals", "deal-123", {"name": "Example"})
+
+
+def test_query_all_records_paginates_to_short_page() -> None:
+    offsets: list[int] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        body = json.loads(request.read())
+        offsets.append(body["offset"])
+        count = 2 if body["offset"] == 0 else 1
+        return httpx.Response(200, json={"data": [{"page": body["offset"]}] * count})
+
+    client = AttioClient(api_key="test-key")
+    client._client = httpx.Client(
+        base_url="https://api.attio.com/v2",
+        headers={"Authorization": "Bearer test-key"},
+        transport=httpx.MockTransport(handler),
+    )
+
+    result = client.query_all_records("deals", page_size=2)
+
+    assert offsets == [0, 2]
+    assert len(result) == 3
+
+
+def test_list_all_notes_paginates_to_short_page() -> None:
+    offsets: list[int] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        offset = int(request.url.params["offset"])
+        offsets.append(offset)
+        count = 2 if offset == 0 else 0
+        return httpx.Response(200, json={"data": [{"page": offset}] * count})
+
+    client = AttioClient(api_key="test-key")
+    client._client = httpx.Client(
+        base_url="https://api.attio.com/v2",
+        headers={"Authorization": "Bearer test-key"},
+        transport=httpx.MockTransport(handler),
+    )
+
+    result = client.list_all_notes("deals", "deal-123", page_size=2)
+
+    assert offsets == [0, 2]
+    assert len(result) == 2
+
+
+def test_rate_limit_response_retries_then_succeeds() -> None:
+    attempts = 0
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        nonlocal attempts
+        attempts += 1
+        if attempts == 1:
+            return httpx.Response(429, headers={"Retry-After": "0"}, json={"message": "wait"})
+        return httpx.Response(200, json={"data": []})
+
+    client = AttioClient(api_key="test-key")
+    client._client = httpx.Client(
+        base_url="https://api.attio.com/v2",
+        headers={"Authorization": "Bearer test-key"},
+        transport=httpx.MockTransport(handler),
+    )
+
+    with patch("client.time.sleep") as sleep:
+        assert client.list_objects() == []
+
+    assert attempts == 2
+    sleep.assert_called_once_with(0.0)
+
+
+def test_retry_after_http_date_is_parsed() -> None:
+    client = AttioClient(api_key="test-key")
+    now = datetime(2026, 8, 8, 12, 0, tzinfo=UTC)
+
+    assert client._retry_delay("Sat, 08 Aug 2026 12:00:05 GMT", now=now) == 5.0

From 80f19cfb03ddbed7865533d76c07bfe12682f443 Mon Sep 17 00:00:00 2001
From: Matthew Slipper <me@matthewslipper.com>
Date: Wed, 19 Aug 2026 04:55:00 +0000
Subject: [PATCH 19/36] refactor: remove vestigial thread key helpers (#1427)

---
 packages/harness-events/src/index.ts      |  2 --
 packages/harness-events/src/thread-key.ts | 15 ---------------
 2 files changed, 17 deletions(-)
 delete mode 100644 packages/harness-events/src/thread-key.ts

diff --git a/packages/harness-events/src/index.ts b/packages/harness-events/src/index.ts
index 9726393d3..019c88b11 100644
--- a/packages/harness-events/src/index.ts
+++ b/packages/harness-events/src/index.ts
@@ -1,5 +1,3 @@
-export { splitThreadKey, normalizeThreadKey } from "./thread-key";
-
 export type JsonValue =
   | null
   | boolean
diff --git a/packages/harness-events/src/thread-key.ts b/packages/harness-events/src/thread-key.ts
deleted file mode 100644
index 2c313028d..000000000
--- a/packages/harness-events/src/thread-key.ts
+++ /dev/null
@@ -1,15 +0,0 @@
-export function splitThreadKey(threadKey: string): { channel: string; threadTs: string } {
-  const parts = threadKey.trim().split(":");
-  if (parts.length === 2 && parts[0] && parts[1]) {
-    return { channel: parts[0], threadTs: parts[1] };
-  }
-  if (parts.length === 3 && parts[1] && parts[2]) {
-    return { channel: parts[1], threadTs: parts[2] };
-  }
-  throw new Error(`Invalid thread key format (expected <channel>:<thread_ts>): ${threadKey}`);
-}
-
-export function normalizeThreadKey(threadKey: string): string {
-  const { channel, threadTs } = splitThreadKey(threadKey);
-  return `${channel}:${threadTs}`;
-}

From 0357221229dbfe14b080562c871b67a770734ed9 Mon Sep 17 00:00:00 2001
From: Daniel Gorrie <dgorrie@tempo.xyz>
Date: Wed, 19 Aug 2026 05:01:25 +0000
Subject: [PATCH 20/36] feat(console): add Slack channel autocomplete (#1408)

* feat(console): add Slack channel autocomplete

* fix(console): allow editing existing Slack permissions

---------

Co-authored-by: Matthew Slipper <me@matthewslipper.com>
---
 .../slack_channel_permission_management.rb    |  13 +-
 .../slack_channel_options_controller.rb       |  38 ++++
 .../slack_channel_autocomplete_controller.js  | 182 ++++++++++++++++++
 .../slack_channel_catalog_provider.rb         |  18 ++
 .../_slack_channel_permissions.html.erb       |  79 +++++---
 services/console/config/routes.rb             |   4 +
 .../slack_channel_options_controller_test.rb  |  69 +++++++
 .../controllers/console_controller_test.rb    |  10 +-
 .../slack_channel_catalog_provider_test.rb    |  22 +++
 9 files changed, 406 insertions(+), 29 deletions(-)
 create mode 100644 services/console/app/controllers/console/slack_channel_options_controller.rb
 create mode 100644 services/console/app/javascript/controllers/slack_channel_autocomplete_controller.js
 create mode 100644 services/console/test/controllers/console/slack_channel_options_controller_test.rb

diff --git a/services/console/app/controllers/concerns/console/slack_channel_permission_management.rb b/services/console/app/controllers/concerns/console/slack_channel_permission_management.rb
index 4edbd7831..af4c7ecf4 100644
--- a/services/console/app/controllers/concerns/console/slack_channel_permission_management.rb
+++ b/services/console/app/controllers/concerns/console/slack_channel_permission_management.rb
@@ -8,10 +8,7 @@ def load_slack_channel_permission_form(owner)
       @slack_channel_catalog = SlackChannelCatalogProvider.fetch
       @slack_channel_names = @slack_channel_catalog.channels.to_h { |channel| [ channel.id, channel.name ] }
       @slack_channel_permissions = owner.slack_channel_permissions.ordered
-      @slack_channel_options = @slack_channel_catalog.channels.map do |channel|
-        label = "##{channel.name} (#{channel.id}) #{channel.private ? "Private" : "Public"}"
-        [ label, channel.id ]
-      end
+      @slack_channel_options_url = slack_channel_options_url(owner)
     end
 
     def update_slack_channel_permissions_from_form(owner, path, preserve_api_managed_direct_messages: false)
@@ -85,5 +82,13 @@ def api_managed_direct_message_rows(owner)
            .select { |permission| permission.channel_id.to_s.start_with?("D") }
            .map(&:as_permission_json)
     end
+
+    def slack_channel_options_url(owner)
+      case owner
+      when Principal then console_principal_slack_channel_options_path(owner.oid)
+      when Role then slack_channel_options_console_role_path(owner.oid)
+      else raise ArgumentError, "unsupported Slack channel permission owner"
+      end
+    end
   end
 end
diff --git a/services/console/app/controllers/console/slack_channel_options_controller.rb b/services/console/app/controllers/console/slack_channel_options_controller.rb
new file mode 100644
index 000000000..7c4c468cd
--- /dev/null
+++ b/services/console/app/controllers/console/slack_channel_options_controller.rb
@@ -0,0 +1,38 @@
+module Console
+  class SlackChannelOptionsController < ApplicationController
+    MAX_RESULTS = 20
+
+    before_action :require_admin
+
+    def index
+      response.headers["Cache-Control"] = "no-store"
+      owner = find_owner
+      result = SlackChannelCatalogProvider.search(
+        query: params[:q],
+        limit: MAX_RESULTS,
+        exclude_ids: owner.slack_channel_permissions.pluck(:channel_id)
+      )
+
+      render json: {
+        options: result.channels.map do |channel|
+          {
+            value: channel.id,
+            label: "##{channel.name}",
+            description: "#{channel.id} · #{channel.private ? "Private" : "Public"}"
+          }
+        end,
+        error: result.error
+      }
+    end
+
+    private
+
+    def find_owner
+      case params[:owner_type]
+      when "principal" then Principal.find_by_oid!(params[:id])
+      when "role" then Role.find_by_oid!(params[:id])
+      else raise ActiveRecord::RecordNotFound
+      end
+    end
+  end
+end
diff --git a/services/console/app/javascript/controllers/slack_channel_autocomplete_controller.js b/services/console/app/javascript/controllers/slack_channel_autocomplete_controller.js
new file mode 100644
index 000000000..7dd048f70
--- /dev/null
+++ b/services/console/app/javascript/controllers/slack_channel_autocomplete_controller.js
@@ -0,0 +1,182 @@
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static targets = ["input", "value", "list", "status", "submit"]
+  static values = { url: String }
+
+  connect() {
+    this.options = []
+    this.activeIndex = -1
+    this.opened = false
+    this.selectedDisplay = null
+    this.updateSubmitState()
+  }
+
+  disconnect() {
+    clearTimeout(this.searchTimer)
+    clearTimeout(this.blurTimer)
+    this.abortController?.abort()
+  }
+
+  open() {
+    clearTimeout(this.blurTimer)
+    this.opened = true
+    if (this.inputTarget.value === this.selectedDisplay) this.inputTarget.select()
+    this.search()
+  }
+
+  input() {
+    this.selectedDisplay = null
+    this.opened = true
+    this.syncManualChannelId()
+    clearTimeout(this.searchTimer)
+    this.searchTimer = setTimeout(() => this.search(), 200)
+  }
+
+  keydown(event) {
+    if (event.key === "ArrowDown") {
+      event.preventDefault()
+      this.moveActive(1)
+    } else if (event.key === "ArrowUp") {
+      event.preventDefault()
+      this.moveActive(-1)
+    } else if (event.key === "Enter" && this.activeIndex >= 0) {
+      event.preventDefault()
+      this.select(this.options[this.activeIndex])
+    } else if (event.key === "Escape") {
+      this.hide()
+    }
+  }
+
+  blur() {
+    this.blurTimer = setTimeout(() => {
+      this.opened = false
+      this.hide()
+    }, 150)
+  }
+
+  async search() {
+    this.abortController?.abort()
+    this.abortController = new AbortController()
+
+    const preservingSelection = this.inputTarget.value === this.selectedDisplay
+    if (!preservingSelection) this.setStatus("Loading channels…")
+
+    const query = preservingSelection ? "" : this.inputTarget.value.trim()
+    this.currentQuery = query
+    const url = new URL(this.urlValue, window.location.origin)
+    url.searchParams.set("q", query)
+
+    try {
+      const response = await fetch(url, {
+        credentials: "same-origin",
+        headers: { "Accept": "application/json" },
+        signal: this.abortController.signal,
+      })
+      const body = await response.json().catch(() => ({}))
+      if (!response.ok) throw new Error(body.error || `Request failed with HTTP ${response.status}`)
+
+      this.options = body.options || []
+      this.renderOptions()
+      if (body.error) {
+        this.setStatus(body.error)
+      } else if (!preservingSelection) {
+        this.setStatus(this.resultStatus())
+      }
+    } catch (error) {
+      if (error.name === "AbortError") return
+      this.options = []
+      this.renderOptions()
+      this.setStatus(error.message || "Could not load Slack channels.", true)
+    }
+  }
+
+  renderOptions() {
+    this.listTarget.replaceChildren()
+    this.activeIndex = -1
+
+    this.options.forEach((option, index) => {
+      const button = document.createElement("button")
+      button.type = "button"
+      button.id = `${this.listTarget.id}_option_${index}`
+      button.className = "block min-h-11 w-full px-3 py-2 text-left transition-colors hover:bg-centaur-500/[0.08] focus:bg-centaur-500/[0.08] focus:outline-none"
+      button.setAttribute("role", "option")
+      button.setAttribute("aria-selected", "false")
+      button.addEventListener("pointerdown", (event) => event.preventDefault())
+      button.addEventListener("click", () => this.select(option))
+
+      const label = document.createElement("div")
+      label.className = "text-sm text-zinc-100"
+      label.textContent = option.label
+      const description = document.createElement("div")
+      description.className = "mt-0.5 text-xs text-zinc-500"
+      description.textContent = option.description
+      button.append(label, description)
+      this.listTarget.append(button)
+    })
+
+    const visible = this.opened && this.options.length > 0
+    this.listTarget.hidden = !visible
+    this.inputTarget.setAttribute("aria-expanded", String(visible))
+  }
+
+  moveActive(delta) {
+    if (this.options.length === 0) return
+    this.activeIndex = (this.activeIndex + delta + this.options.length) % this.options.length
+
+    Array.from(this.listTarget.children).forEach((element, index) => {
+      const active = index === this.activeIndex
+      element.setAttribute("aria-selected", String(active))
+      element.classList.toggle("bg-centaur-500/[0.08]", active)
+      if (active) {
+        this.inputTarget.setAttribute("aria-activedescendant", element.id)
+        element.scrollIntoView({ block: "nearest" })
+      }
+    })
+  }
+
+  select(option) {
+    this.inputTarget.value = `${option.label} (${option.value})`
+    this.valueTarget.value = option.value
+    this.selectedDisplay = this.inputTarget.value
+    this.updateSubmitState()
+    this.setStatus(`Selected ${option.label}.`)
+    this.opened = false
+    this.hide()
+  }
+
+  syncManualChannelId() {
+    const value = this.inputTarget.value.trim().toUpperCase()
+    this.valueTarget.value = /^[CDG][A-Z0-9]{8,}$/.test(value) ? value : ""
+    this.updateSubmitState()
+  }
+
+  updateSubmitState() {
+    const hasInput = this.inputTarget.value.trim() !== ""
+    const hasChannelId = this.valueTarget.value.trim() !== ""
+    this.submitTarget.disabled = hasInput && !hasChannelId
+  }
+
+  resultStatus() {
+    if (this.options.length === 0) return "No matching channels. You can enter a channel ID directly."
+    if (this.options.length === 20) {
+      return this.currentQuery === ""
+        ? "Showing the first 20 channels. Type to search all channels."
+        : "Showing the first 20 matching channels. Keep typing to narrow the results."
+    }
+    return `${this.options.length} matching channel${this.options.length === 1 ? "" : "s"}.`
+  }
+
+  setStatus(message, error = false) {
+    this.statusTarget.textContent = message
+    this.statusTarget.classList.toggle("text-red-300", error)
+    this.statusTarget.classList.toggle("text-zinc-500", !error)
+  }
+
+  hide() {
+    this.listTarget.hidden = true
+    this.inputTarget.setAttribute("aria-expanded", "false")
+    this.inputTarget.removeAttribute("aria-activedescendant")
+    this.activeIndex = -1
+  }
+}
diff --git a/services/console/app/services/slack_channel_catalog_provider.rb b/services/console/app/services/slack_channel_catalog_provider.rb
index 06646fce6..3c2bed9aa 100644
--- a/services/console/app/services/slack_channel_catalog_provider.rb
+++ b/services/console/app/services/slack_channel_catalog_provider.rb
@@ -18,6 +18,24 @@ def fetch
       payload ? deserialize_result(payload) : loading_result
     end
 
+    def search(query:, limit:, exclude_ids: [])
+      result = fetch
+      excluded = Array(exclude_ids).index_with(true)
+      needle = query.to_s.strip.downcase
+      channels = result.channels.reject { |channel| excluded.key?(channel.id) }
+      if needle.present?
+        channels = channels.select do |channel|
+          channel.name.downcase.include?(needle) || channel.id.downcase.include?(needle)
+        end
+      end
+
+      SlackChannelCatalog::Result.new(
+        channels: channels.first(limit),
+        error: result.error,
+        configured: result.configured
+      )
+    end
+
     def refresh(cache_key:)
       config = configuration
       return unless config && cache_key == self.cache_key(**config)
diff --git a/services/console/app/views/console/shared/_slack_channel_permissions.html.erb b/services/console/app/views/console/shared/_slack_channel_permissions.html.erb
index cd2ec4d4d..721f0d309 100644
--- a/services/console/app/views/console/shared/_slack_channel_permissions.html.erb
+++ b/services/console/app/views/console/shared/_slack_channel_permissions.html.erb
@@ -3,14 +3,14 @@
 <% inherited_permissions = local_assigns.fetch(:inherited_permissions, []) %>
 <% api_managed_direct_messages = local_assigns.fetch(:api_managed_direct_messages, false) %>
 <% checkbox_class = "mt-1 h-4 w-4 rounded border-ink-500 bg-ink-800 text-centaur-500 focus:ring-centaur-500" %>
-<% channel_options = @slack_channel_options || [] %>
 <% permissions = @slack_channel_permissions || [] %>
+<% picker_id = dom_id(owner, :slack_channel_picker) %>
 
 <section class="mb-8">
   <div class="mb-4">
     <h2 class="mb-1 text-xs font-semibold uppercase tracking-wider text-zinc-500">Slack Channel Permissions</h2>
   </div>
-  <div class="console-panel">
+  <div class="console-panel overflow-visible">
     <%= form_with model: owner,
                   url: url,
                   method: :patch,
@@ -99,30 +99,61 @@
       <% end %>
 
       <% new_permission = SlackChannelPermission.new(SlackChannelPermission::DEFAULT_ENABLED_ATTRIBUTES) %>
-      <%= form.fields_for :slack_channel_permissions, new_permission do |permission_fields| %>
-        <div class="grid gap-4 border-t border-ink-700 p-5 lg:grid-cols-[minmax(0,1fr)_auto_auto_auto]">
-          <label class="block">
-            <span class="form-label">Add Channel</span>
-            <% if channel_options.any? %>
-              <%= permission_fields.select :channel_id,
-                                           options_for_select([ [ "Select a Slack channel", "" ] ] + channel_options),
-                                           {},
-                                           class: "form-input" %>
-            <% else %>
-              <%= permission_fields.text_field :channel_id, class: "form-input", placeholder: "C0123456789" %>
-            <% end %>
-          </label>
-          <% SlackChannelPermission::PERMISSION_FLAGS.each do |flag| %>
-            <label class="flex items-start gap-3 pt-6">
-              <%= permission_fields.check_box flag.fetch(:attribute), class: checkbox_class %>
-              <span class="text-sm font-medium text-zinc-100"><%= flag.fetch(:label) %></span>
+      <div data-controller="slack-channel-autocomplete"
+           data-slack-channel-autocomplete-url-value="<%= @slack_channel_options_url %>">
+        <%= form.fields_for :slack_channel_permissions, new_permission do |permission_fields| %>
+          <div class="grid gap-4 border-t border-ink-700 p-5 lg:grid-cols-[minmax(0,1fr)_auto_auto_auto]">
+            <label class="block">
+              <span class="form-label">Add Channel</span>
+              <div class="relative">
+                <%= permission_fields.hidden_field :channel_id,
+                                                    data: { slack_channel_autocomplete_target: "value" } %>
+                <%= text_field_tag nil,
+                                   nil,
+                                   id: picker_id,
+                                   class: "form-input",
+                                   placeholder: "Search channels or enter an ID",
+                                   autocomplete: "off",
+                                   role: "combobox",
+                                   aria: {
+                                     autocomplete: "list",
+                                     controls: "#{picker_id}_listbox",
+                                     expanded: "false"
+                                   },
+                                   data: {
+                                     slack_channel_autocomplete_target: "input",
+                                     action: "focus->slack-channel-autocomplete#open input->slack-channel-autocomplete#input keydown->slack-channel-autocomplete#keydown blur->slack-channel-autocomplete#blur"
+                                   } %>
+                <div id="<%= picker_id %>_listbox"
+                     class="absolute z-20 mt-1 max-h-72 w-full overflow-y-auto rounded border border-ink-500 bg-ink-900 shadow-lg"
+                     role="listbox"
+                     hidden
+                     data-slack-channel-autocomplete-target="list"></div>
+                <div class="mt-1 min-h-5 text-xs text-zinc-500"
+                     role="status"
+                     aria-live="polite"
+                     data-slack-channel-autocomplete-target="status"></div>
+                <noscript>
+                  <%= permission_fields.text_field :channel_id,
+                                                   class: "form-input mt-2",
+                                                   placeholder: "C0123456789" %>
+                </noscript>
+              </div>
             </label>
-          <% end %>
-        </div>
-      <% end %>
+            <% SlackChannelPermission::PERMISSION_FLAGS.each do |flag| %>
+              <label class="flex items-start gap-3 pt-6">
+                <%= permission_fields.check_box flag.fetch(:attribute), class: checkbox_class %>
+                <span class="text-sm font-medium text-zinc-100"><%= flag.fetch(:label) %></span>
+              </label>
+            <% end %>
+          </div>
+        <% end %>
 
-      <div class="px-5 pb-5">
-        <%= submit_tag "Save Slack channel permissions", class: "btn-primary" %>
+        <div class="px-5 pb-5">
+          <%= submit_tag "Save Slack channel permissions",
+                         class: "btn-primary disabled:cursor-not-allowed disabled:opacity-50",
+                         data: { slack_channel_autocomplete_target: "submit" } %>
+        </div>
       </div>
     <% end %>
 
diff --git a/services/console/config/routes.rb b/services/console/config/routes.rb
index a445275d0..d418c1c4d 100644
--- a/services/console/config/routes.rb
+++ b/services/console/config/routes.rb
@@ -74,6 +74,8 @@
   namespace :console do
     resources :roles, only: %i[index show new create edit update] do
       member do
+        get "slack_channel_options", to: "slack_channel_options#index",
+            defaults: { owner_type: "role" }, as: :slack_channel_options
         post "grants", to: "roles#grant_secret", as: :grant_secret
         delete "grants/:grant_id", to: "roles#revoke_grant", as: :revoke_grant
         patch "slack_channel_permissions", to: "roles#update_slack_channel_permissions",
@@ -88,6 +90,8 @@
   # and avoid clobbering the console_principal_path helper.
   namespace :console do
     delete "principals/:id",                  to: "principals#destroy", as: :delete_principal
+    get    "principals/:id/slack_channel_options", to: "slack_channel_options#index",
+           defaults: { owner_type: "principal" }, as: :principal_slack_channel_options
     patch  "principals/:id/sandbox_access",   to: "principals#update_sandbox_access", as: :principal_sandbox_access
     patch  "principals/:id/slack_channel_permissions", to: "principals#update_slack_channel_permissions", as: :principal_slack_channel_permissions
     post   "principals/:id/roles",            to: "principals#assign_role",   as: :principal_assign_role
diff --git a/services/console/test/controllers/console/slack_channel_options_controller_test.rb b/services/console/test/controllers/console/slack_channel_options_controller_test.rb
new file mode 100644
index 000000000..35528d719
--- /dev/null
+++ b/services/console/test/controllers/console/slack_channel_options_controller_test.rb
@@ -0,0 +1,69 @@
+require "test_helper"
+
+module Console
+  class SlackChannelOptionsControllerTest < ActionDispatch::IntegrationTest
+    setup do
+      @operator = users(:acme_admin)
+      post login_url, params: { email: @operator.email, password: "password123456" }
+    end
+
+    test "principal options return bounded catalog matches and exclude existing permissions" do
+      principal = principals(:acme_channel)
+      existing = principal.slack_channel_permissions.create!(channel_id: "C0123456789", upload_enabled: true)
+      captured = nil
+      result = SlackChannelCatalog::Result.new(
+        channels: [ SlackChannelCatalog::Channel.new(id: "C1111111111", name: "engineering", private: false) ],
+        error: nil,
+        configured: true
+      )
+
+      search = lambda do |**args|
+        captured = args
+        result
+      end
+      SlackChannelCatalogProvider.stub(:search, search) do
+        get console_principal_slack_channel_options_url(principal.oid), params: { q: "eng" }
+      end
+
+      assert_response :ok
+      assert_equal "no-store", response.headers.fetch("Cache-Control")
+      assert_equal "eng", captured.fetch(:query)
+      assert_equal 20, captured.fetch(:limit)
+      assert_includes captured.fetch(:exclude_ids), existing.channel_id
+      assert_equal(
+        {
+          "options" => [
+            {
+              "value" => "C1111111111",
+              "label" => "#engineering",
+              "description" => "C1111111111 · Public"
+            }
+          ],
+          "error" => nil
+        },
+        response.parsed_body
+      )
+    end
+
+    test "role options use the same lookup endpoint" do
+      role = roles(:acme_infra)
+      result = SlackChannelCatalog::Result.new(channels: [], error: nil, configured: true)
+
+      SlackChannelCatalogProvider.stub(:search, result) do
+        get slack_channel_options_console_role_url(role.oid)
+      end
+
+      assert_response :ok
+      assert_equal [], response.parsed_body.fetch("options")
+    end
+
+    test "non-admins cannot search the catalog" do
+      delete logout_url
+      post login_url, params: { email: users(:member_user).email, password: "password123456" }
+
+      get console_principal_slack_channel_options_url(principals(:acme_channel).oid)
+
+      assert_redirected_to console_threads_path
+    end
+  end
+end
diff --git a/services/console/test/controllers/console_controller_test.rb b/services/console/test/controllers/console_controller_test.rb
index fc2440c1c..139f523b9 100644
--- a/services/console/test/controllers/console_controller_test.rb
+++ b/services/console/test/controllers/console_controller_test.rb
@@ -267,7 +267,8 @@ class ConsoleControllerTest < ActionDispatch::IntegrationTest
     catalog = SlackChannelCatalog::Result.new(
       channels: [
         SlackChannelCatalog::Channel.new(id: "C0123456789", name: "general", private: false),
-        SlackChannelCatalog::Channel.new(id: "G9876543210", name: "private", private: true)
+        SlackChannelCatalog::Channel.new(id: "G9876543210", name: "private", private: true),
+        SlackChannelCatalog::Channel.new(id: "C1111111111", name: "unused", private: false)
       ],
       error: nil,
       configured: true
@@ -280,6 +281,13 @@ class ConsoleControllerTest < ActionDispatch::IntegrationTest
     assert_select "h3", text: "Inherited From Roles"
     assert_select "td", text: /#private/
     assert_select "input[type=checkbox][disabled]", minimum: 3
+    assert_select "input[role=combobox][aria-controls]"
+    assert_select "[data-slack-channel-autocomplete-url-value=?]",
+                  console_principal_slack_channel_options_path(principal.oid)
+    assert_select "input[type=submit][data-slack-channel-autocomplete-target=submit]:not([disabled])",
+                  value: "Save Slack channel permissions"
+    assert_select "select[name$='[channel_id]']", count: 0
+    assert_select "body", text: /#unused/, count: 0
   end
 
   test "credentials table combines id, shows status, and links to detail" do
diff --git a/services/console/test/services/slack_channel_catalog_provider_test.rb b/services/console/test/services/slack_channel_catalog_provider_test.rb
index 8609b76b6..0b746361f 100644
--- a/services/console/test/services/slack_channel_catalog_provider_test.rb
+++ b/services/console/test/services/slack_channel_catalog_provider_test.rb
@@ -149,6 +149,28 @@ class SlackChannelCatalogProviderTest < ActiveJob::TestCase
     end
   end
 
+  test "search returns bounded matches and excludes assigned channels" do
+    result = SlackChannelCatalog::Result.new(
+      channels: [
+        SlackChannelCatalog::Channel.new(id: "C000000001", name: "engineering", private: false),
+        SlackChannelCatalog::Channel.new(id: "C000000002", name: "engineering-private", private: true),
+        SlackChannelCatalog::Channel.new(id: "C000000003", name: "general", private: false)
+      ],
+      error: nil,
+      configured: true
+    )
+
+    SlackChannelCatalogProvider.stub(:fetch, result) do
+      matches = SlackChannelCatalogProvider.search(
+        query: "ENGINEER",
+        limit: 1,
+        exclude_ids: [ "C000000001" ]
+      )
+
+      assert_equal [ "C000000002" ], matches.channels.map(&:id)
+    end
+  end
+
   private
 
   def with_catalog_env(&)

From 80f69e4056be40f1cd6a708d47b3fe2817395cad Mon Sep 17 00:00:00 2001
From: Aaditya Krishnamohan <aaditya@blockhouse.capital>
Date: Wed, 19 Aug 2026 05:09:22 +0000
Subject: [PATCH 21/36] fix(workflows): Linear searchIssues takes `term`, not
 `query` (#1335)

#832 fixed this argument in tools/productivity/linear/readonly.py and pinned it
with a regression test. There is a second, independent copy of the same client
at workflows/linear/readonly.py that was never touched -- it still builds:

    query SearchIssues($query: String!, ...) { searchIssues(query: $query, ...) }

while the copy upstream tests builds `searchIssues(term: $term, ...)`. The two
disagree on the argument name, and only one of them is pinned.

This copy ships: services/api-rs/Dockerfile copies workflows/ into the image,
WORKFLOW_DIRS points at it, and LinearReadonlyClient is exported from
workflows/linear/__init__.py. Nothing calls search_issues on this path today, so
it is latent rather than a live break -- which is why it went unnoticed.

The test is a mirror of the one #832 added, asserting the same three things
against this client. The absence of a test here is the reason the fix did not
propagate; #1300 now runs workflows/tests in CI, so it is gated from here on.
Verified it fails against the unfixed client and passes against the fixed one.

Scope is the argument name only. The two copies still differ in their selection
sets -- the tools copy also selects `project` and `projectMilestone` -- and this
change leaves that alone rather than quietly widening the payload of a query
nobody calls yet.

Co-authored-by: aaditya krishnamohan <201291201+aadityakbh@users.noreply.github.com>
---
 workflows/linear/readonly.py            |  6 ++--
 workflows/tests/test_linear_readonly.py | 41 +++++++++++++++++++++++++
 2 files changed, 44 insertions(+), 3 deletions(-)
 create mode 100644 workflows/tests/test_linear_readonly.py

diff --git a/workflows/linear/readonly.py b/workflows/linear/readonly.py
index f7aca685e..2c4b1463b 100644
--- a/workflows/linear/readonly.py
+++ b/workflows/linear/readonly.py
@@ -374,8 +374,8 @@ def users(self, limit: int = 100) -> list[dict[str, Any]]:
     def search_issues(self, query_str: str, limit: int = 25) -> list[dict[str, Any]]:
         """Search issues by text."""
         query = """
-        query SearchIssues($query: String!, $first: Int!, $after: String) {
-            searchIssues(query: $query, first: $first, after: $after) {
+        query SearchIssues($term: String!, $first: Int!, $after: String) {
+            searchIssues(term: $term, first: $first, after: $after) {
                 nodes {
                     id
                     identifier
@@ -393,7 +393,7 @@ def search_issues(self, query_str: str, limit: int = 25) -> list[dict[str, Any]]
         return self._connection_nodes(
             query,
             connection_path=("searchIssues",),
-            variables={"query": query_str},
+            variables={"term": query_str},
             limit=limit,
         )
 
diff --git a/workflows/tests/test_linear_readonly.py b/workflows/tests/test_linear_readonly.py
new file mode 100644
index 000000000..0b830164a
--- /dev/null
+++ b/workflows/tests/test_linear_readonly.py
@@ -0,0 +1,41 @@
+"""Tests for the workflows-side Linear read-only GraphQL helpers.
+
+This mirrors tools/productivity/linear/test_readonly.py. The two clients are
+independent copies of the same code, and the `term:` fix landed in only one of
+them -- so the invariant is pinned on both sides now, or they drift again.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from workflows.linear.readonly import LinearReadonlyClient
+
+
+class RecordingReadonlyClient(LinearReadonlyClient):
+    def __init__(self) -> None:
+        self.calls: list[dict[str, Any]] = []
+
+    def _query(self, query: str, variables: dict[str, Any] | None = None) -> dict[str, Any]:
+        self.calls.append({"query": query, "variables": variables})
+        return {
+            "searchIssues": {
+                "nodes": [{"identifier": "ENG-1", "title": "Search result"}],
+                "pageInfo": {"hasNextPage": False, "endCursor": None},
+            }
+        }
+
+
+def test_search_issues_uses_linear_term_argument():
+    # `searchIssues` names its search string `term` and requires it. `query` was
+    # the argument of `issueSearch`, the endpoint Linear deprecated in favour of
+    # this one; passing it here fails GraphQL validation, which Linear returns as
+    # an HTTP 400.
+    client = RecordingReadonlyClient()
+
+    result = client.search_issues("auth", limit=1)
+
+    assert result == [{"identifier": "ENG-1", "title": "Search result"}]
+    assert "searchIssues(term: $term" in client.calls[0]["query"]
+    assert "query:" not in client.calls[0]["query"]
+    assert client.calls[0]["variables"] == {"term": "auth", "first": 1, "after": None}

From a48f2f7756af5157e071fb9d668cfcb2ba409a24 Mon Sep 17 00:00:00 2001
From: Matthew Slipper <me@matthewslipper.com>
Date: Wed, 19 Aug 2026 05:11:45 +0000
Subject: [PATCH 22/36] ci: skip Cloudflare deploy without credentials (#1428)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: José Ribeiro <32641844+ribeirojose@users.noreply.github.com>
---
 .github/workflows/docs.yml | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index d023d0979..4d1da58c5 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -61,12 +61,8 @@ jobs:
       - name: Build docs
         run: npm run build
 
-      - name: Skip Cloudflare deploy
-        if: ${{ env.CLOUDFLARE_ACCOUNT_ID == '' || env.CLOUDFLARE_API_TOKEN == '' }}
-        run: echo "Cloudflare credentials are not configured; docs build completed without deployment."
-
       - name: Deploy
-        if: github.event_name != 'pull_request'
+        if: ${{ github.event_name != 'pull_request' && env.CLOUDFLARE_ACCOUNT_ID != '' && env.CLOUDFLARE_API_TOKEN != '' }}
         uses: cloudflare/wrangler-action@ebbaa1584979971c8614a24965b4405ff95890e0 # v4.0.0
         with:
           apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}

From 453eb82b4b21beb9b73ff8483872fef174d8ba80 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Wed, 19 Aug 2026 05:14:05 +0000
Subject: [PATCH 23/36] chore(deps): bump the ruby-dependencies group across 1
 directory with 4 updates (#1403)

* chore(deps): bump the ruby-dependencies group across 1 directory with 4 updates

Bumps the ruby-dependencies group with 4 updates in the /services/console directory: [rails-paradedb](https://github.com/paradedb/rails-paradedb), [bootsnap](https://github.com/rails/bootsnap), [thruster](https://github.com/basecamp/thruster) and [selenium-webdriver](https://github.com/SeleniumHQ/selenium).


Updates `rails-paradedb` from 0.7.0 to 0.12.0
- [Release notes](https://github.com/paradedb/rails-paradedb/releases)
- [Changelog](https://github.com/paradedb/rails-paradedb/blob/main/CHANGELOG.md)
- [Commits](https://github.com/paradedb/rails-paradedb/compare/v0.7.0...v0.12.0)

Updates `bootsnap` from 1.24.6 to 1.25.0
- [Release notes](https://github.com/rails/bootsnap/releases)
- [Changelog](https://github.com/rails/bootsnap/blob/main/CHANGELOG.md)
- [Commits](https://github.com/rails/bootsnap/compare/v1.24.6...v1.25.0)

Updates `thruster` from 0.1.23 to 0.1.25
- [Changelog](https://github.com/basecamp/thruster/blob/main/CHANGELOG.md)
- [Commits](https://github.com/basecamp/thruster/compare/v0.1.23...v0.1.25)

Updates `selenium-webdriver` from 4.46.0 to 4.47.0
- [Release notes](https://github.com/SeleniumHQ/selenium/releases)
- [Changelog](https://github.com/SeleniumHQ/selenium/blob/trunk/rb/CHANGES)
- [Commits](https://github.com/SeleniumHQ/selenium/compare/selenium-4.46.0...selenium-4.47.0)

---
updated-dependencies:
- dependency-name: bootsnap
  dependency-version: 1.25.0
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: ruby-dependencies
- dependency-name: rails-paradedb
  dependency-version: 0.12.0
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: ruby-dependencies
- dependency-name: selenium-webdriver
  dependency-version: 4.47.0
  dependency-type: direct:development
  update-type: version-update:semver-minor
  dependency-group: ruby-dependencies
- dependency-name: thruster
  dependency-version: 0.1.25
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: ruby-dependencies
...

Signed-off-by: dependabot[bot] <support@github.com>

* fix: keep ParadeDB Rails integration compatible

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Matthew Slipper <me@matthewslipper.com>
---
 .github/dependabot.yml        |  5 +++++
 services/console/Gemfile      |  3 ++-
 services/console/Gemfile.lock | 26 +++++++++++++-------------
 3 files changed, 20 insertions(+), 14 deletions(-)

diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index b8684503a..fe63cd8e5 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -27,6 +27,11 @@ updates:
       prefix: chore
       include: scope
     open-pull-requests-limit: 5
+    ignore:
+      # rails-paradedb 0.10+ requires ParadeDB 0.25+, while Console runs 0.23.
+      - dependency-name: rails-paradedb
+        versions:
+          - ">= 0.10.0"
     groups:
       ruby-dependencies:
         patterns:
diff --git a/services/console/Gemfile b/services/console/Gemfile
index 501856ea8..9b0432fc5 100644
--- a/services/console/Gemfile
+++ b/services/console/Gemfile
@@ -8,7 +8,8 @@ gem "propshaft"
 gem "tailwindcss-rails", "4.6.0"
 # Use pg as the database for Active Record
 gem "pg", "~> 1.5"
-# Preserve ParadeDB indexes in Rails schema dumps and migrations.
+# Preserve ParadeDB indexes in Rails schema dumps and migrations. Versions 0.10+
+# require ParadeDB 0.25+, while Console currently runs ParadeDB 0.23.
 gem "rails-paradedb", "0.7.0", require: "parade_db"
 # Opaque ID encoding (bigint <-> short string) for externally-exposed IDs
 gem "sqids", "~> 0.2"
diff --git a/services/console/Gemfile.lock b/services/console/Gemfile.lock
index 49af28d27..dee19df45 100644
--- a/services/console/Gemfile.lock
+++ b/services/console/Gemfile.lock
@@ -82,8 +82,8 @@ GEM
     bcrypt (3.1.22)
     bigdecimal (4.1.2)
     bindex (0.8.1)
-    bootsnap (1.24.6)
-      msgpack (~> 1.2)
+    bootsnap (1.25.0)
+      msgpack (~> 1.5)
     brakeman (8.0.6)
       racc
     builder (3.3.0)
@@ -107,7 +107,7 @@ GEM
       irb (~> 1.10)
       reline (>= 0.3.8)
     drb (2.2.3)
-    erb (6.0.6)
+    erb (6.0.7)
     erubi (1.13.1)
     et-orbi (1.4.1)
       tzinfo
@@ -131,7 +131,7 @@ GEM
       actionpack (>= 6.0.0)
       activesupport (>= 6.0.0)
       railties (>= 6.0.0)
-    io-console (0.8.2)
+    io-console (0.9.2)
     irb (1.18.0)
       pp (>= 0.6.0)
       prism (>= 1.3.0)
@@ -172,7 +172,7 @@ GEM
       drb (~> 2.0)
       prism (~> 1.5)
     minitest-mock (5.27.0)
-    msgpack (1.8.3)
+    msgpack (1.8.4)
     net-imap (0.6.6)
       date
       net-protocol
@@ -220,7 +220,7 @@ GEM
       nio4r (~> 2.0)
     raabro (1.5.0)
     racc (1.8.1)
-    rack (3.2.6)
+    rack (3.2.7)
     rack-session (2.1.2)
       base64 (>= 0.1.0)
       rack (>= 3.0.0)
@@ -265,7 +265,7 @@ GEM
       zeitwerk (~> 2.6)
     rainbow (3.1.1)
     rake (13.4.2)
-    rbs (4.1.2)
+    rbs (4.1.3)
       logger
       prism (>= 1.6.0)
       tsort
@@ -275,7 +275,7 @@ GEM
       rbs (>= 4.0.0)
       tsort
     regexp_parser (2.12.0)
-    reline (0.6.3)
+    reline (0.7.0)
       io-console (~> 0.5)
     request_store (1.7.0)
       rack (>= 1.4)
@@ -314,7 +314,7 @@ GEM
       logger
     rubyzip (3.4.1)
     securerandom (0.4.1)
-    selenium-webdriver (4.46.0)
+    selenium-webdriver (4.47.0)
       base64 (~> 0.2)
       logger (~> 1.4)
       rexml (~> 3.2, >= 3.2.5)
@@ -357,10 +357,10 @@ GEM
     tailwindcss-ruby (4.3.3-x86_64-linux-gnu)
     tailwindcss-ruby (4.3.3-x86_64-linux-musl)
     thor (1.5.0)
-    thruster (0.1.23)
-    thruster (0.1.23-aarch64-linux)
-    thruster (0.1.23-arm64-darwin)
-    thruster (0.1.23-x86_64-linux)
+    thruster (0.1.25)
+    thruster (0.1.25-aarch64-linux)
+    thruster (0.1.25-arm64-darwin)
+    thruster (0.1.25-x86_64-linux)
     timeout (0.6.1)
     tsort (0.2.0)
     turbo-rails (2.0.23)

From 4fdbc48d8a85825600e1552b1ba0138c2754b69c Mon Sep 17 00:00:00 2001
From: vijith-reddy <vijith@tempo.xyz>
Date: Wed, 19 Aug 2026 05:17:14 +0000
Subject: [PATCH 24/36] feat: customize workflow Slack messages (#1401)

* feat: add server-side Slack app DMs

* revert: remove standalone Slack app DM tool

* feat: customize workflow Slack messages

* refactor: simplify workflow Slack method signature

---------

Co-authored-by: Vijith Bheemireddi <vijith@khvkmhft4w.tail388b2e.ts.net>
Co-authored-by: Matthew Slipper <me@matthewslipper.com>
---
 docs/pages/extend/workflows-v2.mdx            | 11 +++++-
 .../crates/centaur-workflows/src/lib.rs       | 18 +++++++++
 .../tests/test_workflow_host.py               | 37 +++++++++++++++++++
 3 files changed, 65 insertions(+), 1 deletion(-)

diff --git a/docs/pages/extend/workflows-v2.mdx b/docs/pages/extend/workflows-v2.mdx
index d0bddd89d..3ae98983b 100644
--- a/docs/pages/extend/workflows-v2.mdx
+++ b/docs/pages/extend/workflows-v2.mdx
@@ -98,11 +98,20 @@ be wrapped in `ctx.step(...)` so the result is checkpointed:
 async def handler(inp: dict, ctx: WorkflowContext) -> dict:
     posted = await ctx.step(
         "post_summary",
-        lambda: ctx.post_to_slack(inp["channel"], inp["summary"]),
+        lambda: ctx.post_to_slack(
+            inp["channel"],
+            inp["summary"],
+            username="Summary Bot",
+            icon_emoji=":memo:",
+        ),
     )
     return {"posted": posted}
 ```
 
+`username` and `icon_emoji` are optional. They customize the Slack app identity
+for that message and require the app installation to grant
+`chat:write.customize`. Omitting them preserves the app's default identity.
+
 ### Make agent turns explicit
 
 Use `ctx.agent_turn(...)` when the workflow needs an agent sandbox:
diff --git a/services/api-rs/crates/centaur-workflows/src/lib.rs b/services/api-rs/crates/centaur-workflows/src/lib.rs
index b12fc6f10..57668046c 100644
--- a/services/api-rs/crates/centaur-workflows/src/lib.rs
+++ b/services/api-rs/crates/centaur-workflows/src/lib.rs
@@ -4149,6 +4149,12 @@ fn python_slack_message_payload(
     if let Some(blocks) = args.get("blocks") {
         payload["blocks"] = blocks.clone();
     }
+    if let Some(username) = args.get("username").and_then(Value::as_str) {
+        payload["username"] = json!(username);
+    }
+    if let Some(icon_emoji) = args.get("icon_emoji").and_then(Value::as_str) {
+        payload["icon_emoji"] = json!(icon_emoji);
+    }
     if let Some(no_attribution) = args.get("no_attribution").and_then(Value::as_bool) {
         payload["no_attribution"] = json!(no_attribution);
     }
@@ -4818,6 +4824,8 @@ mod tests {
                 "reply_broadcast": true,
                 "unfurl_links": true,
                 "unfurl_media": true,
+                "username": "The Date Goblin",
+                "icon_emoji": ":female_mage:",
             }),
         );
 
@@ -4828,6 +4836,16 @@ mod tests {
         assert_eq!(payload["reply_broadcast"], json!(true));
         assert_eq!(payload["unfurl_links"], json!(true));
         assert_eq!(payload["unfurl_media"], json!(true));
+        assert_eq!(payload["username"], json!("The Date Goblin"));
+        assert_eq!(payload["icon_emoji"], json!(":female_mage:"));
+    }
+
+    #[test]
+    fn python_slack_payload_omits_custom_identity_by_default() {
+        let payload = python_slack_message_payload("C123", "hello", "client-1", &json!({}));
+
+        assert!(payload.get("username").is_none());
+        assert!(payload.get("icon_emoji").is_none());
     }
 
     #[test]
diff --git a/services/workflow-python/tests/test_workflow_host.py b/services/workflow-python/tests/test_workflow_host.py
index f894a1a5b..1c743f1a1 100644
--- a/services/workflow-python/tests/test_workflow_host.py
+++ b/services/workflow-python/tests/test_workflow_host.py
@@ -86,6 +86,8 @@ async def request(self, payload):
                 "run_id": "run-child",
                 "created": True,
             }
+        if message_type == "ctx.post_to_slack":
+            return {"channel": payload["channel"], "ts": "1710000000.000100"}
         if message_type == "ctx.sleep":
             return {"slept": True}
         if message_type == "ctx.event.wait":
@@ -433,6 +435,41 @@ def test_start_workflow_enqueues_durable_child_with_idempotency_key(self) -> Non
             ],
         )
 
+    def test_post_to_slack_sends_optional_custom_identity(self) -> None:
+        host = load_workflow_host()
+        rpc = RequestRpc()
+        ctx = host.WorkflowContext(
+            rpc,
+            run_id="run-123",
+            task_id="task-456",
+            workflow_name="sample",
+        )
+
+        result = asyncio.run(
+            ctx.post_to_slack(
+                "U12345678",
+                "Your date is approaching.",
+                username="The Date Goblin",
+                icon_emoji=":female_mage:",
+            )
+        )
+
+        self.assertEqual(result["channel"], "U12345678")
+        self.assertEqual(
+            rpc.requests,
+            [
+                {
+                    "type": "ctx.post_to_slack",
+                    "channel": "U12345678",
+                    "text": "Your date is approaching.",
+                    "args": {
+                        "username": "The Date Goblin",
+                        "icon_emoji": ":female_mage:",
+                    },
+                }
+            ],
+        )
+
     def test_create_pool_retries_transient_connection_failure(self) -> None:
         host = load_workflow_host()
         calls = []

From c133ee7ec91e569a89f7cafb4f0240b7a8c001c0 Mon Sep 17 00:00:00 2001
From: ecejas <ecejasp@gmail.com>
Date: Wed, 19 Aug 2026 05:18:50 +0000
Subject: [PATCH 25/36] feat: support Standard Webhooks authentication (#1380)

Co-authored-by: ecejas <15933097+ecejas@users.noreply.github.com>
---
 docs/pages/extend/workflows.mdx               |  33 +++-
 docs/pages/reference/configuration.mdx        |   2 +-
 services/api-rs/Cargo.lock                    |  26 +++
 services/api-rs/Cargo.toml                    |   1 +
 .../crates/centaur-api-server/Cargo.toml      |   1 +
 .../crates/centaur-api-server/src/routes.rs   | 152 ++++++++++++++++++
 .../crates/centaur-workflows/src/lib.rs       |  53 +++++-
 .../api-rs/rfcs/0003-python-workflow-host.md  |   2 +-
 8 files changed, 265 insertions(+), 5 deletions(-)

diff --git a/docs/pages/extend/workflows.mdx b/docs/pages/extend/workflows.mdx
index c9f5ed1a2..f9919fc39 100644
--- a/docs/pages/extend/workflows.mdx
+++ b/docs/pages/extend/workflows.mdx
@@ -331,8 +331,37 @@ that content type is listed in `allowed_content_types`.
 Webhook requests do not use Centaur API keys. The API verifies the provider
 signature before creating workflow state. `HmacAuth.github(...)` verifies
 `X-Hub-Signature-256`; a plain `HmacAuth(...)` can be used for other
-SHA-256 HMAC providers. During local development or for trusted internal
-routes, `auth="none"` is allowed.
+SHA-256 HMAC providers that sign the raw request body. During local development
+or for trusted internal routes, `auth="none"` is allowed.
+
+For providers that implement the [Standard Webhooks
+specification](https://www.standardwebhooks.com/), use the explicit
+`standard_webhooks` auth type:
+
+```python
+WEBHOOKS = [
+    {
+        "slug": "feed-ingest",
+        "provider": "feed-provider",
+        "auth": {
+            "type": "standard_webhooks",
+            "secret_ref": "FEED_WEBHOOK_SECRET",
+        },
+        "trigger_key": {"type": "header", "header": "webhook-id"},
+        "allowed_methods": ["POST"],
+        "allowed_content_types": ["application/json"],
+    }
+]
+```
+
+Set `FEED_WEBHOOK_SECRET` in the API deployment to the provider's signing
+secret (normally a `whsec_`-prefixed, base64-encoded value). Centaur requires
+the `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers, verifies
+the `v1` signature over the exact raw body, supports space-separated signatures
+for key rotation, and rejects timestamps outside a five-minute window. Using
+`webhook-id` as the trigger key also gives retries the same durable workflow
+identity. Auth schemes are selected by `auth.type`; Centaur does not infer one
+from the headers.
 
 The workflow receives input in this shape:
 
diff --git a/docs/pages/reference/configuration.mdx b/docs/pages/reference/configuration.mdx
index abf705192..7237842b4 100644
--- a/docs/pages/reference/configuration.mdx
+++ b/docs/pages/reference/configuration.mdx
@@ -257,7 +257,7 @@ Sandbox entrypoint and wrappers:
 | `WORKFLOW_RECONCILE_INTERVAL_S`, `WORKFLOW_RESUSPEND_BACKOFF_S` | `api.extraEnv`. | Workflow claim/reclaim cadence. |
 | `WORKFLOW_SCHEDULE_TICK_INTERVAL_S`, `WORKFLOW_SCHEDULE_CATCHUP_LIMIT`, `WORKFLOW_SCHEDULE_MISFIRE_GRACE_S` | `api.extraEnv`. | Scheduled workflow timing and catch-up behavior. |
 | `MY_THREAD_KEY`, `<WORKFLOW_NAME>_THREAD_KEY`, `<WORKFLOW_NAME>_SLACK_CHANNEL` | Workflow-specific env. | Fallback thread/channel targets for workflow agent steps. |
-| `<WEBHOOK_SECRET_REF>` | API env or Secret named by a workflow `WebhookSpec`. | HMAC secret for public workflow webhooks, for example `GITHUB_WEBHOOK_SECRET`. |
+| `<WEBHOOK_SECRET_REF>` | API env or Secret named by a workflow `WebhookSpec`. | Signing secret or bearer token for public workflow webhooks, for example `GITHUB_WEBHOOK_SECRET` or a Standard Webhooks `whsec_...` value. |
 
 Slack ETL workflows:
 
diff --git a/services/api-rs/Cargo.lock b/services/api-rs/Cargo.lock
index 8678d3087..93123af92 100644
--- a/services/api-rs/Cargo.lock
+++ b/services/api-rs/Cargo.lock
@@ -715,6 +715,12 @@ version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4c7f02d4ea65f2c1853089ffd8d2787bdbc63de2f0d29dedbcf8ccdfa0ccd4cf"
 
+[[package]]
+name = "base64"
+version = "0.21.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9d297deb1925b89f2ccc13d7635fa0714f12c87adce1c75356b39ca9b7178567"
+
 [[package]]
 name = "base64"
 version = "0.22.1"
@@ -904,6 +910,7 @@ dependencies = [
  "serde_yaml",
  "sha2 0.11.0",
  "sqlx",
+ "standardwebhooks",
  "subtle",
  "thiserror 2.0.20",
  "time",
@@ -2235,6 +2242,12 @@ dependencies = [
  "digest 0.11.3",
 ]
 
+[[package]]
+name = "hmac-sha256"
+version = "1.1.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ec9d92d097f4749b64e8cc33d924d9f40a2d4eb91402b458014b781f5733d60f"
+
 [[package]]
 name = "home"
 version = "0.5.12"
@@ -4953,6 +4966,19 @@ version = "1.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
 
+[[package]]
+name = "standardwebhooks"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "747264efdc09640f0a838c03b220810a0b89930cb50e3a30f19379d1a90284ac"
+dependencies = [
+ "base64 0.21.7",
+ "hmac-sha256",
+ "http 1.4.2",
+ "thiserror 2.0.19",
+ "time",
+]
+
 [[package]]
 name = "static_assertions"
 version = "1.1.0"
diff --git a/services/api-rs/Cargo.toml b/services/api-rs/Cargo.toml
index 6631c1129..2d330b35f 100644
--- a/services/api-rs/Cargo.toml
+++ b/services/api-rs/Cargo.toml
@@ -87,6 +87,7 @@ metrics-exporter-prometheus = { version = "0.18.3", default-features = false }
 sqlx = { version = "0.8.6", default-features = false, features = ["derive", "json", "macros", "migrate", "postgres", "runtime-tokio-rustls", "time"] }
 strum = { version = "0.28", features = ["derive"] }
 subtle = "2"
+standardwebhooks = "1.0.1"
 test-case = "3.3.1"
 thiserror = "2"
 url = "2"
diff --git a/services/api-rs/crates/centaur-api-server/Cargo.toml b/services/api-rs/crates/centaur-api-server/Cargo.toml
index 62b07a426..84df7a41d 100644
--- a/services/api-rs/crates/centaur-api-server/Cargo.toml
+++ b/services/api-rs/crates/centaur-api-server/Cargo.toml
@@ -35,6 +35,7 @@ serde.workspace = true
 serde_json.workspace = true
 serde_yaml.workspace = true
 sha2.workspace = true
+standardwebhooks.workspace = true
 subtle.workspace = true
 sqlx.workspace = true
 thiserror.workspace = true
diff --git a/services/api-rs/crates/centaur-api-server/src/routes.rs b/services/api-rs/crates/centaur-api-server/src/routes.rs
index 80e91314e..1c6e9e20f 100644
--- a/services/api-rs/crates/centaur-api-server/src/routes.rs
+++ b/services/api-rs/crates/centaur-api-server/src/routes.rs
@@ -215,6 +215,7 @@ const REDACTED_WEBHOOK_HEADERS: &[&str] = &[
     "x-hub-signature",
     "x-hub-signature-256",
     "x-slack-signature",
+    "webhook-signature",
     "stripe-signature",
 ];
 
@@ -3828,6 +3829,9 @@ fn verify_webhook_auth(
             headers,
             raw_body,
         ),
+        WorkflowWebhookAuth::StandardWebhooks { secret_ref } => {
+            verify_standard_webhook_signature(secret_ref, headers, raw_body)
+        }
         WorkflowWebhookAuth::Hmac {
             secret_ref,
             signature_header,
@@ -3845,6 +3849,33 @@ fn verify_webhook_auth(
     }
 }
 
+fn verify_standard_webhook_signature(
+    secret_ref: &str,
+    headers: &HeaderMap,
+    raw_body: &[u8],
+) -> Result<(), ApiError> {
+    let secret = env::var(secret_ref).map_err(|_| {
+        ApiError::Internal(format!(
+            "webhook auth secret {secret_ref} is not configured"
+        ))
+    })?;
+    let secret = secret.trim();
+    let encoded_secret = secret.strip_prefix("whsec_").unwrap_or(secret);
+    if encoded_secret.is_empty() {
+        return Err(ApiError::Internal(format!(
+            "webhook auth secret {secret_ref} is not valid Standard Webhooks key material"
+        )));
+    }
+    let webhook = standardwebhooks::Webhook::new(secret).map_err(|_| {
+        ApiError::Internal(format!(
+            "webhook auth secret {secret_ref} is not valid Standard Webhooks key material"
+        ))
+    })?;
+    webhook
+        .verify(raw_body, headers)
+        .map_err(|_| ApiError::Unauthorized("invalid webhook signature".to_owned()))
+}
+
 fn verify_hmac_signature(
     signature_header: &str,
     signature_prefix: &str,
@@ -3896,6 +3927,7 @@ fn signature_header_name(auth: &WorkflowWebhookAuth) -> Option<&str> {
     match auth {
         WorkflowWebhookAuth::None | WorkflowWebhookAuth::Bearer { .. } => None,
         WorkflowWebhookAuth::Github { .. } => Some("X-Hub-Signature-256"),
+        WorkflowWebhookAuth::StandardWebhooks { .. } => Some("webhook-signature"),
         WorkflowWebhookAuth::Hmac {
             signature_header, ..
         } => Some(signature_header),
@@ -4261,6 +4293,35 @@ mod webhook_tests {
         assert_eq!(safe, json!({"x-test-delivery": "delivery-1"}));
     }
 
+    #[test]
+    fn redacts_standard_webhooks_signature_header() {
+        let mut headers = HeaderMap::new();
+        headers.insert("webhook-signature", "v1,c2lnbmF0dXJl".parse().unwrap());
+        headers.insert("webhook-id", "msg_test".parse().unwrap());
+        headers.insert("webhook-timestamp", "1700000000".parse().unwrap());
+        let spec = WorkflowWebhookSpec {
+            slug: "unit".to_owned(),
+            provider: None,
+            auth: WorkflowWebhookAuth::StandardWebhooks {
+                secret_ref: "TEST_WEBHOOK_SECRET".to_owned(),
+            },
+            trigger_key: None,
+            allowed_methods: vec!["POST".to_owned()],
+            allowed_content_types: vec!["application/json".to_owned()],
+            filter: None,
+        };
+
+        let safe = safe_webhook_headers(&headers, &spec);
+
+        assert_eq!(
+            safe,
+            json!({
+                "webhook-id": "msg_test",
+                "webhook-timestamp": "1700000000"
+            })
+        );
+    }
+
     #[test]
     fn derives_header_trigger_key() {
         let mut headers = HeaderMap::new();
@@ -4305,6 +4366,97 @@ mod webhook_tests {
         .unwrap();
     }
 
+    fn standard_webhook_headers(
+        secret: &str,
+        message_id: &str,
+        timestamp: i64,
+        raw_body: &[u8],
+    ) -> HeaderMap {
+        let encoded_secret = secret.strip_prefix("whsec_").unwrap_or(secret);
+        let key = general_purpose::STANDARD.decode(encoded_secret).unwrap();
+        let mut signed_content = Vec::new();
+        signed_content.extend_from_slice(message_id.as_bytes());
+        signed_content.push(b'.');
+        signed_content.extend_from_slice(timestamp.to_string().as_bytes());
+        signed_content.push(b'.');
+        signed_content.extend_from_slice(raw_body);
+        let mut mac = Hmac::<Sha256>::new_from_slice(&key).unwrap();
+        mac.update(&signed_content);
+        let signature = general_purpose::STANDARD.encode(mac.finalize().into_bytes());
+
+        let mut headers = HeaderMap::new();
+        headers.insert("webhook-id", message_id.parse().unwrap());
+        headers.insert("webhook-timestamp", timestamp.to_string().parse().unwrap());
+        headers.insert(
+            "webhook-signature",
+            format!("v2,ignored v1,AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA= v1,{signature}")
+                .parse()
+                .unwrap(),
+        );
+        headers
+    }
+
+    #[test]
+    fn verifies_standard_webhooks_signature() {
+        let raw_body = br#"{"hello":"signed"}"#;
+        let secret_ref = "CENTRAUR_TEST_STANDARD_WEBHOOK_SECRET";
+        let secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";
+        let timestamp = OffsetDateTime::now_utc().unix_timestamp();
+        unsafe {
+            env::set_var(secret_ref, secret);
+        }
+        let headers = standard_webhook_headers(secret, "msg_test", timestamp, raw_body);
+
+        verify_standard_webhook_signature(secret_ref, &headers, raw_body).unwrap();
+    }
+
+    #[test]
+    fn rejects_invalid_or_stale_standard_webhooks_signature() {
+        let raw_body = br#"{"hello":"signed"}"#;
+        let secret_ref = "CENTRAUR_TEST_STANDARD_WEBHOOK_SECRET_REJECT";
+        let secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";
+        unsafe {
+            env::set_var(secret_ref, secret);
+        }
+
+        let timestamp = OffsetDateTime::now_utc().unix_timestamp();
+        let headers = standard_webhook_headers(secret, "msg_test", timestamp, raw_body);
+        let error =
+            verify_standard_webhook_signature(secret_ref, &headers, br#"{"hello":"tampered"}"#)
+                .unwrap_err();
+        assert!(matches!(error, ApiError::Unauthorized(_)));
+
+        let stale_headers = standard_webhook_headers(secret, "msg_test", timestamp - 301, raw_body);
+        let error =
+            verify_standard_webhook_signature(secret_ref, &stale_headers, raw_body).unwrap_err();
+        assert!(matches!(error, ApiError::Unauthorized(_)));
+    }
+
+    #[test]
+    fn malformed_or_empty_standard_webhooks_secret_is_internal_error() {
+        let secret_ref = "CENTRAUR_TEST_STANDARD_WEBHOOK_SECRET_INVALID";
+        unsafe {
+            env::set_var(secret_ref, "whsec_not-base64");
+        }
+        let headers = standard_webhook_headers(
+            "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw",
+            "msg_test",
+            OffsetDateTime::now_utc().unix_timestamp(),
+            b"{}",
+        );
+
+        let error = verify_standard_webhook_signature(secret_ref, &headers, b"{}").unwrap_err();
+
+        assert!(matches!(error, ApiError::Internal(_)));
+
+        unsafe {
+            env::set_var(secret_ref, "whsec_");
+        }
+        let error = verify_standard_webhook_signature(secret_ref, &headers, b"{}").unwrap_err();
+
+        assert!(matches!(error, ApiError::Internal(_)));
+    }
+
     fn webhook_filter(value: Value) -> WebhookFilter {
         serde_json::from_value(value).unwrap()
     }
diff --git a/services/api-rs/crates/centaur-workflows/src/lib.rs b/services/api-rs/crates/centaur-workflows/src/lib.rs
index 57668046c..c00b6de15 100644
--- a/services/api-rs/crates/centaur-workflows/src/lib.rs
+++ b/services/api-rs/crates/centaur-workflows/src/lib.rs
@@ -452,6 +452,9 @@ pub enum WorkflowWebhookAuth {
     Github {
         secret_ref: String,
     },
+    StandardWebhooks {
+        secret_ref: String,
+    },
     Bearer {
         secret_ref: String,
     },
@@ -1267,7 +1270,9 @@ fn normalize_webhook(webhook: &mut RegisteredWorkflowWebhook) -> Result<(), Work
                 ));
             }
         }
-        WorkflowWebhookAuth::Github { secret_ref } | WorkflowWebhookAuth::Bearer { secret_ref } => {
+        WorkflowWebhookAuth::Github { secret_ref }
+        | WorkflowWebhookAuth::StandardWebhooks { secret_ref }
+        | WorkflowWebhookAuth::Bearer { secret_ref } => {
             if secret_ref.trim().is_empty() {
                 return Err(WorkflowRuntimeError::BadRequest(format!(
                     "workflow webhook {:?} auth requires secret_ref",
@@ -5105,6 +5110,52 @@ mod tests {
         assert_eq!(all[1].key.as_deref(), Some("repository.full_name"));
     }
 
+    #[test]
+    fn discovery_metadata_preserves_standard_webhooks_auth() {
+        let payload: PythonWorkflowDiscoveryPayload = serde_json::from_value(json!({
+            "workflows": [
+                {
+                    "workflow_name": "feed_ingest",
+                    "source_path": "workflows/feed_ingest.py",
+                    "webhooks": [
+                        {
+                            "workflow_name": "feed_ingest",
+                            "source_path": "workflows/feed_ingest.py",
+                            "spec": {
+                                "slug": "feed-ingest",
+                                "auth": {
+                                    "type": "standard_webhooks",
+                                    "secret_ref": "FEED_WEBHOOK_SECRET"
+                                },
+                                "trigger_key": {
+                                    "type": "header",
+                                    "header": "webhook-id"
+                                }
+                            }
+                        }
+                    ]
+                }
+            ],
+        }))
+        .unwrap();
+
+        let metadata = metadata_from_discovery_payload(payload);
+        let registry =
+            build_webhook_registry(&metadata, &WorkflowEnablement::allowlist("feed_ingest"))
+                .unwrap();
+        let webhook = registry.get("feed-ingest").unwrap();
+
+        assert!(matches!(
+            &webhook.spec.auth,
+            WorkflowWebhookAuth::StandardWebhooks { secret_ref }
+                if secret_ref == "FEED_WEBHOOK_SECRET"
+        ));
+        assert!(matches!(
+            &webhook.spec.trigger_key,
+            Some(WorkflowWebhookTriggerKey::Header { header }) if header == "webhook-id"
+        ));
+    }
+
     fn webhook_with_filter(filter: Value) -> RegisteredWorkflowWebhook {
         RegisteredWorkflowWebhook {
             workflow_name: "github_issue_triage".to_owned(),
diff --git a/services/api-rs/rfcs/0003-python-workflow-host.md b/services/api-rs/rfcs/0003-python-workflow-host.md
index f7b1dfa00..f74e68293 100644
--- a/services/api-rs/rfcs/0003-python-workflow-host.md
+++ b/services/api-rs/rfcs/0003-python-workflow-host.md
@@ -312,7 +312,7 @@ The route should:
 
 - look up the registered slug
 - enforce allowed methods and content types
-- verify HMAC, GitHub HMAC, or bearer auth
+- verify raw-body HMAC, GitHub HMAC, Standard Webhooks, or bearer auth
 - redact sensitive headers
 - parse JSON or form payloads
 - preserve the Python-compatible input envelope

From 93115cfcb4e5675cdac88e07f39c46c0a2942623 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jos=C3=A9=20Ribeiro?= <me@joseribeiro.dev>
Date: Wed, 19 Aug 2026 05:23:57 +0000
Subject: [PATCH 26/36] fix(slack): upgrade API emulator (#1152)

fix: upgrade Slack API emulator
---
 pnpm-lock.yaml                                | 23 ++++---------------
 services/slackbotv2/package.json              |  2 +-
 .../slackbotv2/test/chat-sdk-emulate.test.ts  |  6 +++--
 3 files changed, 10 insertions(+), 21 deletions(-)

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 7c19d83b6..2e06abc7d 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -253,8 +253,8 @@ importers:
         specifier: ^7.0.0-dev.20260512.1
         version: 7.0.0-dev.20260616.1
       emulate:
-        specifier: ^0.5.0
-        version: 0.5.0(hono@4.12.25)
+        specifier: ^0.9.0
+        version: 0.9.0
       typescript:
         specifier: ^6.0.3
         version: 6.0.3
@@ -392,12 +392,6 @@ packages:
     peerDependencies:
       graphql: ^0.8.0 || ^0.9.0 || ^0.10.0 || ^0.11.0 || ^0.12.0 || ^0.13.0 || ^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0
 
-  '@hono/node-server@1.19.14':
-    resolution: {integrity: sha512-GwtvgtXxnWsucXvbQXkRgqksiH2Qed37H9xHZocE5sA3N8O8O8/8FA3uclQXxXVzc9XBZuEOMK7+r02FmSpHtw==}
-    engines: {node: '>=18.14.1'}
-    peerDependencies:
-      hono: ^4
-
   '@jridgewell/sourcemap-codec@1.5.5':
     resolution: {integrity: sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==}
 
@@ -1044,8 +1038,8 @@ packages:
   ee-first@1.1.1:
     resolution: {integrity: sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==}
 
-  emulate@0.5.0:
-    resolution: {integrity: sha512-2LrOE8sqa1ITQ1aRR3kZhAhOCNz8hu+Kea9oBKdG/jEK6I/RYlMgHbsvQmbTTtr+nx6+fOOWkL6wqvfLeF5vuA==}
+  emulate@0.9.0:
+    resolution: {integrity: sha512-wgOFQSrjAt0NqPDnYUFyCcCwAVw01aNS3M24SZ2C5ViLQW8ECi0qIyUsW+y2uvflBD48JFqomB+jRox+ktKK/w==}
     hasBin: true
 
   encodeurl@2.0.0:
@@ -2113,10 +2107,6 @@ snapshots:
     dependencies:
       graphql: 17.0.0
 
-  '@hono/node-server@1.19.14(hono@4.12.25)':
-    dependencies:
-      hono: 4.12.25
-
   '@jridgewell/sourcemap-codec@1.5.5': {}
 
   '@linear/sdk@76.0.0(graphql@17.0.0)':
@@ -2830,14 +2820,11 @@ snapshots:
 
   ee-first@1.1.1: {}
 
-  emulate@0.5.0(hono@4.12.25):
+  emulate@0.9.0:
     dependencies:
-      '@hono/node-server': 1.19.14(hono@4.12.25)
       commander: 14.0.3
       picocolors: 1.1.1
       yaml: 2.9.0
-    transitivePeerDependencies:
-      - hono
 
   encodeurl@2.0.0: {}
 
diff --git a/services/slackbotv2/package.json b/services/slackbotv2/package.json
index 655eed33f..ec13b6517 100644
--- a/services/slackbotv2/package.json
+++ b/services/slackbotv2/package.json
@@ -25,7 +25,7 @@
     "@types/bun": "^1.3.13",
     "@types/node": "^25.7.0",
     "@typescript/native-preview": "^7.0.0-dev.20260512.1",
-    "emulate": "^0.5.0",
+    "emulate": "^0.9.0",
     "typescript": "^6.0.3"
   }
 }
diff --git a/services/slackbotv2/test/chat-sdk-emulate.test.ts b/services/slackbotv2/test/chat-sdk-emulate.test.ts
index 3232e316d..36644b29f 100644
--- a/services/slackbotv2/test/chat-sdk-emulate.test.ts
+++ b/services/slackbotv2/test/chat-sdk-emulate.test.ts
@@ -5197,7 +5197,7 @@ describe('slackbotv2', () => {
     bot = createTestBot({ triggerBotAllowlist: ['UOTHERBOT'] })
     codexApi.reset()
     slackApi.reset()
-    const richBotMessage = await postUserMessage('')
+    const richBotMessage = await postUserMessage('attachment-only event placeholder')
     const richBotWaits: Promise<unknown>[] = []
     const richBotResponse = await bot.app.request(
       '/api/webhooks/slack',
@@ -5240,7 +5240,7 @@ describe('slackbotv2', () => {
 
     bot = createTestBot()
     codexApi.reset()
-    const deniedRichBotMessage = await postUserMessage('')
+    const deniedRichBotMessage = await postUserMessage('attachment-only event placeholder')
     const deniedRichBotWaits: Promise<unknown>[] = []
     const deniedRichBotResponse = await bot.app.request(
       '/api/webhooks/slack',
@@ -6445,6 +6445,8 @@ async function sendWebResponse(res: ServerResponse, response: Response): Promise
   res.statusCode = response.status
   res.statusMessage = response.statusText
   response.headers.forEach((value, key) => {
+    // The proxy buffers the body, so let Node choose framing for the buffered response.
+    if (key === 'transfer-encoding') return
     res.setHeader(key, value)
   })
   if (response.body === null || response.status === 204) {

From 86b14a0ec5b9c869b64041c020f262f2482be4a3 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Wed, 19 Aug 2026 21:07:59 +0000
Subject: [PATCH 27/36] chore(deps): bump rails-paradedb from 0.7.0 to 0.9.0 in
 /services/console in the ruby-dependencies group (#1430)

chore(deps): bump rails-paradedb

Bumps the ruby-dependencies group in /services/console with 1 update: rails-paradedb.


Updates `rails-paradedb` from 0.7.0 to 0.9.0

---
updated-dependencies:
- dependency-name: rails-paradedb
  dependency-version: 0.9.0
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: ruby-dependencies
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 services/console/Gemfile      | 2 +-
 services/console/Gemfile.lock | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/services/console/Gemfile b/services/console/Gemfile
index 9b0432fc5..c880b88fb 100644
--- a/services/console/Gemfile
+++ b/services/console/Gemfile
@@ -10,7 +10,7 @@ gem "tailwindcss-rails", "4.6.0"
 gem "pg", "~> 1.5"
 # Preserve ParadeDB indexes in Rails schema dumps and migrations. Versions 0.10+
 # require ParadeDB 0.25+, while Console currently runs ParadeDB 0.23.
-gem "rails-paradedb", "0.7.0", require: "parade_db"
+gem "rails-paradedb", "0.9.0", require: "parade_db"
 # Opaque ID encoding (bigint <-> short string) for externally-exposed IDs
 gem "sqids", "~> 0.2"
 # JSON Schema validation for jsonb config columns
diff --git a/services/console/Gemfile.lock b/services/console/Gemfile.lock
index dee19df45..85c9a8ae4 100644
--- a/services/console/Gemfile.lock
+++ b/services/console/Gemfile.lock
@@ -249,7 +249,7 @@ GEM
     rails-html-sanitizer (1.7.1)
       loofah (~> 2.25, >= 2.25.2)
       nokogiri (>= 1.15.7, != 1.16.7, != 1.16.6, != 1.16.5, != 1.16.4, != 1.16.3, != 1.16.2, != 1.16.1, != 1.16.0.rc1, != 1.16.0)
-    rails-paradedb (0.7.0)
+    rails-paradedb (0.9.0)
       activerecord (>= 7.2, < 9)
       activesupport (>= 7.2, < 9)
       pg (~> 1.5)
@@ -419,7 +419,7 @@ DEPENDENCIES
   propshaft
   puma (>= 5.0)
   rails (~> 8.1.3)
-  rails-paradedb (= 0.7.0)
+  rails-paradedb (= 0.9.0)
   rubocop-rails-omakase
   ruby-vips (~> 2.2)
   selenium-webdriver

From 9d287f7500d364736fa91a8670c50b4c44fe0c70 Mon Sep 17 00:00:00 2001
From: Matthew Slipper <me@matthewslipper.com>
Date: Wed, 19 Aug 2026 21:21:58 +0000
Subject: [PATCH 28/36] refactor(slack): own nanocodex rollout policy (#1437)

* refactor(slack): own nanocodex rollout policy

* chore(chart): bump version to 0.1.121

* refactor(slack): simplify rollout selection check

* docs: correct nanocodex rollout visibility

* docs(chart): describe nanocodex rollout value
---
 contrib/chart/Chart.yaml                      |   2 +-
 contrib/chart/templates/apirs.yaml            |   2 -
 contrib/chart/templates/slackbotv2.yaml       |   5 +-
 contrib/chart/values.schema.json              |   5 +
 contrib/chart/values.yaml                     |   7 +-
 docs/pages/reference/configuration.mdx        |   2 +-
 .../crates/centaur-api-server/src/args.rs     |  41 ----
 .../crates/centaur-api-server/src/main.rs     |   3 +-
 .../crates/centaur-api-server/src/routes.rs   | 207 +-----------------
 .../crates/centaur-api-server/src/types.rs    |  11 -
 .../crates/centaur-session-runtime/src/lib.rs |  14 --
 services/slackbotv2/src/harness-rollout.ts    |  42 ++++
 services/slackbotv2/src/index.ts              |  26 ++-
 services/slackbotv2/src/server.ts             |  14 ++
 services/slackbotv2/src/session-api.ts        |  84 +++----
 services/slackbotv2/src/types.ts              |  10 +-
 .../slackbotv2/test/chat-sdk-emulate.test.ts  |  58 ++---
 .../slackbotv2/test/harness-rollout.test.ts   |  93 ++++++++
 services/slackbotv2/test/session-api.test.ts  |  47 ++--
 19 files changed, 294 insertions(+), 379 deletions(-)
 create mode 100644 services/slackbotv2/src/harness-rollout.ts
 create mode 100644 services/slackbotv2/test/harness-rollout.test.ts

diff --git a/contrib/chart/Chart.yaml b/contrib/chart/Chart.yaml
index d783fe669..6b0f1be4a 100644
--- a/contrib/chart/Chart.yaml
+++ b/contrib/chart/Chart.yaml
@@ -2,7 +2,7 @@ apiVersion: v2
 name: centaur
 description: Helm chart for the trusted Centaur control plane
 type: application
-version: 0.1.122
+version: 0.1.123
 appVersion: "0.1.0"
 dependencies:
   - name: connect
diff --git a/contrib/chart/templates/apirs.yaml b/contrib/chart/templates/apirs.yaml
index 3f49ff7af..38502ee09 100644
--- a/contrib/chart/templates/apirs.yaml
+++ b/contrib/chart/templates/apirs.yaml
@@ -254,8 +254,6 @@ spec:
 {{- end }}
             - name: RUN_MIGRATIONS
               value: {{ .Values.apiRs.runMigrations | quote }}
-            - name: SESSION_CODEX_NANOCODEX_ROLLOUT_PERCENT
-              value: {{ .Values.apiRs.codexNanocodexRolloutPercent | quote }}
             - name: IRON_CONTROL_SYNC_INFRA_SECRETS
               value: {{ .Values.apiRs.syncInfraSecrets | quote }}
             - name: RUST_LOG
diff --git a/contrib/chart/templates/slackbotv2.yaml b/contrib/chart/templates/slackbotv2.yaml
index 0242b1290..02cb12680 100644
--- a/contrib/chart/templates/slackbotv2.yaml
+++ b/contrib/chart/templates/slackbotv2.yaml
@@ -43,10 +43,11 @@ spec:
             - name: CENTAUR_API_URL
               value: {{ printf "http://%s:%v" $apiRsName .Values.apiRs.port | quote }}
             # New threads without an explicit --claude/--amp/--codex/
-            # --nanocodex flag run the deployment's default harness. api-rs
-            # applies any configured Codex/Nanocodex rollout.
+            # --nanocodex flag run the deployment's default harness.
             - name: SLACKBOTV2_DEFAULT_HARNESS
               value: {{ .Values.sandbox.harnessEngine | quote }}
+            - name: SLACKBOTV2_CODEX_NANOCODEX_ROLLOUT_PERCENT
+              value: {{ .Values.slackbotv2.codexNanocodexRolloutPercent | quote }}
             - name: SLACK_BOT_TOKEN
               valueFrom:
                 secretKeyRef:
diff --git a/contrib/chart/values.schema.json b/contrib/chart/values.schema.json
index 4b66d6859..d0b539b36 100644
--- a/contrib/chart/values.schema.json
+++ b/contrib/chart/values.schema.json
@@ -408,6 +408,11 @@
       "type": "object",
       "properties": {
         "mcpPublicUrl": { "type": "string" },
+        "codexNanocodexRolloutPercent": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100
+        },
         "responseMetadataMode": {
           "type": "string",
           "enum": ["first", "always", "never"]
diff --git a/contrib/chart/values.yaml b/contrib/chart/values.yaml
index 9e270efd1..ee0027cb6 100644
--- a/contrib/chart/values.yaml
+++ b/contrib/chart/values.yaml
@@ -400,10 +400,6 @@ apiRs:
     tag: latest
     pullPolicy: Always
   port: 8080
-  # Sticky percentage of session requests for Codex assigned to Nanocodex.
-  # The API hashes the thread key once and persists the resolved harness on the
-  # session. Set to 0 to keep new Codex requests on Codex.
-  codexNanocodexRolloutPercent: 50
   # Public/local MCP endpoint advertised through OAuth protected-resource
   # metadata. Empty falls back to slackbotv2.mcpPublicUrl.
   mcpPublicUrl: ""
@@ -536,6 +532,9 @@ slackbotv2:
   # Join newly-created public channels after subscribed channel_created events.
   # Requires the Slack app to grant channels:read and channels:join.
   autoJoinCreatedChannels: false
+  # Sticky percentage of otherwise-default Codex Slack threads assigned to
+  # Nanocodex. A non-default model selection bypasses the rollout.
+  codexNanocodexRolloutPercent: 0
   # Append model, harness, and reasoning effort to the first live streamed
   # Slack assistant response, every response, or no responses. Independent of
   # the optional Console link below.
diff --git a/docs/pages/reference/configuration.mdx b/docs/pages/reference/configuration.mdx
index 7237842b4..3215050ff 100644
--- a/docs/pages/reference/configuration.mdx
+++ b/docs/pages/reference/configuration.mdx
@@ -167,7 +167,7 @@ Execution tuning:
 | `SLACKBOT_EXTERNAL_ORG_ALLOWLIST` | `slackbot.extraEnv`. | Slack team ids allowed for external org handoff. |
 | `SLACKBOTV2_AUTO_JOIN_CREATED_CHANNELS` | `slackbotv2.autoJoinCreatedChannels`. | Joins newly-created public channels after subscribed `channel_created` events. Requires `channels:read` and `channels:join`. Defaults to `false`. |
 | `SLACKBOTV2_DEFAULT_HARNESS` | `sandbox.harnessEngine`. | Base harness for new Slack threads without an explicit flag or channel default. |
-| `SESSION_CODEX_NANOCODEX_ROLLOUT_PERCENT` | `apiRs.codexNanocodexRolloutPercent`. | Percentage of API session requests for Codex assigned to Nanocodex. Assignment is deterministic by thread key and persisted as the session harness. The API response and structured `session_harness_rollout_resolved` log identify the experiment and cohort; session and execution metadata retain the assignment for later analysis. Slack keeps the cohort unobtrusive by showing `Codex*` in the first response footer. Defaults to `50`; set to `0` to keep new Codex requests on Codex. |
+| `SLACKBOTV2_CODEX_NANOCODEX_ROLLOUT_PERCENT` | `slackbotv2.codexNanocodexRolloutPercent`. | Percentage of otherwise-default Codex Slack threads assigned to Nanocodex. Assignment is deterministic by thread key and recorded in session and execution metadata. Selecting a non-default model bypasses the rollout. When response metadata is enabled, Slack shows the resolved harness name. Defaults to `0`; increase it to enroll new Codex Slack threads. |
 | `SLACKBOTV2_CHANNEL_DEFAULTS` | `slackbotv2.channelDefaults`. | Per-channel default harness / model / provider / reasoning as a JSON object keyed by Slack conversation id, where each value is an object of optional `harness`/`model`/`provider`/`reasoning` fields (same vocabulary as the inline flags, so `harness: claude`, `provider: bedrock`, and Claude model aliases like `opus` all work), e.g. `{"C0ENG":{"harness":"claude","model":"opus","reasoning":"high"},"C0TRIAGE":{"reasoning":"low"}}`. A model is only meaningful within a harness, so name the harness alongside it. Applied when a message in that channel carries no explicit/sticky per-thread flag (below such a flag, above the deployment/baked default) and forwarded onto the harness input line so it takes effect; setting the harness restarts a thread onto it like a `--claude`/`--codex` flag. `reasoning` affects the Codex and Nanocodex harnesses. Malformed JSON and unrecognized field values are logged and ignored. |
 | `SLACK_TEAM_ID` | `slackbot.extraEnv`. | Workspace team ID (e.g. `T01ABCD2EFG`) used to rewrite `https://*.slack.com/archives/...` URLs in final-delivery messages into native `slack://channel?team=...` deep links that open in the Slack app. Leave unset to keep archive URLs unchanged. |
 | `COMMIT_SHA` | Build/deploy env. | Commit shown in Slackbot metadata. |
diff --git a/services/api-rs/crates/centaur-api-server/src/args.rs b/services/api-rs/crates/centaur-api-server/src/args.rs
index 86393ce6e..3cb05d99d 100644
--- a/services/api-rs/crates/centaur-api-server/src/args.rs
+++ b/services/api-rs/crates/centaur-api-server/src/args.rs
@@ -115,10 +115,6 @@ impl Args {
         Duration::from_secs(self.server.shutdown_execution_drain_timeout_secs)
     }
 
-    pub(crate) fn codex_nanocodex_rollout_percent(&self) -> u8 {
-        self.server.codex_nanocodex_rollout_percent
-    }
-
     pub(crate) fn execution_adoption_interval(&self) -> Option<Duration> {
         (self.server.execution_adoption_interval_secs > 0)
             .then(|| Duration::from_secs(self.server.execution_adoption_interval_secs))
@@ -474,16 +470,6 @@ pub(crate) struct ServerArgs {
     pub(crate) bind_addr: SocketAddr,
     #[arg(long, env = "RUN_MIGRATIONS", default_value_t = false)]
     pub(crate) run_migrations: bool,
-    /// Percentage of sessions requesting Codex that are assigned to
-    /// Nanocodex. The assignment is deterministic by thread key and the
-    /// resolved harness is persisted on the session.
-    #[arg(
-        long = "session-codex-nanocodex-rollout-percent",
-        env = "SESSION_CODEX_NANOCODEX_ROLLOUT_PERCENT",
-        default_value_t = 0,
-        value_parser = clap::value_parser!(u8).range(0..=100)
-    )]
-    codex_nanocodex_rollout_percent: u8,
     /// How long shutdown waits for in-flight executions to finish before
     /// releasing their stdout-owner leases for adoption by a peer. Keep
     /// below the pod's terminationGracePeriodSeconds (35s in the chart) so
@@ -2304,33 +2290,6 @@ mod tests {
         assert_eq!(args.sandbox.k8s_context.as_deref(), Some("kind-test"));
     }
 
-    #[test]
-    fn parses_codex_nanocodex_rollout_percent() {
-        let args = Args::try_parse_from([
-            "centaur-api-server",
-            "--database-url",
-            "postgres://postgres:postgres@localhost/centaur",
-            "--session-codex-nanocodex-rollout-percent",
-            "50",
-        ])
-        .unwrap();
-
-        assert_eq!(args.codex_nanocodex_rollout_percent(), 50);
-    }
-
-    #[test]
-    fn rejects_invalid_codex_nanocodex_rollout_percent() {
-        let result = Args::try_parse_from([
-            "centaur-api-server",
-            "--database-url",
-            "postgres://postgres:postgres@localhost/centaur",
-            "--session-codex-nanocodex-rollout-percent",
-            "101",
-        ]);
-
-        assert!(result.is_err());
-    }
-
     #[test]
     fn execution_adoption_rescans_every_fifteen_seconds_by_default() {
         let args = Args::try_parse_from([
diff --git a/services/api-rs/crates/centaur-api-server/src/main.rs b/services/api-rs/crates/centaur-api-server/src/main.rs
index 74b9cbb94..f567778c0 100644
--- a/services/api-rs/crates/centaur-api-server/src/main.rs
+++ b/services/api-rs/crates/centaur-api-server/src/main.rs
@@ -26,8 +26,7 @@ async fn main() -> Result<(), ServerError> {
         "starting centaur api-rs server"
     );
 
-    let app_state = AppState::unready(api_auth)
-        .with_codex_nanocodex_rollout_percent(args.codex_nanocodex_rollout_percent());
+    let app_state = AppState::unready(api_auth);
     let app = build_router_with_app_state(app_state.clone());
     let shutdown_state = app_state.clone();
     let drain_timeout = args.shutdown_execution_drain_timeout();
diff --git a/services/api-rs/crates/centaur-api-server/src/routes.rs b/services/api-rs/crates/centaur-api-server/src/routes.rs
index 1c6e9e20f..3816f1f8e 100644
--- a/services/api-rs/crates/centaur-api-server/src/routes.rs
+++ b/services/api-rs/crates/centaur-api-server/src/routes.rs
@@ -27,7 +27,7 @@ use axum::{
     routing::{any, get, post},
 };
 use base64::{Engine as _, engine::general_purpose};
-use centaur_session_core::{ChatDestination, HarnessType, ThreadKey};
+use centaur_session_core::{ChatDestination, ThreadKey};
 use centaur_session_runtime::{
     ExecuteSessionInput, HarnessConflictPolicy, SandboxRuntime, SessionPrincipalRegistrar,
     SessionRuntime, thread_trace_id, thread_trace_parent_span_id,
@@ -61,10 +61,10 @@ use crate::{
     types::{
         AppendMessagesRequest, AppendMessagesResponse, CreateSessionRequest, CreateSessionResponse,
         DiscordThreadContext, EmitWorkflowEventRequest, EventsQuery, ExecuteSessionRequest,
-        ExecuteSessionResponse, GithubThreadContext, HarnessAssignment,
-        InterruptSessionExecutionRequest, InterruptSessionExecutionResponse, LinearThreadContext,
-        ListWorkflowRunsQuery, OnHarnessConflict, SessionContextResponse, SessionSseEvent,
-        SlackThreadContext, stream_error_sse,
+        ExecuteSessionResponse, GithubThreadContext, InterruptSessionExecutionRequest,
+        InterruptSessionExecutionResponse, LinearThreadContext, ListWorkflowRunsQuery,
+        OnHarnessConflict, SessionContextResponse, SessionSseEvent, SlackThreadContext,
+        stream_error_sse,
     },
 };
 
@@ -72,7 +72,6 @@ use crate::{
 pub struct AppState {
     initialized: Arc<RwLock<Option<AppRuntimeState>>>,
     metrics: PrometheusHandle,
-    codex_nanocodex_rollout_percent: u8,
     auth: ApiAuthConfig,
 }
 
@@ -89,16 +88,10 @@ impl AppState {
         Self {
             initialized: Arc::new(RwLock::new(None)),
             metrics: prometheus_handle().expect("failed to initialize Prometheus metrics recorder"),
-            codex_nanocodex_rollout_percent: 0,
             auth,
         }
     }
 
-    pub fn with_codex_nanocodex_rollout_percent(mut self, percent: u8) -> Self {
-        self.codex_nanocodex_rollout_percent = percent;
-        self
-    }
-
     pub fn ready(
         runtime: SessionRuntime,
         workflows: Option<WorkflowRuntime>,
@@ -626,45 +619,8 @@ async fn create_or_get_session(
     Json(request): Json<CreateSessionRequest>,
 ) -> Result<Json<CreateSessionResponse>, ApiError> {
     let thread_key = ThreadKey::try_from(raw_thread_key)?;
-    let requested_harness = request.harness_type;
+    let harness_type = request.harness_type;
     let runtime = state.runtime()?;
-    let existing_rollout_harness = if requested_harness == HarnessType::Codex {
-        runtime
-            .existing_session_harness(&thread_key)
-            .await?
-            .filter(|harness| matches!(harness, HarnessType::Codex | HarnessType::Nanocodex))
-    } else {
-        None
-    };
-    let harness_type = existing_rollout_harness.clone().unwrap_or_else(|| {
-        rollout_harness_for_thread(
-            &thread_key,
-            &requested_harness,
-            state.codex_nanocodex_rollout_percent,
-        )
-    });
-    let harness_assignment = codex_nanocodex_assignment(
-        &requested_harness,
-        &harness_type,
-        state.codex_nanocodex_rollout_percent,
-    );
-    tracing::info!(
-        component = "api_server",
-        event = "session_harness_rollout_resolved",
-        thread_key = %thread_key,
-        requested_harness = %requested_harness,
-        resolved_harness = %harness_type,
-        ab_test = harness_assignment.is_some(),
-        ab_test_experiment = harness_assignment
-            .as_ref()
-            .map_or("", |assignment| assignment.experiment),
-        ab_test_cohort = harness_assignment
-            .as_ref()
-            .map_or("", |assignment| assignment.cohort.as_ref()),
-        existing_rollout_harness_preserved = existing_rollout_harness.is_some(),
-        codex_nanocodex_rollout_percent = state.codex_nanocodex_rollout_percent,
-        "resolved requested session harness"
-    );
     let on_harness_conflict = match request.on_harness_conflict {
         Some(OnHarnessConflict::Restart) => HarnessConflictPolicy::Restart,
         Some(OnHarnessConflict::Reject) | None => HarnessConflictPolicy::Reject,
@@ -674,165 +630,16 @@ async fn create_or_get_session(
             &thread_key,
             &harness_type,
             request.persona_id.as_deref(),
-            session_metadata_with_harness_assignment(request.metadata, harness_assignment.as_ref()),
+            request.metadata,
             on_harness_conflict,
         )
         .await?;
     Ok(Json(CreateSessionResponse {
         session: outcome.session,
         harness_switched: outcome.harness_switched,
-        harness_assignment,
     }))
 }
 
-const CODEX_NANOCODEX_AB_EXPERIMENT: &str = "codex_nanocodex_ab";
-
-fn codex_nanocodex_assignment(
-    requested_harness: &HarnessType,
-    cohort: &HarnessType,
-    rollout_percent: u8,
-) -> Option<HarnessAssignment> {
-    (*requested_harness == HarnessType::Codex && (1..100).contains(&rollout_percent)).then(|| {
-        HarnessAssignment {
-            experiment: CODEX_NANOCODEX_AB_EXPERIMENT,
-            requested_harness: requested_harness.clone(),
-            cohort: cohort.clone(),
-            rollout_percent,
-        }
-    })
-}
-
-fn session_metadata_with_harness_assignment(
-    metadata: Option<Value>,
-    assignment: Option<&HarnessAssignment>,
-) -> Option<Value> {
-    let Some(assignment) = assignment else {
-        return metadata;
-    };
-    let mut metadata = metadata.unwrap_or_else(|| json!({}));
-    if let Value::Object(object) = &mut metadata {
-        object.insert(
-            "harness_assignment".to_owned(),
-            json!({
-                "experiment": assignment.experiment,
-                "requested_harness": assignment.requested_harness,
-                "cohort": assignment.cohort,
-                "rollout_percent": assignment.rollout_percent,
-            }),
-        );
-    }
-    Some(metadata)
-}
-
-fn rollout_harness_for_thread(
-    thread_key: &ThreadKey,
-    requested_harness: &HarnessType,
-    nanocodex_percent: u8,
-) -> HarnessType {
-    if *requested_harness != HarnessType::Codex || nanocodex_percent == 0 {
-        return requested_harness.clone();
-    }
-    if nanocodex_percent >= 100 {
-        return HarnessType::Nanocodex;
-    }
-
-    let digest = Sha256::digest(thread_key.as_str().as_bytes());
-    let bucket = u32::from_be_bytes([digest[0], digest[1], digest[2], digest[3]]);
-    let threshold = (u64::from(nanocodex_percent) * (u64::from(u32::MAX) + 1)) / 100;
-    if u64::from(bucket) < threshold {
-        HarnessType::Nanocodex
-    } else {
-        HarnessType::Codex
-    }
-}
-
-#[cfg(test)]
-mod harness_rollout_tests {
-    use super::*;
-
-    #[test]
-    fn codex_rollout_is_sticky_and_split_by_thread_key() {
-        let codex_thread = ThreadKey::try_from("slack:C1:1700000000.000100".to_owned()).unwrap();
-        let nanocodex_thread =
-            ThreadKey::try_from("slack:C1:1700000000.000104".to_owned()).unwrap();
-
-        assert_eq!(
-            rollout_harness_for_thread(&codex_thread, &HarnessType::Codex, 50),
-            HarnessType::Codex
-        );
-        assert_eq!(
-            rollout_harness_for_thread(&nanocodex_thread, &HarnessType::Codex, 50),
-            HarnessType::Nanocodex
-        );
-        assert_eq!(
-            rollout_harness_for_thread(&nanocodex_thread, &HarnessType::Codex, 50),
-            HarnessType::Nanocodex
-        );
-    }
-
-    #[test]
-    fn codex_rollout_honors_boundaries_and_other_harnesses() {
-        let thread_key = ThreadKey::try_from("cli:rollout-boundaries".to_owned()).unwrap();
-
-        assert_eq!(
-            rollout_harness_for_thread(&thread_key, &HarnessType::Codex, 0),
-            HarnessType::Codex
-        );
-        assert_eq!(
-            rollout_harness_for_thread(&thread_key, &HarnessType::Codex, 100),
-            HarnessType::Nanocodex
-        );
-        assert_eq!(
-            rollout_harness_for_thread(&thread_key, &HarnessType::ClaudeCode, 50),
-            HarnessType::ClaudeCode
-        );
-        assert_eq!(
-            rollout_harness_for_thread(&thread_key, &HarnessType::Nanocodex, 50),
-            HarnessType::Nanocodex
-        );
-    }
-
-    #[test]
-    fn codex_rollout_is_balanced_across_many_thread_keys() {
-        let nanocodex = (0..10_000)
-            .filter(|index| {
-                let thread_key = ThreadKey::try_from(format!("cli:rollout-{index}")).unwrap();
-                rollout_harness_for_thread(&thread_key, &HarnessType::Codex, 50)
-                    == HarnessType::Nanocodex
-            })
-            .count();
-
-        assert!(
-            (4_900..=5_100).contains(&nanocodex),
-            "nanocodex={nanocodex}"
-        );
-    }
-
-    #[test]
-    fn codex_rollout_assignment_is_explicit_and_persistable() {
-        let assignment =
-            codex_nanocodex_assignment(&HarnessType::Codex, &HarnessType::Nanocodex, 50).unwrap();
-        let metadata = session_metadata_with_harness_assignment(
-            Some(json!({"source": "slackbotv2"})),
-            Some(&assignment),
-        )
-        .unwrap();
-
-        assert_eq!(assignment.experiment, CODEX_NANOCODEX_AB_EXPERIMENT);
-        assert_eq!(assignment.cohort, HarnessType::Nanocodex);
-        assert_eq!(
-            metadata.pointer("/harness_assignment/cohort"),
-            Some(&json!("nanocodex"))
-        );
-        assert_eq!(metadata.get("source"), Some(&json!("slackbotv2")));
-        assert!(codex_nanocodex_assignment(&HarnessType::Codex, &HarnessType::Codex, 0).is_none());
-        assert!(
-            codex_nanocodex_assignment(&HarnessType::Nanocodex, &HarnessType::Nanocodex, 50)
-                .is_none()
-        );
-    }
-}
-
 async fn get_session_context(
     State(state): State<AppState>,
     Extension(caller): Extension<AuthenticatedCaller>,
diff --git a/services/api-rs/crates/centaur-api-server/src/types.rs b/services/api-rs/crates/centaur-api-server/src/types.rs
index 0b051989f..8bd5b7876 100644
--- a/services/api-rs/crates/centaur-api-server/src/types.rs
+++ b/services/api-rs/crates/centaur-api-server/src/types.rs
@@ -31,17 +31,6 @@ pub struct CreateSessionResponse {
     pub session: Session,
     /// True when this request restarted the thread onto a different harness.
     pub harness_switched: bool,
-    /// Present when the API assigned this Codex request through an experiment.
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub harness_assignment: Option<HarnessAssignment>,
-}
-
-#[derive(Clone, Debug, Serialize)]
-pub struct HarnessAssignment {
-    pub experiment: &'static str,
-    pub requested_harness: HarnessType,
-    pub cohort: HarnessType,
-    pub rollout_percent: u8,
 }
 
 #[derive(Clone, Debug, Serialize)]
diff --git a/services/api-rs/crates/centaur-session-runtime/src/lib.rs b/services/api-rs/crates/centaur-session-runtime/src/lib.rs
index 7a7f4f25d..922e4f513 100644
--- a/services/api-rs/crates/centaur-session-runtime/src/lib.rs
+++ b/services/api-rs/crates/centaur-session-runtime/src/lib.rs
@@ -876,20 +876,6 @@ impl SessionRuntime {
         Ok(self.store.get_session(thread_key).await?)
     }
 
-    /// Returns the harness already persisted for a thread, if the session
-    /// exists. API policy uses this to keep rollout assignments sticky across
-    /// configuration changes without exposing the session store itself.
-    pub async fn existing_session_harness(
-        &self,
-        thread_key: &ThreadKey,
-    ) -> Result<Option<HarnessType>, SessionRuntimeError> {
-        match self.store.get_session(thread_key).await {
-            Ok(session) => Ok(Some(session.harness_type)),
-            Err(SessionStoreError::NotFound { .. }) => Ok(None),
-            Err(error) => Err(error.into()),
-        }
-    }
-
     fn resolve_persona_for_create(
         &self,
         requested_persona_id: Option<&str>,
diff --git a/services/slackbotv2/src/harness-rollout.ts b/services/slackbotv2/src/harness-rollout.ts
new file mode 100644
index 000000000..ecb0c95f9
--- /dev/null
+++ b/services/slackbotv2/src/harness-rollout.ts
@@ -0,0 +1,42 @@
+import { createHash } from 'node:crypto'
+import type { SlackbotV2HarnessAssignment } from './types'
+
+const CODEX_NANOCODEX_AB_EXPERIMENT = 'codex_nanocodex_ab'
+
+export type HarnessRolloutResolution = {
+  assignment?: SlackbotV2HarnessAssignment
+  harnessType: string
+}
+
+export function resolveHarnessRollout(input: {
+  modelOverride?: string
+  requestedHarness: string
+  rolloutPercent: number
+  threadId: string
+}): HarnessRolloutResolution {
+  if (
+    input.requestedHarness !== 'codex' ||
+    input.rolloutPercent <= 0 ||
+    Boolean(input.modelOverride?.trim())
+  ) {
+    return { harnessType: input.requestedHarness }
+  }
+
+  const harnessType = selectCodexCohort(input.threadId, input.rolloutPercent)
+  return {
+    assignment: {
+      experiment: CODEX_NANOCODEX_AB_EXPERIMENT,
+      requestedHarness: input.requestedHarness,
+      cohort: harnessType,
+      rolloutPercent: input.rolloutPercent
+    },
+    harnessType
+  }
+}
+
+function selectCodexCohort(threadId: string, nanocodexPercent: number): string {
+  if (nanocodexPercent >= 100) return 'nanocodex'
+  const bucket = createHash('sha256').update(threadId).digest().readUInt32BE(0)
+  const threshold = (nanocodexPercent * 2 ** 32) / 100
+  return bucket < threshold ? 'nanocodex' : 'codex'
+}
diff --git a/services/slackbotv2/src/index.ts b/services/slackbotv2/src/index.ts
index edc8910fc..08fa1691b 100644
--- a/services/slackbotv2/src/index.ts
+++ b/services/slackbotv2/src/index.ts
@@ -30,6 +30,7 @@ import {
   type RendererEvent
 } from '@centaur/rendering'
 import { conflateChatSdkStream } from './conflate'
+import { resolveHarnessRollout } from './harness-rollout'
 import { observeSeconds, slackbotMetrics } from './metrics'
 import {
   renderSlackDisplayText,
@@ -1114,9 +1115,19 @@ async function syncThreadMessageToSession(
   // Without an explicit override or channel default the harness runs its
   // configured default (CLAUDE_MODEL/CODEX_MODEL, else the baked harness
   // config); show and record that instead of dropping the model entirely.
-  const effectiveModel =
-    resolvedModel ??
-    defaultModelForHarness(effectiveHarnessType, input.options.harnessDefaultModels)
+  const harnessDefaultModel = defaultModelForHarness(
+    effectiveHarnessType,
+    input.options.harnessDefaultModels
+  )
+  const effectiveModel = resolvedModel ?? harnessDefaultModel
+  const modelOverride = resolvedModel !== harnessDefaultModel ? resolvedModel : undefined
+  const harnessRollout = resolveHarnessRollout({
+    modelOverride,
+    requestedHarness: effectiveHarnessType,
+    rolloutPercent: input.options.codexNanocodexRolloutPercent ?? 0,
+    threadId: thread.id
+  })
+  const rolloutSelected = harnessRollout.assignment !== undefined
   const resolvedReasoning = reasoningForModel(
     effectiveHarnessType,
     effectiveModel,
@@ -1210,13 +1221,20 @@ async function syncThreadMessageToSession(
     executeMessage: shouldStartExecution ? serializedMessage : undefined,
     // Sticky harness changes only apply when a message starts an execution;
     // restarting the thread out from under an active execution would kill it.
-    harnessType: shouldStartExecution ? resolvedHarnessType : undefined,
+    harnessType: shouldStartExecution
+      ? rolloutSelected
+        ? harnessRollout.harnessType
+        : resolvedHarnessType
+      : undefined,
+    harnessAssignment: shouldStartExecution ? harnessRollout.assignment : undefined,
     metadataHarnessType: shouldStartExecution ? effectiveHarnessType : undefined,
     messages: messagesToAppend,
     model: shouldStartExecution ? resolvedModel : undefined,
     metadataModel: shouldStartExecution ? effectiveModel : undefined,
     provider: shouldStartExecution ? resolvedProvider : undefined,
     reasoning: resolvedReasoning,
+    restartOnHarnessConflict:
+      shouldStartExecution && rolloutSelected ? Boolean(resolvedHarnessType) : undefined,
     onEventId: eventId => {
       lastEventId = Math.max(lastEventId, eventId)
     },
diff --git a/services/slackbotv2/src/server.ts b/services/slackbotv2/src/server.ts
index 23478c24d..703623233 100644
--- a/services/slackbotv2/src/server.ts
+++ b/services/slackbotv2/src/server.ts
@@ -55,6 +55,10 @@ const options: SlackbotV2Options = {
   channelDefaults: parseChannelDefaults(optionalEnv('SLACKBOTV2_CHANNEL_DEFAULTS'), reason =>
     consoleLogger.warn('slackbotv2 SLACKBOTV2_CHANNEL_DEFAULTS', { reason })
   ),
+  codexNanocodexRolloutPercent: percentEnv(
+    'SLACKBOTV2_CODEX_NANOCODEX_ROLLOUT_PERCENT',
+    0
+  ),
   consolePublicUrl: optionalEnv('CENTAUR_CONSOLE_PUBLIC_URL'),
   responseMetadataMode: responseMetadataModeEnv('SLACKBOTV2_RESPONSE_METADATA_MODE'),
   responseServiceTierEnabled: booleanEnv('SLACKBOTV2_RESPONSE_SERVICE_TIER_ENABLED', false),
@@ -161,6 +165,16 @@ function responseMetadataModeEnv(name: string): 'first' | 'always' | 'never' {
   throw new Error(`${name} must be "first", "always", or "never"`)
 }
 
+function percentEnv(name: string, fallback: number): number {
+  const value = optionalEnv(name)
+  if (!value) return fallback
+  const parsed = Number(value)
+  if (!Number.isInteger(parsed) || parsed < 0 || parsed > 100) {
+    throw new Error(`${name} must be an integer from 0 to 100`)
+  }
+  return parsed
+}
+
 function createMessageOverridesStrategy(): SlackbotV2Options['messageOverridesStrategy'] {
   if (messageOverridesStrategyMode !== 'llm') return createFlagMessageOverridesStrategy()
   if (!messageOverridesStrategyApiKey) {
diff --git a/services/slackbotv2/src/session-api.ts b/services/slackbotv2/src/session-api.ts
index b718fe5bd..8e916c40f 100644
--- a/services/slackbotv2/src/session-api.ts
+++ b/services/slackbotv2/src/session-api.ts
@@ -480,7 +480,9 @@ export async function forwardToSessionApi(
       options,
       input.threadId,
       input.harnessType,
-      sessionRequesterMessage(input)
+      sessionRequesterMessage(input),
+      input.restartOnHarnessConflict,
+      input.harnessAssignment
     ),
     sessionApiTimeoutMs(options),
     'create session'
@@ -759,9 +761,9 @@ export function clearConversationNameCacheForTests(): void {
 }
 
 type CreateSessionOutcome = {
-  /** The harness persisted by the API after applying control-plane policy. */
+  /** The harness persisted by the API. */
   harnessType?: string
-  /** The experiment/cohort used to select the persisted harness. */
+  /** The Slack-owned experiment/cohort used to select the persisted harness. */
   harnessAssignment?: SlackbotV2HarnessAssignment
   /** The API restarted the thread onto the requested harness. */
   harnessSwitched: boolean
@@ -771,7 +773,9 @@ async function createSession(
   options: SlackbotV2Options,
   threadId: string,
   harnessType?: string,
-  message?: SlackbotV2ApiMessage
+  message?: SlackbotV2ApiMessage,
+  restartOnHarnessConflict?: boolean,
+  harnessAssignment?: SlackbotV2HarnessAssignment
 ): Promise<CreateSessionOutcome> {
   const requested = harnessType ?? options.defaultHarnessType ?? DEFAULT_HARNESS_TYPE
   // A sticky --claude/--amp/--codex/--nanocodex selection restarts a thread
@@ -781,10 +785,11 @@ async function createSession(
     threadId,
     requested,
     message,
-    harnessType ? 'restart' : undefined
+    (restartOnHarnessConflict ?? Boolean(harnessType)) ? 'restart' : undefined,
+    harnessAssignment
   )
   if (response.ok) {
-    return sessionOutcomeFromResponse(response)
+    return sessionOutcomeFromResponse(response, harnessAssignment)
   }
 
   let body = ''
@@ -799,9 +804,16 @@ async function createSession(
   // harness instead of failing the message.
   const existing = response.status === 409 ? existingHarnessFromConflict(body) : undefined
   if (existing && existing !== requested) {
-    const retry = await postCreateSession(options, threadId, existing, message)
+    const retry = await postCreateSession(
+      options,
+      threadId,
+      existing,
+      message,
+      undefined,
+      harnessAssignment
+    )
     await ensureApiOk(retry, 'create session')
-    return sessionOutcomeFromResponse(retry)
+    return sessionOutcomeFromResponse(retry, harnessAssignment)
   }
   throw new SessionApiError({
     action: 'create session',
@@ -817,7 +829,8 @@ async function postCreateSession(
   threadId: string,
   harnessType: string,
   message?: SlackbotV2ApiMessage,
-  onHarnessConflict?: 'reject' | 'restart'
+  onHarnessConflict?: 'reject' | 'restart',
+  harnessAssignment?: SlackbotV2HarnessAssignment
 ): Promise<Response> {
   const fetchFn = options.fetch ?? fetch
   // The conversation name becomes the session principal's display name in
@@ -836,6 +849,9 @@ async function postCreateSession(
       thread_id: threadId,
       ...slackHomeTeamMetadata(options),
       ...sessionRequesterMetadata(message, requesterIdentity),
+      ...(harnessAssignment
+        ? { harness_assignment: harnessAssignmentMetadata(harnessAssignment) }
+        : {}),
       ...(conversationName ? { slack_conversation_name: conversationName } : {})
     },
     ...(onHarnessConflict ? { on_harness_conflict: onHarnessConflict } : {})
@@ -853,39 +869,38 @@ async function postCreateSession(
   )
 }
 
-async function sessionOutcomeFromResponse(response: Response): Promise<CreateSessionOutcome> {
+async function sessionOutcomeFromResponse(
+  response: Response,
+  harnessAssignment?: SlackbotV2HarnessAssignment
+): Promise<CreateSessionOutcome> {
   try {
     const payload = await response.json()
     const harnessType = isJsonObject(payload) ? stringValue(payload.harness_type) : undefined
-    const harnessAssignment = isJsonObject(payload)
-      ? harnessAssignmentFromResponse(payload.harness_assignment)
-      : undefined
+    const resolvedAssignment =
+      harnessAssignment &&
+      (!harnessType || harnessType === 'codex' || harnessType === 'nanocodex')
+        ? { ...harnessAssignment, cohort: harnessType ?? harnessAssignment.cohort }
+        : undefined
     return {
       harnessSwitched: isJsonObject(payload) && payload.harness_switched === true,
       ...(harnessType ? { harnessType } : {}),
-      ...(harnessAssignment ? { harnessAssignment } : {})
+      ...(resolvedAssignment ? { harnessAssignment: resolvedAssignment } : {})
     }
   } catch {
-    return { harnessSwitched: false }
+    return {
+      harnessSwitched: false,
+      ...(harnessAssignment ? { harnessAssignment } : {})
+    }
   }
 }
 
-function harnessAssignmentFromResponse(value: unknown): SlackbotV2HarnessAssignment | undefined {
-  if (!isJsonObject(value)) return undefined
-  const experiment = stringValue(value.experiment)
-  const requestedHarness = stringValue(value.requested_harness)
-  const cohort = stringValue(value.cohort)
-  const rolloutPercent = value.rollout_percent
-  if (
-    !experiment ||
-    !requestedHarness ||
-    !cohort ||
-    typeof rolloutPercent !== 'number' ||
-    !Number.isFinite(rolloutPercent)
-  ) {
-    return undefined
+function harnessAssignmentMetadata(assignment: SlackbotV2HarnessAssignment): JsonObject {
+  return {
+    experiment: assignment.experiment,
+    requested_harness: assignment.requestedHarness,
+    cohort: assignment.cohort,
+    rollout_percent: assignment.rolloutPercent
   }
-  return { experiment, requestedHarness, cohort, rolloutPercent }
 }
 
 function existingHarnessFromConflict(body: string): string | undefined {
@@ -1342,14 +1357,7 @@ async function executeSession(
         ...(recordedModel ? { model: recordedModel } : {}),
         ...(metadataHarnessType ? { harness_type: metadataHarnessType } : {}),
         ...(harnessAssignment
-          ? {
-              harness_assignment: {
-                experiment: harnessAssignment.experiment,
-                requested_harness: harnessAssignment.requestedHarness,
-                cohort: harnessAssignment.cohort,
-                rollout_percent: harnessAssignment.rolloutPercent
-              }
-            }
+          ? { harness_assignment: harnessAssignmentMetadata(harnessAssignment) }
           : {})
       },
       requesterIdentity
diff --git a/services/slackbotv2/src/types.ts b/services/slackbotv2/src/types.ts
index 1ae87fe2e..884cbc088 100644
--- a/services/slackbotv2/src/types.ts
+++ b/services/slackbotv2/src/types.ts
@@ -155,6 +155,8 @@ export type SlackbotV2Options = {
    * conversation id (SLACKBOTV2_CHANNEL_DEFAULTS). See channel-defaults.ts.
    */
   channelDefaults?: ChannelDefaults
+  /** Percentage of otherwise-default Codex threads assigned to Nanocodex. */
+  codexNanocodexRolloutPercent?: number
   /**
    * Harness for new threads when no --claude/--amp/--codex/--nanocodex/--hermes
    * flag is given (HarnessType wire value: codex | amp | claudecode |
@@ -277,11 +279,11 @@ export type ForwardSessionInput = {
   contextPreamble?: string
   executionId?: string
   executeMessage?: SlackbotV2ApiMessage
-  /** Effective harness selected by sticky thread flags (including --nanocodex). */
+  /** Effective harness selected by Slack policy, including any rollout cohort. */
   harnessType?: string
-  /** Harness returned by api-rs after applying control-plane policy. */
+  /** Harness persisted by api-rs. */
   metadataHarnessType?: string
-  /** Experiment/cohort returned by api-rs and recorded on this execution. */
+  /** Slack-owned experiment/cohort recorded on the session and execution. */
   harnessAssignment?: SlackbotV2HarnessAssignment
   messages: SlackbotV2ApiMessage[]
   /** Effective model selected by sticky thread flags (--model/--opus/...). */
@@ -296,6 +298,8 @@ export type ForwardSessionInput = {
   provider?: string
   /** Per-turn reasoning effort parsed from the `-rsn` flag (Codex/Nanocodex). */
   reasoning?: string
+  /** Whether an explicit Slack override may restart a thread on harness conflict. */
+  restartOnHarnessConflict?: boolean
   onEventId(eventId: number): void
   openStream: boolean
   threadId: string
diff --git a/services/slackbotv2/test/chat-sdk-emulate.test.ts b/services/slackbotv2/test/chat-sdk-emulate.test.ts
index 36644b29f..dc6d1b677 100644
--- a/services/slackbotv2/test/chat-sdk-emulate.test.ts
+++ b/services/slackbotv2/test/chat-sdk-emulate.test.ts
@@ -1172,17 +1172,20 @@ describe('slackbotv2', () => {
     expect(metadataBlockTexts(slackApi.calls)).toHaveLength(0)
   })
 
-  it('shows the API-assigned harness in Slack and retains execution metadata', async () => {
+  it('shows the Slack-assigned harness and retains rollout metadata', async () => {
     const sharedState = createMemoryState()
     await sharedState.connect()
-    codexApi.resolvedHarnessType = 'nanocodex'
-    codexApi.harnessAssignment = {
+    const harnessAssignment = {
       experiment: 'codex_nanocodex_ab',
       requested_harness: 'codex',
       cohort: 'nanocodex',
-      rollout_percent: 50
+      rollout_percent: 100
     }
-    bot = createTestBot({ consolePublicUrl: 'https://console.example.dev', state: sharedState })
+    bot = createTestBot({
+      codexNanocodexRolloutPercent: 100,
+      consolePublicUrl: 'https://console.example.dev',
+      state: sharedState
+    })
 
     const parent = await postUserMessage('A/B test thread context.')
     const mention = await postUserMessage(
@@ -1218,10 +1221,11 @@ describe('slackbotv2', () => {
     expect(footer).toContain('Nanocodex')
     expect(footer).toContain('Low')
     expect(footer).not.toContain('Codex*')
-    expect(codexApi.creates[0]?.body.harness_type).toBe('codex')
+    expect(codexApi.creates[0]?.body.harness_type).toBe('nanocodex')
+    expect(codexApi.creates[0]?.body.metadata.harness_assignment).toEqual(harnessAssignment)
     expect(codexApi.executes[0]?.body.metadata).toMatchObject({
       harness_type: 'nanocodex',
-      harness_assignment: codexApi.harnessAssignment
+      harness_assignment: harnessAssignment
     })
   })
 
@@ -1328,6 +1332,7 @@ describe('slackbotv2', () => {
     await sharedState.connect()
     bot = createTestBot({
       state: sharedState,
+      codexNanocodexRolloutPercent: 100,
       channelDefaults: {
         [CHANNEL_ID]: { harnessType: 'claudecode', model: 'claude-opus-4-8', reasoning: 'high' }
       }
@@ -1361,6 +1366,7 @@ describe('slackbotv2', () => {
 
     // Explicit --codex/--model/-rsn beat every field of the channel default.
     expect(codexApi.creates.map(create => create.body.harness_type)).toEqual(['codex'])
+    expect(codexApi.creates[0]!.body.metadata.harness_assignment).toBeUndefined()
     expect(codexApi.executes).toHaveLength(1)
     const inputLine = JSON.parse(codexApi.executes[0]!.body.input_lines.at(-1)!) as Record<
       string,
@@ -5678,13 +5684,6 @@ type MockSessionApi = {
   failNextExecute: boolean
   failNextExecuteAfterAccept: boolean
   holdNextExecute(): () => void
-  harnessAssignment?: {
-    experiment: string
-    requested_harness: string
-    cohort: string
-    rollout_percent: number
-  }
-  resolvedHarnessType?: string
   reset(): void
   streamCount: number
   url: string
@@ -5707,8 +5706,6 @@ async function startMockCodexApi(): Promise<MockSessionApi> {
   let failNextEvents = false
   let failNextExecute = false
   let failNextExecuteAfterAccept = false
-  let harnessAssignment: MockSessionApi['harnessAssignment']
-  let resolvedHarnessType: string | undefined
   const port = await availablePort(4063)
   const closeStreams = () => {
     for (const stream of streams) stream.end()
@@ -5736,18 +5733,12 @@ async function startMockCodexApi(): Promise<MockSessionApi> {
       get failNextEvents() {
         return failNextEvents
       },
-      get harnessAssignment() {
-        return harnessAssignment
-      },
       idempotentExecutions,
       nextEventId() {
         eventId += 1
         return eventId
       },
       port,
-      get resolvedHarnessType() {
-        return resolvedHarnessType
-      },
       setFailNextEvents(value) {
         failNextEvents = value
       },
@@ -5787,8 +5778,6 @@ async function startMockCodexApi(): Promise<MockSessionApi> {
       failNextEvents = false
       failNextExecute = false
       failNextExecuteAfterAccept = false
-      harnessAssignment = undefined
-      resolvedHarnessType = undefined
       workflowEvents.length = 0
     },
     url: `http://127.0.0.1:${port}`,
@@ -5818,12 +5807,6 @@ async function startMockCodexApi(): Promise<MockSessionApi> {
     set failNextEvents(value: boolean) {
       failNextEvents = value
     },
-    get harnessAssignment() {
-      return harnessAssignment
-    },
-    set harnessAssignment(value) {
-      harnessAssignment = value
-    },
     holdNextExecute() {
       if (executeHoldRelease) throw new Error('execute is already held')
       executeHold = new Promise(resolve => {
@@ -5836,12 +5819,6 @@ async function startMockCodexApi(): Promise<MockSessionApi> {
         release?.()
       }
     },
-    get resolvedHarnessType() {
-      return resolvedHarnessType
-    },
-    set resolvedHarnessType(value: string | undefined) {
-      resolvedHarnessType = value
-    },
     get streamCount() {
       return streams.size
     },
@@ -5892,11 +5869,9 @@ async function handleMockCodexRequest(
     failNextExecuteAfterAccept: boolean
     failNextEvents: boolean
     failNextExecute: boolean
-    harnessAssignment?: MockSessionApi['harnessAssignment']
-      idempotentExecutions: Map<string, string>
+    idempotentExecutions: Map<string, string>
     nextEventId(): number
     port: number
-    resolvedHarnessType?: string
     setFailNextEvents(value: boolean): void
     setFailNextExecute(value: boolean): void
     setFailNextExecuteAfterAccept(value: boolean): void
@@ -5928,10 +5903,7 @@ async function handleMockCodexRequest(
       Response.json({
         thread_key: threadKey,
         sandbox_id: null,
-        harness_type: input.resolvedHarnessType ?? body.harness_type,
-        ...(input.harnessAssignment
-          ? { harness_assignment: input.harnessAssignment }
-          : {}),
+        harness_type: body.harness_type,
         harness_thread_id: null,
         status: 'active'
       })
diff --git a/services/slackbotv2/test/harness-rollout.test.ts b/services/slackbotv2/test/harness-rollout.test.ts
new file mode 100644
index 000000000..aaad9932e
--- /dev/null
+++ b/services/slackbotv2/test/harness-rollout.test.ts
@@ -0,0 +1,93 @@
+import { describe, expect, test } from 'bun:test'
+import { resolveHarnessRollout } from '../src/harness-rollout'
+
+describe('resolveHarnessRollout', () => {
+  test('assigns Codex requests deterministically by Slack thread', () => {
+    const codex = resolveHarnessRollout({
+      requestedHarness: 'codex',
+      rolloutPercent: 50,
+      threadId: 'slack:C1:1700000000.000100'
+    })
+    const nanocodex = resolveHarnessRollout({
+      requestedHarness: 'codex',
+      rolloutPercent: 50,
+      threadId: 'slack:C1:1700000000.000104'
+    })
+
+    expect(codex.harnessType).toBe('codex')
+    expect(nanocodex).toEqual({
+      assignment: {
+        experiment: 'codex_nanocodex_ab',
+        requestedHarness: 'codex',
+        cohort: 'nanocodex',
+        rolloutPercent: 50
+      },
+      harnessType: 'nanocodex'
+    })
+    expect(
+      resolveHarnessRollout({
+        requestedHarness: 'codex',
+        rolloutPercent: 50,
+        threadId: 'slack:C1:1700000000.000104'
+      })
+    ).toEqual(nanocodex)
+  })
+
+  test('does not roll out a request carrying a non-default model', () => {
+    expect(
+      resolveHarnessRollout({
+        modelOverride: 'gpt-5.5',
+        requestedHarness: 'codex',
+        rolloutPercent: 100,
+        threadId: 'slack:C1:model-override'
+      })
+    ).toEqual({ harnessType: 'codex' })
+  })
+
+  test('honors rollout boundaries and leaves other harnesses alone', () => {
+    expect(
+      resolveHarnessRollout({
+        requestedHarness: 'codex',
+        rolloutPercent: 0,
+        threadId: 'slack:C1:disabled'
+      })
+    ).toEqual({ harnessType: 'codex' })
+    expect(
+      resolveHarnessRollout({
+        requestedHarness: 'codex',
+        rolloutPercent: 100,
+        threadId: 'slack:C1:complete'
+      })
+    ).toEqual({
+      assignment: {
+        experiment: 'codex_nanocodex_ab',
+        requestedHarness: 'codex',
+        cohort: 'nanocodex',
+        rolloutPercent: 100
+      },
+      harnessType: 'nanocodex'
+    })
+    expect(
+      resolveHarnessRollout({
+        requestedHarness: 'claudecode',
+        rolloutPercent: 50,
+        threadId: 'slack:C1:claude'
+      })
+    ).toEqual({ harnessType: 'claudecode' })
+  })
+
+  test('is balanced across many Slack thread keys', () => {
+    const nanocodex = Array.from({ length: 10_000 }, (_, index) => index).filter(index => {
+      return (
+        resolveHarnessRollout({
+          requestedHarness: 'codex',
+          rolloutPercent: 50,
+          threadId: `slack:C1:rollout-${index}`
+        }).harnessType === 'nanocodex'
+      )
+    }).length
+
+    expect(nanocodex).toBeGreaterThanOrEqual(4_900)
+    expect(nanocodex).toBeLessThanOrEqual(5_100)
+  })
+})
diff --git a/services/slackbotv2/test/session-api.test.ts b/services/slackbotv2/test/session-api.test.ts
index 173c22219..734e657c1 100644
--- a/services/slackbotv2/test/session-api.test.ts
+++ b/services/slackbotv2/test/session-api.test.ts
@@ -797,36 +797,57 @@ describe('forwardToSessionApi harness restart', () => {
     expect('on_harness_conflict' in (create?.body as object)).toBe(false)
   })
 
-  test('reports the harness resolved by api-rs', async () => {
+  test('records a Slack-owned harness assignment on session creation and execution', async () => {
     const { fetchFn, requests } = fakeApi({
       createSession: [
         {
           body: {
             harness_switched: false,
-            harness_type: 'nanocodex',
-            harness_assignment: {
-              experiment: 'codex_nanocodex_ab',
-              requested_harness: 'codex',
-              cohort: 'nanocodex',
-              rollout_percent: 50
-            }
+            harness_type: 'nanocodex'
           },
           status: 200
         }
       ]
     })
+    const harnessAssignment = {
+      experiment: 'codex_nanocodex_ab',
+      requestedHarness: 'codex',
+      cohort: 'nanocodex',
+      rolloutPercent: 50
+    }
     let resolvedHarness: string | undefined
     let resolvedExperiment: string | undefined
 
-    await forwardToSessionApi(options(fetchFn), forwardInput(apiMessage('hi')), {
-      onSessionCreated: async outcome => {
-        resolvedHarness = outcome.harnessType
-        resolvedExperiment = outcome.harnessAssignment?.experiment
+    await forwardToSessionApi(
+      options(fetchFn),
+      forwardInput(apiMessage('hi'), {
+        harnessAssignment,
+        harnessType: 'nanocodex',
+        restartOnHarnessConflict: false
+      }),
+      {
+        onSessionCreated: async outcome => {
+          resolvedHarness = outcome.harnessType
+          resolvedExperiment = outcome.harnessAssignment?.experiment
+        }
       }
-    })
+    )
 
     expect(resolvedHarness).toBe('nanocodex')
     expect(resolvedExperiment).toBe('codex_nanocodex_ab')
+    const create = requests.find(request => request.url.endsWith('.000100'))
+    expect(create?.body).toMatchObject({
+      harness_type: 'nanocodex',
+      metadata: {
+        harness_assignment: {
+          experiment: 'codex_nanocodex_ab',
+          requested_harness: 'codex',
+          cohort: 'nanocodex',
+          rollout_percent: 50
+        }
+      }
+    })
+    expect('on_harness_conflict' in (create?.body as object)).toBe(false)
     expect(executeBody(requests).metadata).toMatchObject({
       harness_type: 'nanocodex',
       harness_assignment: {

From d13b7e5bc9e481b72f41a0d71fa56e8f97adc18e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jos=C3=A9=20Ribeiro?= <me@joseribeiro.dev>
Date: Wed, 19 Aug 2026 21:31:24 +0000
Subject: [PATCH 29/36] fix(figma): align credential contract (#1146)

fix: align Figma credential contract
---
 tools/productivity/figma/.env.example        |   2 +-
 tools/productivity/figma/cli.py              |   2 +-
 tools/productivity/figma/client.py           |   4 +-
 tools/productivity/figma/test_credentials.py | 115 +++++++++++++++++++
 4 files changed, 119 insertions(+), 4 deletions(-)
 create mode 100644 tools/productivity/figma/test_credentials.py

diff --git a/tools/productivity/figma/.env.example b/tools/productivity/figma/.env.example
index 50a132b4f..49302c275 100644
--- a/tools/productivity/figma/.env.example
+++ b/tools/productivity/figma/.env.example
@@ -1 +1 @@
-FIGMA=
+FIGMA_ACCESS_TOKEN=figd_your-read-only-access-token-here
diff --git a/tools/productivity/figma/cli.py b/tools/productivity/figma/cli.py
index a4f170dda..c2f910ba7 100644
--- a/tools/productivity/figma/cli.py
+++ b/tools/productivity/figma/cli.py
@@ -44,7 +44,7 @@ def crawl(
     """Crawl a Figma file and extract design system info.
 
     Extracts colors, typography, components, variables, and frames from any Figma URL.
-    Uses FIGMA env var for authentication (personal access token).
+    Uses FIGMA_ACCESS_TOKEN for authentication.
     """
     from .client import FigmaClient
 
diff --git a/tools/productivity/figma/client.py b/tools/productivity/figma/client.py
index b91e47a30..3bc699953 100644
--- a/tools/productivity/figma/client.py
+++ b/tools/productivity/figma/client.py
@@ -28,9 +28,9 @@ class FigmaClient:
     BASE_URL = "https://api.figma.com/v1"
 
     def __init__(self, token: str | None = None):
-        self.token = token or secret("FIGMA_ACCESS_TOKEN", "") or secret("FIGMA", "")
+        self.token = token or secret("FIGMA_ACCESS_TOKEN", "")
         if not self.token:
-            raise ValueError("FIGMA token not found. Set FIGMA_ACCESS_TOKEN env var or pass token.")
+            raise ValueError("Figma token not found. Set FIGMA_ACCESS_TOKEN or pass token.")
 
     def _request(self, endpoint: str, retries: int = 3) -> dict:
         """Make authenticated request to Figma API with retry on rate limit."""
diff --git a/tools/productivity/figma/test_credentials.py b/tools/productivity/figma/test_credentials.py
new file mode 100644
index 000000000..175619424
--- /dev/null
+++ b/tools/productivity/figma/test_credentials.py
@@ -0,0 +1,115 @@
+"""Credential contract tests for the Figma tool.
+
+Run from this directory:
+    uv run --no-project --python 3.11 --with pytest pytest test_credentials.py
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import sys
+import tomllib
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+TOOL_DIR = Path(__file__).parent
+REPO_ROOT = TOOL_DIR.parents[2]
+sys.path.insert(0, str(REPO_ROOT))
+
+
+def _load_client_module():
+    client_path = TOOL_DIR / "client.py"
+    spec = importlib.util.spec_from_file_location("test_figma_client_module", client_path)
+    assert spec is not None and spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def test_manifest_limits_token_injection_to_figma_api() -> None:
+    metadata = tomllib.loads((TOOL_DIR / "pyproject.toml").read_text())
+    secrets = metadata["tool"]["centaur"]["secrets"]
+
+    assert secrets == [
+        {
+            "type": "http",
+            "name": "FIGMA_ACCESS_TOKEN",
+            "mode": "inject",
+            "inject_header": "X-Figma-Token",
+            "hosts": ["api.figma.com"],
+        }
+    ]
+
+
+def test_example_environment_uses_declared_secret_name() -> None:
+    example = (TOOL_DIR / ".env.example").read_text().split("=", maxsplit=1)
+
+    assert example[0] == "FIGMA_ACCESS_TOKEN"
+
+
+def test_client_resolves_only_the_declared_secret(monkeypatch) -> None:
+    client_module = _load_client_module()
+    requested_secrets: list[tuple[str, str]] = []
+
+    def fake_secret(name: str, default: str) -> str:
+        requested_secrets.append((name, default))
+        return "placeholder-token"
+
+    monkeypatch.setattr(client_module, "secret", fake_secret)
+
+    client = client_module.FigmaClient()
+
+    assert client.token == "placeholder-token"
+    assert requested_secrets == [("FIGMA_ACCESS_TOKEN", "")]
+
+
+def test_client_does_not_resolve_undeclared_legacy_secret(monkeypatch) -> None:
+    client_module = _load_client_module()
+    requested_secrets: list[tuple[str, str]] = []
+
+    def fake_secret(name: str, default: str) -> str:
+        requested_secrets.append((name, default))
+        return "legacy-token" if name == "FIGMA" else default
+
+    monkeypatch.setattr(client_module, "secret", fake_secret)
+
+    with pytest.raises(ValueError, match="Set FIGMA_ACCESS_TOKEN or pass token"):
+        client_module.FigmaClient()
+
+    assert requested_secrets == [("FIGMA_ACCESS_TOKEN", "")]
+
+
+def test_client_sends_token_only_to_figma_api(monkeypatch) -> None:
+    client_module = _load_client_module()
+    captured_request: dict[str, Any] = {}
+
+    class FakeResponse:
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *_args: object) -> None:
+            return None
+
+        def read(self) -> bytes:
+            return json.dumps({"id": "test-user"}).encode()
+
+    def fake_urlopen(request, timeout: int):
+        captured_request["url"] = request.full_url
+        captured_request["token"] = request.get_header("X-figma-token")
+        captured_request["timeout"] = timeout
+        return FakeResponse()
+
+    monkeypatch.setattr(client_module, "urlopen", fake_urlopen)
+
+    result = client_module.FigmaClient(token="placeholder-token")._request("/me")
+
+    assert result == {"id": "test-user"}
+    assert captured_request == {
+        "url": "https://api.figma.com/v1/me",
+        "token": "placeholder-token",
+        "timeout": 60,
+    }

From 16e6a9bb437de39a4debf140e91e7d3edf77033f Mon Sep 17 00:00:00 2001
From: zhygis <5236121+Zygimantass@users.noreply.github.com>
Date: Wed, 19 Aug 2026 21:31:40 +0000
Subject: [PATCH 30/36] Support custom Codex providers (#1410)

* feat: support custom Codex providers

Amp-Thread-ID: https://ampcode.com/threads/T-01a0118a-4098-7650-b30b-fce6b8237f41
Co-authored-by: Amp <amp@ampcode.com>

* fix: persist custom Codex providers across turns

* chore(chart): bump chart to 0.1.123

* chore(chart): bump chart to 0.1.124

---------

Co-authored-by: Amp <amp@ampcode.com>
Co-authored-by: Matthew Slipper <me@matthewslipper.com>
---
 contrib/chart/Chart.yaml                      |   2 +-
 contrib/chart/templates/apirs.yaml            |   9 ++
 contrib/chart/templates/console.yaml          |   4 +
 contrib/chart/templates/githubbot.yaml        |   4 +
 contrib/chart/templates/linearbot.yaml        |   4 +
 contrib/chart/templates/slackbotv2.yaml       |   4 +
 contrib/chart/values.schema.json              |  20 +++
 contrib/chart/values.yaml                     |  15 ++
 docs/pages/deploying-in-production.mdx        |  22 +++
 docs/pages/reference/configuration.mdx        |   2 +
 services/api-rs/Cargo.lock                    |   3 +-
 .../crates/centaur-api-server/src/args.rs     |   6 +-
 .../crates/centaur-iron-proxy/Cargo.toml      |   1 +
 .../crates/centaur-iron-proxy/src/error.rs    |   7 +
 .../crates/centaur-iron-proxy/src/fragment.rs | 139 ++++++++++++++++++
 .../crates/centaur-iron-proxy/src/lib.rs      |   4 +-
 .../crates/centaur-iron-proxy/src/tests.rs    |  61 ++++++++
 .../controllers/console/threads_controller.rb |  87 ++++++++---
 .../views/console/threads/_composer.html.erb  |   2 +-
 .../console/threads_controller_test.rb        |  28 ++++
 services/githubbot/README.md                  |   2 +-
 services/githubbot/src/index.ts               |   6 +-
 services/githubbot/src/overrides.ts           |  48 ++++++
 services/githubbot/src/session-api.ts         |  10 +-
 services/githubbot/src/turn.ts                |  10 +-
 services/githubbot/src/types.ts               |   4 +
 services/githubbot/test/overrides.test.ts     |  61 +++++++-
 services/linearbot/src/index.ts               |  10 +-
 services/linearbot/src/overrides.ts           |  65 +++++++-
 services/linearbot/src/types.ts               |   2 +
 .../linearbot/test/chat-sdk-emulate.test.ts   |  46 ++++++
 services/linearbot/test/overrides.test.ts     |  61 +++++++-
 services/sandbox/SYSTEM_PROMPT.md             |   2 +-
 services/sandbox/entrypoint.sh                |  31 ++++
 services/slackbotv2/src/overrides.ts          |  52 ++++++-
 services/slackbotv2/test/overrides.test.ts    |  42 +++++-
 36 files changed, 834 insertions(+), 42 deletions(-)

diff --git a/contrib/chart/Chart.yaml b/contrib/chart/Chart.yaml
index 6b0f1be4a..ae23a2317 100644
--- a/contrib/chart/Chart.yaml
+++ b/contrib/chart/Chart.yaml
@@ -2,7 +2,7 @@ apiVersion: v2
 name: centaur
 description: Helm chart for the trusted Centaur control plane
 type: application
-version: 0.1.123
+version: 0.1.124
 appVersion: "0.1.0"
 dependencies:
   - name: connect
diff --git a/contrib/chart/templates/apirs.yaml b/contrib/chart/templates/apirs.yaml
index 38502ee09..e33909116 100644
--- a/contrib/chart/templates/apirs.yaml
+++ b/contrib/chart/templates/apirs.yaml
@@ -427,6 +427,12 @@ spec:
               value: {{ .Values.sandbox.codexAuthMode | quote }}
             - name: CLAUDE_CODE_AUTH_MODE
               value: {{ .Values.sandbox.claudeCodeAuthMode | quote }}
+{{- if .Values.codex.customProviders }}
+            # Shared provider catalog: api-rs derives hostname-scoped proxy
+            # credentials from the same JSON sandboxes use for Codex config.
+            - name: CODEX_CUSTOM_PROVIDERS
+              value: {{ .Values.codex.customProviders | toJson | quote }}
+{{- end }}
             # Which harness's auth fragment iron-proxy registers (and therefore
             # which placeholder credential lands in the sandbox env). Must agree
             # with the harness the sandbox image CMD actually runs.
@@ -445,6 +451,9 @@ spec:
 {{- if not (hasKey .Values.sandbox.extraEnv "COMPANY_CONTEXT_EMBEDDINGS_MODEL") }}
 {{- $sandboxEnvList = append $sandboxEnvList (dict "name" "COMPANY_CONTEXT_EMBEDDINGS_MODEL" "value" $companyContextEmbeddingsModel) }}
 {{- end }}
+{{- if .Values.codex.customProviders }}
+{{- $sandboxEnvList = append $sandboxEnvList (dict "name" "CODEX_CUSTOM_PROVIDERS" "value" (.Values.codex.customProviders | toJson)) }}
+{{- end }}
 {{- range $k, $v := .Values.sandbox.extraEnv }}
 {{- $sandboxEnvList = append $sandboxEnvList (dict "name" $k "value" ($v | toString)) }}
 {{- end }}
diff --git a/contrib/chart/templates/console.yaml b/contrib/chart/templates/console.yaml
index 6b4cbb4ca..69c94d89e 100644
--- a/contrib/chart/templates/console.yaml
+++ b/contrib/chart/templates/console.yaml
@@ -127,6 +127,10 @@ spec:
                   name: {{ $secretEnv }}
                   key: {{ printf "%sSLACK_BOT_TOKEN" $prefix }}
                   optional: true
+{{- if .Values.codex.customProviders }}
+            - name: CODEX_CUSTOM_PROVIDERS
+              value: {{ .Values.codex.customProviders | toJson | quote }}
+{{- end }}
 {{- range $name := tuple "CLAUDE_MODEL" "CODEX_MODEL" }}
 {{- if hasKey $.Values.sandbox.extraEnv $name }}
             # Mirror the deployer's harness default-model override
diff --git a/contrib/chart/templates/githubbot.yaml b/contrib/chart/templates/githubbot.yaml
index d291d6b7f..2b1e75e07 100644
--- a/contrib/chart/templates/githubbot.yaml
+++ b/contrib/chart/templates/githubbot.yaml
@@ -126,6 +126,10 @@ spec:
             # final flush + exit still fit before the pod is force-killed.
             - name: GITHUBBOT_SHUTDOWN_DRAIN_MS
               value: {{ mul (sub (int .Values.githubbot.terminationGracePeriodSeconds) 10) 1000 | quote }}
+{{- if .Values.codex.customProviders }}
+            - name: CODEX_CUSTOM_PROVIDERS
+              value: {{ .Values.codex.customProviders | toJson | quote }}
+{{- end }}
 {{- range $name, $value := .Values.githubbot.extraEnv }}
             - name: {{ $name }}
               value: {{ $value | quote }}
diff --git a/contrib/chart/templates/linearbot.yaml b/contrib/chart/templates/linearbot.yaml
index 5092b8c9d..b90f78f37 100644
--- a/contrib/chart/templates/linearbot.yaml
+++ b/contrib/chart/templates/linearbot.yaml
@@ -63,6 +63,10 @@ spec:
                   key: {{ printf "%sDATABASE_URL" .Values.secretManager.envPrefix }}
             - name: LINEARBOT_USER_NAME
               value: {{ .Values.linearbot.userName | quote }}
+{{- if .Values.codex.customProviders }}
+            - name: CODEX_CUSTOM_PROVIDERS
+              value: {{ .Values.codex.customProviders | toJson | quote }}
+{{- end }}
 {{- range $name, $value := .Values.linearbot.extraEnv }}
             - name: {{ $name }}
               value: {{ $value | quote }}
diff --git a/contrib/chart/templates/slackbotv2.yaml b/contrib/chart/templates/slackbotv2.yaml
index 02cb12680..9fc2ec314 100644
--- a/contrib/chart/templates/slackbotv2.yaml
+++ b/contrib/chart/templates/slackbotv2.yaml
@@ -123,6 +123,10 @@ spec:
             - name: SLACKBOTV2_CHANNEL_DEFAULTS
               value: {{ .Values.slackbotv2.channelDefaults | toJson | quote }}
 {{- end }}
+{{- if .Values.codex.customProviders }}
+            - name: CODEX_CUSTOM_PROVIDERS
+              value: {{ .Values.codex.customProviders | toJson | quote }}
+{{- end }}
 {{- range $name := tuple "CLAUDE_MODEL" "CODEX_MODEL" "CODEX_MODEL_REASONING_EFFORT" }}
 {{- if and (hasKey $.Values.sandbox.extraEnv $name) (not (hasKey $.Values.slackbotv2.extraEnv $name)) }}
             # Mirror the deployer's harness default override (sandbox.extraEnv)
diff --git a/contrib/chart/values.schema.json b/contrib/chart/values.schema.json
index d0b539b36..b61f459c7 100644
--- a/contrib/chart/values.schema.json
+++ b/contrib/chart/values.schema.json
@@ -198,6 +198,26 @@
         }
       }
     },
+    "codex": {
+      "type": "object",
+      "properties": {
+        "customProviders": {
+          "type": "object",
+          "propertyNames": { "pattern": "^[a-z][a-z0-9_-]*$" },
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "name": { "type": "string", "minLength": 1 },
+              "baseUrl": { "type": "string", "pattern": "^https://" },
+              "apiKeyEnv": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*$" },
+              "defaultModel": { "type": "string", "minLength": 1 }
+            },
+            "required": ["name", "baseUrl", "apiKeyEnv"],
+            "additionalProperties": false
+          }
+        }
+      }
+    },
     "sandbox": {
       "type": "object",
       "properties": {
diff --git a/contrib/chart/values.yaml b/contrib/chart/values.yaml
index ee0027cb6..318db1d03 100644
--- a/contrib/chart/values.yaml
+++ b/contrib/chart/values.yaml
@@ -271,6 +271,21 @@ overlays:
   #   toolsSubdir: ""
   #   skillsSubdir: ""
 
+codex:
+  # Operator-defined OpenAI-compatible Responses providers. Each provider is
+  # added to sandbox Codex config, exposed through `--provider <id>`, and given
+  # a hostname-scoped iron-proxy bearer-token replacement. `apiKeyEnv` names a
+  # field in the configured secret source; sandboxes receive only a placeholder.
+  # Example:
+  #   customProviders:
+  #     private_responses:
+  #       name: Private Responses
+  #       baseUrl: https://inference.example.com/v1
+  #       apiKeyEnv: PRIVATE_RESPONSES_API_KEY
+  #       # Optional; callers must pass --model when omitted.
+  #       defaultModel: example-model
+  customProviders: {}
+
 sandbox:
   controller: pod
   image:
diff --git a/docs/pages/deploying-in-production.mdx b/docs/pages/deploying-in-production.mdx
index 294800a97..7d91c4c06 100644
--- a/docs/pages/deploying-in-production.mdx
+++ b/docs/pages/deploying-in-production.mdx
@@ -102,6 +102,7 @@ Store one secret per enabled harness credential:
 | Codex default | `codex` | none or `--codex` | `OPENAI_API_KEY` | `api.openai.com` |
 | Codex with OpenRouter provider | `codex` | none or `--codex` | `OPENROUTER_API_KEY` | `openrouter.ai` |
 | Codex with Meta AI direct | `codex` | `--meta` | `META_AI_API_KEY` | `api.ai.meta.com` |
+| Codex with a custom provider | `codex` | `--provider <id>` | Provider `apiKeyEnv` | Provider `baseUrl` host |
 | Amp | `amp` | `--amp` | `AMP_API_KEY` | `ampcode.com` |
 | Claude Code | `claude-code` | `--claude` | `ANTHROPIC_API_KEY` | `api.anthropic.com` |
 | pi-mono | `pi-mono` | `--pi` | `ANTHROPIC_API_KEY` | `api.anthropic.com` |
@@ -129,6 +130,27 @@ To run Codex through Meta AI direct, store `META_AI_API_KEY` and select the
 provider with `--meta`. Pair it with `--model <model-id>` when choosing a
 provider-specific model for a turn.
 
+To register a private OpenAI-compatible Responses provider, add it once under
+`codex.customProviders`:
+
+```yaml
+codex:
+  customProviders:
+    private_responses:
+      name: Private Responses
+      baseUrl: https://inference.example.com/v1
+      apiKeyEnv: PRIVATE_RESPONSES_API_KEY
+      defaultModel: example-model
+```
+
+Store the named key in the configured iron-proxy secret source. The chart sends
+the non-secret provider catalog to api-rs, sandboxes, chat ingresses, and the
+Console. api-rs registers a bearer-token replacement restricted to the
+`baseUrl` DNS host; sandboxes receive only the `apiKeyEnv` placeholder. Select
+the provider with `--provider private_responses`; `--model` overrides its
+configured default for that turn. If `defaultModel` is omitted, callers must
+pass `--model`; the Console lists only custom providers that define a default.
+
 The backing vault can be shared across the deployment, but access is not. The
 Centaur Console grants each user, channel, issue, or workflow principal only
 the roles and secrets it should use. The `infra` role is assigned to new
diff --git a/docs/pages/reference/configuration.mdx b/docs/pages/reference/configuration.mdx
index 3215050ff..20165cdaa 100644
--- a/docs/pages/reference/configuration.mdx
+++ b/docs/pages/reference/configuration.mdx
@@ -241,6 +241,8 @@ Sandbox entrypoint and wrappers:
 | `CODEX_API_KEY`, `CODEX_HOME`, `CODEX_CONTINUE_THREAD_ID` | `sandbox.extraEnv` or runtime resume. | Codex auth/config/resume behavior. |
 | `CODEX_AUTH_MODE` | `sandbox.codexAuthMode`. | Codex auth flow: `api_key` (default, hits `api.openai.com`) or `access_token` (hits `chatgpt.com` via the brokered ChatGPT login). The chart sets this on api-rs, which propagates it into sandboxes. See [Codex Auth Modes](/deploying-in-production#codex-auth-modes). |
 | `META_AI_API_KEY` | Secret mounted into api-rs. | Meta AI direct credential for Codex provider `responses` and Slack or Linear `--meta` selection. |
+| `CODEX_CUSTOM_PROVIDERS` | Chart-rendered from `codex.customProviders`. | JSON provider catalog consumed by api-rs, sandboxes, chat ingresses, and Console. Prefer the chart value over setting this environment variable directly. Each entry supplies `name`, HTTPS `baseUrl`, `apiKeyEnv`, and an optional `defaultModel`; select it with `--provider <id>`. |
+| Custom provider `apiKeyEnv` | The configured iron-proxy secret source. | Bearer token for that provider. Sandboxes receive only a same-name placeholder, and replacement is restricted to the provider's `baseUrl` DNS host. |
 | `CODEX_MODEL_REASONING_SUMMARY` | `sandbox.extraEnv`. | Sets `model_reasoning_summary` in the Codex config (`auto`, `concise`, `detailed`, `none`). Codex >= 0.139 emits no reasoning summaries unless this is set, so renderers show no thinking trace. |
 | `CODEX_MODEL_REASONING_EFFORT` | `sandbox.extraEnv`. | Overrides the Codex `model_reasoning_effort` (baked into `harness/codex/config.toml`) and Nanocodex's default thinking effort. It is mirrored into Slackbot so the first response footer displays the effective level. One of `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`; an unknown value is ignored (the config default stands). |
 | `CLAUDE_MODEL`, `CLAUDE_CONTINUE_SESSION_ID` | `sandbox.extraEnv` or runtime resume. | Claude model and resume behavior. |
diff --git a/services/api-rs/Cargo.lock b/services/api-rs/Cargo.lock
index 93123af92..3c741df3a 100644
--- a/services/api-rs/Cargo.lock
+++ b/services/api-rs/Cargo.lock
@@ -943,6 +943,7 @@ name = "centaur-iron-proxy"
 version = "0.1.0"
 dependencies = [
  "serde",
+ "serde_json",
  "serde_yaml",
  "strum",
  "thiserror 2.0.20",
@@ -4975,7 +4976,7 @@ dependencies = [
  "base64 0.21.7",
  "hmac-sha256",
  "http 1.4.2",
- "thiserror 2.0.19",
+ "thiserror 1.0.69",
  "time",
 ]
 
diff --git a/services/api-rs/crates/centaur-api-server/src/args.rs b/services/api-rs/crates/centaur-api-server/src/args.rs
index 3cb05d99d..da160b45a 100644
--- a/services/api-rs/crates/centaur-api-server/src/args.rs
+++ b/services/api-rs/crates/centaur-api-server/src/args.rs
@@ -20,7 +20,8 @@ use centaur_iron_control::{
     SessionRegistrar, register_role,
 };
 use centaur_iron_proxy::{
-    ProxyFragment, SourceKind, SourcePolicy, bedrock_enabled, harness_auth_fragment, infra_fragment,
+    ProxyFragment, SourceKind, SourcePolicy, bedrock_enabled, custom_provider_auth_fragments,
+    harness_auth_fragment, infra_fragment,
 };
 use centaur_sandbox_agent_k8s::{
     AgentSandboxBackend, AgentSandboxConfig, GitHubTokenRef, IronControlSettings, IronProxyConfig,
@@ -1964,6 +1965,9 @@ impl IronProxyHarnessArgs {
         if let Some(fragment) = harness_auth_fragment("meta-ai", "api_key")? {
             fragments.push(fragment);
         }
+        if let Ok(raw) = env::var("CODEX_CUSTOM_PROVIDERS") {
+            fragments.extend(custom_provider_auth_fragments(&raw)?);
+        }
         // Bedrock is opt-in (not the default codex provider): only register its
         // SigV4 re-signing fragment when the operator has set CODEX_BEDROCK_REGION,
         // since the fragment expects AWS keys in the secrets backend.
diff --git a/services/api-rs/crates/centaur-iron-proxy/Cargo.toml b/services/api-rs/crates/centaur-iron-proxy/Cargo.toml
index 0e083ccb9..c50a3e3de 100644
--- a/services/api-rs/crates/centaur-iron-proxy/Cargo.toml
+++ b/services/api-rs/crates/centaur-iron-proxy/Cargo.toml
@@ -7,6 +7,7 @@ repository.workspace = true
 
 [dependencies]
 serde.workspace = true
+serde_json.workspace = true
 serde_yaml.workspace = true
 strum.workspace = true
 thiserror.workspace = true
diff --git a/services/api-rs/crates/centaur-iron-proxy/src/error.rs b/services/api-rs/crates/centaur-iron-proxy/src/error.rs
index 6d9f902ab..fb4f7910d 100644
--- a/services/api-rs/crates/centaur-iron-proxy/src/error.rs
+++ b/services/api-rs/crates/centaur-iron-proxy/src/error.rs
@@ -9,6 +9,13 @@ pub enum IronProxyConfigError {
         path: PathBuf,
         source: serde_yaml::Error,
     },
+    #[error("failed to parse CODEX_CUSTOM_PROVIDERS: {source}")]
+    ParseCustomProviders { source: serde_json::Error },
+    #[error("invalid custom Codex provider {provider:?}: {reason}")]
+    InvalidCustomProvider {
+        provider: String,
+        reason: &'static str,
+    },
     #[error("invalid OPENAI_BASE_URL {value:?}: {reason}")]
     InvalidOpenAiBaseUrl { value: String, reason: String },
 }
diff --git a/services/api-rs/crates/centaur-iron-proxy/src/fragment.rs b/services/api-rs/crates/centaur-iron-proxy/src/fragment.rs
index c6a28d7f1..3999efb96 100644
--- a/services/api-rs/crates/centaur-iron-proxy/src/fragment.rs
+++ b/services/api-rs/crates/centaur-iron-proxy/src/fragment.rs
@@ -1,5 +1,7 @@
 use std::{collections::BTreeMap, path::PathBuf};
 
+use serde::Deserialize;
+
 use crate::{IronProxyConfigError, ProxyFragment, Result};
 
 /// The shared infra secrets, embedded at compile time so the binary carries no
@@ -14,6 +16,143 @@ pub fn load_fragment_str(contents: &str) -> Result<ProxyFragment> {
     })
 }
 
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+struct CustomProviderConfig {
+    name: String,
+    base_url: String,
+    api_key_env: String,
+    default_model: Option<String>,
+}
+
+/// Build hostname-scoped bearer-token replacements for operator-configured
+/// OpenAI-compatible Codex providers. The same JSON is consumed by the sandbox
+/// entrypoint, so provider config and proxy credentials share one source of
+/// truth without putting real keys in a sandbox.
+pub fn custom_provider_auth_fragments(raw: &str) -> Result<Vec<ProxyFragment>> {
+    if raw.trim().is_empty() {
+        return Ok(Vec::new());
+    }
+    let providers: BTreeMap<String, CustomProviderConfig> = serde_json::from_str(raw)
+        .map_err(|source| IronProxyConfigError::ParseCustomProviders { source })?;
+    providers
+        .into_iter()
+        .map(|(provider, config)| custom_provider_auth_fragment(&provider, config))
+        .collect()
+}
+
+fn custom_provider_auth_fragment(
+    provider: &str,
+    config: CustomProviderConfig,
+) -> Result<ProxyFragment> {
+    if !valid_provider_id(provider) {
+        return Err(invalid_custom_provider(
+            provider,
+            "id must match [a-z][a-z0-9_-]*",
+        ));
+    }
+    if config.name.trim().is_empty() {
+        return Err(invalid_custom_provider(provider, "name must not be empty"));
+    }
+    if config
+        .default_model
+        .as_ref()
+        .is_some_and(|model| model.trim().is_empty())
+    {
+        return Err(invalid_custom_provider(
+            provider,
+            "defaultModel must not be empty when set",
+        ));
+    }
+    if !valid_env_name(&config.api_key_env) {
+        return Err(invalid_custom_provider(
+            provider,
+            "apiKeyEnv must match [A-Z][A-Z0-9_]*",
+        ));
+    }
+    let host = https_dns_host(&config.base_url).ok_or_else(|| {
+        invalid_custom_provider(
+            provider,
+            "baseUrl must be an HTTPS URL with a DNS hostname and no explicit port",
+        )
+    })?;
+    load_fragment_str(&format!(
+        r#"
+transforms:
+  - name: secrets
+    config:
+      secrets:
+        - id: CODEX_CUSTOM_PROVIDER_{provider}_AUTHORIZATION
+          replace:
+            proxy_value: {api_key_env}
+            match_headers: ["Authorization"]
+          rules: [{{ host: {host} }}]
+"#,
+        api_key_env = config.api_key_env,
+    ))
+}
+
+fn invalid_custom_provider(provider: &str, reason: &'static str) -> IronProxyConfigError {
+    IronProxyConfigError::InvalidCustomProvider {
+        provider: provider.to_owned(),
+        reason,
+    }
+}
+
+fn valid_provider_id(value: &str) -> bool {
+    let mut characters = value.chars();
+    characters
+        .next()
+        .is_some_and(|character| character.is_ascii_lowercase())
+        && characters.all(|character| {
+            character.is_ascii_lowercase()
+                || character.is_ascii_digit()
+                || character == '_'
+                || character == '-'
+        })
+}
+
+fn valid_env_name(value: &str) -> bool {
+    let mut characters = value.chars();
+    characters
+        .next()
+        .is_some_and(|character| character.is_ascii_uppercase())
+        && characters.all(|character| {
+            character.is_ascii_uppercase() || character.is_ascii_digit() || character == '_'
+        })
+}
+
+fn https_dns_host(base_url: &str) -> Option<&str> {
+    let authority = base_url
+        .trim()
+        .strip_prefix("https://")?
+        .split('/')
+        .next()?;
+    let valid_dns_name = authority.len() <= 253
+        && authority
+            .chars()
+            .any(|character| character.is_ascii_alphabetic())
+        && authority.split('.').all(|label| {
+            !label.is_empty()
+                && label.len() <= 63
+                && label
+                    .chars()
+                    .all(|character| character.is_ascii_alphanumeric() || character == '-')
+                && label
+                    .chars()
+                    .next()
+                    .is_some_and(|character| character.is_ascii_alphanumeric())
+                && label
+                    .chars()
+                    .last()
+                    .is_some_and(|character| character.is_ascii_alphanumeric())
+        });
+    if !valid_dns_name {
+        return None;
+    }
+    Some(authority)
+}
+
 /// The harness auth fragment for ``engine`` and ``auth_mode``. These are infra
 /// — known in advance — so they are baked in rather than discovered from disk.
 /// Returns ``None`` for an unknown engine/mode pair.
diff --git a/services/api-rs/crates/centaur-iron-proxy/src/lib.rs b/services/api-rs/crates/centaur-iron-proxy/src/lib.rs
index d59cdb2b0..a9533c9e0 100644
--- a/services/api-rs/crates/centaur-iron-proxy/src/lib.rs
+++ b/services/api-rs/crates/centaur-iron-proxy/src/lib.rs
@@ -5,8 +5,8 @@ mod source;
 
 pub use error::{IronProxyConfigError, Result};
 pub use fragment::{
-    bedrock_enabled, bedrock_region, bedrock_sandbox_env, harness_auth_fragment, infra_fragment,
-    load_fragment_str, pg_sandbox_dsns, placeholder_env,
+    bedrock_enabled, bedrock_region, bedrock_sandbox_env, custom_provider_auth_fragments,
+    harness_auth_fragment, infra_fragment, load_fragment_str, pg_sandbox_dsns, placeholder_env,
 };
 pub use model::{
     PgDsnSetting, PgDsnSettingValueFrom, PostgresClient, PostgresListener, PostgresUpstream,
diff --git a/services/api-rs/crates/centaur-iron-proxy/src/tests.rs b/services/api-rs/crates/centaur-iron-proxy/src/tests.rs
index 75cf4c940..c591f58ad 100644
--- a/services/api-rs/crates/centaur-iron-proxy/src/tests.rs
+++ b/services/api-rs/crates/centaur-iron-proxy/src/tests.rs
@@ -73,6 +73,67 @@ fn harness_auth_fragments_are_baked_in() {
     }
 }
 
+#[test]
+fn custom_provider_fragments_are_scoped_and_declare_placeholders() {
+    let fragments = custom_provider_auth_fragments(
+        r#"{
+            "private_responses": {
+                "name": "Private Responses",
+                "baseUrl": "https://inference.example.com/v1",
+                "apiKeyEnv": "PRIVATE_RESPONSES_API_KEY",
+                "defaultModel": "example-model"
+            }
+        }"#,
+    )
+    .unwrap();
+    let placeholders = placeholder_env(&fragments);
+    assert_eq!(
+        placeholders
+            .get("PRIVATE_RESPONSES_API_KEY")
+            .map(String::as_str),
+        Some("PRIVATE_RESPONSES_API_KEY")
+    );
+
+    let yaml = serde_yaml::to_string(&fragments[0]).unwrap();
+    assert!(yaml.contains("host: inference.example.com"));
+    assert!(yaml.contains("proxy_value: PRIVATE_RESPONSES_API_KEY"));
+    assert!(!yaml.contains("https://"));
+}
+
+#[test]
+fn custom_provider_default_model_is_optional() {
+    let fragments = custom_provider_auth_fragments(
+        r#"{
+            "private_responses": {
+                "name": "Private Responses",
+                "baseUrl": "https://inference.example.com/v1",
+                "apiKeyEnv": "PRIVATE_RESPONSES_API_KEY"
+            }
+        }"#,
+    )
+    .unwrap();
+    assert_eq!(fragments.len(), 1);
+}
+
+#[test]
+fn custom_provider_fragments_reject_unsafe_or_malformed_config() {
+    for raw in [
+        r#"{"bad.id":{"name":"Bad","baseUrl":"https://inference.example.com/v1","apiKeyEnv":"BAD_API_KEY","defaultModel":"model"}}"#,
+        r#"{"private":{"name":"Bad","baseUrl":"http://inference.example.com/v1","apiKeyEnv":"BAD_API_KEY","defaultModel":"model"}}"#,
+        r#"{"private":{"name":"Bad","baseUrl":"https://user@inference.example.com/v1","apiKeyEnv":"BAD_API_KEY","defaultModel":"model"}}"#,
+        r#"{"private":{"name":"Bad","baseUrl":"https://inference.example.com:443/v1","apiKeyEnv":"BAD_API_KEY","defaultModel":"model"}}"#,
+        r#"{"private":{"name":"Bad","baseUrl":"https://127.0.0.1/v1","apiKeyEnv":"BAD_API_KEY","defaultModel":"model"}}"#,
+        r#"{"private":{"name":"Bad","baseUrl":"https://inference.example.com/v1","apiKeyEnv":"bad-key","defaultModel":"model"}}"#,
+        r#"{"private":{"name":"Bad","baseUrl":"https://inference.example.com/v1","apiKeyEnv":"BAD_API_KEY","defaultModel":""}}"#,
+        "not-json",
+    ] {
+        assert!(
+            custom_provider_auth_fragments(raw).is_err(),
+            "accepted {raw}"
+        );
+    }
+}
+
 #[test]
 fn pg_sandbox_dsns_reads_name_and_database_from_fragments() {
     // A listener with a sandbox_env (the api-rs-internal annotation api-rs
diff --git a/services/console/app/controllers/console/threads_controller.rb b/services/console/app/controllers/console/threads_controller.rb
index 3023e40ab..33e596f6c 100644
--- a/services/console/app/controllers/console/threads_controller.rb
+++ b/services/console/app/controllers/console/threads_controller.rb
@@ -90,7 +90,7 @@ class Console::ThreadsController < ApplicationController
   # Pseudo thread key that opens a new-chat composer pane in the split view.
   NEW_PANE_KEY = "new".freeze
 
-  # The composer's model selector, in display order. Each entry pins the
+  # The composer's built-in model selector, in display order. Each entry pins the
   # harness the choice runs on (wire values match api-rs's HarnessType enum,
   # serde lowercase); the model ids are the ones the bots' --model flags
   # expand to (services/slackbotv2/src/overrides.ts). Amp appears as a plain
@@ -99,7 +99,7 @@ class Console::ThreadsController < ApplicationController
   # Claude Opus 5's `fast` choice, which selects OpenRouter's native fast model
   # variant. Codex's enum lives in crates/harness-server/src/codex.rs, with
   # `max` being 5.6-specific.
-  ComposerAgent = Struct.new(:value, :label, :harness, :model, :efforts, keyword_init: true)
+  ComposerAgent = Struct.new(:value, :label, :harness, :model, :provider, :efforts, keyword_init: true)
   CODEX_EFFORTS = [
     %w[minimal Minimal],
     %w[low Low],
@@ -111,8 +111,9 @@ class Console::ThreadsController < ApplicationController
     [ "claude-opus-5", "fast" ] => "claude-opus-5-fast"
   }.freeze
   # First entry doubles as the default pick (unless the deploy's default-model
-  # resolution for its harness names another listed model).
-  COMPOSER_AGENTS = [
+  # resolution for its harness names another listed model). Operator-configured
+  # Codex providers are appended by .composer_agents at runtime.
+  BASE_COMPOSER_AGENTS = [
     ComposerAgent.new(value: "gpt-5.6-sol", label: "GPT-5.6 Sol",
                       harness: "codex", model: "gpt-5.6-sol",
                       efforts: CODEX_EFFORTS + [ %w[max Max] ]),
@@ -136,6 +137,30 @@ class Console::ThreadsController < ApplicationController
                       harness: "amp", model: nil, efforts: [])
   ].freeze
 
+  def self.custom_provider_agents(raw)
+    providers = JSON.parse(raw.presence || "{}")
+    return [] unless providers.is_a?(Hash)
+
+    providers.sort.filter_map do |provider_id, config|
+      next unless provider_id.match?(/\A[a-z][a-z0-9_-]*\z/) && config.is_a?(Hash)
+
+      label = config["name"].to_s.strip
+      model = config["defaultModel"].to_s.strip
+      next if label.blank? || model.blank?
+
+      ComposerAgent.new(
+        value: "provider:#{provider_id}", label: label,
+        harness: "codex", model: model, provider: provider_id, efforts: []
+      )
+    end
+  rescue JSON::ParserError
+    []
+  end
+
+  def self.composer_agents
+    BASE_COMPOSER_AGENTS + custom_provider_agents(ENV["CODEX_CUSTOM_PROVIDERS"])
+  end
+
   helper_method :thread_title,
                 :thread_source_icon,
                 :thread_source_label,
@@ -145,6 +170,7 @@ class Console::ThreadsController < ApplicationController
                 :thread_message_text,
                 :thread_text_preview,
                 :thread_status_classes,
+                :composer_agents,
                 :composer_agent_choices,
                 :composer_default_agent_value,
                 :composer_agents_json,
@@ -304,21 +330,21 @@ def thread_writable?(session)
   # claims a default the sandbox would not actually run.
   def composer_agent_choices
     default_value = composer_default_agent_value
-    COMPOSER_AGENTS
+    composer_agents
       .sort_by.with_index { |agent, index| agent.value == default_value ? -1 : index }
       .map { |agent| [ agent.label, agent.value ] }
   end
 
   def composer_default_agent_value
-    default = default_model_for_harness(COMPOSER_AGENTS.first.harness)
-    COMPOSER_AGENTS.find { |agent| agent.value == default }&.value ||
-      COMPOSER_AGENTS.first.value
+    default = default_model_for_harness(composer_agents.first.harness)
+    composer_agents.find { |agent| agent.value == default }&.value ||
+      composer_agents.first.value
   end
 
   # Per-agent metadata the picker script needs to rebuild the effort submenu
   # when the model changes: { value => { label:, efforts: [[value, label]] } }.
   def composer_agents_json
-    COMPOSER_AGENTS.to_h do |agent|
+    composer_agents.to_h do |agent|
       [ agent.value, { label: agent.label, efforts: agent.efforts } ]
     end.to_json
   end
@@ -337,7 +363,11 @@ def composer_model_for(agent, effort)
   def composer_agent_for(raw)
     value = raw.to_s.strip
     value = composer_default_agent_value if value.blank?
-    COMPOSER_AGENTS.find { |agent| agent.value == value }
+    composer_agents.find { |agent| agent.value == value }
+  end
+
+  def composer_agents
+    self.class.composer_agents
   end
 
   def start_thread(prompt)
@@ -357,9 +387,14 @@ def start_thread(prompt)
     api_client.create_session(
       thread_key: thread_key,
       harness_type: agent.harness,
-      metadata: console_actor_metadata.merge(model.present? ? { model: model } : {})
+      metadata: console_actor_metadata
+        .merge(model.present? ? { model: model } : {})
+        .merge(agent.provider.present? ? { provider: agent.provider } : {})
+    )
+    send_prompt(
+      thread_key, prompt,
+      model: model, provider: agent.provider, effort: reasoning
     )
-    send_prompt(thread_key, prompt, model: model, effort: reasoning)
     # A new-chat pane in a split view swaps the sentinel for the created
     # thread so the other panes stay open.
     open_keys = params[:open_threads].to_s.split(",").map(&:strip).reject(&:blank?)
@@ -380,7 +415,7 @@ def reply_to_thread(thread_key, prompt)
       return
     end
 
-    send_prompt(session.thread_key, prompt, model: reply_model_for(session))
+    send_prompt(session.thread_key, prompt, **reply_overrides_for(session))
     redirect_to console_threads_path(thread: reply_redirect_keys(session.thread_key))
   rescue CentaurApiClient::Error => e
     redirect_to console_threads_path(thread: reply_redirect_keys(thread_key)),
@@ -393,7 +428,7 @@ def reply_to_thread(thread_key, prompt)
   # Append persists the turn in conversation history; execute runs it. The
   # shared client_message_id lets api-rs dedupe the copy of the message the
   # harness echoes back.
-  def send_prompt(thread_key, prompt, model: nil, effort: nil)
+  def send_prompt(thread_key, prompt, model: nil, provider: nil, effort: nil)
     message_id = SecureRandom.uuid
 
     api_client.append_session_messages(
@@ -410,6 +445,7 @@ def send_prompt(thread_key, prompt, model: nil, effort: nil)
 
     execute_metadata = console_actor_metadata.merge(action: "execute")
     execute_metadata[:model] = model if model.present?
+    execute_metadata[:provider] = provider if provider.present?
     execute_metadata[:reasoning] = effort if effort.present?
     api_client.execute_session(
       thread_key: thread_key,
@@ -418,7 +454,7 @@ def send_prompt(thread_key, prompt, model: nil, effort: nil)
       input_lines: [
         composer_input_line(
           thread_key, prompt,
-          model: model, effort: effort, client_message_id: message_id
+          model: model, provider: provider, effort: effort, client_message_id: message_id
         )
       ]
     )
@@ -429,7 +465,7 @@ def send_prompt(thread_key, prompt, model: nil, effort: nil)
   # for Amp) the harness runs its own default. `reasoning` is the per-turn
   # codex effort; other harnesses discard it, and validation upstream only
   # accepts it for codex models anyway.
-  def composer_input_line(thread_key, prompt, model:, effort:, client_message_id:)
+  def composer_input_line(thread_key, prompt, model:, provider:, effort:, client_message_id:)
     line = {
       type: "user",
       thread_key: thread_key,
@@ -444,6 +480,7 @@ def composer_input_line(thread_key, prompt, model:, effort:, client_message_id:)
       }
     }
     line[:model] = model if model.present?
+    line[:provider] = provider if provider.present?
     line[:reasoning] = effort if effort.present?
     line.to_json
   end
@@ -478,10 +515,14 @@ def console_requester_context
   # Follow-ups reuse the model the chat has been running on (mirrors the
   # display resolution in thread_model_label, minus the upcasing): last
   # execution's recorded model, session metadata, then the deploy default.
-  def reply_model_for(session)
-    recorded_model(latest_executions_for([ session.thread_key ])[session.thread_key]&.metadata) ||
-      recorded_model(session.metadata_hash) ||
-      default_model_for_harness(session.harness_type.to_s)
+  def reply_overrides_for(session)
+    execution_metadata = latest_executions_for([ session.thread_key ])[session.thread_key]&.metadata
+    {
+      model: recorded_model(execution_metadata) ||
+        recorded_model(session.metadata_hash) ||
+        default_model_for_harness(session.harness_type.to_s),
+      provider: recorded_provider(execution_metadata) || recorded_provider(session.metadata_hash)
+    }
   end
 
   # Keeps split-view panes open across a composer submit: the form carries the
@@ -1503,6 +1544,12 @@ def recorded_model(metadata)
     metadata["model"].presence
   end
 
+  def recorded_provider(metadata)
+    return unless metadata.is_a?(Hash)
+
+    metadata["provider"].presence
+  end
+
   def default_model_for_harness(harness_type)
     env_name = HARNESS_DEFAULT_MODEL_ENVS[harness_type]
     return unless env_name
diff --git a/services/console/app/views/console/threads/_composer.html.erb b/services/console/app/views/console/threads/_composer.html.erb
index 78d14229e..44e90e0b0 100644
--- a/services/console/app/views/console/threads/_composer.html.erb
+++ b/services/console/app/views/console/threads/_composer.html.erb
@@ -33,7 +33,7 @@
       <span class="console-composer-spacer"></span>
       <% unless thread_mode %>
         <% default_value = composer_default_agent_value %>
-        <% default_agent = Console::ThreadsController::COMPOSER_AGENTS.find { |agent| agent.value == default_value } %>
+        <% default_agent = composer_agents.find { |agent| agent.value == default_value } %>
         <div class="console-composer-model"
              data-console-model-picker
              data-agents="<%= composer_agents_json %>">
diff --git a/services/console/test/controllers/console/threads_controller_test.rb b/services/console/test/controllers/console/threads_controller_test.rb
index dede481bb..0ddf2d6bd 100644
--- a/services/console/test/controllers/console/threads_controller_test.rb
+++ b/services/console/test/controllers/console/threads_controller_test.rb
@@ -1148,6 +1148,34 @@ class Console::ThreadsControllerTest < ActionDispatch::IntegrationTest
     assert_equal "gpt-5.5", create[:metadata][:model]
   end
 
+  test "a configured custom inference model pick uses its codex provider" do
+    client = RecordingApiClient.new
+    config = {
+      private_responses: {
+        name: "Private Responses",
+        baseUrl: "https://inference.example.com/v1",
+        apiKeyEnv: "PRIVATE_RESPONSES_API_KEY",
+        defaultModel: "example-model"
+      }
+    }.to_json
+    with_env("CODEX_CUSTOM_PROVIDERS" => config) do
+      with_composer(client: client) do
+        post console_threads_url,
+             params: { prompt: "Reply with PONG.", model: "provider:private_responses" }
+      end
+    end
+
+    create = client.calls[0].last
+    assert_equal "codex", create[:harness_type]
+    assert_equal "example-model", create[:metadata][:model]
+    assert_equal "private_responses", create[:metadata][:provider]
+
+    execute = client.calls[2].last
+    assert_equal "private_responses", execute[:metadata][:provider]
+    line = JSON.parse(execute[:input_lines].first)
+    assert_equal "private_responses", line["provider"]
+  end
+
   test "a codex chat carries the picked reasoning effort" do
     client = RecordingApiClient.new
     with_composer(client: client) do
diff --git a/services/githubbot/README.md b/services/githubbot/README.md
index 6eca57969..ba42f1415 100644
--- a/services/githubbot/README.md
+++ b/services/githubbot/README.md
@@ -56,7 +56,7 @@ reviewer** like any other collaborator.
   `GITHUBBOT_ISSUE_PROMPT` / `GITHUBBOT_ISSUE_PROMPT_FILE` (used verbatim, like the review prompt).
 - **Per-turn context**: every turn prepends a compact header naming the PR/issue so a recycled
   sandbox always knows which subject to act on and where to reply.
-- `--claude` / `--codex` / `--amp` / `--model …` / `--opus|--sonnet|--haiku` inline flags pick the
+- `--claude` / `--codex` / `--amp` / `--provider …` / `--model …` / `--opus|--sonnet|--haiku` inline flags pick the
   harness/model, same as the other bots.
 
 ## PR self-management (v2)
diff --git a/services/githubbot/src/index.ts b/services/githubbot/src/index.ts
index 12dd5d9f8..4bc4c26aa 100644
--- a/services/githubbot/src/index.ts
+++ b/services/githubbot/src/index.ts
@@ -302,7 +302,11 @@ async function handleMessage(
         contextPreamble: githubContextPreamble(threadKey, reviewComment),
         executeMessage: serialized,
         options,
-        overrides: { harnessType: overrides.harnessType, model: overrides.model },
+        overrides: {
+          harnessType: overrides.harnessType,
+          model: overrides.model,
+          provider: overrides.provider,
+        },
         reactMessageId: message.id,
         sessionThreadKey,
         thread,
diff --git a/services/githubbot/src/overrides.ts b/services/githubbot/src/overrides.ts
index f33a79cb4..945c756ee 100644
--- a/services/githubbot/src/overrides.ts
+++ b/services/githubbot/src/overrides.ts
@@ -2,6 +2,7 @@
  * Inline message directives, cloned from slackbotv2 (which restored them from
  * the v1 slackbot):
  *   --claude | --claude-code | --amp | --codex   pick the harness for the thread
+ *   --provider <name>                            codex via a configured provider
  *   --model <name> (or --model=<name>)           pick the model within that harness
  *   --fable | --opus | --sonnet | --haiku        model shortcuts (imply claude-code)
  *
@@ -16,6 +17,12 @@ export type MessageOverrides = {
   cleanedText: string;
   harnessType?: string;
   model?: string;
+  provider?: string;
+};
+
+export type StickyProviderResolution = {
+  provider?: string;
+  update?: string | null;
 };
 
 // Flag name -> HarnessType wire value (serde lowercase of the Rust enum).
@@ -46,11 +53,14 @@ const MODEL_SHORTCUTS: Record<string, { harnessType: string; model: string }> =
   );
 
 const MODEL_FLAG_PATTERN = /(?:^|\s)--model[=\s]+([A-Za-z0-9._/-]+)(?=\s|$)/i;
+const PROVIDER_FLAG_PATTERN =
+  /(?:^|\s)--provider[=\s]+([A-Za-z][A-Za-z0-9_-]*)(?=\s|$)/i;
 
 export function extractMessageOverrides(text: string): MessageOverrides {
   let cleaned = text;
   let harnessType: string | undefined;
   let model: string | undefined;
+  let provider: string | undefined;
 
   const modelMatch = MODEL_FLAG_PATTERN.exec(cleaned);
   if (modelMatch) {
@@ -59,6 +69,14 @@ export function extractMessageOverrides(text: string): MessageOverrides {
     cleaned = stripMatch(cleaned, modelMatch);
   }
 
+  const providerMatch = PROVIDER_FLAG_PATTERN.exec(cleaned);
+  if (providerMatch) {
+    provider = providerMatch[1]!.toLowerCase();
+    harnessType ??= "codex";
+    model ??= customProviderDefaultModel(provider);
+    cleaned = stripMatch(cleaned, providerMatch);
+  }
+
   for (const [flag, harness] of Object.entries(HARNESS_FLAGS)) {
     const match = flagPattern(flag).exec(cleaned);
     if (!match) continue;
@@ -78,9 +96,39 @@ export function extractMessageOverrides(text: string): MessageOverrides {
     cleanedText: cleaned === text ? text : cleaned.trim(),
     harnessType,
     model,
+    ...(provider ? { provider } : {}),
   };
 }
 
+/**
+ * Resolve the provider fixed at Codex thread start. A provider selection stays
+ * sticky across later turns, while an explicit harness switch clears it.
+ * `update` is omitted when persisted state should remain unchanged; null is a
+ * deliberate tombstone for a previous selection.
+ */
+export function resolveStickyProvider(
+  current: string | null | undefined,
+  overrides: Pick<MessageOverrides, "harnessType" | "provider">,
+): StickyProviderResolution {
+  if (overrides.provider) {
+    return { provider: overrides.provider, update: overrides.provider };
+  }
+  if (overrides.harnessType) return { update: null };
+  return current ? { provider: current } : {};
+}
+
+function customProviderDefaultModel(provider: string): string | undefined {
+  const raw = process.env.CODEX_CUSTOM_PROVIDERS;
+  if (!raw) return undefined;
+  try {
+    const config = JSON.parse(raw)?.[provider];
+    const model = config?.defaultModel;
+    return typeof model === "string" && model.trim() ? model.trim() : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 function flagPattern(flag: string): RegExp {
   return new RegExp(
     `(?:^|\\s)--${flag.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?=\\s|$)`,
diff --git a/services/githubbot/src/session-api.ts b/services/githubbot/src/session-api.ts
index bbc6ccd35..c2c4262f4 100644
--- a/services/githubbot/src/session-api.ts
+++ b/services/githubbot/src/session-api.ts
@@ -190,6 +190,7 @@ export async function forwardToSessionApi(
     input.threadId,
     input.executeMessage,
     input.model,
+    input.provider,
     input.contextPreamble,
   );
   traceLog(options, "githubbot_session_execute_complete", input.trace, {
@@ -220,6 +221,7 @@ export async function executeSessionTurn(
     input.threadId,
     input.executeMessage,
     input.model,
+    input.provider,
     input.contextPreamble,
   );
   traceLog(options, "githubbot_session_execute_complete", input.trace, {
@@ -509,13 +511,14 @@ async function executeSession(
   threadId: string,
   message: GithubbotApiMessage,
   model?: string,
+  provider?: string,
   contextPreamble?: string,
 ): Promise<GithubbotExecuteSessionResponse> {
   const fetchFn = options.fetch ?? fetch;
   const body: GithubbotExecuteSessionRequest = {
     idempotency_key: message.id,
     metadata: sessionMetadata(message, { action: "execute" }),
-    input_lines: toCodexInputLines(message, threadId, model, contextPreamble),
+    input_lines: toCodexInputLines(message, threadId, model, provider, contextPreamble),
     ...(options.idleTimeoutMs === undefined
       ? {}
       : { idle_timeout_ms: options.idleTimeoutMs }),
@@ -741,6 +744,7 @@ function toCodexInputLines(
   message: GithubbotApiMessage,
   threadId: string,
   model?: string,
+  provider?: string,
   contextPreamble?: string,
 ): string[] {
   const staged = new Map<GithubbotApiAttachment, string>();
@@ -774,6 +778,7 @@ function toCodexInputLines(
     threadId,
     staged,
     model,
+    provider,
     contextPreamble,
   );
   if (inlineLine.length > MAX_CODEX_INPUT_LINE_CHARS) {
@@ -787,6 +792,7 @@ function toCodexInputLines(
         threadId,
         staged,
         model,
+        provider,
         contextPreamble,
       );
       if (inlineLine.length <= MAX_CODEX_INPUT_LINE_CHARS) break;
@@ -801,6 +807,7 @@ function toCodexInputLineWithStaged(
   threadId: string,
   staged: Map<GithubbotApiAttachment, string>,
   model?: string,
+  provider?: string,
   contextPreamble?: string,
 ): string {
   return JSON.stringify({
@@ -808,6 +815,7 @@ function toCodexInputLineWithStaged(
     thread_key: threadId,
     trace_metadata: sessionMetadata(message, { action: "execute" }),
     ...(model ? { model } : {}),
+    ...(provider ? { provider } : {}),
     message: {
       role: "user",
       content: codexInputContent(message, staged, contextPreamble),
diff --git a/services/githubbot/src/turn.ts b/services/githubbot/src/turn.ts
index b6c4022bc..ed5ef47dd 100644
--- a/services/githubbot/src/turn.ts
+++ b/services/githubbot/src/turn.ts
@@ -7,6 +7,7 @@ import type { GitHubAdapter } from "@chat-adapter/github";
 import type { Thread } from "chat";
 import { buildCommentReplyBody, CommentReplyCollector } from "./comment-bot";
 import { runExclusive } from "./context";
+import { resolveStickyProvider } from "./overrides";
 import {
   executeSessionTurn,
   forwardToSessionApi,
@@ -262,7 +263,7 @@ export async function runSessionTurn(input: {
   conversationName?: string;
   executeMessage: GithubbotApiMessage;
   options: GithubbotOptions;
-  overrides: { harnessType?: string; model?: string };
+  overrides: { harnessType?: string; model?: string; provider?: string };
   /** Comment to react to (👀 → 🚀/😕); the triggering comment, if any. */
   reactMessageId?: string;
   /**
@@ -291,6 +292,12 @@ export async function runSessionTurn(input: {
   // The 👀 working ack is fired by the caller (handleMessage) before this turn's
   // setup so it lands instantly; here we only settle it to 🚀/😕 at the end.
   const threadState = (await thread.state) ?? {};
+  const provider = resolveStickyProvider(threadState.provider, overrides);
+  if (provider.update !== undefined) {
+    // Commit the selection before execution so a bot/sandbox crash cannot lose
+    // the provider needed to resume this Codex thread on the next turn.
+    await thread.setState({ provider: provider.update });
+  }
   let lastEventId = threadState.lastEventId ?? 0;
   const forwardInput: ForwardSessionInput = {
     afterEventId: lastEventId,
@@ -300,6 +307,7 @@ export async function runSessionTurn(input: {
     harnessType: overrides.harnessType,
     messages: [],
     model: overrides.model,
+    provider: provider.provider,
     onEventId: (eventId) => {
       lastEventId = Math.max(lastEventId, eventId);
       forwardInput.afterEventId = lastEventId;
diff --git a/services/githubbot/src/types.ts b/services/githubbot/src/types.ts
index 68da36e02..fd94a6600 100644
--- a/services/githubbot/src/types.ts
+++ b/services/githubbot/src/types.ts
@@ -179,6 +179,8 @@ export type Githubbot = {
 export type GithubbotThreadState = {
   /** Set once the thread's first turn has run (gates follow-up ingestion). */
   historyForwarded?: boolean;
+  /** Codex provider pinned for this thread. Null clears a previous selection. */
+  provider?: string | null;
   /**
    * Set once the full PR/issue context (with body) has ridden a turn's execute;
    * later turns prepend only the compact header instead.
@@ -243,6 +245,8 @@ export type ForwardSessionInput = {
   messages: GithubbotApiMessage[];
   /** Per-turn model override parsed from message flags (--model/--opus/...). */
   model?: string;
+  /** Effective model provider selected by a message flag; codex only. */
+  provider?: string;
   onEventId(eventId: number): void;
   openStream: boolean;
   threadId: string;
diff --git a/services/githubbot/test/overrides.test.ts b/services/githubbot/test/overrides.test.ts
index 139012f82..9587f8966 100644
--- a/services/githubbot/test/overrides.test.ts
+++ b/services/githubbot/test/overrides.test.ts
@@ -1,5 +1,8 @@
 import { describe, expect, test } from "bun:test";
-import { extractMessageOverrides } from "../src/overrides";
+import {
+  extractMessageOverrides,
+  resolveStickyProvider,
+} from "../src/overrides";
 
 describe("extractMessageOverrides", () => {
   test("returns text untouched without flags", () => {
@@ -62,6 +65,37 @@ describe("extractMessageOverrides", () => {
     });
   });
 
+  test("--provider selects an arbitrary codex provider", () => {
+    expect(
+      extractMessageOverrides(
+        "--provider private_responses --model example-model audit this",
+      ),
+    ).toEqual({
+      cleanedText: "audit this",
+      harnessType: "codex",
+      model: "example-model",
+      provider: "private_responses",
+    });
+  });
+
+  test("--provider uses the configured provider default model", () => {
+    const previous = process.env.CODEX_CUSTOM_PROVIDERS;
+    process.env.CODEX_CUSTOM_PROVIDERS = JSON.stringify({
+      private_responses: { defaultModel: "configured-model" },
+    });
+    try {
+      expect(extractMessageOverrides("--provider=private_responses audit this")).toEqual({
+        cleanedText: "audit this",
+        harnessType: "codex",
+        model: "configured-model",
+        provider: "private_responses",
+      });
+    } finally {
+      if (previous === undefined) delete process.env.CODEX_CUSTOM_PROVIDERS;
+      else process.env.CODEX_CUSTOM_PROVIDERS = previous;
+    }
+  });
+
   test("model shortcuts set model and imply claude-code", () => {
     expect(extractMessageOverrides("--opus fix it")).toEqual({
       cleanedText: "fix it",
@@ -137,3 +171,28 @@ describe("extractMessageOverrides", () => {
     });
   });
 });
+
+describe("resolveStickyProvider", () => {
+  test("persists a selected provider and reuses it on later turns", () => {
+    expect(
+      resolveStickyProvider(undefined, {
+        harnessType: "codex",
+        provider: "private_responses",
+      }),
+    ).toEqual({
+      provider: "private_responses",
+      update: "private_responses",
+    });
+    expect(resolveStickyProvider("private_responses", {})).toEqual({
+      provider: "private_responses",
+    });
+  });
+
+  test("an explicit harness switch clears a previous provider", () => {
+    expect(
+      resolveStickyProvider("private_responses", {
+        harnessType: "claudecode",
+      }),
+    ).toEqual({ update: null });
+  });
+});
diff --git a/services/linearbot/src/index.ts b/services/linearbot/src/index.ts
index 31443f585..81d7de443 100644
--- a/services/linearbot/src/index.ts
+++ b/services/linearbot/src/index.ts
@@ -53,7 +53,7 @@ import {
   updateIssueState,
   type LinearStatusMarker,
 } from "./linear-status";
-import { extractMessageOverrides } from "./overrides";
+import { extractMessageOverrides, resolveStickyProvider } from "./overrides";
 import {
   executeSessionTurn,
   forwardToSessionApi,
@@ -769,6 +769,12 @@ async function runThreadTurn(input: {
     }
   }
   const threadState = (await thread.state) ?? {};
+  const provider = resolveStickyProvider(threadState.provider, overrides);
+  if (provider.update !== undefined) {
+    // Commit the selection before execution so a bot/sandbox crash cannot lose
+    // the provider needed to resume this Codex thread on the next turn.
+    await thread.setState({ provider: provider.update });
+  }
   // Resolve the issue context up front — including whether it's delegated to us.
   // The context rides inline in the execute (contextPreamble lands directly in
   // the prompt's input lines) rather than as a one-time appended session
@@ -832,7 +838,7 @@ async function runThreadTurn(input: {
     harnessType: overrides.harnessType,
     messages: [],
     model: overrides.model,
-    provider: overrides.provider,
+    provider: provider.provider,
     onEventId: (eventId) => {
       lastEventId = Math.max(lastEventId, eventId);
       // Keep afterEventId in sync so a mid-stream retry resumes after the last
diff --git a/services/linearbot/src/overrides.ts b/services/linearbot/src/overrides.ts
index 72cc90fad..8bdd654eb 100644
--- a/services/linearbot/src/overrides.ts
+++ b/services/linearbot/src/overrides.ts
@@ -3,6 +3,7 @@
  * the v1 slackbot):
  *   --claude | --claude-code | --amp | --codex   pick the harness for the thread
  *   --meta                                       codex via Meta AI direct
+ *   --provider <name>                            codex via a configured provider
  *   --model <name> (or --model=<name>)           pick the model within that harness
  *   --fable | --opus | --sonnet | --haiku        model shortcuts (imply claude-code)
  *
@@ -20,6 +21,11 @@ export type MessageOverrides = {
   provider?: string;
 };
 
+export type StickyProviderResolution = {
+  provider?: string;
+  update?: string | null;
+};
+
 // Flag name -> HarnessType wire value (serde lowercase of the Rust enum).
 const HARNESS_FLAGS: Record<string, string> = {
   amp: "amp",
@@ -30,7 +36,9 @@ const HARNESS_FLAGS: Record<string, string> = {
   nanocodex: "nanocodex",
 };
 
-const PROVIDER_FLAGS: Record<string, { provider: string; harnessType: string }> = {
+type ProviderMapping = { provider: string; harnessType: string; model?: string };
+
+const PROVIDER_FLAGS: Record<string, ProviderMapping> = {
   meta: { provider: "responses", harnessType: "codex" },
 };
 
@@ -61,6 +69,11 @@ const MODEL_FLAG_PATTERN = new RegExp(
   "i",
 );
 
+const PROVIDER_FLAG_PATTERN = new RegExp(
+  String.raw`(?:^|\s)--provider${MODEL_VALUE_SEPARATOR}([A-Za-z][A-Za-z0-9_-]*)${FLAG_VALUE_BOUNDARY}`,
+  "i",
+);
+
 export function extractMessageOverrides(text: string): MessageOverrides {
   let cleaned = text;
   let harnessType: string | undefined;
@@ -74,6 +87,15 @@ export function extractMessageOverrides(text: string): MessageOverrides {
     cleaned = stripMatch(cleaned, modelMatch);
   }
 
+  const providerMatch = PROVIDER_FLAG_PATTERN.exec(cleaned);
+  if (providerMatch) {
+    const mapping = providerMapping(providerMatch[1]!);
+    provider = mapping.provider;
+    harnessType ??= mapping.harnessType;
+    model ??= mapping.model;
+    cleaned = stripMatch(cleaned, providerMatch);
+  }
+
   for (const [flag, harness] of Object.entries(HARNESS_FLAGS)) {
     const match = flagPattern(flag).exec(cleaned);
     if (!match) continue;
@@ -94,6 +116,7 @@ export function extractMessageOverrides(text: string): MessageOverrides {
     if (!match) continue;
     provider ??= mapping.provider;
     harnessType ??= mapping.harnessType;
+    model ??= mapping.model;
     cleaned = stripMatch(cleaned, match);
   }
 
@@ -105,6 +128,46 @@ export function extractMessageOverrides(text: string): MessageOverrides {
   };
 }
 
+/**
+ * Resolve the provider fixed at Codex thread start. A provider selection stays
+ * sticky across later turns, while an explicit harness switch clears it.
+ * `update` is omitted when persisted state should remain unchanged; null is a
+ * deliberate tombstone for a previous selection.
+ */
+export function resolveStickyProvider(
+  current: string | null | undefined,
+  overrides: Pick<MessageOverrides, "harnessType" | "provider">,
+): StickyProviderResolution {
+  if (overrides.provider) {
+    return { provider: overrides.provider, update: overrides.provider };
+  }
+  if (overrides.harnessType) return { update: null };
+  return current ? { provider: current } : {};
+}
+
+function providerMapping(value: string): ProviderMapping {
+  const provider = value.toLowerCase();
+  return (
+    PROVIDER_FLAGS[provider] ?? {
+      provider,
+      harnessType: "codex",
+      model: customProviderDefaultModel(provider),
+    }
+  );
+}
+
+function customProviderDefaultModel(provider: string): string | undefined {
+  const raw = process.env.CODEX_CUSTOM_PROVIDERS;
+  if (!raw) return undefined;
+  try {
+    const config = JSON.parse(raw)?.[provider];
+    const model = config?.defaultModel;
+    return typeof model === "string" && model.trim() ? model.trim() : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 function flagPattern(flag: string): RegExp {
   return new RegExp(
     `(?:^|\\s)--${flag.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?=\\s|$)`,
diff --git a/services/linearbot/src/types.ts b/services/linearbot/src/types.ts
index 85aa52eb0..a10a64d8e 100644
--- a/services/linearbot/src/types.ts
+++ b/services/linearbot/src/types.ts
@@ -130,6 +130,8 @@ export type Linearbot = {
 export type LinearbotThreadState = {
   /** Set once the thread's first turn has run (gates follow-up ingestion). */
   historyForwarded?: boolean;
+  /** Codex provider pinned for this thread. Null clears a previous selection. */
+  provider?: string | null;
   /**
    * Set once the full issue context (with description) has ridden a turn's
    * execute; later turns prepend only the compact id/title header instead.
diff --git a/services/linearbot/test/chat-sdk-emulate.test.ts b/services/linearbot/test/chat-sdk-emulate.test.ts
index 992159174..243f01d39 100644
--- a/services/linearbot/test/chat-sdk-emulate.test.ts
+++ b/services/linearbot/test/chat-sdk-emulate.test.ts
@@ -190,6 +190,52 @@ describe("linearbot comment-thread pipeline", () => {
     ).toBe(false);
   });
 
+  it("reuses a persisted Codex provider on a later turn", async () => {
+    const threadKey = `linear:${ISSUE_ID}:c:comment-provider`;
+    await postWebhook(
+      commentCreatedPayload({
+        id: "comment-provider",
+        body: "@centaur --provider private_responses --model example-model first",
+      }),
+    );
+    await waitFor(() =>
+      codexApi.executes.some((e) => e.threadKey === threadKey),
+    );
+    codexApi.emitOutputLines(threadKey, sampleCodexOutputLines("One."));
+    await waitFor(() =>
+      linearApi.botComments.some(
+        (c) => c.parentId === "comment-provider" && c.body.includes("One."),
+      ),
+    );
+
+    await postWebhook(
+      commentCreatedPayload({
+        id: "comment-provider-2",
+        parentId: "comment-provider",
+        body: "@centaur second",
+      }),
+    );
+    await waitFor(
+      () =>
+        codexApi.executes.filter((e) => e.threadKey === threadKey).length === 2,
+    );
+    const secondExecute = codexApi.executes
+      .filter((e) => e.threadKey === threadKey)
+      .at(-1)!;
+    const secondInput = JSON.parse(secondExecute.body.input_lines.at(-1)!) as {
+      provider?: string;
+    };
+    expect(secondInput.provider).toBe("private_responses");
+
+    codexApi.emitOutputLines(threadKey, sampleCodexOutputLines("Two."));
+    await waitFor(() =>
+      linearApi.botComments.some(
+        (c) =>
+          c.parentId === "comment-provider" && c.body.includes("Two."),
+      ),
+    );
+  });
+
   it("posts a live 'Thinking…' comment on the first thought, then swaps it to the answer in place", async () => {
     const threadKey = `linear:${ISSUE_ID}:c:comment-live`;
     await postWebhook(
diff --git a/services/linearbot/test/overrides.test.ts b/services/linearbot/test/overrides.test.ts
index b1ffab135..3cc5396aa 100644
--- a/services/linearbot/test/overrides.test.ts
+++ b/services/linearbot/test/overrides.test.ts
@@ -1,5 +1,8 @@
 import { describe, expect, test } from "bun:test";
-import { extractMessageOverrides } from "../src/overrides";
+import {
+  extractMessageOverrides,
+  resolveStickyProvider,
+} from "../src/overrides";
 
 describe("extractMessageOverrides", () => {
   test("returns text untouched without flags", () => {
@@ -88,6 +91,37 @@ describe("extractMessageOverrides", () => {
     });
   });
 
+  test("--provider selects an arbitrary codex provider", () => {
+    expect(
+      extractMessageOverrides(
+        "--provider private_responses --model example-model audit this",
+      ),
+    ).toEqual({
+      cleanedText: "audit this",
+      harnessType: "codex",
+      model: "example-model",
+      provider: "private_responses",
+    });
+  });
+
+  test("--provider uses the configured provider default model", () => {
+    const previous = process.env.CODEX_CUSTOM_PROVIDERS;
+    process.env.CODEX_CUSTOM_PROVIDERS = JSON.stringify({
+      private_responses: { defaultModel: "configured-model" },
+    });
+    try {
+      expect(extractMessageOverrides("--provider=private_responses audit this")).toEqual({
+        cleanedText: "audit this",
+        harnessType: "codex",
+        model: "configured-model",
+        provider: "private_responses",
+      });
+    } finally {
+      if (previous === undefined) delete process.env.CODEX_CUSTOM_PROVIDERS;
+      else process.env.CODEX_CUSTOM_PROVIDERS = previous;
+    }
+  });
+
   test("--model expands claude aliases to full model ids", () => {
     expect(extractMessageOverrides("--claude --model opus go")).toEqual({
       cleanedText: "go",
@@ -178,3 +212,28 @@ describe("extractMessageOverrides", () => {
     });
   });
 });
+
+describe("resolveStickyProvider", () => {
+  test("persists a selected provider and reuses it on later turns", () => {
+    expect(
+      resolveStickyProvider(undefined, {
+        harnessType: "codex",
+        provider: "private_responses",
+      }),
+    ).toEqual({
+      provider: "private_responses",
+      update: "private_responses",
+    });
+    expect(resolveStickyProvider("private_responses", {})).toEqual({
+      provider: "private_responses",
+    });
+  });
+
+  test("an explicit harness switch clears a previous provider", () => {
+    expect(
+      resolveStickyProvider("private_responses", {
+        harnessType: "claudecode",
+      }),
+    ).toEqual({ update: null });
+  });
+});
diff --git a/services/sandbox/SYSTEM_PROMPT.md b/services/sandbox/SYSTEM_PROMPT.md
index ebfed47a9..0783f030d 100644
--- a/services/sandbox/SYSTEM_PROMPT.md
+++ b/services/sandbox/SYSTEM_PROMPT.md
@@ -38,7 +38,7 @@
 |Model selector: `--model <model-id-or-alias>` or `--model=<model-id-or-alias>`.
 |Claude shortcuts: `--fable`, `--opus`, `--sonnet`, and `--haiku`; these imply the Claude Code harness. The same aliases also work as `--model fable`, `--model opus`, `--model sonnet`, or `--model haiku`.
 |Good examples to show: `--claude --model=fable fix this`, `--codex --model=gpt-5.2 investigate this`, `--amp --model fast review this`, or `--opus implement the change`.
-|Slack-specific extras: `--meta` selects Codex with the Meta provider, `--bedrock` selects Codex with the Bedrock provider, and `-rsn <effort>` sets Codex reasoning effort for that turn.
+|Provider extras: `--meta` selects Codex with the Meta provider, `--bedrock` selects Codex with the Bedrock provider, `--provider <provider-id>` selects an operator-configured Codex provider, and `-rsn <effort>` sets Codex reasoning effort for that turn. Pair a custom provider with `--model <model-id>` unless it has a configured default.
 |If changing the harness on an existing thread, mention that the thread may restart on the requested harness and re-read the thread context.
 
 [Research and Grounding]
diff --git a/services/sandbox/entrypoint.sh b/services/sandbox/entrypoint.sh
index 479e31cd8..d4b4ad66a 100644
--- a/services/sandbox/entrypoint.sh
+++ b/services/sandbox/entrypoint.sh
@@ -246,6 +246,37 @@ if bedrock_region:
         ).setdefault("aws", {})["region"] = bedrock_region
         text = tomli_w.dumps(config)
 
+# CODEX_CUSTOM_PROVIDERS is the chart-rendered map of private OpenAI-compatible
+# Responses providers. Codex reads placeholder API keys from the environment;
+# iron-proxy replaces each one only for its configured base URL's host. Applied
+# before CODEX_CONFIG_OVERLAY so operators can still override provider details.
+custom_providers_raw = (os.environ.get("CODEX_CUSTOM_PROVIDERS") or "").strip()
+if custom_providers_raw:
+    import json
+    import tomllib
+    import tomli_w
+
+    try:
+        custom_providers = json.loads(custom_providers_raw)
+        if not isinstance(custom_providers, dict):
+            raise ValueError("expected an object keyed by provider id")
+        config = tomllib.loads(text)
+        model_providers = config.setdefault("model_providers", {})
+        for provider_id, provider in custom_providers.items():
+            if not isinstance(provider, dict):
+                raise ValueError(f"provider {provider_id!r} must be an object")
+            model_providers[provider_id] = {
+                "name": provider["name"],
+                "base_url": provider["baseUrl"],
+                "env_key": provider["apiKeyEnv"],
+                "wire_api": "responses",
+                "requires_openai_auth": False,
+            }
+    except (json.JSONDecodeError, KeyError, TypeError, ValueError, tomllib.TOMLDecodeError) as exc:
+        print(f"ignoring invalid CODEX_CUSTOM_PROVIDERS: {exc}", file=sys.stderr)
+    else:
+        text = tomli_w.dumps(config)
+
 # CODEX_CONFIG_OVERLAY: deep-merge an operator-supplied TOML fragment over the
 # baked config so a deployment can configure codex -- e.g. point it at a custom
 # model provider via a [model_providers.*] block -- through sandbox.extraEnv,
diff --git a/services/slackbotv2/src/overrides.ts b/services/slackbotv2/src/overrides.ts
index 31c2694e1..2ede28e83 100644
--- a/services/slackbotv2/src/overrides.ts
+++ b/services/slackbotv2/src/overrides.ts
@@ -4,6 +4,7 @@
  *                                                  pick the harness for the thread
  *   --bedrock                                    codex via the AWS Bedrock provider
  *   --meta                                       codex via Meta AI direct
+ *   --provider <name>                            codex via a configured provider
  *   --model <name> (or --model=<name>)           pick the model within that harness
  *   -rsn <effort> (or -rsn=<effort>)             per-turn reasoning effort (codex/nanocodex)
  *   --fable | --opus | --sonnet | --haiku        model shortcuts (imply claude-code)
@@ -51,7 +52,9 @@ const HARNESS_FLAGS: Record<string, string> = {
 // Provider flags select a model provider within the codex harness (and imply
 // it). Bedrock rides codex's built-in `amazon-bedrock` provider, whose wire
 // value is passed through as the blocks-protocol `provider` field.
-const PROVIDER_FLAGS: Record<string, { provider: string; harnessType: string }> = {
+type ProviderMapping = { provider: string; harnessType: string; model?: string }
+
+const PROVIDER_FLAGS: Record<string, ProviderMapping> = {
   bedrock: { provider: 'amazon-bedrock', harnessType: 'codex' },
   meta: { provider: 'responses', harnessType: 'codex' }
 }
@@ -117,6 +120,11 @@ const MODEL_FLAG_PATTERN = new RegExp(
   'i'
 )
 
+const PROVIDER_FLAG_PATTERN = new RegExp(
+  String.raw`(?:^|\s)--provider${MODEL_VALUE_SEPARATOR}([A-Za-z][A-Za-z0-9_-]*)${FLAG_VALUE_BOUNDARY}`,
+  'i'
+)
+
 // Single dash by design: a short per-turn knob (`-rsn high`), so it can't reuse
 // the `--`-prefixed flagPattern() helper. Value-capturing like --model.
 const REASONING_FLAG_PATTERN = new RegExp(
@@ -163,6 +171,15 @@ export function extractMessageOverrides(text: string): MessageOverrides {
     }
   }
 
+  const providerMatch = PROVIDER_FLAG_PATTERN.exec(cleaned)
+  if (providerMatch) {
+    const mapping = providerMapping(providerMatch[1]!)!
+    provider = mapping.provider
+    harnessType ??= mapping.harnessType
+    model ??= mapping.model
+    cleaned = stripMatch(cleaned, providerMatch)
+  }
+
   for (const [flag, harness] of Object.entries(HARNESS_FLAGS)) {
     const match = flagPattern(flag).exec(cleaned)
     if (!match) continue
@@ -183,6 +200,7 @@ export function extractMessageOverrides(text: string): MessageOverrides {
     if (!match) continue
     provider ??= mapping.provider
     harnessType ??= mapping.harnessType
+    model ??= mapping.model
     cleaned = stripMatch(cleaned, match)
   }
 
@@ -252,7 +270,8 @@ export function validateStrategyOverrides(
  * `{ harness, model, provider, reasoning }` config through the same vocabulary
  * as the flag parser (harness/provider/model aliases; a provider implies its
  * harness, like `--bedrock`). Fields are independent; unrecognized harness /
- * provider / reasoning values are reported via `onError` and dropped.
+ * reasoning values and malformed provider ids are reported via `onError` and
+ * dropped.
  */
 export function normalizeHarnessOverrides(
   raw: { harness?: unknown; model?: unknown; provider?: unknown; reasoning?: unknown },
@@ -271,12 +290,13 @@ export function normalizeHarnessOverrides(
 
   const providerRaw = cleanString(raw.provider)
   if (providerRaw) {
-    const mapping = PROVIDER_FLAGS[providerRaw.toLowerCase()]
+    const mapping = providerMapping(providerRaw)
     if (mapping) {
       provider = mapping.provider
       harnessType ??= mapping.harnessType // a provider implies its harness, like --bedrock
+      model ??= mapping.model
     } else {
-      onError?.(`unknown provider "${providerRaw}"`)
+      onError?.(`invalid provider id "${providerRaw}"`)
     }
   }
 
@@ -298,6 +318,30 @@ function cleanString(value: unknown): string | undefined {
   return trimmed === '' ? undefined : trimmed
 }
 
+function providerMapping(value: string): ProviderMapping | undefined {
+  const provider = value.toLowerCase()
+  if (!/^[a-z][a-z0-9_-]*$/.test(provider)) return undefined
+  return (
+    PROVIDER_FLAGS[provider] ?? {
+      provider,
+      harnessType: 'codex',
+      model: customProviderDefaultModel(provider)
+    }
+  )
+}
+
+function customProviderDefaultModel(provider: string): string | undefined {
+  const raw = process.env.CODEX_CUSTOM_PROVIDERS
+  if (!raw) return undefined
+  try {
+    const config = JSON.parse(raw)?.[provider]
+    const model = config?.defaultModel
+    return typeof model === 'string' && model.trim() ? model.trim() : undefined
+  } catch {
+    return undefined
+  }
+}
+
 function flagPattern(flag: string): RegExp {
   return new RegExp(`(?:^|\\s)--${flag.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?=\\s|$)`, 'i')
 }
diff --git a/services/slackbotv2/test/overrides.test.ts b/services/slackbotv2/test/overrides.test.ts
index e7977a3b6..17c9f4686 100644
--- a/services/slackbotv2/test/overrides.test.ts
+++ b/services/slackbotv2/test/overrides.test.ts
@@ -84,6 +84,35 @@ describe('extractMessageOverrides', () => {
     })
   })
 
+  test('--provider selects an arbitrary codex provider', () => {
+    expect(extractMessageOverrides('--provider private_responses --model example-model audit this')).toEqual({
+      cleanedText: 'audit this',
+      harnessType: 'codex',
+      model: 'example-model',
+      provider: 'private_responses',
+      reasoning: undefined
+    })
+  })
+
+  test('--provider uses the configured provider default model', () => {
+    const previous = process.env.CODEX_CUSTOM_PROVIDERS
+    process.env.CODEX_CUSTOM_PROVIDERS = JSON.stringify({
+      private_responses: { defaultModel: 'configured-model' }
+    })
+    try {
+      expect(extractMessageOverrides('--provider=private_responses audit this')).toEqual({
+        cleanedText: 'audit this',
+        harnessType: 'codex',
+        model: 'configured-model',
+        provider: 'private_responses',
+        reasoning: undefined
+      })
+    } finally {
+      if (previous === undefined) delete process.env.CODEX_CUSTOM_PROVIDERS
+      else process.env.CODEX_CUSTOM_PROVIDERS = previous
+    }
+  })
+
   test('--model expands claude aliases to full model ids', () => {
     expect(extractMessageOverrides('--claude --model opus go')).toEqual({
       cleanedText: 'go',
@@ -283,6 +312,15 @@ describe('normalizeHarnessOverrides', () => {
     })
   })
 
+  test('a custom provider is accepted by channel defaults', () => {
+    expect(normalizeHarnessOverrides({ provider: 'private_responses', model: 'example-model' })).toEqual({
+      harnessType: 'codex',
+      model: 'example-model',
+      provider: 'private_responses',
+      reasoning: undefined
+    })
+  })
+
   test('expands a model alias but does not imply a harness (fields are independent)', () => {
     // Like `--model opus` (not `--opus`): the alias expands, harness is left to
     // the explicit `harness` field / thread / deployment default.
@@ -297,7 +335,7 @@ describe('normalizeHarnessOverrides', () => {
   test('reports and drops unrecognized enum-like values', () => {
     const errors: string[] = []
     const result = normalizeHarnessOverrides(
-      { harness: 'gpt', provider: 'openai', reasoning: 'turbo' },
+      { harness: 'gpt', provider: 'not valid', reasoning: 'turbo' },
       message => errors.push(message)
     )
     expect(result).toEqual({
@@ -307,7 +345,7 @@ describe('normalizeHarnessOverrides', () => {
       reasoning: undefined
     })
     expect(errors.some(e => e.includes('unknown harness'))).toBe(true)
-    expect(errors.some(e => e.includes('unknown provider'))).toBe(true)
+    expect(errors.some(e => e.includes('invalid provider id'))).toBe(true)
     expect(errors.some(e => e.includes('unknown reasoning effort'))).toBe(true)
   })
 })

From cafc4e4d6dec25771e3776e494e5f16679a7ef3b Mon Sep 17 00:00:00 2001
From: Oliver Ponder <oliver.ponder@gmail.com>
Date: Wed, 19 Aug 2026 21:46:14 +0000
Subject: [PATCH 31/36] fix(api-rs): authorize githubbot for all its session
 key families (#1435)

The platform scoping added in #1374 pins each ingress key to a single
thread-key prefix, but githubbot mints four: github: (chat),
github-issue: (issue work), github-manage: (owned-PR management) and
github-review: (review runs). Only the first matched, so api-rs 403'd
the bot out of its own issue-work, management and review sessions
("ingress caller denied for another platform's session").

Callers now carry the full list of prefixes their ingress mints, and the
session guard accepts any of them. The other ingresses each mint a
single family and keep their single prefix; unlisted github-* strings
stay denied.

Both ends of the contract are pinned so they cannot drift apart
silently: the api-rs test asserts the shipped ingress spec rather than a
hand-written list, and githubbot pins the prefix each of its thread-key
helpers produces.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
---
 .../crates/centaur-api-server/src/auth.rs     | 136 ++++++++++++------
 .../crates/centaur-api-server/src/routes.rs   |  44 +++++-
 services/githubbot/src/review.ts              |  24 +++-
 services/githubbot/test/thread-keys.test.ts   |  23 +++
 4 files changed, 172 insertions(+), 55 deletions(-)
 create mode 100644 services/githubbot/test/thread-keys.test.ts

diff --git a/services/api-rs/crates/centaur-api-server/src/auth.rs b/services/api-rs/crates/centaur-api-server/src/auth.rs
index f1fb4b899..ab3b09a8e 100644
--- a/services/api-rs/crates/centaur-api-server/src/auth.rs
+++ b/services/api-rs/crates/centaur-api-server/src/auth.rs
@@ -65,7 +65,7 @@ pub(crate) struct AuthenticatedCaller {
     class: CallerClass,
     identity: String,
     capabilities: BTreeSet<Capability>,
-    platform_prefix: Option<&'static str>,
+    platform_prefixes: Option<&'static [&'static str]>,
     principal_subject: Option<String>,
 }
 
@@ -82,8 +82,8 @@ impl AuthenticatedCaller {
         &self.identity
     }
 
-    pub(crate) const fn platform_prefix(&self) -> Option<&'static str> {
-        self.platform_prefix
+    pub(crate) const fn platform_prefixes(&self) -> Option<&'static [&'static str]> {
+        self.platform_prefixes
     }
 
     pub(crate) fn principal_subject(&self) -> Option<&str> {
@@ -123,38 +123,7 @@ impl ApiAuthConfig {
                 None,
             ));
         }
-        for spec in [
-            IngressSpec {
-                env_var: "SLACKBOT_API_KEY",
-                identity: "slackbot",
-                platform_prefix: "slack:",
-                workflow_events: true,
-            },
-            IngressSpec {
-                env_var: "DISCORDBOT_API_KEY",
-                identity: "discordbot",
-                platform_prefix: "discord:",
-                workflow_events: false,
-            },
-            IngressSpec {
-                env_var: "GITHUBBOT_API_KEY",
-                identity: "githubbot",
-                platform_prefix: "github:",
-                workflow_events: true,
-            },
-            IngressSpec {
-                env_var: "LINEARBOT_API_KEY",
-                identity: "linearbot",
-                platform_prefix: "linear:",
-                workflow_events: false,
-            },
-            IngressSpec {
-                env_var: "TEAMSBOT_API_KEY",
-                identity: "teamsbot",
-                platform_prefix: "teams:",
-                workflow_events: false,
-            },
-        ] {
+        for spec in INGRESS_SPECS {
             let Some(token) = optional_env(spec.env_var) else {
                 continue;
             };
@@ -167,7 +136,7 @@ impl ApiAuthConfig {
                 CallerClass::Ingress,
                 token,
                 capabilities,
-                Some(spec.platform_prefix),
+                Some(spec.platform_prefixes),
             ));
         }
 
@@ -203,7 +172,7 @@ impl ApiAuthConfig {
                 Capability::SessionsWrite,
                 Capability::WorkflowsEvents,
             ],
-            Some("slack:"),
+            Some(&["slack:"]),
         )];
         Self {
             static_callers: Arc::new(callers),
@@ -246,7 +215,7 @@ impl ApiAuthConfig {
                     class: CallerClass::Console,
                     identity: subject,
                     capabilities: Capability::ALL.into_iter().collect(),
-                    platform_prefix: None,
+                    platform_prefixes: None,
                     principal_subject: None,
                 })
             }
@@ -278,7 +247,7 @@ impl ApiAuthConfig {
                     class: CallerClass::Principal,
                     identity: subject.clone(),
                     capabilities,
-                    platform_prefix: None,
+                    platform_prefixes: None,
                     principal_subject: Some(subject),
                 })
             }
@@ -317,10 +286,53 @@ enum ApiJwtTokenUse {
     ConsoleService,
 }
 
+/// Every ingress key and the session thread-key families it is allowed to
+/// touch. The platform scoping in `authorize_api_request` denies any
+/// `/api/session/*` call outside them, so a family missing here locks a bot
+/// out of its own sessions.
+const INGRESS_SPECS: &[IngressSpec] = &[
+    IngressSpec {
+        env_var: "SLACKBOT_API_KEY",
+        identity: "slackbot",
+        platform_prefixes: &["slack:"],
+        workflow_events: true,
+    },
+    IngressSpec {
+        env_var: "DISCORDBOT_API_KEY",
+        identity: "discordbot",
+        platform_prefixes: &["discord:"],
+        workflow_events: false,
+    },
+    IngressSpec {
+        env_var: "GITHUBBOT_API_KEY",
+        identity: "githubbot",
+        platform_prefixes: &[
+            "github:",
+            "github-issue:",
+            "github-manage:",
+            "github-review:",
+        ],
+        workflow_events: true,
+    },
+    IngressSpec {
+        env_var: "LINEARBOT_API_KEY",
+        identity: "linearbot",
+        platform_prefixes: &["linear:"],
+        workflow_events: false,
+    },
+    IngressSpec {
+        env_var: "TEAMSBOT_API_KEY",
+        identity: "teamsbot",
+        platform_prefixes: &["teams:"],
+        workflow_events: false,
+    },
+];
+
 struct IngressSpec {
     env_var: &'static str,
     identity: &'static str,
-    platform_prefix: &'static str,
+    /// Every session thread-key prefix this ingress mints.
+    platform_prefixes: &'static [&'static str],
     workflow_events: bool,
 }
 
@@ -329,7 +341,7 @@ fn static_caller(
     class: CallerClass,
     token: String,
     capabilities: impl IntoIterator<Item = Capability>,
-    platform_prefix: Option<&'static str>,
+    platform_prefixes: Option<&'static [&'static str]>,
 ) -> StaticCaller {
     StaticCaller {
         token_digest: Sha256::digest(token.as_bytes()).into(),
@@ -337,7 +349,7 @@ fn static_caller(
             class,
             identity: identity.to_owned(),
             capabilities: capabilities.into_iter().collect(),
-            platform_prefix,
+            platform_prefixes,
             principal_subject: None,
         },
     }
@@ -428,7 +440,7 @@ mod tests {
                 .into_iter()
                 .all(|capability| caller.has_capability(capability))
         );
-        assert_eq!(caller.platform_prefix(), None);
+        assert_eq!(caller.platform_prefixes(), None);
         assert_eq!(caller.principal_subject(), None);
     }
 
@@ -519,6 +531,40 @@ mod tests {
         assert!(caller.has_capability(Capability::WorkflowsWrite));
     }
 
+    #[test]
+    fn githubbot_ingress_covers_every_thread_key_family_it_mints() {
+        // Mirrors services/githubbot/src: chat threads (body-mention.ts), issue
+        // work (issue-manager.ts), owned-PR management (pr-manager.ts) and review
+        // runs (review.ts). githubbot/test/thread-keys.test.ts pins the producer
+        // side; dropping a family here 403s the bot out of its own sessions.
+        let githubbot = INGRESS_SPECS
+            .iter()
+            .find(|spec| spec.identity == "githubbot")
+            .expect("githubbot ingress spec");
+
+        assert_eq!(
+            githubbot.platform_prefixes,
+            [
+                "github:",
+                "github-issue:",
+                "github-manage:",
+                "github-review:"
+            ]
+            .as_slice()
+        );
+    }
+
+    #[test]
+    fn every_ingress_scopes_itself_to_at_least_one_prefix() {
+        for spec in INGRESS_SPECS {
+            assert!(
+                !spec.platform_prefixes.is_empty(),
+                "{} would be scoped to no session at all",
+                spec.identity
+            );
+        }
+    }
+
     #[test]
     fn duplicate_tokens_are_rejected() {
         let callers = vec![
@@ -527,14 +573,14 @@ mod tests {
                 CallerClass::Ingress,
                 "same".to_owned(),
                 [Capability::SessionsWrite],
-                Some("slack:"),
+                Some(&["slack:"]),
             ),
             static_caller(
                 "githubbot",
                 CallerClass::Ingress,
                 "same".to_owned(),
                 [Capability::SessionsWrite],
-                Some("github:"),
+                Some(&["github:"]),
             ),
         ];
 
diff --git a/services/api-rs/crates/centaur-api-server/src/routes.rs b/services/api-rs/crates/centaur-api-server/src/routes.rs
index 3816f1f8e..27555bcf3 100644
--- a/services/api-rs/crates/centaur-api-server/src/routes.rs
+++ b/services/api-rs/crates/centaur-api-server/src/routes.rs
@@ -506,10 +506,10 @@ async fn authorize_api_request(
             .into_response();
     }
 
-    if let Some(prefix) = caller.platform_prefix()
+    if let Some(prefixes) = caller.platform_prefixes()
         && route.starts_with("/api/session/")
         && let Some(thread_key) = session_thread_key_from_request(&request)
-        && !thread_key.as_str().starts_with(prefix)
+        && !thread_key_matches_platform(prefixes, thread_key.as_str())
     {
         record_api_authentication(caller.class().as_str(), "forbidden");
         tracing::warn!(
@@ -519,7 +519,7 @@ async fn authorize_api_request(
             } else {
                 caller.identity()
             },
-            expected_thread_prefix = prefix,
+            expected_thread_prefixes = ?prefixes,
             "ingress caller denied for another platform's session"
         );
         return ApiError::Forbidden("caller is not authorized for this session".to_owned())
@@ -603,6 +603,13 @@ fn session_thread_key_from_request<B>(request: &Request<B>) -> Option<ThreadKey>
     session_thread_key_from_path(request.uri().path())
 }
 
+/// Whether an ingress caller scoped to `prefixes` may touch this session.
+/// A bot can mint several thread-key families (githubbot: `github:`,
+/// `github-manage:`, `github-review:`), so the caller carries them all.
+fn thread_key_matches_platform(prefixes: &[&str], thread_key: &str) -> bool {
+    prefixes.iter().any(|prefix| thread_key.starts_with(prefix))
+}
+
 fn session_thread_key_from_path(path: &str) -> Option<ThreadKey> {
     let rest = path.strip_prefix("/api/session/")?;
     let raw_thread_key = rest.split('/').next()?;
@@ -880,7 +887,36 @@ fn principal_subject_owns_session(subject: Option<&str>, session_principal: Opti
 
 #[cfg(test)]
 mod session_authorization_tests {
-    use super::principal_subject_owns_session;
+    use super::{principal_subject_owns_session, thread_key_matches_platform};
+
+    #[test]
+    fn ingress_scope_covers_every_family_the_bot_mints() {
+        let github = [
+            "github:",
+            "github-issue:",
+            "github-manage:",
+            "github-review:",
+        ];
+        assert!(thread_key_matches_platform(&github, "github:acme/repo:12"));
+        assert!(thread_key_matches_platform(
+            &github,
+            "github-issue:acme/repo:12"
+        ));
+        assert!(thread_key_matches_platform(
+            &github,
+            "github-manage:acme/repo:12"
+        ));
+        assert!(thread_key_matches_platform(
+            &github,
+            "github-review:acme/repo:12"
+        ));
+        assert!(!thread_key_matches_platform(&github, "slack:C123:1.2"));
+        // `github-anything:` outside the listed families stays denied.
+        assert!(!thread_key_matches_platform(
+            &github,
+            "githubx:acme/repo:12"
+        ));
+    }
 
     #[test]
     fn principal_session_reads_require_exact_persisted_owner() {
diff --git a/services/githubbot/src/review.ts b/services/githubbot/src/review.ts
index ffe473f70..1e0d883d0 100644
--- a/services/githubbot/src/review.ts
+++ b/services/githubbot/src/review.ts
@@ -42,6 +42,18 @@ const REVIEW_DEDUP_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 // hit the API for every one.
 const TEAM_MEMBERSHIP_CACHE_TTL_MS = 10 * 60 * 1000;
 
+/**
+ * Session thread key for a PR's review run. api-rs authorizes githubbot per
+ * thread-key prefix, so this family is listed in its ingress spec.
+ */
+export function reviewThreadKey(
+  owner: string,
+  repo: string,
+  number: number,
+): string {
+  return `github-review:${owner}/${repo}:${number}`;
+}
+
 /**
  * Review-on-request trigger. The GitHub chat adapter only surfaces comment
  * threads, so the `pull_request` lifecycle event (action `review_requested`)
@@ -83,7 +95,7 @@ export function handleReviewRequest(
   const teamSlug = stringValue(payload.requested_team?.slug);
   if (!directMatch && !teamSlug) return null;
 
-  const reviewThreadKey = `github-review:${owner}/${repo}:${number}`;
+  const threadKey = reviewThreadKey(owner, repo, number);
   const title = stringValue(payload.pull_request?.title) ?? `#${number}`;
   const url =
     stringValue(payload.pull_request?.html_url) ??
@@ -94,11 +106,11 @@ export function handleReviewRequest(
 
   const trace: GithubbotTrace = {
     includeContext: false,
-    messageId: `review-${reviewThreadKey}-${input.deliveryId}`,
+    messageId: `review-${threadKey}-${input.deliveryId}`,
     mode: "execute",
     openStream: true,
     startedAtMs: nowMs(),
-    threadId: reviewThreadKey,
+    threadId: threadKey,
   };
 
   return (async () => {
@@ -114,7 +126,7 @@ export function handleReviewRequest(
     // Claim the delivery before the background run so a redelivery never
     // double-reviews. State-keyed (not Chat-thread-keyed) because the review
     // thread is synthetic and never touches the adapter.
-    const dedupKey = `${options.stateKeyPrefix ?? "centaur-githubbot"}:review-delivery:${reviewThreadKey}:${input.deliveryId}`;
+    const dedupKey = `${options.stateKeyPrefix ?? "centaur-githubbot"}:review-delivery:${threadKey}:${input.deliveryId}`;
     let claimed = true;
     try {
       claimed = await state.setIfNotExists(dedupKey, "1", REVIEW_DEDUP_TTL_MS);
@@ -151,7 +163,7 @@ export function handleReviewRequest(
         owner,
         repo,
         requester,
-        threadKey: reviewThreadKey,
+        threadKey,
         title,
         url,
       }),
@@ -162,7 +174,7 @@ export function handleReviewRequest(
         forwardInput.afterEventId = lastEventId;
       },
       openStream: false,
-      threadId: reviewThreadKey,
+      threadId: threadKey,
       trace,
     };
 
diff --git a/services/githubbot/test/thread-keys.test.ts b/services/githubbot/test/thread-keys.test.ts
new file mode 100644
index 000000000..92b50ced6
--- /dev/null
+++ b/services/githubbot/test/thread-keys.test.ts
@@ -0,0 +1,23 @@
+import { describe, expect, test } from "bun:test";
+import { issueWorkThreadKey } from "../src/issue-manager";
+import { managementThreadKey } from "../src/pr-manager";
+import { reviewThreadKey } from "../src/review";
+
+// api-rs scopes githubbot's API key to a fixed set of thread-key prefixes, so
+// every family minted here has to stay listed in its ingress spec
+// (services/api-rs/crates/centaur-api-server/src/auth.rs). Renaming one without
+// updating that list 403s the whole flow, and only in background paths where
+// the failure never reaches a human.
+describe("session thread-key families", () => {
+  test("issue-work, management and review keys keep their prefixes", () => {
+    expect(issueWorkThreadKey("acme", "repo", 7)).toBe(
+      "github-issue:acme/repo:7",
+    );
+    expect(managementThreadKey("acme", "repo", 7)).toBe(
+      "github-manage:acme/repo:7",
+    );
+    expect(reviewThreadKey("acme", "repo", 7)).toBe(
+      "github-review:acme/repo:7",
+    );
+  });
+});

From 19606f9ec1486535c75a681f2d7c5ef159d6d237 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Wed, 19 Aug 2026 21:56:22 +0000
Subject: [PATCH 32/36] chore(deps): bump compatible harness-server
 dependencies (#1429)

* chore(deps): bump the harness-server-dependencies group across 1 directory with 3 updates

Bumps the harness-server-dependencies group with 3 updates in the /crates/harness-server directory: [allocative](https://github.com/facebookexperimental/allocative), [thiserror](https://github.com/dtolnay/thiserror) and [uuid](https://github.com/uuid-rs/uuid).


Updates `allocative` from 0.3.4 to 0.3.6
- [Release notes](https://github.com/facebookexperimental/allocative/releases)
- [Commits](https://github.com/facebookexperimental/allocative/commits)

Updates `thiserror` from 2.0.19 to 2.0.20
- [Release notes](https://github.com/dtolnay/thiserror/releases)
- [Commits](https://github.com/dtolnay/thiserror/compare/2.0.19...2.0.20)

Updates `uuid` from 1.24.0 to 1.24.1
- [Release notes](https://github.com/uuid-rs/uuid/releases)
- [Commits](https://github.com/uuid-rs/uuid/compare/v1.24.0...v1.24.1)

---
updated-dependencies:
- dependency-name: allocative
  dependency-version: 0.3.6
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: harness-server-dependencies
- dependency-name: thiserror
  dependency-version: 2.0.20
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: harness-server-dependencies
- dependency-name: uuid
  dependency-version: 1.24.1
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: harness-server-dependencies
...

Signed-off-by: dependabot[bot] <support@github.com>

* fix(deps): retain compatible allocative version

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Matthew Slipper <me@matthewslipper.com>
---
 .github/dependabot.yml           |  5 +++
 crates/harness-server/Cargo.lock | 68 ++++++++++++++++----------------
 crates/harness-server/Cargo.toml |  2 +
 3 files changed, 41 insertions(+), 34 deletions(-)

diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index fe63cd8e5..fcdee485c 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -64,6 +64,11 @@ updates:
       prefix: chore
       include: scope
     open-pull-requests-limit: 5
+    ignore:
+      # Starlark 0.13 uses hashbrown 0.14, which allocative 0.3.6+ no longer supports.
+      - dependency-name: allocative
+        versions:
+          - ">= 0.3.6"
     groups:
       harness-server-dependencies:
         patterns:
diff --git a/crates/harness-server/Cargo.lock b/crates/harness-server/Cargo.lock
index 94cf82acf..4e9483f5e 100644
--- a/crates/harness-server/Cargo.lock
+++ b/crates/harness-server/Cargo.lock
@@ -165,7 +165,7 @@ dependencies = [
  "nom 7.1.3",
  "num-traits",
  "rusticata-macros",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "time",
 ]
 
@@ -404,7 +404,7 @@ dependencies = [
  "cached_proc_macro_types",
  "hashbrown 0.15.5",
  "once_cell",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "web-time",
 ]
 
@@ -574,7 +574,7 @@ dependencies = [
  "serde_json",
  "serde_with",
  "strum_macros",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "tracing",
  "ts-rs",
  "uuid",
@@ -603,7 +603,7 @@ dependencies = [
  "serde_json",
  "shlex 1.3.0",
  "starlark",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
 ]
 
 [[package]]
@@ -639,7 +639,7 @@ dependencies = [
  "rama-unix",
  "serde",
  "serde_json",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "time",
  "tokio",
  "tracing",
@@ -675,7 +675,7 @@ dependencies = [
  "strum",
  "strum_macros",
  "sys-locale",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "tokio",
  "tracing",
  "ts-rs",
@@ -742,7 +742,7 @@ dependencies = [
  "codex-utils-cache",
  "image",
  "mime_guess",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "tokio",
 ]
 
@@ -1732,7 +1732,7 @@ dependencies = [
  "serde",
  "serde_json",
  "sha2 0.11.0",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "tokio",
  "url",
  "uuid",
@@ -1823,7 +1823,7 @@ dependencies = [
  "once_cell",
  "rand 0.9.4",
  "ring",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "tinyvec",
  "tokio",
  "tracing",
@@ -1846,7 +1846,7 @@ dependencies = [
  "rand 0.9.4",
  "resolv-conf",
  "smallvec",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "tokio",
  "tracing",
 ]
@@ -2359,7 +2359,7 @@ dependencies = [
  "jni-sys",
  "log",
  "simd_cesu8",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "walkdir",
  "windows-link",
 ]
@@ -2472,7 +2472,7 @@ checksum = "635839550ae8b90d9fd2571460a6645dc0aec070225956ca7a2831ed31d2795d"
 dependencies = [
  "enumflags2",
  "libc",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
 ]
 
 [[package]]
@@ -2746,7 +2746,7 @@ dependencies = [
  "serde_json",
  "sha1 0.11.0",
  "sha2 0.10.9",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "tokio",
  "tower",
  "tracing",
@@ -2765,7 +2765,7 @@ dependencies = [
  "serde",
  "serde_json",
  "smallvec",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "tokio",
  "web-time",
 ]
@@ -2796,7 +2796,7 @@ dependencies = [
  "rustls",
  "serde",
  "serde_json",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "tokio",
  "tracing",
 ]
@@ -2816,7 +2816,7 @@ dependencies = [
  "serde",
  "serde_json",
  "smallvec",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "tokio",
  "tokio-tungstenite",
  "tower",
@@ -2846,7 +2846,7 @@ dependencies = [
  "serde",
  "serde_json",
  "sha1 0.11.0",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "tokio",
  "tracing",
  "wasm-bindgen",
@@ -3061,7 +3061,7 @@ dependencies = [
  "futures-sink",
  "js-sys",
  "pin-project-lite",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
 ]
 
 [[package]]
@@ -3088,7 +3088,7 @@ dependencies = [
  "percent-encoding",
  "portable-atomic",
  "rand 0.9.4",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
 ]
 
 [[package]]
@@ -3383,7 +3383,7 @@ dependencies = [
  "rustc-hash",
  "rustls",
  "socket2",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "tokio",
  "tracing",
  "web-time",
@@ -3406,7 +3406,7 @@ dependencies = [
  "rustls",
  "rustls-pki-types",
  "slab",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "tinyvec",
  "tracing",
  "web-time",
@@ -3874,7 +3874,7 @@ checksum = "a4e608c6638b9c18977b00b475ac1f28d14e84b27d8d42f70e0bf1e3dec127ac"
 dependencies = [
  "getrandom 0.2.17",
  "libredox",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
 ]
 
 [[package]]
@@ -4070,7 +4070,7 @@ dependencies = [
  "serde",
  "serde_json",
  "sse-stream",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "tokio",
  "tokio-stream",
  "tokio-util",
@@ -5066,11 +5066,11 @@ dependencies = [
 
 [[package]]
 name = "thiserror"
-version = "2.0.19"
+version = "2.0.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "09a43598840e33d5b0331f38c5e30d13bb11c11210a4b58f0d9b18a5a5eefcd9"
+checksum = "ec86235f5fcc2a73650310756d2ac5b138a5780bbbdfae3eeccec992c435ba4f"
 dependencies = [
- "thiserror-impl 2.0.19",
+ "thiserror-impl 2.0.20",
 ]
 
 [[package]]
@@ -5086,9 +5086,9 @@ dependencies = [
 
 [[package]]
 name = "thiserror-impl"
-version = "2.0.19"
+version = "2.0.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "43cbfe0cf76104d42a574802844187e84a305e531ed54455f11fbde0f10541cd"
+checksum = "bc04cd3e1236dd4a98afca4569f2deb3f120e5422a4023be2cb683f8486292af"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -5463,7 +5463,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4994acea2522cd2b3b85c1d9529a55991e3ad5e25cdcd3de9d505972c4379424"
 dependencies = [
  "serde_json",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "ts-rs-macros",
  "uuid",
 ]
@@ -5495,7 +5495,7 @@ dependencies = [
  "rustls",
  "rustls-pki-types",
  "sha1 0.11.0",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
 ]
 
 [[package]]
@@ -5573,9 +5573,9 @@ checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
 
 [[package]]
 name = "uuid"
-version = "1.24.0"
+version = "1.24.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bf3923a6f5c4c6382e0b653c4117f48d631ea17f38ed86e2a828e6f7412f5239"
+checksum = "2cefc03fd367c0c6d4305de1b312cf00248c4114f4a0418ce6a6af769e3b0bd9"
 dependencies = [
  "getrandom 0.4.2",
  "js-sys",
@@ -5811,7 +5811,7 @@ version = "0.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f9b0540e91e49de3817c314da0dd3bc518093ceacc6ea5327cb0e1eb073e5189"
 dependencies = [
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
 ]
 
 [[package]]
@@ -6196,7 +6196,7 @@ dependencies = [
  "oid-registry",
  "ring",
  "rusticata-macros",
- "thiserror 2.0.19",
+ "thiserror 2.0.20",
  "time",
 ]
 
diff --git a/crates/harness-server/Cargo.toml b/crates/harness-server/Cargo.toml
index 22c6abda9..c9af0f362 100644
--- a/crates/harness-server/Cargo.toml
+++ b/crates/harness-server/Cargo.toml
@@ -9,6 +9,8 @@ name = "harness-server"
 path = "src/main.rs"
 
 [dependencies]
+# Starlark 0.13 uses hashbrown 0.14, which is no longer supported by
+# allocative 0.3.6's hashbrown integration.
 allocative = "=0.3.4"
 base64 = "0.23"
 clap = { version = "4.5", features = ["derive"] }

From cb541d4e774b7774a0692233134c2daccfcefee5 Mon Sep 17 00:00:00 2001
From: Derek Cofausper <256792747+decofe@users.noreply.github.com>
Date: Thu, 20 Aug 2026 00:00:56 +0000
Subject: [PATCH 33/36] fix(granola): resolve shared meeting links (#1434)

Co-authored-by: Liam Horne <1933029+snario@users.noreply.github.com>
---
 services/sandbox/SYSTEM_PROMPT.md         |  4 ++
 services/sandbox/test_system_prompt.py    |  8 ++++
 tools/productivity/granola/cli.py         |  4 +-
 tools/productivity/granola/client.py      | 40 ++++++++++++++++++
 tools/productivity/granola/test_client.py | 51 ++++++++++++++++++++++-
 5 files changed, 104 insertions(+), 3 deletions(-)

diff --git a/services/sandbox/SYSTEM_PROMPT.md b/services/sandbox/SYSTEM_PROMPT.md
index 0783f030d..cf64555c9 100644
--- a/services/sandbox/SYSTEM_PROMPT.md
+++ b/services/sandbox/SYSTEM_PROMPT.md
@@ -49,6 +49,10 @@
 |When a user asks for the transcript, exact quote or verbatim lines, recap, or summary of a specific audio/video source — such as a podcast, episode, video, interview, webinar, livestream, talk, or recording — first confirm that you can access that exact original source or its official transcript. If the exact source is unavailable, say so plainly and ask before using show notes, clips, related coverage, adjacent interviews, or other substitute materials.
 |Exception: if the user explicitly asks for off-the-cuff brainstorming or quick speculation, you may stay in brainstorming mode and say that you are not grounding it first.
 
+[Granola share links]
+|When a user provides a `notes.granola.ai` link, pass that exact link to `granola get` before using semantic search or related meeting results. The tool resolves both `/d/<meeting-uuid>` and `/t/<meeting-uuid>-<share-suffix>` links to the same meeting.
+|If direct retrieval fails, report that the linked meeting could not be accessed. Do not substitute a similarly titled meeting or infer the linked meeting's contents from search results.
+
 [Company-context retrieval]
 |For questions about internal history, discussions, decisions, themes, or prior work, use `company_context search` before source-specific tools.
 |Use hybrid search by default for conceptual, thematic, or natural-language queries. Preserve the user's wording for the first query and add no more than one or two focused semantic variants when needed.
diff --git a/services/sandbox/test_system_prompt.py b/services/sandbox/test_system_prompt.py
index edccd2ba2..3850ba4de 100644
--- a/services/sandbox/test_system_prompt.py
+++ b/services/sandbox/test_system_prompt.py
@@ -20,6 +20,14 @@ def test_company_context_retrieval_guidance_is_present(self) -> None:
         self.assertIn("Distinguish direct internal views from AI-generated research", prompt)
         self.assertIn("If retrieval remains weak", prompt)
 
+    def test_granola_share_links_require_direct_retrieval(self) -> None:
+        prompt = SYSTEM_PROMPT.read_text()
+
+        self.assertIn("[Granola share links]", prompt)
+        self.assertIn("pass that exact link to `granola get`", prompt)
+        self.assertIn("both `/d/<meeting-uuid>` and `/t/<meeting-uuid>-<share-suffix>`", prompt)
+        self.assertIn("Do not substitute a similarly titled meeting", prompt)
+
     def test_mpp_fallback_discovery_guidance_is_present(self) -> None:
         prompt = SYSTEM_PROMPT.read_text()
 
diff --git a/tools/productivity/granola/cli.py b/tools/productivity/granola/cli.py
index 8e455bd4f..1c9aae3a6 100644
--- a/tools/productivity/granola/cli.py
+++ b/tools/productivity/granola/cli.py
@@ -87,7 +87,7 @@ def list_notes(
 
 @app.command("get")
 def get_note(
-    note_id: str = typer.Argument(..., help="Note ID (e.g. not_xxxxxxxxxxxxx)"),
+    note_id: str = typer.Argument(..., help="Note ID, meeting UUID, or Granola share link"),
     raw: bool = typer.Option(False, "--raw", "-r", help="Output raw markdown"),
     transcript: bool = typer.Option(False, "--transcript", "-t", help="Include transcript"),
 ):
@@ -131,7 +131,7 @@ def get_note(
 
 @app.command("transcript")
 def get_transcript(
-    note_id: str = typer.Argument(..., help="Note ID"),
+    note_id: str = typer.Argument(..., help="Note ID, meeting UUID, or Granola share link"),
 ):
     """Get the transcript for a meeting note."""
     from .client import _client
diff --git a/tools/productivity/granola/client.py b/tools/productivity/granola/client.py
index 0ef6d3510..5440a9799 100644
--- a/tools/productivity/granola/client.py
+++ b/tools/productivity/granola/client.py
@@ -19,10 +19,27 @@
 from xml.etree import ElementTree
 
 import httpx
+
 from centaur_sdk import secret
 
 API_BASE = "https://public-api.granola.ai"
 MCP_URL = "https://mcp.granola.ai/mcp"
+_NOTE_ID_RE = re.compile(r"^not_[a-zA-Z0-9]{14}$")
+_SHARE_ID_RE = re.compile(
+    r"(?<![0-9a-f])([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})(?![0-9a-f])",
+    re.IGNORECASE,
+)
+
+
+def _normalize_note_ref(note_ref: str) -> str:
+    """Return a Granola API note ID or meeting UUID from an ID/share link."""
+    value = note_ref.strip().removeprefix("<").split("|", 1)[0].removesuffix(">")
+    if _NOTE_ID_RE.fullmatch(value):
+        return value
+    match = _SHARE_ID_RE.search(value)
+    if match:
+        return match.group(1).lower()
+    raise ValueError("expected a Granola not_* ID, meeting UUID, or notes.granola.ai share link")
 
 
 class GranolaClient:
@@ -77,12 +94,33 @@ def list_notes(
             params["updated_after"] = updated_after
         return self._get("/v1/notes", params=params)
 
+    def _resolve_note_id(self, note_ref: str) -> str:
+        normalized = _normalize_note_ref(note_ref)
+        if _NOTE_ID_RE.fullmatch(normalized):
+            return normalized
+
+        cursor: str | None = None
+        while True:
+            page = self.list_notes(page_size=30, cursor=cursor)
+            for note in page.get("notes", []):
+                try:
+                    web_id = _normalize_note_ref(note.get("web_url") or "")
+                except ValueError:
+                    continue
+                if web_id == normalized:
+                    return note["id"]
+            cursor = page.get("cursor")
+            if not page.get("hasMore") or not cursor:
+                break
+        raise RuntimeError(f"meeting {normalized} not found in accessible Granola notes")
+
     def get_note(self, note_id: str, include_transcript: bool = False) -> dict[str, Any]:
         """Fetch a single note by ID (not_* format, e.g. not_1d3tmYTlCICgjy).
 
         Returns full note with title, owner, attendees, summary_markdown,
         calendar_event, folder_membership, and optionally transcript.
         """
+        note_id = self._resolve_note_id(note_id)
         params: dict[str, Any] = {}
         if include_transcript:
             params["include"] = "transcript"
@@ -294,6 +332,7 @@ def list_all_notes(
     def get_note(self, note_id: str, include_transcript: bool = False) -> dict[str, Any]:
         """Fetch a single meeting by UUID, REST-shaped (title, owner, attendees,
         summary_markdown, optionally transcript)."""
+        note_id = _normalize_note_ref(note_id)
         text = self._call_tool("get_meetings", {"meeting_ids": [note_id]})
         notes = _parse_meetings(text)
         if not notes:
@@ -306,6 +345,7 @@ def get_note(self, note_id: str, include_transcript: bool = False) -> dict[str,
     def get_transcript(self, note_id: str) -> list[dict[str, Any]]:
         """Fetch the transcript for a meeting. Returns a list of utterances
         (single block if the MCP text is not line-structured)."""
+        note_id = _normalize_note_ref(note_id)
         text = self._call_tool("get_meeting_transcript", {"meeting_id": note_id})
         if not text.strip():
             return []
diff --git a/tools/productivity/granola/test_client.py b/tools/productivity/granola/test_client.py
index 947c82462..65bea7618 100644
--- a/tools/productivity/granola/test_client.py
+++ b/tools/productivity/granola/test_client.py
@@ -1,4 +1,53 @@
-from client import _parse_meeting_date, _parse_meetings, _parse_participants
+from client import (
+    GranolaClient,
+    _normalize_note_ref,
+    _parse_meeting_date,
+    _parse_meetings,
+    _parse_participants,
+)
+
+
+def test_normalize_note_ref_accepts_both_granola_share_link_forms():
+    meeting_id = "57db2e7a-2aee-40b4-9db2-a20ec81c41c5"
+
+    assert _normalize_note_ref(f"https://notes.granola.ai/d/{meeting_id}") == meeting_id
+    assert (
+        _normalize_note_ref(f"<https://notes.granola.ai/t/{meeting_id}-008umkv4|notes.granola.ai>")
+        == meeting_id
+    )
+
+
+def test_rest_client_resolves_share_link_before_getting_note():
+    meeting_id = "57db2e7a-2aee-40b4-9db2-a20ec81c41c5"
+    client = GranolaClient(api_key="test")
+    calls = []
+
+    def fake_get(path, params=None):
+        calls.append((path, params))
+        if path == "/v1/notes":
+            return {
+                "notes": [
+                    {
+                        "id": "not_1234567890abcd",
+                        "web_url": f"https://notes.granola.ai/d/{meeting_id}",
+                    }
+                ],
+                "hasMore": False,
+                "cursor": None,
+            }
+        return {"id": "not_1234567890abcd", "title": "Stripe risk"}
+
+    client._get = fake_get
+    try:
+        note = client.get_note(f"https://notes.granola.ai/t/{meeting_id}-008umkv4")
+    finally:
+        client.close()
+
+    assert note["title"] == "Stripe risk"
+    assert calls == [
+        ("/v1/notes", {"page_size": 30}),
+        ("/v1/notes/not_1234567890abcd", {}),
+    ]
 
 
 def test_parse_meetings_accepts_extra_attributes_and_decodes_entities():

From bdc84ad29e7a99cc3e207f7fd2a6f491a3db5165 Mon Sep 17 00:00:00 2001
From: Matthew Slipper <me@matthewslipper.com>
Date: Thu, 20 Aug 2026 03:04:25 +0000
Subject: [PATCH 34/36] feat(workflows): resolve principals by OID (#1439)

---
 docs/pages/extend/workflows-v2.mdx            | 11 ++++---
 docs/pages/extend/workflows.mdx               | 10 +++---
 docs/pages/secrets/advanced-permissioning.mdx | 10 +++---
 .../crates/centaur-workflows/src/lib.rs       | 33 +++++++++++++++----
 .../tests/test_workflow_host.py               |  5 ++-
 services/workflow-python/workflow_host.py     |  4 +--
 6 files changed, 48 insertions(+), 25 deletions(-)

diff --git a/docs/pages/extend/workflows-v2.mdx b/docs/pages/extend/workflows-v2.mdx
index 3ae98983b..cb7349c7c 100644
--- a/docs/pages/extend/workflows-v2.mdx
+++ b/docs/pages/extend/workflows-v2.mdx
@@ -180,16 +180,17 @@ cargo run -p centaur-perms -- \
   --tool slack
 ```
 
-To use an existing principal instead, declare its foreign ID:
+To use an existing principal instead, declare its foreign ID or `prn_`-prefixed
+OID:
 
 ```python
 WORKFLOW_PRINCIPAL = "finance-automation"
 ```
 
-The string form resolves the existing principal and fails startup when it does
-not exist. It does not create or update the principal. The `True` form remains
-`workflow-` plus the slugged `WORKFLOW_NAME`. Any `WORKFLOW_PRINCIPAL` value
-requires `apiRs.workflowHostSandbox=true`, which
+The string form resolves the existing principal by foreign ID or OID and fails
+startup when it does not exist. It does not create or update the principal. The
+`True` form remains `workflow-` plus the slugged `WORKFLOW_NAME`. Any
+`WORKFLOW_PRINCIPAL` value requires `apiRs.workflowHostSandbox=true`, which
 renders `WORKFLOW_HOST_SANDBOX=true`; startup fails if a workflow declares a
 principal while workflow-host sandboxing is disabled.
 
diff --git a/docs/pages/extend/workflows.mdx b/docs/pages/extend/workflows.mdx
index f9919fc39..397e6e5b0 100644
--- a/docs/pages/extend/workflows.mdx
+++ b/docs/pages/extend/workflows.mdx
@@ -68,11 +68,11 @@ async def handler(inp: Input, ctx: WorkflowContext) -> dict[str, Any]:
 directly with `ctx.call_tool(...)` and should have its own credential boundary.
 Set it to `True` to have the API derive and register the
 `workflow-nightly-report` principal from `WORKFLOW_NAME`. Set it to an existing
-principal foreign ID, such as `WORKFLOW_PRINCIPAL = "finance-automation"`, to
-run the workflow-host sandbox under that principal instead. An unknown foreign
-ID fails startup. Grant the required tool roles or secrets to the selected
-principal. Any `WORKFLOW_PRINCIPAL` value requires
-`apiRs.workflowHostSandbox=true`, which renders
+principal foreign ID, such as `WORKFLOW_PRINCIPAL = "finance-automation"`, or
+to a `prn_`-prefixed OID to run the workflow-host sandbox under that principal
+instead. An unknown principal reference fails startup. Grant the required tool
+roles or secrets to the selected principal. Any `WORKFLOW_PRINCIPAL` value
+requires `apiRs.workflowHostSandbox=true`, which renders
 `WORKFLOW_HOST_SANDBOX=true`; startup fails if workflow-host sandboxing is
 disabled.
 
diff --git a/docs/pages/secrets/advanced-permissioning.mdx b/docs/pages/secrets/advanced-permissioning.mdx
index 83064acf2..ea42405e6 100644
--- a/docs/pages/secrets/advanced-permissioning.mdx
+++ b/docs/pages/secrets/advanced-permissioning.mdx
@@ -63,7 +63,7 @@ The stable principal ids follow these rules:
 | Teams personal chat | `teams-user-<user-id>` | That Teams user |
 | Teams channel or group conversation | `teams-conversation-<conversation-id>` | Everyone using Centaur in that conversation |
 | Workflow with `WORKFLOW_PRINCIPAL = True` | `workflow-<workflow-name>` | Runs of that workflow |
-| Workflow with `WORKFLOW_PRINCIPAL = "<foreign-id>"` | The selected existing principal | Runs of that workflow |
+| Workflow with `WORKFLOW_PRINCIPAL = "<foreign-id-or-oid>"` | The selected existing principal | Runs of that workflow |
 | Other session key | `thread-<session-key>` | That session key |
 
 Values are lowercased and converted to URL-safe slugs. The team scope is
@@ -408,10 +408,10 @@ consent.
 
 Workflows opt into isolated permissions with `WORKFLOW_PRINCIPAL = True`, which
 derives `workflow-<workflow-name>`. They can instead set `WORKFLOW_PRINCIPAL` to
-an existing principal foreign ID. Agent turns can select an existing principal
-with `ctx.agent_turn(..., principal="<foreign-id>")`. Unknown foreign IDs fail
-instead of falling back to a broader identity. Grant workflows and agent turns
-only the roles or secrets they need. See
+an existing principal foreign ID or `prn_`-prefixed OID. Agent turns can select
+an existing principal with `ctx.agent_turn(..., principal="<foreign-id>")`.
+Unknown foreign IDs fail instead of falling back to a broader identity. Grant
+workflows and agent turns only the roles or secrets they need. See
 [Creating Workflows](/extend/workflows#define-a-workflow).
 
 ## Operational Checklist
diff --git a/services/api-rs/crates/centaur-workflows/src/lib.rs b/services/api-rs/crates/centaur-workflows/src/lib.rs
index c00b6de15..96c55a88a 100644
--- a/services/api-rs/crates/centaur-workflows/src/lib.rs
+++ b/services/api-rs/crates/centaur-workflows/src/lib.rs
@@ -324,8 +324,8 @@ impl WorkflowPrincipalRegistrar {
                         })
                         .await?
                 }
-                WorkflowPrincipalDeclaration::Existing(foreign_id) => {
-                    self.client.get_principal(foreign_id).await?
+                WorkflowPrincipalDeclaration::Existing(reference) => {
+                    self.client.get_principal(reference).await?
                 }
             };
             registered.insert(workflow_name.clone(), record.id);
@@ -1681,7 +1681,7 @@ struct PythonWorkflowDiscovery {
 #[serde(untagged)]
 enum PythonWorkflowPrincipal {
     Enabled(bool),
-    ForeignId(String),
+    Reference(String),
 }
 
 #[derive(Debug, Deserialize)]
@@ -1724,12 +1724,10 @@ fn metadata_from_discovery_payload(
                     WorkflowPrincipalDeclaration::Managed,
                 );
             }
-            Some(PythonWorkflowPrincipal::ForeignId(foreign_id))
-                if !foreign_id.trim().is_empty() =>
-            {
+            Some(PythonWorkflowPrincipal::Reference(reference)) if !reference.trim().is_empty() => {
                 metadata.principals.insert(
                     workflow.workflow_name,
-                    WorkflowPrincipalDeclaration::Existing(foreign_id.trim().to_owned()),
+                    WorkflowPrincipalDeclaration::Existing(reference.trim().to_owned()),
                 );
             }
             _ => {}
@@ -4977,6 +4975,27 @@ mod tests {
         );
     }
 
+    #[test]
+    fn discovery_metadata_preserves_workflow_principal_oid() {
+        let payload: PythonWorkflowDiscoveryPayload = serde_json::from_value(json!({
+            "workflows": [{
+                "workflow_name": "oid_workflow",
+                "source_path": "workflows/oid_workflow.py",
+                "principal": " prn_01k2m3n4p5 ",
+            }],
+        }))
+        .unwrap();
+
+        let metadata = metadata_from_discovery_payload(payload);
+
+        assert_eq!(
+            metadata.principals.get("oid_workflow"),
+            Some(&WorkflowPrincipalDeclaration::Existing(
+                "prn_01k2m3n4p5".to_owned()
+            ))
+        );
+    }
+
     #[test]
     fn workflow_principal_foreign_id_is_derived_from_workflow_name() {
         assert_eq!(
diff --git a/services/workflow-python/tests/test_workflow_host.py b/services/workflow-python/tests/test_workflow_host.py
index 1c743f1a1..b02d51ce9 100644
--- a/services/workflow-python/tests/test_workflow_host.py
+++ b/services/workflow-python/tests/test_workflow_host.py
@@ -634,7 +634,7 @@ def test_load_workflow_file_reads_workflow_principal(self) -> None:
         assert registered is not None
         self.assertEqual(host.normalize_principal(registered), True)
 
-    def test_load_workflow_file_reads_workflow_principal_foreign_id(self) -> None:
+    def test_load_workflow_file_reads_workflow_principal_reference(self) -> None:
         host = load_workflow_host()
         with tempfile.TemporaryDirectory() as tmp:
             path = Path(tmp) / "principal_workflow.py"
@@ -649,6 +649,9 @@ def test_load_workflow_file_reads_workflow_principal_foreign_id(self) -> None:
         assert registered is not None
         self.assertEqual(host.normalize_principal(registered), "finance-automation")
 
+        registered.principal = " prn_01k2m3n4p5 "
+        self.assertEqual(host.normalize_principal(registered), "prn_01k2m3n4p5")
+
     def test_workflow_name_from_source_reads_string_constant(self) -> None:
         host = load_workflow_host()
         with tempfile.TemporaryDirectory() as tmp:
diff --git a/services/workflow-python/workflow_host.py b/services/workflow-python/workflow_host.py
index 755e5c5ca..9e270ae07 100644
--- a/services/workflow-python/workflow_host.py
+++ b/services/workflow-python/workflow_host.py
@@ -361,8 +361,8 @@ def normalize_principal(workflow: RegisteredWorkflow) -> bool | str | None:
     if isinstance(raw, bool):
         return raw or None
     if isinstance(raw, str):
-        foreign_id = raw.strip()
-        return foreign_id or None
+        reference = raw.strip()
+        return reference or None
     return None
 
 

From 666e129b8d848dcc3fd8c9163d2dad927a61ebe0 Mon Sep 17 00:00:00 2001
From: Matthew Slipper <me@matthewslipper.com>
Date: Thu, 20 Aug 2026 04:25:03 +0000
Subject: [PATCH 35/36] fix: retain stale Slack channel catalog (#1441)

---
 .../console/app/services/slack_channel_catalog_provider.rb   | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/services/console/app/services/slack_channel_catalog_provider.rb b/services/console/app/services/slack_channel_catalog_provider.rb
index 3c2bed9aa..bcca2240c 100644
--- a/services/console/app/services/slack_channel_catalog_provider.rb
+++ b/services/console/app/services/slack_channel_catalog_provider.rb
@@ -1,8 +1,7 @@
 require "digest"
 
 class SlackChannelCatalogProvider
-  FRESH_TTL = 5.minutes
-  STALE_TTL = 24.hours
+  FRESH_TTL = 1.hour
   ERROR_TTL = 30.seconds
   REFRESH_LOCK_TTL = 1.minute
 
@@ -43,7 +42,7 @@ def refresh(cache_key:)
       cached = Rails.cache.read(cache_key)
       result = SlackChannelCatalog.new(**config).fetch
       if result.ok?
-        Rails.cache.write(cache_key, serialize_result(result), expires_in: STALE_TTL)
+        Rails.cache.write(cache_key, serialize_result(result))
       elsif cached.nil?
         Rails.cache.write(cache_key, serialize_result(result), expires_in: ERROR_TTL)
       end

From bc72622b200d0f6e3cc92fa1c56a1daff9c051a9 Mon Sep 17 00:00:00 2001
From: Perry Dime <svc_ai@paradigm.xyz>
Date: Thu, 20 Aug 2026 15:34:43 +0000
Subject: [PATCH 36/36] fix: retry transient Slack sync failures (#1443)

Co-authored-by: Perry Dime <260989497+svc-paradigm@users.noreply.github.com>
---
 .../app/jobs/slack_dm/sync_credential_job.rb  |  8 ++++----
 .../app/services/slack_dm/sync_credential.rb  | 14 ++++++++++---
 .../console/test/jobs/slack_dm/jobs_test.rb   | 20 +++++++++++++++++--
 .../services/slack_dm/sync_credential_test.rb | 19 ++++++++++++++++++
 4 files changed, 52 insertions(+), 9 deletions(-)

diff --git a/services/console/app/jobs/slack_dm/sync_credential_job.rb b/services/console/app/jobs/slack_dm/sync_credential_job.rb
index c23d74397..735f07b3a 100644
--- a/services/console/app/jobs/slack_dm/sync_credential_job.rb
+++ b/services/console/app/jobs/slack_dm/sync_credential_job.rb
@@ -1,6 +1,6 @@
 module SlackDm
   class SyncCredentialJob < ApplicationJob
-    MAX_RATE_LIMIT_EXECUTIONS = 2
+    MAX_RETRYABLE_EXECUTIONS = 2
 
     queue_as :default
 
@@ -15,10 +15,10 @@ def perform(credential_id)
       return unless SlackDm::SyncCredential.required_scopes_granted?(credential.scopes)
 
       SlackDm::SyncCredential.new(credential).call
-    rescue SlackDm::SyncCredential::RateLimitedError => e
-      if executions >= MAX_RATE_LIMIT_EXECUTIONS
+    rescue SlackDm::SyncCredential::RetryableApiError => e
+      if executions >= MAX_RETRYABLE_EXECUTIONS
         Rails.logger.warn do
-          "Slack sync job dropped after repeated rate limits: " \
+          "Slack sync job dropped after repeated retryable API failures: " \
             "credential_id=#{credential_id} executions=#{executions}"
         end
         return
diff --git a/services/console/app/services/slack_dm/sync_credential.rb b/services/console/app/services/slack_dm/sync_credential.rb
index a58cc9de9..94e0c961e 100644
--- a/services/console/app/services/slack_dm/sync_credential.rb
+++ b/services/console/app/services/slack_dm/sync_credential.rb
@@ -13,17 +13,22 @@ class SyncCredential
     CONVERSATIONS_HISTORY_ENDPOINT = "https://slack.com/api/conversations.history"
     CONVERSATIONS_REPLIES_ENDPOINT = "https://slack.com/api/conversations.replies"
     API_READ_TIMEOUT_SECONDS = 120
+    TRANSIENT_API_ERRORS = %w[fatal_error internal_error].freeze
+    TRANSIENT_API_RETRY_AFTER_SECONDS = 30
 
     SlackApiError = Class.new(StandardError)
-    class RateLimitedError < SlackApiError
+    class RetryableApiError < SlackApiError
       attr_reader :retry_after
 
       def initialize(retry_after:)
         @retry_after = retry_after
-        super("Slack API rate limited; retry after #{retry_after} seconds")
+        super("Slack API request is retryable after #{retry_after} seconds")
       end
     end
 
+    class RateLimitedError < RetryableApiError; end
+    class TransientApiError < RetryableApiError; end
+
     class << self
       attr_accessor :slack_api_http
 
@@ -71,7 +76,7 @@ def call
         sync_history(conversation, home_team_id, checkpoints[conversation.fetch("id")], batch)
         batch[:run][:conversations_synced] += 1
       rescue StandardError => e
-        raise if e.is_a?(RateLimitedError)
+        raise if e.is_a?(RetryableApiError)
         raise if Rails.env.test?
 
         batch[:run][:conversations_failed] += 1
@@ -347,6 +352,9 @@ def slack_api(endpoint, params = {})
 
       parsed = response.json
       raise SlackApiError, "Slack API returned HTTP #{response.status}" unless response.success?
+      if TRANSIENT_API_ERRORS.include?(parsed["error"])
+        raise TransientApiError.new(retry_after: TRANSIENT_API_RETRY_AFTER_SECONDS)
+      end
       raise SlackApiError, "Slack API returned #{parsed['error']}" unless parsed["ok"] == true
 
       parsed
diff --git a/services/console/test/jobs/slack_dm/jobs_test.rb b/services/console/test/jobs/slack_dm/jobs_test.rb
index a86e75973..0c1e345fe 100644
--- a/services/console/test/jobs/slack_dm/jobs_test.rb
+++ b/services/console/test/jobs/slack_dm/jobs_test.rb
@@ -75,13 +75,29 @@ def slack_credential(
     test "SyncCredentialJob allows only one delayed rate-limit retry" do
       credential = slack_credential(app: slack_app)
       job = SlackDm::SyncCredentialJob.new(credential.id)
-      job.executions = SlackDm::SyncCredentialJob::MAX_RATE_LIMIT_EXECUTIONS - 1
+      job.executions = SlackDm::SyncCredentialJob::MAX_RETRYABLE_EXECUTIONS - 1
 
       SlackDm::SyncCredential.stub(:new, ->(*) { rate_limited_sync(retry_after: 120) }) do
         assert_no_enqueued_jobs { job.perform_now }
       end
 
-      assert_equal SlackDm::SyncCredentialJob::MAX_RATE_LIMIT_EXECUTIONS, job.executions
+      assert_equal SlackDm::SyncCredentialJob::MAX_RETRYABLE_EXECUTIONS, job.executions
+    end
+
+    test "SyncCredentialJob defers transient Slack API failures" do
+      credential = slack_credential(app: slack_app)
+      sync = Object.new
+      sync.define_singleton_method(:call) do
+        raise SlackDm::SyncCredential::TransientApiError.new(retry_after: 30)
+      end
+
+      SlackDm::SyncCredential.stub(:new, ->(*) { sync }) do
+        SlackDm::SyncCredentialJob.perform_now(credential.id)
+      end
+
+      retry_job = enqueued_jobs.sole
+      assert_equal SlackDm::SyncCredentialJob, retry_job[:job]
+      assert_equal [ credential.id ], retry_job[:args]
     end
 
     private
diff --git a/services/console/test/services/slack_dm/sync_credential_test.rb b/services/console/test/services/slack_dm/sync_credential_test.rb
index c82e834d4..452efcfc0 100644
--- a/services/console/test/services/slack_dm/sync_credential_test.rb
+++ b/services/console/test/services/slack_dm/sync_credential_test.rb
@@ -329,5 +329,24 @@ def credential
         assert_equal expected, error.retry_after
       end
     end
+
+    test "transient Slack API errors request deferred job execution" do
+      %w[fatal_error internal_error].each do |error_code|
+        response = HttpClient::Response.new(
+          status: 200,
+          body: { ok: false, error: error_code }.to_json,
+          headers: { "content-type" => "application/json" }
+        )
+
+        error = assert_raises(SlackDm::SyncCredential::TransientApiError) do
+          SlackDm::SyncCredential.new(
+            credential,
+            http_client: FakeHttpClient.new(response)
+          ).call
+        end
+
+        assert_equal SlackDm::SyncCredential::TRANSIENT_API_RETRY_AFTER_SECONDS, error.retry_after
+      end
+    end
   end
 end