viberoom 0.5.8 → 0.6.0

package/README.md

@@ -80,6 +80,16 @@ library marks it as theirs until you have read it.
 
 <br>
 
+## Let them design the room
+
+A vibemate can design a room as well as work in it. It has a built-in skill on what makes rules and
+roles good, and four hub tools: read the room's settings and rules, check a design and preview the
+brief the others would receive, save a template for you to pick under New room, or propose a change to
+the room you are in. A proposal is a card in the chat with the diff; nothing changes until you click
+Apply, and the room is told what you decided.
+
+<br>
+
 ## Talk to all, or to one
 
 <p align="center">
@@ -130,6 +140,8 @@ it in a browser tab. Later, `npm install -g viberoom@latest` and the next start
 - **Nothing leaves your machine** except what each agent sends to its own provider. viberoom never
   sees your keys; every agent keeps its own login.
 - **Edit a message.** Fix what you said; the vibemates get the memo, or the conversation rewinds.
+- **Quote a message.** Select a fragment of a bubble, or copy it with Ctrl+C, and it goes into your next
+  message as a quote — with who said it and when, so the vibemates read it as that person's words, not yours.
 - **Your messages on a timeline.** A thin strip on the chat's right edge, one mark per message of yours:
   hover for the message with its neighbours, click to jump there.
 - **Pick a folder from a tree.** Browse the machine's folders when a room needs one; make a new one on the spot.
@@ -167,6 +179,14 @@ skills and the log.
 
 <br>
 
