pluriply 0.1.0 → 0.3.0

package/src/setup/run-setup.js

@@ -1,49 +1,152 @@
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { CLIENTS, makeEnv } from "./clients.js";
-import { saveConfig, TEMPLATE_AGENTS } from "../hub/index.js";
-import { ensureHub } from "../connector/hub-client.js";
+import { existsSync, rmSync, realpathSync, lstatSync } from "node:fs";
+import { join, dirname, resolve, sep } from "node:path";
+import { homedir } from "node:os";
+import { CLIENTS, makeEnv, isSkipped } from "./clients.js";
+import { HOOK_CLIENTS, hookStatus, installHook, removeHook } from "./hooks.js";
+import { setWorkerEnabled, TEMPLATE_AGENTS } from "../shared/config.js";
+import { readLock } from "../shared/lock.js";
+// 허브(stopHub)와 커넥터(ensureHub → ws)는 쓰는 순간에만 불러온다. 공개 미러에는 src/hub 가
+// 없고 node_modules 도 없을 수 있으므로 이 모듈은 둘 없이 로드돼야 한다(Plan 4e §5).
+const hub = () => import("../hub/index.js");
+const hubClient = () => import("../connector/hub-client.js");
+
+/** 전체 제거 뒤 항상 출력한다: 열린 세션의 커넥터는 등록 해제와 무관하게 살아 있고 허브를 다시 띄울 수 있다(스펙 §4). */
+export const REMOVE_NOTE =
+  "note: close or restart open client sessions; their connectors may restart the hub";
+
+/** @param {string[]|undefined} only */
+function resolveTargets(only) {
+  if (!only) return CLIENTS;
+  return only.map((id) => {
+    const c = CLIENTS.find((x) => x.id === id);
+    if (!c)
+      throw new Error(
+        `unknown client: ${id} (known: ${CLIENTS.map((x) => x.id).join(", ")})`,
+      );
+    return c;
+  });
+}
 
 /**
- * `pluriply setup`: 설치된 클라이언트를 감지해 pluriply 커넥터를 멱등 등록한다.
- * @param {{only?: string[], workers?: boolean, dryRun?: boolean, env?: object, home: string}} opts
- * @returns {Promise<{rows: Array<{id: string, label: string, installed: boolean, result: string}>, failed: number, hub?: {port: number}}>}
+ * 클라이언트를 돌며 표 행을 만든다. register/remove 루프가 공유한다.
+ * `act` 는 실제 등록/해제 호출, `dryRunResult` 는 (status 문자열) → 결과 문자열,
+ * `collect` 는 실패하지 않은 결과에서 워커 활성/비활성 후보를 모은다.
+ * `{error}` → `failed: <err>` 매핑과 `"failed"` → `"failed: see hint above"` 매핑은 여기 산다.
+ * @param {{targets: object[], e: object, dryRun: boolean, act: (c: object) => string, dryRunResult: (st: string) => string, collect: (c: object, result: string) => void}} opts
+ * @returns {{rows: Array<{id: string, label: string, installed: boolean, result: string}>, failed: number}}
  */
