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: make storage recovery actionable and repair Windows installations (#179)

澄潭8572ee98f849
diff --git a/.github/workflows/windows-compile.yml b/.github/workflows/windows-compile.yml
index b1129c7d..5981caaf 100644
--- a/.github/workflows/windows-compile.yml
+++ b/.github/workflows/windows-compile.yml
@@ -63,6 +63,10 @@ jobs:
@{ version=$os.Version; build=$os.BuildNumber; architecture=[Runtime.InteropServices.RuntimeInformation]::OSArchitecture.ToString(); administrator=$admin; evidence='component fixtures, not standard-user installation acceptance' } | ConvertTo-Json -Compress
cargo test --locked --target x86_64-pc-windows-msvc -p hiroute-host-runtime --lib standalone_install::
if ($LASTEXITCODE -ne 0) { throw 'Windows installation component regressions failed' }
+ cargo test --locked --target x86_64-pc-windows-msvc -p hiroute-host-runtime --lib storage_recovery::
+ if ($LASTEXITCODE -ne 0) { throw 'Windows startup-attempt recovery regressions failed' }
+ cargo test --locked --target x86_64-pc-windows-msvc -p hiroute-platform --lib windows::shell_registration::tests::inherited_export_is_published_privately_and_changed_material_is_not_overwritten -- --exact
+ if ($LASTEXITCODE -ne 0) { throw 'Windows recovery-material publication regression failed' }
- name: Check Windows console shell and its restricted host commands
shell: pwsh
env:
@@ -76,3 +80,5 @@ jobs:
if ($LASTEXITCODE -ne 0) { throw 'Shell frontend build failed' }
cargo check --locked --target x86_64-pc-windows-msvc -p hiroute-shell --features shell-runtime --all-targets
if ($LASTEXITCODE -ne 0) { throw 'Windows console shell compilation failed' }
+ cargo test --locked --target x86_64-pc-windows-msvc -p hiroute-shell --features shell-runtime --lib
+ if ($LASTEXITCODE -ne 0) { throw 'Windows current-installation and startup-guidance regressions failed' }
diff --git a/Cargo.lock b/Cargo.lock
index 653ea267..f50a6450 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2509,6 +2509,7 @@ version = "0.1.0"
dependencies = [
"fs2",
"getrandom 0.3.4",
+ "hiroute-diagnostics",
"hiroute-platform",
"nix",
"semver",
@@ -2674,6 +2675,7 @@ dependencies = [
"fs2",
"hiroute-application-api",
"hiroute-client-core",
+ "hiroute-diagnostics",
"hiroute-host-runtime",
"hiroute-platform",
"reqwest",
@@ -2684,6 +2686,7 @@ dependencies = [
"tauri-build",
"tauri-plugin-dialog",
"tauri-plugin-single-instance",
+ "tempfile",
"tokio",
"url",
]
diff --git a/apps/desktop/src-tauri/src/bootstrap.rs b/apps/desktop/src-tauri/src/bootstrap.rs
index b00537b0..e0b83363 100644
--- a/apps/desktop/src-tauri/src/bootstrap.rs
+++ b/apps/desktop/src-tauri/src/bootstrap.rs
@@ -72,20 +72,9 @@ fn decode_startup_failure(value: &serde_json::Value) -> Result<Option<&'static s
if failure.schema != "hiroute.daemon-startup-failure/v1" {
return Err("DAEMON_READY_INVALID");
}
- Ok(Some(match failure.code {
- StartupFailureCode::StorageUnavailable => "DAEMON_STORAGE_UNREADABLE",
- StartupFailureCode::UpgradeSourceUnsupported => "DAEMON_UPGRADE_SOURCE_UNSUPPORTED",
- StartupFailureCode::UpgradeStorageFailed => "DAEMON_UPGRADE_STORAGE_FAILED",
- StartupFailureCode::ReleaseFactsInvalid => "DAEMON_RELEASE_INVALID",
- StartupFailureCode::DependencyUnavailable => "DAEMON_DEPENDENCY_UNAVAILABLE",
- StartupFailureCode::GatewayUnavailable => "DAEMON_GATEWAY_UNAVAILABLE",
- StartupFailureCode::ControlUnavailable => "DAEMON_CONTROL_UNAVAILABLE",
- StartupFailureCode::Cancelled => "DAEMON_START_CANCELLED",
- StartupFailureCode::InvalidConfiguration
- | StartupFailureCode::WorkerRejected
- | StartupFailureCode::ReadyChannelFailed
- | StartupFailureCode::Internal => "DAEMON_START_FAILED",
- }))
+ Ok(Some(hiroute_host_runtime::startup_failure_host_code(
+ failure.code,
+ )))
}
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
diff --git a/apps/desktop/src-tauri/src/bootstrap/tests.rs b/apps/desktop/src-tauri/src/bootstrap/tests.rs
index db9431be..bb9940b8 100644
--- a/apps/desktop/src-tauri/src/bootstrap/tests.rs
+++ b/apps/desktop/src-tauri/src/bootstrap/tests.rs
@@ -186,6 +186,24 @@ fn shutdown_interrupts_a_pending_daemon_ready_read() {
#[test]
fn startup_failure_frame_maps_storage_without_accepting_extra_payload() {
+ for (code, expected) in [
+ ("storage_access_denied", "DAEMON_STORAGE_ACCESS_DENIED"),
+ ("storage_locked", "DAEMON_STORAGE_LOCKED"),
+ ("storage_key_unavailable", "DAEMON_STORAGE_KEY_UNAVAILABLE"),
+ ] {
+ assert_eq!(
+ decode_startup_failure(&serde_json::json!({
+ "schema": "hiroute.daemon-startup-failure/v1", "code": code,
+ })),
+ Ok(Some(expected))
+ );
+ }
+ assert_eq!(
+ decode_startup_failure(&serde_json::json!({
+ "schema": "hiroute.daemon-startup-failure/v1", "code": "unknown_future_recovery_action",
+ })),
+ Err("DAEMON_READY_INVALID")
+ );
assert_eq!(
decode_startup_failure(&serde_json::json!({
"schema": "hiroute.daemon-startup-failure/v1",
diff --git a/apps/desktop/src-tauri/src/bridge/startup.rs b/apps/desktop/src-tauri/src/bridge/startup.rs
index 8a93e83d..582fbf15 100644
--- a/apps/desktop/src-tauri/src/bridge/startup.rs
+++ b/apps/desktop/src-tauri/src/bridge/startup.rs
@@ -56,6 +56,8 @@ pub(super) fn start_session(
pub struct StartupReport {
state: &'static str,
#[serde(skip_serializing_if = "Option::is_none")]
+ storage_recovery: Option<hiroute_host_runtime::StorageRecovery>,
+ #[serde(skip_serializing_if = "Option::is_none")]
code: Option<String>,
recovery_available: bool,
#[serde(skip_serializing_if = "Option::is_none")]
@@ -64,44 +66,56 @@ pub struct StartupReport {
upgrade_phase: Option<hiroute_host_runtime::StorageUpgradePhase>,
}
-fn complete_upgrade_backup(root: &std::path::Path) -> Option<PathBuf> {
- // Select only known backup names and a portable owner-written batch identity.
- // The WebView never supplies a filesystem path or restoration authority.
- let parent = root.join("storage.upgrade-backups");
- if let Ok(storage) =
- hiroute_diagnostics::files::PrivateDir::open_existing(&root.join("storage"))
- && let Ok(Some(mut file)) = storage.open_read("observation-source-backup.json")
- {
- if file.len() > 16 * 1024 {
- return None;
- }
- let link: serde_json::Value =
- serde_json::from_slice(&file.read_prefix(16 * 1024).ok()?).ok()?;
- file.recheck().ok()?;
- let name = link["backup_name"].as_str()?;
- let id = link["set_id"].as_str()?;
- if link["schema"] != 1
- || !matches!(name, "migration-set" | "observation-format-5")
- || id.is_empty()
- || id.len() > 128
- || id.contains("..")
- || !id
- .bytes()
- .all(|b| b.is_ascii_alphanumeric() || matches!(b, b'-' | b'_' | b'.'))
- {
- return None;
- }
- for candidate in [
- parent.join(name),
- parent.join(format!("migration-set.{id}")),
- ] {
- if let Some(path) = published_source(&candidate, Some(id)) {
- return Some(path);
- }
- }
+fn published_backup(
+ root: &std::path::Path,
+ recovery: &hiroute_host_runtime::StorageRecovery,
+) -> Option<PathBuf> {
+ use hiroute_host_runtime::StorageRecoveryAction;
+ if !matches!(
+ recovery.action,
+ StorageRecoveryAction::ResumeCurrent | StorageRecoveryAction::RestoreCompleteGroup
+ ) {
return None;
}
- published_source(&parent.join("migration-set"), None)
+ let name = recovery.backup_name.as_deref()?;
+ let id = recovery.backup_batch.as_deref()?;
+ let portable = |s: &str| {
+ !s.is_empty()
+ && s.len() <= 128
+ && !s.contains("..")
+ && s.bytes()
+ .all(|b| b.is_ascii_alphanumeric() || b"-_.".contains(&b))
+ };
+ if !portable(name) || !portable(id) {
+ return None;
+ }
+ // This target comes from the storage owner's verified failing batch, never
+ // from whichever old directory happens to be present.
+ published_source(&root.join("storage.upgrade-backups").join(name), Some(id))
+}
+
+fn recovery_for_failure(
+ code: &str,
+ root: Option<&std::path::Path>,
+) -> Option<hiroute_host_runtime::StorageRecovery> {
+ use hiroute_diagnostics::event::StartupFailureCode as Failure;
+ use hiroute_host_runtime::StorageRecovery;
+ let storage = root.map(|root| root.join("storage"));
+ let admission = match code {
+ "DAEMON_STORAGE_UNREADABLE" => Some(Failure::StorageUnavailable),
+ "DAEMON_UPGRADE_SOURCE_UNSUPPORTED" => Some(Failure::UpgradeSourceUnsupported),
+ "DAEMON_STORAGE_ACCESS_DENIED" => Some(Failure::StorageAccessDenied),
+ "DAEMON_STORAGE_KEY_UNAVAILABLE" => Some(Failure::StorageKeyUnavailable),
+ "DAEMON_STORAGE_LOCKED" => Some(Failure::StorageLocked),
+ _ => None,
+ };
+ if let Some(code) = admission {
+ return StorageRecovery::read_for_admission_failure(code, storage.as_deref());
+ }
+ if code == "DAEMON_UPGRADE_STORAGE_FAILED" {
+ return storage.and_then(|root| StorageRecovery::read(&root).ok().flatten());
+ }
+ None
}
fn published_source(batch: &std::path::Path, expected_id: Option<&str>) -> Option<PathBuf> {
@@ -141,24 +155,28 @@ pub async fn startup_status(
) -> Result<StartupReport, String> {
super::main_window(&window)?;
if let Some(code) = state.1.error.get() {
+ let recovery = recovery_for_failure(code, state.1.data_root.as_deref());
+ let backup_directory = state.1.data_root.as_deref().and_then(|root| {
+ recovery
+ .as_ref()
+ .and_then(|record| published_backup(root, record))
+ });
return Ok(StartupReport {
state: "failed",
+ storage_recovery: recovery,
code: Some(code.clone()),
recovery_available: state.1.data_root.as_ref().is_some_and(|root| {
root.is_absolute()
&& hiroute_diagnostics::files::PrivateDir::open_existing(root).is_ok()
}),
- backup_directory: state
- .1
- .data_root
- .as_deref()
- .and_then(complete_upgrade_backup),
+ backup_directory,
upgrade_phase: state.1.upgrade_progress.lock().ok().and_then(|p| *p),
});
}
let ready = state.0.try_lock().is_ok_and(|session| session.is_some());
Ok(StartupReport {
state: if ready { "ready" } else { "starting" },
+ storage_recovery: None,
code: None,
recovery_available: false,
backup_directory: None,
@@ -178,9 +196,7 @@ pub async fn open_startup_recovery_directory(
state: State<'_, DesktopState>,
) -> Result<(), String> {
super::main_window(&window)?;
- if state.1.error.get().is_none() {
- return Err("STARTUP_RECOVERY_NOT_REQUIRED".into());
- }
+ let code = state.1.error.get().ok_or("STARTUP_RECOVERY_NOT_REQUIRED")?;
let root = state
.1
.data_root
@@ -189,7 +205,11 @@ pub async fn open_startup_recovery_directory(
.ok_or("PRIVATE_PATH_UNAVAILABLE")?;
hiroute_diagnostics::files::PrivateDir::open_existing(&root)
.map_err(|_| "PRIVATE_PATH_INVALID")?;
- let directory = complete_upgrade_backup(&root).unwrap_or(root);
+ let recovery = recovery_for_failure(code, Some(&root));
+ let directory = recovery
+ .as_ref()
+ .and_then(|record| published_backup(&root, record))
+ .unwrap_or(root);
super::diagnostics::open_in_file_manager(&directory)
.map_err(|_| "STARTUP_RECOVERY_OPEN_FAILED".into())
}
@@ -200,8 +220,21 @@ mod tests {
use std::sync::atomic::Ordering;
use std::time::Duration;
+ fn complete_upgrade_backup(root: &std::path::Path) -> Option<PathBuf> {
+ recovery_for_failure("DAEMON_UPGRADE_STORAGE_FAILED", Some(root))
+ .as_ref()
+ .and_then(|record| published_backup(root, record))
+ }
+
#[test]
- fn observation_source_locator_handles_large_manifests_and_rejects_another_batch() {
+ #[cfg(unix)]
+ fn observation_source_locator_requires_verified_material_and_rejects_another_batch() {
+ use sha2::{Digest, Sha256};
+ use std::os::unix::fs::{MetadataExt, PermissionsExt};
+ let write = |path: PathBuf, bytes: &[u8]| {
+ std::fs::write(&path, bytes).unwrap();
+ std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o600)).unwrap();
+ };
let temporary = tempfile::tempdir().unwrap();
let root = temporary.path();
let storage = root.join("storage");
@@ -214,17 +247,76 @@ mod tests {
br#"{"schema":1,"backup_name":"observation-format-5","set_id":"retained-batch"}"#,
)
.unwrap();
- std::fs::write(
- source.join("source-backup.json"),
- vec![b' '; 5 * 1024 * 1024],
- )
- .unwrap();
+ let history = source.join("storage/observation");
+ hiroute_diagnostics::files::PrivateDir::open_or_create(&history).unwrap();
+ let mut files = serde_json::Map::new();
+ for name in [
+ "storage/live/control.db",
+ "storage/live/runtime.db",
+ "storage/live/secrets.db",
+ "storage/master-key",
+ "storage/observation-hmac-key",
+ "recovery-package/hirouted",
+ ] {
+ let path = source.join(name);
+ hiroute_diagnostics::files::PrivateDir::open_or_create(path.parent().unwrap()).unwrap();
+ write(path, b"retained original");
+ files.insert(
+ name.into(),
+ serde_json::json!(format!("sha256:{:x}", Sha256::digest(b"retained original"))),
+ );
+ }
+ let identity = std::fs::metadata(&history).unwrap();
+ for (path, value) in [
+ (
+ source.join("source-backup.json"),
+ serde_json::json!({"schema":"hiroute.upgrade-source-backup/v2","complete":true,"source_info":{"batch_id":"retained-batch"},"files":files,"sealed_observation":{"identity":[identity.dev(),identity.ino()]}}),
+ ),
+ (
+ batch.join("backup-set.manifest.json"),
+ serde_json::json!({"schema":"hiroute.sqlite-backup-set/v2","set_id":"retained-batch"}),
+ ),
+ ] {
+ write(path, &serde_json::to_vec(&value).unwrap());
+ }
std::fs::write(
batch.join("source-location.json"),
br#"{"schema":1,"complete":true,"batch_id":"retained-batch"}"#,
)
.unwrap();
- assert_eq!(complete_upgrade_backup(root), Some(source));
+ let mut recovery = hiroute_host_runtime::StorageRecovery::new(
+ hiroute_host_runtime::StorageRecoveryCause::MigrationFailed,
+ hiroute_host_runtime::StorageRecoveryAction::ResumeCurrent,
+ );
+ recovery.backup_name = Some("observation-format-5".into());
+ recovery.backup_batch = Some("retained-batch".into());
+ recovery.store(&storage).unwrap();
+ assert_eq!(complete_upgrade_backup(root), Some(source.clone()));
+ for code in [
+ "DAEMON_STORAGE_UNREADABLE",
+ "DAEMON_STORAGE_LOCKED",
+ "DAEMON_STORAGE_ACCESS_DENIED",
+ "DAEMON_GATEWAY_UNAVAILABLE",
+ ] {
+ assert!(
+ recovery_for_failure(code, Some(root))
+ .as_ref()
+ .and_then(|record| published_backup(root, record))
+ .is_none(),
+ "a different current failure cannot offer an older report's recovery folder"
+ );
+ }
+ let mut verified = recovery.clone();
+ verified.cause = hiroute_host_runtime::StorageRecoveryCause::UnsupportedFormat;
+ verified.action = hiroute_host_runtime::StorageRecoveryAction::RestoreCompleteGroup;
+ verified.store(&storage).unwrap();
+ assert_eq!(
+ recovery_for_failure("DAEMON_UPGRADE_SOURCE_UNSUPPORTED", Some(root))
+ .as_ref()
+ .and_then(|record| published_backup(root, record)),
+ Some(source)
+ );
+ recovery.store(&storage).unwrap();
std::fs::write(
batch.join("source-location.json"),
br#"{"schema":1,"complete":true,"batch_id":"different-batch"}"#,
@@ -261,7 +353,8 @@ mod tests {
br#"{"schema":"hiroute.upgrade-source-backup/v1","complete":true}"#,
)
.unwrap();
- assert_eq!(complete_upgrade_backup(&root), Some(backup.clone()));
+ // Directory/manifest existence alone never grants restoration authority.
+ assert_eq!(complete_upgrade_backup(&root), None);
let other = backup.join("other.json");
std::fs::rename(&manifest, &other).unwrap();
symlink(&other, &manifest).unwrap();
diff --git a/apps/desktop/src-tauri/src/updates.rs b/apps/desktop/src-tauri/src/updates.rs
index 8d98b928..c83657f7 100644
--- a/apps/desktop/src-tauri/src/updates.rs
+++ b/apps/desktop/src-tauri/src/updates.rs
@@ -437,7 +437,33 @@ async fn recover_precommit(
})
.await;
match result {
- Ok(Ok(())) => UpdateRecovery::ServiceAvailable,
+ Ok(Ok(())) => {
+ let client = sessions
+ .lock()
+ .await
+ .as_ref()
+ .map(|session| session.client.clone());
+ if let Some(client) = client
+ && client
+ .with_timeout(std::time::Duration::from_secs(2))
+ .query::<_, hiroute_application_api::SystemStatusV1>(
+ "GetSystemStatus",
+ "update-recovery-readiness",
+ &serde_json::json!({}),
+ )
+ .await
+ .is_ok_and(|response| {
+ response.error.is_none()
+ && response.data.is_some_and(|status| {
+ status.daemon == "role_all" && status.gateway == "ready"
+ })
+ })
+ {
+ UpdateRecovery::ServiceAvailable
+ } else {
+ UpdateRecovery::RestartRequired
+ }
+ }
Ok(Err(code)) if code == "UPGRADE_STOP_PENDING" => UpdateRecovery::StopPending,
_ => UpdateRecovery::RestartRequired,
}
diff --git a/apps/desktop/src-tauri/src/updates/installer.rs b/apps/desktop/src-tauri/src/updates/installer.rs
index 27b51d8e..ea14f677 100644
--- a/apps/desktop/src-tauri/src/updates/installer.rs
+++ b/apps/desktop/src-tauri/src/updates/installer.rs
@@ -53,6 +53,11 @@ fn write_private(path: &Path, bytes: &[u8]) -> Result<(), String> {
result
}
pub(super) fn prepare(root: &Path, update: &PreparedUpdate) -> Result<PathBuf, String> {
+ hiroute_host_runtime::run_upgrade_preflight(
+ &update.staged.join("Contents/MacOS/hirouted"),
+ &root.join("storage"),
+ &update.current,
+ )?;
let id = crate::random_id()?;
let directory = update.download_root.join(format!("install-{id}"));
crate::bootstrap::private_dir(&directory)?;
diff --git a/apps/desktop/src/features/UpdatesSettings.tsx b/apps/desktop/src/features/UpdatesSettings.tsx
index 154f93a7..224a9bd5 100644
--- a/apps/desktop/src/features/UpdatesSettings.tsx
+++ b/apps/desktop/src/features/UpdatesSettings.tsx
@@ -67,11 +67,15 @@ export function UpdatesSettings({ active, language, onServiceChanged }: { active
</div>
</div>
{view?.available && !busy && <div className="gateway-risk">{view.available.notes[language]}</div>}
+ {view?.phase === 'ready' && <div className="gateway-risk">{text('如果本次升级需要切换存储格式,将保留配置、凭据与路由,并封存旧 HiRoute 历史。当前历史和统计从切换后开始;原生 Agent 的历史不变。旧历史需用完整旧数据组和配套旧程序恢复查看。', 'When this update changes the storage format, it retains configuration, credentials and routing and seals old HiRoute history. Current history and statistics begin at cutover; native Agent history is unchanged. Access old history by recovering the complete old group with its matching program.')}</div>}
{view?.phase === 'ready' && <div className="gateway-risk">{hostCapabilities().host === 'shell-console' ? text('安装前会等待现有调用和任务结束,可以取消等待。安装期间 Agent 路由会暂时不可用;失败时会尝试恢复旧版本,启动页会显示需要处理的恢复问题。', 'Installation waits for current calls and tasks; you can cancel the wait. Agent routing pauses during installation. A failed update attempts to restore the previous version; the startup page shows any recovery that needs attention.') : text('安装前会等待现有调用和任务结束。安装与首次启动期间,Agent 路由会暂时不可用;需要时可按备份目录中的说明恢复旧 App 和旧数据。', 'Installation waits for current calls and tasks. Agent routing is temporarily unavailable during installation and first startup. If needed, follow the backup instructions to restore the previous App and data.')}</div>}
- {recovery === 'service_available' && <div className="gateway-risk">{text('升级未完成,旧版本服务已恢复,可继续使用或重试安装。', 'The upgrade did not complete. The previous service is available; continue using HiRoute or retry installation.')}</div>}
+ {recovery === 'service_available' && <div className="gateway-risk">{text('升级未完成,本机服务可用。请保留数据和升级材料,按对应恢复指引继续处理。', 'The upgrade did not complete. The local service is available. Keep data and upgrade material and follow the applicable recovery instructions.')}</div>}
{recovery === 'stop_pending' && <div className="settings-inline-error" role="status">{text('服务仍在停止,尚未替换应用。请等待服务退出后,完全退出并重新打开 HiRoute。', 'The service is still stopping and the App has not been replaced. Wait for the service to exit, then fully quit and reopen HiRoute.')}</div>}
- {recovery === 'restart_required' && <div className="settings-inline-error" role="status">{text('尚未替换应用,旧版本服务未能恢复。请完全退出并重新打开 HiRoute,并查看启动页的恢复说明。', 'The App has not been replaced, but the previous service could not be restored. Fully quit and reopen HiRoute and follow the startup recovery instructions.')}</div>}
- {code && <div className="settings-inline-error" role="status">{view?.phase === 'check_failed' ? text(`检查未完成(${code})。当前版本和后台服务仍可继续使用。`, `The check did not complete (${code}). The current version and background service remain available.`) : text(`升级不可用(${code})。可重试检查,或从官网下载安装包并完全退出 HiRoute 后覆盖安装。`, `Update unavailable (${code}). Check again, or download from the official website and fully quit HiRoute before replacing the App.`)}</div>}
+ {recovery === 'restart_required' && <div className="settings-inline-error" role="status">{text('服务未能恢复。请保留数据、旧包与升级记录,重新打开 HiRoute 并按启动页的具体指引处理。', 'The service could not be restored. Keep data, old packages and upgrade journals. Reopen HiRoute and follow the specific startup recovery instructions.')}</div>}
+ {code === 'UPGRADE_PREFLIGHT_UNAVAILABLE' && <div className="settings-inline-error">{text('此候选无法执行所需升级预检。请保留正常运行的原版和数据,使用已验证的过渡版本或联系支持;不要手动覆盖绕过此拒绝。', 'This candidate cannot perform the required upgrade preflight. Keep the working original installation and data. Use a verified transition release or obtain support; do not bypass this refusal with manual replacement.')}</div>}
+ {['UPGRADE_KEY_UNAVAILABLE', 'UPGRADE_RECOVERY_PACKAGE_INVALID', 'UPGRADE_RECOVERY_PACKAGE_MISSING', 'UPGRADE_PREFLIGHT_INVALID', 'UPGRADE_PREFLIGHT_REFUSED'].includes(code ?? '') && <div className="settings-inline-error">{text('升级前提校验未通过。请保留当前程序和全部数据,核对原密钥、配套旧包及本机启动诊断;修复缺失或损坏的材料后再升级。无法取得必要材料时请寻求支持,不要反复重试或直接覆盖安装。', 'Upgrade prerequisites could not be verified. Keep the current program and all data. Check original keys, the matching complete previous package and local startup diagnostics. Correct missing or damaged material before upgrading. Obtain support if essential material is unavailable; repeated retries or manual overwrite cannot reconstruct it.')}</div>}
+ {code === 'UPGRADE_INSUFFICIENT_SPACE' && <div className="settings-inline-error">{text('数据所在磁盘缺少恢复与启动空间。请保留封存历史和旧包,释放无关文件后再重试。', 'The storage volume lacks recovery/startup space. Keep sealed history and old packages, free unrelated files, then retry.')}</div>}
+ {code && <div className="settings-inline-error" role="status">{view?.phase === 'check_failed' ? text(`检查未完成(${code})。本次检查未替换程序。请保留当前安装和数据,恢复连接后再检查。`, `The check did not complete (${code}). This check did not replace the program. Keep the installation and data and check again after restoring connectivity.`) : text(`升级未完成(${code})。请保留原数据和完整旧包,按启动页的具体指引处理。缺少材料、空间或权限的问题解决前,请勿覆盖安装或直接降级。`, `The update did not complete (${code}). Keep the original data and complete previous package and follow the specific startup instructions. Resolve missing material, space or access before replacing the program or downgrading.`)}</div>}
{view && !view.can_install && <div className="gateway-risk">{text('应用内安装需要使用完整的 HiRoute App。', 'In-app installation requires a complete HiRoute App.')}</div>}
</div></section>;
}
diff --git a/apps/desktop/src/occami/styles/components.css b/apps/desktop/src/occami/styles/components.css
index faf182f8..89cf58cc 100644
--- a/apps/desktop/src/occami/styles/components.css
+++ b/apps/desktop/src/occami/styles/components.css
@@ -438,6 +438,9 @@
.callout.warn .icon { color: var(--yellow); }
.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; }
+.startup-recovery .recovery-location { margin-block: 8px; }
+.startup-recovery .recovery-location code { white-space: normal; overflow-wrap: anywhere; user-select: text; }
.toast-stack {
position: fixed;
diff --git a/apps/desktop/src/product/DesktopApp.tsx b/apps/desktop/src/product/DesktopApp.tsx
index d66e72b0..8b6f3e76 100644
--- a/apps/desktop/src/product/DesktopApp.tsx
+++ b/apps/desktop/src/product/DesktopApp.tsx
@@ -1,3 +1,4 @@
+import { startupFailureText } from '../storage-recovery';
import { randomId } from '../random-id.ts';
import { hostCapabilities } from '../host/index.ts';
import { HostNotices } from '../host/ConsoleUi';
@@ -172,6 +173,7 @@ export function DesktopApp() {
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');
const upgradePhase = home.startup?.state === 'starting' ? home.startup.upgrade_phase : undefined;
const upgradePhaseText = upgradePhase ? ({
source_check: language === 'zh' ? '正在校验存储格式' : 'Checking storage format',
@@ -635,19 +637,23 @@ 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>}
- {startupFailure && <div className="callout bad" role="alert" data-error-code={startupFailure.code}>
+ {startupFailure && <div className="callout bad startup-recovery" role="alert" data-error-code={startupFailure.code}>
<UiIcon name="warning" />
<div>
<strong>{language === 'zh' ? '本机服务启动失败' : 'Local service failed to start'}</strong>
- <p>{startupFailure.code === 'DAEMON_UPGRADE_SOURCE_UNSUPPORTED'
- ? (language === 'zh' ? '此数据格式尚无经过验证的升级与恢复路径。请保留原数据并使用对应旧版本,勿清空目录重试。' : 'This data format has no verified upgrade and recovery path. Keep the data and use its matching previous version.')
- : startupFailure.backup_directory
- ? (language === 'zh' ? '请保留当前数据目录,按升级备份中的《恢复说明.md》恢复整组数据,并覆盖安装说明指定的旧版本。恢复会舍弃备份之后的新数据。' : 'Keep the current data directory. Follow the recovery guide in the upgrade backup to restore the complete data set and install the specified previous version. Changes made after the backup will be lost.')
- : (language === 'zh' ? `启动阶段失败(${startupFailure.code ?? 'STARTUP_FAILED'})。请保留现有数据,打开恢复目录查看日志并备份。` : `Startup failed (${startupFailure.code ?? 'STARTUP_FAILED'}). Keep the existing data; open the recovery directory to inspect logs and back it up.`)}</p>
- {startupFailure.backup_directory && <p>{language === 'zh' ? '升级备份:' : 'Upgrade backup: '}{startupFailure.backup_directory}</p>}
+ <p>{startupMessage.reason}</p>
+ <p>{startupMessage.instructions}</p>
+ {startupMessage.backupBatch && <div className="recovery-location">
+ <p><strong>{language === 'zh' ? '已校验的原批次:' : 'Verified original batch: '}</strong><code>{startupMessage.backupBatch}</code></p>
+ <p><strong>{language === 'zh' ? '恢复目录:' : 'Recovery directory: '}</strong><code>{startupMessage.backupDirectory}</code></p>
+ <p>{startupMessage.locationHint}</p>
+ </div>}
{startupFailure.recovery_available && <button className="btn" type="button" onClick={() => {
void invoke('open_startup_recovery_directory').catch(() => setNotice(language === 'zh' ? '无法安全打开恢复目录,请检查目录权限后重试。' : 'The recovery directory could not be opened safely. Check its permissions and try again.'));
- }}>{startupFailure.backup_directory ? (language === 'zh' ? '打开升级备份与恢复说明' : 'Open upgrade backup and recovery guide') : (language === 'zh' ? '打开恢复目录' : 'Open recovery directory')}</button>}
+ }}>{startupFailure.backup_directory ? (language === 'zh' ? '查看保留的恢复材料与说明' : 'Inspect preserved recovery material and guide') : (language === 'zh' ? '打开数据目录' : 'Open data directory')}</button>}
+ <button className="btn" type="button" onClick={() => {
+ void invoke('open_diagnostic_directory').catch(() => setNotice(language === 'zh' ? '无法安全打开诊断目录,请保留数据并联系支持。' : 'The diagnostic directory could not be opened safely. Keep your data and contact support.'));
+ }}>{language === 'zh' ? '打开诊断目录' : 'Open diagnostics'}</button>
</div>
</div>}
diff --git a/apps/desktop/src/product/use-desktop-home.ts b/apps/desktop/src/product/use-desktop-home.ts
index 372be730..e35ebadf 100644
--- a/apps/desktop/src/product/use-desktop-home.ts
+++ b/apps/desktop/src/product/use-desktop-home.ts
@@ -51,7 +51,7 @@ function observationRequest(view: string, query: object) {
}
export function useDesktopHome() {
- const [startup, setStartup] = useState<{ state: 'starting' | 'ready' | 'failed'; code?: string; recovery_available: boolean; backup_directory?: string; upgrade_phase?: 'source_check' | 'backup' | 'conversion' | 'validation' | 'service_recovery' } | null>(null);
+ const [startup, setStartup] = useState<{ state: 'starting' | 'ready' | 'failed'; code?: string; storage_recovery?: unknown; recovery_available: boolean; backup_directory?: string; upgrade_phase?: 'source_check' | 'backup' | 'conversion' | 'validation' | 'service_recovery' } | null>(null);
const [service, setService] = useState<DomainReadSlot<HomeService>>(loading);
const [compute, setCompute] = useState<DomainReadSlot<HomeCompute>>(loading);
const [plans, setPlans] = useState<DomainReadSlot<HomePlans>>(loading);
diff --git a/apps/desktop/src/storage-recovery.ts b/apps/desktop/src/storage-recovery.ts
new file mode 100644
index 00000000..b11cee4b
--- /dev/null
+++ b/apps/desktop/src/storage-recovery.ts
@@ -0,0 +1,80 @@
+// Presentation only: the storage owner supplies the recovery disposition.
+export type StorageRecovery = {
+ schema: 'hiroute.storage-startup-recovery/v1';
+ cause: 'missing_package' | 'invalid_package' | 'insufficient_space' | 'access_denied' | 'locked' | 'missing_key' | 'unsupported_format' | 'namespace_unavailable' | 'migration_failed' | 'unknown_state';
+ action: 'retry_current' | 'preserve_and_diagnose' | 'resume_current' | 'restore_complete_group';
+ backup_batch?: string;
+ backup_name?: string;
+ storage_space?: { required_bytes: number; available_bytes: number };
+};
+type RecoveryText = { reason: string; instructions: string; canRetry: boolean; backupBatch?: string; backupDirectory?: string; locationHint?: string };
+export function storageRecoveryText(value: unknown, language: 'zh' | 'en', platform: string): RecoveryText {
+ const text = (zh: string, en: string) => language === 'zh' ? zh : en;
+ const record = value && typeof value === 'object' ? value as Partial<StorageRecovery> : null;
+ const trusted = record?.schema === 'hiroute.storage-startup-recovery/v1';
+ const cause = trusted ? record.cause : undefined;
+ const reasons: Record<string, string> = {
+ missing_package: text('缺少配套旧版本的完整恢复包,升级已停止。', 'The upgrade stopped because the matching complete previous package is missing.'),
+ invalid_package: text('旧版本恢复包或升级交接记录无法通过校验。', 'The previous recovery package or installation handoff could not be verified.'),
+ insufficient_space: text('数据所在磁盘的恢复材料与启动空间不足。', 'The storage volume has insufficient space for recovery material and startup.'),
+ access_denied: text('无法安全访问所需文件,请检查占用、权限与所有者。', 'Required files could not be accessed safely. Check file use, permissions and ownership.'),
+ locked: text('另一个 HiRoute 实例正在使用这组数据。', 'Another HiRoute instance is using this data group.'),
+ missing_key: text('原数据所需的密钥无法读取或校验。', 'A key required by the original data is unavailable or invalid.'),
+ unsupported_format: text('这组数据的格式没有经过验证的升级路径。', 'This data format has no verified upgrade path.'),
+ namespace_unavailable: text('历史目录无法在同一文件系统内安全封存。请保留材料,检查原历史目录和恢复目标所在磁盘及占用情况。', 'The history directory cannot be sealed safely on the same filesystem. Keep all material and check the history and recovery destination volumes and file use.'),
+ migration_failed: text('数据升级未完成,需要核对保留的恢复材料。', 'The storage upgrade did not complete. Check the preserved recovery material.'),
+ };
+ const knownCause = cause === 'unknown_state' || !!cause && Object.hasOwn(reasons, cause);
+ const reason = cause && Object.hasOwn(reasons, cause) ? reasons[cause] : text('无法确认这组数据的升级状态。', 'The storage upgrade state could not be established.');
+ let instructions = text('请保留所有数据版本、密钥、完整安装包和升级记录。不要直接降级、删除数据或反复重试。查看启动诊断和对应批次的完整恢复说明;整组还原前,先另存新版数据及其配套程序。缺少密钥或完整备份时,请保留材料并寻求支持。', 'Keep every data generation, key, complete package and upgrade journal. Do not downgrade, delete data or retry blindly. Inspect startup diagnostics and the matching complete-group recovery guide. Preserve newer data and its matching program separately before restoration. Missing keys or complete backups may require support.');
+ const portable = (name: unknown): name is string => typeof name === 'string' && /^[A-Za-z0-9._-]{1,128}$/.test(name) && !name.includes('..');
+ const batch = trusted && knownCause && portable(record.backup_batch) && portable(record.backup_name);
+ const located = batch && ['resume_current', 'restore_complete_group'].includes(record.action ?? '');
+ if (trusted && ['resume_current', 'restore_complete_group'].includes(record.action ?? '') && batch) {
+ instructions = record.action === 'resume_current'
+ ? text('已识别并校验原升级批次的恢复材料。请保留所有数据,重新打开当前版本继续该批次;不要运行旧版程序。若仍无法继续,请按该批次的完整恢复说明处理,并先另存新版数据及配套程序。', 'The original upgrade batch and its recovery material were verified. Keep all data and reopen the current version to continue that batch. Do not run an older program. If it cannot continue, follow this batch’s complete recovery guide, first preserving newer data and its matching program separately.')
+ : text('请停止 HiRoute,先另存新版数据及其配套程序,再按已校验批次的恢复说明,还原完整旧数据组及配套旧程序。不要逐库覆盖或混用不同批次。', 'Stop HiRoute and preserve newer data with its matching program separately. Follow the verified batch’s recovery guide to restore the complete old group and matching old program. Never replace individual databases or mix batches.');
+ } else if (cause === 'missing_package' || cause === 'invalid_package') {
+ instructions = platform === 'macos'
+ ? text('请保留所有数据、密钥、升级记录和升级前使用的完整 App。尚未确认原数据组可由旧版读取,请勿直接降级或覆盖数据。打开诊断目录,联系支持核对配套恢复包和受支持的升级路径;缺少原版完整 App 或必要材料时,无法保证恢复服务。', 'Keep all data, keys, upgrade journals and the complete App used before this upgrade. Compatibility with the old program has not been established; do not downgrade or overwrite data. Open diagnostics and contact support to verify the matching recovery package and supported upgrade route. Recovery cannot be guaranteed without the original complete App and required material.')
+ : text('请保留全部数据和升级记录,通过受支持的安装流程补齐并校验配套旧版本完整包。后台服务必须实际收到恢复包信息;仅在终端设置环境变量并不够。查看安装指南和启动诊断;请勿直接降级或覆盖数据。原包或必要材料无法取得时,请联系支持。', 'Keep all data and upgrade journals. Supply and verify the complete matching previous package through the supported installation workflow. The actual background service must receive the recovery input; setting a terminal variable alone is insufficient. Follow the installation guide and inspect startup diagnostics. Do not downgrade or overwrite data. Contact support if the original package or required material is unavailable.');
+ } else if (cause === 'insufficient_space') {
+ instructions = text('请释放数据所在磁盘上的无关文件,保留原数据、封存历史和恢复包。空间足够后,重新打开当前版本继续恢复;不要删除升级备份。', 'Free unrelated files on the storage volume, keeping original data, sealed history and recovery packages. Once enough space is available, reopen the current version to continue recovery. Do not delete upgrade backups.');
+ } else if (cause === 'access_denied' || cause === 'locked') {
+ instructions = text('请关闭其他 HiRoute 实例并解决相关文件占用或访问问题,再重新打开当前版本。保留所有数据和升级记录,不要批量修改权限或清空目录。', 'Close other HiRoute instances and resolve the file-use or access issue, then reopen the current version. Keep all data and upgrade journals. Do not change permissions recursively or empty directories.');
+ }
+ const space = trusted && record.storage_space;
+ if (cause === 'insufficient_space' && space && Number.isSafeInteger(space.required_bytes) && Number.isSafeInteger(space.available_bytes) && space.required_bytes >= 0 && space.available_bytes >= 0) {
+ const mb = (bytes: number) => `${Math.ceil(bytes / 1048576).toLocaleString(language === 'zh' ? 'zh-CN' : 'en-US')} MiB`;
+ instructions += text(` 数据所在磁盘预计需要 ${mb(space.required_bytes)},当前可用 ${mb(space.available_bytes)}。`, ` The storage volume requires approximately ${mb(space.required_bytes)}; ${mb(space.available_bytes)} is available.`);
+ }
+ return { reason, instructions,
+ backupBatch: located ? record.backup_batch : undefined,
+ backupDirectory: located ? `storage.upgrade-backups/${record.backup_name}/source/` : undefined,
+ locationHint: located ? platform === 'windows'
+ ? text('在下方本机日志目录的上一级,进入上述备份目录。先读 RECOVERY.md 或恢复说明.md,再按需阅读 PROGRAM-LOCATIONS.md。', 'From the parent of the local log folder below, open this backup directory. Read RECOVERY.md (or 恢复说明.md), then PROGRAM-LOCATIONS.md where present.')
+ : text('通过下方按钮打开已保留的恢复材料,核对批次后阅读 RECOVERY.md 或恢复说明.md;不要使用其它批次。', 'Open the preserved recovery material with the button below. Match this batch and read RECOVERY.md or 恢复说明.md; do not use another batch.')
+ : undefined,
+ canRetry: trusted && (record.action === 'resume_current' && batch || record.action === 'retry_current' && ['insufficient_space', 'access_denied', 'locked'].includes(cause ?? '')) };
+}
+
+export function startupFailureText(code: string | undefined | null, recovery: unknown, language: 'zh' | 'en', platform: string): RecoveryText {
+ const text = (zh: string, en: string) => language === 'zh' ? zh : en;
+ if (recovery || ['DAEMON_STORAGE_UNREADABLE', 'DAEMON_UPGRADE_SOURCE_UNSUPPORTED', 'DAEMON_UPGRADE_STORAGE_FAILED'].includes(code ?? '')) {
+ return storageRecoveryText(recovery, language, platform);
+ }
+ const reasons: Record<string, string> = {
+ DAEMON_DEPENDENCY_UNAVAILABLE: text('本机服务所需的配套组件无法启动。', 'A required bundled service component could not start.'),
+ DAEMON_GATEWAY_UNAVAILABLE: text('数据初始化已完成,但 Gateway 监听未就绪。', 'Storage initialization completed, but the Gateway listener is unavailable.'),
+ DAEMON_CONTROL_UNAVAILABLE: text('本机控制接口无法启动。', 'The local control interface could not start.'),
+ DAEMON_RELEASE_INVALID: text('当前完整程序的发布信息无法通过校验。', 'The complete program’s release identity could not be verified.'),
+ DAEMON_START_CANCELLED: text('本次服务启动已取消。', 'This service startup was cancelled.'),
+ };
+ return {
+ reason: reasons[code ?? ''] ?? text('本机服务尚未就绪,请查看启动诊断。', 'The local service is unavailable. Inspect startup diagnostics.'),
+ instructions: code === 'DAEMON_GATEWAY_UNAVAILABLE'
+ ? text('请检查配置的监听地址、端口及占用情况,再重新启动当前版本。此提示不要求还原数据库;请保留现有数据与恢复材料。', 'Check the configured listener address, port and file use, then reopen the current version. This failure does not require database restoration. Keep existing data and recovery material.')
+ : text('请保留数据和恢复材料,查看本机诊断中的具体原因。检查当前完整安装包及其配套组件;需要修复程序时使用同一版本的完整安装包。此提示不授权降级或还原数据库。', 'Keep data and recovery material and inspect the local startup diagnostics. Check the complete current package and its bundled components; use the same complete version for program repair. This failure does not authorize downgrade or database restoration.'),
+ canRetry: code === 'DAEMON_START_CANCELLED',
+ };
+}
diff --git a/apps/desktop/tests/README.md b/apps/desktop/tests/README.md
index 0ad8f4ef..29b53652 100644
--- a/apps/desktop/tests/README.md
+++ b/apps/desktop/tests/README.md
@@ -16,7 +16,9 @@ language/theme/size matrix. Native origin ACLs, NSIS, Task/login effects and rea
upgrades keep their [installed gates](../../../docs/windows-desktop-installation.md#evidence-and-release-claims).
It also distinguishes an unavailable Windows update catalog from installation
recovery, and checks the bundled local-listener recovery instructions and usable
-Recheck action at both supported window sizes.
+Recheck action at both supported window sizes. Incomplete installation has a
+neutral heading and exact version/build installer repair, without storage retry
+or an unrelated recovery location.
Start with the user capability, then choose the smallest layer that can observe its
contract. Node state tests explain decision rules; browser scenarios exercise the
@@ -27,6 +29,7 @@ proves native authorization, persistence, process cleanup or real model calls.
| User capability | Representative tests | Unique guarantee |
| --- | --- | --- |
+| 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. |
| Enable or edit Codex routing | `codex.enable.draft-cancel`, `codex.routing.fixed-binding`, `codex.routing.mixed-native-default` in [Agent scenarios](v3/browser/agent-trust-scenarios.mjs) | Cancelling never applies; configured fixed overrides, native reasoning and the chosen default survive save; service responsibility is explained. |
diff --git a/apps/desktop/tests/storage-recovery.test.mjs b/apps/desktop/tests/storage-recovery.test.mjs
new file mode 100644
index 00000000..bdfd277c
--- /dev/null
+++ b/apps/desktop/tests/storage-recovery.test.mjs
@@ -0,0 +1,77 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { storageRecoveryText, startupFailureText } from '../src/storage-recovery.ts';
+const report=(cause,action)=>({schema:'hiroute.storage-startup-recovery/v1',cause,action});
+test('missing packages and retired or unknown actions never authorize program-only downgrade',()=>{
+ for (const language of ['zh','en']) {
+ for (const value of [undefined,report('missing_package','preserve_and_diagnose'),report('missing_package','reinstall_original'),report('missing_key','future_action'),{...report('missing_package','preserve_and_diagnose'),schema:'future'}]) {
+ const message=storageRecoveryText(value,language,'macos');
+ assert.doesNotMatch(message.instructions,language==='zh'?/尚未改变原数据组|重新安装升级前使用的完整原版/:/has not changed the original data group|reinstall the exact complete App/);
+ assert.equal(message.canRetry,false);
+ }
+ }
+});
+test('Windows does not instruct users to reinstall a macOS App and low space preserves backups',()=>{
+ const windows=storageRecoveryText(report('missing_package','preserve_and_diagnose'),'en','windows');
+ assert.doesNotMatch(windows.instructions,/App|Settings/);
+ const low=storageRecoveryText(report('insufficient_space','retry_current'),'en','windows');
+ assert.equal(low.canRetry,true);
+ assert.match(low.instructions,/Do not delete upgrade backups/);
+});
+
+test('resume requires a portable original batch and measured space stays bounded',()=>{
+ for (const id of [undefined,'../foreign','..','',42]) {
+ const value={...report('migration_failed','resume_current'),backup_batch:id};
+ assert.equal(storageRecoveryText(value,'en','windows').canRetry,false);
+ }
+ assert.equal(storageRecoveryText({...report('migration_failed','resume_current'),backup_batch:'set_original',backup_name:'observation-format-5'},'en','windows').canRetry,true);
+ const low=storageRecoveryText({...report('insufficient_space','retry_current'),storage_space:{required_bytes:1048576000,available_bytes:1048576}},'en','windows');
+ assert.match(low.instructions,/1,000 MiB.*1 MiB/);
+});
+
+test('verified recovery shows its exact original batch and source, with a usable folder route',()=>{
+ for (const language of ['zh','en']) for (const action of ['resume_current','restore_complete_group']) {
+ const value={...report('migration_failed',action),backup_batch:'set_original',backup_name:'observation-format-5'};
+ const windows=storageRecoveryText(value,language,'windows');
+ assert.equal(windows.backupBatch,'set_original');
+ assert.equal(windows.backupDirectory,'storage.upgrade-backups/observation-format-5/source/');
+ assert.match(windows.locationHint,/RECOVERY\.md.*PROGRAM-LOCATIONS\.md/);
+ assert.match(windows.locationHint,language==='zh'?/本机日志目录的上一级/:/parent of the local log folder/);
+ const mac=storageRecoveryText(value,language,'macos');
+ assert.match(mac.locationHint,language==='zh'?/下方按钮/:/button below/);
+ }
+});
+
+test('missing or unsafe source names and unknown causes never grant located recovery or resume',()=>{
+ for (const name of [undefined,'../foreign','..','',42,'a'.repeat(129)]) {
+ const value={...report('migration_failed','resume_current'),backup_batch:'set_original',backup_name:name};
+ const message=storageRecoveryText(value,'en','windows');
+ assert.equal(message.canRetry,false);assert.equal(message.backupDirectory,undefined);
+ }
+ for (const cause of ['future_cause','__proto__']) {
+ const value={...report(cause,'resume_current'),backup_batch:'set_original',backup_name:'observation-format-5'};
+ const message=storageRecoveryText(value,'en','windows');
+ assert.equal(message.canRetry,false);assert.equal(message.backupDirectory,undefined);
+ assert.match(message.reason,/could not be established/);
+ }
+});
+
+test('healthy-storage listener failures do not recommend storage recovery',()=>{
+ for (const language of ['zh','en']) {
+ const value=startupFailureText('DAEMON_GATEWAY_UNAVAILABLE',undefined,language,'macos');
+ assert.match(value.reason,language==='zh'?/数据初始化已完成/:/Storage initialization completed/);
+ assert.doesNotMatch(value.instructions,language==='zh'?/完整旧数据组/:/restore the complete old group/);
+ }
+});
+
+test('unverified missing packages give platform-specific repair steps and no blind retry',()=>{
+ for (const language of ['zh','en']) {
+ const mac=storageRecoveryText(report('missing_package','preserve_and_diagnose'),language,'macos');
+ assert.match(mac.instructions,language==='zh'?/尚未确认.*旧版读取/:/Compatibility with the old program has not been established/);
+ assert.match(mac.instructions,language==='zh'?/打开诊断目录/:/Open diagnostics/);
+ const managed=storageRecoveryText(report('invalid_package','preserve_and_diagnose'),language,'windows');
+ assert.match(managed.instructions,language==='zh'?/仅在终端设置环境变量并不够/:/terminal variable alone is insufficient/);
+ assert.equal(mac.canRetry,false);
+ assert.equal(managed.canRetry,false);
+ }
+});
diff --git a/apps/desktop/tests/v3/visual/agent-trust-active.mjs b/apps/desktop/tests/v3/visual/agent-trust-active.mjs
index a15e47fd..066222be 100644
--- a/apps/desktop/tests/v3/visual/agent-trust-active.mjs
+++ b/apps/desktop/tests/v3/visual/agent-trust-active.mjs
@@ -25,7 +25,9 @@ try {
await mkdir(outputRoot, { recursive: true });
const client = await connectPage(port);
try {
- if (process.argv[5] === '--shell-host-only') {
+ if (process.argv[5] === '--storage-recovery-only') {
+ await (await import('./storage-recovery-scenarios.mjs')).runStorageRecoveryScenarios(client, baseUrl, outputRoot);
+ } else if (process.argv[5] === '--shell-host-only') {
await (await import('./shell-host-scenarios.mjs')).runShellHostScenarios(client, baseUrl, outputRoot);
} else if (process.argv[5] === '--console-only') {
await (await import('./console-scenarios.mjs')).runConsoleScenarios(client, baseUrl, outputRoot);
diff --git a/apps/desktop/tests/v3/visual/agent-trust.mjs b/apps/desktop/tests/v3/visual/agent-trust.mjs
index 1d96ef8c..ad65b999 100644
--- a/apps/desktop/tests/v3/visual/agent-trust.mjs
+++ b/apps/desktop/tests/v3/visual/agent-trust.mjs
@@ -10,7 +10,7 @@ const desktopRoot = path.resolve(here, '../../..');
const outputRoot = path.resolve(process.argv[2] ?? path.join(desktopRoot, 'test-results/v3-agent-trust'));
const subscriptionProxyOnly = process.argv[3] === '--subscription-proxy-only';
const shellOnly = process.argv[3] === '--shell-only' || subscriptionProxyOnly;
-if (process.argv[3] && !['--shell-host-only', '--console-only', '--shell-only', '--subscription-proxy-only', '--route-save-only', '--worker-replacement-only', '--claude-collaboration-only', '--route-options-only'].includes(process.argv[3])) throw new Error(`Unknown scenario selection: ${process.argv[3]}`);
+if (process.argv[3] && !['--storage-recovery-only', '--shell-host-only', '--console-only', '--shell-only', '--subscription-proxy-only', '--route-save-only', '--worker-replacement-only', '--claude-collaboration-only', '--route-options-only'].includes(process.argv[3])) throw new Error(`Unknown scenario selection: ${process.argv[3]}`);
const routeSaveOnly = process.argv[3] === '--route-save-only';
const workerReplacementOnly = process.argv[3] === '--worker-replacement-only';
const claudeCollaborationOnly = process.argv[3] === '--claude-collaboration-only';
@@ -80,7 +80,7 @@ try {
try { await waitFor(`http://127.0.0.1:${cdpPort}/json/version`); }
catch (error) { throw new Error(`${error.message}\n${chromeErrors}`); }
const consoleOnly = process.argv[3] === '--console-only';
- const runner = spawn(process.execPath, [path.join(here, 'agent-trust-active.mjs'), String(cdpPort), `http://${consoleOnly ? 'console.test' : '127.0.0.1'}:${httpPort}/`, outputRoot, ...(process.argv[3] === '--shell-host-only' ? ['--shell-host-only'] : consoleOnly ? ['--console-only'] : subscriptionProxyOnly ? ['--subscription-proxy-only'] : shellOnly ? ['--shell-only'] : routeSaveOnly ? ['--route-save-only'] : workerReplacementOnly ? ['--worker-replacement-only'] : claudeCollaborationOnly ? ['--claude-collaboration-only'] : routeOptionsOnly ? ['--route-options-only'] : [])], { cwd: desktopRoot, stdio: 'inherit' });
+ const runner = spawn(process.execPath, [path.join(here, 'agent-trust-active.mjs'), String(cdpPort), `http://${consoleOnly ? 'console.test' : '127.0.0.1'}:${httpPort}/`, outputRoot, ...(process.argv[3] === '--storage-recovery-only' ? ['--storage-recovery-only'] : process.argv[3] === '--shell-host-only' ? ['--shell-host-only'] : consoleOnly ? ['--console-only'] : subscriptionProxyOnly ? ['--subscription-proxy-only'] : shellOnly ? ['--shell-only'] : routeSaveOnly ? ['--route-save-only'] : workerReplacementOnly ? ['--worker-replacement-only'] : claudeCollaborationOnly ? ['--claude-collaboration-only'] : routeOptionsOnly ? ['--route-options-only'] : [])], { cwd: desktopRoot, stdio: 'inherit' });
const outcome = await waitForExit(runner);
if (outcome.code !== 0) process.exitCode = outcome.code ?? 1;
} finally {
diff --git a/apps/desktop/tests/v3/visual/shell-host-scenarios.mjs b/apps/desktop/tests/v3/visual/shell-host-scenarios.mjs
index 3fdba023..ab47d9b2 100644
--- a/apps/desktop/tests/v3/visual/shell-host-scenarios.mjs
+++ b/apps/desktop/tests/v3/visual/shell-host-scenarios.mjs
@@ -68,6 +68,11 @@ export async function runShellHostScenarios(client,baseUrl,output) {
await navigate(client,new URL('/@fs'+shellIndex,baseUrl).href,{width,height});await waitFor(client,'Boolean(document.querySelector("#explanation")?.textContent)');
const box=await evaluate(client,`(()=>{const e=document.querySelector('.shell-status section'),b=e.getBoundingClientRect();return{left:b.left,right:b.right,overflow:e.scrollWidth>e.clientWidth+1,theme:document.querySelector('#root').dataset.theme,button:[...document.querySelectorAll('button')].filter(b=>!b.hidden).map(b=>({width:b.getBoundingClientRect().width,height:b.getBoundingClientRect().height}))};})()`);
assert(box.left>=0&&box.right<=width+1&&!box.overflow&&box.theme===theme&&box.button.every(b=>b.width>35&&b.height>25),'Shell startup layout failed: '+JSON.stringify(box));
+ if(phase==='failed') {
+ const state=await evaluate(client,`({heading:document.querySelector('#phase').textContent,text:document.querySelector('#explanation').textContent,retry:!document.querySelector('#retry').hidden,recovery:!document.querySelector('#recovery-material').hidden})`);
+ assert(state.heading===(language==='zh'?'安装尚未完成':'Installation is incomplete')&&!state.retry&&!state.recovery,'Installer recovery borrowed service/storage failure actions: '+JSON.stringify(state));
+ assert(state.text.includes(language==='zh'?'相同版本及构建':'same version and build')&&state.text.includes(language==='zh'?'寻求支持':'obtain support'),'Installer recovery did not identify the exact retry or missing-installer fallback');
+ }
if(phase==='listener-unavailable') {
const state=await evaluate(client,`(()=>{const recovery=document.querySelector('#console-recovery');const main=document.querySelector('.shell-status');main.scrollTop=0;return{heading:document.querySelector('#phase').textContent,visible:recovery&&!recovery.hidden,steps:recovery?.textContent,top:document.querySelector('h1').getBoundingClientRect().top,commands:recovery?.querySelector('pre')?.textContent};})()`);
assert(state.visible&&state.heading===(language==='zh'?'本机控制台尚未就绪':'The local console is unavailable')&&state.top>=0,'Healthy service was described as a startup failure or clipped: '+JSON.stringify(state));
diff --git a/apps/desktop/tests/v3/visual/storage-recovery-scenarios.mjs b/apps/desktop/tests/v3/visual/storage-recovery-scenarios.mjs
new file mode 100644
index 00000000..550490aa
--- /dev/null
+++ b/apps/desktop/tests/v3/visual/storage-recovery-scenarios.mjs
@@ -0,0 +1,80 @@
+import { writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { evaluate, navigate, waitFor } from './cdp-client.mjs';
+
+// Presentation coverage through the real Desktop and bundled Windows page.
+// Host replies are fixtures; this does not establish installed recovery acceptance.
+export async function runStorageRecoveryScenarios(client, baseUrl, output) {
+ const assert = (condition, message) => { if (!condition) throw new Error(message); };
+ const results = [];
+ const cases = [
+ { cause: 'missing_package', action: 'preserve_and_diagnose' },
+ { cause: 'insufficient_space', action: 'retry_current', storage_space: { required_bytes: 1073741824, available_bytes: 1048576 } },
+ { cause: 'namespace_unavailable', action: 'preserve_and_diagnose' },
+ { cause: 'migration_failed', action: 'resume_current', backup_batch: 'set_original', backup_name: 'migration-set' },
+ { cause: 'migration_failed', action: 'restore_complete_group', backup_batch: 'set_original', backup_name: 'migration-set' },
+ { variant:'long-location', cause:'migration_failed',action:'restore_complete_group',backup_batch:'set_'+ 'a'.repeat(100),backup_name:'observation-format-5.'+'b'.repeat(100) },
+ { cause: 'future_cause', action: 'future_action' },
+ ];
+ for (const platform of ['macos', 'windows']) for (const language of ['zh', 'en']) for (const theme of ['light', 'dark']) for (const [width, height] of [[1200, 813], [755, 600]]) for (const fixture of cases) {
+ const {variant,...facts}=fixture;
+ const report = { schema: 'hiroute.storage-startup-recovery/v1', ...facts };
+ const hasSource = ['resume_current', 'restore_complete_group'].includes(fixture.action);
+ const id = `${platform}.${fixture.cause}.${fixture.action}.${language}.${theme}.${width}${variant?'.'+variant:''}`;
+ await client.send('Emulation.setEmulatedMedia', { features: [{ name: 'prefers-color-scheme', value: theme }] });
+ let script;
+ try {
+ if (platform === 'macos') {
+ await navigate(client, new URL('product-shell.html', baseUrl).href, { width, height });
+ await waitFor(client, 'Boolean(window.productShell)');
+ await evaluate(client, `(()=>{
+ localStorage.setItem('hiroute.language', ${JSON.stringify(language)});
+ localStorage.setItem('hiroute.theme', ${JSON.stringify(theme)});
+ window.productShell.handlers.desktop_snapshot=()=>{throw 'DAEMON_NOT_READY';};
+ window.productShell.handlers.startup_status=()=>({state:'failed',code:'DAEMON_UPGRADE_STORAGE_FAILED',recovery_available:${hasSource},backup_directory:${JSON.stringify(hasSource ? `/Users/example/Library/Application Support/ai.hiroute.desktop/storage.upgrade-backups/${fixture.backup_name}/source` : undefined)},storage_recovery:${JSON.stringify(report)}});
+ window.productShell.remount();
+ })()`);
+ await waitFor(client, 'Boolean(document.querySelector("[data-error-code=DAEMON_UPGRADE_STORAGE_FAILED]"))');
+ } else {
+ script = await client.send('Page.addScriptToEvaluateOnNewDocument', { source: `Object.defineProperty(navigator,'language',{value:${JSON.stringify(language)}});window.__TAURI_INTERNALS__={invoke:async()=>({phase:'failed',code:'DAEMON_UPGRADE_STORAGE_FAILED',logs_path:'C:\\\\Users\\\\example\\\\AppData\\\\Local\\\\HiRoute\\\\diagnostics',storage_recovery:${JSON.stringify(report)}})};` });
+ const shell = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../shell/index.html');
+ await navigate(client, new URL('/@fs' + shell, baseUrl).href, { width, height });
+ await waitFor(client, 'document.querySelector("#failure")?.textContent === "DAEMON_UPGRADE_STORAGE_FAILED"');
+ }
+ const selector = platform === 'macos' ? '[data-error-code=DAEMON_UPGRADE_STORAGE_FAILED]' : '#explanation';
+ const geometry = await evaluate(client, `(()=>{const e=document.querySelector(${JSON.stringify(selector)}); e.scrollIntoView({block:'start'});const b=e.getBoundingClientRect();return{text:e.textContent,left:b.left,right:b.right,overflow:e.scrollWidth>e.clientWidth+1,height:b.height,bodyOverflow:document.documentElement.scrollWidth>innerWidth+1,retry:!!document.querySelector('#retry')&&document.querySelector('#retry').getClientRects().length>0};})()`);
+ if (platform === 'macos') assert(geometry.height < height * 0.8, `Startup guidance stretched to fill the page: ${id}`);
+ assert(!geometry.overflow && !geometry.bodyOverflow && geometry.left >= 0 && geometry.right <= width + 1, `Recovery guidance overflow: ${id} ${JSON.stringify(geometry)}`);
+ assert((language === 'zh' ? /保留|另存/ : /keep|preserv/i).test(geometry.text), `Preservation guidance missing: ${id}`);
+ if (fixture.action === 'preserve_and_diagnose' || fixture.action === 'future_action') {
+ assert(!geometry.text.includes(language === 'zh' ? '尚未改变原数据组' : 'has not changed the original data group'), `Unproven original compatibility: ${id}`);
+ }
+ const expected = {
+ missing_package: language === 'zh' ? '配套旧版本' : 'matching complete previous package',
+ insufficient_space: 'MiB',
+ namespace_unavailable: language === 'zh' ? '同一文件系统' : 'same filesystem',
+ migration_failed: language === 'zh' ? '批次' : 'batch',
+ future_cause: language === 'zh' ? '无法确认' : 'could not be established',
+ }[fixture.cause];
+ assert(geometry.text.includes(expected), `Specific reason/action missing: ${id}`);
+ const located=await evaluate(client,`(()=>{const e=document.querySelector(${JSON.stringify(platform==='macos'?'.recovery-location':'#recovery-material')});return e&&e.getClientRects().length?{text:e.textContent,overflow:e.scrollWidth>e.clientWidth+1}:null;})()`);
+ if(hasSource){
+ assert(located&&!located.overflow&&located.text.includes(fixture.backup_batch)&&located.text.includes(fixture.backup_name)&&located.text.includes('RECOVERY.md'),`Original recovery location missing or overflowing: ${id}`);
+ if(platform==='macos') assert(geometry.text.includes(language==='zh'?'查看保留的恢复材料与说明':'Inspect preserved recovery material and guide'),`Recovery directory action missing: ${id}`);
+ }else assert(!located,`Unverified recovery location exposed: ${id}`);
+ if (platform === 'windows') assert(geometry.retry === ['retry_current', 'resume_current'].includes(fixture.action), `Unsafe or missing retry: ${id}`);
+ const screenshot = `${id}.png`;
+ const shot = await client.send('Page.captureScreenshot', { format: 'png', captureBeyondViewport: false });
+ await writeFile(path.join(output, screenshot), Buffer.from(shot.data, 'base64'));
+ results.push({ id, state: 'green', screenshot, geometry });
+ } catch (error) {
+ await writeFile(path.join(output, id + '.failure.json'), JSON.stringify({error:String(error),page:await evaluate(client, '({url:location.href,state:document.readyState,text:document.body.innerText,resources:performance.getEntriesByType("resource").map(r=>({name:r.name,status:r.responseStatus,duration:r.duration}))})')},null,2));
+ throw error;
+ } finally {
+ if (script) await client.send('Page.removeScriptToEvaluateOnNewDocument', { identifier: script.identifier });
+ }
+ }
+ await writeFile(path.join(output, 'storage-recovery-report.json'), JSON.stringify({ evidence: 'Production Desktop and Windows bundled HTML/styles with synthetic startup replies. Native recovery remains separate.', results }, null, 2) + '\n');
+ process.stdout.write(`green: ${results.length} storage recovery presentation states\n`);
+}
diff --git a/apps/shell/README.md b/apps/shell/README.md
index ddd6ce3d..a16e10af 100644
--- a/apps/shell/README.md
+++ b/apps/shell/README.md
@@ -12,6 +12,9 @@ authentication, confirmations and operations stay in `hirouted` and
explicit owner configuration/restart steps without changing saved scope.
- `mod` / `commands`: private WebView, single instance, navigation lock and
explicit host commands, each checked against the exact active console origin.
+- `startup_failure`: the completed readiness wait projects the latest typed
+ daemon failure through the shared host mapping. Installer, manager-command and
+ console failures never load an older storage recovery report.
- `tray` / platform `shell_login`: window visibility and current-user login start;
quitting the shell leaves the Task running.
- `installer`: NSIS's fixed adapter to the native Rust installation transaction.
diff --git a/apps/shell/index.html b/apps/shell/index.html
index 7c044278..538b888b 100644
--- a/apps/shell/index.html
+++ b/apps/shell/index.html
@@ -1,4 +1,4 @@
<!doctype html>
<html><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>HiRoute</title></head>
-<body><div id="root" class="hr-ui occami-root"><main class="shell-status"><section class="surface"><h1>HiRoute</h1><h2 id="phase"></h2><p id="explanation" role="status"></p><p id="failure" role="alert"></p><div id="console-recovery" hidden><p id="recovery-explanation"></p><pre>hiroute console init --mode loopback
+<body><div id="root" class="hr-ui occami-root"><main class="shell-status"><section class="surface"><h1>HiRoute</h1><h2 id="phase"></h2><p id="explanation" role="status"></p><p id="failure" role="alert"></p><div id="recovery-material" hidden><p><strong id="batch-label"></strong><code id="batch"></code></p><p><strong id="source-label"></strong><code id="source"></code></p><p id="guide-location"></p></div><div id="console-recovery" hidden><p id="recovery-explanation"></p><pre>hiroute console init --mode loopback
hiroute service restart</pre><p id="recovery-warning"></p></div><label id="logs-label" for="logs"></label><input id="logs" class="input" readonly><div class="actions"><button id="retry" class="btn btn-primary" hidden></button><button id="language" class="btn"></button><button id="theme" class="btn"></button></div></section></main></div><script type="module" src="./src/main.ts"></script></body></html>
diff --git a/apps/shell/src-tauri/Cargo.toml b/apps/shell/src-tauri/Cargo.toml
index 2e65ae7e..3657342b 100644
--- a/apps/shell/src-tauri/Cargo.toml
+++ b/apps/shell/src-tauri/Cargo.toml
@@ -30,6 +30,10 @@ tauri-plugin-dialog = { version = "=2.7.3", default-features = false, optional =
[build-dependencies]
tauri-build = { version = "=2.6.3", optional = true }
+[dev-dependencies]
+hiroute-diagnostics = { path = "../../../crates/diagnostics" }
+tempfile.workspace = true
+
[[bin]]
name = "hiroute-shell"
path = "src/main.rs"
diff --git a/apps/shell/src-tauri/installer/README.md b/apps/shell/src-tauri/installer/README.md
index 09328667..25b7ca32 100644
--- a/apps/shell/src-tauri/installer/README.md
+++ b/apps/shell/src-tauri/installer/README.md
@@ -14,3 +14,17 @@ Recovery/uninstall use an exact shell copy in the private NSIS plugin directory.
Unavailable Agent state has a separate default-No confirmation; silent/passive
runs refuse it and exceptional removal always keeps business data. Package cleanup
waits for both transaction owners to commit and preserves rollback sources.
+
+The preinstall helper also receives the manifest-bound candidate daemon extracted
+into the private plugin directory. It checks storage prerequisites before overlay.
+Only a preflight requiring format-changing history cutover retains the complete
+previous Desktop/native installation and fixed HKCU registration; ordinary current
+repair avoids this archival work. It accounts for simultaneous allocations on their actual native volumes. The
+interactive history notice precedes replacement; silent/passive callers receive
+the corresponding notice through installation help or the originating Updates UI.
+The generated whole-group guide uses the installation owner's file map and actual
+Task/login choices, including separate choices, rather than reconstructing paths.
+
+The first supported Windows release has no supported published predecessor.
+Generic complete recovery remains; development historical compatibility promises
+and exhaustive development upgrade matrices are outside this change.
diff --git a/apps/shell/src-tauri/installer/hooks.nsh b/apps/shell/src-tauri/installer/hooks.nsh
index 94de54a8..007e30b9 100644
--- a/apps/shell/src-tauri/installer/hooks.nsh
+++ b/apps/shell/src-tauri/installer/hooks.nsh
@@ -23,6 +23,18 @@ FunctionEnd
!insertmacro HiRouteRestoreConfirmation ""
!insertmacro HiRouteRestoreConfirmation "un."
+Function HiRouteHistoryNotice
+ ${IfThen} $PassiveMode = 1 ${|} Abort ${|}
+ IfSilent 0 +2
+ Abort
+ !insertmacro MUI_HEADER_TEXT "Upgrade and history / 升级与历史" "Keep the complete recovery material / 请保留完整恢复材料"
+ nsDialogs::Create 1018
+ Pop $0
+ ${NSD_CreateLabel} 0 0 100% 100% "When upgrading old HiRoute storage, configuration, credentials and routing continue. Old HiRoute observations are sealed with the matching old program; current history and statistics begin at cutover. Old-period continuation/history references require complete-group recovery with the old program. Native Agent history is unchanged. Service restarts can interrupt availability. Keep all sealed history and recovery packages.$\r$\n$\r$\n升级旧存储时,配置、凭据和路由会保留。旧 HiRoute 历史与配套旧程序一起封存,新历史与统计从切换时开始;旧时期的继续会话与历史引用需要整组恢复到配套旧版本。原生 Agent 历史不变。服务重启会短暂影响使用,请保留全部封存历史与恢复包。"
+ Pop $0
+ nsDialogs::Show
+FunctionEnd
+
Function HiRouteOptions
${IfThen} $PassiveMode = 1 ${|} Abort ${|}
IfSilent 0 +2
@@ -52,11 +64,11 @@ FunctionEnd
StrCmp $INSTDIR "$LOCALAPPDATA\Programs\HiRoute" +3
MessageBox MB_ICONSTOP "HiRoute install directory is invalid. No product files were written." /SD IDOK
Abort
- nsExec::ExecToStack '"$PLUGINSDIR\hiroute-preflight.exe" --installer-prepare "$PLUGINSDIR\hiroute-package.json"'
+ nsExec::ExecToStack '"$PLUGINSDIR\hiroute-preflight.exe" --installer-prepare "$PLUGINSDIR\hiroute-package.json" "$PLUGINSDIR\hirouted-preflight.exe"'
Pop $0
Pop $1
${If} $0 != 0
- MessageBox MB_ICONSTOP "HiRoute could not prepare a verified backup. Existing data is preserved." /SD IDOK
+ MessageBox MB_ICONSTOP "HiRoute could not prepare the upgrade. Installed programs were not replaced and existing data is preserved. $1" /SD IDOK
Abort
${EndIf}
StrCpy $HiRoutePrepared 1
diff --git a/apps/shell/src-tauri/installer/installer.nsi b/apps/shell/src-tauri/installer/installer.nsi
index 71cda8d6..f3a61a24 100644
--- a/apps/shell/src-tauri/installer/installer.nsi
+++ b/apps/shell/src-tauri/installer/installer.nsi
@@ -390,6 +390,7 @@ Function PageLeaveReinstall
FunctionEnd
; Fixed per-user program directory; never a standalone state directory.
+Page custom HiRouteHistoryNotice
Page custom HiRouteOptions HiRouteOptionsLeave
; 6. Start menu shortcut page
@@ -515,6 +516,10 @@ Function .onInit
File "/oname=$PLUGINSDIR\hiroute-package.json" "{{no-escape @key}}"
!else if "{{this.[1]}}" == "standalone/package-manifest.json"
File "/oname=$PLUGINSDIR\hiroute-package.json" "{{no-escape @key}}"
+ !else if "{{this.[1]}}" == "standalone\hirouted.exe"
+ File "/oname=$PLUGINSDIR\hirouted-preflight.exe" "{{no-escape @key}}"
+ !else if "{{this.[1]}}" == "standalone/hirouted.exe"
+ File "/oname=$PLUGINSDIR\hirouted-preflight.exe" "{{no-escape @key}}"
!endif
{{/each}}
nsExec::ExecToStack '"$PLUGINSDIR\hiroute-preflight.exe" --installer-preflight'
@@ -527,19 +532,19 @@ Function .onInit
${IfNot} ${Silent}
!insertmacro CheckIfAppIsRunning "${MAINBINARYNAME}.exe" "${PRODUCTNAME}"
${EndIf}
- nsExec::ExecToStack '"$PLUGINSDIR\hiroute-preflight.exe" --installer-recover'
+ nsExec::ExecToStack '"$PLUGINSDIR\hiroute-preflight.exe" --installer-recover "$PLUGINSDIR\hiroute-package.json" "$PLUGINSDIR\hirouted-preflight.exe"'
Pop $0
Pop $1
${If} $0 = 23
Call HiRouteConfirmUnavailableRestore
${If} $HiRouteRestoreConsent = 1
- nsExec::ExecToStack '"$PLUGINSDIR\hiroute-preflight.exe" --installer-recover --allow-unavailable-agent-restore'
+ nsExec::ExecToStack '"$PLUGINSDIR\hiroute-preflight.exe" --installer-recover "$PLUGINSDIR\hiroute-package.json" "$PLUGINSDIR\hirouted-preflight.exe" --allow-unavailable-agent-restore'
Pop $0
Pop $1
${EndIf}
${EndIf}
${If} $0 != 0
- MessageBox MB_ICONSTOP "HiRoute needs installation recovery. Existing data and changed files are preserved." /SD IDOK
+ MessageBox MB_ICONSTOP "HiRoute needs installation recovery. Existing data and changed files are preserved. $1" /SD IDOK
Abort
${EndIf}
${If} ${Silent}
@@ -854,6 +859,9 @@ Function .onInstFailed
${EndIf}
${EndIf}
hiroute_rollback_registration_done:
+ ${If} $0 != 0
+ MessageBox MB_ICONSTOP "HiRoute could not safely restore the previous installation. Existing programs and data are preserved. $1" /SD IDOK
+ ${EndIf}
SetErrorLevel 1
FunctionEnd
diff --git a/apps/shell/src-tauri/src/lib.rs b/apps/shell/src-tauri/src/lib.rs
index e47552ed..4e120711 100644
--- a/apps/shell/src-tauri/src/lib.rs
+++ b/apps/shell/src-tauri/src/lib.rs
@@ -2,6 +2,9 @@
use url::Url;
#[cfg(any(test, all(windows, feature = "shell-runtime")))]
mod handoff;
+#[cfg(any(test, all(windows, feature = "shell-runtime")))]
+#[path = "runtime/startup_failure.rs"]
+mod startup_failure;
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ConsoleOrigin(String);
diff --git a/apps/shell/src-tauri/src/runtime/install_transaction.rs b/apps/shell/src-tauri/src/runtime/install_transaction.rs
index c027e00a..98cb5d1b 100644
--- a/apps/shell/src-tauri/src/runtime/install_transaction.rs
+++ b/apps/shell/src-tauri/src/runtime/install_transaction.rs
@@ -11,6 +11,8 @@ use std::{
path::{Path, PathBuf},
};
+mod recovery;
+
const INVENTORY: &str = "shell-package.json";
const PENDING: &str = "install-pending.json";
#[derive(Serialize, Deserialize)]
@@ -172,14 +174,83 @@ pub(super) fn validate_installed() -> io::Result<()> {
}
Ok(())
}
-pub(super) fn prepare(manifest: &Path) -> io::Result<()> {
+fn same_repair_payload(
+ pending: &BTreeMap<String, String>,
+ requested: &BTreeMap<String, String>,
+) -> bool {
+ !requested.is_empty()
+ && requested
+ .iter()
+ .all(|(name, hash)| pending.get(name) == Some(hash))
+ && pending.keys().all(|name| {
+ requested.contains_key(name)
+ || matches!(
+ name.as_str(),
+ "uninstall.exe" | "shell-install.json" | INVENTORY
+ )
+ })
+}
+pub(super) fn recover_for_candidate(manifest: &Path, daemon: &Path, allow: bool) -> io::Result<()> {
+ let layout =
+ hiroute_host_runtime::StandaloneLayout::from_environment().map_err(|_| invalid())?;
+ if has_pending()?
+ && pending()?.phase == Phase::Prepared
+ && hiroute_host_runtime::storage_upgrade_started(&layout.storage_root())?
+ {
+ return prepare(manifest, daemon);
+ }
+ windows::recover_pending()?;
+ rollback(allow)
+}
+pub(super) fn prepare(manifest: &Path, daemon: &Path) -> io::Result<()> {
windows::preflight()?;
let package: Package = read(manifest, false)?;
package.validate()?;
if package.target != "x86_64-pc-windows-msvc" {
return Err(invalid());
}
+ let daemon_digest = &package
+ .files
+ .get("bin/hirouted.exe")
+ .ok_or_else(invalid)?
+ .sha256;
+ if hash(daemon)? != *daemon_digest {
+ return Err(invalid());
+ }
if has_pending()? {
+ let layout =
+ hiroute_host_runtime::StandaloneLayout::from_environment().map_err(|_| invalid())?;
+ if hiroute_host_runtime::storage_upgrade_started(&layout.storage_root())? {
+ let value = pending()?;
+ let mut requested: BTreeMap<String, String> = package
+ .files
+ .iter()
+ .map(|(name, item)| {
+ (
+ format!("standalone/{}", Package::relative(name)),
+ item.sha256.clone(),
+ )
+ })
+ .collect();
+ requested.insert("standalone/package-manifest.json".into(), hash(manifest)?);
+ requested.insert("hiroute-shell.exe".into(), hash(&std::env::current_exe()?)?);
+ if value.phase != Phase::Prepared || !same_repair_payload(&value.new, &requested) {
+ return Err(invalid());
+ }
+ // Re-running the exact current installer continues its existing
+ // journal forward. Never replace its retained original rollback set.
+ for name in value.old.keys().chain(value.new.keys()) {
+ let path = root()?.join(name);
+ if present(&path)? {
+ let actual = hash(&path)?;
+ if value.old.get(name) != Some(&actual) && value.new.get(name) != Some(&actual)
+ {
+ return Err(invalid());
+ }
+ }
+ }
+ return Ok(());
+ }
rollback(false)?;
}
let root = root()?;
@@ -259,20 +330,19 @@ pub(super) fn prepare(manifest: &Path) -> io::Result<()> {
for (name, expected) in &old {
backup_file(&root.join(name), &backups.join(name), expected)?;
}
- write(
- &data.join(PENDING),
- &Pending {
- schema: "hiroute.windows-shell-transaction/v1".into(),
- phase: Phase::Prepared,
- old,
- new,
- service_active,
- previous_package,
- previous_autostart,
- console_desired,
- shell_login,
- },
- )
+ let value = Pending {
+ schema: "hiroute.windows-shell-transaction/v1".into(),
+ phase: Phase::Prepared,
+ old,
+ new,
+ service_active,
+ previous_package,
+ previous_autostart,
+ console_desired,
+ shell_login,
+ };
+ recovery::prepare(&value, &package, daemon)?;
+ write(&data.join(PENDING), &value)
}
/// NSIS overlays files, so old content-hashed assets must leave the package's
/// closed file set before the Rust package reader admits the new payload.
@@ -350,6 +420,12 @@ pub(super) fn commit() -> io::Result<()> {
record_generated()?;
let mut value = pending()?;
let root = root()?;
+ let actual_inventory = if present(&root.join(INVENTORY))? {
+ Some(hash(&root.join(INVENTORY))?)
+ } else {
+ None
+ };
+ prepare_inventory(&value.old, &mut value.new, actual_inventory.as_deref())?;
for (name, expected) in &value.new {
if hash(&root.join(name))? != *expected {
return Err(invalid());
@@ -381,6 +457,24 @@ pub(super) fn commit() -> io::Result<()> {
Ok(())
}
+fn prepare_inventory(
+ old: &BTreeMap<String, String>,
+ new: &mut BTreeMap<String, String>,
+ actual: Option<&str>,
+) -> io::Result<()> {
+ if actual.is_some_and(|hash| {
+ old.get(INVENTORY).map(String::as_str) != Some(hash)
+ && new.get(INVENTORY).map(String::as_str) != Some(hash)
+ }) {
+ return Err(invalid());
+ }
+ // A failed publication can leave this generated digest in the prepared
+ // journal while the old inventory is still present. It is metadata about
+ // the inventory, never a member of that inventory's own closed file set.
+ new.remove(INVENTORY);
+ Ok(())
+}
+
fn complete_commit(data: &Path, old: &BTreeMap<String, String>) -> io::Result<()> {
// A manual install has no update finisher to replace an earlier failure. Keep
// the committed journal until reporting succeeds so recovery can repeat it.
@@ -415,6 +509,11 @@ pub(super) fn rollback(allow_unavailable_agent_restore: bool) -> io::Result<()>
cleanup_committed();
return Ok(());
}
+ let layout =
+ hiroute_host_runtime::StandaloneLayout::from_environment().map_err(|_| invalid())?;
+ if hiroute_host_runtime::storage_upgrade_started(&layout.storage_root())? {
+ return Err(io::Error::other("STORAGE_UPGRADE_RECOVERY_REQUIRED"));
+ }
windows::recover_pending()?;
// Validate the complete replacement set before restoring the first file.
for name in value.old.keys().chain(value.new.keys()) {
@@ -523,9 +622,10 @@ pub(super) fn rollback(allow_unavailable_agent_restore: bool) -> io::Result<()>
super::service::manager(&["service", "start", "--output", "json"])
.map_err(|_| invalid())?;
}
+ let service_available = value.service_active && super::service::available_blocking();
write(
&data()?.join("update-outcome.json"),
- &serde_json::json!({"schema":"hiroute.windows-shell-update-outcome/v1","status":"failed","code":"UPGRADE_INSTALL_FAILED","service_available":value.service_active}),
+ &serde_json::json!({"schema":"hiroute.windows-shell-update-outcome/v1","status":"failed","code":"UPGRADE_INSTALL_FAILED","service_available":service_available}),
)?;
clear(&data()?, &value.old)?;
cleanup_committed();
@@ -563,6 +663,52 @@ mod tests {
}
}
+ #[test]
+ fn forward_storage_repair_requires_the_exact_prepared_payload() {
+ let pending = BTreeMap::from([
+ ("hiroute-shell.exe".into(), "shell-new".into()),
+ ("standalone/hirouted.exe".into(), "daemon-new".into()),
+ ("uninstall.exe".into(), "generated".into()),
+ ]);
+ let mut request = pending.clone();
+ request.remove("uninstall.exe");
+ assert!(same_repair_payload(&pending, &request));
+ request.insert("standalone/hirouted.exe".into(), "daemon-old".into());
+ assert!(!same_repair_payload(&pending, &request));
+ assert!(!same_repair_payload(&pending, &BTreeMap::new()));
+ }
+
+ #[test]
+ fn retrying_inventory_publication_accepts_only_old_or_admitted_new_metadata_without_self_hashing()
+ {
+ let old = BTreeMap::from([(INVENTORY.into(), "a".repeat(64))]);
+ let payload = BTreeMap::from([("hiroute-shell.exe".into(), "b".repeat(64))]);
+ let bytes = serde_json::to_vec(&Inventory {
+ schema: "hiroute.windows-shell-package/v1".into(),
+ files: payload.clone(),
+ })
+ .unwrap();
+ let published = format!("{:x}", Sha256::digest(&bytes));
+ for actual in [old[INVENTORY].as_str(), published.as_str()] {
+ let mut new = payload.clone();
+ new.insert(INVENTORY.into(), published.clone());
+ prepare_inventory(&old, &mut new, Some(actual)).unwrap();
+ assert_eq!(new, payload);
+ assert_eq!(
+ serde_json::to_vec(&Inventory {
+ schema: "hiroute.windows-shell-package/v1".into(),
+ files: new
+ })
+ .unwrap(),
+ bytes
+ );
+ }
+ let mut changed = payload.clone();
+ changed.insert(INVENTORY.into(), published);
+ let before = changed.clone();
+ assert!(prepare_inventory(&old, &mut changed, Some(&"c".repeat(64))).is_err());
+ assert_eq!(changed, before);
+ }
#[test]
fn committed_manual_repair_replaces_stale_failure_before_retiring_journal() {
let temporary = PayloadDirectory::new();
diff --git a/apps/shell/src-tauri/src/runtime/install_transaction/recovery.rs b/apps/shell/src-tauri/src/runtime/install_transaction/recovery.rs
new file mode 100644
index 00000000..ca3d32cb
--- /dev/null
+++ b/apps/shell/src-tauri/src/runtime/install_transaction/recovery.rs
@@ -0,0 +1,195 @@
+//! Preserve the complete Desktop, standalone payload and native registration before NSIS overlays it.
+use super::*;
+use hiroute_host_runtime::WindowsDesktopRestore;
+use hiroute_host_runtime::{
+ RetainedRecoveryPackage, StandaloneLayout, read_standalone_install_record,
+};
+
+pub(super) fn prepare(value: &Pending, incoming: &Package, daemon: &Path) -> io::Result<()> {
+ let layout = StandaloneLayout::from_environment().map_err(|_| invalid())?;
+ let Some(previous) = &value.previous_package else {
+ // An uninstalled old data group still needs its matching package. The
+ // candidate explains that refusal before any installed file is replaced.
+ let report = hiroute_host_runtime::checked_upgrade_preflight(
+ daemon,
+ &layout.storage_root(),
+ &data()?.join("missing-original-package"),
+ )
+ .map_err(io::Error::other)?;
+ return windows::preflight_desktop_space(
+ incoming,
+ &data()?,
+ fs::metadata(std::env::current_exe()?)?.len(),
+ 0,
+ Some(&report),
+ );
+ };
+ // Ordinary install/repair must not export historical Task/Apps state or
+ // duplicate the complete Desktop. Those are recovery inputs only when the
+ // actual candidate reports an admitted format-changing history cutover.
+ let report =
+ hiroute_host_runtime::checked_upgrade_preflight(daemon, &layout.storage_root(), previous)
+ .map_err(io::Error::other)?;
+ windows::preflight_desktop_space(
+ incoming,
+ &data()?,
+ fs::metadata(std::env::current_exe()?)?.len(),
+ 0,
+ Some(&report),
+ )?;
+ if !report.history_cutover_required {
+ return Ok(());
+ }
+ let marker = read_standalone_install_record(&layout.marker_path).map_err(io::Error::other)?;
+ if marker.install_root != *previous {
+ return Err(invalid());
+ }
+ let package = Package::read(previous)?;
+ if !value.old.is_empty()
+ && ["hiroute-shell.exe", "uninstall.exe", INVENTORY]
+ .iter()
+ .any(|name| !value.old.contains_key(*name))
+ {
+ return Err(invalid());
+ }
+ let marker_bytes = serde_json::to_vec(&marker).map_err(|_| invalid())?;
+ let shell_bytes = fs::metadata(std::env::current_exe()?)?.len();
+ let mut copy_bytes: u64 = package.files.values().map(|file| file.size).sum();
+ for name in value.old.keys() {
+ copy_bytes = copy_bytes.saturating_add(fs::metadata(root()?.join(name))?.len());
+ }
+ windows::preflight_desktop_space(
+ incoming,
+ &data()?,
+ shell_bytes,
+ copy_bytes.saturating_add(1024 * 1024),
+ None,
+ )?;
+ let mut identity = Sha256::new();
+ identity.update(serde_json::to_vec(&value.old).map_err(|_| invalid())?);
+ identity.update(&marker_bytes);
+ identity.update(hash(&marker.service_definition)?);
+ identity.update([
+ u8::from(value.previous_autostart),
+ u8::from(value.shell_login),
+ ]);
+ let bundle = data()?
+ .join("recovery-packages")
+ .join(format!("{:x}", identity.finalize()));
+ security::ensure_private_directory(&bundle)?;
+ // Both installed namespaces are necessary: the shell includes its generated
+ // uninstaller/inventory, while the Task runs the independent version root.
+ for (name, expected) in &value.old {
+ backup_file(
+ &data()?.join("install-backups").join(name),
+ &bundle.join("desktop").join(name),
+ expected,
+ )?;
+ }
+ for (name, item) in &package.files {
+ let name = Package::relative(name);
+ backup_file(
+ &previous.join(name),
+ &bundle.join("program").join(name),
+ &item.sha256,
+ )?;
+ }
+ backup_file(
+ &previous.join("package-manifest.json"),
+ &bundle.join("program/package-manifest.json"),
+ &hash(&previous.join("package-manifest.json"))?,
+ )?;
+ let mut files = BTreeMap::new();
+ for (name, source) in [
+ ("standalone.json", layout.marker_path.clone()),
+ ("windows-background.json", marker.service_definition.clone()),
+ ] {
+ let relative = format!("installation/{name}");
+ backup_file(&source, &bundle.join(&relative), &hash(&source)?)?;
+ files.insert(relative, source);
+ }
+ for (source, relative, expected) in windows::recovery_files()? {
+ backup_file(&source, &bundle.join(&relative), &expected)?;
+ files.insert(relative, source);
+ }
+ let definition =
+ hiroute_platform::windows::background::read_definition(&marker.service_definition)?;
+ let task_xml = hiroute_platform::windows::task::recovery_xml(&definition).map_err(|error| {
+ if error.kind() == io::ErrorKind::PermissionDenied {
+ error
+ } else {
+ io::Error::other("UPGRADE_TASK_REGISTRATION_UNAVAILABLE")
+ }
+ })?;
+ let task_path = bundle.join("installation/task.xml");
+ if present(&task_path)? {
+ if hash(&task_path)? != format!("{:x}", Sha256::digest(&task_xml)) {
+ return Err(invalid());
+ }
+ } else {
+ hiroute_platform::durable::write_private_new(&task_path, &task_xml)?;
+ }
+ let registration = bundle.join("installation/uninstall.reg");
+ if !value.old.is_empty() {
+ hiroute_platform::windows::shell_registration::export(&registration).map_err(|error| {
+ if error.kind() == io::ErrorKind::PermissionDenied {
+ error
+ } else {
+ io::Error::other("UPGRADE_REGISTRATION_UNAVAILABLE")
+ }
+ })?;
+ }
+ let locations = WindowsDesktopRestore {
+ schema: "hiroute.windows-desktop-restore/v1".into(),
+ program: previous.clone(),
+ desktop: if value.old.is_empty() {
+ None
+ } else {
+ Some(root()?)
+ },
+ task_name: definition.name,
+ task_autostart: value.previous_autostart,
+ shell_login: value.shell_login,
+ files,
+ };
+ locations.validate()?;
+ let bytes = serde_json::to_vec(&locations).map_err(|_| invalid())?;
+ let path = bundle.join("restore-locations.json");
+ if present(&path)? {
+ if hash(&path)? != format!("{:x}", Sha256::digest(&bytes)) {
+ return Err(invalid());
+ }
+ } else {
+ hiroute_platform::durable::write_private_new(&path, &bytes)?;
+ }
+ Package::read(&bundle.join("program"))?;
+ let retained = RetainedRecoveryPackage::capture(&layout.storage_root(), &bundle, daemon)?;
+ let mut expected: std::collections::BTreeSet<String> = package
+ .files
+ .keys()
+ .map(|name| format!("program/{}", Package::relative(name)))
+ .collect();
+ expected.insert("program/package-manifest.json".into());
+ expected.insert("restore-locations.json".into());
+ expected.insert("installation/task.xml".into());
+ expected.extend(value.old.keys().map(|name| format!("desktop/{name}")));
+ expected.extend(locations.files.keys().cloned());
+ if !value.old.is_empty() {
+ expected.insert("installation/uninstall.reg".into());
+ }
+ if retained
+ .files
+ .keys()
+ .cloned()
+ .collect::<std::collections::BTreeSet<_>>()
+ != expected
+ {
+ return Err(invalid());
+ }
+ retained.verify(daemon)?;
+ let report =
+ hiroute_host_runtime::checked_upgrade_preflight(daemon, &layout.storage_root(), &bundle)
+ .map_err(io::Error::other)?;
+ windows::preflight_desktop_space(incoming, &data()?, shell_bytes, 0, Some(&report))?;
+ retained.store()
+}
diff --git a/apps/shell/src-tauri/src/runtime/installer.rs b/apps/shell/src-tauri/src/runtime/installer.rs
index ac13ac7e..5d15902c 100644
--- a/apps/shell/src-tauri/src/runtime/installer.rs
+++ b/apps/shell/src-tauri/src/runtime/installer.rs
@@ -96,6 +96,35 @@ fn preflight() -> Result<(), String> {
}
Ok(())
}
+fn prepare_failure(error: &std::io::Error) -> String {
+ if error.to_string() == "UPGRADE_REGISTRATION_UNAVAILABLE" {
+ return "UPGRADE_REGISTRATION_UNAVAILABLE: The installed Windows Apps registration could not be retained or no longer matches the retained copy. No installed program was replaced. Keep the installed version, all data and recovery material. Repair the known installation with its matching complete installer under the same account; if ownership or the correct registration is unclear, preserve both copies and contact support. / 无法保留已安装程序的 Windows 应用注册,或其内容与保留副本不符。本次尚未替换已安装程序。请保留当前版本、全部数据与恢复材料;使用配套完整安装器在同一账户修复已知安装,无法确认归属或正确注册时请保留两份材料并联系支持。".into();
+ }
+ if error.to_string() == "UPGRADE_TASK_REGISTRATION_UNAVAILABLE" {
+ return "UPGRADE_TASK_REGISTRATION_UNAVAILABLE: The previous HiRoute Task could not be verified or retained. No installed program was replaced. Keep all data and the exact previous installer. If its Task is missing, repair it with that matching installer under the same account; if ownership is unclear, preserve the registration and contact support. / 无法验证或保留旧版 HiRoute 任务,本次尚未替换已安装程序。请保留全部数据与配套旧安装器;若原任务缺失,用该安装器在同一账户修复,无法确认任务归属时保留注册并联系支持。".into();
+ }
+ if let Some(failure) = error
+ .get_ref()
+ .and_then(|error| error.downcast_ref::<hiroute_host_runtime::UpgradePreflightFailure>())
+ {
+ return failure.to_string();
+ }
+ if let Some(failure) = error
+ .get_ref()
+ .and_then(|error| error.downcast_ref::<windows::ReplacementSpaceFailure>())
+ {
+ return failure.to_string();
+ }
+ match error.kind() {
+ std::io::ErrorKind::PermissionDenied => "UPGRADE_ACCESS_DENIED: Close the owning HiRoute instance and check access to this account's installation/recovery folders. Preserve data; do not apply blanket permission changes. / 请关闭占用该安装的 HiRoute 实例并检查本账户安装与恢复目录的访问权限,保留数据,不要批量修改权限。",
+ std::io::ErrorKind::StorageFull => "UPGRADE_INSUFFICIENT_SPACE: The program/recovery volume ran out of space. Keep history and recovery packages; free unrelated files before retrying. / 程序与恢复材料所在磁盘空间不足,请保留历史与恢复包,释放无关文件后再试。",
+ std::io::ErrorKind::WouldBlock => "UPGRADE_FILES_IN_USE: Close the owning HiRoute instance before retrying. No installed program was replaced by this preparation. / 请关闭占用该安装的 HiRoute 实例后再试,本次准备尚未替换已安装的程序。",
+ _ => "INSTALL_PREPARATION_FAILED: Installation preparation could not be verified. Keep all data, programs, installation journals and diagnostics. Close owned instances and check file access and free space, then retry the same complete current installer. If it still fails, preserve the material and contact support; do not delete data or try an arbitrary older installer. / 无法验证安装准备状态。请保留全部数据、程序、安装记录和诊断;关闭占用实例,检查文件访问与空间,再运行同一当前版完整安装器。仍失败时保留现场并联系支持,不要删除数据或尝试任意旧安装器。",
+ }.into()
+}
+fn interrupted_installation_hint() -> &'static str {
+ "INSTALL_CURRENT_REPAIR_REQUIRED: Keep all data, complete installer/program files and installation journals. Close files in use; check access and free space. Rerun the same complete current installer. Do not install an older version over these data. If it still fails, preserve all material and contact support. Verify actual service/Gateway readiness afterward. / 请保留全部数据、完整安装器/程序及安装记录。解除文件占用,检查访问权限和空间,再运行同一当前版完整安装器,不要用旧版覆盖这组数据;仍失败时保留全部材料并联系支持,之后核对服务和 Gateway 实际就绪。"
+}
fn request(cli: &std::path::Path, verb: &str, value: Value) -> Result<Value, String> {
let bytes = serde_json::to_vec(&value).map_err(|_| "INSTALL_REQUEST_INVALID")?;
let (success, value) = service::execute_reply(
@@ -236,30 +265,55 @@ pub fn run_if_requested() -> Option<i32> {
);
}
if verb == "--installer-prepare" {
- let result = if args.len() == 2 {
- super::install_transaction::prepare(std::path::Path::new(&args[1]))
+ let result = if args.len() == 3 {
+ super::install_transaction::prepare(
+ std::path::Path::new(&args[1]),
+ std::path::Path::new(&args[2]),
+ )
} else {
Err(std::io::ErrorKind::InvalidInput.into())
};
- return Some(if result.is_ok() { 0 } else { 1 });
+ return Some(match result {
+ Ok(()) => 0,
+ Err(error) => {
+ eprintln!("{}", prepare_failure(&error));
+ 1
+ }
+ });
}
if matches!(
verb.as_str(),
"--installer-rollback" | "--installer-recover"
) {
let allow = args
- .get(1)
+ .last()
.is_some_and(|arg| arg == "--allow-unavailable-agent-restore");
- if args.len() > 2 || (args.len() == 2 && !allow) {
+ let candidate =
+ verb == "--installer-recover" && (args.len() == 3 || args.len() == 4 && allow);
+ if !candidate && (args.len() > 2 || (args.len() == 2 && !allow)) {
return Some(1);
}
- let result =
- windows::recover_pending().and_then(|()| super::install_transaction::rollback(allow));
+ let result = if candidate {
+ super::install_transaction::recover_for_candidate(
+ std::path::Path::new(&args[1]),
+ std::path::Path::new(&args[2]),
+ allow,
+ )
+ } else {
+ windows::recover_pending().and_then(|()| super::install_transaction::rollback(allow))
+ };
let _ = super::updater::resume_admission();
return Some(match result {
Ok(()) => 0,
Err(error) if error.to_string() == "AGENT_CONTROL_UNAVAILABLE" => 23,
- Err(_) => 1,
+ Err(_) => {
+ let _ = writeln!(
+ std::io::stdout().lock(),
+ "{}",
+ interrupted_installation_hint()
+ );
+ 1
+ }
});
}
let result = if args.iter().skip(1).any(|a| {
@@ -297,7 +351,7 @@ pub fn run_if_requested() -> Option<i32> {
} else {
1
},
- error,
+ format!("{error}\n{}", interrupted_installation_hint()),
),
};
let _ = writeln!(std::io::stdout().lock(), "{text}");
diff --git a/apps/shell/src-tauri/src/runtime/mod.rs b/apps/shell/src-tauri/src/runtime/mod.rs
index bd9646df..49ac0370 100644
--- a/apps/shell/src-tauri/src/runtime/mod.rs
+++ b/apps/shell/src-tauri/src/runtime/mod.rs
@@ -1,4 +1,4 @@
-use crate::ConsoleOrigin;
+use crate::{ConsoleOrigin, startup_failure};
use serde::Serialize;
use std::sync::{
Arc, Mutex,
@@ -18,6 +18,7 @@ pub struct Status {
phase: &'static str,
code: Option<&'static str>,
logs_path: String,
+ storage_recovery: Option<hiroute_host_runtime::StorageRecovery>,
}
pub struct ShellState {
origin: Mutex<Option<ConsoleOrigin>>,
@@ -37,6 +38,7 @@ impl ShellState {
phase: "starting",
code: None,
logs_path: logs,
+ storage_recovery: None,
}),
starting: AtomicBool::new(false),
updater: updater::Updater::new(),
@@ -46,6 +48,14 @@ impl ShellState {
if let Ok(mut status) = self.status.lock() {
status.phase = phase;
status.code = code;
+ status.storage_recovery = None;
+ }
+ }
+ fn failed(&self, failure: startup_failure::Failure) {
+ if let Ok(mut status) = self.status.lock() {
+ status.phase = "failed";
+ status.code = Some(failure.code);
+ status.storage_recovery = failure.recovery;
}
}
}
@@ -72,11 +82,11 @@ fn start(app: tauri::AppHandle, state: Arc<ShellState>) {
.navigate(url)
.map_err(|_| "SHELL_NAVIGATION_FAILED")?;
state.phase("ready", None);
- Ok::<_, &'static str>(())
+ Ok::<_, startup_failure::Failure>(())
}
.await;
- if let Err(code) = outcome {
- state.phase("failed", Some(code));
+ if let Err(failure) = outcome {
+ state.failed(failure);
focus(&app);
}
state.starting.store(false, Ordering::Release);
diff --git a/apps/shell/src-tauri/src/runtime/service.rs b/apps/shell/src-tauri/src/runtime/service.rs
index e57d0908..ea4bf865 100644
--- a/apps/shell/src-tauri/src/runtime/service.rs
+++ b/apps/shell/src-tauri/src/runtime/service.rs
@@ -1,4 +1,4 @@
-use super::ShellState;
+use super::{ShellState, startup_failure};
use crate::ConsoleOrigin;
use hiroute_application_api::{
ConsoleLaunchRequestV1, ConsoleLaunchV1, ErrorCode, MachineEnvelopeV2, SystemStatusV1,
@@ -94,10 +94,7 @@ pub(super) fn execute(
timeout: Duration,
) -> Result<Value, &'static str> {
let (success, value) = execute_reply(cli, args, stdin, timeout)?;
- if !success || value.get("status").is_some_and(|s| s != "succeeded") {
- return Err("SERVICE_COMMAND_FAILED");
- }
- Ok(value.get("data").cloned().unwrap_or(value))
+ startup_failure::command_result(success, value)
}
pub(super) fn manager(args: &[&str]) -> Result<Value, &'static str> {
execute(&cli()?, args, None, Duration::from_secs(45))
@@ -138,20 +135,24 @@ fn launch_reply(
}
pub(super) async fn ready_launch(
state: &ShellState,
-) -> Result<(ConsoleOrigin, url::Url), &'static str> {
+) -> Result<(ConsoleOrigin, url::Url), startup_failure::Failure> {
let status = tauri::async_runtime::spawn_blocking(|| {
manager(&["service", "status", "--output", "json"])
})
.await
.map_err(|_| "SERVICE_STATUS_UNAVAILABLE")??;
+ let layout = StandaloneLayout::from_environment().map_err(|_| "INSTALLATION_UNAVAILABLE")?;
+ let attempt =
+ startup_failure::Attempt::begin(&layout.storage_root(), &layout.diagnostics_root());
if status["manager_active"] != true {
tauri::async_runtime::spawn_blocking(|| manager(&["service", "start", "--output", "json"]))
.await
- .map_err(|_| "SERVICE_START_FAILED")??;
+ .map_err(|_| "SERVICE_START_FAILED")?
+ .map_err(|code| attempt.failed(code))?;
}
state.phase("waiting", None);
- wait_ready().await?;
- launch().await
+ wait_ready().await.map_err(|code| attempt.failed(code))?;
+ launch().await.map_err(Into::into)
}
pub(super) async fn wait_ready() -> Result<(), &'static str> {
let deadline = Instant::now() + Duration::from_secs(45);
diff --git a/apps/shell/src-tauri/src/runtime/startup_failure.rs b/apps/shell/src-tauri/src/runtime/startup_failure.rs
new file mode 100644
index 00000000..05170382
--- /dev/null
+++ b/apps/shell/src-tauri/src/runtime/startup_failure.rs
@@ -0,0 +1,142 @@
+//! Manager failures may show only diagnostic facts observed during this startup.
+use hiroute_host_runtime::{StartupFailureBoundary, StorageRecovery};
+use serde_json::Value;
+use std::path::{Path, PathBuf};
+
+pub(super) struct Failure {
+ pub code: &'static str,
+ pub recovery: Option<StorageRecovery>,
+}
+impl From<&'static str> for Failure {
+ fn from(code: &'static str) -> Self {
+ Self {
+ code,
+ recovery: None,
+ }
+ }
+}
+
+pub(super) struct Attempt {
+ boundary: StartupFailureBoundary,
+ storage: PathBuf,
+ diagnostics: PathBuf,
+}
+impl Attempt {
+ pub fn begin(storage: &Path, diagnostics: &Path) -> Self {
+ Self {
+ boundary: StartupFailureBoundary::capture(diagnostics),
+ storage: storage.to_owned(),
+ diagnostics: diagnostics.to_owned(),
+ }
+ }
+ pub fn failed(&self, code: &'static str) -> Failure {
+ match self.boundary.read_failure(&self.storage, &self.diagnostics) {
+ Some((current, recovery)) => Failure {
+ code: current,
+ recovery,
+ },
+ None => code.into(),
+ }
+ }
+}
+
+pub(super) fn command_result(success: bool, value: Value) -> Result<Value, &'static str> {
+ if !success || value.get("status").is_some_and(|s| s != "succeeded") {
+ return Err("SERVICE_COMMAND_FAILED");
+ }
+ Ok(value.get("data").cloned().unwrap_or(value))
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use hiroute_diagnostics::{
+ Component, DiagnosticRuntime, RuntimeConfig,
+ event::{DiagnosticEvent, ProcessRole, StartupEnd, StartupFailureCode, StartupOutcome},
+ };
+ use hiroute_host_runtime::{StorageRecoveryAction as Action, StorageRecoveryCause as Cause};
+
+ fn write_failure(diagnostics: &Path, code: StartupFailureCode) {
+ let runtime = DiagnosticRuntime::start(RuntimeConfig {
+ root: diagnostics.to_owned(),
+ role: ProcessRole::Daemon,
+ component: Component::Daemon,
+ parent_session_id: None,
+ level_override: None,
+ });
+ runtime.emit(DiagnosticEvent::StartupEnd(StartupEnd {
+ outcome: StartupOutcome::Failure { code },
+ elapsed_ms: 1,
+ }));
+ runtime.shutdown();
+ }
+
+ #[test]
+ fn stopped_service_command_failure_keeps_this_attempts_typed_cause() {
+ for (code, expected, cause, action) in [
+ (
+ StartupFailureCode::StorageLocked,
+ "DAEMON_STORAGE_LOCKED",
+ Cause::Locked,
+ Action::RetryCurrent,
+ ),
+ (
+ StartupFailureCode::StorageKeyUnavailable,
+ "DAEMON_STORAGE_KEY_UNAVAILABLE",
+ Cause::MissingKey,
+ Action::PreserveAndDiagnose,
+ ),
+ (
+ StartupFailureCode::UpgradeStorageFailed,
+ "DAEMON_UPGRADE_STORAGE_FAILED",
+ Cause::MigrationFailed,
+ Action::PreserveAndDiagnose,
+ ),
+ ] {
+ let temp = tempfile::tempdir().unwrap();
+ let storage = temp.path().to_owned();
+ let diagnostics = temp.path().join("diagnostics");
+ let old = StorageRecovery::new(Cause::MissingPackage, Action::PreserveAndDiagnose);
+ old.store(&storage).unwrap();
+ write_failure(&diagnostics, StartupFailureCode::DependencyUnavailable);
+ let attempt = Attempt::begin(&storage, &diagnostics);
+ // CLI start waits for readiness and returns a failed envelope. This
+ // path never reaches the shell's separate wait_ready operation.
+ write_failure(&diagnostics, code);
+ if code == StartupFailureCode::UpgradeStorageFailed {
+ StorageRecovery::new(cause, action).store(&storage).unwrap();
+ }
+ let error = command_result(false, serde_json::json!({"status":"failed"})).unwrap_err();
+ let failure = attempt.failed(error);
+ assert_eq!(failure.code, expected);
+ let report = failure.recovery.unwrap();
+ assert_eq!(report.cause, cause);
+ assert_eq!(report.action, action);
+ if code != StartupFailureCode::UpgradeStorageFailed {
+ assert_eq!(StorageRecovery::read(&storage).unwrap(), Some(old));
+ }
+ }
+ }
+
+ #[test]
+ fn unchanged_diagnostics_and_unproven_attempts_cannot_borrow_old_advice() {
+ let temp = tempfile::tempdir().unwrap();
+ let diagnostics = temp.path().join("diagnostics");
+ write_failure(&diagnostics, StartupFailureCode::StorageKeyUnavailable);
+ let attempt = Attempt::begin(temp.path(), &diagnostics);
+ for code in [
+ "SERVICE_COMMAND_FAILED",
+ "SERVICE_COMMAND_TIMED_OUT",
+ "SERVICE_NOT_READY",
+ ] {
+ let failure = attempt.failed(code);
+ assert_eq!(failure.code, code);
+ assert!(failure.recovery.is_none());
+ }
+ let missing = temp.path().join("absent");
+ let attempt = Attempt::begin(&missing, &missing);
+ let failure = attempt.failed("SERVICE_COMMAND_FAILED");
+ assert_eq!(failure.code, "SERVICE_COMMAND_FAILED");
+ assert!(failure.recovery.is_none());
+ }
+}
diff --git a/apps/shell/src/main.ts b/apps/shell/src/main.ts
index 1999e865..a504fcdf 100644
--- a/apps/shell/src/main.ts
+++ b/apps/shell/src/main.ts
@@ -1,7 +1,8 @@
+import { storageRecoveryText, startupFailureText } from '../../desktop/src/storage-recovery';
import '../../desktop/src/occami/styles.css';
import './status.css';
declare global { interface Window { __TAURI_INTERNALS__: { invoke<T>(command: string): Promise<T> } } }
-type Report = { phase: 'starting' | 'waiting' | 'ready' | 'failed'; code: string | null; logs_path: string };
+type Report = { phase: 'starting' | 'waiting' | 'ready' | 'failed'; code: string | null; logs_path: string; storage_recovery?: unknown };
let language = navigator.language.startsWith('zh') ? 'zh' : 'en';
let dark = matchMedia('(prefers-color-scheme: dark)').matches;
let report: Report = { phase: 'starting', code: null, logs_path: '' };
@@ -9,17 +10,25 @@ const element = (id: string) => document.getElementById(id)!;
function render() {
const zh = language === 'zh'; const text = (cn: string, en: string) => zh ? cn : en;
const listenerUnavailable = report.phase === 'failed' && report.code === 'CONSOLE_LISTENER_UNAVAILABLE';
+ const repairInstaller = report.phase === 'failed' && report.code === 'SHELL_INSTALL_RECOVERY_REQUIRED' && !report.storage_recovery;
+ const recovery = startupFailureText(report.code, report.storage_recovery, language, 'windows');
document.documentElement.lang = zh ? 'zh-CN' : 'en';
element('root').dataset.theme = dark ? 'dark' : 'light';
- element('phase').textContent = listenerUnavailable ? text('本机控制台尚未就绪', 'The local console is unavailable') : report.phase === 'failed' ? text('无法启动本机服务', 'Could not start the local service') : text('正在连接 HiRoute 服务', 'Connecting to HiRoute');
- element('explanation').textContent = listenerUnavailable ? text('后台服务已就绪,但本机控制台未监听。控制台可能已被关闭,或指定端口被占用。', 'The background service is ready, but the local console is not listening. It may be disabled, or its configured port may be in use.') : report.phase === 'failed' ? text('请保留现有数据,在下方日志目录查看详情后重试。', 'Keep your existing data. Check the log directory below, then try again.') : report.phase === 'waiting' ? text('服务正在准备控制台与 Gateway…', 'Preparing the console and Gateway…') : text('正在检查并启动后台服务…', 'Checking and starting the background service…');
+ element('phase').textContent = repairInstaller ? text('安装尚未完成', 'Installation is incomplete') : listenerUnavailable ? text('本机控制台尚未就绪', 'The local console is unavailable') : report.phase === 'failed' ? text('无法启动本机服务', 'Could not start the local service') : text('正在连接 HiRoute 服务', 'Connecting to HiRoute');
+ element('explanation').textContent = listenerUnavailable ? text('后台服务已就绪,但本机控制台未监听。控制台可能已被关闭,或指定端口被占用。', 'The background service is ready, but the local console is not listening. It may be disabled, or its configured port may be in use.') : report.phase === 'failed' ? repairInstaller ? text('安装尚未完成。请保留全部数据、完整程序和安装记录,重新运行刚才相同版本及构建的完整安装程序,以继续修复当前版本。不要改装更旧版本;缺少原安装程序时请寻求支持。', 'Installation is incomplete. Keep all data, complete programs and installation journals. Re-run the same complete installer, with the same version and build, to finish repairing the current version. Do not install an older version; obtain support if the original installer is unavailable.') : recovery.reason + ' ' + recovery.instructions : report.phase === 'waiting' ? text('服务正在准备控制台与 Gateway…', 'Preparing the console and Gateway…') : text('正在检查并启动后台服务…', 'Checking and starting the background service…');
+ element('recovery-material').hidden = report.phase !== 'failed' || listenerUnavailable || !recovery.backupBatch;
+ element('batch-label').textContent = text('已校验的原批次:', 'Verified original batch: ');
+ element('batch').textContent = recovery.backupBatch ?? '';
+ element('source-label').textContent = text('恢复目录:', 'Recovery directory: ');
+ element('source').textContent = recovery.backupDirectory ?? '';
+ element('guide-location').textContent = recovery.locationHint ?? '';
element('console-recovery').hidden = !listenerUnavailable;
element('recovery-explanation').textContent = text('如需恢复本机界面,请在 PowerShell 中运行以下命令,使用自动选择的本机端口:', 'To restore the local interface, run these commands in PowerShell to use an automatically selected local port:');
element('recovery-warning').textContent = text('重启服务可能中断正在进行的调用和任务。完成后点击“重新检查”;此按钮只检查状态,不会修改监听设置。', 'Restarting the service may interrupt active calls and tasks. Then select Recheck; the button only checks status and does not change listener settings.');
element('failure').textContent = report.code ?? '';
element('logs-label').textContent = text('本机日志目录', 'Local log directory');
(element('logs') as HTMLInputElement).value = report.logs_path;
- element('retry').hidden = report.phase !== 'failed'; element('retry').textContent = listenerUnavailable ? text('重新检查', 'Recheck') : text('重试', 'Try again');
+ element('retry').hidden = report.phase !== 'failed' || repairInstaller || (!!report.storage_recovery && !storageRecoveryText(report.storage_recovery, language, 'windows').canRetry); element('retry').textContent = listenerUnavailable ? text('重新检查', 'Recheck') : text('重试', 'Try again');
element('language').textContent = zh ? 'English' : '中文'; element('theme').textContent = dark ? text('浅色', 'Light') : text('深色', 'Dark');
}
element('language').onclick = () => { language = language === 'zh' ? 'en' : 'zh'; render(); };
diff --git a/apps/shell/src/status.css b/apps/shell/src/status.css
index 8832b926..b6e4ddf7 100644
--- a/apps/shell/src/status.css
+++ b/apps/shell/src/status.css
@@ -6,3 +6,7 @@
.shell-status input { min-width: 0; width: 100%; }
.shell-status pre { white-space: pre-wrap; overflow-wrap: anywhere; margin: 12px 0; font-size: 13px; line-height: 1.7; }
.shell-status .actions { display: flex; gap: 8px; flex-wrap: wrap; }
+.shell-status [hidden] { display: none; }
+.shell-status code { white-space: normal; overflow-wrap: anywhere; user-select: text; }
+.shell-status #recovery-material { display: grid; gap: 8px; }
+.shell-status #recovery-material[hidden] { display: none; }
diff --git a/apps/website/content/guides/install-windows.en.md b/apps/website/content/guides/install-windows.en.md
index 57b1164d..0f403933 100644
--- a/apps/website/content/guides/install-windows.en.md
+++ b/apps/website/content/guides/install-windows.en.md
@@ -34,10 +34,16 @@ Open **Settings → Updates**. The shell downloads a newer stable installer from
A manually downloaded newer installer uses the same drain and transaction path. An older daemon that cannot drain requires an explicit interactive confirmation before it can be stopped; a passive update refuses it. If an update fails, the startup page or Updates shows the failure and recovery status. Keep the logs and retained backups. Starting the shell after an interrupted installer attempts journal recovery and resumes paused admission; changed or foreign files require repair and are preserved.
+This is the first supported Windows release. Generic complete-group recovery remains available when verified material is required; this does not promise compatibility with an unpublished development build. Development historical-upgrade matrices are outside this change. Current-format installation/repair does not export Task/Apps registration or duplicate the complete Desktop unnecessarily.
+
+Before a storage-format change, configuration, credentials and routing continue, while old HiRoute observations are sealed with the matching old program. Current history/statistics start at cutover; old-period continuation/history references require complete-group matching-version recovery. Native Agent history is unchanged. Read this notice before unattended `/S` installation too; silent mode has no notice page.
+
+If startup fails, use the bundled page's specific cause and next action. A missing key or unverified package cannot be repaired by repeated retries or an arbitrary older installer. For verified complete recovery, first preserve newer data and its matching program separately. Follow the exact batch's `RECOVERY.md` or Chinese guide and `PROGRAM-LOCATIONS.md`: restore the entire old data group, Desktop/uninstaller, standalone programs, command entries and native files, then the recorded current-user Apps registration and Task. Use the same ordinary account without elevation. Confirm Control/Gateway readiness, old configuration/routing/history and a real request before treating service as restored.
+
## Uninstall
Use **Installed apps → HiRoute → Uninstall**. Before removing the service, HiRoute restores its supported Agent configuration. If restoration needs a decision, uninstall stops and reports the Agent IDs; resolve them in HiRoute and retry. It removes only its recorded application files, Task, shell login entry and any CLI PATH entry it added. Data is retained unless you explicitly select its removal. The separate headless state directory is never used as the NSIS install directory.
If the service is unavailable, interactive recovery or uninstall offers a separate confirmation with **No** selected by default. Continuing may interrupt active work and leave configured Agents needing manual restoration; all HiRoute data is kept. Unattended mode refuses this exception, and a known restoration conflict still blocks removal. A failed first install with no Agent data can roll back without starting the service.
-After an upgrade commits, obsolete verified package files are removed. Uninstall removes the current verified package too; changed or foreign files are preserved.
+After an upgrade commits, obsolete verified package files may be removed. Material still required by storage recovery remains protected. Uninstall removes the current verified package too; changed or foreign files are preserved.
diff --git a/apps/website/content/guides/install-windows.zh.md b/apps/website/content/guides/install-windows.zh.md
index dfbd7807..fe8d886e 100644
--- a/apps/website/content/guides/install-windows.zh.md
+++ b/apps/website/content/guides/install-windows.zh.md
@@ -34,6 +34,12 @@ Get-FileHash -Algorithm SHA256 -LiteralPath "$env:USERPROFILE\Downloads\YOUR-INS
手动下载的新安装包使用同一套排空与事务流程。旧 daemon 不支持排空时,只有交互式安装经明确确认后才能停止它,静默更新会拒绝。失败后,启动页或升级页显示错误和恢复状态,请保留日志与备份。安装被中断后再次打开壳,会尝试 journal 恢复并恢复被暂停的接收入口;遇到变更或外来文件时保留现场并要求修复。
+本次是 Windows 首个受支持版本。通用完整数据组及配套程序/原生状态的恢复能力仍保留,但不承诺兼容未发布开发构建;开发旧版历史升级矩阵不属于本次必要验收。当前格式的安装修复不会无必要地导出 Task/应用注册或重复归档完整 Desktop。
+
+存储格式升级会保留配置、凭据和路由;旧 HiRoute 历史与配套旧程序一起封存,新历史和统计从切换时开始。旧时期的继续会话与历史引用需要整组恢复到配套旧版本,原生 Agent 历史不变。使用无人值守的 `/S` 安装前也应先了解这一变化;静默模式不会显示说明页。
+
+启动失败时,按照内置故障页的具体原因和下一步操作处理。缺失密钥或未经验证的旧包,不能靠重复重试或任意旧安装器修复。存在已验证的完整恢复源时,先将新版数据与配套新程序另存,再按正确批次的“恢复说明.md”和 `PROGRAM-LOCATIONS.md` 还原完整旧数据组、桌面外壳与卸载程序、独立服务包、命令入口和原生安装文件,最后还原本账户的应用注册与 Task。使用同一个普通账户,无需管理员权限。确认 Control/Gateway 实际就绪、原配置/路由/历史可用并完成真实请求后,才算恢复服务。
+
## 卸载
在“已安装的应用 → HiRoute → 卸载”中开始。移除服务前,HiRoute 会恢复受支持的 Agent 配置;需要人工决策时停止卸载并列出 Agent ID,先在 HiRoute 中处理后再试。卸载只删除已登记的安装文件、Task、壳登录项及它自行加入的 CLI PATH 条目。数据默认保留,只有明确勾选才删除。独立 headless 状态目录不会成为 NSIS 的安装目录。
diff --git a/contracts/compatibility-support.v1.json b/contracts/compatibility-support.v1.json
index 84956afc..7d3a3fb0 100644
--- a/contracts/compatibility-support.v1.json
+++ b/contracts/compatibility-support.v1.json
@@ -346,6 +346,7 @@
"hiroute.release-facts-cross-reference/v2",
"hiroute.release-facts/v2",
"hiroute.release-model-data/v2",
+ "hiroute.retained-recovery-package/v1",
"hiroute.routing-control/v1",
"hiroute.routing-control/v2",
"hiroute.routing-observations/v1",
@@ -361,6 +362,7 @@
"hiroute.secret-entry/v1",
"hiroute.secret-entry/v2",
"hiroute.semantic-ledger/v1",
+ "hiroute.service-recovery/v1",
"hiroute.session-detail/v1",
"hiroute.session-list-query/v1",
"hiroute.session-list/v1",
@@ -392,12 +394,14 @@
"hiroute.stable-route/v1",
"hiroute.standalone-install/v1",
"hiroute.standalone-package/v1",
+ "hiroute.standalone-program-restore/v1",
"hiroute.standalone-protected-input-request/v1",
"hiroute.standalone-protected-input-response/v1",
"hiroute.standalone-proxy-environment/v1",
"hiroute.standalone-service-doctor/v1",
"hiroute.standalone-service-logs/v1",
"hiroute.standalone-service-status/v1",
+ "hiroute.storage-startup-recovery/v1",
"hiroute.stored-plan/v1",
"hiroute.stored-publication/v1",
"hiroute.subscription-login-request/v1",
@@ -409,6 +413,7 @@
"hiroute.system-status/v1",
"hiroute.upgrade-installer-decision/v1",
"hiroute.upgrade-installer-started/v1",
+ "hiroute.upgrade-preflight/v1",
"hiroute.upgrade-source-backup/v1",
"hiroute.upgrade-source-backup/v2",
"hiroute.value-ledger-entry/v1",
@@ -420,6 +425,7 @@
"hiroute.windows-artifact-fingerprint/v1",
"hiroute.windows-background-install/v1",
"hiroute.windows-background/v1",
+ "hiroute.windows-desktop-restore/v1",
"hiroute.windows-install-journal/v1",
"hiroute.windows-install-layout/v1",
"hiroute.windows-install-request/v1",
@@ -975,6 +981,7 @@
"subject": "desktop_update",
"audited_prefixes": [
"hiroute.windows-desktop-package",
+ "hiroute.windows-desktop-restore",
"hiroute.website.releases",
"hiroute.desktop-upgrade-handoff",
"hiroute.upgrade-recovery-package",
@@ -985,6 +992,7 @@
],
"current_contracts": [
"hiroute.windows-desktop-package/v1",
+ "hiroute.windows-desktop-restore/v1",
"hiroute.website.releases/v3",
"hiroute.desktop-upgrade-handoff/v1",
"hiroute.upgrade-installer-started/v1",
@@ -1276,7 +1284,7 @@
"field": "context_window_tokens",
"mode": "recovery_read_only",
"owner": "agent-connections",
- "reason": "A descriptor reconstructed from a pre-window immutable settings operation has no managed context policy. It retains that operation\u2019s behavior until settings are saved again.",
+ "reason": "A descriptor reconstructed from a pre-window immutable settings operation has no managed context policy. It retains that operation’s behavior until settings are saved again.",
"removal_condition": "Retire with the pre-window settings operation recovery reader.",
"allowed_paths": [
"crates/domain/src/agents/managed_launch.rs",
diff --git a/crates/cli/src/host_commands.rs b/crates/cli/src/host_commands.rs
index 636d2511..c8733b92 100644
--- a/crates/cli/src/host_commands.rs
+++ b/crates/cli/src/host_commands.rs
@@ -36,6 +36,16 @@ pub(crate) fn execute(arguments: &[String], globals: &Globals) -> Option<CliExec
});
}
let request_id = globals.request_id.clone();
+ if arguments == ["service", "recovery"]
+ && globals.output == OutputMode::Text
+ && globals.agent.is_none()
+ && !globals.has_capability()
+ {
+ return Some(match service::recovery() {
+ Ok(value)=>CliExecution {exit_code:0,stdout:format!("HiRoute startup recovery\n\n{}\n\nStartup diagnostics: {}\n",value["instructions"].as_str().unwrap_or("No verified startup recovery report is available. Keep all data and inspect startup diagnostics; this does not establish service readiness or permission to downgrade."),value["diagnostics_root"].as_str().unwrap_or("unavailable")),stderr:String::new()},
+ Err(error)=>failure(map(error),request_id),
+ });
+ }
if globals.agent.is_some() || globals.has_capability() || globals.output != OutputMode::Json {
return Some(failure(ErrorCode::InvalidArguments, request_id));
}
@@ -46,16 +56,27 @@ pub(crate) fn execute(arguments: &[String], globals: &Globals) -> Option<CliExec
"protected-input" => protected_input_command(&arguments[1..], globals),
_ => unreachable!(),
};
- Some(match result {
+ let mut execution = match result {
Ok(value) => success(value, request_id),
Err(error) => failure(error, request_id),
- })
+ };
+ if execution.exit_code == 6
+ && family == "service"
+ && matches!(
+ arguments.get(1).map(String::as_str),
+ Some("start" | "restart")
+ )
+ && service::recovery().is_ok_and(|report| report["recovery"].is_object())
+ {
+ execution.stderr.push_str("Storage startup needs attention. Run `hiroute service recovery --output text` for the cause, safe next action and diagnostic location. Keep all data and packages.\n");
+ }
+ Some(execution)
}
fn host_help(family: &str) -> &'static str {
match family {
"service" => {
- "Usage\n hiroute service start|stop|restart|status|logs|doctor --output json\n hiroute service autostart enable|disable|status --output json\n hiroute service run\n hiroute service layout --output json\n"
+ "Usage\n hiroute service start|stop|restart|status|logs|doctor|recovery --output json\n hiroute service autostart enable|disable|status --output json\n hiroute service recovery [--output text|json]\n hiroute service run\n hiroute service layout --output json\n"
}
"gateway" => {
"Usage\n hiroute gateway show --output json\n hiroute gateway set --address <IPV4> --port auto|<PORT> [--accept-remote-risk] --output json\n hiroute gateway recover --output json\n"
@@ -96,6 +117,7 @@ fn service_command(
[verb] if verb == "restart" => json_value(service::restart(timeout).map_err(map)?)?,
[verb] if verb == "status" => json_value(service::status().map_err(map)?)?,
[verb] if verb == "logs" => service::logs().map_err(map)?,
+ [verb] if verb == "recovery" => service::recovery().map_err(map)?,
[verb] if verb == "doctor" => service::doctor(),
[verb] if verb == "layout" => service::windows_layout().map_err(map)?,
[verb, manager_flag, manager, daemon_flag, daemon]
diff --git a/crates/cli/src/service.rs b/crates/cli/src/service.rs
index ecebfbcd..d02cf1db 100644
--- a/crates/cli/src/service.rs
+++ b/crates/cli/src/service.rs
@@ -41,6 +41,91 @@ pub(crate) struct ServiceStatus {
runtime_root: PathBuf,
}
+pub(crate) fn recovery() -> Result<serde_json::Value, ServiceFailure> {
+ let layout = StandaloneLayout::from_environment().map_err(|_| ServiceFailure::Unavailable)?;
+ let record = hiroute_host_runtime::StorageRecovery::read_for_failed_startup(
+ &layout.storage_root(),
+ &layout.diagnostics_root(),
+ );
+ let instructions = record
+ .as_ref()
+ .map(|record| recovery_instructions(record, &layout.storage_root()));
+ Ok(
+ json!({"schema":"hiroute.service-recovery/v1", "recovery":record, "instructions":instructions, "diagnostics_root":layout.diagnostics_root()}),
+ )
+}
+
+fn recovery_instructions(record: &hiroute_host_runtime::StorageRecovery, storage: &Path) -> String {
+ use hiroute_host_runtime::StorageRecoveryAction;
+ let mut text = record.operator_guidance().to_owned();
+ if let Some(space) = &record.storage_space {
+ text.push_str(&format!(
+ " Storage volume: approximately {} bytes required, {} bytes available.",
+ space.required_bytes, space.available_bytes
+ ));
+ }
+ if matches!(
+ record.action,
+ StorageRecoveryAction::ResumeCurrent | StorageRecoveryAction::RestoreCompleteGroup
+ ) && let (Some(batch), Some(name), Some(parent), Some(leaf)) = (
+ record.backup_batch.as_deref(),
+ record.backup_name.as_deref(),
+ storage.parent(),
+ storage.file_name(),
+ ) && [batch, name].iter().all(|value| {
+ !value.is_empty()
+ && value.len() <= 128
+ && !value.contains("..")
+ && value
+ .bytes()
+ .all(|byte| byte.is_ascii_alphanumeric() || b"-_.".contains(&byte))
+ }) {
+ // The caller obtained this disposition through the storage owner's
+ // complete batch verification; formatting does not infer authority.
+ let mut directory = leaf.to_os_string();
+ directory.push(".upgrade-backups");
+ let source = parent.join(directory).join(name).join("source");
+ text.push_str(&format!(" Verified original batch: {batch}. Recovery source directory: {}. Read RECOVERY.md (or 恢复说明.md), then PROGRAM-LOCATIONS.md where present. Use only this batch.",source.display()));
+ }
+ text
+}
+
+#[cfg(test)]
+mod recovery_text_tests {
+ use super::*;
+ use hiroute_host_runtime::{StorageRecovery, StorageRecoveryAction, StorageRecoveryCause};
+
+ #[test]
+ fn offline_recovery_names_the_original_batch_and_exact_source_directory() {
+ let directory = tempfile::tempdir().unwrap();
+ let storage = directory.path().join("custom-storage");
+ let mut report = StorageRecovery::new(
+ StorageRecoveryCause::MigrationFailed,
+ StorageRecoveryAction::RestoreCompleteGroup,
+ );
+ report.backup_batch = Some("set_original".into());
+ report.backup_name = Some("observation-format-5".into());
+ let text = recovery_instructions(&report, &storage);
+ assert!(text.contains("Verified original batch: set_original"));
+ assert!(
+ text.contains(
+ &directory
+ .path()
+ .join("custom-storage.upgrade-backups/observation-format-5/source")
+ .display()
+ .to_string()
+ )
+ );
+ assert!(text.contains("RECOVERY.md"));
+ assert!(text.contains("PROGRAM-LOCATIONS.md"));
+ report.action = StorageRecoveryAction::PreserveAndDiagnose;
+ assert!(!recovery_instructions(&report, &storage).contains("Recovery source directory:"));
+ report.action = StorageRecoveryAction::RestoreCompleteGroup;
+ report.backup_name = Some("../foreign".into());
+ assert!(!recovery_instructions(&report, &storage).contains("Recovery source directory:"));
+ }
+}
+
pub(crate) fn status() -> Result<ServiceStatus, ServiceFailure> {
let (layout, _) = installed()?;
Ok(ServiceStatus {
@@ -59,13 +144,19 @@ pub(crate) fn start(timeout: Duration) -> Result<ServiceStatus, ServiceFailure>
let (layout, _) = installed()?;
ensure_not_maintaining(&layout)?;
if !manager_active(&layout) {
+ hiroute_host_runtime::StorageRecovery::clear(&layout.storage_root())
+ .map_err(|_| ServiceFailure::Unavailable)?;
capture_proxy_environment(&layout)?;
}
manager_start(&layout)?;
#[cfg(windows)]
wait_ready(deadline.saturating_duration_since(Instant::now()))?;
#[cfg(not(windows))]
- wait_ready(timeout)?;
+ if let Err(error) = wait_ready(timeout) {
+ #[cfg(target_os = "linux")]
+ stop_failed_storage_start(&layout);
+ return Err(error);
+ }
status()
}
@@ -86,6 +177,8 @@ pub(crate) fn restart(timeout: Duration) -> Result<ServiceStatus, ServiceFailure
let deadline = Instant::now() + timeout;
let (layout, _) = installed()?;
ensure_not_maintaining(&layout)?;
+ hiroute_host_runtime::StorageRecovery::clear(&layout.storage_root())
+ .map_err(|_| ServiceFailure::Unavailable)?;
capture_proxy_environment(&layout)?;
#[cfg(windows)]
windows::restart(&layout, timeout)?;
@@ -94,7 +187,11 @@ pub(crate) fn restart(timeout: Duration) -> Result<ServiceStatus, ServiceFailure
#[cfg(windows)]
wait_ready(deadline.saturating_duration_since(Instant::now()))?;
#[cfg(not(windows))]
- wait_ready(timeout)?;
+ if let Err(error) = wait_ready(timeout) {
+ #[cfg(target_os = "linux")]
+ stop_failed_storage_start(&layout);
+ return Err(error);
+ }
status()
}
@@ -354,11 +451,33 @@ fn wait_ready(timeout: Duration) -> Result<(), ServiceFailure> {
) {
return Ok(());
}
+ if StandaloneLayout::from_environment().is_ok_and(|layout| {
+ hiroute_host_runtime::StorageRecovery::read(&layout.storage_root())
+ .is_ok_and(|report| report.is_some())
+ }) {
+ return Err(ServiceFailure::Unavailable);
+ }
std::thread::sleep(Duration::from_millis(100));
}
Err(ServiceFailure::Unavailable)
}
+#[cfg(target_os = "linux")]
+fn stop_failed_storage_start(layout: &StandaloneLayout) {
+ if hiroute_host_runtime::StorageRecovery::read(&layout.storage_root())
+ .is_ok_and(|report| report.is_some())
+ {
+ // Deterministic storage admission needs correction, not an automatic
+ // manager restart loop. Stop only this verified installation's manager.
+ let _ = run_checked(Command::new("systemctl").args([
+ "--user",
+ "--no-block",
+ "stop",
+ SERVICE_LABEL,
+ ]));
+ }
+}
+
#[cfg(not(windows))]
fn wait_stopped(layout: &StandaloneLayout, timeout: Duration) -> Result<(), ServiceFailure> {
let endpoint = hiroute_client_core::LocalEndpoint::from_runtime_root(&layout.runtime_root);
@@ -383,7 +502,13 @@ fn control_ready(timeout: Duration) -> bool {
LocalControlClient::cli_from_environment()
.map(|client| client.with_timeout(timeout))
.and_then(|client| client.call(request))
- .is_ok_and(|response| response.status == MachineStatus::Succeeded)
+ .is_ok_and(|response| {
+ response.status == MachineStatus::Succeeded
+ && response.error.is_none()
+ && response
+ .data
+ .is_some_and(|data| data["daemon"] == "role_all" && data["gateway"] == "ready")
+ })
}
#[cfg(target_os = "linux")]
diff --git a/crates/daemon/Cargo.toml b/crates/daemon/Cargo.toml
index 17baf23a..2f5b3277 100644
--- a/crates/daemon/Cargo.toml
+++ b/crates/daemon/Cargo.toml
@@ -9,6 +9,7 @@ rust-version.workspace = true
integration-test-hooks = []
[dependencies]
+fs2.workspace = true
bytes.workspace = true
hyper = { version = "=1.11.1", features = ["server", "http1"] }
hyper-util = { version = "=0.1.20", features = ["tokio"] }
diff --git a/crates/daemon/src/control/bin.rs b/crates/daemon/src/control/bin.rs
index 7beb89ab..a54655dd 100644
--- a/crates/daemon/src/control/bin.rs
+++ b/crates/daemon/src/control/bin.rs
@@ -26,6 +26,8 @@ use zeroize::{Zeroize, Zeroizing};
mod ready;
#[cfg(any(unix, windows))]
mod standalone;
+mod startup_recovery;
+mod upgrade_preflight;
#[cfg(windows)]
mod windows_task;
use ready::{write_ready_frame, write_startup_failure_frame};
@@ -63,6 +65,9 @@ struct Arguments {
}
fn main() {
+ if let Some(code) = upgrade_preflight::run_if_requested() {
+ std::process::exit(code);
+ }
#[cfg(windows)]
if std::env::args_os().nth(1).as_deref() == Some(std::ffi::OsStr::new("app-server"))
&& std::env::var_os("HIROUTE_NATIVE_LAUNCH_DESCRIPTOR").is_some()
@@ -208,6 +213,7 @@ fn run_daemon(
level_override,
}));
hiroute_diagnostics::panic::install_panic_hook(diagnostics.handle().clone());
+ let recovery_root = arguments.storage_root.clone();
let result = match arguments.role.as_deref() {
Some("control") => run_control(arguments, &diagnostics),
Some("all") => run_all(
@@ -226,6 +232,13 @@ fn run_daemon(
if managed_role {
let _ = write_startup_failure_frame(error.code);
}
+ if let Some(recovery) = startup_recovery::failure_report(
+ error.code,
+ recovery_root.as_deref(),
+ error.recovery.as_deref(),
+ ) {
+ eprintln!("{}", recovery.operator_guidance());
+ }
diagnostics.shutdown();
return Err(error.message);
}
@@ -238,6 +251,7 @@ fn run_daemon(
struct StartupError {
code: StartupFailureCode,
message: String,
+ recovery: Option<Box<hiroute_host_runtime::StorageRecovery>>,
}
impl From<String> for StartupError {
@@ -257,6 +271,7 @@ impl StartupError {
Self {
code,
message: message.into(),
+ recovery: None,
}
}
}
@@ -278,6 +293,22 @@ fn diagnostics_elapsed_ms(diagnostics: &DiagnosticRuntime) -> u64 {
fn classify_role_all_error(error: &RoleAllError) -> StartupFailureCode {
match error {
+ RoleAllError::StorageRecovery(recovery) => match recovery.cause {
+ hiroute_host_runtime::StorageRecoveryCause::AccessDenied => {
+ StartupFailureCode::StorageAccessDenied
+ }
+ hiroute_host_runtime::StorageRecoveryCause::Locked => StartupFailureCode::StorageLocked,
+ hiroute_host_runtime::StorageRecoveryCause::MissingKey => {
+ StartupFailureCode::StorageKeyUnavailable
+ }
+ hiroute_host_runtime::StorageRecoveryCause::UnsupportedFormat => {
+ StartupFailureCode::UpgradeSourceUnsupported
+ }
+ hiroute_host_runtime::StorageRecoveryCause::UnknownState => {
+ StartupFailureCode::StorageUnavailable
+ }
+ _ => StartupFailureCode::UpgradeStorageFailed,
+ },
RoleAllError::InvalidConfiguration => StartupFailureCode::InvalidConfiguration,
RoleAllError::StandaloneProxyUnavailable => StartupFailureCode::DependencyUnavailable,
RoleAllError::JoinTimeout(_) => StartupFailureCode::Internal,
@@ -429,8 +460,7 @@ fn run_all(
)
})?
.map_err(|error| StartupError::new(StartupFailureCode::ReadyChannelFailed, error))?;
- let mut role = result
- .map_err(|error| StartupError::new(classify_role_all_error(&error), error.to_string()))?;
+ let mut role = result.map_err(startup_recovery::role_failure)?;
#[cfg(unix)]
let protected_inputs = match standalone::ProtectedInputServer::bind_path(protected_input_path) {
Ok(server) => server,
diff --git a/crates/daemon/src/control/runtime.rs b/crates/daemon/src/control/runtime.rs
index e432d9d8..806520bf 100644
--- a/crates/daemon/src/control/runtime.rs
+++ b/crates/daemon/src/control/runtime.rs
@@ -335,11 +335,20 @@ impl ProductionControlRuntime {
recover: bool,
overrides: RuntimeOpenOverrides,
) -> Result<Self, String> {
- observation_key::validate_existing_authority(storage_root)?;
+ observation_key::validate_existing_authority(storage_root).map_err(|error| {
+ overrides.storage_startup.report_failure(error.recovery());
+ error.to_string()
+ })?;
let mut startup = overrides.storage_startup.clone();
startup.preserve_observation_source =
LocalObservationStore::legacy_history_requires_seal(storage_root.join("observation"))
- .map_err(|error| format!("{error}; preserve all storage generations and use the original whole-group recovery guide"))?
+ .map_err(|error| {
+ startup.report_failure(hiroute_host_runtime::StorageRecovery::new(
+ hiroute_host_runtime::StorageRecoveryCause::UnsupportedFormat,
+ hiroute_host_runtime::StorageRecoveryAction::PreserveAndDiagnose,
+ ));
+ format!("{error}; preserve all storage generations and use the original whole-group recovery guide")
+ })?
|| LocalStorageSet::observation_cutover_pending(storage_root);
if startup.preserve_observation_source
&& let Some(progress) = &startup.upgrade_progress
@@ -550,7 +559,13 @@ impl ProductionControlRuntime {
} else {
LocalObservationStore::open(observation_root, digest_authority.clone())
}
- .map_err(|error| error.to_string())?,
+ .map_err(|error| {
+ startup.report_failure(stores.record_observation_startup_failure(
+ storage_root,
+ hiroute_host_runtime::StorageRecoveryCause::MigrationFailed,
+ ));
+ error.to_string()
+ })?,
);
if startup.preserve_observation_source
&& let Some(progress) = &startup.upgrade_progress
diff --git a/crates/daemon/src/control/runtime/observation_key.rs b/crates/daemon/src/control/runtime/observation_key.rs
index 04cc6720..d7bb42cc 100644
--- a/crates/daemon/src/control/runtime/observation_key.rs
+++ b/crates/daemon/src/control/runtime/observation_key.rs
@@ -56,17 +56,35 @@ pub(super) fn observation_workspace_key(
Err(INVALID.into())
}
-pub(super) fn validate_existing_authority(storage_root: &Path) -> Result<(), String> {
- if storage_root.join("observation/activity.db").exists()
- || storage_root.join("observation.upgrade.json").exists()
- || storage_root.join("observation-source-backup.json").exists()
- {
- let mut file = open_key(&storage_root.join("observation-hmac-key")).map_err(|_| INVALID)?;
- if file.metadata().map_err(|_| INVALID)?.len() != 32 {
- return Err(INVALID.into());
+pub(super) fn validate_existing_authority(
+ storage_root: &Path,
+) -> Result<(), hiroute_local_storage::LocalStorageError> {
+ use hiroute_local_storage::LocalStorageError as Error;
+ let mut required = false;
+ for name in [
+ "observation/activity.db",
+ "observation.upgrade.json",
+ "observation-source-backup.json",
+ ] {
+ match std::fs::symlink_metadata(storage_root.join(name)) {
+ Ok(_) => required = true,
+ Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
+ Err(error) => return Err(Error::Io(error)),
+ }
+ }
+ if required {
+ let mut file = open_key(&storage_root.join("observation-hmac-key")).map_err(|error| {
+ if error.kind() == std::io::ErrorKind::NotFound {
+ Error::Locked
+ } else {
+ Error::Io(error)
+ }
+ })?;
+ if file.metadata()?.len() != 32 {
+ return Err(Error::Locked);
}
let mut key = Zeroizing::new([0u8; 32]);
- file.read_exact(&mut *key).map_err(|_| INVALID)?;
+ file.read_exact(&mut *key)?;
}
Ok(())
}
diff --git a/crates/daemon/src/control/standalone/bootstrap.rs b/crates/daemon/src/control/standalone/bootstrap.rs
index 0dbe5d11..d0571dcc 100644
--- a/crates/daemon/src/control/standalone/bootstrap.rs
+++ b/crates/daemon/src/control/standalone/bootstrap.rs
@@ -9,7 +9,7 @@ use hiroute_diagnostics::event::{
use hiroute_diagnostics::runtime::DiagnosticRuntime;
use super::super::{
- Arguments, StartupError, classify_role_all_error, diagnostics_elapsed_ms, write_ready,
+ Arguments, StartupError, diagnostics_elapsed_ms, startup_recovery, write_ready,
};
use super::ProtectedInputServer;
@@ -183,10 +183,7 @@ pub(crate) fn run_all_standalone(
Ok(role) => role,
Err(error) => {
let _ = store.mark_failed("GATEWAY_START_FAILED");
- return Err(StartupError::new(
- classify_role_all_error(&error),
- error.to_string(),
- ));
+ return Err(startup_recovery::role_failure(error));
}
};
let server = match ProtectedInputServer::bind(&layout) {
diff --git a/crates/daemon/src/control/startup_recovery.rs b/crates/daemon/src/control/startup_recovery.rs
new file mode 100644
index 00000000..fb954917
--- /dev/null
+++ b/crates/daemon/src/control/startup_recovery.rs
@@ -0,0 +1,216 @@
+//! Terminal guidance belongs to the current failed attempt, never an older writer's report.
+use hiroute_diagnostics::event::StartupFailureCode;
+use hiroute_host_runtime::{StorageRecovery, StorageRecoveryAction, StorageRecoveryCause};
+use std::path::Path;
+
+pub(super) fn role_failure(error: hiroute_daemon::RoleAllError) -> super::StartupError {
+ let code = super::classify_role_all_error(&error);
+ let message = error.to_string();
+ let recovery = match error {
+ hiroute_daemon::RoleAllError::StorageRecovery(report) => Some(report),
+ _ => None,
+ };
+ super::StartupError {
+ code,
+ message,
+ recovery,
+ }
+}
+
+pub(super) fn failure_report(
+ code: StartupFailureCode,
+ storage: Option<&Path>,
+ current: Option<&StorageRecovery>,
+) -> Option<StorageRecovery> {
+ if let Some(current) = current {
+ return Some(current.clone());
+ }
+ if let Some(report) = StorageRecovery::read_for_admission_failure(code, storage) {
+ return Some(report);
+ }
+ match code {
+ StartupFailureCode::UpgradeStorageFailed => Some(
+ storage
+ .and_then(|root| StorageRecovery::read(root).ok().flatten())
+ .unwrap_or_else(unknown),
+ ),
+ StartupFailureCode::StorageUnavailable => Some(unknown()),
+ _ => None,
+ }
+}
+
+fn unknown() -> StorageRecovery {
+ StorageRecovery::new(
+ StorageRecoveryCause::UnknownState,
+ StorageRecoveryAction::PreserveAndDiagnose,
+ )
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn current_cause_survives_the_ready_channel_after_action_selection() {
+ let directory = tempfile::tempdir().unwrap();
+ StorageRecovery::new(
+ StorageRecoveryCause::MissingPackage,
+ StorageRecoveryAction::PreserveAndDiagnose,
+ )
+ .store(directory.path())
+ .unwrap();
+ for (cause, action, expected) in [
+ (
+ StorageRecoveryCause::UnknownState,
+ StorageRecoveryAction::PreserveAndDiagnose,
+ StartupFailureCode::StorageUnavailable,
+ ),
+ (
+ StorageRecoveryCause::Locked,
+ StorageRecoveryAction::RetryCurrent,
+ StartupFailureCode::StorageLocked,
+ ),
+ (
+ StorageRecoveryCause::AccessDenied,
+ StorageRecoveryAction::RetryCurrent,
+ StartupFailureCode::StorageAccessDenied,
+ ),
+ (
+ StorageRecoveryCause::MissingKey,
+ StorageRecoveryAction::RestoreCompleteGroup,
+ StartupFailureCode::StorageKeyUnavailable,
+ ),
+ (
+ StorageRecoveryCause::UnsupportedFormat,
+ StorageRecoveryAction::RestoreCompleteGroup,
+ StartupFailureCode::UpgradeSourceUnsupported,
+ ),
+ ] {
+ let current = StorageRecovery::new(cause, action);
+ let error = role_failure(hiroute_daemon::RoleAllError::StorageRecovery(Box::new(
+ current.clone(),
+ )));
+ assert_eq!(
+ error.code, expected,
+ "the ready/startup producer must retain cause independently of action"
+ );
+ assert_eq!(
+ failure_report(
+ error.code,
+ Some(directory.path()),
+ error.recovery.as_deref()
+ )
+ .unwrap(),
+ current
+ );
+ let offline = failure_report(error.code, Some(directory.path()), None).unwrap();
+ assert_eq!(
+ offline.cause, cause,
+ "a consumer must not borrow the older missing-package record"
+ );
+ assert_eq!(
+ offline.action,
+ if matches!(
+ cause,
+ StorageRecoveryCause::Locked | StorageRecoveryCause::AccessDenied
+ ) {
+ StorageRecoveryAction::RetryCurrent
+ } else {
+ StorageRecoveryAction::PreserveAndDiagnose
+ }
+ );
+ }
+ assert_eq!(
+ StorageRecovery::read(directory.path())
+ .unwrap()
+ .unwrap()
+ .cause,
+ StorageRecoveryCause::MissingPackage
+ );
+ }
+
+ #[test]
+ fn current_admission_failure_never_borrows_an_old_package_instruction() {
+ let directory = tempfile::tempdir().unwrap();
+ StorageRecovery::new(
+ StorageRecoveryCause::MissingPackage,
+ StorageRecoveryAction::PreserveAndDiagnose,
+ )
+ .store(directory.path())
+ .unwrap();
+ let report = failure_report(
+ StartupFailureCode::StorageLocked,
+ Some(directory.path()),
+ None,
+ )
+ .unwrap();
+ assert_eq!(report.cause, StorageRecoveryCause::Locked);
+ assert_eq!(report.action, StorageRecoveryAction::RetryCurrent);
+ assert!(
+ report
+ .operator_guidance()
+ .contains("Close other owned HiRoute")
+ );
+ assert!(
+ !report
+ .operator_guidance()
+ .contains("HIROUTE_RECOVERY_PACKAGE")
+ );
+ assert_eq!(
+ StorageRecovery::read(directory.path())
+ .unwrap()
+ .unwrap()
+ .cause,
+ StorageRecoveryCause::MissingPackage,
+ "a failed non-writer must not overwrite the old writer's report",
+ );
+ assert!(
+ failure_report(
+ StartupFailureCode::InvalidConfiguration,
+ Some(directory.path()),
+ None
+ )
+ .is_none()
+ );
+ }
+
+ #[test]
+ fn missing_or_unreadable_current_report_only_grants_preservation() {
+ let directory = tempfile::tempdir().unwrap();
+ for code in [
+ StartupFailureCode::StorageUnavailable,
+ StartupFailureCode::UpgradeStorageFailed,
+ ] {
+ let report = failure_report(code, Some(directory.path()), None).unwrap();
+ assert_eq!(report.action, StorageRecoveryAction::PreserveAndDiagnose);
+ assert_eq!(report.cause, StorageRecoveryCause::UnknownState);
+ }
+ }
+
+ #[test]
+ fn current_typed_disposition_survives_both_daemon_launch_modes() {
+ let directory = tempfile::tempdir().unwrap();
+ StorageRecovery::new(
+ StorageRecoveryCause::MissingPackage,
+ StorageRecoveryAction::PreserveAndDiagnose,
+ )
+ .store(directory.path())
+ .unwrap();
+ let current = unknown();
+ let error = role_failure(hiroute_daemon::RoleAllError::StorageRecovery(Box::new(
+ current.clone(),
+ )));
+ let report = failure_report(
+ error.code,
+ Some(directory.path()),
+ error.recovery.as_deref(),
+ )
+ .unwrap();
+ assert_eq!(report, current);
+ assert!(
+ !report
+ .operator_guidance()
+ .contains("HIROUTE_RECOVERY_PACKAGE")
+ );
+ }
+}
diff --git a/crates/daemon/src/control/upgrade_preflight.rs b/crates/daemon/src/control/upgrade_preflight.rs
new file mode 100644
index 00000000..eaa16f07
--- /dev/null
+++ b/crates/daemon/src/control/upgrade_preflight.rs
@@ -0,0 +1,62 @@
+//! Candidate-only read-only preflight used by verified installers.
+use hiroute_host_runtime::{
+ StorageRecovery, StorageRecoveryAction, StorageRecoveryCause, UpgradePreflight,
+};
+use std::path::PathBuf;
+pub(super) fn run_if_requested() -> Option<i32> {
+ let args: Vec<_> = std::env::args_os().skip(1).collect();
+ if args.first().is_none_or(|a| a != "--upgrade-preflight") {
+ return None;
+ }
+ if args.len() != 5 || args[1] != "--storage-root" || args[3] != "--recovery-package" {
+ return Some(2);
+ }
+ let root = PathBuf::from(&args[2]);
+ let package = PathBuf::from(&args[4]);
+ if !root.is_absolute() || !package.is_absolute() {
+ return Some(2);
+ }
+ let result = (|| {
+ let seal = hiroute_observation::LocalObservationStore::legacy_history_requires_seal(
+ root.join("observation"),
+ )
+ .map_err(|_| {
+ Box::new(StorageRecovery::new(
+ StorageRecoveryCause::UnknownState,
+ StorageRecoveryAction::PreserveAndDiagnose,
+ ))
+ })?;
+ let required =
+ hiroute_local_storage::LocalStorageSet::preflight_upgrade(&root, &package, seal)
+ .map_err(|e| Box::new(e.recovery()))?;
+ Ok::<_, Box<StorageRecovery>>((seal, required))
+ })();
+ let available = fs2::available_space(if root.exists() {
+ &root
+ } else {
+ root.parent().unwrap_or(&root)
+ })
+ .unwrap_or(0);
+ let (history_cutover_required, required_bytes, recovery) = match result {
+ Ok((seal, required)) => (seal, required, None),
+ Err(e) => (
+ false,
+ e.storage_space
+ .as_ref()
+ .map_or(0, |space| space.required_bytes),
+ Some(*e),
+ ),
+ };
+ let failed = recovery.is_some();
+ let report = UpgradePreflight {
+ schema: "hiroute.upgrade-preflight/v1".into(),
+ history_cutover_required,
+ required_bytes,
+ available_bytes: available,
+ recovery,
+ };
+ if serde_json::to_writer(std::io::stdout().lock(), &report).is_err() {
+ return Some(1);
+ }
+ Some(if failed { 1 } else { 0 })
+}
diff --git a/crates/daemon/src/delegation/lifecycle/tests/codex_capability.rs b/crates/daemon/src/delegation/lifecycle/tests/codex_capability.rs
index 75d8b061..3abaf72c 100644
--- a/crates/daemon/src/delegation/lifecycle/tests/codex_capability.rs
+++ b/crates/daemon/src/delegation/lifecycle/tests/codex_capability.rs
@@ -55,8 +55,6 @@ for line in sys.stdin:
.duration_since(UNIX_EPOCH)
.unwrap()
.as_millis() as i64;
- request.deadline_unix_ms = now_ms as u64 + 5_000;
- input.deadline = Instant::now() + Duration::from_secs(5);
if continued {
input.session = AcpSessionStart::Load(AcpSessionBinding {
acp_session_id: "native-session".into(),
@@ -85,6 +83,14 @@ for line in sys.stdin:
))),
));
let private_root = request.profile.private_root.clone();
+ // The adapter owns this five-second budget; observation fixture
+ // initialization under a busy test host must not consume it.
+ request.deadline_unix_ms = SystemTime::now()
+ .duration_since(UNIX_EPOCH)
+ .unwrap()
+ .as_millis() as u64
+ + 5_000;
+ input.deadline = Instant::now() + Duration::from_secs(5);
let result = execute(
&LocalWorkerPlatform::default(),
request,
diff --git a/crates/daemon/src/role_all.rs b/crates/daemon/src/role_all.rs
index 821c813f..895ff376 100644
--- a/crates/daemon/src/role_all.rs
+++ b/crates/daemon/src/role_all.rs
@@ -426,12 +426,14 @@ pub fn start_role_all(config: RoleAllConfig) -> Result<RoleAllHandle, RoleAllErr
config
.diagnostics
.stage_begin(StartupStage::PublicationReconcile);
+ let (storage_failure, storage_failures) = std::sync::mpsc::channel();
let runtime = ProductionControlRuntime::prepare_for_role_all_with_codex_desktop_engine(
&config.storage_root,
catalog,
cpa.clone(),
config.codex_desktop_engine.clone(),
hiroute_local_storage::StorageStartupOptions {
+ startup_failure: Some(storage_failure),
gateway_lkg: Some(config.gateway_lkg.clone()),
upgrade_progress: config.upgrade_progress.clone(),
recovery_package: std::env::var_os("HIROUTE_RECOVERY_PACKAGE")
@@ -439,7 +441,10 @@ pub fn start_role_all(config: RoleAllConfig) -> Result<RoleAllHandle, RoleAllErr
..Default::default()
},
)
- .map_err(|error| RoleAllError::Component("Storage", error));
+ .map_err(|error| match storage_failures.try_iter().last() {
+ Some(recovery) => RoleAllError::StorageRecovery(Box::new(recovery)),
+ None => RoleAllError::Component("Storage", error),
+ });
let runtime = match runtime {
Ok(runtime) => {
config
@@ -848,6 +853,8 @@ pub enum RoleAllError {
StandaloneProxyUnavailable,
#[error("role=all configuration is invalid")]
InvalidConfiguration,
+ #[error("storage startup recovery required: {0:?}")]
+ StorageRecovery(Box<hiroute_host_runtime::StorageRecovery>),
#[error("{0} component failed: {1}")]
Component(&'static str, String),
#[error("{0} did not stop before the role=all deadline")]
diff --git a/crates/daemon/tests/windows_desktop.rs b/crates/daemon/tests/windows_desktop.rs
index 44e14dcb..286d7348 100644
--- a/crates/daemon/tests/windows_desktop.rs
+++ b/crates/daemon/tests/windows_desktop.rs
@@ -80,7 +80,17 @@ fn run(program: &Path, args: &[&str], evidence: &Path, phase: &str) -> Vec<u8> {
.stderr(File::create(error).unwrap())
.spawn()
.unwrap();
- let deadline = Instant::now() + Duration::from_secs(150);
+ // NSIS wraps the product's 600-second install request plus extraction/hooks.
+ // Keep CLI and uninstall requests on their existing watchdog.
+ let seconds = if program
+ .file_name()
+ .is_some_and(|name| name == "installer.exe")
+ {
+ 720
+ } else {
+ 150
+ };
+ let deadline = Instant::now() + Duration::from_secs(seconds);
loop {
if let Some(status) = child.try_wait().unwrap() {
assert!(status.success(), "native phase {phase} failed: {status}");
diff --git a/crates/diagnostics/src/event/startup.rs b/crates/diagnostics/src/event/startup.rs
index e470d29f..5a4f16f5 100644
--- a/crates/diagnostics/src/event/startup.rs
+++ b/crates/diagnostics/src/event/startup.rs
@@ -31,6 +31,9 @@ pub enum StartupOutcome {
pub enum StartupFailureCode {
InvalidConfiguration,
StorageUnavailable,
+ StorageAccessDenied,
+ StorageLocked,
+ StorageKeyUnavailable,
UpgradeSourceUnsupported,
UpgradeStorageFailed,
ReleaseFactsInvalid,
diff --git a/crates/host-runtime/Cargo.toml b/crates/host-runtime/Cargo.toml
index 3b607b20..40a75bed 100644
--- a/crates/host-runtime/Cargo.toml
+++ b/crates/host-runtime/Cargo.toml
@@ -9,6 +9,7 @@ rust-version.workspace = true
getrandom.workspace = true
fs2.workspace = true
hiroute-platform = { path = "../platform" }
+hiroute-diagnostics = { path = "../diagnostics" }
nix.workspace = true
serde.workspace = true
serde_json.workspace = true
diff --git a/crates/host-runtime/src/lib.rs b/crates/host-runtime/src/lib.rs
index b97ef9fe..73f843f1 100644
--- a/crates/host-runtime/src/lib.rs
+++ b/crates/host-runtime/src/lib.rs
@@ -31,3 +31,12 @@ pub use subscription_proxy::*;
mod console_listener;
pub use console_listener::*;
pub mod standalone_install;
+
+mod storage_recovery;
+pub use storage_recovery::*;
+
+mod recovery_package;
+pub use recovery_package::*;
+
+mod upgrade_preflight;
+pub use upgrade_preflight::*;
diff --git a/crates/host-runtime/src/recovery_package.rs b/crates/host-runtime/src/recovery_package.rs
new file mode 100644
index 00000000..48e26fea
--- /dev/null
+++ b/crates/host-runtime/src/recovery_package.rs
@@ -0,0 +1,293 @@
+//! Installer-owned previous package handoff for native standalone processes.
+use hiroute_platform::{durable, private_fs};
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+use std::{
+ collections::BTreeMap,
+ fs,
+ io::{self, Read},
+ path::{Path, PathBuf},
+};
+
+pub const RETAINED_PACKAGE_FILE: &str = "upgrade-package.json";
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct WindowsDesktopRestore {
+ pub schema: String,
+ pub program: PathBuf,
+ pub desktop: Option<PathBuf>,
+ pub task_name: String,
+ pub task_autostart: bool,
+ pub shell_login: bool,
+ pub files: BTreeMap<String, PathBuf>,
+}
+impl WindowsDesktopRestore {
+ pub fn validate(&self) -> io::Result<()> {
+ if self.schema != "hiroute.windows-desktop-restore/v1"
+ || !self.program.is_absolute()
+ || self
+ .desktop
+ .as_ref()
+ .is_some_and(|path| !path.is_absolute())
+ || self.files.is_empty()
+ || self
+ .task_name
+ .strip_prefix("HiRoute-")
+ .is_none_or(|suffix| {
+ suffix.len() != 64
+ || !suffix
+ .bytes()
+ .all(|byte| byte.is_ascii_hexdigit() && !byte.is_ascii_uppercase())
+ })
+ || self.files.len() > 6000
+ || !self.files.contains_key("installation/standalone.json")
+ || !self
+ .files
+ .contains_key("installation/windows-background.json")
+ || self.files.iter().any(|(name, target)| {
+ !name.starts_with("installation/")
+ || !target.is_absolute()
+ || name.contains(['\\', ':'])
+ || name.split('/').any(|part| {
+ part.is_empty()
+ || part == "."
+ || part == ".."
+ || !part
+ .bytes()
+ .all(|byte| byte.is_ascii_alphanumeric() || b"-_.".contains(&byte))
+ })
+ })
+ {
+ return Err(invalid());
+ }
+ Ok(())
+ }
+}
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct RetainedRecoveryPackage {
+ pub schema: String,
+ pub storage_root: PathBuf,
+ pub package_root: PathBuf,
+ pub target_daemon_sha256: String,
+ pub files: BTreeMap<String, String>,
+}
+fn invalid() -> io::Error {
+ io::Error::other("UPGRADE_RECOVERY_PACKAGE_INVALID")
+}
+fn hash(path: &Path) -> io::Result<String> {
+ let mut file = private_fs::open_regular_file(path)?;
+ let mut digest = Sha256::new();
+ let mut buffer = [0u8; 64 * 1024];
+ loop {
+ let count = file.read(&mut buffer)?;
+ if count == 0 {
+ break;
+ }
+ digest.update(&buffer[..count]);
+ }
+ Ok(format!("{:x}", digest.finalize()))
+}
+impl RetainedRecoveryPackage {
+ pub fn capture(
+ storage_root: &Path,
+ package_root: &Path,
+ target_daemon: &Path,
+ ) -> io::Result<Self> {
+ fn collect(
+ root: &Path,
+ path: &Path,
+ files: &mut BTreeMap<String, String>,
+ ) -> io::Result<()> {
+ let metadata = fs::symlink_metadata(path)?;
+ if metadata.file_type().is_symlink() {
+ return Err(invalid());
+ }
+ if metadata.is_dir() {
+ for entry in fs::read_dir(path)? {
+ collect(root, &entry?.path(), files)?;
+ }
+ } else if metadata.is_file() {
+ let relative = path
+ .strip_prefix(root)
+ .map_err(|_| invalid())?
+ .to_str()
+ .ok_or_else(invalid)?
+ .replace('\\', "/");
+ files.insert(relative, hash(path)?);
+ } else {
+ return Err(invalid());
+ }
+ if files.len() > 6000 {
+ return Err(invalid());
+ }
+ Ok(())
+ }
+ let mut files = BTreeMap::new();
+ collect(package_root, package_root, &mut files)?;
+ if files.is_empty() {
+ return Err(invalid());
+ }
+ Ok(Self {
+ schema: "hiroute.retained-recovery-package/v1".into(),
+ storage_root: storage_root.to_path_buf(),
+ package_root: package_root.to_path_buf(),
+ target_daemon_sha256: hash(target_daemon)?,
+ files,
+ })
+ }
+ pub fn store(&self) -> io::Result<()> {
+ durable::write_private_atomic(
+ &self
+ .storage_root
+ .parent()
+ .ok_or_else(invalid)?
+ .join(RETAINED_PACKAGE_FILE),
+ &serde_json::to_vec(self)?,
+ )
+ }
+ pub fn read(storage: &Path) -> io::Result<Option<Self>> {
+ let path = storage
+ .parent()
+ .ok_or_else(invalid)?
+ .join(RETAINED_PACKAGE_FILE);
+ let mut file = match private_fs::open_private_file(&path) {
+ Ok(f) => f,
+ Err(e) if e.kind() == io::ErrorKind::NotFound => return Ok(None),
+ Err(e) => return Err(e),
+ };
+ private_fs::verify_single_link(&file)?;
+ let mut bytes = Vec::new();
+ file.by_ref()
+ .take(1024 * 1024 + 1)
+ .read_to_end(&mut bytes)?;
+ if bytes.len() > 1024 * 1024 {
+ return Err(invalid());
+ }
+ let value: Self = serde_json::from_slice(&bytes).map_err(|_| invalid())?;
+ if value.schema != "hiroute.retained-recovery-package/v1"
+ || value.storage_root != storage
+ || !value.package_root.is_absolute()
+ || value.files.is_empty()
+ || value.files.len() > 6000
+ || value.target_daemon_sha256.len() != 64
+ {
+ return Err(invalid());
+ }
+ Ok(Some(value))
+ }
+ pub fn verify(&self, target_daemon: &Path) -> io::Result<()> {
+ if hash(target_daemon)? != self.target_daemon_sha256 {
+ return Err(invalid());
+ }
+ if !fs::symlink_metadata(&self.package_root)?.is_dir()
+ || fs::symlink_metadata(&self.package_root)?
+ .file_type()
+ .is_symlink()
+ {
+ return Err(invalid());
+ }
+ if Self::capture(&self.storage_root, &self.package_root, target_daemon)?.files != self.files
+ {
+ return Err(invalid());
+ }
+ for (name, expected) in &self.files {
+ if name.is_empty()
+ || name.len() > 512
+ || name.contains('\\')
+ || name.split('/').any(|s| {
+ s.is_empty()
+ || s == "."
+ || s == ".."
+ || !s
+ .bytes()
+ .all(|b| b.is_ascii_alphanumeric() || b"-_.@".contains(&b))
+ })
+ {
+ return Err(invalid());
+ }
+ let path = self.package_root.join(name);
+ let mut parent = path.parent().ok_or_else(invalid)?;
+ while parent != self.package_root {
+ let m = fs::symlink_metadata(parent)?;
+ if !m.is_dir() || m.file_type().is_symlink() {
+ return Err(invalid());
+ }
+ parent = parent.parent().ok_or_else(invalid)?;
+ }
+ if expected.len() != 64 || !expected.bytes().all(|b| b.is_ascii_hexdigit()) {
+ return Err(invalid());
+ }
+ }
+ Ok(())
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ #[test]
+ fn complete_desktop_restore_metadata_rejects_unknown_or_foreign_destinations() {
+ let directory = tempfile::tempdir().unwrap();
+ let value = WindowsDesktopRestore {
+ schema: "hiroute.windows-desktop-restore/v1".into(),
+ program: directory.path().join("old-program"),
+ desktop: Some(directory.path().join("old-desktop")),
+ task_name: format!("HiRoute-{}", "a".repeat(64)),
+ task_autostart: false,
+ shell_login: true,
+ files: BTreeMap::from([
+ (
+ "installation/standalone.json".into(),
+ directory.path().join("standalone.json"),
+ ),
+ (
+ "installation/windows-background.json".into(),
+ directory.path().join("background.json"),
+ ),
+ ]),
+ };
+ value.validate().unwrap();
+ let mut unknown = serde_json::to_value(&value).unwrap();
+ unknown["run_arbitrary_command"] = "ignored fields must not be accepted".into();
+ assert!(serde_json::from_value::<WindowsDesktopRestore>(unknown).is_err());
+ let mut unsafe_record = value.clone();
+ unsafe_record.files.insert(
+ "installation/../foreign".into(),
+ directory.path().join("foreign"),
+ );
+ assert!(unsafe_record.validate().is_err());
+ unsafe_record = value.clone();
+ unsafe_record.desktop = Some("relative-desktop".into());
+ assert!(unsafe_record.validate().is_err());
+ unsafe_record = value.clone();
+ unsafe_record
+ .files
+ .remove("installation/windows-background.json");
+ assert!(unsafe_record.validate().is_err());
+ unsafe_record = value;
+ unsafe_record.task_name = "unrelated-task".into();
+ assert!(unsafe_record.validate().is_err());
+ }
+ #[test]
+ fn retained_source_rejects_changed_package_and_wrong_target() {
+ let dir = tempfile::tempdir().unwrap();
+ let package = dir.path().join("old");
+ private_fs::prepare_storage_directory(&package).unwrap();
+ durable::write_private_new(&package.join("hirouted"), b"old program").unwrap();
+ let target = dir.path().join("new");
+ durable::write_private_new(&target, b"new program").unwrap();
+ let storage = dir.path().join("storage");
+ let record = RetainedRecoveryPackage::capture(&storage, &package, &target).unwrap();
+ record.verify(&target).unwrap();
+ record.store().unwrap();
+ let loaded = RetainedRecoveryPackage::read(&storage).unwrap().unwrap();
+ loaded.verify(&target).unwrap();
+ fs::write(&target, b"replaced new program").unwrap();
+ assert!(loaded.verify(&target).is_err());
+ fs::write(&target, b"new program").unwrap();
+ fs::write(package.join("hirouted"), b"wrong old program").unwrap();
+ assert!(loaded.verify(&target).is_err());
+ }
+}
diff --git a/crates/host-runtime/src/standalone_install/journal.rs b/crates/host-runtime/src/standalone_install/journal.rs
index cfaee18b..90d97483 100644
--- a/crates/host-runtime/src/standalone_install/journal.rs
+++ b/crates/host-runtime/src/standalone_install/journal.rs
@@ -206,6 +206,11 @@ impl Journal {
if self.phase == Phase::Committed {
return self.finish(layout);
}
+ if self.operation == Operation::Install
+ && crate::storage_upgrade_started(&layout.storage_root())?
+ {
+ return Err(io::Error::other("STORAGE_UPGRADE_RECOVERY_REQUIRED"));
+ }
for entry in &self.files {
entry.check_current()?;
}
@@ -249,6 +254,31 @@ impl Journal {
}
self.finish_backups(layout)
}
+
+ /// The native leaf must independently match the accepted complete package
+ /// before calling this forward-only path. Never register the older daemon.
+ pub fn reapply_install(
+ &self,
+ layout: &StandaloneLayout,
+ host: &mut impl ManagerHost,
+ ) -> io::Result<()> {
+ self.validate(layout)?;
+ if self.operation != Operation::Install || self.phase != Phase::Prepared {
+ return Err(invalid());
+ }
+ for entry in &self.files {
+ entry.check_current()?;
+ }
+ let mut definitions = vec![&self.new_definition];
+ if let Some(old) = &self.old_definition {
+ definitions.push(old);
+ }
+ host.quiesce(&definitions)?;
+ self.apply_files()?;
+ write_json(&layout.marker_path, &self.new_marker)?;
+ host.register(&self.new_definition, self.old_definition.as_ref())?;
+ write_json(&self.new_marker.service_definition, &self.new_definition)
+ }
}
impl Entry {
fn check_current(&self) -> io::Result<()> {
diff --git a/crates/host-runtime/src/standalone_install/journal/tests.rs b/crates/host-runtime/src/standalone_install/journal/tests.rs
index 87ec4396..9010705f 100644
--- a/crates/host-runtime/src/standalone_install/journal/tests.rs
+++ b/crates/host-runtime/src/standalone_install/journal/tests.rs
@@ -4,14 +4,16 @@ use serde_json::json;
#[derive(Default)]
struct Manager {
calls: Vec<&'static str>,
+ registered: Vec<Value>,
}
impl ManagerHost for Manager {
fn quiesce(&mut self, _: &[&Value]) -> io::Result<()> {
self.calls.push("stop");
Ok(())
}
- fn register(&mut self, _: &Value, _: Option<&Value>) -> io::Result<()> {
+ fn register(&mut self, value: &Value, _: Option<&Value>) -> io::Result<()> {
self.calls.push("register");
+ self.registered.push(value.clone());
Ok(())
}
fn unregister(&mut self, _: &Value) -> io::Result<()> {
@@ -65,6 +67,62 @@ fn fixture() -> (tempfile::TempDir, StandaloneLayout, Journal) {
}
use sha2::Digest;
#[test]
+fn changed_storage_refuses_rollback_and_forward_reapplication_never_registers_old_program() {
+ let (_temp, layout, mut journal) = fixture();
+ let mut old = journal.new_marker.clone();
+ old.install_root = layout.home.join(".local/lib/hiroute/0.3.0-bbbbbbbbbbbb");
+ old.cpa_binary = Some(old.install_root.join("libexec/cliproxyapi.exe"));
+ journal.old_marker = Some(old);
+ journal.old_definition = Some(json!({"manager":"old-task"}));
+ let entry = &mut journal.files[0];
+ fs::write(&entry.destination, b"old").unwrap();
+ directory(entry.backup.parent().unwrap()).unwrap();
+ copy_new(&entry.destination, &entry.backup).unwrap();
+ entry.old_sha256 = Some(format!("{:x}", sha2::Sha256::digest(b"old")));
+ journal.persist(&layout).unwrap();
+ journal.apply_files().unwrap();
+ directory(&layout.storage_root()).unwrap();
+ let flag = layout.storage_root().join("observation.upgrade.json");
+ fs::write(&flag, b"current storage transition; portable fixture only").unwrap();
+ let mut host = Manager::default();
+ assert_eq!(
+ journal
+ .clone()
+ .recover(&layout, &mut host)
+ .unwrap_err()
+ .to_string(),
+ "STORAGE_UPGRADE_RECOVERY_REQUIRED"
+ );
+ assert!(host.calls.is_empty());
+ for _ in 0..2 {
+ journal.reapply_install(&layout, &mut host).unwrap();
+ assert_eq!(fs::read(&journal.files[0].destination).unwrap(), b"new");
+ assert_eq!(fs::read(&journal.files[0].backup).unwrap(), b"old");
+ assert_eq!(
+ fs::read(&flag).unwrap(),
+ b"current storage transition; portable fixture only"
+ );
+ }
+ assert_eq!(host.registered, vec![journal.new_definition.clone(); 2]);
+ assert!(Journal::path(&layout).is_file());
+ journal.commit(&layout).unwrap();
+ journal.finish(&layout).unwrap();
+ assert!(!Journal::path(&layout).exists());
+}
+
+#[test]
+fn forward_reapplication_refuses_changed_files_before_manager_effects() {
+ let (_temp, layout, journal) = fixture();
+ fs::write(&journal.files[0].destination, b"foreign native entry").unwrap();
+ let mut host = Manager::default();
+ assert!(journal.reapply_install(&layout, &mut host).is_err());
+ assert!(host.calls.is_empty());
+ assert_eq!(
+ fs::read(&journal.files[0].destination).unwrap(),
+ b"foreign native entry"
+ );
+}
+#[test]
fn pending_manager_delete_keeps_prepared_journal_and_all_owned_files() {
struct Pending;
impl ManagerHost for Pending {
diff --git a/crates/host-runtime/src/standalone_install/windows.rs b/crates/host-runtime/src/standalone_install/windows.rs
index 730536fc..14bc7030 100644
--- a/crates/host-runtime/src/standalone_install/windows.rs
+++ b/crates/host-runtime/src/standalone_install/windows.rs
@@ -15,6 +15,9 @@ use std::{
path::PathBuf,
time::Duration,
};
+mod repair;
+mod space;
+pub use space::{ReplacementSpaceFailure, preflight_desktop_space};
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
@@ -215,6 +218,9 @@ pub fn recover_pending() -> io::Result<()> {
}
fn cleanup_locked(layout: &StandaloneLayout) -> io::Result<PackageCleanup> {
let mut retained = vec![];
+ if let Some(package) = crate::RetainedRecoveryPackage::read(&layout.storage_root())? {
+ retained.push(package.package_root);
+ }
if let Some(marker) = read_json::<StandaloneInstallRecordV1>(&layout.marker_path, MAX_RECORD)? {
marker.validate().map_err(|_| invalid())?;
retained.push(marker.install_root);
@@ -308,6 +314,29 @@ fn entries(
));
entries
}
+/// The installed transaction owns the complete native file map. Snapshot callers
+/// may retain these admitted bytes, but cannot supply filesystem destinations.
+pub fn recovery_files() -> io::Result<Vec<(PathBuf, String, String)>> {
+ let layout = layout()?;
+ let (marker, _, package) = current(&layout)?.ok_or_else(invalid)?;
+ let mut output = vec![];
+ for (index, (destination, source, _, _)) in entries(&marker.install_root, &layout, &package)
+ .into_iter()
+ .enumerate()
+ {
+ let expected = digest(&source)?.ok_or_else(invalid)?;
+ if digest(&destination)?.as_deref() != Some(expected.as_str()) {
+ return Err(invalid());
+ }
+ output.push((
+ destination,
+ format!("installation/entry-{index}.bin"),
+ expected,
+ ));
+ }
+ Ok(output)
+}
+
fn publish_package(source: &Path, root: &Path, package: &Package) -> io::Result<()> {
if root.try_exists()? {
return package.verify_directory(root);
@@ -328,6 +357,41 @@ fn publish_package(source: &Path, root: &Path, package: &Package) -> io::Result<
package.verify_directory(&stage)?;
hiroute_platform::durable::rename(&stage, root)
}
+fn retained_source(
+ layout: &StandaloneLayout,
+ previous: &(StandaloneInstallRecordV1, Value, Package),
+ target: &std::path::Path,
+) -> io::Result<PathBuf> {
+ if let Some(retained) = crate::RetainedRecoveryPackage::read(&layout.storage_root())?
+ && digest(target)?.as_deref() == Some(retained.target_daemon_sha256.as_str())
+ {
+ retained.verify(target)?;
+ if retained.package_root == previous.0.install_root {
+ return Ok(retained.package_root);
+ }
+ // The NSIS owner retained both program namespaces. Bind its original
+ // standalone payload, marker and Task to this exact installation, rather
+ // than accepting any same-version directory from the handoff.
+ if Package::read(&retained.package_root.join("program"))?.canonical()?
+ != previous.2.canonical()?
+ || read_json::<Value>(
+ &retained.package_root.join("installation/standalone.json"),
+ MAX_RECORD,
+ )? != Some(serde_json::to_value(&previous.0).map_err(|_| invalid())?)
+ || read_json::<Value>(
+ &retained
+ .package_root
+ .join("installation/windows-background.json"),
+ MAX_RECORD,
+ )? != Some(previous.1.clone())
+ {
+ return Err(invalid());
+ }
+ return Ok(retained.package_root);
+ }
+ Ok(previous.0.install_root.clone())
+}
+
pub fn install(request: InstallRequest) -> io::Result<Value> {
if request.schema != "hiroute.windows-install-request/v1" {
return Err(invalid());
@@ -346,14 +410,35 @@ pub fn install(request: InstallRequest) -> io::Result<Value> {
allow_unavailable_stop: false,
};
if let Some(journal) = Journal::read(&layout)? {
+ if journal.operation == journal::Operation::Install
+ && journal.phase == journal::Phase::Prepared
+ && crate::storage_upgrade_started(&layout.storage_root())?
+ {
+ repair::resume(journal, &package, &layout, &mut host, request.autostart)?;
+ return repair::finish(&layout, &package, &request);
+ }
journal.recover(&layout, &mut host)?;
}
let old = current(&layout)?;
+ if let Some(previous) = &old {
+ previous.2.verify_directory(&previous.0.install_root)?;
+ }
let root = layout
.home
.join(".local/lib/hiroute")
.join(package.directory_name());
publish_package(&request.package_directory, &root, &package)?;
+ let recovery_root = if let Some(previous) = &old
+ && root != previous.0.install_root
+ {
+ let target = root.join("hirouted.exe");
+ let source = retained_source(&layout, previous, &target)?;
+ let report = crate::checked_upgrade_preflight(&target, &layout.storage_root(), &source)
+ .map_err(io::Error::other)?;
+ report.history_cutover_required.then_some(source)
+ } else {
+ None
+ };
let native = Definition::new(Manager::Task, root.join("hirouted.exe"))?;
let marker = StandaloneInstallRecordV1 {
schema_version: crate::STANDALONE_INSTALL_SCHEMA_V1.into(),
@@ -418,6 +503,14 @@ pub fn install(request: InstallRequest) -> io::Result<Value> {
&journal.new_definition,
)?;
task::set_autostart(&native, request.autostart)?;
+ if let Some(source) = &recovery_root {
+ crate::RetainedRecoveryPackage::capture(
+ &layout.storage_root(),
+ source,
+ &journal.new_marker.install_root.join("hirouted.exe"),
+ )?
+ .store()?;
+ }
journal.commit(&layout)?;
journal.finish(&layout)
})();
@@ -430,19 +523,7 @@ pub fn install(request: InstallRequest) -> io::Result<Value> {
}
return Err(error);
}
- if request.console_loopback {
- ConsoleListenerStore::new(layout.gateway_config_root())
- .configure(ConsoleListenerDesiredV1::loopback())
- .map_err(|_| invalid())?;
- }
- let cleanup = if request.defer_package_cleanup {
- None
- } else {
- Some(PackageCleanup::best_effort(cleanup_locked(&layout)))
- };
- Ok(
- json!({"schema":"hiroute.windows-install-result/v1","installed":true,"version":package.version,"manager":"task","cli":layout.home.join(".local/bin/hiroute.exe"),"started":false,"package_cleanup":cleanup}),
- )
+ repair::finish(&layout, &package, &request)
}
pub fn uninstall(
request: UninstallRequest,
diff --git a/crates/host-runtime/src/standalone_install/windows/repair.rs b/crates/host-runtime/src/standalone_install/windows/repair.rs
new file mode 100644
index 00000000..1e952b66
--- /dev/null
+++ b/crates/host-runtime/src/standalone_install/windows/repair.rs
@@ -0,0 +1,52 @@
+//! Resume only the accepted current package after storage may have changed.
+use super::*;
+
+pub(super) fn resume(
+ mut journal: Journal,
+ package: &Package,
+ layout: &StandaloneLayout,
+ host: &mut NativeHost<'_>,
+ autostart: bool,
+) -> io::Result<()> {
+ let root = layout
+ .home
+ .join(".local/lib/hiroute")
+ .join(package.directory_name());
+ let native = Definition::new(Manager::Task, root.join("hirouted.exe"))?;
+ let installed = Package::read(&root)?;
+ installed.verify_directory(&root)?;
+ if journal.new_marker.install_root != root
+ || journal.new_marker.version != package.version
+ || journal.new_marker.target != package.target
+ || journal.new_marker.cpa_sha256.as_deref() != Some(package.cpa_digest())
+ || serde_json::to_value(&installed).map_err(|_| invalid())?
+ != serde_json::to_value(package).map_err(|_| invalid())?
+ || journal.new_definition != serde_json::to_value(&native).map_err(|_| invalid())?
+ {
+ return Err(io::Error::other("INSTALL_CURRENT_REPAIR_REQUIRED"));
+ }
+ journal.reapply_install(layout, host)?;
+ task::set_autostart(&native, autostart)?;
+ journal.commit(layout)?;
+ journal.finish(layout)
+}
+
+pub(super) fn finish(
+ layout: &StandaloneLayout,
+ package: &Package,
+ request: &InstallRequest,
+) -> io::Result<Value> {
+ if request.console_loopback {
+ ConsoleListenerStore::new(layout.gateway_config_root())
+ .configure(ConsoleListenerDesiredV1::loopback())
+ .map_err(|_| invalid())?;
+ }
+ let cleanup = if request.defer_package_cleanup {
+ None
+ } else {
+ Some(PackageCleanup::best_effort(cleanup_locked(layout)))
+ };
+ Ok(
+ json!({"schema":"hiroute.windows-install-result/v1","installed":true,"version":package.version,"manager":"task","cli":layout.home.join(".local/bin/hiroute.exe"),"started":false,"package_cleanup":cleanup}),
+ )
+}
diff --git a/crates/host-runtime/src/standalone_install/windows/space.rs b/crates/host-runtime/src/standalone_install/windows/space.rs
new file mode 100644
index 00000000..b01b6a40
--- /dev/null
+++ b/crates/host-runtime/src/standalone_install/windows/space.rs
@@ -0,0 +1,78 @@
+//! Account for simultaneous installation allocations on their actual volumes.
+use super::*;
+use std::collections::BTreeMap;
+
+#[derive(Debug, thiserror::Error)]
+#[error(
+ "UPGRADE_INSUFFICIENT_SPACE: the volume at {location} needs at least {required_bytes} free bytes; {available_bytes} are available. Keep history and recovery packages, free unrelated files, then retry. / 此位置所在磁盘空间不足;请保留历史和恢复包,释放无关文件后再试。",
+ location = .volume.display()
+)]
+pub struct ReplacementSpaceFailure {
+ pub volume: PathBuf,
+ pub required_bytes: u64,
+ pub available_bytes: u64,
+}
+
+fn existing(path: &std::path::Path) -> io::Result<PathBuf> {
+ let mut path = path;
+ loop {
+ match fs::symlink_metadata(path) {
+ Ok(_) => {
+ security::open_identity(path, true)?;
+ return Ok(path.to_owned());
+ }
+ Err(error) if error.kind() == io::ErrorKind::NotFound => {
+ path = path.parent().ok_or_else(invalid)?;
+ }
+ Err(error) => return Err(error),
+ }
+ }
+}
+
+pub fn preflight_desktop_space(
+ package: &Package,
+ shell_state: &std::path::Path,
+ shell_bytes: u64,
+ recovery_copy_bytes: u64,
+ storage: Option<&crate::UpgradePreflight>,
+) -> io::Result<()> {
+ let layout = layout()?;
+ let payload: u64 = package.files.values().map(|file| file.size).sum();
+ let mut allocations = vec![
+ (
+ shell_state.to_owned(),
+ payload
+ .saturating_add(shell_bytes)
+ .saturating_add(recovery_copy_bytes)
+ .saturating_add(64 * 1024 * 1024),
+ ),
+ (
+ layout.home.join(".local/lib/hiroute"),
+ payload.saturating_add(32 * 1024 * 1024),
+ ),
+ ];
+ if let Some(report) = storage
+ && report.required_bytes > 0
+ {
+ allocations.push((layout.storage_root(), report.required_bytes));
+ }
+ let mut volumes: BTreeMap<u32, (PathBuf, u64)> = BTreeMap::new();
+ for (path, bytes) in allocations {
+ let path = existing(&path)?;
+ let file = security::open_identity(&path, true)?;
+ let volume = security::file_identity(&file)?.0;
+ let entry = volumes.entry(volume).or_insert((path, 0));
+ entry.1 = entry.1.saturating_add(bytes);
+ }
+ for (_, (volume, required_bytes)) in volumes {
+ let available_bytes = fs2::available_space(&volume)?;
+ if available_bytes < required_bytes {
+ return Err(io::Error::other(ReplacementSpaceFailure {
+ volume,
+ required_bytes,
+ available_bytes,
+ }));
+ }
+ }
+ Ok(())
+}
diff --git a/crates/host-runtime/src/storage_recovery.rs b/crates/host-runtime/src/storage_recovery.rs
new file mode 100644
index 00000000..eee1c42e
--- /dev/null
+++ b/crates/host-runtime/src/storage_recovery.rs
@@ -0,0 +1,204 @@
+//! Bounded startup recovery facts. Only the storage owner assigns an action.
+use hiroute_platform::{durable, private_fs};
+use serde::{Deserialize, Serialize};
+use std::{
+ io::{self, Read},
+ path::Path,
+};
+
+pub const STORAGE_RECOVERY_SCHEMA: &str = "hiroute.storage-startup-recovery/v1";
+pub const STORAGE_RECOVERY_FILE: &str = "startup-recovery.json";
+mod admission;
+pub use admission::{StartupFailureBoundary, startup_failure_host_code};
+mod batch;
+
+#[derive(Clone, Debug, Deserialize, Serialize, Eq, PartialEq)]
+#[serde(deny_unknown_fields)]
+pub struct RecoverySpace {
+ pub required_bytes: u64,
+ pub available_bytes: u64,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Serialize, Eq, PartialEq)]
+#[serde(rename_all = "snake_case")]
+pub enum StorageRecoveryCause {
+ MissingPackage,
+ InvalidPackage,
+ InsufficientSpace,
+ AccessDenied,
+ Locked,
+ MissingKey,
+ UnsupportedFormat,
+ NamespaceUnavailable,
+ MigrationFailed,
+ UnknownState,
+}
+#[derive(Clone, Copy, Debug, Deserialize, Serialize, Eq, PartialEq)]
+#[serde(rename_all = "snake_case")]
+pub enum StorageRecoveryAction {
+ RetryCurrent,
+ ResumeCurrent,
+ RestoreCompleteGroup,
+ PreserveAndDiagnose,
+}
+#[derive(Clone, Debug, Deserialize, Serialize, Eq, PartialEq)]
+#[serde(deny_unknown_fields)]
+pub struct StorageRecovery {
+ pub schema: String,
+ pub cause: StorageRecoveryCause,
+ pub action: StorageRecoveryAction,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub backup_batch: Option<String>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub backup_name: Option<String>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub storage_space: Option<RecoverySpace>,
+}
+impl StorageRecovery {
+ pub fn new(cause: StorageRecoveryCause, action: StorageRecoveryAction) -> Self {
+ Self {
+ schema: STORAGE_RECOVERY_SCHEMA.into(),
+ cause,
+ action,
+ backup_batch: None,
+ backup_name: None,
+ storage_space: None,
+ }
+ }
+ pub fn read(storage: &Path) -> io::Result<Option<Self>> {
+ let mut file = match private_fs::open_private_file(&storage.join(STORAGE_RECOVERY_FILE)) {
+ Ok(file) => file,
+ Err(error) if error.kind() == io::ErrorKind::NotFound => return Ok(None),
+ Err(error) => return Err(error),
+ };
+ private_fs::verify_single_link(&file)?;
+ let mut bytes = Vec::new();
+ file.by_ref().take(4097).read_to_end(&mut bytes)?;
+ let record: Self = serde_json::from_slice(&bytes).map_err(io::Error::other)?;
+ if bytes.len() > 4096 || record.schema != STORAGE_RECOVERY_SCHEMA {
+ return Err(io::Error::other("STORAGE_RECOVERY_INVALID"));
+ }
+ if matches!(
+ record.action,
+ StorageRecoveryAction::ResumeCurrent | StorageRecoveryAction::RestoreCompleteGroup
+ ) {
+ batch::validate(storage, &record)?;
+ }
+ Ok(Some(record))
+ }
+ pub fn store(&self, storage: &Path) -> io::Result<()> {
+ durable::write_private_atomic(
+ &storage.join(STORAGE_RECOVERY_FILE),
+ &serde_json::to_vec(self)?,
+ )
+ }
+ pub fn clear(storage: &Path) -> io::Result<()> {
+ let path = storage.join(STORAGE_RECOVERY_FILE);
+ match private_fs::open_private_file(&path) {
+ Ok(file) => {
+ private_fs::verify_single_link(&file)?;
+ drop(file);
+ std::fs::remove_file(path)
+ }
+ Err(error) if error.kind() == io::ErrorKind::NotFound => Ok(()),
+ Err(error) => Err(error),
+ }
+ }
+ pub fn operator_guidance(&self) -> &'static str {
+ match (self.cause, self.action) {
+ (_, StorageRecoveryAction::ResumeCurrent) => {
+ "Keep all generations and reopen the current version to resume the identified original upgrade batch. Do not run an older program. If it cannot continue, preserve newer data separately and follow this batch's complete-group recovery guide."
+ }
+ (_, StorageRecoveryAction::RestoreCompleteGroup) => {
+ "Stop HiRoute and preserve newer data with its matching program separately. Follow the verified original batch's RECOVERY.md or recovery guide to restore the entire old group and matching complete program. Never restore individual databases or mix generations."
+ }
+ (StorageRecoveryCause::InsufficientSpace, _) => {
+ "Keep all data and recovery material. Free unrelated space on the storage volume, then retry the current version."
+ }
+ (StorageRecoveryCause::MissingPackage | StorageRecoveryCause::InvalidPackage, _) => {
+ "Keep all storage generations. Supply the verified complete matching old package through the supported installer or HIROUTE_RECOVERY_PACKAGE for the actual daemon process. Do not launch an old program against this data group. Follow the complete-group recovery guide if current-version recovery cannot continue."
+ }
+ (StorageRecoveryCause::AccessDenied | StorageRecoveryCause::Locked, _) => {
+ "Close other owned HiRoute instances and resolve the reported file access or ownership problem. Preserve all data and retry the current version. Do not change permissions recursively or delete recovery material."
+ }
+ (StorageRecoveryCause::NamespaceUnavailable, _) => {
+ "Keep all data and recovery material. The original history and recovery destination must be on the same filesystem and permit an atomic directory move. Correct the recorded locations or file-use problem before retrying the current version; do not copy or delete history to bypass this check."
+ }
+ _ => {
+ "Keep all storage generations, keys, packages and journals. Do not downgrade or delete data. Inspect startup diagnostics and the matching complete-group recovery guide; preserve newer data separately before restoration. Missing keys or source material may require support and cannot be repaired by repeated retries."
+ }
+ }
+ }
+}
+
+/// Installation rollback is insufficient evidence of storage downgrade safety.
+/// Refuse conservatively if any storage-upgrade authority is present or unreadable.
+pub fn storage_upgrade_started(storage: &Path) -> io::Result<bool> {
+ for name in [
+ "observation-source-backup.json",
+ "observation.upgrade.json",
+ "observation.pre-v5-source",
+ "observation.v5-target",
+ "migration-set",
+ ] {
+ match std::fs::symlink_metadata(storage.join(name)) {
+ Ok(_) => return Ok(true),
+ Err(error) if error.kind() == io::ErrorKind::NotFound => {}
+ Err(error) => return Err(error),
+ }
+ }
+ let Some(parent) = storage.parent() else {
+ return Err(io::Error::other("STORAGE_ROOT_INVALID"));
+ };
+ let Some(name) = storage.file_name() else {
+ return Err(io::Error::other("STORAGE_ROOT_INVALID"));
+ };
+ let mut backup = name.to_os_string();
+ backup.push(".upgrade-backups");
+ let backup = parent.join(backup);
+ let metadata = match std::fs::symlink_metadata(&backup) {
+ Ok(metadata) => Some(metadata),
+ Err(error) if error.kind() == io::ErrorKind::NotFound => None,
+ Err(error) => return Err(error),
+ };
+ if let Some(metadata) = metadata {
+ if metadata.file_type().is_symlink() || !metadata.is_dir() {
+ return Err(std::io::Error::other("STORAGE_BACKUP_ROOT_INVALID"));
+ }
+ // Unrecognized recovery material also prevents an unsafe program rollback.
+ if std::fs::read_dir(backup)?.next().is_some() {
+ return Ok(true);
+ }
+ }
+ Ok(false)
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ #[test]
+ fn retired_program_only_action_and_fields_are_not_a_recovery_contract() {
+ let mut value = serde_json::to_value(StorageRecovery::new(
+ StorageRecoveryCause::MissingPackage,
+ StorageRecoveryAction::PreserveAndDiagnose,
+ ))
+ .unwrap();
+ value["action"] = serde_json::json!("reinstall_original");
+ assert!(serde_json::from_value::<StorageRecovery>(value.clone()).is_err());
+ value["action"] = serde_json::json!("preserve_and_diagnose");
+ value["original_state_digest"] = serde_json::json!("unproduced proof");
+ assert!(serde_json::from_value::<StorageRecovery>(value).is_err());
+ }
+ #[test]
+ fn unknown_recovery_cannot_authorize_downgrade() {
+ for field in ["cause", "action"] {
+ let mut value = serde_json::to_value(StorageRecovery::new(
+ StorageRecoveryCause::MissingPackage,
+ StorageRecoveryAction::PreserveAndDiagnose,
+ ))
+ .unwrap();
+ value[field] = serde_json::json!("future_value");
+ assert!(serde_json::from_value::<StorageRecovery>(value).is_err());
+ }
+ }
+}
diff --git a/crates/host-runtime/src/storage_recovery/admission.rs b/crates/host-runtime/src/storage_recovery/admission.rs
new file mode 100644
index 00000000..00f15dc8
--- /dev/null
+++ b/crates/host-runtime/src/storage_recovery/admission.rs
@@ -0,0 +1,463 @@
+//! Early admission can fail before a recovery file can be safely written.
+//! Diagnostic facts here can explain a cause, never authorize data operations.
+use super::*;
+use hiroute_diagnostics::{
+ event::{DiagnosticEvent, ProcessRole, StartupFailureCode, StartupOutcome},
+ files::{CURRENT_LOG_FILE, FileSafetyError, PrivateDir, role_dir_name},
+ identity::BootId,
+ record::DiagnosticRecordV1,
+};
+
+/// A read-only watermark captured before asking the manager to start a service.
+/// Unreadable or incomplete diagnostics cannot establish a fresh failure.
+pub struct StartupFailureBoundary {
+ // None is untrusted/unreadable; Some(None) is verified absence or an empty log.
+ observed: Option<Option<(BootId, u64)>>,
+}
+impl StartupFailureBoundary {
+ pub fn capture(diagnostics: &Path) -> Self {
+ let observed = match diagnostic_tail(diagnostics) {
+ Ok(bytes) if bytes.is_empty() => Some(None),
+ Ok(bytes) if bytes.ends_with(b"\n") => bytes
+ .split(|byte| *byte == b'\n')
+ .rev()
+ .find(|line| !line.is_empty())
+ .and_then(|line| serde_json::from_slice::<DiagnosticRecordV1>(line).ok())
+ .map(|record| Some((record.boot_id, record.sequence))),
+ Err(FileSafetyError::NotFound)
+ | Err(FileSafetyError::Io {
+ kind: io::ErrorKind::NotFound,
+ ..
+ }) => Some(None),
+ _ => None,
+ };
+ Self { observed }
+ }
+
+ pub fn read_failure(
+ &self,
+ storage: &Path,
+ diagnostics: &Path,
+ ) -> Option<(&'static str, Option<StorageRecovery>)> {
+ let previous = self.observed?;
+ let (record, code) = failed_startup(diagnostics)?;
+ if previous
+ .is_some_and(|(boot, sequence)| boot == record.boot_id && record.sequence <= sequence)
+ {
+ return None;
+ }
+ Some((
+ startup_failure_host_code(code),
+ StorageRecovery::for_failure_code(storage, code),
+ ))
+ }
+}
+
+impl StorageRecovery {
+ pub fn read_failed_startup_code(diagnostics: &Path) -> Option<&'static str> {
+ failed_startup_code(diagnostics).map(startup_failure_host_code)
+ }
+ pub fn from_admission_code(code: StartupFailureCode) -> Option<Self> {
+ let cause = match code {
+ StartupFailureCode::StorageUnavailable => StorageRecoveryCause::UnknownState,
+ StartupFailureCode::StorageAccessDenied => StorageRecoveryCause::AccessDenied,
+ StartupFailureCode::StorageLocked => StorageRecoveryCause::Locked,
+ StartupFailureCode::StorageKeyUnavailable => StorageRecoveryCause::MissingKey,
+ StartupFailureCode::UpgradeSourceUnsupported => StorageRecoveryCause::UnsupportedFormat,
+ _ => return None,
+ };
+ let action = if matches!(
+ cause,
+ StorageRecoveryCause::Locked | StorageRecoveryCause::AccessDenied
+ ) {
+ StorageRecoveryAction::RetryCurrent
+ } else {
+ StorageRecoveryAction::PreserveAndDiagnose
+ };
+ Some(Self::new(cause, action))
+ }
+
+ pub fn read_for_admission_failure(
+ code: StartupFailureCode,
+ storage: Option<&Path>,
+ ) -> Option<Self> {
+ Some(Self::from_admission_code(code)?.with_verified_restore(storage))
+ }
+
+ fn with_verified_restore(self, storage: Option<&Path>) -> Self {
+ // The current diagnostic supplies only the cause. Whole-group restore
+ // authority still comes from revalidating the storage owner's exact
+ // original batch. Never borrow program-only reinstall or resume advice.
+ if matches!(
+ self.cause,
+ StorageRecoveryCause::MissingKey
+ | StorageRecoveryCause::UnsupportedFormat
+ | StorageRecoveryCause::UnknownState
+ ) && let Some(storage) = storage
+ && let Ok(Some(record)) = Self::read(storage)
+ && record.cause == self.cause
+ && record.action == StorageRecoveryAction::RestoreCompleteGroup
+ {
+ return record;
+ }
+ self
+ }
+
+ /// Use only on an already failed startup surface. Prefer this attempt's
+ /// diagnostic admission failure over a report left by an earlier writer.
+ /// A log record never grants reinstall, resume or restore authority.
+ pub fn read_for_failed_startup(storage: &Path, diagnostics: &Path) -> Option<Self> {
+ if let Some(code) = failed_startup_code(diagnostics) {
+ return Self::for_failure_code(storage, code);
+ }
+ Self::read_report(storage)
+ }
+
+ fn for_failure_code(storage: &Path, code: StartupFailureCode) -> Option<Self> {
+ if let Some(report) = Self::from_admission_code(code) {
+ return Some(report.with_verified_restore(Some(storage)));
+ }
+ (code == StartupFailureCode::UpgradeStorageFailed)
+ .then(|| Self::read_report(storage))
+ .flatten()
+ }
+
+ fn read_report(storage: &Path) -> Option<Self> {
+ match Self::read(storage) {
+ Ok(report) => report,
+ Err(error) => Some(Self::new(
+ if error.kind() == io::ErrorKind::PermissionDenied {
+ StorageRecoveryCause::AccessDenied
+ } else {
+ StorageRecoveryCause::UnknownState
+ },
+ StorageRecoveryAction::PreserveAndDiagnose,
+ )),
+ }
+ }
+}
+
+fn failed_startup_code(root: &Path) -> Option<StartupFailureCode> {
+ failed_startup(root).map(|(_, code)| code)
+}
+
+fn diagnostic_tail(root: &Path) -> Result<Vec<u8>, FileSafetyError> {
+ let root = PrivateDir::open_existing(root)?;
+ root.recheck_identity()?;
+ let role = PrivateDir::open_existing(&root.path().join(role_dir_name(ProcessRole::Daemon)))?;
+ root.recheck_identity()?;
+ let Some(mut file) = role.open_read(CURRENT_LOG_FILE)? else {
+ return Ok(Vec::new());
+ };
+ file.recheck()?;
+ let bytes = file.read_tail(64 * 1024)?;
+ file.recheck()?;
+ Ok(bytes)
+}
+
+fn failed_startup(root: &Path) -> Option<(DiagnosticRecordV1, StartupFailureCode)> {
+ let bytes = diagnostic_tail(root).ok()?;
+ if !bytes.ends_with(b"\n") {
+ return None;
+ }
+ // The newest startup/process event is the boundary. Unknown or unfinished
+ // attempts cannot borrow an older admission reason from rotated history.
+ for line in bytes
+ .split(|byte| *byte == b'\n')
+ .rev()
+ .filter(|line| !line.is_empty())
+ {
+ let value: serde_json::Value = serde_json::from_slice(line).ok()?;
+ let event = value.get("event")?;
+ if event.get("process_start").is_some() {
+ return None;
+ }
+ if event.get("startup_end").is_some() {
+ let record: DiagnosticRecordV1 = serde_json::from_value(value).ok()?;
+ if let DiagnosticEvent::StartupEnd(end) = &record.event
+ && let StartupOutcome::Failure { code } = end.outcome
+ {
+ return Some((record, code));
+ }
+ return None;
+ }
+ }
+ None
+}
+
+pub fn startup_failure_host_code(code: StartupFailureCode) -> &'static str {
+ match code {
+ StartupFailureCode::StorageUnavailable => "DAEMON_STORAGE_UNREADABLE",
+ StartupFailureCode::StorageAccessDenied => "DAEMON_STORAGE_ACCESS_DENIED",
+ StartupFailureCode::StorageLocked => "DAEMON_STORAGE_LOCKED",
+ StartupFailureCode::StorageKeyUnavailable => "DAEMON_STORAGE_KEY_UNAVAILABLE",
+ StartupFailureCode::UpgradeSourceUnsupported => "DAEMON_UPGRADE_SOURCE_UNSUPPORTED",
+ StartupFailureCode::UpgradeStorageFailed => "DAEMON_UPGRADE_STORAGE_FAILED",
+ StartupFailureCode::ReleaseFactsInvalid => "DAEMON_RELEASE_INVALID",
+ StartupFailureCode::DependencyUnavailable => "DAEMON_DEPENDENCY_UNAVAILABLE",
+ StartupFailureCode::GatewayUnavailable => "DAEMON_GATEWAY_UNAVAILABLE",
+ StartupFailureCode::ControlUnavailable => "DAEMON_CONTROL_UNAVAILABLE",
+ StartupFailureCode::Cancelled => "DAEMON_START_CANCELLED",
+ StartupFailureCode::InvalidConfiguration
+ | StartupFailureCode::WorkerRejected
+ | StartupFailureCode::ReadyChannelFailed
+ | StartupFailureCode::Internal => "DAEMON_START_FAILED",
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use hiroute_diagnostics::{Component, DiagnosticRuntime, RuntimeConfig, event::StartupEnd};
+ #[test]
+ fn boundary_requires_a_new_failure_and_rejects_incomplete_or_unreadable_attempts() {
+ let directory = tempfile::tempdir().unwrap();
+ let diagnostics = directory.path().join("diagnostics");
+ let emit = |outcome| {
+ let runtime = DiagnosticRuntime::start(RuntimeConfig {
+ root: diagnostics.clone(),
+ role: ProcessRole::Daemon,
+ component: Component::Daemon,
+ parent_session_id: None,
+ level_override: None,
+ });
+ if let Some(outcome) = outcome {
+ runtime.emit(DiagnosticEvent::StartupEnd(StartupEnd {
+ outcome,
+ elapsed_ms: 1,
+ }));
+ }
+ runtime.shutdown();
+ };
+ let first_attempt = StartupFailureBoundary::capture(&diagnostics);
+ emit(Some(StartupOutcome::Failure {
+ code: StartupFailureCode::StorageLocked,
+ }));
+ let (code, report) = first_attempt
+ .read_failure(directory.path(), &diagnostics)
+ .unwrap();
+ assert_eq!(code, "DAEMON_STORAGE_LOCKED");
+ assert_eq!(report.unwrap().action, StorageRecoveryAction::RetryCurrent);
+ let boundary = StartupFailureBoundary::capture(&diagnostics);
+ assert!(
+ boundary
+ .read_failure(directory.path(), &diagnostics)
+ .is_none()
+ );
+ emit(Some(StartupOutcome::Failure {
+ code: StartupFailureCode::GatewayUnavailable,
+ }));
+ let (code, report) = boundary
+ .read_failure(directory.path(), &diagnostics)
+ .unwrap();
+ assert_eq!(code, "DAEMON_GATEWAY_UNAVAILABLE");
+ assert!(report.is_none());
+ emit(Some(StartupOutcome::Success));
+ assert!(
+ boundary
+ .read_failure(directory.path(), &diagnostics)
+ .is_none()
+ );
+ emit(None);
+ assert!(
+ boundary
+ .read_failure(directory.path(), &diagnostics)
+ .is_none()
+ );
+ let log = diagnostics.join("daemon").join(CURRENT_LOG_FILE);
+ std::fs::write(&log, b"incomplete record").unwrap();
+ let unknown = StartupFailureBoundary::capture(&diagnostics);
+ emit(Some(StartupOutcome::Failure {
+ code: StartupFailureCode::StorageLocked,
+ }));
+ assert!(
+ unknown
+ .read_failure(directory.path(), &diagnostics)
+ .is_none()
+ );
+ }
+
+ #[test]
+ fn boundary_accepts_completion_of_the_observed_boot_without_reusing_its_old_failure() {
+ let directory = tempfile::tempdir().unwrap();
+ let diagnostics = directory.path().join("diagnostics");
+ let runtime = DiagnosticRuntime::start(RuntimeConfig {
+ root: diagnostics.clone(),
+ role: ProcessRole::Daemon,
+ component: Component::Daemon,
+ parent_session_id: None,
+ level_override: None,
+ });
+ runtime.emit(DiagnosticEvent::StartupEnd(StartupEnd {
+ outcome: StartupOutcome::Failure {
+ code: StartupFailureCode::StorageLocked,
+ },
+ elapsed_ms: 1,
+ }));
+ runtime.shutdown();
+ let log = diagnostics.join("daemon").join(CURRENT_LOG_FILE);
+ let complete = std::fs::read(&log).unwrap();
+ let start = complete
+ .split(|byte| *byte == b'\n')
+ .find(|line| {
+ serde_json::from_slice::<DiagnosticRecordV1>(line)
+ .is_ok_and(|r| matches!(r.event, DiagnosticEvent::ProcessStart(_)))
+ })
+ .unwrap();
+ std::fs::write(&log, [start, b"\n"].concat()).unwrap();
+ let boundary = StartupFailureBoundary::capture(&diagnostics);
+ std::fs::write(&log, &complete).unwrap();
+ let (code, report) = boundary
+ .read_failure(directory.path(), &diagnostics)
+ .unwrap();
+ assert_eq!(code, "DAEMON_STORAGE_LOCKED");
+ assert_eq!(report.unwrap().action, StorageRecoveryAction::RetryCurrent);
+ let after = StartupFailureBoundary::capture(&diagnostics);
+ assert!(after.read_failure(directory.path(), &diagnostics).is_none());
+ }
+
+ #[test]
+ fn current_non_storage_and_unknown_failures_cannot_borrow_an_old_storage_report() {
+ for code in [
+ StartupFailureCode::DependencyUnavailable,
+ StartupFailureCode::GatewayUnavailable,
+ StartupFailureCode::InvalidConfiguration,
+ StartupFailureCode::StorageUnavailable,
+ StartupFailureCode::StorageLocked,
+ ] {
+ let directory = tempfile::tempdir().unwrap();
+ let storage = directory.path();
+ let previous = StorageRecovery::new(
+ StorageRecoveryCause::MissingPackage,
+ StorageRecoveryAction::PreserveAndDiagnose,
+ );
+ previous.store(storage).unwrap();
+ assert_eq!(
+ StorageRecovery::read(storage).unwrap(),
+ Some(previous.clone())
+ );
+ let diagnostics = storage.join("diagnostics");
+ let runtime = DiagnosticRuntime::start(RuntimeConfig {
+ root: diagnostics.clone(),
+ role: ProcessRole::Daemon,
+ component: Component::Daemon,
+ parent_session_id: None,
+ level_override: None,
+ });
+ runtime.emit(DiagnosticEvent::StartupEnd(StartupEnd {
+ outcome: StartupOutcome::Failure { code },
+ elapsed_ms: 1,
+ }));
+ runtime.shutdown();
+ let report = StorageRecovery::read_for_failed_startup(storage, &diagnostics);
+ match code {
+ StartupFailureCode::StorageUnavailable => assert_eq!(
+ report,
+ Some(StorageRecovery::new(
+ StorageRecoveryCause::UnknownState,
+ StorageRecoveryAction::PreserveAndDiagnose,
+ ))
+ ),
+ StartupFailureCode::StorageLocked => assert_eq!(
+ report,
+ Some(StorageRecovery::new(
+ StorageRecoveryCause::Locked,
+ StorageRecoveryAction::RetryCurrent,
+ ))
+ ),
+ _ => assert!(report.is_none()),
+ }
+ assert_eq!(StorageRecovery::read(storage).unwrap(), Some(previous));
+ }
+ }
+
+ #[test]
+ fn latest_failed_startup_code_preserves_non_storage_causes_and_stops_at_a_healthy_boot() {
+ for (code, expected) in [
+ (
+ StartupFailureCode::DependencyUnavailable,
+ "DAEMON_DEPENDENCY_UNAVAILABLE",
+ ),
+ (
+ StartupFailureCode::GatewayUnavailable,
+ "DAEMON_GATEWAY_UNAVAILABLE",
+ ),
+ (StartupFailureCode::StorageLocked, "DAEMON_STORAGE_LOCKED"),
+ ] {
+ let directory = tempfile::tempdir().unwrap();
+ let root = directory.path().join("diagnostics");
+ let config = || RuntimeConfig {
+ root: root.clone(),
+ role: ProcessRole::Daemon,
+ component: Component::Daemon,
+ parent_session_id: None,
+ level_override: None,
+ };
+ let runtime = DiagnosticRuntime::start(config());
+ runtime.emit(DiagnosticEvent::StartupEnd(StartupEnd {
+ outcome: StartupOutcome::Failure { code },
+ elapsed_ms: 1,
+ }));
+ runtime.shutdown();
+ assert_eq!(
+ StorageRecovery::read_failed_startup_code(&root),
+ Some(expected)
+ );
+ let runtime = DiagnosticRuntime::start(config());
+ runtime.emit(DiagnosticEvent::StartupEnd(StartupEnd {
+ outcome: StartupOutcome::Success,
+ elapsed_ms: 1,
+ }));
+ runtime.shutdown();
+ assert_eq!(StorageRecovery::read_failed_startup_code(&root), None);
+ }
+ }
+ #[test]
+ fn early_admission_remains_actionable_without_writing_or_trusting_storage() {
+ for (code, cause) in [
+ (
+ StartupFailureCode::StorageLocked,
+ StorageRecoveryCause::Locked,
+ ),
+ (
+ StartupFailureCode::StorageAccessDenied,
+ StorageRecoveryCause::AccessDenied,
+ ),
+ (
+ StartupFailureCode::StorageKeyUnavailable,
+ StorageRecoveryCause::MissingKey,
+ ),
+ ] {
+ let directory = tempfile::tempdir().unwrap();
+ let diagnostics = directory.path().join("diagnostics");
+ let runtime = DiagnosticRuntime::start(RuntimeConfig {
+ root: diagnostics.clone(),
+ role: ProcessRole::Daemon,
+ component: Component::Daemon,
+ parent_session_id: None,
+ level_override: None,
+ });
+ runtime.emit(DiagnosticEvent::StartupEnd(StartupEnd {
+ outcome: StartupOutcome::Failure { code },
+ elapsed_ms: 1,
+ }));
+ runtime.shutdown();
+ let storage = directory.path().join("inaccessible-storage");
+ let report = StorageRecovery::read_for_failed_startup(&storage, &diagnostics).unwrap();
+ assert_eq!(report.cause, cause);
+ assert_eq!(
+ report.action,
+ if matches!(
+ cause,
+ StorageRecoveryCause::Locked | StorageRecoveryCause::AccessDenied
+ ) {
+ StorageRecoveryAction::RetryCurrent
+ } else {
+ StorageRecoveryAction::PreserveAndDiagnose
+ }
+ );
+ assert_eq!(report.backup_batch, None);
+ assert!(!storage.exists());
+ }
+ }
+}
diff --git a/crates/host-runtime/src/storage_recovery/batch.rs b/crates/host-runtime/src/storage_recovery/batch.rs
new file mode 100644
index 00000000..78df3c69
--- /dev/null
+++ b/crates/host-runtime/src/storage_recovery/batch.rs
@@ -0,0 +1,290 @@
+//! Revoke derived UI advice when its original batch or essential material changed.
+//! The storage owner still performs full admission before resume or restoration.
+use super::*;
+use serde_json::Value;
+use sha2::{Digest, Sha256};
+use std::path::Component;
+
+fn invalid() -> io::Error {
+ io::Error::other("STORAGE_RECOVERY_STALE")
+}
+fn json(path: &Path, limit: u64) -> io::Result<Value> {
+ let mut file = private_fs::open_private_file(path)?;
+ private_fs::verify_single_link(&file)?;
+ let mut bytes = Vec::new();
+ file.by_ref().take(limit + 1).read_to_end(&mut bytes)?;
+ if bytes.len() as u64 > limit {
+ return Err(invalid());
+ }
+ serde_json::from_slice(&bytes).map_err(io::Error::other)
+}
+fn portable(s: &str) -> bool {
+ !s.is_empty()
+ && s.len() <= 128
+ && !s.contains("..")
+ && s.bytes()
+ .all(|b| b.is_ascii_alphanumeric() || b"-_.".contains(&b))
+}
+pub(super) fn validate(storage: &Path, record: &StorageRecovery) -> io::Result<()> {
+ let id = record
+ .backup_batch
+ .as_deref()
+ .filter(|s| portable(s))
+ .ok_or_else(invalid)?;
+ let name = record
+ .backup_name
+ .as_deref()
+ .filter(|s| portable(s))
+ .ok_or_else(invalid)?;
+ let link = json(&storage.join("observation-source-backup.json"), 16 * 1024)?;
+ let linked_name = link["backup_name"]
+ .as_str()
+ .filter(|s| portable(s))
+ .ok_or_else(invalid)?;
+ if link["schema"] != 1
+ || link["set_id"] != id
+ || (name != linked_name && name != format!("migration-set.{id}"))
+ {
+ return Err(invalid());
+ }
+ let mut backup = storage.file_name().ok_or_else(invalid)?.to_os_string();
+ backup.push(".upgrade-backups");
+ let batch = storage
+ .parent()
+ .ok_or_else(invalid)?
+ .join(backup)
+ .join(name);
+ let _batch =
+ hiroute_diagnostics::files::PrivateDir::open_existing(&batch).map_err(|_| invalid())?;
+ let metadata = json(&batch.join("backup-set.manifest.json"), 64 * 1024)?;
+ if metadata["schema"] != "hiroute.sqlite-backup-set/v2" || metadata["set_id"] != id {
+ return Err(invalid());
+ }
+ let source = batch.join("source");
+ let _source =
+ hiroute_diagnostics::files::PrivateDir::open_existing(&source).map_err(|_| invalid())?;
+ let manifest = json(&source.join("source-backup.json"), 1024 * 1024)?;
+ if manifest["schema"] != "hiroute.upgrade-source-backup/v2"
+ || manifest["complete"] != true
+ || manifest["source_info"]["batch_id"] != id
+ {
+ return Err(invalid());
+ }
+ // Check only the explicit copied-material inventory. Historical Observation
+ // content is intentionally absent from this manifest and never traversed.
+ let files = manifest["files"]
+ .as_object()
+ .filter(|f| !f.is_empty() && f.len() <= 10_000)
+ .ok_or_else(invalid)?;
+ for (name, expected) in files {
+ if name.contains(['\\', ':'])
+ || !Path::new(name)
+ .components()
+ .all(|c| matches!(c, Component::Normal(_)))
+ {
+ return Err(invalid());
+ }
+ let path = source.join(name);
+ let _parent = hiroute_diagnostics::files::PrivateDir::open_existing(
+ path.parent().ok_or_else(invalid)?,
+ )
+ .map_err(|_| invalid())?;
+ let mut file = private_fs::open_private_file(&path)?;
+ private_fs::verify_single_link(&file)?;
+ let expected = expected.as_str().ok_or_else(invalid)?;
+ let mut digest = Sha256::new();
+ let mut buffer = [0; 64 * 1024];
+ loop {
+ let count = file.read(&mut buffer)?;
+ if count == 0 {
+ break;
+ }
+ digest.update(&buffer[..count]);
+ }
+ if format!("sha256:{:x}", digest.finalize()) != expected {
+ return Err(invalid());
+ }
+ }
+ for name in [
+ "storage/live/control.db",
+ "storage/live/runtime.db",
+ "storage/live/secrets.db",
+ "storage/master-key",
+ "storage/observation-hmac-key",
+ ] {
+ if !files.contains_key(name) {
+ return Err(invalid());
+ }
+ }
+ if !files
+ .keys()
+ .any(|name| name.starts_with("recovery-package/"))
+ {
+ return Err(invalid());
+ }
+ let history = source.join("storage/observation");
+ let _history =
+ hiroute_diagnostics::files::PrivateDir::open_existing(&history).map_err(|_| invalid())?;
+ #[cfg(unix)]
+ let identity = {
+ use std::os::unix::fs::MetadataExt;
+ let m = std::fs::symlink_metadata(&history)?;
+ [m.dev(), m.ino()]
+ };
+ #[cfg(windows)]
+ let identity = {
+ let f = hiroute_platform::windows::security::open_identity(&history, true)?;
+ let (volume, index) = hiroute_platform::windows::security::file_identity(&f)?;
+ [u64::from(volume), index]
+ };
+ if manifest["sealed_observation"]["identity"] != serde_json::json!(identity) {
+ return Err(invalid());
+ }
+ Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ #[test]
+ fn advice_is_bound_to_the_original_batch_and_essential_material_without_history_scan() {
+ let temp = tempfile::tempdir().unwrap();
+ let storage = temp.path().join("storage");
+ let batch = temp.path().join("storage.upgrade-backups/migration-set");
+ let source = batch.join("source");
+ let history = source.join("storage/observation");
+ for dir in [
+ &storage,
+ &history,
+ &source.join("storage/live"),
+ &source.join("recovery-package"),
+ ] {
+ private_fs::prepare_storage_directory(dir).unwrap();
+ }
+ let mut files = serde_json::Map::new();
+ for name in [
+ "storage/live/control.db",
+ "storage/live/runtime.db",
+ "storage/live/secrets.db",
+ "storage/master-key",
+ "storage/observation-hmac-key",
+ "recovery-package/hirouted",
+ ] {
+ durable::write_private_new(&source.join(name), b"retained source").unwrap();
+ files.insert(
+ name.into(),
+ serde_json::json!(format!("sha256:{:x}", Sha256::digest(b"retained source"))),
+ );
+ }
+ #[cfg(unix)]
+ let identity = {
+ use std::os::unix::fs::MetadataExt;
+ let m = std::fs::symlink_metadata(&history).unwrap();
+ [m.dev(), m.ino()]
+ };
+ #[cfg(windows)]
+ let identity = {
+ let f = hiroute_platform::windows::security::open_identity(&history, true).unwrap();
+ let (volume, index) = hiroute_platform::windows::security::file_identity(&f).unwrap();
+ [u64::from(volume), index]
+ };
+ #[cfg(unix)]
+ std::os::unix::fs::symlink(
+ temp.path().join("missing-history-target"),
+ history.join("never-follow"),
+ )
+ .unwrap();
+ let write = |path: &Path, value: Value| {
+ durable::write_private_atomic(path, &serde_json::to_vec(&value).unwrap()).unwrap()
+ };
+ write(
+ &storage.join("observation-source-backup.json"),
+ serde_json::json!({"schema":1,"set_id":"set_original","backup_name":"migration-set"}),
+ );
+ write(
+ &batch.join("backup-set.manifest.json"),
+ serde_json::json!({"schema":"hiroute.sqlite-backup-set/v2","set_id":"set_original"}),
+ );
+ write(
+ &source.join("source-backup.json"),
+ serde_json::json!({"schema":"hiroute.upgrade-source-backup/v2","complete":true,"source_info":{"batch_id":"set_original"},"files":files,"sealed_observation":{"identity":identity}}),
+ );
+ let mut report = StorageRecovery::new(
+ StorageRecoveryCause::MigrationFailed,
+ StorageRecoveryAction::ResumeCurrent,
+ );
+ report.backup_batch = Some("set_original".into());
+ report.backup_name = Some("migration-set".into());
+ report.store(&storage).unwrap();
+ assert_eq!(
+ StorageRecovery::read(&storage).unwrap(),
+ Some(report.clone())
+ );
+ use hiroute_diagnostics::event::StartupFailureCode as Code;
+ for (code, cause) in [
+ (
+ Code::StorageKeyUnavailable,
+ StorageRecoveryCause::MissingKey,
+ ),
+ (
+ Code::UpgradeSourceUnsupported,
+ StorageRecoveryCause::UnsupportedFormat,
+ ),
+ ] {
+ let mut admitted = report.clone();
+ admitted.cause = cause;
+ admitted.action = StorageRecoveryAction::RestoreCompleteGroup;
+ admitted.store(&storage).unwrap();
+ assert_eq!(
+ StorageRecovery::read_for_admission_failure(code, Some(&storage)),
+ Some(admitted.clone())
+ );
+ let prerequisite =
+ StorageRecovery::read_for_admission_failure(Code::StorageLocked, Some(&storage))
+ .unwrap();
+ assert_eq!(prerequisite.action, StorageRecoveryAction::RetryCurrent);
+ assert!(
+ prerequisite.backup_batch.is_none(),
+ "file use cannot borrow a prior restore target"
+ );
+ admitted.action = StorageRecoveryAction::ResumeCurrent;
+ admitted.store(&storage).unwrap();
+ assert_eq!(
+ StorageRecovery::read_for_admission_failure(code, Some(&storage))
+ .unwrap()
+ .action,
+ StorageRecoveryAction::PreserveAndDiagnose,
+ "a diagnostic cannot grant resume"
+ );
+ admitted.action = StorageRecoveryAction::RestoreCompleteGroup;
+ admitted.store(&storage).unwrap();
+ std::fs::write(source.join("storage/master-key"), b"corrupted value").unwrap();
+ assert_eq!(
+ StorageRecovery::read_for_admission_failure(code, Some(&storage))
+ .unwrap()
+ .action,
+ StorageRecoveryAction::PreserveAndDiagnose,
+ "damaged retained material cannot grant restoration"
+ );
+ std::fs::write(source.join("storage/master-key"), b"retained source").unwrap();
+ }
+ report.store(&storage).unwrap();
+ // An extant file or unchanged length is insufficient: corruption of a
+ // retained key must revoke the otherwise correct batch's restore advice.
+ std::fs::write(source.join("storage/master-key"), b"corrupted value").unwrap();
+ assert!(StorageRecovery::read(&storage).is_err());
+ std::fs::write(source.join("storage/master-key"), b"retained source").unwrap();
+ assert_eq!(StorageRecovery::read(&storage).unwrap(), Some(report));
+ write(
+ &storage.join("observation-source-backup.json"),
+ serde_json::json!({"schema":1,"set_id":"set_foreign","backup_name":"migration-set"}),
+ );
+ assert!(StorageRecovery::read(&storage).is_err());
+ write(
+ &storage.join("observation-source-backup.json"),
+ serde_json::json!({"schema":1,"set_id":"set_original","backup_name":"migration-set"}),
+ );
+ std::fs::remove_file(source.join("storage/master-key")).unwrap();
+ assert!(StorageRecovery::read(&storage).is_err());
+ }
+}
diff --git a/crates/host-runtime/src/upgrade_preflight.rs b/crates/host-runtime/src/upgrade_preflight.rs
new file mode 100644
index 00000000..d6a42fea
--- /dev/null
+++ b/crates/host-runtime/src/upgrade_preflight.rs
@@ -0,0 +1,208 @@
+//! Read-only candidate preflight. It never starts the service or grants write authority.
+use crate::StorageRecovery;
+use serde::{Deserialize, Serialize};
+use std::{
+ io::Read,
+ path::Path,
+ process::{Command, Stdio},
+ time::{Duration, Instant},
+};
+#[derive(Debug, Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct UpgradePreflight {
+ pub schema: String,
+ pub history_cutover_required: bool,
+ pub required_bytes: u64,
+ pub available_bytes: u64,
+ pub recovery: Option<StorageRecovery>,
+}
+#[derive(Debug)]
+pub struct UpgradePreflightFailure {
+ pub code: &'static str,
+ pub recovery: Option<Box<StorageRecovery>>,
+}
+impl std::fmt::Display for UpgradePreflightFailure {
+ fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ formatter.write_str(self.code)?;
+ if let Some(recovery) = &self.recovery {
+ write!(formatter, ": {}", recovery.operator_guidance())?;
+ if let Some(space) = &recovery.storage_space {
+ write!(
+ formatter,
+ " Required: {} bytes; available: {} bytes.",
+ space.required_bytes, space.available_bytes
+ )?;
+ }
+ }
+ Ok(())
+ }
+}
+impl std::error::Error for UpgradePreflightFailure {}
+
+pub fn run_upgrade_preflight(
+ program: &Path,
+ storage: &Path,
+ package: &Path,
+) -> Result<UpgradePreflight, &'static str> {
+ checked_upgrade_preflight(program, storage, package).map_err(|failure| failure.code)
+}
+
+pub fn checked_upgrade_preflight(
+ program: &Path,
+ storage: &Path,
+ package: &Path,
+) -> Result<UpgradePreflight, UpgradePreflightFailure> {
+ let (success, report) =
+ transport(program, storage, package).map_err(|code| UpgradePreflightFailure {
+ code,
+ recovery: None,
+ })?;
+ if !success || report.recovery.is_some() {
+ let code = match report.recovery.as_ref().map(|recovery| recovery.cause) {
+ Some(crate::StorageRecoveryCause::InsufficientSpace) => "UPGRADE_INSUFFICIENT_SPACE",
+ Some(crate::StorageRecoveryCause::MissingKey) => "UPGRADE_KEY_UNAVAILABLE",
+ Some(crate::StorageRecoveryCause::MissingPackage) => "UPGRADE_RECOVERY_PACKAGE_MISSING",
+ Some(crate::StorageRecoveryCause::InvalidPackage) => "UPGRADE_RECOVERY_PACKAGE_INVALID",
+ _ => "UPGRADE_PREFLIGHT_REFUSED",
+ };
+ return Err(UpgradePreflightFailure {
+ code,
+ recovery: report.recovery.map(Box::new),
+ });
+ }
+ Ok(report)
+}
+
+fn transport(
+ program: &Path,
+ storage: &Path,
+ package: &Path,
+) -> Result<(bool, UpgradePreflight), &'static str> {
+ let mut command = Command::new(program);
+ command
+ .arg("--upgrade-preflight")
+ .arg("--storage-root")
+ .arg(storage)
+ .arg("--recovery-package")
+ .arg(package)
+ .stdin(Stdio::null())
+ .stdout(Stdio::piped())
+ .stderr(Stdio::null());
+ #[cfg(windows)]
+ {
+ use std::os::windows::process::CommandExt;
+ command.creation_flags(0x08000000);
+ }
+ let mut child = command
+ .spawn()
+ .map_err(|_| "UPGRADE_PREFLIGHT_UNAVAILABLE")?;
+ let deadline = Instant::now() + Duration::from_secs(15);
+ let status = loop {
+ match child.try_wait() {
+ Ok(Some(status)) => break status,
+ Ok(None) if Instant::now() < deadline => std::thread::sleep(Duration::from_millis(20)),
+ _ => {
+ let _ = child.kill();
+ let _ = child.wait();
+ return Err("UPGRADE_PREFLIGHT_UNAVAILABLE");
+ }
+ }
+ };
+ let mut bytes = Vec::new();
+ child
+ .stdout
+ .take()
+ .ok_or("UPGRADE_PREFLIGHT_INVALID")?
+ .take(16 * 1024 + 1)
+ .read_to_end(&mut bytes)
+ .map_err(|_| "UPGRADE_PREFLIGHT_INVALID")?;
+ if bytes.len() > 16 * 1024 {
+ return Err("UPGRADE_PREFLIGHT_INVALID");
+ }
+ let report: UpgradePreflight =
+ serde_json::from_slice(&bytes).map_err(|_| "UPGRADE_PREFLIGHT_UNAVAILABLE")?;
+ if report.schema != "hiroute.upgrade-preflight/v1" {
+ return Err("UPGRADE_PREFLIGHT_INVALID");
+ }
+ if let Some(recovery) = &report.recovery
+ && (recovery.schema != crate::STORAGE_RECOVERY_SCHEMA
+ || !matches!(
+ recovery.action,
+ crate::StorageRecoveryAction::PreserveAndDiagnose
+ | crate::StorageRecoveryAction::RetryCurrent
+ )
+ || recovery.backup_batch.is_some()
+ || recovery.backup_name.is_some())
+ {
+ // Provisional checks may explain prerequisites, but can never grant a
+ // current-batch resume, restoration or old-program launch authority.
+ return Err("UPGRADE_PREFLIGHT_INVALID");
+ }
+ Ok((status.success(), report))
+}
+
+#[cfg(all(test, unix))]
+mod tests {
+ use super::*;
+ use std::os::unix::fs::PermissionsExt;
+
+ #[test]
+ fn typed_preflight_failure_preserves_measured_recovery_facts_and_rejects_extra_fields() {
+ let directory = tempfile::tempdir().unwrap();
+ let program = directory.path().join("preflight");
+ let report = serde_json::json!({
+ "schema":"hiroute.upgrade-preflight/v1", "history_cutover_required":false,
+ "required_bytes":4096, "available_bytes":12,
+ "recovery":{
+ "schema":"hiroute.storage-startup-recovery/v1", "cause":"insufficient_space",
+ "action":"retry_current", "storage_space":{"required_bytes":4096,"available_bytes":12}
+ }
+ });
+ let write = |report: &serde_json::Value| {
+ std::fs::write(
+ &program,
+ format!("#!/bin/sh\ncat <<'REPORT'\n{report}\nREPORT\nexit 1\n"),
+ )
+ .unwrap();
+ std::fs::set_permissions(&program, std::fs::Permissions::from_mode(0o700)).unwrap();
+ };
+ write(&report);
+ let failure =
+ checked_upgrade_preflight(&program, directory.path(), directory.path()).unwrap_err();
+ assert_eq!(failure.code, "UPGRADE_INSUFFICIENT_SPACE");
+ assert_eq!(
+ failure
+ .recovery
+ .as_ref()
+ .unwrap()
+ .storage_space
+ .as_ref()
+ .unwrap()
+ .required_bytes,
+ 4096
+ );
+ assert!(failure.to_string().contains("4096 bytes"));
+ assert!(failure.to_string().contains("12 bytes"));
+ assert_eq!(
+ run_upgrade_preflight(&program, directory.path(), directory.path()).unwrap_err(),
+ "UPGRADE_INSUFFICIENT_SPACE"
+ );
+ let mut unknown = report;
+ unknown["arbitrary_native_error"] = "never expose raw native output".into();
+ write(&unknown);
+ let failure =
+ checked_upgrade_preflight(&program, directory.path(), directory.path()).unwrap_err();
+ assert!(failure.recovery.is_none());
+ assert!(!failure.to_string().contains("raw native output"));
+ unknown
+ .as_object_mut()
+ .unwrap()
+ .remove("arbitrary_native_error");
+ unknown["recovery"]["action"] = "resume_current".into();
+ write(&unknown);
+ let failure =
+ checked_upgrade_preflight(&program, directory.path(), directory.path()).unwrap_err();
+ assert_eq!(failure.code, "UPGRADE_PREFLIGHT_INVALID");
+ assert!(failure.recovery.is_none());
+ }
+}
diff --git a/crates/local-storage/src/backup/source_snapshot.rs b/crates/local-storage/src/backup/source_snapshot.rs
index 9e7002a7..1f78194f 100644
--- a/crates/local-storage/src/backup/source_snapshot.rs
+++ b/crates/local-storage/src/backup/source_snapshot.rs
@@ -3,6 +3,7 @@ use super::*;
use crate::migrations::{prepare_storage_root as prepare_owner_directory, validate_owner_file};
use serde_json::{Value, json};
use std::collections::BTreeMap;
+mod program_locations;
mod seal;
#[cfg(windows)]
use std::io::{Read, Write};
@@ -114,6 +115,7 @@ fn excluded(name: &str) -> bool {
) || name == "live"
|| name.starts_with("migration-set")
|| name == "startup.lock"
+ || name == hiroute_host_runtime::STORAGE_RECOVERY_FILE
|| name.ends_with(".pid")
|| name.ends_with(".sock")
}
@@ -141,7 +143,7 @@ pub(super) fn publish(
if options.preserve_observation_source && stage.join(MANIFEST).exists() {
return seal::finish(root, backup, &stage, metadata);
}
- preflight_space(root, backup, options)?;
+ preflight_space(root, Some(backup), options)?;
if stage.exists() {
// Never put a moved historical tree into a generic incomplete-copy path.
if stage.join("storage/observation").exists() {
@@ -232,7 +234,7 @@ pub(super) fn publish(
"本次可能转换核心数据库和 Observation 历史;该目录同时保存原始 Observation、密钥、原生恢复材料及其余自有持久状态。"
};
let text = format!(
- "# HiRoute 手工恢复\n\n备份批次 ID:{}\n\n备份源以本说明所在目录为准,目录改名或归档后仍从这里读取;不要使用其它批次。以下源文件路径均相对于本说明所在目录,目标路径为绝对位置。\n\n1. 完全退出 HiRoute,确认服务、CPA、任务与后台自动重启均已停止。\n2. 将 storage 目录 {} 改名保留;不要改名它的上级目录,备份仍保留在上述位置。备份之后的新数据必须与配套新版本单独保留,不能混入旧格式恢复。\n3. 将 storage/ 整个复制回 {},保留权限。不要逐库覆盖,不要遗留不配套的 WAL/SHM。再按以下源 → 目标路径复制额外文件:\n\n{}\n4. 按下面的完整 App 路径和身份覆盖安装旧包,启动后检查配置、Agent 接入及一次真实请求。\n\n{}\n\n{history}\n\n不要将此备份加入诊断导出。\n",
+ "# HiRoute 手工恢复\n\n备份批次 ID:{}\n\n备份源以本说明所在目录为准,目录改名或归档后仍从这里读取;不要使用其它批次。以下源文件路径均相对于本说明所在目录,目标路径为绝对位置。\n\n1. 完全退出 HiRoute,确认服务、CPA、任务与后台自动重启均已停止。\n2. 将 storage 目录 {} 改名保留;不要改名它的上级目录,备份仍保留在上述位置。备份之后的新数据必须与配套新版本单独保留,不能混入旧格式恢复。\n3. 将 storage/ 整个复制回 {},保留权限。不要逐库覆盖,不要遗留不配套的 WAL/SHM。再按以下源 → 目标路径复制额外文件:\n\n{}\n4. 确认完整旧组已还原后,使用下面记录的完整原版程序包。macOS 恢复完整 App;Linux/Windows 按平台安装指南恢复配套程序与服务注册。如存在 PROGRAM-LOCATIONS.md,先按其还原程序、资源和安装记录。启动后检查配置、Agent 接入及一次真实请求。\n\n{}\n\n{history}\n\n不要将此备份加入诊断导出。\n",
metadata["batch_id"]
.as_str()
.ok_or(LocalStorageError::InvalidData)?,
@@ -242,6 +244,21 @@ pub(super) fn publish(
package_identity
);
write_private(&stage.join("恢复说明.md"), text.as_bytes())?;
+ let english_package=options.recovery_package.as_ref().map(|p|format!("Original complete package: {}. The preserved copy is recovery-package/; exact file SHA-256 identities are recorded in source-backup.json.",p.display())).unwrap_or_else(||"Use the exact complete package that produced this backup. Do not substitute a version based only on a label.".into());
+ let english = format!(
+ "# HiRoute complete-group recovery\n\nBatch: {}\n\nUse this guide's containing directory as the source, including after archival. Never use another batch's source or package.\n\n1. Fully stop HiRoute, its daemon, CPA, tasks and automatic service restarts.\n2. Rename the current storage directory at {} and keep it with its matching newer program. Do not rename the parent containing this backup. Post-backup data must remain separate from the restored old group.\n3. Copy the complete storage/ directory back to {} preserving native permissions. Keep Control, Runtime, Secrets, all keys and Observation DB/WAL/SHM/content together. Never restore only activity.db or mix generations.\n4. Restore the auxiliary files below to their recorded original locations.\n{}\n5. The matching complete previous program is preserved in recovery-package/. For macOS restore the complete App, not individual binaries. For an installed standalone package, use its recorded PROGRAM-LOCATIONS.md instructions to restore the original program, resources and service registration before starting the old service. If no installed-location record exists, follow the matching platform installer guide using the exact preserved package identity; do not guess another release.\n6. Start the matching old program. Verify configuration, Agent access, old history where applicable, actual Control/Gateway readiness and a real request. A successful manager command alone does not establish recovery.\n\n{}\n\nOld Observation history was preserved by a same-filesystem directory transition without an eager full-content verification. Inspect original databases/content offline before restoring. Keep newer data separately. The protected source still occupies disk and is a local recovery point, not an independent disaster-recovery copy. Do not include private backups in diagnostic exports.\n",
+ metadata["batch_id"]
+ .as_str()
+ .ok_or(LocalStorageError::InvalidData)?,
+ root.display(),
+ root.display(),
+ extra_paths,
+ english_package
+ );
+ write_private(&stage.join("RECOVERY.md"), english.as_bytes())?;
+ if let Some(package) = &options.recovery_package {
+ program_locations::write(&stage, package)?;
+ }
let mut files = BTreeMap::new();
collect(&stage, &stage, &mut files, false)?;
let created = std::time::SystemTime::now()
@@ -288,11 +305,25 @@ pub(crate) fn publish_locator(backup: &Path, batch_id: &str) -> Result<(), Local
Ok(())
}
-fn preflight_space(
+pub(crate) fn preflight_space(
root: &Path,
- backup: &Path,
+ backup: Option<&Path>,
options: &crate::StorageStartupOptions,
-) -> Result<(), LocalStorageError> {
+) -> Result<u64, LocalStorageError> {
+ if options.preserve_observation_source {
+ // The final source will be published under this sibling backup root.
+ // Its parent already exists; no directories or history are written here.
+ let backup_root = crate::upgrade_backup_root(root)?;
+ let parent = backup_root.parent().ok_or(LocalStorageError::InvalidData)?;
+ let destination = match fs::symlink_metadata(parent) {
+ Ok(_) => parent,
+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
+ parent.parent().ok_or(LocalStorageError::InvalidData)?
+ }
+ Err(e) => return Err(e.into()),
+ };
+ seal::preflight(root, destination)?;
+ }
fn bytes(path: &Path) -> Result<u64, LocalStorageError> {
let meta = fs::symlink_metadata(path)?;
if meta.file_type().is_symlink() {
@@ -324,23 +355,47 @@ fn preflight_space(
}
}
for name in ["control.db", "runtime.db", "secrets.db"] {
- required = required.saturating_add(bytes(&backup.join(name))?);
+ let amount = if let Some(backup) = backup {
+ bytes(&backup.join(name))?
+ } else {
+ let live = root.join("live").join(name);
+ let wal = live.with_file_name(format!("{name}-wal"));
+ let wal_bytes = if wal.try_exists()? { bytes(&wal)? } else { 0 };
+ // The provisional check precedes both the coordinated SQL snapshot
+ // and its complete-source copy. Startup checks again after snapshot.
+ bytes(&live)?.saturating_add(wal_bytes).saturating_mul(2)
+ };
+ required = required.saturating_add(amount);
}
if let Some(package) = &options.recovery_package {
let meta = fs::symlink_metadata(package)?;
if !meta.is_dir()
|| meta.file_type().is_symlink()
- || package.canonicalize()?.starts_with(backup.canonicalize()?)
+ || (if let Some(backup) = backup {
+ package.canonicalize()?.starts_with(backup.canonicalize()?)
+ } else {
+ false
+ })
|| storage_root_conflict(package, root)?
{
return Err(LocalStorageError::InvalidData);
}
required = required.saturating_add(bytes(package)?);
}
- if fs2::available_space(root)? < required {
- return Err(LocalStorageError::InvalidData.at_upgrade_stage("Insufficient space for recovery material and startup headroom; preserve the source and free unrelated space before retrying"));
+ let available = fs2::available_space(root)?;
+ if available < required {
+ let mut recovery = hiroute_host_runtime::StorageRecovery::new(
+ hiroute_host_runtime::StorageRecoveryCause::InsufficientSpace,
+ hiroute_host_runtime::StorageRecoveryAction::RetryCurrent,
+ );
+ recovery.storage_space = Some(hiroute_host_runtime::RecoverySpace {
+ required_bytes: required,
+ available_bytes: available,
+ });
+ return Err(LocalStorageError::Recovery { recovery: Box::new(recovery),
+ source: Box::new(LocalStorageError::InvalidData.at_upgrade_stage("Insufficient space for recovery material and startup headroom; preserve the source and free unrelated space before retrying")) });
}
- Ok(())
+ Ok(required)
}
fn collect(
root: &Path,
diff --git a/crates/local-storage/src/backup/source_snapshot/program_locations.rs b/crates/local-storage/src/backup/source_snapshot/program_locations.rs
new file mode 100644
index 00000000..18718af9
--- /dev/null
+++ b/crates/local-storage/src/backup/source_snapshot/program_locations.rs
@@ -0,0 +1,75 @@
+//! Exact installed program/registration locations for the complete source's guide.
+use super::*;
+mod windows;
+
+pub(super) fn write(stage: &Path, package: &Path) -> Result<(), LocalStorageError> {
+ let locations = package.join("restore-locations.json");
+ if locations.exists() {
+ validate_owner_file(&locations)?;
+ if fs::metadata(&locations)?.len() > 16 * 1024 {
+ return Err(LocalStorageError::InvalidData);
+ }
+ let locations: Value = serde_json::from_slice(&fs::read(locations)?)
+ .map_err(|_| LocalStorageError::InvalidData)?;
+ if locations["schema"] == "hiroute.windows-desktop-restore/v1" {
+ return windows::write(stage, &locations);
+ }
+ if locations["schema"] != "hiroute.standalone-program-restore/v1" {
+ return Err(LocalStorageError::InvalidData);
+ }
+ let mut steps = String::from(
+ "# Standalone program locations / 独立安装原位置\n\nStop the service and restore the complete old storage group first. Copy the following retained directories/files, preserving permissions, then reload the native service manager and start the exact restored service. Do not run a newer installer over the restored old group. / 先停止服务并还原完整旧数据组,再保留权限复制下列目录和文件,重新加载服务管理器并启动配套旧服务。不要用新版安装器覆盖旧组。\n\n",
+ );
+ for name in ["program", "resources"] {
+ let target = locations[name]
+ .as_str()
+ .ok_or(LocalStorageError::InvalidData)?;
+ if !Path::new(target).is_absolute() {
+ return Err(LocalStorageError::InvalidData);
+ }
+ steps.push_str(&format!("- recovery-package/{name}/ → {target}\n"));
+ }
+ for (name, target) in locations["files"]
+ .as_object()
+ .ok_or(LocalStorageError::InvalidData)?
+ {
+ let target = target.as_str().ok_or(LocalStorageError::InvalidData)?;
+ if !name.starts_with("installation/")
+ || name.contains("..")
+ || !Path::new(target).is_absolute()
+ {
+ return Err(LocalStorageError::InvalidData);
+ }
+ steps.push_str(&format!("- recovery-package/{name} → {target}\n"));
+ }
+ if let Some(links) = locations.get("links") {
+ let links = links.as_object().ok_or(LocalStorageError::InvalidData)?;
+ if links.len() != 2 {
+ return Err(LocalStorageError::InvalidData);
+ }
+ steps.push_str("\nRecreate the following symbolic links after restoring the old directories. Replace only these installer-owned entries; preserve a foreign entry and seek support. / 还原旧目录后,重建以下符号链接。只替换这些安装器自有入口;遇到外来文件请保留并寻求支持。\n\n");
+ let program = Path::new(
+ locations["program"]
+ .as_str()
+ .ok_or(LocalStorageError::InvalidData)?,
+ );
+ for (link, target) in links {
+ let link = Path::new(link);
+ let target = Path::new(target.as_str().ok_or(LocalStorageError::InvalidData)?);
+ if !link.is_absolute()
+ || !matches!(
+ link.file_name().and_then(|n| n.to_str()),
+ Some("hiroute" | "hirouted")
+ )
+ || target
+ != program.join(link.file_name().ok_or(LocalStorageError::InvalidData)?)
+ {
+ return Err(LocalStorageError::InvalidData);
+ }
+ steps.push_str(&format!("- {} → {}\n", link.display(), target.display()));
+ }
+ }
+ write_private(&stage.join("PROGRAM-LOCATIONS.md"), steps.as_bytes())?;
+ }
+ Ok(())
+}
diff --git a/crates/local-storage/src/backup/source_snapshot/program_locations/windows.rs b/crates/local-storage/src/backup/source_snapshot/program_locations/windows.rs
new file mode 100644
index 00000000..6d1a8555
--- /dev/null
+++ b/crates/local-storage/src/backup/source_snapshot/program_locations/windows.rs
@@ -0,0 +1,125 @@
+use super::*;
+
+pub(super) fn write(stage: &Path, locations: &Value) -> Result<(), LocalStorageError> {
+ let locations: hiroute_host_runtime::WindowsDesktopRestore =
+ serde_json::from_value(locations.clone()).map_err(|_| LocalStorageError::InvalidData)?;
+ locations.validate()?;
+ if !stage
+ .join("recovery-package/installation/task.xml")
+ .is_file()
+ {
+ return Err(LocalStorageError::InvalidData);
+ }
+ let program = locations.program.display();
+ let cli = locations
+ .files
+ .values()
+ .find(|path| path.file_name().is_some_and(|name| name == "hiroute.exe"))
+ .ok_or(LocalStorageError::InvalidData)?
+ .display();
+ let task = &locations.task_name;
+ let mut text = format!(
+ r"# Windows program and Task recovery / Windows 程序与任务恢复
+
+Read RECOVERY.md or 恢复说明.md first. Use this exact batch and preserve the newer complete data with its matching installer/program separately. Work in the same ordinary Windows account; administrator access is not required.
+先阅读 RECOVERY.md 或恢复说明.md。使用本批次,将新版完整数据与配套安装器/程序另存;在同一个普通 Windows 账户中操作,无需管理员权限。
+
+1. Using the current installed CLI, run `hiroute service autostart disable --output json`, then `hiroute service stop --output json`. Fully quit Desktop and confirm its daemon and CPA have exited. Disable its Desktop login setting before quitting. In Task Scheduler, verify that the recorded `{task}` Task belongs to this account/current HiRoute installation, export it with the newer program, then delete only that stopped registration. Preserve the current program directories and HKCU HiRoute uninstall entry separately. Do not run the product uninstaller or delete user data.
+先用当前 CLI 关闭 Task 登录启动并停止服务,退出前也关闭桌面端的登录启动,完全退出后确认守护进程和 CPA 已结束;在任务计划程序中核对本说明记录的 Task 属于当前账户及 HiRoute 安装,将其导出并与新版程序另存,再仅删除这一已停止的注册。另存当前程序目录与当前账户的 HiRoute 卸载注册项,不要运行产品卸载程序或删除用户数据。
+
+If `hiroute` is not on PATH, invoke the installed entry at `{cli}` directly (PowerShell uses `&` before a quoted executable path). If the CLI is damaged, open Task Scheduler under this same account. Verify that the recorded `{task}` Task belongs to this account/current HiRoute installation, export it with the newer program, then stop/disable it and delete only that stopped registration. Confirm its owned processes have exited before copying data. If ownership or process exit cannot be verified, preserve everything and seek support.
+若找不到 `hiroute` 命令,请直接运行上面的安装入口(PowerShell 在带引号的程序路径前使用 `&`)。若 CLI 已损坏,在同一账户的任务计划程序中核对本说明记录的 Task 属于当前账户和 HiRoute 安装,将其导出并与新版程序另存,再停止、禁用并仅删除这一已停止的注册;确认其进程均已结束后再复制数据。无法核对归属或退出状态时,请保留现场并寻求支持。
+
+2. Restore the complete original storage group using this batch's recovery guide. Then copy the following entire directories/files, preserving native permissions. The retained native file map includes both CLI/daemon entries, management Skills, package metadata, documentation and licenses.
+按本批次说明还原完整旧数据组,再保留原生权限复制下列完整目录和文件。原生文件清单包含 CLI/守护进程入口、管理 Skill、包元数据、文档和许可证。
+
+- recovery-package/program/ → {program}
+
+"
+ );
+ if let Some(desktop) = &locations.desktop {
+ if !desktop.is_absolute() {
+ return Err(LocalStorageError::InvalidData);
+ }
+ text.push_str(&format!(
+ "- recovery-package/desktop/ → {}\n",
+ desktop.display()
+ ));
+ if !stage
+ .join("recovery-package/installation/uninstall.reg")
+ .is_file()
+ {
+ return Err(LocalStorageError::InvalidData);
+ }
+ text.push_str(r"
+The complete Desktop includes its matching shell, uninstaller and closed inventory. Export the current `HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall\HiRoute` entry separately. After restoring the old programs, import `recovery-package/installation/uninstall.reg` with Windows `reg.exe import`. This restores the old current-user Apps registration. Do not substitute another account or another revision's installer.
+旧桌面包包含配套外壳、卸载程序和完整清单。另行导出当前账户上述 HiRoute 注册项;还原旧程序后,用 Windows `reg.exe import` 导入保留的 uninstall.reg,恢复对应旧版的应用注册。不要换账户或使用其它修订的安装器。
+
+");
+ }
+ for (name, target) in &locations.files {
+ text.push_str(&format!(
+ "- recovery-package/{name} → {}\n",
+ target.display()
+ ));
+ }
+ let autostart = locations.task_autostart;
+ let shell_login = locations.shell_login;
+ text.push_str(&format!(r"
+3. In Task Scheduler under this same account, import `recovery-package/installation/task.xml` with the exact Task name `{task}`. Verify its account, restored old daemon path, arguments and ordinary-user run level against `installation/windows-background.json`; do not overwrite an unrelated Task or enable elevated privileges. Only after the complete old group and programs are paired, run `hiroute service start --output json` with the restored old CLI. Open the restored Desktop. Its original Desktop login preference was {}. Restore that choice using the matching Desktop's login setting, then run `hiroute service autostart {} --output json` last to retain the Task's independently recorded login choice even if it differed from the shell.
+在同一账户的任务计划程序中导入本批次的 task.xml,任务名必须为上面记录的完整名称;对照 windows-background.json 核对账户、已还原旧守护进程的路径、参数及普通用户运行级别,不得覆盖无关任务或开启提升权限。完整旧组与旧程序配套后,用已还原的旧 CLI 启动服务,再打开旧桌面端;先恢复其原先的登录启动选择,最后再运行上述 Task autostart 命令,保留 Task 独立记录的选择(即使它与桌面端原先的选择不同)。
+
+4. Verify `hiroute system status --output json` reports actual Control/Gateway readiness. Confirm the original source, credentials, routing and history, and complete a real request. Task command success alone is insufficient. Post-backup data remains in the separately preserved newer generation.
+检查 Control/Gateway 实际就绪、原模型源与凭据、路由和旧历史,并完成一次真实请求;仅 Task 命令成功不代表恢复完成。备份之后的数据保留在另存的新版组中。
+", if shell_login { "enabled / 开启" } else { "disabled / 关闭" }, if autostart { "enable" } else { "disable" }));
+ write_private(&stage.join("PROGRAM-LOCATIONS.md"), text.as_bytes())
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn task_recovery_requires_retained_native_registration_and_published_lifecycle() {
+ let directory = tempfile::tempdir().unwrap();
+ let stage = directory.path();
+ let installation = stage.join("recovery-package/installation");
+ fs::create_dir_all(&installation).unwrap();
+ let locations = hiroute_host_runtime::WindowsDesktopRestore {
+ schema: "hiroute.windows-desktop-restore/v1".into(),
+ program: stage.join("original-program"),
+ desktop: None,
+ task_name: format!("HiRoute-{}", "a".repeat(64)),
+ task_autostart: true,
+ shell_login: false,
+ files: BTreeMap::from([
+ (
+ "installation/standalone.json".into(),
+ stage.join("standalone.json"),
+ ),
+ (
+ "installation/windows-background.json".into(),
+ stage.join("windows-background.json"),
+ ),
+ ("installation/entry-0.bin".into(), stage.join("hiroute.exe")),
+ ]),
+ };
+ let value = serde_json::to_value(locations).unwrap();
+ assert!(
+ write(stage, &value).is_err(),
+ "a JSON definition cannot be imported as a native Task"
+ );
+ fs::write(
+ installation.join("task.xml"),
+ b"native registration fixture; not native evidence",
+ )
+ .unwrap();
+ write(stage, &value).unwrap();
+ let guide = fs::read_to_string(stage.join("PROGRAM-LOCATIONS.md")).unwrap();
+ assert!(guide.contains("recovery-package/installation/task.xml"));
+ assert!(guide.contains("hiroute service autostart disable --output json"));
+ assert!(guide.contains("hiroute service start --output json"));
+ assert!(!guide.contains("hiroute service install"));
+ assert!(!guide.contains("hiroute service uninstall"));
+ }
+}
diff --git a/crates/local-storage/src/backup/source_snapshot/seal.rs b/crates/local-storage/src/backup/source_snapshot/seal.rs
index 09290ff9..6954f95d 100644
--- a/crates/local-storage/src/backup/source_snapshot/seal.rs
+++ b/crates/local-storage/src/backup/source_snapshot/seal.rs
@@ -34,11 +34,17 @@ pub(super) fn capture(root: &Path, destination: &Path) -> Result<Value, LocalSto
if source[0] != identity(destination)?[0] {
return Err(LocalStorageError::InvalidData.at_upgrade_stage(
"Old Observation must be sealed on the same filesystem; no full-copy fallback is allowed",
- ));
+ ).with_recovery(hiroute_host_runtime::StorageRecoveryCause::NamespaceUnavailable,
+ hiroute_host_runtime::StorageRecoveryAction::PreserveAndDiagnose));
}
Ok(json!({"identity":source,"contents":"preserved_without_recursive_verification"}))
}
+/// Check only held directory identities; never enumerate historical contents.
+pub(super) fn preflight(root: &Path, destination_parent: &Path) -> Result<(), LocalStorageError> {
+ capture(root, destination_parent).map(|_| ())
+}
+
pub(super) fn verify_directory(path: &Path, value: &Value) -> Result<(), LocalStorageError> {
let seal = &value["sealed_observation"];
if seal.as_object().is_none_or(|o| o.len() != 2)
diff --git a/crates/local-storage/src/lib.rs b/crates/local-storage/src/lib.rs
index e025bf2e..b448ad7d 100644
--- a/crates/local-storage/src/lib.rs
+++ b/crates/local-storage/src/lib.rs
@@ -46,9 +46,93 @@ pub struct StorageStartupOptions {
pub recovery_package: Option<std::path::PathBuf>,
pub upgrade_progress:
Option<std::sync::mpsc::Sender<hiroute_host_runtime::StorageUpgradePhase>>,
+ /// Per-attempt typed facts also reach the caller when admission cannot
+ /// acquire the writer lock or write a recovery file.
+ pub startup_failure: Option<std::sync::mpsc::Sender<hiroute_host_runtime::StorageRecovery>>,
+}
+impl StorageStartupOptions {
+ pub fn report_failure(&self, recovery: hiroute_host_runtime::StorageRecovery) {
+ if let Some(sender) = &self.startup_failure {
+ let _ = sender.send(recovery);
+ }
+ }
}
impl LocalStorageSet {
+ /// Retain the storage-owner disposition if fresh Observation initialization
+ /// fails after the coordinated core stores opened. `self` keeps their startup
+ /// writer exclusion alive while the original batch is verified.
+ pub fn record_observation_startup_failure(
+ &self,
+ storage: &Path,
+ cause: hiroute_host_runtime::StorageRecoveryCause,
+ ) -> hiroute_host_runtime::StorageRecovery {
+ migrations::startup_recovery::publish_failure(
+ storage,
+ LocalStorageError::InvalidData.with_recovery(
+ cause,
+ if cause == hiroute_host_runtime::StorageRecoveryCause::MigrationFailed
+ && matches!(std::fs::symlink_metadata(storage.join("observation")),
+ Err(error) if error.kind() == std::io::ErrorKind::NotFound)
+ {
+ hiroute_host_runtime::StorageRecoveryAction::ResumeCurrent
+ } else {
+ hiroute_host_runtime::StorageRecoveryAction::PreserveAndDiagnose
+ },
+ ),
+ )
+ .recovery()
+ }
+
+ /// Provisional read-only checks; startup repeats admission under its writer lock.
+ pub fn preflight_upgrade(
+ storage: &Path,
+ package: &Path,
+ seal: bool,
+ ) -> Result<u64, LocalStorageError> {
+ if !storage.exists() {
+ return Ok(0);
+ }
+ migrations::validate_startup_format(storage)?;
+ if !seal {
+ return Ok(0);
+ }
+ LocalSecretStore::migration_binding(
+ &storage.join("live/secrets.db"),
+ &storage.join("master-key"),
+ )?
+ .ok_or(LocalStorageError::Locked)?;
+ migrations::validate_owner_file(&storage.join("observation-hmac-key"))?;
+ if std::fs::metadata(storage.join("observation-hmac-key"))?.len() != 32 {
+ return Err(LocalStorageError::Locked);
+ }
+ match std::fs::symlink_metadata(package) {
+ Ok(metadata) if metadata.is_dir() && !metadata.file_type().is_symlink() => {}
+ Ok(_) => {
+ return Err(LocalStorageError::InvalidData.with_recovery(
+ hiroute_host_runtime::StorageRecoveryCause::InvalidPackage,
+ hiroute_host_runtime::StorageRecoveryAction::PreserveAndDiagnose,
+ ));
+ }
+ Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+ return Err(LocalStorageError::Io(error).with_recovery(
+ hiroute_host_runtime::StorageRecoveryCause::MissingPackage,
+ hiroute_host_runtime::StorageRecoveryAction::PreserveAndDiagnose,
+ ));
+ }
+ Err(error) => return Err(LocalStorageError::Io(error)),
+ }
+ backup::source_snapshot::preflight_space(
+ storage,
+ None,
+ &StorageStartupOptions {
+ preserve_observation_source: true,
+ recovery_package: Some(package.to_path_buf()),
+ ..Default::default()
+ },
+ )
+ }
+
/// A published source link also protects the intentionally absent live root
/// between the old-directory rename and fresh Observation initialization.
pub fn observation_cutover_pending(storage_root: &Path) -> bool {
@@ -82,17 +166,23 @@ impl LocalStorageSet {
options: &StorageStartupOptions,
) -> Result<Self, LocalStorageError> {
let storage_root = storage_root.as_ref();
- migrations::prepare_storage_root(storage_root)?;
- migrations::validate_startup_format(storage_root)?;
- let startup_lock = std::sync::Arc::new(migrations::acquire_startup_lock(storage_root)?);
- migrations::validate_startup_format(storage_root)?;
- Self::open_locked_stores(
- authority,
- barrier,
- storage_root,
- startup_lock,
- Some(options),
- )
+ let result = (|| {
+ migrations::prepare_storage_root(storage_root)?;
+ let startup_lock = std::sync::Arc::new(migrations::acquire_startup_lock(storage_root)?);
+ hiroute_host_runtime::StorageRecovery::clear(storage_root)?;
+ let result = migrations::validate_startup_format(storage_root).and_then(|()| {
+ Self::open_locked_stores(
+ authority,
+ barrier,
+ storage_root,
+ startup_lock.clone(),
+ Some(options),
+ )
+ });
+ result
+ .map_err(|error| migrations::startup_recovery::publish_failure(storage_root, error))
+ })();
+ result.inspect_err(|error: &LocalStorageError| options.report_failure(error.recovery()))
}
// SQL coordinator component harness only: unsupported formats never pass through the
@@ -596,6 +686,11 @@ pub enum LocalStorageError {
"UPGRADE_SOURCE_UNSUPPORTED: this source format has no validated upgrade and recovery path"
)]
UpgradeSourceUnsupported,
+ #[error("storage upgrade requires recovery: {recovery:?}: {source}")]
+ Recovery {
+ recovery: Box<hiroute_host_runtime::StorageRecovery>,
+ source: Box<LocalStorageError>,
+ },
#[error("stable storage upgrade failed at {stage}: {source}")]
UpgradeStage {
stage: &'static str,
@@ -624,6 +719,48 @@ fn prepare_owner_directory(path: &Path) -> Result<(), LocalStorageError> {
}
impl LocalStorageError {
+ pub fn recovery(&self) -> hiroute_host_runtime::StorageRecovery {
+ use hiroute_host_runtime::{
+ StorageRecovery, StorageRecoveryAction as A, StorageRecoveryCause as C,
+ };
+ match self {
+ Self::Recovery { recovery, .. } => recovery.as_ref().clone(),
+ Self::UpgradeStage { source, .. } => {
+ let mut report = source.recovery();
+ if report.cause == C::UnknownState {
+ report.cause = C::MigrationFailed;
+ }
+ report
+ }
+ Self::UpgradeSourceUnsupported => {
+ StorageRecovery::new(C::UnsupportedFormat, A::PreserveAndDiagnose)
+ }
+ Self::Permission => StorageRecovery::new(C::AccessDenied, A::RetryCurrent),
+ Self::Locked | Self::Crypto => {
+ StorageRecovery::new(C::MissingKey, A::PreserveAndDiagnose)
+ }
+ Self::Io(e)
+ if e.kind() == std::io::ErrorKind::WouldBlock
+ || (cfg!(windows) && matches!(e.raw_os_error(), Some(32 | 33))) =>
+ {
+ StorageRecovery::new(C::Locked, A::RetryCurrent)
+ }
+ Self::Io(e) if e.kind() == std::io::ErrorKind::PermissionDenied => {
+ StorageRecovery::new(C::AccessDenied, A::RetryCurrent)
+ }
+ _ => StorageRecovery::new(C::UnknownState, A::PreserveAndDiagnose),
+ }
+ }
+ pub(crate) fn with_recovery(
+ self,
+ cause: hiroute_host_runtime::StorageRecoveryCause,
+ action: hiroute_host_runtime::StorageRecoveryAction,
+ ) -> Self {
+ Self::Recovery {
+ recovery: Box::new(hiroute_host_runtime::StorageRecovery::new(cause, action)),
+ source: Box::new(self),
+ }
+ }
pub(crate) fn at_upgrade_stage(self, stage: &'static str) -> Self {
Self::UpgradeStage {
stage,
diff --git a/crates/local-storage/src/migrations/current_storage.rs b/crates/local-storage/src/migrations/current_storage.rs
index c6c4e6df..5e54ac40 100644
--- a/crates/local-storage/src/migrations/current_storage.rs
+++ b/crates/local-storage/src/migrations/current_storage.rs
@@ -57,8 +57,16 @@ pub(crate) fn acquire_startup_lock(root: &Path) -> Result<std::fs::File, LocalSt
validate_owner_file(&path)?;
file
};
- file.try_lock_exclusive()
- .map_err(|_| LocalStorageError::InvalidData)?;
+ file.try_lock_exclusive().map_err(|error| {
+ if error.kind() == std::io::ErrorKind::WouldBlock {
+ LocalStorageError::Io(error).with_recovery(
+ hiroute_host_runtime::StorageRecoveryCause::Locked,
+ hiroute_host_runtime::StorageRecoveryAction::RetryCurrent,
+ )
+ } else {
+ LocalStorageError::Io(error)
+ }
+ })?;
Ok(file)
}
diff --git a/crates/local-storage/src/migrations/mod.rs b/crates/local-storage/src/migrations/mod.rs
index 892df701..21133a62 100644
--- a/crates/local-storage/src/migrations/mod.rs
+++ b/crates/local-storage/src/migrations/mod.rs
@@ -18,6 +18,7 @@ mod current_storage;
mod observation_source;
mod recovery_package;
mod startup_format;
+pub(crate) mod startup_recovery;
pub(crate) use startup_format::validate_startup_format;
#[cfg(test)]
mod stopped_read_tests;
diff --git a/crates/local-storage/src/migrations/observation_source.rs b/crates/local-storage/src/migrations/observation_source.rs
index cf55cfa9..e7121519 100644
--- a/crates/local-storage/src/migrations/observation_source.rs
+++ b/crates/local-storage/src/migrations/observation_source.rs
@@ -68,9 +68,26 @@ impl MigrationSetCoordinator {
}
let mut options = options.clone();
if options.preserve_observation_source && options.recovery_package.is_none() {
- options.recovery_package = super::recovery_package::previous_desktop(root)?;
+ options.recovery_package =
+ super::recovery_package::previous_desktop(root).map_err(|error| {
+ error.with_recovery(
+ hiroute_host_runtime::StorageRecoveryCause::InvalidPackage,
+ hiroute_host_runtime::StorageRecoveryAction::PreserveAndDiagnose,
+ )
+ })?;
if options.recovery_package.is_none() {
- return Err(LocalStorageError::InvalidData.at_upgrade_stage("Observation history sealing requires a matching old package: set HIROUTE_RECOVERY_PACKAGE"));
+ return Err(LocalStorageError::InvalidData.at_upgrade_stage("Observation history sealing requires a matching old package: set HIROUTE_RECOVERY_PACKAGE").with_recovery(hiroute_host_runtime::StorageRecoveryCause::MissingPackage, hiroute_host_runtime::StorageRecoveryAction::PreserveAndDiagnose));
+ }
+ }
+ if let Some(package) = &options.recovery_package {
+ let valid = package.is_absolute()
+ && fs::symlink_metadata(package)
+ .is_ok_and(|m| m.is_dir() && !m.file_type().is_symlink());
+ if !valid {
+ return Err(LocalStorageError::InvalidData.with_recovery(
+ hiroute_host_runtime::StorageRecoveryCause::InvalidPackage,
+ hiroute_host_runtime::StorageRecoveryAction::PreserveAndDiagnose,
+ ));
}
}
let source = self.set.as_ref().filter(|set| {
diff --git a/crates/local-storage/src/migrations/recovery_package.rs b/crates/local-storage/src/migrations/recovery_package.rs
index b7de9d90..33d0b81f 100644
--- a/crates/local-storage/src/migrations/recovery_package.rs
+++ b/crates/local-storage/src/migrations/recovery_package.rs
@@ -18,7 +18,13 @@ pub(super) fn previous_desktop(storage: &Path) -> Result<Option<PathBuf>, LocalS
.ancestors()
.find(|p| p.extension().is_some_and(|ext| ext == "app"))
else {
- return Ok(None);
+ return match hiroute_host_runtime::RetainedRecoveryPackage::read(storage)? {
+ Some(package) => {
+ package.verify(&executable)?;
+ Ok(Some(package.package_root))
+ }
+ None => Ok(None),
+ };
};
let data = storage.parent().ok_or(LocalStorageError::InvalidData)?;
let directory = data.join("updates");
diff --git a/crates/local-storage/src/migrations/startup_recovery.rs b/crates/local-storage/src/migrations/startup_recovery.rs
new file mode 100644
index 00000000..2aae2d59
--- /dev/null
+++ b/crates/local-storage/src/migrations/startup_recovery.rs
@@ -0,0 +1,273 @@
+//! Recovery disposition is decided while the startup writer lock is held.
+use super::*;
+use hiroute_host_runtime::StorageRecoveryAction as Action;
+
+pub(crate) fn publish_failure(root: &Path, error: LocalStorageError) -> LocalStorageError {
+ let mut recovery = error.recovery();
+ let initial = recovery.clone();
+ // Missing package and matching SQL markers cannot establish that a complete
+ // original group is readable by the exact old program. In particular,
+ // current Gateway payloads can be incompatible without a SQL version change.
+ // No unproven program-only downgrade is authorized here.
+ if matches!(
+ recovery.action,
+ Action::PreserveAndDiagnose | Action::ResumeCurrent
+ ) {
+ let resume = recovery.action == Action::ResumeCurrent;
+ // A verified original group proves a complete restoration target. It
+ // does not prove that arbitrary current corruption can resume. Only a
+ // caller holding the successfully opened core stores may request resume
+ // while the fresh Observation root has not yet been published.
+ match verified_original_source(root) {
+ Ok((name, id, phase)) => {
+ recovery.backup_name = Some(name);
+ recovery.backup_batch = Some(id);
+ recovery.action = if resume
+ && !matches!(phase, BackupSetPhase::Restored | BackupSetPhase::Restoring)
+ {
+ Action::ResumeCurrent
+ } else {
+ Action::RestoreCompleteGroup
+ };
+ }
+ Err(_) => {
+ recovery.action = Action::PreserveAndDiagnose;
+ recovery.backup_name = None;
+ recovery.backup_batch = None;
+ }
+ }
+ }
+ let _ = recovery.store(root);
+ // Preserve the existing public Rust error variants when the additional
+ // disposition carries no different facts. A changed batch/action must still
+ // travel with the error instead of depending on a writable report file.
+ if recovery == initial && !matches!(error, LocalStorageError::Recovery { .. }) {
+ return error;
+ }
+ LocalStorageError::Recovery {
+ recovery: Box::new(recovery),
+ source: Box::new(match error {
+ LocalStorageError::Recovery { source, .. } => *source,
+ error => error,
+ }),
+ }
+}
+
+fn verified_original_source(
+ root: &Path,
+) -> Result<(String, String, BackupSetPhase), LocalStorageError> {
+ let link = root.join("observation-source-backup.json");
+ validate_owner_file(&link)?;
+ if fs::metadata(&link)?.len() > 16 * 1024 {
+ return Err(LocalStorageError::InvalidData);
+ }
+ let record: serde_json::Value =
+ serde_json::from_slice(&fs::read(link)?).map_err(|_| LocalStorageError::InvalidData)?;
+ let name = record["backup_name"]
+ .as_str()
+ .ok_or(LocalStorageError::InvalidData)?;
+ let id = record["set_id"]
+ .as_str()
+ .ok_or(LocalStorageError::InvalidData)?;
+ let portable = |s: &str| {
+ !s.is_empty()
+ && s.len() <= 128
+ && !s.contains("..")
+ && s.bytes()
+ .all(|b| b.is_ascii_alphanumeric() || b"-_.".contains(&b))
+ };
+ if record["schema"] != 1 || !portable(name) || !portable(id) {
+ return Err(LocalStorageError::InvalidData);
+ }
+ let parent = crate::upgrade_backup_root(root)?
+ .parent()
+ .ok_or(LocalStorageError::InvalidData)?
+ .to_path_buf();
+ for name in [name.to_owned(), format!("migration-set.{id}")] {
+ let path = parent.join(&name);
+ if !path.exists() {
+ continue;
+ }
+ let set = BackupSet::open(&crate::daemon_storage_authority(), &path)?;
+ if set.set_id() != id {
+ continue;
+ }
+ crate::backup::source_snapshot::verify_sealed(&path)?;
+ return Ok((name, id.to_owned(), set.phase()));
+ }
+ Err(LocalStorageError::InvalidData)
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use hiroute_host_runtime::{StorageRecovery, StorageRecoveryCause as Cause};
+ #[test]
+ fn early_writer_and_root_refusals_report_the_attempt_without_replacing_writer_facts() {
+ let directory = crate::test_tempdir().unwrap();
+ let root = directory.path().join("storage");
+ let stores = crate::LocalStorageSet::open_for_daemon_startup(&root).unwrap();
+ let prior = StorageRecovery::new(Cause::UnknownState, Action::PreserveAndDiagnose);
+ prior.store(&root).unwrap();
+ let before = fs::read(root.join(hiroute_host_runtime::STORAGE_RECOVERY_FILE)).unwrap();
+ let (sender, receiver) = std::sync::mpsc::channel();
+ let options = crate::StorageStartupOptions {
+ startup_failure: Some(sender),
+ ..Default::default()
+ };
+ let error = crate::LocalStorageSet::open_for_daemon_startup_with_options(&root, &options)
+ .err()
+ .unwrap();
+ assert_eq!(error.recovery().cause, Cause::Locked);
+ let report = receiver.try_recv().unwrap();
+ assert_eq!(report.cause, Cause::Locked);
+ assert_eq!(report.action, Action::RetryCurrent);
+ assert_eq!(
+ fs::read(root.join(hiroute_host_runtime::STORAGE_RECOVERY_FILE)).unwrap(),
+ before
+ );
+ drop(stores);
+ let blocked = directory.path().join("not-a-directory");
+ hiroute_platform::durable::write_private_new(&blocked, b"preserve foreign input").unwrap();
+ assert!(
+ crate::LocalStorageSet::open_for_daemon_startup_with_options(&blocked, &options)
+ .is_err()
+ );
+ assert_eq!(receiver.try_recv().unwrap().cause, Cause::AccessDenied);
+ assert_eq!(fs::read(blocked).unwrap(), b"preserve foreign input");
+ }
+
+ #[test]
+ fn a_verified_old_source_does_not_make_current_corruption_resumable() {
+ let directory = crate::test_tempdir().unwrap();
+ let root = directory.path().join("storage");
+ drop(crate::LocalStorageSet::open_for_daemon_startup(&root).unwrap());
+ hiroute_platform::durable::write_private_new(&root.join("observation-hmac-key"), &[7; 32])
+ .unwrap();
+ crate::prepare_owner_directory(&root.join("observation")).unwrap();
+ let db = Connection::open(root.join("observation/activity.db")).unwrap();
+ db.execute_batch("CREATE TABLE observation_meta(key TEXT PRIMARY KEY,value TEXT); INSERT INTO observation_meta VALUES('schema_version','4');").unwrap();
+ drop(db);
+ let package = directory.path().join("old-program");
+ crate::prepare_owner_directory(&package).unwrap();
+ hiroute_platform::durable::write_private_new(
+ &package.join("hirouted"),
+ b"original program fixture",
+ )
+ .unwrap();
+ let stores = crate::LocalStorageSet::open_for_daemon_startup_with_options(
+ &root,
+ &crate::StorageStartupOptions {
+ preserve_observation_source: true,
+ recovery_package: Some(package),
+ ..Default::default()
+ },
+ )
+ .unwrap();
+ // Successfully opened core + unpublished fresh Observation is a known
+ // initialization boundary. It may continue with the accepted program.
+ stores.record_observation_startup_failure(&root, Cause::MigrationFailed);
+ assert_eq!(
+ StorageRecovery::read(&root).unwrap().unwrap().action,
+ Action::ResumeCurrent
+ );
+ for (kind, cause) in [
+ (std::io::ErrorKind::WouldBlock, Cause::Locked),
+ (std::io::ErrorKind::PermissionDenied, Cause::AccessDenied),
+ ] {
+ let failure = publish_failure(
+ &root,
+ LocalStorageError::Io(std::io::Error::new(kind, "file prerequisite")),
+ );
+ let report = failure.recovery();
+ assert_eq!(report.cause, cause);
+ assert_eq!(
+ report.action,
+ Action::RetryCurrent,
+ "a retained old source must not turn a correctable prerequisite into restoration"
+ );
+ assert!(report.backup_batch.is_none());
+ assert_eq!(
+ StorageRecovery::read(&root).unwrap().unwrap().action,
+ Action::RetryCurrent
+ );
+ }
+ drop(stores);
+ // The retained source still exists after a later generation is present.
+ // Arbitrary damage to that current generation cannot inherit resume.
+ crate::prepare_owner_directory(&root.join("observation")).unwrap();
+ hiroute_platform::durable::write_private_new(
+ &root.join("observation/activity.db"),
+ b"new generation must remain",
+ )
+ .unwrap();
+ fs::write(root.join("live/control.db"), b"damaged current control").unwrap();
+ assert!(crate::LocalStorageSet::open_for_daemon_startup(&root).is_err());
+ let report = StorageRecovery::read(&root).unwrap().unwrap();
+ assert_eq!(report.action, Action::RestoreCompleteGroup);
+ assert!(report.backup_batch.is_some());
+ assert_eq!(
+ fs::read(root.join("live/control.db")).unwrap(),
+ b"damaged current control"
+ );
+ assert_eq!(
+ fs::read(root.join("observation/activity.db")).unwrap(),
+ b"new generation must remain"
+ );
+ }
+
+ #[test]
+ fn missing_package_never_infers_original_program_compatibility_from_sql_markers() {
+ for prior_upgrade in [false, true] {
+ let directory = crate::test_tempdir().unwrap();
+ let root = directory.path().join("storage");
+ drop(crate::LocalStorageSet::open_for_daemon_startup(&root).unwrap());
+ hiroute_platform::durable::write_private_new(
+ &root.join("observation-hmac-key"),
+ &[7; 32],
+ )
+ .unwrap();
+ crate::prepare_owner_directory(&root.join("observation")).unwrap();
+ let path = root.join("observation/activity.db");
+ let db = Connection::open(&path).unwrap();
+ db.execute_batch("CREATE TABLE observation_meta(key TEXT PRIMARY KEY,value TEXT); INSERT INTO observation_meta VALUES('schema_version','4'); CREATE TABLE original_content(id INTEGER PRIMARY KEY,body BLOB); INSERT INTO original_content VALUES(1,X'00ff');").unwrap();
+ drop(db);
+ super::super::set_owner_file_permissions(&path).unwrap();
+ let paths = [
+ "live/control.db",
+ "live/runtime.db",
+ "live/secrets.db",
+ "master-key",
+ "observation-hmac-key",
+ "observation/activity.db",
+ ];
+ let original: Vec<_> = paths
+ .iter()
+ .map(|p| fs::read(root.join(p)).unwrap())
+ .collect();
+ if prior_upgrade {
+ fs::write(
+ root.join("observation.upgrade.json"),
+ b"unknown prior phase",
+ )
+ .unwrap();
+ }
+ assert!(
+ crate::LocalStorageSet::open_for_daemon_startup_with_options(
+ &root,
+ &crate::StorageStartupOptions {
+ preserve_observation_source: true,
+ ..Default::default()
+ }
+ )
+ .is_err()
+ );
+ let recovery = StorageRecovery::read(&root).unwrap().unwrap();
+ assert_eq!(recovery.cause, Cause::MissingPackage);
+ assert_eq!(recovery.action, Action::PreserveAndDiagnose);
+ for (path, before) in paths.iter().zip(original) {
+ assert_eq!(fs::read(root.join(path)).unwrap(), before, "changed {path}");
+ }
+ }
+ }
+}
diff --git a/crates/platform/src/windows/mod.rs b/crates/platform/src/windows/mod.rs
index fd51cc40..c2669614 100644
--- a/crates/platform/src/windows/mod.rs
+++ b/crates/platform/src/windows/mod.rs
@@ -17,5 +17,6 @@ pub mod security;
pub mod service;
pub mod shell_login;
pub mod shell_open;
+pub mod shell_registration;
pub mod task;
pub mod user_path;
diff --git a/crates/platform/src/windows/shell_registration.rs b/crates/platform/src/windows/shell_registration.rs
new file mode 100644
index 00000000..9fe36419
--- /dev/null
+++ b/crates/platform/src/windows/shell_registration.rs
@@ -0,0 +1,225 @@
+//! Read-only export of this product's fixed current-user NSIS registration.
+use super::job::{Child, Launch, Stream};
+use std::{
+ ffi::OsString,
+ io::{self, Read},
+ path::Path,
+ time::{Duration, Instant},
+};
+
+pub fn export(destination: &Path) -> io::Result<()> {
+ export_key(
+ destination,
+ r"HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall\HiRoute",
+ )
+}
+
+fn nonce() -> io::Result<String> {
+ let mut bytes = [0_u8; 16];
+ getrandom::fill(&mut bytes).map_err(|error| io::Error::other(error.to_string()))?;
+ Ok(bytes.iter().map(|byte| format!("{byte:02x}")).collect())
+}
+
+fn system_reg() -> io::Result<std::path::PathBuf> {
+ let mut directory = [0_u16; 32768];
+ // SAFETY: native system-directory API and an actual writable UTF-16 buffer.
+ let count = unsafe {
+ windows_sys::Win32::System::SystemInformation::GetSystemDirectoryW(
+ directory.as_mut_ptr(),
+ directory.len() as u32,
+ )
+ } as usize;
+ if count == 0 || count >= directory.len() {
+ return Err(io::Error::last_os_error());
+ }
+ let directory = String::from_utf16(&directory[..count]).map_err(io::Error::other)?;
+ Ok(Path::new(&directory).join("reg.exe"))
+}
+
+fn export_to(key: &str, destination: &Path) -> io::Result<()> {
+ let reg = system_reg()?;
+ let windows = reg
+ .parent()
+ .and_then(Path::parent)
+ .ok_or(io::ErrorKind::InvalidInput)?;
+ let args = [
+ "export".into(),
+ key.into(),
+ destination.as_os_str().to_owned(),
+ "/y".into(),
+ ];
+ let temporary = destination.parent().ok_or(io::ErrorKind::InvalidInput)?;
+ let env = [
+ (OsString::from("SystemRoot"), windows.as_os_str().to_owned()),
+ (OsString::from("TEMP"), temporary.as_os_str().to_owned()),
+ (OsString::from("TMP"), temporary.as_os_str().to_owned()),
+ ];
+ // reg.exe also needs a writable scratch directory while exporting. With a
+ // cleared environment its Windows-directory fallback fails for an ordinary
+ // account, even when the final destination itself is writable. Keep every
+ // scratch file under this already private, held staging directory.
+ // The existing launcher gives only this suspended child private user-SID
+ // defaults, including for an elevated caller, without changing the parent.
+ let child = Child::spawn(Launch {
+ program: &reg,
+ args: &args,
+ env: &env,
+ cwd: destination.parent(),
+ stdin: Stream::Null,
+ stdout: Stream::Null,
+ stderr: if cfg!(test) {
+ Stream::Piped
+ } else {
+ Stream::Null
+ },
+ })?;
+ #[cfg(test)]
+ let mut child = child;
+ let deadline = Instant::now() + Duration::from_secs(10);
+ loop {
+ if let Some(code) = child.exit_code()? {
+ if code != 0 {
+ #[cfg(test)]
+ if let Some(stderr) = child.stderr.as_mut() {
+ let mut bytes = Vec::new();
+ let _ = stderr.take(4096).read_to_end(&mut bytes);
+ eprintln!(
+ "registry system child exit={code}, bounded stderr={:?}, bytes={bytes:02x?}",
+ String::from_utf8_lossy(&bytes),
+ );
+ }
+ return Err(io::Error::other("SHELL_REGISTRATION_UNAVAILABLE"));
+ }
+ if child.empty()? {
+ return Ok(());
+ }
+ }
+ if Instant::now() >= deadline {
+ let _ = child.terminate();
+ return Err(io::ErrorKind::TimedOut.into());
+ }
+ std::thread::sleep(Duration::from_millis(20));
+ }
+}
+
+fn read_child(parent: &std::fs::File, name: &std::ffi::OsStr) -> io::Result<Vec<u8>> {
+ // reg.exe creates an inherited DACL. Admit only the controlled child's
+ // single-owner regular file under this held, strictly private parent.
+ let file = super::security::open_inherited_private_file_at(parent, name)?;
+ let mut bytes = Vec::new();
+ file.take(64 * 1024 + 1).read_to_end(&mut bytes)?;
+ if bytes.is_empty() || bytes.len() > 64 * 1024 {
+ return Err(io::ErrorKind::InvalidData.into());
+ }
+ Ok(bytes)
+}
+
+fn export_key(destination: &Path, key: &str) -> io::Result<()> {
+ let parent = super::security::open_owner_only(
+ destination.parent().ok_or(io::ErrorKind::InvalidInput)?,
+ true,
+ )?;
+ let name = destination.file_name().ok_or(io::ErrorKind::InvalidInput)?;
+ // Keep unpublished external output outside the immutable retained package.
+ // A crash cannot leave a partial export at its final recovery name.
+ let stage_path = std::env::temp_dir().join(format!("hiroute-registry-{}", nonce()?));
+ let mut stage = crate::private_fs::OwnedDirectory::create(&stage_path)?;
+ let result = (|| {
+ let staged = stage.path().join("uninstall.reg");
+ export_to(key, &staged)?;
+ let held = super::security::open_owner_only(stage.path(), true)?;
+ let bytes = read_child(&held, std::ffi::OsStr::new("uninstall.reg"))?;
+ match read_child(&parent, name) {
+ Ok(previous) => {
+ if previous != bytes {
+ return Err(io::Error::other("SHELL_REGISTRATION_CHANGED"));
+ }
+ // An interrupted earlier preparation may have left the same
+ // complete bytes with inherited protection. Publish only the
+ // independently re-exported, identical value with private ACLs.
+ crate::durable::write_private_atomic(destination, &bytes)?;
+ }
+ Err(error) if error.kind() == io::ErrorKind::NotFound => {
+ crate::durable::write_private_new(destination, &bytes)?;
+ }
+ Err(error) => return Err(error),
+ }
+ super::security::open_owner_only(destination, false)?;
+ Ok(())
+ })();
+ let _ = stage.remove();
+ result
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use std::process::{Command, Stdio};
+
+ struct Registry(String);
+ impl Drop for Registry {
+ fn drop(&mut self) {
+ let _ = Command::new(system_reg().unwrap())
+ .args(["delete", &self.0, "/f"])
+ .stdout(Stdio::null())
+ .stderr(Stdio::null())
+ .status();
+ }
+ }
+
+ #[test]
+ fn inherited_export_is_published_privately_and_changed_material_is_not_overwritten() {
+ let registry = Registry(format!(
+ r"HKCU\Software\HiRouteRecoveryTest-{}",
+ nonce().unwrap()
+ ));
+ assert!(
+ Command::new(system_reg().unwrap())
+ .args([
+ "add",
+ &registry.0,
+ "/v",
+ "Marker",
+ "/t",
+ "REG_SZ",
+ "/d",
+ "original",
+ "/f",
+ ])
+ .stdout(Stdio::null())
+ .stderr(Stdio::null())
+ .status()
+ .unwrap()
+ .success()
+ );
+ let root = tempfile::tempdir().unwrap();
+ let private = root.path().join("private");
+ super::super::security::ensure_private_directory(&private).unwrap();
+ let inherited = private.join("inherited.reg");
+ export_to(&registry.0, &inherited).unwrap();
+ assert!(
+ super::super::security::open_owner_only(&inherited, false).is_err(),
+ "the previous strict-reader path rejects native reg.exe inheritance"
+ );
+ let original = std::fs::read(&inherited).unwrap();
+ export_key(&inherited, &registry.0).unwrap();
+ super::super::security::open_owner_only(&inherited, false).unwrap();
+ assert_eq!(std::fs::read(&inherited).unwrap(), original);
+ let destination = private.join("retained.reg");
+ export_key(&destination, &registry.0).unwrap();
+ super::super::security::open_owner_only(&destination, false).unwrap();
+ assert_eq!(std::fs::read(&destination).unwrap(), original);
+ crate::durable::write_private_atomic(&destination, b"changed retained material").unwrap();
+ assert!(export_key(&destination, &registry.0).is_err());
+ assert_eq!(
+ std::fs::read(&destination).unwrap(),
+ b"changed retained material"
+ );
+ let missing = private.join("missing.reg");
+ assert!(export_key(&missing, &(registry.0.clone() + "-missing")).is_err());
+ assert!(
+ !missing.exists(),
+ "an unsuccessful export must not publish a recovery artifact"
+ );
+ }
+}
diff --git a/crates/platform/src/windows/task.rs b/crates/platform/src/windows/task.rs
index a1aff65d..b88cae4c 100644
--- a/crates/platform/src/windows/task.rs
+++ b/crates/platform/src/windows/task.rs
@@ -1,4 +1,4 @@
-//! Typed Task Scheduler COM boundary. No XML or PowerShell is generated.
+//! Typed Task Scheduler COM boundary. Recovery may export an owned native Task's XML.
use std::io;
use windows::Win32::Foundation::{VARIANT_BOOL, VARIANT_FALSE, VARIANT_TRUE};
use windows::Win32::System::Com::{
@@ -237,6 +237,24 @@ pub fn autostart(definition: &Definition) -> io::Result<bool> {
})
}
+/// Preserve the scheduler's actual registration for manual whole-group recovery.
+/// This reads only the exact owned Task; it never registers or generates a Task.
+pub fn recovery_xml(definition: &Definition) -> io::Result<Vec<u8>> {
+ definition.verify_image()?;
+ with_folder(definition, |folder, definition| unsafe {
+ let registered = owned_task(folder, definition)?;
+ let xml = registered.Xml().map_err(com_error)?.to_string();
+ if xml.is_empty() || xml.len() > 256 * 1024 {
+ return Err(io::Error::from(io::ErrorKind::InvalidData));
+ }
+ // Scheduler XML declares UTF-16. Preserve that encoding with a BOM so
+ // Task Scheduler and schtasks can import the retained file directly.
+ let mut bytes = vec![0xff, 0xfe];
+ bytes.extend(xml.encode_utf16().flat_map(u16::to_le_bytes));
+ Ok(bytes)
+ })
+}
+
pub fn set_autostart(definition: &Definition, enabled: bool) -> io::Result<()> {
with_folder(definition, move |folder, definition| unsafe {
let registered = owned_task(folder, definition)?;
@@ -505,6 +523,18 @@ mod tests {
let _remove = Remove(definition.clone());
assert!(!autostart(&definition).unwrap());
assert!(!active(&definition).unwrap());
+ let xml = recovery_xml(&definition).unwrap();
+ assert!(xml.starts_with(&[0xff, 0xfe]));
+ assert!(
+ String::from_utf16(
+ &xml[2..]
+ .chunks_exact(2)
+ .map(|pair| u16::from_le_bytes([pair[0], pair[1]]))
+ .collect::<Vec<_>>()
+ )
+ .unwrap()
+ .contains("<Task")
+ );
set_autostart(&definition, true).unwrap();
assert!(autostart(&definition).unwrap());
register(&definition, Some(&definition)).unwrap();
@@ -520,6 +550,7 @@ mod tests {
let mut foreign = definition.clone();
foreign.daemon = temporary.path().join("unowned/hirouted.exe");
assert!(active(&foreign).is_err());
+ assert!(recovery_xml(&foreign).is_err());
unregister(&definition).unwrap();
assert!(!active(&definition).unwrap());
assert!(!autostart(&definition).unwrap());
diff --git a/docs/code-map/README.md b/docs/code-map/README.md
index 9c023042..bf7f3b33 100644
--- a/docs/code-map/README.md
+++ b/docs/code-map/README.md
@@ -31,8 +31,8 @@ results in the relevant run record.
| 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) |
| 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) | Preflight → orderly stop → explicit commit; [macOS installation and recovery](../macos-installation.md) |
-| Install, open or update Windows Desktop | [Windows shell](../../apps/shell/README.md), [shell payload and rollback ownership](../../apps/shell/src-tauri/src/runtime/install_transaction.rs), [local-console recovery and catalog failures](../windows-desktop-installation.md), [Rust Task transaction](../../crates/host-runtime/src/standalone_install), [restoration policy](../../crates/host-runtime/src/standalone_install/uninstall.rs), [owned package cleanup](../../crates/host-runtime/src/standalone_install/cleanup.rs) | [Native NSIS smoke](../../crates/daemon/tests/windows_desktop.rs), [shell page/host scenarios](../../apps/desktop/tests/v3/visual/shell-host-scenarios.mjs), [required native gates](../windows-desktop-installation.md#evidence-and-release-claims) |
+| 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) |
+| Install, open or update Windows Desktop | [Windows shell](../../apps/shell/README.md), [shell payload and rollback ownership](../../apps/shell/src-tauri/src/runtime/install_transaction.rs), [current startup failure](../../apps/shell/src-tauri/src/runtime/startup_failure.rs), [local-console recovery and catalog failures](../windows-desktop-installation.md), [Rust Task transaction](../../crates/host-runtime/src/standalone_install), [restoration policy](../../crates/host-runtime/src/standalone_install/uninstall.rs), [owned package cleanup](../../crates/host-runtime/src/standalone_install/cleanup.rs) | [Native NSIS smoke](../../crates/daemon/tests/windows_desktop.rs), [shell page/host scenarios](../../apps/desktop/tests/v3/visual/shell-host-scenarios.mjs), [required native gates](../windows-desktop-installation.md#evidence-and-release-claims) |
| Maintain agent instructions, shared skills and issue-native planning | [Instruction ownership](../../.agents/README.md), [project workflow](../../issue-spec/project/workflow.md), [feedback routing](../../.agents/skills/hiroute-workflow-improvement/SKILL.md) | Pinned generated manifest, individual Claude links and current GitHub artifacts |
| Select, execute or diagnose a build/test run | [Validation workflow](../../.agents/skills/hiroute-validation/SKILL.md), [test map](testing.md) | [Selection](../../scripts/test-plan.py), [configured runner](../../scripts/validation.py) and revision-bound reports |
| Build macOS / Windows Desktop or Linux / Windows headless release candidates | [Release candidate entry](../../scripts/build-release.py), [build and publication guide](../release-builds.md), [independent Unix/Windows candidate jobs](../../.github/workflows/build-release.yml) | [Package-to-publication contract](../../scripts/test-build-release.py), [Linux ABI gate](../../scripts/linux-release-baseline.json), [Windows Desktop identity](../../scripts/package-windows-shell.py); final publishing remains in [release.yml](../../.github/workflows/release.yml) |
diff --git a/docs/code-map/architecture.md b/docs/code-map/architecture.md
index 93e7564c..f8fc77f1 100644
--- a/docs/code-map/architecture.md
+++ b/docs/code-map/architecture.md
@@ -30,7 +30,12 @@ host IPC, startup/reconnect, tray/login preference and NSIS hooks. The
[Rust standalone transaction](../../crates/host-runtime/src/standalone_install)
owns architecture-matched Task installation and current-schema journal recovery; the shell's separate
inventory/finisher owns its program files and update outcome. Neither owns business
-transactions or exposes Local Control to WebView. The
+transactions or exposes Local Control to WebView.
+The native [current-package repair](../../crates/host-runtime/src/standalone_install/windows/repair.rs)
+matches the complete accepted package and owned Task before reapplying a prepared
+core journal forward. Generic rollback refuses possible storage writes before any
+manager effect. NSIS supplies the candidate to early shell recovery, preserving
+the original batch instead of forcing an older-program rollback. The
[release catalog](../../apps/website/src/lib/releases.mjs) emits V3 and the registered
Windows-free V2 projection for supported macOS readers. Public Windows artifacts
are x64 NSIS installers only; headless x64/ARM64 archives stay internal. The
@@ -158,7 +163,7 @@ The shared product-session layer in `crates/product-session` owns Preview compos
| Reference refresh | A checkpoint copies verified installed routing authority at the next revision through the normal publication writer. Preview pins revisions and content; disabled routes, drafts and held versions remain deletion blockers. | [Strict checkpoint](../../crates/domain/src/operation/publication_checkpoint.rs), [shared entry](../../crates/application/src/control_plane/publication_checkpoint.rs), [installed-state facts](../../crates/daemon/src/control/runtime/routing.rs) |
| Profile deletion | Untouched proof binds the current store instance and exact marker; a stage directory alone cannot prove deletion never began. | [Profile lifecycle](../../crates/daemon/src/control/runtime/settings_profile_tests.rs) |
| Worker/content lifetime | Result completion, process stop, body availability and permission to Continue are separate facts; cleanup requires exact ownership. | [Worker map](worker-context.md#state-and-lifetime), [managed-text contract](../../crates/observation/src/managed_text/README.md) |
-| Recovery and compatibility | Current producers have one ingestion contract. Registered legacy revoke tails retain their own ordering; frozen fixtures alone do not establish production upgrade support. | [Startup admission](../../crates/local-storage/src/migrations/startup_format.rs), [legacy-tail tests](../../crates/daemon/src/control/runtime/settings_profile_legacy_tests.rs), [compatibility registry](../../contracts/compatibility-support.v1.json) |
+| Recovery and compatibility | Current producers have one ingestion contract. Startup presenters prefer the current attempt's typed facts over an older writer's report; the Windows shell binds manager-start failures to a diagnostic boot/sequence watermark captured before startup. Registered legacy revoke tails retain their own ordering; frozen fixtures alone do not establish production upgrade support. | [Startup admission](../../crates/local-storage/src/migrations/startup_format.rs), [upgrade recovery action](../../crates/local-storage/src/migrations/startup_recovery.rs), [host failure facts](../../crates/host-runtime/src/storage_recovery.rs), [daemon failure projection](../../crates/daemon/src/control/startup_recovery.rs), [legacy-tail tests](../../crates/daemon/src/control/runtime/settings_profile_legacy_tests.rs), [compatibility registry](../../contracts/compatibility-support.v1.json) |
## Observation and conversation boundaries
@@ -211,6 +216,14 @@ primitives for managed files. The [borrowed native reader](../../crates/cpa-brid
retains external file identity and permission facts through access-lease admission;
it preserves readable native ACLs instead of adopting managed-file permissions.
Follow these owners for elevated-account defaults or third-party file creation.
+The [Windows Apps registration exporter](../../crates/platform/src/windows/shell_registration.rs)
+admits a controlled `reg.exe` export under a held private temporary directory;
+the existing child Job gives that process private user-SID defaults. Its explicit
+environment binds both temporary-directory variables to the same private stage,
+so standard-user export never depends on the Windows-directory scratch fallback. It
+then publishes complete bytes with protected private permissions. A repeated
+preparation must match the retained export; changed material is preserved and
+refused. Unpublished system output never occupies a final recovery filename.
Native client gates select the installed, pinned producer through
[Windows acceptance](../../scripts/windows-headless-ci.ps1). Ordinary Agent
recipes and official Qoder account recipes have separate inventories; the latter
diff --git a/docs/code-map/testing.md b/docs/code-map/testing.md
index 42d0eb90..ab4a8d79 100644
--- a/docs/code-map/testing.md
+++ b/docs/code-map/testing.md
@@ -20,6 +20,19 @@ The [Windows uninstall restore plan](../../crates/cli/src/service/restore_plan.r
keeps Codex root collaboration separate from its model-profile projection; its
portable unit cases cover owner selection and refusal, while the actual NSIS
uninstall remains the native evidence for restoring Agent files.
+The [native registration publication regression](../../crates/platform/src/windows/shell_registration.rs)
+uses a unique disposable registry key to reproduce inherited system-file permissions,
+verify private publication and refuse changed retained bytes or a failed export.
+It verifies a generic recovery boundary; it does not establish a supported
+historical Windows release or a complete ordinary-user restoration journey.
+The [standalone journal cases](../../crates/host-runtime/src/standalone_install/journal/tests.rs)
+also prove that cutover facts stop rollback before manager effects, forward
+reapplication registers only the current definition and preserves the original
+backups, and changed native entries are refused before any manager call.
+Current-installation failure pages and finite installer waits have bounded
+component and production-style checks. Development cross-build simulations are
+not supported historical Windows upgrade evidence. The general complete-source
+recovery design remains; extending the development historical matrix is separate.
Choose a user promise, then the layer that can observe its failure. Keep tests
beside that owner and preserve independent assertions. A focused filesystem
@@ -57,6 +70,7 @@ validate the oracle. The real installed management loop is in
| Observe native routing and rejected attempts | [NativeContextUpstream](../../crates/daemon/tests/support/native_context_fixture.py): count every model POST, including rejected endpoints/models/credentials; keep the ledger for positive route/history assertions |
| Prove exact Continue, concurrent routes and cancellation | [Native context](../../crates/daemon/tests/support/native_context_product.py), [boundary journey](../../crates/daemon/tests/support/native_context_boundaries.py), [boundary oracle guide](../../crates/daemon/tests/support/NATIVE_CONTEXT_BOUNDARIES.md) |
| Prove restoration of old durable state | [Frozen producer fixtures](../../crates/local-storage/src/migrations/fixtures/README.md), [crash-boundary tests](../../crates/local-storage/src/migrations/upgrade_batch_recovery_tests.rs): old bytes through the current consumer, not a new serializer pretending to be history |
+| Locate recovery material while the service is down | [Shared presentation](../../apps/desktop/tests/storage-recovery.test.mjs), [production-style geometry](../../apps/desktop/tests/v3/visual/storage-recovery-scenarios.mjs), [offline CLI formatter](../../crates/cli/src/service.rs): verified batch and source location, platform folder route and guide names; unsafe/absent locations remain unverified. Native opening/restoration needs its own installed evidence. |
| Preserve native probe failure classification | [Pi probe tests](../../crates/integrations/src/agents/pi_runtime_tests.rs), [immutable launcher](../../crates/integrations/tests/fixtures/pi-node-launcher.sh): mutable test bodies are interpreter inputs; executable availability and version/output failures have separate assertions |
| Exercise actual Desktop controls | [Browser scenario map](../../apps/desktop/tests/README.md) and native acceptance: select stable scenario IDs and require every declared outcome |
diff --git a/docs/macos-installation.md b/docs/macos-installation.md
index c642573c..a9586776 100644
--- a/docs/macos-installation.md
+++ b/docs/macos-installation.md
@@ -60,30 +60,48 @@ manually.
## Manual upgrade and removal
-1. Explicitly quit HiRoute and confirm that this service instance and its tasks have stopped.
- Closing the window only hides the application. Full lifecycle acceptance is tracked
- separately; a vanished window alone is not stop evidence.
-2. Preserve the complete previous App before replacing `/Applications/HiRoute.app`; keep
- application data, then launch the new App. A fixed location keeps the per-user symlink
- target stable. If startup asks for a recovery package, select the preserved matching App;
- HiRoute validates the full package before converting data.
-3. If the app moved or integration checks report an invalid path, use the integration Preview
- and confirmation in Settings. Resolve user-configuration drift instead of overwriting it.
- Check and, if needed, disable/re-enable the login item.
-
-Settings → Updates checks the official release catalog and validates the full DMG and App.
-Installation pauses new work, waits for existing calls and tasks, and can be cancelled while
-waiting. Both the owned daemon and Desktop exit before replacement. The previous complete
-App remains alongside the installation; storage migration uses the same startup path as a
-manual upgrade.
-
-When a storage conversion is required, startup preserves a complete private source backup
-at `storage.upgrade-backups/migration-set/source` under the application data root. If startup
-fails, use the backup button and follow `恢复说明.md`: fully stop HiRoute, retain the current
-data directory, restore the whole recorded set to its original locations, and install the
-exact previous complete App named in the guide. Do not combine databases, keys or individual
-binaries from different versions. Manual restoration discards changes made after the backup.
-HiRoute does not automatically roll back data after the migration has completed.
+Prefer **Settings → Updates**. The updater verifies the complete DMG/App, asks the
+verified candidate to check storage/recovery prerequisites before replacement,
+waits for current calls/tasks, and retains the complete previous App and handoff.
+Waiting can be cancelled. Storage startup repeats admission under its writer lock.
+
+If you must replace an App manually, fully quit HiRoute and stop its owned service
+and tasks, keep the complete original App, and preserve the data directory. There
+is no recovery-package picker. A missing-package failure does not authorize
+program-only reinstallation or downgrade. Keep every data generation, key,
+complete App and upgrade journal. Open diagnostics and obtain support to verify
+the matching recovery material and supported upgrade route. Do not infer safety
+from a generic error or the absence of a backup directory.
+
+If startup reports a resumable original batch, reopen the current version. For a
+mixed, modified, unsupported or uncertain group, do not launch an older App.
+Preserve every generation and follow the identified batch's `RECOVERY.md` or
+`恢复说明.md`. Stop HiRoute, preserve newer data with its matching program
+separately, and restore the complete recorded old group and matching complete
+App at their original locations. Never replace individual databases or mix
+WAL/SHM, keys or backup batches. Newer records remain in the separately preserved
+group; they do not appear in the restored old group. Invalid/missing material or
+keys need correction/support, not repeated retries or data deletion.
+
+Recovery instructions remain available on the startup failure page while the
+service is down. A verified resumable/restorable source shows its original batch
+ID and source directory. Use the preserved-material action, match the batch and
+read `RECOVERY.md` or `恢复说明.md` before restoration. Unknown or unverified
+locations cannot authorize recovery. Offline `hiroute service recovery --output json`
+also names the verified batch and absolute source directory.
+Insufficient-space errors require freeing unrelated files;
+retain sealed history and recovery packages. A format-changing update keeps
+configuration, credentials and routing, seals old HiRoute observations, and starts
+current history/statistics at cutover. Native Agent history is unchanged.
+
+The updater shipped by v0.3.1 launches its own installation helper. New preflight
+code cannot retrofit that helper. Use only the transition sequence validated for
+the source release; if no verified route is offered, keep the working installation
+and obtain support rather than bypassing a refusal with manual replacement.
+
+If moving the App invalidates integration paths, use the integration Preview and
+confirmation in Settings, resolve user-configuration drift, and check the login
+item. Window disappearance alone does not establish service/task shutdown.
Before removal, Preview and restore managed model/Agent integration from Settings, disable
background launch at login, explicitly quit, and delete the app. App deletion preserves data
diff --git a/docs/macos-installation.zh-CN.md b/docs/macos-installation.zh-CN.md
index 8da3ca48..19fcec51 100644
--- a/docs/macos-installation.zh-CN.md
+++ b/docs/macos-installation.zh-CN.md
@@ -47,23 +47,35 @@ CPA 随包提供,只在获准订阅路径使用。缺失、替换或不能执
## 手动升级与卸载
-1. 在 HiRoute 中明确退出,确认本次服务和任务完成停止;关闭窗口只隐藏应用。
- 生命周期完整收尾的组合验收跟踪 #93,不能仅凭窗口消失判断已停止。
-2. 先保留完整的旧 App,再替换 `/Applications/HiRoute.app`,保留应用数据后启动新版本。
- 固定位置让用户级符号链接目标不变。若启动提示选择恢复包,选择已保留的配套旧 App;
- 程序会校验完整包后才转换数据。
-3. 若移动了 App 或接入检查报告路径失效,使用设置中的接入预览和确认重新配置;
- 若出现用户配置漂移,先解决冲突,不能直接覆盖。登录项在设置中检查,必要时关闭再启用。
-
-“设置 → 版本升级”从官网检查发布版本并校验完整 DMG 和 App。安装先暂停新工作,
-等待现有调用和任务结束;等待期间可以取消升级。所属 daemon 和 Desktop 均退出后才替换 App,
-完整旧 App 保留在安装目录旁;数据迁移与手动升级使用同一启动入口。
-
-需要转换持久数据时,启动会在应用数据根目录的
-`storage.upgrade-backups/migration-set/source` 保存完整私有备份。启动失败时点击备份入口,
-按《恢复说明.md》完全停止 HiRoute、保留当前数据目录、将整组数据恢复到清单原位置,
-并覆盖安装说明指定的完整旧 App。不要混配不同批次的数据库、密钥或单个二进制。
-手工恢复会舍弃备份之后的新数据;迁移完成后程序不会自动回灌旧备份。
+优先使用 **设置 → 版本升级**。更新器校验完整 DMG/App,由已校验的新程序在替换前
+检查恢复材料与启动空间,等待现有调用和任务完成,并保留完整旧 App 和交接记录。
+等待期间可以取消;正式启动仍会在持有写入屏障时重新校验。
+
+必须手动替换时,先完全退出 HiRoute 并确认所属服务和任务停止,保留完整原版 App
+及数据目录。程序没有恢复包选择器。缺少旧包不允许单独重装旧版或原地降级。请保留所有
+数据版本、密钥、完整 App 和升级记录,打开诊断目录并联系支持核对配套材料与受支持的
+升级路径。不要仅凭通用错误码、Observation 未移动或没有备份目录就判断可以降级。
+
+若已识别可继续的原批次,重新打开当前版本继续恢复。若数据已变化、混合、格式不支持或
+状态不明,不要运行旧版。保留所有数据版本,按对应批次《恢复说明.md》或 RECOVERY.md
+停止服务,先另存新版数据及配套程序,再将完整旧组和完整旧 App 还原到记录位置。
+不要逐库覆盖、遗留不匹配的 WAL/SHM、混配密钥或使用其他批次。新版记录保留在另存的
+数据组中,不会出现在还原后的旧组。缺少密钥或完整材料时需修复前置条件或寻求支持,
+不能靠反复重试、清空目录解决。
+
+服务启动失败时也可在启动页查看具体指引。已校验且可继续或整组恢复的原批次会显示
+批次 ID 和恢复目录;通过恢复材料按钮打开后,核对批次并先读《恢复说明.md》或
+RECOVERY.md。不能根据未知或未校验的位置授权恢复。离线命令
+`hiroute service recovery --output json` 也会列出已校验批次及恢复目录的绝对路径。
+空间不足时应释放无关文件,保留封存历史和
+恢复包。存储格式切换会保留配置、凭据和路由,封存旧 HiRoute 历史,当前历史和统计从
+切换后开始;原生 Agent 历史不变。
+
+v0.3.1 已发布更新器使用自身的安装助手,新代码不能追溯修改它。只采用已验证的来源版本
+升级顺序;没有可用受支持路径时,保留正常安装并寻求支持,不要手动覆盖绕过拒绝。
+
+移动 App 导致接入路径失效时,使用设置中的接入预览和确认,先解决用户配置漂移,
+再检查登录项;不能仅凭窗口消失认定服务已停止。
卸载前先通过设置预览/恢复受管模型及 Agent 接入,再关闭“登录后后台启动”,明确退出,
然后删除 App。删除 App 默认保留数据。若选择彻底清理,确认无任务运行、已恢复接入且
diff --git a/docs/release-contracts.md b/docs/release-contracts.md
index 11ba6d4a..f3a04a94 100644
--- a/docs/release-contracts.md
+++ b/docs/release-contracts.md
@@ -29,6 +29,23 @@ resumes the original batch; missing or replaced archive material is not permissi
to initialize an empty store. Unfinished older conversion generations remain
preserved for whole-group recovery.
+Installers retain the matching old program/resources through a protected handoff bound
+to the storage root and target daemon image. Linux managed services and Windows Tasks
+consume that record without relying on the shell's environment. New candidate preflight
+checks observable prerequisites before replacement; startup repeats admission under its
+writer barrier. The actual updater shipped by the supported source must be tested. In
+particular, v0.3.1 runs its own helper: a new helper does not retrofit its precommit checks.
+A format-changing release requires a verified source/transition route before publication;
+documentation or a rebuilt same-version updater is not that evidence.
+
+On startup refusal, the storage-owned cause/action is available through the native failure
+page and `hiroute service recovery --output json`. Current production recovery does
+not offer program-only original-version reinstallation. A changed/mixed/unknown group
+cannot authorize an old-service launch, including during Windows installer rollback.
+Recognized batches may resume with the current version; complete restoration uses the
+correct verified batch, retaining newer data and program separately. Missing essential
+material requires preservation and diagnosis, not blind retries or empty initialization.
+
Startup does not enumerate, hash, copy or normalize historical Observation
contents. The source manifest verifies copied recovery material and binds the
sealed directory's native identity; it does not claim eager full-content integrity
diff --git a/docs/standalone-cli.md b/docs/standalone-cli.md
index 06c92afd..cf1754e6 100644
--- a/docs/standalone-cli.md
+++ b/docs/standalone-cli.md
@@ -101,6 +101,62 @@ Installation fails if `/Applications/HiRoute.app`, `~/Applications/HiRoute.app`,
Desktop Local Control exists. Stop and uninstall standalone before switching in the other
direction.
+## Storage upgrade recovery
+
+Before replacing an installed program, the verified candidate performs read-only
+preflight. When a history-format cutover is required, the installer retains the
+complete original program/resources and installation records in private service
+state; the daemon receives that handoff directly, including under systemd.
+Current-format repair skips this archival copy and its extra space reserve.
+Repeating the exact same-version installed daemon also preserves existing handoffs
+without requiring a newer preflight helper from an older package; normal storage
+admission still runs when the service starts. Failed
+preparation removes only its unpublished copy; once the handoff may have been
+consumed, its material is retained even after later installation rollback.
+Do not delete `upgrade-packages`, `upgrade-package.json`, sealed history or
+`storage.upgrade-backups` to make room for an upgrade. Budget their disk use.
+
+If startup fails, use `hiroute service recovery --output json` even while Local
+Control is unavailable. It reports the storage-owned cause and action plus the
+startup diagnostic location. Missing packages do not authorize program-only
+downgrade. Preserve data, keys, programs and journals; follow diagnostic/support
+steps when necessary material is unavailable. A resumable batch uses the current
+program. Whole-group recovery uses that batch's `RECOVERY.md`, `恢复说明.md` and,
+when present, `PROGRAM-LOCATIONS.md`: stop the service and automatic restarts,
+preserve newer data/program separately, restore all stores/keys/Observation and
+recorded auxiliary files, then restore the matching program/resources and service
+registration at their recorded locations. Reload the manager and verify actual
+Control/Gateway readiness and a real request. Installation-command success alone
+is insufficient.
+
+Explicit headless operators may still provide the absolute complete old-package
+directory via `HIROUTE_RECOVERY_PACKAGE` on the daemon's first sealing startup.
+For systemd, first stop the failed service with `hiroute service stop --output json`.
+Run `systemctl --user edit ai.hiroute.cli.service` and add a temporary override:
+
+```ini
+[Service]
+Environment="HIROUTE_RECOVERY_PACKAGE=/absolute/path/to/verified-complete-old-package"
+```
+
+Use the actual retained package path, then run `systemctl --user daemon-reload`
+and `hiroute service start --output json`. Inspect `hiroute service recovery
+--output text` if startup still refuses. After successful cutover, remove only
+this temporary `Environment` entry, reload the manager, restart the service and
+verify actual readiness and a request. Preserve unrelated overrides; do not use
+`systemctl revert` to discard them.
+
+Set it on the foreground daemon's actual invocation when running without a manager. Exporting a variable in a shell and calling systemctl
+does not deliver it to the managed daemon. Ordinary installer upgrades use their
+protected handoff instead. Missing keys, unverified sources and unknown phases
+require preservation and diagnosis/support; repeated restarts cannot recreate them.
+The exact unchanged-program repair path does not require a new preflight protocol;
+changing program bytes requires a candidate that implements the supported checks.
+
+A format change preserves configuration, credentials and routing and seals old
+HiRoute observations. Current history/statistics start at cutover; native Agent
+history is unchanged. New current-format records survive ordinary restarts.
+
## Start and verify real readiness
```sh
diff --git a/docs/standalone-cli.zh-CN.md b/docs/standalone-cli.zh-CN.md
index 5704d5ab..c406b98f 100644
--- a/docs/standalone-cli.zh-CN.md
+++ b/docs/standalone-cli.zh-CN.md
@@ -129,6 +129,49 @@ group/world 可写的 Skill 父目录会导致安装在写入前失败。同一
若存在 `/Applications/HiRoute.app`、`~/Applications/HiRoute.app` 或活动 Desktop Local
Control,安装会失败。反向切换时也应先停止并卸载 standalone。
+## 存储升级与恢复
+
+已校验的新程序在替换前先做只读预检。确实需要历史格式切换时,安装器才在私有服务状态目录
+保留完整原版程序、资源与安装记录;daemon 直接读取交接记录,systemd 启动也适用,
+不依赖终端继承变量。同格式修复不复制历史程序包,也不要求这份副本的额外预留空间。
+重装同版本、同一 daemon 镜像时也保留原交接记录,不要求旧包支持新增预检协议;
+服务启动仍执行原有存储校验,不因此获得旧版兼容或降级权限。
+准备失败只清理本次未发布的副本;交接记录可能已被读取后,即使后续安装回滚,也保留材料。请为恢复材料预留空间,不要删除 upgrade-packages、
+upgrade-package.json、封存历史或 storage.upgrade-backups 来绕过空间检查。
+
+服务无法启动时,也可运行 `hiroute service recovery --output json` 查看存储方确定的
+原因、恢复动作与诊断位置。缺包不允许单独重装旧程序或原地降级;请保留数据、密钥、
+完整程序和记录,必要材料缺失时按诊断与支持指引处理。可继续的原批次使用当前版本恢复。必须整组还原时,
+按对应批次的《恢复说明.md》、RECOVERY.md 及可用的 PROGRAM-LOCATIONS.md,停止服务
+和自动重启,先另存新版数据及配套程序,再还原全部数据库、密钥、Observation 和记录的
+辅助文件,最后还原原版程序、资源、安装记录与服务注册。重新加载管理器后确认实际
+Control/Gateway 就绪及一次真实请求;不能只看安装命令退出成功。
+
+显式无界面运维仍支持在首次封存启动时用 HIROUTE_RECOVERY_PACKAGE 提供完整旧包的
+绝对目录。变量必须传给真正的前台 daemon,或写入服务管理器支持的环境配置;在终端
+export 后调用 systemctl 不代表后台进程收到了变量。正常安装器使用受保护交接记录。
+缺少密钥、原材料不可校验或阶段不明时应保留材料并诊断/求助,反复重启不能重建缺失数据。
+修复同一份未变化的程序不要求新增预检协议;程序字节发生变化时,需要候选支持预检。
+
+格式切换保留配置、凭据和路由,封存旧 HiRoute 历史,当前历史和统计从切换后开始;
+原生 Agent 历史不变,当前格式的新记录在正常重启后继续保留。
+
+
+使用 systemd 手工补充旧恢复包时,先运行 `hiroute service stop --output json`
+停止失败服务,再运行 `systemctl --user edit ai.hiroute.cli.service`,添加临时配置:
+
+```ini
+[Service]
+Environment="HIROUTE_RECOVERY_PACKAGE=/absolute/path/to/verified-complete-old-package"
+```
+
+将路径替换为实际校验过的完整旧包目录。运行 `systemctl --user daemon-reload`,
+再运行 `hiroute service start --output json`。仍被拒绝时,运行
+`hiroute service recovery --output text` 查看原因、下一步与诊断目录。
+升级成功后,只移除此临时环境项,重新加载并重启服务,确认实际就绪和一次请求。
+保留其它用户配置,不要用 `systemctl revert` 一并删除它们。仅在终端导出变量,
+不会把该变量交给 systemd 管理的进程。
+
## 启动并确认真实就绪
```sh
diff --git a/docs/standalone-windows.md b/docs/standalone-windows.md
index 1f8d9478..af95fc8f 100644
--- a/docs/standalone-windows.md
+++ b/docs/standalone-windows.md
@@ -99,6 +99,22 @@ After a successful upgrade, obsolete verified version directories are removed
once shell rollback no longer needs them. Uninstall removes the current verified
version too. Changed or foreign entries are preserved for repair.
+## Storage upgrade recovery
+
+Windows has no supported released predecessor in this first release. General
+complete-group recovery remains available, but development-build simulations do
+not establish a historical support promise or a required released-upgrade matrix.
+
+When an admitted format-changing cutover is required, a Task-started daemon reads the installer's protected matching-old-package handoff;
+it does not depend on an environment variable from another PowerShell session.
+The native installer checks the verified candidate before changing programs and
+retains the previous package while recovery needs it. For startup refusal, use
+`hiroute service recovery --output json` and the instructions in
+[Windows recovery](windows-desktop-installation.md#storage-format-failure-and-whole-group-recovery).
+Keep all data, keys and packages. Program-only downgrade is not offered. Use an
+admitted current-batch resume or verified complete-group recovery; preserve and
+diagnose state that cannot be admitted. Verify an actual Gateway request after repair.
+
## Native evidence
[Validation routing](validation-routing.md#windows-iteration-and-release-validation)
diff --git a/docs/validation-routing.md b/docs/validation-routing.md
index 2729d60e..37a2b25f 100644
--- a/docs/validation-routing.md
+++ b/docs/validation-routing.md
@@ -171,7 +171,13 @@ native Quit menu item, then requires that process to exit. It does not kill a
process or stop the background service; an unavailable or ambiguous icon/menu
is an observation failure that must be inspected before retrying.
-`--action install` runs the measured NSIS `/S` entry. For a different installed
+`--action install` runs the measured NSIS `/S` entry. Its specific 720-second
+whole-installer watchdog includes the product adapter's 600-second install request
+and NSIS extraction/hooks; CLI/UI watchdogs and product request deadlines stay
+unchanged. `installer-process.json` records elapsed time, bounded transaction
+phase changes and the actual installer exit. A committed marker without that exit
+does not pass installation. On timeout inspect the retained transaction and any
+remaining product children before recovery or another attempt. For a different installed
candidate, `--from-product OLD_BUNDLE_ID` verifies the old images before invoking
the new installer. Preserve existing data and identify both packages in the
result. Different source revisions carrying the same semantic version prove a
@@ -183,6 +189,8 @@ Administrators SID, including deny-only membership. All native observations and
screenshots remain in ignored, private evidence.
`native-files` captures the fixed Codex/Claude configuration files and inventories
both collaboration and management Skill directories for restoration readback.
+It also fingerprints Codex sessions/history without copying their contents; compare
+immediately around installation/restoration, with no Codex call in between.
`scroll` uses a recent screenshot's window geometry and pointer coordinates, plus
an explicit `--scroll-direction up|down`; it sends a bounded native mouse wheel
event to that foreground window. `codex-call` runs the configured real Codex CLI
@@ -242,6 +250,24 @@ Content-addressed validator helpers are verified and published once by atomic
rename. Wait/status/collection never overwrite helper files that a running
standard-user task may be importing.
+The generic complete-source, matching-program and native-state recovery design
+remains in production. A Windows development-build historical upgrade/restore
+matrix is not required first-release acceptance and does not establish a supported
+released predecessor. Preserve prior simulation evidence; do not mutate an
+existing installation to extend that deferred matrix.
+
+`recovery-lock-ui` requires a recent inspection of the currently installed product
+and an accessible existing input desktop. It starts from actual Gateway readiness,
+stops the owned service, holds only an owned startup-lock file handle and opens the
+real bundled failure page. It observes both languages through the visible language
+button, releases its handle, quits and reopens the same installed Desktop, then
+checks actual Control/Gateway readiness. It never corrupts databases, changes keys,
+manufactures recovery reports or launches an older program. Its screenshots and
+native UI observations remain private evidence, separate from fixture parser tests.
+`recovery-file-use-ui` uses the same bounded sequence against the current
+Control file using only the admitted current installation. Both lock cases require offline current-version
+retry advice rather than borrowing a retained source as a reason to restore old data.
+
Stage separate product and harness bundles when reusing an unchanged product for
a test-only repair. Results record both full revisions, binary hashes, driver hash,
client hashes, actual OS/session/elevation and exactly one test outcome. Zero exit
diff --git a/docs/windows-desktop-installation.md b/docs/windows-desktop-installation.md
index 542459a1..0c61df1d 100644
--- a/docs/windows-desktop-installation.md
+++ b/docs/windows-desktop-installation.md
@@ -110,6 +110,103 @@ recovery succeeded. The next shell start reads the private outcome and can recov
an interrupted transaction after the installer is no longer active. An unresolved
file or service conflict stays on the bundled failure page with a diagnostics path.
+When starting a stopped service, the shell also handles a failed CLI readiness wait.
+It captures a diagnostic watermark before the start request and accepts only a new
+failed startup record. Old, incomplete or unreadable diagnostics leave the manager
+error intact. The typed current cause can explain a lock, missing key or upgrade
+refusal without borrowing an earlier batch's advice.
+
+## Windows support and acceptance scope
+
+This is the first supported Windows release, with no supported released Windows
+predecessor. General complete-group recovery, matching programs/native-state
+preservation and the existing transaction safety boundaries remain available.
+Their presence is not a historical compatibility promise. Development builds and
+simulated cross-build replacements are not released-version upgrade evidence;
+expanding their historical upgrade/restore matrix is separate follow-up work.
+
+Current installation, failure/interruption repair, actionable errors and data
+protection remain required. Ordinary current-format repair does not duplicate the
+complete Desktop or export Task/Apps registration merely to support a historical
+simulation. Those complete-source operations are used when authoritative candidate
+preflight actually requires a format-changing history cutover. Retained recovery
+material is never deleted to narrow acceptance.
+
+## Storage-format failure and whole-group recovery
+
+Before NSIS replaces installed files, its verified candidate daemon checks the
+stopped-source requirements. When an actual history cutover is required,
+preparation retains both the complete previous
+Desktop (including shell, uninstaller and inventory) and standalone version root,
+the native transaction's CLI/daemon/Skill/documentation file map, owned native Task XML and definition,
+login choices and the fixed current-user HiRoute Apps registration. The protected
+handoff binds this material to the storage root and new daemon image. Space checks
+combine simultaneous allocations on the same native volume and check separate
+program/data volumes separately. Candidate preflight runs before replacement; startup
+revalidates under the storage writer barrier. Package cleanup retains the old
+source while its handoff is needed. This does not use macOS App discovery or
+assume that a PowerShell variable is inherited by the logged-on Task.
+
+The bundled failure page displays the storage-owned reason and recovery action
+even when the daemon and console cannot start. It distinguishes missing/invalid
+packages, low space, unavailable keys and unknown state. Fix a stated prerequisite
+before retrying. After a completed readiness wait, it uses the latest typed daemon
+startup failure; a dependency or Gateway failure cannot borrow an old storage
+report. Installer, manager-command and console failures have their own guidance.
+An incomplete installation is identified independently of service readiness and
+offers the exact installer repair path, without an unproven storage retry or old
+batch location. A verified resumable/restorable source shows its original batch
+ID and relative source directory, including long names without clipping. From the
+parent of the displayed local log directory, open that source directory and read
+`RECOVERY.md` or `恢复说明.md`, then `PROGRAM-LOCATIONS.md` where present. Missing,
+unsafe or unverified batch locations must not be presented as verified material.
+Resume an admitted batch with the current program; never start
+an old program against newer/mixed data. Shell rollback checks storage cutover
+facts before reinstalling or starting an old service. An uncommitted shell journal
+is not proof that business data is unchanged.
+
+If an upgrade starts the new service but cannot finish installation, keep both
+complete program versions, all data and the installation journals. Close files
+reported as in use and check access and free space, then rerun the **same complete
+current installer**. Its early recovery verifies the accepted payload before a
+forward repair; it does not replace the original recovery batch or launch the old
+daemon over current data. A changed package or native file is refused. If repair
+still cannot be verified, preserve the material and use the verified batch's
+whole-group guide or obtain support. Check actual service/Gateway readiness and a
+request after repair; do not infer recovery from installer or Task exit alone.
+
+When complete restoration is required and the source is verified, stop the owned Task/daemon and automatic starts, keep
+newer storage with its matching program separately, and follow the exact verified
+batch's Chinese/English generated guide. Restore all stores, keys, Observation and
+recorded auxiliary locations together, then the matching full package and Task
+registration through the platform installation path. Verify actual service and
+Gateway readiness and a request. Missing keys or a substituted/incomplete source
+cannot be repaired by blind retry or choosing another old release. Inspect safe
+startup diagnostics and obtain support while retaining every generation.
+
+Use `hiroute service recovery --output json` for an offline report. Verified
+resume/restore guidance includes the exact batch and absolute source directory,
+derived from the actual storage root. Windows Server
+and Windows 11, ordinary-user and administrator sessions, and released versus
+development packages retain separate evidence boundaries.
+
+### Chinese recovery quick guide
+
+本次是 Windows 首个受支持版本,没有已发布旧版的历史兼容承诺。通用完整恢复能力和数据保护仍保留;开发构建模拟不等于正式升级支持。
+安装或启动失败时,先保留完整程序、全部数据、密钥、安装记录与恢复包。
+文件占用、权限或空间问题应按当前提示处理后再试;不要清空历史、批量修改权限或删除安装记录。
+如果新服务已启动但安装尚未完成,解除占用并核对权限、空间后,重新运行**同一当前版的完整安装器**。
+安装器会核对原先接受的程序包与任务注册,再继续完成安装;程序或记录不符时会拒绝,不能换任意旧安装器覆盖。
+修复之后检查 `hiroute system status --output json` 中的服务与 Gateway 实际就绪状态,并完成一次真实请求。
+
+服务与控制台无法启动时,使用安装包自带的故障页面,或离线运行 `hiroute service recovery --output json`。
+已验证的恢复材料会给出原批次 ID、源目录与说明文件名;从页面所示日志目录的上级目录定位该源目录,
+先读该批次的 `恢复说明.md` 或 `RECOVERY.md`,再读 `PROGRAM-LOCATIONS.md`。
+整组恢复前停止当前账户的 Task、守护进程、CPA 与自动启动,将新版完整数据和配套程序另存,
+再按记录的位置与权限还原旧数据、全部密钥、历史、完整程序和原 Task 注册,并核对原登录启动选择。
+不要逐库覆盖、混用不同批次,或让旧程序读取新版数据。恢复后仍需检查旧配置、路由、历史与一次真实请求。
+缺少密钥、完整原版程序、有效批次,或无法核对文件归属时,保留现场与诊断并联系支持;反复重试或任意降级不能补齐这些材料。
+
## Uninstall boundaries
Agent restoration uses production Preview/Apply and waits for the resulting
diff --git a/issue-spec/specs/getting-started/spec.md b/issue-spec/specs/getting-started/spec.md
index d70cf133..41ba9bcd 100644
--- a/issue-spec/specs/getting-started/spec.md
+++ b/issue-spec/specs/getting-started/spec.md
@@ -308,6 +308,16 @@ The Windows shell SHALL select a newer stable Windows x64 Desktop release from t
- **WHEN** recovery reported an earlier replacement failure and a subsequent manual installer commits the verified new core and shell
- **THEN** the persisted startup and Settings outcome reflects the committed installation instead of claiming that the prior version was restored, and interrupted committed-phase reporting completes idempotently through recovery.
+#### Scenario: Same-current-installer repair after storage cutover
+
+- **WHEN** storage may have changed and a prepared Windows installation is retried with the same complete accepted current package
+- **THEN** early installer recovery verifies that candidate before generic rollback, preserves existing data/recovery material and continues the current installation. A prepared standalone journal can proceed only after the complete current package, target namespace and owned Task definition match; it never registers the older daemon. Reapplication preserves current data and retained recovery material, commits idempotently and checks actual service/Gateway readiness. This is current-installation repair, not support for an unpublished historical Windows source.
+
+#### Scenario: An interrupted installation cannot be safely matched
+
+- **WHEN** the candidate, current files, native registration or prepared journal cannot be verified for safe current-version repair
+- **THEN** recovery preserves both program versions, all data and journals, refuses automatic old-program launch and explains preservation, correction of stated prerequisites, exact-current-installer repair where admitted, and diagnostic/support guidance when repair remains unavailable. Installer exit alone does not establish restored service.
+
Source SPEC comments:
- https://github.com/higress-group/HiRoute/issues/132#issuecomment-6219734656
diff --git a/issue-spec/specs/local-data-and-diagnostics/spec.md b/issue-spec/specs/local-data-and-diagnostics/spec.md
index ac81f8a4..3283b744 100644
--- a/issue-spec/specs/local-data-and-diagnostics/spec.md
+++ b/issue-spec/specs/local-data-and-diagnostics/spec.md
@@ -240,6 +240,83 @@ HiRoute SHALL preserve supported old Observation history unchanged in a protecte
Source SPEC comments:
- https://github.com/higress-group/HiRoute/issues/151#issuecomment-6248902605
+### Requirement: Upgrade recovery actions come from whole-group storage admission
+
+Windows has no supported released predecessor in its first release. Generic complete-group recovery and native-state preservation remain required where applicable; an unpublished development build or simulated upgrade SHALL NOT establish historical release support or require an exhaustive historical acceptance matrix.
+
+HiRoute SHALL provide a bounded typed startup cause and storage-owned recovery action on macOS, Linux and Windows, including while the daemon or console is unavailable. Missing/invalid recovery packages, insufficient space, missing keys, access failures, unsupported/corrupt input and execution/unknown states SHALL retain their safely established meaning. Unknown values SHALL preserve material and SHALL NOT authorize downgrade. Stable legacy startup failure envelopes remain supported; a private bounded recovery report may carry additional safe facts without adding arbitrary error strings or filesystem authority.
+
+Current recovery actions SHALL be prerequisite correction and current-version retry, verified current-batch resume, verified complete-group restoration, or preservation and diagnosis. Program-only original-version reinstallation SHALL NOT be offered: no current production entry establishes the required whole-group compatibility proof. Missing packages, equal SQL markers, an unmoved Observation directory and absence of a backup SHALL NOT authorize downgrade. Diagnostics and transient lock files are not business data.
+
+Installers SHALL retain the complete matching previous program and resources before an admitted incompatible replacement. Ordinary current-format installation/repair SHALL NOT require unnecessary complete-program archival or Task/Apps export. Before allocating a standalone recovery archive for a changed candidate, preflight SHALL determine whether a history cutover is required. Repair with the exact same-version installed daemon image SHALL preserve existing recovery handoffs without requiring a newer preflight protocol from the old package; it SHALL NOT grant storage compatibility, downgrade authority or skip normal startup admission. Failed preparation SHALL discard only its own unpublished archive; a handoff that may have been published or consumed SHALL retain its recovery material even if later installation rollback succeeds. Native standalone startup SHALL obtain verified recovery input through an installation-owned storage-root and target-image-bound handoff rather than assume inheritance of the invoking shell's environment. The explicit absolute `HIROUTE_RECOVERY_PACKAGE` operator entry remains supported. Cleanup SHALL retain material still required by installation or storage recovery. Windows shell rollback SHALL refuse automatic original-program launch when storage has changed or cannot be established as compatible.
+
+The verified candidate SHALL check safely observable recovery/space prerequisites before installed-program replacement, and startup SHALL repeat authoritative admission under its writer barrier. Provisional checks SHALL NOT grant later write authority. Existing active-work waiting, cancellation, ownership and finite startup limits remain. A source release's actual shipped updater and any required transition sequence SHALL be validated; installing a new updater does not retroactively add checks to an old executable.
+
+Recovery presentation SHALL distinguish correcting prerequisites, current-batch resume, verified whole-group restoration and unavailable/unknown material. It SHALL identify the correct original batch rather than select a directory by presence, provide Chinese/English platform instructions, preserve newer data and its matching program separately before restoration, and require actual service readiness and a request before claiming successful restoration. Missing essential material SHALL lead to preservation and diagnostic/support guidance rather than a promise that retries, manual overwrite or an arbitrary older release will recover it.
+
+#### Scenario: Missing package does not authorize program-only downgrade
+
+- **WHEN** startup lacks a matching complete previous package
+- **THEN** consumers preserve all data, keys, programs and journals and provide diagnostic/support steps; they do not offer program-only downgrade without a production whole-group compatibility proof.
+
+#### Scenario: Windows stopped-service startup returns a typed failure
+
+- **WHEN** the shell starts a stopped service and the CLI returns failure after waiting for readiness
+- **THEN** a newly observed daemon startup failure supplies the bounded cause and admitted recovery action; unchanged, incomplete or unreadable previous diagnostics cannot replace the current manager failure. Non-storage failures do not borrow old storage advice.
+
+#### Scenario: Current-format repair requires no historical archive
+
+- **WHEN** a verified standalone candidate reports that no history cutover is required
+- **THEN** repeated installation or repair creates no complete old-package copies, imposes no archival space reserve and leaves existing recovery handoffs, backups and business data unchanged.
+
+#### Scenario: Changed or uncertain group
+
+- **WHEN** core migration/cutover has begun, an original authority changes, a phase is corrupt/unknown or a prior batch prevents proving compatibility
+- **THEN** no consumer offers unverified program-only downgrade and no installer automatically starts an older daemon; all generations and journals remain available for current-version recovery or the corresponding complete-group guide.
+
+#### Scenario: Prepared native installation after possible storage writes
+
+- **WHEN** Windows installation recovery observes storage cutover facts while a native install journal is still prepared
+- **THEN** generic rollback refuses before manager or file effects. Only an independently matched complete accepted current package and its owned native definition may reapply that journal forward; changed native entries or mismatched packages remain preserved and refused. The existing original source is not resealed or replaced, and a successful current repair does not imply that an older program can read the current group.
+
+#### Scenario: A retained source does not authorize blind resume
+
+- **WHEN** an original complete batch is verified but the current generation is damaged or its phase cannot be admitted
+- **THEN** its existence authorizes only the matching complete-group restoration target; it does not grant current-version resume. Resume after fresh Observation initialization failure requires successfully admitted core stores and an unpublished live Observation root, with the same verified original batch still available.
+
+#### Scenario: Managed standalone upgrade
+
+- **WHEN** Linux systemd or a Windows ordinary-user Task starts the installed candidate after an admitted format-changing upgrade
+- **THEN** the matching complete old package is retained and its protected handoff is verified against the storage root and candidate image; package cleanup cannot delete it prematurely and an unrelated terminal variable is not required for ordinary installer operation.
+
+#### Scenario: Complete Windows Desktop recovery material
+
+- **WHEN** verified candidate preflight requires a format-changing cutover over an existing Desktop
+- **THEN** preflight precedes installed-file replacement and retains both program namespaces, shell/uninstaller/inventory, the installation owner's complete native file map, verified native Task XML/definition/login choices and fixed current-user Apps registration. Space budgets combine allocations sharing a volume and keep separate volumes independent. Whole-group recovery restores those matching materials under the same ordinary account, with a batch-specific bilingual guide, import of the exact original Task and actual readiness/request verification. Instructions use published lifecycle commands and Task Scheduler rather than unpublished CLI installation verbs. A same-payload repair preserves the accepted original handoff instead of replacing it with the current program.
+
+#### Scenario: Prerequisite refusal and cancellation
+
+- **WHEN** preflight finds unavailable/unverified material or insufficient recovery space, or the user cancels while waiting for work
+- **THEN** replacement is not committed, the existing installation remains usable when verified, and the user receives the specific correction or cancellation state; startup rechecks races before any incompatible data mutation.
+
+#### Scenario: Failed startup without a console
+
+- **WHEN** the daemon cannot start or an upgrade batch is interrupted
+- **THEN** Desktop, the Windows bundled failure surface and the installed CLI expose the bounded cause and admitted recovery action without depending on the normal server; known resumable batches use the current program, while missing/substituted material never appears as a valid restore target.
+
+#### Scenario: Locate the exact admitted recovery material offline
+
+- **WHEN** a failure admits current-batch resume or complete-group restoration
+- **THEN** the failure surface displays the verified original batch ID, source directory and guide filenames. Windows explains the folder route from its displayed log directory; macOS provides the preserved-material action. Long portable names wrap without hiding content in Chinese and English. The offline CLI names the absolute source directory derived from its actual storage root. Missing/unsafe locations and unrecognized causes cannot grant located recovery or resume.
+
+#### Scenario: Correct a file prerequisite before considering restoration
+
+- **WHEN** the current failure establishes a file-use or access prerequisite, including while a complete original source is retained
+- **THEN** consumers offer correction followed by current-version retry, without borrowing that source as a reason to restore old data. A key/unsupported-format diagnostic may retain a complete-group target only when the storage owner revalidates that exact batch and the recorded cause matches the current failure; a diagnostic alone never grants original-program reinstall, current-batch resume or restoration of unverified material.
+
+Source Issue:
+- https://github.com/higress-group/HiRoute/issues/176
+
### Requirement: Optional capacity retention uses restrained observation maintenance
HiRoute SHALL allow the local installation owner to save or disable one durable active-observation capacity threshold. The default threshold SHALL be 20 GB (20,000,000,000 bytes), including a fresh generation after old-history sealing. The owner may change it or explicitly disable capacity expiry; a disabled choice SHALL remain disabled across restart. Seven-day age retention remains independent. When enabled and exceeded, the existing lifecycle SHALL retire oldest eligible completed-request detail before seven days, preserving in-flight writes, live shared references, deletion/replay barriers, lawful non-content aggregates and recovery backups. Retained observations remain lossless; policy removals SHALL be distinct from representation savings and actual physical release. Accounting/reclamation SHALL use spaced bounded work, yielding and idle/failure/no-progress backoff rather than sustained high CPU or an unbounded catch-up loop. HiRoute SHALL report actual measured usage and pending/blocked release with its reason, without promising an instantaneous hard cap, reporting reusable pages as released, or dropping acknowledged writes. Changes/disabling affect uncommitted future retirement and do not restore already expired history.
diff --git a/issue-spec/specs/runtime-diagnostic-logging/spec.md b/issue-spec/specs/runtime-diagnostic-logging/spec.md
index 66260551..ced72fd6 100644
--- a/issue-spec/specs/runtime-diagnostic-logging/spec.md
+++ b/issue-spec/specs/runtime-diagnostic-logging/spec.md
@@ -109,6 +109,23 @@ normal user's preference, business parameters, security gates, or success criter
Failure/cancellation retains available safe logs and evidence gaps with normal
owned-process cleanup. Logging success is not a substitute for the real smoke path.
+### Requirement: Startup recovery guidance remains available before service readiness
+
+Storage startup SHALL retain bounded typed cause/action facts through its existing local startup channels without requiring a functioning console. The CLI and native failure surfaces SHALL use the storage-owned action rather than infer downgrade permission from a raw error, generic code or backup-directory presence. Unknown reasons, unsupported records and stale original-state bindings SHALL receive a conservative preserve-and-diagnose presentation. Diagnostic exports SHALL exclude complete private recovery backups, credential bytes and arbitrary native error output.
+
+#### Scenario: Admission cannot write a recovery report
+
+- **WHEN** root access, an existing writer lock or an unavailable authority key refuses startup before the storage writer barrier
+- **THEN** the current attempt carries its closed cause through the startup failure channel and diagnostics without writing or replacing a report owned by another writer. Offline consumers may explain that cause with preserve-and-diagnose only; diagnostic records never authorize downgrade, resume or restoration. A later successful/unfinished/unknown startup cannot borrow an earlier admission reason.
+
+#### Scenario: Storage refusal while the server is unavailable
+
+- **WHEN** startup refuses missing recovery material, unavailable keys, low space or an unknown upgrade state
+- **THEN** the installed failure surface and offline CLI can explain the safely established cause and next action without contacting the failed daemon; service availability is not fabricated from manager-command success.
+
+Source Issue:
+- https://github.com/higress-group/HiRoute/issues/176
+
## Implementation references
- [Typed events and records](../../../crates/diagnostics/src/record.rs),
diff --git a/scripts/install-standalone.py b/scripts/install-standalone.py
index 7fcc8512..c5cbb5a8 100755
--- a/scripts/install-standalone.py
+++ b/scripts/install-standalone.py
@@ -409,6 +409,8 @@ def service_bytes(paths, daemon, cpa, cpa_digest):
f"ExecStart={quote(daemon)} --role all --standalone --cpa-binary {quote(cpa)} --cpa-sha256 {cpa_digest}\n"
"Restart=on-failure\nRestartSec=2\nTimeoutStopSec=45\n"
f"Environment=HOME={quote(home)}\nEnvironment={quote('PATH=' + native_path)}\n"
+ f"Environment={quote('XDG_STATE_HOME=' + str(paths['state'].parent))}\n"
+ f"Environment={quote('XDG_RUNTIME_DIR=' + str(paths['runtime']))}\n"
"NoNewPrivileges=true\nPrivateTmp=true\n\n[Install]\nWantedBy=default.target\n"
)
path = home / ".config/systemd/user/ai.hiroute.cli.service"
@@ -696,6 +698,154 @@ def console_component(paths, desired):
return staged_file(destination, (json.dumps(config, sort_keys=True) + "\n").encode(), 0o600), destination
+def candidate_preflight(program, storage, package):
+ # Only our verified, short-lived helper may be killed. Never buffer arbitrary
+ # child diagnostics or start a business service for a provisional check.
+ try:
+ child = subprocess.Popen([str(program), "--upgrade-preflight", "--storage-root", str(storage), "--recovery-package", str(package)], stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL)
+ try:
+ code = child.wait(timeout=15)
+ body = child.stdout.read(16 * 1024 + 1)
+ finally:
+ if child.poll() is None:
+ child.kill()
+ child.wait()
+ child.stdout.close()
+ except (OSError, subprocess.TimeoutExpired) as error:
+ raise ValueError("candidate upgrade preflight is unavailable; the installed program was not replaced. Preserve data and use the verified transition route or startup diagnostics") from error
+ try:
+ report = load_json_bytes(body)
+ except (ValueError, UnicodeError) as error:
+ raise ValueError("candidate cannot perform the required upgrade preflight; use the supported transition release") from error
+ fields = {"schema", "history_cutover_required", "required_bytes", "available_bytes", "recovery"}
+ if (len(body) > 16 * 1024 or not isinstance(report, dict) or set(report) != fields
+ or report["schema"] != "hiroute.upgrade-preflight/v1"
+ or type(report["history_cutover_required"]) is not bool
+ or any(type(report[name]) is not int or not 0 <= report[name] <= 2**64 - 1 for name in ("required_bytes", "available_bytes"))):
+ raise ValueError("candidate upgrade preflight is invalid; the installed program was not replaced. Preserve data and use the verified transition route")
+ if code or report["recovery"] is not None:
+ recovery = report["recovery"]
+ cause = recovery.get("cause") if isinstance(recovery, dict) else "unknown_state"
+ allowed = {"missing_package", "invalid_package", "insufficient_space", "access_denied", "locked", "missing_key", "unsupported_format", "namespace_unavailable", "migration_failed", "unknown_state"}
+ raise ValueError("upgrade preflight refused: " + (cause if cause in allowed else "unknown_state") + "; the installed program was not replaced. Preserve data and old packages, correct the prerequisite before retrying")
+ return report
+
+
+@contextmanager
+def retain_recovery_package(paths, current, target_daemon, version):
+ """Preserve the complete installed program/resources before replacement.
+
+ This handoff goes to the daemon through its private state directory, so
+ systemd/launchd does not depend on inheriting the invoking shell's environment.
+ """
+ if current is None:
+ yield None
+ return
+ old_program, old_resources, _service = validate_marker(paths, current)
+ # Repeating the exact installed writer introduces no new format boundary.
+ # Older packages need not implement this candidate's provisional protocol.
+ # This grants no data compatibility advice and leaves every handoff intact;
+ # the daemon still performs its normal authoritative startup admission.
+ if current["version"] == version and digest(target_daemon) == digest(old_program / "hirouted"):
+ yield None
+ return
+ # This provisional call determines cutover before allocating any archive.
+ # A cutover repeats preflight with the complete retained program/resources.
+ report = candidate_preflight(target_daemon, paths["state"] / "storage", old_program)
+ if not report["history_cutover_required"]:
+ yield None
+ return
+ def footprint(path):
+ metadata = path.lstat()
+ if path.is_symlink() or not (path.is_file() or path.is_dir()):
+ raise ValueError("recovery package contains an unsafe entry")
+ if path.is_dir():
+ return sum(footprint(entry) for entry in path.iterdir())
+ return metadata.st_size
+ required = footprint(old_program) + footprint(old_resources) + 256 * 1024 * 1024
+ if shutil.disk_usage(paths["state"]).free < required:
+ raise ValueError("Insufficient space on the service-state volume for the matching old package; free unrelated space before retrying")
+ parent = paths["state"] / "upgrade-packages"
+ parent.mkdir(mode=0o700, exist_ok=True)
+ if parent.is_symlink() or not parent.is_dir():
+ raise ValueError("unsafe recovery package directory")
+ retained = Path(tempfile.mkdtemp(prefix="old-package-", dir=parent))
+ retained_identity = retained.stat()
+ handoff = None
+ try:
+ files = {}
+ def copy_verified_tree(source, target, prefix):
+ source_fd = os.open(source, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+ try:
+ target.mkdir(mode=0o700)
+ for name in os.listdir(source_fd):
+ metadata = os.stat(name, dir_fd=source_fd, follow_symlinks=False)
+ relative = prefix + "/" + name
+ if stat.S_ISDIR(metadata.st_mode):
+ copy_verified_tree(source / name, target / name, relative)
+ elif stat.S_ISREG(metadata.st_mode):
+ fd = os.open(name, os.O_RDONLY | os.O_NOFOLLOW, dir_fd=source_fd)
+ try:
+ before = os.fstat(fd)
+ if (before.st_dev, before.st_ino) != (metadata.st_dev, metadata.st_ino):
+ raise ValueError("old package changed before preservation")
+ hashed = hashlib.sha256()
+ with os.fdopen(os.open(target / name, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600), "wb") as output:
+ remaining = before.st_size
+ while remaining:
+ chunk = os.read(fd, min(remaining, 64 * 1024))
+ if not chunk:
+ raise ValueError("old package was truncated during preservation")
+ output.write(chunk)
+ hashed.update(chunk)
+ remaining -= len(chunk)
+ if os.read(fd, 1):
+ raise ValueError("old package grew during preservation")
+ after = os.fstat(fd)
+ if (before.st_size, before.st_mtime_ns, before.st_mode) != (after.st_size, after.st_mtime_ns, after.st_mode):
+ raise ValueError("old package changed during preservation")
+ os.fchmod(output.fileno(), stat.S_IMODE(before.st_mode))
+ output.flush()
+ os.fsync(output.fileno())
+ files[relative] = hashed.hexdigest()
+ finally:
+ os.close(fd)
+ else:
+ raise ValueError("old recovery package contains a link or special entry")
+ if len(files) > 6000:
+ raise ValueError("old recovery package has too many entries")
+ finally:
+ os.close(source_fd)
+ for source, name in ((old_program, "program"), (old_resources, "resources")):
+ copy_verified_tree(source, retained / name, name)
+ locations = retained / "restore-locations.json"
+ metadata = retained / "installation"
+ metadata.mkdir(mode=0o700)
+ restore_files = {}
+ for source, name in ((paths["marker"], "standalone.json"), (_service, "service-definition")):
+ if source.exists():
+ target = metadata / name
+ shutil.copy2(source, target)
+ files["installation/" + name] = digest(target)
+ restore_files["installation/" + name] = str(source)
+ links = {str(paths["bin"] / name): str(old_program / name) for name in ("hiroute", "hirouted")}
+ locations.write_text(json.dumps({"schema": "hiroute.standalone-program-restore/v1", "program": str(old_program), "resources": str(old_resources), "files": restore_files, "links": links}, sort_keys=True) + "\n")
+ locations.chmod(0o600)
+ files["restore-locations.json"] = digest(locations)
+ record = {"schema": "hiroute.retained-recovery-package/v1", "storage_root": str(paths["state"] / "storage"), "package_root": str(retained), "target_daemon_sha256": digest(target_daemon), "files": files}
+ candidate_preflight(target_daemon, paths["state"] / "storage", retained)
+ handoff = staged_file(paths["state"] / "upgrade-package.json", (json.dumps(record, sort_keys=True) + "\n").encode(), 0o600)
+ yield handoff
+ finally:
+ # A moved handoff may already have been consumed by a daemon or batch.
+ # Retain it even after later transaction rollback. Delete only this
+ # invocation's still-unpublished copy, never previous recovery material.
+ if handoff is None or handoff.exists():
+ metadata = retained.lstat()
+ if (metadata.st_dev, metadata.st_ino) == (retained_identity.st_dev, retained_identity.st_ino):
+ remove_path(retained)
+
+
def install(args):
home = Path(os.environ.get("HOME", ""))
if not home.is_absolute() or not home.is_dir():
@@ -779,30 +929,33 @@ def install(args):
(staged_link(entry, version_root / name), entry)
)
- if current is not None:
- old_install_root, old_resource_root, _old_service = validate_marker(
- paths, current
+ with retain_recovery_package(paths, current, staged_bin / "hirouted", version) as handoff:
+ if handoff is not None:
+ staged_components.insert(0, (handoff, paths["state"] / "upgrade-package.json"))
+ if current is not None:
+ old_install_root, old_resource_root, _old_service = validate_marker(
+ paths, current
+ )
+ if old_install_root != version_root:
+ staged_components.append((None, old_install_root))
+ if old_resource_root != resource_root:
+ staged_components.append((None, old_resource_root))
+
+ marker = {
+ "schema_version": MARKER_SCHEMA,
+ "version": version,
+ "target": manifest["target"],
+ "install_root": str(version_root),
+ "service_definition": str(service_path),
+ "installed_skills": [str(path) for path in skills],
+ "cpa_binary": str(cpa),
+ "cpa_sha256": manifest["cpa"]["sha256"],
+ }
+ marker_content = (json.dumps(marker, indent=2, sort_keys=True) + "\n").encode()
+ staged_components.append(
+ (staged_file(paths["marker"], marker_content, 0o600), paths["marker"])
)
- if old_install_root != version_root:
- staged_components.append((None, old_install_root))
- if old_resource_root != resource_root:
- staged_components.append((None, old_resource_root))
-
- marker = {
- "schema_version": MARKER_SCHEMA,
- "version": version,
- "target": manifest["target"],
- "install_root": str(version_root),
- "service_definition": str(service_path),
- "installed_skills": [str(path) for path in skills],
- "cpa_binary": str(cpa),
- "cpa_sha256": manifest["cpa"]["sha256"],
- }
- marker_content = (json.dumps(marker, indent=2, sort_keys=True) + "\n").encode()
- staged_components.append(
- (staged_file(paths["marker"], marker_content, 0o600), paths["marker"])
- )
- replace_components(staged_components)
+ replace_components(staged_components)
finally:
for staged_component, _destination in staged_components:
if staged_component is not None and (
diff --git a/scripts/test-build-release.py b/scripts/test-build-release.py
index 15a4eb06..f2286e33 100644
--- a/scripts/test-build-release.py
+++ b/scripts/test-build-release.py
@@ -546,7 +546,14 @@ class HostedReleasePolicyTests(unittest.TestCase):
if line.strip().startswith('cargo test ')]
self.assertEqual(component_tests, [
'cargo test --locked --target x86_64-pc-windows-msvc '
- '-p hiroute-host-runtime --lib standalone_install::'])
+ '-p hiroute-host-runtime --lib standalone_install::',
+ 'cargo test --locked --target x86_64-pc-windows-msvc '
+ '-p hiroute-host-runtime --lib storage_recovery::',
+ 'cargo test --locked --target x86_64-pc-windows-msvc '
+ '-p hiroute-platform --lib windows::shell_registration::tests::'
+ 'inherited_export_is_published_privately_and_changed_material_is_not_overwritten -- --exact',
+ 'cargo test --locked --target x86_64-pc-windows-msvc '
+ '-p hiroute-shell --features shell-runtime --lib'])
self.assertIn("throw 'Windows installation component regressions failed'", workflow)
self.assertIn('component fixtures, not standard-user installation acceptance', workflow)
self.assertNotIn('--ignored', workflow)
diff --git a/scripts/test-standalone-install.py b/scripts/test-standalone-install.py
index 2a37c744..c20d28fe 100755
--- a/scripts/test-standalone-install.py
+++ b/scripts/test-standalone-install.py
@@ -11,6 +11,7 @@ import plistlib
import re
import sys
import tempfile
+from types import SimpleNamespace
import unittest
from unittest.mock import patch
@@ -28,6 +29,20 @@ package = load("package_standalone", "package-standalone.py")
installer = load("install_standalone", "install-standalone.py")
+class PreflightTransportTests(unittest.TestCase):
+ def test_provisional_helper_rejects_malformed_or_unknown_success_reports(self):
+ good = {"schema":"hiroute.upgrade-preflight/v1", "history_cutover_required":False, "required_bytes":0, "available_bytes":1000, "recovery":None}
+ with tempfile.TemporaryDirectory() as directory:
+ helper = Path(directory) / "preflight"
+ for value in [[], {}, dict(good, schema="future"), dict(good, required_bytes=-1), dict(good, history_cutover_required="false")]:
+ helper.write_text("#!" + sys.executable + "\nprint(" + repr(json.dumps(value)) + ")\n")
+ helper.chmod(0o700)
+ with self.assertRaisesRegex(ValueError, "invalid"):
+ installer.candidate_preflight(helper, Path(directory), Path(directory))
+ helper.write_text("#!" + sys.executable + "\nprint(" + repr(json.dumps(good)) + ")\n")
+ self.assertEqual(installer.candidate_preflight(helper, Path(directory), Path(directory)), good)
+
+
class HTTPSResponse(io.BytesIO):
def __init__(self, body, status=200, headers=None, url="https://downloads.example/package"):
super().__init__(body)
@@ -41,6 +56,9 @@ class HTTPSResponse(io.BytesIO):
class StandaloneFixture(unittest.TestCase):
def setUp(self):
+ preflight = patch.object(installer, "candidate_preflight", return_value={"schema": "hiroute.upgrade-preflight/v1", "history_cutover_required": False, "required_bytes": 0, "available_bytes": 1000000000, "recovery": None})
+ self.preflight = preflight.start()
+ self.addCleanup(preflight.stop)
self.temporary = tempfile.TemporaryDirectory()
self.addCleanup(self.temporary.cleanup)
# Installer paths are canonicalized; Linux workbenches may alias /tmp.
@@ -284,8 +302,162 @@ class MacInstallerTests(StandaloneFixture):
self.assertEqual(state.read_text(), "business data")
[email protected](os.name == "posix", "Unix installation recovery")
+class RecoveryRetentionTests(StandaloneFixture):
+ def setUp(self):
+ super().setUp()
+ conflict = patch.object(installer, "desktop_conflict", return_value=False)
+ conflict.start()
+ self.addCleanup(conflict.stop)
+
+ def install_original(self):
+ manifest, archive = self.build("0.1.0")
+ args = self.install_args(manifest, archive)
+ installer.install(args)
+ return args, installer.layout(self.home)
+
+ def test_current_format_repair_does_not_copy_packages_or_replace_existing_handoff(self):
+ with self.environment(), patch.object(installer.subprocess, "run"), patch("builtins.print"):
+ args, paths = self.install_original()
+ retained = paths["state"] / "upgrade-packages/prior-batch"
+ retained.mkdir(parents=True)
+ (retained / "keep").write_bytes(b"existing recovery material")
+ handoff = paths["state"] / "upgrade-package.json"
+ original = json.dumps({"package_root": str(retained)}).encode()
+ handoff.write_bytes(original)
+ data = paths["state"] / "storage/keep"
+ data.parent.mkdir()
+ data.write_bytes(b"business data")
+ self.preflight.side_effect = ValueError("old package has no preflight protocol")
+ with patch.object(installer.shutil, "disk_usage", return_value=SimpleNamespace(free=200 * 1024 * 1024)):
+ for _ in range(2):
+ installer.install(args)
+ self.assertEqual(list(retained.parent.iterdir()), [retained])
+ self.assertEqual(handoff.read_bytes(), original)
+ self.assertEqual((retained / "keep").read_bytes(), b"existing recovery material")
+ self.assertEqual(data.read_bytes(), b"business data")
+
+ def test_changed_writer_without_cutover_skips_archival_after_preflight(self):
+ with self.environment(), patch.object(installer.subprocess, "run"), patch("builtins.print"):
+ args, paths = self.install_original()
+ self.sources["hirouted"].write_bytes(b"changed writer, same storage format")
+ manifest, archive = self.build("0.2.0")
+ with patch.object(installer.shutil, "disk_usage", return_value=SimpleNamespace(free=200 * 1024 * 1024)):
+ installer.install(self.install_args(manifest, archive))
+ self.preflight.assert_called_once()
+ self.assertFalse((paths["state"] / "upgrade-packages").exists())
+ self.assertFalse((paths["state"] / "upgrade-package.json").exists())
+ self.assertEqual((paths["lib"] / "0.2.0/hirouted").read_bytes(), self.sources["hirouted"].read_bytes())
+
+ def test_refused_cutover_discards_only_this_unpublished_copy(self):
+ with self.environment(), patch.object(installer.subprocess, "run"), patch("builtins.print"):
+ args, paths = self.install_original()
+ marker = paths["marker"].read_bytes()
+ retained = paths["state"] / "upgrade-packages/prior-batch"
+ retained.mkdir(parents=True)
+ (retained / "keep").write_bytes(b"retained original")
+ handoff = paths["state"] / "upgrade-package.json"
+ handoff.write_bytes(b"prior handoff")
+ self.sources["hirouted"].write_bytes(b"changed candidate writer")
+ manifest, archive = self.build("0.2.0")
+ args = self.install_args(manifest, archive)
+ for _ in range(2):
+ self.preflight.side_effect = [{"history_cutover_required": True}, ValueError("final preflight refused")]
+ with self.assertRaisesRegex(ValueError, "final preflight refused"):
+ installer.install(args)
+ self.assertEqual(list(retained.parent.iterdir()), [retained])
+ self.assertEqual(handoff.read_bytes(), b"prior handoff")
+ self.assertEqual(paths["marker"].read_bytes(), marker)
+ self.assertEqual((retained / "keep").read_bytes(), b"retained original")
+
+ def test_copy_failure_discards_the_new_private_archive(self):
+ with self.environment(), patch.object(installer.subprocess, "run"), patch("builtins.print"):
+ args, paths = self.install_original()
+ self.sources["hirouted"].write_bytes(b"changed candidate writer")
+ manifest, archive = self.build("0.2.0")
+ args = self.install_args(manifest, archive)
+ self.preflight.return_value = {"history_cutover_required": True}
+ with patch.object(installer.os, "read", side_effect=OSError("copy interrupted")):
+ with self.assertRaisesRegex(OSError, "copy interrupted"):
+ installer.install(args)
+ self.assertEqual(list((paths["state"] / "upgrade-packages").iterdir()), [])
+ self.assertFalse((paths["state"] / "upgrade-package.json").exists())
+
+ def test_published_handoff_copy_survives_later_installation_rollback(self):
+ with self.environment(), patch.object(installer.subprocess, "run"), patch("builtins.print"):
+ args, paths = self.install_original()
+ marker = paths["marker"].read_bytes()
+ handoff = paths["state"] / "upgrade-package.json"
+ handoff.write_bytes(b"prior handoff")
+ original_program = (paths["lib"] / "0.1.0/hirouted").read_bytes()
+ self.sources["hirouted"].write_bytes(b"changed candidate writer")
+ manifest, archive = self.build("0.2.0")
+ args = self.install_args(manifest, archive)
+ self.preflight.return_value = {"history_cutover_required": True}
+ replace = installer.os.replace
+ def fail_marker(source, destination):
+ if Path(destination) == paths["marker"] and Path(source).name.startswith("." + paths["marker"].name + "."):
+ raise OSError("publication interrupted")
+ return replace(source, destination)
+ with patch.object(installer.os, "replace", side_effect=fail_marker):
+ with self.assertRaisesRegex(OSError, "publication interrupted"):
+ installer.install(args)
+ self.assertEqual(paths["marker"].read_bytes(), marker)
+ self.assertEqual(handoff.read_bytes(), b"prior handoff")
+ copies = list((paths["state"] / "upgrade-packages").iterdir())
+ self.assertEqual(len(copies), 1)
+ self.assertEqual((copies[0] / "program/hirouted").read_bytes(), original_program)
+
+
@unittest.skipUnless(os.name == "posix" and os.uname().sysname == "Linux", "Linux layout test")
class InstallerTests(StandaloneFixture):
+ def test_upgrade_retains_the_complete_original_package_and_restoration_entries(self):
+ old_manifest, old_archive = self.build("0.1.0")
+ with self.environment(), patch.object(installer.subprocess, "run"), patch("builtins.print"):
+ installer.install(self.install_args(old_manifest, old_archive))
+ paths = installer.layout(self.home)
+ old_program, old_resources, service = installer.validate_marker(paths, installer.read_marker(paths))
+ original_program = (old_program / "hirouted").read_bytes()
+ original_service = service.read_bytes()
+ self.sources["hirouted"].write_bytes(b"new verified daemon")
+ manifest, archive = self.build("0.2.0")
+ self.preflight.return_value = {"history_cutover_required": True}
+ installer.install(self.install_args(manifest, archive))
+ handoff = json.loads((paths["state"] / "upgrade-package.json").read_text())
+ retained = Path(handoff["package_root"])
+ self.assertEqual((retained / "program/hirouted").read_bytes(), original_program)
+ self.assertEqual((retained / "installation/service-definition").read_bytes(), original_service)
+ self.assertFalse(old_program.exists())
+ self.assertFalse(old_resources.exists())
+ self.assertEqual(handoff["target_daemon_sha256"], installer.digest(paths["lib"] / "0.2.0/hirouted"))
+ self.assertEqual(handoff["storage_root"], str(paths["state"] / "storage"))
+ locations = json.loads((retained / "restore-locations.json").read_text())
+ self.assertEqual(locations["program"], str(old_program))
+ self.assertEqual(locations["links"], {str(paths["bin"] / name): str(old_program / name) for name in ("hiroute", "hirouted")})
+ for name, expected in handoff["files"].items():
+ self.assertEqual(installer.digest(retained / name), expected)
+ self.assertNotIn(b"HIROUTE_RECOVERY_PACKAGE", service.read_bytes())
+
+ def test_preflight_refusal_preserves_the_original_installation_and_service(self):
+ old_manifest, old_archive = self.build("0.1.0")
+ with self.environment(), patch.object(installer.subprocess, "run"), patch("builtins.print"):
+ installer.install(self.install_args(old_manifest, old_archive))
+ paths = installer.layout(self.home)
+ old_program, old_resources, service = installer.validate_marker(paths, installer.read_marker(paths))
+ before = {path: path.read_bytes() for path in [paths["marker"], old_program / "hirouted", service]}
+ original_link = (paths["bin"] / "hiroute").readlink()
+ self.sources["hirouted"].write_bytes(b"changed candidate daemon")
+ manifest, archive = self.build("0.2.0")
+ with patch.object(installer, "candidate_preflight", side_effect=ValueError("insufficient_space")):
+ with self.assertRaisesRegex(ValueError, "insufficient_space"):
+ installer.install(self.install_args(manifest, archive))
+ for path, content in before.items():
+ self.assertEqual(path.read_bytes(), content)
+ self.assertEqual((paths["bin"] / "hiroute").readlink(), original_link)
+ self.assertTrue(old_resources.is_dir())
+ self.assertFalse((paths["lib"] / "0.2.0").exists())
+ self.assertFalse((paths["state"] / "upgrade-package.json").exists())
+
def test_accessible_service_home_preserves_permissions(self):
manifest, archive = self.build()
self.home.chmod(0o775)
diff --git a/scripts/test-windows-dev.py b/scripts/test-windows-dev.py
index bae81a23..ba32e3e2 100644
--- a/scripts/test-windows-dev.py
+++ b/scripts/test-windows-dev.py
@@ -32,6 +32,27 @@ desktop = load('windows-desktop-session')
class Runner(unittest.TestCase):
+ def test_incomplete_installation_page_requires_exact_repair_and_no_storage_retry_in_both_languages(self):
+ (self.root/'window.png').write_bytes(b'captured native image placeholder')
+ (self.root/'ui.json').write_text('{}')
+ button=dict(name='English',type='ControlType.Button',offscreen=False,runtime_id='42.1')
+ zh=dict(nodes=[dict(name='安装尚未完成'),dict(name='SHELL_INSTALL_RECOVERY_REQUIRED'),
+ dict(name='相同版本及构建;缺包时寻求支持'),button])
+ en=dict(nodes=[dict(name='Installation is incomplete'),dict(name='SHELL_INSTALL_RECOVERY_REQUIRED'),
+ dict(name='same version and build; obtain support if missing')])
+ with patch.object(desktop,'ui_action',side_effect=[zh,en]) as action:
+ self.assertEqual(desktop.failure_page_languages(self.root,Path('shell.exe'),42,'installer_recovery'),['zh','en'])
+ self.assertEqual(action.call_args_list[1].args[-1],button,
+ 'Native invocation needs the entire observed element for identity recheck')
+ for extra in [dict(name='RECOVERY.md'),dict(name='重试',offscreen=False)]:
+ with self.subTest(extra=extra),patch.object(desktop,'ui_action',return_value=dict(nodes=zh['nodes']+[extra])), \
+ self.assertRaisesRegex(ValueError,'borrowed storage advice'):
+ desktop.failure_page_languages(self.root,Path('shell.exe'),42,'installer_recovery')
+ with patch.object(desktop,'ui_action',return_value=dict(nodes=[n for n in zh['nodes'] if '相同版本' not in n['name']])), \
+ self.assertRaisesRegex(ValueError,'exact repair/support'):
+ desktop.failure_page_languages(self.root,Path('shell.exe'),42,'installer_recovery')
+
+
def setUp(self):
self.temporary = tempfile.TemporaryDirectory()
self.addCleanup(self.temporary.cleanup)
@@ -99,11 +120,85 @@ class Runner(unittest.TestCase):
with self.assertRaisesRegex(ValueError, 'binary changed'):
desktop.installed(profiles, self.root, manifest)
+ def test_nsis_waits_for_exit_past_cli_watchdog_and_records_transaction_phases(self):
+ locations = {name: self.root / name for name in ('data', 'shell_state')}
+ for path in locations.values():
+ path.mkdir()
+ pending = locations['shell_state'] / 'install-pending.json'
+ pending.write_text(json.dumps(dict(phase='prepared')))
+ clock = [0.0]
+ child = unittest.mock.Mock(pid=42)
+ child.poll.side_effect = [None, None, 0]
+ def advance(_):
+ clock[0] += 80
+ if clock[0] == 160:
+ pending.unlink()
+ (locations['shell_state'] / 'update-outcome.json').write_text(json.dumps(dict(status='succeeded')))
+ with patch.object(desktop.subprocess, 'Popen', return_value=child), \
+ patch.object(desktop.time, 'monotonic', side_effect=lambda: clock[0]), \
+ patch.object(desktop.time, 'sleep', side_effect=advance):
+ result = desktop.nsis_install(self.root / 'installer.exe', self.root, locations)
+ self.assertEqual(result['elapsed_seconds'], 160)
+ self.assertEqual(result['exit_code'], 0)
+ self.assertFalse(result['timed_out'])
+ self.assertEqual(result['events'][0]['changes']['shell']['phase'], 'prepared')
+ self.assertEqual(result['events'][-1]['changes']['outcome']['status'], 'succeeded')
+ child.kill.assert_not_called()
+ self.assertEqual(json.loads((self.root / 'installer-process.json').read_text()), result)
+
+ def test_nsis_watchdog_records_failure_and_stops_only_the_held_child(self):
+ locations = {name: self.root / name for name in ('data', 'shell_state')}
+ clock = [0.0]
+ child = unittest.mock.Mock(pid=42)
+ child.poll.return_value = None
+ def advance(_):
+ clock[0] += 1
+ with patch.object(desktop, 'NSIS_INSTALL_TIMEOUT', 2), \
+ patch.object(desktop.subprocess, 'Popen', return_value=child), \
+ patch.object(desktop.time, 'monotonic', side_effect=lambda: clock[0]), \
+ patch.object(desktop.time, 'sleep', side_effect=advance), \
+ self.assertRaises(desktop.subprocess.TimeoutExpired):
+ desktop.nsis_install(self.root / 'installer.exe', self.root, locations)
+ child.kill.assert_called_once_with()
+ child.wait.assert_called_once_with(timeout=30)
+ result = json.loads((self.root / 'installer-process.json').read_text())
+ self.assertTrue(result['timed_out'])
+ self.assertNotIn('exit_code', result)
+
+
def test_desktop_refuses_filtered_administrator_before_native_actions(self):
with self.assertRaisesRegex(ValueError, 'filtered administrator'), patch.object(desktop.subprocess, 'run') as run:
desktop.execute({}, self.root, self.root, {}, profiles, {'administrator_groups': True}, host.manifest, self.root)
run.assert_not_called()
+
+ def test_native_lock_ui_requires_current_inspection_before_stopping_any_service(self):
+ with patch.object(desktop.subprocess,'run') as run,patch.object(desktop,'installed') as admit:
+ with self.assertRaisesRegex(ValueError,'recent current-product inspection'):
+ desktop.locked_startup_ui({},self.root,self.root,{},profiles,{},self.root)
+ run.assert_not_called();admit.assert_not_called()
+
+
+ def test_startup_fixture_refuses_foreign_activity_before_desktop_or_service_mutation(self):
+ observed='a'*32;folder=self.root/'runs'/observed;folder.mkdir(parents=True)
+ config=dict(user='owner',session_id=3)
+ request=dict(product='current',observation_run=observed,config=config)
+ (folder/'request.json').write_text(json.dumps(dict(operation='inspect',product='current',config=config)))
+ (folder/'result.json').write_text(json.dumps(dict(passed=True,administrator=False)))
+ install=self.root/'version';shell=self.root/'desktop/hiroute-shell.exe'
+ facts=dict(marker=dict(record=dict(install_root=str(install))),
+ definition=dict(text=json.dumps(dict(name='HiRoute-'+'b'*64))))
+ for activity in [dict(processes=[dict(ExecutablePath=str(self.root/'foreign/hirouted.exe'))]),
+ dict(tasks=[dict(TaskName='unrelated-task')])]:
+ with patch.object(desktop,'installed',return_value=({},facts,shell)), \
+ patch.object(desktop,'desktop_state') as state,patch.object(desktop.subprocess,'run') as run:
+ with self.assertRaisesRegex(ValueError,'unrelated product activity'):
+ desktop.startup_ui_context(request,self.root,{},profiles,activity,self.root)
+ state.assert_not_called();run.assert_not_called()
+
+
+
+
def test_desktop_helper_requires_the_exact_committed_hash(self):
path = self.root / 'desktop.py'
path.write_text('raise RuntimeError("must not import")')
@@ -343,6 +438,37 @@ class Runner(unittest.TestCase):
self.assertEqual(run.call_args.args[0], [str(shell), '--installer-install', '--no-login-start', '--no-tray'])
self.assertEqual((self.root / 'installer-resume.stdout').read_bytes(), b'installed')
+ def test_prepared_repair_accepts_only_the_measured_old_or_current_marker(self):
+ home=self.root/'home';namespace=home/'.local/lib/hiroute'
+ old=namespace/('0.3.1-'+'a'*12);current=namespace/('0.3.1-'+'b'*12)
+ programs=home/'local/Programs/HiRoute';(programs/'standalone').mkdir(parents=True)
+ prior=dict(source_revision='a'*40,files={});pm=dict(source_revision='b'*40,files={})
+ for folder,record,prefix in [(old,prior,b'old'),(current,pm,b'current')]:
+ folder.mkdir(parents=True)
+ for name in ['hiroute.exe','hirouted.exe']:
+ (folder/name).write_bytes(prefix+name.encode());record['files'][name]=dict(sha256=profiles.digest(folder/name))
+ if folder==current:(programs/'standalone'/name).write_bytes((folder/name).read_bytes())
+ shell=programs/'hiroute-shell.exe';shell.write_bytes(b'current measured shell');pm['shell_sha256']=profiles.digest(shell)
+ pending=dict(schema='hiroute.windows-shell-transaction/v1',phase='prepared',previous_package=str(old),new={'hiroute-shell.exe':pm['shell_sha256']})
+ facts={'marker':dict(sha256='marker',record=dict(install_root=str(old))),
+ 'install-pending.json':dict(sha256='pending',record=pending),'programs':dict(path=str(programs))}
+ observation='f'*32;run=self.root/'runs'/observation;run.mkdir(parents=True)
+ new_bundle='b'*12+'-'+'d'*12;old_bundle='a'*12+'-'+'c'*12
+ request=dict(product=new_bundle,from_product=old_bundle,observation_run=observation,config=dict(session_id=3))
+ (run/'request.json').write_text(json.dumps(dict(product=new_bundle,config=dict(session_id=3))))
+ (run/'result.json').write_text(json.dumps(dict(passed=True,assessment='inspection_only',installation=facts)))
+ with patch.object(desktop.Path,'home',return_value=home),patch.dict(os.environ,LOCALAPPDATA=str(home/'local')), \
+ patch.object(profiles,'inspect_installation',return_value=facts):
+ for accepted in [old,current]:
+ facts['marker']['record']['install_root']=str(accepted)
+ self.assertEqual(desktop.prepared_installer_replacement(request,pm,profiles,dict(processes=[]),lambda _:prior,self.root)[2],shell)
+ foreign=namespace/('0.3.1-'+'e'*12);facts['marker']['record']['install_root']=str(foreign)
+ with self.assertRaisesRegex(ValueError,'outside the admitted'):
+ desktop.prepared_installer_replacement(request,pm,profiles,dict(processes=[]),lambda _:prior,self.root)
+ facts['marker']['record']['install_root']=str(current);(current/'hiroute.exe').write_bytes(b'substituted current CLI')
+ with self.assertRaisesRegex(ValueError,'substituted product'):
+ desktop.prepared_installer_replacement(request,pm,profiles,dict(processes=[]),lambda _:prior,self.root)
+
def test_nsis_retry_admits_the_exact_interrupted_product_before_normal_install(self):
interrupted = 'b' * 12 + '-' + 'c' * 12
request = dict(product='a' * 12 + '-' + 'd' * 12, from_product='e' * 12 + '-' + 'f' * 12,
@@ -728,7 +854,10 @@ class Runner(unittest.TestCase):
if len(controller.powershell(script)) > 6000:
self.assertEqual(base64.b64decode(payload).decode('utf-8'), script)
bridge = base64.b64decode(command.split()[-1]).decode('utf-16le')
- self.assertIn('[Console]::In.ReadToEnd()', bridge)
+ self.assertIn('[Console]::In.ReadLine()', bridge)
+ self.assertNotIn('ReadToEnd', bridge)
+ self.assertTrue(payload.endswith('\n'))
+ self.assertIn('$line.Length -ne ' + str(len(payload) - 1), bridge)
else:
self.assertIsNone(payload)
self.assertEqual(base64.b64decode(command.split()[-1]).decode('utf-16le'), script)
diff --git a/scripts/windows-desktop-session.py b/scripts/windows-desktop-session.py
index 47683313..79897558 100644
--- a/scripts/windows-desktop-session.py
+++ b/scripts/windows-desktop-session.py
@@ -5,6 +5,8 @@ Uses the installed NSIS product, Windows UI Automation and window screenshots.
It never injects browser scripts, creates a login or changes native data roots.
"""
import json
+import base64
+import hashlib
import ctypes
import os
from pathlib import Path
@@ -457,13 +459,20 @@ def prepared_installer_replacement(request, pm, helper, activity, manifest, root
raise ValueError('Only the exact prepared shell installation can be resumed')
prior = manifest(root / 'bundles' / request['from_product'])
marker = facts['marker']['record']
- previous = helper.plain(Path(marker['install_root']))
- if (previous != Path(pending.get('previous_package') or '') or not previous.name.endswith(prior['source_revision'][:12])
+ previous = helper.plain(Path(pending.get('previous_package') or ''))
+ if (not previous.name.endswith(prior['source_revision'][:12])
or previous.parent != Path.home() / '.local/lib/hiroute'):
raise ValueError('The retained previous package does not match the requested product')
for name in ('hiroute.exe', 'hirouted.exe'):
if helper.digest(previous / name) != prior['files'][name]['sha256']:
raise ValueError('The retained previous product changed')
+ active=helper.plain(Path(marker['install_root']))
+ accepted=prior if active==previous else pm
+ if active.parent!=previous.parent or not active.name.endswith(accepted['source_revision'][:12]):
+ raise ValueError('The current installation marker is outside the admitted old/current pair')
+ for name in ('hiroute.exe','hirouted.exe'):
+ if helper.digest(active/name)!=accepted['files'][name]['sha256']:
+ raise ValueError('The current installation marker points at a substituted product')
programs = helper.plain(Path(facts['programs']['path']))
shell = helper.plain(programs / 'hiroute-shell.exe')
if (helper.digest(shell) != pm['shell_sha256'] or pending.get('new', {}).get('hiroute-shell.exe') != pm['shell_sha256']
@@ -611,12 +620,224 @@ def admit_nsis_install(request, helper, activity, manifest, root):
raise ValueError('Fresh Desktop installation must not adopt an existing product')
+# The shell's installer adapter permits one 600-second native install request.
+# NSIS also extracts files and runs its prepare/commit hooks outside that request.
+# Keep this specific whole-installer watchdog outside that product deadline;
+# ordinary public CLI/UI actions retain their existing bounds.
+NSIS_INSTALL_TIMEOUT = 720
+
+
+def nsis_install(installer, run, locations):
+ """Wait for the actual NSIS child and retain bounded phase/timing evidence.
+
+ Observing a committed marker is never a substitute for installer exit. On
+ timeout stop only our owned NSIS process; its product transaction remains
+ available for inspection and normal recovery, without automatic replay.
+ """
+ observed = {
+ 'shell': locations['shell_state'] / 'install-pending.json',
+ 'standalone': locations['data'] / 'service/install-journal.json',
+ 'installation': locations['data'] / 'standalone.json',
+ 'outcome': locations['shell_state'] / 'update-outcome.json',
+ }
+ started = time.monotonic()
+ evidence = dict(watchdog_seconds=NSIS_INSTALL_TIMEOUT, events=[])
+ signatures = {}
+
+ def record(final=None):
+ changed = {}
+ for name, path in observed.items():
+ try:
+ info = path.stat()
+ signature = (info.st_mtime_ns, info.st_size)
+ if signature == signatures.get(name):
+ continue
+ signatures[name] = signature
+ value = dict(present=True, bytes=info.st_size)
+ if info.st_size <= 1024 * 1024:
+ with path.open('rb') as source:
+ data = source.read(1024 * 1024 + 1)
+ try:
+ row = json.loads(data)
+ value.update({k: row[k] for k in ('phase', 'status')
+ if isinstance(row.get(k), str) and len(row[k]) <= 64})
+ except (ValueError, TypeError):
+ value['incomplete_read'] = True
+ changed[name] = value
+ except FileNotFoundError:
+ if signatures.get(name) != 'absent':
+ signatures[name] = 'absent'
+ changed[name] = dict(present=False)
+ except OSError:
+ if signatures.get(name) != 'unavailable':
+ signatures[name] = 'unavailable'
+ changed[name] = dict(unavailable=True)
+ if changed and len(evidence['events']) < 256:
+ evidence['events'].append(dict(elapsed_seconds=round(time.monotonic()-started, 3),
+ changes=changed))
+ if final is not None:
+ evidence.update(final, elapsed_seconds=round(time.monotonic()-started, 3))
+ (run / 'installer-process.json').write_text(json.dumps(evidence, indent=2), encoding='utf-8')
+
+ with (run / 'installer.stdout').open('xb') as out, (run / 'installer.stderr').open('xb') as err:
+ child = subprocess.Popen([str(installer), '/S'], stdin=subprocess.DEVNULL, stdout=out, stderr=err)
+ evidence['pid'] = child.pid
+ while True:
+ code = child.poll()
+ record()
+ if code is not None:
+ record(dict(exit_code=code, timed_out=False))
+ if code:
+ raise subprocess.CalledProcessError(code, [str(installer), '/S'])
+ return evidence
+ if time.monotonic()-started >= NSIS_INSTALL_TIMEOUT:
+ record(dict(timed_out=True))
+ child.kill()
+ child.wait(timeout=30)
+ raise subprocess.TimeoutExpired([str(installer), '/S'], NSIS_INSTALL_TIMEOUT)
+ time.sleep(0.5)
+
+
+def failure_page_languages(run, shell, pid, cause):
+ import shutil
+ observed=ui_action(run,dict(desktop_action='snapshot'),shell,pid)
+ deadline=time.monotonic()+75
+ languages=[]
+ reasons={'locked':('另一个 HiRoute 实例','Another HiRoute instance'),
+ 'unsupported_format':('这组数据的格式没有经过验证','This data format has no verified upgrade path'),
+ 'installer_recovery':('安装尚未完成','Installation is incomplete')}
+ for index in range(2):
+ while True:
+ names='\n'.join(n.get('name','') for n in observed.get('nodes',[]))
+ zh,en=reasons[cause]
+ language='zh' if zh in names else 'en' if en in names else None
+ if language is not None:break
+ if time.monotonic()>=deadline:raise ValueError('The native failure page did not expose the current cause')
+ time.sleep(1)
+ observed=ui_action(run,dict(desktop_action='snapshot'),shell,pid)
+ prefix={'locked':'locked','unsupported_format':'format','installer_recovery':'installer-recovery'}[cause]
+ shutil.copyfile(run/'window.png',run/(prefix+'-'+language+'.png'))
+ shutil.copyfile(run/'ui.json',run/(prefix+'-'+language+'.json'))
+ if cause=='installer_recovery':
+ if ('SHELL_INSTALL_RECOVERY_REQUIRED' not in names
+ or ('相同版本及构建' if language=='zh' else 'same version and build') not in names
+ or ('寻求支持' if language=='zh' else 'obtain support') not in names
+ or any(n.get('name') in ('重试','Try again') and not n.get('offscreen') for n in observed.get('nodes',[]))
+ or 'RECOVERY.md' in names):
+ raise ValueError('The incomplete installation page borrowed storage advice or lost its exact repair/support path')
+ languages.append(language)
+ if index==0:
+ buttons=[n for n in observed['nodes'] if n.get('name') in ('English','中文') and n.get('type')=='ControlType.Button' and not n.get('offscreen')]
+ if len(buttons)!=1:raise ValueError('The actual failure-page language control is unavailable')
+ observed=ui_action(run,dict(desktop_action='invoke'),shell,pid,buttons[0])
+ if set(languages)!={'zh','en'}:raise ValueError('Both native failure-page languages were not observed')
+ return languages
+
+
+def startup_ui_context(request, product, pm, helper, activity, root):
+ observation = request.get('observation_run')
+ if not re.fullmatch(r'[a-f0-9]{32}',observation or ''):
+ raise ValueError('The native lock UI case requires a recent current-product inspection')
+ inspected = root/'runs'/observation
+ before_request = helper.bounded_json(inspected/'request.json')
+ before_result = helper.bounded_json(inspected/'result.json')
+ if (before_request.get('operation') != 'inspect' or before_request['product'] != request['product']
+ or not before_result.get('passed') or before_result.get('administrator') is not False
+ or before_request['config']['user'] != request['config']['user']
+ or before_request['config']['session_id'] != request['config']['session_id']
+ or time.time()-(inspected/'result.json').stat().st_mtime>3600):
+ raise ValueError('The native lock UI inspection is stale or belongs to another product/account')
+ roots,facts,shell = installed(helper,product,pm)
+ if any(Path(p.get('ExecutablePath') or '') == shell for p in activity.get('processes', [])):
+ raise ValueError('Quit the installed Desktop before the bounded native UI case')
+ install=Path(facts['marker']['record']['install_root'])
+ allowed={install/'hirouted.exe',install/'libexec/cliproxyapi.exe'}
+ task=json.loads(facts['definition']['text']).get('name','')
+ if (not re.fullmatch(r'HiRoute-[a-f0-9]{64}',task)
+ or any(Path(p.get('ExecutablePath') or '') not in allowed for p in activity.get('processes',[]))
+ or any(t.get('TaskName')!=task for t in activity.get('tasks',[]))):
+ raise ValueError('Preserve unrelated product activity before the bounded native UI fixture')
+ if not desktop_state().get('interactive'):
+ raise ValueError('The existing input desktop is unavailable; no lock fixture was created')
+ return roots,facts,shell
+
+
+def locked_startup_ui(request, run, product, pm, helper, activity, root, file_use=False):
+ """Own one bounded lock fixture, inspect both real languages, then reopen normally."""
+ import shutil
+ roots,facts,shell = startup_ui_context(request,product,pm,helper,activity,root)
+ cli = Path(facts['marker']['record']['install_root'])/'hiroute.exe'
+ def command(args,label):
+ done=subprocess.run([str(cli),*args],capture_output=True,timeout=150,creationflags=0x08000000)
+ (run/(label+'.stdout')).write_bytes(done.stdout);(run/(label+'.stderr')).write_bytes(done.stderr)
+ if done.returncode:raise ValueError('The current-product fixture command failed: '+label)
+ return json.loads(done.stdout)
+ if command(['system','status','--output','json'],'before-system').get('data',{}).get('gateway') != 'ready':
+ raise ValueError('The current Gateway must be healthy before the native lock fixture')
+ command(['service','stop','--output','json'],'fixture-stop')
+ storage=roots['state']/'storage'
+ report=helper.plain(storage/'startup-recovery.json')
+ report_before=helper.digest(report) if report.exists() else None
+ kernel=ctypes.WinDLL('kernel32',use_last_error=True)
+ from ctypes import wintypes
+ kernel.CreateFileW.argtypes=[wintypes.LPCWSTR,wintypes.DWORD,wintypes.DWORD,ctypes.c_void_p,wintypes.DWORD,wintypes.DWORD,wintypes.HANDLE]
+ kernel.CreateFileW.restype=wintypes.HANDLE;kernel.CloseHandle.argtypes=[wintypes.HANDLE]
+ target=storage/('live/control.db' if file_use else 'startup.lock')
+ handle=kernel.CreateFileW(str(helper.plain(target)),0,0,None,3,0x00200000,None)
+ if handle==wintypes.HANDLE(-1).value:raise ctypes.WinError(ctypes.get_last_error())
+ child=None
+ languages=[]
+ failure=None
+ try:
+ child=subprocess.Popen([str(shell)],stdin=subprocess.DEVNULL,stdout=subprocess.DEVNULL,stderr=subprocess.DEVNULL)
+ time.sleep(15)
+ languages=failure_page_languages(run,shell,child.pid,'locked')
+ offline=command(['service','recovery','--output','json'],'locked-offline-recovery').get('data',{}).get('recovery',{})
+ if offline.get('cause')!='locked' or offline.get('action')!='retry_current' or offline.get('backup_batch'):
+ raise ValueError('A correctable native file-use prerequisite did not offer current-version retry')
+ except Exception as error:
+ failure=error
+ finally:
+ kernel.CloseHandle(handle)
+ if child is not None and child.poll() is None:
+ try:
+ ui_action(run,dict(desktop_action='quit'),shell,child.pid)
+ child.wait(timeout=20)
+ except Exception:
+ if child.poll() is None:child.terminate();child.wait(timeout=20)
+ recovery_file=helper.plain(storage/'startup-recovery.json')
+ unchanged=(helper.digest(recovery_file) if recovery_file.exists() else None)==report_before
+ if not file_use and not unchanged and failure is None:
+ failure=ValueError('A non-writer lock failure overwrote the previous recovery report')
+ # Follow the visible instruction: release the file use and reopen this same
+ # complete version. Keep business readiness separate from the window result.
+ reopened=subprocess.Popen([str(shell)],stdin=subprocess.DEVNULL,stdout=subprocess.DEVNULL,stderr=subprocess.DEVNULL)
+ try:
+ time.sleep(15)
+ ui_action(run,dict(desktop_action='snapshot'),shell,reopened.pid)
+ shutil.copyfile(run/'window.png',run/'reopened-current.png')
+ if command(['system','status','--output','json'],'reopened-system').get('data',{}).get('gateway')!='ready':
+ raise ValueError('Reopening the current version did not restore actual Gateway readiness')
+ finally:
+ if reopened.poll() is None:
+ try:ui_action(run,dict(desktop_action='quit'),shell,reopened.pid);reopened.wait(timeout=20)
+ except Exception:
+ if reopened.poll() is None:reopened.terminate();reopened.wait(timeout=20)
+ if failure is not None:raise failure
+ return dict(native_entry='real standard-user '+('current-Control file-use' if file_use else 'locked-startup')+' page and current-version reopen',languages=languages,
+ recovery_report_unchanged=unchanged,gateway_ready_after_reopen=True)
+
+
def execute(request, run, product, pm, helper, activity, manifest, root):
if activity.get('administrator_groups') is not False:
raise ValueError('Native Desktop evidence requires a standard account, not a filtered administrator')
action = request['desktop_action']
- if action not in ('install', 'installer-resume', 'installer-quarantine', 'launch', 'snapshot', 'invoke', 'text', 'click', 'scroll', 'close', 'quit', 'tray-observe', 'desktop-state', 'cli', 'native-files', 'codex-call', 'codex-inference', 'network-probe'):
+ if action not in ('install', 'installer-resume', 'installer-quarantine', 'launch', 'snapshot', 'invoke', 'text', 'click', 'scroll', 'close', 'quit', 'tray-observe', 'desktop-state', 'cli', 'native-files', 'codex-call', 'codex-inference', 'network-probe', 'recovery-lock-ui', 'recovery-file-use-ui'):
raise ValueError('Unknown native Desktop action')
+ if action == 'recovery-lock-ui':
+ return locked_startup_ui(request,run,product,pm,helper,activity,root)
+ if action == 'recovery-file-use-ui':
+ return locked_startup_ui(request,run,product,pm,helper,activity,root,file_use=True)
if action == 'desktop-state':
return dict(native_entry='read-only input desktop inspection', state=desktop_state())
if action == 'native-files':
@@ -635,6 +856,13 @@ def execute(request, run, product, pm, helper, activity, manifest, root):
files[relative] = dict(exists=True, sha256=helper.digest(path), bytes=path.stat().st_size)
else:
files[relative] = dict(exists=True, inventory=helper.inventory(path))
+ # Compare these before/after an upgrade or restoration without invoking
+ # Codex in between. Calls themselves legitimately append native history.
+ for relative in ('.codex/sessions','.codex/history.jsonl'):
+ path=helper.plain(Path.home()/relative)
+ if not path.exists():files[relative]=dict(exists=False)
+ elif path.is_dir():files[relative]=dict(exists=True,inventory=helper.inventory(path))
+ else:files[relative]=dict(exists=True,sha256=helper.digest(path),bytes=path.stat().st_size)
(run / 'native-files.json').write_text(json.dumps(files, indent=2), encoding='utf-8')
return dict(native_entry='read-only native configuration inventory', files=files)
if action == 'installer-resume':
@@ -646,11 +874,11 @@ def execute(request, run, product, pm, helper, activity, manifest, root):
if action == 'install':
admit_nsis_install(request, helper, activity, manifest, root)
previous = request.get('from_product')
- with (run / 'installer.stdout').open('xb') as out, (run / 'installer.stderr').open('xb') as err:
- done = subprocess.run([str(product / 'installer.exe'), '/S'], stdin=subprocess.DEVNULL,
- stdout=out, stderr=err, timeout=150, check=True)
+ timing = nsis_install(product / 'installer.exe', run,
+ helper.locations(Path.home(), Path(os.environ['LOCALAPPDATA'])))
_, after, _ = installed(helper, product, pm)
- return dict(native_entry='NSIS /S', exit_code=done.returncode, installation=after,
+ return dict(native_entry='NSIS /S', exit_code=timing['exit_code'], installation=after,
+ elapsed_seconds=timing['elapsed_seconds'],
upgrade_from=previous, recovery_from=request.get('recover_product'),
installer_sha256=pm['files']['installer.exe']['sha256'])
roots, facts, shell = installed(helper, product, pm)
diff --git a/scripts/windows-dev-profile.py b/scripts/windows-dev-profile.py
index b6966b6a..991bf29a 100644
--- a/scripts/windows-dev-profile.py
+++ b/scripts/windows-dev-profile.py
@@ -3,6 +3,7 @@
import hashlib
import json
import os
+import re
from pathlib import Path
import stat
@@ -105,6 +106,7 @@ def inspect_installation(native_home, local_app_data):
pass # A concurrently written or clipped first/last record is incomplete.
tails[str(path.relative_to(diagnostics))] = dict(bytes=size, records=records)
facts['diagnostics_tail'] = tails
+ # Pre-replacement refusal may precede the transaction journal. Inspect only
expected = facts.get('shell-package.json', {}).get('record', {}).get('files', {})
mismatches = []
for name, wanted in expected.items():
@@ -118,6 +120,8 @@ def inspect_installation(native_home, local_app_data):
backups = plain(local_app_data / 'HiRoute/shell/install-backups')
if backups.is_dir():
facts['shell_backup_entries'] = sorted(str(p.relative_to(backups)) for p in backups.rglob('*') if p.is_file())[:100]
+ facts['shell_backup_mismatches'] = [name for name, wanted in expected.items()
+ if (path := plain(backups / name)).is_file() and digest(path) != wanted]
return facts
@@ -244,3 +248,14 @@ def archive_orphaned_data(native_home, local_app_data, destination, inspected, a
outcome='archived_and_verified', manifest_sha256=digest(manifest))), encoding='utf-8')
return dict(archived=[str(t) for _, t in moved], backup_manifest='profile-backup.json',
native_configuration='unchanged', assessment='preparation_only')
+
+
+def bounded_json(path, maximum=1024 * 1024):
+ path = plain(path)
+ if not path.is_file() or path.stat().st_size > maximum:
+ raise ValueError('Missing or oversized recovery metadata')
+ with path.open('rb') as stream:
+ content = stream.read(maximum + 1)
+ if len(content) > maximum:
+ raise ValueError('Recovery metadata changed while reading')
+ return json.loads(content)
diff --git a/scripts/windows-dev.py b/scripts/windows-dev.py
index e842ff28..bfab9049 100644
--- a/scripts/windows-dev.py
+++ b/scripts/windows-dev.py
@@ -140,12 +140,16 @@ class Remote:
payload = None
if len(command) > 6000:
# Windows OpenSSH may enter through cmd.exe's 8191-character limit.
- # Keep argv bounded; the encoded bridge reads source data to EOF.
- payload = base64.b64encode(script.encode('utf-8')).decode()
+ # A length-checked line avoids waiting for SSH/PowerShell to forward
+ # EOF before the remote command can run. Never replay a timeout.
+ encoded = base64.b64encode(script.encode('utf-8')).decode()
+ payload = encoded + '\n'
command = powershell(
"$ErrorActionPreference='Stop';"
+ "$line=[Console]::In.ReadLine();"
+ "if($null -eq $line -or $line.Length -ne " + str(len(encoded)) + "){throw 'Incomplete source frame'};"
"$source=[Text.Encoding]::UTF8.GetString("
- "[Convert]::FromBase64String([Console]::In.ReadToEnd()));"
+ "[Convert]::FromBase64String($line));"
"& ([ScriptBlock]::Create($source))")
result = subprocess.run(['ssh', *self.options, self.config['host'], command],
input=payload, capture_output=True, text=True,
@@ -334,7 +338,7 @@ def main():
desktop = commands.add_parser('desktop-session', help='Measured installed Desktop and native UI acceptance')
desktop.add_argument('--product', required=True)
desktop.add_argument('--action', dest='desktop_action', required=True,
- choices=('install', 'installer-resume', 'installer-quarantine', 'launch', 'snapshot', 'invoke', 'text', 'click', 'scroll', 'close', 'quit', 'tray-observe', 'desktop-state', 'cli', 'native-files', 'codex-call', 'codex-inference', 'network-probe'))
+ choices=('install', 'installer-resume', 'installer-quarantine', 'launch', 'snapshot', 'invoke', 'text', 'click', 'scroll', 'close', 'quit', 'tray-observe', 'desktop-state', 'cli', 'native-files', 'codex-call', 'codex-inference', 'network-probe', 'recovery-lock-ui', 'recovery-file-use-ui'))
desktop.add_argument('--from-product', help='Exact installed bundle admitted before a cross-build upgrade')
desktop.add_argument('--recover-product', help='Exact interrupted bundle, with a recent inspection, before normal NSIS recovery')
desktop.add_argument('--observation-run')
@@ -426,7 +430,8 @@ def main():
if args.desktop_action == 'scroll' and args.scroll_direction is None:
raise ValueError('Scrolling requires an explicit direction')
values.update(run_id=uuid.uuid4().hex, harness=args.product, binary='hiroute.exe',
- case='native_desktop_' + args.desktop_action.replace('-', '_'), operation='desktop', ignored=False, timeout=240)
+ case='native_desktop_' + args.desktop_action.replace('-', '_'), operation='desktop', ignored=False,
+ timeout={'install':810,'recovery-lock-ui':600,'recovery-file-use-ui':600}.get(args.desktop_action,240))
values.pop('cli_args')
if args.desktop_action == 'cli':
if args.cli_args is None: