better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/bot-mode.md

@@ -0,0 +1,309 @@
+---
+title: "Bot Mode"
+description: "Turn your Hermes profiles into a roster of named Bots — each with its own chat, role, model, memory, skills, and avatar. Bots run routines, share group chats, and message each other."
+---
+
+# Bot Mode
+
+**Bot Mode** turns your [Hermes profiles](./profiles.md) into a roster of named **Bots**. Each Bot has its own role, model, memory, skills, and avatar; Bots run recurring routines, deliberate together in group chats, and message each other directly. Build a specialist Bot once and it is there forever, one click away.
+
+Bot Mode ships **built into the [desktop app](./desktop.md)** and is **on by default** — no install needed. It appears as a **Bots** tab next to Sessions in the left sidebar, with a **Routines** tile docked beside the conversation while the Bots tab is active.
+
+:::tip A Bot is a profile
+There is no new primitive to learn: a Bot **is** a Hermes profile — isolated config, memory, skills, credentials, and chat history under `~/.hermes/profiles/<name>/`. Bot Mode is a UI over that primitive, so everything you do in it is visible from the CLI too: `hermes -p <bot> chat` opens the same agent, and Bot routines appear in `hermes cron list`. No core patches, no background daemons, no extra storage.
+:::
+
+## The Bots pane
+
+The roster shows one row per agent profile: avatar, latest-message preview, and timestamp.
+
+- **Click a Bot** to land in its chat — every Bot has a canonical, persistent **Bot Chat** conversation that is created (and pinned) the moment the Bot is born. A row click always opens that Bot Chat (the same conversation the row previews), even when you have other tabs open for the Bot; those tabs stay open beside it. In the tab strip the Bot Chat is captioned with the Bot's name, so two open Bots are told apart at a glance.
+- **Active now** — the roster's activity filter includes the owner of the focused live turn, Bots that wrote within the last 90 seconds, and Bots with a recent worker heartbeat. A connected gateway alone does not mean a Bot is working.
+- **Search** filters the roster as you type.
+- **Hide a Bot** — right-click a row → **Hide Bot** to take a Bot you don't use out of the roster and the Active-now strip. Hiding is display-only: @mentions still resolve, group-chat memberships are untouched, and routines keep running. Once at least one Bot is hidden, an **eye toggle** appears in the pane header — click it to reveal hidden Bots dimmed in place, then right-click → **Unhide Bot** to bring one back. Hidden Bots never toast, but they accumulate unread activity silently and the eye badges a dot so you know something happened. Hidden state is saved in the Bot's profile metadata, so it follows the Bot to every desktop connected to that backend.
+
+:::note The canonical Bot Chat is a forever-chat
+Typing `/new` (or `/reset`) inside a Bot's canonical chat would fork the relationship into a scratch session — the one thing Bot Mode promises never happens. The composer reroutes it to `/compact` instead: fresh working context, same conversation. Regular sessions on the same profile keep full `/new` freedom.
+
+Archiving a Bot Chat from the sidebar retires it: the next click on the Bot starts a fresh conversation that becomes the new canonical Bot Chat. The retired chat stays archived and hidden — its history is preserved in the database, but it is no longer reachable from the Bot or the archive view. The automatic idle-archive sweep (`sessions.auto_archive`) never retires a Bot Chat; only an explicit archive does.
+:::
+
+### Organize bots into sections
+
+Sections are folders you make yourself — **Clients**, **Team**, whatever fits — as a second axis beside the automatic per-gateway grouping. With no sections created the roster is the plain list it always was.
+
+- **Create one** from the pane's **+** menu → **New section**, or right-click a Bot → **Move to section** → **New section…** (that files the Bot into it as you create it).
+- **File a Bot** by dragging its row onto a section — the target highlights while you hover, and **Esc** cancels the drag — or right-click → **Move to section** and pick one. **Remove from section** puts it back in **Unassigned**.
+- **Rename, reorder, or delete** a section from its heading's right-click menu (or the **⋯** that appears on hover); double-click a heading to rename. Headings fold like the gateway headings do.
+- **Deleting a section never deletes Bots** — they return to **Unassigned**, and the toast offers **Undo**. No confirmation is asked.
+
+Membership is stored in each Bot's profile metadata (`ui_meta`), so a Bot's section follows it to every desktop connected to that backend. When the roster shows more than one gateway, sections nest inside each gateway's bucket.
+
+## Creating a Bot
+
+Hit **New Agent** in the roster. The quick path is three fields — **Name**, **Title**, **Description** — and the Bot exists in seconds, introducing itself as the first message of its new Bot Chat.
+
+An **Advanced** disclosure opens the full capabilities surface:
+
+- **Clone from an existing profile** — start from another Bot's config, skills, SOUL, and memory, or pick **Fresh profile** for a clean start.
+- **Create empty** — skip the bundled skills entirely for a minimal profile.
+- **Model & provider pin** — give the Bot its own model. Any provider/model pair Hermes knows about works, and different Bots can run on different models side by side. Leave it unset to inherit from the launch profile.
+- **Custom SOUL.md** — the Bot's persona and standing instructions.
+- **Per-skill, per-toolset, and per-MCP-server enablement** — tick exactly the capabilities this specialist needs.
+- **Shared keys** — by default the new Bot shares one OAuth/token pool with the main profile, so credential refreshes cannot invalidate each other. (Older gateways copy credentials instead — still functional, just forked.)
+
+### Choosing which machine it lives on ("Create on")
+
+With more than one connection registered in [Settings → Connections](./multi-connection-desktop.md), the New Agent dialog grows a **Create on** picker. Pick a device and the profile is created on **that** machine's backend — your window never switches gateways. The new Bot then appears in the roster as a Connections Bot (with an `@name-device` handle when the name exists on several machines), and chatting with it routes to its own machine.
+
+With a single connection (the common case) the picker is hidden and the Bot is created on the machine you're connected to — exactly the old behavior.
+
+Remote-creation notes:
+
+- **Clone source** is a profile of the *target* machine (its `default`) — a remote box doesn't have your local profiles to clone.
+- The live Capabilities tab pins to the target machine's backend, so skills, tools, and MCP servers you configure during creation land on the machine the Bot will live on. (Older desktop builds fall back to staged Skills/Tools/MCP checklists for remote targets; both read the target machine's catalog.)
+- Cancelling the dialog discards the draft profile on whichever machine it was created.
+
+**Edit Profile** (right-click a Bot) reopens the same surface on the live profile any time: avatar, title, description, model pin, skills, toolsets, MCP servers, and the full SOUL.md.
+
+**Duplicate** (right-click) makes a full clone of a Bot — config, skills, SOUL.md, memory, and its look. **Delete Profile** permanently removes one, behind the same destructive confirmation the desktop's profile menu uses; the default profile cannot be deleted.
+
+## Avatars
+
+Every Bot gets a face:
+
+- **Blob faces** (default) — a deterministic soft-body face drawn from the Bot's name: same name, same face, forever. While you type a name in New Agent the face follows it live; hit **Randomize** to re-roll, **Lock face** to keep the one you like even if the name changes, or pin one of the six silhouettes (round, organic, boxy, nub, cloud, sun) while everything else still comes from the name.
+- **Geometric faces** — the classic 7 shapes × 10 colors. During a focused live turn, the owning Bot leans and looks upward with three animated dots, then eases back to idle when the turn ends. Ownership includes the connection, so same-named Bots on different gateways do not borrow the pose. Background workers keep their existing working animation; photos, blob faces and sigils keep their own rendering.
+- **An uploaded image** — any picture you like.
+- **An AI-generated portrait** — when an image backend is configured, generated in place (this rides the standard `image.generate` RPC and works over both local and remote gateways).
+- **A pixel pet** — a companion from the [petdex gallery](./features/pets.md) that bounces beside the avatar while the Bot is busy. Run `hermes pets` in a terminal to explore the gallery.
+
+A Bot's look, title, and description are stored in the profile's metadata on the backend, so the same Bot appears the same way on every desktop connected to that backend.
+
+## Routines
+
+The **Routines** pane attaches recurring tasks to the Bot that does them — "summarize my inbox every morning" lives next to the Bot responsible for it. The pane docks beside the chat only while the Bots tab is active and steps aside when you switch back to Sessions (older desktop builds keep it always visible). A structured schedule picker builds the schedule (frequency first, then only the detail that matters), with an Advanced field exposing the raw Hermes schedule string.
+
+Routines are plain [Hermes cron jobs](./features/cron.md) namespaced `[bot:<name>] <routine>` — they also show up in `hermes cron list` and the core Cron page. Runs land in the Bot's own chat history, so the result is right where you would talk to that Bot anyway.
+
+## Groups and group chats
+
+Messages sent during a member turn queue behind the active room drive, including
+replies in the same thread. They do not interrupt that member or mark unseen
+messages as read. Stop cancels queued continuations and holds the members until
+resumed. A quiet room watches timed-out members for another 21 minutes after the
+foreground wait ends; this observation window does not extend the turn itself.
+Unresolved member failures remain visible in the collapsed Activity summary after
+the room settles. Expand Activity for the turn sequence; re-address the member to
+try again. An ambiguous submit failure is not automatically resubmitted.
+
+
+Right-click a local Bot → **Manage groups** to add or remove it from any number of group chats. Pick existing groups independently or create one inline. Local membership is stored in the Bot's backend-synced profile metadata, so it follows that profile across desktops; older profiles with one legacy group continue to work. Connections Bots join through the New Group Chat picker and remain source-qualified in the room's shared state.
+
+**Rooms follow your gateways, not one Desktop.** Each room's recent transcript, members, picture, and name are mirrored into the shared profile metadata of **every** gateway your Desktop is connected to, with per-gateway versioning so two Desktops writing at once merge instead of overwriting each other. Open Hermes Desktop on another machine against the same gateway (local network, Tailscale, anywhere) and the room appears with its history; gateway-only clients see it too. Rooms carry a durable internal identity, so renaming one changes just its display name everywhere, disbanding one removes it permanently on every client — even ones that were offline at the time — and recreating a same-name group starts a genuinely fresh room. If a gateway dies or is removed, nothing is lost: every connected Desktop keeps the full room locally and re-seeds any gateway it reconnects to. (The full orchestration log stays in each Desktop's local storage; the shared mirror is a bounded recent-history projection.)
+
+A group's identity is editable, at creation and after:
+
+- **New Group Chat** lets you set an optional **room picture** alongside the name — upload one from your device or generate one (when an image backend is configured), using the same pipeline as Bot avatars. The picture appears in the roster row (in place of the default group glyph) and leads the title in the room header.
+- The room header's **gear** button opens **Group settings**, where you can **rename** the group or set, replace, or remove its picture any time. A rename carries everything with it — the room log, each member's room session, memberships, and the picture — so no history is lost. Renaming to a name that's already taken is rejected rather than silently suffixed.
+
+Groups are standalone rows in the same activity-ordered roster as Bot DMs. A Bot keeps one DM row even when it belongs to several groups, while every group gets its own room row with member count, latest-message preview, timestamp, and needs-you state.
+
+Use the **Move up** and **Move down** arrows beside a room to choose its position among rooms. Until the first move, the existing pinned-first, recent-activity order is unchanged. After a move, room order is saved on this Desktop and survives reloads; new rooms follow the explicitly ordered rooms within their pinned or unpinned band. Moves cannot cross the pinned boundary, and filtering does not discard hidden rooms from the saved order. These controls reorder actual Group Chat rooms, not user-created Bot folders, and do not change membership or gateway ownership.
+
+**Open chat** on any group row (2–6 Bots) opens a shared room where the whole group coordinates:
+
+- **One visible conversation.** Public messages and each member's reply stay readable in arrival order, with the speaker's name and timestamp. Starting another topic does not collapse earlier replies. **Reply in thread** continues that topic without reordering the room; **Activity** is a secondary status view, not a replacement for messages. Private Bot Chats remain separate.
+- Your message triggers up to **three serial rounds** of member turns. @-mentioned Bots respond (everyone responds when nobody is mentioned); each Bot replies briefly or passes, and the room settles when a full round stays silent.
+- Teammates can hand off to the primary Bot with `@hermes`, including in older saved rooms; Bots on other gateways keep their device-qualified tags (for example, `@default-vera`).
+- Bots pull each other in with `@name`, and escalate real judgment calls to you with `@user` — the group row shows a **needs you** badge when that happens. Pending questions and command approvals also light that badge; resolving the last prompt clears only prompt attention, not an independent mention. Prompts follow a renamed room, while disbanding retires them even if a member's in-flight poll arrives later.
+- Hard caps (10 messages per send, 3 rounds) keep rooms from spinning.
+- Each member keeps its own persistent room session, so room context survives like any other conversation.
+- **Not every Bot replies to every message.** Speaking is each member's own choice — a Bot replies only when it has something new to add and passes otherwise, and @-mentioning specific members scopes the round to them. Expect the members you addressed (or whoever has something to say) to speak, and the rest to stay quiet.
+- **Rooms keep running when you close the Desktop.** When every member of a room lives on the same gateway, that gateway owns turn scheduling through a durable driver: closing Hermes Desktop (or losing its connection) does not stop a room mid-discussion, and the Desktop simply catches up from the room's log when it reconnects. `groups.capabilities` on the gateway reports `driver: true` when this applies. Rooms whose members span several machines are different: each member's turns run on its own gateway, and the cross-connection courier described under *Bot-to-bot messaging* still applies to them.
+- **Rooms can span machines.** The New Group Chat picker seats Bots from any registered connection; each member's turns run on its own machine, in its own room session there. Cross-machine members carry a device badge (`dixie · Mac Mini`) in the room and in other members' transcripts, and the disambiguated `@name-device` handle works in room mentions — so same-named agents on two machines never blur together.
+- **Plugins can watch members work.** The durable room log records `turn.started` and `turn.settled`; what a member does in between (tools, approvals, streamed text) is projected to plugins through the [`on_room_member_activity`](/user-guide/features/hooks#on_room_member_activity) hook with room, member and turn coordinates, so community clients can build tool cards and live member status on top of Group Chat without reading Hermes internals.
+
+## Bot-to-bot messaging
+
+Bots message each other with attribution, and you can hand work off from any chat:
+
+- **@mentions** — type `@researcher have a look at this` in any chat and the composer's `@` autocomplete helps you pick the right Bot; on send, the mention is resolved against the live roster and the active Bot is told exactly who you mean (profile, friendly name, and device for cross-connection Bots). The Bot then composes its own message and sends it with `message_agent` — your text is never forwarded verbatim, and the reply comes back attributed to that agent. An email address or an unknown `@` passes through untouched. Bots on other connected machines are reachable the same way: the Desktop relays the message over that connection's own socket (see *Bots across machines* below).
+- **Renamed Bots keep their tags in sync** — give a Bot a friendly name (the pencil in its chat header, or `hermes profile rename`) and it becomes taggable by that name: a Bot titled *Research Buddy* answers to `@research-buddy` (and `@researchbuddy`), in regular chats and in group rooms alike. The composer's `@` autocomplete offers the renamed tag and also matches when you type the old profile name, which keeps resolving too.
+- **Direct messages** — every Bot Chat carries the `message_agent` tool: a Bot messages a teammate by calling `message_agent(target="researcher", message="…")`. The tool validates the target against the live roster, prefixes the sender's `Message from 🤖 <sender> (@<sender>):` attribution automatically, and delivers into the teammate's canonical Bot Chat. Delivery is **fire-and-forget**: the sender gets an acknowledgement, finishes its turn, and the reply arrives later as a background completion notification. The message travels as a real parameter (nothing shell-interpreted — quotes, `$(...)`, and backticks arrive verbatim), and the Bot composes its own message rather than forwarding your words. The teammate roster — names **and roles** from each profile's title/description — is part of every Bot Chat's system prompt, so Bots know who does what before choosing a recipient. The tool exists **only** in canonical Bot Chat sessions on Bot-Mode-managed installs; regular chats, group-room member sessions, and CLI sessions never see it.
+
+Local messages also reach a Bot Chat that stays open in Desktop or the TUI. The receiving backend keeps ownership: it reads durable ingress on its existing notification poller, admits immediately when idle, or waits until the running turn and already queued human prompts finish. A `queued` acknowledgement confirms durable admission, **not** a completed reply. The target profile retains the delivery ID and receipt under `runtime/bot_live_delivery/`; `settled` confirms completion. A crashed or cancelled imported turn is not automatically replayed, and pending work pinned to a departed owner remains inspectable rather than being silently rerun. Do not resend a delivery whose outcome is unknown. Older backends without live-delivery capability retain the existing ownership refusal; restart that backend after upgrading.
+
+- **Staying silent** — a Bot that has nothing to add may end a turn with one of the [intentional silence tokens](./messaging/index.md#intentional-silence-tokens) (`[SILENT]`, `NO_REPLY`, …). The Bot Chat keeps that turn in its transcript but renders nothing, and a teammate that messaged it gets an empty reply instead of the token. Failed turns and prose that merely mentions a token are shown as-is.
+
+The backend teaches each Bot's canonical Bot Chat session the messaging protocol automatically at prompt-build time — including when a teammate opens it headlessly from the CLI. Only the canonical Bot Chat gets the protocol section; your regular sessions and your SOUL.md stay untouched. This is controlled by `agent.bot_mode_protocol` in `config.yaml` (default: on):
+
+```yaml
+agent:
+  bot_mode_protocol: true   # inject the bot-to-bot messaging protocol into canonical Bot Chats
+```
+
+:::note
+Bot-to-bot delivery is per-invocation: the receiving Bot picks the message up when it next runs. Live interrupt of a Bot mid-conversation is future work.
+:::
+
+### Failed turns retry safely
+
+Local one-shot delivery preserves the active-session refusal code separately from
+its human-readable message. `SESSION_NOT_OWNED` produces `target_busy`; an
+unreadable coordination registry is not mislabeled as another owner. Older local
+CLIs without the code marker still use the historical refusal wording.
+
+A failed delivery turn is retried at most once, and only when a retry can actually help. Transient failures (target runtime offline, delivery timeout, provider rate limit or server error) re-run the same Bot Chat session unchanged. A context-overflow failure also re-runs the same session — the retried turn compacts the over-threshold transcript via the standard context-compression pass before calling the model, so the retry fits where the original didn't. Auth, quota, and configuration failures never auto-retry: a second attempt cannot fix them and only burns quota, so the failure is surfaced immediately. A retried turn never starts a fresh session — your Bot Chat history and context stay intact.
+
+When a target has no live Desktop or TUI owner, local delivery opens that
+profile's canonical Bot Chat through a quiet CLI turn. The transport prefers
+the Hermes entrypoint beside the sending runtime's Python interpreter, so an
+unrelated or older `hermes` on a service's `PATH` cannot take precedence when
+that sibling entrypoint exists. `--in ~` selects the working directory; the
+explicit Bot Chat title is resolved in the target profile's session database.
+
+### When a delivery fails: typed reasons
+
+A failed bot turn or relay delivery carries a machine-readable `reason` code alongside the human error text, end to end: the target gateway classifies the failure (`provider_auth_or_access`, `provider_quota_limit`, `provider_rate_limit`, `provider_server_error`, `context_overflow`, `missing_config`, `model_unavailable`, `runtime_offline`, `queued_expired`, `delivery_timeout`, `target_busy`, `unknown`), the Desktop forwards it, and the sending agent's completion notification is tagged `[reason: <code>]` ahead of the error text. A calling agent can branch on the code — "sign in again" vs "retry later" — instead of parsing provider prose. The Desktop's needs-attention badge uses the same codes.
+
+### Messaging across connected machines (the Desktop relay)
+
+Every gateway you register in **Settings → Connections** — local, remote URL, SSH, Hermes Cloud, docker — is a persistent line the Desktop holds open, and Bot Mode uses those lines for messaging automatically. No extra setup:
+
+- **Rosters propagate on their own.** While the Desktop runs, it periodically tells each connected gateway which agents live on the *other* connections. Every Bot Chat's teammate roster then lists them ("Teammates on OTHER connected machines"), with names, roles, and which machine they're on — and the roster refreshes when agents appear, disappear, or get renamed (capability epoch).
+- **`message_agent` reaches them directly.** A Bot on your laptop messages the cloud agent with `message_agent(target="moxie", …)` exactly like a local teammate. If the same handle exists on several machines, disambiguate with `target="moxie@<connection>"` (the tool's error tells the Bot the exact forms). Delivery rides the Desktop: the sending gateway queues the message, the Desktop relays it to the target connection's own gateway, the target Bot runs a turn in its canonical Bot Chat, and the reply comes back to the sender as the same background completion notification local DMs use. Messages to different Bots are delivered side by side, so one Bot's long turn never delays another Bot's mail (or ages it past `bot_mode.envelope_ttl_seconds`); messages to the *same* Bot are delivered in order, one turn at a time.
+- **The Desktop is the courier.** Cross-connection delivery works while a Desktop that knows both connections is running (it holds the sockets and the credentials — gateways never see each other's auth). If the Desktop is closed mid-delivery, the sender's Bot is told the reply didn't arrive rather than left hanging. For always-on machine-to-machine messaging with no Desktop in the loop, register a peer (`hermes peer`, below) — the two routes coexist.
+
+### Bot-initiated DMs across machines (`hermes peer`)
+
+Bots on one machine can message Bots on **another machine's gateway** without any desktop in the loop. Register the other gateway as a *peer* (its API server URL + `API_SERVER_KEY`):
+
+```bash
+hermes peer add spark --url http://spark.lan:8377 --key <API_SERVER_KEY>
+hermes peer list
+hermes peer dm spark < /tmp/dm.txt        # message body from a file (nothing shell-interpreted)
+hermes peer dm spark/researcher < /tmp/dm.txt   # named profile on a multiplexed peer
+hermes peer run spark --idempotency-key ticket-123 < /tmp/long-task.txt
+hermes peer status spark run_abc123
+hermes peer stop spark run_abc123
+```
+
+`hermes peer dm` delivers into the remote agent's canonical Bot Chat over the peer's existing API server, runs one agent turn there, and prints the reply on stdout — the exact cross-machine twin of the local `hermes -p <bot> chat` command.
+
+Use `peer dm` only for short queries and receipts because it holds one HTTP
+connection until the turn finishes. For a long turn, `peer run` returns a
+`run_id` immediately; poll it with `peer status`. The run inherits the
+canonical Bot Chat transcript, and a stable `--idempotency-key` makes a retry
+return the original run instead of starting duplicate work. Use `peer stop`
+with that exact run ID to interrupt it without targeting another turn.
+
+Once a peer is registered, the messaging protocol taught to every Bot Chat (`agent.bot_mode_protocol`) automatically includes the peer roster, and `message_agent` accepts peer targets directly — `message_agent(target="spark/researcher", …)`, or `target="spark"` for the peer's main agent — so **your bots learn on their own** that teammates exist on other machines and how to reach them. Registering or removing a peer refreshes each Bot Chat's protocol on its next message (capability epoch).
+
+Requirements: the peer machine runs the `api_server` gateway platform with a strong `API_SERVER_KEY`; reachability is your network's business (LAN, Tailscale, VPN). The key is a credential and lives in `~/.hermes/.env` as `HERMES_PEER_<NAME>_KEY`; peer names/URLs live in `config.yaml` under `bot_peers`.
+
+:::note One-way reachability (NAT)
+Cross-gateway links are direct gateway-to-gateway connections — Desktop is a
+viewer, not a relay. A gateway behind home NAT can dial out to a public peer
+(laptop → VPS works), but the reverse direction has no inbound route
+(VPS → home fails) unless your network provides one. If your Group Chat spans
+a NAT boundary, put the room's authority on the host every participant can
+reach (typically the public VPS), or bridge the network with Tailscale/VPN.
+:::
+
+### Transferring hosted room authority
+
+Authority takeover is an **operator recovery procedure**, not an atomic handover.
+Use the existing JSON-RPC methods `groups.promote` and `groups.demote` on the
+appropriate gateway. There are no `groups.peer.promote` or `groups.peer.demote`
+methods; `groups.capabilities` lists the methods your gateway supports.
+
+:::warning Fence the old writer before promotion
+Before sending `confirm: true`, establish that the previous authority **cannot
+commit**, and keep that fence in place until it has been demoted. Stop its
+room-writing processes and prevent automatic restart, or use an equivalent
+infrastructure fence. A network timeout, disconnecting Desktop, or `groups.stop`
+is not proof: the old gateway may still be running, and stopping a turn does not
+revoke room authority. If you cannot establish the fence, do not promote.
+:::
+
+1. **Check replica coverage.** On the replacement gateway, inspect
+   `groups.replica_state` with `{"room_id":"ROOM_ID"}` and compare `last_seq`
+   with `latest_seq`. Require a complete replica before planned takeover;
+   promotion itself does not check this coverage. `groups.replicate` reports
+   `caught_up` after ingesting pages returned by `groups.log`; peer registration
+   alone does not prove the replacement has the room history. Caught-up status
+   describes the last replicated page, not proof the old writer has stopped or
+   that no newer events exist. For a planned move, quiesce writers, replicate
+   through the final cursor, then maintain the fence. For disaster recovery,
+   account for any history that never reached the replica.
+2. **Promote only while the old writer is fenced.** On the replacement:
+
+   ```json
+   {"jsonrpc":"2.0","id":1,"method":"groups.promote","params":{"room_id":"ROOM_ID","confirm":true,"reason":"planned-handover"}}
+   ```
+
+   `room_id` and `confirm: true` are required; `reason` is optional and defaults
+   to `authority-unreachable`. Confirmation is your assertion that the previous
+   authority cannot commit, **not** a request to fence it automatically. Without
+   confirmation the call returns error `4118`. A successful result reports
+   `authority_gateway_id` and `authority_epoch` (the replicated epoch plus one).
+3. **Demote the old authority before returning it to service.** Keep its normal
+   room writers fenced while applying this RPC through a controlled recovery
+   connection on the old gateway. Replace the example gateway ID and epoch with
+   the exact values returned by the successful promotion:
+
+   ```json
+   {"jsonrpc":"2.0","id":2,"method":"groups.demote","params":{"room_id":"ROOM_ID","observed_gateway_id":"NEW_GATEWAY_ID","observed_epoch":2}}
+   ```
+
+   All three parameters are required. Do not guess a future epoch: demotion
+   requires evidence of a newer authority, not an invented value. It records
+   `authority.lost` and adopts the observed lineage; repeating the same lineage
+   is idempotent. If the old host is unavailable, keep it fenced and perform
+   this step before restoring its normal writers.
+4. **Verify and reconnect.** Read `groups.state` on both gateways and compare
+   `room.authority_gateway_id` and `room.authority_epoch` with the promotion
+   result. Old-authority sends must be refused; direct clients to the replacement.
+   Demotion fences writes; it does not merge histories or automatically turn the
+   old authoritative store into a synchronized replica.
+
+Promoting while the old gateway remains writable allows both independent
+`state.db` stores to accept messages and develop divergent histories. A higher
+epoch on the replacement does not remotely disable the old writer; equal epochs
+are not required for split-brain. If histories have already diverged, fence
+writers and preserve both histories for recovery rather than assuming that
+promotion, demotion, or replay will merge them.
+
+## Bots across machines
+
+When you register several backends in **Settings → Connections** — the local runtime, remote gateways, SSH hosts, Hermes Cloud instances — the roster shows the Bots from **every** connected source, persistently: SSH sources are inventoried without spawning anything on the remote box, and machines that are momentarily unreachable keep their last-known rows instead of vanishing. When the same profile name exists on several sources, handles disambiguate as `@name-device` (for example `@research-homelab`). A Bot's chats, sessions, memory, and routines live on the machine that owns the profile.
+
+Clicking a Connections Bot does **not** hop your window onto that machine — stay in your chat and `@mention` it, seat it in a group chat, or create new agents on it directly with the **Create on** picker. Cloud and local agents share one roster this way: register your Hermes Cloud instance and your desktop (say, over Tailscale or SSH) and their Bots can message each other and sit in the same rooms, with each agent's work running on its own machine. Bot-to-bot DMs across those machines go through the Desktop relay automatically (see *Messaging across connected machines* above).
+
+See [Connecting Desktop to Many Hermes Instances](./multi-connection-desktop.md) for the full multi-connection guide.
+
+## Warm Bot Backends (how many bots run at once)
+
+Each local Bot runs in its own backend process, and Desktop keeps at most **Settings → Advanced → Warm Bot Backends** of them alive at once (default 3, ~60 MB each). Idle backends are reaped after the idle timeout next to that setting (default 10 minutes); the `Hermes backend for profile "<name>" exited (1)` line in `desktop.log` that follows an idle-reap message is that cleanup, not a crash. A Bot you open while every slot is busy waits up to 30 seconds for a slot, then fails with *timed out waiting for a free local slot*.
+
+Reads of another Bot's chat history and background transcript refreshes do **not** take a slot — only an interactive open or a running turn does. If you drive a large fleet (group chats with many members, or Kanban dispatch across many profiles), raise Warm Bot Backends toward the number of Bots you expect to be active at the same time and give the machine the memory to match. Setting it higher than the profiles you actually use only adds startup work.
+
+## Turning it off
+
+Bot Mode is a bundled desktop plugin. Flip its **Desktop** switch off in **Capabilities → Plugins → Bots** — the roster, the Routines pane, and the composer middleware unregister live, no restart needed. Your profiles, sessions, and cron jobs are untouched either way; Bot Mode never owns your data, it only renders it.
+
+There is also a preference to hide the canonical Bot Chats from the regular sidebar session list, so they only appear inside the Bots pane. (This uses the core hidden-session flag; on older gateways the chats simply stay visible.)
+
+## CLI parity
+
+Because Bots are profiles, everything has a terminal equivalent:
+
+| In Bot Mode | From a shell |
+| --- | --- |
+| Chat with a Bot | `hermes -p <bot> chat` |
+| A Bot's files, skills, memory | `~/.hermes/profiles/<bot>/` |
+| Routines | `hermes cron list` (jobs named `[bot:<name>] …`) |
+| Create / inspect profiles | `hermes profile create`, `hermes profile list` |
+
+See [Profiles](./profiles.md) for the underlying primitive and [Profile Commands](../reference/profile-commands.md) for the full CLI reference.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/checkpoints-and-rollback.md

@@ -0,0 +1,283 @@
+---
+sidebar_position: 8
+sidebar_label: "Checkpoints & Rollback"
+title: "Checkpoints and /rollback"
+description: "Filesystem safety nets for destructive operations using shadow git repos and automatic snapshots"
+---
+
+# Checkpoints and `/rollback`
+
+Hermes Agent can automatically snapshot your project before **destructive operations** and restore it with a single command. Checkpoints are **opt-in** as of v2 — most users never use `/rollback`, and the shadow-store storage is non-trivial over time, so the default is off.
+
+Enable checkpoints per-session with `--checkpoints`:
+
+```bash
+hermes chat --checkpoints
+```
+
+Or enable globally in `~/.hermes/config.yaml`:
+
+```yaml
+checkpoints:
+  enabled: true
+```
+
+This safety net is powered by an internal **Checkpoint Manager** that keeps a single shared shadow git repository under `~/.hermes/checkpoints/store/` — your real project `.git` is never touched. Every project the agent works in shares the same store, so git's content-addressable object DB deduplicates across projects and across turns.
+
+## What Triggers a Checkpoint
+
+Checkpoints are taken automatically before:
+
+- **File tools** — `write_file` and `patch`
+- **Destructive terminal commands** — `rm`, `rmdir`, `cp`, `install`, `mv`, `sed -i`, `truncate`, `dd`, `shred`, output redirects (`>`), and `git reset`/`clean`/`checkout`
+
+The agent creates **at most one checkpoint per directory per turn**, so long-running sessions don't spam snapshots.
+
+## Quick Reference
+
+In-session slash commands:
+
+| Command | Description |
+|---------|-------------|
+| `/rollback` | List all checkpoints with change stats |
+| `/rollback <N>` | Restore to checkpoint N, keeping your hand-edits (also undoes last chat turn) |
+| `/rollback <N> --all` | Full restore — overwrites your hand-edits too |
+| `/rollback diff <N>` | Preview diff between checkpoint N and current state |
+| `/rollback <N> <file>` | Restore a single file from checkpoint N |
+
+CLI for inspecting and managing the store outside a session:
+
+| Command | Description |
+|---------|-------------|
+| `hermes checkpoints` | Show total size, project count, per-project breakdown |
+| `hermes checkpoints status` | Same as bare `checkpoints` |
+| `hermes checkpoints list` | Alias for `status` |
+| `hermes checkpoints prune` | Force a sweep: delete orphans/stale, GC, enforce size cap |
+| `hermes checkpoints clear` | Nuke the entire checkpoint base (asks first) |
+| `hermes checkpoints clear-legacy` | Delete only the `legacy-*` archives from v1 migration |
+
+## How Checkpoints Work
+
+At a high level:
+
+- Hermes detects when tools are about to **modify files** in your working tree.
+- Once per conversation turn (per directory), it:
+  - Resolves a reasonable project root for the file.
+  - Initialises or reuses the **single shared shadow store** at `~/.hermes/checkpoints/store/`.
+  - Stages into a per-project index, builds a tree, and commits to a per-project ref (`refs/hermes/<project-hash>`).
+- These per-project refs form a checkpoint history that you can inspect and restore via `/rollback`.
+
+```mermaid
+flowchart LR
+  user["User command\n(hermes, gateway)"]
+  agent["AIAgent\n(run_agent.py)"]
+  tools["File & terminal tools"]
+  cpMgr["CheckpointManager"]
+  store["Shared shadow store\n~/.hermes/checkpoints/store/"]
+
+  user --> agent
+  agent -->|"tool call"| tools
+  tools -->|"before mutate\nensure_checkpoint()"| cpMgr
+  cpMgr -->|"git add/commit-tree/update-ref"| store
+  cpMgr -->|"OK / skipped"| tools
+  tools -->|"apply changes"| agent
+```
+
+## Configuration
+
+Configure in `~/.hermes/config.yaml`:
+
+```yaml
+checkpoints:
+  enabled: false              # master switch (default: false — opt-in)
+  max_snapshots: 20           # max checkpoints per project (enforced via ref rewrite + gc)
+  max_total_size_mb: 500      # hard cap on total store size; oldest commits dropped
+  max_file_size_mb: 10        # skip any single file larger than this
+
+  # Auto-maintenance (on by default): sweep ~/.hermes/checkpoints/ in the
+  # background — the CLI on a helper thread right after launch, the gateway
+  # on its housekeeping tick — and delete project entries whose last_touch is
+  # older than retention_days. Runs at most once per min_interval_hours,
+  # tracked via a .last_prune marker. It never blocks the prompt or gateway
+  # startup: the `git gc` that reclaims space can take tens of seconds on a
+  # large store. This sweep never deletes "orphan" entries (working directory
+  # not found) — a missing workdir is ambiguous (deleted project vs. an
+  # unmounted external volume / network share / VPN not yet up), so orphan
+  # cleanup is only ever done via the explicit `hermes checkpoints prune`
+  # command below, with a confirmation prompt.
+  auto_prune: true
+  retention_days: 7
+  min_interval_hours: 24
+```
+
+To disable everything:
+
+```yaml
+checkpoints:
+  enabled: false
+  auto_prune: false
+```
+
+When `enabled: false`, the Checkpoint Manager is a no-op and never attempts git operations. When `auto_prune: false`, the store grows until you run `hermes checkpoints prune` manually.
+
+## Listing Checkpoints
+
+From a CLI session:
+
+```
+/rollback
+```
+
+Hermes responds with a formatted list showing change statistics:
+
+```text
+📸 Checkpoints for /path/to/project:
+
+  1. 4270a8c  2026-03-16 04:36  before patch  (1 file, +1/-0)
+  2. eaf4c1f  2026-03-16 04:35  before write_file
+  3. b3f9d2e  2026-03-16 04:34  before terminal: sed -i s/old/new/ config.py  (1 file, +1/-1)
+
+  /rollback <N>             restore to checkpoint N (keeps your hand-edits)
+  /rollback <N> --all       full restore, overwriting your hand-edits too
+  /rollback diff <N>        preview changes since checkpoint N
+  /rollback <N> <file>      restore a single file from checkpoint N
+```
+
+## Inspecting the Store from the Shell
+
+```bash
+hermes checkpoints
+```
+
+Sample output:
+
+```text
+Checkpoint base: /home/you/.hermes/checkpoints
+Total size:      142.3 MB
+  store/         138.1 MB
+  legacy-*       4.2 MB
+Projects:        12
+
+  WORKDIR                                                       COMMITS    LAST TOUCH  STATE
+  /home/you/code/hermes-agent                                        20       2h ago  live
+  /home/you/code/experiments/rl-runner                                8       1d ago  live
+  /home/you/code/old-prototype                                        3       9d ago  orphan
+  ...
+
+Legacy archives (1):
+  legacy-20260506-050616                           4.2 MB
+
+Clear with: hermes checkpoints clear-legacy
+```
+
+Force a full sweep (ignores the 24h idempotency marker):
+
+```bash
+hermes checkpoints prune --retention-days 3 --max-size-mb 200
+```
+
+## Previewing Changes with `/rollback diff`
+
+Before committing to a restore, preview what has changed since a checkpoint:
+
+```
+/rollback diff 1
+```
+
+This shows a git diff stat summary followed by the actual diff.
+
+## Restoring with `/rollback`
+
+```
+/rollback 1
+```
+
+Behind the scenes, Hermes:
+
+1. Verifies the target commit exists in the shadow store.
+2. Takes a **pre-rollback snapshot** of the current state so you can "undo the undo" later.
+3. Restores tracked files in your working directory — **preserving your hand-edits** (see below).
+4. **Undoes the last conversation turn** so the agent's context matches the restored filesystem state.
+
+### User hand-edits are preserved by default
+
+`/rollback <N>` restores only the files Hermes itself changed. Every successful
+`write_file` / `patch` records the file's content hash in an **agent-write
+ledger**; at restore time, any file whose current contents no longer match what
+Hermes last wrote (you edited it afterwards, or Hermes never touched it) is
+**skipped** instead of overwritten, and listed in the output:
+
+```
+✅ Restored to checkpoint a1b2c3d4: before write_file
+↷ Kept your hand-edits: src/config.py, notes.md
+Use /rollback <N> --all to restore those too.
+```
+
+To force the classic full restore that reverts everything — including your own
+edits — add `--all`:
+
+```
+/rollback 1 --all
+```
+
+If the ledger is empty (a store created before this feature, or Hermes hasn't
+written any files in the project yet), `/rollback` falls back to the full
+restore automatically.
+
+## Single-File Restore
+
+Restore just one file from a checkpoint without affecting the rest of the directory:
+
+```
+/rollback 1 src/broken_file.py
+```
+
+## Safety and Performance Guards
+
+- **Git availability** — if `git` is not found on `PATH`, checkpoints are transparently disabled.
+- **Directory scope** — Hermes skips overly broad directories (root `/`, home `$HOME`).
+- **Repository size** — directories with more than 50,000 files are skipped.
+- **Per-file size cap** — files larger than `max_file_size_mb` (default 10 MB) are excluded from the snapshot. Prevents accidentally swallowing datasets, model weights, or generated media.
+- **Total store size cap** — when the store exceeds `max_total_size_mb` (default 500 MB), each checkpoint drops the oldest commit of every project that still has more than one snapshot (one round per checkpoint), and the periodic prune repeats drop → gc → re-measure until the store fits. A project is never reduced below one snapshot, so a store of many large projects can legitimately sit above the cap.
+- **Real pruning, off the hot path** — `max_snapshots` and the size cap are enforced by rewriting the per-project ref at checkpoint time (cheap); the store is then marked `.gc-pending` and the periodic prune runs `git gc --prune=now` once, so loose objects don't accumulate and a tool call never waits on a full repack.
+- **No-change snapshots** — if there are no changes since the last snapshot, the checkpoint is skipped.
+- **Non-fatal errors** — all errors inside the Checkpoint Manager are logged at debug level; your tools continue to run.
+
+## Where Checkpoints Live
+
+```text
+~/.hermes/checkpoints/
+  ├── store/                 # single shared bare git repo
+  │   ├── HEAD, objects/     # git internals (shared across projects)
+  │   ├── refs/hermes/<hash> # per-project branch tip
+  │   ├── indexes/<hash>     # per-project git index
+  │   ├── projects/<hash>.json  # workdir + created_at + last_touch
+  │   ├── .gc-pending        # refs rewritten since the last gc; cleared by the next prune
+  │   └── info/exclude
+  ├── .last_prune            # auto-prune idempotency marker
+  └── legacy-<ts>/           # archived pre-v2 per-project shadow repos
+```
+
+Each `<hash>` is derived from the absolute path of the working directory. You normally never need to touch these manually — use `hermes checkpoints status` / `prune` / `clear` instead.
+
+### Migration from v1
+
+Before the v2 rewrite, each working directory got its own complete shadow git repo directly under `~/.hermes/checkpoints/<hash>/`. That layout couldn't dedup objects across projects and had a documented no-op pruner — the store would grow without bound.
+
+On first v2 run, any pre-v2 shadow repos are moved into `~/.hermes/checkpoints/legacy-<timestamp>/` so the new single-store layout starts clean. Old `/rollback` history is still reachable by manually inspecting the legacy archive with `git`; once you're confident you don't need it, run:
+
+```bash
+hermes checkpoints clear-legacy
+```
+
+to reclaim the space. Legacy archives are also swept by `auto_prune` after `retention_days`.
+
+## Best Practices
+
+- **Enable checkpoints only when you need them** — `hermes chat --checkpoints` or per-profile `enabled: true`.
+- **Use `/rollback diff` before restoring** — preview what will change to pick the right checkpoint.
+- **Use `/rollback` instead of `git reset`** when you want to undo agent-driven changes only.
+- **Check `hermes checkpoints status` occasionally** if you use checkpoints regularly — shows which projects are active and what the store costs you.
+- **Combine with Git worktrees** for maximum safety — keep each Hermes session in its own worktree/branch, with checkpoints as an extra layer.
+
+For running multiple agents in parallel on the same repo, see the guide on [Git worktrees](./git-worktrees.md).