Skip to content

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

Rust

fix(hooks): trigger detached drains at safe boundaries

AkitaOnRailsaaf934174c7d
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f29de938..1e65a707 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Fixed
+- Native hook spool delivery no longer relies only on the cancellation-prone
+ `session-end` hook to start the detached drainer. `stop` and `pre-compact`
+ also request the background `hook-drain` helper after enqueue, and Unix builds
+ use a trusted `setsid` launcher when available before falling back to a
+ separate process group.
- OpenCode generated plugins now close sessions from the official
`session.deleted` event and a deduped best-effort `dispose` fallback, so
OpenCode sessions can produce automatic session summaries and handoffs without
diff --git a/crates/ai-memory-cli/src/commands/hook.rs b/crates/ai-memory-cli/src/commands/hook.rs
index 3beb871d..2881eff6 100644
--- a/crates/ai-memory-cli/src/commands/hook.rs
+++ b/crates/ai-memory-cli/src/commands/hook.rs
@@ -105,17 +105,21 @@ fn incremental_drain_threshold_from(mut lookup: impl FnMut(&str) -> Option<Strin
/// Whether to run a mid-session catch-up drain for this event: only
/// `post-tool-use` (the highest-frequency event) and only once the spool backlog
-/// has crossed `threshold`. Boundaries (`session-start`/`session-end`) remain
-/// the main flush, so a light session never drains mid-session.
+/// has crossed `threshold`. Boundaries run their own cleanup/background drains,
+/// so a light session never drains mid-session.
fn should_incremental_drain(event: &str, spool_len: usize, threshold: usize) -> bool {
event == "post-tool-use" && spool_len >= threshold
}
-fn spawn_session_end_drainer(data_dir: &Path) -> std::io::Result<()> {
+fn spawn_background_drainer(data_dir: &Path) -> std::io::Result<()> {
hook_drain_process::spawn(data_dir)
}
-fn after_session_end_enqueue(
+fn should_spawn_background_drainer(event: &str) -> bool {
+ matches!(event, "session-end" | "stop" | "pre-compact")
+}
+
+fn after_background_drain_event_enqueue(
data_dir: &Path,
spawn: impl FnOnce(&Path) -> std::io::Result<()>,
) -> std::io::Result<()> {
@@ -182,7 +186,7 @@ pub async fn run(data_dir: Option<PathBuf>, args: HookArgs) -> anyhow::Result<()
args,
payload,
&mut stdout,
- spawn_session_end_drainer,
+ spawn_background_drainer,
)
.await
}
@@ -192,7 +196,7 @@ async fn run_with_payload<W, S>(
args: HookArgs,
payload: String,
stdout: &mut W,
- spawn_session_end_drainer: S,
+ spawn_background_drainer: S,
) -> anyhow::Result<()>
where
W: std::io::Write,
@@ -283,10 +287,12 @@ where
}
}
- // session-end: enqueue and hand delivery to a detached native drainer so the
- // agent quit path is not cancelled while the server processes backlog.
- if args.event == "session-end"
- && let Err(err) = after_session_end_enqueue(&dd, spawn_session_end_drainer)
+ // Boundary drain trigger: enqueue first, then ask a detached native drainer
+ // to flush the shared spool. `session-end` remains the primary close path,
+ // but `stop` and `pre-compact` also trigger the helper so delivery does not
+ // rely on the single hook most likely to be cancelled during agent shutdown.
+ if should_spawn_background_drainer(&args.event)
+ && let Err(err) = after_background_drain_event_enqueue(&dd, spawn_background_drainer)
{
eprintln!(
"ai-memory hook warning: failed to start background spool drainer; event remains queued: {err}"
@@ -352,6 +358,18 @@ mod tests {
assert!(!should_incremental_drain("stop", 999, 32));
}
+ #[test]
+ fn boundary_events_trigger_background_drainer() {
+ assert!(should_spawn_background_drainer("session-end"));
+ assert!(should_spawn_background_drainer("stop"));
+ assert!(should_spawn_background_drainer("pre-compact"));
+
+ assert!(!should_spawn_background_drainer("session-start"));
+ assert!(!should_spawn_background_drainer("post-tool-use"));
+ assert!(!should_spawn_background_drainer("pre-tool-use"));
+ assert!(!should_spawn_background_drainer("user-prompt"));
+ }
+
#[test]
fn incremental_threshold_parses_and_falls_back() {
assert_eq!(incremental_drain_threshold_from(|_| Some("64".into())), 64);
@@ -467,6 +485,47 @@ mod tests {
);
}
+ #[tokio::test]
+ async fn stop_and_pre_compact_spawn_background_drainer_after_enqueue() {
+ for event in ["stop", "pre-compact"] {
+ let tmp = tempfile::tempdir().unwrap();
+ let data_dir = tmp.path().to_path_buf();
+ let spool = hook_spool::spool_dir(&data_dir);
+ let called = std::cell::Cell::new(0);
+ let mut stdout = Vec::new();
+ let args = HookArgs {
+ event: event.into(),
+ agent: "claude-code".into(),
+ server_url: "http://127.0.0.1:1".into(),
+ auth_token: None,
+ project_strategy: None,
+ };
+
+ run_with_payload(
+ Some(data_dir.clone()),
+ args,
+ r#"{"session_id":"s","cwd":"/tmp"}"#.into(),
+ &mut stdout,
+ |path| {
+ assert_eq!(path, data_dir.as_path());
+ assert_eq!(hook_spool::spool_len(&spool), 1, "spawn runs after enqueue");
+ called.set(called.get() + 1);
+ Ok(())
+ },
+ )
+ .await
+ .unwrap();
+
+ assert_eq!(stdout, b"{}\n", "{event} should keep hook stdout clean");
+ assert_eq!(called.get(), 1, "{event} should start background drain");
+ assert_eq!(
+ hook_spool::spool_len(&spool),
+ 1,
+ "{event} must not drain inline"
+ );
+ }
+ }
+
#[tokio::test]
async fn session_end_run_spawn_failure_keeps_event_queued_and_stdout_clean() {
let tmp = tempfile::tempdir().unwrap();
@@ -494,7 +553,7 @@ mod tests {
#[test]
fn session_end_spawn_failure_is_returned_for_warning_only() {
let tmp = tempfile::tempdir().unwrap();
- let err = after_session_end_enqueue(tmp.path(), |_path| {
+ let err = after_background_drain_event_enqueue(tmp.path(), |_path| {
Err(std::io::Error::other("spawn failed"))
})
.unwrap_err();
@@ -503,11 +562,11 @@ mod tests {
}
#[test]
- fn session_end_policy_spawns_without_inline_drain() {
+ fn background_drain_event_policy_spawns_without_inline_drain() {
let tmp = tempfile::tempdir().unwrap();
let called = std::cell::Cell::new(false);
- after_session_end_enqueue(tmp.path(), |path| {
+ after_background_drain_event_enqueue(tmp.path(), |path| {
assert_eq!(path, tmp.path());
called.set(true);
Ok(())
diff --git a/crates/ai-memory-cli/src/commands/hook_drain_process.rs b/crates/ai-memory-cli/src/commands/hook_drain_process.rs
index 87a50dae..17f2e457 100644
--- a/crates/ai-memory-cli/src/commands/hook_drain_process.rs
+++ b/crates/ai-memory-cli/src/commands/hook_drain_process.rs
@@ -33,9 +33,10 @@ pub struct SpawnConfig {
/// Platform detach configuration.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum DetachConfig {
- /// Unix starts a new process group.
+ /// Unix starts the drainer in a new session through a trusted `setsid`
+ /// launcher when available; otherwise it falls back to a new process group.
#[cfg(unix)]
- UnixProcessGroupZero,
+ UnixNewSession { setsid: Option<PathBuf> },
/// Windows creation flags.
#[cfg(windows)]
WindowsCreationFlags(u32),
@@ -84,13 +85,11 @@ fn spawn_spec(spec: &DrainCommandSpec) -> io::Result<()> {
.append(true)
.open(&config.stderr_file)?;
- let mut command = Command::new(&spec.exe);
+ let mut command = command_for_spec(spec, &config.detach);
command
- .args(&spec.args)
.stdin(Stdio::null())
.stdout(Stdio::null())
.stderr(Stdio::from(stderr));
- apply_detach_flags(&mut command, &config.detach);
match command.spawn() {
Ok(_child) => Ok(()),
@@ -108,13 +107,11 @@ fn spawn_spec(spec: &DrainCommandSpec) -> io::Result<()> {
.create(true)
.append(true)
.open(&config.stderr_file)?;
- let mut retry = Command::new(&spec.exe);
+ let mut retry = command_for_spec(spec, &config.detach);
retry
- .args(&spec.args)
.stdin(Stdio::null())
.stdout(Stdio::null())
.stderr(Stdio::from(stderr));
- apply_detach_flags(&mut retry, &config.detach);
retry.spawn().map(|_| ())
}
Err(err) => Err(err),
@@ -123,17 +120,40 @@ fn spawn_spec(spec: &DrainCommandSpec) -> io::Result<()> {
#[cfg(unix)]
fn detach_config(_try_breakaway: bool) -> DetachConfig {
- DetachConfig::UnixProcessGroupZero
+ DetachConfig::UnixNewSession {
+ setsid: trusted_setsid_launcher(),
+ }
}
#[cfg(unix)]
-fn apply_detach_flags(command: &mut Command, detach: &DetachConfig) {
+fn command_for_spec(spec: &DrainCommandSpec, detach: &DetachConfig) -> Command {
use std::os::unix::process::CommandExt as _;
- if matches!(detach, DetachConfig::UnixProcessGroupZero) {
- command.process_group(0);
+
+ match detach {
+ DetachConfig::UnixNewSession {
+ setsid: Some(setsid),
+ } => {
+ let mut command = Command::new(setsid);
+ command.arg(&spec.exe).args(&spec.args);
+ command
+ }
+ DetachConfig::UnixNewSession { setsid: None } => {
+ let mut command = Command::new(&spec.exe);
+ command.args(&spec.args);
+ command.process_group(0);
+ command
+ }
}
}
+#[cfg(unix)]
+fn trusted_setsid_launcher() -> Option<PathBuf> {
+ [Path::new("/usr/bin/setsid"), Path::new("/bin/setsid")]
+ .into_iter()
+ .find(|path| path.is_file())
+ .map(Path::to_path_buf)
+}
+
#[cfg(windows)]
fn detach_config(try_breakaway: bool) -> DetachConfig {
const DETACHED_PROCESS: u32 = 0x0000_0008;
@@ -156,13 +176,25 @@ fn apply_detach_flags(command: &mut Command, detach: &DetachConfig) {
}
}
+#[cfg(windows)]
+fn command_for_spec(spec: &DrainCommandSpec, detach: &DetachConfig) -> Command {
+ let mut command = Command::new(&spec.exe);
+ command.args(&spec.args);
+ apply_detach_flags(&mut command, detach);
+ command
+}
+
#[cfg(not(any(unix, windows)))]
fn detach_config(_try_breakaway: bool) -> DetachConfig {
DetachConfig::None
}
#[cfg(not(any(unix, windows)))]
-fn apply_detach_flags(_command: &mut Command, _detach: &DetachConfig) {}
+fn command_for_spec(spec: &DrainCommandSpec, _detach: &DetachConfig) -> Command {
+ let mut command = Command::new(&spec.exe);
+ command.args(&spec.args);
+ command
+}
#[cfg(not(windows))]
fn should_retry_without_breakaway(_err: &io::Error) -> bool {
@@ -213,13 +245,16 @@ mod tests {
#[cfg(unix)]
#[test]
- fn unix_spawn_config_uses_process_group_zero() {
+ fn unix_spawn_config_prefers_true_session_detach_when_available() {
let tmp = tempfile::tempdir().unwrap();
let spec = command_spec(tmp.path()).unwrap();
- assert_eq!(
- spawn_config(&spec, true).detach,
- DetachConfig::UnixProcessGroupZero
- );
+ let DetachConfig::UnixNewSession { setsid } = spawn_config(&spec, true).detach;
+ if let Some(path) = setsid {
+ assert!(
+ path == Path::new("/usr/bin/setsid") || path == Path::new("/bin/setsid"),
+ "only trusted absolute setsid launchers are used: {path:?}"
+ );
+ }
}
#[cfg(windows)]
diff --git a/crates/ai-memory-cli/src/commands/hook_spool.rs b/crates/ai-memory-cli/src/commands/hook_spool.rs
index e2c02aad..f7af1f87 100644
--- a/crates/ai-memory-cli/src/commands/hook_spool.rs
+++ b/crates/ai-memory-cli/src/commands/hook_spool.rs
@@ -1,11 +1,13 @@
//! Local spool for lifecycle-hook events — decouples capture from the network.
//!
-//! Per-tool-call hooks (`pre-tool-use`, `post-tool-use`, `user-prompt-submit`,
-//! `stop`) append an event here (an instant local write) instead of POSTing
-//! synchronously. The spool is drained to the server at **session boundaries**
-//! (a cleanup pass at `session-start`, the main flush at `session-end`), where a
-//! few seconds of latency is acceptable — unlike the per-tool-call hot path,
-//! which must never block the agent.
+//! Per-tool-call hooks (`pre-tool-use`, `post-tool-use`, `user-prompt-submit`)
+//! append an event here (an instant local write) instead of POSTing
+//! synchronously. The spool is drained to the server at **session boundaries**:
+//! a cleanup pass at `session-start`, detached background flushes at
+//! cancellation-prone boundaries (`stop`, `pre-compact`, `session-end`), and a
+//! small threshold-triggered catch-up on busy `post-tool-use` streams. A few
+//! seconds of latency is acceptable at boundaries, unlike the per-tool-call hot
+//! path, which must never block the agent.
//!
//! This makes capture reliable against a remote/slow server (no event is lost:
//! a file persists until the server answers 2xx) without ever blocking a tool
diff --git a/docs/install.md b/docs/install.md
index 1f41f034..d1ed9a80 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -369,18 +369,23 @@ the agent can execute files owned by your user. Re-run `install-hooks --apply`
after package upgrades to refresh those staged copies.
Native `ai-memory hook --event ...` commands spool events locally. Session start
-does a short bounded cleanup drain before fetching a handoff; session end starts
-a detached `hook-drain` helper so agent quit paths are not blocked by a large
-backlog. The built-in timings stay short on agent-facing paths, but high-latency
-or large-backlog instances can raise them with whole-minute runtime env vars in
-the agent's environment; no `install-hooks` rerun is needed:
+does a short bounded cleanup drain before fetching a handoff; cancellation-prone
+boundary events (`stop`, `pre-compact`, and `session-end`) start a detached
+`hook-drain` helper so delivery does not depend on one shutdown hook surviving.
+On Unix, the helper uses a trusted `setsid` launcher when available and falls
+back to a separate process group otherwise; Windows uses detached/breakaway
+process flags. The spool is capped, so a permanently undrained backlog is
+eventually pruned rather than unbounded, but old undelivered events can be lost.
+The built-in timings stay short on agent-facing paths, but high-latency or
+large-backlog instances can raise them with whole-minute runtime env vars in the
+agent's environment; no `install-hooks` rerun is needed:
| Env var | Built-in default | Max override | What it caps |
|---|---:|---:|---|
| `AI_MEMORY_HOOK_DRAIN_TIMEOUT_MINUTES` | 3 seconds | 60 minutes | each event POST during a drain |
| `AI_MEMORY_HOOK_HANDOFF_TIMEOUT_MINUTES` | 3 seconds | 60 minutes | the synchronous `session-start` handoff GET |
| `AI_MEMORY_HOOK_START_BUDGET_MINUTES` | 3 seconds | 60 minutes | total time `session-start` may spend waiting for the drain lock and cleanup draining |
-| `AI_MEMORY_HOOK_BACKGROUND_DRAIN_BUDGET_MINUTES` | 5 minutes | 60 minutes | total time the detached `hook-drain` helper may spend after `session-end` |
+| `AI_MEMORY_HOOK_BACKGROUND_DRAIN_BUDGET_MINUTES` | 5 minutes | 60 minutes | total time the detached `hook-drain` helper may spend after a background-drain boundary |
| `AI_MEMORY_HOOK_INCREMENTAL_THRESHOLD` | 32 events | positive integer | spool backlog size that triggers a 250 ms `post-tool-use` catch-up drain |
Timing values must be positive whole minutes. Missing, empty, non-numeric, or