Skip to content

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

Rust

fix(run): keep sessions linked under a custom native store reachable

Éverton Toffanettod662c53d91b6
diff --git a/CHANGELOG.md b/CHANGELOG.md
index c0229db6..aa5b4d9c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
provider. (#1026)
### Fixed
+- Fixed `continue`, `resume` and bare `ai-memory run` losing sessions launched
+ under a custom native store, such as a second Claude Code config home set
+ with `CLAUDE_CONFIG_DIR`. Automatic harness selection now scans the store the
+ launch resolves (`--env`, then the process environment) instead of always the
+ default one. The client records the store of every session it links, at
+ launch or when the run finishes, in `client-projects.json`. A later launch
+ that cannot find that session and resolves a different store now stops with
+ an error naming both stores and keeps the workstream link, where it used to
+ start fresh and repoint the workstream. `--fresh` still starts a new session.
+ (#1047)
- Fixed interrupted launchers blocking an immediate managed-workstream restart
by adding explicit `ai-memory run --force-unlock` recovery. The server
atomically expires and replaces only a lease attributed to the same
diff --git a/crates/ai-memory-cli/src/commands/project_registry.rs b/crates/ai-memory-cli/src/commands/project_registry.rs
index 084c10fe..bb386462 100644
--- a/crates/ai-memory-cli/src/commands/project_registry.rs
+++ b/crates/ai-memory-cli/src/commands/project_registry.rs
@@ -20,6 +20,9 @@ use crate::http_client::ServerEndpoint;
const REGISTRY_VERSION: u32 = 1;
const MAX_REGISTRY_BYTES: u64 = 4 * 1024 * 1024;
const MAX_LINKS: usize = 10_000;
+/// Oldest records are evicted first; an evicted session only loses the
+/// mismatch check and falls back to the pre-record behavior.
+const MAX_SESSION_STORES: usize = 1_000;
const REGISTRY_FILE: &str = "client-projects.json";
const REGISTRY_LOCK_FILE: &str = "client-projects.lock";
@@ -38,10 +41,30 @@ pub(super) struct ProjectLink {
pub(super) linked_at: String,
}
+/// The native store this client launched one linked session under.
+///
+/// The server only learns the native session id, so without this record a
+/// later launch cannot tell a deleted session from one that lives under a
+/// different store override (a second `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, ...).
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+struct SessionStore {
+ server: String,
+ harness: String,
+ native_session_id: String,
+ /// Absolute, normalized store root, so the default store and an override
+ /// spelling the same directory compare equal.
+ store: PathBuf,
+ recorded_at: String,
+}
+
#[derive(Debug, Serialize, Deserialize)]
struct ProjectRegistry {
version: u32,
links: Vec<ProjectLink>,
+ // Optional so registries written before this field still load; older
+ // binaries ignore it and simply drop it on their next write.
+ #[serde(default, skip_serializing_if = "Vec::is_empty")]
+ session_stores: Vec<SessionStore>,
}
impl Default for ProjectRegistry {
@@ -49,6 +72,7 @@ impl Default for ProjectRegistry {
Self {
version: REGISTRY_VERSION,
links: Vec::new(),
+ session_stores: Vec::new(),
}
}
}
@@ -135,6 +159,57 @@ pub(super) fn rekey_scope(
})
}
+/// Remember the store a session was linked under, after the server accepted
+/// the link (at launch, or at finish for an id discovered after the run).
+pub(super) fn record_session_store(
+ config: &Config,
+ endpoint: &ServerEndpoint,
+ harness: &str,
+ native_session_id: &str,
+ store: &Path,
+) -> Result<()> {
+ let server = endpoint.identity();
+ update_registry(config, |registry| {
+ registry.session_stores.retain(|record| {
+ !(record.server == server
+ && record.harness == harness
+ && record.native_session_id == native_session_id)
+ });
+ registry.session_stores.push(SessionStore {
+ server,
+ harness: harness.to_owned(),
+ native_session_id: native_session_id.to_owned(),
+ store: store.to_path_buf(),
+ recorded_at: jiff::Timestamp::now().to_string(),
+ });
+ let excess = registry
+ .session_stores
+ .len()
+ .saturating_sub(MAX_SESSION_STORES);
+ registry.session_stores.drain(..excess);
+ Ok(true)
+ })
+}
+
+/// The store a session was linked under, if this client recorded one.
+pub(super) fn recorded_session_store(
+ config: &Config,
+ endpoint: &ServerEndpoint,
+ harness: &str,
+ native_session_id: &str,
+) -> Result<Option<PathBuf>> {
+ let server = endpoint.identity();
+ Ok(load_registry(&registry_path(config))?
+ .session_stores
+ .into_iter()
+ .find(|record| {
+ record.server == server
+ && record.harness == harness
+ && record.native_session_id == native_session_id
+ })
+ .map(|record| record.store))
+}
+
fn registry_path(config: &Config) -> PathBuf {
config.data_dir.join(REGISTRY_FILE)
}
@@ -418,4 +493,107 @@ mod tests {
assert_eq!(links[0].project, "renamed");
assert_eq!(links[0].linked_at, original_linked_at);
}
+
+ #[test]
+ fn session_stores_are_keyed_by_server_harness_and_session() {
+ let tmp = tempfile::TempDir::new().unwrap();
+ let config = config_at(&tmp.path().join("data"));
+ let first = endpoint("http://memory-one:49374");
+ let second = endpoint("http://memory-two:49374");
+ let custom = tmp.path().join("claude-glm").join("projects");
+ let default = tmp.path().join("home").join(".claude").join("projects");
+
+ record_session_store(&config, &first, "claude", "abc", &custom).unwrap();
+ record_session_store(&config, &first, "codex", "def", &default).unwrap();
+
+ assert_eq!(
+ recorded_session_store(&config, &first, "claude", "abc").unwrap(),
+ Some(custom.clone())
+ );
+ assert_eq!(
+ recorded_session_store(&config, &first, "codex", "def").unwrap(),
+ Some(default.clone())
+ );
+ assert_eq!(
+ recorded_session_store(&config, &first, "codex", "abc").unwrap(),
+ None
+ );
+ assert_eq!(
+ recorded_session_store(&config, &second, "claude", "abc").unwrap(),
+ None
+ );
+
+ record_session_store(&config, &first, "claude", "abc", &default).unwrap();
+ assert_eq!(
+ recorded_session_store(&config, &first, "claude", "abc").unwrap(),
+ Some(default)
+ );
+ }
+
+ /// Registries written before session stores existed keep loading, and
+ /// recording one keeps their links.
+ #[test]
+ fn registries_without_session_stores_still_load() {
+ let tmp = tempfile::TempDir::new().unwrap();
+ let data = tmp.path().join("data");
+ let checkout = tmp.path().join("checkout");
+ fs::create_dir_all(&data).unwrap();
+ fs::create_dir(&checkout).unwrap();
+ let config = config_at(&data);
+ let endpoint = endpoint("http://memory:49374");
+ let store = tmp.path().join("store");
+ record_prepared_checkout(&config, &endpoint, "default", "app", &checkout).unwrap();
+ let legacy = fs::read_to_string(data.join(REGISTRY_FILE)).unwrap();
+ assert!(!legacy.contains("session_stores"), "{legacy}");
+
+ assert_eq!(
+ recorded_session_store(&config, &endpoint, "claude", "abc").unwrap(),
+ None
+ );
+ record_session_store(&config, &endpoint, "claude", "abc", &store).unwrap();
+
+ assert_eq!(links_for_server(&config, &endpoint).unwrap().len(), 1);
+ assert_eq!(
+ recorded_session_store(&config, &endpoint, "claude", "abc").unwrap(),
+ Some(store)
+ );
+ }
+
+ #[test]
+ fn session_store_records_evict_the_oldest_first() {
+ let tmp = tempfile::TempDir::new().unwrap();
+ let config = config_at(&tmp.path().join("data"));
+ let endpoint = endpoint("http://memory:49374");
+ let server = endpoint.identity();
+ let store = tmp.path().join("store");
+ update_registry(&config, |registry| {
+ registry.session_stores = (0..MAX_SESSION_STORES)
+ .map(|index| SessionStore {
+ server: server.clone(),
+ harness: "claude".to_owned(),
+ native_session_id: format!("session-{index}"),
+ store: store.clone(),
+ recorded_at: "2026-01-01T00:00:00Z".to_owned(),
+ })
+ .collect();
+ Ok(true)
+ })
+ .unwrap();
+
+ record_session_store(&config, &endpoint, "claude", "newest", &store).unwrap();
+
+ let path = registry_path(&config);
+ assert_eq!(
+ load_registry(&path).unwrap().session_stores.len(),
+ MAX_SESSION_STORES
+ );
+ assert_eq!(
+ recorded_session_store(&config, &endpoint, "claude", "session-0").unwrap(),
+ None
+ );
+ assert_eq!(
+ recorded_session_store(&config, &endpoint, "claude", "newest").unwrap(),
+ Some(store)
+ );
+ }
}
diff --git a/crates/ai-memory-cli/src/commands/run.rs b/crates/ai-memory-cli/src/commands/run.rs
index 80be0fda..565f321b 100644
--- a/crates/ai-memory-cli/src/commands/run.rs
+++ b/crates/ai-memory-cli/src/commands/run.rs
@@ -16,14 +16,14 @@ use ai_memory_workstream::{
JailHostFacts, JailSupport, JailToggleChoice, JailToggleKind, LaunchMode, LaunchPlan,
LaunchRoots, ManagedHarness, NativeSessionCandidate, ai_jail_support,
allows_native_session_adoption, apply_claude_true_yolo, apply_yolo, build_ai_jail_invocation,
- build_launch_plan, build_launch_plan_with_env, crush_global_config_path,
+ build_launch_plan, build_launch_plan_with_env, clean_path, crush_global_config_path,
discover_native_session, export_transcript, has_native_session_selector, inside_ai_jail_here,
inspect_repository, jail_checklist, jail_toggle, kiro_explicit_session_id,
kiro_harness_from_source_cursor, kiro_selects_non_default_engine, kiro_selects_v2_engine,
kiro_selects_v3_engine, kiro_v3_resume_uses_default_store, list_native_sessions,
- marked_choices, native_session_exists, native_session_in_checkout, omp_profile_flag,
- omp_profile_flag_env, parse_jail_toggles, store_override_vars, usable_ai_jail_here,
- wait_for_transcript_flush,
+ marked_choices, native_session_exists, native_session_in_checkout, native_store_root,
+ omp_profile_flag, omp_profile_flag_env, parse_jail_toggles, store_override_vars,
+ usable_ai_jail_here, wait_for_transcript_flush,
};
use anyhow::{Context as _, Result, anyhow};
use tokio::process::Command;
@@ -153,7 +153,7 @@ pub(super) async fn run_from_with_wiring(
}
let auto_candidates = if automatic_harness {
filter_usable_auto_sessions(
- list_auto_sessions(&home, &repository.cwd).await?,
+ list_auto_sessions(&home, &repository.cwd, &run_env).await?,
|harness| executable_available(OsStr::new(harness.executable())),
)?
} else {
@@ -334,6 +334,22 @@ pub(super) async fn run_from_with_wiring(
&run_env,
));
if let Some(orphaned_session) = orphaned_session {
+ let recorded = super::project_registry::recorded_session_store(
+ config,
+ &endpoint,
+ harness.as_str(),
+ &orphaned_session,
+ )
+ .unwrap_or_else(|error| {
+ eprintln!(
+ "ai-memory: could not read the client-local session store record ({error:#}); treating the linked session as deleted"
+ );
+ None
+ });
+ let current = effective_store(harness, &home, &repository.cwd, plan.session_dir.as_deref());
+ if let Some(error) = store_mismatch_error(harness, &orphaned_session, recorded, &current) {
+ acquired_try!(Err(error));
+ }
eprintln!(
"ai-memory: linked {} session {} is missing from its native store; starting fresh and repointing workstream '{}' after the new session is established",
harness.as_str(),
@@ -498,6 +514,17 @@ pub(super) async fn run_from_with_wiring(
}
super::run_autowire::ensure_wired_with(config, harness, wire_overrides, &wire_env);
}
+ // A Kiro v3 resume that dropped `KIRO_HOME` runs against the default store.
+ let linked_store = effective_store(
+ harness,
+ &home,
+ &repository.cwd,
+ if remove_kiro_home {
+ None
+ } else {
+ plan.session_dir.as_deref()
+ },
+ );
if plan.mode == LaunchMode::Session
&& let Some(native_session_id) = &plan.expected_session_id
{
@@ -512,6 +539,7 @@ pub(super) async fn run_from_with_wiring(
.await
.context("linking the managed native session; the agent was not started")
);
+ remember_session_store(config, &endpoint, harness, native_session_id, &linked_store);
}
let crush_context = if harness == ManagedHarness::Crush && plan.mode == LaunchMode::Session {
@@ -722,6 +750,14 @@ pub(super) async fn run_from_with_wiring(
.await
);
+ // Sessions whose id was unknown at launch (a fresh Codex session, say) are
+ // linked by the finish request above, so record their store here.
+ if plan.mode == LaunchMode::Session
+ && let Some(native_session_id) = native_session_id.as_deref()
+ && plan.expected_session_id.as_deref() != Some(native_session_id)
+ {
+ remember_session_store(config, &endpoint, harness, native_session_id, &linked_store);
+ }
if plan.mode == LaunchMode::Session
&& prepared.sync_through > prepared.sync_after
&& !server_status.is_some_and(|status| status.context_delivered)
@@ -1434,11 +1470,26 @@ async fn resolve_native_session_after_run(
}))
}
-async fn list_auto_sessions(home: &Path, cwd: &Path) -> Result<Vec<AutoSessionCandidate>> {
+async fn list_auto_sessions(
+ home: &Path,
+ cwd: &Path,
+ env_overrides: &[(String, String)],
+) -> Result<Vec<AutoSessionCandidate>> {
let mut found = Vec::new();
let mut failures = Vec::new();
for harness in AUTO_HARNESSES {
- match list_native_sessions(harness, home, cwd, None, 1).await {
+ // Scan the store the launch would resume from. With a custom
+ // `CLAUDE_CONFIG_DIR` (or another store override) the default store
+ // holds none of this checkout's sessions, so scanning it either finds
+ // nothing or picks a session the launched harness cannot see.
+ let session_dir = match auto_session_dir(harness, home, cwd, env_overrides) {
+ Ok(session_dir) => session_dir,
+ Err(error) => {
+ failures.push(format!("{}: {error}", harness.as_str()));
+ continue;
+ }
+ };
+ match list_native_sessions(harness, home, cwd, session_dir.as_deref(), 1).await {
Ok(candidates) => found.extend(
candidates
.into_iter()
@@ -1466,6 +1517,25 @@ async fn list_auto_sessions(home: &Path, cwd: &Path) -> Result<Vec<AutoSessionCa
Ok(found)
}
+/// The native store a bare launch of `harness` resolves, the same way the
+/// launch plan does: `--env`/`--env-file` first, then the process environment.
+fn auto_session_dir(
+ harness: ManagedHarness,
+ home: &Path,
+ cwd: &Path,
+ env_overrides: &[(String, String)],
+) -> Result<Option<PathBuf>> {
+ Ok(build_launch_plan_with_env(
+ harness,
+ None,
+ Vec::new(),
+ None,
+ env_overrides,
+ Some(LaunchRoots { home, cwd }),
+ )?
+ .session_dir)
+}
+
fn unique_auto_agents(candidates: &[AutoSessionCandidate]) -> Vec<AgentKind> {
let mut agents = Vec::new();
for candidate in candidates {
@@ -1784,6 +1854,103 @@ fn build_preflighted_launch_plan(
}
}
+/// The store a launch reads, absolute and normalized so the default store and
+/// an override spelling the same directory (relative, trailing slash,
+/// symlinked) compare equal. A relative override resolves against the checkout,
+/// where the harness runs.
+fn effective_store(
+ harness: ManagedHarness,
+ home: &Path,
+ cwd: &Path,
+ session_dir: Option<&Path>,
+) -> PathBuf {
+ let root = native_store_root(harness, home, session_dir);
+ let absolute = if root.is_absolute() {
+ root
+ } else {
+ cwd.join(root)
+ };
+ std::fs::canonicalize(&absolute).unwrap_or_else(|_| canonical_prefix(&clean_path(&absolute)))
+}
+
+/// Canonicalize the deepest existing ancestor and keep the missing tail, so a
+/// store that does not exist yet still compares equal to the same directory
+/// once it does (on macOS, `/var` vs `/private/var`).
+fn canonical_prefix(path: &Path) -> PathBuf {
+ let mut tail = Vec::new();
+ let mut existing = path;
+ loop {
+ if let Ok(real) = std::fs::canonicalize(existing) {
+ return tail.iter().rev().fold(real, |acc, part| acc.join(part));
+ }
+ match (existing.parent(), existing.file_name()) {
+ (Some(parent), Some(name)) => {
+ tail.push(name.to_os_string());
+ existing = parent;
+ }
+ _ => return path.to_path_buf(),
+ }
+ }
+}
+
+fn remember_session_store(
+ config: &Config,
+ endpoint: &ServerEndpoint,
+ harness: ManagedHarness,
+ native_session_id: &str,
+ store: &Path,
+) {
+ if let Err(error) = super::project_registry::record_session_store(
+ config,
+ endpoint,
+ harness.as_str(),
+ native_session_id,
+ store,
+ ) {
+ eprintln!(
+ "ai-memory: could not record the client-local session store ({error:#}); continuing the managed run"
+ );
+ }
+}
+
+/// Refuse to replace a linked session that was launched under a different
+/// native store than this launch resolves.
+///
+/// Such a session most likely still exists in its own store; starting fresh
+/// would repoint the workstream and orphan it. With no record (or the same
+/// store) the session really is gone and replacing it stays the right call.
+fn store_mismatch_error(
+ harness: ManagedHarness,
+ native_session_id: &str,
+ recorded: Option<PathBuf>,
+ current: &Path,
+) -> Option<anyhow::Error> {
+ let recorded = recorded?;
+ if recorded == current {
+ return None;
+ }
+ // Native flags and profiles move some stores too, not only the variables.
+ let flags: &[&str] = match harness {
+ ManagedHarness::Pi => &["--session-dir"],
+ ManagedHarness::Omp => &["--session-dir", "--profile", "OMP_PROFILE"],
+ ManagedHarness::Crush => &["--data-dir"],
+ _ => &[],
+ };
+ let selectors = [store_override_vars(harness), flags].concat().join("/");
+ let hint = if selectors.is_empty() {
+ " from the original environment".to_owned()
+ } else {
+ format!(" with the same {selectors}")
+ };
+ Some(anyhow!(
+ "linked {} session {} was launched under {} but this launch resolves {}; relaunch{hint} to resume it, or pass --fresh to start a new session",
+ harness.as_str(),
+ display_session_id(native_session_id),
+ super::show::terminal_text(&recorded.to_string_lossy()),
+ super::show::terminal_text(&current.to_string_lossy()),
+ ))
+}
+
fn ensure_executable_available(harness: ManagedHarness, executable: Option<&OsStr>) -> Result<()> {
let program = executable.unwrap_or_else(|| OsStr::new(harness.executable()));
if executable_available(program) {
@@ -4221,6 +4388,131 @@ mod tests {
server.abort();
}
+ /// A store mismatch must stop before `/link` and before the harness
+ /// spawns, release the prepared run, and leave the workstream link alone.
+ #[cfg(unix)]
+ #[tokio::test]
+ async fn a_store_mismatch_stops_before_linking_or_spawning_and_releases_the_run() {
+ use std::os::unix::fs::PermissionsExt as _;
+
+ use crate::commands::run_autowire::WireOverrides;
+ use crate::config::Config;
+
+ const LINKED: &str = "33333333-3333-4333-8333-333333333333";
+ let cancels = Arc::new(AtomicUsize::new(0));
+ let links = Arc::new(AtomicUsize::new(0));
+ let cancel_hits = Arc::clone(&cancels);
+ let link_hits = Arc::clone(&links);
+ let app = Router::new()
+ .route(
+ "/workstream/runs",
+ post(|| async {
+ axum::Json(PrepareManagedRunResponse {
+ workstream_id: WorkstreamId::new(),
+ workstream_name: "default".into(),
+ run_id: ManagedRunId::new(),
+ resolved_agent: None,
+ native_session_id: Some(LINKED.into()),
+ source_cursor: None,
+ sync_after: 0,
+ sync_through: 0,
+ may_adopt_existing_session: false,
+ })
+ }),
+ )
+ .route(
+ "/workstream/runs/{run_id}/cancel",
+ post(move || {
+ cancel_hits.fetch_add(1, Ordering::SeqCst);
+ async { StatusCode::NO_CONTENT }
+ }),
+ )
+ .route(
+ "/workstream/runs/{run_id}/link",
+ post(move || {
+ link_hits.fetch_add(1, Ordering::SeqCst);
+ async { StatusCode::NO_CONTENT }
+ }),
+ );
+ let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+ let address = listener.local_addr().unwrap();
+ let server = tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
+
+ let home = tempfile::tempdir().unwrap();
+ let data = tempfile::tempdir().unwrap();
+ let repo = tempfile::tempdir().unwrap();
+ let spawned = repo.path().join("spawned");
+ let script = repo.path().join("marker-harness");
+ std::fs::write(
+ &script,
+ format!("#!/bin/sh\ntouch {}\nexit 0\n", spawned.display()),
+ )
+ .unwrap();
+ std::fs::set_permissions(&script, std::fs::Permissions::from_mode(0o755)).unwrap();
+
+ let mut config = Config::load(None, Some(home.path().to_path_buf())).unwrap();
+ config.data_dir = data.path().to_path_buf();
+ config.home_dir = Some(home.path().to_string_lossy().into_owned());
+ config.server_url = format!("http://{address}");
+ config.run_autowire = false;
+
+ let endpoint = ServerEndpoint::from_config_resolving_auth(&config).await;
+ let custom = home.path().join("claude-glm").join("projects");
+ let recorded = effective_store(
+ ManagedHarness::Claude,
+ home.path(),
+ repo.path(),
+ Some(&custom),
+ );
+ super::super::project_registry::record_session_store(
+ &config, &endpoint, "claude", LINKED, &recorded,
+ )
+ .unwrap();
+
+ let default_home = home.path().join(".claude");
+ let args = RunArgs {
+ workspace: Some("ws".into()),
+ project: Some("proj".into()),
+ workstream: None,
+ new_workstream: None,
+ executable: Some(script),
+ yolo: false,
+ true_yolo: false,
+ jail: None,
+ no_jail: false,
+ fresh: false,
+ force_unlock: false,
+ no_autowire: true,
+ // Pinned so a contributor's own CLAUDE_CONFIG_DIR cannot leak in.
+ env: vec![(
+ "CLAUDE_CONFIG_DIR".to_string(),
+ default_home.to_string_lossy().into_owned(),
+ )],
+ env_file: None,
+ harness: Some(RunHarnessChoice::Claude),
+ native_args: Vec::new(),
+ };
+
+ let error = run_from_with_wiring(&config, args, repo.path(), &WireOverrides::default())
+ .await
+ .expect_err("a session linked under another store must not be replaced");
+ let message = format!("{error:#}");
+ assert!(message.contains("--fresh"), "{message}");
+ assert!(!spawned.exists(), "the harness must not start");
+ assert_eq!(
+ links.load(Ordering::SeqCst),
+ 0,
+ "the workstream link must not move"
+ );
+ assert_eq!(
+ cancels.load(Ordering::SeqCst),
+ 1,
+ "the prepared run is released"
+ );
+
+ server.abort();
+ }
+
#[test]
fn missing_linked_session_starts_fresh_but_explicit_selectors_win() {
let temp = tempfile::tempdir().unwrap();
@@ -4293,6 +4585,142 @@ mod tests {
assert_eq!(explicit.expected_session_id.as_deref(), Some("chosen"));
}
+ /// A linked session missing from this launch's store is only replaced
+ /// when it was linked under the same store (or nothing was recorded).
+ #[test]
+ fn a_missing_session_linked_under_another_store_is_not_replaced() {
+ let custom = PathBuf::from("/stores/claude-glm/projects");
+ let default = PathBuf::from("/home/me/.claude/projects");
+ let claude = ManagedHarness::Claude;
+
+ assert!(store_mismatch_error(claude, "linked", None, &default).is_none());
+ assert!(store_mismatch_error(claude, "linked", Some(custom.clone()), &custom).is_none());
+
+ let error = store_mismatch_error(claude, "linked", Some(custom.clone()), &default)
+ .expect("custom store recorded, default store resolved")
+ .to_string();
+ assert!(error.contains("/stores/claude-glm/projects"), "{error}");
+ assert!(error.contains("/home/me/.claude/projects"), "{error}");
+ assert!(error.contains("CLAUDE_CONFIG_DIR"), "{error}");
+ assert!(error.contains("--fresh"), "{error}");
+
+ let omp = store_mismatch_error(
+ ManagedHarness::Omp,
+ "linked",
+ Some(custom.clone()),
+ &default,
+ )
+ .expect("stores differ")
+ .to_string();
+ assert!(omp.contains("--profile"), "{omp}");
+ let crush = store_mismatch_error(
+ ManagedHarness::Crush,
+ "linked",
+ Some(custom.clone()),
+ &default,
+ )
+ .expect("stores differ")
+ .to_string();
+ assert!(crush.contains("with the same --data-dir"), "{crush}");
+ let command_code = store_mismatch_error(
+ ManagedHarness::CommandCode,
+ "linked",
+ Some(custom),
+ &default,
+ )
+ .expect("stores differ")
+ .to_string();
+ assert!(
+ command_code.contains("relaunch from the original environment"),
+ "{command_code}"
+ );
+ }
+
+ /// The default store and an override naming the same directory are one
+ /// store, however the override is spelled.
+ #[test]
+ fn effective_store_treats_equivalent_spellings_as_one_store() {
+ let temp = tempfile::tempdir().unwrap();
+ let home = temp.path().join("home");
+ let cwd = temp.path().join("repo");
+ std::fs::create_dir_all(home.join(".claude/projects")).unwrap();
+ std::fs::create_dir_all(&cwd).unwrap();
+ let claude = ManagedHarness::Claude;
+ let default = effective_store(claude, &home, &cwd, None);
+
+ let explicit = home.join(".claude/projects");
+ assert_eq!(
+ effective_store(claude, &home, &cwd, Some(&explicit)),
+ default
+ );
+ let dotted = home.join("x/../.claude/./projects/");
+ assert_eq!(effective_store(claude, &home, &cwd, Some(&dotted)), default);
+ let relative = Path::new("../home/.claude/projects");
+ assert_eq!(
+ effective_store(claude, &home, &cwd, Some(relative)),
+ default
+ );
+ #[cfg(unix)]
+ {
+ let alias = temp.path().join("alias");
+ std::os::unix::fs::symlink(home.join(".claude"), &alias).unwrap();
+ assert_eq!(
+ effective_store(claude, &home, &cwd, Some(&alias.join("projects"))),
+ default
+ );
+ }
+
+ let other = temp.path().join("claude-glm/projects");
+ assert_ne!(effective_store(claude, &home, &cwd, Some(&other)), default);
+
+ let later = temp.path().join("later/projects");
+ let before = effective_store(claude, &home, &cwd, Some(&later));
+ std::fs::create_dir_all(&later).unwrap();
+ assert_eq!(effective_store(claude, &home, &cwd, Some(&later)), before);
+ }
+
+ /// Bare mode must scan the store the launch would resume from, not the
+ /// default one, or a custom `CLAUDE_CONFIG_DIR` session is never found.
+ #[tokio::test]
+ async fn auto_session_scan_follows_the_store_override() {
+ let temp = tempfile::tempdir().unwrap();
+ let home = temp.path().join("home");
+ let cwd = temp.path().join("repo");
+ let custom = temp.path().join("claude-custom");
+ std::fs::create_dir_all(&home).unwrap();
+ std::fs::create_dir_all(&cwd).unwrap();
+ let cwd = cwd.canonicalize().unwrap();
+ let write_session = |config_dir: &Path, id: &str| {
+ let bucket = config_dir
+ .join("projects")
+ .join(cwd.to_string_lossy().replace('/', "-"));
+ std::fs::create_dir_all(&bucket).unwrap();
+ let line = serde_json::json!({
+ "type": "user",
+ "sessionId": id,
+ "cwd": cwd,
+ "message": {"role": "user", "content": "hi"},
+ });
+ std::fs::write(bucket.join(format!("{id}.jsonl")), format!("{line}\n")).unwrap();
+ };
+ let default_id = "11111111-1111-4111-8111-111111111111";
+ let custom_id = "22222222-2222-4222-8222-222222222222";
+ write_session(&home.join(".claude"), default_id);
+ write_session(&custom, custom_id);
+ let overrides = [(
+ "CLAUDE_CONFIG_DIR".to_string(),
+ custom.to_string_lossy().into_owned(),
+ )];
+
+ let found = list_auto_sessions(&home, &cwd, &overrides).await.unwrap();
+ let claude: Vec<&str> = found
+ .iter()
+ .filter(|candidate| candidate.harness == ManagedHarness::Claude)
+ .map(|candidate| candidate.session.native_session_id.as_str())
+ .collect();
+ assert_eq!(claude, [custom_id]);
+ }
+
#[test]
fn force_fresh_bypasses_an_existing_link_and_rejects_native_selectors() {
let temp = tempfile::tempdir().unwrap();
diff --git a/crates/ai-memory-workstream/src/lib.rs b/crates/ai-memory-workstream/src/lib.rs
index 32b804ff..9849105f 100644
--- a/crates/ai-memory-workstream/src/lib.rs
+++ b/crates/ai-memory-workstream/src/lib.rs
@@ -24,6 +24,6 @@ pub use repository::{RepositoryIdentity, inspect_repository};
pub use transcript::{
AmbiguousNativeSession, ExportedTranscript, NativeSessionCandidate, discover_native_session,
export_transcript, kiro_harness_from_source_cursor, kiro_v3_resume_uses_default_store,
- list_native_sessions, native_session_exists, native_session_in_checkout,
+ list_native_sessions, native_session_exists, native_session_in_checkout, native_store_root,
wait_for_transcript_flush,
};
diff --git a/crates/ai-memory-workstream/src/transcript.rs b/crates/ai-memory-workstream/src/transcript.rs
index 498a3d0d..1e92e028 100644
--- a/crates/ai-memory-workstream/src/transcript.rs
+++ b/crates/ai-memory-workstream/src/transcript.rs
@@ -3417,6 +3417,16 @@ fn session_root(harness: ManagedHarness, home: &Path, override_dir: Option<&Path
}
}
+/// The primary native store root a launch reads: `session_dir` when an
+/// override resolved one, otherwise the harness default under `home`.
+pub fn native_store_root(
+ harness: ManagedHarness,
+ home: &Path,
+ session_dir: Option<&Path>,
+) -> PathBuf {
+ session_root(harness, home, session_dir)
+}
+
/// Kiro CLI 2.16.2 honored `KIRO_HOME` for its v2 store but wrote v3 sessions
/// to the default home during acceptance. Scan the configured root first and
/// the default root as a compatibility fallback; every result still passes
diff --git a/docs/managed-workstreams.md b/docs/managed-workstreams.md
index 9b42d59d..4d4f7155 100644
--- a/docs/managed-workstreams.md
+++ b/docs/managed-workstreams.md
@@ -473,6 +473,19 @@ expand `$HOME` on the command line and write absolute paths in an
`--env-file`. Manual `install-hooks` / `install-mcp` do not take `--env`; they
read their own environment.
+Automatic harness selection (bare `run`, `continue` and `resume`) scans the
+store the launch resolves from that same environment, so a checkout whose
+sessions live under a custom `CLAUDE_CONFIG_DIR` is found when the variable is
+set. Whenever the client links a session, at launch or when the run finishes,
+it also records that session's store in the client-local `client-projects.json`.
+If a later launch cannot find the linked session in the store it resolves and
+the recorded store is a different directory, the launch stops with an error
+naming both directories instead of starting fresh and repointing the workstream
+away from a session that still exists. Relaunch with the same variable (or
+store flag) to resume it, or pass `--fresh` to start a new session. Sessions linked before this record
+existed, and a session missing from its own recorded store, still start fresh
+as before.
+
The Pi-family adapter
also recognizes a complete `.jsonl.<nonce>.tmp` atomic-write file when a native
process exits before renaming it; incomplete final JSONL records are never