@ai-ecoverse/slicc-kernel 1.29.2 → 1.30.1

package/README.md

@@ -64,7 +64,7 @@ Starts `argv` as the session leader on a new terminal and resolves once it is ru
 | --- | --- |
 | `pid` | the session leader's pid |
 | `onData` | the output listener; output that arrives while it is `null` is kept and delivered when one is set |
-| `write(data)` | types a string or bytes into the terminal; with `ISIG` on, `^C`, `^Z` and `^\` signal the foreground process group |
+| `write(data)` | types a string or bytes into the terminal; with `ISIG` on, `^C`, `^Z` and `^\` signal the foreground process group. A key typed while a child of that group is still setting up is held until the child has finished, then sent to the group in the foreground at that point. Setting up means the child's calls before its first other one: `setpgid`, `tcsetpgrp` and signal masks. The hold ends 250 ms after the child's first call at the latest. So `^Z` right after a command line stops the new job, as it does on Linux, where that setup takes microseconds rather than a worker start. |
 | `resize(cols, rows)` | sets the window size (`TIOCGWINSZ`) and sends `SIGWINCH` to the foreground process group |
 | `signal(name)` | sends a signal (`'SIGINT'`, `'SIGTSTP'`, `'SIGQUIT'`, `'SIGHUP'`, …) to the foreground process group, regardless of termios |
 | `exited` | resolves with the session leader's exit status (`128 + n` if killed by signal `n`) |
@@ -140,15 +140,38 @@ A WASI preview1 or WASIX program (Zig, Rust, Go, wasi-libc or wasix-libc C) has
 { "slicc": { "abi": "wasi", "commands": { "rg": { "wasm": "bin/rg.wasm" }, "rustc": { "script": "bin/rustc" } } } }
 ```
 