+## Questions, ideas, bugs
+
+- A question ("how do I ...?") goes to [Discussions → Q&A](https://github.com/todor-rusev/viberoom/discussions/categories/q-a).
+- An idea goes to [Discussions → Ideas](https://github.com/todor-rusev/viberoom/discussions/categories/ideas).
+- A bug goes to [Issues](https://github.com/todor-rusev/viberoom/issues/new/choose); the form asks for what a fix needs.
+
+<br>
+
 ## Development
 
 ```sh

package/dist/agent-health.js

@@ -0,0 +1,52 @@
+// viberoom - Copyright (c) 2026 Todor Rusev - AGPL-3.0-or-later; see LICENSE
+export function loginState(probe, evidence) {
+    if (!probe)
+        return "unknown";
+    if (probe.env.some((name) => (evidence.env[name] ?? "").trim().length > 0))
+        return "ok";
+    if (probe.files.some((file) => evidence.exists(file)))
+        return "ok";
+    if (probe.fileless?.includes(evidence.platform))
+        return "unknown";
+    return probe.files.length ? "missing" : "unknown";
+}
+const LOGIN_WORDS = /\b(not logged in|log ?in required|login required|please log ?in|unauthori[sz]ed|authentication (failed|required|error)|invalid api key|api key (is )?(missing|not set|invalid)|no credentials|credentials not found|401|403|oauth|token (expired|invalid))\b/i;
+const MISSING_WORDS = /\b(enoent|not found|no such file|is not recognized|command not found|spawn\w* (failed|error))\b/i;
+const TIMEOUT_WORDS = /\b(timed out|timeout|took too long|did not answer|no response)\b/i;
+export function classifyStartFailure(input) {
+    const text = [input.error, ...(input.stderr ?? [])].join("\n");
+    const login = input.loginCommand ? `run \`${input.loginCommand}\` in a terminal, then try again` : `log in to ${input.vendor} in a terminal, then try again`;
+    if (LOGIN_WORDS.test(text) || input.loginState === "missing") {
+        return {
+            kind: "login",
+            what: `${input.vendor} is installed here but the hub could not get past its login.`,
+            advice: `${login}. The hub never asks for credentials itself: it uses the login the vendor's own CLI keeps on this machine.`,
+        };
+    }
+    if (MISSING_WORDS.test(text)) {
+        return {
+            kind: "not-installed",
+            what: `The ${input.vendor} program could not be started: this machine could not find or run it.`,
+            advice: input.installHint ? `Install or repair it: ${input.installHint}. Then run \`viberoom doctor\`, which lists what was found.` : "Reinstall it, then run `viberoom doctor`, which lists what was found.",
+        };
+    }
+    if (TIMEOUT_WORDS.test(text)) {
+        return {
+            kind: "timeout",
+            what: `${input.vendor} started but did not answer the hub in time.`,
+            advice: `Start it yourself once in a terminal (\`${input.loginCommand ?? input.vendor.toLowerCase()}\`): a first run that asks something — a login, a trust prompt, an update — blocks the protocol until it is answered.`,
+        };
+    }
+    if (/\bexited\b|\bexit code\b|\bsignal\b|\bclosed\b/i.test(text)) {
+        return {
+            kind: "crash",
+            what: `${input.vendor} started and then stopped before the hub could talk to it.`,
+            advice: `Run it once in a terminal to see what it prints; \`viberoom logs\` has the hub's side, with the agent's own last lines.`,
+        };
+    }
+    return {
+        kind: "unknown",
+        what: `${input.vendor} could not be started.`,
+        advice: `Run it once in a terminal to see what it says; \`viberoom logs\` has the hub's side, with the agent's own last lines.`,
+    };
+}

package/dist/context.js

@@ -25,6 +25,12 @@ export function crossedThreshold(previousUsed, used, size, threshold = NOTES_THR
         return false;
     return used / size >= threshold && previousUsed / size < threshold;
 }
+export function emptyUsageReport(previousUsed, used) {
+    return previousUsed > 0 && used === 0;
+}
+export function looksCompacted(previousUsed, used) {
+    return previousUsed > 0 && used > 0 && used < previousUsed * 0.7;
+}
 export function overThreshold(used, size, threshold = NOTES_THRESHOLD) {
     return size > 0 && used / size >= threshold;
 }

package/dist/duration.js

@@ -0,0 +1,12 @@
+// viberoom - Copyright (c) 2026 Todor Rusev - AGPL-3.0-or-later; see LICENSE
+export function formatDuration(ms) {
+    const total = Math.max(0, Math.round(ms / 1000));
+    if (total < 60)
+        return `${total} s`;
+    const seconds = String(total % 60).padStart(2, "0");
+    const minutes = Math.floor(total / 60) % 60;
+    const hours = Math.floor(total / 3600);
+    if (!hours)
+        return `${minutes}m ${seconds}s`;
+    return `${hours}h ${String(minutes).padStart(2, "0")}m ${seconds}s`;
+}

package/dist/hub.js

@@ -10,7 +10,7 @@ import { listRecipes } from "./recipes.js";
 import { DEFAULT_ROOM_SETTINGS } from "./persona.js";
 import { Room } from "./room.js";
 import { SkillLibrary } from "./skills.js";
-import { TemplateLibrary } from "./templates.js";
+import { TemplateLibrary, roomSettingsFromTemplate } from "./templates.js";
 export const TEXT_FONTS = ["nunito", "inter", "noto-sans", "arial", "system"];
 export const MONO_FONTS = ["jetbrains-mono", "fira-code", "source-code-pro", "system"];
 export const DEFAULT_APPEARANCE = { chatFontSize: 14.5, font: "nunito", mono: "jetbrains-mono" };
@@ -45,6 +45,8 @@ export class Hub extends EventEmitter {
             library: this.skills,
             serverScript: fileURLToPath(new URL("./mcp-skills-server.js", import.meta.url)),
             hubUrl: () => this.hubUrl,
+            templates: this.templates,
+            templatesChanged: () => this.emit("event", { type: "templates" }),
             needApproval: () => this.settings.agentSkillsNeedApproval === true,
             save: (draft) => {
                 const { body: _b, ...meta } = this.saveSkillInternal(draft);
@@ -114,6 +116,7 @@ export class Hub extends EventEmitter {
             editor: { ...DEFAULT_EDITOR_SETTINGS },
             appearance: { ...DEFAULT_APPEARANCE },
             checkForUpdates: true,
+            reconnectMode: "replay",
             roomDefaults: {},
             vendorPresets: {},
         };
@@ -183,6 +186,14 @@ export class Hub extends EventEmitter {
         }
         if (!next.diagrams)
             next.diagrams = { preset: "pop", primary: null };
+        if (patch.reconnectMode !== undefined) {
+            const mode = String(patch.reconnectMode);
+            if (mode !== "replay" && mode !== "load")
+                throw new Error("reconnectMode must be replay or load");
+            next.reconnectMode = mode;
+        }
+        if (next.reconnectMode !== "load")
+            next.reconnectMode = "replay";
         if (patch.editor !== undefined && typeof patch.editor === "object" && patch.editor) {
             const e = patch.editor;
             const mode = String(e.mode ?? next.editor?.mode ?? "auto");
@@ -332,7 +343,7 @@ export class Hub extends EventEmitter {
         const template = this.templates.get(input.templateId);
         if (!template)
             throw new Error(`no such template: ${input.templateId}`);
-        const { room, notices } = this.createRoom({ name: input.name, dir: input.dir || template.dir || null, settings: template.settings });
+        const { room, notices } = this.createRoom({ name: input.name, dir: input.dir || template.dir || null, settings: roomSettingsFromTemplate(template) });
         const installed = new Set(listRecipes().filter((r) => !r.unavailableReason).map((r) => r.id));
         for (const [i, tv] of template.vibemates.entries()) {
             const choice = { ...(input.vibemates[i] ?? { name: tv.name, agentType: "" }) };

package/dist/launcher.js

@@ -1,6 +1,6 @@
 // viberoom - Copyright (c) 2026 Todor Rusev - AGPL-3.0-or-later; see LICENSE
 import { existsSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
-import { join, posix, win32 } from "node:path";
+import { join, posix, resolve, win32 } from "node:path";
 const COMMANDS = new Set(["run", "serve", "start", "stop", "status", "open", "logs", "doctor", "help"]);
 export function splitCommand(argv) {
     const first = argv[0];
@@ -26,7 +26,7 @@ export function readPidFile(dataDir) {
         const parsed = JSON.parse(raw);
         if (typeof parsed.pid !== "number")
             return null;
-        return { pid: parsed.pid, port: Number(parsed.port ?? 0), build: String(parsed.build ?? ""), startedAt: Number(parsed.startedAt ?? 0) };
+        return { pid: parsed.pid, port: Number(parsed.port ?? 0), build: String(parsed.build ?? ""), startedAt: Number(parsed.startedAt ?? 0), ...(parsed.foreground ? { foreground: true } : {}) };
     }
     catch {
         return null;
@@ -41,6 +41,23 @@ export function isProcessAlive(pid) {
         return error.code === "EPERM";
     }
 }
+export function sameDataDir(a, b) {
+    const norm = (p) => {
+        const r = resolve(p).replace(/[\\/]+$/, "");
+        return process.platform === "win32" ? r.toLowerCase() : r;
+    };
+    return norm(a) === norm(b);
+}
+export function hubPortFor(port, portGiven, liveRecord) {
+    if (portGiven || !liveRecord || !liveRecord.port)
+        return port;
+    return liveRecord.port;
+}
+export function foreignHub(identity, dataDir) {
+    if (!identity || !identity.dataDir)
+        return null;
+    return sameDataDir(identity.dataDir, dataDir) ? null : identity.dataDir;
+}
 const LOG_ROTATE_BYTES = 5 * 1024 * 1024;
 export function rotateLog(path, limit = LOG_ROTATE_BYTES) {
     try {

package/dist/main.js

@@ -8,7 +8,7 @@ import { fileURLToPath } from "node:url";
 import { Hub } from "./hub.js";
 import { Logger } from "./log.js";
 import { startServer } from "./server.js";
-import { appWindowArgs, recordedWindowPlacement, savedWindowPlacement, browserAdvice, findChromium, isProcessAlive, logFilePath, openUrlCommand, pidFilePath, readPidFile, rotateLog, splitCommand, tailFile, writePidFile, } from "./launcher.js";
+import { appWindowArgs, recordedWindowPlacement, savedWindowPlacement, browserAdvice, findChromium, foreignHub, hubPortFor, isProcessAlive, logFilePath, openUrlCommand, pidFilePath, readPidFile, rotateLog, splitCommand, tailFile, writePidFile, } from "./launcher.js";
 import { aumidSyncScript, installShortcuts, windowsShortcutPaths } from "./shortcuts.js";
 import { askEnter, renderInstalled, runMenu, unicodeSupported } from "./tui.js";
 import { listRecipes } from "./recipes.js";
@@ -17,11 +17,13 @@ function parseArgs(argv) {
     const options = {
         command,
         port: 4810,
+        portGiven: false,
         dataDir: process.env.VIBEROOM_DATA_DIR ? resolve(process.env.VIBEROOM_DATA_DIR) : resolve(homedir(), ".viberoom"),
         name: undefined,
         open: true,
         browser: false,
         menu: true,
+        force: false,
     };
     for (let i = 0; i < rest.length; i++) {
         const arg = rest[i];
@@ -34,6 +36,7 @@ function parseArgs(argv) {
         switch (arg) {
             case "--port":
                 options.port = Number(next());
+                options.portGiven = true;
                 break;
             case "--name":
                 options.name = next();
@@ -49,6 +52,9 @@ function parseArgs(argv) {
                 options.open = false;
                 options.menu = false;
                 break;
+            case "--force":
+                options.force = true;
+                break;
             case "--browser":
                 options.browser = true;
                 options.menu = false;
@@ -74,8 +80,9 @@ Commands
                process and open the window; if a hub is already running, open it (or replace it
                when this build is newer)
   start        run the hub hidden in the background (log in <data-dir>/hub.log) and open the window
-  stop         stop the background hub
-  status       show whether a hub is running, its build and address
+  stop         stop this data folder's hub (found through its pid file; a hub of another folder on
+               the port is left alone; --port names a port explicitly)
+  status       show whether this data folder's hub is running, its build and address
   open         open the window of the running hub
   logs         print the last lines of the background hub's log
   doctor       check Node, the browser, the coding agents and the hub; say what is missing and why
@@ -88,11 +95,11 @@ Options
   --browser    open the default browser instead of a Chromium app window
 `);
 }
-import { checkForUpdate } from "./update.js";
+import { checkForUpdate, newerSourceThanBuild } from "./update.js";
 function buildInfo() {
     const pkg = JSON.parse(readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8"));
     const built = statSync(fileURLToPath(import.meta.url)).mtime;
-    return { name: pkg.name, version: pkg.version, build: built.toISOString() };
+    return { name: pkg.name, version: pkg.version, build: built.toISOString(), staleSource: newerSourceThanBuild(import.meta.url) };
 }
 async function runningInstance(port) {
     const url = `http://127.0.0.1:${port}/`;
@@ -110,14 +117,21 @@ async function runningInstance(port) {
     try {
         const res = await fetch(`${url}api/version`, { signal: AbortSignal.timeout(1500) });
         if (!res.ok)
-            return { url, build: null };
+            return { url, build: null, dataDir: null, pid: null };
         const info = (await res.json());
-        return { url, build: typeof info.build === "string" ? info.build : null };
+        return { url, build: typeof info.build === "string" ? info.build : null, dataDir: typeof info.dataDir === "string" ? info.dataDir : null, pid: typeof info.pid === "number" ? info.pid : null };
     }
     catch {
-        return { url, build: null };
+        return { url, build: null, dataDir: null, pid: null };
     }
 }
+function liveRecord(dataDir) {
+    const record = readPidFile(dataDir);
+    return record && isProcessAlive(record.pid) ? record : null;
+}
+function otherHubMessage(port, other, mine) {
+    return `port ${port} is used by a viberoom hub whose rooms are in ${other}, not in ${mine}; it was left alone. Run this one on another port (--port ${port + 1}) or stop that hub first: viberoom stop --data-dir "${other}"`;
+}
 async function waitUntil(check, timeoutMs, stepMs = 250) {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
@@ -225,7 +239,9 @@ async function runDoctor(options, info) {
     const found = recipes.filter((r) => !r.unavailableReason);
     lines.push(`${found.length ? "ok  " : "warn"} coding agents: ${found.length ? found.map((r) => r.vendor).join(", ") : "none found"}${found.length ? "" : " (install and log in to at least one: Claude Code, Codex, Gemini CLI, Cursor, OpenCode or GitHub Copilot)"}`);
     for (const r of recipes.filter((r) => r.unavailableReason))
-        lines.push(`     ${r.vendor}: ${r.unavailableReason}`);
+        lines.push(`     ${r.vendor}: ${r.unavailableReason} (${r.installHint})`);
+    for (const r of found.filter((r) => r.loginState === "missing"))
+        lines.push(`warn ${r.vendor}: installed, not logged in: run \`${r.loginCommand}\``);
     const running = await runningInstance(options.port);
     lines.push(running ? `ok   hub running at ${running.url} (build ${running.build ?? "unknown"})` : `info no hub on port ${options.port}: start one with "viberoom start" (or "viberoom start --browser" without a Chromium browser)`);
     lines.push(`     data: ${options.dataDir}`);
@@ -238,6 +254,9 @@ async function runHub(options, log, info) {
     const background = options.command === "serve";
     if (!background) {
         const running = await runningInstance(options.port);
+        const other = foreignHub(running, options.dataDir);
+        if (other)
+            throw new Error(otherHubMessage(options.port, other, options.dataDir));
         if (running && running.build === info.build) {
             log.info(`viberoom is already running at ${running.url} (same build); opening it.`);
             process.stdout.write(`${running.url}\n`);
@@ -265,14 +284,13 @@ async function runHub(options, log, info) {
         log.info("shutting down: closing agent sessions");
         await hub.shutdown();
         server?.close();
-        if (background)
-            rmSync(pidFilePath(options.dataDir), { force: true });
+        rmSync(pidFilePath(options.dataDir), { force: true });
         process.exit(0);
     };
     const listenDeadline = Date.now() + 15_000;
     for (;;) {
         try {
-            server = await startServer(hub, options.port, log.child("http"), info, () => void shutdown());
+            server = await startServer(hub, options.port, log.child("http"), info, () => void shutdown(), () => handOverToFreshHub(options, log));
             break;
         }
         catch (error) {
@@ -294,9 +312,10 @@ async function runHub(options, log, info) {
                 log.warn(`update check failed: ${update.error}`);
         });
     }
-    if (background)
-        writePidFile(options.dataDir, { pid: process.pid, port: options.port, build: info.build, startedAt: Date.now() });
+    writePidFile(options.dataDir, { pid: process.pid, port: options.port, build: info.build, startedAt: Date.now(), ...(background ? {} : { foreground: true }) });
     log.info(`viberoom ${info.version} (build ${info.build}) is open at ${server.url} (data: ${hub.dataDir}; rooms: ${[...hub.rooms.values()].map((r) => r.name).join(", ")})`);
+    if (info.staleSource)
+        log.warn(`the code on disk is newer than this build (${info.staleSource} changed after dist/ was compiled): the UI is served live, the hub is not; rebuild and restart with: node scripts/update.mjs`);
     process.stdout.write(`${server.url}\n`);
     if (options.open && !background)
         openWindow(server.url, options, log);
@@ -304,10 +323,22 @@ async function runHub(options, log, info) {
     process.on("SIGTERM", () => void shutdown());
     process.on("SIGHUP", () => void shutdown());
 }
+function handOverToFreshHub(options, log) {
+    const args = [fileURLToPath(import.meta.url), "start", "--force", "--port", String(options.port), "--data-dir", options.dataDir, "--no-open"];
+    if (options.name)
+        args.push("--name", options.name);
+    const child = spawn(process.execPath, args, { cwd: options.dataDir, detached: true, stdio: "ignore", windowsHide: true });
+    child.unref();
+    log.info(`restart requested from the window: a fresh hub is starting (pid ${child.pid})`);
+}
 async function startBackground(options, log, info) {
-    const url = `http://127.0.0.1:${options.port}/`;
-    const running = await runningInstance(options.port);
-    if (running && running.build === info.build) {
+    const port = hubPortFor(options.port, options.portGiven, liveRecord(options.dataDir));
+    const url = `http://127.0.0.1:${port}/`;
+    const running = await runningInstance(port);
+    const other = foreignHub(running, options.dataDir);
+    if (other)
+        throw new Error(otherHubMessage(port, other, options.dataDir));
+    if (running && running.build === info.build && !options.force) {
         log.info(`viberoom is already running at ${url} (same build).`);
         process.stdout.write(`${url}\n`);
         if (options.open)
@@ -317,20 +348,20 @@ async function startBackground(options, log, info) {
     if (running) {
         log.info(`an older viberoom build is running at ${url}; replacing it with the build from ${info.build}`);
         if (!(await stopInstance(url, log)))
-            throw new Error(`the older viberoom hub on port ${options.port} did not stop; try: viberoom stop`);
+            throw new Error(`the older viberoom hub on port ${port} did not stop; try: viberoom stop`);
     }
     mkdirSync(options.dataDir, { recursive: true });
     const logPath = logFilePath(options.dataDir);
     rotateLog(logPath);
     const fd = openSync(logPath, "a");
-    const args = [fileURLToPath(import.meta.url), "serve", "--port", String(options.port), "--data-dir", options.dataDir, "--no-open"];
+    const args = [fileURLToPath(import.meta.url), "serve", "--port", String(port), "--data-dir", options.dataDir, "--no-open"];
     if (options.name)
         args.push("--name", options.name);
     const child = spawn(process.execPath, args, { cwd: options.dataDir, detached: true, stdio: ["ignore", fd, fd], windowsHide: true });
     child.unref();
     closeSync(fd);
     log.info(`hub started in the background (pid ${child.pid}); log: ${logPath}`);
-    const up = await waitUntil(async () => (await runningInstance(options.port))?.build === info.build, 20_000);
+    const up = await waitUntil(async () => (await runningInstance(port))?.build === info.build, 20_000);
     if (!up)
         throw new Error(`the hub did not come up within 20 s; see ${logPath}`);
     process.stdout.write(`${url}\n`);
@@ -338,23 +369,27 @@ async function startBackground(options, log, info) {
         openWindow(url, options, log);
 }
 async function stopBackground(options, log) {
-    const url = `http://127.0.0.1:${options.port}/`;
-    const record = readPidFile(options.dataDir);
+    const live = liveRecord(options.dataDir);
+    const port = hubPortFor(options.port, options.portGiven, live);
+    const url = `http://127.0.0.1:${port}/`;
+    const other = foreignHub(await runningInstance(port), options.dataDir);
+    if (other)
+        throw new Error(`the hub on port ${port} keeps its rooms in ${other}, not in ${options.dataDir}, so it was left running. To stop that one: viberoom stop --data-dir "${other}"`);
     if (await isUp(url)) {
         const ok = await stopInstance(url, log);
         if (ok) {
-            log.info(`hub on port ${options.port} stopped`);
+            log.info(`hub on port ${port} stopped`);
             rmSync(pidFilePath(options.dataDir), { force: true });
             return;
         }
     }
-    if (record && isProcessAlive(record.pid)) {
-        log.warn(`the hub did not answer on ${url}; terminating pid ${record.pid}`);
+    if (live) {
+        log.warn(`the hub did not answer on ${url}; terminating pid ${live.pid}`);
         try {
-            process.kill(record.pid);
+            process.kill(live.pid);
         }
         catch (error) {
-            throw new Error(`could not terminate pid ${record.pid}: ${String(error)}`);
+            throw new Error(`could not terminate pid ${live.pid}: ${String(error)}`);
         }
         rmSync(pidFilePath(options.dataDir), { force: true });
         return;
@@ -363,15 +398,22 @@ async function stopBackground(options, log) {
     log.info("no hub is running");
 }
 async function showStatus(options) {
-    const url = `http://127.0.0.1:${options.port}/`;
-    const running = await runningInstance(options.port);
     const record = readPidFile(options.dataDir);
+    const live = record && isProcessAlive(record.pid) ? record : null;
+    const port = hubPortFor(options.port, options.portGiven, live);
+    const url = `http://127.0.0.1:${port}/`;
+    const running = await runningInstance(port);
     if (running) {
-        const pid = record && isProcessAlive(record.pid) ? ` (background pid ${record.pid}, started ${new Date(record.startedAt).toLocaleString()})` : " (foreground or another data folder)";
-        process.stdout.write(`running at ${url}${pid}\nbuild: ${running.build ?? "unknown (older build)"}\ndata: ${options.dataDir}\nlog: ${logFilePath(options.dataDir)}\n`);
+        const other = foreignHub(running, options.dataDir);
+        const who = other
+            ? ` (a hub of another data folder: ${other}; this folder's hub is not running)`
+            : live
+                ? ` (${live.foreground ? "pid" : "background pid"} ${live.pid}, started ${new Date(live.startedAt).toLocaleString()})`
+                : " (foreground or another data folder)";
+        process.stdout.write(`running at ${url}${who}\nbuild: ${running.build ?? "unknown (older build)"}\ndata: ${other ?? options.dataDir}\nlog: ${logFilePath(other ?? options.dataDir)}\n`);
     }
     else {
-        process.stdout.write(`not running on port ${options.port}${record ? ` (stale pid file: ${record.pid})` : ""}\n`);
+        process.stdout.write(`not running on port ${port}${record ? ` (stale pid file: ${record.pid})` : ""}\n`);
         if (record && !isProcessAlive(record.pid))
             rmSync(pidFilePath(options.dataDir), { force: true });
     }
@@ -394,9 +436,10 @@ async function main() {
             await showStatus(options);
             return;
         case "open": {
-            const url = `http://127.0.0.1:${options.port}/`;
+            const port = hubPortFor(options.port, options.portGiven, liveRecord(options.dataDir));
+            const url = `http://127.0.0.1:${port}/`;
             if (!(await isUp(url)))
-                throw new Error(`no hub is running on port ${options.port}; start one with: viberoom start`);
+                throw new Error(`no hub is running on port ${port}; start one with: viberoom start`);
             openWindow(url, options, log);
             return;
         }

package/dist/mcp-skills-server.js

@@ -13,6 +13,33 @@ const SKILL_FIELDS = {
     agent_invocable: { type: "boolean", description: "optional (default true): agents may load it themselves" },
     dry_run: { type: "boolean", description: "optional: only lint, write nothing" },
 };
+const DESIGN_FIELDS = {
+    kind: { type: "string", enum: ["template", "room"], description: "template: a whole template (name, description, vibemates); room: a change to this room, starting from its current settings" },
+    name: { type: "string", description: "the template's name (1-40 characters; the id is derived from it)" },
+    description: { type: "string", description: "what the room is for and how it feels, two sentences; shown in the picker" },
+    emoji: { type: "string", description: "optional: the room's emoji" },
+    settings: {
+        type: "object",
+        description: "room settings by key, only the ones you set; describe_room lists the keys with their meaning, bounds and defaults. Rules go in customRules, one per line.",
+        additionalProperties: true,
+    },
+    vibemates: {
+        type: "array",
+        description: "the vibemates: name (1-24 letters, digits, _ or -), tagline (the one line the others see, up to 80 characters), role (who this one is and which way it leans; private), avatar (one emoji), skills (names from the library)",
+        items: {
+            type: "object",
+            properties: {
+                name: { type: "string" },
+                tagline: { type: "string" },
+                role: { type: "string" },
+                avatar: { type: "string" },
+                skills: { type: "array", items: { type: "string" } },
+                replyDelay: { type: "number", description: "optional: seconds this vibemate waits before a turn, overriding the room's delay" },
+            },
+            required: ["name"],
+        },
+    },
+};
 const TOOLS = [
     {
         name: TOOL_NAME,
@@ -45,6 +72,71 @@ const TOOLS = [
             required: ["name"],
         },
     },
+    {
+        name: "describe_room",
+        description: "The facts about this room before you design anything: its settings with their meaning, bounds, defaults and current values; the rules; the vibemates (name, tagline, role, avatar, skills); the skill library; the templates that exist; and the brief you yourself receive. Read-only. Load the built-in skill \"room-designer\" for what makes rules and roles good.",
+        inputSchema: { type: "object", properties: {} },
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: "lint_room_design",
+        description: "Check a room design without saving anything: the same errors and warnings create_template / propose_room_changes would give, plus a preview of the brief the first vibemate would receive (exactly what the room will read). kind \"template\" checks a whole template; kind \"room\" checks a change to this room, starting from its current settings.",
+        inputSchema: { type: "object", properties: DESIGN_FIELDS, required: ["kind"] },
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: "create_template",
+        description: "Save a room template into the human's library: a file the human picks under New room to create a room with these settings, rules and vibemates. No effect on any existing room. The hub checks the design first (errors stop the save, warnings come back with it). A taken name gets a numbered id unless replace is true and the template is one you or the human made.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: DESIGN_FIELDS.name,
+                description: DESIGN_FIELDS.description,
+                emoji: DESIGN_FIELDS.emoji,
+                settings: DESIGN_FIELDS.settings,
+                vibemates: DESIGN_FIELDS.vibemates,
+                replace: { type: "boolean", description: "optional: overwrite the template with this name instead of saving a numbered copy (never a template viberoom ships)" },
+            },
+            required: ["name", "description", "vibemates"],
+        },
+    },
+    {
+        name: "propose_room_changes",
+        description: "Propose changes to this room: settings by key (rules in customRules, one per line) and vibemates to add, update or remove. The hub checks the change set like a template, then shows the human a card with the diff and the warnings; nothing changes until the human clicks Apply, and the room gets a line with the outcome. A new vibemate is added waiting for the human to pick its coding agent. Say in why what the change fixes.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                why: { type: "string", description: "one or two sentences: what this change fixes or enables; shown on the card" },
+                settings: DESIGN_FIELDS.settings,
+                vibemates: {
+                    type: "object",
+                    description: "optional: vibemates to add (full entries), update (by name; give only the fields that change; newName renames) or remove (names)",
+                    properties: {
+                        add: DESIGN_FIELDS.vibemates,
+                        update: {
+                            type: "array",
+                            items: { type: "object", properties: { name: { type: "string" }, newName: { type: "string" }, tagline: { type: "string" }, role: { type: "string" }, avatar: { type: "string" }, skills: { type: "array", items: { type: "string" } }, replyDelay: { type: "number" } }, required: ["name"] },
+                        },
+                        remove: { type: "array", items: { type: "string" } },
+                    },
+                },
+            },
+            required: ["why"],
+        },
+    },
+    {
+        name: "read_message",
+        description: "One message of this room by its number: the whole of a message that was quoted to you as \"> Name (#N, time): …\", or any message whose #N you have seen. Returns who wrote it, to whom, when, its text, its images as file paths and, with around > 0, up to that many messages before and after it. Read-only; the human sees the call like any other tool call.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                seq: { type: "integer", description: "the message number, the N of #N" },
+                around: { type: "integer", minimum: 0, maximum: 5, description: "optional: how many neighbouring messages to include on each side (default 0, at most 5)" },
+            },
+            required: ["seq"],
+        },
+        annotations: { readOnlyHint: true },
+    },
 ];
 let readySent = false;
 function send(message) {
@@ -144,6 +236,57 @@ async function handle(message) {
                 reply(id, { content: [{ type: "text", text: String(res.body.message ?? "attached") }] });
                 return;
             }
+            if (name === "describe_room") {
+                const res = await hub(`/api/mcp/room?token=${encodeURIComponent(TOKEN)}`);
+                if (!res.ok)
+                    return errorResult("the room could not be described", res);
+                reply(id, { content: [{ type: "text", text: JSON.stringify(res.body, null, 2) }] });
+                return;
+            }
+            if (name === "lint_room_design") {
+                const res = await hub("/api/mcp/design/lint", {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({ token: TOKEN, ...args }),
+                });
+                if (!res.ok)
+                    return errorResult("the design could not be checked", res);
+                reply(id, { content: [{ type: "text", text: JSON.stringify(res.body, null, 2) }], isError: res.body.ok === false ? true : undefined });
+                return;
+            }
+            if (name === "create_template") {
+                const res = await hub("/api/mcp/templates", {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({ token: TOKEN, ...args }),
+                });
+                if (!res.ok)
+                    return errorResult("the template could not be saved", res);
+                reply(id, { content: [{ type: "text", text: String(res.body.message ?? "saved") }] });
+                return;
+            }
+            if (name === "propose_room_changes") {
+                const res = await hub("/api/mcp/propose", {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({ token: TOKEN, ...args }),
+                });
+                if (!res.ok)
+                    return errorResult("the proposal could not be made", res);
+                reply(id, { content: [{ type: "text", text: String(res.body.message ?? "proposed") }] });
+                return;
+            }
+            if (name === "read_message") {
+                const seq = Number(args.seq);
+                if (!Number.isInteger(seq))
+                    return fail(id, -32602, "read_message needs seq: the message number, the N of #N");
+                const around = Number(args.around);
+                const res = await hub(`/api/mcp/message?token=${encodeURIComponent(TOKEN)}&seq=${seq}${Number.isInteger(around) && around > 0 ? `&around=${around}` : ""}`);
+                if (!res.ok)
+                    return errorResult("the message could not be read", res);
+                reply(id, { content: [{ type: "text", text: JSON.stringify(res.body, null, 2) }] });
+                return;
+            }
             fail(id, -32602, `unknown tool: ${name}`);
             return;
         }