Skip to content

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

Rust

fix(hooks): claim complete startup context atomically

AkitaOnRailsea354e6ebf97
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 115feb00..779ee682 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -54,6 +54,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
now always pass `-i`, while `-t` is added only when stdin and stdout are
both terminals. `AI_MEMORY_NO_TTY=1` disables only TTY allocation and
no longer disconnects stdin. (#243)
+- Managed `SessionStart` delivery now includes a pending single-use
+ handoff before the portable workstream ledger and optional project
+ brief. Handoff and ledger acknowledgements are claimed together only
+ after the complete response has been assembled; a failed or racing
+ ledger claim cannot consume the handoff or suppress retry delivery.
+ (#235)
## [1.18.0] - 2026-07-23
diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rs
index 66bc9e3c..0ecf8ddc 100644
--- a/crates/ai-memory-hooks/src/router.rs
+++ b/crates/ai-memory-hooks/src/router.rs
@@ -1090,7 +1090,7 @@ async fn fetch_and_accept_handoff(
// too. The brief already reaches the managed path (it is recomposed per
// session, so resolving it twice was harmless); the handoff is single-use
// and had no second chance.
- let managed_md = fetch_managed_context(state, &query, agent).await?;
+ let managed = fetch_managed_context(state, &query, agent).await?;
// `/handoff` has no session_id in the request — `per_session` mode
// therefore falls back to the single slot (graceful degradation),
// while `per_actor` keys by `user` alone.
@@ -1110,32 +1110,54 @@ async fn fetch_and_accept_handoff(
false,
)
.await?;
- let handoff_md = {
- let handoff = state
- .reader
- .latest_open_handoff(ws, proj, query.cwd.clone())
- .await?;
- match handoff {
- Some(h) => {
- state.writer.accept_handoff(h.id, agent, None).await?;
- Some(render_handoff_markdown(&h))
- }
- None => None,
- }
- };
+ let handoff = state
+ .reader
+ .latest_open_handoff(ws, proj, query.cwd.clone())
+ .await?;
+ let handoff_md = handoff.as_ref().map(render_handoff_markdown);
// The brief is additive and non-destructive: unlike the handoff (a
- // single-use slot consumed above), it is recomposed on every opted-in
+ // single-use slot claimed below), it is recomposed on every opted-in
// session start — exactly what a Claude Code `/clear` needs (#176).
let brief_md = render_requested_session_brief(state, &query, ws, proj).await?;
// Handoff first: it is a short curated pointer and must not be buried
// under a ledger that can run tens of KB. The existing ledger-then-brief
- // order is preserved.
+ // order is preserved. Claim both single-use inputs only after every
+ // fallible read and render has succeeded, and in one transaction so a
+ // failed or racing managed claim cannot consume the handoff by itself.
+ let acceptance = if handoff.is_some() || managed.is_some() {
+ state
+ .writer
+ .accept_startup_context(
+ handoff.as_ref().map(|handoff| handoff.id),
+ agent,
+ None,
+ managed.as_ref().map(|managed| managed.run_id),
+ )
+ .await?
+ } else {
+ ai_memory_store::StartupContextAcceptance::default()
+ };
+ let handoff_md = if acceptance.handoff_accepted {
+ handoff_md
+ } else {
+ None
+ };
+ let managed_md = if acceptance.managed_context_accepted {
+ managed.and_then(|managed| managed.markdown)
+ } else {
+ None
+ };
Ok(combine_handoff_and_brief(
handoff_md,
combine_handoff_and_brief(managed_md, brief_md),
))
}
+struct PendingManagedContext {
+ run_id: ManagedRunId,
+ markdown: Option<String>,
+}
+
/// Render the managed-run ledger for this SessionStart, if there is one.
///
/// Returns `None` — never an early exit for the caller — when the run is
@@ -1146,7 +1168,7 @@ async fn fetch_managed_context(
state: &HookState,
query: &HandoffQuery,
agent: AgentKind,
-) -> anyhow::Result<Option<String>> {
+) -> anyhow::Result<Option<PendingManagedContext>> {
let Some(raw_run_id) = query.managed_run.as_deref() else {
return Ok(None);
};
@@ -1186,8 +1208,10 @@ async fn fetch_managed_context(
context.workstream_id,
context.sync_after,
);
- let _ = state.writer.accept_managed_run_context(run_id).await?;
- Ok(rendered)
+ Ok(Some(PendingManagedContext {
+ run_id,
+ markdown: rendered,
+ }))
}
async fn render_requested_session_brief(
@@ -5732,23 +5756,20 @@ mod tests {
.await
.unwrap();
- let rendered = fetch_and_accept_handoff(
- &state,
- HandoffQuery {
- agent: Some("codex".into()),
- cwd: Some(cwd),
- workspace: Some("default".into()),
- project: Some("scratch".into()),
- project_strategy: None,
- briefing: None,
- briefing_budget: None,
- managed_run: Some(run.run_id.to_string()),
- session_id: Some("native-2".into()),
- },
- None,
- )
- .await
- .unwrap();
+ let query = HandoffQuery {
+ agent: Some("codex".into()),
+ cwd: Some(cwd),
+ workspace: Some("default".into()),
+ project: Some("scratch".into()),
+ project_strategy: None,
+ briefing: None,
+ briefing_budget: None,
+ managed_run: Some(run.run_id.to_string()),
+ session_id: Some("native-2".into()),
+ };
+ let rendered = fetch_and_accept_handoff(&state, query.clone(), None)
+ .await
+ .unwrap();
let rendered = rendered.expect("managed SessionStart must return context");
assert!(
@@ -5768,6 +5789,13 @@ mod tests {
.is_none(),
"a handoff delivered on a managed SessionStart must be marked accepted"
);
+ assert!(
+ fetch_and_accept_handoff(&state, query, None)
+ .await
+ .unwrap()
+ .is_none(),
+ "the combined handoff and managed packet must be delivered only once"
+ );
}
fn brief_page(
diff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rs
index 0a58c479..ced1ada8 100644
--- a/crates/ai-memory-store/src/lib.rs
+++ b/crates/ai-memory-store/src/lib.rs
@@ -60,7 +60,7 @@ pub use workstream::{
FinishWorkstreamRun, FinishedWorkstreamRun, ManagedRunContext, PrepareWorkstreamRun,
PreparedWorkstreamRun, StoredManagedRunStatus, WorkstreamSelection,
};
-pub use writer::WriterHandle;
+pub use writer::{StartupContextAcceptance, WriterHandle};
/// Filename used inside the data dir's `db/` subdirectory.
pub const DB_FILENAME: &str = "memory.sqlite";
@@ -122,9 +122,9 @@ impl Store {
mod tests {
use super::*;
use ai_memory_core::{
- ActorContext, AgentKind, LinkTarget, ManagedRunId, NewObservation, NewPage, NewSession,
- NewWorkstreamEvent, ObservationId, ObservationKind, PageId, PagePath, ProjectId, Sanitized,
- Sanitizer, SessionId, Tier, UserId, WorkspaceId, WorkstreamEventKind,
+ ActorContext, AgentKind, LinkTarget, ManagedRunId, NewHandoff, NewObservation, NewPage,
+ NewSession, NewWorkstreamEvent, ObservationId, ObservationKind, PageId, PagePath,
+ ProjectId, Sanitized, Sanitizer, SessionId, Tier, UserId, WorkspaceId, WorkstreamEventKind,
};
use rusqlite::{Connection, params};
use sha2::{Digest, Sha256};
@@ -4419,6 +4419,84 @@ mod tests {
);
}
+ #[tokio::test]
+ async fn startup_context_claim_is_atomic_and_single_use() {
+ let tmp = TempDir::new().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let (ws, proj) = open_managed_scope(&store, "startup-claim").await;
+ let run = store
+ .writer
+ .prepare_workstream_run(managed_prepare_input(ws, proj, "test:1"))
+ .await
+ .unwrap();
+ let insert_handoff = || NewHandoff {
+ workspace_id: ws,
+ project_id: proj,
+ from_session_id: None,
+ from_agent: AgentKind::ClaudeCode,
+ to_agent: None,
+ cwd: None,
+ summary: "continue".into(),
+ open_questions: Vec::new(),
+ next_steps: Vec::new(),
+ files_touched: Vec::new(),
+ };
+
+ let first_handoff = store.writer.insert_handoff(insert_handoff()).await.unwrap();
+ let accepted = store
+ .writer
+ .accept_startup_context(
+ Some(first_handoff),
+ AgentKind::Codex,
+ None,
+ Some(run.run_id),
+ )
+ .await
+ .unwrap();
+ assert_eq!(
+ accepted,
+ StartupContextAcceptance {
+ handoff_accepted: true,
+ managed_context_accepted: true,
+ }
+ );
+ assert!(
+ store
+ .reader
+ .latest_open_handoff(ws, proj, None)
+ .await
+ .unwrap()
+ .is_none()
+ );
+
+ let second_handoff = store.writer.insert_handoff(insert_handoff()).await.unwrap();
+ let rejected = store
+ .writer
+ .accept_startup_context(
+ Some(second_handoff),
+ AgentKind::Codex,
+ None,
+ Some(run.run_id),
+ )
+ .await
+ .unwrap();
+ assert_eq!(
+ rejected,
+ StartupContextAcceptance::default(),
+ "an already-delivered managed packet must reject the whole claim"
+ );
+ assert_eq!(
+ store
+ .reader
+ .latest_open_handoff(ws, proj, None)
+ .await
+ .unwrap()
+ .map(|handoff| handoff.id),
+ Some(second_handoff),
+ "a failed managed claim must roll back the handoff transition"
+ );
+ }
+
#[tokio::test]
async fn run_context_delivers_newest_events_in_sequence_order() {
let tmp = TempDir::new().unwrap();
diff --git a/crates/ai-memory-store/src/ops.rs b/crates/ai-memory-store/src/ops.rs
index 513d48d6..6c08c160 100644
--- a/crates/ai-memory-store/src/ops.rs
+++ b/crates/ai-memory-store/src/ops.rs
@@ -57,7 +57,7 @@ pub struct PurgeSummary {
pub embeddings_deleted: u64,
}
use jiff::Timestamp;
-use rusqlite::{Connection, OptionalExtension, params};
+use rusqlite::{Connection, OptionalExtension, Transaction, params};
use sha2::{Digest, Sha256};
use crate::error::{StoreError, StoreResult};
@@ -1242,11 +1242,22 @@ pub fn accept_handoff(
accepting_agent: AgentKind,
accepting_session: Option<&SessionId>,
) -> StoreResult<()> {
+ let tx = conn.transaction()?;
+ accept_handoff_in_transaction(&tx, handoff_id, accepting_agent, accepting_session)?;
+ tx.commit()?;
+ Ok(())
+}
+
+pub(crate) fn accept_handoff_in_transaction(
+ tx: &Transaction<'_>,
+ handoff_id: &HandoffId,
+ accepting_agent: AgentKind,
+ accepting_session: Option<&SessionId>,
+) -> StoreResult<bool> {
let now = Timestamp::now().as_microsecond();
let agent = accepting_agent.as_str();
let session: Option<&[u8]> = accepting_session.map(|s| &s.as_bytes()[..]);
- let tx = conn.transaction()?;
- let (ws, proj) = handoff_scope(&tx, handoff_id)?;
+ let (ws, proj) = handoff_scope(tx, handoff_id)?;
let changed = tx.execute(
"UPDATE handoffs SET state = 'accepted', accepted_by = ?1, accepted_at = ?2, \
accepted_by_session = ?3 \
@@ -1256,7 +1267,7 @@ pub fn accept_handoff(
// Only a real state transition ('open' -> 'accepted') is audited.
if changed > 0 {
audit(
- &tx,
+ tx,
"accept_handoff",
ws.as_ref(),
proj.as_ref(),
@@ -1265,8 +1276,7 @@ pub fn accept_handoff(
now,
)?;
}
- tx.commit()?;
- Ok(())
+ Ok(changed > 0)
}
/// Mark an open handoff expired so it will no longer be consumed.
diff --git a/crates/ai-memory-store/src/workstream.rs b/crates/ai-memory-store/src/workstream.rs
index b792d89c..a26e2bc3 100644
--- a/crates/ai-memory-store/src/workstream.rs
+++ b/crates/ai-memory-store/src/workstream.rs
@@ -517,13 +517,31 @@ pub(crate) fn link_native_session(
/// Mark the assigned synchronization packet delivered to SessionStart.
pub(crate) fn accept_context(conn: &mut Connection, run_id: ManagedRunId) -> StoreResult<bool> {
- let now = Timestamp::now().as_microsecond();
let tx = conn.transaction()?;
+ let accepted = accept_context_in_transaction(&tx, run_id, false)?;
+ tx.commit()?;
+ Ok(accepted)
+}
+
+pub(crate) fn claim_context_in_transaction(
+ tx: &Transaction<'_>,
+ run_id: ManagedRunId,
+) -> StoreResult<bool> {
+ accept_context_in_transaction(tx, run_id, true)
+}
+
+fn accept_context_in_transaction(
+ tx: &Transaction<'_>,
+ run_id: ManagedRunId,
+ require_undelivered: bool,
+) -> StoreResult<bool> {
+ let now = Timestamp::now().as_microsecond();
let run: Option<(Vec<u8>, String, Option<String>, i64)> = tx
.query_row(
"SELECT workstream_id, agent_kind, native_session_id, sync_through \
- FROM managed_runs WHERE id = ?1 AND state = 'active'",
- params![run_id.as_bytes()],
+ FROM managed_runs WHERE id = ?1 AND state = 'active' \
+ AND (?2 = 0 OR context_delivered = 0)",
+ params![run_id.as_bytes(), i64::from(require_undelivered)],
|row| Ok((row.get(0)?, row.get(1)?, row.get(2)?, row.get(3)?)),
)
.optional()?;
@@ -543,7 +561,6 @@ pub(crate) fn accept_context(conn: &mut Connection, run_id: ManagedRunId) -> Sto
params![sync_through, now, workstream, agent, native_session],
)?;
}
- tx.commit()?;
Ok(true)
}
diff --git a/crates/ai-memory-store/src/writer.rs b/crates/ai-memory-store/src/writer.rs
index 1d986633..0a31bc59 100644
--- a/crates/ai-memory-store/src/writer.rs
+++ b/crates/ai-memory-store/src/writer.rs
@@ -31,6 +31,15 @@ use crate::workstream::{
FinishWorkstreamRun, FinishedWorkstreamRun, PrepareWorkstreamRun, PreparedWorkstreamRun,
};
+/// Result of atomically claiming the startup context assembled for one hook.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub struct StartupContextAcceptance {
+ /// The requested single-use handoff changed from open to accepted.
+ pub handoff_accepted: bool,
+ /// The requested managed synchronization packet changed to delivered.
+ pub managed_context_accepted: bool,
+}
+
/// Commands accepted by the writer thread.
pub(crate) enum WriteCmd {
GetOrCreateWorkspace {
@@ -294,6 +303,13 @@ pub(crate) enum WriteCmd {
run_id: ManagedRunId,
reply: oneshot::Sender<StoreResult<bool>>,
},
+ AcceptStartupContext {
+ handoff_id: Option<HandoffId>,
+ accepting_agent: AgentKind,
+ accepting_session: Option<SessionId>,
+ managed_run_id: Option<ManagedRunId>,
+ reply: oneshot::Sender<StoreResult<StartupContextAcceptance>>,
+ },
FinishWorkstreamRun {
input: FinishWorkstreamRun,
reply: oneshot::Sender<StoreResult<FinishedWorkstreamRun>>,
@@ -1175,6 +1191,30 @@ impl WriterHandle {
rx.await.map_err(|_| StoreError::WriterClosed)?
}
+ /// Atomically claim the handoff and managed ledger selected for one
+ /// SessionStart response.
+ ///
+ /// When a managed run was requested but is no longer claimable, the
+ /// handoff remains open and both result fields are false.
+ pub async fn accept_startup_context(
+ &self,
+ handoff_id: Option<HandoffId>,
+ accepting_agent: AgentKind,
+ accepting_session: Option<SessionId>,
+ managed_run_id: Option<ManagedRunId>,
+ ) -> StoreResult<StartupContextAcceptance> {
+ let (tx, rx) = oneshot::channel();
+ self.send(WriteCmd::AcceptStartupContext {
+ handoff_id,
+ accepting_agent,
+ accepting_session,
+ managed_run_id,
+ reply: tx,
+ })
+ .await?;
+ rx.await.map_err(|_| StoreError::WriterClosed)?
+ }
+
/// Index an immutable transcript segment and release the run lease.
pub async fn finish_workstream_run(
&self,
@@ -1587,6 +1627,41 @@ fn worker_loop(mut conn: Connection, mut rx: mpsc::Receiver<WriteCmd>) {
let result = crate::workstream::accept_context(&mut conn, run_id);
send_or_warn(reply, result, "accept_managed_run_context");
}
+ WriteCmd::AcceptStartupContext {
+ handoff_id,
+ accepting_agent,
+ accepting_session,
+ managed_run_id,
+ reply,
+ } => {
+ let result = (|| {
+ let tx = conn.transaction()?;
+ let managed_context_accepted = match managed_run_id {
+ Some(run_id) => {
+ crate::workstream::claim_context_in_transaction(&tx, run_id)?
+ }
+ None => false,
+ };
+ if managed_run_id.is_some() && !managed_context_accepted {
+ return Ok(StartupContextAcceptance::default());
+ }
+ let handoff_accepted = match handoff_id {
+ Some(handoff_id) => ops::accept_handoff_in_transaction(
+ &tx,
+ &handoff_id,
+ accepting_agent,
+ accepting_session.as_ref(),
+ )?,
+ None => false,
+ };
+ tx.commit()?;
+ Ok(StartupContextAcceptance {
+ handoff_accepted,
+ managed_context_accepted,
+ })
+ })();
+ send_or_warn(reply, result, "accept_startup_context");
+ }
WriteCmd::FinishWorkstreamRun { input, reply } => {
let result = crate::workstream::finish_run(&mut conn, &input);
send_or_warn(reply, result, "finish_workstream_run");
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 82d36fb5..7869e110 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -118,6 +118,9 @@ session, and marks lifecycle calls with an invocation-scoped run id.
SessionStart injects an unseen bounded event range; Crush receives it through a
temporary supported global-context path because it lacks SessionStart. The host
imports the native transcript tail and a Git checkpoint when the child exits.
+An explicitly pending handoff is delivered before the managed event range;
+their single-use delivery claims share one writer transaction after the
+complete startup response has been assembled.
ai-memory opens native stores read-only. Raw sanitized JSONL segments are
immutable, while SQLite supplies monotonic sequences, FTS, native
source/delivery cursors, and idempotent retry state. A full-ledger
diff --git a/docs/design-decisions.md b/docs/design-decisions.md
index a2d94e73..eed8323b 100644
--- a/docs/design-decisions.md
+++ b/docs/design-decisions.md
@@ -300,10 +300,13 @@ are excluded explicitly.
A renewable single-writer lease resolves precedence and concurrency instead of
attempting bidirectional file synchronization. SessionStart receives a bounded
-unseen delta; the full visible ledger stays searchable. Repository checkpoints
-are evidence at run boundaries and never commit, stash, reset, or otherwise
-mutate the checkout. The markdown wiki remains the durable knowledge surface;
-the managed ledger is an operational continuity substrate.
+unseen delta without replacing an explicitly pending handoff. When both exist,
+the curated handoff is rendered first and their delivery claims commit
+atomically after the complete startup response is assembled. The full visible
+ledger stays searchable. Repository checkpoints are evidence at run boundaries
+and never commit, stash, reset, or otherwise mutate the checkout. The markdown
+wiki remains the durable knowledge surface; the managed ledger is an
+operational continuity substrate.
Native-session adoption is restricted to bootstrapping an otherwise-empty
workstream. The interactive launcher may offer recent sessions recorded for the
diff --git a/docs/managed-workstreams.md b/docs/managed-workstreams.md
index 24991cde..c22ee7fd 100644
--- a/docs/managed-workstreams.md
+++ b/docs/managed-workstreams.md
@@ -94,8 +94,11 @@ consume the later adoption opportunity.
The UserPromptSubmit hook issues the `/handoff` GET with the native
`session_id` in the query; the server links the session and renders the
packet atomically, and Kimi Code injects the hook's stdout as a user
- message before the turn. Direct launches continue to use the existing
- single-use handoff path.
+ message before the turn. A pending single-use handoff remains additive:
+ it is placed before the managed packet, and both delivery claims commit
+ together only after the full handoff/packet/brief response is assembled.
+ Direct launches continue to use the same handoff path without a managed
+ packet.
4. When the child exits, ai-memory reads the native transcript store without
modifying it. Visible user/assistant messages, completed tool calls/results,
compaction summaries, and a non-mutating Git checkpoint enter an append-only