@ai-ecoverse/slicc-kernel 1.8.12 → 1.10.0

package/dist/kernel-worker.js

@@ -193,6 +193,33 @@ function pinScript(url) {
   }
 }
 
+// src/client/protocol.ts
+var PROTOCOL = [1, 1];
+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/fs/types.ts
 function fsError(code, path) {
   return Object.assign(new Error(`${code}: ${path}`), { code });
@@ -222,13 +249,378 @@ function inodeOf(path) {
   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;
+
+// src/transport.ts
+var MAX_REQUEST_BODY = 64 * 1024 * 1024;
+function serveTransport(peer, transport) {
+  const open = /* @__PURE__ */ new Map();
+  const fail = (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) {
+      fail(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) {
+      fail(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/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();
+  const watches = /* @__PURE__ */ new Map();
+  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 unwatch of watches.values()) unwatch();
+    watches.clear();
+    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 "watch": {
+        const unwatch = l.watchers.watch(
+          req.paths,
+          { recursive: req.recursive },
+          (change) => send({ watch: req.id, change })
+        );
+        watches.set(req.id, unwatch);
+        return { result: req.id };
+      }
+      case "unwatch":
+        watches.get(req.watch)?.();
+        watches.delete(req.watch);
+        return { result: true };
+      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/opfs.ts
 var S_IFDIR = 16384;
 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 = {
@@ -379,7 +771,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) {
@@ -2412,6 +2804,7 @@ var RemoteTransport = class {
   port;
   waiting = /* @__PURE__ */ new Map();
   nextId = 0;
+  failure;
   constructor(port, traits) {
     this.port = port;
     this.traits = traits;
@@ -2424,7 +2817,13 @@ var RemoteTransport = class {
       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);
@@ -2502,61 +2901,6 @@ var RemoteTransport = 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/commands.ts
 var NAME = /^[A-Za-z0-9._+-]+$/;
 var ENV_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -2687,7 +3031,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";
 }
@@ -2707,7 +3051,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("/")) || "/";
@@ -2795,6 +3139,89 @@ function withCommandDirs(fs, names) {
   };
 }
 
+// src/fs/watch.ts
+var WATCH_BATCH_LIMIT = 1e3;
+var under2 = (path, dir) => dir === "/" || path.startsWith(`${dir}/`);
+var parentOf3 = (path) => path.slice(0, path.lastIndexOf("/")) || "/";
+function touches(watcher, changed) {
+  return watcher.paths.some(
+    (watched) => changed === watched || under2(watched, changed) || (watcher.recursive ? under2(changed, watched) : parentOf3(changed) === watched)
+  );
+}
+var FsWatchers = class {
+  watchers = /* @__PURE__ */ new Set();
+  watch(paths, options, notify) {
+    const watcher = {
+      paths: paths.map(normalizePath),
+      recursive: options.recursive === true,
+      notify,
+      pending: /* @__PURE__ */ new Set(),
+      scheduled: false
+    };
+    this.watchers.add(watcher);
+    return () => {
+      this.watchers.delete(watcher);
+    };
+  }
+  changed(...paths) {
+    for (const watcher of this.watchers) {
+      for (const path of paths) {
+        const changed = normalizePath(path);
+        if (touches(watcher, changed)) watcher.pending.add(changed);
+      }
+      if (watcher.pending.size === 0 || watcher.scheduled) continue;
+      watcher.scheduled = true;
+      setTimeout(() => this.flush(watcher), 0);
+    }
+  }
+  flush(watcher) {
+    watcher.scheduled = false;
+    const paths = [...watcher.pending];
+    watcher.pending.clear();
+    if (!this.watchers.has(watcher)) return;
+    watcher.notify(paths.length > WATCH_BATCH_LIMIT ? { overflow: true } : { paths });
+  }
+  wrap(fs) {
+    const after = (run2, changed) => async (...args) => {
+      try {
+        await run2(...args);
+      } finally {
+        this.changed(...changed(...args));
+      }
+    };
+    const overrides = {
+      writeFile: after(fs.writeFile.bind(fs), (path) => [path]),
+      mkdir: async (path, options) => {
+        const created = [];
+        if (options?.recursive) {
+          const parts = normalizePath(path).split("/").filter(Boolean);
+          for (let at = 1; at < parts.length; at++) {
+            const ancestor = `/${parts.slice(0, at).join("/")}`;
+            if (created.length > 0 || !await fs.exists(ancestor)) created.push(ancestor);
+          }
+        }
+        try {
+          await fs.mkdir(path, options);
+        } finally {
+          this.changed(...created, path);
+        }
+      },
+      rm: after(fs.rm.bind(fs), (path) => [path]),
+      rename: after(fs.rename.bind(fs), (from, to) => [from, to]),
+      symlink: after(fs.symlink.bind(fs), (_target, path) => [path]),
+      chmod: after(fs.chmod.bind(fs), (path) => [path]),
+      utimes: after(fs.utimes.bind(fs), (path) => [path])
+    };
+    return new Proxy(fs, {
+      get(target, key, receiver) {
+        if (Object.hasOwn(overrides, key)) return overrides[key];
+        const value = Reflect.get(target, key, receiver);
+        return typeof value === "function" ? value.bind(target) : value;
+      }
+    });
+  }
+};
+
 // src/kernel/children.ts
 var SpawnError = class extends Error {
   code;
@@ -4712,6 +5139,7 @@ var SYSCALL_OPS = /* @__PURE__ */ new Set([
   "proc-captured",
   "proc-fork",
   "proc-kill",
+  "proc-list",
   "proc-exec",
   "proc-setpgid",
   "proc-getpgid",
@@ -5160,6 +5588,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" };
@@ -5263,6 +5697,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,
@@ -5407,6 +5842,9 @@ var JobTable = class {
     this.members.set(pid, member);
     return member;
   }
+  list() {
+    return [...this.members.values()];
+  }
   remove(pid) {
     this.members.delete(pid);
   }
@@ -5737,16 +6175,19 @@ 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));
   net = new LoopbackNet();
   ca;
   transport;
+  watchers = new FsWatchers();
   nextPid = 1e3;
+  boot = Date.now();
   terminals = 0;
   constructor(options) {
-    this.base = options.fs;
+    this.base = this.watchers.wrap(options.fs);
     this.createWorker = options.createWorker;
     this.modulesDir = options.modules ?? "/node_modules";
     this.env = { ...networkEnv(), ...options.env };
@@ -5757,7 +6198,7 @@ var Launcher = class {
       engine: kernelTlsEngine(packageTlsEngine(options.fs, this.modulesDir)),
       ca: this.ca
     });
-    this.fs = withCommandDirs(options.fs, async () => new Set((await this.commands()).keys()));
+    this.fs = withCommandDirs(this.base, async () => new Set((await this.commands()).keys()));
   }
   commands() {
     this.catalog ??= scanCommands(this.base, this.modulesDir);
@@ -5915,6 +6356,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,
@@ -5926,17 +6368,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);
@@ -6014,8 +6496,9 @@ var Launcher = class {
     const env = this.environment(cwd, options.env);
     const out = [];
     const err = [];
+    const keep = options.collect !== false;
     const collect = (chunks, tee) => (bytes) => {
-      chunks.push(bytes);
+      if (keep) chunks.push(bytes);
       tee?.(bytes);
     };
     const stdout = collect(out, options.onStdout);
@@ -6031,6 +6514,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) };
   }
@@ -6043,7 +6527,7 @@ function signalNumber(name2) {
     throw new Error(`unknown signal ${name2}`);
   return SIG[key];
 }
-function act(session, req) {
+function act2(session, req) {
   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(signalNumber(req.signal));
@@ -6056,7 +6540,35 @@ function serveKernel(port, deps) {
   let launcher;
   let remote;
   const terminals = /* @__PURE__ */ new Map();
-  const reply = (id, body) => port.postMessage({ id, ...body });
+  const reply = (id, body, transfer) => port.postMessage({ id, ...body }, transfer);
+  const clients = /* @__PURE__ */ new Set();
+  const locks = deps.locks === null ? void 0 : deps.locks ?? locksOf();
+  let holding;
+  function holdLock(locks2) {
+    holding ??= new Promise((resolve) => {
+      const name2 = `slicc-kernel:${crypto.randomUUID()}`;
+      void locks2.request(name2, () => {
+        resolve(name2);
+        return new Promise(() => {
+        });
+      });
+    });
+    return holding;
+  }
+  async function connect() {
+    await ready2();
+    const { port1, port2 } = new MessageChannel();
+    const held = locks ? await holdLock(locks) : void 0;
+    const served = serveClient(port1, {
+      launcher: ready2,
+      signal: signalNumber,
+      ...locks ? { locks } : {},
+      ...held ? { lock: held } : {}
+    });
+    clients.add(served);
+    void served.closed.then(() => clients.delete(served));
+    return port2;
+  }
   async function ready2() {
     if (!launcher) throw new Error("the kernel is not initialized");
     return launcher;
@@ -6095,10 +6607,11 @@ function serveKernel(port, deps) {
       return true;
     }
     if (req.op === "open-terminal") return terminal(req);
+    if (req.op === "connect") return connect();
     if (req.op === "terminal") {
       const session = terminals.get(req.terminal);
       if (!session) throw new Error(`no terminal ${req.terminal}`);
-      act(session, req);
+      act2(session, req);
       return true;
     }
     return (await ready2()).run(req.argv, {
@@ -6114,7 +6627,7 @@ function serveKernel(port, deps) {
     }
     const req = event.data;
     handle(req).then(
-      (result) => reply(req.id, { result }),
+      (result) => reply(req.id, { result }, result instanceof MessagePort ? [result] : void 0),
       (err) => reply(req.id, { error: err instanceof Error ? err.message : String(err) })
     );
   });