verifiers 0.3.2.dev45__tar.gz → 0.3.2.dev47__tar.gz

{verifiers-0.3.2.dev45 → verifiers-0.3.2.dev47}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: verifiers
-Version: 0.3.2.dev45
+Version: 0.3.2.dev47
 Summary: Verifiers: Environments for LLM Reinforcement Learning
 Project-URL: Homepage, https://github.com/primeintellect-ai/verifiers
 Project-URL: Documentation, https://github.com/primeintellect-ai/verifiers

{verifiers-0.3.2.dev45 → verifiers-0.3.2.dev47}/tests/v1/test_scoring.py

@@ -89,6 +89,19 @@ async def test_config_plugged_fns_merge_and_override(tmp_path) -> None:
         HookTask(HookData(idx=0, prompt="abc"), config).hooks("reward")
 
 
+async def test_defer_scoring_defers_only_task_scoring() -> None:
+    task = HookTask(HookData(idx=0, prompt="abc"))
+    trace = vf.Trace(
+        agent=vf.AgentInfo(config=vf.AgentConfig()),
+        task=vf.TraceTask(type="HookTask", data=task.data),
+    )
+
+    await task.defer_scoring().score(trace)
+    assert trace.rewards == {}
+    await task.score(trace)
+    assert set(trace.rewards) == {"fmt", "lcs"}
+
+
 def test_compare_stdout_results_accepts_token_equal_text() -> None:
     assert vf.compare_stdout_results("hello   world\n", "hello world\n")
 

{verifiers-0.3.2.dev45 → verifiers-0.3.2.dev47}/verifiers/v1/agent.py

@@ -11,7 +11,7 @@ import asyncio
 import logging
 from collections.abc import AsyncIterator, Callable, Mapping
 from contextlib import asynccontextmanager, nullcontext
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from typing import Self
 
 from verifiers.v1.clients import (
@@ -54,6 +54,27 @@ __all__ = ["Agent", "AgentConfig", "Agents", "TimeoutConfig", "make_agent"]
 logger = logging.getLogger(__name__)
 
 
+def resolve_rollout_timeouts(timeout: TimeoutConfig, task: Task) -> RolloutTimeouts:
+    """Apply an agent's stage-timeout precedence to one task."""
+    agent_timeout = (
+        timeout.rollout if timeout.rollout is not None else task.data.timeout.agent
+    )
+    return RolloutTimeouts(
+        setup=timeout.setup if timeout.setup is not None else task.data.timeout.setup,
+        agent=agent_timeout,
+        finalize=(
+            timeout.finalize
+            if timeout.finalize is not None
+            else task.data.timeout.finalize
+        ),
+        scoring=(
+            timeout.scoring
+            if timeout.scoring is not None
+            else task.data.timeout.scoring
+        ),
+    )
+
+
 def _check_borrowed_placement(
     task: Task, runtime: Runtime, base_config: RuntimeConfig
 ) -> None:
@@ -526,34 +547,15 @@ class Agent:
             runtime_config,
             tools=[*task.toolsets(task.config), *shared_tools.values()],
         )
