bothouse-dsh 0.1.57 → 0.1.59

package/collab/dsh-member.mjs

@@ -10,7 +10,7 @@ import { randomUUID } from 'node:crypto';
 import { readFileSync, realpathSync, statSync } from 'node:fs';
 import { basename, isAbsolute, relative, sep } from 'node:path';
 import { exitTarget } from './team-exit.mjs';
-import { DEFAULT_DISPATCH_MODE, MAX_TEXT } from './store.mjs';
+import { DEFAULT_DISPATCH_MODE, MAX_TEXT, messageAttachments } from './store.mjs';
 import { ChannelApprovals, DEFAULT_ACTIONS } from './approvals.mjs';
 import { DEFAULT_PERMISSION_PRESET, presetDecision } from './cli-member.mjs';
 import { GateContext } from './gate-context.mjs';
@@ -61,7 +61,7 @@ export function memberStatus(hub, tasks = hub?.tasks, roomId) {
 import { mentions, nameCalled, split } from './mentions.mjs';
 import { quotePrefix } from './store.mjs';
 import { progressCardOf } from './cloudweb.mjs';
-import { attachmentBlocks, namedAttachmentBlocks, nativeAttachmentBlocks, undeliveredReasonZh } from './attachments.mjs';
+import { attachmentBlocks, namedAttachmentBlocks, nativeAttachmentBlocks, oversizedNote, undeliveredReasonZh } from './attachments.mjs';
 
 const CONTEXT_LIMIT = 50;
 const CLOSE_TIMEOUT_MS = 5_000;
@@ -360,10 +360,31 @@ export class TurnProgress {
   }
 }
 
