@tritard/waterbrother 0.16.21 → 0.16.23

package/README.md

@@ -261,6 +261,14 @@ Rollout order:
 3. approvals over messaging
 4. only then group DM collaboration
 
+Shared project foundation is now live:
+- enable it with `waterbrother project share`
+- inspect it with `waterbrother room status`
+- control conversation vs execution with `waterbrother room mode chat|plan|execute`
+- claim or release the shared operator lock with `waterbrother room claim` and `waterbrother room release`
+- shared project metadata lives in `.waterbrother/shared.json`
+- human collaboration notes live in `ROUNDTABLE.md`
+
 Current Telegram behavior:
 - if the TUI is open, Telegram prompts are injected into the live TUI session and the work is visible in the terminal
 - if no live TUI session is attached, Telegram falls back to a remote run with `approval=never`
@@ -269,6 +277,8 @@ Current Telegram behavior:
 - pending pairings are explicit and expire automatically after 12 hours unless approved
 - paired Telegram users drive the same live session and permissions as the terminal operator when the TUI bridge is attached
 - Telegram now supports remote workspace control with `/cwd`, `/use <path>`, `/desktop`, and `/new-project <name>`
+- shared projects now support `/room`, `/mode`, `/claim`, and `/release` from Telegram with a single active-operator lock
+- shared Telegram execution only runs when the shared room is in `execute` mode
 - pairing is now explicit: first DM creates a pending request, then approve locally with `waterbrother gateway pair telegram <user-id>`
 
 ## Release flow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tritard/waterbrother",
-  "version": "0.16.21",
+  "version": "0.16.23",
   "description": "Waterbrother: bring-your-own-model coding CLI with local tools, sessions, operator modes, and approval controls",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -57,6 +57,16 @@ import { runQualityChecks, formatQualityFindings, buildQualityFixPrompt } from "
 import { scanForInitiatives, formatInitiatives, buildInitiativeFixPrompt } from "./initiative.js";
 import { formatPlanForDisplay } from "./planner.js";
 import { parseCharterFromGoal, runExperimentLoop, formatExperimentSummary, gitReturnToBranch } from "./experiment.js";
