Skip to content

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

Rust

fix(hooks): report what a hook-drain pass did instead of exiting silently (#495)

Samir Hanna Verzafa435f9e55a8
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 869a3b04..a6ceab33 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Fixed
+- Made `hook-drain` say what a pass actually did. The drain already returned
+ `sent`/`remaining`/`dropped` counts and `run_drain` discarded all three, so
+ three passes that mean opposite things — everything delivered, every queued
+ event discarded undelivered at the retry cap or the spool TTL, and nothing
+ attempted at all because another drainer held the lock — were byte-identical
+ on both streams and in the exit code. A drain that silently loses capture was
+ therefore indistinguishable in the field from one that works, which is how
+ #493 was reported: exit 0, no output, an empty `hook-drain.log`, and no way
+ to tell which of the three had happened. A pass that leaves nothing behind
+ stays silent, so `hook-drain.log` keeps receiving only warnings and a healthy
+ instance never grows it; a pass that leaves events queued or drops them, and
+ a pass that found the lock held, now each emit one stderr line. stderr, not
+ stdout: the drainer's stdout is contractually empty and the detached helper
+ already redirects stderr into the log. This changes no delivery behaviour —
+ it only stops the existing behaviour being unfalsifiable. (#493)
- Stopped the scaffolding filter discarding terse prompts. The identifier
branch added in #484 fired on any single token carrying a digit and a
hyphen, underscore or bracket, which is the shape of a bare model id and
diff --git a/crates/ai-memory-cli/src/commands/hook.rs b/crates/ai-memory-cli/src/commands/hook.rs
index cc5e0b95..0e61e7ff 100644
--- a/crates/ai-memory-cli/src/commands/hook.rs
+++ b/crates/ai-memory-cli/src/commands/hook.rs
@@ -317,13 +317,59 @@ pub async fn run_drain(data_dir: Option<PathBuf>) -> anyhow::Result<()> {
)
.await
{
- Ok(hook_spool::LockedDrainResult::Drained(_))
- | Ok(hook_spool::LockedDrainResult::LockBusy) => {}
+ Ok(outcome) => {
+ let _ = write_drain_report(&mut std::io::stderr(), &outcome);
+ }
Err(err) => eprintln!("ai-memory hook-drain warning: failed to acquire drain lock: {err}"),
}
Ok(())
}
+/// Report a drain pass on stderr when it ended with events undelivered.
+///
+/// Silent on a clean pass (nothing queued, or everything delivered) so
+/// `hook-drain.log` stays warning-only, matching the rotation budget in
+/// [`hook_drain_process`]. stderr, never stdout: the drainer's stdout is
+/// contractually empty and the detached helper redirects stderr into the log.
+///
+/// Without this the drain discarded its own [`hook_spool::DrainResult`], so a
+/// pass that dropped every queued event without sending it was byte-identical,
+/// on both streams and in the exit code, to one that delivered them all — and
+/// so was a pass that did nothing because another drainer held the lock (#493).
+fn write_drain_report<W: std::io::Write>(
+ w: &mut W,
+ outcome: &hook_spool::LockedDrainResult,
+) -> std::io::Result<()> {
+ match outcome {
+ // Says what this pass did, not what the spool holds: `LockBusy` is
+ // returned before `drain_until_quiescent` lists anything, so the count
+ // of queued events is unknown here. Asserting one would repeat, inside
+ // the fix, the confusion the fix is for.
+ hook_spool::LockedDrainResult::LockBusy => writeln!(
+ w,
+ "ai-memory hook-drain warning: another drainer holds the spool lock; \
+ this pass attempted no delivery and left the spool untouched"
+ ),
+ hook_spool::LockedDrainResult::Drained(result) => {
+ if result.remaining == 0 && result.dropped == 0 {
+ return Ok(());
+ }
+ // "acknowledged", not "delivered": `sent` counts what the server
+ // ACKed, and an ack also covers an item the server accepted and then
+ // dropped by capture policy (`accepted_indices` includes protocol
+ // drops). Reporting those as delivered would assert storage the
+ // drain cannot observe — the precise confusion #493 was written in.
+ writeln!(
+ w,
+ "ai-memory hook-drain warning: {} event(s) acknowledged by the server, \
+ {} still queued, {} DROPPED undelivered (past the retry cap or \
+ older than the spool TTL)",
+ result.sent, result.remaining, result.dropped
+ )
+ }
+ }
+}
+
fn env_lookup(name: &str) -> Option<String> {
std::env::var(name).ok()
}
@@ -1022,6 +1068,88 @@ mod tests {
}
}
+ fn drain_report(outcome: &hook_spool::LockedDrainResult) -> String {
+ let mut out = Vec::new();
+ write_drain_report(&mut out, outcome).unwrap();
+ String::from_utf8(out).unwrap()
+ }
+
+ /// A pass with nothing left behind says nothing, so `hook-drain.log` keeps
+ /// receiving only warnings and a healthy instance never grows it.
+ #[test]
+ fn drain_report_is_silent_on_a_clean_pass() {
+ for result in [
+ hook_spool::DrainResult::default(),
+ hook_spool::DrainResult {
+ sent: 12,
+ remaining: 0,
+ dropped: 0,
+ },
+ ] {
+ let report = drain_report(&hook_spool::LockedDrainResult::Drained(result));
+ assert!(report.is_empty(), "clean pass emitted: {report}");
+ }
+ }
+
+ /// The regression #493 exists for. Three passes that mean opposite things —
+ /// everything delivered, everything discarded undelivered, and nothing even
+ /// attempted because another drainer held the lock — used to produce the
+ /// same empty output and the same exit 0, which is what left the reporter
+ /// unable to tell a working drain from a silently lossy one. Pin that each
+ /// one is now distinguishable from the other two.
+ #[test]
+ fn drain_report_separates_loss_and_contention_from_a_clean_pass() {
+ let clean = drain_report(&hook_spool::LockedDrainResult::Drained(
+ hook_spool::DrainResult {
+ sent: 5,
+ remaining: 0,
+ dropped: 0,
+ },
+ ));
+ let lossy = drain_report(&hook_spool::LockedDrainResult::Drained(
+ hook_spool::DrainResult {
+ sent: 0,
+ remaining: 0,
+ dropped: 7,
+ },
+ ));
+ let busy = drain_report(&hook_spool::LockedDrainResult::LockBusy);
+
+ assert!(clean.is_empty());
+ assert!(
+ lossy.contains("DROPPED") && lossy.contains('7'),
+ "a pass that discarded 7 undelivered events must name the loss: {lossy}"
+ );
+ assert!(
+ !busy.contains("queued"),
+ "LockBusy is returned before the spool is listed, so the report must \
+ not claim anything about queued events: {busy}"
+ );
+ assert!(
+ busy.contains("lock"),
+ "a contended pass must say it delivered nothing: {busy}"
+ );
+ assert_ne!(lossy, busy);
+ assert_ne!(lossy, clean);
+ assert_ne!(busy, clean);
+ }
+
+ /// Events merely still queued (server down, or the budget ran out) are a
+ /// warning too — they are the state that precedes the drop — but they must
+ /// not be reported as lost.
+ #[test]
+ fn drain_report_distinguishes_still_queued_from_dropped() {
+ let report = drain_report(&hook_spool::LockedDrainResult::Drained(
+ hook_spool::DrainResult {
+ sent: 1,
+ remaining: 4,
+ dropped: 0,
+ },
+ ));
+ assert!(report.contains("4 still queued"), "{report}");
+ assert!(report.contains("0 DROPPED"), "{report}");
+ }
+
#[test]
fn kiro_v3_live_lifecycle_fixtures_share_native_context() {
let fixture: serde_json::Value = serde_json::from_str(include_str!(