herdrchat 1.2.1 → 1.3.1

package/docs/architecture.md

@@ -1,33 +1,36 @@
 # herdrchat architecture
 
-herdrchat has two kinds of plug-ins that grow over time: **chat apps** (Feishu now,
-Telegram next, then Slack and Discord) and **harnesses** (Claude Code now, then codex
-and pi). The core between them knows neither. This page says where everything is and
+herdrchat has two kinds of plug-ins that grow over time: **chat apps** (Feishu and
+Telegram now, Slack and Discord later) and **agents**, each read by its reader (Claude
+Code now, then codex and pi). The core between them knows neither. This page says where everything is and
 how to add one of each.
 
 ## The parts
 
 ```
 bin/
-  cli.mjs                  herdrchat init|start|stop|status|logs
+  cli.mjs                  herdrchat init|start|stop|status|logs|install|uninstall|run|version
   herdrchat.mjs            wires the parts: config, log, the chat app, the core
 lib/
-  core/                    the same for every chat app and every harness
+  core/                    the same for every chat app and every agent
     engine.mjs             follows hc, keeps one room per herdr-app tab, posts what agents
                            say, dialogs and clicks, what you type, the overview
-    hc.mjs  events.mjs     hc: commands, and its live event stream
+    hc.mjs  events.mjs     hc: commands, its live event stream, the sessions on a machine
     views.mjs              which view of a terminal is followed (hc core id + tN)
     cursor.mjs  home.mjs   what was posted already; reading an agent's log files
     menu.mjs               a dialog's options, read from the screen
     config.mjs  log.mjs    config.env, state.json, the daily log
-    readers/               one reader per harness (the contract is in index.mjs)
+    service.mjs            herdrchat as a launchd or systemd service
+    readers/               one reader per agent (the contract is in index.mjs)
   chats/
     contract.mjs           what a chat app gives the core, and the check for it
     index.mjs              the list of chat apps
-    feishu/                index.mjs (the contract), client.mjs, overview.mjs, ...
+    feishu/                index.mjs (the contract), client.mjs, overview.mjs, avatar.mjs, userauth.mjs
+    telegram/              index.mjs (the contract), client.mjs, format.mjs
 test/
   fakes.mjs                a fake chat app, a fake hc and a fake reader
-  engine.test.mjs          the core, run on the fakes
+  engine.test.mjs          the core, run on the fakes; the apps' contracts
+  *.test.mjs               the parts one by one
 ```
 
 The rules that keep it this way:
@@ -61,7 +64,7 @@ The rules that keep it this way:
    `HERDRCHAT_CHAT=<app>` in that profile's config.env), so the running Feishu bot is
    not touched.
 
-## Adding a harness
+## Adding an agent
 
 1. Read how the agent keeps its conversation on disk, from its docs or its source: where
    the log is, how to find the one for a running terminal, how a turn's last answer is

package/docs/guide.md

@@ -8,17 +8,33 @@ dialogs, the overview), each behind one contract (`docs/architecture.md`); Slack
 Discord may follow the same way. A profile is one chat app (`HERDRCHAT_CHAT`); to use
 both, run a profile each.
 
