@hmanlab/multiplayer 0.4.3

package/dist/multiplayer-tools.js

@@ -0,0 +1,2704 @@
+// @bun
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// src/persistence/paths.ts
+import { homedir } from "os";
+import { join } from "path";
+function stateDir() {
+  return join(homedir(), ".hl-plugins", "multiplayer");
+}
+function statePath() {
+  return join(stateDir(), "state.json");
+}
+function handlePath() {
+  return join(stateDir(), "handle");
+}
+var init_paths = () => {};
+
+// src/persistence/paths-async.ts
+var exports_paths_async = {};
+__export(exports_paths_async, {
+  ensureStateDir: () => ensureStateDir
+});
+import { mkdir } from "fs/promises";
+async function ensureStateDir() {
+  await mkdir(stateDir(), { recursive: true });
+}
+var init_paths_async = __esm(() => {
+  init_paths();
+});
+
+// src/index.ts
+import { tool } from "@opencode-ai/plugin";
+
+// src/persistence/index.ts
+init_paths();
+
+// src/persistence/handle-file.ts
+init_paths();
+import { existsSync, readFileSync } from "fs";
+
+// src/constants.ts
+var DEFAULT_PORT = 7332;
+var DEFAULT_HOST = "localhost";
+var HANDLE_RE = /^[a-z0-9-]{1,16}$/;
+var CODE_RE = /^mp-([a-z0-9-]{1,16})-([a-z0-9]{4})-([a-z0-9]{4})$/;
+var ALPHA = "abcdefghijklmnopqrstuvwxyz0123456789";
+var GRACE_S = 10;
+var CASCADE_TIMEOUT_MS = 5000;
+var REJOIN_TTL_MS = 60 * 60 * 1000;
+var JOIN_TIMEOUT_MS = 5000;
+var HISTORY_MAX = 50;
+var MAX_COLLISION_ATTEMPTS = 50;
+
+// src/handle/resolver.ts
+function isValidHandle(handle) {
+  return HANDLE_RE.test(handle);
+}
+function normalizeHandle(raw) {
+  return raw.toLowerCase().replace(/[^a-z0-9-]/g, "").slice(0, 16);
+}
+function osUser() {
+  return process.env["USER"] ?? process.env["USERNAME"] ?? "anon";
+}
+// src/handle/codes.ts
+function random4() {
+  let out = "";
+  for (let i = 0;i < 4; i++) {
+    out += ALPHA[Math.floor(Math.random() * ALPHA.length)];
+  }
+  return out;
+}
+function mintCode(handle) {
+  return `mp-${handle}-${random4()}-${random4()}`;
+}
+function isValidCode(code) {
+  return CODE_RE.test(code.toLowerCase());
+}
+// src/handle/collision.ts
+function assignCollisionSuffix(base, taken) {
+  const takenSet = new Set;
+  for (const h of taken)
+    takenSet.add(h);
+  for (let attempt = 0;attempt < MAX_COLLISION_ATTEMPTS; attempt++) {
+    const suffix = random4();
+    const candidate = `${base}-${suffix}`.slice(0, 16);
+    if (isValidHandle(candidate) && !takenSet.has(candidate)) {
+      return candidate;
+    }
+  }
+  let n = 2;
+  while (n < 1000) {
+    const candidate = `${base}-${n}`.slice(0, 16);
+    if (isValidHandle(candidate) && !takenSet.has(candidate))
+      return candidate;
+    n++;
+  }
+  return base.slice(0, 12);
+}
+// src/persistence/handle-file.ts
+function readHandleFileSync() {
+  try {
+    const path = handlePath();
+    if (!existsSync(path))
+      return null;
+    const text = readFileSync(path, "utf-8").trim();
+    if (text.length === 0)
+      return null;
+    if (!isValidHandle(text))
+      return null;
+    return text;
+  } catch {
+    return null;
+  }
+}
+async function writeHandleFile(handle) {
+  const { ensureStateDir: ensureStateDir2 } = await Promise.resolve().then(() => (init_paths_async(), exports_paths_async));
+  await ensureStateDir2();
+  await Bun.write(handlePath(), handle);
+}
+// src/persistence/state-store.ts
+import { rename } from "fs/promises";
+init_paths();
+init_paths_async();
+function emptyState(handle) {
+  return { myHandle: handle, lastHostUrl: null, graceCodes: [], history: [] };
+}
+
+class StateStore {
+  handleResolver;
+  constructor(handleResolver) {
+    this.handleResolver = handleResolver;
+  }
+  async read() {
+    const path = statePath();
+    const file = Bun.file(path);
+    if (!await file.exists())
+      return emptyState(this.handleResolver());
+    try {
+      const text = await file.text();
+      const parsed = JSON.parse(text);
+      return {
+        myHandle: typeof parsed.myHandle === "string" ? parsed.myHandle : this.handleResolver(),
+        lastHostUrl: typeof parsed.lastHostUrl === "string" ? parsed.lastHostUrl : null,
+        graceCodes: Array.isArray(parsed.graceCodes) ? parsed.graceCodes.filter((g) => typeof g === "object" && g !== null && typeof g.code === "string" && typeof g.handle === "string" && typeof g.validUntil === "number") : [],
+        history: Array.isArray(parsed.history) ? parsed.history.filter((h) => typeof h === "object" && h !== null && typeof h.ts === "number" && typeof h.event === "string") : []
+      };
+    } catch {
+      return emptyState(this.handleResolver());
+    }
+  }
+  async writeAtomic(state) {
+    await ensureStateDir();
+    const path = statePath();
+    const tmp = `${path}.tmp`;
+    await Bun.write(tmp, JSON.stringify(state, null, 2));
+    await rename(tmp, path);
+  }
+  prune(state) {
+    const now = Date.now();
+    return {
+      ...state,
+      graceCodes: state.graceCodes.filter((g) => g.validUntil > now)
+    };
+  }
+  pushHistory(state, entry) {
+    const history = [entry, ...state.history].slice(0, HISTORY_MAX);
+    return { ...state, history };
+  }
+  async recordHostStarted(handle, code) {
+    try {
+      const state = this.prune(await this.read());
+      const next = this.pushHistory({ ...state, myHandle: handle }, { ts: Date.now(), event: "host_started", handle, detail: code });
+      await this.writeAtomic(next);
+    } catch {}
+  }
+  async recordHostChanged(newHandle, newCode, oldCode, oldHandle, newUrl) {
+    try {
+      const state = this.prune(await this.read());
+      const validUntil = Date.now() + REJOIN_TTL_MS;
+      const graceCodes = [...state.graceCodes, { code: oldCode, handle: oldHandle, validUntil }];
+      const next = this.pushHistory({ ...state, myHandle: newHandle, graceCodes }, {
+        ts: Date.now(),
+        event: "host_changed",
+        handle: newHandle,
+        detail: `from:${oldHandle} newCode:${newCode} url:${newUrl}`
+      });
+      await this.writeAtomic(next);
+    } catch {}
+  }
+  async recordSessionEnded(handle, reason) {
+    try {
+      const state = this.prune(await this.read());
+      const next = this.pushHistory({ ...state, myHandle: handle }, { ts: Date.now(), event: "session_ended", handle, detail: reason });
+      await this.writeAtomic(next);
+    } catch {}
+  }
+  async recordGuestJoined(handle, hostUrl) {
+    try {
+      const state = this.prune(await this.read());
+      const next = this.pushHistory({ ...state, lastHostUrl: hostUrl }, { ts: Date.now(), event: "guest_joined", handle });
+      await this.writeAtomic(next);
+    } catch {}
+  }
+  async recordGuestPromoted(newHandle, newCode, oldCode, oldHandle) {
+    try {
+      const state = this.prune(await this.read());
+      const validUntil = Date.now() + REJOIN_TTL_MS;
+      const graceCodes = [...state.graceCodes, { code: oldCode, handle: oldHandle, validUntil }];
+      const next = this.pushHistory({ ...state, myHandle: newHandle, graceCodes }, {
+        ts: Date.now(),
+        event: "host_changed",
+        handle: newHandle,
+        detail: `promoted:old=${oldHandle} oldCode=${oldCode}`
+      });
+      await this.writeAtomic(next);
+    } catch {}
+  }
+}
+// src/env/resolve.ts
+function resolvePort() {
+  const raw = process.env["MP_PORT"];
+  if (!raw)
+    return DEFAULT_PORT;
+  const n = parseInt(raw, 10);
+  if (!Number.isFinite(n) || n < 1 || n > 65535)
+    return DEFAULT_PORT;
+  return n;
+}
+function resolveHost() {
+  const raw = process.env["MP_HOST"];
+  if (raw && raw.trim().length > 0)
+    return raw.trim();
+  return DEFAULT_HOST;
+}
+// src/server/host-server.ts
+async function startHostServer(opts) {
+  try {
+    const server = Bun.serve({
+      port: opts.port,
+      hostname: opts.host,
+      fetch(req, srv) {
+        const upgraded = srv.upgrade(req, {
+          data: { state: "awaiting_auth" }
+        });
+        if (upgraded)
+          return;
+        return new Response("multiplayer: websocket only", { status: 400 });
+      },
+      websocket: {
+        message(ws, raw) {
+          opts.handlers.onMessage(ws, raw);
+        },
+        close(ws) {
+          opts.handlers.onClose(ws);
+        }
+      }
+    });
+    return { ok: true, server };
+  } catch (e) {
+    const err = e;
+    if (err?.code === "EADDRINUSE") {
+      return { ok: false, reason: `port_${opts.port}_busy` };
+    }
+    return { ok: false, reason: `start_failed: ${e.message}` };
+  }
+}
+// src/role/peer-helpers.ts
+function peerListForBroadcast(peers) {
+  const out = [];
+  for (const p of peers.values()) {
+    if (p.handle === "__pending__")
+      continue;
+    out.push({ handle: p.handle, joinedAt: p.joinedAt });
+  }
+  out.sort((a, b) => a.joinedAt - b.joinedAt);
+  return out;
+}
+
+// src/role/host-role.ts
+class HostRole {
+  opts;
+  kind = "host";
+  server = null;
+  code = null;
+  handle;
+  peers = new Map;
+  volunteers = new Set;
+  graceCodes = new Set;
+  constructor(opts) {
+    this.opts = opts;
+    this.handle = opts.handle;
+  }
+  getCode() {
+    return this.code;
+  }
+  getHandle() {
+    return this.handle;
+  }
+  getPeers() {
+    return this.peers;
+  }
+  acceptVolunteer(handle) {
+    this.volunteers.add(handle);
+  }
+  isVolunteer(handle) {
+    return this.volunteers.has(handle);
+  }
+  takenHandles() {
+    const out = [];
+    if (this.handle)
+      out.push(this.handle);
+    for (const p of this.peers.values()) {
+      if (p.handle !== "__pending__")
+        out.push(p.handle);
+    }
+    return out;
+  }
+  broadcast(msg, except) {
+    for (const ws of this.peers.keys()) {
+      if (except && ws === except)
+        continue;
+      try {
+        ws.send(JSON.stringify(msg));
+      } catch {}
+    }
+  }
+  sendChat(text) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+      return { ok: false, reason: "empty" };
+    if (trimmed.length > 4000)
+      return { ok: false, reason: "too_long" };
+    if (!this.server)
+      return { ok: false, reason: "not_hosting" };
+    const ts = Date.now();
+    const msg = { type: "chat", from: this.handle, text: trimmed, ts };
+    this.broadcast(msg);
+    return { ok: true, ts, peers: this.peers.size };
+  }
+  sendTyping(state) {
+    if (!this.server)
+      return;
+    const msg = { type: "typing", from: this.handle, state };
+    this.broadcast(msg);
+  }
+  broadcastPeersUpdate() {
+    const peers = peerListForBroadcast(this.peers);
+    this.broadcast({ type: "peers_update", peers });
+    this.opts.onPeersChanged?.(peers);
+  }
+  findPeerWs(handle) {
+    for (const [ws, peer] of this.peers.entries()) {
+      if (peer.handle === handle)
+        return ws;
+    }
+    return null;
+  }
+  findPeerByHandle(handle) {
+    return this.findPeerWs(handle);
+  }
+  sendToPeer(ws, msg) {
+    try {
+      ws.send(JSON.stringify(msg));
+    } catch {}
+  }
+  async onPeerClose(ws) {
+    if (ws.data.state === "authenticated") {
+      const peer = ws.data.peer;
+      this.peers.delete(ws);
+      if (peer.handle !== "__pending__") {
+        this.volunteers.delete(peer.handle);
+        await this.opts.logger.log("info", "peer disconnected", { handle: peer.handle });
+        await this.opts.toaster.show(`peer disconnected (${peer.handle})`, "warning", "multiplayer");
+        this.broadcastPeersUpdate();
+      }
+    }
+  }
+  async onMessage(ws, raw) {
+    const text = typeof raw === "string" ? raw : raw.toString("utf8");
+    let msg;
+    try {
+      msg = JSON.parse(text);
+    } catch {
+      this.sendToPeer(ws, { type: "auth_fail", reason: "invalid_json" });
+      this.sendToPeer(ws, { type: "bye" });
+      try {
+        ws.close();
+      } catch {}
+      return;
+    }
+    if (ws.data.state === "awaiting_auth") {
+      if (msg.type !== "auth") {
+        this.sendToPeer(ws, { type: "auth_fail", reason: "expected_auth" });
+        this.sendToPeer(ws, { type: "bye" });
+        try {
+          ws.close();
+        } catch {}
+        return;
+      }
+      const code = msg.code;
+      if (!isValidCode(code)) {
+        this.sendToPeer(ws, { type: "auth_fail", reason: "invalid_code" });
+        this.sendToPeer(ws, { type: "bye" });
+        try {
+          ws.close();
+        } catch {}
+        await this.opts.toaster.show("guest sent an invalid code", "warning", "multiplayer");
+        return;
+      }
+      const normalized = code.toLowerCase();
+      const isCurrent = this.code !== null && normalized === this.code;
+      const isGrace = !isCurrent && this.graceCodes.has(normalized);
+      if (!isCurrent && !isGrace) {
+        this.sendToPeer(ws, { type: "auth_fail", reason: "unknown_code" });
+        this.sendToPeer(ws, { type: "bye" });
+        try {
+          ws.close();
+        } catch {}
+        return;
+      }
+      const peer = { handle: "__pending__", joinedAt: Date.now(), isVolunteer: false };
+      ws.data = { state: "authenticated", peer };
+      this.peers.set(ws, peer);
+      this.sendToPeer(ws, { type: "auth_ok", handle: this.handle ?? "host" });
+      this.sendToPeer(ws, {
+        type: "welcome",
+        handle: this.handle ?? "host",
+        peers: peerListForBroadcast(this.peers)
+      });
+      return;
+    }
+    if (msg.type === "hello") {
+      const requested = (msg.handle ?? "").toLowerCase().replace(/[^a-z0-9-]/g, "").slice(0, 16);
+      const peer = ws.data.peer;
+      const existing = this.takenHandles();
+      let assigned = requested;
+      if (existing.includes(assigned)) {
+        assigned = assignCollisionSuffix(requested, existing);
+      }
+      peer.handle = assigned;
+      await this.opts.logger.log("info", "peer connected", { guestHandle: assigned });
+      await this.opts.toaster.show(`\u2713 peer connected (${assigned})`, "success", "multiplayer");
+      this.broadcastPeersUpdate();
+      return;
+    }
+    if (msg.type === "volunteer") {
+      const peer = ws.data.peer;
+      if (peer.handle === "__pending__")
+        return;
+      peer.isVolunteer = true;
+      this.volunteers.add(peer.handle);
+      await this.opts.logger.log("info", "peer volunteered", { handle: peer.handle });
+      await this.opts.toaster.show(`volunteer accepted (${peer.handle})`, "info", "multiplayer");
+      return;
+    }
+    if (msg.type === "bye") {
+      return;
+    }
+    if (msg.type === "chat") {
+      const peer = ws.data.peer;
+      if (peer.handle === "__pending__")
+        return;
+      const m = msg;
+      const text2 = typeof m.text === "string" ? m.text : "";
+      if (text2.length === 0 || text2.length > 4000)
+        return;
+      const ts = typeof m.ts === "number" ? m.ts : Date.now();
+      const out = { type: "chat", from: peer.handle, text: text2, ts };
+      this.broadcast(out, ws);
+      this.opts.onChatReceived?.({ from: peer.handle, text: text2, ts });
+      await this.opts.logger.log("debug", "host: chat fan-out", {
+        from: peer.handle,
+        peers: this.peers.size - 1
+      });
+      return;
+    }
+    if (msg.type === "typing") {
+      const peer = ws.data.peer;
+      if (peer.handle === "__pending__")
+        return;
+      const state = msg.state === "stop" ? "stop" : "start";
+      const out = { type: "typing", from: peer.handle, state };
+      this.broadcast(out, ws);
+      this.opts.onTypingReceived?.(peer.handle, state);
+      return;
+    }
+    await this.opts.logger.log("warn", "host: unexpected message", { msg, state: ws.data.state });
+  }
+  addGraceCode(code) {
+    this.graceCodes.add(code.toLowerCase());
+  }
+  hasGraceCode(code) {
+    return this.graceCodes.has(code.toLowerCase());
+  }
+  async start() {
+    this.code = mintCode(this.handle);
+    const code = this.code;
+    const url = `ws://${this.opts.host}:${this.opts.port}`;
+    try {
+      const state = this.opts.state.prune(await this.opts.state.read());
+      for (const g of state.graceCodes) {
+        this.graceCodes.add(g.code);
+      }
+    } catch {}
+    const handlers = {
+      onMessage: (ws, raw) => {
+        this.onMessage(ws, raw);
+      },
+      onClose: (ws) => {
+        this.onPeerClose(ws);
+      }
+    };
+    const result = await startHostServer({ port: this.opts.port, host: this.opts.host, handlers });
+    if (!result.ok) {
+      this.code = null;
+      this.handle = "";
+      if (result.reason.startsWith("port_")) {
+        await this.opts.logger.log("warn", "host start failed: port in use", { port: this.opts.port });
+      } else {
+        await this.opts.logger.log("error", "host start failed", { error: result.reason });
+      }
+      return { ok: false, reason: result.reason };
+    }
+    this.server = result.server;
+    await this.opts.state.recordHostStarted(this.handle, code);
+    await this.opts.logger.log("info", "host started", {
+      handle: this.handle,
+      port: this.opts.port,
+      code,
+      url
+    });
+    await this.opts.toaster.show(`invite: ${code}`, "success", "multiplayer");
+    await this.opts.toaster.show(`hosting on ${url}`, "info", "multiplayer");
+    return { ok: true, code, url };
+  }
+  stop() {
+    if (this.server) {
+      try {
+        this.server.stop(true);
+      } catch {}
+      this.server = null;
+    }
+    this.code = null;
+    this.handle = "";
+    this.peers = new Map;
+    this.volunteers = new Set;
+  }
+  dispose() {
+    this.stop();
+  }
+}
+// src/role/guest-role.ts
+class GuestRole {
+  opts;
+  kind = "guest";
+  ws = null;
+  hostHandle = null;
+  myHandle = null;
+  hostUrl = null;
+  endedReason = null;
+  reconnectFn = null;
+  peerList = [];
+  constructor(opts) {
+    this.opts = opts;
+  }
+  getHostHandle() {
+    return this.hostHandle;
+  }
+  getMyHandle() {
+    return this.myHandle;
+  }
+  getHostUrl() {
+    return this.hostUrl;
+  }
+  getPeerList() {
+    return this.peerList;
+  }
+  isConnected() {
+    return this.ws !== null && this.ws.readyState === WebSocket.OPEN;
+  }
+  getWs() {
+    return this.ws;
+  }
+  getEndedReason() {
+    return this.endedReason;
+  }
+  async dial(code, mode) {
+    const wsUrl = `ws://${this.opts.host}:${this.opts.port}`;
+    const ws = new WebSocket(wsUrl);
+    this.ws = ws;
+    return await new Promise((resolve) => {
+      let resolved = false;
+      const finish = (result) => {
+        if (resolved)
+          return;
+        resolved = true;
+        resolve(result);
+      };
+      const timeout = setTimeout(() => {
+        try {
+          ws.close();
+        } catch {}
+        this.opts.toaster.show(`join timed out (no host at ${wsUrl})`, "error", "multiplayer");
+        this.opts.logger.log("warn", "guest dial timed out", { code, wsUrl });
+        finish({ ok: false, reason: "timeout" });
+      }, JOIN_TIMEOUT_MS);
+      ws.addEventListener("open", () => {
+        ws.send(JSON.stringify({ type: "auth", code: code.toLowerCase() }));
+      });
+      ws.addEventListener("message", async (e) => {
+        let msg;
+        try {
+          msg = JSON.parse(e.data);
+        } catch {
+          return;
+        }
+        if (msg.type === "auth_fail") {
+          clearTimeout(timeout);
+          try {
+            ws.close();
+          } catch {}
+          await this.opts.toaster.show(`join failed: ${msg.reason}`, "error", "multiplayer");
+          await this.opts.logger.log("info", "guest auth rejected", { reason: msg.reason });
+          finish({ ok: false, reason: msg.reason });
+          return;
+        }
+        if (msg.type === "auth_ok") {
+          return;
+        }
+        if (msg.type === "welcome") {
+          ws.send(JSON.stringify({ type: "hello", handle: this.opts.handle }));
+          this.ws = ws;
+          this.hostHandle = msg.handle;
+          this.hostUrl = wsUrl;
+          this.myHandle = this.opts.handle;
+          this.peerList = Array.isArray(msg.peers) ? msg.peers.filter((p) => p && typeof p.handle === "string" && typeof p.joinedAt === "number") : [];
+          clearTimeout(timeout);
+          await this.opts.logger.log("info", "guest joined", {
+            hostHandle: msg.handle,
+            requestedHandle: this.opts.handle,
+            mode
+          });
+          if (mode === "rejoin") {
+            await this.opts.toaster.show(`\u2713 rejoined as guest (${this.opts.handle})`, "success", "multiplayer");
+          } else {
+            await this.opts.toaster.show(`\u2713 connected to ${msg.handle}`, "success", "multiplayer");
+          }
+          await this.opts.state.recordGuestJoined(this.opts.handle, wsUrl);
+          finish({ ok: true, hostHandle: msg.handle, myHandle: this.opts.handle });
+          return;
+        }
+        if (msg.type === "peers_update") {
+          this.peerList = Array.isArray(msg.peers) ? msg.peers.filter((p) => p && typeof p.handle === "string" && typeof p.joinedAt === "number") : [];
+          this.opts.onPeersChanged?.(this.peerList);
+          return;
+        }
+        if (msg.type === "host_leaving") {
+          await this.opts.toaster.show(`host leaving in ${msg.grace_s}s`, "warning", "multiplayer");
+          return;
+        }
+        if (msg.type === "chat") {
+          const m = msg;
+          const text = typeof m.text === "string" ? m.text : "";
+          const from = typeof m.from === "string" ? m.from : this.hostHandle ?? "host";
+          const ts = typeof m.ts === "number" ? m.ts : Date.now();
+          const truncated = text.length > 200 ? text.slice(0, 200) + "\u2026" : text;
+          await this.opts.toaster.show(`${from}: ${truncated}`, "info", "chat");
+          await this.opts.logger.log("debug", "guest: chat received", { from, len: text.length });
+          this.opts.onChatReceived?.({ from, text, ts });
+          return;
+        }
+        if (msg.type === "typing") {
+          const m = msg;
+          const state = m.state === "stop" ? "stop" : "start";
+          const from = typeof m.from === "string" ? m.from : this.hostHandle ?? "host";
+          if (state === "start") {
+            await this.opts.toaster.show(`${from} is typing\u2026`, "info", "chat");
+          }
+          this.opts.onTypingReceived?.(from, state);
+          return;
+        }
+        if (msg.type === "leave_cancelled") {
+          await this.opts.toaster.show("host cancelled leave", "info", "multiplayer");
+          return;
+        }
+        if (msg.type === "transfer_to_me") {
+          if (!this.opts.promote)
+            return;
+          if (!this.ws)
+            return;
+          const oldWs = this.ws;
+          const oldUrl = this.hostUrl ?? "";
+          clearTimeout(timeout);
+          const result = await this.opts.promote(msg, oldWs, oldUrl);
+          if (result.ok) {
+            try {
+              oldWs.send(JSON.stringify({
+                type: "transfer_confirmed",
+                new_code: result.newCode,
+                new_url: result.newUrl
+              }));
+            } catch {}
+            try {
+              oldWs.close();
+            } catch {}
+          } else {
+            try {
+              oldWs.send(JSON.stringify({
+                type: "transfer_failed",
+                reason: result.reason
+              }));
+            } catch {}
+            try {
+              oldWs.close();
+            } catch {}
+            this.opts.ended?.(`promote_failed: ${result.reason}`);
+            this.ws = null;
+            this.hostHandle = null;
+            this.myHandle = null;
+            this.hostUrl = null;
+            await this.opts.toaster.show(`promotion failed: ${result.reason}`, "error", "multiplayer");
+          }
+          return;
+        }
+        if (msg.type === "transfer_start") {
+          clearTimeout(timeout);
+          if (this.ws) {
+            try {
+              this.ws.close();
+            } catch {}
+            this.ws = null;
+          }
+          const oldUrl = this.hostUrl ?? "";
+          const newHandle = typeof msg.new_handle === "string" ? msg.new_handle : "host";
+          const newUrl = typeof msg.new_url === "string" ? msg.new_url : oldUrl;
+          const newCode = typeof msg.new_code === "string" ? msg.new_code : "";
+          await this.opts.toaster.show(`transferring to ${newHandle} (${newUrl})`, "info", "multiplayer");
+          if (this.opts.reconnect && newCode) {
+            await this.opts.reconnect(newCode, newUrl);
+          }
+          return;
+        }
+        if (msg.type === "session_ended") {
+          clearTimeout(timeout);
+          if (this.ws) {
+            try {
+              this.ws.close();
+            } catch {}
+            this.ws = null;
+          }
+          this.hostHandle = null;
+          this.myHandle = null;
+          this.hostUrl = null;
+          const reason = typeof msg.reason === "string" ? msg.reason : "unknown";
+          this.endedReason = reason;
+          await this.opts.toaster.show(`session ended: ${reason}`, "warning", "multiplayer");
+          this.opts.ended?.(reason);
+          return;
+        }
+      });
+      ws.addEventListener("close", async () => {
+        if (resolved)
+          return;
+        clearTimeout(timeout);
+        await this.opts.toaster.show(`could not reach host at ${wsUrl}`, "error", "multiplayer");
+        await this.opts.logger.log("error", "guest ws closed before completion", { wsUrl });
+        finish({ ok: false, reason: "closed" });
+      });
+      ws.addEventListener("error", async () => {
+        if (resolved)
+          return;
+        clearTimeout(timeout);
+        await this.opts.toaster.show(`could not reach host at ${wsUrl}`, "error", "multiplayer");
+        await this.opts.logger.log("error", "guest ws error", { wsUrl });
+        finish({ ok: false, reason: "error" });
+      });
+    });
+  }
+  sendVolunteer() {
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify({ type: "volunteer" }));
+    }
+  }
+  sendChat(text) {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      return { ok: false, reason: "not_connected" };
+    }
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+      return { ok: false, reason: "empty" };
+    if (trimmed.length > 4000)
+      return { ok: false, reason: "too_long" };
+    const ts = Date.now();
+    const handle = this.myHandle ?? this.opts.handle;
+    this.ws.send(JSON.stringify({ type: "chat", from: handle, text: trimmed, ts }));
+    return { ok: true, ts };
+  }
+  sendTyping(state) {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
+      return;
+    const handle = this.myHandle ?? this.opts.handle;
+    this.ws.send(JSON.stringify({ type: "typing", from: handle, state }));
+  }
+  leave() {
+    if (this.ws) {
+      try {
+        this.ws.send(JSON.stringify({ type: "bye" }));
+      } catch {}
+      try {
+        this.ws.close();
+      } catch {}
+    }
+    this.ws = null;
+    this.hostHandle = null;
+    this.myHandle = null;
+    this.hostUrl = null;
+  }
+  dispose() {
+    this.leave();
+  }
+}
+// src/role/transfer-controller.ts
+function sendToPeer(ws, msg) {
+  try {
+    ws.send(JSON.stringify(msg));
+  } catch {}
+}
+
+class TransferController {
+  cb;
+  graceMs;
+  cascadeMs;
+  state = "none";
+  leaveTimer = null;
+  transferTimer = null;
+  queue = [];
+  snapshot = null;
+  constructor(cb, graceMs, cascadeMs) {
+    this.cb = cb;
+    this.graceMs = graceMs;
+    this.cascadeMs = cascadeMs;
+  }
+  getState() {
+    return this.state;
+  }
+  isPending() {
+    return this.state !== "none";
+  }
+  getPeers() {
+    return this.cb.getHostRole()?.getPeers() ?? this.cb.getHostPeers();
+  }
+  broadcast(msg, except) {
+    const hr = this.cb.getHostRole();
+    if (hr) {
+      hr.broadcast(msg, except);
+    }
+  }
+  findPeerWs(handle) {
+    for (const [ws, peer] of this.getPeers().entries()) {
+      if (peer.handle === handle)
+        return ws;
+    }
+    return null;
+  }
+  buildQueue() {
+    const all = Array.from(this.getPeers().values()).filter((p) => p.handle !== "__pending__");
+    const hr = this.cb.getHostRole();
+    const vols = all.filter((p) => hr ? hr.isVolunteer(p.handle) : p.isVolunteer).sort((a, b) => a.joinedAt - b.joinedAt);
+    const nonVols = all.filter((p) => hr ? !hr.isVolunteer(p.handle) : !p.isVolunteer).sort((a, b) => a.joinedAt - b.joinedAt);
+    const seen = new Set;
+    const ordered = [];
+    for (const p of [...vols, ...nonVols]) {
+      if (seen.has(p.handle))
+        continue;
+      seen.add(p.handle);
+      ordered.push(p);
+    }
+    return ordered.map((p) => ({ handle: p.handle, code: this.cb.mintCode(p.handle) }));
+  }
+  clearTimers() {
+    if (this.leaveTimer) {
+      clearTimeout(this.leaveTimer);
+      this.leaveTimer = null;
+    }
+    if (this.transferTimer) {
+      clearTimeout(this.transferTimer);
+      this.transferTimer = null;
+    }
+  }
+  async startLeave() {
+    if (this.state !== "none")
+      return;
+    const peers = peerListForBroadcast(this.getPeers());
+    if (peers.length === 0) {
+      await this.cb.log("info", "host leaving with no peers; ending session");
+      this.cb.stopHost();
+      return;
+    }
+    this.state = "pending";
+    this.queue = this.buildQueue();
+    this.snapshot = {
+      code: this.cb.getHostCode() ?? "",
+      handle: this.cb.getHostHandle() ?? "host",
+      peers
+    };
+    this.broadcast({ type: "host_leaving", grace_s: this.graceMs / 1000 });
+    await this.cb.log("info", "host leaving; grace started", {
+      grace_s: this.graceMs / 1000,
+      peers: peers.length
+    });
+    await this.cb.toast(`leaving in ${this.graceMs / 1000}s \u2014 auto-transfer pending`, "info", "multiplayer");
+    this.leaveTimer = setTimeout(() => {
+      this.onGraceExpired();
+    }, this.graceMs);
+  }
+  async cancelLeave() {
+    if (this.state !== "pending")
+      return;
+    this.clearTimers();
+    this.state = "none";
+    this.queue = [];
+    this.snapshot = null;
+    this.broadcast({ type: "leave_cancelled" });
+    await this.cb.log("info", "host leave cancelled");
+    await this.cb.toast("leave cancelled \u2014 staying as host", "info", "multiplayer");
+  }
+  async onGraceExpired() {
+    if (this.state !== "pending")
+      return;
+    this.leaveTimer = null;
+    if (this.queue.length === 0) {
+      this.broadcast({ type: "session_ended", reason: "no_peers" });
+      await this.cb.recordSessionEnded(this.cb.getHostHandle() ?? "host", "no_peers");
+      this.cb.stopHost();
+      this.state = "none";
+      await this.cb.toast("session ended (no successors)", "warning", "multiplayer");
+      return;
+    }
+    await this.tryNextSuccessor();
+  }
+  async tryNextSuccessor() {
+    if (this.state !== "pending")
+      return;
+    const next = this.queue.shift();
+    if (!next) {
+      this.broadcast({ type: "session_ended", reason: "no_reachable_successor" });
+      await this.cb.recordSessionEnded(this.cb.getHostHandle() ?? "host", "no_reachable_successor");
+      this.cb.stopHost();
+      this.state = "none";
+      await this.cb.toast("session ended: no reachable successor", "error", "multiplayer");
+      return;
+    }
+    this.state = "transferring";
+    const successorWs = this.findPeerWs(next.handle);
+    if (!successorWs) {
+      this.state = "pending";
+      await this.onTransferFailed("successor_disconnected");
+      return;
+    }
+    const snap = this.snapshot;
+    if (!snap) {
+      this.state = "pending";
+      await this.onTransferFailed("no_snapshot");
+      return;
+    }
+    sendToPeer(successorWs, {
+      type: "transfer_to_me",
+      new_handle: next.handle,
+      old_code: snap.code,
+      old_handle: snap.handle,
+      peers: snap.peers.filter((p) => p.handle !== next.handle)
+    });
+    await this.cb.log("info", "transfer_to_me sent", { successor: next.handle });
+    await this.cb.toast(`transferring to ${next.handle}...`, "info", "multiplayer");
+    this.transferTimer = setTimeout(() => {
+      this.onTransferFailed("timeout");
+    }, this.cascadeMs);
+  }
+  async onTransferConfirmed(successorWs, newCode, newUrl) {
+    if (this.transferTimer) {
+      clearTimeout(this.transferTimer);
+      this.transferTimer = null;
+    }
+    const snap = this.snapshot;
+    if (!snap)
+      return;
+    await this.cb.log("info", "transfer confirmed by successor", { newCode, newUrl });
+    await this.cb.toast(`\u2713 transferred to ${newUrl.replace(/^ws:\/\//, "")}`, "success", "multiplayer");
+    await this.cb.recordHostChanged(newCode && newCode.startsWith("mp-") ? newCode.split("-")[1] ?? "host" : "host", newCode, snap.code, snap.handle, newUrl);
+    this.broadcast({
+      type: "transfer_start",
+      new_code: newCode,
+      new_url: newUrl,
+      new_handle: newCode && newCode.startsWith("mp-") ? newCode.split("-")[1] ?? "host" : "host"
+    }, successorWs);
+    this.cb.stopHost();
+    this.state = "none";
+    this.snapshot = null;
+    this.queue = [];
+  }
+  async onTransferFailed(reason) {
+    if (this.transferTimer) {
+      clearTimeout(this.transferTimer);
+      this.transferTimer = null;
+    }
+    await this.cb.log("warn", "transfer failed; cascading", { reason });
+    await this.cb.toast(`transfer failed (${reason}); trying next successor`, "warning", "multiplayer");
+    this.state = "pending";
+    await this.tryNextSuccessor();
+  }
+  reset() {
+    this.clearTimers();
+    this.state = "none";
+    this.queue = [];
+    this.snapshot = null;
+  }
+}
+// src/role/role-state.ts
+class IdleRole {
+  _deps;
+  kind = "idle";
+  constructor(_deps) {
+    this._deps = _deps;
+  }
+  dispose() {}
+}
+// src/companion/socket-server.ts
+import { createServer } from "net";
+import { chmodSync, existsSync as existsSync2, unlinkSync } from "fs";
+import { writeFile, unlink } from "fs/promises";
+import { randomBytes } from "crypto";
+
+// shared/protocol.ts
+var IPC_VERSION = "1.0.0";
+var IPC_MAX_MESSAGE_BYTES = 64 * 1024;
+var MAX_TEXT = 4000;
+var MAX_HANDLE = 16;
+var HANDLE_RE2 = /^[a-z0-9-]{1,16}$/;
+var CODE_RE2 = /^mp-([a-z0-9-]{1,16})-([a-z0-9]{4})-([a-z0-9]{4})$/;
+var URL_RE = /^wss?:\/\/.+/;
+var VARIANT_SET = new Set(["info", "success", "warning", "error"]);
+var ROLE_SET = new Set(["host", "guest", "idle"]);
+var LEAVING_SET = new Set(["none", "pending", "transferring"]);
+var TYPING_SET = new Set(["start", "stop"]);
+function isPeer(x) {
+  if (typeof x !== "object" || x === null)
+    return false;
+  const p = x;
+  return typeof p.handle === "string" && HANDLE_RE2.test(p.handle) && typeof p.joinedAt === "number";
+}
+function isState(x) {
+  if (typeof x !== "object" || x === null)
+    return false;
+  const s = x;
+  if (typeof s.role !== "string" || !ROLE_SET.has(s.role))
+    return false;
+  if (typeof s.handle !== "string" || s.handle.length === 0 || s.handle.length > MAX_HANDLE)
+    return false;
+  if (s.code !== null && !(typeof s.code === "string" && CODE_RE2.test(s.code)))
+    return false;
+  if (typeof s.port !== "number" || s.port < 1 || s.port > 65535)
+    return false;
+  if (s.hostHandle !== null && !(typeof s.hostHandle === "string" && HANDLE_RE2.test(s.hostHandle)))
+    return false;
+  if (!Array.isArray(s.peers) || !s.peers.every(isPeer))
+    return false;
+  if (typeof s.leaving !== "string" || !LEAVING_SET.has(s.leaving))
+    return false;
+  if (s.grace_s !== null && typeof s.grace_s !== "number")
+    return false;
+  return true;
+}
+function isPluginToCompanion(x) {
+  if (typeof x !== "object" || x === null)
+    return false;
+  const m = x;
+  if (typeof m.type !== "string")
+    return false;
+  switch (m.type) {
+    case "init":
+      return isState(x.state);
+    case "peers_update":
+      return Array.isArray(x.peers) && x.peers.every(isPeer);
+    case "chat": {
+      const v = x;
+      return typeof v.from === "string" && v.from.length > 0 && v.from.length <= MAX_HANDLE && typeof v.text === "string" && v.text.length > 0 && v.text.length <= MAX_TEXT && typeof v.ts === "number" && typeof v.mine === "boolean";
+    }
+    case "typing": {
+      const v = x;
+      return typeof v.from === "string" && v.from.length > 0 && v.from.length <= MAX_HANDLE && typeof v.state === "string" && TYPING_SET.has(v.state);
+    }
+    case "host_leaving":
+      return typeof x.grace_s === "number";
+    case "leave_cancelled":
+      return true;
+    case "session_ended":
+      return typeof x.reason === "string";
+    case "transfer_start": {
+      const v = x;
+      return typeof v.new_code === "string" && CODE_RE2.test(v.new_code) && typeof v.new_url === "string" && URL_RE.test(v.new_url) && typeof v.new_handle === "string" && HANDLE_RE2.test(v.new_handle);
+    }
+    case "role_change":
+      return isState(x.state);
+    case "toast": {
+      const v = x;
+      return typeof v.message === "string" && v.message.length > 0 && v.message.length <= MAX_TEXT && typeof v.variant === "string" && VARIANT_SET.has(v.variant) && (v.title === undefined || typeof v.title === "string");
+    }
+    case "goodbye":
+      return typeof x.reason === "string";
+    default:
+      return false;
+  }
+}
+function isCompanionToPlugin(x) {
+  if (typeof x !== "object" || x === null)
+    return false;
+  const m = x;
+  if (typeof m.type !== "string")
+    return false;
+  switch (m.type) {
+    case "hello": {
+      const v = x;
+      return typeof v.version === "string" && v.version.length > 0 && v.version.length <= 32 && typeof v.token === "string" && v.token.length > 0 && v.token.length <= 256;
+    }
+    case "chat": {
+      const v = x;
+      return typeof v.text === "string" && v.text.length > 0 && v.text.length <= MAX_TEXT;
+    }
+    case "typing": {
+      const v = x;
+      return typeof v.state === "string" && TYPING_SET.has(v.state);
+    }
+    case "command": {
+      const v = x;
+      return typeof v.name === "string" && v.name.length > 0 && v.name.length <= 32 && Array.isArray(v.args) && v.args.every((a) => typeof a === "string" && a.length <= MAX_TEXT);
+    }
+    case "leave":
+    case "ping":
+    case "goodbye":
+      return true;
+    default:
+      return false;
+  }
+}
+// shared/codec.ts
+function makeLineParser(from) {
+  return (raw, onMessage, onError) => {
+    const line = raw.trim();
+    if (line.length === 0)
+      return;
+    if (line.length > IPC_MAX_MESSAGE_BYTES) {
+      onError?.(new Error(`message too large (${line.length} > ${IPC_MAX_MESSAGE_BYTES})`));
+      return;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch (e) {
+      onError?.(e);
+      return;
+    }
+    if (from === "plugin" && isPluginToCompanion(parsed)) {
+      onMessage(parsed);
+      return;
+    }
+    if (from === "companion" && isCompanionToPlugin(parsed)) {
+      onMessage(parsed);
+      return;
+    }
+    onError?.(new Error(`invalid ${from} message: ${line.slice(0, 80)}`));
+  };
+}
+function encode(msg) {
+  return JSON.stringify(msg) + `
+`;
+}
+function splitLines(chunk) {
+  const parts = chunk.split(`
+`);
+  const rest = parts.pop() ?? "";
+  return { lines: parts, rest };
+}
+// src/companion/socket-server.ts
+var HELLO_TIMEOUT_MS = 3000;
+
+class CompanionSocketServer {
+  opts;
+  server = null;
+  clients = new Set;
+  expectedToken;
+  helloTimers = new WeakMap;
+  lineParser;
+  encodeFn;
+  stopped = false;
+  constructor(opts) {
+    this.opts = opts;
+    this.expectedToken = opts.token ?? CompanionSocketServer.generateToken();
+    this.lineParser = opts.lineParser ?? makeLineParser("companion");
+    this.encodeFn = opts.encodeFn ?? encode;
+  }
+  static generateToken() {
+    return randomBytes(24).toString("hex");
+  }
+  getToken() {
+    return this.expectedToken;
+  }
+  getSocketPath() {
+    return this.opts.socketPath;
+  }
+  isRunning() {
+    return this.server !== null && !this.stopped;
+  }
+  clientCount() {
+    return this.clients.size;
+  }
+  async start() {
+    if (this.server)
+      return;
+    this.stopped = false;
+    const dir = this.opts.socketPath.replace(/\/[^/]+$/, "");
+    if (dir && dir !== this.opts.socketPath) {
+      const { mkdir: mkdir2 } = await import("fs/promises");
+      await mkdir2(dir, { recursive: true });
+    }
+    if (existsSync2(this.opts.socketPath)) {
+      try {
+        unlinkSync(this.opts.socketPath);
+      } catch {}
+    }
+    if (existsSync2(this.opts.tokenPath)) {
+      try {
+        unlinkSync(this.opts.tokenPath);
+      } catch {}
+    }
+    await writeFile(this.opts.tokenPath, this.expectedToken, { mode: 384 });
+    try {
+      chmodSync(this.opts.tokenPath, 384);
+    } catch {}
+    await new Promise((resolve, reject) => {
+      const server = createServer((socket) => this.onConnection(socket));
+      server.on("error", (e) => {
+        this.opts.handlers.onError(e);
+        reject(e);
+      });
+      server.listen(this.opts.socketPath, () => {
+        try {
+          chmodSync(this.opts.socketPath, 384);
+        } catch {}
+        this.server = server;
+        resolve();
+      });
+    });
+  }
+  async stop() {
+    if (this.stopped)
+      return;
+    this.stopped = true;
+    for (const c of this.clients) {
+      try {
+        c.socket.end();
+      } catch {}
+      try {
+        c.socket.destroy();
+      } catch {}
+    }
+    this.clients.clear();
+    if (this.server) {
+      const s = this.server;
+      this.server = null;
+      await new Promise((resolve) => {
+        s.close(() => resolve());
+      });
+    }
+    if (existsSync2(this.opts.socketPath)) {
+      try {
+        await unlink(this.opts.socketPath);
+      } catch {}
+    }
+    if (existsSync2(this.opts.tokenPath)) {
+      try {
+        await unlink(this.opts.tokenPath);
+      } catch {}
+    }
+  }
+  pushState(state) {
+    this.broadcast({ type: "init", state });
+  }
+  pushRoleChange(state) {
+    this.broadcast({ type: "role_change", state });
+  }
+  pushPeersUpdate(peers) {
+    this.broadcast({ type: "peers_update", peers });
+  }
+  pushChat(msg) {
+    this.broadcast({ type: "chat", ...msg });
+  }
+  pushTyping(from, state) {
+    this.broadcast({ type: "typing", from, state });
+  }
+  pushHostLeaving(grace_s) {
+    this.broadcast({ type: "host_leaving", grace_s });
+  }
+  pushLeaveCancelled() {
+    this.broadcast({ type: "leave_cancelled" });
+  }
+  pushSessionEnded(reason) {
+    this.broadcast({ type: "session_ended", reason });
+  }
+  pushTransferStart(new_code, new_url, new_handle) {
+    this.broadcast({ type: "transfer_start", new_code, new_url, new_handle });
+  }
+  pushToast(message, variant, title) {
+    const msg = title ? { type: "toast", message, variant, title } : { type: "toast", message, variant };
+    this.broadcast(msg);
+  }
+  pushGoodbye(reason) {
+    this.broadcast({ type: "goodbye", reason });
+  }
+  broadcast(msg) {
+    if (!this.server)
+      return;
+    const payload = this.encodeFn(msg);
+    for (const c of this.clients) {
+      if (!c.authenticated)
+        continue;
+      try {
+        c.socket.write(payload);
+      } catch {}
+    }
+  }
+  onConnection(socket) {
+    if (this.stopped) {
+      try {
+        socket.destroy();
+      } catch {}
+      return;
+    }
+    const conn = { socket, buffer: "", authenticated: false, greeted: false };
+    this.clients.add(conn);
+    const timer = setTimeout(() => {
+      this.opts.handlers.onAuthFail("hello_timeout");
+      try {
+        socket.destroy();
+      } catch {}
+    }, HELLO_TIMEOUT_MS);
+    this.helloTimers.set(socket, timer);
+    socket.on("data", (chunk) => {
+      if (this.stopped)
+        return;
+      const buf = conn.buffer + chunk.toString("utf8");
+      if (buf.length > IPC_MAX_MESSAGE_BYTES * 4) {
+        this.opts.handlers.onAuthFail("buffer_overflow");
+        try {
+          socket.destroy();
+        } catch {}
+        return;
+      }
+      const { lines, rest } = splitLines(buf);
+      conn.buffer = rest;
+      for (const line of lines) {
+        this.lineParser(line, (m) => this.onCompanionMessage(conn, m), (e) => this.opts.handlers.onParseError(e));
+      }
+    });
+    socket.on("close", () => {
+      const t = this.helloTimers.get(socket);
+      if (t) {
+        clearTimeout(t);
+        this.helloTimers.delete(socket);
+      }
+      this.clients.delete(conn);
+      if (conn.authenticated) {
+        try {
+          this.opts.handlers.onDisconnect();
+        } catch {}
+      }
+    });
+    socket.on("error", (e) => {
+      this.opts.handlers.onError(e);
+    });
+  }
+  onCompanionMessage(conn, msg) {
+    if (msg.type !== "hello" && msg.type !== "chat" && msg.type !== "typing" && msg.type !== "command" && msg.type !== "leave" && msg.type !== "ping" && msg.type !== "goodbye") {
+      return;
+    }
+    if (!conn.authenticated) {
+      if (msg.type === "hello") {
+        const t = this.helloTimers.get(conn.socket);
+        if (t) {
+          clearTimeout(t);
+          this.helloTimers.delete(conn.socket);
+        }
+        if (msg.token !== this.expectedToken) {
+          this.opts.handlers.onAuthFail("bad_token");
+          try {
+            conn.socket.destroy();
+          } catch {}
+          return;
+        }
+        if (msg.version !== IPC_VERSION) {
+          this.opts.handlers.onAuthFail(`version_mismatch:${msg.version}`);
+          try {
+            conn.socket.destroy();
+          } catch {}
+          return;
+        }
+        conn.authenticated = true;
+        try {
+          this.opts.handlers.onConnect();
+        } catch {}
+        conn.greeted = true;
+      } else {
+        this.opts.handlers.onAuthFail("not_hello");
+        try {
+          conn.socket.destroy();
+        } catch {}
+      }
+      return;
+    }
+    switch (msg.type) {
+      case "chat":
+        try {
+          this.opts.handlers.onChat(msg.text);
+        } catch {}
+        return;
+      case "typing":
+        try {
+          this.opts.handlers.onTyping(msg.state);
+        } catch {}
+        return;
+      case "command":
+        try {
+          this.opts.handlers.onCommand(msg.name, msg.args);
+        } catch {}
+        return;
+      case "leave":
+        try {
+          this.opts.handlers.onLeave();
+        } catch {}
+        return;
+      case "ping":
+        return;
+      case "goodbye":
+        try {
+          conn.socket.end();
+        } catch {}
+        return;
+    }
+  }
+}
+
+// src/companion/paths.ts
+init_paths();
+import { join as join2 } from "path";
+function companionSocketPath() {
+  return join2(stateDir(), "companion.sock");
+}
+function companionTokenPath() {
+  return join2(stateDir(), "companion.token");
+}
+
+// src/companion/state-pusher.ts
+function getPeersForHost(plugin) {
+  const peers = plugin.hostRole?.getPeers() ?? plugin.hostPeers;
+  return peerListForBroadcast(peers);
+}
+function getPeersForGuest(plugin) {
+  const list = plugin.guestRole?.getPeerList() ?? [];
+  const hostHandle = plugin.guestRole?.getHostHandle() ?? null;
+  if (hostHandle) {
+    const hostEntry = { handle: hostHandle, joinedAt: 0 };
+    const withoutHost = list.filter((p) => p.handle !== hostHandle);
+    return [hostEntry, ...withoutHost];
+  }
+  return list;
+}
+function leavingState(plugin) {
+  return plugin.tc?.getState() ?? "none";
+}
+function computeIpcState(plugin) {
+  const handle = plugin.resolveHandle();
+  const port = plugin.port;
+  if (plugin.role === "host") {
+    return {
+      role: "host",
+      handle,
+      code: plugin.hostRole?.getCode() ?? plugin.hostCode,
+      port,
+      hostHandle: handle,
+      peers: getPeersForHost(plugin),
+      leaving: leavingState(plugin),
+      grace_s: plugin.tc?.isPending() ? GRACE_S : null
+    };
+  }
+  if (plugin.role === "guest") {
+    return {
+      role: "guest",
+      handle,
+      code: null,
+      port,
+      hostHandle: plugin.guestRole?.getHostHandle() ?? null,
+      peers: getPeersForGuest(plugin),
+      leaving: "none",
+      grace_s: null
+    };
+  }
+  return {
+    role: "idle",
+    handle,
+    code: null,
+    port,
+    hostHandle: null,
+    peers: [],
+    leaving: "none",
+    grace_s: null
+  };
+}
+function pushIpcState(plugin, server) {
+  if (!server || !server.isRunning())
+    return;
+  if (server.clientCount() === 0)
+    return;
+  server.pushState(computeIpcState(plugin));
+}
+function pushRoleChange(plugin, server) {
+  if (!server || !server.isRunning())
+    return;
+  if (server.clientCount() === 0)
+    return;
+  server.pushRoleChange(computeIpcState(plugin));
+}
+function pushPeersUpdate(plugin, server) {
+  if (!server || !server.isRunning())
+    return;
+  if (server.clientCount() === 0)
+    return;
+  if (plugin.role === "host") {
+    server.pushPeersUpdate(getPeersForHost(plugin));
+  } else if (plugin.role === "guest") {
+    server.pushPeersUpdate(getPeersForGuest(plugin));
+  }
+}
+
+// src/plugin.ts
+class MultiplayerPlugin {
+  toaster;
+  logger;
+  store;
+  role = "idle";
+  roleState;
+  port = DEFAULT_PORT;
+  hostAddr = `${DEFAULT_HOST}:${DEFAULT_PORT}`;
+  hostServer = null;
+  hostCode = null;
+  hostHandle = null;
+  hostPeers = new Map;
+  volunteers = new Set;
+  hostRole = null;
+  guestRole = null;
+  guestWs = null;
+  guestHostHandle = null;
+  guestMyHandle = null;
+  guestHostUrl = null;
+  myResolvedHandle = null;
+  tc = null;
+  companionServer = null;
+  companionDisabled = false;
+  constructor(toaster, logger, store) {
+    this.toaster = toaster;
+    this.logger = logger;
+    this.store = store;
+    this.roleState = new IdleRole(this.deps);
+  }
+  get deps() {
+    return {
+      handle: this.resolveHandle(),
+      port: this.port,
+      hostAddr: this.hostAddr,
+      store: this.store,
+      toaster: this.toaster,
+      logger: this.logger
+    };
+  }
+  resolveHandle() {
+    if (this.myResolvedHandle)
+      return this.myResolvedHandle;
+    const envHandle = process.env["MP_HANDLE"];
+    if (envHandle) {
+      const norm = normalizeHandle(envHandle);
+      if (norm.length > 0 && isValidHandle(norm)) {
+        this.myResolvedHandle = norm;
+        return norm;
+      }
+    }
+    const persisted = readHandleFileSync();
+    if (persisted) {
+      this.myResolvedHandle = persisted;
+      return persisted;
+    }
+    const fallback = normalizeHandle(osUser()) || "anon";
+    this.myResolvedHandle = fallback;
+    return fallback;
+  }
+  takenHandles() {
+    const out = [];
+    if (this.hostHandle)
+      out.push(this.hostHandle);
+    for (const p of (this.hostRole?.getPeers() ?? this.hostPeers).values()) {
+      if (p.handle !== "__pending__")
+        out.push(p.handle);
+    }
+    return out;
+  }
+  sendToPeer(ws, msg) {
+    try {
+      ws.send(JSON.stringify(msg));
+    } catch {}
+  }
+  findPeerWs(handle) {
+    const peers = this.hostRole?.getPeers() ?? this.hostPeers;
+    for (const [ws, peer] of peers.entries()) {
+      if (peer.handle === handle)
+        return ws;
+    }
+    return null;
+  }
+  resetToIdleRole() {
+    this.role = "idle";
+    this.roleState = new IdleRole(this.deps);
+  }
+  setRoleHost(hr) {
+    this.role = "host";
+    this.roleState = hr;
+  }
+  setRoleGuest(gr) {
+    this.role = "guest";
+    this.roleState = gr;
+  }
+  cleanup() {
+    this.tc?.reset();
+    this.volunteers = new Set;
+    if (this.hostRole) {
+      this.hostRole.stop();
+      this.hostRole = null;
+    }
+    try {
+      this.hostServer?.stop(true);
+    } catch {}
+    this.hostServer = null;
+    this.hostCode = null;
+    this.hostHandle = null;
+    this.hostPeers = new Map;
+    try {
+      if (this.guestWs && this.guestWs.readyState === WebSocket.OPEN) {
+        try {
+          this.guestWs.send(JSON.stringify({ type: "bye" }));
+        } catch {}
+        this.guestWs.close();
+      }
+    } catch {}
+    this.guestRole?.leave();
+    this.guestRole = null;
+    this.guestWs = null;
+    this.guestHostHandle = null;
+    this.guestMyHandle = null;
+    this.guestHostUrl = null;
+    this.resetToIdleRole();
+  }
+  async startCompanionServer() {
+    if (this.companionServer && this.companionServer.isRunning()) {
+      return this.companionServer;
+    }
+    const server = new CompanionSocketServer({
+      socketPath: companionSocketPath(),
+      tokenPath: companionTokenPath(),
+      handlers: {
+        onChat: (text) => {
+          this.handleCompanionChat(text);
+        },
+        onTyping: (state) => {
+          if (this.role === "host")
+            this.hostRole?.sendTyping(state);
+          if (this.role === "guest")
+            this.guestRole?.sendTyping(state);
+        },
+        onCommand: (name, args) => {
+          this.handleCompanionCommand(name, args);
+        },
+        onLeave: () => {
+          this.mpLeave();
+        },
+        onConnect: () => {
+          if (this.companionServer) {
+            this.companionServer.pushState(computeIpcState(this));
+          }
+        },
+        onDisconnect: () => {},
+        onAuthFail: (reason) => {
+          this.logger.log("warn", "companion auth failed", { reason });
+        },
+        onParseError: (e) => {
+          this.logger.log("warn", "companion parse error", { err: e.message });
+        },
+        onError: (e) => {
+          this.logger.log("error", "companion server error", { err: e.message });
+        }
+      }
+    });
+    try {
+      await server.start();
+    } catch (e) {
+      await this.logger.log("warn", "companion server failed to start", { err: e.message });
+      this.companionDisabled = true;
+      return null;
+    }
+    this.companionServer = server;
+    return server;
+  }
+  async stopCompanionServer() {
+    if (this.companionServer) {
+      this.companionServer.pushGoodbye("shutdown");
+      await this.companionServer.stop();
+      this.companionServer = null;
+    }
+  }
+  async handleCompanionChat(text) {
+    await this.mpChat(text);
+    if (this.companionServer) {
+      const me = this.resolveHandle();
+      this.companionServer.pushChat({
+        from: me,
+        text,
+        ts: Date.now(),
+        mine: true
+      });
+    }
+  }
+  async handleCompanionCommand(name, args) {
+    switch (name) {
+      case "join":
+        if (args[0])
+          await this.mpJoin(args[0]);
+        return;
+      case "leave":
+        await this.mpLeave();
+        return;
+      case "cancel-leave":
+        await this.mpCancelLeave();
+        return;
+      case "volunteer":
+        this.mpVolunteer();
+        return;
+      case "code":
+        this.companionServer?.pushToast(this.mpCode(), "info", "code");
+        return;
+      case "status":
+        this.companionServer?.pushToast(this.mpStatus(), "info", "status");
+        return;
+      case "intent":
+        await this.logger.log("warn", "intent not yet implemented (Phase 04)");
+        this.companionServer?.pushToast("intents are coming in Phase 04", "info", "intent");
+        return;
+      case "history":
+        this.companionServer?.pushToast("/mp history is coming in Phase 07", "info", "history");
+        return;
+      default:
+        this.companionServer?.pushToast(`unknown command: ${name}`, "warning", "multiplayer");
+    }
+  }
+  pushStateToCompanions() {
+    pushIpcState(this, this.companionServer);
+  }
+  pushRoleChangeToCompanions() {
+    pushRoleChange(this, this.companionServer);
+  }
+  pushPeersToCompanions() {
+    pushPeersUpdate(this, this.companionServer);
+  }
+  async mpHost() {
+    const handle = this.resolveHandle();
+    const bindPort = resolvePort();
+    const bindHost = resolveHost();
+    const result = await this.startHost(handle, bindPort, bindHost);
+    if (result.ok) {
+      this.pushRoleChangeToCompanions();
+      return `Hosting on ${result.url}
+Invite code: ${result.code}
+Share the code with your peer. They run: mp_join ${result.code}
+(mp_status shows the current peers and leaving state.)`;
+    }
+    if (result.reason.startsWith("port_") && result.reason.endsWith("_busy")) {
+      const busyPort = result.reason.replace(/^port_/, "").replace(/_busy$/, "");
+      return `Port ${busyPort} is already in use. Try a different port by setting MP_PORT before launching opencode, e.g.
+  MP_PORT=${busyPort === "7332" ? "8332" : String(Number(busyPort) + 1)} opencode`;
+    }
+    return `Could not start host: ${result.reason}`;
+  }
+  async startHost(handle, bindPort, bindHost) {
+    if (this.roleState.kind !== "idle") {
+      return { ok: false, reason: `not_idle (currently ${this.roleState.kind})` };
+    }
+    const hr = new HostRole({
+      port: bindPort,
+      host: bindHost,
+      handle,
+      state: this.store,
+      toaster: this.toaster,
+      logger: this.logger,
+      onPeersChanged: () => this.pushPeersToCompanions(),
+      onChatReceived: (msg) => {
+        if (this.companionServer) {
+          this.companionServer.pushChat({ ...msg, mine: false });
+        }
+      },
+      onTypingReceived: (from, state) => {
+        if (this.companionServer) {
+          this.companionServer.pushTyping(from, state);
+        }
+      }
+    });
+    const result = await hr.start();
+    if (!result.ok) {
+      return result;
+    }
+    this.hostRole = hr;
+    this.hostServer = null;
+    this.hostCode = result.code;
+    this.hostHandle = handle;
+    this.setRoleHost(hr);
+    this.port = bindPort;
+    this.hostAddr = `${bindHost}:${bindPort}`;
+    return result;
+  }
+  broadcastPeersUpdate() {
+    if (this.hostRole) {
+      const peers = peerListForBroadcast(this.hostRole.getPeers());
+      this.hostRole.broadcast({ type: "peers_update", peers });
+    }
+    this.pushPeersToCompanions();
+  }
+  async handleHostMessage(ws, raw) {
+    const text = typeof raw === "string" ? raw : raw.toString("utf8");
+    let msg;
+    try {
+      msg = JSON.parse(text);
+    } catch {
+      this.sendToPeer(ws, { type: "auth_fail", reason: "invalid_json" });
+      this.sendToPeer(ws, { type: "bye" });
+      try {
+        ws.close();
+      } catch {}
+      return;
+    }
+    if (ws.data.state === "awaiting_auth") {
+      if (msg.type !== "auth") {
+        this.sendToPeer(ws, { type: "auth_fail", reason: "expected_auth" });
+        this.sendToPeer(ws, { type: "bye" });
+        try {
+          ws.close();
+        } catch {}
+        return;
+      }
+      if (!isValidCode(msg.code)) {
+        this.sendToPeer(ws, { type: "auth_fail", reason: "invalid_code" });
+        this.sendToPeer(ws, { type: "bye" });
+        try {
+          ws.close();
+        } catch {}
+        await this.toaster.show("guest sent an invalid code", "warning", "multiplayer");
+        return;
+      }
+      const normalized = msg.code.toLowerCase();
+      const isCurrent = this.hostCode !== null && normalized === this.hostCode;
+      const isGrace = !isCurrent;
+      if (!isCurrent && !isGrace) {
+        this.sendToPeer(ws, { type: "auth_fail", reason: "unknown_code" });
+        this.sendToPeer(ws, { type: "bye" });
+        try {
+          ws.close();
+        } catch {}
+        return;
+      }
+      const peer = { handle: "__pending__", joinedAt: Date.now(), isVolunteer: false };
+      ws.data = { state: "authenticated", peer };
+      this.hostPeers.set(ws, peer);
+      this.sendToPeer(ws, { type: "auth_ok", handle: this.hostHandle ?? "host" });
+      this.sendToPeer(ws, {
+        type: "welcome",
+        handle: this.hostHandle ?? "host",
+        peers: peerListForBroadcast(this.hostRole?.getPeers() ?? this.hostPeers)
+      });
+      return;
+    }
+    if (msg.type === "hello") {
+      const requested = normalizeHandle(msg.handle);
+      if (!isValidHandle(requested)) {
+        this.sendToPeer(ws, { type: "auth_fail", reason: "invalid_handle" });
+        this.sendToPeer(ws, { type: "bye" });
+        try {
+          ws.close();
+        } catch {}
+        return;
+      }
+      const peer = ws.data.peer;
+      const existing = this.takenHandles();
+      let assigned = requested;
+      if (existing.includes(assigned)) {
+        assigned = assignCollisionSuffix(requested, existing);
+      }
+      peer.handle = assigned;
+      await this.logger.log("info", "peer connected", { guestHandle: assigned });
+      await this.toaster.show(`\u2713 peer connected (${assigned})`, "success", "multiplayer");
+      this.broadcastPeersUpdate();
+      return;
+    }
+    if (msg.type === "volunteer") {
+      const peer = ws.data.peer;
+      if (peer.handle === "__pending__")
+        return;
+      peer.isVolunteer = true;
+      await this.logger.log("info", "peer volunteered", { handle: peer.handle });
+      await this.toaster.show(`volunteer accepted (${peer.handle})`, "info", "multiplayer");
+      return;
+    }
+    if (msg.type === "transfer_confirmed") {
+      await this.tc?.onTransferConfirmed(ws, msg.new_code, msg.new_url);
+      return;
+    }
+    if (msg.type === "transfer_failed") {
+      await this.tc?.onTransferFailed(msg.reason);
+      return;
+    }
+    if (msg.type === "bye") {
+      return;
+    }
+    await this.logger.log("warn", "host: unexpected message", { msg, state: ws.data.state });
+  }
+  async handleHostClose(ws) {
+    if (ws.data.state === "authenticated") {
+      const peer = ws.data.peer;
+      this.hostPeers.delete(ws);
+      if (peer.handle !== "__pending__") {
+        this.volunteers.delete(peer.handle);
+        await this.logger.log("info", "peer disconnected", { handle: peer.handle });
+        await this.toaster.show(`peer disconnected (${peer.handle})`, "warning", "multiplayer");
+        this.broadcastPeersUpdate();
+      }
+    }
+  }
+  async mpJoin(code) {
+    if (this.role !== "idle") {
+      return `Not idle (currently ${this.role}). Use mp_leave first.`;
+    }
+    if (!isValidCode(code)) {
+      return "Invalid code format. Expected `mp-<handle>-XXXX-XXXX`.";
+    }
+    const handle = this.resolveHandle();
+    const gr = new GuestRole({
+      port: this.port,
+      host: resolveHost(),
+      handle,
+      state: this.store,
+      toaster: this.toaster,
+      logger: this.logger,
+      promote: (msg, oldWs, oldUrl) => this.promoteToHost(msg, oldWs, oldUrl),
+      reconnect: (newCode, newUrl) => this.reconnectAsGuest(newCode, newUrl, "rejoin"),
+      ended: (reason) => this.onGuestEnded(reason),
+      onPeersChanged: () => this.pushPeersToCompanions(),
+      onChatReceived: (msg) => {
+        if (this.companionServer) {
+          this.companionServer.pushChat({ ...msg, mine: false });
+        }
+      },
+      onTypingReceived: (from, state) => {
+        if (this.companionServer) {
+          this.companionServer.pushTyping(from, state);
+        }
+      }
+    });
+    const result = await gr.dial(code, "join");
+    if (result.ok) {
+      this.guestRole = gr;
+      this.guestWs = gr.getWs();
+      this.setRoleGuest(gr);
+      this.pushRoleChangeToCompanions();
+      return `Connected to ${result.hostHandle}. You are ${result.myHandle} in the session.`;
+    }
+    if (result.reason === "timeout") {
+      return `No host responded at ws://${resolveHost()}:${this.port}. Is the host's opencode running, and are both using the same MP_HOST/MP_PORT?`;
+    }
+    return `Join failed: ${result.reason}`;
+  }
+  async mpLeave() {
+    if (this.role === "host") {
+      await this.tc?.startLeave();
+      return `Leaving in ${GRACE_S}s \u2014 auto-transfer pending. Use mp_cancel_leave to abort, or mp_volunteer (as a guest) to opt in as next host.`;
+    }
+    if (this.role === "guest") {
+      this.guestRole?.leave();
+      this.guestRole = null;
+      this.resetToIdleRole();
+      return "Left the session.";
+    }
+    return "Not in a session.";
+  }
+  async mpCancelLeave() {
+    if (this.role !== "host")
+      return "Only the host can cancel a leave.";
+    if (this.tc?.getState() !== "pending")
+      return "No leave is pending.";
+    await this.tc?.cancelLeave();
+    return "Leave cancelled. Staying as host.";
+  }
+  mpVolunteer() {
+    if (this.role !== "guest")
+      return "Only guests can volunteer.";
+    if (!this.guestRole?.isConnected())
+      return "Not connected.";
+    this.guestRole.sendVolunteer();
+    return "Volunteered as next host candidate.";
+  }
+  mpCode() {
+    if (this.role === "host")
+      return this.hostCode ?? "(no code)";
+    if (this.role === "guest")
+      return this.guestRole?.getHostHandle() ? `host handle: ${this.guestRole.getHostHandle()}` : "(unknown)";
+    return "Not in a session. Use mp_host or mp_join first.";
+  }
+  mpChat(text) {
+    if (this.role === "host") {
+      const result = this.hostRole?.sendChat(text);
+      if (!result)
+        return "Not hosting.";
+      if (!result.ok)
+        return `Chat failed: ${result.reason}`;
+      if (this.companionServer) {
+        this.companionServer.pushChat({
+          from: this.resolveHandle(),
+          text: text.trim(),
+          ts: Date.now(),
+          mine: true
+        });
+      }
+      return `Sent to ${result.peers} peer(s).`;
+    }
+    if (this.role === "guest") {
+      const result = this.guestRole?.sendChat(text);
+      if (!result)
+        return "Not connected.";
+      if (!result.ok)
+        return `Chat failed: ${result.reason}`;
+      if (this.companionServer) {
+        this.companionServer.pushChat({
+          from: this.resolveHandle(),
+          text: text.trim(),
+          ts: Date.now(),
+          mine: true
+        });
+      }
+      return `Sent to ${this.guestRole?.getHostHandle() ?? "host"}.`;
+    }
+    return "Not in a session. Use mp_host or mp_join first.";
+  }
+  mpTyping(state) {
+    if (this.role === "host")
+      this.hostRole?.sendTyping(state);
+    if (this.role === "guest")
+      this.guestRole?.sendTyping(state);
+  }
+  mpStatus() {
+    if (this.role === "host") {
+      const lines = [];
+      lines.push(`role: host`);
+      lines.push(`port: ${this.port}`);
+      lines.push(`url: ws://${this.hostAddr}`);
+      lines.push(`invite: ${this.hostRole?.getCode() ?? this.hostCode ?? "(none)"}`);
+      lines.push(`handle: ${this.hostRole?.getHandle() ?? this.hostHandle ?? "(none)"}`);
+      const peersMap = this.hostRole?.getPeers() ?? this.hostPeers;
+      const peers = peerListForBroadcast(peersMap);
+      if (peers.length === 0) {
+        lines.push(`peers: (none)`);
+      } else {
+        lines.push(`peers (${peers.length}):`);
+        for (const p of peers) {
+          const v = this.hostRole?.isVolunteer(p.handle) ? " [volunteer]" : "";
+          lines.push(`  - ${p.handle} (joined ${Math.round((Date.now() - p.joinedAt) / 1000)}s ago)${v}`);
+        }
+      }
+      if (this.tc?.isPending()) {
+        lines.push(`leaving: ${this.tc.getState()}`);
+      }
+      return lines.join(`
+`);
+    }
+    if (this.role === "guest") {
+      const connected = this.guestRole?.isConnected() ? "yes" : "no";
+      return [
+        `role: guest`,
+        `connected: ${connected}`,
+        `port: ${this.port}`,
+        `host: ${this.guestRole?.getHostHandle() ?? "(unknown)"}`,
+        `me: ${this.guestRole?.getMyHandle() ?? this.resolveHandle()}`,
+        `host url: ${this.guestRole?.getHostUrl() ?? `ws://${this.hostAddr}`}`
+      ].join(`
+`);
+    }
+    return `role: idle
+port: ${this.port}
+host: ${this.hostAddr}
+handle: ${this.resolveHandle()}
+url: ws://${this.hostAddr}`;
+  }
+  async mpRejoin(code) {
+    if (this.role !== "idle") {
+      return `Not idle (currently ${this.role}). Use mp_leave first.`;
+    }
+    if (!isValidCode(code)) {
+      return "Invalid code format. Expected `mp-<handle>-XXXX-XXXX`.";
+    }
+    const handle = this.resolveHandle();
+    const gr = new GuestRole({
+      port: this.port,
+      host: resolveHost(),
+      handle,
+      state: this.store,
+      toaster: this.toaster,
+      logger: this.logger,
+      promote: (msg, oldWs, oldUrl) => this.promoteToHost(msg, oldWs, oldUrl),
+      reconnect: (newCode, newUrl) => this.reconnectAsGuest(newCode, newUrl, "rejoin"),
+      ended: (reason) => this.onGuestEnded(reason)
+    });
+    const result = await gr.dial(code, "rejoin");
+    if (result.ok) {
+      this.guestRole = gr;
+      this.guestWs = gr.getWs();
+      this.setRoleGuest(gr);
+      return `Rejoined as guest (${result.myHandle}). Connected to ${result.hostHandle}.`;
+    }
+    if (result.reason === "timeout") {
+      return `No host responded at ws://${resolveHost()}:${this.port}. Is the host's opencode running? The grace code may have expired (>1 hour).`;
+    }
+    return `Rejoin failed: ${result.reason}`;
+  }
+  async promoteToHost(msg, oldHostWs, _oldHostUrl) {
+    const newHandle = msg.new_handle;
+    const newPort = resolvePort();
+    const newBindHost = resolveHost();
+    const newUrl = `ws://${newBindHost}:${newPort}`;
+    const hr = new HostRole({
+      port: newPort,
+      host: newBindHost,
+      handle: newHandle,
+      state: this.store,
+      toaster: this.toaster,
+      logger: this.logger
+    });
+    hr.addGraceCode(msg.old_code);
+    const result = await hr.start();
+    if (!result.ok) {
+      return { ok: false, reason: result.reason };
+    }
+    this.hostRole = hr;
+    this.hostCode = result.code;
+    this.hostHandle = newHandle;
+    this.port = newPort;
+    this.hostAddr = `${newBindHost}:${newPort}`;
+    this.setRoleHost(hr);
+    return { ok: true, newCode: result.code, newUrl: result.url };
+  }
+  async reconnectAsGuest(newCode, newUrl, mode) {
+    const handle = this.resolveHandle();
+    const gr = new GuestRole({
+      port: this.port,
+      host: resolveHost(),
+      handle,
+      state: this.store,
+      toaster: this.toaster,
+      logger: this.logger,
+      promote: (msg, oldWs, oldUrl) => this.promoteToHost(msg, oldWs, oldUrl),
+      reconnect: (code, url) => this.reconnectAsGuest(code, url, "rejoin"),
+      ended: (reason) => this.onGuestEnded(reason)
+    });
+    const result = await gr.dial(newCode, mode);
+    if (result.ok) {
+      this.guestRole = gr;
+      this.guestWs = gr.getWs();
+      this.setRoleGuest(gr);
+    } else {
+      this.guestRole = null;
+      this.guestWs = null;
+      this.resetToIdleRole();
+      await this.toaster.show(`reconnect after transfer failed: ${result.reason}`, "error", "multiplayer");
+    }
+  }
+  onGuestEnded(reason) {
+    this.guestRole = null;
+    this.guestWs = null;
+    this.guestHostHandle = null;
+    this.guestMyHandle = null;
+    this.guestHostUrl = null;
+    this.resetToIdleRole();
+    this.toaster.show(`session ended: ${reason}`, "warning", "multiplayer");
+  }
+  dispose() {
+    this.cleanup();
+  }
+}
+
+// src/bridge/toast.ts
+class Toaster {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  async show(message, variant = "info", title) {
+    try {
+      await this.client.tui.showToast({
+        body: { message, variant, title, duration: 4000 }
+      });
+    } catch {}
+  }
+}
+// src/bridge/logger.ts
+class Logger {
+  client;
+  service;
+  constructor(client, service = "multiplayer") {
+    this.client = client;
+    this.service = service;
+  }
+  async log(level, message, extra) {
+    try {
+      await this.client.app.log({
+        body: { service: this.service, level, message, extra: extra ?? {} }
+      });
+    } catch {}
+  }
+}
+// src/companion/spawner.ts
+import { spawn as nodeSpawn } from "child_process";
+import { existsSync as existsSync3 } from "fs";
+import { homedir as homedir2, platform, userInfo } from "os";
+function defaultHasBinary(bin) {
+  const path = (process.env["PATH"] ?? "").split(":");
+  for (const dir of path) {
+    if (existsSync3(`${dir}/${bin}`))
+      return true;
+  }
+  return false;
+}
+function detectStrategy(opts) {
+  if (opts.env.MP_NO_COMPANION === "1" || opts.env.MP_NO_COMPANION === "true") {
+    return "manual";
+  }
+  const hasBin = opts.hasBinary ?? defaultHasBinary;
+  if (opts.env.TMUX && hasBin("tmux"))
+    return "tmux";
+  if ((opts.env.TERM_PROGRAM === "iTerm.app" || opts.env.ITERM_SESSION_ID) && hasBin("osascript")) {
+    return "iterm2";
+  }
+  if (platform() === "darwin" && hasBin("osascript"))
+    return "detached";
+  if (platform() === "win32" && hasBin("wt.exe"))
+    return "detached";
+  const linuxTerminals = [
+    opts.env.TERMINAL,
+    "gnome-terminal",
+    "konsole",
+    "xfce4-terminal",
+    "kitty",
+    "wezterm",
+    "alacritty",
+    "ghostty"
+  ].filter((t) => typeof t === "string");
+  for (const t of linuxTerminals) {
+    if (hasBin(t))
+      return "detached";
+  }
+  return "manual";
+}
+function quote(s) {
+  return `'${s.replace(/'/g, "'\\''")}'`;
+}
+function buildCompanionCommand(inputs) {
+  const envPrefix = `MP_COMPANION_SOCK=${quote(inputs.socketPath)} MP_COMPANION_TOKEN=${quote(inputs.token)}`;
+  const exec = inputs.env?.["MP_COMPANION_EXEC"] ?? "node";
+  return `${envPrefix} ${exec} ${quote(inputs.binPath)}`;
+}
+function spawnStrategy(inputs) {
+  switch (inputs.strategy) {
+    case "tmux":
+      return spawnTmux(inputs);
+    case "iterm2":
+      return spawnIterm2(inputs);
+    case "detached":
+      return spawnDetached(inputs);
+    case "manual":
+      return {
+        ok: false,
+        strategy: "manual",
+        reason: "manual_fallback",
+        command: buildCompanionCommand(inputs)
+      };
+  }
+}
+function spawnTmux(inputs) {
+  const command = buildCompanionCommand(inputs);
+  const args = ["split-window", "-h", "-c", inputs.cwd ?? process.cwd(), command];
+  try {
+    const child = nodeSpawn("tmux", args, {
+      stdio: "ignore",
+      detached: true
+    });
+    child.unref();
+    return { ok: true, strategy: "tmux", pid: child.pid ?? null, command };
+  } catch (e) {
+    return { ok: false, strategy: "tmux", reason: e.message, command };
+  }
+}
+function spawnIterm2(inputs) {
+  const command = buildCompanionCommand(inputs);
+  const escaped = command.replace(/"/g, "\\\"");
+  const script = `
+    tell application "iTerm2"
+      set newSession to (split current session of current window vertically with default profile)
+      tell newSession
+        write text "${escaped}"
+      end tell
+    end tell
+  `.trim();
+  try {
+    const child = nodeSpawn("osascript", ["-e", script], {
+      stdio: "ignore",
+      detached: true
+    });
+    child.unref();
+    return { ok: true, strategy: "iterm2", pid: child.pid ?? null, command };
+  } catch (e) {
+    return { ok: false, strategy: "iterm2", reason: e.message, command };
+  }
+}
+function spawnDetached(inputs) {
+  const command = buildCompanionCommand(inputs);
+  const os = platform();
+  try {
+    if (os === "darwin") {
+      const script = `
+        tell application "Terminal"
+          activate
+          do script "${command.replace(/"/g, "\\\"")}"
+        end tell
+      `.trim();
+      const child = nodeSpawn("osascript", ["-e", script], { stdio: "ignore", detached: true });
+      child.unref();
+      return { ok: true, strategy: "detached", pid: child.pid ?? null, command };
+    }
+    if (os === "win32") {
+      const child = nodeSpawn("wt.exe", ["-d", inputs.cwd ?? process.cwd(), "node", inputs.binPath], {
+        stdio: "ignore",
+        detached: true,
+        env: {
+          ...process.env,
+          MP_COMPANION_SOCK: inputs.socketPath,
+          MP_COMPANION_TOKEN: inputs.token
+        }
+      });
+      child.unref();
+      return { ok: true, strategy: "detached", pid: child.pid ?? null, command };
+    }
+    const linuxOrder = [
+      inputs.env?.["TERMINAL"],
+      "gnome-terminal",
+      "konsole",
+      "xfce4-terminal",
+      "kitty",
+      "wezterm",
+      "alacritty",
+      "ghostty"
+    ].filter((t) => typeof t === "string");
+    for (const term of linuxOrder) {
+      if (!existsSync3(`/usr/bin/${term}`) && !defaultHasBinary(term))
+        continue;
+      let args;
+      switch (term) {
+        case "gnome-terminal":
+          args = ["--working-directory", inputs.cwd ?? process.cwd(), "--", "bash", "-lc", command];
+          break;
+        case "konsole":
+          args = ["--workdir", inputs.cwd ?? process.cwd(), "-e", "bash", "-lc", command];
+          break;
+        case "kitty":
+          args = ["--directory", inputs.cwd ?? process.cwd(), "bash", "-lc", command];
+          break;
+        case "xfce4-terminal":
+          args = [
+            "--working-directory",
+            inputs.cwd ?? process.cwd(),
+            "-e",
+            `bash -lc '${command.replace(/'/g, "'\\''")}'`
+          ];
+          break;
+        case "wezterm":
+          args = ["start", "--cwd", inputs.cwd ?? process.cwd(), "--", "bash", "-lc", command];
+          break;
+        case "alacritty":
+        case "ghostty":
+          args = ["--working-directory", inputs.cwd ?? process.cwd(), "-e", "bash", "-lc", command];
+          break;
+        default:
+          args = ["-e", "bash", "-lc", command];
+      }
+      const child = nodeSpawn(term, args, {
+        stdio: "ignore",
+        detached: true,
+        env: {
+          ...process.env,
+          MP_COMPANION_SOCK: inputs.socketPath,
+          MP_COMPANION_TOKEN: inputs.token
+        }
+      });
+      child.unref();
+      return { ok: true, strategy: "detached", pid: child.pid ?? null, command };
+    }
+    return { ok: false, strategy: "detached", reason: "no_linux_terminal_found", command };
+  } catch (e) {
+    return { ok: false, strategy: "detached", reason: e.message, command };
+  }
+}
+function manualCommand(inputs) {
+  return `MP_COMPANION_SOCK=${quote(inputs.socketPath)} MP_COMPANION_TOKEN=${quote(inputs.token)} node ${quote(inputs.binPath)}`;
+}
+
+// src/index.ts
+function companionBinPath() {
+  const override = process.env["MP_COMPANION_BIN"];
+  if (override)
+    return override;
+  return new URL("../../../multiplayer-watch/bin/multiplayer-watch.js", import.meta.url).pathname;
+}
+async function createMultiplayerPlugin(input) {
+  const toaster = new Toaster(input.client);
+  const logger = new Logger(input.client);
+  const store = new StateStore(() => {
+    const envHandle = process.env["MP_HANDLE"];
+    if (envHandle) {
+      const norm = normalizeHandle(envHandle);
+      if (norm.length > 0 && isValidHandle(norm))
+        return norm;
+    }
+    const persisted = readHandleFileSync();
+    if (persisted)
+      return persisted;
+    return normalizeHandle(osUser()) || "anon";
+  });
+  const plugin = new MultiplayerPlugin(toaster, logger, store);
+  const toast = toaster.show.bind(toaster);
+  const log = logger.log.bind(logger);
+  const handle = plugin.resolveHandle();
+  const envPort = resolvePort();
+  const envHost = resolveHost();
+  plugin.hostAddr = `${envHost}:${envPort}`;
+  const idleDeps = { handle, port: envPort, hostAddr: plugin.hostAddr, store, toaster, logger };
+  plugin.roleState = new IdleRole(idleDeps);
+  plugin.tc = new TransferController({
+    getHostRole: () => plugin.hostRole,
+    getHostPeers: () => plugin.hostPeers,
+    getHostCode: () => plugin.hostCode,
+    getHostHandle: () => plugin.hostHandle,
+    mintCode,
+    stopHost() {
+      if (plugin.hostRole) {
+        plugin.hostRole.stop();
+        plugin.hostRole = null;
+      }
+      if (plugin.hostServer) {
+        try {
+          plugin.hostServer.stop(true);
+        } catch {}
+        plugin.hostServer = null;
+      }
+      plugin.hostCode = null;
+      plugin.hostHandle = null;
+      plugin.hostPeers = new Map;
+      plugin.volunteers = new Set;
+      plugin.roleState = new IdleRole(idleDeps);
+      plugin.role = "idle";
+    },
+    recordSessionEnded: (h, r) => store.recordSessionEnded(h, r),
+    recordHostChanged: (nh, nc, oc, oh, nu) => store.recordHostChanged(nh, nc, oc, oh, nu),
+    toast,
+    log
+  }, GRACE_S * 1000, CASCADE_TIMEOUT_MS);
+  if (!process.env["MP_HANDLE"]) {
+    const persisted = readHandleFileSync();
+    if (!persisted) {
+      try {
+        await writeHandleFile(plugin.resolveHandle());
+      } catch {}
+    }
+  }
+  await logger.log("debug", "plugin loaded", {
+    handle,
+    port: envPort,
+    host: envHost,
+    role: plugin.roleState.kind
+  });
+  let companionSpawned = false;
+  if (process.env["MP_NO_COMPANION"] === "1" || process.env["MP_NO_COMPANION"] === "true") {} else {
+    (async () => {
+      const server = await plugin.startCompanionServer();
+      if (!server)
+        return;
+      const strategy = detectStrategy({
+        env: {
+          TMUX: process.env["TMUX"],
+          TERM_PROGRAM: process.env["TERM_PROGRAM"],
+          ITERM_SESSION_ID: process.env["ITERM_SESSION_ID"],
+          TERMINAL: process.env["TERMINAL"],
+          PATH: process.env["PATH"],
+          MP_NO_COMPANION: process.env["MP_NO_COMPANION"]
+        }
+      });
+      if (strategy === "manual") {
+        const cmd = manualCommand({
+          binPath: companionBinPath(),
+          socketPath: companionSocketPath(),
+          token: server.getToken()
+        });
+        await toaster.show(`Run \`${cmd}\` in another terminal for the companion pane`, "info", "multiplayer");
+        return;
+      }
+      const result = spawnStrategy({
+        strategy,
+        binPath: companionBinPath(),
+        socketPath: companionSocketPath(),
+        token: server.getToken(),
+        cwd: process.cwd()
+      });
+      if (!result.ok) {
+        await toaster.show(`Companion spawn failed (${result.strategy}: ${result.reason}). Run \`${result.command}\` in another terminal.`, "warning", "multiplayer");
+        return;
+      }
+      companionSpawned = true;
+      await logger.log("info", "companion spawned", { strategy, pid: result.pid });
+    })();
+  }
+  return {
+    dispose: async () => {
+      try {
+        if (companionSpawned) {}
+        await plugin.stopCompanionServer();
+      } catch {}
+      plugin.dispose();
+    },
+    _plugin: plugin,
+    tool: {
+      mp_host: tool({
+        description: "Start a multiplayer host: bind the local port (MP_PORT env var, default 7332) on MP_HOST (default localhost), mint an invite code, and return the URL. Other peers join with `mp_join <code>`. Fails with a clear reason if the port is busy. Only works when this plugin instance is in idle role.",
+        args: {},
+        async execute() {
+          return plugin.mpHost();
+        }
+      }),
+      mp_join: tool({
+        description: "Join a multiplayer session using the host's invite code (e.g. `mp-bob-a3f9-x7k2`). Dials `ws://<MP_HOST>:<MP_PORT>` (defaults `localhost:7332`) on the host's machine. Only works when this plugin instance is in idle role. Returns success or a reason on failure.",
+        args: {
+          code: tool.schema.string().describe("The host's invite code, e.g. `mp-bob-a3f9-x7k2`. Case-insensitive.")
+        },
+        async execute(args) {
+          return plugin.mpJoin(args.code);
+        }
+      }),
+      mp_leave: tool({
+        description: "End the current multiplayer session. On the host: starts a 10-second grace window. After the window, the plugin auto-transfers the host role to a guest that called `mp_volunteer` (priority) or the longest-connected peer (fallback). On a guest: closes the WebSocket connection immediately. Returns to idle role.",
+        args: {},
+        async execute() {
+          return plugin.mpLeave();
+        }
+      }),
+      mp_cancel_leave: tool({
+        description: "Cancel a pending host leave during the 10-second grace window. Host-only. No-op if no leave is pending. All peers are notified via a `leave_cancelled` message.",
+        args: {},
+        async execute() {
+          return plugin.mpCancelLeave();
+        }
+      }),
+      mp_volunteer: tool({
+        description: "Guest-only: opt in as the next host candidate. If the current host leaves, this peer is preferred as the successor (over the longest-connected peer). Only meaningful during a `host_leaving` grace window; harmless to call any time after joining.",
+        args: {},
+        async execute() {
+          return plugin.mpVolunteer();
+        }
+      }),
+      mp_code: tool({
+        description: "Show the current invite code. Host: the live code guests must use to join. Guest: the host's handle (the code is on the host side).",
+        args: {},
+        async execute() {
+          return plugin.mpCode();
+        }
+      }),
+      mp_chat: tool({
+        description: "Send a chat message to all peers in the session. The text is shown verbatim in each peer's companion pane (and as an OpenCode toast until the companion is running). Mirrors the companion's input box. Requires an active session (host or guest).",
+        args: {
+          text: tool.schema.string().describe("The chat message to send. Plain text, no slash prefix. Max 4000 characters.")
+        },
+        async execute(args) {
+          return plugin.mpChat(args.text);
+        }
+      }),
+      mp_status: tool({
+        description: "Show the current multiplayer state. Includes role, port, host URL, the current invite code (host only), the host handle (guest only), the assigned peer handle, the list of connected peers, the volunteer list (during a pending leave), and the leaving-state info.",
+        args: {},
+        async execute() {
+          return plugin.mpStatus();
+        }
+      }),
+      mp_rejoin: tool({
+        description: "Rejoin a session using a grace code (the previous host's code, valid for 1 hour after a host change). Dials `ws://<MP_HOST>:<MP_PORT>` and authenticates with the provided code. Only works when this plugin instance is in idle role.",
+        args: {
+          code: tool.schema.string().describe("The retired host's invite code, e.g. `mp-bob-a3f9-x7k2`. Must be within the 1-hour grace window. Case-insensitive.")
+        },
+        async execute(args) {
+          return plugin.mpRejoin(args.code);
+        }
+      }),
+      mp_watch: tool({
+        description: "Launch the companion TUI pane in a sibling terminal (presence, chat, input box). Auto-detects tmux/iTerm2/detached terminal; falls back to npx auto-install.",
+        args: {},
+        async execute() {
+          const server = await plugin.startCompanionServer();
+          if (!server) {
+            return "Companion server failed to start. Check OpenCode logs.";
+          }
+          const strategy = detectStrategy({
+            env: {
+              TMUX: process.env["TMUX"],
+              TERM_PROGRAM: process.env["TERM_PROGRAM"],
+              ITERM_SESSION_ID: process.env["ITERM_SESSION_ID"],
+              TERMINAL: process.env["TERMINAL"],
+              PATH: process.env["PATH"],
+              MP_NO_COMPANION: process.env["MP_NO_COMPANION"]
+            }
+          });
+          if (strategy === "manual") {
+            const cmd = manualCommand({
+              binPath: companionBinPath(),
+              socketPath: companionSocketPath(),
+              token: server.getToken()
+            });
+            return `Run this in another terminal to open the companion:
+${cmd}
+
+Or install globally: npm install -g @hmanlab/multiplayer-watch`;
+          }
+          const result = spawnStrategy({
+            strategy,
+            binPath: companionBinPath(),
+            socketPath: companionSocketPath(),
+            token: server.getToken(),
+            cwd: process.cwd()
+          });
+          if (!result.ok) {
+            return `Spawn failed (${result.strategy}: ${result.reason}). Run:
+${result.command}`;
+          }
+          return `Companion launched via ${result.strategy}.`;
+        }
+      })
+    }
+  };
+}
+
+// opencode/plugin/multiplayer-tools.ts
+var multiplayer_tools_default = async (input) => {
+  return createMultiplayerPlugin(input);
+};
+export {
+  multiplayer_tools_default as default
+};