Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

fix(desktop): prevent npm writes from forcing Runtime repair (#3031)

Call White93b6ec404d83
diff --git a/desktop/README.md b/desktop/README.md
index 2a9e35aac..15625bd35 100644
--- a/desktop/README.md
+++ b/desktop/README.md
@@ -32,7 +32,10 @@ product logic.
Homebrew resolve exactly as they do in a terminal. The shell runs `$SHELL -l
-i -c` once per start, reads only `PATH`, and keeps its own `PATH` when that
shell fails or takes longer than 10 seconds. A private Runtime still puts its
- own `bin` and Node directories first. Discovery and the lifecycle verbs do
+ own `bin` directory first, but does not put bundled Node on the shared PATH:
+ external npm must use the user's Node, not derive a global install prefix
+ inside the immutable Runtime. Avibe-owned Node consumers use explicit private
+ toolchain paths. Discovery and the lifecycle verbs do
not consult the login shell, so adopting a running Runtime never waits on it.
The lookup runs on a blocking thread before the launch-state lock is taken, so
a concurrent Stop is not held for that budget. A successful lookup lets the
@@ -97,8 +100,12 @@ Agents inherit a PATH led by the Runtime's dedicated `bin` directory. It provide
`vibe` (`vibe.cmd` on Windows), which runs the bundled Python with `-I -B -m vibe`.
The entry point is generated when building the bundle, covered by its manifest,
and works after relocation, including installation paths containing spaces.
-The private Python directory is not added to PATH, so the user's `python3` and
-`pip` remain available. Build-machine Python console scripts are removed.
+The private Python and Node directories are not added to the shared PATH, so
+external tools keep the user's interpreter selection. Avibe's backend installer,
+Show Runtime, and computer-use helpers select bundled Node explicitly; the backend
+installer uses an isolated mutable prefix. This keeps an external npm global
+install from adding packages to the immutable Runtime and triggering a repair on
+the next launch. Build-machine Python console scripts are removed.
**Login-shell limitation:** a user profile that prepends a new global CLI
directory or replaces PATH can override the bundled `vibe`. Profiles that
diff --git a/desktop/runtime-host/src/launcher.rs b/desktop/runtime-host/src/launcher.rs
index 8ff2f2322..dee3342fb 100644
--- a/desktop/runtime-host/src/launcher.rs
+++ b/desktop/runtime-host/src/launcher.rs
@@ -603,9 +603,12 @@ impl RuntimeCommand {
backends_root: PathBuf,
runtime_id: &str,
) -> Self {
- let tools_dir = node.parent().expect("validated private Node has a parent").to_owned();
- // The builder includes a relocatable vibe entry point in bin. Expose
- // only that directory, never python/bin (which would shadow user tools).
+ // Only the relocatable vibe entry point belongs on the shared PATH.
+ // In particular, exposing bundled Node pairs an external npm shebang
+ // with our interpreter: npm's default global prefix then points inside
+ // this immutable tree, and a global install forces a startup repair.
+ // Private Node/npm consumers receive explicit handles below instead.
+ // Never expose python/bin either (it would shadow the user's tools).
let cli_dir = runtime_root.join("bin");
Self {
executable: python,
@@ -640,7 +643,7 @@ impl RuntimeCommand {
// what covers this process itself.
(OsString::from("PYTHONDONTWRITEBYTECODE"), OsString::from("1")),
],
- path_prefix: vec![cli_dir, tools_dir],
+ path_prefix: vec![cli_dir],
withholds_inherited_python: true,
}
}
@@ -2338,7 +2341,7 @@ mod tests {
}
#[test]
- fn private_runtime_commands_ignore_user_python_and_prepend_managed_tools() {
+ fn private_runtime_commands_isolate_python_and_expose_only_the_vibe_shim() {
let runtime_root = PathBuf::from("/private/runtime");
let python = PathBuf::from("/private/runtime/python/bin/python3");
let node = PathBuf::from("/private/runtime/tools/bin/node");
@@ -2358,14 +2361,7 @@ mod tests {
&"a".repeat(64),
);
let path_entries: Vec<_> = env::split_paths(&command.path(Some(&inherited)).expect("private PATH")).collect();
- assert_eq!(
- path_entries,
- [
- runtime_root.join("bin"),
- node.parent().unwrap().to_owned(),
- PathBuf::from("/usr/bin")
- ]
- );
+ assert_eq!(path_entries, [runtime_root.join("bin"), PathBuf::from("/usr/bin")]);
assert_eq!(command.executable, python);
assert_eq!(
@@ -2434,8 +2430,50 @@ mod tests {
std::fs::remove_dir_all(&dir).ok();
}
+ #[cfg(unix)]
+ #[test]
+ fn a_private_runtime_leaves_external_npm_on_the_users_node() {
+ use std::os::unix::fs::PermissionsExt;
+
+ let dir = scratch_dir("external-npm-node");
+ let tree = dir.join("Runtime With Spaces");
+ let tools = tree.join("tools/bin");
+ let external = dir.join("user-node/bin");
+ for path in [&tools, &external] {
+ std::fs::create_dir_all(path).expect("test-owned tool directory");
+ }
+ // The fixtures identify which interpreter /usr/bin/env selects. They
+ // do not simulate npm's prefix algorithm or run any package manager.
+ for (path, body) in [
+ (tools.join("node"), "#!/bin/sh\nprintf 'bundled-node'\n"),
+ (external.join("node"), "#!/bin/sh\nprintf 'user-node'\n"),
+ (external.join("npm"), "#!/usr/bin/env node\n"),
+ ] {
+ std::fs::write(&path, body).expect("test executable");
+ std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755)).expect("executable mode");
+ }
+ let python = write_fake_runtime(&tree, "#!/bin/sh\nexec npm\n");
+ let runtime = RuntimeCommand::private(
+ tree.clone(),
+ python,
+ tools.join("node"),
+ tree.join("tools/npm/bin/npm-cli.js"),
+ dir.join("backends"),
+ &"a".repeat(64),
+ );
+ let login_path = env::join_paths([&external]).expect("test-owned PATH");
+
+ let mut command = Command::new(&runtime.executable);
+ command.env_clear().env("HOME", &dir).current_dir(&dir);
+ runtime.apply(&mut command, Some(&login_path));
+ let output = command.output().expect("test Runtime launches external npm");
+ assert!(output.status.success(), "{:?}", output.stderr);
+ assert_eq!(String::from_utf8_lossy(&output.stdout), "user-node");
+ std::fs::remove_dir_all(dir).expect("remove test-owned tools");
+ }
+
#[test]
- fn a_private_runtime_keeps_its_own_tools_ahead_of_the_login_shell_path() {
+ fn a_private_runtime_keeps_only_its_vibe_shim_ahead_of_the_login_shell_path() {
let runtime = RuntimeCommand::private(
PathBuf::from("/private/runtime"),
PathBuf::from("/private/runtime/python/bin/python3"),
@@ -2457,7 +2495,6 @@ mod tests {
env::split_paths(path).collect::<Vec<_>>(),
[
PathBuf::from("/private/runtime/bin"),
- PathBuf::from("/private/runtime/tools/bin"),
PathBuf::from("/login/nvm/bin"),
PathBuf::from("/usr/bin"),
]
diff --git a/desktop/scripts/build-runtime-bundle.py b/desktop/scripts/build-runtime-bundle.py
index 4098027f3..969fd5de7 100755
--- a/desktop/scripts/build-runtime-bundle.py
+++ b/desktop/scripts/build-runtime-bundle.py
@@ -623,7 +623,6 @@ def private_probe_environment(probe_home: Path, node: Path, npm_cli: Path, paylo
part
for part in (
str(payload / CLI_BIN_DIR),
- str(node.parent),
inherited_path,
)
if part
diff --git a/docs/plans/desktop-startup-runtime-toolchain.md b/docs/plans/desktop-startup-runtime-toolchain.md
new file mode 100644
index 000000000..63acff56e
--- /dev/null
+++ b/docs/plans/desktop-startup-runtime-toolchain.md
@@ -0,0 +1,95 @@
+# Desktop startup: keep external npm out of the immutable Runtime
+
+## Background and goal
+
+Desktop's discovery phase includes Runtime preparation, not just a health probe.
+An unprefixed external `npm install --global` can run on the bundled Node because
+`RuntimeCommand::private` prepends its tools directory to every descendant's
+`PATH`. npm then derives its default global prefix from that Node installation,
+adds files to the immutable Runtime, and causes a later launch to extract a
+repair slot. A diagnostic npm log confirms this Node/npm combination and a
+successful global install; the exact initiating process is not established.
+
+Prevent this cross-toolchain pairing without changing endpoint/config discovery,
+Runtime integrity checks, repair-slot reuse, or a running service.
+
+## Change contract
+
+- Only the bundled `vibe` entry-point directory leads the Runtime-wide PATH.
+ External Node/npm retain the user's login-shell selection.
+- Avibe's own backend installer, Show Runtime, and computer-use Node consumers
+ retain their existing explicit bundled Node/npm handles. Backend installs keep
+ their explicit mutable staging prefix and isolated npm config/cache.
+- Do not inject global `PREFIX` or `NPM_CONFIG_PREFIX`, override user npm config,
+ create endpoint caches, or add another mutable toolchain installation.
+- No release, deployment, live service restart, active-slot deletion, or user
+ config modification is part of this source change.
+
+## Scope and consumers
+
+The owner is the Rust private Runtime launch environment; the bundle builder's
+probe environment mirrors that contract and must not hide a shared-PATH dependency.
+Python consumers already
+select private Node explicitly (`vibe.desktop_backends`, `core.show_runtime`,
+`core.computer_js_kernels`, and `vibe.computer_script_runner`). Published private
+backends are native executables, not npm JavaScript shims. Dedicated backend
+installation additionally prepends Node only in its isolated subprocess env.
+
+External tools that require Node must use their own Node installation, as they do
+in a terminal; the bundled toolchain is not a general-purpose user installation.
+Existing contaminated slots remain intact. The existing repair-slot mechanism
+handles them without deleting the Runtime a live service may still use.
+
+## Validation plan and test rationale
+
+- Extend the existing cross-platform launch-environment contract: retain the
+ private vibe shim and explicit Node/npm handles, but exclude bundled Node from
+ inherited PATH. Its pre-fix failure is the extra tools directory.
+- Extend the private login-PATH coverage with a Unix subprocess
+ regression: an external npm-shaped `#!/usr/bin/env node` launcher must select
+ the external Node fixture, not the bundled one. This tests actual shebang/PATH
+ resolution rather than simulating npm's prefix algorithm. Existing tests only
+ asserted the old, harmful PATH order.
+- Run a real offline npm write probe with copied (not symlinked) Node in scratch,
+ isolated HOME/config/cache and a local fixture package. Compare old/new PATH:
+ only the former should write beneath the scratch immutable Runtime. Never
+ install with production Node's implicit prefix.
+- Extend the existing bundle-probe environment test for its distinct packaging
+ risk: the release smoke probe must use the launcher's PATH contract, rather than
+ masking a consumer's accidental dependency on globally available bundled Node.
+ It failed before the builder correction because of the extra tools directory.
+- Run focused Rust launcher tests, runtime-host tests, fmt and clippy; run existing
+ Python private backend and explicit Node consumer tests with hermetic state.
+- Open a PR and require exact-head Codex review and applicable CI before delivery.
+
+## Progress
+
+- [x] Correlate Runtime contamination with npm command metadata.
+- [x] Withdraw speculative endpoint-cache prototype; net diff contains no cache.
+- [x] Inventory explicit private Node consumers.
+- [x] Implement the launch environment correction and regression coverage.
+- [x] Complete focused validation and offline npm write probe.
+- [ ] Complete review and CI.
+
+## Validation evidence
+
+- The new shebang regression failed before the fix with `bundled-node` instead of
+ `user-node`, and passes afterward. The bundle mirror assertion also failed on
+ its old extra PATH entry and passes with the corrected environment.
+- A real offline npm local-tarball install, with copied Node executables and every
+ config/cache/home path in scratch, wrote into `Runtime With Spaces/tools` with
+ the old PATH and only into `user-node` with the new PATH. The Runtime fingerprint
+ stayed unchanged after the corrected install. No real install was modified.
+- Rust formatting and runtime-host clippy (`-D warnings`) passed. The full
+ runtime-host suite passed with `--test-threads=1`: 184 unit tests, 87 integration
+ tests, and one doc test. A default-parallel run hit the unchanged login-path
+ subprocess-start timeout test; that test passed alone and in the serial suite.
+- Existing Python desktop backend/runtime tests passed (161 tests). A separate
+ run with a scratch-owned Node passed all 127 bundle-builder, computer JS kernel,
+ and computer script SDK tests. HOME, Avibe home, XDG state, and credentials were
+ isolated. Dependencies live in this worktree's own venv; its local source-path
+ entry supports the existing isolated-interpreter bundle test without building
+ or installing any UI onto the user's service.
+- Real installed Desktop reopening remains a post-build manual check. This patch
+ prevents repeated repair caused by this PATH leak; it does not remove the
+ expected initial extraction for a new Runtime version or claim instant startup.
diff --git a/tests/test_desktop_runtime_bundle_builder.py b/tests/test_desktop_runtime_bundle_builder.py
index 5bb3e681f..4ba70fcdb 100644
--- a/tests/test_desktop_runtime_bundle_builder.py
+++ b/tests/test_desktop_runtime_bundle_builder.py
@@ -100,6 +100,8 @@ def test_private_probe_environment_does_not_inherit_credentials(monkeypatch, tmp
monkeypatch.setenv("ANTHROPIC_AUTH_TOKEN", "must-not-cross-boundary")
monkeypatch.setenv("CODEX_HOME", "/real/codex-home")
monkeypatch.setenv("HOME", "/real/home")
+ user_bin = tmp_path / "user-bin"
+ monkeypatch.setenv("PATH", str(user_bin))
probe_home = tmp_path / "probe"
node = tmp_path / "payload" / "tools" / "bin" / "node"
@@ -111,7 +113,10 @@ def test_private_probe_environment_does_not_inherit_credentials(monkeypatch, tmp
assert "ANTHROPIC_AUTH_TOKEN" not in environment
assert environment["HOME"] == str(probe_home)
assert environment["CODEX_HOME"] == str(probe_home / "codex")
- assert environment["PATH"].split(builder.os.pathsep)[:2] == [str(payload / "bin"), str(node.parent)]
+ # Match the real Desktop launcher: only vibe is global; private Node/npm
+ # remain explicit so package probes cannot hide a shared-PATH dependency.
+ assert environment["PATH"].split(builder.os.pathsep) == [str(payload / "bin"), str(user_bin)]
+ assert environment["VIBE_SHOW_RUNTIME_NODE_BIN"] == str(node)
assert str(payload / "python" / "bin") not in environment["PATH"].split(builder.os.pathsep)
assert environment["ZDOTDIR"] == str(probe_home)
assert environment["AVIBE_DESKTOP_NPM_CLI"] == str(npm_cli)