Skip to content

YC (S26) | Open Computer History | Continuously record your company computer work, map your workflows, help you find work worth automating, and power your agents' context

fix(db): resume verified recovery after SHM timestamp changes (#6932)

Ezra Ellette018f1ecfa4c7
diff --git a/Cargo.lock b/Cargo.lock
index 076ab4e1b..e54d978b2 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -8555,7 +8555,7 @@ dependencies = [
[[package]]
name = "screenpipe-audio"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"anyhow",
"audiopipe",
@@ -8623,7 +8623,7 @@ dependencies = [
[[package]]
name = "screenpipe-audio-eval"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"anyhow",
"audiopipe",
@@ -8662,7 +8662,7 @@ dependencies = [
[[package]]
name = "screenpipe-config"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"dirs 6.0.0",
"screenpipe-cpu-features",
@@ -8676,7 +8676,7 @@ dependencies = [
[[package]]
name = "screenpipe-connect"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"anyhow",
"async-imap",
@@ -8724,7 +8724,7 @@ dependencies = [
[[package]]
name = "screenpipe-core"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"accessibility",
"accessibility-sys",
@@ -8778,11 +8778,11 @@ dependencies = [
[[package]]
name = "screenpipe-cpu-features"
-version = "0.4.48"
+version = "0.4.49"
[[package]]
name = "screenpipe-db"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"anyhow",
"chrono",
@@ -8813,7 +8813,7 @@ dependencies = [
[[package]]
name = "screenpipe-engine"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"anyhow",
"arc-swap",
@@ -8898,7 +8898,7 @@ dependencies = [
[[package]]
name = "screenpipe-events"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"anyhow",
"chrono",
@@ -8916,7 +8916,7 @@ dependencies = [
[[package]]
name = "screenpipe-gateway"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"async-trait",
"axum",
@@ -8946,7 +8946,7 @@ dependencies = [
[[package]]
name = "screenpipe-meeting-eval"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"anyhow",
"clap",
@@ -8958,7 +8958,7 @@ dependencies = [
[[package]]
name = "screenpipe-overlay-win"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"serde",
"serde_json",
@@ -8969,7 +8969,7 @@ dependencies = [
[[package]]
name = "screenpipe-redact"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"aho-corasick",
"anyhow",
@@ -9008,7 +9008,7 @@ dependencies = [
[[package]]
name = "screenpipe-resource"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"serde",
"sysinfo",
@@ -9028,7 +9028,7 @@ dependencies = [
[[package]]
name = "screenpipe-screen"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"accessibility-sys",
"anyhow",
@@ -9109,7 +9109,7 @@ dependencies = [
[[package]]
name = "screenpipe-sqlite-coordinator"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"libsqlite3-sys",
"serde",
@@ -9123,7 +9123,7 @@ dependencies = [
[[package]]
name = "screenpipe-sqlite-recovery"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"cc",
"libsqlite3-sys",
@@ -9133,7 +9133,7 @@ dependencies = [
[[package]]
name = "screenpipe-sync"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"async-trait",
"base64 0.22.1",
@@ -9155,7 +9155,7 @@ dependencies = [
[[package]]
name = "screenpipe-team-memory"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"serde",
"serde_yaml",
@@ -9164,7 +9164,7 @@ dependencies = [
[[package]]
name = "screenpipe-telemetry-wire"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"serde",
"serde_json",
@@ -9174,7 +9174,7 @@ dependencies = [
[[package]]
name = "screenpipe-vault"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"argon2 0.5.3",
"chacha20poly1305",
diff --git a/Cargo.toml b/Cargo.toml
index c298af2e8..3af3b3c4b 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -16,7 +16,7 @@ exclude = [
resolver = "2"
[workspace.package]
-version = "0.4.48"
+version = "0.4.49"
authors = ["louis030195 <[email protected]>"]
description = ""
repository = "https://github.com/screenpipe/screenpipe"
diff --git a/apps/screenpipe-app-tauri/src-tauri/Cargo.lock b/apps/screenpipe-app-tauri/src-tauri/Cargo.lock
index 09a63c2bc..3d94afff7 100644
--- a/apps/screenpipe-app-tauri/src-tauri/Cargo.lock
+++ b/apps/screenpipe-app-tauri/src-tauri/Cargo.lock
@@ -11276,7 +11276,7 @@ dependencies = [
[[package]]
name = "screenpipe-audio"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"anyhow",
"audiopipe",
@@ -11356,7 +11356,7 @@ dependencies = [
[[package]]
name = "screenpipe-config"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"dirs 6.0.0",
"screenpipe-cpu-features",
@@ -11369,7 +11369,7 @@ dependencies = [
[[package]]
name = "screenpipe-connect"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"anyhow",
"async-imap",
@@ -11415,7 +11415,7 @@ dependencies = [
[[package]]
name = "screenpipe-core"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"accessibility",
"accessibility-sys",
@@ -11468,11 +11468,11 @@ dependencies = [
[[package]]
name = "screenpipe-cpu-features"
-version = "0.4.48"
+version = "0.4.49"
[[package]]
name = "screenpipe-db"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"anyhow",
"chrono",
@@ -11500,7 +11500,7 @@ dependencies = [
[[package]]
name = "screenpipe-engine"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"anyhow",
"arc-swap",
@@ -11574,7 +11574,7 @@ dependencies = [
[[package]]
name = "screenpipe-events"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"anyhow",
"chrono",
@@ -11590,7 +11590,7 @@ dependencies = [
[[package]]
name = "screenpipe-overlay-win"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"serde",
"serde_json",
@@ -11609,7 +11609,7 @@ dependencies = [
[[package]]
name = "screenpipe-redact"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"aho-corasick",
"anyhow",
@@ -11646,7 +11646,7 @@ dependencies = [
[[package]]
name = "screenpipe-resource"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"serde",
"sysinfo",
@@ -11666,7 +11666,7 @@ dependencies = [
[[package]]
name = "screenpipe-screen"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"accessibility-sys",
"anyhow",
@@ -11733,7 +11733,7 @@ dependencies = [
[[package]]
name = "screenpipe-sqlite-coordinator"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"libsqlite3-sys",
"serde",
@@ -11746,7 +11746,7 @@ dependencies = [
[[package]]
name = "screenpipe-sqlite-recovery"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"cc",
"libsqlite3-sys",
@@ -11754,7 +11754,7 @@ dependencies = [
[[package]]
name = "screenpipe-sync"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"async-trait",
"base64 0.22.1",
@@ -11774,7 +11774,7 @@ dependencies = [
[[package]]
name = "screenpipe-telemetry-wire"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"serde",
"serde_json",
@@ -11784,7 +11784,7 @@ dependencies = [
[[package]]
name = "screenpipe-vault"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"argon2 0.5.3",
"chacha20poly1305",
diff --git a/crates/screenpipe-engine/src/cli/db.rs b/crates/screenpipe-engine/src/cli/db.rs
index d0300314e..4bb528cf8 100644
--- a/crates/screenpipe-engine/src/cli/db.rs
+++ b/crates/screenpipe-engine/src/cli/db.rs
@@ -46,7 +46,7 @@ use anyhow::{bail, Context, Result};
use rusqlite::{Connection, OpenFlags};
use serde::{Deserialize, Serialize};
use std::fs::{self, OpenOptions};
-use std::io::Write;
+use std::io::{Read, Write};
use std::path::{Path, PathBuf};
use std::process::{Command, Stdio};
use std::sync::atomic::{AtomicBool, Ordering};
@@ -386,7 +386,7 @@ pub async fn handle_db_command(command: &DbCommand) -> Result<()> {
let data_dir = screenpipe_core::paths::default_screenpipe_data_dir();
match command {
DbCommand::Check => integrity_check(&data_dir.join("db.sqlite")),
- DbCommand::Recover { force } => recover(&data_dir, *force).await,
+ DbCommand::Recover { force, resume } => recover(&data_dir, *force, *resume).await,
DbCommand::Cleanup { apply, force } => cleanup(&data_dir, *apply, *force).await,
DbCommand::Unlock { force } => unlock(&data_dir, *force),
}
@@ -497,7 +497,7 @@ fn update_manifest(
atomic_write_manifest(&phase_path, manifest)
}
-#[derive(Debug, Eq, PartialEq)]
+#[derive(Clone, Debug, Eq, PartialEq)]
struct GenerationComponentFingerprint {
name: String,
identity: screenpipe_db::SqliteFileIdentity,
@@ -544,8 +544,9 @@ fn generation_fingerprint(live: &Path) -> Result<Vec<GenerationComponentFingerpr
/// A quarantined app shell can cause SQLite to create a brand-new zero-byte
/// WAL while rendering the recovery UI. That file contains no committed data
-/// and does not make the base database a newer generation. Keep rejecting any
-/// base DB change, any existing-sidecar change, and any WAL with bytes.
+/// and does not make the base database a newer generation. SHM is a transient
+/// WAL index, not committed data: a timestamp-only change is also harmless.
+/// Keep rejecting DB/WAL changes and SHM identity, size, or presence changes.
fn recovery_source_is_current(
source: &[GenerationComponentFingerprint],
current: &[GenerationComponentFingerprint],
@@ -559,7 +560,15 @@ fn recovery_source_is_current(
!newly_created_empty_wal
});
- source.iter().eq(current_without_new_empty_wal)
+ let current = current_without_new_empty_wal.collect::<Vec<_>>();
+ source.len() == current.len()
+ && source.iter().zip(current).all(|(before, after)| {
+ before == after
+ || (before.name == "db.sqlite-shm"
+ && before.name == after.name
+ && before.identity == after.identity
+ && before.length == after.length)
+ })
}
fn prepare_readonly_generation(
@@ -828,13 +837,121 @@ fn restore_interrupted_swap(data_dir: &Path, live: &Path) -> Result<()> {
Ok(())
}
-async fn recover(data_dir: &Path, _force: bool) -> Result<()> {
+async fn recover(data_dir: &Path, _force: bool, resume: bool) -> Result<()> {
// A recovery that races even one live SQLite connection cannot promise an
// exact source generation. `--force` is retained for CLI compatibility but
// deliberately cannot override this architectural boundary.
ensure_app_quit(false)?;
- recover_offline(data_dir).await
+ if resume {
+ resume_recovery_offline(data_dir).await
+ } else {
+ recover_offline(data_dir).await
+ }
+}
+
+/// Compare only the small WAL copies; never read/copy the entire main database.
+fn same_file_bytes(left: &Path, right: &Path) -> Result<bool> {
+ if fs::metadata(left)?.len() != fs::metadata(right)?.len() {
+ return Ok(false);
+ }
+ let mut left = fs::File::open(left)?;
+ let mut right = fs::File::open(right)?;
+ let mut a = [0u8; 64 * 1024];
+ let mut b = [0u8; 64 * 1024];
+ loop {
+ let count = left.read(&mut a)?;
+ if count == 0 {
+ return Ok(right.read(&mut b[..1])? == 0);
+ }
+ right.read_exact(&mut b[..count])?;
+ if a[..count] != b[..count] {
+ return Ok(false);
+ }
+ }
+}
+
+fn validate_resume_source(
+ live: &Path,
+ recovery_dir: &Path,
+ manifest: &RecoveryManifest,
+) -> Result<Vec<GenerationComponentFingerprint>> {
+ let work = recovery_dir.join("working-copy/db.sqlite");
+ let candidate = recovery_dir.join("candidate.sqlite");
+ if manifest.schema_version != 1
+ || !matches!(manifest.phase, RecoveryPhase::CandidateVerified)
+ || fs::canonicalize(&manifest.live_path)? != fs::canonicalize(live)?
+ || recovery_dir.join("source-generation").exists()
+ {
+ bail!(
+ "cannot resume: candidate does not describe an uninstalled recovery for this database"
+ );
+ }
+ for path in [live, work.as_path(), candidate.as_path()] {
+ if !fs::symlink_metadata(path)?.file_type().is_file() {
+ bail!(
+ "cannot resume: expected a regular file at {}",
+ path.display()
+ );
+ }
+ }
+ let before = generation_fingerprint(live)?;
+ // v0.4.48 did not persist source fingerprints. Its original identity,
+ // surviving hard link, and pre-recovery DB/WAL write times establish that
+ // this is still its input. Fail closed if those facts cannot be established.
+ if before[0].identity != manifest.original_identity
+ || screenpipe_db::sqlite_file_identity(&work)? != manifest.original_identity
+ || manifest.started_at_unix_ms == 0
+ || before
+ .iter()
+ .filter(|part| part.name != "db.sqlite-shm")
+ .any(|part| {
+ !part.modified_unix_nanos.is_some_and(|modified| {
+ modified < u128::from(manifest.started_at_unix_ms) * 1_000_000
+ })
+ })
+ {
+ bail!("cannot resume: original DB/WAL changed since this recovery started, or its read-only input link is missing");
+ }
+ let live_wal = sqlite_sidecar(live, "-wal");
+ let work_wal = sqlite_sidecar(&work, "-wal");
+ if live_wal.exists() != work_wal.exists()
+ || (live_wal.exists() && !same_file_bytes(&live_wal, &work_wal)?)
+ {
+ bail!("cannot resume: original WAL differs from the saved recovery input");
+ }
+ if manifest.candidate_identity.as_ref()
+ != Some(&screenpipe_db::sqlite_file_identity(&candidate)?)
+ {
+ bail!("cannot resume: candidate file identity changed since verification");
+ }
+ if !recovery_source_is_current(&before, &generation_fingerprint(live)?) {
+ bail!("cannot resume: source changed while checking the saved recovery input");
+ }
+ Ok(before)
+}
+
+async fn resume_recovery_offline(data_dir: &Path) -> Result<()> {
+ let _lock = DbLock::acquire(data_dir, "recover --resume")?;
+ let live = data_dir.join("db.sqlite");
+ if !screenpipe_db::sqlite_quarantine_exists(&live) {
+ bail!("cannot resume: no active database quarantine; no files were replaced");
+ }
+ for recovery_dir in newest_recovery_directories(data_dir)? {
+ let verified = recovery_dir.join("recovery-manifest-candidate-verified.json");
+ if !verified.exists() || !recovery_dir.join("candidate.sqlite").exists() {
+ continue;
+ }
+ let manifest: RecoveryManifest = serde_json::from_slice(&fs::read(&verified)?)
+ .context("reading verified recovery manifest")?;
+ let fingerprint = validate_resume_source(&live, &recovery_dir, &manifest)?;
+ println!("resuming verified candidate at {}", recovery_dir.display());
+ println!(
+ "rechecking the existing candidate; no database copy or page-level recovery needed"
+ );
+ return verify_and_install_candidate(data_dir, &recovery_dir, manifest, fingerprint).await;
+ }
+ bail!("no previously verified candidate available to resume; no new recovery was started and no database files were replaced")
}
/// Recover a database that was durably quarantined by the running app.
@@ -864,15 +981,6 @@ async fn recover_offline(data_dir: &Path) -> Result<()> {
}
let original_identity = screenpipe_db::sqlite_file_identity(&live)
.with_context(|| format!("identifying quarantined database {}", live.display()))?;
- let marker = match screenpipe_db::read_sqlite_quarantine(&live) {
- Ok(marker) => marker,
- Err(error) => {
- eprintln!(
- "warning: active quarantine marker is unreadable ({error}); keeping it fail-closed until recovery completes"
- );
- None
- }
- };
if !screenpipe_db::sqlite_quarantine_exists(&live) {
screenpipe_db::persist_sqlite_quarantine(
&live,
@@ -885,12 +993,11 @@ async fn recover_offline(data_dir: &Path) -> Result<()> {
let ts = chrono::Local::now().format("%Y%m%d-%H%M%S").to_string();
let recovery_dir = data_dir.join(format!("db-recovery-{ts}-{}", std::process::id()));
let work_dir = recovery_dir.join("working-copy");
- let source_dir = recovery_dir.join("source-generation");
fs::create_dir_all(&work_dir)?;
let work = work_dir.join("db.sqlite");
let candidate = recovery_dir.join("candidate.sqlite");
let manifest_path = recovery_dir.join(RECOVERY_MANIFEST_FILE);
- let mut manifest = RecoveryManifest {
+ let manifest = RecoveryManifest {
schema_version: 1,
phase: RecoveryPhase::Preparing,
live_path: live.clone(),
@@ -923,7 +1030,31 @@ async fn recover_offline(data_dir: &Path) -> Result<()> {
println!(" rebuilt FTS5 indexes: {}", rebuilt_fts.join(", "));
}
- let mut forbidden_identities = vec![original_identity.clone()];
+ verify_and_install_candidate(data_dir, &recovery_dir, manifest, source_fingerprint).await
+}
+
+async fn verify_and_install_candidate(
+ data_dir: &Path,
+ recovery_dir: &Path,
+ mut manifest: RecoveryManifest,
+ source_fingerprint: Vec<GenerationComponentFingerprint>,
+) -> Result<()> {
+ let live = data_dir.join("db.sqlite");
+ let work_dir = recovery_dir.join("working-copy");
+ let source_dir = recovery_dir.join("source-generation");
+ let candidate = recovery_dir.join("candidate.sqlite");
+ let manifest_path = recovery_dir.join(RECOVERY_MANIFEST_FILE);
+ let source_table_count = table_count(&work_dir.join("db.sqlite")).unwrap_or(0);
+ let marker = match screenpipe_db::read_sqlite_quarantine(&live) {
+ Ok(marker) => marker,
+ Err(error) => {
+ eprintln!(
+ "warning: active quarantine marker is unreadable ({error}); keeping it fail-closed until recovery completes"
+ );
+ None
+ }
+ };
+ let mut forbidden_identities = vec![manifest.original_identity.clone()];
if let Some(marker_identity) = marker.and_then(|marker| marker.file_identity) {
if !forbidden_identities.contains(&marker_identity) {
forbidden_identities.push(marker_identity);
@@ -958,12 +1089,18 @@ async fn recover_offline(data_dir: &Path) -> Result<()> {
);
}
- manifest.candidate_identity = Some(candidate_verification.file_identity.clone());
- update_manifest(
- &manifest_path,
- &mut manifest,
- RecoveryPhase::CandidateVerified,
- )?;
+ if matches!(manifest.phase, RecoveryPhase::CandidateVerified) {
+ if manifest.candidate_identity.as_ref() != Some(&candidate_verification.file_identity) {
+ bail!("candidate identity changed during resumed verification; original remains untouched");
+ }
+ } else {
+ manifest.candidate_identity = Some(candidate_verification.file_identity.clone());
+ update_manifest(
+ &manifest_path,
+ &mut manifest,
+ RecoveryPhase::CandidateVerified,
+ )?;
+ }
let current_fingerprint = generation_fingerprint(&live)?;
if !recovery_source_is_current(&source_fingerprint, &current_fingerprint) {
@@ -1292,6 +1429,22 @@ mod recovery_tests {
use super::*;
use std::io::{Seek, SeekFrom};
+ #[test]
+ fn recovery_cli_accepts_explicit_resume_without_force() {
+ use clap::Parser;
+ let cli = super::super::Cli::try_parse_from(["screenpipe", "db", "recover", "--resume"])
+ .expect("customer resume command must parse");
+ assert!(matches!(
+ cli.command,
+ super::super::Command::Db {
+ subcommand: DbCommand::Recover {
+ resume: true,
+ force: false
+ }
+ }
+ ));
+ }
+
fn write_generation(live: &Path) {
fs::write(live, b"database-bytes").expect("write db");
fs::write(sqlite_sidecar(live, "-wal"), b"wal-bytes").expect("write wal");
@@ -1416,6 +1569,221 @@ mod recovery_tests {
assert!(!recovery_source_is_current(&source, &changed));
}
+ #[test]
+ fn recovery_accepts_shm_timestamp_only_but_rejects_generation_changes() {
+ let dir = tempfile::tempdir().unwrap();
+ let live = dir.path().join("db.sqlite");
+ write_generation(&live);
+ let source = generation_fingerprint(&live).unwrap();
+ for index in 0..3 {
+ let mut current = source.clone();
+ current[index].modified_unix_nanos = Some(42);
+ assert_eq!(recovery_source_is_current(&source, &current), index == 2);
+ current = source.clone();
+ current[index].length += 1;
+ assert!(!recovery_source_is_current(&source, &current));
+ current = source.clone();
+ current[index].identity = source[(index + 1) % 3].identity.clone();
+ assert!(!recovery_source_is_current(&source, &current));
+ current = source.clone();
+ current.remove(index);
+ assert!(!recovery_source_is_current(&source, &current));
+ }
+ }
+
+ fn set_modified(path: &Path, time: SystemTime) {
+ OpenOptions::new()
+ .write(true)
+ .open(path)
+ .unwrap()
+ .set_modified(time)
+ .unwrap();
+ }
+
+ /// Create the exact v0.4.48 on-disk state after candidate verification and
+ /// before installation, including a row present only in the copied WAL.
+ async fn resumable_fixture(data_dir: &Path) -> (PathBuf, RecoveryManifest) {
+ fs::create_dir_all(data_dir).unwrap();
+ let seed = data_dir.join("seed.sqlite");
+ let writer = Connection::open(&seed).unwrap();
+ writer
+ .execute_batch(
+ "PRAGMA journal_mode=WAL; PRAGMA wal_autocheckpoint=0; \
+ CREATE TABLE records (id INTEGER PRIMARY KEY, value TEXT); \
+ PRAGMA wal_checkpoint(TRUNCATE); \
+ INSERT INTO records VALUES (1, 'only-in-wal');",
+ )
+ .unwrap();
+ let live = data_dir.join("db.sqlite");
+ for suffix in ["", "-wal", "-shm"] {
+ let destination = data_dir.join(format!("db.sqlite{suffix}"));
+ fs::copy(data_dir.join(format!("seed.sqlite{suffix}")), &destination).unwrap();
+ set_modified(
+ &destination,
+ UNIX_EPOCH + Duration::from_secs(now_unix() - 60),
+ );
+ }
+ drop(writer);
+ let directory = data_dir.join("db-recovery-20260906-000000-48");
+ fs::create_dir_all(directory.join("working-copy")).unwrap();
+ let work = directory.join("working-copy/db.sqlite");
+ let candidate = directory.join("candidate.sqlite");
+ let mut manifest = test_manifest(&live);
+ manifest.started_at_unix_ms = now_unix() * 1000;
+ atomic_write_manifest(&directory.join(RECOVERY_MANIFEST_FILE), &manifest).unwrap();
+ prepare_readonly_generation(&live, &work).unwrap();
+ screenpipe_sqlite_recovery::recover_database(&work, &candidate).unwrap();
+ let verification = screenpipe_db::verify_fresh_sqlite_recovery_candidate(
+ &candidate,
+ &[manifest.original_identity.clone()],
+ )
+ .await
+ .unwrap();
+ manifest.candidate_identity = Some(verification.file_identity);
+ update_manifest(
+ &directory.join(RECOVERY_MANIFEST_FILE),
+ &mut manifest,
+ RecoveryPhase::CandidateVerified,
+ )
+ .unwrap();
+ screenpipe_db::persist_sqlite_quarantine(&live, Some(11), "resume fixture").unwrap();
+ (directory, manifest)
+ }
+
+ fn triplet_bytes(live: &Path) -> Vec<Vec<u8>> {
+ [
+ live.to_path_buf(),
+ sqlite_sidecar(live, "-wal"),
+ sqlite_sidecar(live, "-shm"),
+ ]
+ .iter()
+ .map(|path| fs::read(path).unwrap())
+ .collect()
+ }
+
+ #[tokio::test]
+ async fn resume_048_candidate_after_shm_timestamp_change_without_recovering_again() {
+ let dir = tempfile::tempdir().unwrap();
+ let (recovery_dir, manifest) = resumable_fixture(dir.path()).await;
+ let live = dir.path().join("db.sqlite");
+ let originals = triplet_bytes(&live);
+ set_modified(&sqlite_sidecar(&live, "-shm"), SystemTime::now());
+ resume_recovery_offline(dir.path())
+ .await
+ .expect("resume verified 0.4.48 candidate");
+ assert_eq!(
+ Some(screenpipe_db::sqlite_file_identity(&live).unwrap()),
+ manifest.candidate_identity
+ );
+ assert_eq!(
+ newest_recovery_directories(dir.path()).unwrap(),
+ vec![recovery_dir.clone()]
+ );
+ assert!(!screenpipe_db::sqlite_quarantine_exists(&live));
+ assert_eq!(
+ triplet_bytes(&recovery_dir.join("source-generation/db.sqlite")),
+ originals
+ );
+ let connection =
+ Connection::open_with_flags(&live, OpenFlags::SQLITE_OPEN_READ_ONLY).unwrap();
+ assert_eq!(
+ connection
+ .query_row("SELECT value FROM records WHERE id=1", [], |r| r
+ .get::<_, String>(0))
+ .unwrap(),
+ "only-in-wal"
+ );
+ }
+
+ #[tokio::test]
+ async fn resume_rejects_changed_db_or_wal_and_preserves_originals() {
+ for suffix in ["", "-wal"] {
+ let dir = tempfile::tempdir().unwrap();
+ let (recovery_dir, _) = resumable_fixture(dir.path()).await;
+ let live = dir.path().join("db.sqlite");
+ set_modified(
+ &dir.path().join(format!("db.sqlite{suffix}")),
+ SystemTime::now(),
+ );
+ let originals = triplet_bytes(&live);
+ let error = resume_recovery_offline(dir.path()).await.unwrap_err();
+ assert!(error.to_string().contains("changed since"), "{error:#}");
+ assert_eq!(triplet_bytes(&live), originals);
+ assert!(recovery_dir.join("candidate.sqlite").exists());
+ assert!(screenpipe_db::sqlite_quarantine_exists(&live));
+ }
+ }
+
+ #[tokio::test]
+ async fn resume_checks_wal_bytes_even_with_unchanged_size_and_timestamp() {
+ let dir = tempfile::tempdir().unwrap();
+ let (_, manifest) = resumable_fixture(dir.path()).await;
+ let live = dir.path().join("db.sqlite");
+ let wal = sqlite_sidecar(&live, "-wal");
+ let modified = fs::metadata(&wal).unwrap().modified().unwrap();
+ let mut bytes = fs::read(&wal).unwrap();
+ bytes[40] ^= 0xff;
+ fs::write(&wal, bytes).unwrap();
+ set_modified(&wal, modified);
+ let originals = triplet_bytes(&live);
+ let error = resume_recovery_offline(dir.path()).await.unwrap_err();
+ assert!(error.to_string().contains("WAL differs"), "{error:#}");
+ assert_eq!(triplet_bytes(&live), originals);
+ assert_eq!(
+ screenpipe_db::sqlite_file_identity(&live).unwrap(),
+ manifest.original_identity
+ );
+ }
+
+ #[tokio::test]
+ async fn resume_revalidates_candidate_and_never_swaps_a_corrupt_file() {
+ let dir = tempfile::tempdir().unwrap();
+ let (recovery_dir, _) = resumable_fixture(dir.path()).await;
+ let live = dir.path().join("db.sqlite");
+ let originals = triplet_bytes(&live);
+ fs::write(recovery_dir.join("candidate.sqlite"), b"not a database").unwrap();
+ let error = resume_recovery_offline(dir.path()).await.unwrap_err();
+ assert!(
+ error.to_string().contains("candidate failed verification"),
+ "{error:#}"
+ );
+ assert_eq!(triplet_bytes(&live), originals);
+ assert!(!recovery_dir.join("source-generation").exists());
+ assert!(screenpipe_db::sqlite_quarantine_exists(&live));
+ }
+
+ #[tokio::test]
+ async fn resume_rejects_replaced_candidate_or_missing_input_link() {
+ for target in ["candidate.sqlite", "working-copy/db.sqlite"] {
+ let dir = tempfile::tempdir().unwrap();
+ let (recovery_dir, _) = resumable_fixture(dir.path()).await;
+ let live = dir.path().join("db.sqlite");
+ let originals = triplet_bytes(&live);
+ let target = recovery_dir.join(target);
+ let saved = recovery_dir.join("saved.sqlite");
+ fs::rename(&target, &saved).unwrap();
+ fs::copy(&saved, &target).unwrap();
+ assert!(resume_recovery_offline(dir.path()).await.is_err());
+ assert_eq!(triplet_bytes(&live), originals);
+ assert!(screenpipe_db::sqlite_quarantine_exists(&live));
+ }
+ }
+
+ #[tokio::test]
+ async fn resume_without_verified_candidate_does_not_start_recovery() {
+ let dir = tempfile::tempdir().unwrap();
+ let live = dir.path().join("db.sqlite");
+ write_generation(&live);
+ screenpipe_db::persist_sqlite_quarantine(&live, Some(11), "resume fixture").unwrap();
+ let originals = triplet_bytes(&live);
+ let error = resume_recovery_offline(dir.path()).await.unwrap_err();
+ assert!(error
+ .to_string()
+ .contains("no previously verified candidate"));
+ assert!(newest_recovery_directories(dir.path()).unwrap().is_empty());
+ assert_eq!(triplet_bytes(&live), originals);
+ }
+
#[test]
fn archive_failure_rolls_every_component_back() {
let dir = tempfile::tempdir().expect("tempdir");
diff --git a/crates/screenpipe-engine/src/cli/mod.rs b/crates/screenpipe-engine/src/cli/mod.rs
index a3bc467a2..be0ba33bf 100644
--- a/crates/screenpipe-engine/src/cli/mod.rs
+++ b/crates/screenpipe-engine/src/cli/mod.rs
@@ -1992,6 +1992,10 @@ pub enum DbCommand {
/// verifies integrity, foreign keys, and a durable write canary, then swaps.
/// Refuses to run while screenpipe is open.
Recover {
+ /// Revalidate and install the newest previously verified candidate.
+ /// Never starts another full recovery if the candidate cannot be reused.
+ #[arg(long)]
+ resume: bool,
/// Deprecated compatibility flag. Recovery still refuses to race a
/// reachable screenpipe server because that cannot preserve one exact
/// DB/WAL/SHM generation.
diff --git a/docs/SQLITE_RECOVERY.md b/docs/SQLITE_RECOVERY.md
index 069f700a0..f1275dcb4 100644
--- a/docs/SQLITE_RECOVERY.md
+++ b/docs/SQLITE_RECOVERY.md
@@ -1,8 +1,8 @@
# SQLite quarantine and recovery
<!-- doc-covers: crates/screenpipe-sqlite-recovery, crates/screenpipe-sqlite-coordinator, crates/screenpipe-engine/src/cli/db.rs -->
-<!-- doc-verified: 590f6e55f57e161d7e66e550bd39bb9e86384481 -->
-> **Current.** Recovery contract reviewed against 590f6e55f and the read-only source change (2026-09-06).
+<!-- doc-verified: 06acc67b08cafc3c02352bc82d4ce9633a92eb96 -->
+> **Current.** Recovery contract reviewed against 06acc67b08 and the SHM timestamp / candidate resume change (2026-09-06).
Screenpipe treats `SQLITE_IOERR`, `SQLITE_CORRUPT`, `SQLITE_FULL`, and
`SQLITE_NOTADB` as generation-ending faults. A new connection, pool, engine, or
@@ -83,8 +83,9 @@ snapshot impossible.
no checkpoint or database write is permitted through the shared file. If
hard links are unavailable, copy the main DB too. Compare file identity,
length, and nanosecond modification time before/after preparation and again
- before swap; if anything changed, refuse recovery because the source was not
- truly offline.
+ before swap. Reject DB/WAL changes; tolerate only a newly created empty WAL
+ and timestamp-only changes to the transient SHM index. SHM identity, size,
+ and presence changes still reject installation.
3. Run SQLite's official page-level Recovery API, compiled into Screenpipe,
against only that working path. Recovery never depends on a host `sqlite3`
executable or package-manager installation.
@@ -113,6 +114,27 @@ The original generation is never checkpointed, truncated, or used as the
recovery destination. Quarantine clears only after a real write advances and is
read back from the verified replacement.
+## Resume a verified candidate
+
+If recovery finished verification but refused installation (for example,
+v0.4.48 rejected an SHM timestamp-only change), keep the recovery directory and
+run `screenpipe db recover --resume` with Screenpipe fully stopped.
+
+This selects the newest retained `candidate.sqlite` with a candidate-verified
+manifest. It requires the original physical database identity and surviving
+read-only input hard link, DB/WAL modification times older than that recovery's
+start, and byte-for-byte equality between the original WAL and private input
+WAL. This supports v0.4.48 manifests without trusting an unrecorded fingerprint.
+Missing evidence, a changed candidate identity, or an already-started archive
+fails closed. A copied (rather than linked) main input cannot be resumed.
+
+The candidate undergoes the same integrity, foreign-key, FTS, fresh-identity,
+write-canary, schema-parity, and installation checks as a new recovery. Source
+fingerprints are checked again before the swap. This does not redo page-level
+recovery or allocate another full database; validation still scans the candidate
+and can take time. If no eligible candidate exists, the command stops without
+starting a new recovery. Original DB/WAL/SHM remain recoverable on failure.
+
## Crash behavior
Each recovery phase writes a synced manifest. The durable marker blocks normal
diff --git a/packages/sdk/Cargo.lock b/packages/sdk/Cargo.lock
index 8f5ecb10f..af5f62c8f 100644
--- a/packages/sdk/Cargo.lock
+++ b/packages/sdk/Cargo.lock
@@ -6798,7 +6798,7 @@ dependencies = [
[[package]]
name = "screenpipe-config"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"dirs 6.0.0",
"screenpipe-cpu-features",
@@ -6810,7 +6810,7 @@ dependencies = [
[[package]]
name = "screenpipe-connect"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"anyhow",
"async-imap",
@@ -6855,7 +6855,7 @@ dependencies = [
[[package]]
name = "screenpipe-core"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"accessibility",
"accessibility-sys",
@@ -6897,11 +6897,11 @@ dependencies = [
[[package]]
name = "screenpipe-cpu-features"
-version = "0.4.48"
+version = "0.4.49"
[[package]]
name = "screenpipe-db"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"anyhow",
"chrono",
@@ -6929,7 +6929,7 @@ dependencies = [
[[package]]
name = "screenpipe-events"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"anyhow",
"chrono",
@@ -6967,7 +6967,7 @@ dependencies = [
[[package]]
name = "screenpipe-screen"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"accessibility-sys",
"anyhow",
@@ -7045,7 +7045,7 @@ dependencies = [
[[package]]
name = "screenpipe-sqlite-coordinator"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"libsqlite3-sys",
"serde",
@@ -7074,7 +7074,7 @@ dependencies = [
[[package]]
name = "screenpipe-vault"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"argon2 0.5.3",
"chacha20poly1305",
diff --git a/packages/sdk/examples/tauri-app/src-tauri/Cargo.lock b/packages/sdk/examples/tauri-app/src-tauri/Cargo.lock
index 22c02a6c7..1b46dffe8 100644
--- a/packages/sdk/examples/tauri-app/src-tauri/Cargo.lock
+++ b/packages/sdk/examples/tauri-app/src-tauri/Cargo.lock
@@ -6924,7 +6924,7 @@ dependencies = [
[[package]]
name = "screenpipe-config"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"dirs 6.0.0",
"screenpipe-cpu-features",
@@ -6936,7 +6936,7 @@ dependencies = [
[[package]]
name = "screenpipe-connect"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"anyhow",
"async-imap",
@@ -6981,7 +6981,7 @@ dependencies = [
[[package]]
name = "screenpipe-core"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"accessibility",
"accessibility-sys",
@@ -7023,11 +7023,11 @@ dependencies = [
[[package]]
name = "screenpipe-cpu-features"
-version = "0.4.48"
+version = "0.4.49"
[[package]]
name = "screenpipe-db"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"anyhow",
"chrono",
@@ -7055,7 +7055,7 @@ dependencies = [
[[package]]
name = "screenpipe-events"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"anyhow",
"chrono",
@@ -7091,7 +7091,7 @@ dependencies = [
[[package]]
name = "screenpipe-screen"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"accessibility-sys",
"anyhow",
@@ -7158,7 +7158,7 @@ dependencies = [
[[package]]
name = "screenpipe-sqlite-coordinator"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"libsqlite3-sys",
"serde",
@@ -7195,7 +7195,7 @@ dependencies = [
[[package]]
name = "screenpipe-vault"
-version = "0.4.48"
+version = "0.4.49"
dependencies = [
"argon2 0.5.3",
"chacha20poly1305",