@ai-ecoverse/slicc-kernel 1.0.0 → 1.1.0

package/README.md

@@ -37,10 +37,30 @@ Runs `argv[0]` with `argv` as its arguments and resolves when it exits. `stdout`
 | option | |
 | --- | --- |
 | `cwd` | working directory, default `/`; created in OPFS if missing |
-| `env` | extra environment; the defaults are `PATH=/usr/bin:/bin`, `HOME=/`, `PWD=<cwd>` |
+| `env` | extra environment; the defaults are `PATH=/usr/bin:/bin`, `HOME=/home`, `PWD=<cwd>` |
 | `stdin` | a string or `Uint8Array`; without it stdin is `/dev/null` |
 | `onStdout`, `onStderr` | called with each chunk of text as it is written |
 
+### `kernel.openTerminal(argv, options?) → Promise<Terminal>`
+
+Starts `argv` as the session leader on a new terminal and resolves once it is running, or rejects if `argv[0]` cannot be found. Its stdin, stdout and stderr are the terminal, which has a line discipline with echo, canonical mode and `ISIG`, and supports job control, so `kernel.openTerminal(['bash', '-i'])` gives an interactive shell. The API was designed with [slicc-spectrum](https://github.com/ai-ecoverse/slicc-spectrum), a terminal web component, and these names are kept stable.
+
+| option | |
+| --- | --- |
+| `cwd`, `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) |
+
+| `Terminal` | |
+| --- | --- |
+| `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 |
+| `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`) |
+| `close()` | hangs up: `SIGHUP` to the foreground process group, and reads from the terminal return end-of-file |
+
 ### `kernel.terminate()`
 
 Stops the kernel worker and every process. Pending and later calls reject.
@@ -53,14 +73,18 @@ Commands come from installed packages in npm's `node_modules` layout: every `<mo
 { "slicc": { "abi": "emscripten", "commands": { "bash": { "glue": "bin/bash", "wasm": "bin/bash.wasm" } } } }
 ```
 
-Entries may also set `argv0`, `args` and `env` (with `${package}` expanded to the package directory), and a package-wide `slicc.env`. 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, and a script through its `#!` line (including `#!/usr/bin/env name`). The catalog is re-read at the start of every `run`, so packages installed in between are picked up.
+Entries may also set `argv0`, `args` and `env` (with `${package}` expanded to the package directory), and a package-wide `slicc.env`. 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, 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. The catalog is re-read at the start of every `run`, so packages installed in between are picked up.
 
 ## Filesystem
 
-`/` is the OPFS root. Each process mounts the top-level directories that exist when it starts (plus `/usr` and `/bin`), so files in them are shared by all processes and visible through the OPFS API as soon as the process that wrote them has closed them; `run` resolves only after that. `/tmp`, `/dev`, `/proc` and anything created directly in `/` while a process runs live in that process's memory unless the directory already exists in OPFS. File contents are buffered per open file and written back on close, `fsync` and exit; metadata operations (`mkdir`, `rename`, `rm`, …) go straight to OPFS. The kernel worker is the only writer.
+`/` is the OPFS root. Each process mounts the top-level directories that exist when it starts (plus `/usr` and `/bin`), so files in them are shared by all processes and visible through the OPFS API as soon as the process that wrote them has closed them; `run` resolves only after that. `createKernel` creates `/tmp` and `/home` in OPFS, so they are shared too. `/dev`, `/proc` and anything created directly in `/` while a process runs live in that process's memory unless it already exists in OPFS. File contents are buffered per open file and written back on close, `fsync` and exit; metadata operations (`mkdir`, `rename`, `rm`, …) go straight to OPFS. The kernel worker is the only writer.
 
 OPFS stores no POSIX metadata, so modes are synthesized: directories `0755`, files `0644`, and files under `node_modules/*/bin/` `0755`. `chmod` and `utime` are remembered for the lifetime of the kernel worker. Symlinks are not supported (`ENOSYS`). Directories are renamed with `FileSystemHandle.move()` where available, else by copy and delete.
 
