@ai-ecoverse/slicc-kernel 1.8.12 → 1.9.0

package/dist/node.js

@@ -1,5 +1,496 @@
 // src/node.ts
-import { Worker } from "node:worker_threads";
+import { MessageChannel as MessageChannel2, Worker } from "node:worker_threads";
+
+// src/fs/types.ts
+function fsError(code, path) {
+  return Object.assign(new Error(`${code}: ${path}`), { code });
+}
+function normalizePath(path) {
+  const parts = [];
+  for (const part of path.split("/")) {
+    if (part === "" || part === ".") continue;
+    if (part === "..") parts.pop();
+    else parts.push(part);
+  }
+  return `/${parts.join("/")}`;
+}
+function resolvePath(base, path) {
+  return normalizePath(path.startsWith("/") ? path : `${base}/${path}`);
+}
+function inodeOf(path) {
+  let h1 = 3735928559;
+  let h2 = 1103547991;
+  for (let i = 0; i < path.length; i++) {
+    const c = path.charCodeAt(i);
+    h1 = Math.imul(h1 ^ c, 2654435761);
+    h2 = Math.imul(h2 ^ c, 1597334677);
+  }
+  h1 = Math.imul(h1 ^ h1 >>> 16, 2246822507) ^ Math.imul(h2 ^ h2 >>> 13, 3266489909);
+  h2 = Math.imul(h2 ^ h2 >>> 16, 2246822507) ^ Math.imul(h1 ^ h1 >>> 13, 3266489909);
+  return 4294967296 * (2097151 & h2) + (h1 >>> 0) || 1;
+}
+
+// src/kernel/signals.ts
+var SIG = {
+  HUP: 1,
+  INT: 2,
+  QUIT: 3,
+  ILL: 4,
+  TRAP: 5,
+  ABRT: 6,
+  BUS: 7,
+  FPE: 8,
+  KILL: 9,
+  USR1: 10,
+  SEGV: 11,
+  USR2: 12,
+  PIPE: 13,
+  ALRM: 14,
+  TERM: 15,
+  STKFLT: 16,
+  CHLD: 17,
+  CONT: 18,
+  STOP: 19,
+  TSTP: 20,
+  TTIN: 21,
+  TTOU: 22,
+  URG: 23,
+  XCPU: 24,
+  XFSZ: 25,
+  VTALRM: 26,
+  PROF: 27,
+  WINCH: 28,
+  POLL: 29,
+  PWR: 30,
+  SYS: 31
+};
+var IGNORED_BY_DEFAULT = /* @__PURE__ */ new Set([SIG.CHLD, SIG.URG, SIG.WINCH]);
+var STOPPING = /* @__PURE__ */ new Set([SIG.STOP, SIG.TSTP, SIG.TTIN, SIG.TTOU]);
+function defaultAction(sig) {
+  if (sig === SIG.CONT) return "continue";
+  if (STOPPING.has(sig)) return "stop";
+  return IGNORED_BY_DEFAULT.has(sig) ? "ignore" : "terminate";
+}
+function isSignal(sig) {
+  return Number.isInteger(sig) && sig >= 1 && sig <= 31;
+}
+function sigbit(sig) {
+  return 1 << sig;
+}
+var SIGNAL_BY_NAME = {
+  SIGINT: SIG.INT,
+  SIGTERM: SIG.TERM,
+  SIGKILL: SIG.KILL,
+  SIGSTOP: SIG.STOP,
+  SIGCONT: SIG.CONT
+};
+
+// src/body-idle.ts
+var BODY_IDLE_MS = 5 * 60 * 1e3;
+function idleFailure(ms) {
+  return Object.assign(new Error(`the response body sent no data for ${ms} ms`), {
+    code: "ETIMEDOUT"
+  });
+}
+async function readWithin(reader, ms) {
+  if (!(ms > 0 && ms < Number.POSITIVE_INFINITY)) return reader.read();
+  let timer;
+  const idle = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(idleFailure(ms)), ms);
+  });
+  try {
+    return await Promise.race([reader.read(), idle]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// src/transport.ts
+var MAX_REQUEST_BODY = 64 * 1024 * 1024;
+function joinHeaders(headers) {
+  const out = new Headers();
+  for (const [name2, value] of headers) {
+    try {
+      out.append(name2, value);
+    } catch {
+    }
+  }
+  return out;
+}
+async function* chunks(body, idleMs) {
+  if (!body) return;
+  const reader = body.getReader();
+  try {
+    for (let next = await readWithin(reader, idleMs); !next.done; next = await readWithin(reader, idleMs)) {
+      if (next.value.byteLength > 0) yield next.value;
+    }
+  } finally {
+    await reader.cancel().catch(() => void 0);
+  }
+}
+function fetchTransport(options = {}) {
+  const send = options.fetch ?? globalThis.fetch.bind(globalThis);
+  return {
+    traits: {
+      manualRedirects: false,
+      encodedBodies: false,
+      maxRequestBody: options.maxRequestBody ?? MAX_REQUEST_BODY,
+      crossOrigin: "cors"
+    },
+    async fetch(request) {
+      let response;
+      try {
+        response = await send(request.url, {
+          method: request.method,
+          headers: joinHeaders(request.headers),
+          ...request.body ? { body: request.body } : {},
+          signal: request.signal,
+          redirect: "follow",
+          credentials: "omit",
+          mode: "cors"
+        });
+      } catch (e) {
+        if (request.signal.aborted) throw e;
+        throw Object.assign(
+          new Error(
+            `fetch ${request.url} failed (unreachable, or not allowed by CORS)${options.hint ? `: ${options.hint}` : ""}`
+          ),
+          { status: 502 }
+        );
+      }
+      const headers = [];
+      response.headers.forEach((value, name2) => {
+        headers.push([name2, value]);
+      });
+      const body = chunks(response.body, options.bodyIdleMs ?? BODY_IDLE_MS);
+      return {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+        body,
+        cancel: async () => {
+          await body.return(void 0);
+          await response.body?.cancel().catch(() => void 0);
+        }
+      };
+    }
+  };
+}
+function serveTransport(peer, transport) {
+  const open = /* @__PURE__ */ new Map();
+  const fail2 = (nid, e) => {
+    open.delete(nid);
+    const { status, code } = e;
+    peer.postMessage({
+      net: "error",
+      nid,
+      message: e instanceof Error ? e.message : String(e),
+      ...typeof status === "number" ? { status } : {},
+      ...typeof code === "string" ? { code } : {}
+    });
+  };
+  const start = async (call) => {
+    const abort = new AbortController();
+    const entry = { abort };
+    open.set(call.nid, entry);
+    try {
+      const response = await transport.fetch({
+        url: call.url,
+        method: call.method,
+        headers: call.headers,
+        ...call.body ? { body: call.body } : {},
+        signal: abort.signal
+      });
+      if (!open.has(call.nid)) {
+        await response.cancel();
+        return;
+      }
+      open.set(call.nid, { abort, body: response.body[Symbol.asyncIterator](), response });
+      peer.postMessage({
+        net: "head",
+        nid: call.nid,
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers
+      });
+    } catch (e) {
+      fail2(call.nid, e);
+    }
+  };
+  const read = async (nid) => {
+    const body = open.get(nid)?.body;
+    if (!body) return;
+    try {
+      const next = await body.next();
+      if (next.done) {
+        open.delete(nid);
+        peer.postMessage({ net: "end", nid });
+      } else {
+        const bytes = next.value.slice();
+        peer.postMessage({ net: "chunk", nid, bytes }, [bytes.buffer]);
+      }
+    } catch (e) {
+      fail2(nid, e);
+    }
+  };
+  const drop = (nid) => {
+    const entry = open.get(nid);
+    open.delete(nid);
+    entry?.abort.abort();
+    void entry?.response?.cancel().catch(() => void 0);
+  };
+  return {
+    answer(call) {
+      if (call.net === "fetch") void start(call);
+      else if (call.net === "read") void read(call.nid);
+      else drop(call.nid);
+    },
+    close() {
+      for (const nid of [...open.keys()]) drop(nid);
+    }
+  };
+}
+
+// src/client/protocol.ts
+var PROTOCOL = [1, 0];
+var FS_METHODS = [
+  "readFile",
+  "writeFile",
+  "stat",
+  "lstat",
+  "readdir",
+  "mkdir",
+  "rm",
+  "rename",
+  "realpath",
+  "symlink",
+  "readlink",
+  "exists"
+];
+function locksOf(scope = globalThis) {
+  const locks = scope.navigator?.locks;
+  return typeof locks?.request === "function" ? locks : void 0;
+}
+function versionError(theirs) {
+  const major = Array.isArray(theirs) ? theirs[0] : void 0;
+  if (major === PROTOCOL[0]) return void 0;
+  const named = typeof major === "number" ? `${major}.x` : "without a version";
+  return `slicc-kernel client protocol ${named} is not supported: this side speaks ${PROTOCOL.join(".")}`;
+}
+
+// src/client/serve-client.ts
+var MAX_LINKS = 40;
+function act(session, req, signal) {
+  if (req.action === "write") session.write(req.bytes);
+  else if (req.action === "resize") session.resize(req.cols, req.rows);
+  else if (req.action === "signal") session.signal(signal(req.signal));
+  else session.close();
+}
+async function realpath(fs, path) {
+  let parts = fs.resolvePath("/", path).split("/").filter(Boolean);
+  let resolved = "";
+  for (let hops = 0; parts.length > 0; ) {
+    const [name2, ...rest] = parts;
+    const next = `${resolved}/${name2}`;
+    if (!(await fs.lstat(next)).isSymbolicLink) {
+      resolved = next;
+      parts = rest;
+      continue;
+    }
+    if (++hops > MAX_LINKS) throw fsError("ELOOP", path);
+    const target = await fs.readlink(next);
+    const base = target.startsWith("/") ? "/" : resolved || "/";
+    parts = [...fs.resolvePath(base, target).split("/").filter(Boolean), ...rest];
+    resolved = "";
+  }
+  return resolved || "/";
+}
+async function fsCall(fs, method, args) {
+  const path = (i) => fs.resolvePath("/", String(args[i]));
+  switch (method) {
+    case "readFile": {
+      const bytes = (await fs.readFileBuffer(path(0))).slice();
+      return { result: bytes, transfer: [bytes.buffer] };
+    }
+    case "writeFile":
+      await fs.writeFile(path(0), args[1]);
+      return { result: true };
+    case "stat":
+      return { result: await fs.stat(path(0)) };
+    case "lstat":
+      return { result: await fs.lstat(path(0)) };
+    case "readdir":
+      return { result: await fs.readdir(path(0)) };
+    case "mkdir":
+      await fs.mkdir(path(0), { recursive: true });
+      return { result: true };
+    case "rm":
+      await fs.rm(path(0), { recursive: true, force: args[1] === true });
+      return { result: true };
+    case "rename":
+      await fs.rename(path(0), path(1));
+      return { result: true };
+    case "realpath":
+      return { result: await realpath(fs, String(args[0])) };
+    case "symlink":
+      await fs.symlink(String(args[0]), path(1));
+      return { result: true };
+    case "readlink":
+      return { result: await fs.readlink(path(0)) };
+    default:
+      return { result: await fs.exists(path(0)) };
+  }
+}
+function serveClient(port, host) {
+  let state = "new";
+  const terminals = /* @__PURE__ */ new Map();
+  const groups = /* @__PURE__ */ new Set();
+  let net;
+  const ended = Promise.withResolvers();
+  const send = (message2, transfer = []) => {
+    if (state !== "closed") port.postMessage(message2, transfer);
+  };
+  const reply = (id, body, transfer) => send({ id, ...body }, transfer);
+  function detach(kill = false, bye = "the slicc-kernel detached this client") {
+    if (state === "closed") return;
+    send({ bye });
+    state = "closed";
+    net?.close();
+    for (const session of terminals.values()) session.close();
+    terminals.clear();
+    const pids = [...groups];
+    groups.clear();
+    if (kill && pids.length > 0) {
+      void host.launcher().then((launcher) => {
+        for (const pid of pids) launcher.kill(-pid, SIG.KILL);
+      });
+    }
+    port.close?.();
+    ended.resolve();
+  }
+  async function hello(message2) {
+    const refused = versionError(message2.protocol);
+    if (refused) {
+      send({ hello: { protocol: PROTOCOL, error: refused } });
+      detach();
+      return;
+    }
+    const launcher = await host.launcher();
+    const transport = host.transport?.() ?? launcher.transport;
+    net = serveTransport({ postMessage: (m, t) => send(m, t) }, transport);
+    state = "open";
+    if (message2.lock && host.locks) void host.locks.request(message2.lock, () => detach());
+    send({
+      hello: {
+        protocol: PROTOCOL,
+        traits: transport.traits,
+        ...host.lock ? { lock: host.lock } : {}
+      }
+    });
+  }
+  async function terminal(req, l) {
+    const session = await l.openTerminal(req.argv, {
+      ...req.options,
+      onData: (bytes) => reply(req.id, { fd: 1, bytes: bytes.slice() })
+    });
+    if (state === "closed") {
+      session.close();
+    } else {
+      terminals.set(req.id, session);
+      reply(req.id, { started: session.pid });
+    }
+    try {
+      return { result: await session.exited };
+    } finally {
+      terminals.delete(req.id);
+    }
+  }
+  async function spawn(req, l) {
+    const out = (fd) => (bytes) => reply(req.id, { fd, bytes: bytes.slice() });
+    let leader;
+    const result = await l.run(req.argv, {
+      ...req.options,
+      collect: false,
+      onStdout: out(1),
+      onStderr: out(2),
+      onStarted: (pid) => {
+        leader = pid;
+        if (state === "closed") return;
+        groups.add(pid);
+        reply(req.id, { started: pid });
+      }
+    });
+    if (leader === void 0) throw fsError("ENOENT", `${req.argv[0] ?? ""}: command not found`);
+    if (!l.list().some((p) => p.pgid === leader)) groups.delete(leader);
+    return { result: result.status };
+  }
+  async function handle(req) {
+    const l = await host.launcher();
+    switch (req.op) {
+      case "spawn":
+        return spawn(req, l);
+      case "open-terminal":
+        return terminal(req, l);
+      case "terminal": {
+        const session = terminals.get(req.terminal);
+        if (!session) throw new Error(`no terminal ${req.terminal}`);
+        act(session, req, host.signal);
+        return { result: true };
+      }
+      case "kill":
+        if (!l.kill(req.pid, host.signal(req.signal))) throw fsError("ESRCH", `pid ${req.pid}`);
+        return { result: true };
+      case "ps":
+        return {
+          result: l.list().map(({ tid: _, ...entry }) => entry)
+        };
+      case "fs":
+        if (!FS_METHODS.includes(req.method)) {
+          throw new Error(`unknown file system call ${req.method}`);
+        }
+        return fsCall(l.fs, req.method, req.args);
+      case "detach":
+        return { result: true };
+      default:
+        throw new Error(`unknown op ${req.op}`);
+    }
+  }
+  port.addEventListener("message", (event) => {
+    const data = event.data;
+    if (state === "closed") return;
+    if (data.hello) {
+      if (state === "new") {
+        hello(data.hello).catch((err) => {
+          send({ hello: { protocol: PROTOCOL, error: String(err?.message ?? err) } });
+          detach();
+        });
+      }
+      return;
+    }
+    if (state !== "open") return;
+    if (data.net !== void 0) {
+      net?.answer(data);
+      return;
+    }
+    const req = data;
+    handle(req).then(
+      ({ result, transfer }) => {
+        reply(req.id, { result }, transfer);
+        if (req.op === "detach") detach(req.kill === true);
+      },
+      (err) => {
+        const code = err?.code;
+        reply(req.id, {
+          error: err instanceof Error ? err.message : String(err),
+          ...typeof code === "string" ? { code } : {}
+        });
+      }
+    );
+  });
+  port.addEventListener("close", () => detach());
+  port.start?.();
+  return { detach, closed: ended.promise };
+}
 
 // src/fs/meta.ts
 function parentOf(path) {
@@ -34,49 +525,20 @@ var MemoryMeta = class {
     this.entries.set(to, moved(root(carried.find((entry) => entry.path === from)), to));
   }
   async remove(paths) {
-    for (const key of [...this.entries.keys()]) {
-      if (paths.some((path) => under(key, path))) this.entries.delete(key);
-    }
-  }
-  async links(dir) {
-    return [...this.entries.values()].filter((entry) => entry.dir === dir);
-  }
-  async under(path) {
-    return [...this.entries.values()].filter((entry) => under(entry.path, path));
-  }
-  async all() {
-    return [...this.entries.values()];
-  }
-};
-
-// src/fs/types.ts
-function fsError(code, path) {
-  return Object.assign(new Error(`${code}: ${path}`), { code });
-}
-function normalizePath(path) {
-  const parts = [];
-  for (const part of path.split("/")) {
-    if (part === "" || part === ".") continue;
-    if (part === "..") parts.pop();
-    else parts.push(part);
+    for (const key of [...this.entries.keys()]) {
+      if (paths.some((path) => under(key, path))) this.entries.delete(key);
+    }
   }
-  return `/${parts.join("/")}`;
-}
-function resolvePath(base, path) {
-  return normalizePath(path.startsWith("/") ? path : `${base}/${path}`);
-}
-function inodeOf(path) {
-  let h1 = 3735928559;
-  let h2 = 1103547991;
-  for (let i = 0; i < path.length; i++) {
-    const c = path.charCodeAt(i);
-    h1 = Math.imul(h1 ^ c, 2654435761);
-    h2 = Math.imul(h2 ^ c, 1597334677);
+  async links(dir) {
+    return [...this.entries.values()].filter((entry) => entry.dir === dir);
   }
-  h1 = Math.imul(h1 ^ h1 >>> 16, 2246822507) ^ Math.imul(h2 ^ h2 >>> 13, 3266489909);
-  h2 = Math.imul(h2 ^ h2 >>> 16, 2246822507) ^ Math.imul(h1 ^ h1 >>> 13, 3266489909);
-  return 4294967296 * (2097151 & h2) + (h1 >>> 0) || 1;
-}
+  async under(path) {
+    return [...this.entries.values()].filter((entry) => under(entry.path, path));
+  }
+  async all() {
+    return [...this.entries.values()];
+  }
+};
 
 // src/fs/opfs.ts
 var S_IFDIR = 16384;
@@ -84,7 +546,7 @@ var S_IFREG = 32768;
 var S_IFLNK = 40960;
 var PERM_MASK = 4095;
 var READ_ATTEMPTS = 3;
-var MAX_LINKS = 40;
+var MAX_LINKS2 = 40;
 var CHECK_MS = 1e3;
 var EXECUTABLE = /\/node_modules\/(?:@[^/]+\/)?[^/]+\/bin\//;
 var ERRNO_BY_DOM_ERROR = {
@@ -235,7 +697,7 @@ var OpfsFs = class {
   }
   async locate(path, follow) {
     let current = path;
-    for (let hops = 0; hops <= MAX_LINKS; hops++) {
+    for (let hops = 0; hops <= MAX_LINKS2; hops++) {
       try {
         return { path: current, handle: await this.handle(current) };
       } catch (err) {
@@ -699,7 +1161,7 @@ async function scanCommands(fs, modules) {
 var S_IFDIR2 = 16384;
 var S_IFREG2 = 32768;
 var COMMAND = /^\/(?:usr\/)?bin\/([^/]+)$/;
-var MAX_LINKS2 = 40;
+var MAX_LINKS3 = 40;
 function missing2(err) {
   return err?.code === "ENOENT";
 }
@@ -719,7 +1181,7 @@ function synthetic(directory, path) {
 }
 async function followLinks(fs, path) {
   let current = path;
-  for (let hops = 0; hops < MAX_LINKS2; hops++) {
+  for (let hops = 0; hops < MAX_LINKS3; hops++) {
     const st = await fs.lstat(current).catch(() => void 0);
     if (!st?.isSymbolicLink) return current;
     const parent = current.slice(0, current.lastIndexOf("/")) || "/";
@@ -3159,61 +3621,6 @@ var HttpHandles = class {
   }
 };
 
-// src/kernel/signals.ts
-var SIG = {
-  HUP: 1,
-  INT: 2,
-  QUIT: 3,
-  ILL: 4,
-  TRAP: 5,
-  ABRT: 6,
-  BUS: 7,
-  FPE: 8,
-  KILL: 9,
-  USR1: 10,
-  SEGV: 11,
-  USR2: 12,
-  PIPE: 13,
-  ALRM: 14,
-  TERM: 15,
-  STKFLT: 16,
-  CHLD: 17,
-  CONT: 18,
-  STOP: 19,
-  TSTP: 20,
-  TTIN: 21,
-  TTOU: 22,
-  URG: 23,
-  XCPU: 24,
-  XFSZ: 25,
-  VTALRM: 26,
-  PROF: 27,
-  WINCH: 28,
-  POLL: 29,
-  PWR: 30,
-  SYS: 31
-};
-var IGNORED_BY_DEFAULT = /* @__PURE__ */ new Set([SIG.CHLD, SIG.URG, SIG.WINCH]);
-var STOPPING = /* @__PURE__ */ new Set([SIG.STOP, SIG.TSTP, SIG.TTIN, SIG.TTOU]);
-function defaultAction(sig) {
-  if (sig === SIG.CONT) return "continue";
-  if (STOPPING.has(sig)) return "stop";
-  return IGNORED_BY_DEFAULT.has(sig) ? "ignore" : "terminate";
-}
-function isSignal(sig) {
-  return Number.isInteger(sig) && sig >= 1 && sig <= 31;
-}
-function sigbit(sig) {
-  return 1 << sig;
-}
-var SIGNAL_BY_NAME = {
-  SIGINT: SIG.INT,
-  SIGTERM: SIG.TERM,
-  SIGKILL: SIG.KILL,
-  SIGSTOP: SIG.STOP,
-  SIGCONT: SIG.CONT
-};
-
 // src/kernel/tty.ts
 var ICRNL = 256;
 var IUTF8 = 16384;
@@ -4416,6 +4823,7 @@ var SYSCALL_OPS = /* @__PURE__ */ new Set([
   "proc-captured",
   "proc-fork",
   "proc-kill",
+  "proc-list",
   "proc-exec",
   "proc-setpgid",
   "proc-getpgid",
@@ -4864,6 +5272,12 @@ var WasmProcess = class {
           throw new KernelError("ESRCH");
         }
         return { ok: true, kind: "void" };
+      case "proc-list":
+        return {
+          ok: true,
+          kind: "json",
+          json: this.options.processes?.() ?? { boot: 0, processes: [] }
+        };
       case "proc-alarm":
         this.setAlarm(req.sig, req.firstMs ?? req.ms, req.repeat ? req.ms : 0, req.timer);
         return { ok: true, kind: "void" };
@@ -4967,6 +5381,7 @@ function spawnWasmProcess(opts) {
     forker: opts.forker,
     fs: opts.fs,
     kill: opts.kill,
+    processes: opts.processes,
     jobs: opts.jobs,
     ptys: opts.ptys,
     net: opts.net,
@@ -5111,6 +5526,9 @@ var JobTable = class {
     this.members.set(pid, member);
     return member;
   }
+  list() {
+    return [...this.members.values()];
+  }
   remove(pid) {
     this.members.delete(pid);
   }
@@ -5441,6 +5859,7 @@ var Launcher = class {
   processes = /* @__PURE__ */ new Map();
   zombies = /* @__PURE__ */ new Set();
   orphans = /* @__PURE__ */ new Set();
+  described = /* @__PURE__ */ new Map();
   jobs = new JobTable();
   locks = new LockTable();
   ptys = new PtyTable((tty, sig) => this.jobs.signalOwnedForeground(tty, sig));
@@ -5448,6 +5867,7 @@ var Launcher = class {
   ca;
   transport;
   nextPid = 1e3;
+  boot = Date.now();
   terminals = 0;
   constructor(options) {
     this.base = options.fs;
@@ -5619,6 +6039,7 @@ var Launcher = class {
       spawner: this.spawner(pid, req.report),
       forker: this.forker(pid, req),
       kill: (target, sig) => this.kill(target, sig),
+      processes: () => ({ boot: this.boot, processes: this.list() }),
       jobs: this.jobs,
       ptys: this.ptys,
       net: this.net,
@@ -5630,17 +6051,57 @@ var Launcher = class {
     });
     this.processes.set(pid, handle);
     this.jobs.add(pid, req.ppid, (sig) => handle.signal(sig), terminal);
+    this.described.set(pid, {
+      argv: [req.argv0, ...req.args],
+      tty: terminal?.name ?? null,
+      started: Date.now()
+    });
     void handle.exited.then(() => {
       this.processes.delete(pid);
-      if (req.ppid === void 0 || this.orphans.delete(pid)) this.jobs.remove(pid);
+      if (req.ppid === void 0 || this.orphans.delete(pid)) this.forget(pid);
       else this.zombies.add(pid);
     });
     return handle;
   }
+  forget(pid) {
+    this.jobs.remove(pid);
+    this.described.delete(pid);
+  }
   reaped(pid) {
-    if (this.zombies.delete(pid)) this.jobs.remove(pid);
+    if (this.zombies.delete(pid)) this.forget(pid);
     else this.orphans.add(pid);
   }
+  list() {
+    const members = new Map(this.jobs.list().map((member) => [member.pid, member]));
+    const rootOf = (member) => {
+      let root = member;
+      for (let up = members.get(root.execParent ?? -1); up; up = members.get(up.execParent ?? -1)) {
+        root = up;
+      }
+      return root;
+    };
+    const shown = (pid) => {
+      const member = pid === void 0 ? void 0 : members.get(pid);
+      return member ? rootOf(member).pid : pid ?? 0;
+    };
+    const listed = [];
+    for (const member of members.values()) {
+      const described = this.described.get(member.pid);
+      if (member.execed || !described) continue;
+      const root = rootOf(member);
+      listed.push({
+        pid: root.pid,
+        tid: member.pid,
+        ppid: shown(root.ppid),
+        pgid: member.pgid,
+        sid: member.sid,
+        ...described,
+        started: (this.described.get(root.pid) ?? described).started,
+        state: this.processes.has(member.pid) ? "S" : "Z"
+      });
+    }
+    return listed;
+  }
   spawner(ppid, report) {
     return async (req, fds) => {
       const planned = await this.plan(req.file, req.argv, req.cwd);
@@ -5718,8 +6179,9 @@ var Launcher = class {
     const env = this.environment(cwd, options.env);
     const out = [];
     const err = [];
+    const keep = options.collect !== false;
     const collect = (chunks2, tee) => (bytes) => {
-      chunks2.push(bytes);
+      if (keep) chunks2.push(bytes);
       tee?.(bytes);
     };
     const stdout = collect(out, options.onStdout);
@@ -5735,6 +6197,7 @@ var Launcher = class {
     fds.installAt(1, sinkFile(stdout));
     fds.installAt(2, sinkFile(stderr));
     const handle = await this.launch(planned, { env, cwd, fds, report });
+    options.onStarted?.(handle.pid);
     const status = await handle.exited;
     return { status, stdout: concat4(out), stderr: concat4(err) };
   }
@@ -5876,6 +6339,118 @@ function memoryRoot() {
   return new MemoryDirectory("", null);
 }
 
+// src/kernel/net/remote-transport.ts
+var TransportError = class extends Error {
+  status;
+  code;
+  constructor(message2, status, code) {
+    super(message2);
+    this.status = status;
+    this.code = code;
+  }
+};
+var RemoteTransport = class {
+  traits;
+  port;
+  waiting = /* @__PURE__ */ new Map();
+  nextId = 0;
+  failure;
+  constructor(port, traits) {
+    this.port = port;
+    this.traits = traits;
+  }
+  receive(reply) {
+    const waiter = this.waiting.get(reply.nid);
+    if (!waiter) return;
+    this.waiting.delete(reply.nid);
+    if (reply.net === "error") {
+      waiter.reject(new TransportError(reply.message, reply.status, reply.code));
+    } else waiter.resolve(reply);
+  }
+  fail(error) {
+    this.failure = error;
+    for (const waiter of this.waiting.values()) waiter.reject(error);
+    this.waiting.clear();
+  }
+  ask(call) {
+    if (this.failure) return Promise.reject(this.failure);
+    return new Promise((resolve, reject) => {
+      this.waiting.set(call.nid, { resolve, reject });
+      this.port.postMessage(call);
+    });
+  }
+  cancel(nid) {
+    const waiter = this.waiting.get(nid);
+    this.waiting.delete(nid);
+    waiter?.reject(new TransportError("the request was cancelled"));
+    this.port.postMessage({ net: "cancel", nid });
+  }
+  async fetch(request) {
+    const nid = ++this.nextId;
+    const { signal } = request;
+    signal.throwIfAborted();
+    let finished = false;
+    const abort = () => {
+      finished = true;
+      this.cancel(nid);
+    };
+    signal.addEventListener("abort", abort, { once: true });
+    const finish = () => {
+      if (finished) return;
+      finished = true;
+      signal.removeEventListener("abort", abort);
+    };
+    let head;
+    try {
+      head = await this.ask({
+        net: "fetch",
+        nid,
+        url: request.url,
+        method: request.method,
+        headers: request.headers,
+        ...request.body ? { body: request.body } : {}
+      });
+    } catch (e) {
+      finish();
+      throw e;
+    }
+    const { status, statusText, headers } = head;
+    const read = async () => {
+      if (finished) return void 0;
+      const reply = await this.ask({ net: "read", nid }).catch((e) => {
+        finish();
+        throw e;
+      });
+      if (reply.net === "chunk") return reply.bytes;
+      finish();
+      return void 0;
+    };
+    const cancel = async () => {
+      if (finished) return;
+      finish();
+      this.cancel(nid);
+    };
+    return {
+      status,
+      statusText,
+      headers,
+      cancel,
+      body: {
+        [Symbol.asyncIterator]: () => ({
+          next: async () => {
+            const bytes = await read();
+            return bytes ? { value: bytes, done: false } : { value: void 0, done: true };
+          },
+          return: async () => {
+            await cancel();
+            return { value: void 0, done: true };
+          }
+        })
+      }
+    };
+  }
+};
+
 // src/serve.ts
 function signalNumber(name2) {
   const key = name2.slice(3);
@@ -5884,94 +6459,262 @@ function signalNumber(name2) {
   return SIG[key];
 }
 
-// src/body-idle.ts
-var BODY_IDLE_MS = 5 * 60 * 1e3;
-function idleFailure(ms) {
-  return Object.assign(new Error(`the response body sent no data for ${ms} ms`), {
-    code: "ETIMEDOUT"
+// src/client/attach.ts
+var KernelGoneError = class extends Error {
+  constructor(message2 = "the slicc-kernel this client was attached to is gone") {
+    super(message2);
+    this.name = "KernelGoneError";
+  }
+};
+var KernelCallError = class extends Error {
+  code;
+  constructor(message2, code) {
+    super(message2);
+    this.name = "KernelCallError";
+    this.code = code;
+  }
+};
+var encoder4 = new TextEncoder();
+var bytesOf2 = (data) => typeof data === "string" ? encoder4.encode(data) : data;
+var UNAVAILABLE = {
+  manualRedirects: false,
+  encodedBodies: false,
+  maxRequestBody: 0,
+  unavailable: true
+};
+async function holdLock(locks) {
+  if (!locks) return { release() {
+  } };
+  const name2 = `slicc-kernel-client:${crypto.randomUUID()}`;
+  const granted = Promise.withResolvers();
+  const held = Promise.withResolvers();
+  void locks.request(name2, () => {
+    granted.resolve();
+    return held.promise;
   });
+  await granted.promise;
+  return { name: name2, release: () => held.resolve() };
 }
-async function readWithin(reader, ms) {
-  if (!(ms > 0 && ms < Number.POSITIVE_INFINITY)) return reader.read();
-  let timer;
-  const idle = new Promise((_, reject) => {
-    timer = setTimeout(() => reject(idleFailure(ms)), ms);
-  });
-  try {
-    return await Promise.race([reader.read(), idle]);
-  } finally {
-    clearTimeout(timer);
+function concat5(chunks2) {
+  const out = new Uint8Array(chunks2.reduce((n, c) => n + c.length, 0));
+  let at = 0;
+  for (const chunk2 of chunks2) {
+    out.set(chunk2, at);
+    at += chunk2.length;
   }
+  return out;
 }
-
-// src/transport.ts
-var MAX_REQUEST_BODY = 64 * 1024 * 1024;
-function joinHeaders(headers) {
-  const out = new Headers();
-  for (const [name2, value] of headers) {
-    try {
-      out.append(name2, value);
-    } catch {
+var Channel = class {
+  greeted = Promise.withResolvers();
+  ended = Promise.withResolvers();
+  remote;
+  failure;
+  pending = /* @__PURE__ */ new Map();
+  nextId = 0;
+  port;
+  release;
+  constructor(port, release) {
+    this.port = port;
+    this.release = release;
+    this.greeted.promise.catch(() => void 0);
+    port.addEventListener("message", (event) => this.receive(event.data));
+    port.addEventListener("close", () => this.end(new KernelGoneError()));
+    port.start?.();
+  }
+  post(message2) {
+    if (!this.failure) this.port.postMessage(message2);
+  }
+  end(error) {
+    if (this.failure) return;
+    this.failure = error;
+    this.greeted.reject(error);
+    this.remote?.fail(error);
+    for (const call of this.pending.values()) call.reject(error);
+    this.pending.clear();
+    this.release();
+    this.port.close?.();
+    this.ended.resolve(error);
+  }
+  request(call, handlers = {}) {
+    const id = ++this.nextId;
+    const { failure } = this;
+    if (failure) return { id, done: Promise.reject(failure) };
+    const done4 = new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject, ...handlers });
+      this.port.postMessage({ ...call, id });
+    });
+    return { id, done: done4 };
+  }
+  call(call) {
+    return this.request(call).done;
+  }
+  receive(data) {
+    if (data.bye !== void 0) {
+      this.end(new KernelGoneError(data.bye));
+      return;
+    }
+    if (data.hello) {
+      this.greeted.resolve(data.hello);
+      return;
     }
+    if (data.net !== void 0) {
+      this.remote?.receive(data);
+      return;
+    }
+    const reply = data;
+    const call = this.pending.get(reply.id);
+    if (!call) return;
+    if (reply.fd !== void 0) {
+      call.output?.(reply.fd, reply.bytes);
+      return;
+    }
+    if (reply.started !== void 0) {
+      call.started?.(reply.started);
+      return;
+    }
+    this.pending.delete(reply.id);
+    if (reply.error !== void 0) call.reject(new KernelCallError(reply.error, reply.code));
+    else call.resolve(reply.result);
   }
-  return out;
+};
+async function spawnOn(channel, argv, opts) {
+  const { onStdout, onStderr, stdin, group: _, ...rest } = opts;
+  const started = Promise.withResolvers();
+  const options = { ...rest, ...stdin !== void 0 ? { stdin: bytesOf2(stdin) } : {} };
+  const { done: done4 } = channel.request(
+    { op: "spawn", argv, options },
+    {
+      output: (fd, bytes) => (fd === 1 ? onStdout : onStderr)?.(bytes),
+      started: started.resolve
+    }
+  );
+  done4.catch(started.reject);
+  const pid = await started.promise;
+  return {
+    pid,
+    pgid: pid,
+    exited: done4,
+    signal: async (name2 = "SIGTERM") => void await channel.call({ op: "kill", pid: -pid, signal: name2 })
+  };
 }
-async function* chunks(body, idleMs) {
-  if (!body) return;
-  const reader = body.getReader();
-  try {
-    for (let next = await readWithin(reader, idleMs); !next.done; next = await readWithin(reader, idleMs)) {
-      if (next.value.byteLength > 0) yield next.value;
+async function runOn(channel, argv, opts) {
+  const { onStdout, onStderr, ...rest } = opts;
+  const chunks2 = { 1: [], 2: [] };
+  const live = { 1: new TextDecoder(), 2: new TextDecoder() };
+  const tee = (fd, on) => (bytes) => {
+    chunks2[fd].push(bytes);
+    on?.(live[fd].decode(bytes, { stream: true }));
+  };
+  const child = await spawnOn(channel, argv, {
+    ...rest,
+    onStdout: tee(1, onStdout),
+    onStderr: tee(2, onStderr)
+  });
+  const status = await child.exited;
+  const text = (fd) => new TextDecoder().decode(concat5(chunks2[fd]));
+  return { pid: child.pid, status, stdout: text(1), stderr: text(2) };
+}
+async function terminalOn(channel, argv, opts) {
+  const { onData, ...options } = opts;
+  let listener = onData ?? null;
+  const backlog = [];
+  const started = Promise.withResolvers();
+  const { id, done: done4 } = channel.request(
+    { op: "open-terminal", argv, options },
+    {
+      output: (_fd, bytes) => listener ? listener(bytes) : backlog.push(bytes),
+      started: started.resolve
     }
+  );
+  done4.catch(started.reject);
+  const pid = await started.promise;
+  const send = (action) => void channel.call({ op: "terminal", terminal: id, ...action }).catch(() => void 0);
+  return {
+    pid,
+    exited: done4,
+    get onData() {
+      return listener;
+    },
+    set onData(next) {
+      listener = next;
+      if (next) for (const bytes of backlog.splice(0)) next(bytes);
+    },
+    write: (data) => send({ action: "write", bytes: bytesOf2(data) }),
+    resize: (cols, rows) => send({ action: "resize", cols, rows }),
+    signal: (name2) => send({ action: "signal", signal: name2 }),
+    close: () => send({ action: "close" })
+  };
+}
+function fsOn(channel) {
+  const fs = (method, ...args) => channel.call({ op: "fs", method, args });
+  const done4 = async (method, ...args) => void await fs(method, ...args);
+  return {
+    readFile: (path) => fs("readFile", path),
+    readText: async (path) => new TextDecoder().decode(await fs("readFile", path)),
+    writeFile: (path, data) => done4("writeFile", path, data),
+    stat: (path) => fs("stat", path),
+    lstat: (path) => fs("lstat", path),
+    readdir: (path) => fs("readdir", path),
+    mkdir: (path) => done4("mkdir", path),
+    rm: (path, o = {}) => done4("rm", path, o.force === true),
+    rename: (from, to) => done4("rename", from, to),
+    realpath: (path) => fs("realpath", path),
+    symlink: (target, path) => done4("symlink", target, path),
+    readlink: (path) => fs("readlink", path),
+    exists: (path) => fs("exists", path)
+  };
+}
+async function greet(channel, lock, timeoutMs) {
+  channel.post({ hello: { protocol: PROTOCOL, ...lock ? { lock } : {} } });
+  const timer = setTimeout(
+    () => channel.end(
+      new KernelGoneError(`no slicc-kernel answered on this port within ${timeoutMs} ms`)
+    ),
+    timeoutMs
+  );
+  let hello;
+  try {
+    hello = await channel.greeted.promise;
   } finally {
-    await reader.cancel().catch(() => void 0);
+    clearTimeout(timer);
   }
-}
-function fetchTransport(options = {}) {
-  const send = options.fetch ?? globalThis.fetch.bind(globalThis);
+  const refused = hello.error ?? versionError(hello.protocol);
+  if (refused) {
+    const error = new Error(refused);
+    channel.end(error);
+    throw error;
+  }
+  return hello;
+}
+async function attachKernel(port, options = {}) {
+  const locks = options.locks === null ? void 0 : options.locks ?? locksOf();
+  const own = await holdLock(locks);
+  const channel = new Channel(port, own.release);
+  const hello = await greet(channel, own.name, options.timeoutMs ?? 1e4);
+  if (hello.lock && locks) void locks.request(hello.lock, () => channel.end(new KernelGoneError()));
+  const transport = new RemoteTransport(
+    { postMessage: (call) => channel.post(call) },
+    hello.traits ?? UNAVAILABLE
+  );
+  channel.remote = transport;
   return {
-    traits: {
-      manualRedirects: false,
-      encodedBodies: false,
-      maxRequestBody: options.maxRequestBody ?? MAX_REQUEST_BODY,
-      crossOrigin: "cors"
+    protocol: hello.protocol,
+    transport,
+    closed: channel.ended.promise,
+    spawn: (argv, opts = {}) => spawnOn(channel, argv, opts),
+    run: (argv, opts = {}) => runOn(channel, argv, opts),
+    openTerminal: (argv, opts = {}) => terminalOn(channel, argv, opts),
+    ps: () => channel.call({ op: "ps" }),
+    kill: async (pid, signal = "SIGTERM") => void await channel.call({ op: "kill", pid, signal }),
+    fetch: (req) => {
+      const { signal, ...rest } = req;
+      return transport.fetch({ ...rest, signal: signal ?? new AbortController().signal });
     },
-    async fetch(request) {
-      let response;
-      try {
-        response = await send(request.url, {
-          method: request.method,
-          headers: joinHeaders(request.headers),
-          ...request.body ? { body: request.body } : {},
-          signal: request.signal,
-          redirect: "follow",
-          credentials: "omit",
-          mode: "cors"
-        });
-      } catch (e) {
-        if (request.signal.aborted) throw e;
-        throw Object.assign(
-          new Error(
-            `fetch ${request.url} failed (unreachable, or not allowed by CORS)${options.hint ? `: ${options.hint}` : ""}`
-          ),
-          { status: 502 }
-        );
-      }
-      const headers = [];
-      response.headers.forEach((value, name2) => {
-        headers.push([name2, value]);
-      });
-      const body = chunks(response.body, options.bodyIdleMs ?? BODY_IDLE_MS);
-      return {
-        status: response.status,
-        statusText: response.statusText,
-        headers,
-        body,
-        cancel: async () => {
-          await body.return(void 0);
-          await response.body?.cancel().catch(() => void 0);
-        }
-      };
+    fs: fsOn(channel),
+    async close(o = {}) {
+      if (channel.failure) return;
+      await channel.call({ op: "detach", ...o.kill ? { kill: true } : {} }).catch(() => void 0);
+      channel.end(new KernelGoneError("this client is closed"));
     }
   };
 }
@@ -6033,6 +6776,7 @@ async function createNodeKernel(options = {}) {
   await fs.reconcile();
   const live = /* @__PURE__ */ new Set();
   const pending = /* @__PURE__ */ new Set();
+  const clients = /* @__PURE__ */ new Set();
   let terminated = false;
   const file = options.worker ?? new URL("./node-process-worker.js", import.meta.url);
   const transport = options.network?.transport;
@@ -6102,14 +6846,29 @@ async function createNodeKernel(options = {}) {
       await fs.writeFile(path, data);
     },
     readFile: async (path) => fs.readFileBuffer(path),
+    async connect() {
+      if (terminated) throw new Error(TERMINATED);
+      const { port1, port2 } = new MessageChannel2();
+      const served = serveClient(port1, {
+        launcher: async () => launcher,
+        signal: signalNumber
+      });
+      clients.add(served);
+      void served.closed.then(() => clients.delete(served));
+      return port2;
+    },
     terminate() {
       terminated = true;
+      for (const client of [...clients]) client.detach();
       for (const reject of [...pending]) reject(new Error(TERMINATED));
       for (const kill of [...live]) kill();
     }
   };
 }
 export {
+  KernelCallError,
+  KernelGoneError,
+  attachKernel,
   createNodeKernel,
   fetchTransport,
   memoryRoot,