The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
fix(scratch): no process start waits for the scratch-dir prune
Tekniumeefd03b3ee33
diff --git a/agent/prompt_builder.py b/agent/prompt_builder.pyindex d85519a4ef5..f85a291127b 100644--- a/agent/prompt_builder.py+++ b/agent/prompt_builder.py@@ -16,8 +16,7 @@ from pathlib import Pathfrom typing import Any, Dict, Optionalfrom 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:passdiff --git a/hermes_constants.py b/hermes_constants.pyindex 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 sitesknowing. Entries idle for ``SCRATCH_MAX_IDLE_HOURS`` are pruned at most once per processand 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`` ora 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) -> Paexcept OSError:passif 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_threadif _scratch_pruned_once:returnwith _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.pyindex 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 constantshome = 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 Truehints = _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.0finally: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.mdindex 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` pointRAM-backed system temp dir. The system prompt names this directory as the scratchdirectory. Hermes only sets these when they are not already set — a `TMPDIR` exportedby 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 entrystays as long as anything anywhere inside it was written in the last day, and goes a day afterthe last write. Hardlinked files do not count as writes (a `git clone --local` shares pack fileswith its source repo, whose activity would otherwise keep the clone forever). Before an idle entry is deleted, Hermes also stops any process still running