Skip to content

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

Rust

docs(run): qualify Claude attach lifecycle evidence

Éverton Toffanetto0e85f85e5f48
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bfeeb1e4..ece38311 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,6 +18,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
flag. The launcher now confirms the session is live in this checkout with
`claude agents --json` (only for a transcript recorded in the background) and
opens it with `claude attach <id>`; any failure keeps the native resume.
+ Documented the observed attach-hook behavior, early-exit import boundary and
+ fallback validation limits.
(#1052)
- Fixed watcher reindexing racing with writes and batches to the same page by
sharing their per-page mutex from disk read through SQLite upsert. Both
diff --git a/crates/ai-memory-cli/src/commands/run.rs b/crates/ai-memory-cli/src/commands/run.rs
index 423e1de5..2ce1574b 100644
--- a/crates/ai-memory-cli/src/commands/run.rs
+++ b/crates/ai-memory-cli/src/commands/run.rs
@@ -550,9 +550,9 @@ pub(super) async fn run_from_with_wiring(
remember_session_store(config, &endpoint, harness, native_session_id, &linked_store);
}
// Claude refuses `--resume` on a background session that is still running
- // and points at `claude attach`, so open it that way instead. An attached
- // terminal starts no native session of its own: SessionStart never fires
- // in it, and native flags have nothing to apply to.
+ // and points at `claude attach`, so open it that way instead. The 2.1.288
+ // lifecycle check observed no new SessionStart from the attach client;
+ // native flags are omitted because it connects to the existing session.
let attached_background = if harness == ManagedHarness::Claude
&& plan.mode == LaunchMode::Session
&& resumes_linked_session
diff --git a/docs/managed-workstreams.md b/docs/managed-workstreams.md
index fb6bab98..1f91230d 100644
--- a/docs/managed-workstreams.md
+++ b/docs/managed-workstreams.md
@@ -427,14 +427,35 @@ attaches) and points at `claude attach <id>`. Only when the
transcript shows the session ran in the background (`sessionKind: "bg"`)
does ai-memory ask `claude agents --json --cwd <checkout>`. When that lists the
session as a live background one in this checkout, it launches
-`claude attach <id>` with the listing's short id instead. An attached terminal
-starts no native session of its own: native arguments are not passed, and the
-workstream context packet is not delivered (SessionStart does not fire). A
-failed or unexpected listing keeps the native resume. (#1052)
-
-Claude Code background sessions run inside the Claude Code daemon, not in the
-process `ai-memory run` spawned, so their hooks never carry the run's id. When a
-managed Claude session attaches to one (`/resume` on a session shown as
+`claude attach <id>` with the listing's short id instead. Native arguments are
+not passed to the attach client. In the Claude Code 2.1.288 lifecycle validation,
+no new `SessionStart` was observed from the attach client; the background
+worker's hooks carried the background session id. Delivery of a pending
+workstream context packet through attach remains unverified: that validation
+did not exercise a pending packet. The launcher reports this limitation and
+suppresses the missing-acknowledgement warning for attach. (#1052)
+
+When the attach client detaches or exits early, the managed run finishes with
+the client's exit status and imports the linked transcript available at finish.
+It neither stops the daemon nor waits for the background turn to complete;
+events written after that import remain outside it. In the same validation,
+Ctrl-Z detached with exit 0, and terminating only the attach client produced
+exit 1 while the daemon continued and emitted `Stop` after the run finished.
+
+A failed, unavailable or unexpected `claude agents` listing keeps the native
+resume and its original flags. That fallback can still encounter Claude's
+refusal to resume a live background session with flags. The lifecycle test
+injected an exit-127 listing and an incompatible JSON object, then exercised
+the real resume and backend; an older Claude binary without `agents` was not
+tested. These observations are recorded in the
+[PR #1067 lifecycle validation](https://github.com/akitaonrails/ai-memory/pull/1067#issuecomment-5962340148).
+
+Claude Code background sessions run inside the Claude Code daemon, separately
+from the attach client. Their hooks use the daemon worker's inherited
+environment: the 2.1.288 validation observed an `AI_MEMORY_RUN_ID` from an
+earlier launch, different from the current attach runs. A daemon hook therefore
+does not by itself identify the current attaching run. When a managed Claude
+session attaches to one (`/resume` on a session shown as
"running in the background"), the conversation goes on in the background
session's transcript. At the end of the run, ai-memory looks for a transcript
written during the run whose `sessionKind: "bg"` records name the run's own