+Words used here:
+
+| Word | Meaning |
+|---|---|
+| hc, herdr-core | the program that runs terminals and keeps them alive ([herdr.dev](https://herdr.dev)) |
+| herdr-app | its desktop and phone app, which shows the terminals in spaces and tabs |
+| session | one hc core and its terminals (`HC_SESSION`); `ls ~/.local/state/herdr-core` lists those on a machine |
+| space, tab | how herdr-app groups terminals in its sidebar |
+| room | where one tab is mirrored: a Feishu group or a Telegram topic |
+| direct chat | your private chat with the bot: the overview and the commands |
+| profile | one herdrchat setup for one chat app, with its own settings and state (`default` unless named) |
+| reader | the part that reads an agent's own conversation log (Claude Code so far) |
+
 ## Feishu
 
 herdr-app, moved into one Feishu bot:
 
 | herdr-app | Feishu |
 |---|---|
-| a terminal it shows (it has a `where` label) | a group named `<space> / <tab>`, tagged with the session; type there to talk to it. A tab only numbered (`2`) is named by the terminal's title instead (whatever the program sets, for any agent; Claude Code sets its session name or topic), else its hc name |
+| a tab | a group named `<space> / <tab>`, tagged with its session; type there to talk to it |
 | a space | one avatar for all of its groups: the space's first letter on a color of its own |
 | a terminal on another machine | a group named `<space> / <tab>`, tagged with the machine, made once |
 | a terminal that is gone | its group stays, with its history, tagged `ended` (untagged if it comes back) |
-| herdr itself | the direct chat with the bot: an overview card (every terminal's state, what waits for you first, each a link to its group), kept up to date in place; `/ls`, `/new`, `/kill` |
+| the sidebar | the direct chat with the bot: an overview card (every terminal's state, what waits for you first, each a link to its group), kept up to date in place; `/ls`, `/new`, `/kill` |
+
+A tab herdr-app only numbered (`2`) is named after the terminal's title instead (what the
+program sets; Claude Code sets its session name or topic), else its hc name.
 
 Everything comes from hc, so it works the same for Claude Code, codex, pi or any program
 hc shows, on this machine or on a machine hc has added. Nothing is installed in the agents.
@@ -26,25 +42,75 @@ hc shows, on this machine or on a machine hc has added. Nothing is installed in
 ## Telegram
 
 A Telegram bot cannot make groups, so it uses topics in your private chat with the bot
-(topic mode must be on in @BotFather):
+(topic mode must be on: BotFather's mini app, the Open button in the BotFather chat, then
+the bot, Threaded Mode):
 
 | herdr-app | Telegram |
 |---|---|
 | a tab | a topic named `<space> / <tab>` in the bot's private chat; type there to talk to it |
 | a space | one topic icon color for all of its topics (Telegram offers six) |
 | a terminal that is gone | its topic stays, its name starting with 🔚 (taken off if it comes back) |
-| herdr itself | the chat's main thread: the overview message, edited in place; `/ls`, `/new`, `/kill`; `/` shows the commands |
+| the sidebar | the chat's main thread: the overview message, edited in place; `/ls`, `/new`, `/kill`; `/` shows the commands |
+
+What differs is in "Feishu and Telegram side by side" below. Telegram takes about one
+message a second in a chat, so the bot queues and waits as Telegram asks. Setting it up:
+"Set up: Telegram" below.
+
+## Feishu and Telegram side by side
 
-What differs: an image goes as its own photo after the text (a message cannot hold one);
-a dialog's free answer is typed in the topic (a message has no text box); there are no
-tags, labels, pins or `/auth` (a bot cannot act as you). Telegram takes about one message
-a second in a chat, so the bot queues and waits as Telegram asks. Setting it up:
-`skills/herdrchat/references/telegram.md`.
+Both do the same things; where an app cannot, something stands in.
+
+| | Feishu | Telegram |
+|---|---|---|
+| a tab | a group | a topic in the bot's private chat |
+| a space | an avatar (its letter, its color) | a topic icon color |
+| an ended terminal | the `ended` tag | 🔚 before the topic's name |
+| the direct chat | the overview card, commands typed or from the bot menu (set in the console) | the main thread: the overview, commands with the `/` list |
+| what it says while working | one live card per turn, edited | one live message per turn, edited |
+| a dialog | a card with buttons, a text box for its own words | a message with buttons; its own words are typed in the topic |
+| needs you | the group pinned (after `/auth`), an @ that rings | the dialog card pinned in its topic, a reply that rings |
+| quiet spaces (`HERDR_MUTED_SPACES`) | groups muted (after `/auth`); only an @ rings | posts silent; only a short reply rings |
+| silent spaces (`HERDR_SILENT_SPACES`) | no @ | no ringing reply |
+| a new room (`HERDR_HISTORY`), `/history` | the conversation as a file, its newest part in a folded panel | the same, the newest part in an expandable quote |
+| images | in the card, both ways | as photos after the text, both ways |
+| your message marked | a reaction, then OK | 👀, then 👌 |
+| tags and labels (`HERDR_BOT_TAGS`, `HERDR_USER_TAGS`) | yes | none in Telegram |
+| messages while the bot is away | looked for and handled when it connects | kept by Telegram for 24 hours, handled when it connects |
+| acting as you (`/auth`) | mute, labels, pins | not needed: posts are silent by themselves |
+
+## Settings
+
+In the profile's `config.env` (`herdrchat status` prints where it is):
+
+| Key | For | Default | What it does |
+|---|---|---|---|
+| `HERDRCHAT_CHAT` | both | `feishu` | the chat app this profile mirrors into: `feishu` or `telegram` |
+| `HERDR_SESSIONS` | both | (required) | the hc sessions to mirror, comma-separated; machines they reach come along |
+| `HERDR_MUTED_SPACES` | both | `all` | spaces whose rooms are quiet: only "needs you" and "done" ring; empty for none |
+| `HERDR_SILENT_SPACES` | both | (none) | spaces where nothing rings, not even "needs you" |
+| `HERDR_HISTORY` | both | `file,folded` | what a new room gets of the conversation before it: `file`, `folded`, both, or empty |
+| `FEISHU_APP_ID`, `FEISHU_APP_SECRET` | Feishu | (required) | the Feishu app |
+| `FEISHU_OWNER_OPEN_ID` | Feishu | (empty) | you; the bot tells you yours when you message it |
+| `HERDR_BOT_TAGS` | Feishu | `on` | the session or machine tag and `ended` next to a group's name |
+| `HERDR_USER_TAGS` | Feishu | `on` | your sidebar labels, once `/auth` is done |
+| `TELEGRAM_BOT_TOKEN` | Telegram | (required) | the bot's token from @BotFather |
+| `TELEGRAM_OWNER_ID` | Telegram | (empty) | you; the bot tells you yours when you message it |
+
+Where a profile's files are: settings in `~/.config/herdrchat/<profile>/config.env`,
+what the bot writes (state, logs, your `/auth` token) in
+`~/.local/state/herdrchat/<profile>/`; `herdrchat status` prints both.
+
+In the environment (not `config.env`): `HERDRCHAT_PROFILE` (or `--profile`) picks the
+profile; `HERDRCHAT_HOME` puts a profile's `config.env` and state in one folder of your
+choice (give each profile its own); `XDG_CONFIG_HOME` and `XDG_STATE_HOME` move the usual
+folders. A setup in a moved folder gets its own hc terminal and service name, so trying
+one never touches the usual one. A key set in the environment wins over `config.env`. A
+setting changed in `config.env` takes effect at the next `herdrchat start`.
 
 ## How it works: hc, plus a reader per agent
 
-**hc is the backbone.** The bot follows `hc events --json` for each session (format:
-herdr-core `schema/README.md`, "Events"). From hc it learns which terminals exist, where
+**hc is the backbone.** The bot follows `hc events --json` for each session (its format:
+`hc schema`). From hc it learns which terminals exist, where
 herdr-app shows them, their status, and when a turn ends (`turn` event: the status left
 `working`). Typing from a group goes through `hc send`.
 
@@ -59,7 +125,7 @@ each agent a reader reads the agent's own records. The status hc reports names t
 | anything else | none | nothing by itself; what you type gets its screen in reply |
 
 On another machine, a reader reads the same files through `hc exec --on`. To add an
-agent: `docs/architecture.md`, "Adding a harness".
+agent: `docs/architecture.md`, "Adding an agent".
 
 ## What a room shows
 
@@ -151,8 +217,10 @@ delivered (the terminal has ended) says so plainly.
 
 - Direct chat: `/ls` (the overview again at the bottom of the chat; the old one is
   recalled), `/new <session> <space>/<tab> [command]` (start one; default `claude`;
-  `--cwd <dir>` first to pick its folder), `/kill <session> <address>`, `/auth` (see
-  below).
+  `--cwd <dir>` first to pick its folder), `/kill <session> <address>`, `/auth` (Feishu;
+  see below). Telegram lists them when you type `/`; Feishu can have a bot menu for
+  `/ls`, help and `/auth` (set in the developer console:
+  `skills/herdrchat/references/feishu.md`, "The bot menu").
 - In a terminal's room: any text goes to it (marked once typed in, and again when the
   turn that took it is over); an image (alone or in a rich text message) is sent
   beside the terminal with `hc put`, on its machine, and its path is typed in with your
@@ -160,32 +228,52 @@ delivered (the terminal has ended) says so plainly.
   dialog it waits on, as is), `/esc`, `/history` (the conversation so far, as a file and
   a folded post). Dialog cards have buttons.
 
