@ai-ecoverse/slicc-kernel 1.178.3 → 1.179.0

package/README.md

@@ -57,6 +57,7 @@ Runs `argv[0]` with `argv` as its arguments and resolves when it exits. `stdout`
 | option | |
 | --- | --- |
 | `cwd` | working directory, default `/`; created in OPFS if missing. Under `users: 'enforce'`, a `cwd` the user can't search rejects with `code: 'EACCES'` (`cannot change to <cwd>: Permission denied`) and starts nothing, as a `chdir` there fails on Linux; `openTerminal` does the same. A program's spawn with its own `cwd` (`ctx.spawn`, `ctx.sync.run`, a WASIX `posix_spawn` chdir action) is checked the same way and fails with `EACCES`, while a child that inherits its parent's cwd keeps it unchecked, as on Linux |
+| `cwdMissing` | `'create'` (the default) or `'error'`: what happens when `cwd` doesn't exist. `'create'` creates it, with its parents, as described for `cwd`. `'error'` rejects with `code: 'ENOENT'` (`cannot change to <cwd>: No such file or directory`) and starts nothing, as a `chdir` there fails on Linux. A caller that keeps directories in a list to run commands in, and so may name one that was removed since, should pass `'error'`: with `'create'`, its next command brings the removed directory back, empty ([#1808](https://github.com/ai-ecoverse/slicc-kernel/issues/1808)). Any other value rejects with a `TypeError`; `openTerminal` takes it too |
 | `user` | the user to run as, by name or uid (see [Users](#users)); default `root`. An unknown user rejects with `code: 'ENOENT'` |
 | `tag` | a string the kernel keeps with the process and every process it starts (fork, spawn and exec), and hands to `approve` with a [`sudo`](#sudo) request, so the embedder knows which agent asks; nothing a program does changes it. Anything but a string rejects with a `TypeError` |
 | `env` | extra environment, over the user's defaults: `HOME`, `USER`, `LOGNAME`, `PNPM_HOME` and `PATH=$PNPM_HOME/bin:/usr/local/bin:/usr/bin:/bin` (see [Users](#users)), `TZ=<system time zone>` (see [Time zone](#time-zone)), and `PWD=<cwd>` |
@@ -69,7 +70,7 @@ Starts `argv` as the session leader on a new terminal and resolves once it is ru
 
 | option | |
 | --- | --- |
-| `cwd`, `user`, `tag`, `env` | as for `run`; `TERM=xterm-256color` and `COLORTERM=truecolor` are added |
+| `cwd`, `cwdMissing`, `user`, `tag`, `env` | as for `run`; `TERM=xterm-256color` and `COLORTERM=truecolor` are added |
 | `cols`, `rows` | initial size, default 80 × 24, so `$COLUMNS` and `$LINES` are right before the first prompt |
 | `onData` | called with each chunk of output as raw bytes (escape sequences included) |
 
@@ -176,7 +177,7 @@ Attaches to a kernel over a port from `kernel.connect()`, in any realm: a worker
 
 | Client | |
 |---|---|
-| `spawn(argv, { cwd, user, env, stdin, pgid, onStdout, onStderr })` | runs over pipes and resolves with `{ pid, pgid, exited, ended, signal(name) }` once the process has started; `ended` resolves with `{ status, signal }`, `signal` named only when a signal ended the process, as for `kernel.run` (an older kernel never names one); output arrives in chunks, as bytes, and the kernel keeps no copy; every spawn leads its own process group, which `signal` (default `SIGTERM`) signals, unless `pgid` names an existing group to join (protocol 1.3): the process then joins that group and that group's session, as `setpgid` would (a client has no session of its own: each of its spawns and terminals leads one, and `setpgid` cannot cross sessions), and `signal` signals the whole group. The group must have been started by this client (a spawn or a terminal it opened), even if its leader has exited; an unknown group rejects with `code: 'ESRCH'`, another session's with `code: 'EPERM'`, and against a 1.2 kernel the client rejects with `code: 'ENOSYS'` before sending anything, as an older kernel would ignore the option; a program that cannot start rejects with `code: 'ENOENT'`. `user` runs it as another user, which only a root client may (see `kernel.connect`); against a 1.7 kernel the client rejects with `code: 'ENOSYS'` |
+| `spawn(argv, { cwd, cwdMissing, user, env, stdin, pgid, onStdout, onStderr })` | runs over pipes and resolves with `{ pid, pgid, exited, ended, signal(name) }` once the process has started; `ended` resolves with `{ status, signal }`, `signal` named only when a signal ended the process, as for `kernel.run` (an older kernel never names one); output arrives in chunks, as bytes, and the kernel keeps no copy; every spawn leads its own process group, which `signal` (default `SIGTERM`) signals, unless `pgid` names an existing group to join (protocol 1.3): the process then joins that group and that group's session, as `setpgid` would (a client has no session of its own: each of its spawns and terminals leads one, and `setpgid` cannot cross sessions), and `signal` signals the whole group. The group must have been started by this client (a spawn or a terminal it opened), even if its leader has exited; an unknown group rejects with `code: 'ESRCH'`, another session's with `code: 'EPERM'`, and against a 1.2 kernel the client rejects with `code: 'ENOSYS'` before sending anything, as an older kernel would ignore the option; a program that cannot start rejects with `code: 'ENOENT'`. `user` runs it as another user, which only a root client may (see `kernel.connect`); against a 1.7 kernel the client rejects with `code: 'ENOSYS'`. `cwdMissing` is as for `kernel.run` (protocol 1.14); `run` and `openTerminal` take it too, and with `'error'` against a 1.13 kernel, which would create the directory, the client rejects with `code: 'ENOSYS'` before sending anything |
 | `run(argv, options?)` | `spawn` and wait: `{ pid, status, signal, stdout, stderr }` as text, with `onStdout`/`onStderr` streaming text; `signal` as for `kernel.run` |
 | `openTerminal(argv, options?)` | a pty session, as `kernel.openTerminal`, `ended` included |
 | `ps()` | the kernel's processes: `{ pid, ppid, pgid, sid, argv, tty, started, state, rss, utime, stime, uid, gid }`, `state` being `'S'`, `'T'` (stopped) or `'Z'`, `rss` the process's resident memory in bytes (the size of its wasm memory, what `/proc/<pid>/status` shows as `VmRSS`; absent from kernels before 1.61), `utime`/`stime` the CPU time it has used, in milliseconds, in its program and in the kernel's calls (see [`/proc`](#proc); absent for a JS program and from kernels before 1.63) and `uid`/`gid` the effective ids (absent from a 1.7 kernel), and `tag` the process's tag (see `kernel.run`), when it has one, with `tags`, all of them in order, when a spawn added one (see `kernel.connect`), on rows the client's user may see as root or as the same uid. A client bound to a user sees only that user's processes |
@@ -1067,7 +1068,7 @@ With `users: 'enforce'`, the default, or `'report'`, files have owners, and [Per
 - **Homes:** every `kernel.users.add` gives the user's home (only a real directory at `/home/<dir>`, not a symlink or a path through one) and everything in it without an owner of its own to the user, and sets the home's mode: `0700`, `0750` for a `scoop-` user, `2750` with `homeGroup`, and its `~/.local/share/pnpm`'s to `0700` (`0750` for a `scoop-` user). The embedder calls `add` for each user at boot, as it already does, so homes made before owners were on become the user's. That also means a user's own `chmod` or `chgrp` of its home lasts only until the next `add`, and `add` must get the same `homeGroup` every time.
 - **`chown`, `lchown`, `fchown`:** Emscripten programs, and WASI programs through `slicc_fs` (see [File modes and the umask](#file-modes-and-the-umask)), change owners through the kernel, by the Linux rules: root may set any owner and group; a file's owner may set its group to one it belongs to, or leave it as it is; anything else fails with `EPERM`. `-1` keeps an id. A `chown` that sets an owner or group of a file clears its setuid bit, and its setgid bit if the file is group-executable, whoever calls it, root included, as on Linux. With `users: 'off'`, `chown` succeeds and changes nothing, as before.
 - **What programs see:** `stat` shows the owners to Emscripten programs, whatever their libc reports for their own ids, so a program built before H1 sees real owners too, and its owner checks can fail. WASI programs read them with `slicc_fs.fd_owner` and `path_owner`. The commands in `/usr/bin` and `/bin` are root's, and a user's own commands in `~/.local/share/pnpm/bin` belong to the owner of the closest real directory above them, normally the user.
-- **Mounts:** the options `uid=` and `gid=` (decimal ids) give a mount its owner; without them it belongs to whoever mounted it: root for `kernel.mount`, `/etc/fstab` and a client, the process's effective ids for `mount(2)`, which then shows them in its options (a process that isn't root gets its own ids whatever `uid=` and `gid=` it passes, so it can't make a mount look root's). A mount whose driver keeps owners (`tmpfs`) starts with its root owned so, and its files get owners as on the root file system, `chown` included. On `hostfs`, `fsa` and any driver without `owners`, every file shows as the mount's owner and `chown` fails with `EPERM`, root's too, as on a FAT drive. An embedder that mounts a folder for a user (bios's linked and picked folders) passes that user's `uid` and `gid`, or the user's programs see root's files there, and git calls the repository's ownership dubious. Those mounts also take the FAT-style options `umask=`, `fmask=` and `dmask=` (octal, as on Linux `vfat`): when any is set, the kernel synthesises the permission bits that `stat` and DAC see from `0666` for files and `0777` for directories (and symlinks), less the mask (`fmask` for files, `dmask` for directories, and `umask` as the default for both). Without them, files stay `0644` and directories `0755` as before, so only the mount's `uid` may write. `umask=000` (or `fmask=000,dmask=000`) makes every file and directory world-writable under DAC, which is how a personal cone (another uid) can write a folder mounted as the template `cone` user. When a mask is set on a mount without a `chmod` capability (`fsa`), `chmod` is a no-op and is not owner-only, so a create that then sets the mode from another uid still succeeds. Without a mask, and on a mount that keeps real modes through `chmod` (`hostfs`), `chmod` still requires the mount's `uid` (or root). Drivers with `owners` (`tmpfs`) ignore the mask options: their modes stay real, and chmod still requires the owner.
+- **Mounts:** the options `uid=` and `gid=` (decimal ids) give a mount its owner; without them it belongs to whoever mounted it: root for `kernel.mount`, `/etc/fstab` and a client, the process's effective ids for `mount(2)`, which then shows them in its options (a process that isn't root gets its own ids whatever `uid=` and `gid=` it passes, so it can't make a mount look root's). A mount whose driver keeps owners (`tmpfs`) starts with its root owned so, and its files get owners as on the root file system, `chown` included. On `hostfs`, `fsa` and any driver without `owners`, every file shows as the mount's owner and `chown` fails with `EPERM`, root's too, as on a FAT drive. An embedder that mounts a folder for a user (bios's linked and picked folders) passes that user's `uid` and `gid`, or the user's programs see root's files there, and git calls the repository's ownership dubious. Those mounts also take the FAT-style options `umask=`, `fmask=` and `dmask=` (octal, as on Linux `vfat`): when any is set, the kernel synthesises the permission bits that `stat` and DAC see from `0666` for files and `0777` for directories (and symlinks), less the mask (`fmask` for files, `dmask` for directories, and `umask` as the default for both). Without them, files stay `0644` and directories `0755` as before, so only the mount's `uid` may write. `umask=000` (or `fmask=000,dmask=000`) makes every file and directory world-writable under DAC, which is how a personal cone (another uid) can write a folder mounted as the template `cone` user. When a mask is set on a mount without a `chmod` capability (`fsa`), `chmod` is a no-op and is not owner-only, so a create that then sets the mode from another uid still succeeds, and a non-owner who can write the file may set its times to an explicit value (`utimes` / `cp -p` / `tar x`), as on Linux `vfat` with a uid/umask mount; "now" times already needed only write access. Without a mask, and on a mount that keeps real modes through `chmod` (`hostfs`), `chmod` still requires the mount's `uid` (or root), and explicit times stay owner-only. Drivers with `owners` (`tmpfs`) ignore the mask options: their modes stay real, and chmod and explicit times still require the owner.
 
 ### Permissions
 

package/dist/driver-worker.js

@@ -824,7 +824,7 @@ async function loopbackFetch(dial, input, options) {
 }
 
 // src/client/protocol.ts
-var PROTOCOL = [1, 13];
+var PROTOCOL = [1, 14];
 function locksOf(scope = globalThis) {
   const locks = scope.navigator?.locks;
   return typeof locks?.request === "function" ? locks : void 0;
@@ -1059,6 +1059,8 @@ async function spawnOn(channel, argv, opts) {
   });
   if (opts.tag !== void 0) await since(channel, 12, "a tag per spawn", async () => {
   });
+  if (opts.cwdMissing === "error") await since(channel, 14, "cwdMissing: 'error'", async () => {
+  });
   const started = Promise.withResolvers();
   let endedBy;
   const options = { ...rest, ...stdin !== void 0 ? { stdin: bytesOf2(stdin) } : {} };
@@ -1118,6 +1120,8 @@ async function terminalOn(channel, argv, opts) {
   });
   if (opts.tag !== void 0) await since(channel, 12, "a tag per terminal", async () => {
   });
+  if (opts.cwdMissing === "error") await since(channel, 14, "cwdMissing: 'error'", async () => {
+  });
   let listener = onData ?? null;
   const backlog = [];
   const started = Promise.withResolvers();