@pipemd-core/pipemd 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to PipeMD.
 
+## [1.1.0] — 2026-05-23
+
+### Added
+
+- **`pmd link` — Cross-machine crew federation** — connects PipeMD daemons across machines and Docker containers so crew sessions (agent coordination data) are shared in real time
+  - `pmd-linkd` relay server — one per machine, aggregates crew sessions from all local daemons, syncs with remote relays
+  - `POST /crew` endpoint — daemons push local sessions, receive merged remote sessions for their group
+  - `POST /sync` endpoint — relay-to-relay bidirectional sync of all groups, bearer token auth
+  - `GET /status` endpoint — monitoring: group counts, peer connection status
+  - `GET /health` endpoint — liveness check
+  - Named groups — coordination scopes that route sessions to the right project daemon (default: repo directory name, configurable via `link.group` or `PMD_GROUP` env var)
+  - Daemon relay client — embedded in each daemon, auto-starts when `PMD_RELAY` or `link.relay` is configured
+  - Remote session merge — `listSessions()` returns local + remote sessions; `renderCrewBlock()` tags remote agents with `· remote: <hostname>`
+  - Cross-machine conflict detection — `findConflicts()` detects file claim conflicts across machines
+  - Session expiry — remote sessions not refreshed within 15s are evicted from the relay's in-memory store
+  - Docker support — container daemons connect to relay via `PMD_RELAY=http://relay:9741` (Docker DNS)
+  - Zero new dependencies — pure Node.js `http` module
+
+### Test Suite
+
+- 121 assertions, 0 failures across 10 suites
+- `test:unit` (19) — reverseInject + link relay unit tests
+- `test:link` (17) — relay lifecycle, cross-origin exchange, group isolation, conflict detection, token auth
+- All existing suites unchanged: e2e (36), bidir (27), arch (63), compose (17), crew (92), scripts (79), inject (47)
+
 ## [1.0.0] — 2026-05-21
 
 ### Added

package/README.md

@@ -281,6 +281,35 @@ Crew hooks are available for Claude Code, OpenCode, and Gemini CLI — agents au
 
 ---
 
+## Known Limitations
+
+### FIFO (Named Pipe) Read Errors with Some Agents
+
+Agents backed by Effect.js (e.g. OpenCode) may fail to read pipe-mode context files with errors like:
+
+```
+Unknown: FileSystem.readAlloc (30)
+```
+
+**Root cause:** These agents use Effect.js's `FileSystem.readAlloc`, which expects regular file semantics (seekable, known size). PipeMD's named pipes are FIFOs — stream-oriented, unseekable, and `stat()` reports size 0. When the agent passes `limit`/`offset`, Effect.js tries to `seek()` on the FIFO and fails.
+
+**Mitigation:** The PipeMD OpenCode plugin automatically detects FIFO reads and redirects them to a regular temp file rendered by `pmd run`. This should resolve the error for most setups. Make sure your plugin is up to date (`pmd crew install-hooks` or `pmd init`).
+
+**Fallback workaround:** If the plugin fix doesn't cover your case, switch the affected pipe to legacy mode in `.pipemd/config.yml`:
+
+```yaml
+pipes:
+  - file: AGENTS.md
+    render: .pipemd/template.md
+    mode: legacy   # writes a regular file instead of a FIFO
+```
+
+Legacy mode writes a real file to disk, so agents read it normally. You lose zero-disk-write semantics, but context stays live.
+
+**Tracking:** If you hit this, please comment on or open an issue so we can track which agents are affected.
+
+---
+
 ## Contributing
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for build instructions, source layout, and architecture details.

package/dist/index.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command as Command14 } from "commander";
-import chalk18 from "chalk";
+import { Command as Command15 } from "commander";
+import chalk19 from "chalk";
 
 // src/commands/init.ts
 import { Command } from "commander";