+/** Text with every @-mention taken out, trimmed: what a command word is matched against. */
+function commandOf(text, members) {
+  return split(text, members).filter(([, id]) => id === null).map(([seg]) => seg).join('').trim();
+}
+
 /** Whether text, with @-mentions removed, is the /new command (bridge core cmdNew). */
 export function isNewCommand(text, members) {
-  const rest = split(text, members).filter(([, id]) => id === null).map(([seg]) => seg).join('').trim();
-  return /^\/new(\s|$)/.test(rest);
+  return /^\/new(\s|$)/.test(commandOf(text, members));
+}
+
+/**
+ * The stop command a person typed in a channel: 'one' for `/stop`, 'all' for
+ * `/stop all`, undefined for anything else. The @ that addressed it is already
+ * gone by the time the message reaches this planner (the bridge forwards a
+ * channel command stripped, mentions.mjs forMember), so the members it reaches
+ * are the planner's own targets — the same rule /new follows.
+ *
+ * Not the bridge's /stop all (bridge/core/stop_all.go, every bot in the channel
+ * stops its own bridge session): this one only ends DSH members' turns here.
+ */
+export function stopCommand(text, members) {
+  const rest = commandOf(text, members);
+  if (/^\/stop\s+all$/i.test(rest)) return 'all';
+  if (/^\/stop$/i.test(rest)) return 'one';
+  return undefined;
 }
 
 export class DshMembers {
@@ -387,8 +408,10 @@ export class DshMembers {
     this.openTurns = new Map();
     /** Agents whose request hook was installed after they were loaded by someone else. */
     this.hooked = new WeakSet();
-    /** JSON([memberId, cwd, roomId]) -> { memberId, cli, agent } live local CLI agents (members with a `cli` field). */
+    /** JSON([memberId, cwd, roomId]) -> { memberId, roomId, cli, agent } live local CLI agents. */
     this.cliAgents = new Map();
+    // Releasing a workspace retains its bindings for rework, but needs no resident CLI.
+    this.store.onWorkspaceRelease(roomId => this.dropRoomCli(roomId));
     /** #557: permission cards of channel-started turns, shared with cloud-web bots. */
     this.approvals = ChannelApprovals.of(hub);
     /** Session ids whose owner chose 允许所有: later asks in that Session are allowed without a card (CLI members: `cli:<ACP session id>`). */
@@ -410,6 +433,14 @@ export class DshMembers {
     if (this.config.get(m.id)?.cli !== m.cli) this.dropCli(m.id);
     this.config.set(m.id, m);
     this.publish(m);
+    // Hub owns scope rules, including workspace inheritance and the member's private chat.
+    const removed = (id, roomId) => id === m.id && !this.hub.membersInRoom(roomId).some(member => member.id === m.id);
+    this.cancelCliStarts(removed);
+    for (const [key, entry] of this.cliAgents) {
+      if (!removed(entry.memberId, entry.roomId)) continue;
+      entry.agent.close();
+      this.cliAgents.delete(key);
+    }
   }
 
   /** Stop routing to a member. Pending jobs for it fail when they run; history keeps its name. */
@@ -461,10 +492,22 @@ export class DshMembers {
    * @returns { stopped, running } member ids whose turn was cancelled / left running.
    */
   recall(triggerId) {
+    return this.cancelJobs(job => job.trigger_id === triggerId);
+  }
+
+  /**
+   * #148 / #299: end every open job `match` accepts. A queued one is closed, one
+   * still waiting in the member's inbox is taken back, and a turn already running
+   * is cancelled the way DSH's stop button does (keepInbox, so the member's later
+   * inputs still run). Jobs it cannot reach (a CLI member's ask) keep running.
+   * The one cancel path behind both "the owner withdrew the message" and "/stop".
+   * @returns { stopped, running } member ids whose turn was cancelled / left running.
+   */
+  cancelJobs(match) {
     const stopped = [];
     const running = [];
     for (const job of this.store.openJobs()) {
-      if (job.trigger_id !== triggerId) continue;
+      if (!match(job)) 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;
@@ -481,6 +524,29 @@ export class DshMembers {
     return { stopped, running };
   }
 
+  /**
+   * #299: `/stop` / `/stop all` typed in the channel. Cancels member turns in this
+   * room on the sender's own thread and posts one receipt saying who stopped and
+   * who is still running; it never queues, so it cannot arrive after the turn it
+   * is meant to end.
+   * @returns { stopped, still_running } member names, as the DELETE route's shape.
+   */
+  stopHere(msg, memberIds) {
+    const { stopped, running } = this.cancelJobs(job => job.room_id === msg.room_id && memberIds.includes(job.member_id));
+    const name = id => this.config.get(id)?.name ?? id;
+    const still_running = [...new Set(running.map(name))];
+    const stoppedNames = [...new Set(stopped.map(name))];
+    const text = stoppedNames.length === 0
+      ? `⏹ 没有在跑的活。`
+      : `⏹ 已停下 ${stoppedNames.join('、')} 这一轮。` + (still_running.length ? `\n仍在跑：${still_running.join('、')}` : '');
+    this.hub.post(msg.room_id, {
+      authorKind: 'system', author: 'system', name: 'system',
+      clientKey: `dsh-stop-${msg.id}-${stoppedNames.length ? 'stopped' : 'idle'}`,
+      text,
+    });
+    return { stopped: stoppedNames, still_running };
+  }
+
   /**
    * #557: root approval/request answerer (installed prepended by the plugin).
    * The Session is held out of the DSH conversation list, so its approval
@@ -536,6 +602,20 @@ export class DshMembers {
     const visible = new Set(this.hub.routableIn(msg.room_id).map(m => m.id));
     const targets = [...this.config.keys()].filter(id => !this.hub.quota?.cooling(id) && visible.has(id) && id !== msg.author && !answered.has(id) && (!target || target === id)
       && (only !== null ? only.has(id) : hit.has(id) || (leadTarget && id === leadID) || (msg.author_kind === 'role' && nameCalled(msg.text, this.config.get(id).name, [...this.config.keys()].filter(o => o !== id).map(o => this.config.get(o).name)))));
+    // #299: /stop and /stop all end the member turns running here, now. Both used to fall through to
+    // addJob+enqueue below, which serializes per (member, room) — so the stop only ran once the turn it
+    // was meant to end had already finished. They take the same out-of-band cancel path as recall, with
+    // no placeholder job and no queue slot, so the receipt cannot arrive late.
+    // Not the bridge's /stop all (stop_all.go): that stops every bot's bridge session in the channel.
+    const stop = msg.author_kind === 'user' ? stopCommand(msg.text, this.hub.routableIn(msg.room_id)) : undefined;
+    // `/stop all` is typed bare, so its targets are none; it stops every DSH member visible here.
+    // A single `/stop` only stops the members the message reaches, the same targets /new uses.
+    if (stop !== undefined) {
+      const ids = stop === 'all' ? [...this.config.keys()].filter(id => visible.has(id)) : targets;
+      // Nobody is here to stop: keep quiet, like any other message that reaches no member.
+      if (ids.length === 0) return undefined;
+      return () => { this.stopHere(msg, ids); };
+    }
     if (targets.length === 0) return undefined;
     // /new goes to the members the message reaches, as on Discord where only the addressed bot handles it.
     if (msg.author_kind === 'user' && isNewCommand(msg.text, this.hub.routableIn(msg.room_id))) {
@@ -635,9 +715,11 @@ export class DshMembers {
     // never advances the cursor, so the same image would block the room.
     const { parts: media, dropped: refused } = await nativeAttachmentBlocks(this.rt.ctx.attachments, namedAttachmentBlocks(this.rt.files, unseen));
     const dropped = refused.map(d => `\n\n[${d.name}: 附件未送达（${undeliveredReasonZh(d)}）]`).join('');
+    // #197: a file over the bot connection cap is not inlined; the member reads it from disk.
+    const oversized = oversizedNote(this.rt.files?.oversized(unseen.flatMap(messageAttachments)));
     const wiki = await this.turnContext(member, room, agent.session.id, unseen);
     if (this.closed) return;
-    const input = this.rt.createUserMessage({ content: [{ type: 'text', text: promptText(room, member, unseen, withBlock(memberStatus(this.hub, undefined, room.id), wiki.block), this.store.dispatchMode(room.id), this.store) + dropped + (this.rt.later?.instructions(member.id, room.id) ?? '') + workspaceHint(this.hub, this.rt.later, member.id, room.id) }, ...media], source: { kind: 'user' } });
+    const input = this.rt.createUserMessage({ content: [{ type: 'text', text: promptText(room, member, unseen, withBlock(memberStatus(this.hub, undefined, room.id), wiki.block), this.store.dispatchMode(room.id), this.store) + dropped + (oversized ? `\n${oversized}` : '') + (this.rt.later?.instructions(member.id, room.id) ?? '') + workspaceHint(this.hub, this.rt.later, member.id, room.id) }, ...media], source: { kind: 'user' } });
     const seqBefore = agent.session.seq;
     if (!this.store.markSent(jobId, agent.session.id, seqBefore, input.id)) return;
     wiki.commit();
@@ -678,7 +760,7 @@ 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, roomId: room.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);
@@ -757,7 +839,12 @@ export class DshMembers {
         }
       };
       const prompt = promptText(room, member, unseen, withBlock(memberStatus(this.hub, undefined, room.id), wiki.block), this.store.dispatchMode(room.id), this.store) + (this.rt.later?.instructions(member.id, room.id) ?? '') + workspaceHint(this.hub, this.rt.later, member.id, room.id);
-      const text = (await entry.agent.ask(prompt, String(room.id), onText, onTool, { resumeId, onSession, onPermission, cliConfig: member.cliConfig, cliConfigManaged: member.cliConfigManaged, attachments: attachmentBlocks(this.rt.files, unseen) }))?.trim();
+      // #197 合 develop: 这里不能再提前 wiki.commit()。develop 的 af2d1afe 把「记忆已送达」
+      // 挪进 onSession 回调，因为 cli-member.mjs 先建会话、再应用 CLI 配置，才触发 onSession；
+      // 这两步失败时提前标记会让重试跳过 MEMORY.md。记忆目录是否真的送达由 onSession 里的调用决定。
+      // #197: a file over the bot connection cap is not inlined; the CLI reads it from disk.
+      const bigNote = oversizedNote(this.rt.files?.oversized(unseen.flatMap(messageAttachments)));
+      const text = (await entry.agent.ask(`${prompt}${bigNote ? `\n${bigNote}` : ''}`, String(room.id), onText, onTool, { resumeId, onSession, onPermission, cliConfig: member.cliConfig, cliConfigManaged: member.cliConfigManaged, attachments: attachmentBlocks(this.rt.files, unseen) }))?.trim();
       if (this.closed) return;
       this.hub.quota?.observe(member.id, room.id, { error: text });
       if (!text) { this.fail(job.id, `${member.name} 这一轮没有给出回复（${member.cli} 没有输出文字）`); return; }
@@ -803,13 +890,20 @@ export class DshMembers {
   resetRoom(roomId) {
     this.gateContext.resetRoom(roomId);
     this.memoryIndex.resetRoom(roomId);
-    for (const { agent } of this.cliAgents.values()) {
-      agent.sessions?.delete(String(roomId));
-      agent.saved?.delete(String(roomId));
+    this.dropRoomCli(roomId);
+  }
+
+  dropRoomCli(roomId) {
+    this.cancelCliStarts((_memberId, id) => id === roomId);
+    for (const [key, entry] of this.cliAgents) {
+      if (entry.roomId !== roomId) continue;
+      entry.agent.close();
+      this.cliAgents.delete(key);
     }
   }
 
   dropCli(id) {
+    this.cancelCliStarts(memberId => memberId === id);
     for (const [key, entry] of this.cliAgents) {
       if (entry.memberId !== id) continue;
       entry.agent.close();
@@ -817,6 +911,14 @@ export class DshMembers {
     }
   }
 
+  /** Close queued CLI jobs too: run/markSent must not revive a process after cleanup. */
+  cancelCliStarts(matches) {
+    for (const job of this.store.openJobs()) {
+      if (job.state !== 'pending' || this.config.get(job.member_id)?.cli === undefined || !matches(job.member_id, job.room_id)) continue;
+      this.store.finishJob(job.id, 'interrupted');
+    }
+  }
+
   /** Watch for the consuming turn, admit the input, and post the outcome. */
   async admitAndSettle(job, member, agent, input, seqBefore) {
     const sessionId = agent.session.id;

package/collab/instance-lock.mjs

@@ -1,8 +1,11 @@
-import { mkdirSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { accessSync, chmodSync, constants, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 
 export const LOCK_FILE = 'collab.lock';
+// #216: the holder's identity, so the DSH that is refused can say who holds the lock
+// instead of calling a busy service "not configured".
+export const OWNER_FILE = 'collab.owner.json';
 
 /**
  * #1019: one DSH process per collab data directory. Two hosts on the same collab.sqlite3 both run
@@ -44,3 +47,133 @@ export function lockBusyMessage(path) {
   return `conest-collab: 频道插件没有启动——这台电脑上已经有另一个 DSH 在用同一份频道数据（${path}）。`
     + '两个同时跑会让提醒、派活和消息各处理两遍。请用已经打开的那个 DSH；要换就先关掉它再打开。';
 }
+
+/**
+ * #216: the instance that holds the lock records who it is next to it, so the DSH that is
+ * refused can name the holder instead of telling the user to go and configure collab.yml.
+ * Written after the lock is held (so the record always describes the current holder) and
+ * removed on release; a record left behind by a crash is harmless because the reader also
+ * checks the lock itself.
+ * @returns the record written.
+ */
+export function writeLockOwner(path, info) {
+  const file = join(dirname(path), OWNER_FILE);
+  mkdirSync(dirname(file), { recursive: true });
+  const record = { ...info, lock: path, writtenAt: info.writtenAt ?? Date.now() };
+  // 来源：沿用 pairing.mjs saveJSON 的私有凭据权限；收紧旧诊断文件后再写连接口令。
+  try { chmodSync(file, 0o600); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  writeFileSync(file, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+  return record;
+}
+
+/**
+ * #216: the holder record for the data directory of `path`.
+ * @returns the record, or undefined when no holder wrote one (an older install, or a
+ * crashed holder whose lock the kernel already dropped).
+ */
+export function readLockOwner(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(join(dirname(path), OWNER_FILE), 'utf8'));
+    return parsed !== null && typeof parsed === 'object' ? parsed : undefined;
+  } catch {
+    // Missing or half-written: the caller falls back to the plain refusal.
+    return undefined;
+  }
+}
+
+/** #216: remove `pid`'s record; another live holder's record is left alone. */
+export function clearLockOwner(path, pid = process.pid) {
+  const record = readLockOwner(path);
+  if (record !== undefined && record.pid !== undefined && record.pid !== pid) return;
+  try { unlinkSync(join(dirname(path), OWNER_FILE)); } catch { /* already gone */ }
+}
+
+/**
+ * #216/#227: take the lock and publish who holds it, as one step.
+ *
+ * Writing the record can fail (a directory where the file should be, a full or read-only data
+ * directory). The lock must not survive that failure: the plugin throws, the DSH keeps running
+ * with the error logged, and a lock nobody will ever release welds the data directory shut for
+ * every later DSH — the user sees "another DSH is using this" with no DSH to quit. So a failed
+ * write releases the lock before the error travels on.
+ *
+ * @returns the held lock with its record written.
+ * @throws the write error, after releasing the lock.
+ */
+export function acquireLockWithOwner(path, info) {
+  const lock = InstanceLock.acquire(path);
+  if (lock === undefined) return undefined;
+  try {
+    writeLockOwner(path, info);
+  } catch (error) {
+    lock.release();
+    throw error;
+  }
+  return lock;
+}
+
+/** #216: is `pid` a live process on this machine? EPERM means it exists but is not ours. */
+function alive(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (error) { return error?.code === 'EPERM'; }
+}
+
+/**
+ * #227: does anyone hold the lock at `path`? Answered by reading it, never by taking it.
+ *
+ * The probe used to be `InstanceLock.acquire` + release, so it held the exclusive lock for the
+ * instant between the two: a page poll landing in that instant made a DSH starting at the same
+ * moment refuse to start (实测约 95 us/次，另一进程 120 次启动被拒 0 次但这是运气), and on a free
+ * directory it created the lock file. A read-only connection takes no lock and creates no file:
+ * a holder's `BEGIN EXCLUSIVE` makes the read fail at once with SQLITE_BUSY — the same signal
+ * without the contention (实测约 32 us/次).
+ *
+ * @returns 'held' when someone holds the lock, 'free' when nobody does, 'unknown' when the file
+ * cannot be read for a reason other than "locked" (permissions, I/O).
+ */
+function probeLock(path) {
+  let db;
+  try {
+    db = new DatabaseSync(path, { readOnly: true });
+    // 来源：沿用 InstanceLock.acquire 的 0 —— 探测不能等，等就等于页面轮询把状态请求拖住。
+    db.exec('PRAGMA busy_timeout = 0;');
+    db.prepare('SELECT count(*) FROM sqlite_master').get();
+    return 'free';
+  } catch (error) {
+    // 来源：SQLite 结果码——5 BUSY / 6 LOCKED 是别人的排他事务。
+    if (error?.errcode === 5 || error?.errcode === 6 || /\blocked\b|\bbusy\b/i.test(String(error?.message))) return 'held';
+    // 14 CANTOPEN 有歧义：文件不在（没人持锁）和数据目录不可读（读不出状态）都会报它。
+    // 来源：实测——目录 000 时 existsSync 也回 false，只有 access 的 EACCES/ENOENT 能分开。
+    try { accessSync(path, constants.R_OK); } catch (denied) { return denied?.code === 'ENOENT' ? 'free' : 'unknown'; }
+    return 'unknown';
+  } finally {
+    try { db?.close(); } catch { /* nothing to close */ }
+  }
+}
+
+/**
+ * #216: what a DSH that lost the lock tells its own page about that lock.
+ * - the lock is free (the holder quit): `free`, so the page asks for a restart instead of
+ *   repeating a holder that already let go;
+ * - the lock is held and a live holder recorded itself: who holds it;
+ * - the lock is held, or cannot be read, without a trustworthy record: busy, holder unknown —
+ *   the page must still not call it "not configured".
+ *
+ * The record alone never decides. Only `alive(pid)` plus a held lock makes it the holder: a dead
+ * pid's record outlives its holder, and a crash between `release` and `clearLockOwner` leaves a
+ * record naming a process that holds nothing (#227 2026-11-06 19:40，notes/utils/227-lockprobe/e.mjs).
+ */
+export function lockStatus(path) {
+  const record = readLockOwner(path);
+  // #216: the data directory and the lock path travel with every answer, so a page told
+  // "busy, holder unknown" can still say which directory to look at and which file to check
+  // (`lsof <lock>`) — and does not have to rebuild a path itself, which breaks on Windows.
+  const where = { dataDir: dirname(path), lock: path };
+  if (probeLock(path) === 'free') return { busy: false, free: true, ...where };
+  // #227: still held (or unreadable) — name the holder only when the record and the lock agree.
+  if (record !== undefined && alive(record.pid)) {
+    const { local, ...owner } = record;
+    return { busy: true, owner, ...where };
+  }
+  return { busy: true, owner: null, ...where };
+}

package/collab/local-host.mjs

@@ -0,0 +1,106 @@
+// #216: later DSH windows use the existing channel host; only that host opens the store.
+import { request as httpRequest } from 'node:http';
+import { randomUUID } from 'node:crypto';
+import { readLockOwner, lockStatus } from './instance-lock.mjs';
+import { isLoopback } from './pairing.mjs';
+
+/** Private discovery material, kept beside the lock and omitted from the diagnostic API. */
+export function localConnection(webServer) {
+  const url = new URL(webServer.getOrigin());
+  if (url.protocol !== 'http:' || !isLoopback(url.hostname.replace(/^\[|\]$/g, ''))) return undefined;
+  return { origin: url.origin, token: randomUUID() };
+}
+
+/** A forwarder proves it can read the holder's private discovery file. */
+export function isLocalOwner(req, connection) {
+  return connection !== undefined && isLoopback(req.socket.remoteAddress)
+    && req.headers['x-collab-local'] === connection.token;
+}
+
+/** Same-origin HTTP/SSE bridge, using pairing.mjs remoteProxyRoute's streaming lifecycle. */
+export function forwardLocal(req, res, lockPath, reject) {
+  const denied = reject(req);
+  if (denied !== undefined) return reply(res, denied, { error: '请先登录本页 DSH' });
+  const status = lockStatus(lockPath);
+  const record = readLockOwner(lockPath);
+  const connection = status.busy && status.owner?.pid !== undefined && status.owner.pid === record?.pid ? record?.local : undefined;
+  if (connection === undefined) return reply(res, 404, { error: '频道宿主无法自动连接，请查看占用提示' });
+  let url;
+  try {
+    url = new URL(connection.origin);
+    if (url.protocol !== 'http:' || !isLoopback(url.hostname.replace(/^\[|\]$/g, '')) || typeof connection.token !== 'string') throw Error('invalid local host');
+  } catch {
+    return reply(res, 404, { error: '频道宿主没有留下可用的本机连接信息' });
+  }
+  const headers = { 'x-collab-local': connection.token };
+  // 来源：沿用 pairing.mjs PASS_REQUEST; neither host's browser credentials cross this bridge.
+  for (const h of ['accept', 'content-type', 'content-length', 'last-event-id', 'range', 'if-none-match', 'if-modified-since']) {
+    if (req.headers[h] !== undefined) headers[h] = req.headers[h];
+  }
+  return new Promise(resolve => {
+    const up = httpRequest(url, { path: req.url, method: req.method, headers }, incoming => {
+      const out = {};
+      // 来源：沿用 pairing.mjs PASS_RESPONSE; no upstream cookie reaches the browser.
+      for (const h of ['content-type', 'cache-control', 'etag', 'last-modified', 'content-disposition', 'content-range', 'accept-ranges', 'location']) {
+        if (incoming.headers[h] !== undefined) out[h] = incoming.headers[h];
+      }
+      res.writeHead(incoming.statusCode, out);
+      res.flushHeaders?.();
+      incoming.pipe(res);
+      incoming.on('end', resolve);
+      incoming.on('error', () => { res.destroy(); resolve(); });
+    });
+    up.on('error', () => {
+      if (!res.headersSent) reply(res, 404, { error: '频道宿主已断开，请查看占用提示' });
+      else res.destroy();
+      resolve();
+    });
+    req.on('aborted', () => up.destroy());
+    req.on('error', () => up.destroy());
+    res.on('close', () => { if (!res.writableEnded) up.destroy(); });
+    req.pipe(up);
+  });
+}
+
+function reply(res, status, value) {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+  res.end(JSON.stringify(value));
+}
+
+/** #227: where a later DSH reports which process holds the channel data. */
+export const BUSY_PATH = '/collab/api/lock';
+
+/**
+ * #597 G26: a later ticket only opens workspaces (and later). Sent anywhere else, say where to go
+ * instead of a bare 401, so a member does not give up; the route's own auth is unchanged.
+ */
+export const TICKET_WRONG_ROUTE = '这个接口不认 X-Later-Ticket 票据。建工作区请用 POST /collab/api/rooms/{id}/workspaces（同一个票据头，JSON: title, owner, reason），任务和十分钟看门会自动开，不用再调 /tasks。';
+
+/** The 401/403 split every scoped route uses when the caller is not the owner. */
+export function refuse(req, res) {
+  if (req.headers?.['x-later-ticket'] !== undefined) return reply(res, 403, { error: TICKET_WRONG_ROUTE });
+  return reply(res, 401, { error: 'unauthorized' });
+}
+
+/**
+ * #227: the two routes a second DSH serves when another process holds the channel data.
+ * It is a client of that host, never a second writer, so it publishes the holder's status and
+ * forwards the channel API instead of opening the store.
+ *
+ * Extracted from `apply` so this branch can be tested without loading the plugin (审稿 F2:
+ * `plugin.mjs` needs the DSH runtime to import, and this branch had no unit test at all).
+ *
+ * @param ctx - the plugin context: `webServer.register`, `effect`, `connection.requestRejection`.
+ * @param lockPath - the lock file the holder took; both routes answer from it.
+ */
+export function mountSharedHost(ctx, lockPath) {
+  ctx.effect(() => ctx.webServer.register({ kind: 'exact', path: BUSY_PATH,
+    handler: (req, res) => {
+      if (ctx.connection.requestRejection(req) !== undefined) return refuse(req, res);
+      return reply(res, 200, lockStatus(lockPath));
+    },
+  }), 'conest-collab: holder status');
+  ctx.effect(() => ctx.webServer.register({ kind: 'prefix', path: '/collab',
+    handler: (req, res) => forwardLocal(req, res, lockPath, req => ctx.connection.requestRejection(req)),
+  }), 'conest-collab: shared local host');
+}