pluriply 0.1.0

package/LICENSE-HUB.md

@@ -0,0 +1,38 @@
+# Pluriply Hub License
+
+Copyright (c) 2026 TQSoft. All rights reserved.
+
+This license applies to the Pluriply hub bundle distributed as
+`src/hub/index.js` inside the `pluriply` npm package (the "Hub"). The Hub is
+**not** open source. The rest of the package is licensed under the MIT
+License in `LICENSE.md`.
+
+## Permitted use
+
+You may install and run the Hub on your own machines as part of the
+`pluriply` npm package, for the purpose of using Pluriply.
+
+## Restrictions
+
+Except as expressly permitted above, you may not:
+
+1. redistribute the Hub, in whole or in part, separately from the `pluriply`
+   npm package;
+2. modify, translate, or create derivative works of the Hub;
+3. reverse engineer, decompile, deobfuscate, or otherwise attempt to derive
+   the source code of the Hub, except to the extent such restriction is
+   prohibited by applicable law;
+4. include the Hub in, or use it to build, another product or service.
+
+## No warranty
+
+THE HUB IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL TQSOFT BE LIABLE FOR
+ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING FROM THE USE OF THE HUB.
+
+## Contact
+
+Licensing inquiries: support@pluriply.com
+
+Pluriply is a trademark of TQSoft.

package/LICENSE.md

@@ -0,0 +1,32 @@
+# License
+
+This package is licensed under the MIT License below, **except** for the
+Pluriply hub bundle at `src/hub/` (in the npm package, `src/hub/index.js`),
+which is proprietary and licensed under the terms in `LICENSE-HUB.md`.
+
+Everything else — the CLI (`bin/`), the MCP connector (`src/connector/`),
+shared utilities (`src/shared/`), and setup (`src/setup/`) — is MIT.
+
+---
+
+MIT License
+
+Copyright (c) 2026 TQSoft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# Pluriply
+
+Connect your AI coding tools into one collaboration channel. Claude Code,
+Codex, Antigravity and friends join a local channel, delegate tasks to each
+other, ask questions, and cross-review results — all on your machine.
+
+Pluriply is a trademark of TQSoft.
+
+## Supported tools
+
+| Tool                     | Role                             |
+| ------------------------ | -------------------------------- |
+| Claude Code (CLI)        | interactive peer, headless worker |
+| Codex (CLI)              | interactive peer, headless worker |
+| Antigravity CLI (`agy`)  | interactive peer, headless worker |
+| Claude Desktop           | interactive peer                 |
+| Antigravity IDE          | interactive peer                 |
+
+Requires Node.js 20 or newer. macOS is tested; Linux should work; Windows is untested.
+
+## Install
+
+```sh
+npx pluriply setup
+```
+
+`setup` detects the tools installed on this machine and registers the
+Pluriply MCP connector with each of them (idempotent — run it again any time).
+
+- `npx pluriply setup --dry-run` — show what would change without touching anything.
+- `npx pluriply setup --workers` — also let the hub run Claude Code / Codex / Antigravity headlessly for `send_task` and `ask_agent`.
+- `npx pluriply setup --only claude-code,codex` — limit to specific tools.
+
+Restart your AI tools afterwards so they pick up the new MCP server.
+
+## Use
+
+Every connected tool gets the same MCP tools. A typical flow:
+
+1. In one tool, call `join_channel` (no arguments) — it creates a channel and returns a code.
+2. In another tool, call `join_channel` with that code. `list_peers` shows who is connected.
+3. `send_task` delegates work to a peer (`to: "codex"`) and returns a task id; `get_task_result` collects the outcome.
+4. `ask_agent` asks a peer a question and waits for the answer.
+5. `request_review` asks a peer for a read-only review of your changes; `submit_review` is how the reviewer answers.
+6. `share_update` posts a note to the channel; `get_channel_context` shows recent activity.
+
+The hub starts automatically when the first connector needs it. Useful commands:
+
+```sh
+npx pluriply status                 # is the hub running?
+npx pluriply hub restart            # restart it (e.g. after an upgrade)
+npx pluriply worker enable codex    # allow headless Codex workers
+npx pluriply worker list
+```
+
+## Where your data lives
+
+Everything stays on your machine under `~/.pluriply/` (channels, task history,
+results). There is no server and no account. Delete the folder to reset.
+
+## License
+
+The CLI, connector, shared utilities and setup code in this repository are
+MIT licensed — see `LICENSE.md`. You can read every line that runs inside
+your AI tools and touches your configuration files.
+
+The Pluriply **hub** is not open source. The npm package ships it as a single
+bundled file (`src/hub/index.js`) under the terms in `LICENSE-HUB.md`, and its
+source is not in this repository. We keep the hub proprietary because it is
+the part of Pluriply we intend to build a business on; the parts that run
+inside your tools stay open so you can audit them.
+
+## Issues
+
+Bug reports and questions: https://github.com/pluriply/pluriply/issues
+Licensing inquiries: support@pluriply.com

