Skip to content

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

Rust

feat(sessions): end idle sessions from the maintenance tick

Djalma Júnior43b288a35611
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 59954396..ce65d053 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,20 @@ version in [`docs/changelog/`](docs/changelog/):
## [Unreleased]
+### Added
+- Added opt-in `[sessions] idle_end_after_hours` (env
+ `AI_MEMORY_SESSIONS__IDLE_END_AFTER_HOURS`; default `0`, off; range
+ `1..=8760`). When it is set, the `serve` maintenance tick ends open sessions
+ with no activity for that many hours, such as a harness that crashed or a
+ terminal closed before `SessionEnd` fired. A substantive session gets its
+ `sessions/<id>.md` summary page, attributed to the session's owner, and its
+ consolidation job. A boundary-only session ends lifecycle-only and releases
+ the handoff it had accepted. The tick creates no handoff of its own and skips
+ sessions bound to an active managed run. A real `SessionEnd` or checkpoint
+ that lands while the tick runs wins, and the tick leaves that session alone.
+ `ended_at` is the time of the tick; the session's last activity goes in the
+ audit row. (#PRNUM)
+
## [3.1.0] - 2026-10-16
### Added
diff --git a/Cargo.lock b/Cargo.lock
index cee0583a..dde95534 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -176,6 +176,7 @@ dependencies = [
"sha2",
"tempfile",
"tokio",
+ "tower",
"tracing",
"uuid",
]
diff --git a/crates/ai-memory-cli/src/commands/serve.rs b/crates/ai-memory-cli/src/commands/serve.rs
index 6c388ee5..ae28908e 100644
--- a/crates/ai-memory-cli/src/commands/serve.rs
+++ b/crates/ai-memory-cli/src/commands/serve.rs
@@ -1413,10 +1413,13 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {
embedder.clone(),
admin_llm.clone(),
config.decay,
+ config.sessions,
config.dream,
activity_clock,
config.contradiction_band_min,
config.contradiction_band_max,
+ config.consolidate_on_session_end,
+ consolidator.is_some(),
)
.await;
@@ -2081,10 +2084,13 @@ async fn start_maintenance_scheduler(
embedder: Option<Arc<dyn Embedder>>,
llm: Option<Arc<dyn LlmProvider>>,
decay: crate::config::DecaySettings,
+ sessions: crate::config::SessionsSettings,
dream: crate::config::DreamSettings,
activity_clock: ai_memory_consolidate::ActivityClock,
contradiction_band_min: f32,
contradiction_band_max: f32,
+ consolidate_on_session_end: bool,
+ has_session_consolidator: bool,
) -> Vec<tokio::task::JoinHandle<()>> {
let maintenance_enabled = settings.enabled;
if !maintenance_enabled {
@@ -2449,6 +2455,92 @@ async fn start_maintenance_scheduler(
}
}
+ // Idle session auto-end: end the open sessions that never received a
+ // `SessionEnd` (crashed harness, closed terminal, timed-out hook) with
+ // the effects the hook path would have given them — summary page and
+ // consolidation job, never a handoff. Bounded batch every fixed
+ // interval; the scan is stateless and idempotent (the writer-side
+ // `ended_at IS NULL` CAS plus the conditional page write make a double
+ // end impossible), so it needs no persisted cadence state.
+ let idle_end_after_hours = sessions.idle_end_after_hours;
+ if maintenance_enabled && idle_end_after_hours > 0 {
+ let writer = writer.clone();
+ let reader = reader.clone();
+ let wiki = wiki.clone();
+ tasks.push(tokio::spawn(async move {
+ let mut interval = tokio::time::interval(std::time::Duration::from_secs(
+ ai_memory_hooks::IDLE_END_INTERVAL_SECS,
+ ));
+ // The first tick fires immediately; let the server come up and
+ // the writer settle before the first scan.
+ interval.tick().await;
+ loop {
+ interval.tick().await;
+ let now_us = jiff::Timestamp::now().as_microsecond();
+ // The config load bounds the value to a microsecond-safe
+ // range; the checked arithmetic is the runtime belt (an
+ // overflow would flip the cutoff and mass-end sessions).
+ let Some(cutoff_us) = i64::from(idle_end_after_hours)
+ .checked_mul(3_600_000_000)
+ .and_then(|window_us| now_us.checked_sub(window_us))
+ else {
+ tracing::warn!(
+ idle_end_after_hours,
+ "idle session auto-end tick: cutoff arithmetic overflowed; skipping this pass"
+ );
+ continue;
+ };
+ // Over-fetch the selection past the active-run sessions:
+ // the tick excludes them (their lifecycle belongs to the
+ // run), and the exclusion must not starve the batch bound
+ // behind a backlog of persistently excluded sessions.
+ let active_runs = match reader
+ .active_managed_run_native_session_ids()
+ .await
+ {
+ Ok(active_runs) => active_runs,
+ Err(error) => {
+ tracing::warn!(error = %error, "idle session auto-end run check failed");
+ continue;
+ }
+ };
+ let idle = match reader
+ .idle_open_sessions(
+ cutoff_us,
+ ai_memory_hooks::IDLE_END_BATCH
+ .saturating_add(active_runs.len()),
+ )
+ .await
+ {
+ Ok(idle) => idle,
+ Err(error) => {
+ tracing::warn!(error = %error, "idle session auto-end selection failed");
+ continue;
+ }
+ };
+ if idle.is_empty() {
+ continue;
+ }
+ match ai_memory_hooks::run_idle_end_tick(&ai_memory_hooks::IdleEndTickInput {
+ writer: &writer,
+ reader: &reader,
+ wiki: &wiki,
+ sessions: idle,
+ now_us: jiff::Timestamp::now().as_microsecond(),
+ consolidate_on_session_end,
+ has_consolidator: has_session_consolidator,
+ })
+ .await
+ {
+ // Success is the tick's own log (idle_end.rs); the
+ // scheduler only surfaces failures.
+ Ok(_outcome) => {}
+ Err(error) => tracing::warn!(error = %error, "idle session auto-end tick failed"),
+ }
+ }
+ }));
+ }
+
if tasks.is_empty() {
info!("scheduled maintenance enabled but all intervals are disabled");
} else {
@@ -4268,10 +4360,13 @@ mod tests {
None,
None,
crate::config::DecaySettings::default(),
+ crate::config::SessionsSettings::default(),
crate::config::DreamSettings::default(),
ai_memory_consolidate::ActivityClock::default(),
ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
+ false,
+ false,
)
.await;
assert!(tasks.is_empty());
@@ -4318,10 +4413,13 @@ mod tests {
None,
None,
crate::config::DecaySettings::default(),
+ crate::config::SessionsSettings::default(),
crate::config::DreamSettings::default(),
ai_memory_consolidate::ActivityClock::default(),
ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
+ false,
+ false,
)
.await;
// One enabled lint/sweep job plus the independent hollow-project job.
@@ -4332,6 +4430,235 @@ mod tests {
}
}
+ /// The idle auto-end task starts only with maintenance enabled AND
+ /// `idle_end_after_hours > 0`; either switch off leaves the task count
+ /// unchanged.
+ #[tokio::test]
+ async fn idle_end_tick_does_not_start_when_disabled_or_maintenance_off() {
+ let baseline = MaintenanceSettings {
+ enabled: true,
+ forget_sweep_interval_secs: 0,
+ lint_interval_secs: 60,
+ embedding_backfill_interval_secs: 0,
+ reconcile_tombstones_deleted_pages: false,
+ };
+ // Key at 0: the baseline task count (one lint job + hollow-project job).
+ let (_tmp, store, wiki, _ws, _first, _second) = two_project_wiki().await;
+ let tasks = start_maintenance_scheduler(
+ baseline.clone(),
+ AutoImproveSettings::default(),
+ store.reader.clone(),
+ store.writer.clone(),
+ wiki,
+ None,
+ None,
+ crate::config::DecaySettings::default(),
+ crate::config::SessionsSettings::default(),
+ crate::config::DreamSettings::default(),
+ ai_memory_consolidate::ActivityClock::default(),
+ ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
+ false,
+ false,
+ )
+ .await;
+ assert_eq!(tasks.len(), 2);
+ for task in tasks {
+ task.abort();
+ }
+
+ // Key on: exactly one extra task — the idle auto-end loop.
+ let (_tmp, store, wiki, _ws, _first, _second) = two_project_wiki().await;
+ let tasks = start_maintenance_scheduler(
+ baseline.clone(),
+ AutoImproveSettings::default(),
+ store.reader.clone(),
+ store.writer.clone(),
+ wiki,
+ None,
+ None,
+ crate::config::DecaySettings::default(),
+ crate::config::SessionsSettings {
+ idle_end_after_hours: 1,
+ },
+ crate::config::DreamSettings::default(),
+ ai_memory_consolidate::ActivityClock::default(),
+ ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
+ false,
+ false,
+ )
+ .await;
+ assert_eq!(tasks.len(), 3);
+ for task in tasks {
+ task.abort();
+ }
+
+ // Maintenance disabled with the key on: nothing starts.
+ let (_tmp, store, wiki, _ws, _first, _second) = two_project_wiki().await;
+ let tasks = start_maintenance_scheduler(
+ MaintenanceSettings {
+ enabled: false,
+ ..baseline
+ },
+ AutoImproveSettings::default(),
+ store.reader.clone(),
+ store.writer.clone(),
+ wiki,
+ None,
+ None,
+ crate::config::DecaySettings::default(),
+ crate::config::SessionsSettings {
+ idle_end_after_hours: 1,
+ },
+ crate::config::DreamSettings::default(),
+ ai_memory_consolidate::ActivityClock::default(),
+ ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
+ true,
+ true,
+ )
+ .await;
+ assert!(tasks.is_empty());
+ }
+
+ /// With the key on, the first real pass (one fixed interval after start,
+ /// fast-forwarded with paused `tokio::time`) ends an idle session with
+ /// the page, the watermark, the audit row and the consolidation job —
+ /// no real sleeping.
+ #[tokio::test]
+ async fn idle_end_tick_ends_an_idle_session_on_the_first_pass() {
+ let (_tmp, store, wiki, ws, proj, _second) = two_project_wiki().await;
+ tokio::time::pause();
+ let now = jiff::Timestamp::now().as_microsecond();
+ let last_activity = now - 2 * 3_600_000_000; // two hours ago.
+ let sid = SessionId::new();
+ store
+ .writer
+ .begin_session(NewSession {
+ id: sid,
+ workspace_id: ws,
+ project_id: proj,
+ agent_kind: AgentKind::Codex,
+ cwd: Some("/repo".into()),
+ actor_user: None,
+ occurred_at: Some(last_activity),
+ })
+ .await
+ .unwrap();
+ store
+ .writer
+ .insert_observation(Sanitized::new(
+ NewObservation {
+ session_id: sid,
+ workspace_id: ws,
+ project_id: proj,
+ kind: ObservationKind::UserPrompt,
+ extension: None,
+ source_event: None,
+ title: "idle scheduler test".into(),
+ body: "prompt two hours ago".into(),
+ importance: 5,
+ occurred_at: Some(last_activity),
+ },
+ &Sanitizer::builtin(),
+ ))
+ .await
+ .unwrap();
+
+ let tasks = start_maintenance_scheduler(
+ MaintenanceSettings {
+ enabled: true,
+ forget_sweep_interval_secs: 0,
+ lint_interval_secs: 0,
+ embedding_backfill_interval_secs: 0,
+ reconcile_tombstones_deleted_pages: false,
+ },
+ AutoImproveSettings::default(),
+ store.reader.clone(),
+ store.writer.clone(),
+ wiki,
+ None,
+ None,
+ crate::config::DecaySettings::default(),
+ crate::config::SessionsSettings {
+ idle_end_after_hours: 1,
+ },
+ crate::config::DreamSettings::default(),
+ ai_memory_consolidate::ActivityClock::default(),
+ ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
+ true,
+ true,
+ )
+ .await;
+
+ // The settle tick already fired; let the spawned task register its
+ // first real interval timer, then fast-forward one fixed interval so
+ // the first real pass runs.
+ for _ in 0..32 {
+ tokio::task::yield_now().await;
+ }
+ tokio::time::advance(std::time::Duration::from_secs(
+ ai_memory_hooks::IDLE_END_INTERVAL_SECS,
+ ))
+ .await;
+ let mut ended = false;
+ for _ in 0..500 {
+ let disp = store
+ .reader
+ .session_end_disposition(sid, ws, proj, AgentKind::Codex)
+ .await
+ .unwrap();
+ if matches!(disp, ai_memory_store::SessionEndDisposition::AlreadyEnded) {
+ ended = true;
+ break;
+ }
+ tokio::time::advance(std::time::Duration::from_millis(10)).await;
+ }
+ assert!(ended, "the first pass must end the idle session");
+
+ // Page written, tick-clock ended_at (last activity in the audit
+ // detail), audit row, consolidation job.
+ let page = store
+ .reader
+ .latest_page_id_by_ids(ws, proj, format!("sessions/{sid}.md"))
+ .await
+ .unwrap();
+ assert!(page.is_some());
+ let audit = store
+ .reader
+ .list_audit_events(ai_memory_store::AuditLogFilter {
+ op: Some("idle_session_end".into()),
+ ..Default::default()
+ })
+ .await
+ .unwrap();
+ assert_eq!(audit.len(), 1);
+ assert!(
+ audit[0].at >= now && audit[0].at < now + 60_000_000_000,
+ "ended_at is the tick's clock (the discovery is ordered by ended_at): {}",
+ audit[0].at
+ );
+ assert!(
+ audit[0].detail.contains(&last_activity.to_string()),
+ "the last activity survives in the audit detail: {}",
+ audit[0].detail
+ );
+ // Claim with a fresh clock: the enqueue's `requested_at` is the
+ // tick's wall time, after this test's `now`.
+ let now_after = jiff::Timestamp::now().as_microsecond();
+ let job = store
+ .writer
+ .claim_session_consolidation(now_after + 1_000, now_after - 1_000)
+ .await
+ .unwrap();
+ assert_eq!(job.map(|j| j.session_id()), Some(sid));
+ for task in tasks {
+ task.abort();
+ }
+ }
+
struct PanicLlm;
impl LlmProvider for PanicLlm {
diff --git a/crates/ai-memory-cli/src/config.rs b/crates/ai-memory-cli/src/config.rs
index 39ac68c8..11f0a0bb 100644
--- a/crates/ai-memory-cli/src/config.rs
+++ b/crates/ai-memory-cli/src/config.rs
@@ -567,6 +567,8 @@ pub struct Config {
pub decay: DecaySettings,
/// Server-side scheduled maintenance. Jobs run outside hook latency.
pub maintenance: MaintenanceSettings,
+ /// Server-side session lifecycle (idle auto-end tick).
+ pub sessions: SessionsSettings,
/// Lower edge (inclusive) of `memory_lint`'s A5 zero-LLM
/// contradiction-detection cosine-similarity band. Two cold pages whose
/// embeddings sit in `[contradiction_band_min, contradiction_band_max)`
@@ -1385,6 +1387,7 @@ impl Default for Config {
embedding_document_prefix: None,
decay: DecaySettings::default(),
maintenance: MaintenanceSettings::default(),
+ sessions: SessionsSettings::default(),
contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
dream: DreamSettings::default(),
@@ -1829,6 +1832,21 @@ impl Default for MaintenanceSettings {
}
}
+/// `[sessions]` server-side session lifecycle.
+///
+/// Env form: `AI_MEMORY_SESSIONS__IDLE_END_AFTER_HOURS=24`.
+#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
+#[serde(default)]
+pub struct SessionsSettings {
+ /// Hours of silence after which the maintenance tick ends an open
+ /// session that never received a `SessionEnd` (crashed harness, closed
+ /// terminal, timed-out hook): summary page + consolidation job, no
+ /// handoff. `0` (the default) disables the tick — the explicit
+ /// `finalize-on-exit` / `repair-backfill-timestamps` path stays the only
+ /// end for sessions an operator may still come back to.
+ pub idle_end_after_hours: u32,
+}
+
/// `[dream]` — the opt-in LLM dream pass (docs/design-memory-aging.md §B2–B4).
///
/// OFF by default (`enabled = false`): the scheduled job is not started, and even
@@ -2375,6 +2393,19 @@ impl Config {
validate_run_profiles(&config.run)?;
+ // The idle auto-end tick turns `idle_end_after_hours` into a
+ // microsecond cutoff: a value above a year is a configuration
+ // mistake (a typo of minutes for days), and a huge value would also
+ // push the cutoff microsecond arithmetic toward `i64` overflow.
+ // Bound it at load rather than at 3am inside the tick.
+ if config.sessions.idle_end_after_hours > 8760 {
+ anyhow::bail!(
+ "sessions.idle_end_after_hours must be 0 (off) or at most 8760 hours \
+ (one year); got {}",
+ config.sessions.idle_end_after_hours
+ );
+ }
+
if !config.decay.breadth_weight.is_finite() || config.decay.breadth_weight < 0.0 {
anyhow::bail!(
"decay.breadth_weight must be a finite number greater than or equal to zero"
@@ -6723,6 +6754,80 @@ fn ambient_llm_base_url_still_configures_opencode() {
);
}
+// --- `[sessions] idle_end_after_hours` ------------------------------
+
+/// The key defaults to `0` (off) when absent, parses from TOML, and the
+/// load-time bound rejects a year-plus value by naming the key.
+#[test]
+fn sessions_idle_end_defaults_off_loads_from_toml_and_rejects_out_of_range() {
+ use tempfile::TempDir;
+ assert_eq!(Config::default().sessions.idle_end_after_hours, 0);
+
+ let tmp = TempDir::new().unwrap();
+ let config_path = tmp.path().join("config.toml");
+ // Absent key keeps the default.
+ std::fs::write(&config_path, "# nothing\n").unwrap();
+ let config = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap();
+ assert_eq!(config.sessions.idle_end_after_hours, 0);
+
+ // TOML parse.
+ std::fs::write(&config_path, "[sessions]\nidle_end_after_hours = 24\n").unwrap();
+ let config = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap();
+ assert_eq!(config.sessions.idle_end_after_hours, 24);
+
+ // Boundary: one year is accepted.
+ std::fs::write(&config_path, "[sessions]\nidle_end_after_hours = 8760\n").unwrap();
+ let config = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap();
+ assert_eq!(config.sessions.idle_end_after_hours, 8760);
+
+ // Above the bound the load fails and names the key.
+ std::fs::write(&config_path, "[sessions]\nidle_end_after_hours = 8761\n").unwrap();
+ let error = Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))
+ .expect_err("above the bound must fail at load");
+ assert!(
+ error.to_string().contains("idle_end_after_hours"),
+ "unexpected error: {error:#}"
+ );
+}
+
+/// The env form `AI_MEMORY_SESSIONS__IDLE_END_AFTER_HOURS` outranks the
+/// TOML value, like every other flat config key.
+#[test]
+fn sessions_idle_end_env_overrides_config() {
+ use tempfile::TempDir;
+ const CHILD_MARKER: &str = "AI_MEMORY_TEST_SESSIONS_IDLE_END_CHILD";
+ if std::env::var_os(CHILD_MARKER).is_some() {
+ let tmp = TempDir::new().unwrap();
+ let config_path = tmp.path().join("config.toml");
+ std::fs::write(&config_path, "[sessions]\nidle_end_after_hours = 24\n").unwrap();
+ let config = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap();
+ assert_eq!(config.sessions.idle_end_after_hours, 48);
+ println!("sessions-idle-end-env-applied");
+ return;
+ }
+
+ let output = std::process::Command::new(std::env::current_exe().unwrap())
+ .arg("--exact")
+ .arg("config::sessions_idle_end_env_overrides_config")
+ .arg("--test-threads=1")
+ .arg("--nocapture")
+ .env(CHILD_MARKER, "1")
+ .env("AI_MEMORY_SESSIONS__IDLE_END_AFTER_HOURS", "48")
+ .output()
+ .unwrap();
+ assert!(
+ output.status.success(),
+ "child test failed:\nstdout: {}\nstderr: {}",
+ String::from_utf8_lossy(&output.stdout),
+ String::from_utf8_lossy(&output.stderr)
+ );
+ assert!(
+ String::from_utf8_lossy(&output.stdout).contains("sessions-idle-end-env-applied"),
+ "child stdout: {}",
+ String::from_utf8_lossy(&output.stdout)
+ );
+}
+
// Naming ai-memory is how an operator says they mean it: proxying Gemini stays
// possible, and the explicit setting outranks an ambient one that disagrees.
#[test]
diff --git a/crates/ai-memory-cli/templates/config.default.toml b/crates/ai-memory-cli/templates/config.default.toml
index 817cd2a2..c4ea228f 100644
--- a/crates/ai-memory-cli/templates/config.default.toml
+++ b/crates/ai-memory-cli/templates/config.default.toml
@@ -150,6 +150,17 @@ log_level = "info"
# embedding_model = "..." # provider-specific override
# embedding_dim = 384 # must match the model
+# --- Session lifecycle (server-side) --------------------------------------
+# [sessions] idle_end_after_hours = N (default 0 = off): the maintenance
+# tick ends open sessions whose last activity is older than N hours
+# (crashed harness, closed terminal, timed-out hook) with the summary page
+# and consolidation job a real SessionEnd would have given — never a
+# handoff. Bounded batch of 25 every 15 minutes; a late real SessionEnd
+# always wins (page write conditional on the selected version, end stamp a
+# CAS on ended_at IS NULL). Validated at load: 0 or 1..=8760.
+# [sessions]
+# idle_end_after_hours = 24
+
[decay]
lambda = 0.02
sigma = 0.6
diff --git a/crates/ai-memory-hooks/Cargo.toml b/crates/ai-memory-hooks/Cargo.toml
index 16dc3f13..d67fa918 100644
--- a/crates/ai-memory-hooks/Cargo.toml
+++ b/crates/ai-memory-hooks/Cargo.toml
@@ -40,6 +40,8 @@ git2.workspace = true
ai-memory-llm.workspace = true
async-trait.workspace = true
rusqlite.workspace = true
+# Drive the real `/hook` route in the idle-end race tests.
+tower.workspace = true
[lints]
workspace = true
diff --git a/crates/ai-memory-hooks/src/idle_end.rs b/crates/ai-memory-hooks/src/idle_end.rs
new file mode 100644
index 00000000..d31da157
--- /dev/null
+++ b/crates/ai-memory-hooks/src/idle_end.rs
@@ -0,0 +1,391 @@
+//! Server-side idle session auto-end.
+//!
+//! A harness that crashes, gets killed, or times out mid-task never delivers
+//! its `SessionEnd`: the session row stays open forever, its observations are
+//! never consolidated, and no one decides whether its summary page was worth
+//! keeping. When `[sessions] idle_end_after_hours` is set, the `ai-memory
+//! serve` maintenance scheduler runs [`run_idle_end_tick`] every
+//! [`IDLE_END_INTERVAL_SECS`]: it ends the open sessions whose last activity
+//! is older than the cutoff with the effects a real `SessionEnd` would have
+//! had — summary page, consolidation job, watermark — and re-opens a handoff
+//! that an ended boundary-only session had claimed for its owner.
+//!
+//! The baton is the hook path's decision: the tick never creates a handoff.
+//! What the server itself checks are the idle threshold — the session's
+//! last activity is older than `[sessions] idle_end_after_hours` — and the
+//! active-run exclusion: a session bound to a `state = 'active'` managed run
+//! is left to that run's own lifecycle.
+//!
+//! The tick never owns a session a live hook owns. Selection is a single
+//! read that also captures each session page's current version; a real
+//! `SessionEnd` landing between that read and the tick's write wins at every
+//! seam:
+//! - the substantive summary page is written conditionally on the version
+//! seen at selection ([`ai_memory_wiki::ConditionalWrite`]) — a page the
+//! hook delivered after the selection is a precondition mismatch, so the
+//! session is skipped entirely;
+//! - the end stamp re-verifies, inside its CAS, that the session is still
+//! open in its scope, that the session's observation count (every row of
+//! the session, the digest's population) still equals the count the digest
+//! was built from, and that the latest page version is still the one the
+//! tick wrote or kept;
+//! - the lifecycle-only end applies the same scope/open guards before any
+//! mutation and re-checks substantiveness atomically;
+//! - sessions bound to an active managed run are excluded before any write,
+//! and the caller over-fetches the selection (`IDLE_END_BATCH` plus the
+//! number of active-run sessions) so the exclusion cannot starve the
+//! batch behind persistently excluded sessions;
+//! - attribution follows the session's stored owner, parsed with the same
+//! fail-closed semantics as the `SessionEnd` path.
+
+use std::collections::HashSet;
+
+use ai_memory_core::{PageId, SessionId};
+use ai_memory_store::{
+ IdleEndAction, IdleEndCandidate, IdleEndResult, PagePrecondition, ReaderPool, WriterHandle,
+};
+use ai_memory_wiki::{ConditionalWrite, Wiki, WritePageRequest};
+use tracing::{debug, info, warn};
+
+use crate::router::stored_session_identity;
+use crate::synth::{SessionDigest, synthesize_session_page};
+
+/// Bounded per-tick selection: one tick ends at most this many sessions; the
+/// next picks up the rest. Keeps a backlog of long-idle sessions from
+/// turning one tick into an unbounded burst of page writes and
+/// consolidation jobs.
+pub const IDLE_END_BATCH: usize = 25;
+
+/// Fixed tick interval. The scan is stateless and idempotent (the
+/// `ended_at IS NULL` CAS plus the conditional page write make a double
+/// end impossible), so a fixed interval needs no persisted cadence state.
+pub const IDLE_END_INTERVAL_SECS: u64 = 15 * 60;
+
+/// What one idle auto-end tick did.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub struct IdleEndTickOutcome {
+ /// Substantive sessions ended (summary page + consolidation job).
+ pub ended: usize,
+ /// Boundary-only sessions ended (no page, no job; a handoff they had
+ /// claimed is re-opened for its owner).
+ pub lifecycle_only: usize,
+ /// Sessions skipped: an active managed run owns them, their page write
+ /// lost to a real `SessionEnd`, their end CAS lost, or their stored
+ /// owner is corrupt.
+ pub skipped: usize,
+ /// Summary pages the tick wrote.
+ pub pages_written: usize,
+}
+
+/// Everything one tick needs. `sessions` is the selection the serve loop
+/// made (oldest last-activity first); the serve loop over-fetches it —
+/// [`IDLE_END_BATCH`] plus the number of active-run sessions — so the
+/// exclusion of active-run sessions cannot starve the batch. The page
+/// version each entry carries is the conditional write's precondition.
+pub struct IdleEndTickInput<'a> {
+ /// Writer handle for the batched end command.
+ pub writer: &'a WriterHandle,
+ /// Reader pool for the per-session reads.
+ pub reader: &'a ReaderPool,
+ /// Wiki for the conditional page write and the auto-commit.
+ pub wiki: &'a Wiki,
+ /// Selected idle sessions.
+ pub sessions: Vec<ai_memory_store::IdleOpenSession>,
+ /// The tick's clock (Unix microseconds): the `ended_at` of every end it
+ /// stamps, so the auto-improvement discovery (ordered by `ended_at`)
+ /// finds auto-ended sessions in the order they were ended.
+ pub now_us: i64,
+ /// Server `consolidate_on_session_end` flag.
+ pub consolidate_on_session_end: bool,
+ /// Whether a consolidator is configured; the enqueue only happens when
+ /// this and `consolidate_on_session_end` are both true, mirroring the
+ /// hook path.
+ pub has_consolidator: bool,
+}
+
+/// What the summary-page step decided for one substantive session.
+enum PageDecision {
+ /// The tick wrote the rule-based summary; the id is current.
+ Written(PageId),
+ /// The agent's own page is kept as-is (no write); the id is current.
+ KeptAgentPage(PageId),
+ /// A real `SessionEnd` (or another writer) landed at the path after the
+ /// selection: the session is skipped entirely.
+ Superseded,
+}
+
+/// Run one idle auto-end tick over a pre-selected batch of idle sessions.
+///
+/// See the module docs for the race guarantees. Selection happens in the
+/// serve loop (one reader call); this function only classifies, writes the
+/// summary pages conditionally, and stamps the ends in one writer command.
+///
+/// # Errors
+/// Propagates store or wiki errors (a failed read/write leaves the affected
+/// sessions open for the next tick); per-session races are reported in
+/// [`IdleEndTickOutcome`], not as errors.
+pub async fn run_idle_end_tick(input: &IdleEndTickInput<'_>) -> anyhow::Result<IdleEndTickOutcome> {
+ let mut outcome = IdleEndTickOutcome::default();
+ if input.sessions.is_empty() {
+ return Ok(outcome);
+ }
+ // A live managed run owns its native session's lifecycle (its end comes
+ // from the run's own completion), so its sessions are never idle-ended
+ // even when the session row looks quiet. The join is done in Rust —
+ // `managed_runs.native_session_id` holds the harness's native id string
+ // while `sessions.id` is the derived UUID — via the one shared rule,
+ // `SessionId::from_native`.
+ let active_runs: HashSet<SessionId> = input
+ .reader
+ .active_managed_run_native_session_ids()
+ .await?
+ .iter()
+ .map(|raw| SessionId::from_native(raw))
+ .collect();
+ let enqueue_consolidation = input.consolidate_on_session_end && input.has_consolidator;
+
+ // Exclude active-run sessions BEFORE consuming the batch bound: the
+ // caller over-fetched the selection past the excluded ones, so a
+ // backlog of persistently excluded sessions cannot starve the eligible
+ // ones behind them.
+ let eligible: Vec<&ai_memory_store::IdleOpenSession> = input
+ .sessions
+ .iter()
+ .filter(|session| {
+ if active_runs.contains(&session.session_id) {
+ outcome.skipped += 1;
+ debug!(
+ session = %session.session_id,
+ "idle end: session is bound to an active managed run; leaving it to the run's own lifecycle"
+ );
+ false
+ } else {
+ true
+ }
+ })
+ .take(IDLE_END_BATCH)
+ .collect();
+
+ let mut candidates = Vec::new();
+ for session in eligible {
+ let substantive = input
+ .reader
+ .session_has_substantive_observation(
+ session.workspace_id,
+ session.project_id,
+ session.session_id,
+ )
+ .await?;
+ if !substantive {
+ candidates.push(IdleEndCandidate {
+ session_id: session.session_id,
+ workspace_id: session.workspace_id,
+ project_id: session.project_id,
+ agent_kind: session.agent_kind,
+ action: IdleEndAction::LifecycleOnly {
+ now_us: input.now_us,
+ last_activity_us: session.last_activity_us,
+ },
+ });
+ continue;
+ }
+ let (page, observation_count) = match summary_page_decision(input, session).await {
+ Ok((PageDecision::Written(page_id), count)) => {
+ outcome.pages_written += 1;
+ (page_id, count)
+ }
+ Ok((PageDecision::KeptAgentPage(page_id), count)) => (page_id, count),
+ Ok((PageDecision::Superseded, _)) => {
+ outcome.skipped += 1;
+ continue;
+ }
+ Err(error) => {
+ warn!(
+ session = %session.session_id,
+ error = %error,
+ "idle end: summary page failed; session stays open for the next tick"
+ );
+ outcome.skipped += 1;
+ continue;
+ }
+ };
+ candidates.push(IdleEndCandidate {
+ session_id: session.session_id,
+ workspace_id: session.workspace_id,
+ project_id: session.project_id,
+ agent_kind: session.agent_kind,
+ action: IdleEndAction::Substantive {
+ expected_page_id: page,
+ observation_count,
+ now_us: input.now_us,
+ last_activity_us: session.last_activity_us,
+ },
+ });
+ }
+ if candidates.is_empty() {
+ return Ok(outcome);
+ }
+ // One writer command for the whole batch: each candidate is stamped by
+ // its own guarded write (a real SessionEnd winning the race reports
+ // Lost, never an error), and each substantive end enqueues its
+ // consolidation job inside the same command.
+ let session_ids: Vec<SessionId> = candidates.iter().map(|c| c.session_id).collect();
+ let results = input
+ .writer
+ .end_idle_sessions(candidates, enqueue_consolidation)
+ .await?;
+ for (session_id, result) in session_ids.into_iter().zip(results) {
+ match result {
+ IdleEndResult::EndedSubstantive => outcome.ended += 1,
+ IdleEndResult::EndedLifecycleOnly => outcome.lifecycle_only += 1,
+ IdleEndResult::Lost => {
+ outcome.skipped += 1;
+ debug!(
+ session = %session_id,
+ "idle end: a real SessionEnd won the race; the hook's end owns the session"
+ );
+ }
+ }
+ }
+ // Auto-commit the wiki tree so the session page changes land in git in
+ // one snapshot, the same way the SessionEnd path does.
+ if outcome.pages_written > 0 {
+ match input.wiki.commit_all(&format!(
+ "idle session end: {} session(s)",
+ outcome.pages_written
+ )) {
+ Ok(Some(oid)) => debug!(commit = %oid, "idle session end auto-commit"),
+ Ok(None) => debug!("wiki clean after idle session end"),
+ Err(e) => warn!(error = %e, "idle session end auto-commit failed"),
+ }
+ }
+ if outcome.ended + outcome.lifecycle_only > 0 {
+ info!(
+ ended = outcome.ended,
+ lifecycle_only = outcome.lifecycle_only,
+ skipped = outcome.skipped,
+ pages_written = outcome.pages_written,
+ "idle session auto-end tick"
+ );
+ }
+ Ok(outcome)
+}
+
+/// Write — or keep — one substantive session's summary page exactly the way
+/// the `SessionEnd` path does, but conditional on the page version the
+/// selection saw, so a real `SessionEnd` that delivered its page after the
+/// selection is never superseded by the rule-based summary.
+async fn summary_page_decision(
+ input: &IdleEndTickInput<'_>,
+ session: &ai_memory_store::IdleOpenSession,
+) -> anyhow::Result<(PageDecision, i64)> {
+ // The agent's own page wins over the rule-based summary, the same rule
+ // the SessionEnd path applies at its end: when the agent wrote
+ // `sessions/<id>.md` itself, the automatic writer keeps it. Its current
+ // version is read now (keeping means not writing, so a late write
+ // cannot be superseded); a missing row falls through to the
+ // rule-based summary, as the SessionEnd path does.
+ let agent_page_current = if input.wiki.session_page_written_by_agent(
+ session.workspace_id,
+ session.project_id,
+ session.session_id,
+ )? {
+ input
+ .reader
+ .latest_page_id_by_ids(
+ session.workspace_id,
+ session.project_id,
+ session_page_path(session.session_id),
+ )
+ .await?
+ } else {
+ None
+ };
+ if let Some(page_id) = agent_page_current {
+ debug!(
+ session = %session.session_id,
+ "idle end: keeping the agent's own session page over the rule-based summary"
+ );
+ // The kept page is not tied to a digest generation, but the stamp's
+ // count guard still needs a count read at decision time: a non-end
+ // observation landing after this read loses the CAS (the session
+ // retries on the next tick) instead of silently widening the
+ // watermark.
+ let observation_count = input
+ .reader
+ .session_observation_count(session.workspace_id, session.project_id, session.session_id)
+ .await?;
+ return Ok((PageDecision::KeptAgentPage(page_id), observation_count));
+ }
+ // Read after the decision above, so anything captured in between is in
+ // it — the same order the SessionEnd path uses. The count the digest is
+ // built from is read in the SAME snapshot, so the stamp's count guard
+ // (the window between this read and the stamp) is checked against
+ // exactly what the page represents.
+ let (digest, observation_count) = SessionDigest::load_with_count(
+ input.reader,
+ session.workspace_id,
+ session.project_id,
+ session.session_id,
+ )
+ .await?;
+ let page = synthesize_session_page(
+ session.workspace_id,
+ session.project_id,
+ session.session_id,
+ session.agent_kind,
+ &digest,
+ );
+ // Attribute the write to the operator who OWNED the session, read back
+ // from the session row — the server process is the writer, not the
+ // author.
+ let actor = stored_session_identity(session.actor_user.clone())?.1;
+ // The precondition is the version the tick SAW WHEN IT READ THE
+ // SESSION (the selection), captured before any write in this tick: a
+ // real SessionEnd that lands the page after the selection changes the
+ // latest version and this write must back off.
+ let precondition = match session.seen_page_id {
+ Some(seen) => PagePrecondition::Latest(seen),
+ None => PagePrecondition::Absent,
+ };
+ match input
+ .wiki
+ .write_page_if(
+ WritePageRequest {
+ workspace_id: page.workspace_id,
+ project_id: page.project_id,
+ path: page.path.clone(),
+ frontmatter: page.frontmatter_json.clone(),
+ body: page.body.clone(),
+ tier: page.tier,
+ pinned: page.pinned,
+ title: None,
+ admission_ctx: None,
+ author_id: None,
+ actor,
+ evidence: Vec::new(),
+ },
+ precondition,
+ )
+ .await
+ {
+ Ok(ConditionalWrite::Written(page_id)) => {
+ Ok((PageDecision::Written(page_id), observation_count))
+ }
+ Ok(ConditionalWrite::Mismatch { current }) => {
+ debug!(
+ session = %session.session_id,
+ current = ?current,
+ "idle end: the session page moved after the selection; skipping the session"
+ );
+ Ok((PageDecision::Superseded, observation_count))
+ }
+ Err(error) => Err(error.into()),
+ }
+}
+
+/// The session page path, the same `sessions/<id>.md` rule the rest of the
+/// automatic writers use.
+fn session_page_path(session_id: SessionId) -> String {
+ format!("sessions/{session_id}.md")
+}
diff --git a/crates/ai-memory-hooks/src/lib.rs b/crates/ai-memory-hooks/src/lib.rs
index 6d6dffd6..4bd385f8 100644
--- a/crates/ai-memory-hooks/src/lib.rs
+++ b/crates/ai-memory-hooks/src/lib.rs
@@ -27,6 +27,7 @@ mod brief_tiers;
pub mod capture_policy;
pub mod drop_list;
mod grants;
+pub mod idle_end;
pub mod log;
pub mod payload;
mod recap;
@@ -54,6 +55,9 @@ pub use capture_policy::{
glob_segment_matches, glob_walk, repository_admits_capture, tool_call_payload, valid_call_id,
};
pub use drop_list::IngestDropList;
+pub use idle_end::{
+ IDLE_END_BATCH, IDLE_END_INTERVAL_SECS, IdleEndTickInput, IdleEndTickOutcome, run_idle_end_tick,
+};
pub use payload::{
HookEnvelope, HookEvent, NOTIFICATION_EXCERPT_MAX_BYTES, POST_COMPACTION_EXCERPT_MAX_BYTES,
USER_PROMPT_EXCERPT_MAX_BYTES, agent_from_payload, cap_lifecycle_body_for_client,
diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rs
index fd834892..197fe1ec 100644
--- a/crates/ai-memory-hooks/src/router.rs
+++ b/crates/ai-memory-hooks/src/router.rs
@@ -4100,11 +4100,8 @@ async fn process_authorized(
// and current actorless sessions use the same value; attributing either to
// whoever delivers SessionEnd would silently rebucket shared context. A
// store failure aborts this event rather than guessing an owner.
- let session_owner = parse_session_owner(admitted.owner().map(str::to_owned))?;
- let session_actor = session_owner
- .as_ref()
- .map(IdentityKey::to_actor_context)
- .unwrap_or_default();
+ let (session_owner, session_actor) =
+ stored_session_identity(admitted.owner().map(str::to_owned))?;
// A redelivery of a checkpoint whose LLM rewrite already ran (or is
// running) must not put the rule-based page back over it: the enqueue of
// that same generation would be ignored, so the LLM page would be lost.
@@ -4244,37 +4241,43 @@ async fn process_authorized(
} else {
None
};
- let page_id =
- match agent_session_page_id(state, page_ws, page_proj, session_id, &new_page.path)
- .await?
- {
- Some(page_id) => page_id,
- None => {
- state
- .wiki
- .write_page(ai_memory_wiki::WritePageRequest {
- workspace_id: new_page.workspace_id,
- project_id: new_page.project_id,
- path: new_page.path.clone(),
- frontmatter: new_page.frontmatter_json.clone(),
- body: new_page.body.clone(),
- tier: new_page.tier,
- pinned: new_page.pinned,
- title: None,
- admission_ctx: None,
- author_id: None,
- // Attribute to the operator who OWNED the session, read back
- // from the session row, not to whoever delivered this
- // SessionEnd — a spool drain, an operator finalizing a stuck
- // session, or a shared hook token can all carry a different
- // identity. NULL stays anonymous/shared, including rows that
- // predate owner recording.
- actor: session_actor.clone(),
- evidence: Vec::new(),
- })
- .await?
- }
- };
+ let page_id = match agent_session_page_id(
+ &state.wiki,
+ &state.reader,
+ page_ws,
+ page_proj,
+ session_id,
+ &new_page.path,
+ )
+ .await?
+ {
+ Some(page_id) => page_id,
+ None => {
+ state
+ .wiki
+ .write_page(ai_memory_wiki::WritePageRequest {
+ workspace_id: new_page.workspace_id,
+ project_id: new_page.project_id,
+ path: new_page.path.clone(),
+ frontmatter: new_page.frontmatter_json.clone(),
+ body: new_page.body.clone(),
+ tier: new_page.tier,
+ pinned: new_page.pinned,
+ title: None,
+ admission_ctx: None,
+ author_id: None,
+ // Attribute to the operator who OWNED the session, read back
+ // from the session row, not to whoever delivered this
+ // SessionEnd — a spool drain, an operator finalizing a stuck
+ // session, or a shared hook token can all carry a different
+ // identity. NULL stays anonymous/shared, including rows that
+ // predate owner recording.
+ actor: session_actor.clone(),
+ evidence: Vec::new(),
+ })
+ .await?
+ }
+ };
if track_page_write && previous_page_id != Some(page_id) {
state.ingest_metrics.record_persisted(now_unix_ms());
}
@@ -4471,6 +4474,23 @@ fn parse_session_owner(owner: Option<String>) -> anyhow::Result<Option<IdentityK
.transpose()
}
+/// The session's persisted owner as both its parsed identity and the actor
+/// context every write on the session's behalf is attributed to — the
+/// `SessionEnd` path and the idle auto-end tick share this one parse so the
+/// two cannot drift. Only SQL NULL has the intentional legacy/shared meaning
+/// (and maps to the default shared actor); a malformed owned key fails
+/// closed rather than silently rebucketing the session's context to shared.
+pub(crate) fn stored_session_identity(
+ stored_owner: Option<String>,
+) -> anyhow::Result<(Option<IdentityKey>, ai_memory_core::ActorContext)> {
+ let owner = parse_session_owner(stored_owner)?;
+ let actor = owner
+ .as_ref()
+ .map(IdentityKey::to_actor_context)
+ .unwrap_or_default();
+ Ok((owner, actor))
+}
+
fn resolve_session_id(env: &HookEnvelope) -> anyhow::Result<SessionId> {
if let Some(raw) = &env.session_id {
return Ok(SessionId::from_native(raw));
@@ -4793,9 +4813,16 @@ async fn write_checkpoint_page(
// SessionEnd: the checkpoint would replace it with the server's model or
// the rule-based summary.
let path = PagePath::new(format!("sessions/{session_id}.md"))?;
- if agent_session_page_id(state, workspace_id, project_id, session_id, &path)
- .await?
- .is_some()
+ if agent_session_page_id(
+ &state.wiki,
+ &state.reader,
+ workspace_id,
+ project_id,
+ session_id,
+ &path,
+ )
+ .await?
+ .is_some()
{
return Ok(false);
}
@@ -4856,17 +4883,15 @@ async fn write_checkpoint_page(
/// tool call, the Stop and the SessionEnd always land after that write, so
/// no observation count separates a current page from a stale one. A page
/// that cannot be read is replaced as before, with a warning.
-async fn agent_session_page_id(
- state: &HookState,
+pub(crate) async fn agent_session_page_id(
+ wiki: &Wiki,
+ reader: &ai_memory_store::ReaderPool,
workspace_id: WorkspaceId,
project_id: ProjectId,
session_id: SessionId,
path: &PagePath,
) -> anyhow::Result<Option<PageId>> {
- match state
- .wiki
- .session_page_written_by_agent(workspace_id, project_id, session_id)
- {
+ match wiki.session_page_written_by_agent(workspace_id, project_id, session_id) {
Ok(true) => {}
Ok(false) => return Ok(None),
Err(error) => {
@@ -4878,8 +4903,7 @@ async fn agent_session_page_id(
return Ok(None);
}
}
- let page_id = state
- .reader
+ let page_id = reader
.latest_page_id_by_ids(workspace_id, project_id, path.as_str().to_owned())
.await?;
if page_id.is_some() {
diff --git a/crates/ai-memory-hooks/src/synth.rs b/crates/ai-memory-hooks/src/synth.rs
index 75f62750..a2ac8cf1 100644
--- a/crates/ai-memory-hooks/src/synth.rs
+++ b/crates/ai-memory-hooks/src/synth.rs
@@ -197,6 +197,33 @@ impl SessionDigest {
)
}
+ /// [`Self::load`], also returning the session's observation count from
+ /// the SAME read snapshot the digest was built from.
+ ///
+ /// The idle auto-end tick binds that count to the end stamp (review R36
+ /// F3): an observation landing after the digest was built must invalidate
+ /// the stamp instead of reaching the watermark without reaching the page.
+ ///
+ /// # Errors
+ /// Propagates any store error.
+ pub(crate) async fn load_with_count(
+ reader: &ReaderPool,
+ workspace_id: WorkspaceId,
+ project_id: ProjectId,
+ session_id: SessionId,
+ ) -> StoreResult<(Self, i64)> {
+ reader
+ .read_session_observations(workspace_id, project_id, session_id, move |snapshot| {
+ let (digest, _stats) = build_digest(snapshot, session_id)?;
+ // Overflow only with more than 9.2e18 observations: fail
+ // toward `Lost` at the stamp (an unrepresentable count never
+ // matches the stamp-time COUNT), never toward a wrong stamp.
+ let total = i64::try_from(snapshot.kind_summary()?.total).unwrap_or(i64::MAX);
+ Ok((digest, total))
+ })
+ .await
+ }
+
/// [`Self::load`], also reporting what the load read.
///
/// # Errors
@@ -1664,3 +1691,114 @@ mod tests {
);
}
}
+
+#[cfg(test)]
+mod load_with_count_scopes {
+ use ai_memory_core::{
+ AgentKind, NewObservation, NewSession, ObservationKind, Sanitized, Sanitizer,
+ };
+ use ai_memory_store::Store;
+
+ use super::*;
+
+ /// The new raw-id entry point must refuse foreign tuples the way the
+ /// bounded read refuses them: the idle tick's digest can never load a
+ /// session's observations through a scope the session does not belong
+ /// to. Each refusal is paired with the legitimate control in the same
+ /// fixture.
+ #[tokio::test]
+ async fn foreign_and_missing_tuples_load_nothing_the_right_tuple_loads() {
+ let tmp = tempfile::tempdir().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let ws = store
+ .writer
+ .get_or_create_workspace("default".to_string())
+ .await
+ .unwrap();
+ let proj = store
+ .writer
+ .get_or_create_project(ws, "idle", None)
+ .await
+ .unwrap();
+ let other = store
+ .writer
+ .get_or_create_project(ws, "other", None)
+ .await
+ .unwrap();
+ let foreign_ws = store
+ .writer
+ .get_or_create_workspace("foreign".to_string())
+ .await
+ .unwrap();
+ let sid = SessionId::new();
+ store
+ .writer
+ .begin_session(NewSession {
+ id: sid,
+ workspace_id: ws,
+ project_id: proj,
+ agent_kind: AgentKind::Codex,
+ cwd: None,
+ actor_user: None,
+ occurred_at: None,
+ })
+ .await
+ .unwrap();
+ async fn insert_obs(
+ store: &Store,
+ sid: SessionId,
+ ws: WorkspaceId,
+ proj: ProjectId,
+ kind: ObservationKind,
+ body: &str,
+ ) {
+ let obs = NewObservation {
+ session_id: sid,
+ workspace_id: ws,
+ project_id: proj,
+ kind,
+ extension: None,
+ source_event: None,
+ title: "scoped test event".into(),
+ body: body.into(),
+ importance: 5,
+ occurred_at: None,
+ };
+ store
+ .writer
+ .insert_observation(Sanitized::new(obs, &Sanitizer::builtin()))
+ .await
+ .unwrap();
+ }
+ insert_obs(&store, sid, ws, proj, ObservationKind::UserPrompt, "prompt").await;
+ insert_obs(&store, sid, ws, proj, ObservationKind::PostToolUse, "tool").await;
+ let reader = store.reader.clone();
+
+ // Violations: a foreign project, a foreign workspace, a missing id —
+ // each is refused, so none of them can load the session's rows.
+ let foreign_project = SessionDigest::load_with_count(&reader, ws, other, sid).await;
+ assert!(
+ matches!(foreign_project, Err(StoreError::SessionCollision)),
+ "a foreign project loads no observations"
+ );
+ let foreign_workspace =
+ SessionDigest::load_with_count(&reader, foreign_ws, proj, sid).await;
+ assert!(
+ matches!(foreign_workspace, Err(StoreError::SessionCollision)),
+ "a foreign workspace loads no observations"
+ );
+ let missing = SessionDigest::load_with_count(&reader, ws, proj, SessionId::new()).await;
+ assert!(
+ matches!(missing, Err(StoreError::SessionCollision)),
+ "a missing id loads nothing"
+ );
+
+ // Legitimate control: the right tuple loads the session's rows and
+ // counts them from the same snapshot.
+ let (digest, count) = SessionDigest::load_with_count(&reader, ws, proj, sid)
+ .await
+ .unwrap();
+ assert_eq!(count, 2, "the digest's snapshot counts both rows");
+ assert_eq!(digest.total, 2);
+ }
+}
diff --git a/crates/ai-memory-hooks/tests/suite/idle_end.rs b/crates/ai-memory-hooks/tests/suite/idle_end.rs
new file mode 100644
index 00000000..84cff603
--- /dev/null
+++ b/crates/ai-memory-hooks/tests/suite/idle_end.rs
@@ -0,0 +1,936 @@
+//! Server-side idle auto-end, tick level: what one `run_idle_end_tick` pass
+//! does on top of the store's guarded batch. The store-level guarantees
+//! (CAS guard, watermark math, cross-scope refusal) live in
+//! `ai-memory-store::tests::idle_session_end`; here the tick's own decisions
+//! are exercised: substantive vs lifecycle-only classification, the
+//! conditional page write that never supersedes a real SessionEnd,
+//! agent-page retention, managed-run exclusion, the batch bound, and the
+//! convergence of a late real SessionEnd (via the real `/hook` route).
+//!
+//! Coverage matrix: M5 (attribution to the session owner), M6 (late real
+//! SessionEnd converges, no double handoff), M9 (no overwrite of a
+//! concurrently ended session), invariant #16 (pages shared / batons owned —
+//! the idle end never creates a handoff and never filters the page).
+
+use std::future::Future;
+use std::pin::Pin;
+use std::sync::Arc;
+use std::time::Duration;
+
+use ai_memory_core::{
+ ActorContext, AgentKind, IdentityKey, IngestMetrics, NewObservation, NewSession,
+ ObservationKind, PagePath, ProjectId, Sanitized, Sanitizer, SessionId, Tier, WorkspaceId,
+};
+use ai_memory_store::{SessionEndDisposition, Store, WorkstreamSelection};
+use ai_memory_wiki::Wiki;
+use axum::body::Body;
+use axum::http::{Request, StatusCode};
+use tempfile::TempDir;
+use tower::ServiceExt;
+
+use crate::idle_end::{IDLE_END_BATCH, IdleEndTickInput, run_idle_end_tick};
+use crate::router::{
+ DEFAULT_HOOK_INGEST_MAX_IN_FLIGHT, HookState, IngestGates, IngestRateLimiter,
+ ProjectCacheStore, SubagentSessionSet, hook_router,
+};
+
+const WORKSPACE: &str = "default";
+const PROJECT: &str = "idle";
+const CWD: &str = "/repo";
+
+/// One hour in microseconds.
+const HOUR_US: i64 = 3_600_000_000;
+
+async fn harness() -> (TempDir, Store, Wiki, HookState) {
+ let tmp = TempDir::new().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let ws = store
+ .writer
+ .get_or_create_workspace(WORKSPACE)
+ .await
+ .unwrap();
+ let proj = store
+ .writer
+ .get_or_create_project(ws, PROJECT, None)
+ .await
+ .unwrap();
+ let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();
+ let state = HookState {
+ ingest_metrics: Arc::new(IngestMetrics::default()),
+ workspace_id: ws,
+ project_id: proj,
+ writer: store.writer.clone(),
+ reader: store.reader.clone(),
+ wiki: wiki.clone(),
+ consolidator: None,
+ sanitizer: Sanitizer::default(),
+ project_cache: Arc::new(tokio::sync::Mutex::new(ProjectCacheStore::default())),
+ active_project: ai_memory_core::ActiveProject::new(),
+ consolidate_on_session_end: true,
+ session_consolidation_notify: None,
+ profile_notify: None,
+ capture_assistant_enabled: false,
+ claim_handoff_on_session_start: true,
+ create_handoff_on_session_end: true,
+ subagent_sessions: Arc::new(tokio::sync::Mutex::new(SubagentSessionSet::default())),
+ ingest_rate: Arc::new(tokio::sync::Mutex::new(IngestRateLimiter::disabled())),
+ home_dir: None,
+ trusted_proxy_identity: false,
+ ingest_semaphore: Arc::new(tokio::sync::Semaphore::new(
+ DEFAULT_HOOK_INGEST_MAX_IN_FLIGHT,
+ )),
+ ingest_gates: IngestGates::default(),
+ per_user_slots: false,
+ mid_session_routing: ai_memory_core::MidSessionRouting::default(),
+ profile: ai_memory_core::profile::ProfileSettings::default(),
+ ingest_drop_list: crate::drop_list::IngestDropList::default(),
+ };
+ (tmp, store, wiki, state)
+}
+
+fn now_us() -> i64 {
+ std::time::SystemTime::now()
+ .duration_since(std::time::UNIX_EPOCH)
+ .unwrap()
+ .as_micros() as i64
+}
+
+fn owner(user: &str) -> String {
+ IdentityKey::User(user.to_string()).storage_key()
+}
+
+/// Begin a session, back-dated to `at` (and optionally owned by `owner`).
+async fn begin(
+ store: &Store,
+ ws: WorkspaceId,
+ proj: ProjectId,
+ at: i64,
+ actor_user: Option<String>,
+) -> SessionId {
+ let sid = SessionId::new();
+ store
+ .writer
+ .begin_session(NewSession {
+ id: sid,
+ workspace_id: ws,
+ project_id: proj,
+ agent_kind: AgentKind::Codex,
+ cwd: Some(CWD.into()),
+ actor_user,
+ occurred_at: Some(at),
+ })
+ .await
+ .unwrap();
+ sid
+}
+
+async fn observe(state: &HookState, sid: SessionId, kind: ObservationKind, at: i64, body: &str) {
+ state
+ .writer
+ .insert_observation(Sanitized::new(
+ NewObservation {
+ session_id: sid,
+ workspace_id: state.workspace_id,
+ project_id: state.project_id,
+ kind,
+ extension: None,
+ source_event: None,
+ title: "idle tick test event".into(),
+ body: body.into(),
+ importance: 5,
+ occurred_at: Some(at),
+ },
+ &state.sanitizer,
+ ))
+ .await
+ .unwrap();
+}
+
+async fn disposition(
+ store: &Store,
+ ws: WorkspaceId,
+ proj: ProjectId,
+ sid: SessionId,
+) -> SessionEndDisposition {
+ store
+ .reader
+ .session_end_disposition(sid, ws, proj, AgentKind::Codex)
+ .await
+ .unwrap()
+}
+
+/// The page path the tick and the hook share for one session.
+fn page_path(sid: SessionId) -> String {
+ format!("sessions/{}.md", sid.to_string().to_lowercase())
+}
+
+async fn page_total(
+ reader: &ai_memory_store::ReaderPool,
+ ws: WorkspaceId,
+ proj: ProjectId,
+ sid: SessionId,
+) -> u64 {
+ reader
+ .page_versions(ws, proj, page_path(sid), 10, 0)
+ .await
+ .unwrap()
+ .total
+}
+
+async fn open_handoffs(store: &Store, ws: WorkspaceId, proj: ProjectId) -> usize {
+ store
+ .reader
+ .open_handoffs_for_project(ws, proj, 100)
+ .await
+ .unwrap()
+ .len()
+}
+
+async fn idle_end_audit(store: &Store) -> Vec<ai_memory_store::AuditEvent> {
+ store
+ .reader
+ .list_audit_events(ai_memory_store::AuditLogFilter {
+ workspace: Some(WORKSPACE.to_string()),
+ project: Some(PROJECT.to_string()),
+ op: Some("idle_session_end".to_string()),
+ before_id: None,
+ limit: 5,
+ })
+ .await
+ .unwrap()
+}
+
+/// POST a real `/hook` SessionEnd for `sid`, the same shape a lifecycle
+/// hook sends. Returns the HTTP status of the acceptance.
+async fn post_session_end(state: &HookState, sid: SessionId) -> StatusCode {
+ let app = hook_router(state.clone());
+ let body = serde_json::json!({
+ "event": "session-end",
+ "session_id": sid.to_string(),
+ });
+ let req = Request::builder()
+ .method("POST")
+ .uri(format!(
+ "/hook?event=session-end&agent=codex&cwd={CWD}&workspace={WORKSPACE}&project={PROJECT}"
+ ))
+ .header("content-type", "application/json")
+ .body(Body::from(serde_json::to_vec(&body).unwrap()))
+ .unwrap();
+ app.oneshot(req).await.unwrap().status()
+}
+
+/// Poll an async condition (bounded) until it holds; returns whether it did.
+///
+/// The hook route returns 202 as soon as the effect task is SPAWNED (the
+/// hook path is fire-and-forget: no completion barrier is offered), so a
+/// test that must observe the effect's store state has no deterministic
+/// hand-off point to wait on. Bounded polling against a monotone condition
+/// (a row appears / a count settles) is the faithful substitute; a sleep
+/// before the assertion would be a race fudge, this is not.
+async fn until<'a, F>(mut cond: F) -> bool
+where
+ F: FnMut() -> Pin<Box<dyn Future<Output = bool> + Send + 'a>>,
+{
+ for _ in 0..200 {
+ if cond().await {
+ return true;
+ }
+ tokio::time::sleep(Duration::from_millis(20)).await;
+ }
+ cond().await
+}
+
+#[tokio::test]
+async fn idle_tick_ends_idle_substantive_session_with_page_job_and_no_handoff() {
+ let (_tmp, store, wiki, state) = harness().await;
+ let ws = state.workspace_id;
+ let proj = state.project_id;
+ let now = now_us();
+ // Owned by operator "alice": last activity five hours ago.
+ let sid = begin(&store, ws, proj, now - 5 * HOUR_US, Some(owner("alice"))).await;
+ observe(
+ &state,
+ sid,
+ ObservationKind::UserPrompt,
+ now - 5 * HOUR_US,
+ "frobnicate the idle watermark sentinel",
+ )
+ .await;
+
+ // Selection, exactly as `serve` does: idle cutoff two hours.
+ let sessions = store
+ .reader
+ .idle_open_sessions(now - 2 * HOUR_US, IDLE_END_BATCH)
+ .await
+ .unwrap();
+ assert_eq!(sessions.len(), 1);
+ assert_eq!(sessions[0].session_id, sid);
+ assert_eq!(
+ sessions[0].actor_user.as_deref(),
+ Some(owner("alice").as_str())
+ );
+
+ let outcome = run_idle_end_tick(&IdleEndTickInput {
+ writer: &store.writer,
+ reader: &store.reader,
+ wiki: &wiki,
+ sessions,
+ now_us: jiff::Timestamp::now().as_microsecond(),
+ consolidate_on_session_end: true,
+ has_consolidator: true,
+ })
+ .await
+ .unwrap();
+ assert_eq!(
+ (
+ outcome.ended,
+ outcome.lifecycle_only,
+ outcome.skipped,
+ outcome.pages_written
+ ),
+ (1, 0, 0, 1)
+ );
+
+ // The session is ended, watermark = last activity, audited with a page.
+ assert!(matches!(
+ disposition(&store, ws, proj, sid).await,
+ SessionEndDisposition::AlreadyEnded
+ ));
+ let audit = idle_end_audit(&store).await;
+ assert_eq!(audit.len(), 1);
+ assert!(
+ audit[0].at >= now && audit[0].at < now + HOUR_US,
+ "ended_at is the tick's clock (the discovery is ordered by ended_at), not the last activity: {}",
+ audit[0].at
+ );
+ assert!(
+ audit[0].detail.contains(&(now - 5 * HOUR_US).to_string()),
+ "the last activity survives in the audit detail: {}",
+ audit[0].detail
+ );
+ assert_eq!(audit[0].page_path.as_deref(), Some(page_path(sid).as_str()));
+
+ // Page exists and is attributed to the session owner (M5): the frontmatter
+ // carries the owner's username, not the anonymous server identity.
+ let path = PagePath::new(page_path(sid)).unwrap();
+ let doc = wiki.read_page(ws, proj, &path).unwrap();
+ assert_eq!(
+ doc.frontmatter["last_modified_by"]["username"], "alice",
+ "page must carry the session owner, got: {}",
+ doc.frontmatter
+ );
+ // Invariant #16: pages are shared — a second operator reads the page the
+ // operator's harness left idle-ended, with the owner's attribution intact
+ // (`author_id` never becomes a read filter).
+ use ai_memory_core::{NewUser, UserRole};
+ let bob = store
+ .writer
+ .create_human_user(
+ NewUser {
+ username: "bob".into(),
+ name: None,
+ email: None,
+ },
+ UserRole::User,
+ None,
+ false,
+ )
+ .await
+ .unwrap();
+ let hits = store
+ .reader
+ .search_pages("frobnicate sentinel idle".to_string(), 5, Some(bob))
+ .await
+ .unwrap();
+ assert!(
+ hits.iter().any(|h| h.path.to_string() == page_path(sid)),
+ "a second operator must read the owner's idle-ended page; hits: {:?}",
+ hits.iter().map(|h| h.path.to_string()).collect::<Vec<_>>()
+ );
+
+ // Consolidation job enqueued (claim with a fresh clock: the enqueue's
+ // `requested_at` is the tick's wall time, after this test's `now`).
+ let now_after = now_us();
+ let job = store
+ .writer
+ .claim_session_consolidation(now_after + 1_000, now_after - 1_000)
+ .await
+ .unwrap();
+ assert_eq!(job.map(|j| j.session_id()), Some(sid));
+
+ // No handoff: the idle end is never a baton hand-off.
+ assert_eq!(open_handoffs(&store, ws, proj).await, 0);
+
+ // A second tick sees nothing: the ended session is outside the scan.
+ let again = store
+ .reader
+ .idle_open_sessions(now - 2 * HOUR_US, IDLE_END_BATCH)
+ .await
+ .unwrap();
+ assert!(again.is_empty());
+}
+
+#[tokio::test]
+async fn idle_tick_lifecycle_only_ends_without_page_or_job_and_creates_no_handoff() {
+ let (_tmp, store, _wiki, state) = harness().await;
+ let ws = state.workspace_id;
+ let proj = state.project_id;
+ let now = now_us();
+ // Session whose only content is a Stop (no substantive observation).
+ let sid = begin(&store, ws, proj, now - 4 * HOUR_US, None).await;
+ observe(
+ &state,
+ sid,
+ ObservationKind::Stop,
+ now - 4 * HOUR_US,
+ "done",
+ )
+ .await;
+
+ let sessions = store
+ .reader
+ .idle_open_sessions(now - 2 * HOUR_US, IDLE_END_BATCH)
+ .await
+ .unwrap();
+ assert_eq!(sessions.len(), 1);
+
+ let outcome = run_idle_end_tick(&IdleEndTickInput {
+ writer: &store.writer,
+ reader: &store.reader,
+ wiki: &state.wiki,
+ sessions,
+ now_us: jiff::Timestamp::now().as_microsecond(),
+ consolidate_on_session_end: true,
+ has_consolidator: true,
+ })
+ .await
+ .unwrap();
+ assert_eq!(
+ (
+ outcome.ended,
+ outcome.lifecycle_only,
+ outcome.skipped,
+ outcome.pages_written
+ ),
+ (0, 1, 0, 0)
+ );
+
+ assert!(matches!(
+ disposition(&store, ws, proj, sid).await,
+ SessionEndDisposition::AlreadyEnded
+ ));
+ assert!(
+ store
+ .reader
+ .latest_page_id_by_ids(ws, proj, page_path(sid))
+ .await
+ .unwrap()
+ .is_none()
+ );
+ assert!(
+ store
+ .writer
+ .claim_session_consolidation(now + 1_000, now - 1_000)
+ .await
+ .unwrap()
+ .is_none()
+ );
+ assert_eq!(open_handoffs(&store, ws, proj).await, 0);
+}
+
+#[tokio::test]
+async fn idle_tick_skips_active_sessions_and_respects_the_batch() {
+ let (_tmp, store, wiki, state) = harness().await;
+ let ws = state.workspace_id;
+ let proj = state.project_id;
+ let now = now_us();
+
+ // 27 idle sessions (oldest first) plus one active session.
+ for i in 0..27 {
+ // 5h..5h13m ago — all well past the one-hour cutoff.
+ let at = now - (5 * 3600 + i * 30) * 1_000_000;
+ let sid = begin(&store, ws, proj, at, None).await;
+ observe(&state, sid, ObservationKind::UserPrompt, at, "prompt").await;
+ }
+ let active = begin(&store, ws, proj, now - 10 * 60 * 1_000_000, None).await;
+ observe(
+ &state,
+ active,
+ ObservationKind::UserPrompt,
+ now - 10 * 60 * 1_000_000,
+ "still working",
+ )
+ .await;
+
+ let tick = |sessions: Vec<_>| {
+ let (store, wiki) = (&store, &wiki);
+ async move {
+ run_idle_end_tick(&IdleEndTickInput {
+ writer: &store.writer,
+ reader: &store.reader,
+ wiki,
+ sessions,
+ now_us: jiff::Timestamp::now().as_microsecond(),
+ consolidate_on_session_end: true,
+ has_consolidator: true,
+ })
+ .await
+ }
+ };
+
+ // Pass 1 ends exactly the batch bound — oldest first, never the active.
+ let selected = store
+ .reader
+ .idle_open_sessions(now - HOUR_US, IDLE_END_BATCH)
+ .await
+ .unwrap();
+ assert_eq!(selected.len(), IDLE_END_BATCH);
+ assert!(!selected.iter().any(|s| s.session_id == active));
+ let outcome = tick(selected).await.unwrap();
+ assert_eq!(outcome.ended, IDLE_END_BATCH);
+
+ // Pass 2 ends the two remaining idle sessions.
+ let selected = store
+ .reader
+ .idle_open_sessions(now - HOUR_US, IDLE_END_BATCH)
+ .await
+ .unwrap();
+ assert_eq!(selected.len(), 2);
+ let outcome = tick(selected).await.unwrap();
+ assert_eq!(outcome.ended, 2);
+
+ // Pass 3: only the active session remains — it is never selected.
+ let selected = store
+ .reader
+ .idle_open_sessions(now - HOUR_US, IDLE_END_BATCH)
+ .await
+ .unwrap();
+ assert!(selected.is_empty());
+ assert!(matches!(
+ disposition(&store, ws, proj, active).await,
+ SessionEndDisposition::Open
+ ));
+}
+
+#[tokio::test]
+async fn idle_tick_excludes_active_managed_run_sessions() {
+ let (_tmp, store, wiki, state) = harness().await;
+ let ws = state.workspace_id;
+ let proj = state.project_id;
+ let now = now_us();
+ // Idle on paper: last activity five hours ago…
+ let sid = begin(&store, ws, proj, now - 5 * HOUR_US, None).await;
+ observe(
+ &state,
+ sid,
+ ObservationKind::UserPrompt,
+ now - 5 * HOUR_US,
+ "old prompt",
+ )
+ .await;
+ // …but a managed run launched from it is still active.
+ let run = store
+ .writer
+ .prepare_workstream_run(ai_memory_store::PrepareWorkstreamRun {
+ workspace_id: ws,
+ project_id: proj,
+ repo_fingerprint: "repo".into(),
+ worktree_fingerprint: "worktree".into(),
+ cwd: CWD.into(),
+ agent: AgentKind::Codex,
+ automatic_harness: false,
+ available_agents: Vec::new(),
+ selection: WorkstreamSelection::Current,
+ lease_owner: "test:idle".into(),
+ })
+ .await
+ .unwrap();
+ store
+ .writer
+ .link_managed_run_session(run.run_id, AgentKind::Codex, sid.to_string())
+ .await
+ .unwrap();
+
+ let run_tick = |sessions| {
+ let (store, wiki) = (&store, &wiki);
+ async move {
+ run_idle_end_tick(&IdleEndTickInput {
+ writer: &store.writer,
+ reader: &store.reader,
+ wiki,
+ sessions,
+ now_us: jiff::Timestamp::now().as_microsecond(),
+ consolidate_on_session_end: true,
+ has_consolidator: true,
+ })
+ .await
+ }
+ };
+
+ let sessions = store
+ .reader
+ .idle_open_sessions(now - 2 * HOUR_US, IDLE_END_BATCH)
+ .await
+ .unwrap();
+ assert_eq!(sessions.len(), 1);
+ let outcome = run_tick(sessions).await.unwrap();
+ assert_eq!((outcome.ended, outcome.skipped), (0, 1));
+ assert!(matches!(
+ disposition(&store, ws, proj, sid).await,
+ SessionEndDisposition::Open
+ ));
+
+ // The run finishes: the next pass ends the session normally.
+ store.writer.cancel_managed_run(run.run_id).await.unwrap();
+ let sessions = store
+ .reader
+ .idle_open_sessions(now - 2 * HOUR_US, IDLE_END_BATCH)
+ .await
+ .unwrap();
+ assert_eq!(sessions.len(), 1);
+ let outcome = run_tick(sessions).await.unwrap();
+ assert_eq!((outcome.ended, outcome.skipped), (1, 0));
+ assert!(matches!(
+ disposition(&store, ws, proj, sid).await,
+ SessionEndDisposition::AlreadyEnded
+ ));
+}
+
+#[tokio::test]
+async fn idle_tick_excluded_backlog_cannot_starve_the_batch() {
+ let (_tmp, store, wiki, state) = harness().await;
+ let ws = state.workspace_id;
+ let proj = state.project_id;
+ let now = now_us();
+
+ // 25 idle sessions each bound to an active managed run (the excluded
+ // backlog, the OLDEST), plus one eligible session BEHIND them.
+ let mut excluded = Vec::new();
+ for i in 0..25u32 {
+ let at = now - (26 - i as i64) * HOUR_US;
+ let sid = begin(&store, ws, proj, at, None).await;
+ observe(
+ &state,
+ sid,
+ ObservationKind::UserPrompt,
+ at,
+ "backlog prompt",
+ )
+ .await;
+ let run = store
+ .writer
+ .prepare_workstream_run(ai_memory_store::PrepareWorkstreamRun {
+ workspace_id: ws,
+ project_id: proj,
+ repo_fingerprint: format!("repo-{i}"),
+ worktree_fingerprint: format!("worktree-{i}"),
+ cwd: CWD.into(),
+ agent: AgentKind::Codex,
+ automatic_harness: false,
+ available_agents: Vec::new(),
+ selection: WorkstreamSelection::Current,
+ lease_owner: format!("test:idle-backlog-{i}"),
+ })
+ .await
+ .unwrap();
+ store
+ .writer
+ .link_managed_run_session(run.run_id, AgentKind::Codex, sid.to_string())
+ .await
+ .unwrap();
+ excluded.push((sid, run.run_id));
+ }
+ let eligible = begin(&store, ws, proj, now - HOUR_US, None).await;
+ observe(
+ &state,
+ eligible,
+ ObservationKind::UserPrompt,
+ now - HOUR_US,
+ "eligible prompt",
+ )
+ .await;
+
+ // The serve loop over-fetches the selection past the excluded sessions
+ // (batch + active-run count): the tick must not starve the eligible
+ // session behind a 25-deep excluded backlog.
+ let sessions = store
+ .reader
+ .idle_open_sessions(now - 30 * 60_000_000, IDLE_END_BATCH.saturating_add(25))
+ .await
+ .unwrap();
+ assert_eq!(sessions.len(), 26);
+
+ let run_tick = |sessions| {
+ let (store, wiki) = (&store, &wiki);
+ async move {
+ run_idle_end_tick(&IdleEndTickInput {
+ writer: &store.writer,
+ reader: &store.reader,
+ wiki,
+ sessions,
+ now_us: jiff::Timestamp::now().as_microsecond(),
+ consolidate_on_session_end: true,
+ has_consolidator: true,
+ })
+ .await
+ }
+ };
+
+ let outcome = run_tick(sessions).await.unwrap();
+ assert_eq!(
+ (outcome.ended, outcome.skipped),
+ (1, 25),
+ "the eligible session ends on the FIRST pass despite 25 excluded sessions ahead of it"
+ );
+ assert!(matches!(
+ disposition(&store, ws, proj, eligible).await,
+ SessionEndDisposition::AlreadyEnded
+ ));
+
+ // A second pass: the eligible one is gone; the excluded backlog stays
+ // open (their lifecycle belongs to the runs).
+ let sessions = store
+ .reader
+ .idle_open_sessions(now - 30 * 60_000_000, IDLE_END_BATCH.saturating_add(25))
+ .await
+ .unwrap();
+ assert_eq!(sessions.len(), 25);
+ let outcome = run_tick(sessions).await.unwrap();
+ assert_eq!(
+ (outcome.ended, outcome.skipped),
+ (0, 25),
+ "the excluded sessions stay open over the second pass"
+ );
+ for (sid, _run) in &excluded {
+ assert!(matches!(
+ disposition(&store, ws, proj, *sid).await,
+ SessionEndDisposition::Open
+ ));
+ }
+}
+
+#[tokio::test]
+async fn idle_tick_keeps_a_session_page_written_by_the_agent() {
+ let (_tmp, store, wiki, state) = harness().await;
+ let ws = state.workspace_id;
+ let proj = state.project_id;
+ let now = now_us();
+ let sid = begin(&store, ws, proj, now - 5 * HOUR_US, None).await;
+ observe(
+ &state,
+ sid,
+ ObservationKind::UserPrompt,
+ now - 5 * HOUR_US,
+ "agent wrote its own summary",
+ )
+ .await;
+
+ // The agent already wrote the session page (e.g. via `memory_write_page`).
+ let path = PagePath::new(page_path(sid)).unwrap();
+ wiki.write_page(ai_memory_wiki::WritePageRequest {
+ workspace_id: ws,
+ project_id: proj,
+ path: path.clone(),
+ frontmatter: serde_json::json!({ "consolidated_by": "agent" }),
+ body: "Agent-authored summary that must survive the idle end.".into(),
+ tier: Tier::Episodic,
+ pinned: false,
+ title: None,
+ admission_ctx: None,
+ author_id: None,
+ actor: ActorContext::default(),
+ evidence: Vec::new(),
+ })
+ .await
+ .unwrap();
+ let current = store
+ .reader
+ .latest_page_id_by_ids(ws, proj, page_path(sid))
+ .await
+ .unwrap()
+ .expect("agent page must be indexed");
+
+ let sessions = store
+ .reader
+ .idle_open_sessions(now - 2 * HOUR_US, IDLE_END_BATCH)
+ .await
+ .unwrap();
+ assert_eq!(sessions.len(), 1);
+ assert_eq!(
+ sessions[0].seen_page_id,
+ Some(current),
+ "selection must carry the current page id"
+ );
+
+ let outcome = run_idle_end_tick(&IdleEndTickInput {
+ writer: &store.writer,
+ reader: &store.reader,
+ wiki: &wiki,
+ sessions,
+ now_us: jiff::Timestamp::now().as_microsecond(),
+ consolidate_on_session_end: true,
+ has_consolidator: true,
+ })
+ .await
+ .unwrap();
+ assert_eq!(
+ (outcome.ended, outcome.pages_written),
+ (1, 0),
+ "an agent-written page is kept, not re-synthesized"
+ );
+ assert!(matches!(
+ disposition(&store, ws, proj, sid).await,
+ SessionEndDisposition::AlreadyEnded
+ ));
+ // Exactly one page version: the agent's, untouched.
+ assert_eq!(page_total(&store.reader, ws, proj, sid).await, 1);
+ let doc = wiki.read_page(ws, proj, &path).unwrap();
+ assert!(doc.body.contains("Agent-authored summary"));
+}
+
+#[tokio::test]
+async fn idle_tick_skips_a_session_ended_by_a_real_session_end_between_selection_and_write() {
+ let (_tmp, store, _wiki, state) = harness().await;
+ let ws = state.workspace_id;
+ let proj = state.project_id;
+ let now = now_us();
+ let sid = begin(&store, ws, proj, now - 5 * HOUR_US, None).await;
+ observe(
+ &state,
+ sid,
+ ObservationKind::UserPrompt,
+ now - 5 * HOUR_US,
+ "real end wins the race",
+ )
+ .await;
+
+ // The tick selects the session…
+ let sessions = store
+ .reader
+ .idle_open_sessions(now - 2 * HOUR_US, IDLE_END_BATCH)
+ .await
+ .unwrap();
+ assert_eq!(sessions.len(), 1);
+
+ // …a real `/hook` SessionEnd lands and ends the session first. The
+ // route 202s after SPAWNING its effect (no completion barrier), so the
+ // bounded poll below waits on the effect's store state, not a sleep.
+ assert_eq!(post_session_end(&state, sid).await, StatusCode::ACCEPTED);
+ let settled = until(|| {
+ let store = &store;
+ Box::pin(async move {
+ matches!(
+ disposition(store, ws, proj, sid).await,
+ SessionEndDisposition::AlreadyEnded
+ )
+ })
+ })
+ .await;
+ assert!(settled, "the real SessionEnd must end the session");
+ let hook_page = store
+ .reader
+ .latest_page_id_by_ids(ws, proj, page_path(sid))
+ .await
+ .unwrap()
+ .expect("hook page must exist");
+
+ // The tick then runs with its stale selection: the page precondition
+ // (Absent) no longer holds and the CAS guard (ended_at IS NULL) no
+ // longer holds either — it must skip, not overwrite (M9).
+ let outcome = run_idle_end_tick(&IdleEndTickInput {
+ writer: &store.writer,
+ reader: &store.reader,
+ wiki: &state.wiki,
+ sessions,
+ now_us: jiff::Timestamp::now().as_microsecond(),
+ consolidate_on_session_end: true,
+ has_consolidator: true,
+ })
+ .await
+ .unwrap();
+ assert_eq!(
+ (outcome.ended, outcome.skipped, outcome.pages_written),
+ (0, 1, 0)
+ );
+ // The hook's page is the only version — the tick superseded nothing.
+ assert_eq!(
+ store
+ .reader
+ .latest_page_id_by_ids(ws, proj, page_path(sid))
+ .await
+ .unwrap(),
+ Some(hook_page)
+ );
+ assert_eq!(page_total(&store.reader, ws, proj, sid).await, 1);
+ // The hook created its handoff; the tick added none.
+ assert_eq!(open_handoffs(&store, ws, proj).await, 1);
+ // No idle-end audit row: the tick ended nothing.
+ assert!(idle_end_audit(&store).await.is_empty());
+}
+
+#[tokio::test]
+async fn idle_tick_late_real_session_end_with_new_work_reends_with_handoff() {
+ let (_tmp, store, _wiki, state) = harness().await;
+ let ws = state.workspace_id;
+ let proj = state.project_id;
+ let now = now_us();
+ let sid = begin(&store, ws, proj, now - 5 * HOUR_US, None).await;
+ observe(
+ &state,
+ sid,
+ ObservationKind::UserPrompt,
+ now - 5 * HOUR_US,
+ "first work",
+ )
+ .await;
+
+ // The tick ends the session first (watermark at the old activity).
+ let sessions = store
+ .reader
+ .idle_open_sessions(now - 2 * HOUR_US, IDLE_END_BATCH)
+ .await
+ .unwrap();
+ let outcome = run_idle_end_tick(&IdleEndTickInput {
+ writer: &store.writer,
+ reader: &store.reader,
+ wiki: &state.wiki,
+ sessions,
+ now_us: jiff::Timestamp::now().as_microsecond(),
+ consolidate_on_session_end: true,
+ has_consolidator: true,
+ })
+ .await
+ .unwrap();
+ assert_eq!(outcome.ended, 1);
+
+ // The session was not really done: new work arrives, then the real
+ // SessionEnd. The hook must re-end (new watermark, new page version,
+ // and the one handoff a real SessionEnd carries).
+ observe(
+ &state,
+ sid,
+ ObservationKind::UserPrompt,
+ now - 1_000,
+ "late work after the idle end",
+ )
+ .await;
+ assert_eq!(post_session_end(&state, sid).await, StatusCode::ACCEPTED);
+ let settled = until(|| {
+ let store = &store;
+ Box::pin(async move { open_handoffs(store, ws, proj).await == 1 })
+ })
+ .await;
+ assert!(
+ settled,
+ "the real SessionEnd must claim exactly one handoff"
+ );
+ assert_eq!(open_handoffs(&store, ws, proj).await, 1);
+ assert_eq!(page_total(&store.reader, ws, proj, sid).await, 2);
+ assert!(matches!(
+ disposition(&store, ws, proj, sid).await,
+ SessionEndDisposition::AlreadyEnded
+ ));
+ // No second idle-end audit row: the hook's re-end carries its own audit
+ // op, and the tick's single end stands unchallenged.
+ assert_eq!(idle_end_audit(&store).await.len(), 1);
+}
diff --git a/crates/ai-memory-hooks/tests/suite/mod.rs b/crates/ai-memory-hooks/tests/suite/mod.rs
index 125c4a8d..f3891b8f 100644
--- a/crates/ai-memory-hooks/tests/suite/mod.rs
+++ b/crates/ai-memory-hooks/tests/suite/mod.rs
@@ -2,6 +2,7 @@
//! test harness (see the `integration` module in `src/lib.rs`), so they cost
//! no extra binary; a new file must be declared below.
+mod idle_end;
mod powershell_home;
mod powershell_marker_aliases;
mod powershell_server_routed;
diff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rs
index 5b3c1059..3de56da0 100644
--- a/crates/ai-memory-store/src/lib.rs
+++ b/crates/ai-memory-store/src/lib.rs
@@ -63,13 +63,14 @@ pub use maintenance::MaintenanceJob;
pub use ops::{
AdmittedSession, BootstrapChunkRecord, CompactSummary, Compaction, ConditionalUpsert,
DateOnlyTtlPage, DeleteWorkspaceSummary, EmbedOutcome, EmbeddingWrite, EntityBackfillSummary,
- HookSessionAdmission, IdentityResolution, IngestObservationOutcome, LifecycleOnlyEndOutcome,
- MAX_PENDING_INBOX_MESSAGES, MoveSessionSummary, MoveSummary, ObservationPruneOutcome,
- OkfMigratedPage, PAGE_WINDOW_BACKFILL_BATCH, PagePrecondition, PageWindowBackfillSummary,
- PagesMode, ProjectAliasWriteResolution, PurgeMode, PurgeSessionSummary, PurgeSummary,
- ReorgSummary, RepairSessionTimesSummary, RepairedSessionTimes, SessionTimesCandidate,
- SessionTimesSkipReason, SkippedSessionTimes, StaleAfterRepair, backfill_entity_index,
- backfill_page_windows, backfill_page_windows_in_batches, purge_session, record_embed_failure,
+ HookSessionAdmission, IdentityResolution, IdleEndAction, IdleEndCandidate, IdleEndResult,
+ IngestObservationOutcome, LifecycleOnlyEndOutcome, MAX_PENDING_INBOX_MESSAGES,
+ MoveSessionSummary, MoveSummary, ObservationPruneOutcome, OkfMigratedPage,
+ PAGE_WINDOW_BACKFILL_BATCH, PagePrecondition, PageWindowBackfillSummary, PagesMode,
+ ProjectAliasWriteResolution, PurgeMode, PurgeSessionSummary, PurgeSummary, ReorgSummary,
+ RepairSessionTimesSummary, RepairedSessionTimes, SessionTimesCandidate, SessionTimesSkipReason,
+ SkippedSessionTimes, StaleAfterRepair, backfill_entity_index, backfill_page_windows,
+ backfill_page_windows_in_batches, purge_session, record_embed_failure,
};
pub use profile::{
NewProfileCandidate, PROFILE_CANDIDATES_LIMIT, PROFILE_ENTRIES_LIMIT, PROFILE_HARVEST_BATCH,
@@ -86,18 +87,19 @@ pub use reader::{
AutoImproveParkedClaim, BriefPageBody, BriefingPage, BriefingSnapshot, ClientActivity,
ContaminationFinding, ContaminationReport, ContaminationSummary, ContradictionEdge,
DecayCandidate, DecayTombstone, DerivedIndexStatus, EmbeddingTripleCount, FeedbackFinding,
- GraphVia, HealthDetail, HealthPage, HybridSearch, InboxCount, InboxEntry, ObservationHit,
- ObservationOrder, ObservationPage, ObservationPageResult, ObservationRecord, OpenSession,
- PAGE_KINDS, PAGE_VERSIONS_MAX_LIMIT, PageAuthor, PageFilter, PageHit, PageHitWithMeta,
- PageLinks, PageLinksPreview, PageMeta, PageSummary, PageVersion, PageVersionBody, PageVersions,
- ProjectCoordinateCollisionReason, ProjectCoordinateDiagnostic, ProjectCoordinateStatus,
- ProjectSummary, RELATED_WALK_MAX_DEPTH, RELATED_WALK_MAX_NODES, ReaderPool,
- ReindexTargetStatus, RelatedNode, RelatedPage, RrfContributions, SESSION_LINE_TITLE_CHARS,
- SUBSTANTIVE_OBSERVATION_KIND_SQL, ScopeRow, SearchExplain, SessionConsolidationQueue,
- SessionConsolidationSummary, SessionDependentRows, SessionEndDisposition, SessionKindSummary,
- SessionLine, SessionObservationSnapshot, SessionSummary, SessionToolTitles, SettledPage,
- StatusCounts, StorageStatus, StoredEmbedding, StoredPageBody, StreamTimings, VectorQuery,
- WorkspaceScopeRow, WorkspaceSummary, f32_vec_to_bytes,
+ GraphVia, HealthDetail, HealthPage, HybridSearch, IdleOpenSession, InboxCount, InboxEntry,
+ ObservationHit, ObservationOrder, ObservationPage, ObservationPageResult, ObservationRecord,
+ OpenSession, PAGE_KINDS, PAGE_VERSIONS_MAX_LIMIT, PageAuthor, PageFilter, PageHit,
+ PageHitWithMeta, PageLinks, PageLinksPreview, PageMeta, PageSummary, PageVersion,
+ PageVersionBody, PageVersions, ProjectCoordinateCollisionReason, ProjectCoordinateDiagnostic,
+ ProjectCoordinateStatus, ProjectSummary, RELATED_WALK_MAX_DEPTH, RELATED_WALK_MAX_NODES,
+ ReaderPool, ReindexTargetStatus, RelatedNode, RelatedPage, RrfContributions,
+ SESSION_LINE_TITLE_CHARS, SUBSTANTIVE_OBSERVATION_KIND_SQL, ScopeRow, SearchExplain,
+ SessionConsolidationQueue, SessionConsolidationSummary, SessionDependentRows,
+ SessionEndDisposition, SessionKindSummary, SessionLine, SessionObservationSnapshot,
+ SessionSummary, SessionToolTitles, SettledPage, StatusCounts, StorageStatus, StoredEmbedding,
+ StoredPageBody, StreamTimings, VectorQuery, WorkspaceScopeRow, WorkspaceSummary,
+ f32_vec_to_bytes,
};
pub use retrieval_tuning::{RetrievalTuning, is_session_recall_query};
pub use scope::{
@@ -108,7 +110,9 @@ pub use scope::{
lookup_existing_workspace, lookup_global_scope, lookup_profile_scope,
resolve_many_existing_scopes, resolve_many_existing_scopes_guarded,
};
-pub use session_consolidation::{SESSION_CONSOLIDATION_MAX_ATTEMPTS, SessionConsolidationJob};
+pub use session_consolidation::{
+ SESSION_CONSOLIDATION_MAX_ATTEMPTS, SessionConsolidationJob, enqueue_in_tx,
+};
pub use users::{LoginUser, TOKEN_HASH_LEN, TOKEN_RAW_LEN, TokenPepper, hash_token};
pub use web_sessions::{LiveWebSession, WebSession, hash_session_secret};
pub use workstream::{
diff --git a/crates/ai-memory-store/src/ops.rs b/crates/ai-memory-store/src/ops.rs
index e8bc01ce..2715484d 100644
--- a/crates/ai-memory-store/src/ops.rs
+++ b/crates/ai-memory-store/src/ops.rs
@@ -3249,6 +3249,292 @@ pub fn end_admitted_session_with_handoff(
Ok(id)
}
+/// An idle auto-end candidate as selected by the server-side tick
+/// ([`crate::reader::ReaderPool::idle_open_sessions`]).
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum IdleEndAction {
+ /// A substantive session: end it with its summary page and, when the
+ /// caller asks for it, its consolidation job.
+ Substantive {
+ /// The latest `sessions/<id>.md` version the tick WROTE OR KEPT.
+ /// The stamp re-verifies it is still the latest: a checkpoint or a
+ /// real `SessionEnd` page landing after the tick's write would
+ /// otherwise leave the stamp pointing at a page that no longer
+ /// represents the session's work.
+ expected_page_id: PageId,
+ /// The session's observation count at the moment the digest was
+ /// built (read in the digest's own snapshot: EVERY observation of
+ /// the session, whatever project each row landed in — the same
+ /// population `session_observation_count` counts). The stamp
+ /// re-verifies the live count still equals it: a non-end observation
+ /// landing after the digest would otherwise reach the watermark
+ /// without reaching the page.
+ observation_count: i64,
+ /// The tick's clock, in Unix microseconds. `ended_at` is stamped
+ /// with it — not with the session's last activity — so the
+ /// auto-improvement discovery, which is ordered by `ended_at`, finds
+ /// auto-ended sessions in the order they were ended.
+ now_us: i64,
+ /// The session's last activity, in Unix microseconds. Recorded in
+ /// the audit detail next to the tick's clock.
+ last_activity_us: i64,
+ },
+ /// A boundary-only session: end it without a page or a consolidation
+ /// job; a handoff accepted for it reopens for its owner.
+ LifecycleOnly {
+ /// The tick's clock, as in [`Self::Substantive::now_us`].
+ now_us: i64,
+ /// The session's last activity, as in
+ /// [`Self::Substantive::last_activity_us`].
+ last_activity_us: i64,
+ },
+}
+
+/// Outcome of one candidate in a batched idle end.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum IdleEndResult {
+ /// The substantive session ended with its summary page and watermark.
+ EndedSubstantive,
+ /// The lifecycle-only session ended (releasing its accepted handoff
+ /// when one existed).
+ EndedLifecycleOnly,
+ /// The session could no longer be ended: a real `SessionEnd` won the
+ /// race (the CAS saw `ended_at` set), the candidate no longer matches
+ /// its row's scope, the observation count or the latest page version
+ /// moved after the tick read it, or substantive work arrived before the
+ /// lifecycle-only atomic re-check. The row is untouched.
+ Lost,
+}
+
+/// One session for [`idle_end_sessions`], fully scoped so the guarded write
+/// never trusts a caller-provided id alone.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct IdleEndCandidate {
+ /// Session to end.
+ pub session_id: SessionId,
+ /// Workspace the session row must belong to.
+ pub workspace_id: WorkspaceId,
+ /// Project the session row must belong to.
+ pub project_id: ProjectId,
+ /// Harness recorded on the session row.
+ pub agent_kind: AgentKind,
+ /// What the end does.
+ pub action: IdleEndAction,
+}
+
+/// End a batch of idle sessions in one writer command.
+///
+/// Each candidate is stamped by its own guarded write. The substantive end
+/// is an `UPDATE … WHERE ended_at IS NULL` CAS that ALSO re-verifies what the
+/// summary page saw: the session's observation count (every row of the
+/// session, the digest's population) must still equal the
+/// count the digest was built from, and the latest page version must still
+/// be the one the tick wrote or kept. Any mismatch — a non-end observation,
+/// a checkpoint page, or a real `SessionEnd` landing after the tick's read —
+/// reports [`IdleEndResult::Lost`] and rolls the candidate's transaction
+/// back: no stamp, no audit, no enqueue; the page the tick wrote stays an
+/// ordinary version. The lifecycle-only end applies the same scope/open
+/// guards before any mutation and re-checks substantiveness atomically,
+/// reporting `Lost` instead of downgrading substantive work to a boundary-
+/// only end.
+///
+/// `ended_at` is the tick's clock (`now_us`), and
+/// `ended_observation_count` is counted in the same transaction as the
+/// stamp, so a later real `SessionEnd` is `AlreadyEnded` (no new
+/// observations) or `ReEnd` (new work arrived) against that watermark —
+/// never a double end of the same work. The session's last activity is
+/// preserved in the audit detail (`last_activity_us`). No handoff is
+/// created here: the baton is the hook path's decision.
+///
+/// `enqueue_consolidation` is the server's resolved
+/// `consolidate_on_session_end` flag, the same effect the hook path applies
+/// to a substantive end, computed once per tick. The enqueue runs INSIDE the
+/// stamp's transaction: a failed enqueue rolls back the stamp and the audit,
+/// leaving the session open for the next tick. A lost candidate is never
+/// enqueued.
+///
+/// # Errors
+/// Returns a [`StoreError`] on any SQL or commit failure. A CAS miss is not
+/// an error: it is reported per candidate as [`IdleEndResult::Lost`].
+pub fn idle_end_sessions(
+ conn: &mut Connection,
+ candidates: &[IdleEndCandidate],
+ enqueue_consolidation: bool,
+) -> StoreResult<Vec<IdleEndResult>> {
+ idle_end_sessions_inner(conn, candidates, enqueue_consolidation, None)
+}
+
+/// Test-only: [`idle_end_sessions`] with a `pre_stamp` hook that runs on
+/// the writer connection BEFORE each candidate's stamp transaction opens
+/// (after the previous candidate finished, before the `transaction()`
+/// below) — not inside it. Lets a test race a real effect (a non-end
+/// observation, a checkpoint page, a real `SessionEnd` stamp)
+/// deterministically into the window between the tick's page write and the
+/// stamp, without sleeps. The hook simulates a concurrent writer's effect
+/// landing in that window; it is not a participant in the stamp
+/// transaction.
+#[cfg(test)]
+pub fn idle_end_sessions_pre_stamp(
+ conn: &mut Connection,
+ candidates: &[IdleEndCandidate],
+ enqueue_consolidation: bool,
+ pre_stamp: &mut dyn FnMut(&mut Connection),
+) -> StoreResult<Vec<IdleEndResult>> {
+ idle_end_sessions_inner(conn, candidates, enqueue_consolidation, Some(pre_stamp))
+}
+
+fn idle_end_sessions_inner(
+ conn: &mut Connection,
+ candidates: &[IdleEndCandidate],
+ enqueue_consolidation: bool,
+ mut pre_stamp: Option<&mut dyn FnMut(&mut Connection)>,
+) -> StoreResult<Vec<IdleEndResult>> {
+ let mut results = Vec::with_capacity(candidates.len());
+ for candidate in candidates {
+ if let Some(hook) = pre_stamp.as_mut() {
+ hook(conn);
+ }
+ let result = match &candidate.action {
+ IdleEndAction::Substantive {
+ expected_page_id,
+ observation_count,
+ now_us,
+ last_activity_us,
+ } => {
+ let tx = conn.transaction()?;
+ let page_blob: &[u8] = expected_page_id.as_bytes();
+ let changed = tx.execute(
+ "UPDATE sessions \
+ SET ended_at = ?1, summary_page_id = ?2, \
+ ended_observation_count = ( \
+ SELECT COUNT(*) FROM observations \
+ WHERE session_id = ?3 \
+ ) \
+ WHERE id = ?3 AND workspace_id = ?4 AND project_id = ?5 \
+ AND ended_at IS NULL \
+ AND ( \
+ SELECT COUNT(*) FROM observations \
+ WHERE session_id = ?3 \
+ ) = ?6 \
+ AND ( \
+ SELECT id FROM pages \
+ WHERE workspace_id = ?4 AND project_id = ?5 \
+ AND path = ?7 AND is_latest = 1 \
+ ) = ?2",
+ params![
+ *now_us,
+ page_blob,
+ candidate.session_id.as_bytes(),
+ candidate.workspace_id.as_bytes(),
+ candidate.project_id.as_bytes(),
+ *observation_count,
+ format!("sessions/{}.md", candidate.session_id)
+ ],
+ )?;
+ if changed == 0 {
+ // A real SessionEnd (or another writer) ended the
+ // session after the tick selected it, the session's
+ // work or its page moved after the tick's read, or the
+ // candidate no longer matches its row: the newer effect
+ // owns the row. Drop the transaction to roll back.
+ results.push(IdleEndResult::Lost);
+ continue;
+ }
+ audit_with_detail(
+ &tx,
+ "idle_session_end",
+ Some(candidate.workspace_id.as_bytes()),
+ Some(candidate.project_id.as_bytes()),
+ Some(expected_page_id.as_bytes()),
+ None,
+ *now_us,
+ &serde_json::json!({
+ "session_id": candidate.session_id.to_string(),
+ "action": "substantive",
+ "last_activity_us": *last_activity_us,
+ })
+ .to_string(),
+ )?;
+ // The enqueue runs inside the stamp's transaction: a failed
+ // enqueue propagates, the transaction rolls back, and the
+ // session stays open for the next tick.
+ if enqueue_consolidation {
+ crate::session_consolidation::enqueue_in_tx(
+ &tx,
+ candidate.workspace_id,
+ candidate.project_id,
+ candidate.session_id,
+ )?;
+ }
+ tx.commit()?;
+ IdleEndResult::EndedSubstantive
+ }
+ IdleEndAction::LifecycleOnly {
+ now_us,
+ last_activity_us,
+ } => {
+ let tx = conn.transaction()?;
+ // The same guards as the substantive arm, before any
+ // mutation or handoff release: the candidate's scope must
+ // match the row and the row must still be open. Anything
+ // else is a stale or foreign candidate: `Lost`, nothing
+ // written.
+ let open: i64 = tx.query_row(
+ "SELECT COUNT(*) FROM sessions \
+ WHERE id = ?1 AND workspace_id = ?2 AND project_id = ?3 \
+ AND ended_at IS NULL",
+ params![
+ candidate.session_id.as_bytes(),
+ candidate.workspace_id.as_bytes(),
+ candidate.project_id.as_bytes()
+ ],
+ |row| row.get(0),
+ )?;
+ if open == 0 {
+ results.push(IdleEndResult::Lost);
+ continue;
+ }
+ let outcome =
+ end_lifecycle_only_session_in_tx(&tx, &candidate.session_id, Some(*now_us))?;
+ match outcome {
+ LifecycleOnlyEndOutcome::Ended { .. } => {
+ // The auto-end audit is its own row in the stamp's
+ // transaction, distinct from the
+ // `release_lifecycle_only_handoff` row the handoff
+ // release writes when a handoff was released.
+ audit_with_detail(
+ &tx,
+ "idle_session_end",
+ Some(candidate.workspace_id.as_bytes()),
+ Some(candidate.project_id.as_bytes()),
+ None,
+ None,
+ *now_us,
+ &serde_json::json!({
+ "session_id": candidate.session_id.to_string(),
+ "action": "lifecycle_only",
+ "last_activity_us": *last_activity_us,
+ })
+ .to_string(),
+ )?;
+ tx.commit()?;
+ IdleEndResult::EndedLifecycleOnly
+ }
+ // Substantive work raced the tick's classification: leave
+ // the session open (the transaction rolls back) and let
+ // the real end — or the next tick — handle it.
+ LifecycleOnlyEndOutcome::Substantive => {
+ results.push(IdleEndResult::Lost);
+ continue;
+ }
+ }
+ }
+ };
+ results.push(result);
+ }
+ Ok(results)
+}
+
/// Mark a keyed hook event complete after its downstream effects finish.
///
/// This transition is idempotent so two resumed processors can converge on the
diff --git a/crates/ai-memory-store/src/reader.rs b/crates/ai-memory-store/src/reader.rs
index a2664dd3..4be83aab 100644
--- a/crates/ai-memory-store/src/reader.rs
+++ b/crates/ai-memory-store/src/reader.rs
@@ -1199,6 +1199,39 @@ pub struct SessionConsolidationQueue {
pub oldest_pending_requested_at_us: Option<i64>,
}
+/// One open session selected by [`ReaderPool::idle_open_sessions`] for the
+/// server-side idle auto-end tick: its last activity
+/// (`MAX(observations.created_at)`, falling back to `started_at`) is older
+/// than the tick's cutoff, and it never received a `SessionEnd`.
+#[derive(Debug, Clone)]
+pub struct IdleOpenSession {
+ /// Session id.
+ pub session_id: SessionId,
+ /// Owning workspace.
+ pub workspace_id: WorkspaceId,
+ /// Owning project.
+ pub project_id: ProjectId,
+ /// Harness that opened the session.
+ pub agent_kind: AgentKind,
+ /// Captured session cwd, if available.
+ pub cwd: Option<String>,
+ /// Operator owning the session (`IdentityKey::storage_key`), `None` when
+ /// the session is shared/actorless. The tick attributes its page to this
+ /// owner, not to the server process.
+ pub actor_user: Option<String>,
+ /// Session start, Unix microseconds.
+ pub started_at: i64,
+ /// `MAX(observations.created_at)`, or `started_at` when the session has
+ /// no observations. The end preserves it in the audit detail
+ /// (`last_activity_us`); `ended_at` is the tick's clock.
+ pub last_activity_us: i64,
+ /// Latest `sessions/<id>.md` version captured alongside the selection
+ /// (same read, before any write). The tick's conditional page write takes
+ /// it as its precondition, so it cannot supersede a page a real
+ /// `SessionEnd` delivered after the selection.
+ pub seen_page_id: Option<PageId>,
+}
+
/// One session as listed from a scope by [`ReaderPool::sessions_for_scope`]
/// and [`ReaderPool::session_summary_scoped`].
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
@@ -3788,6 +3821,42 @@ impl ReaderPool {
.await
}
+ /// Count one session's IN-SCOPE observations — every kind, not just the
+ /// substantive ones. A session's idle end stamps
+ /// `ended_observation_count` from the live count and re-verifies the
+ /// candidate's digest-time count against it: a non-end observation
+ /// (a `Stop`, a lifecycle marker) landing in the window between the
+ /// digest read and the stamp must still lose the CAS. Scoped the same
+ /// way as [`Self::session_has_substantive_observation`]; a missing or
+ /// foreign session counts as zero.
+ ///
+ /// # Errors
+ /// Propagates any SQL or pool error.
+ pub async fn session_observation_count(
+ &self,
+ workspace_id: WorkspaceId,
+ project_id: ProjectId,
+ session_id: SessionId,
+ ) -> StoreResult<i64> {
+ self.with_conn(move |conn| {
+ const SQL: &str = "SELECT COUNT(*) \
+ FROM observations AS o \
+ JOIN sessions AS s ON s.id = o.session_id \
+ WHERE o.session_id = ?1 \
+ AND s.workspace_id = ?2 AND s.project_id = ?3";
+ Ok(conn.query_row(
+ SQL,
+ params![
+ session_id.as_bytes(),
+ workspace_id.as_bytes(),
+ project_id.as_bytes()
+ ],
+ |row| row.get(0),
+ )?)
+ })
+ .await
+ }
+
/// Read one session's observations through bounded queries, all inside one
/// read transaction so every answer describes the same set of rows. The
/// session must belong to the given workspace and project; a foreign or
@@ -4950,6 +5019,151 @@ impl ReaderPool {
.await
}
+ /// Open sessions whose last activity is older than `cutoff_us`, for the
+ /// server-side idle auto-end tick.
+ ///
+ /// "Last activity" is `MAX(observations.created_at)` — the same fact the
+ /// end's audit preserves (`last_activity_us` detail; `ended_at` itself is
+ /// the tick's clock) — falling back to `started_at` for a session that
+ /// began but never captured an observation. Sessions without the
+ /// `ended_at IS NULL` shape are never returned, so the result is a
+ /// re-check-free candidate list: the end itself still guards with its own
+ /// `ended_at IS NULL` CAS in the writer.
+ ///
+ /// `seen_page_id` captures the latest `sessions/<id>.md` version in the
+ /// SAME STATEMENT as the session row (a correlated subquery over `pages`,
+ /// so one atomic SELECT cannot observe a page a real `SessionEnd`
+ /// publishes after the session row was read): the tick's conditional page
+ /// write takes it as its precondition and cannot supersede a page the
+ /// hook delivered between the selection and the tick's write. The path is
+ /// rendered in SQL from the id blob (see the query below); the selection
+ /// test proves it byte-for-byte against the Rust-rendered path.
+ ///
+ /// Ordered by last activity (oldest first) and bounded by `limit`, so one
+ /// tick ends a bounded batch and the next picks up the rest.
+ ///
+ /// # Errors
+ /// Propagates any SQL or pool error.
+ pub async fn idle_open_sessions(
+ &self,
+ cutoff_us: i64,
+ limit: usize,
+ ) -> StoreResult<Vec<IdleOpenSession>> {
+ self.with_conn(move |conn| {
+ // ONE statement: the correlated subquery reads each session page
+ // from the same atomic snapshot as the session row, so the tick's
+ // precondition can never be a page version it never saw.
+ //
+ // The page path is rendered in SQL because `sessions.id` is the
+ // 16-byte UUID blob while `pages.path` is text: `lower(hex(s.id))`
+ // is the UUID's canonical hyphenless hex in the same lowercase
+ // letters `SessionId`'s `Display` prints, and the substr pieces
+ // reinsert the 8-4-4-4-12 hyphens. The result is byte-for-byte the
+ // Rust `format!("sessions/{session_id}.md")` — the selection test
+ // proves it with a page present (captured) and absent (not), so a
+ // rendering drift would stall the session, never compare against a
+ // guessed path.
+ let mut stmt = conn.prepare(
+ "SELECT s.id, s.workspace_id, s.project_id, s.agent_kind, s.cwd, s.actor_user, \
+ s.started_at, COALESCE( \
+ (SELECT MAX(o.created_at) FROM observations o \
+ WHERE o.session_id = s.id), \
+ s.started_at) AS last_activity, \
+ (SELECT p.id FROM pages p \
+ WHERE p.workspace_id = s.workspace_id \
+ AND p.project_id = s.project_id \
+ AND p.is_latest = 1 \
+ AND p.path = 'sessions/' || substr(lower(hex(s.id)), 1, 8) || '-' || \
+ substr(lower(hex(s.id)), 9, 4) || '-' || \
+ substr(lower(hex(s.id)), 13, 4) || '-' || \
+ substr(lower(hex(s.id)), 17, 4) || '-' || \
+ substr(lower(hex(s.id)), 21, 12) || '.md') \
+ FROM sessions s \
+ WHERE s.ended_at IS NULL \
+ AND COALESCE( \
+ (SELECT MAX(o.created_at) FROM observations o \
+ WHERE o.session_id = s.id), \
+ s.started_at) < ?1 \
+ ORDER BY last_activity ASC, s.id ASC \
+ LIMIT ?2",
+ )?;
+ let rows = stmt
+ .query_map(params![cutoff_us, limit as i64], |row| {
+ Ok((
+ row.get::<_, Vec<u8>>(0)?,
+ row.get::<_, Vec<u8>>(1)?,
+ row.get::<_, Vec<u8>>(2)?,
+ row.get::<_, String>(3)?,
+ row.get::<_, Option<String>>(4)?,
+ row.get::<_, Option<String>>(5)?,
+ row.get::<_, i64>(6)?,
+ row.get::<_, i64>(7)?,
+ row.get::<_, Option<Vec<u8>>>(8)?,
+ ))
+ })?
+ .collect::<Result<Vec<_>, _>>()?;
+ let mut out = Vec::with_capacity(rows.len());
+ for (
+ id,
+ workspace_id,
+ project_id,
+ agent_kind,
+ cwd,
+ actor_user,
+ started_at,
+ last_activity_us,
+ page_id,
+ ) in rows
+ {
+ let session_id = SessionId::from_slice(&id)?;
+ let workspace_id = WorkspaceId::from_slice(&workspace_id)?;
+ let project_id = ProjectId::from_slice(&project_id)?;
+ let seen_page_id = page_id
+ .as_ref()
+ .map(|bytes| PageId::from_slice(bytes))
+ .transpose()?;
+ out.push(IdleOpenSession {
+ session_id,
+ workspace_id,
+ project_id,
+ agent_kind: AgentKind::from_wire(&agent_kind),
+ cwd,
+ actor_user,
+ started_at,
+ last_activity_us,
+ seen_page_id,
+ });
+ }
+ Ok(out)
+ })
+ .await
+ }
+
+ /// Native session ids bound to `managed_runs` rows still in state
+ /// `active`, for the idle auto-end tick's exclusion: a live managed run
+ /// (`ai-memory run`) owns its native session's lifecycle, so the tick
+ /// must not end it even when the session row looks idle.
+ ///
+ /// The join is done in Rust, not SQL: `managed_runs.native_session_id`
+ /// holds the harness's native id string while `sessions.id` is the
+ /// derived UUIDv7 blob, so the two columns never compare equal in SQL.
+ ///
+ /// # Errors
+ /// Propagates any SQL or pool error.
+ pub async fn active_managed_run_native_session_ids(&self) -> StoreResult<Vec<String>> {
+ self.with_conn(|conn| {
+ let mut stmt = conn.prepare(
+ "SELECT native_session_id FROM managed_runs \
+ WHERE state = 'active' AND native_session_id IS NOT NULL",
+ )?;
+ let ids = stmt
+ .query_map([], |row| row.get::<_, String>(0))?
+ .collect::<Result<Vec<_>, _>>()?;
+ Ok(ids)
+ })
+ .await
+ }
+
/// Resolve the `(workspace, project)` where a session's observations
/// actually landed, independent of the (possibly stale) `sessions` row.
///
diff --git a/crates/ai-memory-store/src/session_consolidation.rs b/crates/ai-memory-store/src/session_consolidation.rs
index a7835890..351b356a 100644
--- a/crates/ai-memory-store/src/session_consolidation.rs
+++ b/crates/ai-memory-store/src/session_consolidation.rs
@@ -2,7 +2,7 @@
use ai_memory_core::{ProjectId, SessionId, WorkspaceId};
use jiff::Timestamp;
-use rusqlite::{Connection, OptionalExtension, TransactionBehavior, params};
+use rusqlite::{Connection, OptionalExtension, Transaction, TransactionBehavior, params};
use uuid::Uuid;
use crate::error::{StoreError, StoreResult};
@@ -112,6 +112,44 @@ fn enqueue_eligible(
project_id: ProjectId,
session_id: SessionId,
eligibility: EnqueueEligibility,
+) -> StoreResult<bool> {
+ let tx = conn.transaction()?;
+ let inserted = enqueue_eligible_in_tx(&tx, workspace_id, project_id, session_id, eligibility)?;
+ tx.commit()?;
+ Ok(inserted)
+}
+
+/// [`enqueue`] inside a caller-owned transaction: the job insert commits or
+/// rolls back WITH the caller's effect, so a failed enqueue can never leave
+/// an ended session behind without its consolidation job.
+///
+/// Returns `true` only when a new generation was inserted. A duplicate
+/// generation, missing session, mismatched scope, open session, or
+/// observation-less session returns `false` without creating work.
+///
+/// # Errors
+/// Propagates SQL errors; the caller rolls back its own transaction.
+pub fn enqueue_in_tx(
+ tx: &Transaction<'_>,
+ workspace_id: WorkspaceId,
+ project_id: ProjectId,
+ session_id: SessionId,
+) -> StoreResult<bool> {
+ enqueue_eligible_in_tx(
+ tx,
+ workspace_id,
+ project_id,
+ session_id,
+ EnqueueEligibility::EndedSession,
+ )
+}
+
+fn enqueue_eligible_in_tx(
+ tx: &Transaction<'_>,
+ workspace_id: WorkspaceId,
+ project_id: ProjectId,
+ session_id: SessionId,
+ eligibility: EnqueueEligibility,
) -> StoreResult<bool> {
let ended_predicate = match eligibility {
EnqueueEligibility::EndedSession => "AND s.ended_at IS NOT NULL",
@@ -131,7 +169,6 @@ fn enqueue_eligible(
HAVING COUNT(o.id) > 0"
);
let now = Timestamp::now().as_microsecond();
- let tx = conn.transaction()?;
let inserted = tx.execute(
&sql,
params![
@@ -155,7 +192,6 @@ fn enqueue_eligible(
)",
params![now, session_id.as_bytes()],
)?;
- tx.commit()?;
Ok(inserted == 1)
}
diff --git a/crates/ai-memory-store/src/writer.rs b/crates/ai-memory-store/src/writer.rs
index 984e5fcb..0d42d927 100644
--- a/crates/ai-memory-store/src/writer.rs
+++ b/crates/ai-memory-store/src/writer.rs
@@ -29,8 +29,9 @@ use crate::auto_improve::{
use crate::error::{StoreError, StoreResult};
use crate::ops::{
self, AdmittedSession, DeleteWorkspaceSummary, EmbeddingWrite, HookSessionAdmission,
- IngestObservationOutcome, LifecycleOnlyEndOutcome, MoveSessionSummary, MoveSummary,
- ObservationPruneOutcome, PagesMode, PurgeSummary, ReorgSummary,
+ IdleEndCandidate, IdleEndResult, IngestObservationOutcome, LifecycleOnlyEndOutcome,
+ MoveSessionSummary, MoveSummary, ObservationPruneOutcome, PagesMode, PurgeSummary,
+ ReorgSummary,
};
use crate::session_consolidation::SessionConsolidationJob;
use crate::users::{self, TOKEN_HASH_LEN};
@@ -219,6 +220,22 @@ pub(crate) enum WriteCmd {
session_id: SessionId,
reply: oneshot::Sender<StoreResult<LifecycleOnlyEndOutcome>>,
},
+ EndIdleSessions {
+ candidates: Vec<IdleEndCandidate>,
+ enqueue_consolidation: bool,
+ reply: oneshot::Sender<StoreResult<Vec<IdleEndResult>>>,
+ },
+ /// Test-only: [`WriteCmd::EndIdleSessions`] with a pre-stamp hook that
+ /// runs on the writer connection BEFORE each candidate's stamp
+ /// transaction opens, racing an effect into the window between the
+ /// tick's page write and the stamp.
+ #[cfg(test)]
+ EndIdleSessionsPreStamp {
+ candidates: Vec<IdleEndCandidate>,
+ enqueue_consolidation: bool,
+ pre_stamp: Box<dyn FnMut(&mut Connection) + Send>,
+ reply: oneshot::Sender<StoreResult<Vec<IdleEndResult>>>,
+ },
SweepHollowProjects {
min_age_days: u32,
reply: oneshot::Sender<StoreResult<Vec<String>>>,
@@ -1473,6 +1490,52 @@ impl WriterHandle {
rx.await.map_err(|_| StoreError::WriterClosed)?
}
+ /// End a batch of idle sessions the server-side tick selected
+ /// ([`crate::reader::ReaderPool::idle_open_sessions`]), one writer
+ /// command per tick. See [`ops::idle_end_sessions`] for the guarded-
+ /// write and watermark semantics; a lost candidate (a real `SessionEnd`
+ /// won the race) is reported, never an error.
+ ///
+ /// # Errors
+ /// Returns [`StoreError::WriterClosed`] or propagates SQL/state errors.
+ pub async fn end_idle_sessions(
+ &self,
+ candidates: Vec<IdleEndCandidate>,
+ enqueue_consolidation: bool,
+ ) -> StoreResult<Vec<IdleEndResult>> {
+ let (tx, rx) = oneshot::channel();
+ self.send(WriteCmd::EndIdleSessions {
+ candidates,
+ enqueue_consolidation,
+ reply: tx,
+ })
+ .await?;
+ rx.await.map_err(|_| StoreError::WriterClosed)?
+ }
+
+ /// Test-only: [`Self::end_idle_sessions`] with a `pre_stamp` hook that
+ /// runs on the writer connection BEFORE each candidate's stamp
+ /// transaction opens — not inside it — so a test can race a real effect
+ /// into the window between the tick's page write and the stamp without
+ /// sleeps.
+ #[cfg(test)]
+ pub async fn end_idle_sessions_pre_stamp(
+ &self,
+ candidates: Vec<IdleEndCandidate>,
+ enqueue_consolidation: bool,
+ pre_stamp: Box<dyn FnMut(&mut rusqlite::Connection) + Send>,
+ ) -> StoreResult<Vec<IdleEndResult>> {
+ let (tx, rx) = oneshot::channel();
+ self.send(WriteCmd::EndIdleSessionsPreStamp {
+ candidates,
+ enqueue_consolidation,
+ pre_stamp,
+ reply: tx,
+ })
+ .await?;
+ rx.await.map_err(|_| StoreError::WriterClosed)?
+ }
+
/// Delete hollow project rows (no data of any kind) older than
/// `min_age_days`; returns the deleted names. See
/// [`ops::sweep_hollow_projects`].
@@ -3922,6 +3985,30 @@ fn worker_loop(mut conn: Connection, mut rx: mpsc::Receiver<WriteCmd>) {
let result = ops::end_lifecycle_only_session(&mut conn, &session_id);
send_or_warn(reply, result, "end_lifecycle_only_session");
}
+ WriteCmd::EndIdleSessions {
+ candidates,
+ enqueue_consolidation,
+ reply,
+ } => {
+ let result = ops::idle_end_sessions(&mut conn, &candidates, enqueue_consolidation);
+ send_or_warn(reply, result, "idle_end_sessions");
+ }
+ #[cfg(test)]
+ WriteCmd::EndIdleSessionsPreStamp {
+ candidates,
+ enqueue_consolidation,
+ pre_stamp,
+ reply,
+ } => {
+ let mut pre_stamp = pre_stamp;
+ let result = ops::idle_end_sessions_pre_stamp(
+ &mut conn,
+ &candidates,
+ enqueue_consolidation,
+ &mut pre_stamp,
+ );
+ send_or_warn(reply, result, "idle_end_sessions_pre_stamp");
+ }
WriteCmd::SweepHollowProjects {
min_age_days,
reply,
diff --git a/crates/ai-memory-store/tests/suite/idle_session_end.rs b/crates/ai-memory-store/tests/suite/idle_session_end.rs
new file mode 100644
index 00000000..263f8240
--- /dev/null
+++ b/crates/ai-memory-store/tests/suite/idle_session_end.rs
@@ -0,0 +1,1842 @@
+//! Server-side idle auto-end, store level: cutoff-scoped selection, the
+//! tick-clock `ended_at` with the last activity preserved in the audit, the
+//! guarded stamp (the `ended_at IS NULL` CAS re-verifying the in-scope
+//! observation count and the latest page version a real `SessionEnd` that
+//! wins the race is never re-stamped), the lifecycle-only audit + handoff
+//! release, the late-real-`SessionEnd` convergence against the watermark,
+//! and batched one-command ends.
+
+use ai_memory_core::{
+ AgentKind, HandoffAcceptance, HandoffId, HandoffState, NewHandoff, NewObservation, NewPage,
+ NewSession, ObservationKind, OwnerFilter, PagePath, ProjectId, Sanitized, Sanitizer, SessionId,
+ Tier, WorkspaceId,
+};
+use ai_memory_store::{
+ AuditLogFilter, IdleEndAction, IdleEndCandidate, IdleEndResult, SessionEndDisposition, Store,
+};
+
+const HOUR_US: i64 = 3_600_000_000;
+
+async fn scope(store: &Store) -> (WorkspaceId, ProjectId) {
+ let ws = store
+ .writer
+ .get_or_create_workspace("default".to_string())
+ .await
+ .unwrap();
+ let proj = store
+ .writer
+ .get_or_create_project(ws, "idle", None)
+ .await
+ .unwrap();
+ (ws, proj)
+}
+
+fn backdated(started_at_us: i64, actor_user: Option<String>) -> NewSession {
+ NewSession {
+ occurred_at: Some(started_at_us),
+ id: SessionId::new(),
+ workspace_id: WorkspaceId::new(),
+ project_id: ProjectId::new(),
+ agent_kind: AgentKind::Codex,
+ cwd: Some("/repo".into()),
+ actor_user,
+ }
+}
+
+async fn begin(
+ store: &Store,
+ ws: WorkspaceId,
+ proj: ProjectId,
+ at_us: i64,
+ actor: Option<String>,
+) -> SessionId {
+ let id = SessionId::new();
+ store
+ .writer
+ .begin_session(NewSession {
+ id,
+ workspace_id: ws,
+ project_id: proj,
+ ..backdated(at_us, actor)
+ })
+ .await
+ .unwrap();
+ id
+}
+
+fn observation(
+ sid: SessionId,
+ ws: WorkspaceId,
+ proj: ProjectId,
+ kind: ObservationKind,
+ at_us: i64,
+ body: &str,
+) -> NewObservation {
+ NewObservation {
+ session_id: sid,
+ workspace_id: ws,
+ project_id: proj,
+ kind,
+ extension: None,
+ source_event: None,
+ title: "idle test event".into(),
+ body: body.into(),
+ importance: 5,
+ occurred_at: Some(at_us),
+ }
+}
+
+async fn insert(store: &Store, obs: NewObservation) {
+ store
+ .writer
+ .insert_observation(Sanitized::new(obs, &Sanitizer::builtin()))
+ .await
+ .unwrap();
+}
+
+fn substantive(
+ sid: SessionId,
+ ws: WorkspaceId,
+ proj: ProjectId,
+ page: ai_memory_core::PageId,
+ count: i64,
+ now_us: i64,
+ last_activity_us: i64,
+) -> IdleEndCandidate {
+ IdleEndCandidate {
+ session_id: sid,
+ workspace_id: ws,
+ project_id: proj,
+ agent_kind: AgentKind::Codex,
+ action: IdleEndAction::Substantive {
+ expected_page_id: page,
+ observation_count: count,
+ now_us,
+ last_activity_us,
+ },
+ }
+}
+
+fn lifecycle_only(
+ sid: SessionId,
+ ws: WorkspaceId,
+ proj: ProjectId,
+ now_us: i64,
+ last_activity_us: i64,
+) -> IdleEndCandidate {
+ IdleEndCandidate {
+ session_id: sid,
+ workspace_id: ws,
+ project_id: proj,
+ agent_kind: AgentKind::Codex,
+ action: IdleEndAction::LifecycleOnly {
+ now_us,
+ last_activity_us,
+ },
+ }
+}
+
+async fn session_page(
+ store: &Store,
+ ws: WorkspaceId,
+ proj: ProjectId,
+ sid: SessionId,
+) -> ai_memory_core::PageId {
+ store
+ .writer
+ .upsert_page(NewPage {
+ workspace_id: ws,
+ project_id: proj,
+ path: PagePath::new(format!("sessions/{sid}.md")).unwrap(),
+ title: "summary".into(),
+ body: "rule-based summary".into(),
+ tier: Tier::Episodic,
+ frontmatter_json: serde_json::json!({}),
+ pinned: false,
+ links: Vec::new(),
+ author_id: None,
+ expires_at: None,
+ entities: Vec::new(),
+ evidence: Vec::new(),
+ })
+ .await
+ .unwrap()
+}
+
+/// A new version of the session page with distinct body content: the
+/// store's upsert is idempotent for identical content (same version id),
+/// so a "moved latest page" needs a real content change.
+async fn session_page_body(
+ store: &Store,
+ ws: WorkspaceId,
+ proj: ProjectId,
+ sid: SessionId,
+ body: &str,
+) -> ai_memory_core::PageId {
+ store
+ .writer
+ .upsert_page(NewPage {
+ workspace_id: ws,
+ project_id: proj,
+ path: PagePath::new(format!("sessions/{sid}.md")).unwrap(),
+ title: "summary".into(),
+ body: body.into(),
+ tier: Tier::Episodic,
+ frontmatter_json: serde_json::json!({}),
+ pinned: false,
+ links: Vec::new(),
+ author_id: None,
+ expires_at: None,
+ entities: Vec::new(),
+ evidence: Vec::new(),
+ })
+ .await
+ .unwrap()
+}
+
+fn idle_audit_filter() -> AuditLogFilter {
+ AuditLogFilter {
+ workspace: Some("default".into()),
+ project: Some("idle".into()),
+ op: Some("idle_session_end".into()),
+ ..Default::default()
+ }
+}
+
+#[tokio::test]
+async fn idle_selection_is_cutoff_scoped_ordered_and_bounded() {
+ let tmp = tempfile::tempdir().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let (ws, proj) = scope(&store).await;
+ let now = jiff::Timestamp::now().as_microsecond();
+
+ // Idle + substantive: started 10h ago, last activity 9h ago.
+ let old = begin(&store, ws, proj, now - 10 * HOUR_US, None).await;
+ insert(
+ &store,
+ observation(
+ old,
+ ws,
+ proj,
+ ObservationKind::UserPrompt,
+ now - 9 * HOUR_US,
+ "old prompt",
+ ),
+ )
+ .await;
+ // Idle + no observations: last activity falls back to started_at (5h ago).
+ let bare = begin(&store, ws, proj, now - 5 * HOUR_US, None).await;
+ // Active: last activity 1h ago — outside a 2h cutoff.
+ let fresh = begin(&store, ws, proj, now - HOUR_US, None).await;
+ insert(
+ &store,
+ observation(
+ fresh,
+ ws,
+ proj,
+ ObservationKind::UserPrompt,
+ now - HOUR_US,
+ "fresh prompt",
+ ),
+ )
+ .await;
+ // Already ended 7h ago: never a candidate.
+ let ended = begin(&store, ws, proj, now - 8 * HOUR_US, None).await;
+ insert(
+ &store,
+ observation(
+ ended,
+ ws,
+ proj,
+ ObservationKind::UserPrompt,
+ now - 7 * HOUR_US,
+ "ended prompt",
+ ),
+ )
+ .await;
+ store.writer.end_session(ended, None).await.unwrap();
+
+ let cutoff = now - 2 * HOUR_US;
+ let idle = store.reader.idle_open_sessions(cutoff, 25).await.unwrap();
+ let ids: Vec<SessionId> = idle.iter().map(|s| s.session_id).collect();
+ // Oldest last-activity first: the 9h-old session, then the 5h-old bare one.
+ assert_eq!(ids, vec![old, bare]);
+ assert_eq!(
+ idle[0].last_activity_us,
+ now - 9 * HOUR_US,
+ "the watermark is MAX(observations.created_at), not started_at"
+ );
+ assert_eq!(
+ idle[1].last_activity_us,
+ now - 5 * HOUR_US,
+ "a session without observations falls back to started_at"
+ );
+ assert!(idle.iter().all(|s| s.seen_page_id.is_none()));
+
+ // Bounded: a limit of one keeps only the oldest.
+ let first = store.reader.idle_open_sessions(cutoff, 1).await.unwrap();
+ assert_eq!(first.len(), 1);
+ assert_eq!(first[0].session_id, old);
+
+ // The selection also captures each session page's latest version (the
+ // tick's write precondition) from the same statement: a session WITH a
+ // page reports it, a pageless one stays `None`. This also proves the
+ // SQL-rendered path (the id blob's hex with 8-4-4-4-12 hyphens) is
+ // byte-for-byte the Rust `sessions/<id>.md` the page was written at.
+ let page = session_page(&store, ws, proj, old).await;
+ let idle = store.reader.idle_open_sessions(cutoff, 25).await.unwrap();
+ let by_id = |sid: SessionId| idle.iter().find(|s| s.session_id == sid).unwrap();
+ assert_eq!(by_id(old).seen_page_id, Some(page));
+ assert!(by_id(bare).seen_page_id.is_none());
+}
+
+#[tokio::test]
+async fn idle_end_stamps_watermark_audit_page_and_consolidation() {
+ let tmp = tempfile::tempdir().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let (ws, proj) = scope(&store).await;
+ let now = jiff::Timestamp::now().as_microsecond();
+ let watermark = now - 5 * HOUR_US;
+
+ let sid = begin(&store, ws, proj, watermark - HOUR_US, None).await;
+ insert(
+ &store,
+ observation(
+ sid,
+ ws,
+ proj,
+ ObservationKind::UserPrompt,
+ watermark,
+ "idle prompt",
+ ),
+ )
+ .await;
+ let page = session_page(&store, ws, proj, sid).await;
+
+ let results = store
+ .writer
+ .end_idle_sessions(
+ vec![substantive(sid, ws, proj, page, 1, now, watermark)],
+ true,
+ )
+ .await
+ .unwrap();
+ assert_eq!(results, vec![IdleEndResult::EndedSubstantive]);
+
+ // The audit row carries the tick's clock (the auto-improvement discovery
+ // is ordered by `ended_at`, so auto-ended sessions are found in the
+ // order they were ended) — and keeps the last activity next to it.
+ let audits = store
+ .reader
+ .list_audit_events(idle_audit_filter())
+ .await
+ .unwrap();
+ assert_eq!(audits.len(), 1);
+ assert_eq!(audits[0].at, now, "ended_at is the tick's clock");
+ assert!(audits[0].detail.contains(&sid.to_string()));
+ assert!(
+ audits[0].detail.contains(&watermark.to_string()),
+ "the last activity survives in the audit detail: {}",
+ audits[0].detail
+ );
+
+ // A late real SessionEnd with no new work converges against the watermark.
+ let disposition = store
+ .reader
+ .session_end_disposition(sid, ws, proj, AgentKind::Codex)
+ .await
+ .unwrap();
+ assert_eq!(disposition, SessionEndDisposition::AlreadyEnded);
+
+ // The consolidation job is enqueued inside the same command. A fresh
+ // clock: the job's `next_attempt_at` is the enqueue's own `now`.
+ let claimed_now = jiff::Timestamp::now().as_microsecond();
+ let job = store
+ .writer
+ .claim_session_consolidation(claimed_now, claimed_now - 1)
+ .await
+ .unwrap()
+ .expect("the idle end enqueues its consolidation job");
+ assert_eq!(job.session_id(), sid);
+
+ // It is no longer selectable as idle.
+ assert!(
+ store
+ .reader
+ .idle_open_sessions(claimed_now - HOUR_US, 25)
+ .await
+ .unwrap()
+ .is_empty()
+ );
+}
+
+#[tokio::test]
+async fn idle_end_loses_to_an_already_ended_session() {
+ let tmp = tempfile::tempdir().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let (ws, proj) = scope(&store).await;
+ let now = jiff::Timestamp::now().as_microsecond();
+ let watermark = now - 5 * HOUR_US;
+
+ let sid = begin(&store, ws, proj, watermark - HOUR_US, None).await;
+ insert(
+ &store,
+ observation(
+ sid,
+ ws,
+ proj,
+ ObservationKind::UserPrompt,
+ watermark,
+ "worked on it",
+ ),
+ )
+ .await;
+ // The real SessionEnd lands first (its end is now, not the watermark).
+ store.writer.end_session(sid, None).await.unwrap();
+
+ let page = session_page(&store, ws, proj, sid).await;
+ let results = store
+ .writer
+ .end_idle_sessions(
+ vec![substantive(sid, ws, proj, page, 1, now, watermark)],
+ false,
+ )
+ .await
+ .unwrap();
+ // CAS lost: no restamp, no audit, no overwrite of the hook's end.
+ assert_eq!(results, vec![IdleEndResult::Lost]);
+ let audits = store
+ .reader
+ .list_audit_events(AuditLogFilter {
+ op: Some("idle_session_end".into()),
+ ..Default::default()
+ })
+ .await
+ .unwrap();
+ assert!(audits.is_empty(), "a lost end writes no audit row");
+ let disposition = store
+ .reader
+ .session_end_disposition(sid, ws, proj, AgentKind::Codex)
+ .await
+ .unwrap();
+ assert_eq!(disposition, SessionEndDisposition::AlreadyEnded);
+}
+
+#[tokio::test]
+async fn idle_end_reopens_the_handoff_a_lifecycle_only_session_claimed() {
+ let tmp = tempfile::tempdir().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let (ws, proj) = scope(&store).await;
+ let now = jiff::Timestamp::now().as_microsecond();
+ let watermark = now - 4 * HOUR_US;
+
+ // Boundary-only: a start and a stop, no real work.
+ let sid = begin(&store, ws, proj, watermark - HOUR_US, None).await;
+ insert(
+ &store,
+ observation(
+ sid,
+ ws,
+ proj,
+ ObservationKind::Stop,
+ watermark,
+ "turn finished",
+ ),
+ )
+ .await;
+ let handoff = store
+ .writer
+ .insert_handoff(NewHandoff {
+ workspace_id: ws,
+ project_id: proj,
+ from_session_id: None,
+ from_agent: AgentKind::Codex,
+ to_agent: None,
+ cwd: Some("/repo".into()),
+ summary: "pick up the build".into(),
+ open_questions: Vec::new(),
+ next_steps: Vec::new(),
+ files_touched: Vec::new(),
+ owner_user: None,
+ })
+ .await
+ .unwrap();
+ assert!(
+ store
+ .writer
+ .accept_handoff(HandoffAcceptance {
+ handoff_id: handoff,
+ workspace_id: ws,
+ project_id: proj,
+ accepting_agent: AgentKind::Codex,
+ accepting_session: Some(sid),
+ accepting_user: None,
+ owner_filter: OwnerFilter::Any,
+ receiving_cwd: Some("/repo".into()),
+ })
+ .await
+ .unwrap()
+ );
+
+ let results = store
+ .writer
+ .end_idle_sessions(vec![lifecycle_only(sid, ws, proj, now, watermark)], true)
+ .await
+ .unwrap();
+ assert_eq!(results, vec![IdleEndResult::EndedLifecycleOnly]);
+
+ // The claimed baton goes back to the open pool for its owner.
+ let reopened = store.reader.handoff_by_id(handoff).await.unwrap().unwrap();
+ assert_eq!(reopened.lifecycle.state, HandoffState::Open);
+ assert!(reopened.lifecycle.accepted_by_session.is_none());
+
+ // No page, no consolidation job, no new handoff. Fresh clock so the
+ // "no job" claim actually sees due jobs.
+ assert!(
+ store
+ .reader
+ .latest_page_id_by_ids(ws, proj, format!("sessions/{sid}.md"))
+ .await
+ .unwrap()
+ .is_none()
+ );
+ let claimed_now = jiff::Timestamp::now().as_microsecond();
+ assert!(
+ store
+ .writer
+ .claim_session_consolidation(claimed_now, claimed_now - 1)
+ .await
+ .unwrap()
+ .is_none()
+ );
+ // The auto-end audit is its OWN row, distinct from the handoff release's
+ // `release_lifecycle_only_handoff` row: an operator looking for the
+ // automatic end sees exactly one idle_session_end row, with the tick's
+ // clock and the last activity in the detail.
+ let audits = store
+ .reader
+ .list_audit_events(idle_audit_filter())
+ .await
+ .unwrap();
+ assert_eq!(audits.len(), 1, "exactly one idle_session_end row");
+ assert_eq!(audits[0].at, now);
+ assert!(
+ audits[0].detail.contains("lifecycle_only"),
+ "the detail says which kind of idle end this was: {}",
+ audits[0].detail
+ );
+ assert!(
+ audits[0].detail.contains(&watermark.to_string()),
+ "the last activity survives in the audit detail: {}",
+ audits[0].detail
+ );
+ let release_audits = store
+ .reader
+ .list_audit_events(AuditLogFilter {
+ op: Some("release_lifecycle_only_handoff".into()),
+ ..Default::default()
+ })
+ .await
+ .unwrap();
+ assert_eq!(
+ release_audits.len(),
+ 1,
+ "the handoff release keeps its own audit row, distinct from the auto-end"
+ );
+}
+
+#[tokio::test]
+async fn idle_end_lifecycle_only_loses_to_a_substantive_race() {
+ let tmp = tempfile::tempdir().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let (ws, proj) = scope(&store).await;
+ let now = jiff::Timestamp::now().as_microsecond();
+ let watermark = now - 4 * HOUR_US;
+
+ let sid = begin(&store, ws, proj, watermark - HOUR_US, None).await;
+ insert(
+ &store,
+ observation(
+ sid,
+ ws,
+ proj,
+ ObservationKind::Stop,
+ watermark,
+ "turn finished",
+ ),
+ )
+ .await;
+ // Substantive work races in before the atomic end re-check.
+ insert(
+ &store,
+ observation(
+ sid,
+ ws,
+ proj,
+ ObservationKind::UserPrompt,
+ now,
+ "late real work",
+ ),
+ )
+ .await;
+
+ let results = store
+ .writer
+ .end_idle_sessions(vec![lifecycle_only(sid, ws, proj, now, watermark)], true)
+ .await
+ .unwrap();
+ assert_eq!(
+ results,
+ vec![IdleEndResult::Lost],
+ "the atomic re-check must not downgrade substantive work to a boundary-only end"
+ );
+ let disposition = store
+ .reader
+ .session_end_disposition(sid, ws, proj, AgentKind::Codex)
+ .await
+ .unwrap();
+ assert_eq!(disposition, SessionEndDisposition::Open);
+}
+
+#[tokio::test]
+async fn idle_end_watermark_converges_a_late_real_session_end() {
+ let tmp = tempfile::tempdir().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let (ws, proj) = scope(&store).await;
+ let now = jiff::Timestamp::now().as_microsecond();
+ let watermark = now - 5 * HOUR_US;
+
+ let sid = begin(&store, ws, proj, watermark - HOUR_US, None).await;
+ insert(
+ &store,
+ observation(
+ sid,
+ ws,
+ proj,
+ ObservationKind::UserPrompt,
+ watermark,
+ "idle prompt",
+ ),
+ )
+ .await;
+ let page = session_page(&store, ws, proj, sid).await;
+ store
+ .writer
+ .end_idle_sessions(
+ vec![substantive(sid, ws, proj, page, 1, now, watermark)],
+ false,
+ )
+ .await
+ .unwrap();
+ assert_eq!(
+ store
+ .reader
+ .session_end_disposition(sid, ws, proj, AgentKind::Codex)
+ .await
+ .unwrap(),
+ SessionEndDisposition::AlreadyEnded,
+ "no new work since the watermark: the real end is a no-op AlreadyEnded"
+ );
+
+ // New work arrives: the real end re-ends against the old watermark.
+ insert(
+ &store,
+ observation(
+ sid,
+ ws,
+ proj,
+ ObservationKind::UserPrompt,
+ now,
+ "late real work",
+ ),
+ )
+ .await;
+ assert_eq!(
+ store
+ .reader
+ .session_end_disposition(sid, ws, proj, AgentKind::Codex)
+ .await
+ .unwrap(),
+ SessionEndDisposition::ReEndWithNewWork
+ );
+ store.writer.end_session(sid, None).await.unwrap();
+ assert_eq!(
+ store
+ .reader
+ .session_end_disposition(sid, ws, proj, AgentKind::Codex)
+ .await
+ .unwrap(),
+ SessionEndDisposition::AlreadyEnded,
+ "the watermark moved with the re-end"
+ );
+}
+
+#[tokio::test]
+async fn idle_end_batch_stamps_every_candidate_in_one_command() {
+ let tmp = tempfile::tempdir().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let (ws, proj) = scope(&store).await;
+ let now = jiff::Timestamp::now().as_microsecond();
+
+ let mut candidates = Vec::new();
+ for i in 0..25u32 {
+ let watermark = now - (i as i64 + 1) * HOUR_US;
+ let sid = begin(&store, ws, proj, watermark - HOUR_US, None).await;
+ insert(
+ &store,
+ observation(
+ sid,
+ ws,
+ proj,
+ ObservationKind::UserPrompt,
+ watermark,
+ &format!("prompt {i}"),
+ ),
+ )
+ .await;
+ let page = session_page(&store, ws, proj, sid).await;
+ // The 13th candidate is already ended: it must report Lost in batch.
+ if i == 12 {
+ store.writer.end_session(sid, None).await.unwrap();
+ }
+ candidates.push(substantive(sid, ws, proj, page, 1, now, watermark));
+ }
+ let results = store
+ .writer
+ .end_idle_sessions(candidates, false)
+ .await
+ .unwrap();
+ assert_eq!(results.len(), 25);
+ let ended = results
+ .iter()
+ .filter(|r| matches!(r, IdleEndResult::EndedSubstantive))
+ .count();
+ let lost = results
+ .iter()
+ .filter(|r| matches!(r, IdleEndResult::Lost))
+ .count();
+ assert_eq!(ended, 24);
+ assert_eq!(lost, 1);
+ assert_eq!(results[12], IdleEndResult::Lost);
+ // enqueue=false: no consolidation job was created by any of the ends.
+ let claimed_now = jiff::Timestamp::now().as_microsecond();
+ assert!(
+ store
+ .writer
+ .claim_session_consolidation(claimed_now, claimed_now - 1)
+ .await
+ .unwrap()
+ .is_none()
+ );
+}
+
+#[tokio::test]
+async fn idle_end_candidate_cannot_cross_the_project_boundary() {
+ let tmp = tempfile::tempdir().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let (ws, proj) = scope(&store).await;
+ let other = store
+ .writer
+ .get_or_create_project(ws, "other", None)
+ .await
+ .unwrap();
+ let now = jiff::Timestamp::now().as_microsecond();
+ let watermark = now - 5 * HOUR_US;
+
+ let sid = begin(&store, ws, proj, watermark - HOUR_US, None).await;
+ insert(
+ &store,
+ observation(
+ sid,
+ ws,
+ proj,
+ ObservationKind::UserPrompt,
+ watermark,
+ "idle prompt",
+ ),
+ )
+ .await;
+ let page = session_page(&store, ws, proj, sid).await;
+ // A candidate that names the wrong project must lose the CAS even though
+ // the session id is otherwise valid (the stamp never trusts a caller-
+ // provided id alone).
+ let results = store
+ .writer
+ .end_idle_sessions(
+ vec![substantive(sid, ws, other, page, 1, now, watermark)],
+ false,
+ )
+ .await
+ .unwrap();
+ assert_eq!(results, vec![IdleEndResult::Lost]);
+ let disposition = store
+ .reader
+ .session_end_disposition(sid, ws, proj, AgentKind::Codex)
+ .await
+ .unwrap();
+ assert_eq!(disposition, SessionEndDisposition::Open);
+ // Same-scope control: the identical candidate named at the session's
+ // real project ends it — the refusal above was the scope guard, not the
+ // session itself.
+ let results = store
+ .writer
+ .end_idle_sessions(
+ vec![substantive(sid, ws, proj, page, 1, now, watermark)],
+ false,
+ )
+ .await
+ .unwrap();
+ assert_eq!(results, vec![IdleEndResult::EndedSubstantive]);
+ let disposition = store
+ .reader
+ .session_end_disposition(sid, ws, proj, AgentKind::Codex)
+ .await
+ .unwrap();
+ assert_eq!(disposition, SessionEndDisposition::AlreadyEnded);
+}
+
+#[tokio::test]
+async fn idle_end_cas_rejects_a_stale_observation_count() {
+ let tmp = tempfile::tempdir().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let (ws, proj) = scope(&store).await;
+ let now = jiff::Timestamp::now().as_microsecond();
+ let watermark = now - 5 * HOUR_US;
+
+ let sid = begin(&store, ws, proj, watermark - HOUR_US, None).await;
+ insert(
+ &store,
+ observation(
+ sid,
+ ws,
+ proj,
+ ObservationKind::UserPrompt,
+ watermark,
+ "idle prompt",
+ ),
+ )
+ .await;
+ let page = session_page(&store, ws, proj, sid).await;
+ // The candidate was built from a digest that saw exactly one
+ // observation. A non-end observation lands after that read (the window
+ // between the tick's read and the stamp): the count guard must refuse
+ // the stamp, or the watermark would cover work the page never saw.
+ insert(
+ &store,
+ observation(
+ sid,
+ ws,
+ proj,
+ ObservationKind::UserPrompt,
+ now,
+ "late work the page never saw",
+ ),
+ )
+ .await;
+ let results = store
+ .writer
+ .end_idle_sessions(
+ vec![substantive(sid, ws, proj, page, 1, now, watermark)],
+ false,
+ )
+ .await
+ .unwrap();
+ assert_eq!(
+ results,
+ vec![IdleEndResult::Lost],
+ "an observation after the digest read must lose the CAS"
+ );
+ let audits = store
+ .reader
+ .list_audit_events(idle_audit_filter())
+ .await
+ .unwrap();
+ assert!(audits.is_empty(), "a lost end writes no audit row");
+ assert_eq!(
+ store
+ .reader
+ .session_end_disposition(sid, ws, proj, AgentKind::Codex)
+ .await
+ .unwrap(),
+ SessionEndDisposition::Open,
+ "the session stays open: the next tick re-reads the digest and the count"
+ );
+}
+
+#[tokio::test]
+async fn idle_end_cas_rejects_a_moved_latest_page() {
+ let tmp = tempfile::tempdir().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let (ws, proj) = scope(&store).await;
+ let now = jiff::Timestamp::now().as_microsecond();
+ let watermark = now - 5 * HOUR_US;
+
+ let sid = begin(&store, ws, proj, watermark - HOUR_US, None).await;
+ insert(
+ &store,
+ observation(
+ sid,
+ ws,
+ proj,
+ ObservationKind::UserPrompt,
+ watermark,
+ "idle prompt",
+ ),
+ )
+ .await;
+ let page_v1 = session_page(&store, ws, proj, sid).await;
+ // A checkpoint (or the real SessionEnd) lands a newer page version
+ // after the tick wrote v1. Stamping v1 would point summary_page_id at a
+ // page that no longer represents the session's work: the latest-version
+ // guard must refuse.
+ let page_v2 = session_page_body(&store, ws, proj, sid, "checkpoint v2, new content").await;
+ assert_ne!(page_v1, page_v2);
+ let results = store
+ .writer
+ .end_idle_sessions(
+ vec![substantive(sid, ws, proj, page_v1, 1, now, watermark)],
+ false,
+ )
+ .await
+ .unwrap();
+ assert_eq!(
+ results,
+ vec![IdleEndResult::Lost],
+ "a newer page version must lose the CAS"
+ );
+ let audits = store
+ .reader
+ .list_audit_events(idle_audit_filter())
+ .await
+ .unwrap();
+ assert!(audits.is_empty(), "a lost end writes no audit row");
+ assert_eq!(
+ store
+ .reader
+ .session_end_disposition(sid, ws, proj, AgentKind::Codex)
+ .await
+ .unwrap(),
+ SessionEndDisposition::Open,
+ "the session stays open for the next tick"
+ );
+}
+
+#[tokio::test]
+async fn idle_end_consolidation_enqueue_shares_the_callers_transaction() {
+ let tmp = tempfile::tempdir().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let (ws, proj) = scope(&store).await;
+ let now = jiff::Timestamp::now().as_microsecond();
+ let watermark = now - 5 * HOUR_US;
+
+ let sid = begin(&store, ws, proj, watermark - HOUR_US, None).await;
+ insert(
+ &store,
+ observation(
+ sid,
+ ws,
+ proj,
+ ObservationKind::UserPrompt,
+ watermark,
+ "idle prompt",
+ ),
+ )
+ .await;
+ store.writer.end_session(sid, None).await.unwrap();
+
+ // The idle stamp enqueues its consolidation job INSIDE the stamp's
+ // transaction: the enqueue must live or die with the caller's commit.
+ // Prove the rollback side — a failing caller statement discards the
+ // enqueue with everything else in the transaction.
+ let mut conn = rusqlite::Connection::open(tmp.path().join("db").join("memory.sqlite")).unwrap();
+ let tx = conn.transaction().unwrap();
+ ai_memory_store::session_consolidation::enqueue_in_tx(&tx, ws, proj, sid).unwrap();
+ // The job is visible to the caller's transaction...
+ let visible: i64 = tx
+ .query_row(
+ "SELECT COUNT(*) FROM session_consolidation_jobs WHERE session_id = ?1",
+ rusqlite::params![sid.as_bytes()],
+ |row| row.get(0),
+ )
+ .unwrap();
+ assert_eq!(visible, 1);
+ // ...and a failing statement rolls the whole transaction back.
+ let failed = tx.execute("INSERT INTO no_such_table VALUES (1)", []);
+ assert!(failed.is_err(), "the caller's failure");
+ drop(tx);
+ let rows: i64 = conn
+ .query_row(
+ "SELECT COUNT(*) FROM session_consolidation_jobs WHERE session_id = ?1",
+ rusqlite::params![sid.as_bytes()],
+ |row| row.get(0),
+ )
+ .unwrap();
+ assert_eq!(
+ rows, 0,
+ "a failed caller command discards the enqueue: the session stays \
+ enqueuable, the next tick retries"
+ );
+}
+
+#[tokio::test]
+async fn idle_end_pre_stamp_non_end_observation_in_window_loses_the_cas() {
+ let tmp = tempfile::tempdir().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let (ws, proj) = scope(&store).await;
+ let now = jiff::Timestamp::now().as_microsecond();
+ let watermark = now - 5 * HOUR_US;
+
+ let sid = begin(&store, ws, proj, watermark - HOUR_US, None).await;
+ insert(
+ &store,
+ observation(
+ sid,
+ ws,
+ proj,
+ ObservationKind::UserPrompt,
+ watermark,
+ "idle prompt",
+ ),
+ )
+ .await;
+ let page = session_page(&store, ws, proj, sid).await;
+
+ // The test-only seam races a non-end observation (a `Stop` marker) into
+ // the window between the tick's digest read and the stamp: the count
+ // guard must lose the CAS, or the watermark would cover work the page
+ // never saw. Enqueue is ON: a lost candidate must still create no job.
+ let results = store
+ .writer
+ .end_idle_sessions_pre_stamp(
+ vec![substantive(sid, ws, proj, page, 1, now, watermark)],
+ true,
+ Box::new(move |conn| { conn.execute(
+ "INSERT INTO observations \
+ (id, session_id, workspace_id, project_id, kind, title, body, importance, created_at) \
+ VALUES (?1, ?2, ?3, ?4, 'stop', 'window stop', 'a non-end observation in the window', 5, ?5)",
+ rusqlite::params![
+ uuid::Uuid::new_v4().as_bytes(),
+ sid.as_bytes(),
+ ws.as_bytes(),
+ proj.as_bytes(),
+ now
+ ],
+ )
+ .unwrap();
+ }),
+ )
+ .await
+ .unwrap();
+ assert_eq!(results, vec![IdleEndResult::Lost]);
+ let audits = store
+ .reader
+ .list_audit_events(idle_audit_filter())
+ .await
+ .unwrap();
+ assert!(audits.is_empty(), "a lost end writes no audit row");
+ assert_eq!(
+ store
+ .reader
+ .session_end_disposition(sid, ws, proj, AgentKind::Codex)
+ .await
+ .unwrap(),
+ SessionEndDisposition::Open,
+ "the session stays open for the next tick"
+ );
+ // Lost with consolidation enabled: the enqueue is skipped, not half-done.
+ let claimed_now = jiff::Timestamp::now().as_microsecond();
+ assert!(
+ store
+ .writer
+ .claim_session_consolidation(claimed_now, claimed_now - 1)
+ .await
+ .unwrap()
+ .is_none(),
+ "a lost candidate with enqueue on creates no job"
+ );
+}
+
+#[tokio::test]
+async fn idle_end_pre_stamp_checkpoint_page_in_window_loses_the_cas() {
+ let tmp = tempfile::tempdir().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let (ws, proj) = scope(&store).await;
+ let now = jiff::Timestamp::now().as_microsecond();
+ let watermark = now - 5 * HOUR_US;
+
+ let sid = begin(&store, ws, proj, watermark - HOUR_US, None).await;
+ insert(
+ &store,
+ observation(
+ sid,
+ ws,
+ proj,
+ ObservationKind::UserPrompt,
+ watermark,
+ "idle prompt",
+ ),
+ )
+ .await;
+ let page_v1 = session_page(&store, ws, proj, sid).await;
+
+ // The seam races a checkpoint page version (a new latest row supersedes
+ // v1) into the window: the latest-version guard must lose the CAS, or
+ // summary_page_id would point at a page that no longer represents the
+ // session's work.
+ let results = store
+ .writer
+ .end_idle_sessions_pre_stamp(
+ vec![substantive(sid, ws, proj, page_v1, 1, now, watermark)],
+ false,
+ Box::new(move |conn| {
+ let body = "checkpoint v2 landing in the window";
+ use sha2::Digest;
+ let mut hasher = sha2::Sha256::default();
+ hasher.update(body.as_bytes());
+ let sha: [u8; 32] = hasher.finalize().into();
+ conn.execute(
+ "UPDATE pages SET is_latest = 0 WHERE id = ?1",
+ rusqlite::params![page_v1.as_bytes()],
+ )
+ .unwrap();
+ conn.execute(
+ "INSERT INTO pages \
+ (id, workspace_id, project_id, path, path_search, title, tier, body, \
+ body_sha256, frontmatter_json, is_latest, supersedes, pinned, author_id, \
+ created_at, updated_at, expires_at, valid_from, compacted_at) \
+ VALUES (?1, ?2, ?3, ?4, ?4, 'summary', 'episodic', ?5, ?6, '{}', 1, ?7, 0, NULL, ?8, ?8, NULL, ?8, NULL)",
+ rusqlite::params![
+ uuid::Uuid::new_v4().as_bytes(),
+ ws.as_bytes(),
+ proj.as_bytes(),
+ format!("sessions/{sid}.md"),
+ body,
+ sha,
+ page_v1.as_bytes(),
+ now
+ ],
+ )
+ .unwrap();
+ }),
+ )
+ .await
+ .unwrap();
+ assert_eq!(
+ results,
+ vec![IdleEndResult::Lost],
+ "a newer page version landing in the window must lose the stamp"
+ );
+ let audits = store
+ .reader
+ .list_audit_events(idle_audit_filter())
+ .await
+ .unwrap();
+ assert!(audits.is_empty(), "a lost end writes no audit row");
+ assert_eq!(
+ store
+ .reader
+ .session_end_disposition(sid, ws, proj, AgentKind::Codex)
+ .await
+ .unwrap(),
+ SessionEndDisposition::Open,
+ "the session stays open: the next tick re-reads and the checkpoint wins"
+ );
+}
+
+#[tokio::test]
+async fn idle_end_pre_stamp_real_session_end_in_window_loses_the_cas() {
+ let tmp = tempfile::tempdir().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let (ws, proj) = scope(&store).await;
+ let now = jiff::Timestamp::now().as_microsecond();
+ let watermark = now - 5 * HOUR_US;
+ let hook_end_us = now - HOUR_US / 2;
+
+ let sid = begin(&store, ws, proj, watermark - HOUR_US, None).await;
+ insert(
+ &store,
+ observation(
+ sid,
+ ws,
+ proj,
+ ObservationKind::UserPrompt,
+ watermark,
+ "idle prompt",
+ ),
+ )
+ .await;
+ let page = session_page(&store, ws, proj, sid).await;
+
+ // The seam stamps the session exactly the way a real SessionEnd's hook
+ // path does (ended_at + the live observation count): the `ended_at IS
+ // NULL` guard must lose the CAS and the hook's end keeps the row.
+ let results = store
+ .writer
+ .end_idle_sessions_pre_stamp(
+ vec![substantive(sid, ws, proj, page, 1, now, watermark)],
+ true,
+ Box::new(move |conn| {
+ conn.execute(
+ "UPDATE sessions SET ended_at = ?1, \
+ ended_observation_count = (SELECT COUNT(*) FROM observations WHERE session_id = ?2) \
+ WHERE id = ?2",
+ rusqlite::params![hook_end_us, sid.as_bytes()],
+ )
+ .unwrap();
+ }),
+ )
+ .await
+ .unwrap();
+ assert_eq!(results, vec![IdleEndResult::Lost]);
+ let audits = store
+ .reader
+ .list_audit_events(idle_audit_filter())
+ .await
+ .unwrap();
+ assert!(audits.is_empty(), "a lost end writes no audit row");
+ // The hook's end is untouched: no idle restamp, no idle-enqueue job.
+ assert_eq!(
+ store
+ .reader
+ .session_end_disposition(sid, ws, proj, AgentKind::Codex)
+ .await
+ .unwrap(),
+ SessionEndDisposition::AlreadyEnded
+ );
+ let claimed_now = jiff::Timestamp::now().as_microsecond();
+ assert!(
+ store
+ .writer
+ .claim_session_consolidation(claimed_now, claimed_now - 1)
+ .await
+ .unwrap()
+ .is_none(),
+ "the lost candidate never enqueues; the hook path owns the job"
+ );
+}
+
+#[tokio::test]
+async fn idle_end_consolidation_enqueue_failure_rolls_back_and_retries() {
+ let tmp = tempfile::tempdir().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let (ws, proj) = scope(&store).await;
+ let now = jiff::Timestamp::now().as_microsecond();
+ let watermark = now - 5 * HOUR_US;
+
+ let sid = begin(&store, ws, proj, watermark - HOUR_US, None).await;
+ insert(
+ &store,
+ observation(
+ sid,
+ ws,
+ proj,
+ ObservationKind::UserPrompt,
+ watermark,
+ "idle prompt",
+ ),
+ )
+ .await;
+ let page = session_page(&store, ws, proj, sid).await;
+
+ // F6: the consolidation enqueue runs INSIDE the stamp's transaction.
+ // A test-only trigger aborts the job INSERT: the whole command — stamp,
+ // audit, enqueue — must roll back and the session stay open.
+ let failed = store
+ .writer
+ .end_idle_sessions_pre_stamp(
+ vec![substantive(sid, ws, proj, page, 1, now, watermark)],
+ true,
+ Box::new(|conn| {
+ conn.execute(
+ "CREATE TRIGGER idle_f6_abort \
+ BEFORE INSERT ON session_consolidation_jobs \
+ BEGIN SELECT RAISE(ABORT, 'f6 test trigger'); END",
+ [],
+ )
+ .unwrap();
+ }),
+ )
+ .await;
+ assert!(
+ failed.is_err(),
+ "the aborted enqueue must fail the whole command"
+ );
+ assert_eq!(
+ store
+ .reader
+ .session_end_disposition(sid, ws, proj, AgentKind::Codex)
+ .await
+ .unwrap(),
+ SessionEndDisposition::Open,
+ "the stamp rolled back with the enqueue: the session stays open"
+ );
+ let audits = store
+ .reader
+ .list_audit_events(idle_audit_filter())
+ .await
+ .unwrap();
+ assert!(
+ audits.is_empty(),
+ "the audit row rolled back with the enqueue: {}",
+ audits
+ .iter()
+ .map(|e| e.op.clone())
+ .collect::<Vec<_>>()
+ .join(", ")
+ );
+ let claimed_now = jiff::Timestamp::now().as_microsecond();
+ assert!(
+ store
+ .writer
+ .claim_session_consolidation(claimed_now, claimed_now - 1)
+ .await
+ .unwrap()
+ .is_none(),
+ "no half-enqueued job survives the rollback"
+ );
+
+ // The next pass (trigger removed) ends the session and enqueues.
+ let results = store
+ .writer
+ .end_idle_sessions_pre_stamp(
+ vec![substantive(sid, ws, proj, page, 1, now, watermark)],
+ true,
+ Box::new(|conn| {
+ conn.execute("DROP TRIGGER idle_f6_abort", []).unwrap();
+ }),
+ )
+ .await
+ .unwrap();
+ assert_eq!(results, vec![IdleEndResult::EndedSubstantive]);
+ // Fresh wall clock: the retried pass's enqueue used its own .
+ let fresh = jiff::Timestamp::now().as_microsecond();
+ let job = store
+ .writer
+ .claim_session_consolidation(fresh + 1_000, fresh)
+ .await
+ .unwrap()
+ .expect("the retried pass enqueues its consolidation job");
+ assert_eq!(job.session_id(), sid);
+}
+
+#[tokio::test]
+async fn idle_end_lifecycle_only_refuses_a_foreign_scope_candidate() {
+ let tmp = tempfile::tempdir().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let (ws, proj) = scope(&store).await;
+ let other = store
+ .writer
+ .get_or_create_project(ws, "other", None)
+ .await
+ .unwrap();
+ let now = jiff::Timestamp::now().as_microsecond();
+ let watermark = now - 4 * HOUR_US;
+
+ // Boundary-only session in `proj`, with a handoff it claimed.
+ let sid = begin(&store, ws, proj, watermark - HOUR_US, None).await;
+ insert(
+ &store,
+ observation(
+ sid,
+ ws,
+ proj,
+ ObservationKind::Stop,
+ watermark,
+ "turn finished",
+ ),
+ )
+ .await;
+ let handoff = store
+ .writer
+ .insert_handoff(NewHandoff {
+ workspace_id: ws,
+ project_id: proj,
+ from_session_id: None,
+ from_agent: AgentKind::Codex,
+ to_agent: None,
+ cwd: Some("/repo".into()),
+ summary: "pick up the build".into(),
+ open_questions: Vec::new(),
+ next_steps: Vec::new(),
+ files_touched: Vec::new(),
+ owner_user: None,
+ })
+ .await
+ .unwrap();
+ assert!(
+ store
+ .writer
+ .accept_handoff(HandoffAcceptance {
+ handoff_id: handoff,
+ workspace_id: ws,
+ project_id: proj,
+ accepting_agent: AgentKind::Codex,
+ accepting_session: Some(sid),
+ accepting_user: None,
+ owner_filter: OwnerFilter::Any,
+ receiving_cwd: Some("/repo".into()),
+ })
+ .await
+ .unwrap()
+ );
+
+ // A lifecycle-only candidate naming the WRONG project must lose before
+ // any mutation or handoff release — even though the session id is
+ // otherwise valid (the end ops key on the id alone; the guard is what
+ // makes scope matter).
+ let results = store
+ .writer
+ .end_idle_sessions(vec![lifecycle_only(sid, ws, other, now, watermark)], true)
+ .await
+ .unwrap();
+ assert_eq!(results, vec![IdleEndResult::Lost]);
+ assert_ne!(
+ store
+ .reader
+ .session_end_disposition(sid, ws, proj, AgentKind::Codex)
+ .await
+ .unwrap(),
+ SessionEndDisposition::AlreadyEnded,
+ "the foreign-scope candidate ends nothing"
+ );
+ // The claimed handoff is untouched: the release belongs to the real
+ // scope's end, not a foreign candidate's.
+ let still = store.reader.handoff_by_id(handoff).await.unwrap().unwrap();
+ assert_eq!(
+ still.lifecycle.state,
+ HandoffState::Accepted,
+ "the handoff stays claimed for its real owner"
+ );
+ let audits = store
+ .reader
+ .list_audit_events(idle_audit_filter())
+ .await
+ .unwrap();
+ assert!(audits.is_empty(), "a lost end writes no audit row");
+}
+
+/// R36b-1: the CAS count guard must count the SAME population as the digest
+/// and `session_observation_count` — every observation of the validated
+/// session, whatever project each row landed in. A session that carried work
+/// into another project must end, not spin as `Lost` forever.
+#[tokio::test]
+async fn idle_end_counts_the_same_observation_population_as_the_digest() {
+ let tmp = tempfile::tempdir().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let (ws, proj) = scope(&store).await;
+ let other = store
+ .writer
+ .get_or_create_project(ws, "other-count", None)
+ .await
+ .unwrap();
+ let now = jiff::Timestamp::now().as_microsecond();
+ let watermark = now - 5 * HOUR_US;
+
+ let sid = begin(&store, ws, proj, watermark - HOUR_US, None).await;
+ insert(
+ &store,
+ observation(
+ sid,
+ ws,
+ proj,
+ ObservationKind::UserPrompt,
+ watermark,
+ "home scope",
+ ),
+ )
+ .await;
+ // The session keeps its id when its work lands in another project:
+ // the second observation carries the other project's coordinates.
+ insert(
+ &store,
+ observation(
+ sid,
+ ws,
+ other,
+ ObservationKind::PostToolUse,
+ watermark,
+ "moved scope",
+ ),
+ )
+ .await;
+ let page = session_page(&store, ws, proj, sid).await;
+ // The production counter sees the whole session population...
+ let count = store
+ .reader
+ .session_observation_count(ws, proj, sid)
+ .await
+ .unwrap();
+ assert_eq!(
+ count, 2,
+ "the counter counts every row of the validated session"
+ );
+ // ...so the stamp must accept the candidate without any race.
+ let results = store
+ .writer
+ .end_idle_sessions(
+ vec![substantive(sid, ws, proj, page, count, now, watermark)],
+ false,
+ )
+ .await
+ .unwrap();
+ assert_eq!(
+ results,
+ vec![IdleEndResult::EndedSubstantive],
+ "digest/counter and CAS count the same population; nothing raced"
+ );
+ // The watermark covers BOTH observations, not only the in-scope row.
+ let conn = rusqlite::Connection::open(tmp.path().join("db").join("memory.sqlite")).unwrap();
+ let ended_count: i64 = conn
+ .query_row(
+ "SELECT COALESCE(ended_observation_count, -1) FROM sessions WHERE id = ?1",
+ rusqlite::params![sid.as_bytes()],
+ |row| row.get(0),
+ )
+ .unwrap();
+ assert_eq!(
+ ended_count, 2,
+ "the watermark counts the whole session population"
+ );
+}
+
+/// R36b-3: the raw-id reader refuses foreign workspaces, foreign projects
+/// and missing session ids with a zero count — and returns the count for
+/// the right tuple (legitimate control in the same fixture).
+#[tokio::test]
+async fn session_observation_count_refuses_foreign_and_missing_scopes() {
+ let tmp = tempfile::tempdir().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let (ws, proj) = scope(&store).await;
+ let other = store
+ .writer
+ .get_or_create_project(ws, "other-count", None)
+ .await
+ .unwrap();
+ let foreign_ws = store
+ .writer
+ .get_or_create_workspace("foreign".to_string())
+ .await
+ .unwrap();
+ let now = jiff::Timestamp::now().as_microsecond();
+ let watermark = now - 5 * HOUR_US;
+
+ let sid = begin(&store, ws, proj, watermark - HOUR_US, None).await;
+ for body in ["first", "second"] {
+ insert(
+ &store,
+ observation(sid, ws, proj, ObservationKind::UserPrompt, watermark, body),
+ )
+ .await;
+ }
+ let reader = store.reader.clone();
+ // Legitimate control: the right tuple returns the count.
+ assert_eq!(
+ reader
+ .session_observation_count(ws, proj, sid)
+ .await
+ .unwrap(),
+ 2
+ );
+ // Violations: a foreign project, a foreign workspace, a missing id —
+ // each counts nothing the session does not own in that scope.
+ assert_eq!(
+ reader
+ .session_observation_count(ws, other, sid)
+ .await
+ .unwrap(),
+ 0,
+ "a foreign project counts no rows of the session"
+ );
+ assert_eq!(
+ reader
+ .session_observation_count(foreign_ws, proj, sid)
+ .await
+ .unwrap(),
+ 0,
+ "a foreign workspace counts no rows of the session"
+ );
+ assert_eq!(
+ reader
+ .session_observation_count(ws, proj, SessionId::new())
+ .await
+ .unwrap(),
+ 0,
+ "a missing id counts nothing"
+ );
+}
+
+/// R36b-3: `enqueue_in_tx` refuses a foreign tuple — it enqueues nothing
+/// and leaves the foreign project's queue exactly as it was — while the
+/// right tuple enqueues (legitimate control in the same fixture).
+#[tokio::test]
+async fn enqueue_in_tx_refuses_a_foreign_scope_and_leaves_the_foreign_queue() {
+ let tmp = tempfile::tempdir().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let (ws, proj) = scope(&store).await;
+ let other = store
+ .writer
+ .get_or_create_project(ws, "other-count", None)
+ .await
+ .unwrap();
+ let now = jiff::Timestamp::now().as_microsecond();
+ let watermark = now - 5 * HOUR_US;
+
+ // The session the foreign candidate will name: ended, with work.
+ let sid = begin(&store, ws, proj, watermark - HOUR_US, None).await;
+ insert(
+ &store,
+ observation(
+ sid,
+ ws,
+ proj,
+ ObservationKind::UserPrompt,
+ watermark,
+ "work to consolidate",
+ ),
+ )
+ .await;
+ // The foreign project's own ended session and its job: the baseline the
+ // foreign attempt must not disturb.
+ let sid_other = begin(&store, ws, other, watermark - HOUR_US, None).await;
+ insert(
+ &store,
+ observation(
+ sid_other,
+ ws,
+ other,
+ ObservationKind::UserPrompt,
+ watermark,
+ "foreign project work",
+ ),
+ )
+ .await;
+ let mut conn = rusqlite::Connection::open(tmp.path().join("db").join("memory.sqlite")).unwrap();
+ {
+ let tx = conn.transaction().unwrap();
+ // Both sessions end inside the baseline transaction FIRST: the job
+ // INSERT needs `ended_at IS NOT NULL`.
+ for id in [sid, sid_other] {
+ tx.execute(
+ "UPDATE sessions SET ended_at = ?1, \
+ ended_observation_count = (SELECT COUNT(*) FROM observations WHERE session_id = ?2) \
+ WHERE id = ?2",
+ rusqlite::params![now, id.as_bytes()],
+ )
+ .unwrap();
+ }
+ ai_memory_store::session_consolidation::enqueue_in_tx(&tx, ws, other, sid_other).unwrap();
+ tx.commit().unwrap();
+ }
+ let queue_of = |conn: &rusqlite::Connection, ws: WorkspaceId, proj: ProjectId| -> i64 {
+ conn.query_row(
+ "SELECT COUNT(*) FROM session_consolidation_jobs \
+ WHERE workspace_id = ?1 AND project_id = ?2",
+ rusqlite::params![ws.as_bytes(), proj.as_bytes()],
+ |row| row.get(0),
+ )
+ .unwrap()
+ };
+ let jobs_for = |conn: &rusqlite::Connection, id: SessionId| -> i64 {
+ conn.query_row(
+ "SELECT COUNT(*) FROM session_consolidation_jobs WHERE session_id = ?1",
+ rusqlite::params![id.as_bytes()],
+ |row| row.get(0),
+ )
+ .unwrap()
+ };
+ let baseline_other = queue_of(&conn, ws, other);
+ assert_eq!(baseline_other, 1, "the foreign project's baseline job");
+
+ // Violation: the session's real scope is `proj`, but the candidate
+ // names `other`. Nothing may be enqueued anywhere.
+ {
+ let tx = conn.transaction().unwrap();
+ let enqueued =
+ ai_memory_store::session_consolidation::enqueue_in_tx(&tx, ws, other, sid).unwrap();
+ assert!(!enqueued, "the foreign tuple enqueues nothing");
+ tx.commit().unwrap();
+ }
+ assert_eq!(
+ jobs_for(&conn, sid),
+ 0,
+ "no job appeared for the session in any project"
+ );
+ assert_eq!(
+ queue_of(&conn, ws, other),
+ baseline_other,
+ "the foreign project's queue is unchanged"
+ );
+ assert_eq!(
+ queue_of(&conn, ws, proj),
+ 0,
+ "the real scope got no job either"
+ );
+
+ // Legitimate control: the right tuple enqueues.
+ {
+ let tx = conn.transaction().unwrap();
+ let enqueued =
+ ai_memory_store::session_consolidation::enqueue_in_tx(&tx, ws, proj, sid).unwrap();
+ assert!(enqueued, "the right tuple enqueues");
+ tx.commit().unwrap();
+ }
+ assert_eq!(jobs_for(&conn, sid), 1);
+}
+
+/// R36b-3 (lifecycle-only arm): a dedicated already-ended case returns
+/// `Lost` with no audit and no handoff release — next to its own
+/// legitimate control in the same fixture, which ends and releases.
+#[tokio::test]
+async fn idle_end_lifecycle_only_refuses_an_already_ended_session_with_control() {
+ async fn claimed_handoff(
+ store: &Store,
+ ws: WorkspaceId,
+ proj: ProjectId,
+ sid: SessionId,
+ ) -> HandoffId {
+ let handoff = store
+ .writer
+ .insert_handoff(NewHandoff {
+ workspace_id: ws,
+ project_id: proj,
+ from_session_id: None,
+ from_agent: AgentKind::Codex,
+ to_agent: None,
+ cwd: Some("/repo".into()),
+ summary: "pick up the build".into(),
+ open_questions: Vec::new(),
+ next_steps: Vec::new(),
+ files_touched: Vec::new(),
+ owner_user: None,
+ })
+ .await
+ .unwrap();
+ assert!(
+ store
+ .writer
+ .accept_handoff(HandoffAcceptance {
+ handoff_id: handoff,
+ workspace_id: ws,
+ project_id: proj,
+ accepting_agent: AgentKind::Codex,
+ accepting_session: Some(sid),
+ accepting_user: None,
+ owner_filter: OwnerFilter::Any,
+ receiving_cwd: Some("/repo".into()),
+ })
+ .await
+ .unwrap()
+ );
+ handoff
+ }
+
+ let tmp = tempfile::tempdir().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let (ws, proj) = scope(&store).await;
+ let now = jiff::Timestamp::now().as_microsecond();
+ let watermark = now - 4 * HOUR_US;
+
+ // A: boundary-only, already ended by the hook path, handoff claimed.
+ let sid_a = begin(&store, ws, proj, watermark - HOUR_US, None).await;
+ insert(
+ &store,
+ observation(
+ sid_a,
+ ws,
+ proj,
+ ObservationKind::Stop,
+ watermark,
+ "A's turn finished",
+ ),
+ )
+ .await;
+ let handoff_a = claimed_handoff(&store, ws, proj, sid_a).await;
+ // B: the open control, the same shape.
+ let sid_b = begin(&store, ws, proj, watermark - HOUR_US, None).await;
+ insert(
+ &store,
+ observation(
+ sid_b,
+ ws,
+ proj,
+ ObservationKind::Stop,
+ watermark,
+ "B's turn finished",
+ ),
+ )
+ .await;
+ let handoff_b = claimed_handoff(&store, ws, proj, sid_b).await;
+
+ // The hook path ended A first (not the tick): ended_at + watermark.
+ {
+ let conn = rusqlite::Connection::open(tmp.path().join("db").join("memory.sqlite")).unwrap();
+ conn.execute(
+ "UPDATE sessions SET ended_at = ?1, \
+ ended_observation_count = (SELECT COUNT(*) FROM observations WHERE session_id = ?2) \
+ WHERE id = ?2",
+ rusqlite::params![now, sid_a.as_bytes()],
+ )
+ .unwrap();
+ }
+
+ // One tick command: A is refused by the scope/open guard, B ends.
+ let results = store
+ .writer
+ .end_idle_sessions(
+ vec![
+ lifecycle_only(sid_a, ws, proj, now, watermark),
+ lifecycle_only(sid_b, ws, proj, now, watermark),
+ ],
+ true,
+ )
+ .await
+ .unwrap();
+ assert_eq!(
+ results,
+ vec![IdleEndResult::Lost, IdleEndResult::EndedLifecycleOnly],
+ "the already-ended case loses; the control ends"
+ );
+ // A's claimed handoff is untouched: the release belongs to a live end.
+ let handoff_a = store
+ .reader
+ .handoff_by_id(handoff_a)
+ .await
+ .unwrap()
+ .unwrap();
+ assert_eq!(
+ handoff_a.lifecycle.state,
+ HandoffState::Accepted,
+ "the already-ended session's handoff stays claimed"
+ );
+ // B's handoff was released by its legitimate end.
+ let handoff_b = store
+ .reader
+ .handoff_by_id(handoff_b)
+ .await
+ .unwrap()
+ .unwrap();
+ assert_eq!(
+ handoff_b.lifecycle.state,
+ HandoffState::Open,
+ "the control's handoff is released by its end"
+ );
+ // Exactly one idle_session_end audit row: the control's, with the
+ // tick's clock and the lifecycle-only action. A wrote nothing.
+ let audits = store
+ .reader
+ .list_audit_events(idle_audit_filter())
+ .await
+ .unwrap();
+ assert_eq!(audits.len(), 1, "only the control end audits");
+ assert_eq!(audits[0].at, now, "the tick's clock");
+ assert!(
+ audits[0].detail.contains("lifecycle_only"),
+ "the detail says which kind of idle end this was: {}",
+ audits[0].detail
+ );
+ assert!(
+ audits[0].detail.contains(&sid_b.to_string()),
+ "the audit row is the control's: {}",
+ audits[0].detail
+ );
+}
diff --git a/crates/ai-memory-store/tests/suite/mod.rs b/crates/ai-memory-store/tests/suite/mod.rs
index 54fef78e..a8646e2f 100644
--- a/crates/ai-memory-store/tests/suite/mod.rs
+++ b/crates/ai-memory-store/tests/suite/mod.rs
@@ -14,6 +14,7 @@ mod fts_drift_status;
mod fts_stopwords_config;
mod handoff_ownership;
mod identity_resolution;
+mod idle_session_end;
mod most_recently_active_scope;
mod multi_session;
mod observation_prune;
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index b5291550..d34d98a9 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -116,7 +116,19 @@ from hook paths.
canonical SessionEnd path as a native hook. Generated session-page
frontmatter records `session_id` plus the immutable `sessions.agent_kind`
as `agent`; it describes the page's harness origin, not the later writer.
- Manual page writes do not receive inferred agent metadata.
+ Manual page writes do not receive inferred agent metadata. A session that
+ never delivered a `SessionEnd` (crashed harness, closed terminal) is ended
+ by the maintenance tick when `[sessions] idle_end_after_hours` is set, with
+ the tick's own page write, the consolidation job and the lifecycle-only
+ handoff release — no additional handoff from the tick. The page write is
+ conditional on the page version the selection captured in its own
+ statement, and the end stamp is a CAS on `ended_at IS NULL` that also
+ re-verifies the session's observation count (the digest's population) and
+ the latest page version — so a late real `SessionEnd` (or a checkpoint)
+ wins that race and converges through `AlreadyEnded`/`ReEnd`. `ended_at` is
+ the tick's clock (the session's last activity is preserved in the audit
+ detail), and the consolidation job is enqueued inside the stamp's
+ transaction.
4. When `AI_MEMORY_LLM_PROVIDER` is set, `memory_consolidate` rewrites
that summary into a richer durable page or fans out into a
multi-page batch under `concepts/`, `decisions/`, `gotchas/`. Consolidation
@@ -1062,6 +1074,24 @@ reconcile_tombstones_deleted_pages = false
# behavior (deletions still need `ai-memory delete-page`).
# Docs: docs/okf.md, docs/install.md.
+[sessions] # server-side session lifecycle
+idle_end_after_hours = 0 # 0 (default) = off. N > 0 (capped at 8760):
+ # the [maintenance] tick ends open sessions whose
+ # last activity is older than N hours with the tick's
+ # own effects (summary page attributed to the
+ # session owner + consolidation job, and the
+ # lifecycle-only handoff release), never an
+ # additional handoff from the tick. Bounded batch
+ # of 25 every 15 minutes; the page write is
+ # conditional on the version the selection
+ # captured, the end stamp is an `ended_at IS NULL`
+ # CAS that also re-verifies the session's
+ # observation count and the latest page version,
+ # so a real SessionEnd landing around the tick
+ # wins that race. `ended_at`
+ # is the tick's clock; the last activity is kept
+ # in the audit detail.
+
[decay] # M8 retention params
lambda = 0.02 # ↓ to forget less aggressively (fallback λ)
sigma = 0.6 # ↑ to reward query-hits more
diff --git a/docs/security-boundaries.md b/docs/security-boundaries.md
index b5f1eaf4..aa607ad3 100644
--- a/docs/security-boundaries.md
+++ b/docs/security-boundaries.md
@@ -51,6 +51,7 @@ means the boundary is not built yet.
| 4h | Offer-mode SessionStart never consumes or injects handoff-controlled text | `ai-memory-hooks/src/router.rs` `fetch_and_accept_handoff_at` branches on the startup configuration before admission/claim and `render_handoff_notice` emits only typed metadata (`HandoffId`, `AgentKind`, computed age); the normal writer CAS remains the only later claim path | `router.rs` `handoff_notice_is_metadata_only_and_never_carries_the_summary` plants hostile summary/questions/steps/files; `offer_mode_leaves_the_baton_open_and_notice_omits_the_summary` exercises the production hook route, asserts the row remains open, then proves the legitimate exact-id writer claim still consumes it (#1030) | STRONG |
| 4i | The compaction recap reads one session's own captured text and never writes or claims | `ai-memory-hooks/src/recap.rs` `handle_recap`/`build_recap` — anchored on the session row (`session_project_ids`), then `grants::authorize_resolved(.., ProjectAccess::Read)` on that project, whose refusal answers exactly like an unknown id (`200` with the no-session notice: no `403`, no project name), and `session_summary_scoped` with the `/handoff` owner filter (`User(key)` or `Unattributed`), so another operator's session answers like an unknown id; open handoffs are read with `list_handoffs` under the same owner filter and never claimed; nothing is written (no claim, active-project publish, observation, or page); stored text is rendered inside the untrusted-history fence with its markers escaped (`escape_untrusted_history_markers`) | `recap.rs` `recap_returns_the_window_and_writes_nothing` (the handoff stays open and the session's row count is unchanged), `another_operator_cannot_read_an_owned_session` (owner control: `owner_reads_own_session`), `db_user_without_grant_reads_a_session_as_unknown` (no status, project name or prompt text gives the refusal away; control: a read grant restores it); through the production `require_bearer` with real `aim_` tokens, `ai-memory-mcp/tests/suite/recap_identity.rs` `a_db_user_cannot_read_another_users_session_through_the_middleware` (owner control), `an_unattributed_caller_cannot_read_an_owned_session` (control: an unowned session stays readable) and `a_db_user_without_a_grant_reads_their_own_restricted_session_as_unknown` (control: a read grant), `recap_for_unknown_session_is_a_notice`, `fence_markers_in_stored_text_are_escaped` | STRONG |
| 4j | A hook never claims a handoff for an event that names no project directory | `GET /handoff` claims the newest open handoff in whatever project the server resolves; a request without `cwd` lets the server use its default or the caller's last active project, so the claim could consume another repository's handoff. Every front door gates the claim on a resolved directory and leaves the handoff open for `memory_handoff_accept`: the native hook in `ai-memory-cli/src/commands/hook.rs` `run_with_payload` (`handoff_scoped`, a resolved `policy_cwd`, gates SessionStart, Kimi's UserPromptSubmit and Grok's PostToolUse, with a stderr warning at SessionStart); the shell bundle's `hooks/_lib.sh` `ai_memory_get_handoff` (refuses a URL without the `&cwd=` that `ai_memory_marker_qs` adds for every named directory); the PowerShell `hooks/lib/ai-memory-hook.ps1` `Invoke-AiMemoryHook` (`$FetchHandoff -and $Cwd`); and the generated OpenCode, OpenCode 2, OMP and Pi integrations' `fetchHandoff` (`if (!cwd) return undefined;`). OpenClaw's `fetchHandoff` already required a directory. The only fallbacks are Devin's documented ones (`DEVIN_PROJECT_DIR`, then the hook's own directory), in `resolve_hook_cwd_with`, `ai_memory_resolve_cwd` and `Resolve-AiMemoryCwd`, and CodeBuddy's documented `CODEBUDDY_PROJECT_DIR` in the native hook (never its process cwd) (#1299) | `hook.rs` `a_handoff_is_never_claimed_without_a_project_directory` (CodeBuddy, Claude Code and Codex SessionStart, Kimi UserPromptSubmit and Grok PostToolUse with no `cwd` send no `GET /handoff`; control: the same events with a `cwd` claim once, naming it); `codebuddy_missing_cwd_uses_codebuddy_project_dir_only` and, end to end against a real server, `ai-memory-cli/tests/suite/external_capture.rs` `codebuddy_start_without_a_directory_leaves_the_default_projects_handoff` (a CodeBuddy SessionStart with no `cwd`, run from inside the project, leaves the server-default project's handoff open; controls: the payload's `cwd`, then `CODEBUDDY_PROJECT_DIR`, claim it); `tests/hooks/test_lib.sh` "a handoff is never claimed without a project directory" (every shell script that fetches a handoff, discovered from the bundle and run from an unrelated directory: no payload directory, no claim; control: a directory claims and names it; Devin claims for its own directory; the PowerShell helper runs the same pair where a PowerShell exists, else a static pin); `install_hooks.rs` `generated_integrations_never_fetch_a_handoff_without_a_directory` and, running the generated OMP extension in Node, `slow_generated_handoff_runtime::omp_extension_never_claims_a_handoff_without_a_directory` (an empty `ctx.cwd` sends no claim; control: a directory claims). Each fails with its guard removed | STRONG for the native hook, the shell bundle and the generated integrations; the PowerShell runtime case runs only where a PowerShell is installed |
+| 4k | The idle-session auto-end (`[sessions] idle_end_after_hours`) never ends a session it does not own: idle-threshold + active-run exclusion at selection, guarded CAS stamp, conditional page write, owner attribution | `ai-memory-store/src/reader.rs` `idle_open_sessions` — ONE statement: the idle-threshold predicate (`ended_at IS NULL` + `COALESCE(MAX(observations.created_at), started_at) < cutoff`), `ORDER BY last_activity ASC` capped at the batch, and a correlated `pages` subquery bound to the session's own `workspace_id`/`project_id` and to the path rendered in SQL from the id blob (`lower(hex(id))` with 8-4-4-4-12 hyphens — byte-for-byte the Rust `format!("sessions/{session_id}.md")`, proven by the selection test with a page present and absent) capturing the latest `sessions/<id>.md` version as the tick's write precondition — a read path, never a write; `active_managed_run_native_session_ids` (only `state = 'active'` managed runs). `ai-memory-store/src/ops.rs` `idle_end_sessions` — per-candidate `UPDATE sessions … WHERE id AND workspace_id AND project_id AND ended_at IS NULL` that also re-verifies the session's observation count (EVERY row of the session — the digest's population, no per-row scope filter) and the latest page version; `ended_at` = the tick's clock (last activity kept in the audit detail), `ended_observation_count` counted at the stamp, one `idle_session_end` audit row in the same transaction, and the consolidation gate: the job is enqueued INSIDE the stamp's transaction (`session_consolidation::enqueue_in_tx`), so a failed enqueue rolls back the stamp, the audit row and the job, while the page the tick already wrote stays as an ordinary version; a lost stamp skips the enqueue and never aborts the batch. The lifecycle-only gate applies the same scope/open guard before any mutation, re-checks substantiveness atomically, reuses `end_lifecycle_only_session_in_tx` (releasing the accepted handoff), and writes its OWN `idle_session_end` audit row distinct from the `release_lifecycle_only_handoff` row. `ai-memory-hooks/src/idle_end.rs` `run_idle_end_tick` — excludes active-run sessions in Rust via `SessionId::from_native` BEFORE the batch bound (the serve loop over-fetches, so an excluded backlog cannot starve the batch), classifies via `session_has_substantive_observation`, builds the page and its count from one digest snapshot (`SessionDigest::load_with_count` — the count the CAS guard re-verifies), writes the page with `Wiki::write_page_if` under `PagePrecondition::Latest(seen)`/`Absent` (`Mismatch` skips the whole session), keeps an agent-written page (`session_page_written_by_agent`), and attributes via `router.rs` `stored_session_identity` (the hook path's own fail-closed parse). The tick creates no additional handoff: the consolidation gate and the lifecycle-only release gate are its only handoff-affecting effects | `store` `tests/suite/idle_session_end.rs` — guard by guard: `idle_end_loses_to_an_already_ended_session` (the `ended_at IS NULL` predicate; fails with it removed), `idle_end_counts_the_same_observation_population_as_the_digest` (a multi-project session ends with `ended_observation_count` = 2; fails if the CAS count's population diverges from the digest/counter's), `idle_end_cas_rejects_a_stale_observation_count` (the count guard; fails with it removed), `idle_end_cas_rejects_a_moved_latest_page` (the page-version guard; fails with it removed), `idle_end_pre_stamp_non_end_observation_in_window_loses_the_cas` / `idle_end_pre_stamp_checkpoint_page_in_window_loses_the_cas` / `idle_end_pre_stamp_real_session_end_in_window_loses_the_cas` (the test-only seam runs on the writer connection BEFORE the candidate's stamp transaction and injects the SQL effects a concurrent writer would leave in the read-to-stamp window — simulated effects, not a run of the hook's `SessionEnd` handler; a `Lost` with the consolidation gate on creates no job; each fails with its guard removed), `idle_end_candidate_cannot_cross_the_project_boundary` (a foreign-scope candidate is refused; same-scope control ends), `idle_end_lifecycle_only_refuses_a_foreign_scope_candidate` (the lifecycle-only scope/open guard: `Lost`, no audit, the claimed handoff stays `Accepted`; fails with the guard removed), `idle_end_lifecycle_only_refuses_an_already_ended_session_with_control` (dedicated already-ended case: `Lost` with no audit and no handoff release, next to the open control in the same fixture that ends and releases), `idle_end_lifecycle_only_loses_to_a_substantive_race` (the atomic substantiveness re-check), `idle_end_reopens_the_handoff_a_lifecycle_only_session_claimed` (exactly one `idle_session_end` row, distinct from the release row), `idle_end_watermark_converges_a_late_real_session_end` (a late real `SessionEnd` converges through `AlreadyEnded`/`ReEnd`), `idle_end_batch_stamps_every_candidate_in_one_command`, `idle_selection_is_cutoff_scoped_ordered_and_bounded` (threshold, order, bound; `seen_page_id` captured with a page present and `None` without — the `session_page_path` rendering), `idle_end_stamps_watermark_audit_page_and_consolidation`, `idle_end_consolidation_enqueue_shares_the_callers_transaction` + `idle_end_consolidation_enqueue_failure_rolls_back_and_retries` (the in-transaction enqueue; fails out-of-transaction), `session_observation_count_refuses_foreign_and_missing_scopes` (foreign workspace / foreign project / missing id each count 0; the right tuple counts — the raw-id reader's scope join), `enqueue_in_tx_refuses_a_foreign_scope_and_leaves_the_foreign_queue` (a foreign tuple enqueues nothing and the foreign project's queue is unchanged; the right tuple enqueues — the job INSERT's scope binding). `hooks` `tests/suite/idle_end.rs` + `src/synth.rs` `load_with_count_scopes`: `foreign_and_missing_tuples_load_nothing_the_right_tuple_loads` (`SessionDigest::load_with_count` refuses a foreign tuple and a missing id as `SessionCollision`; the right tuple loads and counts — the tuple validation; fails with it removed), `idle_tick_skips_a_session_ended_by_a_real_session_end_between_selection_and_write` (a real `/hook` `SessionEnd` landing between selection and page write leaves the hook's page as the only version and no additional handoff from the tick; fails with the conditional write removed — the CAS itself is proven by the store tests above), `idle_tick_late_real_session_end_with_new_work_reends_with_handoff` (the late real end re-ends with exactly one handoff), `idle_tick_excludes_active_managed_run_sessions` (+control after `cancel_managed_run`), `idle_tick_excluded_backlog_cannot_starve_the_batch` (25 excluded sessions cannot consume the batch), `idle_tick_ends_idle_substantive_session_with_page_job_and_no_handoff` (owner attribution via `last_modified_by.username`; no additional handoff from the tick), `idle_tick_lifecycle_only_ends_without_page_or_job_and_creates_no_handoff`, `idle_tick_skips_active_sessions_and_respects_the_batch`, `idle_tick_keeps_a_session_page_written_by_the_agent`; `cli` `serve.rs` `idle_end_tick_does_not_start_when_disabled_or_maintenance_off` and `idle_end_tick_ends_an_idle_session_on_the_first_pass` (tick-clock `ended_at`, paused `tokio::time`), `config.rs` `sessions_idle_end_defaults_off_loads_from_toml_and_rejects_out_of_range` | STRONG |
| 5a | Pages shared: `author_id` is never a read filter (invariant #16) | `ai-memory-store/src/reader.rs` `search_pages`/`page_body_by_ids` — `author_id` is an attribution JOIN only, never a WHERE term; `observation_stream_votes` lets every session vote whatever its owner (the owner filter only withholds the observation excerpt and ids, never the vote or the page) | `multi_session.rs` — a page with a **non-null** `author_id` (operator A) is readable by operator B in the same project; `multi_session.rs` `another_operators_observations_lift_their_session_page_in_a_shared_project` (operator B's owned session, authored page and observations lift that page for operator A's query); `ai-memory-mcp` `server.rs` `observation_stream_evidence_stays_inside_a_restricted_project` (a second operator with only a read grant gets the session page lifted by the first operator's observation); `multi_session.rs` `observation_excerpts_follow_the_session_owner_while_the_vote_stays_shared` (B still gets A's session page ranked by A's observation, with the page's own snippet) | STRONG |
| 5b | Page supersession (loser stays reachable) | `ai-memory-store/src/ops.rs` `upsert_page_in_tx` — demote `is_latest=0` (never delete) + `supersedes` chain; read side: `reader.rs` `page_versions` lists every row at the path, with no `is_latest` filter, for `/web/w/…/h/*path` and `/api/v1/…/history/*path`. It does apply TTL expiry (`reader.rs` `history_visible`): a version whose own `expires_at` passed is neither listed nor readable by id, a path whose live version expired shows no history at all (the forget sweep hard-deletes every row there), and a `supersedes` link to a hidden version reads as `null`. Expiry is the only thing that hides a superseded version; a concurrent write never does | `multi_session.rs` `concurrent_writes_to_one_path_supersede_rather_than_destroy`; `retrieval_superseded.rs`; `multi_session.rs` `page_history_keeps_the_overwritten_version_and_stays_in_scope`; `ai-memory-web` `history_replay.rs` `history_keeps_both_sides_of_a_concurrent_divergent_write` (two attributed writers on one base: all three versions and both authors listed, one `is_latest`, the two writers' versions diff by id) and `history_lists_k_plus_one_versions_newest_first_and_diffs_the_latest`; bite: an `is_latest = 1` filter in `page_versions` fails both; `history_hides_expired_versions_and_expired_pages` (an expired superseded version and every version of a page whose live version expired answer 404 by path and by id on HTML and JSON, and the live successor's `supersedes` is `null`; control: a TTL in the future is listed and diffable; bites with the per-row predicate removed, with the live-version clause disabled, and with the `supersedes` hiding removed) | STRONG |
| 5c | Watcher reindex and Wiki writes share per-page serialization (invariant #16) | `ai-memory-wiki/src/wiki.rs` `reindex_page` takes `mutation_lock.read` before `reindex_page_locked` takes `lock_page`, covering disk read through the single-writer upsert; callers already holding the exclusive global guard do not reacquire it. `write_page` uses the same page mutex and `apply_batch` retains sorted, deduplicated locks; embedding runs after both guards are released | `wiki.rs` `reindex_page_lock_waits_before_reading_and_allows_another_path` (transient snapshot refused while locked, another path progresses, release indexes the committed bytes without rewriting disk), `reindex_page_lock_serializes_write_through_the_upsert` and `reindex_page_lock_and_reversed_duplicate_batches_do_not_deadlock` (real concurrent operations, final disk/SQL winner and supersession ancestry preserved); all three fail with the reindex page guard removed. `reindex_page_lock_releases_both_guards_before_embedding` checks both body and abstract embedding; `decay_cleanup_reindex_does_not_embed_under_the_exclusive_lock` covers the exclusive caller | STRONG for a shared Wiki handle and its clones. External editors and independently constructed Wiki handles do not participate in these locks |