Skip to content

The agent that grows with you

fix(scratch): no process start waits for the scratch-dir prune

Tekniumeefd03b3ee33
diff --git a/agent/prompt_builder.py b/agent/prompt_builder.py
index d85519a4ef5..f85a291127b 100644
--- a/agent/prompt_builder.py
+++ b/agent/prompt_builder.py
@@ -16,8 +16,7 @@ from pathlib import Path
from typing import Any, Dict, Optional
from hermes_constants import (
- get_hermes_home, get_scratch_dir, get_skills_dir, is_wsl, prune_scratch_dir_in_background,
- reset_hermes_home_override, set_hermes_home_override,
+ get_hermes_home, get_scratch_dir, get_skills_dir, is_wsl, reset_hermes_home_override, set_hermes_home_override,
)
from agent.model_metadata import CHARS_PER_TOKEN
@@ -921,9 +920,7 @@ def _local_host_hints() -> list[str]:
# The model reaches for the system temp dir by reflex (tmpfs on most Linux hosts, fills RAM);
# naming Hermes' scratch dir here is what makes the TMPDIR export a habit rather than a hidden default.
try:
- scratch = get_scratch_dir(prune=False)
- prune_scratch_dir_in_background(scratch)
- host_lines.append(f"Scratch directory: {scratch} (TMPDIR points here; write temporary files "
+ host_lines.append(f"Scratch directory: {get_scratch_dir()} (TMPDIR points here; write temporary files "
"and probes there, never under the system temp dir; entries idle for 24h are pruned)")
except OSError:
pass
diff --git a/hermes_constants.py b/hermes_constants.py
index 2f768768612..35c0548ce4a 100644
--- a/hermes_constants.py
+++ b/hermes_constants.py
@@ -969,6 +969,9 @@ def get_scratch_dir(home: str | Path | None = None, *, prune: bool = True) -> Pa
:func:`export_scratch_tmp_env`), so ``tempfile`` defaults land here without call sites
knowing. Entries idle for ``SCRATCH_MAX_IDLE_HOURS`` are pruned at most once per process
and once per hour across processes (stamp file), so a fan-out of children stays cheap.
+ *prune* only schedules that pass on a daemon thread: the directory itself is created and
+ permissioned before this returns, but no caller (the boot hook included) waits on the
+ idle scan or the ``rmtree`` of a multi-GB entry.
Permissions follow :func:`apply_secure_dir_policy`, so an explicit ``HERMES_HOME_MODE`` or
a managed/shared home is honored instead of a blanket ``0700`` (#117347).
@@ -984,7 +987,7 @@ def get_scratch_dir(home: str | Path | None = None, *, prune: bool = True) -> Pa
except OSError:
pass
if prune:
- _prune_scratch_dir_once(scratch)
+ prune_scratch_dir_in_background(scratch)
return scratch
@@ -1019,13 +1022,21 @@ def _prune_scratch_dir_once(scratch: Path) -> None:
def prune_scratch_dir_in_background(scratch: Path) -> None:
- """Schedule one prune using the caller's resolved home, without blocking a turn."""
+ """Schedule one prune of the *scratch* the caller resolved, without blocking it.
+
+ The thread gets the path, never re-resolves it: threads do not inherit the profile-override
+ contextvar. A process that exits mid-prune kills the daemon thread with the hourly stamp
+ already touched; every deletion is re-validated right before it happens, so a cut pass only
+ leaves fewer entries removed. Entries it never reached go on the next hourly pass; the one
+ cut inside ``rmtree`` has fresh directory mtimes from the unlinks, so its remainder goes
+ 24 h later like any other entry written to."""
global _scratch_prune_thread
if _scratch_pruned_once:
return
with _scratch_prune_lock:
if _scratch_pruned_once or _scratch_prune_thread is not None:
return
+ # health: allow HX012 -- the caller's resolved path is passed in; nothing in the prune reads the scope
_scratch_prune_thread = threading.Thread(
target=_prune_scratch_dir_once, args=(scratch,), name="scratch-prune", daemon=True,
)
diff --git a/tests/test_scratch_dir.py b/tests/test_scratch_dir.py
index 94b5b79afd4..7f969135429 100644
--- a/tests/test_scratch_dir.py
+++ b/tests/test_scratch_dir.py
@@ -22,104 +22,76 @@ from hermes_constants import apply_scratch_tmp_env, get_scratch_dir, prune_scrat
@pytest.fixture
-def background_scratch_prune(tmp_path, monkeypatch):
+def blocked_scratch_prune(tmp_path, monkeypatch):
+ """A once-per-process prune that is still due and blocks until released: a caller that
+ waits on it shows up as a stall, one that does not returns at once."""
import hermes_constants as constants
home = tmp_path / "launch"
monkeypatch.setenv("HERMES_HOME", str(home))
monkeypatch.setattr(constants, "_scratch_pruned_once", False)
- monkeypatch.setattr(constants, "_scratch_prune_thread", None)
- monkeypatch.setattr(constants, "_scratch_prune_lock", threading.Lock())
- calls, threads = [], []
- real_thread = threading.Thread
-
- def tracked_thread(*args, **kwargs):
- thread = real_thread(*args, **kwargs)
- if thread.name == "scratch-prune":
- threads.append(thread)
- return thread
-
- monkeypatch.setattr(constants.threading, "Thread", tracked_thread)
- monkeypatch.setattr(constants, "prune_scratch_dir", calls.append)
+ monkeypatch.setattr(constants, "_scratch_prune_thread", None, raising=False)
+ release, calls = threading.Event(), []
+
+ def blocked_prune(scratch):
+ calls.append(scratch)
+ release.wait(timeout=3)
+
+ monkeypatch.setattr(constants, "prune_scratch_dir", blocked_prune)
token = constants.set_hermes_home_override(None)
try:
- yield SimpleNamespace(home=home, calls=calls, threads=threads)
+ yield SimpleNamespace(home=home, calls=calls, release=release)
finally:
- for thread in threads:
+ release.set()
+ thread = getattr(constants, "_scratch_prune_thread", None)
+ if thread is not None:
thread.join(timeout=5)
assert not thread.is_alive()
constants.reset_hermes_home_override(token)
-def test_host_hints_do_not_wait_for_scratch_prune(background_scratch_prune, monkeypatch):
+def _finish_prune(state):
import hermes_constants as constants
- from agent.prompt_builder import _local_host_hints
- state = background_scratch_prune
+ state.release.set()
+ constants._scratch_prune_thread.join(timeout=5)
+
- def slow_prune(scratch):
- state.calls.append(scratch)
- time.sleep(2) # health: allow HX013 -- simulate the slow prune specified by the regression
+def test_boot_hook_and_prompt_never_wait_for_the_scratch_prune(blocked_scratch_prune):
+ """The boot hook returns with TMPDIR pointing at a scratch dir that already exists, and the
+ prune it triggered runs once, later, on that dir; the prompt build does not start another."""
+ from agent.prompt_builder import _local_host_hints
- monkeypatch.setattr(constants, "prune_scratch_dir", slow_prune)
+ state = blocked_scratch_prune
+ scratch = state.home / "cache" / "scratch"
+ env = {"HERMES_HOME": str(state.home)}
start = time.monotonic()
+ assert apply_scratch_tmp_env(env) is True
hints = _local_host_hints()
- elapsed = time.monotonic() - start
- assert elapsed < 0.5
- assert len(state.threads) == 1
- thread = state.threads[0]
- assert thread.daemon
- thread.join(timeout=5)
- assert not thread.is_alive()
- scratch = state.home / "cache" / "scratch"
+ assert time.monotonic() - start < 1.0
+ assert env["TMPDIR"] == str(scratch) and scratch.is_dir()
+ assert f"Scratch directory: {scratch} (TMPDIR points here" in hints[0]
+ _finish_prune(state)
assert state.calls == [scratch]
- assert f"Scratch directory: {scratch} (TMPDIR points here; write temporary files " in hints[0]
-def test_host_hints_schedule_only_one_scratch_prune(background_scratch_prune, monkeypatch):
+def test_background_prune_targets_the_routed_home(blocked_scratch_prune, tmp_path):
+ """Threads do not inherit the profile override: the prune must use the scratch dir the
+ routed caller resolved, never the launch home's."""
import hermes_constants as constants
- from agent.prompt_builder import _local_host_hints
-
- state = background_scratch_prune
- release = threading.Event()
- prune_once = constants._prune_scratch_dir_once
-
- def delayed_prune(scratch):
- release.wait(timeout=5)
- prune_once(scratch)
-
- monkeypatch.setattr(constants, "_prune_scratch_dir_once", delayed_prune)
- try:
- _local_host_hints()
- _local_host_hints()
- assert len(state.threads) == 1
- finally:
- release.set()
- for thread in state.threads:
- thread.join(timeout=5)
- _local_host_hints()
- assert len(state.threads) == 1
- assert state.calls == [state.home / "cache" / "scratch"]
-
-
-def test_host_hints_scratch_prune_uses_routed_home(background_scratch_prune, tmp_path):
- import hermes_constants as constants
- from agent.prompt_builder import _local_host_hints
- state = background_scratch_prune
- routed_home = tmp_path / "routed"
- token = constants.set_hermes_home_override(routed_home)
+ state = blocked_scratch_prune
+ routed = tmp_path / "routed"
+ token = constants.set_hermes_home_override(routed)
try:
- hints = _local_host_hints()
+ start = time.monotonic()
+ scratch = get_scratch_dir()
+ assert time.monotonic() - start < 1.0
finally:
constants.reset_hermes_home_override(token)
- assert len(state.threads) == 1
- thread = state.threads[0]
- thread.join(timeout=5)
- assert not thread.is_alive()
- scratch = routed_home / "cache" / "scratch"
+ _finish_prune(state)
+ assert scratch == routed / "cache" / "scratch"
assert state.calls == [scratch]
- assert f"Scratch directory: {scratch} (TMPDIR points here; write temporary files " in hints[0]
def test_scratch_env_follows_home_and_respects_user_tmpdir(tmp_path):
diff --git a/website/docs/user-guide/configuration.md b/website/docs/user-guide/configuration.md
index 5c7e70e1af4..b513947415f 100644
--- a/website/docs/user-guide/configuration.md
+++ b/website/docs/user-guide/configuration.md
@@ -258,7 +258,8 @@ backend, cron) and every child it launches gets `TMPDIR`, `TMP` and `TEMP` point
RAM-backed system temp dir. The system prompt names this directory as the scratch
directory. Hermes only sets these when they are not already set — a `TMPDIR` exported
by you or by the OS (macOS `/var/folders`, Windows `%TEMP%`) is left alone. Entries are
-pruned at startup (at most once per hour) once they have been **idle for 24 hours**: an entry
+pruned in the background right after startup (at most once per hour; startup never waits for
+it) once they have been **idle for 24 hours**: an entry
stays as long as anything anywhere inside it was written in the last day, and goes a day after
the last write. Hardlinked files do not count as writes (a `git clone --local` shares pack files
with its source repo, whose activity would otherwise keep the clone forever). Before an idle entry is deleted, Hermes also stops any process still running