herdrchat 1.4.0 → 1.5.0

package/README.md

@@ -28,8 +28,9 @@ questions, send and receive images, and see all terminals in one overview. A new
 topic starts with the conversation so far, and your phone rings only when an agent needs
 you or is done (on Feishu once you have sent `/auth` to the bot; on Telegram right away).
 
-Claude Code is mirrored fully. Other agents show their screen when you type to them,
-until herdrchat learns to read their conversations too.
+Claude Code and Codex are mirrored fully, their dialogs answered with buttons. Other
+agents show their screen when you type to them, until herdrchat learns to read their
+conversations too.
 
 ## You need
 

package/README.zh.md

@@ -24,7 +24,7 @@ agent 干活时说的话实时可见，它问你的问题点按钮就能回答
 新开的群或话题会先补上之前的对话；只有 agent 需要你、或者做完的时候手机才会响
 （飞书要先给 bot 发一次 `/auth`；Telegram 直接就是这样）。
 
-目前 Claude Code 是完整同步的。其他 agent 在你给它发消息时会回一次屏幕内容，
+目前 Claude Code 和 Codex 是完整同步的，它们的对话框都能点按钮回答。其他 agent 在你给它发消息时会回一次屏幕内容，
 等 herdrchat 学会读它们的对话记录以后，也会完整同步。
 
 ## 需要什么

package/docs/architecture.md

@@ -2,7 +2,7 @@
 
 herdrchat has two kinds of plug-ins that grow over time: **chat apps** (Feishu and
 Telegram now, Slack and Discord later) and **agents**, each read by its reader (Claude
-Code now, then codex and pi). The core between them knows neither. This page says where everything is and
+Code and Codex now, then pi). The core between them knows neither. This page says where everything is and
 how to add one of each.
 
 ## The parts

package/docs/guide.md

@@ -345,8 +345,12 @@ before it is started again. Tokens and secrets are never logged. The skill's
 ## 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 post nothing by themselves
+- Claude Code and Codex have readers so far. pi and the rest post nothing by themselves
   until each has a reader; what you type to them gets their screen in reply.
+- Codex: its log is found as the one written in its folder since it started (Codex names
+  no pid outside its database), so two Codex sessions started in the same folder at the
+  same moment could be told apart wrongly. Its questions with choices come as text: answer
+  by typing. A group is named after Codex's thread name once it has one.
 - Only text, images and rich text are passed on; files, stickers and the rest are not.
 - An image that fails to upload three times is not sent; the group says so and why.
 - Feishu only, not Lark (the international version) yet: the bot talks to open.feishu.cn.

package/lib/chats/feishu/client.mjs

@@ -48,10 +48,26 @@ function card(markdown) {
   return JSON.stringify({ schema: '2.0', body: { elements: [{ tag: 'markdown', content: markdown }] } });
 }
 
+// A card's header: its title with Feishu's own icon for what the card is, in place of the
+// emoji the core leads a title with (the icon says it once), and the color of its tone.
+export const TONES = {
+  working: { template: 'blue', icon: 'loading_outlined' },
+  closed: { template: 'grey', icon: 'done_outlined' },
+  needs: { template: 'orange', icon: 'warning_outlined' },
+  done: { template: 'grey', icon: 'done_outlined' },
+  good: { template: 'green', icon: 'done_outlined' },
+  bad: { template: 'red', icon: 'warning_outlined' },
+};
+const LEADING_EMOJI = /^(?:[\p{Extended_Pictographic}\u2600-\u27BF][\uFE0F\u200D]*\s*)+/u;
+export function header(title, tone) {
+  const t = TONES[tone] || TONES.working;
+  return { title: { tag: 'plain_text', content: String(title).replace(LEADING_EMOJI, '') || String(title) }, template: t.template, icon: { tag: 'standard_icon', token: t.icon, color: t.template } };
+}
+
 // A markdown card that can be edited after it is sent (updateCard needs update_multi
 // on the card both before and after).