@@ -1257,6 +1257,7 @@ function storePayload(trigger, payload) {
       try {
         const tool = (input && input.tool) || "";
         const args = (output && output.args) || {};
+        if (tool === "read") resolveFifoRead(args);
         const trigger = isEditTool(tool) ? "before-edit" : "before-read";
         const filePath = extractFilePath(args);
         join(); heartbeat();
@@ -1279,12 +1280,14 @@ function storePayload(trigger, payload) {
       try {
         const tool = (input && input.tool) || "";
         const args = (output && output.args) || {};
+        if (tool === "read") resolveFifoRead(args);
         join(); heartbeat();
         pushEvent("before", tool, extractFilePath(args), "ok", 0);
       } catch (e) { logPluginError("tool.execute.before", e); }
     },`;
   const afterHandler = withInjection ? `"tool.execute.after": async (input, output) => {
       try {
+        cleanupFifoTemp();
         const tool = (input && input.tool) || "";
         const isEdit = isEditTool(tool);
         if (isEdit) {
@@ -1308,6 +1311,7 @@ function storePayload(trigger, payload) {
       } catch (e) { logPluginError("tool.execute.after", e); }
     },` : `"tool.execute.after": async (input, output) => {
       try {
+        cleanupFifoTemp();
         const tool = (input && input.tool) || "";
         if (!isEditTool(tool)) return;
         const args = (output && output.args) || (input && input.args) || {};
@@ -1705,7 +1709,9 @@ function generateInjectionYml(config) {
 
 // src/core/paths.ts
 import path10 from "path";
+import os3 from "os";
 var PIPEMD_DIR = ".pipemd";
+var HOME_LINK_DIR = path10.join(os3.homedir(), ".pipemd", "link");
 var LIVE_DIR = path10.join(PIPEMD_DIR, "live");
 var PID_FILE = path10.join(PIPEMD_DIR, ".daemon.pid");
 var STATUS_FILE = path10.join(PIPEMD_DIR, ".status.json");
@@ -3170,7 +3176,7 @@ function listSessions() {
   try {
     files = fs10.readdirSync(CREW_DIR2);
   } catch {
-    return [];
+    files = [];
   }
   const out = [];
   for (const f of files) {
@@ -3181,6 +3187,7 @@ function listSessions() {
     } catch {
     }
   }
+  out.push(...remoteSessionsCache);
   return out;
 }
 function deleteSession(id) {
@@ -3189,6 +3196,7 @@ function deleteSession(id) {
   } catch {
   }
 }
+var remoteSessionsCache = [];
 function isPidAlive(pid) {
   if (!pid || pid <= 0) return false;
   try {
@@ -3240,8 +3248,8 @@ function resolveProcessCwd(pid) {
   if (isWindows()) return void 0;
   try {
     const target = `/proc/${pid}/cwd`;
-    const link = fs10.readlinkSync(target);
-    return typeof link === "string" ? link : void 0;
+    const link2 = fs10.readlinkSync(target);
+    return typeof link2 === "string" ? link2 : void 0;
   } catch {
     return void 0;
   }
@@ -3507,8 +3515,9 @@ function renderCrewBlock(opts = {}) {
     lines.push("_No active PipeMD crew sessions._");
   }
   for (const coord of coordinators) {
+    const remoteTag = coord._remote && coord._origin ? ` \xB7 remote: ${coord._origin}` : "";
     lines.push("");
-    lines.push(`\u25B8 ${coord.harness}  (coordinator ${coord.id} \xB7 pid ${coord.pid})`);
+    lines.push(`\u25B8 ${coord.harness}  (coordinator ${coord.id} \xB7 pid ${coord.pid}${remoteTag})`);
     if (coord.note) lines.push(`    \xB7 note: ${coord.note}`);
     const cc = claimList(coord);
     if (cc) lines.push(`    \xB7 claimed: ${cc}`);
@@ -3519,7 +3528,8 @@ function renderCrewBlock(opts = {}) {
       const claimStr = claimed ? `claimed: ${claimed}` : "no claim";
       const noteStr = w.note ? `  "${w.note}"` : "";
       const flag = w.claimedFiles.some((c) => conflictPaths.has(c.path)) ? "  \u26A0\uFE0F" : "";
-      lines.push(`    ${branch} ${w.label || w.id}  ${claimStr}${noteStr}${flag}`);
+      const rmt = w._remote && w._origin ? ` \xB7 remote: ${w._origin}` : "";
+      lines.push(`    ${branch} ${w.label || w.id}  ${claimStr}${noteStr}${flag}${rmt}`);
     });
   }
   const unattached = workers.filter(
@@ -3702,12 +3712,12 @@ function ensureCacheDir() {
   }
 }
 function readCache(key) {
-  const path25 = entryPath(key);
-  if (!existsSync(path25)) {
+  const path27 = entryPath(key);
+  if (!existsSync(path27)) {
     return null;
   }
   try {
-    const raw = readFileSync(path25, "utf-8");
+    const raw = readFileSync(path27, "utf-8");
     const entry = JSON.parse(raw);
     if (Date.now() - entry.timestamp > entry.ttl) {
       return null;
@@ -3728,17 +3738,17 @@ function writeCache(key, data, ttl, metadata) {
     ttl,
     ...metadata ? { metadata } : {}
   };
-  const path25 = entryPath(key);
-  atomicWrite(path25, JSON.stringify(entry));
+  const path27 = entryPath(key);
+  atomicWrite(path27, JSON.stringify(entry));
   return entry;
 }
 function isFresh(key) {
   return readCache(key) !== null;
 }
 function invalidate(key) {
-  const path25 = entryPath(key);
-  if (existsSync(path25)) {
-    unlinkSync(path25);
+  const path27 = entryPath(key);
+  if (existsSync(path27)) {
+    unlinkSync(path27);
   }
 }
 
@@ -3761,18 +3771,18 @@ function loadSession(sessionId) {
     return {};
   }
 }
-function saveSession(sessionId, store) {
+function saveSession(sessionId, store2) {
   ensureInjectedDir();
-  atomicWrite(sessionPath(sessionId), JSON.stringify(store));
+  atomicWrite(sessionPath(sessionId), JSON.stringify(store2));
 }
 function recordInjection(sessionId, source, content) {
-  const store = loadSession(sessionId);
-  store[source] = { hash: computePayloadHash(content), timestamp: Date.now() };
-  saveSession(sessionId, store);
+  const store2 = loadSession(sessionId);
+  store2[source] = { hash: computePayloadHash(content), timestamp: Date.now() };
+  saveSession(sessionId, store2);
 }
 function checkInjectionStatus(sessionId, source, content) {
-  const store = loadSession(sessionId);
-  const entry = store[source];
+  const store2 = loadSession(sessionId);
+  const entry = store2[source];
   if (!entry) return "new";
   const hash = computePayloadHash(content);
   return hash === entry.hash ? "unchanged" : "changed";
@@ -3836,6 +3846,115 @@ function tailLog(lines = 20) {
   }
 }
 
+// src/core/net/daemon-client.ts
+import http from "http";
+import os4 from "os";
+
+// src/core/net/protocol.ts
+var DEFAULT_PORT = 9741;
+var POLL_INTERVAL_MS = 5e3;
+var SESSION_EXPIRY_MS = 15e3;
+
+// src/core/net/daemon-client.ts
+var remoteCache = [];
+var pollTimer = null;
+function setRemoteSessions(sessions) {
+  remoteCache = sessions;
+}
+function clearRemoteSessions() {
+  remoteCache = [];
+}
+function relayUrl() {
+  return process.env.PMD_RELAY || null;
+}
+function postToRelay(url, body) {
+  return new Promise((resolve2, reject) => {
+    const data = JSON.stringify(body);
+    const req = http.request(
+      {
+        hostname: url.hostname,
+        port: url.port || 9741,
+        path: url.pathname || "/crew",
+        method: "POST",
+        timeout: 5e3,
+        headers: {
+          "Content-Type": "application/json",
+          "Content-Length": Buffer.byteLength(data)
+        }
+      },
+      (res) => {
+        const chunks = [];
+        res.on("data", (c) => chunks.push(c));
+        res.on("end", () => {
+          if (res.statusCode !== 200) {
+            reject(new Error(`relay responded ${res.statusCode}`));
+            return;
+          }
+          try {
+            const parsed = JSON.parse(Buffer.concat(chunks).toString("utf-8"));
+            const sessions = (parsed.sessions || []).map((s) => ({
+              ...s,
+              _remote: true,
+              _origin: s._origin || "remote"
+            }));
+            resolve2({ sessions });
+          } catch (e) {
+            reject(e);
+          }
+        });
+      }
+    );
+    req.on("error", reject);
+    req.on("timeout", () => {
+      req.destroy();
+      reject(new Error("relay timeout"));
+    });
+    req.write(data);
+    req.end();
+  });
+}
+async function syncWithRelay(group, sessions) {
+  const urlStr = relayUrl();
+  if (!urlStr) return [];
+  try {
+    const url = new URL(urlStr);
+    const msg = {
+      group,
+      hostname: os4.hostname(),
+      sessions
+    };
+    const result = await postToRelay(url, msg);
+    return result.sessions;
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    if (!msg.includes("ECONNREFUSED") && !msg.includes("timeout")) {
+      log.warn(`Relay client: ${msg}`);
+    }
+    return [];
+  }
+}
+function startRelayClient(group, getLocalSessions) {
+  if (pollTimer) return;
+  if (!relayUrl()) return;
+  const poll = async () => {
+    try {
+      const local = getLocalSessions();
+      const remote = await syncWithRelay(group, local);
+      setRemoteSessions(remote);
+    } catch {
+    }
+  };
+  poll();
+  pollTimer = setInterval(poll, POLL_INTERVAL_MS);
+}
+function stopRelayClient() {
+  if (pollTimer) {
+    clearInterval(pollTimer);
+    pollTimer = null;
+  }
+  clearRemoteSessions();
+}
+
 // src/core/daemon.ts
 var WRITE_BUFFER_DEBOUNCE_MS = 1e3;
 var INJECTION_LOG_MAX_AGE_MS = 36e5;
@@ -4474,10 +4593,25 @@ function runDaemon() {
   } else if (legacyModePipes.length === 0) {
     startLegacyWatcher(config);
   }
-  process.on("SIGTERM", () => shutdown(allPipePaths));
-  process.on("SIGINT", () => shutdown(allPipePaths));
+  process.on("SIGTERM", () => {
+    stopRelayClient();
+    shutdown(allPipePaths);
+  });
+  process.on("SIGINT", () => {
+    stopRelayClient();
+    shutdown(allPipePaths);
+  });
   process.on("SIGHUP", () => {
   });
+  const relayUrl2 = config.link?.relay || process.env.PMD_RELAY;
+  if (relayUrl2) {
+    const groupName = config.link?.group || path15.basename(process.cwd());
+    startRelayClient(groupName, () => {
+      const all = listSessions();
+      return all.filter((s) => !s._remote);
+    });
+    log.info(`Relay client started: ${relayUrl2} (group: ${groupName})`);
+  }
   process.on("uncaughtException", (err) => {
     log.error(`Uncaught exception: ${err.message}`);
     shutdown(allPipePaths);
@@ -6551,8 +6685,561 @@ var trace = new Command13("trace").description("Live resolution tree \u2014 debu
 });
 var traceCommand = trace;
 
+// src/commands/link.ts
+import { Command as Command14 } from "commander";
+import chalk18 from "chalk";
+import http2 from "http";
+import crypto3 from "crypto";
+import fs25 from "fs";
+import path25 from "path";
+import os5 from "os";
+import { spawn as spawn3, execSync as sleepExec } from "child_process";
+var LINK_DIR = path25.join(os5.homedir(), ".pipemd", "link");
+var PID_FILE3 = path25.join(LINK_DIR, "relay.pid");
+var TOKEN_FILE = path25.join(LINK_DIR, "relay.token");
+var PORT_FILE = path25.join(LINK_DIR, "relay.port");
+var PEERS_FILE = path25.join(LINK_DIR, "peers.json");
+function ensureLinkDir() {
+  fs25.mkdirSync(LINK_DIR, { recursive: true });
+}
+function readRelayPid() {
+  try {
+    return parseInt(fs25.readFileSync(PID_FILE3, "utf-8").trim(), 10) || null;
+  } catch {
+    return null;
+  }
+}
+function isRelayRunning() {
+  const pid = readRelayPid();
+  if (!pid) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    try {
+      fs25.unlinkSync(PID_FILE3);
+    } catch {
+    }
+    return false;
+  }
+}
+function readRelayPort() {
+  try {
+    return parseInt(fs25.readFileSync(PORT_FILE, "utf-8").trim(), 10) || DEFAULT_PORT;
+  } catch {
+    return DEFAULT_PORT;
+  }
+}
+function readOrGenerateToken() {
+  try {
+    if (fs25.existsSync(TOKEN_FILE)) {
+      return fs25.readFileSync(TOKEN_FILE, "utf-8").trim();
+    }
+  } catch {
+  }
+  const token = crypto3.randomBytes(16).toString("hex");
+  ensureLinkDir();
+  fs25.writeFileSync(TOKEN_FILE, token, "utf-8");
+  return token;
+}
+function readPeers() {
+  try {
+    if (!fs25.existsSync(PEERS_FILE)) return [];
+    return JSON.parse(fs25.readFileSync(PEERS_FILE, "utf-8"));
+  } catch {
+    return [];
+  }
+}
+function writePeers(peers) {
+  ensureLinkDir();
+  fs25.writeFileSync(PEERS_FILE, JSON.stringify(peers, null, 2), "utf-8");
+}
+function startRelayProcess() {
+  const selfPath = process.argv[1];
+  const child = spawn3(process.execPath, [selfPath, "_linkd"], {
+    cwd: process.cwd(),
+    detached: true,
+    stdio: "ignore"
+  });
+  child.unref();
+  return child.pid;
+}
+function httpGet(urlStr) {
+  return new Promise((resolve2) => {
+    try {
+      const url = new URL(urlStr);
+      const req = http2.get(
+        { hostname: url.hostname, port: url.port || DEFAULT_PORT, path: url.pathname || "/health", timeout: 3e3 },
+        (res) => {
+          const chunks = [];
+          res.on("data", (c) => chunks.push(c));
+          res.on("end", () => {
+            try {
+              resolve2({ ok: res.statusCode === 200, data: JSON.parse(Buffer.concat(chunks).toString("utf-8")) });
+            } catch {
+              resolve2({ ok: res.statusCode === 200, data: null });
+            }
+          });
+        }
+      );
+      req.on("error", () => resolve2({ ok: false, data: null }));
+      req.on("timeout", () => {
+        req.destroy();
+        resolve2({ ok: false, data: null });
+      });
+    } catch {
+      resolve2({ ok: false, data: null });
+    }
+  });
+}
+function httpGetStatus(host, token) {
+  return new Promise((resolve2) => {
+    try {
+      const [h, portStr] = host.split(":");
+      const port = parseInt(portStr || "9741", 10);
+      const headers = {};
+      if (token) headers.Authorization = `Bearer ${token}`;
+      const req = http2.get({ hostname: h, port, path: "/status", timeout: 3e3, headers }, (res) => {
+        const chunks = [];
+        res.on("data", (c) => chunks.push(c));
+        res.on("end", () => {
+          try {
+            resolve2(JSON.parse(Buffer.concat(chunks).toString("utf-8")));
+          } catch {
+            resolve2(null);
+          }
+        });
+      });
+      req.on("error", () => resolve2(null));
+      req.on("timeout", () => {
+        req.destroy();
+        resolve2(null);
+      });
+    } catch {
+      resolve2(null);
+    }
+  });
+}
+function doStart() {
+  if (isRelayRunning()) {
+    return chalk18.dim(`Relay already running (PID ${readRelayPid()}, port ${readRelayPort()})`);
+  }
+  ensureLinkDir();
+  const pid = startRelayProcess();
+  for (let i = 0; i < 20; i++) {
+    const check = readRelayPid();
+    if (check && (() => {
+      try {
+        process.kill(check, 0);
+        return true;
+      } catch {
+        return false;
+      }
+    })()) {
+      const port = readRelayPort();
+      return chalk18.green(`\u2714 Relay started (PID ${check}, port ${port})`);
+    }
+    sleepExec("sleep 0.25", { stdio: "ignore" });
+  }
+  return chalk18.yellow("\u26A0 Relay may not have started. Check with `pmd link --list`");
+}
+function formatLinkHelp() {
+  const lines = [];
+  const w = (name, desc) => `  ${chalk18.cyan(name.padEnd(22))}${chalk18.dim(desc)}`;
+  lines.push(chalk18.bold("Usage:"));
+  lines.push(w("pmd link", "Start relay and show invite command"));
+  lines.push(w("pmd link <host:port>", "Connect to a remote relay"));
+  lines.push("");
+  lines.push(chalk18.bold("Options:"));
+  lines.push(w("--token <token>", "Auth token for the remote relay"));
+  lines.push(w("--list", "Show relay status and connected peers"));
+  lines.push(w("--disconnect <host>", "Remove a peer connection"));
+  lines.push(w("--stop", "Stop the relay process"));
+  lines.push("");
+  return "\n" + lines.join("\n") + "\n";
+}
+var link = new Command14("link").description("Connect PipeMD daemons across machines and Docker containers").configureHelp({ visibleCommands: () => [] }).addHelpText("after", formatLinkHelp());
+link.command("start", { hidden: true }).action(() => {
+  const msg = doStart();
+  if (msg) console.log(msg);
+});
+link.option("--token <token>", "auth token for remote relay").option("--list", "show relay status and connected peers").option("--disconnect <host>", "remove a peer connection").option("--stop", "stop the relay process").argument("[host]", "remote relay address (host:port)").action(async (host, opts) => {
+  if (opts.stop) {
+    const pid = readRelayPid();
+    if (pid) {
+      try {
+        process.kill(pid, "SIGTERM");
+      } catch {
+      }
+      console.log(chalk18.green(`\u2714 Relay stopped (PID ${pid})`));
+    } else {
+      console.log(chalk18.dim("No relay running."));
+    }
+    return;
+  }
+  if (opts.disconnect) {
+    const peers = readPeers().filter((p) => p.host !== opts.disconnect);
+    writePeers(peers);
+    console.log(chalk18.green(`\u2714 Disconnected from ${opts.disconnect}`));
+    return;
+  }
+  if (opts.list) {
+    const running = isRelayRunning();
+    const port2 = readRelayPort();
+    const pid = readRelayPid();
+    console.log(chalk18.bold("Relay:"));
+    if (running) {
+      console.log(chalk18.green(`  \u2714 Running (PID ${pid}, port ${port2})`));
+    } else {
+      console.log(chalk18.dim("  Not running"));
+    }
+    const peers = readPeers();
+    if (peers.length > 0) {
+      console.log(chalk18.bold("\nPeers:"));
+      for (const p of peers) {
+        const status = await httpGetStatus(p.host, p.token);
+        if (status && status.ok) {
+          const groupNames = Object.keys(status.groups || {});
+          const totalAgents = Object.values(status.groups || {}).reduce((sum, g) => sum + (g.local || 0) + (g.remote || 0), 0);
+          console.log(chalk18.green(`  \u2714 ${p.host}`) + chalk18.dim(` \u2014 ${totalAgents} agents, groups: ${groupNames.join(", ") || "none"}`));
+        } else {
+          console.log(chalk18.red(`  \u2716 ${p.host}`) + chalk18.dim(" \u2014 unreachable"));
+        }
+      }
+    } else {
+      console.log(chalk18.dim("\n  No peers configured."));
+    }
+    if (running) {
+      const localStatus = await httpGetStatus(`localhost:${port2}`);
+      if (localStatus && localStatus.groups) {
+        const groups = localStatus.groups;
+        const names = Object.keys(groups);
+        if (names.length > 0) {
+          console.log(chalk18.bold("\nGroups:"));
+          for (const [name, info] of Object.entries(groups)) {
+            const g = info;
+            console.log(`  ${chalk18.cyan(name)} \u2014 ${g.local} local, ${g.remote} remote`);
+          }
+        }
+      }
+    }
+    return;
+  }
+  if (host) {
+    const { ok } = await httpGet(`http://${host}/health`);
+    if (!ok) {
+      console.log(chalk18.red(`\u2716 Cannot reach ${host}. Is the relay running there?`));
+      process.exit(1);
+    }
+    const peerToken = opts.token || "";
+    const peers = readPeers();
+    if (!peers.find((p) => p.host === host)) {
+      peers.push({ host, token: peerToken });
+      writePeers(peers);
+    }
+    if (!isRelayRunning()) {
+      doStart();
+    }
+    console.log(chalk18.green(`\u2714 Connected to ${host}`));
+    console.log(chalk18.dim("  Crew sessions will sync bidirectionally within 5 seconds."));
+    return;
+  }
+  if (!isRelayRunning()) {
+    doStart();
+  }
+  const token = readOrGenerateToken();
+  const port = readRelayPort();
+  const h = os5.hostname();
+  console.log();
+  console.log(chalk18.green(`\u2714 Token: ${token}`));
+  console.log(chalk18.green(`\u2714 Relay: ${h}:${port}`));
+  console.log();
+  console.log("On the other machine, run:");
+  console.log(chalk18.cyan(`  pmd link ${h}:${port} --token ${token}`));
+  console.log();
+});
+var linkCommand = link;
+
+// src/core/net/relay.ts
+import http3 from "http";
+import os6 from "os";
+import fs26 from "fs";
+import path26 from "path";
+var store = /* @__PURE__ */ new Map();
+var peerLastSync = /* @__PURE__ */ new Map();
+var syncTimer = null;
+var server = null;
+function hostname() {
+  return os6.hostname();
+}
+function readBody(req) {
+  return new Promise((resolve2, reject) => {
+    const chunks = [];
+    req.on("data", (c) => chunks.push(c));
+    req.on("end", () => resolve2(Buffer.concat(chunks).toString("utf-8")));
+    req.on("error", reject);
+  });
+}
+function jsonResponse(res, code, data) {
+  const body = JSON.stringify(data);
+  res.writeHead(code, {
+    "Content-Type": "application/json",
+    "Content-Length": Buffer.byteLength(body)
+  });
+  res.end(body);
+}
+function mergeSessionsFor(group, excludeOrigin) {
+  const origins = store.get(group);
+  if (!origins) return [];
+  const out = [];
+  for (const [origin, entry] of origins) {
+    if (origin === excludeOrigin) continue;
+    out.push(
+      ...entry.sessions.map((s) => ({
+        ...s,
+        _remote: true,
+        _origin: origin
+      }))
+    );
+  }
+  return out;
+}
+function expireStaleGroups() {
+  const now = Date.now();
+  for (const [group, origins] of store) {
+    for (const [origin, entry] of origins) {
+      if (now - entry.lastSeen > SESSION_EXPIRY_MS) {
+        origins.delete(origin);
+        log.info(`Relay: expired ${origin}/${group} (stale ${Math.round((now - entry.lastSeen) / 1e3)}s)`);
+      }
+    }
+    if (origins.size === 0) {
+      store.delete(group);
+    }
+  }
+}
+function readPeers2() {
+  try {
+    const homeDir = os6.homedir();
+    const peersFile = path26.join(homeDir, ".pipemd", "link", "peers.json");
+    if (!fs26.existsSync(peersFile)) return [];
+    return JSON.parse(fs26.readFileSync(peersFile, "utf-8"));
+  } catch {
+    return [];
+  }
+}
+function readToken() {
+  try {
+    const homeDir = os6.homedir();
+    const tokenFile = path26.join(homeDir, ".pipemd", "link", "relay.token");
+    if (fs26.existsSync(tokenFile)) {
+      return fs26.readFileSync(tokenFile, "utf-8").trim();
+    }
+  } catch {
+  }
+  return "";
+}
+function syncWithPeers() {
+  expireStaleGroups();
+  const peers = readPeers2();
+  if (peers.length === 0) return;
+  const localToken = readToken();
+  const allGroups = {};
+  for (const [group, origins] of store) {
+    const sessions = [];
+    for (const [, entry] of origins) {
+      sessions.push(...entry.sessions);
+    }
+    allGroups[group] = sessions;
+  }
+  const myHostname = hostname();
+  for (const peer of peers) {
+    const [host, portStr] = peer.host.split(":");
+    const port = parseInt(portStr || "9741", 10);
+    const payload = { hostname: myHostname, groups: allGroups };
+    const body = JSON.stringify(payload);
+    const req = http3.request(
+      { hostname: host, port, path: "/sync", method: "POST", timeout: 5e3, headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body), Authorization: `Bearer ${localToken || peer.token}` } },
+      (res) => {
+        const chunks = [];
+        res.on("data", (c) => chunks.push(c));
+        res.on("end", () => {
+          if (res.statusCode !== 200) return;
+          try {
+            const remote = JSON.parse(Buffer.concat(chunks).toString("utf-8"));
+            const now = Date.now();
+            for (const [group, sessions] of Object.entries(remote.groups)) {
+              let origins = store.get(group);
+              if (!origins) {
+                origins = /* @__PURE__ */ new Map();
+                store.set(group, origins);
+              }
+              origins.set(remote.hostname, { sessions, lastSeen: now });
+            }
+            peerLastSync.set(peer.host, now);
+          } catch {
+            log.warn(`Relay: failed to parse sync response from ${peer.host}`);
+          }
+        });
+      }
+    );
+    req.on("error", () => {
+    });
+    req.on("timeout", () => req.destroy());
+    req.write(body);
+    req.end();
+  }
+}
+function handleCrew(req, res) {
+  readBody(req).then((raw) => {
+    const msg = JSON.parse(raw);
+    const { group, hostname: origin, sessions } = msg;
+    let origins = store.get(group);
+    if (!origins) {
+      origins = /* @__PURE__ */ new Map();
+      store.set(group, origins);
+    }
+    origins.set(origin, { sessions, lastSeen: Date.now() });
+    log.info(`Relay: received ${sessions.length} session(s) for ${group} from ${origin}`);
+    const remoteSessions = mergeSessionsFor(group, origin);
+    jsonResponse(res, 200, { sessions: remoteSessions });
+  }).catch(() => jsonResponse(res, 400, { error: "invalid body" }));
+}
+function handleSync(req, res) {
+  const token = readToken();
+  const auth = req.headers.authorization;
+  if (token && auth !== `Bearer ${token}`) {
+    jsonResponse(res, 403, { error: "unauthorized" });
+    return;
+  }
+  readBody(req).then((raw) => {
+    const msg = JSON.parse(raw);
+    const now = Date.now();
+    for (const [group, sessions] of Object.entries(msg.groups)) {
+      let origins = store.get(group);
+      if (!origins) {
+        origins = /* @__PURE__ */ new Map();
+        store.set(group, origins);
+      }
+      origins.set(msg.hostname, { sessions, lastSeen: now });
+    }
+    const myGroups = {};
+    for (const [group, origins] of store) {
+      const sessions = [];
+      for (const [origin, entry] of origins) {
+        if (origin !== msg.hostname) {
+          sessions.push(...entry.sessions);
+        }
+      }
+      if (sessions.length > 0) myGroups[group] = sessions;
+    }
+    peerLastSync.set(msg.hostname, now);
+    jsonResponse(res, 200, { hostname: hostname(), groups: myGroups });
+  }).catch(() => jsonResponse(res, 400, { error: "invalid body" }));
+}
+function handleStatus(_req, res) {
+  const groups = {};
+  const myHost = hostname();
+  for (const [group, origins] of store) {
+    let local = 0;
+    let remote = 0;
+    for (const [origin, entry] of origins) {
+      if (origin === myHost) local += entry.sessions.length;
+      else remote += entry.sessions.length;
+    }
+    groups[group] = { local, remote };
+  }
+  const peers = readPeers2().map((p) => {
+    const ts = peerLastSync.get(p.host);
+    return { host: p.host, lastSync: ts ? new Date(ts).toISOString() : null };
+  });
+  jsonResponse(res, 200, { ok: true, hostname: myHost, groups, peers });
+}
+function requestHandler(req, res) {
+  if (req.method === "POST" && req.url === "/crew") {
+    handleCrew(req, res);
+  } else if (req.method === "POST" && req.url === "/sync") {
+    handleSync(req, res);
+  } else if (req.method === "GET" && req.url === "/status") {
+    handleStatus(req, res);
+  } else if (req.method === "GET" && req.url === "/health") {
+    jsonResponse(res, 200, { ok: true, hostname: hostname() });
+  } else {
+    jsonResponse(res, 404, { error: "not found" });
+  }
+}
+function startRelay(port = DEFAULT_PORT) {
+  return new Promise((resolve2, reject) => {
+    server = http3.createServer(requestHandler);
+    server.on("error", (err) => {
+      if (err.code === "EADDRINUSE") {
+        server = null;
+        reject(err);
+      } else {
+        log.error(`Relay error: ${err.message}`);
+      }
+    });
+    server.listen(port, () => {
+      const addr = server.address();
+      const actualPort = typeof addr === "object" && addr ? addr.port : port;
+      log.info(`Relay listening on port ${actualPort}`);
+      syncTimer = setInterval(syncWithPeers, POLL_INTERVAL_MS);
+      setInterval(expireStaleGroups, POLL_INTERVAL_MS * 3);
+      resolve2(actualPort);
+    });
+  });
+}
+function stopRelay() {
+  if (syncTimer) {
+    clearInterval(syncTimer);
+    syncTimer = null;
+  }
+  if (server) {
+    server.close();
+    server = null;
+  }
+  log.info("Relay stopped");
+}
+function runRelay() {
+  const homeDir = os6.homedir();
+  const linkDir = path26.join(homeDir, ".pipemd", "link");
+  fs26.mkdirSync(linkDir, { recursive: true });
+  const pidFile = path26.join(linkDir, "relay.pid");
+  fs26.writeFileSync(pidFile, String(process.pid), "utf-8");
+  process.on("SIGTERM", () => {
+    try {
+      fs26.unlinkSync(pidFile);
+    } catch {
+    }
+    stopRelay();
+    process.exit(0);
+  });
+  process.on("SIGINT", () => {
+    try {
+      fs26.unlinkSync(pidFile);
+    } catch {
+    }
+    stopRelay();
+    process.exit(0);
+  });
+  const envPort = parseInt(process.env.PMD_LINK_PORT || "", 10);
+  let port = isNaN(envPort) ? DEFAULT_PORT : envPort;
+  startRelay(port).then((actualPort) => {
+    log.info(`Relay running on port ${actualPort}`);
+    const portFile = path26.join(linkDir, "relay.port");
+    fs26.writeFileSync(portFile, String(actualPort), "utf-8");
+  }).catch((err) => {
+    log.error(`Relay failed to start: ${err.message}`);
+    try {
+      fs26.unlinkSync(pidFile);
+    } catch {
+    }
+    process.exit(1);
+  });
+}
+
 // src/index.ts
-var program = new Command14();
+var program = new Command15();
 var GROUPS = [
   {
     title: "Setup",
@@ -6590,6 +7277,10 @@ var GROUPS = [
       {
         name: "trace",
         desc: "Live resolution tree \u2014 debug crew coordination"
+      },
+      {
+        name: "link",
+        desc: "Connect daemons across machines and Docker containers"
       }
     ]
   },
@@ -6609,17 +7300,17 @@ function formatHelp() {
     ...GROUPS.flatMap((g) => g.commands.map((c) => c.name.length))
   );
   for (const group of GROUPS) {
-    lines.push(chalk18.bold(group.title + ":"));
+    lines.push(chalk19.bold(group.title + ":"));
     for (const cmd of group.commands) {
       lines.push(
-        `  ${chalk18.cyan(padRight(cmd.name, maxName))}  ${chalk18.dim(cmd.desc)}`
+        `  ${chalk19.cyan(padRight(cmd.name, maxName))}  ${chalk19.dim(cmd.desc)}`
       );
     }
     lines.push("");
   }
   lines.push(
-    chalk18.dim(
-      `Run ${chalk18.reset("pmd <command> --help")} for usage on any command.`
+    chalk19.dim(
+      `Run ${chalk19.reset("pmd <command> --help")} for usage on any command.`
     )
   );
   lines.push("");
@@ -6627,7 +7318,7 @@ function formatHelp() {
 }
 program.name("pmd").description(
   "PipeMD \u2014 The Dynamic Context Harness for AI Coding Agents"
-).version("1.0.1").configureHelp({ visibleCommands: () => [] }).addHelpText("after", formatHelp());
+).version("1.1.0").configureHelp({ visibleCommands: () => [] }).addHelpText("after", formatHelp());
 program.addCommand(initCommand);
 program.addCommand(startCommand);
 program.addCommand(stopCommand);
@@ -6639,9 +7330,13 @@ program.addCommand(doctorCommand);
 program.addCommand(uninstallCommand);
 program.addCommand(crewCommand);
 program.addCommand(traceCommand);
+program.addCommand(linkCommand);
 program.addCommand(injectCommand, { hidden: true });
 program.addCommand(statuslineCommand, { hidden: true });
 program.command("_daemon", { hidden: true }).description("(internal) Run the daemon process").action(() => {
   runDaemon();
 });
+program.command("_linkd", { hidden: true }).description("(internal) Run the link relay process").action(() => {
+  runRelay();
+});
 program.parse();

package/dist/plugins/opencode-server.js

@@ -8,9 +8,31 @@
 //   event(session.idle / session.status) → heartbeat + worker cleanup
 //   experimental.chat.system.transform → sub-agent detection + LLM context injection
 import { execFile, execFileSync } from "node:child_process";
-import { existsSync, writeFileSync, readFileSync, mkdirSync, renameSync, appendFileSync } from "node:fs";
+import { existsSync, writeFileSync, readFileSync, mkdirSync, renameSync, appendFileSync, statSync, unlinkSync } from "node:fs";
 import { resolve as resolvePath, join as joinPath } from "node:path";
 
+const FIFO_TEMP = joinPath("/tmp", "pmd-fifo-read-" + process.pid + ".md");
+
+function isFifoFile(filePath) {
+  if (!filePath) return false;
+  try { return statSync(resolvePath(filePath)).isFIFO(); } catch { return false; }
+}
+
+function resolveFifoRead(args) {
+  const filePath = extractFilePath(args);
+  if (!isFifoFile(filePath)) return;
+  try {
+    execFileSync(getPmdBin(), ["run", "-o", FIFO_TEMP], { encoding: "utf-8", timeout: 10000, stdio: "ignore" });
+    if ("filePath" in args) args.filePath = FIFO_TEMP;
+    if ("path" in args) args.path = FIFO_TEMP;
+    if ("file_path" in args) args.file_path = FIFO_TEMP;
+  } catch (e) { logPluginError("resolveFifoRead", e); }
+}
+
+function cleanupFifoTemp() {
+  try { unlinkSync(FIFO_TEMP); } catch {}
+}
+
 function resolvePmd() {
   const local = resolvePath(process.cwd(), "node_modules/.bin/pmd");
   if (existsSync(local)) return local;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipemd-core/pipemd",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "The Dynamic Context Harness for AI Coding Agents",
   "type": "module",
   "bin": {
@@ -18,8 +18,9 @@
     "test:compose": "bash tests/e2e-compose.sh",
     "test:crew": "bash tests/e2e-crew.sh",
     "test:inject": "bash tests/e2e-inject.sh",
-    "test:unit": "node tests/test-reverse-inject.mjs",
-    "test": "pnpm test:unit && pnpm test:e2e && pnpm test:bidir && pnpm test:scripts && pnpm test:arch && pnpm test:compose && pnpm test:crew && pnpm test:inject"
+    "test:unit": "node tests/test-reverse-inject.mjs && node tests/test-link.mjs",
+    "test:link": "bash tests/e2e-link.sh",
+    "test": "pnpm test:unit && pnpm test:e2e && pnpm test:bidir && pnpm test:scripts && pnpm test:arch && pnpm test:compose && pnpm test:crew && pnpm test:inject && pnpm test:link"
   },
   "engines": {
     "node": ">=18.0.0"