Skip to content

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

Rust

feat(run): isolate jailed OpenCode servers

AkitaOnRails642939a45107
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 85ed1d80..ba1c1716 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -134,6 +134,14 @@ version in [`docs/changelog/`](docs/changelog/):
### Changed
+- Jailed OpenCode managed runs now add the native `--standalone` flag unless
+ the caller explicitly supplies `--standalone` or `--server`. The private
+ server keeps tool processes inside ai-jail's Linux PID namespace, so a
+ detached job cannot survive the jail. Current documentation presents
+ `opencode` as the single auto-detected integration; `opencode2`,
+ `opencode-v2`, and `open-code2` remain supported legacy force-V2 aliases for
+ existing scripts rather than a separately advertised beta harness.
+
- `move-project` now refuses the **copy+purge merge** — the path taken when the
destination workspace already holds a project of the same name — unless
`--allow-lossy-merge` is passed as well as `--confirm`. That path keeps only
diff --git a/README.md b/README.md
index 115ca43a..077196c8 100644
--- a/README.md
+++ b/README.md
@@ -136,8 +136,7 @@ caveats is in [`docs/support-matrix.md`](docs/support-matrix.md).
| Codex | Supported |
| Command Code | Supported |
| Devin CLI | Supported |
-| OpenCode (V1/V2 auto-detected) | Supported |
-| OpenCode V2 compatibility aliases (`opencode2`, `opencode-v2`, `open-code2`) | Supported |
+| OpenCode (V1/V2 auto-detected; legacy force-V2 aliases retained) | Supported |
| Cursor | Supported |
| Gemini CLI | Supported |
| Oh My Pi / OMP | Supported |
@@ -436,9 +435,10 @@ Wiring another agent is the same two commands with a different name:
matrix. OpenCode is version-detected by host-side commands; when generating its
artifacts inside a container, use `setup-agent --agent opencode
--opencode-dialect v1|v2 --to /tmp/unused` because the container cannot inspect
-the host executable. The `opencode2` aliases remain force-V2 compatibility
-spellings. The full per-agent guide, including Windows and remote servers, is
-[`docs/install.md`](docs/install.md).
+the host executable. The legacy `opencode2`, `opencode-v2`, and `open-code2`
+aliases remain force-V2 compatibility spellings for old scripts; use
+`opencode` for new commands. The full per-agent guide, including Windows and
+remote servers, is [`docs/install.md`](docs/install.md).
Two agents in the same project at once, or teammates on one server, work
out of the box: the "current project" pointer is isolated per caller
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rs
index caf7ed07..ca8ab996 100644
--- a/crates/ai-memory-cli/src/cli.rs
+++ b/crates/ai-memory-cli/src/cli.rs
@@ -4686,7 +4686,7 @@ mod tests {
}
#[test]
- fn opencode2_aliases_parse_to_the_beta_variants() {
+ fn opencode2_aliases_parse_to_the_v2_compatibility_variants() {
for alias in ["opencode2", "opencode-v2", "open-code2"] {
let cli = Cli::try_parse_from([
"ai-memory",
diff --git a/crates/ai-memory-cli/src/commands/install_hooks.rs b/crates/ai-memory-cli/src/commands/install_hooks.rs
index 496efd8a..0f831262 100644
--- a/crates/ai-memory-cli/src/commands/install_hooks.rs
+++ b/crates/ai-memory-cli/src/commands/install_hooks.rs
@@ -3989,7 +3989,7 @@ pub(crate) fn opencode2_plugin_path() -> anyhow::Result<std::path::PathBuf> {
.join("ai-memory-opencode2.ts"))
}
-/// Generate an OpenCode 2.0 beta plugin at
+/// Generate an OpenCode V2 plugin at
/// `~/.config/opencode/plugins/ai-memory-opencode2.ts`.
///
/// The V2 plugin API (`{ id, setup }` with `ctx.session.hook` /
@@ -4044,11 +4044,9 @@ fn render_opencode2_plugin(
capture_mode: &str,
capture_assistant: bool,
) -> Result<()> {
- println!(
- "// OpenCode 2.0 beta plugin — write to ~/.config/opencode/plugins/ai-memory-opencode2.ts"
- );
+ println!("// OpenCode V2 plugin — write to ~/.config/opencode/plugins/ai-memory-opencode2.ts");
println!("// Or re-run with `--apply` to install it automatically.");
- println!("// Restart OpenCode 2 after changing plugins; config is loaded at startup.");
+ println!("// Restart OpenCode V2 after changing plugins; config is loaded at startup.");
println!();
println!(
"{}",
diff --git a/crates/ai-memory-cli/src/commands/install_mcp.rs b/crates/ai-memory-cli/src/commands/install_mcp.rs
index 922e307c..b5e8449a 100644
--- a/crates/ai-memory-cli/src/commands/install_mcp.rs
+++ b/crates/ai-memory-cli/src/commands/install_mcp.rs
@@ -2000,10 +2000,10 @@ fn build_mcp_entry_cline(args: &InstallMcpArgs) -> Result<serde_json::Value> {
Ok(serde_json::Value::Object(entry))
}
-/// OpenCode 2.0 beta MCP entry: `type: "remote"` + `url` + optional
+/// OpenCode V2 MCP entry: `type: "remote"` + `url` + optional
/// `headers` under `mcp.servers`. V2 has no `enabled` field (servers
/// connect unless `disabled: true`), and header-credentialed servers
-/// must set `oauth: false` so the beta does not attempt OAuth discovery
+/// must set `oauth: false` so V2 does not attempt OAuth discovery
/// against ai-memory's local endpoint
/// (https://opencode.ai/v2/docs/mcp-servers).
fn build_mcp_entry_opencode2(args: &InstallMcpArgs) -> Result<serde_json::Value> {
@@ -2482,7 +2482,7 @@ fn render_opencode(args: &InstallMcpArgs) -> Result<String> {
fn render_opencode2(args: &InstallMcpArgs) -> Result<String> {
Ok(format!(
- "# OpenCode 2.0 beta (`opencode2`) — merge into\n\
+ "# OpenCode V2 (`opencode2` compatibility alias) — merge into\n\
# ~/.config/opencode/opencode.json(c) under \"mcp\" → \"servers\":\n\
#\n\
# V2 nests servers under `mcp.servers` (V1 used direct `mcp`)\n\
diff --git a/crates/ai-memory-cli/src/commands/run.rs b/crates/ai-memory-cli/src/commands/run.rs
index 312a080e..f5dea6d0 100644
--- a/crates/ai-memory-cli/src/commands/run.rs
+++ b/crates/ai-memory-cli/src/commands/run.rs
@@ -16,10 +16,10 @@ use ai_memory_workstream::{
AmbiguousNativeSession, ClaudeContinuation, ExportedTranscript, FORWARDED_ENV_NAMES,
JailChecklistItem, 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_lookup, claude_continued_session,
- claude_live_background_attach_id, claude_session_ran_in_background, clean_path,
- crush_global_config_path, discover_native_session, export_transcript,
+ allows_native_session_adoption, apply_claude_true_yolo, apply_jail_process_isolation,
+ apply_yolo, build_ai_jail_invocation, build_launch_plan, build_launch_plan_with_env_lookup,
+ claude_continued_session, claude_live_background_attach_id, claude_session_ran_in_background,
+ clean_path, crush_global_config_path, discover_native_session, export_transcript,
has_native_session_selector, inside_ai_jail_here, inspect_repository,
is_interactive_session_invocation, jail_checklist, jail_toggle, kiro_explicit_session_id,
kiro_harness_from_source_cursor, kiro_selects_non_default_engine, kiro_selects_v2_engine,
@@ -689,6 +689,11 @@ async fn run_once_with_wiring(
return Err(augment_connect_error(probe_error, &endpoint, &url)
.context("opening managed workstream; the agent was not started"));
}
+ if jailed && apply_jail_process_isolation(provisional_harness, &mut native_args) {
+ eprintln!(
+ "ai-memory: OpenCode is running --standalone so its server and tool processes stay inside ai-jail"
+ );
+ }
return run_degraded_offline(
config,
DegradedLaunch {
@@ -820,6 +825,11 @@ async fn run_once_with_wiring(
} else {
resolved_harness
};
+ if jailed && apply_jail_process_isolation(harness, &mut native_args) {
+ eprintln!(
+ "ai-memory: OpenCode is running --standalone so its server and tool processes stay inside ai-jail"
+ );
+ }
if automatic_harness
&& matches!(
harness,
diff --git a/crates/ai-memory-workstream/src/harness.rs b/crates/ai-memory-workstream/src/harness.rs
index f7c330be..78199bd5 100644
--- a/crates/ai-memory-workstream/src/harness.rs
+++ b/crates/ai-memory-workstream/src/harness.rs
@@ -131,9 +131,9 @@ pub enum ManagedHarness {
Codex,
/// OpenCode.
OpenCode,
- /// OpenCode 2.0 beta (`opencode2` binary, side-by-side with v1).
- /// Shares v1's config dir, session store, and agent kind; only the
- /// launched executable differs.
+ /// Legacy force-V2 compatibility spelling (`opencode2` executable).
+ /// Shares the generic OpenCode config dir, session store, and agent kind;
+ /// only the executable selection and skipped version probe differ.
OpenCode2,
/// Pi coding agent.
Pi,
@@ -645,6 +645,27 @@ pub fn apply_yolo(harness: ManagedHarness, args: &mut Vec<OsString>) {
}
}
+/// Keep OpenCode's server and tool processes inside an ai-jail lifecycle.
+///
+/// OpenCode V2 normally delegates to a shared per-user service. That service
+/// can outlive the jailed client and create tool processes outside the jail's
+/// PID namespace. A private `--standalone` server stays inside the namespace,
+/// so Linux tears down its remaining descendants when the jail exits. An
+/// explicit `--server` remains authoritative: it deliberately selects an
+/// external service and must not be silently overridden.
+///
+/// Returns whether `--standalone` was added.
+pub fn apply_jail_process_isolation(harness: ManagedHarness, args: &mut Vec<OsString>) -> bool {
+ if harness != ManagedHarness::OpenCode2
+ || launch_mode(harness, args) != LaunchMode::Session
+ || has_flag(args, &["--standalone", "--server"])
+ {
+ return false;
+ }
+ args.push(OsString::from("--standalone"));
+ true
+}
+
/// Opt-in Claude-only "true yolo": on top of [`apply_yolo`]'s
/// `--dangerously-skip-permissions`, force `bypassPermissions` through
/// `--settings`, whose CLI-flag precedence beats a `defaultMode` in the user's
@@ -822,10 +843,10 @@ fn launch_mode(harness: ManagedHarness, args: &[OsString]) -> LaunchMode {
"db",
]
.as_slice(),
- // Beta subcommands, verified on `opencode2 v0.0.0-beta-18999`
- // (`opencode2 --help`). `run` stays session-bearing (see
- // `noninteractive_invocation`); `mini` is the minimal interactive
- // UI and also stays session-bearing.
+ // V2 subcommands, originally verified on the side-by-side
+ // `opencode2 v0.0.0-beta-18999` binary and retained for the legacy
+ // force-V2 spelling. `run` stays session-bearing (see
+ // `noninteractive_invocation`); `mini` is the minimal interactive UI.
ManagedHarness::OpenCode2 => [
"upgrade", "acp", "api", "debug", "console", "auth", "mcp", "plugin", "models",
"stats", "export", "import", "service", "pair", "serve",
@@ -1726,8 +1747,8 @@ fn environment_session_dir_with(
match harness {
ManagedHarness::Claude => value("CLAUDE_CONFIG_DIR").map(|dir| dir.join("projects")),
ManagedHarness::Codex => value("CODEX_HOME").map(|dir| dir.join("sessions")),
- // The beta channel keeps v1's `opencode.db` filename (other channels
- // get `opencode-<channel>.db`), so both harnesses share one store.
+ // V2 keeps v1's `opencode.db` filename (other channels get
+ // `opencode-<channel>.db`), so both adapters share one store.
ManagedHarness::OpenCode | ManagedHarness::OpenCode2 => {
value("XDG_DATA_HOME").map(|dir| dir.join("opencode"))
}
@@ -2047,16 +2068,16 @@ mod tests {
Some(ManagedHarness::OpenCode2)
);
}
- let beta = ManagedHarness::OpenCode2;
+ let compatibility = ManagedHarness::OpenCode2;
// Same store, same kind, same flags — only the executable differs,
// so `run opencode2` resumes v1 sessions and vice versa.
- assert_eq!(beta.executable(), "opencode2");
- assert_eq!(beta.as_str(), "opencode2");
- assert_eq!(beta.agent_kind(), AgentKind::OpenCode);
+ assert_eq!(compatibility.executable(), "opencode2");
+ assert_eq!(compatibility.as_str(), "opencode2");
+ assert_eq!(compatibility.agent_kind(), AgentKind::OpenCode);
assert_eq!(ManagedHarness::OpenCode.agent_kind(), AgentKind::OpenCode);
let plan = build_launch_plan(
- beta,
+ compatibility,
None,
vec![OsString::from("run"), OsString::from("continue here")],
Some("shared-id"),
@@ -2069,29 +2090,38 @@ mod tests {
assert_eq!(plan.expected_session_id.as_deref(), Some("shared-id"));
let mut yolo = Vec::new();
- apply_yolo(beta, &mut yolo);
- apply_yolo(beta, &mut yolo);
+ apply_yolo(compatibility, &mut yolo);
+ apply_yolo(compatibility, &mut yolo);
assert_eq!(strings(&yolo), ["--auto"]);
assert!(allows_native_session_adoption(
- beta,
+ compatibility,
&[OsString::from("--auto")]
));
assert!(!allows_native_session_adoption(
- beta,
+ compatibility,
&[OsString::from("run"), OsString::from("continue here")]
));
for utility in ["service", "api", "auth"] {
- let plan =
- build_launch_plan(beta, None, vec![OsString::from(utility)], Some("shared-id"))
- .unwrap();
+ let plan = build_launch_plan(
+ compatibility,
+ None,
+ vec![OsString::from(utility)],
+ Some("shared-id"),
+ )
+ .unwrap();
assert_eq!(plan.mode, LaunchMode::Passthrough, "{utility}");
}
// `mini` is the interactive UI, not a utility: it stays
// session-bearing.
- let mini =
- build_launch_plan(beta, None, vec![OsString::from("mini")], Some("shared-id")).unwrap();
+ let mini = build_launch_plan(
+ compatibility,
+ None,
+ vec![OsString::from("mini")],
+ Some("shared-id"),
+ )
+ .unwrap();
assert_eq!(mini.mode, LaunchMode::Session);
}
@@ -2198,6 +2228,68 @@ mod tests {
}
}
+ #[test]
+ fn jailed_opencode_uses_a_private_server_by_default() {
+ let mut interactive = Vec::new();
+ assert!(apply_jail_process_isolation(
+ ManagedHarness::OpenCode2,
+ &mut interactive
+ ));
+ assert_eq!(strings(&interactive), ["--standalone"]);
+
+ let mut run = ["run", "inspect this checkout"]
+ .map(OsString::from)
+ .to_vec();
+ assert!(apply_jail_process_isolation(
+ ManagedHarness::OpenCode2,
+ &mut run
+ ));
+ assert_eq!(
+ strings(&run),
+ ["run", "inspect this checkout", "--standalone"]
+ );
+ }
+
+ #[test]
+ fn jailed_opencode_preserves_explicit_server_selection() {
+ for original in [
+ vec!["--standalone"],
+ vec!["--server", "http://127.0.0.1:4096"],
+ vec!["run", "--server=http://127.0.0.1:4096", "inspect"],
+ ] {
+ let mut args = original.iter().map(OsString::from).collect::<Vec<_>>();
+ assert!(!apply_jail_process_isolation(
+ ManagedHarness::OpenCode2,
+ &mut args
+ ));
+ assert_eq!(strings(&args), original);
+ }
+ }
+
+ #[test]
+ fn jail_process_isolation_ignores_utilities_and_other_harnesses() {
+ let mut service = ["service", "status"].map(OsString::from).to_vec();
+ assert!(!apply_jail_process_isolation(
+ ManagedHarness::OpenCode2,
+ &mut service
+ ));
+ assert_eq!(strings(&service), ["service", "status"]);
+
+ let mut codex = Vec::new();
+ assert!(!apply_jail_process_isolation(
+ ManagedHarness::Codex,
+ &mut codex
+ ));
+ assert!(codex.is_empty());
+
+ let mut opencode_v1 = Vec::new();
+ assert!(!apply_jail_process_isolation(
+ ManagedHarness::OpenCode,
+ &mut opencode_v1
+ ));
+ assert!(opencode_v1.is_empty());
+ }
+
#[test]
fn command_code_resumes_exactly_and_preserves_native_arguments() {
let fresh = build_launch_plan(
diff --git a/crates/ai-memory-workstream/src/lib.rs b/crates/ai-memory-workstream/src/lib.rs
index 8478d398..0cb80b2b 100644
--- a/crates/ai-memory-workstream/src/lib.rs
+++ b/crates/ai-memory-workstream/src/lib.rs
@@ -7,12 +7,12 @@ mod transcript;
pub use harness::{
LaunchMode, LaunchPlan, LaunchRoots, ManagedHarness, OpenCodeDialect, TranscriptCapability,
- allows_native_session_adoption, apply_claude_true_yolo, apply_yolo, build_launch_plan,
- build_launch_plan_with_env, build_launch_plan_with_env_lookup, clean_path, crush_data_dir,
- crush_global_config_path, env_dir_override, has_native_session_selector,
- is_interactive_session_invocation, kiro_explicit_session_id, kiro_selects_non_default_engine,
- kiro_selects_v2_engine, kiro_selects_v3_engine, omp_agent_dir, omp_profile_flag,
- omp_profile_flag_env, store_override_vars,
+ allows_native_session_adoption, apply_claude_true_yolo, apply_jail_process_isolation,
+ apply_yolo, build_launch_plan, build_launch_plan_with_env, build_launch_plan_with_env_lookup,
+ clean_path, crush_data_dir, crush_global_config_path, env_dir_override,
+ has_native_session_selector, is_interactive_session_invocation, kiro_explicit_session_id,
+ kiro_selects_non_default_engine, kiro_selects_v2_engine, kiro_selects_v3_engine, omp_agent_dir,
+ omp_profile_flag, omp_profile_flag_env, store_override_vars,
};
pub use jail::{
FORWARDED_ENV_NAMES, JAIL_TOGGLES, JailChecklistItem, JailEnv, JailHostFacts, JailOs,
diff --git a/crates/ai-memory-workstream/src/transcript.rs b/crates/ai-memory-workstream/src/transcript.rs
index bf815b38..b21b40ae 100644
--- a/crates/ai-memory-workstream/src/transcript.rs
+++ b/crates/ai-memory-workstream/src/transcript.rs
@@ -5386,11 +5386,11 @@ fn opencode_directories(cwd: &Path) -> (String, String) {
(native, forward)
}
-/// OpenCode 2.0 beta transcript adapter.
+/// OpenCode V2 transcript adapter.
///
-/// The beta keeps v1's database file but replaced its tables: `session_v2`
+/// V2 keeps v1's database file but replaced its tables: `session_v2`
/// carries sessions, `session_message` carries typed messages. Shapes below
-/// were verified against beta-18999: user `{text, files}`, assistant
+/// were originally verified against beta-18999: user `{text, files}`, assistant
/// `content[]` with `text` / `tool` / `reasoning` parts. Reasoning content
/// is encrypted and excluded like v1's hidden reasoning; anything else
/// unrecognized becomes a bounded loss, never a guess — the beta schema is
diff --git a/docs/install.md b/docs/install.md
index 4fc72ad2..f76fe4da 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -2227,10 +2227,10 @@ and launch share the same captured environment plus `--env` / `--env-file`
overrides. Malformed output, a timeout, or an unsupported future major fails with
an actionable error instead of guessing.
-### OpenCode 2 (beta)
+### OpenCode V2 compatibility
The generated plugin targets the OpenCode 2.0.10+ event API (checked against
-2.0.14). OpenCode 2 runs one long-lived service behind every CLI, so closing a
+2.0.14). OpenCode V2 runs one long-lived service behind every CLI, so closing a
terminal is not a session end: each completed root turn instead writes a
deterministic checkpoint (no LLM call) of `sessions/<id>.md` and refreshes the
session's automatic handoff, keeping one open baton per live session. The next
@@ -2255,9 +2255,10 @@ For a commented `opencode.jsonc`, preview `install-mcp --client opencode2` and
merge the entry into the existing `mcp.servers` object by hand: the apply path
writes strict JSON.
-The `opencode2`, `opencode-v2`, and `open-code2` spellings remain compatibility
-aliases that force the V2 contracts without probing. They share V1's config dir
-and session store. Prefer the generic `opencode` spelling for normal installs:
+The `opencode2`, `opencode-v2`, and `open-code2` spellings are legacy
+compatibility aliases that force the V2 contracts without probing. They share
+the generic OpenCode config directory and session store and are not a separate
+harness. Prefer the generic `opencode` spelling for normal installs:
```bash
# Host-side generic commands auto-detect V2; compatibility aliases force it.
@@ -2282,19 +2283,13 @@ preserved. Repeating either install is
byte-idempotent, and `uninstall` continues to recognize both historical files
and MCP locations.
-> **Back up `~/.local/share/opencode` before running the beta against
-> your real data.** The two binaries share the one `opencode.db` file and
-> the beta has migrated its schema in place before, leaving stable
-> `opencode` 1.x broken
-> ([upstream #42260](https://github.com/anomalyco/opencode/issues/42260)).
-> ai-memory only ever opens that database read-only; the migration risk
-> comes from launching `opencode2` itself, not from this integration.
->
-> **The beta's background service defaults to port 49374, which is also ai-memory's
-> default.** Running both on defaults crash-loops the opencode2 service
+> **OpenCode V2's shared background service defaults to port 49374, which is
+> also ai-memory's default.** Running both on defaults prevents the OpenCode service
> (`Managed service port 49374 ... is already in use`). Move one side:
-> `opencode2 service set port <free-port>`, or start ai-memory with
+> `opencode service set port <free-port>`, or start ai-memory with
> `--bind 127.0.0.1:<free-port>` (and matching `--server-url` installs).
+> `ai-memory run --jail opencode` avoids the shared-service collision by using
+> OpenCode's private `--standalone` server inside the jail.
**On a Gemini/Vertex model, serve Gemini-safe schemas.** OpenCode forwards MCP
tool schemas to the configured provider verbatim, and Google's `Schema`
diff --git a/docs/managed-harness-contributions.md b/docs/managed-harness-contributions.md
index 0d30f546..5c89c75c 100644
--- a/docs/managed-harness-contributions.md
+++ b/docs/managed-harness-contributions.md
@@ -1,7 +1,7 @@
# Adding a managed harness
Managed-workstream support is narrower than MCP or lifecycle-hook support. This
-release can manage Claude Code, Codex, OpenCode, OpenCode 2 beta, Pi, Crush, Kimi Code, Command
+release can manage Claude Code, Codex, OpenCode, Pi, Crush, Kimi Code, Command
Code, Kiro CLI v2/v3, OMP, Grok Build CLI, Antigravity CLI, and GitHub Copilot CLI. IBM Bob,
Gemini CLI, Devin CLI, Cursor, and the other integrations in the README support
matrix do not become managed merely because ai-memory can capture their hooks.
diff --git a/docs/managed-workstreams.md b/docs/managed-workstreams.md
index e3d3326c..49b2fdc3 100644
--- a/docs/managed-workstreams.md
+++ b/docs/managed-workstreams.md
@@ -1,12 +1,19 @@
# Managed cross-harness workstreams
`ai-memory run` is an opt-in launcher that lets one logical coding session move
-between Claude Code, Codex, OpenCode, OpenCode 2 beta, Pi, Crush, Kimi Code, Command Code, Kiro
+between Claude Code, Codex, OpenCode, Pi, Crush, Kimi Code, Command Code, Kiro
CLI v2/v3, OMP, Grok Build CLI, Antigravity CLI, and GitHub Copilot CLI. Direct agent launches
keep their existing ai-memory behavior. There is no global mode toggle and no
`switch` command: using `run` selects the current workstream and transparently
creates or resumes the correct native session for the requested harness.
+On Linux, a jailed OpenCode session uses a private `--standalone` server by
+default. This keeps its server and tool processes inside ai-jail's PID
+namespace so they cannot survive the jail. An explicit native `--server`
+still wins because it deliberately selects an external service. The legacy
+`opencode2`, `opencode-v2`, and `open-code2` names force the V2 adapter for old
+scripts; they are compatibility aliases, not a second OpenCode harness.
+
When the server runs with `--enable-web`, root can inspect all managed ledgers
at `/web/workstreams`. The read-only page shows trusted lifecycle state, the
latest harness/run, current harness links, event counts, and activity times. It
@@ -421,15 +428,15 @@ flavor remains exact. OMP, Grok, Antigravity, and Copilot remain available expli
but are not in the automatic pool. OpenCode's resolved major contributes one
adapter to the pool, so shared V1/V2 storage never duplicates a candidate.
-OpenCode 2 sessions run inside a shared background service, so its plugin
-cannot see a managed run's environment the way in-process plugins do. Managed
-`run opencode2` legs launch with the correct resume selectors, capture through
-hooks, and import the beta transcript (all verified live), but the
+Non-jailed OpenCode V2 sessions normally run inside a shared background service,
+so its plugin cannot see a managed run's environment the way in-process plugins
+do. Managed OpenCode V2 legs launch with the correct resume selectors, capture
+through hooks, and import the V2 transcript (all verified live), but the
ledger-delta acknowledgement (`context_delivered`) does not fire, because the
accept path requires the run id on the session-start hook. When this fails the
range is redelivered, never lost: a later leg into another harness may receive the range
-again. Until the beta offers per-invocation plugin context, cross-harness
-continuity into opencode2 arrives through the ordinary handoff loop rather
+again. Until the shared service offers per-invocation plugin context, cross-harness
+continuity into OpenCode V2 arrives through the ordinary handoff loop rather
than the ledger delta.
Bare mode accepts wrapper options but not harness-native arguments or
diff --git a/docs/mcp-install.md b/docs/mcp-install.md
index 5ca251cc..3b69fa10 100644
--- a/docs/mcp-install.md
+++ b/docs/mcp-install.md
@@ -1988,11 +1988,11 @@ that *starts* the next one - to play nicely with ai-memory:
| Side | What's needed | Covered by |
|---|---|---|
-| **Ending side** | The agent must create a handoff through a true session-end hook, the manual finalizer, or `memory_handoff_begin`. | Built-in automatically for Claude Code, Codex (native `SessionEnd`, Codex CLI 0.145.0+), Devin CLI, Cursor, Gemini CLI, Grok Build CLI, Zero, Kimi Code, OpenClaw, OpenCode, OpenCode 2 beta, and OMP. Antigravity CLI, both Kiro CLI engines, and Command Code have no reliable true session-end event; run `ai-memory finalize-session` with the corresponding `--agent` after the final turn (also the fallback on Codex older than 0.145.0). MCP-only clients such as Swival must call `memory_handoff_begin` explicitly. |
-| **Starting side** | Either (a) the session-start/plugin path injects the handoff via `/handoff`, OR (b) the model inspects with `memory_handoff_list` then claims with `memory_handoff_accept` (`handoff_id` from the list). | (a) is built-in for Claude Code / Codex / Devin CLI / Cursor / Gemini CLI / Antigravity CLI / Kimi Code / Grok Build CLI / both Kiro CLI engines / Command Code / OpenClaw / OpenCode / OpenCode 2 beta / OMP. Grok's (a) is the first `PostToolUse` `additionalContext`, not SessionStart; `install-hooks --agent grok --apply` also installs a first-turn `memory_handoff_list` user rule so that tool exists. Zero discards SessionStart stdout; Swival is MCP-only. Use (b) for those. (b) works for any MCP-capable client if you nudge the model - see [the managed routing package](usage.md#install-the-routing-snippet-and-agent-skills). |
+| **Ending side** | The agent must create a handoff through a true session-end hook, the manual finalizer, or `memory_handoff_begin`. | Built-in automatically for Claude Code, Codex (native `SessionEnd`, Codex CLI 0.145.0+), Devin CLI, Cursor, Gemini CLI, Grok Build CLI, Zero, Kimi Code, OpenClaw, OpenCode, and OMP. Antigravity CLI, both Kiro CLI engines, and Command Code have no reliable true session-end event; run `ai-memory finalize-session` with the corresponding `--agent` after the final turn (also the fallback on Codex older than 0.145.0). MCP-only clients such as Swival must call `memory_handoff_begin` explicitly. |
+| **Starting side** | Either (a) the session-start/plugin path injects the handoff via `/handoff`, OR (b) the model inspects with `memory_handoff_list` then claims with `memory_handoff_accept` (`handoff_id` from the list). | (a) is built-in for Claude Code / Codex / Devin CLI / Cursor / Gemini CLI / Antigravity CLI / Kimi Code / Grok Build CLI / both Kiro CLI engines / Command Code / OpenClaw / OpenCode / OMP. Grok's (a) is the first `PostToolUse` `additionalContext`, not SessionStart; `install-hooks --agent grok --apply` also installs a first-turn `memory_handoff_list` user rule so that tool exists. Zero discards SessionStart stdout; Swival is MCP-only. Use (b) for those. (b) works for any MCP-capable client if you nudge the model - see [the managed routing package](usage.md#install-the-routing-snippet-and-agent-skills). |
OpenCode uses its official `session.deleted` plugin event for true session-end
-delivery. The OpenCode 2 beta plugin subscribes to the same event name on the
+delivery. The OpenCode V2 plugin subscribes to the same event name on the
V2 event stream and injects handoffs through the `context` hook instead of
v1's removed `experimental.chat.system.transform`. Its generated plugin also sends a deduped best-effort close for any
still-active sessions from `dispose` during normal plugin teardown; abrupt
diff --git a/docs/support-matrix.md b/docs/support-matrix.md
index 0843d09f..4c938b40 100644
--- a/docs/support-matrix.md
+++ b/docs/support-matrix.md
@@ -20,14 +20,13 @@
| Codex | Supported | MCP config + lifecycle hooks; native commands enforce capture exclusions. The same hooks, MCP tools and skills also ship as a marketplace plugin (ai-memory 3.0 or later; see [`install.md`](install.md#marketplace-plugins)). `SessionEnd` is wired since Codex CLI 0.145.0 (openai/codex#33895), so finished sessions get an automatic end-of-session summary/handoff; on older Codex the event is inert and `ai-memory finalize-session --agent codex` is the fallback. Managed runs (`ai-memory run codex`) recover when Codex's shared daemon reports a stale run id, provided exactly one live run matches the authorized project, checkout, and operator; ambiguous matches fail closed. `--no-daemon` remains available as an isolation and diagnostic option (see [`docs/managed-workstreams.md`](managed-workstreams.md)). Optionally captures the assistant's final turn on `Stop` when installed with `--capture-assistant` and the server enables `capture_assistant` (double opt-in, off by default) — Codex's `Stop` payload carries `last_assistant_message`, same as Claude Code. A prompt starting with `reload context` receives a compaction recap as `UserPromptSubmit` developer context, capped at 6,000 chars (see [`usage.md`](usage.md#reload-context-after-a-compaction)). |
| Command Code | Supported | MCP config (`~/.commandcode/mcp.json`) + its four stable lifecycle-hook events (`~/.commandcode/settings.json`); native commands enforce capture exclusions and `SessionStart` injects handoffs. `Stop` is only a turn boundary, so use `ai-memory finalize-session --agent command-code` after the final turn; an interactive session launched with `ai-memory run command-code` is finalized automatically when it exits if the run can tie the session to itself (see [`docs/managed-workstreams.md`](managed-workstreams.md)). `ai-memory run command-code` adds exact v3 native-session resume and visible-event import; experimental unsandboxed Mods remain excluded. |
| Devin CLI | Supported | MCP config + lifecycle hooks. Hooks use Devin's `PostCompaction` event, inject handoffs via `hookSpecificOutput.additionalContext`, and omit subagent events because Devin does not expose them. |
-| OpenCode (V1/V2 auto-detected) | Supported | Host-side generic `opencode` commands probe the exact executable and select the V1 direct MCP/function-plugin/transcript contracts or V2 nested `mcp.servers`/`{ id, setup }` plugin/`session_v2` contracts. The result is reused through managed discovery, launch, auto-wire, and transcript import; an automatic run skips OpenCode when probing fails but continues other harness discovery. Container-oriented `setup-agent` requires `--opencode-dialect v1|v2`. Generated sibling plugins and alternate MCP entries are migrated only when ai-memory ownership is proven. A prompt starting with `reload context` receives a compaction recap through the plugin's system/context hook until the next compaction (see [`usage.md`](usage.md#reload-context-after-a-compaction)). |
-| OpenCode V2 compatibility aliases | Supported | `opencode2`, `opencode-v2`, and `open-code2` force V2 compatibility without probing. V2 completed root turns checkpoint the session page and baton without ending the shared service's session; MCP calls route by the native `_meta` session id, and `--capture-assistant` is supported (double opt-in). |
+| OpenCode (V1/V2 auto-detected) | Supported | Host-side generic `opencode` commands probe the exact executable and select the V1 direct MCP/function-plugin/transcript contracts or V2 nested `mcp.servers`/`{ id, setup }` plugin/`session_v2` contracts. The result is reused through managed discovery, launch, auto-wire, and transcript import; an automatic run skips OpenCode when probing fails but continues other harness discovery. Container-oriented `setup-agent` requires `--opencode-dialect v1|v2`. The legacy `opencode2`, `opencode-v2`, and `open-code2` spellings remain force-V2 aliases for old scripts, not separate harnesses. Generated sibling plugins and alternate MCP entries are migrated only when ai-memory ownership is proven. V2 root turns checkpoint the session page and baton without ending the shared service's session; MCP calls route by the native `_meta` session id, and `--capture-assistant` is supported (double opt-in). A prompt starting with `reload context` receives a compaction recap through the plugin's system/context hook until the next compaction (see [`usage.md`](usage.md#reload-context-after-a-compaction)). Under `ai-memory run --jail`, OpenCode defaults to a private `--standalone` server so its tool processes remain in the jail; an explicit `--server` remains authoritative. |
| Cursor | Supported | MCP config + lifecycle hooks. |
| Gemini CLI | Supported | MCP config + lifecycle hooks. |
| Oh My Pi / OMP | Supported | Use `--client omp` / `--agent omp` (or `oh-my-pi`) for native `.omp` MCP config + TypeScript extension; generated extension enforces capture exclusions. |
| Pi | Supported | Generated `~/.pi/agent/extensions/ai-memory-pi.ts` extension provides lifecycle capture and an HTTP MCP bridge; generated extension enforces capture exclusions. |
| Crush | Managed-only | `ai-memory run crush` resumes its project-local session database and supplies portable context through a temporary supported global-context file; no lifecycle-hook installer is provided. |
-| Managed workstreams | Opt-in | `ai-memory run` provides transparent cross-harness continuity for Claude Code, Codex, OpenCode, OpenCode 2 beta, Pi, Crush, Kimi Code, Command Code, both incompatible Kiro CLI engines, OMP, Grok Build CLI, Antigravity CLI, and GitHub Copilot CLI. Direct launches remain unchanged. See [`docs/managed-workstreams.md`](managed-workstreams.md). |
+| Managed workstreams | Opt-in | `ai-memory run` provides transparent cross-harness continuity for Claude Code, Codex, OpenCode, Pi, Crush, Kimi Code, Command Code, both incompatible Kiro CLI engines, OMP, Grok Build CLI, Antigravity CLI, and GitHub Copilot CLI. Direct launches remain unchanged. See [`docs/managed-workstreams.md`](managed-workstreams.md). |
| `--yolo` safety + ai-jail | Linux/macOS; Windows partial | `ai-memory run --yolo` warns before it disarms an agent's permission prompts and, on Linux/macOS, offers to re-exec the session inside [ai-jail](https://github.com/akitaonrails/ai-jail) when it is usable — installed and with its sandbox backend present (`bwrap` / `sandbox-exec`); otherwise it asks nothing and proceeds (`--network`, forwarding only already-set credential/config env vars). Accepting the offer shows a checklist of ai-jail toggles pre-marked with smart defaults (credentials present on the host, SSH for an SSH `origin`, worktree metadata in a linked worktree; Docker socket, GPU, display, Pictures, Tailscale unchecked). `--jail` re-runs inside ai-jail without asking (also without `--yolo` and non-interactively; it errors when ai-jail is not usable), `--jail=github,aws,no-mise` is exact (every unnamed checklist row is forced off with `--no-X`; `all`/`none` too; the checklist likewise passes unchecked rows as `--no-X`, while bare `--jail` leaves unmarked rows to your ai-jail config), and `--no-jail` skips the offer. Only toggles the installed ai-jail supports are offered; the credential mounts (`github`, `aws`, `kube`, `gcloud`, `docker-config`) need ai-jail 2.5.0. A project `.ai-jail` in the launch directory replaces the checklist and the bare-`--jail` defaults (ai-jail loads it as-is; `--jail=…` still overrides), and every re-exec passes `--no-save-config` so ai-jail never writes the run's flags into it. Both prompts are skipped on a non-interactive stdin/stderr and when already detected inside ai-jail. Windows gets the warning but never the ai-jail offer (ai-jail is Linux/macOS-only). Opt-in `--true-yolo` implies `--yolo` and, for Claude only, additionally forces `bypassPermissions` over any settings `defaultMode` (interchangeable with `--yolo` for other harnesses); `claude_true_yolo` applies the same Claude extra to `--yolo` launches. Claude's own explicit `ask` rules and command-safety checks still prompt in every mode. See [`docs/design-yolo-safety-ai-jail.md`](design-yolo-safety-ai-jail.md). |
| Claude Desktop (Chat) | MCP-only | Uses `mcp-remote`; the ordinary Chat surface does not run lifecycle hooks. macOS, Windows, and Linux (Anthropic's Debian/Ubuntu beta, `~/.config/Claude/claude_desktop_config.json`). Cowork capture is not claimed; see the explicit boundary in [`mcp-install.md`](mcp-install.md#claude-desktop). |
| Claude Desktop (Code tab) | Supported | Local Code-tab sessions run Claude Code with the user's `~/.claude/settings.json`, so the Claude Code hooks capture them as `claude-code`; a session without a project folder lands in its own scratch-directory project. |
diff --git a/docs/usage.md b/docs/usage.md
index a0de1c9e..85c0dc81 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -811,7 +811,7 @@ above it and never overrides them:
1. The user's current instructions in the conversation.
2. The repository's rules file: `CLAUDE.md` for Claude Code; for Codex, Devin
- CLI, OpenCode, OpenCode 2 beta, Cursor, Gemini CLI, Grok Build CLI, Kimi
+ CLI, OpenCode, Cursor, Gemini CLI, Grok Build CLI, Kimi
Code, Kiro CLI, and Command Code it is usually `AGENTS.md`.
3. The project's memory: its pages, `_rules/`, decisions and gotchas.
4. The cross-project profile: the user's usual choices from other projects
diff --git a/docs/use-cases.md b/docs/use-cases.md
index af57341d..45f233d6 100644
--- a/docs/use-cases.md
+++ b/docs/use-cases.md
@@ -91,7 +91,7 @@
the workstream immediately. If a linked native transcript was deleted,
ai-memory detects the orphan before launch and starts fresh; `--fresh` forces
that recovery for one harness. Managed mode currently covers Claude Code,
- Codex, OpenCode, OpenCode 2 beta, Pi, Crush, Kimi Code, Command Code, Kiro CLI v2/v3, OMP,
+ Codex, OpenCode, Pi, Crush, Kimi Code, Command Code, Kiro CLI v2/v3, OMP,
Grok Build CLI, Antigravity CLI, and GitHub Copilot CLI; direct harness launches remain unchanged. See
[Managed cross-harness workstreams](managed-workstreams.md).
- **"Just put me back where I was."** From any directory, with no name to