-## Set up
-
-Telegram: `skills/herdrchat/references/telegram.md`. Feishu:
-
-Steps 1, 2, 5 and 6 are in the Feishu developer console; the herdrchat skill
-(`/herdrchat setup`, see "Skills") does them with an agent, or guides you through them.
-
-1. Feishu developer console: create a custom app (企业自建应用), add the bot ability.
-2. Permissions (batch import): `im:message:send_as_bot`, `im:message.p2p_msg:readonly`,
-   `im:message.group_msg`, `im:chat:create`, `im:chat:update`,
-   `im:message.reactions:write_only`, `im:resource` (images out),
-   `im:message:readonly` (images in), `im:tag:write`,
-   `im:biz_entity_tag_relation:write` (group tags).
-3. `herdrchat init` makes `~/.config/herdrchat/default/config.env`; fill the app ID, the
-   secret and `HERDR_SESSIONS`: the hc sessions on the machine the bot runs on that herdr-app shows
-   (the machines they connect to come along, as in herdr-app). See "Where things are"
-   for other places and more than one profile.
-4. `herdrchat start` (the console checks for a live connection in the next step).
+## Set up: Telegram
+
+1. In Telegram, message **@BotFather**: `/newbot`, give it a name and a username ending
+   in `bot`. It answers with a token; keep it private.
+2. Turn on topics for the bot: in the BotFather chat tap **Open** (its mini app), pick the
+   bot, turn on **Threaded Mode**. Without it the bot cannot make topics.
+3. `herdrchat init --chat telegram` (with `--profile <name>` too if you also run Feishu)
+   prints where its `config.env` is. Fill in `TELEGRAM_BOT_TOKEN` and `HERDR_SESSIONS`
+   (`ls ~/.local/state/herdr-core` lists your hc sessions).
+4. `herdrchat start`, then message the bot anything. It answers with the line to add,
+   `TELEGRAM_OWNER_ID=<your id>`; add it and run `herdrchat start` again. One topic per
+   tab appears in your private chat with the bot (Telegram takes about one message a
+   second, so many tabs take a moment).
+5. Once it works: `herdrchat install` (see "Running as a service").
+
+If Telegram is your only app, use the default profile with `--chat telegram`. Use
+`--profile <name>` only for a second chat app beside the first.
+
+## Set up: Feishu
+
+Feishu only: Lark (the international version) is not supported yet. Steps 1, 2, 5 and 6
+are in the Feishu developer console (`https://open.feishu.cn/app`); the herdrchat skill
+(`/herdrchat setup`) can do them with you.
+
+1. Create a custom app (企业自建应用) and add the bot ability (机器人).
+2. Permissions: import the scopes listed in `skills/herdrchat/references/feishu.md`,
+   "Scopes this bot uses" (there as JSON for the batch import): sending as the bot,
+   reading the messages sent to it, making and renaming groups, reactions, images both
+   ways, and group tags.
+3. `herdrchat init` prints where its `config.env` is. Fill in the app's App ID and App
+   Secret (the app's 凭证与基础信息 page) and `HERDR_SESSIONS` (`ls
+   ~/.local/state/herdr-core` lists your hc sessions).
+4. `herdrchat start`. The bot must be running for the next step: the console checks for
+   a live connection.
 5. Events and callbacks (事件与回调): for events, choose the long connection mode (长连接)
    and add `im.message.receive_v1`; for callbacks (回调配置), choose the long connection
    mode too and add `card.action.trigger` (the dialog buttons).
-6. Publish a version.
+6. Publish a version. If the page does not say 本次发布免审核, your team's admin must
+   approve it first.
 7. Open `https://applink.feishu.cn/client/bot/open?appId=<app id>` and send anything.
-   The bot answers with your `open_id`; put it in `FEISHU_OWNER_OPEN_ID` and run
-   `herdrchat start` again.
-8. Once it works: `herdrchat install` (see "Running as a service").
+   The bot answers with the line to add, `FEISHU_OWNER_OPEN_ID=<your open_id>`; add it
+   and run `herdrchat start` again. One group per tab appears.
+8. Optional: send `/auth` to the bot so it can mute its groups for you ("Optional: let
+   the bot act as you"), and add the bot menu (`skills/herdrchat/references/feishu.md`,
+   "The bot menu").
+9. Once it works: `herdrchat install` (see "Running as a service").
 
 ## Running as a service
 
@@ -235,18 +323,18 @@ refreshed, the bot says so once and falls back.
 `SKILL.md`): `/herdrchat setup`, `status`, `start`, `stop`, `install`, `logs`, `auth`,
 `config`, `fix`, `feishu <task>` (the developer console, with Ego Lite from
 https://lite.ego.app/ or as a guided walk-through) and `telegram <task>` (the bot, from
-@BotFather to the first topic). Details per part are in `skills/herdrchat/references/`. To use it
-with Claude Code, link it where skills are read, for example
-`ln -s "$PWD/skills/herdrchat" ~/.claude/skills/herdrchat`.
+@BotFather to the first topic). Details per part are in `skills/herdrchat/references/`.
+Install it with `npx skills add zhangxiangliang/herdrchat` (README); from a clone you can
+link it instead, for example `ln -s "$PWD/skills/herdrchat" ~/.claude/skills/herdrchat`.
 
 ## Logs
 