-Entries may also set `argv0`, `args` and `env`, and a package can set `slicc.env` for all of its commands. An entry with `"argv0Path": true` gets the absolute path it was run by as `argv[0]` when that path is a link outside `/bin` and `/usr/bin` to the command, as a venv's `bin/python` is (the `#!` line of a script naming such a link included), so it can find what sits beside that link; other entries keep their `argv0`. In `env`, `${package}` is the package directory, `${cwd}` the process's working directory, and `${NAME}` the caller's `NAME` when the program starts (a default naming an unset variable is left out); a relative path that exists in the package (`lib/python3.14`, `./`) becomes that absolute path. The caller's environment wins over these defaults; a `null` value removes the variable for the command, after the caller's environment is applied (a host-networked program can drop the kernel's proxy settings that way), and a command entry can set a variable its package's `slicc.env` removes. The first package to define a name wins. `sh` runs bash as `sh` unless a package provides its own. The installed commands appear as executables in a virtual `/usr/bin` and `/bin`, so `PATH` lookups, `command -v` and `ls /usr/bin` work without writing anything to OPFS. A process can also run a program by the path of its glue when the `.wasm` sits next to it, a wasm module by its own path (as a WASI program), and a script through its `#!` line (including `#!/usr/bin/env name`). Executing any other file fails with `ENOEXEC`, so bash runs it as a shell script, as POSIX shells do. Commands also come from pnpm's global directory. Every process gets `PNPM_HOME=/home/.local/share/pnpm`, unless the embedder sets its own, and has `$PNPM_HOME/bin` on `PATH`. The kernel scans each of pnpm's global install groups (`$PNPM_HOME/global/*/<group>/node_modules`) after `/node_modules`, which wins when both provide a command. The catalog is re-read whenever anything under either changes, so `pnpm add -g @ai-ecoverse/wasi-ripgrep` makes `rg` work in the same shell, and `pnpm remove -g` removes it again.
+Entries may also set `argv0`, `args` and `env`, and a package can set `slicc.env` for all of its commands. A WASI entry with `"preopenRoot": true` also gets `/` as a preopen (see [WASI programs](#wasi-programs)). An entry with `"argv0Path": true` gets the absolute path it was run by as `argv[0]` when that path is a link outside `/bin` and `/usr/bin` to the command, as a venv's `bin/python` is (the `#!` line of a script naming such a link included), so it can find what sits beside that link; other entries keep their `argv0`. In `env`, `${package}` is the package directory, `${cwd}` the process's working directory, and `${NAME}` the caller's `NAME` when the program starts (a default naming an unset variable is left out); a relative path that exists in the package (`lib/python3.14`, `./`) becomes that absolute path. The caller's environment wins over these defaults; a `null` value removes the variable for the command, after the caller's environment is applied (a host-networked program can drop the kernel's proxy settings that way), and a command entry can set a variable its package's `slicc.env` removes. The first package to define a name wins. `sh` runs bash as `sh` unless a package provides its own. The installed commands appear as executables in a virtual `/usr/bin` and `/bin`, so `PATH` lookups, `command -v` and `ls /usr/bin` work without writing anything to OPFS. A process can also run a program by the path of its glue when the `.wasm` sits next to it, a wasm module by its own path (as a WASI program), and a script through its `#!` line (including `#!/usr/bin/env name`). Executing any other file fails with `ENOEXEC`, so bash runs it as a shell script, as POSIX shells do. Commands also come from pnpm's global directory. Every process gets `PNPM_HOME=/home/.local/share/pnpm`, unless the embedder sets its own, and has `$PNPM_HOME/bin` on `PATH`. The kernel scans each of pnpm's global install groups (`$PNPM_HOME/global/*/<group>/node_modules`) after `/node_modules`, which wins when both provide a command. The catalog is re-read whenever anything under either changes, so `pnpm add -g @ai-ecoverse/wasi-ripgrep` makes `rg` work in the same shell, and `pnpm remove -g` removes it again.
 
 ### WASI programs
 
-A WASI program runs in a process worker of its own like an Emscripten one, against the same kernel: its descriptors, pipes, terminals and job control are the kernel's, and its files are OPFS. Preopens are `.` (the cwd), `/dev` and every top-level directory, plus the virtual `/usr` and `/bin`. On top of preview1 it gets:
+A WASI program runs in a process worker of its own like an Emscripten one, against the same kernel: its descriptors, pipes, terminals and job control are the kernel's, and its files are OPFS. **Preopens**, in order:
+1. `.`, the cwd, as fd 3, which Zig's std takes for its cwd;
+2. `/dev` and every top-level directory, plus the virtual `/usr` and `/bin`, sorted by name.
+
+Every WASI program sees `/` through the cwd.
+
+**`preopenRoot`.** A command whose manifest entry sets `"preopenRoot": true` gets two more preopens after those:
+3. `/`, the root;
+4. `./`, the cwd again.
+
+That's for programs that walk to the root, such as Go's (`GOOS=wasip1`) and esbuild's resolver. The order serves each runtime:
+- **Go** takes its working directory from `PWD`, which every process gets, and resolves absolute paths against the longest matching preopen name. So `os.ReadDir("/")`, `filepath.Abs("../..")` and walking up to the root work. Without `preopenRoot`, nothing is named `/` and they fail with `EBADF`.
+- **wasi-libc** (C, and Rust's `wasm32-wasip1`) reads `.`, `/` and `./` as the same empty prefix, and the last one wins. So the trailing `./` keeps relative paths on the cwd.
+- **Zig** keeps fd 3, and a second `.` would stop it from starting.
+
+**Working directory.** wasi-libc's own `getcwd()` stays `/` (Rust's `current_dir()`, `canonicalize(".")`) in either layout, because the C library starts with a working directory of `/` and no runtime can change it. A wasi-libc program that needs its real directory takes it from `PWD` (`set_current_dir($PWD)` at start); relative paths are the cwd either way. WASIX programs ask the kernel for their cwd and get the real one.
+
+**Descriptor numbers.** Preopens take consecutive descriptors from 3, since WASI libraries look for them until the first gap:
+- without `preopenRoot`: fds 3 through 3 + *n*, *n* being the number of top-level directories, `/dev`, `/usr` and `/bin` together;
+- with it: two more, through 3 + *n* + 2.
+
+A descriptor a program inherits at one of those numbers (from bash's `3<file`, or a `posix_spawn` file action) moves to the first free number above them. One above the range keeps its number. A command that takes descriptors by number from its caller should leave `preopenRoot` off, which keeps the shorter range.
+
+On top of preview1 a WASI program gets:
 
 - **Threads**: `wasi.thread-spawn` (wasm32-wasip1-threads) and WASIX `thread_spawn_v2` start a worker per thread on the process's shared memory, sized from the module's own import (a 2 GiB maximum when the engine cannot reserve more). The threads share one descriptor table; `exit` or a trap in any thread ends the process. At most 64 threads per process; `SLICC_WASM_THREADS` sets another cap, up to 256.
 - **WASIX** (a module importing `wasix_32v1`): fork and setjmp/longjmp through Asyncify (the module is built with `wasm-opt --asyncify`), exec, `posix_spawn`, `waitpid`, pipes, `dup2`, signal handlers and interval timers, terminal modes, and dynamic linking: a position-independent main module loads side modules with `dlopen` from `LD_LIBRARY_PATH`, its runtime path, `/lib`, `/usr/lib` and `/usr/local/lib`.
-- **Sockets**: the WASIX socket calls (`sock_open`, `bind`, `listen`, `connect`, `accept`, options, local and peer names) are the kernel's loopback sockets, and preview1's `sock_recv` / `sock_send` / `sock_shutdown` work on them and on inherited ones. Writing to a socket whose peer is gone fails with `EPIPE`, through `fd_write` as through `sock_send`, as if `MSG_NOSIGNAL` were set, since a WASI program cannot ignore `SIGPIPE`; a pipe or terminal whose reader is gone still ends the program with status 141. HTTP and HTTPS leave through the realm proxy that `https_proxy` names, as for any other program; `resolve` answers loopback names and literal addresses.
+- **Sockets**: the WASIX socket calls (`sock_open`, `bind`, `listen`, `connect`, `accept`, options, local and peer names) are the kernel's loopback sockets, and preview1's `sock_recv` / `sock_send` / `sock_shutdown` work on them and on inherited ones. Writing to a socket whose peer is gone fails with `EPIPE`, through `fd_write` as through `sock_send`, as if `MSG_NOSIGNAL` were set, since a WASI program cannot ignore `SIGPIPE`; a pipe or terminal whose reader is gone still ends the program with status 141. HTTP and HTTPS leave through the realm proxy that `https_proxy` names, as for any other program; `resolve` answers `/etc/hosts` names and literal addresses, and the [uplink](#uplink)'s names.
 - **Diagnostics**: a trap ends the program with 134 and its message on stderr; with `SLICC_WASM_BACKTRACE=1` the wasm frames follow, named from the module's name section, or from a sidecar for a module shipped without one (`<module>.names` beside it, or the same path in a `<package>-names` package). `SLICC_WASI_STATS=1` makes a program print its calls, counted and timed, as it ends.
 
 ### Program imports

package/dist/kernel-worker.js

@@ -4550,6 +4550,7 @@ function commandOf(pkg, name2, raw, packageAbi, shared) {
     wasm,
     argv0,
     ...raw.argv0Path === true ? { argv0Path: true } : {},
+    ...abi === "wasi" && raw.preopenRoot === true ? { preopenRoot: true } : {},
     ...args ? { args } : {},
     ...withEnv,
     ...imports ? { imports } : {}
@@ -7875,7 +7876,7 @@ var WasmProcess = class {
     for (const listener of this.stateListeners) listener("continued", SIG.CONT);
   }
   async syscall(req) {
-    this.options.onSyscall?.();
+    this.options.onSyscall?.(req);
     for (; ; ) {
       await this.resumed;
       const stops = this.stops;
@@ -7999,9 +8000,10 @@ var WasmProcess = class {
           json: this.fds.numbers().map((fd) => ({ fd, ...this.fdInfo(fd) }))
         };
       case "fd-meta": {
-        const file = this.fds.get(req.fd).file;
-        if (!file.held) throw new KernelError("EBADF");
-        file.heldMeta = req.meta;
+        if (!this.fds.get(req.fd).file.held) throw new KernelError("EBADF");
+        const cloexec = this.fds.closesOnExec(req.fd);
+        this.fds.installAt(req.fd, heldFile(req.meta));
+        if (cloexec) this.fds.setCloseOnExec(req.fd);
         return { ok: true, kind: "void" };
       }
       case "fd-setfl":
@@ -8668,6 +8670,57 @@ var JobTable = class {
   }
 };
 
+// src/kernel/settling.ts
+var SETUP_OPS = /* @__PURE__ */ new Set([
+  "proc-list",
+  "proc-identity",
+  "fd-info",
+  "sig-mask",
+  "proc-setpgid",
+  "tty-pgrp-set"
+]);
+var SETTLE_MS = 250;
+var KEY_SIGNALS = /* @__PURE__ */ new Set([2, 3, 20]);
+var SettlingChildren = class {
+  children = /* @__PURE__ */ new Map();
+  held = [];
+  pgidOf;
+  settleMs;
+  constructor(pgidOf, settleMs = SETTLE_MS) {
+    this.pgidOf = pgidOf;
+    this.settleMs = settleMs;
+  }
+  started(pid, ppid) {
+    this.children.set(pid, { ppid });
+  }
+  syscall(pid, op) {
+    const child = this.children.get(pid);
+    if (!child) return;
+    if (!SETUP_OPS.has(op)) {
+      this.settled(pid);
+      return;
+    }
+    child.timer ??= setTimeout(() => this.settled(pid), this.settleMs);
+  }
+  settled(pid) {
+    const child = this.children.get(pid);
+    if (!child) return;
+    clearTimeout(child.timer);
+    this.children.delete(pid);
+    const ready2 = this.held.filter((h) => !this.blocking(h.pgid));
+    this.held = this.held.filter((h) => this.blocking(h.pgid));
+    for (const h of ready2) h.send();
+  }
+  deliver(sig, pgid, send) {
+    if (KEY_SIGNALS.has(sig) && this.blocking(pgid)) this.held.push({ pgid, send });
+    else send();
+  }
+  blocking(pgid) {
+    for (const { ppid } of this.children.values()) if (this.pgidOf(ppid) === pgid) return true;
+    return false;
+  }
+};
+
 // src/mount/driver.ts
 function fsError2(code, message2 = code) {
   return Object.assign(new Error(message2), { code });
@@ -9893,7 +9946,8 @@ function targetOf(command) {
     ...command.args ? { prefix: command.args } : {},
     ...command.env ? { env: command.env } : {},
     ...command.unset ? { unset: command.unset } : {},
-    ...command.imports ? { imports: command.imports } : {}
+    ...command.imports ? { imports: command.imports } : {},
+    ...command.preopenRoot ? { preopenRoot: true } : {}
   };
 }
 function childHandle(handle) {
@@ -9927,7 +9981,14 @@ var Launcher = class {
   described = /* @__PURE__ */ new Map();
   jobs = new JobTable();
   locks = new LockTable();
-  ptys = new PtyTable((tty, sig) => this.jobs.signalOwnedForeground(tty, sig));
+  settling = new SettlingChildren((pid) => this.jobs.pgidOf(pid));
+  ptys = new PtyTable(
+    (tty, sig) => this.settling.deliver(
+      sig,
+      this.jobs.tcgetpgrp(tty, 0),
+      () => this.jobs.signalOwnedForeground(tty, sig)
+    )
+  );
   net = new LoopbackNet();
   cdp;
   ca;
@@ -10129,7 +10190,8 @@ var Launcher = class {
       ...memory ? { memory } : {},
       foreign,
       ...names ? { names } : {},
-      ...imports !== void 0 ? { imports } : {}
+      ...imports !== void 0 ? { imports } : {},
+      ...target.preopenRoot ? { preopenRoot: true } : {}
     };
   }
   async launch(planned, req) {
@@ -10166,7 +10228,10 @@ var Launcher = class {
         await (asked ??= decided.then(count));
         return this.identityOf(pid);
       },
-      onSyscall: () => this.decide(pid),
+      onSyscall: (call) => {
+        this.decide(pid);
+        this.settling.syscall(pid, call.op);
+      },
       ...req.ignored ? { ignored: req.ignored } : {},
       program: req.program,
       argv0: req.argv0,
@@ -10199,6 +10264,7 @@ var Launcher = class {
       ...this.shownIds(req)
     });
     this.processes.set(pid, handle);
+    if (req.ppid !== void 0) this.settling.started(pid, req.ppid);
     this.jobs.add(pid, req.ppid, (sig) => handle.signal(sig), terminal);
     if (req.exec && req.ppid !== void 0) this.jobs.exec(req.ppid, pid, true);
     if (req.pgid !== void 0) this.jobs.join(pid, req.pgid);
@@ -10209,6 +10275,7 @@ var Launcher = class {
     });
     void handle.exited.then(() => {
       this.processes.delete(pid);
+      this.settling.settled(pid);
       if (req.ppid === void 0 || this.orphans.delete(pid)) this.forget(pid);
       else this.zombies.add(pid);
     });
@@ -10521,7 +10588,11 @@ var Launcher = class {
     let leader = 0;
     const tty = new KernelTty(
       { write: (bytes) => options.onData(bytes.slice()) },
-      (sig) => this.jobs.signalForeground(tty, leader, sig)
+      (sig) => this.settling.deliver(
+        sig,
+        this.jobs.tcgetpgrp(tty, leader),
+        () => this.jobs.signalForeground(tty, leader, sig)
+      )
     );
     tty.name = `/dev/tty${++this.terminals}`;
     tty.setSize(options.cols ?? 80, options.rows ?? 24);