feat: US-083 - Add WasmVM terminal tests: echo, ls, output preservation

Add terminal-level tests for real brush-shell commands through the full
WasmVM stack using @xterm/headless for screen-state verification.

Key changes:
- Add ONLCR output processing to PTY slave write path (POSIX standard)
- Fix WasmVM driver to route stdout/stderr through kernel fdWrite for PTY
  (was only routing pipes, not character devices)
- Pass ttyFds to worker so brush-shell detects interactive mode
- Implement getIno/getInodeByIno in kernel VFS adapter for WASI path ops
- Add @xterm/headless devDep and TerminalHarness to wasmvm test dir

Tests: echo, output preservation, export pass with exact screen matching.
cd and ls are .todo (pre-existing WASI path resolution / proc_spawn issues).

Author: NathanFlurry

packages/kernel/src/pty.ts

@@ -138,18 +138,20 @@ export class PtyManager {
 			return this.processInput(state, data);
 		} else {
 			// Slave write → output buffer (master reads)
+			// ONLCR: convert \n to \r\n (standard POSIX terminal output processing)
 			if (state.closed.slave) throw new KernelError("EIO", "slave closed");
 			if (state.closed.master) throw new KernelError("EIO", "master closed");
 
+			const processed = this.processOutput(data);
 			if (state.outputWaiters.length > 0) {
 				const waiter = state.outputWaiters.shift()!;
-				waiter(data);
+				waiter(processed);
 			} else {
 				// Enforce buffer limit to prevent unbounded memory growth
-				if (this.bufferBytes(state.outputBuffer) + data.length > MAX_PTY_BUFFER_BYTES) {
+				if (this.bufferBytes(state.outputBuffer) + processed.length > MAX_PTY_BUFFER_BYTES) {
 					throw new KernelError("EAGAIN", "PTY output buffer full");
 				}
-				state.outputBuffer.push(new Uint8Array(data));
+				state.outputBuffer.push(new Uint8Array(processed));
 			}
 		}
 
@@ -316,6 +318,35 @@ export class PtyManager {
 		return ref.ptyId;
 	}
 
+	// -------------------------------------------------------------------
+	// Output processing (ONLCR)
+	// -------------------------------------------------------------------
+
+	/** Convert lone \n to \r\n in output data (POSIX ONLCR). */
+	private processOutput(data: Uint8Array): Uint8Array {
+		// Fast path: no newlines → return as-is
+		if (!data.includes(0x0a)) return data;
+
+		// Count lone LFs (not preceded by CR) to size the result buffer
+		let extraCRs = 0;
+		for (let i = 0; i < data.length; i++) {
+			if (data[i] === 0x0a && (i === 0 || data[i - 1] !== 0x0d)) {
+				extraCRs++;
+			}
+		}
+		if (extraCRs === 0) return data;
+
+		const result = new Uint8Array(data.length + extraCRs);
+		let j = 0;
+		for (let i = 0; i < data.length; i++) {
+			if (data[i] === 0x0a && (i === 0 || data[i - 1] !== 0x0d)) {
+				result[j++] = 0x0d; // CR
+			}
+			result[j++] = data[i];
+		}
+		return result;
+	}
+
 	// -------------------------------------------------------------------
 	// Line discipline input processing
 	// -------------------------------------------------------------------

packages/kernel/test/kernel-integration.test.ts

@@ -1960,7 +1960,7 @@ describe("kernel + MockRuntimeDriver integration", () => {
 			proc.kill();
 		});
 
-		it("write to slave → read from master", async () => {
+		it("write to slave → read from master (ONLCR converts \\n to \\r\\n)", async () => {
 			const driver = new MockRuntimeDriver(["proc"], {
 				proc: { neverExit: true },
 			});
@@ -1973,8 +1973,9 @@ describe("kernel + MockRuntimeDriver integration", () => {
 			const msg = new TextEncoder().encode("hello\n");
 			ki.fdWrite(proc.pid, slaveFd, msg);
 
+			// Slave output goes through ONLCR: \n → \r\n (POSIX default)
 			const data = await ki.fdRead(proc.pid, masterFd, 1024);
-			expect(new TextDecoder().decode(data)).toBe("hello\n");
+			expect(new TextDecoder().decode(data)).toBe("hello\r\n");
 
 			proc.kill();
 		});

packages/runtime/wasmvm/package.json

@@ -18,6 +18,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.10.2",
+    "@xterm/headless": "^6.0.0",
     "typescript": "^5.7.2",
     "vitest": "^2.1.8"
   }

packages/runtime/wasmvm/src/driver.ts

@@ -129,21 +129,28 @@ class WasmVmRuntimeDriver implements RuntimeDriver {
       };
     });
 
-    // Set up stdin pipe so writeStdin/closeStdin deliver data through kernel FD 0
-    const stdinPipe = kernel.pipe(ctx.pid);
-    kernel.fdDup2(ctx.pid, stdinPipe.readFd, 0);
-    kernel.fdClose(ctx.pid, stdinPipe.readFd);
-    const stdinWriteFd = stdinPipe.writeFd;
+    // Set up stdin pipe for writeStdin/closeStdin — skip if FD 0 is already
+    // a PTY slave (interactive shell: stdin flows through kernel PTY)
+    const stdinIsPty = kernel.isatty(ctx.pid, 0);
+    let stdinWriteFd: number | undefined;
+    if (!stdinIsPty) {
+      const stdinPipe = kernel.pipe(ctx.pid);
+      kernel.fdDup2(ctx.pid, stdinPipe.readFd, 0);
+      kernel.fdClose(ctx.pid, stdinPipe.readFd);
+      stdinWriteFd = stdinPipe.writeFd;
+    }
 
     const proc: DriverProcess = {
       onStdout: null,
       onStderr: null,
       onExit: null,
       writeStdin: (data: Uint8Array) => {
-        kernel.fdWrite(ctx.pid, stdinWriteFd, data);
+        if (stdinWriteFd !== undefined) kernel.fdWrite(ctx.pid, stdinWriteFd, data);
       },
       closeStdin: () => {
-        try { kernel.fdClose(ctx.pid, stdinWriteFd); } catch { /* already closed */ }
+        if (stdinWriteFd !== undefined) {
+          try { kernel.fdClose(ctx.pid, stdinWriteFd); } catch { /* already closed */ }
+        }
       },
       kill: (_signal: number) => {
         const worker = this._activeWorkers.get(ctx.pid);
@@ -169,12 +176,13 @@ class WasmVmRuntimeDriver implements RuntimeDriver {
     this._kernel = null;
   }
 
-  /** Check if a process's FD is a pipe via kernel FD stat. */
-  private _isFdPiped(pid: number, fd: number): boolean {
+  /** Check if a process's FD is routed through kernel (pipe or PTY). */
+  private _isFdKernelRouted(pid: number, fd: number): boolean {
     if (!this._kernel) return false;
     try {
       const stat = this._kernel.fdStat(pid, fd);
-      return stat.filetype === 6; // FILETYPE_PIPE
+      if (stat.filetype === 6) return true; // FILETYPE_PIPE
+      return this._kernel.isatty(pid, fd); // PTY slave
     } catch {
       return false;
     }
@@ -197,10 +205,16 @@ class WasmVmRuntimeDriver implements RuntimeDriver {
     const signalBuf = new SharedArrayBuffer(SIGNAL_BUFFER_BYTES);
     const dataBuf = new SharedArrayBuffer(DATA_BUFFER_BYTES);
 
-    // Check if stdio FDs are piped by inspecting the kernel FD table
-    const stdinPiped = this._isFdPiped(ctx.pid, 0);
-    const stdoutPiped = this._isFdPiped(ctx.pid, 1);
-    const stderrPiped = this._isFdPiped(ctx.pid, 2);
+    // Check if stdio FDs are kernel-routed (pipe or PTY)
+    const stdinPiped = this._isFdKernelRouted(ctx.pid, 0);
+    const stdoutPiped = this._isFdKernelRouted(ctx.pid, 1);
+    const stderrPiped = this._isFdKernelRouted(ctx.pid, 2);
+
+    // Detect which FDs are TTYs (PTY slaves) for brush-shell interactive mode
+    const ttyFds: number[] = [];
+    for (const fd of [0, 1, 2]) {
+      if (kernel.isatty(ctx.pid, fd)) ttyFds.push(fd);
+    }
 
     const workerData: WorkerInitData = {
       wasmBinaryPath: this._wasmBinaryPath,
@@ -212,10 +226,11 @@ class WasmVmRuntimeDriver implements RuntimeDriver {
       cwd: ctx.cwd,
       signalBuf,
       dataBuf,
-      // Tell worker which stdio channels are piped so it routes writes correctly
+      // Tell worker which stdio channels are kernel-routed
       stdinFd: stdinPiped ? 99 : undefined,
       stdoutFd: stdoutPiped ? 99 : undefined,
       stderrFd: stderrPiped ? 99 : undefined,
+      ttyFds: ttyFds.length > 0 ? ttyFds : undefined,
     };
 
     const workerUrl = new URL('./kernel-worker.ts', import.meta.url);

packages/runtime/wasmvm/src/kernel-worker.ts

@@ -175,6 +175,45 @@ function createKernelProcessIO(): WasiProcessIO {
 function createKernelVfs(): WasiVFS {
   const decoder = new TextDecoder();
 
+  // Inode cache for getIno/getInodeByIno — synthesizes inodes from kernel VFS stat
+  let nextIno = 1;
+  const pathToIno = new Map<string, number>();
+  const inoCache = new Map<number, WasiInode>();
+
+  function resolveIno(path: string): number | null {
+    const cached = pathToIno.get(path);
+    if (cached !== undefined) return cached;
+
+    const res = rpcCall('vfsStat', { path });
+    if (res.errno !== 0) return null;
+
+    // RPC response fields: { type, mode, uid, gid, nlink, size, atime, mtime, ctime }
+    const raw = JSON.parse(decoder.decode(res.data)) as Record<string, unknown>;
+    const ino = nextIno++;
+    pathToIno.set(path, ino);
+
+    const nodeType = raw.type as string ?? 'file';
+    const isDir = nodeType === 'dir';
+    const node: WasiInode = {
+      type: nodeType,
+      mode: (raw.mode as number) ?? (isDir ? 0o40755 : 0o100644),
+      uid: (raw.uid as number) ?? 0,
+      gid: (raw.gid as number) ?? 0,
+      nlink: (raw.nlink as number) ?? 1,
+      size: (raw.size as number) ?? 0,
+      atime: (raw.atime as number) ?? Date.now(),
+      mtime: (raw.mtime as number) ?? Date.now(),
+      ctime: (raw.ctime as number) ?? Date.now(),
+    };
+
+    if (isDir) {
+      node.entries = new Map();
+    }
+
+    inoCache.set(ino, node);
+    return ino;
+  }
+
   return {
     exists(path: string): boolean {
       const res = rpcCall('vfsExists', { path });
@@ -241,11 +280,11 @@ function createKernelVfs(): WasiVFS {
     chmod(_path: string, _mode: number): void {
       // No-op — permissions handled by kernel
     },
-    getIno(_path: string): number | null {
-      return null;
+    getIno(path: string): number | null {
+      return resolveIno(path);
     },
-    getInodeByIno(_ino: number): WasiInode | null {
-      return null;
+    getInodeByIno(ino: number): WasiInode | null {
+      return inoCache.get(ino) ?? null;
     },
     snapshot(): VfsSnapshotEntry[] {
       return [];
@@ -357,6 +396,34 @@ function createHostProcessImports(getMemory: () => WebAssembly.Memory | null) {
       view.setUint32(ret_write_fd_ptr, writeFd, true);
       return ERRNO_SUCCESS;
     },
+
+    /** fd_dup(fd, ret_new_fd) -> errno */
+    fd_dup(fd: number, ret_new_fd_ptr: number): number {
+      const mem = getMemory();
+      if (!mem) return ERRNO_EINVAL;
+
+      const res = rpcCall('fdDup', { fd });
+      if (res.errno !== 0) return res.errno;
+
+      new DataView(mem.buffer).setUint32(ret_new_fd_ptr, res.intResult, true);
+      return ERRNO_SUCCESS;
+    },
+
+    /** proc_getpid(ret_pid) -> errno */
+    proc_getpid(ret_pid_ptr: number): number {
+      const mem = getMemory();
+      if (!mem) return ERRNO_EINVAL;
+
+      new DataView(mem.buffer).setUint32(ret_pid_ptr, init.pid, true);
+      return ERRNO_SUCCESS;
+    },
+
+    /** sleep_ms(milliseconds) -> errno — blocks via Atomics.wait */
+    sleep_ms(milliseconds: number): number {
+      const buf = new Int32Array(new SharedArrayBuffer(4));
+      Atomics.wait(buf, 0, 0, milliseconds);
+      return ERRNO_SUCCESS;
+    },
   };
 }
 
@@ -422,7 +489,7 @@ async function main(): Promise<void> {
   const userManager = new UserManager({
     getMemory,
     fdTable,
-    ttyFds: false,
+    ttyFds: init.ttyFds ? new Set(init.ttyFds) : false,
   });
 
   const hostProcess = createHostProcessImports(getMemory);

packages/runtime/wasmvm/src/syscall-rpc.ts

@@ -90,4 +90,6 @@ export interface WorkerInitData {
   stdoutFd?: number;
   /** FD override for stderr (pipe write end in parent's table, or undefined). */
   stderrFd?: number;
+  /** Which stdio FDs are TTYs (for brush-shell interactive mode detection). */
+  ttyFds?: number[];
 }