herdrchat 1.3.0 → 1.3.2

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,18 +42,19 @@ 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:
-`skills/herdrchat/references/telegram.md`.
+"Set up: Telegram" below.
 
 ## Feishu and Telegram side by side
 
@@ -79,16 +96,21 @@ In the profile's `config.env` (`herdrchat status` prints where it is):
 | `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;
-`XDG_CONFIG_HOME` and `XDG_STATE_HOME` move the usual folders. `herdrchat start` and
-`herdrchat install` hand the bot hc's full path as `HERDRCHAT_HC`. A setting changed in
-`config.env` takes effect at the next `herdrchat start`.
+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`.
 
@@ -103,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
 
@@ -206,32 +228,50 @@ 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. Optional: the bot menu in the direct chat (`skills/herdrchat/references/feishu.md`,
+   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").
 
@@ -283,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
 
@@ -303,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',
@@ -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/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) {
@@ -526,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

@@ -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);
@@ -329,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) {
@@ -375,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)
@@ -418,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,

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,

package/lib/core/engine.mjs

@@ -58,7 +58,8 @@ const ENDED_REPLY = 'Not delivered: this terminal has ended. Nothing you send he
 const WAIT = Symbol('wait');
 const FILE_BYTES = 20 * 1000 * 1000;
 
