herdrchat 1.1.2 → 1.2.1

package/README.md

@@ -2,7 +2,7 @@
 
 # herdrchat
 
-Every terminal hc runs, in the chat app you already use. Feishu first.
+Every terminal hc runs, in the chat app you already use: Feishu or Telegram.
 
 [English](README.md) · [简体中文](README.zh.md)
 
@@ -16,13 +16,15 @@ herdr-app has official phone and desktop apps. But to use them away from your de
 phone has to reach the machine that runs hc, so you first need a VPN or a private network.
 And on a small phone screen, working with an agent is clumsy.
 
-Feishu is already on your phone. herdrchat connects out to Feishu by itself, so there is
-nothing to set up on your network: no public IP, no VPN. Each terminal becomes a Feishu
-group. You read what the agent says while it works, tap buttons to answer its questions,
-send and receive images, and see all terminals on one overview card. Your phone rings
-only when an agent needs you or is done. It works with any agent hc runs.
+Your chat app is already on your phone. herdrchat connects out to it by itself, so there
+is nothing to set up on your network: no public IP, no VPN. Each herdr-app tab becomes a
+Feishu group, or a topic in your private chat with the Telegram bot. You read what the
+agent says while it works, tap buttons to answer its questions, send and receive images,
+and see all terminals on one overview. A new room starts with the conversation so far.
+Your phone rings only when an agent needs you or is done. It works with any agent hc
+runs.
 
-Feishu comes first. When we have time, Slack, Discord and Telegram may follow.
+Use one app or both at once (a profile each). Slack and Discord may follow.
 
 ## Install
 
@@ -35,18 +37,22 @@ Then ask your agent:
 
 | Command | What it does |
 |---|---|
-| `/herdrchat setup` | Sets everything up with you: the Feishu app, the settings, the first start. |
+| `/herdrchat setup` | Sets everything up with you: the Feishu app or the Telegram bot, the settings, the first start. |
 | `/herdrchat status` | Says whether it runs, and what is wrong if anything is. |
 | `/herdrchat fix` | Finds the cause of a problem and fixes it. |
 | `/herdrchat config` | Changes a setting: which terminals, which groups stay quiet, tags. |
 | `/herdrchat feishu <task>` | Does a task in the Feishu developer console for you. |
+| `/herdrchat telegram <task>` | The Telegram bot, from @BotFather to the first topic. |
 
-On the command line, without an agent: `herdrchat init`, `start`, `stop`, `status`, `logs`.
+On the command line, without an agent: `herdrchat init`, `start`, `stop`, `status`, `logs`;
+`herdrchat install` runs it as a service that starts at login and comes back after a
+crash. Add `--profile <name>` for a second chat app.
 
 ## Where things are
 
-Settings in `~/.config/herdrchat/default/config.env`, everything the bot writes in
-`~/.local/state/herdrchat/default/`. Updating or reinstalling herdrchat never touches them.
+Settings in `~/.config/herdrchat/<profile>/config.env`, everything the bot writes in
+`~/.local/state/herdrchat/<profile>/` (the profile is `default` unless you name one).
+Updating or reinstalling herdrchat never touches them.
 
 How it works and every setting: [docs/guide.md](docs/guide.md).
 

package/README.zh.md

@@ -2,7 +2,7 @@
 
 # herdrchat
 
-hc 跑的每个终端，都能在你常用的聊天软件里看到和回复。先支持飞书。
+hc 跑的每个终端，都能在你常用的聊天软件里看到和回复：飞书或 Telegram。
 
 [English](README.md) · [简体中文](README.zh.md)
 
@@ -15,12 +15,13 @@ hc 跑的每个终端，都能在你常用的聊天软件里看到和回复。
 herdr-app 官方有手机端和电脑端。但想在外面用，手机得能连到跑 hc 的机器，
 所以要先折腾 VPN 或内网环境；而且在手机的小屏幕上和 agent 交互，体验并不好。
 
-飞书本来就在你手机上。herdrchat 自己主动连到飞书，网络上什么都不用配：不要公网 IP，也不要 VPN。
-每个终端就是一个飞书群：agent 干活时说的话实时可见，它问你的问题点按钮就能回答，
-图片双向都能传，所有终端汇总在一张总览卡片上。只有 agent 需要你、或者做完的时候手机才会响。
+聊天软件本来就在你手机上。herdrchat 自己主动连过去，网络上什么都不用配：不要公网 IP，也不要 VPN。
+herdr-app 的每个标签页，在飞书里是一个群，在 Telegram 里是和 bot 私聊中的一个话题：
+agent 干活时说的话实时可见，它问你的问题点按钮就能回答，图片双向都能传，所有终端汇总在一张总览里。
+新开的群或话题会先补上之前的对话。只有 agent 需要你、或者做完的时候手机才会响。
 hc 能跑的 agent 都能用，我们自己用下来非常顺畅。
 
-先支持飞书。后面有精力的话，也会考虑接入 Slack、Discord、Telegram 等其他聊天软件。
+可以只用一个，也可以两个同时用（各开一个 profile）。后面有精力的话，也会考虑接入 Slack、Discord。
 
 ## 安装
 
@@ -33,17 +34,19 @@ npm install -g herdrchat                   # skill 要用到的 herdrchat 命令
 
 | 命令 | 做什么 |
 |---|---|
-| `/herdrchat setup` | 和你一起从零配好：飞书应用、配置、第一次启动。 |
+| `/herdrchat setup` | 和你一起从零配好：飞书应用或 Telegram bot、配置、第一次启动。 |
 | `/herdrchat status` | 告诉你它在不在跑，有问题的话问题在哪。 |
 | `/herdrchat fix` | 找出问题的原因并修好。 |
 | `/herdrchat config` | 改配置：接哪些终端、哪些群保持安静、标签。 |
 | `/herdrchat feishu <任务>` | 替你在飞书开发者后台完成操作。 |
+| `/herdrchat telegram <任务>` | Telegram bot：从 @BotFather 一直到第一个话题。 |
 
-不用 agent 也可以直接在命令行里用：`herdrchat init`、`start`、`stop`、`status`、`logs`。
+不用 agent 也可以直接在命令行里用：`herdrchat init`、`start`、`stop`、`status`、`logs`；
+`herdrchat install` 把它装成系统服务，开机自动启动，崩溃后自动重启。第二个聊天软件加 `--profile <名字>`。
 
 ## 文件在哪
 
-配置在 `~/.config/herdrchat/default/config.env`，bot 写的东西都在 `~/.local/state/herdrchat/default/`。
+配置在 `~/.config/herdrchat/<profile>/config.env`，bot 写的东西都在 `~/.local/state/herdrchat/<profile>/`（没指定 profile 时就是 `default`）。
 更新或重装 herdrchat 都不会动它们。
 
 工作原理和全部配置：[docs/guide.md](docs/guide.md)（英文）。

package/bin/cli.mjs

@@ -2,12 +2,15 @@
 // herdrchat's command line: set up, start, stop and look at one profile.
 //
 //   herdrchat <command> [--profile <name>]
