Skip to content

Make Codex and Claude Code subscriptions go further: a local model router that gives routine agent work to economical models and keeps your strongest model for the hard parts.

fix(desktop): restore trusted connection without restarting daemon (#194)

澄潭021fcb8ca78e
diff --git a/apps/desktop/README.md b/apps/desktop/README.md
index 4573c62f..eb6c0743 100644
--- a/apps/desktop/README.md
+++ b/apps/desktop/README.md
@@ -48,8 +48,15 @@ object, input, digest/revisions, and window lifetime, and expires after 60 secon
WebView only returns a one-time accept or reject for a current confirmation ID; it cannot
supply context, skip confirmation, or acquire a capability. Acceptance registers a one-time
Desktop capability through the inherited channel, and Apply is sent only after the matching
-acknowledgement succeeds. An uncertain registration result closes that write relationship;
-restart the native application to establish a new one.
+acknowledgement succeeds. An uncertain exchange invalidates that channel, including
+protected history reads, while the daemon may still respond to ordinary queries. Desktop
+shows this distinction and offers **Restore local connection**. Independent inherited
+maintenance pauses new work and confirms existing requests/tasks have finished before
+orderly replacement under the same host lock. Active work is left running and admission
+is restored; retry recovery after it finishes. Replacement creates a fresh native product
+session, expires old confirmations and preserves saved data. Uncertain channels and old
+callbacks never acquire the new session's authority. An unavailable maintenance channel
+or externally managed daemon gives explicit guidance instead of being forcefully replaced.
Desktop keeps only the current interaction's submission key, digest, and Operation reference
in memory so it can query or explicitly retry after a lost response. Reopening reads actual
diff --git a/apps/desktop/README.zh-CN.md b/apps/desktop/README.zh-CN.md
index 1a7eb655..ba5cfb2d 100644
--- a/apps/desktop/README.zh-CN.md
+++ b/apps/desktop/README.zh-CN.md
@@ -30,7 +30,7 @@ macOS 平台构建和实际窗口交互需要在 macOS 本机验证;通用开
## 恢复与授权边界
-确认上下文由 native backend 持有,只绑定这次 Preview 的对象、输入、digest/revisions 和窗口生命期,60 秒后失效。业务确认统一由本地 WebView 展示;WebView 只能针对 backend 发出的当前临时确认 ID 回传一次接受或拒绝,不能携带上下文、跳过确认或取得能力。接受后才通过继承通道登记 Desktop 主体的一次性能力;匹配的成功 ACK 之后才能发送 Apply。登记通道出现不确定结果后停止使用该写入关系,重新启动 native 应用才能建立新关系。
+确认上下文由 native backend 持有,只绑定这次 Preview 的对象、输入、digest/revisions 和窗口生命期,60 秒后失效。业务确认统一由本地 WebView 展示;WebView 只能针对 backend 发出的当前临时确认 ID 回传一次接受或拒绝,不能携带上下文、跳过确认或取得能力。接受后才通过继承通道登记 Desktop 主体的一次性能力;匹配的成功 ACK 之后才能发送 Apply。通道交换出现不确定结果后停止使用该通道,包括需要同一权限的历史读取;此时 daemon 的普通查询可能仍可响应。Desktop 会区分这些状态并提供“恢复本机连接”。恢复使用独立继承的维护通道,暂停新工作并确认现有请求/任务完成后,持有原宿主锁有序替换服务。仍有工作时保留运行服务并恢复新工作准入,待工作完成后可再次恢复。替换建立全新的 native 产品会话,使旧确认失效并保留已保存数据;不复用不确定通道或把旧回调接到新权限。维护通道不可用或服务由其他入口管理时显示明确指引,不强制接管。
Desktop 只在当前交互内存中保留提交 key、摘要和 Operation 引用,用于响应丢失后的查询与显式重试。重开直接读取服务端实际配置;事务恢复属于 daemon 的既有 Journal。客户端不读写 `pending-intent.json`,历史文件不会触发告警或锁定编辑。切换编辑不取消后台操作,新动作独立经过服务端版本与幂等检查。
diff --git a/apps/desktop/src-tauri/build.rs b/apps/desktop/src-tauri/build.rs
index b13d62da..104d1b70 100644
--- a/apps/desktop/src-tauri/build.rs
+++ b/apps/desktop/src-tauri/build.rs
@@ -92,6 +92,7 @@ fn main() {
"quit_desktop",
"diagnostic_status",
"startup_status",
+ "recover_native_connection",
"open_startup_recovery_directory",
"update_status",
"update_check",
diff --git a/apps/desktop/src-tauri/capabilities/main.json b/apps/desktop/src-tauri/capabilities/main.json
index 07c228a4..a761af4e 100644
--- a/apps/desktop/src-tauri/capabilities/main.json
+++ b/apps/desktop/src-tauri/capabilities/main.json
@@ -85,6 +85,7 @@
"allow-worker-task-continue",
"allow-diagnostic-status",
"allow-startup-status",
+ "allow-recover-native-connection",
"allow-open-startup-recovery-directory",
"allow-update-status",
"allow-update-check",
diff --git a/apps/desktop/src-tauri/permissions/autogenerated/recover_native_connection.toml b/apps/desktop/src-tauri/permissions/autogenerated/recover_native_connection.toml
new file mode 100644
index 00000000..8c817927
--- /dev/null
+++ b/apps/desktop/src-tauri/permissions/autogenerated/recover_native_connection.toml
@@ -0,0 +1,11 @@
+# Automatically generated - DO NOT EDIT!
+
+[[permission]]
+identifier = "allow-recover-native-connection"
+description = "Enables the recover_native_connection command without any pre-configured scope."
+commands.allow = ["recover_native_connection"]
+
+[[permission]]
+identifier = "deny-recover-native-connection"
+description = "Denies the recover_native_connection command without any pre-configured scope."
+commands.deny = ["recover_native_connection"]
diff --git a/apps/desktop/src-tauri/src/bootstrap.rs b/apps/desktop/src-tauri/src/bootstrap.rs
index e0b83363..e5e90622 100644
--- a/apps/desktop/src-tauri/src/bootstrap.rs
+++ b/apps/desktop/src-tauri/src/bootstrap.rs
@@ -1,4 +1,4 @@
-//! Native-owned child and three private inherited channels. Never exposed over WebView IPC.
+//! Native-owned child with private inherited shutdown and grant channels. Never exposed over WebView IPC.
use command_fds::{CommandFdExt, FdMapping};
use fs2::FileExt;
use hiroute_application_api::{CanonicalDigest, ComputeCandidateRefV2, RevisionSetV1};
@@ -24,6 +24,8 @@ use zeroize::Zeroizing;
use crate::native_diagnostics::NativeDiagnostics;
const DAEMON_READY_TIMEOUT: Duration = Duration::from_secs(210);
+mod channel;
+mod recovery;
mod startup_progress;
pub enum ApplyPurpose {
AgentPlan,
@@ -42,6 +44,7 @@ struct OwnedChild {
capability: File,
ack: File,
authority_healthy: bool,
+ pending_ack: Option<channel::PendingAck>,
manual_input_candidates: BTreeSet<String>,
diagnostics: Option<DiagnosticsPort>,
}
@@ -107,8 +110,11 @@ impl Resident {
})
.map_err(|_| "UPGRADE_FRAME_INVALID")?;
bytes.push(b'\n');
+ let started = Instant::now();
+ let mut phase = hiroute_diagnostics::event::ProtectedExchangePhase::RequestWrite;
let exchange = (|| {
write_frame(&mut owned.capability, &bytes)?;
+ phase = hiroute_diagnostics::event::ProtectedExchangePhase::AcknowledgementRead;
let bytes = read_frame(&mut owned.ack, 4096, Duration::from_secs(10), None)?;
let status: hiroute_host_runtime::LauncherUpgradeStatus =
serde_json::from_slice(&bytes).map_err(|_| "UPGRADE_ACK_INVALID")?;
@@ -123,6 +129,15 @@ impl Resident {
if exchange.is_err() {
owned.authority_healthy = false;
}
+ channel::emit_exchange(
+ owned.diagnostics.as_ref(),
+ hiroute_diagnostics::event::ProtectedExchangeKind::Upgrade,
+ phase,
+ &id,
+ started,
+ exchange.as_ref().err(),
+ exchange.is_err(),
+ );
exchange
}
@@ -406,6 +421,7 @@ impl Resident {
capability: cap_write,
ack: ack_read,
authority_healthy: true,
+ pending_ack: None,
manual_input_candidates: BTreeSet::new(),
diagnostics: Some(stages.clone()),
};
@@ -670,8 +686,15 @@ impl Resident {
.map_err(|_| "PROTECTED_INPUT_INVALID")?,
);
bytes.push(b'\n');
- write_frame(&mut owned.capability, &bytes)?;
- receive_ack(&mut owned.ack, &id, Duration::from_secs(2))
+ // Track even an uncertain registration so recovery can release its input.
+ owned
+ .manual_input_candidates
+ .insert(candidate.candidate_ref.clone());
+ owned.exchange_ack(
+ &bytes,
+ &id,
+ hiroute_diagnostics::event::ProtectedExchangeKind::InputRegister,
+ )
}
pub fn release_model_input(&mut self, candidate: &ComputeCandidateRefV2) -> Result<(), String> {
candidate
@@ -687,32 +710,7 @@ impl Resident {
{
return Ok(());
}
- let id = crate::random_id()?;
- #[derive(serde::Serialize)]
- struct Release<'a> {
- schema: &'static str,
- registration_id: &'a str,
- candidate_ref: &'a str,
- }
- let mut bytes = Zeroizing::new(
- serde_json::to_vec(&Release {
- schema: "hiroute.protected-input/v1",
- registration_id: &id,
- candidate_ref: &candidate.candidate_ref,
- })
- .map_err(|_| "PROTECTED_INPUT_INVALID")?,
- );
- bytes.push(b'\n');
- let result = write_frame(&mut owned.capability, &bytes)
- .and_then(|()| receive_ack(&mut owned.ack, &id, Duration::from_secs(2)));
- if result.is_ok() {
- owned
- .manual_input_candidates
- .remove(&candidate.candidate_ref);
- } else {
- owned.authority_healthy = false;
- }
- result
+ owned.release_input(&candidate.candidate_ref)
}
fn register_operation(
&mut self,
@@ -726,7 +724,7 @@ impl Resident {
let result = self.register_once(digest, revisions, operation);
if result.is_err() {
// A partial/timed-out channel cannot be reused for a different registration.
- // Keep the owned daemon alive for reads; a new native session re-establishes authority.
+ // Local Control can remain live, but protected observation reads also need authority.
if let Some(owned) = &mut self.owned {
owned.authority_healthy = false;
}
@@ -775,11 +773,15 @@ impl Resident {
.map_err(|_| "REGISTRATION_INVALID")?,
);
bytes.push(b'\n');
- write_frame(&mut owned.capability, &bytes)?;
- receive_ack(&mut owned.ack, &id, Duration::from_secs(2))?;
+ owned.exchange_ack(
+ &bytes,
+ &id,
+ hiroute_diagnostics::event::ProtectedExchangeKind::Grant,
+ )?;
Ok(capability)
}
}
+#[cfg(test)]
fn receive_ack(reader: &mut impl Read, id: &str, timeout: Duration) -> Result<(), String> {
let ack: Ack = serde_json::from_slice(&read_frame(reader, 1024, timeout, None)?)
.map_err(|_| "REGISTRATION_ACK_INVALID")?;
@@ -965,5 +967,8 @@ pub(crate) fn acquire_host_lock(root: &Path) -> Result<File, String> {
#[cfg(test)]
mod tests;
+#[cfg(all(test, target_os = "macos"))]
+mod channel_native_tests;
+
mod authority;
pub use authority::{NativeAuthority, resident};
diff --git a/apps/desktop/src-tauri/src/bootstrap/authority.rs b/apps/desktop/src-tauri/src/bootstrap/authority.rs
index 398f839e..8254eff7 100644
--- a/apps/desktop/src-tauri/src/bootstrap/authority.rs
+++ b/apps/desktop/src-tauri/src/bootstrap/authority.rs
@@ -9,6 +9,14 @@ impl HostAuthority for NativeAuthority {
fn as_any(&self) -> &dyn std::any::Any {
&self.0
}
+ fn native_connection(&self) -> Option<hiroute_product_session::NativeConnectionStatus> {
+ Some(
+ self.0
+ .lock()
+ .map(|mut resident| resident.native_connection())
+ .unwrap_or(hiroute_product_session::NativeConnectionStatus::RestartRequired),
+ )
+ }
fn has_authority(&self) -> bool {
self.0
.lock()
diff --git a/apps/desktop/src-tauri/src/bootstrap/channel.rs b/apps/desktop/src-tauri/src/bootstrap/channel.rs
new file mode 100644
index 00000000..f1f21e94
--- /dev/null
+++ b/apps/desktop/src-tauri/src/bootstrap/channel.rs
@@ -0,0 +1,309 @@
+use super::*;
+use hiroute_diagnostics::{correlation::CorrelationDomain, event::*};
+
+/// One fully written request and its exact reply. Partial reply bytes survive a
+/// timeout; malformed replies and incomplete request writes are not recoverable.
+pub(super) struct PendingAck {
+ id: String,
+ bytes: Vec<u8>,
+}
+
+impl PendingAck {
+ fn new(id: &str) -> Self {
+ Self {
+ id: id.into(),
+ bytes: Vec::new(),
+ }
+ }
+
+ fn receive(&mut self, reader: &mut impl Read, timeout: Duration) -> Result<(), String> {
+ let deadline = Instant::now() + timeout;
+ loop {
+ if Instant::now() >= deadline {
+ return Err("PROTECTED_CHANNEL_TIMEOUT".into());
+ }
+ let mut byte = [0];
+ match reader.read(&mut byte) {
+ Ok(0) => return Err("PROTECTED_CHANNEL_CLOSED".into()),
+ Ok(_) if byte[0] == b'\n' => {
+ let ack: Ack = serde_json::from_slice(&self.bytes)
+ .map_err(|_| "REGISTRATION_ACK_INVALID")?;
+ if ack.schema != "hiroute.protected-apply-ack/v2"
+ || ack.registration_id != self.id
+ || !ack.registered
+ {
+ return Err("REGISTRATION_ACK_MISMATCH".into());
+ }
+ return Ok(());
+ }
+ Ok(_) => {
+ if self.bytes.len() >= 1024 {
+ return Err("PROTECTED_CHANNEL_OVERSIZED".into());
+ }
+ self.bytes.push(byte[0]);
+ }
+ Err(error) if error.kind() == std::io::ErrorKind::Interrupted => {}
+ Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => {
+ std::thread::sleep(Duration::from_millis(5));
+ }
+ Err(_) => return Err("PROTECTED_CHANNEL_UNAVAILABLE".into()),
+ }
+ }
+ }
+}
+
+impl OwnedChild {
+ pub(super) fn release_input(&mut self, candidate_ref: &str) -> Result<(), String> {
+ let id = crate::random_id()?;
+ #[derive(serde::Serialize)]
+ struct Release<'a> {
+ schema: &'static str,
+ registration_id: &'a str,
+ candidate_ref: &'a str,
+ }
+ let mut bytes = Zeroizing::new(
+ serde_json::to_vec(&Release {
+ schema: "hiroute.protected-input/v1",
+ registration_id: &id,
+ candidate_ref,
+ })
+ .map_err(|_| "PROTECTED_INPUT_INVALID")?,
+ );
+ bytes.push(b'\n');
+ let result = self.exchange_ack(
+ &bytes,
+ &id,
+ hiroute_diagnostics::event::ProtectedExchangeKind::InputRelease,
+ );
+ if result.is_ok() {
+ self.manual_input_candidates.remove(candidate_ref);
+ } else {
+ self.authority_healthy = false;
+ }
+ result
+ }
+
+ pub(super) fn finish_pending_ack(&mut self) -> Result<(), String> {
+ let pending = self
+ .pending_ack
+ .as_mut()
+ .ok_or("AUTHORITY_RECOVERY_UNAVAILABLE")?;
+ let result = pending.receive(&mut self.ack, Duration::from_secs(2));
+ // Only a timeout can preserve a known request/reply boundary.
+ if !result
+ .as_ref()
+ .is_err_and(|error| error == "PROTECTED_CHANNEL_TIMEOUT")
+ {
+ self.pending_ack = None;
+ }
+ result
+ }
+
+ pub(super) fn resume_ack(&mut self) -> Result<(), String> {
+ let id = self
+ .pending_ack
+ .as_ref()
+ .ok_or("AUTHORITY_RECOVERY_UNAVAILABLE")?
+ .id
+ .clone();
+ let started = Instant::now();
+ let result = self.finish_pending_ack();
+ emit_exchange(
+ self.diagnostics.as_ref(),
+ ProtectedExchangeKind::Recovery,
+ ProtectedExchangePhase::AcknowledgementRead,
+ &id,
+ started,
+ result.as_ref().err(),
+ result.is_err(),
+ );
+ result
+ }
+
+ pub(super) fn exchange_ack(
+ &mut self,
+ bytes: &[u8],
+ id: &str,
+ kind: ProtectedExchangeKind,
+ ) -> Result<(), String> {
+ let started = Instant::now();
+ let mut phase = ProtectedExchangePhase::RequestWrite;
+ let result = (|| {
+ if self.pending_ack.is_some() {
+ return Err("TRUSTED_AUTHORITY_UNAVAILABLE".into());
+ }
+ write_frame(&mut self.capability, bytes)?;
+ self.pending_ack = Some(PendingAck::new(id));
+ phase = ProtectedExchangePhase::AcknowledgementRead;
+ self.finish_pending_ack()
+ })();
+ if result.is_err() {
+ self.authority_healthy = false;
+ }
+ emit_exchange(
+ self.diagnostics.as_ref(),
+ kind,
+ phase,
+ id,
+ started,
+ result.as_ref().err(),
+ result.is_err(),
+ );
+ result.map_err(|_| "TRUSTED_AUTHORITY_UNAVAILABLE".into())
+ }
+}
+
+pub(super) fn emit_exchange(
+ diagnostics: Option<&DiagnosticsPort>,
+ kind: ProtectedExchangeKind,
+ phase: ProtectedExchangePhase,
+ id: &str,
+ started: Instant,
+ error: Option<&String>,
+ authority_lost: bool,
+) {
+ let Some(diagnostics) = diagnostics else {
+ return;
+ };
+ let error = error.map(|error| match error.as_str() {
+ "PROTECTED_CHANNEL_TIMEOUT" => ProtectedExchangeError::Timeout,
+ "PROTECTED_CHANNEL_CLOSED" => ProtectedExchangeError::Closed,
+ "PROTECTED_CHANNEL_OVERSIZED" => ProtectedExchangeError::Oversized,
+ "REGISTRATION_ACK_INVALID" | "UPGRADE_ACK_INVALID" => ProtectedExchangeError::Invalid,
+ "REGISTRATION_ACK_MISMATCH" => ProtectedExchangeError::Mismatch,
+ _ => ProtectedExchangeError::Unavailable,
+ });
+ diagnostics
+ .handle()
+ .try_emit(DiagnosticEvent::ProtectedExchange(ProtectedExchange {
+ kind,
+ phase,
+ registration_token: diagnostics
+ .handle()
+ .token(CorrelationDomain::ProtectedRegistration, id),
+ elapsed_ms: started.elapsed().as_millis() as u64,
+ error,
+ authority_lost,
+ }));
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn partial_ack_bytes_survive_timeout_and_only_the_exact_reply_resumes() {
+ let (mut reader, mut writer) = pipe().unwrap();
+ nonblocking(&reader).unwrap();
+ let id = "a".repeat(64);
+ let frame = format!(
+ "{{\"schema\":\"hiroute.protected-apply-ack/v2\",\"registration_id\":\"{id}\",\"registered\":true}}\n"
+ );
+ writer.write_all(&frame.as_bytes()[..31]).unwrap();
+ let mut pending = PendingAck::new(&id);
+ assert_eq!(
+ pending
+ .receive(&mut reader, Duration::from_millis(20))
+ .unwrap_err(),
+ "PROTECTED_CHANNEL_TIMEOUT"
+ );
+ assert_eq!(pending.bytes.len(), 31);
+ writer.write_all(&frame.as_bytes()[31..]).unwrap();
+ pending
+ .receive(&mut reader, Duration::from_millis(20))
+ .unwrap();
+ }
+
+ #[test]
+ fn resynchronization_transfers_live_child_without_writing_another_request() {
+ let root = tempfile::tempdir().unwrap();
+ let mut resident = super::super::tests::recovery_resident(root.path(), false);
+ let (mut requests, writer) = pipe().unwrap();
+ let (reader, mut replies) = pipe().unwrap();
+ nonblocking(&requests).unwrap();
+ nonblocking(&reader).unwrap();
+ let owned = resident.owned.as_mut().unwrap();
+ owned.capability = writer;
+ owned.ack = reader;
+ let pid = owned.child.id();
+ let id = "b".repeat(64);
+ assert!(
+ owned
+ .exchange_ack(b"one complete request\n", &id, ProtectedExchangeKind::Grant)
+ .is_err()
+ );
+ assert_eq!(
+ read_frame(&mut requests, 1024, Duration::from_millis(20), None).unwrap(),
+ b"one complete request"
+ );
+ assert_eq!(
+ resident.recover_authority().err().unwrap(),
+ "AUTHORITY_RECOVERY_PENDING"
+ );
+ assert!(resident.owned.as_ref().unwrap().pending_ack.is_some());
+ replies.write_all(format!("{{\"schema\":\"hiroute.protected-apply-ack/v2\",\"registration_id\":\"{id}\",\"registered\":true}}\n").as_bytes()).unwrap();
+ let mut replacement = resident.recover_authority().unwrap();
+ assert!(replacement.has_authority());
+ assert!(!resident.has_authority());
+ assert_eq!(replacement.owned.as_ref().unwrap().child.id(), pid);
+ assert!(replacement.owned.as_ref().unwrap().shutdown.is_some());
+ assert_eq!(
+ read_frame(&mut requests, 1024, Duration::from_millis(20), None).unwrap_err(),
+ "PROTECTED_CHANNEL_TIMEOUT"
+ );
+ drop(resident);
+ assert!(
+ replacement
+ .owned
+ .as_mut()
+ .unwrap()
+ .child
+ .try_wait()
+ .unwrap()
+ .is_none()
+ );
+ assert!(acquire_host_lock(root.path()).is_err());
+ }
+ #[test]
+ fn a_conflicting_ack_invalidates_authority_and_late_success_is_never_consumed() {
+ let root = tempfile::tempdir().unwrap();
+ let mut resident = super::super::tests::recovery_resident(root.path(), false);
+ let (mut requests, request_writer) = pipe().unwrap();
+ let (reply_reader, mut replies) = pipe().unwrap();
+ nonblocking(&requests).unwrap();
+ nonblocking(&reply_reader).unwrap();
+ let owned = resident.owned.as_mut().unwrap();
+ owned.capability = request_writer;
+ owned.ack = reply_reader;
+ std::thread::scope(|scope| {
+ scope.spawn(move || {
+ let bytes = read_frame(&mut requests, 4096, Duration::from_secs(2), None).unwrap();
+ let request: serde_json::Value = serde_json::from_slice(&bytes).unwrap();
+ let conflicting = format!("{{\"schema\":\"hiroute.protected-apply-ack/v2\",\"registration_id\":\"{}\",\"registered\":true}}\n", "f".repeat(64));
+ write_frame(&mut replies, conflicting.as_bytes()).unwrap();
+ let late = format!("{{\"schema\":\"hiroute.protected-apply-ack/v2\",\"registration_id\":{},\"registered\":true}}\n", request["registration_id"]);
+ write_frame(&mut replies, late.as_bytes()).unwrap();
+ assert_eq!(read_frame(&mut requests, 4096, Duration::from_millis(100), None).unwrap_err(), "PROTECTED_CHANNEL_TIMEOUT");
+ });
+ let revisions = RevisionSetV1 {
+ target: 0,
+ dependencies: Default::default(),
+ };
+ for _ in 0..2 {
+ assert_eq!(
+ resident
+ .register_operation(
+ &CanonicalDigest::of_bytes(b"exact request"),
+ &revisions,
+ "ListSessionsV2"
+ )
+ .unwrap_err(),
+ "TRUSTED_AUTHORITY_UNAVAILABLE"
+ );
+ }
+ assert!(!resident.has_authority());
+ assert!(resident.owned.as_ref().unwrap().pending_ack.is_none());
+ assert!(resident.recover_authority().is_err());
+ });
+ }
+}
diff --git a/apps/desktop/src-tauri/src/bootstrap/channel_native_tests.rs b/apps/desktop/src-tauri/src/bootstrap/channel_native_tests.rs
new file mode 100644
index 00000000..89e837d5
--- /dev/null
+++ b/apps/desktop/src-tauri/src/bootstrap/channel_native_tests.rs
@@ -0,0 +1,239 @@
+//! Real Resident/daemon exchanges; synthetic private inputs, no user state.
+use super::*;
+use hiroute_application_api::ClientServiceStatusV1;
+use hiroute_product_session::HostAuthority;
+
+fn daemon() -> PathBuf {
+ let build = Command::new("cargo")
+ .args([
+ "build",
+ "--locked",
+ "-p",
+ "hiroute-daemon",
+ "--bin",
+ "hirouted",
+ ])
+ .current_dir(Path::new(env!("CARGO_MANIFEST_DIR")).join("../../.."))
+ .output()
+ .unwrap();
+ assert!(
+ build.status.success(),
+ "daemon prerequisite: {}",
+ String::from_utf8_lossy(&build.stderr)
+ );
+ std::env::current_exe()
+ .unwrap()
+ .parent()
+ .unwrap()
+ .parent()
+ .unwrap()
+ .join("hirouted")
+}
+
+struct Paused(nix::unistd::Pid);
+impl Paused {
+ fn new(pid: u32) -> Self {
+ let pid = nix::unistd::Pid::from_raw(pid as i32);
+ nix::sys::signal::kill(pid, nix::sys::signal::Signal::SIGSTOP).unwrap();
+ std::thread::sleep(Duration::from_millis(50));
+ Self(pid)
+ }
+}
+impl Drop for Paused {
+ fn drop(&mut self) {
+ let _ = nix::sys::signal::kill(self.0, nix::sys::signal::Signal::SIGCONT);
+ }
+}
+
+#[test]
+fn live_daemon_after_ack_timeout_does_not_report_a_healthy_native_session() {
+ let root = tempfile::Builder::new()
+ .prefix("hr187-")
+ .tempdir_in(std::fs::canonicalize("/tmp").unwrap())
+ .unwrap();
+ let mut resident = Resident::open(root.path(), &daemon()).unwrap();
+ let runtime = tokio::runtime::Runtime::new().unwrap();
+ let before = runtime
+ .block_on(resident.client.query::<_, ClientServiceStatusV1>(
+ "GetClientServiceStatus",
+ "before-fault",
+ &serde_json::json!({}),
+ ))
+ .unwrap()
+ .data
+ .unwrap();
+ let paused = Paused::new(resident.owned.as_ref().unwrap().child.id());
+ let started = Instant::now();
+ assert!(
+ resident
+ .register_operation(
+ &CanonicalDigest::of_bytes(b"timeout witness"),
+ &before.revisions,
+ "ListSessionsV2"
+ )
+ .is_err()
+ );
+ assert!(started.elapsed() >= Duration::from_secs(2));
+ assert!(started.elapsed() < Duration::from_secs(4));
+ drop(paused);
+ let after = runtime
+ .block_on(resident.client.query::<_, ClientServiceStatusV1>(
+ "GetClientServiceStatus",
+ "after-fault",
+ &serde_json::json!({}),
+ ))
+ .unwrap()
+ .data
+ .unwrap();
+ assert!(after.recovery_ready);
+ assert_eq!(before.revisions, after.revisions);
+ let mut session = crate::session_from_resident(resident);
+ let request = || {
+ serde_json::from_value(serde_json::json!({
+ "schema":"hiroute.observation.query/v2", "intent":{"view":"status","query":{}}
+ }))
+ .unwrap()
+ };
+ for _ in 0..2 {
+ let error = runtime
+ .block_on(session.observation_read(request()))
+ .unwrap_err();
+ assert!(
+ matches!(error, hiroute_product_session::failure::DesktopFailure::Native { ref code } if code == "TRUSTED_AUTHORITY_UNAVAILABLE")
+ );
+ }
+ let snapshot = runtime.block_on(session.snapshot()).unwrap();
+ assert!(
+ !snapshot.trusted_authority,
+ "a live service does not prove a usable native authority"
+ );
+}
+
+#[test]
+fn fresh_native_session_resynchronizes_without_restarting_the_daemon() {
+ let root = tempfile::Builder::new()
+ .prefix("hr187-")
+ .tempdir_in(std::fs::canonicalize("/tmp").unwrap())
+ .unwrap();
+ let binary = daemon();
+ let mut resident = Resident::open(root.path(), &binary).unwrap();
+ let runtime = tokio::runtime::Runtime::new().unwrap();
+ let before = runtime
+ .block_on(resident.client.query::<_, ClientServiceStatusV1>(
+ "GetClientServiceStatus",
+ "before-recovery",
+ &serde_json::json!({}),
+ ))
+ .unwrap()
+ .data
+ .unwrap();
+ let previous = resident.owned.as_ref().unwrap().child.id();
+ let paused = Paused::new(previous);
+ assert!(
+ resident
+ .register_operation(
+ &CanonicalDigest::of_bytes(b"late old registration"),
+ &before.revisions,
+ "ListSessionsV2"
+ )
+ .is_err()
+ );
+ drop(paused);
+ // The daemon writes the original success ACK after the caller's absolute timeout.
+ // Recovery consumes only this exact pending ACK, then creates a new host session.
+ std::thread::sleep(Duration::from_millis(100));
+ let replacement = resident.recover_authority().unwrap();
+ assert_eq!(replacement.owned.as_ref().unwrap().child.id(), previous);
+ assert!(
+ !resident.has_authority(),
+ "captured old authority cannot authorize after replacement"
+ );
+ assert!(
+ acquire_host_lock(root.path()).is_err(),
+ "replacement retains the original host lease"
+ );
+ let mut session = crate::session_from_resident(replacement);
+ let snapshot = runtime.block_on(session.snapshot()).unwrap();
+ assert!(snapshot.trusted_authority);
+ assert_eq!(snapshot.service.revisions, before.revisions);
+ assert_eq!(
+ snapshot.native_connection,
+ Some(hiroute_product_session::NativeConnectionStatus::Ready)
+ );
+ let request = serde_json::from_value(serde_json::json!({
+ "schema":"hiroute.observation.query/v2", "intent":{"view":"status","query":{}}
+ }))
+ .unwrap();
+ assert!(runtime.block_on(session.observation_read(request)).is_ok());
+ let candidate = session
+ .authority
+ .register_model_input(Zeroizing::new("synthetic recovered input".into()))
+ .unwrap();
+ session.authority.release_model_input(&candidate).unwrap();
+ assert!(!resident.has_authority());
+ assert!(
+ resident
+ .register_operation(
+ &CanonicalDigest::of_bytes(b"old callback"),
+ &before.revisions,
+ "ListSessionsV2"
+ )
+ .is_err(),
+ "captured old authority must not regain grant issuance"
+ );
+ assert!(
+ runtime
+ .block_on(resident.client.query::<_, ClientServiceStatusV1>(
+ "GetClientServiceStatus",
+ "same-daemon-still-responsive",
+ &serde_json::json!({})
+ ))
+ .is_ok()
+ );
+}
+
+#[test]
+fn resynchronization_releases_an_input_whose_registration_finished_after_timeout() {
+ let root = tempfile::Builder::new()
+ .prefix("hr187-input-")
+ .tempdir_in(std::fs::canonicalize("/tmp").unwrap())
+ .unwrap();
+ let mut resident = Resident::open(root.path(), &daemon()).unwrap();
+ let pid = resident.owned.as_ref().unwrap().child.id();
+ let candidate = ComputeCandidateRefV2 {
+ candidate_ref: format!("candidate/native/{}", crate::random_id().unwrap()),
+ candidate_revision: 1,
+ };
+ let paused = Paused::new(pid);
+ assert!(
+ resident
+ .register_model_input_once(&candidate, "synthetic abandoned input")
+ .is_err()
+ );
+ assert!(
+ resident
+ .owned
+ .as_ref()
+ .unwrap()
+ .manual_input_candidates
+ .contains(&candidate.candidate_ref)
+ );
+ drop(paused);
+ let mut replacement = resident.recover_authority().unwrap();
+ assert_eq!(replacement.owned.as_ref().unwrap().child.id(), pid);
+ assert!(
+ replacement
+ .owned
+ .as_ref()
+ .unwrap()
+ .manual_input_candidates
+ .is_empty()
+ );
+ // Reusing this private test identity would fail if the late registration's
+ // protected input remained in the daemon registry.
+ replacement
+ .register_model_input_once(&candidate, "synthetic fresh input")
+ .unwrap();
+ replacement.release_model_input(&candidate).unwrap();
+ assert!(!resident.has_authority());
+}
diff --git a/apps/desktop/src-tauri/src/bootstrap/recovery.rs b/apps/desktop/src-tauri/src/bootstrap/recovery.rs
new file mode 100644
index 00000000..cc1d88db
--- /dev/null
+++ b/apps/desktop/src-tauri/src/bootstrap/recovery.rs
@@ -0,0 +1,112 @@
+//! Resume only the exact outstanding reply, then transfer ownership to a fresh
+//! Desktop session. No daemon stop, admission pause, new pipe or business replay.
+use super::*;
+
+impl Resident {
+ pub(crate) fn native_connection(&mut self) -> hiroute_product_session::NativeConnectionStatus {
+ use hiroute_product_session::NativeConnectionStatus as Status;
+ if self.has_authority() {
+ return Status::Ready;
+ }
+ let Some(owned) = self.owned.as_mut() else {
+ return Status::NotOwned;
+ };
+ if owned.shutdown.is_some()
+ && owned.pending_ack.is_some()
+ && matches!(owned.child.try_wait(), Ok(None))
+ {
+ Status::RecoveryRequired
+ } else {
+ Status::RestartRequired
+ }
+ }
+
+ #[cfg(any(test, all(target_os = "macos", feature = "desktop-runtime")))]
+ pub(crate) fn recover_authority(&mut self) -> Result<Self, String> {
+ if self.has_authority() {
+ return Err("AUTHORITY_RECOVERY_NOT_NEEDED".into());
+ }
+ let lock = self
+ ._lock
+ .try_clone()
+ .map_err(|_| "HOST_LOCK_UNAVAILABLE")?;
+ let owned = self.owned.as_mut().ok_or("AUTHORITY_RECOVERY_NOT_OWNED")?;
+ if owned.shutdown.is_none() || !matches!(owned.child.try_wait(), Ok(None)) {
+ return Err("AUTHORITY_RECOVERY_UNAVAILABLE".into());
+ }
+ owned.resume_ack().map_err(|error| {
+ if error == "PROTECTED_CHANNEL_TIMEOUT" {
+ "AUTHORITY_RECOVERY_PENDING"
+ } else {
+ "AUTHORITY_RECOVERY_UNAVAILABLE"
+ }
+ .to_owned()
+ })?;
+ // No old session may retain an abandoned or uncertain protected input.
+ for candidate_ref in owned.manual_input_candidates.clone() {
+ owned.release_input(&candidate_ref)?;
+ }
+ owned.authority_healthy = true;
+ // Captured old NativeAuthority instances keep this empty Resident. They
+ // cannot mint fresh grants even though the daemon and its PID are unchanged.
+ Ok(Self {
+ client: self.client.clone(),
+ owned: self.owned.take(),
+ _lock: lock,
+ })
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn recovery_never_takes_authority_from_an_external_owner() {
+ let root = tempfile::tempdir().unwrap();
+ let mut resident = Resident {
+ client: Client::new(
+ "hiroute-desktop",
+ LocalEndpoint::from_runtime_root(root.path()),
+ ),
+ owned: None,
+ _lock: acquire_host_lock(root.path()).unwrap(),
+ };
+ assert_eq!(
+ resident.native_connection(),
+ hiroute_product_session::NativeConnectionStatus::NotOwned
+ );
+ assert_eq!(
+ resident.recover_authority().err().unwrap(),
+ "AUTHORITY_RECOVERY_NOT_OWNED"
+ );
+ }
+
+ #[test]
+ fn an_unframed_or_closed_channel_has_no_in_place_recovery() {
+ let root = tempfile::tempdir().unwrap();
+ let mut resident = super::super::tests::recovery_resident(root.path(), false);
+ resident.owned.as_mut().unwrap().authority_healthy = false;
+ let pid = resident.owned.as_ref().unwrap().child.id();
+ assert_eq!(
+ resident.native_connection(),
+ hiroute_product_session::NativeConnectionStatus::RestartRequired
+ );
+ assert_eq!(
+ resident.recover_authority().err().unwrap(),
+ "AUTHORITY_RECOVERY_UNAVAILABLE"
+ );
+ assert_eq!(resident.owned.as_ref().unwrap().child.id(), pid);
+ assert!(
+ resident
+ .owned
+ .as_mut()
+ .unwrap()
+ .child
+ .try_wait()
+ .unwrap()
+ .is_none()
+ );
+ assert!(resident.owned.as_ref().unwrap().shutdown.is_some());
+ }
+}
diff --git a/apps/desktop/src-tauri/src/bootstrap/tests.rs b/apps/desktop/src-tauri/src/bootstrap/tests.rs
index bb9940b8..693443a3 100644
--- a/apps/desktop/src-tauri/src/bootstrap/tests.rs
+++ b/apps/desktop/src-tauri/src/bootstrap/tests.rs
@@ -1,6 +1,6 @@
use super::*;
-fn recovery_resident(root: &Path, slow: bool) -> Resident {
+pub(super) fn recovery_resident(root: &Path, slow: bool) -> Resident {
let (reader, writer) = pipe().unwrap();
let (_, capability) = pipe().unwrap();
let (ack, _) = pipe().unwrap();
@@ -24,6 +24,7 @@ fn recovery_resident(root: &Path, slow: bool) -> Resident {
capability,
ack,
authority_healthy: true,
+ pending_ack: None,
manual_input_candidates: BTreeSet::new(),
diagnostics: None,
}),
@@ -125,6 +126,7 @@ fn upgrade_prepare_status_cancel_exchange_complete_correlated_frames() {
capability,
ack,
authority_healthy: true,
+ pending_ack: None,
manual_input_candidates: BTreeSet::new(),
diagnostics: None,
}),
diff --git a/apps/desktop/src-tauri/src/bridge.rs b/apps/desktop/src-tauri/src/bridge.rs
index a177a780..9ceec22b 100644
--- a/apps/desktop/src-tauri/src/bridge.rs
+++ b/apps/desktop/src-tauri/src/bridge.rs
@@ -49,7 +49,9 @@ mod host_settings;
mod subscription_proxy;
use host_settings::*;
use subscription_proxy::*;
+mod connection_recovery;
mod startup;
+use connection_recovery::*;
pub use diagnostics::DiagnosticsState;
pub use startup::StartupState;
use startup::*;
@@ -853,6 +855,7 @@ pub fn run() {
quit_desktop,
diagnostic_status,
startup_status,
+ recover_native_connection,
open_startup_recovery_directory,
update_status,
update_check,
diff --git a/apps/desktop/src-tauri/src/bridge/connection_recovery.rs b/apps/desktop/src-tauri/src/bridge/connection_recovery.rs
new file mode 100644
index 00000000..f2465f03
--- /dev/null
+++ b/apps/desktop/src-tauri/src/bridge/connection_recovery.rs
@@ -0,0 +1,26 @@
+//! One main-window recovery action; no path, command, grant or principal comes from IPC.
+use super::*;
+
+#[tauri::command]
+pub(super) async fn recover_native_connection(
+ window: WebviewWindow,
+ state: State<'_, DesktopState>,
+) -> Result<(), DesktopFailure> {
+ main_window(&window)?;
+ let handle = window.app_handle();
+ // Expire prompts before waiting for the session lock, including callbacks already accepted.
+ expire_window_confirmations(handle, window.label());
+ let mut sessions = state.0.clone().lock_owned().await;
+ tokio::task::spawn_blocking(move || {
+ let current = sessions.as_mut().ok_or("RESIDENT_UNAVAILABLE")?;
+ current.invalidate_confirmation();
+ let mut native = crate::bootstrap::resident(current)?;
+ let replacement = native.recover_authority()?;
+ drop(native);
+ *sessions = Some(crate::session_from_resident(replacement));
+ Ok::<_, String>(())
+ })
+ .await
+ .map_err(|_| "AUTHORITY_RECOVERY_UNAVAILABLE")??;
+ Ok(())
+}
diff --git a/apps/desktop/src-tauri/src/bridge_command_acl_tests.rs b/apps/desktop/src-tauri/src/bridge_command_acl_tests.rs
index add675b1..50ee650f 100644
--- a/apps/desktop/src-tauri/src/bridge_command_acl_tests.rs
+++ b/apps/desktop/src-tauri/src/bridge_command_acl_tests.rs
@@ -51,7 +51,11 @@ const DIAGNOSTIC_COMMANDS: &[&str] = &[
"set_diagnostic_level",
"open_diagnostic_directory",
];
-const STARTUP_COMMANDS: &[&str] = &["startup_status", "open_startup_recovery_directory"];
+const STARTUP_COMMANDS: &[&str] = &[
+ "startup_status",
+ "open_startup_recovery_directory",
+ "recover_native_connection",
+];
const CONFIRMATION_COMMANDS: &[&str] = &["web_confirmation_snapshot", "resolve_web_confirmation"];
const EXTERNAL_URL_COMMANDS: &[&str] = &["open_external_url"];
const WINDOW_BEHAVIOR_COMMANDS: &[&str] = &["perform_titlebar_double_click"];
diff --git a/apps/desktop/src/features/Sessions.tsx b/apps/desktop/src/features/Sessions.tsx
index 06f38130..21bfe4bc 100644
--- a/apps/desktop/src/features/Sessions.tsx
+++ b/apps/desktop/src/features/Sessions.tsx
@@ -6,6 +6,7 @@ import type { CorrelationKind } from './session-correlation';
import { readableEvent, excerpt, excerptAround, groupToolEvents, contentDisplayRuns, coalesceResponseText, isPrivateContentKind, isTechnicalContentKind, summarizeToolArguments, type ReadableEvent } from './session-content';
import { firstRealUserText, splitLeadingAgentContext } from './session-title';
import { formatCacheHit, formatCacheHitCoverage, formatTokenCount, usageValue, type CacheHitSummary, type UsageMetric } from './usage-presentation';
+import { nativeConnectionReadText } from '../native-connection';
import { safeDiagnosticCode } from '../error-code';
import { observationRead as read } from './observation-client';
import { PlanQuality } from './PlanQuality';
@@ -292,7 +293,7 @@ export function Sessions({ initialSession = null, initialRequest = null, languag
{!listLoaded && listBusy && <div className="empty-state" role="status"><div><span className="oc-spinner" /><p>{text('正在读取本机会话…', 'Reading local sessions…')}</p></div></div>}
<MaintenanceStatus key={reload} language={language} />
- {!listLoaded && listError && !keyword.trim() ? <div className="empty-state"><div><span className="empty-icon"><UiIcon name="warning" /></span><h3>{text('暂时无法读取会话', 'Sessions are temporarily unavailable')}</h3><p>{text('请确认本机服务正在运行,然后重试。', 'Make sure the local service is running, then retry.')}</p><button className="btn btn-primary" type="button" onClick={refresh}>{text('重试', 'Retry')}</button></div></div> : !listLoaded && listBusy ? null : emptyFirstUse ? <div className="empty-state"><div><span className="empty-icon"><UiIcon name="sessions" /></span><h3>{text('还没有会话记录', 'No sessions yet')}</h3><p>{text('在已接入的 Agent 中开始使用,经过 HiRoute 的会话会显示在这里。', 'Start in a connected Agent. Sessions routed through HiRoute will appear here.')}</p>{onOpenAgents && <button className="btn btn-primary" type="button" onClick={onOpenAgents}>{text('查看 Agent 接入', 'View Agent connections')}</button>}</div></div> : <div className={`session-layout${session ? ' has-selection' : ''}${factsOpen ? ' with-inspector' : ''}${keyword.trim() ? ' is-searching' : ''}${listError ? ' with-list-error' : ''}`}>
+ {!listLoaded && listError && !keyword.trim() ? <div className="empty-state"><div><span className="empty-icon"><UiIcon name="warning" /></span><h3>{text('暂时无法读取会话', 'Sessions are temporarily unavailable')}</h3><p>{nativeConnectionReadText(listError, language) ?? text('请确认本机服务正在运行,然后重试。', 'Make sure the local service is running, then retry.')}</p><button className="btn btn-primary" type="button" onClick={refresh}>{text('重试', 'Retry')}</button></div></div> : !listLoaded && listBusy ? null : emptyFirstUse ? <div className="empty-state"><div><span className="empty-icon"><UiIcon name="sessions" /></span><h3>{text('还没有会话记录', 'No sessions yet')}</h3><p>{text('在已接入的 Agent 中开始使用,经过 HiRoute 的会话会显示在这里。', 'Start in a connected Agent. Sessions routed through HiRoute will appear here.')}</p>{onOpenAgents && <button className="btn btn-primary" type="button" onClick={onOpenAgents}>{text('查看 Agent 接入', 'View Agent connections')}</button>}</div></div> : <div className={`session-layout${session ? ' has-selection' : ''}${factsOpen ? ' with-inspector' : ''}${keyword.trim() ? ' is-searching' : ''}${listError ? ' with-list-error' : ''}`}>
<aside className="session-master" aria-label={text('会话列表', 'Session list')}>
<form onSubmit={event => { event.preventDefault(); void load(); }} className="session-filters">
<label className="search-box"><span className="sr-only">{text('搜索会话正文', 'Search session content')}</span><UiIcon name="search" /><input className="input" value={keyword} maxLength={256} onChange={event => { generation.current++; clearTimelineSelection(); setSearchCursor(null); setSessionCursor(null); setHits([]); setPartial(false); setListError(''); setListBusy(true); setKeyword(event.target.value); }} placeholder={text('搜索会话正文', 'Search session content')} /></label>
@@ -321,7 +322,7 @@ export function Sessions({ initialSession = null, initialRequest = null, languag
<div className="oc-model-back"><button className="btn btn-quiet" type="button" onClick={() => { timelineGeneration.current++; factGeneration.current++; setSession(null); setRequest(null); setFactsOpen(false); if (!listLoaded) void load(); }}><UiIcon name="arrowLeft" />{text('返回会话列表', 'Back to sessions')}</button></div>
<header className="transcript-head"><div><h2><ContentExcerpt session={session} language={language} fallback={text('会话正文', 'Conversation')} limit={56} revision={refreshVersion + reload} onModel={model => setSessionModels(current => current[session] === model ? current : { ...current, [session]: model })} onRoute={route => setSessionRoutes(current => current[session] === route ? current : { ...current, [session]: route })} /></h2><p>{[agentName(selectedSummary?.agent_id), sessionRoutes[session], selectedSummary ? sessionTimeLabel(selectedSummary.last_request_at_ms, language) : undefined].filter(Boolean).join(' · ')}</p></div><div className="transcript-actions">{routed && <div className="segmented session-view-tabs" role="group" aria-label={text('会话视图', 'Session view')}>{([['timeline', text('路由时间线', 'Routing timeline')], ['conversation', text('对话', 'Conversation')]] as const).map(([value, label]) => <button key={value} type="button" className={`segment${pane === value ? ' active' : ''}`} aria-pressed={pane === value} onClick={() => setSessionView(value)}>{label}</button>)}</div>}<button className="btn" type="button" disabled={!request} onClick={() => factsOpen ? setFactsOpen(false) : openFacts()}><UiIcon name="activity" />{factsOpen ? text('收起运行记录', 'Hide run record') : text('运行记录', 'Run record')}</button>{!factsOpen && <button className="icon-btn" type="button" aria-label={text('清理此会话', 'Clear this session')} disabled={busy} onClick={() => { setCleanupError(''); setCleanupOpen(true); }}><UiIcon name="trash" /></button>}</div></header>
{focusedRequest && focusedRequest === request && <div className="callout session-detail-feedback session-request-focus" data-request-id={focusedRequest} role="status"><UiIcon name="activity" /><div><strong>{selectedRequest ? text('已定位所选请求', 'Selected request') : timelineError ? text('所选请求不可用', 'Selected request unavailable') : text('正在定位所选请求…', 'Locating selected request…')}</strong>{selectedRequest && <p>{new Date(selectedRequest.started_at_ms).toLocaleString(language === 'zh' ? 'zh-CN' : 'en')}{selectedRequest.final_native_model && ' · ' + selectedRequest.final_native_model}<br />{text('下方包含本次请求的历史对话和回复。', 'The content below includes this request’s conversation history and response.')}</p>}</div><button className="btn" type="button" onClick={() => void timeline(session)}>{text('查看完整会话', 'View full session')}</button></div>}
- {timelineError && <div className="callout bad session-detail-feedback" role="alert" data-error-code={timelineError}><UiIcon name="warning" /><div><strong>{text('会话详情没有刷新', 'The session details were not refreshed')}</strong><p>{requests.length ? text('已加载的请求仍然保留。', 'Previously loaded requests are still available.') : text('暂时无法读取这条会话。', 'This session is temporarily unavailable.')}</p><button className="btn" type="button" onClick={() => void timeline(session, null, undefined, focusedRequest)}>{text('重试', 'Retry')}</button></div></div>}
+ {timelineError && <div className="callout bad session-detail-feedback" role="alert" data-error-code={timelineError}><UiIcon name="warning" /><div><strong>{text('会话详情没有刷新', 'The session details were not refreshed')}</strong><p>{nativeConnectionReadText(timelineError, language) ?? (requests.length ? text('已加载的请求仍然保留。', 'Previously loaded requests are still available.') : text('暂时无法读取这条会话。', 'This session is temporarily unavailable.'))}</p><button className="btn" type="button" onClick={() => void timeline(session, null, undefined, focusedRequest)}>{text('重试', 'Retry')}</button></div></div>}
<div className={`session-routing-and-conversation show-${pane}`}>
<Disclosure className="native-details session-model-performance" label={text('本会话的模型表现', 'Model performance in this session')} language={language} onOpenChange={setQualityOpen}><PlanQuality key={session} sessionId={session} language={language} compact active={active && qualityOpen} refreshVersion={refreshVersion + reload} onOpenEvidence={(targetSession, targetRequest) => void timeline(targetSession, null, undefined, targetRequest)} /></Disclosure>
<div className="session-pane" hidden={pane !== 'timeline'}><RoutingTimeline key={session} session={session} language={language} active={active} displayed={pane === 'timeline'} refreshVersion={refreshVersion + reload} requestId={routingRequestId} onOpenPerformance={setQualityPlan} onAvailability={setRouting} onSelectRequest={selectTimelineRequest} onViewConversation={item => { selectTimelineRequest(item); setSessionView('conversation'); }} /></div>
diff --git a/apps/desktop/src/features/home/Home.tsx b/apps/desktop/src/features/home/Home.tsx
index df2ebc58..2d6d60a4 100644
--- a/apps/desktop/src/features/home/Home.tsx
+++ b/apps/desktop/src/features/home/Home.tsx
@@ -1,3 +1,4 @@
+import { nativeConnectionReadText } from '../../native-connection';
import { TrustAttention } from '../trust/TrustAttention';
import type { TrustSuggestionsRead } from '../trust/use-trust-suggestions';
import { useState, type ReactNode } from 'react';
@@ -54,7 +55,7 @@ export function Home({ language, reads, onAction, hasTasks = false, trustSuggest
const attention = trustSuggestions && <TrustAttention onAct={onTrustAction} read={trustSuggestions} language={language} names={Object.fromEntries((plans?.plans ?? []).map(plan => [plan.planId, plan.displayName]))} onOpen={planId => onAction({kind:'open-plan',returnTo:'home',planId,performance:true})} />;
return <ProductPage title={text('首页', 'Home')} subtitle={recent.length ? text('近期使用与需要你处理的事', 'Recent work and things that need your attention') : undefined}>
<div className="home-wrap v3-home" data-home-mode={mode}>
- {!!errors.length && <div className="callout bad home-read-error" role="alert"><UiIcon name="warning" /><div><strong>{text('部分信息暂时无法读取', 'Some information is temporarily unavailable')}</strong><p>{text('已有数据会保留;首次读取完成前不会把当前状态当作首次使用。', 'Existing data is retained. The app will not treat this as first use until the initial reads finish.')}</p><div className="actions">{errors.map(domain => <button className="btn btn-quiet" key={domain} type="button" onClick={() => onAction({kind:'retry-read', domain})}>{text('重试', 'Retry')} {domainLabels[domain]}</button>)}</div></div></div>}
+ {!!errors.length && <div className="callout bad home-read-error" role="alert"><UiIcon name="warning" /><div><strong>{text('部分信息暂时无法读取', 'Some information is temporarily unavailable')}</strong><p>{errors.map(domain => reads[domain]).map(read => read.status === 'error' ? nativeConnectionReadText(read.code, language) : undefined).find(Boolean) ?? text('已有数据会保留;首次读取完成前不会把当前状态当作首次使用。', 'Existing data is retained. The app will not treat this as first use until the initial reads finish.')}</p><div className="actions">{errors.map(domain => <button className="btn btn-quiet" key={domain} type="button" onClick={() => onAction({kind:'retry-read', domain})}>{text('重试', 'Retry')} {domainLabels[domain]}</button>)}</div></div></div>}
{unresolvedRequiredRead && !recent.length ? <section className="surface v3-ready"><UiIcon name="warning" /><div><strong>{text('暂时无法确认当前配置', 'Current setup cannot be confirmed')}</strong><p>{text('请先重试上方读取;确认实际状态后再继续配置。', 'Retry the reads above before changing setup.')}</p></div></section> : mode === 'loading' && !recent.length ? <div className="oc-status-row" role="status"><span className="oc-spinner" /><span>{text('正在读取本机配置与记录…', 'Reading local configuration and records…')}</span></div> : activityPending && !recent.length ? <div className="oc-status-row" role="status"><span className="oc-spinner" /><span>{text('正在确认会话记录…', 'Checking session records…')}</span></div> : !recent.length ? <>
<section className="v3-welcome"><div className="eyebrow"><UiIcon name="route" />{text('模型与 Agent 的智能路由', 'Smart routing for models and agents')}</div>
<h1>{complete ? text('准备好了,回到你常用的 Agent', 'Ready. Open your usual agent.') : text('让合适的模型和 Agent\n处理合适的任务', 'The right models and agents\nfor each task')}</h1>
diff --git a/apps/desktop/src/features/home/state.ts b/apps/desktop/src/features/home/state.ts
index e1da5bda..85a81ceb 100644
--- a/apps/desktop/src/features/home/state.ts
+++ b/apps/desktop/src/features/home/state.ts
@@ -64,7 +64,7 @@ export function visibleData<T>(read: HomeRead<T>): T | undefined {
}
export function deriveHomeServiceStatus(read: HomeRead<HomeService>): {
- state: 'ready' | 'read_only' | 'unavailable' | 'unknown';
+ state: 'ready' | 'read_only' | 'connection_lost' | 'unavailable' | 'unknown';
operational: boolean;
} {
if (read.status !== 'ready') {
@@ -74,10 +74,10 @@ export function deriveHomeServiceStatus(read: HomeRead<HomeService>): {
const running = service.daemon === 'running'
&& ['ready', 'empty', 'no_new_calls'].includes(service.gateway);
return {
- state: service.daemon === 'read_only' ? 'read_only'
+ state: service.nativeConnectionLost ? 'connection_lost' : service.daemon === 'read_only' ? 'read_only'
: service.daemon === 'unavailable' ? 'unavailable'
: running ? 'ready' : 'unknown',
- operational: running && Boolean(service.recoveryReady),
+ operational: running && Boolean(service.recoveryReady) && !service.nativeConnectionLost,
};
}
diff --git a/apps/desktop/src/features/home/types.ts b/apps/desktop/src/features/home/types.ts
index 4f97dcb0..35ff3622 100644
--- a/apps/desktop/src/features/home/types.ts
+++ b/apps/desktop/src/features/home/types.ts
@@ -11,6 +11,7 @@ export type HomeRead<T> =
| { status: 'error'; code: string; message?: string; previous?: T; retryable?: boolean };
export type HomeService = {
+ nativeConnectionLost?: boolean;
daemon: 'running' | 'starting' | 'unavailable' | 'read_only' | 'unknown';
gateway: 'ready' | 'empty' | 'no_new_calls' | 'unavailable' | 'unknown';
recoveryReady: boolean | null;
diff --git a/apps/desktop/src/host/index.ts b/apps/desktop/src/host/index.ts
index 713bfe37..7113d132 100644
--- a/apps/desktop/src/host/index.ts
+++ b/apps/desktop/src/host/index.ts
@@ -1,6 +1,7 @@
import { browserCapabilities, type HostCapabilities, type HostKind, type HostTransport } from './types.ts';
import { consoleTransport, consoleCapabilities } from './console.ts';
import type { WebConfirmationRequest } from '../features/web-confirmation.ts';
+import { nativeConnectionLost } from '../native-connection.ts';
import type { ThemePreference, ResolvedTheme } from '../ui/preferences';
export type { HostCapabilities, HostKind, HostTransport } from './types.ts';
export { plaintextConsole } from './console.ts';
@@ -46,7 +47,7 @@ async function browserCall(command: string, args: Record<string, unknown>): Prom
}
return consoleTransport.call(command, args);
}
-export async function invoke<T>(command: string, args: Record<string, unknown> = {}): Promise<T> {
+async function invokeHost<T>(command: string, args: Record<string, unknown> = {}): Promise<T> {
if (override) {
if (override.capabilities().host === 'console' && ['open_external_url', 'save_classifier_openapi', 'open_diagnostic_directory', 'open_startup_recovery_directory'].includes(command)) return browserCall(command, args) as Promise<T>;
return override.call<T>(command, args);
@@ -55,6 +56,13 @@ export async function invoke<T>(command: string, args: Record<string, unknown> =
if (hostKind() === 'shell-console' && (command.startsWith('update_') || command.startsWith('login_start_') || ['open_external_url', 'save_classifier_openapi', 'open_in_browser', 'restart_service', 'reconnect'].includes(command))) return (await import('@tauri-apps/api/core')).invoke<T>(`shell_${command}`, args);
return browserCall(command, args) as Promise<T>;
}
+export async function invoke<T>(command: string, args: Record<string, unknown> = {}): Promise<T> {
+ try { return await invokeHost<T>(command, args); }
+ catch (error) {
+ if (hostKind() === 'tauri' && nativeConnectionLost(error)) window.dispatchEvent(new Event('hiroute-native-connection-unavailable'));
+ throw error;
+ }
+}
export async function listenForHostConfirmations(onRequest: (request: WebConfirmationRequest) => void): Promise<() => void> { return hostKind() === 'tauri' ? (await import('./tauri.ts')).listenNativeConfirmation(onRequest) : () => {}; }
export async function syncHostTheme(preference: ThemePreference, resolved: ResolvedTheme): Promise<'skipped' | 'synced'> { if (hostKind() !== 'tauri') return 'skipped'; await (await import('./tauri.ts')).syncNativeTheme(preference, resolved); return 'synced'; }
export async function nativeClipboard(value: string): Promise<boolean> { if (hostKind() !== 'tauri') return false; return (await import('./tauri.ts')).writeNativeClipboard(value); }
diff --git a/apps/desktop/src/native-connection.ts b/apps/desktop/src/native-connection.ts
new file mode 100644
index 00000000..a0b41c11
--- /dev/null
+++ b/apps/desktop/src/native-connection.ts
@@ -0,0 +1,14 @@
+import { safeDiagnosticCode } from './error-code.ts';
+
+export type NativeConnectionStatus = 'ready' | 'recovery_required' | 'restart_required' | 'not_owned';
+
+export function nativeConnectionLost(error: unknown): boolean {
+ return ['TRUSTED_AUTHORITY_UNAVAILABLE', 'PROTECTED_CHANNEL_TIMEOUT', 'PROTECTED_CHANNEL_CLOSED', 'PROTECTED_CHANNEL_UNAVAILABLE', 'REGISTRATION_ACK_INVALID', 'REGISTRATION_ACK_MISMATCH'].includes(safeDiagnosticCode(error, ''));
+}
+
+export function nativeConnectionReadText(error: unknown, language: 'zh' | 'en'): string | undefined {
+ if (!nativeConnectionLost(error)) return;
+ return language === 'zh'
+ ? '本机可信连接已失效,暂时无法读取记录。请查看页面上方的连接恢复提示。'
+ : 'The trusted local connection was lost, so records cannot be read. Follow the connection recovery guidance above.';
+}
diff --git a/apps/desktop/src/occami/styles/components.css b/apps/desktop/src/occami/styles/components.css
index 49a4f4e7..e151bf7d 100644
--- a/apps/desktop/src/occami/styles/components.css
+++ b/apps/desktop/src/occami/styles/components.css
@@ -440,6 +440,9 @@
.callout.bad { border-color: color-mix(in srgb, var(--red) 22%, transparent); background: var(--red-soft); }
.callout.bad .icon { color: var(--red); }
.main > div.startup-recovery:not([hidden]) { height: auto; min-height: auto; flex: 0 0 auto; }
+.main > div.native-connection-recovery:not([hidden]) { height: auto; min-height: auto; flex: 0 0 auto; flex-wrap: wrap; }
+.native-connection-recovery > div { flex: 1 1 20rem; min-width: 0; overflow-wrap: anywhere; }
+.native-connection-recovery > button { flex: 0 0 auto; max-width: 100%; white-space: normal; }
.startup-recovery .recovery-location { margin-block: 8px; }
.startup-recovery .recovery-location code { white-space: normal; overflow-wrap: anywhere; user-select: text; }
diff --git a/apps/desktop/src/product/DesktopApp.tsx b/apps/desktop/src/product/DesktopApp.tsx
index a13bf3a5..83ccf506 100644
--- a/apps/desktop/src/product/DesktopApp.tsx
+++ b/apps/desktop/src/product/DesktopApp.tsx
@@ -2,6 +2,7 @@ import type { Options } from '../plan-editor';
import { TrialQuickStart } from '../features/trial/TrialQuickStart';
import { NewModels } from '../features/trial/NewModels';
import { useTrustSuggestions } from '../features/trust/use-trust-suggestions';
+import { NativeConnectionRecovery } from './NativeConnectionRecovery';
import { startupFailureText } from '../storage-recovery';
import { randomId } from '../random-id.ts';
import { hostCapabilities } from '../host/index.ts';
@@ -101,7 +102,7 @@ function failureHelp(code: string, language: 'zh' | 'en', operation?: DesktopOpe
CHANGE_PREVIEW_STALE: ['预览已过期,请重新预览当前方案。', 'The preview is stale. Preview the current plan again.'],
LATEST_EDIT_NOT_APPLIED: ['已恢复原操作,最新编辑尚未应用。请先核对原操作结果。', 'The original operation was restored. Check its result before applying the latest edit.'],
OPERATION_IN_PROGRESS: ['这次保存仍在进行,完成后即可再次保存。', 'This save is still running. Save again after it finishes.'],
- TRUSTED_AUTHORITY_UNAVAILABLE: ['此连接仅支持查看,无法授权变更。', 'This connection supports viewing but cannot authorize a change.'],
+ TRUSTED_AUTHORITY_UNAVAILABLE: ['本机可信连接不可用,请恢复本机连接后重试。', 'The trusted local connection is unavailable. Restore the local connection and retry.'],
IDEMPOTENCY_KEY_REUSED: ['上一次保存仍在处理中。请先查看其结果,最新编辑尚未应用。', 'The previous save is still being processed. Check its result first; the latest edit was not applied.'],
};
return messages[code]?.[language === 'zh' ? 0 : 1]
@@ -178,6 +179,11 @@ export function DesktopApp() {
{ id: 'sessions', label: text.pages.sessions, icon: 'sessions' },
];
+ useEffect(() => {
+ const refresh = () => { void home.refreshDesktop(); };
+ window.addEventListener('hiroute-native-connection-unavailable', refresh);
+ return () => window.removeEventListener('hiroute-native-connection-unavailable', refresh);
+ }, [home.refreshDesktop]);
const serviceStatus = deriveHomeServiceStatus(home.reads.service);
const startupFailure = home.startup?.state === 'failed' ? home.startup : null;
const startupMessage = startupFailureText(startupFailure?.code, startupFailure?.storage_recovery, language, 'macos');
@@ -190,6 +196,7 @@ export function DesktopApp() {
service_recovery: language === 'zh' ? '正在恢复本机服务' : 'Restoring the local service',
})[upgradePhase] : undefined;
const serviceLabel = {
+ connection_lost: language === 'zh' ? '本机连接需要恢复' : 'Local connection needs recovery',
read_only: text.serviceReadOnly,
unavailable: text.serviceUnavailable,
ready: text.serviceReady,
@@ -697,6 +704,7 @@ export function DesktopApp() {
<HostNotices language={language} />
{notice && <div className="toast-stack" aria-live="polite"><div className="toast" role="status"><UiIcon name="info" /><span>{notice}</span></div></div>}
{upgradePhaseText && <div className="callout" role="status" aria-live="polite"><UiIcon name="info" /><div><strong>{upgradePhaseText}</strong><p>{language === 'zh' ? '请等待升级完成;请保留原数据与完整安装包。' : 'Wait for the upgrade to finish. Keep the original data and complete installation package.'}</p></div></div>}
+ <NativeConnectionRecovery status={home.desktopSnapshot?.native_connection} language={language} serviceResponsive={home.reads.service.status === 'ready'} onRefresh={home.refreshDesktop} onRecovered={async () => { await home.refreshAll(); setRefreshVersion(value => value + 1); }} />
{startupFailure && <div className="callout bad startup-recovery" role="alert" data-error-code={startupFailure.code}>
<UiIcon name="warning" />
<div>
diff --git a/apps/desktop/src/product/NativeConnectionRecovery.tsx b/apps/desktop/src/product/NativeConnectionRecovery.tsx
new file mode 100644
index 00000000..0b68a68e
--- /dev/null
+++ b/apps/desktop/src/product/NativeConnectionRecovery.tsx
@@ -0,0 +1,32 @@
+import { useEffect, useState } from 'react';
+import { invoke } from '../host/index.ts';
+import { safeDiagnosticCode } from '../error-code';
+import type { NativeConnectionStatus } from '../native-connection';
+
+export function NativeConnectionRecovery({ status, language, serviceResponsive, onRecovered, onRefresh }: {
+ status?: NativeConnectionStatus; language: 'zh' | 'en'; serviceResponsive: boolean; onRecovered: () => Promise<void>; onRefresh: () => Promise<void>;
+}) {
+ const [busy, setBusy] = useState(false);
+ const [error, setError] = useState('');
+ useEffect(() => { setError(''); }, [status]);
+ if (!status || status === 'ready') return null;
+ const text = (zh: string, en: string) => language === 'zh' ? zh : en;
+ async function recover() {
+ if (busy) return;
+ setBusy(true); setError('');
+ try { await invoke('recover_native_connection'); await onRecovered(); }
+ catch (failure) { setError(safeDiagnosticCode(failure, 'AUTHORITY_RECOVERY_UNAVAILABLE')); await onRefresh(); }
+ finally { setBusy(false); }
+ }
+ return <div className="callout bad native-connection-recovery" role="alert" data-connection-state={status}>
+ <div><strong>{status === 'not_owned' ? text('本机服务由其他入口管理', 'Local service managed elsewhere') : text('本机可信连接已失效', 'Trusted local connection lost')}</strong>
+ <p>{status === 'not_owned' ? text('本机服务正由其他入口管理,当前窗口无法读取受保护记录。请从该入口正常退出服务,再重新打开 HiRoute。', 'The local service is managed by another entry. This window cannot read protected records. Quit the service normally from that entry, then reopen HiRoute.') : !serviceResponsive ? text('当前无法确认本机服务状态。恢复连接会保留已保存的数据,不会重启服务。', 'The current local service state cannot be confirmed. Restore keeps saved data without restarting the service.') : text('本机服务仍可响应,但记录读取和需要授权的操作暂时不可用。恢复连接不会重启服务,运行中的请求和任务会继续执行。', 'The local service still responds, but records and protected actions are unavailable. Restore keeps the service and running requests and tasks active.')}</p>
+ {busy && <p role="status">{text('正在安全恢复本机连接…', 'Restoring the local connection safely…')}</p>}
+ {error && <p data-error-code={error}>{error === 'AUTHORITY_RECOVERY_PENDING'
+ ? text('尚未收到完整回复。当前服务保持运行,请稍后再次恢复。', 'The complete reply has not arrived. The service is still running; try restoring again shortly.')
+ : text('连接恢复未完成。请查看诊断信息或稍后重试。', 'Connection restoration did not complete. Check diagnostics or try again shortly.')}</p>}
+ {status === 'restart_required' && <p>{text('连接已断开或无法安全同步。请等现有工作结束后,正常退出并重新打开 HiRoute。', 'The connection is closed or cannot be safely synchronized. After existing work finishes, quit and reopen HiRoute normally.')}</p>}
+ </div>
+ {status === 'recovery_required' && <button className="btn btn-primary" type="button" disabled={busy} onClick={() => void recover()}>{text('恢复本机连接', 'Restore local connection')}</button>}
+ </div>;
+}
diff --git a/apps/desktop/src/product/home-projections.ts b/apps/desktop/src/product/home-projections.ts
index 7787cfa7..a09d2fef 100644
--- a/apps/desktop/src/product/home-projections.ts
+++ b/apps/desktop/src/product/home-projections.ts
@@ -16,6 +16,7 @@ import type { CacheHitSummary } from '../features/usage-presentation';
import type { Draft, Plan, Selection } from '../plan-editor';
export type DesktopSnapshot = {
+ native_connection?: import('../native-connection').NativeConnectionStatus;
catalog_error: unknown | null;
service: {
daemon_role: string;
@@ -95,6 +96,7 @@ export function projectHomeService(snapshot: DesktopSnapshot): HomeService {
}[snapshot.service.gateway] as HomeService['gateway'] | undefined;
return {
daemon: snapshot.trusted_authority ? 'running' : 'read_only',
+ nativeConnectionLost: snapshot.native_connection === 'recovery_required' || snapshot.native_connection === 'restart_required',
gateway: gateway ?? 'unknown',
recoveryReady: snapshot.service.recovery_ready,
};
diff --git a/apps/desktop/tests/README.md b/apps/desktop/tests/README.md
index 6a31d38b..bb405aa4 100644
--- a/apps/desktop/tests/README.md
+++ b/apps/desktop/tests/README.md
@@ -29,6 +29,7 @@ proves native authorization, persistence, process cleanup or real model calls.
| User capability | Representative tests | Unique guarantee |
| --- | --- | --- |
+| Restore a lost native connection while the daemon responds | `desktop.connection.loss-retry-recovery`, `desktop.connection.pending-and-failed-recovery`, `desktop.connection.unowned-service` in [shell scenarios](v3/browser/native-connection-scenarios.mjs), [production captures](v3/visual/native-connection-captures.mjs) | Accurate Home/Sessions read errors, explicit recovery, duplicate prevention, pending/failure states, external ownership refusal, and zh/en light/dark geometry at both window sizes. Native Resident/daemon faults, exact reply synchronization with unchanged daemon identity, running work, old confirmation expiry and retained data require separate macOS execution. |
| Recover after a storage upgrade refuses startup | [Recovery presentation](storage-recovery.test.mjs), [production-style scenarios](v3/visual/storage-recovery-scenarios.mjs), [storage owner proof](../../../crates/local-storage/src/migrations/startup_recovery.rs) | Original-program reinstall requires the authoritative admitted unchanged group; unknown causes never grant downgrade. Verified source guidance names the exact batch, source directory and guides; long names wrap in both languages/themes. Windows supplies a route from the displayed log folder; macOS offers the preserved-material action. Missing/unsafe locations grant neither located recovery nor resume. Native installed upgrade, complete restoration and real requests remain separate acceptance. |
| Search session content and continue reading matches | [Session scenarios](v3/browser/session-window-scenarios.mjs), [session layout captures](v3/visual/session-window-active.mjs) | Results represent distinct matching sessions; keyword edits discard stale pages, failed continuation withdraws its cursor, and clearing search resumes automatic selection after an in-flight detail read. Pending indexing and complete empty results remain distinct. Chinese/English searching, results, empty, pending and retry states stay readable at 1200×813 and 755×600 using production styles. Real lookup, fresh authorization and Worker activity require native acceptance. |
| Connect an API through the service directory | [Connection flow scenarios](v3/visual/connection-flow-active.mjs), [directory and draft rules](connection-directory.test.mjs) | Full branded directory, separate product drafts and keys, checked source name, cancellation, explicit model selection and inherited append behavior. Uses production styles; native save and live calls need separate acceptance. |
diff --git a/apps/desktop/tests/v3/browser/native-connection-scenarios.mjs b/apps/desktop/tests/v3/browser/native-connection-scenarios.mjs
new file mode 100644
index 00000000..9bb28fca
--- /dev/null
+++ b/apps/desktop/tests/v3/browser/native-connection-scenarios.mjs
@@ -0,0 +1,68 @@
+import { scenario } from './scenario-selection.mjs';
+
+export function nativeConnectionScenarios({ fresh, click, until, text, calls, control }) {
+ const c = control;
+ const assert = (value, message) => { if (!value) throw new Error(message); };
+ async function lose() {
+ c().desktop.native_connection = 'recovery_required';
+ c().desktop.trusted_authority = false;
+ c().handlers.observation_read = () => { throw { source: 'native', code: 'TRUSTED_AUTHORITY_UNAVAILABLE' }; };
+ await c().callHost('observation_read', {}).catch(() => {});
+ await until(() => document.querySelector('[data-connection-state="recovery_required"]'), 'lost native connection');
+ }
+ return [
+ scenario('desktop.connection.unowned-service', ['native-recovery'], 'An externally managed daemon cannot be taken over from the Desktop recovery control', async () => {
+ await fresh(); await lose();
+ c().desktop.native_connection = 'not_owned';
+ await c().callHost('observation_read', {}).catch(() => {});
+ await until(() => document.querySelector('[data-connection-state="not_owned"]'), 'external service ownership');
+ assert(text().includes('其他入口管理'), 'External ownership guidance missing');
+ assert(!document.querySelector('.native-connection-recovery button'), 'External daemon can be taken over');
+ assert(calls('recover_native_connection').length === 0, 'Recovery touched an external daemon');
+ }),
+ scenario('desktop.connection.loss-retry-recovery', ['native-recovery'], 'Live service with lost authority shows accurate read errors and only explicit recovery restores it', async () => {
+ await fresh(); await lose(); await click('会话');
+ await until(() => text().includes('暂时无法读取记录'), 'accurate observation error');
+ const health = document.querySelector('.sidebar-health')?.textContent ?? '';
+ assert(health.includes('需要恢复') && !health.includes('只读'), 'Lost authority masquerades as a healthy or intentionally read-only service');
+ const retry = [...document.querySelectorAll('button')].find(button => button.textContent.trim() === '重试');
+ assert(retry, 'Read retry missing'); retry.click();
+ await until(() => text().includes('暂时无法读取记录'), 'retry stays refused');
+ assert(calls('recover_native_connection').length === 0, 'Read retry silently restarted the service');
+ c().handlers.recover_native_connection = async payload => {
+ assert(Object.keys(payload).length === 0, 'WebView supplied native authority or filesystem parameters');
+ c().desktop.native_connection = 'ready'; c().desktop.trusted_authority = true;
+ delete c().handlers.observation_read;
+ };
+ await click('恢复本机连接');
+ await until(() => !document.querySelector('.native-connection-recovery'), 'recovered status');
+ assert(calls('recover_native_connection').length === 1, 'Recovery was repeated');
+ }),
+ scenario('desktop.connection.pending-and-failed-recovery', ['native-recovery'], 'Pending and failed recovery preserve an explicit action and prevent duplicate submission', async () => {
+ await fresh(); await lose();
+ let release;
+ c().handlers.recover_native_connection = () => new Promise((_, reject) => { release = reject; });
+ await click('恢复本机连接');
+ const button = document.querySelector('.native-connection-recovery button');
+ assert(button.disabled, 'Concurrent recovery remains enabled'); button.click();
+ assert(calls('recover_native_connection').length === 1, 'Concurrent recovery submitted twice');
+ release({ source: 'native', code: 'AUTHORITY_RECOVERY_PENDING' });
+ await until(() => text().includes('尚未收到完整回复'), 'pending reply guidance');
+ assert(c().desktop.native_connection === 'recovery_required', 'Pending reply became a successful connection');
+ c().handlers.recover_native_connection = () => { throw { source: 'native', code: 'AUTHORITY_RECOVERY_UNAVAILABLE' }; };
+ await click('恢复本机连接'); await until(() => text().includes('连接恢复未完成'), 'failed resynchronization guidance');
+ c().desktop.native_connection = 'restart_required';
+ await c().callHost('observation_read', {}).catch(() => {});
+ await until(() => document.querySelector('[data-connection-state="restart_required"]'), 'closed or invalid channel state');
+ assert(!document.querySelector('.native-connection-recovery button'), 'Invalid channel offered unsafe reuse');
+ c().desktop.native_connection = 'recovery_required';
+ await c().callHost('observation_read', {}).catch(() => {});
+ await until(() => document.querySelector('.native-connection-recovery button'), 'retry after pending stop');
+ c().handlers.desktop_snapshot = () => { throw { source: 'native', code: 'DAEMON_UNAVAILABLE' }; };
+ c().handlers.recover_native_connection = () => { throw { source: 'native', code: 'DAEMON_START_FAILED' }; };
+ await click('恢复本机连接');
+ await until(() => text().includes('当前无法确认本机服务状态'), 'failed connection restoration cannot claim a responsive daemon');
+ assert(!document.querySelector('.native-connection-recovery').textContent.includes('本机服务仍可响应'), 'Old reachability was displayed as current after a failed connection restoration');
+ }),
+ ];
+}
diff --git a/apps/desktop/tests/v3/browser/product-shell-scenarios.mjs b/apps/desktop/tests/v3/browser/product-shell-scenarios.mjs
index 0fc4ec27..31014f23 100644
--- a/apps/desktop/tests/v3/browser/product-shell-scenarios.mjs
+++ b/apps/desktop/tests/v3/browser/product-shell-scenarios.mjs
@@ -1,6 +1,7 @@
import { scenario, scenarioCatalog, runScenarios } from './scenario-selection.mjs';
import { productShellRequired } from './scenario-requirements.mjs';
import { cProtocolScenarios } from './c-protocol-scenarios.mjs';
+import { nativeConnectionScenarios } from './native-connection-scenarios.mjs';
import { presentationScenarios } from './presentation-interactions.mjs';
const c = () => window.productShell;
const pause = ms => new Promise(resolve => setTimeout(resolve, ms));
@@ -57,6 +58,7 @@ async function routing() {
await until(() => document.querySelector('.plan-identity-fields input'), 'route editor');
}
const scenarios = [
+ ...nativeConnectionScenarios({ fresh, click, until, text, calls, control: c }),
...cProtocolScenarios({ fresh, routing, click, until, all, text, calls, setInput, control: c }),
...presentationScenarios,
scenario('desktop.routing.two-context-conflict', ['routing-editor'], 'A rival context revision refuses stale publication and preserves the current draft', async () => {
diff --git a/apps/desktop/tests/v3/browser/scenario-requirements.mjs b/apps/desktop/tests/v3/browser/scenario-requirements.mjs
index ffbb8a25..824bc105 100644
--- a/apps/desktop/tests/v3/browser/scenario-requirements.mjs
+++ b/apps/desktop/tests/v3/browser/scenario-requirements.mjs
@@ -63,6 +63,9 @@ export const focusedRequirements = {
};
export const productShellRequired = [
+ 'desktop.connection.unowned-service',
+ 'desktop.connection.loss-retry-recovery',
+ 'desktop.connection.pending-and-failed-recovery',
'desktop.settings.storage-capacity',
'desktop.routing.native-default',
'desktop.decisions.connectivity-test',
diff --git a/apps/desktop/tests/v3/visual/agent-trust-active.mjs b/apps/desktop/tests/v3/visual/agent-trust-active.mjs
index 066222be..f6502dec 100644
--- a/apps/desktop/tests/v3/visual/agent-trust-active.mjs
+++ b/apps/desktop/tests/v3/visual/agent-trust-active.mjs
@@ -130,9 +130,12 @@ try {
await navigate(client, fixtureUrl('product-shell.html'), { width: 1280, height: 900 });
await waitFor(client, 'Boolean(window.productShell)', { timeout: 7000 });
const catalog = await evaluate(client, "import('/product-shell-scenarios.mjs').then(module => module.productShellScenarioCatalog)");
- const selected = selectScenarios(catalog, subscriptionProxyOnly
+ const requested = process.env.HIROUTE_BROWSER_SCENARIOS?.split(',');
+ const applicable = hostTransport === 'console' ? catalog.filter(item => !item.capabilities.includes('native-recovery')) : catalog;
+ const required = productShellRequired.filter(id => applicable.some(item => item.id === id));
+ const selected = selectScenarios(applicable, subscriptionProxyOnly
? { capability: 'subscription-proxy', requiredIds: focusedRequirements['subscription-proxy'] }
- : { ids: process.env.HIROUTE_BROWSER_SCENARIOS?.split(','), requiredIds: process.env.HIROUTE_BROWSER_SCENARIOS?.split(',') ?? productShellRequired });
+ : { ids: requested, requiredIds: requested ?? required });
const results = [];
for (const { id } of selected) {
const viewport = ['desktop.models.subscription-scan.recommended-login',
@@ -147,6 +150,9 @@ try {
}
assertScenarioResults(selected, results);
checks.push(...results);
+ if (selected.some(s => s.capabilities.includes('native-recovery'))) {
+ checks.push(...await (await import('./native-connection-captures.mjs')).nativeConnectionCaptures(client, baseUrl, outputRoot));
+ }
if (selected.some(s => s.id === 'desktop.settings.storage-capacity')) {
checks.push(...await (await import('./storage-capacity-captures.mjs')).runStorageCapacityCaptures(client, outputRoot));
}
diff --git a/apps/desktop/tests/v3/visual/native-connection-captures.mjs b/apps/desktop/tests/v3/visual/native-connection-captures.mjs
new file mode 100644
index 00000000..07d28b76
--- /dev/null
+++ b/apps/desktop/tests/v3/visual/native-connection-captures.mjs
@@ -0,0 +1,37 @@
+import { writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { evaluate, navigate, waitFor } from './cdp-client.mjs';
+
+export async function nativeConnectionCaptures(client, baseUrl, output) {
+ const results = [];
+ for (const language of ['zh', 'en']) for (const theme of ['light', 'dark']) for (const viewport of [{ width: 1200, height: 813 }, { width: 755, height: 600 }]) {
+ await navigate(client, new URL('product-shell.html', baseUrl).href, viewport);
+ await waitFor(client, 'Boolean(window.productShell)');
+ await evaluate(client, `(() => {
+ localStorage.setItem('hiroute.language', ${JSON.stringify(language)});
+ localStorage.setItem('hiroute.theme', ${JSON.stringify(theme)});
+ const c = window.productShell;
+ c.desktop.native_connection = 'recovery_required'; c.desktop.trusted_authority = false;
+ c.handlers.observation_read = () => { throw { source: 'native', code: 'TRUSTED_AUTHORITY_UNAVAILABLE' }; };
+ c.handlers.recover_native_connection = () => { throw { source: 'native', code: 'AUTHORITY_RECOVERY_PENDING' }; };
+ c.remount();
+ })()`);
+ await waitFor(client, 'Boolean(document.querySelector(".native-connection-recovery button"))');
+ await evaluate(client, 'document.querySelector(".native-connection-recovery button").click()');
+ await waitFor(client, 'Boolean(document.querySelector("[data-error-code=AUTHORITY_RECOVERY_PENDING]"))');
+ const geometry = await evaluate(client, `(() => {
+ const box = document.querySelector('.native-connection-recovery'); const action = box.querySelector('button');
+ const b = box.getBoundingClientRect(), a = action.getBoundingClientRect();
+ return { bodyOverflow: document.documentElement.scrollWidth > innerWidth + 1,
+ overflow: box.scrollWidth > box.clientWidth + 1, height: b.height,
+ actionVisible: a.left >= 0 && a.right <= innerWidth + 1 && a.top >= 0 && a.bottom <= innerHeight,
+ text: box.textContent };
+ })()`);
+ if (geometry.overflow || geometry.bodyOverflow || !geometry.actionVisible || geometry.height > viewport.height * .65) throw new Error(`Recovery geometry: ${JSON.stringify({ language, theme, viewport, geometry })}`);
+ const id = `native-connection-${language}-${theme}-${viewport.width}`;
+ const shot = await client.send('Page.captureScreenshot', { format: 'png', captureBeyondViewport: false });
+ await writeFile(path.join(output, `${id}.png`), Buffer.from(shot.data, 'base64'));
+ results.push({ id, state: 'green', language, theme, viewport, geometry, screenshot: `${id}.png` });
+ }
+ return results;
+}
diff --git a/contracts/compatibility-support.v1.json b/contracts/compatibility-support.v1.json
index 2bd6683d..ae682ff7 100644
--- a/contracts/compatibility-support.v1.json
+++ b/contracts/compatibility-support.v1.json
@@ -157,6 +157,7 @@
"hiroute.cpa-managed-login/v1",
"hiroute.cpa-managed-oauth-binding/v1",
"hiroute.cpa-managed-subscription-discovery/v1",
+ "hiroute.cpa-model-discovery/v1",
"hiroute.cpa-owner/v1",
"hiroute.cpa-source-binding-identity/v1",
"hiroute.cpa-subscription-catalog-capability/v1",
diff --git a/crates/cpa-bridge/src/accounts.rs b/crates/cpa-bridge/src/accounts.rs
index 62fbc2da..d007b27c 100644
--- a/crates/cpa-bridge/src/accounts.rs
+++ b/crates/cpa-bridge/src/accounts.rs
@@ -187,6 +187,7 @@ pub(crate) trait CpaControlPlane: Send + Sync {
expected_version: &str,
timeout: Duration,
refresh_models: bool,
+ diagnostics: &hiroute_diagnostics::context::DiagnosticContext,
) -> Result<Vec<AccountSnapshotRecord>, AccountDiscoveryError>;
}
@@ -260,6 +261,30 @@ pub(crate) enum AccountDiscoveryError {
Http(#[from] crate::http::LoopbackHttpError),
}
+impl AccountDiscoveryError {
+ pub(crate) fn diagnostic_code(&self) -> hiroute_diagnostics::event::CpaFailureCode {
+ use crate::http::LoopbackHttpError;
+ use hiroute_diagnostics::event::CpaFailureCode;
+ match self {
+ Self::Http(LoopbackHttpError::Io(error)) => {
+ if matches!(
+ error.kind(),
+ std::io::ErrorKind::TimedOut | std::io::ErrorKind::WouldBlock
+ ) {
+ CpaFailureCode::ControlTimeout
+ } else {
+ CpaFailureCode::ControlTransport
+ }
+ }
+ Self::ManagementAuthentication | Self::DownstreamAuthentication => {
+ CpaFailureCode::ControlAuthentication
+ }
+ Self::PinNotApplied => CpaFailureCode::ControlPinNotApplied,
+ _ => CpaFailureCode::ControlRejected,
+ }
+ }
+}
+
#[cfg(test)]
mod tests {
use super::*;
diff --git a/crates/cpa-bridge/src/accounts/stock.rs b/crates/cpa-bridge/src/accounts/stock.rs
index f861226d..18ab4502 100644
--- a/crates/cpa-bridge/src/accounts/stock.rs
+++ b/crates/cpa-bridge/src/accounts/stock.rs
@@ -5,6 +5,8 @@ use std::path::Path;
use std::thread;
use std::time::{Duration, Instant};
+use hiroute_diagnostics::context::DiagnosticContext;
+use hiroute_diagnostics::event::{CpaControlPhase, CpaPinChecks};
use serde_json::Value;
use sha2::{Digest, Sha256};
@@ -19,9 +21,14 @@ use crate::http::{LoopbackRequest, percent_encode_query, request};
const MAX_AUTH_FILES: usize = 10_000;
const PIN_POLL_INTERVAL: Duration = Duration::from_millis(20);
+mod diagnostics;
+mod model_discovery;
mod validation;
-use validation::{persisted_controls_match, reject_secret_material, validate_management_response};
+use diagnostics::DiscoveryTrace;
+use validation::{
+ observe_persisted_controls, reject_secret_material, validate_management_response,
+};
#[derive(Clone, Copy, Debug, Default)]
pub(crate) struct StockCpaControlPlane;
@@ -78,20 +85,24 @@ impl CpaControlPlane for StockCpaControlPlane {
expected_version: &str,
timeout: Duration,
refresh_models: bool,
+ diagnostics: &DiagnosticContext,
) -> Result<Vec<AccountSnapshotRecord>, AccountDiscoveryError> {
let deadline = Instant::now()
.checked_add(timeout)
.ok_or(AccountDiscoveryError::PinNotApplied)?;
- let mut names = fs::read_dir(auth_dir)
- .map_err(AccountDiscoveryError::AuthDirectory)?
- .filter_map(Result::ok)
- .filter_map(|entry| {
- let file_type = entry.file_type().ok()?;
- let name = entry.file_name().into_string().ok()?;
- (file_type.is_file() && name.to_ascii_lowercase().ends_with(".json"))
- .then_some(name)
- })
- .collect::<Vec<_>>();
+ let mut trace = DiscoveryTrace::new(diagnostics, timeout, refresh_models);
+ let mut names = trace.run(CpaControlPhase::InventoryRead, |_| {
+ Ok(fs::read_dir(auth_dir)
+ .map_err(AccountDiscoveryError::AuthDirectory)?
+ .filter_map(Result::ok)
+ .filter_map(|entry| {
+ let file_type = entry.file_type().ok()?;
+ let name = entry.file_name().into_string().ok()?;
+ (file_type.is_file() && name.to_ascii_lowercase().ends_with(".json"))
+ .then_some(name)
+ })
+ .collect::<Vec<_>>())
+ })?;
names.sort();
if names.len() > MAX_AUTH_FILES {
return Err(AccountDiscoveryError::TooManyAccounts);
@@ -107,14 +118,18 @@ impl CpaControlPlane for StockCpaControlPlane {
let mut matched_managed = BTreeSet::new();
let mut snapshots = Vec::new();
let mut seen_indexes = BTreeSet::new();
- for name in names {
- let Some(account) = get_oauth_account(
- address,
- secrets,
- expected_version,
- remaining_timeout(deadline)?,
- &name,
- )?
+ for (ordinal, name) in names.into_iter().enumerate() {
+ trace.account_ordinal = Some(ordinal as u32);
+ trace.checks = CpaPinChecks::default();
+ let Some(account) = trace.run(CpaControlPhase::AccountRead, |_| {
+ get_oauth_account(
+ address,
+ secrets,
+ expected_version,
+ remaining_timeout(deadline)?,
+ &name,
+ )
+ })?
else {
continue;
};
@@ -144,28 +159,36 @@ impl CpaControlPlane for StockCpaControlPlane {
// only repair changed controls or honor an explicit subscription check.
if refresh_models
|| account.request_retry != Some(0)
- || !persisted_controls_match(auth_dir, &name, &prefix)?
+ || !trace.run(CpaControlPhase::ControlsRead, |trace| {
+ observe_persisted_controls(auth_dir, &name, &prefix, &mut trace.checks)
+ })?
{
- patch_account_controls(
+ trace.checks = CpaPinChecks::default();
+ trace.run(CpaControlPhase::ControlsPatch, |_| {
+ patch_account_controls(
+ address,
+ secrets,
+ expected_version,
+ remaining_timeout(deadline)?,
+ &account.id,
+ &prefix,
+ managed,
+ )
+ })?;
+ }
+ let models = trace.run(CpaControlPhase::AccountPin, |trace| {
+ wait_for_account_pin(
address,
+ auth_dir,
secrets,
expected_version,
- remaining_timeout(deadline)?,
- &account.id,
+ deadline,
+ &name,
+ &account,
&prefix,
- managed,
- )?;
- }
- let models = wait_for_account_pin(
- address,
- auth_dir,
- secrets,
- expected_version,
- deadline,
- &name,
- &account,
- &prefix,
- )?;
+ trace,
+ )
+ })?;
snapshots.push(AccountSnapshotRecord {
account_kind: account.kind,
stock_id: account.id,
@@ -181,7 +204,11 @@ impl CpaControlPlane for StockCpaControlPlane {
if matched_managed.len() != managed_identities.len() {
return Err(AccountDiscoveryError::AccountDisappeared);
}
- wait_for_prefixed_catalog(address, secrets, deadline, &snapshots)?;
+ trace.account_ordinal = None;
+ trace.checks = CpaPinChecks::default();
+ trace.run(CpaControlPhase::CatalogPin, |trace| {
+ wait_for_prefixed_catalog(address, secrets, deadline, &snapshots, trace)
+ })?;
snapshots.sort_by(|left, right| left.account_digest.cmp(&right.account_digest));
Ok(snapshots)
}
@@ -204,8 +231,10 @@ fn wait_for_account_pin(
name: &str,
account: &StockAccount,
prefix: &str,
+ trace: &mut DiscoveryTrace<'_>,
) -> Result<BTreeSet<String>, AccountDiscoveryError> {
loop {
+ trace.polls = trace.polls.saturating_add(1);
let patched = get_oauth_account(
address,
secrets,
@@ -214,19 +243,43 @@ fn wait_for_account_pin(
name,
)?
.ok_or(AccountDiscoveryError::AccountDisappeared)?;
+ trace.checks.account_index_matches = Some(patched.auth_index == account.auth_index);
+ trace.checks.account_retry_zero = Some(patched.request_retry == Some(0));
if patched.auth_index == account.auth_index && patched.request_retry == Some(0) {
- let registered = get_account_models(
+ let (registered, discovery_terminal) = get_account_models(
address,
secrets,
expected_version,
remaining_timeout(deadline)?,
&account.id,
+ trace,
)?;
- if let Ok(models) = strip_exact_prefix(&registered, prefix)
- && persisted_controls_match(auth_dir, name, prefix)?
+ trace.checks.account_model_count = Some(registered.len() as u32);
+ trace.checks.account_models_nonempty = Some(!registered.is_empty());
+ if registered.is_empty() && discovery_terminal {
+ return Err(AccountDiscoveryError::PinNotApplied);
+ }
+ let prefixed = strip_exact_prefix(&registered, prefix);
+ let marker = format!("{prefix}/");
+ let prefixes_match = registered.iter().all(|model| {
+ model
+ .strip_prefix(&marker)
+ .is_some_and(|model| !model.is_empty())
+ });
+ trace.checks.account_models_prefixed =
+ (!registered.is_empty()).then_some(prefixes_match);
+ trace.checks.account_model_ids_valid =
+ (!registered.is_empty() && prefixes_match).then_some(prefixed.is_ok());
+ if let Ok(models) = prefixed
+ && observe_persisted_controls(auth_dir, name, prefix, &mut trace.checks)?
{
return Ok(models);
}
+ } else {
+ trace.checks.account_models_nonempty = None;
+ trace.checks.account_models_prefixed = None;
+ trace.checks.account_model_ids_valid = None;
+ trace.checks.account_model_count = None;
}
let remaining = remaining_timeout(deadline)?;
thread::sleep(PIN_POLL_INTERVAL.min(remaining));
@@ -238,9 +291,17 @@ fn wait_for_prefixed_catalog(
secrets: &InstanceSecrets,
deadline: Instant,
snapshots: &[AccountSnapshotRecord],
+ trace: &mut DiscoveryTrace<'_>,
) -> Result<(), AccountDiscoveryError> {
loop {
- match validate_prefixed_catalog(address, secrets, remaining_timeout(deadline)?, snapshots) {
+ trace.polls = trace.polls.saturating_add(1);
+ match validate_prefixed_catalog(
+ address,
+ secrets,
+ remaining_timeout(deadline)?,
+ snapshots,
+ trace,
+ ) {
Ok(()) => return Ok(()),
Err(AccountDiscoveryError::PinNotApplied) => {
let remaining = remaining_timeout(deadline)?;
@@ -419,7 +480,8 @@ fn get_account_models(
expected_version: &str,
timeout: Duration,
id: &str,
-) -> Result<BTreeSet<String>, AccountDiscoveryError> {
+ trace: &mut DiscoveryTrace<'_>,
+) -> Result<(BTreeSet<String>, bool), AccountDiscoveryError> {
let path = format!(
"/v0/management/auth-files/models?name={}",
percent_encode_query(id)
@@ -436,6 +498,7 @@ fn get_account_models(
let value: Value =
serde_json::from_slice(&response.body).map_err(AccountDiscoveryError::Json)?;
reject_secret_material(&value)?;
+ trace.model_discovery(&value);
let models = value
.get("models")
.and_then(Value::as_array)
@@ -454,7 +517,8 @@ fn get_account_models(
return Err(AccountDiscoveryError::DuplicateModel);
}
}
- Ok(result)
+ let terminal = result.is_empty() && model_discovery::latest_is_terminal(&value);
+ Ok((result, terminal))
}
fn validate_prefixed_catalog(
@@ -462,6 +526,7 @@ fn validate_prefixed_catalog(
secrets: &InstanceSecrets,
timeout: Duration,
snapshots: &[AccountSnapshotRecord],
+ trace: &mut DiscoveryTrace<'_>,
) -> Result<(), AccountDiscoveryError> {
let response = request(LoopbackRequest {
address,
@@ -485,14 +550,20 @@ fn validate_prefixed_catalog(
.iter()
.filter_map(|model| model.get("id").and_then(Value::as_str))
.collect::<BTreeSet<_>>();
+ let mut missing = 0_u32;
for snapshot in snapshots {
for model in &snapshot.observed_model_ids {
if !available.contains(format!("{}/{model}", snapshot.prefix).as_str()) {
- return Err(AccountDiscoveryError::PinNotApplied);
+ missing = missing.saturating_add(1);
}
}
}
- Ok(())
+ trace.checks.catalog_missing_count = Some(missing);
+ if missing == 0 {
+ Ok(())
+ } else {
+ Err(AccountDiscoveryError::PinNotApplied)
+ }
}
fn account_digest(kind: CpaAccountKind, auth_index: &str) -> String {
diff --git a/crates/cpa-bridge/src/accounts/stock/diagnostic_tests.rs b/crates/cpa-bridge/src/accounts/stock/diagnostic_tests.rs
new file mode 100644
index 00000000..93ff44c5
--- /dev/null
+++ b/crates/cpa-bridge/src/accounts/stock/diagnostic_tests.rs
@@ -0,0 +1,216 @@
+use super::*;
+use hiroute_diagnostics::event::{CpaControlPhase, CpaStageOutcome, ProcessRole};
+use hiroute_diagnostics::level::DiagnosticLevel;
+use hiroute_diagnostics::record::Component;
+use hiroute_diagnostics::runtime::{DiagnosticRuntime, RuntimeConfig};
+
+fn diagnostics(root: &Path) -> DiagnosticRuntime {
+ DiagnosticRuntime::start(RuntimeConfig {
+ root: root.to_owned(),
+ role: ProcessRole::Daemon,
+ component: Component::Cpa,
+ parent_session_id: None,
+ level_override: Some(DiagnosticLevel::Debug),
+ })
+}
+
+#[test]
+fn each_unmet_pin_condition_is_reported_without_per_poll_logging() {
+ for (fault, field, expected) in [
+ (1, "account_models_nonempty", serde_json::json!(false)),
+ (2, "account_models_prefixed", serde_json::json!(false)),
+ (3, "catalog_missing_count", serde_json::json!(1)),
+ (4, "account_index_matches", serde_json::json!(false)),
+ (5, "account_retry_zero", serde_json::json!(false)),
+ (6, "persisted_prefix_matches", serde_json::json!(false)),
+ (7, "persisted_retry_zero", serde_json::json!(false)),
+ (8, "persisted_cooling_disabled", serde_json::json!(false)),
+ (9, "account_model_ids_valid", serde_json::json!(false)),
+ ] {
+ let fixture = Fixture::new();
+ fixture.fault.store(fault, Ordering::SeqCst);
+ let path = fixture.root.path().join("codex-a.json");
+ let mut controls: Value = serde_json::from_slice(&fs::read(&path).unwrap()).unwrap();
+ match fault {
+ 6 => controls["prefix"] = serde_json::json!("wrong"),
+ 7 => controls["request_retry"] = serde_json::json!(1),
+ 8 => controls["disable_cooling"] = serde_json::json!(false),
+ _ => (),
+ }
+ fs::write(path, controls.to_string()).unwrap();
+ let logs = crate::private_test_support::tempdir().unwrap();
+ let runtime = diagnostics(logs.path());
+ let identity = ManagedAccountIdentity {
+ account_kind: CpaAccountKind::Codex,
+ stock_file_name: "codex-a.json".into(),
+ account_digest: "a".repeat(64),
+ generation: 1,
+ client_version: None,
+ };
+ let result = StockCpaControlPlane.discover_and_pin(
+ fixture.address,
+ fixture.root.path(),
+ &[identity],
+ &InstanceSecrets::generate().unwrap(),
+ "8.0.4-hiroute.4",
+ Duration::from_millis(150),
+ false,
+ &runtime.port().handle().context(),
+ );
+ // The shared deadline may expire between polls or during the last local
+ // read. The observed unmet condition must survive either terminal error.
+ assert!(result.is_err(), "fault {fault}: {result:?}");
+ runtime.shutdown();
+ let text = fs::read_to_string(logs.path().join("daemon/current.jsonl")).unwrap();
+ let events: Vec<Value> = text
+ .lines()
+ .filter_map(|line| {
+ let value: Value = serde_json::from_str(line).unwrap();
+ value["event"]["cpa_control"].is_object().then_some(value)
+ })
+ .collect();
+ let failed = events
+ .iter()
+ .find(|event| event["event"]["cpa_control"]["outcome"]["failed"].is_object())
+ .unwrap();
+ let control = &failed["event"]["cpa_control"];
+ assert_eq!(
+ control["checks"][field], expected,
+ "fault {fault}: {control}"
+ );
+ assert_eq!(
+ control["phase"],
+ if fault == 3 {
+ "catalog_pin"
+ } else {
+ "account_pin"
+ }
+ );
+ assert!(control["polls"].as_u64().unwrap() > 1);
+ assert_eq!(failed["level"], "warn");
+ assert!(events.len() <= 10, "per-poll logging: {}", events.len());
+ assert!(
+ events
+ .iter()
+ .all(|event| event["span_id"] == failed["span_id"])
+ );
+ for forbidden in [
+ "codex-a.json",
+ "idx-a",
+ "future-model",
+ "other-prefix",
+ "Bearer",
+ ] {
+ assert!(!text.contains(forbidden), "diagnostic leaked {forbidden}");
+ }
+ if fault == 1 {
+ assert_eq!(control["checks"]["account_index_matches"], true);
+ assert_eq!(control["checks"]["account_retry_zero"], true);
+ for field in [
+ "persisted_prefix_matches",
+ "persisted_retry_zero",
+ "persisted_cooling_disabled",
+ ] {
+ assert_eq!(control["checks"][field], true);
+ }
+ assert_eq!(fixture.patches.load(Ordering::SeqCst), 0);
+ }
+ if fault == 9 {
+ assert_eq!(control["checks"]["account_models_nonempty"], true);
+ assert_eq!(control["checks"]["account_models_prefixed"], true);
+ }
+ }
+}
+
+#[test]
+fn slow_patch_is_distinct_from_unmet_pin_checks() {
+ let fixture = Fixture::new();
+ fixture.patch_delay_ms.store(300, Ordering::SeqCst);
+ let logs = crate::private_test_support::tempdir().unwrap();
+ let runtime = diagnostics(logs.path());
+ let identity = ManagedAccountIdentity {
+ account_kind: CpaAccountKind::Codex,
+ stock_file_name: "codex-a.json".into(),
+ account_digest: "a".repeat(64),
+ generation: 1,
+ client_version: None,
+ };
+ let result = StockCpaControlPlane.discover_and_pin(
+ fixture.address,
+ fixture.root.path(),
+ &[identity],
+ &InstanceSecrets::generate().unwrap(),
+ "8.0.4-hiroute.4",
+ Duration::from_millis(100),
+ true,
+ &runtime.port().handle().context(),
+ );
+ assert!(result.is_err());
+ runtime.shutdown();
+ let log = fs::read_to_string(logs.path().join("daemon/current.jsonl")).unwrap();
+ let failed: Value = log
+ .lines()
+ .map(|line| serde_json::from_str::<Value>(line).unwrap())
+ .find(|event| event["event"]["cpa_control"]["outcome"]["failed"].is_object())
+ .unwrap();
+ assert_eq!(failed["event"]["cpa_control"]["phase"], "controls_patch");
+ assert_eq!(
+ failed["event"]["cpa_control"]["outcome"]["failed"]["code"],
+ "control_timeout"
+ );
+ assert_eq!(failed["event"]["cpa_control"]["polls"], 0);
+ assert!(
+ failed["event"]["cpa_control"]["checks"]
+ .as_object()
+ .unwrap()
+ .is_empty()
+ );
+}
+
+#[test]
+#[ignore = "requires a private HIROUTE_CPA_PIN_SMOKE manifest and an isolated real CPA"]
+fn live_managed_cpa_discovery_diagnostics() {
+ let manifest = std::env::var("HIROUTE_CPA_PIN_SMOKE").expect("smoke manifest required");
+ let value: Value = serde_json::from_slice(&fs::read(manifest).unwrap()).unwrap();
+ let field = |key: &str| value[key].as_str().unwrap();
+ let runtime = diagnostics(Path::new(field("diagnostics_root")));
+ let identity = ManagedAccountIdentity {
+ account_kind: CpaAccountKind::Codex,
+ stock_file_name: field("stock_file_name").into(),
+ account_digest: "a".repeat(64),
+ generation: 1,
+ client_version: value["client_version"].as_str().map(str::to_owned),
+ };
+ let result = StockCpaControlPlane.discover_and_pin(
+ field("address").parse().unwrap(),
+ Path::new(field("auth_dir")),
+ &[identity],
+ &InstanceSecrets::read(Path::new(field("capability_file"))).unwrap(),
+ field("version"),
+ crate::MANAGED_CPA_CONTROL_TIMEOUT,
+ value["refresh_models"].as_bool().unwrap(),
+ &runtime.port().handle().context(),
+ );
+ runtime.shutdown();
+ let log = fs::read_to_string(Path::new(field("diagnostics_root")).join("daemon/current.jsonl"))
+ .unwrap();
+ let events: Vec<hiroute_diagnostics::record::DiagnosticRecordV1> = log
+ .lines()
+ .map(|line| serde_json::from_str(line).unwrap())
+ .collect();
+ if value["expect_empty"].as_bool().unwrap() {
+ assert!(result.is_err());
+ assert!(events.iter().any(|event| matches!(&event.event,
+ hiroute_diagnostics::event::DiagnosticEvent::CpaControl(control)
+ if control.phase == CpaControlPhase::AccountPin
+ && matches!(control.outcome, CpaStageOutcome::Failed { .. })
+ && control.checks.account_models_nonempty == Some(false)
+ && control.checks.account_index_matches == Some(true)
+ && control.checks.account_retry_zero == Some(true)
+ )));
+ } else {
+ let accounts = result.unwrap();
+ assert_eq!(accounts.len(), 1);
+ assert!(!accounts[0].observed_model_ids.is_empty());
+ }
+}
diff --git a/crates/cpa-bridge/src/accounts/stock/diagnostics.rs b/crates/cpa-bridge/src/accounts/stock/diagnostics.rs
new file mode 100644
index 00000000..81005eb4
--- /dev/null
+++ b/crates/cpa-bridge/src/accounts/stock/diagnostics.rs
@@ -0,0 +1,78 @@
+use std::time::{Duration, Instant};
+
+use hiroute_diagnostics::context::DiagnosticContext;
+use hiroute_diagnostics::event::{
+ CpaControl, CpaControlPhase, CpaPinChecks, CpaStageOutcome, DiagnosticEvent,
+};
+
+use crate::accounts::AccountDiscoveryError;
+
+pub(super) struct DiscoveryTrace<'a> {
+ context: &'a DiagnosticContext,
+ started: Instant,
+ budget_ms: u64,
+ refresh_models: bool,
+ pub account_ordinal: Option<u32>,
+ pub polls: u32,
+ pub checks: CpaPinChecks,
+ model_discovery: super::model_discovery::Observations,
+}
+
+impl<'a> DiscoveryTrace<'a> {
+ pub fn new(context: &'a DiagnosticContext, timeout: Duration, refresh_models: bool) -> Self {
+ Self {
+ context,
+ started: Instant::now(),
+ budget_ms: millis(timeout),
+ refresh_models,
+ account_ordinal: None,
+ polls: 0,
+ checks: CpaPinChecks::default(),
+ model_discovery: Default::default(),
+ }
+ }
+
+ pub fn model_discovery(&mut self, response: &serde_json::Value) {
+ for observation in self.model_discovery.read(response, self.account_ordinal) {
+ self.context
+ .emit(DiagnosticEvent::CpaModelDiscovery(observation));
+ }
+ }
+
+ pub fn run<T>(
+ &mut self,
+ phase: CpaControlPhase,
+ operation: impl FnOnce(&mut Self) -> Result<T, AccountDiscoveryError>,
+ ) -> Result<T, AccountDiscoveryError> {
+ self.polls = 0;
+ let started = Instant::now();
+ self.emit(phase, CpaStageOutcome::Entered, Duration::ZERO);
+ let result = operation(self);
+ let outcome = match &result {
+ Ok(_) => CpaStageOutcome::Completed,
+ Err(error) => CpaStageOutcome::Failed {
+ code: error.diagnostic_code(),
+ },
+ };
+ self.emit(phase, outcome, started.elapsed());
+ result
+ }
+
+ fn emit(&self, phase: CpaControlPhase, outcome: CpaStageOutcome, elapsed: Duration) {
+ self.context.emit(DiagnosticEvent::CpaControl(CpaControl {
+ phase,
+ outcome,
+ elapsed_ms: millis(elapsed),
+ total_elapsed_ms: millis(self.started.elapsed()),
+ budget_ms: self.budget_ms,
+ refresh_models: self.refresh_models,
+ account_ordinal: self.account_ordinal,
+ polls: self.polls,
+ checks: self.checks.clone(),
+ }));
+ }
+}
+
+fn millis(duration: Duration) -> u64 {
+ duration.as_millis().min(u128::from(u64::MAX)) as u64
+}
diff --git a/crates/cpa-bridge/src/accounts/stock/model_discovery.rs b/crates/cpa-bridge/src/accounts/stock/model_discovery.rs
new file mode 100644
index 00000000..f6c38574
--- /dev/null
+++ b/crates/cpa-bridge/src/accounts/stock/model_discovery.rs
@@ -0,0 +1,137 @@
+use hiroute_diagnostics::event::{
+ CpaDiscoveryAttempt, CpaDiscoveryObservation, CpaDiscoveryOutcome, CpaDiscoveryPhase,
+ CpaDiscoveryUnavailable, CpaModelDiscovery,
+};
+use serde::Deserialize;
+use serde_json::Value;
+
+const MAX_OBSERVATIONS: usize = 64;
+
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct Snapshot {
+ schema: String,
+ process_id: u32,
+ evicted_accounts: u64,
+ first_failure: Option<CpaDiscoveryAttempt>,
+ latest: Option<CpaDiscoveryAttempt>,
+ registration_pending: Option<bool>,
+}
+
+/// Dedupe transitions, ignoring the growing elapsed time of an entered phase.
+/// Both retention and emitted records are bounded for this control operation.
+#[derive(Default)]
+pub(super) struct Observations {
+ seen: Vec<CpaModelDiscovery>,
+ truncated: bool,
+}
+
+impl Observations {
+ pub fn read(&mut self, value: &Value, ordinal: Option<u32>) -> Vec<CpaModelDiscovery> {
+ let observations = parse(value)
+ .map(|(_, observations)| observations)
+ .unwrap_or_else(|reason| vec![CpaDiscoveryObservation::Unavailable { reason }]);
+ let mut result = Vec::new();
+ for observation in observations {
+ let event = CpaModelDiscovery {
+ account_ordinal: ordinal,
+ observation,
+ };
+ let mut key = event.clone();
+ if let CpaDiscoveryObservation::Observed { attempt, .. } = &mut key.observation {
+ attempt.elapsed_ms = 0;
+ attempt.phase_elapsed_ms = 0;
+ for timing in &mut attempt.timings {
+ timing.elapsed_ms = 0;
+ }
+ }
+ if self.seen.contains(&key) {
+ continue;
+ }
+ if self.seen.len() == MAX_OBSERVATIONS {
+ if !self.truncated {
+ self.truncated = true;
+ result.push(CpaModelDiscovery {
+ account_ordinal: ordinal,
+ observation: CpaDiscoveryObservation::Unavailable {
+ reason: CpaDiscoveryUnavailable::ObservationLimit,
+ },
+ });
+ }
+ break;
+ }
+ self.seen.push(key);
+ result.push(event);
+ }
+ result
+ }
+}
+
+fn parse(
+ value: &Value,
+) -> Result<(Option<bool>, Vec<CpaDiscoveryObservation>), CpaDiscoveryUnavailable> {
+ let raw = value
+ .get("hiroute_model_discovery")
+ .ok_or(CpaDiscoveryUnavailable::MetadataAbsent)?;
+ let snapshot: Snapshot = serde_json::from_value(raw.clone())
+ .map_err(|_| CpaDiscoveryUnavailable::InvalidMetadata)?;
+ if snapshot.schema != "hiroute.cpa-model-discovery/v1" || snapshot.process_id == 0 {
+ return Err(CpaDiscoveryUnavailable::InvalidMetadata);
+ }
+ let mut result = Vec::new();
+ for (retained_first_failure, attempt) in
+ [(true, snapshot.first_failure), (false, snapshot.latest)]
+ {
+ let Some(attempt) = attempt else { continue };
+ if !valid(&attempt)
+ || (retained_first_failure
+ && !matches!(
+ attempt.outcome,
+ CpaDiscoveryOutcome::Failed | CpaDiscoveryOutcome::Discarded
+ ))
+ {
+ return Err(CpaDiscoveryUnavailable::InvalidMetadata);
+ }
+ result.push(CpaDiscoveryObservation::Observed {
+ process_id: snapshot.process_id,
+ evicted_accounts: snapshot.evicted_accounts,
+ retained_first_failure,
+ attempt,
+ });
+ }
+ if result.is_empty() {
+ return Err(CpaDiscoveryUnavailable::NoAttempt);
+ }
+ Ok((snapshot.registration_pending, result))
+}
+
+fn valid(attempt: &CpaDiscoveryAttempt) -> bool {
+ attempt.attempt_id != 0
+ && attempt.timings.len() <= 6
+ && [attempt.http_status, attempt.proxy_status]
+ .into_iter()
+ .flatten()
+ .all(|status| (100..=599).contains(&status))
+ && (!matches!(
+ attempt.outcome,
+ CpaDiscoveryOutcome::Failed | CpaDiscoveryOutcome::Discarded
+ ) || attempt.reason.is_some())
+}
+
+/// Only a stable catalog read with no registration in flight can end an empty wait.
+/// Missing/malformed metadata and retained older failures cannot establish this.
+pub(super) fn latest_is_terminal(value: &Value) -> bool {
+ parse(value).is_ok_and(|(pending, observations)| {
+ pending == Some(false) && observations.into_iter().any(|observation| {
+ matches!(observation, CpaDiscoveryObservation::Observed {
+ retained_first_failure: false, attempt, ..
+ } if matches!(attempt.outcome, CpaDiscoveryOutcome::Failed | CpaDiscoveryOutcome::Discarded)
+ || (attempt.phase == CpaDiscoveryPhase::Registration
+ && attempt.outcome == CpaDiscoveryOutcome::Completed
+ && attempt.model_count == Some(0)))
+ })
+ })
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/cpa-bridge/src/accounts/stock/model_discovery/tests.rs b/crates/cpa-bridge/src/accounts/stock/model_discovery/tests.rs
new file mode 100644
index 00000000..350671b0
--- /dev/null
+++ b/crates/cpa-bridge/src/accounts/stock/model_discovery/tests.rs
@@ -0,0 +1,186 @@
+use super::*;
+use hiroute_diagnostics::event::{CpaDiscoveryPhase, CpaDiscoveryReason, DiagnosticEvent};
+use hiroute_diagnostics::level::DiagnosticLevel;
+use serde_json::json;
+
+fn payload() -> Value {
+ json!({"models":[], "hiroute_model_discovery": {
+ "schema":"hiroute.cpa-model-discovery/v1", "process_id":123,
+ "evicted_accounts":0, "first_failure":null, "registration_pending":false,
+ "latest": {"attempt_id":1,"phase":"request","outcome":"failed",
+ "reason":"proxy_rejected","elapsed_ms":47,"phase_elapsed_ms":46,
+ "proxy_status":503,"timings":[{"phase":"request","outcome":"failed",
+ "reason":"proxy_rejected","elapsed_ms":46}]}
+ }})
+}
+
+#[test]
+fn retains_first_failure_after_recovery_and_deduplicates_polling() {
+ let mut observations = Observations::default();
+ let mut value = payload();
+ value["hiroute_model_discovery"]["first_failure"] =
+ value["hiroute_model_discovery"]["latest"].clone();
+ let first = observations.read(&value, Some(0));
+ assert_eq!(first.len(), 2);
+ assert_eq!(
+ DiagnosticEvent::CpaModelDiscovery(first[0].clone()).level(),
+ DiagnosticLevel::Warn
+ );
+ for elapsed in 100..1000 {
+ value["hiroute_model_discovery"]["latest"]["elapsed_ms"] = json!(elapsed);
+ assert!(observations.read(&value, Some(0)).is_empty());
+ }
+ value["hiroute_model_discovery"]["latest"] = json!({
+ "attempt_id":2,"phase":"registration","outcome":"completed",
+ "elapsed_ms":1060,"phase_elapsed_ms":1,"http_status":200,"model_count":9,
+ "timings":[{"phase":"registration","outcome":"completed","elapsed_ms":1,"model_count":9}]
+ });
+ let recovered = observations.read(&value, Some(0));
+ assert_eq!(recovered.len(), 1);
+ assert!(matches!(
+ &recovered[0].observation,
+ CpaDiscoveryObservation::Observed {
+ retained_first_failure: false,
+ attempt: CpaDiscoveryAttempt {
+ phase: CpaDiscoveryPhase::Registration,
+ model_count: Some(9),
+ ..
+ },
+ ..
+ }
+ ));
+ // A later control span still sees the retained first failure with its original duration.
+ let later = Observations::default().read(&value, Some(0));
+ assert!(matches!(
+ &later[0].observation,
+ CpaDiscoveryObservation::Observed {
+ retained_first_failure: true,
+ attempt: CpaDiscoveryAttempt {
+ reason: Some(CpaDiscoveryReason::ProxyRejected),
+ proxy_status: Some(503),
+ http_status: None,
+ elapsed_ms: 47,
+ ..
+ },
+ ..
+ }
+ ));
+ let event = DiagnosticEvent::CpaModelDiscovery(later[0].clone());
+ let encoded = serde_json::to_string(&event).unwrap();
+ assert_eq!(
+ serde_json::from_str::<DiagnosticEvent>(&encoded).unwrap(),
+ event
+ );
+}
+
+#[test]
+fn rejects_untrusted_metadata_without_forwarding_strings_or_breaking_business_response() {
+ for modification in [
+ json!({"reason":"private.example/token"}),
+ json!({"url":"https://private.example/token"}),
+ json!({"phase":"private.example/token"}),
+ json!({"http_status":999}),
+ json!({"attempt_id":0}),
+ json!({"timings": vec![json!({"phase":"request","outcome":"completed","elapsed_ms":0});7]}),
+ ] {
+ let mut value = payload();
+ for (key, item) in modification.as_object().unwrap() {
+ value["hiroute_model_discovery"]["latest"][key] = item.clone();
+ }
+ let events = Observations::default().read(&value, Some(0));
+ assert!(matches!(
+ events[0].observation,
+ CpaDiscoveryObservation::Unavailable {
+ reason: CpaDiscoveryUnavailable::InvalidMetadata
+ }
+ ));
+ assert!(
+ !serde_json::to_string(&events)
+ .unwrap()
+ .contains("private.example")
+ );
+ assert_eq!(value["models"], json!([]));
+ }
+ let absent = Observations::default().read(&json!({"models":[]}), None);
+ assert!(matches!(
+ absent[0].observation,
+ CpaDiscoveryObservation::Unavailable {
+ reason: CpaDiscoveryUnavailable::MetadataAbsent
+ }
+ ));
+}
+
+#[test]
+fn observation_limit_is_explicit_and_bounded() {
+ let mut observations = Observations::default();
+ let mut value = payload();
+ let mut emitted = Vec::new();
+ for id in 1..=200 {
+ value["hiroute_model_discovery"]["latest"]["attempt_id"] = json!(id);
+ emitted.extend(observations.read(&value, Some(0)));
+ }
+ assert_eq!(observations.seen.len(), MAX_OBSERVATIONS);
+ assert_eq!(emitted.len(), MAX_OBSERVATIONS + 1);
+ assert!(matches!(
+ emitted.last().unwrap().observation,
+ CpaDiscoveryObservation::Unavailable {
+ reason: CpaDiscoveryUnavailable::ObservationLimit
+ }
+ ));
+}
+
+#[test]
+fn registration_guard_reports_the_exact_unmet_version_checks() {
+ let mut value = payload();
+ value["hiroute_model_discovery"]["latest"] = json!({
+ "attempt_id": 2, "phase":"registration", "outcome":"discarded",
+ "reason":"account_changed", "elapsed_ms":860, "phase_elapsed_ms":0,
+ "http_status":200, "model_count":9, "generation_matches":true,
+ "registration_epoch_matches":false, "timings":[]
+ });
+ let events = Observations::default().read(&value, Some(0));
+ assert!(matches!(
+ &events[0].observation,
+ CpaDiscoveryObservation::Observed {
+ attempt: CpaDiscoveryAttempt {
+ generation_matches: Some(true),
+ registration_epoch_matches: Some(false),
+ http_status: Some(200),
+ ..
+ },
+ ..
+ }
+ ));
+}
+
+#[test]
+fn only_the_latest_valid_terminal_attempt_can_shorten_an_empty_wait() {
+ let mut value = payload();
+ assert!(latest_is_terminal(&value));
+ value["hiroute_model_discovery"]["first_failure"] =
+ value["hiroute_model_discovery"]["latest"].clone();
+ value["hiroute_model_discovery"]["latest"]["outcome"] = json!("entered");
+ value["hiroute_model_discovery"]["latest"]["reason"] = Value::Null;
+ assert!(!latest_is_terminal(&value));
+ value["hiroute_model_discovery"]["latest"]["phase"] = json!("catalog");
+ value["hiroute_model_discovery"]["latest"]["outcome"] = json!("completed");
+ assert!(!latest_is_terminal(&value));
+ value["hiroute_model_discovery"]["latest"]["phase"] = json!("registration");
+ assert!(!latest_is_terminal(&value));
+ value["hiroute_model_discovery"]["latest"]["model_count"] = json!(0);
+ assert!(latest_is_terminal(&value));
+ value["hiroute_model_discovery"]["registration_pending"] = json!(true);
+ assert!(!latest_is_terminal(&value));
+ value["hiroute_model_discovery"]
+ .as_object_mut()
+ .unwrap()
+ .remove("registration_pending");
+ assert!(!latest_is_terminal(&value));
+ value["hiroute_model_discovery"]["registration_pending"] = json!(false);
+ value["hiroute_model_discovery"]["latest"]["model_count"] = json!(1);
+ assert!(!latest_is_terminal(&value));
+ value["hiroute_model_discovery"]["latest"]["model_count"] = json!(0);
+ value["hiroute_model_discovery"]["latest"]["unexpected"] = json!(true);
+ assert!(!latest_is_terminal(&value));
+ assert!(!latest_is_terminal(&json!({"models":[]})));
+}
diff --git a/crates/cpa-bridge/src/accounts/stock/pin_tests.rs b/crates/cpa-bridge/src/accounts/stock/pin_tests.rs
index ccd308f6..1bb841ea 100644
--- a/crates/cpa-bridge/src/accounts/stock/pin_tests.rs
+++ b/crates/cpa-bridge/src/accounts/stock/pin_tests.rs
@@ -11,6 +11,7 @@ struct Fixture {
patches: Arc<AtomicUsize>,
reject_patch: Arc<AtomicBool>,
patch_delay_ms: Arc<AtomicUsize>,
+ fault: Arc<AtomicUsize>,
stop: Arc<AtomicBool>,
worker: Option<thread::JoinHandle<()>>,
}
@@ -41,10 +42,14 @@ impl Fixture {
let patches = Arc::new(AtomicUsize::new(0));
let reject_patch = Arc::new(AtomicBool::new(false));
let patch_delay_ms = Arc::new(AtomicUsize::new(0));
+ let fault = Arc::new(AtomicUsize::new(0));
let stop = Arc::new(AtomicBool::new(false));
let (count, reject, stopped) = (patches.clone(), reject_patch.clone(), stop.clone());
let delay = patch_delay_ms.clone();
+ let fault_value = fault.clone();
let worker = thread::spawn(move || {
+ let mut account_reads = 0;
+ let mut model_reads = 0;
for stream in listener.incoming() {
let mut stream = stream.unwrap();
if stopped.load(Ordering::SeqCst) {
@@ -56,9 +61,16 @@ impl Fixture {
let mut bytes = Vec::new();
let mut byte = [0];
while !bytes.ends_with(b"\r\n\r\n") {
- stream.read_exact(&mut byte).unwrap();
+ if stream.read_exact(&mut byte).is_err() {
+ break;
+ }
bytes.push(byte[0]);
}
+ // A caller may exhaust its shared budget after connect or a partial
+ // write. That abandoned request must not kill the fixture server.
+ if !bytes.ends_with(b"\r\n\r\n") {
+ continue;
+ }
let header = String::from_utf8(bytes).unwrap();
let length: usize = header
.lines()
@@ -67,7 +79,9 @@ impl Fixture {
.parse()
.unwrap();
let mut body = vec![0; length];
- stream.read_exact(&mut body).unwrap();
+ if stream.read_exact(&mut body).is_err() {
+ continue;
+ }
let (status, body) = if header.starts_with("PATCH ") {
count.fetch_add(1, Ordering::SeqCst);
thread::sleep(Duration::from_millis(delay.load(Ordering::SeqCst) as u64));
@@ -79,20 +93,59 @@ impl Fixture {
(200, "{}".to_owned())
}
} else if header.starts_with("GET /v0/management/auth-files?name=") {
- (
- 200,
- String::from_utf8(super::tests::oauth_response("")).unwrap(),
- )
+ account_reads += 1;
+ let mut value: Value =
+ serde_json::from_slice(&super::tests::oauth_response("")).unwrap();
+ if account_reads > 1 && fault_value.load(Ordering::SeqCst) == 4 {
+ value["files"][0]["auth_index"] = serde_json::json!("idx-changed");
+ }
+ if fault_value.load(Ordering::SeqCst) == 5 {
+ value["files"][0]["request_retry"] = serde_json::json!(1);
+ }
+ (200, value.to_string())
} else if header.starts_with("GET /v0/management/auth-files/models?") {
- (
- 200,
- r#"{"models":[{"id":"hiroute-codex-current/future-model"}]}"#.to_owned(),
- )
+ model_reads += 1;
+ let body = match fault_value.load(Ordering::SeqCst) {
+ 1 => r#"{"models":[]}"#.to_owned(),
+ 2 => r#"{"models":[{"id":"other-prefix/future-model"}]}"#.to_owned(),
+ 9 => serde_json::json!({"models":[{"id":format!("hiroute-codex-current/{}", "a".repeat(257))}]}).to_string(),
+ fault @ 15..=16 if model_reads < 3 => {
+ let latest = if fault == 15 {
+ serde_json::json!({"attempt_id":1,"phase":"registration","outcome":"discarded","reason":"account_changed","elapsed_ms":50,"phase_elapsed_ms":0,"timings":[]})
+ } else {
+ serde_json::json!({"attempt_id":2,"phase":"registration","outcome":"completed","model_count":1,"elapsed_ms":60,"phase_elapsed_ms":0,"timings":[]})
+ };
+ serde_json::json!({"models":[],"hiroute_model_discovery":{
+ "schema":"hiroute.cpa-model-discovery/v1","process_id":123,
+ "evicted_accounts":0,"first_failure":null,"latest":latest,
+ "registration_pending":fault == 15
+ }}).to_string()
+ },
+ fault @ 10..=14 => {
+ let empty = fault != 11 && (fault != 12 || model_reads < 3);
+ let (phase, outcome, reason) = match fault {
+ 12 => ("request", "entered", None),
+ 13 => ("registration", "completed", Some("empty_after_filtering")),
+ 14 => ("registration", "discarded", Some("account_changed")),
+ _ => ("request", "failed", Some("timeout")),
+ };
+ serde_json::json!({
+ "models": if empty {serde_json::json!([])} else {serde_json::json!([{"id":"hiroute-codex-current/future-model"}])},
+ "hiroute_model_discovery": {"schema":"hiroute.cpa-model-discovery/v1", "process_id":123,"evicted_accounts":0,"first_failure":null,
+ "registration_pending":false,
+ "latest":{"attempt_id":1,"phase":phase,"outcome":outcome,"reason":reason,"model_count":0,"elapsed_ms":50,"phase_elapsed_ms":50,"timings":[]}}
+ }).to_string()
+ },
+ _ => r#"{"models":[{"id":"hiroute-codex-current/future-model"}]}"#.to_owned(),
+ };
+ (200, body)
} else if header.starts_with("GET /v1/models ") {
- (
- 200,
- r#"{"data":[{"id":"hiroute-codex-current/future-model"}]}"#.to_owned(),
- )
+ let body = if fault_value.load(Ordering::SeqCst) == 3 {
+ r#"{"data":[]}"#
+ } else {
+ r#"{"data":[{"id":"hiroute-codex-current/future-model"}]}"#
+ };
+ (200, body.to_owned())
} else {
panic!("unexpected request: {}", header.lines().next().unwrap());
};
@@ -101,9 +154,14 @@ impl Fixture {
"HTTP/1.1 {status} OK\r\nX-CPA-Version: 8.0.4-hiroute.4\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}",
body.len()
);
- // The legacy-deadline negative case deliberately closes this socket early.
- if delay.load(Ordering::SeqCst) == 0 {
- written.unwrap();
+ if let Err(error) = written {
+ assert!(matches!(
+ error.kind(),
+ std::io::ErrorKind::BrokenPipe
+ | std::io::ErrorKind::ConnectionReset
+ | std::io::ErrorKind::TimedOut
+ | std::io::ErrorKind::WouldBlock
+ ));
}
}
});
@@ -113,6 +171,7 @@ impl Fixture {
patches,
reject_patch,
patch_delay_ms,
+ fault,
stop,
worker: Some(worker),
}
@@ -141,10 +200,77 @@ impl Fixture {
"8.0.4-hiroute.4",
timeout,
refresh,
+ &hiroute_diagnostics::context::DiagnosticHandle::noop().context(),
)
}
}
+#[path = "diagnostic_tests.rs"]
+mod diagnostic_tests;
+
+#[test]
+fn terminal_empty_discovery_fails_without_spending_the_control_budget() {
+ for fault in [10, 13, 14] {
+ let fixture = Fixture::new();
+ fixture.fault.store(fault, Ordering::SeqCst);
+ let started = Instant::now();
+ assert!(matches!(
+ fixture.discover(false),
+ Err(AccountDiscoveryError::PinNotApplied)
+ ));
+ assert!(started.elapsed() < Duration::from_millis(500));
+ assert_eq!(fixture.patches.load(Ordering::SeqCst), 0);
+ }
+}
+
+#[test]
+fn pending_discovery_and_retained_catalog_keep_their_existing_meaning() {
+ for fault in [11, 12] {
+ let fixture = Fixture::new();
+ fixture.fault.store(fault, Ordering::SeqCst);
+ assert_eq!(
+ fixture.discover(false).unwrap()[0].observed_model_ids,
+ BTreeSet::from(["future-model".into()])
+ );
+ assert_eq!(fixture.patches.load(Ordering::SeqCst), 0);
+ }
+}
+
+#[test]
+fn authorization_handoff_gap_keeps_waiting_for_the_current_catalog() {
+ assert_concurrent_catalog_recovers(15);
+}
+
+#[test]
+fn mixed_empty_catalog_and_success_snapshot_keeps_waiting() {
+ assert_concurrent_catalog_recovers(16);
+}
+
+fn assert_concurrent_catalog_recovers(fault: usize) {
+ let fixture = Fixture::new();
+ fixture.fault.store(fault, Ordering::SeqCst);
+ assert_eq!(
+ fixture.discover(false).unwrap()[0].observed_model_ids,
+ BTreeSet::from(["future-model".into()])
+ );
+ assert_eq!(fixture.patches.load(Ordering::SeqCst), 0);
+}
+
+#[test]
+fn fixture_survives_abandoned_deadline_connections() {
+ for partial in [
+ b"".as_slice(),
+ b"GET /v0/management/auth-files?name=codex-a.json HTTP/1.1\r\n".as_slice(),
+ b"PATCH /v0/management/auth-files/fields HTTP/1.1\r\nContent-Length: 3\r\n\r\nx".as_slice(),
+ ] {
+ let fixture = Fixture::new();
+ let mut stream = std::net::TcpStream::connect(fixture.address).unwrap();
+ stream.write_all(partial).unwrap();
+ drop(stream);
+ assert_eq!(fixture.discover(false).unwrap().len(), 1);
+ }
+}
+
#[test]
fn production_control_budget_covers_synchronous_refresh_and_pin_readback() {
let fixture = Fixture::new();
@@ -233,6 +359,7 @@ fn live_managed_cpa_pin_reads() {
field("version"),
Duration::from_secs(5),
false,
+ &hiroute_diagnostics::context::DiagnosticHandle::noop().context(),
)
.unwrap();
assert_eq!(accounts.len(), 1);
diff --git a/crates/cpa-bridge/src/accounts/stock/validation.rs b/crates/cpa-bridge/src/accounts/stock/validation.rs
index b624b42f..c60445aa 100644
--- a/crates/cpa-bridge/src/accounts/stock/validation.rs
+++ b/crates/cpa-bridge/src/accounts/stock/validation.rs
@@ -19,10 +19,11 @@ struct PersistedControls<'a> {
disable_cooling: Option<bool>,
}
-pub(super) fn persisted_controls_match(
+pub(super) fn observe_persisted_controls(
auth_dir: &Path,
name: &str,
prefix: &str,
+ checks: &mut hiroute_diagnostics::event::CpaPinChecks,
) -> Result<bool, AccountDiscoveryError> {
if Path::new(name).file_name().and_then(|value| value.to_str()) != Some(name) {
return Err(AccountDiscoveryError::InvalidAccount);
@@ -41,9 +42,12 @@ pub(super) fn persisted_controls_match(
}
let controls: PersistedControls<'_> =
serde_json::from_slice(bytes.as_slice()).map_err(AccountDiscoveryError::Json)?;
- Ok(controls.prefix == Some(prefix)
- && controls.request_retry == Some(0)
- && controls.disable_cooling == Some(true))
+ checks.persisted_prefix_matches = Some(controls.prefix == Some(prefix));
+ checks.persisted_retry_zero = Some(controls.request_retry == Some(0));
+ checks.persisted_cooling_disabled = Some(controls.disable_cooling == Some(true));
+ Ok(checks.persisted_prefix_matches == Some(true)
+ && checks.persisted_retry_zero == Some(true)
+ && checks.persisted_cooling_disabled == Some(true))
}
pub(super) fn validate_management_response(
diff --git a/crates/cpa-bridge/src/accounts/stock/version_sync_tests.rs b/crates/cpa-bridge/src/accounts/stock/version_sync_tests.rs
index 92837ade..cc3a9c9c 100644
--- a/crates/cpa-bridge/src/accounts/stock/version_sync_tests.rs
+++ b/crates/cpa-bridge/src/accounts/stock/version_sync_tests.rs
@@ -128,6 +128,7 @@ fn check_stale_manager(old: Option<&str>) {
"8.0.4-hiroute.4",
Duration::from_secs(2),
true,
+ &hiroute_diagnostics::context::DiagnosticHandle::noop().context(),
);
stop.store(true, Ordering::SeqCst);
let _ = TcpStream::connect(address);
diff --git a/crates/cpa-bridge/src/lib.rs b/crates/cpa-bridge/src/lib.rs
index 4d7c0f2e..34b28132 100644
--- a/crates/cpa-bridge/src/lib.rs
+++ b/crates/cpa-bridge/src/lib.rs
@@ -64,7 +64,7 @@ pub use subscription::{
/// Stock CPA release whose CLI/config/management contract this implementation was grounded on.
pub const STOCK_CPA_CONTRACT_VERSION: &str = "7.2.140";
/// Exact managed binary: upstream protocol contract plus the private parent-pipe bootstrap.
-pub const MANAGED_CPA_ARTIFACT_VERSION: &str = "8.0.4-hiroute.5";
+pub const MANAGED_CPA_ARTIFACT_VERSION: &str = "8.0.4-hiroute.8";
/// The management PATCH synchronously refreshes upstream models before local pin checks.
/// Its whole-flow budget must leave room beyond CPA's five-second upstream deadline.
pub const MANAGED_CPA_CONTROL_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(20);
diff --git a/crates/cpa-bridge/src/managed_sessions/cpa_oauth_fixture.py b/crates/cpa-bridge/src/managed_sessions/cpa_oauth_fixture.py
index 62fd8310..634cf509 100644
--- a/crates/cpa-bridge/src/managed_sessions/cpa_oauth_fixture.py
+++ b/crates/cpa-bridge/src/managed_sessions/cpa_oauth_fixture.py
@@ -49,6 +49,16 @@ def credential():
def record_catalog(event, **facts):
+ # A test can hold each external inventory response while checking that its
+ # caller has released shared daemon storage. Production never loads this file.
+ if event == 'inventory' and (controls / 'probe-catalog-lock').exists():
+ probe = controls / ('catalog-probe-' + str(time.monotonic_ns()))
+ probe.touch(mode=0o600)
+ deadline = time.monotonic() + 3
+ while not probe.with_suffix('.resume').exists():
+ if time.monotonic() >= deadline:
+ raise RuntimeError('catalog lock probe was not released')
+ time.sleep(0.005)
if not (controls / 'record-model-catalog').exists():
return
descriptor = os.open(controls / 'catalog.jsonl',
diff --git a/crates/cpa-bridge/src/runtime/routing_batch.rs b/crates/cpa-bridge/src/runtime/routing_batch.rs
index 27535c0b..0eb20d31 100644
--- a/crates/cpa-bridge/src/runtime/routing_batch.rs
+++ b/crates/cpa-bridge/src/runtime/routing_batch.rs
@@ -280,6 +280,7 @@ impl ManagedCpaRuntime {
&live.artifact.version().to_string(),
self.spec.control_timeout,
expected.is_some(),
+ &self.diagnostics.handle().context(),
) {
Ok(discovered) => {
self.emit_stage(
@@ -294,7 +295,7 @@ impl ManagedCpaRuntime {
self.emit_stage(
CpaStageKind::ControlCall,
CpaStageOutcome::Failed {
- code: control_failure_code(&error),
+ code: error.diagnostic_code(),
},
control_started.elapsed().as_millis() as u64,
inner.restart_count,
@@ -376,23 +377,3 @@ impl ManagedCpaRuntime {
Ok(result)
}
}
-
-fn control_failure_code(error: &AccountDiscoveryError) -> CpaFailureCode {
- use crate::http::LoopbackHttpError;
- match error {
- AccountDiscoveryError::Http(LoopbackHttpError::Io(error)) => {
- if matches!(
- error.kind(),
- std::io::ErrorKind::TimedOut | std::io::ErrorKind::WouldBlock
- ) {
- CpaFailureCode::ControlTimeout
- } else {
- CpaFailureCode::ControlTransport
- }
- }
- AccountDiscoveryError::ManagementAuthentication
- | AccountDiscoveryError::DownstreamAuthentication => CpaFailureCode::ControlAuthentication,
- AccountDiscoveryError::PinNotApplied => CpaFailureCode::ControlPinNotApplied,
- _ => CpaFailureCode::ControlRejected,
- }
-}
diff --git a/crates/cpa-bridge/src/runtime/tests.rs b/crates/cpa-bridge/src/runtime/tests.rs
index d2814601..cfb37949 100644
--- a/crates/cpa-bridge/src/runtime/tests.rs
+++ b/crates/cpa-bridge/src/runtime/tests.rs
@@ -223,6 +223,7 @@ impl CpaControlPlane for FakeControl {
expected_version: &str,
timeout: Duration,
refresh_models: bool,
+ _diagnostics: &hiroute_diagnostics::context::DiagnosticContext,
) -> Result<Vec<AccountSnapshotRecord>, AccountDiscoveryError> {
self.discoveries.fetch_add(1, Ordering::SeqCst);
self.refresh_requested
diff --git a/crates/cpa-bridge/src/runtime/tests/cancelled_start.rs b/crates/cpa-bridge/src/runtime/tests/cancelled_start.rs
index fbd5a7b9..8bbf9584 100644
--- a/crates/cpa-bridge/src/runtime/tests/cancelled_start.rs
+++ b/crates/cpa-bridge/src/runtime/tests/cancelled_start.rs
@@ -77,9 +77,17 @@ impl CpaControlPlane for ReadyControl {
version: &str,
timeout: Duration,
refresh: bool,
+ diagnostics: &hiroute_diagnostics::context::DiagnosticContext,
) -> Result<Vec<AccountSnapshotRecord>, AccountDiscoveryError> {
self.control.discover_and_pin(
- address, auth_dir, identities, secrets, version, timeout, refresh,
+ address,
+ auth_dir,
+ identities,
+ secrets,
+ version,
+ timeout,
+ refresh,
+ diagnostics,
)
}
}
diff --git a/crates/cpa-bridge/src/runtime/tests/owner_rollback.rs b/crates/cpa-bridge/src/runtime/tests/owner_rollback.rs
index e37ab024..63f2ff87 100644
--- a/crates/cpa-bridge/src/runtime/tests/owner_rollback.rs
+++ b/crates/cpa-bridge/src/runtime/tests/owner_rollback.rs
@@ -29,6 +29,7 @@ impl CpaControlPlane for CancellingControl {
_version: &str,
_timeout: Duration,
_refresh: bool,
+ _diagnostics: &hiroute_diagnostics::context::DiagnosticContext,
) -> Result<Vec<AccountSnapshotRecord>, AccountDiscoveryError> {
panic!("a rejected orphan must never discover accounts")
}
diff --git a/crates/cpa-bridge/src/runtime/tests/request_io.rs b/crates/cpa-bridge/src/runtime/tests/request_io.rs
index 1295474d..6c40e89a 100644
--- a/crates/cpa-bridge/src/runtime/tests/request_io.rs
+++ b/crates/cpa-bridge/src/runtime/tests/request_io.rs
@@ -139,6 +139,7 @@ impl CpaControlPlane for GatedControl {
version: &str,
timeout: Duration,
refresh_models: bool,
+ diagnostics: &hiroute_diagnostics::context::DiagnosticContext,
) -> Result<Vec<AccountSnapshotRecord>, AccountDiscoveryError> {
self.inner.discover_and_pin(
address,
@@ -148,6 +149,7 @@ impl CpaControlPlane for GatedControl {
version,
timeout,
refresh_models,
+ diagnostics,
)
}
}
diff --git a/crates/daemon/src/console/tests.rs b/crates/daemon/src/console/tests.rs
index c3d438e6..21e625bc 100644
--- a/crates/daemon/src/console/tests.rs
+++ b/crates/daemon/src/console/tests.rs
@@ -351,6 +351,18 @@ pub(super) fn installed_test_layout(test: &str) -> bool {
let cli = staged.path().join("hiroute");
std::fs::copy(std::env::current_exe().unwrap(), &daemon).unwrap();
std::fs::copy(&daemon, &cli).unwrap();
+ #[cfg(target_os = "macos")]
+ for executable in [&daemon, &cli] {
+ // macOS can reject a copied Rust test executable's CT signature before
+ // the installed-layout child reaches any assertion. Sign only these
+ // private, self-built fixture copies; production signing is unchanged.
+ let status = std::process::Command::new("/usr/bin/codesign")
+ .args(["--force", "--sign", "-"])
+ .arg(executable)
+ .status()
+ .unwrap();
+ assert!(status.success(), "private installed fixture signing failed");
+ }
let bin = home.join(".local/bin");
std::fs::create_dir_all(&bin).unwrap();
std::os::unix::fs::symlink(&cli, bin.join("hiroute")).unwrap();
diff --git a/crates/daemon/src/control/bin.rs b/crates/daemon/src/control/bin.rs
index a54655dd..4aaa27fc 100644
--- a/crates/daemon/src/control/bin.rs
+++ b/crates/daemon/src/control/bin.rs
@@ -23,6 +23,7 @@ use hiroute_local_storage::ApplyCapabilityRegistrationV1;
use serde::Deserialize;
use zeroize::{Zeroize, Zeroizing};
+mod protected_exchange;
mod ready;
#[cfg(any(unix, windows))]
mod standalone;
@@ -486,41 +487,17 @@ fn run_all(
#[cfg(unix)]
protected_inputs.poll(&role)?;
for frame in capabilities.read_available()? {
- let registration_id = frame.registration_id();
if acknowledgements.is_none() {
return Err(
"v2 capability registration requires a protected acknowledgement channel"
.into(),
);
}
- match frame {
- ProtectedChannelFrame::Upgrade(request) => {
- let status = role.upgrade_status(request.action, request.registration_id)?;
- let writer = acknowledgements.as_mut().expect("checked channel");
- serde_json::to_writer(&mut *writer, &status)
- .map_err(|_| "upgrade acknowledgement failed")?;
- use std::io::Write;
- writer
- .write_all(b"\n")
- .map_err(|_| "upgrade acknowledgement failed")?;
- writer
- .flush()
- .map_err(|_| "upgrade acknowledgement failed")?;
- continue;
- }
- ProtectedChannelFrame::Apply { registration, .. } => {
- role.register_apply_capability(registration)?;
- }
- ProtectedChannelFrame::InputRegister {
- candidate, secret, ..
- } => role.register_manual_protected_input(candidate, secret)?,
- ProtectedChannelFrame::InputRelease { candidate_ref, .. } => {
- role.release_manual_protected_input(&candidate_ref)?;
- }
- }
- write_ack(
+ protected_exchange::process(
+ &role,
+ frame,
acknowledgements.as_mut().expect("checked channel"),
- &registration_id,
+ diagnostics,
)?;
}
std::thread::sleep(Duration::from_millis(5));
diff --git a/crates/daemon/src/control/protected_exchange.rs b/crates/daemon/src/control/protected_exchange.rs
new file mode 100644
index 00000000..880e5ca3
--- /dev/null
+++ b/crates/daemon/src/control/protected_exchange.rs
@@ -0,0 +1,79 @@
+//! Production launcher registration and ACK diagnostics share an irreversible correlation.
+use super::*;
+use hiroute_diagnostics::{correlation::CorrelationDomain, event::*};
+
+pub(super) fn process(
+ role: &hiroute_daemon::RoleAllHandle,
+ frame: ProtectedChannelFrame,
+ writer: &mut std::fs::File,
+ diagnostics: &DiagnosticRuntime,
+) -> Result<(), String> {
+ let id = frame.registration_id();
+ let kind = match &frame {
+ ProtectedChannelFrame::Upgrade(_) => ProtectedExchangeKind::Upgrade,
+ ProtectedChannelFrame::Apply { .. } => ProtectedExchangeKind::Grant,
+ ProtectedChannelFrame::InputRegister { .. } => ProtectedExchangeKind::InputRegister,
+ ProtectedChannelFrame::InputRelease { .. } => ProtectedExchangeKind::InputRelease,
+ };
+ let started = std::time::Instant::now();
+ let mut phase = ProtectedExchangePhase::Register;
+ let result = (|| {
+ match frame {
+ ProtectedChannelFrame::Upgrade(request) => {
+ let status = role.upgrade_status(request.action, request.registration_id)?;
+ phase = ProtectedExchangePhase::AcknowledgementWrite;
+ return write_status(writer, &status);
+ }
+ ProtectedChannelFrame::Apply { registration, .. } => {
+ role.register_apply_capability(registration)?
+ }
+ ProtectedChannelFrame::InputRegister {
+ candidate, secret, ..
+ } => role.register_manual_protected_input(candidate, secret)?,
+ ProtectedChannelFrame::InputRelease { candidate_ref, .. } => {
+ role.release_manual_protected_input(&candidate_ref)?
+ }
+ }
+ phase = ProtectedExchangePhase::AcknowledgementWrite;
+ write_ack(writer, &id)
+ })();
+ diagnostics.emit(DiagnosticEvent::ProtectedExchange(ProtectedExchange {
+ kind,
+ phase,
+ registration_token: diagnostics
+ .handle()
+ .token(CorrelationDomain::ProtectedRegistration, &id),
+ elapsed_ms: started.elapsed().as_millis() as u64,
+ error: result
+ .as_ref()
+ .err()
+ .map(|_| ProtectedExchangeError::Unavailable),
+ authority_lost: false,
+ }));
+ result
+}
+
+pub(super) fn write_status(
+ writer: &mut std::fs::File,
+ status: &hiroute_host_runtime::LauncherUpgradeStatus,
+) -> Result<(), String> {
+ let mut bytes = serde_json::to_vec(status).map_err(|_| "upgrade response invalid")?;
+ bytes.push(b'\n');
+ let mut bytes = bytes.as_slice();
+ let deadline = std::time::Instant::now() + PROTECTED_FRAME_DEADLINE;
+ while !bytes.is_empty() {
+ if std::time::Instant::now() >= deadline {
+ return Err("upgrade acknowledgement timed out".into());
+ }
+ match writer.write(bytes) {
+ Ok(0) => return Err("upgrade channel closed".into()),
+ Ok(count) => bytes = &bytes[count..],
+ Err(error) if error.kind() == std::io::ErrorKind::Interrupted => {}
+ Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => {
+ std::thread::sleep(Duration::from_millis(5))
+ }
+ Err(_) => return Err("upgrade channel unavailable".into()),
+ }
+ }
+ Ok(())
+}
diff --git a/crates/daemon/src/control/runtime/routing.rs b/crates/daemon/src/control/runtime/routing.rs
index 1a28d745..a4bd4e99 100644
--- a/crates/daemon/src/control/runtime/routing.rs
+++ b/crates/daemon/src/control/runtime/routing.rs
@@ -810,6 +810,9 @@ impl LocalControlAdapter {
expected_revisions
.dependencies
.insert("release.model_data".into(), provenance.release_sequence);
+ // Revalidation can wait for CPA control or lifecycle work. Native
+ // grants use this same store mutex and have a shorter ACK deadline.
+ drop(stores);
if let Some(batch) = cpa_batch
&& !batch.finish().unwrap_or(false)
{
diff --git a/crates/daemon/src/control/runtime/subscriptions/login_admission_tests.rs b/crates/daemon/src/control/runtime/subscriptions/login_admission_tests.rs
index 8cc151db..9f5620df 100644
--- a/crates/daemon/src/control/runtime/subscriptions/login_admission_tests.rs
+++ b/crates/daemon/src/control/runtime/subscriptions/login_admission_tests.rs
@@ -39,6 +39,8 @@ use super::super::{LocalControlAdapter, ProductionControlRuntime, RuntimeOpenOve
#[path = "discovery_tests.rs"]
mod discovery_tests;
+mod routing_lock_tests;
+
struct Fixture {
runtime: ProductionControlRuntime,
runtimes: Arc<ManagedCpaRuntimeSet>,
diff --git a/crates/daemon/src/control/runtime/subscriptions/login_admission_tests/routing_lock_tests.rs b/crates/daemon/src/control/runtime/subscriptions/login_admission_tests/routing_lock_tests.rs
new file mode 100644
index 00000000..4aa305d3
--- /dev/null
+++ b/crates/daemon/src/control/runtime/subscriptions/login_admission_tests/routing_lock_tests.rs
@@ -0,0 +1,78 @@
+use super::*;
+use hiroute_application::control::RoutingFactsPort;
+use std::time::Instant;
+
+#[test]
+fn cpa_snapshot_revalidation_does_not_block_native_grant_registration() {
+ if crate::test_support::isolated_agent_home(concat!(
+ "control::runtime::subscriptions::login_admission_tests::routing_lock_tests::",
+ "cpa_snapshot_revalidation_does_not_block_native_grant_registration"
+ )) {
+ return;
+ }
+ let fixture = Fixture::new();
+ let login = fixture.authorize(SubscriptionLoginProviderV1::Codex);
+ let checked = fixture.check(&login);
+ fixture.save(fixture.candidate_request(&checked, "snapshot-lock-source"));
+ fs::write(fixture.root.path().join("probe-catalog-lock"), b"probe").unwrap();
+ let mut blocked = 0;
+ let mut probes = 0;
+ std::thread::scope(|scope| {
+ let (sender, receiver) = mpsc::channel();
+ let adapter = fixture.adapter();
+ scope.spawn(move || {
+ sender
+ .send(adapter.routing_compilation_snapshot(&WorkspaceId::default()))
+ .unwrap();
+ });
+ let deadline = Instant::now() + Duration::from_secs(15);
+ loop {
+ for entry in fs::read_dir(fixture.root.path()).unwrap() {
+ let path = entry.unwrap().path();
+ if !path
+ .file_name()
+ .unwrap()
+ .to_string_lossy()
+ .starts_with("catalog-probe-")
+ || path.extension().is_some()
+ || path.with_extension("resume").exists()
+ {
+ continue;
+ }
+ probes += 1;
+ // The external CPA response is still held. A native registration
+ // must not wait for its control deadline while holding up all ACKs.
+ let available = fixture.adapter().stores.try_lock().is_ok();
+ if !available {
+ blocked += 1;
+ } else {
+ let registration = hiroute_local_storage::ApplyCapabilityRegistrationV1::from_protected_launcher(
+ format!("native-grant-lock-probe-{probes:040}"), "desktop", WorkspaceId::default(),
+ "ListSessionsV2", hiroute_domain::CanonicalDigest::of_bytes(b"bounded probe"),
+ hiroute_domain::RevisionSetV1 { target: 0, dependencies: Default::default() },
+ std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_secs() as i64 + 60,
+ ).unwrap();
+ fixture
+ .runtime
+ .register_apply_capability(registration)
+ .unwrap();
+ }
+ fs::write(path.with_extension("resume"), b"resume").unwrap();
+ }
+ if let Ok(result) = receiver.try_recv() {
+ assert!(result.is_ok());
+ break;
+ }
+ assert!(Instant::now() < deadline, "routing lock probe stalled");
+ std::thread::sleep(Duration::from_millis(5));
+ }
+ });
+ assert!(
+ probes >= 2,
+ "must exercise initial and final CPA observations"
+ );
+ assert_eq!(
+ blocked, 0,
+ "external CPA observation held shared storage and blocked native grants"
+ );
+}
diff --git a/crates/daemon/tests/subscription_management_product.rs b/crates/daemon/tests/subscription_management_product.rs
index 027b62d4..35c1bce6 100644
--- a/crates/daemon/tests/subscription_management_product.rs
+++ b/crates/daemon/tests/subscription_management_product.rs
@@ -37,7 +37,7 @@ import re
import sys
import urllib.parse
-VERSION = "8.0.4-hiroute.5"
+VERSION = "8.0.4-hiroute.8"
MANAGED_NAME = "hiroute-managed-codex.json"
MODEL_ID = "gpt-5.3-codex-spark"
ADDED_MODEL_ID = "gpt-5.5"
diff --git a/crates/daemon/tests/support/cpa_upstream.py b/crates/daemon/tests/support/cpa_upstream.py
index 81219ac7..17128ef1 100644
--- a/crates/daemon/tests/support/cpa_upstream.py
+++ b/crates/daemon/tests/support/cpa_upstream.py
@@ -13,7 +13,7 @@ import threading
import time
from urllib.parse import parse_qs, urlparse
-VERSION = '8.0.4-hiroute.5'
+VERSION = '8.0.4-hiroute.8'
controls = Path(__file__).resolve().parent
model_override = controls / 'model-id'
MODEL = (model_override.read_text().strip()
diff --git a/crates/daemon/tests/support/standalone_headless_product.py b/crates/daemon/tests/support/standalone_headless_product.py
index e37ce6eb..d43a7186 100644
--- a/crates/daemon/tests/support/standalone_headless_product.py
+++ b/crates/daemon/tests/support/standalone_headless_product.py
@@ -381,7 +381,7 @@ for line in sys.stdin:
'--version', '0.1.0-headless-product', '--revision', self.sha,
'--hiroute', str(candidate_hiroute),
'--hirouted', str(candidate_hirouted),
- '--cpa-binary', str(cpa), '--cpa-version', '8.0.4-hiroute.5',
+ '--cpa-binary', str(cpa), '--cpa-version', '8.0.4-hiroute.8',
'--cpa-license', str(license_path),
'--notices', str(package_source / 'notices'), '--console-assets', str(staged_console),
'--output', str(self.package),
diff --git a/crates/diagnostics/src/correlation.rs b/crates/diagnostics/src/correlation.rs
index 4273ca70..9c1d3222 100644
--- a/crates/diagnostics/src/correlation.rs
+++ b/crates/diagnostics/src/correlation.rs
@@ -23,6 +23,7 @@ const TOKEN_DOMAIN_PREFIX: &[u8] = b"hiroute.diagnostic.token.v1";
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CorrelationDomain {
ControlRequest,
+ ProtectedRegistration,
ModelRequest,
Decision,
Attempt,
@@ -39,6 +40,7 @@ impl CorrelationDomain {
fn tag(self) -> &'static [u8] {
match self {
CorrelationDomain::ControlRequest => b"control_request",
+ CorrelationDomain::ProtectedRegistration => b"protected_registration",
CorrelationDomain::ModelRequest => b"model_request",
CorrelationDomain::Decision => b"decision",
CorrelationDomain::Attempt => b"attempt",
diff --git a/crates/diagnostics/src/event/cpa_control.rs b/crates/diagnostics/src/event/cpa_control.rs
new file mode 100644
index 00000000..bb516c01
--- /dev/null
+++ b/crates/diagnostics/src/event/cpa_control.rs
@@ -0,0 +1,99 @@
+//! Bounded CPA discovery facts. No account IDs, model IDs, paths or response text.
+
+use serde::{Deserialize, Serialize};
+
+use super::CpaStageOutcome;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct CpaControl {
+ pub phase: CpaControlPhase,
+ pub outcome: CpaStageOutcome,
+ pub elapsed_ms: u64,
+ pub total_elapsed_ms: u64,
+ pub budget_ms: u64,
+ pub refresh_models: bool,
+ /// Ordinal within this discovery span, never an account identity.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub account_ordinal: Option<u32>,
+ pub polls: u32,
+ pub checks: CpaPinChecks,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum CpaControlPhase {
+ InventoryRead,
+ AccountRead,
+ ControlsRead,
+ ControlsPatch,
+ AccountPin,
+ CatalogPin,
+}
+
+/// Absent means this check was not reached. False and unobserved are distinct.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct CpaPinChecks {
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub account_index_matches: Option<bool>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub account_retry_zero: Option<bool>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub persisted_prefix_matches: Option<bool>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub persisted_retry_zero: Option<bool>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub persisted_cooling_disabled: Option<bool>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub account_models_nonempty: Option<bool>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub account_models_prefixed: Option<bool>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub account_model_ids_valid: Option<bool>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub account_model_count: Option<u32>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub catalog_missing_count: Option<u32>,
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use crate::event::{CpaFailureCode, DiagnosticEvent};
+ use crate::level::DiagnosticLevel;
+
+ #[test]
+ fn old_stage_records_remain_readable_and_pin_facts_are_closed() {
+ let old: DiagnosticEvent = serde_json::from_str(
+ r#"{"cpa_stage":{"stage":"control_call","elapsed_ms":20000,"restart_generation":0}}"#,
+ )
+ .unwrap();
+ assert!(matches!(old, DiagnosticEvent::CpaStage(_)));
+ let checks: CpaPinChecks =
+ serde_json::from_str(r#"{"account_models_nonempty":false}"#).unwrap();
+ assert_eq!(checks.account_models_nonempty, Some(false));
+ assert_eq!(checks.account_models_prefixed, None);
+ assert!(serde_json::from_str::<CpaPinChecks>(r#"{"account":"private"}"#).is_err());
+ let event = DiagnosticEvent::CpaControl(CpaControl {
+ phase: CpaControlPhase::AccountPin,
+ outcome: CpaStageOutcome::Failed {
+ code: CpaFailureCode::ControlPinNotApplied,
+ },
+ elapsed_ms: 20000,
+ total_elapsed_ms: 20000,
+ budget_ms: 20000,
+ refresh_models: false,
+ account_ordinal: Some(0),
+ polls: 900,
+ checks,
+ });
+ assert_eq!(event.level(), DiagnosticLevel::Warn);
+ let json = serde_json::to_string(&event).unwrap();
+ assert!(json.len() < 1024);
+ assert_eq!(
+ serde_json::from_str::<DiagnosticEvent>(&json).unwrap(),
+ event
+ );
+ }
+}
diff --git a/crates/diagnostics/src/event/cpa_model_discovery.rs b/crates/diagnostics/src/event/cpa_model_discovery.rs
new file mode 100644
index 00000000..6b7909aa
--- /dev/null
+++ b/crates/diagnostics/src/event/cpa_model_discovery.rs
@@ -0,0 +1,116 @@
+//! Closed, bounded facts observed inside CPA; never upstream error text.
+
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct CpaModelDiscovery {
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub account_ordinal: Option<u32>,
+ pub observation: CpaDiscoveryObservation,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "status", rename_all = "snake_case", deny_unknown_fields)]
+pub enum CpaDiscoveryObservation {
+ Observed {
+ process_id: u32,
+ evicted_accounts: u64,
+ /// Retained by CPA from an earlier attempt, possibly before this span.
+ retained_first_failure: bool,
+ attempt: CpaDiscoveryAttempt,
+ },
+ Unavailable {
+ reason: CpaDiscoveryUnavailable,
+ },
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum CpaDiscoveryUnavailable {
+ MetadataAbsent,
+ InvalidMetadata,
+ NoAttempt,
+ ObservationLimit,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct CpaDiscoveryAttempt {
+ pub attempt_id: u64,
+ pub phase: CpaDiscoveryPhase,
+ pub outcome: CpaDiscoveryOutcome,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub reason: Option<CpaDiscoveryReason>,
+ pub elapsed_ms: u64,
+ pub phase_elapsed_ms: u64,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub http_status: Option<u16>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub proxy_status: Option<u16>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub model_count: Option<u64>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub generation_matches: Option<bool>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub registration_epoch_matches: Option<bool>,
+ pub timings: Vec<CpaDiscoveryTiming>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct CpaDiscoveryTiming {
+ pub phase: CpaDiscoveryPhase,
+ pub outcome: CpaDiscoveryOutcome,
+ pub elapsed_ms: u64,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub reason: Option<CpaDiscoveryReason>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub model_count: Option<u64>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum CpaDiscoveryPhase {
+ Credentials,
+ ClientVersion,
+ Request,
+ Response,
+ Catalog,
+ Registration,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum CpaDiscoveryOutcome {
+ Entered,
+ Completed,
+ Failed,
+ Discarded,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum CpaDiscoveryReason {
+ MissingAccessToken,
+ ClientVersionUnavailable,
+ Cancelled,
+ Timeout,
+ DnsFailure,
+ ConnectFailure,
+ ProxyFailure,
+ ProxyRejected,
+ TlsFailure,
+ TransportFailure,
+ HttpRejected,
+ BodyReadFailure,
+ ResponseTooLarge,
+ InvalidCatalog,
+ InvalidModelId,
+ DuplicateModelId,
+ EmptyCatalog,
+ EmptyAfterFiltering,
+ AccountMissing,
+ AccountDisabled,
+ AccountChanged,
+}
diff --git a/crates/diagnostics/src/event/mod.rs b/crates/diagnostics/src/event/mod.rs
index 1614d60a..9870b24a 100644
--- a/crates/diagnostics/src/event/mod.rs
+++ b/crates/diagnostics/src/event/mod.rs
@@ -9,8 +9,11 @@ mod common;
mod content;
mod control;
mod cpa;
+mod cpa_control;
+mod cpa_model_discovery;
mod model;
mod observation;
+mod protected_channel;
mod startup;
mod system;
mod worker;
@@ -23,8 +26,11 @@ pub use common::*;
pub use content::*;
pub use control::*;
pub use cpa::*;
+pub use cpa_control::*;
+pub use cpa_model_discovery::*;
pub use model::*;
pub use observation::*;
+pub use protected_channel::*;
pub use startup::*;
pub use system::*;
pub use worker::*;
@@ -53,6 +59,7 @@ pub enum DiagnosticEvent {
Apply(ApplyEvent),
ControlCallEnd(ControlCallEnd),
ControlStage(ControlStage),
+ ProtectedExchange(ProtectedExchange),
RequestBegin(RequestBegin),
RequestEnd(RequestEnd),
RouteSelected(RouteSelected),
@@ -81,6 +88,8 @@ pub enum DiagnosticEvent {
CpaLifecycle(CpaLifecycle),
CredentialLease(CredentialLease),
CpaStage(CpaStage),
+ CpaControl(CpaControl),
+ CpaModelDiscovery(CpaModelDiscovery),
}
impl DiagnosticEvent {
@@ -136,6 +145,13 @@ impl DiagnosticEvent {
}
}
DiagnosticEvent::ControlStage(_) => Debug,
+ DiagnosticEvent::ProtectedExchange(exchange) => {
+ if exchange.error.is_some() {
+ Warn
+ } else {
+ Debug
+ }
+ }
DiagnosticEvent::RequestBegin(_)
| DiagnosticEvent::RouteSelected(_)
| DiagnosticEvent::AttemptBegin(_) => Info,
@@ -186,6 +202,26 @@ impl DiagnosticEvent {
| DiagnosticEvent::CpaLifecycle(_)
| DiagnosticEvent::CredentialLease(_) => Info,
DiagnosticEvent::WorkerStage(_) | DiagnosticEvent::CpaStage(_) => Debug,
+ DiagnosticEvent::CpaControl(control) => match control.outcome {
+ CpaStageOutcome::Failed { .. } => Warn,
+ _ => Debug,
+ },
+ DiagnosticEvent::CpaModelDiscovery(discovery) => match &discovery.observation {
+ CpaDiscoveryObservation::Observed { attempt, .. }
+ if matches!(
+ attempt.outcome,
+ CpaDiscoveryOutcome::Failed | CpaDiscoveryOutcome::Discarded
+ ) || attempt.reason.is_some() =>
+ {
+ Warn
+ }
+ CpaDiscoveryObservation::Unavailable {
+ reason:
+ CpaDiscoveryUnavailable::InvalidMetadata
+ | CpaDiscoveryUnavailable::ObservationLimit,
+ } => Warn,
+ _ => Debug,
+ },
}
}
@@ -221,6 +257,7 @@ impl DiagnosticEvent {
DiagnosticEvent::Apply(_) => "apply",
DiagnosticEvent::ControlCallEnd(_) => "control_call_end",
DiagnosticEvent::ControlStage(_) => "control_stage",
+ DiagnosticEvent::ProtectedExchange(_) => "protected_exchange",
DiagnosticEvent::RequestBegin(_) => "request_begin",
DiagnosticEvent::RequestEnd(_) => "request_end",
DiagnosticEvent::RouteSelected(_) => "route_selected",
@@ -249,6 +286,8 @@ impl DiagnosticEvent {
DiagnosticEvent::CpaLifecycle(_) => "cpa_lifecycle",
DiagnosticEvent::CredentialLease(_) => "credential_lease",
DiagnosticEvent::CpaStage(_) => "cpa_stage",
+ DiagnosticEvent::CpaControl(_) => "cpa_control",
+ DiagnosticEvent::CpaModelDiscovery(_) => "cpa_model_discovery",
}
}
}
diff --git a/crates/diagnostics/src/event/protected_channel.rs b/crates/diagnostics/src/event/protected_channel.rs
new file mode 100644
index 00000000..41b93f84
--- /dev/null
+++ b/crates/diagnostics/src/event/protected_channel.rs
@@ -0,0 +1,44 @@
+//! Closed, secret-free evidence for the native launcher exchange and loss transition.
+use crate::identity::CorrelationToken;
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ProtectedExchangeKind {
+ Grant,
+ InputRegister,
+ InputRelease,
+ Upgrade,
+ Recovery,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ProtectedExchangePhase {
+ RequestWrite,
+ AcknowledgementRead,
+ Register,
+ AcknowledgementWrite,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ProtectedExchangeError {
+ Timeout,
+ Closed,
+ Oversized,
+ Invalid,
+ Mismatch,
+ Unavailable,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ProtectedExchange {
+ pub kind: ProtectedExchangeKind,
+ pub phase: ProtectedExchangePhase,
+ pub registration_token: Option<CorrelationToken>,
+ pub elapsed_ms: u64,
+ pub error: Option<ProtectedExchangeError>,
+ pub authority_lost: bool,
+}
diff --git a/crates/product-session/src/authority.rs b/crates/product-session/src/authority.rs
index fd4ba041..992193f3 100644
--- a/crates/product-session/src/authority.rs
+++ b/crates/product-session/src/authority.rs
@@ -15,6 +15,9 @@ pub enum ApplyPurpose {
pub trait HostAuthority: Send + Sync + Any {
fn as_any(&self) -> &dyn Any;
fn has_authority(&self) -> bool;
+ fn native_connection(&self) -> Option<crate::NativeConnectionStatus> {
+ None
+ }
fn register_operation(
&self,
digest: &CanonicalDigest,
@@ -234,6 +237,9 @@ impl SessionAuthority {
}
}
impl HostAuthority for SessionAuthority {
+ fn native_connection(&self) -> Option<crate::NativeConnectionStatus> {
+ self.host.native_connection()
+ }
fn as_any(&self) -> &dyn Any {
self.host.as_any()
}
diff --git a/crates/product-session/src/commands.json b/crates/product-session/src/commands.json
index ca61bd30..a1921a22 100644
--- a/crates/product-session/src/commands.json
+++ b/crates/product-session/src/commands.json
@@ -797,6 +797,12 @@
"result": "Result<StartupReport, String>",
"host_only": true
},
+ {
+ "name": "recover_native_connection",
+ "args": [],
+ "result": "Result<(), DesktopFailure>",
+ "host_only": true
+ },
{
"name": "open_startup_recovery_directory",
"args": [],
diff --git a/crates/product-session/src/lib.rs b/crates/product-session/src/lib.rs
index 2be482a4..5424972f 100644
--- a/crates/product-session/src/lib.rs
+++ b/crates/product-session/src/lib.rs
@@ -7,7 +7,7 @@ pub mod operation_observation;
pub mod session;
pub mod web_confirmation;
pub use authority::{HostAuthority, SessionAuthority};
-pub use session::ProductSession;
+pub use session::{NativeConnectionStatus, ProductSession};
#[cfg(feature = "test-support")]
pub mod fault;
pub fn random_id() -> Result<String, String> {
diff --git a/crates/product-session/src/session.rs b/crates/product-session/src/session.rs
index 4aab8d74..2a57f6c4 100644
--- a/crates/product-session/src/session.rs
+++ b/crates/product-session/src/session.rs
@@ -67,8 +67,19 @@ pub struct RestoreName {
pub plan_id: String,
pub previous_name: String,
}
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum NativeConnectionStatus {
+ Ready,
+ RecoveryRequired,
+ RestartRequired,
+ NotOwned,
+}
+
#[derive(Serialize)]
pub struct DesktopSnapshot {
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub native_connection: Option<NativeConnectionStatus>,
pub service: ClientServiceStatusV1,
pub catalog: AgentPlanCatalogViewV2,
pub catalog_error: Option<DesktopFailure>,
@@ -425,8 +436,17 @@ impl ProductSession {
};
// The successful status query came over Client Core's verified owner-only Local Control
// peer. Configuration writes use that same transport, not the separate check grant pipe.
- let trusted_authority = true;
+ let native_connection = self.authority.native_connection();
+ let trusted_authority = !matches!(
+ native_connection,
+ Some(
+ NativeConnectionStatus::RecoveryRequired
+ | NativeConnectionStatus::RestartRequired
+ | NativeConnectionStatus::NotOwned
+ )
+ );
Ok(DesktopSnapshot {
+ native_connection,
service,
catalog,
catalog_error,
diff --git a/docs/code-map/README.md b/docs/code-map/README.md
index 8db045d3..4542e769 100644
--- a/docs/code-map/README.md
+++ b/docs/code-map/README.md
@@ -30,7 +30,7 @@ results in the relevant run record.
| Delegate, read, cancel or continue a Worker task | [Worker lifecycle and native differences](worker-context.md#follow-a-task-through-its-owners) | [Delegation](../../tools/product-e2e/tests/worker_delegation.rs), [read/Continue](../../tools/product-e2e/tests/worker_read.rs) |
| Inspect sessions, content, cost and competence | [Observation owners](architecture.md#observation-and-conversation-boundaries), [decision attribution](decision-foundation.md#observation-and-public-consumers) | [Concurrent routing timeline and incremental read bounds](../../crates/observation/src/store/tests/plan_quality/routing_timeline.rs), [opening protection projection](../../crates/observation/src/store/tests/plan_quality/routing_timeline_protection.rs), [stage summaries](../../crates/observation/src/store/tests/plan_quality/summary.rs) |
| Connect, resume or adjust through a terminal/Agent | [CLI journey](../../crates/cli/src/quickstart.rs), [complete Plan recovery](../../crates/cli/src/quickstart/plan_restore.rs), [shared authoring](../../crates/application/src/routing/editor_options.rs), [installed schemas](../../crates/application-api/src/command_schemas.rs), [shared management Skill](../../assets/skills/hiroute-management/SKILL.md) | [Installed Quickstart](../../crates/daemon/tests/support/quickstart_product.py), [effective evidence](../../crates/daemon/src/control/runtime/settings_effective_tests.rs) |
-| Manage the service through CLI or Desktop | [client-core](../../crates/client-core/src), [CLI](../../crates/cli/src), [Desktop host](../../apps/desktop/src-tauri/src), [daemon control](../../crates/daemon/src/control) | [Real control process](../../tools/product-e2e/tests/control_shell.rs), [Desktop test map](../../apps/desktop/tests/README.md) |
+| Manage the service through CLI or Desktop | [client-core](../../crates/client-core/src), [CLI](../../crates/cli/src), [Desktop host](../../apps/desktop/src-tauri/src) and [native connection recovery](../../apps/desktop/src-tauri/src/bootstrap/recovery.rs), [daemon control](../../crates/daemon/src/control) | [Real control process](../../tools/product-e2e/tests/control_shell.rs), [Desktop test map](../../apps/desktop/tests/README.md) |
| Configure and open the authenticated console locally or remotely | [Console owner](../../crates/daemon/src/console), [shared product session](../../crates/product-session/src), [console guide](../web-console.md) | [Real role-all authority/HTTP composition](../../crates/daemon/src/console/tests.rs), [production browser scenarios](../../apps/desktop/tests/v3/visual/console-scenarios.mjs) |
| Install and operate native Windows headless, including background service | [Windows operating guide](../standalone-windows.md), [native kernel owners](../../crates/platform/README.md), [Rust installation transaction](../../crates/host-runtime/src/standalone_install) | [Actual installed Control/Gateway/restart](../../crates/daemon/tests/windows_headless.rs); Task is the only offered manager; SCM is refused unchanged and retains low-level tests |
| Upgrade Desktop and recover a failed installation | [Updater](../../apps/desktop/src-tauri/src/updates.rs), [installer handshake](../../apps/desktop/src-tauri/src/updates/installer.rs), [resident restart](../../apps/desktop/src-tauri/src/bootstrap.rs), [shared recovery facts](../../crates/host-runtime/src/storage_recovery.rs), [early admission diagnostics](../../crates/host-runtime/src/storage_recovery/admission.rs), [storage admission](../../crates/local-storage/src/migrations/startup_recovery.rs) | Preflight → orderly stop → explicit commit; [macOS installation and recovery](../macos-installation.md) |
diff --git a/docs/code-map/architecture.md b/docs/code-map/architecture.md
index 4e7e4b7a..e9f02056 100644
--- a/docs/code-map/architecture.md
+++ b/docs/code-map/architecture.md
@@ -117,6 +117,7 @@ The name must fit any runtime root that supports `hiroute/control.sock`, includi
| Rename a connection, append models or remove saved configuration | [Shared lifecycle planner](../../crates/application/src/compute_management/mutations/lifecycle.rs), [transactional reference guards](../../crates/local-storage/src/control/compute/management/references.rs), [Desktop lifecycle dialog](../../apps/desktop/src/features/models/ConnectionLifecycleDialog.tsx) | Templates do not own credentials. Explicit append preserves saved members; enabled/disabled routes and retained recovery versions block removal. Removing the last model requires explicit connection deletion; owned secrets follow the same recoverable operation. |
| Save Key order or use current Keys with an older plan | [Single-save edits](../../apps/desktop/src/features/models/model-draft.ts), [request admission](../../crates/gateway/src/core_runtime/credentials.rs), [current pool authority](../../crates/local-storage/src/control/compute/management/runtime_pool.rs), [safe Key masks](../../crates/daemon/src/control/runtime/model_connections/key_masks.rs) | A request owns its admitted Key IDs and order; later exact leases enforce current source/Key eligibility and generation. Admission retains closed permission denials in the existing request summary. Shared Plan content stays frozen. Masks are a separate authenticated query; saved plaintext never reaches Desktop. |
| Connect a native Codex or Claude subscription | [Source discovery](../../crates/integrations/src/agents/subscription_sources.rs), [credential adapters](../../crates/cpa-bridge/src), [shared lifecycle](../../crates/daemon/src/control/runtime/subscriptions.rs), [provider runtimes](../../crates/cpa-bridge/src/runtime_set.rs) | Native clients retain refresh authority; only access leases enter isolated CPA instances. Claude Keychain interaction is limited to an explicit check; discovery reads metadata only. Codex borrowing reads file storage only and rejects a configured non-file store even if stale auth.json remains. |
+| Locate a slow subscription validation condition | [Stock discovery/pin loop](../../crates/cpa-bridge/src/accounts/stock.rs), [pin facts](../../crates/diagnostics/src/event/cpa_control.rs), [CPA discovery facts](../../crates/diagnostics/src/event/cpa_model_discovery.rs), [troubleshooting](../diagnostic-troubleshooting.md) | [Condition regressions and isolated live probe](../../crates/cpa-bridge/src/accounts/stock/diagnostic_tests.rs) distinguish unmet pins; [private metadata admission](../../crates/cpa-bridge/src/accounts/stock/model_discovery.rs) observes upstream phase, reason and timing from the [pinned CPA](../../vendor/cpa/README.md), retaining the first failure without logging account identities. |
| Sign in independently to a Codex or Claude subscription | [Shared login control](../../crates/application/src/control_plane/subscription_login.rs), [protected lifecycle](../../crates/daemon/src/control/runtime/subscriptions/login.rs), [private sessions](../../crates/cpa-bridge/src/managed_sessions.rs), [Desktop sign-in](../../apps/desktop/src/features/subscriptions/SubscriptionSignIn.tsx) | CPA receives browser callbacks on temporary loopback listeners; an unavailable listener uses explicit protected manual input. Login is separate from Check/Save and routing. Daemon maintenance owns pending completion/expiry, and saved revisions own runtime selection. [The pinned CPA adapter](../../vendor/cpa/README.md) owns callback admission, authorization and refresh. |
| Lease a subscription credential without blocking Gateway workers | [Async adapter](../../crates/daemon/src/gateway_ports/credential/cpa.rs), [request budget](../../crates/cpa-bridge/src/request_context.rs), [admission and observations](../../crates/cpa-bridge/src/runtime/admission.rs), [Claude identity resolution](../../crates/cpa-bridge/src/claude_profile.rs) | Bounded provider executors own compatibility I/O. Short admission updates revoke before lifecycle work; identity lookup runs outside the lifecycle owner. Cancellation and saved revisions guard later publication. Follow [concurrency regressions](../../crates/cpa-bridge/src/runtime/tests/request_io.rs) for races with disable, replacement and delayed I/O. |
| Inspect saved subscription mode and repair sign-in | [V3 query](../../crates/application/src/compute_management/query_v3.rs), [mode and repair copy](../../apps/desktop/src/features/models/subscription-copy.ts) | Mode derives from the committed source selection and survives missing credentials. Desktop consumes V3; published V2 queries retain their strict response shape. Existing release-version matching still applies; an external service without V3 requires an update. |
@@ -152,6 +153,11 @@ Follow discovery through an ordinary request using the saved source. The
Scan → Prepare → Save → restart → native use, including stale-source rejection.
The shared product-session layer in `crates/product-session` owns Preview composition, confirmation permits, retry identity and protected-input lifetime. Desktop supplies its inherited-channel `HostAuthority` adapter in `apps/desktop/src-tauri/src/bootstrap/authority.rs`; native startup, updater and window authority stay with the Desktop host.
+[Native recovery](../../apps/desktop/src-tauri/src/bootstrap/recovery.rs) completes
+only the exact outstanding acknowledgement on the existing inherited channel,
+then transfers the running child to a fresh product session. It never restarts the
+daemon or pauses work. Old confirmations and authority remain invalid; malformed
+or closed channels fail closed. Status separates reachability from protected authority.
## State and lifecycle boundaries
diff --git a/docs/diagnostic-troubleshooting.md b/docs/diagnostic-troubleshooting.md
index be87ae79..b1cb9902 100644
--- a/docs/diagnostic-troubleshooting.md
+++ b/docs/diagnostic-troubleshooting.md
@@ -48,3 +48,65 @@ Run the `stream_replay PRIVATE_CAPTURE` example in the same candidate's Debug bu
Replay supports only successful cross-protocol decoder paths. It skips 1xx and requires one final status. Same-protocol projectors and unsuccessful statuses explicitly return `unsupported_capture_path`; they must not produce decoder judgments from a substitute production entry. Raw captures must not be committed or attached to an Issue. A separate owner with a bounded lifetime stops the isolated candidate's entire process group, including descendants after the main process exits, and reaps the main process. It does not stop other sessions or processes with reused identities. After the CLI returns, retain the session for at most 24 hours, then delete it. Output includes the owner PID; SIGTERM to that owner stops the candidate early and deletes the session immediately. Do not force-kill the owner during retention. Host shutdown or SIGKILL prevents cleanup; after recovery, use `private-stream-capture.py cleanup ROOT` to delete the exact expired session. Locks use kernel ownership and release when the candidate crashes. A leftover lock file does not permanently block cleanup; an active writer still prevents it.
macOS may stop reporting PGID/SID for an exited but unreaped child. The supervisor may use the process group ID established at creation only if it created the candidate with `start_new_session` and `waitid(WNOWAIT)` still proves that child is waitable. This fallback remains forbidden for live, reaped or unknown-origin processes. After normal exit, retain sealed samples until their deadline; a failed zombie PGID query must not trigger early deletion. Darwin may also return EPERM when signaling a group containing only a zombie. Accept this result only when kernel PID and process-group snapshots match exactly and prove the group contains only that unreaped leader. Other members or a failed query remain errors. Report diagnostic repairs, historical failure attribution and semantic repairs backed by actual old failing samples separately. Failure to reproduce does not establish a repair.
+
+## Native connection lost while the daemon responds
+
+A successful Local Control/CLI query does not establish that Desktop's separate
+inherited protected channel is healthy. Home and Sessions also require that
+channel. `TRUSTED_AUTHORITY_UNAVAILABLE` after an exchange failure stays denied;
+ordinary read retry cannot repair it. Use **Restore local connection** in Desktop.
+Recovery completes the exact pending acknowledgement on the same inherited channel
+and creates a fresh product session. It never resends the failed business operation,
+pauses admission or restarts the daemon, so running requests/tasks continue. A
+pending reply can be retried; partial reply bytes are retained within the frame
+bound. Incomplete request writes, malformed/mismatched replies and closed channels
+require normal reopening after work finishes; they cannot be safely synchronized.
+
+Routing snapshot revalidation must release shared storage before waiting for CPA.
+Otherwise its control/lifecycle deadline can block native grant registration past
+the shorter host ACK deadline. A long CPA call and routing snapshot are evidence
+of contention, not proof of which historical protected exchange first failed.
+
+For slow subscription validation, follow `cpa_control` records sharing a span.
+`controls_patch` can include synchronous upstream model discovery; an entered phase
+without a terminal observation identifies the last reached boundary, not its cause.
+`account_pin` and `catalog_pin` report their elapsed/shared budget and poll counts.
+Their `checks` distinguish index continuity, retry settings, persisted controls,
+empty account models, wrong prefixes and missing downstream models. Missing fields
+mean the check was not reached; false is an actual unmet condition. These are last
+observations within one call, not an atomic snapshot of the external process.
+
+For the upstream cause, inspect `cpa_model_discovery` in the same span. It records
+CPA's credentials, client-version, request, response, catalog and registration
+phases, elapsed times and closed failure reasons. `retained_first_failure` marks
+an earlier failure retained by the same CPA process, not a new failure caused by
+the current read. Compare process/attempt IDs before attributing a retry. The
+record distinguishes proxy rejection from upstream HTTP status, and a successful
+empty list from filtering or a discarded stale account. Missing/invalid metadata,
+account eviction, observation limits and process exit constrain completeness;
+older logs lacking these facts cannot establish an original network cause.
+
+An empty account catalog after a failed initial discovery can coexist with correct
+persisted controls. Ordinary pin reads do not refresh an already-correct account;
+repeated reads alone therefore cannot establish that upstream discovery recovered.
+Use an isolated explicit check to distinguish this state from slow management I/O.
+Current pin reads fail promptly only for a quiescent registration with a consistent
+terminal observation and no account models. The management response marks the
+whole registration as pending across an authorization handoff, and also marks a
+catalog/status read as pending when registration changes during that read.
+Pending, inconsistent or unobserved discovery remains subject to the ordinary
+control deadline; an older retained failure does not make the latest attempt fail.
+Generation-only supersession may hand off once to current access credentials in
+the same upstream deadline. A different registration epoch, disable or removal
+never follows that handoff. Inspect both attempts before attributing a new request
+to a transport retry.
+Keep remote availability, local pin convergence and successful inference separate.
+Do not infer the historical failing condition from the generic
+`control_pin_not_applied` code alone.
+
+Inspect `protected_exchange` in both roles before attributing the original trigger.
+The event records a closed exchange family, phase, duration, failure category and
+HMAC registration correlation, with the authority-loss transition on the host.
+A late successful daemon ACK can coexist with a host timeout; it does not authorize
+reuse. A successful later recovery is not proof of the earlier failure's cause.
+Keep raw diagnostics private and report only revision-bound observable outcomes.
diff --git a/issue-spec/specs/model-discovery/spec.md b/issue-spec/specs/model-discovery/spec.md
index f0a51132..4de4b1de 100644
--- a/issue-spec/specs/model-discovery/spec.md
+++ b/issue-spec/specs/model-discovery/spec.md
@@ -68,12 +68,59 @@ Missing version, timeout, or invalid directory cannot manufacture remote results
a prior registered directory remains available, while a first failed lookup creates
no static substitute candidates. Discovery success does not prove inference.
+If an in-flight Codex lookup is superseded by an enabled, access-bearing newer
+generation of the same registered authorization, the old result MUST be discarded.
+Registration MAY rediscover once using the latest generation within the same
+upstream deadline. It MUST NOT follow removal, disable, loss of access credentials
+or replacement of the registered authorization. Ordinary transport failure MUST
+NOT itself trigger this generation handoff. Continued updates or exhausted time
+remain explicit bounded failures; no background restart is required.
+
+An empty account directory with a validated latest terminal discovery failure,
+discard or completed empty registration MUST fail promptly rather than consume
+the remaining control budget by polling the same empty result, only when the
+whole registration is quiescent and its observation is consistent with that
+directory read. An attempt discarded before an authorized handoff is not a
+terminal registration. Pending work and concurrent changes during the read may
+still converge within the original budget. Missing or invalid diagnostic
+metadata, unknown registration state and retained older failures do not establish
+a terminal empty directory.
+A nonempty retained directory keeps its existing pin and authorization checks.
+
#### Scenario: Directory lookup fails and later recovers
- **WHEN** an approved lease temporarily cannot obtain a client version or directory
- **THEN** failure MUST remain explicit and bounded; a later refresh uses the actual
selected engine and current account results without inventing membership.
+#### Scenario: Authorization changes while its directory is being discovered
+
+- **WHEN** the same registered account gains a newer enabled authorization generation
+ before a lookup can register its results
+- **THEN** the old results are discarded, at most one rediscovery uses the latest
+ credentials and rules within the original deadline, and removal, disable or
+ replacement cannot publish the superseded results.
+
+#### Scenario: Failed initial discovery leaves an empty directory
+
+- **WHEN** account controls are correct but the latest observable discovery is
+ terminal and the account directory is empty
+- **THEN** an ordinary pin read fails promptly without another remote lookup or
+ waiting out the entire control budget; a later explicit check may recover it.
+
+#### Scenario: A pin read overlaps authorization handoff
+
+- **WHEN** an old attempt is discarded but the same registration still has a
+ bounded rediscovery to run
+- **THEN** an empty pin read continues its original convergence wait, without
+ another refresh, until the registration settles or the budget expires.
+
+#### Scenario: A catalog read overlaps successful registration
+
+- **WHEN** registration changes between the model read and its status observation
+- **THEN** the mixed response MUST NOT establish a terminal empty directory; a
+ subsequent stable read may observe the successful catalog within the same budget.
+
### Requirement: Native static API imports retain native precedence and evidence
Pi discovery MUST passively read effective user models/auth configuration and the
diff --git a/issue-spec/specs/runtime-diagnostic-logging/spec.md b/issue-spec/specs/runtime-diagnostic-logging/spec.md
index ced72fd6..6fb6d0ec 100644
--- a/issue-spec/specs/runtime-diagnostic-logging/spec.md
+++ b/issue-spec/specs/runtime-diagnostic-logging/spec.md
@@ -85,6 +85,22 @@ evidence cannot be reported as complete replay. Read chunks are not original TCP
packets. A successful sample without the actual historical failure cannot establish
that its cause was fixed. This private artifact is never normal product logging.
+### Requirement: Subscription validation identifies the unmet condition
+
+CPA subscription discovery SHALL distinguish inventory/account reads, control
+updates, account pin validation and downstream catalog validation. A phase emits
+entry before blocking and a terminal outcome with its own elapsed time, the shared
+budget consumed, explicit-refresh intent and poll count. One discovery span ties
+these observations together without an account identity. Terminal failures remain
+visible at Warn; normal details remain Debug.
+
+Pin evidence SHALL report the last observed equality/boolean/count facts for account
+identity continuity, retry policy, persisted prefix/retry/cooling controls, nonempty
+account models, exact model prefixes, valid stripped IDs and missing downstream membership. Unreached
+checks remain absent, rather than false. Polling MUST NOT emit a record per poll.
+Paths, credentials, account/model names and raw responses remain excluded. Historical
+records lacking these observations cannot establish which pin condition failed.
+
### Requirement: Diagnostic degradation cannot block business execution
Queues, per-event size, file rotation, and retention MUST be bounded. Request
diff --git a/issue-spec/specs/shared-client-access/spec.md b/issue-spec/specs/shared-client-access/spec.md
index 218f2e0d..dcf2153c 100644
--- a/issue-spec/specs/shared-client-access/spec.md
+++ b/issue-spec/specs/shared-client-access/spec.md
@@ -63,6 +63,60 @@ Authenticated console sessions have the same protected-operation authority as ma
Source SPEC comments:
- https://github.com/higress-group/HiRoute/issues/132#issuecomment-6219725852
+### Requirement: Native connection loss is truthful and safely recoverable
+
+A responsive daemon SHALL NOT establish that the Desktop's inherited protected
+channel remains usable. Failed, timed-out, malformed or mismatched exchanges SHALL
+invalidate that channel without accepting a late response for another registration.
+Protected observations and actions SHALL fail closed with an actionable connection
+failure; service status SHALL distinguish that failure from daemon unavailability
+and from an intentional read-only connection. Existing loaded records and unsaved
+non-secret input SHALL remain available without being presented as fresh reads.
+
+Desktop SHALL offer recovery for a fully written request whose exact acknowledgement
+is still pending. It SHALL retain partial reply bytes within the existing bound,
+require the original schema and registration identity, and complete that reply
+before any new registration. This only restores transport synchronization; it SHALL
+NOT authorize or automatically replay the failed business operation. Incomplete
+request writes, closed channels and malformed/mismatched replies SHALL remain
+denied and require normal reopening after existing work finishes.
+
+Successful synchronization SHALL create a distinct product session, expire old
+confirmations, retire old authority and release abandoned session-owned inputs.
+It SHALL keep the existing daemon, inherited descriptors, host lease and listener;
+it SHALL NOT pause admission or interrupt running requests/tasks. It SHALL preserve
+saved configuration, retained sessions and operation identities without relaxing
+digests, revisions or principals. A missing or failed recovery remains explicit.
+External CPA revalidation SHALL NOT hold the shared storage needed by native grant
+registration across a control/lifecycle wait.
+
+The first failed exchange SHALL have bounded diagnostics identifying its phase,
+closed failure category, duration and irreversible registration correlation. Neither
+capability/input bytes, business payloads nor raw registration identifiers may appear.
+A controlled timeout reproducer SHALL NOT be described as the cause of an earlier
+unobserved failure.
+
+#### Scenario: Daemon responds after an uncertain protected exchange
+
+- **WHEN** the owned daemon is responsive after a protected registration times out
+- **THEN** Desktop reports loss of its trusted connection, protected reads remain
+ denied and ordinary Retry cannot treat a late ACK as new authorization.
+
+#### Scenario: Recovery synchronizes a pending reply without stopping work
+
+- **WHEN** the user restores a timed-out native connection with a fully written request
+- **THEN** only its exact pending reply can restore synchronization; a new Desktop
+ session restores protected reads/actions while the same daemon and running work
+ continue, and old confirmations and authority cannot resume.
+
+#### Scenario: Invalid framing cannot acquire recovery authority
+
+- **WHEN** a request is incompletely written or its reply is malformed, mismatched or closed
+- **THEN** in-place recovery remains unavailable, the daemon is not stopped, and
+ Desktop explains normal reopening after existing work finishes.
+
+Source Issue: https://github.com/higress-group/HiRoute/issues/187
+
### Requirement: Clients observe work without automatically repeating it
Accepted is not succeeded. Measured progress alone supports percentages; otherwise
diff --git a/scripts/test-package-desktop.py b/scripts/test-package-desktop.py
index a67d8c27..978ff3f5 100644
--- a/scripts/test-package-desktop.py
+++ b/scripts/test-package-desktop.py
@@ -94,7 +94,7 @@ class BundleIdentityTests(unittest.TestCase):
def test_cpa_is_explicitly_signed_before_release_probe(self):
events = []
- release = ("CLIProxyAPI Version: 8.0.4-hiroute.5, Commit: "
+ release = ("CLIProxyAPI Version: 8.0.4-hiroute.8, Commit: "
"a270e7b9e57aaecd8f82555f44c2108518ad2330, "
"BuiltAt: 2026-09-29T00:00:00Z")
with patch.object(package, "sign", side_effect=lambda *_: events.append("sign")), \
diff --git a/vendor/cpa/README.md b/vendor/cpa/README.md
index 19f8a501..e57e385b 100644
--- a/vendor/cpa/README.md
+++ b/vendor/cpa/README.md
@@ -60,16 +60,58 @@ upstream response bodies. An initial failure does not create model entries.
This does not add polling or a new catalog cache. Inference does not discover
models. Successful listing is not proof that inference succeeds.
+An enabled newer generation of the same registration can supersede an in-flight
+lookup. The stale result is discarded and the registration owner can discover
+once for the latest access-bearing generation, sharing the original five-second
+deadline. Removal, disable, lost access and a different registration epoch cannot
+request this handoff. Transport failure alone does not retry. Continued churn
+remains bounded and observable; an old account cannot populate a replacement.
+
HiRoute's ordinary routing compilation and Codex preview read and verify the
registered catalog without repeating an already-correct auth control PATCH.
An explicit subscription check refreshes it; credential/version changes use the
existing auth update path. This keeps remote directory availability out of
unchanged preview/publication reads while retaining all account pin checks.
+When the directory is empty and the whole registration is quiescent with a
+consistent terminal observation, a pin read fails immediately instead of polling
+that empty result for 20 seconds. The existing response's `registration_pending`
+flag covers the whole registration, including the gap before a bounded handoff.
+Queued auth updates and reconciliation passes share that same scope.
+Two observations bracket the local catalog read; any intervening transition makes
+that response pending. No registry lock spans discovery or management I/O.
+Pending work still gets its existing convergence wait. Missing/malformed
+observations, unknown registration state and an older retained failure cannot
+shorten the wait. A nonempty retained directory still undergoes every normal pin check.
For native borrowing, the fields PATCH carries the validated lease's current `hiroute_client_version`
alongside its controls. CPA persists and synchronously discovers that version
even when its watcher still holds the preceding metadata. No access or refresh
token is included in this control request.
+The existing authenticated account-model response also carries the private
+`hiroute.cpa-model-discovery/v1` observation. CPA retains the first failed or
+discarded attempt and the latest attempt per account, including phase, closed
+reason, total/phase durations, HTTP or proxy status, model counts and up to six
+phase timings. Credentials, native version, account/model IDs, URLs and raw errors
+are excluded. The in-memory store holds at most 128 accounts and reports evictions;
+process exit loses it. Retention starts when this artifact starts, so it cannot
+recover historical failures from an older process. Older concurrent attempts
+cannot overwrite the latest attempt. No new endpoint or maintenance channel is
+introduced. Transport retry settings are unchanged; generation handoff shares
+the original five-second discovery deadline.
+In-flight registration counts are separate from the retained history, survive
+history eviction and are deleted when the last overlapping registration exits.
+
+HiRoute validates this metadata independently of model membership, emits bounded
+`cpa_model_discovery` transitions on its existing diagnostic context and explicitly
+marks missing, invalid or truncated observations. Repeated polling does not emit
+the same transition again. Proxy CONNECT rejection has its own status; it must
+not be interpreted as an upstream HTTP response. An empty successful upstream
+list, filtering to zero models and discarding a stale authorization are distinct
+observations. These facts diagnose listing and registration, not inference.
+Registration also records generation and registration-epoch equality as separate
+booleans, so a stale result identifies the actual failed guard without exposing
+authorization identifiers or generation values.
+
On Windows, native Codex and Claude file borrowing uses
[`borrowed_native_windows.rs`](../../crates/cpa-bridge/src/borrowed_native_windows.rs).
The reader holds the inspected parent and regular file, rejects reparses and
diff --git a/vendor/cpa/local-management-stdin.patch b/vendor/cpa/local-management-stdin.patch
index 381c06d5..8894c3fc 100644
--- a/vendor/cpa/local-management-stdin.patch
+++ b/vendor/cpa/local-management-stdin.patch
@@ -104,6 +104,92 @@ index 2b99077..a661fbb 100644
cmd.StartServiceWithPluginHost(cfg, configFilePath, password, pluginHost, serverOptions...)
}
}
+diff --git a/internal/api/handlers/management/auth_files.go b/internal/api/handlers/management/auth_files.go
+index 0a4ed74..5678a80 100644
+--- a/internal/api/handlers/management/auth_files.go
++++ b/internal/api/handlers/management/auth_files.go
+@@ -16,6 +16,7 @@ import (
+ "github.com/router-for-me/CLIProxyAPI/v8/internal/auth/codex"
+ "github.com/router-for-me/CLIProxyAPI/v8/internal/config"
+ "github.com/router-for-me/CLIProxyAPI/v8/internal/credentialweight"
++ "github.com/router-for-me/CLIProxyAPI/v8/internal/modeldiscovery"
+ "github.com/router-for-me/CLIProxyAPI/v8/internal/registry"
+ coreauth "github.com/router-for-me/CLIProxyAPI/v8/sdk/cliproxy/auth"
+ log "github.com/sirupsen/logrus"
+@@ -355,7 +356,10 @@ func (h *Handler) GetAuthFileModels(c *gin.Context) {
+
+ // Get models from registry
+ reg := registry.GetGlobalRegistry()
+- models := reg.GetModelsForClient(authID)
++ var models []*registry.ModelInfo
++ discovery := modeldiscovery.ReadCatalog(authID, func() {
++ models = reg.GetModelsForClient(authID)
++ })
+
+ result := make([]gin.H, 0, len(models))
+ for _, m := range models {
+@@ -374,7 +378,7 @@ func (h *Handler) GetAuthFileModels(c *gin.Context) {
+ result = append(result, entry)
+ }
+
+- c.JSON(200, gin.H{"models": result})
++ c.JSON(200, gin.H{"models": result, "hiroute_model_discovery": discovery})
+ }
+
+ // List auth files from disk when the auth manager is unavailable.
+diff --git a/internal/api/handlers/management/auth_files_discovery_test.go b/internal/api/handlers/management/auth_files_discovery_test.go
+new file mode 100644
+index 0000000..b4b2fb3
+--- /dev/null
++++ b/internal/api/handlers/management/auth_files_discovery_test.go
+@@ -0,0 +1,47 @@
++package management
++
++import (
++ "context"
++ "encoding/json"
++ "net/http/httptest"
++ "strings"
++ "testing"
++
++ "github.com/gin-gonic/gin"
++ "github.com/router-for-me/CLIProxyAPI/v8/internal/config"
++ "github.com/router-for-me/CLIProxyAPI/v8/internal/modeldiscovery"
++ coreauth "github.com/router-for-me/CLIProxyAPI/v8/sdk/cliproxy/auth"
++)
++
++func TestHiRouteDiscoveryExistingManagementResponseResolvesFileName(t *testing.T) {
++ manager := coreauth.NewManager(nil, nil, nil)
++ a := &coreauth.Auth{ID: "private/internal/account", FileName: "private-file.json", Provider: "codex"}
++ if _, err := manager.Register(context.Background(), a); err != nil {
++ t.Fatal(err)
++ }
++ trace := modeldiscovery.Begin(a.ID)
++ trace.Enter(modeldiscovery.ClientVersion)
++ trace.End(modeldiscovery.Failed, modeldiscovery.ClientVersionUnavailable)
++ done := modeldiscovery.Registering(a.ID)
++ defer done()
++ handler := NewHandlerWithoutConfigFilePath(&config.Config{}, manager)
++ recorder := httptest.NewRecorder()
++ ctx, _ := gin.CreateTestContext(recorder)
++ ctx.Request = httptest.NewRequest("GET", "/v0/management/auth-files/models?name=private-file.json", nil)
++ handler.GetAuthFileModels(ctx)
++ var response struct {
++ Models []any `json:"models"`
++ Discovery modeldiscovery.Snapshot `json:"hiroute_model_discovery"`
++ }
++ if err := json.Unmarshal(recorder.Body.Bytes(), &response); err != nil {
++ t.Fatal(err)
++ }
++ if recorder.Code != 200 || response.Models == nil || !response.Discovery.RegistrationPending || response.Discovery.FirstFailure == nil || response.Discovery.FirstFailure.Reason != modeldiscovery.ClientVersionUnavailable {
++ t.Fatalf("missing observation: %+v", response)
++ }
++ for _, private := range []string{a.ID, a.FileName, "access_token"} {
++ if strings.Contains(recorder.Body.String(), private) {
++ t.Fatal("private diagnostic material")
++ }
++ }
++}
diff --git a/internal/api/handlers/management/auth_files_oauth_callback.go b/internal/api/handlers/management/auth_files_oauth_callback.go
index f33f82e..3d87ba9 100644
--- a/internal/api/handlers/management/auth_files_oauth_callback.go
@@ -1143,12 +1229,621 @@ index 7d69d46..44da6d5 100644
return t.transport.RoundTrip(req)
}
+diff --git a/internal/modeldiscovery/diagnostics.go b/internal/modeldiscovery/diagnostics.go
+new file mode 100644
+index 0000000..c444f23
+--- /dev/null
++++ b/internal/modeldiscovery/diagnostics.go
+@@ -0,0 +1,285 @@
++// Package modeldiscovery retains bounded, secret-free observations for the
++// existing authenticated management response. It never logs raw errors or I/O.
++package modeldiscovery
++
++import (
++ "context"
++ "crypto/x509"
++ "errors"
++ "net"
++ "os"
++ "strings"
++ "sync"
++ "sync/atomic"
++ "time"
++
++ "github.com/router-for-me/CLIProxyAPI/v8/sdk/proxyutil"
++)
++
++const capacity = 128
++
++type Phase string
++type Outcome string
++type Reason string
++
++const (
++ Credentials Phase = "credentials"
++ ClientVersion Phase = "client_version"
++ Request Phase = "request"
++ Response Phase = "response"
++ Catalog Phase = "catalog"
++ Registration Phase = "registration"
++ Entered Outcome = "entered"
++ Completed Outcome = "completed"
++ Failed Outcome = "failed"
++ Discarded Outcome = "discarded"
++ NoReason Reason = ""
++ MissingAccessToken Reason = "missing_access_token"
++ ClientVersionUnavailable Reason = "client_version_unavailable"
++ Cancelled Reason = "cancelled"
++ Timeout Reason = "timeout"
++ DNSFailure Reason = "dns_failure"
++ ConnectFailure Reason = "connect_failure"
++ ProxyFailure Reason = "proxy_failure"
++ ProxyRejected Reason = "proxy_rejected"
++ TLSFailure Reason = "tls_failure"
++ TransportFailure Reason = "transport_failure"
++ HTTPRejected Reason = "http_rejected"
++ BodyReadFailure Reason = "body_read_failure"
++ ResponseTooLarge Reason = "response_too_large"
++ InvalidCatalog Reason = "invalid_catalog"
++ InvalidModelID Reason = "invalid_model_id"
++ DuplicateModelID Reason = "duplicate_model_id"
++ EmptyCatalog Reason = "empty_catalog"
++ EmptyAfterFiltering Reason = "empty_after_filtering"
++ AccountMissing Reason = "account_missing"
++ AccountDisabled Reason = "account_disabled"
++ AccountChanged Reason = "account_changed"
++)
++
++type PhaseTiming struct {
++ Phase Phase `json:"phase"`
++ Outcome Outcome `json:"outcome"`
++ ElapsedMS uint64 `json:"elapsed_ms"`
++ Reason Reason `json:"reason,omitempty"`
++ ModelCount *uint64 `json:"model_count,omitempty"`
++}
++
++type Attempt struct {
++ ID uint64 `json:"attempt_id"`
++ Phase Phase `json:"phase"`
++ Outcome Outcome `json:"outcome"`
++ Reason Reason `json:"reason,omitempty"`
++ ElapsedMS uint64 `json:"elapsed_ms"`
++ PhaseElapsedMS uint64 `json:"phase_elapsed_ms"`
++ HTTPStatus *int `json:"http_status,omitempty"`
++ ProxyStatus *int `json:"proxy_status,omitempty"`
++ ModelCount *uint64 `json:"model_count,omitempty"`
++ GenerationMatches *bool `json:"generation_matches,omitempty"`
++ RegistrationEpochMatches *bool `json:"registration_epoch_matches,omitempty"`
++ Timings []PhaseTiming `json:"timings"`
++}
++
++type Snapshot struct {
++ Schema string `json:"schema"`
++ ProcessID int `json:"process_id"`
++ EvictedAccounts uint64 `json:"evicted_accounts"`
++ FirstFailure *Attempt `json:"first_failure"`
++ Latest *Attempt `json:"latest"`
++ RegistrationPending bool `json:"registration_pending"`
++ revision uint64
++}
++
++type entry struct {
++ first *Attempt
++ latest Attempt
++ updated time.Time
++}
++
++var store = struct {
++ sync.Mutex
++ entries map[string]*entry
++ evicted uint64
++ active map[string]uint64
++ revision uint64
++}{entries: make(map[string]*entry), active: make(map[string]uint64)}
++var nextID atomic.Uint64
++
++type contextKey struct{}
++
++// Trace belongs to one synchronous discovery/registration attempt, not a goroutine
++// shared by independent registrations. Only immutable copies enter the store.
++type Trace struct {
++ account string
++ started time.Time
++ phaseStarted time.Time
++ value Attempt
++}
++
++func Begin(account string) *Trace {
++ return &Trace{account: account, started: time.Now(), value: Attempt{ID: nextID.Add(1), Timings: []PhaseTiming{}}}
++}
++
++func WithTrace(ctx context.Context, trace *Trace) context.Context {
++ return context.WithValue(ctx, contextKey{}, trace)
++}
++
++func FromContext(ctx context.Context) *Trace {
++ trace, _ := ctx.Value(contextKey{}).(*Trace)
++ return trace
++}
++
++func (t *Trace) Enter(phase Phase) {
++ t.phaseStarted = time.Now()
++ t.value.Phase, t.value.Outcome, t.value.Reason = phase, Entered, NoReason
++ t.value.ElapsedMS, t.value.PhaseElapsedMS = millis(time.Since(t.started)), 0
++ t.publish()
++}
++
++func (t *Trace) End(outcome Outcome, reason Reason) {
++ t.value.Outcome, t.value.Reason = outcome, reason
++ t.value.ElapsedMS, t.value.PhaseElapsedMS = millis(time.Since(t.started)), millis(time.Since(t.phaseStarted))
++ if len(t.value.Timings) < 6 {
++ t.value.Timings = append(t.value.Timings, PhaseTiming{t.value.Phase, outcome, t.value.PhaseElapsedMS, reason, t.value.ModelCount})
++ }
++ t.publish()
++}
++
++func (t *Trace) HTTP(status int) { t.value.HTTPStatus = &status }
++func (t *Trace) Models(count int) { value := uint64(count); t.value.ModelCount = &value }
++
++func (t *Trace) RegistrationChecks(generation, epoch bool) {
++ t.value.GenerationMatches, t.value.RegistrationEpochMatches = &generation, &epoch
++}
++
++// Transport retains only closed categories. URLs, hostnames, proxy credentials
++// and arbitrary error strings are never copied into an observation.
++func (t *Trace) Transport(err error) {
++ var proxyError *proxyutil.ConnectStatusError
++ if errors.As(err, &proxyError) {
++ status := proxyError.StatusCode
++ t.value.ProxyStatus = &status
++ t.End(Failed, ProxyRejected)
++ return
++ }
++ reason := TransportFailure
++ var dns *net.DNSError
++ var network *net.OpError
++ var timeout net.Error
++ var unknownCA x509.UnknownAuthorityError
++ var hostname x509.HostnameError
++ var invalidCertificate x509.CertificateInvalidError
++ switch {
++ case errors.Is(err, context.Canceled):
++ reason = Cancelled
++ case errors.Is(err, context.DeadlineExceeded):
++ reason = Timeout
++ case errors.As(err, &timeout) && timeout.Timeout():
++ reason = Timeout
++ case errors.As(err, &dns):
++ reason = DNSFailure
++ case errors.As(err, &unknownCA), errors.As(err, &hostname), errors.As(err, &invalidCertificate):
++ reason = TLSFailure
++ case errors.As(err, &network) && network.Op == "dial":
++ reason = ConnectFailure
++ }
++ // The pinned transports own these fixed wrappers. Inspecting them refines a
++ // category without retaining the nested message or guessing an upstream status.
++ if reason == TransportFailure || reason == ConnectFailure {
++ for cause := err; cause != nil; cause = errors.Unwrap(cause) {
++ message := cause.Error()
++ switch {
++ case strings.HasPrefix(message, "utls: TLS handshake:"), strings.HasPrefix(message, "HTTPS proxy TLS handshake failed:"):
++ reason = TLSFailure
++ case strings.HasPrefix(message, "dial HTTP proxy failed:"), strings.HasPrefix(message, "write CONNECT request failed:"), strings.HasPrefix(message, "read CONNECT response failed:"):
++ reason = ProxyFailure
++ }
++ }
++ }
++ t.End(Failed, reason)
++}
++
++func (t *Trace) publish() {
++ if t.account == "" || len(t.account) > 4096 {
++ return
++ }
++ store.Lock()
++ defer store.Unlock()
++ store.revision++
++ current := store.entries[t.account]
++ if current == nil {
++ if len(store.entries) == capacity {
++ var oldest string
++ var id uint64 = ^uint64(0)
++ for key, value := range store.entries {
++ if value.latest.ID < id {
++ oldest, id = key, value.latest.ID
++ }
++ }
++ delete(store.entries, oldest)
++ store.evicted++
++ }
++ current = &entry{}
++ store.entries[t.account] = current
++ }
++ if current.first == nil && (t.value.Outcome == Failed || t.value.Outcome == Discarded) {
++ copy := clone(t.value)
++ current.first = &copy
++ }
++ if t.value.ID >= current.latest.ID {
++ current.latest, current.updated = clone(t.value), time.Now()
++ }
++}
++
++func Read(account string) Snapshot {
++ store.Lock()
++ defer store.Unlock()
++ result := Snapshot{Schema: "hiroute.cpa-model-discovery/v1", ProcessID: os.Getpid(), EvictedAccounts: store.evicted,
++ RegistrationPending: store.active[account] != 0, revision: store.revision}
++ if current := store.entries[account]; current != nil {
++ latest := clone(current.latest)
++ if latest.Outcome == Entered {
++ delta := millis(time.Since(current.updated))
++ latest.ElapsedMS += delta
++ latest.PhaseElapsedMS += delta
++ }
++ result.Latest = &latest
++ if current.first != nil {
++ first := clone(*current.first)
++ result.FirstFailure = &first
++ }
++ }
++ return result
++}
++
++func clone(value Attempt) Attempt {
++ if value.GenerationMatches != nil {
++ copy := *value.GenerationMatches
++ value.GenerationMatches = &copy
++ }
++ if value.RegistrationEpochMatches != nil {
++ copy := *value.RegistrationEpochMatches
++ value.RegistrationEpochMatches = &copy
++ }
++ if value.HTTPStatus != nil {
++ copy := *value.HTTPStatus
++ value.HTTPStatus = &copy
++ }
++ if value.ProxyStatus != nil {
++ copy := *value.ProxyStatus
++ value.ProxyStatus = &copy
++ }
++ if value.ModelCount != nil {
++ copy := *value.ModelCount
++ value.ModelCount = &copy
++ }
++ value.Timings = append([]PhaseTiming{}, value.Timings...)
++ for index := range value.Timings {
++ if value.Timings[index].ModelCount != nil {
++ copy := *value.Timings[index].ModelCount
++ value.Timings[index].ModelCount = &copy
++ }
++ }
++ return value
++}
++func millis(value time.Duration) uint64 { return uint64(value.Milliseconds()) }
+diff --git a/internal/modeldiscovery/diagnostics_test.go b/internal/modeldiscovery/diagnostics_test.go
+new file mode 100644
+index 0000000..9c9d1d2
+--- /dev/null
++++ b/internal/modeldiscovery/diagnostics_test.go
+@@ -0,0 +1,100 @@
++package modeldiscovery
++
++import (
++ "context"
++ "encoding/json"
++ "fmt"
++ "net"
++ "strings"
++ "testing"
++ "time"
++
++ "github.com/router-for-me/CLIProxyAPI/v8/sdk/proxyutil"
++)
++
++func TestHiRouteDiscoveryFirstFailureSurvivesRecoveryAndOutOfOrderCompletion(t *testing.T) {
++ id := "private-account-must-not-leak"
++ first := Begin(id)
++ first.Enter(ClientVersion)
++ first.End(Failed, ClientVersionUnavailable)
++ second := Begin(id)
++ second.Enter(Catalog)
++ second.Models(9)
++ second.End(Completed, NoReason)
++ first.Enter(Registration)
++ first.End(Discarded, AccountChanged)
++ snapshot := Read(id)
++ if snapshot.FirstFailure == nil || snapshot.FirstFailure.Reason != ClientVersionUnavailable || snapshot.Latest.ID != second.value.ID {
++ t.Fatal("first failure or latest attempt lost")
++ }
++ if *snapshot.Latest.ModelCount != 9 {
++ t.Fatal("model count lost")
++ }
++ *snapshot.Latest.ModelCount = 123
++ if *Read(id).Latest.ModelCount != 9 {
++ t.Fatal("snapshot mutates retained observation")
++ }
++ encoded, _ := json.Marshal(snapshot)
++ if strings.Contains(string(encoded), id) || strings.Contains(string(encoded), "access_token") {
++ t.Fatal("private identity leaked")
++ }
++}
++
++func TestHiRouteDiscoveryTransportCategoriesNeverRetainRawErrors(t *testing.T) {
++ for index, item := range []struct {
++ err error
++ reason Reason
++ status int
++ }{
++ {context.DeadlineExceeded, Timeout, 0},
++ {context.Canceled, Cancelled, 0},
++ {&net.DNSError{Name: "private-host", Err: "private-token"}, DNSFailure, 0},
++ {&net.OpError{Op: "dial", Err: fmt.Errorf("private-token")}, ConnectFailure, 0},
++ {fmt.Errorf("utls: TLS handshake: private-token"), TLSFailure, 0},
++ {fmt.Errorf("read CONNECT response failed: private-token"), ProxyFailure, 0},
++ {fmt.Errorf("wrapped: %w", &proxyutil.ConnectStatusError{StatusCode: 503}), ProxyRejected, 503},
++ {fmt.Errorf("private-token"), TransportFailure, 0},
++ } {
++ id := fmt.Sprintf("transport-%d", index)
++ trace := Begin(id)
++ trace.Enter(Request)
++ trace.Transport(item.err)
++ value := Read(id).Latest
++ if value.Reason != item.reason {
++ t.Fatalf("case %d reason=%s", index, value.Reason)
++ }
++ if item.status != 0 && (value.ProxyStatus == nil || *value.ProxyStatus != item.status || value.HTTPStatus != nil) {
++ t.Fatal("proxy status was mislabeled as upstream status")
++ }
++ data, _ := json.Marshal(value)
++ if strings.Contains(string(data), "private-token") || strings.Contains(string(data), "private-host") {
++ t.Fatal("raw transport data leaked")
++ }
++ }
++}
++
++func TestHiRouteDiscoveryStorageAndPhaseHistoryAreBounded(t *testing.T) {
++ for index := 0; index < capacity+5; index++ {
++ trace := Begin(fmt.Sprintf("bounded-%d", index))
++ for phase := 0; phase < 10; phase++ {
++ trace.Enter(Request)
++ trace.End(Completed, NoReason)
++ }
++ }
++ store.Lock()
++ count := len(store.entries)
++ store.Unlock()
++ if count > capacity || Read("bounded-132").EvictedAccounts == 0 {
++ t.Fatal("unbounded account history")
++ }
++ latest := Read("bounded-132").Latest
++ if latest == nil || len(latest.Timings) != 6 {
++ t.Fatal("unbounded phase history")
++ }
++ trace := Begin("progress")
++ trace.Enter(Request)
++ time.Sleep(time.Millisecond)
++ if Read("progress").Latest.Outcome != Entered || Read("progress").Latest.ElapsedMS == 0 {
++ t.Fatal("blocked phase is not observable")
++ }
++}
+diff --git a/internal/modeldiscovery/registration.go b/internal/modeldiscovery/registration.go
+new file mode 100644
+index 0000000..9b51136
+--- /dev/null
++++ b/internal/modeldiscovery/registration.go
+@@ -0,0 +1,39 @@
++package modeldiscovery
++
++import "sync"
++
++// Registering spans the whole registration, including the gap between a
++// discarded attempt and its bounded handoff. Entries live only while work runs;
++// evicting diagnostic history cannot erase an in-flight registration.
++func Registering(account string) func() {
++ if account == "" || len(account) > 4096 {
++ return func() {}
++ }
++ store.Lock()
++ store.active[account]++
++ store.revision++
++ store.Unlock()
++ var once sync.Once
++ return func() {
++ once.Do(func() {
++ store.Lock()
++ defer store.Unlock()
++ store.active[account]--
++ if store.active[account] == 0 {
++ delete(store.active, account)
++ }
++ store.revision++
++ })
++ }
++}
++
++// ReadCatalog brackets a local catalog read without holding the diagnostics
++// mutex across registry work. A transition during the read is pending for this
++// response, so mixed snapshots cannot turn an empty read into a terminal result.
++func ReadCatalog(account string, read func()) Snapshot {
++ before := Read(account)
++ read()
++ after := Read(account)
++ after.RegistrationPending = before.RegistrationPending || after.RegistrationPending || before.revision != after.revision
++ return after
++}
+diff --git a/internal/modeldiscovery/registration_test.go b/internal/modeldiscovery/registration_test.go
+new file mode 100644
+index 0000000..55ff881
+--- /dev/null
++++ b/internal/modeldiscovery/registration_test.go
+@@ -0,0 +1,94 @@
++package modeldiscovery
++
++import (
++ "testing"
++
++ "github.com/router-for-me/CLIProxyAPI/v8/internal/registry"
++)
++
++func TestHiRouteRegistrationHandoffRemainsPendingBetweenAttempts(t *testing.T) {
++ const account = "handoff-gap"
++ gap, resume, finished := make(chan struct{}), make(chan struct{}), make(chan struct{})
++ go func() {
++ defer close(finished)
++ done := Registering(account)
++ defer done()
++ first := Begin(account)
++ first.Enter(Registration)
++ first.End(Discarded, AccountChanged)
++ close(gap)
++ <-resume
++ second := Begin(account)
++ second.Enter(Registration)
++ second.Models(1)
++ second.End(Completed, NoReason)
++ }()
++ <-gap
++ snapshot := ReadCatalog(account, func() {})
++ close(resume)
++ <-finished
++ if !snapshot.RegistrationPending || snapshot.Latest == nil || snapshot.Latest.Outcome != Discarded {
++ t.Fatal("discarded first attempt hid the pending handoff")
++ }
++ settled := ReadCatalog(account, func() {})
++ if settled.RegistrationPending || settled.Latest == nil || settled.Latest.ModelCount == nil || *settled.Latest.ModelCount != 1 {
++ t.Fatal("completed registration did not become quiescent")
++ }
++}
++
++func TestHiRouteCatalogReadDetectsConcurrentRegistrationCompletion(t *testing.T) {
++ const account = "mixed-catalog-snapshot"
++ reg := registry.GetGlobalRegistry()
++ defer reg.UnregisterClient(account)
++ first := Begin(account)
++ first.Enter(Request)
++ first.End(Failed, Timeout)
++ read, resume := make(chan struct{}), make(chan struct{})
++ result := make(chan Snapshot, 1)
++ var models []*registry.ModelInfo
++ go func() {
++ result <- ReadCatalog(account, func() {
++ models = reg.GetModelsForClient(account)
++ close(read)
++ <-resume
++ })
++ }()
++ <-read
++ done := Registering(account)
++ second := Begin(account)
++ second.Enter(Registration)
++ reg.RegisterClient(account, "codex", []*registry.ModelInfo{{ID: "current-model", Object: "model", Type: "codex"}})
++ second.Models(1)
++ second.End(Completed, NoReason)
++ done()
++ close(resume)
++ snapshot := <-result
++ if len(models) != 0 || snapshot.Latest == nil || snapshot.Latest.ModelCount == nil || *snapshot.Latest.ModelCount != 1 || !snapshot.RegistrationPending {
++ t.Fatal("mixed empty/success response was presented as quiescent")
++ }
++ settled := ReadCatalog(account, func() { models = reg.GetModelsForClient(account) })
++ if len(models) != 1 || settled.RegistrationPending {
++ t.Fatal("next stable read did not recover")
++ }
++}
++
++func TestHiRouteRegistrationTrackingIsAccountScopedAndSurvivesHistoryEviction(t *testing.T) {
++ const account = "active-during-eviction"
++ first, second := Registering(account), Registering(account)
++ for index := 0; index < capacity+1; index++ {
++ trace := Begin(string(rune(index + 1000)))
++ trace.Enter(Request)
++ }
++ first()
++ first() // Registration task completion and batch cleanup may both finish it.
++ if !Read(account).RegistrationPending || Read("other-account").RegistrationPending {
++ t.Fatal("overlapping work or account scope lost")
++ }
++ second()
++ store.Lock()
++ _, retained := store.active[account]
++ store.Unlock()
++ if retained || Read(account).RegistrationPending {
++ t.Fatal("finished registration state leaked")
++ }
++}
+diff --git a/internal/runtime/executor/codex_model_diagnostics_test.go b/internal/runtime/executor/codex_model_diagnostics_test.go
+new file mode 100644
+index 0000000..30e6697
+--- /dev/null
++++ b/internal/runtime/executor/codex_model_diagnostics_test.go
+@@ -0,0 +1,61 @@
++package executor
++
++import (
++ "context"
++ "io"
++ "net/http"
++ "strings"
++ "testing"
++
++ "github.com/router-for-me/CLIProxyAPI/v8/internal/modeldiscovery"
++ cliproxyauth "github.com/router-for-me/CLIProxyAPI/v8/sdk/cliproxy/auth"
++)
++
++type discoveryDiagnosticTransport struct {
++ status int
++ body string
++}
++
++func (d discoveryDiagnosticTransport) RoundTrip(req *http.Request) (*http.Response, error) {
++ return &http.Response{StatusCode: d.status, Header: make(http.Header), Body: io.NopCloser(strings.NewReader(d.body)), Request: req}, nil
++}
++
++func TestHiRouteCodexDiscoveryFailurePhaseAndSafeResponseFacts(t *testing.T) {
++ for _, item := range []struct {
++ name string
++ status int
++ body string
++ phase modeldiscovery.Phase
++ reason modeldiscovery.Reason
++ }{
++ {"unauthorized", 401, `{"error":"private-token"}`, modeldiscovery.Response, modeldiscovery.HTTPRejected},
++ {"forbidden", 403, `private-token`, modeldiscovery.Response, modeldiscovery.HTTPRejected},
++ {"invalid-json", 200, `private-token`, modeldiscovery.Catalog, modeldiscovery.InvalidCatalog},
++ {"duplicate", 200, `{"models":[{"slug":"m"},{"slug":"m"}]}`, modeldiscovery.Catalog, modeldiscovery.DuplicateModelID},
++ {"empty", 200, `{"models":[]}`, modeldiscovery.Catalog, modeldiscovery.EmptyCatalog},
++ } {
++ t.Run(item.name, func(t *testing.T) {
++ id := "diagnostic-" + item.name
++ a := &cliproxyauth.Auth{ID: id, Metadata: map[string]any{"access_token": "private-token", "hiroute_client_version": "0.999.0"}}
++ ctx := context.WithValue(context.Background(), "cliproxy.roundtripper", http.RoundTripper(discoveryDiagnosticTransport{item.status, item.body}))
++ _, err := NewCodexExecutor(nil).DiscoverModels(ctx, a, nil)
++ value := modeldiscovery.Read(id).Latest
++ if value == nil || value.Phase != item.phase || value.Reason != item.reason || value.HTTPStatus == nil || *value.HTTPStatus != item.status {
++ t.Fatal("failure boundary or HTTP status lost")
++ }
++ if item.name == "empty" {
++ if err != nil || value.Outcome != modeldiscovery.Completed || value.ModelCount == nil || *value.ModelCount != 0 {
++ t.Fatal("valid empty catalog mislabeled as failed transport")
++ }
++ } else if err == nil {
++ t.Fatal("invalid discovery succeeded")
++ }
++ })
++ }
++ id := "missing-version-diagnostic"
++ _, err := NewCodexExecutor(nil).DiscoverModels(context.Background(), &cliproxyauth.Auth{ID: id, Metadata: map[string]any{"access_token": "private-token"}}, nil)
++ value := modeldiscovery.Read(id).Latest
++ if err == nil || value.Phase != modeldiscovery.ClientVersion || value.Reason != modeldiscovery.ClientVersionUnavailable || value.HTTPStatus != nil {
++ t.Fatal("local version failure confused with an upstream response")
++ }
++}
diff --git a/internal/runtime/executor/codex_models.go b/internal/runtime/executor/codex_models.go
new file mode 100644
-index 0000000..403683d
+index 0000000..f17845a
--- /dev/null
+++ b/internal/runtime/executor/codex_models.go
-@@ -0,0 +1,126 @@
+@@ -0,0 +1,173 @@
+package executor
+
+import (
@@ -1161,6 +1856,7 @@ index 0000000..403683d
+ "strings"
+ "time"
+
++ "github.com/router-for-me/CLIProxyAPI/v8/internal/modeldiscovery"
+ "github.com/router-for-me/CLIProxyAPI/v8/internal/registry"
+ "github.com/router-for-me/CLIProxyAPI/v8/internal/runtime/executor/helps"
+ cliproxyauth "github.com/router-for-me/CLIProxyAPI/v8/sdk/cliproxy/auth"
@@ -1171,16 +1867,32 @@ index 0000000..403683d
+func (e *CodexExecutor) DiscoverModels(ctx context.Context, auth *cliproxyauth.Auth, known []*registry.ModelInfo) ([]*registry.ModelInfo, error) {
+ ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+ defer cancel()
++ trace := modeldiscovery.FromContext(ctx)
++ if trace == nil {
++ id := ""
++ if auth != nil {
++ id = auth.ID
++ }
++ trace = modeldiscovery.Begin(id)
++ }
++ trace.Enter(modeldiscovery.Credentials)
+ token, _ := codexCreds(auth)
+ if strings.TrimSpace(token) == "" {
++ trace.End(modeldiscovery.Failed, modeldiscovery.MissingAccessToken)
+ return nil, fmt.Errorf("codex model discovery: missing access token")
+ }
++ trace.End(modeldiscovery.Completed, modeldiscovery.NoReason)
++ trace.Enter(modeldiscovery.ClientVersion)
+ version, err := codexModelDiscoveryVersion(auth)
+ if err != nil {
++ trace.End(modeldiscovery.Failed, modeldiscovery.ClientVersionUnavailable)
+ return nil, err
+ }
++ trace.End(modeldiscovery.Completed, modeldiscovery.NoReason)
++ trace.Enter(modeldiscovery.Request)
+ req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://chatgpt.com/backend-api/codex/models?client_version="+url.QueryEscape(version), nil)
+ if err != nil {
++ trace.Transport(err)
+ return nil, err
+ }
+ applyCodexHeadersFromSources(req, auth, token, false, e.cfg, nil)
@@ -1189,17 +1901,35 @@ index 0000000..403683d
+ client.CheckRedirect = func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }
+ resp, err := client.Do(req)
+ if err != nil {
++ trace.Transport(err)
+ return nil, fmt.Errorf("codex model discovery: transport failed")
+ }
+ defer resp.Body.Close()
++ trace.HTTP(resp.StatusCode)
++ trace.End(modeldiscovery.Completed, modeldiscovery.NoReason)
++ trace.Enter(modeldiscovery.Response)
+ if resp.StatusCode != http.StatusOK {
++ trace.End(modeldiscovery.Failed, modeldiscovery.HTTPRejected)
+ return nil, fmt.Errorf("codex model discovery: HTTP %d", resp.StatusCode)
+ }
+ const limit = 16 << 20
+ body, err := io.ReadAll(io.LimitReader(resp.Body, limit+1))
+ if err != nil || len(body) > limit {
++ reason := modeldiscovery.BodyReadFailure
++ if len(body) > limit {
++ reason = modeldiscovery.ResponseTooLarge
++ }
++ if ctx.Err() == context.DeadlineExceeded {
++ reason = modeldiscovery.Timeout
++ }
++ if ctx.Err() == context.Canceled {
++ reason = modeldiscovery.Cancelled
++ }
++ trace.End(modeldiscovery.Failed, reason)
+ return nil, fmt.Errorf("codex model discovery: unreadable or oversized catalog")
+ }
++ trace.End(modeldiscovery.Completed, modeldiscovery.NoReason)
++ trace.Enter(modeldiscovery.Catalog)
+ var catalog struct {
+ Models []struct {
+ Slug string `json:"slug"`
@@ -1214,6 +1944,7 @@ index 0000000..403683d
+ } `json:"models"`
+ }
+ if json.Unmarshal(body, &catalog) != nil || catalog.Models == nil {
++ trace.End(modeldiscovery.Failed, modeldiscovery.InvalidCatalog)
+ return nil, fmt.Errorf("codex model discovery: invalid catalog")
+ }
+ byID := make(map[string]*registry.ModelInfo, len(known))
@@ -1227,6 +1958,11 @@ index 0000000..403683d
+ for _, remote := range catalog.Models {
+ id := strings.TrimSpace(remote.Slug)
+ if id == "" || seen[id] {
++ reason := modeldiscovery.InvalidModelID
++ if seen[id] {
++ reason = modeldiscovery.DuplicateModelID
++ }
++ trace.End(modeldiscovery.Failed, reason)
+ return nil, fmt.Errorf("codex model discovery: invalid or duplicate model ID")
+ }
+ seen[id] = true
@@ -1251,6 +1987,12 @@ index 0000000..403683d
+ }
+ models = append(models, &m)
+ }
++ trace.Models(len(models))
++ reason := modeldiscovery.NoReason
++ if len(models) == 0 {
++ reason = modeldiscovery.EmptyCatalog
++ }
++ trace.End(modeldiscovery.Completed, reason)
+ return models, nil
+}
+
@@ -2088,12 +2830,36 @@ index 0000000..91db81d
+ t.Fatalf("overflow trace=%q", trace.Header())
+ }
+}
+diff --git a/sdk/cliproxy/service_auth.go b/sdk/cliproxy/service_auth.go
+index c2b4f73..035cda4 100644
+--- a/sdk/cliproxy/service_auth.go
++++ b/sdk/cliproxy/service_auth.go
+@@ -5,6 +5,7 @@ import (
+ "strings"
+ "time"
+
++ "github.com/router-for-me/CLIProxyAPI/v8/internal/modeldiscovery"
+ "github.com/router-for-me/CLIProxyAPI/v8/internal/runtime/executor"
+ "github.com/router-for-me/CLIProxyAPI/v8/internal/util"
+ "github.com/router-for-me/CLIProxyAPI/v8/internal/watcher"
+@@ -100,6 +101,11 @@ func (s *Service) handleAuthUpdates(ctx context.Context, updates []watcher.AuthU
+ if s == nil {
+ return
+ }
++ // Accepted updates are pending even while waiting for the update lock.
++ for _, update := range updates {
++ done := modeldiscovery.Registering(authUpdateID(update))
++ defer done()
++ }
+ // Keep this path limited to the targeted auths. Global plugin rebuilds and
+ // in-flight Antigravity probes can hold authUpdateMu for minutes and stall
+ // Management API PATCH responses.
diff --git a/sdk/cliproxy/service_codex_discovery_test.go b/sdk/cliproxy/service_codex_discovery_test.go
new file mode 100644
-index 0000000..4b42cba
+index 0000000..8909d5d
--- /dev/null
+++ b/sdk/cliproxy/service_codex_discovery_test.go
-@@ -0,0 +1,62 @@
+@@ -0,0 +1,114 @@
+package cliproxy
+
+import (
@@ -2103,6 +2869,7 @@ index 0000000..4b42cba
+ "strings"
+ "testing"
+
++ "github.com/router-for-me/CLIProxyAPI/v8/internal/modeldiscovery"
+ coreauth "github.com/router-for-me/CLIProxyAPI/v8/sdk/cliproxy/auth"
+ "github.com/router-for-me/CLIProxyAPI/v8/sdk/config"
+)
@@ -2148,6 +2915,13 @@ index 0000000..4b42cba
+ if len(GlobalModelRegistry().GetModelsForClient(a.ID)) != 0 {
+ t.Fatal("empty authoritative list did not remove models")
+ }
++ snapshot := modeldiscovery.Read(a.ID)
++ if snapshot.FirstFailure == nil || snapshot.FirstFailure.Reason != modeldiscovery.HTTPRejected || snapshot.Latest == nil || snapshot.Latest.Phase != modeldiscovery.Registration || snapshot.Latest.Reason != modeldiscovery.EmptyAfterFiltering {
++ t.Fatalf("lost first failure or empty registration facts: %+v", snapshot)
++ }
++ if snapshot.Latest.Timings[4].Reason != modeldiscovery.EmptyCatalog {
++ t.Fatal("upstream empty catalog was confused with filtering")
++ }
+ status, body = 200, `{"models":[{"slug":"other-account-model"}]}`
+ a.ID, a.Prefix = "other-account", "other"
+ defer GlobalModelRegistry().UnregisterClient(a.ID)
@@ -2156,13 +2930,327 @@ index 0000000..4b42cba
+ t.Fatal("cross-account catalog leakage")
+ }
+}
++
++func TestHiRouteDiscoveryRegistrationDiscard(t *testing.T) {
++ for _, reason := range []modeldiscovery.Reason{modeldiscovery.AccountMissing, modeldiscovery.AccountDisabled, modeldiscovery.AccountChanged, modeldiscovery.Cancelled} {
++ t.Run(string(reason), func(t *testing.T) {
++ manager := coreauth.NewManager(nil, nil, nil)
++ a := &coreauth.Auth{ID: "discard-" + string(reason), Provider: "codex", Metadata: map[string]any{"access_token": "private-test-token", "hiroute_client_version": "0.999.0"}}
++ registered, err := manager.Register(context.Background(), a)
++ if err != nil {
++ t.Fatal(err)
++ }
++ a = registered.Clone()
++ s := &Service{cfg: &config.Config{}, coreManager: manager}
++ ctx, cancel := context.WithCancel(context.Background())
++ defer cancel()
++ ctx = context.WithValue(ctx, "cliproxy.roundtripper", discoveryTransport(func(r *http.Request) (*http.Response, error) {
++ switch reason {
++ case modeldiscovery.AccountMissing:
++ manager.Remove(context.Background(), a.ID)
++ case modeldiscovery.AccountDisabled, modeldiscovery.AccountChanged:
++ current, _ := manager.GetByID(a.ID)
++ current.Disabled = reason == modeldiscovery.AccountDisabled
++ current.RegistrationEpoch++
++ if _, err := manager.Update(context.Background(), current); err != nil {
++ t.Fatal(err)
++ }
++ case modeldiscovery.Cancelled:
++ cancel()
++ }
++ return &http.Response{StatusCode: 200, Header: make(http.Header), Body: io.NopCloser(strings.NewReader(`{"models":[{"slug":"safe-model"}]}`)), Request: r}, nil
++ }))
++ s.registerModelsForAuth(ctx, a)
++ snapshot := modeldiscovery.Read(a.ID)
++ if snapshot.Latest == nil || snapshot.Latest.Phase != modeldiscovery.Registration || snapshot.Latest.Outcome != modeldiscovery.Discarded || snapshot.Latest.Reason != reason {
++ t.Fatalf("wrong discard: %+v", snapshot.Latest)
++ }
++ if reason == modeldiscovery.AccountChanged && (snapshot.Latest.RegistrationEpochMatches == nil || *snapshot.Latest.RegistrationEpochMatches) {
++ t.Fatal("missing exact registration epoch mismatch")
++ }
++ if len(GlobalModelRegistry().GetModelsForClient(a.ID)) != 0 {
++ t.Fatal("discarded catalog registered")
++ }
++ })
++ }
++}
+diff --git a/sdk/cliproxy/service_codex_registration.go b/sdk/cliproxy/service_codex_registration.go
+new file mode 100644
+index 0000000..518a73f
+--- /dev/null
++++ b/sdk/cliproxy/service_codex_registration.go
+@@ -0,0 +1,48 @@
++package cliproxy
++
++import (
++ "context"
++ "strings"
++ "time"
++
++ "github.com/router-for-me/CLIProxyAPI/v8/internal/modeldiscovery"
++ coreauth "github.com/router-for-me/CLIProxyAPI/v8/sdk/cliproxy/auth"
++)
++
++func (s *Service) registerModelsForAuthWithCache(ctx context.Context, a *coreauth.Auth, cache *openAICompatibilityRegistrationCache) {
++ if a != nil {
++ done := modeldiscovery.Registering(a.ID)
++ defer done()
++ }
++ if !codexDiscoveryAccount(a) {
++ s.registerModelsForAuthAttempt(ctx, a, cache)
++ return
++ }
++ if ctx == nil {
++ ctx = context.Background()
++ }
++ // A newer generation may supersede a lookup while it is in flight. Discard
++ // its result, then discover once for that latest generation in the SAME
++ // five-second budget. Transport failures do not request a handoff.
++ ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
++ defer cancel()
++ if s != nil && s.coreManager != nil {
++ if latest, ok := s.coreManager.GetByID(a.ID); ok && latest != nil && latest.RegistrationEpoch == a.RegistrationEpoch && codexDiscoveryAccount(latest) {
++ a = latest
++ }
++ }
++ for attempt := 0; attempt < 2 && ctx.Err() == nil; attempt++ {
++ a = s.registerModelsForAuthAttempt(ctx, a, cache)
++ if a == nil {
++ return
++ }
++ }
++}
++
++func codexDiscoveryAccount(a *coreauth.Auth) bool {
++ if a == nil || !strings.EqualFold(strings.TrimSpace(a.Provider), "codex") || a.AuthKind() == "apikey" {
++ return false
++ }
++ token, _ := a.Metadata["access_token"].(string)
++ return strings.TrimSpace(token) != ""
++}
+diff --git a/sdk/cliproxy/service_codex_registration_test.go b/sdk/cliproxy/service_codex_registration_test.go
+new file mode 100644
+index 0000000..63e93fc
+--- /dev/null
++++ b/sdk/cliproxy/service_codex_registration_test.go
+@@ -0,0 +1,208 @@
++package cliproxy
++
++import (
++ "context"
++ "errors"
++ "io"
++ "net/http"
++ "strings"
++ "testing"
++ "time"
++
++ "github.com/router-for-me/CLIProxyAPI/v8/internal/modeldiscovery"
++ "github.com/router-for-me/CLIProxyAPI/v8/internal/watcher"
++ coreauth "github.com/router-for-me/CLIProxyAPI/v8/sdk/cliproxy/auth"
++ "github.com/router-for-me/CLIProxyAPI/v8/sdk/config"
++)
++
++func TestHiRouteCodexRegistrationUsesLatestGeneration(t *testing.T) {
++ manager := coreauth.NewManager(nil, nil, nil)
++ original, err := manager.Register(context.Background(), &coreauth.Auth{ID: "generation-handoff", Provider: "codex", Prefix: "old", Metadata: map[string]any{"access_token": "old-access", "hiroute_client_version": "0.999.0"}})
++ if err != nil {
++ t.Fatal(err)
++ }
++ defer GlobalModelRegistry().UnregisterClient(original.ID)
++ service := &Service{cfg: &config.Config{}, coreManager: manager}
++ service.cfg.ForceModelPrefix = true
++ calls := 0
++ var firstDeadline time.Time
++ ctx := context.WithValue(context.Background(), "cliproxy.roundtripper", discoveryTransport(func(r *http.Request) (*http.Response, error) {
++ calls++
++ if !modeldiscovery.Read(original.ID).RegistrationPending {
++ t.Fatal("registration scope ended before its lookup/handoff")
++ }
++ deadline, ok := r.Context().Deadline()
++ if !ok {
++ t.Fatal("missing discovery bound")
++ }
++ body := `{"models":[{"slug":"old-only"}]}`
++ switch calls {
++ case 1:
++ firstDeadline = deadline
++ if r.Header.Get("Authorization") != "Bearer old-access" {
++ t.Fatal("wrong original credential")
++ }
++ next, _ := manager.GetByID(original.ID)
++ next.Prefix = "new"
++ next.Metadata["access_token"] = "new-access"
++ if _, err := manager.Update(context.Background(), next); err != nil {
++ t.Fatal(err)
++ }
++ time.Sleep(15 * time.Millisecond)
++ case 2:
++ if !deadline.Equal(firstDeadline) {
++ t.Fatal("handoff reset the discovery deadline")
++ }
++ if r.Header.Get("Authorization") != "Bearer new-access" {
++ t.Fatal("latest credential not used")
++ }
++ body = `{"models":[{"slug":"new-only"}]}`
++ default:
++ t.Fatal("unbounded generation handoff")
++ }
++ return &http.Response{StatusCode: 200, Header: make(http.Header), Body: io.NopCloser(strings.NewReader(body)), Request: r}, nil
++ }))
++ service.completeModelRegistrationForAuth(ctx, original)
++ models := GlobalModelRegistry().GetModelsForClient(original.ID)
++ if calls != 2 || len(models) != 1 || models[0].ID != "new/new-only" {
++ t.Fatalf("latest authorization lost: calls=%d models=%+v", calls, models)
++ }
++ snapshot := modeldiscovery.Read(original.ID)
++ if snapshot.RegistrationPending {
++ t.Fatal("registration scope leaked after completion")
++ }
++ if snapshot.FirstFailure == nil || snapshot.FirstFailure.Reason != modeldiscovery.AccountChanged || snapshot.Latest == nil || snapshot.Latest.Phase != modeldiscovery.Registration || snapshot.Latest.Outcome != modeldiscovery.Completed {
++ t.Fatal("handoff lost failure/recovery evidence")
++ }
++}
++
++func TestHiRouteCodexRegistrationHandoffIsBoundedAndDoesNotRetryTransport(t *testing.T) {
++ for _, mutate := range []bool{false, true} {
++ name := "transport"
++ if mutate {
++ name = "continuous-generation-change"
++ }
++ t.Run(name, func(t *testing.T) {
++ manager := coreauth.NewManager(nil, nil, nil)
++ original, err := manager.Register(context.Background(), &coreauth.Auth{ID: "bounded-" + name, Provider: "codex", Metadata: map[string]any{"access_token": "test-access", "hiroute_client_version": "0.999.0"}})
++ if err != nil {
++ t.Fatal(err)
++ }
++ service := &Service{cfg: &config.Config{}, coreManager: manager}
++ calls := 0
++ ctx := context.WithValue(context.Background(), "cliproxy.roundtripper", discoveryTransport(func(r *http.Request) (*http.Response, error) {
++ calls++
++ if !mutate {
++ return nil, errors.New("synthetic transport failure")
++ }
++ if calls > 2 {
++ t.Fatal("unbounded registration handoff")
++ }
++ next, _ := manager.GetByID(original.ID)
++ if _, err := manager.Update(context.Background(), next); err != nil {
++ t.Fatal(err)
++ }
++ return &http.Response{StatusCode: 200, Header: make(http.Header), Body: io.NopCloser(strings.NewReader(`{"models":[{"slug":"stale"}]}`)), Request: r}, nil
++ }))
++ service.completeModelRegistrationForAuth(ctx, original)
++ expected := 1
++ if mutate {
++ expected = 2
++ }
++ if calls != expected || len(GlobalModelRegistry().GetModelsForClient(original.ID)) != 0 {
++ t.Fatalf("wrong bounded outcome: calls=%d", calls)
++ }
++ })
++ }
++}
++
++func TestHiRouteCodexRegistrationDoesNotFollowRevokedOrReplacedAccount(t *testing.T) {
++ for _, action := range []string{"removed", "disabled", "no-access", "replaced"} {
++ t.Run(action, func(t *testing.T) {
++ manager := coreauth.NewManager(nil, nil, nil)
++ original, err := manager.Register(context.Background(), &coreauth.Auth{ID: "revoke-" + action, Provider: "codex", Metadata: map[string]any{"access_token": "test-access", "hiroute_client_version": "0.999.0"}})
++ if err != nil {
++ t.Fatal(err)
++ }
++ defer GlobalModelRegistry().UnregisterClient(original.ID)
++ service := &Service{cfg: &config.Config{}, coreManager: manager}
++ calls := 0
++ ctx := context.WithValue(context.Background(), "cliproxy.roundtripper", discoveryTransport(func(r *http.Request) (*http.Response, error) {
++ calls++
++ current, _ := manager.GetByID(original.ID)
++ switch action {
++ case "removed":
++ manager.Remove(context.Background(), original.ID)
++ case "replaced":
++ manager.Remove(context.Background(), original.ID)
++ if _, err := manager.Register(context.Background(), current); err != nil {
++ t.Fatal(err)
++ }
++ default:
++ if action == "disabled" {
++ current.Disabled = true
++ } else {
++ delete(current.Metadata, "access_token")
++ }
++ if _, err := manager.Update(context.Background(), current); err != nil {
++ t.Fatal(err)
++ }
++ }
++ return &http.Response{StatusCode: 200, Header: make(http.Header), Body: io.NopCloser(strings.NewReader(`{"models":[{"slug":"stale"}]}`)), Request: r}, nil
++ }))
++ service.completeModelRegistrationForAuth(ctx, original)
++ if calls != 1 || len(GlobalModelRegistry().GetModelsForClient(original.ID)) != 0 {
++ t.Fatal("followed revoked/replaced authorization or introduced static fallback")
++ }
++ })
++ }
++}
++
++func TestHiRouteCodexRegistrationPendingIncludesQueuedWork(t *testing.T) {
++ manager := coreauth.NewManager(nil, nil, nil)
++ original, err := manager.Register(context.Background(), &coreauth.Auth{ID: "queued-registration", Provider: "codex", Prefix: "subscription", Metadata: map[string]any{"access_token": "synthetic-access", "hiroute_client_version": "0.999.0"}})
++ if err != nil {
++ t.Fatal(err)
++ }
++ defer GlobalModelRegistry().UnregisterClient(original.ID)
++ prior := modeldiscovery.Begin(original.ID)
++ prior.Enter(modeldiscovery.Request)
++ prior.End(modeldiscovery.Failed, modeldiscovery.Timeout)
++ next, _ := manager.GetByID(original.ID)
++ next, err = manager.Update(context.Background(), next)
++ if err != nil {
++ t.Fatal(err)
++ }
++ service := &Service{cfg: &config.Config{}, coreManager: manager}
++ service.cfg.ForceModelPrefix = true
++ ctx := context.WithValue(context.Background(), "cliproxy.roundtripper", discoveryTransport(func(r *http.Request) (*http.Response, error) {
++ return &http.Response{StatusCode: 200, Header: make(http.Header), Body: io.NopCloser(strings.NewReader(`{"models":[{"slug":"current-model"}]}`)), Request: r}, nil
++ }))
++ service.authUpdateMu.Lock()
++ started, finished := make(chan struct{}), make(chan struct{})
++ go func() {
++ defer close(finished)
++ close(started)
++ service.handleAuthUpdate(ctx, watcher.AuthUpdate{Action: watcher.AuthUpdateActionModify, ID: next.ID, Auth: next})
++ }()
++ <-started
++ deadline := time.Now().Add(time.Second)
++ for !modeldiscovery.Read(original.ID).RegistrationPending && time.Now().Before(deadline) {
++ time.Sleep(time.Millisecond)
++ }
++ var models []*ModelInfo
++ blocked := modeldiscovery.ReadCatalog(original.ID, func() { models = GlobalModelRegistry().GetModelsForClient(original.ID) })
++ service.authUpdateMu.Unlock()
++ select {
++ case <-finished:
++ case <-time.After(2 * time.Second):
++ t.Fatal("queued registration did not finish")
++ }
++ if len(models) != 0 || !blocked.RegistrationPending || blocked.Latest == nil || blocked.Latest.Outcome != modeldiscovery.Failed {
++ t.Fatal("accepted update waiting for the lock looked terminal")
++ }
++ recovered := GlobalModelRegistry().GetModelsForClient(original.ID)
++ if len(recovered) != 1 || recovered[0].ID != "subscription/current-model" || modeldiscovery.Read(original.ID).RegistrationPending {
++ t.Fatal("queued registration did not recover and clear pending state")
++ }
++}
diff --git a/sdk/cliproxy/service_models.go b/sdk/cliproxy/service_models.go
-index 1bb4b62..7d18fc8 100644
+index 1bb4b62..107749c 100644
--- a/sdk/cliproxy/service_models.go
+++ b/sdk/cliproxy/service_models.go
-@@ -9,8 +9,10 @@ import (
+@@ -8,9 +8,12 @@ import (
+
"github.com/router-for-me/CLIProxyAPI/v8/internal/constant"
"github.com/router-for-me/CLIProxyAPI/v8/internal/modelconfig"
++ "github.com/router-for-me/CLIProxyAPI/v8/internal/modeldiscovery"
"github.com/router-for-me/CLIProxyAPI/v8/internal/registry"
+ "github.com/router-for-me/CLIProxyAPI/v8/internal/runtime/executor"
coreauth "github.com/router-for-me/CLIProxyAPI/v8/sdk/cliproxy/auth"
@@ -2171,20 +3259,52 @@ index 1bb4b62..7d18fc8 100644
)
// registerModelsForAuth (re)binds provider models in the global registry using the core auth ID as client identifier.
-@@ -149,6 +151,22 @@ func (s *Service) registerModelsForAuthWithCache(ctx context.Context, a *coreaut
+@@ -18,7 +21,7 @@ func (s *Service) registerModelsForAuth(ctx context.Context, a *coreauth.Auth) {
+ s.registerModelsForAuthWithCache(ctx, a, nil)
+ }
+
+-func (s *Service) registerModelsForAuthWithCache(ctx context.Context, a *coreauth.Auth, compatCache *openAICompatibilityRegistrationCache) {
++func (s *Service) registerModelsForAuthAttempt(ctx context.Context, a *coreauth.Auth, compatCache *openAICompatibilityRegistrationCache) (rebind *coreauth.Auth) {
+ if a == nil || a.ID == "" {
+ return
+ }
+@@ -71,6 +74,7 @@ func (s *Service) registerModelsForAuthWithCache(ctx context.Context, a *coreaut
+ return
+ }
+ var models []*ModelInfo
++ var discoveryTrace *modeldiscovery.Trace
+ switch provider {
+ case constant.Gemini:
+ models = registry.GetGeminiModels()
+@@ -149,6 +153,37 @@ func (s *Service) registerModelsForAuthWithCache(ctx context.Context, a *coreaut
default:
models = registry.GetCodexProModels()
}
+ if token, _ := a.Metadata["access_token"].(string); strings.TrimSpace(token) != "" {
-+ discovered, err := executor.NewCodexExecutor(s.cfg).DiscoverModels(ctx, a, models)
++ discoveryTrace = modeldiscovery.Begin(a.ID)
++ discovered, err := executor.NewCodexExecutor(s.cfg).DiscoverModels(modeldiscovery.WithTrace(ctx, discoveryTrace), a, models)
+ if err != nil {
+ log.Warnf("Codex model discovery failed; retaining registered catalog: %v", err)
+ return
+ }
++ discoveryTrace.Enter(modeldiscovery.Registration)
+ // An auth removed or replaced during the bounded request must not reappear.
+ if s.coreManager != nil {
+ current, ok := s.coreManager.GetByID(a.ID)
++ if ok {
++ discoveryTrace.RegistrationChecks(current.Generation == a.Generation, current.RegistrationEpoch == a.RegistrationEpoch)
++ }
+ if !ok || current.Disabled || current.Generation != a.Generation || current.RegistrationEpoch != a.RegistrationEpoch {
++ reason := modeldiscovery.AccountChanged
++ if !ok {
++ reason = modeldiscovery.AccountMissing
++ } else if current.Disabled {
++ reason = modeldiscovery.AccountDisabled
++ }
++ discoveryTrace.End(modeldiscovery.Discarded, reason)
++ if ok && !current.Disabled && current.RegistrationEpoch == a.RegistrationEpoch && current.Generation != a.Generation && codexDiscoveryAccount(current) && ctx.Err() == nil {
++ return current
++ }
+ return
+ }
+ }
@@ -2194,6 +3314,60 @@ index 1bb4b62..7d18fc8 100644
models = applyExcludedModels(models, excluded)
case "kimi", "kimi-ai", "kimi.ai", "kimi.com":
models = registry.GetKimiModels()
+@@ -283,10 +318,16 @@ func (s *Service) registerModelsForAuthWithCache(ctx context.Context, a *coreaut
+ }
+ }
+ if ctx.Err() != nil {
++ if discoveryTrace != nil {
++ discoveryTrace.End(modeldiscovery.Discarded, modeldiscovery.Cancelled)
++ }
+ return
+ }
+ models = applyOAuthModelAliasForAuth(s.cfg, provider, authKind, a.Attributes, models)
+ if ctx.Err() != nil {
++ if discoveryTrace != nil {
++ discoveryTrace.End(modeldiscovery.Discarded, modeldiscovery.Cancelled)
++ }
+ return
+ }
+ key := provider
+@@ -297,6 +338,15 @@ func (s *Service) registerModelsForAuthWithCache(ctx context.Context, a *coreaut
+ if len(models) > 0 {
+ models = applyOAuthSettingsForAuth(s.cfg, provider, authKind, models)
+ s.registerResolvedModelsForAuth(a, key, applyModelPrefixes(models, a.Prefix, s.cfg != nil && s.cfg.ForceModelPrefix))
++ if discoveryTrace != nil {
++ registered := GlobalModelRegistry().GetModelsForClient(a.ID)
++ discoveryTrace.Models(len(registered))
++ reason := modeldiscovery.NoReason
++ if len(registered) == 0 {
++ reason = modeldiscovery.EmptyAfterFiltering
++ }
++ discoveryTrace.End(modeldiscovery.Completed, reason)
++ }
+ if strings.EqualFold(strings.TrimSpace(a.Provider), "antigravity") {
+ s.asyncProbeAntigravityCapabilities(ctx, a, key)
+ }
+@@ -304,6 +354,11 @@ func (s *Service) registerModelsForAuthWithCache(ctx context.Context, a *coreaut
+ }
+
+ GlobalModelRegistry().UnregisterClient(a.ID)
++ if discoveryTrace != nil {
++ discoveryTrace.Models(0)
++ discoveryTrace.End(modeldiscovery.Completed, modeldiscovery.EmptyAfterFiltering)
++ }
++ return
+ }
+
+ // refreshModelRegistrationForAuth re-applies the latest model registration for
+@@ -325,6 +380,8 @@ func (s *Service) refreshModelRegistrationForAuthWithContext(ctx context.Context
+ if s == nil || s.coreManager == nil || current == nil || current.ID == "" {
+ return false
+ }
++ done := modeldiscovery.Registering(current.ID)
++ defer done()
+ if ctx == nil {
+ ctx = context.Background()
+ }
diff --git a/sdk/proxyutil/environment.go b/sdk/proxyutil/environment.go
new file mode 100644
index 0000000..46f700b
@@ -2252,3 +3426,35 @@ index 0000000..46f700b
+ }
+ return nil
+}
+diff --git a/sdk/proxyutil/proxy.go b/sdk/proxyutil/proxy.go
+index 4119baa..8f6d675 100644
+--- a/sdk/proxyutil/proxy.go
++++ b/sdk/proxyutil/proxy.go
+@@ -20,6 +20,14 @@ import (
+ // Mode describes how a proxy setting should be interpreted.
+ type Mode int
+
++// ConnectStatusError preserves a machine-readable proxy status without carrying
++// its untrusted reason phrase into discovery diagnostics.
++type ConnectStatusError struct{ StatusCode int }
++
++func (e *ConnectStatusError) Error() string {
++ return fmt.Sprintf("proxy CONNECT returned status %d", e.StatusCode)
++}
++
+ const (
+ // ModeInherit means no explicit proxy behavior was configured.
+ ModeInherit Mode = iota
+@@ -312,10 +320,8 @@ func (d *httpConnectDialer) DialContext(ctx context.Context, network, addr strin
+ if resp.Body != nil {
+ _ = resp.Body.Close()
+ }
+- if errClose := conn.Close(); errClose != nil {
+- return nil, fmt.Errorf("proxy CONNECT returned status %s; close failed: %v", resp.Status, errClose)
+- }
+- return nil, fmt.Errorf("proxy CONNECT returned status %s", resp.Status)
++ _ = conn.Close()
++ return nil, &ConnectStatusError{StatusCode: resp.StatusCode}
+ }
+
+ if errContext := ctx.Err(); errContext != nil {
diff --git a/vendor/cpa/source.json b/vendor/cpa/source.json
index 674f65a4..71ba3a7f 100644
--- a/vendor/cpa/source.json
+++ b/vendor/cpa/source.json
@@ -1,8 +1,8 @@
{
"repository": "https://github.com/router-for-me/CLIProxyAPI",
"commit": "a270e7b9e57aaecd8f82555f44c2108518ad2330",
- "version": "8.0.4-hiroute.5",
+ "version": "8.0.4-hiroute.8",
"built_at": "2026-09-29T00:00:00Z",
"patch": "local-management-stdin.patch",
- "patch_sha256": "3d871605b9f8bbb7ec25b1f3ecfc86c80f0d77e77bf10584cb82bf8766249d7f"
+ "patch_sha256": "0add1230022935ed2be228b6311e629ce74dd5cf95a22fd5d315733ece4f01b5"
}