@query-farm/vgi-rpc 0.7.3 → 0.7.5

package/dist/index.js

@@ -8168,1204 +8168,1197 @@ function mtlsAuthenticateSubject(options) {
   }
   return mtlsAuthenticate({ validate, header, checkExpiry });
 }
-// src/launcher/hash.ts
-var HASH_LEN = 16;
-function canonicalJson(value) {
-  if (value === null)
-    return "null";
-  if (typeof value === "boolean")
-    return value ? "true" : "false";
-  if (typeof value === "number") {
-    return JSON.stringify(value);
-  }
-  if (typeof value === "string")
-    return JSON.stringify(value);
-  if (Array.isArray(value)) {
-    return `[${value.map(canonicalJson).join(",")}]`;
-  }
-  if (typeof value === "object") {
-    const keys = Object.keys(value).sort();
-    const parts = keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`);
-    return `{${parts.join(",")}}`;
-  }
-  throw new TypeError(`canonicalJson: unsupported type ${typeof value}`);
+// src/schema.ts
+var str = utf8();
+var bytes = binary();
+var int = int64();
+var int322 = int32();
+var int162 = int16();
+var int82 = int8();
+var uint82 = uint8();
+var uint162 = uint16();
+var uint322 = uint32();
+var uint642 = uint64();
+var float = float64();
+var float322 = float32();
+var bool2 = bool();
+function isField(x) {
+  return x != null && typeof x.name === "string" && x.type != null && typeof x.nullable === "boolean";
 }
-async function sha256Hex3(data) {
-  const buf2 = new ArrayBuffer(data.byteLength);
-  new Uint8Array(buf2).set(data);
-  const digest = await crypto.subtle.digest("SHA-256", buf2);
-  return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
+function isDataType(x) {
+  return x != null && typeof x.typeId === "number";
 }
-async function computeHash(workerArgv, cwd, env) {
-  const cwdValue = cwd !== undefined ? cwd : process.cwd();
-  const sourceEnv = env ?? process.env;
-  const filteredEnv = {};
-  for (const key of Object.keys(sourceEnv)) {
-    if (key.startsWith("VGI_RPC_")) {
-      const v = sourceEnv[key];
-      if (v !== undefined)
-        filteredEnv[key] = v;
+function toSchema(spec) {
+  const maybeFields = spec.fields;
+  if (Array.isArray(maybeFields)) {
+    const out = [];
+    for (const f of maybeFields) {
+      if (isField(f)) {
+        out.push(f);
+      } else {
+        out.push(field(f.name, f.type, f.nullable ?? true, f.metadata));
+      }
     }
+    return schema(out);
   }
-  const canonical = {
-    cmd: [...workerArgv],
-    cwd: cwdValue,
-    env: filteredEnv
-  };
-  const payload = new TextEncoder().encode(canonicalJson(canonical));
-  const hex = await sha256Hex3(payload);
-  return hex.slice(0, HASH_LEN);
-}
-// src/launcher/launch.ts
-import { spawn } from "node:child_process";
-import { createWriteStream, unlinkSync as unlinkSync2 } from "node:fs";
-
-// src/launcher/lock.ts
-import { closeSync, constants as FS, openSync, readSync, statSync, writeSync } from "node:fs";
-var POLL_MS = 50;
-var VERIFY_RETRIES = 5;
-function pidAlive(pid) {
-  if (!Number.isInteger(pid) || pid <= 0)
-    return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err2) {
-    return err2?.code === "EPERM";
+  const fields = [];
+  for (const [name, value] of Object.entries(spec)) {
+    if (isField(value)) {
+      fields.push(value);
+    } else if (isDataType(value)) {
+      fields.push(field(name, value, false));
+    } else {
+      throw new TypeError(`Invalid schema value for "${name}": expected DataType or Field, got ${typeof value}`);
+    }
   }
+  return schema(fields);
 }
-function readPid(path) {
-  try {
-    const fd = openSync(path, FS.O_RDONLY);
-    try {
-      const buf2 = Buffer.alloc(64);
-      const n = readSync(fd, buf2, 0, buf2.length, 0);
-      const text = buf2.subarray(0, n).toString("utf8").trim();
-      if (text === "")
-        return 0;
-      const parsed = Number(text);
-      return Number.isInteger(parsed) ? parsed : 0;
-    } finally {
-      closeSync(fd);
-    }
-  } catch {
-    return 0;
+function inferParamTypes(spec) {
+  const sch = toSchema(spec);
+  if (sch.fields.length === 0)
+    return;
+  const result = {};
+  for (const f of sch.fields) {
+    let mapped;
+    if (isUtf8(f.type))
+      mapped = "str";
+    else if (isBinary(f.type))
+      mapped = "bytes";
+    else if (isBool(f.type))
+      mapped = "bool";
+    else if (isFloat(f.type))
+      mapped = "float";
+    else if (isInt(f.type))
+      mapped = "int";
+    if (!mapped)
+      return;
+    result[f.name] = mapped;
   }
+  return result;
 }
-function tryStampPid(path) {
-  const fd = openSync(path, FS.O_RDWR | FS.O_CREAT, 384);
-  try {
-    const stamp = Buffer.from(String(process.pid), "utf8");
-    const { ftruncateSync } = __require("node:fs");
-    ftruncateSync(fd, 0);
-    let written = 0;
-    while (written < stamp.length) {
-      const n = writeSync(fd, stamp, written, stamp.length - written, 0 + written);
-      if (n <= 0)
-        throw new Error(`writeSync returned ${n}`);
-      written += n;
+
+// src/protocol.ts
+var EMPTY_SCHEMA3 = schema([]);
+
+class Protocol {
+  name;
+  protocolVersion;
+  protocolVersionParts;
+  _methods = new Map;
+  constructor(name, options) {
+    this.name = name;
+    const raw = options?.protocolVersion;
+    if (raw === undefined || raw === "") {
+      this.protocolVersion = "";
+      this.protocolVersionParts = null;
+    } else {
+      this.protocolVersion = raw;
+      this.protocolVersionParts = parseProtocolVersion(raw);
     }
-    const st = statSync(path);
-    if (st.size !== stamp.length)
-      return false;
-    return true;
-  } finally {
-    closeSync(fd);
+  }
+  unary(name, config) {
+    const params = toSchema(config.params);
+    this._methods.set(name, {
+      name,
+      type: "unary" /* UNARY */,
+      paramsSchema: params,
+      resultSchema: toSchema(config.result),
+      handler: config.handler,
+      doc: config.doc,
+      defaults: config.defaults,
+      paramTypes: config.paramTypes ?? inferParamTypes(params)
+    });
+    return this;
+  }
+  producer(name, config) {
+    const params = toSchema(config.params);
+    this._methods.set(name, {
+      name,
+      type: "stream" /* STREAM */,
+      paramsSchema: params,
+      resultSchema: EMPTY_SCHEMA3,
+      outputSchema: toSchema(config.outputSchema),
+      inputSchema: EMPTY_SCHEMA3,
+      producerInit: config.init,
+      producerFn: config.produce,
+      onCancel: config.onCancel,
+      headerSchema: config.headerSchema ? toSchema(config.headerSchema) : undefined,
+      headerInit: config.headerInit,
+      doc: config.doc,
+      defaults: config.defaults,
+      paramTypes: config.paramTypes ?? inferParamTypes(params)
+    });
+    return this;
+  }
+  exchange(name, config) {
+    const params = toSchema(config.params);
+    this._methods.set(name, {
+      name,
+      type: "stream" /* STREAM */,
+      paramsSchema: params,
+      resultSchema: EMPTY_SCHEMA3,
+      inputSchema: toSchema(config.inputSchema),
+      outputSchema: toSchema(config.outputSchema),
+      exchangeInit: config.init,
+      exchangeFn: config.exchange,
+      onCancel: config.onCancel,
+      headerSchema: config.headerSchema ? toSchema(config.headerSchema) : undefined,
+      headerInit: config.headerInit,
+      doc: config.doc,
+      defaults: config.defaults,
+      paramTypes: config.paramTypes ?? inferParamTypes(params)
+    });
+    return this;
+  }
+  getMethods() {
+    return new Map(this._methods);
   }
 }
-function clearStamp(path) {
+// src/dispatch/stream.ts
+var EMPTY_SCHEMA4 = schema([]);
+async function dispatchStream(method, params, writer, reader, serverId, requestId, externalConfig, kind) {
+  const isProducer = !!method.producerFn;
+  let state;
   try {
-    const fd = openSync(path, FS.O_RDWR);
-    try {
-      const { ftruncateSync } = __require("node:fs");
-      ftruncateSync(fd, 0);
-    } finally {
-      closeSync(fd);
+    if (isProducer) {
+      state = await method.producerInit(params);
+    } else {
+      state = await method.exchangeInit(params);
     }
-  } catch {}
-}
-function tryAcquireLock(lockPath) {
-  for (let attempt = 0;attempt < VERIFY_RETRIES; attempt++) {
-    const existingPid = readPid(lockPath);
-    if (existingPid > 0 && pidAlive(existingPid)) {
-      return null;
+  } catch (error) {
+    const errSchema = method.headerSchema ?? EMPTY_SCHEMA4;
+    const errBatch = buildErrorBatch(errSchema, error, serverId, requestId);
+    await writer.writeStream(errSchema, [errBatch]);
+    const inputSchema2 = await reader.openNextStream();
+    if (inputSchema2) {
+      while (await reader.readNextBatch() !== null) {}
     }
-    if (!tryStampPid(lockPath))
-      continue;
-    const verifyPid = readPid(lockPath);
-    if (verifyPid !== process.pid) {
-      continue;
-    }
-    let released = false;
-    return {
-      path: lockPath,
-      release() {
-        if (released)
-          return;
-        released = true;
-        clearStamp(lockPath);
-      }
-    };
+    return;
   }
-  return null;
-}
-async function acquireLock(lockPath, timeoutMs) {
-  const deadline = Date.now() + Math.max(0, timeoutMs);
-  for (;; ) {
-    const handle = tryAcquireLock(lockPath);
-    if (handle)
-      return handle;
-    if (Date.now() >= deadline) {
-      throw new Error(`failed to acquire ${lockPath} within ${timeoutMs}ms`);
+  const outputSchema = state?.__outputSchema ?? method.outputSchema;
+  const effectiveProducer = state?.__isProducer ?? isProducer;
+  if (method.headerSchema && method.headerInit) {
+    try {
+      const headerOut = new OutputCollector(method.headerSchema, true, serverId, requestId, undefined, undefined, kind);
+      const headerValues = method.headerInit(params, state, headerOut);
+      const headerBatch = buildResultBatch(method.headerSchema, headerValues, serverId, requestId);
+      const headerBatches = [...headerOut.batches.map((b) => b.batch), headerBatch];
+      await writer.writeStream(method.headerSchema, headerBatches);
+    } catch (error) {
+      const errBatch = buildErrorBatch(method.headerSchema, error, serverId, requestId);
+      await writer.writeStream(method.headerSchema, [errBatch]);
+      const inputSchema2 = await reader.openNextStream();
+      if (inputSchema2) {
+        while (await reader.readNextBatch() !== null) {}
+      }
+      return;
     }
-    await new Promise((r) => setTimeout(r, POLL_MS));
   }
-}
-
-// src/launcher/state.ts
-import { existsSync, mkdirSync, readFileSync, statSync as statSync2, unlinkSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import * as path from "node:path";
-function socketPaths(stateDir, hashId) {
-  return {
-    lockPath: path.join(stateDir, `${hashId}.lock`),
-    sockPath: path.join(stateDir, `${hashId}.sock`),
-    metaPath: path.join(stateDir, `${hashId}.meta`)
-  };
-}
-function defaultStateDir() {
-  let base;
-  if (process.platform === "win32") {
-    base = path.join(tmpdir(), "vgi-rpc");
-  } else {
-    const xdg = process.env.XDG_RUNTIME_DIR;
-    if (xdg) {
-      base = path.join(xdg, "vgi-rpc");
-    } else {
-      const uid = typeof process.geteuid === "function" ? process.geteuid() : 0;
-      base = path.join(tmpdir(), `vgi-rpc-${uid}`);
-    }
+  const inputSchema = await reader.openNextStream();
+  if (!inputSchema) {
+    const errBatch = buildErrorBatch(outputSchema, new Error("Expected input stream but got EOF"), serverId, requestId);
+    await writer.writeStream(outputSchema, [errBatch]);
+    return;
   }
-  mkdirSync(base, { recursive: true, mode: 448 });
-  if (process.platform !== "win32" && typeof process.geteuid === "function") {
-    try {
-      const st = statSync2(base);
-      if (st.uid !== process.geteuid()) {
-        throw new Error(`state directory ${base} is not owned by current user`);
+  const stream = writer.openStream(outputSchema);
+  const expectedInputSchema = state?.__inputSchema ?? method.inputSchema;
+  try {
+    while (true) {
+      let inputBatch = await reader.readNextBatch();
+      if (!inputBatch)
+        break;
+      if (inputBatch.metadata?.get(CANCEL_KEY)) {
+        if (method.onCancel) {
+          try {
+            await method.onCancel(state);
+          } catch (err2) {
+            console.debug?.(`onCancel hook failed: ${err2 instanceof Error ? err2.message : err2}`);
+          }
+        }
+        break;
       }
-    } catch (err2) {
-      if (err2?.code === "ENOENT") {} else {
-        throw err2;
+      if (expectedInputSchema && !effectiveProducer && inputBatch.schema !== expectedInputSchema) {
+        try {
+          inputBatch = conformBatchToSchema(inputBatch, expectedInputSchema);
+        } catch (e) {
+          if (e instanceof TypeError)
+            throw e;
+          console.debug?.(`Schema conformance skipped: ${e instanceof Error ? e.message : e}`);
+        }
+      }
+      const out = new OutputCollector(outputSchema, effectiveProducer, serverId, requestId, undefined, undefined, kind);
+      if (isProducer) {
+        await method.producerFn(state, out);
+      } else {
+        await method.exchangeFn(state, inputBatch, out);
+      }
+      for (const emitted of out.batches) {
+        let batch = emitted.batch;
+        if (externalConfig) {
+          batch = await maybeExternalizeBatch(batch, externalConfig);
+        }
+        if (emitted.metadata && emitted.metadata.size > 0) {
+          batch = withBatchMetadata(batch, emitted.metadata);
+        }
+        await stream.write(batch);
+      }
+      if (out.finished) {
+        break;
       }
     }
+  } catch (error) {
+    await stream.write(buildErrorBatch(outputSchema, error, serverId, requestId));
   }
-  return base;
-}
-function writeMeta(metaPath, workerArgv, cwd, sockPath) {
-  const payload = {
-    cmd: [...workerArgv],
-    cwd,
-    socket: sockPath,
-    started_at: Date.now() / 1000,
-    launcher_pid: process.pid
-  };
+  await stream.close();
   try {
-    writeFileSync(metaPath, JSON.stringify(payload, null, 2), { encoding: "utf8", mode: 384 });
+    while (await reader.readNextBatch() !== null) {}
   } catch {}
 }
-async function probeSocket(sockPath, timeoutMs = 2000) {
-  if (!existsSync(sockPath))
-    return false;
-  const net = await import("node:net");
-  return new Promise((resolve) => {
-    const sock = net.createConnection({ path: sockPath });
-    const timer = setTimeout(() => {
-      sock.destroy();
-      resolve(false);
-    }, timeoutMs);
-    sock.once("connect", () => {
-      clearTimeout(timer);
-      sock.end();
-      resolve(true);
-    });
-    sock.once("error", () => {
-      clearTimeout(timer);
-      resolve(false);
-    });
-  });
-}
-function tryReadMeta(metaPath) {
+
+// src/dispatch/unary.ts
+async function dispatchUnary(method, params, writer, serverId, requestId, externalConfig, kind) {
+  const schema2 = method.resultSchema;
+  const out = new OutputCollector(schema2, true, serverId, requestId, undefined, undefined, kind);
   try {
-    const raw = readFileSync(metaPath, "utf8");
-    const meta = JSON.parse(raw);
-    return {
-      cmd: Array.isArray(meta.cmd) ? meta.cmd.map(String) : [],
-      cwd: typeof meta.cwd === "string" ? meta.cwd : "",
-      startedAt: typeof meta.started_at === "number" ? meta.started_at : null
-    };
-  } catch {
-    return { cmd: [], cwd: "", startedAt: null };
+    const result = await method.handler(params, out);
+    let resultBatch = buildResultBatch(schema2, result, serverId, requestId);
+    if (externalConfig) {
+      resultBatch = await maybeExternalizeBatch(resultBatch, externalConfig);
+    }
+    const batches = [...out.batches.map((b) => b.batch), resultBatch];
+    await writer.writeStream(schema2, batches);
+  } catch (error) {
+    const batch = buildErrorBatch(schema2, error, serverId, requestId);
+    await writer.writeStream(schema2, [batch]);
   }
 }
-async function statusRows(stateDir) {
-  const { readdirSync } = await import("node:fs");
-  const rows = [];
-  let entries;
-  try {
-    entries = readdirSync(stateDir);
-  } catch {
-    return rows;
+
+// src/wire/writer.ts
+var STDOUT_FD = 1;
+var _NODE_FS_MOD2 = "node:fs";
+var _writeSync = null;
+function _loadWriteSync2() {
+  if (_writeSync)
+    return _writeSync;
+  const req = import.meta.require ?? globalThis.require ?? null;
+  if (!req) {
+    throw new Error("IpcStreamWriter requires Bun or Node.js CJS for sync node:fs.writeSync. " + "Subprocess transport is not available in this runtime.");
   }
-  for (const name of entries.sort()) {
-    if (!name.endsWith(".lock"))
-      continue;
-    const hashId = name.slice(0, -5);
-    const { sockPath, metaPath } = socketPaths(stateDir, hashId);
-    const meta = tryReadMeta(metaPath);
-    rows.push({
-      hashId,
-      cmd: meta.cmd,
-      cwd: meta.cwd,
-      socket: sockPath,
-      startedAt: meta.startedAt,
-      alive: await probeSocket(sockPath)
-    });
+  const fs = req(_NODE_FS_MOD2);
+  _writeSync = fs.writeSync.bind(fs);
+  return _writeSync;
+}
+function writeAll(fd, data) {
+  const writeSync = _loadWriteSync2();
+  let offset = 0;
+  while (offset < data.length) {
+    try {
+      const written = writeSync(fd, data, offset, data.length - offset);
+      if (written <= 0)
+        throw new Error(`writeSync returned ${written}`);
+      offset += written;
+    } catch (e) {
+      if (e.code === "EAGAIN") {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 1);
+        continue;
+      }
+      throw e;
+    }
   }
-  return rows;
 }
-async function gcStateDir(stateDir, tryAcquire, options) {
-  const { readdirSync } = await import("node:fs");
-  const cleaned = [];
-  const skipped = [];
-  const limit = options?.limit ?? null;
-  const excludeHash = options?.excludeHash ?? null;
-  let entries;
-  try {
-    entries = readdirSync(stateDir);
-  } catch {
-    return { cleaned, skippedInUse: skipped };
+async function socketWriteAll(socket, data) {
+  if (socket.destroyed || socket.writableEnded) {
+    throw new Error("socketWriteAll: socket is already closed");
   }
-  let seen = 0;
-  for (const name of entries.sort()) {
-    if (!name.endsWith(".lock"))
-      continue;
-    if (limit !== null && seen >= limit)
-      break;
-    seen += 1;
-    const hashId = name.slice(0, -5);
-    if (excludeHash !== null && hashId === excludeHash)
-      continue;
-    const { lockPath, sockPath, metaPath } = socketPaths(stateDir, hashId);
-    const release = await tryAcquire(lockPath);
-    if (release === null) {
-      skipped.push(hashId);
-      continue;
+  const ok = socket.write(data);
+  if (ok)
+    return;
+  await new Promise((resolve, reject) => {
+    const cleanup = () => {
+      socket.off("drain", onDrain);
+      socket.off("error", onError);
+      socket.off("close", onClose);
+    };
+    const onDrain = () => {
+      cleanup();
+      resolve();
+    };
+    const onError = (err2) => {
+      cleanup();
+      reject(err2);
+    };
+    const onClose = () => {
+      cleanup();
+      resolve();
+    };
+    socket.once("drain", onDrain);
+    socket.once("error", onError);
+    socket.once("close", onClose);
+  });
+}
+
+class IpcStreamWriter {
+  target;
+  constructor(fdOrSocket = STDOUT_FD) {
+    if (typeof fdOrSocket === "number") {
+      this.target = { kind: "fd", fd: fdOrSocket };
+    } else {
+      this.target = { kind: "socket", socket: fdOrSocket };
     }
-    try {
-      if (await probeSocket(sockPath)) {
-        continue;
-      }
-      for (const p of [sockPath, metaPath, lockPath]) {
-        try {
-          unlinkSync(p);
-        } catch {}
-      }
-      cleaned.push(hashId);
-    } finally {
-      release();
+  }
+  async writeStream(schema2, batches) {
+    const bytes2 = serializeBatches(schema2, batches);
+    if (this.target.kind === "fd") {
+      writeAll(this.target.fd, bytes2);
+    } else {
+      await socketWriteAll(this.target.socket, bytes2);
     }
   }
-  return { cleaned, skippedInUse: skipped };
+  openStream(schema2) {
+    return new IncrementalStream(this.target, schema2);
+  }
 }
 
-// src/launcher/launch.ts
-var DEFAULT_GC_LIMIT = 16;
-async function launch(config) {
-  if (!config.workerArgv || config.workerArgv.length === 0) {
-    throw new Error("workerArgv must be non-empty");
+class IncrementalStream {
+  encoder;
+  target;
+  closed = false;
+  writeChain = Promise.resolve();
+  constructor(target, schema2) {
+    this.target = target;
+    this.encoder = createIncrementalEncoder(schema2);
+    this.enqueue(this.encoder.start());
   }
-  const stateDir = config.stateDir ?? defaultStateDir();
-  const idleTimeout = config.idleTimeout ?? 300;
-  const connectTimeoutMs = (config.connectTimeout ?? 30) * 1000;
-  const startupTimeoutMs = (config.workerStartupTimeout ?? 60) * 1000;
-  let lockPath;
-  let sockPath;
-  let metaPath;
-  let hashId;
-  if (config.socketPath !== undefined) {
-    const { resolve } = await import("node:path");
-    sockPath = resolve(config.socketPath);
-    lockPath = `${sockPath}.lock`;
-    metaPath = null;
-    hashId = null;
-  } else {
-    hashId = await computeHash(config.workerArgv);
-    const paths = socketPaths(stateDir, hashId);
-    lockPath = paths.lockPath;
-    sockPath = paths.sockPath;
-    metaPath = paths.metaPath;
+  async write(batch) {
+    if (this.closed)
+      throw new Error("Stream already closed");
+    return this.enqueue(this.encoder.writeBatch(batch));
   }
-  const handle = await acquireLock(lockPath, connectTimeoutMs);
-  try {
-    if (await probeSocket(sockPath)) {
-      return sockPath;
-    }
-    try {
-      unlinkSync2(sockPath);
-    } catch {}
-    if (metaPath !== null) {
-      writeMeta(metaPath, config.workerArgv, process.cwd(), sockPath);
-    }
-    await spawnWorker(config.workerArgv, sockPath, idleTimeout, config.workerStderr ?? null, startupTimeoutMs);
-    return sockPath;
-  } finally {
-    handle.release();
-    if (hashId !== null) {
-      try {
-        await gcStateDir(stateDir, async (p) => {
-          const h = tryAcquireLock(p);
-          return h ? () => h.release() : null;
-        }, { limit: DEFAULT_GC_LIMIT, excludeHash: hashId });
-      } catch {}
-    }
+  async close() {
+    if (this.closed)
+      return;
+    this.closed = true;
+    return this.enqueue(this.encoder.finish());
+  }
+  enqueue(bytes2) {
+    const next = this.writeChain.then(() => {
+      if (this.target.kind === "fd") {
+        writeAll(this.target.fd, bytes2);
+        return;
+      }
+      return socketWriteAll(this.target.socket, bytes2);
+    });
+    this.writeChain = next.catch(() => {
+      return;
+    });
+    return next;
   }
 }
-async function spawnWorker(workerArgv, sockPath, idleTimeout, workerStderr, startupTimeoutMs) {
-  const fullArgv = [...workerArgv, "--unix", sockPath, "--idle-timeout", String(idleTimeout)];
-  const [cmd, ...rest] = fullArgv;
-  const stderrTarget = workerStderr === null ? "ignore" : "pipe";
-  const proc = spawn(cmd, rest, {
-    stdio: ["ignore", "pipe", stderrTarget],
-    detached: false
-  });
-  if (workerStderr !== null && proc.stderr) {
-    const sink = createWriteStream(workerStderr, { flags: "a" });
-    proc.stderr.pipe(sink);
+
+// src/server.ts
+var EMPTY_SCHEMA5 = schema([]);
+function randomStreamId() {
+  const bytes2 = new Uint8Array(16);
+  crypto.getRandomValues(bytes2);
+  let out = "";
+  for (let i = 0;i < bytes2.length; i++) {
+    out += bytes2[i].toString(16).padStart(2, "0");
   }
-  const expectedPrefix = `UNIX:${sockPath}`;
-  const reader = lineReader(proc.stdout);
-  const deadline = Date.now() + startupTimeoutMs;
-  while (Date.now() < deadline) {
-    const remaining = deadline - Date.now();
-    const result = await Promise.race([
-      reader.next().then((r) => ({ kind: "line", value: r })),
-      onceExit(proc).then((rc) => ({ kind: "exit", rc })),
-      delay(remaining).then(() => ({ kind: "timeout" }))
-    ]);
-    if (result.kind === "exit") {
-      throw new Error(`worker exited before readiness (rc=${result.rc})`);
+  return out;
+}
+
+class VgiRpcServer {
+  protocol;
+  enableDescribe;
+  serverId;
+  _describePromise = null;
+  protocolVersion;
+  dispatchHook = null;
+  externalConfig;
+  onServeStart = null;
+  serveStartFired = false;
+  constructor(protocol, options) {
+    this.protocol = protocol;
+    this.enableDescribe = options?.enableDescribe ?? true;
+    this.serverId = options?.serverId ?? crypto.randomUUID().replace(/-/g, "").slice(0, 12);
+    this.dispatchHook = options?.dispatchHook ?? null;
+    this.externalConfig = options?.externalLocation;
+    this.protocolVersion = options?.protocolVersion ?? "";
+    this.onServeStart = options?.onServeStart ?? null;
+  }
+  async notifyTransport(kind) {
+    if (this.serveStartFired)
+      return;
+    if (this.onServeStart) {
+      await this.onServeStart(kind);
     }
-    if (result.kind === "timeout") {
-      proc.kill("SIGTERM");
-      throw new Error(`worker did not emit UNIX:<path> within ${startupTimeoutMs}ms`);
+    this.serveStartFired = true;
+  }
+  async describeInfo() {
+    if (!this._describePromise) {
+      this._describePromise = buildDescribeBatch(this.protocol.name, this.protocol.getMethods(), this.serverId, this.protocol.protocolVersion || undefined).then(({ batch, metadata }) => ({
+        batch,
+        protocolHash: metadata.get("vgi_rpc.protocol_hash") ?? ""
+      }));
     }
-    if (result.value.done) {
-      const rc = await onceExit(proc);
-      throw new Error(`worker exited before readiness (rc=${rc})`);
+    return this._describePromise;
+  }
+  checkProtocolVersion(clientVersion) {
+    const serverParts = this.protocol.protocolVersionParts;
+    const serverVersion = this.protocol.protocolVersion;
+    if (clientVersion === undefined) {
+      throw new ProtocolVersionError(`VGI client/worker protocol_version mismatch.
+` + `  Client: <not declared>
+` + `  Server: ${serverVersion}
+` + "  Direction: the client did not send a vgi_rpc.protocol_version " + "metadata key. This is either a vgi-rpc framework bug or a " + "non-VGI client connecting to a VGI worker.");
     }
-    const line = result.value.value;
-    if (line.startsWith("UNIX:")) {
-      if (line !== expectedPrefix) {
-        proc.kill("SIGTERM");
-        throw new Error(`worker bound to unexpected path: ${JSON.stringify(line)} (expected ${JSON.stringify(expectedPrefix)})`);
-      }
-      reader.drainAndDiscard();
+    let clientParts;
+    try {
+      clientParts = parseProtocolVersion(clientVersion);
+    } catch {
+      throw new ProtocolVersionError(`VGI client/worker protocol_version mismatch.
+` + `  Client: ${clientVersion}
+` + `  Server: ${serverVersion}
+` + "  Direction: client sent a malformed protocol_version. " + "Expected canonical semver MAJOR.MINOR.PATCH.");
+    }
+    if (clientParts[0] === serverParts[0] && clientParts[1] === serverParts[1]) {
       return;
     }
-    process.env.VGI_RPC_LAUNCHER_DEBUG && process.stderr.write(`launcher: skipping pre-bind stdout line: ${JSON.stringify(line)}
-`);
+    const clientOlder = clientParts[0] < serverParts[0] || clientParts[0] === serverParts[0] && clientParts[1] < serverParts[1];
+    const direction = clientOlder ? `client is too old; upgrade the VGI extension/client to a version supporting protocol_version ${serverVersion}.` : `server is too old; upgrade the VGI worker to a version supporting protocol_version ${clientVersion}.`;
+    throw new ProtocolVersionError(`VGI client/worker protocol_version mismatch.
+` + `  Client: ${clientVersion}
+` + `  Server: ${serverVersion}
+` + `  Direction: ${direction}`);
   }
-  proc.kill("SIGTERM");
-  throw new Error(`worker did not emit UNIX:<path> within ${startupTimeoutMs}ms`);
-}
-function lineReader(stream) {
-  let buffer = "";
-  let ended = false;
-  const queued = [];
-  const waiters = [];
-  let discardMode = false;
-  const flushWaiter = () => {
-    if (waiters.length === 0)
-      return;
-    if (queued.length > 0) {
-      const w = waiters.shift();
-      w?.({ done: false, value: queued.shift() ?? "" });
-    } else if (ended) {
-      const w = waiters.shift();
-      w?.({ done: true, value: "" });
-    }
-  };
-  stream.setEncoding?.("utf8");
-  stream.on("data", (chunk) => {
-    if (discardMode)
-      return;
-    buffer += String(chunk);
-    for (;; ) {
-      const nl = buffer.indexOf(`
+  async run() {
+    const stdin = process.stdin;
+    if (process.stdin.isTTY || process.stdout.isTTY) {
+      process.stderr.write("WARNING: This process communicates via Arrow IPC on stdin/stdout " + `and is not intended to be run interactively.
+` + "It should be launched as a subprocess by an RPC client " + `(e.g. vgi_rpc.connect()).
 `);
-      if (nl < 0)
-        break;
-      const line = buffer.slice(0, nl).replace(/\r$/, "");
-      buffer = buffer.slice(nl + 1);
-      queued.push(line);
-    }
-    flushWaiter();
-  });
-  stream.on("end", () => {
-    ended = true;
-    if (buffer.length > 0) {
-      queued.push(buffer.replace(/\r$/, ""));
-      buffer = "";
     }
-    flushWaiter();
-  });
-  stream.on("error", () => {
-    ended = true;
-    flushWaiter();
-  });
-  return {
-    next() {
-      return new Promise((resolve) => {
-        waiters.push(resolve);
-        flushWaiter();
-      });
-    },
-    drainAndDiscard() {
-      discardMode = true;
-      queued.length = 0;
-      stream.resume?.();
+    const reader = await IpcStreamReader.create(stdin);
+    const writer = new IpcStreamWriter;
+    try {
+      while (true) {
+        await this.notifyTransport("pipe" /* PIPE */);
+        await this.serveOne(reader, writer);
+      }
+    } catch (e) {
+      if (e.message?.includes("closed") || e.message?.includes("Expected Schema Message") || e.message?.includes("null or length 0") || e.code === "EPIPE" || e.code === "ERR_STREAM_PREMATURE_CLOSE" || e.code === "ERR_STREAM_DESTROYED" || e instanceof Error && e.message.includes("EOF")) {
+        return;
+      }
+      throw e;
+    } finally {
+      await reader.cancel();
     }
-  };
-}
-function onceExit(proc) {
-  return new Promise((resolve) => {
-    proc.once("exit", (code) => resolve(code));
-  });
-}
-function delay(ms) {
-  return new Promise((r) => setTimeout(r, Math.max(0, ms)));
-}
-// src/launcher/serve-unix.ts
-import { existsSync as existsSync2, unlinkSync as unlinkSync3 } from "node:fs";
-import { createServer } from "node:net";
-import * as path2 from "node:path";
-
-// src/dispatch/stream.ts
-var EMPTY_SCHEMA3 = schema([]);
-async function dispatchStream(method, params, writer, reader, serverId, requestId, externalConfig, kind) {
-  const isProducer = !!method.producerFn;
-  let state;
-  try {
-    if (isProducer) {
-      state = await method.producerInit(params);
-    } else {
-      state = await method.exchangeInit(params);
+  }
+  async serveOne(reader, writer) {
+    const stream = await reader.readStream();
+    if (!stream) {
+      throw new Error("EOF");
     }
-  } catch (error) {
-    const errSchema = method.headerSchema ?? EMPTY_SCHEMA3;
-    const errBatch = buildErrorBatch(errSchema, error, serverId, requestId);
-    await writer.writeStream(errSchema, [errBatch]);
-    const inputSchema2 = await reader.openNextStream();
-    if (inputSchema2) {
-      while (await reader.readNextBatch() !== null) {}
+    const { schema: schema2, batches } = stream;
+    if (batches.length === 0) {
+      const err2 = new RpcError("ProtocolError", "Request stream contains no batches", "");
+      const errBatch = buildErrorBatch(EMPTY_SCHEMA5, err2, this.serverId, null);
+      await writer.writeStream(EMPTY_SCHEMA5, [errBatch]);
+      return;
     }
-    return;
-  }
-  const outputSchema = state?.__outputSchema ?? method.outputSchema;
-  const effectiveProducer = state?.__isProducer ?? isProducer;
-  if (method.headerSchema && method.headerInit) {
+    const batch = batches[0];
+    let methodName;
+    let params;
+    let requestId;
     try {
-      const headerOut = new OutputCollector(method.headerSchema, true, serverId, requestId, undefined, undefined, kind);
-      const headerValues = method.headerInit(params, state, headerOut);
-      const headerBatch = buildResultBatch(method.headerSchema, headerValues, serverId, requestId);
-      const headerBatches = [...headerOut.batches.map((b) => b.batch), headerBatch];
-      await writer.writeStream(method.headerSchema, headerBatches);
-    } catch (error) {
-      const errBatch = buildErrorBatch(method.headerSchema, error, serverId, requestId);
-      await writer.writeStream(method.headerSchema, [errBatch]);
-      const inputSchema2 = await reader.openNextStream();
-      if (inputSchema2) {
-        while (await reader.readNextBatch() !== null) {}
+      const parsed = parseRequest(schema2, batch);
+      methodName = parsed.methodName;
+      params = parsed.params;
+      requestId = parsed.requestId;
+    } catch (e) {
+      const errBatch = buildErrorBatch(EMPTY_SCHEMA5, e, this.serverId, null);
+      await writer.writeStream(EMPTY_SCHEMA5, [errBatch]);
+      if (e instanceof VersionError || e instanceof RpcError) {
+        return;
       }
+      throw e;
+    }
+    if (methodName === DESCRIBE_METHOD_NAME && this.enableDescribe) {
+      const { batch: batch2 } = await this.describeInfo();
+      await writer.writeStream(batch2.schema, [batch2]);
       return;
     }
-  }
-  const inputSchema = await reader.openNextStream();
-  if (!inputSchema) {
-    const errBatch = buildErrorBatch(outputSchema, new Error("Expected input stream but got EOF"), serverId, requestId);
-    await writer.writeStream(outputSchema, [errBatch]);
-    return;
-  }
-  const stream = writer.openStream(outputSchema);
-  const expectedInputSchema = state?.__inputSchema ?? method.inputSchema;
-  try {
-    while (true) {
-      let inputBatch = await reader.readNextBatch();
-      if (!inputBatch)
-        break;
-      if (inputBatch.metadata?.get(CANCEL_KEY)) {
-        if (method.onCancel) {
-          try {
-            await method.onCancel(state);
-          } catch (err2) {
-            console.debug?.(`onCancel hook failed: ${err2 instanceof Error ? err2.message : err2}`);
-          }
-        }
-        break;
-      }
-      if (expectedInputSchema && !effectiveProducer && inputBatch.schema !== expectedInputSchema) {
-        try {
-          inputBatch = conformBatchToSchema(inputBatch, expectedInputSchema);
-        } catch (e) {
-          if (e instanceof TypeError)
-            throw e;
-          console.debug?.(`Schema conformance skipped: ${e instanceof Error ? e.message : e}`);
-        }
+    const methods = this.protocol.getMethods();
+    const method = methods.get(methodName);
+    if (!method) {
+      const available = [...methods.keys()].sort();
+      const err2 = new MethodNotImplementedError(`Unknown method: '${methodName}'. Available methods: [${available.join(", ")}]`);
+      const errBatch = buildErrorBatch(EMPTY_SCHEMA5, err2, this.serverId, requestId);
+      await writer.writeStream(EMPTY_SCHEMA5, [errBatch]);
+      return;
+    }
+    if (this.protocol.protocolVersionParts !== null) {
+      try {
+        const md = batch.metadata;
+        this.checkProtocolVersion(md?.get(PROTOCOL_VERSION_KEY));
+      } catch (exc) {
+        const errSchema = method.type === "unary" /* UNARY */ ? method.resultSchema : EMPTY_SCHEMA5;
+        const errBatch = buildErrorBatch(errSchema, exc, this.serverId, requestId);
+        await writer.writeStream(errSchema, [errBatch]);
+        return;
       }
-      const out = new OutputCollector(outputSchema, effectiveProducer, serverId, requestId, undefined, undefined, kind);
-      if (isProducer) {
-        await method.producerFn(state, out);
+    }
+    const methodType = method.type === "unary" /* UNARY */ ? "unary" : "stream";
+    let requestData;
+    try {
+      requestData = serializeBatch(batch);
+    } catch {}
+    let streamId;
+    if (methodType === "stream") {
+      streamId = randomStreamId();
+    }
+    const { protocolHash } = await this.describeInfo();
+    const info = {
+      method: methodName,
+      methodType,
+      serverId: this.serverId,
+      requestId,
+      protocol: this.protocol.name,
+      protocolHash,
+      protocolVersion: this.protocolVersion,
+      kind: "pipe" /* PIPE */,
+      principal: "",
+      authDomain: "",
+      authenticated: false,
+      remoteAddr: "",
+      requestData,
+      streamId
+    };
+    const stats = {
+      inputBatches: 0,
+      outputBatches: 0,
+      inputRows: 0,
+      outputRows: 0,
+      inputBytes: 0,
+      outputBytes: 0
+    };
+    const token = this.dispatchHook?.onDispatchStart(info);
+    let dispatchError;
+    applyDefaults(params, method.defaults);
+    try {
+      if (method.type === "unary" /* UNARY */) {
+        await dispatchUnary(method, params, writer, this.serverId, requestId, this.externalConfig, "pipe" /* PIPE */);
       } else {
-        await method.exchangeFn(state, inputBatch, out);
-      }
-      for (const emitted of out.batches) {
-        let batch = emitted.batch;
-        if (externalConfig) {
-          batch = await maybeExternalizeBatch(batch, externalConfig);
-        }
-        if (emitted.metadata && emitted.metadata.size > 0) {
-          batch = withBatchMetadata(batch, emitted.metadata);
-        }
-        await stream.write(batch);
-      }
-      if (out.finished) {
-        break;
+        await dispatchStream(method, params, writer, reader, this.serverId, requestId, this.externalConfig, "pipe" /* PIPE */);
       }
+    } catch (e) {
+      dispatchError = e instanceof Error ? e : new Error(String(e));
+      throw e;
+    } finally {
+      this.dispatchHook?.onDispatchEnd(token, info, stats, dispatchError);
     }
-  } catch (error) {
-    await stream.write(buildErrorBatch(outputSchema, error, serverId, requestId));
   }
-  await stream.close();
-  try {
-    while (await reader.readNextBatch() !== null) {}
-  } catch {}
 }
-
-// src/dispatch/unary.ts
-async function dispatchUnary(method, params, writer, serverId, requestId, externalConfig, kind) {
-  const schema2 = method.resultSchema;
-  const out = new OutputCollector(schema2, true, serverId, requestId, undefined, undefined, kind);
-  try {
-    const result = await method.handler(params, out);
-    let resultBatch = buildResultBatch(schema2, result, serverId, requestId);
-    if (externalConfig) {
-      resultBatch = await maybeExternalizeBatch(resultBatch, externalConfig);
+// src/launcher/hash.ts
+var HASH_LEN = 16;
+function canonicalJson(value) {
+  if (value === null)
+    return "null";
+  if (typeof value === "boolean")
+    return value ? "true" : "false";
+  if (typeof value === "number") {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "string")
+    return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return `[${value.map(canonicalJson).join(",")}]`;
+  }
+  if (typeof value === "object") {
+    const keys = Object.keys(value).sort();
+    const parts = keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`);
+    return `{${parts.join(",")}}`;
+  }
+  throw new TypeError(`canonicalJson: unsupported type ${typeof value}`);
+}
+async function sha256Hex3(data) {
+  const buf2 = new ArrayBuffer(data.byteLength);
+  new Uint8Array(buf2).set(data);
+  const digest = await crypto.subtle.digest("SHA-256", buf2);
+  return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function computeHash(workerArgv, cwd, env) {
+  const cwdValue = cwd !== undefined ? cwd : process.cwd();
+  const sourceEnv = env ?? process.env;
+  const filteredEnv = {};
+  for (const key of Object.keys(sourceEnv)) {
+    if (key.startsWith("VGI_RPC_")) {
+      const v = sourceEnv[key];
+      if (v !== undefined)
+        filteredEnv[key] = v;
     }
-    const batches = [...out.batches.map((b) => b.batch), resultBatch];
-    await writer.writeStream(schema2, batches);
-  } catch (error) {
-    const batch = buildErrorBatch(schema2, error, serverId, requestId);
-    await writer.writeStream(schema2, [batch]);
   }
+  const canonical = {
+    cmd: [...workerArgv],
+    cwd: cwdValue,
+    env: filteredEnv
+  };
+  const payload = new TextEncoder().encode(canonicalJson(canonical));
+  const hex = await sha256Hex3(payload);
+  return hex.slice(0, HASH_LEN);
 }
+// src/launcher/launch.ts
+import { spawn } from "node:child_process";
+import { createWriteStream, unlinkSync as unlinkSync2 } from "node:fs";
 
-// src/wire/writer.ts
-var STDOUT_FD = 1;
-var _NODE_FS_MOD2 = "node:fs";
-var _writeSync = null;
-function _loadWriteSync2() {
-  if (_writeSync)
-    return _writeSync;
-  const req = import.meta.require ?? globalThis.require ?? null;
-  if (!req) {
-    throw new Error("IpcStreamWriter requires Bun or Node.js CJS for sync node:fs.writeSync. " + "Subprocess transport is not available in this runtime.");
+// src/launcher/lock.ts
+import { closeSync, constants as FS, openSync, readSync, statSync, writeSync } from "node:fs";
+var POLL_MS = 50;
+var VERIFY_RETRIES = 5;
+function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0)
+    return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err2) {
+    return err2?.code === "EPERM";
   }
-  const fs = req(_NODE_FS_MOD2);
-  _writeSync = fs.writeSync.bind(fs);
-  return _writeSync;
 }
-function writeAll(fd, data) {
-  const writeSync2 = _loadWriteSync2();
-  let offset = 0;
-  while (offset < data.length) {
+function readPid(path) {
+  try {
+    const fd = openSync(path, FS.O_RDONLY);
     try {
-      const written = writeSync2(fd, data, offset, data.length - offset);
-      if (written <= 0)
-        throw new Error(`writeSync returned ${written}`);
-      offset += written;
-    } catch (e) {
-      if (e.code === "EAGAIN") {
-        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 1);
-        continue;
-      }
-      throw e;
+      const buf2 = Buffer.alloc(64);
+      const n = readSync(fd, buf2, 0, buf2.length, 0);
+      const text = buf2.subarray(0, n).toString("utf8").trim();
+      if (text === "")
+        return 0;
+      const parsed = Number(text);
+      return Number.isInteger(parsed) ? parsed : 0;
+    } finally {
+      closeSync(fd);
     }
+  } catch {
+    return 0;
   }
 }
-async function socketWriteAll(socket, data) {
-  if (socket.destroyed || socket.writableEnded) {
-    throw new Error("socketWriteAll: socket is already closed");
+function tryStampPid(path) {
+  const fd = openSync(path, FS.O_RDWR | FS.O_CREAT, 384);
+  try {
+    const stamp = Buffer.from(String(process.pid), "utf8");
+    const { ftruncateSync } = __require("node:fs");
+    ftruncateSync(fd, 0);
+    let written = 0;
+    while (written < stamp.length) {
+      const n = writeSync(fd, stamp, written, stamp.length - written, 0 + written);
+      if (n <= 0)
+        throw new Error(`writeSync returned ${n}`);
+      written += n;
+    }
+    const st = statSync(path);
+    if (st.size !== stamp.length)
+      return false;
+    return true;
+  } finally {
+    closeSync(fd);
   }
-  const ok = socket.write(data);
-  if (ok)
-    return;
-  await new Promise((resolve, reject) => {
-    const cleanup = () => {
-      socket.off("drain", onDrain);
-      socket.off("error", onError);
-      socket.off("close", onClose);
-    };
-    const onDrain = () => {
-      cleanup();
-      resolve();
-    };
-    const onError = (err2) => {
-      cleanup();
-      reject(err2);
-    };
-    const onClose = () => {
-      cleanup();
-      resolve();
+}
+function clearStamp(path) {
+  try {
+    const fd = openSync(path, FS.O_RDWR);
+    try {
+      const { ftruncateSync } = __require("node:fs");
+      ftruncateSync(fd, 0);
+    } finally {
+      closeSync(fd);
+    }
+  } catch {}
+}
+function tryAcquireLock(lockPath) {
+  for (let attempt = 0;attempt < VERIFY_RETRIES; attempt++) {
+    const existingPid = readPid(lockPath);
+    if (existingPid > 0 && pidAlive(existingPid)) {
+      return null;
+    }
+    if (!tryStampPid(lockPath))
+      continue;
+    const verifyPid = readPid(lockPath);
+    if (verifyPid !== process.pid) {
+      continue;
+    }
+    let released = false;
+    return {
+      path: lockPath,
+      release() {
+        if (released)
+          return;
+        released = true;
+        clearStamp(lockPath);
+      }
     };
-    socket.once("drain", onDrain);
-    socket.once("error", onError);
-    socket.once("close", onClose);
-  });
+  }
+  return null;
 }
-
-class IpcStreamWriter {
-  target;
-  constructor(fdOrSocket = STDOUT_FD) {
-    if (typeof fdOrSocket === "number") {
-      this.target = { kind: "fd", fd: fdOrSocket };
-    } else {
-      this.target = { kind: "socket", socket: fdOrSocket };
+async function acquireLock(lockPath, timeoutMs) {
+  const deadline = Date.now() + Math.max(0, timeoutMs);
+  for (;; ) {
+    const handle = tryAcquireLock(lockPath);
+    if (handle)
+      return handle;
+    if (Date.now() >= deadline) {
+      throw new Error(`failed to acquire ${lockPath} within ${timeoutMs}ms`);
     }
+    await new Promise((r) => setTimeout(r, POLL_MS));
   }
-  async writeStream(schema2, batches) {
-    const bytes = serializeBatches(schema2, batches);
-    if (this.target.kind === "fd") {
-      writeAll(this.target.fd, bytes);
+}
+
+// src/launcher/state.ts
+import { existsSync, mkdirSync, readFileSync, statSync as statSync2, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import * as path from "node:path";
+function socketPaths(stateDir, hashId) {
+  return {
+    lockPath: path.join(stateDir, `${hashId}.lock`),
+    sockPath: path.join(stateDir, `${hashId}.sock`),
+    metaPath: path.join(stateDir, `${hashId}.meta`)
+  };
+}
+function defaultStateDir() {
+  let base;
+  if (process.platform === "win32") {
+    base = path.join(tmpdir(), "vgi-rpc");
+  } else {
+    const xdg = process.env.XDG_RUNTIME_DIR;
+    if (xdg) {
+      base = path.join(xdg, "vgi-rpc");
     } else {
-      await socketWriteAll(this.target.socket, bytes);
+      const uid = typeof process.geteuid === "function" ? process.geteuid() : 0;
+      base = path.join(tmpdir(), `vgi-rpc-${uid}`);
     }
   }
-  openStream(schema2) {
-    return new IncrementalStream(this.target, schema2);
+  mkdirSync(base, { recursive: true, mode: 448 });
+  if (process.platform !== "win32" && typeof process.geteuid === "function") {
+    try {
+      const st = statSync2(base);
+      if (st.uid !== process.geteuid()) {
+        throw new Error(`state directory ${base} is not owned by current user`);
+      }
+    } catch (err2) {
+      if (err2?.code === "ENOENT") {} else {
+        throw err2;
+      }
+    }
   }
+  return base;
 }
-
-class IncrementalStream {
-  encoder;
-  target;
-  closed = false;
-  writeChain = Promise.resolve();
-  constructor(target, schema2) {
-    this.target = target;
-    this.encoder = createIncrementalEncoder(schema2);
-    this.enqueue(this.encoder.start());
-  }
-  async write(batch) {
-    if (this.closed)
-      throw new Error("Stream already closed");
-    return this.enqueue(this.encoder.writeBatch(batch));
-  }
-  async close() {
-    if (this.closed)
-      return;
-    this.closed = true;
-    return this.enqueue(this.encoder.finish());
-  }
-  enqueue(bytes) {
-    const next = this.writeChain.then(() => {
-      if (this.target.kind === "fd") {
-        writeAll(this.target.fd, bytes);
-        return;
-      }
-      return socketWriteAll(this.target.socket, bytes);
+function writeMeta(metaPath, workerArgv, cwd, sockPath) {
+  const payload = {
+    cmd: [...workerArgv],
+    cwd,
+    socket: sockPath,
+    started_at: Date.now() / 1000,
+    launcher_pid: process.pid
+  };
+  try {
+    writeFileSync(metaPath, JSON.stringify(payload, null, 2), { encoding: "utf8", mode: 384 });
+  } catch {}
+}
+async function probeSocket(sockPath, timeoutMs = 2000) {
+  if (!existsSync(sockPath))
+    return false;
+  const net = await import("node:net");
+  return new Promise((resolve) => {
+    const sock = net.createConnection({ path: sockPath });
+    const timer = setTimeout(() => {
+      sock.destroy();
+      resolve(false);
+    }, timeoutMs);
+    sock.once("connect", () => {
+      clearTimeout(timer);
+      sock.end();
+      resolve(true);
     });
-    this.writeChain = next.catch(() => {
-      return;
+    sock.once("error", () => {
+      clearTimeout(timer);
+      resolve(false);
     });
-    return next;
-  }
+  });
 }
-
-// src/launcher/serve-unix.ts
-var EMPTY_SCHEMA4 = schema([]);
-async function serveUnix(protocol, options) {
-  const sockPath = path2.resolve(options.unixPath);
-  const idleTimeoutS = options.idleTimeout ?? 300;
-  const startupGraceS = options.startupGraceSeconds ?? 5;
-  const protocolVersion = options.protocolVersion ?? "";
-  const serverId = options.serverId ?? crypto.randomUUID().replace(/-/g, "").slice(0, 12);
-  const enableDescribe = options.enableDescribe ?? true;
-  const dispatchHook = options.dispatchHook ?? null;
-  const externalConfig = options.externalLocation;
-  const onServeStart = options.onServeStart ?? null;
-  const backlog = options.backlog ?? 16;
-  const announcementSink = options.announcementSink ?? process.stdout;
-  if (existsSync2(sockPath)) {
-    try {
-      unlinkSync3(sockPath);
-    } catch {}
+function tryReadMeta(metaPath) {
+  try {
+    const raw = readFileSync(metaPath, "utf8");
+    const meta = JSON.parse(raw);
+    return {
+      cmd: Array.isArray(meta.cmd) ? meta.cmd.map(String) : [],
+      cwd: typeof meta.cwd === "string" ? meta.cwd : "",
+      startedAt: typeof meta.started_at === "number" ? meta.started_at : null
+    };
+  } catch {
+    return { cmd: [], cwd: "", startedAt: null };
   }
-  let describePromise = null;
-  function describeInfo() {
-    if (!describePromise) {
-      describePromise = buildDescribeBatch(protocol.name, protocol.getMethods(), serverId).then(({ batch, metadata }) => ({
-        batch,
-        protocolHash: metadata.get("vgi_rpc.protocol_hash") ?? ""
-      }));
-    }
-    return describePromise;
+}
+async function statusRows(stateDir) {
+  const { readdirSync } = await import("node:fs");
+  const rows = [];
+  let entries;
+  try {
+    entries = readdirSync(stateDir);
+  } catch {
+    return rows;
   }
-  let serveStartFired = false;
-  async function notifyTransport() {
-    if (serveStartFired)
-      return;
-    if (onServeStart) {
-      await onServeStart("unix" /* UNIX */);
-    }
-    serveStartFired = true;
+  for (const name of entries.sort()) {
+    if (!name.endsWith(".lock"))
+      continue;
+    const hashId = name.slice(0, -5);
+    const { sockPath, metaPath } = socketPaths(stateDir, hashId);
+    const meta = tryReadMeta(metaPath);
+    rows.push({
+      hashId,
+      cmd: meta.cmd,
+      cwd: meta.cwd,
+      socket: sockPath,
+      startedAt: meta.startedAt,
+      alive: await probeSocket(sockPath)
+    });
   }
-  const server = createServer({ allowHalfOpen: false });
-  let activeConnections = 0;
-  let idleTimer = null;
-  let resolveDone = () => {};
-  let rejectDone = () => {};
-  const done = new Promise((resolve2, reject) => {
-    resolveDone = resolve2;
-    rejectDone = reject;
-  });
-  let stopped = false;
-  function armIdleTimer() {
-    if (idleTimeoutS <= 0)
-      return;
-    if (idleTimer)
-      clearTimeout(idleTimer);
-    idleTimer = setTimeout(() => {
-      if (activeConnections === 0 && !stopped) {
-        shutdown();
-      }
-    }, idleTimeoutS * 1000);
+  return rows;
+}
+async function gcStateDir(stateDir, tryAcquire, options) {
+  const { readdirSync } = await import("node:fs");
+  const cleaned = [];
+  const skipped = [];
+  const limit = options?.limit ?? null;
+  const excludeHash = options?.excludeHash ?? null;
+  let entries;
+  try {
+    entries = readdirSync(stateDir);
+  } catch {
+    return { cleaned, skippedInUse: skipped };
   }
-  function disarmIdleTimer() {
-    if (idleTimer) {
-      clearTimeout(idleTimer);
-      idleTimer = null;
+  let seen = 0;
+  for (const name of entries.sort()) {
+    if (!name.endsWith(".lock"))
+      continue;
+    if (limit !== null && seen >= limit)
+      break;
+    seen += 1;
+    const hashId = name.slice(0, -5);
+    if (excludeHash !== null && hashId === excludeHash)
+      continue;
+    const { lockPath, sockPath, metaPath } = socketPaths(stateDir, hashId);
+    const release = await tryAcquire(lockPath);
+    if (release === null) {
+      skipped.push(hashId);
+      continue;
     }
-  }
-  async function shutdown() {
-    if (stopped)
-      return;
-    stopped = true;
-    disarmIdleTimer();
-    await new Promise((resolve2) => {
-      server.close(() => resolve2());
-    });
     try {
-      unlinkSync3(sockPath);
-    } catch {}
-    resolveDone();
-  }
-  server.on("connection", (socket) => {
-    activeConnections += 1;
-    disarmIdleTimer();
-    handleConnection(socket).catch((err2) => {
-      process.stderr.write(`vgi-rpc/unix: connection failed: ${err2?.message ?? err2}
-`);
-    }).finally(() => {
-      activeConnections -= 1;
-      socket.destroy();
-      if (activeConnections === 0 && !stopped) {
-        armIdleTimer();
+      if (await probeSocket(sockPath)) {
+        continue;
       }
-    });
-  });
-  server.on("error", (err2) => {
-    if (stopped)
-      return;
-    rejectDone(err2);
-  });
-  async function handleConnection(socket) {
-    const reader = await IpcStreamReader.create(socket);
-    const writer = new IpcStreamWriter(socket);
-    try {
-      await notifyTransport();
-      while (true) {
+      for (const p of [sockPath, metaPath, lockPath]) {
         try {
-          await serveOnce(reader, writer);
-        } catch (e) {
-          const err2 = e;
-          if (err2?.message?.includes("closed") || err2?.message?.includes("Expected Schema Message") || err2?.message?.includes("null or length 0") || err2?.message?.includes("EOF") || err2?.code === "EPIPE" || err2?.code === "ERR_STREAM_PREMATURE_CLOSE" || err2?.code === "ERR_STREAM_DESTROYED") {
-            return;
-          }
-          throw e;
-        }
+          unlinkSync(p);
+        } catch {}
       }
+      cleaned.push(hashId);
     } finally {
-      try {
-        await reader.cancel();
-      } catch {}
+      release();
     }
   }
-  async function serveOnce(reader, writer) {
-    const stream = await reader.readStream();
-    if (!stream) {
-      throw new Error("EOF");
-    }
-    const { schema: schema2, batches } = stream;
-    if (batches.length === 0) {
-      const err2 = new RpcError("ProtocolError", "Request stream contains no batches", "");
-      const errBatch = buildErrorBatch(EMPTY_SCHEMA4, err2, serverId, null);
-      await writer.writeStream(EMPTY_SCHEMA4, [errBatch]);
-      return;
-    }
-    const batch = batches[0];
-    let methodName;
-    let params;
-    let requestId;
-    try {
-      const parsed = parseRequest(schema2, batch);
-      methodName = parsed.methodName;
-      params = parsed.params;
-      requestId = parsed.requestId;
-    } catch (e) {
-      const errBatch = buildErrorBatch(EMPTY_SCHEMA4, e, serverId, null);
-      await writer.writeStream(EMPTY_SCHEMA4, [errBatch]);
-      if (e instanceof VersionError || e instanceof RpcError)
-        return;
-      throw e;
-    }
-    if (methodName === DESCRIBE_METHOD_NAME && enableDescribe) {
-      const { batch: descBatch } = await describeInfo();
-      await writer.writeStream(descBatch.schema, [descBatch]);
-      return;
-    }
-    const methods = protocol.getMethods();
-    const method = methods.get(methodName);
-    if (!method) {
-      const available = [...methods.keys()].sort();
-      const err2 = new Error(`Unknown method: '${methodName}'. Available methods: [${available.join(", ")}]`);
-      const errBatch = buildErrorBatch(EMPTY_SCHEMA4, err2, serverId, requestId);
-      await writer.writeStream(EMPTY_SCHEMA4, [errBatch]);
-      return;
+  return { cleaned, skippedInUse: skipped };
+}
+
+// src/launcher/launch.ts
+var DEFAULT_GC_LIMIT = 16;
+async function launch(config) {
+  if (!config.workerArgv || config.workerArgv.length === 0) {
+    throw new Error("workerArgv must be non-empty");
+  }
+  const stateDir = config.stateDir ?? defaultStateDir();
+  const idleTimeout = config.idleTimeout ?? 300;
+  const connectTimeoutMs = (config.connectTimeout ?? 30) * 1000;
+  const startupTimeoutMs = (config.workerStartupTimeout ?? 60) * 1000;
+  let lockPath;
+  let sockPath;
+  let metaPath;
+  let hashId;
+  if (config.socketPath !== undefined) {
+    const { resolve } = await import("node:path");
+    sockPath = resolve(config.socketPath);
+    lockPath = `${sockPath}.lock`;
+    metaPath = null;
+    hashId = null;
+  } else {
+    hashId = await computeHash(config.workerArgv);
+    const paths = socketPaths(stateDir, hashId);
+    lockPath = paths.lockPath;
+    sockPath = paths.sockPath;
+    metaPath = paths.metaPath;
+  }
+  const handle = await acquireLock(lockPath, connectTimeoutMs);
+  try {
+    if (await probeSocket(sockPath)) {
+      return sockPath;
     }
-    const methodType = method.type === "unary" /* UNARY */ ? "unary" : "stream";
-    let requestData;
     try {
-      requestData = serializeBatch(batch);
+      unlinkSync2(sockPath);
     } catch {}
-    const { protocolHash } = await describeInfo();
-    const info = {
-      method: methodName,
-      methodType,
-      serverId,
-      requestId,
-      protocol: protocol.name,
-      protocolHash,
-      protocolVersion,
-      kind: "unix" /* UNIX */,
-      principal: "",
-      authDomain: "",
-      authenticated: false,
-      remoteAddr: "",
-      requestData
-    };
-    const stats = {
-      inputBatches: 0,
-      outputBatches: 0,
-      inputRows: 0,
-      outputRows: 0,
-      inputBytes: 0,
-      outputBytes: 0
-    };
-    const token = dispatchHook?.onDispatchStart(info);
-    let dispatchError;
-    applyDefaults(params, method.defaults);
-    try {
-      if (method.type === "unary" /* UNARY */) {
-        await dispatchUnary(method, params, writer, serverId, requestId, externalConfig, "unix" /* UNIX */);
-      } else {
-        await dispatchStream(method, params, writer, reader, serverId, requestId, externalConfig, "unix" /* UNIX */);
-      }
-    } catch (e) {
-      dispatchError = e instanceof Error ? e : new Error(String(e));
-      throw e;
-    } finally {
-      dispatchHook?.onDispatchEnd(token, info, stats, dispatchError);
+    if (metaPath !== null) {
+      writeMeta(metaPath, config.workerArgv, process.cwd(), sockPath);
+    }
+    await spawnWorker(config.workerArgv, sockPath, idleTimeout, config.workerStderr ?? null, startupTimeoutMs);
+    return sockPath;
+  } finally {
+    handle.release();
+    if (hashId !== null) {
+      try {
+        await gcStateDir(stateDir, async (p) => {
+          const h = tryAcquireLock(p);
+          return h ? () => h.release() : null;
+        }, { limit: DEFAULT_GC_LIMIT, excludeHash: hashId });
+      } catch {}
     }
   }
-  await new Promise((resolve2, reject) => {
-    server.listen({ path: sockPath, backlog }, () => resolve2());
-    server.once("error", (err2) => reject(err2));
+}
+async function spawnWorker(workerArgv, sockPath, idleTimeout, workerStderr, startupTimeoutMs) {
+  const fullArgv = [...workerArgv, "--unix", sockPath, "--idle-timeout", String(idleTimeout)];
+  const [cmd, ...rest] = fullArgv;
+  const stderrTarget = workerStderr === null ? "ignore" : "pipe";
+  const proc = spawn(cmd, rest, {
+    stdio: ["ignore", "pipe", stderrTarget],
+    detached: false
   });
-  try {
-    const { chmodSync } = await import("node:fs");
-    chmodSync(sockPath, 384);
-  } catch {}
-  options.onBound?.(sockPath);
-  announcementSink.write(`UNIX:${sockPath}
-`);
-  if (idleTimeoutS > 0) {
-    setTimeout(() => {
-      if (activeConnections === 0 && !stopped)
-        armIdleTimer();
-    }, startupGraceS * 1000).unref?.();
+  if (workerStderr !== null && proc.stderr) {
+    const sink = createWriteStream(workerStderr, { flags: "a" });
+    proc.stderr.pipe(sink);
   }
-  return {
-    socketPath: sockPath,
-    stop: shutdown,
-    done
-  };
-}
-// src/schema.ts
-var str = utf8();
-var bytes = binary();
-var int = int64();
-var int322 = int32();
-var int162 = int16();
-var int82 = int8();
-var uint82 = uint8();
-var uint162 = uint16();
-var uint322 = uint32();
-var uint642 = uint64();
-var float = float64();
-var float322 = float32();
-var bool2 = bool();
-function isField(x) {
-  return x != null && typeof x.name === "string" && x.type != null && typeof x.nullable === "boolean";
-}
-function isDataType(x) {
-  return x != null && typeof x.typeId === "number";
-}
-function toSchema(spec) {
-  const maybeFields = spec.fields;
-  if (Array.isArray(maybeFields)) {
-    const out = [];
-    for (const f of maybeFields) {
-      if (isField(f)) {
-        out.push(f);
-      } else {
-        out.push(field(f.name, f.type, f.nullable ?? true, f.metadata));
-      }
+  const expectedPrefix = `UNIX:${sockPath}`;
+  const reader = lineReader(proc.stdout);
+  const deadline = Date.now() + startupTimeoutMs;
+  while (Date.now() < deadline) {
+    const remaining = deadline - Date.now();
+    const result = await Promise.race([
+      reader.next().then((r) => ({ kind: "line", value: r })),
+      onceExit(proc).then((rc) => ({ kind: "exit", rc })),
+      delay(remaining).then(() => ({ kind: "timeout" }))
+    ]);
+    if (result.kind === "exit") {
+      throw new Error(`worker exited before readiness (rc=${result.rc})`);
     }
-    return schema(out);
-  }
-  const fields = [];
-  for (const [name, value] of Object.entries(spec)) {
-    if (isField(value)) {
-      fields.push(value);
-    } else if (isDataType(value)) {
-      fields.push(field(name, value, false));
-    } else {
-      throw new TypeError(`Invalid schema value for "${name}": expected DataType or Field, got ${typeof value}`);
+    if (result.kind === "timeout") {
+      proc.kill("SIGTERM");
+      throw new Error(`worker did not emit UNIX:<path> within ${startupTimeoutMs}ms`);
     }
-  }
-  return schema(fields);
-}
-function inferParamTypes(spec) {
-  const sch = toSchema(spec);
-  if (sch.fields.length === 0)
-    return;
-  const result = {};
-  for (const f of sch.fields) {
-    let mapped;
-    if (isUtf8(f.type))
-      mapped = "str";
-    else if (isBinary(f.type))
-      mapped = "bytes";
-    else if (isBool(f.type))
-      mapped = "bool";
-    else if (isFloat(f.type))
-      mapped = "float";
-    else if (isInt(f.type))
-      mapped = "int";
-    if (!mapped)
+    if (result.value.done) {
+      const rc = await onceExit(proc);
+      throw new Error(`worker exited before readiness (rc=${rc})`);
+    }
+    const line = result.value.value;
+    if (line.startsWith("UNIX:")) {
+      if (line !== expectedPrefix) {
+        proc.kill("SIGTERM");
+        throw new Error(`worker bound to unexpected path: ${JSON.stringify(line)} (expected ${JSON.stringify(expectedPrefix)})`);
+      }
+      reader.drainAndDiscard();
       return;
-    result[f.name] = mapped;
-  }
-  return result;
-}
-
-// src/protocol.ts
-var EMPTY_SCHEMA5 = schema([]);
-
-class Protocol {
-  name;
-  protocolVersion;
-  protocolVersionParts;
-  _methods = new Map;
-  constructor(name, options) {
-    this.name = name;
-    const raw = options?.protocolVersion;
-    if (raw === undefined || raw === "") {
-      this.protocolVersion = "";
-      this.protocolVersionParts = null;
-    } else {
-      this.protocolVersion = raw;
-      this.protocolVersionParts = parseProtocolVersion(raw);
     }
+    process.env.VGI_RPC_LAUNCHER_DEBUG && process.stderr.write(`launcher: skipping pre-bind stdout line: ${JSON.stringify(line)}
+`);
   }
-  unary(name, config) {
-    const params = toSchema(config.params);
-    this._methods.set(name, {
-      name,
-      type: "unary" /* UNARY */,
-      paramsSchema: params,
-      resultSchema: toSchema(config.result),
-      handler: config.handler,
-      doc: config.doc,
-      defaults: config.defaults,
-      paramTypes: config.paramTypes ?? inferParamTypes(params)
-    });
-    return this;
-  }
-  producer(name, config) {
-    const params = toSchema(config.params);
-    this._methods.set(name, {
-      name,
-      type: "stream" /* STREAM */,
-      paramsSchema: params,
-      resultSchema: EMPTY_SCHEMA5,
-      outputSchema: toSchema(config.outputSchema),
-      inputSchema: EMPTY_SCHEMA5,
-      producerInit: config.init,
-      producerFn: config.produce,
-      onCancel: config.onCancel,
-      headerSchema: config.headerSchema ? toSchema(config.headerSchema) : undefined,
-      headerInit: config.headerInit,
-      doc: config.doc,
-      defaults: config.defaults,
-      paramTypes: config.paramTypes ?? inferParamTypes(params)
-    });
-    return this;
-  }
-  exchange(name, config) {
-    const params = toSchema(config.params);
-    this._methods.set(name, {
-      name,
-      type: "stream" /* STREAM */,
-      paramsSchema: params,
-      resultSchema: EMPTY_SCHEMA5,
-      inputSchema: toSchema(config.inputSchema),
-      outputSchema: toSchema(config.outputSchema),
-      exchangeInit: config.init,
-      exchangeFn: config.exchange,
-      onCancel: config.onCancel,
-      headerSchema: config.headerSchema ? toSchema(config.headerSchema) : undefined,
-      headerInit: config.headerInit,
-      doc: config.doc,
-      defaults: config.defaults,
-      paramTypes: config.paramTypes ?? inferParamTypes(params)
-    });
-    return this;
-  }
-  getMethods() {
-    return new Map(this._methods);
-  }
-}
-// src/server.ts
-var EMPTY_SCHEMA6 = schema([]);
-function randomStreamId() {
-  const bytes2 = new Uint8Array(16);
-  crypto.getRandomValues(bytes2);
-  let out = "";
-  for (let i = 0;i < bytes2.length; i++) {
-    out += bytes2[i].toString(16).padStart(2, "0");
-  }
-  return out;
+  proc.kill("SIGTERM");
+  throw new Error(`worker did not emit UNIX:<path> within ${startupTimeoutMs}ms`);
 }
-
-class VgiRpcServer {
-  protocol;
-  enableDescribe;
-  serverId;
-  _describePromise = null;
-  protocolVersion;
-  dispatchHook = null;
-  externalConfig;
-  onServeStart = null;
-  serveStartFired = false;
-  constructor(protocol, options) {
-    this.protocol = protocol;
-    this.enableDescribe = options?.enableDescribe ?? true;
-    this.serverId = options?.serverId ?? crypto.randomUUID().replace(/-/g, "").slice(0, 12);
-    this.dispatchHook = options?.dispatchHook ?? null;
-    this.externalConfig = options?.externalLocation;
-    this.protocolVersion = options?.protocolVersion ?? "";
-    this.onServeStart = options?.onServeStart ?? null;
-  }
-  async notifyTransport(kind) {
-    if (this.serveStartFired)
+function lineReader(stream) {
+  let buffer = "";
+  let ended = false;
+  const queued = [];
+  const waiters = [];
+  let discardMode = false;
+  const flushWaiter = () => {
+    if (waiters.length === 0)
       return;
-    if (this.onServeStart) {
-      await this.onServeStart(kind);
+    if (queued.length > 0) {
+      const w = waiters.shift();
+      w?.({ done: false, value: queued.shift() ?? "" });
+    } else if (ended) {
+      const w = waiters.shift();
+      w?.({ done: true, value: "" });
+    }
+  };
+  stream.setEncoding?.("utf8");
+  stream.on("data", (chunk) => {
+    if (discardMode)
+      return;
+    buffer += String(chunk);
+    for (;; ) {
+      const nl = buffer.indexOf(`
+`);
+      if (nl < 0)
+        break;
+      const line = buffer.slice(0, nl).replace(/\r$/, "");
+      buffer = buffer.slice(nl + 1);
+      queued.push(line);
+    }
+    flushWaiter();
+  });
+  stream.on("end", () => {
+    ended = true;
+    if (buffer.length > 0) {
+      queued.push(buffer.replace(/\r$/, ""));
+      buffer = "";
     }
-    this.serveStartFired = true;
+    flushWaiter();
+  });
+  stream.on("error", () => {
+    ended = true;
+    flushWaiter();
+  });
+  return {
+    next() {
+      return new Promise((resolve) => {
+        waiters.push(resolve);
+        flushWaiter();
+      });
+    },
+    drainAndDiscard() {
+      discardMode = true;
+      queued.length = 0;
+      stream.resume?.();
+    }
+  };
+}
+function onceExit(proc) {
+  return new Promise((resolve) => {
+    proc.once("exit", (code) => resolve(code));
+  });
+}
+function delay(ms) {
+  return new Promise((r) => setTimeout(r, Math.max(0, ms)));
+}
+// src/launcher/serve-unix.ts
+import { existsSync as existsSync2, unlinkSync as unlinkSync3 } from "node:fs";
+import { createServer } from "node:net";
+import * as path2 from "node:path";
+var EMPTY_SCHEMA6 = schema([]);
+async function serveUnix(protocol, options) {
+  const sockPath = path2.resolve(options.unixPath);
+  const idleTimeoutS = options.idleTimeout ?? 300;
+  const startupGraceS = options.startupGraceSeconds ?? 5;
+  const protocolVersion = options.protocolVersion ?? "";
+  const serverId = options.serverId ?? crypto.randomUUID().replace(/-/g, "").slice(0, 12);
+  const enableDescribe = options.enableDescribe ?? true;
+  const dispatchHook = options.dispatchHook ?? null;
+  const externalConfig = options.externalLocation;
+  const onServeStart = options.onServeStart ?? null;
+  const backlog = options.backlog ?? 16;
+  const announcementSink = options.announcementSink ?? process.stdout;
+  if (existsSync2(sockPath)) {
+    try {
+      unlinkSync3(sockPath);
+    } catch {}
   }
-  async describeInfo() {
-    if (!this._describePromise) {
-      this._describePromise = buildDescribeBatch(this.protocol.name, this.protocol.getMethods(), this.serverId, this.protocol.protocolVersion || undefined).then(({ batch, metadata }) => ({
+  let describePromise = null;
+  function describeInfo() {
+    if (!describePromise) {
+      describePromise = buildDescribeBatch(protocol.name, protocol.getMethods(), serverId).then(({ batch, metadata }) => ({
         batch,
         protocolHash: metadata.get("vgi_rpc.protocol_hash") ?? ""
       }));
     }
-    return this._describePromise;
+    return describePromise;
   }
-  checkProtocolVersion(clientVersion) {
-    const serverParts = this.protocol.protocolVersionParts;
-    const serverVersion = this.protocol.protocolVersion;
-    if (clientVersion === undefined) {
-      throw new ProtocolVersionError(`VGI client/worker protocol_version mismatch.
-` + `  Client: <not declared>
-` + `  Server: ${serverVersion}
-` + "  Direction: the client did not send a vgi_rpc.protocol_version " + "metadata key. This is either a vgi-rpc framework bug or a " + "non-VGI client connecting to a VGI worker.");
-    }
-    let clientParts;
-    try {
-      clientParts = parseProtocolVersion(clientVersion);
-    } catch {
-      throw new ProtocolVersionError(`VGI client/worker protocol_version mismatch.
-` + `  Client: ${clientVersion}
-` + `  Server: ${serverVersion}
-` + "  Direction: client sent a malformed protocol_version. " + "Expected canonical semver MAJOR.MINOR.PATCH.");
+  let serveStartFired = false;
+  async function notifyTransport() {
+    if (serveStartFired)
+      return;
+    if (onServeStart) {
+      await onServeStart("unix" /* UNIX */);
     }
-    if (clientParts[0] === serverParts[0] && clientParts[1] === serverParts[1]) {
+    serveStartFired = true;
+  }
+  const server = createServer({ allowHalfOpen: false });
+  let activeConnections = 0;
+  let idleTimer = null;
+  let resolveDone = () => {};
+  let rejectDone = () => {};
+  const done = new Promise((resolve2, reject) => {
+    resolveDone = resolve2;
+    rejectDone = reject;
+  });
+  let stopped = false;
+  function armIdleTimer() {
+    if (idleTimeoutS <= 0)
       return;
+    if (idleTimer)
+      clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => {
+      if (activeConnections === 0 && !stopped) {
+        shutdown();
+      }
+    }, idleTimeoutS * 1000);
+  }
+  function disarmIdleTimer() {
+    if (idleTimer) {
+      clearTimeout(idleTimer);
+      idleTimer = null;
     }
-    const clientOlder = clientParts[0] < serverParts[0] || clientParts[0] === serverParts[0] && clientParts[1] < serverParts[1];
-    const direction = clientOlder ? `client is too old; upgrade the VGI extension/client to a version supporting protocol_version ${serverVersion}.` : `server is too old; upgrade the VGI worker to a version supporting protocol_version ${clientVersion}.`;
-    throw new ProtocolVersionError(`VGI client/worker protocol_version mismatch.
-` + `  Client: ${clientVersion}
-` + `  Server: ${serverVersion}
-` + `  Direction: ${direction}`);
   }
-  async run() {
-    const stdin = process.stdin;
-    if (process.stdin.isTTY || process.stdout.isTTY) {
-      process.stderr.write("WARNING: This process communicates via Arrow IPC on stdin/stdout " + `and is not intended to be run interactively.
-` + "It should be launched as a subprocess by an RPC client " + `(e.g. vgi_rpc.connect()).
+  async function shutdown() {
+    if (stopped)
+      return;
+    stopped = true;
+    disarmIdleTimer();
+    await new Promise((resolve2) => {
+      server.close(() => resolve2());
+    });
+    try {
+      unlinkSync3(sockPath);
+    } catch {}
+    resolveDone();
+  }
+  server.on("connection", (socket) => {
+    activeConnections += 1;
+    disarmIdleTimer();
+    handleConnection(socket).catch((err2) => {
+      process.stderr.write(`vgi-rpc/unix: connection failed: ${err2?.message ?? err2}
 `);
-    }
-    const reader = await IpcStreamReader.create(stdin);
-    const writer = new IpcStreamWriter;
+    }).finally(() => {
+      activeConnections -= 1;
+      socket.destroy();
+      if (activeConnections === 0 && !stopped) {
+        armIdleTimer();
+      }
+    });
+  });
+  server.on("error", (err2) => {
+    if (stopped)
+      return;
+    rejectDone(err2);
+  });
+  async function handleConnection(socket) {
+    const reader = await IpcStreamReader.create(socket);
+    const writer = new IpcStreamWriter(socket);
     try {
+      await notifyTransport();
       while (true) {
-        await this.notifyTransport("pipe" /* PIPE */);
-        await this.serveOne(reader, writer);
-      }
-    } catch (e) {
-      if (e.message?.includes("closed") || e.message?.includes("Expected Schema Message") || e.message?.includes("null or length 0") || e.code === "EPIPE" || e.code === "ERR_STREAM_PREMATURE_CLOSE" || e.code === "ERR_STREAM_DESTROYED" || e instanceof Error && e.message.includes("EOF")) {
-        return;
+        try {
+          await serveOnce(reader, writer);
+        } catch (e) {
+          const err2 = e;
+          if (err2?.message?.includes("closed") || err2?.message?.includes("Expected Schema Message") || err2?.message?.includes("null or length 0") || err2?.message?.includes("EOF") || err2?.code === "EPIPE" || err2?.code === "ERR_STREAM_PREMATURE_CLOSE" || err2?.code === "ERR_STREAM_DESTROYED") {
+            return;
+          }
+          throw e;
+        }
       }
-      throw e;
     } finally {
-      await reader.cancel();
+      try {
+        await reader.cancel();
+      } catch {}
     }
   }
-  async serveOne(reader, writer) {
+  async function serveOnce(reader, writer) {
     const stream = await reader.readStream();
     if (!stream) {
       throw new Error("EOF");
@@ -9373,7 +9366,7 @@ class VgiRpcServer {
     const { schema: schema2, batches } = stream;
     if (batches.length === 0) {
       const err2 = new RpcError("ProtocolError", "Request stream contains no batches", "");
-      const errBatch = buildErrorBatch(EMPTY_SCHEMA6, err2, this.serverId, null);
+      const errBatch = buildErrorBatch(EMPTY_SCHEMA6, err2, serverId, null);
       await writer.writeStream(EMPTY_SCHEMA6, [errBatch]);
       return;
     }
@@ -9387,63 +9380,46 @@ class VgiRpcServer {
       params = parsed.params;
       requestId = parsed.requestId;
     } catch (e) {
-      const errBatch = buildErrorBatch(EMPTY_SCHEMA6, e, this.serverId, null);
+      const errBatch = buildErrorBatch(EMPTY_SCHEMA6, e, serverId, null);
       await writer.writeStream(EMPTY_SCHEMA6, [errBatch]);
-      if (e instanceof VersionError || e instanceof RpcError) {
+      if (e instanceof VersionError || e instanceof RpcError)
         return;
-      }
       throw e;
     }
-    if (methodName === DESCRIBE_METHOD_NAME && this.enableDescribe) {
-      const { batch: batch2 } = await this.describeInfo();
-      await writer.writeStream(batch2.schema, [batch2]);
+    if (methodName === DESCRIBE_METHOD_NAME && enableDescribe) {
+      const { batch: descBatch } = await describeInfo();
+      await writer.writeStream(descBatch.schema, [descBatch]);
       return;
     }
-    const methods = this.protocol.getMethods();
+    const methods = protocol.getMethods();
     const method = methods.get(methodName);
     if (!method) {
       const available = [...methods.keys()].sort();
-      const err2 = new MethodNotImplementedError(`Unknown method: '${methodName}'. Available methods: [${available.join(", ")}]`);
-      const errBatch = buildErrorBatch(EMPTY_SCHEMA6, err2, this.serverId, requestId);
+      const err2 = new Error(`Unknown method: '${methodName}'. Available methods: [${available.join(", ")}]`);
+      const errBatch = buildErrorBatch(EMPTY_SCHEMA6, err2, serverId, requestId);
       await writer.writeStream(EMPTY_SCHEMA6, [errBatch]);
       return;
     }
-    if (this.protocol.protocolVersionParts !== null) {
-      try {
-        const md = batch.metadata;
-        this.checkProtocolVersion(md?.get(PROTOCOL_VERSION_KEY));
-      } catch (exc) {
-        const errSchema = method.type === "unary" /* UNARY */ ? method.resultSchema : EMPTY_SCHEMA6;
-        const errBatch = buildErrorBatch(errSchema, exc, this.serverId, requestId);
-        await writer.writeStream(errSchema, [errBatch]);
-        return;
-      }
-    }
     const methodType = method.type === "unary" /* UNARY */ ? "unary" : "stream";
     let requestData;
     try {
       requestData = serializeBatch(batch);
     } catch {}
-    let streamId;
-    if (methodType === "stream") {
-      streamId = randomStreamId();
-    }
-    const { protocolHash } = await this.describeInfo();
+    const { protocolHash } = await describeInfo();
     const info = {
       method: methodName,
       methodType,
-      serverId: this.serverId,
+      serverId,
       requestId,
-      protocol: this.protocol.name,
+      protocol: protocol.name,
       protocolHash,
-      protocolVersion: this.protocolVersion,
-      kind: "pipe" /* PIPE */,
+      protocolVersion,
+      kind: "unix" /* UNIX */,
       principal: "",
       authDomain: "",
       authenticated: false,
       remoteAddr: "",
-      requestData,
-      streamId
+      requestData
     };
     const stats = {
       inputBatches: 0,
@@ -9453,22 +9429,44 @@ class VgiRpcServer {
       inputBytes: 0,
       outputBytes: 0
     };
-    const token = this.dispatchHook?.onDispatchStart(info);
+    const token = dispatchHook?.onDispatchStart(info);
     let dispatchError;
     applyDefaults(params, method.defaults);
     try {
       if (method.type === "unary" /* UNARY */) {
-        await dispatchUnary(method, params, writer, this.serverId, requestId, this.externalConfig, "pipe" /* PIPE */);
+        await dispatchUnary(method, params, writer, serverId, requestId, externalConfig, "unix" /* UNIX */);
       } else {
-        await dispatchStream(method, params, writer, reader, this.serverId, requestId, this.externalConfig, "pipe" /* PIPE */);
+        await dispatchStream(method, params, writer, reader, serverId, requestId, externalConfig, "unix" /* UNIX */);
       }
     } catch (e) {
       dispatchError = e instanceof Error ? e : new Error(String(e));
       throw e;
     } finally {
-      this.dispatchHook?.onDispatchEnd(token, info, stats, dispatchError);
+      dispatchHook?.onDispatchEnd(token, info, stats, dispatchError);
     }
   }
+  await new Promise((resolve2, reject) => {
+    server.listen({ path: sockPath, backlog }, () => resolve2());
+    server.once("error", (err2) => reject(err2));
+  });
+  try {
+    const { chmodSync } = await import("node:fs");
+    chmodSync(sockPath, 384);
+  } catch {}
+  options.onBound?.(sockPath);
+  announcementSink.write(`UNIX:${sockPath}
+`);
+  if (idleTimeoutS > 0) {
+    setTimeout(() => {
+      if (activeConnections === 0 && !stopped)
+        armIdleTimer();
+    }, startupGraceS * 1000).unref?.();
+  }
+  return {
+    socketPath: sockPath,
+    stop: shutdown,
+    done
+  };
 }
 export {
   unpackStateToken,
@@ -9563,4 +9561,4 @@ export {
   ARROW_CONTENT_TYPE
 };
 
-//# debugId=03000096478B827564756E2164756E21
+//# debugId=4D9D32B49233679B64756E2164756E21