herdrchat 1.2.1 → 1.3.1

package/lib/core/engine.mjs

@@ -17,7 +17,7 @@
 //   post(room, markdown) -> message; reply(where, markdown)
 //   postCard(room, look) -> message; editCard(message, look)   look: {title, tone, markdown}
 //   postDialog(room, dialog, value) -> message; closeDialog(message, dialog, done)
-//   pin(k, room); unpin(k); pinned() -> keys; ring(k, message, text)
+//   pin(k, room, message); unpin(k); pinned() -> keys; ring(k, message, text)
 //   markWorking(message) -> token; markDone(message, token)
 //   image(buffer) -> markdown; download(message, ref, file)
 //   postFile(room, {name, data, caption}); postFolded(room, {title, markdown}); foldedBytes
@@ -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 }) {
@@ -623,7 +624,7 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
     if (!dialog.menu) {
       const sent = await postTo(session, record, `**${dialog.title}**\n\n${dialog.markdown}\n\nReply \`/answer <text>\` to answer it, or \`/esc\` to cancel it.`);
       const room = read().chats[k]?.chat;
-      if (room) await chat.pin(k, room);
+      if (room) await chat.pin(k, room, sent);
       await chat.ring(k, sent, '⚠️ needs you');
     } else {
       const message = await deliver(session, record, (room) => chat.postDialog(room, dialog, dialogValue(session, address, dialog)));
@@ -631,7 +632,7 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
         remember(message, dialog);
         openCard.set(k, { message, dialog });
         const room = read().chats[k]?.chat;
-        if (room) await chat.pin(k, room);
+        if (room) await chat.pin(k, room, message);
         await chat.ring(k, message, '⚠️ needs you');
         // answered while the card was on its way: nothing will close it later, so now
         const live = views.get(session)?.terminals.get(address);
@@ -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
     }
@@ -46,7 +49,10 @@ export function createLog(dir) {
   };
 
   log.capture = ({ onCrash } = {}) => {
-    console.log = (...args) => write('INFO', args);
+    // a library that prints its errors as plain log lines ("[error]: ...", as the Feishu
+    // SDK does) gets them logged as WARN, so `herdrchat logs --errors` finds them
+    const levelOf = (args) => (/^\[(error|warn)\]/i.test(String(args[0] ?? '')) ? 'WARN' : 'INFO');
+    console.log = (...args) => write(levelOf(args), args);
     console.info = console.log;
     console.warn = (...args) => write('WARN', args);
     console.error = (...args) => write('ERROR', args);

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.2.1",
+  "version": "1.3.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

@@ -1,26 +1,28 @@
 ---
 name: herdrchat
-description: Set up, run and look after herdrchat, the chat front-end for hc that mirrors every herdr-app tab into a chat app - Feishu (one group per tab) or Telegram (one topic per tab in the bot's private chat), with dialog buttons, an overview and quiet phones - first setup of either app, running both side by side, start and stop, status and logs, /auth, settings, fixing problems, the Feishu developer console and @BotFather. Use for anything about herdrchat or its Feishu or Telegram bot, even when the user only says "set up the Telegram bot", "is it running", "it doesn't post", "mute the workers" or "publish the bot". Trigger with "/herdrchat", "/herdrchat setup", "/herdrchat status", "/herdrchat fix".
+description: Set up, run and look after herdrchat, which mirrors every herdr-app (hc) tab into Feishu (a group per tab) or Telegram (a topic per tab): first setup of either app, start, stop, status, logs, running it as a service, settings, fixing problems, the Feishu developer console and @BotFather. Use for anything about herdrchat or its Feishu or Telegram bot, even "set up the Telegram bot", "is it running", "it does not post" or "mute the workers". Trigger with "/herdrchat", "/herdrchat setup", "/herdrchat status", "/herdrchat fix".
 ---
 
 # herdrchat
 
 herdrchat mirrors every herdr-app tab into a chat app: a group per tab in Feishu, a topic
 per tab in the bot's private chat in Telegram; the conversation as it happens, dialogs as
-buttons, an overview in the direct chat. One profile is one chat app (`HERDRCHAT_CHAT`);
-to use both, run a profile each (`--profile telegram` beside the default Feishu one).
+buttons, an overview in the direct chat. One profile is one chat app (`HERDRCHAT_CHAT`):
+one app uses the default profile; a second app beside it gets its own (`--profile <name>`).
 
 Its command is `herdrchat` (`node bin/cli.mjs` in a clone): check with `command -v
 herdrchat`; when it is missing, ask before `npm install -g herdrchat`. A profile
 (`--profile`, default `default`) keeps its settings in
 `~/.config/herdrchat/<profile>/config.env` and its state in
-`~/.local/state/herdrchat/<profile>/`; `herdrchat status` prints both.
+`~/.local/state/herdrchat/<profile>/`; `herdrchat status` prints both. Files named here
+from the package (`config.env.example`, `docs/guide.md`) are in the installed package,
+`$(npm root -g)/herdrchat/`, or in the clone.
 
 ## Commands
 
 | Command | Do |
 |---|---|
-| `/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 setup` | First ask which chat app (Feishu, Telegram, or both: the second one on its own profile). Telegram: `/herdrchat telegram setup`. Feishu, in this order: create the app, the bot ability and the scopes (`references/feishu.md`); `herdrchat init` and fill `config.env` with the user (App ID, App Secret, `HERDR_SESSIONS`: `ls ~/.local/state/herdr-core` lists the sessions); `herdrchat start` (the console's long-connection check needs it running); events and callbacks; publish a version; the user messages the bot and adds the `FEISHU_OWNER_OPEN_ID` line it answers with; `herdrchat start` again; offer `/herdrchat auth` and `herdrchat install`. |
 | `/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. 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). |
@@ -29,7 +31,7 @@ herdrchat`; when it is missing, ask before `npm install -g herdrchat`. A profile
 | `/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. |
 | `/herdrchat fix` | Find the cause from `herdrchat status`, the logs and the live result, then fix it: `references/ops.md`. |
 | `/herdrchat feishu <task>` | Anything in the Feishu developer console: scopes, callbacks, publishing, the icon, deleting an app: `references/feishu.md`. |
-| `/herdrchat telegram <task>` | The Telegram bot, as its own profile: `setup` (@BotFather, topic mode, token, owner id, first start), checking the token, quiet and silent spaces, what Telegram cannot do and what stands in: `references/telegram.md`. |
+| `/herdrchat telegram <task>` | The Telegram bot (the default profile when it is the only app): `setup` (@BotFather, topic mode, token, owner id, first start), checking the token, quiet and silent spaces, what Telegram cannot do and what stands in: `references/telegram.md`. |
 
 With no subcommand, run `herdrchat status` and suggest the next step from it.
 
@@ -39,8 +41,7 @@ With no subcommand, run `herdrchat status` and suggest the next step from it.
   disbanding anything, sending to a real group. One yes covers one action.
 - Never print, screenshot or paste `FEISHU_APP_SECRET`, `TELEGRAM_BOT_TOKEN` or
   `user-token.json`; ask the user to paste a token into `config.env` themselves.
-- A check that decides an action runs on its own first (read the config, then start;
-  scan, then commit).
+- A check that decides an action runs on its own first (read the config, then start).
 - Say what was checked on the live bot and what was not.
 
 ## References

package/skills/herdrchat/references/feishu.md

@@ -53,9 +53,10 @@ that applies or publishes something, and read it.
 ### Create the app (first setup only)
 
 Developer console home -> create a custom app (企业自建应用) with a name, a description
-and an icon -> Add capabilities -> Bot. Then import the scopes, set events and
-callbacks, start the bot (`herdrchat start`) and publish. The "Set up" section of `docs/guide.md`
-lists the same steps from the repo's side.
+and an icon -> Add capabilities -> Bot. Then import the scopes, have the user fill
+`config.env` (`herdrchat init`), start the bot (`herdrchat start`: the long-connection
+check below needs it running), set events and callbacks, and publish. "Set up: Feishu"
+in `docs/guide.md` lists the same steps from the user's side.
 
 ### Import scopes
 
@@ -107,6 +108,27 @@ Deactivate it first in the tenant admin console,
 `https://<tenant>.feishu.cn/admin/appCenter/manage/<APP_ID>` (needs a tenant admin),
 then delete it in the developer console. Ask before each of the two steps.
 
+### The bot menu (optional)
+
+A menu at the bottom of the direct chat with the bot, so the commands are a tap away as
+Telegram's "/" list is. Feishu sets it only in the developer console (no API), shows it
+in the direct chat only (not in groups), and needs a published version (then about five
+minutes, and a client of 5.27 or later).
+
+1. 应用能力 -> 机器人 -> 机器人自定义菜单: edit, turn it on (开启), pick a style.
+2. Add items whose action is 推送事件 (push an event), with these keys; the bot treats a
+   click as that command in the direct chat:
+   | Item | Event key |
+   |---|---|
+   | Overview | `ls` |
+   | Help | `help` |
+   | Act as me | `auth` |
+3. 事件与回调 -> 事件配置 (long connection mode, as for messages) -> 添加事件:
+   机器人自定义菜单事件 (`application.bot.menu_v6`).
+4. Publish a version. Ask before publishing.
+
+Commands that take words (`/new`, `/kill`) stay typed.
+
 ## Scopes this bot uses
 
 Bot identity (the bot itself) and user identity (only for `/auth`, acting as the user):

package/skills/herdrchat/references/ops.md

@@ -1,25 +1,27 @@
 # Ops: running and looking after herdrchat
 
-The bot is `bin/herdrchat.mjs`. It runs in an hc terminal named `herdrchat`, in the first
-hc session listed in `HERDR_SESSIONS`; `herdrchat start` (re)starts it and keeps it
-running (`node bin/cli.mjs` from a clone). A profile (`--profile` or `HERDRCHAT_PROFILE`,
-default `default`; another one runs as the hc terminal `herdrchat-<profile>`) has its
-settings in `~/.config/herdrchat/<profile>/config.env` and writes to
-`~/.local/state/herdrchat/<profile>/` (call it `D` below), unless `HERDRCHAT_HOME` holds
-both (`config.env`, `state/`). Its settings in Feishu itself (scopes, callbacks, icon,
-versions) are in `references/feishu.md`.
+The bot (`bin/herdrchat.mjs` in the installed package) runs one of two ways:
 
-Below, `S` is the first session in `HERDR_SESSIONS`.
+- as a **service** of the system, after `herdrchat install` (launchd on macOS, systemd on
+  Linux): it starts at login and comes back after a crash; recommended;
+- in an **hc terminal** named `herdrchat` (`herdrchat-<profile>` for another profile), in
+  the first session of `HERDR_SESSIONS`, after `herdrchat start` without a service.
+
+`herdrchat status` says which, and where the profile's files are: settings in
+`~/.config/herdrchat/<profile>/config.env`, state and logs in
+`~/.local/state/herdrchat/<profile>/` (call it `D` below). The app's own settings (Feishu
+scopes, callbacks; the Telegram bot's topic mode) are in `references/feishu.md` and
+`references/telegram.md`.
 
 ## Is it running
 
 ```sh
-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 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
+herdrchat status                       # how it runs, sessions, keys set or missing, errors today
+herdrchat logs --errors                # what went wrong today ("[feishu] connected" / "[telegram] connected as @…" when in)
+herdrchat start                        # restart: stops it everywhere, waits up to a minute until it is in
+herdrchat install                      # make it a service: starts at login, back after a crash
+launchctl print gui/$(id -u)/app.herdrchat.<profile>   # macOS: the service's state, pid, last exit
+systemctl --user status herdrchat-<profile>            # Linux: the same
 ```
 
 A restart is needed after any code or `config.env` change. It is safe: what was posted
@@ -28,7 +30,7 @@ is in `D/state.json`, so it picks up where it stopped.
 While the bot is down the user hears nothing, so:
 
 - Never end with the bot down: `herdrchat start` exits 1 with its errors when the bot
-  does not reach Feishu within 30 s; fix that before anything else.
+  does not reach its chat app within 60 s; fix that before anything else.
 - Never stop or restart the hc core (`hc server stop|restart`) of the session the bot
   runs in without saying so first, and run `herdrchat start` right after.
 - Never start an hc core from an agent's shell: the core passes that shell's variables
@@ -73,49 +75,17 @@ grep -h ' <- \| -> ' D/logs/$(date -u +%F).log | tail   # posts out, your messag
 Read it with a short `node -e` and print only what you need. `D/user-token.json` is
 your token after `/auth`: never print it.
 
-## Did the change take effect
-
-Check the live result, not only the code: count what actually happened in Feishu with
-the bot's own client (`lib/chats/feishu/client.mjs` `createClient` with `loadConfig()`), for example:
-
-- mentions in a group since a time: `im.v1.message.list` on the chat, then each item's
-  `mentions` (a mention inside a card is not counted by Feishu, so it does not ring);
-- a group's bot tags: `im.v2.bizEntityTagRelation.get` with `tag_biz_type: 'chat'`;
-- whether a card was edited: `im.v1.message.get`, compare `update_time` with `create_time`.
-
-Say which checks were run and which were not; "the code is there" is not "it works".
-
 ## Usual problems
 
 | You see | Likely cause | Do |
 |---|---|---|
-| nothing posts | bot down, or `FEISHU_OWNER_OPEN_ID` unset | check it runs; the log says "owner not set" |
+| nothing posts | bot down, or the owner not set (`FEISHU_OWNER_OPEN_ID`, `TELEGRAM_OWNER_ID`) | `herdrchat status`; the log says "owner not set" |
+| Telegram: no topic appears | topic mode off | log: "topic mode is off"; BotFather's mini app, the bot, Threaded Mode, then start again |
+| Telegram: `telegram poll: ... 409` | another copy polls the same token | stop it (another machine?), then start once |
 | a button gives error 200340 | the card callback is not set up | `references/feishu.md`: events and card callbacks |
 | a dialog had no card | answered in the terminal before the card; or no numbered menu on screen | log: `blocked`; the card says `/answer` when it saw no menu |
 | the phone rings too much | Feishu: not `/auth`ed; either app: settings | Feishu `/auth`; `HERDR_MUTED_SPACES` (quiet but for needs you and done), `HERDR_SILENT_SPACES` (nothing rings), per profile |
 | a ⚠️ warning in the direct chat about acting as you | the token could not be refreshed | send `/auth` again |
 | a group keeps an old name | its terminal is not live | it renames when the terminal is back |
 | a Feishu call fails with 400 in a burst | a rate limit (tags: 5 a second) | space the calls; the bot queues tag calls |
-
-## Trying a Feishu API safely
-
-1. Read the official doc first (open.feishu.cn); write down the scope and limits.
-2. Make real calls only with this repo's own code (the SDK or `fetch`), never through a
-   third-party tool; reading another tool's docs or a dry run to learn a path is fine.
-3. Test in a throwaway group the bot creates for it (`zz-test ...`), never in a
-   terminal's group; label each test message ("Test 2/3: ...") so the user can tell
-   which one rang.
-4. Measure the result (an API field, a read-back) instead of assuming it; ask the user
-   only what only a phone shows (did it ring).
-5. Clean up in the same run: disband the test group, delete test labels and tags you
-   made, recall test messages, delete scratch files.
-
-## Before a commit
-
-1. `npm test` passes.
-2. Stage, then, as its own step, scan the staged files for anything real: session and
-   machine names, the app id (`cli_`), open_ids (`ou_`), chat ids (`oc_`), message ids
-   (`om_`), label ids (`ofg_`), the tenant's name, people's names, local paths. Read the
-   result before committing; never chain the scan and the commit in one command.
-3. Show the commit message (Conventional Commits; the body says why) and commit only
-   after the user's yes. No push without its own yes.
+| `herdrchat start` says it did not reach its chat app | wrong keys, or no network | `herdrchat logs --errors`; check the keys in `config.env` |

package/skills/herdrchat/references/telegram.md

@@ -3,9 +3,11 @@
 A Telegram bot cannot make groups (the Bot API has no such method), so herdrchat puts each
 herdr-app tab in a **topic** of your private chat with the bot: each has its own name,
 icon color (one per space), unread count, and can be muted on its own. The chat's main
-thread holds the overview and the commands. It runs as its **own profile**, beside a
-Feishu one; each bot follows the same hc terminals, so an answer in either reaches the
-terminal, and a dialog answered in one closes its card in the other.
+thread holds the overview and the commands. When Telegram is the only chat app, it uses
+the default profile; beside a Feishu bot it gets its own (`--profile telegram`), and both
+follow the same hc terminals, so an answer in either reaches the terminal and a dialog
+answered in one closes its card in the other. Below, `P` is ` --profile <name>` when it
+has its own profile, else nothing.
 
 ## Setup (`/herdrchat telegram setup`)
 
@@ -14,34 +16,26 @@ Do these in order; the user does the Telegram steps, you check each one.
 1. **The bot.** The user messages **@BotFather**: `/newbot`, a name, a username ending in
    `bot`. BotFather answers with a token. The user keeps it: never ask them to paste it
    into the chat.
-2. **Topic mode.** It is not in BotFather's `/mybots` → Bot Settings list; it is in
-   BotFather's mini app (the **Open** button at the bottom left of the BotFather chat):
-   pick the bot, turn on Threaded Mode / topics. Check it (step 5): `has_topics_enabled`
-   must be `true`, or no topic can be made.
-3. **The profile's config.** Make `~/.config/herdrchat/telegram/config.env` (folder mode
-   700, file 600) with:
-   ```
-   HERDRCHAT_CHAT=telegram
-   TELEGRAM_BOT_TOKEN=
-   TELEGRAM_OWNER_ID=
-   HERDR_SESSIONS=<the same sessions as the Feishu profile>
-   ```
-   and ask the user to paste the token after `TELEGRAM_BOT_TOKEN=` themselves
-   (`open -e <file>` opens it), no quotes, no spaces.
-4. **First start, to learn the owner.** `herdrchat start --profile telegram`; the user
-   messages the bot anything; it answers `TELEGRAM_OWNER_ID=<digits>`. The user puts that
-   in the config. Until then the bot makes no topic.
-5. **Check, without printing secrets.** In a short `node -e`: read the token from the
-   config, call `https://api.telegram.org/bot<token>/getMe`, print only `username` and
-   `has_topics_enabled`; for the owner, print only whether `TELEGRAM_OWNER_ID` is digits.
-6. **Start again.** Read the config (secrets hidden) in one step, then
-   `herdrchat start --profile telegram` in the next. One topic per tab appears; Telegram
-   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.
+2. **The config.** `herdrchat init --chat telegram P` makes the profile's `config.env`
+   (private) and prints where it is. Ask the user to paste the token after
+   `TELEGRAM_BOT_TOKEN=` themselves (`open -e <file>` opens it), no quotes, no spaces, and
+   fill `HERDR_SESSIONS` with them (`ls ~/.local/state/herdr-core` lists the sessions).
+3. **Topic mode, checked before the first start.** It is not in BotFather's `/mybots` →
+   Bot Settings list; it is in BotFather's mini app (the **Open** button at the bottom
+   left of the BotFather chat): pick the bot, turn on Threaded Mode. Check it without
+   printing the token: a short `node -e` reads the token from the config, calls
+   `https://api.telegram.org/bot<token>/getMe` and prints only `username` and
+   `has_topics_enabled`, which must be `true`.
+4. **First start, to learn the owner.** `herdrchat start P`; the user messages the bot
+   anything; it answers with the line to add, `TELEGRAM_OWNER_ID=<digits>`, and where the
+   file is. The user adds it. Until then the bot makes no topic.
+5. **Start again.** Read the config (secrets hidden) in one step, then
+   `herdrchat start P` in the next. One topic per tab appears; Telegram 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.
+6. **Make it a service.** Once it works: `herdrchat install P`. It then starts at login
+   and comes back by itself after a crash, whatever happens to the hc cores;
+   `herdrchat status P` says it runs as the service.
 
 ## What rings
 
@@ -64,7 +58,8 @@ without muting each topic by hand.
 | an ended group gets the "ended" tag | an ended topic's name starts with 🔚 (closing a topic is documented for supergroups only) |
 | an image inside a card | each image as its own photo after the text |
 | a text box on a dialog card | type the answer in the topic |
-| tags, labels, pins, `/auth` | none (a topic cannot be pinned; a bot cannot act as the user) |
+| pins the group that needs you | pins the dialog card in its topic until it is answered |
+| tags, labels, `/auth` | none (a bot cannot act as the user) |
 | the overview card | one message in the main thread, edited in place |
 | `/` commands: typed | `/` shows a menu: ls, new, kill, screen, answer, esc, history |
 
@@ -72,9 +67,9 @@ without muting each topic by hand.
 
 | Seen | Cause | Do |
 |---|---|---|
-| log: `topic mode is off for @<bot>` | step 2 not done | turn it on in BotFather's mini app, check `has_topics_enabled`, start again |
-| the bot answers `Owner is not set` | `TELEGRAM_OWNER_ID` empty | step 4 |
-| `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: `topic mode is off for @<bot>` | step 3 not done | turn it on in BotFather's mini app, check `has_topics_enabled`, start again |
+| the bot answers "To make you this bot's owner…" | `TELEGRAM_OWNER_ID` empty | step 4 |
+| `herdrchat start` says it did not reach its chat app | wrong token, or no network | check with getMe (step 3) |
+| log: `telegram poll: ... 409` | another copy polls the same token | `herdrchat stop P`, 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 card is older than the last 300 dialog cards | answer the newest card, or in the terminal |