+import {
+  claimSharedOperator,
+  disableSharedProject,
+  enableSharedProject,
+  formatSharedProjectStatus,
+  getSharedProjectPaths,
+  loadSharedProject,
+  releaseSharedOperator,
+  setSharedRoomMode
+} from "./shared-project.js";
 
 const execFileAsync = promisify(execFile);
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -135,6 +145,12 @@ const INTERACTIVE_COMMANDS = [
   { name: "/gateway unpair <user-id>", description: "Remove a paired Telegram user id" },
   { name: "/gateway stop", description: "Stop the tracked Telegram gateway process" },
   { name: "/channels", description: "Show messaging channel readiness" },
+  { name: "/share-project", description: "Enable shared-project mode in the current cwd" },
+  { name: "/unshare-project", description: "Disable shared-project mode in the current cwd" },
+  { name: "/room", description: "Show shared room status for the current project" },
+  { name: "/room mode <chat|plan|execute>", description: "Set collaboration mode for the shared room" },
+  { name: "/room claim", description: "Claim operator control for the shared room" },
+  { name: "/room release", description: "Release operator control for the shared room" },
   { name: "/cwd", description: "Show current working directory" },
   { name: "/use <path>", description: "Switch the live session to a different working directory" },
   { name: "/desktop", description: "Switch the live session to ~/Desktop" },
@@ -253,6 +269,12 @@ Usage:
   waterbrother gateway pairings [telegram]
   waterbrother gateway pair [telegram] <user-id>
   waterbrother gateway unpair [telegram] <user-id>
+  waterbrother project share
+  waterbrother project unshare
+  waterbrother room status
+  waterbrother room mode <chat|plan|execute>
+  waterbrother room claim
+  waterbrother room release
   waterbrother mcp list
   waterbrother commit [--push]
   waterbrother pr [--branch=<name>]
@@ -3697,6 +3719,100 @@ async function runGatewayCommand(positional, runtime, { cwd = process.cwd(), asJ
   throw new Error("Usage: waterbrother gateway status|run <telegram>|stop [telegram]|pairings [telegram]|pair [telegram] <user-id>|unpair [telegram] <user-id>");
 }
 
+function getLocalOperatorIdentity() {
+  const userName = String(process.env.USER || process.env.USERNAME || "local").trim() || "local";
+  return {
+    id: `local:${userName}`,
+    name: userName
+  };
+}
+
+async function runProjectCommand(positional, { cwd = process.cwd(), asJson = false } = {}) {
+  const sub = String(positional[1] || "").trim().toLowerCase();
+  if (sub === "share") {
+    const operator = getLocalOperatorIdentity();
+    const project = await enableSharedProject(cwd, { userId: operator.id, userName: operator.name, role: "owner" });
+    const paths = getSharedProjectPaths(cwd);
+    if (asJson) {
+      printData({ ok: true, action: "share", project, paths }, true);
+      return;
+    }
+    console.log(`Shared project enabled in ${cwd}`);
+    console.log(`shared metadata: ${paths.sharedJson}`);
+    console.log(`roundtable: ${paths.roundtable}`);
+    return;
+  }
+
+  if (sub === "unshare") {
+    const project = await disableSharedProject(cwd);
+    if (asJson) {
+      printData({ ok: true, action: "unshare", project }, true);
+      return;
+    }
+    console.log(project ? `Shared project disabled in ${cwd}` : "Project was not shared");
+    return;
+  }
+
+  throw new Error("Usage: waterbrother project share|unshare");
+}
+
+async function runRoomCommand(positional, { cwd = process.cwd(), asJson = false } = {}) {
+  const sub = String(positional[1] || "status").trim().toLowerCase();
+  if (sub === "status") {
+    const project = await loadSharedProject(cwd);
+    if (asJson) {
+      printData(project || { enabled: false, cwd }, true);
+      return;
+    }
+    console.log(formatSharedProjectStatus(project));
+    return;
+  }
+
+  if (sub === "claim") {
+    const operator = getLocalOperatorIdentity();
+    const project = await claimSharedOperator(cwd, operator);
+    if (asJson) {
+      printData({ ok: true, action: "claim", project }, true);
+      return;
+    }
+    console.log(`Room claimed by ${operator.name}`);
+    return;
+  }
+
+  if (sub === "release") {
+    const operator = getLocalOperatorIdentity();
+    const project = await releaseSharedOperator(cwd, operator.id);
+    if (asJson) {
+      printData({ ok: true, action: "release", project }, true);
+      return;
+    }
+    console.log(`Room released by ${operator.name}`);
+    return;
+  }
+
+  if (sub === "mode") {
+    const nextMode = String(positional[2] || "").trim().toLowerCase();
+    if (!nextMode) {
+      const project = await loadSharedProject(cwd);
+      if (asJson) {
+        printData({ ok: true, roomMode: project?.roomMode || null, project }, true);
+        return;
+      }
+      console.log(project?.roomMode || "shared project: off");
+      return;
+    }
+    const project = await setSharedRoomMode(cwd, nextMode);
+    if (asJson) {
+      printData({ ok: true, action: "mode", roomMode: project.roomMode, project }, true);
+      return;
+    }
+    console.log(`Room mode set to ${project.roomMode}`);
+    return;
+  }
+
+  throw new Error("Usage: waterbrother room status|mode <chat|plan|execute>|claim|release");
+}
+
 async function runMcpCommand(positional, runtime, { cwd, asJson = false } = {}) {
   const sub = positional[1] || "list";
   if (sub !== "list") {
@@ -7495,6 +7611,65 @@ Be concrete about surfaces — name actual pages/flows. Choose the best stack fo
       continue;
     }
 
+    if (line === "/share-project") {
+      try {
+        await runProjectCommand(["project", "share"], { cwd: context.cwd, asJson: false });
+      } catch (error) {
+        console.log(`share-project failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+      continue;
+    }
+
+    if (line === "/unshare-project") {
+      try {
+        await runProjectCommand(["project", "unshare"], { cwd: context.cwd, asJson: false });
+      } catch (error) {
+        console.log(`unshare-project failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+      continue;
+    }
+
+    if (line === "/room") {
+      try {
+        await runRoomCommand(["room", "status"], { cwd: context.cwd, asJson: false });
+      } catch (error) {
+        console.log(`room status failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+      continue;
+    }
+
+    if (line.startsWith("/room mode ")) {
+      const nextMode = line.replace("/room mode", "").trim().toLowerCase();
+      if (!nextMode) {
+        console.log("Usage: /room mode <chat|plan|execute>");
+        continue;
+      }
+      try {
+        await runRoomCommand(["room", "mode", nextMode], { cwd: context.cwd, asJson: false });
+      } catch (error) {
+        console.log(`room mode failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+      continue;
+    }
+
+    if (line === "/room claim") {
+      try {
+        await runRoomCommand(["room", "claim"], { cwd: context.cwd, asJson: false });
+      } catch (error) {
+        console.log(`room claim failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+      continue;
+    }
+
+    if (line === "/room release") {
+      try {
+        await runRoomCommand(["room", "release"], { cwd: context.cwd, asJson: false });
+      } catch (error) {
+        console.log(`room release failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+      continue;
+    }
+
     if (line === "/gateway pairings") {
       const ttlMinutes = Number.isFinite(Number(context.runtime.channels?.telegram?.pairingExpiryMinutes))
         ? Math.max(1, Math.floor(Number(context.runtime.channels.telegram.pairingExpiryMinutes)))
@@ -9311,6 +9486,16 @@ export async function runCli(argv) {
     return;
   }
 
+  if (command === "project") {
+    await runProjectCommand(positional, { cwd: startupCwd, asJson });
+    return;
+  }
+
+  if (command === "room") {
+    await runRoomCommand(positional, { cwd: startupCwd, asJson });
+    return;
+  }
+
   if (command === "gateway") {
     await runGatewayCommand(positional, runtime, { cwd: startupCwd, asJson });
     return;

package/src/gateway.js

@@ -8,6 +8,7 @@ import { createSession, listSessions, loadSession, saveSession } from "./session
 import { DEFAULT_PENDING_PAIRING_TTL_MINUTES, loadGatewayBridge, loadGatewayState, prunePendingPairings, saveGatewayBridge, saveGatewayState } from "./gateway-state.js";
 import { getGatewayStatus, getChannelSpec } from "./channels.js";
 import { canonicalizeLoosePath } from "./path-utils.js";
+import { claimSharedOperator, loadSharedProject, releaseSharedOperator, setSharedRoom, setSharedRoomMode } from "./shared-project.js";
 
 const execFileAsync = promisify(execFile);
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -24,6 +25,10 @@ const TELEGRAM_COMMANDS = [
   { command: "status", description: "Show the linked remote session" },
   { command: "cwd", description: "Show the current remote working directory" },
   { command: "runtime", description: "Show active runtime status" },
+  { command: "room", description: "Show shared room status" },
+  { command: "mode", description: "Show or set shared room mode" },
+  { command: "claim", description: "Claim operator control for a shared project" },
+  { command: "release", description: "Release operator control for a shared project" },
   { command: "sessions", description: "List recent remote sessions" },
   { command: "new", description: "Start a fresh remote session" },
   { command: "clear", description: "Clear current remote conversation" }
@@ -193,6 +198,10 @@ function buildRemoteHelp() {
     "<code>/desktop</code> switch the linked session to <code>~/Desktop</code>",
     "<code>/new-project &lt;name&gt;</code> create a folder on Desktop and switch into it",
     "<code>/runtime</code> show active provider/model/runtime state",
+    "<code>/room</code> show shared project room status",
+    "<code>/mode</code> or <code>/mode &lt;chat|plan|execute&gt;</code> inspect or change shared room mode",
+    "<code>/claim</code> claim operator control for a shared project",
+    "<code>/release</code> release operator control for a shared project",
     "<code>/sessions</code> list recent linked remote sessions",
     "<code>/resume &lt;session-id&gt;</code> switch the linked remote session",
     "<code>/new</code> start a fresh remote session",
@@ -257,6 +266,32 @@ function formatSessionListMarkup(currentSessionId, sessions = []) {
   return lines.join("\n");
 }
 
+function formatTelegramRoomMarkup(project) {
+  if (!project?.enabled) {
+    return "<b>Shared room</b>\nThis project is not shared.";
+  }
+  const members = Array.isArray(project.members) ? project.members : [];
+  const active = project.activeOperator?.id
+    ? `${project.activeOperator.name || project.activeOperator.id} (${project.activeOperator.id})`
+    : "none";
+  const roomLabel = project.room?.chatId
+    ? `${project.room.provider || "telegram"} ${project.room.chatId}${project.room.title ? ` (${project.room.title})` : ""}`
+    : "not linked";
+  const memberLines = members.length
+    ? members.map((member) => `• ${escapeTelegramHtml(member.name || member.id)} <i>(${escapeTelegramHtml(member.role || "editor")})</i>`).join("\n")
+    : "• none";
+  return [
+    "<b>Shared room</b>",
+    `project: <code>${escapeTelegramHtml(project.projectName || "")}</code>`,
+    `mode: <code>${escapeTelegramHtml(project.mode || "single-operator")}</code>`,
+    `room mode: <code>${escapeTelegramHtml(project.roomMode || "chat")}</code>`,
+    `room: <code>${escapeTelegramHtml(roomLabel)}</code>`,
+    `active operator: <code>${escapeTelegramHtml(active)}</code>`,
+    "<b>Members</b>",
+    memberLines
+  ].join("\n");
+}
+
 function extractRetryDelayMs(error, attempt) {
   const retryAfter = Number(error?.retryAfterSeconds);
   if (Number.isFinite(retryAfter) && retryAfter > 0) {
@@ -565,6 +600,52 @@ class TelegramGateway {
     return session.cwd;
   }
 
+  async loadSharedProjectForSession(sessionId) {
+    const session = await loadSession(sessionId);
+    const project = await loadSharedProject(session.cwd || this.cwd);
+    return { session, project };
+  }
+
+  async bindSharedRoomForMessage(message, sessionId) {
+    const { session, project } = await this.loadSharedProjectForSession(sessionId);
+    if (!project?.enabled) {
+      return { session, project };
+    }
+    const next = await setSharedRoom(session.cwd || this.cwd, {
+      provider: "telegram",
+      chatId: String(message.chat.id),
+      title: String(message.chat.title || "").trim()
+    });
+    return { session, project: next };
+  }
+
+  async ensureSharedOperator(message, sessionId) {
+    const { session, project } = await this.loadSharedProjectForSession(sessionId);
+    if (!project?.enabled) return { ok: true, project: null, session };
+    const bound = await this.bindSharedRoomForMessage(message, sessionId);
+    if (bound.project?.roomMode !== "execute") {
+      return {
+        ok: false,
+        project: bound.project,
+        session: bound.session,
+        reason: `Shared room is in ${bound.project?.roomMode || "chat"} mode. Switch to /mode execute before running code.`
+      };
+    }
+    const userId = String(message?.from?.id || "").trim();
+    if (!bound.project?.activeOperator?.id) {
+      return { ok: false, project: bound.project, session: bound.session, reason: "No active operator. Use /claim first." };
+    }
+    if (bound.project.activeOperator.id !== userId) {
+      return {
+        ok: false,
+        project: bound.project,
+        session: bound.session,
+        reason: `Room is currently claimed by ${bound.project.activeOperator.name || bound.project.activeOperator.id}. Use /claim after they release it.`
+      };
+    }
+    return { ok: true, project: bound.project, session: bound.session };
+  }
+
   async getLiveBridgeHost() {
     const bridge = await loadGatewayBridge("telegram");
     const host = bridge.activeHost || {};
@@ -793,6 +874,73 @@ class TelegramGateway {
       return;
     }
 
+    if (text === "/room") {
+      const { project } = await this.bindSharedRoomForMessage(message, sessionId);
+      await this.sendMessage(message.chat.id, project?.enabled ? formatTelegramRoomMarkup(project) : "<b>Shared room</b>\nThis project is not shared.", message.message_id);
+      return;
+    }
+
+    if (text === "/mode") {
+      const { project } = await this.bindSharedRoomForMessage(message, sessionId);
+      await this.sendMessage(
+        message.chat.id,
+        project?.enabled
+          ? `<b>Shared room mode</b>\n<code>${escapeTelegramHtml(project.roomMode || "chat")}</code>`
+          : "This project is not shared.",
+        message.message_id
+      );
+      return;
+    }
+
+    if (text.startsWith("/mode ")) {
+      const requestedMode = text.replace("/mode", "").trim().toLowerCase();
+      const { session, project } = await this.bindSharedRoomForMessage(message, sessionId);
+      if (!project?.enabled) {
+        await this.sendMessage(message.chat.id, "This project is not shared.", message.message_id);
+        return;
+      }
+      try {
+        const next = await setSharedRoomMode(session.cwd || this.cwd, requestedMode);
+        await this.sendMessage(message.chat.id, `Shared room mode set to <code>${escapeTelegramHtml(next.roomMode)}</code>`, message.message_id);
+      } catch (error) {
+        await this.sendMessage(message.chat.id, escapeTelegramHtml(error instanceof Error ? error.message : String(error)), message.message_id);
+      }
+      return;
+    }
+
+    if (text === "/claim") {
+      const { session, project } = await this.bindSharedRoomForMessage(message, sessionId);
+      if (!project?.enabled) {
+        await this.sendMessage(message.chat.id, "This project is not shared. Enable sharing from the terminal first with <code>waterbrother project share</code>.", message.message_id);
+        return;
+      }
+      try {
+        const claimed = await claimSharedOperator(session.cwd || this.cwd, {
+          id: userId,
+          name: peer?.username || [message?.from?.first_name, message?.from?.last_name].filter(Boolean).join(" ").trim() || userId
+        });
+        await this.sendMessage(message.chat.id, `Shared room claimed by <code>${escapeTelegramHtml(claimed.activeOperator?.name || claimed.activeOperator?.id || userId)}</code>`, message.message_id);
+      } catch (error) {
+        await this.sendMessage(message.chat.id, escapeTelegramHtml(error instanceof Error ? error.message : String(error)), message.message_id);
+      }
+      return;
+    }
+
+    if (text === "/release") {
+      const { session, project } = await this.bindSharedRoomForMessage(message, sessionId);
+      if (!project?.enabled) {
+        await this.sendMessage(message.chat.id, "This project is not shared.", message.message_id);
+        return;
+      }
+      try {
+        const released = await releaseSharedOperator(session.cwd || this.cwd, userId);
+        await this.sendMessage(message.chat.id, released.activeOperator?.id ? formatTelegramRoomMarkup(released) : "Shared room released.", message.message_id);
+      } catch (error) {
+        await this.sendMessage(message.chat.id, escapeTelegramHtml(error instanceof Error ? error.message : String(error)), message.message_id);
+      }
+      return;
+    }
+
     if (text === "/runtime") {
       const status = await this.runRuntimeStatus();
       await this.sendMessage(message.chat.id, formatRuntimeStatus(status), message.message_id);
@@ -903,6 +1051,11 @@ class TelegramGateway {
     const stopTyping = await this.startTypingLoop(message.chat.id);
     let previewMessage = null;
     try {
+      const operatorGate = await this.ensureSharedOperator(message, sessionId);
+      if (!operatorGate.ok) {
+        await this.sendMessage(message.chat.id, escapeTelegramHtml(operatorGate.reason || "Shared room is not available."), message.message_id, { parseMode: "HTML" });
+        return;
+      }
       previewMessage = await this.sendProgressMessage(message.chat.id, message.message_id);
       const content = (await this.runPromptViaBridge(message, sessionId, text))
         ?? (await this.runPromptFallback(sessionId, text));

package/src/shared-project.js

@@ -0,0 +1,279 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+const SHARED_FILE = path.join(".waterbrother", "shared.json");
+const ROUNDTABLE_FILE = "ROUNDTABLE.md";
+
+function normalizeMember(member = {}) {
+  return {
+    id: String(member.id || "").trim(),
+    name: String(member.name || "").trim(),
+    role: ["owner", "editor", "observer"].includes(String(member.role || "").trim()) ? String(member.role).trim() : "editor",
+    paired: member.paired !== false
+  };
+}
+
+function normalizeSharedProject(project = {}, cwd = process.cwd()) {
+  const members = Array.isArray(project.members) ? project.members.map(normalizeMember).filter((item) => item.id) : [];
+  const activeOperator = project.activeOperator && typeof project.activeOperator === "object"
+    ? {
+        id: String(project.activeOperator.id || "").trim(),
+        name: String(project.activeOperator.name || "").trim(),
+        claimedAt: String(project.activeOperator.claimedAt || "").trim()
+      }
+    : null;
+
+  return {
+    version: 1,
+    enabled: project.enabled !== false,
+    projectId: String(project.projectId || `proj_${crypto.randomBytes(4).toString("hex")}`).trim(),
+    projectName: String(project.projectName || path.basename(cwd || process.cwd()) || "project").trim(),
+    cwd: String(cwd || project.cwd || process.cwd()).trim(),
+    room: {
+      provider: String(project.room?.provider || "").trim(),
+      chatId: String(project.room?.chatId || "").trim(),
+      title: String(project.room?.title || "").trim()
+    },
+    mode: String(project.mode || "single-operator").trim() || "single-operator",
+    roomMode: ["chat", "plan", "execute"].includes(String(project.roomMode || "").trim())
+      ? String(project.roomMode).trim()
+      : "chat",
+    members,
+    activeOperator: activeOperator?.id ? activeOperator : null,
+    approvalPolicy: String(project.approvalPolicy || "owner").trim() || "owner",
+    createdAt: String(project.createdAt || new Date().toISOString()).trim(),
+    updatedAt: String(project.updatedAt || new Date().toISOString()).trim()
+  };
+}
+
+function sharedFilePath(cwd) {
+  return path.join(cwd, SHARED_FILE);
+}
+
+function roundtablePath(cwd) {
+  return path.join(cwd, ROUNDTABLE_FILE);
+}
+
+async function ensureProjectStateDir(cwd) {
+  await fs.mkdir(path.join(cwd, ".waterbrother"), { recursive: true });
+}
+
+async function pathExists(target) {
+  try {
+    await fs.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function writeJsonAtomically(targetPath, value) {
+  const tempPath = `${targetPath}.${process.pid}.${Date.now()}.tmp`;
+  await fs.writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+  await fs.rename(tempPath, targetPath);
+}
+
+function defaultRoundtableContent(project) {
+  const memberLines = project.members.length
+    ? project.members.map((member) => `- ${member.name || member.id} (${member.role})`).join("\n")
+    : "- none yet";
+  const activeOperator = project.activeOperator?.id
+    ? `${project.activeOperator.name || project.activeOperator.id}`
+    : "none";
+  return [
+    "# Roundtable",
+    "",
+    "## Project",
+    `- Name: ${project.projectName}`,
+    `- Mode: ${project.mode}`,
+    `- Room mode: ${project.roomMode}`,
+    `- Approval policy: ${project.approvalPolicy}`,
+    project.room?.provider ? `- Room: ${project.room.provider} ${project.room.chatId || ""}`.trim() : "- Room: not linked",
+    "",
+    "## Members",
+    memberLines,
+    "",
+    "## Current Goal",
+    "-",
+    "",
+    "## Active Operator",
+    `- ${activeOperator}`,
+    "",
+    "## Decisions",
+    "-",
+    "",
+    "## Open Questions",
+    "-",
+    "",
+    "## Task Queue",
+    "- open: -",
+    "- active: -",
+    "- blocked: -",
+    "- done: -",
+    ""
+  ].join("\n");
+}
+
+export async function ensureRoundtable(cwd, project) {
+  const target = roundtablePath(cwd);
+  if (await pathExists(target)) return target;
+  await fs.writeFile(target, defaultRoundtableContent(project), "utf8");
+  return target;
+}
+
+export async function appendRoundtableEvent(cwd, line) {
+  const target = roundtablePath(cwd);
+  if (!(await pathExists(target))) return null;
+  await fs.appendFile(target, `${String(line || "").trim()}\n`, "utf8");
+  return target;
+}
+
+export async function loadSharedProject(cwd) {
+  try {
+    const raw = await fs.readFile(sharedFilePath(cwd), "utf8");
+    return normalizeSharedProject(JSON.parse(raw), cwd);
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+export async function saveSharedProject(cwd, project) {
+  await ensureProjectStateDir(cwd);
+  const next = normalizeSharedProject({
+    ...project,
+    updatedAt: new Date().toISOString()
+  }, cwd);
+  await writeJsonAtomically(sharedFilePath(cwd), next);
+  await ensureRoundtable(cwd, next);
+  return next;
+}
+
+export async function enableSharedProject(cwd, options = {}) {
+  const existing = await loadSharedProject(cwd);
+  const userName = String(options.userName || process.env.USER || os.userInfo().username || "local").trim();
+  const userId = String(options.userId || `local:${userName}`).trim();
+  const initialRole = String(options.role || "owner").trim() || "owner";
+  const member = normalizeMember({ id: userId, name: userName, role: initialRole, paired: true });
+  const members = existing?.members?.length ? [...existing.members] : [];
+  if (!members.some((item) => item.id === member.id)) members.unshift(member);
+  const project = await saveSharedProject(cwd, {
+    ...existing,
+    enabled: true,
+    projectName: existing?.projectName || path.basename(cwd),
+    members,
+    activeOperator: existing?.activeOperator || {
+      id: member.id,
+      name: member.name,
+      claimedAt: new Date().toISOString()
+    }
+  });
+  await appendRoundtableEvent(cwd, `- ${new Date().toISOString()}: sharing enabled by ${member.name || member.id}`);
+  return project;
+}
+
+export async function disableSharedProject(cwd) {
+  const existing = await loadSharedProject(cwd);
+  if (!existing) return null;
+  const next = await saveSharedProject(cwd, {
+    ...existing,
+    enabled: false,
+    activeOperator: null
+  });
+  await appendRoundtableEvent(cwd, `- ${new Date().toISOString()}: sharing disabled`);
+  return next;
+}
+
+export async function setSharedRoom(cwd, room = {}) {
+  const existing = await loadSharedProject(cwd);
+  if (!existing) throw new Error("Project is not shared. Run `waterbrother project share` first.");
+  const next = await saveSharedProject(cwd, {
+    ...existing,
+    room: {
+      provider: String(room.provider || existing.room?.provider || "").trim(),
+      chatId: String(room.chatId || existing.room?.chatId || "").trim(),
+      title: String(room.title || existing.room?.title || "").trim()
+    }
+  });
+  return next;
+}
+
+export async function setSharedRoomMode(cwd, roomMode = "chat") {
+  const existing = await loadSharedProject(cwd);
+  if (!existing?.enabled) throw new Error("Project is not shared.");
+  const normalized = String(roomMode || "").trim().toLowerCase();
+  if (!["chat", "plan", "execute"].includes(normalized)) {
+    throw new Error("Invalid room mode. Expected one of chat, plan, execute.");
+  }
+  const next = await saveSharedProject(cwd, {
+    ...existing,
+    roomMode: normalized
+  });
+  await appendRoundtableEvent(cwd, `- ${new Date().toISOString()}: room mode set to ${normalized}`);
+  return next;
+}
+
+export async function claimSharedOperator(cwd, operator = {}) {
+  const existing = await loadSharedProject(cwd);
+  if (!existing?.enabled) throw new Error("Project is not shared.");
+  const nextOperator = {
+    id: String(operator.id || "").trim(),
+    name: String(operator.name || "").trim(),
+    claimedAt: new Date().toISOString()
+  };
+  if (!nextOperator.id) throw new Error("operator id is required");
+  if (existing.activeOperator?.id && existing.activeOperator.id !== nextOperator.id) {
+    throw new Error(`Room is currently claimed by ${existing.activeOperator.name || existing.activeOperator.id}`);
+  }
+  const members = [...(existing.members || [])];
+  if (!members.some((item) => item.id === nextOperator.id)) {
+    members.push(normalizeMember({ id: nextOperator.id, name: nextOperator.name, role: "editor", paired: true }));
+  }
+  const next = await saveSharedProject(cwd, {
+    ...existing,
+    members,
+    activeOperator: nextOperator
+  });
+  await appendRoundtableEvent(cwd, `- ${new Date().toISOString()}: operator claimed by ${nextOperator.name || nextOperator.id}`);
+  return next;
+}
+
+export async function releaseSharedOperator(cwd, operatorId = "") {
+  const existing = await loadSharedProject(cwd);
+  if (!existing?.enabled) throw new Error("Project is not shared.");
+  const normalizedId = String(operatorId || "").trim();
+  if (existing.activeOperator?.id && normalizedId && existing.activeOperator.id !== normalizedId) {
+    throw new Error(`Room is currently claimed by ${existing.activeOperator.name || existing.activeOperator.id}`);
+  }
+  const next = await saveSharedProject(cwd, {
+    ...existing,
+    activeOperator: null
+  });
+  await appendRoundtableEvent(cwd, `- ${new Date().toISOString()}: operator released`);
+  return next;
+}
+
+export function formatSharedProjectStatus(project) {
+  if (!project) return "shared project: off";
+  return JSON.stringify({
+    enabled: project.enabled,
+    projectId: project.projectId,
+    projectName: project.projectName,
+    cwd: project.cwd,
+    room: project.room,
+    mode: project.mode,
+    roomMode: project.roomMode,
+    approvalPolicy: project.approvalPolicy,
+    activeOperator: project.activeOperator,
+    members: project.members
+  }, null, 2);
+}
+
+export function getSharedProjectPaths(cwd) {
+  return {
+    sharedJson: sharedFilePath(cwd),
+    roundtable: roundtablePath(cwd)
+  };
+}