Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(bot): make session paths portable on Windows (#4162)

DuTao32a6aff8f9ab
diff --git a/bot/tests/test_agent_loop_outcome.py b/bot/tests/test_agent_loop_outcome.py
index 03fbad040..da49eed79 100644
--- a/bot/tests/test_agent_loop_outcome.py
+++ b/bot/tests/test_agent_loop_outcome.py
@@ -12,7 +12,9 @@ from vikingbot.agent.loop import AgentLoop
from vikingbot.bus.events import InboundMessage, OutboundEventType
from vikingbot.bus.queue import MessageBus
from vikingbot.config.schema import AgentsConfig, Config, SessionKey
+from vikingbot.openviking_mount.session_state import make_openviking_storage_session_id
from vikingbot.providers.base import LLMProvider, LLMResponse, ToolCallRequest
+from vikingbot.session.manager import SessionManager
class _FakeProvider(LLMProvider):
@@ -442,6 +444,58 @@ async def test_agent_loop_build_prompt_history_uses_ov_context_plus_unsynced_tai
]
+async def test_agent_loop_build_prompt_history_falls_back_to_loaded_local_history_when_ov_empty(
+ temp_dir: Path, monkeypatch
+):
+ monkeypatch.setattr(AgentLoop, "_register_builtin_hooks", lambda self: None)
+ monkeypatch.setattr(AgentLoop, "_register_default_tools", lambda self: None)
+ monkeypatch.setattr("vikingbot.agent.loop.SubagentManager", _FakeSubagentManager)
+
+ fake_ov_client = _FakeOVClient(context_payload={"messages": []})
+
+ async def fake_get_ov_client(self, session_key, openviking_connection=None, actor_peer_id=None):
+ del self, session_key, openviking_connection, actor_peer_id
+ return fake_ov_client
+
+ monkeypatch.setattr(AgentLoop, "_get_ov_client", fake_get_ov_client)
+
+ config = Config(
+ storage_workspace=str(temp_dir),
+ ov_server={"server_url": "http://127.0.0.1:1933"},
+ agents={"session_context_enabled": True, "session_context_token_budget": 321},
+ )
+ loop = AgentLoop(
+ bus=MessageBus(),
+ provider=_FakeProvider(),
+ workspace=temp_dir / "workspace",
+ config=config,
+ )
+
+ session_key = SessionKey(type="cli", channel_id="default", chat_id="session-local-fallback")
+ session = loop.sessions.get_or_create(session_key, skip_heartbeat=True)
+ session.add_message("user", "persisted user")
+ session.add_message("assistant", "persisted assistant")
+ session.add_message("user", "current question")
+ session.metadata["openviking"] = {
+ "session_id": "ov-session-missing-context",
+ "last_synced_local_index": 1,
+ }
+ await loop.sessions.save(session)
+
+ restarted_sessions = SessionManager(config.bot_data_path)
+ loaded_session = restarted_sessions.get_or_create(session_key, skip_heartbeat=True)
+ history = await loop._build_prompt_history(loaded_session)
+
+ assert fake_ov_client.context_calls == [("ov-session-missing-context", 321)]
+ assert [message["content"] for message in history] == [
+ "persisted user",
+ "persisted assistant",
+ "current question",
+ ]
+ assert loaded_session.metadata["openviking"]["last_synced_local_index"] == 1
+
+
@pytest.mark.asyncio
async def test_agent_loop_build_prompt_history_skips_tail_when_sync_cursor_is_past_local_messages(
temp_dir: Path, monkeypatch
@@ -656,7 +710,7 @@ async def test_agent_loop_submits_openviking_session_through_compact_hook(
assert len(calls) == 1
context, kwargs = calls[0]
assert context.event_type == "message.compact"
- assert context.session_id == session_key.safe_name()
+ assert context.session_id == make_openviking_storage_session_id(session_key.safe_name())
assert kwargs == {"session": session, "force_commit": False}
@@ -1038,6 +1092,8 @@ async def test_agent_loop_post_turn_clears_local_session_after_openviking_commit
persisted_session = loop.sessions.get_or_create(session_key, skip_heartbeat=True)
assert calls[-1]["commit_message_threshold"] == 3
assert persisted_session.messages == []
- assert persisted_session.metadata["openviking"]["session_id"] == session_key.safe_name()
+ assert persisted_session.metadata["openviking"]["session_id"] == (
+ make_openviking_storage_session_id(session_key.safe_name())
+ )
assert persisted_session.metadata["openviking"]["last_synced_local_index"] == -1
assert persisted_session.metadata["openviking"]["last_commit_local_index"] == -1
diff --git a/bot/tests/test_compile.py b/bot/tests/test_compile.py
index cecd62d47..0b36fb8c9 100644
--- a/bot/tests/test_compile.py
+++ b/bot/tests/test_compile.py
@@ -56,6 +56,7 @@ from vikingbot.config.schema import (
from vikingbot.sandbox import SandboxManager
from vikingbot.sandbox.backends.srt import SrtBackend
from vikingbot.sandbox.base import SandboxFileInfo
+from vikingbot.utils.session_paths import portable_path_component
from openviking.core.skill_loader import SkillLoader
from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils
@@ -4630,7 +4631,7 @@ async def test_srt_settings_created_by_manager_are_in_the_workspace_baseline(
skills=[],
)
manager = SandboxManager(config, tmp_path / "workspaces", tmp_path / "source")
- session_key = SessionKey(type="compile", channel_id="cmp", chat_id="cmp")
+ session_key = SessionKey(type="compile", channel_id="cmp", chat_id="cmp:windows")
sandbox = await manager.get_sandbox(session_key)
baseline = {
@@ -4639,7 +4640,10 @@ async def test_srt_settings_created_by_manager_are_in_the_workspace_baseline(
}
workspace_id = manager.to_workspace_id(session_key)
- assert baseline == {f"sandboxes/{workspace_id}-srt-settings.json"}
+ settings_name = portable_path_component(workspace_id)
+ assert ":" in workspace_id
+ assert ":" not in settings_name
+ assert baseline == {f"sandboxes/{settings_name}-srt-settings.json"}
@pytest.mark.asyncio
diff --git a/bot/tests/test_openapi_auth.py b/bot/tests/test_openapi_auth.py
index dbed13039..3197f9c57 100644
--- a/bot/tests/test_openapi_auth.py
+++ b/bot/tests/test_openapi_auth.py
@@ -19,6 +19,7 @@ from vikingbot.channels.openapi_models import ChatRequest, ChatResponse
from vikingbot.compile.models import CompileAccepted
from vikingbot.config.schema import BotChannelConfig, SessionKey
from vikingbot.session.manager import Session
+from vikingbot.utils.session_paths import portable_session_name
@pytest.fixture
@@ -218,6 +219,20 @@ class TestOpenAPIAuth:
assert response.status_code == 409
assert message_bus.inbound_size == 0
+ def test_scoped_session_id_stays_logical_while_storage_path_is_portable(
+ self, message_bus, temp_workspace
+ ):
+ channel = OpenAPIChannel(OpenAPIChannelConfig(), message_bus, temp_workspace)
+ scope = channel._principal_scope("standalone")
+ storage_key = channel._scoped_session_id(scope, "order:123")
+ session_key = SessionKey(type="cli", channel_id="default", chat_id=storage_key)
+
+ assert storage_key == f"{scope}:order:123"
+ assert session_key.safe_name() == f"cli__default__{scope}:order:123"
+ assert channel._session_manager._get_session_path(session_key).name == (
+ f"{portable_session_name(session_key)}.jsonl"
+ )
+
def test_delete_rotation_survives_restart_and_session_id_reuse(
self, message_bus, temp_workspace
):
@@ -1579,7 +1594,7 @@ class TestOpenAPIAuth:
assert response.status_code == 200
- session_path = temp_workspace / "sessions" / "cli__default__session-1.jsonl"
+ session_path = channel._session_manager._get_session_path(session_key)
lines = session_path.read_text(encoding="utf-8").splitlines()
metadata = json.loads(lines[0])
messages = [json.loads(line) for line in lines[1:]]
diff --git a/bot/tests/test_openviking_api_key_type.py b/bot/tests/test_openviking_api_key_type.py
index 5fa958711..402c81326 100644
--- a/bot/tests/test_openviking_api_key_type.py
+++ b/bot/tests/test_openviking_api_key_type.py
@@ -24,7 +24,11 @@ from vikingbot.hooks.builtins import openviking_hooks as openviking_hooks_module
from vikingbot.hooks.builtins.openviking_hooks import OpenVikingCompactHook
from vikingbot.openviking_mount import ov_server as ov_server_module
from vikingbot.openviking_mount.ov_server import VikingClient
-from vikingbot.openviking_mount.session_state import reset_openviking_state
+from vikingbot.openviking_mount.session_state import (
+ OPENVIKING_SESSION_ID_FORMAT,
+ make_openviking_storage_session_id,
+ reset_openviking_state,
+)
from vikingbot.session.manager import SessionManager
@@ -1214,7 +1218,13 @@ async def test_compact_hook_session_context_commits_single_session_with_peer_mes
pending_tokens = self.pending_tokens.pop(0) if self.pending_tokens else 0
return {"session_id": session_id, "pending_tokens": pending_tokens}
- async def commit_session(self, session_id, keep_recent_count=0, user_id=None):
+ async def commit_session(
+ self,
+ session_id,
+ keep_recent_count=0,
+ user_id=None,
+ **_retention_kwargs,
+ ):
self.commit_calls.append((session_id, keep_recent_count, user_id))
return {"session_id": session_id, "status": "accepted"}
@@ -1226,10 +1236,17 @@ async def test_compact_hook_session_context_commits_single_session_with_peer_mes
monkeypatch.setattr(hook, "_get_client", _fake_get_client)
+ session_key = SessionKey(
+ type="cli",
+ channel_id="default",
+ chat_id="4ab668637bdb513f9384c8a8:order:123",
+ )
+ logical_session_id = session_key.safe_name()
+ storage_session_id = make_openviking_storage_session_id(logical_session_id)
context = HookContext(
event_type="message.compact",
workspace_id="ws",
- session_key=SessionKey(type="cli", channel_id="default", chat_id="chat-1"),
+ session_key=session_key,
)
session = SimpleNamespace(
messages=[
@@ -1248,16 +1265,22 @@ async def test_compact_hook_session_context_commits_single_session_with_peer_mes
assert result["users_count"] == 0
assert fake_client.append_calls == [
(
- "cli__default__chat-1",
+ storage_session_id,
["admin answer", "u1 asks", "u1 reply", "u2 asks"],
None,
"admin",
)
]
- assert fake_client.commit_calls == [("cli__default__chat-1", 2, "admin")]
+ assert fake_client.commit_calls == [(storage_session_id, 0, "admin")]
+ assert {session_id for session_id, _user_id in fake_client.session_calls} == {
+ storage_session_id
+ }
+ assert ":" not in storage_session_id
state = session.metadata["openviking"]
- assert state["session_id"] == "cli__default__chat-1"
+ assert state["session_id"] == storage_session_id
+ assert state["logical_session_id"] == logical_session_id
+ assert state["session_id_format"] == OPENVIKING_SESSION_ID_FORMAT
assert state["last_synced_local_index"] == len(session.messages) - 1
assert state["last_pending_tokens"] == 0
assert state["last_sync_status"] == "success"
diff --git a/bot/tests/test_sandbox_startup.py b/bot/tests/test_sandbox_startup.py
index c4c4cbbbd..cf799902a 100644
--- a/bot/tests/test_sandbox_startup.py
+++ b/bot/tests/test_sandbox_startup.py
@@ -13,6 +13,7 @@ sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from vikingbot.config.schema import Config, SessionKey # noqa: E402
from vikingbot.sandbox.backends.srt import SrtBackend # noqa: E402
from vikingbot.sandbox.manager import SandboxManager # noqa: E402
+from vikingbot.utils.session_paths import portable_path_component # noqa: E402
def test_srt_backend_uses_workspace_id_and_nested_config(tmp_path):
@@ -21,7 +22,7 @@ def test_srt_backend_uses_workspace_id_and_nested_config(tmp_path):
backend = SrtBackend(config, "shared", tmp_path / "shared")
- assert backend._settings_path.name == "shared-srt-settings.json"
+ assert backend._settings_path.name == (f"{portable_path_component('shared')}-srt-settings.json")
settings = json.loads(backend._settings_path.read_text())
assert settings["network"]["allowedDomains"] == ["example.com"]
assert settings["filesystem"]["allowWrite"][0] == str((tmp_path / "shared").resolve())
diff --git a/bot/tests/test_session_portable_paths.py b/bot/tests/test_session_portable_paths.py
new file mode 100644
index 000000000..d45f4ab39
--- /dev/null
+++ b/bot/tests/test_session_portable_paths.py
@@ -0,0 +1,345 @@
+"""Regression tests for portable Bot session persistence paths."""
+
+import hashlib
+import json
+import os
+import unicodedata
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+from vikingbot.config.schema import SessionKey
+from vikingbot.heartbeat.service import HeartbeatService
+from vikingbot.openviking_mount.session_state import (
+ OPENVIKING_SESSION_ID_FORMAT,
+ get_openviking_session_id,
+)
+from vikingbot.sandbox.manager import SandboxManager
+from vikingbot.session.manager import Session, SessionManager
+from vikingbot.utils.session_paths import (
+ portable_path_component,
+ resolve_workspace_path,
+ workspace_name,
+)
+
+
+def _write_session(
+ path: Path,
+ key: SessionKey,
+ content: str,
+ *,
+ metadata: dict | None = None,
+) -> None:
+ metadata = {
+ "_type": "metadata",
+ "session_key": key.safe_name(),
+ "created_at": "2026-08-20T00:00:00",
+ "updated_at": "2026-08-20T00:00:01",
+ "metadata": metadata if metadata is not None else {"source": content},
+ }
+ message = {
+ "role": "user",
+ "content": content,
+ "timestamp": "2026-08-20T00:00:01",
+ }
+ path.write_text(
+ f"{json.dumps(metadata, ensure_ascii=False)}\n{json.dumps(message, ensure_ascii=False)}\n",
+ encoding="utf-8",
+ )
+
+
+ ("logical", "portable"),
+ [
+ ("order-123", "order-123"),
+ ("订单😀", "订单😀"),
+ ("order:123", "order%3A123"),
+ ("folder/name", "folder%2Fname"),
+ (r"folder\name", "folder%5Cname"),
+ ('bad<>"|?*', "bad%3C%3E%22%7C%3F%2A"),
+ ("literal%3A", "literal%253A"),
+ ("line\nbreak", "line%0Abreak"),
+ ("trailing.", "trailing%2E"),
+ ("trailing ", "trailing%20"),
+ ("CON", "%43ON"),
+ ],
+)
+def test_portable_path_component_is_readable_and_windows_safe(logical, portable):
+ result = portable_path_component(logical)
+ digest = hashlib.sha256(logical.encode("utf-8", errors="surrogatepass")).hexdigest()[:16]
+
+ assert result == f"{portable}~{digest}"
+ assert not any(character in result for character in '<>:"/\\|?*')
+ assert not result.endswith((".", " "))
+
+
+def test_portable_path_component_bounds_long_names():
+ first = portable_path_component("订单" * 200)
+ second = portable_path_component("订单" * 199 + "号")
+
+ assert len(first.encode("utf-8")) <= 180
+ assert len(second.encode("utf-8")) <= 180
+ assert first != second
+ assert "订单" in first
+
+
+def test_portable_path_components_resist_case_and_unicode_normalization_collisions():
+ lower = portable_path_component("foo")
+ upper = portable_path_component("FOO")
+ composed = portable_path_component("é")
+ decomposed = portable_path_component("e\u0301")
+
+ assert lower.casefold() != upper.casefold()
+ assert unicodedata.normalize("NFD", composed) != unicodedata.normalize("NFD", decomposed)
+
+
+def test_openviking_storage_id_preserves_successful_legacy_namespace():
+ key = SessionKey(type="cli", channel_id="default", chat_id="scope:order:123")
+ logical_session_id = key.safe_name()
+ session = Session(
+ key=key,
+ metadata={
+ "openviking": {
+ "session_id": logical_session_id,
+ "last_sync_status": "success",
+ }
+ },
+ )
+
+ assert get_openviking_session_id(session) == logical_session_id
+ assert session.metadata["openviking"].get("session_id_format") is None
+
+
+def test_openviking_storage_id_migrates_known_failed_unsafe_legacy_id():
+ key = SessionKey(type="cli", channel_id="default", chat_id="scope:order:123")
+ logical_session_id = key.safe_name()
+ session = Session(
+ key=key,
+ metadata={
+ "openviking": {
+ "session_id": logical_session_id,
+ "last_sync_status": "error",
+ "last_synced_local_index": -1,
+ "last_commit_local_index": -1,
+ }
+ },
+ )
+
+ storage_session_id = get_openviking_session_id(session)
+
+ assert storage_session_id == portable_path_component(logical_session_id)
+ assert ":" not in storage_session_id
+ assert session.metadata["openviking"]["logical_session_id"] == logical_session_id
+ assert session.metadata["openviking"]["session_id_format"] == (OPENVIKING_SESSION_ID_FORMAT)
+
+
+def test_new_session_uses_portable_filename_without_changing_logical_key(tmp_path):
+ manager = SessionManager(tmp_path / "bot")
+ key = SessionKey(
+ type="cli",
+ channel_id="default",
+ chat_id="account:order__123/branch?",
+ )
+ session = Session(key=key, metadata={"openviking": {"session_id": key.safe_name()}})
+ session.add_message("user", "hello")
+
+ manager._save_unlocked(session)
+
+ path = manager._get_session_path(key)
+ assert path.name == f"{portable_path_component(key.safe_name())}.jsonl"
+ assert path.name.startswith("cli__default__account%3Aorder__123%2Fbranch%3F~")
+ assert path.exists()
+ first_line = json.loads(path.read_text(encoding="utf-8").splitlines()[0])
+ assert first_line["session_key"] == key.safe_name()
+ assert first_line["session_key_fields"] == key.model_dump(mode="json")
+ assert first_line["metadata"]["openviking"]["session_id"] == key.safe_name()
+
+ restarted = SessionManager(tmp_path / "bot")
+ loaded = restarted.get_or_create(key)
+ assert loaded.key == key
+ assert loaded.messages[0]["content"] == "hello"
+ assert restarted.list_sessions()[0]["key"] == key
+
+
+def test_legacy_metadata_preserves_double_underscore_in_chat_id(tmp_path):
+ manager = SessionManager(tmp_path / "bot")
+ key = SessionKey(type="cli", channel_id="default", chat_id="legacy__session")
+ path = manager.sessions_dir / f"{key.safe_name()}.jsonl"
+ _write_session(path, key, "legacy history")
+
+ assert manager.get_or_create(key).key == key
+ assert manager.list_sessions()[0]["key"] == key
+
+
+def test_legacy_session_is_loaded_then_lazily_migrated_on_save(tmp_path):
+ manager = SessionManager(tmp_path / "bot")
+ key = SessionKey(type="cli", channel_id="default", chat_id="legacy%session")
+ legacy_path = manager.sessions_dir / f"{key.safe_name()}.jsonl"
+ canonical_path = manager._get_session_path(key)
+ _write_session(legacy_path, key, "legacy history")
+
+ loaded = manager.get_or_create(key)
+
+ assert loaded.messages[0]["content"] == "legacy history"
+ assert manager.has_persisted(key)
+ assert legacy_path.exists()
+ assert not canonical_path.exists()
+
+ manager._save_unlocked(loaded)
+
+ assert canonical_path.exists()
+ assert not legacy_path.exists()
+ assert SessionManager(tmp_path / "bot").get_or_create(key).messages[0]["content"] == (
+ "legacy history"
+ )
+
+
[email protected](os.name == "nt", reason="Windows cannot create the legacy colon filename")
+def test_legacy_openapi_session_migrates_without_changing_openviking_id(tmp_path):
+ manager = SessionManager(tmp_path / "bot")
+ key = SessionKey(
+ type="cli",
+ channel_id="default",
+ chat_id="4ab668637bdb513f9384c8a8:order-123:7425fd71",
+ )
+ legacy_path = manager.sessions_dir / f"{key.safe_name()}.jsonl"
+ canonical_path = manager._get_session_path(key)
+ openviking_id = key.safe_name()
+ _write_session(
+ legacy_path,
+ key,
+ "existing OpenAPI history",
+ metadata={"openviking": {"session_id": openviking_id}},
+ )
+
+ loaded = manager.get_or_create(key)
+ manager._save_unlocked(loaded)
+
+ assert canonical_path.name == f"{portable_path_component(key.safe_name())}.jsonl"
+ assert canonical_path.exists()
+ assert not legacy_path.exists()
+ assert loaded.key == key
+ assert loaded.metadata["openviking"]["session_id"] == openviking_id
+ assert loaded.messages[0]["content"] == "existing OpenAPI history"
+
+
+def test_delete_removes_canonical_and_legacy_files(tmp_path):
+ manager = SessionManager(tmp_path / "bot")
+ key = SessionKey(type="cli", channel_id="default", chat_id="both%paths")
+ canonical_path = manager._get_session_path(key)
+ legacy_path = manager.sessions_dir / f"{key.safe_name()}.jsonl"
+ _write_session(canonical_path, key, "canonical")
+ _write_session(legacy_path, key, "legacy")
+
+ assert manager.delete(key)
+ assert not canonical_path.exists()
+ assert not legacy_path.exists()
+
+
+def test_list_sessions_deduplicates_interrupted_migration(tmp_path):
+ manager = SessionManager(tmp_path / "bot")
+ key = SessionKey(type="cli", channel_id="default", chat_id="both%paths")
+ canonical_path = manager._get_session_path(key)
+ legacy_path = manager.sessions_dir / f"{key.safe_name()}.jsonl"
+ _write_session(legacy_path, key, "legacy")
+ _write_session(canonical_path, key, "canonical")
+
+ sessions = manager.list_sessions()
+
+ assert len(sessions) == 1
+ assert sessions[0]["key"] == key
+ assert sessions[0]["path"] == str(canonical_path)
+
+
+def test_session_files_do_not_collide_after_casefold_or_unicode_normalization(tmp_path):
+ manager = SessionManager(tmp_path / "bot")
+ keys = [
+ SessionKey(type="cli", channel_id="default", chat_id="foo"),
+ SessionKey(type="cli", channel_id="default", chat_id="FOO"),
+ SessionKey(type="cli", channel_id="default", chat_id="é"),
+ SessionKey(type="cli", channel_id="default", chat_id="e\u0301"),
+ ]
+
+ paths = []
+ for key in keys:
+ session = Session(key=key)
+ session.add_message("user", key.chat_id)
+ manager._save_unlocked(session)
+ paths.append(manager._get_session_path(key))
+
+ assert len({path.name.casefold() for path in paths}) == len(paths)
+ assert len({unicodedata.normalize("NFD", path.name) for path in paths}) == len(paths)
+ assert all(path.exists() for path in paths)
+
+
+def test_legacy_lookup_does_not_reuse_a_case_folded_different_session(tmp_path):
+ manager = SessionManager(tmp_path / "bot")
+ lower = SessionKey(type="cli", channel_id="default", chat_id="foo")
+ upper = SessionKey(type="cli", channel_id="default", chat_id="FOO")
+ _write_session(manager.sessions_dir / f"{lower.safe_name()}.jsonl", lower, "lower")
+
+ assert manager._find_session_path(upper) is None
+
+
+ ("mode", "logical_name"),
+ [
+ ("per-session", "cli__alerts:primary__order:123"),
+ ("per-channel", "cli__alerts:primary"),
+ ],
+)
+def test_workspace_names_are_portable_for_every_isolation_mode(mode, logical_name):
+ key = SessionKey(type="cli", channel_id="alerts:primary", chat_id="order:123")
+
+ result = workspace_name(key, mode, portable=True)
+
+ assert result == portable_path_component(logical_name)
+ assert result.startswith(logical_name.replace(":", "%3A"))
+ assert ":" not in result
+
+
+def test_sandbox_and_heartbeat_reuse_existing_legacy_workspace(tmp_path):
+ key = SessionKey(type="cli", channel_id="default", chat_id="legacy%workspace")
+ legacy_name = workspace_name(key, "per-session", portable=False)
+ legacy_path = tmp_path / legacy_name
+ legacy_path.mkdir()
+
+ sandbox_manager = object.__new__(SandboxManager)
+ sandbox_manager.workspace = tmp_path
+ sandbox_manager.config = SimpleNamespace(sandbox=SimpleNamespace(mode="per-session"))
+ assert sandbox_manager.to_workspace_id(key) == legacy_name
+ assert sandbox_manager.get_workspace_path(key) == legacy_path
+
+ session_manager = SimpleNamespace(
+ list_sessions=lambda: [
+ {
+ "key": key,
+ "created_at": "2026-08-20T00:00:00",
+ "updated_at": "2026-08-20T00:00:01",
+ "metadata": {},
+ }
+ ]
+ )
+ heartbeat = HeartbeatService(
+ workspace=tmp_path,
+ sandbox_mode="per-session",
+ session_manager=session_manager,
+ )
+ assert heartbeat._get_all_workspaces() == {legacy_path: [key]}
+
+
+def test_legacy_workspace_with_path_separators_is_not_reused(tmp_path):
+ key = SessionKey(type="cli", channel_id="default", chat_id="nested/workspace")
+ canonical = tmp_path / workspace_name(key, "per-session", portable=True)
+
+ assert resolve_workspace_path(tmp_path, key, "per-session") == canonical
+ assert canonical.parent == tmp_path
+
+
+def test_legacy_workspace_lookup_requires_exact_logical_name(tmp_path):
+ lower = SessionKey(type="cli", channel_id="default", chat_id="foo")
+ upper = SessionKey(type="cli", channel_id="default", chat_id="FOO")
+ (tmp_path / lower.safe_name()).mkdir()
+
+ expected = tmp_path / workspace_name(upper, "per-session", portable=True)
+ assert resolve_workspace_path(tmp_path, upper, "per-session") == expected
diff --git a/bot/vikingbot/agent/loop.py b/bot/vikingbot/agent/loop.py
index b987816f8..91bc6a73b 100644
--- a/bot/vikingbot/agent/loop.py
+++ b/bot/vikingbot/agent/loop.py
@@ -867,9 +867,16 @@ class AgentLoop:
context_payload,
provider_name=provider_name,
)
+ unsynced_messages = get_unsynced_messages(session)
+ if not ov_history and len(unsynced_messages) < len(session.messages):
+ logger.warning(
+ f"OpenViking returned no session context for {session_id}; "
+ "falling back to complete local session history."
+ )
+ unsynced_messages = session.messages
local_tail = self._format_history_messages(
session,
- get_unsynced_messages(session),
+ unsynced_messages,
provider_name=provider_name,
)
combined_history = ov_history + local_tail
diff --git a/bot/vikingbot/config/schema.py b/bot/vikingbot/config/schema.py
index 44a95b41f..49724f701 100644
--- a/bot/vikingbot/config/schema.py
+++ b/bot/vikingbot/config/schema.py
@@ -1070,7 +1070,9 @@ class SessionKey(BaseModel):
@staticmethod
def from_safe_name(safe_name: str):
- file_name_split = safe_name.split("__")
+ file_name_split = safe_name.split("__", 2)
+ if len(file_name_split) != 3:
+ raise ValueError(f"Invalid session key: {safe_name!r}")
return SessionKey(
type=file_name_split[0], channel_id=file_name_split[1], chat_id=file_name_split[2]
)
diff --git a/bot/vikingbot/heartbeat/service.py b/bot/vikingbot/heartbeat/service.py
index ed916273a..a564c5d7d 100644
--- a/bot/vikingbot/heartbeat/service.py
+++ b/bot/vikingbot/heartbeat/service.py
@@ -9,6 +9,7 @@ from loguru import logger
from vikingbot.config.schema import SessionKey
from vikingbot.session.manager import SessionManager
+from vikingbot.utils.session_paths import resolve_workspace_path
# Default interval: 30 minutes
DEFAULT_HEARTBEAT_INTERVAL_S = 30 * 60
@@ -131,7 +132,11 @@ class HeartbeatService:
if self.sandbox_mode == "shared":
sandbox_workspace = self.workspace / "shared"
else:
- sandbox_workspace = self.workspace / session_key.safe_name()
+ sandbox_workspace = resolve_workspace_path(
+ self.workspace,
+ session_key,
+ self.sandbox_mode,
+ )
workspaces.setdefault(sandbox_workspace, []).append(session_key)
return workspaces
diff --git a/bot/vikingbot/openviking_mount/session_state.py b/bot/vikingbot/openviking_mount/session_state.py
index be8e0ec4a..d5548eab8 100644
--- a/bot/vikingbot/openviking_mount/session_state.py
+++ b/bot/vikingbot/openviking_mount/session_state.py
@@ -4,6 +4,12 @@ import uuid
from typing import Any
from vikingbot.session.manager import Session
+from vikingbot.utils.session_paths import (
+ is_windows_safe_path_component,
+ portable_path_component,
+)
+
+OPENVIKING_SESSION_ID_FORMAT = "portable-v1"
def get_openviking_state(session: Session) -> dict[str, Any]:
@@ -22,6 +28,33 @@ def parse_local_index(value: Any, default: int = -1) -> int:
return max(index, -1)
+def make_openviking_storage_session_id(logical_session_id: str) -> str:
+ """Map a logical Bot session ID to a stable OpenViking storage ID."""
+ return portable_path_component(logical_session_id)
+
+
+def _legacy_session_has_synced_data(state: dict[str, Any]) -> bool:
+ if state.get("last_sync_status") == "success":
+ return True
+ if parse_local_index(state.get("last_synced_local_index", -1)) >= 0:
+ return True
+ if parse_local_index(state.get("last_commit_local_index", -1)) >= 0:
+ return True
+ sender_indexes = state.get("last_sender_synced_local_indexes")
+ return isinstance(sender_indexes, dict) and any(
+ parse_local_index(index) >= 0 for index in sender_indexes.values()
+ )
+
+
+def _can_migrate_failed_legacy_session_id(state: dict[str, Any], session_id: str) -> bool:
+ """Migrate only known-failed unsafe IDs; preserve unknown legacy namespaces."""
+ return bool(
+ state.get("last_sync_status") == "error"
+ and not is_windows_safe_path_component(session_id)
+ and not _legacy_session_has_synced_data(state)
+ )
+
+
def get_openviking_session_id(
session: Session,
*,
@@ -30,21 +63,32 @@ def get_openviking_session_id(
) -> str:
state = get_openviking_state(session)
current_session_id = str(state.get("session_id") or "").strip()
- if current_session_id and not rotate:
+ if (
+ current_session_id
+ and not rotate
+ and not _can_migrate_failed_legacy_session_id(state, current_session_id)
+ ):
return current_session_id
- if default_session_id:
+ if current_session_id and not rotate:
+ base_session_id = current_session_id
+ elif default_session_id:
base_session_id = default_session_id
else:
base_session_id = session.key.safe_name()
- session_id = f"{base_session_id}-{uuid.uuid4().hex[:8]}" if rotate else base_session_id
+
+ logical_session_id = f"{base_session_id}-{uuid.uuid4().hex[:8]}" if rotate else base_session_id
+ session_id = make_openviking_storage_session_id(logical_session_id)
state["session_id"] = session_id
+ state["logical_session_id"] = logical_session_id
+ state["session_id_format"] = OPENVIKING_SESSION_ID_FORMAT
return session_id
def reset_openviking_state(session: Session, *, rotate_session_id: bool = False) -> None:
session_id = get_openviking_session_id(session, rotate=rotate_session_id)
- session.metadata["openviking"] = {
+ previous_state = get_openviking_state(session)
+ state = {
"session_id": session_id,
"last_synced_local_index": -1,
"last_sender_synced_local_indexes": {},
@@ -52,6 +96,10 @@ def reset_openviking_state(session: Session, *, rotate_session_id: bool = False)
"last_commit_local_index": -1,
"last_sync_status": "reset",
}
+ for key in ("logical_session_id", "session_id_format"):
+ if key in previous_state:
+ state[key] = previous_state[key]
+ session.metadata["openviking"] = state
def get_unsynced_messages(
diff --git a/bot/vikingbot/sandbox/backends/srt.py b/bot/vikingbot/sandbox/backends/srt.py
index 1a16e1efa..4824df821 100644
--- a/bot/vikingbot/sandbox/backends/srt.py
+++ b/bot/vikingbot/sandbox/backends/srt.py
@@ -11,6 +11,7 @@ from loguru import logger
from vikingbot.config.schema import SandboxConfig
from vikingbot.sandbox.backends import register_backend
from vikingbot.sandbox.base import SandboxBackend, SandboxNotStartedError
+from vikingbot.utils.session_paths import portable_path_component
@register_backend("srt")
@@ -41,7 +42,8 @@ class SrtBackend(SandboxBackend):
srt_config = self._load_config()
# Place settings file in workspace/sandboxes/ directory
- settings_path = self._workspace / "sandboxes" / f"{self.workspace_id}-srt-settings.json"
+ settings_name = portable_path_component(self.workspace_id)
+ settings_path = self._workspace / "sandboxes" / f"{settings_name}-srt-settings.json"
settings_path.parent.mkdir(parents=True, exist_ok=True)
with open(settings_path, "w") as f:
diff --git a/bot/vikingbot/sandbox/manager.py b/bot/vikingbot/sandbox/manager.py
index ab62c037a..07c1902aa 100644
--- a/bot/vikingbot/sandbox/manager.py
+++ b/bot/vikingbot/sandbox/manager.py
@@ -7,6 +7,7 @@ from loguru import logger
from vikingbot.config.schema import Config, SessionKey
from vikingbot.sandbox.backends import get_backend
from vikingbot.sandbox.base import SandboxBackend, UnsupportedBackendError
+from vikingbot.utils.session_paths import resolve_workspace_path, workspace_name
class SandboxManager:
@@ -39,13 +40,15 @@ class SandboxManager:
"""Get or create session-specific sandbox."""
workspace_id = self.to_workspace_id(session_key)
if workspace_id not in self._sandboxes:
- sandbox = await self._create_sandbox(workspace_id)
+ sandbox = await self._create_sandbox(
+ workspace_id,
+ self.get_workspace_path(session_key),
+ )
self._sandboxes[workspace_id] = sandbox
return self._sandboxes[workspace_id]
- async def _create_sandbox(self, workspace_id: str) -> SandboxBackend:
+ async def _create_sandbox(self, workspace_id: str, workspace: Path) -> SandboxBackend:
"""Create new sandbox instance."""
- workspace = self.workspace / workspace_id
instance = self._backend_cls(self.config.sandbox, workspace_id, workspace)
try:
await instance.start()
@@ -110,15 +113,14 @@ class SandboxManager:
self._sandboxes.clear()
def get_workspace_path(self, session_key: SessionKey) -> Path:
- return self.workspace / self.to_workspace_id(session_key)
+ return resolve_workspace_path(
+ self.workspace,
+ session_key,
+ self.config.sandbox.mode,
+ )
def to_workspace_id(self, session_key: SessionKey):
- if self.config.sandbox.mode == "shared":
- return "shared"
- elif self.config.sandbox.mode == "per-channel":
- return session_key.channel_key()
- else: # per-session
- return session_key.safe_name()
+ return workspace_name(session_key, self.config.sandbox.mode, portable=False)
async def get_sandbox_cwd(self, session_key: SessionKey) -> str:
sandbox: SandboxBackend = await self._get_or_create_sandbox(session_key)
diff --git a/bot/vikingbot/session/manager.py b/bot/vikingbot/session/manager.py
index 8339962d1..e9ed505e4 100644
--- a/bot/vikingbot/session/manager.py
+++ b/bot/vikingbot/session/manager.py
@@ -2,6 +2,7 @@
import asyncio
import json
+import uuid
from dataclasses import dataclass, field
from datetime import datetime
from pathlib import Path
@@ -13,6 +14,10 @@ from vikingbot.config.schema import SessionKey
from vikingbot.providers.registry import find_by_name
from vikingbot.sandbox.manager import SandboxManager
from vikingbot.utils.helpers import ensure_dir, ensure_non_empty_assistant_content
+from vikingbot.utils.session_paths import (
+ find_exact_child,
+ portable_session_name,
+)
T = TypeVar("T")
@@ -152,10 +157,55 @@ class SessionManager:
return lock
def _get_session_path(self, session_key: SessionKey) -> Path:
- return self.sessions_dir / f"{session_key.safe_name()}.jsonl"
+ return self.sessions_dir / f"{portable_session_name(session_key)}.jsonl"
+
+ def _get_legacy_session_path(self, session_key: SessionKey) -> Path | None:
+ """Return the pre-portability path when it is a local path component."""
+ filename = f"{session_key.safe_name()}.jsonl"
+ path = self.sessions_dir / filename
+ if path.parent != self.sessions_dir:
+ return None
+ return path
+
+ def _find_legacy_session_path(self, session_key: SessionKey) -> Path | None:
+ """Find a legacy file without accepting another folded SessionKey."""
+ candidate = self._get_legacy_session_path(session_key)
+ if candidate is None:
+ return None
+
+ exact = find_exact_child(self.sessions_dir, candidate.name)
+ if exact is not None:
+ return exact
+ if not candidate.exists():
+ return None
+
+ # A normalizing filesystem may expose the same logical filename with a
+ # different spelling. Accept it only when its persisted identity agrees.
+ try:
+ with open(candidate, encoding="utf-8") as stream:
+ data = json.loads(stream.readline())
+ raw_session_key = data.get("session_key_fields")
+ persisted_key = (
+ SessionKey.model_validate(raw_session_key)
+ if isinstance(raw_session_key, dict)
+ else SessionKey.from_safe_name(data.get("session_key"))
+ )
+ except Exception:
+ return None
+ return candidate if persisted_key == session_key else None
+
+ def _find_session_path(self, session_key: SessionKey) -> Path | None:
+ """Prefer the portable path while accepting existing legacy files."""
+ path = self._get_session_path(session_key)
+ if path.exists():
+ return path
+ legacy_path = self._get_legacy_session_path(session_key)
+ if legacy_path is not None and legacy_path != path:
+ return self._find_legacy_session_path(session_key)
+ return None
def has_persisted(self, session_key: SessionKey) -> bool:
- return self._get_session_path(session_key).exists()
+ return self._find_session_path(session_key) is not None
def get_or_create(self, key: SessionKey, skip_heartbeat: bool = False) -> Session:
"""
@@ -184,10 +234,7 @@ class SessionManager:
if self.sandbox_manager:
from vikingbot.utils.helpers import ensure_session_workspace
- if self.sandbox_manager.config.mode == "shared":
- workspace_path = self.sandbox_manager.workspace / "shared"
- else:
- workspace_path = self.sandbox_manager.workspace / key.safe_name()
+ workspace_path = self.sandbox_manager.get_workspace_path(key)
ensure_session_workspace(workspace_path)
# Initialize sandbox
@@ -207,9 +254,8 @@ class SessionManager:
def _load(self, session_key: SessionKey) -> Session | None:
"""Load a session from disk."""
- path = self._get_session_path(session_key)
-
- if not path.exists():
+ path = self._find_session_path(session_key)
+ if path is None:
return None
try:
@@ -218,7 +264,7 @@ class SessionManager:
created_at = None
session_key_from_metadata = None
- with open(path) as f:
+ with open(path, encoding="utf-8") as f:
for line in f:
line = line.strip()
if not line:
@@ -233,8 +279,11 @@ class SessionManager:
if data.get("created_at")
else None
)
- session_key_from_metadata = SessionKey.from_safe_name(
- data.get("session_key")
+ raw_session_key = data.get("session_key_fields")
+ session_key_from_metadata = (
+ SessionKey.model_validate(raw_session_key)
+ if isinstance(raw_session_key, dict)
+ else SessionKey.from_safe_name(data.get("session_key"))
)
else:
messages.append(data)
@@ -248,9 +297,7 @@ class SessionManager:
metadata=metadata,
)
except Exception as e:
- raise RuntimeError(
- f"Failed to load session from {path}: {e}"
- ) from e
+ raise RuntimeError(f"Failed to load session from {path}: {e}") from e
async def save(self, session: Session) -> None:
"""Save a session to disk."""
@@ -264,21 +311,32 @@ class SessionManager:
def _save_unlocked(self, session: Session) -> None:
"""Persist a session while holding the per-session lock."""
path = self._get_session_path(session.key)
-
- with open(path, "w") as f:
- # Write metadata first
- metadata_line = {
- "_type": "metadata",
- "session_key": session.key.safe_name(),
- "created_at": session.created_at.isoformat(),
- "updated_at": session.updated_at.isoformat(),
- "metadata": session.metadata,
- }
- f.write(json.dumps(metadata_line, ensure_ascii=False) + "\n")
-
- # Write messages
- for msg in session.messages:
- f.write(json.dumps(msg, ensure_ascii=False) + "\n")
+ temporary = path.with_name(f".{path.name}.{uuid.uuid4().hex}.tmp")
+ try:
+ with open(temporary, "w", encoding="utf-8") as f:
+ # Write metadata first. Keep the logical SessionKey unchanged.
+ metadata_line = {
+ "_type": "metadata",
+ "session_key": session.key.safe_name(),
+ "session_key_fields": session.key.model_dump(mode="json"),
+ "created_at": session.created_at.isoformat(),
+ "updated_at": session.updated_at.isoformat(),
+ "metadata": session.metadata,
+ }
+ f.write(json.dumps(metadata_line, ensure_ascii=False) + "\n")
+
+ for msg in session.messages:
+ f.write(json.dumps(msg, ensure_ascii=False) + "\n")
+ temporary.replace(path)
+ finally:
+ temporary.unlink(missing_ok=True)
+
+ # A successful canonical write completes the lazy legacy migration.
+ legacy_path = self._find_legacy_session_path(session.key)
+ if legacy_path == path:
+ legacy_path = None
+ if legacy_path is not None:
+ legacy_path.unlink(missing_ok=True)
self._cache[session.key] = session
@@ -334,12 +392,15 @@ class SessionManager:
# Remove from cache
self._cache.pop(key, None)
- # Remove file
- path = self._get_session_path(key)
- if path.exists():
- path.unlink()
- return True
- return False
+ # Remove both representations in case migration was interrupted.
+ deleted = False
+ legacy_path = self._find_legacy_session_path(key)
+ paths = {self._get_session_path(key), legacy_path}
+ for path in paths:
+ if path is not None and path.exists():
+ path.unlink()
+ deleted = True
+ return deleted
def list_sessions(self) -> list[dict[str, Any]]:
"""
@@ -348,27 +409,40 @@ class SessionManager:
Returns:
List of session info dicts.
"""
- sessions = []
+ sessions_by_key: dict[SessionKey, dict[str, Any]] = {}
for path in self.sessions_dir.glob("*.jsonl"):
try:
- with open(path) as f:
+ with open(path, encoding="utf-8") as f:
first_line = f.readline().strip()
if first_line:
data = json.loads(first_line)
if data.get("_type") == "metadata":
- session_key = SessionKey.from_safe_name(data.get("session_key"))
- metadata = data.get("metadata", {})
- sessions.append(
- {
- "key": session_key,
- "created_at": data.get("created_at"),
- "updated_at": data.get("updated_at"),
- "metadata": metadata,
- "path": str(path),
- }
+ raw_session_key = data.get("session_key_fields")
+ session_key = (
+ SessionKey.model_validate(raw_session_key)
+ if isinstance(raw_session_key, dict)
+ else SessionKey.from_safe_name(data.get("session_key"))
)
+ metadata = data.get("metadata", {})
+ session_info = {
+ "key": session_key,
+ "created_at": data.get("created_at"),
+ "updated_at": data.get("updated_at"),
+ "metadata": metadata,
+ "path": str(path),
+ }
+ existing = sessions_by_key.get(session_key)
+ canonical_path = self._get_session_path(session_key)
+ if existing is None or (
+ path == canonical_path and Path(existing["path"]) != canonical_path
+ ):
+ sessions_by_key[session_key] = session_info
except Exception:
continue
- return sorted(sessions, key=lambda x: x.get("updated_at", ""), reverse=True)
+ return sorted(
+ sessions_by_key.values(),
+ key=lambda x: x.get("updated_at") or "",
+ reverse=True,
+ )
diff --git a/bot/vikingbot/tests/unit/test_openviking_session_retention.py b/bot/vikingbot/tests/unit/test_openviking_session_retention.py
index 1703a66f1..733ee225f 100644
--- a/bot/vikingbot/tests/unit/test_openviking_session_retention.py
+++ b/bot/vikingbot/tests/unit/test_openviking_session_retention.py
@@ -6,6 +6,7 @@ from vikingbot.agent.loop import AgentLoop
from vikingbot.config.schema import SessionKey
from vikingbot.hooks.base import HookContext
from vikingbot.hooks.builtins.openviking_hooks import OpenVikingCompactHook
+from vikingbot.openviking_mount.session_state import make_openviking_storage_session_id
from vikingbot.session.manager import Session
@@ -51,7 +52,7 @@ async def test_session_context_commit_uses_turn_budget_retention():
assert result["success"] is True
assert commit_calls == [
{
- "session_id": session_key.safe_name(),
+ "session_id": make_openviking_storage_session_id(session_key.safe_name()),
"keep_recent_count": 0,
"retention_mode": "turn_budget",
"keep_recent_turn_count": 3,
diff --git a/bot/vikingbot/utils/session_paths.py b/bot/vikingbot/utils/session_paths.py
new file mode 100644
index 000000000..aacd21b34
--- /dev/null
+++ b/bot/vikingbot/utils/session_paths.py
@@ -0,0 +1,149 @@
+"""Portable filesystem names derived from logical Bot session keys."""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+ from vikingbot.config.schema import SessionKey
+
+
+_WINDOWS_UNSAFE_CHARS = frozenset('<>:"/\\|?*%')
+_WINDOWS_INVALID_CHARS = _WINDOWS_UNSAFE_CHARS - {"%"}
+_WINDOWS_RESERVED_STEMS = frozenset(
+ {
+ "CON",
+ "PRN",
+ "AUX",
+ "NUL",
+ *(f"COM{index}" for index in range(1, 10)),
+ *(f"LPT{index}" for index in range(1, 10)),
+ }
+)
+# Leave room for file extensions and atomic-write suffixes below NAME_MAX=255.
+_MAX_COMPONENT_BYTES = 180
+_LONG_NAME_HASH_LENGTH = 16
+
+
+def _percent_encode(character: str) -> str:
+ return "".join(f"%{byte:02X}" for byte in character.encode("utf-8", errors="surrogatepass"))
+
+
+def _escaped_path_component(value: str) -> tuple[str, list[str]]:
+ chunks: list[str] = []
+ for index, character in enumerate(value):
+ codepoint = ord(character)
+ is_control = codepoint < 32 or codepoint == 127
+ is_surrogate = 0xD800 <= codepoint <= 0xDFFF
+ is_trailing_windows_char = index == len(value) - 1 and character in {".", " "}
+ if (
+ character not in _WINDOWS_UNSAFE_CHARS
+ and not is_control
+ and not is_surrogate
+ and not is_trailing_windows_char
+ ):
+ chunks.append(character)
+ else:
+ chunks.append(_percent_encode(character))
+
+ candidate = "".join(chunks)
+ stem = candidate.split(".", 1)[0].rstrip(" .").upper()
+ if stem in _WINDOWS_RESERVED_STEMS and candidate:
+ candidate = f"{_percent_encode(candidate[0])}{candidate[1:]}"
+ chunks = [candidate]
+ return candidate, chunks
+
+
+def _hashed_path_component(value: str, candidate: str, chunks: list[str]) -> str:
+ digest = hashlib.sha256(value.encode("utf-8", errors="surrogatepass")).hexdigest()
+ suffix = f"~{digest[:_LONG_NAME_HASH_LENGTH]}"
+ if len(f"{candidate}{suffix}".encode("utf-8", errors="surrogatepass")) <= (
+ _MAX_COMPONENT_BYTES
+ ):
+ return f"{candidate}{suffix}"
+
+ remaining = _MAX_COMPONENT_BYTES - len(suffix)
+ prefix: list[str] = []
+ for chunk in chunks:
+ chunk_size = len(chunk.encode("utf-8", errors="surrogatepass"))
+ if chunk_size > remaining:
+ break
+ prefix.append(chunk)
+ remaining -= chunk_size
+ return f"{''.join(prefix).rstrip(' .')}{suffix}"
+
+
+def portable_path_component(value: str) -> str:
+ """Return a collision-resistant path component for supported filesystems.
+
+ The logical value is not changed. Only its filesystem representation is
+ escaped, using UTF-8 percent encoding for Windows-reserved characters,
+ controls, literal percent signs, and trailing spaces or periods. A digest
+ of the original UTF-8 bytes prevents collisions on case-insensitive and
+ Unicode-normalizing filesystems.
+ """
+ candidate, chunks = _escaped_path_component(value)
+ return _hashed_path_component(value, candidate, chunks)
+
+
+def is_windows_safe_path_component(value: str) -> bool:
+ """Return whether an existing logical identifier can be a Windows path component."""
+ if not value or value in {".", ".."}:
+ return False
+ if len(value.encode("utf-8", errors="surrogatepass")) > _MAX_COMPONENT_BYTES:
+ return False
+ if value.endswith((".", " ")):
+ return False
+
+ for character in value:
+ codepoint = ord(character)
+ if (
+ character in _WINDOWS_INVALID_CHARS
+ or codepoint < 32
+ or codepoint == 127
+ or 0xD800 <= codepoint <= 0xDFFF
+ ):
+ return False
+
+ stem = value.split(".", 1)[0].rstrip(" .").upper()
+ return stem not in _WINDOWS_RESERVED_STEMS
+
+
+def find_exact_child(parent: Path, name: str) -> Path | None:
+ """Find an existing child without case-folded or normalized path lookup."""
+ candidate = parent / name
+ if candidate.parent != parent:
+ return None
+ try:
+ return next((child for child in parent.iterdir() if child.name == name), None)
+ except FileNotFoundError:
+ return None
+
+
+def portable_session_name(session_key: SessionKey) -> str:
+ """Return the canonical filesystem name for a logical session key."""
+ return portable_path_component(session_key.safe_name())
+
+
+def workspace_name(session_key: SessionKey, sandbox_mode: Any, *, portable: bool) -> str:
+ """Return a workspace directory name for the configured sandbox mode."""
+ mode = str(getattr(sandbox_mode, "value", sandbox_mode))
+ if mode == "shared":
+ return "shared"
+ logical_name = session_key.channel_key() if mode == "per-channel" else session_key.safe_name()
+ return portable_path_component(logical_name) if portable else logical_name
+
+
+def resolve_workspace_path(parent: Path, session_key: SessionKey, sandbox_mode: Any) -> Path:
+ """Prefer a portable workspace while reusing a safe existing legacy one."""
+ canonical = parent / workspace_name(session_key, sandbox_mode, portable=True)
+ if canonical.exists():
+ return canonical
+
+ legacy_name = workspace_name(session_key, sandbox_mode, portable=False)
+ if "/" in legacy_name or "\\" in legacy_name:
+ return canonical
+ legacy = find_exact_child(parent, legacy_name)
+ return legacy if legacy is not None and legacy != canonical else canonical