-// hc: {followEvents, cores, machines, getTerminal, screenTail, send, keys, put, run, kill};
+// hc: {followEvents, cores, machines, getTerminal, screenTail, send, keys, put, run, kill,
+// nameTab?(tabId, name): name a tab in herdr-app, when it runs here};
 // readers: {agentOf, readerFor}; store: {read, write} of state.json; inbox: a folder for
 // images on their way to a terminal; quick: shorter waits (tests).
 export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logError, startedAt = new Date().toISOString(), inbox = path.join(os.tmpdir(), 'herdrchat-inbox'), quick = false }) {
@@ -952,8 +953,9 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
       log(`-> ${session}/${address}: ${text.slice(0, 80)}`);
       await markWorking(k, message);
     } catch (err) {
-      const hint = /blocked/i.test(err.message) ? '\n\nIt waits on a dialog. Reply `/answer <text>` to answer it, or `/esc` to cancel it.' : '';
-      await chat.reply(where, `Not delivered: ${plainError(err)}\n\n${await screen(session, address)}${hint}`);
+      // the screen only when it helps: it waits on something you can answer from there
+      const waits = /blocked/i.test(err.message);
+      await chat.reply(where, `Not delivered: ${plainError(err)}${waits ? `\n\n${await screen(session, address)}\n\nIt waits on a dialog. Reply \`/answer <text>\` to answer it, or \`/esc\` to cancel it.` : ''}`);
       return;
     }
     // Anything but an agent posts nothing by itself: what you typed gets one look at its
@@ -1028,7 +1030,7 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
     '`/new <session> <space>/<tab> [command]` start a terminal (default `claude`); `--cwd <dir>` first to pick its folder',
     '`/kill <session> <address>` end a terminal',
     ...(chat.help || []),
-    'In a terminal\'s room: type to talk to it; `/screen`, `/answer <text>`, `/esc`, `/history` (the conversation so far, as a file).',
+    `In a terminal's ${chat.roomWord}: type to talk to it; \`/screen\`, \`/answer <text>\`, \`/esc\`, \`/history\` (the conversation so far, as a file).`,
   ].join('\n');
 
   async function newTerminal(args) {
@@ -1047,13 +1049,17 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
     const spaceId = sibling?.labels['herdr.space'] || `sp${crypto.randomBytes(16).toString('hex')}`;
     const folder = cwd || sibling?.foreground?.cwd || sibling?.cwd || os.homedir();
     const line = command.length ? command.join(' ') : 'claude';
+    const tabId = `tb${crypto.randomBytes(16).toString('hex')}`;
     const out = await hc.run(session, {
       cwd: folder,
-      labels: { 'herdr.space': spaceId, 'herdr.tab': `tb${crypto.randomBytes(16).toString('hex')}`, where: `${space} / ${tab}` },
+      labels: { 'herdr.space': spaceId, 'herdr.tab': tabId, where: `${space} / ${tab}` },
       argv: ['/bin/zsh', '-lc', `exec ${line}`], // login shell for PATH; exec so no bare shell is left behind
     });
     const address = JSON.parse(out).address;
-    return `Started \`${line}\` as \`${address}\` in ${session} / ${space} / ${tab} (\`${folder}\`). Its room appears in a moment.`;
+    // herdr-app makes the tab and numbers it, whatever `where` says: it is named as asked,
+    // by the tab id it keeps (nothing happens where herdr-app is not running)
+    if (hc.nameTab) hc.nameTab(tabId, tab).catch((err) => logWarn(`tab ${tab} not named in herdr-app: ${err.message}`));
+    return `Started \`${line}\` as \`${address}\` in ${session} / ${space} / ${tab} (\`${folder}\`). Its ${chat.roomWord} appears in a moment.`;
   }
 
   async function direct(where, text) {
@@ -1073,14 +1079,14 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
   async function onMessage({ room, where, message, text, images = [] }) {
     try {
       if (!room) {
-        if (images.length) await chat.reply(where, 'Send images in a terminal\'s room.');
+        if (images.length) await chat.reply(where, `Send images in a terminal's ${chat.roomWord}.`);
         else await direct(where, text);
         return;
       }
       const target = terminalOfRoom(room);
       if (!target) {
         log(`message in a room this bot did not make: ${room}`);
-        await chat.reply(where, 'Not delivered: this room is not a terminal\'s. Each terminal has its own room; the direct chat takes /ls, /new and /kill.');
+        await chat.reply(where, `Not delivered: this ${chat.roomWord} is not a terminal's. Each terminal has its own ${chat.roomWord}; the direct chat takes /ls, /new and /kill.`);
         return;
       }
       if (views.get(target.session)?.terminals.get(target.address)?.state !== 'live') {

package/lib/core/hc.mjs

@@ -1,6 +1,10 @@
 // Thin wrapper over the hc CLI. Every call names its session (HC_SESSION),
 // never the default core.
 import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
 
 // The bot runs in an hc terminal itself. Called with that terminal's identity, hc would
 // wrap what the bot types in <hc from="tN"> tags, as a note from another agent; without
@@ -68,7 +72,8 @@ export function run(session, { name, cwd, labels = {}, argv }) {
 
 // force: type even when the program is blocked on a dialog (it answers the dialog).
 export function send(session, address, text, { force = false } = {}) {
-  const args = ['send', ...(force ? ['--force'] : []), address, text];
+  // `--`: what you typed is never taken for an option, even when it starts with "-"
+  const args = ['send', ...(force ? ['--force'] : []), address, '--', text];
   return hc(session, args, { timeoutMs: 60000 });
 }
 
@@ -96,6 +101,57 @@ export function isUnavailable(err) {
   return /"kind":"unavailable"/.test(err?.message || '');
 }
 
+// The hc sessions on this machine, from hc's own folder (asking hc about a session that
+// does not exist would start one: a typo must not make a session).
+export const hcStateRoot = (env = process.env) => path.join(env.XDG_STATE_HOME || path.join(os.homedir(), '.local', 'state'), 'herdr-core');
+export function sessionsHere() {
+  try {
+    return fs.readdirSync(hcStateRoot(), { withFileTypes: true }).filter((d) => d.isDirectory() && fs.existsSync(path.join(hcStateRoot(), d.name, 'core.json'))).map((d) => d.name).sort();
+  } catch {
+    return [];
+  }
+}
+
+// Whether a session's hc core runs, without starting it: its socket (named in core.lock)
+// takes a connection.
+export function coreUp(session, timeoutMs = 1000) {
+  let socket;
+  try {
+    socket = fs.readFileSync(path.join(hcStateRoot(), session, 'core.lock'), 'utf8').trim().split('\n')[0];
+  } catch {
+    return Promise.resolve(false);
+  }
+  return new Promise((resolve) => {
+    const c = net.connect(socket);
+    const done = (up) => { c.destroy(); resolve(up); };
+    c.once('connect', () => done(true));
+    c.once('error', () => done(false));
+    setTimeout(() => done(false), timeoutMs);
+  });
+}
+
+// herdr-app names the tab with this id (it may take a few seconds to show it), when
+// herdr-app runs on this machine; resolves false when it is not there or never shows it.
+const TAB_TRIES = 10;
+export async function nameTab(tabId, name, { tries = TAB_TRIES, waitMs = 1000 } = {}) {
+  const app = (args) => new Promise((resolve, reject) => execFile('herdr-app', args, { env: ENV, timeout: 10000 }, (err, stdout) => (err ? reject(err) : resolve(stdout))));
+  for (let i = 0; i < tries; i += 1) {
+    let spaces;
+    try {
+      spaces = JSON.parse(await app(['ls'])).spaces || [];
+    } catch {
+      return false; // no herdr-app here, or no window
+    }
+    const found = spaces.flatMap((s) => s.tabs || []).find((t) => t.id === tabId || t.id.endsWith(`/${tabId}`));
+    if (found) {
+      if (found.name !== name) await app(['do', 'tab.rename', '--id', found.id, '--name', name]);
+      return true;
+    }
+    await new Promise((r) => setTimeout(r, waitMs));
+  }
+  return false;
+}
+
 // A failed hc call as a person reads it: hc's own message, without the command line or
 // its JSON wrapping.
 export function plainError(err) {

package/lib/core/log.mjs

@@ -9,6 +9,9 @@ import path from 'node:path';
 import util from 'node:util';
 
 const KEEP_DAYS = 14;
+
+// A log file per local day (what "today" means to you); the time on each line is UTC.
+export const localDay = (d = new Date()) => `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
 const CRASH_WAIT_MS = 3000;
 
 export function createLog(dir) {
@@ -19,7 +22,7 @@ export function createLog(dir) {
   const prune = (today) => {
     if (pruned === today) return;
     pruned = today;
-    const oldest = new Date(Date.now() - KEEP_DAYS * 86400 * 1000).toISOString().slice(0, 10);
+    const oldest = localDay(new Date(Date.now() - KEEP_DAYS * 86400 * 1000));
     for (const f of fs.readdirSync(dir)) {
       if (/^\d{4}-\d{2}-\d{2}\.log$/.test(f) && f.slice(0, 10) < oldest) fs.rmSync(path.join(dir, f), { force: true });
     }
@@ -32,8 +35,8 @@ export function createLog(dir) {
     const line = `${now} ${level} ${text}`;
     (level === 'ERROR' ? out.error : out.log)(line);
     try {
-      fs.appendFileSync(path.join(dir, `${now.slice(0, 10)}.log`), `${line}\n`, { mode: 0o600 }); // it quotes your messages
-      prune(now.slice(0, 10));
+      fs.appendFileSync(path.join(dir, `${localDay()}.log`), `${line}\n`, { mode: 0o600 }); // it quotes your messages
+      prune(localDay());
     } catch {
       // the disk is the last resort; stdout has the line
     }

package/lib/core/readers/index.mjs

@@ -16,7 +16,7 @@
 // Cursors are in ../cursor.mjs.
 //
 // To add an agent: write lib/core/readers/<agent>.mjs and list it in LISTED below
-// (docs/architecture.md, "Adding a harness").
+// (docs/architecture.md, "Adding an agent").
 import path from 'node:path';
 import * as claude from './claude.mjs';
 

package/lib/core/service.mjs

@@ -76,6 +76,7 @@ const run = (cmd, args) => execFileSync(cmd, args, { encoding: 'utf8', stdio: ['
 
 // {kind, name, file, content, write, remove, installed, load, unload, restart, state,
 // nodeGone}, or null on a system with neither launchd nor systemd.
+// `profile` here is the profile's id (placesOf: the profile, tagged when its folder is moved).
 export function serviceOf({ profile, root, node, env, stateDir, platform = process.platform, home = os.homedir() }) {
   const script = path.join(root, 'bin', 'herdrchat.mjs');
   const out = path.join(stateDir, 'logs', 'service.out.log');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "herdrchat",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "Chat front-ends for hc: every terminal hc runs, in the chat app you use",
   "repository": {
     "type": "git",
@@ -37,6 +37,7 @@
   "devDependencies": {
     "@semantic-release/changelog": "^7.0.0",
     "@semantic-release/git": "^11.0.1",
-    "semantic-release": "^25.0.9"
+    "semantic-release": "^25.0.9",
+    "yaml": "^2.9.1"
   }
 }