Initial import of NousResearch/hermes-agent

2026-05-31 09:36:58 +08:00
commit d73ff9b0fb
4188 changed files with 1614916 additions and 0 deletions
@@ -0,0 +1,473 @@
+# Telegram DM User-Managed Multi-Session Topics Implementation Plan
+
+> **For Hermes:** Use test-driven-development for implementation. Use subagent-driven-development only after this plan is split into small reviewed tasks.
+
+**Goal:** Add an opt-in Telegram DM multi-session mode where Telegram user-created private-chat topics become independent Hermes session lanes, while the root DM becomes a system lobby.
+
+**Architecture:** Rely on Telegram's native private-chat topic UI. Users create new topics with the `+` button; Hermes maps each `message_thread_id` to a separate session lane. Hermes does not create topics for normal `/new` flow and does not try to manage topic lifecycle beyond activation/status, root-lobby behavior, and restoring legacy sessions into a user-created topic.
+
+**Tech Stack:** Hermes gateway, Telegram Bot API 9.4+, python-telegram-bot adapter, SQLite SessionDB / side tables, pytest.
+
+---
+
+## 1. Product decisions
+
+### Accepted
+
+- PR-quality implementation: migrations, tests, docs, backwards compatibility.
+- Use SQLite persistence, not JSON sidecars.
+- Live status suffixes in topic titles are out of MVP.
+- Topic title sync/editing is out of MVP except future-compatible storage if cheap.
+- User creates Telegram topics manually through the Telegram bot interface.
+- `/new` does **not** create Telegram topics.
+- Root/main DM becomes a system lobby after activation.
+- Existing Telegram behavior remains unchanged until the feature is activated/enabled.
+- Migration of old sessions is supported through `/topic` listing and `/topic <session_id>` restore inside a user-created topic.
+
+### Telegram API assumptions verified from Bot API docs
+
+- `getMe` returns bot `User` fields:
+  - `has_topics_enabled`: forum/topic mode enabled in private chats.
+  - `allows_users_to_create_topics`: users may create/delete topics in private chats.
+- `createForumTopic` works for private chats with a user, but MVP does not rely on it for normal flow.
+- `Message.message_thread_id` identifies a topic in private chats.
+- `sendMessage` supports `message_thread_id` for private-chat topics.
+- `pinChatMessage` is allowed in private chats.
+
+---
+
+## 2. Target UX
+
+### 2.1 Activation from root/main DM
+
+User sends:
+
+```text
+/topic
+```
+
+Hermes:
+
+1. calls Telegram `getMe`;
+2. verifies `has_topics_enabled` and `allows_users_to_create_topics`;
+3. enables multi-session topic mode for this Telegram DM user/chat;
+4. sends an onboarding message;
+5. pins the onboarding message if configured;
+6. shows old/unlinked sessions that can be restored into topics.
+
+Suggested onboarding text:
+
+```text
+Multi-session mode is enabled.
+
+Create new Hermes chats with the + button in this bot interface. Each Telegram topic is an independent Hermes session, so you can work on different tasks in parallel.
+
+This main chat is reserved for system commands, status, and session management.
+
+To restore an old session:
+1. Use /topic here to see unlinked sessions.
+2. Create a new topic with the + button.
+3. Send /topic <session_id> inside that topic.
+```
+
+### 2.2 Root/main DM after activation
+
+Root DM is a system lobby.
+
+Allowed/system commands include at least:
+
+- `/topic`
+- `/status`
+- `/sessions` if available
+- `/usage`
+- `/help`
+- `/platforms`
+
+Normal user prompts in root DM do not enter the agent loop. Reply:
+
+```text
+This main chat is reserved for system commands.
+
+To chat with Hermes, create a new topic using the + button in this bot interface. Each topic works as an independent Hermes session.
+```
+
+`/new` in root DM does not create a session/topic. Reply:
+
+```text
+To start a new parallel Hermes chat, create a new topic with the + button in this bot interface.
+
+Each topic is an independent Hermes session. Use /new inside a topic only if you want to replace that topic's current session.
+```
+
+### 2.3 First message in a user-created topic
+
+When a user creates a Telegram topic and sends the first message there:
+
+1. Hermes receives a Telegram DM message with `message_thread_id`.
+2. Hermes derives the existing thread-aware `session_key` from `(platform=telegram, chat_type=dm, chat_id, thread_id)`.
+3. If no binding exists, Hermes creates a fresh Hermes session for this topic lane and persists the binding.
+4. The message runs through the normal agent loop for that lane.
+
+### 2.4 `/new` inside a non-main topic
+
+`/new` remains supported but replaces the session attached to the current topic lane.
+
+Hermes should warn:
+
+```text
+Started a new Hermes session in this topic.
+
+Tip: for parallel work, create a new topic with the + button instead of using /new here. /new replaces the session attached to the current topic.
+```
+
+### 2.5 `/topic` in root/main DM after activation
+
+Shows:
+
+- mode enabled/disabled;
+- last capability check result;
+- whether intro message is pinned if known;
+- count of known topic bindings;
+- list of old/unlinked sessions.
+
+Example:
+
+```text
+Telegram multi-session topics are enabled.
+
+Create new Hermes chats with the + button in this bot interface.
+
+Unlinked previous sessions:
+1. 2026-05-01 Research notes — id: abc123
+2. 2026-04-30 Deploy debugging — id: def456
+3. Untitled session — id: ghi789
+
+To restore one:
+1. Create a new topic with the + button.
+2. Open that topic.
+3. Send /topic <id>
+```
+
+### 2.6 `/topic` inside a non-main topic
+
+Without args, show the current topic binding:
+
+```text
+This topic is linked to:
+Session: Research notes
+ID: abc123
+
+Use /new to replace this topic with a fresh session.
+For parallel work, create another topic with the + button.
+```
+
+### 2.7 `/topic <session_id>` inside a non-main topic
+
+Restore an old/unlinked session into the current user-created topic.
+
+Behavior:
+
+1. reject if not in Telegram DM topic;
+2. verify session belongs to the same Telegram user/chat or is a safe legacy root DM session for this user;
+3. reject if session is already linked to another active topic in MVP;
+4. `SessionStore.switch_session(current_topic_session_key, target_session_id)`;
+5. upsert binding with `managed_mode = restored`;
+6. send two messages into the topic:
+   - session restored confirmation;
+   - last Hermes assistant message if available.
+
+Example:
+
+```text
+Session restored: Research notes
+
+Last Hermes message:
+...
+```
+
+---
+
+## 3. Persistence model
+
+Use SQLite, but topic-mode schema changes are **explicit opt-in migrations**, not automatic startup reconciliation.
+
+Important rollback-safety rule:
+
+- upgrading Hermes and starting the gateway must not create Telegram topic-mode tables or columns;
+- old/default Telegram behavior must keep working on the existing `state.db`;
+- the first `/topic` activation path calls an idempotent explicit migration, then enables topic mode for that chat;
+- if activation fails before the migration is needed, the database remains in the pre-topic-mode shape.
+
+### 3.1 No eager `sessions` table mutation for MVP
+
+Do **not** add `chat_id`, `chat_type`, `thread_id`, or `session_key` columns to `sessions` as part of ordinary `SessionDB()` startup. The existing declarative `_reconcile_columns()` mechanism would add them eagerly on every process start, which violates the managed-migration requirement.
+
+For MVP, keep origin/session-lane data in topic-specific side tables created only by the explicit `/topic` migration. Legacy unlinked sessions can be discovered conservatively from existing data (`source = telegram`, `user_id = current Telegram user`) plus absence from topic bindings.
+
+If future PRs need richer origin metadata for all gateway sessions, introduce it behind a separate explicit migration/command or a compatibility-reviewed schema bump.
+
+### 3.2 Explicit `/topic` migration API
+
+Add an idempotent method such as:
+
+```python
+def apply_telegram_topic_migration(self) -> None: ...
+```
+
+It creates only topic-mode side tables/indexes and records:
+
+```text
+state_meta.telegram_dm_topic_schema_version = 1
+```
+
+This method is called from `/topic` activation/status paths before reading or writing topic-mode state. It is not called from generic `SessionDB.__init__`, gateway startup, CLI startup, or auto-maintenance.
+
+### 3.3 `telegram_dm_topic_mode`
+
+Stores per-user/chat activation state. Created only by `apply_telegram_topic_migration()`.
+
+Suggested fields:
+
+- `chat_id` primary key
+- `user_id`
+- `enabled`
+- `activated_at`
+- `updated_at`
+- `has_topics_enabled`
+- `allows_users_to_create_topics`
+- `capability_checked_at`
+- `intro_message_id`
+- `pinned_message_id`
+
+### 3.4 `telegram_dm_topic_bindings`
+
+Stores Telegram topic/thread to Hermes session binding. Created only by `apply_telegram_topic_migration()`.
+
+Suggested fields:
+
+- `chat_id`
+- `thread_id`
+- `user_id`
+- `session_key`
+- `session_id`
+- `managed_mode`
+  - `auto`
+  - `restored`
+  - `new_replaced`
+- `linked_at`
+- `updated_at`
+
+Recommended constraints:
+
+- primary key `(chat_id, thread_id)`;
+- unique index on `session_id` for MVP to prevent one session linked to multiple topics;
+- index `(user_id, chat_id)` for status/listing.
+
+### 3.5 Unlinked session semantics
+
+For MVP, a session is unlinked if:
+
+- `source = telegram`;
+- `user_id = current Telegram user`;
+- no row in `telegram_dm_topic_bindings` has `session_id = session_id`.
+
+This is intentionally conservative until a future explicit migration adds richer cross-platform origin metadata.
+
+Never dedupe by title.
+
+---
+
+## 4. Config
+
+Suggested config block:
+
+```yaml
+platforms:
+  telegram:
+    extra:
+      multisession_topics:
+        enabled: false
+        mode: user_managed_topics
+        root_chat_behavior: system_lobby
+        pin_intro_message: true
+```
+
+Notes:
+
+- `enabled: false` means existing Telegram behavior is unchanged.
+- Activation via `/topic` may create per-chat enabled state only if global config permits it.
+- `root_chat_behavior: system_lobby` is the MVP behavior for activated chats.
+
+---
+
+## 5. Command behavior summary
+
+### `/topic` root/main DM
+
+- If not activated: capability check, activate, send/pin onboarding, list unlinked sessions.
+- If activated: show status and unlinked sessions.
+
+### `/topic` non-main topic
+
+- Show current binding.
+
+### `/topic <session_id>` root/main DM
+
+Reject with instructions:
+
+```text
+Create a new topic with the + button, open it, then send /topic <session_id> there to restore this session.
+```
+
+### `/topic <session_id>` non-main topic
+
+Restore that session into this topic if ownership/linking checks pass.
+
+### `/new` root/main DM when activated
+
+Reply with instructions to use the `+` button. Do not enter agent loop.
+
+### `/new` non-main topic
+
+Create a new session in the current topic lane, persist/update binding, warn that `+` is preferred for parallel work.
+
+### Normal text root/main DM when activated
+
+Reply with system-lobby instruction. Do not enter agent loop.
+
+### Normal text non-main topic
+
+Normal Hermes agent flow for that topic's session lane.
+
+---
+
+## 6. PR breakdown
+
+### PR 1 — Explicit topic-mode schema migration
+
+**Goal:** Add rollback-safe SQLite support for Telegram topic mode without mutating `state.db` on ordinary upgrade/startup.
+
+**Files likely touched:**
+
+- `hermes_state.py`
+- tests under `tests/`
+
+**Tests first:**
+
+1. opening an old/current DB with `SessionDB()` does not create topic-mode tables or `sessions` origin columns;
+2. calling `apply_telegram_topic_migration()` creates `telegram_dm_topic_mode` and `telegram_dm_topic_bindings` idempotently;
+3. migration records `state_meta.telegram_dm_topic_schema_version = 1`.
+
+### PR 2 — Topic mode activation and binding APIs
+
+**Goal:** Add SQLite persistence for activation and topic bindings.
+
+**Tests first:**
+
+1. enable/check mode row round-trips;
+2. binding upsert and lookup by `(chat_id, user_id, thread_id)`;
+3. linked sessions are excluded from unlinked list.
+
+### PR 3 — `/topic` activation/status command
+
+**Goal:** Implement root activation/status/listing behavior.
+
+**Tests first:**
+
+1. `/topic` in root checks `getMe` capabilities and records activation;
+2. capability failure returns readable instructions;
+3. activated root `/topic` lists unlinked sessions.
+
+### PR 4 — System lobby behavior
+
+**Goal:** Prevent root chat from entering agent loop after activation.
+
+**Tests first:**
+
+1. normal text in activated root returns lobby instruction;
+2. `/new` in activated root returns `+` button instruction;
+3. non-activated root behavior is unchanged.
+
+### PR 5 — Auto-bind user-created topics
+
+**Goal:** First message in non-main topic creates/uses an independent session lane.
+
+**Tests first:**
+
+1. new topic message creates binding with `auto_created`;
+2. repeated topic message reuses same binding/lane;
+3. two topics in same DM do not share sessions.
+
+### PR 6 — Restore legacy sessions into a topic
+
+**Goal:** Implement `/topic <session_id>` in non-main topics.
+
+**Tests first:**
+
+1. root `/topic <id>` rejects with instructions;
+2. topic `/topic <id>` switches current topic lane to target session;
+3. restore rejects sessions from other users/chats;
+4. restore rejects already-linked sessions;
+5. restore emits confirmation and last Hermes assistant message.
+
+### PR 7 — `/new` inside topic updates binding
+
+**Goal:** Keep existing `/new` semantics but persist topic binding replacement.
+
+**Tests first:**
+
+1. `/new` in topic creates a new session for same topic lane;
+2. binding updates to `managed_mode = new_replaced`;
+3. response includes guidance to use `+` for parallel work.
+
+### PR 8 — Docs and polish
+
+**Goal:** Document the feature and Telegram setup.
+
+**Files likely touched:**
+
+- `website/docs/user-guide/messaging/telegram.md`
+- maybe `website/docs/user-guide/sessions.md`
+
+Docs must explain:
+
+- BotFather/Telegram settings for topic mode and user-created topics;
+- `/topic` activation;
+- root system lobby;
+- using `+` for new parallel chats;
+- restoring old sessions with `/topic <id>` inside a topic;
+- limitations.
+
+---
+
+## 7. Testing / quality gates
+
+Run targeted tests after each TDD cycle, then broader tests before completion.
+
+Suggested commands after inspection confirms test paths:
+
+```bash
+python -m pytest tests/test_hermes_state.py -q
+python -m pytest tests/gateway/ -q
+python -m pytest tests/ -o 'addopts=' -q
+```
+
+Do not ship without verifying disabled-feature backwards compatibility.
+
+---
+
+## 8. Definition of done for MVP
+
+- `/topic` activates/checks Telegram DM multi-session mode.
+- Root DM becomes a system lobby after activation.
+- Onboarding message tells users to create new chats with the Telegram `+` button.
+- Onboarding message can be pinned in private chat.
+- User-created topics automatically become independent Hermes session lanes.
+- `/new` in root gives instructions, not a new agent run.
+- `/new` in a topic creates a new session in that topic and warns that `+` is preferred for parallel work.
+- `/topic` in root lists unlinked old sessions.
+- `/topic <session_id>` inside a topic restores that session and sends confirmation + last Hermes assistant message.
+- Ownership checks prevent restoring other users' sessions.
+- Already-linked sessions are not restored into a second topic in MVP.
+- Existing Telegram behavior is unchanged when the feature is disabled.
+- Tests and docs are included.
@@ -0,0 +1,434 @@
+# s6-overlay Supervision for Per-Profile Gateways in Docker — Implementation Plan
+
+> **Status: shipped.** Phases 0–5 landed via PR
+> [NousResearch/hermes-agent#30136](https://github.com/NousResearch/hermes-agent/pull/30136)
+> in May 2026. This document is preserved as a post-implementation reference
+> for the architecture and the resolved design questions. The phase-by-phase
+> TDD walkthrough (≈2,800 lines) and the v2/v3 re-validation preambles have
+> been removed — the canonical implementation history is the PR commit log
+> (`git log --oneline a957ef083..a6f7171a5 -- 'docker/*' 'hermes_cli/service_manager.py' …`).
+> Open Questions are collapsed into a single Decision Log table; full
+> deliberations live in PR review comments.
+
+**Goal:** Replace `tini` with s6-overlay as PID 1 in the Hermes Docker image so
+that the main hermes process, the dashboard, and dynamically-created
+per-profile gateways all run as supervised services (auto-restart on crash,
+clean shutdown, signal forwarding, zombie reaping). Preserve every existing
+`docker run …` invocation pattern — including interactive TUI.
+
+**Architecture:** s6-overlay's `/init` is the container ENTRYPOINT, running
+s6-svscan as PID 1. Main hermes and the dashboard are declared as static
+s6-rc services at image build time. Per-profile gateways — which users create
+*after* the image is built (`hermes profile create coder` →
+`coder gateway start`) — are registered dynamically by writing service
+directories under a scandir watched by s6-svscan. A `ServiceManager` protocol
+abstracts the install/start/stop/restart surface across the init systems we
+care about (systemd on Linux host, launchd on macOS host, Scheduled Tasks on
+native Windows host, s6 inside container) and adds a second tier for runtime
+service registration that only s6 implements.
+
+**Tech Stack:**
+
+- [s6-overlay](https://github.com/just-containers/s6-overlay) v3.2.3.0
+  (noarch + per-arch tarballs ~15 MB). SHA256-pinned via build ARGs;
+  multi-arch via `TARGETARCH` (amd64 → `x86_64`, arm64 → `aarch64`).
+- Debian 13.4 base image (unchanged).
+- [hadolint](https://github.com/hadolint/hadolint) for the Dockerfile +
+  [shellcheck](https://github.com/koalaman/shellcheck) for entrypoint scripts.
+- Python subprocess wrappers for `s6-svc`, `s6-svstat`, `s6-svscanctl`.
+- Existing systemd/launchd/windows surface in `hermes_cli/gateway.py` and
+  `hermes_cli/gateway_windows.py`.
+
+**Scope:**
+
+- Container-only (host-side systemd/launchd/windows behavior is preserved,
+  not modified).
+- s6-overlay only (no pure-Python fallback).
+- Architecture A (s6 owns PID 1; tini is removed).
+- Interactive TUI must keep working:
+  `docker run -it --rm nousresearch/hermes-agent:latest --tui`.
+- Dynamic registration is limited to per-profile gateways — one service per
+  profile, created when a profile is created, torn down when deleted. A
+  `gateway-default` slot is always registered for the root HERMES_HOME
+  profile so `hermes gateway start` (no `-p`) has somewhere to land.
+
+**Out of scope:**
+
+- Host-side dynamic supervision (systemd-run / launchd transient plists) —
+  not needed.
+- Pure-Python supervisor fallback — not needed.
+- Arbitrary user-defined supervised processes inside the container — only
+  profile gateways.
+- Migration of existing per-profile systemd unit generation to s6 on the
+  host side.
+- Non-Docker container runtimes (Podman rootless validated reactively).
+- UX polish around in-container profile lifecycle (e.g. a nice status view
+  of all supervised profile gateways) — deferred to follow-up.
+
+---
+
+## Background From The Codebase
+
+> **Note on line numbers:** This section refers to functions and structures
+> by name only. Use `grep -n 'def <name>' <file>` to locate anything below
+> if you need the current line.
+
+### Pre-s6 container init (what we replaced)
+
+The original `Dockerfile` declared
+`ENTRYPOINT [ "/usr/bin/tini", "-g", "--", "/opt/hermes/docker/entrypoint.sh" ]`.
+tini was PID 1, reaped zombies, forwarded SIGTERM to the process group. The
+old `docker/entrypoint.sh`:
+
+1. `gosu` privilege drop from root → `hermes` UID.
+2. Copied `.env.example`, `cli-config.yaml.example`, `SOUL.md` into
+   `$HERMES_HOME` if missing.
+3. Synced bundled skills via `tools/skills_sync.py`.
+4. Optionally backgrounded `hermes dashboard` in a subshell when
+   `HERMES_DASHBOARD=1` — **not supervised**, no restart.
+5. `exec hermes "$@"` — tini's sole direct child.
+
+Known limitations: dashboard crash → stays dead; dashboard fails at startup →
+silent; gateway crash → dashboard dies too. The May 4, 2026 decision was
+"leave as is" because nothing in the container needed supervision then.
+Adding per-profile gateway supervision changed that.
+
+### ServiceManager surface (what we wrapped, not refactored)
+
+All init-system logic lives in **`hermes_cli/gateway.py`** (~5,400 LOC at
+re-validation). The systemd/launchd code is ~1,500 lines of that, plus a
+separate **`hermes_cli/gateway_windows.py`** (~690 LOC) for Windows
+Scheduled Tasks.
+
+| Layer | Systemd functions | Launchd functions | Windows functions |
+|---|---|---|---|
+| **Detection** | `supports_systemd_services()`, `_systemd_operational()`, `_wsl_systemd_operational()`, `_container_systemd_operational()` | `is_macos()` | `is_windows()`, `gateway_windows.is_installed()` |
+| **Paths** | `get_systemd_unit_path(system)`, `get_service_name()` | `get_launchd_plist_path()`, `get_launchd_label()` | `gateway_windows.get_task_name()`, `get_task_script_path()`, `get_startup_entry_path()` |
+| **Install/lifecycle** | `systemd_install(force, system, run_as_user)`, `systemd_uninstall(system)`, `systemd_start/stop/restart(system)` | `launchd_install(force)`, `launchd_uninstall/start/stop/restart` | `gateway_windows.install/uninstall/start/stop/restart` |
+| **Probes** | `_probe_systemd_service_running(system)`, `_read_systemd_unit_properties(system)`, `_wait_for_systemd_service_restart`, `_recover_pending_systemd_restart` | `_probe_launchd_service_running()` | `gateway_windows.is_task_registered()`, `_pid_exists` helper |
+| **D-Bus plumbing** | `_ensure_user_systemd_env`, `_user_systemd_socket_ready`, `_user_systemd_private_socket_path`, `get_systemd_linger_status` | — | — |
+| **Unit/plist generation** | `generate_systemd_unit(system, run_as_user)`, `systemd_unit_is_current`, `refresh_systemd_unit_if_needed` | plist templating in `launchd_install` | `_build_gateway_cmd_script`, `_build_startup_launcher`, `_write_task_script` |
+
+Container-relevant callers outside `gateway.py`:
+
+- `hermes_cli/status.py` — gained an `s6` branch for in-container runs.
+- `hermes_cli/profiles.py` — `create_profile` / `delete_profile` register and
+  unregister with s6 inside the container (no-op on host).
+- `hermes_cli/doctor.py` — `_check_gateway_service_linger` skips on s6, and a
+  new "Service Supervisor" section reports main-hermes / dashboard /
+  profile-gateway counts via the ServiceManager.
+- `hermes_cli/gateway.py::gateway_command` — the
+  `elif is_container():` rejection arms that refused gateway lifecycle
+  operations were removed; the `_dispatch_via_service_manager_if_s6` helper
+  intercepts start/stop/restart and routes them through s6.
+
+### Per-profile gateway spawning
+
+`hermes gateway start`, `coder gateway start` (profile alias), and
+`hermes -p <profile> gateway start` all spawn a gateway process scoped to a
+given profile. See
+[Profiles: Running Gateways](https://hermes-agent.nousresearch.com/docs/user-guide/profiles#running-gateways).
+On host, lifecycle is managed via per-profile systemd units
+(`hermes-gateway-<profile>.service`); inside the container, an s6 service at
+`/run/service/gateway-<name>/` is registered when the profile is created and
+torn down when it's deleted.
+
+**Persistence across container restart:** `/run/service/` is tmpfs —
+service registrations are wiped when the container restarts. Profile
+directories at `/opt/data/profiles/<name>/` live on the persistent VOLUME,
+and each one records its gateway's last state in `gateway_state.json`.
+`/etc/cont-init.d/02-reconcile-profiles` walks the persistent profiles on
+every container boot, recreates the s6 service slots via
+`hermes_cli/container_boot.py`, and auto-starts those whose last recorded
+state was `running`. Profiles whose last state was `stopped`,
+`startup_failed`, `starting`, or absent get their slot recreated in the
+`down` state and wait for explicit user action. `docker restart` is therefore
+invisible to a user with running profile gateways: they come back up;
+stopped ones stay stopped.
+
+### s6-overlay constraints
+
+- **Root/non-root model:** `/init` runs as root to set up the supervision
+  tree, install signal handlers, and run the stage2 hook that does
+  `usermod`/`chown`. Each supervised service drops to UID 10000 via
+  `s6-setuidgid hermes` in its `run` script. The per-service `s6-supervise`
+  monitor stays root so it can signal its child regardless of UID. Net
+  effect: hermes and all its subprocesses run as UID 10000 exactly as
+  before; only the supervision tree itself runs as root.
+- v3.2.3.0 has limited non-root support for running `/init` itself as
+  non-root — some tools (`fix-attrs`, `logutil-service`) assume root. We
+  don't hit this because `/init` runs as root.
+- Scandir hard cap: `services_max` default 1000, configurable to 160,000.
+- `/command/with-contenv` sources `/run/s6/container_environment/*` into
+  service env — convenient for passing `HERMES_HOME` etc.
+- s6 signal semantics: service crash triggers `s6-supervise` restart after
+  1s; override with a `finish` script.
+- Zombie reaping: PID 1 (s6-svscan) reaps all zombies non-blockingly on
+  SIGCHLD. Any subagent subprocess spawned by the main hermes process is
+  reaped automatically.
+
+---
+
+## Key Design Decisions
+
+### D1. s6-overlay replaces tini entirely
+
+Container ENTRYPOINT is `/init`, PID 1 is s6-svscan. The main hermes
+process, the dashboard, and every per-profile gateway run as supervised
+services. This is a single breaking change to the container contract.
+
+### D2. Main hermes is an s6 service with container-exit semantics
+
+The contract "container exits when `hermes` exits" is preserved via a
+service `finish` script that writes to
+`/run/s6-linux-init-container-results/exitcode` and calls
+`/run/s6/basedir/bin/halt`. All five supported invocations work:
+
+| `docker run <image> …` | Behavior |
+|---|---|
+| (no args) | `hermes` with no args, container exits when hermes exits |
+| `chat -q "..."` | `hermes chat -q "..."`, container exits with hermes exit code |
+| `sleep infinity` | `sleep infinity` directly (long-lived sandbox mode) |
+| `bash` | interactive `bash` directly |
+| `docker run -it … --tui` | interactive Ink TUI with real TTY — see D9 |
+
+`docker/main-wrapper.sh` detects whether `$1` is an executable on PATH and
+routes either to "run this as a one-shot main service" or "wrap with
+hermes".
+
+### D3. Static services at build time; dynamic (per-profile) services at runtime
+
+s6 offers two mechanisms:
+
+- **s6-rc** (declarative, compile-then-swap): used for main hermes and the
+  dashboard — they're known at image build time.
+- **scandir** (drop a directory + `s6-svscanctl -a`): used for per-profile
+  gateways — profiles are user-created after the image is built.
+
+Per-profile gateway service dirs live at `/run/service/gateway-<profile>/`
+(tmpfs, hermes-writable). s6-svscan picks them up on rescan.
+
+### D4. ServiceManager protocol with two methods for runtime registration
+
+Host paths (systemd, launchd, Windows Scheduled Tasks) need only
+install/start/stop/restart of pre-declared services. Inside the container,
+we additionally need to register services at runtime when a profile is
+created. The protocol exposes this directly:
+
+```python
+class ServiceManager(Protocol):
+    kind: ServiceManagerKind  # "systemd" | "launchd" | "windows" | "s6" | "none"
+
+    # Lifecycle of an already-declared service
+    def start(self, name: str) -> None: ...
+    def stop(self, name: str) -> None: ...
+    def restart(self, name: str) -> None: ...
+    def is_running(self, name: str) -> bool: ...
+
+    # Runtime registration (container-only; hosts raise NotImplementedError)
+    def supports_runtime_registration(self) -> bool: ...
+    def register_profile_gateway(
+        self, profile: str, *,
+        extra_env: dict[str, str] | None = None,
+    ) -> None: ...
+    def unregister_profile_gateway(self, profile: str) -> None: ...
+    def list_profile_gateways(self) -> list[str]: ...
+```
+
+Systemd, launchd, and Windows backends raise `NotImplementedError` on the
+registration methods. Only the s6 backend implements them. Callers check
+`supports_runtime_registration()` before calling.
+
+The scope is intentionally narrow: it's specifically "register/unregister a
+profile gateway," not a general-purpose process-management API.
+
+### D5. Per-profile gateway service spec is fixed, not user-provided
+
+Every profile gateway has the same command shape
+(`hermes -p <profile> gateway run`, or `hermes gateway run` for the default
+profile). The s6 backend generates the `run` script from a fixed template
+given the profile name — no arbitrary command list. This keeps the API
+surface tight and prevents callers from accidentally registering
+non-gateway services.
+
+Port selection is governed by the profile's `config.yaml`
+(`[gateway] port = …`) — the single source of truth. (The original plan
+proposed a Python-side SHA-256 port allocator with a 600-port range; it was
+retired during PR review because it was dead code through the entire stack.)
+
+### D6. Add detect_service_manager() alongside supports_systemd_services()
+
+`supports_systemd_services()` stays as-is (host code paths unchanged). A new
+`detect_service_manager() -> Literal["systemd", "launchd", "windows", "s6", "none"]`
+composes existing detection functions (`is_macos()`, `is_windows()`,
+`supports_systemd_services()`, `is_container()` + `_s6_running()`) and adds
+an s6 branch for container detection. Host call sites continue to use the
+existing functions; container-only code (the profile hooks) uses the new one.
+
+`_s6_running()` probes `/proc/1/comm` (world-readable) and
+`/run/s6/basedir`. The earlier `/proc/1/exe` probe was root-only readable
+and silently failed for the unprivileged hermes user (UID 10000), making
+the entire runtime-registration path inert in production — caught in PR
+review.
+
+### D7. Wrap existing systemd/launchd/windows functions, don't rewrite them
+
+`SystemdServiceManager` / `LaunchdServiceManager` / `WindowsServiceManager`
+are thin adapters over the existing `systemd_*` / `launchd_*` module-level
+functions in `hermes_cli/gateway.py` and the
+`gateway_windows.install/uninstall/start/stop/restart/is_installed`
+functions in `hermes_cli/gateway_windows.py`. We get the abstraction
+without rewriting ~2,200 LOC of working code.
+
+### D8. Profile create/delete hooks register/unregister the s6 service
+
+When `hermes profile create <name>` runs inside the container, the
+profile-creation code path calls
+`ServiceManager.register_profile_gateway(<name>)` if
+`supports_runtime_registration()` is True. When `hermes profile delete
+<name>` runs, it calls `unregister_profile_gateway(<name>)`. On host, both
+calls are no-ops (registration not supported; existing systemd unit
+generation continues to handle install/uninstall).
+
+Existing per-profile `hermes -p <profile> gateway start/stop/restart` CLI
+commands continue to work — in the container they dispatch to
+`ServiceManager.start/stop/restart("gateway-<profile>")`, which translates
+to `s6-svc -u`/`-d`/`-t` on the service dir.
+
+`hermes gateway start` (no `-p`) targets a special `gateway-default` slot
+that's always registered by the cont-init reconciler. Its run script omits
+the `-p` flag and runs against the root `$HERMES_HOME` profile.
+
+`--all` lifecycle (`hermes gateway stop --all`, `... restart --all`)
+iterates `mgr.list_profile_gateways()` through s6 so s6's `want up`/`want
+down` flips correctly. Without this, `--all` fell through to `pkill`
+followed by s6-supervise auto-restart — net effect: kick instead of stop.
+
+### D9. Interactive TUI bypasses s6 service-mode and runs as CMD for TTY passthrough
+
+`docker run -it --rm <image> --tui` needs a real TTY connected to container
+stdin/stdout for Ink raw-mode keyboard input, cursor control, and SIGWINCH.
+Running the TUI as a normal s6 service fails because s6-supervise
+disconnects service stdio from the container TTY (documented:
+[s6-overlay#230](https://github.com/just-containers/s6-overlay/issues/230)).
+
+**The pattern:** s6-overlay's `/init` execs a CMD as the container's "main
+program" after the supervision tree is up. The CMD inherits
+stdin/stdout/stderr from `/init` — which in `-it` mode is the container
+TTY. The stage2 hook detects the TUI case and short-circuits the
+main-hermes service so the hermes CMD becomes that main program.
+
+```sh
+# In docker/stage2-hook.sh
+_is_tui_invocation() {
+    for arg in "$@"; do
+        case "$arg" in --tui|-T) return 0 ;; esac
+    done
+    case "${HERMES_TUI:-}" in 1|true|TRUE|yes) return 0 ;; esac
+    if [ -t 0 ] && [ $# -eq 0 ]; then return 0; fi
+    return 1
+}
+```
+
+And in `docker/s6-rc.d/main-hermes/run`:
+
+```sh
+if [ -f /var/run/s6/container_environment/HERMES_TUI_MODE ]; then
+    exec sleep infinity   # s6-overlay will exec CMD as the TTY-connected main
+fi
+exec s6-setuidgid hermes hermes ${HERMES_ARGS:-}
+```
+
+In TUI mode main hermes is effectively unsupervised (same as the pre-s6
+behavior with tini — acceptable because the user is interactively
+present). Dashboard and profile gateways still get full s6 supervision via
+their separate services.
+
+The integration test `test_tty_passthrough_to_container` uses `tput cols`
+and `COLUMNS=123` as the probe.
+
+---
+
+## Risk Register
+
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+| Phase 2 breaks a downstream user's Dockerfile that `FROM`s ours | Medium | Medium | Release notes call out ENTRYPOINT change; the test harness (`tests/docker/`) gives high confidence in behavior parity |
+| TUI TTY passthrough fails on some Docker versions | Low | High | Harness includes `test_tty_passthrough_to_container` as a hard gate; fallback plan = s6-fdholder ([s6-overlay#230](https://github.com/just-containers/s6-overlay/issues/230) Solution 2) |
+| s6-overlay non-root quirks (logutil-service, fix-attrs) bite us | Low | Low | Supervisor runs as root, services drop — sidesteps these issues |
+| Podman rootless UID mapping confuses s6 | Medium | Low | Documented as supported, fix reactively; a Podman + Docker environment is stood up for validation |
+| Test harness is flaky (docker daemon issues, timing) | Medium | Low | Generous timeouts; skip when docker unavailable; polling helpers replace fixed sleeps in `test_container_restart.py` |
+| Profile gateway crash loop masks a real config error | Low | Medium | s6 `finish` script `max_restarts` cap (planned follow-up); operators see crash-looping logs in `$HERMES_HOME/logs/gateways/<profile>/` |
+| Dockerfile+entrypoint drift from linter (hadolint/shellcheck) reveals latent bugs | Low | Low | CI lint jobs catch them; fix or document ignore with rationale |
+| Stale `gateway.pid` from a dead container collides with an unrelated live PID in the restarted container | Low | Medium | Cont-init reconciliation removes `gateway.pid` and `processes.json` from every profile dir on boot, before any new gateway starts |
+| `docker restart` silently loses per-profile gateway registrations (tmpfs scandir wiped) | High (without mitigation) | High | Cont-init reconciliation re-registers from persistent `$HERMES_HOME/profiles/` and auto-starts those last seen `running`; outcome recorded to `$HERMES_HOME/logs/container-boot.log` (size-bounded, rotates to `.1` at 256 KiB) |
+| A `running` gateway that's actually broken auto-restarts into a crash loop after every container restart | Low | Medium | s6 `finish` script `max_restarts` cap (planned); follow-up: `hermes doctor` alerts when N consecutive container restarts ended in `startup_failed` |
+| `_s6_running()` detection works as root but silently fails for unprivileged hermes user, making runtime-registration path inert | High (without mitigation) | High | **Caught in PR review.** Detection now probes `/proc/1/comm` (world-readable) + `/run/s6/basedir`. Docker integration tests refactored to `docker exec -u hermes` so the realistic runtime user is exercised |
+| `s6-svscanctl` from hermes hits EACCES on the root-owned control FIFO | Medium | Medium | `02-reconcile-profiles` chowns `/run/service/.s6-svscan/{control,lock}` to hermes after stage1 creates them |
+| Per-service `supervise/control` FIFO is root-owned by s6-supervise, blocking `s6-svc` from hermes | Known | Medium | Surfaced cleanly as `S6CommandError` (with rc + stderr) instead of raw `CalledProcessError`. Permission fix tracked as a follow-up (small SUID helper, polling chown loop in cont-init.d, or replace `s6-svc` with `down`-marker manipulation) |
+
+---
+
+## Decision Log
+
+| # | Question | Decision |
+|---|---|---|
+| OQ1 | Gate Phase 2 behind env var? | Ship directly (Hermes is pre-1.0; users can pin the previous image) |
+| OQ2 | s6 root model | Root `/init`, drop per-service via `s6-setuidgid hermes` |
+| OQ3 | Dashboard opt-in mechanism | Always declared as an s6 service; `03-dashboard-toggle` cont-init script writes a `down` marker when `HERMES_DASHBOARD` is unset so `s6-svstat` reports the slot's real state |
+| OQ4 | Podman rootless | Supported, fix reactively |
+| OQ5 | Service naming | `gateway-<profile>` (matches pre-existing `hermes-gateway-<profile>.service` systemd convention) |
+| OQ6 | — (retired; no subagent gateways in scope) | — |
+| OQ7 | Resource limits per profile gateway | Defer (no per-cgroup limits; rely on the container's overall limit) |
+| OQ8 | Log persistence | `$HERMES_HOME/logs/gateways/<profile>/`. The log path is sourced from runtime `$HERMES_HOME` via `with-contenv`, NOT Python-substituted at registration time |
+| OQ9 | TUI passthrough | Trust the documented [s6-overlay#230](https://github.com/just-containers/s6-overlay/issues/230) Solution 1; harness includes a TTY passthrough hard-gate test |
+
+**Post-merge additions from PR #30136 review:**
+
+- **Multi-arch tarballs:** `TARGETARCH` mapped to `x86_64` / `aarch64`;
+  per-arch tarball fetched via `curl` because `ADD` doesn't honor BuildKit
+  args.
+- **SHA256 verification:** all three tarballs (noarch, symlinks, per-arch)
+  pinned via build ARGs and verified with `sha256sum -c` against a single
+  checksum file (avoids hadolint DL4006 piped-shell warning).
+- **`gateway-default` slot:** always registered by the reconciler so
+  `hermes gateway start` (no `-p`) has somewhere to land.
+- **Friendly lifecycle errors:** `GatewayNotRegisteredError` and
+  `S6CommandError` translate `CalledProcessError` into actionable CLI
+  messages.
+- **Atomic publication in the reconciler:** mirrors
+  `register_profile_gateway`'s tmp+rename pattern.
+- **`container-boot.log` rotation:** 256 KiB soft cap, rotated to `.1`.
+- **`port` parameter retired:** allocator + kwarg were dead code through
+  the entire stack; `config.yaml` is the single source of truth.
+
+---
+
+## Verification Checklist
+
+- [x] Test harness (`tests/docker/`) passes against the s6 image
+- [x] hadolint + shellcheck run green in CI
+- [x] `docker run -it --rm hermes-agent --tui` starts the Ink TUI with
+      working keyboard input, cursor control, and resize (SIGWINCH)
+- [x] Dashboard crashes are recovered by s6 within ~2s
+- [x] `hermes profile create test` inside a container creates
+      `/run/service/gateway-test/`
+- [x] `hermes -p test gateway start` inside a container dispatches through s6
+- [x] `hermes -p test gateway stop` inside a container cleanly stops via s6
+- [x] `hermes profile delete test` inside a container removes
+      `/run/service/gateway-test/`
+- [x] Profile gateway logs persist at
+      `$HERMES_HOME/logs/gateways/test/current`
+- [x] `hermes status` inside the container shows `Manager: s6`
+- [x] `hermes gateway start` (no `-p`) inside a container targets
+      `gateway-default` and runs against the root profile
+- [x] `hermes gateway stop --all` / `... restart --all` iterate every
+      profile gateway under s6 instead of pkill-then-supervise-restart
+- [x] `docker restart` survives per-profile gateway registrations via the
+      cont-init reconciler; running gateways come back up, stopped ones
+      stay down
+- [x] Multi-arch image builds for both `linux/amd64` and `linux/arm64`
+- [x] s6-overlay tarballs are SHA256-verified at build time
+- [x] No systemd/launchd host-side functions were modified (only wrapped)
+- [x] `hermes gateway install/start/stop` on Linux host and macOS host
+      behave identically to pre-change
@@ -0,0 +1,152 @@
+# ACP Zed Pre-Edit Approval Diffs Implementation Plan
+
+> **For Hermes:** Use subagent-driven-development skill to implement this plan task-by-task.
+
+**Goal:** Gate file mutations in ACP/Zed behind explicit pre-edit approval with a structured diff, similar to Codex/Kimi edit review behavior.
+
+**Architecture:** Hermes already renders edit diffs after tools run. This PR adds a pre-mutation permission gate for file mutation tools. Intercept `write_file`, `patch`, and eventually `skill_manage` before they mutate disk; compute proposed old/new content; send ACP `session/request_permission` with `kind="edit"` and diff content; only execute the mutation after approval. Rejections return a clear tool result and leave files unchanged.
+
+**Tech Stack:** Python, ACP `request_permission`, `FileEditToolCallContent` / `acp.tool_diff_content`, Hermes file tools, pytest with temp files.
+
+---
+
+### Task 1: Confirm current ACP diff/permission schema
+
+Run:
+
+```bash
+/home/nour/.hermes/hermes-agent/venv/bin/python - <<'PY'
+from acp.schema import RequestPermissionRequest, ToolCallUpdate
+import acp, inspect
+print(RequestPermissionRequest.model_fields)
+print(ToolCallUpdate.model_fields)
+print(inspect.signature(acp.tool_diff_content))
+PY
+```
+
+Record actual field names. Do not rely on stale examples.
+
+### Task 2: Add denied-write test
+
+**Objective:** A rejected `write_file` must not mutate disk.
+
+**Files:**
+- Create/modify: `tests/acp/test_edit_approval.py`
+
+Test shape:
+
+```python
+def test_write_file_rejected_by_acp_permission_does_not_mutate(tmp_path):
+    path = tmp_path / "demo.txt"
+    path.write_text("old")
+
+    # Install fake ACP edit approval callback returning reject_once.
+    # Invoke the same interception function that the terminal/tool path will call.
+
+    result = maybe_gate_file_edit(
+        tool_name="write_file",
+        args={"path": str(path), "content": "new"},
+        approval_requester=fake_reject,
+    )
+
+    assert path.read_text() == "old"
+    assert "rejected" in result.lower()
+```
+
+The exact function name will be created in Task 4.
+
+### Task 3: Add approved-write test
+
+**Objective:** Approved writes proceed and include diff content in permission request.
+
+Assert:
+
+- fake requester received tool call `kind == "edit"`
+- content includes diff block for `demo.txt`
+- after approval, file content is changed
+
+### Task 4: Implement edit proposal computation
+
+**Files:**
+- Create: `acp_adapter/edit_approval.py`
+
+Add pure helpers first:
+
+```python
+@dataclass
+class EditProposal:
+    path: str
+    old_text: str | None
+    new_text: str
+    title: str
+
+
+def proposal_for_write_file(args: dict[str, Any]) -> EditProposal:
+    path = str(args["path"])
+    old_text = Path(path).read_text(encoding="utf-8") if Path(path).exists() else None
+    new_text = str(args.get("content", ""))
+    return EditProposal(path=path, old_text=old_text, new_text=new_text, title=f"Edit {path}")
+```
+
+For `patch`, start with replace-mode only. V4A/multi-file patches can be a second task or second PR if too risky.
+
+### Task 5: Implement ACP permission requester
+
+**Files:**
+- Modify: `acp_adapter/permissions.py` or new `acp_adapter/edit_approval.py`
+
+Build request with:
+
+```python
+acp.tool_diff_content(path=proposal.path, old_text=proposal.old_text, new_text=proposal.new_text)
+```
+
+Options:
+
+- allow once
+- reject once
+- optionally allow always/reject always only after policy storage exists
+
+Default deny on exception/cancel/timeout.
+
+### Task 6: Intercept file mutation tools before execution
+
+**Objective:** Ensure mutation cannot happen before approval.
+
+**Files:**
+- Likely modify: `model_tools.py` or `acp_adapter/server.py` session-context tool wrapper
+
+Do not bury this inside post-execution `acp_adapter/events.py`; that is too late.
+
+Preferred design:
+
+- set an ACP session contextvar around `agent.run_conversation(...)`
+- in the central tool execution path, before dispatching `write_file`/`patch`, call the ACP edit approval gate if contextvar exists
+- if rejected, return a normal tool result string like `{"success": false, "error": "Edit rejected by user"}`
+- if approved, continue to original tool implementation
+
+### Task 7: Expand patch coverage
+
+Add tests for:
+
+- `patch` replace mode approved/rejected
+- creating a new file via `write_file`
+- missing old string -> should fail before approval or return normal patch error, but must not mutate
+- permission requester exception -> deny and no mutation
+
+### Task 8: Verification
+
+Run:
+
+```bash
+scripts/run_tests.sh tests/acp/test_edit_approval.py tests/acp/test_events.py tests/acp/test_tools.py -q
+```
+
+Then run manual Zed verification:
+
+1. Ask Hermes ACP to edit a small file.
+2. Confirm Zed shows a diff before mutation.
+3. Reject and verify file unchanged.
+4. Approve and verify file changed.
+
+**Do not merge** without manual reject-path verification.