feat(gateway): add session workspace binding

[qWaitCrypto]

What does this PR do?

Adds session-scoped workspace binding for messaging gateway sessions.

Gateway users can now run /workspace <absolute-path> or /cwd <absolute-path> to bind the current chat/thread to a project directory. Subsequent agent turns in that gateway session resolve runtime cwd, context files, terminal commands, file tools, code execution, delegation hints, checkpoints, and runtime footer/status output against the bound workspace instead of the global terminal.cwd.

This keeps the existing default behavior unchanged when no workspace is bound, while making multi-chat and multi-repo gateway usage practical without running one bot process per project.

Related Issue

#37277

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Security fix
• Documentation update
• Tests (adding or improving test coverage)
• Refactor (no behavior change)
• New skill (bundled or hub)

Changes Made

• Added /workspace and /cwd gateway commands for showing, setting, and clearing the current session workspace.
• Persisted workspace cwd on gateway session state and SessionDB.sessions.cwd, including resume/session-switch handling.
• Added a session-context cwd resolver so gateway turns can expose their workspace without mutating process-wide environment variables.
• Routed workspace cwd through terminal/file/code/delegate tool resolution, destructive-command checkpoints, subdirectory hints, and runtime footer/status output.
• Added cleanup/sync handling for stale workspace directories and session-id changes after compression.
• Added English and Chinese gateway command messages.
• Added focused tests for workspace commands, runtime cwd resolution, file tool cwd fallback, terminal overrides, footer consistency, and checkpoint cwd handling.

How to Test

1. Run the focused test suite:

   env UV_CACHE_DIR=/tmp/uv-cache PYTHONPATH=/mnt/d/hermes-agent uv run --no-project --offline --with pytest==9.0.2 --with pytest-asyncio==1.3.0 --with pytest-timeout==2.4.0 --with httpx==0.28.1 --with python-dotenv==1.2.2 --with pyyaml==6.0.3 python -m pytest tests/agent/test_tool_executor_workspace_cwd.py tests/tools/test_file_tools_cwd_resolution.py tests/gateway/test_workspace_command.py tests/agent/test_runtime_cwd.py tests/tools/test_terminal_task_cwd.py tests/gateway/test_runtime_footer.py -q --tb=short

2. In a gateway session, run /workspace /absolute/path/to/project.

3. Ask the agent to read a relative file or run pwd; it should use the bound workspace.

4. Run /workspace clear and confirm the session returns to the global gateway cwd.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: WSL2 Ubuntu on Windows

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) - or N/A
• I've updated cli-config.yaml.example if I added/changed config keys - or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows - or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide - or N/A
• I've updated tool descriptions/schemas if I changed tool behavior - or N/A

Screenshots / Logs

Focused tests passed locally:

67 passed in 27.23s

[teknium1]

Thanks for this @qWaitCrypto — the use case is real and well-argued (one gateway bot serving multiple repos), and the writeup in #37277 is excellent.

Closing this one without merging, though, because most of it duplicates machinery that landed in the ~300 commits since your branch's base. The per-session cwd mechanism you're rebuilding already exists on main:

• agent/runtime_cwd.py has a _SESSION_CWD contextvar plus set_session_cwd() / clear_session_cwd(). Every cwd consumer (terminal, file tools, code/delegate, context-file discovery, footer/status) already resolves the per-session workspace through resolve_agent_cwd() / resolve_context_cwd().
• gateway/session_context.set_session_vars() already calls set_session_cwd(cwd) — that's exactly the seam the docstring on your base said "a future PR adds a contextvar arm at the set_session_vars seam, by design."
• The desktop/TUI gateway already ships the user-facing command: session.cwd.set -> _set_session_cwd(), which validates the dir, persists to SessionDB, and tears down the stale VM.

So merging this as-is would fork the cwd mechanism — it introduces a parallel workspace_cwd attribute, _register_gateway_workspace_override, and its own SessionDB sync, instead of using the canonical set_session_cwd() + update_session_cwd() that are now in place.

The one genuinely-missing piece is the messaging-gateway slash command: gateway/run.py has no /workspace /cwd handler, so Telegram/Discord/Slack can't do what the TUI already can. That's the worthwhile kernel here, and it's a small handler on top of the existing plumbing rather than a 695-line change.

I'd rather rebuild that thin slice fresh against current main than land a stale parallel implementation. Crediting your design — #37277 captured the requirement and surfaces exactly right. Sorry for the wasted diff; the infra moving underneath you is on us, not you.