-export async function runSetup({ only, workers = false, dryRun = false, env, home }) {
-  const e = env ?? makeEnv();
-  const targets = only
-    ? only.map((id) => {
-        const c = CLIENTS.find((x) => x.id === id);
-        if (!c) throw new Error(`unknown client: ${id} (known: ${CLIENTS.map((x) => x.id).join(", ")})`);
-        return c;
-      })
-    : CLIENTS;
+function walkClients({ targets, e, dryRun, act, dryRunResult, collect }) {
   const rows = [];
   let failed = 0;
-  const enabledAgents = [];
   for (const c of targets) {
     const det = c.detect(e);
     if (!det.installed) {
-      rows.push({ id: c.id, label: c.label, installed: false, result: "not installed" });
+      rows.push({
+        id: c.id,
+        label: c.label,
+        installed: false,
+        result: "not installed",
+      });
       continue;
     }
     let result;
     if (dryRun) {
-      const st = c.status(e);
-      result = st === "present" ? "present" : typeof st === "object" ? `failed: ${st.error}` : "planned";
+      // PLURIPLY_SKIP_MCP_REGISTER 가 켜져 있으면 register/unregister 와 같은 순서(감지 → 스킵 →
+      // 상태조회)로 status() 호출 자체를 건너뛴다 — 안 그러면 dry-run만 진짜로 mcp list 를 쳐서
+      // 실행 결과와 어긋난다.
+      if (isSkipped(e)) {
+        result = "skipped";
+      } else {
+        const st = c.status(e);
+        result =
+          typeof st === "object" ? `failed: ${st.error}` : dryRunResult(st);
+      }
     } else {
-      result = c.register(e);
+      result = act(c);
       if (result === "failed") result = "failed: see hint above";
     }
     if (result.startsWith("failed")) failed++;
-    else if (c.kind === "cli" && TEMPLATE_AGENTS.includes(c.agent)) enabledAgents.push(c.agent);
+    else collect(c, result);
     rows.push({ id: c.id, label: c.label, installed: true, result });
   }
-  if (workers && !dryRun && enabledAgents.length > 0) enableWorkers(home, enabledAgents);
-  const out = { rows, failed, workers: workers ? enabledAgents : [] };
+  return { rows, failed };
+}
+
+/**
+ * MCP 등록 표(`rows`)를 바탕으로 훅 행을 만든다(스펙 §6). 도구가 감지되지 않았으면 not installed,
+ * `hooks:false` 면 skipped, dry-run 은 상태만 본다. 실패는 failed 로 세고 진행한다.
+ * @returns {{hookRows: object[], failed: number}}
+ */
+function walkHooks({ targets, rows, e, dryRun, hooks, remove }) {
+  const hookRows = [];
+  let failed = 0;
+  for (const hc of HOOK_CLIENTS) {
+    if (!targets.some((c) => c.id === hc.id)) continue;
+    const row = rows.find((x) => x.id === hc.id);
+    const installed = Boolean(row?.installed);
+    let result;
+    if (!installed) result = "not installed";
+    else if (!hooks) result = "skipped";
+    else if (dryRun) {
+      const st = hookStatus(e, hc);
+      if (typeof st === "object") result = `failed: ${st.error}`;
+      else if (remove) result = st === "missing" ? "absent" : "planned";
+      else result = st === "present" ? "present" : "planned";
+    } else result = remove ? removeHook(e, hc) : installHook(e, hc);
+    if (result === "failed") result = "failed: see hint above";
+    if (result.startsWith("failed")) failed++;
+    hookRows.push({ id: hc.id, label: hc.label, installed, result });
+  }
+  return { hookRows, failed };
+}
+
+/**
+ * `pluriply setup`: 설치된 클라이언트를 감지해 pluriply 커넥터를 멱등 등록한다.
+ * `remove` 면 반대로 등록을 풀고 워커 설정·허브·(purge 시) 데이터까지 정리한다.
+ * `--purge` 는 pluriply 홈이 심볼릭 링크면 **링크만 끊고** 링크가 가리키는 디렉터리는 남긴다
+ * (그 안의 내용까지 지우려면 실제 경로를 직접 지워야 한다).
+ * env.stopHub / env.rm / env.lstat 은 테스트가 주입한다.
+ * `hooks`(기본 true)는 Claude Code·Codex 의 Stop 훅 등록 여부다(스펙 §6). `--remove` 는 이 값과
+ * 무관하게 항상 훅을 제거한다.
+ * @param {{only?: string[], workers?: boolean, dryRun?: boolean, remove?: boolean, purge?: boolean, hooks?: boolean, env?: object, home: string}} opts
+ */
+export async function runSetup({
+  only,
+  workers = false,
+  dryRun = false,
+  remove = false,
+  purge = false,
+  hooks = true,
+  env,
+  home,
+}) {
+  const e = env ?? makeEnv();
+  const targets = resolveTargets(only);
+  if (remove) return runRemove({ targets, only, dryRun, purge, e, home });
+  const enabledAgents = [];
+  const { rows, failed } = walkClients({
+    targets,
+    e,
+    dryRun,
+    act: (c) => c.register(e),
+    dryRunResult: (st) => (st === "present" ? "present" : "planned"),
+    collect: (c) => {
+      if (c.kind === "cli" && TEMPLATE_AGENTS.includes(c.agent))
+        enabledAgents.push(c.agent);
+    },
+  });
+  const hk = walkHooks({ targets, rows, e, dryRun, hooks, remove: false });
+  if (workers && !dryRun && enabledAgents.length > 0)
+    setWorkerEnabled(home, enabledAgents, true);
+  const out = {
+    rows,
+    failed: failed + hk.failed,
+    hookRows: hk.hookRows,
+    workers: workers && !dryRun ? enabledAgents : [],
+  };
   if (!dryRun) {
     try {
-      out.hub = { port: (await ensureHub({ home })).port };
+      out.hub = { port: (await (await hubClient()).ensureHub({ home })).port };
     } catch (err) {
       out.hubError = err.message;
     }
@@ -51,32 +154,197 @@ export async function runSetup({ only, workers = false, dryRun = false, env, hom
   return out;
 }
 
-/** bin/pluriply.js `worker enable` 과 같은 병합 규칙: 원본 문서를 보존하고 workers 만 갱신 */
-function enableWorkers(home, agents) {
-  const file = join(home, "config.json");
-  let rawDoc = {};
-  if (existsSync(file)) {
+/**
+ * `--purge` 가드가 **판정에 쓰는** 경로. 문자열 비교만으로는 심볼릭 링크(`/tmp/users-alias/alice` →
+ * `/Users/alice`)나 플랫폼 별칭(`/var` → `/private/var`)을 잡을 수 없으므로 realpath 로 정규화한다.
+ * 아직 없는 홈은 realpath 가 던지니 resolve 로 물러선다. e.realpath 는 테스트 주입용.
+ *
+ * 주의: 실제로 `rm` 을 거는 경로는 이게 아니라 `resolve(home)` 이다 — runRemove 주석 참고.
+ * @param {string} home @param {object} [e] @returns {string}
+ */
+function purgeTarget(home, e = {}) {
+  const abs = resolve(home);
+  try {
+    return (e.realpath ?? realpathSync.native)(abs);
+  } catch {
+    return abs;
+  }
+}
+
+/** 대소문자를 구분하지 않는 파일시스템(macOS·Windows)에서는 비교도 대소문자를 무시한다. */
+function foldCase(p, platform) {
+  return platform === "darwin" || platform === "win32" ? p.toLowerCase() : p;
+}
+
+/** 루트를 뺀 경로 세그먼트 수. Windows 드라이브 문자(`C:`)는 세지 않는다 — `C:\Users` 는 1. */
+function depth(p) {
+  return p.split(/[\\/]+/).filter((x) => x !== "" && !/^[A-Za-z]:$/.test(x))
+    .length;
+}
+
+/**
+ * rm -rf 전 정신 확인: 지워선 안 되는 경로면 사람이 읽는 이유를, 괜찮으면 null 을 돌려준다.
+ * 거부 대상 — (a) 파일시스템 루트, (b) 사용자 홈 그 자체, (c) 사용자 홈의 상위 디렉터리,
+ * (d) 세그먼트가 두 개 미만인 최상위 디렉터리(`/Users`, `/home`, `/etc`, `C:\Users`).
+ * e.userHome / e.platform / e.realpath 는 테스트 주입용(어댑터의 env.homeDir 과는 다른 값)이며
+ * 기본은 os.homedir() / process.platform 이다.
+ * @param {string} home @param {object} [e] @returns {string|null}
+ */
+export function purgeRefusal(home, e = {}) {
+  const platform = e.platform ?? process.platform;
+  const target = purgeTarget(home, e);
+  const userHome = purgeTarget(e.userHome ?? homedir(), e);
+  const t = foldCase(target, platform);
+  const u = foldCase(userHome, platform);
+  if (dirname(target) === target) return `${target} is a filesystem root`;
+  if (t === u) return `${target} resolves to your home directory`;
+  if (u.startsWith(t.endsWith(sep) ? t : t + sep))
+    return `${target} contains your home directory`;
+  // 정규화 전후 둘 다 본다: `/etc` 는 macOS 에서 `/private/etc`(두 칸) 로 풀려 정규화 경로만
+  // 보면 통과해버린다.
+  if (depth(target) < 2 || depth(resolve(home)) < 2)
+    return `${target} is a top-level directory`;
+  return null;
+}
+
+async function runRemove({ targets, only, dryRun, purge, e, home }) {
+  const { rows, failed: rowsFailed } = walkClients({
+    targets,
+    e,
+    dryRun,
+    act: (c) => c.unregister(e),
+    dryRunResult: (st) => (st === "missing" ? "absent" : "planned"),
+    // remove 는 워커 비활성화를 행 결과가 아니라 대상 목록 자체로 정하므로(아래 toDisable)
+    // 여기서 따로 모을 게 없다.
+    collect: () => {},
+  });
+  // --remove 는 --no-hooks 와 무관하게 항상 훅을 제거한다.
+  const hk = walkHooks({ targets, rows, e, dryRun, hooks: true, remove: true });
+  const out = {
+    mode: "remove",
+    rows,
+    failed: rowsFailed + hk.failed,
+    hookRows: hk.hookRows,
+    workers: [],
+    workersDisabled: [],
+  };
+  if (dryRun) {
+    // --purge 는 --only 와 함께 실행되지 않는다(허브를 건드리지 않으므로 지울 것도 없다) — CLI 도 이 조합을 거부한다.
+    // 계획 단계에서도 실제 실행과 같은 가드를 태운다 — dry-run 이 "지우겠다"고 해놓고
+    // 실행이 거부하면(또는 그 반대면) 사용자가 확인할 방법이 없다.
+    if (purge && !only) {
+      const refusal = purgeRefusal(home, e);
+      if (refusal) {
+        out.purgeError = refusal;
+        out.failed++;
+      } else out.purge = `planned ${home}`;
+    }
+    return out;
+  }
+  // --only 면 그 실행에서 겨냥한 CLI 템플릿 에이전트 전부(행 결과가 removed/absent/skipped/failed
+  // 무엇이든) 비활성, 전체 제거면 템플릿 에이전트 전부 비활성. config.json 이 없으면 만들지 않는다.
+  // 행 결과로만 판단하면(예: removed 만) MCP 등록이 이미 없는(absent) 워커가 config.json 에는
+  // enabled:true 로 남아 허브가 계속 받아준다 — worker enable 로 등록 없이 활성화될 수 있어서다.
+  const toDisable = only
+    ? targets
+        .filter((c) => c.kind === "cli" && TEMPLATE_AGENTS.includes(c.agent))
+        .map((c) => c.agent)
+    : [...TEMPLATE_AGENTS];
+  if (toDisable.length > 0 && existsSync(join(home, "config.json"))) {
     try {
-      rawDoc = JSON.parse(readFileSync(file, "utf8"));
-    } catch {
-      rawDoc = {};
+      setWorkerEnabled(home, toDisable, false);
+      out.workersDisabled = toDisable;
+    } catch (err) {
+      out.workersError = err.message;
+      out.failed++;
+    }
+  }
+  if (only) return out;
+  try {
+    const stop = e.stopHub ?? (await hub()).stopHub;
+    out.hub = await stop({ home });
+  } catch (err) {
+    out.hubError = err.message;
+    out.failed++;
+  }
+  if (out.hub === "timeout") {
+    out.hubPid = readLock(home)?.pid;
+    out.failed++;
+  } else if (out.hub && purge) {
+    const refusal = purgeRefusal(home, e);
+    if (refusal) {
+      out.purgeError = refusal;
+      out.failed++;
+    } else {
+      // 판정은 정규화된 경로로(위 purgeRefusal), 삭제는 **정규화하지 않은** 경로로 한다.
+      // realpath 를 지우면 `~/.pluriply` 가 다른 디렉터리로의 심볼릭 링크일 때 그 바깥 디렉터리가
+      // 통째로 재귀 삭제되고 끊어진 링크만 남는다 — pluriply 소유가 아닌 데이터가 사라진다.
+      // rmSync 는 링크를 따라가지 않으므로 링크 경로를 그대로 주면 링크만 끊긴다(대상은 그대로).
+      const raw = resolve(home);
+      let symlinked = false;
+      try {
+        symlinked = (e.lstat ?? lstatSync)(raw).isSymbolicLink();
+      } catch {
+        // 경합으로 사라졌거나 못 읽으면 평범한 디렉터리로 보고 문구만 단순하게 간다
+      }
+      (e.rm ?? rmSync)(raw, { recursive: true, force: true });
+      out.purge = symlinked
+        ? `removed ${home} (symlink unlinked; target kept)`
+        : `removed ${home}`;
     }
   }
-  if (!rawDoc || typeof rawDoc !== "object" || Array.isArray(rawDoc)) rawDoc = {};
-  const workers = { ...(rawDoc.workers ?? {}) };
-  for (const a of agents) workers[a] = { ...(workers[a] ?? {}), enabled: true };
-  saveConfig(home, { ...rawDoc, workers });
+  out.note = REMOVE_NOTE;
+  return out;
 }
 
 /** @param {Awaited<ReturnType<typeof runSetup>>} r @returns {string[]} 사람이 읽는 표 */
 export function formatSetup(r, { workers = false } = {}) {
-  const lines = r.rows.map((row) => `${row.id.padEnd(16)} ${row.installed ? "installed    " : "not installed"} ${row.result}`);
+  const lines = r.rows.map(
+    (row) =>
+      `${row.id.padEnd(16)} ${row.installed ? "installed    " : "not installed"} ${row.result}`,
+  );
+  for (const row of r.hookRows ?? [])
+    lines.push(
+      `hooks ${row.id.padEnd(12)} ${row.installed ? "installed    " : "not installed"} ${row.result}`,
+    );
+  if (r.mode === "remove") {
+    if (r.workersDisabled.length)
+      lines.push(`workers disabled: ${r.workersDisabled.join(", ")}`);
+    if (r.workersError)
+      lines.push(`workers: could not update config (${r.workersError})`);
+    if (r.hub === "stopped") lines.push("hub: stopped");
+    else if (r.hub === "not-running") lines.push("hub: not running");
+    else if (r.hub === "timeout")
+      lines.push(
+        `hub: failed to stop within 5s (pid ${r.hubPid ?? "unknown"})`,
+      );
+    else if (r.hubError) lines.push(`hub: could not stop (${r.hubError})`);
+    if (r.purge) lines.push(`purge: ${r.purge}`);
+    if (r.purgeError) lines.push(`purge: refused (${r.purgeError})`);
+    if (r.note) lines.push(r.note);
+    return lines;
+  }
   if (r.hub) lines.push(`hub: running on port ${r.hub.port}`);
   if (r.hubError) lines.push(`hub: could not start (${r.hubError})`);
   if (r.workers.length) lines.push(`workers enabled: ${r.workers.join(", ")}`);
   else if (!workers) {
-    const cli = r.rows.filter((x) => x.installed && TEMPLATE_AGENTS.includes(x.id)).map((x) => x.id);
-    if (cli.length) lines.push(`hint: run \`pluriply worker enable <${cli.join("|")}>\` to let the hub run that tool headlessly (or re-run setup --workers)`);
+    const cli = r.rows
+      .filter((x) => x.installed && TEMPLATE_AGENTS.includes(x.id))
+      .map((x) => x.id);
+    if (cli.length)
+      lines.push(
+        `hint: run \`pluriply worker enable <${cli.join("|")}>\` to let the hub run that tool headlessly (or re-run setup --workers)`,
+      );
   }
+  if (
+    (r.hookRows ?? []).some(
+      (x) =>
+        x.id === "codex" &&
+        (x.result === "registered" || x.result === "updated"),
+    )
+  )
+    lines.push(
+      "hint: Codex asks to trust the new hook in its next session — approve it.",
+    );
   return lines;
 }

package/src/setup/toml-lite.js

@@ -0,0 +1,87 @@
+/**
+ * codex `config.toml` 을 파서 없이 다루는 최소 편집기. 섹션 헤더 줄(`[a.b]`, `[[a]]`)과 그 본문
+ * (다음 헤더 전까지) 단위로만 동작한다. 최상위 점 표기(`a.b.key = …`) 와 인라인 테이블은
+ * 다루지 않는다(스펙 §11). 줄 끝 주석은 허용한다.
+ *
+ * 따옴표 헤더(`[projects."/Users/alice/My Project"]`)는 **경계로는** 인식한다. codex 가 바로 그런
+ * 헤더를 쓰므로, 못 알아보면 `[mcp_servers.pluriply.*]` 하위 테이블을 지우던 중 그 뒤의 무관한
+ * `[projects.…]` 섹션까지 함께 지워진다. 이름 비교는 문자열 그대로 하므로 따옴표 헤더는 그냥
+ * "다른 섹션"으로 남는다(따옴표를 풀어 정규화하지는 않는다).
+ *
+ * 트리플쿼트 문자열(`"""…"""`/`'''…'''`)은 다루지 않는다(스펙 §11). `#` 주석 안에 나온
+ * `"""` 한 조각만으로도 진짜 문자열 상태와 무관하게 상태가 뒤집힐 수 있어, 줄 개수만 세는
+ * 방식으로는 주석과 문자열을 구분할 수 없다 — 파서 없이 안전하게 가르는 방법이 없으므로,
+ * 문서 어디에든 `"""`·`'''` 가 있으면 편집 자체를 거부한다(`hasTripleQuotes`).
+ */
+
+/** @param {string} line @returns {string|null} 헤더 줄이면 대괄호 안 이름, 아니면 null */
+function headerName(line) {
+  // 대괄호 안은 무엇이든(공백·점·슬래시·따옴표) 받는다 — 경계 판정이 목적이다.
+  const m = line.match(/^\s*\[\[?\s*(.+?)\s*\]\]?\s*(#.*)?$/);
+  return m ? m[1] : null;
+}
+
+/**
+ * 문서 어디에든(주석·문자열·그 밖 어디든) `"""` 또는 `'''` 가 있는지만 본다. 있으면
+ * `insertTomlKey`/`removeTomlSections` 는 편집을 거부한다(스펙 §11 — 트리플쿼트 문자열은
+ * 지원 범위 밖).
+ * @param {string} text @returns {boolean}
+ */
+export function hasTripleQuotes(text) {
+  return text.includes('"""') || text.includes("'''");
+}
+
+/**
+ * `[header]` 섹션 본문에 `key = value` 한 줄을 헤더 바로 아래에 넣는다.
+ * @param {string} text
+ * @param {string} header 대괄호 없는 이름(예: "mcp_servers.pluriply")
+ * @param {string} key
+ * @param {string} value TOML 리터럴 그대로(예: "600")
+ * @returns {{text: string, changed: boolean, reason?: "no-header"|"present"|"unsupported"}}
+ */
+export function insertTomlKey(text, header, key, value) {
+  if (hasTripleQuotes(text))
+    return { text, changed: false, reason: "unsupported" };
+  const lines = text.split("\n");
+  const start = lines.findIndex((l) => headerName(l) === header);
+  if (start === -1) return { text, changed: false, reason: "no-header" };
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (headerName(lines[i]) !== null) {
+      end = i;
+      break;
+    }
+  }
+  const keyRe = new RegExp(
+    `^\\s*${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*=`,
+  );
+  const hasKey = lines.slice(start + 1, end).some((l) => keyRe.test(l));
+  if (hasKey) return { text, changed: false, reason: "present" };
+  lines.splice(start + 1, 0, `${key} = ${value}`);
+  return { text: lines.join("\n"), changed: true };
+}
+
+/**
+ * 이름이 `prefix` 이거나 `prefix.` 로 시작하는 모든 섹션(헤더 + 본문)을 지운다.
+ * @param {string} text @param {string} prefix 예: "mcp_servers.pluriply"
+ * @returns {{text: string, removed: number, reason?: "unsupported"}}
+ */
+export function removeTomlSections(text, prefix) {
+  if (hasTripleQuotes(text)) return { text, removed: 0, reason: "unsupported" };
+  const lines = text.split("\n");
+  const out = [];
+  let removed = 0;
+  let skipping = false;
+  lines.forEach((line) => {
+    const name = headerName(line);
+    if (name !== null) {
+      skipping = name === prefix || name.startsWith(`${prefix}.`);
+      if (skipping) {
+        removed++;
+        return;
+      }
+    }
+    if (!skipping) out.push(line);
+  });
+  return { text: out.join("\n"), removed };
+}

package/src/shared/config.js

@@ -0,0 +1,102 @@
+import {
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  existsSync,
+  mkdirSync,
+} from "node:fs";
+import { join, isAbsolute } from "node:path";
+
+/** 내장 워커 템플릿이 있는 에이전트. 허브(worker-templates.js)와 setup 이 같이 쓴다. */
+export const TEMPLATE_AGENTS = ["codex", "claude-code", "antigravity"];
+
+/** 워커 상한 기본값 */
+export const DEFAULT_LIMITS = Object.freeze({
+  maxDepth: 2,
+  timeoutMs: 20 * 60 * 1000,
+  maxConcurrentPerAgent: 1,
+  maxQueuedPerAgent: 10,
+});
+
+/**
+ * `<home>/config.json`. 없거나 손상되면 기본값.
+ * @param {string} home
+ * @returns {{workers: object, limits: {maxDepth: number, timeoutMs: number, maxConcurrentPerAgent: number, maxQueuedPerAgent: number}, allowedRoots: string[]}}
+ */
+export function loadConfig(home) {
+  const file = join(home, "config.json");
+  let doc = {};
+  if (existsSync(file)) {
+    try {
+      doc = JSON.parse(readFileSync(file, "utf8"));
+    } catch {
+      doc = {};
+    }
+  }
+  if (!doc || typeof doc !== "object" || Array.isArray(doc)) doc = {};
+  const workers =
+    doc.workers &&
+    typeof doc.workers === "object" &&
+    !Array.isArray(doc.workers)
+      ? doc.workers
+      : {};
+  const limits = { ...DEFAULT_LIMITS };
+  for (const key of Object.keys(DEFAULT_LIMITS)) {
+    const v = doc.limits?.[key];
+    if (Number.isInteger(v) && v > 0) limits[key] = v;
+  }
+  const allowedRoots = Array.isArray(doc.allowedRoots)
+    ? doc.allowedRoots.filter((r) => typeof r === "string" && isAbsolute(r))
+    : [];
+  return { workers, limits, allowedRoots };
+}
+
+/**
+ * @param {string} home @param {object} doc tmp+rename으로 원자 저장.
+ * home 이 아직 없는 새 설치(허브를 한 번도 안 띄운 상태에서 setup --workers, worker enable 이
+ * 먼저 실행되는 경우)에서도 ENOENT 없이 만들어지도록 폴더를 먼저 보장한다.
+ */
+export function saveConfig(home, doc) {
+  mkdirSync(home, { recursive: true });
+  const file = join(home, "config.json");
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(doc, null, 2));
+  renameSync(tmp, file);
+}
+
+/** @returns {boolean} */
+export function workerEnabled(config, agent) {
+  return config.workers[agent]?.enabled === true;
+}
+
+/**
+ * 원본 config.json 문서를 다시 읽어 workers 만 병합한다. loadConfig 가 돌려주는 값은
+ * limits·allowedRoots 에 기본값이 채워진 파생값이라 그대로 되쓰면 사용자가 넣은 다른 키가
+ * 사라지므로 파일을 직접 읽는다(없거나 손상되면 {}). enable 은 {...기존, enabled: true} 병합,
+ * disable 은 키 삭제. bin `worker enable|disable`, `setup --workers`, `setup --remove` 가 쓴다.
+ * @param {string} home @param {string[]} agents @param {boolean} enabled
+ */
+export function setWorkerEnabled(home, agents, enabled) {
+  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 = {};
+  const workers =
+    rawDoc.workers &&
+    typeof rawDoc.workers === "object" &&
+    !Array.isArray(rawDoc.workers)
+      ? { ...rawDoc.workers }
+      : {};
+  for (const a of agents) {
+    if (enabled) workers[a] = { ...(workers[a] ?? {}), enabled: true };
+    else delete workers[a];
+  }
+  saveConfig(home, { ...rawDoc, workers });
+}

package/src/shared/identity.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
 import { resolve } from "node:path";
 
 /** ids.js의 shortId 알파벳(i, l, o, 0, 1 제외)과 같은 문자 집합 */
@@ -16,7 +17,8 @@ export function isValidAgentName(name) {
  * @param {string} agent @param {NodeJS.ProcessEnv} env @returns {string}
  */
 export function resolveAgentName(agent, env) {
-  if (agent === "antigravity" && env.ANTIGRAVITY_EDITOR_APP_ROOT) return "antigravity-ide";
+  if (agent === "antigravity" && env.ANTIGRAVITY_EDITOR_APP_ROOT)
+    return "antigravity-ide";
   return agent;
 }
 
@@ -50,6 +52,15 @@ export function toolOf(id) {
  * @param {string} tool @param {string} cwd @returns {string} `<tool>@<sha256 앞 8자>`
  */
 export function cwdKey(tool, cwd) {
-  const hash = createHash("sha256").update(resolve(cwd)).digest("hex");
+  // 심볼릭 링크로 인한 별칭(예: macOS /var → /private/var, cwd 별칭 디렉터리)을
+  // 같은 키로 묶는다. 존재하지 않는 경로는 realpath 가 실패하므로 resolve 결과를 쓴다
+  // (커넥터가 아직 만들어지지 않은 폴더로 뜨는 드문 경우까지 키를 안정적으로 유지).
+  let p = resolve(cwd);
+  try {
+    p = realpathSync.native(p);
+  } catch {
+    // 그대로 둔다
+  }
+  const hash = createHash("sha256").update(p).digest("hex");
   return `${tool}@${hash.slice(0, 8)}`;
 }

package/src/shared/lock.js

@@ -0,0 +1,20 @@
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * `<home>/hub.json` 락파일. 없거나 손상이면(pid·port 가 정수가 아니면 포함) null.
+ * 허브(lifecycle.js)와 setup 이 같이 읽는다 — setup 은 허브 코드 없이도 로드돼야 한다(Plan 4e).
+ * @param {string} home @returns {object|null}
+ */
+export function readLock(home) {
+  const lockPath = join(home, "hub.json");
+  if (!existsSync(lockPath)) return null;
+  try {
+    const doc = JSON.parse(readFileSync(lockPath, "utf8"));
+    return Number.isInteger(doc?.pid) && Number.isInteger(doc?.port)
+      ? doc
+      : null;
+  } catch {
+    return null;
+  }
+}