-//     init     make the profile's config.env from the example when it is missing
-//     start    start (or restart) it in its own hc terminal, kept running
-//     stop     stop it
-//     status   running or not, its folders, sessions, /auth, errors today
-//     logs     today's log (-n <lines>, --errors for ERROR and WARN only)
-//     run      run in the foreground (what start keeps running)
+//     init       make the profile's config.env from the example when it is missing
+//     install    run it as a service of the system (launchd, systemd): it starts at
+//                login and comes back after a crash; start, stop, status go through it
+//     uninstall  no service any more (it is stopped)
+//     start      start (or restart) it: the service, or else its own hc terminal
+//     stop       stop it
+//     status     how it runs, its folders, sessions, its chat app, errors today
+//     logs       today's log (-n <lines>, --errors for ERROR and WARN only)
+//     run        run in the foreground (what start keeps running)
 //
 // The profile is --profile or HERDRCHAT_PROFILE (default "default"); where its files are
 // is in lib/core/config.mjs.
@@ -18,12 +21,14 @@ import { fileURLToPath } from 'node:url';
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const USAGE = `herdrchat <command> [--profile <name>]
 
-  init     make the profile's config.env from the example when it is missing
-  start    start (or restart) it in its own hc terminal, kept running
-  stop     stop it
-  status   running or not, its folders, sessions, /auth, errors today
-  logs     today's log (-n <lines>, --errors for ERROR and WARN only)
-  run      run in the foreground (what start keeps running)`;
+  init       make the profile's config.env from the example when it is missing
+  install    run it as a service of the system: starts at login, back after a crash
+  uninstall  no service any more (it is stopped)
+  start      start (or restart) it: the service, or else its own hc terminal
+  stop       stop it
+  status     how it runs, its folders, sessions, its chat app, errors today
+  logs       today's log (-n <lines>, --errors for ERROR and WARN only)
+  run        run in the foreground (what start keeps running)`;
 
 const argv = process.argv.slice(2);
 const flag = (name) => {
@@ -42,6 +47,7 @@ const command = argv.find((a) => !a.startsWith('-'));
 // after the profile is set: lib/core/config.mjs reads it when it loads
 const { CONFIG_FILE, STATE_DIR, loadConfig, makeDirs, placesOf } = await import('../lib/core/config.mjs');
 const { hc } = await import('../lib/core/hc.mjs');
+const { serviceOf } = await import('../lib/core/service.mjs');
 const places = placesOf();
 
 const shellQuote = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
@@ -86,6 +92,26 @@ async function waitConnected(since) {
   return { ok: false, errors: [...new Set(errors.map((l) => l.slice(25)))].slice(-5) };
 }
 
+// What the bot needs wherever it runs (hc starts a program with the core's environment,
+// and a service with almost none): hc's full path, our PATH, the profile and the folders.
+// Nothing else, so no agent's variables come along.
+function botEnv() {
+  const hcPath = findHc();
+  if (!hcPath) throw new Error('hc is not on PATH: install herdr-core first (https://herdr.app)');
+  const env = { HERDRCHAT_HC: hcPath, HERDRCHAT_PROFILE: places.profile };
+  for (const k of ['PATH', 'HERDRCHAT_HOME', 'XDG_CONFIG_HOME', 'XDG_STATE_HOME']) if (process.env[k]) env[k] = process.env[k];
+  return env;
+}
+
+const service = () => serviceOf({ profile: places.profile, root: ROOT, node: process.execPath, env: botEnv(), stateDir: STATE_DIR });
+
+function failedToConnect(where, result) {
+  console.error(`${where} but did not reach its chat app within ${CONNECT_WAIT_MS / 1000} s.`);
+  if (result.errors.length) console.error(`Its errors:\n  ${result.errors.join('\n  ')}`);
+  console.error('It keeps retrying; `herdrchat logs --errors` shows more.');
+  process.exitCode = 1;
+}
+
 async function terminalState(session) {
   try {
     return JSON.parse(await hc(session, ['get', places.terminal, '--json'])).state;
@@ -106,53 +132,97 @@ const commands = {
     console.log(`Made ${CONFIG_FILE}: fill in the app id, the secret and HERDR_SESSIONS.`);
   },
 
+  // The service file is written again each time (a moved node or hc is picked up), and
+  // the bot in an hc terminal is stopped first: two bots would answer every message.
+  async install() {
+    const svc = service();
+    if (!svc) throw new Error(`no launchd or systemd on ${process.platform}: run \`herdrchat start\` instead`);
+    loadConfig(); // a config that cannot start the bot fails here, not in the service
+    await stopEverywhere();
+    svc.unload();
+    svc.write(svc.content);
+    const since = new Date().toISOString();
+    svc.load();
+    const result = await waitConnected(since);
+    if (!result.ok) return failedToConnect(`The ${svc.kind} service ${svc.name} is installed`, result);
+    console.log(`Installed the ${svc.kind} service ${svc.name} (${svc.file}); it is running, connected to its chat app, starts at login and comes back after a crash.`);
+    if (svc.kind === 'systemd') console.log('To keep it running after you log out: loginctl enable-linger');
+  },
+
+  async uninstall() {
+    const svc = service();
+    if (!svc?.installed()) {
+      console.log('No herdrchat service is installed for this profile.');
+      return;
+    }
+    svc.unload();
+    svc.remove();
+    console.log(`Removed the ${svc.kind} service ${svc.name}; the bot is stopped. \`herdrchat start\` runs it in an hc terminal again.`);
+  },
+
   async start() {
+    await stopEverywhere();
+    const svc = service();
+    const since = new Date().toISOString();
+    if (svc?.installed()) {
+      if (svc.loaded()) svc.restart();
+      else svc.load();
+      const result = await waitConnected(since);
+      if (!result.ok) return failedToConnect(`The ${svc.kind} service ${svc.name} started`, result);
+      console.log(`Started the ${svc.kind} service ${svc.name} (profile ${places.profile}); connected to its chat app.`);
+      return;
+    }
     const session = firstSession();
-    const hcPath = findHc();
-    if (!hcPath) throw new Error('hc is not on PATH: install herdr-core first (https://herdr.app)');
-    // hc starts a program with the core's environment, not ours, and a core started by a
-    // service may not have hc on its PATH: hc's full path, our PATH, the profile and the
-    // folders go along
-    const env = [['HERDRCHAT_HC', hcPath], ...['PATH', 'HERDRCHAT_PROFILE', 'HERDRCHAT_HOME', 'XDG_CONFIG_HOME', 'XDG_STATE_HOME'].map((k) => [k, process.env[k]])]
-      .filter(([, v]) => v)
-      .map(([k, v]) => `${k}=${shellQuote(v)}`)
-      .join(' ');
+    const env = Object.entries(botEnv()).map(([k, v]) => `${k}=${shellQuote(v)}`).join(' ');
     const run = `env ${env} ${shellQuote(process.execPath)} ${shellQuote(path.join(ROOT, 'bin', 'herdrchat.mjs'))}`;
     const loop = `while true; do ${run}; echo 'herdrchat exited, restarting in 3 s'; sleep 3; done`;
-    await stopEverywhere();
-    const since = new Date().toISOString();
     await hc(session, ['run', '--bg', '--no-parent', '--name', places.terminal, '--cwd', ROOT, '--', 'sh', '-c', loop]);
     const result = await waitConnected(since);
-    if (!result.ok) {
-      console.error(`${places.terminal} started in hc session ${session} but did not reach its chat app within ${CONNECT_WAIT_MS / 1000} s.`);
-      if (result.errors.length) console.error(`Its errors:\n  ${result.errors.join('\n  ')}`);
-      console.error('It keeps retrying; `herdrchat logs --errors` shows more.');
-      process.exitCode = 1;
-      return;
-    }
-    console.log(`Started ${places.terminal} (profile ${places.profile}) in hc session ${session}; connected to its chat app.`);
+    if (!result.ok) return failedToConnect(`${places.terminal} started in hc session ${session}`, result);
+    console.log(`Started ${places.terminal} (profile ${places.profile}) in hc session ${session}; connected to its chat app. \`herdrchat install\` makes it a service that starts at login and comes back after a crash.`);
   },
 
   async stop() {
     await stopEverywhere();
-    console.log(`Stopped ${places.terminal}. Until it starts again, nothing reaches Feishu.`);
+    const svc = service();
+    if (svc?.installed()) svc.unload(); // stays installed: \`herdrchat start\` loads it again; at login it starts again
+    console.log(`Stopped herdrchat (profile ${places.profile}). Until it starts again, nothing reaches its chat app.`);
   },
 
   async status() {
-    console.log(`profile   ${places.profile} (hc terminal ${places.terminal})`);
+    console.log(`profile   ${places.profile}`);
     console.log(`settings  ${CONFIG_FILE}${fs.existsSync(CONFIG_FILE) ? '' : '  (missing: run `herdrchat init`)'}`);
     console.log(`state     ${STATE_DIR}`);
     if (!fs.existsSync(CONFIG_FILE)) return;
     const cfg = loadConfig();
     console.log(`sessions  ${cfg.sessions.join(', ')}`);
-    console.log(`running   ${(await terminalState(cfg.sessions[0])) === 'live' ? 'yes' : 'no (`herdrchat start`)'}`);
-    let token = null;
-    try {
-      token = JSON.parse(fs.readFileSync(path.join(STATE_DIR, 'user-token.json'), 'utf8'));
-    } catch {
-      // no /auth yet
+    // how it runs: the service, an hc terminal, or not at all
+    const svc = service();
+    const inTerminal = (await terminalState(cfg.sessions[0])) === 'live';
+    if (svc?.installed()) {
+      const st = svc.state();
+      console.log(`running   ${st.running ? `yes, as the ${svc.kind} service ${svc.name}${st.pid ? ` (pid ${st.pid})` : ''}` : `no: the ${svc.kind} service ${svc.name} is stopped (\`herdrchat start\`)`}`);
+      const gone = svc.nodeGone();
+      if (gone) console.log(`          the service runs ${gone}, which is gone (node moved): \`herdrchat install\` again`);
+      if (inTerminal) console.log(`          also in hc terminal ${places.terminal}: two bots; \`herdrchat start\` keeps one`);
+    } else {
+      console.log(`running   ${inTerminal ? `yes, in hc terminal ${places.terminal} (session ${cfg.sessions[0]}); \`herdrchat install\` makes it a service` : 'no (`herdrchat start`, or `herdrchat install` for a service)'}`);
+    }
+    // what its chat app needs, without printing a secret
+    console.log(`chat      ${cfg.chat}`);
+    if (cfg.chat === 'feishu') {
+      let token = null;
+      try {
+        token = JSON.parse(fs.readFileSync(path.join(STATE_DIR, 'user-token.json'), 'utf8'));
+      } catch {
+        // no /auth yet
+      }
+      console.log(`owner     ${cfg.ownerOpenId ? 'set' : 'not set: message the bot, it says what to put in config.env'}`);
+      console.log(`/auth     ${!token ? 'not done (muting, labels and pins need it)' : (token.refreshUntil || 0) > Date.now() ? 'done' : 'expired: send /auth again'}`);
+    } else if (cfg.chat === 'telegram') {
+      console.log(`token     ${cfg.env.TELEGRAM_BOT_TOKEN ? 'set' : 'missing: TELEGRAM_BOT_TOKEN from @BotFather'}`);
+      console.log(`owner     ${cfg.env.TELEGRAM_OWNER_ID ? 'set' : 'not set: message the bot, it says what to put in config.env'}`);
     }
-    console.log(`/auth     ${!token ? 'not done' : (token.refreshUntil || 0) > Date.now() ? 'done' : 'expired: send /auth again'}`);
     const log = path.join(STATE_DIR, 'logs', `${new Date().toISOString().slice(0, 10)}.log`);
     if (fs.existsSync(log)) {
       const text = fs.readFileSync(log, 'utf8');

package/docs/guide.md

@@ -2,9 +2,11 @@
 
 How herdrchat works and every setting, for when the README is not enough.
 
-herdrchat is a chat front-end for hc: every terminal hc runs, followed and answered in a
-chat app. Feishu is the first (one bot); Slack, Discord and Telegram may follow, on the
-same core (hc events, a reader per agent, dialogs, the overview) with an adapter each.
+herdrchat is a chat front-end for hc: every herdr-app tab, followed and answered in a chat
+app, Feishu or Telegram. Both sit on the same core (hc events, a reader per agent,
+dialogs, the overview), each behind one contract (`docs/architecture.md`); Slack and
+Discord may follow the same way. A profile is one chat app (`HERDRCHAT_CHAT`); to use
+both, run a profile each.
 
 ## Feishu
 
@@ -21,6 +23,24 @@ herdr-app, moved into one Feishu bot:
 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.
 
+## 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):
+
+| 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 |
+
+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`.
+
 ## How it works: hc, plus a reader per agent
 
 **hc is the backbone.** The bot follows `hc events --json` for each session (format:
@@ -36,13 +56,14 @@ each agent a reader reads the agent's own records. The status hc reports names t
 | `status.app` | reader | reads |
 |---|---|---|
 | `claude-code` | `lib/core/readers/claude.mjs` | its transcript: the terminal's foreground pid names the session in `~/.claude/sessions/<pid>.json` |
-| anything else | none (default) | the screen, through `hc read` |
+| 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, write `lib/core/readers/<agent>.mjs` (the contract is at the top of
-`lib/core/readers/index.mjs`) and list it there.
+agent: `docs/architecture.md`, "Adding a harness".
+
+## What a room shows
 
-## What a group shows
+A room is a Feishu group or a Telegram topic.
 
 - A program with a reader:
   - while it works: one "⌛️ Working…" card per turn (then "✅ Worked"), edited every 5
@@ -50,9 +71,12 @@ agent, write `lib/core/readers/<agent>.mjs` (the contract is at the top of
     mid-turn) as **You:**, and each tool it calls as one line (`▸ Bash: Run the tests`).
     It shows the program is alive, as herdr-app does, and since an edit is not a new
     message, the phone does not ring every few seconds;
-  - when the turn ends: its last answer, as a new message. Without `/auth` you are
-    notified when a turn starts and when it is done; with it, groups are muted and only
-    an @ under the answer rings (see "Optional: let the bot act as you").
+  - when the turn ends: its last answer, as a new message. In a space of
+    `HERDR_MUTED_SPACES` (all, by default) only "needs you" and "done" ring: in Feishu
+    the groups are muted (after `/auth`) and an @ under the answer rings; in Telegram
+    the posts go silently and a short reply rings. `HERDR_SILENT_SPACES` rings nothing.
+  - A message another terminal sent with `hc send` shows as **From t7 review**, not as
+    yours (hc wraps it in `<hc from="…">`, for any agent).
   - Images too: ones it looked at (a screenshot, an image file it read) and ones you
     pasted in the terminal, shown in the card.
   - What you sent from the group is not repeated.
@@ -63,15 +87,21 @@ agent, write `lib/core/readers/<agent>.mjs` (the contract is at the top of
   a red "⚠️ Needs you" card. When the screen shows a numbered menu (as Claude Code's
   permission and question dialogs do), the card shows only the dialog, as text, with a
   button per option; a multi-select also has "Next ⇥", a "Type something" option a box to
-  type in, and every card "Esc". Without a menu the card shows the screen and how to
-  answer by typing. Once the dialog is gone the card turns to "✅ Done".
-
-## Answering a dialog from Feishu
-
-A button presses that option's number key in the terminal (Next presses tab, Esc esc).
+  type in (Feishu; in Telegram you type the answer in the topic), and every card "Esc".
+  Without a menu the card shows the last lines of the screen and how to answer by typing.
+  Once the dialog is gone the card turns to "✅ Done". A card is posted only for a dialog
+  that still waits: one answered while its screen was read gets none.
+
+## Answering a dialog from the chat
+
+A button presses that option's number key in the terminal (Esc presses esc). A question
+with previews (a box beside its options) takes no number, so there the button moves with
+the arrows from the cursor to that option and presses Enter. In a multi-select, a box is
+ticked on the card only, at once; Next sends them all: each box that differs from the
+screen is pressed, then tab.
 Before it presses anything, the bot reads the screen again and checks that it still
-shows the same dialog (a hash of it, from its top border to its last option) and the
-same option, so an old card can never answer a newer dialog that looks alike. After the
+shows the same dialog (a hash of it, from its top border to its last option, without the
+cursor, the check marks and the preview box) and the same option, so an old card can never answer a newer dialog that looks alike. After the
 key, the card turns into the dialog's next step (a toggled box, the next question, the
 review) or says what was picked. Text you type in the group while it waits goes into its
 "Type something" box when it has one.
@@ -123,14 +153,17 @@ delivered (the terminal has ended) says so plainly.
   recalled), `/new <session> <space>/<tab> [command]` (start one; default `claude`;
   `--cwd <dir>` first to pick its folder), `/kill <session> <address>`, `/auth` (see
   below).
-- In a terminal's group: any text goes to it (marked THINKING once typed in, then OK when
-  the turn that took it is over); an image (alone or in a rich text message) is sent
+- 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
   text, so an agent like Claude Code opens it; `/screen`, `/answer <text>` (type into the
-  dialog it waits on, as is), `/esc`. Dialog cards have buttons.
+  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.
 
@@ -152,6 +185,24 @@ Steps 1, 2, 5 and 6 are in the Feishu developer console; the herdrchat skill
 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").
+
+## Running as a service
+
+`herdrchat start` runs the bot in an hc terminal, which ends when that hc core stops,
+and nothing starts it after a reboot. `herdrchat install` makes it a service of the
+system instead: a launchd agent on macOS, a systemd user unit on Linux. It starts at
+login, comes back by itself after a crash, and does not depend on any hc core. It runs
+node and the bot by their full paths with only the variables it needs (hc's path, PATH,
+the profile, the folders), so no agent's variables come along. With it installed,
+`start`, `stop` and `status` go through the service; `herdrchat uninstall` removes it.
+Each profile is its own service (`herdrchat install --profile telegram`).
+
+- After a node upgrade that moves node, run `herdrchat install` again; `herdrchat status`
+  says when the service's node is gone.
+- On Linux, `loginctl enable-linger` keeps it running after you log out.
+- What the process prints before its log is open (a crash at start) goes to
+  `logs/service.out.log` in the state folder.
 
 ## Optional: let the bot act as you
 
@@ -181,9 +232,10 @@ refreshed, the bot says so once and falls back.
 ## Skills
 
 `skills/herdrchat/` is one skill for an agent (Claude Code or another that reads
-`SKILL.md`): `/herdrchat setup`, `status`, `start`, `stop`, `logs`, `auth`, `config`, `fix`
-and `feishu <task>` (the developer console, with Ego Lite from https://lite.ego.app/ or as
-a guided walk-through). Details per part are in `skills/herdrchat/references/`. To use it
+`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`.
 
@@ -191,7 +243,7 @@ with Claude Code, link it where skills are read, for example
 
 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/default/logs/*.log` finds
+~/.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.
@@ -199,12 +251,15 @@ skill's `references/ops.md` explains the lines.
 ## Limits
 
 - Narration blocks are a condensed version of the text Claude showed, not the exact words.
-- Only Claude Code has a reader so far. codex, pi and the rest get their screen, at turn
-  end only, until each has a reader.
+- Only Claude Code has a reader so far. codex, pi and the rest post nothing by themselves
+  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 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.
+- Telegram: a bot cannot mute a topic for you; a topic you mute in Telegram stays fully
+  quiet, "needs you" included. Closing a topic is documented for supergroups only, so an
+  ended topic is marked by its name.
 - Dialog buttons come from the screen's numbered menu; a dialog drawn some other way gets
   the screen and `/answer`, `/esc`.

package/lib/chats/feishu/client.mjs

@@ -258,7 +258,8 @@ 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.
-export function startEvents(cfg, onMessage, onCardAction, onReady = () => {}) {
+// onConnect runs at every connection, the first and each one after a drop.
+export function startEvents(cfg, onMessage, onCardAction, onReady = () => {}, onConnect = () => {}) {
   const ws = new Lark.WSClient({
     appId: cfg.appId,
     appSecret: cfg.appSecret,
@@ -266,9 +267,13 @@ export function startEvents(cfg, onMessage, onCardAction, onReady = () => {}) {
     onReady: () => {
       console.log('[feishu] connected');
       onReady();
+      onConnect();
     },
     onReconnecting: () => console.warn('[feishu] reconnecting'),
-    onReconnected: () => console.log('[feishu] reconnected'),
+    onReconnected: () => {
+      console.log('[feishu] reconnected');
+      onConnect();
+    },
     onError: (err) => console.error(`[feishu] connection failed: ${err.message}`),
   });
   ws.start({

package/lib/chats/feishu/index.mjs

@@ -401,13 +401,40 @@ export function create({ cfg, store, log, logWarn, logError, stateDir, lane, sco
 
   // Messages (deduplicated, the owner's only) and card clicks, turned into the core's
   // shape: {room (null: the direct chat), where, message, text, images}.
+  //
+  // Feishu wants an event handled within 3 seconds or it pushes it again, so a message is
+  // taken at once and then handled in its chat's own queue (in order). Whether Feishu
+  // sends again what came while the bot was offline is not documented, so the bot looks
+  // itself: per chat it keeps the time of the last message it handled (state.json
+  // feishuRead), and at every connection it lists what came after that and handles what
+  // it missed.
   const seen = new Set();
+  const queues = new Map(); // chat -> its last queued message
+  function queued(chatId, fn) {
+    const next = (queues.get(chatId) || Promise.resolve()).then(fn).catch((err) => logError(`feishu message in ${chatId}:`, err));
+    queues.set(chatId, next);
+    next.then(() => { if (queues.get(chatId) === next) queues.delete(chatId); });
+  }
+  function markRead(chatId, at) {
+    const state = read();
+    if ((state.feishuRead?.[chatId] || 0) >= at) return;
+    state.feishuRead = { ...(state.feishuRead || {}), [chatId]: at };
+    write(state);
+  }
+
   function start({ onMessage, onAction, onReady }) {
-    const handleMessage = async (data) => {
+    const take = (data) => {
       const msg = data.message;
       if (seen.has(msg.message_id)) return;
       seen.add(msg.message_id);
-      if (seen.size > 1000) seen.delete(seen.values().next().value);
+      if (seen.size > 2000) seen.delete(seen.values().next().value);
+      queued(msg.chat_id, async () => {
+        await handleMessage(data);
+        markRead(msg.chat_id, Number(msg.create_time) || Date.now());
+      });
+    };
+    const handleMessage = async (data) => {
+      const msg = data.message;
       const openId = data.sender?.sender_id?.open_id;
       if (!cfg.ownerOpenId) {
         log(`owner not set; message from open_id ${openId}`);
@@ -437,7 +464,30 @@ export function create({ cfg, store, log, logWarn, logError, stateDir, lane, sco
       if (out.card?.kind === 'dialog') res.card = { type: 'raw', data: menuCard({ title: out.card.dialog.title, markdown: out.card.dialog.markdown, menu: out.card.dialog.menu, value: out.card.value }) };
       return res;
     };
-    startEvents(cfg, handleMessage, handleAction, onReady);
+    // What came while the bot was away: the owner's messages after the last one handled,
+    // in every chat it reads (a chat with none handled yet starts from now).
+    const catchUp = async () => {
+      if (!cfg.ownerOpenId) return;
+      const state = read();
+      const chats = new Set([...Object.values(state.chats || {}).filter((c) => !c.ended).map((c) => c.chat), ...Object.keys(state.feishuRead || {})]);
+      for (const chatId of chats) {
+        const since = state.feishuRead?.[chatId];
+        if (!since) {
+          markRead(chatId, Date.now());
+          continue;
+        }
+        try {
+          const res = await client.im.v1.message.list({ params: { container_id_type: 'chat', container_id: chatId, start_time: String(Math.floor(since / 1000)), sort_type: 'ByCreateTimeAsc', page_size: 50 } });
+          const missed = (res?.data?.items || []).filter((m) => Number(m.create_time) > since && m.sender?.sender_type === 'user' && m.sender?.id === cfg.ownerOpenId && !seen.has(m.message_id));
+          if (missed.length) log(`feishu: ${missed.length} message(s) in ${chatId} came while the bot was away`);
+          const p2p = !Object.values(state.chats || {}).some((c) => c.chat === chatId);
+          for (const m of missed) take({ message: { message_id: m.message_id, chat_id: chatId, chat_type: p2p ? 'p2p' : 'group', message_type: m.msg_type, content: m.body?.content || '{}', create_time: m.create_time }, sender: { sender_id: { open_id: m.sender.id } } });
+        } catch (err) {
+          logWarn(`feishu: could not look for missed messages in ${chatId}: ${err.message}`);
+        }
+      }
+    };
+    startEvents(cfg, take, handleAction, onReady, () => catchUp().catch((err) => logError(`feishu catch-up: ${err.message}`)));
     setInterval(() => asYou().catch((err) => logError(`as you: ${err.message}`)), YOU_CHECK_MS);
     asYou().catch((err) => logError(`as you: ${err.message}`));
   }

package/lib/chats/telegram/index.mjs

@@ -13,9 +13,10 @@
 //                 topic's name gets a 🔚 in front, taken off when it is live again
 //   images        a message cannot hold one, so each goes as its own photo after the text
 //   buttons       callback_data holds 64 bytes, so a button carries a short id and the
-//                 dialog it answers is kept here
+//                 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
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import { createClient } from './client.mjs';
 import { escapeHtml, split, toHtml } from './format.mjs';
@@ -133,14 +134,17 @@ export function create({ cfg, store, log, logWarn, logError }) {
 
   // ---------- dialogs ----------
 
-  // A button carries "<id>:<pick>"; the id names the dialog's value, kept here (a click
-  // after a restart finds nothing and is told the dialog is gone).
-  const buttons = new Map();
-  let buttonN = 0;
+  // A button carries "<id>:<pick>"; the id names the dialog's value (the newest
+  // BUTTONS_KEPT; an older card is told its dialog is gone).
+  // They are kept in state.json (buttons), so a card still answers after a restart.
   function keyboard(dialog, value) {
-    const id = (buttonN += 1).toString(36);
-    buttons.set(id, { value, labels: Object.fromEntries(dialog.menu.options.map((o) => [o.n, o.label])) });
-    if (buttons.size > BUTTONS_KEPT) buttons.delete(buttons.keys().next().value);
+    const id = crypto.randomBytes(6).toString('base64url');
+    const state = read();
+    const kept = { ...(state.buttons || {}), [id]: { value, labels: Object.fromEntries(dialog.menu.options.map((o) => [o.n, o.label])) } };
+    const ids = Object.keys(kept);
+    for (const old of ids.slice(0, Math.max(0, ids.length - BUTTONS_KEPT))) delete kept[old];
+    state.buttons = kept;
+    write(state);
     const rows = [];
     for (const o of dialog.menu.options) {
       if (o === dialog.menu.free) continue;
@@ -326,10 +330,10 @@ export function create({ cfg, store, log, logWarn, logError }) {
     const answer = (text) => tg.call('answerCallbackQuery', { callback_query_id: q.id, text: (text || '').slice(0, 200) }).catch(() => {});
     if (String(q.from?.id) !== owner) return answer('Only the owner can answer.');
     const [id, pickRaw] = String(q.data || '').split(':');
-    const kept = buttons.get(id);
+    const kept = read().buttons?.[id];
     const message = String(q.message?.message_id || '');
     if (!kept) {
-      await edit(message, `${q.message?.text ? escapeHtml(q.message.text) : ''}\n\n<b>This dialog is gone (the bot restarted); see the newest card.</b>`, { reply_markup: { inline_keyboard: [] } }).catch(() => {});
+      await edit(message, `${q.message?.text ? escapeHtml(q.message.text) : ''}\n\n<b>This card is too old to answer; see the newest card.</b>`, { reply_markup: { inline_keyboard: [] } }).catch(() => {});
       return answer('This dialog is gone.');
     }
     const pick = /^\d+$/.test(pickRaw) ? Number(pickRaw) : pickRaw;
@@ -340,9 +344,12 @@ export function create({ cfg, store, log, logWarn, logError }) {
   }
 
   // Long polling: getUpdates holds up to POLL_SECONDS for news; a failure waits RETRY_MS
-  // and tries again (409: another copy of the bot polls the same token).
+  // and tries again (409: another copy of the bot polls the same token). Telegram keeps
+  // what the bot has not confirmed for 24 hours, so nothing sent while it was away is
+  // lost; which update it handled last is kept in state.json (telegramOffset), so after a
+  // restart nothing is handled twice.
   function start({ onMessage, onAction, onReady = () => {} }) {
-    let offset = 0;
+    let offset = read().telegramOffset || 0;
     let connected = false;
     (async () => {
       for (;;) {
@@ -361,13 +368,17 @@ export function create({ cfg, store, log, logWarn, logError }) {
           }
           const updates = await tg.call('getUpdates', { offset, timeout: POLL_SECONDS, allowed_updates: ['message', 'callback_query'] }, { timeoutMs: (POLL_SECONDS + 15) * 1000 });
           for (const u of updates) {
-            offset = u.update_id + 1;
             try {
               if (u.message) await handleMessage(u.message, onMessage);
               if (u.callback_query) await handleClick(u.callback_query, onAction);
             } catch (err) {
               logError(`telegram update ${u.update_id}:`, err);
             }
+            // saved once handled: a crash halfway handles it again, never skips it
+            offset = u.update_id + 1;
+            const state = read();
+            state.telegramOffset = offset;
+            write(state);
           }
         } catch (err) {
           logError(`telegram poll: ${err.message}`);

package/lib/core/engine.mjs

@@ -248,7 +248,7 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
   function transcriptOf(items) {
     const parts = [];
     for (const it of items) {
-      if (it.role === 'you') parts.push(`**You** · ${clock(it.at)}\n${it.text.split('\n').map((l) => `> ${l}`).join('\n')}`);
+      if (it.role === 'you') parts.push(youOrOthers(it.text, ` · ${clock(it.at)}`));
       else if (it.role === 'ai') parts.push(it.text);
       else if (it.role === 'tool') parts.push(it.text);
       else if (it.role === 'image') parts.push(`_(an image ${it.from === 'you' ? 'you pasted' : 'it looked at'})_`);
@@ -357,6 +357,23 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
   // What you sent from the chat; its room shows it already, so it is not posted again.
   const fromChat = new Map();
 
+  // A message another terminal sent with `hc send` reaches the agent wrapped by hc as
+  // <hc from="t7 review" reach="...">...</hc> (any agent: hc adds it), so it is shown as
+  // from that terminal, not as yours; what is around such notes is yours.
+  const HC_NOTE = /<hc from="([^"]*)"(?:\s+reach="([^"]*)")?>([\s\S]*?)<\/hc>/g;
+  const quoted = (text) => text.split('\n').map((l) => `> ${l}`).join('\n');
+  function youOrOthers(text, at = '') {
+    const parts = [];
+    let rest = text;
+    for (const m of text.matchAll(HC_NOTE)) {
+      parts.push(`**From ${m[1]}**${at}${m[2] ? ` _(answer: ${m[2]})_` : ''}\n${quoted(m[3].trim())}`);
+      rest = rest.replace(m[0], '');
+    }
+    rest = rest.trim();
+    if (rest) parts.unshift(`**You:**${at ? ` ${at.replace(/^ · /, '')}` : ''}\n${quoted(rest)}`);
+    return parts.join('\n\n');
+  }
+
   function formatItems(k, items) {
     const sent = fromChat.get(k) || [];
     const parts = [];
@@ -380,7 +397,7 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
           sent.splice(i, 1);
           continue;
         }
-        parts.push(`**You:**\n${it.text.split('\n').map((l) => `> ${l}`).join('\n')}`);
+        parts.push(youOrOthers(it.text));
       } else {
         parts.push(it.text);
       }
@@ -624,9 +641,17 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
     log(`<- ${session}/${address}: blocked${dialog.menu ? ` (${dialog.menu.options.length} options)` : ''}`);
   }
 
+  // The keys that pick an option: its digit, or, in a question with previews (which takes
+  // no digit), the arrows from the cursor to it and Enter.
+  function pickKeys(menu, option) {
+    if (!menu.beside) return [String(option.n)];
+    const moves = option.n - (menu.cursor || 1);
+    return [...Array(Math.abs(moves)).fill(moves > 0 ? 'down' : 'up'), 'enter'];
+  }
+
   // "Type something": pick that option, then type the words.
   async function answerFree(session, address, menu, text) {
-    await hc.keys(session, address, [String(menu.free.n)]);
+    await hc.keys(session, address, pickKeys(menu, menu.free));
     await sleep(300);
     await hc.send(session, address, text, { force: true });
   }
@@ -689,7 +714,7 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
         await answerFree(v.s, v.a, menu, text);
         picked = text;
       } else {
-        await hc.keys(v.s, v.a, [String(option.n)]);
+        await hc.keys(v.s, v.a, pickKeys(menu, option));
         picked = `${option.n}. ${option.label}`;
       }
     }
@@ -772,6 +797,7 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
     if (now !== was) since.set(k, Date.now());
     if (now !== 'blocked') {
       postedDialog.delete(k);
+      if (now) sendWaiting(k);
       if (chat.pinned().includes(k)) later(session, address, 'unpin', () => chat.unpin(k));
       if (openCard.has(k)) later(session, address, 'dialog', () => closeCard(k, '✔ Answered.'));
       return;
@@ -863,6 +889,23 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
     }
   }
 
+  // Messages sent while it waited on a dialog with no box to type in, per terminal, kept
+  // in state.json (waiting) so a restart does not lose them; they go in, in order, once it
+  // no longer waits (onStatus, and at start).
+  function hold(k, m) {
+    const state = read();
+    state.waiting = { ...(state.waiting || {}), [k]: [...(state.waiting?.[k] || []), m] };
+    write(state);
+  }
+  function sendWaiting(k) {
+    const state = read();
+    const held = state.waiting?.[k];
+    if (!held?.length) return;
+    delete state.waiting[k];
+    write(state);
+    for (const m of held) laneOf(k, 'held message', () => typeInto(m.where, m.message, m.session, m.address, m.text));
+  }
+
   async function typeInto(where, message, session, address, text) {
     const record = views.get(session)?.terminals.get(address);
     if (!record || record.state !== 'live') {
@@ -883,16 +926,21 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
       return;
     }
     const answer = text.match(/^\/answer\s+([\s\S]+)$/);
-    if (!answer && agent && record.status?.state === 'blocked') {
+    // whether it waits on a dialog now: asked of hc, since the status followed from its
+    // events can be a moment behind (a dialog just answered still looks blocked)
+    const waits = !answer && agent && (await hc.getTerminal(session, address).catch(() => record))?.status?.state === 'blocked';
+    if (waits) {
       // It waits on a dialog: words go into its "Type something" box when it has one;
-      // otherwise the dialog card comes again, to pick there.
+      // otherwise they wait for the dialog to be answered, then go in (never dropped).
       const menu = menuOf(await hc.screenTail(session, address, SCREEN_LINES));
       if (menu?.free) {
         await answerFree(session, address, menu, text);
         log(`-> ${session}/${address}: answered ${text.slice(0, 80)}`);
         await markWorking(key(session, address), message);
       } else {
-        await postBlocked(session, address, record, { again: true });
+        hold(key(session, address), { where, message, session, address, text });
+        log(`-> ${session}/${address}: held until its dialog is answered: ${text.slice(0, 80)}`);
+        await chat.reply(where, 'It asks something first (the card above). Your message goes in once that is answered.');
       }
       return;
     }
@@ -1032,6 +1080,7 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
       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.');
         return;
       }
       if (views.get(target.session)?.terminals.get(target.address)?.state !== 'live') {
@@ -1058,6 +1107,11 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
     for (const session of cfg.sessions) watch(session);
     ready.then(() => setTimeout(async () => {
       await endGone().catch((err) => logError(`end gone rooms: ${err.message}`));
+      // messages held before a restart, for terminals that no longer wait
+      for (const k of Object.keys(read().waiting || {})) {
+        const address = addressOfKey(k);
+        if (!cfg.sessions.some((s) => views.get(s)?.terminals.get(address)?.status?.state === 'blocked')) sendWaiting(k);
+      }
       // pins left from before a restart, for terminals that no longer wait
       for (const k of chat.pinned()) {
         const address = addressOfKey(k);

package/lib/core/menu.mjs

@@ -45,7 +45,8 @@ function keyOf(lines, top, last) {
 }
 
 export function menuOf(screen) {
-  const lines = screen.split('\n').map(ownPart);
+  const raw = screen.split('\n');
+  const lines = raw.map(ownPart);
   let run = null;
   let menu = null;
   lines.forEach((line, i) => {
@@ -63,7 +64,13 @@ export function menuOf(screen) {
   });
   if (!menu) return null;
   const top = topOf(lines, menu.first);
+  // A question with previews takes no digit (its keys say "↑/↓ to navigate"): an option
+  // is reached from the cursor (❯) with the arrows, then Enter.
+  const beside = raw.slice(menu.first, menu.last + 1).some((l) => BESIDE.test(l));
+  const cursor = menu.options.find((o, i) => raw.slice(menu.first, menu.last + 1).some((l) => /❯/.test(l) && new RegExp(`^\\s*❯\\s*${o.n}\\.`).test(l)))?.n || 1;
   return {
+    beside,
+    cursor,
     key: keyOf(lines, top, menu.last),
     framed: BORDER.test(lines[top]), // a dialog's top border; a numbered list in text has none
     text: lines.slice(top, menu.first).filter((l) => !RULE.test(l)).map((l) => l.trim()).join('\n'),

package/lib/core/service.mjs

@@ -0,0 +1,165 @@
+// herdrchat as a service of the system, so it starts at login and comes back by itself
+// after a crash, whatever happens to the hc cores: a launchd LaunchAgent on macOS, a
+// systemd user unit on Linux. `herdrchat install` makes it; start, stop and status then
+// go through it. Without it the bot runs in an hc terminal (`herdrchat start`), which
+// ends when that hc core stops.
+//
+// The service runs node and bin/herdrchat.mjs by their full paths, with only the
+// variables listed in `env` (no agent's variables come along): a node upgrade that moves
+// node needs `herdrchat install` again, which status says.
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const THROTTLE_S = 10; // launchd: at most one start in this many seconds
+const RESTART_S = 5; // systemd: wait before starting again
+
+const xml = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+export function launchdPlist({ label, node, script, root, env, out }) {
+  const vars = Object.entries(env).map(([k, v]) => `      <key>${xml(k)}</key>\n      <string>${xml(v)}</string>`).join('\n');
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key>
+    <string>${xml(label)}</string>
+    <key>ProgramArguments</key>
+    <array>
+      <string>${xml(node)}</string>
+      <string>${xml(script)}</string>
+    </array>
+    <key>WorkingDirectory</key>
+    <string>${xml(root)}</string>
+    <key>EnvironmentVariables</key>
+    <dict>
+${vars}
+    </dict>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>ThrottleInterval</key>
+    <integer>${THROTTLE_S}</integer>
+    <key>StandardOutPath</key>
+    <string>${xml(out)}</string>
+    <key>StandardErrorPath</key>
+    <string>${xml(out)}</string>
+  </dict>
+</plist>
+`;
+}
+
+const unitQuote = (s) => `"${String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+
+export function systemdUnit({ profile, node, script, root, env, out }) {
+  return `[Unit]
+Description=herdrchat (profile ${profile}): herdr-app tabs in a chat app
+After=network-online.target
+
+[Service]
+ExecStart=${unitQuote(node)} ${unitQuote(script)}
+WorkingDirectory=${root}
+${Object.entries(env).map(([k, v]) => `Environment=${unitQuote(`${k}=${v}`)}`).join('\n')}
+Restart=always
+RestartSec=${RESTART_S}
+StandardOutput=append:${out}
+StandardError=append:${out}
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+const run = (cmd, args) => execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+
+// {kind, name, file, content, write, remove, installed, load, unload, restart, state,
+// nodeGone}, or null on a system with neither launchd nor systemd.
+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');
+  const common = { profile, node, script, root, env, out };
+  if (platform === 'darwin') {
+    const label = `app.herdrchat.${profile}`;
+    const file = path.join(home, 'Library', 'LaunchAgents', `${label}.plist`);
+    const target = `gui/${process.getuid()}/${label}`;
+    return {
+      kind: 'launchd',
+      name: label,
+      file,
+      content: launchdPlist({ ...common, label }),
+      loaded() {
+        try {
+          run('launchctl', ['print', target]);
+          return true;
+        } catch {
+          return false;
+        }
+      },
+      load() { run('launchctl', ['bootstrap', `gui/${process.getuid()}`, file]); },
+      unload() { try { run('launchctl', ['bootout', target]); } catch { /* not loaded */ } },
+      restart() { run('launchctl', ['kickstart', '-k', target]); },
+      // {running, pid}
+      state() {
+        try {
+          const text = run('launchctl', ['print', target]);
+          return { running: /\bstate = running\b/.test(text), pid: Number(text.match(/\bpid = (\d+)/)?.[1]) || null };
+        } catch {
+          return { running: false, pid: null };
+        }
+      },
+      ...files(file, out),
+    };
+  }
+  if (platform === 'linux') {
+    const unit = `herdrchat-${profile}.service`;
+    const file = path.join(process.env.XDG_CONFIG_HOME || path.join(home, '.config'), 'systemd', 'user', unit);
+    const ctl = (...a) => run('systemctl', ['--user', ...a]);
+    return {
+      kind: 'systemd',
+      name: unit,
+      file,
+      content: systemdUnit(common),
+      loaded() {
+        try {
+          return ctl('is-enabled', unit).trim() === 'enabled';
+        } catch {
+          return false;
+        }
+      },
+      load() { ctl('daemon-reload'); ctl('enable', '--now', unit); },
+      unload() { try { ctl('disable', '--now', unit); } catch { /* not loaded */ } },
+      restart() { ctl('restart', unit); },
+      state() {
+        try {
+          const pid = Number(ctl('show', '-p', 'MainPID', '--value', unit).trim()) || null;
+          return { running: ctl('is-active', unit).trim() === 'active', pid };
+        } catch {
+          return { running: false, pid: null };
+        }
+      },
+      ...files(file, out),
+    };
+  }
+  return null;
+}
+
+function files(file, out) {
+  return {
+    installed: () => fs.existsSync(file),
+    write(content) {
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.mkdirSync(path.dirname(out), { recursive: true, mode: 0o700 });
+      fs.writeFileSync(file, content, { mode: 0o600 });
+    },
+    remove() { fs.rmSync(file, { force: true }); },
+    // the node the installed service runs, when it is gone (a node upgrade moved it)
+    nodeGone() {
+      if (!fs.existsSync(file)) return null;
+      const text = fs.readFileSync(file, 'utf8');
+      const node = text.match(/<string>([^<]*node[^<]*)<\/string>/)?.[1] || text.match(/^ExecStart="([^"]+)"/m)?.[1];
+      return node && !fs.existsSync(node) ? node : null;
+    },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "herdrchat",
-  "version": "1.1.2",
+  "version": "1.2.1",
   "description": "Chat front-ends for hc: every terminal hc runs, in the chat app you use",
   "repository": {
     "type": "git",

package/skills/herdrchat/SKILL.md

@@ -22,7 +22,8 @@ herdrchat`; when it is missing, ask before `npm install -g herdrchat`. A profile
 |---|---|
 | `/herdrchat setup` | First ask which chat app (Feishu, Telegram, or both: one profile each). Telegram: `/herdrchat telegram setup`. Feishu, in order: `herdrchat init`; make the Feishu app (`references/feishu.md`: create, bot, scopes, events and callbacks); fill `config.env` with the user (app id, secret, `HERDR_SESSIONS`: the hc sessions herdr-app shows on this machine); `herdrchat start`; publish a version; get the user's open_id (they message the bot, it answers with it) into `FEISHU_OWNER_OPEN_ID`; start again. Optional: `/herdrchat auth`. |
 | `/herdrchat status` | `herdrchat status`; explain each line; on errors, `/herdrchat fix`. |
-| `/herdrchat start`, `/herdrchat stop` | Read `config.env` (its `HERDR_SESSIONS`) in one step, then `herdrchat start` / `stop` in the next; never both at once. |
+| `/herdrchat start`, `/herdrchat stop` | Read `config.env` (its `HERDR_SESSIONS`) in one step, then `herdrchat start` / `stop` in the next; never both at once. With a service installed they go through it. |
+| `/herdrchat install`, `/herdrchat uninstall` | Run it as a service of the system (launchd on macOS, systemd on Linux): it starts at login and comes back after a crash, whatever happens to the hc cores. Recommended once it works. Read the config first; after a node upgrade, install again (`herdrchat status` says so). |
 | `/herdrchat logs` | `herdrchat logs --errors` (or `-n 100`); explain them with `references/ops.md` "Logs". |
 | `/herdrchat auth` | The user sends `/auth` to the bot and allows it on Feishu's page; the app needs the user scopes in `references/feishu.md`. Then groups are muted, labels and pins follow. |
 | `/herdrchat config` | Change a setting in `config.env` with the user (sessions, `HERDR_MUTED_SPACES`, `HERDR_SILENT_SPACES`, `HERDR_BOT_TAGS`, `HERDR_USER_TAGS`, `HERDR_HISTORY`, `HERDRCHAT_CHAT`; each is explained in `config.env.example`), read the file back, then restart. |

package/skills/herdrchat/references/ops.md

@@ -17,7 +17,9 @@ Below, `S` is the first session in `HERDR_SESSIONS`.
 HC_SESSION=S hc get herdrchat --json      # state "live"
 HC_SESSION=S hc read herdrchat --lines 40 # its terminal: start lines, "[feishu] connected"
 herdrchat status                              # running, folders, /auth, errors today
-herdrchat start                               # restart: stops it in every session, waits until it reaches Feishu
+herdrchat start                               # restart: stops it in every session, waits until it reaches its chat app
+herdrchat install                             # run it as a service (launchd/systemd): starts at login, back after a crash
+launchctl print gui/$(id -u)/app.herdrchat.<profile>   # the service on macOS: state, pid, last exit
 ```
 
 A restart is needed after any code or `config.env` change. It is safe: what was posted
@@ -38,7 +40,7 @@ While the bot is down the user hears nothing, so:
 
 ## Logs
 
-`D/logs/<YYYY-MM-DD>.log`, one file a day, 14 kept, lines `<time> <LEVEL> <text>`:
+`D/logs/<YYYY-MM-DD>.log`, one file a day, 14 kept, lines `<time> <LEVEL> <text>`. Run as a service, what the process printed before its log was open (a crash at start) is in `D/logs/service.out.log`:
 
 ```sh
 grep -h ERROR D/logs/*.log | tail -20   # what went wrong

package/skills/herdrchat/references/telegram.md

@@ -39,6 +39,9 @@ Do these in order; the user does the Telegram steps, you check each one.
    takes about one message a second in a chat, so twenty tabs take twenty seconds. A new
    topic gets the conversation before it (`HERDR_HISTORY`); `/history` in a topic posts it
    again.
+7. **Make it a service.** Once it works: `herdrchat install --profile telegram`. It then
+   starts at login and comes back by itself after a crash, whatever happens to the hc
+   cores; `herdrchat status --profile telegram` says it runs as the service.
 
 ## What rings
 
@@ -74,4 +77,4 @@ without muting each topic by hand.
 | `herdrchat start` says it did not reach its chat app | wrong token, or no network | check with getMe (step 5) |
 | log: `telegram poll: ... 409` | another copy polls the same token | `herdrchat stop --profile telegram`, find the other one (another machine?), start once |
 | log: `too fast, waiting N s` | Telegram's flood limit; the bot waits as told | nothing; it catches up |
-| a click answers "This dialog is gone" | the bot restarted after the card was posted (button ids live in memory) | answer the newest card, or in the terminal |
+| a click answers "This dialog is gone" | the card is older than the last 300 dialog cards | answer the newest card, or in the terminal |