bothouse-dsh 0.1.47 → 0.1.49

package/collab/dsh-member.mjs

@@ -17,7 +17,9 @@ import { GateContext } from './gate-context.mjs';
 import { MemoryIndex } from './memory-index.mjs';
 // Shared with the bridge (bridge/core/team_mode.go): a common part, then one
 // "## <mode>" section per dispatch mode; a member sees only its room's section.
-const TEAM_MODE_FILE = readFileSync(new URL('./team-mode-rules.md', import.meta.url), 'utf8');
+// A Windows checkout (git core.autocrlf) turns the file to CRLF: "## solo\r\n" then misses the
+// `${mode}\n` match below and every member turn failed with "reading 'slice'". Read it as LF.
+const TEAM_MODE_FILE = readFileSync(new URL('./team-mode-rules.md', import.meta.url), 'utf8').replace(/\r\n?/g, '\n');
 export function teamModeRules(mode = DEFAULT_DISPATCH_MODE) {
   const [common, ...parts] = TEAM_MODE_FILE.split(/^## /m);
   const section = parts.find(p => p.startsWith(`${mode}\n`)) ?? parts.find(p => p.startsWith(`${DEFAULT_DISPATCH_MODE}\n`));
@@ -26,7 +28,7 @@ export function teamModeRules(mode = DEFAULT_DISPATCH_MODE) {
 /** #597 G24: the open-workspace command, for the selected primary role only, never in bridge prompts. */
 export function workspaceHint(hub, later, memberId, roomId) {
   if (!later?.workspaceInstructions || hub?.primaryIn?.(roomId)?.id !== memberId) return '';
-  return later.workspaceInstructions(memberId, roomId);
+  return later.workspaceInstructions(memberId, roomId) + (later.teamInstructions?.(memberId, roomId) ?? '');
 }
 /**
  * #597 G24: DSH members have no bridge session, so the shared line about `bothouse workspace new` /
@@ -199,8 +201,11 @@ const INTERRUPTED = Symbol('interrupted');
 export function friendlyFailure(raw) {
   if (raw?.code === 'COLLAB_CLI_START') return raw.message;
   const text = String(raw);
-  if (/no.{0,12}(api.?key|key)|missing.{0,12}(key|credential)|api.?key.{0,12}(missing|not set|required)|未配置.*key/i.test(text)) return '还没有配置模型的 API Key，请先去配置模型。';
+  if (/no.{0,12}(api.?key|key)|missing.{0,12}(key|credential)|api.?key.{0,12}(missing|not set|required)|未配置.*key/i.test(text)) return '还没填模型密钥，填好就能用。';
   if (/model.{0,30}(not found|unavailable|not available|unsupported)|unknown model|模型.*不可用|404/i.test(text)) return '这个模型暂时不可用，请检查模型名称或换一个模型。';
+  // An unreachable provider is a setting or network problem. Echoing the transport wording
+  // ("Connection error.") behind "请检查配置" told the user nothing about which setting to fix.
+  if (/connection error|econnrefused|econnreset|enotfound|etimedout|eai_again|fetch failed|socket hang up|network ?(error|request failed)|timed out|timeout/i.test(text)) return '连不上模型服务：中转站地址或网络不通。请检查设置里的模型地址和 Key，或换一个中转站再试。';
   if (/login|log.?in|auth|unauthorized|401|未登录/i.test(text)) return '模型或 CLI 还没有登录，或登录已过期。请先登录后再试。';
   if (/exit|ENOENT|spawn|没有输出文字/i.test(text)) return '本机 CLI 未能正常运行或已退出，请检查安装和登录状态。';
   // A Host older than this plugin has no scope lease on its preset registry, so no member can be
@@ -457,7 +462,7 @@ export class DshMembers {
     const running = [];
     for (const job of this.store.openJobs()) {
       if (job.trigger_id !== triggerId) continue;
-      if (job.state === 'pending') { this.store.finishJob(job.id, 'interrupted'); continue; }
+      if (job.state === 'pending') { this.store.finishJob(job.id, 'interrupted'); this.syncQueue(job.member_id, job.room_id); continue; }
       const w = this.watching.get(job.session_id);
       const agent = job.input_id ? this.rt.ctx.agents.get(job.session_id) : undefined;
       if (w?.jobId !== job.id || agent === undefined) { running.push(job.member_id); continue; }
@@ -580,14 +585,29 @@ export class DshMembers {
   /** Serialize work per (member, room): runs, recoveries, and Session resumes never overlap. */
   enqueue(job, task) {
     const key = `${job.member_id}\u0000${job.room_id}`;
-    const tail = (this.queues.get(key) ?? Promise.resolve()).then(() => (this.closed ? undefined : task())).catch((error) => {
+    const sync = () => this.syncQueue(job.member_id, job.room_id);
+    const tail = (this.queues.get(key) ?? Promise.resolve()).then(() => { sync(); return this.closed ? undefined : task(); }).catch((error) => {
       this.rt.logger.warn('collab: DSH job %d failed: %s', job.id, error?.stack ?? error);
       if (!this.closed) this.fail(job.id, error?.code === 'COLLAB_CLI_START' ? error : `出错了：${error?.message ?? error}`);
-    });
+    }).finally(sync);
     this.queues.set(key, tail);
+    sync();
     return tail;
   }
 
+  /**
+   * #1020: tell the hub which of the owner's messages wait for this member here — its open
+   * jobs after the first (the one running or about to), still pending. Withdrawing one is the
+   * existing recall (#148 a queued job is closed).
+   */
+  syncQueue(memberId, roomId) {
+    if (typeof this.hub.setQueue !== 'function') return;
+    const open = this.store.openJobs().filter(j => j.member_id === memberId && j.room_id === roomId);
+    const ids = open.slice(1).filter(j => j.state === 'pending').map(j => j.trigger_id)
+      .filter(id => this.store.message(id)?.author_kind === 'user');
+    this.hub.setQueue(roomId, memberId, ids);
+  }
+
   async run(jobId) {
     const job = this.store.job(jobId);
     if (job === undefined || job.state !== 'pending') return;
@@ -652,7 +672,9 @@ export class DshMembers {
     let entry = this.cliAgents.get(cliKey);
     if (entry === undefined) {
       // Persona goes through promptText every turn, so an edit applies without restarting the CLI.
-      entry = { memberId: member.id, cli: member.cli, agent: this.rt.createCliMember({ cli: member.cli, cwd, persona: '' }) };
+      entry = { memberId: member.id, cli: member.cli, agent: this.rt.createCliMember({ cli: member.cli, cwd, persona: '',
+        // #1020: memvote.py records citations under these (memory-sources.mjs), named as the gate key (gate-context.mjs).
+        env: { CC_PROJECT: `dsh:${member.id}`, CC_SESSION_KEY: `dsh:${member.id}:${room.id}` } }) };
       this.cliAgents.set(cliKey, entry);
     }
     this.hub.setError(member.id, undefined);
@@ -863,6 +885,24 @@ export class DshMembers {
     if (this.closed) return;
     const job = this.store.job(jobId);
     if (job === undefined || !this.store.finishJob(jobId, state)) return;
+    // A restart is not a configuration problem: the member is healthy and only the turn it was
+    // running is lost, so it takes a retry button and leaves the member online. Reporting it as
+    // "成员出错 / 去配置模型" also cooled the provider quota for what was a process restart.
+    if (state === 'interrupted') {
+      this.hub.setError(job.member_id, undefined);
+      this.hub.post(job.room_id, {
+        authorKind: 'system', author: 'system', name: 'system', text: String(notice), clientKey: `dsh-job-${jobId}-${state}-${Date.now()}`,
+        card: JSON.stringify({
+          title: '被中断',
+          state: 'failed',
+          action: 'retry',
+          job_id: jobId,
+          member_id: job.member_id,
+          trigger_id: job.trigger_id,
+        }),
+      });
+      return;
+    }
     this.hub.quota?.observe(job.member_id, job.room_id, { error: String(notice) });
     const error = friendlyFailure(notice);
     this.hub.setError(job.member_id, error);

package/collab/gate-context.mjs

@@ -1,21 +1,95 @@
 // Per-turn wiki pages and task board for DSH-native members, from the local gate's
 // POST /context (bridge/contrib/gate/gate.py -> ctxsvc.context): the same source and the same
-// block the bridge puts before a bot's turn (bridge/core/gate.go turnContext). The gate's port
-// comes from GATE_PORT, which bothouse sets on the `dsh web` it starts to the port it runs the
-// gate on (core/gate_proc.go gatePort); without it, or with the gate down, a turn goes out as before.
+// block the bridge puts before a bot's turn (bridge/core/gate.go turnContext).
+//
+// The gate's port: GATE_PORT, which bothouse sets on the `dsh web` it starts to the port it runs the
+// gate on (core/gate_proc.go gatePort). A `dsh web` started another way (reload-dsh.py reusing an old
+// environment, the desktop app) has no GATE_PORT, so it is read from the same config.toml the bridge
+// itself reads: [gate] port (core/gate_proc.go LocalGatePort), default 9930 when the file has no
+// [gate] table (that is gate.py's own PORT). Without a config file either, no port: a turn goes out
+// as before, and the log says why instead of the badge and the pages vanishing without a word.
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { dataDirCandidates } from './memory-sources.mjs';
 
 // Same as the bridge's wait for /context (core/gate.go turnContext: 2s).
 export const GATE_CONTEXT_TIMEOUT_MS = 2_000;
+// 来源：contrib/gate/gate.py PORT = 9930，core/setup_wizard_warnings.go defaultGatePort 同值
+// （LocalGatePort 在 config [gate] port 缺省或为 0 时也用它）。
+export const DEFAULT_GATE_PORT = 9930;
+
+/** `port\0where` of the log lines already written: one line per process, not one per member. */
+const announced = new Set();
+
+/** `[gate] port` of a bridge config's text, as Go reads cfg.Gate.Port; 0 when it has no such table. */
+export function gatePortSetting(text) {
+  let inside = false;
+  for (const line of String(text).split(/\r?\n/)) {
+    const header = /^\s*\[\s*([^\]]+?)\s*\]/.exec(line);
+    if (header !== null) { inside = header[1] === 'gate'; continue; }
+    if (!inside) continue;
+    const kv = /^\s*port\s*=\s*(\d+)\s*(?:#.*)?$/.exec(line);
+    if (kv === null) continue;
+    const port = Number(kv[1]);
+    if (Number.isInteger(port) && port > 0) return port;
+  }
+  return 0;
+}
+
+/**
+ * The bridge config this process should read: $BOTHOUSE_CONFIG (the bridge's --config), else
+ * <its data dir>/config.toml, the data dir being the one the gate itself would pick
+ * (bridge/brand.go dataDir, bridge/contrib/gate/datadir.py data_dir). The process's own ./config.toml
+ * is deliberately not tried: that is the bridge's rule for the bridge's cwd, not for a plugin's.
+ * @param {NodeJS.ProcessEnv} env
+ * @param {string} home
+ * @returns {string}
+ */
+export function bridgeConfigFile(env = process.env, home = homedir()) {
+  const explicit = String(env.BOTHOUSE_CONFIG ?? '').trim();
+  if (explicit !== '' && explicit !== '~' && !explicit.startsWith('~/')) return explicit;
+  if (explicit !== '') return join(home, explicit.slice(2));
+  return join(dataDirCandidates(env, home)[0], 'config.toml');
+}
+
+/**
+ * The gate port to use, and where it came from (for the log line).
+ * @param {NodeJS.ProcessEnv} env
+ * @param {string} home
+ * @param {(file: string, encoding: string) => string} readFile
+ * @returns {{ port: string, why: string }}
+ */
+export function resolveGatePort(env = process.env, home = homedir(), readFile = readFileSync) {
+  const fromEnv = String(env.GATE_PORT ?? '').trim();
+  if (fromEnv !== '') return { port: fromEnv, why: 'GATE_PORT' };
+  const file = bridgeConfigFile(env, home);
+  let text;
+  try { text = readFile(file, 'utf8'); } catch { return { port: '', why: `没有配置文件 ${file}` }; }
+  const port = gatePortSetting(text);
+  if (port !== 0) return { port: String(port), why: `${file} [gate] port` };
+  return { port: String(DEFAULT_GATE_PORT), why: `${file} 没有 [gate] port，用默认端口` };
+}
 
 export class GateContext {
   /**
-   * @param options - { port?: gate port (default process.env.GATE_PORT), timeoutMs?, fetch?, logger? }.
+   * @param options - { port?: gate port (default: GATE_PORT, else the bridge config's [gate] port),
+   *   timeoutMs?, fetch?, logger? }.
    */
-  constructor({ port = process.env.GATE_PORT, timeoutMs = GATE_CONTEXT_TIMEOUT_MS, fetch: fetchFn = globalThis.fetch, logger } = {}) {
-    this.port = String(port ?? '').trim();
+  constructor({ port, timeoutMs = GATE_CONTEXT_TIMEOUT_MS, fetch: fetchFn = globalThis.fetch, logger } = {}) {
+    const from = port === undefined ? resolveGatePort() : { port: String(port ?? '').trim(), why: 'port 参数' };
+    this.port = String(from.port ?? '').trim();
     this.timeoutMs = timeoutMs;
     this.fetch = fetchFn;
     this.logger = logger;
+    // One line per process (a member each builds its own GateContext): which port the context goes
+    // to and from where, so a missing one is a line in the log instead of a silently missing block.
+    const line = `${this.port}\u0000${from.why}`;
+    if (!announced.has(line)) {
+      announced.add(line);
+      if (this.port !== '') this.logger?.info?.('collab: gate context: port %s（%s）', this.port, from.why);
+      else this.logger?.warn?.('collab: gate context: 没有 gate 端口（%s）；每轮不带 wiki 页和任务板', from.why);
+    }
     /** `${member}\0${room}` -> { session, epoch }: the name of that conversation's context for the gate. */
     this.sent = new Map();
   }

package/collab/hub.mjs

@@ -17,6 +17,8 @@ export class Hub {
     this.members = new Map();
     /** roomId -> Set<memberId> currently working */
     this.thinking = new Map();
+    /** #1020: room id -> member id -> ids of the owner's messages waiting behind that member's running turn. */
+    this.queued = new Map();
     /** id -> optional busy fields published by the team-status reader (#876). */
     this.presence = new Map();
     this.listeners = [];
@@ -27,6 +29,9 @@ export class Hub {
   memberList() { return [...this.members.values()]; }
 
   membersInRoom(roomId) {
+    // #1023: a private chat has the owner and its one agent, whatever that agent's channel list says.
+    const dm = this.store.dmMember?.(roomId);
+    if (dm !== undefined) return this.memberList().filter(m => m.kind === 'human' || m.id === dm);
     const channel = this.store.settingsRoom(roomId);
     return this.memberList().filter(m => !m.rooms?.length || m.rooms.includes(channel));
   }
@@ -45,6 +50,9 @@ export class Hub {
 
   /** Channel selection, inherited by workspaces; only unset channels use the legacy global choice. */
   primaryIn(roomId) {
+    // #1023: in a private chat the one agent answers every owner message, @ or not.
+    const dm = this.store.dmMember?.(roomId);
+    if (dm !== undefined) return this.routableIn(roomId).find(m => m.id === dm);
     const id = this.store.leadId(roomId);
     const member = id === null ? this.selectedPrimaryMember() : this.members.get(id);
     return member && this.routableIn(roomId).some(m => m.id === member.id) ? member : undefined;
@@ -66,6 +74,7 @@ export class Hub {
     if (!this.members.delete(id)) return;
     this.presence.delete(id);
     for (const room of this.thinking.keys()) this.setThinking(room, id, false);
+    for (const room of [...this.queued.keys()]) this.setQueue(room, id, []);
     this.emit({ type: 'members', members: this.memberView() });
   }
 
@@ -76,6 +85,7 @@ export class Hub {
     if (!online) {
       this.presence.delete(id);
       for (const room of this.thinking.keys()) this.setThinking(room, id, false);
+      for (const room of [...this.queued.keys()]) this.setQueue(room, id, []);
     }
     this.emit({ type: 'members', members: this.memberView() });
   }
@@ -114,6 +124,21 @@ export class Hub {
     this.emit({ type: 'thinking', room_id: roomId, members: [...set] });
   }
 
+  /** #1020: replace the queue a member has in a room (ids in queue order; [] clears it). */
+  setQueue(roomId, id, ids) {
+    const room = this.queued.get(roomId) ?? new Map();
+    const before = room.get(id) ?? [];
+    if (before.length === ids.length && before.every((x, i) => x === ids[i])) return;
+    if (ids.length) room.set(id, [...ids]); else room.delete(id);
+    if (room.size) this.queued.set(roomId, room); else this.queued.delete(roomId);
+    this.emit({ type: 'queue', room_id: roomId, queued: this.queueView(roomId) });
+  }
+
+  /** #1020: { member id: [message ids] } waiting in a room. */
+  queueView(roomId) {
+    return Object.fromEntries([...(this.queued.get(roomId) ?? new Map())]);
+  }
+
   memberView() {
     return this.memberList().map(({ id, name, kind, online, model, cli, permissionPreset, persona, nameCustomized, avatar, avatarVersion, source, error, rooms }) => ({
       id, name, kind, ...(rooms ? { rooms } : {}), online: online !== false && !error, ...(error ? { error } : {}), ...(avatar ? { avatar, ...(avatarVersion ? { avatarVersion } : {}) } : {}),
@@ -161,6 +186,7 @@ export class Hub {
       return r;
     });
     if (!result.created) return result;
+    result.message = this.withMemories(result.message);
     for (const next of after) {
       Promise.resolve().then(next).catch((error) => {
         this.logger.warn('collab: post-commit step failed: %s', error?.stack ?? error);
@@ -195,7 +221,7 @@ export class Hub {
       return c;
     });
     if (r === undefined) return undefined;
-    const row = r.message;
+    const row = r.first ? this.withMemories(r.message) : r.message;
     this.emit({ type: 'message', message: publicMessage(row, this.store) });
     if (!r.first) return row;
     for (const next of after) {
@@ -211,6 +237,21 @@ export class Hub {
     return row;
   }
 
+  /**
+   * #1020: attach to a member's reply the memory entries it cited here since its last reply
+   * (memory-sources.mjs). Command answers (from_turn 0), cards and drafts take none.
+   */
+  withMemories(row) {
+    if (!this.memorySources || row?.author_kind !== 'role' || row.card != null || row.draft || row.from_turn === 0) return row;
+    const voter = this.members.get(row.author)?.voter ?? `dsh:${row.author}`;
+    let items;
+    try { items = this.memorySources.take(voter, row.room_id); } catch (error) {
+      this.logger.warn('collab: memory sources failed: %s', error?.message ?? error);
+      return row;
+    }
+    return items.length ? (this.store.setMemories(row.id, items) ?? row) : row;
+  }
+
   /** Edit/delete a row the same author wrote, and tell browsers. */
   edit(id, authorKind, author, text, card) {
     const row = this.store.edit(id, authorKind, author, text, card);

package/collab/later.mjs

@@ -104,6 +104,18 @@ export class Later {
     const curl = `curl -sS -X POST ${quote(url)} -H 'content-type: application/json' -H ${quote(`X-Later-Ticket: ${ticket}`)} -d '{"title":"任务标题","owner":"接活人id（省略=你自己）","reason":"交接说明"}'`;
     return `\n【开工作区】整块活要交出去时，建工作区=这一条，任务和十分钟看门会自动开，不要另调 /tasks（它不认票据）。${local}或等价的接口 POST /collab/api/rooms/${room}/workspaces：\n${curl}\n一步建好工作区、开任务、挂十分钟看门并叫醒接活人；不要再在频道里 @ 同一件活。返回不是 200 就把返回原样告诉用户，不要悄悄自己做。工作区里的接活人是新会话，只看得到交接说明：里面要写清用户原话、参照的现成实现、以哪个分支为底、验收标准。\n`;
   }
+  /**
+   * 一句话拉团队 (user 11-04): how the primary role builds a channel of new roles in one call.
+   * Primary-only like workspaceInstructions (dsh-member.mjs workspaceHint).
+   */
+  teamInstructions(member, room) {
+    const quote = value => "'" + String(value).replaceAll("'", "'\\''") + "'";
+    const ticket = this.ticket(member, room);
+    const json = '{"channel":"小团队","model":"模型id（用户没说就省略=DSH默认模型）","members":[{"name":"写手","persona":"你是写手，负责写和改博客文章。"},{"name":"程序员","persona":"你是程序员，负责写代码和审代码。"}]}';
+    const local = this.origin ? `本机命令（改 JSON 里的内容）：\n${quote(process.execPath)} ${quote(fileURLToPath(import.meta.url))} team ${quote(this.origin)} ${quote(ticket)} ${quote(json)}\n` : '';
+    const url = `${this.origin ?? 'http://<本机 DSH 地址>'}/collab/api/rooms/${room}/team`;
+    return `\n【建团队】用户要你建几个角色、拉个群/频道时，一条就建好：新频道、每个角色（名字、人设、模型），你是新频道的主角色。${local}或 POST ${url}（头 X-Later-Ticket: ${ticket}，JSON 同上）。名字不带空格和 @；人设一两句写清分工；用户说了模型就填 model（如 deepseek-v4.1-flash），没说就省略。返回不是 200 就把返回原样告诉用户。建好后告诉用户频道名、每个角色和模型，问要不要丢个题目试跑。\n`;
+  }
   tick() {
     for (const row of this.db.prepare('SELECT * FROM member_later WHERE announced = 0').all()) {
       this.hub.post(row.room_id, { authorKind: 'system', author: 'system', name: '回查登记',
@@ -134,6 +146,15 @@ if (process.argv[1] === fileURLToPath(import.meta.url) && process.argv[2] === 'w
   const body = await res.text();
   if (!res.ok) { console.error(`workspace: ${res.status} ${body}`); process.exit(1); }
   console.log(body);
+} else if (process.argv[1] === fileURLToPath(import.meta.url) && process.argv[2] === 'team') {
+  const [origin, ticket, spec] = process.argv.slice(3);
+  const room = ticketClaims(ticket)?.r;
+  if (!origin || !Number.isSafeInteger(room) || !spec) { console.error('usage: later.mjs team <origin> <ticket> \'{"channel":"…","model":"…","members":[{"name":"…","persona":"…"}]}\''); process.exit(2); }
+  const res = await fetch(new URL(`/collab/api/rooms/${room}/team`, origin), { method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-later-ticket': ticket }, body: spec });
+  const body = await res.text();
+  if (!res.ok) { console.error(`team: ${res.status} ${body}`); process.exit(1); }
+  console.log(body);
 } else if (process.argv[1] === fileURLToPath(import.meta.url)) {
   const [origin, ticket, delay, title, todo] = process.argv.slice(2);
   const room = ticketClaims(ticket)?.r;

package/collab/memory-sources.mjs

@@ -0,0 +1,159 @@
+// #1020 回复的记忆来源：which pushed memory entries a reply used, shown as a badge under it.
+// The gate pushes entries tagged [#编号] before each turn (bridge/contrib/gate/ctxsvc.py exp_tag) and the
+// agent reports the ones it used with memvote.py (+编号), which appends a by="self" line to votes.jsonl
+// ({t, voter: CC_PROJECT, id: "页#指纹", vote, by, key: CC_SESSION_KEY, agent}). This module tails that file
+// and hands each new reply of a member the entries it cited in that room since its previous reply.
+// Nothing is guessed: no citation, no badge (a member that never runs memvote gets none).
+//
+// Where the file is: MEMVOTE_DIR (memvote.py's own override), else <gate data dir>/gate, where bothouse
+// installs the gate (bridge/core/gate_proc.go). The data dir is found the way the gate itself finds it
+// (bridge/contrib/gate/datadir.py data_dir, Go brand.go dataDir): BOTHOUSE_DATA_DIR, GATE_SETUP_DIR,
+// CC_DATA_DIR, else ~/.bothouse (~/.cc-connect only while that legacy layout is the one that exists).
+// It must not depend on BOTHOUSE_DATA_DIR alone: a `dsh web` started by a script that reuses an old
+// environment has only CC_DATA_DIR, and the badge used to vanish there silently.
+// Page paths are relative to GATE_WIKI (~/wiki) or start with ~/ for a role wiki (memvote.full_id).
+import { closeSync, existsSync, openSync, readSync, readFileSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const MAX_ITEMS = 12; // a badge lists at most this many entries
+const TITLE_CHARS = 120;
+
+/** `~/x` in a config value, as expanduser does for the gate (datadir.guard). */
+const expand = (value, home) => String(value ?? '').trim().replace(/^~(?=\/|$)/, home);
+
+/**
+ * The bothouse data dirs this machine may have, in the order the gate itself picks one
+ * (bridge/contrib/gate/datadir.py data_dir; Go brand.go dataDir for the last one).
+ * @param {NodeJS.ProcessEnv} env
+ * @param {string} home
+ * @returns {string[]}
+ */
+export function dataDirCandidates(env = process.env, home = homedir()) {
+  const dirs = [];
+  for (const key of ['BOTHOUSE_DATA_DIR', 'GATE_SETUP_DIR', 'CC_DATA_DIR']) {
+    const dir = expand(env[key], home);
+    if (dir !== '') dirs.push(dir);
+  }
+  // ~/.cc-connect is the legacy layout, used only while ~/.bothouse does not exist and it does.
+  const preferred = join(home, '.bothouse');
+  const legacy = join(home, '.cc-connect');
+  dirs.push(!existsSync(preferred) && existsSync(legacy) ? legacy : preferred);
+  return dirs;
+}
+
+/**
+ * memvote.py's votes.jsonl: MEMVOTE_DIR when set (memvote's own override names the one file it writes),
+ * else <the gate's data dir>/gate. Same precedence as the gate reading its own directory, so a `dsh web`
+ * that inherited only CC_DATA_DIR reads the file the running gate actually appends to.
+ * @param {NodeJS.ProcessEnv} env
+ * @param {string} home
+ * @returns {string}
+ */
+export function defaultVotesFile(env = process.env, home = homedir()) {
+  const dir = expand(env.MEMVOTE_DIR, home);
+  if (dir !== '') return join(dir, 'votes.jsonl');
+  return join(dataDirCandidates(env, home)[0], 'gate', 'votes.jsonl');
+}
+
+/** Room id a cite's session key names: bridge cloud-web "…room-<id>…", or the DSH gate key "dsh:<member>:<room>". */
+export function keyRoom(key) {
+  const s = String(key ?? '');
+  const m = /(?:^|:)room-(\d+)(?::|$)/.exec(s) ?? /^dsh:[^:]+:(\d+)$/.exec(s);
+  return m ? Number(m[1]) : undefined;
+}
+
+export class MemorySources {
+  /** @param options - { file?: votes.jsonl path, wiki?, home?, logger? } */
+  constructor({ file = defaultVotesFile(), wiki = process.env.GATE_WIKI || join(homedir(), 'wiki'), home = homedir(), logger } = {}) {
+    this.file = file;
+    this.wiki = String(wiki).replace(/^~(?=\/|$)/, home);
+    this.home = home;
+    this.logger = logger;
+    // Say which file the badge reads, so a silent one is explained in the log instead of vanishing.
+    if (!this.file) this.logger?.warn?.('collab: memory sources: no votes.jsonl path (set BOTHOUSE_DATA_DIR, GATE_SETUP_DIR or CC_DATA_DIR, or MEMVOTE_DIR); replies carry no memory sources');
+    else if (existsSync(this.file)) this.logger?.info?.('collab: memory sources: reading %s', this.file);
+    else this.logger?.warn?.('collab: memory sources: %s does not exist yet (wrong data dir, or the gate has not recorded a cite); replies carry no memory sources until it appears', this.file);
+    // Only citations made after this process started belong to its replies.
+    this.offset = this.size();
+    this.rest = '';
+    /** `${voter}\0${room}` -> ordered unique entry ids cited and not yet shown. */
+    this.pending = new Map();
+    this.titles = new Map();
+  }
+
+  size() {
+    if (!this.file) return 0;
+    try { return statSync(this.file).size; } catch { return 0; }
+  }
+
+  /** Read the lines appended since the last call. */
+  poll() {
+    if (!this.file) return;
+    const size = this.size();
+    if (size < this.offset) { this.offset = 0; this.rest = ''; } // rotated or truncated
+    if (size === this.offset) return;
+    let fd;
+    try {
+      fd = openSync(this.file, 'r');
+      const buf = Buffer.alloc(size - this.offset);
+      readSync(fd, buf, 0, buf.length, this.offset);
+      this.offset = size;
+      const lines = (this.rest + buf.toString('utf8')).split('\n');
+      this.rest = lines.pop() ?? '';
+      for (const line of lines) this.take1(line);
+    } catch (error) {
+      this.logger?.warn?.('collab: memory sources: %s', error?.message ?? error);
+    } finally {
+      if (fd !== undefined) closeSync(fd);
+    }
+  }
+
+  take1(line) {
+    let r;
+    try { r = JSON.parse(line); } catch { return; }
+    // by="self" vote=1: the agent says it used this entry (memvote.py "+编号"); "-" (entry wrong) and "x" are not sources.
+    if (r?.by !== 'self' || r.vote !== 1 || typeof r.id !== 'string' || !r.id.includes('#')) return;
+    const room = keyRoom(r.key);
+    if (room === undefined || !r.voter) return;
+    const k = `${r.voter}\u0000${room}`;
+    const list = this.pending.get(k) ?? [];
+    if (!list.includes(r.id)) list.push(r.id);
+    this.pending.set(k, list);
+  }
+
+  /**
+   * The entries `voter` cited in `room` since its previous reply there, as [{ id, ref, page, title }]
+   * (ref = the short 编号 shown in the push), and forget them. [] when it cited none.
+   */
+  take(voter, room) {
+    this.poll();
+    const k = `${voter}\u0000${room}`;
+    const ids = this.pending.get(k);
+    if (!ids?.length) return [];
+    this.pending.delete(k);
+    return ids.slice(0, MAX_ITEMS).map(id => {
+      const [page, ref] = [id.slice(0, id.lastIndexOf('#')), id.slice(id.lastIndexOf('#') + 1)];
+      return { id, ref, page, title: this.title(page, ref) };
+    });
+  }
+
+  /** The wiki line an entry id points at (memvote.full_id: sha1 of the stripped line, first 10 hex), trimmed. */
+  title(page, ref) {
+    const key = `${page}#${ref}`;
+    if (this.titles.has(key)) return this.titles.get(key);
+    let out = '';
+    const path = page.startsWith('~/') ? join(this.home, page.slice(2)) : join(this.wiki, page);
+    try {
+      for (const raw of readFileSync(path, 'utf8').split('\n')) {
+        if (createHash('sha1').update(raw.trim()).digest('hex').slice(0, 10) !== ref) continue;
+        out = raw.trim().replace(/^[-*]\s+/, '').replace(/\s+/g, ' ');
+        break;
+      }
+    } catch { /* page moved or gone: the badge still shows its path */ }
+    if (out.length > TITLE_CHARS) out = out.slice(0, TITLE_CHARS - 1) + '…';
+    this.titles.set(key, out);
+    return out;
+  }
+}