Add files using upload-large-folder tool

codex-rs/analytics/src/accepted_lines.rs

@@ -0,0 +1,187 @@
+use crate::events::CodexAcceptedLineFingerprintsEventParams;
+use crate::events::CodexAcceptedLineFingerprintsEventRequest;
+use crate::events::TrackEventRequest;
+use codex_git_utils::canonicalize_git_remote_url;
+use codex_git_utils::get_git_remote_urls_assume_git_repo;
+use sha1::Digest;
+use std::path::Path;
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct AcceptedLineCounts {
+    pub(crate) accepted_added_lines: u64,
+    pub(crate) accepted_deleted_lines: u64,
+}
+
+pub(crate) struct AcceptedLineFingerprintEventInput {
+    pub(crate) event_type: &'static str,
+    pub(crate) turn_id: String,
+    pub(crate) thread_id: String,
+    pub(crate) product_surface: Option<String>,
+    pub(crate) model_slug: Option<String>,
+    pub(crate) completed_at: u64,
+    pub(crate) repo_hash: Option<String>,
+    pub(crate) accepted_added_lines: u64,
+    pub(crate) accepted_deleted_lines: u64,
+}
+
+pub(crate) fn accepted_line_counts_from_unified_diff(unified_diff: &str) -> AcceptedLineCounts {
+    let mut in_hunk = false;
+    let mut accepted_added_lines = 0;
+    let mut accepted_deleted_lines = 0;
+
+    for line in unified_diff.lines() {
+        if line.starts_with("diff --git ") {
+            in_hunk = false;
+            continue;
+        }
+
+        if line.starts_with("@@ ") {
+            in_hunk = true;
+            continue;
+        }
+
+        if !in_hunk && (line.starts_with("+++ ") || line.starts_with("--- ")) {
+            continue;
+        }
+
+        if line.starts_with('+') {
+            accepted_added_lines += 1;
+            continue;
+        }
+
+        if line.starts_with('-') {
+            accepted_deleted_lines += 1;
+        }
+    }
+
+    AcceptedLineCounts {
+        accepted_added_lines,
+        accepted_deleted_lines,
+    }
+}
+
+pub fn fingerprint_hash(domain: &str, value: &str) -> String {
+    let mut hasher = sha1::Sha1::new();
+    hasher.update(b"file-line-v1\0");
+    hasher.update(domain.as_bytes());
+    hasher.update(b"\0");
+    hasher.update(value.as_bytes());
+    format!("{:x}", hasher.finalize())
+}
+
+pub(crate) fn accepted_line_fingerprint_event_requests(
+    input: AcceptedLineFingerprintEventInput,
+) -> Vec<TrackEventRequest> {
+    let AcceptedLineFingerprintEventInput {
+        event_type,
+        turn_id,
+        thread_id,
+        product_surface,
+        model_slug,
+        completed_at,
+        repo_hash,
+        accepted_added_lines,
+        accepted_deleted_lines,
+    } = input;
+
+    vec![TrackEventRequest::AcceptedLineFingerprints(Box::new(
+        CodexAcceptedLineFingerprintsEventRequest {
+            event_type: "codex_accepted_line_fingerprints",
+            event_params: CodexAcceptedLineFingerprintsEventParams {
+                event_type,
+                turn_id,
+                thread_id,
+                product_surface,
+                model_slug,
+                completed_at,
+                repo_hash,
+                accepted_added_lines,
+                accepted_deleted_lines,
+                line_fingerprints: [],
+            },
+        },
+    ))]
+}
+
+pub async fn accepted_line_repo_hash_for_cwd(cwd: &Path) -> Option<String> {
+    let remotes = get_git_remote_urls_assume_git_repo(cwd).await?;
+    remotes
+        .get("origin")
+        .or_else(|| remotes.values().next())
+        .map(|remote_url| {
+            let canonical_remote_url = canonicalize_git_remote_url(remote_url.as_str())
+                .unwrap_or_else(|| remote_url.to_string());
+            fingerprint_hash("repo", &canonical_remote_url)
+        })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_accepted_line_counts() {
+        let diff = "\
+diff --git a/src/lib.rs b/src/lib.rs
+index 1111111..2222222
+--- a/src/lib.rs
++++ b/src/lib.rs
+@@ -1,3 +1,5 @@
+-old line
++fn useful() {
++}
++    return user.id;
+ context
+";
+
+        assert_eq!(
+            accepted_line_counts_from_unified_diff(diff),
+            AcceptedLineCounts {
+                accepted_added_lines: 3,
+                accepted_deleted_lines: 1,
+            },
+        );
+    }
+
+    #[test]
+    fn skips_added_file_metadata_headers() {
+        let diff = "\
+diff --git a/new.py b/new.py
+new file mode 100644
+index 0000000..1111111
+--- /dev/null
++++ b/new.py
+@@ -0,0 +1 @@
++print('hello')
+";
+
+        assert_eq!(
+            accepted_line_counts_from_unified_diff(diff),
+            AcceptedLineCounts {
+                accepted_added_lines: 1,
+                accepted_deleted_lines: 0,
+            },
+        );
+    }
+
+    #[test]
+    fn parses_hunk_lines_that_look_like_file_headers() {
+        let diff = "\
+diff --git a/src/lib.rs b/src/lib.rs
+index 1111111..2222222
+--- a/src/lib.rs
++++ b/src/lib.rs
+@@ -1,2 +1,2 @@
+--- old value
++++ new value
+";
+
+        assert_eq!(
+            accepted_line_counts_from_unified_diff(diff),
+            AcceptedLineCounts {
+                accepted_added_lines: 1,
+                accepted_deleted_lines: 1,
+            },
+        );
+    }
+}

codex-rs/analytics/src/analytics_capture.rs

@@ -0,0 +1,34 @@
+use crate::events::TrackEventsRequest;
+use std::fs::File;
+use std::fs::OpenOptions;
+use std::io;
+use std::io::Write;
+use std::path::Path;
+
+pub(crate) const ANALYTICS_EVENTS_CAPTURE_FILE_ENV_VAR: &str =
+    "CODEX_ANALYTICS_EVENTS_CAPTURE_FILE";
+
+pub(crate) fn initialize(path: &Path) -> io::Result<()> {
+    open_capture_file(path).map(drop)
+}
+
+pub(crate) fn append_payload(path: &Path, payload: &TrackEventsRequest) -> io::Result<()> {
+    let mut line = serde_json::to_vec(payload)
+        .map_err(|err| io::Error::new(io::ErrorKind::InvalidData, err))?;
+    line.push(b'\n');
+
+    let mut file = open_capture_file(path)?;
+    file.write_all(&line)?;
+    file.flush()
+}
+
+fn open_capture_file(path: &Path) -> io::Result<File> {
+    let mut options = OpenOptions::new();
+    options.create(true).append(true);
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::OpenOptionsExt;
+        options.mode(0o600);
+    }
+    options.open(path)
+}

codex-rs/analytics/src/client.rs

@@ -0,0 +1,961 @@
+use crate::events::AppServerRpcTransport;
+use crate::events::GuardianReviewAnalyticsResult;
+use crate::events::GuardianReviewTrackContext;
+use crate::events::TrackEventRequest;
+use crate::events::TrackEventsRequest;
+use crate::events::current_runtime_metadata;
+use crate::facts::AnalyticsFact;
+use crate::facts::AnalyticsJsonRpcError;
+use crate::facts::AppInvocation;
+use crate::facts::AppMentionedInput;
+use crate::facts::AppUsedInput;
+use crate::facts::ArtifactOperation;
+use crate::facts::ArtifactOperationInput;
+use crate::facts::CodexGoalEvent;
+use crate::facts::CustomAnalyticsFact;
+use crate::facts::ElicitationType;
+use crate::facts::ExternalAgentConfigImportCompletedInput;
+use crate::facts::ExternalAgentConfigImportFailureInput;
+use crate::facts::HookRunFact;
+use crate::facts::HookRunInput;
+use crate::facts::ImagePreparationFact;
+use crate::facts::McpToolCallElicitation;
+use crate::facts::PluginInstallFailedInput;
+use crate::facts::PluginInstallRequested;
+use crate::facts::PluginInstallRequestedInput;
+use crate::facts::PluginInstallSource;
+use crate::facts::PluginMeasurementsInput;
+use crate::facts::PluginState;
+use crate::facts::PluginStateChangedInput;
+use crate::facts::SkillInvocation;
+use crate::facts::SkillInvokedInput;
+use crate::facts::SubAgentThreadStartedInput;
+use crate::facts::TrackEventsContext;
+use crate::facts::TurnCodexErrorFact;
+use crate::facts::TurnProfileFact;
+use crate::facts::TurnResolvedConfigFact;
+use crate::facts::TurnTokenUsageFact;
+use crate::guardian_v2::GuardianV2Event;
+use crate::now_unix_millis;
+use crate::reducer::AnalyticsReducer;
+use crate::reducer::MAX_PLUGIN_MEASUREMENTS_PER_BATCH;
+use crate::reducer::tracked_tool_item_id;
+use crate::reducer::valid_plugin_measurement_identifier;
+use crate::reducer::valid_plugin_measurement_row;
+use codex_app_server_protocol::ClientRequest;
+use codex_app_server_protocol::ClientResponsePayload;
+use codex_app_server_protocol::InitializeParams;
+use codex_app_server_protocol::ItemCompletedNotification;
+use codex_app_server_protocol::ItemStartedNotification;
+use codex_app_server_protocol::JSONRPCErrorError;
+use codex_app_server_protocol::RequestId;
+use codex_app_server_protocol::ServerNotification;
+use codex_app_server_protocol::ServerRequest;
+use codex_app_server_protocol::ServerResponse;
+use codex_app_server_protocol::Turn;
+use codex_app_server_protocol::TurnCompletedNotification;
+use codex_app_server_protocol::TurnError;
+use codex_app_server_protocol::TurnItemsView;
+use codex_app_server_protocol::TurnStartedNotification;
+use codex_app_server_protocol::TurnStatus;
+use codex_app_server_protocol::item_event_to_server_notification;
+use codex_login::AuthManager;
+use codex_login::CodexAuth;
+use codex_login::default_client::create_client;
+use codex_plugin::PluginId;
+use codex_plugin::PluginTelemetryMetadata;
+use codex_protocol::ThreadId;
+use codex_protocol::items::CollabAgentToolCallItem;
+use codex_protocol::items::CollabAgentToolCallStatus;
+use codex_protocol::items::TurnItem;
+use codex_protocol::protocol::Event;
+use codex_protocol::protocol::EventMsg;
+use codex_protocol::request_permissions::RequestPermissionsResponse;
+use std::collections::HashSet;
+use std::path::PathBuf;
+use std::sync::Arc;
+use std::sync::Mutex;
+use std::time::Duration;
+use tokio::sync::mpsc;
+use tokio::sync::oneshot;
+
+const ANALYTICS_EVENTS_QUEUE_SIZE: usize = 256;
+const ANALYTICS_EVENTS_TIMEOUT: Duration = Duration::from_secs(10);
+// Covers two sequential POSTs plus queue/barrier scheduling; additional queued sends remain best-effort.
+const ANALYTICS_EVENTS_FLUSH_TIMEOUT: Duration = Duration::from_secs(25);
+const ANALYTICS_EVENT_DEDUPE_MAX_KEYS: usize = 4096;
+
+pub(crate) enum AnalyticsEventsQueueMessage {
+    Fact(Box<AnalyticsFact>),
+    Flush(oneshot::Sender<()>),
+}
+
+#[derive(Clone)]
+pub(crate) struct AnalyticsEventsQueue {
+    pub(crate) sender: mpsc::Sender<AnalyticsEventsQueueMessage>,
+    pub(crate) app_used_emitted_keys: Arc<Mutex<HashSet<(String, String)>>>,
+    pub(crate) plugin_used_emitted_keys: Arc<Mutex<HashSet<(String, String)>>>,
+}
+
+#[derive(Clone)]
+pub struct AnalyticsEventsClient {
+    queue: Option<AnalyticsEventsQueue>,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+enum AnalyticsEventsDestination {
+    Http {
+        url: String,
+    },
+    #[cfg(debug_assertions)]
+    CaptureFile {
+        path: PathBuf,
+    },
+}
+
+impl AnalyticsEventsDestination {
+    fn from_base_url(base_url: String) -> Self {
+        let capture_file = analytics_capture_file_from_env();
+        Self::from_base_url_and_capture_file(base_url, capture_file)
+    }
+
+    fn from_base_url_and_capture_file(base_url: String, capture_file: Option<PathBuf>) -> Self {
+        #[cfg(debug_assertions)]
+        if let Some(path) = capture_file {
+            if let Err(err) = crate::analytics_capture::initialize(&path) {
+                tracing::error!(
+                    path = %path.display(),
+                    "failed to initialize analytics event capture; network delivery remains disabled: {err}"
+                );
+            }
+            tracing::warn!(
+                path = %path.display(),
+                "analytics event capture enabled; network delivery is disabled"
+            );
+            return Self::CaptureFile { path };
+        }
+
+        #[cfg(not(debug_assertions))]
+        let _ = capture_file;
+
+        let base_url = base_url.trim_end_matches('/');
+        Self::Http {
+            url: format!("{base_url}/codex/analytics-events/events"),
+        }
+    }
+}
+
+fn analytics_capture_file_from_env() -> Option<PathBuf> {
+    #[cfg(debug_assertions)]
+    {
+        std::env::var_os(crate::analytics_capture::ANALYTICS_EVENTS_CAPTURE_FILE_ENV_VAR)
+            .filter(|value| !value.is_empty())
+            .map(PathBuf::from)
+    }
+
+    #[cfg(not(debug_assertions))]
+    None
+}
+
+impl AnalyticsEventsQueue {
+    fn new(auth_manager: Arc<AuthManager>, destination: AnalyticsEventsDestination) -> Self {
+        let (sender, mut receiver) = mpsc::channel(ANALYTICS_EVENTS_QUEUE_SIZE);
+        tokio::spawn(async move {
+            let mut reducer = AnalyticsReducer::default();
+            while let Some(input) = receiver.recv().await {
+                let input = match input {
+                    AnalyticsEventsQueueMessage::Fact(input) => *input,
+                    AnalyticsEventsQueueMessage::Flush(done_tx) => {
+                        let mut events = Vec::new();
+                        reducer.flush(&mut events);
+                        send_track_events(&auth_manager, &destination, events).await;
+                        let _ = done_tx.send(());
+                        continue;
+                    }
+                };
+                let mut events = Vec::new();
+                reducer.ingest(input, &mut events).await;
+                send_track_events(&auth_manager, &destination, events).await;
+            }
+        });
+        Self {
+            sender,
+            app_used_emitted_keys: Arc::new(Mutex::new(HashSet::new())),
+            plugin_used_emitted_keys: Arc::new(Mutex::new(HashSet::new())),
+        }
+    }
+
+    fn try_send(&self, input: AnalyticsFact) {
+        if self
+            .sender
+            .try_send(AnalyticsEventsQueueMessage::Fact(Box::new(input)))
+            .is_err()
+        {
+            //TODO: add a metric for this
+            tracing::warn!("dropping analytics events: queue is full");
+        }
+    }
+
+    pub(crate) fn should_enqueue_app_used(
+        &self,
+        tracking: &TrackEventsContext,
+        app: &AppInvocation,
+    ) -> bool {
+        let Some(connector_id) = app.connector_id.as_ref() else {
+            return true;
+        };
+        let mut emitted = self
+            .app_used_emitted_keys
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        if emitted.len() >= ANALYTICS_EVENT_DEDUPE_MAX_KEYS {
+            emitted.clear();
+        }
+        emitted.insert((tracking.turn_id.clone(), connector_id.clone()))
+    }
+
+    pub(crate) fn should_enqueue_plugin_used(
+        &self,
+        tracking: &TrackEventsContext,
+        plugin: &PluginTelemetryMetadata,
+    ) -> bool {
+        let mut emitted = self
+            .plugin_used_emitted_keys
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        if emitted.len() >= ANALYTICS_EVENT_DEDUPE_MAX_KEYS {
+            emitted.clear();
+        }
+        let Some(plugin_id) = plugin
+            .plugin_id
+            .as_ref()
+            .map(PluginId::as_key)
+            .or_else(|| plugin.remote_plugin_id.clone())
+        else {
+            return true;
+        };
+        emitted.insert((tracking.turn_id.clone(), plugin_id))
+    }
+}
+
+impl AnalyticsEventsClient {
+    pub fn new(
+        auth_manager: Arc<AuthManager>,
+        base_url: String,
+        analytics_enabled: Option<bool>,
+    ) -> Self {
+        let destination = AnalyticsEventsDestination::from_base_url(base_url);
+        Self {
+            queue: (analytics_enabled != Some(false))
+                .then(|| AnalyticsEventsQueue::new(Arc::clone(&auth_manager), destination)),
+        }
+    }
+
+    pub fn disabled() -> Self {
+        Self { queue: None }
+    }
+
+    pub async fn flush(&self) {
+        let Some(queue) = self.queue.as_ref() else {
+            return;
+        };
+        let (done_tx, done_rx) = oneshot::channel();
+        let flushed = tokio::time::timeout(ANALYTICS_EVENTS_FLUSH_TIMEOUT, async {
+            if queue
+                .sender
+                .send(AnalyticsEventsQueueMessage::Flush(done_tx))
+                .await
+                .is_err()
+            {
+                return false;
+            }
+            done_rx.await.is_ok()
+        })
+        .await;
+
+        if !matches!(flushed, Ok(true)) {
+            tracing::warn!("timed out or failed while flushing analytics events");
+        }
+    }
+
+    pub fn is_enabled(&self) -> bool {
+        self.queue.is_some()
+    }
+
+    pub fn track_plugin_measurements(&self, mut input: PluginMeasurementsInput) {
+        if input.rows.is_empty()
+            || input.rows.len() > MAX_PLUGIN_MEASUREMENTS_PER_BATCH
+            || !valid_plugin_measurement_identifier(&input.operation)
+        {
+            return;
+        }
+        input.rows.retain(valid_plugin_measurement_row);
+        if input.rows.is_empty() {
+            return;
+        }
+        self.record_fact(AnalyticsFact::Custom(
+            CustomAnalyticsFact::PluginMeasurements(input),
+        ));
+    }
+
+    pub fn track_skill_invocations(
+        &self,
+        tracking: TrackEventsContext,
+        invocations: Vec<SkillInvocation>,
+    ) {
+        if invocations.is_empty() {
+            return;
+        }
+        self.record_fact(AnalyticsFact::Custom(CustomAnalyticsFact::SkillInvoked(
+            SkillInvokedInput {
+                tracking,
+                invocations,
+            },
+        )));
+    }
+
+    pub fn track_artifact_operation(
+        &self,
+        tracking: TrackEventsContext,
+        operation: ArtifactOperation,
+    ) {
+        self.record_fact(AnalyticsFact::Custom(
+            CustomAnalyticsFact::ArtifactOperation(ArtifactOperationInput {
+                tracking,
+                operation,
+            }),
+        ));
+    }
+
+    pub fn track_initialize(
+        &self,
+        connection_id: u64,
+        params: InitializeParams,
+        product_client_id: String,
+        rpc_transport: AppServerRpcTransport,
+    ) {
+        self.record_fact(AnalyticsFact::Initialize {
+            connection_id,
+            params,
+            product_client_id,
+            runtime: current_runtime_metadata(),
+            rpc_transport,
+        });
+    }
+
+    pub fn track_subagent_thread_started(&self, input: SubAgentThreadStartedInput) {
+        self.record_fact(AnalyticsFact::Custom(
+            CustomAnalyticsFact::SubAgentThreadStarted(input),
+        ));
+    }
+
+    /// Logs Guardian turn and tool events that bypass the app-server listener.
+    pub fn track_guardian_session_event(&self, thread_id: ThreadId, event: &Event) {
+        if let Some(notification) = session_event_to_analytics_notification(thread_id, event) {
+            self.track_notification(&notification);
+        }
+    }
+
+    pub fn track_collab_tool_call(
+        &self,
+        turn_id: String,
+        mut item: CollabAgentToolCallItem,
+        started_at_ms: i64,
+        completed_at_ms: i64,
+    ) {
+        let thread_id = item.sender_thread_id.to_string();
+        let completed_item = TurnItem::CollabAgentToolCall(item.clone()).into();
+        item.status = CollabAgentToolCallStatus::InProgress;
+
+        self.track_notification(&ServerNotification::ItemStarted(ItemStartedNotification {
+            item: TurnItem::CollabAgentToolCall(item).into(),
+            thread_id: thread_id.clone(),
+            turn_id: turn_id.clone(),
+            started_at_ms,
+        }));
+        self.track_notification(&ServerNotification::ItemCompleted(
+            ItemCompletedNotification {
+                item: completed_item,
+                thread_id,
+                turn_id,
+                completed_at_ms,
+            },
+        ));
+    }
+
+    pub fn track_code_mode_tool_call(&self, input: crate::facts::CodeModeToolCallFact) {
+        self.record_fact(AnalyticsFact::Custom(
+            CustomAnalyticsFact::CodeModeToolCall(input),
+        ));
+    }
+
+    pub fn track_control_tool_call(&self, input: crate::facts::ControlToolCallFact) {
+        self.record_fact(AnalyticsFact::Custom(CustomAnalyticsFact::ControlToolCall(
+            input,
+        )));
+    }
+
+    pub fn track_guardian_review(
+        &self,
+        tracking: &GuardianReviewTrackContext,
+        result: GuardianReviewAnalyticsResult,
+        completed_at_ms: u64,
+    ) {
+        self.record_fact(AnalyticsFact::Custom(CustomAnalyticsFact::GuardianReview(
+            Box::new(tracking.event_params(result, completed_at_ms)),
+        )));
+    }
+
+    pub fn track_app_mentioned(&self, tracking: TrackEventsContext, mentions: Vec<AppInvocation>) {
+        if mentions.is_empty() {
+            return;
+        }
+        self.record_fact(AnalyticsFact::Custom(CustomAnalyticsFact::AppMentioned(
+            AppMentionedInput { tracking, mentions },
+        )));
+    }
+
+    pub fn track_request(
+        &self,
+        connection_id: u64,
+        request_id: RequestId,
+        request: &ClientRequest,
+    ) {
+        if let ClientRequest::TurnInterrupt { params, .. } = request {
+            if params.turn_id.is_empty() {
+                return;
+            }
+            self.record_fact(AnalyticsFact::ExplicitClientInterruptRequest {
+                connection_id,
+                request_id,
+                turn_id: params.turn_id.clone(),
+                requested_at_ms: now_unix_millis(),
+            });
+            return;
+        }
+        if !matches!(
+            request,
+            ClientRequest::TurnStart { .. } | ClientRequest::TurnSteer { .. }
+        ) {
+            return;
+        }
+        self.record_fact(AnalyticsFact::ClientRequest {
+            connection_id,
+            request_id,
+            request: Box::new(request.clone()),
+        });
+    }
+
+    pub fn track_app_used(
+        &self,
+        tracking: TrackEventsContext,
+        app: AppInvocation,
+        elicitation_type: Option<ElicitationType>,
+    ) {
+        let Some(queue) = self.queue.as_ref() else {
+            return;
+        };
+        if !queue.should_enqueue_app_used(&tracking, &app) {
+            return;
+        }
+        self.record_fact(AnalyticsFact::Custom(CustomAnalyticsFact::AppUsed(
+            AppUsedInput {
+                tracking,
+                app,
+                elicitation_type,
+            },
+        )));
+    }
+
+    pub fn track_mcp_tool_call_elicitation(&self, input: McpToolCallElicitation) {
+        self.record_fact(AnalyticsFact::Custom(
+            CustomAnalyticsFact::McpToolCallElicitation(input),
+        ));
+    }
+
+    pub fn track_hook_run(&self, tracking: TrackEventsContext, hook: HookRunFact) {
+        self.record_fact(AnalyticsFact::Custom(CustomAnalyticsFact::HookRun(
+            HookRunInput { tracking, hook },
+        )));
+    }
+
+    pub fn track_plugin_used(&self, tracking: TrackEventsContext, plugin: PluginTelemetryMetadata) {
+        let Some(queue) = self.queue.as_ref() else {
+            return;
+        };
+        if !queue.should_enqueue_plugin_used(&tracking, &plugin) {
+            return;
+        }
+        self.record_fact(AnalyticsFact::Custom(CustomAnalyticsFact::PluginUsed(
+            crate::facts::PluginUsedInput { tracking, plugin },
+        )));
+    }
+
+    pub fn track_plugin_install_requested(
+        &self,
+        tracking: TrackEventsContext,
+        request: PluginInstallRequested,
+    ) {
+        self.record_fact(AnalyticsFact::Custom(
+            CustomAnalyticsFact::PluginInstallRequested(PluginInstallRequestedInput {
+                tracking,
+                request,
+            }),
+        ));
+    }
+
+    pub fn track_compaction(&self, event: crate::facts::CodexCompactionEvent) {
+        self.record_fact(AnalyticsFact::Custom(CustomAnalyticsFact::Compaction(
+            Box::new(event),
+        )));
+    }
+
+    pub fn track_guardian_v2_event(&self, event: GuardianV2Event) {
+        self.record_fact(AnalyticsFact::Custom(CustomAnalyticsFact::GuardianV2(
+            Box::new(event),
+        )));
+    }
+
+    pub fn track_goal_event(&self, event: CodexGoalEvent) {
+        self.record_fact(AnalyticsFact::Custom(CustomAnalyticsFact::Goal(Box::new(
+            event,
+        ))));
+    }
+
+    pub fn track_thread_hint_status(&self, event: crate::thread_hint::ThreadHintStatusEvent) {
+        self.record_fact(AnalyticsFact::Custom(
+            CustomAnalyticsFact::ThreadHintStatus(Box::new(event)),
+        ));
+    }
+
+    pub fn track_image_preparation(&self, fact: ImagePreparationFact) {
+        self.record_fact(AnalyticsFact::Custom(
+            CustomAnalyticsFact::ImagePreparation(Box::new(fact)),
+        ));
+    }
+
+    pub fn track_turn_resolved_config(&self, fact: TurnResolvedConfigFact) {
+        self.record_fact(AnalyticsFact::Custom(
+            CustomAnalyticsFact::TurnResolvedConfig(Box::new(fact)),
+        ));
+    }
+
+    pub fn track_turn_token_usage(&self, fact: TurnTokenUsageFact) {
+        self.record_fact(AnalyticsFact::Custom(CustomAnalyticsFact::TurnTokenUsage(
+            Box::new(fact),
+        )));
+    }
+
+    pub fn track_turn_profile(&self, fact: TurnProfileFact) {
+        self.record_fact(AnalyticsFact::Custom(CustomAnalyticsFact::TurnProfile(
+            Box::new(fact),
+        )));
+    }
+
+    pub fn track_turn_codex_error(&self, fact: TurnCodexErrorFact) {
+        self.record_fact(AnalyticsFact::Custom(CustomAnalyticsFact::TurnCodexError(
+            Box::new(fact),
+        )));
+    }
+
+    pub fn track_plugin_installed(&self, plugin: PluginTelemetryMetadata) {
+        self.record_fact(AnalyticsFact::Custom(
+            CustomAnalyticsFact::PluginStateChanged(PluginStateChangedInput {
+                plugin,
+                state: PluginState::Installed,
+            }),
+        ));
+    }
+
+    pub fn track_plugin_install_failed(
+        &self,
+        plugin: PluginTelemetryMetadata,
+        source: PluginInstallSource,
+        error_type: String,
+        sub_error_type: Option<String>,
+    ) {
+        self.record_fact(AnalyticsFact::Custom(
+            CustomAnalyticsFact::PluginInstallFailed(PluginInstallFailedInput {
+                plugin,
+                source,
+                error_type,
+                sub_error_type,
+            }),
+        ));
+    }
+
+    pub fn track_external_agent_config_import_completed(
+        &self,
+        input: ExternalAgentConfigImportCompletedInput,
+    ) {
+        self.record_fact(AnalyticsFact::Custom(
+            CustomAnalyticsFact::ExternalAgentConfigImportCompleted(input),
+        ));
+    }
+
+    pub fn track_external_agent_config_import_failure(
+        &self,
+        input: ExternalAgentConfigImportFailureInput,
+    ) {
+        self.record_fact(AnalyticsFact::Custom(
+            CustomAnalyticsFact::ExternalAgentConfigImportFailure(input),
+        ));
+    }
+
+    pub fn track_plugin_uninstalled(&self, plugin: PluginTelemetryMetadata) {
+        self.record_fact(AnalyticsFact::Custom(
+            CustomAnalyticsFact::PluginStateChanged(PluginStateChangedInput {
+                plugin,
+                state: PluginState::Uninstalled,
+            }),
+        ));
+    }
+
+    pub fn track_plugin_enabled(&self, plugin: PluginTelemetryMetadata) {
+        self.record_fact(AnalyticsFact::Custom(
+            CustomAnalyticsFact::PluginStateChanged(PluginStateChangedInput {
+                plugin,
+                state: PluginState::Enabled,
+            }),
+        ));
+    }
+
+    pub fn track_plugin_disabled(&self, plugin: PluginTelemetryMetadata) {
+        self.record_fact(AnalyticsFact::Custom(
+            CustomAnalyticsFact::PluginStateChanged(PluginStateChangedInput {
+                plugin,
+                state: PluginState::Disabled,
+            }),
+        ));
+    }
+
+    pub(crate) fn record_fact(&self, input: AnalyticsFact) {
+        if let Some(queue) = self.queue.as_ref() {
+            queue.try_send(input);
+        }
+    }
+
+    pub fn track_response(
+        &self,
+        connection_id: u64,
+        request_id: RequestId,
+        response: &ClientResponsePayload,
+    ) {
+        self.track_response_inner(
+            connection_id,
+            request_id,
+            response,
+            /*thread_originator*/ None,
+        );
+    }
+
+    pub fn track_response_with_thread_originator(
+        &self,
+        connection_id: u64,
+        request_id: RequestId,
+        response: &ClientResponsePayload,
+        thread_originator: String,
+    ) {
+        self.track_response_inner(connection_id, request_id, response, Some(thread_originator));
+    }
+
+    fn track_response_inner(
+        &self,
+        connection_id: u64,
+        request_id: RequestId,
+        response: &ClientResponsePayload,
+        thread_originator: Option<String>,
+    ) {
+        if !matches!(
+            response,
+            ClientResponsePayload::ThreadStart(_)
+                | ClientResponsePayload::ThreadResume(_)
+                | ClientResponsePayload::ThreadFork(_)
+                | ClientResponsePayload::TurnStart(_)
+                | ClientResponsePayload::TurnSteer(_)
+                | ClientResponsePayload::TurnInterrupt(_)
+        ) {
+            return;
+        }
+        if serde_json::to_writer(std::io::sink(), response).is_err() {
+            return;
+        }
+        self.record_fact(AnalyticsFact::ClientResponse {
+            connection_id,
+            request_id,
+            response: Box::new(response.clone()),
+            thread_originator,
+        });
+    }
+
+    pub fn track_error_response(
+        &self,
+        connection_id: u64,
+        request_id: RequestId,
+        error: JSONRPCErrorError,
+        error_type: Option<AnalyticsJsonRpcError>,
+    ) {
+        self.record_fact(AnalyticsFact::ErrorResponse {
+            connection_id,
+            request_id,
+            error,
+            error_type,
+        });
+    }
+
+    pub fn track_server_request(&self, connection_id: u64, request: ServerRequest) {
+        self.record_fact(AnalyticsFact::ServerRequest {
+            connection_id,
+            request: Box::new(request),
+        });
+    }
+
+    pub fn track_server_response(&self, completed_at_ms: u64, response: ServerResponse) {
+        self.record_fact(AnalyticsFact::ServerResponse {
+            completed_at_ms,
+            response: Box::new(response),
+        });
+    }
+
+    pub fn track_effective_permissions_approval_response(
+        &self,
+        completed_at_ms: u64,
+        request_id: RequestId,
+        response: RequestPermissionsResponse,
+    ) {
+        self.record_fact(AnalyticsFact::EffectivePermissionsApprovalResponse {
+            completed_at_ms,
+            request_id,
+            response: Box::new(response),
+        });
+    }
+
+    pub fn track_server_request_aborted(&self, completed_at_ms: u64, request_id: RequestId) {
+        self.record_fact(AnalyticsFact::ServerRequestAborted {
+            completed_at_ms,
+            request_id,
+        });
+    }
+
+    /// Records analytics-relevant notifications without cloning ignored variants.
+    pub fn track_notification(&self, notification: &ServerNotification) {
+        if !matches!(
+            notification,
+            ServerNotification::ThreadArchived(_)
+                | ServerNotification::ThreadClosed(_)
+                | ServerNotification::ThreadUnarchived(_)
+                | ServerNotification::TurnStarted(_)
+                | ServerNotification::TurnCompleted(_)
+                | ServerNotification::TurnDiffUpdated(_)
+                | ServerNotification::ItemStarted(_)
+                | ServerNotification::ItemCompleted(_)
+                | ServerNotification::ItemGuardianApprovalReviewStarted(_)
+                | ServerNotification::ItemGuardianApprovalReviewCompleted(_)
+        ) {
+            return;
+        }
+        self.record_fact(AnalyticsFact::Notification(Box::new(notification.clone())));
+    }
+}
+
+fn session_event_to_analytics_notification(
+    thread_id: ThreadId,
+    event: &Event,
+) -> Option<ServerNotification> {
+    let notification = match &event.msg {
+        EventMsg::ItemStarted(started) => item_event_to_server_notification(
+            event.msg.clone(),
+            &started.thread_id.to_string(),
+            &started.turn_id,
+        ),
+        EventMsg::ItemCompleted(completed) => item_event_to_server_notification(
+            event.msg.clone(),
+            &completed.thread_id.to_string(),
+            &completed.turn_id,
+        ),
+        EventMsg::TurnStarted(started) => {
+            ServerNotification::TurnStarted(TurnStartedNotification {
+                thread_id: thread_id.to_string(),
+                turn: Turn {
+                    started_at: started.started_at,
+                    ..analytics_turn(&started.turn_id, TurnStatus::InProgress)
+                },
+            })
+        }
+        EventMsg::TurnComplete(completed) => {
+            let error = completed.error.as_ref().map(|error| TurnError {
+                message: String::new(),
+                codex_error_info: error.codex_error_info.clone().map(Into::into),
+                additional_details: None,
+                misalignment: None,
+            });
+            let status = if error.is_some() {
+                TurnStatus::Failed
+            } else {
+                TurnStatus::Completed
+            };
+            ServerNotification::TurnCompleted(TurnCompletedNotification {
+                thread_id: thread_id.to_string(),
+                turn: Turn {
+                    error,
+                    started_at: completed.started_at,
+                    completed_at: completed.completed_at,
+                    duration_ms: completed.duration_ms,
+                    ..analytics_turn(&completed.turn_id, status)
+                },
+            })
+        }
+        EventMsg::TurnAborted(aborted) => {
+            ServerNotification::TurnCompleted(TurnCompletedNotification {
+                thread_id: thread_id.to_string(),
+                turn: Turn {
+                    started_at: aborted.started_at,
+                    completed_at: aborted.completed_at,
+                    duration_ms: aborted.duration_ms,
+                    ..analytics_turn(
+                        aborted.turn_id.as_deref().unwrap_or(&event.id),
+                        TurnStatus::Interrupted,
+                    )
+                },
+            })
+        }
+        // Legacy tool events accompany canonical items. Messages, reasoning, and review
+        // content must not enter the analytics queue.
+        _ => return None,
+    };
+    match &notification {
+        ServerNotification::ItemStarted(ItemStartedNotification { item, .. })
+        | ServerNotification::ItemCompleted(ItemCompletedNotification { item, .. }) => {
+            tracked_tool_item_id(item)?;
+        }
+        _ => {}
+    }
+    Some(notification)
+}
+
+fn analytics_turn(turn_id: &str, status: TurnStatus) -> Turn {
+    Turn {
+        id: turn_id.to_string(),
+        items: Vec::new(),
+        items_view: TurnItemsView::NotLoaded,
+        status,
+        error: None,
+        started_at: None,
+        completed_at: None,
+        duration_ms: None,
+    }
+}
+
+async fn send_track_events(
+    auth_manager: &AuthManager,
+    destination: &AnalyticsEventsDestination,
+    mut events: Vec<TrackEventRequest>,
+) {
+    if events.is_empty() {
+        return;
+    }
+
+    let Some(auth) = auth_manager.auth().await else {
+        return;
+    };
+    if auth.is_api_key_auth() {
+        events.retain(TrackEventRequest::can_send_with_api_key_auth);
+    } else if !auth.uses_codex_backend() {
+        return;
+    }
+    if events.is_empty() {
+        return;
+    }
+
+    for events in track_event_request_batches(events) {
+        send_track_events_request(&auth, destination, events).await;
+    }
+}
+
+fn track_event_request_batches(events: Vec<TrackEventRequest>) -> Vec<Vec<TrackEventRequest>> {
+    let mut batches = Vec::new();
+    let mut current_batch = Vec::new();
+
+    for event in events {
+        if event.should_send_in_isolated_request() {
+            if !current_batch.is_empty() {
+                batches.push(current_batch);
+                current_batch = Vec::new();
+            }
+            batches.push(vec![event]);
+        } else {
+            current_batch.push(event);
+        }
+    }
+
+    if !current_batch.is_empty() {
+        batches.push(current_batch);
+    }
+
+    batches
+}
+
+async fn send_track_events_request(
+    auth: &CodexAuth,
+    destination: &AnalyticsEventsDestination,
+    events: Vec<TrackEventRequest>,
+) {
+    if events.is_empty() {
+        return;
+    }
+
+    let payload = TrackEventsRequest { events };
+
+    #[cfg(debug_assertions)]
+    if capture_track_events_request(destination, &payload) {
+        return;
+    }
+
+    let url = match destination {
+        AnalyticsEventsDestination::Http { url } => url,
+        #[cfg(debug_assertions)]
+        AnalyticsEventsDestination::CaptureFile { .. } => return,
+    };
+    let response = create_client()
+        .post(url)
+        .timeout(ANALYTICS_EVENTS_TIMEOUT)
+        .headers(codex_model_provider::auth_provider_from_auth(auth).to_auth_headers())
+        .header("Content-Type", "application/json")
+        .json(&payload)
+        .send()
+        .await;
+
+    match response {
+        Ok(response) if response.status().is_success() => {}
+        Ok(response) => {
+            let status = response.status();
+            let body = response.text().await.unwrap_or_default();
+            tracing::warn!("events failed with status {status}: {body}");
+        }
+        Err(err) => {
+            tracing::warn!("failed to send events request: {err}");
+        }
+    }
+}
+
+#[cfg(debug_assertions)]
+fn capture_track_events_request(
+    destination: &AnalyticsEventsDestination,
+    payload: &TrackEventsRequest,
+) -> bool {
+    let AnalyticsEventsDestination::CaptureFile { path } = destination else {
+        return false;
+    };
+
+    if let Err(err) = crate::analytics_capture::append_payload(path, payload) {
+        tracing::error!(
+            path = %path.display(),
+            "failed to capture analytics events; network delivery remains disabled: {err}"
+        );
+    }
+    true
+}
+
+#[cfg(test)]
+#[path = "client_tests.rs"]
+mod tests;

codex-rs/analytics/src/client_tests.rs

@@ -0,0 +1,1020 @@
+use super::AnalyticsEventsClient;
+use super::AnalyticsEventsDestination;
+use super::AnalyticsEventsQueue;
+use super::AnalyticsEventsQueueMessage;
+#[cfg(debug_assertions)]
+use super::capture_track_events_request;
+#[cfg(debug_assertions)]
+use super::send_track_events;
+#[cfg(debug_assertions)]
+use super::send_track_events_request;
+use super::track_event_request_batches;
+#[cfg(debug_assertions)]
+use crate::events::AppServerRpcTransport;
+use crate::events::CodexAcceptedLineFingerprintsEventParams;
+use crate::events::CodexAcceptedLineFingerprintsEventRequest;
+#[cfg(debug_assertions)]
+use crate::events::CodexAppServerClientMetadata;
+#[cfg(debug_assertions)]
+use crate::events::CodexMcpToolCallEventParams;
+#[cfg(debug_assertions)]
+use crate::events::CodexMcpToolCallEventRequest;
+#[cfg(debug_assertions)]
+use crate::events::CodexPluginMeasurementEventParams;
+#[cfg(debug_assertions)]
+use crate::events::CodexPluginMeasurementEventRequest;
+#[cfg(debug_assertions)]
+use crate::events::CodexPluginMetadata;
+#[cfg(debug_assertions)]
+use crate::events::CodexPluginUsedEventRequest;
+#[cfg(debug_assertions)]
+use crate::events::CodexPluginUsedMetadata;
+#[cfg(debug_assertions)]
+use crate::events::CodexRuntimeMetadata;
+#[cfg(debug_assertions)]
+use crate::events::CodexToolItemEventBase;
+#[cfg(debug_assertions)]
+use crate::events::FinalApprovalOutcome;
+use crate::events::SkillInvocationEventParams;
+use crate::events::SkillInvocationEventRequest;
+#[cfg(debug_assertions)]
+use crate::events::ThreadArchiveAction;
+#[cfg(debug_assertions)]
+use crate::events::ThreadArchiveEvent;
+#[cfg(debug_assertions)]
+use crate::events::ThreadArchiveEventParams;
+#[cfg(debug_assertions)]
+use crate::events::ToolItemTerminalStatus;
+use crate::events::TrackEventRequest;
+#[cfg(debug_assertions)]
+use crate::events::codex_artifact_operation_event_request;
+use crate::facts::AnalyticsFact;
+use crate::facts::AppInvocation;
+#[cfg(debug_assertions)]
+use crate::facts::ArtifactOperation;
+#[cfg(debug_assertions)]
+use crate::facts::ArtifactOperationLifecycle;
+use crate::facts::CustomAnalyticsFact;
+use crate::facts::ElicitationType;
+use crate::facts::InvocationType;
+use crate::facts::PluginMeasurementRow;
+use crate::facts::PluginMeasurementsInput;
+use crate::facts::TrackEventsContext;
+use crate::reducer::MAX_PLUGIN_MEASUREMENTS_PER_BATCH;
+use codex_app_server_protocol::ApprovalsReviewer as AppServerApprovalsReviewer;
+use codex_app_server_protocol::AskForApproval as AppServerAskForApproval;
+use codex_app_server_protocol::ClientRequest;
+use codex_app_server_protocol::ClientResponsePayload;
+use codex_app_server_protocol::CommandExecutionOutputDeltaNotification;
+use codex_app_server_protocol::RequestId;
+use codex_app_server_protocol::SandboxPolicy as AppServerSandboxPolicy;
+use codex_app_server_protocol::ServerNotification;
+use codex_app_server_protocol::SessionSource as AppServerSessionSource;
+use codex_app_server_protocol::Thread;
+use codex_app_server_protocol::ThreadArchiveParams;
+use codex_app_server_protocol::ThreadArchiveResponse;
+use codex_app_server_protocol::ThreadArchivedNotification;
+use codex_app_server_protocol::ThreadForkResponse;
+use codex_app_server_protocol::ThreadResumeResponse;
+use codex_app_server_protocol::ThreadStartResponse;
+use codex_app_server_protocol::ThreadStatus as AppServerThreadStatus;
+use codex_app_server_protocol::Turn;
+use codex_app_server_protocol::TurnDiffUpdatedNotification;
+use codex_app_server_protocol::TurnInterruptParams;
+use codex_app_server_protocol::TurnInterruptResponse;
+use codex_app_server_protocol::TurnStartParams;
+use codex_app_server_protocol::TurnStartResponse;
+use codex_app_server_protocol::TurnStatus as AppServerTurnStatus;
+use codex_app_server_protocol::TurnSteerParams;
+use codex_app_server_protocol::TurnSteerResponse;
+#[cfg(debug_assertions)]
+use codex_login::AuthManager;
+use codex_utils_absolute_path::test_support::PathBufExt;
+use codex_utils_absolute_path::test_support::test_path_buf;
+use pretty_assertions::assert_eq;
+use std::collections::BTreeMap;
+use std::collections::HashSet;
+#[cfg(debug_assertions)]
+use std::fs;
+#[cfg(debug_assertions)]
+use std::path::PathBuf;
+use std::sync::Arc;
+use std::sync::Mutex;
+#[cfg(debug_assertions)]
+use std::time::SystemTime;
+use tokio::sync::mpsc;
+use tokio::sync::mpsc::error::TryRecvError;
+
+#[cfg(debug_assertions)]
+impl AnalyticsEventsClient {
+    pub(crate) fn new_for_capture_file(auth_manager: Arc<AuthManager>, path: PathBuf) -> Self {
+        Self {
+            queue: Some(AnalyticsEventsQueue::new(
+                auth_manager,
+                AnalyticsEventsDestination::CaptureFile { path },
+            )),
+        }
+    }
+}
+
+fn sample_accepted_line_fingerprint_event(thread_id: &str) -> TrackEventRequest {
+    TrackEventRequest::AcceptedLineFingerprints(Box::new(
+        CodexAcceptedLineFingerprintsEventRequest {
+            event_type: "codex_accepted_line_fingerprints",
+            event_params: CodexAcceptedLineFingerprintsEventParams {
+                event_type: "codex.accepted_line_fingerprints",
+                turn_id: "turn-1".to_string(),
+                thread_id: thread_id.to_string(),
+                product_surface: Some("codex".to_string()),
+                model_slug: Some("gpt-5.1-codex".to_string()),
+                completed_at: 1,
+                repo_hash: None,
+                accepted_added_lines: 1,
+                accepted_deleted_lines: 0,
+                line_fingerprints: [],
+            },
+        },
+    ))
+}
+
+fn sample_skill_track_event(thread_id: &str, plugin_id: Option<&str>) -> TrackEventRequest {
+    TrackEventRequest::SkillInvocation(SkillInvocationEventRequest {
+        event_type: "skill_invocation",
+        skill_id: format!("skill-{thread_id}"),
+        skill_name: "doc".to_string(),
+        event_params: SkillInvocationEventParams {
+            product_client_id: None,
+            skill_scope: None,
+            plugin_id: plugin_id.map(str::to_string),
+            remote_plugin_id: None,
+            thread_id: Some(thread_id.to_string()),
+            turn_id: Some("turn-1".to_string()),
+            invoke_type: Some(InvocationType::Explicit),
+            model_slug: Some("gpt-5.1-codex".to_string()),
+        },
+    })
+}
+
+#[cfg(debug_assertions)]
+fn sample_artifact_operation_event(thread_id: &str) -> TrackEventRequest {
+    TrackEventRequest::ArtifactOperation(codex_artifact_operation_event_request(
+        TrackEventsContext {
+            model_slug: "gpt-5.1-codex".to_string(),
+            thread_id: thread_id.to_string(),
+            turn_id: "turn-1".to_string(),
+            product_client_id: "codex_desktop".to_string(),
+        },
+        ArtifactOperation {
+            item_id: format!("item-{thread_id}"),
+            lifecycle: ArtifactOperationLifecycle::Started,
+            occurred_at_ms: 1,
+            plugin_id: "presentations@openai-primary-runtime".to_string(),
+            script_path: "skills/presentations/container_tools/mark_artifact_operation_started.mjs"
+                .to_string(),
+            skill: "presentations".to_string(),
+            artifact_type: "presentation".to_string(),
+            operation_kind: "create".to_string(),
+            expected_output_count: 1,
+            output_format: "pptx".to_string(),
+            execution_backend: "unified_exec".to_string(),
+        },
+    ))
+}
+
+fn sample_regular_track_event(thread_id: &str) -> TrackEventRequest {
+    sample_skill_track_event(thread_id, /*plugin_id*/ None)
+}
+
+#[cfg(debug_assertions)]
+fn sample_mcp_tool_call_event(thread_id: &str, plugin_id: Option<&str>) -> TrackEventRequest {
+    TrackEventRequest::McpToolCall(CodexMcpToolCallEventRequest {
+        event_type: "codex_mcp_tool_call_event",
+        event_params: CodexMcpToolCallEventParams {
+            base: CodexToolItemEventBase {
+                thread_id: thread_id.to_string(),
+                session_id: format!("session-{thread_id}"),
+                turn_id: "turn-1".to_string(),
+                root_turn_id: None,
+                item_id: format!("item-{thread_id}"),
+                cell_id: None,
+                parent_call_id: None,
+                originating_response_id: None,
+                subsequent_response_id: None,
+                app_server_client: CodexAppServerClientMetadata {
+                    product_client_id: "codex_desktop".to_string(),
+                    client_name: None,
+                    client_version: None,
+                    rpc_transport: AppServerRpcTransport::InProcess,
+                    experimental_api_enabled: None,
+                },
+                runtime: CodexRuntimeMetadata {
+                    codex_rs_version: "0.0.0".to_string(),
+                    runtime_os: "test".to_string(),
+                    runtime_os_version: "test".to_string(),
+                    runtime_arch: "test".to_string(),
+                },
+                thread_source: None,
+                subagent_source: None,
+                parent_thread_id: None,
+                tool_name: "search".to_string(),
+                tool_event_type: None,
+                started_at_ms: 1,
+                completed_at_ms: 2,
+                duration_ms: Some(1),
+                execution_duration_ms: Some(1),
+                review_count: 0,
+                guardian_review_count: 0,
+                user_review_count: 0,
+                final_approval_outcome: FinalApprovalOutcome::NotNeeded,
+                terminal_status: ToolItemTerminalStatus::Completed,
+                failure_kind: None,
+                requested_additional_permissions: false,
+                requested_network_access: false,
+            },
+            mcp_server_name: "sample".to_string(),
+            mcp_tool_name: "search".to_string(),
+            mcp_error_present: false,
+            plugin_id: plugin_id.map(str::to_string),
+            connector_id: None,
+            elicitation_type: None,
+        },
+    })
+}
+
+#[cfg(debug_assertions)]
+fn sample_plugin_used_track_event(thread_id: &str, plugin_id: Option<&str>) -> TrackEventRequest {
+    TrackEventRequest::PluginUsed(CodexPluginUsedEventRequest {
+        event_type: "codex_plugin_used",
+        event_params: CodexPluginUsedMetadata {
+            plugin: CodexPluginMetadata {
+                plugin_id: plugin_id.map(str::to_string),
+                remote_plugin_id: None,
+                plugin_name: Some("sample".to_string()),
+                marketplace_name: Some("test".to_string()),
+                has_skills: Some(true),
+                mcp_server_count: Some(1),
+                connector_ids: Some(vec!["calendar".to_string()]),
+                product_client_id: Some("codex_desktop".to_string()),
+            },
+            mcp_server_names: Some(vec!["mcp-1".to_string()]),
+            thread_id: Some(thread_id.to_string()),
+            turn_id: Some("turn-1".to_string()),
+            model_slug: Some("gpt-5.1-codex".to_string()),
+        },
+    })
+}
+
+#[cfg(debug_assertions)]
+fn unique_capture_path(name: &str) -> PathBuf {
+    let nonce = SystemTime::now()
+        .duration_since(SystemTime::UNIX_EPOCH)
+        .expect("system clock should be after Unix epoch")
+        .as_nanos();
+    std::env::temp_dir().join(format!(
+        "codex-analytics-{name}-{}-{nonce}.jsonl",
+        std::process::id()
+    ))
+}
+
+fn client_with_receiver() -> (
+    AnalyticsEventsClient,
+    mpsc::Receiver<AnalyticsEventsQueueMessage>,
+) {
+    let (sender, receiver) = mpsc::channel(8);
+    let queue = AnalyticsEventsQueue {
+        sender,
+        app_used_emitted_keys: Arc::new(Mutex::new(HashSet::new())),
+        plugin_used_emitted_keys: Arc::new(Mutex::new(HashSet::new())),
+    };
+    (AnalyticsEventsClient { queue: Some(queue) }, receiver)
+}
+
+#[test]
+#[cfg(debug_assertions)]
+fn analytics_destination_uses_explicit_capture_file() {
+    let capture_path = unique_capture_path("destination");
+    let destination = AnalyticsEventsDestination::from_base_url_and_capture_file(
+        "https://chatgpt.com/backend-api/".to_string(),
+        Some(capture_path.clone()),
+    );
+
+    assert_eq!(
+        destination,
+        AnalyticsEventsDestination::CaptureFile {
+            path: capture_path.clone()
+        }
+    );
+    assert_eq!(
+        fs::read_to_string(&capture_path).expect("read capture file"),
+        ""
+    );
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+
+        let mode = fs::metadata(&capture_path)
+            .expect("read capture file metadata")
+            .permissions()
+            .mode();
+        assert_eq!(mode & 0o777, 0o600);
+    }
+    fs::remove_file(capture_path).expect("remove capture file");
+}
+
+#[test]
+fn analytics_destination_uses_http_without_capture_file() {
+    let destination = AnalyticsEventsDestination::from_base_url_and_capture_file(
+        "https://chatgpt.com/backend-api/".to_string(),
+        /*capture_file*/ None,
+    );
+
+    assert_eq!(
+        destination,
+        AnalyticsEventsDestination::Http {
+            url: "https://chatgpt.com/backend-api/codex/analytics-events/events".to_string()
+        }
+    );
+}
+
+#[test]
+#[cfg(not(debug_assertions))]
+fn analytics_destination_ignores_capture_file_in_release() {
+    let destination = AnalyticsEventsDestination::from_base_url_and_capture_file(
+        "https://chatgpt.com/backend-api/".to_string(),
+        Some(std::path::PathBuf::from("ignored.jsonl")),
+    );
+
+    assert_eq!(
+        destination,
+        AnalyticsEventsDestination::Http {
+            url: "https://chatgpt.com/backend-api/codex/analytics-events/events".to_string()
+        }
+    );
+}
+
+#[tokio::test]
+#[cfg(debug_assertions)]
+async fn capture_file_writes_exact_serialized_request() {
+    let capture_path = unique_capture_path("single");
+    let destination = AnalyticsEventsDestination::CaptureFile {
+        path: capture_path.clone(),
+    };
+    let event = sample_regular_track_event("thread-1");
+    let expected_event = serde_json::to_value(&event).expect("serialize expected event");
+    let auth = codex_login::CodexAuth::create_dummy_chatgpt_auth_for_testing();
+
+    send_track_events_request(&auth, &destination, vec![event]).await;
+
+    let contents = fs::read_to_string(&capture_path).expect("read capture file");
+    let lines = contents.lines().collect::<Vec<_>>();
+    assert_eq!(lines.len(), 1);
+    let payload: serde_json::Value =
+        serde_json::from_str(lines[0]).expect("parse captured payload");
+    assert_eq!(payload, serde_json::json!({"events": [expected_event]}));
+
+    fs::remove_file(capture_path).expect("remove capture file");
+}
+
+#[tokio::test]
+#[cfg(debug_assertions)]
+async fn capture_file_writes_final_batches_as_separate_lines() {
+    let capture_path = unique_capture_path("batches");
+    let destination = AnalyticsEventsDestination::CaptureFile {
+        path: capture_path.clone(),
+    };
+    let auth = codex_login::CodexAuth::create_dummy_chatgpt_auth_for_testing();
+    let events = vec![
+        sample_regular_track_event("thread-1"),
+        sample_accepted_line_fingerprint_event("thread-2"),
+        sample_regular_track_event("thread-3"),
+    ];
+
+    for batch in track_event_request_batches(events) {
+        send_track_events_request(&auth, &destination, batch).await;
+    }
+
+    let contents = fs::read_to_string(&capture_path).expect("read capture file");
+    let payloads = contents
+        .lines()
+        .map(|line| serde_json::from_str::<serde_json::Value>(line).expect("parse capture line"))
+        .collect::<Vec<_>>();
+    assert_eq!(payloads.len(), 3);
+    assert_eq!(payloads[0]["events"][0]["skill_id"], "skill-thread-1");
+    assert_eq!(
+        payloads[1]["events"][0]["event_type"],
+        "codex_accepted_line_fingerprints"
+    );
+    assert_eq!(payloads[2]["events"][0]["skill_id"], "skill-thread-3");
+
+    fs::remove_file(capture_path).expect("remove capture file");
+}
+
+#[tokio::test]
+#[cfg(debug_assertions)]
+async fn api_key_auth_sends_only_plugin_events_to_codex_backend() {
+    let capture_path = unique_capture_path("api-key-plugin-events");
+    let destination = AnalyticsEventsDestination::CaptureFile {
+        path: capture_path.clone(),
+    };
+    let auth_manager = codex_login::AuthManager::from_auth_for_testing(
+        codex_login::CodexAuth::from_api_key("sk-test"),
+    );
+    let plugin_measurement = |thread_id: &str, plugin_id: &str| {
+        TrackEventRequest::PluginMeasurement(CodexPluginMeasurementEventRequest {
+            event_type: "codex_plugin_measurement_event",
+            event_params: CodexPluginMeasurementEventParams {
+                model_slug: None,
+                reasoning_effort: None,
+                thread_id: thread_id.to_string(),
+                turn_id: "turn-1".to_string(),
+                item_id: "item-1".to_string(),
+                originator: "codex_cli_rs".to_string(),
+                plugin_id: plugin_id.to_string(),
+                execution_id: "execution-1".to_string(),
+                operation: "security_scan".to_string(),
+                measurement_name: "findings".to_string(),
+                number_value: 1.0,
+                dimensions: None,
+            },
+        })
+    };
+
+    send_track_events(
+        &auth_manager,
+        &destination,
+        vec![
+            sample_regular_track_event("non-plugin-skill"),
+            sample_mcp_tool_call_event("non-plugin-mcp", /*plugin_id*/ None),
+            sample_plugin_used_track_event("non-plugin-used", /*plugin_id*/ None),
+            plugin_measurement("non-plugin-measurement", /*plugin_id*/ ""),
+            sample_accepted_line_fingerprint_event("other-event"),
+            TrackEventRequest::ThreadArchive(ThreadArchiveEvent {
+                event_type: "codex_thread_archive_event",
+                event_params: ThreadArchiveEventParams {
+                    thread_id: "non-plugin-thread-archive".to_string(),
+                    action: ThreadArchiveAction::Archived,
+                    occurred_at_ms: 1,
+                    app_server_client: None,
+                    runtime: None,
+                    thread_source: None,
+                    parent_thread_id: None,
+                },
+            }),
+            sample_plugin_used_track_event("plugin-used", Some("sample@test")),
+            sample_skill_track_event("plugin-skill", Some("sample@test")),
+            sample_mcp_tool_call_event("plugin-mcp", Some("sample@test")),
+            sample_artifact_operation_event("plugin-artifact"),
+            plugin_measurement("plugin-measurement", "sample@test"),
+        ],
+    )
+    .await;
+
+    let contents = fs::read_to_string(&capture_path).expect("read capture file");
+    let lines = contents.lines().collect::<Vec<_>>();
+    assert_eq!(lines.len(), 1);
+    let payload: serde_json::Value =
+        serde_json::from_str(lines[0]).expect("parse captured payload");
+    let events = payload["events"].as_array().expect("events array");
+    for event in events {
+        let event_params = event["event_params"].as_object().expect("event params");
+        for server_owned_field in [
+            "auth_mode",
+            "api_organization_id",
+            "api_project_id",
+            "api_key_tracking_id",
+        ] {
+            assert!(!event_params.contains_key(server_owned_field));
+        }
+    }
+    let delivered_events = events
+        .iter()
+        .map(|event| {
+            serde_json::json!({
+                "event_type": event["event_type"],
+                "plugin_id": event["event_params"]["plugin_id"],
+                "thread_id": event["event_params"]["thread_id"],
+            })
+        })
+        .collect::<Vec<_>>();
+    assert_eq!(
+        delivered_events,
+        vec![
+            serde_json::json!({
+                "event_type": "codex_plugin_used",
+                "plugin_id": "sample@test",
+                "thread_id": "plugin-used",
+            }),
+            serde_json::json!({
+                "event_type": "skill_invocation",
+                "plugin_id": "sample@test",
+                "thread_id": "plugin-skill",
+            }),
+            serde_json::json!({
+                "event_type": "codex_mcp_tool_call_event",
+                "plugin_id": "sample@test",
+                "thread_id": "plugin-mcp",
+            }),
+            serde_json::json!({
+                "event_type": "codex_artifact_operation",
+                "plugin_id": "presentations@openai-primary-runtime",
+                "thread_id": "plugin-artifact",
+            }),
+            serde_json::json!({
+                "event_type": "codex_plugin_measurement_event",
+                "plugin_id": "sample@test",
+                "thread_id": "plugin-measurement",
+            }),
+        ]
+    );
+
+    fs::remove_file(capture_path).expect("remove capture file");
+}
+
+#[test]
+#[cfg(debug_assertions)]
+fn capture_write_failure_still_consumes_delivery() {
+    let capture_path = unique_capture_path("missing-parent").join("events.jsonl");
+    let destination = AnalyticsEventsDestination::CaptureFile { path: capture_path };
+    let payload = crate::events::TrackEventsRequest {
+        events: vec![sample_regular_track_event("thread-1")],
+    };
+
+    assert!(capture_track_events_request(&destination, &payload));
+}
+
+fn sample_turn_start_request() -> ClientRequest {
+    ClientRequest::TurnStart {
+        request_id: RequestId::Integer(1),
+        params: TurnStartParams {
+            thread_id: "thread-1".to_string(),
+            client_user_message_id: None,
+            input: Vec::new(),
+            ..Default::default()
+        },
+    }
+}
+
+fn sample_turn_steer_request() -> ClientRequest {
+    ClientRequest::TurnSteer {
+        request_id: RequestId::Integer(2),
+        params: TurnSteerParams {
+            thread_id: "thread-1".to_string(),
+            expected_turn_id: "turn-1".to_string(),
+            client_user_message_id: None,
+            input: Vec::new(),
+            responsesapi_client_metadata: None,
+            additional_context: None,
+        },
+    }
+}
+
+fn sample_turn_interrupt_request(turn_id: &str) -> ClientRequest {
+    ClientRequest::TurnInterrupt {
+        request_id: RequestId::Integer(3),
+        params: TurnInterruptParams {
+            thread_id: "thread-1".to_string(),
+            turn_id: turn_id.to_string(),
+        },
+    }
+}
+
+fn sample_turn_interrupt_response() -> ClientResponsePayload {
+    ClientResponsePayload::TurnInterrupt(TurnInterruptResponse {})
+}
+
+fn sample_thread_archive_request() -> ClientRequest {
+    ClientRequest::ThreadArchive {
+        request_id: RequestId::Integer(3),
+        params: ThreadArchiveParams {
+            thread_id: "thread-1".to_string(),
+        },
+    }
+}
+
+fn sample_thread(thread_id: &str) -> Thread {
+    Thread {
+        originator: None,
+        environments: None,
+        id: thread_id.to_string(),
+        extra: None,
+        session_id: format!("session-{thread_id}"),
+        forked_from_id: None,
+        parent_thread_id: None,
+        preview: "first prompt".to_string(),
+        ephemeral: false,
+        section: None,
+        section_entered_at: None,
+        project_id: None,
+        daybreak_enabled: None,
+        history_mode: Default::default(),
+        model_provider: "openai".to_string(),
+        model: None,
+        reasoning_effort: None,
+        created_at: 1,
+        updated_at: 2,
+        recency_at: Some(2),
+        status: AppServerThreadStatus::Idle,
+        path: None,
+        cwd: test_path_buf("/tmp").abs(),
+        cli_version: "0.0.0".to_string(),
+        source: AppServerSessionSource::Exec,
+        can_accept_direct_input: None,
+        thread_source: None,
+        agent_nickname: None,
+        agent_role: None,
+        git_info: None,
+        name: None,
+        turns: Vec::new(),
+    }
+}
+
+fn sample_thread_start_response() -> ClientResponsePayload {
+    ClientResponsePayload::ThreadStart(ThreadStartResponse {
+        disabled_plugin_ids: Vec::new(),
+        thread: sample_thread("thread-1"),
+        model: "gpt-5".to_string(),
+        model_provider: "openai".to_string(),
+        service_tier: None,
+        cwd: test_path_buf("/tmp").abs(),
+        runtime_workspace_roots: Vec::new(),
+        instruction_sources: Vec::new(),
+        approval_policy: AppServerAskForApproval::OnRequest,
+        approvals_reviewer: AppServerApprovalsReviewer::User,
+        sandbox: AppServerSandboxPolicy::DangerFullAccess,
+        active_permission_profile: None,
+        reasoning_effort: None,
+        multi_agent_mode: Default::default(),
+    })
+}
+
+fn sample_thread_resume_response() -> ClientResponsePayload {
+    ClientResponsePayload::ThreadResume(ThreadResumeResponse {
+        disabled_plugin_ids: Vec::new(),
+        thread: sample_thread("thread-2"),
+        model: "gpt-5".to_string(),
+        model_provider: "openai".to_string(),
+        service_tier: None,
+        cwd: test_path_buf("/tmp").abs(),
+        runtime_workspace_roots: Vec::new(),
+        instruction_sources: Vec::new(),
+        approval_policy: AppServerAskForApproval::OnRequest,
+        approvals_reviewer: AppServerApprovalsReviewer::User,
+        sandbox: AppServerSandboxPolicy::DangerFullAccess,
+        active_permission_profile: None,
+        reasoning_effort: None,
+        collaboration_mode: None,
+        multi_agent_mode: Default::default(),
+        initial_turns_page: None,
+        turns_backwards_cursor: None,
+        items_backwards_cursor: None,
+    })
+}
+
+fn sample_thread_fork_response() -> ClientResponsePayload {
+    ClientResponsePayload::ThreadFork(ThreadForkResponse {
+        disabled_plugin_ids: Vec::new(),
+        thread: sample_thread("thread-3"),
+        model: "gpt-5".to_string(),
+        model_provider: "openai".to_string(),
+        service_tier: None,
+        cwd: test_path_buf("/tmp").abs(),
+        runtime_workspace_roots: Vec::new(),
+        instruction_sources: Vec::new(),
+        approval_policy: AppServerAskForApproval::OnRequest,
+        approvals_reviewer: AppServerApprovalsReviewer::User,
+        sandbox: AppServerSandboxPolicy::DangerFullAccess,
+        active_permission_profile: None,
+        reasoning_effort: None,
+        multi_agent_mode: Default::default(),
+    })
+}
+
+fn sample_turn_start_response() -> ClientResponsePayload {
+    ClientResponsePayload::TurnStart(TurnStartResponse {
+        turn: Turn {
+            id: "turn-1".to_string(),
+            items_view: codex_app_server_protocol::TurnItemsView::Full,
+            items: Vec::new(),
+            status: AppServerTurnStatus::InProgress,
+            error: None,
+            started_at: None,
+            completed_at: None,
+            duration_ms: None,
+        },
+    })
+}
+
+fn sample_turn_steer_response() -> ClientResponsePayload {
+    ClientResponsePayload::TurnSteer(TurnSteerResponse {
+        turn_id: "turn-2".to_string(),
+    })
+}
+
+#[test]
+fn track_plugin_measurements_rejects_unbounded_inputs_before_queueing() {
+    let (client, mut receiver) = client_with_receiver();
+    let measurements = |row_count| PluginMeasurementsInput {
+        thread_id: "thread-1".to_string(),
+        turn_id: "turn-1".to_string(),
+        item_id: "item-1".to_string(),
+        originator: "codex_cli_rs".to_string(),
+        model_slug: None,
+        reasoning_effort: None,
+        plugin_id: "sample@openai-curated".to_string(),
+        execution_id: "execution-1".to_string(),
+        operation: "security_scan".to_string(),
+        rows: vec![
+            PluginMeasurementRow {
+                measurement_name: "finding_count".to_string(),
+                number_value: 1.0,
+                dimensions: BTreeMap::new(),
+            };
+            row_count
+        ],
+    };
+
+    client.track_plugin_measurements(measurements(MAX_PLUGIN_MEASUREMENTS_PER_BATCH + 1));
+    assert!(matches!(receiver.try_recv(), Err(TryRecvError::Empty)));
+
+    let mut oversized_operation = measurements(1);
+    oversized_operation.operation = "o".repeat(65);
+    client.track_plugin_measurements(oversized_operation);
+    assert!(matches!(receiver.try_recv(), Err(TryRecvError::Empty)));
+
+    let mut mixed_rows = measurements(4);
+    mixed_rows.rows[0].measurement_name = "m".repeat(65);
+    mixed_rows.rows[1]
+        .dimensions
+        .insert("d".repeat(65), "valid".to_string());
+    mixed_rows.rows[2]
+        .dimensions
+        .insert("valid".to_string(), "v".repeat(65));
+    client.track_plugin_measurements(mixed_rows);
+    assert!(matches!(
+        receiver.try_recv(),
+        Ok(AnalyticsEventsQueueMessage::Fact(fact))
+            if matches!(
+                fact.as_ref(),
+                AnalyticsFact::Custom(CustomAnalyticsFact::PluginMeasurements(input))
+                    if input.rows.len() == 1
+                        && input.rows[0].measurement_name == "finding_count"
+            )
+    ));
+
+    client.track_plugin_measurements(measurements(MAX_PLUGIN_MEASUREMENTS_PER_BATCH));
+    assert!(matches!(
+        receiver.try_recv(),
+        Ok(AnalyticsEventsQueueMessage::Fact(fact))
+            if matches!(
+                fact.as_ref(),
+                AnalyticsFact::Custom(CustomAnalyticsFact::PluginMeasurements(input))
+                    if input.rows.len() == MAX_PLUGIN_MEASUREMENTS_PER_BATCH
+            )
+    ));
+}
+
+#[test]
+fn track_request_only_enqueues_analytics_relevant_requests() {
+    let (client, mut receiver) = client_with_receiver();
+
+    for (request_id, request) in [
+        (RequestId::Integer(1), sample_turn_start_request()),
+        (RequestId::Integer(2), sample_turn_steer_request()),
+    ] {
+        client.track_request(/*connection_id*/ 7, request_id, &request);
+        assert!(matches!(
+            receiver.try_recv(),
+            Ok(AnalyticsEventsQueueMessage::Fact(input))
+                if matches!(*input, AnalyticsFact::ClientRequest { .. })
+        ));
+    }
+
+    client.track_request(
+        /*connection_id*/ 7,
+        RequestId::Integer(3),
+        &sample_turn_interrupt_request("turn-1"),
+    );
+    assert!(matches!(
+        receiver.try_recv(),
+        Ok(AnalyticsEventsQueueMessage::Fact(input))
+            if matches!(
+                *input,
+                AnalyticsFact::ExplicitClientInterruptRequest {
+                    ref turn_id,
+                    requested_at_ms,
+                    ..
+                } if turn_id == "turn-1" && requested_at_ms > 0
+            )
+    ));
+
+    let ignored_request = sample_thread_archive_request();
+    client.track_request(
+        /*connection_id*/ 7,
+        RequestId::Integer(3),
+        &ignored_request,
+    );
+    assert!(matches!(receiver.try_recv(), Err(TryRecvError::Empty)));
+
+    client.track_request(
+        /*connection_id*/ 7,
+        RequestId::Integer(4),
+        &sample_turn_interrupt_request(""),
+    );
+    assert!(matches!(receiver.try_recv(), Err(TryRecvError::Empty)));
+}
+
+#[test]
+fn track_response_only_enqueues_analytics_relevant_responses() {
+    let (client, mut receiver) = client_with_receiver();
+
+    for (request_id, response) in [
+        (RequestId::Integer(1), sample_thread_start_response()),
+        (RequestId::Integer(2), sample_thread_resume_response()),
+        (RequestId::Integer(3), sample_thread_fork_response()),
+        (RequestId::Integer(4), sample_turn_start_response()),
+        (RequestId::Integer(5), sample_turn_steer_response()),
+        (RequestId::Integer(6), sample_turn_interrupt_response()),
+    ] {
+        client.track_response(/*connection_id*/ 7, request_id, &response);
+        assert!(matches!(
+            receiver.try_recv(),
+            Ok(AnalyticsEventsQueueMessage::Fact(input))
+                if matches!(*input, AnalyticsFact::ClientResponse { .. })
+        ));
+    }
+
+    client.track_response(
+        /*connection_id*/ 7,
+        RequestId::Integer(7),
+        &ClientResponsePayload::ThreadArchive(ThreadArchiveResponse {}),
+    );
+    assert!(matches!(receiver.try_recv(), Err(TryRecvError::Empty)));
+}
+
+#[cfg(unix)]
+#[test]
+fn track_response_ignores_unserializable_thread_responses() {
+    use std::ffi::OsString;
+    use std::os::unix::ffi::OsStringExt;
+
+    let (client, mut receiver) = client_with_receiver();
+    let mut response = sample_thread_start_response();
+    let ClientResponsePayload::ThreadStart(thread_start) = &mut response else {
+        panic!("expected thread/start response");
+    };
+    thread_start.cwd = codex_utils_absolute_path::AbsolutePathBuf::from_absolute_path(
+        std::path::PathBuf::from(OsString::from_vec(vec![b'/', b'b', b'a', b'd', 0xff])),
+    )
+    .expect("non-UTF-8 Unix paths are valid absolute paths");
+
+    client.track_response(/*connection_id*/ 7, RequestId::Integer(1), &response);
+
+    assert!(matches!(receiver.try_recv(), Err(TryRecvError::Empty)));
+}
+
+#[tokio::test]
+async fn flush_waits_for_preceding_fact_delivery() {
+    let (client, mut receiver) = client_with_receiver();
+    client.track_request(
+        /*connection_id*/ 7,
+        RequestId::Integer(1),
+        &sample_turn_start_request(),
+    );
+
+    let flush = tokio::spawn(async move { client.flush().await });
+    assert!(matches!(
+        receiver.recv().await,
+        Some(AnalyticsEventsQueueMessage::Fact(input))
+            if matches!(*input, AnalyticsFact::ClientRequest { .. })
+    ));
+    let done_tx = match receiver.recv().await {
+        Some(AnalyticsEventsQueueMessage::Flush(done_tx)) => done_tx,
+        _ => panic!("expected analytics flush barrier"),
+    };
+    tokio::time::sleep(std::time::Duration::from_millis(25)).await;
+    assert!(!flush.is_finished());
+    done_tx.send(()).expect("flush receiver should remain open");
+    flush.await.expect("flush task should complete");
+}
+
+#[tokio::test]
+async fn flush_is_noop_when_analytics_is_disabled() {
+    let client = AnalyticsEventsClient::new(
+        codex_login::AuthManager::from_auth_for_testing(
+            codex_login::CodexAuth::create_dummy_chatgpt_auth_for_testing(),
+        ),
+        "https://chatgpt.com/backend-api".to_string(),
+        /*analytics_enabled*/ Some(false),
+    );
+    client.track_notification(&ServerNotification::ThreadArchived(
+        ThreadArchivedNotification {
+            thread_id: "thread-1".to_string(),
+        },
+    ));
+    assert!(client.queue.is_none());
+    client.flush().await;
+}
+
+#[test]
+fn app_used_preserves_first_classification_and_emits_again_next_turn() {
+    let (client, mut receiver) = client_with_receiver();
+    let tracking = TrackEventsContext {
+        model_slug: "gpt-5".to_string(),
+        thread_id: "thread-1".to_string(),
+        turn_id: "turn-1".to_string(),
+        product_client_id: "codex_desktop".to_string(),
+    };
+    for (turn_id, elicitation_type) in [
+        ("turn-1", Some(ElicitationType::AuthOrLink)),
+        ("turn-1", None),
+        ("turn-2", None),
+    ] {
+        client.track_app_used(
+            TrackEventsContext {
+                turn_id: turn_id.to_string(),
+                ..tracking.clone()
+            },
+            AppInvocation {
+                connector_id: Some("calendar".to_string()),
+                app_name: Some("Calendar".to_string()),
+                invocation_type: Some(InvocationType::Implicit),
+            },
+            elicitation_type,
+        );
+    }
+    for (turn_id, elicitation_type) in [
+        ("turn-1", Some(ElicitationType::AuthOrLink)),
+        ("turn-2", None),
+    ] {
+        let Ok(AnalyticsEventsQueueMessage::Fact(input)) = receiver.try_recv() else {
+            panic!("expected app-used analytics fact");
+        };
+        let AnalyticsFact::Custom(CustomAnalyticsFact::AppUsed(input)) = *input else {
+            panic!("expected app-used analytics fact");
+        };
+        assert_eq!(
+            (
+                input.tracking.turn_id.as_str(),
+                input.app.connector_id.as_deref(),
+                input.elicitation_type,
+            ),
+            (turn_id, Some("calendar"), elicitation_type)
+        );
+    }
+    assert!(matches!(receiver.try_recv(), Err(TryRecvError::Empty)));
+}
+
+#[test]
+fn track_notification_only_enqueues_analytics_relevant_notifications() {
+    let (client, mut receiver) = client_with_receiver();
+    let tracked_payload = TurnDiffUpdatedNotification {
+        thread_id: "thread-1".to_string(),
+        turn_id: "turn-1".to_string(),
+        diff: "diff".to_string(),
+    };
+    let tracked_notification = ServerNotification::TurnDiffUpdated(tracked_payload.clone());
+
+    client.track_notification(&tracked_notification);
+
+    let Ok(AnalyticsEventsQueueMessage::Fact(input)) = receiver.try_recv() else {
+        panic!("expected analytics notification");
+    };
+    let AnalyticsFact::Notification(notification) = *input else {
+        panic!("expected analytics notification fact");
+    };
+    let ServerNotification::TurnDiffUpdated(notification) = *notification else {
+        panic!("expected turn diff notification");
+    };
+    assert_eq!(notification, tracked_payload);
+
+    let ignored_notification =
+        ServerNotification::CommandExecutionOutputDelta(CommandExecutionOutputDeltaNotification {
+            thread_id: "thread-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            item_id: "item-1".to_string(),
+            delta: "output".to_string(),
+        });
+
+    client.track_notification(&ignored_notification);
+    assert!(matches!(receiver.try_recv(), Err(TryRecvError::Empty)));
+}
+
+#[test]
+fn track_event_request_batches_only_isolates_accepted_line_fingerprint_events() {
+    let batches = track_event_request_batches(vec![
+        sample_regular_track_event("thread-1"),
+        sample_regular_track_event("thread-2"),
+        sample_accepted_line_fingerprint_event("thread-3"),
+        sample_accepted_line_fingerprint_event("thread-4"),
+        sample_regular_track_event("thread-5"),
+        sample_regular_track_event("thread-6"),
+    ]);
+
+    assert_eq!(batches.len(), 4);
+    assert_eq!(batches[0].len(), 2);
+    assert_eq!(batches[1].len(), 1);
+    assert_eq!(batches[2].len(), 1);
+    assert_eq!(batches[3].len(), 2);
+    assert!(batches[1][0].should_send_in_isolated_request());
+    assert!(batches[2][0].should_send_in_isolated_request());
+}

codex-rs/analytics/src/events.rs

@@ -0,0 +1,1542 @@
+use std::time::Instant;
+
+use crate::facts::AppInvocation;
+use crate::facts::ArtifactOperation;
+use crate::facts::ArtifactOperationLifecycle;
+use crate::facts::CodexCompactionEvent;
+use crate::facts::CodexErrKind;
+use crate::facts::CodexGoalEvent;
+use crate::facts::CompactionImplementation;
+use crate::facts::CompactionPhase;
+use crate::facts::CompactionReason;
+use crate::facts::CompactionStatus;
+use crate::facts::CompactionStrategy;
+use crate::facts::CompactionTrigger;
+use crate::facts::ElicitationType;
+use crate::facts::GoalEventKind;
+use crate::facts::HookRunFact;
+use crate::facts::ImagePreparationMetadata;
+use crate::facts::InvocationType;
+use crate::facts::PluginInstallRequested;
+use crate::facts::PluginState;
+use crate::facts::SubAgentThreadStartedInput;
+use crate::facts::ThreadInitializationMode;
+use crate::facts::TrackEventsContext;
+use crate::facts::TurnStatus;
+use crate::facts::TurnSteerRejectionReason;
+use crate::facts::TurnSteerResult;
+use crate::facts::TurnSubmissionType;
+use crate::guardian_v2::GuardianV2EventRequest;
+use crate::now_unix_millis;
+use codex_app_server_protocol::CodexErrorInfo;
+use codex_app_server_protocol::CommandExecutionSource;
+use codex_login::default_client::originator;
+use codex_plugin::PluginId;
+use codex_plugin::PluginTelemetryMetadata;
+use codex_protocol::approvals::NetworkApprovalProtocol;
+use codex_protocol::models::AdditionalPermissionProfile;
+use codex_protocol::models::SandboxPermissions;
+use codex_protocol::protocol::GuardianAssessmentOutcome;
+use codex_protocol::protocol::GuardianCommandSource;
+use codex_protocol::protocol::GuardianRiskLevel;
+use codex_protocol::protocol::GuardianUserAuthorization;
+use codex_protocol::protocol::HookEventName;
+use codex_protocol::protocol::HookExecutionMode;
+use codex_protocol::protocol::HookHandlerType;
+use codex_protocol::protocol::HookRunStatus;
+use codex_protocol::protocol::HookSource;
+use codex_protocol::protocol::SubAgentSource;
+use codex_protocol::protocol::ThreadSource;
+use codex_protocol::protocol::TokenUsage;
+use serde::Serialize;
+use std::collections::BTreeMap;
+
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum AppServerRpcTransport {
+    Stdio,
+    Websocket,
+    InProcess,
+}
+
+#[derive(Serialize)]
+pub(crate) struct TrackEventsRequest {
+    pub(crate) events: Vec<TrackEventRequest>,
+}
+
+#[derive(Serialize)]
+#[serde(untagged)]
+pub(crate) enum TrackEventRequest {
+    SkillInvocation(SkillInvocationEventRequest),
+    ThreadInitialized(ThreadInitializedEvent),
+    ThreadArchive(ThreadArchiveEvent),
+    GuardianReview(Box<GuardianReviewEventRequest>),
+    GuardianV2(Box<GuardianV2EventRequest>),
+    AppMentioned(CodexAppMentionedEventRequest),
+    AppUsed(CodexAppUsedEventRequest),
+    HookRun(CodexHookRunEventRequest),
+    Compaction(Box<CodexCompactionEventRequest>),
+    Goal(Box<CodexGoalEventRequest>),
+    ThreadHintStatus(Box<crate::thread_hint::ThreadHintStatusEventRequest>),
+    TurnEvent(Box<CodexTurnEventRequest>),
+    TurnSteer(CodexTurnSteerEventRequest),
+    ArtifactOperation(CodexArtifactOperationEventRequest),
+    CommandExecution(CodexCommandExecutionEventRequest),
+    PluginMeasurement(CodexPluginMeasurementEventRequest),
+    FileChange(CodexFileChangeEventRequest),
+    McpToolCall(CodexMcpToolCallEventRequest),
+    DynamicToolCall(CodexDynamicToolCallEventRequest),
+    ControlToolCall(CodexControlToolCallEventRequest),
+    CollabAgentToolCall(CodexCollabAgentToolCallEventRequest),
+    WebSearch(CodexWebSearchEventRequest),
+    ImageGeneration(CodexImageGenerationEventRequest),
+    AcceptedLineFingerprints(Box<CodexAcceptedLineFingerprintsEventRequest>),
+    #[allow(dead_code)]
+    ReviewEvent(CodexReviewEventRequest),
+    PluginUsed(CodexPluginUsedEventRequest),
+    PluginInstallRequested(CodexPluginInstallRequestedEventRequest),
+    PluginInstalled(CodexPluginEventRequest),
+    PluginUninstalled(CodexPluginEventRequest),
+    PluginEnabled(CodexPluginEventRequest),
+    PluginDisabled(CodexPluginEventRequest),
+    PluginInstallFailed(CodexPluginInstallFailedEventRequest),
+    ExternalAgentConfigImportCompleted(CodexOnboardingExternalAgentImportCompleteEventRequest),
+    ExternalAgentConfigImportFailure(CodexOnboardingExternalAgentImportFailureEventRequest),
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexArtifactOperationEventParams {
+    pub(crate) thread_id: String,
+    pub(crate) turn_id: String,
+    pub(crate) item_id: String,
+    pub(crate) lifecycle: ArtifactOperationLifecycle,
+    pub(crate) occurred_at_ms: u64,
+    pub(crate) product_client_id: String,
+    pub(crate) runtime: CodexRuntimeMetadata,
+    pub(crate) model_slug: String,
+    pub(crate) plugin_id: String,
+    pub(crate) script_path: String,
+    pub(crate) skill: String,
+    pub(crate) artifact_type: String,
+    pub(crate) operation_kind: String,
+    pub(crate) expected_output_count: u32,
+    pub(crate) output_format: String,
+    pub(crate) execution_backend: String,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexArtifactOperationEventRequest {
+    pub(crate) event_type: &'static str,
+    pub(crate) event_params: CodexArtifactOperationEventParams,
+}
+
+pub(crate) fn codex_artifact_operation_event_request(
+    tracking: TrackEventsContext,
+    operation: ArtifactOperation,
+) -> CodexArtifactOperationEventRequest {
+    CodexArtifactOperationEventRequest {
+        event_type: "codex_artifact_operation",
+        event_params: CodexArtifactOperationEventParams {
+            thread_id: tracking.thread_id,
+            turn_id: tracking.turn_id,
+            item_id: operation.item_id,
+            lifecycle: operation.lifecycle,
+            occurred_at_ms: operation.occurred_at_ms,
+            product_client_id: tracking.product_client_id,
+            runtime: current_runtime_metadata(),
+            model_slug: tracking.model_slug,
+            plugin_id: operation.plugin_id,
+            script_path: operation.script_path,
+            skill: operation.skill,
+            artifact_type: operation.artifact_type,
+            operation_kind: operation.operation_kind,
+            expected_output_count: operation.expected_output_count,
+            output_format: operation.output_format,
+            execution_backend: operation.execution_backend,
+        },
+    }
+}
+
+impl TrackEventRequest {
+    pub(crate) fn should_send_in_isolated_request(&self) -> bool {
+        matches!(self, Self::AcceptedLineFingerprints(_))
+    }
+
+    pub(crate) fn can_send_with_api_key_auth(&self) -> bool {
+        match self {
+            Self::PluginUsed(event) => event.event_params.plugin.plugin_id.is_some(),
+            Self::SkillInvocation(event) => event.event_params.plugin_id.is_some(),
+            Self::McpToolCall(event) => event.event_params.plugin_id.is_some(),
+            Self::ArtifactOperation(event) => !event.event_params.plugin_id.is_empty(),
+            Self::PluginMeasurement(event) => !event.event_params.plugin_id.is_empty(),
+            _ => false,
+        }
+    }
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexAcceptedLineFingerprintsEventParams {
+    pub(crate) event_type: &'static str,
+    pub(crate) turn_id: String,
+    pub(crate) thread_id: String,
+    pub(crate) product_surface: Option<String>,
+    pub(crate) model_slug: Option<String>,
+    pub(crate) completed_at: u64,
+    pub(crate) repo_hash: Option<String>,
+    pub(crate) accepted_added_lines: u64,
+    pub(crate) accepted_deleted_lines: u64,
+    // Analytics ingestion and warehouse schemas require this field on the wire.
+    // Keep it statically empty; line fingerprints are no longer generated.
+    pub(crate) line_fingerprints: [(); 0],
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexAcceptedLineFingerprintsEventRequest {
+    pub(crate) event_type: &'static str,
+    pub(crate) event_params: CodexAcceptedLineFingerprintsEventParams,
+}
+
+#[derive(Serialize)]
+pub(crate) struct SkillInvocationEventRequest {
+    pub(crate) event_type: &'static str,
+    pub(crate) skill_id: String,
+    pub(crate) skill_name: String,
+    pub(crate) event_params: SkillInvocationEventParams,
+}
+
+#[derive(Serialize)]
+pub(crate) struct SkillInvocationEventParams {
+    pub(crate) product_client_id: Option<String>,
+    pub(crate) skill_scope: Option<String>,
+    pub(crate) plugin_id: Option<String>,
+    pub(crate) remote_plugin_id: Option<String>,
+    pub(crate) thread_id: Option<String>,
+    pub(crate) turn_id: Option<String>,
+    pub(crate) invoke_type: Option<InvocationType>,
+    pub(crate) model_slug: Option<String>,
+}
+
+#[derive(Clone, Serialize)]
+pub(crate) struct CodexAppServerClientMetadata {
+    pub(crate) product_client_id: String,
+    pub(crate) client_name: Option<String>,
+    pub(crate) client_version: Option<String>,
+    pub(crate) rpc_transport: AppServerRpcTransport,
+    pub(crate) experimental_api_enabled: Option<bool>,
+}
+
+#[derive(Clone, Serialize)]
+pub(crate) struct CodexRuntimeMetadata {
+    pub(crate) codex_rs_version: String,
+    pub(crate) runtime_os: String,
+    pub(crate) runtime_os_version: String,
+    pub(crate) runtime_arch: String,
+}
+
+#[derive(Serialize)]
+pub(crate) struct ThreadInitializedEventParams {
+    pub(crate) thread_id: String,
+    pub(crate) session_id: String,
+    pub(crate) app_server_client: CodexAppServerClientMetadata,
+    pub(crate) runtime: CodexRuntimeMetadata,
+    pub(crate) model: String,
+    pub(crate) ephemeral: bool,
+    /// Whether the thread's checkout is a validated linked Git worktree, if known.
+    pub(crate) is_worktree: Option<bool>,
+    pub(crate) thread_source: Option<ThreadSource>,
+    pub(crate) initialization_mode: ThreadInitializationMode,
+    pub(crate) subagent_source: Option<String>,
+    pub(crate) parent_thread_id: Option<String>,
+    pub(crate) forked_from_thread_id: Option<String>,
+    pub(crate) created_at: u64,
+}
+
+#[derive(Serialize)]
+pub(crate) struct ThreadInitializedEvent {
+    pub(crate) event_type: &'static str,
+    pub(crate) event_params: ThreadInitializedEventParams,
+}
+
+#[derive(Clone, Copy, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum ThreadArchiveAction {
+    Archived,
+    Unarchived,
+}
+
+#[derive(Serialize)]
+pub(crate) struct ThreadArchiveEventParams {
+    pub(crate) thread_id: String,
+    pub(crate) action: ThreadArchiveAction,
+    pub(crate) occurred_at_ms: u64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(crate) app_server_client: Option<CodexAppServerClientMetadata>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(crate) runtime: Option<CodexRuntimeMetadata>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(crate) thread_source: Option<ThreadSource>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(crate) parent_thread_id: Option<String>,
+}
+
+#[derive(Serialize)]
+pub(crate) struct ThreadArchiveEvent {
+    pub(crate) event_type: &'static str,
+    pub(crate) event_params: ThreadArchiveEventParams,
+}
+
+#[derive(Serialize)]
+pub(crate) struct GuardianReviewEventRequest {
+    pub(crate) event_type: &'static str,
+    pub(crate) event_params: GuardianReviewEventPayload,
+}
+
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum GuardianReviewDecision {
+    Approved,
+    Denied,
+    Aborted,
+}
+
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum GuardianReviewTerminalStatus {
+    Approved,
+    Denied,
+    Aborted,
+    TimedOut,
+    FailedClosed,
+}
+
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum GuardianReviewFailureReason {
+    Timeout,
+    Cancelled,
+    PromptBuildError,
+    SessionError,
+    ParseError,
+}
+
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum GuardianReviewSessionKind {
+    TrunkNew,
+    TrunkReused,
+    EphemeralForked,
+}
+
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum GuardianApprovalRequestSource {
+    /// Approval requested directly by the main Codex turn.
+    MainTurn,
+    /// Approval requested by a delegated subagent and routed through the parent
+    /// session for guardian review.
+    DelegatedSubagent,
+}
+
+/// Path-free permission metadata for a Guardian reviewed action.
+#[derive(Clone, Debug, Serialize)]
+pub struct GuardianAdditionalPermissions {
+    network: Option<GuardianNetworkPermissions>,
+}
+
+#[derive(Clone, Debug, Serialize)]
+struct GuardianNetworkPermissions {
+    enabled: Option<bool>,
+}
+
+impl From<&AdditionalPermissionProfile> for GuardianAdditionalPermissions {
+    fn from(permissions: &AdditionalPermissionProfile) -> Self {
+        Self {
+            network: permissions
+                .network
+                .as_ref()
+                .map(|network| GuardianNetworkPermissions {
+                    enabled: network.enabled,
+                }),
+        }
+    }
+}
+
+#[derive(Clone, Debug, Serialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum GuardianReviewedAction {
+    Shell {
+        sandbox_permissions: SandboxPermissions,
+        additional_permissions: Option<GuardianAdditionalPermissions>,
+    },
+    UnifiedExec {
+        sandbox_permissions: SandboxPermissions,
+        additional_permissions: Option<GuardianAdditionalPermissions>,
+        tty: bool,
+    },
+    WriteStdin {
+        tty: bool,
+    },
+    Execve {
+        source: GuardianCommandSource,
+        additional_permissions: Option<GuardianAdditionalPermissions>,
+    },
+    ApplyPatch {},
+    NetworkAccess {
+        protocol: NetworkApprovalProtocol,
+        port: u16,
+    },
+    McpToolCall {
+        server: String,
+        tool_name: String,
+        connector_id: Option<String>,
+        connector_name: Option<String>,
+        tool_title: Option<String>,
+    },
+    RequestPermissions {},
+}
+
+#[derive(Clone, Serialize)]
+pub struct GuardianReviewEventParams {
+    pub thread_id: String,
+    pub turn_id: String,
+    pub review_id: String,
+    pub target_item_id: Option<String>,
+    pub approval_request_source: GuardianApprovalRequestSource,
+    pub reviewed_action: GuardianReviewedAction,
+    pub reviewed_action_truncated: bool,
+    pub decision: GuardianReviewDecision,
+    pub terminal_status: GuardianReviewTerminalStatus,
+    pub failure_reason: Option<GuardianReviewFailureReason>,
+    pub attempt_count: i64,
+    pub risk_level: Option<GuardianRiskLevel>,
+    pub user_authorization: Option<GuardianUserAuthorization>,
+    pub outcome: Option<GuardianAssessmentOutcome>,
+    pub guardian_thread_id: Option<String>,
+    pub guardian_session_kind: Option<GuardianReviewSessionKind>,
+    pub guardian_model: Option<String>,
+    pub guardian_reasoning_effort: Option<String>,
+    pub guardian_default_review_model_id: Option<String>,
+    pub guardian_catalog_contains_auto_review: Option<bool>,
+    pub guardian_review_model_overridden: Option<bool>,
+    pub guardian_review_model_override: Option<String>,
+    pub guardian_model_provider_id: Option<String>,
+    pub had_prior_review_context: Option<bool>,
+    pub review_timeout_ms: u64,
+    pub tool_call_count: Option<u64>,
+    pub time_to_first_token_ms: Option<u64>,
+    pub completion_latency_ms: Option<u64>,
+    pub started_at: u64,
+    pub completed_at: Option<u64>,
+    pub input_tokens: Option<i64>,
+    pub cached_input_tokens: Option<i64>,
+    pub cache_write_input_tokens: Option<i64>,
+    pub output_tokens: Option<i64>,
+    pub reasoning_output_tokens: Option<i64>,
+    pub total_tokens: Option<i64>,
+}
+
+pub struct GuardianReviewTrackContext {
+    thread_id: String,
+    turn_id: String,
+    review_id: String,
+    target_item_id: Option<String>,
+    approval_request_source: GuardianApprovalRequestSource,
+    reviewed_action: GuardianReviewedAction,
+    review_timeout_ms: u64,
+    pub started_at_ms: u64,
+    started_instant: Instant,
+}
+
+impl GuardianReviewTrackContext {
+    pub fn new(
+        thread_id: String,
+        turn_id: String,
+        review_id: String,
+        target_item_id: Option<String>,
+        approval_request_source: GuardianApprovalRequestSource,
+        reviewed_action: GuardianReviewedAction,
+        review_timeout_ms: u64,
+    ) -> Self {
+        Self {
+            thread_id,
+            turn_id,
+            review_id,
+            target_item_id,
+            approval_request_source,
+            reviewed_action,
+            review_timeout_ms,
+            started_at_ms: now_unix_millis(),
+            started_instant: Instant::now(),
+        }
+    }
+
+    pub(crate) fn event_params(
+        &self,
+        result: GuardianReviewAnalyticsResult,
+        completed_at_ms: u64,
+    ) -> GuardianReviewEventParams {
+        GuardianReviewEventParams {
+            thread_id: self.thread_id.clone(),
+            turn_id: self.turn_id.clone(),
+            review_id: self.review_id.clone(),
+            target_item_id: self.target_item_id.clone(),
+            approval_request_source: self.approval_request_source,
+            reviewed_action: self.reviewed_action.clone(),
+            reviewed_action_truncated: result.reviewed_action_truncated,
+            decision: result.decision,
+            terminal_status: result.terminal_status,
+            failure_reason: result.failure_reason,
+            attempt_count: result.attempt_count,
+            risk_level: result.risk_level,
+            user_authorization: result.user_authorization,
+            outcome: result.outcome,
+            guardian_thread_id: result.guardian_thread_id,
+            guardian_session_kind: result.guardian_session_kind,
+            guardian_model: result.guardian_model,
+            guardian_reasoning_effort: result.guardian_reasoning_effort,
+            guardian_default_review_model_id: result.guardian_default_review_model_id,
+            guardian_catalog_contains_auto_review: result.guardian_catalog_contains_auto_review,
+            guardian_review_model_overridden: result.guardian_review_model_overridden,
+            guardian_review_model_override: result.guardian_review_model_override,
+            guardian_model_provider_id: result.guardian_model_provider_id,
+            had_prior_review_context: result.had_prior_review_context,
+            review_timeout_ms: self.review_timeout_ms,
+            // TODO(rhan-oai): plumb nested Guardian review session tool-call counts.
+            tool_call_count: None,
+            time_to_first_token_ms: result.time_to_first_token_ms,
+            completion_latency_ms: Some(self.started_instant.elapsed().as_millis() as u64),
+            started_at: self.started_at_ms / 1_000,
+            completed_at: Some(completed_at_ms / 1_000),
+            input_tokens: result.token_usage.as_ref().map(|usage| usage.input_tokens),
+            cached_input_tokens: result
+                .token_usage
+                .as_ref()
+                .map(|usage| usage.cached_input_tokens),
+            cache_write_input_tokens: result
+                .token_usage
+                .as_ref()
+                .map(|usage| usage.cache_write_input_tokens),
+            output_tokens: result.token_usage.as_ref().map(|usage| usage.output_tokens),
+            reasoning_output_tokens: result
+                .token_usage
+                .as_ref()
+                .map(|usage| usage.reasoning_output_tokens),
+            total_tokens: result.token_usage.as_ref().map(|usage| usage.total_tokens),
+        }
+    }
+}
+
+#[derive(Debug)]
+pub struct GuardianReviewAnalyticsResult {
+    pub decision: GuardianReviewDecision,
+    pub terminal_status: GuardianReviewTerminalStatus,
+    pub failure_reason: Option<GuardianReviewFailureReason>,
+    pub attempt_count: i64,
+    pub risk_level: Option<GuardianRiskLevel>,
+    pub user_authorization: Option<GuardianUserAuthorization>,
+    pub outcome: Option<GuardianAssessmentOutcome>,
+    pub guardian_thread_id: Option<String>,
+    pub guardian_session_kind: Option<GuardianReviewSessionKind>,
+    pub guardian_model: Option<String>,
+    pub guardian_reasoning_effort: Option<String>,
+    pub guardian_default_review_model_id: Option<String>,
+    pub guardian_catalog_contains_auto_review: Option<bool>,
+    pub guardian_review_model_overridden: Option<bool>,
+    pub guardian_review_model_override: Option<String>,
+    pub guardian_model_provider_id: Option<String>,
+    pub had_prior_review_context: Option<bool>,
+    pub reviewed_action_truncated: bool,
+    pub token_usage: Option<TokenUsage>,
+    pub time_to_first_token_ms: Option<u64>,
+}
+
+impl GuardianReviewAnalyticsResult {
+    pub fn without_session() -> Self {
+        Self {
+            decision: GuardianReviewDecision::Denied,
+            terminal_status: GuardianReviewTerminalStatus::FailedClosed,
+            failure_reason: None,
+            attempt_count: 1,
+            risk_level: None,
+            user_authorization: None,
+            outcome: None,
+            guardian_thread_id: None,
+            guardian_session_kind: None,
+            guardian_model: None,
+            guardian_reasoning_effort: None,
+            guardian_default_review_model_id: None,
+            guardian_catalog_contains_auto_review: None,
+            guardian_review_model_overridden: None,
+            guardian_review_model_override: None,
+            guardian_model_provider_id: None,
+            had_prior_review_context: None,
+            reviewed_action_truncated: false,
+            token_usage: None,
+            time_to_first_token_ms: None,
+        }
+    }
+
+    pub fn from_session(params: GuardianReviewSessionAnalyticsParams) -> Self {
+        Self {
+            guardian_thread_id: Some(params.guardian_thread_id),
+            guardian_session_kind: Some(params.guardian_session_kind),
+            guardian_model: Some(params.guardian_model),
+            guardian_reasoning_effort: params.guardian_reasoning_effort,
+            guardian_default_review_model_id: Some(params.guardian_default_review_model_id),
+            guardian_catalog_contains_auto_review: Some(
+                params.guardian_catalog_contains_auto_review,
+            ),
+            guardian_review_model_overridden: Some(params.guardian_review_model_overridden),
+            guardian_review_model_override: params.guardian_review_model_override,
+            guardian_model_provider_id: Some(params.guardian_model_provider_id),
+            had_prior_review_context: Some(params.had_prior_review_context),
+            ..Self::without_session()
+        }
+    }
+}
+
+pub struct GuardianReviewSessionAnalyticsParams {
+    pub guardian_thread_id: String,
+    pub guardian_session_kind: GuardianReviewSessionKind,
+    pub guardian_model: String,
+    pub guardian_reasoning_effort: Option<String>,
+    pub guardian_default_review_model_id: String,
+    pub guardian_catalog_contains_auto_review: bool,
+    pub guardian_review_model_overridden: bool,
+    pub guardian_review_model_override: Option<String>,
+    pub guardian_model_provider_id: String,
+    pub had_prior_review_context: bool,
+}
+
+#[derive(Serialize)]
+pub(crate) struct GuardianReviewEventPayload {
+    pub(crate) session_id: String,
+    pub(crate) app_server_client: CodexAppServerClientMetadata,
+    pub(crate) runtime: CodexRuntimeMetadata,
+    #[serde(flatten)]
+    pub(crate) guardian_review: GuardianReviewEventParams,
+}
+
+#[allow(dead_code)]
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum FinalApprovalOutcome {
+    Unknown,
+    NotNeeded,
+    ConfigAllowed,
+    PolicyForbidden,
+    GuardianApproved,
+    GuardianDenied,
+    GuardianAborted,
+    UserApproved,
+    UserApprovedForSession,
+    UserDenied,
+    UserAborted,
+}
+
+#[allow(dead_code)]
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum ToolItemTerminalStatus {
+    Completed,
+    Failed,
+    Rejected,
+    Interrupted,
+}
+
+#[allow(dead_code)]
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum ToolItemFailureKind {
+    ToolError,
+    ApprovalDenied,
+    ApprovalAborted,
+    SandboxDenied,
+    PolicyForbidden,
+}
+
+/// The immediate initiator of the tool request associated with an analytics event.
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum ToolEventType {
+    /// The event item ID matches a tool call emitted in a sampled model response.
+    ModelToolCall,
+    /// The event item ID matches a child call dispatched by an executing tool.
+    InnerToolCall,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexToolItemEventBase {
+    pub(crate) thread_id: String,
+    pub(crate) session_id: String,
+    pub(crate) turn_id: String,
+    pub(crate) root_turn_id: Option<String>,
+    /// App-server ThreadItem.id. For tool-originated items this generally
+    /// corresponds to the originating core call_id.
+    pub(crate) item_id: String,
+    pub(crate) cell_id: Option<String>,
+    pub(crate) parent_call_id: Option<String>,
+    pub(crate) originating_response_id: Option<String>,
+    pub(crate) subsequent_response_id: Option<String>,
+    pub(crate) app_server_client: CodexAppServerClientMetadata,
+    pub(crate) runtime: CodexRuntimeMetadata,
+    pub(crate) thread_source: Option<ThreadSource>,
+    pub(crate) subagent_source: Option<String>,
+    pub(crate) parent_thread_id: Option<String>,
+    pub(crate) tool_name: String,
+    /// Absent when origin evidence is unavailable or conflicting at emission time.
+    pub(crate) tool_event_type: Option<ToolEventType>,
+    pub(crate) started_at_ms: u64,
+    pub(crate) completed_at_ms: u64,
+    // Observed item lifecycle duration. This may undercount end-to-end execution
+    // for tools where app-server only sees part of the upstream flow.
+    pub(crate) duration_ms: Option<u64>,
+    pub(crate) execution_duration_ms: Option<u64>,
+    pub(crate) review_count: u64,
+    pub(crate) guardian_review_count: u64,
+    pub(crate) user_review_count: u64,
+    pub(crate) final_approval_outcome: FinalApprovalOutcome,
+    pub(crate) terminal_status: ToolItemTerminalStatus,
+    pub(crate) failure_kind: Option<ToolItemFailureKind>,
+    pub(crate) requested_additional_permissions: bool,
+    pub(crate) requested_network_access: bool,
+}
+
+#[allow(dead_code)]
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum ReviewSubjectKind {
+    CommandExecution,
+    WriteStdin,
+    FileChange,
+    McpToolCall,
+    Permissions,
+    NetworkAccess,
+}
+
+#[allow(dead_code)]
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum Reviewer {
+    Guardian,
+    User,
+}
+
+#[allow(dead_code)]
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum ReviewTrigger {
+    Initial,
+    SandboxDenial,
+    NetworkPolicyDenial,
+    ExecveIntercept,
+}
+
+#[allow(dead_code)]
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum ReviewStatus {
+    Approved,
+    Denied,
+    Aborted,
+    TimedOut,
+}
+
+#[allow(dead_code)]
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum ReviewResolution {
+    None,
+    SessionApproval,
+    ExecPolicyAmendment,
+    NetworkPolicyAmendment,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexReviewEventParams {
+    pub(crate) thread_id: String,
+    pub(crate) turn_id: String,
+    pub(crate) item_id: Option<String>,
+    pub(crate) review_id: String,
+    pub(crate) app_server_client: CodexAppServerClientMetadata,
+    pub(crate) runtime: CodexRuntimeMetadata,
+    pub(crate) thread_source: Option<ThreadSource>,
+    pub(crate) subagent_source: Option<String>,
+    pub(crate) parent_thread_id: Option<String>,
+    pub(crate) subject_kind: ReviewSubjectKind,
+    pub(crate) subject_name: String,
+    pub(crate) reviewer: Reviewer,
+    pub(crate) trigger: ReviewTrigger,
+    pub(crate) status: ReviewStatus,
+    pub(crate) resolution: ReviewResolution,
+    pub(crate) started_at_ms: u64,
+    pub(crate) completed_at_ms: u64,
+    pub(crate) duration_ms: Option<u64>,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexReviewEventRequest {
+    pub(crate) event_type: &'static str,
+    pub(crate) event_params: CodexReviewEventParams,
+}
+#[allow(dead_code)]
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum WebSearchActionKind {
+    Search,
+    OpenPage,
+    FindInPage,
+    Other,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexCommandExecutionEventParams {
+    pub(crate) model_slug: Option<String>,
+    pub(crate) reasoning_effort: Option<String>,
+    #[serde(flatten)]
+    pub(crate) base: CodexToolItemEventBase,
+    pub(crate) plugin_id: Option<String>,
+    pub(crate) script_path: Option<String>,
+    pub(crate) command_execution_source: CommandExecutionSource,
+    pub(crate) exit_code: Option<i32>,
+    pub(crate) command_total_action_count: u64,
+    pub(crate) command_read_action_count: u64,
+    pub(crate) command_list_files_action_count: u64,
+    pub(crate) command_search_action_count: u64,
+    pub(crate) command_unknown_action_count: u64,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexCommandExecutionEventRequest {
+    pub(crate) event_type: &'static str,
+    pub(crate) event_params: CodexCommandExecutionEventParams,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexPluginMeasurementEventParams {
+    pub(crate) thread_id: String,
+    pub(crate) turn_id: String,
+    pub(crate) item_id: String,
+    pub(crate) originator: String,
+    pub(crate) model_slug: Option<String>,
+    pub(crate) reasoning_effort: Option<String>,
+    pub(crate) plugin_id: String,
+    pub(crate) execution_id: String,
+    pub(crate) operation: String,
+    pub(crate) measurement_name: String,
+    pub(crate) number_value: f64,
+    pub(crate) dimensions: Option<BTreeMap<String, String>>,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexPluginMeasurementEventRequest {
+    pub(crate) event_type: &'static str,
+    pub(crate) event_params: CodexPluginMeasurementEventParams,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexFileChangeEventParams {
+    #[serde(flatten)]
+    pub(crate) base: CodexToolItemEventBase,
+    pub(crate) file_change_count: u64,
+    pub(crate) file_add_count: u64,
+    pub(crate) file_update_count: u64,
+    pub(crate) file_delete_count: u64,
+    pub(crate) file_move_count: u64,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexFileChangeEventRequest {
+    pub(crate) event_type: &'static str,
+    pub(crate) event_params: CodexFileChangeEventParams,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexMcpToolCallEventParams {
+    #[serde(flatten)]
+    pub(crate) base: CodexToolItemEventBase,
+    pub(crate) mcp_server_name: String,
+    pub(crate) mcp_tool_name: String,
+    pub(crate) mcp_error_present: bool,
+    pub(crate) plugin_id: Option<String>,
+    pub(crate) connector_id: Option<String>,
+    pub(crate) elicitation_type: Option<ElicitationType>,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexMcpToolCallEventRequest {
+    pub(crate) event_type: &'static str,
+    pub(crate) event_params: CodexMcpToolCallEventParams,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexDynamicToolCallEventParams {
+    #[serde(flatten)]
+    pub(crate) base: CodexToolItemEventBase,
+    pub(crate) dynamic_tool_name: String,
+    pub(crate) success: Option<bool>,
+    pub(crate) output_content_item_count: Option<u64>,
+    pub(crate) output_text_item_count: Option<u64>,
+    pub(crate) output_image_item_count: Option<u64>,
+    pub(crate) output_audio_item_count: Option<u64>,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexDynamicToolCallEventRequest {
+    pub(crate) event_type: &'static str,
+    pub(crate) event_params: CodexDynamicToolCallEventParams,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexControlToolCallEventParams {
+    #[serde(flatten)]
+    pub(crate) base: CodexToolItemEventBase,
+    pub(crate) success: bool,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexControlToolCallEventRequest {
+    pub(crate) event_type: &'static str,
+    pub(crate) event_params: CodexControlToolCallEventParams,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexCollabAgentToolCallEventParams {
+    #[serde(flatten)]
+    pub(crate) base: CodexToolItemEventBase,
+    pub(crate) sender_thread_id: String,
+    pub(crate) receiver_thread_count: u64,
+    pub(crate) receiver_thread_ids: Option<Vec<String>>,
+    pub(crate) requested_model: Option<String>,
+    pub(crate) requested_reasoning_effort: Option<String>,
+    pub(crate) agent_state_count: Option<u64>,
+    pub(crate) completed_agent_count: Option<u64>,
+    pub(crate) failed_agent_count: Option<u64>,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexCollabAgentToolCallEventRequest {
+    pub(crate) event_type: &'static str,
+    pub(crate) event_params: CodexCollabAgentToolCallEventParams,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexWebSearchEventParams {
+    #[serde(flatten)]
+    pub(crate) base: CodexToolItemEventBase,
+    pub(crate) web_search_action: Option<WebSearchActionKind>,
+    pub(crate) query_present: bool,
+    pub(crate) query_count: Option<u64>,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexWebSearchEventRequest {
+    pub(crate) event_type: &'static str,
+    pub(crate) event_params: CodexWebSearchEventParams,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexImageGenerationEventParams {
+    #[serde(flatten)]
+    pub(crate) base: CodexToolItemEventBase,
+    pub(crate) revised_prompt_present: bool,
+    pub(crate) saved_path_present: bool,
+    pub(crate) transparent_background: Option<bool>,
+    pub(crate) imagegen_request_id: Option<String>,
+    pub(crate) generation_id: Option<String>,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexImageGenerationEventRequest {
+    pub(crate) event_type: &'static str,
+    pub(crate) event_params: CodexImageGenerationEventParams,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexAppMetadata {
+    pub(crate) connector_id: Option<String>,
+    pub(crate) thread_id: Option<String>,
+    pub(crate) turn_id: Option<String>,
+    pub(crate) app_name: Option<String>,
+    pub(crate) product_client_id: Option<String>,
+    pub(crate) invoke_type: Option<InvocationType>,
+    pub(crate) model_slug: Option<String>,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexAppMentionedEventRequest {
+    pub(crate) event_type: &'static str,
+    pub(crate) event_params: CodexAppMetadata,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexAppUsedMetadata {
+    #[serde(flatten)]
+    pub(crate) app: CodexAppMetadata,
+    pub(crate) elicitation_type: Option<ElicitationType>,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexAppUsedEventRequest {
+    pub(crate) event_type: &'static str,
+    pub(crate) event_params: CodexAppUsedMetadata,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexHookRunMetadata {
+    pub(crate) thread_id: Option<String>,
+    pub(crate) turn_id: Option<String>,
+    pub(crate) product_client_id: Option<String>,
+    pub(crate) model_slug: Option<String>,
+    pub(crate) hook_name: Option<String>,
+    pub(crate) hook_source: Option<&'static str>,
+    pub(crate) handler_type: Option<HookHandlerType>,
+    pub(crate) execution_mode: Option<HookExecutionMode>,
+    pub(crate) status: Option<HookRunStatus>,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexHookRunEventRequest {
+    pub(crate) event_type: &'static str,
+    pub(crate) event_params: CodexHookRunMetadata,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexCompactionEventParams {
+    pub(crate) thread_id: String,
+    pub(crate) session_id: String,
+    pub(crate) turn_id: String,
+    pub(crate) app_server_client: CodexAppServerClientMetadata,
+    pub(crate) runtime: CodexRuntimeMetadata,
+    pub(crate) thread_source: Option<ThreadSource>,
+    pub(crate) subagent_source: Option<String>,
+    pub(crate) parent_thread_id: Option<String>,
+    pub(crate) trigger: CompactionTrigger,
+    pub(crate) reason: CompactionReason,
+    pub(crate) implementation: CompactionImplementation,
+    pub(crate) phase: CompactionPhase,
+    pub(crate) strategy: CompactionStrategy,
+    pub(crate) status: CompactionStatus,
+    pub(crate) codex_error_kind: Option<CodexErrKind>,
+    pub(crate) codex_error_http_status_code: Option<u16>,
+    pub(crate) active_context_tokens_before: i64,
+    pub(crate) active_context_tokens_after: i64,
+    pub(crate) retained_image_count: Option<usize>,
+    pub(crate) compaction_summary_tokens: Option<i64>,
+    pub(crate) cached_input_tokens: Option<i64>,
+    pub(crate) cache_write_input_tokens: Option<i64>,
+    pub(crate) started_at: u64,
+    pub(crate) completed_at: u64,
+    pub(crate) duration_ms: Option<u64>,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexCompactionEventRequest {
+    pub(crate) event_type: &'static str,
+    pub(crate) event_params: CodexCompactionEventParams,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexGoalEventParams {
+    pub(crate) thread_id: String,
+    pub(crate) session_id: String,
+    pub(crate) turn_id: Option<String>,
+    pub(crate) app_server_client: CodexAppServerClientMetadata,
+    pub(crate) runtime: CodexRuntimeMetadata,
+    pub(crate) thread_source: Option<ThreadSource>,
+    pub(crate) subagent_source: Option<String>,
+    pub(crate) parent_thread_id: Option<String>,
+    pub(crate) goal_id: String,
+    pub(crate) event_kind: GoalEventKind,
+    pub(crate) goal_status: codex_state::ThreadGoalStatus,
+    pub(crate) has_token_budget: bool,
+    pub(crate) cumulative_tokens_accounted: Option<i64>,
+    pub(crate) cumulative_time_accounted_seconds: Option<i64>,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexGoalEventRequest {
+    pub(crate) event_type: &'static str,
+    pub(crate) event_params: CodexGoalEventParams,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexTurnEventParams {
+    pub(crate) thread_id: String,
+    pub(crate) session_id: String,
+    pub(crate) turn_id: String,
+    pub(crate) root_turn_id: Option<String>,
+    pub(crate) turn_trigger: Option<String>,
+    pub(crate) codex_turn_source: Option<String>,
+    // TODO(rhan-oai): Populate once queued/default submission type is plumbed from
+    // the turn/start callsites instead of always being reported as None.
+    pub(crate) submission_type: Option<TurnSubmissionType>,
+    pub(crate) app_server_client: CodexAppServerClientMetadata,
+    pub(crate) runtime: CodexRuntimeMetadata,
+    pub(crate) ephemeral: bool,
+    pub(crate) thread_source: Option<ThreadSource>,
+    pub(crate) initialization_mode: ThreadInitializationMode,
+    pub(crate) subagent_source: Option<String>,
+    pub(crate) parent_thread_id: Option<String>,
+    pub(crate) model: Option<String>,
+    pub(crate) model_provider: String,
+    pub(crate) sandbox_policy: Option<&'static str>,
+    pub(crate) reasoning_effort: Option<String>,
+    pub(crate) reasoning_summary: Option<String>,
+    pub(crate) service_tier: String,
+    pub(crate) approval_policy: String,
+    pub(crate) approvals_reviewer: String,
+    pub(crate) guardian_v2_enabled: bool,
+    pub(crate) sandbox_network_access: bool,
+    pub(crate) collaboration_mode: Option<&'static str>,
+    pub(crate) personality: Option<String>,
+    pub(crate) workspace_kind: Option<String>,
+    pub(crate) num_input_images: usize,
+    pub(crate) image_preparations: Vec<ImagePreparationMetadata>,
+    pub(crate) is_first_turn: bool,
+    pub(crate) status: Option<TurnStatus>,
+    /// Client wall-clock time for the first non-startup turn/interrupt request
+    /// that later received a successful response.
+    pub(crate) explicit_client_interrupt_requested_at_ms: Option<u64>,
+    pub(crate) turn_error: Option<CodexErrorInfo>,
+    pub(crate) codex_error_kind: Option<CodexErrKind>,
+    pub(crate) codex_error_http_status_code: Option<u16>,
+    pub(crate) steer_count: Option<usize>,
+    pub(crate) total_tool_call_count: Option<usize>,
+    pub(crate) shell_command_count: Option<usize>,
+    pub(crate) file_change_count: Option<usize>,
+    pub(crate) mcp_tool_call_count: Option<usize>,
+    pub(crate) dynamic_tool_call_count: Option<usize>,
+    pub(crate) subagent_tool_call_count: Option<usize>,
+    pub(crate) web_search_count: Option<usize>,
+    pub(crate) image_generation_count: Option<usize>,
+    pub(crate) input_tokens: Option<i64>,
+    pub(crate) cached_input_tokens: Option<i64>,
+    pub(crate) cache_write_input_tokens: Option<i64>,
+    pub(crate) output_tokens: Option<i64>,
+    pub(crate) reasoning_output_tokens: Option<i64>,
+    pub(crate) total_tokens: Option<i64>,
+    pub(crate) before_first_sampling_ms: u64,
+    pub(crate) sampling_ms: u64,
+    pub(crate) compaction_ms: u64,
+    pub(crate) between_sampling_overhead_ms: u64,
+    pub(crate) tool_blocking_ms: u64,
+    pub(crate) after_last_sampling_ms: u64,
+    pub(crate) sampling_request_count: u32,
+    pub(crate) sampling_retry_count: u32,
+    pub(crate) duration_ms: Option<u64>,
+    pub(crate) started_at: Option<u64>,
+    pub(crate) completed_at: Option<u64>,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexTurnEventRequest {
+    pub(crate) event_type: &'static str,
+    pub(crate) event_params: CodexTurnEventParams,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexTurnSteerEventParams {
+    pub(crate) thread_id: String,
+    pub(crate) session_id: String,
+    pub(crate) expected_turn_id: Option<String>,
+    pub(crate) accepted_turn_id: Option<String>,
+    pub(crate) app_server_client: CodexAppServerClientMetadata,
+    pub(crate) runtime: CodexRuntimeMetadata,
+    pub(crate) thread_source: Option<ThreadSource>,
+    pub(crate) subagent_source: Option<String>,
+    pub(crate) parent_thread_id: Option<String>,
+    pub(crate) num_input_images: usize,
+    pub(crate) result: TurnSteerResult,
+    pub(crate) rejection_reason: Option<TurnSteerRejectionReason>,
+    pub(crate) created_at: u64,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexTurnSteerEventRequest {
+    pub(crate) event_type: &'static str,
+    pub(crate) event_params: CodexTurnSteerEventParams,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexPluginMetadata {
+    pub(crate) plugin_id: Option<String>,
+    pub(crate) remote_plugin_id: Option<String>,
+    pub(crate) plugin_name: Option<String>,
+    pub(crate) marketplace_name: Option<String>,
+    pub(crate) has_skills: Option<bool>,
+    pub(crate) mcp_server_count: Option<usize>,
+    pub(crate) connector_ids: Option<Vec<String>>,
+    pub(crate) product_client_id: Option<String>,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexPluginUsedMetadata {
+    #[serde(flatten)]
+    pub(crate) plugin: CodexPluginMetadata,
+    pub(crate) mcp_server_names: Option<Vec<String>>,
+    pub(crate) thread_id: Option<String>,
+    pub(crate) turn_id: Option<String>,
+    pub(crate) model_slug: Option<String>,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexPluginInstallRequestedPluginMetadata {
+    pub(crate) plugin_id: String,
+    pub(crate) remote_plugin_id: Option<String>,
+    pub(crate) plugin_name: String,
+    pub(crate) connector_ids: Vec<String>,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexPluginInstallRequestedMetadata {
+    pub(crate) suggestion_id: String,
+    pub(crate) plugins: Vec<CodexPluginInstallRequestedPluginMetadata>,
+    pub(crate) source: crate::facts::PluginInstallRequestSource,
+    pub(crate) thread_id: String,
+    pub(crate) turn_id: String,
+    pub(crate) model_slug: String,
+    pub(crate) product_client_id: Option<String>,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexPluginInstallRequestedEventRequest {
+    pub(crate) event_type: &'static str,
+    pub(crate) event_params: CodexPluginInstallRequestedMetadata,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexPluginEventRequest {
+    pub(crate) event_type: &'static str,
+    pub(crate) event_params: CodexPluginMetadata,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexPluginInstallFailedMetadata {
+    #[serde(flatten)]
+    pub(crate) plugin: CodexPluginMetadata,
+    pub(crate) source: crate::facts::PluginInstallSource,
+    pub(crate) error_type: String,
+    pub(crate) sub_error_type: Option<String>,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexPluginInstallFailedEventRequest {
+    pub(crate) event_type: &'static str,
+    pub(crate) event_params: CodexPluginInstallFailedMetadata,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexOnboardingExternalAgentImportCompleteMetadata {
+    pub(crate) import_id: String,
+    pub(crate) source: String,
+    pub(crate) provider_id: String,
+    #[serde(rename = "type")]
+    pub(crate) item_type: String,
+    pub(crate) success_count: usize,
+    pub(crate) failed_count: usize,
+    pub(crate) product_client_id: Option<String>,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexOnboardingExternalAgentImportCompleteEventRequest {
+    pub(crate) event_type: &'static str,
+    pub(crate) event_params: CodexOnboardingExternalAgentImportCompleteMetadata,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexOnboardingExternalAgentImportFailureMetadata {
+    pub(crate) import_id: String,
+    pub(crate) source: String,
+    pub(crate) provider_id: String,
+    #[serde(rename = "type")]
+    pub(crate) item_type: String,
+    pub(crate) failure_stage: String,
+    pub(crate) error_type: String,
+    pub(crate) sub_error_type: Option<String>,
+    pub(crate) product_client_id: Option<String>,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexOnboardingExternalAgentImportFailureEventRequest {
+    pub(crate) event_type: &'static str,
+    pub(crate) event_params: CodexOnboardingExternalAgentImportFailureMetadata,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexPluginUsedEventRequest {
+    pub(crate) event_type: &'static str,
+    pub(crate) event_params: CodexPluginUsedMetadata,
+}
+
+pub(crate) fn plugin_state_event_type(state: PluginState) -> &'static str {
+    match state {
+        PluginState::Installed => "codex_plugin_installed",
+        PluginState::Uninstalled => "codex_plugin_uninstalled",
+        PluginState::Enabled => "codex_plugin_enabled",
+        PluginState::Disabled => "codex_plugin_disabled",
+    }
+}
+
+pub(crate) fn codex_app_metadata(
+    tracking: &TrackEventsContext,
+    app: AppInvocation,
+) -> CodexAppMetadata {
+    CodexAppMetadata {
+        connector_id: app.connector_id,
+        thread_id: Some(tracking.thread_id.clone()),
+        turn_id: Some(tracking.turn_id.clone()),
+        app_name: app.app_name,
+        product_client_id: Some(tracking.product_client_id.clone()),
+        invoke_type: app.invocation_type,
+        model_slug: Some(tracking.model_slug.clone()),
+    }
+}
+
+pub(crate) fn codex_plugin_metadata(plugin: PluginTelemetryMetadata) -> CodexPluginMetadata {
+    codex_plugin_metadata_with_product_client_id(plugin, originator().value)
+}
+
+fn codex_plugin_metadata_with_product_client_id(
+    plugin: PluginTelemetryMetadata,
+    product_client_id: String,
+) -> CodexPluginMetadata {
+    let PluginTelemetryMetadata {
+        plugin_id,
+        remote_plugin_id,
+        capability_summary,
+    } = plugin;
+    CodexPluginMetadata {
+        plugin_id: plugin_id.as_ref().map(PluginId::as_key),
+        remote_plugin_id,
+        plugin_name: plugin_id
+            .as_ref()
+            .map(|plugin_id| plugin_id.plugin_name.clone()),
+        marketplace_name: plugin_id.map(|plugin_id| plugin_id.marketplace_name),
+        has_skills: capability_summary
+            .as_ref()
+            .map(|summary| summary.has_skills),
+        mcp_server_count: capability_summary
+            .as_ref()
+            .map(|summary| summary.mcp_server_names.len()),
+        connector_ids: capability_summary.map(|summary| {
+            summary
+                .app_connector_ids
+                .into_iter()
+                .map(|connector_id| connector_id.0)
+                .collect()
+        }),
+        product_client_id: Some(product_client_id),
+    }
+}
+
+pub(crate) fn codex_plugin_install_requested_metadata(
+    tracking: &TrackEventsContext,
+    request: PluginInstallRequested,
+) -> CodexPluginInstallRequestedMetadata {
+    CodexPluginInstallRequestedMetadata {
+        suggestion_id: request.suggestion_id,
+        plugins: request
+            .plugins
+            .into_iter()
+            .map(|plugin| CodexPluginInstallRequestedPluginMetadata {
+                plugin_id: plugin.plugin_id,
+                remote_plugin_id: plugin.remote_plugin_id,
+                plugin_name: plugin.plugin_name,
+                connector_ids: plugin.connector_ids,
+            })
+            .collect(),
+        source: request.source,
+        thread_id: tracking.thread_id.clone(),
+        turn_id: tracking.turn_id.clone(),
+        model_slug: tracking.model_slug.clone(),
+        product_client_id: Some(originator().value),
+    }
+}
+
+pub(crate) fn codex_compaction_event_params(
+    input: CodexCompactionEvent,
+    session_id: String,
+    app_server_client: CodexAppServerClientMetadata,
+    runtime: CodexRuntimeMetadata,
+    thread_source: Option<ThreadSource>,
+    subagent_source: Option<String>,
+    parent_thread_id: Option<String>,
+) -> CodexCompactionEventParams {
+    CodexCompactionEventParams {
+        thread_id: input.thread_id,
+        session_id,
+        turn_id: input.turn_id,
+        app_server_client,
+        runtime,
+        thread_source,
+        subagent_source,
+        parent_thread_id,
+        trigger: input.trigger,
+        reason: input.reason,
+        implementation: input.implementation,
+        phase: input.phase,
+        strategy: input.strategy,
+        status: input.status,
+        codex_error_kind: input.codex_error_kind,
+        codex_error_http_status_code: input.codex_error_http_status_code,
+        active_context_tokens_before: input.active_context_tokens_before,
+        active_context_tokens_after: input.active_context_tokens_after,
+        retained_image_count: input.retained_image_count,
+        compaction_summary_tokens: input.compaction_summary_tokens,
+        cached_input_tokens: input.cached_input_tokens,
+        cache_write_input_tokens: input.cache_write_input_tokens,
+        started_at: input.started_at,
+        completed_at: input.completed_at,
+        duration_ms: input.duration_ms,
+    }
+}
+
+pub(crate) fn codex_goal_event_params(
+    input: CodexGoalEvent,
+    session_id: String,
+    app_server_client: CodexAppServerClientMetadata,
+    runtime: CodexRuntimeMetadata,
+    thread_source: Option<ThreadSource>,
+    subagent_source: Option<String>,
+    parent_thread_id: Option<String>,
+) -> CodexGoalEventParams {
+    CodexGoalEventParams {
+        thread_id: input.thread_id,
+        session_id,
+        turn_id: input.turn_id,
+        app_server_client,
+        runtime,
+        thread_source,
+        subagent_source,
+        parent_thread_id,
+        goal_id: input.goal_id,
+        event_kind: input.event_kind,
+        goal_status: input.goal_status,
+        has_token_budget: input.has_token_budget,
+        cumulative_tokens_accounted: input.cumulative_tokens_accounted,
+        cumulative_time_accounted_seconds: input.cumulative_time_accounted_seconds,
+    }
+}
+
+pub(crate) fn codex_plugin_used_metadata(
+    tracking: &TrackEventsContext,
+    plugin: PluginTelemetryMetadata,
+) -> CodexPluginUsedMetadata {
+    let mcp_server_names = plugin
+        .capability_summary
+        .as_ref()
+        .map(|summary| summary.mcp_server_names.clone());
+    CodexPluginUsedMetadata {
+        plugin: codex_plugin_metadata_with_product_client_id(
+            plugin,
+            tracking.product_client_id.clone(),
+        ),
+        mcp_server_names,
+        thread_id: Some(tracking.thread_id.clone()),
+        turn_id: Some(tracking.turn_id.clone()),
+        model_slug: Some(tracking.model_slug.clone()),
+    }
+}
+
+pub(crate) fn codex_hook_run_metadata(
+    tracking: &TrackEventsContext,
+    hook: HookRunFact,
+) -> CodexHookRunMetadata {
+    CodexHookRunMetadata {
+        thread_id: Some(tracking.thread_id.clone()),
+        turn_id: Some(tracking.turn_id.clone()),
+        product_client_id: Some(tracking.product_client_id.clone()),
+        model_slug: Some(tracking.model_slug.clone()),
+        hook_name: Some(analytics_hook_event_name(hook.event_name).to_owned()),
+        hook_source: Some(analytics_hook_source(hook.hook_source)),
+        handler_type: Some(hook.handler_type),
+        execution_mode: Some(hook.execution_mode),
+        status: Some(analytics_hook_status(hook.status)),
+    }
+}
+
+fn analytics_hook_event_name(event_name: HookEventName) -> &'static str {
+    match event_name {
+        HookEventName::PreToolUse => "PreToolUse",
+        HookEventName::PermissionRequest => "PermissionRequest",
+        HookEventName::PostToolUse => "PostToolUse",
+        HookEventName::PreCompact => "PreCompact",
+        HookEventName::PostCompact => "PostCompact",
+        HookEventName::SessionStart => "SessionStart",
+        HookEventName::SessionEnd => "SessionEnd",
+        HookEventName::UserPromptSubmit => "UserPromptSubmit",
+        HookEventName::SubagentStart => "SubagentStart",
+        HookEventName::SubagentStop => "SubagentStop",
+        HookEventName::Stop => "Stop",
+        HookEventName::Interrupt => "Interrupt",
+    }
+}
+
+fn analytics_hook_source(source: HookSource) -> &'static str {
+    match source {
+        HookSource::System => "system",
+        HookSource::User => "user",
+        HookSource::Project => "project",
+        HookSource::Mdm => "mdm",
+        HookSource::SessionFlags => "session_flags",
+        HookSource::Plugin => "plugin",
+        HookSource::CloudRequirements => "cloud_requirements",
+        HookSource::CloudManagedConfig => "cloud_managed_config",
+        HookSource::LegacyManagedConfigFile => "legacy_managed_config_file",
+        HookSource::LegacyManagedConfigMdm => "legacy_managed_config_mdm",
+        HookSource::Unknown => "unknown",
+    }
+}
+
+pub(crate) fn current_runtime_metadata() -> CodexRuntimeMetadata {
+    let os_info = os_info::get();
+    CodexRuntimeMetadata {
+        codex_rs_version: env!("CARGO_PKG_VERSION").to_string(),
+        runtime_os: std::env::consts::OS.to_string(),
+        runtime_os_version: os_info.version().to_string(),
+        runtime_arch: std::env::consts::ARCH.to_string(),
+    }
+}
+
+pub(crate) fn subagent_thread_started_event_request(
+    input: SubAgentThreadStartedInput,
+) -> ThreadInitializedEvent {
+    let event_params = ThreadInitializedEventParams {
+        thread_id: input.thread_id,
+        session_id: input.session_id,
+        app_server_client: CodexAppServerClientMetadata {
+            product_client_id: input.product_client_id,
+            client_name: input.client_name,
+            client_version: input.client_version,
+            rpc_transport: AppServerRpcTransport::InProcess,
+            experimental_api_enabled: None,
+        },
+        runtime: current_runtime_metadata(),
+        model: input.model,
+        ephemeral: input.ephemeral,
+        is_worktree: None,
+        thread_source: input.thread_source,
+        initialization_mode: ThreadInitializationMode::New,
+        subagent_source: Some(subagent_source_name(&input.subagent_source)),
+        parent_thread_id: input.parent_thread_id,
+        forked_from_thread_id: input.forked_from_thread_id,
+        created_at: input.created_at,
+    };
+    ThreadInitializedEvent {
+        event_type: "codex_thread_initialized",
+        event_params,
+    }
+}
+
+pub(crate) fn subagent_source_name(subagent_source: &SubAgentSource) -> String {
+    subagent_source.kind().to_string()
+}
+
+fn analytics_hook_status(status: HookRunStatus) -> HookRunStatus {
+    match status {
+        // Running is unexpected here and normalized defensively.
+        HookRunStatus::Running => HookRunStatus::Failed,
+        other => other,
+    }
+}

codex-rs/analytics/src/facts.rs

@@ -0,0 +1,742 @@
+use crate::events::AppServerRpcTransport;
+use crate::events::CodexRuntimeMetadata;
+use crate::events::GuardianReviewEventParams;
+use crate::guardian_v2::GuardianV2Event;
+use codex_app_server_protocol::ClientRequest;
+use codex_app_server_protocol::ClientResponsePayload;
+use codex_app_server_protocol::InitializeParams;
+use codex_app_server_protocol::JSONRPCErrorError;
+use codex_app_server_protocol::RequestId;
+use codex_app_server_protocol::ServerNotification;
+use codex_app_server_protocol::ServerRequest;
+use codex_app_server_protocol::ServerResponse;
+use codex_plugin::PluginTelemetryMetadata;
+use codex_protocol::config_types::ApprovalsReviewer;
+use codex_protocol::config_types::ModeKind;
+use codex_protocol::config_types::Personality;
+use codex_protocol::config_types::ReasoningSummary;
+use codex_protocol::config_types::ServiceTier;
+use codex_protocol::error::CodexErr;
+pub use codex_protocol::error::CodexErrKind;
+use codex_protocol::models::PermissionProfile;
+use codex_protocol::openai_models::ReasoningEffort;
+use codex_protocol::protocol::AskForApproval;
+use codex_protocol::protocol::HookEventName;
+use codex_protocol::protocol::HookExecutionMode;
+use codex_protocol::protocol::HookHandlerType;
+use codex_protocol::protocol::HookRunStatus;
+use codex_protocol::protocol::HookSource;
+use codex_protocol::protocol::SessionSource;
+use codex_protocol::protocol::SkillScope;
+use codex_protocol::protocol::SubAgentSource;
+use codex_protocol::protocol::ThreadSource;
+use codex_protocol::protocol::TokenUsage;
+use codex_protocol::request_permissions::RequestPermissionsResponse;
+use serde::Serialize;
+use std::collections::BTreeMap;
+use std::path::PathBuf;
+use std::sync::Arc;
+
+#[derive(Clone)]
+pub struct TrackEventsContext {
+    pub model_slug: String,
+    pub thread_id: String,
+    pub turn_id: String,
+    pub product_client_id: String,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ArtifactOperationLifecycle {
+    Started,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ArtifactOperation {
+    pub item_id: String,
+    pub lifecycle: ArtifactOperationLifecycle,
+    pub occurred_at_ms: u64,
+    pub plugin_id: String,
+    pub script_path: String,
+    pub skill: String,
+    pub artifact_type: String,
+    pub operation_kind: String,
+    pub expected_output_count: u32,
+    pub output_format: String,
+    pub execution_backend: String,
+}
+
+#[derive(Clone)]
+pub enum CodeModeToolCallFact {
+    CellStarted {
+        thread_id: String,
+        turn_id: String,
+        call_id: String,
+        cell_id: String,
+    },
+    ChildStarted {
+        thread_id: String,
+        turn_id: String,
+        call_id: String,
+        cell_id: String,
+    },
+    CellClosed {
+        thread_id: String,
+        turn_id: String,
+        cell_id: String,
+    },
+    SamplingResponseCompleted {
+        thread_id: String,
+        turn_id: String,
+        response_id: String,
+        tool_call_ids: Vec<String>,
+    },
+    Completed {
+        thread_id: String,
+        turn_id: String,
+        turn_metadata: Arc<dyn TurnAnalyticsMetadata>,
+        call_id: String,
+        cell_id: Option<String>,
+        tool_name: String,
+        started_at_ms: u64,
+        completed_at_ms: u64,
+        status: CodeModeToolCallStatus,
+    },
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum CodeModeToolCallStatus {
+    Completed,
+    Failed,
+    Interrupted,
+}
+
+#[derive(Clone)]
+pub struct ControlToolCallFact {
+    pub thread_id: String,
+    pub turn_id: String,
+    pub turn_metadata: Arc<dyn TurnAnalyticsMetadata>,
+    pub call_id: String,
+    pub cell_id: Option<String>,
+    pub tool_name: String,
+    pub started_at_ms: u64,
+    pub completed_at_ms: u64,
+    pub status: ControlToolCallStatus,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum ControlToolCallStatus {
+    Completed,
+    Failed,
+    Rejected,
+    Interrupted,
+}
+
+pub fn build_track_events_context(
+    model_slug: String,
+    thread_id: String,
+    turn_id: String,
+    product_client_id: String,
+) -> TrackEventsContext {
+    TrackEventsContext {
+        model_slug,
+        thread_id,
+        turn_id,
+        product_client_id,
+    }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ImageDetailSetting {
+    High,
+    Original,
+}
+
+/// Measurements for one successfully decoded image at the point where Codex prepares it for
+/// durable conversation history.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
+pub struct ImagePreparationMetadata {
+    /// Set for images embedded in message content.
+    pub message_role: Option<String>,
+    /// Set to the originating call ID for tool-output images. This joins to the `item_id` on
+    /// existing tool events for tool type and provenance.
+    pub item_id: Option<String>,
+    pub effective_detail: ImageDetailSetting,
+    pub source_width: u32,
+    pub source_height: u32,
+    pub prepared_width: u32,
+    pub prepared_height: u32,
+}
+
+#[derive(Clone)]
+pub struct ImagePreparationFact {
+    pub turn_id: String,
+    pub metadata: ImagePreparationMetadata,
+}
+
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum TurnSubmissionType {
+    Default,
+    Queued,
+}
+
+#[derive(Clone)]
+pub struct TurnResolvedConfigFact {
+    pub turn_id: String,
+    pub thread_id: String,
+    pub turn_metadata: Arc<dyn TurnAnalyticsMetadata>,
+    pub num_input_images: usize,
+    pub submission_type: Option<TurnSubmissionType>,
+    pub ephemeral: bool,
+    pub session_source: SessionSource,
+    pub model: String,
+    pub model_provider: String,
+    pub permission_profile: PermissionProfile,
+    pub permission_profile_cwd: PathBuf,
+    pub reasoning_effort: Option<ReasoningEffort>,
+    pub reasoning_summary: Option<ReasoningSummary>,
+    pub service_tier: Option<ServiceTier>,
+    pub approval_policy: AskForApproval,
+    pub approvals_reviewer: ApprovalsReviewer,
+    pub guardian_v2_enabled: bool,
+    pub sandbox_network_access: bool,
+    pub collaboration_mode: ModeKind,
+    pub personality: Option<Personality>,
+    pub workspace_kind: Option<String>,
+    pub is_first_turn: bool,
+}
+
+/// A live, read-only view of a turn's analytics metadata.
+///
+/// Implementations must return `None` for unknown or ambiguous roots. The reducer
+/// reads this when constructing each event because steering can invalidate a root
+/// after the turn's configuration has been resolved.
+pub trait TurnAnalyticsMetadata: Send + Sync {
+    fn root_turn_id(&self) -> Option<String>;
+    /// The caller-provided trigger recorded when this turn started.
+    fn turn_trigger(&self) -> Option<String>;
+    /// The effective Responses source at event emission, including accepted steers.
+    fn codex_turn_source(&self) -> Option<String>;
+}
+
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ThreadInitializationMode {
+    New,
+    Forked,
+    Resumed,
+}
+
+#[derive(Clone)]
+pub struct TurnTokenUsageFact {
+    pub turn_id: String,
+    pub thread_id: String,
+    pub token_usage: TokenUsage,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
+pub struct TurnProfile {
+    pub before_first_sampling_ms: u64,
+    pub sampling_ms: u64,
+    pub compaction_ms: u64,
+    pub between_sampling_overhead_ms: u64,
+    pub tool_blocking_ms: u64,
+    pub after_last_sampling_ms: u64,
+    pub sampling_request_count: u32,
+    pub sampling_retry_count: u32,
+}
+
+#[derive(Clone)]
+pub struct TurnProfileFact {
+    pub turn_id: String,
+    pub profile: TurnProfile,
+}
+
+#[derive(Clone)]
+pub struct TurnCodexErrorFact {
+    pub(crate) turn_id: String,
+    pub(crate) thread_id: String,
+    pub(crate) error: TurnCodexError,
+}
+
+impl TurnCodexErrorFact {
+    pub fn from_codex_err(thread_id: String, turn_id: String, error: &CodexErr) -> Self {
+        Self {
+            turn_id,
+            thread_id,
+            error: TurnCodexError::from_codex_err(error),
+        }
+    }
+}
+
+#[derive(Clone)]
+pub(crate) struct TurnCodexError {
+    pub(crate) kind: CodexErrKind,
+    pub(crate) http_status_code: Option<u16>,
+}
+
+impl TurnCodexError {
+    fn from_codex_err(error: &CodexErr) -> Self {
+        Self {
+            kind: error.into(),
+            http_status_code: error.http_status_code_value(),
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum TurnStatus {
+    Completed,
+    Failed,
+    Interrupted,
+}
+
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum TurnSteerResult {
+    Accepted,
+    Rejected,
+}
+
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum TurnSteerRejectionReason {
+    NoActiveTurn,
+    ExpectedTurnMismatch,
+    NonSteerableReview,
+    NonSteerableCompact,
+    EmptyInput,
+    InputTooLarge,
+}
+
+#[derive(Clone)]
+pub struct CodexTurnSteerEvent {
+    pub expected_turn_id: Option<String>,
+    pub accepted_turn_id: Option<String>,
+    pub num_input_images: usize,
+    pub result: TurnSteerResult,
+    pub rejection_reason: Option<TurnSteerRejectionReason>,
+    pub created_at: u64,
+}
+
+#[derive(Clone, Copy, Debug)]
+pub enum AnalyticsJsonRpcError {
+    TurnSteer(TurnSteerRequestError),
+    Input(InputError),
+}
+
+#[derive(Clone, Copy, Debug)]
+pub enum TurnSteerRequestError {
+    NoActiveTurn,
+    ExpectedTurnMismatch,
+    NonSteerableReview,
+    NonSteerableCompact,
+}
+
+#[derive(Clone, Copy, Debug)]
+pub enum InputError {
+    Empty,
+    TooLarge,
+}
+
+impl From<TurnSteerRequestError> for TurnSteerRejectionReason {
+    fn from(error: TurnSteerRequestError) -> Self {
+        match error {
+            TurnSteerRequestError::NoActiveTurn => Self::NoActiveTurn,
+            TurnSteerRequestError::ExpectedTurnMismatch => Self::ExpectedTurnMismatch,
+            TurnSteerRequestError::NonSteerableReview => Self::NonSteerableReview,
+            TurnSteerRequestError::NonSteerableCompact => Self::NonSteerableCompact,
+        }
+    }
+}
+
+impl From<InputError> for TurnSteerRejectionReason {
+    fn from(error: InputError) -> Self {
+        match error {
+            InputError::Empty => Self::EmptyInput,
+            InputError::TooLarge => Self::InputTooLarge,
+        }
+    }
+}
+
+#[derive(Clone, Debug)]
+pub struct SkillInvocation {
+    pub skill_name: String,
+    pub location: SkillInvocationLocation,
+    pub plugin_id: Option<String>,
+    pub remote_plugin_id: Option<String>,
+    pub invocation_type: InvocationType,
+}
+
+#[derive(Clone, Debug)]
+pub enum SkillInvocationLocation {
+    Host {
+        path: PathBuf,
+        scope: SkillScope,
+    },
+    Resource {
+        id: String,
+        skill_id: Option<String>,
+        scope: Option<SkillScope>,
+    },
+}
+
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "lowercase")]
+pub enum InvocationType {
+    Explicit,
+    Implicit,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ElicitationType {
+    /// Authentication or account linking blocked the original attempt, as reported
+    /// by trusted connector auth-failure metadata. Both are treated the same when
+    /// identifying elicitation-only usage. This does not imply that an
+    /// authentication prompt was shown or completed.
+    AuthOrLink,
+    Approval,
+}
+
+pub struct AppInvocation {
+    pub connector_id: Option<String>,
+    pub app_name: Option<String>,
+    pub invocation_type: Option<InvocationType>,
+}
+
+/// A known classification, queued before the corresponding item completion.
+/// Ordinary calls do not send this fact; their emitted classification stays null.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct McpToolCallElicitation {
+    pub thread_id: String,
+    pub turn_id: String,
+    pub item_id: String,
+    pub elicitation_type: ElicitationType,
+}
+
+#[derive(Clone)]
+pub struct SubAgentThreadStartedInput {
+    pub session_id: String,
+    pub thread_id: String,
+    pub parent_thread_id: Option<String>,
+    pub forked_from_thread_id: Option<String>,
+    pub product_client_id: String,
+    pub client_name: Option<String>,
+    pub client_version: Option<String>,
+    pub model: String,
+    pub ephemeral: bool,
+    pub thread_source: Option<ThreadSource>,
+    pub subagent_source: SubAgentSource,
+    pub created_at: u64,
+}
+
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum CompactionTrigger {
+    Manual,
+    Auto,
+}
+
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum CompactionReason {
+    UserRequested,
+    ContextLimit,
+    ModelDownshift,
+    CompHashChanged,
+}
+
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum CompactionImplementation {
+    Responses,
+    ResponsesCompactionV2,
+}
+
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum CompactionPhase {
+    StandaloneTurn,
+    PreTurn,
+    MidTurn,
+}
+
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum CompactionStrategy {
+    Memento,
+    PrefixCompaction,
+}
+
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum CompactionStatus {
+    Completed,
+    Failed,
+    Interrupted,
+}
+
+#[derive(Clone)]
+pub struct CodexCompactionEvent {
+    pub thread_id: String,
+    pub turn_id: String,
+    pub trigger: CompactionTrigger,
+    pub reason: CompactionReason,
+    pub implementation: CompactionImplementation,
+    pub phase: CompactionPhase,
+    pub strategy: CompactionStrategy,
+    pub status: CompactionStatus,
+    pub codex_error_kind: Option<CodexErrKind>,
+    pub codex_error_http_status_code: Option<u16>,
+    pub active_context_tokens_before: i64,
+    pub active_context_tokens_after: i64,
+    pub retained_image_count: Option<usize>,
+    pub compaction_summary_tokens: Option<i64>,
+    pub cached_input_tokens: Option<i64>,
+    pub cache_write_input_tokens: Option<i64>,
+    pub started_at: u64,
+    pub completed_at: u64,
+    pub duration_ms: Option<u64>,
+}
+
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum GoalEventKind {
+    Created,
+    UsageAccounted,
+    StatusChanged,
+    Cleared,
+}
+
+#[derive(Clone)]
+pub struct CodexGoalEvent {
+    pub thread_id: String,
+    pub turn_id: Option<String>,
+    pub goal_id: String,
+    pub event_kind: GoalEventKind,
+    pub goal_status: codex_state::ThreadGoalStatus,
+    pub has_token_budget: bool,
+    pub cumulative_tokens_accounted: Option<i64>,
+    pub cumulative_time_accounted_seconds: Option<i64>,
+}
+
+#[allow(dead_code)]
+pub(crate) enum AnalyticsFact {
+    Initialize {
+        connection_id: u64,
+        params: InitializeParams,
+        product_client_id: String,
+        runtime: CodexRuntimeMetadata,
+        rpc_transport: AppServerRpcTransport,
+    },
+    ClientRequest {
+        connection_id: u64,
+        request_id: RequestId,
+        request: Box<ClientRequest>,
+    },
+    ExplicitClientInterruptRequest {
+        connection_id: u64,
+        request_id: RequestId,
+        turn_id: String,
+        requested_at_ms: u64,
+    },
+    ClientResponse {
+        connection_id: u64,
+        request_id: RequestId,
+        response: Box<ClientResponsePayload>,
+        thread_originator: Option<String>,
+    },
+    ErrorResponse {
+        connection_id: u64,
+        request_id: RequestId,
+        error: JSONRPCErrorError,
+        error_type: Option<AnalyticsJsonRpcError>,
+    },
+    ServerRequest {
+        connection_id: u64,
+        request: Box<ServerRequest>,
+    },
+    ServerResponse {
+        completed_at_ms: u64,
+        response: Box<ServerResponse>,
+    },
+    EffectivePermissionsApprovalResponse {
+        completed_at_ms: u64,
+        request_id: RequestId,
+        response: Box<RequestPermissionsResponse>,
+    },
+    ServerRequestAborted {
+        completed_at_ms: u64,
+        request_id: RequestId,
+    },
+    Notification(Box<ServerNotification>),
+    // Facts that do not naturally exist on the app-server protocol surface, or
+    // would require non-trivial protocol reshaping on this branch.
+    Custom(CustomAnalyticsFact),
+}
+
+pub(crate) enum CustomAnalyticsFact {
+    ArtifactOperation(ArtifactOperationInput),
+    CodeModeToolCall(CodeModeToolCallFact),
+    ControlToolCall(ControlToolCallFact),
+    SubAgentThreadStarted(SubAgentThreadStartedInput),
+    Compaction(Box<CodexCompactionEvent>),
+    Goal(Box<CodexGoalEvent>),
+    ThreadHintStatus(Box<crate::thread_hint::ThreadHintStatusEvent>),
+    GuardianReview(Box<GuardianReviewEventParams>),
+    GuardianV2(Box<GuardianV2Event>),
+    TurnResolvedConfig(Box<TurnResolvedConfigFact>),
+    TurnTokenUsage(Box<TurnTokenUsageFact>),
+    TurnProfile(Box<TurnProfileFact>),
+    TurnCodexError(Box<TurnCodexErrorFact>),
+    ImagePreparation(Box<ImagePreparationFact>),
+    SkillInvoked(SkillInvokedInput),
+    AppMentioned(AppMentionedInput),
+    AppUsed(AppUsedInput),
+    McpToolCallElicitation(McpToolCallElicitation),
+    HookRun(HookRunInput),
+    PluginUsed(PluginUsedInput),
+    PluginInstallRequested(PluginInstallRequestedInput),
+    PluginStateChanged(PluginStateChangedInput),
+    PluginInstallFailed(PluginInstallFailedInput),
+    PluginMeasurements(PluginMeasurementsInput),
+    ExternalAgentConfigImportCompleted(ExternalAgentConfigImportCompletedInput),
+    ExternalAgentConfigImportFailure(ExternalAgentConfigImportFailureInput),
+}
+
+pub(crate) struct ArtifactOperationInput {
+    pub tracking: TrackEventsContext,
+    pub operation: ArtifactOperation,
+}
+
+#[derive(Clone, Debug, PartialEq)]
+pub struct PluginMeasurementRow {
+    pub measurement_name: String,
+    pub number_value: f64,
+    pub dimensions: BTreeMap<String, String>,
+}
+
+#[derive(Clone, Debug, PartialEq)]
+pub struct PluginMeasurementsInput {
+    pub thread_id: String,
+    pub turn_id: String,
+    pub item_id: String,
+    pub originator: String,
+    pub model_slug: Option<String>,
+    pub reasoning_effort: Option<String>,
+    pub plugin_id: String,
+    pub execution_id: String,
+    pub operation: String,
+    pub rows: Vec<PluginMeasurementRow>,
+}
+
+pub(crate) struct SkillInvokedInput {
+    pub tracking: TrackEventsContext,
+    pub invocations: Vec<SkillInvocation>,
+}
+
+pub(crate) struct AppMentionedInput {
+    pub tracking: TrackEventsContext,
+    pub mentions: Vec<AppInvocation>,
+}
+
+pub(crate) struct AppUsedInput {
+    pub tracking: TrackEventsContext,
+    pub app: AppInvocation,
+    pub elicitation_type: Option<ElicitationType>,
+}
+
+pub(crate) struct HookRunInput {
+    pub tracking: TrackEventsContext,
+    pub hook: HookRunFact,
+}
+
+pub struct HookRunFact {
+    pub event_name: HookEventName,
+    pub hook_source: HookSource,
+    pub handler_type: HookHandlerType,
+    pub execution_mode: HookExecutionMode,
+    pub status: HookRunStatus,
+}
+
+pub(crate) struct PluginUsedInput {
+    pub tracking: TrackEventsContext,
+    pub plugin: PluginTelemetryMetadata,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum PluginInstallRequestSource {
+    EndpointRecommendation,
+    LegacyDiscovery,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct PluginInstallRequested {
+    pub suggestion_id: String,
+    pub plugins: Vec<PluginInstallRequestedPlugin>,
+    pub source: PluginInstallRequestSource,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct PluginInstallRequestedPlugin {
+    pub plugin_id: String,
+    pub remote_plugin_id: Option<String>,
+    pub plugin_name: String,
+    pub connector_ids: Vec<String>,
+}
+
+pub(crate) struct PluginInstallRequestedInput {
+    pub tracking: TrackEventsContext,
+    pub request: PluginInstallRequested,
+}
+
+pub(crate) struct PluginStateChangedInput {
+    pub plugin: PluginTelemetryMetadata,
+    pub state: PluginState,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum PluginInstallSource {
+    Manual,
+    ExternalAgentMigration,
+}
+
+pub(crate) struct PluginInstallFailedInput {
+    pub plugin: PluginTelemetryMetadata,
+    pub source: PluginInstallSource,
+    pub error_type: String,
+    pub sub_error_type: Option<String>,
+}
+
+pub struct ExternalAgentConfigImportCompletedInput {
+    pub import_id: String,
+    pub source: String,
+    pub provider_id: String,
+    pub item_type: String,
+    pub success_count: usize,
+    pub failed_count: usize,
+}
+
+pub struct ExternalAgentConfigImportFailureInput {
+    pub import_id: String,
+    pub source: String,
+    pub provider_id: String,
+    pub item_type: String,
+    pub failure_stage: String,
+    pub error_type: String,
+    pub sub_error_type: Option<String>,
+}
+
+#[derive(Clone, Copy)]
+pub(crate) enum PluginState {
+    Installed,
+    Uninstalled,
+    Enabled,
+    Disabled,
+}

codex-rs/analytics/src/guardian_v2.rs

@@ -0,0 +1,49 @@
+//! Guardian V2 classifier and fast-decision facts, enriched by the existing reducer.
+//! Payloads contain attribution and bounded outcomes, never prompts or tool arguments.
+
+use crate::events::CodexAppServerClientMetadata;
+use crate::events::CodexRuntimeMetadata;
+use codex_protocol::protocol::ThreadSource;
+use serde::Serialize;
+
+#[derive(Serialize)]
+pub struct GuardianV2Event {
+    pub thread_id: String,
+    pub turn_id: String,
+    pub item_id: Option<String>,
+    pub model: Option<String>,
+    pub occurred_at_ms: u64,
+    #[serde(flatten)]
+    pub kind: GuardianV2EventKind,
+}
+
+#[derive(Serialize)]
+#[serde(untagged)]
+pub enum GuardianV2EventKind {
+    Classification {
+        outcome: &'static str,
+        risk_level: Option<&'static str>,
+        duration_ms: u64,
+    },
+    FastDecision {
+        decision: &'static str,
+    },
+}
+
+#[derive(Serialize)]
+pub(crate) struct GuardianV2EventRequest {
+    pub(crate) event_type: &'static str,
+    pub(crate) event_params: GuardianV2EventParams,
+}
+
+#[derive(Serialize)]
+pub(crate) struct GuardianV2EventParams {
+    pub(crate) session_id: String,
+    pub(crate) app_server_client: CodexAppServerClientMetadata,
+    pub(crate) runtime: CodexRuntimeMetadata,
+    pub(crate) thread_source: Option<ThreadSource>,
+    pub(crate) subagent_source: Option<String>,
+    pub(crate) parent_thread_id: Option<String>,
+    #[serde(flatten)]
+    pub(crate) guardian_v2: GuardianV2Event,
+}

codex-rs/analytics/src/lib.rs

@@ -0,0 +1,116 @@
+mod accepted_lines;
+#[cfg(debug_assertions)]
+mod analytics_capture;
+mod client;
+mod events;
+mod facts;
+mod guardian_v2;
+mod reducer;
+mod thread_hint;
+
+use std::time::SystemTime;
+use std::time::UNIX_EPOCH;
+
+pub use accepted_lines::fingerprint_hash;
+pub use client::AnalyticsEventsClient;
+pub use events::AppServerRpcTransport;
+pub use events::GuardianAdditionalPermissions;
+pub use events::GuardianApprovalRequestSource;
+pub use events::GuardianReviewAnalyticsResult;
+pub use events::GuardianReviewDecision;
+pub use events::GuardianReviewEventParams;
+pub use events::GuardianReviewFailureReason;
+pub use events::GuardianReviewSessionAnalyticsParams;
+pub use events::GuardianReviewSessionKind;
+pub use events::GuardianReviewTerminalStatus;
+pub use events::GuardianReviewTrackContext;
+pub use events::GuardianReviewedAction;
+pub use facts::AnalyticsJsonRpcError;
+pub use facts::AppInvocation;
+pub use facts::ArtifactOperation;
+pub use facts::ArtifactOperationLifecycle;
+pub use facts::CodeModeToolCallFact;
+pub use facts::CodeModeToolCallStatus;
+pub use facts::CodexCompactionEvent;
+pub use facts::CodexErrKind;
+pub use facts::CodexGoalEvent;
+pub use facts::CodexTurnSteerEvent;
+pub use facts::CompactionImplementation;
+pub use facts::CompactionPhase;
+pub use facts::CompactionReason;
+pub use facts::CompactionStatus;
+pub use facts::CompactionStrategy;
+pub use facts::CompactionTrigger;
+pub use facts::ControlToolCallFact;
+pub use facts::ControlToolCallStatus;
+pub use facts::ElicitationType;
+pub use facts::ExternalAgentConfigImportCompletedInput;
+pub use facts::ExternalAgentConfigImportFailureInput;
+pub use facts::GoalEventKind;
+pub use facts::HookRunFact;
+pub use facts::ImageDetailSetting;
+pub use facts::ImagePreparationFact;
+pub use facts::ImagePreparationMetadata;
+pub use facts::InputError;
+pub use facts::InvocationType;
+pub use facts::McpToolCallElicitation;
+pub use facts::PluginInstallRequestSource;
+pub use facts::PluginInstallRequested;
+pub use facts::PluginInstallRequestedPlugin;
+pub use facts::PluginInstallSource;
+pub use facts::PluginMeasurementRow;
+pub use facts::PluginMeasurementsInput;
+pub use facts::SkillInvocation;
+pub use facts::SkillInvocationLocation;
+pub use facts::SubAgentThreadStartedInput;
+pub use facts::ThreadInitializationMode;
+pub use facts::TrackEventsContext;
+pub use facts::TurnAnalyticsMetadata;
+pub use facts::TurnCodexErrorFact;
+pub use facts::TurnProfile;
+pub use facts::TurnProfileFact;
+pub use facts::TurnResolvedConfigFact;
+pub use facts::TurnStatus;
+pub use facts::TurnSteerRejectionReason;
+pub use facts::TurnSteerRequestError;
+pub use facts::TurnSteerResult;
+pub use facts::TurnTokenUsageFact;
+pub use facts::build_track_events_context;
+pub use guardian_v2::GuardianV2Event;
+pub use guardian_v2::GuardianV2EventKind;
+pub use thread_hint::ThreadHintStatus;
+pub use thread_hint::ThreadHintStatusEvent;
+
+#[cfg(test)]
+mod analytics_client_tests;
+
+pub fn now_unix_seconds() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_secs()
+}
+
+pub fn now_unix_millis() -> u64 {
+    u64::try_from(
+        SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_millis(),
+    )
+    .unwrap_or(u64::MAX)
+}
+
+pub(crate) fn serialize_enum_as_string<T: serde::Serialize>(value: &T) -> Option<String> {
+    serde_json::to_value(value)
+        .ok()
+        .and_then(|value| value.as_str().map(str::to_string))
+}
+
+pub(crate) fn usize_to_u64(value: usize) -> u64 {
+    u64::try_from(value).unwrap_or(u64::MAX)
+}
+
+pub(crate) fn option_i64_to_u64(value: Option<i64>) -> Option<u64> {
+    value.and_then(|value| u64::try_from(value).ok())
+}

codex-rs/analytics/src/thread_hint.rs

@@ -0,0 +1,38 @@
+//! Per-attempt thread hint status analytics without hint contents.
+
+use crate::events::CodexAppServerClientMetadata;
+use crate::events::CodexRuntimeMetadata;
+use codex_protocol::protocol::ThreadSource;
+use serde::Serialize;
+
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ThreadHintStatus {
+    Succeeded,
+    Failed,
+}
+
+pub struct ThreadHintStatusEvent {
+    pub thread_id: String,
+    pub status: ThreadHintStatus,
+    pub occurred_at_ms: u64,
+}
+
+#[derive(Serialize)]
+pub(crate) struct ThreadHintStatusEventRequest {
+    pub(crate) event_type: &'static str,
+    pub(crate) event_params: ThreadHintStatusEventParams,
+}
+
+#[derive(Serialize)]
+pub(crate) struct ThreadHintStatusEventParams {
+    pub(crate) thread_id: String,
+    pub(crate) session_id: String,
+    pub(crate) app_server_client: CodexAppServerClientMetadata,
+    pub(crate) runtime: CodexRuntimeMetadata,
+    pub(crate) thread_source: Option<ThreadSource>,
+    pub(crate) subagent_source: Option<String>,
+    pub(crate) parent_thread_id: Option<String>,
+    pub(crate) status: ThreadHintStatus,
+    pub(crate) occurred_at_ms: u64,
+}

codex-rs/app-server-daemon/src/backend/mod.rs

@@ -0,0 +1,52 @@
+mod pid;
+#[cfg(windows)]
+pub(crate) mod windows;
+
+use std::path::Path;
+use std::path::PathBuf;
+
+use serde::Serialize;
+
+pub(crate) use pid::PidBackend;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub enum BackendKind {
+    Pid,
+}
+
+#[derive(Debug, Clone)]
+pub(crate) struct BackendPaths {
+    pub(crate) codex_bin: PathBuf,
+    pub(crate) pid_file: PathBuf,
+    pub(crate) update_pid_file: PathBuf,
+    pub(crate) remote_control_enabled: bool,
+}
+
+pub(crate) fn pid_backend(paths: BackendPaths) -> PidBackend {
+    PidBackend::new(
+        paths.codex_bin,
+        paths.pid_file,
+        paths.remote_control_enabled,
+    )
+}
+
+pub(crate) fn pid_update_loop_backend(paths: BackendPaths) -> PidBackend {
+    PidBackend::new_update_loop(
+        paths.codex_bin,
+        paths.update_pid_file,
+        /*restore_release*/ None,
+    )
+}
+
+pub(crate) async fn append_stderr_log_tail_context(pid_file: &Path, context: &mut String) {
+    match pid::read_stderr_log_tail(pid_file).await {
+        Ok(Some(tail)) => tail.append_to_context(context),
+        Ok(None) => {}
+        Err(err) => {
+            context.push_str(&format!(
+                "\n\nFailed to read managed app-server stderr log: {err:#}"
+            ));
+        }
+    }
+}

codex-rs/app-server-daemon/src/backend/pid.rs

@@ -0,0 +1,774 @@
+//! PID reservations serialize detached launches; process identities protect stale-record cleanup.
+
+#[path = "pid_identity.rs"]
+mod identity;
+
+use std::io::SeekFrom;
+use std::path::Path;
+use std::path::PathBuf;
+use std::time::Duration;
+
+use crate::managed_install::ExecutableIdentity;
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::bail;
+#[cfg(any(unix, windows))]
+use codex_app_server_transport::REMOTE_CONTROL_DISABLED_ENV_VAR;
+use serde::Deserialize;
+use serde::Serialize;
+use tokio::fs;
+use tokio::io::AsyncReadExt;
+use tokio::io::AsyncSeekExt;
+#[cfg(unix)]
+use tokio::process::Command;
+use tokio::time::sleep;
+
+use crate::settings::DEFAULT_SHUTDOWN_GRACE_SECONDS;
+
+const STOP_POLL_INTERVAL: Duration = Duration::from_millis(50);
+const STOP_FORCE_TIMEOUT: Duration = Duration::from_secs(10);
+const START_TIMEOUT: Duration = Duration::from_secs(10);
+const STDERR_LOG_TAIL_BYTES: u64 = 4096;
+
+#[derive(Debug)]
+#[cfg_attr(not(any(unix, windows)), allow(dead_code))]
+pub(crate) struct PidBackend {
+    codex_bin: PathBuf,
+    pid_file: PathBuf,
+    lock_file: PathBuf,
+    command_kind: PidCommandKind,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct PidRecord {
+    pid: u32,
+    // Keep the legacy timestamp for older CLI/updater versions reading this record.
+    process_start_time: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[serde(alias = "linuxProcessIdentity")]
+    process_identity: Option<identity::ProcessIdentity>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    executable_identity: Option<ExecutableIdentity>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct PidLogTail {
+    pub(crate) path: PathBuf,
+    pub(crate) contents: String,
+}
+
+impl PidLogTail {
+    pub(crate) fn append_to_context(&self, context: &mut String) {
+        context.push_str(&format!(
+            "\n\nManaged app-server stderr ({}):",
+            self.path.display()
+        ));
+        for line in self.contents.lines() {
+            context.push_str("\n  ");
+            context.push_str(line);
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+enum PidFileState {
+    Missing,
+    Starting,
+    Running(PidRecord),
+}
+
+#[derive(Debug, Clone)]
+#[cfg_attr(not(any(unix, windows)), allow(dead_code))]
+enum PidCommandKind {
+    AppServer { remote_control_enabled: bool },
+    UpdateLoop { restore_release: Option<String> },
+}
+
+impl PidBackend {
+    pub(crate) async fn running_executable_identity(&self) -> Result<Option<ExecutableIdentity>> {
+        match self.read_pid_file_state().await? {
+            PidFileState::Running(record) if self.record_is_active(&record).await? => {
+                Ok(record.executable_identity)
+            }
+            _ => Ok(None),
+        }
+    }
+
+    pub(crate) fn new(codex_bin: PathBuf, pid_file: PathBuf, remote_control_enabled: bool) -> Self {
+        let lock_file = pid_file.with_extension("pid.lock");
+        Self {
+            codex_bin,
+            pid_file,
+            lock_file,
+            command_kind: PidCommandKind::AppServer {
+                remote_control_enabled,
+            },
+        }
+    }
+
+    pub(crate) fn new_update_loop(
+        codex_bin: PathBuf,
+        pid_file: PathBuf,
+        restore_release: Option<String>,
+    ) -> Self {
+        let lock_file = pid_file.with_extension("pid.lock");
+        Self {
+            codex_bin,
+            pid_file,
+            lock_file,
+            command_kind: PidCommandKind::UpdateLoop { restore_release },
+        }
+    }
+
+    pub(crate) async fn is_starting_or_running(&self) -> Result<bool> {
+        loop {
+            match self.read_pid_file_state().await? {
+                PidFileState::Missing => return Ok(false),
+                PidFileState::Starting => return Ok(true),
+                PidFileState::Running(record) => {
+                    if self.record_is_active(&record).await? {
+                        return Ok(true);
+                    }
+                    match self.refresh_after_stale_record(&record).await? {
+                        PidFileState::Missing => return Ok(false),
+                        PidFileState::Starting | PidFileState::Running(_) => continue,
+                    }
+                }
+            }
+        }
+    }
+
+    #[cfg(any(unix, windows))]
+    pub(crate) async fn start(&self) -> Result<Option<u32>> {
+        self.start_inner(/*replacement*/ None).await
+    }
+
+    #[cfg(not(any(unix, windows)))]
+    pub(crate) async fn start(&self) -> Result<Option<u32>> {
+        bail!("pid-managed app-server startup is unsupported on this platform")
+    }
+
+    pub(crate) async fn stop(&self) -> Result<()> {
+        self.stop_with_grace(DEFAULT_SHUTDOWN_GRACE_SECONDS).await
+    }
+
+    pub(crate) async fn stop_with_grace(&self, grace_seconds: u32) -> Result<()> {
+        loop {
+            let Some(record) = self.wait_for_pid_start().await? else {
+                return Ok(());
+            };
+            if !self.record_is_active(&record).await? {
+                match self.refresh_after_stale_record(&record).await? {
+                    PidFileState::Missing => return Ok(()),
+                    PidFileState::Starting | PidFileState::Running(_) => continue,
+                }
+            }
+
+            let pid = record.pid;
+            let started_at = tokio::time::Instant::now();
+            let force_after = Duration::from_secs(grace_seconds.into());
+            let deadline = started_at + force_after + STOP_FORCE_TIMEOUT;
+            #[cfg(unix)]
+            self.terminate_process(pid)?;
+            #[cfg(windows)]
+            let process = {
+                let Some(process) = super::windows::Process::open(pid)? else {
+                    continue;
+                };
+                if process.start_time()? != record.process_start_time {
+                    continue;
+                }
+                match self.command_kind {
+                    PidCommandKind::AppServer { .. } => {
+                        let codex_home = self
+                            .pid_file
+                            .parent()
+                            .and_then(Path::parent)
+                            .context("daemon pid path has no Codex home")?;
+                        let socket_path =
+                            codex_app_server_transport::app_server_control_socket_path(codex_home)?;
+                        if let Err(err) =
+                            crate::client::request_shutdown(socket_path.as_path(), pid).await
+                        {
+                            tracing::warn!(%pid, %err, "managed app-server shutdown request failed; waiting for force deadline");
+                        }
+                    }
+                    PidCommandKind::UpdateLoop { .. } => {
+                        fs::write(self.pid_file.with_extension("shutdown"), pid.to_string())
+                            .await
+                            .context("failed to request updater shutdown")?;
+                    }
+                }
+                process
+            };
+            let mut forced = false;
+            loop {
+                #[cfg(unix)]
+                if let Ok(raw_pid) = libc::pid_t::try_from(pid)
+                    && raw_pid > 0
+                {
+                    // A previous updater may have started this child; reap it if it has exited.
+                    unsafe { libc::waitpid(raw_pid, std::ptr::null_mut(), libc::WNOHANG) };
+                }
+                if !self.record_is_active(&record).await? {
+                    match self.refresh_after_stale_record(&record).await? {
+                        PidFileState::Missing => return Ok(()),
+                        PidFileState::Starting | PidFileState::Running(_) => break,
+                    }
+                }
+                if tokio::time::Instant::now() >= deadline {
+                    break;
+                }
+                if !forced && started_at.elapsed() >= force_after {
+                    #[cfg(unix)]
+                    self.force_terminate_process(pid)?;
+                    #[cfg(windows)]
+                    process.terminate()?;
+                    forced = true;
+                }
+                sleep(STOP_POLL_INTERVAL).await;
+            }
+
+            if self.record_is_active(&record).await? {
+                bail!("timed out waiting for pid-managed app server {pid} to stop");
+            }
+        }
+    }
+
+    async fn wait_for_pid_start(&self) -> Result<Option<PidRecord>> {
+        let deadline = tokio::time::Instant::now() + START_TIMEOUT;
+        loop {
+            match self.read_pid_file_state().await? {
+                PidFileState::Missing => return Ok(None),
+                PidFileState::Running(record) => return Ok(Some(record)),
+                PidFileState::Starting if tokio::time::Instant::now() < deadline => {
+                    sleep(STOP_POLL_INTERVAL).await;
+                }
+                PidFileState::Starting => {
+                    bail!(
+                        "timed out waiting for pid reservation in {} to finish initializing",
+                        self.pid_file.display()
+                    );
+                }
+            }
+        }
+    }
+
+    async fn read_pid_file_state(&self) -> Result<PidFileState> {
+        let contents = match fs::read_to_string(&self.pid_file).await {
+            Ok(contents) => contents,
+            Err(err) if err.kind() == std::io::ErrorKind::NotFound => {
+                return if reservation_lock_is_active(&self.lock_file).await? {
+                    Ok(PidFileState::Starting)
+                } else {
+                    Ok(PidFileState::Missing)
+                };
+            }
+            Err(err) => {
+                return Err(err).with_context(|| {
+                    format!("failed to read pid file {}", self.pid_file.display())
+                });
+            }
+        };
+        if contents.trim().is_empty() {
+            match inspect_empty_pid_reservation(&self.pid_file, &self.lock_file).await? {
+                EmptyPidReservation::Active => {
+                    return Ok(PidFileState::Starting);
+                }
+                EmptyPidReservation::Stale => {
+                    return Ok(PidFileState::Missing);
+                }
+                EmptyPidReservation::Record(record) => return Ok(PidFileState::Running(record)),
+            }
+        }
+        let record = serde_json::from_str(&contents)
+            .with_context(|| format!("invalid pid file contents in {}", self.pid_file.display()))?;
+        Ok(PidFileState::Running(record))
+    }
+
+    async fn read_pid_file_state_with_lock_held(&self) -> Result<PidFileState> {
+        let contents = match fs::read_to_string(&self.pid_file).await {
+            Ok(contents) => contents,
+            Err(err) if err.kind() == std::io::ErrorKind::NotFound => {
+                return Ok(PidFileState::Missing);
+            }
+            Err(err) => {
+                return Err(err).with_context(|| {
+                    format!("failed to read pid file {}", self.pid_file.display())
+                });
+            }
+        };
+        if contents.trim().is_empty() {
+            let _ = fs::remove_file(&self.pid_file).await;
+            return Ok(PidFileState::Missing);
+        }
+        let record = serde_json::from_str(&contents)
+            .with_context(|| format!("invalid pid file contents in {}", self.pid_file.display()))?;
+        Ok(PidFileState::Running(record))
+    }
+
+    async fn refresh_after_stale_record(&self, expected: &PidRecord) -> Result<PidFileState> {
+        let reservation_lock = self.acquire_reservation_lock().await?;
+        let state = match self.read_pid_file_state_with_lock_held().await? {
+            PidFileState::Running(record) if record == *expected => {
+                let _ = fs::remove_file(&self.pid_file).await;
+                PidFileState::Missing
+            }
+            state => state,
+        };
+        drop(reservation_lock);
+        Ok(state)
+    }
+
+    async fn acquire_reservation_lock(&self) -> Result<fs::File> {
+        let reservation_lock = fs::OpenOptions::new()
+            .create(true)
+            .truncate(false)
+            .write(true)
+            .open(&self.lock_file)
+            .await
+            .with_context(|| {
+                format!("failed to open pid lock file {}", self.lock_file.display())
+            })?;
+        let lock_deadline = tokio::time::Instant::now() + START_TIMEOUT;
+        while !try_lock_file(&reservation_lock)? {
+            if tokio::time::Instant::now() >= lock_deadline {
+                bail!(
+                    "timed out waiting for pid lock {}",
+                    self.lock_file.display()
+                );
+            }
+            sleep(STOP_POLL_INTERVAL).await;
+        }
+        Ok(reservation_lock)
+    }
+
+    #[cfg(any(unix, windows))]
+    async fn open_stderr_log(&self) -> Result<fs::File> {
+        let stderr_log_file = stderr_log_file_for_pid_file(&self.pid_file);
+        fs::OpenOptions::new()
+            .create(true)
+            .truncate(true)
+            .write(true)
+            .open(&stderr_log_file)
+            .await
+            .with_context(|| {
+                format!(
+                    "failed to open stderr log for pid-managed app server {}",
+                    stderr_log_file.display()
+                )
+            })
+    }
+
+    #[cfg(any(unix, windows))]
+    fn command_args(&self) -> Vec<&str> {
+        match &self.command_kind {
+            PidCommandKind::AppServer {
+                remote_control_enabled: true,
+            } => vec!["app-server", "--remote-control", "--listen", "unix://"],
+            PidCommandKind::AppServer {
+                remote_control_enabled: false,
+            } => vec!["app-server", "--listen", "unix://"],
+            PidCommandKind::UpdateLoop { restore_release } => {
+                let mut args = vec!["app-server", "daemon", "pid-update-loop"];
+                if let Some(release) = restore_release {
+                    args.extend(["--restore-release", release.as_str()]);
+                }
+                args
+            }
+        }
+    }
+
+    #[cfg(any(unix, windows))]
+    fn command_env(&self) -> Option<(&'static str, &'static str)> {
+        match self.command_kind {
+            PidCommandKind::AppServer {
+                remote_control_enabled: false,
+            } => Some((REMOTE_CONTROL_DISABLED_ENV_VAR, "1")),
+            PidCommandKind::AppServer {
+                remote_control_enabled: true,
+            }
+            | PidCommandKind::UpdateLoop { .. } => None,
+        }
+    }
+
+    fn terminate_process(&self, pid: u32) -> Result<()> {
+        match self.command_kind {
+            PidCommandKind::AppServer { .. } => terminate_process(pid),
+            #[cfg(unix)]
+            PidCommandKind::UpdateLoop { .. } => terminate_process_group(pid),
+            #[cfg(not(unix))]
+            PidCommandKind::UpdateLoop { .. } => terminate_process(pid),
+        }
+    }
+
+    #[cfg(not(windows))]
+    fn force_terminate_process(&self, pid: u32) -> Result<()> {
+        match self.command_kind {
+            PidCommandKind::AppServer { .. } => force_terminate_process(pid),
+            PidCommandKind::UpdateLoop { .. } => force_terminate_process_group(pid),
+        }
+    }
+
+    async fn record_is_active(&self, record: &PidRecord) -> Result<bool> {
+        process_matches_record(record).await
+    }
+}
+
+pub(crate) async fn read_stderr_log_tail(pid_file: &Path) -> Result<Option<PidLogTail>> {
+    let path = stderr_log_file_for_pid_file(pid_file);
+    let Some(contents) = read_log_tail(&path, STDERR_LOG_TAIL_BYTES).await? else {
+        return Ok(None);
+    };
+    Ok(Some(PidLogTail { path, contents }))
+}
+
+fn stderr_log_file_for_pid_file(pid_file: &Path) -> PathBuf {
+    pid_file.with_extension("stderr.log")
+}
+
+async fn read_log_tail(path: &Path, byte_limit: u64) -> Result<Option<String>> {
+    let mut file = match fs::File::open(path).await {
+        Ok(file) => file,
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => return Ok(None),
+        Err(err) => {
+            return Err(err)
+                .with_context(|| format!("failed to open stderr log {}", path.display()));
+        }
+    };
+    let len = file
+        .metadata()
+        .await
+        .with_context(|| format!("failed to inspect stderr log {}", path.display()))?
+        .len();
+    if len == 0 {
+        return Ok(None);
+    }
+
+    let start = len.saturating_sub(byte_limit);
+    file.seek(SeekFrom::Start(start))
+        .await
+        .with_context(|| format!("failed to seek stderr log {}", path.display()))?;
+    let mut bytes = Vec::new();
+    file.read_to_end(&mut bytes)
+        .await
+        .with_context(|| format!("failed to read stderr log {}", path.display()))?;
+    if start > 0
+        && let Some(newline_index) = bytes.iter().position(|byte| *byte == b'\n')
+    {
+        bytes.drain(..=newline_index);
+    }
+    let contents = String::from_utf8_lossy(&bytes).trim_end().to_string();
+    if contents.is_empty() {
+        return Ok(None);
+    }
+    Ok(Some(contents))
+}
+
+#[cfg(unix)]
+fn process_exists(pid: u32) -> bool {
+    let Ok(pid) = libc::pid_t::try_from(pid) else {
+        return false;
+    };
+    let result = unsafe { libc::kill(pid, 0) };
+    result == 0 || std::io::Error::last_os_error().raw_os_error() == Some(libc::EPERM)
+}
+
+#[cfg(unix)]
+fn terminate_process(pid: u32) -> Result<()> {
+    let raw_pid = libc::pid_t::try_from(pid)
+        .with_context(|| format!("pid-managed app server pid {pid} is out of range"))?;
+    let result = unsafe { libc::kill(raw_pid, libc::SIGTERM) };
+    if result == 0 {
+        return Ok(());
+    }
+    let err = std::io::Error::last_os_error();
+    if err.raw_os_error() == Some(libc::ESRCH) {
+        return Ok(());
+    }
+    Err(err).with_context(|| format!("failed to terminate pid-managed app server {pid}"))
+}
+
+#[cfg(unix)]
+fn force_terminate_process(pid: u32) -> Result<()> {
+    let raw_pid = libc::pid_t::try_from(pid)
+        .with_context(|| format!("pid-managed app server pid {pid} is out of range"))?;
+    let result = unsafe { libc::kill(raw_pid, libc::SIGKILL) };
+    if result == 0 {
+        return Ok(());
+    }
+    let err = std::io::Error::last_os_error();
+    if err.raw_os_error() == Some(libc::ESRCH) {
+        return Ok(());
+    }
+    Err(err).with_context(|| format!("failed to force terminate pid-managed app server {pid}"))
+}
+
+#[cfg(unix)]
+fn terminate_process_group(pid: u32) -> Result<()> {
+    let raw_pid = libc::pid_t::try_from(pid)
+        .with_context(|| format!("pid-managed updater pid {pid} is out of range"))?;
+    let result = unsafe { libc::kill(-raw_pid, libc::SIGTERM) };
+    if result == 0 {
+        return Ok(());
+    }
+    let err = std::io::Error::last_os_error();
+    if err.raw_os_error() == Some(libc::ESRCH) {
+        return Ok(());
+    }
+    Err(err).with_context(|| format!("failed to terminate pid-managed updater group {pid}"))
+}
+
+#[cfg(unix)]
+fn force_terminate_process_group(pid: u32) -> Result<()> {
+    let raw_pid = libc::pid_t::try_from(pid)
+        .with_context(|| format!("pid-managed updater pid {pid} is out of range"))?;
+    let result = unsafe { libc::kill(-raw_pid, libc::SIGKILL) };
+    if result == 0 {
+        return Ok(());
+    }
+    let err = std::io::Error::last_os_error();
+    if err.raw_os_error() == Some(libc::ESRCH) {
+        return Ok(());
+    }
+    Err(err).with_context(|| format!("failed to force terminate pid-managed updater group {pid}"))
+}
+
+#[cfg(not(any(unix, windows)))]
+fn terminate_process(_pid: u32) -> Result<()> {
+    bail!("pid-managed app-server shutdown is unsupported on this platform")
+}
+
+#[cfg(not(any(unix, windows)))]
+fn force_terminate_process(_pid: u32) -> Result<()> {
+    bail!("pid-managed app-server shutdown is unsupported on this platform")
+}
+
+#[cfg(not(any(unix, windows)))]
+fn force_terminate_process_group(_pid: u32) -> Result<()> {
+    bail!("pid-managed updater shutdown is unsupported on this platform")
+}
+
+#[cfg(unix)]
+async fn process_matches_record(record: &PidRecord) -> Result<bool> {
+    if !process_exists(record.pid) {
+        return Ok(false);
+    }
+
+    let details = async {
+        #[cfg(any(target_os = "linux", target_os = "macos"))]
+        if let Some(expected) = &record.process_identity {
+            return expected.matches_process(record.pid).await;
+        }
+        let (state, start_time) = read_process_details(record.pid).await?;
+        let matches = start_time == record.process_start_time;
+        let is_zombie = state.starts_with('Z');
+        if !matches && !is_zombie {
+            bail!(
+                "cannot verify pid-managed process {}: legacy start time changed; PID record retained. \
+                 Retry with the locale and timezone used to start the daemon. If the system clock \
+                 changed, stop the original process before restarting the daemon",
+                record.pid
+            );
+        }
+        Ok((is_zombie, matches))
+    }
+    .await;
+    match details {
+        Ok((is_zombie, matches)) => {
+            // An unreaped zombie still passes kill(pid, 0) and retains its start
+            // time, but it can no longer run the app-server or updater.
+            if is_zombie {
+                if matches && let Ok(raw_pid) = libc::pid_t::try_from(record.pid) {
+                    // Re-exec can lose the Child handle without changing parenthood.
+                    unsafe { libc::waitpid(raw_pid, std::ptr::null_mut(), libc::WNOHANG) };
+                }
+                return Ok(false);
+            }
+            Ok(matches)
+        }
+        Err(_err) if !process_exists(record.pid) => Ok(false),
+        Err(err) => Err(err),
+    }
+}
+
+#[cfg(not(any(unix, windows)))]
+async fn process_matches_record(_record: &PidRecord) -> Result<bool> {
+    Ok(false)
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+#[cfg_attr(not(any(unix, windows)), allow(dead_code))]
+enum EmptyPidReservation {
+    Active,
+    Stale,
+    Record(PidRecord),
+}
+
+#[cfg(unix)]
+fn try_lock_file(file: &fs::File) -> Result<bool> {
+    use std::os::fd::AsRawFd;
+
+    let result = unsafe { libc::flock(file.as_raw_fd(), libc::LOCK_EX | libc::LOCK_NB) };
+    if result == 0 {
+        return Ok(true);
+    }
+
+    let err = std::io::Error::last_os_error();
+    if err.raw_os_error() == Some(libc::EWOULDBLOCK) {
+        return Ok(false);
+    }
+    Err(err).context("failed to lock pid reservation")
+}
+
+#[cfg(not(any(unix, windows)))]
+fn try_lock_file(_file: &fs::File) -> Result<bool> {
+    bail!("pid-managed app-server startup is unsupported on this platform")
+}
+
+#[cfg(any(unix, windows))]
+async fn reservation_lock_is_active(path: &Path) -> Result<bool> {
+    let file = match fs::OpenOptions::new()
+        .write(true)
+        .create(true)
+        .truncate(false)
+        .open(path)
+        .await
+    {
+        Ok(file) => file,
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => {
+            return Ok(false);
+        }
+        Err(err) => {
+            return Err(err)
+                .with_context(|| format!("failed to inspect pid lock file {}", path.display()));
+        }
+    };
+    Ok(!try_lock_file(&file)?)
+}
+
+#[cfg(not(any(unix, windows)))]
+async fn reservation_lock_is_active(_path: &Path) -> Result<bool> {
+    Ok(false)
+}
+
+#[cfg(any(unix, windows))]
+async fn inspect_empty_pid_reservation(
+    pid_path: &Path,
+    lock_path: &Path,
+) -> Result<EmptyPidReservation> {
+    let file = match fs::OpenOptions::new()
+        .write(true)
+        .create(true)
+        .truncate(false)
+        .open(lock_path)
+        .await
+    {
+        Ok(file) => file,
+        Err(err) => {
+            return Err(err).with_context(|| {
+                format!("failed to inspect pid lock file {}", lock_path.display())
+            });
+        }
+    };
+    if !try_lock_file(&file)? {
+        return Ok(EmptyPidReservation::Active);
+    }
+
+    let contents = match fs::read_to_string(pid_path).await {
+        Ok(contents) => contents,
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => {
+            return Ok(EmptyPidReservation::Stale);
+        }
+        Err(err) => {
+            return Err(err)
+                .with_context(|| format!("failed to reread pid file {}", pid_path.display()));
+        }
+    };
+    if contents.trim().is_empty() {
+        let _ = fs::remove_file(pid_path).await;
+        return Ok(EmptyPidReservation::Stale);
+    }
+
+    let record = serde_json::from_str(&contents)
+        .with_context(|| format!("invalid pid file contents in {}", pid_path.display()))?;
+    Ok(EmptyPidReservation::Record(record))
+}
+
+#[cfg(not(any(unix, windows)))]
+async fn inspect_empty_pid_reservation(
+    _pid_path: &Path,
+    _lock_path: &Path,
+) -> Result<EmptyPidReservation> {
+    Ok(EmptyPidReservation::Stale)
+}
+
+#[cfg(unix)]
+async fn read_process_start_time(pid: u32) -> Result<String> {
+    Ok(read_process_details(pid).await?.1)
+}
+
+#[cfg(unix)]
+async fn read_process_details(pid: u32) -> Result<(String, String)> {
+    let output = Command::new("ps")
+        .args(["-p", &pid.to_string(), "-o", "stat=", "-o", "lstart="])
+        .output()
+        .await
+        .context("failed to invoke ps for pid-managed app server")?;
+    if !output.status.success() {
+        bail!("failed to read start time for pid-managed app server {pid}");
+    }
+
+    let details = String::from_utf8(output.stdout)
+        .context("pid-managed app server process details were not utf-8")?;
+    let Some((state, start_time)) = details.trim().split_once(char::is_whitespace) else {
+        bail!("pid-managed app server {pid} has no recorded start time");
+    };
+    let start_time = start_time.trim();
+    if start_time.is_empty() {
+        bail!("pid-managed app server {pid} has no recorded start time");
+    }
+    Ok((state.to_string(), start_time.to_string()))
+}
+
+#[cfg(all(test, any(unix, windows)))]
+#[path = "pid_tests.rs"]
+mod tests;
+
+#[cfg(windows)]
+use super::windows::try_lock_file;
+
+#[cfg(windows)]
+async fn read_process_start_time(pid: u32) -> Result<String> {
+    super::windows::Process::open(pid)?
+        .context("daemon process exited during startup")?
+        .start_time()
+}
+
+#[cfg(windows)]
+async fn process_matches_record(record: &PidRecord) -> Result<bool> {
+    let Some(process) = super::windows::Process::open(record.pid)? else {
+        return Ok(false);
+    };
+    Ok(process.is_running()? && process.start_time()? == record.process_start_time)
+}
+
+#[cfg(windows)]
+fn force_terminate_process(pid: u32) -> Result<()> {
+    if let Some(process) = super::windows::Process::open(pid)? {
+        process.terminate()?;
+    }
+    Ok(())
+}
+
+#[cfg(windows)]
+use force_terminate_process as terminate_process;
+
+#[cfg(windows)]
+#[path = "pid_windows.rs"]
+mod windows;
+
+#[cfg(any(unix, windows))]
+#[path = "pid_start.rs"]
+mod start;

codex-rs/app-server-daemon/src/backend/pid_identity.rs

@@ -0,0 +1,242 @@
+//! Native process identities and zombie state, independent of locale and timezone.
+//! Boot IDs prevent records surviving reboot from matching reused process identifiers.
+
+#[cfg(any(target_os = "linux", target_os = "macos", test))]
+use anyhow::Context;
+#[cfg(any(target_os = "linux", target_os = "macos", test))]
+use anyhow::Result;
+use serde::Deserialize;
+use serde::Serialize;
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(untagged, rename_all_fields = "camelCase")]
+pub(super) enum ProcessIdentity {
+    Linux {
+        boot_id: String,
+        start_ticks: u64,
+    },
+    // Untagged decoding must try this before the timestamp-only MacOs variant.
+    MacOsUnique {
+        boot_id: String,
+        unique_id: u64,
+        start_seconds: u64,
+        start_microseconds: u64,
+    },
+    MacOs {
+        start_seconds: u64,
+        start_microseconds: u64,
+    },
+}
+
+#[cfg(any(target_os = "linux", target_os = "macos"))]
+impl ProcessIdentity {
+    pub(super) async fn matches_process(&self, pid: u32) -> Result<(bool, bool)> {
+        // A different boot proves staleness even when the reused PID is inaccessible.
+        if let Self::Linux { boot_id, .. } | Self::MacOsUnique { boot_id, .. } = self
+            && *boot_id != read_boot_id().await?
+        {
+            return Ok((false, false));
+        }
+        #[cfg(target_os = "macos")]
+        if let Self::MacOsUnique { unique_id, .. } = self
+            && *unique_id != read_unique_id(pid)?
+        {
+            return Ok((false, false));
+        }
+        let (is_zombie, actual) = read_process_details(pid).await?;
+        let matches = if let (
+            // Timestamp-only native records predate the cross-user identity check.
+            Self::MacOs {
+                start_seconds,
+                start_microseconds,
+            },
+            Self::MacOsUnique {
+                start_seconds: actual_seconds,
+                start_microseconds: actual_microseconds,
+                ..
+            },
+        ) = (self, &actual)
+        {
+            start_seconds == actual_seconds && start_microseconds == actual_microseconds
+        } else {
+            *self == actual
+        };
+        Ok((is_zombie, matches))
+    }
+}
+
+#[cfg(any(target_os = "linux", target_os = "macos"))]
+impl super::PidBackend {
+    pub(crate) async fn promote_legacy_identity(&self) -> Result<()> {
+        let _reservation = self.acquire_reservation_lock().await?;
+        let super::PidFileState::Running(mut record) =
+            self.read_pid_file_state_with_lock_held().await?
+        else {
+            return Ok(());
+        };
+        if matches!(
+            record.process_identity,
+            Some(ProcessIdentity::Linux { .. } | ProcessIdentity::MacOsUnique { .. })
+        ) {
+            return Ok(());
+        }
+        // An updater keeps its PID across exec during upgrades. Only promote a
+        // legacy record while its original check still identifies the process,
+        // with the native identity unchanged on both sides of that check.
+        let before = read_process_details(record.pid).await?;
+        if before.0 || !super::process_matches_record(&record).await? {
+            return Ok(());
+        }
+        if read_process_details(record.pid).await? != before {
+            return Ok(());
+        }
+        record.process_identity = Some(before.1);
+        let temporary = self.pid_file.with_extension("pid.tmp");
+        tokio::fs::write(&temporary, serde_json::to_vec(&record)?).await?;
+        tokio::fs::rename(&temporary, &self.pid_file).await?;
+        Ok(())
+    }
+}
+
+#[cfg(target_os = "macos")]
+pub(super) async fn read_process_details(pid: u32) -> Result<(bool, ProcessIdentity)> {
+    let boot_id = read_boot_id().await?;
+    let unique_id = read_unique_id(pid)?;
+    let pid = libc::pid_t::try_from(pid).context("daemon pid is out of range")?;
+    let mut info = std::mem::MaybeUninit::<libc::proc_bsdinfo>::uninit();
+    let size = std::mem::size_of::<libc::proc_bsdinfo>() as libc::c_int;
+    // SAFETY: the buffer has the exact size and alignment required by this flavor.
+    // arg=1 includes zombies so callers can reap children that have exited.
+    let read = unsafe {
+        libc::proc_pidinfo(
+            pid,
+            libc::PROC_PIDTBSDINFO,
+            /*arg*/ 1,
+            info.as_mut_ptr().cast(),
+            size,
+        )
+    };
+    if read <= 0 {
+        return Err(std::io::Error::last_os_error())
+            .context("failed to read daemon process identity");
+    }
+    anyhow::ensure!(read == size, "incomplete daemon process identity");
+    // SAFETY: proc_pidinfo initialized the entire structure on success.
+    let info = unsafe { info.assume_init() };
+    anyhow::ensure!(
+        unique_id == read_unique_id(info.pbi_pid)?,
+        "daemon process changed while reading its identity"
+    );
+    Ok((
+        info.pbi_status == libc::SZOMB,
+        ProcessIdentity::MacOsUnique {
+            boot_id,
+            unique_id,
+            start_seconds: info.pbi_start_tvsec,
+            start_microseconds: info.pbi_start_tvusec,
+        },
+    ))
+}
+
+#[cfg(target_os = "macos")]
+fn read_unique_id(pid: u32) -> Result<u64> {
+    // XNU's proc_uniqidentifierinfo ABI (flavor 17), unchanged in size since 2013.
+    // Unlike PROC_PIDTBSDINFO, this query does not require matching process ownership.
+    #[repr(C)]
+    struct UniqueInfo {
+        executable_uuid: [u8; 16],
+        unique_id: u64,
+        parent_unique_id: u64,
+        reserved: [u64; 3],
+    }
+    let pid = libc::pid_t::try_from(pid).context("daemon pid is out of range")?;
+    let mut info = std::mem::MaybeUninit::<UniqueInfo>::uninit();
+    let size = std::mem::size_of::<UniqueInfo>() as libc::c_int;
+    // SAFETY: the buffer matches proc_uniqidentifierinfo's size and alignment.
+    let read = unsafe {
+        libc::proc_pidinfo(
+            pid,
+            /*flavor*/ 17,
+            /*arg*/ 1,
+            info.as_mut_ptr().cast(),
+            size,
+        )
+    };
+    if read <= 0 {
+        return Err(std::io::Error::last_os_error()).context("failed to read daemon unique ID");
+    }
+    anyhow::ensure!(read == size, "incomplete daemon unique ID");
+    // SAFETY: proc_pidinfo initialized the entire structure on success.
+    Ok(unsafe { info.assume_init() }.unique_id)
+}
+
+#[cfg(target_os = "macos")]
+async fn read_boot_id() -> Result<String> {
+    let mut buffer = [0u8; 37];
+    let mut size = buffer.len();
+    // SAFETY: the writable buffer has size bytes; the new-value pointer is null.
+    let result = unsafe {
+        libc::sysctlbyname(
+            c"kern.bootsessionuuid".as_ptr(),
+            buffer.as_mut_ptr().cast(),
+            &mut size,
+            std::ptr::null_mut(),
+            /*newlen*/ 0,
+        )
+    };
+    if result != 0 {
+        return Err(std::io::Error::last_os_error()).context("failed to read macOS boot ID");
+    }
+    anyhow::ensure!(size == buffer.len(), "incomplete macOS boot ID");
+    Ok(std::ffi::CStr::from_bytes_with_nul(&buffer)?
+        .to_str()?
+        .to_owned())
+}
+
+#[cfg(target_os = "linux")]
+pub(super) async fn read_process_details(pid: u32) -> Result<(bool, ProcessIdentity)> {
+    let stat = tokio::fs::read(format!("/proc/{pid}/stat"))
+        .await
+        .with_context(|| format!("failed to read process stat for pid-managed process {pid}"))?;
+    let (state, start_ticks) = parse_stat(&stat)?;
+    Ok((
+        state == "Z",
+        ProcessIdentity::Linux {
+            boot_id: read_boot_id().await?,
+            start_ticks,
+        },
+    ))
+}
+
+#[cfg(target_os = "linux")]
+async fn read_boot_id() -> Result<String> {
+    let boot_id = tokio::fs::read_to_string("/proc/sys/kernel/random/boot_id")
+        .await
+        .context("failed to read Linux boot ID")?;
+    let boot_id = boot_id.trim();
+    anyhow::ensure!(!boot_id.is_empty(), "Linux boot ID is empty");
+    Ok(boot_id.to_owned())
+}
+
+#[cfg(any(target_os = "linux", test))]
+fn parse_stat(stat: &[u8]) -> Result<(String, u64)> {
+    // comm (field 2) can contain spaces and closing parentheses. The final ')'
+    // terminates it; splitting the whole line on whitespace miscounts fields.
+    let end = stat
+        .iter()
+        .rposition(|byte| *byte == b')')
+        .context("process stat has no comm")?;
+    let fields = std::str::from_utf8(&stat[end + 1..]).context("invalid process stat fields")?;
+    let mut fields = fields.split_whitespace();
+    let state = fields.next().context("process stat has no state")?;
+    let start_ticks = fields
+        .nth(/*n*/ 18)
+        .context("process stat has no start time")?
+        .parse()
+        .context("process stat start time is invalid")?;
+    Ok((state.to_string(), start_ticks))
+}
+
+#[cfg(test)]
+#[path = "pid_identity_tests.rs"]
+mod tests;

codex-rs/app-server-daemon/src/backend/pid_identity_tests.rs

@@ -0,0 +1,89 @@
+use super::parse_stat;
+use pretty_assertions::assert_eq;
+
+#[test]
+fn parses_start_ticks_after_comm_with_spaces_and_parentheses() {
+    let stat =
+        b"123 (codex \xff) worker) S 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 987654321 20";
+    assert_eq!(parse_stat(stat).unwrap(), ("S".to_string(), 987654321));
+}
+
+#[test]
+fn reads_earlier_linux_identity_field() {
+    use crate::backend::pid::PidRecord;
+    let mut expected = serde_json::json!({
+        "pid": 42,
+        "processStartTime": "legacy timestamp",
+        "linuxProcessIdentity": {"bootId": "boot", "startTicks": 123},
+    });
+    let record: PidRecord = serde_json::from_value(expected.clone()).unwrap();
+    expected["processIdentity"] = expected
+        .as_object_mut()
+        .unwrap()
+        .remove("linuxProcessIdentity")
+        .unwrap();
+    assert_eq!(serde_json::to_value(record).unwrap(), expected);
+}
+
+#[cfg(any(target_os = "linux", target_os = "macos"))]
+#[tokio::test]
+async fn previous_boot_does_not_require_process_inspection() {
+    let (_, identity) = super::read_process_details(std::process::id())
+        .await
+        .unwrap();
+    let mut record = serde_json::to_value(identity).unwrap();
+    record["bootId"] = "previous boot".into();
+    let identity: super::ProcessIdentity = serde_json::from_value(record).unwrap();
+    // An invalid PID would make process inspection fail if it preceded the boot check.
+    assert_eq!(
+        identity.matches_process(u32::MAX).await.unwrap(),
+        (false, false)
+    );
+}
+
+#[cfg(target_os = "macos")]
+#[tokio::test]
+async fn reused_pid_can_belong_to_root() {
+    let (_, identity) = super::read_process_details(std::process::id())
+        .await
+        .unwrap();
+    // launchd is root-owned: PROC_PIDTBSDINFO returns EPERM for an ordinary caller.
+    assert_eq!(
+        identity.matches_process(/*pid*/ 1).await.unwrap(),
+        (false, false)
+    );
+}
+
+#[cfg(target_os = "macos")]
+#[tokio::test]
+async fn promotes_timestamp_only_macos_record() {
+    use crate::backend::pid::PidBackend;
+    use crate::backend::pid::PidRecord;
+
+    let temp = tempfile::TempDir::new().unwrap();
+    let path = temp.path().join("server.pid");
+    let (_, identity) = super::read_process_details(std::process::id())
+        .await
+        .unwrap();
+    let mut legacy = serde_json::to_value(&identity).unwrap();
+    legacy.as_object_mut().unwrap().remove("bootId");
+    legacy.as_object_mut().unwrap().remove("uniqueId");
+    let mut record = PidRecord {
+        pid: std::process::id(),
+        process_start_time: "unused legacy text".into(),
+        process_identity: Some(serde_json::from_value(legacy).unwrap()),
+        executable_identity: None,
+    };
+    std::fs::write(&path, serde_json::to_vec(&record).unwrap()).unwrap();
+    let backend = PidBackend::new(
+        temp.path().join("codex"),
+        path.clone(),
+        /*remote_control_enabled*/ false,
+    );
+    backend.promote_legacy_identity().await.unwrap();
+    record.process_identity = Some(identity);
+    assert_eq!(
+        serde_json::from_slice::<PidRecord>(&std::fs::read(path).unwrap()).unwrap(),
+        record,
+    );
+}

codex-rs/app-server-daemon/src/backend/pid_start.rs

@@ -0,0 +1,321 @@
+//! Detached process launch and PID publication. Hold the reservation lock until
+//! the record is published, and on Windows until an updater acknowledges startup.
+
+use super::PidBackend;
+#[cfg(windows)]
+use super::PidCommandKind;
+use super::PidFileState;
+use super::PidRecord;
+use super::read_process_start_time;
+use crate::managed_install::executable_identity;
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::bail;
+use std::process::Stdio;
+use tokio::fs;
+use tokio::process::Command;
+
+impl PidBackend {
+    pub(super) async fn start_inner(&self, replacement: Option<PidRecord>) -> Result<Option<u32>> {
+        #[cfg(windows)]
+        crate::backend::windows::ensure_not_elevated()?;
+        if let Some(parent) = self.pid_file.parent() {
+            codex_uds::prepare_private_socket_directory(parent)
+                .await
+                .with_context(|| format!("failed to create pid directory {}", parent.display()))?;
+        }
+        let reservation_lock = self.acquire_reservation_lock().await?;
+        loop {
+            match fs::OpenOptions::new()
+                .create_new(true)
+                .write(true)
+                .open(&self.pid_file)
+                .await
+            {
+                Ok(pid_file) => {
+                    drop(pid_file);
+                    break;
+                }
+                Err(err) if err.kind() == std::io::ErrorKind::AlreadyExists => {
+                    match self.read_pid_file_state_with_lock_held().await? {
+                        PidFileState::Missing => continue,
+                        PidFileState::Running(record) => {
+                            if replacement.as_ref() == Some(&record) {
+                                break;
+                            }
+                            if replacement.is_some() {
+                                if self.record_is_active(&record).await? {
+                                    bail!("updater ownership changed before handoff");
+                                }
+                                // A failed rollback may leave the dead successor's record.
+                                break;
+                            }
+                            if self.record_is_active(&record).await? {
+                                return Ok(None);
+                            }
+                            let _ = fs::remove_file(&self.pid_file).await;
+                            continue;
+                        }
+                        PidFileState::Starting => {
+                            unreachable!("lock holder cannot observe starting")
+                        }
+                    }
+                }
+                Err(err) => {
+                    return Err(err).with_context(|| {
+                        format!("failed to reserve pid file {}", self.pid_file.display())
+                    });
+                }
+            }
+        }
+        // Pin the selected release across installer symlink/junction retargeting.
+        let codex_bin = fs::canonicalize(&self.codex_bin)
+            .await
+            .unwrap_or_else(|_| self.codex_bin.clone());
+        let launched_identity =
+            if matches!(self.command_kind, super::PidCommandKind::AppServer { .. }) {
+                executable_identity(&codex_bin).await.ok()
+            } else {
+                None
+            };
+        let mut command = Command::new(&codex_bin);
+        let stderr_log = match self.open_stderr_log().await {
+            Ok(stderr_log) => stderr_log,
+            Err(err) => {
+                if replacement.is_none() {
+                    let _ = fs::remove_file(&self.pid_file).await;
+                }
+                return Err(err);
+            }
+        };
+        command
+            .args(self.command_args())
+            .stdin(Stdio::null())
+            .stdout(Stdio::null())
+            .stderr(Stdio::from(stderr_log.into_std().await));
+        // Older or pinned managed binaries may predate this optional startup flag.
+        let managed_app_server =
+            matches!(self.command_kind, super::PidCommandKind::AppServer { .. });
+        if managed_app_server
+            && matches!(
+                tokio::time::timeout(
+                    std::time::Duration::from_secs(5),
+                    Command::new(&codex_bin)
+                        .args(["app-server", "--managed-daemon", "--help"])
+                        .stdin(Stdio::null())
+                        .stdout(Stdio::null())
+                        .stderr(Stdio::null())
+                        .kill_on_drop(true)
+                        .status(),
+                ).await,
+                Ok(Ok(status)) if status.success()
+            )
+        {
+            command.arg("--managed-daemon");
+        } else if managed_app_server {
+            let codex_home = self
+                .pid_file
+                .parent()
+                .and_then(std::path::Path::parent)
+                .context("daemon pid path has no Codex home")?;
+            let recovery_file = codex_app_server_transport::daemon_recovery_file_path(codex_home);
+            match fs::remove_file(&recovery_file).await {
+                Ok(()) => {}
+                Err(err) if err.kind() == std::io::ErrorKind::NotFound => {}
+                Err(err) => {
+                    tracing::warn!(path = %recovery_file.display(), %err, "failed to clear daemon recovery state before legacy launch");
+                }
+            }
+        }
+        if let Some((key, value)) = self.command_env() {
+            command.env(key, value);
+        }
+
+        #[cfg(unix)]
+        {
+            unsafe {
+                command.pre_exec(|| {
+                    if libc::setsid() == -1 {
+                        return Err(std::io::Error::last_os_error());
+                    }
+                    Ok(())
+                });
+            }
+        }
+
+        #[cfg(windows)]
+        {
+            use windows_sys::Win32::System::Threading::CREATE_BREAKAWAY_FROM_JOB;
+            use windows_sys::Win32::System::Threading::DETACHED_PROCESS;
+            // Preserve process-scoped paths before changing cwd; CA names match CUSTOM_CA_ENV_KEYS.
+            for name in [
+                "CODEX_HOME",
+                "CODEX_SQLITE_HOME",
+                "CODEX_CA_CERTIFICATE",
+                "SSL_CERT_FILE",
+                "REQUESTS_CA_BUNDLE",
+                "CURL_CA_BUNDLE",
+                "NODE_EXTRA_CA_CERTS",
+                "GIT_SSL_CAINFO",
+                "CARGO_HTTP_CAINFO",
+                "PIP_CERT",
+                "BUNDLE_SSL_CA_CERT",
+                "npm_config_cafile",
+                "AWS_CONFIG_FILE",
+                "AWS_SHARED_CREDENTIALS_FILE",
+                "AWS_WEB_IDENTITY_TOKEN_FILE",
+                "AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE",
+            ] {
+                let Some(mut value) = std::env::var_os(name) else {
+                    continue;
+                };
+                if matches!(name, "CODEX_SQLITE_HOME" | "npm_config_cafile") {
+                    value = value.to_str().unwrap_or_default().trim().into();
+                }
+                // These consumers expand `~` independently of the working directory.
+                let expands_home = if name == "npm_config_cafile" {
+                    value
+                        .to_str()
+                        .is_some_and(|path| path.starts_with("~/") || path.starts_with("~\\"))
+                } else {
+                    matches!(
+                        name,
+                        "CODEX_SQLITE_HOME" | "AWS_CONFIG_FILE" | "AWS_SHARED_CREDENTIALS_FILE"
+                    ) && std::path::Path::new(&value).starts_with("~")
+                };
+                if value.is_empty() || expands_home {
+                    continue;
+                }
+                command.env(name, std::path::absolute(value)?);
+            }
+            if let Some(value) = std::env::var_os("SSL_CERT_DIR") {
+                let paths = std::env::split_paths(&value)
+                    .filter(|path| !path.as_os_str().is_empty())
+                    .map(std::path::absolute)
+                    .collect::<std::io::Result<Vec<_>>>()?;
+                command.env("SSL_CERT_DIR", std::env::join_paths(paths)?);
+            }
+            // A Windows process pins its working directory for its lifetime.
+            // Keep both managed children out of the launching project's directory.
+            command.current_dir(
+                self.pid_file
+                    .parent()
+                    .context("daemon pid path has no parent")?,
+            );
+            // Never retry inside the parent's Job Object: that would report a
+            // successful launch that dies when the terminal/SSH session closes.
+            command.creation_flags(DETACHED_PROCESS | CREATE_BREAKAWAY_FROM_JOB);
+            if matches!(self.command_kind, PidCommandKind::UpdateLoop { .. }) {
+                match fs::remove_file(self.pid_file.with_extension("ready")).await {
+                    Ok(()) => {}
+                    Err(err) if err.kind() == std::io::ErrorKind::NotFound => {}
+                    Err(err) => return Err(err).context("failed to clear updater readiness"),
+                }
+            }
+            match self.command_kind {
+                PidCommandKind::AppServer { .. } => {
+                    command.env(codex_app_server_transport::DAEMON_SHUTDOWN_SOCKET_ENV, "1");
+                }
+                PidCommandKind::UpdateLoop { .. } => {
+                    let shutdown_file = self.pid_file.with_extension("shutdown");
+                    match fs::remove_file(&shutdown_file).await {
+                        Ok(()) => {}
+                        Err(err) if err.kind() == std::io::ErrorKind::NotFound => {}
+                        Err(err) => {
+                            return Err(err).context("failed to clear updater shutdown request");
+                        }
+                    }
+                    command.env(
+                        codex_app_server_transport::DAEMON_SHUTDOWN_FILE_ENV,
+                        shutdown_file,
+                    );
+                }
+            }
+        }
+
+        let child = match command.spawn() {
+            Ok(child) => child,
+            Err(err) => {
+                if replacement.is_none() {
+                    let _ = fs::remove_file(&self.pid_file).await;
+                }
+                return Err(err).with_context(|| {
+                    let job_hint = if cfg!(windows) {
+                        " (the Windows host job must allow breakaway)"
+                    } else {
+                        ""
+                    };
+                    format!(
+                        "failed to spawn detached app-server process using {}{job_hint}",
+                        self.codex_bin.display()
+                    )
+                });
+            }
+        };
+        let pid = child
+            .id()
+            .context("spawned app-server process has no pid")?;
+        let record = match async {
+            #[cfg(windows)]
+            super::super::windows::Process::open(pid)?
+                .context("daemon exited during launch")?
+                .ensure_detached()?;
+            let process_start_time = read_process_start_time(pid).await?;
+            #[cfg(any(target_os = "linux", target_os = "macos"))]
+            let process_identity = super::identity::read_process_details(pid)
+                .await
+                .ok()
+                .map(|(_, identity)| identity);
+            #[cfg(not(any(target_os = "linux", target_os = "macos")))]
+            let process_identity = None;
+            anyhow::Ok(PidRecord {
+                pid,
+                process_start_time,
+                process_identity,
+                executable_identity: launched_identity,
+            })
+        }
+        .await
+        {
+            Ok(record) => record,
+            Err(err) => {
+                let _ = self.terminate_process(pid);
+                let mut context =
+                    format!("failed to record pid-managed app-server process {pid} startup");
+                super::super::append_stderr_log_tail_context(&self.pid_file, &mut context).await;
+                if replacement.is_none() {
+                    let _ = fs::remove_file(&self.pid_file).await;
+                }
+                return Err(err).context(context);
+            }
+        };
+        let contents = serde_json::to_vec(&record).context("failed to serialize pid record")?;
+        let temp_pid_file = self.pid_file.with_extension("pid.tmp");
+        if let Err(err) = fs::write(&temp_pid_file, &contents).await {
+            let _ = self.terminate_process(pid);
+            if replacement.is_none() {
+                let _ = fs::remove_file(&self.pid_file).await;
+            }
+            return Err(err).with_context(|| {
+                format!("failed to write pid temp file {}", temp_pid_file.display())
+            });
+        }
+        if let Err(err) = fs::rename(&temp_pid_file, &self.pid_file).await {
+            let _ = self.terminate_process(pid);
+            let _ = fs::remove_file(&temp_pid_file).await;
+            if replacement.is_none() {
+                let _ = fs::remove_file(&self.pid_file).await;
+            }
+            return Err(err).with_context(|| {
+                format!("failed to publish pid file {}", self.pid_file.display())
+            });
+        }
+        #[cfg(windows)]
+        if matches!(self.command_kind, PidCommandKind::UpdateLoop { .. }) {
+            self.finish_updater_start(&record, replacement.as_ref())
+                .await?;
+        }
+        drop(reservation_lock);
+        Ok(Some(pid))
+    }
+}

codex-rs/app-server-daemon/src/backend/pid_tests.rs

@@ -0,0 +1,924 @@
+#[cfg(any(unix, windows))]
+use std::process::Stdio;
+use std::time::Duration;
+
+use pretty_assertions::assert_eq;
+use tempfile::TempDir;
+#[cfg(any(unix, windows))]
+use tokio::time::sleep;
+
+use codex_app_server_transport::REMOTE_CONTROL_DISABLED_ENV_VAR;
+
+use super::PidBackend;
+use super::PidCommandKind;
+use super::PidFileState;
+use super::PidLogTail;
+use super::PidRecord;
+#[cfg(unix)]
+use super::read_process_start_time;
+use super::read_stderr_log_tail;
+use super::stderr_log_file_for_pid_file;
+use super::try_lock_file;
+
+#[cfg(windows)]
+fn is_elevated_test_process() -> anyhow::Result<bool> {
+    let output = std::process::Command::new("powershell.exe")
+        .args([
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            "[Security.Principal.WindowsPrincipal]::new([Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)",
+        ])
+        .output()?;
+    anyhow::ensure!(
+        output.status.success(),
+        "administrator membership query failed"
+    );
+    match String::from_utf8(output.stdout)?.trim() {
+        "True" => Ok(true),
+        "False" => Ok(false),
+        other => anyhow::bail!("unexpected administrator membership: {other}"),
+    }
+}
+
+#[tokio::test]
+async fn locked_empty_pid_file_is_treated_as_active_reservation() {
+    let temp_dir = TempDir::new().expect("temp dir");
+    let pid_file = temp_dir.path().join("app-server.pid");
+    tokio::fs::write(&pid_file, "")
+        .await
+        .expect("write pid file");
+    let backend = PidBackend::new(
+        temp_dir.path().join("codex"),
+        pid_file.clone(),
+        /*remote_control_enabled*/ false,
+    );
+    let reservation = tokio::fs::OpenOptions::new()
+        .create(true)
+        .truncate(false)
+        .write(true)
+        .open(&backend.lock_file)
+        .await
+        .expect("open pid lock file");
+    assert!(try_lock_file(&reservation).expect("lock reservation"));
+
+    assert_eq!(
+        backend.read_pid_file_state().await.expect("read pid"),
+        PidFileState::Starting
+    );
+    assert!(pid_file.exists());
+}
+
+#[tokio::test]
+async fn unlocked_empty_pid_file_is_treated_as_stale_reservation() {
+    let temp_dir = TempDir::new().expect("temp dir");
+    let pid_file = temp_dir.path().join("app-server.pid");
+    tokio::fs::write(&pid_file, "")
+        .await
+        .expect("write pid file");
+    let backend = PidBackend::new(
+        temp_dir.path().join("codex"),
+        pid_file.clone(),
+        /*remote_control_enabled*/ false,
+    );
+
+    assert_eq!(
+        backend.read_pid_file_state().await.expect("read pid"),
+        PidFileState::Missing
+    );
+    assert!(!pid_file.exists());
+}
+
+#[tokio::test]
+async fn stop_waits_for_live_reservation_to_resolve() {
+    let temp_dir = TempDir::new().expect("temp dir");
+    let pid_file = temp_dir.path().join("app-server.pid");
+    tokio::fs::write(&pid_file, "")
+        .await
+        .expect("write pid file");
+    let backend = PidBackend::new(
+        temp_dir.path().join("codex"),
+        pid_file.clone(),
+        /*remote_control_enabled*/ false,
+    );
+    let reservation = tokio::fs::OpenOptions::new()
+        .create(true)
+        .truncate(false)
+        .write(true)
+        .open(&backend.lock_file)
+        .await
+        .expect("open pid lock file");
+    assert!(try_lock_file(&reservation).expect("lock reservation"));
+    let cleanup = tokio::spawn(async move {
+        tokio::time::sleep(Duration::from_millis(50)).await;
+        drop(reservation);
+        tokio::fs::remove_file(pid_file)
+            .await
+            .expect("remove pid file");
+    });
+
+    backend.stop().await.expect("stop");
+    cleanup.await.expect("cleanup task");
+}
+
+#[tokio::test]
+async fn start_retries_stale_empty_pid_file_under_its_own_lock() {
+    let temp_dir = TempDir::new().expect("temp dir");
+    let state_dir = temp_dir.path().join("state");
+    codex_uds::prepare_private_socket_directory(&state_dir)
+        .await
+        .expect("private state directory");
+    let pid_file = state_dir.join("app-server.pid");
+    tokio::fs::write(&pid_file, "")
+        .await
+        .expect("write pid file");
+    let backend = PidBackend::new(
+        temp_dir.path().join("missing-codex"),
+        pid_file,
+        /*remote_control_enabled*/ false,
+    );
+
+    let err = backend.start().await.expect_err("start");
+    #[cfg(windows)]
+    if is_elevated_test_process().expect("query administrator membership") {
+        assert!(err.to_string().contains("non-elevated terminal"));
+        assert_eq!(
+            tokio::fs::read(&backend.pid_file).await.unwrap(),
+            Vec::<u8>::new()
+        );
+        assert!(!backend.lock_file.exists());
+        return;
+    }
+    assert!(
+        err.to_string()
+            .starts_with("failed to spawn detached app-server process using ")
+    );
+}
+
+#[cfg(unix)]
+#[tokio::test]
+async fn legacy_launch_clears_recovery_best_effort() {
+    for snapshot_is_directory in [false, true] {
+        let home = TempDir::new().expect("temp dir");
+        let state_dir = home.path().join("app-server-daemon");
+        std::fs::create_dir_all(&state_dir).expect("state dir");
+        let recovery_file = codex_app_server_transport::daemon_recovery_file_path(home.path());
+        if snapshot_is_directory {
+            std::fs::create_dir(&recovery_file).expect("invalid snapshot directory");
+        } else {
+            std::fs::write(&recovery_file, "{}").expect("pending snapshot");
+        }
+        let backend = PidBackend::new(
+            home.path().join("missing-codex"),
+            state_dir.join("app-server.pid"),
+            /*remote_control_enabled*/ false,
+        );
+
+        let error = backend.start().await.expect_err("missing binary");
+        assert!(
+            error
+                .to_string()
+                .starts_with("failed to spawn detached app-server process using "),
+            "{error:#}"
+        );
+        assert_eq!(recovery_file.exists(), snapshot_is_directory);
+    }
+}
+
+#[tokio::test]
+async fn stale_record_cleanup_preserves_replacement_record() {
+    let temp_dir = TempDir::new().expect("temp dir");
+    let pid_file = temp_dir.path().join("app-server.pid");
+    let backend = PidBackend::new(
+        temp_dir.path().join("codex"),
+        pid_file.clone(),
+        /*remote_control_enabled*/ false,
+    );
+    let stale = PidRecord {
+        pid: 1,
+        process_start_time: "old".to_string(),
+        process_identity: None,
+        executable_identity: None,
+    };
+    let replacement = PidRecord {
+        pid: 2,
+        process_start_time: "new".to_string(),
+        process_identity: None,
+        executable_identity: None,
+    };
+    tokio::fs::write(
+        &pid_file,
+        serde_json::to_vec(&replacement).expect("serialize replacement"),
+    )
+    .await
+    .expect("write replacement pid file");
+
+    assert_eq!(
+        backend
+            .refresh_after_stale_record(&stale)
+            .await
+            .expect("cleanup"),
+        PidFileState::Running(replacement)
+    );
+}
+
+#[cfg(unix)]
+#[tokio::test]
+async fn pid_record_captures_the_resolved_launch_binary() {
+    use std::os::unix::fs::PermissionsExt;
+
+    let temp = TempDir::new().expect("temp dir");
+    let original = temp.path().join("original-codex");
+    let replacement = temp.path().join("replacement-codex");
+    for (path, bytes) in [
+        (&original, b"#!/bin/sh\nexec sleep 30\n".as_slice()),
+        (
+            &replacement,
+            b"#!/bin/sh\n# replacement\nexec sleep 30\n".as_slice(),
+        ),
+    ] {
+        std::fs::write(path, bytes).expect("binary");
+        std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o755)).expect("executable");
+    }
+    let selected = temp.path().join("current-codex");
+    std::os::unix::fs::symlink(&original, &selected).expect("selected binary");
+    let backend = PidBackend::new(
+        selected.clone(),
+        temp.path().join("app-server.pid"),
+        /*remote_control_enabled*/ false,
+    );
+    backend.start().await.expect("start daemon");
+    let record: PidRecord =
+        serde_json::from_slice(&std::fs::read(&backend.pid_file).expect("PID record"))
+            .expect("parse PID record");
+    assert_eq!(
+        record.executable_identity,
+        Some(
+            crate::managed_install::executable_identity(&original)
+                .await
+                .expect("original digest")
+        )
+    );
+    std::fs::remove_file(&selected).expect("remove link");
+    std::os::unix::fs::symlink(&replacement, &selected).expect("retarget link");
+    assert_ne!(
+        record.executable_identity,
+        Some(
+            crate::managed_install::executable_identity(&selected)
+                .await
+                .expect("new digest")
+        )
+    );
+    assert_eq!(
+        serde_json::from_str::<PidRecord>(r#"{"pid":1,"processStartTime":"old"}"#)
+            .expect("legacy PID record")
+            .executable_identity,
+        None
+    );
+    backend.stop().await.expect("stop daemon");
+}
+
+#[cfg(unix)]
+#[tokio::test]
+async fn legacy_start_time_mismatch_preserves_record_and_process() {
+    let temp = TempDir::new().unwrap();
+    let backend = PidBackend::new(
+        temp.path().join("codex"),
+        temp.path().join("app-server.pid"),
+        /*remote_control_enabled*/ false,
+    );
+    let contents = serde_json::to_vec(&serde_json::json!({
+        "pid": std::process::id(),
+        "processStartTime": "historical wall-clock start time",
+    }))
+    .unwrap();
+    std::fs::write(&backend.pid_file, &contents).unwrap();
+    for result in [
+        backend.is_starting_or_running().await.map(|_| ()),
+        backend.start().await.map(|_| ()),
+        backend.stop().await,
+        #[cfg(any(target_os = "linux", target_os = "macos"))]
+        backend.promote_legacy_identity().await,
+    ] {
+        assert!(
+            result
+                .unwrap_err()
+                .to_string()
+                .contains("PID record retained")
+        );
+    }
+    assert_eq!(std::fs::read(&backend.pid_file).unwrap(), contents);
+}
+
+#[cfg(unix)]
+#[tokio::test]
+async fn stop_reaps_untracked_app_server_child() {
+    let temp_dir = TempDir::new().expect("temp dir");
+    let pid_file = temp_dir.path().join("app-server.pid");
+    let mut child = std::process::Command::new("sleep")
+        .arg("5")
+        .stdin(Stdio::null())
+        .stdout(Stdio::null())
+        .stderr(Stdio::null())
+        .spawn()
+        .expect("spawn app-server shim");
+    let pid = child.id();
+    let record = PidRecord {
+        pid,
+        process_start_time: read_process_start_time(pid).await.expect("start time"),
+        process_identity: None,
+        executable_identity: None,
+    };
+    tokio::fs::write(
+        &pid_file,
+        serde_json::to_vec(&record).expect("serialize pid"),
+    )
+    .await
+    .expect("write pid file");
+    let backend = PidBackend::new(
+        temp_dir.path().join("codex"),
+        pid_file.clone(),
+        /*remote_control_enabled*/ false,
+    );
+
+    let result = tokio::time::timeout(Duration::from_secs(2), backend.stop()).await;
+    if matches!(child.try_wait(), Ok(None)) {
+        let _ = child.kill();
+        let _ = child.wait();
+    }
+
+    // `sleep` is not tracked by Tokio, so stop must reap it instead of leaving a zombie.
+    result.expect("stop timed out").expect("stop");
+    assert!(!pid_file.exists());
+}
+
+#[cfg(any(unix, windows))]
+#[tokio::test]
+async fn shutdown_grace_child() {
+    let Some(ready) = std::env::var_os("CODEX_TEST_SHUTDOWN_GRACE_READY") else {
+        return;
+    };
+    let ready = std::path::PathBuf::from(ready);
+    #[cfg(unix)]
+    let mut terminate = tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate())
+        .expect("install shutdown handler");
+    tokio::fs::write(&ready, "").await.expect("ready marker");
+    let _ = tokio::time::timeout(Duration::from_secs(8), async {
+        #[cfg(unix)]
+        terminate.recv().await;
+        #[cfg(windows)]
+        loop {
+            if ready.with_extension("shutdown").exists() {
+                break;
+            }
+            sleep(Duration::from_millis(10)).await;
+        }
+        if std::env::var_os("CODEX_TEST_SHUTDOWN_GRACE_EXIT").is_some() {
+            sleep(Duration::from_millis(150)).await;
+            tokio::fs::write(ready.with_extension("exited"), "")
+                .await
+                .expect("graceful exit marker");
+            return;
+        }
+        std::future::pending::<()>().await;
+    })
+    .await;
+}
+
+#[cfg(any(unix, windows))]
+#[tokio::test]
+async fn shutdown_grace_handles_process_exit() {
+    let temp = TempDir::new().expect("temp dir");
+    for (name, grace_seconds, exits) in [
+        ("zero", 0, false),
+        ("finite_exit", 1, true),
+        ("finite_force", 1, false),
+    ] {
+        let ready = temp.path().join(format!("{name}.ready"));
+        let mut child = std::process::Command::new(std::env::current_exe().expect("test binary"))
+            .args(["--exact", "backend::pid::tests::shutdown_grace_child"])
+            .env("CODEX_TEST_SHUTDOWN_GRACE_READY", &ready)
+            .envs(exits.then_some(("CODEX_TEST_SHUTDOWN_GRACE_EXIT", "1")))
+            .stdout(Stdio::null())
+            .stderr(Stdio::null())
+            .spawn()
+            .expect("spawn daemon shim");
+        let pid = child.id();
+        let wait_until = tokio::time::Instant::now() + Duration::from_secs(3);
+        while !ready.exists() {
+            assert!(
+                tokio::time::Instant::now() < wait_until,
+                "shim did not start"
+            );
+            sleep(Duration::from_millis(10)).await;
+        }
+        let pid_file = temp.path().join(format!("{name}.pid"));
+        let record = PidRecord {
+            pid,
+            process_start_time: super::read_process_start_time(pid)
+                .await
+                .expect("start time"),
+            process_identity: None,
+            executable_identity: None,
+        };
+        tokio::fs::write(
+            &pid_file,
+            serde_json::to_vec(&record).expect("serialize pid"),
+        )
+        .await
+        .expect("write pid file");
+        #[cfg(unix)]
+        let backend = PidBackend::new(
+            temp.path().join("codex"),
+            pid_file,
+            /*remote_control_enabled*/ false,
+        );
+        #[cfg(windows)]
+        let backend = PidBackend::new_update_loop(
+            temp.path().join("codex"),
+            pid_file,
+            /*restore_release*/ None,
+        );
+        let result = tokio::time::timeout(
+            Duration::from_secs(3),
+            backend.stop_with_grace(grace_seconds),
+        )
+        .await;
+        let still_running = backend
+            .record_is_active(&record)
+            .await
+            .expect("child status");
+        if still_running {
+            child.kill().expect("clean up daemon shim");
+        }
+        let _ = child.wait(); // The backend may already have reaped a Unix child.
+        result.expect("stop deadline").expect("stop outcome");
+        assert_eq!(ready.with_extension("exited").exists(), exits);
+        assert!(!still_running, "{name}");
+    }
+}
+
+#[cfg(unix)]
+#[tokio::test]
+async fn stopping_updater_signals_its_installer_process_group() {
+    use std::os::unix::process::CommandExt;
+
+    let temp = TempDir::new().expect("temp dir");
+    let ready = temp.path().join("installer.ready");
+    let stopped = temp.path().join("installer.stopped");
+    let mut command = std::process::Command::new("/bin/sh");
+    command
+        .args([
+            "-c",
+            "sh -c 'trap \"touch $STOP_MARKER; exit 0\" TERM; touch $READY_MARKER; while :; do sleep 1; done' & wait",
+        ])
+        .env("READY_MARKER", &ready)
+        .env("STOP_MARKER", &stopped)
+        .stdout(Stdio::null())
+        .stderr(Stdio::null());
+    unsafe {
+        command.pre_exec(|| {
+            if libc::setsid() == -1 {
+                return Err(std::io::Error::last_os_error());
+            }
+            Ok(())
+        });
+    }
+    let mut child = command.spawn().expect("spawn updater shim");
+    let pid = child.id();
+    let deadline = tokio::time::Instant::now() + Duration::from_secs(2);
+    while !ready.exists() {
+        assert!(
+            tokio::time::Instant::now() < deadline,
+            "installer did not start"
+        );
+        sleep(Duration::from_millis(10)).await;
+    }
+    let pid_file = temp.path().join("updater.pid");
+    tokio::fs::write(
+        &pid_file,
+        serde_json::to_vec(&PidRecord {
+            pid,
+            process_start_time: read_process_start_time(pid).await.expect("start time"),
+            process_identity: None,
+            executable_identity: None,
+        })
+        .expect("serialize pid"),
+    )
+    .await
+    .expect("write pid file");
+    let backend = PidBackend::new_update_loop(
+        temp.path().join("codex"),
+        pid_file,
+        /*restore_release*/ None,
+    );
+    backend.stop().await.expect("stop updater");
+    // The backend normally reaps the shim, so a second wait may return ECHILD.
+    let _ = child.wait();
+    let deadline = tokio::time::Instant::now() + Duration::from_secs(2);
+    while !stopped.exists() {
+        assert!(
+            tokio::time::Instant::now() < deadline,
+            "installer was not stopped"
+        );
+        sleep(Duration::from_millis(10)).await;
+    }
+}
+
+#[cfg(unix)]
+#[tokio::test]
+async fn exited_unreaped_updater_is_reaped() {
+    let temp = TempDir::new().expect("temp dir");
+    let mut child = std::process::Command::new("sleep")
+        .arg("60")
+        .spawn()
+        .expect("spawn updater shim");
+    #[cfg(any(target_os = "linux", target_os = "macos"))]
+    let process_identity = Some(
+        super::identity::read_process_details(child.id())
+            .await
+            .unwrap()
+            .1,
+    );
+    #[cfg(not(any(target_os = "linux", target_os = "macos")))]
+    let process_identity = None;
+    let record = PidRecord {
+        pid: child.id(),
+        process_start_time: read_process_start_time(child.id())
+            .await
+            .expect("start time"),
+        process_identity,
+        executable_identity: None,
+    };
+    let backend = PidBackend::new_update_loop(
+        temp.path().join("codex"),
+        temp.path().join("updater.pid"),
+        /*restore_release*/ None,
+    );
+    child.kill().expect("terminate updater shim");
+    let deadline = tokio::time::Instant::now() + Duration::from_secs(5);
+    let result = loop {
+        let result = backend.record_is_active(&record).await;
+        if matches!(&result, Ok(false)) || tokio::time::Instant::now() >= deadline {
+            break result;
+        }
+        tokio::time::sleep(Duration::from_millis(50)).await;
+    };
+    assert!(!result.expect("check zombie updater"));
+    assert_eq!(
+        child
+            .wait()
+            .expect_err("updater shim was already reaped")
+            .raw_os_error(),
+        Some(libc::ECHILD)
+    );
+}
+
+#[test]
+fn update_loop_uses_hidden_app_server_subcommand() {
+    let backend = PidBackend {
+        codex_bin: "codex".into(),
+        pid_file: "updater.pid".into(),
+        lock_file: "updater.pid.lock".into(),
+        command_kind: PidCommandKind::UpdateLoop {
+            restore_release: None,
+        },
+    };
+
+    assert_eq!(
+        backend.command_args(),
+        vec!["app-server", "daemon", "pid-update-loop"]
+    );
+}
+
+#[test]
+fn app_server_remote_control_uses_runtime_flag() {
+    let backend = PidBackend::new(
+        "codex".into(),
+        "app-server.pid".into(),
+        /*remote_control_enabled*/ true,
+    );
+
+    assert_eq!(
+        backend.command_args(),
+        vec!["app-server", "--remote-control", "--listen", "unix://"]
+    );
+}
+
+#[test]
+fn app_server_disabled_remote_control_uses_compatible_args_and_runtime_env() {
+    let backend = PidBackend::new(
+        "codex".into(),
+        "app-server.pid".into(),
+        /*remote_control_enabled*/ false,
+    );
+
+    assert_eq!(
+        backend.command_args(),
+        vec!["app-server", "--listen", "unix://"]
+    );
+    assert_eq!(
+        backend.command_env(),
+        Some((REMOTE_CONTROL_DISABLED_ENV_VAR, "1"))
+    );
+}
+
+#[tokio::test]
+async fn read_stderr_log_tail_returns_recent_complete_lines() {
+    let temp_dir = TempDir::new().expect("temp dir");
+    let pid_file = temp_dir.path().join("app-server.pid");
+    let log_file = stderr_log_file_for_pid_file(&pid_file);
+    let contents = format!("{}\nrecent error\nusage", "x".repeat(4100));
+    tokio::fs::write(&log_file, contents)
+        .await
+        .expect("write stderr log");
+
+    assert_eq!(
+        read_stderr_log_tail(&pid_file)
+            .await
+            .expect("read stderr log"),
+        Some(PidLogTail {
+            path: log_file,
+            contents: "recent error\nusage".to_string(),
+        })
+    );
+}
+
+#[tokio::test]
+async fn stale_creation_time_never_stops_reused_pid() {
+    let temp = TempDir::new().expect("temp");
+    let backend = PidBackend::new(
+        temp.path().join("codex.exe"),
+        temp.path().join("server.pid"),
+        /*remote_control_enabled*/ false,
+    );
+    #[cfg(any(target_os = "linux", target_os = "macos"))]
+    let identities = {
+        use super::identity::ProcessIdentity;
+        let (_, identity) = super::identity::read_process_details(std::process::id())
+            .await
+            .unwrap();
+        let mut stale_time = identity.clone();
+        let mut stale_epoch = identity;
+        match &mut stale_time {
+            ProcessIdentity::Linux { start_ticks, .. } => *start_ticks += 1,
+            ProcessIdentity::MacOs {
+                start_microseconds, ..
+            }
+            | ProcessIdentity::MacOsUnique {
+                start_microseconds, ..
+            } => *start_microseconds += 1,
+        }
+        match &mut stale_epoch {
+            ProcessIdentity::Linux { boot_id, .. } => boot_id.push_str("-previous"),
+            ProcessIdentity::MacOs { start_seconds, .. } => *start_seconds += 1,
+            ProcessIdentity::MacOsUnique { unique_id, .. } => *unique_id += 1,
+        }
+        [Some(stale_time), Some(stale_epoch)]
+    };
+    #[cfg(not(any(target_os = "linux", target_os = "macos")))]
+    let identities = [None];
+    for process_identity in identities {
+        let record = PidRecord {
+            pid: std::process::id(),
+            process_start_time: "stale".into(),
+            process_identity,
+            executable_identity: None,
+        };
+        let contents = serde_json::to_vec(&record).unwrap();
+        std::fs::write(&backend.pid_file, &contents).unwrap();
+        backend.stop().await.expect("stale record cleanup");
+        assert!(!backend.pid_file.exists());
+        assert!(!backend.pid_file.with_extension("shutdown").exists());
+    }
+}
+
+#[cfg(windows)]
+#[tokio::test]
+async fn failed_updater_handoff_preserves_predecessor_record() {
+    let elevated = is_elevated_test_process().expect("query administrator membership");
+    let temp = TempDir::new().expect("temp");
+    let state_dir = temp.path().join("state");
+    codex_uds::prepare_private_socket_directory(&state_dir)
+        .await
+        .expect("private state directory");
+    let backend = PidBackend::new_update_loop(
+        temp.path().join("missing-codex.exe"),
+        state_dir.join("updater.pid"),
+        /*restore_release*/ None,
+    );
+    let record = PidRecord {
+        pid: std::process::id(),
+        process_start_time: super::read_process_start_time(std::process::id())
+            .await
+            .unwrap(),
+        process_identity: None,
+        executable_identity: None,
+    };
+    for record in [
+        record.clone(),
+        PidRecord {
+            process_start_time: "stale".into(),
+            ..record
+        },
+    ] {
+        tokio::fs::write(&backend.pid_file, serde_json::to_vec(&record).unwrap())
+            .await
+            .unwrap();
+        let error = backend.replace_current_updater().await.unwrap_err();
+        if elevated {
+            assert!(error.to_string().contains("non-elevated terminal"));
+        } else {
+            // Windows may reject breakaway before reporting the missing executable.
+            // Both must reach process I/O rather than rejecting stale ownership.
+            assert!(error.root_cause().is::<std::io::Error>(), "{error:#}");
+        }
+        assert_eq!(
+            backend.read_pid_file_state().await.unwrap(),
+            PidFileState::Running(record)
+        );
+    }
+}
+
+#[cfg(windows)]
+#[tokio::test]
+async fn updater_readiness_and_post_publication_failure_preserve_ownership() {
+    use futures::FutureExt;
+    use windows_sys::Win32::Security::ImpersonateAnonymousToken;
+    use windows_sys::Win32::Security::RevertToSelf;
+    use windows_sys::Win32::System::Threading::GetCurrentThread;
+
+    let temp = TempDir::new().expect("temp");
+    let backend = PidBackend::new_update_loop(
+        temp.path().join("codex.exe"),
+        temp.path().join("updater.pid"),
+        /*restore_release*/ None,
+    );
+    let _lock = backend
+        .acquire_reservation_lock()
+        .await
+        .expect("reservation lock");
+    let mut child = tokio::process::Command::new("powershell.exe")
+        .args([
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            "Start-Sleep 60",
+        ])
+        .creation_flags(windows_sys::Win32::System::Threading::CREATE_NO_WINDOW)
+        .kill_on_drop(true)
+        .spawn()
+        .expect("successor fixture");
+    let pid = child.id().expect("pid");
+    let successor = PidRecord {
+        pid,
+        process_start_time: super::read_process_start_time(pid)
+            .await
+            .expect("creation time"),
+        process_identity: None,
+        executable_identity: None,
+    };
+    let predecessor = PidRecord {
+        pid: std::process::id(),
+        process_start_time: super::read_process_start_time(std::process::id())
+            .await
+            .expect("creation time"),
+        process_identity: None,
+        executable_identity: None,
+    };
+    tokio::fs::write(&backend.pid_file, serde_json::to_vec(&successor).unwrap())
+        .await
+        .unwrap();
+    let ready = backend.pid_file.with_extension("ready");
+    tokio::fs::write(&ready, b"").await.unwrap();
+    backend
+        .finish_updater_start(&successor, Some(&predecessor))
+        .await
+        .expect("ready successor");
+    assert!(!ready.exists());
+    assert_eq!(
+        backend.read_pid_file_state().await.unwrap(),
+        PidFileState::Running(successor.clone())
+    );
+
+    // If cleanup cannot even query the successor, leave its ownership intact.
+    std::thread::scope(|scope| {
+        scope
+            .spawn(|| {
+                assert_ne!(unsafe { ImpersonateAnonymousToken(GetCurrentThread()) }, 0);
+                let result = backend
+                    .finish_updater_start(&successor, Some(&predecessor))
+                    .now_or_never();
+                let reverted = unsafe { RevertToSelf() };
+                assert_ne!(reverted, 0);
+                let error = result
+                    .expect("denied cleanup must not suspend")
+                    .unwrap_err();
+                assert_eq!(
+                    error
+                        .downcast_ref::<std::io::Error>()
+                        .unwrap()
+                        .raw_os_error(),
+                    Some(windows_sys::Win32::Foundation::ERROR_ACCESS_DENIED as i32)
+                );
+            })
+            .join()
+            .expect("anonymous cleanup check");
+    });
+    assert_eq!(
+        backend.read_pid_file_state().await.unwrap(),
+        PidFileState::Running(successor.clone())
+    );
+
+    let reused_pid = PidRecord {
+        process_start_time: "stale".into(),
+        ..successor.clone()
+    };
+    assert!(
+        backend
+            .finish_updater_start(&reused_pid, Some(&predecessor))
+            .await
+            .is_err()
+    );
+    assert_eq!(
+        backend.read_pid_file_state().await.unwrap(),
+        PidFileState::Running(predecessor.clone())
+    );
+    assert!(
+        child.try_wait().unwrap().is_none(),
+        "PID reuse must not terminate another process"
+    );
+    tokio::fs::write(&backend.pid_file, serde_json::to_vec(&successor).unwrap())
+        .await
+        .unwrap();
+    // An invalid readiness path triggers cleanup while the successor is alive.
+    tokio::fs::create_dir(&ready).await.unwrap();
+    assert!(
+        backend
+            .finish_updater_start(&successor, Some(&predecessor))
+            .await
+            .is_err()
+    );
+    assert!(
+        child.try_wait().unwrap().is_some(),
+        "successor must exit before rollback"
+    );
+    assert_eq!(
+        backend.read_pid_file_state().await.unwrap(),
+        PidFileState::Running(predecessor)
+    );
+}
+
+#[cfg(windows)]
+#[test]
+fn inaccessible_pid_preserves_identity_check_error() {
+    use futures::FutureExt;
+    use windows_sys::Win32::Security::ImpersonateAnonymousToken;
+    use windows_sys::Win32::Security::RevertToSelf;
+    use windows_sys::Win32::System::Threading::GetCurrentThread;
+
+    // Isolate impersonation from Tokio workers and other tests. Query our own
+    // process anonymously instead of assuming a system PID is inaccessible.
+    std::thread::spawn(|| {
+        let record = PidRecord {
+            pid: std::process::id(),
+            process_start_time: "stale".into(),
+            process_identity: None,
+            executable_identity: None,
+        };
+        assert!(
+            crate::backend::windows::Process::open(record.pid)
+                .unwrap()
+                .is_some()
+        );
+        assert_ne!(unsafe { ImpersonateAnonymousToken(GetCurrentThread()) }, 0);
+        let opened = crate::backend::windows::Process::open(record.pid);
+        // Windows identity checks are synchronous; never suspend while impersonating.
+        let matches = super::process_matches_record(&record).now_or_never();
+        let reverted = unsafe { RevertToSelf() };
+        assert_ne!(reverted, 0);
+
+        let error = match opened {
+            Err(error) => error,
+            Ok(_) => panic!("anonymous caller unexpectedly queried the test process"),
+        };
+        assert_eq!(
+            error
+                .downcast_ref::<std::io::Error>()
+                .unwrap()
+                .raw_os_error(),
+            Some(windows_sys::Win32::Foundation::ERROR_ACCESS_DENIED as i32),
+        );
+        assert_eq!(
+            matches
+                .expect("identity check must not suspend")
+                .unwrap_err()
+                .downcast_ref::<std::io::Error>()
+                .unwrap()
+                .raw_os_error(),
+            Some(windows_sys::Win32::Foundation::ERROR_ACCESS_DENIED as i32),
+        );
+    })
+    .join()
+    .expect("anonymous identity check");
+}

codex-rs/app-server-daemon/src/backend/pid_windows.rs

@@ -0,0 +1,100 @@
+//! Windows updater publication handshake. The predecessor holds the operation
+//! and reservation locks until its successor initializes and acknowledges readiness.
+
+use super::super::windows::Process;
+use super::PidBackend;
+use super::PidFileState;
+use super::PidRecord;
+use super::START_TIMEOUT;
+use super::STOP_POLL_INTERVAL;
+use super::process_matches_record;
+use super::read_process_start_time;
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::bail;
+use tokio::fs;
+use tokio::time::sleep;
+
+impl PidBackend {
+    pub(crate) async fn wait_for_ownership(&self) -> Result<()> {
+        let deadline = tokio::time::Instant::now() + START_TIMEOUT;
+        loop {
+            if let PidFileState::Running(record) = self.read_pid_file_state().await?
+                && record.pid == std::process::id()
+                && self.record_is_active(&record).await?
+            {
+                return Ok(());
+            }
+            if tokio::time::Instant::now() >= deadline {
+                bail!("updater was not published by its launcher");
+            }
+            sleep(STOP_POLL_INTERVAL).await;
+        }
+    }
+
+    pub(crate) async fn mark_ready(&self) -> Result<()> {
+        fs::write(self.pid_file.with_extension("ready"), b"")
+            .await
+            .context("failed to acknowledge updater startup")
+    }
+
+    pub(crate) async fn replace_current_updater(&self) -> Result<()> {
+        let record = PidRecord {
+            pid: std::process::id(),
+            process_start_time: read_process_start_time(std::process::id()).await?,
+            process_identity: None,
+            executable_identity: None,
+        };
+        self.start_inner(Some(record)).await?;
+        Ok(())
+    }
+
+    pub(super) async fn finish_updater_start(
+        &self,
+        record: &PidRecord,
+        replacement: Option<&PidRecord>,
+    ) -> Result<()> {
+        let temp_pid_file = self.pid_file.with_extension("pid.tmp");
+        let ready = self.pid_file.with_extension("ready");
+        let deadline = tokio::time::Instant::now() + START_TIMEOUT;
+        let startup = async {
+            loop {
+                if !process_matches_record(record).await? {
+                    bail!("updater exited before becoming ready");
+                }
+                match fs::remove_file(&ready).await {
+                    Ok(()) => return Ok(()),
+                    Err(err) if err.kind() == std::io::ErrorKind::NotFound => {}
+                    Err(err) => return Err(err.into()),
+                }
+                if tokio::time::Instant::now() >= deadline {
+                    bail!("updater did not become ready");
+                }
+                sleep(STOP_POLL_INTERVAL).await;
+            }
+        }
+        .await;
+        if let Err(err) = startup {
+            if let Some(process) = Process::open(record.pid)?
+                && process.start_time()? == record.process_start_time
+            {
+                process.terminate()?;
+                let deadline = tokio::time::Instant::now() + START_TIMEOUT;
+                while process.is_running()? {
+                    if tokio::time::Instant::now() >= deadline {
+                        bail!("failed updater did not exit; ownership was not restored");
+                    }
+                    sleep(STOP_POLL_INTERVAL).await;
+                }
+            }
+            if let Some(previous) = replacement {
+                fs::write(&temp_pid_file, serde_json::to_vec(previous)?).await?;
+                fs::rename(&temp_pid_file, &self.pid_file).await?;
+            } else {
+                let _ = fs::remove_file(&self.pid_file).await;
+            }
+            return Err(err);
+        }
+        Ok(())
+    }
+}

codex-rs/app-server-daemon/src/backend/windows.rs

@@ -0,0 +1,286 @@
+//! Windows process identity and file locks. Keep a process handle across shutdown
+//! so PID reuse can never redirect forced termination to a different process.
+//! Managed servers must not elevate ordinary clients sharing the account's socket.
+//! Installer jobs contain extraction processes when an update is cancelled.
+
+use std::io;
+use std::os::windows::io::AsRawHandle;
+use std::os::windows::io::FromRawHandle;
+use std::os::windows::io::OwnedHandle;
+use std::os::windows::process::CommandExt;
+use std::path::Path;
+use std::process::Command;
+use std::process::Stdio;
+
+use anyhow::Context;
+use anyhow::Result;
+use windows_sys::Win32::Foundation::ERROR_INVALID_PARAMETER;
+use windows_sys::Win32::Foundation::ERROR_LOCK_VIOLATION;
+use windows_sys::Win32::Foundation::FILETIME;
+use windows_sys::Win32::Foundation::WAIT_OBJECT_0;
+use windows_sys::Win32::Foundation::WAIT_TIMEOUT;
+use windows_sys::Win32::Security::GetTokenInformation;
+use windows_sys::Win32::Security::TOKEN_ELEVATION;
+use windows_sys::Win32::Security::TOKEN_QUERY;
+use windows_sys::Win32::Security::TokenElevation;
+use windows_sys::Win32::Storage::FileSystem::LOCKFILE_EXCLUSIVE_LOCK;
+use windows_sys::Win32::Storage::FileSystem::LOCKFILE_FAIL_IMMEDIATELY;
+use windows_sys::Win32::Storage::FileSystem::LockFileEx;
+use windows_sys::Win32::System::JobObjects::AssignProcessToJobObject;
+use windows_sys::Win32::System::JobObjects::CreateJobObjectW;
+use windows_sys::Win32::System::JobObjects::IsProcessInJob;
+use windows_sys::Win32::System::JobObjects::JOB_OBJECT_LIMIT_BREAKAWAY_OK;
+use windows_sys::Win32::System::JobObjects::JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE;
+use windows_sys::Win32::System::JobObjects::JOBOBJECT_EXTENDED_LIMIT_INFORMATION;
+use windows_sys::Win32::System::JobObjects::JobObjectExtendedLimitInformation;
+use windows_sys::Win32::System::JobObjects::SetInformationJobObject;
+use windows_sys::Win32::System::Threading::CREATE_BREAKAWAY_FROM_JOB;
+use windows_sys::Win32::System::Threading::CREATE_SUSPENDED;
+use windows_sys::Win32::System::Threading::DETACHED_PROCESS;
+use windows_sys::Win32::System::Threading::GetCurrentProcess;
+use windows_sys::Win32::System::Threading::GetProcessId;
+use windows_sys::Win32::System::Threading::GetProcessTimes;
+use windows_sys::Win32::System::Threading::OpenProcess;
+use windows_sys::Win32::System::Threading::OpenProcessToken;
+use windows_sys::Win32::System::Threading::PROCESS_ACCESS_RIGHTS;
+use windows_sys::Win32::System::Threading::PROCESS_QUERY_LIMITED_INFORMATION;
+use windows_sys::Win32::System::Threading::PROCESS_SYNCHRONIZE;
+use windows_sys::Win32::System::Threading::PROCESS_TERMINATE;
+use windows_sys::Win32::System::Threading::TerminateProcess;
+use windows_sys::Win32::System::Threading::WaitForSingleObject;
+
+pub(crate) fn ensure_not_elevated() -> Result<()> {
+    let mut token = 0;
+    if unsafe { OpenProcessToken(GetCurrentProcess(), TOKEN_QUERY, &mut token) } == 0 {
+        return Err(io::Error::last_os_error()).context("failed to query daemon launcher token");
+    }
+    let token = unsafe { OwnedHandle::from_raw_handle(token as _) };
+    let mut elevation: TOKEN_ELEVATION = unsafe { std::mem::zeroed() };
+    let mut returned = 0;
+    if unsafe {
+        GetTokenInformation(
+            token.as_raw_handle() as _,
+            TokenElevation,
+            (&mut elevation as *mut TOKEN_ELEVATION).cast(),
+            std::mem::size_of::<TOKEN_ELEVATION>() as u32,
+            &mut returned,
+        )
+    } == 0
+    {
+        return Err(io::Error::last_os_error())
+            .context("failed to query daemon launcher elevation");
+    }
+    anyhow::ensure!(
+        elevation.TokenIsElevated == 0,
+        "start the Windows daemon from a non-elevated terminal; shared clients must not inherit administrator privileges"
+    );
+    Ok(())
+}
+
+// Probe the actual child association: escaping an inner job can leave an outer
+// job attached. Suspend the image so no application code runs before cleanup.
+pub(crate) fn ensure_detached_launch(executable: &Path) -> Result<()> {
+    let mut child = Command::new(executable)
+        .creation_flags(CREATE_SUSPENDED | DETACHED_PROCESS | CREATE_BREAKAWAY_FROM_JOB)
+        .stdin(Stdio::null())
+        .stdout(Stdio::null())
+        .stderr(Stdio::null())
+        .spawn()
+        .context("cannot launch detached daemon; existing daemon was not stopped")?;
+    let mut in_job = 0;
+    let result = if unsafe {
+        IsProcessInJob(
+            child.as_raw_handle() as _,
+            /*jobhandle*/ 0,
+            &mut in_job,
+        )
+    } == 0
+    {
+        Err(io::Error::last_os_error()).context("failed to verify daemon launch capability")
+    } else if in_job != 0 {
+        Err(anyhow::anyhow!(
+            "host Job Object prevents daemon detachment; start from a host that allows breakaway"
+        ))
+    } else {
+        Ok(())
+    };
+    child
+        .kill()
+        .context("failed to terminate suspended launch probe")?;
+    child
+        .wait()
+        .context("failed to reap suspended launch probe")?;
+    result
+}
+
+pub(super) struct Process(OwnedHandle);
+
+impl Process {
+    pub(super) fn open(pid: u32) -> Result<Option<Self>> {
+        Self::open_with_access(pid, PROCESS_QUERY_LIMITED_INFORMATION | PROCESS_SYNCHRONIZE)
+    }
+
+    fn open_with_access(pid: u32, access: PROCESS_ACCESS_RIGHTS) -> Result<Option<Self>> {
+        let handle = unsafe {
+            OpenProcess(access, /*binherithandle*/ 0, pid)
+        };
+        if handle == 0 {
+            let err = io::Error::last_os_error();
+            return if err.raw_os_error() == Some(ERROR_INVALID_PARAMETER as i32) {
+                Ok(None)
+            } else {
+                Err(err).context("failed to open daemon process")
+            };
+        }
+        Ok(Some(Self(unsafe {
+            OwnedHandle::from_raw_handle(handle as _)
+        })))
+    }
+
+    pub(super) fn start_time(&self) -> Result<String> {
+        let mut created: FILETIME = unsafe { std::mem::zeroed() };
+        let mut exited = created;
+        let mut kernel = created;
+        let mut user = created;
+        if unsafe {
+            GetProcessTimes(
+                self.0.as_raw_handle() as _,
+                &mut created,
+                &mut exited,
+                &mut kernel,
+                &mut user,
+            )
+        } == 0
+        {
+            return Err(io::Error::last_os_error()).context("failed to query daemon creation time");
+        }
+        Ok(
+            ((u64::from(created.dwHighDateTime) << 32) | u64::from(created.dwLowDateTime))
+                .to_string(),
+        )
+    }
+
+    pub(super) fn is_running(&self) -> Result<bool> {
+        match unsafe {
+            WaitForSingleObject(self.0.as_raw_handle() as _, /*dwmilliseconds*/ 0)
+        } {
+            WAIT_TIMEOUT => Ok(true),
+            WAIT_OBJECT_0 => Ok(false),
+            _ => Err(io::Error::last_os_error()).context("failed to wait for daemon process"),
+        }
+    }
+
+    pub(super) fn ensure_detached(&self) -> Result<()> {
+        let mut in_job = 0;
+        if unsafe {
+            IsProcessInJob(
+                self.0.as_raw_handle() as _,
+                /*jobhandle*/ 0,
+                &mut in_job,
+            )
+        } == 0
+        {
+            let error = io::Error::last_os_error();
+            self.terminate()?;
+            return Err(error).context("failed to verify daemon detachment");
+        }
+        if in_job != 0 {
+            self.terminate()?;
+            anyhow::bail!(
+                "host Job Object prevents daemon detachment; start from a host that allows breakaway"
+            );
+        }
+        Ok(())
+    }
+
+    pub(super) fn terminate(&self) -> Result<()> {
+        if !self.is_running()? {
+            return Ok(());
+        }
+        let pid = unsafe { GetProcessId(self.0.as_raw_handle() as _) };
+        let Some(target) = Self::open_with_access(
+            pid,
+            PROCESS_QUERY_LIMITED_INFORMATION | PROCESS_SYNCHRONIZE | PROCESS_TERMINATE,
+        )?
+        else {
+            return Ok(());
+        };
+        // Keep the original identity handle alive and validate the handle that
+        // will actually be terminated, rather than trusting a second PID lookup.
+        if target.start_time()? != self.start_time()? || !target.is_running()? {
+            return Ok(());
+        }
+        if unsafe {
+            TerminateProcess(target.0.as_raw_handle() as _, /*uexitcode*/ 1)
+        } == 0
+        {
+            return Err(io::Error::last_os_error()).context("failed to terminate daemon process");
+        }
+        Ok(())
+    }
+}
+
+pub(crate) fn try_lock_file(file: &tokio::fs::File) -> Result<bool> {
+    let mut overlapped = unsafe { std::mem::zeroed() };
+    if unsafe {
+        LockFileEx(
+            file.as_raw_handle() as _,
+            LOCKFILE_EXCLUSIVE_LOCK | LOCKFILE_FAIL_IMMEDIATELY,
+            /*dwreserved*/ 0,
+            /*nnumberofbytestolocklow*/ 1,
+            /*nnumberofbytestolockhigh*/ 0,
+            &mut overlapped,
+        )
+    } != 0
+    {
+        return Ok(true);
+    }
+    let err = io::Error::last_os_error();
+    if err.raw_os_error() == Some(ERROR_LOCK_VIOLATION as i32) {
+        return Ok(false);
+    }
+    Err(err).context("failed to lock daemon state")
+}
+
+// Keep installer descendants bounded by the updater's lifetime, while allowing
+// app-server launches and successor updaters to break away from this job.
+pub(crate) fn updater_job() -> Result<OwnedHandle> {
+    process_job(unsafe { GetCurrentProcess() })
+}
+
+/// Called before writing the installer script, while PowerShell is waiting on stdin.
+pub(crate) fn installer_job(child: &tokio::process::Child) -> Result<OwnedHandle> {
+    let process = child
+        .raw_handle()
+        .context("installer process handle is unavailable")?;
+    process_job(process as isize)
+}
+
+fn process_job(process: isize) -> Result<OwnedHandle> {
+    let job = unsafe { CreateJobObjectW(std::ptr::null(), std::ptr::null()) };
+    if job == 0 {
+        return Err(io::Error::last_os_error()).context("failed to create updater job");
+    }
+    let owned = unsafe { OwnedHandle::from_raw_handle(job as _) };
+    let mut limits: JOBOBJECT_EXTENDED_LIMIT_INFORMATION = unsafe { std::mem::zeroed() };
+    limits.BasicLimitInformation.LimitFlags =
+        JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE | JOB_OBJECT_LIMIT_BREAKAWAY_OK;
+    if unsafe {
+        SetInformationJobObject(
+            job,
+            JobObjectExtendedLimitInformation,
+            (&limits as *const JOBOBJECT_EXTENDED_LIMIT_INFORMATION).cast(),
+            std::mem::size_of_val(&limits) as u32,
+        )
+    } == 0
+        || unsafe { AssignProcessToJobObject(job, process) } == 0
+    {
+        return Err(io::Error::last_os_error())
+            .context("failed to contain updater installer processes");
+    }
+    Ok(owned)
+}
+
+#[cfg(test)]
+#[path = "windows_tests.rs"]
+mod tests;

codex-rs/app-server-daemon/src/backend/windows_tests.rs

@@ -0,0 +1,87 @@
+use super::Process;
+use pretty_assertions::assert_eq;
+use std::os::windows::io::AsRawHandle;
+use windows_sys::Win32::Foundation::ERROR_ACCESS_DENIED;
+use windows_sys::Win32::System::Threading::CREATE_NO_WINDOW;
+use windows_sys::Win32::System::Threading::TerminateProcess;
+
+#[test]
+fn detached_launch_preflight_rejects_restrictive_job() {
+    const CHILD: &str = "CODEX_TEST_RESTRICTIVE_LAUNCH_JOB";
+    let executable = std::env::current_exe().expect("test executable");
+    if std::env::var_os(CHILD).is_some() {
+        let job = unsafe { super::CreateJobObjectW(std::ptr::null(), std::ptr::null()) };
+        assert_ne!(job, 0);
+        let job = unsafe {
+            <std::os::windows::io::OwnedHandle as std::os::windows::io::FromRawHandle>::from_raw_handle(job as _)
+        };
+        assert_ne!(
+            unsafe {
+                super::AssignProcessToJobObject(
+                    job.as_raw_handle() as _,
+                    super::GetCurrentProcess(),
+                )
+            },
+            0
+        );
+        // A new job does not permit breakaway. Reject before any lifecycle mutation.
+        assert!(super::ensure_detached_launch(&executable).is_err());
+        return;
+    }
+    let output = std::process::Command::new(executable)
+        .args([
+            "--exact",
+            "backend::windows::tests::detached_launch_preflight_rejects_restrictive_job",
+            "--nocapture",
+        ])
+        .env(CHILD, "1")
+        .output()
+        .expect("isolated job test");
+    assert!(
+        output.status.success(),
+        "{}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    assert!(String::from_utf8_lossy(&output.stdout).contains("1 passed"));
+}
+
+#[tokio::test]
+async fn identity_queries_do_not_require_termination_access() {
+    let mut child = tokio::process::Command::new("powershell.exe")
+        .args([
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            "Start-Sleep 60",
+        ])
+        .creation_flags(CREATE_NO_WINDOW)
+        .kill_on_drop(true)
+        .spawn()
+        .expect("child");
+    let process = Process::open(child.id().expect("pid"))
+        .expect("query handle")
+        .expect("live process");
+    assert!(!process.start_time().expect("creation time").is_empty());
+    assert!(process.is_running().expect("liveness"));
+    // Check the rights on the actual query handle, independent of privileges
+    // that could let the caller reopen the process with termination access.
+    assert_eq!(
+        unsafe {
+            TerminateProcess(process.0.as_raw_handle() as _, /*uexitcode*/ 1)
+        },
+        0
+    );
+    assert_eq!(
+        std::io::Error::last_os_error().raw_os_error(),
+        Some(ERROR_ACCESS_DENIED as i32)
+    );
+    assert!(
+        process
+            .is_running()
+            .expect("query must not terminate child")
+    );
+    child
+        .kill()
+        .await
+        .expect("cleanup through original spawn handle");
+}

codex-rs/app-server-daemon/src/client.rs

@@ -0,0 +1,207 @@
+use std::path::Path;
+use std::time::Duration;
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::anyhow;
+use codex_app_server_protocol::ClientInfo;
+use codex_app_server_protocol::InitializeCapabilities;
+use codex_app_server_protocol::InitializeParams;
+use codex_app_server_protocol::InitializeResponse;
+use codex_app_server_protocol::JSONRPCMessage;
+use codex_app_server_protocol::JSONRPCNotification;
+use codex_app_server_protocol::JSONRPCRequest;
+use codex_app_server_protocol::RequestId;
+use codex_uds::UnixStream;
+use futures::SinkExt;
+use futures::StreamExt;
+use tokio::io::AsyncRead;
+use tokio::io::AsyncWrite;
+use tokio::time::timeout;
+use tokio_tungstenite::WebSocketStream;
+use tokio_tungstenite::client_async;
+use tokio_tungstenite::tungstenite::Message;
+
+pub(crate) const CONTROL_SOCKET_RESPONSE_TIMEOUT: Duration = Duration::from_secs(2);
+const CLIENT_NAME: &str = "codex_app_server_daemon";
+const INITIALIZE_REQUEST_ID: RequestId = RequestId::Integer(1);
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct ProbeInfo {
+    pub(crate) app_server_version: String,
+}
+
+pub(crate) async fn probe(socket_path: &Path) -> Result<ProbeInfo> {
+    timeout(CONTROL_SOCKET_RESPONSE_TIMEOUT, probe_inner(socket_path))
+        .await
+        .with_context(|| {
+            format!(
+                "timed out probing app-server control socket {}",
+                socket_path.display()
+            )
+        })?
+}
+
+async fn probe_inner(socket_path: &Path) -> Result<ProbeInfo> {
+    let mut websocket = connect(socket_path).await?;
+
+    let initialize_response = initialize(&mut websocket, /*experimental_api*/ false).await?;
+    let initialized = JSONRPCMessage::Notification(JSONRPCNotification {
+        method: "initialized".to_string(),
+        params: None,
+    });
+    send_message(&mut websocket, &initialized)
+        .await
+        .context("failed to send initialized notification")?;
+    websocket.close(None).await.ok();
+
+    Ok(ProbeInfo {
+        app_server_version: parse_version_from_user_agent(&initialize_response.user_agent)?,
+    })
+}
+
+pub(crate) async fn connect(socket_path: &Path) -> Result<WebSocketStream<UnixStream>> {
+    connect_at(socket_path, "ws://localhost/").await
+}
+
+async fn connect_at(socket_path: &Path, url: &str) -> Result<WebSocketStream<UnixStream>> {
+    let stream = UnixStream::connect(socket_path)
+        .await
+        .with_context(|| format!("failed to connect to {}", socket_path.display()))?;
+    let (websocket, _response) = client_async(url, stream)
+        .await
+        .with_context(|| format!("failed to upgrade {}", socket_path.display()))?;
+    Ok(websocket)
+}
+
+#[cfg(windows)]
+pub(crate) async fn request_shutdown(socket_path: &Path, pid: u32) -> Result<()> {
+    timeout(CONTROL_SOCKET_RESPONSE_TIMEOUT, async {
+        let mut websocket = connect_at(socket_path, "ws://localhost/daemon/shutdown").await?;
+        websocket
+            .send(Message::Text(pid.to_string().into()))
+            .await?;
+        let reply = websocket
+            .next()
+            .await
+            .context("shutdown socket closed without acknowledgment")??;
+        anyhow::ensure!(
+            matches!(reply, Message::Text(ack) if ack == pid.to_string()),
+            "shutdown acknowledgment did not match the managed process {pid}"
+        );
+        websocket.close(None).await?;
+        Ok(())
+    })
+    .await
+    .context("timed out waiting for managed app-server shutdown acknowledgment")?
+}
+
+pub(crate) async fn initialize<S>(
+    websocket: &mut WebSocketStream<S>,
+    experimental_api: bool,
+) -> Result<InitializeResponse>
+where
+    S: AsyncRead + AsyncWrite + Unpin,
+{
+    let initialize = JSONRPCMessage::Request(JSONRPCRequest {
+        id: INITIALIZE_REQUEST_ID,
+        method: "initialize".to_string(),
+        params: Some(serde_json::to_value(InitializeParams {
+            client_info: ClientInfo {
+                name: CLIENT_NAME.to_string(),
+                title: Some("Codex App Server Daemon".to_string()),
+                version: env!("CARGO_PKG_VERSION").to_string(),
+            },
+            capabilities: if experimental_api {
+                Some(InitializeCapabilities {
+                    experimental_api: true,
+                    ..Default::default()
+                })
+            } else {
+                None
+            },
+        })?),
+        trace: None,
+    });
+    send_message(websocket, &initialize)
+        .await
+        .context("failed to send initialize request")?;
+
+    let response = loop {
+        let message = timeout(CONTROL_SOCKET_RESPONSE_TIMEOUT, read_message(websocket))
+            .await
+            .context("timed out waiting for initialize response")??;
+        if let JSONRPCMessage::Response(response) = message
+            && response.id == INITIALIZE_REQUEST_ID
+        {
+            break response;
+        }
+    };
+    serde_json::from_value::<InitializeResponse>(response.result)
+        .context("failed to parse initialize response")
+}
+
+pub(crate) async fn send_message<S>(
+    websocket: &mut WebSocketStream<S>,
+    message: &JSONRPCMessage,
+) -> Result<()>
+where
+    S: AsyncRead + AsyncWrite + Unpin,
+{
+    websocket
+        .send(Message::Text(serde_json::to_string(message)?.into()))
+        .await?;
+    Ok(())
+}
+
+pub(crate) async fn read_message<S>(websocket: &mut WebSocketStream<S>) -> Result<JSONRPCMessage>
+where
+    S: AsyncRead + AsyncWrite + Unpin,
+{
+    loop {
+        let frame = websocket
+            .next()
+            .await
+            .ok_or_else(|| anyhow!("app-server closed the control socket"))??;
+        let Message::Text(payload) = frame else {
+            continue;
+        };
+        return serde_json::from_str::<JSONRPCMessage>(&payload)
+            .context("failed to parse app-server JSON-RPC message");
+    }
+}
+
+fn parse_version_from_user_agent(user_agent: &str) -> Result<String> {
+    let (_originator, rest) = user_agent
+        .split_once('/')
+        .ok_or_else(|| anyhow!("app-server user-agent omitted version separator"))?;
+    let version = rest
+        .split_whitespace()
+        .next()
+        .filter(|version| !version.is_empty())
+        .ok_or_else(|| anyhow!("app-server user-agent omitted version"))?;
+    Ok(version.to_string())
+}
+
+#[cfg(all(test, unix))]
+mod tests {
+    use pretty_assertions::assert_eq;
+
+    use super::parse_version_from_user_agent;
+
+    #[test]
+    fn parses_version_from_codex_user_agent() {
+        assert_eq!(
+            parse_version_from_user_agent(
+                "codex_app_server_daemon/1.2.3 (Linux 6.8.0; x86_64) codex_cli_rs/1.2.3",
+            )
+            .expect("version"),
+            "1.2.3"
+        );
+    }
+
+    #[test]
+    fn rejects_user_agent_without_version() {
+        assert!(parse_version_from_user_agent("codex_app_server_daemon").is_err());
+    }
+}

codex-rs/app-server-daemon/src/install_lock.rs

@@ -0,0 +1,143 @@
+//! Coordinates package selection with the shell and PowerShell installers.
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::anyhow;
+use std::fs::OpenOptions;
+use std::path::Path;
+use std::time::Duration;
+use tokio::time::sleep;
+
+pub(crate) struct InstallLock {
+    _file: Option<tokio::fs::File>,
+    directory: Option<std::path::PathBuf>,
+    _directory_owner: Option<tempfile::TempDir>,
+}
+
+impl Drop for InstallLock {
+    fn drop(&mut self) {
+        if let Some(directory) = &self.directory {
+            let _ = std::fs::remove_file(directory);
+        }
+    }
+}
+
+pub(crate) async fn acquire_install_lock(root: &Path) -> Result<InstallLock> {
+    let lock = root.join("install.lock");
+    let deadline = tokio::time::Instant::now() + Duration::from_secs(30);
+    #[cfg(unix)]
+    let use_lockf = {
+        // Match the installer so both processes coordinate on the same lock.
+        let choice = tokio::process::Command::new("/bin/sh")
+            .args(["-c", if cfg!(target_os = "macos") {
+                "if command -v lockf >/dev/null 2>&1; then exit 0; elif command -v flock >/dev/null 2>&1; then exit 1; else exit 2; fi"
+            } else {
+                "if command -v flock >/dev/null 2>&1; then exit 1; else exit 2; fi"
+            }])
+            .status().await?;
+        match choice.code() {
+            Some(0) => true,
+            Some(1) => false,
+            Some(2) => {
+                let directory = root.join("install.lock.d");
+                // Publish complete metadata atomically. Older shell installers
+                // immediately remove an empty lock directory as stale.
+                let owner = tempfile::Builder::new()
+                    .prefix("install-lock-")
+                    .tempdir_in(root)?;
+                std::fs::write(owner.path().join("pid"), std::process::id().to_string())?;
+                let now = std::time::SystemTime::now()
+                    .duration_since(std::time::UNIX_EPOCH)?
+                    .as_secs();
+                std::fs::write(owner.path().join("started_at"), now.to_string())?;
+                loop {
+                    match std::os::unix::fs::symlink(owner.path(), &directory) {
+                        Ok(()) => {
+                            return Ok(InstallLock {
+                                _file: None,
+                                directory: Some(directory),
+                                _directory_owner: Some(owner),
+                            });
+                        }
+                        Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => {}
+                        Err(error) => {
+                            return Err(error)
+                                .context("failed to acquire daemon installer directory lock");
+                        }
+                    }
+                    let pid = std::fs::read_to_string(directory.join("pid"))
+                        .ok()
+                        .and_then(|pid| pid.trim().parse::<i32>().ok())
+                        .filter(|pid| *pid > 0);
+                    let dead = pid.is_none_or(|pid| unsafe { libc::kill(pid, 0) } != 0
+                        && std::io::Error::last_os_error().raw_os_error() == Some(libc::ESRCH));
+                    let age = std::fs::metadata(&directory)
+                        .and_then(|metadata| metadata.modified())
+                        .ok()
+                        .and_then(|modified| modified.elapsed().ok())
+                        .unwrap_or_default();
+                    // Allow the creator time to publish its PID; match the installer's
+                    // ten-minute stale-lock grace instead of stealing an active lock.
+                    if dead && age >= Duration::from_secs(600) {
+                        std::fs::remove_dir_all(&directory)?;
+                        continue;
+                    }
+                    anyhow::ensure!(
+                        tokio::time::Instant::now() < deadline,
+                        "timed out waiting for daemon installer lock {}",
+                        directory.display()
+                    );
+                    sleep(Duration::from_millis(50)).await;
+                }
+            }
+            _ => return Err(anyhow!("failed to detect daemon installer lock tools")),
+        }
+    };
+    let mut options = OpenOptions::new();
+    options.create(true).truncate(false).write(true);
+    #[cfg(windows)]
+    {
+        use std::os::windows::fs::OpenOptionsExt;
+        options.share_mode(0);
+    }
+    loop {
+        let acquired = options.open(&lock);
+        #[cfg(unix)]
+        let acquired = acquired.and_then(|file| {
+            {
+                use std::os::fd::AsRawFd;
+                let result = if use_lockf {
+                    unsafe { libc::lockf(file.as_raw_fd(), libc::F_TLOCK, 0) }
+                } else {
+                    unsafe { libc::flock(file.as_raw_fd(), libc::LOCK_EX | libc::LOCK_NB) }
+                };
+                if result != 0 {
+                    return Err(std::io::Error::last_os_error());
+                }
+            }
+            Ok(file)
+        });
+        match acquired {
+            Ok(file) => {
+                return Ok(InstallLock {
+                    _file: Some(tokio::fs::File::from_std(file)),
+                    directory: None,
+                    _directory_owner: None,
+                });
+            }
+            Err(error)
+                if error.kind() == std::io::ErrorKind::WouldBlock
+                    || cfg!(windows)
+                        && (error.raw_os_error() == Some(32)
+                            || error.kind() == std::io::ErrorKind::PermissionDenied) => {}
+            Err(error) => return Err(error).context("failed to acquire daemon installer lock"),
+        }
+        if tokio::time::Instant::now() >= deadline {
+            return Err(anyhow!(
+                "timed out waiting for daemon installer lock {}",
+                lock.display()
+            ));
+        }
+        sleep(Duration::from_millis(50)).await;
+    }
+}

codex-rs/app-server-daemon/src/lib.rs

@@ -0,0 +1,1400 @@
+//! Managed app-server lifecycle, serialized across CLI invocations and the updater.
+
+mod backend;
+#[cfg(windows)]
+use backend::windows::try_lock_file;
+mod client;
+mod install_lock;
+mod managed_install;
+mod prepare_install;
+pub use prepare_install::InstallRequest;
+pub use prepare_install::update_from_cli;
+mod remote_control_client;
+mod settings;
+mod thread_recovery;
+mod update_loop;
+
+use std::path::Path;
+use std::path::PathBuf;
+use std::time::Duration;
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::anyhow;
+pub use backend::BackendKind;
+use backend::BackendPaths;
+use codex_app_server_protocol::RemoteControlConnectionStatus;
+use codex_app_server_protocol::RemoteControlPairingStartResponse;
+use codex_app_server_transport::app_server_control_socket_path;
+use codex_utils_home_dir::find_codex_home;
+use managed_install::managed_codex_bin;
+#[cfg(any(unix, windows))]
+use managed_install::managed_codex_version;
+use serde::Serialize;
+use settings::DaemonSettings;
+use settings::MAX_SHUTDOWN_GRACE_SECONDS;
+use tokio::time::sleep;
+
+const START_POLL_INTERVAL: Duration = Duration::from_millis(50);
+const START_TIMEOUT: Duration = Duration::from_secs(10);
+// Leave room for the longest graceful stop, forced-exit check, and restart.
+const OPERATION_LOCK_TIMEOUT: Duration =
+    Duration::from_secs(MAX_SHUTDOWN_GRACE_SECONDS as u64 + 75);
+const LEGACY_PID_FILE_NAME: &str = "app-server.pid";
+const LEGACY_UPDATE_PID_FILE_NAME: &str = "app-server-updater.pid";
+const DAEMON_PID_FILE_NAME: &str = "daemon.pid";
+const DAEMON_UPDATE_PID_FILE_NAME: &str = "daemon-updater.pid";
+const OPERATION_LOCK_FILE_NAME: &str = "daemon.lock";
+const SETTINGS_FILE_NAME: &str = "settings.json";
+const STATE_DIR_NAME: &str = "app-server-daemon";
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum LifecycleCommand {
+    Start,
+    Restart,
+    Stop,
+    Version,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub enum LifecycleStatus {
+    AlreadyRunning,
+    Started,
+    Restarted,
+    Stopped,
+    NotRunning,
+    Running,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct LifecycleOutput {
+    pub status: LifecycleStatus,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub backend: Option<BackendKind>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub pid: Option<u32>,
+    pub managed_codex_path: PathBuf,
+    pub managed_codex_version: Option<String>,
+    pub socket_path: PathBuf,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub cli_version: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub app_server_version: Option<String>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct BootstrapOptions {
+    pub remote_control_enabled: bool,
+}
+
+/// Passively probes an existing app-server socket and returns its reported
+/// app-server version.
+pub async fn probe_app_server_version(socket_path: &Path) -> Result<String> {
+    Ok(client::probe(socket_path).await?.app_server_version)
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub enum BootstrapStatus {
+    Bootstrapped,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct BootstrapOutput {
+    pub status: BootstrapStatus,
+    pub backend: BackendKind,
+    pub auto_update_enabled: bool,
+    pub remote_control_enabled: bool,
+    pub managed_codex_path: PathBuf,
+    pub managed_codex_version: Option<String>,
+    pub socket_path: PathBuf,
+    pub cli_version: String,
+    pub app_server_version: String,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, serde::Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub enum UpdateStatus {
+    Updated,
+    NoUpdate,
+    Unsupported,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, serde::Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct UpdateOutput {
+    pub status: UpdateStatus,
+    pub managed_codex_path: PathBuf,
+    pub installed_version: Option<String>,
+    pub running_version: Option<String>,
+    pub message: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(untagged)]
+pub enum RemoteControlStartOutput {
+    Bootstrap(BootstrapOutput),
+    Start(LifecycleOutput),
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RemoteControlReadyStatus {
+    pub status: RemoteControlConnectionStatus,
+    pub server_name: String,
+    pub environment_id: Option<String>,
+    pub timed_out: bool,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RemoteControlReadyOutput {
+    pub daemon: RemoteControlStartOutput,
+    pub remote_control: RemoteControlReadyStatus,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RemoteControlMode {
+    Enabled,
+    Disabled,
+}
+
+impl RemoteControlMode {
+    fn is_enabled(self) -> bool {
+        matches!(self, Self::Enabled)
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub enum RemoteControlStatus {
+    Enabled,
+    Disabled,
+    AlreadyEnabled,
+    AlreadyDisabled,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RemoteControlOutput {
+    pub status: RemoteControlStatus,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub backend: Option<BackendKind>,
+    pub remote_control_enabled: bool,
+    pub socket_path: PathBuf,
+    pub cli_version: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub app_server_version: Option<String>,
+}
+
+#[cfg(any(unix, windows))]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum RestartIfRunningOutcome {
+    Busy,
+    NotRunning,
+    NotReady,
+    AlreadyCurrent,
+    Restarted,
+}
+
+#[cfg(any(unix, windows))]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum RestartMode {
+    IfVersionChanged,
+    IfBinaryOrVersionChanged,
+    Always,
+}
+
+#[cfg(any(unix, windows))]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum RestartDecision {
+    NotReady,
+    AlreadyCurrent,
+    Restart,
+}
+
+pub async fn run(command: LifecycleCommand) -> Result<LifecycleOutput> {
+    ensure_supported_platform()?;
+    #[cfg(windows)]
+    if matches!(command, LifecycleCommand::Start | LifecycleCommand::Restart) {
+        backend::windows::ensure_not_elevated()?;
+    }
+    // Keep daemon package preparation off callers' async stack frames.
+    Box::pin(Daemon::from_environment()?.run(command)).await
+}
+
+pub async fn bootstrap(options: BootstrapOptions) -> Result<BootstrapOutput> {
+    ensure_supported_platform()?;
+    #[cfg(windows)]
+    backend::windows::ensure_not_elevated()?;
+    Box::pin(Daemon::from_environment()?.bootstrap(options)).await
+}
+
+pub async fn ensure_remote_control_ready() -> Result<RemoteControlReadyOutput> {
+    ensure_supported_platform()?;
+    #[cfg(windows)]
+    backend::windows::ensure_not_elevated()?;
+    Box::pin(Daemon::from_environment()?.ensure_remote_control_ready()).await
+}
+
+pub async fn enable_remote_control_on_socket(
+    socket_path: &Path,
+    connect_timeout: Duration,
+    connect_retry_delay: Duration,
+) -> Result<RemoteControlReadyStatus> {
+    ensure_supported_platform()?;
+    remote_control_client::enable_remote_control_with_connect_retry(
+        socket_path,
+        connect_timeout,
+        connect_retry_delay,
+    )
+    .await
+}
+
+/// Starts a manual pairing session through an already-running daemon app-server.
+pub async fn start_remote_control_pairing() -> Result<RemoteControlPairingStartResponse> {
+    ensure_supported_platform()?;
+    let daemon = Daemon::from_environment()?;
+    remote_control_client::start_pairing(&daemon.socket_path).await
+}
+
+pub async fn set_remote_control(mode: RemoteControlMode) -> Result<RemoteControlOutput> {
+    ensure_supported_platform()?;
+    #[cfg(windows)]
+    backend::windows::ensure_not_elevated()?;
+    Box::pin(Daemon::from_environment()?.set_remote_control(mode)).await
+}
+
+pub async fn run_pid_update_loop(
+    http_client_factory: codex_http_client::HttpClientFactory,
+    restore_release: Option<String>,
+) -> Result<()> {
+    ensure_supported_platform()?;
+    #[cfg(windows)]
+    backend::windows::ensure_not_elevated()?;
+    update_loop::run(http_client_factory, restore_release).await
+}
+
+pub async fn update(
+    http_client_factory: codex_http_client::HttpClientFactory,
+) -> Result<UpdateOutput> {
+    ensure_supported_platform()?;
+    #[cfg(windows)]
+    backend::windows::ensure_not_elevated()?;
+    update_loop::request_manual_update(&Daemon::from_environment()?, http_client_factory).await
+}
+
+#[cfg(any(unix, windows))]
+fn ensure_supported_platform() -> Result<()> {
+    Ok(())
+}
+
+#[cfg(not(any(unix, windows)))]
+fn ensure_supported_platform() -> Result<()> {
+    Err(anyhow!(
+        "codex app-server daemon lifecycle is only supported on Unix and Windows platforms"
+    ))
+}
+
+#[derive(Clone)]
+struct Daemon {
+    socket_path: PathBuf,
+    pid_file: PathBuf,
+    update_pid_file: PathBuf,
+    operation_lock_file: PathBuf,
+    settings_file: PathBuf,
+    managed_codex_bin: PathBuf,
+}
+
+impl Daemon {
+    fn from_environment() -> Result<Self> {
+        let codex_home = find_codex_home().context("failed to resolve CODEX_HOME")?;
+        let socket_path = app_server_control_socket_path(codex_home.as_path())?
+            .as_path()
+            .to_path_buf();
+        let state_dir = codex_home.as_path().join(STATE_DIR_NAME);
+        let managed_codex_bin = managed_codex_bin(codex_home.as_path());
+        // Old CLIs must not mistake a daemon-owned installation for their backend.
+        let (pid_file, update_pid_file) =
+            if managed_codex_bin.starts_with(codex_home.as_path().join("packages/standalone")) {
+                (LEGACY_PID_FILE_NAME, LEGACY_UPDATE_PID_FILE_NAME)
+            } else {
+                (DAEMON_PID_FILE_NAME, DAEMON_UPDATE_PID_FILE_NAME)
+            };
+        Ok(Self {
+            socket_path,
+            pid_file: state_dir.join(pid_file),
+            update_pid_file: state_dir.join(update_pid_file),
+            operation_lock_file: state_dir.join(OPERATION_LOCK_FILE_NAME),
+            settings_file: state_dir.join(SETTINGS_FILE_NAME),
+            managed_codex_bin,
+        })
+    }
+
+    fn recovery_file(&self) -> Result<PathBuf> {
+        Ok(codex_app_server_transport::daemon_recovery_file_path(
+            self.settings_file
+                .parent()
+                .and_then(Path::parent)
+                .context("daemon settings path has no Codex home")?,
+        ))
+    }
+
+    // Call only after taking the operation lock: an explicit update may have
+    // migrated the package and PID namespace while this command was waiting.
+    fn current_installation(&self) -> Result<Self> {
+        let managed_codex_bin = self.current_managed_codex_bin()?;
+        let home = self
+            .settings_file
+            .parent()
+            .and_then(Path::parent)
+            .context("daemon settings path has no Codex home")?;
+        let (pid, updater) = if managed_codex_bin.starts_with(home.join("packages/standalone")) {
+            (LEGACY_PID_FILE_NAME, LEGACY_UPDATE_PID_FILE_NAME)
+        } else {
+            (DAEMON_PID_FILE_NAME, DAEMON_UPDATE_PID_FILE_NAME)
+        };
+        Ok(Self {
+            managed_codex_bin,
+            pid_file: self.pid_file.with_file_name(pid),
+            update_pid_file: self.update_pid_file.with_file_name(updater),
+            ..self.clone()
+        })
+    }
+
+    async fn run(&self, command: LifecycleCommand) -> Result<LifecycleOutput> {
+        if command == LifecycleCommand::Version {
+            return self.version().await;
+        }
+        let _operation_lock = self.acquire_operation_lock().await?;
+        let selected = self.current_installation()?;
+        match command {
+            LifecycleCommand::Start => selected.start().await,
+            LifecycleCommand::Restart => selected.restart().await,
+            LifecycleCommand::Stop => {
+                let output = selected.stop().await?;
+                if let Err(err) = thread_recovery::discard_pending(&selected) {
+                    eprintln!("warning: failed to clear saved threads after daemon stop: {err}");
+                }
+                Ok(output)
+            }
+            LifecycleCommand::Version => unreachable!(),
+        }
+    }
+
+    async fn start(&self) -> Result<LifecycleOutput> {
+        let mut managed = self.clone();
+        let settings = self.load_settings().await?;
+        let (status, backend, pid, info) = if let Ok(info) = client::probe(&self.socket_path).await
+        {
+            (
+                LifecycleStatus::AlreadyRunning,
+                self.running_backend(&settings).await?,
+                None,
+                info,
+            )
+        } else if self.running_backend_instance(&settings).await?.is_some() {
+            (
+                LifecycleStatus::AlreadyRunning,
+                Some(BackendKind::Pid),
+                None,
+                self.wait_until_ready().await?,
+            )
+        } else {
+            // A fresh start must ignore snapshots left by older stop clients.
+            if let Err(err) = thread_recovery::discard_pending(self) {
+                eprintln!("warning: failed to clear stale daemon recovery before start: {err}");
+            }
+            prepare_install::prepare(self, &settings).await?;
+            managed.managed_codex_bin = self.current_managed_codex_bin()?;
+            managed.ensure_managed_codex_bin()?;
+            let pid = managed.start_managed_backend(&settings).await?;
+            (
+                LifecycleStatus::Started,
+                Some(BackendKind::Pid),
+                pid,
+                self.wait_until_ready().await?,
+            )
+        };
+        if backend.is_some()
+            && let Err(err) = managed.ensure_managed_updater(&settings).await
+        {
+            eprintln!("warning: failed to ensure managed updater after app-server start: {err:#}");
+        }
+        Ok(managed
+            .output(status, backend, pid, Some(info.app_server_version))
+            .await)
+    }
+
+    async fn restart(&self) -> Result<LifecycleOutput> {
+        let settings = self.load_settings().await?;
+        if client::probe(&self.socket_path).await.is_ok()
+            && self.running_backend(&settings).await?.is_none()
+        {
+            return Err(anyhow!(
+                "app server is running but is not managed by codex app-server daemon"
+            ));
+        }
+        prepare_install::prepare(self, &settings).await?;
+        let mut managed = self.clone();
+        managed.managed_codex_bin = self.current_managed_codex_bin()?;
+        if !settings.auto_update_enabled {
+            backend::pid_update_loop_backend(self.backend_paths(&settings))
+                .stop()
+                .await?;
+        }
+
+        managed.ensure_managed_codex_bin()?;
+        if let Some(backend) = self.running_backend_instance(&settings).await? {
+            if let Err(err) = thread_recovery::discard_pending(self) {
+                eprintln!("warning: failed to clear stale daemon recovery before restart: {err}");
+            }
+            backend
+                .stop_with_grace(settings.shutdown_grace_seconds)
+                .await?;
+        }
+
+        let pid = managed.start_managed_backend(&settings).await?;
+        let info = self.wait_until_ready().await?;
+        if let Err(err) = managed.ensure_managed_updater(&settings).await {
+            eprintln!(
+                "warning: failed to ensure managed updater after app-server restart: {err:#}"
+            );
+        }
+        Ok(managed
+            .output(
+                LifecycleStatus::Restarted,
+                Some(BackendKind::Pid),
+                pid,
+                Some(info.app_server_version),
+            )
+            .await)
+    }
+
+    #[cfg(any(unix, windows))]
+    pub(crate) async fn try_restart_if_running(
+        &self,
+        mode: RestartMode,
+        managed_codex_bin: &Path,
+    ) -> Result<RestartIfRunningOutcome> {
+        let operation_lock = self.open_operation_lock_file().await?;
+        if !try_lock_file(&operation_lock)? {
+            return Ok(RestartIfRunningOutcome::Busy);
+        }
+        let settings = self.load_settings().await?;
+        let outcome = if let Some(backend) = self.running_backend_instance(&settings).await? {
+            let info = client::probe(&self.socket_path).await.ok();
+            let managed_version = if info.is_some() {
+                Some(managed_codex_version(managed_codex_bin).await?)
+            } else {
+                None
+            };
+            // The installer can retarget `current` while the updater waits for
+            // this lock or probes the running server. Never restart from a
+            // release that is no longer the selected latest-channel binary.
+            if !self.is_stable_standalone_release()?
+                || managed_install::resolved_managed_codex_bin(&self.current_managed_codex_bin()?)
+                    .await
+                    .ok()
+                    .as_deref()
+                    != Some(managed_codex_bin)
+            {
+                return Ok(RestartIfRunningOutcome::AlreadyCurrent);
+            }
+            let mode = if mode == RestartMode::IfBinaryOrVersionChanged {
+                let managed_identity =
+                    managed_install::executable_identity(managed_codex_bin).await?;
+                if backend.running_executable_identity().await?.as_ref() == Some(&managed_identity)
+                {
+                    RestartMode::IfVersionChanged
+                } else {
+                    RestartMode::Always
+                }
+            } else {
+                mode
+            };
+            match restart_decision(mode, info.as_ref(), managed_version.as_deref()) {
+                RestartDecision::NotReady => return Ok(RestartIfRunningOutcome::NotReady),
+                RestartDecision::AlreadyCurrent => RestartIfRunningOutcome::AlreadyCurrent,
+                RestartDecision::Restart => {
+                    #[cfg(windows)]
+                    backend::windows::ensure_detached_launch(managed_codex_bin)?;
+                    if let Err(err) = thread_recovery::discard_pending(self) {
+                        eprintln!(
+                            "warning: failed to clear stale daemon recovery before update: {err}"
+                        );
+                    }
+                    backend
+                        .stop_with_grace(settings.shutdown_grace_seconds)
+                        .await?;
+                    let _ = self
+                        .start_managed_backend_with_bin(&settings, managed_codex_bin)
+                        .await?;
+                    self.wait_until_ready().await?;
+                    RestartIfRunningOutcome::Restarted
+                }
+            }
+        } else if client::probe(&self.socket_path).await.is_ok() {
+            return Err(anyhow!(
+                "app server is running but is not managed by codex app-server daemon"
+            ));
+        } else {
+            RestartIfRunningOutcome::NotRunning
+        };
+
+        if !self.is_stable_standalone_release()?
+            || managed_install::resolved_managed_codex_bin(&self.current_managed_codex_bin()?)
+                .await
+                .ok()
+                .as_deref()
+                != Some(managed_codex_bin)
+        {
+            return Ok(RestartIfRunningOutcome::AlreadyCurrent);
+        }
+        Ok(outcome)
+    }
+
+    async fn stop(&self) -> Result<LifecycleOutput> {
+        let settings = DaemonSettings::load_for_stop(&self.settings_file).await;
+        if let Some(backend) = self.running_backend_instance(&settings).await? {
+            backend
+                .stop_with_grace(settings.shutdown_grace_seconds)
+                .await?;
+            return Ok(self
+                .output(
+                    LifecycleStatus::Stopped,
+                    Some(BackendKind::Pid),
+                    /*pid*/ None,
+                    /*app_server_version*/ None,
+                )
+                .await);
+        }
+
+        if client::probe(&self.socket_path).await.is_ok() {
+            return Err(anyhow!(
+                "app server is running but is not managed by codex app-server daemon"
+            ));
+        }
+
+        Ok(self
+            .output(
+                LifecycleStatus::NotRunning,
+                /*backend*/ None,
+                /*pid*/ None,
+                /*app_server_version*/ None,
+            )
+            .await)
+    }
+
+    async fn version(&self) -> Result<LifecycleOutput> {
+        let settings = self.load_settings().await?;
+        let info = client::probe(&self.socket_path).await?;
+        Ok(self
+            .output(
+                LifecycleStatus::Running,
+                self.running_backend(&settings).await?,
+                /*pid*/ None,
+                Some(info.app_server_version),
+            )
+            .await)
+    }
+
+    async fn wait_until_ready(&self) -> Result<client::ProbeInfo> {
+        let deadline = tokio::time::Instant::now() + START_TIMEOUT;
+        loop {
+            match client::probe(&self.socket_path).await {
+                Ok(info) => return Ok(info),
+                Err(err) if tokio::time::Instant::now() < deadline => {
+                    let _ = err;
+                    sleep(START_POLL_INTERVAL).await;
+                }
+                Err(err) => {
+                    let context = self.app_server_not_ready_context().await;
+                    return Err(err).context(context);
+                }
+            }
+        }
+    }
+
+    async fn app_server_not_ready_context(&self) -> String {
+        let mut context = format!(
+            "app server did not become ready on {}",
+            self.socket_path.display()
+        );
+        self.append_daemon_app_server_context(&mut context).await;
+        backend::append_stderr_log_tail_context(&self.pid_file, &mut context).await;
+        context
+    }
+
+    async fn append_daemon_app_server_context(&self, context: &mut String) {
+        let managed_codex_version = self
+            .managed_codex_version_best_effort()
+            .await
+            .unwrap_or_else(|| "unknown".to_string());
+        context.push_str(&format!(
+            "\n\nDaemon used app-server:\n  path: {}\n  version: {managed_codex_version}",
+            self.managed_codex_bin.display()
+        ));
+    }
+
+    async fn bootstrap(&self, options: BootstrapOptions) -> Result<BootstrapOutput> {
+        let _operation_lock = self.acquire_operation_lock().await?;
+        self.current_installation()?.bootstrap_locked(options).await
+    }
+
+    async fn ensure_remote_control_started(&self) -> Result<RemoteControlStartOutput> {
+        let _operation_lock = self.acquire_operation_lock().await?;
+        let selected = self.current_installation()?;
+        let settings = selected.load_settings().await?;
+        if selected.is_bootstrapped(&settings).await? {
+            let _ = selected
+                .set_remote_control_locked(RemoteControlMode::Enabled)
+                .await?;
+            let output = selected.start().await?;
+            return Ok(RemoteControlStartOutput::Start(output));
+        }
+
+        let output = selected
+            .bootstrap_locked(BootstrapOptions {
+                remote_control_enabled: true,
+            })
+            .await?;
+        Ok(RemoteControlStartOutput::Bootstrap(output))
+    }
+
+    async fn ensure_remote_control_ready(&self) -> Result<RemoteControlReadyOutput> {
+        let daemon = self.ensure_remote_control_started().await?;
+        let remote_control =
+            remote_control_client::enable_remote_control(&self.socket_path).await?;
+        Ok(RemoteControlReadyOutput {
+            daemon,
+            remote_control,
+        })
+    }
+
+    async fn set_remote_control(&self, mode: RemoteControlMode) -> Result<RemoteControlOutput> {
+        let _operation_lock = self.acquire_operation_lock().await?;
+        self.current_installation()?
+            .set_remote_control_locked(mode)
+            .await
+    }
+
+    async fn set_remote_control_locked(
+        &self,
+        mode: RemoteControlMode,
+    ) -> Result<RemoteControlOutput> {
+        let previous_settings = self.load_settings().await?;
+        let mut settings = previous_settings.clone();
+        let remote_control_enabled = mode.is_enabled();
+        let backend = self.running_backend_instance(&previous_settings).await?;
+
+        if backend.is_none() && client::probe(&self.socket_path).await.is_ok() {
+            return Err(anyhow!(
+                "app server is running but is not managed by codex app-server daemon"
+            ));
+        }
+
+        if settings.remote_control_enabled == remote_control_enabled {
+            let info = if backend.is_some() {
+                Some(self.wait_until_ready().await?)
+            } else {
+                None
+            };
+            if info.is_some() {
+                match mode {
+                    RemoteControlMode::Enabled => {
+                        remote_control_client::enable_remote_control(&self.socket_path).await?;
+                    }
+                    RemoteControlMode::Disabled => {
+                        remote_control_client::disable_remote_control(&self.socket_path).await?;
+                    }
+                }
+            }
+            return Ok(self.remote_control_output(
+                already_remote_control_status(mode),
+                backend.map(|_| BackendKind::Pid),
+                remote_control_enabled,
+                info.map(|info| info.app_server_version),
+            ));
+        }
+
+        if backend.is_some() {
+            self.ensure_managed_codex_bin()?;
+        }
+        settings.remote_control_enabled = remote_control_enabled;
+        settings.save(&self.settings_file).await?;
+
+        let app_server_version = if let Some(backend) = backend {
+            if let Err(err) = thread_recovery::discard_pending(self) {
+                eprintln!(
+                    "warning: failed to clear stale recovery before remote-control restart: {err}"
+                );
+            }
+            backend
+                .stop_with_grace(settings.shutdown_grace_seconds)
+                .await?;
+            let _ = self.start_managed_backend(&settings).await?;
+            let info = self.wait_until_ready().await?;
+            if let Err(err) = self.ensure_managed_updater(&settings).await {
+                eprintln!(
+                    "warning: failed to ensure managed updater after remote-control change: {err:#}"
+                );
+            }
+            Some(info.app_server_version)
+        } else {
+            None
+        };
+
+        Ok(self.remote_control_output(
+            remote_control_status(mode),
+            app_server_version.as_ref().map(|_| BackendKind::Pid),
+            remote_control_enabled,
+            app_server_version,
+        ))
+    }
+
+    async fn bootstrap_locked(&self, options: BootstrapOptions) -> Result<BootstrapOutput> {
+        let mut settings = self.load_settings().await?;
+        settings.remote_control_enabled = options.remote_control_enabled;
+        if client::probe(&self.socket_path).await.is_ok()
+            && self.running_backend(&settings).await?.is_none()
+        {
+            return Err(anyhow!(
+                "app server is running but is not managed by codex app-server daemon"
+            ));
+        }
+        prepare_install::prepare(self, &settings).await?;
+        let mut managed = self.clone();
+        managed.managed_codex_bin = self.current_managed_codex_bin()?;
+        managed.ensure_managed_codex_bin()?;
+        settings.save(&self.settings_file).await?;
+
+        backend::pid_update_loop_backend(self.backend_paths(&settings))
+            .stop()
+            .await?;
+        if let Some(backend) = self.running_backend_instance(&settings).await? {
+            if let Err(err) = thread_recovery::discard_pending(self) {
+                eprintln!("warning: failed to clear stale daemon recovery before bootstrap: {err}");
+            }
+            backend
+                .stop_with_grace(settings.shutdown_grace_seconds)
+                .await?;
+        }
+
+        let backend = backend::pid_backend(managed.backend_paths(&settings));
+        backend.start().await?;
+        let info = self.wait_until_ready().await?;
+        let auto_update_enabled = managed.ensure_managed_updater(&settings).await?;
+        let managed_codex_version = managed.managed_codex_version_best_effort().await;
+        Ok(BootstrapOutput {
+            status: BootstrapStatus::Bootstrapped,
+            backend: BackendKind::Pid,
+            auto_update_enabled,
+            remote_control_enabled: settings.remote_control_enabled,
+            managed_codex_path: managed.managed_codex_bin,
+            managed_codex_version,
+            socket_path: self.socket_path.clone(),
+            cli_version: env!("CARGO_PKG_VERSION").to_string(),
+            app_server_version: info.app_server_version,
+        })
+    }
+
+    async fn running_backend(&self, settings: &DaemonSettings) -> Result<Option<BackendKind>> {
+        Ok(self
+            .running_backend_instance(settings)
+            .await?
+            .map(|_| BackendKind::Pid))
+    }
+
+    async fn running_backend_instance(
+        &self,
+        settings: &DaemonSettings,
+    ) -> Result<Option<backend::PidBackend>> {
+        let backend = backend::pid_backend(self.backend_paths(settings));
+        if backend.is_starting_or_running().await? {
+            return Ok(Some(backend));
+        }
+        Ok(None)
+    }
+
+    async fn start_managed_backend(&self, settings: &DaemonSettings) -> Result<Option<u32>> {
+        self.start_managed_backend_with_bin(settings, &self.managed_codex_bin)
+            .await
+    }
+
+    async fn start_managed_backend_with_bin(
+        &self,
+        settings: &DaemonSettings,
+        managed_codex_bin: &Path,
+    ) -> Result<Option<u32>> {
+        let backend =
+            backend::pid_backend(self.backend_paths_with_bin(settings, managed_codex_bin));
+        backend.start().await
+    }
+
+    async fn ensure_managed_updater(&self, settings: &DaemonSettings) -> Result<bool> {
+        let updater = backend::pid_update_loop_backend(self.backend_paths(settings));
+        if !settings.auto_update_enabled {
+            updater.stop().await?;
+            return Ok(false);
+        }
+        if !self.is_stable_standalone_release()? {
+            // An installer publishes current and the latest marker separately.
+            // Keep its updater alive while that publication may be in progress.
+            if !self.has_latest_selection_marker() {
+                updater.stop().await?;
+            }
+            return Ok(false);
+        }
+        let Ok(codex_bin) =
+            managed_install::resolved_managed_codex_bin(&self.managed_codex_bin).await
+        else {
+            if !self.has_latest_selection_marker() {
+                updater.stop().await?;
+            }
+            return Ok(false);
+        };
+        if !managed_install::supports_daemon_update_loop(&codex_bin).await
+            || !self.is_stable_standalone_release()?
+            || !managed_install::resolved_managed_codex_bin(&self.managed_codex_bin)
+                .await
+                .is_ok_and(|selected| selected == codex_bin)
+        {
+            if !self.has_latest_selection_marker() {
+                updater.stop().await?;
+            }
+            return Ok(false);
+        }
+        backend::pid_update_loop_backend(self.backend_paths_with_bin(settings, &codex_bin))
+            .start()
+            .await?;
+        Ok(true)
+    }
+
+    fn is_stable_standalone_release(&self) -> Result<bool> {
+        let codex_home = self
+            .settings_file
+            .parent()
+            .and_then(Path::parent)
+            .context("daemon settings path has no Codex home")?;
+        Ok(managed_install::is_stable_standalone_release(
+            codex_home,
+            &self.current_managed_codex_bin()?,
+        ))
+    }
+
+    fn current_managed_codex_bin(&self) -> Result<PathBuf> {
+        // An installer can move a legacy binary into bin/ while this updater runs.
+        let home = self
+            .settings_file
+            .parent()
+            .and_then(Path::parent)
+            .context("daemon settings path has no Codex home")?;
+        Ok(managed_install::managed_codex_bin(home))
+    }
+
+    fn has_latest_selection_marker(&self) -> bool {
+        self.settings_file
+            .parent()
+            .and_then(Path::parent)
+            .is_some_and(|home| {
+                managed_install::package_root(home)
+                    .join("auto-update-version")
+                    .is_file()
+            })
+    }
+
+    async fn is_bootstrapped(&self, settings: &DaemonSettings) -> Result<bool> {
+        if !settings.auto_update_enabled
+            || !self.is_stable_standalone_release()?
+            || !managed_install::supports_daemon_update_loop(&self.managed_codex_bin).await
+        {
+            return Ok(self.running_backend_instance(settings).await?.is_some());
+        }
+        let updater = backend::pid_update_loop_backend(self.backend_paths(settings));
+        updater.is_starting_or_running().await
+    }
+
+    fn ensure_managed_codex_bin(&self) -> Result<()> {
+        if self.managed_codex_bin.is_file() {
+            #[cfg(windows)]
+            backend::windows::ensure_detached_launch(&self.managed_codex_bin)?;
+            return Ok(());
+        }
+
+        let managed_codex_path = self.managed_codex_bin.display();
+        Err(anyhow!(
+            "daemon executable not found at {managed_codex_path}; repair the existing installation, or run `codex app-server daemon start` to install a missing daemon"
+        ))
+    }
+
+    #[cfg(any(unix, windows))]
+    async fn managed_codex_version_best_effort(&self) -> Option<String> {
+        managed_codex_version(&self.managed_codex_bin).await.ok()
+    }
+
+    #[cfg(not(any(unix, windows)))]
+    async fn managed_codex_version_best_effort(&self) -> Option<String> {
+        None
+    }
+
+    fn backend_paths(&self, settings: &DaemonSettings) -> BackendPaths {
+        self.backend_paths_with_bin(settings, &self.managed_codex_bin)
+    }
+
+    fn backend_paths_with_bin(
+        &self,
+        settings: &DaemonSettings,
+        managed_codex_bin: &Path,
+    ) -> BackendPaths {
+        BackendPaths {
+            codex_bin: managed_codex_bin.to_path_buf(),
+            pid_file: self.pid_file.clone(),
+            update_pid_file: self.update_pid_file.clone(),
+            remote_control_enabled: settings.remote_control_enabled,
+        }
+    }
+
+    fn manual_update_socket_path(&self) -> PathBuf {
+        self.update_pid_file.with_extension("sock")
+    }
+
+    async fn load_settings(&self) -> Result<DaemonSettings> {
+        DaemonSettings::load(&self.settings_file).await
+    }
+
+    async fn acquire_operation_lock(&self) -> Result<tokio::fs::File> {
+        let operation_lock = self.open_operation_lock_file().await?;
+        let deadline = tokio::time::Instant::now() + OPERATION_LOCK_TIMEOUT;
+        while !try_lock_file(&operation_lock)? {
+            if tokio::time::Instant::now() >= deadline {
+                return Err(anyhow!(
+                    "timed out waiting for daemon operation lock {}",
+                    self.operation_lock_file.display()
+                ));
+            }
+            sleep(START_POLL_INTERVAL).await;
+        }
+        Ok(operation_lock)
+    }
+
+    async fn open_operation_lock_file(&self) -> Result<tokio::fs::File> {
+        if let Some(parent) = self.operation_lock_file.parent() {
+            #[cfg(unix)]
+            if let Some(home) = parent.parent() {
+                tokio::fs::create_dir_all(home).await?;
+            }
+            codex_uds::prepare_private_socket_directory(parent)
+                .await
+                .with_context(|| {
+                    format!(
+                        "failed to create daemon state directory {}",
+                        parent.display()
+                    )
+                })?;
+        }
+        tokio::fs::OpenOptions::new()
+            .create(true)
+            .truncate(false)
+            .write(true)
+            .open(&self.operation_lock_file)
+            .await
+            .with_context(|| {
+                format!(
+                    "failed to open daemon operation lock {}",
+                    self.operation_lock_file.display()
+                )
+            })
+    }
+
+    async fn output(
+        &self,
+        status: LifecycleStatus,
+        backend: Option<BackendKind>,
+        pid: Option<u32>,
+        app_server_version: Option<String>,
+    ) -> LifecycleOutput {
+        let managed_codex_version = self.managed_codex_version_best_effort().await;
+        LifecycleOutput {
+            status,
+            backend,
+            pid,
+            managed_codex_path: self.managed_codex_bin.clone(),
+            managed_codex_version,
+            socket_path: self.socket_path.clone(),
+            cli_version: Some(env!("CARGO_PKG_VERSION").to_string()),
+            app_server_version,
+        }
+    }
+
+    fn remote_control_output(
+        &self,
+        status: RemoteControlStatus,
+        backend: Option<BackendKind>,
+        remote_control_enabled: bool,
+        app_server_version: Option<String>,
+    ) -> RemoteControlOutput {
+        RemoteControlOutput {
+            status,
+            backend,
+            remote_control_enabled,
+            socket_path: self.socket_path.clone(),
+            cli_version: env!("CARGO_PKG_VERSION").to_string(),
+            app_server_version,
+        }
+    }
+}
+
+fn remote_control_status(mode: RemoteControlMode) -> RemoteControlStatus {
+    match mode {
+        RemoteControlMode::Enabled => RemoteControlStatus::Enabled,
+        RemoteControlMode::Disabled => RemoteControlStatus::Disabled,
+    }
+}
+
+fn already_remote_control_status(mode: RemoteControlMode) -> RemoteControlStatus {
+    match mode {
+        RemoteControlMode::Enabled => RemoteControlStatus::AlreadyEnabled,
+        RemoteControlMode::Disabled => RemoteControlStatus::AlreadyDisabled,
+    }
+}
+
+#[cfg(any(unix, windows))]
+fn restart_decision(
+    mode: RestartMode,
+    info: Option<&client::ProbeInfo>,
+    managed_version: Option<&str>,
+) -> RestartDecision {
+    match (mode, info, managed_version) {
+        (RestartMode::IfBinaryOrVersionChanged, _, _) => {
+            unreachable!("binary comparison is resolved before restart decision")
+        }
+        (RestartMode::IfVersionChanged, None, _) => RestartDecision::NotReady,
+        (RestartMode::IfVersionChanged, Some(info), Some(managed_version))
+            if info.app_server_version == managed_version =>
+        {
+            RestartDecision::AlreadyCurrent
+        }
+        _ => RestartDecision::Restart,
+    }
+}
+
+#[cfg(unix)]
+fn try_lock_file(file: &tokio::fs::File) -> Result<bool> {
+    use std::os::fd::AsRawFd;
+
+    let result = unsafe { libc::flock(file.as_raw_fd(), libc::LOCK_EX | libc::LOCK_NB) };
+    if result == 0 {
+        return Ok(true);
+    }
+
+    let err = std::io::Error::last_os_error();
+    if err.raw_os_error() == Some(libc::EWOULDBLOCK) {
+        return Ok(false);
+    }
+    Err(err).context("failed to lock daemon operation")
+}
+
+#[cfg(not(any(unix, windows)))]
+fn try_lock_file(_file: &tokio::fs::File) -> Result<bool> {
+    Ok(true)
+}
+
+#[cfg(all(test, any(unix, windows)))]
+mod tests {
+    use pretty_assertions::assert_eq;
+    use tempfile::TempDir;
+
+    use super::BackendKind;
+    use super::BootstrapOutput;
+    use super::BootstrapStatus;
+    use super::Daemon;
+    use super::LifecycleOutput;
+    use super::LifecycleStatus;
+    use super::RemoteControlStartOutput;
+    use super::RemoteControlStatus;
+    use super::RestartDecision;
+    use super::RestartMode;
+    use super::restart_decision;
+    use crate::client::ProbeInfo;
+    #[cfg(unix)]
+    use crate::settings::DaemonSettings;
+
+    #[test]
+    fn remote_control_status_uses_camel_case_json() {
+        assert_eq!(
+            serde_json::to_string(&RemoteControlStatus::AlreadyEnabled).expect("serialize"),
+            "\"alreadyEnabled\""
+        );
+    }
+
+    #[test]
+    fn restart_decision_preserves_forced_refreshes() {
+        let current_info = ProbeInfo {
+            app_server_version: "0.1.0".to_string(),
+        };
+
+        assert_eq!(
+            [
+                restart_decision(
+                    RestartMode::IfVersionChanged,
+                    Some(&current_info),
+                    Some("0.1.0"),
+                ),
+                restart_decision(
+                    RestartMode::IfVersionChanged,
+                    /*info*/ None,
+                    /*managed_version*/ None,
+                ),
+                restart_decision(RestartMode::Always, Some(&current_info), Some("0.1.0")),
+                restart_decision(
+                    RestartMode::Always,
+                    /*info*/ None,
+                    /*managed_version*/ None,
+                ),
+            ],
+            [
+                RestartDecision::AlreadyCurrent,
+                RestartDecision::NotReady,
+                RestartDecision::Restart,
+                RestartDecision::Restart,
+            ]
+        );
+    }
+
+    #[test]
+    fn remote_control_start_output_serializes_inner_output_without_tag() {
+        let lifecycle_output = LifecycleOutput {
+            status: LifecycleStatus::AlreadyRunning,
+            backend: Some(BackendKind::Pid),
+            pid: None,
+            managed_codex_path: "codex".into(),
+            managed_codex_version: Some("1.2.3".to_string()),
+            socket_path: "codex.sock".into(),
+            cli_version: Some("1.2.3".to_string()),
+            app_server_version: Some("1.2.4".to_string()),
+        };
+        let output = RemoteControlStartOutput::Start(lifecycle_output.clone());
+
+        assert_eq!(
+            serde_json::to_value(&lifecycle_output).expect("serialize"),
+            serde_json::json!({
+                "status": "alreadyRunning",
+                "backend": "pid",
+                "managedCodexPath": "codex",
+                "managedCodexVersion": "1.2.3",
+                "socketPath": "codex.sock",
+                "cliVersion": "1.2.3",
+                "appServerVersion": "1.2.4",
+            })
+        );
+        assert_eq!(
+            serde_json::to_value(output).expect("serialize"),
+            serde_json::to_value(lifecycle_output).expect("serialize")
+        );
+
+        let bootstrap_output = BootstrapOutput {
+            status: BootstrapStatus::Bootstrapped,
+            backend: BackendKind::Pid,
+            auto_update_enabled: true,
+            remote_control_enabled: true,
+            managed_codex_path: "codex".into(),
+            managed_codex_version: Some("1.2.3".to_string()),
+            socket_path: "codex.sock".into(),
+            cli_version: "1.2.3".to_string(),
+            app_server_version: "1.2.4".to_string(),
+        };
+        let output = RemoteControlStartOutput::Bootstrap(bootstrap_output.clone());
+
+        assert_eq!(
+            serde_json::to_value(&bootstrap_output).expect("serialize"),
+            serde_json::json!({
+                "status": "bootstrapped",
+                "backend": "pid",
+                "autoUpdateEnabled": true,
+                "remoteControlEnabled": true,
+                "managedCodexPath": "codex",
+                "managedCodexVersion": "1.2.3",
+                "socketPath": "codex.sock",
+                "cliVersion": "1.2.3",
+                "appServerVersion": "1.2.4",
+            })
+        );
+        assert_eq!(
+            serde_json::to_value(output).expect("serialize"),
+            serde_json::to_value(bootstrap_output).expect("serialize")
+        );
+    }
+
+    #[tokio::test]
+    async fn waiting_lifecycle_command_uses_migrated_installation() {
+        let home = TempDir::new().expect("home");
+        let state = home.path().join("app-server-daemon");
+        let legacy = home.path().join("packages/standalone/current");
+        std::fs::create_dir_all(&legacy).expect("legacy selection");
+        let daemon = Daemon {
+            socket_path: home.path().join("server.sock"),
+            pid_file: state.join(super::LEGACY_PID_FILE_NAME),
+            update_pid_file: state.join(super::LEGACY_UPDATE_PID_FILE_NAME),
+            operation_lock_file: state.join("daemon.lock"),
+            settings_file: state.join("settings.json"),
+            managed_codex_bin: super::managed_codex_bin(home.path()),
+        };
+        let lock = daemon.acquire_operation_lock().await.expect("lock");
+        let stop = daemon.run(super::LifecycleCommand::Stop);
+        tokio::pin!(stop);
+        assert!(
+            tokio::time::timeout(std::time::Duration::from_millis(20), &mut stop)
+                .await
+                .is_err()
+        );
+        std::fs::create_dir_all(home.path().join("packages/app-server-daemon/current"))
+            .expect("migrate selection");
+        drop(lock);
+        let output = stop.await.expect("stop");
+        assert_eq!(
+            (output.status, output.managed_codex_path),
+            (
+                LifecycleStatus::NotRunning,
+                super::managed_codex_bin(home.path())
+            )
+        );
+    }
+
+    #[tokio::test]
+    async fn stop_creates_missing_home_parent() {
+        let temp = TempDir::new().expect("temp dir");
+        let state = temp.path().join("missing-home").join("daemon-state");
+        let daemon = Daemon {
+            socket_path: state.join("server.sock"),
+            pid_file: state.join("server.pid"),
+            update_pid_file: state.join("updater.pid"),
+            operation_lock_file: state.join("daemon.lock"),
+            settings_file: state.join("settings.json"),
+            managed_codex_bin: state.join("missing-codex"),
+        };
+        assert_eq!(
+            daemon
+                .run(super::LifecycleCommand::Stop)
+                .await
+                .expect("stop on fresh home")
+                .status,
+            LifecycleStatus::NotRunning,
+        );
+    }
+
+    #[tokio::test]
+    async fn stop_and_fresh_start_discard_pending_thread_restore() {
+        let home = TempDir::new().expect("home");
+        let state = home.path().join("app-server-daemon");
+        codex_uds::prepare_private_socket_directory(&state)
+            .await
+            .expect("private state directory");
+        let daemon = Daemon {
+            socket_path: home.path().join("server.sock"),
+            pid_file: state.join("server.pid"),
+            update_pid_file: state.join("updater.pid"),
+            operation_lock_file: state.join("daemon.lock"),
+            settings_file: state.join("settings.json"),
+            managed_codex_bin: home.path().join("codex"),
+        };
+        codex_app_server_transport::daemon_recovery::write_candidates(
+            &daemon.recovery_file().expect("recovery path"),
+            &["thread".to_string()].into_iter().collect(),
+        )
+        .expect("saved threads");
+        assert_eq!(
+            daemon
+                .run(super::LifecycleCommand::Stop)
+                .await
+                .expect("stop")
+                .status,
+            LifecycleStatus::NotRunning
+        );
+        assert!(!daemon.recovery_file().expect("recovery path").exists());
+        // Simulate an older stop client leaving a snapshot behind.
+        std::fs::write(
+            daemon.recovery_file().expect("recovery path"),
+            r#"["thread"]"#,
+        )
+        .expect("legacy saved threads");
+        daemon
+            .run(super::LifecycleCommand::Start)
+            .await
+            .expect_err("missing backend binary");
+        assert!(!daemon.recovery_file().expect("recovery path").exists());
+    }
+
+    #[cfg(unix)]
+    #[tokio::test]
+    async fn managed_local_backend_counts_as_bootstrapped_without_updater() {
+        use std::os::unix::fs::PermissionsExt;
+
+        let home = TempDir::new().expect("home");
+        let standalone = home.path().join("packages/standalone");
+        let local_bin = standalone.join("local-main/bin/codex");
+        tokio::fs::create_dir_all(local_bin.parent().expect("bin parent"))
+            .await
+            .expect("local bin directory");
+        tokio::fs::write(&local_bin, b"#!/bin/sh\nexec sleep 30\n")
+            .await
+            .expect("local bin");
+        std::fs::set_permissions(&local_bin, std::fs::Permissions::from_mode(0o755))
+            .expect("executable local bin");
+        std::os::unix::fs::symlink("local-main", standalone.join("current"))
+            .expect("current local build");
+        let state = home.path().join("app-server-daemon");
+        let daemon = Daemon {
+            socket_path: home
+                .path()
+                .join("app-server-control/app-server-control.sock"),
+            pid_file: state.join("app-server.pid"),
+            update_pid_file: state.join("app-server-updater.pid"),
+            operation_lock_file: state.join("daemon.lock"),
+            settings_file: state.join("settings.json"),
+            managed_codex_bin: standalone.join("current/bin/codex"),
+        };
+        let settings = DaemonSettings::default();
+        assert!(
+            !daemon
+                .is_bootstrapped(&settings)
+                .await
+                .expect("not running")
+        );
+        let backend = crate::backend::pid_backend(daemon.backend_paths(&settings));
+        backend.start().await.expect("start local backend");
+        let bootstrapped = daemon.is_bootstrapped(&settings).await;
+        backend.stop().await.expect("stop local backend");
+        assert!(bootstrapped.expect("managed local backend"));
+    }
+
+    #[tokio::test]
+    async fn not_ready_context_reports_daemon_app_server_before_stderr() {
+        let temp_dir = TempDir::new().expect("temp dir");
+        let daemon = Daemon {
+            socket_path: temp_dir.path().join("app-server-control.sock"),
+            pid_file: temp_dir.path().join("app-server.pid"),
+            update_pid_file: temp_dir.path().join("app-server-updater.pid"),
+            operation_lock_file: temp_dir.path().join("daemon.lock"),
+            settings_file: temp_dir.path().join("settings.json"),
+            managed_codex_bin: temp_dir.path().join("missing-codex"),
+        };
+        let stderr_log = daemon.pid_file.with_extension("stderr.log");
+        tokio::fs::write(&stderr_log, "unexpected argument")
+            .await
+            .expect("write stderr log");
+
+        assert_eq!(
+            daemon.app_server_not_ready_context().await,
+            format!(
+                "app server did not become ready on {}\n\n\
+                 Daemon used app-server:\n  path: {}\n  version: unknown\n\n\
+                 Managed app-server stderr ({}):\n  unexpected argument",
+                daemon.socket_path.display(),
+                daemon.managed_codex_bin.display(),
+                stderr_log.display()
+            )
+        );
+    }
+}

codex-rs/app-server-daemon/src/managed_install.rs

@@ -0,0 +1,221 @@
+//! Resolves both package and legacy standalone layouts and compares installed executables.
+
+use std::path::Path;
+use std::path::PathBuf;
+use std::process::Stdio;
+use std::time::Duration;
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::anyhow;
+use serde::Deserialize;
+use serde::Serialize;
+use tokio::fs;
+use tokio::process::Command;
+use tokio::time::timeout;
+
+/// New daemons own their packages, regardless of how the calling CLI was installed.
+/// Preserve legacy launch state, including logs left after a daemon is stopped;
+/// settings, installer selections, and lock files alone do not prove a prior launch.
+pub(crate) fn package_root(codex_home: &Path) -> PathBuf {
+    let dedicated = codex_home.join("packages/app-server-daemon");
+    if !matches!(dedicated.join("current").symlink_metadata(),
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound)
+    {
+        return dedicated;
+    }
+    let state = codex_home.join("app-server-daemon");
+    for (package, artifacts) in [
+        (
+            "app-server-daemon",
+            [
+                crate::DAEMON_PID_FILE_NAME,
+                "daemon.stderr.log",
+                crate::DAEMON_UPDATE_PID_FILE_NAME,
+                "daemon-updater.stderr.log",
+            ],
+        ),
+        (
+            "standalone",
+            [
+                crate::LEGACY_PID_FILE_NAME,
+                "app-server.stderr.log",
+                crate::LEGACY_UPDATE_PID_FILE_NAME,
+                "app-server-updater.stderr.log",
+            ],
+        ),
+    ] {
+        if artifacts.iter().any(|name| {
+            !matches!(state.join(name).symlink_metadata(),
+                Err(error) if error.kind() == std::io::ErrorKind::NotFound)
+        }) {
+            return codex_home.join("packages").join(package);
+        }
+    }
+    dedicated
+}
+
+/// Resolve both packaged and legacy binaries without requiring a valid install.
+pub(crate) fn managed_codex_bin(codex_home: &Path) -> PathBuf {
+    let root = package_root(codex_home);
+    let current = root.join("current");
+    let packaged = current.join("bin").join(managed_codex_file_name());
+    let legacy = current.join(managed_codex_file_name());
+    if packaged.is_file()
+        || !legacy.is_file() && (cfg!(windows) || root.ends_with("app-server-daemon"))
+    {
+        packaged
+    } else {
+        legacy
+    }
+}
+
+/// Only latest-channel stable releases may run the public latest-version updater.
+pub(crate) fn is_stable_standalone_release(codex_home: &Path, codex_bin: &Path) -> bool {
+    let standalone = package_root(codex_home);
+    let Ok(releases) = std::fs::canonicalize(standalone.join("releases")) else {
+        return false;
+    };
+    let Ok(release) = std::fs::canonicalize(standalone.join("current")) else {
+        return false;
+    };
+    if release.parent() != Some(releases.as_path()) {
+        return false;
+    }
+    let Some(release_name) = release.file_name().and_then(|name| name.to_str()) else {
+        return false;
+    };
+    // GNU packages can seed the new directory; retain legacy updater eligibility.
+    if standalone.ends_with("standalone") && release_name.ends_with("-gnu") {
+        return false;
+    }
+    let targets = [
+        "aarch64-apple-darwin",
+        "x86_64-apple-darwin",
+        "aarch64-unknown-linux-gnu",
+        "x86_64-unknown-linux-gnu",
+        "aarch64-unknown-linux-musl",
+        "x86_64-unknown-linux-musl",
+        "aarch64-pc-windows-msvc",
+        "x86_64-pc-windows-msvc",
+    ];
+    let Some(version) = targets
+        .iter()
+        .find_map(|target| release_name.strip_suffix(&format!("-{target}")))
+    else {
+        return false;
+    };
+    let components: Vec<_> = version.split('.').collect();
+    components.len() == 3
+        && components.iter().all(|component| {
+            !component.is_empty() && component.bytes().all(|byte| byte.is_ascii_digit())
+        })
+        && std::fs::read_to_string(standalone.join("auto-update-version"))
+            .is_ok_and(|selected| selected == release_name)
+        && std::fs::canonicalize(codex_bin).is_ok_and(|bin| bin.starts_with(&release))
+}
+
+/// Older managed binaries can serve app-server requests without owning an updater.
+pub(crate) async fn supports_daemon_update_loop(codex_bin: &Path) -> bool {
+    supports_daemon_command(codex_bin, &["pid-update-loop", "--help"]).await
+}
+
+/// Probe an internal daemon command without running a long-lived process.
+pub(crate) async fn supports_daemon_command(codex_bin: &Path, args: &[&str]) -> bool {
+    let mut command = Command::new(codex_bin);
+    #[cfg(windows)]
+    command.creation_flags(windows_sys::Win32::System::Threading::CREATE_NO_WINDOW);
+    timeout(
+        Duration::from_secs(5),
+        command
+            .args(["app-server", "daemon"])
+            .args(args)
+            .stdin(Stdio::null())
+            .stdout(Stdio::null())
+            .stderr(Stdio::null())
+            .kill_on_drop(true)
+            .status(),
+    )
+    .await
+    .is_ok_and(|result| result.is_ok_and(|status| status.success()))
+}
+
+pub(crate) async fn resolved_managed_codex_bin(codex_bin: &Path) -> Result<PathBuf> {
+    fs::canonicalize(codex_bin).await.with_context(|| {
+        format!(
+            "failed to resolve managed Codex binary {}",
+            codex_bin.display()
+        )
+    })
+}
+
+pub(crate) async fn managed_codex_version(codex_bin: &Path) -> Result<String> {
+    let mut command = Command::new(codex_bin);
+    #[cfg(windows)]
+    command.creation_flags(windows_sys::Win32::System::Threading::CREATE_NO_WINDOW);
+    let output = command
+        .arg("--version")
+        .kill_on_drop(true)
+        .output()
+        .await
+        .with_context(|| {
+            format!(
+                "failed to invoke managed Codex binary {}",
+                codex_bin.display()
+            )
+        })?;
+    if !output.status.success() {
+        return Err(anyhow!(
+            "managed Codex binary {} exited with status {}",
+            codex_bin.display(),
+            output.status
+        ));
+    }
+
+    let stdout = String::from_utf8(output.stdout).with_context(|| {
+        format!(
+            "managed Codex version was not utf-8: {}",
+            codex_bin.display()
+        )
+    })?;
+    parse_codex_version(&stdout)
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub(crate) struct ExecutableIdentity {
+    digest: [u8; 32],
+}
+
+pub(crate) async fn executable_identity(executable: &Path) -> Result<ExecutableIdentity> {
+    let bytes = fs::read(executable)
+        .await
+        .with_context(|| format!("failed to read executable {}", executable.display()))?;
+    Ok(executable_identity_from_bytes(&bytes))
+}
+
+pub(crate) fn executable_identity_from_bytes(bytes: &[u8]) -> ExecutableIdentity {
+    ExecutableIdentity {
+        digest: *blake3::hash(bytes).as_bytes(),
+    }
+}
+
+fn managed_codex_file_name() -> &'static str {
+    if cfg!(windows) { "codex.exe" } else { "codex" }
+}
+
+fn parse_codex_version(output: &str) -> Result<String> {
+    let version = output
+        .split_whitespace()
+        .nth(1)
+        .filter(|version| !version.is_empty())
+        .ok_or_else(|| anyhow!("managed Codex version output was malformed"))?;
+    Ok(version.to_string())
+}
+
+#[cfg(test)]
+#[path = "managed_install_tests.rs"]
+mod tests;
+
+#[cfg(test)]
+#[path = "managed_install_path_tests.rs"]
+mod path_tests;

codex-rs/app-server-daemon/src/managed_install_path_tests.rs

@@ -0,0 +1,127 @@
+use pretty_assertions::assert_eq;
+
+#[test]
+fn discovers_package_and_legacy_installs() {
+    let home = tempfile::TempDir::new().expect("home");
+    let current = home.path().join("packages/standalone/current");
+    let legacy = current.join(super::managed_codex_file_name());
+    assert_eq!(
+        super::managed_codex_bin(home.path()),
+        home.path()
+            .join("packages/app-server-daemon/current/bin")
+            .join(super::managed_codex_file_name())
+    );
+    std::fs::create_dir_all(&current).expect("current directory");
+    std::fs::write(&legacy, b"legacy").expect("legacy executable");
+    let state = home.path().join("app-server-daemon");
+    std::fs::create_dir(&state).unwrap();
+    for name in ["settings.json", "daemon.lock", "app-server.pid.lock"] {
+        std::fs::write(state.join(name), b"").unwrap();
+    }
+    // A CLI install and a previous stop/status operation do not establish ownership.
+    assert_eq!(
+        super::package_root(home.path()),
+        home.path().join("packages/app-server-daemon")
+    );
+    std::fs::write(state.join("app-server.stderr.log"), b"").unwrap();
+    assert_eq!(super::managed_codex_bin(home.path()), legacy);
+    let packaged = current.join("bin").join(super::managed_codex_file_name());
+    std::fs::create_dir(current.join("bin")).expect("bin directory");
+    std::fs::write(&packaged, b"packaged").expect("packaged executable");
+    assert_eq!(super::managed_codex_bin(home.path()), packaged);
+
+    std::fs::remove_dir_all(home.path().join("packages/standalone")).unwrap();
+    assert_eq!(
+        super::package_root(home.path()),
+        home.path().join("packages/standalone")
+    );
+    std::fs::remove_file(state.join("app-server.stderr.log")).unwrap();
+    std::fs::write(state.join("app-server.pid"), b"running daemon").unwrap();
+    assert_eq!(
+        super::package_root(home.path()),
+        home.path().join("packages/standalone")
+    );
+
+    std::fs::write(state.join("daemon.pid"), b"running dedicated daemon").unwrap();
+    assert_eq!(
+        super::package_root(home.path()),
+        home.path().join("packages/app-server-daemon")
+    );
+    std::fs::remove_file(state.join("daemon.pid")).unwrap();
+    std::fs::write(state.join("daemon.stderr.log"), b"").unwrap();
+    assert_eq!(
+        super::package_root(home.path()),
+        home.path().join("packages/app-server-daemon")
+    );
+
+    #[cfg(unix)]
+    {
+        let dedicated = home.path().join("packages/app-server-daemon");
+        std::fs::write(&dedicated, b"not a directory").expect("unreadable selection");
+        assert_eq!(super::package_root(home.path()), dedicated);
+    }
+}
+
+#[cfg(unix)]
+#[test]
+fn updater_only_runs_for_stable_installer_owned_releases() {
+    let home = tempfile::TempDir::new().expect("home");
+    let state = home.path().join("app-server-daemon");
+    std::fs::create_dir(&state).unwrap();
+    std::fs::write(state.join("app-server.stderr.log"), b"").unwrap();
+    let standalone = home.path().join("packages/standalone");
+    let current = standalone.join("current");
+    let release = standalone.join("releases/0.150.0-aarch64-apple-darwin");
+    let managed = release.join("bin/codex");
+    std::fs::create_dir_all(managed.parent().expect("bin parent")).expect("release");
+    std::fs::write(&managed, b"stable").expect("managed bin");
+    std::os::unix::fs::symlink(&release, &current).expect("current release");
+    assert!(!super::is_stable_standalone_release(home.path(), &managed));
+    let marker = standalone.join("auto-update-version");
+    let release_name = release.file_name().expect("release name");
+    std::fs::write(&marker, release_name.as_encoded_bytes()).expect("latest selection");
+    assert!(super::is_stable_standalone_release(home.path(), &managed));
+    std::fs::write(&marker, b"0.149.0-aarch64-apple-darwin").expect("stale selection");
+    assert!(!super::is_stable_standalone_release(home.path(), &managed));
+    std::fs::remove_file(&marker).expect("pinned selection");
+    assert!(!super::is_stable_standalone_release(home.path(), &managed));
+
+    let alpha = standalone.join("releases/0.151.0-alpha.1-aarch64-apple-darwin");
+    let alpha_managed = alpha.join("bin/codex");
+    std::fs::create_dir_all(alpha_managed.parent().expect("alpha bin parent"))
+        .expect("alpha release");
+    std::fs::write(&alpha_managed, b"alpha").expect("alpha bin");
+    std::fs::remove_file(&current).expect("remove current");
+    std::os::unix::fs::symlink(alpha, &current).expect("current alpha");
+    assert!(!super::is_stable_standalone_release(
+        home.path(),
+        &alpha_managed
+    ));
+
+    let local = standalone.join("local-main");
+    let local_managed = local.join("bin/codex");
+    std::fs::create_dir_all(local_managed.parent().expect("local bin parent"))
+        .expect("local build");
+    std::fs::write(&local_managed, b"local").expect("local bin");
+    std::fs::remove_file(&current).expect("remove current");
+    std::os::unix::fs::symlink(local, &current).expect("current local build");
+    assert!(!super::is_stable_standalone_release(
+        home.path(),
+        &local_managed
+    ));
+}
+
+#[cfg(unix)]
+#[tokio::test]
+async fn older_managed_binary_does_not_claim_updater_support() {
+    use std::os::unix::fs::PermissionsExt;
+
+    let temp = tempfile::TempDir::new().expect("home");
+    let binary = temp.path().join("codex");
+    std::fs::write(&binary, b"#!/bin/sh\nexit 2\n").expect("older binary");
+    std::fs::set_permissions(&binary, std::fs::Permissions::from_mode(0o755))
+        .expect("executable binary");
+    assert!(!super::supports_daemon_update_loop(&binary).await);
+    std::fs::write(&binary, b"#!/bin/sh\nexit 0\n").expect("newer binary");
+    assert!(super::supports_daemon_update_loop(&binary).await);
+}

codex-rs/app-server-daemon/src/managed_install_tests.rs

@@ -0,0 +1,27 @@
+use pretty_assertions::assert_eq;
+
+use super::executable_identity_from_bytes;
+use super::parse_codex_version;
+
+#[test]
+fn parses_codex_cli_version_output() {
+    assert_eq!(
+        parse_codex_version("codex 1.2.3\n").expect("version"),
+        "1.2.3"
+    );
+}
+
+#[test]
+fn rejects_malformed_codex_cli_version_output() {
+    assert!(parse_codex_version("codex\n").is_err());
+}
+
+#[test]
+fn executable_identity_uses_binary_contents() {
+    let old = executable_identity_from_bytes(b"old");
+    let same = executable_identity_from_bytes(b"old");
+    let new = executable_identity_from_bytes(b"new");
+
+    assert_eq!(old, same);
+    assert_ne!(old, new);
+}

codex-rs/app-server-daemon/src/manual_update.rs

@@ -0,0 +1,281 @@
+//! Forwards manual requests to the updater and reports its install and restart result.
+
+use anyhow::Context;
+use anyhow::Result;
+use codex_uds::UnixStream;
+use tokio::io::AsyncReadExt;
+use tokio::io::AsyncWriteExt;
+use tokio::time::Duration;
+use tokio::time::sleep;
+use tokio::time::timeout;
+
+use super::InstallerHttp;
+use super::Signal;
+use super::UpdateLoopControl;
+use super::UpdateTrigger;
+use super::selected_release;
+use super::update_once;
+use crate::Daemon;
+use crate::RestartIfRunningOutcome;
+use crate::UpdateOutput;
+use crate::UpdateStatus;
+use crate::client;
+use crate::managed_install::executable_identity;
+use crate::managed_install::managed_codex_version;
+
+pub(crate) async fn request(daemon: &Daemon) -> Result<UpdateOutput> {
+    let socket_path = daemon.manual_update_socket_path();
+    let mut replacement_deadline = None;
+    'request: loop {
+        let mut connection = if let Some(deadline) = replacement_deadline {
+            loop {
+                if let Ok(connection) = UnixStream::connect(&socket_path).await {
+                    break connection;
+                }
+                // A one-shot updater may exit after accepting the connection but
+                // before reading our request. Give a successor time to appear,
+                // then return to the normal startup path if none owns the PID.
+                if tokio::time::Instant::now() + Duration::from_secs(29) >= deadline {
+                    let settings = daemon.load_settings().await?;
+                    if !crate::backend::pid_update_loop_backend(daemon.backend_paths(&settings))
+                        .is_starting_or_running()
+                        .await?
+                    {
+                        replacement_deadline = None;
+                        continue 'request;
+                    }
+                }
+                anyhow::ensure!(
+                    tokio::time::Instant::now() < deadline,
+                    "timed out waiting for the replacement daemon updater"
+                );
+                sleep(Duration::from_millis(50)).await;
+            }
+        } else {
+            match UnixStream::connect(&socket_path).await {
+                Ok(connection) => connection,
+                Err(_) => {
+                    let _operation_lock = daemon.acquire_operation_lock().await?;
+                    if let Ok(connection) = UnixStream::connect(&socket_path).await {
+                        connection
+                    } else {
+                        let settings = daemon.load_settings().await?;
+                        if !supported(daemon)?
+                            || (daemon.running_backend_instance(&settings).await?.is_none()
+                                && client::probe(&daemon.socket_path).await.is_ok())
+                        {
+                            return unsupported(daemon).await;
+                        }
+                        crate::backend::pid_update_loop_backend(daemon.backend_paths(&settings))
+                            .stop()
+                            .await?;
+                        let current_exe = std::env::current_exe()?;
+                        let paths = daemon.backend_paths_with_bin(&settings, &current_exe);
+                        let restore_release = if daemon.is_stable_standalone_release()? {
+                            None
+                        } else {
+                            Some(selected_release(daemon)?.2)
+                        };
+                        let worker = crate::backend::PidBackend::new_update_loop(
+                            paths.codex_bin,
+                            paths.update_pid_file,
+                            restore_release,
+                        );
+                        worker.start().await?;
+                        let deadline = tokio::time::Instant::now() + Duration::from_secs(30);
+                        loop {
+                            if let Ok(connection) = UnixStream::connect(&socket_path).await {
+                                break connection;
+                            }
+                            anyhow::ensure!(
+                                tokio::time::Instant::now() < deadline,
+                                "timed out waiting for the daemon updater to accept a manual request"
+                            );
+                            sleep(Duration::from_millis(50)).await;
+                        }
+                    }
+                }
+            }
+        };
+        let mut response = Vec::new();
+        let transport = async {
+            #[cfg(windows)]
+            connection.ensure_non_elevated_peer()?;
+            connection.write_all(b"update\n").await?;
+            connection
+                .take(16 * 1024)
+                .read_to_end(&mut response)
+                .await?;
+            Ok::<_, std::io::Error>(())
+        }
+        .await;
+        if response.is_empty() {
+            if transport
+                .as_ref()
+                .is_err_and(|err| err.kind() == std::io::ErrorKind::PermissionDenied)
+            {
+                transport?;
+            }
+            let deadline = replacement_deadline
+                .get_or_insert_with(|| tokio::time::Instant::now() + Duration::from_secs(30));
+            anyhow::ensure!(
+                tokio::time::Instant::now() < *deadline,
+                "daemon updater disconnected before responding"
+            );
+            sleep(Duration::from_millis(50)).await;
+            continue;
+        }
+        transport?;
+        let outcome: std::result::Result<UpdateOutput, String> =
+            serde_json::from_slice(&response).context("invalid response from daemon updater")?;
+        let outcome = outcome.map_err(anyhow::Error::msg)?;
+        if outcome.status == UpdateStatus::Unsupported && supported(daemon)? {
+            // A scheduled or older updater cannot authorize restoring a pin.
+            // Replace it under the writable operation lock, even with identical bytes.
+            let _operation_lock = daemon.acquire_operation_lock().await?;
+            let settings = daemon.load_settings().await?;
+            let worker = crate::backend::pid_update_loop_backend(daemon.backend_paths(&settings));
+            if !daemon.is_stable_standalone_release()? {
+                worker.stop().await?;
+                continue 'request;
+            }
+        }
+        return Ok(outcome);
+    }
+}
+
+pub(super) fn supported(daemon: &Daemon) -> Result<bool> {
+    if daemon.is_stable_standalone_release()? {
+        return Ok(true);
+    }
+    let Ok((root, release, _)) = selected_release(daemon) else {
+        return Ok(false);
+    };
+    let bin = daemon.current_managed_codex_bin()?;
+    Ok(std::fs::canonicalize(root.join("releases"))
+        .is_ok_and(|releases| release.parent() == Some(releases.as_path()))
+        && bin.is_file()
+        && std::fs::canonicalize(bin).is_ok_and(|bin| bin.starts_with(&release)))
+}
+
+const UNSUPPORTED_MESSAGE: &str =
+    "This command requires a daemon package selected from its managed releases directory.";
+
+pub(super) async fn unsupported(daemon: &Daemon) -> Result<UpdateOutput> {
+    let managed_codex_path = daemon.current_managed_codex_bin()?;
+    Ok(UpdateOutput {
+        status: UpdateStatus::Unsupported,
+        installed_version: managed_codex_version(&managed_codex_path).await.ok(),
+        running_version: client::probe(&daemon.socket_path)
+            .await
+            .ok()
+            .map(|info| info.app_server_version),
+        managed_codex_path,
+        message: UNSUPPORTED_MESSAGE.to_string(),
+    })
+}
+
+pub(super) async fn handle_request(
+    mut connection: UnixStream,
+    http: &impl InstallerHttp,
+    daemon: &Daemon,
+    running_updater_identity: &crate::managed_install::ExecutableIdentity,
+    terminate: &mut Signal,
+    trigger: UpdateTrigger<'_>,
+) -> Result<RequestDisposition> {
+    #[cfg(windows)]
+    if connection.ensure_non_elevated_peer().is_err() {
+        return Ok(RequestDisposition::Unchanged);
+    }
+    let mut request = [0; 7];
+    if !matches!(
+        timeout(Duration::from_secs(5), connection.read_exact(&mut request)).await,
+        Ok(Ok(_))
+    ) || &request != b"update\n"
+    {
+        return Ok(RequestDisposition::Unchanged);
+    }
+    let result = run(http, daemon, running_updater_identity, terminate, trigger).await;
+    let interrupted = result.as_ref().err().is_some_and(|err| {
+        err.downcast_ref::<std::io::Error>()
+            .is_some_and(|err| err.kind() == std::io::ErrorKind::Interrupted)
+    });
+    let unsupported = result
+        .as_ref()
+        .is_ok_and(|output| output.status == UpdateStatus::Unsupported);
+    let outcome: std::result::Result<UpdateOutput, String> =
+        result.map_err(|err| format!("{err:#}"));
+    let sent = connection.write_all(&serde_json::to_vec(&outcome)?).await;
+    if interrupted {
+        return Ok(RequestDisposition::Stop);
+    }
+    sent?;
+    Ok(if unsupported {
+        RequestDisposition::Unchanged
+    } else {
+        RequestDisposition::Continue
+    })
+}
+
+pub(super) enum RequestDisposition {
+    Continue,
+    Unchanged,
+    Stop,
+}
+
+pub(super) async fn run(
+    http: &impl InstallerHttp,
+    daemon: &Daemon,
+    running_updater_identity: &crate::managed_install::ExecutableIdentity,
+    terminate: &mut Signal,
+    trigger: UpdateTrigger<'_>,
+) -> Result<UpdateOutput> {
+    let settings = daemon.load_settings().await?;
+    let managed_running = daemon.running_backend_instance(&settings).await?.is_some();
+    if !(daemon.is_stable_standalone_release()?
+        || matches!(trigger, UpdateTrigger::RestoreProduction(_)) && supported(daemon)?)
+        || (!managed_running && client::probe(&daemon.socket_path).await.is_ok())
+    {
+        return unsupported(daemon).await;
+    }
+
+    let managed_codex_path = daemon.current_managed_codex_bin()?;
+    let (_, previous_release, _) = selected_release(daemon)?;
+    let previous_identity = executable_identity(&managed_codex_path).await?;
+    let (control, restart) =
+        update_once(http, daemon, running_updater_identity, terminate, trigger).await?;
+    if matches!(control, UpdateLoopControl::Stop) {
+        return Err(std::io::Error::from(std::io::ErrorKind::Interrupted).into());
+    }
+    let current_managed_codex_path = daemon.current_managed_codex_bin()?;
+    let installed_version = Some(managed_codex_version(&current_managed_codex_path).await?);
+    let updated = previous_release != selected_release(daemon)?.1
+        || previous_identity != executable_identity(&current_managed_codex_path).await?;
+    let running_version = client::probe(&daemon.socket_path)
+        .await
+        .ok()
+        .map(|info| info.app_server_version);
+    let message = match restart {
+        Some(RestartIfRunningOutcome::Restarted) => {
+            "The managed installation is ready and the running daemon was restarted. Active or queued work may have been interrupted."
+        }
+        Some(RestartIfRunningOutcome::AlreadyCurrent) => {
+            "The managed installation and running daemon are already current; the daemon was left running."
+        }
+        Some(RestartIfRunningOutcome::NotRunning) => {
+            "The managed installation is ready; no daemon was running when the updater checked."
+        }
+        _ => unreachable!("successful manual update has a restart outcome"),
+    };
+    Ok(UpdateOutput {
+        status: if updated {
+            UpdateStatus::Updated
+        } else {
+            UpdateStatus::NoUpdate
+        },
+        managed_codex_path: current_managed_codex_path,
+        installed_version,
+        running_version,
+        message: message.to_string(),
+    })
+}

codex-rs/app-server-daemon/src/migration.rs

@@ -0,0 +1,193 @@
+//! Moves a legacy daemon to its dedicated package only during an explicit update.
+//! Preparation leaves the legacy selection intact; publishing current is the cutover.
+
+use std::path::Path;
+
+use anyhow::Context;
+use anyhow::Result;
+use futures::FutureExt;
+
+use super::InstallerHttp;
+use super::InstallerMode;
+use super::fetch_installer_script;
+use super::run_installer_script;
+use super::selected_release;
+use crate::Daemon;
+use crate::UpdateOutput;
+use crate::UpdateStatus;
+use crate::backend;
+use crate::client;
+use crate::install_lock::acquire_install_lock;
+use crate::managed_install;
+
+pub(super) async fn run(http: &impl InstallerHttp, legacy: &Daemon) -> Result<UpdateOutput> {
+    let _operation_lock = legacy.acquire_operation_lock().await?;
+    let previous = selected_release(legacy)?;
+    anyhow::ensure!(
+        previous.0.ends_with("standalone") && super::manual_update::supported(legacy)?,
+        "daemon selection changed; retry the update"
+    );
+    let home = previous
+        .0
+        .parent()
+        .and_then(Path::parent)
+        .context("package root has no Codex home")?;
+    let root = home.join("packages/app-server-daemon");
+    let settings = legacy.load_settings().await?;
+    let running = legacy.running_backend_instance(&settings).await?;
+    if running.is_none() && client::probe(&legacy.socket_path).await.is_ok() {
+        return super::manual_update::unsupported(legacy).await;
+    }
+    #[cfg(unix)]
+    let mut terminate = tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate())?;
+    let cancellation = async {
+        #[cfg(unix)]
+        tokio::select! {
+            _ = terminate.recv() => {},
+            _ = tokio::signal::ctrl_c() => {},
+        }
+        #[cfg(windows)]
+        let _ = tokio::signal::ctrl_c().await;
+        Some(())
+    };
+    let mut cancellation = std::pin::pin!(cancellation);
+
+    let script = fetch_installer_script(http).await?;
+    anyhow::ensure!(
+        script
+            .windows(b"CODEX_INSTALL_DEFER_SELECTION".len())
+            .any(|window| window == b"CODEX_INSTALL_DEFER_SELECTION"),
+        "the published installer does not support daemon migration yet; the legacy installation was left unchanged"
+    );
+    eprintln!("Preparing the daemon update in {}...", root.display());
+    #[cfg(unix)]
+    {
+        if matches!(
+            run_installer_script(
+                &script,
+                InstallerMode::Migration,
+                &root,
+                cancellation.as_mut()
+            )
+            .await?,
+            super::UpdateLoopControl::Stop
+        ) {
+            return Err(std::io::Error::from(std::io::ErrorKind::Interrupted).into());
+        }
+    }
+    #[cfg(windows)]
+    tokio::select! {
+        result = run_installer_script(&script, InstallerMode::Migration, &root) => { result?; },
+        _ = &mut cancellation => return Err(std::io::Error::from(std::io::ErrorKind::Interrupted).into()),
+    }
+
+    let _install_lock = acquire_install_lock(&root).await?;
+    let pending = root.join(".migration-current");
+    let release = pending
+        .canonicalize()
+        .context("installer did not prepare a daemon package")?;
+    let name = release
+        .file_name()
+        .context("prepared release has no name")?;
+    anyhow::ensure!(
+        release.parent() == Some(root.join("releases").canonicalize()?.as_path())
+            && std::fs::read_to_string(root.join("auto-update-version"))? == name.to_string_lossy(),
+        "installer did not prepare a latest-channel daemon package"
+    );
+    let entrypoint = if cfg!(windows) {
+        "bin/codex.exe"
+    } else {
+        "bin/codex"
+    };
+    let binary = release.join(entrypoint);
+    let version = managed_install::managed_codex_version(&binary).await?;
+    anyhow::ensure!(
+        name.to_string_lossy().starts_with(&format!("{version}-")),
+        "prepared daemon version does not match its release"
+    );
+    // An older production updater understands only the legacy package/PID paths.
+    anyhow::ensure!(
+        managed_install::supports_daemon_command(
+            &binary,
+            &["pid-update-loop", "--check-package-ownership"]
+        )
+        .await,
+        "the latest production release does not support daemon migration yet; the legacy daemon was left running"
+    );
+    #[cfg(windows)]
+    backend::windows::ensure_detached_launch(&binary)?;
+    anyhow::ensure!(
+        selected_release(legacy)? == previous,
+        "daemon selection changed; retry the update"
+    );
+    if cancellation.as_mut().now_or_never().is_some() {
+        return Err(std::io::Error::from(std::io::ErrorKind::Interrupted).into());
+    }
+    let cutover = async {
+        backend::pid_update_loop_backend(legacy.backend_paths(&settings))
+            .stop()
+            .await?;
+        anyhow::ensure!(
+            selected_release(legacy)? == previous,
+            "daemon selection changed; retry the update"
+        );
+        if let Some(running) = &running {
+            crate::thread_recovery::discard_pending(legacy)?;
+            running
+                .stop_with_grace(settings.shutdown_grace_seconds)
+                .await?;
+        }
+        std::fs::rename(&pending, root.join("current"))
+            .context("failed to select the new daemon package; retry the update")
+    }
+    .await;
+    if let Err(error) = cutover {
+        if let Err(restore_error) = async {
+            legacy
+                .current_installation()?
+                .ensure_managed_updater(&settings)
+                .await
+        }
+        .await
+        {
+            eprintln!(
+                "warning: failed to restore the legacy updater after migration failed: {restore_error:#}"
+            );
+        }
+        return Err(error);
+    }
+    let selected = Daemon {
+        pid_file: legacy.pid_file.with_file_name(crate::DAEMON_PID_FILE_NAME),
+        update_pid_file: legacy
+            .update_pid_file
+            .with_file_name(crate::DAEMON_UPDATE_PID_FILE_NAME),
+        managed_codex_bin: root.join("current").join(entrypoint),
+        ..legacy.clone()
+    };
+    let running_version = if running.is_some() {
+        selected.start_managed_backend(&settings).await.context(
+            "daemon migrated but could not start; retry with `codex app-server daemon start`",
+        )?;
+        Some(
+            selected
+                .wait_until_ready()
+                .await
+                .context(
+                    "daemon migrated but is not ready; retry with `codex app-server daemon start`",
+                )?
+                .app_server_version,
+        )
+    } else {
+        None
+    };
+    if let Err(error) = selected.ensure_managed_updater(&settings).await {
+        eprintln!("warning: daemon migrated but its updater could not start: {error:#}");
+    }
+    Ok(UpdateOutput {
+        status: UpdateStatus::Updated,
+        installed_version: Some(version),
+        running_version,
+        managed_codex_path: selected.managed_codex_bin,
+        message: "The daemon was updated and moved to its dedicated package. The legacy CLI package was left unchanged.".to_string(),
+    })
+}

codex-rs/app-server-daemon/src/prepare_install.rs

@@ -0,0 +1,493 @@
+//! Installs complete CLI packages after confirmation. Initial starts preserve
+//! existing selections; explicit replacements migrate to dedicated packages and stay pinned.
+
+use std::path::Path;
+use std::path::PathBuf;
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::anyhow;
+use codex_install_context::CodexPackageManifest;
+use codex_install_context::InstallContext;
+
+use crate::Daemon;
+use crate::install_lock::acquire_install_lock;
+use crate::managed_install;
+use crate::settings::DaemonSettings;
+
+/// The complete CLI package offered for a daemon installation.
+pub struct InstallRequest {
+    pub source: PathBuf,
+    pub version: String,
+    pub destination: PathBuf,
+    pub installed_version: Option<String>,
+    pub restart_required: bool,
+}
+
+/// Prepare a missing package while the caller holds the daemon operation lock.
+pub(super) async fn prepare(daemon: &Daemon, settings: &DaemonSettings) -> Result<()> {
+    let source = InstallContext::current().package_layout.as_ref();
+    // Keep package replacement state out of the CLI dispatcher's async stack frame.
+    Box::pin(prepare_from_package(
+        daemon,
+        settings,
+        InstallMode::Missing,
+        source.map(|layout| layout.package_dir.as_path()),
+        &std::env::current_exe()?,
+        |_| Ok(true),
+    ))
+    .await
+    .map(|_| ())
+}
+
+/// Select this CLI's complete package and pin it, restarting only a running daemon.
+/// Returns None when the user cancels without changing the installation.
+pub async fn update_from_cli(
+    confirm: impl FnOnce(&InstallRequest) -> Result<bool>,
+) -> Result<Option<crate::UpdateOutput>> {
+    crate::ensure_supported_platform()?;
+    #[cfg(windows)]
+    crate::backend::windows::ensure_not_elevated()?;
+    let daemon = Daemon::from_environment()?;
+    let settings = daemon.load_settings().await?;
+    let source = InstallContext::current().package_layout.as_ref();
+    if !Box::pin(prepare_from_package(
+        &daemon,
+        &settings,
+        InstallMode::Replace,
+        source.map(|layout| layout.package_dir.as_path()),
+        &std::env::current_exe()?,
+        confirm,
+    ))
+    .await?
+    {
+        return Ok(None);
+    }
+    let managed_codex_path = daemon.current_managed_codex_bin()?;
+    Ok(Some(crate::UpdateOutput {
+        status: crate::UpdateStatus::Updated,
+        installed_version: Some(managed_install::managed_codex_version(&managed_codex_path).await?),
+        running_version: crate::client::probe(&daemon.socket_path)
+            .await
+            .ok()
+            .map(|info| info.app_server_version),
+        managed_codex_path,
+        message: "The CLI package is selected and pinned. Run `codex app-server daemon update` to return to production updates.".to_string(),
+    }))
+}
+
+#[derive(Clone, Copy, PartialEq, Eq)]
+enum InstallMode {
+    Missing,
+    Replace,
+}
+
+async fn prepare_from_package(
+    daemon: &Daemon,
+    settings: &DaemonSettings,
+    mode: InstallMode,
+    source: Option<&Path>,
+    running_exe: &Path,
+    confirm: impl FnOnce(&InstallRequest) -> Result<bool>,
+) -> Result<bool> {
+    let home = daemon
+        .settings_file
+        .parent()
+        .and_then(Path::parent)
+        .context("daemon settings path has no Codex home")?;
+    let previous_root = managed_install::package_root(home);
+    let root = home.join("packages/app-server-daemon");
+    anyhow::ensure!(
+        daemon.managed_codex_bin.starts_with(&previous_root),
+        "daemon package location changed; retry the command"
+    );
+    if mode == InstallMode::Missing {
+        if previous_root != root
+            || daemon.running_backend_instance(settings).await?.is_some()
+            || crate::client::probe(&daemon.socket_path).await.is_ok()
+        {
+            return Ok(true);
+        }
+        if !matches!(root.join("current").symlink_metadata(), Err(error) if error.kind() == std::io::ErrorKind::NotFound)
+            || ["daemon.pid", "daemon.stderr.log", "daemon-updater.pid", "daemon-updater.stderr.log"]
+                .iter().any(|name| !matches!(home.join("app-server-daemon").join(name).symlink_metadata(), Err(error) if error.kind() == std::io::ErrorKind::NotFound))
+        {
+            daemon.ensure_managed_codex_bin()?;
+            return Ok(true);
+        }
+    } else {
+        anyhow::ensure!(
+            previous_root.join("current").symlink_metadata().is_ok(),
+            "no daemon package is selected; run `codex app-server daemon start` first"
+        );
+    }
+    std::fs::create_dir_all(&root)?;
+    anyhow::ensure!(
+        managed_install::package_root(home) == previous_root,
+        "daemon package location changed; retry the command"
+    );
+    let backend = daemon.running_backend_instance(settings).await?;
+    anyhow::ensure!(
+        backend.is_some() || crate::client::probe(&daemon.socket_path).await.is_err(),
+        "app server is running but is not managed by codex app-server daemon"
+    );
+    let selected = managed_install::managed_codex_bin(home);
+    let previous_release = previous_root.join("current").canonicalize().ok();
+    if mode == InstallMode::Missing {
+        if selected.is_file() {
+            return Ok(true);
+        }
+        anyhow::ensure!(
+            backend.is_none()
+                && matches!(root.join("current").symlink_metadata(), Err(error) if error.kind() == std::io::ErrorKind::NotFound),
+            "the selected daemon package is incomplete; repair its installation before starting"
+        );
+    }
+    let source = source.context(
+        "this CLI has no complete local package; install a packaged Codex CLI or use the standalone installer",
+    )?;
+    anyhow::ensure!(
+        !root.canonicalize()?.starts_with(source.canonicalize()?),
+        "CODEX_HOME must be outside the source CLI package"
+    );
+    let manifest_bytes = std::fs::read(source.join("codex-package.json"))?;
+    let manifest: CodexPackageManifest = serde_json::from_slice(&manifest_bytes)?;
+    let version = manifest.version.to_string();
+    let target = platform_target()?;
+    let metadata: serde_json::Value = serde_json::from_slice(&manifest_bytes)?;
+    let entrypoint = if cfg!(windows) {
+        "bin/codex.exe"
+    } else {
+        "bin/codex"
+    };
+    anyhow::ensure!(
+        metadata["target"] == target && metadata["entrypoint"] == entrypoint,
+        "the CLI package does not match this platform or executable"
+    );
+    validate_package(source)?;
+    // A local build may replace the executable while confirmation is pending.
+    let running_identity = managed_install::executable_identity(running_exe).await?;
+    if mode == InstallMode::Replace {
+        if !confirm(&InstallRequest {
+            source: source.to_path_buf(),
+            version: version.clone(),
+            destination: root.clone(),
+            installed_version: tokio::time::timeout(
+                std::time::Duration::from_secs(5),
+                managed_install::managed_codex_version(&selected),
+            )
+            .await
+            .ok()
+            .and_then(Result::ok),
+            restart_required: backend.is_some(),
+        })? {
+            return Ok(false);
+        }
+    } else {
+        eprintln!(
+            "Installing daemon from CLI version {version} into {}...",
+            root.display()
+        );
+    }
+    // Confirmation must not block lifecycle commands. Recheck the approved
+    // selection and running state once this operation owns both locks.
+    let _operation_lock = if mode == InstallMode::Replace {
+        Some(daemon.acquire_operation_lock().await?)
+    } else {
+        None // Initial startup already holds the operation lock.
+    };
+    let current_settings = if mode == InstallMode::Replace {
+        Some(daemon.load_settings().await?)
+    } else {
+        None
+    };
+    let settings = current_settings.as_ref().unwrap_or(settings);
+    let _install_lock = acquire_install_lock(&root).await?;
+    anyhow::ensure!(
+        managed_install::package_root(home) == previous_root,
+        "daemon package location changed; retry the command"
+    );
+    if mode == InstallMode::Missing && managed_install::managed_codex_bin(home).is_file() {
+        return Ok(true);
+    }
+    anyhow::ensure!(
+        previous_root.join("current").canonicalize().ok() == previous_release,
+        "daemon selection changed while awaiting confirmation; retry the command"
+    );
+    let current_backend = daemon.running_backend_instance(settings).await?;
+    anyhow::ensure!(
+        current_backend.is_some() == backend.is_some(),
+        "daemon running state changed while awaiting confirmation; retry the command"
+    );
+    let backend = current_backend;
+    let stable = stable_version(&version).is_some();
+    let releases = root.join("releases");
+    std::fs::create_dir_all(&releases)?;
+    let stage = tempfile::Builder::new()
+        .prefix(".staging.")
+        .tempdir_in(&releases)?;
+    let digest = package_tree(source, Some(stage.path()))?;
+    validate_package(stage.path())?;
+    let staged_exe = if cfg!(target_os = "macos") && stage.path().join("CodexCLI.app").is_dir() {
+        stage.path().join("CodexCLI.app/Contents/MacOS/codex")
+    } else {
+        stage.path().join(entrypoint)
+    };
+    anyhow::ensure!(
+        package_tree(source, /*destination*/ None)? == digest
+            && std::fs::read(stage.path().join("codex-package.json"))? == manifest_bytes
+            && managed_install::executable_identity(&staged_exe).await? == running_identity,
+        "the CLI package changed while preparing the daemon or differs from the running executable"
+    );
+    let binary_version =
+        managed_install::managed_codex_version(&stage.path().join(entrypoint)).await?;
+    anyhow::ensure!(
+        !stable || version == binary_version,
+        "the CLI package version does not match its executable"
+    );
+    let name = if stable && mode == InstallMode::Missing {
+        format!("{version}-{target}")
+    } else {
+        format!("local-{digest}-{target}")
+    };
+    let release = releases.join(&name);
+    if release.try_exists()? {
+        anyhow::ensure!(
+            !release.symlink_metadata()?.file_type().is_symlink()
+                && package_tree(&release, /*destination*/ None)? == digest,
+            "an existing daemon release has different contents; refusing to overwrite it"
+        );
+    } else {
+        #[cfg(unix)]
+        if !stage.path().join("codex").exists() {
+            std::os::unix::fs::symlink("bin/codex", stage.path().join("codex"))?;
+        }
+        std::fs::rename(stage.path(), &release)?;
+    }
+    let standalone = home.join("packages/standalone");
+    let canonical_source = source.canonicalize()?;
+    let follows_latest = mode == InstallMode::Missing
+        && stable
+        && (standalone.join("current").canonicalize().ok().as_deref()
+            != Some(canonical_source.as_path())
+            || std::fs::read_to_string(standalone.join("auto-update-version"))
+                .ok()
+                .as_deref()
+                == canonical_source.file_name().and_then(|name| name.to_str()));
+    anyhow::ensure!(
+        managed_install::package_root(home) == previous_root
+            && (backend.is_some() || crate::client::probe(&daemon.socket_path).await.is_err()),
+        "daemon package location or socket ownership changed while preparing its package; retry the command"
+    );
+    #[cfg(windows)]
+    if backend.is_some() {
+        crate::backend::windows::ensure_detached_launch(&release.join(entrypoint))?;
+    }
+    #[cfg(windows)]
+    windows::validate_selection(&root)?;
+    if mode == InstallMode::Replace {
+        let stopped = async {
+            crate::backend::pid_update_loop_backend(daemon.backend_paths(settings))
+                .stop()
+                .await?;
+            anyhow::ensure!(
+                managed_install::package_root(home) == previous_root
+                    && previous_root.join("current").canonicalize().ok() == previous_release,
+                "daemon selection changed while preparing its package; retry the command"
+            );
+            if let Some(backend) = &backend {
+                if let Err(error) = crate::thread_recovery::discard_pending(daemon) {
+                    eprintln!(
+                        "warning: failed to clear stale daemon recovery before replacement: {error}"
+                    );
+                }
+                backend
+                    .stop_with_grace(settings.shutdown_grace_seconds)
+                    .await?;
+            }
+            Ok::<(), anyhow::Error>(())
+        }
+        .await;
+        if let Err(error) = stopped {
+            if let Err(restore_error) = async {
+                daemon
+                    .current_installation()?
+                    .ensure_managed_updater(settings)
+                    .await
+            }
+            .await
+            {
+                eprintln!(
+                    "warning: failed to restore the daemon updater after replacement failed: {restore_error:#}"
+                );
+            }
+            return Err(error);
+        }
+    }
+    let marker = root.join("auto-update-version");
+    if follows_latest {
+        let temporary = tempfile::NamedTempFile::new_in(&root)?;
+        std::fs::write(temporary.path(), &name)?;
+        temporary.persist(marker)?;
+    } else if marker.exists() {
+        std::fs::remove_file(marker)?;
+    }
+    #[cfg(unix)]
+    {
+        let temporary = tempfile::TempDir::new_in(&root)?;
+        let link = temporary.path().join("current");
+        std::os::unix::fs::symlink(&release, &link)?;
+        std::fs::rename(link, root.join("current"))?;
+    }
+    #[cfg(windows)]
+    windows::select_release(&root, &release)?;
+    if backend.is_some() {
+        let selected = Daemon {
+            pid_file: daemon.pid_file.with_file_name(crate::DAEMON_PID_FILE_NAME),
+            update_pid_file: daemon
+                .update_pid_file
+                .with_file_name(crate::DAEMON_UPDATE_PID_FILE_NAME),
+            managed_codex_bin: root.join("current").join(entrypoint),
+            ..daemon.clone()
+        };
+        selected.start_managed_backend(settings).await.context(
+            "daemon package selected but could not start; retry with `codex app-server daemon start`",
+        )?;
+        selected.wait_until_ready().await?;
+    }
+    Ok(true)
+}
+
+/// Hash the complete tree and optionally copy those same bytes. Relative file
+/// links are materialized; escaping links and directory links are rejected.
+fn package_tree(root: &Path, destination: Option<&Path>) -> Result<String> {
+    let canonical_root = root.canonicalize()?;
+    let mut hasher = blake3::Hasher::new();
+    let mut paths = vec![root.to_path_buf()];
+    while let Some(path) = paths.pop() {
+        let relative = path.strip_prefix(root)?;
+        // The Unix installer adds this alias outside the package layout.
+        if cfg!(unix)
+            && relative == Path::new("codex")
+            && std::fs::read_link(&path).ok().as_deref() == Some(Path::new("bin/codex"))
+        {
+            continue;
+        }
+        anyhow::ensure!(
+            path.canonicalize()?.starts_with(&canonical_root),
+            "package link escapes its root"
+        );
+        let metadata = path.metadata()?;
+        hasher.update(relative.as_os_str().as_encoded_bytes());
+        hasher.update(&[0]);
+        if metadata.is_dir() {
+            anyhow::ensure!(
+                !path.symlink_metadata()?.file_type().is_symlink(),
+                "package contains a directory link"
+            );
+            hasher.update(b"directory");
+            if let Some(destination) = destination
+                && !relative.as_os_str().is_empty()
+            {
+                std::fs::create_dir(destination.join(relative))?;
+            }
+            let mut entries = std::fs::read_dir(&path)?
+                .map(|entry| entry.map(|entry| entry.path()))
+                .collect::<std::io::Result<Vec<_>>>()?;
+            entries.sort();
+            paths.extend(entries);
+        } else {
+            anyhow::ensure!(metadata.is_file(), "package contains an unsupported file");
+            let bytes = std::fs::read(&path)?;
+            hasher.update(b"file");
+            hasher.update(blake3::hash(&bytes).as_bytes());
+            #[cfg(unix)]
+            {
+                use std::os::unix::fs::PermissionsExt;
+                hasher.update(&(metadata.permissions().mode() & 0o777).to_le_bytes());
+            }
+            if let Some(destination) = destination {
+                let target = destination.join(relative);
+                std::fs::write(&target, bytes)?;
+                std::fs::set_permissions(target, metadata.permissions())?;
+            }
+        }
+    }
+    Ok(hasher.finalize().to_hex().to_string())
+}
+
+fn stable_version(value: &str) -> Option<semver::Version> {
+    let version = semver::Version::parse(value).ok()?;
+    (version.pre.is_empty()
+        && version.build.is_empty()
+        && (version.major, version.minor, version.patch) != (0, 0, 0))
+        .then_some(version)
+}
+
+fn validate_package(root: &Path) -> Result<()> {
+    let mut names = vec![
+        "codex-package.json",
+        if cfg!(windows) {
+            "bin/codex.exe"
+        } else {
+            "bin/codex"
+        },
+        if cfg!(windows) {
+            "bin/codex-code-mode-host.exe"
+        } else {
+            "bin/codex-code-mode-host"
+        },
+        if cfg!(windows) {
+            "codex-path/rg.exe"
+        } else {
+            "codex-path/rg"
+        },
+    ];
+    if cfg!(windows) {
+        names.extend([
+            "codex-resources/codex-command-runner.exe",
+            "codex-resources/codex-windows-sandbox-setup.exe",
+        ]);
+    } else if cfg!(target_os = "linux") {
+        names.push("codex-resources/bwrap");
+    }
+    for name in names {
+        if !root.join(name).is_file() {
+            return Err(anyhow!(
+                "local Codex package is missing {name}; reinstall the CLI or use the standalone installer"
+            ));
+        }
+        #[cfg(unix)]
+        if name != "codex-package.json" {
+            use std::os::unix::fs::PermissionsExt;
+            if std::fs::metadata(root.join(name))?.permissions().mode() & 0o111 == 0 {
+                return Err(anyhow!(
+                    "local Codex package file {name} is not executable; reinstall the CLI or use the standalone installer"
+                ));
+            }
+        }
+    }
+    Ok(())
+}
+
+fn platform_target() -> Result<&'static str> {
+    match (std::env::consts::OS, std::env::consts::ARCH) {
+        ("macos", "aarch64") => Ok("aarch64-apple-darwin"),
+        ("macos", "x86_64") => Ok("x86_64-apple-darwin"),
+        ("linux", "aarch64") if cfg!(target_env = "gnu") => Ok("aarch64-unknown-linux-gnu"),
+        ("linux", "aarch64") => Ok("aarch64-unknown-linux-musl"),
+        ("linux", "x86_64") if cfg!(target_env = "gnu") => Ok("x86_64-unknown-linux-gnu"),
+        ("linux", "x86_64") => Ok("x86_64-unknown-linux-musl"),
+        ("windows", "aarch64") => Ok("aarch64-pc-windows-msvc"),
+        ("windows", "x86_64") => Ok("x86_64-pc-windows-msvc"),
+        (os, arch) => Err(anyhow!("unsupported packaged daemon platform {os}/{arch}")),
+    }
+}
+
+#[cfg(windows)]
+#[path = "prepare_install_windows.rs"]
+mod windows;
+
+#[cfg(test)]
+#[path = "prepare_install_tests.rs"]
+mod tests;

codex-rs/app-server-daemon/src/prepare_install_tests.rs

@@ -0,0 +1,385 @@
+//! Covers complete-package staging, conservative selection, and legacy preservation.
+#![cfg(unix)]
+use super::InstallMode;
+use super::prepare_from_package;
+use super::validate_package;
+use crate::settings::DaemonSettings;
+use pretty_assertions::assert_eq;
+use std::os::unix::fs::PermissionsExt;
+use std::path::Path;
+use std::path::PathBuf;
+
+fn daemon(home: &std::path::Path) -> crate::Daemon {
+    let state = home.join("app-server-daemon");
+    crate::Daemon {
+        socket_path: state.join("app-server.sock"),
+        pid_file: state.join("app-server.pid"),
+        update_pid_file: state.join("app-server-updater.pid"),
+        operation_lock_file: state.join("daemon.lock"),
+        settings_file: state.join("settings.json"),
+        managed_codex_bin: crate::managed_install::managed_codex_bin(home),
+    }
+}
+
+fn package(root: &Path, version: &str) -> PathBuf {
+    let target = super::platform_target().expect("target");
+    for dir in ["bin", "codex-path", "codex-resources/nested"] {
+        std::fs::create_dir_all(root.join(dir)).expect("package directory");
+    }
+    let bin = root.join("bin/codex");
+    std::fs::write(&bin, format!("#!/bin/sh\necho 'codex {version}'\n")).expect("codex executable");
+    for file in [
+        "bin/codex-code-mode-host",
+        "codex-path/rg",
+        "codex-resources/nested/runtime",
+    ] {
+        std::fs::write(root.join(file), b"runtime").expect("package file");
+        if file != "codex-resources/nested/runtime" {
+            std::fs::set_permissions(root.join(file), std::fs::Permissions::from_mode(0o755))
+                .expect("executable helper");
+        }
+    }
+    if cfg!(target_os = "linux") {
+        std::fs::write(root.join("codex-resources/bwrap"), b"runtime").expect("bwrap");
+        std::fs::set_permissions(
+            root.join("codex-resources/bwrap"),
+            std::fs::Permissions::from_mode(0o755),
+        )
+        .expect("executable bwrap");
+    }
+    std::fs::set_permissions(&bin, std::fs::Permissions::from_mode(0o755))
+        .expect("executable permission");
+    std::fs::write(
+        root.join("codex-package.json"),
+        serde_json::json!({
+            "version": version, "target": target, "entrypoint": "bin/codex"
+        })
+        .to_string(),
+    )
+    .expect("manifest");
+    bin
+}
+
+#[tokio::test]
+async fn seeds_full_package() {
+    let temp = tempfile::TempDir::new().expect("temp");
+    let home = temp.path().join("home");
+    let daemon = daemon(&home);
+    let settings = DaemonSettings::default();
+    let old = temp.path().join("old");
+    let old_bin = package(&old, "0.152.0");
+    prepare_from_package(
+        &daemon,
+        &settings,
+        InstallMode::Missing,
+        Some(&old),
+        &old_bin,
+        |_| Ok(true),
+    )
+    .await
+    .expect("seed");
+
+    let standalone = home.join("packages/app-server-daemon");
+    let selected = std::fs::canonicalize(standalone.join("current")).expect("selected");
+    assert_eq!(
+        std::fs::read(selected.join("codex-resources/nested/runtime")).expect("runtime"),
+        b"runtime"
+    );
+    assert_eq!(
+        std::fs::read_to_string(standalone.join("auto-update-version")).expect("marker"),
+        selected.file_name().expect("name").to_string_lossy()
+    );
+    assert!(validate_package(&selected).is_ok());
+}
+
+#[tokio::test]
+async fn incomplete_source_fails_without_selecting_it() {
+    let temp = tempfile::TempDir::new().expect("temp");
+    let source = temp.path().join("package");
+    let bin = package(&source, "0.152.0");
+    std::fs::remove_file(source.join("bin/codex-code-mode-host")).expect("remove helper");
+    let home = temp.path().join("home");
+    let error = prepare_from_package(
+        &daemon(&home),
+        &DaemonSettings::default(),
+        InstallMode::Missing,
+        Some(&source),
+        &bin,
+        |_| Ok(true),
+    )
+    .await
+    .expect_err("incomplete package");
+    assert!(error.to_string().contains("bin/codex-code-mode-host"));
+    assert!(!home.join("packages/app-server-daemon/current").exists());
+}
+
+#[cfg(target_os = "macos")]
+#[tokio::test]
+async fn provisioned_macos_bundle_seeds_from_its_running_executable() {
+    let temp = tempfile::TempDir::new().expect("temp");
+    let source = temp.path().join("package");
+    let launcher = package(&source, "0.1.0-internal-test.202609091200.1");
+    std::fs::write(&launcher, b"#!/bin/sh\necho codex 0.0.0\n").expect("launcher");
+    let bundle = source.join("CodexCLI.app/Contents/MacOS/codex");
+    std::fs::create_dir_all(bundle.parent().expect("bundle parent")).expect("bundle dir");
+    std::fs::write(&bundle, b"provisioned executable").expect("bundle executable");
+    let home = temp.path().join("home");
+    prepare_from_package(
+        &daemon(&home),
+        &DaemonSettings::default(),
+        InstallMode::Missing,
+        Some(&source),
+        &bundle,
+        |_| Ok(true),
+    )
+    .await
+    .expect("seed provisioned bundle");
+    let selected = std::fs::canonicalize(home.join("packages/app-server-daemon/current"))
+        .expect("selected release");
+    assert_eq!(
+        std::fs::read(selected.join("CodexCLI.app/Contents/MacOS/codex"))
+            .expect("bundled executable"),
+        b"provisioned executable"
+    );
+    assert!(
+        !home
+            .join("packages/app-server-daemon/auto-update-version")
+            .exists()
+    );
+}
+
+#[tokio::test]
+async fn legacy_selection_is_not_migrated_or_refreshed() {
+    let temp = tempfile::TempDir::new().unwrap();
+    let home = temp.path().join("home");
+    let legacy = home.join("packages/standalone");
+    let bin = package(&legacy.join("releases/old"), "0.150.0");
+    std::os::unix::fs::symlink("releases/old", legacy.join("current")).unwrap();
+    let state = home.join("app-server-daemon");
+    std::fs::create_dir(&state).unwrap();
+    std::fs::write(state.join("app-server.stderr.log"), b"").unwrap();
+    let source = temp.path().join("new");
+    let new_bin = package(&source, "0.160.0");
+    prepare_from_package(
+        &daemon(&home),
+        &DaemonSettings::default(),
+        InstallMode::Missing,
+        Some(&source),
+        &new_bin,
+        |_| Ok(true),
+    )
+    .await
+    .unwrap();
+    assert_eq!(
+        crate::managed_install::managed_codex_bin(&home)
+            .canonicalize()
+            .unwrap(),
+        bin.canonicalize().unwrap()
+    );
+    assert!(!home.join("packages/app-server-daemon").exists());
+}
+
+#[tokio::test]
+async fn standalone_seed_preserves_explicit_pin_or_latest_channel() {
+    for follows_latest in [false, true] {
+        let temp = tempfile::TempDir::new().unwrap();
+        let home = temp.path().join("home");
+        let standalone = home.join("packages/standalone");
+        let source = standalone.join("releases/0.152.0-local-target");
+        let bin = package(&source, "0.152.0");
+        std::os::unix::fs::symlink(&source, standalone.join("current")).unwrap();
+        if follows_latest {
+            std::fs::write(
+                standalone.join("auto-update-version"),
+                "0.152.0-local-target",
+            )
+            .unwrap();
+        }
+        prepare_from_package(
+            &daemon(&home),
+            &DaemonSettings::default(),
+            InstallMode::Missing,
+            Some(&source),
+            &bin,
+            |_| Ok(true),
+        )
+        .await
+        .unwrap();
+        let root = home.join("packages/app-server-daemon");
+        let selected = root.join("current").canonicalize().unwrap();
+        assert_eq!(
+            std::fs::read_to_string(root.join("auto-update-version")).ok(),
+            follows_latest.then(|| selected.file_name().unwrap().to_string_lossy().into_owned())
+        );
+    }
+}
+
+#[tokio::test]
+async fn explicit_selection_requires_unchanged_cli_and_pins_all_versions() {
+    for legacy in [false, true] {
+        let temp = tempfile::TempDir::new().unwrap();
+        let home = temp.path().join("home");
+        let source = temp.path().join("source");
+        let bin = package(&source, "0.152.0");
+        let settings = DaemonSettings::default();
+        let initial = daemon(&home);
+        prepare_from_package(
+            &initial,
+            &settings,
+            InstallMode::Missing,
+            Some(&source),
+            &bin,
+            |_| Ok(true),
+        )
+        .await
+        .unwrap();
+        if legacy {
+            std::fs::rename(
+                home.join("packages/app-server-daemon"),
+                home.join("packages/standalone"),
+            )
+            .unwrap();
+            let root = home.join("packages/standalone");
+            let name = std::fs::read_to_string(root.join("auto-update-version")).unwrap();
+            std::fs::remove_file(root.join("current")).unwrap();
+            std::os::unix::fs::symlink(root.join("releases").join(name), root.join("current"))
+                .unwrap();
+            let state = home.join("app-server-daemon");
+            std::fs::create_dir_all(&state).unwrap();
+            std::fs::write(state.join("app-server.stderr.log"), b"").unwrap();
+        }
+        let initial_root = crate::managed_install::package_root(&home);
+        let legacy_release = initial_root.join("current").canonicalize().unwrap();
+        let legacy_marker = std::fs::read(initial_root.join("auto-update-version")).unwrap();
+        let error = prepare_from_package(
+            &daemon(&home),
+            &settings,
+            InstallMode::Replace,
+            Some(&source),
+            &bin,
+            |_| {
+                let mut rebuilt = std::fs::read(&bin)?;
+                rebuilt.extend_from_slice(b"# rebuilt during confirmation\n");
+                std::fs::write(&bin, rebuilt)?;
+                Ok(true)
+            },
+        )
+        .await
+        .expect_err("reject a CLI rebuilt during confirmation");
+        assert!(
+            error
+                .to_string()
+                .contains("differs from the running executable")
+        );
+        assert_eq!(
+            initial_root.join("current").canonicalize().unwrap(),
+            legacy_release
+        );
+        assert_eq!(
+            std::fs::read(initial_root.join("auto-update-version")).unwrap(),
+            legacy_marker
+        );
+        let root = home.join("packages/app-server-daemon");
+        let mut previous = legacy_release.clone();
+        for version in [
+            "0.153.0",
+            "0.151.0",
+            "0.151.0",
+            "0.154.0-alpha.1",
+            "0.0.0",
+            "0.0.0",
+        ] {
+            let daemon = daemon(&home);
+            let previous_root = crate::managed_install::package_root(&home);
+            package(&source, version);
+            std::fs::write(
+                source.join("codex-resources/nested/runtime"),
+                previous.to_string_lossy().as_bytes(),
+            )
+            .unwrap();
+            let before = std::fs::read(previous.join("bin/codex")).unwrap();
+            assert!(
+                !prepare_from_package(
+                    &daemon,
+                    &settings,
+                    InstallMode::Replace,
+                    Some(&source),
+                    &bin,
+                    |request| {
+                        assert_eq!(request.destination, root);
+                        Ok(false)
+                    }
+                )
+                .await
+                .unwrap()
+            );
+            assert_eq!(crate::managed_install::package_root(&home), previous_root);
+            assert_eq!(
+                previous_root.join("current").canonicalize().unwrap(),
+                previous
+            );
+            prepare_from_package(
+                &daemon,
+                &settings,
+                InstallMode::Replace,
+                Some(&source),
+                &bin,
+                |_| Ok(true),
+            )
+            .await
+            .unwrap();
+            let selected = root.join("current").canonicalize().unwrap();
+            assert_eq!(crate::managed_install::package_root(&home), root);
+            if legacy {
+                assert_eq!(
+                    initial_root.join("current").canonicalize().unwrap(),
+                    legacy_release
+                );
+                assert_eq!(
+                    std::fs::read(initial_root.join("auto-update-version")).unwrap(),
+                    legacy_marker
+                );
+            }
+            assert_ne!(selected, previous);
+            assert_eq!(
+                std::fs::read(selected.join("bin/codex")).unwrap(),
+                std::fs::read(&bin).unwrap()
+            );
+            assert_eq!(std::fs::read(previous.join("bin/codex")).unwrap(), before);
+            assert!(!root.join("auto-update-version").exists());
+            assert!(daemon.running_backend(&settings).await.unwrap().is_none());
+            previous = selected;
+        }
+    }
+}
+
+#[tokio::test]
+async fn broken_selection_is_not_a_missing_installation() {
+    let temp = tempfile::TempDir::new().unwrap();
+    let home = temp.path().join("home");
+    let source = temp.path().join("source");
+    let bin = package(&source, "0.152.0");
+    let daemon = daemon(&home);
+    let current = home.join("packages/app-server-daemon/current");
+    std::fs::create_dir_all(current.parent().unwrap()).unwrap();
+    std::os::unix::fs::symlink("missing-release", &current).unwrap();
+    let error = prepare_from_package(
+        &daemon,
+        &DaemonSettings::default(),
+        InstallMode::Missing,
+        Some(&source),
+        &bin,
+        |_| panic!("broken installation must not request replacement"),
+    )
+    .await
+    .unwrap_err();
+    assert!(
+        error
+            .to_string()
+            .contains("repair the existing installation")
+    );
+    assert_eq!(
+        std::fs::read_link(current).unwrap(),
+        PathBuf::from("missing-release")
+    );
+}

codex-rs/app-server-daemon/src/prepare_install_windows.rs

@@ -0,0 +1,97 @@
+//! Selects a Windows managed release by creating or retargeting the installer junction.
+
+use std::os::windows::ffi::OsStrExt;
+use std::os::windows::fs::OpenOptionsExt;
+use std::os::windows::io::AsRawHandle;
+use std::path::Path;
+
+use anyhow::Context;
+use anyhow::Result;
+use windows_sys::Win32::Storage::FileSystem::FILE_FLAG_BACKUP_SEMANTICS;
+use windows_sys::Win32::Storage::FileSystem::FILE_FLAG_OPEN_REPARSE_POINT;
+use windows_sys::Win32::Storage::FileSystem::FILE_SHARE_DELETE;
+use windows_sys::Win32::Storage::FileSystem::FILE_SHARE_READ;
+use windows_sys::Win32::Storage::FileSystem::FILE_SHARE_WRITE;
+use windows_sys::Win32::System::IO::DeviceIoControl;
+
+pub(super) fn select_release(root: &Path, release: &Path) -> Result<()> {
+    let release = release.canonicalize()?;
+    let current = root.join("current");
+    if current.symlink_metadata().is_err() {
+        let temporary = tempfile::TempDir::new_in(root)?;
+        let junction = temporary.path().join("current");
+        std::fs::create_dir(&junction)?;
+        retarget_junction(&junction, &release)?;
+        std::fs::rename(junction, &current)?;
+        return Ok(());
+    }
+    validate_selection(root)?;
+    retarget_junction(&current, &release)
+}
+
+pub(super) fn validate_selection(root: &Path) -> Result<()> {
+    let current = root.join("current");
+    if matches!(current.symlink_metadata(), Err(error) if error.kind() == std::io::ErrorKind::NotFound)
+    {
+        return Ok(());
+    }
+    anyhow::ensure!(
+        current.canonicalize()?.parent() == Some(root.join("releases").canonicalize()?.as_path()),
+        "refusing to replace a daemon selection outside its releases directory"
+    );
+    Ok(())
+}
+
+fn retarget_junction(current: &Path, release: &Path) -> Result<()> {
+    // Use the same mount-point reparse operation as the standalone installer.
+    // Retargeting in place keeps current available to concurrent readers.
+    const FSCTL_SET_REPARSE_POINT: u32 = 0x0009_00a4;
+    const IO_REPARSE_TAG_MOUNT_POINT: u32 = 0xa000_0003;
+    const GENERIC_WRITE: u32 = 0x4000_0000;
+    let release: Vec<u16> = release.as_os_str().encode_wide().collect();
+    let prefix: Vec<u16> = r"\\?\".encode_utf16().collect();
+    let release = release.strip_prefix(prefix.as_slice()).unwrap_or(&release);
+    let substitute: Vec<u8> = r"\??\"
+        .encode_utf16()
+        .chain(release.iter().copied())
+        .flat_map(u16::to_le_bytes)
+        .collect();
+    u16::try_from(substitute.len() + 20).context("managed release path is too long")?;
+    let length = substitute.len() as u16;
+    // REPARSE_DATA_BUFFER: an 8-byte header, then four u16 byte offsets/lengths
+    // for substitute and print names. The UTF-16 path buffer starts at byte 16;
+    // both names have a trailing NUL, and the print name is empty.
+    let mut data = vec![0; substitute.len() + 20];
+    data[0..4].copy_from_slice(&IO_REPARSE_TAG_MOUNT_POINT.to_le_bytes());
+    data[4..6].copy_from_slice(&(length + 12).to_le_bytes());
+    data[10..12].copy_from_slice(&length.to_le_bytes());
+    data[12..14].copy_from_slice(&(length + 2).to_le_bytes());
+    data[16..16 + substitute.len()].copy_from_slice(&substitute);
+    let handle = std::fs::OpenOptions::new()
+        .access_mode(GENERIC_WRITE)
+        .share_mode(FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE)
+        .custom_flags(FILE_FLAG_BACKUP_SEMANTICS | FILE_FLAG_OPEN_REPARSE_POINT)
+        .open(current)?;
+    let mut returned = 0;
+    if unsafe {
+        DeviceIoControl(
+            handle.as_raw_handle() as isize,
+            FSCTL_SET_REPARSE_POINT,
+            data.as_ptr().cast(),
+            data.len() as u32,
+            std::ptr::null_mut(),
+            0,
+            &mut returned,
+            std::ptr::null_mut(),
+        )
+    } == 0
+    {
+        return Err(std::io::Error::last_os_error())
+            .context("failed to retarget managed daemon junction");
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+#[path = "prepare_install_windows_tests.rs"]
+mod tests;

codex-rs/app-server-daemon/src/prepare_install_windows_tests.rs

@@ -0,0 +1,19 @@
+//! Verifies Windows selection without requiring an elevated daemon.
+use pretty_assertions::assert_eq;
+
+#[cfg(windows)]
+#[test]
+fn daemon_junction_can_be_created_and_retargeted_without_cli_links() {
+    let home = tempfile::TempDir::new().unwrap();
+    let root = home.path().join("packages/app-server-daemon");
+    for version in ["first", "second"] {
+        let release = root.join("releases").join(version);
+        std::fs::create_dir_all(&release).unwrap();
+        super::select_release(&root, &release).unwrap();
+        assert_eq!(
+            root.join("current").canonicalize().unwrap(),
+            release.canonicalize().unwrap()
+        );
+    }
+    assert!(!home.path().join("packages/standalone").exists());
+}

codex-rs/app-server-daemon/src/remote_control_client.rs

@@ -0,0 +1,770 @@
+use std::path::Path;
+use std::time::Duration;
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::anyhow;
+use codex_app_server_protocol::JSONRPCMessage;
+use codex_app_server_protocol::JSONRPCNotification;
+use codex_app_server_protocol::JSONRPCRequest;
+use codex_app_server_protocol::RemoteControlConnectionStatus;
+use codex_app_server_protocol::RemoteControlDisableParams;
+use codex_app_server_protocol::RemoteControlDisableResponse;
+use codex_app_server_protocol::RemoteControlEnableParams;
+use codex_app_server_protocol::RemoteControlEnableResponse;
+use codex_app_server_protocol::RemoteControlPairingStartParams;
+use codex_app_server_protocol::RemoteControlPairingStartResponse;
+use codex_app_server_protocol::RemoteControlStatusChangedNotification;
+use codex_app_server_protocol::RequestId;
+use serde::de::DeserializeOwned;
+use tokio::io::AsyncRead;
+use tokio::io::AsyncWrite;
+use tokio::time::Instant;
+use tokio::time::sleep;
+use tokio::time::timeout;
+use tokio_tungstenite::WebSocketStream;
+
+use crate::RemoteControlReadyStatus;
+use crate::client;
+
+const REMOTE_CONTROL_READY_TIMEOUT: Duration = Duration::from_secs(10);
+const REMOTE_CONTROL_REQUEST_ID: RequestId = RequestId::Integer(2);
+const INVALID_PARAMS_ERROR_CODE: i64 = -32602;
+
+enum RemoteControlRpcResponse<T> {
+    Success(T),
+    InvalidParams,
+}
+
+pub(crate) async fn enable_remote_control(socket_path: &Path) -> Result<RemoteControlReadyStatus> {
+    let mut websocket = client::connect(socket_path).await?;
+    enable_remote_control_with_timeout(&mut websocket, REMOTE_CONTROL_READY_TIMEOUT).await
+}
+
+pub(crate) async fn disable_remote_control(socket_path: &Path) -> Result<RemoteControlReadyStatus> {
+    let mut websocket = client::connect(socket_path).await?;
+    initialize_client(&mut websocket).await?;
+    let params = serde_json::to_value(RemoteControlDisableParams { ephemeral: true })?;
+    let response: RemoteControlDisableResponse = request_remote_control_with_legacy_fallback(
+        &mut websocket,
+        "remoteControl/disable",
+        params,
+    )
+    .await?;
+    websocket.close(None).await.ok();
+    Ok(RemoteControlReadyStatus::from(response))
+}
+
+pub(crate) async fn start_pairing(socket_path: &Path) -> Result<RemoteControlPairingStartResponse> {
+    let mut websocket = client::connect(socket_path).await?;
+    initialize_client(&mut websocket).await?;
+    let params = serde_json::to_value(RemoteControlPairingStartParams { manual_code: true })?;
+    send_remote_control_request(
+        &mut websocket,
+        REMOTE_CONTROL_REQUEST_ID.clone(),
+        "remoteControl/pairing/start",
+        Some(params),
+    )
+    .await?;
+    let response = match read_remote_control_response(
+        &mut websocket,
+        &REMOTE_CONTROL_REQUEST_ID,
+        "remoteControl/pairing/start",
+    )
+    .await?
+    {
+        RemoteControlRpcResponse::Success(response) => response,
+        RemoteControlRpcResponse::InvalidParams => {
+            return Err(anyhow!(
+                "remoteControl/pairing/start rejected manual pairing parameters"
+            ));
+        }
+    };
+    websocket.close(None).await.ok();
+    Ok(response)
+}
+
+pub(crate) async fn enable_remote_control_with_connect_retry(
+    socket_path: &Path,
+    connect_timeout: Duration,
+    connect_retry_delay: Duration,
+) -> Result<RemoteControlReadyStatus> {
+    let mut websocket =
+        connect_with_retry(socket_path, connect_timeout, connect_retry_delay).await?;
+    enable_remote_control_with_timeout(&mut websocket, REMOTE_CONTROL_READY_TIMEOUT).await
+}
+
+async fn enable_remote_control_with_timeout<S>(
+    websocket: &mut WebSocketStream<S>,
+    ready_timeout: Duration,
+) -> Result<RemoteControlReadyStatus>
+where
+    S: AsyncRead + AsyncWrite + Unpin,
+{
+    initialize_client(websocket).await?;
+
+    let response: RemoteControlEnableResponse = request_remote_control_with_legacy_fallback(
+        websocket,
+        "remoteControl/enable",
+        serde_json::to_value(RemoteControlEnableParams { ephemeral: true })?,
+    )
+    .await?;
+    let mut latest = RemoteControlReadyStatus::from(response);
+    if latest.status == RemoteControlConnectionStatus::Connecting {
+        latest = wait_for_remote_control_status(websocket, latest, ready_timeout).await?;
+    }
+    websocket.close(None).await.ok();
+    Ok(latest)
+}
+
+async fn initialize_client<S>(websocket: &mut WebSocketStream<S>) -> Result<()>
+where
+    S: AsyncRead + AsyncWrite + Unpin,
+{
+    client::initialize(websocket, /*experimental_api*/ true).await?;
+    let initialized = JSONRPCMessage::Notification(JSONRPCNotification {
+        method: "initialized".to_string(),
+        params: None,
+    });
+    client::send_message(websocket, &initialized)
+        .await
+        .context("failed to send initialized notification")
+}
+
+async fn send_remote_control_request<S>(
+    websocket: &mut WebSocketStream<S>,
+    request_id: RequestId,
+    method: &str,
+    params: Option<serde_json::Value>,
+) -> Result<()>
+where
+    S: AsyncRead + AsyncWrite + Unpin,
+{
+    let request = JSONRPCMessage::Request(JSONRPCRequest {
+        id: request_id,
+        method: method.to_string(),
+        params,
+        trace: None,
+    });
+    client::send_message(websocket, &request)
+        .await
+        .with_context(|| format!("failed to send {method} request"))
+}
+
+async fn request_remote_control_with_legacy_fallback<S, T>(
+    websocket: &mut WebSocketStream<S>,
+    method: &str,
+    params: serde_json::Value,
+) -> Result<T>
+where
+    S: AsyncRead + AsyncWrite + Unpin,
+    T: DeserializeOwned,
+{
+    send_remote_control_request(
+        websocket,
+        REMOTE_CONTROL_REQUEST_ID.clone(),
+        method,
+        Some(params),
+    )
+    .await?;
+    match read_remote_control_response(websocket, &REMOTE_CONTROL_REQUEST_ID, method).await? {
+        RemoteControlRpcResponse::Success(response) => Ok(response),
+        RemoteControlRpcResponse::InvalidParams => {
+            send_remote_control_request(
+                websocket,
+                REMOTE_CONTROL_REQUEST_ID.clone(),
+                method,
+                /*params*/ None,
+            )
+            .await?;
+            match read_remote_control_response(websocket, &REMOTE_CONTROL_REQUEST_ID, method)
+                .await?
+            {
+                RemoteControlRpcResponse::Success(response) => Ok(response),
+                RemoteControlRpcResponse::InvalidParams => {
+                    Err(anyhow!("{method} rejected legacy params"))
+                }
+            }
+        }
+    }
+}
+
+async fn connect_with_retry(
+    socket_path: &Path,
+    connect_timeout: Duration,
+    connect_retry_delay: Duration,
+) -> Result<WebSocketStream<codex_uds::UnixStream>> {
+    let deadline = Instant::now() + connect_timeout;
+    loop {
+        match client::connect(socket_path).await {
+            Ok(websocket) => return Ok(websocket),
+            Err(_) if Instant::now() < deadline => {
+                sleep(connect_retry_delay).await;
+            }
+            Err(error) => {
+                return Err(error).with_context(|| {
+                    format!(
+                        "app server did not become ready on {}",
+                        socket_path.display()
+                    )
+                });
+            }
+        }
+    }
+}
+
+async fn read_remote_control_response<S, T>(
+    websocket: &mut WebSocketStream<S>,
+    request_id: &RequestId,
+    method: &str,
+) -> Result<RemoteControlRpcResponse<T>>
+where
+    S: AsyncRead + AsyncWrite + Unpin,
+    T: DeserializeOwned,
+{
+    loop {
+        let message = timeout(
+            client::CONTROL_SOCKET_RESPONSE_TIMEOUT,
+            client::read_message(websocket),
+        )
+        .await
+        .with_context(|| format!("timed out waiting for {method} response"))??;
+        match message {
+            JSONRPCMessage::Response(response) if response.id == *request_id => {
+                let response = serde_json::from_value::<T>(response.result)
+                    .with_context(|| format!("failed to parse {method} response"))?;
+                return Ok(RemoteControlRpcResponse::Success(response));
+            }
+            JSONRPCMessage::Error(err)
+                if err.id == *request_id && err.error.code == INVALID_PARAMS_ERROR_CODE =>
+            {
+                return Ok(RemoteControlRpcResponse::InvalidParams);
+            }
+            JSONRPCMessage::Error(err) if err.id == *request_id => {
+                return Err(anyhow!("{method} failed: {}", err.error.message));
+            }
+            JSONRPCMessage::Notification(notification)
+                if remote_control_status_notification(&notification).is_some() =>
+            {
+                continue;
+            }
+            _ => {}
+        }
+    }
+}
+
+async fn wait_for_remote_control_status<S>(
+    websocket: &mut WebSocketStream<S>,
+    mut latest: RemoteControlReadyStatus,
+    ready_timeout: Duration,
+) -> Result<RemoteControlReadyStatus>
+where
+    S: AsyncRead + AsyncWrite + Unpin,
+{
+    let deadline = tokio::time::Instant::now() + ready_timeout;
+    while tokio::time::Instant::now() < deadline {
+        let remaining = deadline.saturating_duration_since(tokio::time::Instant::now());
+        let message = match timeout(remaining, client::read_message(websocket)).await {
+            Ok(Ok(message)) => message,
+            Ok(Err(err)) => return Err(err),
+            Err(_) => {
+                latest.timed_out = true;
+                return Ok(latest);
+            }
+        };
+        let JSONRPCMessage::Notification(notification) = message else {
+            continue;
+        };
+        let Some(status) = remote_control_status_notification(&notification) else {
+            continue;
+        };
+        latest = RemoteControlReadyStatus::from(status);
+        if latest.status != RemoteControlConnectionStatus::Connecting {
+            return Ok(latest);
+        }
+    }
+    latest.timed_out = true;
+    Ok(latest)
+}
+
+fn remote_control_status_notification(
+    notification: &JSONRPCNotification,
+) -> Option<RemoteControlStatusChangedNotification> {
+    if notification.method != "remoteControl/status/changed" {
+        return None;
+    }
+    let params = notification.params.clone()?;
+    serde_json::from_value(params).ok()
+}
+
+impl From<RemoteControlEnableResponse> for RemoteControlReadyStatus {
+    fn from(response: RemoteControlEnableResponse) -> Self {
+        let RemoteControlEnableResponse {
+            status,
+            server_name,
+            installation_id: _,
+            environment_id,
+        } = response;
+        Self {
+            status,
+            server_name,
+            environment_id,
+            timed_out: false,
+        }
+    }
+}
+
+impl From<RemoteControlDisableResponse> for RemoteControlReadyStatus {
+    fn from(response: RemoteControlDisableResponse) -> Self {
+        let RemoteControlDisableResponse {
+            status,
+            server_name,
+            installation_id: _,
+            environment_id,
+        } = response;
+        Self {
+            status,
+            server_name,
+            environment_id,
+            timed_out: false,
+        }
+    }
+}
+
+impl From<RemoteControlStatusChangedNotification> for RemoteControlReadyStatus {
+    fn from(notification: RemoteControlStatusChangedNotification) -> Self {
+        let RemoteControlStatusChangedNotification {
+            status,
+            server_name,
+            installation_id: _,
+            environment_id,
+        } = notification;
+        Self {
+            status,
+            server_name,
+            environment_id,
+            timed_out: false,
+        }
+    }
+}
+
+#[cfg(all(test, unix))]
+mod tests {
+    use anyhow::Result;
+    use codex_app_server_protocol::JSONRPCError;
+    use codex_app_server_protocol::JSONRPCErrorError;
+    use codex_app_server_protocol::JSONRPCResponse;
+    use codex_uds::UnixListener;
+    use pretty_assertions::assert_eq;
+    use tempfile::TempDir;
+    use tokio_tungstenite::accept_async;
+
+    use super::*;
+
+    const INITIALIZE_REQUEST_ID: RequestId = RequestId::Integer(1);
+    const TEST_INSTALLATION_ID: &str = "11111111-1111-4111-8111-111111111111";
+    const TEST_SERVER_NAME: &str = "owen-mbp";
+    const TEST_CODEX_HOME: &str = "/tmp/codex-home";
+
+    #[tokio::test]
+    async fn enable_remote_control_uses_connected_enable_response_without_later_notification()
+    -> Result<()> {
+        let status = run_enable_remote_control_scenario(EnableScenario {
+            initial_notification: Some(remote_control_status(
+                RemoteControlConnectionStatus::Connected,
+                Some("env_test"),
+            )),
+            enable_response: remote_control_status(
+                RemoteControlConnectionStatus::Connected,
+                Some("env_test"),
+            ),
+            after_enable_notification: None,
+            ready_timeout: Duration::from_millis(20),
+            reject_ephemeral_params: false,
+        })
+        .await?;
+
+        assert_eq!(
+            status,
+            RemoteControlReadyStatus {
+                status: RemoteControlConnectionStatus::Connected,
+                server_name: TEST_SERVER_NAME.to_string(),
+                environment_id: Some("env_test".to_string()),
+                timed_out: false,
+            }
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn enable_remote_control_waits_for_connected_notification() -> Result<()> {
+        let status = run_enable_remote_control_scenario(EnableScenario {
+            initial_notification: None,
+            enable_response: remote_control_status(
+                RemoteControlConnectionStatus::Connecting,
+                /*environment_id*/ None,
+            ),
+            after_enable_notification: Some(remote_control_status(
+                RemoteControlConnectionStatus::Connected,
+                Some("env_test"),
+            )),
+            ready_timeout: Duration::from_secs(1),
+            reject_ephemeral_params: false,
+        })
+        .await?;
+
+        assert_eq!(
+            status,
+            RemoteControlReadyStatus {
+                status: RemoteControlConnectionStatus::Connected,
+                server_name: TEST_SERVER_NAME.to_string(),
+                environment_id: Some("env_test".to_string()),
+                timed_out: false,
+            }
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn enable_remote_control_reports_connecting_after_timeout() -> Result<()> {
+        let status = run_enable_remote_control_scenario(EnableScenario {
+            initial_notification: None,
+            enable_response: remote_control_status(
+                RemoteControlConnectionStatus::Connecting,
+                /*environment_id*/ None,
+            ),
+            after_enable_notification: None,
+            ready_timeout: Duration::from_millis(20),
+            reject_ephemeral_params: false,
+        })
+        .await?;
+
+        assert_eq!(
+            status,
+            RemoteControlReadyStatus {
+                status: RemoteControlConnectionStatus::Connecting,
+                server_name: TEST_SERVER_NAME.to_string(),
+                environment_id: None,
+                timed_out: true,
+            }
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn enable_remote_control_returns_errored_enable_response() -> Result<()> {
+        let status = run_enable_remote_control_scenario(EnableScenario {
+            initial_notification: None,
+            enable_response: remote_control_status(
+                RemoteControlConnectionStatus::Errored,
+                /*environment_id*/ None,
+            ),
+            after_enable_notification: None,
+            ready_timeout: Duration::from_millis(20),
+            reject_ephemeral_params: false,
+        })
+        .await?;
+
+        assert_eq!(
+            status,
+            RemoteControlReadyStatus {
+                status: RemoteControlConnectionStatus::Errored,
+                server_name: TEST_SERVER_NAME.to_string(),
+                environment_id: None,
+                timed_out: false,
+            }
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn enable_remote_control_retries_without_params_for_older_servers() -> Result<()> {
+        let status = run_enable_remote_control_scenario(EnableScenario {
+            initial_notification: None,
+            enable_response: remote_control_status(
+                RemoteControlConnectionStatus::Connected,
+                Some("env_test"),
+            ),
+            after_enable_notification: None,
+            ready_timeout: Duration::from_millis(20),
+            reject_ephemeral_params: true,
+        })
+        .await?;
+
+        assert_eq!(
+            status,
+            RemoteControlReadyStatus {
+                status: RemoteControlConnectionStatus::Connected,
+                server_name: TEST_SERVER_NAME.to_string(),
+                environment_id: Some("env_test".to_string()),
+                timed_out: false,
+            }
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn disable_remote_control_retries_without_params_for_older_servers() -> Result<()> {
+        let dir = TempDir::new()?;
+        let socket_path = dir.path().join("app-server.sock");
+        let listener = UnixListener::bind(&socket_path).await?;
+        let server_task = tokio::spawn(async move {
+            let mut websocket = accept_initialized_client(listener).await?;
+            let disable = client::read_message(&mut websocket).await?;
+            let JSONRPCMessage::Request(disable) = disable else {
+                panic!("expected remoteControl/disable request");
+            };
+            assert_eq!(disable.id, REMOTE_CONTROL_REQUEST_ID);
+            assert_eq!(disable.method, "remoteControl/disable");
+            assert_eq!(
+                disable.params,
+                Some(serde_json::json!({ "ephemeral": true }))
+            );
+            client::send_message(
+                &mut websocket,
+                &JSONRPCMessage::Error(JSONRPCError {
+                    id: REMOTE_CONTROL_REQUEST_ID,
+                    error: JSONRPCErrorError {
+                        code: INVALID_PARAMS_ERROR_CODE,
+                        message: "Invalid params".to_string(),
+                        data: None,
+                    },
+                }),
+            )
+            .await?;
+            let fallback = client::read_message(&mut websocket).await?;
+            let JSONRPCMessage::Request(fallback) = fallback else {
+                panic!("expected fallback remoteControl/disable request");
+            };
+            assert_eq!(fallback.id, REMOTE_CONTROL_REQUEST_ID);
+            assert_eq!(fallback.method, "remoteControl/disable");
+            assert_eq!(fallback.params, None);
+            client::send_message(
+                &mut websocket,
+                &JSONRPCMessage::Response(JSONRPCResponse {
+                    id: REMOTE_CONTROL_REQUEST_ID,
+                    result: serde_json::to_value(RemoteControlDisableResponse::from(
+                        remote_control_status(
+                            RemoteControlConnectionStatus::Disabled,
+                            /*environment_id*/ None,
+                        ),
+                    ))?,
+                }),
+            )
+            .await?;
+            Ok::<_, anyhow::Error>(())
+        });
+
+        let status = disable_remote_control(&socket_path).await?;
+        server_task.await??;
+        assert_eq!(
+            status,
+            RemoteControlReadyStatus {
+                status: RemoteControlConnectionStatus::Disabled,
+                server_name: TEST_SERVER_NAME.to_string(),
+                environment_id: None,
+                timed_out: false,
+            }
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn start_pairing_requests_manual_code() -> Result<()> {
+        let dir = TempDir::new()?;
+        let socket_path = dir.path().join("app-server.sock");
+        let listener = UnixListener::bind(&socket_path).await?;
+        let server_task = tokio::spawn(async move {
+            let mut websocket = accept_initialized_client(listener).await?;
+            let pairing = client::read_message(&mut websocket).await?;
+            let JSONRPCMessage::Request(pairing) = pairing else {
+                panic!("expected remoteControl/pairing/start request");
+            };
+            assert_eq!(pairing.id, REMOTE_CONTROL_REQUEST_ID);
+            assert_eq!(pairing.method, "remoteControl/pairing/start");
+            assert_eq!(
+                pairing.params,
+                Some(serde_json::json!({ "manualCode": true }))
+            );
+            client::send_message(
+                &mut websocket,
+                &JSONRPCMessage::Response(JSONRPCResponse {
+                    id: REMOTE_CONTROL_REQUEST_ID,
+                    result: serde_json::to_value(RemoteControlPairingStartResponse {
+                        pairing_code: "pairing-code".to_string(),
+                        manual_pairing_code: Some("ABCD-EFGH".to_string()),
+                        environment_id: "env_test".to_string(),
+                        expires_at: 1_700_000_000,
+                    })?,
+                }),
+            )
+            .await?;
+            Ok::<_, anyhow::Error>(())
+        });
+
+        let response = start_pairing(&socket_path).await?;
+        server_task.await??;
+        assert_eq!(
+            response,
+            RemoteControlPairingStartResponse {
+                pairing_code: "pairing-code".to_string(),
+                manual_pairing_code: Some("ABCD-EFGH".to_string()),
+                environment_id: "env_test".to_string(),
+                expires_at: 1_700_000_000,
+            }
+        );
+        Ok(())
+    }
+
+    struct EnableScenario {
+        initial_notification: Option<RemoteControlStatusChangedNotification>,
+        enable_response: RemoteControlStatusChangedNotification,
+        after_enable_notification: Option<RemoteControlStatusChangedNotification>,
+        ready_timeout: Duration,
+        reject_ephemeral_params: bool,
+    }
+
+    async fn run_enable_remote_control_scenario(
+        scenario: EnableScenario,
+    ) -> Result<RemoteControlReadyStatus> {
+        let dir = TempDir::new()?;
+        let socket_path = dir.path().join("app-server.sock");
+        let listener = UnixListener::bind(&socket_path).await?;
+        let ready_timeout = scenario.ready_timeout;
+        let server_task = tokio::spawn(serve_enable_remote_control_scenario(listener, scenario));
+
+        let mut websocket = client::connect(&socket_path).await?;
+        let status = enable_remote_control_with_timeout(&mut websocket, ready_timeout).await?;
+        server_task.await??;
+        Ok(status)
+    }
+
+    async fn serve_enable_remote_control_scenario(
+        listener: UnixListener,
+        scenario: EnableScenario,
+    ) -> Result<()> {
+        let mut websocket = accept_initialized_client(listener).await?;
+        if let Some(status) = scenario.initial_notification {
+            send_remote_control_status(&mut websocket, status).await?;
+        }
+
+        let enable = client::read_message(&mut websocket).await?;
+        let JSONRPCMessage::Request(enable) = enable else {
+            panic!("expected remoteControl/enable request");
+        };
+        assert_eq!(enable.id, REMOTE_CONTROL_REQUEST_ID);
+        assert_eq!(enable.method, "remoteControl/enable");
+        assert_eq!(
+            enable.params,
+            Some(serde_json::json!({ "ephemeral": true }))
+        );
+        if scenario.reject_ephemeral_params {
+            client::send_message(
+                &mut websocket,
+                &JSONRPCMessage::Error(JSONRPCError {
+                    id: REMOTE_CONTROL_REQUEST_ID,
+                    error: JSONRPCErrorError {
+                        code: INVALID_PARAMS_ERROR_CODE,
+                        message: "Invalid params".to_string(),
+                        data: None,
+                    },
+                }),
+            )
+            .await?;
+            let fallback = client::read_message(&mut websocket).await?;
+            let JSONRPCMessage::Request(fallback) = fallback else {
+                panic!("expected fallback remoteControl/enable request");
+            };
+            assert_eq!(fallback.id, REMOTE_CONTROL_REQUEST_ID);
+            assert_eq!(fallback.method, "remoteControl/enable");
+            assert_eq!(fallback.params, None);
+        }
+        client::send_message(
+            &mut websocket,
+            &JSONRPCMessage::Response(JSONRPCResponse {
+                id: REMOTE_CONTROL_REQUEST_ID,
+                result: serde_json::to_value(RemoteControlEnableResponse::from(
+                    scenario.enable_response,
+                ))?,
+            }),
+        )
+        .await?;
+
+        if let Some(status) = scenario.after_enable_notification {
+            send_remote_control_status(&mut websocket, status).await?;
+        } else {
+            tokio::time::sleep(Duration::from_millis(50)).await;
+        }
+
+        Ok(())
+    }
+
+    async fn accept_initialized_client(
+        mut listener: UnixListener,
+    ) -> Result<WebSocketStream<codex_uds::UnixStream>> {
+        let stream = listener.accept().await?;
+        let mut websocket = accept_async(stream).await?;
+        let initialize = client::read_message(&mut websocket).await?;
+        let JSONRPCMessage::Request(initialize) = initialize else {
+            panic!("expected initialize request");
+        };
+        assert_eq!(initialize.id, INITIALIZE_REQUEST_ID);
+        assert_eq!(initialize.method, "initialize");
+        let Some(initialize_params) = initialize.params else {
+            panic!("expected initialize params");
+        };
+        assert_eq!(
+            initialize_params["capabilities"]["experimentalApi"],
+            serde_json::Value::Bool(true)
+        );
+        client::send_message(
+            &mut websocket,
+            &JSONRPCMessage::Response(JSONRPCResponse {
+                id: INITIALIZE_REQUEST_ID,
+                result: serde_json::json!({
+                    "userAgent": "codex_app_server/1.2.3",
+                    "codexHome": TEST_CODEX_HOME,
+                    "platformFamily": "unix",
+                    "platformOs": "macos",
+                }),
+            }),
+        )
+        .await?;
+
+        let initialized = client::read_message(&mut websocket).await?;
+        let JSONRPCMessage::Notification(initialized) = initialized else {
+            panic!("expected initialized notification");
+        };
+        assert_eq!(initialized.method, "initialized");
+        Ok(websocket)
+    }
+
+    async fn send_remote_control_status<S>(
+        websocket: &mut WebSocketStream<S>,
+        status: RemoteControlStatusChangedNotification,
+    ) -> Result<()>
+    where
+        S: tokio::io::AsyncRead + tokio::io::AsyncWrite + Unpin,
+    {
+        client::send_message(
+            websocket,
+            &JSONRPCMessage::Notification(JSONRPCNotification {
+                method: "remoteControl/status/changed".to_string(),
+                params: Some(serde_json::to_value(status)?),
+            }),
+        )
+        .await
+    }
+
+    fn remote_control_status(
+        status: RemoteControlConnectionStatus,
+        environment_id: Option<&str>,
+    ) -> RemoteControlStatusChangedNotification {
+        RemoteControlStatusChangedNotification {
+            status,
+            server_name: TEST_SERVER_NAME.to_string(),
+            installation_id: TEST_INSTALLATION_ID.to_string(),
+            environment_id: environment_id.map(str::to_string),
+        }
+    }
+}

codex-rs/app-server-daemon/src/settings.rs

@@ -0,0 +1,195 @@
+use std::path::Path;
+use std::time::Duration;
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::ensure;
+use serde::Deserialize;
+use serde::de::DeserializeOwned;
+use serde_json::Map;
+use serde_json::Value;
+use tokio::fs;
+
+pub(crate) const DEFAULT_UPDATE_INTERVAL_MINUTES: u32 = 60;
+pub(crate) const DEFAULT_SHUTDOWN_GRACE_SECONDS: u32 = 60;
+pub(crate) const MAX_SHUTDOWN_GRACE_SECONDS: u32 = 5 * 60;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct DaemonSettings {
+    pub(crate) remote_control_enabled: bool,
+    pub(crate) auto_update_enabled: bool,
+    pub(crate) update_interval_minutes: u32,
+    pub(crate) shutdown_grace_seconds: u32,
+}
+
+impl Default for DaemonSettings {
+    fn default() -> Self {
+        Self {
+            remote_control_enabled: false,
+            auto_update_enabled: true,
+            update_interval_minutes: DEFAULT_UPDATE_INTERVAL_MINUTES,
+            shutdown_grace_seconds: DEFAULT_SHUTDOWN_GRACE_SECONDS,
+        }
+    }
+}
+
+#[derive(Default, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct StopSettings {
+    shutdown_grace_seconds: Option<u32>,
+}
+
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct StoredSettings {
+    #[serde(default)]
+    remote_control_enabled: bool,
+    #[serde(default = "default_shutdown_grace_seconds")]
+    shutdown_grace_seconds: u32,
+    #[serde(default)]
+    updater: UpdaterSettings,
+}
+
+impl Default for StoredSettings {
+    fn default() -> Self {
+        Self {
+            remote_control_enabled: false,
+            shutdown_grace_seconds: DEFAULT_SHUTDOWN_GRACE_SECONDS,
+            updater: UpdaterSettings::default(),
+        }
+    }
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct UpdaterSettings {
+    #[serde(default = "default_auto_update_enabled")]
+    pub(crate) auto_update_enabled: bool,
+    #[serde(default = "default_update_interval_minutes")]
+    pub(crate) update_interval_minutes: u32,
+}
+
+impl Default for UpdaterSettings {
+    fn default() -> Self {
+        Self {
+            auto_update_enabled: default_auto_update_enabled(),
+            update_interval_minutes: default_update_interval_minutes(),
+        }
+    }
+}
+
+fn default_auto_update_enabled() -> bool {
+    true
+}
+
+fn default_update_interval_minutes() -> u32 {
+    DEFAULT_UPDATE_INTERVAL_MINUTES
+}
+
+fn default_shutdown_grace_seconds() -> u32 {
+    DEFAULT_SHUTDOWN_GRACE_SECONDS
+}
+
+fn validate_shutdown_grace(seconds: u32) -> Result<()> {
+    ensure!(
+        seconds <= MAX_SHUTDOWN_GRACE_SECONDS,
+        "shutdown grace must be between 0 and {MAX_SHUTDOWN_GRACE_SECONDS} seconds"
+    );
+    Ok(())
+}
+
+impl UpdaterSettings {
+    pub(crate) async fn load(settings_file: &Path) -> Result<Self> {
+        let settings: StoredSettings = read_settings(settings_file).await?;
+        validate_shutdown_grace(settings.shutdown_grace_seconds)?;
+        let settings = settings.updater;
+        settings.validate()?;
+        Ok(settings)
+    }
+
+    pub(crate) fn validate(&self) -> Result<()> {
+        ensure!(
+            self.update_interval_minutes > 0,
+            "update interval must be positive"
+        );
+        Ok(())
+    }
+
+    pub(crate) fn update_interval(&self, minute: Duration) -> Duration {
+        minute * self.update_interval_minutes
+    }
+}
+
+impl DaemonSettings {
+    pub(crate) async fn load(path: &Path) -> Result<Self> {
+        let settings: StoredSettings = read_settings(path).await?;
+        settings.updater.validate()?;
+        validate_shutdown_grace(settings.shutdown_grace_seconds)?;
+        Ok(Self {
+            remote_control_enabled: settings.remote_control_enabled,
+            auto_update_enabled: settings.updater.auto_update_enabled,
+            update_interval_minutes: settings.updater.update_interval_minutes,
+            shutdown_grace_seconds: settings.shutdown_grace_seconds,
+        })
+    }
+
+    pub(crate) async fn load_for_stop(path: &Path) -> Self {
+        // Stop must work even when settings are unreadable or partially edited.
+        let shutdown_grace_seconds = read_settings::<StopSettings>(path)
+            .await
+            .ok()
+            .and_then(|settings| settings.shutdown_grace_seconds)
+            .filter(|&seconds| seconds <= MAX_SHUTDOWN_GRACE_SECONDS)
+            .unwrap_or(DEFAULT_SHUTDOWN_GRACE_SECONDS);
+        Self {
+            shutdown_grace_seconds,
+            ..Self::default()
+        }
+    }
+
+    pub(crate) async fn save(&self, path: &Path) -> Result<()> {
+        if let Some(parent) = path.parent() {
+            fs::create_dir_all(parent).await.with_context(|| {
+                format!(
+                    "failed to create daemon settings directory {}",
+                    parent.display()
+                )
+            })?;
+        }
+        let mut settings: Map<String, Value> = read_settings(path).await?;
+        settings.insert(
+            "remoteControlEnabled".to_string(),
+            Value::Bool(self.remote_control_enabled),
+        );
+        let contents =
+            serde_json::to_vec_pretty(&settings).context("failed to serialize settings")?;
+        let temporary_path = path.with_extension("tmp");
+        fs::write(&temporary_path, contents)
+            .await
+            .with_context(|| {
+                format!(
+                    "failed to write daemon settings {}",
+                    temporary_path.display()
+                )
+            })?;
+        fs::rename(&temporary_path, path)
+            .await
+            .with_context(|| format!("failed to replace daemon settings {}", path.display()))
+    }
+}
+
+async fn read_settings<T: DeserializeOwned + Default>(path: &Path) -> Result<T> {
+    let contents = match fs::read_to_string(path).await {
+        Ok(contents) => contents,
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => return Ok(T::default()),
+        Err(err) => {
+            return Err(err).with_context(|| format!("failed to read settings {}", path.display()));
+        }
+    };
+    serde_json::from_str(&contents)
+        .with_context(|| format!("failed to parse settings {}", path.display()))
+}
+
+#[cfg(test)]
+#[path = "settings_tests.rs"]
+mod tests;

codex-rs/app-server-daemon/src/settings_tests.rs

@@ -0,0 +1,130 @@
+use pretty_assertions::assert_eq;
+use tempfile::TempDir;
+
+use super::DaemonSettings;
+use super::MAX_SHUTDOWN_GRACE_SECONDS;
+
+#[tokio::test]
+async fn remote_control_save_preserves_updater_settings() {
+    let temp = TempDir::new().expect("temp dir");
+    let path = temp.path().join("settings.json");
+    tokio::fs::write(&path, r#"{"remoteControlEnabled":true}"#)
+        .await
+        .expect("write legacy settings");
+
+    let settings = DaemonSettings::load(&path).await.expect("load settings");
+    assert_eq!(
+        settings,
+        DaemonSettings {
+            remote_control_enabled: true,
+            ..DaemonSettings::default()
+        }
+    );
+
+    tokio::fs::write(
+        &path,
+        r#"{"remoteControlEnabled":true,"shutdownGraceSeconds":25,"updater":{"autoUpdateEnabled":false,"updateIntervalMinutes":17},"futureSetting":42}"#,
+    )
+    .await
+    .expect("write settings");
+    let updated = DaemonSettings {
+        remote_control_enabled: false,
+        ..DaemonSettings::load(&path)
+            .await
+            .expect("load updater settings")
+    };
+    updated.save(&path).await.expect("save remote control");
+    assert_eq!(
+        serde_json::from_slice::<serde_json::Value>(
+            &tokio::fs::read(&path).await.expect("read settings")
+        )
+        .expect("parse settings"),
+        serde_json::json!({
+            "remoteControlEnabled": false,
+            "shutdownGraceSeconds": 25,
+            "updater": {"autoUpdateEnabled": false, "updateIntervalMinutes": 17},
+            "futureSetting": 42,
+        })
+    );
+}
+
+#[tokio::test]
+async fn shutdown_grace_accepts_zero_through_five_minutes() {
+    let temp = TempDir::new().expect("temp dir");
+    let path = temp.path().join("settings.json");
+    assert_eq!(
+        DaemonSettings::load(&path).await.expect("missing settings"),
+        DaemonSettings::default()
+    );
+    assert_eq!(
+        DaemonSettings::load_for_stop(&path)
+            .await
+            .shutdown_grace_seconds,
+        60
+    );
+
+    for seconds in [
+        0,
+        MAX_SHUTDOWN_GRACE_SECONDS,
+        MAX_SHUTDOWN_GRACE_SECONDS + 1,
+    ] {
+        tokio::fs::write(
+            &path,
+            serde_json::to_vec(&serde_json::json!({"shutdownGraceSeconds": seconds}))
+                .expect("serialize settings"),
+        )
+        .await
+        .expect("write settings");
+        let expected = (seconds <= MAX_SHUTDOWN_GRACE_SECONDS).then_some(seconds);
+        assert_eq!(
+            DaemonSettings::load(&path)
+                .await
+                .ok()
+                .map(|settings| settings.shutdown_grace_seconds),
+            expected
+        );
+        assert_eq!(
+            DaemonSettings::load_for_stop(&path)
+                .await
+                .shutdown_grace_seconds,
+            expected.unwrap_or(60)
+        );
+    }
+
+    tokio::fs::write(&path, r#"{"shutdownGraceSeconds":"unlimited"}"#)
+        .await
+        .expect("write invalid settings");
+    assert!(DaemonSettings::load(&path).await.is_err());
+    assert_eq!(
+        DaemonSettings::load_for_stop(&path)
+            .await
+            .shutdown_grace_seconds,
+        60
+    );
+}
+
+#[tokio::test]
+async fn update_interval_accepts_long_values_and_rejects_zero() {
+    let temp = TempDir::new().expect("temp dir");
+    let path = temp.path().join("settings.json");
+    for minutes in [u32::MAX, 0] {
+        tokio::fs::write(
+            &path,
+            serde_json::to_vec(&serde_json::json!({
+                "updater": {"updateIntervalMinutes": minutes},
+            }))
+            .expect("serialize invalid settings"),
+        )
+        .await
+        .expect("write invalid settings");
+        let loaded = DaemonSettings::load(&path).await;
+        if minutes == 0 {
+            assert!(loaded.is_err());
+        } else {
+            assert_eq!(
+                loaded.expect("load long interval").update_interval_minutes,
+                minutes
+            );
+        }
+    }
+}

codex-rs/app-server-daemon/src/thread_recovery.rs

@@ -0,0 +1,16 @@
+//! Removes stale snapshots before planned daemon replacements.
+
+use std::io::ErrorKind;
+
+use anyhow::Context;
+use anyhow::Result;
+
+use crate::Daemon;
+
+pub(crate) fn discard_pending(daemon: &Daemon) -> Result<()> {
+    match std::fs::remove_file(daemon.recovery_file()?) {
+        Ok(()) => Ok(()),
+        Err(err) if err.kind() == ErrorKind::NotFound => Ok(()),
+        Err(err) => Err(err).context("failed to clear daemon recovery file"),
+    }
+}

codex-rs/app-server-daemon/src/update_loop.rs

@@ -0,0 +1,710 @@
+//! Owns scheduled and manual installs, daemon restarts, and updater replacement.
+
+use std::path::Path;
+#[cfg(unix)]
+use std::process::Command as StdCommand;
+use std::process::Stdio;
+use std::time::Duration;
+
+use anyhow::Context;
+use anyhow::Result;
+use codex_http_client::ClientRouteClass;
+use codex_http_client::HttpClientFactory;
+use codex_http_client::RouteAwareClientPool;
+use futures::FutureExt;
+#[cfg(unix)]
+use std::os::unix::process::CommandExt;
+use tokio::io::AsyncWriteExt;
+use tokio::process::Command;
+#[cfg(unix)]
+use tokio::signal::unix::Signal;
+#[cfg(unix)]
+use tokio::signal::unix::SignalKind;
+#[cfg(unix)]
+use tokio::signal::unix::signal;
+use tokio::time::Instant;
+use tokio::time::sleep;
+use tokio::time::sleep_until;
+
+use crate::Daemon;
+use crate::RestartIfRunningOutcome;
+use crate::RestartMode;
+use crate::managed_install::ExecutableIdentity;
+use crate::managed_install::executable_identity;
+use crate::managed_install::resolved_managed_codex_bin;
+#[cfg(any(target_os = "linux", target_os = "macos", windows))]
+use crate::settings::DaemonSettings;
+use crate::settings::UpdaterSettings;
+
+#[path = "manual_update.rs"]
+mod manual_update;
+#[path = "migration.rs"]
+mod migration;
+
+pub(crate) async fn request_manual_update(
+    daemon: &Daemon,
+    http_client_factory: HttpClientFactory,
+) -> Result<crate::UpdateOutput> {
+    if daemon
+        .pid_file
+        .file_name()
+        .is_some_and(|name| name == crate::LEGACY_PID_FILE_NAME)
+        && manual_update::supported(daemon)?
+    {
+        let http = RouteAwareClientPool::new_without_request_logging(
+            http_client_factory,
+            ClientRouteClass::Other,
+        );
+        return migration::run(&http, daemon).await;
+    }
+    manual_update::request(daemon).await
+}
+
+const INITIAL_UPDATE_DELAY: Duration = Duration::from_secs(5 * 60);
+const RESTART_RETRY_INTERVAL: Duration = Duration::from_millis(50);
+#[cfg(unix)]
+const INSTALL_URL: &str = "https://chatgpt.com/codex/install.sh";
+#[cfg(windows)]
+const INSTALL_URL: &str = "https://chatgpt.com/codex/install.ps1";
+
+pub(crate) async fn run(
+    http_client_factory: HttpClientFactory,
+    restore_release: Option<String>,
+) -> Result<()> {
+    let http = RouteAwareClientPool::new_without_request_logging(
+        http_client_factory,
+        ClientRouteClass::Other,
+    );
+    run_with_http(
+        &http,
+        &Daemon::from_environment()?,
+        &current_updater_identity().await?,
+        restore_release,
+    )
+    .await
+}
+
+async fn run_with_http(
+    http: &impl InstallerHttp,
+    daemon: &Daemon,
+    running_updater_identity: &ExecutableIdentity,
+    mut restore_release: Option<String>,
+) -> Result<()> {
+    #[cfg(unix)]
+    let mut terminate =
+        signal(SignalKind::terminate()).context("failed to install updater shutdown handler")?;
+    #[cfg(any(target_os = "linux", target_os = "macos"))]
+    {
+        let paths = daemon.backend_paths(&DaemonSettings::default());
+        for backend in [
+            crate::backend::pid_backend(paths.clone()),
+            crate::backend::pid_update_loop_backend(paths),
+        ] {
+            // Inspection failures must preserve legacy records without blocking updates.
+            let _ = backend.promote_legacy_identity().await;
+        }
+    }
+    #[cfg(windows)]
+    let updater = {
+        // Updater ownership needs only paths, not settings that may be mid-edit.
+        crate::backend::pid_update_loop_backend(daemon.backend_paths(&DaemonSettings::default()))
+    };
+    #[cfg(windows)]
+    updater.wait_for_ownership().await?;
+    #[cfg(windows)]
+    let mut terminate = Signal;
+    #[cfg(windows)]
+    let _installer_job = crate::backend::windows::updater_job()?;
+    let socket_path = daemon.manual_update_socket_path();
+    codex_uds::prepare_private_socket_directory(
+        socket_path
+            .parent()
+            .context("updater socket has no parent")?,
+    )
+    .await?;
+    if socket_path.exists() {
+        tokio::fs::remove_file(&socket_path).await?;
+    }
+    let mut listener = Some(codex_uds::UnixListener::bind(&socket_path).await?);
+    #[cfg(windows)]
+    updater.mark_ready().await?;
+    let needs_managed_handoff =
+        match resolved_managed_codex_bin(&daemon.current_managed_codex_bin()?).await {
+            Ok(managed_bin) => {
+                executable_identity(&managed_bin).await.ok().as_ref()
+                    != Some(running_updater_identity)
+            }
+            Err(_) => true,
+        };
+    let auto_update_enabled = UpdaterSettings::load(&daemon.settings_file)
+        .await
+        .map(|settings| settings.auto_update_enabled)
+        .unwrap_or(true);
+    let mut next_check = Instant::now()
+        + if restore_release.is_some() || needs_managed_handoff || !auto_update_enabled {
+            Duration::from_secs(15)
+        } else {
+            INITIAL_UPDATE_DELAY
+        };
+    let mut manual_handoff_pending = needs_managed_handoff;
+    loop {
+        tokio::select! {
+            biased;
+            _ = terminate.recv() => return Ok(()),
+            connection = listener.as_mut().context("updater listener closed")?.accept() => {
+                let connection = connection.context("failed to accept updater request")?;
+                // Only a manual CLI launch under the operation lock supplies this
+                // single-use authority. Ordinary socket requests cannot undo a pin.
+                let restoration = restore_release.take();
+                let trigger = restoration.as_deref().map_or(UpdateTrigger::Manual, UpdateTrigger::RestoreProduction);
+                let disposition = match manual_update::handle_request(connection, http, daemon, running_updater_identity, &mut terminate, trigger).await {
+                    Ok(manual_update::RequestDisposition::Stop) => return Ok(()),
+                    Ok(disposition) => disposition,
+                    Err(_) => manual_update::RequestDisposition::Continue,
+                };
+                if UpdaterSettings::load(&daemon.settings_file)
+                    .await
+                    .is_ok_and(|settings| !settings.auto_update_enabled)
+                {
+                    // Drain requests queued during this one-shot update before exiting.
+                    next_check = Instant::now() + Duration::from_millis(100);
+                    continue;
+                }
+                if matches!(disposition, manual_update::RequestDisposition::Unchanged) {
+                    continue;
+                }
+                manual_handoff_pending = true;
+                next_check = Instant::now();
+            }
+            _ = sleep_until(next_check) => {
+                // The authorizing CLI may have exited before sending its request.
+                if restore_release.is_some() {
+                    return Ok(());
+                }
+                match UpdaterSettings::load(&daemon.settings_file).await {
+                    Ok(settings) if !settings.auto_update_enabled => return Ok(()),
+                    Err(_) => {
+                        next_check = Instant::now() + Duration::from_secs(60);
+                        continue;
+                    }
+                    Ok(_) => {}
+                }
+                // Failed successor cleanup leaves its PID published. The predecessor
+                // must stop instead of installing again without ownership.
+                #[cfg(windows)]
+                updater.wait_for_ownership().await?;
+                if manual_handoff_pending {
+                    if !daemon.is_stable_standalone_release()? {
+                        if !daemon.has_latest_selection_marker() {
+                            return Ok(());
+                        }
+                        next_check = Instant::now() + Duration::from_secs(30);
+                        continue;
+                    }
+                    match adopt_managed_updater(daemon, running_updater_identity, &mut listener).await {
+                        Ok(UpdateLoopControl::Stop) => return Ok(()),
+                        Ok(UpdateLoopControl::Continue) => {
+                            manual_handoff_pending = false;
+                            let Some(delay) = next_update_delay(daemon).await else {
+                                return Ok(());
+                            };
+                            next_check = Instant::now() + delay;
+                        }
+                        Err(err) => {
+                            if listener.is_none() {
+                                return Err(err);
+                            }
+                            eprintln!("warning: failed to refresh managed updater: {err:#}");
+                            next_check = Instant::now() + Duration::from_secs(30);
+                        }
+                    }
+                    continue;
+                }
+                match update_once(http, daemon, running_updater_identity, &mut terminate, UpdateTrigger::Scheduled).await {
+                    Ok((UpdateLoopControl::Continue, Some(_))) => {
+                        manual_handoff_pending = true;
+                        next_check = Instant::now();
+                        continue;
+                    }
+                    Ok((UpdateLoopControl::Continue, None)) | Err(_) => {}
+                    Ok((UpdateLoopControl::Stop, _)) => return Ok(()),
+                }
+                let Some(delay) = next_update_delay(daemon).await else {
+                    return Ok(());
+                };
+                next_check = Instant::now() + delay;
+            }
+        }
+    }
+}
+
+async fn next_update_delay(daemon: &Daemon) -> Option<Duration> {
+    match UpdaterSettings::load(&daemon.settings_file).await {
+        Ok(settings) if !settings.auto_update_enabled => None,
+        Ok(settings) => Some(settings.update_interval(Duration::from_secs(60))),
+        Err(_) => Some(Duration::from_secs(60)),
+    }
+}
+
+async fn adopt_managed_updater(
+    daemon: &Daemon,
+    running_identity: &ExecutableIdentity,
+    listener: &mut Option<codex_uds::UnixListener>,
+) -> Result<UpdateLoopControl> {
+    let managed_bin = resolved_managed_codex_bin(&daemon.current_managed_codex_bin()?).await?;
+    if executable_identity(&managed_bin).await? == *running_identity {
+        return Ok(UpdateLoopControl::Continue);
+    }
+    if !crate::managed_install::supports_daemon_update_loop(&managed_bin).await {
+        return Ok(UpdateLoopControl::Stop);
+    }
+    #[cfg(unix)]
+    {
+        let _ = listener;
+        reexec_managed_updater(&managed_bin).map(|_| UpdateLoopControl::Stop)
+    }
+    #[cfg(windows)]
+    {
+        let replacement = crate::backend::pid_update_loop_backend(
+            daemon.backend_paths_with_bin(&daemon.load_settings().await?, &managed_bin),
+        );
+        listener.take();
+        if let Err(err) = replacement.replace_current_updater().await {
+            // A failed replacement may still own the PID if its cleanup could
+            // not terminate the successor. Never reopen our request socket then.
+            replacement.wait_for_ownership().await?;
+            let socket_path = daemon.manual_update_socket_path();
+            if socket_path.exists() {
+                tokio::fs::remove_file(&socket_path).await?;
+            }
+            *listener = Some(codex_uds::UnixListener::bind(&socket_path).await?);
+            return Err(err);
+        }
+        Ok(UpdateLoopControl::Stop)
+    }
+}
+
+async fn sleep_or_terminate(duration: Duration, terminate: &mut Signal) -> bool {
+    tokio::select! {
+        _ = sleep(duration) => false,
+        _ = terminate.recv() => true,
+    }
+}
+
+enum UpdateLoopControl {
+    Continue,
+    Stop,
+}
+
+#[derive(Clone, Copy, PartialEq, Eq)]
+enum UpdateTrigger<'a> {
+    Scheduled,
+    Manual,
+    RestoreProduction(&'a str),
+}
+
+async fn update_once(
+    http: &impl InstallerHttp,
+    daemon: &Daemon,
+    running_updater_identity: &ExecutableIdentity,
+    terminate: &mut Signal,
+    trigger: UpdateTrigger<'_>,
+) -> Result<(UpdateLoopControl, Option<RestartIfRunningOutcome>)> {
+    if trigger == UpdateTrigger::Scheduled
+        && !UpdaterSettings::load(&daemon.settings_file)
+            .await?
+            .auto_update_enabled
+    {
+        return Ok((UpdateLoopControl::Stop, None));
+    }
+    if release_selection_unstable(daemon, trigger)? {
+        // An installer can be between changing current and publishing its
+        // latest-channel marker. Retry after the interval instead of exiting.
+        return Ok((UpdateLoopControl::Continue, None));
+    }
+    let (package_root, previous_selection, previous_release) = selected_release(daemon)?;
+    let codex_home = package_root
+        .parent()
+        .and_then(Path::parent)
+        .context("daemon package root has no Codex home")?;
+    let (installer_mode, installer_guard) =
+        if let UpdateTrigger::RestoreProduction(expected) = trigger {
+            anyhow::ensure!(
+                previous_release == expected,
+                "daemon selection changed; retry the update"
+            );
+            (
+                InstallerMode::RestoreProduction(&previous_release),
+                "CODEX_INSTALL_IF_CURRENT",
+            )
+        } else {
+            (
+                InstallerMode::Update(&previous_release),
+                "CODEX_INSTALL_IF_LATEST",
+            )
+        };
+    let script = tokio::select! {
+        result = fetch_installer_script(http) => result?,
+        _ = terminate.recv() => return Ok((UpdateLoopControl::Stop, None)),
+    };
+    anyhow::ensure!(
+        script
+            .windows(installer_guard.len())
+            .any(|window| window == installer_guard.as_bytes()),
+        "standalone installer does not support {installer_guard} guarded updates"
+    );
+    if package_root.ends_with("app-server-daemon") {
+        anyhow::ensure!(
+            script
+                .windows(b"CODEX_INSTALL_DAEMON_ONLY".len())
+                .any(|window| window == b"CODEX_INSTALL_DAEMON_ONLY"),
+            "installer does not support daemon-owned packages"
+        );
+    }
+    if trigger == UpdateTrigger::Scheduled
+        && !UpdaterSettings::load(&daemon.settings_file)
+            .await?
+            .auto_update_enabled
+    {
+        return Ok((UpdateLoopControl::Stop, None));
+    }
+    if release_selection_unstable(daemon, trigger)? {
+        return Ok((UpdateLoopControl::Continue, None));
+    }
+    anyhow::ensure!(
+        crate::managed_install::package_root(codex_home) == package_root,
+        "daemon package root changed during the update; retry the command"
+    );
+    #[cfg(unix)]
+    if matches!(
+        run_installer_script(&script, installer_mode, &package_root, terminate.recv()).await?,
+        UpdateLoopControl::Stop
+    ) {
+        return Ok((UpdateLoopControl::Stop, None));
+    }
+    #[cfg(windows)]
+    tokio::select! {
+        result = run_installer_script(&script, installer_mode, &package_root) => { result?; },
+        _ = terminate.recv() => return Ok((UpdateLoopControl::Stop, None)),
+    }
+    anyhow::ensure!(
+        trigger == UpdateTrigger::Scheduled || daemon.is_stable_standalone_release()?,
+        "installer did not select a stable latest release; retry the update"
+    );
+    if release_selection_unstable(daemon, trigger)? {
+        return Ok((UpdateLoopControl::Continue, None));
+    }
+
+    let managed_codex_bin =
+        resolved_managed_codex_bin(&daemon.current_managed_codex_bin()?).await?;
+    let restart_mode = match trigger {
+        // The package can contain different resources even when its CLI binary
+        // is identical. A release change must also replace the running process.
+        UpdateTrigger::Manual | UpdateTrigger::RestoreProduction(_)
+            if selected_release(daemon)?.1 != previous_selection =>
+        {
+            RestartMode::Always
+        }
+        UpdateTrigger::Manual | UpdateTrigger::RestoreProduction(_) => {
+            RestartMode::IfBinaryOrVersionChanged
+        }
+        UpdateTrigger::Scheduled
+            if executable_identity(&managed_codex_bin).await? != *running_updater_identity =>
+        {
+            RestartMode::Always
+        }
+        UpdateTrigger::Scheduled => RestartMode::IfVersionChanged,
+    };
+
+    loop {
+        if terminate.recv().now_or_never().flatten().is_some() {
+            return Ok((UpdateLoopControl::Stop, None));
+        }
+        match daemon
+            .try_restart_if_running(restart_mode, &managed_codex_bin)
+            .await?
+        {
+            RestartIfRunningOutcome::Busy => {
+                if sleep_or_terminate(RESTART_RETRY_INTERVAL, terminate).await {
+                    return Ok((UpdateLoopControl::Stop, None));
+                }
+            }
+            RestartIfRunningOutcome::Restarted => {
+                return Ok((
+                    UpdateLoopControl::Continue,
+                    Some(RestartIfRunningOutcome::Restarted),
+                ));
+            }
+            RestartIfRunningOutcome::NotRunning => {
+                return Ok((
+                    UpdateLoopControl::Continue,
+                    Some(RestartIfRunningOutcome::NotRunning),
+                ));
+            }
+            RestartIfRunningOutcome::AlreadyCurrent
+                if trigger != UpdateTrigger::Scheduled
+                    && restart_mode == RestartMode::IfBinaryOrVersionChanged =>
+            {
+                anyhow::ensure!(
+                    daemon.is_stable_standalone_release()?
+                        && resolved_managed_codex_bin(&daemon.current_managed_codex_bin()?).await?
+                            == managed_codex_bin,
+                    "managed daemon changed during the update; retry"
+                );
+                return Ok((
+                    UpdateLoopControl::Continue,
+                    Some(RestartIfRunningOutcome::AlreadyCurrent),
+                ));
+            }
+            RestartIfRunningOutcome::NotReady | RestartIfRunningOutcome::AlreadyCurrent => {
+                anyhow::ensure!(
+                    trigger == UpdateTrigger::Scheduled,
+                    "managed daemon could not restart; retry when it is ready"
+                );
+                return Ok((
+                    if daemon.is_stable_standalone_release()? {
+                        UpdateLoopControl::Continue
+                    } else {
+                        UpdateLoopControl::Stop
+                    },
+                    None,
+                ));
+            }
+        }
+    }
+}
+
+fn release_selection_unstable(daemon: &Daemon, trigger: UpdateTrigger<'_>) -> Result<bool> {
+    if daemon.is_stable_standalone_release()?
+        || matches!(trigger, UpdateTrigger::RestoreProduction(_))
+            && manual_update::supported(daemon)?
+    {
+        return Ok(false);
+    }
+    anyhow::ensure!(
+        trigger == UpdateTrigger::Scheduled,
+        "standalone install selection changed during the update"
+    );
+    Ok(true)
+}
+
+fn selected_release(daemon: &Daemon) -> Result<(std::path::PathBuf, std::path::PathBuf, String)> {
+    let home = daemon
+        .settings_file
+        .parent()
+        .and_then(Path::parent)
+        .context("daemon settings path has no Codex home")?;
+    let root = crate::managed_install::package_root(home);
+    let release = std::fs::canonicalize(root.join("current"))?;
+    let name = release
+        .file_name()
+        .context("managed release has no name")?
+        .to_string_lossy()
+        .into_owned();
+    Ok((root, release, name))
+}
+
+async fn current_updater_identity() -> Result<ExecutableIdentity> {
+    let current_exe =
+        std::env::current_exe().context("failed to resolve current updater executable")?;
+    executable_identity(&current_exe).await
+}
+
+#[cfg(unix)]
+pub(crate) fn reexec_managed_updater(managed_codex_bin: &std::path::Path) -> Result<()> {
+    let err = StdCommand::new(managed_codex_bin)
+        .args(["app-server", "daemon", "pid-update-loop"])
+        .exec();
+    Err(err).with_context(|| {
+        format!(
+            "failed to replace updater with managed Codex binary {}",
+            managed_codex_bin.display()
+        )
+    })
+}
+
+enum InstallerMode<'a> {
+    Update(&'a str),
+    RestoreProduction(&'a str),
+    Migration,
+}
+
+async fn run_installer_script(
+    script: &[u8],
+    mode: InstallerMode<'_>,
+    package_root: &Path,
+    #[cfg(unix)] terminate: impl std::future::Future<Output = Option<()>>,
+) -> Result<UpdateLoopControl> {
+    #[cfg(unix)]
+    let mut command = {
+        let mut command = Command::new("/bin/sh");
+        command.arg("-s");
+        command.process_group(0);
+        command
+    };
+    #[cfg(windows)]
+    let mut command = {
+        let mut command = Command::new("powershell.exe");
+        command.creation_flags(windows_sys::Win32::System::Threading::CREATE_NO_WINDOW);
+        command.args(["-NoLogo", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", "try { Invoke-Expression ([Console]::In.ReadToEnd()) } catch { Write-Error $_; exit 1 }"])
+            .kill_on_drop(true);
+        command
+    };
+    let (latest_guard, current_guard, previous_release, defer_selection) = match mode {
+        InstallerMode::Update(release) => ("1", "0", release, "0"),
+        InstallerMode::RestoreProduction(release) => ("0", "1", release, "0"),
+        InstallerMode::Migration => ("0", "0", "", "1"),
+    };
+    let mut child = command
+        .env(
+            "CODEX_HOME",
+            package_root
+                .parent()
+                .and_then(Path::parent)
+                .context("package root has no Codex home")?,
+        )
+        .env("CODEX_INSTALL_DEFER_SELECTION", defer_selection)
+        .env(
+            "CODEX_INSTALL_DAEMON_ONLY",
+            if package_root.ends_with("app-server-daemon") {
+                "1"
+            } else {
+                "0"
+            },
+        )
+        .env("CODEX_RELEASE", "latest")
+        .env("CODEX_NON_INTERACTIVE", "1")
+        .env("CODEX_INSTALL_IF_LATEST", latest_guard)
+        .env("CODEX_INSTALL_IF_CURRENT", current_guard)
+        .env("CODEX_UPDATE_FROM_RELEASE", previous_release)
+        .kill_on_drop(true)
+        .stdin(Stdio::piped())
+        .stdout(Stdio::null())
+        .stderr(Stdio::null())
+        .spawn()
+        .context("failed to invoke standalone Codex updater")?;
+    #[cfg(windows)]
+    let _installer_job = crate::backend::windows::installer_job(&child)?;
+    let mut stdin = child
+        .stdin
+        .take()
+        .context("standalone Codex updater stdin was unavailable")?;
+    #[cfg(unix)]
+    let mut terminate = std::pin::pin!(terminate);
+    #[cfg(unix)]
+    let write_result = tokio::select! {
+        result = stdin.write_all(script) => Some(result),
+        _ = &mut terminate => None,
+    };
+    #[cfg(windows)]
+    let write_result = Some(stdin.write_all(script).await);
+    drop(stdin);
+    #[cfg(unix)]
+    if write_result.is_none() {
+        cancel_installer(&mut child, package_root).await;
+        return Ok(UpdateLoopControl::Stop);
+    }
+    write_result
+        .context("installer write was cancelled")?
+        .context("failed to pass standalone Codex updater to shell")?;
+    #[cfg(unix)]
+    let status = tokio::select! {
+        result = child.wait() => result,
+        _ = &mut terminate => {
+            cancel_installer(&mut child, package_root).await;
+            return Ok(UpdateLoopControl::Stop);
+        }
+    };
+    #[cfg(windows)]
+    let status = child.wait().await;
+    let status = status.context("failed to wait for standalone Codex updater")?;
+
+    if status.success() {
+        Ok(UpdateLoopControl::Continue)
+    } else {
+        anyhow::bail!("standalone Codex updater exited with status {status}")
+    }
+}
+
+#[cfg(unix)]
+async fn cancel_installer(child: &mut tokio::process::Child, package_root: &Path) {
+    let Some(pid) = child.id().and_then(|pid| libc::pid_t::try_from(pid).ok()) else {
+        return;
+    };
+    // Let the shell's EXIT/TERM trap release the installer lock first.
+    unsafe { libc::kill(-pid, libc::SIGTERM) };
+    sleep(Duration::from_secs(2)).await;
+    // Keep the shell unreaped until after the group kill, so its PID cannot
+    // be reused while descendants that ignored TERM are still running.
+    unsafe { libc::kill(-pid, libc::SIGKILL) };
+    // A forced kill can bypass the shell trap on hosts using the mkdir lock.
+    // The lock is ours only if its recorded owner is this still-unreaped shell.
+    let lock = package_root.join("install.lock.d");
+    if std::fs::read_to_string(lock.join("pid")).is_ok_and(|owner| owner.trim() == pid.to_string())
+    {
+        let _ = std::fs::remove_dir_all(lock);
+    }
+    let _ = child.wait().await;
+}
+
+async fn fetch_installer_script(http: &impl InstallerHttp) -> Result<Vec<u8>> {
+    match http.get(INSTALL_URL).await? {
+        InstallerResponse::Success(body) => Ok(body),
+        InstallerResponse::Unsuccessful { status } => {
+            anyhow::bail!("standalone Codex updater request failed with status {status}")
+        }
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+enum InstallerResponse {
+    Success(Vec<u8>),
+    Unsuccessful { status: u16 },
+}
+
+/// HTTP boundary used to download the standalone installer.
+///
+/// Implementations must issue a GET for the supplied URL, return exact response bytes for a
+/// successful status, and report a non-success status without buffering its response body.
+trait InstallerHttp: Send + Sync {
+    fn get<'a>(
+        &'a self,
+        url: &'a str,
+    ) -> impl std::future::Future<Output = Result<InstallerResponse>> + Send + 'a;
+}
+
+impl InstallerHttp for RouteAwareClientPool {
+    async fn get(&self, url: &str) -> Result<InstallerResponse> {
+        let response = RouteAwareClientPool::get(self, url)
+            .send()
+            .await
+            .context("failed to fetch standalone Codex updater")?;
+        if !response.status().is_success() {
+            return Ok(InstallerResponse::Unsuccessful {
+                status: response.status().as_u16(),
+            });
+        }
+        let body = response
+            .bytes()
+            .await
+            .context("failed to read standalone Codex updater")?
+            .to_vec();
+        Ok(InstallerResponse::Success(body))
+    }
+}
+
+#[cfg(test)]
+#[path = "update_loop_tests.rs"]
+mod tests;
+
+#[cfg(windows)]
+struct Signal;
+
+#[cfg(windows)]
+impl Signal {
+    async fn recv(&mut self) -> Option<()> {
+        // An unreadable control path must stop the updater rather than disable shutdown.
+        let _ = codex_app_server_transport::daemon_shutdown_signal().await;
+        Some(())
+    }
+}

codex-rs/app-server-daemon/src/update_loop_tests.rs

@@ -0,0 +1,891 @@
+use std::sync::Mutex;
+#[cfg(unix)]
+use std::time::Duration;
+
+use pretty_assertions::assert_eq;
+#[cfg(unix)]
+use tempfile::TempDir;
+
+use super::INSTALL_URL;
+use super::InstallerHttp;
+use super::InstallerResponse;
+use super::fetch_installer_script;
+#[cfg(unix)]
+use super::manual_update::run as manual_update_once;
+#[cfg(unix)]
+use crate::Daemon;
+#[cfg(unix)]
+use crate::UpdateOutput;
+#[cfg(unix)]
+use crate::UpdateStatus;
+#[cfg(unix)]
+use crate::managed_install::executable_identity;
+#[cfg(unix)]
+use crate::managed_install::executable_identity_from_bytes;
+
+#[tokio::test]
+async fn installer_fetch_uses_exact_url_and_preserves_bytes() {
+    let script = b"#!/bin/sh\nprintf 'update bytes'\n".to_vec();
+    let http = FakeInstallerHttp::new(InstallerResponse::Success(script.clone()));
+
+    assert_eq!(
+        fetch_installer_script(&http)
+            .await
+            .expect("installer fetch should succeed"),
+        script
+    );
+    assert_eq!(http.requested_urls(), vec![INSTALL_URL.to_string()]);
+}
+
+#[tokio::test]
+async fn installer_fetch_rejects_non_success_status() {
+    let http = FakeInstallerHttp::new(InstallerResponse::Unsuccessful { status: 503 });
+
+    let error = fetch_installer_script(&http)
+        .await
+        .expect_err("non-success response should fail");
+
+    assert!(error.to_string().contains("503"));
+    assert_eq!(http.requested_urls(), vec![INSTALL_URL.to_string()]);
+}
+
+struct FakeInstallerHttp {
+    response: InstallerResponse,
+    requested_urls: Mutex<Vec<String>>,
+}
+
+#[cfg(unix)]
+#[tokio::test]
+async fn explicit_update_migrates_running_and_stopped_installations() {
+    for (running, local) in [(false, false), (true, false), (false, true), (true, true)] {
+        let home = TempDir::new().unwrap();
+        let (legacy, release) = manual_update_daemon(&home);
+        let root = home.path().join("packages/standalone");
+        if local {
+            let package = root.join("releases/local-development");
+            std::fs::create_dir(&package).unwrap();
+            std::fs::copy(&legacy.managed_codex_bin, package.join("codex")).unwrap();
+            std::fs::remove_file(root.join("current")).unwrap();
+            std::os::unix::fs::symlink(&package, root.join("current")).unwrap();
+            std::fs::remove_file(root.join("auto-update-version")).unwrap();
+        }
+        let previous = root.join("current").canonicalize().unwrap();
+        let scheduled = FakeInstallerHttp::new(InstallerResponse::Success(
+        b"# CODEX_INSTALL_IF_LATEST\ntest \"$CODEX_INSTALL_DEFER_SELECTION\" = 0 && test \"$CODEX_INSTALL_DAEMON_ONLY\" = 0\n".to_vec(),
+    ));
+        super::update_once(
+            &scheduled,
+            &legacy,
+            &executable_identity(&legacy.managed_codex_bin)
+                .await
+                .unwrap(),
+            &mut test_terminate(),
+            super::UpdateTrigger::Scheduled,
+        )
+        .await
+        .unwrap();
+        assert_eq!(
+            scheduled.requested_urls(),
+            if local {
+                vec![]
+            } else {
+                vec![INSTALL_URL.to_string()]
+            }
+        );
+        assert_eq!(
+            crate::managed_install::package_root(home.path()),
+            home.path().join("packages/standalone")
+        );
+        let settings = format!(
+            r#"{{"updater":{{"autoUpdateEnabled":{running}}},"remoteControlEnabled":true}}"#
+        );
+        std::fs::write(&legacy.settings_file, &settings).unwrap();
+        let daemon_settings = legacy.load_settings().await.unwrap();
+        let old_backend = crate::backend::pid_backend(legacy.backend_paths(&daemon_settings));
+        let old_updater =
+            crate::backend::pid_update_loop_backend(legacy.backend_paths(&daemon_settings));
+        let server = if running {
+            old_backend.start().await.unwrap();
+            old_updater.start().await.unwrap();
+            Some(test_control_server(&legacy, home.path()).await)
+        } else {
+            None
+        };
+        let legacy_bin = std::fs::read(&legacy.managed_codex_bin).unwrap();
+        let dedicated = home.path().join("packages/app-server-daemon");
+        let old_installer = FakeInstallerHttp::new(InstallerResponse::Success(b"exit 99".to_vec()));
+        assert!(
+            super::migration::run(&old_installer, &legacy)
+                .await
+                .unwrap_err()
+                .to_string()
+                .contains("does not support daemon migration")
+        );
+
+        let script = format!(
+            r#"# CODEX_INSTALL_DEFER_SELECTION
+set -eu
+test "$CODEX_INSTALL_DEFER_SELECTION" = 1
+test "$CODEX_INSTALL_IF_CURRENT" = 0
+test "$CODEX_INSTALL_DAEMON_ONLY" = 1
+test "$CODEX_INSTALL_IF_LATEST" = 0
+root="$CODEX_HOME/packages/app-server-daemon"
+mkdir -p "$root/releases/{release}/bin"
+printf '#!/bin/sh\nif [ "$1" = --version ]; then echo codex 1.0.0; else exit 2; fi\n' > "$root/releases/{release}/bin/codex"
+chmod +x "$root/releases/{release}/bin/codex"
+ln -sfn 'releases/{release}' "$root/.migration-current"
+printf '{release}' > "$root/auto-update-version"
+"#
+        );
+        let http = FakeInstallerHttp::new(InstallerResponse::Success(script.as_bytes().to_vec()));
+        let error = super::migration::run(&http, &legacy).await.unwrap_err();
+        assert!(
+            error
+                .to_string()
+                .contains("production release does not support daemon migration")
+        );
+        assert!(!dedicated.join("current").exists());
+        assert_eq!(
+            crate::managed_install::package_root(home.path()),
+            home.path().join("packages/standalone")
+        );
+        assert_eq!(
+            (
+                old_backend.is_starting_or_running().await.unwrap(),
+                old_updater.is_starting_or_running().await.unwrap()
+            ),
+            (running, running)
+        );
+        let compatible = FakeInstallerHttp::new(InstallerResponse::Success(script.replace("else exit 2", "elif [ \"$4\" = --check-package-ownership ] || [ \"$4\" = --help ]; then exit 0; else exec sleep 30").into_bytes()));
+        let output = super::migration::run(&compatible, &legacy).await.unwrap();
+        assert_eq!(output, UpdateOutput {
+        status: UpdateStatus::Updated,
+        installed_version: Some("1.0.0".to_string()),
+        running_version: (running).then(|| "1.0.0".to_string()),
+        managed_codex_path: dedicated.join("current/bin/codex"),
+        message: "The daemon was updated and moved to its dedicated package. The legacy CLI package was left unchanged.".to_string(),
+    });
+        assert_eq!(
+            crate::managed_install::package_root(home.path()),
+            dedicated.clone()
+        );
+        assert!(!dedicated.join(".migration-current").exists());
+        assert_eq!(root.join("current").canonicalize().unwrap(), previous);
+        assert_eq!(
+            std::fs::read(&legacy.managed_codex_bin).unwrap(),
+            legacy_bin
+        );
+        assert_eq!(
+            std::fs::read_to_string(&legacy.settings_file).unwrap(),
+            settings
+        );
+        let selected = Daemon {
+            pid_file: legacy.pid_file.with_file_name(crate::DAEMON_PID_FILE_NAME),
+            update_pid_file: legacy
+                .update_pid_file
+                .with_file_name(crate::DAEMON_UPDATE_PID_FILE_NAME),
+            managed_codex_bin: dedicated.join("current/bin/codex"),
+            ..legacy.clone()
+        };
+        let new_backend = crate::backend::pid_backend(selected.backend_paths(&daemon_settings));
+        assert_eq!(new_backend.is_starting_or_running().await.unwrap(), running);
+        assert!(!old_backend.is_starting_or_running().await.unwrap());
+        assert!(!old_updater.is_starting_or_running().await.unwrap());
+        let new_updater =
+            crate::backend::pid_update_loop_backend(selected.backend_paths(&daemon_settings));
+        assert_eq!(new_updater.is_starting_or_running().await.unwrap(), running);
+        new_updater.stop().await.unwrap();
+        new_backend.stop().await.unwrap();
+        if let Some(server) = server {
+            server.abort();
+        }
+    }
+}
+
+impl FakeInstallerHttp {
+    fn new(response: InstallerResponse) -> Self {
+        Self {
+            response,
+            requested_urls: Mutex::new(Vec::new()),
+        }
+    }
+
+    fn requested_urls(&self) -> Vec<String> {
+        self.requested_urls
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .clone()
+    }
+}
+
+impl InstallerHttp for FakeInstallerHttp {
+    async fn get(&self, url: &str) -> anyhow::Result<InstallerResponse> {
+        self.requested_urls
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .push(url.to_string());
+        Ok(self.response.clone())
+    }
+}
+
+#[cfg(unix)]
+#[tokio::test]
+async fn cancelling_installer_stops_children_and_releases_fallback_lock() {
+    let home = tempfile::TempDir::new().expect("home");
+    let ready = home.path().join("ready");
+    let delayed = home.path().join("delayed");
+    let lock = home.path().join("packages/standalone/install.lock.d");
+    let script = format!(
+        "mkdir -p '{lock}'\necho $$ > '{lock}/pid'\n(trap '' TERM; echo ready > '{ready}'; sleep 4; echo late > '{delayed}') &\nwait\n",
+        lock = lock.display(),
+        ready = ready.display(),
+        delayed = delayed.display(),
+    );
+    let (cancel, cancelled) = tokio::sync::oneshot::channel();
+    let ready_for_signal = ready.clone();
+    let signal_sender = tokio::spawn(async move {
+        let deadline = tokio::time::Instant::now() + Duration::from_secs(5);
+        while !ready_for_signal.exists() {
+            assert!(
+                tokio::time::Instant::now() < deadline,
+                "installer did not start"
+            );
+            tokio::time::sleep(Duration::from_millis(20)).await;
+        }
+        cancel.send(()).expect("cancel installer");
+    });
+    let result = tokio::time::timeout(
+        Duration::from_secs(10),
+        super::run_installer_script(
+            script.as_bytes(),
+            super::InstallerMode::Update("0.150.0-test"),
+            &home.path().join("packages/standalone"),
+            async { cancelled.await.ok() },
+        ),
+    )
+    .await
+    .expect("installer cancellation timed out")
+    .expect("installer cancellation failed");
+    signal_sender.await.expect("signal sender");
+    assert!(matches!(result, super::UpdateLoopControl::Stop));
+    assert!(!lock.exists());
+    tokio::time::sleep(Duration::from_secs(3)).await;
+    assert!(!delayed.exists());
+}
+
+#[cfg(unix)]
+fn manual_update_daemon(home: &TempDir) -> (Daemon, String) {
+    use std::os::unix::fs::PermissionsExt;
+
+    let target = if cfg!(target_os = "macos") {
+        format!("{}-apple-darwin", std::env::consts::ARCH)
+    } else {
+        format!("{}-unknown-linux-musl", std::env::consts::ARCH)
+    };
+    let release = format!("1.0.0-{target}");
+    let standalone = home.path().join("packages/standalone");
+    let bin = standalone.join("releases").join(&release).join("codex");
+    std::fs::create_dir_all(bin.parent().expect("binary parent")).expect("release directory");
+    std::fs::write(
+        &bin,
+        b"#!/bin/sh\nif [ \"$1\" = '--version' ]; then echo codex 1.0.0; else exec sleep 30; fi\n",
+    )
+    .expect("managed binary");
+    std::fs::set_permissions(&bin, std::fs::Permissions::from_mode(0o755))
+        .expect("executable binary");
+    std::os::unix::fs::symlink(format!("releases/{release}"), standalone.join("current"))
+        .expect("current release");
+    std::fs::write(standalone.join("auto-update-version"), &release).expect("latest marker");
+    let state = home.path().join("app-server-daemon");
+    std::fs::create_dir(&state).unwrap();
+    std::fs::write(state.join("app-server.stderr.log"), b"").unwrap();
+    (
+        Daemon {
+            socket_path: home.path().join("app-server-control/server.sock"),
+            pid_file: state.join("app-server.pid"),
+            update_pid_file: state.join("app-server-updater.pid"),
+            operation_lock_file: state.join("daemon.lock"),
+            settings_file: state.join("settings.json"),
+            managed_codex_bin: standalone.join("current/codex"),
+        },
+        release,
+    )
+}
+
+#[cfg(unix)]
+fn test_terminate() -> tokio::signal::unix::Signal {
+    tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate())
+        .expect("install test signal handler")
+}
+
+#[cfg(unix)]
+#[tokio::test]
+async fn manual_request_retries_after_updater_replacement() {
+    use tokio::io::AsyncReadExt;
+    use tokio::io::AsyncWriteExt;
+
+    let home = TempDir::new().expect("home");
+    let (daemon, _) = manual_update_daemon(&home);
+    let socket_path = daemon.manual_update_socket_path();
+    codex_uds::prepare_private_socket_directory(socket_path.parent().expect("socket parent"))
+        .await
+        .expect("socket directory");
+    let mut listener = codex_uds::UnixListener::bind(&socket_path)
+        .await
+        .expect("old updater socket");
+    let expected = UpdateOutput {
+        status: UpdateStatus::NoUpdate,
+        managed_codex_path: daemon.managed_codex_bin.clone(),
+        installed_version: None,
+        running_version: None,
+        message: "already current".to_string(),
+    };
+    let reply = expected.clone();
+    let server = tokio::spawn(async move {
+        let mut old = listener.accept().await.expect("first connection");
+        let mut request = [0; 7];
+        old.read_exact(&mut request).await.expect("first request");
+        drop(old);
+        drop(listener);
+        tokio::fs::remove_file(&socket_path)
+            .await
+            .expect("remove old socket");
+        let mut successor = codex_uds::UnixListener::bind(&socket_path)
+            .await
+            .expect("successor socket");
+        let mut connection = successor.accept().await.expect("retried connection");
+        connection
+            .read_exact(&mut request)
+            .await
+            .expect("retried request");
+        connection
+            .write_all(&serde_json::to_vec(&Ok::<_, String>(reply)).expect("serialize response"))
+            .await
+            .expect("send response");
+    });
+    assert_eq!(
+        super::manual_update::request(&daemon)
+            .await
+            .expect("request survives handoff"),
+        expected
+    );
+    server.await.expect("replacement task");
+}
+
+#[cfg(unix)]
+#[tokio::test]
+async fn manual_request_recovers_when_one_shot_updater_exits() {
+    use tokio::io::AsyncReadExt;
+
+    let home = TempDir::new().expect("home");
+    let (daemon, _) = manual_update_daemon(&home);
+    let socket_path = daemon.manual_update_socket_path();
+    codex_uds::prepare_private_socket_directory(socket_path.parent().expect("socket parent"))
+        .await
+        .expect("socket directory");
+    let mut listener = codex_uds::UnixListener::bind(&socket_path)
+        .await
+        .expect("one-shot updater socket");
+    let server = tokio::spawn(async move {
+        let mut connection = listener.accept().await.expect("request connection");
+        let mut request = [0; 7];
+        connection.read_exact(&mut request).await.expect("request");
+        drop(connection);
+        drop(listener);
+        tokio::fs::remove_file(socket_path)
+            .await
+            .expect("remove exited updater socket");
+    });
+    // Without the selected executable, the startup path reports unsupported. A
+    // retry that only waits for a successor would time out instead.
+    std::fs::remove_file(&daemon.managed_codex_bin).expect("remove selected binary");
+    let result = tokio::time::timeout(
+        Duration::from_secs(5),
+        super::manual_update::request(&daemon),
+    )
+    .await
+    .expect("retry should return to normal startup")
+    .expect("unsupported response");
+    assert_eq!(result.status, UpdateStatus::Unsupported);
+    server.await.expect("updater task");
+}
+
+#[cfg(unix)]
+#[tokio::test]
+async fn unsupported_request_preserves_updater_schedule() {
+    use tokio::io::AsyncReadExt;
+    use tokio::io::AsyncWriteExt;
+
+    let home = TempDir::new().expect("home");
+    let (daemon, _) = manual_update_daemon(&home);
+    let daemon = std::sync::Arc::new(daemon);
+    let identity = executable_identity(&daemon.managed_codex_bin)
+        .await
+        .expect("updater identity");
+    let socket_path = daemon.manual_update_socket_path();
+    let http = FakeInstallerHttp::new(InstallerResponse::Success(Vec::new()));
+    let updater_daemon = std::sync::Arc::clone(&daemon);
+    let worker = tokio::spawn(async move {
+        super::run_with_http(
+            &http,
+            &updater_daemon,
+            &identity,
+            /*restore_release*/ None,
+        )
+        .await
+    });
+    let deadline = tokio::time::Instant::now() + Duration::from_secs(5);
+    while !socket_path.exists() {
+        assert!(
+            tokio::time::Instant::now() < deadline,
+            "updater did not listen"
+        );
+        tokio::time::sleep(Duration::from_millis(20)).await;
+    }
+    // An external installer can pin while this ordinary worker still listens.
+    // Raw IPC must not gain the manual CLI's authority to restore production.
+    let marker = super::selected_release(&daemon)
+        .unwrap()
+        .0
+        .join("auto-update-version");
+    let previous_marker = std::fs::read(&marker).unwrap();
+    std::fs::remove_file(&marker).unwrap();
+    let mut pinned = codex_uds::UnixStream::connect(&socket_path).await.unwrap();
+    pinned.write_all(b"update\n").await.unwrap();
+    let mut response = Vec::new();
+    pinned.read_to_end(&mut response).await.unwrap();
+    let response: Result<UpdateOutput, String> = serde_json::from_slice(&response).unwrap();
+    assert_eq!(response.unwrap().status, UpdateStatus::Unsupported);
+    assert!(!marker.exists());
+    std::fs::write(&marker, previous_marker).unwrap();
+    std::fs::remove_file(&daemon.managed_codex_bin).expect("remove selected binary");
+    let mut malformed = codex_uds::UnixStream::connect(&socket_path)
+        .await
+        .expect("connect malformed request");
+    malformed
+        .write_all(b"upd")
+        .await
+        .expect("send partial request");
+    malformed.shutdown().await.expect("disconnect request");
+    let mut discarded = Vec::new();
+    malformed
+        .read_to_end(&mut discarded)
+        .await
+        .expect("rejected request");
+    tokio::time::sleep(Duration::from_millis(100)).await;
+    assert!(!worker.is_finished(), "malformed request stopped updater");
+    assert_eq!(
+        super::manual_update::request(&daemon)
+            .await
+            .expect("unsupported response")
+            .status,
+        UpdateStatus::Unsupported
+    );
+    tokio::time::sleep(Duration::from_millis(100)).await;
+    assert!(!worker.is_finished(), "unsupported request stopped updater");
+    worker.abort();
+}
+
+#[cfg(unix)]
+async fn test_control_server(
+    daemon: &Daemon,
+    home: &std::path::Path,
+) -> tokio::task::JoinHandle<()> {
+    use futures::SinkExt;
+    use futures::StreamExt;
+    std::fs::create_dir_all(daemon.socket_path.parent().expect("socket parent"))
+        .expect("socket directory");
+    let mut listener = codex_uds::UnixListener::bind(&daemon.socket_path)
+        .await
+        .expect("control listener");
+    let codex_home = home.to_path_buf();
+    tokio::spawn(async move {
+        loop {
+            let connection = listener.accept().await.expect("control connection");
+            let mut websocket = tokio_tungstenite::accept_async(connection)
+                .await
+                .expect("websocket handshake");
+            websocket
+                .next()
+                .await
+                .expect("initialize request")
+                .expect("frame");
+            let version = if std::fs::read_to_string(
+                crate::managed_install::package_root(&codex_home).join("auto-update-version"),
+            )
+            .unwrap_or_default()
+            .starts_with("1.1.0")
+            {
+                "1.1.0"
+            } else {
+                "1.0.0"
+            };
+            websocket.send(tokio_tungstenite::tungstenite::Message::Text(
+                serde_json::json!({"id": 1, "result": {
+                    "userAgent": format!("codex_app_server_daemon/{version}"),
+                    "codexHome": codex_home, "platformFamily": "unix", "platformOs": std::env::consts::OS,
+                }}).to_string().into(),
+            )).await.expect("initialize response");
+            websocket
+                .next()
+                .await
+                .expect("initialized notification")
+                .expect("frame");
+        }
+    })
+}
+
+#[cfg(unix)]
+#[tokio::test]
+async fn manual_update_restarts_managed_daemon_with_automatic_updates_disabled() {
+    check_manual_update_restart("standalone").await;
+}
+
+#[cfg(unix)]
+#[tokio::test]
+async fn manual_update_restarts_local_daemon_with_automatic_updates_disabled() {
+    check_manual_update_restart("app-server-daemon").await;
+}
+
+#[cfg(unix)]
+async fn check_manual_update_restart(package_directory: &str) {
+    use tokio::io::AsyncReadExt;
+    use tokio::io::AsyncWriteExt;
+
+    let local_package = package_directory == "app-server-daemon";
+    let home = TempDir::new().expect("home");
+    let (mut daemon, mut release) = manual_update_daemon(&home);
+    let standalone = home.path().join("packages").join(package_directory);
+    if local_package {
+        std::fs::rename(home.path().join("packages/standalone"), &standalone).unwrap();
+        let local = format!("local-development-{release}");
+        std::fs::rename(
+            standalone.join("releases").join(&release),
+            standalone.join("releases").join(&local),
+        )
+        .unwrap();
+        std::fs::remove_file(standalone.join("current")).unwrap();
+        std::os::unix::fs::symlink(format!("releases/{local}"), standalone.join("current"))
+            .unwrap();
+        std::fs::remove_file(standalone.join("auto-update-version")).unwrap();
+        daemon.managed_codex_bin = standalone.join("current/codex");
+        release = local;
+    }
+    let daemon = std::sync::Arc::new(daemon);
+    std::fs::create_dir_all(daemon.settings_file.parent().expect("state directory"))
+        .expect("state directory");
+    std::fs::write(
+        &daemon.settings_file,
+        r#"{"updater":{"autoUpdateEnabled":false}}"#,
+    )
+    .expect("disabled updater");
+    let server = test_control_server(&daemon, home.path()).await;
+    let settings = crate::settings::DaemonSettings::default();
+    let backend = crate::backend::pid_backend(daemon.backend_paths(&settings));
+    backend.start().await.expect("start daemon");
+    let current_pid = || {
+        serde_json::from_slice::<serde_json::Value>(
+            &std::fs::read(&daemon.pid_file).expect("daemon PID record"),
+        )
+        .expect("PID JSON")["pid"]
+            .as_u64()
+            .expect("PID")
+    };
+    let before = current_pid();
+    let version = if local_package { "1.0.0" } else { "1.1.0" };
+    let next = release
+        .trim_start_matches("local-development-")
+        .replacen("1.0.0", version, 1);
+    let guard = if local_package {
+        "CODEX_INSTALL_IF_CURRENT"
+    } else {
+        "CODEX_INSTALL_IF_LATEST"
+    };
+    let install_binary = if local_package {
+        // Same binary and version, but a different package: it must still restart.
+        format!(
+            "cp '{root}/releases/{release}/codex' '{root}/releases/{next}/bin/codex'",
+            root = standalone.display()
+        )
+    } else {
+        format!(
+            r#"printf '#!/bin/sh\nif [ "$1" = --version ]; then echo codex 1.1.0; else exec sleep 30; fi\n' > '{root}/releases/{next}/bin/codex'"#,
+            root = standalone.display()
+        )
+    };
+    let ready = home.path().join("installer-ready");
+    let proceed = home.path().join("installer-proceed");
+    let script = format!(
+        "#!/bin/sh\n# CODEX_INSTALL_IF_LATEST CODEX_INSTALL_IF_CURRENT CODEX_INSTALL_DAEMON_ONLY\nif [ \"$CODEX_UPDATE_FROM_RELEASE\" = '{next}' ]; then exit 0; fi\ntest \"${guard}\" = 1 || exit 4\ntest \"$CODEX_UPDATE_FROM_RELEASE\" = '{release}' || exit 5\ntouch '{ready}'\nwhile [ ! -e '{proceed}' ]; do sleep .05; done\nmkdir -p '{root}/releases/{next}/bin'\n{install_binary}\nchmod +x '{root}/releases/{next}/bin/codex'\nln -sfn 'releases/{next}' '{root}/current'\nprintf '{next}' > '{root}/auto-update-version'\n",
+        root = standalone.display(),
+        ready = ready.display(),
+        proceed = proceed.display(),
+    );
+    let http = FakeInstallerHttp::new(InstallerResponse::Success(script.into_bytes()));
+    let updater_daemon = std::sync::Arc::clone(&daemon);
+    let restore_release = local_package.then(|| release.clone());
+    let worker = tokio::spawn(async move {
+        super::run_with_http(
+            &http,
+            &updater_daemon,
+            &executable_identity_from_bytes(b"updater"),
+            restore_release,
+        )
+        .await
+    });
+    let deadline = tokio::time::Instant::now() + Duration::from_secs(5);
+    while !daemon.manual_update_socket_path().exists() {
+        assert!(
+            tokio::time::Instant::now() < deadline,
+            "updater did not listen"
+        );
+        tokio::time::sleep(Duration::from_millis(20)).await;
+    }
+    let request_daemon = std::sync::Arc::clone(&daemon);
+    let request = tokio::spawn(async move { super::manual_update::request(&request_daemon).await });
+    while !ready.exists() {
+        assert!(
+            tokio::time::Instant::now() < deadline,
+            "installer did not start"
+        );
+        tokio::time::sleep(Duration::from_millis(20)).await;
+    }
+    let mut queued = codex_uds::UnixStream::connect(&daemon.manual_update_socket_path())
+        .await
+        .expect("queue a second update");
+    queued
+        .write_all(b"update\n")
+        .await
+        .expect("send second update");
+    std::fs::write(proceed, b"go").expect("release installer");
+    let output = request
+        .await
+        .expect("first request task")
+        .expect("manual update");
+    assert_eq!(output.status, UpdateStatus::Updated);
+    assert_eq!(output.installed_version.as_deref(), Some(version));
+    assert_eq!(output.running_version.as_deref(), Some(version));
+    assert_eq!(
+        output.managed_codex_path,
+        standalone.join("current/bin/codex")
+    );
+    let restarted = current_pid();
+    assert_ne!(restarted, before);
+    let mut response = Vec::new();
+    queued
+        .read_to_end(&mut response)
+        .await
+        .expect("second response");
+    let second: Result<crate::UpdateOutput, String> =
+        serde_json::from_slice(&response).expect("valid second response");
+    assert_eq!(
+        second.expect("second update").status,
+        UpdateStatus::NoUpdate
+    );
+    assert_eq!(current_pid(), restarted);
+    tokio::time::timeout(Duration::from_secs(5), worker)
+        .await
+        .expect("one-shot updater did not exit")
+        .expect("updater task")
+        .expect("updater loop");
+    let no_op = FakeInstallerHttp::new(InstallerResponse::Success(
+        b"#!/bin/sh\n# CODEX_INSTALL_IF_LATEST CODEX_INSTALL_DAEMON_ONLY\nexit 0\n".to_vec(),
+    ));
+    use std::io::Write;
+    std::fs::OpenOptions::new()
+        .append(true)
+        .open(
+            daemon
+                .current_managed_codex_bin()
+                .expect("current executable"),
+        )
+        .expect("managed executable")
+        .write_all(b"\n# same-version replacement\n")
+        .expect("replace binary bytes");
+    let output = manual_update_once(
+        &no_op,
+        &daemon,
+        &executable_identity_from_bytes(b"updater"),
+        &mut test_terminate(),
+        super::UpdateTrigger::Manual,
+    )
+    .await
+    .expect("retry with stale running binary");
+    assert_eq!(output.status, UpdateStatus::NoUpdate);
+    assert_ne!(current_pid(), restarted);
+    backend.stop().await.expect("stop daemon");
+    server.abort();
+}
+
+#[cfg(windows)]
+#[tokio::test]
+async fn powershell_installer_is_noninteractive_and_reports_script_failure() {
+    let valid = FakeInstallerHttp::new(InstallerResponse::Success(
+        br#"
+function Test-Installer {
+    if ($env:CODEX_NON_INTERACTIVE -ne '1') { throw 'interactive installer' }
+    if ($env:CODEX_INSTALL_DAEMON_ONLY -ne '1') { throw 'wrong package destination' }
+    if ($env:CODEX_INSTALL_IF_CURRENT -ne '1' -or $env:CODEX_INSTALL_IF_LATEST -ne '0') { throw 'wrong update guard' }
+}
+Test-Installer
+"#
+        .to_vec(),
+    ));
+    let script = super::fetch_installer_script(&valid)
+        .await
+        .expect("fetch installer");
+    super::run_installer_script(
+        &script,
+        super::InstallerMode::RestoreProduction("0.150.0-x86_64-pc-windows-msvc"),
+        std::path::Path::new("packages/app-server-daemon"),
+    )
+    .await
+    .expect("installer succeeds");
+    let failing = FakeInstallerHttp::new(InstallerResponse::Success(
+        b"throw 'installer failed'".to_vec(),
+    ));
+    let script = super::fetch_installer_script(&failing)
+        .await
+        .expect("fetch failing installer");
+    assert!(
+        super::run_installer_script(
+            &script,
+            super::InstallerMode::RestoreProduction("0.150.0-x86_64-pc-windows-msvc"),
+            std::path::Path::new("packages/app-server-daemon")
+        )
+        .await
+        .is_err()
+    );
+}
+
+#[cfg(unix)]
+#[tokio::test]
+async fn update_rejects_a_package_root_change_during_download() {
+    struct ChangingRoot<'a>(&'a std::path::Path);
+    impl InstallerHttp for ChangingRoot<'_> {
+        async fn get(&self, _url: &str) -> anyhow::Result<InstallerResponse> {
+            std::os::unix::fs::symlink(
+                self.0.join("packages/standalone"),
+                self.0.join("packages/app-server-daemon"),
+            )?;
+            Ok(InstallerResponse::Success(
+                b"# CODEX_INSTALL_IF_LATEST\nexit 99\n".to_vec(),
+            ))
+        }
+    }
+    let home = TempDir::new().unwrap();
+    let (daemon, _) = manual_update_daemon(&home);
+    let identity = executable_identity(&daemon.managed_codex_bin)
+        .await
+        .unwrap();
+    let error = manual_update_once(
+        &ChangingRoot(home.path()),
+        &daemon,
+        &identity,
+        &mut test_terminate(),
+        super::UpdateTrigger::Manual,
+    )
+    .await
+    .unwrap_err();
+    assert!(error.to_string().contains("package root changed"));
+}
+
+#[cfg(unix)]
+#[tokio::test]
+async fn daemon_owned_updates_require_and_request_an_isolated_installer() {
+    let home = TempDir::new().unwrap();
+    let (mut daemon, release) = manual_update_daemon(&home);
+    let root = home.path().join("packages/app-server-daemon");
+    std::fs::rename(home.path().join("packages/standalone"), &root).unwrap();
+    daemon.managed_codex_bin = root.join("current/codex");
+    let identity = executable_identity(&daemon.managed_codex_bin)
+        .await
+        .unwrap();
+    let old = FakeInstallerHttp::new(InstallerResponse::Success(
+        b"# CODEX_INSTALL_IF_LATEST\nexit 0\n".to_vec(),
+    ));
+    let error = manual_update_once(
+        &old,
+        &daemon,
+        &identity,
+        &mut test_terminate(),
+        super::UpdateTrigger::Manual,
+    )
+    .await
+    .unwrap_err();
+    assert!(
+        error
+            .to_string()
+            .contains("does not support daemon-owned packages")
+    );
+    let current = FakeInstallerHttp::new(InstallerResponse::Success(
+        b"# CODEX_INSTALL_IF_LATEST\ntest \"$CODEX_INSTALL_IF_LATEST\" = 1 && test \"$CODEX_INSTALL_DAEMON_ONLY\" = 1\n".to_vec(),
+    ));
+    let output = manual_update_once(
+        &current,
+        &daemon,
+        &identity,
+        &mut test_terminate(),
+        super::UpdateTrigger::Manual,
+    )
+    .await
+    .unwrap();
+    assert_eq!(output.status, UpdateStatus::NoUpdate);
+    assert!(!home.path().join("packages/standalone").exists());
+
+    // Reuse the stopped daemon to verify explicit unpinning with either preference.
+    let marker = root.join("auto-update-version");
+    let no_op = FakeInstallerHttp::new(InstallerResponse::Success(
+        b"# CODEX_INSTALL_IF_CURRENT CODEX_INSTALL_DAEMON_ONLY\nexit 0\n".to_vec(),
+    ));
+    let script = format!(
+        r#"# CODEX_INSTALL_IF_CURRENT CODEX_INSTALL_DAEMON_ONLY
+set -eu
+test "$CODEX_INSTALL_IF_CURRENT" = 1
+test "$CODEX_INSTALL_IF_LATEST" = 0
+test "$CODEX_INSTALL_DAEMON_ONLY" = 1
+test "$CODEX_RELEASE" = latest
+test "$CODEX_UPDATE_FROM_RELEASE" = '{release}'
+printf '%s' '{release}' > '{marker}'
+"#,
+        marker = marker.display()
+    );
+    let restore = FakeInstallerHttp::new(InstallerResponse::Success(script.into_bytes()));
+    for auto_update_enabled in [false, true] {
+        let settings = format!(r#"{{"updater":{{"autoUpdateEnabled":{auto_update_enabled}}}}}"#);
+        std::fs::write(&daemon.settings_file, &settings).unwrap();
+        std::fs::remove_file(&marker).unwrap();
+        let error = manual_update_once(
+            &no_op,
+            &daemon,
+            &identity,
+            &mut test_terminate(),
+            super::UpdateTrigger::RestoreProduction(&release),
+        )
+        .await
+        .unwrap_err();
+        assert!(
+            error
+                .to_string()
+                .contains("did not select a stable latest release")
+        );
+        assert!(!marker.exists());
+        let restored = manual_update_once(
+            &restore,
+            &daemon,
+            &identity,
+            &mut test_terminate(),
+            super::UpdateTrigger::RestoreProduction(&release),
+        )
+        .await
+        .unwrap();
+        // Restoring eligibility for the same package still reports noUpdate.
+        assert_eq!(restored, output);
+        assert!(!daemon.pid_file.exists());
+        assert!(daemon.is_stable_standalone_release().unwrap());
+        assert_eq!(
+            std::fs::read_to_string(&daemon.settings_file).unwrap(),
+            settings
+        );
+    }
+}

codex-rs/build-info/src/build_info_tests.rs

@@ -0,0 +1,197 @@
+use std::fs;
+
+use codex_install_context::InstallContext;
+use pretty_assertions::assert_eq;
+use semver::Version;
+use tempfile::tempdir;
+
+use crate::BuildInfo;
+use crate::build_id;
+
+const BUILD_COMMIT: &str = "0123456789abcdef0123456789abcdef01234567";
+
+/// A packaged runtime takes its release identity from its package manifest.
+#[test]
+fn packaged_runtime_uses_manifest_version() {
+    let package = tempdir().expect("create runtime package");
+    let bin_dir = package.path().join("bin");
+    fs::create_dir(&bin_dir).expect("create runtime binary directory");
+    let executable = bin_dir.join("codex");
+    fs::write(&executable, b"").expect("create runtime binary");
+    fs::write(
+        package.path().join("codex-package.json"),
+        r#"{"version":"1.2.3-alpha.4"}"#,
+    )
+    .expect("create runtime package manifest");
+
+    let context = InstallContext::from_exe(
+        cfg!(target_os = "macos"),
+        Some(&executable),
+        /*method_override*/ None,
+    );
+
+    assert_eq!(
+        BuildInfo::resolve(&context, BUILD_COMMIT),
+        BuildInfo {
+            version: Version::parse("1.2.3-alpha.4").expect("valid release version"),
+            build_commit: BUILD_COMMIT.to_string(),
+            target: Some(env!("CODEX_BUILD_TARGET").to_string()),
+        },
+    );
+}
+
+/// Unpackaged builds expose their stamped commit and structured source version.
+#[test]
+fn unpackaged_runtime_uses_build_commit() {
+    let context = InstallContext::from_exe(
+        cfg!(target_os = "macos"),
+        /*current_exe*/ None,
+        /*method_override*/ None,
+    );
+
+    assert_eq!(
+        BuildInfo::resolve(&context, BUILD_COMMIT),
+        BuildInfo {
+            version: Version::new(0, 0, 0),
+            build_commit: BUILD_COMMIT.to_string(),
+            target: Some(env!("CODEX_BUILD_TARGET").to_string()),
+        },
+    );
+}
+
+/// Older package layouts without release metadata retain their build identity.
+#[test]
+fn legacy_package_without_version_uses_build_commit() {
+    let package = tempdir().expect("create runtime package");
+    let bin_dir = package.path().join("bin");
+    fs::create_dir(&bin_dir).expect("create runtime binary directory");
+    let executable = bin_dir.join("codex");
+    fs::write(&executable, b"").expect("create runtime binary");
+    fs::write(package.path().join("codex-package.json"), "{}")
+        .expect("create legacy runtime package manifest");
+
+    let context = InstallContext::from_exe(
+        cfg!(target_os = "macos"),
+        Some(&executable),
+        /*method_override*/ None,
+    );
+
+    assert_eq!(
+        BuildInfo::resolve(&context, BUILD_COMMIT),
+        BuildInfo {
+            version: Version::new(0, 0, 0),
+            build_commit: BUILD_COMMIT.to_string(),
+            target: Some(env!("CODEX_BUILD_TARGET").to_string()),
+        },
+    );
+}
+
+/// Invalid package versions cannot override the executable's stamped commit.
+#[test]
+fn invalid_package_version_uses_build_commit() {
+    let package = tempdir().expect("create runtime package");
+    let bin_dir = package.path().join("bin");
+    fs::create_dir(&bin_dir).expect("create runtime binary directory");
+    let executable = bin_dir.join("codex");
+    fs::write(&executable, b"").expect("create runtime binary");
+    fs::write(
+        package.path().join("codex-package.json"),
+        r#"{"version":"not-a-release-version"}"#,
+    )
+    .expect("create runtime package manifest");
+
+    let context = InstallContext::from_exe(
+        cfg!(target_os = "macos"),
+        Some(&executable),
+        /*method_override*/ None,
+    );
+
+    assert_eq!(
+        BuildInfo::resolve(&context, BUILD_COMMIT),
+        BuildInfo {
+            version: Version::new(0, 0, 0),
+            build_commit: BUILD_COMMIT.to_string(),
+            target: Some(env!("CODEX_BUILD_TARGET").to_string()),
+        },
+    );
+}
+
+/// Serializing build information preserves release version, commit, and target.
+#[test]
+fn build_info_serialization_preserves_build_provenance() {
+    let build_info = BuildInfo {
+        version: Version::parse("1.2.3-alpha.4").expect("valid release version"),
+        build_commit: BUILD_COMMIT.to_string(),
+        target: Some("x86_64-pc-windows-msvc".to_string()),
+    };
+    let serialized = serde_json::json!({
+        "version": "1.2.3-alpha.4",
+        "build_commit": BUILD_COMMIT,
+        "target": "x86_64-pc-windows-msvc",
+    });
+
+    assert_eq!(
+        serde_json::to_value(&build_info).expect("serialize build information"),
+        serialized,
+    );
+    assert_eq!(
+        serde_json::from_value::<BuildInfo>(serialized).expect("deserialize build information"),
+        build_info,
+    );
+}
+
+#[test]
+fn historical_build_info_does_not_infer_the_current_target() {
+    let legacy = serde_json::json!({ "version": "1.2.3", "build_commit": BUILD_COMMIT });
+    for info in [
+        serde_json::from_value::<BuildInfo>(legacy).expect("deserialize legacy build information"),
+        BuildInfo::from_version("1.2.3"),
+        BuildInfo::from_version(BUILD_COMMIT),
+    ] {
+        assert_eq!(info.target(), None);
+    }
+}
+
+#[test]
+fn build_id_is_stable_and_uses_the_supplied_commit_and_target() {
+    // These vectors also cover targets different from the machine running CI.
+    for (target, digest) in [
+        (
+            "aarch64-apple-darwin",
+            "90138d7ee35f3f61cd61eb55e8d64105f856055641af175388b102dffa772594",
+        ),
+        (
+            "x86_64-unknown-linux-gnu",
+            "89f3a373036537bde64861b3ad8b1c9494924b0174622e47acda695619630d09",
+        ),
+        (
+            "x86_64-unknown-linux-musl",
+            "fb4f62da3e84f6864dcec8ede7bc66f1c96ecaeaf55f8a786b85df994057c8ac",
+        ),
+    ] {
+        let expected = Some(format!("sha256:{digest}"));
+        assert_eq!(build_id(BUILD_COMMIT, target), expected);
+        assert_eq!(
+            build_id(&BUILD_COMMIT.to_ascii_uppercase(), target),
+            expected
+        );
+        assert_ne!(
+            build_id("1123456789abcdef0123456789abcdef01234567", target),
+            expected
+        );
+    }
+}
+
+#[test]
+fn build_id_requires_a_valid_stamp_and_target() {
+    for commit in [
+        "",
+        "dev",
+        "unknown",
+        "0123456",
+        "zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz",
+    ] {
+        assert_eq!(build_id(commit, "x86_64-unknown-linux-musl"), None);
+    }
+    assert_eq!(build_id(BUILD_COMMIT, ""), None);
+}

codex-rs/build-info/src/lib.rs

@@ -0,0 +1,155 @@
+//! Resolve the packaged release version, compiled commit, and target of the current runtime.
+
+use std::fmt;
+use std::sync::OnceLock;
+
+use codex_install_context::InstallContext;
+use semver::Version;
+use serde::Deserialize;
+use serde::Serialize;
+use sha2::Digest;
+use sha2::Sha256;
+
+static BUILD_INFO: OnceLock<BuildInfo> = OnceLock::new();
+
+/// Initialize build information from the commit stamped into the calling executable.
+///
+/// The environment lookup intentionally expands at the macro call site so Git
+/// changes invalidate only final binary actions, not this shared library.
+/// Cargo builds must supply STABLE_GIT_COMMIT in the build environment.
+#[macro_export]
+macro_rules! initialize {
+    () => {
+        $crate::BuildInfo::initialize(option_env!("STABLE_GIT_COMMIT").unwrap_or("dev"));
+    };
+}
+
+/// The packaged release version and build provenance for the current runtime.
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+pub struct BuildInfo {
+    version: Version,
+    build_commit: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    target: Option<String>,
+}
+
+impl BuildInfo {
+    /// Return build information for the current Codex runtime.
+    pub fn get() -> Self {
+        BUILD_INFO
+            .get_or_init(|| Self::resolve(InstallContext::current(), "dev"))
+            .clone()
+    }
+
+    /// Initialize build information using the final executable's stamped commit.
+    ///
+    /// Keeping the stamp in the executable prevents Git operations from
+    /// invalidating the shared Rust library graph.
+    #[doc(hidden)]
+    pub fn initialize(build_commit: &'static str) {
+        let _ = BUILD_INFO.get_or_init(|| Self::resolve(InstallContext::current(), build_commit));
+    }
+
+    /// Recover structured release information from a persisted version string.
+    pub fn from_version(version: impl Into<String>) -> Self {
+        let version = version.into();
+        match Version::parse(&version) {
+            Ok(parsed_version) => Self {
+                build_commit: if parsed_version.major == 0
+                    && parsed_version.minor == 0
+                    && parsed_version.patch == 0
+                {
+                    version
+                } else {
+                    "unknown".to_string()
+                },
+                version: parsed_version,
+                target: None,
+            },
+            Err(_) => Self {
+                version: Version::new(0, 0, 0),
+                build_commit: version,
+                target: None,
+            },
+        }
+    }
+
+    /// Return the parsed package version, or `0.0.0` for a source build.
+    pub fn version(&self) -> &Version {
+        &self.version
+    }
+
+    /// Format the version for a user-facing Codex header.
+    pub fn display_version(&self) -> String {
+        if self.build_commit == "dev" {
+            "dev".to_string()
+        } else if self.is_source_build() {
+            format!("v{}", self.build_commit)
+        } else {
+            format!("v{}", self.version)
+        }
+    }
+
+    /// Identify source builds without parsing their displayed Git commit.
+    pub fn is_source_build(&self) -> bool {
+        self.version.major == 0 && self.version.minor == 0 && self.version.patch == 0
+    }
+
+    /// Return the Git commit stamped into the final executable.
+    pub fn build_commit(&self) -> &str {
+        &self.build_commit
+    }
+
+    /// Return the compiler target triple, or `None` for historical metadata without a target.
+    pub fn target(&self) -> Option<&str> {
+        self.target.as_deref()
+    }
+
+    fn resolve(install_context: &InstallContext, build_commit: &'static str) -> Self {
+        if let Some(manifest) = install_context.package_manifest() {
+            return Self {
+                version: manifest.version,
+                build_commit: build_commit.to_owned(),
+                target: Some(env!("CODEX_BUILD_TARGET").to_owned()),
+            };
+        }
+
+        Self {
+            version: Version::new(0, 0, 0),
+            build_commit: build_commit.to_owned(),
+            target: Some(env!("CODEX_BUILD_TARGET").to_owned()),
+        }
+    }
+}
+
+/// Derive a standard build's opaque ID from its stamped commit and compiler target.
+///
+/// Explicit inputs let CI identify cross-compiled builds without running them.
+/// Runtime callers must use the running executable's stamp and target. The stable
+/// encoding is SHA-256 of `git:<full lowercase commit>:<target>`, excluding version.
+/// This identifies a standard build configuration, not exact executable bytes.
+pub fn build_id(build_commit: &str, target: &str) -> Option<String> {
+    if build_commit.len() != 40
+        || !build_commit.bytes().all(|byte| byte.is_ascii_hexdigit())
+        || target.is_empty()
+    {
+        return None;
+    }
+    let identity = format!("git:{}:{target}", build_commit.to_ascii_lowercase());
+    let digest = Sha256::digest(identity.as_bytes());
+    Some(format!("sha256:{digest:x}"))
+}
+
+impl fmt::Display for BuildInfo {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        if self.is_source_build() {
+            formatter.write_str(&self.build_commit)
+        } else {
+            self.version.fmt(formatter)
+        }
+    }
+}
+
+#[cfg(test)]
+#[path = "build_info_tests.rs"]
+mod tests;

codex-rs/cloud-tasks/src/app.rs

@@ -0,0 +1,534 @@
+use std::time::Duration;
+use std::time::Instant;
+
+// Environment filter data models for the TUI
+#[derive(Clone, Debug, Default)]
+pub struct EnvironmentRow {
+    pub id: String,
+    pub label: Option<String>,
+    pub is_pinned: bool,
+    pub repo_hints: Option<String>, // e.g., "openai/codex"
+}
+
+#[derive(Clone, Debug, Default)]
+pub struct EnvModalState {
+    pub query: String,
+    pub selected: usize,
+}
+
+#[derive(Clone, Debug, Default)]
+pub struct BestOfModalState {
+    pub selected: usize,
+}
+
+#[derive(Clone, Debug, Copy, PartialEq, Eq)]
+pub enum ApplyResultLevel {
+    Success,
+    Partial,
+    Error,
+}
+
+#[derive(Clone, Debug)]
+pub struct ApplyModalState {
+    pub task_id: TaskId,
+    pub title: String,
+    pub result_message: Option<String>,
+    pub result_level: Option<ApplyResultLevel>,
+    pub skipped_paths: Vec<String>,
+    pub conflict_paths: Vec<String>,
+    pub diff_override: Option<String>,
+}
+
+use crate::scrollable_diff::ScrollableDiff;
+use codex_cloud_tasks_client::CloudBackend;
+use codex_cloud_tasks_client::TaskId;
+use codex_cloud_tasks_client::TaskSummary;
+#[derive(Default)]
+pub struct App {
+    pub tasks: Vec<TaskSummary>,
+    pub selected: usize,
+    pub status: String,
+    pub diff_overlay: Option<DiffOverlay>,
+    pub spinner_start: Option<Instant>,
+    pub refresh_inflight: bool,
+    pub details_inflight: bool,
+    // Environment filter state
+    pub env_filter: Option<String>,
+    pub env_modal: Option<EnvModalState>,
+    pub apply_modal: Option<ApplyModalState>,
+    pub best_of_modal: Option<BestOfModalState>,
+    pub environments: Vec<EnvironmentRow>,
+    pub env_last_loaded: Option<std::time::Instant>,
+    pub env_loading: bool,
+    pub env_error: Option<String>,
+    // New Task page
+    pub new_task: Option<crate::new_task::NewTaskPage>,
+    pub best_of_n: usize,
+    // Apply preflight spinner state
+    pub apply_preflight_inflight: bool,
+    // Apply action spinner state
+    pub apply_inflight: bool,
+    // Background enrichment coordination
+    pub list_generation: u64,
+    pub in_flight: std::collections::HashSet<String>,
+    // Background enrichment caches were planned; currently unused.
+}
+
+impl App {
+    pub fn new() -> Self {
+        Self {
+            tasks: Vec::new(),
+            selected: 0,
+            status: "Press r to refresh".to_string(),
+            diff_overlay: None,
+            spinner_start: None,
+            refresh_inflight: false,
+            details_inflight: false,
+            env_filter: None,
+            env_modal: None,
+            apply_modal: None,
+            best_of_modal: None,
+            environments: Vec::new(),
+            env_last_loaded: None,
+            env_loading: false,
+            env_error: None,
+            new_task: None,
+            best_of_n: 1,
+            apply_preflight_inflight: false,
+            apply_inflight: false,
+            list_generation: 0,
+            in_flight: std::collections::HashSet::new(),
+        }
+    }
+
+    pub fn next(&mut self) {
+        if self.tasks.is_empty() {
+            return;
+        }
+        self.selected = (self.selected + 1).min(self.tasks.len().saturating_sub(1));
+    }
+
+    pub fn prev(&mut self) {
+        if self.tasks.is_empty() {
+            return;
+        }
+        if self.selected > 0 {
+            self.selected -= 1;
+        }
+    }
+}
+
+pub async fn load_tasks(
+    backend: &dyn CloudBackend,
+    env: Option<&str>,
+) -> anyhow::Result<Vec<TaskSummary>> {
+    // In later milestones, add a small debounce, spinner, and error display.
+    let tasks = tokio::time::timeout(
+        Duration::from_secs(5),
+        backend.list_tasks(env, Some(20), /*cursor*/ None),
+    )
+    .await??;
+    // Hide review-only tasks from the main list.
+    let filtered: Vec<TaskSummary> = tasks.tasks.into_iter().filter(|t| !t.is_review).collect();
+    Ok(filtered)
+}
+
+pub struct DiffOverlay {
+    pub title: String,
+    pub task_id: TaskId,
+    pub sd: ScrollableDiff,
+    pub base_can_apply: bool,
+    pub diff_lines: Vec<String>,
+    pub text_lines: Vec<String>,
+    pub prompt: Option<String>,
+    pub attempts: Vec<AttemptView>,
+    pub selected_attempt: usize,
+    pub current_view: DetailView,
+    pub base_turn_id: Option<String>,
+    pub sibling_turn_ids: Vec<String>,
+    pub attempt_total_hint: Option<usize>,
+}
+
+#[derive(Clone, Debug, Default)]
+pub struct AttemptView {
+    pub turn_id: Option<String>,
+    pub status: codex_cloud_tasks_client::AttemptStatus,
+    pub attempt_placement: Option<i64>,
+    pub diff_lines: Vec<String>,
+    pub text_lines: Vec<String>,
+    pub prompt: Option<String>,
+    pub diff_raw: Option<String>,
+}
+
+impl AttemptView {
+    pub fn has_diff(&self) -> bool {
+        !self.diff_lines.is_empty()
+    }
+
+    pub fn has_text(&self) -> bool {
+        !self.text_lines.is_empty() || self.prompt.is_some()
+    }
+}
+
+impl DiffOverlay {
+    pub fn new(task_id: TaskId, title: String, attempt_total_hint: Option<usize>) -> Self {
+        let mut sd = ScrollableDiff::new();
+        sd.set_content(Vec::new());
+        Self {
+            title,
+            task_id,
+            sd,
+            base_can_apply: false,
+            diff_lines: Vec::new(),
+            text_lines: Vec::new(),
+            prompt: None,
+            attempts: vec![AttemptView::default()],
+            selected_attempt: 0,
+            current_view: DetailView::Prompt,
+            base_turn_id: None,
+            sibling_turn_ids: Vec::new(),
+            attempt_total_hint,
+        }
+    }
+
+    pub fn current_attempt(&self) -> Option<&AttemptView> {
+        self.attempts.get(self.selected_attempt)
+    }
+
+    pub fn base_attempt_mut(&mut self) -> &mut AttemptView {
+        if self.attempts.is_empty() {
+            self.attempts.push(AttemptView::default());
+        }
+        &mut self.attempts[0]
+    }
+
+    pub fn set_view(&mut self, view: DetailView) {
+        self.current_view = view;
+        self.apply_selection_to_fields();
+    }
+
+    pub fn expected_attempts(&self) -> Option<usize> {
+        self.attempt_total_hint.or({
+            if self.attempts.is_empty() {
+                None
+            } else {
+                Some(self.attempts.len())
+            }
+        })
+    }
+
+    pub fn attempt_count(&self) -> usize {
+        self.attempts.len()
+    }
+
+    pub fn attempt_display_total(&self) -> usize {
+        self.expected_attempts()
+            .unwrap_or_else(|| self.attempts.len().max(1))
+    }
+
+    pub fn step_attempt(&mut self, delta: isize) -> bool {
+        let total = self.attempts.len();
+        if total <= 1 {
+            return false;
+        }
+        let total_isize = total as isize;
+        let current = self.selected_attempt as isize;
+        let mut next = current + delta;
+        next = ((next % total_isize) + total_isize) % total_isize;
+        let next = next as usize;
+        self.selected_attempt = next;
+        self.apply_selection_to_fields();
+        true
+    }
+
+    pub fn current_can_apply(&self) -> bool {
+        matches!(self.current_view, DetailView::Diff)
+            && self
+                .current_attempt()
+                .and_then(|attempt| attempt.diff_raw.as_ref())
+                .map(|diff| !diff.is_empty())
+                .unwrap_or(false)
+    }
+
+    pub fn apply_selection_to_fields(&mut self) {
+        let (diff_lines, text_lines, prompt) = if let Some(attempt) = self.current_attempt() {
+            (
+                attempt.diff_lines.clone(),
+                attempt.text_lines.clone(),
+                attempt.prompt.clone(),
+            )
+        } else {
+            self.diff_lines.clear();
+            self.text_lines.clear();
+            self.prompt = None;
+            self.sd.set_content(vec!["<loading attempt>".to_string()]);
+            return;
+        };
+
+        self.diff_lines = diff_lines.clone();
+        self.text_lines = text_lines.clone();
+        self.prompt = prompt;
+
+        match self.current_view {
+            DetailView::Diff => {
+                if diff_lines.is_empty() {
+                    self.sd.set_content(vec!["<no diff available>".to_string()]);
+                } else {
+                    self.sd.set_content(diff_lines);
+                }
+            }
+            DetailView::Prompt => {
+                if text_lines.is_empty() {
+                    self.sd.set_content(vec!["<no output>".to_string()]);
+                } else {
+                    self.sd.set_content(text_lines);
+                }
+            }
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum DetailView {
+    Diff,
+    Prompt,
+}
+
+/// Internal app events delivered from background tasks.
+/// These let the UI event loop remain responsive and keep the spinner animating.
+#[derive(Debug)]
+pub enum AppEvent {
+    TasksLoaded {
+        env: Option<String>,
+        result: anyhow::Result<Vec<TaskSummary>>,
+    },
+    // Background diff summary events were planned; removed for now to keep code minimal.
+    /// Autodetection of a likely environment id finished
+    EnvironmentAutodetected(anyhow::Result<crate::env_detect::AutodetectSelection>),
+    /// Background completion of environment list fetch
+    EnvironmentsLoaded(anyhow::Result<Vec<EnvironmentRow>>),
+    DetailsDiffLoaded {
+        id: TaskId,
+        title: String,
+        diff: String,
+    },
+    DetailsMessagesLoaded {
+        id: TaskId,
+        title: String,
+        messages: Vec<String>,
+        prompt: Option<String>,
+        turn_id: Option<String>,
+        sibling_turn_ids: Vec<String>,
+        attempt_placement: Option<i64>,
+        attempt_status: codex_cloud_tasks_client::AttemptStatus,
+    },
+    DetailsFailed {
+        id: TaskId,
+        title: String,
+        error: String,
+    },
+    AttemptsLoaded {
+        id: TaskId,
+        attempts: Vec<codex_cloud_tasks_client::TurnAttempt>,
+    },
+    /// Background completion of new task submission
+    NewTaskSubmitted(Result<codex_cloud_tasks_client::CreatedTask, String>),
+    /// Background completion of apply preflight when opening modal or on demand
+    ApplyPreflightFinished {
+        id: TaskId,
+        title: String,
+        message: String,
+        level: ApplyResultLevel,
+        skipped: Vec<String>,
+        conflicts: Vec<String>,
+    },
+    /// Background completion of apply action (actual patch application)
+    ApplyFinished {
+        id: TaskId,
+        result: std::result::Result<codex_cloud_tasks_client::ApplyOutcome, String>,
+    },
+}
+
+// Convenience aliases; currently unused.
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use chrono::Utc;
+    use codex_cloud_tasks_client::CloudBackendFuture;
+    use codex_cloud_tasks_client::CloudTaskError;
+
+    struct FakeBackend {
+        // maps env key to titles
+        by_env: std::collections::HashMap<Option<String>, Vec<&'static str>>,
+    }
+
+    impl FakeBackend {
+        async fn list_tasks(
+            &self,
+            env: Option<&str>,
+            limit: Option<i64>,
+            cursor: Option<&str>,
+        ) -> Result<codex_cloud_tasks_client::TaskListPage, CloudTaskError> {
+            let key = env.map(str::to_string);
+            let titles = self
+                .by_env
+                .get(&key)
+                .cloned()
+                .unwrap_or_else(|| vec!["default-a", "default-b"]);
+            let mut out = Vec::new();
+            for (i, t) in titles.into_iter().enumerate() {
+                out.push(TaskSummary {
+                    id: TaskId(format!("T-{i}")),
+                    title: t.to_string(),
+                    status: codex_cloud_tasks_client::TaskStatus::Ready,
+                    updated_at: Utc::now(),
+                    environment_id: env.map(str::to_string),
+                    environment_label: None,
+                    summary: codex_cloud_tasks_client::DiffSummary::default(),
+                    is_review: false,
+                    attempt_total: Some(1),
+                });
+            }
+            let max = limit.unwrap_or(i64::MAX);
+            let max = max.min(20);
+            let mut limited = Vec::new();
+            for task in out {
+                if (limited.len() as i64) >= max {
+                    break;
+                }
+                limited.push(task);
+            }
+            Ok(codex_cloud_tasks_client::TaskListPage {
+                tasks: limited,
+                cursor: cursor.map(str::to_string),
+            })
+        }
+
+        async fn get_task_summary(&self, id: TaskId) -> Result<TaskSummary, CloudTaskError> {
+            self.list_tasks(/*env*/ None, /*limit*/ None, /*cursor*/ None)
+                .await?
+                .tasks
+                .into_iter()
+                .find(|t| t.id == id)
+                .ok_or_else(|| CloudTaskError::Msg(format!("Task {} not found", id.0)))
+        }
+
+        async fn get_task_text(
+            &self,
+            _id: TaskId,
+        ) -> Result<codex_cloud_tasks_client::TaskText, CloudTaskError> {
+            Ok(codex_cloud_tasks_client::TaskText {
+                prompt: Some("Example prompt".to_string()),
+                messages: Vec::new(),
+                turn_id: Some("fake-turn".to_string()),
+                sibling_turn_ids: Vec::new(),
+                attempt_placement: Some(0),
+                attempt_status: codex_cloud_tasks_client::AttemptStatus::Completed,
+            })
+        }
+    }
+
+    impl codex_cloud_tasks_client::CloudBackend for FakeBackend {
+        fn list_tasks<'a>(
+            &'a self,
+            env: Option<&'a str>,
+            limit: Option<i64>,
+            cursor: Option<&'a str>,
+        ) -> CloudBackendFuture<'a, codex_cloud_tasks_client::TaskListPage> {
+            Box::pin(FakeBackend::list_tasks(self, env, limit, cursor))
+        }
+
+        fn get_task_summary(&self, id: TaskId) -> CloudBackendFuture<'_, TaskSummary> {
+            Box::pin(FakeBackend::get_task_summary(self, id))
+        }
+
+        fn get_task_diff(&self, _id: TaskId) -> CloudBackendFuture<'_, Option<String>> {
+            Box::pin(async {
+                Err(codex_cloud_tasks_client::CloudTaskError::Unimplemented(
+                    "not used in test",
+                ))
+            })
+        }
+
+        fn get_task_messages(&self, _id: TaskId) -> CloudBackendFuture<'_, Vec<String>> {
+            Box::pin(async { Ok(vec![]) })
+        }
+
+        fn get_task_text(
+            &self,
+            id: TaskId,
+        ) -> CloudBackendFuture<'_, codex_cloud_tasks_client::TaskText> {
+            Box::pin(FakeBackend::get_task_text(self, id))
+        }
+
+        fn list_sibling_attempts(
+            &self,
+            _task: TaskId,
+            _turn_id: String,
+        ) -> CloudBackendFuture<'_, Vec<codex_cloud_tasks_client::TurnAttempt>> {
+            Box::pin(async { Ok(Vec::new()) })
+        }
+
+        fn apply_task(
+            &self,
+            _id: TaskId,
+            _diff_override: Option<String>,
+        ) -> CloudBackendFuture<'_, codex_cloud_tasks_client::ApplyOutcome> {
+            Box::pin(async {
+                Err(codex_cloud_tasks_client::CloudTaskError::Unimplemented(
+                    "not used in test",
+                ))
+            })
+        }
+
+        fn apply_task_preflight(
+            &self,
+            _id: TaskId,
+            _diff_override: Option<String>,
+        ) -> CloudBackendFuture<'_, codex_cloud_tasks_client::ApplyOutcome> {
+            Box::pin(async {
+                Err(codex_cloud_tasks_client::CloudTaskError::Unimplemented(
+                    "not used in test",
+                ))
+            })
+        }
+
+        fn create_task<'a>(
+            &'a self,
+            _env_id: &'a str,
+            _prompt: &'a str,
+            _git_ref: &'a str,
+            _qa_mode: bool,
+            _best_of_n: usize,
+        ) -> CloudBackendFuture<'a, codex_cloud_tasks_client::CreatedTask> {
+            Box::pin(async {
+                Err(codex_cloud_tasks_client::CloudTaskError::Unimplemented(
+                    "not used in test",
+                ))
+            })
+        }
+    }
+
+    #[tokio::test]
+    async fn load_tasks_uses_env_parameter() {
+        // Arrange: env-specific task titles
+        let mut by_env = std::collections::HashMap::new();
+        by_env.insert(None, vec!["root-1", "root-2"]);
+        by_env.insert(Some("env-A".to_string()), vec!["A-1"]);
+        by_env.insert(Some("env-B".to_string()), vec!["B-1", "B-2", "B-3"]);
+        let backend = FakeBackend { by_env };
+
+        // Act + Assert
+        let root = load_tasks(&backend, /*env*/ None).await.unwrap();
+        assert_eq!(root.len(), 2);
+        assert_eq!(root[0].title, "root-1");
+
+        let a = load_tasks(&backend, Some("env-A")).await.unwrap();
+        assert_eq!(a.len(), 1);
+        assert_eq!(a[0].title, "A-1");
+
+        let b = load_tasks(&backend, Some("env-B")).await.unwrap();
+        assert_eq!(b.len(), 3);
+        assert_eq!(b[2].title, "B-3");
+    }
+}

codex-rs/cloud-tasks/src/cli.rs

@@ -0,0 +1,120 @@
+use clap::Args;
+use clap::Parser;
+use codex_utils_cli::CliConfigOverrides;
+
+#[derive(Parser, Debug, Default)]
+#[command(version)]
+pub struct Cli {
+    #[clap(skip)]
+    pub config_overrides: CliConfigOverrides,
+
+    #[command(subcommand)]
+    pub command: Option<Command>,
+}
+
+#[derive(Debug, clap::Subcommand)]
+pub enum Command {
+    /// Submit a new Codex Cloud task without launching the TUI.
+    Exec(ExecCommand),
+    /// Show the status of a Codex Cloud task.
+    Status(StatusCommand),
+    /// List Codex Cloud tasks.
+    List(ListCommand),
+    /// Apply the diff for a Codex Cloud task locally.
+    Apply(ApplyCommand),
+    /// Show the unified diff for a Codex Cloud task.
+    Diff(DiffCommand),
+}
+
+#[derive(Debug, Args)]
+pub struct ExecCommand {
+    /// Task prompt to run in Codex Cloud.
+    #[arg(value_name = "QUERY")]
+    pub query: Option<String>,
+
+    /// Target environment identifier (see `codex cloud` to browse).
+    #[arg(long = "env", value_name = "ENV_ID")]
+    pub environment: String,
+
+    /// Number of assistant attempts (best-of-N).
+    #[arg(
+        long = "attempts",
+        default_value_t = 1usize,
+        value_parser = parse_attempts
+    )]
+    pub attempts: usize,
+
+    /// Git branch to run in Codex Cloud (defaults to current branch).
+    #[arg(long = "branch", value_name = "BRANCH")]
+    pub branch: Option<String>,
+}
+
+fn parse_attempts(input: &str) -> Result<usize, String> {
+    let value: usize = input
+        .parse()
+        .map_err(|_| "attempts must be an integer between 1 and 4".to_string())?;
+    if (1..=4).contains(&value) {
+        Ok(value)
+    } else {
+        Err("attempts must be between 1 and 4".to_string())
+    }
+}
+
+fn parse_limit(input: &str) -> Result<i64, String> {
+    let value: i64 = input
+        .parse()
+        .map_err(|_| "limit must be an integer between 1 and 20".to_string())?;
+    if (1..=20).contains(&value) {
+        Ok(value)
+    } else {
+        Err("limit must be between 1 and 20".to_string())
+    }
+}
+
+#[derive(Debug, Args)]
+pub struct StatusCommand {
+    /// Codex Cloud task identifier to inspect.
+    #[arg(value_name = "TASK_ID")]
+    pub task_id: String,
+}
+
+#[derive(Debug, Args)]
+pub struct ListCommand {
+    /// Filter tasks by environment identifier.
+    #[arg(long = "env", value_name = "ENV_ID")]
+    pub environment: Option<String>,
+
+    /// Maximum number of tasks to return (1-20).
+    #[arg(long = "limit", default_value_t = 20, value_parser = parse_limit, value_name = "N")]
+    pub limit: i64,
+
+    /// Pagination cursor returned by a previous call.
+    #[arg(long = "cursor", value_name = "CURSOR")]
+    pub cursor: Option<String>,
+
+    /// Emit JSON instead of plain text.
+    #[arg(long = "json", default_value_t = false)]
+    pub json: bool,
+}
+
+#[derive(Debug, Args)]
+pub struct ApplyCommand {
+    /// Codex Cloud task identifier to apply.
+    #[arg(value_name = "TASK_ID")]
+    pub task_id: String,
+
+    /// Attempt number to apply (1-based).
+    #[arg(long = "attempt", value_parser = parse_attempts, value_name = "N")]
+    pub attempt: Option<usize>,
+}
+
+#[derive(Debug, Args)]
+pub struct DiffCommand {
+    /// Codex Cloud task identifier to display.
+    #[arg(value_name = "TASK_ID")]
+    pub task_id: String,
+
+    /// Attempt number to display (1-based).
+    #[arg(long = "attempt", value_parser = parse_attempts, value_name = "N")]
+    pub attempt: Option<usize>,
+}

codex-rs/cloud-tasks/src/env_detect.rs

@@ -0,0 +1,428 @@
+use codex_git_utils::SanitizedGitUrl;
+use codex_http_client::RouteAwareClientPool;
+use http::StatusCode;
+use http::header::CONTENT_TYPE;
+use http::header::HeaderMap;
+use std::collections::HashMap;
+use tracing::info;
+use tracing::warn;
+
+#[derive(Debug, Clone, serde::Deserialize)]
+struct CodeEnvironment {
+    id: String,
+    #[serde(default)]
+    label: Option<String>,
+    #[serde(default)]
+    is_pinned: Option<bool>,
+    #[serde(default)]
+    task_count: Option<i64>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AutodetectSelection {
+    pub id: String,
+    pub label: Option<String>,
+}
+
+pub async fn autodetect_environment_id(
+    http: &RouteAwareClientPool,
+    base_url: &str,
+    headers: &HeaderMap,
+    desired_label: Option<String>,
+) -> anyhow::Result<AutodetectSelection> {
+    autodetect_environment_id_with_origins(
+        http,
+        base_url,
+        headers,
+        desired_label,
+        &get_git_origins(),
+    )
+    .await
+}
+
+async fn autodetect_environment_id_with_origins(
+    http: &impl EnvironmentHttp,
+    base_url: &str,
+    headers: &HeaderMap,
+    desired_label: Option<String>,
+    origins: &[SanitizedGitUrl],
+) -> anyhow::Result<AutodetectSelection> {
+    // 1) Try repo-specific environments based on local git origins (GitHub only, like VSCode)
+    crate::append_error_log(format!("env: git origins: {origins:?}"));
+    let mut by_repo_envs: Vec<CodeEnvironment> = Vec::new();
+    for origin in origins {
+        if let Some((owner, repo)) = parse_owner_repo(origin.as_str()) {
+            let url = if base_url.contains("/backend-api") {
+                format!(
+                    "{}/wham/environments/by-repo/{}/{}/{}",
+                    base_url, "github", owner, repo
+                )
+            } else {
+                format!(
+                    "{}/api/codex/environments/by-repo/{}/{}/{}",
+                    base_url, "github", owner, repo
+                )
+            };
+            crate::append_error_log(format!("env: GET {url}"));
+            match get_json::<Vec<CodeEnvironment>>(http, &url, headers).await {
+                Ok(mut list) => {
+                    crate::append_error_log(format!(
+                        "env: by-repo returned {} env(s) for {owner}/{repo}",
+                        list.len(),
+                    ));
+                    by_repo_envs.append(&mut list);
+                }
+                Err(e) => crate::append_error_log(format!(
+                    "env: by-repo fetch failed for {owner}/{repo}: {e}"
+                )),
+            }
+        }
+    }
+    if let Some(env) = pick_environment_row(&by_repo_envs, desired_label.as_deref()) {
+        return Ok(AutodetectSelection {
+            id: env.id.clone(),
+            label: env.label.as_deref().map(str::to_owned),
+        });
+    }
+
+    // 2) Fallback to the full list
+    let list_url = if base_url.contains("/backend-api") {
+        format!("{base_url}/wham/environments")
+    } else {
+        format!("{base_url}/api/codex/environments")
+    };
+    crate::append_error_log(format!("env: GET {list_url}"));
+    // Fetch and log the full environments JSON for debugging
+    let response = http.get(&list_url, headers).await?;
+    let status = response.status;
+    let ct = response.content_type;
+    let body = response.body;
+    crate::append_error_log(format!("env: status={status} content-type={ct}"));
+    match serde_json::from_str::<serde_json::Value>(&body) {
+        Ok(v) => {
+            let pretty = serde_json::to_string_pretty(&v).unwrap_or(body.clone());
+            crate::append_error_log(format!("env: /environments JSON (pretty):\n{pretty}"));
+        }
+        Err(_) => crate::append_error_log(format!("env: /environments (raw):\n{body}")),
+    }
+    if !status.is_success() {
+        anyhow::bail!("GET {list_url} failed: {status}; content-type={ct}; body={body}");
+    }
+    let all_envs: Vec<CodeEnvironment> = serde_json::from_str(&body).map_err(|e| {
+        anyhow::anyhow!("Decode error for {list_url}: {e}; content-type={ct}; body={body}")
+    })?;
+    if let Some(env) = pick_environment_row(&all_envs, desired_label.as_deref()) {
+        return Ok(AutodetectSelection {
+            id: env.id.clone(),
+            label: env.label.as_deref().map(str::to_owned),
+        });
+    }
+    anyhow::bail!("no environments available")
+}
+
+fn pick_environment_row(
+    envs: &[CodeEnvironment],
+    desired_label: Option<&str>,
+) -> Option<CodeEnvironment> {
+    if envs.is_empty() {
+        return None;
+    }
+    if let Some(label) = desired_label {
+        let lc = label.to_lowercase();
+        if let Some(e) = envs
+            .iter()
+            .find(|e| e.label.as_deref().unwrap_or("").to_lowercase() == lc)
+        {
+            crate::append_error_log(format!("env: matched by label: {label} -> {}", e.id));
+            return Some(e.clone());
+        }
+    }
+    if envs.len() == 1 {
+        crate::append_error_log("env: single environment available; selecting it");
+        return Some(envs[0].clone());
+    }
+    if let Some(e) = envs.iter().find(|e| e.is_pinned.unwrap_or(false)) {
+        crate::append_error_log(format!("env: selecting pinned environment: {}", e.id));
+        return Some(e.clone());
+    }
+    // Highest task_count as heuristic
+    if let Some(e) = envs
+        .iter()
+        .max_by_key(|e| e.task_count.unwrap_or(0))
+        .or_else(|| envs.first())
+    {
+        crate::append_error_log(format!("env: selecting by task_count/first: {}", e.id));
+        return Some(e.clone());
+    }
+    None
+}
+
+async fn get_json<T: serde::de::DeserializeOwned>(
+    http: &impl EnvironmentHttp,
+    url: &str,
+    headers: &HeaderMap,
+) -> anyhow::Result<T> {
+    let response = http.get(url, headers).await?;
+    let status = response.status;
+    let ct = response.content_type;
+    let body = response.body;
+    crate::append_error_log(format!("env: status={status} content-type={ct}"));
+    if !status.is_success() {
+        anyhow::bail!("GET {url} failed: {status}; content-type={ct}; body={body}");
+    }
+    let parsed = serde_json::from_str::<T>(&body).map_err(|e| {
+        anyhow::anyhow!("Decode error for {url}: {e}; content-type={ct}; body={body}")
+    })?;
+    Ok(parsed)
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+struct EnvironmentResponse {
+    status: StatusCode,
+    content_type: String,
+    body: String,
+}
+
+/// HTTP boundary used by environment discovery.
+///
+/// Implementations must issue a GET for the complete `url`, forward all supplied headers, and
+/// return the response status, content type, and body for the caller to validate and decode.
+trait EnvironmentHttp: Send + Sync {
+    fn get<'a>(
+        &'a self,
+        url: &'a str,
+        headers: &'a HeaderMap,
+    ) -> impl std::future::Future<Output = anyhow::Result<EnvironmentResponse>> + Send + 'a;
+}
+
+impl EnvironmentHttp for RouteAwareClientPool {
+    async fn get(&self, url: &str, headers: &HeaderMap) -> anyhow::Result<EnvironmentResponse> {
+        let response = RouteAwareClientPool::get(self, url)
+            .headers(headers.clone())
+            .send()
+            .await?;
+        Ok(EnvironmentResponse {
+            status: response.status(),
+            content_type: response
+                .headers()
+                .get(CONTENT_TYPE)
+                .and_then(|value| value.to_str().ok())
+                .unwrap_or("")
+                .to_string(),
+            body: response.text().await.unwrap_or_default(),
+        })
+    }
+}
+
+fn get_git_origins() -> Vec<SanitizedGitUrl> {
+    // Prefer: git config --get-regexp remote\..*\.url
+    let out = std::process::Command::new("git")
+        .args(["-c", codex_git_utils::SAFE_BARE_REPOSITORY_CONFIG])
+        .args(["config", "--get-regexp", "remote\\..*\\.url"])
+        .output();
+    if let Ok(ok) = out
+        && ok.status.success()
+    {
+        let s = String::from_utf8_lossy(&ok.stdout);
+        let mut urls = Vec::new();
+        for line in s.lines() {
+            if let Some((_, url)) = line.split_once(' ')
+                && let Ok(url) = SanitizedGitUrl::try_from(url.trim())
+            {
+                urls.push(url);
+            }
+        }
+        if !urls.is_empty() {
+            return uniq(urls);
+        }
+    }
+    // Fallback: git remote -v
+    let out = std::process::Command::new("git")
+        .args(["-c", codex_git_utils::SAFE_BARE_REPOSITORY_CONFIG])
+        .args(["remote", "-v"])
+        .output();
+    if let Ok(ok) = out
+        && ok.status.success()
+    {
+        let s = String::from_utf8_lossy(&ok.stdout);
+        let mut urls = Vec::new();
+        for line in s.lines() {
+            let parts: Vec<&str> = line.split_whitespace().collect();
+            if parts.len() >= 2
+                && let Ok(url) = SanitizedGitUrl::try_from(parts[1])
+            {
+                urls.push(url);
+            }
+        }
+        if !urls.is_empty() {
+            return uniq(urls);
+        }
+    }
+    Vec::new()
+}
+
+fn uniq(mut v: Vec<SanitizedGitUrl>) -> Vec<SanitizedGitUrl> {
+    v.sort();
+    v.dedup();
+    v
+}
+
+fn parse_owner_repo(url: &str) -> Option<(String, String)> {
+    // Normalize common prefixes and handle multiple SSH/HTTPS variants.
+    let mut s = url.trim().to_string();
+    // Drop protocol scheme for ssh URLs
+    if let Some(rest) = s.strip_prefix("ssh://") {
+        s = rest.to_string();
+    }
+    // Accept any user before @github.com (e.g., git@, org-123@)
+    if let Some(idx) = s.find("@github.com:") {
+        let rest = &s[idx + "@github.com:".len()..];
+        let rest = rest.trim_start_matches('/').trim_end_matches(".git");
+        let mut parts = rest.splitn(2, '/');
+        let owner = parts.next()?.to_string();
+        let repo = parts.next()?.to_string();
+        crate::append_error_log(format!("env: parsed SSH GitHub origin => {owner}/{repo}"));
+        return Some((owner, repo));
+    }
+    // HTTPS or git protocol
+    for prefix in [
+        "https://github.com/",
+        "http://github.com/",
+        "git://github.com/",
+        "github.com/",
+        "github.com:",
+    ] {
+        if let Some(rest) = s.strip_prefix(prefix) {
+            let rest = rest.trim_start_matches('/').trim_end_matches(".git");
+            let mut parts = rest.splitn(2, '/');
+            let owner = parts.next()?.to_string();
+            let repo = parts.next()?.to_string();
+            crate::append_error_log(format!("env: parsed HTTP GitHub origin => {owner}/{repo}"));
+            return Some((owner, repo));
+        }
+    }
+    None
+}
+
+/// List environments for the current repo(s) with a fallback to the global list.
+/// Returns a de-duplicated, sorted set suitable for the TUI modal.
+pub async fn list_environments(
+    http: &RouteAwareClientPool,
+    base_url: &str,
+    headers: &HeaderMap,
+) -> anyhow::Result<Vec<crate::app::EnvironmentRow>> {
+    list_environments_with_origins(http, base_url, headers, &get_git_origins()).await
+}
+
+async fn list_environments_with_origins(
+    http: &impl EnvironmentHttp,
+    base_url: &str,
+    headers: &HeaderMap,
+    origins: &[SanitizedGitUrl],
+) -> anyhow::Result<Vec<crate::app::EnvironmentRow>> {
+    let mut map: HashMap<String, crate::app::EnvironmentRow> = HashMap::new();
+
+    // 1) By-repo lookup for each parsed GitHub origin
+    for origin in origins {
+        if let Some((owner, repo)) = parse_owner_repo(origin.as_str()) {
+            let url = if base_url.contains("/backend-api") {
+                format!(
+                    "{}/wham/environments/by-repo/{}/{}/{}",
+                    base_url, "github", owner, repo
+                )
+            } else {
+                format!(
+                    "{}/api/codex/environments/by-repo/{}/{}/{}",
+                    base_url, "github", owner, repo
+                )
+            };
+            match get_json::<Vec<CodeEnvironment>>(http, &url, headers).await {
+                Ok(list) => {
+                    info!("env_tui: by-repo {}:{} -> {} envs", owner, repo, list.len());
+                    for e in list {
+                        let entry =
+                            map.entry(e.id.clone())
+                                .or_insert_with(|| crate::app::EnvironmentRow {
+                                    id: e.id.clone(),
+                                    label: e.label.clone(),
+                                    is_pinned: e.is_pinned.unwrap_or(false),
+                                    repo_hints: Some(format!("{owner}/{repo}")),
+                                });
+                        // Merge: keep label if present, or use new; accumulate pinned flag
+                        if entry.label.is_none() {
+                            entry.label = e.label.clone();
+                        }
+                        entry.is_pinned = entry.is_pinned || e.is_pinned.unwrap_or(false);
+                        if entry.repo_hints.is_none() {
+                            entry.repo_hints = Some(format!("{owner}/{repo}"));
+                        }
+                    }
+                }
+                Err(e) => {
+                    warn!(
+                        "env_tui: by-repo fetch failed for {}/{}: {}",
+                        owner, repo, e
+                    );
+                }
+            }
+        }
+    }
+
+    // 2) Fallback to the full list; on error return what we have if any.
+    let list_url = if base_url.contains("/backend-api") {
+        format!("{base_url}/wham/environments")
+    } else {
+        format!("{base_url}/api/codex/environments")
+    };
+    match get_json::<Vec<CodeEnvironment>>(http, &list_url, headers).await {
+        Ok(list) => {
+            info!("env_tui: global list -> {} envs", list.len());
+            for e in list {
+                let entry = map
+                    .entry(e.id.clone())
+                    .or_insert_with(|| crate::app::EnvironmentRow {
+                        id: e.id.clone(),
+                        label: e.label.clone(),
+                        is_pinned: e.is_pinned.unwrap_or(false),
+                        repo_hints: None,
+                    });
+                if entry.label.is_none() {
+                    entry.label = e.label.clone();
+                }
+                entry.is_pinned = entry.is_pinned || e.is_pinned.unwrap_or(false);
+            }
+        }
+        Err(e) => {
+            if map.is_empty() {
+                return Err(e);
+            } else {
+                warn!(
+                    "env_tui: global list failed; using by-repo results only: {}",
+                    e
+                );
+            }
+        }
+    }
+
+    let mut rows: Vec<crate::app::EnvironmentRow> = map.into_values().collect();
+    rows.sort_by(|a, b| {
+        // pinned first
+        let p = b.is_pinned.cmp(&a.is_pinned);
+        if p != std::cmp::Ordering::Equal {
+            return p;
+        }
+        // then label (ci), then id
+        let al = a.label.as_deref().unwrap_or("").to_lowercase();
+        let bl = b.label.as_deref().unwrap_or("").to_lowercase();
+        let l = al.cmp(&bl);
+        if l != std::cmp::Ordering::Equal {
+            return l;
+        }
+        a.id.cmp(&b.id)
+    });
+    Ok(rows)
+}
+
+#[cfg(test)]
+#[path = "env_detect_tests.rs"]
+mod tests;

codex-rs/cloud-tasks/src/env_detect_tests.rs

@@ -0,0 +1,359 @@
+use std::collections::HashMap;
+use std::io;
+use std::io::Read;
+use std::io::Write;
+use std::sync::Mutex;
+use std::time::Duration;
+use std::time::Instant;
+
+use codex_http_client::ClientRouteClass;
+use codex_http_client::HttpClientFactory;
+use codex_http_client::OutboundProxyPolicy;
+use http::HeaderMap;
+use http::HeaderValue;
+use http::StatusCode;
+use http::header::AUTHORIZATION;
+use pretty_assertions::assert_eq;
+
+use super::*;
+
+const BASE_URL: &str = "https://chatgpt.com/backend-api";
+const BY_REPO_URL: &str =
+    "https://chatgpt.com/backend-api/wham/environments/by-repo/github/openai/codex";
+const GLOBAL_URL: &str = "https://chatgpt.com/backend-api/wham/environments";
+
+#[tokio::test]
+async fn production_http_forwards_headers_and_decodes_response() {
+    let listener = std::net::TcpListener::bind(("127.0.0.1", 0))
+        .expect("environment HTTP listener should bind");
+    let address = listener
+        .local_addr()
+        .expect("environment HTTP listener should have an address");
+    listener
+        .set_nonblocking(true)
+        .expect("environment HTTP listener should become nonblocking");
+    let server = std::thread::spawn(move || {
+        let deadline = Instant::now() + Duration::from_secs(10);
+        let (mut stream, _) = loop {
+            match listener.accept() {
+                Ok(connection) => break connection,
+                Err(error) if error.kind() == io::ErrorKind::WouldBlock => {
+                    assert!(
+                        Instant::now() < deadline,
+                        "environment HTTP listener should receive a request"
+                    );
+                    std::thread::sleep(Duration::from_millis(10));
+                }
+                Err(error) => panic!("environment HTTP listener should accept: {error}"),
+            }
+        };
+        stream
+            .set_nonblocking(false)
+            .expect("environment HTTP stream should become blocking");
+        stream
+            .set_read_timeout(Some(Duration::from_secs(10)))
+            .expect("environment HTTP stream should get a read timeout");
+        let mut request = Vec::new();
+        let mut buffer = [0_u8; 1024];
+        loop {
+            let bytes_read = stream
+                .read(&mut buffer)
+                .expect("environment HTTP request should read");
+            if bytes_read == 0 {
+                break;
+            }
+            request.extend_from_slice(&buffer[..bytes_read]);
+            if request.windows(4).any(|window| window == b"\r\n\r\n") {
+                break;
+            }
+        }
+
+        let body = r#"[{"id":"env-real","label":"Real"}]"#;
+        write!(
+            stream,
+            "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}",
+            body.len()
+        )
+        .expect("environment HTTP response should write");
+        String::from_utf8(request).expect("environment HTTP request should be UTF-8")
+    });
+    let http = RouteAwareClientPool::new_without_request_logging(
+        HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault),
+        ClientRouteClass::Api,
+    );
+    let base_url = format!("http://{address}");
+    let headers =
+        HeaderMap::from_iter([(AUTHORIZATION, HeaderValue::from_static("Bearer real-token"))]);
+
+    let selection = tokio::time::timeout(
+        Duration::from_secs(10),
+        autodetect_environment_id_with_origins(
+            &http,
+            &base_url,
+            &headers,
+            /*desired_label*/ None,
+            &[],
+        ),
+    )
+    .await
+    .expect("environment request should finish")
+    .expect("environment response should decode");
+    let request = server
+        .join()
+        .expect("environment HTTP server should finish");
+
+    assert_eq!(
+        selection,
+        AutodetectSelection {
+            id: "env-real".to_string(),
+            label: Some("Real".to_string()),
+        }
+    );
+    assert!(request.starts_with("GET /api/codex/environments HTTP/1.1\r\n"));
+    assert!(
+        request
+            .to_ascii_lowercase()
+            .contains("authorization: bearer real-token\r\n")
+    );
+}
+
+#[tokio::test]
+async fn autodetect_requests_exact_repository_endpoint_and_decodes_selection() {
+    let http = FakeHttp::new(HashMap::from([(
+        BY_REPO_URL.to_string(),
+        json_response(r#"[{"id":"env-repo","label":"Repository","is_pinned":true}]"#),
+    )]));
+
+    let headers = HeaderMap::from_iter([(
+        AUTHORIZATION,
+        HeaderValue::from_static("Bearer forwarded-token"),
+    )]);
+    let selection = autodetect_environment_id_with_origins(
+        &http,
+        BASE_URL,
+        &headers,
+        Some("Repository".to_string()),
+        &[SanitizedGitUrl::try_from("git@github.com:openai/codex.git").expect("valid Git remote")],
+    )
+    .await
+    .expect("repository environment should be selected");
+
+    assert_eq!(
+        selection,
+        AutodetectSelection {
+            id: "env-repo".to_string(),
+            label: Some("Repository".to_string()),
+        }
+    );
+    assert_eq!(
+        http.requests(),
+        vec![RecordedRequest {
+            url: BY_REPO_URL.to_string(),
+            headers,
+        }]
+    );
+}
+
+/// Repository discovery must accept credential-bearing origins without exposing credentials.
+#[tokio::test]
+async fn autodetect_sanitizes_credential_bearing_git_origins() {
+    let http = FakeHttp::new(HashMap::from([(
+        BY_REPO_URL.to_string(),
+        json_response(r#"[{"id":"env-repo","label":"Repository"}]"#),
+    )]));
+
+    let selection = autodetect_environment_id_with_origins(
+        &http,
+        BASE_URL,
+        &HeaderMap::new(),
+        /*desired_label*/ None,
+        &[SanitizedGitUrl::try_from(
+            "https://alice:synthetic-git-secret@github.com/openai/codex.git",
+        )
+        .expect("valid Git remote")],
+    )
+    .await
+    .expect("repository environment should be selected");
+
+    assert_eq!(
+        selection,
+        AutodetectSelection {
+            id: "env-repo".to_string(),
+            label: Some("Repository".to_string()),
+        }
+    );
+    assert_eq!(http.requested_urls(), vec![BY_REPO_URL.to_string()]);
+}
+
+/// Removing an SCP remote username must not prevent repository-specific discovery.
+#[tokio::test]
+async fn autodetect_recognizes_sanitized_scp_git_origins() {
+    let http = FakeHttp::new(HashMap::from([(
+        BY_REPO_URL.to_string(),
+        json_response(r#"[{"id":"env-repo","label":"Repository"}]"#),
+    )]));
+
+    let selection = autodetect_environment_id_with_origins(
+        &http,
+        BASE_URL,
+        &HeaderMap::new(),
+        /*desired_label*/ None,
+        &[
+            SanitizedGitUrl::try_from("org-123@github.com:openai/codex.git")
+                .expect("valid Git remote"),
+        ],
+    )
+    .await
+    .expect("repository environment should be selected");
+
+    assert_eq!(
+        selection,
+        AutodetectSelection {
+            id: "env-repo".to_string(),
+            label: Some("Repository".to_string()),
+        }
+    );
+    assert_eq!(http.requested_urls(), vec![BY_REPO_URL.to_string()]);
+}
+
+#[tokio::test]
+async fn autodetect_falls_back_to_exact_global_endpoint_and_decodes_selection() {
+    let http = FakeHttp::new(HashMap::from([
+        (BY_REPO_URL.to_string(), json_response("[]")),
+        (
+            GLOBAL_URL.to_string(),
+            json_response(r#"[{"id":"env-global","label":"Global"}]"#),
+        ),
+    ]));
+
+    let selection = autodetect_environment_id_with_origins(
+        &http,
+        BASE_URL,
+        &HeaderMap::new(),
+        /*desired_label*/ None,
+        &[SanitizedGitUrl::try_from("git@github.com:openai/codex.git").expect("valid Git remote")],
+    )
+    .await
+    .expect("global environment should be selected");
+
+    assert_eq!(
+        selection,
+        AutodetectSelection {
+            id: "env-global".to_string(),
+            label: Some("Global".to_string()),
+        }
+    );
+    assert_eq!(
+        http.requested_urls(),
+        vec![BY_REPO_URL.to_string(), GLOBAL_URL.to_string()]
+    );
+}
+
+#[tokio::test]
+async fn list_requests_exact_repository_and_global_endpoints_and_merges_results() {
+    let http = FakeHttp::new(HashMap::from([
+        (
+            BY_REPO_URL.to_string(),
+            json_response(r#"[{"id":"env-repo","label":"Repository"}]"#),
+        ),
+        (
+            GLOBAL_URL.to_string(),
+            json_response(
+                r#"[{"id":"env-repo","is_pinned":true},{"id":"env-global","label":"Global"}]"#,
+            ),
+        ),
+    ]));
+
+    let rows = list_environments_with_origins(
+        &http,
+        BASE_URL,
+        &HeaderMap::new(),
+        &[
+            SanitizedGitUrl::try_from("https://github.com/openai/codex.git")
+                .expect("valid Git remote"),
+        ],
+    )
+    .await
+    .expect("environment list should decode");
+
+    assert_eq!(
+        rows.into_iter()
+            .map(|row| (row.id, row.label, row.is_pinned, row.repo_hints))
+            .collect::<Vec<_>>(),
+        vec![
+            (
+                "env-repo".to_string(),
+                Some("Repository".to_string()),
+                true,
+                Some("openai/codex".to_string()),
+            ),
+            (
+                "env-global".to_string(),
+                Some("Global".to_string()),
+                false,
+                None,
+            ),
+        ]
+    );
+    assert_eq!(
+        http.requested_urls(),
+        vec![BY_REPO_URL.to_string(), GLOBAL_URL.to_string()]
+    );
+}
+
+struct FakeHttp {
+    responses: HashMap<String, EnvironmentResponse>,
+    requests: Mutex<Vec<RecordedRequest>>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+struct RecordedRequest {
+    url: String,
+    headers: HeaderMap,
+}
+
+impl FakeHttp {
+    fn new(responses: HashMap<String, EnvironmentResponse>) -> Self {
+        Self {
+            responses,
+            requests: Mutex::new(Vec::new()),
+        }
+    }
+
+    fn requests(&self) -> Vec<RecordedRequest> {
+        self.requests.lock().expect("request lock").clone()
+    }
+
+    fn requested_urls(&self) -> Vec<String> {
+        self.requests
+            .lock()
+            .expect("request lock")
+            .iter()
+            .map(|request| request.url.clone())
+            .collect()
+    }
+}
+
+impl EnvironmentHttp for FakeHttp {
+    async fn get(&self, url: &str, headers: &HeaderMap) -> anyhow::Result<EnvironmentResponse> {
+        self.requests
+            .lock()
+            .expect("request lock")
+            .push(RecordedRequest {
+                url: url.to_string(),
+                headers: headers.clone(),
+            });
+        self.responses
+            .get(url)
+            .cloned()
+            .ok_or_else(|| anyhow::anyhow!("unexpected URL: {url}"))
+    }
+}
+
+fn json_response(body: &str) -> EnvironmentResponse {
+    EnvironmentResponse {
+        status: StatusCode::OK,
+        content_type: "application/json".to_string(),
+        body: body.to_string(),
+    }
+}

codex-rs/cloud-tasks/src/new_task.rs

@@ -0,0 +1,35 @@
+use codex_tui::ComposerInput;
+
+pub struct NewTaskPage {
+    pub composer: ComposerInput,
+    pub submitting: bool,
+    pub env_id: Option<String>,
+    pub best_of_n: usize,
+}
+
+impl NewTaskPage {
+    pub fn new(env_id: Option<String>, best_of_n: usize) -> Self {
+        let mut composer = ComposerInput::new();
+        composer.set_hint_items(vec![
+            ("⏎", "send"),
+            ("Shift+⏎", "newline"),
+            ("Ctrl+O", "env"),
+            ("Ctrl+N", "attempts"),
+            ("Ctrl+C", "quit"),
+        ]);
+        Self {
+            composer,
+            submitting: false,
+            env_id,
+            best_of_n,
+        }
+    }
+
+    // Additional helpers can be added as usage evolves.
+}
+
+impl Default for NewTaskPage {
+    fn default() -> Self {
+        Self::new(/*env_id*/ None, /*best_of_n*/ 1)
+    }
+}

codex-rs/cloud-tasks/src/scrollable_diff.rs

@@ -0,0 +1,208 @@
+use unicode_segmentation::UnicodeSegmentation;
+use unicode_width::UnicodeWidthStr;
+
+/// Scroll position and geometry for a vertical scroll view.
+#[derive(Clone, Copy, Debug, Default)]
+pub struct ScrollViewState {
+    pub scroll: u16,
+    pub viewport_h: u16,
+    pub content_h: u16,
+}
+
+impl ScrollViewState {
+    pub fn clamp(&mut self) {
+        let max_scroll = self.content_h.saturating_sub(self.viewport_h);
+        if self.scroll > max_scroll {
+            self.scroll = max_scroll;
+        }
+    }
+}
+
+/// A simple, local scrollable view for diffs or message text.
+///
+/// Owns raw lines, caches wrapped lines for a given width, and maintains
+/// a small scroll state that is clamped whenever geometry shrinks.
+#[derive(Clone, Debug, Default)]
+pub struct ScrollableDiff {
+    raw: Vec<String>,
+    wrapped: Vec<String>,
+    wrapped_src_idx: Vec<usize>,
+    wrap_cols: Option<u16>,
+    pub state: ScrollViewState,
+}
+
+impl ScrollableDiff {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Replace the raw content lines. Does not rewrap immediately; call `set_width` next.
+    pub fn set_content(&mut self, lines: Vec<String>) {
+        self.raw = lines;
+        self.wrapped.clear();
+        self.wrapped_src_idx.clear();
+        self.state.content_h = 0;
+        // Force rewrap on next set_width even if width is unchanged
+        self.wrap_cols = None;
+    }
+
+    /// Set the wrap width. If changed, rebuild wrapped lines and clamp scroll.
+    pub fn set_width(&mut self, width: u16) {
+        if self.wrap_cols == Some(width) {
+            return;
+        }
+        self.wrap_cols = Some(width);
+        self.rewrap(width);
+        self.state.clamp();
+    }
+
+    /// Update viewport height and clamp scroll if needed.
+    pub fn set_viewport(&mut self, height: u16) {
+        self.state.viewport_h = height;
+        self.state.clamp();
+    }
+
+    /// Return the cached wrapped lines. Call `set_width` first when area changes.
+    pub fn wrapped_lines(&self) -> &[String] {
+        &self.wrapped
+    }
+
+    pub fn wrapped_src_indices(&self) -> &[usize] {
+        &self.wrapped_src_idx
+    }
+
+    pub fn raw_line_at(&self, idx: usize) -> &str {
+        self.raw.get(idx).map(String::as_str).unwrap_or("")
+    }
+
+    /// Scroll by a signed delta; clamps to content.
+    pub fn scroll_by(&mut self, delta: i16) {
+        let s = self.state.scroll as i32 + delta as i32;
+        self.state.scroll = s.clamp(0, self.max_scroll() as i32) as u16;
+    }
+
+    /// Page by a signed delta; typically viewport_h - 1.
+    pub fn page_by(&mut self, delta: i16) {
+        self.scroll_by(delta);
+    }
+
+    pub fn scroll_to_top(&mut self) {
+        self.state.scroll = 0;
+    }
+
+    pub fn scroll_to_bottom(&mut self) {
+        self.state.scroll = self.max_scroll();
+    }
+
+    /// Optional percent scrolled; None when not enough geometry is known.
+    pub fn percent_scrolled(&self) -> Option<u8> {
+        if self.state.content_h == 0 || self.state.viewport_h == 0 {
+            return None;
+        }
+        if self.state.content_h <= self.state.viewport_h {
+            return None;
+        }
+        let visible_bottom = self.state.scroll.saturating_add(self.state.viewport_h) as f32;
+        let pct = (visible_bottom / self.state.content_h as f32 * 100.0).round();
+        Some(pct.clamp(0.0, 100.0) as u8)
+    }
+
+    fn max_scroll(&self) -> u16 {
+        self.state.content_h.saturating_sub(self.state.viewport_h)
+    }
+
+    fn rewrap(&mut self, width: u16) {
+        if width == 0 {
+            self.wrapped = self.raw.clone();
+            self.state.content_h = self.wrapped.len() as u16;
+            return;
+        }
+        let max_cols = width as usize;
+        let mut out: Vec<String> = Vec::new();
+        let mut out_idx: Vec<usize> = Vec::new();
+        for (raw_idx, raw) in self.raw.iter().enumerate() {
+            // Normalize tabs for width accounting (MVP: 4 spaces).
+            let raw = raw.replace('\t', "    ");
+            if raw.is_empty() {
+                out.push(String::new());
+                out_idx.push(raw_idx);
+                continue;
+            }
+            let mut line = String::new();
+            let mut line_cols = 0usize;
+            let mut last_soft_idx: Option<usize> = None; // last whitespace or punctuation break
+            for grapheme in raw
+                .graphemes(/*is_extended*/ true)
+                .flat_map(|grapheme| grapheme.split_inclusive(char::is_whitespace))
+            {
+                if grapheme == "\n" {
+                    out.push(std::mem::take(&mut line));
+                    out_idx.push(raw_idx);
+                    line_cols = 0;
+                    last_soft_idx = None;
+                    continue;
+                }
+                let grapheme_width = display_width(grapheme);
+                if line_cols.saturating_add(grapheme_width) > max_cols {
+                    if let Some(split) = last_soft_idx {
+                        let (prefix, rest) = line.split_at(split);
+                        let prefix = prefix.trim_end();
+                        if !prefix.is_empty() {
+                            out.push(prefix.to_string());
+                            out_idx.push(raw_idx);
+                        }
+                        line = rest.trim_start().to_string();
+                        last_soft_idx = None;
+                        // Retry adding the current grapheme now that the line may be shorter.
+                    } else if !line.is_empty() {
+                        out.push(std::mem::take(&mut line));
+                        out_idx.push(raw_idx);
+                    }
+                }
+                if grapheme.chars().all(char::is_whitespace)
+                    || grapheme.chars().any(|ch| {
+                        matches!(
+                            ch,
+                            ',' | ';'
+                                | '.'
+                                | ':'
+                                | ')'
+                                | ']'
+                                | '}'
+                                | '|'
+                                | '/'
+                                | '?'
+                                | '!'
+                                | '-'
+                                | '_'
+                        )
+                    })
+                {
+                    last_soft_idx = Some(line.len());
+                }
+                line.push_str(grapheme);
+                line_cols = display_width(&line);
+            }
+            if !line.is_empty() {
+                out.push(line);
+                out_idx.push(raw_idx);
+            }
+        }
+        self.wrapped = out;
+        self.wrapped_src_idx = out_idx;
+        self.state.content_h = self.wrapped.len() as u16;
+    }
+}
+
+/// Counts terminal cells, including the halfwidth sound marks omitted by `unicode-width`.
+fn display_width(text: &str) -> usize {
+    UnicodeWidthStr::width(text)
+        + text
+            .chars()
+            .filter(|ch| matches!(ch, '\u{FF9E}' | '\u{FF9F}'))
+            .count()
+}
+
+#[cfg(test)]
+#[path = "scrollable_diff_tests.rs"]
+mod tests;

codex-rs/cloud-tasks/src/scrollable_diff_tests.rs

@@ -0,0 +1,48 @@
+use super::ScrollableDiff;
+use pretty_assertions::assert_eq;
+
+#[test]
+fn wraps_halfwidth_sound_marks_using_ratatui_width() {
+    let mut diff = ScrollableDiff::new();
+    diff.set_content(vec![
+        "aｶﾞbﾊﾟc".to_string(),
+        "a ﾞb".to_string(),
+        "a ﾟb".to_string(),
+    ]);
+    diff.set_width(/*width*/ 2);
+
+    insta::assert_snapshot!(
+        diff.wrapped_lines().join("\n"),
+        @r"
+        a
+        ｶﾞ
+        b
+        ﾊﾟ
+        c
+        a
+        ﾞb
+        a
+        ﾟb
+        "
+    );
+    assert_eq!(diff.wrapped_src_indices(), [0, 0, 0, 0, 0, 1, 1, 2, 2]);
+}
+
+#[test]
+fn does_not_emit_empty_rows_after_full_width_sound_mark_graphemes() {
+    for grapheme in ["ｶﾞ", "ﾊﾟ"] {
+        let mut diff = ScrollableDiff::new();
+        diff.set_content(vec![format!("a {grapheme} tail")]);
+        diff.set_width(/*width*/ 2);
+
+        let expected = ["a", grapheme, "ta", "il"];
+        let actual = diff
+            .wrapped_lines()
+            .iter()
+            .map(String::as_str)
+            .collect::<Vec<_>>();
+        assert_eq!(actual, expected);
+        assert_eq!(diff.wrapped_src_indices(), [0, 0, 0, 0]);
+        assert_eq!(diff.state.content_h, 4);
+    }
+}

codex-rs/cloud-tasks/src/ui.rs

@@ -0,0 +1,1046 @@
+use ratatui::layout::Constraint;
+use ratatui::layout::Direction;
+use ratatui::layout::Layout;
+use ratatui::prelude::*;
+use ratatui::style::Color;
+use ratatui::style::Modifier;
+use ratatui::style::Style;
+use ratatui::style::Stylize;
+use ratatui::widgets::Block;
+use ratatui::widgets::BorderType;
+use ratatui::widgets::Borders;
+use ratatui::widgets::Clear;
+use ratatui::widgets::List;
+use ratatui::widgets::ListItem;
+use ratatui::widgets::ListState;
+use ratatui::widgets::Padding;
+use ratatui::widgets::Paragraph;
+use std::sync::OnceLock;
+use std::time::Instant;
+
+use crate::app::App;
+use crate::app::AttemptView;
+use crate::util::format_relative_time_now;
+use codex_cloud_tasks_client::AttemptStatus;
+use codex_cloud_tasks_client::TaskStatus;
+use codex_tui::render_markdown_text;
+
+pub fn draw(frame: &mut Frame, app: &mut App) {
+    let area = frame.area();
+    let chunks = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([
+            Constraint::Min(1),    // list
+            Constraint::Length(2), // two-line footer (help + status)
+        ])
+        .split(area);
+    if app.new_task.is_some() {
+        draw_new_task_page(frame, chunks[0], app);
+        draw_footer(frame, chunks[1], app);
+    } else {
+        draw_list(frame, chunks[0], app);
+        draw_footer(frame, chunks[1], app);
+    }
+
+    if app.diff_overlay.is_some() {
+        draw_diff_overlay(frame, area, app);
+    }
+    if app.env_modal.is_some() {
+        draw_env_modal(frame, area, app);
+    }
+    if app.best_of_modal.is_some() {
+        draw_best_of_modal(frame, area, app);
+    }
+    if app.apply_modal.is_some() {
+        draw_apply_modal(frame, area, app);
+    }
+}
+
+// ===== Overlay helpers (geometry + styling) =====
+static ROUNDED: OnceLock<bool> = OnceLock::new();
+
+fn rounded_enabled() -> bool {
+    *ROUNDED.get_or_init(|| {
+        std::env::var("CODEX_TUI_ROUNDED")
+            .ok()
+            .map(|v| v == "1")
+            .unwrap_or(true)
+    })
+}
+
+fn overlay_outer(area: Rect) -> Rect {
+    let outer_v = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([
+            Constraint::Percentage(10),
+            Constraint::Percentage(80),
+            Constraint::Percentage(10),
+        ])
+        .split(area)[1];
+    Layout::default()
+        .direction(Direction::Horizontal)
+        .constraints([
+            Constraint::Percentage(10),
+            Constraint::Percentage(80),
+            Constraint::Percentage(10),
+        ])
+        .split(outer_v)[1]
+}
+
+fn overlay_block() -> Block<'static> {
+    let base = Block::default().borders(Borders::ALL);
+    let base = if rounded_enabled() {
+        base.border_type(BorderType::Rounded)
+    } else {
+        base
+    };
+    base.padding(Padding::new(2, 2, 1, 1))
+}
+
+fn overlay_content(area: Rect) -> Rect {
+    overlay_block().inner(area)
+}
+
+pub fn draw_new_task_page(frame: &mut Frame, area: Rect, app: &mut App) {
+    let title_spans = {
+        let mut spans: Vec<ratatui::text::Span> = vec!["New Task".magenta().bold()];
+        if let Some(id) = app
+            .new_task
+            .as_ref()
+            .and_then(|p| p.env_id.as_ref())
+            .cloned()
+        {
+            spans.push("  • ".into());
+            // Try to map id to label
+            let label = app
+                .environments
+                .iter()
+                .find(|r| r.id == id)
+                .and_then(|r| r.label.clone())
+                .unwrap_or(id);
+            spans.push(label.dim());
+        } else {
+            spans.push("  • ".into());
+            spans.push("Env: none (press ctrl-o to choose)".red());
+        }
+        if let Some(page) = app.new_task.as_ref() {
+            spans.push("  • ".into());
+            let attempts = page.best_of_n;
+            let label = format!(
+                "{} attempt{}",
+                attempts,
+                if attempts == 1 { "" } else { "s" }
+            );
+            spans.push(label.cyan());
+        }
+        spans
+    };
+    let block = Block::default()
+        .borders(Borders::ALL)
+        .title(Line::from(title_spans));
+
+    frame.render_widget(Clear, area);
+    frame.render_widget(block.clone(), area);
+    let content = block.inner(area);
+
+    // Expand composer height up to (terminal height - 6), with a 3-line minimum.
+    let max_allowed = frame.area().height.saturating_sub(6).max(3);
+    let desired = app
+        .new_task
+        .as_ref()
+        .map(|p| p.composer.desired_height(content.width))
+        .unwrap_or(3)
+        .clamp(3, max_allowed);
+
+    // Anchor the composer to the bottom-left by allocating a flexible spacer
+    // above it and a fixed `desired`-height area for the composer.
+    let rows = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([Constraint::Min(1), Constraint::Length(desired)])
+        .split(content);
+    let composer_area = rows[1];
+
+    if let Some(page) = app.new_task.as_ref() {
+        page.composer.render_ref(composer_area, frame.buffer_mut());
+        // Composer renders its own footer hints; no extra row here.
+    }
+
+    // Place cursor where composer wants it
+    if let Some(page) = app.new_task.as_ref()
+        && let Some((x, y)) = page.composer.cursor_pos(composer_area)
+    {
+        frame.set_cursor_position((x, y));
+    }
+}
+
+fn draw_list(frame: &mut Frame, area: Rect, app: &mut App) {
+    let items: Vec<ListItem> = app.tasks.iter().map(|t| render_task_item(app, t)).collect();
+
+    // Selection reflects the actual task index (no artificial spacer item).
+    let mut state = ListState::default().with_selected(Some(app.selected));
+    // Dim task list when a modal/overlay is active to emphasize focus.
+    let dim_bg = app.env_modal.is_some()
+        || app.apply_modal.is_some()
+        || app.best_of_modal.is_some()
+        || app.diff_overlay.is_some();
+    // Dynamic title includes current environment filter
+    let suffix_span = if let Some(ref id) = app.env_filter {
+        let label = app
+            .environments
+            .iter()
+            .find(|r| &r.id == id)
+            .and_then(|r| r.label.clone())
+            .unwrap_or_else(|| "Selected".to_string());
+        format!(" • {label}").dim()
+    } else {
+        " • All".dim()
+    };
+    // Percent scrolled based on selection position in the list (0% at top, 100% at bottom).
+    let percent_span = if app.tasks.len() <= 1 {
+        "  • 0%".dim()
+    } else {
+        let p = ((app.selected as f32) / ((app.tasks.len() - 1) as f32) * 100.0).round() as i32;
+        format!("  • {}%", p.clamp(0, 100)).dim()
+    };
+    let title_line = {
+        let base = Line::from(vec!["Cloud Tasks".into(), suffix_span, percent_span]);
+        if dim_bg {
+            base.style(Style::default().add_modifier(Modifier::DIM))
+        } else {
+            base
+        }
+    };
+    let block = Block::default().borders(Borders::ALL).title(title_line);
+    // Render the outer block first
+    frame.render_widget(block.clone(), area);
+    // Draw list inside with a persistent top spacer row
+    let inner = block.inner(area);
+    let rows = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([Constraint::Length(1), Constraint::Min(1)])
+        .split(inner);
+    let mut list = List::new(items)
+        .highlight_symbol("› ")
+        .highlight_style(Style::default().bold());
+    if dim_bg {
+        list = list.style(Style::default().add_modifier(Modifier::DIM));
+    }
+    frame.render_stateful_widget(list, rows[1], &mut state);
+
+    // In-box spinner during initial/refresh loads
+    if app.refresh_inflight {
+        draw_centered_spinner(frame, inner, &mut app.spinner_start, "Loading tasks…");
+    }
+}
+
+fn draw_footer(frame: &mut Frame, area: Rect, app: &mut App) {
+    let mut help = vec![
+        "↑/↓".dim(),
+        ": Move  ".dim(),
+        "r".dim(),
+        ": Refresh  ".dim(),
+        "Enter".dim(),
+        ": Open  ".dim(),
+    ];
+    // Apply hint; show disabled note when overlay is open without a diff.
+    if let Some(ov) = app.diff_overlay.as_ref() {
+        if !ov.current_can_apply() {
+            help.push("a".dim());
+            help.push(": Apply (disabled)  ".dim());
+        } else {
+            help.push("a".dim());
+            help.push(": Apply  ".dim());
+        }
+        if ov.attempt_count() > 1 {
+            help.push("Tab".dim());
+            help.push(": Next attempt  ".dim());
+            help.push("[ ]".dim());
+            help.push(": Cycle attempts  ".dim());
+        }
+    } else {
+        help.push("a".dim());
+        help.push(": Apply  ".dim());
+    }
+    help.push("o : Set Env  ".dim());
+    if app.new_task.is_some() {
+        help.push("Ctrl+N".dim());
+        help.push(format!(": Attempts {}x  ", app.best_of_n).dim());
+        help.push("(editing new task)  ".dim());
+    } else {
+        help.push("n : New Task  ".dim());
+    }
+    help.extend(vec!["q".dim(), ": Quit  ".dim()]);
+    // Split footer area into two rows: help+spinner (top) and status (bottom)
+    let rows = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([Constraint::Length(1), Constraint::Length(1)])
+        .split(area);
+
+    // Top row: help text + spinner at right
+    let top = Layout::default()
+        .direction(Direction::Horizontal)
+        .constraints([Constraint::Fill(1), Constraint::Length(18)])
+        .split(rows[0]);
+    let para = Paragraph::new(Line::from(help));
+    // Draw help text; avoid clearing the whole footer area every frame.
+    frame.render_widget(para, top[0]);
+    // Right side: spinner or clear the spinner area if idle to prevent stale glyphs.
+    if app.refresh_inflight
+        || app.details_inflight
+        || app.env_loading
+        || app.apply_preflight_inflight
+        || app.apply_inflight
+    {
+        draw_inline_spinner(frame, top[1], &mut app.spinner_start, "Loading…");
+    } else {
+        frame.render_widget(Clear, top[1]);
+    }
+
+    // Bottom row: status/log text across full width (single-line; sanitize newlines)
+    let mut status_line = app.status.replace('\n', " ");
+    if status_line.len() > 2000 {
+        // hard cap to avoid TUI noise
+        status_line.truncate(2000);
+        status_line.push('…');
+    }
+    // Clear the status row to avoid trailing characters when the message shrinks.
+    frame.render_widget(Clear, rows[1]);
+    let status = Paragraph::new(status_line);
+    frame.render_widget(status, rows[1]);
+}
+
+fn draw_diff_overlay(frame: &mut Frame, area: Rect, app: &mut App) {
+    let inner = overlay_outer(area);
+    if app.diff_overlay.is_none() {
+        return;
+    }
+    let ov_can_apply = app
+        .diff_overlay
+        .as_ref()
+        .map(super::app::DiffOverlay::current_can_apply)
+        .unwrap_or(false);
+    let is_error = app
+        .diff_overlay
+        .as_ref()
+        .and_then(|o| o.sd.wrapped_lines().first().cloned())
+        .map(|s| s.trim_start().starts_with("Task failed:"))
+        .unwrap_or(false)
+        && !ov_can_apply;
+    let title = app
+        .diff_overlay
+        .as_ref()
+        .map(|o| o.title.clone())
+        .unwrap_or_default();
+
+    // Title block
+    let title_ref = title.as_str();
+    let mut title_spans: Vec<ratatui::text::Span> = if is_error {
+        vec![
+            "Details ".magenta(),
+            "[FAILED]".red().bold(),
+            " ".into(),
+            title_ref.magenta(),
+        ]
+    } else if ov_can_apply {
+        vec!["Diff: ".magenta(), title_ref.magenta()]
+    } else {
+        vec!["Details: ".magenta(), title_ref.magenta()]
+    };
+    if let Some(p) = app
+        .diff_overlay
+        .as_ref()
+        .and_then(|o| o.sd.percent_scrolled())
+    {
+        title_spans.push("  • ".dim());
+        title_spans.push(format!("{p}%").dim());
+    }
+    frame.render_widget(Clear, inner);
+    frame.render_widget(
+        overlay_block().title(Line::from(title_spans)).clone(),
+        inner,
+    );
+
+    // Content area and optional status bar
+    let content_full = overlay_content(inner);
+    let mut content_area = content_full;
+    if let Some(ov) = app.diff_overlay.as_mut() {
+        let has_text = ov.current_attempt().is_some_and(AttemptView::has_text);
+        let has_diff = ov.current_attempt().is_some_and(AttemptView::has_diff) || ov.base_can_apply;
+        if has_diff || has_text {
+            let rows = Layout::default()
+                .direction(Direction::Vertical)
+                .constraints([Constraint::Length(1), Constraint::Min(1)])
+                .split(content_full);
+            // Status bar label
+            let mut spans: Vec<ratatui::text::Span> = Vec::new();
+            if has_diff && has_text {
+                let prompt_lbl = if matches!(ov.current_view, crate::app::DetailView::Prompt) {
+                    "[Prompt]".magenta().bold()
+                } else {
+                    "Prompt".dim()
+                };
+                let diff_lbl = if matches!(ov.current_view, crate::app::DetailView::Diff) {
+                    "[Diff]".magenta().bold()
+                } else {
+                    "Diff".dim()
+                };
+                spans.extend(vec![
+                    prompt_lbl,
+                    "  ".into(),
+                    diff_lbl,
+                    "  ".into(),
+                    "(← → to switch view)".dim(),
+                ]);
+            } else if has_text {
+                spans.push("Conversation".magenta().bold());
+            } else {
+                spans.push("Diff".magenta().bold());
+            }
+            if let Some(total) = ov.expected_attempts().or({
+                if ov.attempts.is_empty() {
+                    None
+                } else {
+                    Some(ov.attempts.len())
+                }
+            }) && total > 1
+            {
+                spans.extend(vec![
+                    "  ".into(),
+                    format!("Attempt {}/{}", ov.selected_attempt + 1, total)
+                        .bold()
+                        .dim(),
+                    "  ".into(),
+                    "(Tab/Shift-Tab or [ ] to cycle attempts)".dim(),
+                ]);
+            }
+            frame.render_widget(Paragraph::new(Line::from(spans)), rows[0]);
+            ov.sd.set_width(rows[1].width);
+            ov.sd.set_viewport(rows[1].height);
+            content_area = rows[1];
+        } else {
+            ov.sd.set_width(content_full.width);
+            ov.sd.set_viewport(content_full.height);
+            content_area = content_full;
+        }
+    }
+
+    // Styled content render
+    // Choose styling by the active view, not just presence of a diff
+    let is_diff_view = app
+        .diff_overlay
+        .as_ref()
+        .map(|o| matches!(o.current_view, crate::app::DetailView::Diff))
+        .unwrap_or(false);
+    let styled_lines: Vec<Line<'static>> = if is_diff_view {
+        let raw = app.diff_overlay.as_ref().map(|o| o.sd.wrapped_lines());
+        raw.unwrap_or(&[])
+            .iter()
+            .map(|l| style_diff_line(l))
+            .collect()
+    } else {
+        app.diff_overlay
+            .as_ref()
+            .map(|o| style_conversation_lines(&o.sd, o.current_attempt()))
+            .unwrap_or_default()
+    };
+    let raw_empty = app
+        .diff_overlay
+        .as_ref()
+        .map(|o| o.sd.wrapped_lines().is_empty())
+        .unwrap_or(true);
+    if app.details_inflight && raw_empty {
+        draw_centered_spinner(
+            frame,
+            content_area,
+            &mut app.spinner_start,
+            "Loading details…",
+        );
+    } else {
+        let scroll = app
+            .diff_overlay
+            .as_ref()
+            .map(|o| o.sd.state.scroll)
+            .unwrap_or(0);
+        let content = Paragraph::new(Text::from(styled_lines)).scroll((scroll, 0));
+        frame.render_widget(content, content_area);
+    }
+}
+
+pub fn draw_apply_modal(frame: &mut Frame, area: Rect, app: &mut App) {
+    use ratatui::widgets::Wrap;
+    let inner = overlay_outer(area);
+    let title = Line::from("Apply Changes?".magenta().bold());
+    let block = overlay_block().title(title);
+    frame.render_widget(Clear, inner);
+    frame.render_widget(block.clone(), inner);
+    let content = overlay_content(inner);
+
+    if let Some(m) = &app.apply_modal {
+        // Header
+        let header = Paragraph::new(Line::from(
+            format!("Apply '{}' ?", m.title).magenta().bold(),
+        ))
+        .wrap(Wrap { trim: true });
+        // Footer instructions
+        let footer =
+            Paragraph::new(Line::from("Press Y to apply, P to preflight, N to cancel.").dim())
+                .wrap(Wrap { trim: true });
+
+        // Split into header/body/footer
+        let rows = Layout::default()
+            .direction(Direction::Vertical)
+            .constraints([
+                Constraint::Length(1),
+                Constraint::Min(1),
+                Constraint::Length(1),
+            ])
+            .split(content);
+
+        frame.render_widget(header, rows[0]);
+        // Body: spinner while preflight/apply runs; otherwise show result message and path lists
+        if app.apply_preflight_inflight {
+            draw_centered_spinner(frame, rows[1], &mut app.spinner_start, "Checking…");
+        } else if app.apply_inflight {
+            draw_centered_spinner(frame, rows[1], &mut app.spinner_start, "Applying…");
+        } else if m.result_message.is_none() {
+            draw_centered_spinner(frame, rows[1], &mut app.spinner_start, "Loading…");
+        } else if let Some(msg) = &m.result_message {
+            let mut body_lines: Vec<Line> = Vec::new();
+            let first = match m.result_level {
+                Some(crate::app::ApplyResultLevel::Success) => msg.clone().green(),
+                Some(crate::app::ApplyResultLevel::Partial) => msg.clone().magenta(),
+                Some(crate::app::ApplyResultLevel::Error) => msg.clone().red(),
+                None => msg.clone().into(),
+            };
+            body_lines.push(Line::from(first));
+
+            // On partial or error, show conflicts/skips if present
+            if !matches!(m.result_level, Some(crate::app::ApplyResultLevel::Success)) {
+                use ratatui::text::Span;
+                if !m.conflict_paths.is_empty() {
+                    body_lines.push(Line::from(""));
+                    body_lines.push(
+                        Line::from(format!("Conflicts ({}):", m.conflict_paths.len()))
+                            .red()
+                            .bold(),
+                    );
+                    for p in &m.conflict_paths {
+                        body_lines
+                            .push(Line::from(vec!["  • ".into(), Span::raw(p.clone()).dim()]));
+                    }
+                }
+                if !m.skipped_paths.is_empty() {
+                    body_lines.push(Line::from(""));
+                    body_lines.push(
+                        Line::from(format!("Skipped ({}):", m.skipped_paths.len()))
+                            .magenta()
+                            .bold(),
+                    );
+                    for p in &m.skipped_paths {
+                        body_lines
+                            .push(Line::from(vec!["  • ".into(), Span::raw(p.clone()).dim()]));
+                    }
+                }
+            }
+            let body = Paragraph::new(body_lines).wrap(Wrap { trim: true });
+            frame.render_widget(body, rows[1]);
+        }
+        frame.render_widget(footer, rows[2]);
+    }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum ConversationSpeaker {
+    User,
+    Assistant,
+}
+
+fn style_conversation_lines(
+    sd: &crate::scrollable_diff::ScrollableDiff,
+    attempt: Option<&AttemptView>,
+) -> Vec<Line<'static>> {
+    use ratatui::text::Span;
+
+    let wrapped = sd.wrapped_lines();
+    if wrapped.is_empty() {
+        return Vec::new();
+    }
+
+    let indices = sd.wrapped_src_indices();
+    let mut styled: Vec<Line<'static>> = Vec::new();
+    let mut speaker: Option<ConversationSpeaker> = None;
+    let mut in_code = false;
+    let mut last_src: Option<usize> = None;
+    let mut bullet_indent: Option<usize> = None;
+
+    for (display, &src_idx) in wrapped.iter().zip(indices.iter()) {
+        let raw = sd.raw_line_at(src_idx);
+        let trimmed = raw.trim();
+        let is_new_raw = last_src.map(|prev| prev != src_idx).unwrap_or(true);
+
+        if trimmed.eq_ignore_ascii_case("user:") {
+            speaker = Some(ConversationSpeaker::User);
+            in_code = false;
+            bullet_indent = None;
+            styled.push(conversation_header_line(
+                ConversationSpeaker::User,
+                /*attempt*/ None,
+            ));
+            last_src = Some(src_idx);
+            continue;
+        }
+        if trimmed.eq_ignore_ascii_case("assistant:") {
+            speaker = Some(ConversationSpeaker::Assistant);
+            in_code = false;
+            bullet_indent = None;
+            styled.push(conversation_header_line(
+                ConversationSpeaker::Assistant,
+                attempt,
+            ));
+            last_src = Some(src_idx);
+            continue;
+        }
+        if raw.is_empty() {
+            let mut spans: Vec<Span> = Vec::new();
+            if let Some(role) = speaker {
+                spans.push(conversation_gutter_span(role));
+            } else {
+                spans.push(Span::raw(String::new()));
+            }
+            styled.push(Line::from(spans));
+            last_src = Some(src_idx);
+            bullet_indent = None;
+            continue;
+        }
+
+        if is_new_raw {
+            let trimmed_start = raw.trim_start();
+            if trimmed_start.starts_with("```") {
+                in_code = !in_code;
+                bullet_indent = None;
+            } else if !in_code
+                && (trimmed_start.starts_with("- ") || trimmed_start.starts_with("* "))
+            {
+                let indent = raw.chars().take_while(|c| c.is_whitespace()).count();
+                bullet_indent = Some(indent);
+            } else if !in_code {
+                bullet_indent = None;
+            }
+        }
+
+        let mut spans: Vec<Span> = Vec::new();
+        if let Some(role) = speaker {
+            spans.push(conversation_gutter_span(role));
+        }
+
+        spans.extend(conversation_text_spans(
+            display,
+            in_code,
+            is_new_raw,
+            bullet_indent,
+        ));
+
+        styled.push(Line::from(spans));
+        last_src = Some(src_idx);
+    }
+
+    if styled.is_empty() {
+        wrapped.iter().map(|l| Line::from(l.to_string())).collect()
+    } else {
+        styled
+    }
+}
+
+fn conversation_header_line(
+    speaker: ConversationSpeaker,
+    attempt: Option<&AttemptView>,
+) -> Line<'static> {
+    use ratatui::text::Span;
+
+    let mut spans: Vec<Span> = vec!["╭ ".dim()];
+    match speaker {
+        ConversationSpeaker::User => {
+            spans.push("User".cyan().bold());
+            spans.push(" prompt".dim());
+        }
+        ConversationSpeaker::Assistant => {
+            spans.push("Assistant".magenta().bold());
+            spans.push(" response".dim());
+            if let Some(attempt) = attempt
+                && let Some(status_span) = attempt_status_span(attempt.status)
+            {
+                spans.push("  • ".dim());
+                spans.push(status_span);
+            }
+        }
+    }
+    Line::from(spans)
+}
+
+fn conversation_gutter_span(speaker: ConversationSpeaker) -> ratatui::text::Span<'static> {
+    match speaker {
+        ConversationSpeaker::User => "│ ".cyan().dim(),
+        ConversationSpeaker::Assistant => "│ ".magenta().dim(),
+    }
+}
+
+fn conversation_text_spans(
+    display: &str,
+    in_code: bool,
+    is_new_raw: bool,
+    bullet_indent: Option<usize>,
+) -> Vec<ratatui::text::Span<'static>> {
+    use ratatui::text::Span;
+
+    if in_code {
+        return vec![Span::styled(
+            display.to_string(),
+            Style::default().fg(Color::Cyan),
+        )];
+    }
+
+    let trimmed = display.trim_start();
+
+    if let Some(indent) = bullet_indent {
+        if is_new_raw {
+            let rest = trimmed.get(2..).unwrap_or("").trim_start();
+            let mut spans: Vec<Span> = Vec::new();
+            if indent > 0 {
+                spans.push(Span::raw(" ".repeat(indent)));
+            }
+            spans.push("• ".into());
+            spans.push(Span::raw(rest.to_string()));
+            return spans;
+        }
+        let mut continuation = String::new();
+        continuation.push_str(&" ".repeat(indent + 2));
+        continuation.push_str(trimmed);
+        return vec![Span::raw(continuation)];
+    }
+
+    if is_new_raw
+        && (trimmed.starts_with("### ") || trimmed.starts_with("## ") || trimmed.starts_with("# "))
+    {
+        return vec![Span::styled(
+            display.to_string(),
+            Style::default()
+                .fg(Color::Magenta)
+                .add_modifier(Modifier::BOLD),
+        )];
+    }
+
+    let mut rendered = render_markdown_text(display);
+    if rendered.lines.is_empty() {
+        return vec![Span::raw(display.to_string())];
+    }
+    // `render_markdown_text` can yield multiple lines when the input contains
+    // explicit breaks. We only expect a single line here; join the spans of the
+    // first rendered line for styling.
+    rendered.lines.remove(0).spans.into_iter().collect()
+}
+
+fn attempt_status_span(status: AttemptStatus) -> Option<ratatui::text::Span<'static>> {
+    match status {
+        AttemptStatus::Completed => Some("Completed".green()),
+        AttemptStatus::Failed => Some("Failed".red().bold()),
+        AttemptStatus::InProgress => Some("In progress".magenta()),
+        AttemptStatus::Pending => Some("Pending".cyan()),
+        AttemptStatus::Cancelled => Some("Cancelled".dim()),
+        AttemptStatus::Unknown => None,
+    }
+}
+
+fn style_diff_line(raw: &str) -> Line<'static> {
+    use ratatui::style::Color;
+    use ratatui::style::Modifier;
+    use ratatui::style::Style;
+    use ratatui::text::Span;
+
+    if raw.starts_with("@@") {
+        return Line::from(vec![Span::styled(
+            raw.to_string(),
+            Style::default()
+                .fg(Color::Magenta)
+                .add_modifier(Modifier::BOLD),
+        )]);
+    }
+    if raw.starts_with("+++") || raw.starts_with("---") {
+        return Line::from(vec![Span::styled(
+            raw.to_string(),
+            Style::default().add_modifier(Modifier::DIM),
+        )]);
+    }
+    if raw.starts_with('+') {
+        return Line::from(vec![Span::styled(
+            raw.to_string(),
+            Style::default().fg(Color::Green),
+        )]);
+    }
+    if raw.starts_with('-') {
+        return Line::from(vec![Span::styled(
+            raw.to_string(),
+            Style::default().fg(Color::Red),
+        )]);
+    }
+    Line::from(vec![Span::raw(raw.to_string())])
+}
+
+fn render_task_item(_app: &App, t: &codex_cloud_tasks_client::TaskSummary) -> ListItem<'static> {
+    let status = match t.status {
+        TaskStatus::Ready => "READY".green(),
+        TaskStatus::Pending => "PENDING".magenta(),
+        TaskStatus::Applied => "APPLIED".blue(),
+        TaskStatus::Error => "ERROR".red(),
+    };
+
+    // Title line: [STATUS] Title
+    let title = Line::from(vec![
+        "[".into(),
+        status,
+        "] ".into(),
+        t.title.clone().into(),
+    ]);
+
+    // Meta line: environment label and relative time (dim)
+    let mut meta: Vec<ratatui::text::Span> = Vec::new();
+    if let Some(lbl) = t.environment_label.as_ref().filter(|s| !s.is_empty()) {
+        meta.push(lbl.clone().dim());
+    }
+    let when = format_relative_time_now(t.updated_at).dim();
+    if !meta.is_empty() {
+        meta.push("  ".into());
+        meta.push("•".dim());
+        meta.push("  ".into());
+    }
+    meta.push(when);
+    let meta_line = Line::from(meta);
+
+    // Subline: summary when present; otherwise show "no diff"
+    let sub = if t.summary.files_changed > 0
+        || t.summary.lines_added > 0
+        || t.summary.lines_removed > 0
+    {
+        let adds = t.summary.lines_added;
+        let dels = t.summary.lines_removed;
+        let files = t.summary.files_changed;
+        Line::from(vec![
+            format!("+{adds}").green(),
+            "/".into(),
+            format!("−{dels}").red(),
+            " ".into(),
+            "•".dim(),
+            " ".into(),
+            format!("{files}").into(),
+            " ".into(),
+            "files".dim(),
+        ])
+    } else {
+        Line::from("no diff".to_string().dim())
+    };
+
+    // Insert a blank spacer line after the summary to separate tasks
+    let spacer = Line::from("");
+    ListItem::new(vec![title, meta_line, sub, spacer])
+}
+
+fn draw_inline_spinner(
+    frame: &mut Frame,
+    area: Rect,
+    spinner_start: &mut Option<Instant>,
+    label: &str,
+) {
+    use ratatui::widgets::Paragraph;
+    let start = spinner_start.get_or_insert_with(Instant::now);
+    let blink_on = (start.elapsed().as_millis() / 600).is_multiple_of(2);
+    let dot = if blink_on {
+        "• ".into()
+    } else {
+        "◦ ".dim()
+    };
+    let label = label.cyan();
+    let line = Line::from(vec![dot, label]);
+    frame.render_widget(Paragraph::new(line), area);
+}
+
+fn draw_centered_spinner(
+    frame: &mut Frame,
+    area: Rect,
+    spinner_start: &mut Option<Instant>,
+    label: &str,
+) {
+    // Center a 1xN spinner within the given rect
+    let rows = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([
+            Constraint::Percentage(50),
+            Constraint::Length(1),
+            Constraint::Percentage(49),
+        ])
+        .split(area);
+    let cols = Layout::default()
+        .direction(Direction::Horizontal)
+        .constraints([
+            Constraint::Percentage(50),
+            Constraint::Length(18),
+            Constraint::Percentage(50),
+        ])
+        .split(rows[1]);
+    draw_inline_spinner(frame, cols[1], spinner_start, label);
+}
+
+// Styling helpers for diff rendering live inline where used.
+
+pub fn draw_env_modal(frame: &mut Frame, area: Rect, app: &mut App) {
+    use ratatui::widgets::Wrap;
+
+    // Use shared overlay geometry and padding.
+    let inner = overlay_outer(area);
+
+    // Title: primary only; move long hints to a subheader inside content.
+    let title = Line::from(vec!["Select Environment".magenta().bold()]);
+    let block = overlay_block().title(title);
+
+    frame.render_widget(Clear, inner);
+    frame.render_widget(block.clone(), inner);
+    let content = overlay_content(inner);
+
+    if app.env_loading {
+        draw_centered_spinner(
+            frame,
+            content,
+            &mut app.spinner_start,
+            "Loading environments…",
+        );
+        return;
+    }
+
+    // Layout: subheader + search + results list
+    let rows = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([
+            Constraint::Length(1), // subheader
+            Constraint::Length(1), // search
+            Constraint::Min(1),    // list
+        ])
+        .split(content);
+
+    // Subheader with usage hints (dim cyan)
+    let subheader = Paragraph::new(Line::from(
+        "Type to search, Enter select, Esc cancel".cyan().dim(),
+    ))
+    .wrap(Wrap { trim: true });
+    frame.render_widget(subheader, rows[0]);
+
+    let query = app
+        .env_modal
+        .as_ref()
+        .map(|m| m.query.clone())
+        .unwrap_or_default();
+    let ql = query.to_lowercase();
+    let search = Paragraph::new(format!("Search: {query}")).wrap(Wrap { trim: true });
+    frame.render_widget(search, rows[1]);
+
+    // Filter environments by query (case-insensitive substring over label/id/hints)
+    let envs: Vec<&crate::app::EnvironmentRow> = app
+        .environments
+        .iter()
+        .filter(|e| {
+            if ql.is_empty() {
+                return true;
+            }
+            let mut hay = String::new();
+            if let Some(l) = &e.label {
+                hay.push_str(&l.to_lowercase());
+                hay.push(' ');
+            }
+            hay.push_str(&e.id.to_lowercase());
+            if let Some(h) = &e.repo_hints {
+                hay.push(' ');
+                hay.push_str(&h.to_lowercase());
+            }
+            hay.contains(&ql)
+        })
+        .collect();
+
+    let mut items: Vec<ListItem> = Vec::new();
+    items.push(ListItem::new(Line::from("All Environments (Global)")));
+    for env in envs.iter() {
+        let primary = env.label.clone().unwrap_or_else(|| "<unnamed>".to_string());
+        let mut spans: Vec<ratatui::text::Span> = vec![primary.into()];
+        if env.is_pinned {
+            spans.push("  ".into());
+            spans.push("PINNED".magenta().bold());
+        }
+        spans.push("  ".into());
+        spans.push(env.id.clone().dim());
+        if let Some(hint) = &env.repo_hints {
+            spans.push("  ".into());
+            spans.push(hint.clone().dim());
+        }
+        items.push(ListItem::new(Line::from(spans)));
+    }
+
+    let sel_desired = app.env_modal.as_ref().map(|m| m.selected).unwrap_or(0);
+    let sel = sel_desired.min(envs.len());
+    let mut list_state = ListState::default().with_selected(Some(sel));
+    let list = List::new(items)
+        .highlight_symbol("› ")
+        .highlight_style(Style::default().bold())
+        .block(Block::default().borders(Borders::NONE));
+    frame.render_stateful_widget(list, rows[2], &mut list_state);
+}
+
+pub fn draw_best_of_modal(frame: &mut Frame, area: Rect, app: &mut App) {
+    use ratatui::widgets::Wrap;
+
+    let inner = overlay_outer(area);
+    const MAX_WIDTH: u16 = 40;
+    const MIN_WIDTH: u16 = 20;
+    const MAX_HEIGHT: u16 = 12;
+    const MIN_HEIGHT: u16 = 6;
+    let modal_width = inner.width.min(MAX_WIDTH).max(inner.width.min(MIN_WIDTH));
+    let modal_height = inner
+        .height
+        .min(MAX_HEIGHT)
+        .max(inner.height.min(MIN_HEIGHT));
+    let modal_x = inner.x + (inner.width.saturating_sub(modal_width)) / 2;
+    let modal_y = inner.y + (inner.height.saturating_sub(modal_height)) / 2;
+    let modal_area = Rect::new(modal_x, modal_y, modal_width, modal_height);
+    let title = Line::from(vec!["Parallel Attempts".magenta().bold()]);
+    let block = overlay_block().title(title);
+
+    frame.render_widget(Clear, modal_area);
+    frame.render_widget(block.clone(), modal_area);
+    let content = overlay_content(modal_area);
+
+    let rows = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([Constraint::Length(2), Constraint::Min(1)])
+        .split(content);
+
+    let hint = Paragraph::new(Line::from("Use ↑/↓ to choose, 1-4 jump".cyan().dim()))
+        .wrap(Wrap { trim: true });
+    frame.render_widget(hint, rows[0]);
+
+    let selected = app.best_of_modal.as_ref().map(|m| m.selected).unwrap_or(0);
+    let options = [1usize, 2, 3, 4];
+    let mut items: Vec<ListItem> = Vec::new();
+    for &attempts in &options {
+        let noun = if attempts == 1 { "attempt" } else { "attempts" };
+        let mut spans: Vec<ratatui::text::Span> = vec![format!("{attempts} {noun:<8}").into()];
+        spans.push("  ".into());
+        spans.push(format!("{attempts}x parallel").dim());
+        if attempts == app.best_of_n {
+            spans.push("  ".into());
+            spans.push("Current".magenta().bold());
+        }
+        items.push(ListItem::new(Line::from(spans)));
+    }
+    let sel = selected.min(options.len().saturating_sub(1));
+    let mut list_state = ListState::default().with_selected(Some(sel));
+    let list = List::new(items)
+        .highlight_symbol("› ")
+        .highlight_style(Style::default().bold())
+        .block(Block::default().borders(Borders::NONE));
+    frame.render_stateful_widget(list, rows[1], &mut list_state);
+}

codex-rs/cloud-tasks/src/util.rs

@@ -0,0 +1,173 @@
+use chrono::DateTime;
+use chrono::Local;
+use chrono::Utc;
+use http::header::HeaderMap;
+
+use codex_core::config::Config;
+use codex_http_client::HttpClientFactory;
+use codex_http_client::OutboundProxyPolicy;
+use codex_login::AuthManager;
+use std::sync::Arc;
+
+pub fn set_user_agent_suffix(suffix: &str) {
+    if let Ok(mut guard) = codex_login::default_client::USER_AGENT_SUFFIX.lock() {
+        guard.replace(suffix.to_string());
+    }
+}
+
+pub fn append_error_log(message: impl AsRef<str>) {
+    let ts = Utc::now().to_rfc3339();
+    if let Ok(mut f) = std::fs::OpenOptions::new()
+        .create(true)
+        .append(true)
+        .open("error.log")
+    {
+        use std::io::Write as _;
+        let _ = writeln!(f, "[{ts}] {}", message.as_ref());
+    }
+}
+
+/// Normalize the configured base URL to a canonical form used by the backend client.
+/// - trims trailing '/'
+/// - appends '/backend-api' for ChatGPT hosts when missing
+pub fn normalize_base_url(input: &str) -> String {
+    let mut base_url = input.to_string();
+    while base_url.ends_with('/') {
+        base_url.pop();
+    }
+    if (base_url.starts_with("https://chatgpt.com")
+        || base_url.starts_with("https://chat.openai.com"))
+        && !base_url.contains("/backend-api")
+    {
+        base_url = format!("{base_url}/backend-api");
+    }
+    base_url
+}
+
+/// Validate the destination before loading saved ChatGPT credentials, including in mock mode:
+/// environment discovery still makes authenticated HTTP requests when the task backend is mocked.
+pub(crate) fn validate_chatgpt_base_url(input: &str) -> anyhow::Result<String> {
+    let invalid_url = || {
+        anyhow::anyhow!(
+            "CODEX_CLOUD_TASKS_BASE_URL must use a trusted HTTPS origin on port 443, without user information, a query, or a fragment; custom backends cannot use saved ChatGPT credentials"
+        )
+    };
+    let uri = input.parse::<http::Uri>().map_err(|_| invalid_url())?;
+    let authority = uri
+        .authority()
+        .ok_or_else(invalid_url)?
+        .as_str()
+        .to_ascii_lowercase();
+    if uri.scheme_str() != Some("https")
+        || !matches!(
+            authority.as_str(),
+            "chatgpt.com"
+                | "chatgpt.com:443"
+                | "chat.openai.com"
+                | "chat.openai.com:443"
+                | "chatgpt-staging.com"
+                | "chatgpt-staging.com:443"
+        )
+        || uri.query().is_some()
+        || input.contains('#')
+    {
+        return Err(invalid_url());
+    }
+    Ok(normalize_base_url(&format!(
+        "https://{authority}{}",
+        uri.path()
+    )))
+}
+
+pub async fn load_auth_manager(
+    chatgpt_base_url: Option<String>,
+) -> (Option<Arc<AuthManager>>, HttpClientFactory) {
+    // TODO: pass in cli overrides once cloud tasks properly support them.
+    let config = match Config::load_with_cli_overrides(Vec::new()).await {
+        Ok(config) => config,
+        Err(error) => {
+            append_error_log(format!(
+                "failed to load auth config; using transport-default proxy handling: {error}"
+            ));
+            let http_client_factory = HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault);
+            return (None, http_client_factory);
+        }
+    };
+    let http_client_factory = config.http_client_factory();
+    let mut auth_config = config.auth_config();
+    auth_config.chatgpt_base_url = chatgpt_base_url.or(Some(config.chatgpt_base_url.clone()));
+    let auth_manager = match AuthManager::shared_from_auth_config(
+        auth_config,
+        /*enable_codex_api_key_env*/ false,
+    )
+    .await
+    {
+        Ok(auth_manager) => auth_manager,
+        Err(error) => {
+            append_error_log(format!("failed to load auth: {error}"));
+            return (None, http_client_factory);
+        }
+    };
+    (Some(auth_manager), http_client_factory)
+}
+
+/// Build headers for ChatGPT-backed requests: `User-Agent`, optional `Authorization`,
+/// and optional `ChatGPT-Account-Id`.
+pub async fn build_chatgpt_headers() -> HeaderMap {
+    use http::header::HeaderValue;
+    use http::header::USER_AGENT;
+
+    set_user_agent_suffix("codex_cloud_tasks_tui");
+    let ua = codex_login::default_client::get_codex_user_agent();
+    let mut headers = HeaderMap::new();
+    headers.insert(
+        USER_AGENT,
+        HeaderValue::from_str(&ua).unwrap_or(HeaderValue::from_static("codex-cli")),
+    );
+    if let Some(am) = load_auth_manager(/*chatgpt_base_url*/ None).await.0
+        && let Some(auth) = am.auth().await
+        && auth.uses_codex_backend()
+    {
+        headers.extend(codex_model_provider::auth_provider_from_auth(&auth).to_auth_headers());
+    }
+    headers
+}
+
+/// Construct a browser-friendly task URL for the given backend base URL.
+pub fn task_url(base_url: &str, task_id: &str) -> String {
+    let normalized = normalize_base_url(base_url);
+    if let Some(root) = normalized.strip_suffix("/backend-api") {
+        return format!("{root}/codex/tasks/{task_id}");
+    }
+    if let Some(root) = normalized.strip_suffix("/api/codex") {
+        return format!("{root}/codex/tasks/{task_id}");
+    }
+    if normalized.ends_with("/codex") {
+        return format!("{normalized}/tasks/{task_id}");
+    }
+    format!("{normalized}/codex/tasks/{task_id}")
+}
+
+pub fn format_relative_time(reference: DateTime<Utc>, ts: DateTime<Utc>) -> String {
+    let mut secs = (reference - ts).num_seconds();
+    if secs < 0 {
+        secs = 0;
+    }
+    if secs < 60 {
+        return format!("{secs}s ago");
+    }
+    let mins = secs / 60;
+    if mins < 60 {
+        return format!("{mins}m ago");
+    }
+    let hours = mins / 60;
+    if hours < 24 {
+        return format!("{hours}h ago");
+    }
+    let local = ts.with_timezone(&Local);
+    local.format("%b %e %H:%M").to_string()
+}
+
+pub fn format_relative_time_now(ts: DateTime<Utc>) -> String {
+    format_relative_time(Utc::now(), ts)
+}