-Everything the bot logs goes to `logs/<YYYY-MM-DD>.log` in the state folder (one file a
-day, the last 14 kept) as `<time> <LEVEL> <text>`, besides its terminal: `grep ERROR
-~/.local/state/herdrchat/<profile>/logs/*.log` finds
-what went wrong, a retry that recovered is a `WARN`, and a crash leaves its stack there
-before it is started again. Tokens and secrets are never logged. The
-skill's `references/ops.md` explains the lines.
+Everything the bot logs goes to `logs/<YYYY-MM-DD>.log` in the state folder, one file a
+day by your local date (the last 14 kept), as `<time> <LEVEL> <text>` with the time in
+UTC. `herdrchat logs` shows today's (`--errors` only what went wrong, `--day 2026-01-31`
+another day); a retry that recovered is a `WARN`, and a crash leaves its stack there
+before it is started again. Tokens and secrets are never logged. The skill's
+`references/ops.md` explains the lines.
 
 ## Limits
 
@@ -255,6 +343,7 @@ skill's `references/ops.md` explains the lines.
   until each has a reader; what you type to them gets their screen in reply.
 - Only text, images and rich text are passed on; files, stickers and the rest are not.
 - An image that fails to upload three times is not sent; the group says so and why.
+- Feishu only, not Lark (the international version) yet: the bot talks to open.feishu.cn.
 - Feishu takes tag names of at most 16 characters; a longer session or machine name is cut
   at its last `-`, `_` or `.` that fits (`build-agent-server` becomes `build-agent`).
 - Avatars are drawn with `sips`, so only on macOS; elsewhere groups keep Feishu's default.

