Skip to content

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

Rust

fix(hooks): make SessionEnd recovery convergent

AkitaOnRails188b6edc26d3
diff --git a/CHANGELOG.md b/CHANGELOG.md
index c7cbbd1d..943f2171 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -39,6 +39,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
including subdirectories and linked worktrees. (#259)
### Fixed
+- SessionEnd recovery now commits the ended generation and automatic handoff in
+ one SQLite transaction, then lets an already-ended native replay converge the
+ remaining wiki commit, durable consolidation enqueue, and ingest-key
+ completion. An interruption after `ended_at` can no longer strand a missing
+ handoff or permanently pending spool key, and missing or scope/agent-
+ mismatched SessionEnd events no longer attempt consolidation recovery against
+ an unrelated session. (#270)
- Bare `install-hooks --apply` re-runs, including the Docker wrapper's
post-upgrade refresh, now preserve an install's baked `repo-root` project
strategy for every supported hook integration. An explicit
diff --git a/README.md b/README.md
index e4224d89..320f5cfe 100644
--- a/README.md
+++ b/README.md
@@ -670,7 +670,9 @@ drain latency does not cancel it. Failed jobs retry with backoff and survive a
server restart. A resumed native session is ended again only after its
observation generation advances; the persisted generation watermark makes
duplicate SessionEnd delivery and system clock skew converge without repeated
-provider work.
+provider work. The end watermark and automatic handoff commit atomically, and
+an interrupted keyed replay finishes the wiki commit, queue insert, and key
+completion without duplicating that handoff.
Recommended defaults:
diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rs
index ed778f99..b2ef9ab2 100644
--- a/crates/ai-memory-hooks/src/router.rs
+++ b/crates/ai-memory-hooks/src/router.rs
@@ -1969,16 +1969,38 @@ async fn process(
.await?
{
ai_memory_store::SessionEndDisposition::Open => {}
- ai_memory_store::SessionEndDisposition::DropStale => {
- // A first delivery can be cancelled after `end_session` but
- // before its durable LLM job is queued. The replay must ensure
- // that job exists before acknowledging the already-ended
- // session; enqueue is generation-idempotent.
+ ai_memory_store::SessionEndDisposition::DropInvalid => {
+ info!(
+ session = %session_id,
+ agent = %env.agent.as_str(),
+ "ignoring SessionEnd for missing, mismatched, or cross-agent session"
+ );
+ return Ok(());
+ }
+ ai_memory_store::SessionEndDisposition::AlreadyEnded => {
+ // End stamping and the legacy handoff commit atomically. A
+ // first delivery can still be cancelled after that transaction
+ // but before the wiki commit, durable LLM enqueue, or ingest-key
+ // completion. Re-run those idempotent tail effects before
+ // acknowledging the already-ended session.
+ let commit_msg = format!("repair session {}", short_id(&session_id.to_string()),);
+ match state.wiki.commit_all(&commit_msg) {
+ Ok(Some(oid)) => debug!(commit = %oid, "wiki recovery auto-commit"),
+ Ok(None) => debug!("wiki clean during SessionEnd recovery"),
+ Err(e) => warn!(error = %e, "SessionEnd recovery auto-commit failed"),
+ }
enqueue_session_end_consolidation(state, session_id, ws, proj).await?;
+ if let Some(key) = env.ingest_key {
+ let completed = state
+ .writer
+ .complete_observation_ingest_if_claimed(proj, key.clone())
+ .await?;
+ debug!(key, completed, "SessionEnd recovery ingest-key completion");
+ }
info!(
session = %session_id,
agent = %env.agent.as_str(),
- "ignoring SessionEnd for missing, mismatched, or already-ended session"
+ "recovered tail effects for already-ended SessionEnd"
);
return Ok(());
}
@@ -2181,8 +2203,8 @@ async fn process(
actor: ai_memory_core::ActorContext::anonymous(),
})
.await?;
- state.writer.end_session(session_id, Some(page_id)).await?;
let handoff_id = if managed {
+ state.writer.end_session(session_id, Some(page_id)).await?;
None
} else {
let handoff = build_auto_handoff(
@@ -2193,7 +2215,12 @@ async fn process(
env.cwd.clone(),
&observations,
);
- Some(state.writer.insert_handoff(handoff).await?)
+ Some(
+ state
+ .writer
+ .end_session_with_handoff(session_id, Some(page_id), handoff)
+ .await?,
+ )
};
// Auto-commit the wiki tree so the session/handoff/log.md
// changes land in git in one atomic snapshot.
@@ -5187,7 +5214,18 @@ mod tests {
#[tokio::test]
async fn mismatched_session_end_does_not_create_summary_or_handoff() {
let tmp = TempDir::new().unwrap();
- let state = make_state(&tmp).await;
+ let mut state = make_state(&tmp).await;
+ let llm = Arc::new(RecordingLlm(Mutex::new(None)));
+ state.consolidator = Some(Arc::new(Consolidator::new(
+ state.reader.clone(),
+ state.writer.clone(),
+ state.wiki.clone(),
+ llm,
+ state.workspace_id,
+ state.project_id,
+ )));
+ state.consolidate_on_session_end = true;
+ state.session_consolidation_notify = Some(Arc::new(tokio::sync::Notify::new()));
let target = state
.writer
.get_or_create_project(state.workspace_id, "target", None)
@@ -5253,6 +5291,16 @@ mod tests {
.is_none(),
"mismatched SessionEnd must not create a target handoff"
);
+ let now = Timestamp::now().as_microsecond();
+ assert!(
+ state
+ .writer
+ .claim_session_consolidation(now, now - 1)
+ .await
+ .unwrap()
+ .is_none(),
+ "mismatched SessionEnd must not enter consolidation recovery"
+ );
}
#[tokio::test]
@@ -5423,7 +5471,7 @@ mod tests {
}
#[tokio::test]
- async fn stale_session_end_redelivery_repairs_missing_queue_job() {
+ async fn stale_session_end_redelivery_converges_interrupted_tail_effects() {
let tmp = TempDir::new().unwrap();
let mut state = make_state(&tmp).await;
let llm = Arc::new(RecordingLlm(Mutex::new(None)));
@@ -5439,24 +5487,94 @@ mod tests {
state.session_consolidation_notify = Some(Arc::new(tokio::sync::Notify::new()));
let sid = "20202020-2020-2020-2020-202020202020";
let session_id: SessionId = sid.parse().unwrap();
- let fire = |event: &str| {
+ let fire = |event: &str, key: Option<&str>| {
HookEnvelope::from_query_and_body(
HookQuery {
event: event.into(),
agent: Some("codex".into()),
+ ingest_key: key.map(str::to_string),
..Default::default()
},
serde_json::json!({ "session_id": sid, "prompt": "finish" }),
)
};
- process(&state, fire("user-prompt-submit"), None)
+ process(&state, fire("user-prompt-submit", None), None)
+ .await
+ .unwrap();
+ let (workspace_id, project_id, _) = state
+ .reader
+ .find_session_scope(session_id)
+ .await
+ .unwrap()
+ .unwrap();
+ let pending_observation = || {
+ Sanitized::new(
+ NewObservation {
+ session_id,
+ workspace_id,
+ project_id,
+ kind: ObservationKind::SessionEnd,
+ extension: None,
+ source_event: None,
+ title: "session-end".into(),
+ body: "finish".into(),
+ importance: 7,
+ },
+ &state.sanitizer,
+ )
+ };
+ assert!(matches!(
+ state
+ .writer
+ .insert_observation_ingest(pending_observation(), "entry-recovery".into())
+ .await
+ .unwrap(),
+ IngestObservationOutcome::Inserted(_)
+ ));
+
+ // Reproduce the durable boundary from #270: the summary file exists and
+ // the atomic end+handoff transaction committed, then the request was
+ // cancelled before the wiki commit, queue insert, or key completion.
+ let observations = state
+ .reader
+ .observations_for_session(session_id)
+ .await
+ .unwrap();
+ let page = synthesize_session_page(workspace_id, project_id, session_id, &observations);
+ let page_id = state
+ .wiki
+ .write_page(ai_memory_wiki::WritePageRequest {
+ workspace_id,
+ project_id,
+ path: page.path,
+ frontmatter: page.frontmatter_json,
+ body: page.body,
+ tier: page.tier,
+ pinned: page.pinned,
+ title: None,
+ admission_ctx: None,
+ author_id: None,
+ actor: ai_memory_core::ActorContext::anonymous(),
+ })
+ .await
+ .unwrap();
+ let handoff = build_auto_handoff(
+ workspace_id,
+ project_id,
+ AgentKind::Codex,
+ session_id,
+ None,
+ &observations,
+ );
+ state
+ .writer
+ .end_session_with_handoff(session_id, Some(page_id), handoff)
.await
.unwrap();
- // Reproduce the persisted boundary from #260: the original request
- // reached end_session, then was cancelled before it could enqueue.
- state.writer.end_session(session_id, None).await.unwrap();
- process(&state, fire("session-end"), None).await.unwrap();
+ process(&state, fire("session-end", Some("entry-recovery")), None)
+ .await
+ .unwrap();
let now = Timestamp::now().as_microsecond();
let job = state
.writer
@@ -5465,7 +5583,33 @@ mod tests {
.unwrap()
.expect("stale redelivery must restore the missing durable job");
assert_eq!(job.session_id(), session_id);
- assert_eq!(job.generation(), 1);
+ assert_eq!(job.generation(), 2);
+ assert_eq!(
+ state
+ .writer
+ .insert_observation_ingest(pending_observation(), "entry-recovery".into())
+ .await
+ .unwrap(),
+ IngestObservationOutcome::AlreadyComplete,
+ "the recovered event must finish its pending ingest key"
+ );
+ let briefing = state
+ .reader
+ .briefing_for_project(workspace_id, project_id, 1)
+ .await
+ .unwrap();
+ assert_eq!(
+ briefing.pending_handoff_count, 1,
+ "recovery must preserve exactly one automatic handoff"
+ );
+ assert!(
+ state
+ .wiki
+ .commit_all("verify recovery clean")
+ .unwrap()
+ .is_none(),
+ "recovery must commit the summary file left by the interrupted request"
+ );
}
// Issue #152: an agent that resumes an ended session under the same id
@@ -5511,7 +5655,7 @@ mod tests {
.unwrap();
assert_eq!(
disposition,
- ai_memory_store::SessionEndDisposition::DropStale,
+ ai_memory_store::SessionEndDisposition::AlreadyEnded,
"a freshly-ended session with no newer work must drop duplicate ends"
);
let page_after_first_end = state
@@ -5585,7 +5729,7 @@ mod tests {
.unwrap();
assert_eq!(
disposition,
- ai_memory_store::SessionEndDisposition::DropStale,
+ ai_memory_store::SessionEndDisposition::AlreadyEnded,
"after the re-end, the generation watermark must cover resumed work"
);
}
diff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rs
index 30a8cff9..5baa8095 100644
--- a/crates/ai-memory-store/src/lib.rs
+++ b/crates/ai-memory-store/src/lib.rs
@@ -2694,6 +2694,92 @@ mod tests {
);
}
+ #[tokio::test]
+ async fn session_end_and_automatic_handoff_commit_atomically() {
+ let tmp = TempDir::new().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let ws = store
+ .writer
+ .get_or_create_workspace("default")
+ .await
+ .unwrap();
+ let proj = store
+ .writer
+ .get_or_create_project(ws, "ai-memory", None)
+ .await
+ .unwrap();
+ let other = store
+ .writer
+ .get_or_create_project(ws, "other", None)
+ .await
+ .unwrap();
+ let session_id = SessionId::new();
+ store
+ .writer
+ .begin_session(NewSession {
+ id: session_id,
+ workspace_id: ws,
+ project_id: proj,
+ agent_kind: AgentKind::Codex,
+ cwd: None,
+ })
+ .await
+ .unwrap();
+ let handoff = |project_id| NewHandoff {
+ workspace_id: ws,
+ project_id,
+ from_session_id: Some(session_id),
+ from_agent: AgentKind::Codex,
+ to_agent: None,
+ cwd: None,
+ summary: "continue".into(),
+ open_questions: Vec::new(),
+ next_steps: Vec::new(),
+ files_touched: Vec::new(),
+ };
+
+ assert!(
+ store
+ .writer
+ .end_session_with_handoff(session_id, None, handoff(other))
+ .await
+ .is_err(),
+ "a mismatched handoff must reject the whole end transition"
+ );
+ assert_eq!(
+ store
+ .reader
+ .session_end_disposition(session_id, ws, proj, AgentKind::Codex)
+ .await
+ .unwrap(),
+ SessionEndDisposition::Open,
+ "failed handoff insertion must leave the session open"
+ );
+
+ store
+ .writer
+ .end_session_with_handoff(session_id, None, handoff(proj))
+ .await
+ .unwrap();
+ let conn = Connection::open(store.db_path()).unwrap();
+ let ended: Option<i64> = conn
+ .query_row(
+ "SELECT ended_at FROM sessions WHERE id = ?1",
+ params![session_id.as_bytes()],
+ |row| row.get(0),
+ )
+ .unwrap();
+ let handoffs: i64 = conn
+ .query_row(
+ "SELECT COUNT(*) FROM handoffs WHERE from_session_id = ?1",
+ params![session_id.as_bytes()],
+ |row| row.get(0),
+ )
+ .unwrap();
+ assert!(ended.is_some());
+ assert_eq!(handoffs, 1);
+ }
+
#[tokio::test]
async fn session_end_disposition_uses_observation_generation_not_wall_clock() {
let tmp = TempDir::new().unwrap();
@@ -2709,6 +2795,15 @@ mod tests {
.await
.unwrap();
let session_id = SessionId::new();
+ assert_eq!(
+ store
+ .reader
+ .session_end_disposition(session_id, ws, proj, AgentKind::ClaudeCode)
+ .await
+ .unwrap(),
+ SessionEndDisposition::DropInvalid,
+ "a missing session must not enter already-ended recovery"
+ );
store
.writer
.begin_session(NewSession {
@@ -2720,6 +2815,27 @@ mod tests {
})
.await
.unwrap();
+ let other_proj = store
+ .writer
+ .get_or_create_project(ws, "other", None)
+ .await
+ .unwrap();
+ assert_eq!(
+ store
+ .reader
+ .session_end_disposition(session_id, ws, other_proj, AgentKind::ClaudeCode)
+ .await
+ .unwrap(),
+ SessionEndDisposition::DropInvalid
+ );
+ assert_eq!(
+ store
+ .reader
+ .session_end_disposition(session_id, ws, proj, AgentKind::Codex)
+ .await
+ .unwrap(),
+ SessionEndDisposition::DropInvalid
+ );
let first_observation = store
.writer
.insert_observation(Sanitized::new(
@@ -2759,7 +2875,7 @@ mod tests {
.session_end_disposition(session_id, ws, proj, AgentKind::ClaudeCode)
.await
.unwrap(),
- SessionEndDisposition::DropStale,
+ SessionEndDisposition::AlreadyEnded,
"a covered observation must stay covered even if its timestamp is in the future"
);
@@ -2803,7 +2919,7 @@ mod tests {
.session_end_disposition(session_id, ws, proj, AgentKind::ClaudeCode)
.await
.unwrap(),
- SessionEndDisposition::DropStale,
+ SessionEndDisposition::AlreadyEnded,
"stamping the new generation must make the re-end converge"
);
}
diff --git a/crates/ai-memory-store/src/ops.rs b/crates/ai-memory-store/src/ops.rs
index df050a70..c69397e7 100644
--- a/crates/ai-memory-store/src/ops.rs
+++ b/crates/ai-memory-store/src/ops.rs
@@ -836,6 +836,14 @@ pub fn end_session(
conn: &mut Connection,
session_id: &SessionId,
summary_page_id: Option<&PageId>,
+) -> StoreResult<()> {
+ end_session_row(conn, session_id, summary_page_id)
+}
+
+fn end_session_row(
+ conn: &Connection,
+ session_id: &SessionId,
+ summary_page_id: Option<&PageId>,
) -> StoreResult<()> {
let now = Timestamp::now().as_microsecond();
let page_blob: Option<&[u8]> = summary_page_id.map(|p| &p.as_bytes()[..]);
@@ -922,6 +930,23 @@ pub fn complete_observation_ingest(
project_id: &ProjectId,
ingest_key: &str,
) -> StoreResult<()> {
+ if !complete_observation_ingest_if_claimed(conn, project_id, ingest_key)? {
+ return Err(StoreError::InvalidState(
+ "cannot complete an ingest key that was not claimed".into(),
+ ));
+ }
+ Ok(())
+}
+
+/// Mark a keyed hook event complete when its observation claim exists.
+///
+/// Recovery paths use the boolean result to distinguish a pending native-hook
+/// replay from an unkeyed or unrelated duplicate SessionEnd.
+pub fn complete_observation_ingest_if_claimed(
+ conn: &mut Connection,
+ project_id: &ProjectId,
+ ingest_key: &str,
+) -> StoreResult<bool> {
let completed_at = Timestamp::now().as_microsecond();
let matched = conn.execute(
"UPDATE ingest_keys \
@@ -929,12 +954,7 @@ pub fn complete_observation_ingest(
WHERE project_id = ?2 AND key = ?3",
params![completed_at, project_id.as_bytes(), ingest_key],
)?;
- if matched == 0 {
- return Err(StoreError::InvalidState(
- "cannot complete an ingest key that was not claimed".into(),
- ));
- }
- Ok(())
+ Ok(matched != 0)
}
/// The observation INSERT itself, shared by the plain and keyed paths
@@ -1166,6 +1186,54 @@ pub fn hard_delete_decayed_pages(
/// Insert a new handoff in state=open.
pub fn insert_handoff(conn: &mut Connection, h: &NewHandoff) -> StoreResult<HandoffId> {
+ let tx = conn.transaction()?;
+ let id = insert_handoff_row(&tx, h)?;
+ tx.commit()?;
+ Ok(id)
+}
+
+/// Atomically stamp a session ended and insert its automatic handoff.
+///
+/// A failed handoff insert rolls the end stamp back, so a keyed retry can run
+/// the complete SessionEnd path instead of observing a partially ended session.
+pub fn end_session_with_handoff(
+ conn: &mut Connection,
+ session_id: &SessionId,
+ summary_page_id: Option<&PageId>,
+ handoff: &NewHandoff,
+) -> StoreResult<HandoffId> {
+ if handoff.from_session_id.as_ref() != Some(session_id) {
+ return Err(StoreError::InvalidState(
+ "automatic handoff source does not match the ended session".into(),
+ ));
+ }
+ let tx = conn.transaction()?;
+ let session_scope: Option<(Vec<u8>, Vec<u8>)> = tx
+ .query_row(
+ "SELECT workspace_id, project_id FROM sessions WHERE id = ?1",
+ params![session_id.as_bytes()],
+ |row| Ok((row.get(0)?, row.get(1)?)),
+ )
+ .optional()?;
+ let Some((workspace_id, project_id)) = session_scope else {
+ return Err(StoreError::InvalidState(
+ "cannot end a missing session with an automatic handoff".into(),
+ ));
+ };
+ if workspace_id.as_slice() != handoff.workspace_id.as_bytes()
+ || project_id.as_slice() != handoff.project_id.as_bytes()
+ {
+ return Err(StoreError::InvalidState(
+ "automatic handoff scope does not match the ended session".into(),
+ ));
+ }
+ end_session_row(&tx, session_id, summary_page_id)?;
+ let id = insert_handoff_row(&tx, handoff)?;
+ tx.commit()?;
+ Ok(id)
+}
+
+fn insert_handoff_row(conn: &Transaction<'_>, h: &NewHandoff) -> StoreResult<HandoffId> {
let id = HandoffId::new();
let now = Timestamp::now().as_microsecond();
let open_q = serde_json::to_string(&h.open_questions)?;
@@ -1191,8 +1259,7 @@ pub fn insert_handoff(conn: &mut Connection, h: &NewHandoff) -> StoreResult<Hand
// Insert + audit atomically. Handoffs are keyed by agent/session, not a DB
// user, so the audit author is NULL — the row records the lifecycle event
// (op + workspace/project + time), not an operator identity.
- let tx = conn.transaction()?;
- tx.execute(
+ conn.execute(
"INSERT INTO handoffs \
(id, workspace_id, project_id, from_session_id, from_agent, to_agent, cwd, summary, \
open_questions, next_steps, files_touched, state, created_at) \
@@ -1213,7 +1280,7 @@ pub fn insert_handoff(conn: &mut Connection, h: &NewHandoff) -> StoreResult<Hand
],
)?;
audit(
- &tx,
+ conn,
"insert_handoff",
Some(h.workspace_id.as_bytes()),
Some(h.project_id.as_bytes()),
@@ -1221,7 +1288,6 @@ pub fn insert_handoff(conn: &mut Connection, h: &NewHandoff) -> StoreResult<Hand
None,
now,
)?;
- tx.commit()?;
Ok(id)
}
diff --git a/crates/ai-memory-store/src/reader.rs b/crates/ai-memory-store/src/reader.rs
index 74457923..d9ec7b3e 100644
--- a/crates/ai-memory-store/src/reader.rs
+++ b/crates/ai-memory-store/src/reader.rs
@@ -241,9 +241,13 @@ pub enum SessionEndDisposition {
/// The session is open in the resolved scope/agent: run the normal end
/// path.
Open,
- /// Missing, cross-scope, cross-agent, or already ended with no observations
- /// beyond the persisted end generation: a duplicate or stale end — drop it.
- DropStale,
+ /// The session is missing or does not match the resolved scope/agent. Drop
+ /// the event without attempting recovery against an unrelated session.
+ DropInvalid,
+ /// The matching session already ended with no observations beyond the
+ /// persisted end generation. Converge any interrupted downstream effects,
+ /// then drop the duplicate end.
+ AlreadyEnded,
/// Already ended, but the observation count exceeds the persisted end
/// generation: the agent resumed the session under the same id — run the
/// full end path again so the resumed work reaches the compiled page
@@ -1536,7 +1540,7 @@ impl ReaderPool {
.optional()?;
let Some((ended_at, ended_observation_count)) = end_state else {
// Missing, cross-scope, or cross-agent: never end it.
- return Ok(SessionEndDisposition::DropStale);
+ return Ok(SessionEndDisposition::DropInvalid);
};
if ended_at.is_none() {
return Ok(SessionEndDisposition::Open);
@@ -1549,7 +1553,7 @@ impl ReaderPool {
if current_observation_count > ended_observation_count {
Ok(SessionEndDisposition::ReEndWithNewWork)
} else {
- Ok(SessionEndDisposition::DropStale)
+ Ok(SessionEndDisposition::AlreadyEnded)
}
})
.await
diff --git a/crates/ai-memory-store/src/writer.rs b/crates/ai-memory-store/src/writer.rs
index e011d422..724294b8 100644
--- a/crates/ai-memory-store/src/writer.rs
+++ b/crates/ai-memory-store/src/writer.rs
@@ -96,6 +96,12 @@ pub(crate) enum WriteCmd {
summary_page_id: Option<PageId>,
reply: oneshot::Sender<StoreResult<()>>,
},
+ EndSessionWithHandoff {
+ session_id: SessionId,
+ summary_page_id: Option<PageId>,
+ handoff: NewHandoff,
+ reply: oneshot::Sender<StoreResult<HandoffId>>,
+ },
SweepHollowProjects {
min_age_days: u32,
reply: oneshot::Sender<StoreResult<Vec<String>>>,
@@ -114,6 +120,11 @@ pub(crate) enum WriteCmd {
ingest_key: String,
reply: oneshot::Sender<StoreResult<()>>,
},
+ CompleteObservationIngestIfClaimed {
+ project_id: ProjectId,
+ ingest_key: String,
+ reply: oneshot::Sender<StoreResult<bool>>,
+ },
EnqueueSessionConsolidation {
workspace_id: WorkspaceId,
project_id: ProjectId,
@@ -511,6 +522,27 @@ impl WriterHandle {
rx.await.map_err(|_| StoreError::WriterClosed)?
}
+ /// Atomically end a session and insert its automatic handoff.
+ ///
+ /// # Errors
+ /// Returns [`StoreError::WriterClosed`] or propagates SQL/state errors.
+ pub async fn end_session_with_handoff(
+ &self,
+ session_id: SessionId,
+ summary_page_id: Option<PageId>,
+ handoff: NewHandoff,
+ ) -> StoreResult<HandoffId> {
+ let (tx, rx) = oneshot::channel();
+ self.send(WriteCmd::EndSessionWithHandoff {
+ session_id,
+ summary_page_id,
+ handoff,
+ 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`].
@@ -592,6 +624,24 @@ impl WriterHandle {
rx.await.map_err(|_| StoreError::WriterClosed)?
}
+ /// Mark a keyed hook event complete if its observation claim exists.
+ ///
+ /// Returns `false` for an unkeyed or unrelated duplicate recovery attempt.
+ pub async fn complete_observation_ingest_if_claimed(
+ &self,
+ project_id: ProjectId,
+ ingest_key: String,
+ ) -> StoreResult<bool> {
+ let (tx, rx) = oneshot::channel();
+ self.send(WriteCmd::CompleteObservationIngestIfClaimed {
+ project_id,
+ ingest_key,
+ reply: tx,
+ })
+ .await?;
+ rx.await.map_err(|_| StoreError::WriterClosed)?
+ }
+
/// Persist one opt-in SessionEnd consolidation job for the current
/// observation generation. Duplicate generations are idempotent.
pub async fn enqueue_session_consolidation(
@@ -1446,6 +1496,20 @@ fn worker_loop(mut conn: Connection, mut rx: mpsc::Receiver<WriteCmd>) {
let result = ops::end_session(&mut conn, &session_id, summary_page_id.as_ref());
send_or_warn(reply, result, "end_session");
}
+ WriteCmd::EndSessionWithHandoff {
+ session_id,
+ summary_page_id,
+ handoff,
+ reply,
+ } => {
+ let result = ops::end_session_with_handoff(
+ &mut conn,
+ &session_id,
+ summary_page_id.as_ref(),
+ &handoff,
+ );
+ send_or_warn(reply, result, "end_session_with_handoff");
+ }
WriteCmd::SweepHollowProjects {
min_age_days,
reply,
@@ -1473,6 +1537,18 @@ fn worker_loop(mut conn: Connection, mut rx: mpsc::Receiver<WriteCmd>) {
let result = ops::complete_observation_ingest(&mut conn, &project_id, &ingest_key);
send_or_warn(reply, result, "complete_observation_ingest");
}
+ WriteCmd::CompleteObservationIngestIfClaimed {
+ project_id,
+ ingest_key,
+ reply,
+ } => {
+ let result = ops::complete_observation_ingest_if_claimed(
+ &mut conn,
+ &project_id,
+ &ingest_key,
+ );
+ send_or_warn(reply, result, "complete_observation_ingest_if_claimed");
+ }
WriteCmd::EnqueueSessionConsolidation {
workspace_id,
project_id,
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 24e94a25..d27f73ad 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -68,16 +68,19 @@ from hook paths.
overlapping retry with the original processor. Downstream effects remain
at-least-once until that completion marker, so a process crash during those
effects may repeat an already applied effect rather than silently lose the
- rest. `log.md` gets an appended
+ rest. For an interrupted already-ended SessionEnd, the replay converges the
+ wiki commit, durable provider job, and pending key without appending another
+ observation. `log.md` gets an appended
`## [YYYY-MM-DDTHH:MM:SSZ] <event> | <title>` line.
3. On true `SessionEnd` events, the server synthesises a
`sessions/<id>.md` summary page (rule-based, no LLM) and opens a
- `Handoff` row for the next agent. The same transaction that stamps the
- session ended records the covered observation count. A later SessionEnd
- re-runs the path only when that generation advances, so resumed sessions
- are captured while duplicate delivery and clock skew converge. Existing
- ended sessions are baselined at migration instead of becoming historical
- catch-up work. Auto-commits the wiki. Clients
+ `Handoff` row for the next agent. One SQLite transaction inserts that
+ automatic handoff, stamps the session ended, and records the covered
+ observation count, so recovery never sees only half of those DB effects. A
+ later SessionEnd re-runs the path only when that generation advances, so
+ resumed sessions are captured while duplicate delivery and clock skew
+ converge. Existing ended sessions are baselined at migration instead of
+ becoming historical catch-up work. Auto-commits the wiki. Clients
without a reliable true session-end hook need an explicit ending action:
Codex provides `ai-memory finalize-session`, while Antigravity CLI should
call `memory_handoff_begin` before quitting when a handoff is needed.
diff --git a/docs/design-decisions.md b/docs/design-decisions.md
index 59ae49ab..1d9fec16 100644
--- a/docs/design-decisions.md
+++ b/docs/design-decisions.md
@@ -96,7 +96,7 @@ Why not LanceDB/Qdrant/Kuzu/CozoDB/SurrealDB?
**LLM for consolidation passes:**
- **Off by default**, behaves like agentmemory after #138's fix. Without a provider, the system still works: synthetic compression (rule-based), no LLM-generated summaries, no `memory_consolidate` page-rewrite.
-- With a provider, LLM consolidation runs on PreCompact, on demand via `memory_consolidate`, and at session end only when `AI_MEMORY_CONSOLIDATE_ON_SESSION_END=true` (off by default — session end always writes a rule-based summary page + handoff regardless). SessionEnd provider work is persisted by observation generation and consumed outside the hook request by one bounded retrying worker, so client drain cancellation cannot lose it. The completed end also stores the observation count it covered; a resumed session re-enters the end path only after that count advances, avoiding non-convergent wall-clock comparisons. Optional 6h maintenance timer.
+- With a provider, LLM consolidation runs on PreCompact, on demand via `memory_consolidate`, and at session end only when `AI_MEMORY_CONSOLIDATE_ON_SESSION_END=true` (off by default — session end always writes a rule-based summary page + handoff regardless). SessionEnd provider work is persisted by observation generation and consumed outside the hook request by one bounded retrying worker, so client drain cancellation cannot lose it. The automatic handoff and completed-end watermark commit in one SQLite transaction; an already-ended keyed replay converges the remaining wiki commit, provider enqueue, and ingest-key completion. The completed end also stores the observation count it covered; a resumed session re-enters the end path only after that count advances, avoiding non-convergent wall-clock comparisons. Optional 6h maintenance timer.
- Providers implement `LlmProvider { complete(...); complete_structured(...) }`. The current provider and authentication matrix lives in [`ARCHITECTURE.md`](ARCHITECTURE.md); this design boundary also covers OpenAI-compatible endpoints such as Ollama, vLLM, and LM Studio.
- **Native HTTP per provider** - no LiteLLM-equivalent. The cognee tracker (#2412/#2430/#2537/#2608/#2749/#2782/#2840/#2842) showed silent-kwarg-drop in a generic gateway is the #1 source of provider bugs. Each provider's typed JSON, errors on unknown fields. Hand-coded but correct.
- **Structured output via JSON schema, not XML, not Instructor-style wrapping.** Use each provider's native JSON-mode where available; for Anthropic, request a tool-use response with a typed schema. Validate with `serde_json` + `schemars`-derived schemas.
diff --git a/docs/install.md b/docs/install.md
index 6f44ac1d..627bbad6 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -477,7 +477,10 @@ boundary events (`stop`, `pre-compact`, and `session-end`) start a detached
Each spooled entry keeps one idempotency key across retries. A server that
processed an event but lost the batch response will not duplicate its
observation or completed session-end effects; if processing stopped after the
-observation commit, the retry re-runs downstream wiki/handoff work. Those
+observation commit, the retry re-runs downstream work. SessionEnd atomically
+commits its end watermark with its automatic handoff; a retry that finds that
+transaction complete finishes any interrupted wiki commit, durable provider
+enqueue, and ingest-key completion without adding a second handoff. Those
incomplete effects remain at-least-once until the server marks the event
complete.
On Unix, the helper uses a trusted `setsid` launcher when available and falls