package/bin/pluriply.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  Hub,
+  stopHub,
+  spawnHub,
+  readLock,
+  loadConfig,
+  saveConfig,
+  TEMPLATE_AGENTS,
+} from "../src/hub/index.js";
+import { pluriplyHome } from "../src/shared/paths.js";
+import { pingHub } from "../src/shared/probe.js";
+import { connectIfLive } from "../src/connector/hub-client.js";
+import { isValidAgentName } from "../src/shared/identity.js";
+import { registerMcpServer } from "../src/shared/mcp-register.js";
+
+const BIN_PATH = fileURLToPath(import.meta.url);
+
+const [cmd, ...rest] = process.argv.slice(2);
+const sub = rest[0];
+
+/** --agent x 같은 플래그 파싱 */
+function flag(name) {
+  const i = rest.indexOf(`--${name}`);
+  return i === -1 ? undefined : rest[i + 1];
+}
+
+if (cmd === "hub" && sub === "start") {
+  try {
+    const hub = new Hub();
+    const { port, redundant } = await hub.start();
+    if (redundant) {
+      console.log(`pluriply hub already running on ${port}`);
+      process.exit(0);
+    }
+    console.log(`pluriply hub listening on ${port}`);
+    const shutdown = async () => {
+      await hub.stop();
+      process.exit(0);
+    };
+    process.on("SIGTERM", shutdown);
+    process.on("SIGINT", shutdown);
+  } catch (err) {
+    console.error(`failed to start hub: ${err.message}`);
+    process.exit(1);
+  }
+} else if (cmd === "hub" && sub === "stop") {
+  const home = pluriplyHome();
+  const result = await stopHub({ home });
+  if (result === "not-running") console.log("not running");
+  else if (result === "stopped") console.log("hub stopped");
+  else {
+    const lock = readLock(home);
+    console.error(`hub did not stop within 5s (pid ${lock?.pid ?? "unknown"})`);
+    process.exit(1);
+  }
+} else if (cmd === "hub" && sub === "restart") {
+  const home = pluriplyHome();
+  try {
+    const stopped = await stopHub({ home });
+    if (stopped === "timeout") {
+      console.error("hub did not stop within 5s; not restarting");
+      process.exit(1);
+    }
+    const live = await spawnHub({ home });
+    console.log(`pluriply hub restarted on ${live.port}`);
+  } catch (err) {
+    console.error(`failed to restart hub: ${err.message}`);
+    process.exit(1);
+  }
+} else if (cmd === "worker") {
+  const home = pluriplyHome();
+  const agent = rest[1];
+  if (sub === "list") {
+    const cfg = loadConfig(home);
+    // 살아 있는 허브에만 붙는다: 새로 띄우지 않는다. 전역 실행 중 워커 수는
+    // worker.status(payload {})로 물어보며, 허브가 없거나 질의가 실패/타임아웃되면
+    // 접미사 없이 조용히 넘어간다. 소켓은 받아들이지만 응답을 안 하는 허브에
+    // 무한정 매달리지 않도록 명시적 타임아웃을 둔다(연결 자체의 타임아웃과 별개).
+    let running = null;
+    const client = await connectIfLive({ home });
+    if (client) {
+      try {
+        ({ running } = await client.request(
+          "worker.status",
+          {},
+          { timeoutMs: 3000 },
+        ));
+      } catch {
+        running = null;
+      } finally {
+        client.close();
+      }
+    }
+    for (const a of TEMPLATE_AGENTS) {
+      const enabled = Boolean(cfg.workers[a]?.enabled);
+      const suffix = enabled && running ? ` (${running} running)` : "";
+      console.log(`${a}: ${enabled ? "enabled" : "disabled"}${suffix}`);
+    }
+  } else if ((sub === "enable" || sub === "disable") && agent) {
+    if (!TEMPLATE_AGENTS.includes(agent)) {
+      console.error(`no worker template for "${agent}"`);
+      process.exit(1);
+    }
+    const cfg = loadConfig(home);
+    const workers = { ...cfg.workers };
+    if (sub === "enable")
+      workers[agent] = { ...(workers[agent] ?? {}), enabled: true };
+    else delete workers[agent];
+    // 원본 config.json 문서를 그대로 보존한 채 workers만 갱신한다: loadConfig가
+    // 돌려주는 cfg는 allowedRoots·limits를 기본값으로 채워 넣은 파생값이라, 그걸
+    // 그대로 다시 쓰면 사용자가 직접 넣은 allowedRoots(Task 1의 cwd 경계 설정)나
+    // 손대지 않은 다른 키가 사라진다. 파일을 다시 읽어 병합한다(없거나 손상돼도 {}).
+    const file = join(home, "config.json");
+    let rawDoc = {};
+    if (existsSync(file)) {
+      try {
+        rawDoc = JSON.parse(readFileSync(file, "utf8"));
+      } catch {
+        rawDoc = {};
+      }
+    }
+    if (!rawDoc || typeof rawDoc !== "object" || Array.isArray(rawDoc))
+      rawDoc = {};
+    saveConfig(home, { ...rawDoc, workers });
+    if (sub === "enable") registerMcpServer(agent, { binPath: BIN_PATH });
+    console.log(`worker ${agent} ${sub}d`);
+  } else {
+    console.error(
+      "usage: pluriply worker <enable|disable> <agent> | worker list",
+    );
+    process.exit(1);
+  }
+} else if (cmd === "setup") {
+  const { runSetup, formatSetup } = await import("../src/setup/run-setup.js");
+  const { makeEnv } = await import("../src/setup/clients.js");
+  const onlyArg = flag("only");
+  const workers = rest.includes("--workers");
+  const dryRun = rest.includes("--dry-run");
+  try {
+    const r = await runSetup({
+      only: onlyArg ? onlyArg.split(",").map((x) => x.trim()).filter(Boolean) : undefined,
+      workers,
+      dryRun,
+      env: makeEnv({ binPath: BIN_PATH }),
+      home: pluriplyHome(),
+    });
+    if (dryRun) console.log("(dry run — nothing was changed)");
+    for (const line of formatSetup(r, { workers })) console.log(line);
+    if (r.failed > 0) process.exit(1);
+  } catch (err) {
+    console.error(`setup failed: ${err.message}`);
+    process.exit(1);
+  }
+} else if (cmd === "status") {
+  const lock = readLock(pluriplyHome());
+  if (!lock) {
+    console.log("not running");
+  } else {
+    const info = await pingHub(lock.port);
+    if (!info) {
+      console.log(`stale lockfile (pid ${lock.pid} not responding)`);
+    } else {
+      console.log(
+        `running (port ${lock.port}, pid ${info.pid ?? lock.pid}, version ${info.version ?? "unknown"}, protocol ${info.protocol ?? 1})`,
+      );
+    }
+  }
+} else if (cmd === "connector") {
+  const agent = flag("agent");
+  if (!agent) {
+    console.error("usage: pluriply connector --agent <name>");
+    process.exit(1);
+  }
+  if (!isValidAgentName(agent)) {
+    console.error(`invalid agent name: ${agent}`);
+    process.exit(1);
+  }
+  const { startConnector } = await import("../src/connector/mcp-server.js");
+  await startConnector({ agent });
+} else {
+  console.error(
+    "usage: pluriply <setup [--workers] [--dry-run] [--only a,b]|hub start|hub stop|hub restart|connector --agent <name>|status|worker enable|disable <codex|claude-code|antigravity>|worker list>",
+  );
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "pluriply",
+  "version": "0.1.0",
+  "description": "Connect your AI coding tools into one collaboration channel",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pluriply/pluriply.git"
+  },
+  "homepage": "https://github.com/pluriply/pluriply#readme",
+  "bugs": {
+    "url": "https://github.com/pluriply/pluriply/issues"
+  },
+  "bin": {
+    "pluriply": "bin/pluriply.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "ws": "^8.21.3",
+    "zod": "^4.5.4"
+  }
+}