package/lib/chats/contract.mjs

@@ -18,6 +18,7 @@ export const CHAT_MEMBERS = {
   name: 'string: the app, as in HERDRCHAT_CHAT',
   ready: '() -> boolean: the owner is known (no room is made before)',
   help: 'string[]: lines it adds to the direct chat\'s help',
+  roomWord: 'string: what the user calls a room in this app (group, topic), for what the bot says',
   liveBytes: 'number: how much text one editable card holds',
   split: '(markdown) -> string[]: one message\'s worth each',
   start: '({onMessage, onAction, onReady}): connect; onMessage({room|null, where, message, text, images}) for the owner\'s messages (room null: the direct chat), onAction({value, message, answer}) -> {toast: {type, text}, card?: {kind: done|dialog, ...}} for button clicks',
@@ -33,7 +34,7 @@ export const CHAT_MEMBERS = {
   editCard: '(message, look)',
   postDialog: '(room, dialog, value) -> message: dialog {title, markdown, menu, doneTitle}; each button sends value plus {pick, label}',
   closeDialog: '(message, dialog, done): no buttons any more, says what was done',
-  pin: '(k, room): the room waits for you',
+  pin: '(k, room, message): the room waits for you, on this message (its dialog card)',
   unpin: '(k)',
   pinned: '() -> k[]',
   ring: '(k, message, text): make the phone ring for this message if it would not',
@@ -48,7 +49,7 @@ export const CHAT_MEMBERS = {
   showOverview: '(rows, {fresh}): rows [{name, address, state, kind, program, since, room}]',
 };
 
-const TYPES = { name: 'string', help: 'object', liveBytes: 'number', foldedBytes: 'number' };
+const TYPES = { name: 'string', help: 'object', roomWord: 'string', liveBytes: 'number', foldedBytes: 'number' };
 
 // Throws, naming every member that is missing or of the wrong kind.
 export function checkChat(chat) {

package/lib/chats/feishu/client.mjs

@@ -69,14 +69,15 @@ async function createMessage(client, receiveIdType, receiveId, msgType, content)
 }
 
 // A markdown card per chunk; plain text when the card is refused. Returns the id of the
-// last message sent.
+// last message sent. `chatId` may be "open_id:<id>" for a person's direct chat.
 export async function sendMarkdown(client, chatId, text) {
+  const [idType, id] = chatId.startsWith('open_id:') ? ['open_id', chatId.slice(8)] : ['chat_id', chatId];
   let last = null;
   for (const part of chunk(text || '(empty)')) {
     try {
-      last = await createMessage(client, 'chat_id', chatId, 'interactive', card(part));
+      last = await createMessage(client, idType, id, 'interactive', card(part));
     } catch (err) {
-      last = await createMessage(client, 'chat_id', chatId, 'text', JSON.stringify({ text: part }));
+      last = await createMessage(client, idType, id, 'text', JSON.stringify({ text: part }));
       console.warn(`[feishu] card refused, sent as text: ${err.message}`);
     }
   }
@@ -258,8 +259,9 @@ export async function renameChat(client, chatId, name) {
 // Messages in (im.message.receive_v1) and card clicks (card.action.trigger), both over
 // the long connection. A click must be answered within 3 seconds; what `onCardAction`
 // returns ({toast, card}) is that answer.
-// onConnect runs at every connection, the first and each one after a drop.
-export function startEvents(cfg, onMessage, onCardAction, onReady = () => {}, onConnect = () => {}) {
+// onConnect runs at every connection, the first and each one after a drop; onMenu gets a
+// click on the bot's menu (application.bot.menu_v6: its event_key and who clicked).
+export function startEvents(cfg, onMessage, onCardAction, onReady = () => {}, onConnect = () => {}, onMenu = () => {}) {
   const ws = new Lark.WSClient({
     appId: cfg.appId,
     appSecret: cfg.appSecret,
@@ -285,6 +287,13 @@ export function startEvents(cfg, onMessage, onCardAction, onReady = () => {}, on
           console.error(`[feishu] message handler: ${err.stack || err.message}`);
         }
       },
+      'application.bot.menu_v6': async (data) => {
+        try {
+          await onMenu(data);
+        } catch (err) {
+          console.error(`[feishu] menu handler: ${err.stack || err.message}`);
+        }
+      },
       'card.action.trigger': async (data) => {
         try {
           return await onCardAction(data);

package/lib/chats/feishu/index.mjs

@@ -17,6 +17,9 @@ const DONE_EMOJI = 'OK';
 const TONES = { working: 'blue', closed: 'grey', needs: 'red', done: 'grey', good: 'green', bad: 'red' };
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// What to do after an edit to config.env, said the way this profile is run.
+const startAgain = (cfg) => `\`herdrchat start${cfg.profile && cfg.profile !== 'default' ? ` --profile ${cfg.profile}` : ''}\``;
+
 const inSpaces = (set, space) => set.all || set.spaces.includes(space);
 const spaceOfName = (name) => (name || '').split(' / ')[0];
 
@@ -438,7 +441,7 @@ export function create({ cfg, store, log, logWarn, logError, stateDir, lane, sco
       const openId = data.sender?.sender_id?.open_id;
       if (!cfg.ownerOpenId) {
         log(`owner not set; message from open_id ${openId}`);
-        if (msg.chat_type === 'p2p') await reply(msg.chat_id, `Owner is not set. Put this in config.env:\n\n\`FEISHU_OWNER_OPEN_ID=${openId}\`\n\nthen restart the bot.`);
+        if (msg.chat_type === 'p2p') await reply(msg.chat_id, `Hello! To make you this bot's owner (the only person it listens to), add this line to ${cfg.configFile || 'config.env'}:\n\n\`FEISHU_OWNER_OPEN_ID=${openId}\`\n\nthen run ${startAgain(cfg)}. Your terminals' groups appear then.`);
         return;
       }
       if (openId !== cfg.ownerOpenId) {
@@ -487,7 +490,16 @@ export function create({ cfg, store, log, logWarn, logError, stateDir, lane, sco
         }
       }
     };
-    startEvents(cfg, take, handleAction, onReady, () => catchUp().catch((err) => logError(`feishu catch-up: ${err.message}`)));
+    // The bot's menu (set in the developer console; direct chat only): an item that pushes
+    // an event with key "ls", "help" or "auth" works as that command sent in the direct chat.
+    const onMenu = async (data) => {
+      const openId = data.operator?.operator_id?.open_id;
+      const key = String(data.event_key || '').replace(/^\//, '');
+      if (!cfg.ownerOpenId || openId !== cfg.ownerOpenId || !/^[a-z]+$/.test(key)) return;
+      log(`feishu menu: /${key}`);
+      queued('menu', () => onMessage({ room: null, where: `open_id:${openId}`, message: `menu-${data.timestamp || Date.now()}`, text: `/${key}`, images: [] }));
+    };
+    startEvents(cfg, take, handleAction, onReady, () => catchUp().catch((err) => logError(`feishu catch-up: ${err.message}`)), onMenu);
     setInterval(() => asYou().catch((err) => logError(`as you: ${err.message}`)), YOU_CHECK_MS);
     asYou().catch((err) => logError(`as you: ${err.message}`));
   }
@@ -517,6 +529,7 @@ export function create({ cfg, store, log, logWarn, logError, stateDir, lane, sco
     name: 'feishu',
     ready: () => Boolean(cfg.ownerOpenId),
     help: ['`/auth` let the bot act as you for chat-list settings (mute, labels, pin)'],
+    roomWord: 'group',
     liveBytes: 20000, // a card may hold 30 KB; room for JSON escaping
     split: (text) => chunk(text),
     start,

package/lib/chats/telegram/index.mjs

@@ -15,7 +15,7 @@
 //   buttons       callback_data holds 64 bytes, so a button carries a short id and the
 //                 dialog it answers is kept in state.json
 //   a free answer no text box on a message: you type the answer in the topic
-//   pin           a topic cannot be pinned; nothing is done
+//   pin           a topic cannot be pinned, so the dialog card is: pinned while it waits
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import { createClient } from './client.mjs';
@@ -46,6 +46,9 @@ const COMMANDS = [
 ];
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// What to do after an edit to config.env, said the way this profile is run.
+const startAgain = (cfg) => `\`herdrchat start${cfg.profile && cfg.profile !== 'default' ? ` --profile ${cfg.profile}` : ''}\``;
+
 const inSpaces = (set, space) => set.all || set.spaces.includes(space);
 const spaceOfName = (name) => (name || '').split(' / ')[0];
 const cut = (text, max) => (text.length > max ? `${text.slice(0, max - 1)}…` : text);
@@ -204,9 +207,27 @@ export function create({ cfg, store, log, logWarn, logError }) {
 
   // ---------- attention ----------
 
-  const pins = new Set();
-  const pin = async (k) => { pins.add(k); };
-  const unpin = async (k) => { pins.delete(k); };
+  // A dialog card is pinned while it waits, as Feishu pins its group, and unpinned once
+  // it is answered; which message is pinned for which room is kept in state.json (pinned).
+  async function pin(k, room, message) {
+    if (!message) return;
+    try {
+      await tg.queued('pinChatMessage', { chat_id: owner, message_id: Number(message), disable_notification: true });
+      const state = read();
+      state.pinned = { ...(state.pinned || {}), [k]: String(message) };
+      write(state);
+    } catch (err) {
+      logError(`pin ${message}: ${err.message}`);
+    }
+  }
+  async function unpin(k) {
+    const message = read().pinned?.[k];
+    if (!message) return;
+    await tg.queued('unpinChatMessage', { chat_id: owner, message_id: Number(message) }).catch((err) => logError(`unpin ${message}: ${err.message}`));
+    const state = read();
+    delete state.pinned[k];
+    write(state);
+  }
 
   // In a quiet room this reply is what sounds; in another the post sounded already. A
   // space in HERDR_SILENT_SPACES never sounds.
@@ -311,7 +332,7 @@ export function create({ cfg, store, log, logWarn, logError }) {
     const where = `${m.chat.id}:${m.is_topic_message ? m.message_thread_id : ''}`;
     if (!owner) {
       log(`owner not set; message from user id ${from}`);
-      if (m.chat.type === 'private') await reply(where, `Owner is not set. Put this in config.env:\n\n\`TELEGRAM_OWNER_ID=${from}\`\n\nthen restart the bot.`);
+      if (m.chat.type === 'private') await reply(where, `Hello! To make you this bot's owner (the only person it listens to), add this line to ${cfg.configFile || 'config.env'}:\n\n\`TELEGRAM_OWNER_ID=${from}\`\n\nthen run ${startAgain(cfg)}. Your terminals' topics appear then.`);
       return;
     }
     if (from !== owner || String(m.chat.id) !== owner) {
@@ -357,7 +378,7 @@ export function create({ cfg, store, log, logWarn, logError }) {
           if (!username) {
             const me = await tg.call('getMe');
             username = me.username;
-            if (!me.has_topics_enabled) logWarn(`telegram: topic mode is off for @${username}; turn it on in @BotFather (Bot Settings), or no room can be made`);
+            if (!me.has_topics_enabled) logWarn(`telegram: topic mode is off for @${username}, so no topic can be made: open @BotFather, tap Open (its mini app), pick the bot, turn on Threaded Mode, then herdrchat start again`);
             await tg.call('setMyCommands', { commands: COMMANDS }).catch((err) => logWarn(`telegram commands: ${err.message}`));
           }
           // the token works and Telegram answers: in (the first poll may hold for a while)
@@ -400,6 +421,7 @@ export function create({ cfg, store, log, logWarn, logError }) {
     name: 'telegram',
     ready: () => Boolean(owner),
     help: [],
+    roomWord: 'topic',
     liveBytes: 3500, // a message holds 4096 characters after parsing
     split: (text) => split(text),
     start,
@@ -416,7 +438,7 @@ export function create({ cfg, store, log, logWarn, logError }) {
     closeDialog,
     pin,
     unpin,
-    pinned: () => [...pins],
+    pinned: () => Object.keys(read().pinned || {}),
     ring,
     markWorking,
     markDone,

package/lib/core/config.mjs

@@ -26,19 +26,34 @@
 //   HERDR_HISTORY                    what a new room gets of the conversation before it:
 //                                    `file,folded` (default: all of it as a file, the newest
 //                                    part in a folded post), `file`, `folded`, or empty / `none`
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
-// Where one profile lives, from the environment: {profile, configDir, stateDir, terminal}.
+// Where one profile lives, from the environment: {profile, id, configDir, stateDir,
+// terminal}. `id` names what the system sees of it (its hc terminal, its service): the
+// profile, plus a short tag of its folder when that is not the usual one (HERDRCHAT_HOME,
+// XDG_*), so a setup tried in another folder never stops, replaces or removes the real one.
 export function placesOf(env = process.env, home = os.homedir()) {
   const profile = env.HERDRCHAT_PROFILE || 'default';
-  if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(profile)) throw new Error(`HERDRCHAT_PROFILE "${profile}": letters, digits, - and _ only`);
-  const terminal = profile === 'default' ? 'herdrchat' : `herdrchat-${profile}`;
-  if (env.HERDRCHAT_HOME) return { profile, configDir: env.HERDRCHAT_HOME, stateDir: path.join(env.HERDRCHAT_HOME, 'state'), terminal };
-  const configRoot = env.XDG_CONFIG_HOME || path.join(home, '.config');
-  const stateRoot = env.XDG_STATE_HOME || path.join(home, '.local', 'state');
-  return { profile, configDir: path.join(configRoot, 'herdrchat', profile), stateDir: path.join(stateRoot, 'herdrchat', profile), terminal };
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(profile)) throw new Error(`profile "${profile}": use letters, digits, - and _ only`);
+  const usual = path.join(home, '.config', 'herdrchat', profile);
+  let configDir;
+  let stateDir;
+  if (env.HERDRCHAT_HOME) {
+    configDir = env.HERDRCHAT_HOME;
+    stateDir = path.join(env.HERDRCHAT_HOME, 'state');
+  } else {
+    configDir = path.join(env.XDG_CONFIG_HOME || path.join(home, '.config'), 'herdrchat', profile);
+    stateDir = path.join(env.XDG_STATE_HOME || path.join(home, '.local', 'state'), 'herdrchat', profile);
+  }
+  const usualState = path.join(home, '.local', 'state', 'herdrchat', profile);
+  const moved = path.resolve(configDir) !== usual || path.resolve(stateDir) !== usualState;
+  const tag = moved ? crypto.createHash('sha1').update(`${path.resolve(configDir)}\0${path.resolve(stateDir)}`).digest('hex').slice(0, 6) : '';
+  const id = tag ? `${profile}-${tag}` : profile;
+  const terminal = id === 'default' ? 'herdrchat' : `herdrchat-${id}`;
+  return { profile, id, configDir, stateDir, terminal };
 }
 
 const places = placesOf();
@@ -90,13 +105,16 @@ export function onOff(value, fallback) {
 
 // `requires`: config keys the chat app cannot start without (its module's `requires`).
 // `env` is everything config.env and the environment hold, for the app's own keys.
-export function loadConfig({ requires = [] } = {}) {
+// `sessions: false`: an empty HERDR_SESSIONS is not an error (status shows what is set).
+export function loadConfig({ requires = [], sessions: needSessions = true } = {}) {
   const env = { ...parseEnv(CONFIG_FILE), ...process.env };
   const sessions = (env.HERDR_SESSIONS || '').split(',').map((s) => s.trim()).filter(Boolean);
   const missing = requires.filter((k) => !env[k]);
-  if (missing.length) throw new Error(`${CONFIG_FILE}: ${missing.join(', ')} ${missing.length > 1 ? 'are' : 'is'} required`);
-  if (!sessions.length) throw new Error(`${CONFIG_FILE}: HERDR_SESSIONS must list at least one hc session`);
+  if (missing.length) throw new Error(`${missing.join(', ')} ${missing.length > 1 ? 'are' : 'is'} empty in ${CONFIG_FILE}: fill ${missing.length > 1 ? 'them' : 'it'} in (the comment above each says where it comes from), then start again.`);
+  if (needSessions && !sessions.length) throw new Error(`HERDR_SESSIONS is empty in ${CONFIG_FILE}: put the hc sessions to mirror there, comma-separated (\`ls ~/.local/state/herdr-core\` lists the sessions on this machine), then start again.`);
   return {
+    profile: places.profile,
+    configFile: CONFIG_FILE,
     chat: env.HERDRCHAT_CHAT || 'feishu',
     env,
     sessions,