Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

fix(wiki): check session tombstones in reindex transactions

Samir Hanna Verza71ef6118eae8
diff --git a/CHANGELOG.md b/CHANGELOG.md
index da1fca12..7e101b7a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,10 @@ version in [`docs/changelog/`](docs/changelog/):
## [Unreleased]
### Fixed
+- Revalidated session-purge tombstones inside the reindex write transaction,
+ preventing a queued watcher update from recreating a deleted summary after
+ file cleanup failed. Kept surviving manual replacements at the same path
+ editable through the watcher (#1439).
- Added exact hover timestamps to `/web` page metadata, made the OKF upgrade
dialog keyboard accessible, and added a labelled main-navigation landmark
with current-page state and narrow-screen wrapping.
diff --git a/crates/ai-memory-store/src/error.rs b/crates/ai-memory-store/src/error.rs
index ebbac1b5..aa86777a 100644
--- a/crates/ai-memory-store/src/error.rs
+++ b/crates/ai-memory-store/src/error.rs
@@ -145,7 +145,7 @@ pub enum StoreError {
/// caller-invariant violation).
#[error("not found: {0}")]
NotFound(String),
- /// A late-arriving event named a session that `purge_session` removed.
+ /// An event or disk reindex named a session that `purge_session` removed.
/// Recreating it would silently undo a deletion the operator already
/// performed and an application may already have reported to a user, so
/// ingest refuses instead (#387).
diff --git a/crates/ai-memory-store/src/ops.rs b/crates/ai-memory-store/src/ops.rs
index 5c5d81e5..10b9a0e6 100644
--- a/crates/ai-memory-store/src/ops.rs
+++ b/crates/ai-memory-store/src/ops.rs
@@ -203,6 +203,55 @@ pub fn upsert_page(conn: &mut Connection, page: &NewPage) -> StoreResult<PageId>
Ok(result_id)
}
+/// Reindex a disk page without reviving a purged session's summary.
+/// The tombstone and any surviving manual version are checked in the upsert
+/// transaction, so a directory walk's earlier snapshot cannot authorize a
+/// write after a session purge. Explicit page writes/restores use `upsert_page`.
+pub fn upsert_page_from_disk(conn: &mut Connection, page: &NewPage) -> StoreResult<PageId> {
+ let now = Timestamp::now().as_microsecond();
+ let tx = conn.transaction()?;
+ let session = page
+ .path
+ .as_str()
+ .strip_prefix("sessions/")
+ .and_then(|rest| rest.strip_suffix(".md"))
+ .and_then(|id| id.parse::<SessionId>().ok());
+ if let Some(session) = session {
+ let session_text = session.to_string();
+ let owns_file = page
+ .frontmatter_json
+ .get("session_id")
+ .and_then(|v| v.as_str())
+ == Some(session_text.as_str());
+ // #866 keeps manual versions at this path. They may keep changing,
+ // but absence of `session_id` alone is not permission to recreate a
+ // deleted page: legacy summaries can lack that field too (#701).
+ let blocked: bool = tx.query_row(
+ "SELECT EXISTS(SELECT 1 FROM purged_sessions \
+ WHERE workspace_id = ?1 AND project_id = ?2 AND session_id = ?3) \
+ AND (?6 OR NOT EXISTS(SELECT 1 FROM pages \
+ WHERE workspace_id = ?1 AND project_id = ?2 AND path = ?4 \
+ AND is_latest = 1 \
+ AND json_extract(frontmatter_json, '$.session_id') IS NOT ?5))",
+ params![
+ page.workspace_id.as_bytes(),
+ page.project_id.as_bytes(),
+ session.as_bytes(),
+ page.path.as_str(),
+ session_text,
+ owns_file
+ ],
+ |row| row.get(0),
+ )?;
+ if blocked {
+ return Err(StoreError::SessionPurged(session_text));
+ }
+ }
+ let id = upsert_page_in_tx(&tx, page, now)?;
+ tx.commit()?;
+ Ok(id)
+}
+
/// What a conditional page write requires of the current latest version.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PagePrecondition {
@@ -9233,6 +9282,88 @@ pub(crate) mod tests {
assert_eq!(survivor, (manual.as_bytes().to_vec(), false));
}
+ #[test]
+ fn disk_reindex_checks_purge_and_surviving_version_ownership() {
+ for (label, manual_before, manual_after, incoming_owned, blocked) in [
+ ("owned leftover", false, false, true, true),
+ ("legacy leftover", false, false, false, true),
+ ("older manual is not live", true, false, false, true),
+ ("live manual replacement", false, true, false, false),
+ ("summary over live manual", false, true, true, true),
+ ] {
+ let (_tmp, mut conn, ws, proj) = fresh_db();
+ let sid = SessionId::new();
+ let path = format!("sessions/{sid}.md");
+ begin_session(&mut conn, &hook_session(sid, ws, proj, None)).unwrap();
+ if manual_before {
+ upsert_page(&mut conn, &page(ws, proj, &path, "older manual")).unwrap();
+ }
+ let id = upsert_page(&mut conn, &session_page(ws, proj, sid, "summary")).unwrap();
+ end_session(&mut conn, &sid, Some(&id)).unwrap();
+ if manual_after {
+ upsert_page(&mut conn, &page(ws, proj, &path, "manual survivor")).unwrap();
+ }
+ purge_session(
+ &mut conn,
+ ws,
+ proj,
+ sid,
+ None,
+ Compaction::Skip,
+ PurgeMode::Commit,
+ )
+ .unwrap();
+ let disk = if incoming_owned {
+ session_page(ws, proj, sid, "rewritten summary")
+ } else {
+ page(ws, proj, &path, "rewritten manual")
+ };
+ let rows_before = count(&conn, "SELECT COUNT(*) FROM pages");
+ let result = upsert_page_from_disk(&mut conn, &disk);
+ if blocked {
+ assert!(
+ matches!(result, Err(StoreError::SessionPurged(_))),
+ "{label}: {result:?}"
+ );
+ assert_eq!(
+ count(&conn, "SELECT COUNT(*) FROM pages"),
+ rows_before,
+ "{label}"
+ );
+ } else {
+ assert!(result.is_ok(), "{label}: {result:?}");
+ }
+ // Tombstones are scoped; the same session id in a sibling project
+ // and another session's path in this project remain writable.
+ let sibling = get_or_create_project(&mut conn, &ws, "sibling", None).unwrap();
+ assert!(
+ upsert_page_from_disk(&mut conn, &session_page(ws, sibling, sid, "sibling"))
+ .is_ok()
+ );
+ assert!(
+ upsert_page_from_disk(
+ &mut conn,
+ &session_page(ws, proj, SessionId::new(), "other session")
+ )
+ .is_ok()
+ );
+ let other_ws = get_or_create_workspace(&mut conn, "other-workspace").unwrap();
+ let other_proj = get_or_create_project(&mut conn, &other_ws, "other", None).unwrap();
+ assert!(
+ upsert_page_from_disk(
+ &mut conn,
+ &session_page(other_ws, other_proj, sid, "other workspace")
+ )
+ .is_ok()
+ );
+ // A session_id on an ordinary content page has never made that
+ // page the reserved session summary targeted by this gate.
+ let mut note = page(ws, proj, "notes/ordinary.md", "ordinary");
+ note.frontmatter_json = serde_json::json!({"session_id": sid.to_string()});
+ assert!(upsert_page_from_disk(&mut conn, &note).is_ok());
+ }
+ }
+
#[test]
fn purge_session_keeps_later_manual_page_and_its_wiki_path() {
let (_tmp, mut conn, ws, proj) = fresh_db();
diff --git a/crates/ai-memory-store/src/writer.rs b/crates/ai-memory-store/src/writer.rs
index 984e5fcb..0e5834e4 100644
--- a/crates/ai-memory-store/src/writer.rs
+++ b/crates/ai-memory-store/src/writer.rs
@@ -174,6 +174,10 @@ pub(crate) enum WriteCmd {
page: NewPage,
reply: oneshot::Sender<StoreResult<PageId>>,
},
+ UpsertPageFromDisk {
+ page: NewPage,
+ reply: oneshot::Sender<StoreResult<PageId>>,
+ },
UpsertPageIf {
page: NewPage,
precondition: ops::PagePrecondition,
@@ -2772,6 +2776,20 @@ impl WriterHandle {
rx.await.map_err(|_| StoreError::WriterClosed)?
}
+ /// Reindex a disk page, checking session-purge tombstones in the write
+ /// transaction. A live manual replacement at a purged session's path is
+ /// preserved; a leftover session summary cannot recreate deleted rows.
+ ///
+ /// # Errors
+ /// Returns [`StoreError::SessionPurged`] for a purged summary, or the
+ /// writer/SQL errors from [`Self::upsert_page`].
+ pub async fn upsert_page_from_disk(&self, page: NewPage) -> StoreResult<PageId> {
+ let (tx, rx) = oneshot::channel();
+ self.send(WriteCmd::UpsertPageFromDisk { page, reply: tx })
+ .await?;
+ rx.await.map_err(|_| StoreError::WriterClosed)?
+ }
+
/// [`Self::upsert_page`] only when `precondition` holds for the latest
/// version at the page's path, checked in the write's own transaction.
///
@@ -3851,6 +3869,10 @@ fn worker_loop(mut conn: Connection, mut rx: mpsc::Receiver<WriteCmd>) {
let result = ops::upsert_page(&mut conn, &page);
send_or_warn(reply, result, "upsert_page");
}
+ WriteCmd::UpsertPageFromDisk { page, reply } => {
+ let result = ops::upsert_page_from_disk(&mut conn, &page);
+ send_or_warn(reply, result, "upsert_page_from_disk");
+ }
WriteCmd::UpsertPageIf {
page,
precondition,
diff --git a/crates/ai-memory-wiki/src/watcher.rs b/crates/ai-memory-wiki/src/watcher.rs
index e1c5203e..7418730a 100644
--- a/crates/ai-memory-wiki/src/watcher.rs
+++ b/crates/ai-memory-wiki/src/watcher.rs
@@ -281,28 +281,11 @@ async fn handle_event(wiki: &Wiki, event: notify_debouncer_full::DebouncedEvent)
if is_reserved_page_file(raw_path, &page_path) {
continue;
}
- // A tombstoned session's page must not come back from a file its
- // purge could not remove (#701). The path shape decides whether the
- // lookup is worth a round trip: only `sessions/<id>.md` can be that
- // file, so an ordinary edit to `index.md` or a decision page never
- // queries. The sweep paths amortise the same set over a whole
- // directory instead; this one sees a single file per event.
- if let Some(session) = crate::wiki::session_id_for_page(&page_path) {
- match wiki.purged_sessions(ws, proj).await {
- Ok(purged) if purged.contains(&session) => {
- debug!(path = %page_path, "ignoring event for a purged session page");
- continue;
- }
- Ok(_) => {}
- // Fails open, deliberately: a transient lookup error must not
- // stop the watcher from indexing edits. The cost of failing
- // open here is bounded — the next reconcile pass loads the set
- // again and skips the page then.
- Err(e) => warn!(path = %page_path, error = %e, "purged-session lookup failed"),
- }
- }
match wiki.reindex_page(ws, proj, page_path.clone()).await {
Ok(_) => debug!(path = %page_path, "reindexed via watcher"),
+ Err(WikiError::Store(ai_memory_store::StoreError::SessionPurged(_))) => {
+ debug!(path = %page_path, "ignoring event for a purged session page");
+ }
Err(e) => warn!(path = %page_path, error = %e, "watcher reindex failed"),
}
}
@@ -352,21 +335,12 @@ async fn reindex_project_dir(
}
};
- // Fails open for the same reason the single-event path does: a lookup
- // error must not stop a directory event from indexing. `Wiki::reindex_all`
- // is the one caller that fails closed, because an operator-triggered
- // reindex should report the failure rather than quietly skip the gate.
- let purged = wiki.purged_sessions(ws, proj).await.unwrap_or_else(|e| {
- warn!(error = %e, "purged-session lookup failed; not gating this pass");
- std::collections::HashSet::new()
- });
for path in pages {
- if crate::wiki::is_purged_session_page(&path, &purged) {
- debug!(path = %path, "skipping a purged session page");
- continue;
- }
match wiki.reindex_page(ws, proj, path.clone()).await {
Ok(_) => debug!(path = %path, "reindexed via watcher directory event"),
+ Err(WikiError::Store(ai_memory_store::StoreError::SessionPurged(_))) => {
+ debug!(path = %path, "skipping a purged session page");
+ }
Err(e) => warn!(path = %path, error = %e, "watcher directory reindex failed"),
}
}
@@ -693,25 +667,15 @@ async fn reconcile(
tokio::task::spawn_blocking(move || walk_markdown_partial(&proj_root))
.await
.map_err(|e| WikiError::Io(std::io::Error::other(e.to_string())))??;
- // Once per directory, not once per page: a project accumulates one
- // tombstone per purge, and the set is only consulted for the
- // `sessions/<id>.md` paths that a session purge could have left behind.
- let purged = wiki.purged_sessions(ws, proj).await?;
let mut walked: HashSet<PagePath> = HashSet::with_capacity(pages.len());
for path in pages {
walked.insert(path.clone());
- if crate::wiki::is_purged_session_page(&path, &purged) {
- debug!(
- path = %path,
- "skipping reconcile of a purged (tombstoned) session page",
- );
- stats.skipped_purged_sessions += 1;
- continue;
- }
- if let Err(e) = wiki.reindex_page(ws, proj, path.clone()).await {
- warn!(path = %path, error = %e, "reconcile reindex failed");
- } else {
- stats.indexed += 1;
+ match wiki.reindex_page(ws, proj, path.clone()).await {
+ Ok(_) => stats.indexed += 1,
+ Err(WikiError::Store(ai_memory_store::StoreError::SessionPurged(_))) => {
+ stats.skipped_purged_sessions += 1;
+ }
+ Err(e) => warn!(path = %path, error = %e, "reconcile reindex failed"),
}
}
@@ -1047,6 +1011,96 @@ mod tests {
/// case where the file *outlives* the purge: a cleanup failure is a
/// reported, already-tested outcome, and after one the rows are gone while
/// the markdown is still on disk. Reverting the tombstone gate fails this.
+ #[tokio::test]
+ async fn manual_survivor_remains_reindexable_after_session_purge() {
+ let (_tmp, store, wiki, ws, proj) = setup().await;
+ let sid = ai_memory_core::SessionId::new();
+ store
+ .writer
+ .begin_session(ai_memory_core::NewSession {
+ occurred_at: None,
+ id: sid,
+ workspace_id: ws,
+ project_id: proj,
+ agent_kind: ai_memory_core::AgentKind::ClaudeCode,
+ cwd: None,
+ actor_user: None,
+ })
+ .await
+ .unwrap();
+ let path = PagePath::new(format!("sessions/{sid}.md")).unwrap();
+ let abs = wiki.abs_path(ws, proj, &path);
+ std::fs::create_dir_all(abs.parent().unwrap()).unwrap();
+ std::fs::write(
+ &abs,
+ format!("---\ntitle: Session\nsession_id: {sid}\n---\n\noriginalsummarytoken\n"),
+ )
+ .unwrap();
+ let id = wiki.reindex_page(ws, proj, path.clone()).await.unwrap();
+ store.writer.end_session(sid, Some(id)).await.unwrap();
+ // A manual replacement has no session_id; the store deliberately preserves it (#866).
+ std::fs::write(&abs, "---\ntitle: Manual\n---\n\nmanualbeforetoken\n").unwrap();
+ wiki.reindex_page(ws, proj, path.clone()).await.unwrap();
+ let outcome = wiki
+ .purge_session(ws, proj, sid, None, ai_memory_store::Compaction::Skip)
+ .await
+ .unwrap();
+ assert_eq!(outcome.summary.pages_deleted, 1);
+ assert!(outcome.summary.removed_paths.is_empty());
+ assert!(abs.is_file());
+ assert_eq!(
+ store
+ .reader
+ .search_pages("manualbeforetoken".into(), 10, None)
+ .await
+ .unwrap()
+ .len(),
+ 1
+ );
+ for (indexer, token) in [
+ ("reconcile", "manualreconciletoken"),
+ ("file event", "manualfileeventtoken"),
+ ("directory event", "manualdirectorytoken"),
+ ("rebuild", "manualrebuildtoken"),
+ ] {
+ std::fs::write(&abs, format!("---\ntitle: Manual\n---\n\n{token}\n")).unwrap();
+ match indexer {
+ "reconcile" => {
+ let stats = reconcile(&wiki, &mut MissingStreaks::new()).await.unwrap();
+ assert_eq!(stats.skipped_purged_sessions, 0);
+ }
+ "file event" => {
+ let event = notify_debouncer_full::DebouncedEvent::new(
+ notify::Event::new(EventKind::Modify(notify::event::ModifyKind::Any))
+ .add_path(abs.clone()),
+ std::time::Instant::now(),
+ );
+ handle_event(&wiki, event).await;
+ }
+ "directory event" => {
+ assert!(
+ reindex_project_dir(&wiki, ws, proj, wiki.project_root(ws, proj)).await
+ );
+ }
+ "rebuild" => {
+ let summary = wiki.reindex_all().await.unwrap();
+ assert_eq!(summary.skipped_purged_sessions, 0);
+ }
+ _ => unreachable!(),
+ }
+ let hits = store
+ .reader
+ .search_pages(token.into(), 10, None)
+ .await
+ .unwrap();
+ assert_eq!(
+ hits.len(),
+ 1,
+ "{indexer} must keep the preserved manual page editable"
+ );
+ }
+ }
+
#[tokio::test]
async fn purged_session_page_is_not_resurrected_by_a_reconcile_tick() {
let (tmp, store, wiki, ws, proj) = setup().await;
diff --git a/crates/ai-memory-wiki/src/wiki.rs b/crates/ai-memory-wiki/src/wiki.rs
index e16589cb..1db66595 100644
--- a/crates/ai-memory-wiki/src/wiki.rs
+++ b/crates/ai-memory-wiki/src/wiki.rs
@@ -89,10 +89,9 @@ pub struct ReindexSummary {
/// The session a page belongs to, for paths that name one.
///
-/// Pure path shape, no I/O: only `sessions/<id>.md` can be resurrected by a
-/// purge whose file cleanup failed, so this is what decides whether the
-/// tombstone set is worth consulting — or, on the single-event path, whether
-/// it is worth loading at all.
+/// Pure path shape, no I/O. Used to keep session-summary paths out of the
+/// missing-file retirement safety net. Reindex ownership and tombstone
+/// checks belong to the store transaction, not this path-only classifier.
pub(crate) fn session_id_for_page(path: &PagePath) -> Option<SessionId> {
path.as_str()
.strip_prefix("sessions/")
@@ -100,18 +99,6 @@ pub(crate) fn session_id_for_page(path: &PagePath) -> Option<SessionId> {
.and_then(|id| id.parse::<SessionId>().ok())
}
-/// Whether `path` is the page of a session this scope has tombstoned.
-///
-/// For callers that already hold the scope's set. The empty-set and
-/// path-shape checks come first so a sweep over a project with no purges
-/// never parses an id.
-pub(crate) fn is_purged_session_page(path: &PagePath, purged: &HashSet<SessionId>) -> bool {
- if purged.is_empty() {
- return false;
- }
- session_id_for_page(path).is_some_and(|id| purged.contains(&id))
-}
-
enum PageStoreRemoval {
Delete {
author_id: Option<UserId>,
@@ -1810,11 +1797,9 @@ impl Wiki {
}
}
- /// Session ids this scope has tombstoned, as a set for the reindex gate.
- ///
- /// The session-level twin of [`WriterHandle::scope_is_purged`], and read
- /// the same way: once per directory per reindex pass, by the callers that
- /// walk a tree, rather than once per page (#701).
+ /// Session ids this scope has tombstoned, for lifecycle inspection.
+ /// Reindex enforces these tombstones in its store write transaction,
+ /// rather than authorizing a write from an earlier snapshot of this set.
///
/// # Errors
/// Propagates the store error.
@@ -2282,7 +2267,7 @@ impl Wiki {
let id = self
.writer
- .upsert_page(NewPage {
+ .upsert_page_from_disk(NewPage {
workspace_id,
project_id,
path,
@@ -2508,18 +2493,12 @@ impl Wiki {
let pages = tokio::task::spawn_blocking(move || crate::watcher::walk_markdown(&pr))
.await
.map_err(|e| WikiError::Io(std::io::Error::other(e.to_string())))??;
- let purged = self.purged_sessions(ws, proj).await?;
for path in pages {
- if is_purged_session_page(&path, &purged) {
- tracing::debug!(
- path = %path,
- "skipping reindex of a purged (tombstoned) session page",
- );
- summary.skipped_purged_sessions += 1;
- continue;
- }
match self.reindex_page(ws, proj, path).await {
Ok(_) => summary.pages += 1,
+ Err(WikiError::Store(ai_memory_store::StoreError::SessionPurged(_))) => {
+ summary.skipped_purged_sessions += 1;
+ }
Err(WikiError::Store(ai_memory_store::StoreError::PagePathCollides {
requested,
existing,
@@ -8466,6 +8445,79 @@ mod tests {
(store, wiki, ws, src, dst, sid, path)
}
+ #[tokio::test]
+ async fn reindex_queued_after_purge_rechecks_session_tombstone() {
+ let tmp = TempDir::new().unwrap();
+ let (store, wiki, ws, proj, _, sid, path) = session_with_page(&tmp).await;
+ let page_id = wiki.reindex_page(ws, proj, path.clone()).await.unwrap();
+ store.writer.end_session(sid, Some(page_id)).await.unwrap();
+ // The watcher's per-directory snapshot predates the purge.
+ let snapshot = wiki.purged_sessions(ws, proj).await.unwrap();
+ assert!(!snapshot.contains(&sid));
+ let abs = wiki.abs_path(ws, proj, &path);
+ let raw = std::fs::read(&abs).unwrap();
+ let guard = wiki.mutation_lock.read().await;
+ let purge = wiki.purge_session(ws, proj, sid, None, ai_memory_store::Compaction::Skip);
+ tokio::pin!(purge);
+ tokio::select! { biased;
+ _ = &mut purge => panic!("purge should wait for the shared guard"),
+ _ = std::future::ready(()) => {}
+ }
+ // A page already admitted by the stale snapshot queues behind the purge.
+ let reindex = wiki.reindex_page(ws, proj, path.clone());
+ tokio::pin!(reindex);
+ tokio::select! { biased;
+ _ = &mut reindex => panic!("reindex should wait behind queued purge"),
+ _ = std::future::ready(()) => {}
+ }
+ // Force cleanup failure portably, as the owned-session purge test
+ // does. Restore the readable leftover before the queued reindex runs.
+ std::fs::remove_file(&abs).unwrap();
+ std::fs::create_dir(&abs).unwrap();
+ drop(guard);
+ let outcome = purge.await.unwrap();
+ assert_eq!(outcome.files_failed, vec![path.clone()]);
+ std::fs::remove_dir(&abs).unwrap();
+ std::fs::write(&abs, raw).unwrap();
+ assert!(abs.is_file());
+ assert!(
+ store
+ .reader
+ .find_session_scope(sid)
+ .await
+ .unwrap()
+ .is_none()
+ );
+ assert!(
+ store
+ .reader
+ .search_pages("consolidated".into(), 10, None)
+ .await
+ .unwrap()
+ .is_empty()
+ );
+ assert!(wiki.purged_sessions(ws, proj).await.unwrap().contains(&sid));
+ let reindexed = reindex.await;
+ let hits = store
+ .reader
+ .search_pages("consolidated".into(), 10, None)
+ .await
+ .unwrap();
+ assert!(
+ matches!(
+ reindexed,
+ Err(WikiError::Store(
+ ai_memory_store::StoreError::SessionPurged(_)
+ ))
+ ),
+ "{reindexed:?}"
+ );
+ assert!(
+ hits.is_empty(),
+ "a reindex queued after purge resurrected the tombstoned session page"
+ );
+ }
+
#[tokio::test]
async fn purge_session_waits_for_in_flight_reindex_before_deleting_rows() {
let tmp = TempDir::new().unwrap();
diff --git a/docs/lifecycle-ops.md b/docs/lifecycle-ops.md
index d926fea8..b3b35fca 100644
--- a/docs/lifecycle-ops.md
+++ b/docs/lifecycle-ops.md
@@ -192,6 +192,15 @@ busy server therefore holds up wiki mutations for longer than the delete itself.
The git checkpoints taken before and after the purge sit outside the guard: they
bracket it, they do not snapshot it.
+Reindex checks session-purge tombstones in the same SQL transaction as its
+page write. A watcher event or directory walk that started before a purge
+cannot use a stale check to restore a summary left by failed file cleanup.
+A manual replacement already preserved by the purge remains reindexable:
+the disk page must not name the purged session as its owner, and a live
+non-owned version must still exist at that path. A leftover legacy summary
+without `session_id` has no such surviving version and stays excluded.
+The watcher, its reconciliation pass and `reindex` use the same check.
+
### Scope containment
The session id is never authority on its own. Every statement is filtered on