package/src/connector/hub-client.js

@@ -0,0 +1,327 @@
+import WebSocket from "ws";
+import { EventEmitter } from "node:events";
+import { pluriplyHome } from "../shared/paths.js";
+import { liveHub, spawnHub } from "../hub/index.js";
+import { PROTOCOL_VERSION } from "../shared/version.js";
+
+const RECONNECT_TOTAL_MS = 60_000;
+const RECONNECT_MAX_DELAY_MS = 5_000;
+/**
+ * request()가 this.reconnecting을 기다리는 상한. BARRIER_TIMEOUT_MS(재접속 후
+ * "reconnected" 리스너를 기다리는 상한)보다 넉넉히 커야 한다 — this.reconnecting은
+ * 그 리스너뿐 아니라 허브 재스폰 전체(ensureHub → 없으면 spawnHub, 초 단위가 될
+ * 수 있다)까지 포함하므로, 이 값이 짧으면 재접속(허브 재스폰 포함)이 아직
+ * 끝나지 않았는데 request()가 먼저 포기하고 readyState===OPEN만 보고 재join이
+ * 안 끝난 소켓으로 그대로 전송해버릴 수 있다. BARRIER_TIMEOUT_MS + 허브 재스폰
+ * 한 번(초 단위)을 넉넉히 덮도록 15s로 둔다.
+ */
+const REQUEST_WAIT_MS = 15_000;
+/**
+ * 재접속 성공 뒤 "reconnected" 리스너(예: 채널 재join)를 기다리는 최대 시간.
+ * 리스너가 절대 끝나지 않아도(응답 없는 hub.request 등) 이 시간이 지나면
+ * 재접속 루프가 포기하고 넘어가, this.reconnecting이 영원히 non-null로
+ * 남아 이후의 모든 끊김을 무시하는 사태를 막는다.
+ */
+const BARRIER_TIMEOUT_MS = 5_000;
+
+/**
+ * 재접속 후 한 번만 재시도해도 안전한, 읽기 전용(부수효과 없는) 허브 연산.
+ * `task.create`/`channel.create`/`channel.join`/`task.cancel`/`task.claim`/`task.complete`/
+ * `context.add` 등은 여기 넣지 않는다: 허브 상태는 `<home>/channels/*.json`에 영속화되므로,
+ * 요청이 실제로는 허브에 도달해 처리된 뒤 응답만 유실된 경우 재전송이 같은 연산을
+ * 한 번 더(예: 태스크 중복 생성, 워커 중복 스폰) 실행할 수 있다.
+ */
+const RETRYABLE = new Set([
+  "ping",
+  "task.get",
+  "task.wait",
+  "task.list",
+  "channel.peers",
+  "channel.presence",
+  "worker.status",
+  "context.list",
+]);
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** @returns {Promise<WebSocket|null>} 연결 실패 시 null */
+function tryConnect(port, timeoutMs = 1000) {
+  return new Promise((resolve) => {
+    const ws = new WebSocket(`ws://127.0.0.1:${port}`);
+    const timer = setTimeout(() => {
+      ws.terminate();
+      resolve(null);
+    }, timeoutMs);
+    ws.on("open", () => {
+      clearTimeout(timer);
+      resolve(ws);
+    });
+    ws.on("error", () => {
+      clearTimeout(timer);
+      resolve(null);
+    });
+  });
+}
+
+/** ping 정보로 구형 허브 여부 판정 */
+function staleFrom(info, port) {
+  if (info.protocol && info.protocol >= PROTOCOL_VERSION) return null;
+  return {
+    version: info.version ?? "unknown",
+    protocol: info.protocol ?? 1,
+    pid: info.pid ?? info.lockPid,
+    port,
+  };
+}
+
+/**
+ * 허브가 없으면 detached로 기동한다.
+ * @returns {Promise<{port: number, info: object}>} info는 ping 응답(+port, lockPid)
+ */
+export async function ensureHub({ home = pluriplyHome() } = {}) {
+  const live = (await liveHub(home)) ?? (await spawnHub({ home }));
+  return { port: live.port, info: live };
+}
+
+/**
+ * 허브와의 요청/응답 클라이언트. id 상관관계로 동시 요청을 지원하고,
+ * 연결이 끊기면 백오프로 재접속한다. 이벤트: reconnected({port}), dead.
+ */
+export class HubClient extends EventEmitter {
+  /** @type {() => void} close()가 호출되면 풀린다; #reconnect의 대기를 즉시 깨운다 */
+  #resolveClosed;
+  /** @type {Promise<void>} */
+  #closedSignal;
+
+  /**
+   * @param {WebSocket} ws
+   * @param {{home?: string, reconnectTotalMs?: number}} [opts] home이 없으면 재접속하지 않는다.
+   *   reconnectTotalMs는 재접속을 포기하기까지의 총 시간(기본 RECONNECT_TOTAL_MS) — 테스트에서 dead 경로를 짧게 만드는 데 쓴다.
+   */
+  constructor(ws, { home, reconnectTotalMs = RECONNECT_TOTAL_MS } = {}) {
+    super();
+    this.home = home;
+    this.reconnectTotalMs = reconnectTotalMs;
+    this.pending = new Map();
+    this.seq = 0;
+    this.stale = null;
+    this.closed = false;
+    this.dead = false;
+    /** @type {Promise<void>|null} 재접속 진행 중이면 그 프라미스 */
+    this.reconnecting = null;
+    this.#closedSignal = new Promise((resolve) => {
+      this.#resolveClosed = resolve;
+    });
+    this.#attach(ws);
+  }
+
+  #attach(ws) {
+    // 이전 소켓의 리스너를 떼어낸다: 늦게 도착하는 error/close가 새 연결의
+    // pending 요청을 잘못 실패시키는 것을 막는다 (기존 소켓이 없으면 no-op).
+    this.ws?.removeAllListeners();
+    this.ws = ws;
+    ws.on("message", (raw) => {
+      let msg;
+      try {
+        msg = JSON.parse(raw.toString());
+      } catch {
+        return; // 허브가 보낸 비 JSON 프레임은 무시
+      }
+      const entry = this.pending.get(msg.id);
+      if (!entry) return;
+      this.pending.delete(msg.id);
+      msg.ok
+        ? entry.resolve(msg.payload)
+        : entry.reject(new Error(msg.error?.message ?? "hub error"));
+    });
+    ws.on("close", () => this.#onLost(new Error("hub connection closed")));
+    ws.on("error", (err) =>
+      this.#onLost(new Error(`hub connection error: ${err.message}`)),
+    );
+  }
+
+  #failAll(err) {
+    for (const { reject } of this.pending.values()) reject(err);
+    this.pending.clear();
+  }
+
+  #onLost(err) {
+    this.#failAll(err);
+    if (this.closed || this.dead || this.reconnecting || !this.home) return;
+    this.reconnecting = this.#reconnect().finally(() => {
+      this.reconnecting = null;
+    });
+    // close()가 이 재접속 도중에 호출되고 그 순간 아무도 request()에서
+    // this.reconnecting을 기다리고 있지 않으면, #reconnect가 정상 반환하므로
+    // 이 프라미스는 사실 거부되지 않는다. 그래도 향후 리스너(예: "reconnected"
+    // 구독자)가 동기적으로 던지는 경우까지 대비해 처리기를 미리 붙여 둔다.
+    this.reconnecting.catch(() => {});
+  }
+
+  async #reconnect() {
+    const deadline = Date.now() + this.reconnectTotalMs;
+    let delay = 250;
+    while (Date.now() < deadline && !this.closed) {
+      try {
+        const { port, info } = await ensureHub({ home: this.home });
+        if (this.closed) return; // close()가 ensureHub 대기 중에 호출됨
+        const ws = await tryConnect(port, 3000);
+        if (this.closed) {
+          ws?.terminate(); // close()가 tryConnect 대기 중에 호출됨: 새 소켓을 붙이지 않는다
+          return;
+        }
+        if (ws) {
+          this.#attach(ws);
+          this.stale = staleFrom(info, port);
+          // emit 대신 리스너를 직접 호출해 반환 프라미스를 기다린다: 이렇게 하면
+          // this.reconnecting은 리스너(도구 계층의 채널 재join)가 끝난 뒤에야
+          // 해소되고, request()가 reconnecting을 기다리는 로직(readyState와
+          // 무관하게 reconnecting이 있으면 기다린다) 덕분에 재접속 후 첫 요청은
+          // 재join 뒤에 나간다. 리스너 예외는 삼킨다(allSettled).
+          // rawListeners를 쓴다: listeners()는 .once() 래퍼를 풀어 원본 콜백을
+          // 돌려주므로 여기서 직접 호출하면 emit()과 달리 "한 번 호출 후 자동
+          // 해제"가 발동하지 않아 같은 .once 리스너가 재접속마다 다시 불린다.
+          // rawListeners가 돌려주는 래퍼를 그대로 호출해야 emit()과 동일하게
+          // once가 정확히 한 번만 불린다.
+          // 리스너가 응답 없이 멈춰도 이 대기가 영원히 끝나지 않으면 this.reconnecting이
+          // 계속 non-null로 남아 #onLost가 이후의 모든 끊김을 무시하게 된다 —
+          // BARRIER_TIMEOUT_MS로 상한을 둬서 그 사태를 막는다(리스너 자체는
+          // 백그라운드에서 계속 돌아가지만 결과는 기다리지 않는다).
+          await Promise.race([
+            Promise.allSettled(
+              this.rawListeners("reconnected").map((fn) =>
+                Promise.resolve().then(() => fn({ port })),
+              ),
+            ),
+            sleep(BARRIER_TIMEOUT_MS),
+          ]);
+          return;
+        }
+      } catch {
+        // 허브가 아직 없음: 재시도
+      }
+      // 다음 시도까지의 대기는 close()가 즉시 깨울 수 있어야 한다
+      await Promise.race([sleep(delay), this.#closedSignal]);
+      delay = Math.min(delay * 2, RECONNECT_MAX_DELAY_MS);
+    }
+    if (!this.closed) {
+      this.dead = true;
+      this.emit("dead");
+    }
+  }
+
+  /**
+   * 허브에 접속한다. 허브 프로토콜이 커넥터보다 낮으면 `stale`에 기록하되 접속은 유지한다.
+   * @param {{home?: string, reconnectTotalMs?: number}} [opts] @returns {Promise<HubClient>}
+   */
+  static async connect({ home = pluriplyHome(), reconnectTotalMs } = {}) {
+    const { port, info } = await ensureHub({ home });
+    const ws = await tryConnect(port, 3000);
+    if (!ws) throw new Error("could not connect to pluriply hub");
+    const client = new HubClient(ws, { home, reconnectTotalMs });
+    client.stale = staleFrom(info, port);
+    return client;
+  }
+
+  /**
+   * @param {string} type @param {object} [payload]
+   * @param {{duringReconnect?: boolean, timeoutMs?: number}} [opts] duringReconnect: true면 this.reconnecting을
+   *   기다리지 않고 곧장 보낸다. #reconnect가 소켓을 붙인(#attach) 직후 "reconnected"
+   *   리스너를 호출해 그 반환 프라미스를 기다리는 동안에는, readyState가 이미 OPEN이라도
+   *   this.reconnecting은 아직 non-null이다 — 이 옵션 없이 그 리스너 자신이 request()를
+   *   부르면(예: tools.js의 채널 재join) this.reconnecting을 기다리다 자기 자신을
+   *   기다리는 교착 상태에 빠지므로, 리스너 안에서 나가는 요청에는 반드시 넘겨야 한다.
+   *   timeoutMs: 있으면 그 시간 안에 응답이 없을 때 "hub request timed out: <type>"으로
+   *   거부하고 pending 항목을 지운다(허브가 소켓은 받아들이되 응답을 안 보내는 경우 대비 —
+   *   예: worker list가 죽은 허브를 붙잡고 무한정 기다리는 사고를 막는다).
+   * @returns {Promise<object>}
+   */
+  async request(
+    type,
+    payload = {},
+    { duringReconnect = false, timeoutMs } = {},
+  ) {
+    if (this.dead) throw new Error("hub unreachable; restart the tool");
+    // readyState만으로는 부족하다: #reconnect가 #attach로 소켓을 OPEN 상태로
+    // 바꾼 뒤에도 "reconnected" 리스너(채널 재join)가 끝날 때까지 this.reconnecting은
+    // non-null로 남아있다. 그 틈에 나간 request()가 재join보다 먼저 허브에 도착하는
+    // 것을 막으려면 readyState와 무관하게 reconnecting이 있으면 기다려야 한다.
+    if (this.reconnecting && !duringReconnect) {
+      await Promise.race([this.reconnecting, sleep(REQUEST_WAIT_MS)]);
+    }
+    if (this.ws.readyState !== WebSocket.OPEN)
+      throw new Error("hub connection closed");
+    try {
+      return await this.#send(type, payload, timeoutMs);
+    } catch (err) {
+      // readyState가 아직 OPEN으로 보이는 순간 보냈는데 그 직후 끊긴 경우:
+      // 재접속이 이미 시작됐다면 그걸 기다렸다가 한 번만 더 시도한다.
+      // 주의: 허브 상태는 인메모리가 아니라 `<home>/channels/*.json`에 영속화된다
+      // (store.js) — 재시작한 허브도 같은 파일을 그대로 읽는다. 즉 첫 전송이
+      // 실제로 허브에 도달해 처리된 뒤 응답만 유실됐다면, 재전송은 같은 연산을
+      // 두 번째로 실행한다(예: task.create가 태스크를 두 개 만들고 워커도
+      // 두 번 뜬다). 그래서 재시도는 부수효과가 없는 읽기 전용 연산으로만
+      // 한정한다 — RETRYABLE에 없는 타입은 원래 에러로 즉시 거부한다.
+      if (
+        RETRYABLE.has(type) &&
+        err.message === "hub connection closed" &&
+        this.reconnecting &&
+        !duringReconnect
+      ) {
+        await Promise.race([this.reconnecting, sleep(REQUEST_WAIT_MS)]);
+        if (this.ws.readyState === WebSocket.OPEN)
+          return this.#send(type, payload, timeoutMs);
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * @param {string} type @param {object} payload @param {number} [timeoutMs]
+   * @returns {Promise<object>}
+   */
+  #send(type, payload, timeoutMs) {
+    const id = `req_${++this.seq}`;
+    return new Promise((resolve, reject) => {
+      let timer;
+      // resolve/reject 어느 쪽이 먼저 오든(정상 응답 vs 타임아웃) 남은 타이머를 지우고
+      // pending에서 항목을 지운다 — 메시지 핸들러의 delete와 겹쳐도 Map.delete는 멱등이다.
+      const settle = (fn) => (arg) => {
+        if (timer) clearTimeout(timer);
+        this.pending.delete(id);
+        fn(arg);
+      };
+      const entry = { resolve: settle(resolve), reject: settle(reject) };
+      this.pending.set(id, entry);
+      if (timeoutMs) {
+        timer = setTimeout(
+          () => entry.reject(new Error(`hub request timed out: ${type}`)),
+          timeoutMs,
+        );
+        timer.unref?.(); // 이 타이머만으로 프로세스가 살아있지 않게 한다(CLI 종료용)
+      }
+      this.ws.send(JSON.stringify({ id, type, payload }));
+    });
+  }
+
+  close() {
+    this.closed = true;
+    this.#resolveClosed();
+    this.ws.close();
+  }
+}
+
+/**
+ * 이미 떠 있는 허브에만 접속한다. 없으면 스폰하지 않고 null을 반환한다.
+ * home을 넘기지 않은 HubClient를 돌려주므로 끊겨도 재접속하지 않는다.
+ * @param {{home?: string}} [opts] @returns {Promise<HubClient|null>}
+ */
+export async function connectIfLive({ home = pluriplyHome() } = {}) {
+  const live = await liveHub(home);
+  if (!live) return null;
+  const ws = await tryConnect(live.port, 3000);
+  if (!ws) return null;
+  const client = new HubClient(ws, {});
+  client.stale = staleFrom(live, live.port);
+  return client;
+}