Skip to content

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

Rust

fix(hooks): only synthesize a session page when the session did real work (#662)

AkitaOnRails3772088eeac6
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e07c1d64..b81f5198 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -77,6 +77,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
line is a hook log entry), moved into a shared `ledger` module so both
call sites stay in sync; a page literally named `log-2026-09.md` whose
body is prose is still migrated. (#669)
+- SessionEnd no longer writes an ephemeral `sessions/<id>.md` page for a
+ session that logged no real work. `is_lifecycle_only_session` treated a
+ session as skippable only when every observation was `SessionStart` or
+ `SessionEnd`, so a single `Stop` observation — which OpenCode fires for
+ purely internal work like branch-naming, alongside `session.created` +
+ `session.idle` with no user prompt and no tool use — was enough to make
+ the session look substantive and get a wiki page synthesized for it,
+ flooding the wiki with no-op session pages. "Substantive" is now defined
+ positively instead of negatively: a session counts as real work only if
+ it contains a `UserPrompt`, `PreToolUse`, or `PostToolUse` observation
+ (`is_ephemeral_session` in `ai-memory-hooks`). The atomic store-side
+ check (`end_lifecycle_only_session_in_tx` in `ai-memory-store`) moved to
+ the same positive `kind IN ('user-prompt', 'pre-tool-use',
+ 'post-tool-use')` test so the two stay in agreement, and the
+ PreCompact/PostCompaction checkpoint path gates on the same test rather
+ than only `observations.is_empty()`. Provider-agnostic: this fixes the
+ class for any harness that fires lifecycle-only `Stop`/`Notification`
+ events, not just OpenCode. (#662)
## [2.1.0] - 2026-09-06
diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rs
index 5c2a72f1..2ed4b477 100644
--- a/crates/ai-memory-hooks/src/router.rs
+++ b/crates/ai-memory-hooks/src/router.rs
@@ -2694,7 +2694,7 @@ async fn process_authorized(
Err(e) => warn!(error = %e, "SessionEnd recovery auto-commit failed"),
}
let observations = state.reader.observations_for_session(session_id).await?;
- if !is_lifecycle_only_session(&observations) {
+ if !is_ephemeral_session(&observations) {
enqueue_session_end_consolidation(
state,
session_id,
@@ -2803,7 +2803,7 @@ async fn process_authorized(
// Substantive sessions synthesize the summary page and auto-handoff below.
if matches!(env.event, HookEvent::SessionEnd) {
let mut observations = state.reader.observations_for_session(session_id).await?;
- if is_lifecycle_only_session(&observations) {
+ if is_ephemeral_session(&observations) {
let outcome = state
.writer
.end_admitted_lifecycle_only_session(admitted.clone())
@@ -2837,7 +2837,7 @@ async fn process_authorized(
);
// The writer observed substantive work, so the refreshed
// set cannot still satisfy the lifecycle-only predicate.
- debug_assert!(!is_lifecycle_only_session(&observations));
+ debug_assert!(!is_ephemeral_session(&observations));
}
}
}
@@ -3028,14 +3028,23 @@ fn resolve_native_session_id(raw: &str) -> SessionId {
.unwrap_or_else(|_| SessionId(Uuid::new_v5(&Uuid::NAMESPACE_OID, raw.as_bytes())))
}
-fn is_lifecycle_only_session(observations: &[ai_memory_core::Observation]) -> bool {
- !observations.is_empty()
- && observations.iter().all(|observation| {
- matches!(
- observation.kind,
- ObservationKind::SessionStart | ObservationKind::SessionEnd
- )
- })
+/// A session is substantive iff it logged at least one `UserPrompt`,
+/// `PreToolUse`, or `PostToolUse` observation. Everything else — including
+/// `Stop` and `Notification`, which some harnesses (e.g. OpenCode) fire for
+/// purely internal work such as branch-naming — is ephemeral/no-op and must
+/// not synthesize a session page. This positive definition MUST stay in sync
+/// with the store-side SQL in `end_lifecycle_only_session_in_tx`
+/// (ai-memory-store/src/ops.rs): both sides classify every observation set
+/// identically, or the atomic store re-check silently reverts this verdict.
+fn is_ephemeral_session(observations: &[ai_memory_core::Observation]) -> bool {
+ !observations.iter().any(|observation| {
+ matches!(
+ observation.kind,
+ ObservationKind::UserPrompt
+ | ObservationKind::PreToolUse
+ | ObservationKind::PostToolUse
+ )
+ })
}
fn build_auto_handoff(
@@ -3354,7 +3363,7 @@ async fn consolidate_or_synth(
}
}
let observations = state.reader.observations_for_session(session_id).await?;
- if observations.is_empty() {
+ if is_ephemeral_session(&observations) {
return Ok(());
}
let new_page = synthesize_session_page(
@@ -8046,6 +8055,49 @@ mod tests {
);
}
+ /// Reproduces the #662 OpenCode bug: an internal session (e.g.
+ /// branch-naming) that fires only lifecycle + `Stop` events, with no
+ /// user prompt and no tool use, must not flood the wiki with an
+ /// ephemeral `sessions/<id>.md` page.
+ #[tokio::test]
+ async fn stop_only_session_ends_without_writing_a_page() {
+ let tmp = TempDir::new().unwrap();
+ let state = make_state(&tmp).await;
+ let sid = "14141414-1414-1414-1414-141414141414";
+ for event in ["session-start", "stop", "session-end"] {
+ let env = HookEnvelope::from_query_and_body(
+ HookQuery {
+ event: event.into(),
+ agent: Some("opencode".into()),
+ ..Default::default()
+ },
+ serde_json::json!({ "session_id": sid }),
+ );
+ process(&state, env, None, Vec::new()).await.unwrap();
+ }
+
+ let pages = state
+ .reader
+ .recent_pages_for_project(state.workspace_id, state.project_id, 20)
+ .await
+ .unwrap();
+ assert!(
+ pages
+ .iter()
+ .all(|page| !page.path.as_str().starts_with("sessions/")),
+ "a Stop-only session with no prompt and no tool use must not synthesize a page; got {:?}",
+ pages.iter().map(|p| p.path.as_str()).collect::<Vec<_>>()
+ );
+ assert_eq!(
+ state
+ .reader
+ .latest_completed_session_for_project(state.workspace_id, state.project_id)
+ .await
+ .unwrap(),
+ Some(sid.parse().unwrap())
+ );
+ }
+
#[tokio::test]
async fn stop_does_not_end_session() {
let tmp = TempDir::new().unwrap();
@@ -11488,6 +11540,19 @@ mod tests {
);
process(&state, start, None, Vec::new()).await.unwrap();
+ // #662: checkpointing now gates on the same positive "has real work"
+ // test as SessionEnd, so a prompt must precede compaction for the
+ // rule-based checkpoint to have anything substantive to write.
+ let prompt = HookEnvelope::from_query_and_body(
+ HookQuery {
+ event: "user-prompt-submit".into(),
+ agent: Some("devin".into()),
+ ..Default::default()
+ },
+ serde_json::json!({ "session_id": sid }),
+ );
+ process(&state, prompt, None, Vec::new()).await.unwrap();
+
let pages_before = state
.reader
.recent_pages_for_project(state.workspace_id, state.project_id, 20)
@@ -12309,6 +12374,56 @@ mod tests {
}
}
+ // ── is_ephemeral_session: positive substantive-work predicate ─────────
+
+ #[test]
+ fn ephemeral_session_pure_lifecycle_and_stop_has_no_real_work() {
+ let observations = vec![
+ mk_obs(ObservationKind::SessionStart, "start", ""),
+ mk_obs(ObservationKind::Stop, "stop", ""),
+ mk_obs(ObservationKind::SessionEnd, "end", ""),
+ ];
+ assert!(
+ is_ephemeral_session(&observations),
+ "a Stop-only session (no prompt, no tool use) must be classified ephemeral, \
+ matching OpenCode's internal session.created/session.idle no-op sessions"
+ );
+ }
+
+ #[test]
+ fn ephemeral_session_empty_observations_is_ephemeral() {
+ assert!(is_ephemeral_session(&[]));
+ }
+
+ #[test]
+ fn ephemeral_session_with_user_prompt_is_not_ephemeral() {
+ let observations = vec![
+ mk_obs(ObservationKind::SessionStart, "start", ""),
+ mk_obs(ObservationKind::UserPrompt, "hello", "do the thing"),
+ mk_obs(ObservationKind::Stop, "stop", ""),
+ mk_obs(ObservationKind::SessionEnd, "end", ""),
+ ];
+ assert!(
+ !is_ephemeral_session(&observations),
+ "a session with a real user prompt must synthesize a page"
+ );
+ }
+
+ #[test]
+ fn ephemeral_session_with_tool_use_but_no_prompt_is_not_ephemeral() {
+ let observations = vec![
+ mk_obs(ObservationKind::SessionStart, "start", ""),
+ mk_obs(ObservationKind::PreToolUse, "Read", "README.md"),
+ mk_obs(ObservationKind::PostToolUse, "Read", "README.md"),
+ mk_obs(ObservationKind::Stop, "stop", ""),
+ mk_obs(ObservationKind::SessionEnd, "end", ""),
+ ];
+ assert!(
+ !is_ephemeral_session(&observations),
+ "tool-only work with no user prompt still counts as substantive"
+ );
+ }
+
#[test]
fn open_questions_extracts_question_mark_prompt() {
let obs = vec![
diff --git a/crates/ai-memory-store/src/ops.rs b/crates/ai-memory-store/src/ops.rs
index 48fde177..4d30aeca 100644
--- a/crates/ai-memory-store/src/ops.rs
+++ b/crates/ai-memory-store/src/ops.rs
@@ -1301,10 +1301,18 @@ fn end_lifecycle_only_session_in_tx(
tx: &Transaction<'_>,
session_id: &SessionId,
) -> StoreResult<LifecycleOnlyEndOutcome> {
+ // Substantive is defined POSITIVELY: at least one observation that is
+ // real work (a user prompt or a tool use). This MUST stay in sync with
+ // `is_ephemeral_session` in ai-memory-hooks/src/router.rs — both sides
+ // must classify every observation set identically, or this atomic
+ // re-check would silently revert the router's verdict. Everything else,
+ // including `stop` and `notification` (some harnesses, e.g. OpenCode,
+ // fire these for purely internal work), is ephemeral.
let has_substantive_observation: bool = tx.query_row(
"SELECT EXISTS( \
SELECT 1 FROM observations \
- WHERE session_id = ?1 AND kind NOT IN ('session-start', 'session-end') \
+ WHERE session_id = ?1 \
+ AND kind IN ('user-prompt', 'pre-tool-use', 'post-tool-use') \
)",
params![session_id.as_bytes()],
|row| row.get(0),
@@ -7133,6 +7141,94 @@ pub(crate) mod tests {
assert_eq!(state, "accepted");
}
+ /// Pins the two-sided invariant with `is_ephemeral_session` in
+ /// ai-memory-hooks/src/router.rs: a session with only `session-start`,
+ /// `stop`, `session-end` (the #662 OpenCode internal-session shape) has
+ /// no positive-work observation and must end as `Ended`, not
+ /// `Substantive`.
+ #[test]
+ fn end_lifecycle_only_session_treats_stop_only_session_as_ended() {
+ let (_tmp, mut conn, ws, proj) = fresh_db();
+ let receiver = SessionId::new();
+ begin_session(
+ &mut conn,
+ &NewSession {
+ id: receiver,
+ workspace_id: ws,
+ project_id: proj,
+ agent_kind: AgentKind::OpenCode,
+ cwd: Some("/repo".into()),
+ actor_user: None,
+ },
+ )
+ .unwrap();
+ insert_observation(
+ &mut conn,
+ &NewObservation {
+ session_id: receiver,
+ workspace_id: ws,
+ project_id: proj,
+ kind: ObservationKind::Stop,
+ extension: None,
+ source_event: None,
+ title: "stop".into(),
+ body: String::new(),
+ importance: 5,
+ },
+ )
+ .unwrap();
+
+ assert_eq!(
+ end_lifecycle_only_session(&mut conn, &receiver).unwrap(),
+ LifecycleOnlyEndOutcome::Ended {
+ reopened_handoff: None
+ },
+ "a Stop-only session has no user-prompt/pre-tool-use/post-tool-use \
+ observation, so it must be classified ended, not substantive"
+ );
+ }
+
+ /// Companion to the Stop-only case above: a `user-prompt` observation
+ /// alone (no lifecycle bookends yet inserted beyond SessionStart) makes
+ /// the session substantive.
+ #[test]
+ fn end_lifecycle_only_session_treats_user_prompt_as_substantive() {
+ let (_tmp, mut conn, ws, proj) = fresh_db();
+ let receiver = SessionId::new();
+ begin_session(
+ &mut conn,
+ &NewSession {
+ id: receiver,
+ workspace_id: ws,
+ project_id: proj,
+ agent_kind: AgentKind::OpenCode,
+ cwd: Some("/repo".into()),
+ actor_user: None,
+ },
+ )
+ .unwrap();
+ insert_observation(
+ &mut conn,
+ &NewObservation {
+ session_id: receiver,
+ workspace_id: ws,
+ project_id: proj,
+ kind: ObservationKind::UserPrompt,
+ extension: None,
+ source_event: None,
+ title: "hello".into(),
+ body: "do the thing".into(),
+ importance: 5,
+ },
+ )
+ .unwrap();
+
+ assert_eq!(
+ end_lifecycle_only_session(&mut conn, &receiver).unwrap(),
+ LifecycleOnlyEndOutcome::Substantive
+ );
+ }
+
#[test]
fn failed_auto_handoff_insert_rolls_back_same_cwd_expiration() {
let (_tmp, mut conn, ws, proj) = fresh_db();