+Reads retry briefly when a concurrent write has invalidated the OPFS file snapshot (`NotReadableError`).
+
+The filesystem is our own rather than [ZenFS](https://github.com/zen-fs/core) (which SLICC uses), because OPFS stays the single source of truth: other writers, such as the BIOS installing packages or a page writing files, need no index to stay consistent with, and nothing is preloaded into memory at mount. In exchange there are no persistent POSIX modes, times, inode numbers or symlinks.
+
 ## What is in here
 
 The kernel is ported from SLICC's `packages/webapp/src/kernel/` with the browser-specific VFS replaced by an OPFS one:
@@ -73,6 +97,10 @@ The kernel is ported from SLICC's `packages/webapp/src/kernel/` with the browser
 
 SLICC's networking (sockets, the TLS proxy) and WASI support are not included.
 
+## Installing from git
+
+`npm install github:ai-ecoverse/slicc-kernel#<sha>` works: the `prepare` script builds `dist/`.
+
 ## Development
 
 ```sh

package/dist/index.js

@@ -20,6 +20,7 @@ async function createKernel(options = {}) {
     const call2 = pending.get(data.id);
     if (!call2) return;
     if (data.fd !== void 0) return call2.output?.(data.fd, data.bytes);
+    if (data.started !== void 0) return call2.started?.(data.started);
     pending.delete(data.id);
     if (data.error !== void 0) call2.reject(new Error(data.error));
     else call2.resolve(data.result);
@@ -28,13 +29,49 @@ async function createKernel(options = {}) {
     event.preventDefault();
     fail(new Error(`slicc-kernel worker failed: ${event.message}`));
   });
-  function call(req, output) {
-    if (failure) return Promise.reject(failure);
+  function request(req, handlers = {}) {
     const id = ++nextId;
-    return new Promise((resolve, reject) => {
-      pending.set(id, { resolve, reject, ...output ? { output } : {} });
+    if (failure) return { id, done: Promise.reject(failure) };
+    const done = new Promise((resolve, reject) => {
+      pending.set(id, { resolve, reject, ...handlers });
       worker.postMessage({ ...req, id });
     });
+    return { id, done };
+  }
+  const call = (req, handlers) => request(req, handlers).done;
+  async function openTerminal(argv, opts = {}) {
+    const { onData, ...options2 } = opts;
+    let listener = onData ?? null;
+    const backlog = [];
+    const started = Promise.withResolvers();
+    const { id, done } = request(
+      { op: "open-terminal", argv, options: options2 },
+      {
+        output: (_fd, bytes) => listener ? listener(bytes) : backlog.push(bytes),
+        started: started.resolve
+      }
+    );
+    done.catch(started.reject);
+    const pid = await started.promise;
+    const send = (action) => void call({ op: "terminal", terminal: id, ...action }).catch(() => void 0);
+    return {
+      pid,
+      exited: done,
+      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: typeof data === "string" ? new TextEncoder().encode(data) : data
+      }),
+      resize: (cols, rows) => send({ action: "resize", cols, rows }),
+      signal: (name) => send({ action: "signal", signal: name }),
+      close: () => send({ action: "close" })
+    };
   }
   await call({
     op: "init",
@@ -49,7 +86,7 @@ async function createKernel(options = {}) {
       const input = typeof stdin === "string" ? new TextEncoder().encode(stdin) : stdin;
       const result = await call(
         { op: "run", argv, options: { ...rest, ...input ? { stdin: input } : {} } },
-        (fd, bytes) => streams[fd](bytes)
+        { output: (fd, bytes) => streams[fd](bytes) }
       );
       const decoder = new TextDecoder();
       return {
@@ -58,6 +95,7 @@ async function createKernel(options = {}) {
         stderr: decoder.decode(result.stderr)
       };
     },
+    openTerminal,
     terminate() {
       fail(new Error("slicc-kernel terminated"));
       worker.terminate();

package/dist/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/index.ts"],
-  "sourcesContent": ["import type { KernelCall } from './serve.ts';\n\nexport interface KernelOptions {\n  root?: FileSystemDirectoryHandle;\n  modules?: string;\n  env?: Record<string, string>;\n  worker?: string | URL;\n}\n\nexport interface RunOptions {\n  cwd?: string;\n  env?: Record<string, string>;\n  stdin?: string | Uint8Array;\n  onStdout?: (text: string) => void;\n  onStderr?: (text: string) => void;\n}\n\nexport interface RunResult {\n  status: number;\n  stdout: string;\n  stderr: string;\n}\n\nexport interface Kernel {\n  run(argv: string[], options?: RunOptions): Promise<RunResult>;\n  terminate(): void;\n}\n\ninterface Reply {\n  id: number;\n  result?: unknown;\n  error?: string;\n  fd?: 1 | 2;\n  bytes?: Uint8Array;\n}\n\ninterface Pending {\n  resolve: (value: unknown) => void;\n  reject: (error: Error) => void;\n  output?: (fd: 1 | 2, bytes: Uint8Array) => void;\n}\n\nconst ISOLATION =\n  'slicc-kernel needs a cross-origin isolated page (Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp or credentialless)';\n\nfunction streamer(callback: ((text: string) => void) | undefined) {\n  const decoder = new TextDecoder();\n  return (bytes: Uint8Array) => callback?.(decoder.decode(bytes, { stream: true }));\n}\n\nexport async function createKernel(options: KernelOptions = {}): Promise<Kernel> {\n  if (!globalThis.crossOriginIsolated) throw new Error(ISOLATION);\n  const url = options.worker ?? new URL('./kernel-worker.js', import.meta.url);\n  const worker = new Worker(url, { type: 'module', name: 'slicc-kernel' });\n  const pending = new Map<number, Pending>();\n  let nextId = 0;\n  let failure: Error | undefined;\n\n  const fail = (error: Error) => {\n    failure = error;\n    for (const call of pending.values()) call.reject(error);\n    pending.clear();\n  };\n  worker.addEventListener('message', ({ data }: MessageEvent<Reply>) => {\n    const call = pending.get(data.id);\n    if (!call) return;\n    if (data.fd !== undefined) return call.output?.(data.fd, data.bytes as Uint8Array);\n    pending.delete(data.id);\n    if (data.error !== undefined) call.reject(new Error(data.error));\n    else call.resolve(data.result);\n  });\n  worker.addEventListener('error', (event) => {\n    event.preventDefault();\n    fail(new Error(`slicc-kernel worker failed: ${event.message}`));\n  });\n\n  function call(req: KernelCall, output?: Pending['output']): Promise<unknown> {\n    if (failure) return Promise.reject(failure);\n    const id = ++nextId;\n    return new Promise((resolve, reject) => {\n      pending.set(id, { resolve, reject, ...(output ? { output } : {}) });\n      worker.postMessage({ ...req, id });\n    });\n  }\n\n  await call({\n    op: 'init',\n    ...(options.root ? { root: options.root } : {}),\n    ...(options.modules ? { modules: options.modules } : {}),\n    ...(options.env ? { env: options.env } : {}),\n  });\n\n  return {\n    async run(argv, runOptions = {}) {\n      const { onStdout, onStderr, stdin, ...rest } = runOptions;\n      const streams = { 1: streamer(onStdout), 2: streamer(onStderr) };\n      const input = typeof stdin === 'string' ? new TextEncoder().encode(stdin) : stdin;\n      const result = (await call(\n        { op: 'run', argv, options: { ...rest, ...(input ? { stdin: input } : {}) } },\n        (fd, bytes) => streams[fd](bytes)\n      )) as { status: number; stdout: Uint8Array; stderr: Uint8Array };\n      const decoder = new TextDecoder();\n      return {\n        status: result.status,\n        stdout: decoder.decode(result.stdout),\n        stderr: decoder.decode(result.stderr),\n      };\n    },\n    terminate() {\n      fail(new Error('slicc-kernel terminated'));\n      worker.terminate();\n    },\n  };\n}\n"],
-  "mappings": "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",
-  "names": ["call"]
+  "sourcesContent": ["import type { KernelCall, TerminalAction } from './serve.ts';\n\nexport interface KernelOptions {\n  root?: FileSystemDirectoryHandle;\n  modules?: string;\n  env?: Record<string, string>;\n  worker?: string | URL;\n}\n\nexport interface RunOptions {\n  cwd?: string;\n  env?: Record<string, string>;\n  stdin?: string | Uint8Array;\n  onStdout?: (text: string) => void;\n  onStderr?: (text: string) => void;\n}\n\nexport interface RunResult {\n  status: number;\n  stdout: string;\n  stderr: string;\n}\n\nexport interface Kernel {\n  run(argv: string[], options?: RunOptions): Promise<RunResult>;\n  openTerminal(argv: string[], options?: TerminalOptions): Promise<Terminal>;\n  terminate(): void;\n}\n\nexport interface TerminalOptions {\n  cwd?: string;\n  env?: Record<string, string>;\n  cols?: number;\n  rows?: number;\n  onData?: (bytes: Uint8Array) => void;\n}\n\nexport type TerminalSignal =\n  | 'SIGINT'\n  | 'SIGTSTP'\n  | 'SIGQUIT'\n  | 'SIGHUP'\n  | 'SIGTERM'\n  | 'SIGKILL'\n  | 'SIGCONT';\n\nexport interface Terminal {\n  readonly pid: number;\n  readonly exited: Promise<number>;\n  onData: ((bytes: Uint8Array) => void) | null;\n  write(data: string | Uint8Array): void;\n  resize(cols: number, rows: number): void;\n  signal(name: TerminalSignal): void;\n  close(): void;\n}\n\ninterface Reply {\n  id: number;\n  result?: unknown;\n  error?: string;\n  fd?: 1 | 2;\n  bytes?: Uint8Array;\n  started?: number;\n}\n\ninterface Pending {\n  resolve: (value: unknown) => void;\n  reject: (error: Error) => void;\n  output?: (fd: 1 | 2, bytes: Uint8Array) => void;\n  started?: (pid: number) => void;\n}\n\ninterface Handlers {\n  output?: Pending['output'];\n  started?: Pending['started'];\n}\n\nconst ISOLATION =\n  'slicc-kernel needs a cross-origin isolated page (Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp or credentialless)';\n\nfunction streamer(callback: ((text: string) => void) | undefined) {\n  const decoder = new TextDecoder();\n  return (bytes: Uint8Array) => callback?.(decoder.decode(bytes, { stream: true }));\n}\n\nexport async function createKernel(options: KernelOptions = {}): Promise<Kernel> {\n  if (!globalThis.crossOriginIsolated) throw new Error(ISOLATION);\n  const url = options.worker ?? new URL('./kernel-worker.js', import.meta.url);\n  const worker = new Worker(url, { type: 'module', name: 'slicc-kernel' });\n  const pending = new Map<number, Pending>();\n  let nextId = 0;\n  let failure: Error | undefined;\n\n  const fail = (error: Error) => {\n    failure = error;\n    for (const call of pending.values()) call.reject(error);\n    pending.clear();\n  };\n  worker.addEventListener('message', ({ data }: MessageEvent<Reply>) => {\n    const call = pending.get(data.id);\n    if (!call) return;\n    if (data.fd !== undefined) return call.output?.(data.fd, data.bytes as Uint8Array);\n    if (data.started !== undefined) return call.started?.(data.started);\n    pending.delete(data.id);\n    if (data.error !== undefined) call.reject(new Error(data.error));\n    else call.resolve(data.result);\n  });\n  worker.addEventListener('error', (event) => {\n    event.preventDefault();\n    fail(new Error(`slicc-kernel worker failed: ${event.message}`));\n  });\n\n  function request(\n    req: KernelCall,\n    handlers: Handlers = {}\n  ): { id: number; done: Promise<unknown> } {\n    const id = ++nextId;\n    if (failure) return { id, done: Promise.reject(failure) };\n    const done = new Promise((resolve, reject) => {\n      pending.set(id, { resolve, reject, ...handlers });\n      worker.postMessage({ ...req, id });\n    });\n    return { id, done };\n  }\n\n  const call = (req: KernelCall, handlers?: Handlers) => request(req, handlers).done;\n\n  async function openTerminal(argv: string[], opts: TerminalOptions = {}): Promise<Terminal> {\n    const { onData, ...options } = opts;\n    let listener = onData ?? null;\n    const backlog: Uint8Array[] = [];\n    const started = Promise.withResolvers<number>();\n    const { id, done } = request(\n      { op: 'open-terminal', argv, options },\n      {\n        output: (_fd, bytes) => (listener ? listener(bytes) : backlog.push(bytes)),\n        started: started.resolve,\n      }\n    );\n    done.catch(started.reject);\n    const pid = await started.promise;\n    const send = (action: TerminalAction) =>\n      void call({ op: 'terminal', terminal: id, ...action }).catch(() => undefined);\n    return {\n      pid,\n      exited: done as Promise<number>,\n      get onData() {\n        return listener;\n      },\n      set onData(next) {\n        listener = next;\n        if (next) for (const bytes of backlog.splice(0)) next(bytes);\n      },\n      write: (data) =>\n        send({\n          action: 'write',\n          bytes: typeof data === 'string' ? new TextEncoder().encode(data) : data,\n        }),\n      resize: (cols, rows) => send({ action: 'resize', cols, rows }),\n      signal: (name) => send({ action: 'signal', signal: name }),\n      close: () => send({ action: 'close' }),\n    };\n  }\n\n  await call({\n    op: 'init',\n    ...(options.root ? { root: options.root } : {}),\n    ...(options.modules ? { modules: options.modules } : {}),\n    ...(options.env ? { env: options.env } : {}),\n  });\n\n  return {\n    async run(argv, runOptions = {}) {\n      const { onStdout, onStderr, stdin, ...rest } = runOptions;\n      const streams = { 1: streamer(onStdout), 2: streamer(onStderr) };\n      const input = typeof stdin === 'string' ? new TextEncoder().encode(stdin) : stdin;\n      const result = (await call(\n        { op: 'run', argv, options: { ...rest, ...(input ? { stdin: input } : {}) } },\n        { output: (fd, bytes) => streams[fd](bytes) }\n      )) as { status: number; stdout: Uint8Array; stderr: Uint8Array };\n      const decoder = new TextDecoder();\n      return {\n        status: result.status,\n        stdout: decoder.decode(result.stdout),\n        stderr: decoder.decode(result.stderr),\n      };\n    },\n    openTerminal,\n    terminate() {\n      fail(new Error('slicc-kernel terminated'));\n      worker.terminate();\n    },\n  };\n}\n"],
+  "mappings": "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",
+  "names": ["call", "options"]
 }

package/dist/kernel-worker.js

@@ -19,6 +19,7 @@ function resolvePath(base, path) {
 var S_IFDIR = 16384;
 var S_IFREG = 32768;
 var PERM_MASK = 4095;
+var READ_ATTEMPTS = 3;
 var EXECUTABLE = /\/node_modules\/(?:@[^/]+\/)?[^/]+\/bin\//;
 var ERRNO_BY_DOM_ERROR = {
   NotFoundError: "ENOENT",
@@ -102,7 +103,16 @@ var OpfsFs = class {
   async readFileBuffer(path) {
     const handle = await this.handle(path);
     if (handle.kind === "directory") throw fsError("EISDIR", path);
-    return new Uint8Array(await (await handle.getFile()).arrayBuffer());
+    for (let attempt = 1; ; attempt++) {
+      try {
+        return new Uint8Array(await (await handle.getFile()).arrayBuffer());
+      } catch (err) {
+        if (err?.name !== "NotReadableError" || attempt >= READ_ATTEMPTS) {
+          throw translate(err, path);
+        }
+        await new Promise((resolve) => setTimeout(resolve, attempt * 10));
+      }
+    }
   }
   async readFile(path) {
     return new TextDecoder().decode(await this.readFileBuffer(path));
@@ -225,6 +235,61 @@ var OpfsFs = 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_]*$/;
@@ -1163,61 +1228,6 @@ function attachSyncSabResponder(port, sab, token, opts) {
   };
 }
 
-// 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;
@@ -2719,6 +2729,7 @@ var JobTable = class {
 var COMMAND2 = /^\/(?:usr\/)?bin\/([^/]+)$/;
 var SHEBANG_MAX = 256;
 var NOT_FOUND = 127;
+var SHARED_DIRS = ["/tmp", "/home"];
 var encoder3 = new TextEncoder();
 function baseName(path) {
   return path.slice(path.lastIndexOf("/") + 1);
@@ -2766,6 +2777,7 @@ var Launcher = class {
   jobs = new JobTable();
   ptys = new PtyTable((tty, sig) => this.jobs.signalOwnedForeground(tty, sig));
   nextPid = 1e3;
+  terminals = 0;
   constructor(options) {
     this.base = options.fs;
     this.createWorker = options.createWorker;
@@ -2815,6 +2827,10 @@ var Launcher = class {
     if (direct) return { target: direct, args: [...direct.prefix ?? [], ...argv.slice(1)] };
     return this.interpreted(file, argv, cwd);
   }
+  async unrunnable(file, cwd) {
+    const head = await this.base.readFileBuffer(this.fs.resolvePath(cwd, file)).catch(() => null);
+    return head && !(head[0] === 35 && head[1] === 33) ? "ENOEXEC" : "ENOENT";
+  }
   module(path) {
     return this.base.stat(path).then((st) => {
       const key = `${path}:${st.size}:${st.mtime.getTime()}`;
@@ -2889,7 +2905,7 @@ var Launcher = class {
       const planned = await this.plan(req.file, req.argv, req.cwd);
       if (!planned) {
         await fds.closeAll();
-        throw new SpawnError("ENOENT");
+        throw new SpawnError(await this.unrunnable(req.file, req.cwd));
       }
       const handle = await this.launch(planned, { env: req.env, cwd: req.cwd, fds, report, ppid });
       return childHandle(handle);
@@ -2905,10 +2921,59 @@ var Launcher = class {
     if (sig !== 0) handle.signal(sig);
     return true;
   }
-  async run(argv, options = {}) {
+  async prepare() {
+    for (const dir of SHARED_DIRS) await this.base.mkdir(dir, { recursive: true });
+  }
+  environment(cwd, extra) {
+    return { PATH: "/usr/bin:/bin", HOME: "/home", ...this.env, PWD: cwd, ...extra };
+  }
+  async starting(argv, dir) {
     this.catalog = void 0;
-    const cwd = this.fs.resolvePath("/", options.cwd ?? "/");
-    const env = { PATH: "/usr/bin:/bin", HOME: "/", ...this.env, PWD: cwd, ...options.env };
+    const cwd = this.fs.resolvePath("/", dir ?? "/");
+    const [file = ""] = argv;
+    await this.base.mkdir(cwd, { recursive: true });
+    return { cwd, file, planned: await this.plan(file, argv, cwd) };
+  }
+  async openTerminal(argv, options) {
+    const { cwd, file, planned } = await this.starting(argv, options.cwd);
+    if (!planned) throw new Error(`${file}: command not found`);
+    let leader = 0;
+    const tty = new KernelTty(
+      { write: (bytes) => options.onData(bytes.slice()) },
+      (sig) => this.jobs.signalForeground(tty, leader, sig)
+    );
+    tty.name = `/dev/tty${++this.terminals}`;
+    tty.setSize(options.cols ?? 80, options.rows ?? 24);
+    const fds = new FdTable();
+    const stdio = tty.file();
+    fds.installAt(0, stdio);
+    fds.installAt(1, stdio.retain());
+    fds.installAt(2, stdio.retain());
+    const env = this.environment(cwd, {
+      TERM: "xterm-256color",
+      COLORTERM: "truecolor",
+      ...options.env
+    });
+    const report = (message) => options.onData(encoder3.encode(`${message}\r
+`));
+    const handle = await this.launch(planned, { env, cwd, fds, report });
+    leader = handle.pid;
+    void handle.exited.then(() => tty.hangup());
+    return {
+      pid: handle.pid,
+      exited: handle.exited,
+      write: (bytes) => tty.receive(bytes),
+      resize: (cols, rows) => tty.resize(cols, rows),
+      signal: (sig) => this.jobs.signalForeground(tty, leader, sig),
+      close: () => {
+        tty.signalHangup();
+        tty.hangup();
+      }
+    };
+  }
+  async run(argv, options = {}) {
+    const { cwd, file, planned } = await this.starting(argv, options.cwd);
+    const env = this.environment(cwd, options.env);
     const out = [];
     const err = [];
     const collect = (chunks, tee) => (bytes) => {
@@ -2919,9 +2984,6 @@ var Launcher = class {
     const stderr = collect(err, options.onStderr);
     const report = (message) => stderr(encoder3.encode(`${message}
 `));
-    const [file = ""] = argv;
-    await this.base.mkdir(cwd, { recursive: true });
-    const planned = await this.plan(file, argv, cwd);
     if (!planned) {
       report(`${file}: command not found`);
       return { status: NOT_FOUND, stdout: concat2(out), stderr: concat2(err) };
@@ -2937,24 +2999,60 @@ var Launcher = class {
 };
 
 // src/serve.ts
+function signalNumber(name) {
+  const key = name.slice(3);
+  if (!name.startsWith("SIG") || !Object.hasOwn(SIG, key))
+    throw new Error(`unknown signal ${name}`);
+  return SIG[key];
+}
+function act(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));
+  else session.close();
+}
 function serveKernel(port, deps) {
   let launcher;
+  const terminals = /* @__PURE__ */ new Map();
   const reply = (id, body) => port.postMessage({ id, ...body });
+  async function ready2() {
+    if (!launcher) throw new Error("the kernel is not initialized");
+    return launcher;
+  }
+  async function terminal(req) {
+    const onData = (bytes) => reply(req.id, { fd: 1, bytes });
+    const session = await (await ready2()).openTerminal(req.argv, { ...req.options, onData });
+    terminals.set(req.id, session);
+    reply(req.id, { started: session.pid });
+    try {
+      return await session.exited;
+    } finally {
+      terminals.delete(req.id);
+    }
+  }
   async function handle(req) {
     if (req.op === "init") {
-      launcher = (req.root ? Promise.resolve(req.root) : deps.storage()).then(
-        (root) => new Launcher({
+      launcher = (req.root ? Promise.resolve(req.root) : deps.storage()).then(async (root) => {
+        const started = new Launcher({
           fs: new OpfsFs(root),
           createWorker: deps.createWorker,
           ...req.modules ? { modules: req.modules } : {},
           ...req.env ? { env: req.env } : {}
-        })
-      );
+        });
+        await started.prepare();
+        return started;
+      });
       await launcher;
       return true;
     }
-    if (!launcher) throw new Error("the kernel is not initialized");
-    return (await launcher).run(req.argv, {
+    if (req.op === "open-terminal") return terminal(req);
+    if (req.op === "terminal") {
+      const session = terminals.get(req.terminal);
+      if (!session) throw new Error(`no terminal ${req.terminal}`);
+      act(session, req);
+      return true;
+    }
+    return (await ready2()).run(req.argv, {
       ...req.options,
       onStdout: (bytes) => reply(req.id, { fd: 1, bytes }),
       onStderr: (bytes) => reply(req.id, { fd: 2, bytes })