Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(run): allow same-owner lease recovery
AkitaOnRailse2d7d17d906d
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex a7c02988..c0229db6 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -12,6 +12,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0provider. (#1026)### Fixed+- 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+ authenticated operator (or another unattributed lease in single-user+ operation), while cross-operator eviction remains refused; the command does+ not kill a native process. (#795)- Fixed Unix release archives potentially carrying macOS AppleDouble sidecarsoutside the native upgrader's strict path allowlist. Release packing nowdisables sidecar generation, and packaging tests lock the staged top-leveldiff --git a/README.md b/README.mdindex 7503c407..a2ec9225 100644--- a/README.md+++ b/README.md@@ -364,8 +364,16 @@ config home.ai-memory run claudeai-memory run codex --yolo # later: same workstream, different harnessai-memory continue # resume the newest managed checkout+# after a dead launcher left its lease behind (same operator only)+ai-memory run --force-unlock codex```+`--force-unlock` immediately expires the selected workstream's active lease;+use it only when you know the previous launcher is gone. It does not kill a+native process, and it cannot evict another authenticated operator's run. See+the [managed-workstream recovery notes](docs/managed-workstreams.md#lease-recovery)+for the full safety contract.+Auto-wiring is on by default; opt out with `ai-memory run --no-autowire` or`AI_MEMORY_RUN_AUTOWIRE=false`. You can still wire agents by hand with`install-hooks` / `install-mcp` (e.g. for a harness you never launch throughdiff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rsindex d2705980..5ccc5fd3 100644--- a/crates/ai-memory-cli/src/cli.rs+++ b/crates/ai-memory-cli/src/cli.rs@@ -49,7 +49,7 @@ pub enum Command {RepairBackfillTimestamps(RepairBackfillTimestampsArgs),/// Launch an agent in an opt-in, cross-harness managed workstream./// Native arguments are forwarded except exact wrapper flags such as- /// `--yolo` and `--fresh`.+ /// `--yolo`, `--fresh`, and `--force-unlock`.Run(RunArgs),/// Pick a local project and installed harness, then launch from that/// checkout. Removes the `cd` step `run` requires.@@ -326,6 +326,12 @@ pub struct RunArgs {/// resuming or adopting an existing harness session.#[arg(long)]pub fresh: bool,+ /// Force-expire the selected workstream's active lease before launching.+ /// Use only when the previous launcher is gone: its later heartbeat or+ /// finish will be refused. The server permits takeover only for the same+ /// authenticated operator (or the single-user, unattributed owner).+ #[arg(long)]+ pub force_unlock: bool,/// Skip the one-time auto-install of this harness's ai-memory hooks + MCP./// Auto-wire is on by default so a managed launch captures without a manual/// `install-hooks`/`install-mcp` step; pass this (or setdiff --git a/crates/ai-memory-cli/src/commands/continue_session.rs b/crates/ai-memory-cli/src/commands/continue_session.rsindex f5a75533..23b3f56c 100644--- a/crates/ai-memory-cli/src/commands/continue_session.rs+++ b/crates/ai-memory-cli/src/commands/continue_session.rs@@ -76,6 +76,7 @@ pub async fn run(config: &Config, args: ContinueArgs) -> Result<i32> {jail: None,no_jail: false,fresh: args.fresh,+ force_unlock: false,no_autowire: false,env: Vec::new(),env_file: None,diff --git a/crates/ai-memory-cli/src/commands/resume.rs b/crates/ai-memory-cli/src/commands/resume.rsindex be4d5612..e5825df4 100644--- a/crates/ai-memory-cli/src/commands/resume.rs+++ b/crates/ai-memory-cli/src/commands/resume.rs@@ -165,6 +165,7 @@ pub async fn run(config: &Config, args: ResumeArgs) -> Result<i32> {jail: None,no_jail: false,fresh: args.fresh,+ force_unlock: false,no_autowire: false,env: Vec::new(),env_file: None,diff --git a/crates/ai-memory-cli/src/commands/run.rs b/crates/ai-memory-cli/src/commands/run.rsindex 3594e03e..80be0fda 100644--- a/crates/ai-memory-cli/src/commands/run.rs+++ b/crates/ai-memory-cli/src/commands/run.rs@@ -126,6 +126,7 @@ pub(super) async fn run_from_with_wiring(let trailing_yolo = remove_wrapper_yolo(&mut native_args);let trailing_true_yolo = remove_wrapper_true_yolo(&mut native_args);let trailing_fresh = remove_wrapper_fresh(&mut native_args);+ let trailing_force_unlock = remove_wrapper_force_unlock(&mut native_args);let trailing_no_autowire = remove_wrapper_no_autowire(&mut native_args);let trailing_jail = remove_wrapper_jail(&mut native_args);let jail_request = jail_request(args.jail, args.no_jail, trailing_jail)?;@@ -136,6 +137,7 @@ pub(super) async fn run_from_with_wiring();let yolo_requested = yolo_modes.yolo;let force_fresh = args.fresh || trailing_fresh;+ let force_unlock = args.force_unlock || trailing_force_unlock;let no_autowire = args.no_autowire || trailing_no_autowire;let run_env = resolve_run_env(args.env_file.as_deref(), &args.env).context("resolving --env/--env-file for the managed run")?;@@ -226,6 +228,7 @@ pub(super) async fn run_from_with_wiring(available_agents: unique_auto_agents(&auto_candidates),workstream: args.workstream,new_workstream: args.new_workstream,+ force_unlock,lease_owner: lease_owner(),};let interrupted_before_spawn = CancellationToken::new();@@ -1618,6 +1621,12 @@ fn remove_wrapper_fresh(args: &mut Vec<OsString>) -> bool {args.len() != before}+fn remove_wrapper_force_unlock(args: &mut Vec<OsString>) -> bool {+ let before = args.len();+ args.retain(|arg| arg != OsStr::new("--force-unlock"));+ args.len() != before+}+fn remove_wrapper_no_autowire(args: &mut Vec<OsString>) -> bool {let before = args.len();args.retain(|arg| arg != OsStr::new("--no-autowire"));@@ -2283,6 +2292,15 @@ async fn prepare_managed_run(interactive: bool,interrupted: &CancellationToken,) -> Result<PrepareManagedRunResponse> {+ if request.force_unlock {+ return match post_json(endpoint, "/workstream/runs", request).await {+ Err(error) if is_active_workstream_conflict(&error) => Err(error.context(+ "--force-unlock was refused: the active lease belongs to another operator, or \+ the server does not support forced lease recovery",+ )),+ other => other,+ };+ }let result = prepare_managed_run_with_retry(endpoint,request,@@ -3284,6 +3302,7 @@ mod tests {available_agents: Vec::new(),workstream: None,new_workstream: None,+ force_unlock: false,lease_owner: "workstation:43".into(),};@@ -3402,6 +3421,7 @@ mod tests {available_agents: Vec::new(),workstream: None,new_workstream: None,+ force_unlock: false,lease_owner: "workstation:43".into(),}}@@ -3475,6 +3495,27 @@ mod tests {server.abort();}+ #[tokio::test]+ async fn force_unlock_asks_once_instead_of_waiting_out_the_lease() {+ let (app, attempts) = held_lease_server(usize::MAX, Duration::from_secs(60));+ let (endpoint, server) = serve(app).await;+ let mut request = held_lease_request();+ request.force_unlock = true;+ let started = std::time::Instant::now();++ let error = prepare_managed_run(&endpoint, &request, true, &CancellationToken::new())+ .await+ .expect_err("a server that refuses the takeover must fail immediately");++ assert!(started.elapsed() < Duration::from_secs(5));+ assert_eq!(attempts.load(Ordering::SeqCst), 1);+ assert!(+ format!("{error:#}").contains("--force-unlock was refused"),+ "{error:#}"+ );+ server.abort();+ }+#[tokio::test]async fn ctrl_c_aborts_the_held_lease_wait_immediately() {let (app, attempts) = held_lease_server(1, Duration::from_secs(60));@@ -3969,6 +4010,30 @@ mod tests {assert_eq!(trailing, ["--model", "opus"].map(OsString::from));}+ #[test]+ fn force_unlock_is_a_wrapper_flag_before_or_after_the_harness() {+ let cli = Cli::try_parse_from([+ "ai-memory",+ "run",+ "--force-unlock",+ "codex",+ "--model",+ "gpt-5",+ ])+ .unwrap();+ let CliCommand::Run(args) = cli.command else {+ panic!("expected run command");+ };+ assert!(args.force_unlock);+ assert_eq!(args.native_args, ["--model", "gpt-5"].map(OsString::from));++ let mut trailing = ["--model", "gpt-5", "--force-unlock"]+ .map(OsString::from)+ .to_vec();+ assert!(remove_wrapper_force_unlock(&mut trailing));+ assert_eq!(trailing, ["--model", "gpt-5"].map(OsString::from));+ }+#[test]fn wrapper_no_autowire_parses_before_or_after_the_harness() {// Before the harness: clap binds it as the wrapper flag.@@ -4129,6 +4194,7 @@ mod tests {jail: None,no_jail: false,fresh: false,+ force_unlock: false,no_autowire: true,env: vec![("CLAUDE_CONFIG_DIR".to_string(), "/from/cli".to_string())],env_file: Some(env_file.clone()),@@ -4617,6 +4683,7 @@ mod tests {jail: None,no_jail: false,fresh: false,+ force_unlock: false,no_autowire: false,env: Vec::new(),env_file: None,@@ -4772,6 +4839,7 @@ mod tests {jail: None,no_jail: false,fresh: false,+ force_unlock: false,no_autowire: false,env,env_file: None,diff --git a/crates/ai-memory-cli/src/commands/show.rs b/crates/ai-memory-cli/src/commands/show.rsindex e64b664b..b0a48076 100644--- a/crates/ai-memory-cli/src/commands/show.rs+++ b/crates/ai-memory-cli/src/commands/show.rs@@ -229,6 +229,7 @@ pub async fn run(config: &Config, args: ShowArgs) -> Result<i32> {jail: None,no_jail: false,fresh: args.fresh,+ force_unlock: false,no_autowire: false,env: Vec::new(),env_file: None,diff --git a/crates/ai-memory-core/src/workstream.rs b/crates/ai-memory-core/src/workstream.rsindex e63db1c9..035de2a4 100644--- a/crates/ai-memory-core/src/workstream.rs+++ b/crates/ai-memory-core/src/workstream.rs@@ -146,6 +146,12 @@ pub struct PrepareManagedRunRequest {/// Create and select a fresh named workstream.#[serde(default, skip_serializing_if = "Option::is_none")]pub new_workstream: Option<String>,+ /// Expire an active lease owned by this same operator before opening the+ /// replacement run. This is an explicit recovery override for a launcher+ /// that exited without releasing its lease; it never permits cross-owner+ /// takeover.+ #[serde(default)]+ pub force_unlock: bool,/// Diagnostic owner label (host and process id), not an authorization key.pub lease_owner: String,}@@ -398,5 +404,27 @@ mod tests {assert!(!request.automatic_harness);assert!(request.available_agents.is_empty());+ assert!(!request.force_unlock);+ }++ #[test]+ fn forced_unlock_is_explicit_on_the_wire() {+ let request: PrepareManagedRunRequest = serde_json::from_value(serde_json::json!({+ "workspace": "default",+ "project": "memory",+ "cwd": "/repo",+ "repo_fingerprint": "repo",+ "worktree_fingerprint": "worktree",+ "agent": "codex",+ "force_unlock": true,+ "lease_owner": "host:2"+ }))+ .unwrap();++ assert!(request.force_unlock);+ assert_eq!(+ serde_json::to_value(request).unwrap()["force_unlock"],+ serde_json::json!(true)+ );}}diff --git a/crates/ai-memory-hooks/src/workstream.rs b/crates/ai-memory-hooks/src/workstream.rsindex dd1ebc9d..f3a2292c 100644--- a/crates/ai-memory-hooks/src/workstream.rs+++ b/crates/ai-memory-hooks/src/workstream.rs@@ -288,9 +288,10 @@ async fn prepare_run(Ok(owner) => owner,Err(failure) => return error(StatusCode::INTERNAL_SERVER_ERROR, failure.to_string()),};+ let force_unlock = request.force_unlock;let prepared = state.writer- .prepare_workstream_run_owned(+ .prepare_workstream_run_owned_with_unlock(PrepareWorkstreamRun {workspace_id: scope.workspace_id,project_id: scope.project_id,@@ -304,6 +305,7 @@ async fn prepare_run(lease_owner: request.lease_owner,},owner_user,+ force_unlock,).await;match prepared {@@ -1439,6 +1441,7 @@ mod tests {available_agents: vec![AgentKind::Codex, AgentKind::ClaudeCode],workstream: None,new_workstream: None,+ force_unlock: false,lease_owner: "automatic".into(),}),)@@ -1476,6 +1479,7 @@ mod tests {available_agents: Vec::new(),workstream: None,new_workstream: None,+ force_unlock: false,lease_owner: "explicit".into(),}),)@@ -1515,6 +1519,7 @@ mod tests {available_agents: vec![AgentKind::KimiCode, AgentKind::ClaudeCode],workstream: None,new_workstream: None,+ force_unlock: false,lease_owner: "automatic".into(),}),)@@ -1561,6 +1566,7 @@ mod tests {available_agents: Vec::new(),workstream: None,new_workstream: None,+ force_unlock: false,lease_owner: "alice-launcher".into(),}),)@@ -1613,6 +1619,106 @@ mod tests {);}+ #[tokio::test]+ async fn force_unlock_cannot_evict_another_operator() {+ let temp = TempDir::new().unwrap();+ let store = Store::open(temp.path()).unwrap();+ let state = test_state(&store, temp.path());+ for name in ["alice", "bob"] {+ store+ .writer+ .create_human_user(+ ai_memory_core::NewUser {+ username: name.into(),+ name: None,+ email: None,+ },+ ai_memory_core::UserRole::User,+ None,+ false,+ )+ .await+ .unwrap();+ }+ let actor = |name: &str| {+ Some(Extension(ai_memory_core::ActorContext {+ user: Some(name.into()),+ ..ai_memory_core::ActorContext::default()+ }))+ };+ let request = |force_unlock: bool, lease_owner: &str| PrepareManagedRunRequest {+ workspace: "default".into(),+ project: "managed-force-unlock".into(),+ cwd: "/repo".into(),+ repo_fingerprint: "repo".into(),+ worktree_fingerprint: "worktree".into(),+ agent: AgentKind::Codex,+ automatic_harness: false,+ available_agents: Vec::new(),+ workstream: None,+ new_workstream: None,+ force_unlock,+ lease_owner: lease_owner.into(),+ };++ let first = prepare_run(+ State(state.clone()),+ None,+ actor("alice"),+ None,+ Json(request(false, "alice:1")),+ )+ .await;+ assert_eq!(first.status(), StatusCode::OK);+ let body = to_bytes(first.into_body(), 64 * 1024).await.unwrap();+ let first: PrepareManagedRunResponse = serde_json::from_slice(&body).unwrap();++ let refused = prepare_run(+ State(state.clone()),+ None,+ actor("bob"),+ None,+ Json(request(true, "bob:2")),+ )+ .await;+ assert_eq!(refused.status(), StatusCode::CONFLICT);+ assert!(+ store+ .writer+ .heartbeat_managed_run(first.run_id)+ .await+ .unwrap(),+ "the refused caller must not disturb Alice's lease"+ );++ let replacement = prepare_run(+ State(state),+ None,+ actor("alice"),+ None,+ Json(request(true, "alice:3")),+ )+ .await;+ assert_eq!(replacement.status(), StatusCode::OK);+ let body = to_bytes(replacement.into_body(), 64 * 1024).await.unwrap();+ let replacement: PrepareManagedRunResponse = serde_json::from_slice(&body).unwrap();+ assert_ne!(replacement.run_id, first.run_id);+ assert!(+ !store+ .writer+ .heartbeat_managed_run(first.run_id)+ .await+ .unwrap()+ );+ assert!(+ store+ .writer+ .heartbeat_managed_run(replacement.run_id)+ .await+ .unwrap()+ );+ }+#[tokio::test]async fn kiro_is_accepted_as_an_explicit_and_automatic_harness() {let temp = TempDir::new().unwrap();@@ -1635,6 +1741,7 @@ mod tests {available_agents: Vec::new(),workstream: None,new_workstream: None,+ force_unlock: false,lease_owner: "explicit".into(),}),)@@ -1673,6 +1780,7 @@ mod tests {available_agents: vec![AgentKind::KiroCli],workstream: None,new_workstream: None,+ force_unlock: false,lease_owner: "automatic".into(),}),)@@ -1702,6 +1810,7 @@ mod tests {available_agents: Vec::new(),workstream: None,new_workstream: None,+ force_unlock: false,lease_owner: "explicit".into(),}),)@@ -1740,6 +1849,7 @@ mod tests {available_agents: vec![AgentKind::CommandCode, AgentKind::ClaudeCode],workstream: None,new_workstream: None,+ force_unlock: false,lease_owner: "automatic".into(),}),)@@ -1769,6 +1879,7 @@ mod tests {available_agents: Vec::new(),workstream: None,new_workstream: None,+ force_unlock: false,lease_owner: "explicit".into(),}),)@@ -1807,6 +1918,7 @@ mod tests {available_agents: vec![AgentKind::Grok],workstream: None,new_workstream: None,+ force_unlock: false,lease_owner: "automatic".into(),}),)@@ -1839,6 +1951,7 @@ mod tests {available_agents: Vec::new(),workstream: None,new_workstream: None,+ force_unlock: false,lease_owner: "explicit".into(),}),)@@ -1877,6 +1990,7 @@ mod tests {available_agents: vec![AgentKind::AntigravityCli],workstream: None,new_workstream: None,+ force_unlock: false,lease_owner: "automatic".into(),}),)@@ -2144,6 +2258,7 @@ mod tests {available_agents: Vec::new(),workstream: None,new_workstream: None,+ force_unlock: false,lease_owner: "alice".into(),}),)diff --git a/crates/ai-memory-store/src/ops.rs b/crates/ai-memory-store/src/ops.rsindex d93ea5cf..d7e64a82 100644--- a/crates/ai-memory-store/src/ops.rs+++ b/crates/ai-memory-store/src/ops.rs@@ -12545,6 +12545,7 @@ pub(crate) mod tests {lease_owner: "test".into(),},None,+ false,).unwrap();@@ -14457,6 +14458,7 @@ pub(crate) mod tests {lease_owner: "test".to_string(),},None,+ false,).expect("opening a managed run should succeed")}diff --git a/crates/ai-memory-store/src/workstream.rs b/crates/ai-memory-store/src/workstream.rsindex d7380d17..f85a2c34 100644--- a/crates/ai-memory-store/src/workstream.rs+++ b/crates/ai-memory-store/src/workstream.rs@@ -276,6 +276,7 @@ pub(crate) fn prepare_run(conn: &mut Connection,input: &PrepareWorkstreamRun,owner_user: Option<&str>,+ force_unlock: bool,) -> StoreResult<PreparedWorkstreamRun> {if owner_user.is_some_and(|owner| ai_memory_core::IdentityKey::from_storage_key(owner).is_none())@@ -293,21 +294,29 @@ pub(crate) fn prepare_run()?;let (workstream_id, workstream_name) = select_workstream(&tx, input, now)?;- let busy: Option<(String, i64)> = tx+ let busy: Option<(Vec<u8>, String, i64, Option<String>)> = tx.query_row(- "SELECT lease_owner, lease_expires_at FROM managed_runs \+ "SELECT id, lease_owner, lease_expires_at, owner_user FROM managed_runs \WHERE workstream_id = ?1 AND state = 'active'",params![workstream_id.as_bytes()],- |row| Ok((row.get(0)?, row.get(1)?)),+ |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?, row.get(3)?)),).optional()?;- if let Some((owner, expires)) = busy {- return Err(StoreError::WorkstreamBusy(format!(- "owned by {owner} until {}",- Timestamp::from_microsecond(expires)- .map(|t| t.to_string())- .unwrap_or_else(|_| expires.to_string())- )));+ if let Some((run_id, owner, expires, active_owner_user)) = busy {+ if force_unlock && active_owner_user.as_deref() == owner_user {+ tx.execute(+ "UPDATE managed_runs SET state = 'expired', ended_at = ?1, \+ lease_expires_at = ?1 WHERE id = ?2 AND state = 'active'",+ params![now, run_id],+ )?;+ } else {+ return Err(StoreError::WorkstreamBusy(format!(+ "owned by {owner} until {}",+ Timestamp::from_microsecond(expires)+ .map(|t| t.to_string())+ .unwrap_or_else(|_| expires.to_string())+ )));+ }}let latest_sequence: i64 = tx.query_row(diff --git a/crates/ai-memory-store/src/writer.rs b/crates/ai-memory-store/src/writer.rsindex 95992e9e..4462d925 100644--- a/crates/ai-memory-store/src/writer.rs+++ b/crates/ai-memory-store/src/writer.rs@@ -715,6 +715,7 @@ pub(crate) enum WriteCmd {PrepareWorkstreamRun {input: PrepareWorkstreamRun,owner_user: Option<String>,+ force_unlock: bool,reply: oneshot::Sender<StoreResult<PreparedWorkstreamRun>>,},HeartbeatManagedRun {@@ -3013,11 +3014,24 @@ impl WriterHandle {&self,input: PrepareWorkstreamRun,owner_user: Option<String>,+ ) -> StoreResult<PreparedWorkstreamRun> {+ self.prepare_workstream_run_owned_with_unlock(input, owner_user, false)+ .await+ }++ /// Select a workstream, optionally replacing this same operator's active+ /// lease in the same writer transaction.+ pub async fn prepare_workstream_run_owned_with_unlock(+ &self,+ input: PrepareWorkstreamRun,+ owner_user: Option<String>,+ force_unlock: bool,) -> StoreResult<PreparedWorkstreamRun> {let (tx, rx) = oneshot::channel();self.send(WriteCmd::PrepareWorkstreamRun {input,owner_user,+ force_unlock,reply: tx,}).await?;@@ -4269,10 +4283,15 @@ fn worker_loop(mut conn: Connection, mut rx: mpsc::Receiver<WriteCmd>) {WriteCmd::PrepareWorkstreamRun {input,owner_user,+ force_unlock,reply,} => {- let result =- crate::workstream::prepare_run(&mut conn, &input, owner_user.as_deref());+ let result = crate::workstream::prepare_run(+ &mut conn,+ &input,+ owner_user.as_deref(),+ force_unlock,+ );send_or_warn(reply, result, "prepare_workstream_run");}WriteCmd::HeartbeatManagedRun { run_id, reply } => {diff --git a/crates/ai-memory-store/tests/suite/multi_session.rs b/crates/ai-memory-store/tests/suite/multi_session.rsindex 4ae0e4b1..204f5bd0 100644--- a/crates/ai-memory-store/tests/suite/multi_session.rs+++ b/crates/ai-memory-store/tests/suite/multi_session.rs@@ -22,7 +22,7 @@ use ai_memory_core::{owner_stamp,};use ai_memory_store::{- LinkOrAdoptManagedRunSession, ManagedRunSessionLink, PrepareWorkstreamRun, Store,+ LinkOrAdoptManagedRunSession, ManagedRunSessionLink, PrepareWorkstreamRun, Store, StoreError,WorkstreamSelection,};@@ -917,6 +917,99 @@ async fn stale_codex_run_recovery_cannot_cross_project_owner_or_session_boundari);}+/// Forced lease recovery is deliberately narrower than project write access:+/// the same operator can recover their own abandoned launcher, while another+/// operator in the same project cannot evict it. The old run becomes terminal+/// in the same transaction that creates the replacement.+#[tokio::test]+async fn force_unlock_replaces_only_the_same_operators_active_run() {+ let tmp = tempfile::tempdir().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let (ws, proj) = scope(&store).await;+ let alice = operator("alice");+ let bob = operator("bob");+ let prepare = |lease_owner: &str| PrepareWorkstreamRun {+ workspace_id: ws,+ project_id: proj,+ repo_fingerprint: "repo".into(),+ worktree_fingerprint: "worktree".into(),+ cwd: "/repo".into(),+ agent: AgentKind::Codex,+ automatic_harness: false,+ available_agents: Vec::new(),+ selection: WorkstreamSelection::Current,+ lease_owner: lease_owner.into(),+ };++ let abandoned = store+ .writer+ .prepare_workstream_run_owned(prepare("alice:1"), Some(alice.clone()))+ .await+ .unwrap();+ let refused = store+ .writer+ .prepare_workstream_run_owned_with_unlock(prepare("bob:2"), Some(bob), true)+ .await+ .unwrap_err();+ assert!(matches!(refused, StoreError::WorkstreamBusy(_)));+ assert!(+ store+ .writer+ .heartbeat_managed_run(abandoned.run_id)+ .await+ .unwrap(),+ "a refused cross-owner takeover must leave the original lease active"+ );++ let replacement = store+ .writer+ .prepare_workstream_run_owned_with_unlock(prepare("alice:3"), Some(alice.clone()), true)+ .await+ .unwrap();+ assert_ne!(replacement.run_id, abandoned.run_id);+ assert!(+ !store+ .writer+ .heartbeat_managed_run(abandoned.run_id)+ .await+ .unwrap(),+ "the replaced run must be terminal"+ );+ assert!(+ store+ .writer+ .heartbeat_managed_run(replacement.run_id)+ .await+ .unwrap(),+ "the replacement is the sole live control"+ );++ let solo = store+ .writer+ .prepare_workstream_run_owned(+ PrepareWorkstreamRun {+ selection: WorkstreamSelection::New("solo".into()),+ ..prepare("solo:1")+ },+ None,+ )+ .await+ .unwrap();+ let solo_replacement = store+ .writer+ .prepare_workstream_run_owned_with_unlock(+ PrepareWorkstreamRun {+ selection: WorkstreamSelection::Named("solo".into()),+ ..prepare("solo:2")+ },+ None,+ true,+ )+ .await+ .unwrap();+ assert_ne!(solo_replacement.run_id, solo.run_id);+}+/// Two launches in one repository are a real possibility when the operator/// uses separate named workstreams. Recovery must refuse to guess between/// them, and an active foreign id must not be treated as a stale trigger.diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex 05fd1c36..28fd5c4b 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -205,8 +205,12 @@ ledger/session state: after any harness establishes the workstream, a newlyjoining harness starts fresh and receives portable history instead of adoptingunrelated old native history. Handled launcher failures cancel their lease;normal reopen retries brief finalization conflicts, while an unclean process-death remains bounded by the renewable lease expiry. See [Managed cross-harness-workstreams](managed-workstreams.md).+death remains bounded by the renewable lease expiry. An explicit+`--force-unlock` recovery expires and replaces a selected active lease in the+same writer transaction, but only when its durable operator attribution equals+the new run's attribution; the informational `host:pid` lease label is never an+authorization key. The old run can no longer heartbeat or finish. See [Managed+cross-harness workstreams](managed-workstreams.md).## Hook event vocabularydiff --git a/docs/managed-workstreams.md b/docs/managed-workstreams.mdindex e4575301..9b42d59d 100644--- a/docs/managed-workstreams.md+++ b/docs/managed-workstreams.md@@ -74,9 +74,9 @@ ai-memory run```Everything after the harness name is native argv except the wrapper-owned exact-flags `--yolo` and `--fresh`. No `--` separator is needed, and ai-memory does-not maintain a second copy of each harness's option schema. Other wrapper-options come first:+flags `--yolo`, `--fresh`, and `--force-unlock`. No `--` separator is needed,+and ai-memory does not maintain a second copy of each harness's option schema.+Other wrapper options come first:Portable events, handoffs, and project briefs are injected as explicitlydelimited, untrusted historical data. Instruction-like text inside stored@@ -88,7 +88,8 @@ file, and the current checkout remain authoritative.```textai-memory run [--workspace NAME] [--project NAME][--workstream NAME | --new NAME] [--executable PATH]- [--yolo] [--fresh] [--env KEY=VALUE]... [--env-file PATH]+ [--yolo] [--fresh] [--force-unlock]+ [--env KEY=VALUE]... [--env-file PATH][claude|claude*|codex|opencode|opencode2|pi|crush|omp|kimi|command-code|kiro|grok|antigravity][native arguments...]```@@ -691,6 +692,8 @@ immediately. A new launch retries an active-workstream conflict briefly so aprevious launcher can finish; if another harness is genuinely still running,the conflict remains and concurrent writers are still rejected.+### Lease recovery+A launcher that dies without releasing its lease — killed, its terminalclosed, or a sandbox such as ai-jail torn down — leaves the workstream helduntil that lease lapses. An interactive relaunch (stdin and stderr are@@ -705,6 +708,25 @@ retry window and fail fast rather than hanging. Terminalinterrupts continue to reach the child while the parent stays alive to finishor cancel the run.+When you know the prior launcher is gone and do not want to wait for the lease,+force-expire it explicitly:++```bash+ai-memory run --force-unlock codex+# The exact wrapper flag is also accepted after the harness name.+ai-memory run codex --force-unlock+```++The replacement is atomic and limited to the same durable authenticated+operator; in single-user or otherwise unattributed operation, both runs must be+unattributed. A different operator's active run is still refused. The command+expires the managed lease only — it does not signal or kill a native process.+If the previous launcher is actually alive, its later heartbeats and finish are+rejected, and its final transcript tail may not be imported. Use+`--force-unlock` only after verifying that launcher has stopped. Older servers+do not honor the request and return a refusal, so upgrade the server as well as+the client before relying on this recovery path.+Before the child starts, `Ctrl+C` at the native-session chooser cancels theacquired run and exits without requiring Enter or adopting the selected session.The launcher waits for the server's cancellation response. A request error isdiff --git a/docs/security-boundaries.md b/docs/security-boundaries.mdindex 845b9f25..d2344cbe 100644--- a/docs/security-boundaries.md+++ b/docs/security-boundaries.md@@ -61,7 +61,7 @@ boundary not yet built.| 12 | Network/auth posture | `config.rs` loopback `DEFAULT_BIND`; `serve.rs` `validate_http_exposure`, `require_allowed_host`; `auth.rs` `require_bearer` | `serve.rs` host-guard (missing→400 / forged→403), non-loopback-requires-token; `auth.rs` wrong-token 401 | STRONG || 13 | Managed-run transcript attribution (concurrent launches in one checkout, invariant #16) | `ai-memory-store/src/workstream.rs` `link_native_session` stamps `native_session_linked_at` on its own run only, both `finish` updates drop the stamp when the session changes, `run_status` reports it; `ai-memory-cli/src/commands/run.rs` `resolve_native_session_after_run` takes a linked session only when `ai-memory-workstream` `native_session_in_checkout` holds it for this checkout (OpenCode by recorded directory), never falls back to a link it set aside, and turns an `AmbiguousNativeSession` into a warning with nothing imported; `ai-memory-workstream/src/transcript.rs` `discover_crush` claims only the one top-level session created (or, with `--continue`, touched) during the run, and in a data directory outside the project only one that edited a file in it | `multi_session.rs` `a_session_linked_by_one_managed_run_is_not_another_runs`; `run.rs` `a_session_linked_during_the_run_wins_over_discovery` (concurrent newer session, another checkout's link refused, no fallback to it, unlinked control); `transcript.rs` `native_session_in_checkout_checks_the_opencode_directory`; `store/src/lib.rs` `managed_run_status_reports_a_link_made_during_the_run`; `run.rs` `ambiguous_crush_discovery_keeps_the_run`; `transcript.rs` `crush_discovery_claims_only_the_session_the_run_created`, `crush_discovery_in_a_shared_store_claims_only_an_edit_here` | PARTIAL: a run whose child links nothing still falls back to discovering the newest session in the checkout; Crush, which has no hooks, relies on that discovery alone and claims nothing when it is ambiguous || 13a | Managed Codex stale-daemon run recovery (#987; concurrent launches, project/worktree isolation, operator isolation) | `managed_runs.owner_user` (V71) uses the topology-aware `IdentityKey` owner stamp; `router.rs` resolves and authorizes the SessionStart repository before handling the untrusted run id; store `link_or_adopt_native_session` selects and links in one writer transaction and admits only the sole live, undelivered, never-linked Codex run in the exact workspace/project/checkout-cwd/owner bucket. An active supplied id must itself match every boundary; another harness, an ambiguity, or a second native session is refused | `multi_session.rs` `stale_codex_run_recovery_cannot_cross_project_owner_or_session_boundaries` (foreign owner, foreign checkout, and cross-project candidates refused; project-local controls and racing rebind), `stale_codex_run_recovery_fails_closed_on_ambiguity_and_active_mismatch` (two candidates and active foreign id refused, exact control); `workstream.rs` `prepare_stamps_the_operator_bucket_used_by_session_start_recovery` (HTTP actor stamp with foreign and legitimate controls); `router.rs` `managed_session_start_delivers_ledger_and_pending_handoff` supplies a finished stale id and proves the new run is linked and delivered | STRONG for SessionStart recovery. No candidate is selected from a run id's stale scope, another checkout, or another operator bucket; ambiguity deliberately falls back to no managed packet |-| 13b | Managed-run lease exclusivity (one active run per workstream, invariant #16) | `ai-memory-store/src/workstream.rs` `prepare_run` expires lapsed leases and refuses any other `active` run on the workstream inside one transaction (`StoreError::WorkstreamBusy`), regardless of the `lease_owner` label; `heartbeat` renews only `active` rows. `ai-memory-cli/src/commands/run.rs` `wait_out_held_lease` (interactive relaunch) only waits for a reported expiry and retries — it never cancels or claims another run, so the server's busy check stays the sole arbiter | `store/src/lib.rs` `managed_workstream_batches_are_idempotent_and_release_the_lease` (second prepare refused while active); `run.rs` `a_renewed_lease_is_reported_as_a_live_owner_not_taken_over` (renewing holder is reported, never displaced), with controls `interactive_launch_waits_out_a_lapsing_lease_then_proceeds` and `ctrl_c_aborts_the_held_lease_wait_immediately` | STRONG for exclusivity. The `lease_owner` label (`host:pid`) is informational only and not unique inside ai-jail (every jailed launcher reports `ai-sandbox:<ns-pid>`), so it must never become an ownership key |+| 13b | Managed-run lease exclusivity and explicit recovery (one active run per workstream, invariant #16) | `ai-memory-store/src/workstream.rs` `prepare_run` expires lapsed leases and otherwise refuses an `active` run inside the writer transaction (`StoreError::WorkstreamBusy`). The explicit `force_unlock` path may expire and replace that row in the same transaction only when its durable `owner_user` equals the incoming actor's attribution; different operators remain isolated. `heartbeat` renews only `active` rows. `ai-memory-cli/src/commands/run.rs` normally uses `wait_out_held_lease`; `--force-unlock` instead asks once and fails immediately when refused. Neither path treats the informational `lease_owner` label as authority | `multi_session.rs` `force_unlock_replaces_only_the_same_operators_active_run` (foreign operator refused with live control, same operator succeeds, old run loses heartbeat, unattributed single-user control); hooks `workstream.rs` `force_unlock_cannot_evict_another_operator` exercises the HTTP actor boundary; CLI `run.rs` `force_unlock_asks_once_instead_of_waiting_out_the_lease`; existing controls `managed_workstream_batches_are_idempotent_and_release_the_lease`, `a_renewed_lease_is_reported_as_a_live_owner_not_taken_over`, `interactive_launch_waits_out_a_lapsing_lease_then_proceeds`, and `ctrl_c_aborts_the_held_lease_wait_immediately` | STRONG for exclusivity. The `lease_owner` label (`host:pid`) is informational only and not unique inside ai-jail (every jailed launcher reports `ai-sandbox:<ns-pid>`), so it must never become an ownership key. A shared unattributed/root context is intentionally one operator bucket; deployments needing person-level refusal must authenticate DB users || 14 | Per-project authorization (#708) | `ai-memory-store/src/project_authz.rs` `authorize_project` / `ProjectAuthz::authorize` choke point (V68 `project_grants` + `projects.access_mode`, default `open`; V69 `projects.created_by` feeds `is_creator`); `scope.rs` `ScopeResolver::with_project_authz` (reader pool for reads, writer actor for writes) and its free forms `authorize_scope_for` / `*_guarded`, attached for every DB user by `ai-memory-mcp` `scope_resolver_as`, `ai-memory-web` `authorize_read` / `lookup_project`, and `ai-memory-hooks` (`grants.rs` `authorize_resolved` for run/workstream ids, the capture check in `router.rs`); read-shaped mutations resolve at `ProjectAccess::Write` (`resolve_existing_args(.., need)`); unscoped reads filtered before `LIMIT` by `reader.rs` `readable_repository_sql`; `WriterHandle::authorize_project` as defense in depth. Page ids are never taken from a caller (only derived from already-authorized hits), so there is no page-id entry point to guard | `tests/suite/project_authz.rs` (decision matrix, ship-inert, resolver gate); `tests/suite/access_mode.rs` `every_caller_against_both_modes`, `a_restricted_project_admits_the_team_and_refuses_the_outsider`, `new_projects_follow_the_server_default_and_admit_their_creator`; `scope.rs` `the_argument_shape_does_not_decide_the_level`, `a_user_reaches_only_what_they_were_granted`, `creating_authorizes_against_a_project_that_already_exists`, `a_refused_scope_fails_the_search_instead_of_shortening_it`; `grants.rs` `search_finds_only_what_the_viewer_may_read`, `the_limit_counts_only_what_the_viewer_may_see`, `the_workspace_handoff_comes_only_from_readable_repositories`; `ai-memory-mcp` `server.rs` `a_reader_may_read_everything_and_change_nothing`, `bob_cannot_read_alices_page_in_a_restricted_project`, `bob_cannot_find_alices_page_by_searching_in_a_restricted_project`, `bob_cannot_consolidate_a_session_in_alices_repository`, `a_restricted_projects_queues_need_write`; `ai-memory-hooks` `a_capture_needs_writer_on_the_repository_it_lands_in`, `session_start_delivers_nothing_from_a_repository_the_viewer_cannot_read`, `run_and_workstream_ids_only_answer_someone_who_may_reach_the_repository`; `ai-memory-web` `web_reads_honour_grants_in_a_restricted_project`, `metadata_shows_only_what_the_viewer_may_read` — each with a granted or open-project control, and proven to fail with the choke point (18 tests) or the SQL filter (9 tests) neutralized | STRONG — slice 3 closed both bypass classes (unscoped reads, raw-id entry points) and added the root-only management surface. Out of scope by design: per-project administrators (granting/restricting is root-only), and access modes, creators and grants live only in SQLite, so `reindex` resets them || 14b | Repository identity routing (#708) | `ai-memory-store/src/ops.rs` `resolve_project_by_identity` — one transaction; an identity already on a project is never overwritten; an unclaimed project is claimed only when the capturing user may write it (the choke point's `resolve_project_authz` on the same transaction), otherwise it is returned unclaimed; a different identity under the same name splits into a new project with no shared `repo_path`; `ai-memory-hooks/src/router.rs` `cache_key_for` keys the path cache by identity too; `ai-memory-core/src/repository_identity.rs` strips credentials from remote URLs client-side, and the server accepts only the routing rungs (`explicit`, `git_remote`) from the wire | `tests/suite/identity_resolution.rs` `an_outsider_cannot_take_an_unclaimed_projects_identity` (control: `an_existing_project_is_claimed_in_place`), `two_unrelated_repositories_with_one_folder_name_stay_apart`, `a_created_or_split_project_admits_its_creator`; `router.rs` `one_path_with_two_remotes_is_two_projects`, `two_api_checkouts_with_different_remotes_get_two_projects` (a manifest rung on the wire is ignored); `repository_identity.rs` credential and normalisation tables — the claim guard and the cache key each proven to fail their test when removed | STRONG — first claimant wins: in a restricted workspace a user who creates a project under a remote identity first holds it until root grants others || 14c | Client-supplied event time is bounded and self-scoped (#919) | `ai-memory-hooks/src/payload.rs` `HookEnvelope::occurred_at_micros` — a `/hook` caller's optional `occurred_at` must be `> 0` and `<= now + 5min`; it only sets the caller's *own* admitted session's `started_at`/`ended_at`/`created_at`, never another session/project/user, and the ingest dedup `seen_at`/TTL stays on `now` | `payload.rs` `occurred_at_micros_rejects_a_far_future_timestamp`, `…_rejects_non_positive_values`, `…_rejects_garbage_strings` | MEDIUM — self-scoped numeric bound; no cross-tenant surface (a client already controls its own content) |