-export function textCard(markdown, title, template) {
-  return { schema: '2.0', config: { update_multi: true }, header: { title: { tag: 'plain_text', content: title }, template }, body: { elements: [{ tag: 'markdown', content: markdown }] } };
+export function textCard(markdown, title, tone = 'working') {
+  return { schema: '2.0', config: { update_multi: true }, header: header(title, tone), body: { elements: [{ tag: 'markdown', content: markdown }] } };
 }
 
 export async function updateCard(client, messageId, cardJson) {
@@ -99,9 +115,17 @@ const BUTTON_TEXT = 80;
 
 function button(text, value, type = 'default') {
   const short = text.length > BUTTON_TEXT ? `${text.slice(0, BUTTON_TEXT - 1)}…` : text;
-  return { tag: 'button', type, width: 'fill', text: { tag: 'plain_text', content: short }, behaviors: [{ type: 'callback', value }] };
+  return { tag: 'button', type, width: 'default', size: 'medium', text: { tag: 'plain_text', content: short }, hover_tips: { tag: 'plain_text', content: text }, behaviors: [{ type: 'callback', value }] };
 }
 
+// Buttons side by side, wrapping onto the next line when the screen is narrow.
+const row = (buttons) => ({ tag: 'column_set', flex_mode: 'flow', horizontal_spacing: 'small', columns: buttons.map((b) => ({ tag: 'column', width: 'auto', elements: [b] })) });
+// Short options (Yes / No) sit side by side; a long one would be cut there, so then each
+// option is a line of its own, as wide as its words, at the left like the text above.
+const SIDE_BY_SIDE = { most: 4, chars: 14 };
+const fitsSideBySide = (labels) => labels.length <= SIDE_BY_SIDE.most && labels.every((l) => [...l].length <= SIDE_BY_SIDE.chars);
+const options = (buttons, labels) => (fitsSideBySide(labels) ? [row(buttons)] : buttons);
+
 // A multi-select's boxes are checkers in a form: with no behaviors a checker is ticked on
 // the phone only, so ticking makes no call and shows no loading; Next submits the form,
 // and each box comes back in form_value under its name, box_<n> (ticksOf reads them).
@@ -109,16 +133,18 @@ export const BOX = 'box_';
 export function menuCard({ title, markdown, menu, value }) {
   const elements = [{ tag: 'markdown', content: markdown }];
   const boxes = [];
+  const choices = [];
   for (const o of menu.options) {
     if (o === menu.free) continue;
     if (menu.multi && o.checked !== null) {
       boxes.push({ tag: 'checker', name: `${BOX}${o.n}`, checked: o.checked, text: { tag: 'plain_text', content: `${o.n}. ${o.label}` } });
       continue;
     }
-    elements.push(button(`${o.n}. ${o.label}`, { ...value, pick: o.n, label: o.label }, o.n === 1 && !menu.multi ? 'primary' : 'default'));
+    choices.push(button(`${o.n}. ${o.label}`, { ...value, pick: o.n, label: o.label }, o.n === 1 && !menu.multi ? 'primary_filled' : 'default'));
   }
+  if (choices.length) elements.push(...options(choices, choices.map((b) => b.text.content)));
   if (menu.multi) {
-    elements.push({ tag: 'form', name: 'boxes', elements: [...boxes, { ...button('Next ⇥', { ...value, pick: 'tab' }, 'primary'), name: 'next', form_action_type: 'submit' }] });
+    elements.push({ tag: 'form', name: 'boxes', elements: [...boxes, { ...button('Next ⇥', { ...value, pick: 'tab' }, 'primary_filled'), name: 'next', form_action_type: 'submit' }] });
   }
   if (menu.free) {
     elements.push({
@@ -126,17 +152,24 @@ export function menuCard({ title, markdown, menu, value }) {
       name: 'free',
       elements: [
         { tag: 'input', name: 'answer', required: true, placeholder: { tag: 'plain_text', content: menu.free.label } },
-        { ...button('Send', { ...value, pick: menu.free.n, label: menu.free.label }, 'primary'), name: 'send', form_action_type: 'submit' },
+        { ...button('Send', { ...value, pick: menu.free.n, label: menu.free.label }, 'primary_filled'), name: 'send', form_action_type: 'submit' },
       ],
     });
   }
-  elements.push(button('Esc (cancel)', { ...value, pick: 'esc' }, 'danger'));
-  return { schema: '2.0', config: { update_multi: true }, header: { title: { tag: 'plain_text', content: title }, template: 'red' }, body: { elements } };
+  elements.push(row([button('Esc (cancel)', { ...value, pick: 'esc' }, 'danger_text')]));
+  return { schema: '2.0', config: { update_multi: true }, header: header(title, 'needs'), body: { elements } };
 }
 
 // The card once it is answered: the same text, no buttons, and what was done.
+// A dialog once answered (or gone): grey, its text, and what was done in small type.
 export function doneCard(title, markdown, done) {
-  return { schema: '2.0', config: { update_multi: true }, header: { title: { tag: 'plain_text', content: title }, template: 'grey' }, body: { elements: [{ tag: 'markdown', content: `${markdown}\n\n**${done}**` }] } };
+  return {
+    schema: '2.0',
+    config: { update_multi: true },
+    header: header(title, 'done'),
+    // the icon is the check: one the core leads `done` with goes
+    body: { elements: [{ tag: 'markdown', content: markdown }, { tag: 'markdown', content: String(done).replace(/^[✔✓]\uFE0F?\s*/u, ''), text_size: 'notation', icon: { tag: 'standard_icon', token: 'done_outlined', color: 'grey' } }] },
+  };
 }
 
 // Takes back a message the bot sent.
@@ -184,8 +217,16 @@ export async function downloadImage(client, messageId, imageKey, file) {
 
 // What a received message says: its text and the keys of its images, in order, for
 // text, image and rich text (post) messages; null for any other kind.
+// null for what is not passed on: another type (a file, forwarded chat records, ...), or a
+// content that is not JSON (a merged forward lists as "Merged and Forwarded Message").
 export function messageParts(messageType, content) {
-  const c = JSON.parse(content);
+  let c;
+  try {
+    c = JSON.parse(content);
+  } catch {
+    return null;
+  }
+  if (!c || typeof c !== 'object') return null;
   if (messageType === 'text') return { text: c.text || '', images: [] };
   if (messageType === 'image') return { text: '', images: [c.image_key] };
   if (messageType !== 'post') return null;

package/lib/chats/feishu/index.mjs

@@ -1,28 +1,23 @@
-// herdrchat's Feishu side: one group per tab (a "room" to the core), the direct chat with
-// the bot for the overview and commands, and what only Feishu has: tenant tags, group
-// avatars, and, after /auth, acting as you (muted groups, your labels, pins, @ mentions).
-// The core (lib/core/engine.mjs) calls only what is returned here; see "The chat side"
-// there for what each call means.
-import { ticksOf, createClient, bindTag, chunk, createChat, createTag, doneCard, downloadImage, foldedCard, menuCard, messageParts, recallMessage, renameChat, replyMention, sendCard, sendFile, sendMarkdown, setChatAvatar, startEvents, tagName, textCard, unbindTag, updateCard, uploadImage } from './client.mjs';
-import { COLORS, avatarPng, letterOf } from './avatar.mjs';
+// herdrchat's Feishu side: the rooms (rooms/: how tabs are laid out in groups, and what a
+// group wears), the direct chat with the bot for the overview and commands, and, after
+// /auth, acting as you (muted groups, your labels, pins, @ mentions). The core
+// (lib/core/engine.mjs) calls only what is returned here; see "The chat side" there for
+// what each call means.
+import { ticksOf, createClient, chunk, doneCard, downloadImage, foldedCard, menuCard, messageParts, recallMessage, sendCard, sendFile, sendMarkdown, startEvents, textCard, updateCard, uploadImage } from './client.mjs';
 import { overviewCard, overviewText } from './overview.mjs';
 import { createUserAuth } from './userauth.mjs';
+import { createDecor } from './rooms/decor.mjs';
+import { createGroups } from './rooms/groups.mjs';
 
-const ENDED_TAG = '#ended';
-const ENDED_LABEL = 'ended';
 const YOU_CHECK_MS = 60 * 1000;
 const OVERVIEW_TRIES = 3;
 const WORKING_EMOJI = 'THINKING';
 const DONE_EMOJI = 'OK';
-const TONES = { working: 'blue', closed: 'grey', needs: 'red', done: 'grey', good: 'green', bad: 'red' };
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 // What to do after an edit to config.env, said the way this profile is run.
 const startAgain = (cfg) => `\`herdrchat start${cfg.profile && cfg.profile !== 'default' ? ` --profile ${cfg.profile}` : ''}\``;
 
-const inSpaces = (set, space) => set.all || set.spaces.includes(space);
-const spaceOfName = (name) => (name || '').split(' / ')[0];
-
 // cfg: loadConfig(); store: {read, write} of state.json; lane(k, label, fn): runs fn in
 // the room's lane, after what is queued for it; scopeOf(k): the session or machine a
 // room's terminal belongs to (its tag and label).
@@ -33,110 +28,6 @@ export function create({ cfg, store, log, logWarn, logError, stateDir, lane, sco
   const userAuth = createUserAuth(cfg, stateDir);
   const { read, write } = store;
 
-  function setRoom(k, fields) {
-    const state = read();
-    if (state.chats[k]) state.chats[k] = { ...state.chats[k], ...fields };
-    write(state);
-  }
-
-  // Lanes run side by side: a thing that is made once (a tag, a space's avatar) is made
-  // by the first lane that needs it; the others wait for that.
-  const making = new Map();
-  function once(id, make) {
-    if (!making.has(id)) making.set(id, make().finally(() => making.delete(id)));
-    return making.get(id);
-  }
-
-  // ---------- tags and avatars ----------
-
-  // One tenant tag per session or machine, made once, and one "ended" tag; their ids are
-  // kept in state.json (tags).
-  async function tagOf(id, name = id) {
-    return read().tags?.[id] || once(`tag ${id}`, async () => {
-      const tag = await createTag(client, name);
-      const state = read();
-      state.tags = { ...(state.tags || {}), [id]: tag };
-      write(state);
-      log(`created tag ${name} (${tag})`);
-      return tag;
-    });
-  }
-
-  // Each space gets an avatar: its first letter on a color of its own (the first color no
-  // other space has), kept in state.json (spaces), so all of its groups look alike, as in
-  // herdr-app. The color is picked and saved before the first await, so spaces made side
-  // by side never pick the same one. A failure is logged and tried again at the next check.
-  function colorOf(space) {
-    const state = read();
-    const spaces = state.spaces || {};
-    if (spaces[space]?.color) return spaces[space].color;
-    const used = Object.values(spaces).map((x) => x.color);
-    const color = COLORS.find((c) => !used.includes(c)) || COLORS[used.length % COLORS.length];
-    state.spaces = { ...spaces, [space]: { color } };
-    write(state);
-    return color;
-  }
-
-  async function avatarOf(space) {
-    return read().spaces?.[space]?.image || once(`avatar ${space}`, async () => {
-      const color = colorOf(space);
-      const image = await uploadImage(client, await avatarPng(letterOf(space), color), 'avatar');
-      const state = read();
-      state.spaces = { ...(state.spaces || {}), [space]: { color, image } };
-      write(state);
-      log(`made avatar for space ${space} (${color})`);
-      return image;
-    });
-  }
-
-  // the space's avatar; a no-op when the group has it, so it follows a space that changes
-  async function avatarRoom(k, space) {
-    const c = read().chats[k];
-    if (!c) return;
-    try {
-      const image = await avatarOf(space);
-      if (c.avatar === image) return;
-      await setChatAvatar(client, c.chat, image);
-      setRoom(k, { avatar: image });
-    } catch (err) {
-      logError(`avatar ${space} on ${c.chat}: ${err.message}`);
-    }
-  }
-
-  // Bot tags (HERDR_BOT_TAGS): the session or machine tag next to a group's name and, once
-  // its terminal is gone, "ended". They are tenant tags, so they can be turned off; off
-  // takes off the ones already on. A failure is logged and tried again at the next check.
-  async function syncBotTags(k, scope) {
-    const c = read().chats[k];
-    if (!c) return;
-    try {
-      if (cfg.botTags) {
-        const tag = await tagOf(scope);
-        if (c.tag !== tag) {
-          await bindTag(client, tag, c.chat);
-          setRoom(k, { tag });
-        }
-        if (Boolean(c.ended) !== Boolean(c.endedTag)) {
-          const ended = await tagOf(ENDED_TAG, 'ended');
-          await (c.ended ? bindTag : unbindTag)(client, ended, c.chat);
-          setRoom(k, { endedTag: Boolean(c.ended) });
-        }
-      } else {
-        const tags = read().tags || {};
-        if (c.tag) {
-          await unbindTag(client, c.tag, c.chat).catch(() => {});
-          setRoom(k, { tag: null });
-        }
-        if (c.endedTag && tags[ENDED_TAG]) {
-          await unbindTag(client, tags[ENDED_TAG], c.chat).catch(() => {});
-          setRoom(k, { endedTag: false });
-        }
-      }
-    } catch (err) {
-      logError(`bot tags on ${c.name}: ${err.message}`);
-    }
-  }
-
   // ---------- acting as you (optional, after /auth) ----------
 
   // With your token (userauth.mjs) the bot does what only you can: mutes its groups,
@@ -153,10 +44,17 @@ export function create({ cfg, store, log, logWarn, logError, stateDir, lane, sco
     if (Date.now() - youCheckedAt < YOU_CHECK_MS) return you;
     youCheckedAt = Date.now();
     const was = you;
-    you = await userAuth.allowed();
+    try {
+      you = await userAuth.allowed();
+    } catch (err) {
+      // not known (Feishu not reached): it stays as it was, and is asked again soon
+      youCheckedAt = Date.now() - YOU_CHECK_MS + 10 * 1000;
+      logWarn(`acting as you: not checked (${err.message}); it stays ${you ? 'on' : 'off'}`);
+      return you;
+    }
     if (you && !was) {
       log('acting as you: on');
-      setTimeout(alignAll, 0);
+      setTimeout(() => rooms.alignAll(), 0);
     } else if (!you && was) {
       logWarn('acting as you: off');
       await tellOwner({ title: '⚠️ Needs you', tone: 'needs', markdown: 'The bot can no longer act as you (mute, labels, pin). Send `/auth` to allow it again.' }).catch(() => {});
@@ -164,112 +62,15 @@ export function create({ cfg, store, log, logWarn, logError, stateDir, lane, sco
     return you;
   }
 
-  async function labelOf(name) {
-    return read().labels?.[name] || once(`label ${name}`, async () => {
-      const found = (await userAuth.feedGroups())?.groups?.find((g) => g.name === name);
-      const id = found?.group_id || (await userAuth.createFeedGroup(name))?.group_id;
-      if (!id) throw new Error(`no label ${name}`);
-      const state = read();
-      state.labels = { ...(state.labels || {}), [name]: id };
-      write(state);
-      log(`label ${name} (${id})`);
-      return id;
-    });
-  }
-
-  // A label you deleted is made again at the next try.
-  async function intoLabel(name, chat) {
-    try {
-      await userAuth.addToFeedGroup(await labelOf(name), [chat]);
-    } catch (err) {
-      const state = read();
-      if (state.labels) delete state.labels[name];
-      write(state);
-      throw err;
-    }
-  }
-
-  // Your label (HERDR_USER_TAGS, acting as you): the session or machine, or "ended" once
-  // the terminal is gone; off takes the group out of it (the label itself is yours).
-  async function syncUserLabel(k, scope) {
-    if (!(await asYou())) return;
-    const c = read().chats[k];
-    if (!c) return;
-    const want = cfg.userTags ? (c.ended ? ENDED_LABEL : tagName(scope)) : null;
-    if ((c.label || null) === want) return;
-    try {
-      if (c.label) await userAuth.removeFromFeedGroup(await labelOf(c.label), [c.chat]).catch(() => {});
-      if (want) await intoLabel(want, c.chat);
-      setRoom(k, { label: want });
-    } catch (err) {
-      logError(`as you, label of ${c.name}: ${err.message}`);
-    }
-  }
-
-  // HERDR_MUTED_SPACES says which groups are muted (all, none, or some spaces); a change
-  // in config.env is applied both ways at the next start.
-  async function muteRoom(k, space) {
-    const c = read().chats[k];
-    const want = inSpaces(cfg.muted, space);
-    if (!c || Boolean(c.muted) === want) return;
-    try {
-      await userAuth.setMuted([c.chat], want);
-      setRoom(k, { muted: want });
-    } catch (err) {
-      logError(`as you, mute ${c.chat}: ${err.message}`);
-    }
-  }
-
-  // Everything at once, when acting as you turns on: live groups to their labels, ended
-  // ones to "ended".
-  function alignAll() {
-    for (const [k, c] of Object.entries(read().chats)) {
-      if (!cfg.sessions.includes(c.session)) continue;
-      lane(k, 'as you', () => (c.ended ? endRoom(k) : placeRoom(k, { space: spaceOfName(c.name) })));
-    }
-  }
-
   // ---------- rooms ----------
 
-  // One group per tab, with you in it; what you type there goes to its terminal.
-  async function openRoom({ name, intro }) {
-    return createChat(client, cfg.ownerOpenId, name, intro);
-  }
-
-  async function renameRoom(room, name) {
-    await renameChat(client, room, name);
-  }
-
-  // Puts a live group where it belongs: its avatar, its bot tag and, acting as you, muted
-  // and in your label. Cheap when nothing is left to do.
-  async function placeRoom(k, { space }) {
-    await avatarRoom(k, space);
-    await syncBotTags(k, scopeOf(k));
-    if (!(await asYou())) return;
-    await muteRoom(k, space);
-    await syncUserLabel(k, scopeOf(k));
-  }
-
-  // A group whose terminal is gone keeps its history, tagged "ended".
-  async function endRoom(k) {
-    const c = read().chats[k];
-    if (!c) return;
-    await syncBotTags(k, scopeOf(k));
-    if (!c.avatar) await avatarRoom(k, spaceOfName(c.name));
-    if (!(await asYou())) return;
-    await muteRoom(k, spaceOfName(c.name));
-    await syncUserLabel(k, scopeOf(k));
-  }
-
-  async function reviveRoom(k) {
-    await syncBotTags(k, scopeOf(k));
-    await syncUserLabel(k, scopeOf(k));
-  }
+  const decor = createDecor({ client, cfg, store, log, logError, userAuth, asYou });
+  const rooms = createGroups({ client, cfg, store, logError, lane, scopeOf, userAuth, asYou, decor });
 
   // ---------- posting ----------
 
   const post = (room, markdown) => sendMarkdown(client, room, markdown);
-  const card = ({ title, tone, markdown }) => textCard(markdown, title, TONES[tone] || 'blue');
+  const card = ({ title, tone, markdown }) => textCard(markdown, title, tone);
 
   async function postCard(room, look) {
     const res = await sendCard(client, room, card(look));
@@ -289,43 +90,6 @@ export function create({ cfg, store, log, logWarn, logError, stateDir, lane, sco
     await updateCard(client, message, doneCard(dialog.doneTitle, dialog.markdown, done));
   }
 
-  // The group that needs you is pinned while it waits (acting as you), and unpinned when
-  // it no longer does; which ones are pinned is kept in state.json (pinned).
-  async function pin(k, room) {
-    if (!(await asYou())) return;
-    try {
-      await userAuth.pin(room);
-      const state = read();
-      state.pinned = { ...(state.pinned || {}), [k]: room };
-      write(state);
-    } catch (err) {
-      logError(`pin ${room}: ${err.message}`);
-    }
-  }
-
-  async function unpin(k) {
-    const room = read().pinned?.[k];
-    if (!room) return;
-    try {
-      await userAuth.unpin(room);
-    } catch (err) {
-      logError(`unpin ${room}: ${err.message}`);
-    }
-    const state = read();
-    delete state.pinned[k];
-    write(state);
-  }
-
-  const pinned = () => Object.keys(read().pinned || {});
-
-  // In a muted group only a mention rings; a group that is not muted rings anyway. A
-  // space in HERDR_SILENT_SPACES gets no mention at all.
-  async function ring(k, message, text) {
-    const c = read().chats[k];
-    if (!message || !c?.muted || inSpaces(cfg.silent, spaceOfName(c.name)) || !(await asYou())) return;
-    await replyMention(client, message, cfg.ownerOpenId, text).catch((err) => logError(`mention: ${err.message}`));
-  }
-
   async function addReaction(message, emoji) {
     const res = await client.im.v1.messageReaction.create({ path: { message_id: message }, data: { reaction_type: { emoji_type: emoji } } });
     return res?.data?.reaction_id;
@@ -432,7 +196,14 @@ export function create({ cfg, store, log, logWarn, logError, stateDir, lane, sco
       seen.add(msg.message_id);
       if (seen.size > 2000) seen.delete(seen.values().next().value);
       queued(msg.chat_id, async () => {
-        await handleMessage(data);
+        // whatever goes wrong, you are told it did not get through, and it is not tried
+        // again at every connection
+        try {
+          await handleMessage(data);
+        } catch (err) {
+          logError(`feishu message ${msg.message_id} in ${msg.chat_id}:`, err);
+          if (data.sender?.sender_id?.open_id === cfg.ownerOpenId) await reply(msg.chat_id, `⚠️ Not delivered: it could not be handled (${err.message}). Send it again; \`herdrchat logs\` has the details.`).catch(() => {});
+        }
         markRead(msg.chat_id, Number(msg.create_time) || Date.now());
       });
     };
@@ -455,12 +226,12 @@ export function create({ cfg, store, log, logWarn, logError, stateDir, lane, sco
       }
       const parts = messageParts(msg.message_type, msg.content);
       if (!parts) {
-        await reply(msg.chat_id, 'Only text and images are passed on.');
+        await reply(msg.chat_id, `Not delivered: only text and images are passed on, not this (${msg.message_type}). Copy its text into a message.`);
         return;
       }
       const text = parts.text.replace(/@_user_\d+/g, '').trim();
       if (!text && !parts.images.length) return;
-      await onMessage({ room: msg.chat_type === 'p2p' ? null : msg.chat_id, where: msg.chat_id, message: msg.message_id, text, images: parts.images });
+      await onMessage({ room: rooms.roomOf(msg), where: msg.chat_id, message: msg.message_id, text, images: parts.images });
     };
     // A click must be answered within 3 seconds; the core's answer becomes Feishu's
     // callback response: a toast and, when the card changes, its new form.
@@ -487,7 +258,7 @@ export function create({ cfg, store, log, logWarn, logError, stateDir, lane, sco
     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 || {})]);
+      const chats = new Set([...rooms.roomChats(), ...Object.keys(state.feishuRead || {})]);
       for (const chatId of chats) {
         const since = state.feishuRead?.[chatId];
         if (!since) {
@@ -498,7 +269,7 @@ export function create({ cfg, store, log, logWarn, logError, stateDir, lane, sco
           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);
+          const p2p = !rooms.isRoomChat(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}`);
@@ -544,25 +315,25 @@ export function create({ cfg, store, log, logWarn, logError, stateDir, lane, sco
     name: 'feishu',
     ready: () => Boolean(cfg.ownerOpenId),
     help: ['`/auth` let the bot act as you for chat-list settings (mute, labels, pin)'],
-    roomWord: 'group',
+    roomWord: rooms.roomWord,
     liveBytes: 20000, // a card may hold 30 KB; room for JSON escaping
     split: (text) => chunk(text),
     start,
     command,
-    openRoom,
-    renameRoom,
-    placeRoom,
-    endRoom,
-    reviveRoom,
+    openRoom: rooms.openRoom,
+    renameRoom: rooms.renameRoom,
+    placeRoom: rooms.placeRoom,
+    endRoom: rooms.endRoom,
+    reviveRoom: rooms.reviveRoom,
     post,
     postCard,
     editCard,
     postDialog,
     closeDialog,
-    pin,
-    unpin,
-    pinned,
-    ring,
+    pin: rooms.pin,
+    unpin: rooms.unpin,
+    pinned: rooms.pinned,
+    ring: rooms.ring,
     markWorking,
     markDone,
     image,

package/lib/chats/feishu/overview.mjs

@@ -1,15 +1,17 @@
 // The overview: one card in the direct chat with the bot, as herdr-app's sidebar shows it.
-// Every terminal is a line: its state, its group (a link that opens it), what it waits on
-// and since when. What waits for you comes first. The card is edited in place, so it
-// never rings.
+// Every terminal is a line: its state as a colored tag, its group (a link that opens it),
+// what it waits on and since when. What waits for you
+// comes first. The card is edited in place, so it never rings.
+import { header } from './client.mjs';
+
 const STATES = {
-  blocked: { icon: '⚠️', word: 'needs you', rank: 0 },
-  error: { icon: '🔴', word: 'error', rank: 1 },
-  working: { icon: '⌛️', word: 'working', rank: 2 },
-  done: { icon: '✅', word: 'done', rank: 3 },
-  idle: { icon: '❓', word: 'idle', rank: 4 },
+  blocked: { color: 'orange', word: 'needs you', rank: 0 },
+  error: { color: 'red', word: 'error', rank: 1 },
+  working: { color: 'blue', word: 'working', rank: 2 },
+  done: { color: 'green', word: 'done', rank: 3 },
+  idle: { color: 'neutral', word: 'idle', rank: 4 },
 };
-const OTHER = { icon: '❓', word: '', rank: 5 };
+const OTHER = { color: 'neutral', word: '', rank: 5 };
 
 const chatLink = (chat) => `https://applink.feishu.cn/client/chat/open?openChatId=${chat}`;
 const clock = (ms) => new Date(ms).toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit' });
@@ -24,19 +26,19 @@ export function overviewText(rows) {
     const s = STATES[r.state] || OTHER;
     const name = r.room ? `[${escape(r.name)}](${chatLink(r.room)})` : escape(r.name);
     const word = s === OTHER ? r.program || 'no status' : `${s.word}${r.state === 'blocked' && r.kind ? ` (${r.kind})` : ''}`;
-    return `${s.icon} **${name}** · ${escape(word)}${r.since ? ` · since ${clock(r.since)}` : ''} · \`${r.address}\``;
+    return `<text_tag color='${s.color}'>${escape(word)}</text_tag> **${name}**${r.since ? ` · since ${clock(r.since)}` : ''} · \`${r.address}\``;
   }).join('\n');
 }
 
 export function overviewCard(rows, now) {
   const waiting = rows.filter((r) => r.state === 'blocked').length;
   const working = rows.filter((r) => r.state === 'working').length;
-  const template = waiting ? 'orange' : working ? 'blue' : 'green';
-  const title = `${waiting ? `⚠️ ${waiting} needs you · ` : ''}herdrchat · ${rows.length} terminals`;
+  const tone = waiting ? 'needs' : working ? 'working' : 'good';
+  const title = `${waiting ? `${waiting} needs you · ` : ''}herdrchat · ${rows.length} terminals`;
   return {
     schema: '2.0',
     config: { update_multi: true },
-    header: { title: { tag: 'plain_text', content: title }, template },
-    body: { elements: [{ tag: 'markdown', content: `${overviewText(rows)}\n\n<font color='grey'>Updated ${clock(now)}</font>` }] },
+    header: header(title, tone),
+    body: { elements: [{ tag: 'markdown', content: overviewText(rows) }, { tag: 'markdown', content: `Updated ${clock(now)}`, text_size: 'notation' }] },
   };
 }

package/lib/chats/feishu/rooms/decor.mjs

@@ -0,0 +1,174 @@
+// What a Feishu group wears (groups.mjs makes one per tab): the space's avatar, the bot
+// tags, and, acting as you, your label and its mute. Each call takes an `entry`, {get() -> record, set(fields)}: the record
+// of the group in state.json, {chat, name, avatar, tag, ended, endedTag, label, muted}.
+import { bindTag, createTag, setChatAvatar, tagName, unbindTag, uploadImage } from '../client.mjs';
+import { COLORS, avatarPng, letterOf } from '../avatar.mjs';
+
+const ENDED_TAG = '#ended';
+const ENDED_LABEL = 'ended';
+
+export const inSpaces = (set, space) => set.all || set.spaces.includes(space);
+export const spaceOfName = (name) => (name || '').split(' / ')[0];
+
+// asYou() -> whether the bot may act as you now (index.mjs keeps that)
+export function createDecor({ client, cfg, store, log, logError, userAuth, asYou }) {
+  const { read, write } = store;
+
+  // Lanes run side by side: a thing that is made once (a tag, a space's avatar) is made
+  // by the first lane that needs it; the others wait for that.
+  const making = new Map();
+  function once(id, make) {
+    if (!making.has(id)) making.set(id, make().finally(() => making.delete(id)));
+    return making.get(id);
+  }
+
+  // ---------- tags and avatars ----------
+
+  // One tenant tag per session or machine, made once, and one "ended" tag; their ids are
+  // kept in state.json (tags).
+  async function tagOf(id, name = id) {
+    return read().tags?.[id] || once(`tag ${id}`, async () => {
+      const tag = await createTag(client, name);
+      const state = read();
+      state.tags = { ...(state.tags || {}), [id]: tag };
+      write(state);
+      log(`created tag ${name} (${tag})`);
+      return tag;
+    });
+  }
+
+  // Each space gets an avatar: its first letter on a color of its own (the first color no
+  // other space has), kept in state.json (spaces), so all of its groups look alike, as in
+  // herdr-app. The color is picked and saved before the first await, so spaces made side
+  // by side never pick the same one. A failure is logged and tried again at the next check.
+  function colorOf(space) {
+    const state = read();
+    const spaces = state.spaces || {};
+    if (spaces[space]?.color) return spaces[space].color;
+    const used = Object.values(spaces).map((x) => x.color);
+    const color = COLORS.find((c) => !used.includes(c)) || COLORS[used.length % COLORS.length];
+    state.spaces = { ...spaces, [space]: { color } };
+    write(state);
+    return color;
+  }
+
+  async function avatarOf(space) {
+    return read().spaces?.[space]?.image || once(`avatar ${space}`, async () => {
+      const color = colorOf(space);
+      const image = await uploadImage(client, await avatarPng(letterOf(space), color), 'avatar');
+      const state = read();
+      state.spaces = { ...(state.spaces || {}), [space]: { color, image } };
+      write(state);
+      log(`made avatar for space ${space} (${color})`);
+      return image;
+    });
+  }
+
+  // the space's avatar; a no-op when the group has it, so it follows a space that changes
+  async function avatar(entry, space) {
+    const c = entry.get();
+    if (!c) return;
+    try {
+      const image = await avatarOf(space);
+      if (c.avatar === image) return;
+      await setChatAvatar(client, c.chat, image);
+      entry.set({ avatar: image });
+    } catch (err) {
+      logError(`avatar ${space} on ${c.chat}: ${err.message}`);
+    }
+  }
+
+  // Bot tags (HERDR_BOT_TAGS): the session or machine tag next to a group's name and, once
+  // its terminal is gone, "ended". They are tenant tags, so they can be turned off; off
+  // takes off the ones already on. A failure is logged and tried again at the next check.
+  async function botTags(entry, scope) {
+    const c = entry.get();
+    if (!c) return;
+    try {
+      if (cfg.botTags) {
+        const tag = await tagOf(scope);
+        if (c.tag !== tag) {
+          await bindTag(client, tag, c.chat);
+          entry.set({ tag });
+        }
+        if (Boolean(c.ended) !== Boolean(c.endedTag)) {
+          const ended = await tagOf(ENDED_TAG, 'ended');
+          await (c.ended ? bindTag : unbindTag)(client, ended, c.chat);
+          entry.set({ endedTag: Boolean(c.ended) });
+        }
+      } else {
+        const tags = read().tags || {};
+        if (c.tag) {
+          await unbindTag(client, c.tag, c.chat).catch(() => {});
+          entry.set({ tag: null });
+        }
+        if (c.endedTag && tags[ENDED_TAG]) {
+          await unbindTag(client, tags[ENDED_TAG], c.chat).catch(() => {});
+          entry.set({ endedTag: false });
+        }
+      }
+    } catch (err) {
+      logError(`bot tags on ${c.name}: ${err.message}`);
+    }
+  }
+
+  // ---------- acting as you ----------
+
+  async function labelOf(name) {
+    return read().labels?.[name] || once(`label ${name}`, async () => {
+      const found = (await userAuth.feedGroups())?.groups?.find((g) => g.name === name);
+      const id = found?.group_id || (await userAuth.createFeedGroup(name))?.group_id;
+      if (!id) throw new Error(`no label ${name}`);
+      const state = read();
+      state.labels = { ...(state.labels || {}), [name]: id };
+      write(state);
+      log(`label ${name} (${id})`);
+      return id;
+    });
+  }
+
+  // A label you deleted is made again at the next try.
+  async function intoLabel(name, chat) {
+    try {
+      await userAuth.addToFeedGroup(await labelOf(name), [chat]);
+    } catch (err) {
+      const state = read();
+      if (state.labels) delete state.labels[name];
+      write(state);
+      throw err;
+    }
+  }
+
+  // Your label (HERDR_USER_TAGS, acting as you): the session or machine, or "ended" once
+  // the terminal is gone; off takes the group out of it (the label itself is yours).
+  async function userLabel(entry, scope) {
+    if (!(await asYou())) return;
+    const c = entry.get();
+    if (!c) return;
+    const want = cfg.userTags ? (c.ended ? ENDED_LABEL : tagName(scope)) : null;
+    if ((c.label || null) === want) return;
+    try {
+      if (c.label) await userAuth.removeFromFeedGroup(await labelOf(c.label), [c.chat]).catch(() => {});
+      if (want) await intoLabel(want, c.chat);
+      entry.set({ label: want });
+    } catch (err) {
+      logError(`as you, label of ${c.name}: ${err.message}`);
+    }
+  }
+
+  // HERDR_MUTED_SPACES says which groups are muted (all, none, or some spaces); a change
+  // in config.env is applied both ways at the next start.
+  async function mute(entry, space) {
+    const c = entry.get();
+    const want = inSpaces(cfg.muted, space);
+    if (!c || Boolean(c.muted) === want) return;
+    try {
+      await userAuth.setMuted([c.chat], want);
+      entry.set({ muted: want });
+    } catch (err) {
+      logError(`as you, mute ${c.chat}: ${err.message}`);
+    }
+  }
+
+  return { avatar, botTags, userLabel, mute };
+}

package/lib/chats/feishu/rooms/groups.mjs

@@ -0,0 +1,110 @@
+// One Feishu group per herdr-app tab, with you in it; what you type there goes to its
+// terminal. A room is the group's chat id. The group wears its space's avatar, its tags
+// and, acting as you, its mute and your label (decor.mjs); the group that needs you is
+// pinned. index.mjs calls only what is returned here.
+import { createChat, renameChat, replyMention } from '../client.mjs';
+import { inSpaces, spaceOfName } from './decor.mjs';
+
+export function createGroups({ client, cfg, store, logError, lane, scopeOf, userAuth, asYou, decor }) {
+  const { read, write } = store;
+  const entryOf = (k) => ({
+    get: () => read().chats[k],
+    set: (fields) => {
+      const state = read();
+      if (state.chats[k]) state.chats[k] = { ...state.chats[k], ...fields };
+      write(state);
+    },
+  });
+
+  async function openRoom({ name, intro }) {
+    return createChat(client, cfg.ownerOpenId, name, intro);
+  }
+
+  async function renameRoom(room, name) {
+    await renameChat(client, room, name);
+  }
+
+  // Puts a live group where it belongs: its avatar, its bot tag and, acting as you, muted
+  // and in your label. Cheap when nothing is left to do.
+  async function placeRoom(k, { space }) {
+    const entry = entryOf(k);
+    await decor.avatar(entry, space);
+    await decor.botTags(entry, scopeOf(k));
+    if (!(await asYou())) return;
+    await decor.mute(entry, space);
+    await decor.userLabel(entry, scopeOf(k));
+  }
+
+  // A group whose terminal is gone keeps its history, tagged "ended".
+  async function endRoom(k) {
+    const entry = entryOf(k);
+    const c = entry.get();
+    if (!c) return;
+    await decor.botTags(entry, scopeOf(k));
+    if (!c.avatar) await decor.avatar(entry, spaceOfName(c.name));
+    if (!(await asYou())) return;
+    await decor.mute(entry, spaceOfName(c.name));
+    await decor.userLabel(entry, scopeOf(k));
+  }
+
+  async function reviveRoom(k) {
+    const entry = entryOf(k);
+    await decor.botTags(entry, scopeOf(k));
+    await decor.userLabel(entry, scopeOf(k));
+  }
+
+  // Everything at once, when acting as you turns on: live groups to their labels, ended
+  // ones to "ended".
+  function alignAll() {
+    for (const [k, c] of Object.entries(read().chats)) {
+      if (!cfg.sessions.includes(c.session)) continue;
+      lane(k, 'as you', () => (c.ended ? endRoom(k) : placeRoom(k, { space: spaceOfName(c.name) })));
+    }
+  }
+
+  // The group that needs you is pinned while it waits (acting as you), and unpinned when
+  // it no longer does; which ones are pinned is kept in state.json (pinned).
+  async function pin(k, room) {
+    if (!(await asYou())) return;
+    try {
+      await userAuth.pin(room);
+      const state = read();
+      state.pinned = { ...(state.pinned || {}), [k]: room };
+      write(state);
+    } catch (err) {
+      logError(`pin ${room}: ${err.message}`);
+    }
+  }
+
+  async function unpin(k) {
+    const room = read().pinned?.[k];
+    if (!room) return;
+    try {
+      await userAuth.unpin(room);
+    } catch (err) {
+      logError(`unpin ${room}: ${err.message}`);
+    }
+    const state = read();
+    delete state.pinned[k];
+    write(state);
+  }
+
+  const pinned = () => Object.keys(read().pinned || {});
+
+  // In a muted group only a mention rings; a group that is not muted rings anyway. A
+  // space in HERDR_SILENT_SPACES gets no mention at all.
+  async function ring(k, message, text) {
+    const c = read().chats[k];
+    if (!message || !c?.muted || inSpaces(cfg.silent, spaceOfName(c.name)) || !(await asYou())) return;
+    await replyMention(client, message, cfg.ownerOpenId, text).catch((err) => logError(`mention: ${err.message}`));
+  }
+
+  // A message, to the core's words: the room it came from (null: the direct chat).
+  const roomOf = (msg) => (msg.chat_type === 'p2p' ? null : msg.chat_id);
+  // The chats whose messages the bot reads (to look for what it missed), and whether a
+  // chat is one of them rather than the direct chat.
+  const roomChats = () => Object.values(read().chats || {}).filter((c) => !c.ended).map((c) => c.chat);
+  const isRoomChat = (chatId) => Object.values(read().chats || {}).some((c) => c.chat === chatId);
+
+  return { roomWord: 'group', openRoom, renameRoom, placeRoom, endRoom, reviveRoom, alignAll, pin, unpin, pinned, ring, roomOf, roomChats, isRoomChat };
+}

package/lib/chats/feishu/userauth.mjs

@@ -107,7 +107,16 @@ export function createUserAuth(cfg, dir) {
   return {
     startDeviceFlow,
     waitForToken,
-    allowed: async () => Boolean(await token().catch(() => null)),
+    // false only when there is no token or Feishu refused to refresh it; a call that did not
+    // get through (the network) throws, so a moment offline is not taken for a revoked /auth
+    allowed: async () => {
+      try {
+        return Boolean(await token());
+      } catch (err) {
+        if (/^token refresh:/.test(err.message)) return false;
+        throw err;
+      }
+    },
     setMuted: (chatIds, muted) => call('POST', '/open-apis/im/v1/chat_user_setting/batch_update', { chat_settings: chatIds.map((chat_id) => ({ chat_id, is_muted: muted })) }),
     feedGroups: () => call('GET', '/open-apis/im/v1/groups?page_size=50&page_token='),
     createFeedGroup: (name) => call('POST', '/open-apis/im/v1/groups', { feed_group_creator: { name, type: 'normal' } }),

package/lib/chats/telegram/index.mjs

@@ -399,6 +399,9 @@ export function create({ cfg, store, log, logWarn, logError, claimOwner = () =>
               if (u.callback_query) await handleClick(u.callback_query, onAction);
             } catch (err) {
               logError(`telegram update ${u.update_id}:`, err);
+              // a message that could not be handled: you are told, never left guessing
+              const m = u.message;
+              if (m && String(m.from?.id || '') === owner) await reply(`${m.chat.id}:${m.is_topic_message ? m.message_thread_id : ''}`, `⚠️ Not delivered: it could not be handled (${err.message}). Send it again; \`herdrchat logs\` has the details.`).catch(() => {});
             }
             // saved once handled: a crash halfway handles it again, never skips it
             offset = u.update_id + 1;

package/lib/core/cursor.mjs

@@ -19,7 +19,10 @@ function after(cursor, at, id) {
 
 function idOf(entry) {
   if (entry.uuid) return entry.uuid;
-  return crypto.createHash('sha1').update(`${entry.type}|${entry.timestamp}|${entry.operation || ''}|${entry.content || ''}`).digest('hex');
+  // Codex keeps what an entry is in `payload` (an item has its own id): two entries in the
+  // same millisecond must not share an id, or the second would count as posted
+  const payload = entry.payload ? `|${entry.payload.item?.id || entry.payload.id || entry.payload.call_id || JSON.stringify(entry.payload).slice(0, 4000)}` : '';
+  return crypto.createHash('sha1').update(`${entry.type}|${entry.timestamp}|${entry.operation || ''}|${entry.content || ''}${payload}`).digest('hex');
 }
 
 // The items after `cursor` in log `lines`, in order, using `entryItems(entry)` (the

package/lib/core/engine.mjs

@@ -160,7 +160,9 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
   // dropped, so a spinner in a title never renames a room.
   function tabName(where, record) {
     if (!/^\d+$/.test(where.tab)) return where.tab;
-    const title = String(record.title || '').replace(/^[^\p{L}\p{N}]+/u, '').replace(/\s+/g, ' ').trim();
+    // an agent whose title holds more than a name (Codex: "<thread> | <folder>") says which part
+    const titled = agentOf(record)?.titleOf?.(record.title) ?? record.title;
+    const title = String(titled || '').replace(/^[^\p{L}\p{N}]+/u, '').replace(/\s+/g, ' ').trim();
     const name = title || record.name || '';
     if (!name) return where.tab;
     return name.length > TITLE_MAX ? `${name.slice(0, TITLE_MAX - 1)}…` : name;

package/lib/core/home.mjs

@@ -17,6 +17,16 @@ export async function homeFile(session, machine, rel, { tail } = {}) {
   return hc(session, ['exec', '--on', machine, ...argv], { timeoutMs: 30000 });
 }
 
+// A short shell command in the home folder of the machine a terminal runs on: here, or
+// through `hc exec --on <machine>`. Its output; empty when it fails.
+export async function homeShell(session, machine, script) {
+  if (!machine) {
+    const { execFile } = await import('node:child_process');
+    return new Promise((resolve) => execFile('sh', ['-c', script], { cwd: os.homedir(), timeout: 30000 }, (err, stdout) => resolve(err && !stdout ? '' : String(stdout))));
+  }
+  return hc(session, ['exec', '--on', machine, 'sh', '-c', script], { timeoutMs: 30000 }).catch(() => '');
+}
+
 // The items after `cursor` in a .jsonl log: its tail first, the whole file when the tail
 // does not reach back to the cursor.
 export async function logAfter(session, machine, rel, cursor, entryItems) {

package/lib/core/menu.mjs

@@ -1,5 +1,6 @@
 // The menu a blocked program shows on its screen, as Claude Code draws its permission
-// and question dialogs:
+// and question dialogs (Codex draws its approvals alike, with › for the cursor, no border,
+// and the dialog under the "• Running …" line of what it asks about):
 //   ❯ 1. Yes                      a digit key picks an option
 //     2. [✔] Red                  in a multi-select, a digit toggles it; tab goes on
 //     3. Type something.          picking it lets you type your own answer
@@ -20,7 +21,9 @@
 // nor of the key; a question's own left border (│) goes too.
 import crypto from 'node:crypto';
 
-const OPTION = /^\s*(?:❯\s*)?(\d{1,2})\.\s+(?:\[(.)\]\s+)?(.*\S)\s*$/;
+const OPTION = /^\s*(?:[❯›]\s*)?(\d{1,2})\.\s+(?:\[(.)\]\s+)?(.*\S)\s*$/;
+const CURSOR = /[❯›]/;
+const ITEM = /^•\s/; // a Codex item, at the left edge: what its dialog asks about
 const RULE = /^[\s─╌━-]*$/;
 const BORDER = /^\s*─{10,}/;
 const FREE = /^Type something/i;
@@ -31,10 +34,14 @@ const ownPart = (line) => line.replace(BESIDE, '').replace(LEFT_BORDER, '$1');
 
 const TEXT_LINES = 15; // a dialog with no border found: this many lines above its options
 
+// {top, framed}: the dialog's top border; with none above it, the nearest Codex item line
+// (also a known edge); else TEXT_LINES above its options, not known as a dialog
 function topOf(lines, first) {
   let top = first;
   while (top > 0 && !BORDER.test(lines[top])) top -= 1;
-  return BORDER.test(lines[top]) ? top : Math.max(0, first - TEXT_LINES);
+  if (BORDER.test(lines[top])) return { top, framed: true };
+  for (let i = first - 1; i >= 0; i -= 1) if (ITEM.test(lines[i])) return { top: i, framed: true };
+  return { top: Math.max(0, first - TEXT_LINES), framed: false };
 }
 
 const MARKS = /[☐☑☒✔✓✗✘■□●○◉◯]/gu;
@@ -42,7 +49,7 @@ const MARKS = /[☐☑☒✔✓✗✘■□●○◉◯]/gu;
 // Joined with spaces, not line breaks: the same dialog wraps at other places when the
 // terminal is resized (herdr-app opened on a phone), and it is still the same dialog.
 function keyOf(lines, top, last) {
-  const body = lines.slice(top, last + 1).map((l) => l.replace(/❯/g, '').replace(/^(\s*\d{1,2}\.\s+)\[.\]/, '$1').replace(MARKS, '')).join(' ').replace(/\s+/g, ' ').trim();
+  const body = lines.slice(top, last + 1).map((l) => l.replace(/[❯›]/g, '').replace(/^(\s*\d{1,2}\.\s+)\[.\]/, '$1').replace(MARKS, '')).join(' ').replace(/\s+/g, ' ').trim();
   return crypto.createHash('sha1').update(body).digest('hex').slice(0, 12);
 }
 
@@ -65,16 +72,16 @@ export function menuOf(screen) {
     menu = run;
   });
   if (!menu) return null;
-  const top = topOf(lines, menu.first);
+  const { top, framed } = 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;
+  const cursor = menu.options.find((o) => raw.slice(menu.first, menu.last + 1).some((l) => CURSOR.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
+    framed, // a dialog's known top; a numbered list in text has none
     text: lines.slice(top, menu.first).filter((l) => !RULE.test(l)).map((l) => l.trim()).join('\n'),
     options: menu.options,
     multi: menu.options.some((o) => o.checked !== null),

package/lib/core/readers/codex.mjs

@@ -0,0 +1,134 @@
+// Reader for Codex (hc status app "codex"): its own rollout log.
+//   Where: Codex writes each session to ~/.codex/sessions/YYYY/MM/DD/rollout-<time>-<id>.jsonl,
+//     whose first line (session_meta) names its cwd. It does not keep the file open or
+//     name its pid anywhere outside its database, so the log is found as the one written
+//     since the terminal's codex started, in the cwd it runs in; with two such, the one
+//     whose session began nearest after that start (a resumed session began before it,
+//     and then the newest file wins). Found once per codex process.
+//   What becomes an item: the "item_completed" events, one per finished item, as Codex
+//     itself shows them:
+//     you  UserMessage: what you typed
+//     ai   AgentMessage: what it said; `phase` "commentary" while it works, "final_answer"
+//          at the end, which marks `end` (a question it asks the async way, with its
+//          choices in the text, is a final answer too, but the turn goes on after it)
+//     tool CommandExecution (a command it ran), FileChange (files it added, changed or
+//          removed), and any other item but reasoning, as one line
+import path from 'node:path';
+import { getTerminal, machineOf } from '../hc.mjs';
+import { homeShell, logAfter } from '../home.mjs';
+import { itemsAfter } from '../cursor.mjs';
+
+export const app = 'codex';
+export const processes = ['codex'];
+
+const textOf = (content) => (Array.isArray(content) ? content.filter((c) => /^text$/i.test(c.type) && c.text).map((c) => c.text).join('\n') : '');
+const short = (s, max = 120) => {
+  const one = String(s || '').replace(/\s+/g, ' ').trim();
+  return one.length > max ? `${one.slice(0, max - 3)}...` : one;
+};
+
+function commandOf(item) {
+  const argv = Array.isArray(item.command) ? item.command : [item.command];
+  // a shell's `-lc <command>` shows as the command itself
+  const at = argv.findIndex((a) => a === '-lc' || a === '-c');
+  return at >= 0 && argv[at + 1] ? argv[at + 1] : argv.join(' ');
+}
+
+function entryItems(entry) {
+  if (entry.type !== 'event_msg' || entry.payload?.type !== 'item_completed') return [];
+  const item = entry.payload.item || {};
+  switch (item.type) {
+    case 'UserMessage': {
+      const t = textOf(item.content).trim();
+      return t ? [{ role: 'you', text: t }] : [];
+    }
+    case 'AgentMessage': {
+      const t = textOf(item.content).trim();
+      return t ? [{ role: 'ai', text: t, end: item.phase === 'final_answer' && item.delivery !== 'async' }] : [];
+    }
+    case 'CommandExecution':
+      return [{ role: 'tool', text: `▸ exec: ${short(commandOf(item))}` }];
+    case 'FileChange': {
+      const changes = Object.entries(item.changes || {}).map(([file, c]) => `${c.type || 'change'} ${path.basename(file)}`);
+      return [{ role: 'tool', text: `▸ edit: ${short(changes.join(', ') || 'files')}` }];
+    }
+    default:
+      return item.type && !/reasoning/i.test(item.type) ? [{ role: 'tool', text: `▸ ${item.type}` }] : [];
+  }
+}
+
+export function conversationAfter(lines, cursor) {
+  return itemsAfter(lines, cursor, entryItems);
+}
+
+// "[[dd-]hh:]mm:ss", as ps prints how long a process has run
+export function seconds(etime) {
+  const t = String(etime).trim();
+  const [days, rest] = t.includes('-') ? t.split('-') : ['0', t];
+  const parts = rest.split(':').map(Number);
+  while (parts.length < 3) parts.unshift(0);
+  return Number(days) * 86400 + parts[0] * 3600 + parts[1] * 60 + parts[2];
+}
+
+// lines "file\t"cwd":"…"\t"timestamp":"…"" -> the log of the codex that started at `started`
+export function pickLog(list, cwd, started) {
+  const mine = list.split('\n').map((l) => l.split('\t')).filter(([f, c]) => f && c === `"cwd":"${cwd}"`)
+    .map(([file, , ts]) => ({ file, began: Date.parse(String(ts || '').replace(/^"timestamp":"|"$/g, '')) || 0 }));
+  if (!mine.length) return null;
+  const fresh = mine.filter((m) => m.began >= started - 5000).sort((a, b) => a.began - b.began);
+  return (fresh[0] || [...mine].sort((a, b) => b.file.localeCompare(a.file))[0]).file;
+}
+
+const LIST = (minutes) => [
+  `find .codex/sessions -name 'rollout-*.jsonl' -mmin -${minutes} 2>/dev/null | while read -r f; do`,
+  `printf '%s\\t%s\\t%s\\n' "$f" "$(head -n1 "$f" | grep -o '"cwd":"[^"]*"' | head -1)" "$(head -n1 "$f" | grep -o '"timestamp":"[^"]*"' | head -1)";`,
+  'done',
+].join(' ');
+
+const found = new Map(); // `${session}|${address}|${pid}` -> the log (relative to home)
+
+async function logOf(session, address, fg) {
+  const key = `${session}|${address}|${fg.pid}`;
+  if (found.has(key)) return found.get(key);
+  const machine = machineOf(address);
+  const age = (await homeShell(session, machine, `ps -o etime= -p ${Number(fg.pid)}`)).trim();
+  if (!age) return null;
+  const started = Date.now() - seconds(age) * 1000;
+  const minutes = Math.ceil((Date.now() - started) / 60000) + 1;
+  const file = pickLog(await homeShell(session, machine, LIST(minutes)), fg.cwd, started);
+  if (file) found.set(key, file);
+  return file;
+}
+
+// What is new since `cursor`: {items, file}, or null when the terminal runs no codex whose
+// log is found. A new codex in the same terminal (a new process) reads its own log; what
+// is left in the cursor's old one comes first.
+export async function after(session, address, cursor) {
+  const fg = (await getTerminal(session, address)).foreground;
+  if (!fg?.pid || !fg.cwd) return null;
+  const file = await logOf(session, address, fg);
+  if (!file) return null;
+  const machine = machineOf(address);
+  const items = [];
+  if (cursor.file && cursor.file !== file) {
+    try {
+      items.push(...(await logAfter(session, machine, cursor.file, cursor, entryItems)));
+    } catch {
+      // the old log is gone; nothing left to read there
+    }
+  }
+  items.push(...(await logAfter(session, machine, file, cursor, entryItems)));
+  return { items, file };
+}
+
+export function rest(session, address, cursor) {
+  return logAfter(session, machineOf(address), cursor.file, cursor, entryItems);
+}
+
+// The room's name from the terminal's title: Codex titles it "<thread> | <folder>", led by
+// a spinner while it works and by "[ . ] Action Required | " while it waits on you. The
+// thread is "codex" until Codex names it; the name stays put while its state changes.
+export function titleOf(title) {
+  const plain = String(title || '').replace(/^[^\p{L}\p{N}[]+/u, '').replace(/^\[[^\]]*\]\s*Action Required\s*\|\s*/i, '');
+  return plain.split(' | ')[0].trim();
+}

package/lib/core/readers/index.mjs

@@ -11,6 +11,8 @@
 //                                       the log it read, kept in the cursor
 //   rest(session, address, cursor)   -> items: what `cursor.file` still holds after the
 //                                       program is gone
+//   titleOf(title)                   (optional) the room's name from the terminal's title,
+//                                       when the agent's title holds more than a name
 // Items are {role: 'you' | 'ai' | 'tool', text, at, id, end?} (`end` marks the turn's last
 // answer) or {role: 'image', from: 'you' | 'ai', media, data (base64), at, id}.
 // Cursors are in ../cursor.mjs.
@@ -19,6 +21,7 @@
 // (docs/architecture.md, "Adding an agent").
 import path from 'node:path';
 import * as claude from './claude.mjs';
+import * as codex from './codex.mjs';
 
 // What every reader exports (see above); checked for each one listed here when this
 // loads, so a reader that misses one fails at start, not when its agent first runs.
@@ -29,7 +32,7 @@ export function checkReader(reader) {
   return reader;
 }
 
-export const LISTED = [claude].map(checkReader);
+export const LISTED = [claude, codex].map(checkReader);
 const READERS = new Map(LISTED.map((r) => [r.app, r]));
 
 export function readerFor(app) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "herdrchat",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "The chat client for hc (herdr): see and answer every hc terminal from Feishu or Telegram",
   "repository": {
     "type": "git",