Skip to content

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

Rust

docs(wrapper): name what actually ends a managed run

Avelinoed02eccec818
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 203ac3e8..f58956f9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -36,13 +36,15 @@ version in [`docs/changelog/`](docs/changelog/):
start. These paths now embed each written page the same way
`memory_write_page` does. (#1258)
- Fixed `ai-memory run` reporting `server unavailable` for a heartbeat the
- server answered and rejected. A managed run lease lapses while the host
- sleeps, and the first heartbeat after wake is answered with `409 managed run
- lease is not active` in about a millisecond, but the launcher printed the
- outage notice for every failed heartbeat and sent the real reason to a
- `debug` line nobody sees at the default level. The notice now carries the
- server's own reason for a rejection, and keeps the outage wording only for a
- server the launcher could not reach. (#1277)
+ server answered and rejected. A heartbeat is rejected once its managed run
+ stops being active, which on a workstation usually means a later `run`
+ prepared a workstream and expired every active run whose lease had already
+ passed. The launcher printed the outage notice for a failure of any kind and
+ sent the real reason to a `debug` line nobody sees at the default level, so a
+ server that answered `409 managed run lease is not active` in about a
+ millisecond read as an outage. The notice now carries the server's own reason
+ for a rejection, and keeps the outage wording only for a server the launcher
+ could not reach. (#1277)
## [3.0.0] - 2026-10-13
diff --git a/crates/ai-memory-cli/src/commands/run.rs b/crates/ai-memory-cli/src/commands/run.rs
index 9fa132f1..c213c245 100644
--- a/crates/ai-memory-cli/src/commands/run.rs
+++ b/crates/ai-memory-cli/src/commands/run.rs
@@ -2033,10 +2033,10 @@ async fn capture_interrupts(interrupted: CancellationToken) {
/// The operator-facing line for one failed heartbeat.
///
/// Only a heartbeat that never reached the server may claim the server is
-/// unavailable. A rejection the server answered — the 90s lease a sleeping
-/// machine outlived, a run already finished — is actionable and names its
-/// own reason, instead of being reported as an outage the operator would
-/// go looking for in the server.
+/// unavailable. A rejection the server answered names its own reason instead.
+/// That reason is actionable: the run stopped being active, because it was
+/// finished, cancelled, or expired by a later prepare. Reporting it as an
+/// outage sends the operator looking for a server that never went away.
fn heartbeat_failure_notice(error: &anyhow::Error) -> String {
if error
.chain()
diff --git a/docs/managed-workstreams.md b/docs/managed-workstreams.md
index 9f5a7b5e..d90f9efd 100644
--- a/docs/managed-workstreams.md
+++ b/docs/managed-workstreams.md
@@ -1106,11 +1106,16 @@ cancel, finish, or destructive operation remains terminal for the old run.
The outage wording is reserved for a server the launcher could not reach. When
the server answers a heartbeat and rejects it, the notice carries the server's
-own reason instead. The common case is a lease the machine slept through: the
-launcher stops probing while the host is suspended, the 90-second lease lapses,
-and the first heartbeat after wake is answered with `managed run lease is not
-active` rather than being lost in transit. Reporting that as an outage would
-send the operator looking for a server that never went away.
+own reason instead. A lapsed timestamp alone is not that case: `heartbeat`
+renews any run whose state is still `active`, so the original launcher recovers
+its own lease after an outage or a host suspend. The rejection arrives once the
+run stops being active, because it was finished, cancelled, or expired by a
+later prepare. That last one is the common path on a workstation, since the
+first statement of every prepare expires each active run whose lease has
+already passed. A launcher that was suspended past its lease keeps renewing
+until any other `run` prepares a workstream, and then reads `managed run lease
+is not active` from a server that is reachable and idle. Reporting that as an
+outage would send the operator looking for a server that never went away.
If the client is terminated without cleanup, such as with `kill -9`, its lease
expires within 90 seconds. A later managed run starts from the last committed