-        # Timeout precedence: agent-level wins, else the task's, else no limit.
-        agent_timeout = (
-            self.timeout.rollout
-            if self.timeout.rollout is not None
-            else task.data.timeout.agent
-        )
+        timeouts = resolve_rollout_timeouts(self.timeout, task)
         return {
             "agent_config": self.config,
             "harness": self.harness,
             "ctx": self.ctx,
             "runtime_config": runtime_config,
-            "timeouts": RolloutTimeouts(
-                setup=(
-                    self.timeout.setup
-                    if self.timeout.setup is not None
-                    else task.data.timeout.setup
-                ),
-                agent=cap_remote_agent_timeout(agent_timeout, runtime_config, task),
-                finalize=(
-                    self.timeout.finalize
-                    if self.timeout.finalize is not None
-                    else task.data.timeout.finalize
-                ),
-                scoring=(
-                    self.timeout.scoring
-                    if self.timeout.scoring is not None
-                    else task.data.timeout.scoring
-                ),
+            "timeouts": replace(
+                timeouts,
+                agent=cap_remote_agent_timeout(timeouts.agent, runtime_config, task),
             ),
             "limits": self.limits,
             "shared_tools": shared_tools,

{verifiers-0.3.2.dev45 → verifiers-0.3.2.dev47}/verifiers/v1/configs/harness.py

@@ -4,12 +4,16 @@ from __future__ import annotations
 
 import os
 from pathlib import Path
+from typing import Annotated
 
 from pydantic import ConfigDict, Field, FiniteFloat
 from pydantic_config import BaseConfig
 
 from verifiers.v1.types import ID
 
+PinnedVersion = Annotated[str, Field(pattern=r"^[A-Za-z0-9._+-]+$")]
+"""A release/tag a harness pins its program install to."""
+
 
 class HarnessConfig(BaseConfig):
     id: ID = "bash"

verifiers-0.3.2.dev47/verifiers/v1/envs/isolated_verifier/__init__.py

@@ -0,0 +1,7 @@
+from verifiers.v1.envs.isolated_verifier.env import (
+    IsolatedVerifierEnv,
+    IsolatedVerifierEnvConfig,
+    VerifierConfig,
+)
+
+__all__ = ["IsolatedVerifierEnv", "IsolatedVerifierEnvConfig", "VerifierConfig"]

verifiers-0.3.2.dev47/verifiers/v1/envs/isolated_verifier/env.py

@@ -0,0 +1,182 @@
+"""Deterministic task verification in a fresh runtime.
+
+One solver agent runs the task. Its task scoring is deferred, declared artifacts
+are collected after normal task finalization, and the solver runtime is destroyed.
+The task is then set up with a fresh controller in a fresh runtime, its artifacts
+are restored, and its ordinary metrics and rewards run there onto the solver's trace.
+"""
+
+import asyncio
+import copy
+import logging
+from contextlib import AsyncExitStack
+from pathlib import PurePosixPath
+from typing import Any
+
+from pydantic import Field, SerializationInfo, field_serializer
+
+import verifiers.v1 as vf
+from verifiers.v1.agent import resolve_rollout_timeouts
+from verifiers.v1.errors import TaskError, boundary
+from verifiers.v1.runtimes import Runtime, RuntimeConfig, provision_runtime
+from verifiers.v1.utils.compile import resolve_runtime_config
+from verifiers.v1.utils.decorators import invoke
+from verifiers.v1.utils.retries import backoff
+
+logger = logging.getLogger(__name__)
+
+
+class VerifierConfig(vf.BaseConfig):
+    runtime: RuntimeConfig | None = None
+    """Independent verifier placement and policy. None provisions a fresh runtime
+    equivalent to the solver's resolved task runtime."""
+    env: dict[str, str] | None = None
+    """Process environment for verifier setup and scoring. None uses the task's
+    normal runtime environment."""
+    retries: int = Field(2, ge=0)
+    """Extra fresh-runtime attempts after setup, restoration, staging, or scoring
+    failures."""
+
+    @field_serializer("runtime")
+    def serialize_runtime(
+        self, runtime: RuntimeConfig | None, info: SerializationInfo
+    ) -> dict | None:
+        """Keep an omitted image omitted across a resolved-config round trip."""
+        if runtime is None:
+            return None
+        values = runtime.model_dump(mode=info.mode)
+        if "image" not in runtime.model_fields_set:
+            values.pop("image", None)
+        return values
+
+
+class IsolatedVerifierEnvConfig(vf.EnvConfig):
+    agent: vf.AgentConfig = vf.AgentConfig()
+    """The one solver seat."""
+    verifier: VerifierConfig = VerifierConfig()
+    """The fresh verifier's runtime, process environment, and retry policy."""
+
+
+class IsolatedVerifierEnv(vf.Env[IsolatedVerifierEnvConfig]):
+    """Run one solver, then its deterministic task scoring in a fresh runtime."""
+
+    async def run(self, task: vf.Task, agents: vf.Agents) -> None:
+        if task.config.judges:
+            raise ValueError(
+                "isolated-verifier runs deterministic task metrics and rewards; "
+                "model-backed task judges are not supported"
+            )
+        self.verifier_config(task)  # Refuse an impossible verifier before solving.
+        await agents.agent.run(task.defer_scoring(), collect_artifacts=True)
+
+    def verifier_config(self, task: vf.Task) -> RuntimeConfig:
+        base = self.config.verifier.runtime or self.config.agent.runtime
+        config = resolve_runtime_config(base, task)
+        image_spec = type(base).model_fields.get("image")
+        if (
+            self.config.verifier.runtime is not None
+            and image_spec is not None
+            and "image" in base.model_fields_set
+        ):
+            config = config.model_copy(update={"image": base.image})
+        if isinstance(config, vf.SubprocessConfig):
+            raise TypeError(
+                "isolated-verifier requires a container runtime so artifacts can be "
+                "restored safely; configure the agent or verifier runtime as docker, "
+                "prime, or modal"
+            )
+        relative = [
+            artifact.source
+            for artifact in task.data.artifacts
+            if not PurePosixPath(artifact.source).is_absolute()
+        ]
+        solver = resolve_runtime_config(self.config.agent.runtime, task)
+        solver_workdir = PurePosixPath(getattr(solver, "workdir", "") or "/")
+        verifier_workdir = PurePosixPath(config.workdir)
+        if relative and solver_workdir != verifier_workdir:
+            raise ValueError(
+                "isolated-verifier cannot transfer relative artifacts "
+                f"{relative!r} between solver workdir {str(solver_workdir)!r} and "
+                f"verifier workdir {str(verifier_workdir)!r}; use matching workdirs "
+                "or absolute artifact paths"
+            )
+        return config
+
+    async def finalize(self, task: vf.Task, episode: vf.Episode) -> None:
+        solution = episode.traces[0]
+        if solution.ok:
+            graded = await self.grade(self.verifier_config(task), task, solution)
+            episode.traces[0] = graded[1]
+
+    async def stage_verifier(
+        self, task: vf.Task, solution: vf.Trace, runtime: Runtime
+    ) -> None:
+        artifacts = dict(solution.state.artifacts)
+        async with boundary(TaskError, "verifier task setup"):
+            await invoke(task.setup, {"trace": solution, "runtime": runtime})
+        await vf.restore(runtime, artifacts)
+        async with boundary(TaskError, "verifier staging"):
+            await invoke(task.stage_verifier, {"trace": solution, "runtime": runtime})
+
+    async def verify(self, task: vf.Task, solution: vf.Trace, runtime: Runtime) -> Any:
+        await task.score(solution, runtime)
+
+    async def grade(
+        self,
+        config: RuntimeConfig,
+        task: vf.Task,
+        solution: vf.Trace,
+        *,
+        scoring_timeout_covers_attempt: bool = False,
+    ) -> tuple[Any, vf.Trace]:
+        timeouts = resolve_rollout_timeouts(self.config.agent.timeout, task)
+        last: Exception | None = None
+        for attempt in range(self.config.verifier.retries + 1):
+            if attempt:
+                delay = backoff(attempt - 1)
+                logger.warning(
+                    "isolated verifier attempt %d/%d failed (%s); retrying in %.1fs",
+                    attempt,
+                    self.config.verifier.retries + 1,
+                    last,
+                    delay,
+                )
+                await asyncio.sleep(delay)
+            try:
+                # Teardown is outside the stage deadlines: a completed score must
+                # survive a slow cleanup of the verifier runtime.
+                async with (
+                    AsyncExitStack() as boxes,
+                    asyncio.timeout(
+                        timeouts.scoring if scoring_timeout_covers_attempt else None
+                    ),
+                ):
+                    async with asyncio.timeout(timeouts.setup):
+                        # Failed setup or scoring must not alter the next attempt.
+                        # Only the successful controller and trace leave this scope.
+                        verifier_task = copy.deepcopy(task)
+                        verifier_solution = copy.deepcopy(solution)
+                        runtime = await boxes.enter_async_context(
+                            provision_runtime(
+                                config,
+                                env=(
+                                    verifier_task.runtime_env()
+                                    if self.config.verifier.env is None
+                                    else self.config.verifier.env
+                                ),
+                            )
+                        )
+                        await runtime.prepare_setup()
+                        await self.stage_verifier(
+                            verifier_task, verifier_solution, runtime
+                        )
+                        await runtime.prepare_execution([])
+                    async with asyncio.timeout(timeouts.scoring):
+                        result = await self.verify(
+                            verifier_task, verifier_solution, runtime
+                        )
+                    return result, verifier_solution
+            except Exception as error:  # noqa: BLE001 - retry the whole fresh box
+                last = error
+        assert last is not None
+        raise last

{verifiers-0.3.2.dev45 → verifiers-0.3.2.dev47}/verifiers/v1/harnesses/claude_code/harness.py

@@ -1,13 +1,10 @@
 """Run Claude Code through the Claude Agent SDK ACP adapter."""
 
-import shlex
-
-from pydantic import Field
-
 from verifiers.v1.acp import ACPConfig, ACPHarness
 from verifiers.v1.clients import ModelContext
-from verifiers.v1.configs.harness import HarnessConfig
+from verifiers.v1.configs.harness import HarnessConfig, PinnedVersion
 from verifiers.v1.harnesses.node import NODE_BIN_DIR, ensure_node
+from verifiers.v1.harnesses.utils.install import ensure_installed, remove_dir
 from verifiers.v1.runtimes import Runtime
 from verifiers.v1.task import TaskData
 from verifiers.v1.trace import Trace
@@ -32,7 +29,7 @@ touch {ready}
 
 
 class ClaudeCodeHarnessConfig(HarnessConfig):
-    version: str = Field(default="2.1.232", pattern=r"^[A-Za-z0-9._+-]+$")
+    version: PinnedVersion = "2.1.232"
     """Claude Code release to install, pinned for reproducibility."""
 
 
@@ -51,25 +48,18 @@ class ClaudeCodeHarness(ACPHarness[ClaudeCodeHarnessConfig]):
         acp_bin = ACP_BIN.format(**versions)
         ready = f"{directory}/.ready"
         script = ACP_INSTALL.replace("{packages}", packages).replace("{ready}", ready)
-        ensure = shlex.quote(
-            f"[ -f {ready} ] && [ -x {claude_bin} ] && [ -x {acp_bin} ] || ({script})"
-        )
-        acp_guarded = (
-            f"mkdir -p {directory} && "
-            f'"$(command -v flock || command -v lockf)" {directory}/install.lock '
-            f"sh -c {ensure}"
-        )
-        acp_result = await runtime.run(
-            ["sh", "-c", acp_guarded],
-            {
+        await ensure_installed(
+            runtime,
+            directory=directory,
+            ready=f"[ -f {ready} ] && [ -x {claude_bin} ] && [ -x {acp_bin} ]",
+            install=script,
+            env={
                 **self.config.resolved_env,
                 "VF_CLAUDE_CODE_VERSION": self.config.version,
                 "VF_CLAUDE_ACP_VERSION": ACP_VERSION,
             },
+            label="Claude Agent ACP",
         )
-        if acp_result.exit_code != 0:
-            detail = (acp_result.stderr or acp_result.stdout).strip()[-500:]
-            raise RuntimeError(f"Claude Agent ACP install failed: {detail}")
         await super().setup(runtime)
 
     async def prepare_acp(
@@ -113,11 +103,7 @@ class ClaudeCodeHarness(ACPHarness[ClaudeCodeHarnessConfig]):
         )
 
     async def cleanup(self, trace: Trace, runtime: Runtime) -> None:
-        result = await runtime.run(["rm", "-rf", self.config_dir(trace)], {})
-        if result.exit_code != 0:
-            raise RuntimeError(
-                f"failed to clean up Claude config: {result.stderr.strip()[-500:]}"
-            )
+        await remove_dir(runtime, self.config_dir(trace), "Claude config")
 
     @staticmethod
     def config_dir(trace: Trace) -> str:

{verifiers-0.3.2.dev45 → verifiers-0.3.2.dev47}/verifiers/v1/harnesses/codex/harness.py

@@ -4,15 +4,13 @@ import hashlib
 import json
 import logging
 import re
-import shlex
 from collections import Counter
 
-from pydantic import Field
-
 from verifiers.v1.acp import ACPConfig, ACPHarness
 from verifiers.v1.clients import ModelContext
-from verifiers.v1.configs.harness import HarnessConfig
+from verifiers.v1.configs.harness import HarnessConfig, PinnedVersion
 from verifiers.v1.harnesses.node import NODE_BIN_DIR, ensure_node
+from verifiers.v1.harnesses.utils.install import ensure_installed, remove_dir
 from verifiers.v1.runtimes import Runtime
 from verifiers.v1.task import TaskData
 from verifiers.v1.trace import Trace
@@ -38,7 +36,7 @@ touch {ready}
 
 
 class CodexHarnessConfig(HarnessConfig):
-    version: str = Field(default="0.147.0", pattern=r"^[A-Za-z0-9._+-]+$")
+    version: PinnedVersion = "0.147.0"
     """Codex release to install, pinned for reproducibility."""
     multi_agent: bool = False
     """Enable Codex's native multi-agent v2 tools."""
@@ -64,24 +62,18 @@ class CodexHarness(ACPHarness[CodexHarnessConfig]):
         acp_bin = ACP_BIN.format(**versions)
         ready = f"{directory}/.ready"
         script = INSTALL.replace("{packages}", packages).replace("{ready}", ready)
-        ensure = shlex.quote(
-            f"[ -f {ready} ] && [ -x {codex_bin} ] && [ -x {acp_bin} ] || ({script})"
-        )
-        guarded = (
-            f"mkdir -p {directory} && "
-            f'"$(command -v flock || command -v lockf)" {directory}/install.lock '
-            f"sh -c {ensure}"
-        )
-        install = await runtime.run(
-            ["sh", "-c", guarded],
-            {
+        await ensure_installed(
+            runtime,
+            directory=directory,
+            ready=f"[ -f {ready} ] && [ -x {codex_bin} ] && [ -x {acp_bin} ]",
+            install=script,
+            env={
                 **self.config.resolved_env,
                 "VF_CODEX_VERSION": self.config.version,
                 "VF_CODEX_ACP_VERSION": ACP_VERSION,
             },
+            label="codex",
         )
-        if install.exit_code != 0:
-            raise RuntimeError(f"codex install failed: {install.stderr.strip()[-500:]}")
         await super().setup(runtime)
 
     async def prepare_acp(
@@ -112,11 +104,7 @@ class CodexHarness(ACPHarness[CodexHarnessConfig]):
         )
 
     async def cleanup(self, trace: Trace, runtime: Runtime) -> None:
-        result = await runtime.run(["rm", "-rf", self.trace_home(trace)], {})
-        if result.exit_code != 0:
-            raise RuntimeError(
-                f"failed to clean up Codex home: {result.stderr.strip()[-500:]}"
-            )
+        await remove_dir(runtime, self.trace_home(trace), "Codex home")
 
     @staticmethod
     def trace_home(trace: Trace) -> str:

{verifiers-0.3.2.dev45 → verifiers-0.3.2.dev47}/verifiers/v1/harnesses/hermes_agent/harness.py

@@ -3,11 +3,10 @@
 import json
 from pathlib import Path
 
-from pydantic import Field
-
 from verifiers.v1.acp import ACPConfig, ACPHarness
 from verifiers.v1.clients import ModelContext
-from verifiers.v1.configs.harness import HarnessConfig
+from verifiers.v1.configs.harness import HarnessConfig, PinnedVersion
+from verifiers.v1.harnesses.utils.install import remove_dir
 from verifiers.v1.runtimes import Runtime
 from verifiers.v1.task import TaskData
 from verifiers.v1.trace import Trace
@@ -16,7 +15,7 @@ PROGRAM_SOURCE = (Path(__file__).resolve().parent / "program.py").read_text()
 
 
 class HermesAgentHarnessConfig(HarnessConfig):
-    version: str = Field(default="0.19.0", pattern=r"^[A-Za-z0-9._+-]+$")
+    version: PinnedVersion = "0.19.0"
     """Hermes Agent release to install, pinned for reproducibility."""
     use_bundled_skill: bool = False
     """Enable Hermes Agent's bundled skill catalog in addition to uploaded skills."""
@@ -96,8 +95,4 @@ class HermesAgentHarness(ACPHarness[HermesAgentHarnessConfig]):
         )
 
     async def cleanup(self, trace: Trace, runtime: Runtime) -> None:
-        result = await runtime.run(["rm", "-rf", f"/tmp/vf-hermes/{trace.id}"], {})
-        if result.exit_code:
-            raise RuntimeError(
-                f"failed to clean up Hermes home: {result.stderr.strip()[-500:]}"
-            )
+        await remove_dir(runtime, f"/tmp/vf-hermes/{trace.id}", "Hermes home")

{verifiers-0.3.2.dev45 → verifiers-0.3.2.dev47}/verifiers/v1/harnesses/kimi_code/harness.py

@@ -1,15 +1,14 @@
 """Run Kimi Code's native ACP server against interception."""
 
 import logging
-import shlex
 from typing import Literal
 
 import tomli_w
-from pydantic import Field
 
 from verifiers.v1.acp import ACPConfig, ACPHarness
 from verifiers.v1.clients import ModelContext
-from verifiers.v1.configs.harness import HarnessConfig
+from verifiers.v1.configs.harness import HarnessConfig, PinnedVersion
+from verifiers.v1.harnesses.utils.install import ensure_installed
 from verifiers.v1.runtimes import Runtime
 from verifiers.v1.task import TaskData
 from verifiers.v1.trace import Trace
@@ -39,7 +38,7 @@ env \
 
 
 class KimiCodeHarnessConfig(HarnessConfig):
-    version: str = Field(default="0.36.0", pattern=r"^[A-Za-z0-9._+-]+$")
+    version: PinnedVersion = "0.36.0"
     """Kimi Code release to install, pinned for reproducibility."""
     transport: Literal["chat_completions", "responses", "anthropic_messages"] = (
         "chat_completions"
@@ -58,16 +57,13 @@ class KimiCodeHarness(ACPHarness[KimiCodeHarnessConfig]):
             "kimi-code: ensuring Kimi Code %s is installed", self.config.version
         )
         script = INSTALL.replace("{version}", self.config.version)
-        guarded = (
-            "mkdir -p /tmp/vf-kimi-code && "
-            '"$(command -v flock || command -v lockf)" '
-            f"/tmp/vf-kimi-code/install.lock sh -c {shlex.quote(script)}"
+        await ensure_installed(
+            runtime,
+            directory="/tmp/vf-kimi-code",
+            install=script,
+            env={},
+            label="Kimi Code",
         )
-        install = await runtime.run(["sh", "-c", guarded], {})
-        if install.exit_code != 0:
-            raise RuntimeError(
-                f"Kimi Code install failed: {install.stderr.strip()[-500:]}"
-            )
         await super().setup(runtime)
 
     async def prepare_acp(

{verifiers-0.3.2.dev45 → verifiers-0.3.2.dev47}/verifiers/v1/harnesses/mini_swe_agent/harness.py

@@ -1,9 +1,7 @@
 from pathlib import Path
 
-from pydantic import Field
-
 from verifiers.v1.clients import ModelContext
-from verifiers.v1.configs.harness import HarnessConfig
+from verifiers.v1.configs.harness import HarnessConfig, PinnedVersion
 from verifiers.v1.harness import Harness
 from verifiers.v1.runtimes import ProgramResult, Runtime
 from verifiers.v1.task import TaskData
@@ -13,7 +11,7 @@ PROGRAM_SOURCE = (Path(__file__).resolve().parent / "program.py").read_text()
 
 
 class MiniSWEAgentHarnessConfig(HarnessConfig):
-    version: str = Field(default="2.4.6", pattern=r"^[A-Za-z0-9._+-]+$")
+    version: PinnedVersion = "2.4.6"
     """mini-swe-agent release to install, pinned for reproducibility."""
 
 

{verifiers-0.3.2.dev45 → verifiers-0.3.2.dev47}/verifiers/v1/harnesses/node.py

@@ -1,5 +1,4 @@
-import shlex
-
+from verifiers.v1.harnesses.utils.install import ensure_installed
 from verifiers.v1.runtimes import Runtime
 
 NODE_DIR = "/var/tmp/vf-node"
@@ -39,16 +38,12 @@ node_ok || { echo "ACP adapters require Node.js 22.19 or newer" >&2; exit 1; }
 
 async def ensure_node(runtime: Runtime) -> None:
     """Install the shared Node runtime used by ACP adapter harnesses."""
-    lock = f"{NODE_DIR}.install.lock"
-    guarded = (
-        f'until ln -s "$$" {lock} 2>/dev/null; do '
-        f"owner=$(readlink {lock}); "
-        f'if ! kill -0 "$owner" 2>/dev/null; then '
-        f'[ "$(readlink {lock})" != "$owner" ] || rm -f {lock}; fi; '
-        f"sleep 0.1; done; "
-        f'trap \'[ "$(readlink {lock})" != "$$" ] || rm -f {lock}\' EXIT; '
-        f"sh -c {shlex.quote(INSTALL)}"
+    # The install replaces NODE_DIR wholesale, so the lock lives beside it.
+    await ensure_installed(
+        runtime,
+        directory=NODE_DIR,
+        lock=f"{NODE_DIR}.install.lock",
+        install=INSTALL,
+        env={"VF_NODE_VERSION": NODE_VERSION},
+        label="Node.js",
     )
-    result = await runtime.run(["sh", "-c", guarded], {"VF_NODE_VERSION": NODE_VERSION})
-    if result.exit_code != 0:
-        raise RuntimeError(f"Node.js install failed: {result.stderr.strip()[-500:]}")