novac 2.0.1 → 2.2.0

package/kits/libtea/kitdef.js

@@ -0,0 +1,2691 @@
+/**
+ * tea's F — Virtual Filesystem  (v2.0.0)
+ *
+ * Features:
+ *   - POSIX-style path mode (default)
+ *   - Windows-style path mode:  mode: 'win'  → C:\Users\...
+ *   - URL-style path mode:      mode: 'url'  → http://host/path/...
+ *   - Snapshots saved to ./snaps/ (not /tmp)
+ *   - Mount appends into /mnt/ and fixes duplicate-segment collisions
+ *   - Real watcher events: 'change', 'rename', 'unlink', 'mkdir', 'write'
+ *   - Permission enforcement (uid/gid/mode checks)
+ *   - exec: shell interpreter (sh-compatible lexer + parser + evaluator)
+ *     - ENV variables, PATH lookup, pipelines, redirections, &&/||/;
+ *     - Built-ins: cd, echo, export, unset, env, pwd, alias, type, which, exit
+ *     - Executable files in bin/, she-bang (#!) support
+ *   - REPL: tf.repl() → interactive shell session object
+ *   - TeaBin: custom binary executable format
+ *     - Registers: R0–R15, SP, PC, FLAGS
+ *     - Opcodes: MOV, ADD, SUB, MUL, DIV, MOD, AND, OR, XOR, NOT, SHL, SHR,
+ *                CMP, JMP, JE, JNE, JL, JG, JLE, JGE, CALL, RET, PUSH, POP,
+ *                LOAD, STORE, ALLOC, FREE, IN, OUT, HALT, NOP, INT
+ *     - Heap memory (Uint8Array), stack, syscall interrupts
+ *
+ * Architecture:
+ *   The entire FS is one JS object:
+ *   {
+ *     meta: { created, label, version },
+ *     tree: { "/": { type:"dir", mode:0o755, uid:0, gid:0, atime, mtime, ctime, children:{} }, ... },
+ *     inodeCounter: 3
+ *   }
+ *
+ * Path resolution always starts from "/" (or drive root in win mode).
+ * Hard links, symlinks, permissions, mounts all supported.
+ */
+
+"use strict";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const S_IFREG = 0o100000;
+const S_IFDIR = 0o040000;
+const S_IFLNK = 0o120000;
+
+const S_IRUSR = 0o400; const S_IWUSR = 0o200; const S_IXUSR = 0o100;
+const S_IRGRP = 0o040; const S_IWGRP = 0o020; const S_IXGRP = 0o010;
+const S_IROTH = 0o004; const S_IWOTH = 0o002; const S_IXOTH = 0o001;
+
+const O_RDONLY = 0;
+const O_WRONLY = 1;
+const O_RDWR   = 2;
+const O_CREAT  = 64;
+const O_EXCL   = 128;
+const O_TRUNC  = 512;
+const O_APPEND = 1024;
+
+const COPYFILE_EXCL = 1;
+const VERSION = "2.0.0";
+const SNAP_DIR = "./snaps";
+
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+
+class TFError extends Error {
+  constructor(code, message, path) {
+    super(message + (path ? ` '${path}'` : ""));
+    this.code = code; this.path = path; this.name = "TFError";
+  }
+}
+
+function err(code, path) {
+  const messages = {
+    ENOENT: "no such file or directory", EEXIST: "file already exists",
+    ENOTDIR: "not a directory", EISDIR: "is a directory",
+    ENOTEMPTY: "directory not empty", EACCES: "permission denied",
+    EBADF: "bad file descriptor", EINVAL: "invalid argument",
+    ELOOP: "too many levels of symbolic links", EPERM: "operation not permitted",
+    ENOTSUP: "operation not supported", ENOTEXEC: "exec format error",
+    ENOMEM: "out of memory", EFAULT: "bad address",
+  };
+  return new TFError(code, messages[code] || code, path);
+}
+
+// ---------------------------------------------------------------------------
+// Path mode adapters
+// ---------------------------------------------------------------------------
+
+/**
+ * PathAdapter: normalises between posix / win / url path representations.
+ * Internally we always use posix "/"-separated paths.
+ * The adapter converts user-supplied paths → internal, and internal → display.
+ */
+class PathAdapter {
+  constructor(mode = "posix") {
+    this.mode = mode;
+  }
+
+  // Convert external path (user-supplied) to internal posix path
+  toInternal(p) {
+    if (typeof p !== "string") throw err("EINVAL");
+    switch (this.mode) {
+      case "win": return this._winToInternal(p);
+      case "url": return this._urlToInternal(p);
+      default:    return p; // posix: pass through
+    }
+  }
+
+  // Convert internal posix path to external display form
+  toExternal(p) {
+    switch (this.mode) {
+      case "win": return this._internalToWin(p);
+      case "url": return this._internalToUrl(p);
+      default:    return p;
+    }
+  }
+
+  _winToInternal(p) {
+    // "C:\Users\foo\bar"  →  "/C/Users/foo/bar"
+    // "C:/"               →  "/C"
+    // "\foo\bar"          →  "/foo/bar"
+    // "foo\bar"           →  "/foo/bar"
+    let s = p.replace(/\\/g, "/");
+    const driveMatch = s.match(/^([A-Za-z]):(\/.*)?$/);
+    if (driveMatch) {
+      const drive = driveMatch[1].toUpperCase();
+      const rest  = driveMatch[2] || "/";
+      s = "/" + drive + rest;
+    } else if (!s.startsWith("/")) {
+      s = "/" + s;
+    }
+    return s;
+  }
+
+  _internalToWin(p) {
+    // "/C/Users/foo" → "C:\Users\foo"
+    const m = p.match(/^\/([A-Z])(\/.*)?$/);
+    if (m) {
+      return m[1] + ":" + (m[2] || "\\").replace(/\//g, "\\");
+    }
+    return p.replace(/\//g, "\\");
+  }
+
+  _urlToInternal(p) {
+    // "http://hostname/path/to/file"  →  "/http/hostname/path/to/file"
+    // "https://example.com/a/b"       →  "/https/example.com/a/b"
+    // "/path"                         →  "/path"
+    const m = p.match(/^([a-zA-Z][a-zA-Z0-9+\-.]*):\/\/([^/]*)(\/.*)?$/);
+    if (m) {
+      const scheme = m[1].toLowerCase();
+      const host   = m[2];
+      const rest   = m[3] || "/";
+      return "/" + scheme + "/" + host + rest;
+    }
+    return p.startsWith("/") ? p : "/" + p;
+  }
+
+  _internalToUrl(p) {
+    // "/http/example.com/a/b"  →  "http://example.com/a/b"
+    const m = p.match(/^\/([a-z][a-z0-9+\-.]*)\/([^/]+)(\/.*)?$/);
+    if (m) {
+      return m[1] + "://" + m[2] + (m[3] || "/");
+    }
+    return p;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+
+function now() { return new Date().toISOString(); }
+
+function normPath(p) {
+  if (typeof p !== "string") throw err("EINVAL");
+  const abs = p.startsWith("/") ? p : "/" + p;
+  const parts = abs.split("/").filter(Boolean);
+  const stack = [];
+  for (const part of parts) {
+    if (part === ".") continue;
+    if (part === "..") stack.pop();
+    else stack.push(part);
+  }
+  return "/" + stack.join("/");
+}
+
+function splitPath(p) {
+  const n = normPath(p);
+  if (n === "/") return { dir: "/", base: "" };
+  const idx = n.lastIndexOf("/");
+  return { dir: idx === 0 ? "/" : n.slice(0, idx), base: n.slice(idx + 1) };
+}
+
+function matchGlob(pattern, str) {
+  const re = pattern
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/\*\*/g, "§DOUBLE§").replace(/\*/g, "[^/]*")
+    .replace(/§DOUBLE§/g, ".*").replace(/\?/g, "[^/]");
+  return new RegExp("^" + re + "$").test(str);
+}
+
+// ---------------------------------------------------------------------------
+// Simple EventEmitter
+// ---------------------------------------------------------------------------
+
+class EventEmitter {
+  constructor() { this._events = {}; }
+  on(ev, fn)  { (this._events[ev] = this._events[ev] || []).push(fn); return this; }
+  off(ev, fn) { if (this._events[ev]) this._events[ev] = this._events[ev].filter(f => f !== fn); return this; }
+  emit(ev, ...args) { (this._events[ev] || []).slice().forEach(fn => { try { fn(...args); } catch(_) {} }); }
+  once(ev, fn) {
+    const w = (...args) => { fn(...args); this.off(ev, w); };
+    return this.on(ev, w);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Stats
+// ---------------------------------------------------------------------------
+
+class Stats {
+  constructor(node, nodeId) {
+    this.dev         = 1;
+    this.ino         = parseInt(nodeId.replace(/\D/g, ""), 10) || 0;
+    this.mode        = (node.mode & 0o7777) | (node.type === "dir" ? S_IFDIR : node.type === "symlink" ? S_IFLNK : S_IFREG);
+    this.nlink       = node.nlink || 1;
+    this.uid         = node.uid || 0;
+    this.gid         = node.gid || 0;
+    this.rdev        = 0;
+    this.size        = node.type === "file" ? (node.data || "").length : node.type === "symlink" ? (node.link || "").length : 4096;
+    this.blksize     = 4096;
+    this.blocks      = Math.ceil(this.size / 512);
+    this.atimeMs     = new Date(node.atime || node.ctime).getTime();
+    this.mtimeMs     = new Date(node.mtime || node.ctime).getTime();
+    this.ctimeMs     = new Date(node.ctime).getTime();
+    this.birthtimeMs = new Date(node.ctime).getTime();
+    this.atime = new Date(this.atimeMs); this.mtime = new Date(this.mtimeMs);
+    this.ctime = new Date(this.ctimeMs); this.birthtime = new Date(this.birthtimeMs);
+    this._type = node.type;
+  }
+  isFile()            { return this._type === "file"; }
+  isDirectory()       { return this._type === "dir"; }
+  isSymbolicLink()    { return this._type === "symlink"; }
+  isBlockDevice()     { return false; }
+  isCharacterDevice() { return false; }
+  isFIFO()            { return false; }
+  isSocket()          { return false; }
+}
+
+// ===========================================================================
+// TeaBin — Custom Binary Executable Format + VM
+// ===========================================================================
+
+/**
+ * Binary format (little-endian):
+ *   Magic: 0x54 0x45 0x41 0x42  ("TEAB")
+ *   Version: 1 byte
+ *   Data segment size: 4 bytes (uint32)
+ *   Data segment: N bytes
+ *   Code segment size: 4 bytes (uint32)
+ *   Code segment: each instruction = 6 bytes:
+ *     [opcode:1][mode:1][arg0:2][arg1:2]  (uint16 args)
+ *
+ * Registers: R0–R15 (index 0–15), SP (16), PC (17)
+ * FLAGS: ZF (zero), SF (sign), OF (overflow), CF (carry)
+ */
+
+const OP = {
+  NOP:   0x00,
+  // Data movement
+  MOV:   0x01,  // MOV dst_reg, src (reg or imm)
+  LOAD:  0x02,  // LOAD dst_reg, addr_reg  — load word from memory[addr]
+  STORE: 0x03,  // STORE addr_reg, src_reg — store word to memory[addr]
+  PUSH:  0x04,  // PUSH src_reg
+  POP:   0x05,  // POP  dst_reg
+  // Arithmetic
+  ADD:   0x10,
+  SUB:   0x11,
+  MUL:   0x12,
+  DIV:   0x13,
+  MOD:   0x14,
+  // Bitwise
+  AND:   0x20,
+  OR:    0x21,
+  XOR:   0x22,
+  NOT:   0x23,
+  SHL:   0x24,
+  SHR:   0x25,
+  // Compare / branch
+  CMP:   0x30,  // CMP reg, reg/imm  — sets FLAGS
+  JMP:   0x31,  // JMP addr (imm = instruction index)
+  JE:    0x32,  // Jump if ZF
+  JNE:   0x33,
+  JL:    0x34,  // Jump if SF != OF
+  JG:    0x35,  // Jump if ZF=0 and SF=OF
+  JLE:   0x36,
+  JGE:   0x37,
+  // Subroutines
+  CALL:  0x40,  // CALL addr — pushes PC, jumps
+  RET:   0x41,  // RET — pops PC
+  // Memory management
+  ALLOC: 0x50,  // ALLOC dst_reg, size_reg — malloc(size) → pointer in dst
+  FREE:  0x51,  // FREE addr_reg
+  // I/O
+  IN:    0x60,  // IN dst_reg, port
+  OUT:   0x61,  // OUT port, src_reg
+  // System
+  INT:   0x70,  // INT vector — software interrupt / syscall
+  HALT:  0xFF,
+};
+
+// Arg mode flags (encoded in 'mode' byte of instruction)
+const ARG_REG = 0;   // argument is register index
+const ARG_IMM = 1;   // argument is immediate value
+// mode byte: bits[0]=arg0 is imm, bits[1]=arg1 is imm
+
+const REG_COUNT = 18; // R0–R15 + SP(16) + PC(17)
+const SP_IDX = 16;
+const PC_IDX = 17;
+const HEAP_SIZE = 1024 * 64; // 64 KB
+
+class TeaBinVM {
+  constructor(opts = {}) {
+    this.regs  = new Int32Array(REG_COUNT);  // registers
+    this.mem   = new Uint8Array(HEAP_SIZE);  // flat heap
+    this.stack = [];                          // JS-array stack (separate from heap)
+    this.flags = { ZF: false, SF: false, OF: false, CF: false };
+    this._heapAllocs = new Map();            // ptr → size
+    this._heapTop    = 0;
+    this.halted = false;
+    this.exitCode = 0;
+    this._ports = opts.ports || {};          // port → {read, write} handlers
+    this._intHandlers = opts.interrupts || {}; // vector → fn(vm)
+    this.stdout = [];
+    this.stdin  = [];
+    this._maxCycles = opts.maxCycles || 1_000_000;
+  }
+
+  /** Load a TEAB binary (ArrayBuffer or Uint8Array) */
+  load(binary) {
+    const buf = binary instanceof Uint8Array ? binary : new Uint8Array(binary);
+    let off = 0;
+
+    // Magic
+    if (buf[0] !== 0x54 || buf[1] !== 0x45 || buf[2] !== 0x41 || buf[3] !== 0x42)
+      throw new Error("Invalid TEAB magic");
+    off = 4;
+
+    const _version = buf[off++]; // reserved
+
+    // Data segment
+    const dataSize = buf[off] | (buf[off+1]<<8) | (buf[off+2]<<16) | (buf[off+3]<<24);
+    off += 4;
+    this.mem.set(buf.subarray(off, off + dataSize), 0);
+    this._heapTop = dataSize;
+    off += dataSize;
+
+    // Code segment
+    const codeSize = buf[off] | (buf[off+1]<<8) | (buf[off+2]<<16) | (buf[off+3]<<24);
+    off += 4;
+    this._instructions = [];
+    for (let i = 0; i < codeSize; i += 6) {
+      const opcode = buf[off + i];
+      const mode   = buf[off + i + 1];
+      const arg0   = buf[off + i + 2] | (buf[off + i + 3] << 8);
+      const arg1   = buf[off + i + 4] | (buf[off + i + 5] << 8);
+      this._instructions.push({ opcode, mode, arg0, arg1 });
+    }
+    this.regs[SP_IDX] = HEAP_SIZE - 1; // stack grows down in heap (but we use JS stack)
+    this.regs[PC_IDX] = 0;
+    return this;
+  }
+
+  /** Build a TEAB binary from an assembly-like source string */
+  static assemble(src) {
+    const lines = src.split(/\n/).map(l => l.replace(/;.*/, "").trim()).filter(Boolean);
+    const labels = {};
+    // First pass: collect labels
+    let instrIdx = 0;
+    for (const line of lines) {
+      if (line.endsWith(":")) { labels[line.slice(0, -1)] = instrIdx; continue; }
+      if (line.startsWith(".data")) continue;
+      instrIdx++;
+    }
+
+    const instructions = [];
+    const dataBytes = [];
+    let inData = false;
+    const dataLabels = {};
+
+    for (const line of lines) {
+      if (line.startsWith(".data")) { inData = true; continue; }
+      if (line.startsWith(".code")) { inData = false; continue; }
+      if (line.endsWith(":")) continue; // label
+
+      if (inData) {
+        // .data label "string" or .data label 0x...
+        const m = line.match(/^(\w+)\s+"(.*)"$/) || line.match(/^(\w+)\s+(.+)$/);
+        if (m) {
+          dataLabels[m[1]] = dataBytes.length;
+          const val = m[2];
+          if (val.startsWith('"')) {
+            for (const ch of val.slice(1, -1)) dataBytes.push(ch.charCodeAt(0));
+            dataBytes.push(0); // null terminate
+          } else {
+            const n = parseInt(val, 0);
+            dataBytes.push(n & 0xFF, (n>>8)&0xFF, (n>>16)&0xFF, (n>>24)&0xFF);
+          }
+        }
+        continue;
+      }
+
+      const parts = line.split(/[\s,]+/);
+      const mnemo = parts[0].toUpperCase();
+      const opcode = OP[mnemo];
+      if (opcode === undefined) throw new Error(`Unknown opcode: ${mnemo}`);
+
+      const parseArg = (s) => {
+        if (!s) return { val: 0, imm: false };
+        if (/^R\d+$/i.test(s)) return { val: parseInt(s.slice(1)), imm: false };
+        if (s.toUpperCase() === "SP") return { val: SP_IDX, imm: false };
+        if (s.toUpperCase() === "PC") return { val: PC_IDX, imm: false };
+        if (labels[s] !== undefined) return { val: labels[s], imm: true };
+        if (dataLabels[s] !== undefined) return { val: dataLabels[s], imm: true };
+        return { val: parseInt(s, 0) & 0xFFFF, imm: true };
+      };
+
+      const a0 = parseArg(parts[1]);
+      const a1 = parseArg(parts[2]);
+      const mode = (a0.imm ? 1 : 0) | (a1.imm ? 2 : 0);
+      instructions.push({ opcode, mode, arg0: a0.val & 0xFFFF, arg1: a1.val & 0xFFFF });
+    }
+
+    // Encode
+    const dataSize = dataBytes.length;
+    const codeSize = instructions.length * 6;
+    const total = 4 + 1 + 4 + dataSize + 4 + codeSize;
+    const buf = new Uint8Array(total);
+    let off = 0;
+    buf[off++]=0x54; buf[off++]=0x45; buf[off++]=0x41; buf[off++]=0x42; // TEAB
+    buf[off++]=1; // version
+    buf[off++]=dataSize&0xFF; buf[off++]=(dataSize>>8)&0xFF;
+    buf[off++]=(dataSize>>16)&0xFF; buf[off++]=(dataSize>>24)&0xFF;
+    for (const b of dataBytes) buf[off++]=b;
+    buf[off++]=codeSize&0xFF; buf[off++]=(codeSize>>8)&0xFF;
+    buf[off++]=(codeSize>>16)&0xFF; buf[off++]=(codeSize>>24)&0xFF;
+    for (const ins of instructions) {
+      buf[off++]=ins.opcode; buf[off++]=ins.mode;
+      buf[off++]=ins.arg0&0xFF; buf[off++]=(ins.arg0>>8)&0xFF;
+      buf[off++]=ins.arg1&0xFF; buf[off++]=(ins.arg1>>8)&0xFF;
+    }
+    return buf;
+  }
+
+  _getReg(idx) { return this.regs[idx] | 0; }
+  _setReg(idx, val) {
+    this.regs[idx] = val | 0;
+    if (idx === PC_IDX) return;
+    this.flags.ZF = (val === 0);
+    this.flags.SF = (val < 0);
+  }
+
+  _arg(val, isImm) { return isImm ? (val | 0) : this._getReg(val); }
+
+  _memReadWord(addr) {
+    addr = addr & 0xFFFF;
+    return this.mem[addr] | (this.mem[addr+1]<<8) | (this.mem[addr+2]<<16) | (this.mem[addr+3]<<24);
+  }
+  _memWriteWord(addr, val) {
+    addr = addr & 0xFFFF;
+    this.mem[addr]=val&0xFF; this.mem[addr+1]=(val>>8)&0xFF;
+    this.mem[addr+2]=(val>>16)&0xFF; this.mem[addr+3]=(val>>24)&0xFF;
+  }
+
+  _alloc(size) {
+    const ptr = this._heapTop;
+    if (ptr + size > HEAP_SIZE) throw err("ENOMEM");
+    this._heapAllocs.set(ptr, size);
+    this._heapTop += size;
+    return ptr;
+  }
+
+  _free(ptr) { this._heapAllocs.delete(ptr); }
+
+  _setFlags(val) {
+    this.flags.ZF = (val === 0);
+    this.flags.SF = (val < 0);
+  }
+
+  run() {
+    let cycles = 0;
+    const ins = this._instructions;
+    while (!this.halted && this.regs[PC_IDX] < ins.length && cycles < this._maxCycles) {
+      const pc = this.regs[PC_IDX]++;
+      const { opcode, mode, arg0, arg1 } = ins[pc];
+      const imm0 = (mode & 1) !== 0;
+      const imm1 = (mode & 2) !== 0;
+      const v0   = this._arg(arg0, imm0);
+      const v1   = this._arg(arg1, imm1);
+
+      switch (opcode) {
+        case OP.NOP: break;
+        case OP.HALT: this.halted = true; this.exitCode = v0; break;
+
+        case OP.MOV: this._setReg(arg0, v1); break;
+
+        case OP.LOAD: {
+          const word = this._memReadWord(v1);
+          this._setReg(arg0, word);
+          break;
+        }
+        case OP.STORE: this._memWriteWord(v0, v1); break;
+
+        case OP.PUSH:
+          this.stack.push(v0);
+          break;
+        case OP.POP:
+          if (this.stack.length === 0) throw new Error("Stack underflow");
+          this._setReg(arg0, this.stack.pop());
+          break;
+
+        case OP.ADD: { const r = (v0 + v1)|0; this._setFlags(r); this.flags.CF = (v0+v1) > 0x7FFFFFFF; this._setReg(arg0, r); break; }
+        case OP.SUB: { const r = (v0 - v1)|0; this._setFlags(r); this._setReg(arg0, r); break; }
+        case OP.MUL: { const r = Math.imul(v0, v1); this._setFlags(r); this._setReg(arg0, r); break; }
+        case OP.DIV: { if (v1===0) throw new Error("Division by zero"); const r=(v0/v1)|0; this._setFlags(r); this._setReg(arg0, r); break; }
+        case OP.MOD: { if (v1===0) throw new Error("Division by zero"); const r=v0%v1; this._setFlags(r); this._setReg(arg0, r); break; }
+
+        case OP.AND: { const r=v0&v1; this._setFlags(r); this._setReg(arg0, r); break; }
+        case OP.OR:  { const r=v0|v1; this._setFlags(r); this._setReg(arg0, r); break; }
+        case OP.XOR: { const r=v0^v1; this._setFlags(r); this._setReg(arg0, r); break; }
+        case OP.NOT: { const r=~v0;   this._setFlags(r); this._setReg(arg0, r); break; }
+        case OP.SHL: { const r=(v0<<v1)|0; this._setFlags(r); this._setReg(arg0, r); break; }
+        case OP.SHR: { const r=(v0>>v1)|0; this._setFlags(r); this._setReg(arg0, r); break; }
+
+        case OP.CMP: {
+          const r = (v0 - v1)|0;
+          this.flags.ZF = (r === 0);
+          this.flags.SF = (r < 0);
+          this.flags.OF = ((v0 >= 0 && v1 < 0 && r < 0) || (v0 < 0 && v1 >= 0 && r >= 0));
+          this.flags.CF = (v0 < v1);
+          break;
+        }
+
+        case OP.JMP:  this.regs[PC_IDX] = v0; break;
+        case OP.JE:   if (this.flags.ZF) this.regs[PC_IDX] = v0; break;
+        case OP.JNE:  if (!this.flags.ZF) this.regs[PC_IDX] = v0; break;
+        case OP.JL:   if (this.flags.SF !== this.flags.OF) this.regs[PC_IDX] = v0; break;
+        case OP.JG:   if (!this.flags.ZF && this.flags.SF === this.flags.OF) this.regs[PC_IDX] = v0; break;
+        case OP.JLE:  if (this.flags.ZF || this.flags.SF !== this.flags.OF) this.regs[PC_IDX] = v0; break;
+        case OP.JGE:  if (this.flags.SF === this.flags.OF) this.regs[PC_IDX] = v0; break;
+
+        case OP.CALL:
+          this.stack.push(this.regs[PC_IDX]);
+          this.regs[PC_IDX] = v0;
+          break;
+        case OP.RET:
+          if (this.stack.length === 0) { this.halted = true; break; }
+          this.regs[PC_IDX] = this.stack.pop();
+          break;
+
+        case OP.ALLOC: {
+          const ptr = this._alloc(v1);
+          this._setReg(arg0, ptr);
+          break;
+        }
+        case OP.FREE: this._free(v0); break;
+
+        case OP.IN: {
+          const port = v1;
+          const handler = this._ports[port];
+          const val = handler ? handler.read() : (this.stdin.shift() || 0);
+          this._setReg(arg0, val);
+          break;
+        }
+        case OP.OUT: {
+          const port = v0;
+          const val = v1;
+          const handler = this._ports[port];
+          if (handler) { handler.write(val); }
+          else { this.stdout.push(val); }
+          break;
+        }
+
+        case OP.INT: {
+          const vec = v0;
+          const handler = this._intHandlers[vec];
+          if (handler) handler(this);
+          // Syscall table for INT 0x80 (Linux-style)
+          else if (vec === 0x80) this._syscall();
+          break;
+        }
+
+        default:
+          throw new Error(`Unknown opcode: 0x${opcode.toString(16)}`);
+      }
+      cycles++;
+    }
+    if (cycles >= this._maxCycles) throw new Error("CPU cycle limit exceeded");
+    return this.exitCode;
+  }
+
+  _syscall() {
+    // R0 = syscall number, R1–R5 = args
+    const num = this._getReg(0);
+    switch (num) {
+      case 1: // write(fd, buf_ptr, len) → writes string to stdout
+      {
+        const ptr = this._getReg(2);
+        const len = this._getReg(3);
+        let s = "";
+        for (let i = 0; i < len; i++) s += String.fromCharCode(this.mem[(ptr + i) & 0xFFFF] || 0);
+        this.stdout.push(s);
+        this._setReg(0, len);
+        break;
+      }
+      case 60: // exit(code)
+        this.exitCode = this._getReg(1);
+        this.halted = true;
+        break;
+      default:
+        this._setReg(0, -1); // ENOSYS
+    }
+  }
+
+  /** Read a null-terminated string from memory at addr */
+  readString(addr) {
+    let s = "";
+    let i = addr;
+    while (i < HEAP_SIZE && this.mem[i] !== 0) s += String.fromCharCode(this.mem[i++]);
+    return s;
+  }
+}
+
+// ===========================================================================
+// Shell (sh interpreter)
+// ===========================================================================
+
+/**
+ * Sh — a minimal but real sh interpreter
+ * Supports: variables, ENV, export, PATH lookup, pipelines (|), redirections
+ *   (>, >>, <), background (&), &&, ||, ;, subshells $(), quoting, globs,
+ *   built-ins, #! scripts, and TeaBin executables.
+ */
+
+class Sh {
+  constructor(fs, opts = {}) {
+    this._fs  = fs;
+    this.env  = Object.assign({
+      PATH: "/bin:/usr/bin:/usr/local/bin",
+      HOME: "/root",
+      USER: "root",
+      SHELL: "/bin/sh",
+      PWD: "/",
+      PS1: "$ ",
+      IFS: " \t\n",
+    }, opts.env || {});
+    this.aliases = {};
+    this._exitCode = 0;
+    this._uid = opts.uid !== undefined ? opts.uid : 0;
+    this._gid = opts.gid !== undefined ? opts.gid : 0;
+  }
+
+  // -- Public API -----------------------------------------------------------
+
+  /** Execute a shell script string. Returns { stdout, stderr, code }. */
+  exec(script, opts = {}) {
+    const ctx = {
+      stdin:  opts.stdin  || [],
+      stdout: opts.stdout || [],
+      stderr: opts.stderr || [],
+      vars:   Object.assign({}, this.env),
+    };
+    try {
+      const tokens = this._lex(script);
+      const ast    = this._parse(tokens);
+      this._execList(ast, ctx);
+    } catch(e) {
+      if (e && e._exit) { this._exitCode = e.code; return { stdout: ctx.stdout.join(""), stderr: ctx.stderr.join(""), code: e.code }; }
+      ctx.stderr.push(e.message + "\n");
+      this._exitCode = 1;
+    }
+    return {
+      stdout: ctx.stdout.join(""),
+      stderr: ctx.stderr.join(""),
+      code: this._exitCode,
+    };
+  }
+
+  // -- Lexer ----------------------------------------------------------------
+
+  _lex(src) {
+    const tokens = [];
+    let i = 0;
+    while (i < src.length) {
+      const ch = src[i];
+      // skip whitespace (but not newlines — they're separators)
+      if (ch === " " || ch === "\t") { i++; continue; }
+      if (ch === "\n" || ch === ";") { tokens.push({ type: "SEP" }); i++; continue; }
+      if (ch === "#") { while (i < src.length && src[i] !== "\n") i++; continue; }
+      if (ch === "&" && src[i+1] === "&") { tokens.push({ type: "AND" }); i+=2; continue; }
+      if (ch === "|" && src[i+1] === "|") { tokens.push({ type: "OR"  }); i+=2; continue; }
+      if (ch === "|") { tokens.push({ type: "PIPE" }); i++; continue; }
+      if (ch === "&") { tokens.push({ type: "BG" }); i++; continue; }
+      if (ch === ">") {
+        if (src[i+1] === ">") { tokens.push({ type: "REDIR_APPEND" }); i+=2; }
+        else                  { tokens.push({ type: "REDIR_OUT" });    i++;  }
+        continue;
+      }
+      if (ch === "<") { tokens.push({ type: "REDIR_IN" }); i++; continue; }
+      if (ch === "(") { tokens.push({ type: "LPAREN" }); i++; continue; }
+      if (ch === ")") { tokens.push({ type: "RPAREN" }); i++; continue; }
+      if (ch === "{") { tokens.push({ type: "LBRACE" }); i++; continue; }
+      if (ch === "}") { tokens.push({ type: "RBRACE" }); i++; continue; }
+
+      // String / word
+      let word = "";
+      while (i < src.length) {
+        const c = src[i];
+        if (" \t\n;|&<>(){}".includes(c)) break;
+        if (c === "\\") { i++; word += src[i] || ""; i++; continue; }
+        if (c === "'") {
+          i++;
+          while (i < src.length && src[i] !== "'") word += src[i++];
+          i++;
+          continue;
+        }
+        if (c === '"') {
+          i++;
+          while (i < src.length && src[i] !== '"') {
+            if (src[i] === "\\" && '"$`\\'.includes(src[i+1])) { i++; word += src[i++]; }
+            else word += src[i++];
+          }
+          i++;
+          continue;
+        }
+        word += c; i++;
+      }
+      if (word) tokens.push({ type: "WORD", value: word });
+    }
+    return tokens;
+  }
+
+  // -- Parser ---------------------------------------------------------------
+  // Produces a list of command nodes
+
+  _parse(tokens) {
+    // Flatten into a list of "statements" separated by SEP/AND/OR/PIPE/BG
+    return this._parseList(tokens, 0).nodes;
+  }
+
+  _parseList(tokens, pos) {
+    const nodes = [];
+    while (pos < tokens.length) {
+      const { node, pos: newPos } = this._parseCmd(tokens, pos);
+      pos = newPos;
+      if (node) nodes.push(node);
+      if (pos >= tokens.length) break;
+      const sep = tokens[pos];
+      if (sep.type === "RPAREN" || sep.type === "RBRACE") break;
+      if (sep.type === "SEP")  { nodes.push({ type: "SEP" }); pos++; continue; }
+      if (sep.type === "AND")  { nodes.push({ type: "AND" }); pos++; continue; }
+      if (sep.type === "OR")   { nodes.push({ type: "OR"  }); pos++; continue; }
+      if (sep.type === "PIPE") { nodes.push({ type: "PIPE" }); pos++; continue; }
+      if (sep.type === "BG")   { nodes.push({ type: "BG"  }); pos++; continue; }
+      break;
+    }
+    return { nodes, pos };
+  }
+
+  _parseCmd(tokens, pos) {
+    const words = [];
+    const redirs = [];
+    while (pos < tokens.length) {
+      const tok = tokens[pos];
+      if (["SEP","AND","OR","PIPE","BG","RPAREN","RBRACE"].includes(tok.type)) break;
+      if (tok.type === "REDIR_OUT" || tok.type === "REDIR_APPEND" || tok.type === "REDIR_IN") {
+        const kind = tok.type;
+        pos++;
+        const file = tokens[pos];
+        if (!file || file.type !== "WORD") throw new Error("sh: expected filename after redirect");
+        redirs.push({ kind, file: file.value });
+        pos++;
+        continue;
+      }
+      if (tok.type === "LPAREN") {
+        // subshell
+        pos++;
+        const { nodes, pos: endPos } = this._parseList(tokens, pos);
+        pos = endPos + 1; // skip RPAREN
+        return { node: { type: "SUBSHELL", body: nodes }, pos };
+      }
+      if (tok.type === "WORD") { words.push(tok.value); pos++; continue; }
+      pos++;
+    }
+    if (words.length === 0 && redirs.length === 0) return { node: null, pos };
+    return { node: { type: "CMD", words, redirs }, pos };
+  }
+
+  // -- Executor -------------------------------------------------------------
+
+  _execList(nodes, ctx) {
+    let i = 0;
+    while (i < nodes.length) {
+      const node = nodes[i];
+      if (!node || node.type === "SEP") { i++; continue; }
+
+      // Collect a pipeline
+      const pipeline = [node];
+      i++;
+      while (i < nodes.length && nodes[i] && nodes[i].type === "PIPE") {
+        i++; // skip PIPE
+        if (i < nodes.length && nodes[i] && nodes[i].type !== "SEP")
+          pipeline.push(nodes[i++]);
+      }
+
+      this._execPipeline(pipeline, ctx);
+
+      // Check && / ||
+      if (i < nodes.length && nodes[i]) {
+        if (nodes[i].type === "AND")  { i++; if (this._exitCode !== 0) { while (i < nodes.length && nodes[i].type !== "SEP") i++; } continue; }
+        if (nodes[i].type === "OR")   { i++; if (this._exitCode === 0) { while (i < nodes.length && nodes[i].type !== "SEP") i++; } continue; }
+      }
+    }
+  }
+
+  _execPipeline(pipeline, ctx) {
+    if (pipeline.length === 1) {
+      this._execNode(pipeline[0], ctx);
+      return;
+    }
+    // Build piped buffers
+    let prevOut = ctx.stdin;
+    for (let i = 0; i < pipeline.length; i++) {
+      const isLast = (i === pipeline.length - 1);
+      const pipeOut = isLast ? ctx.stdout : [];
+      const pipeCtx = {
+        stdin:  prevOut,
+        stdout: pipeOut,
+        stderr: ctx.stderr,
+        vars:   ctx.vars,
+      };
+      this._execNode(pipeline[i], pipeCtx);
+      prevOut = pipeOut;
+    }
+  }
+
+  _execNode(node, ctx) {
+    if (!node) return;
+    if (node.type === "SEP") return;
+    if (node.type === "SUBSHELL") {
+      const subCtx = { stdin: [...ctx.stdin], stdout: ctx.stdout, stderr: ctx.stderr, vars: { ...ctx.vars } };
+      this._execList(node.body, subCtx);
+      return;
+    }
+    if (node.type === "CMD") {
+      // Expand vars and perform globbing
+      const words = node.words.map(w => this._expand(w, ctx));
+      const expanded = [];
+      for (const w of words) {
+        const globs = this._glob(w, ctx.vars.PWD || "/");
+        expanded.push(...globs);
+      }
+      if (expanded.length === 0) return;
+
+      // Handle redirections
+      let stdin  = ctx.stdin;
+      let stdout = ctx.stdout;
+      for (const r of node.redirs) {
+        const file = this._expand(r.file, ctx);
+        if (r.kind === "REDIR_IN") {
+          try { stdin = [this._fs.readFile(file, "utf8")]; } catch(_) { stdin = []; }
+        } else if (r.kind === "REDIR_OUT") {
+          const buf = [];
+          stdout = buf;
+          // after exec, write buf to file
+          const flush = () => this._fs.writeFile(file, buf.join(""));
+          ctx._flushes = ctx._flushes || [];
+          ctx._flushes.push(flush);
+        } else if (r.kind === "REDIR_APPEND") {
+          const buf = [];
+          stdout = buf;
+          const flush = () => this._fs.appendFile(file, buf.join(""));
+          ctx._flushes = ctx._flushes || [];
+          ctx._flushes.push(flush);
+        }
+      }
+
+      const cmdCtx = { stdin, stdout, stderr: ctx.stderr, vars: ctx.vars };
+      this._runCommand(expanded[0], expanded.slice(1), cmdCtx);
+
+      // Flush redirections
+      for (const f of (ctx._flushes || [])) f();
+      ctx._flushes = [];
+      return;
+    }
+  }
+
+  _expand(word, ctx) {
+    // $VAR, ${VAR}, $?, $$
+    return word.replace(/\$\{([^}]+)\}|\$([A-Za-z_][A-Za-z0-9_]*|\?|\$|\d+)/g, (_, a, b) => {
+      const name = a || b;
+      if (name === "?") return String(this._exitCode);
+      if (name === "$") return "$$";
+      return ctx.vars[name] !== undefined ? ctx.vars[name] : "";
+    });
+  }
+
+  _glob(pattern, cwd) {
+    if (!/[*?]/.test(pattern)) return [pattern];
+    try {
+      const hits = this._fs.glob(pattern, { cwd });
+      return hits.length ? hits : [pattern];
+    } catch(_) { return [pattern]; }
+  }
+
+  _runCommand(cmd, args, ctx) {
+    // Alias expansion
+    if (this.aliases[cmd]) {
+      const aliased = this._lex(this.aliases[cmd] + " " + args.join(" "));
+      const ast = this._parse(aliased);
+      this._execList(ast, ctx);
+      return;
+    }
+
+    // Variable assignment (FOO=bar)
+    if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(cmd)) {
+      const eq = cmd.indexOf("=");
+      const key = cmd.slice(0, eq);
+      const val = this._expand(cmd.slice(eq + 1), ctx);
+      ctx.vars[key] = val;
+      this.env[key] = val;
+      this._exitCode = 0;
+      return;
+    }
+
+    // Built-ins
+    if (this._builtin(cmd, args, ctx)) return;
+
+    // PATH lookup
+    const bin = this._findBin(cmd, ctx.vars.PATH || this.env.PATH);
+    if (!bin) {
+      ctx.stderr.push(`sh: ${cmd}: command not found\n`);
+      this._exitCode = 127;
+      return;
+    }
+
+    this._execFile(bin, [cmd, ...args], ctx);
+  }
+
+  _findBin(name, PATH) {
+    if (name.startsWith("/") || name.startsWith("./") || name.startsWith("../")) {
+      return this._fs.exists(name) ? name : null;
+    }
+    for (const dir of (PATH || "").split(":")) {
+      const p = dir.endsWith("/") ? dir + name : dir + "/" + name;
+      if (this._fs.exists(p)) return p;
+    }
+    return null;
+  }
+
+  _execFile(path, argv, ctx) {
+    let data;
+    try {
+      data = this._fs.readFile(path, "utf8");
+    } catch(e) {
+      ctx.stderr.push(`sh: ${path}: ${e.message}\n`);
+      this._exitCode = 126;
+      return;
+    }
+
+    // Check execute permission
+    try {
+      const st = this._fs.stat(path);
+      const canExec = (st.uid === this._uid && (st.mode & S_IXUSR)) ||
+                      (st.gid === this._gid && (st.mode & S_IXGRP)) ||
+                      (this._uid === 0) ||
+                      (st.mode & S_IXOTH);
+      if (!canExec) { ctx.stderr.push(`sh: ${path}: permission denied\n`); this._exitCode = 126; return; }
+    } catch(_) {}
+
+    // She-bang
+    if (data.startsWith("#!")) {
+      const firstLine = data.split("\n")[0].slice(2).trim();
+      const interp = firstLine.split(/\s+/);
+      this._runCommand(interp[0], [...interp.slice(1), path, ...argv.slice(1)], ctx);
+      return;
+    }
+
+    // TEAB binary magic (base64-encoded in the file data, or raw bytes check)
+    if (data.startsWith("TEAB") || (data.charCodeAt(0) === 0x54 && data.charCodeAt(1) === 0x45)) {
+      this._execTeaBin(data, argv, ctx);
+      return;
+    }
+
+    // Treat as shell script
+    const saved = { ...this.env };
+    ctx.vars["0"] = argv[0];
+    argv.slice(1).forEach((a, i) => { ctx.vars[String(i+1)] = a; });
+    this.exec(data, { stdin: ctx.stdin, stdout: ctx.stdout, stderr: ctx.stderr });
+    Object.assign(this.env, saved);
+  }
+
+  _execTeaBin(data, argv, ctx) {
+    try {
+      // Encode file data as Uint8Array (assuming it's stored as a binary string)
+      const bytes = new Uint8Array(data.length);
+      for (let i = 0; i < data.length; i++) bytes[i] = data.charCodeAt(i) & 0xFF;
+      const vm = new TeaBinVM({
+        interrupts: {
+          0x80: (vm) => {
+            // Write syscall: R0=1 → stdout
+            if (vm._getReg(0) === 1) {
+              const ptr = vm._getReg(2);
+              const len = vm._getReg(3);
+              let s = "";
+              for (let i = 0; i < len; i++) s += String.fromCharCode(vm.mem[(ptr+i)&0xFFFF]);
+              ctx.stdout.push(s);
+              vm._setReg(0, len);
+            }
+          }
+        }
+      });
+      vm.load(bytes);
+      this._exitCode = vm.run();
+      for (const o of vm.stdout) ctx.stdout.push(typeof o === "number" ? String.fromCharCode(o) : String(o));
+    } catch(e) {
+      ctx.stderr.push(`${argv[0]}: ${e.message}\n`);
+      this._exitCode = 1;
+    }
+  }
+
+  _builtin(cmd, args, ctx) {
+    switch (cmd) {
+      case "echo": {
+        let newline = true, i = 0;
+        if (args[0] === "-n") { newline = false; i = 1; }
+        ctx.stdout.push(args.slice(i).join(" ") + (newline ? "\n" : ""));
+        this._exitCode = 0;
+        return true;
+      }
+      case "printf": {
+        let fmt = args[0] || "";
+        let ai = 1;
+        const out = fmt.replace(/%[diouxXeEfgGsqcb%]/g, (m) => {
+          if (m === "%%") return "%";
+          const a = args[ai++] || "";
+          if (m === "%d" || m === "%i") return String(parseInt(a,10)||0);
+          if (m === "%s") return a;
+          if (m === "%x") return (parseInt(a,10)||0).toString(16);
+          if (m === "%o") return (parseInt(a,10)||0).toString(8);
+          return a;
+        }).replace(/\\n/g,"\n").replace(/\\t/g,"\t").replace(/\\r/g,"\r");
+        ctx.stdout.push(out);
+        this._exitCode = 0;
+        return true;
+      }
+      case "cd": {
+        const target = args[0] || ctx.vars.HOME || "/";
+        const p = target.startsWith("/") ? target : (ctx.vars.PWD || "/") + "/" + target;
+        const norm = normPath(p);
+        if (!this._fs.exists(norm)) {
+          ctx.stderr.push(`cd: ${target}: No such file or directory\n`);
+          this._exitCode = 1;
+        } else {
+          ctx.vars.PWD = norm;
+          this.env.PWD = norm;
+          this._exitCode = 0;
+        }
+        return true;
+      }
+      case "pwd": { ctx.stdout.push((ctx.vars.PWD || "/") + "\n"); this._exitCode = 0; return true; }
+      case "export": {
+        for (const a of args) {
+          if (a.includes("=")) {
+            const [k, ...v] = a.split("=");
+            ctx.vars[k] = v.join("=");
+            this.env[k] = ctx.vars[k];
+          } else {
+            this.env[a] = ctx.vars[a] || "";
+          }
+        }
+        this._exitCode = 0;
+        return true;
+      }
+      case "unset": { for (const a of args) { delete ctx.vars[a]; delete this.env[a]; } this._exitCode = 0; return true; }
+      case "env":
+      case "printenv": {
+        if (args.length) { ctx.stdout.push((ctx.vars[args[0]] || "") + "\n"); }
+        else { for (const [k,v] of Object.entries(ctx.vars)) ctx.stdout.push(`${k}=${v}\n`); }
+        this._exitCode = 0; return true;
+      }
+      case "set": {
+        for (const [k,v] of Object.entries(ctx.vars)) ctx.stdout.push(`${k}=${v}\n`);
+        this._exitCode = 0; return true;
+      }
+      case "alias": {
+        if (args.length === 0) {
+          for (const [k,v] of Object.entries(this.aliases)) ctx.stdout.push(`alias ${k}='${v}'\n`);
+        } else {
+          for (const a of args) {
+            const eq = a.indexOf("=");
+            if (eq < 0) { ctx.stdout.push(`alias ${a}='${this.aliases[a] || ""}'\n`); }
+            else { this.aliases[a.slice(0, eq)] = a.slice(eq + 1).replace(/^'|'$/g, ""); }
+          }
+        }
+        this._exitCode = 0; return true;
+      }
+      case "unalias": { for (const a of args) delete this.aliases[a]; this._exitCode = 0; return true; }
+      case "type":
+      case "which": {
+        for (const a of args) {
+          if (this.aliases[a]) { ctx.stdout.push(`${a} is aliased to '${this.aliases[a]}'\n`); continue; }
+          if (["echo","printf","cd","pwd","export","unset","env","alias","type","which","true","false","exit","read","test","[","source",".","sleep","kill"].includes(a)) {
+            ctx.stdout.push(`${a} is a shell builtin\n`); continue;
+          }
+          const bin = this._findBin(a, ctx.vars.PATH);
+          if (bin) ctx.stdout.push(bin + "\n");
+          else ctx.stderr.push(`${a}: not found\n`);
+        }
+        this._exitCode = 0; return true;
+      }
+      case "true":  { this._exitCode = 0; return true; }
+      case "false": { this._exitCode = 1; return true; }
+      case "exit":  { throw { _exit: true, code: parseInt(args[0], 10) || 0 }; }
+      case "source":
+      case ".": {
+        const path = args[0];
+        if (!path) { ctx.stderr.push("source: filename argument required\n"); this._exitCode = 1; return true; }
+        try {
+          const script = this._fs.readFile(path, "utf8");
+          const r = this.exec(script, { stdin: ctx.stdin, stdout: ctx.stdout, stderr: ctx.stderr });
+          this._exitCode = r.code;
+        } catch(e) { ctx.stderr.push(`source: ${path}: ${e.message}\n`); this._exitCode = 1; }
+        return true;
+      }
+      case "read": {
+        const varName = args[0] || "REPLY";
+        const line = (ctx.stdin.shift() || "").replace(/\n$/, "");
+        ctx.vars[varName] = line;
+        this._exitCode = 0; return true;
+      }
+      case "test":
+      case "[": {
+        // Basic test expressions
+        const a = args.slice(0, args[args.length-1] === "]" ? -1 : undefined);
+        this._exitCode = this._test(a, ctx) ? 0 : 1;
+        return true;
+      }
+      case "sleep": {
+        // no-op in virtual fs
+        this._exitCode = 0; return true;
+      }
+      case "cat": {
+        if (args.length === 0) {
+          ctx.stdout.push(...ctx.stdin); this._exitCode = 0; return true;
+        }
+        for (const f of args) {
+          try { ctx.stdout.push(this._fs.readFile(f, "utf8")); }
+          catch(e) { ctx.stderr.push(`cat: ${f}: ${e.message}\n`); this._exitCode = 1; return true; }
+        }
+        this._exitCode = 0; return true;
+      }
+      case "ls": {
+        const dir = args.find(a => !a.startsWith("-")) || ctx.vars.PWD || "/";
+        const showHidden = args.includes("-a") || args.includes("-la") || args.includes("-al");
+        const long = args.includes("-l") || args.includes("-la") || args.includes("-al");
+        try {
+          const entries = this._fs.readdir(dir, { withFileTypes: true });
+          for (const e of entries) {
+            if (!showHidden && e.name.startsWith(".")) continue;
+            if (long) {
+              const st = this._fs.stat(dir === "/" ? "/" + e.name : dir + "/" + e.name);
+              const type = e.isDirectory() ? "d" : e.isSymbolicLink() ? "l" : "-";
+              const mode = this._formatMode(st.mode);
+              ctx.stdout.push(`${type}${mode} ${st.nlink} ${st.uid} ${st.gid} ${String(st.size).padStart(6)} ${e.name}\n`);
+            } else {
+              ctx.stdout.push(e.name + "  ");
+            }
+          }
+          if (!long) ctx.stdout.push("\n");
+          this._exitCode = 0;
+        } catch(e) { ctx.stderr.push(`ls: ${dir}: ${e.message}\n`); this._exitCode = 1; }
+        return true;
+      }
+      case "mkdir": {
+        const recursive = args.includes("-p");
+        const dirs = args.filter(a => !a.startsWith("-"));
+        for (const d of dirs) {
+          try { this._fs.mkdir(d, { recursive }); }
+          catch(e) { ctx.stderr.push(`mkdir: ${d}: ${e.message}\n`); this._exitCode = 1; return true; }
+        }
+        this._exitCode = 0; return true;
+      }
+      case "rm": {
+        const recursive = args.includes("-r") || args.includes("-rf") || args.includes("-fr");
+        const force     = args.includes("-f") || args.includes("-rf") || args.includes("-fr");
+        const files = args.filter(a => !a.startsWith("-"));
+        for (const f of files) {
+          try { this._fs.rm(f, { recursive, force }); }
+          catch(e) { if (!force) { ctx.stderr.push(`rm: ${f}: ${e.message}\n`); this._exitCode = 1; return true; } }
+        }
+        this._exitCode = 0; return true;
+      }
+      case "cp": {
+        const recursive = args.includes("-r") || args.includes("-R");
+        const paths = args.filter(a => !a.startsWith("-"));
+        if (paths.length < 2) { ctx.stderr.push("cp: missing file operand\n"); this._exitCode = 1; return true; }
+        try { this._fs.cp(paths[0], paths[1], { recursive }); this._exitCode = 0; }
+        catch(e) { ctx.stderr.push(`cp: ${e.message}\n`); this._exitCode = 1; }
+        return true;
+      }
+      case "mv": {
+        if (args.length < 2) { ctx.stderr.push("mv: missing file operand\n"); this._exitCode = 1; return true; }
+        try { this._fs.rename(args[0], args[1]); this._exitCode = 0; }
+        catch(e) { ctx.stderr.push(`mv: ${e.message}\n`); this._exitCode = 1; }
+        return true;
+      }
+      case "chmod": {
+        if (args.length < 2) { ctx.stderr.push("chmod: missing operand\n"); this._exitCode = 1; return true; }
+        const mode = parseInt(args[0], 8);
+        try { this._fs.chmod(args[1], mode); this._exitCode = 0; }
+        catch(e) { ctx.stderr.push(`chmod: ${e.message}\n`); this._exitCode = 1; }
+        return true;
+      }
+      case "touch": {
+        for (const f of args) {
+          try {
+            if (!this._fs.exists(f)) this._fs.writeFile(f, "");
+            else this._fs.utimes(f, new Date(), new Date());
+          } catch(e) { ctx.stderr.push(`touch: ${f}: ${e.message}\n`); this._exitCode = 1; return true; }
+        }
+        this._exitCode = 0; return true;
+      }
+      case "grep": {
+        const pattern = args[0];
+        const files   = args.slice(1);
+        if (!pattern) { ctx.stderr.push("grep: usage: grep PATTERN [FILE...]\n"); this._exitCode = 1; return true; }
+        const re = new RegExp(pattern);
+        let found = false;
+        const search = (text, label) => {
+          for (const line of text.split("\n")) {
+            if (re.test(line)) { ctx.stdout.push((files.length > 1 ? label + ":" : "") + line + "\n"); found = true; }
+          }
+        };
+        if (files.length === 0) { search(ctx.stdin.join(""), "stdin"); }
+        else {
+          for (const f of files) {
+            try { search(this._fs.readFile(f, "utf8"), f); }
+            catch(e) { ctx.stderr.push(`grep: ${f}: ${e.message}\n`); }
+          }
+        }
+        this._exitCode = found ? 0 : 1; return true;
+      }
+      case "find": {
+        const path = args[0] || ctx.vars.PWD || "/";
+        const opts = {};
+        for (let i = 1; i < args.length; i++) {
+          if (args[i] === "-type" && args[i+1]) { opts.type = args[++i]; }
+          if (args[i] === "-name" && args[i+1]) { opts.name = args[++i]; }
+        }
+        try {
+          const results = this._fs.find(path, opts);
+          for (const r of results) ctx.stdout.push(r + "\n");
+          this._exitCode = 0;
+        } catch(e) { ctx.stderr.push(`find: ${e.message}\n`); this._exitCode = 1; }
+        return true;
+      }
+      case "wc": {
+        const text = args.length > 0 ? this._fs.readFile(args[0], "utf8") : ctx.stdin.join("");
+        const lines = (text.match(/\n/g) || []).length;
+        const words = text.split(/\s+/).filter(Boolean).length;
+        const chars = text.length;
+        ctx.stdout.push(`  ${lines}  ${words} ${chars}\n`);
+        this._exitCode = 0; return true;
+      }
+      case "head": {
+        const n = args.includes("-n") ? parseInt(args[args.indexOf("-n")+1]) : 10;
+        const src = args.find(a => !a.startsWith("-")) || null;
+        const text = src ? this._fs.readFile(src, "utf8") : ctx.stdin.join("");
+        ctx.stdout.push(text.split("\n").slice(0, n).join("\n") + "\n");
+        this._exitCode = 0; return true;
+      }
+      case "tail": {
+        const n = args.includes("-n") ? parseInt(args[args.indexOf("-n")+1]) : 10;
+        const src = args.find(a => !a.startsWith("-")) || null;
+        const text = src ? this._fs.readFile(src, "utf8") : ctx.stdin.join("");
+        const lines = text.split("\n");
+        ctx.stdout.push(lines.slice(-n).join("\n") + "\n");
+        this._exitCode = 0; return true;
+      }
+      case "sort": {
+        const text = ctx.stdin.join("");
+        const sorted = text.split("\n").filter(Boolean).sort().join("\n") + "\n";
+        ctx.stdout.push(sorted); this._exitCode = 0; return true;
+      }
+      case "uniq": {
+        const text = ctx.stdin.join("");
+        const lines = text.split("\n");
+        const out = [lines[0]];
+        for (let i = 1; i < lines.length; i++) if (lines[i] !== lines[i-1]) out.push(lines[i]);
+        ctx.stdout.push(out.join("\n") + "\n"); this._exitCode = 0; return true;
+      }
+      case "tr": {
+        const [set1, set2] = args;
+        let text = ctx.stdin.join("");
+        if (set1 && set2) {
+          for (let i = 0; i < Math.min(set1.length, set2.length); i++)
+            text = text.split(set1[i]).join(set2[i]);
+        }
+        ctx.stdout.push(text); this._exitCode = 0; return true;
+      }
+      case "sed": {
+        // Basic s/pat/rep/g support
+        const expr = args[0] || "";
+        const src  = args[1] || null;
+        let text = src ? this._fs.readFile(src, "utf8") : ctx.stdin.join("");
+        const m = expr.match(/^s\/(.+)\/(.*)\/([gim]*)$/);
+        if (m) {
+          const re = new RegExp(m[1], m[3] || "");
+          text = text.replace(re, m[2]);
+        }
+        ctx.stdout.push(text); this._exitCode = 0; return true;
+      }
+      case "awk": {
+        // Very minimal: print $N support
+        const prog = args[0] || "{ print }";
+        const text = ctx.stdin.join("");
+        for (const line of text.split("\n").filter(Boolean)) {
+          const fields = line.split(/\s+/);
+          const out = prog
+            .replace(/\$(\d+)/g, (_, n) => fields[parseInt(n)-1] || "")
+            .replace(/\$0/g, line)
+            .replace(/print\s*/g, "");
+          ctx.stdout.push(out.trim() + "\n");
+        }
+        this._exitCode = 0; return true;
+      }
+      default: return false;
+    }
+  }
+
+  _test(args, ctx) {
+    if (args.length === 0) return false;
+    if (args[0] === "!" ) return !this._test(args.slice(1), ctx);
+    if (args[1] === "-a") return this._test(args.slice(0,1), ctx) && this._test(args.slice(2), ctx);
+    if (args[1] === "-o") return this._test(args.slice(0,1), ctx) || this._test(args.slice(2), ctx);
+    if (args[0] === "-f") return this._fs.exists(args[1]) && this._fs.stat(args[1]).isFile();
+    if (args[0] === "-d") return this._fs.exists(args[1]) && this._fs.stat(args[1]).isDirectory();
+    if (args[0] === "-e") return this._fs.exists(args[1]);
+    if (args[0] === "-n") return (args[1] || "").length > 0;
+    if (args[0] === "-z") return (args[1] || "").length === 0;
+    if (args[1] === "=")  return args[0] === args[2];
+    if (args[1] === "!=") return args[0] !== args[2];
+    if (args[1] === "-eq") return parseInt(args[0]) === parseInt(args[2]);
+    if (args[1] === "-ne") return parseInt(args[0]) !== parseInt(args[2]);
+    if (args[1] === "-lt") return parseInt(args[0]) <   parseInt(args[2]);
+    if (args[1] === "-le") return parseInt(args[0]) <=  parseInt(args[2]);
+    if (args[1] === "-gt") return parseInt(args[0]) >   parseInt(args[2]);
+    if (args[1] === "-ge") return parseInt(args[0]) >=  parseInt(args[2]);
+    return args[0].length > 0;
+  }
+
+  _formatMode(mode) {
+    const bits = "rwxrwxrwx";
+    return bits.split("").map((b, i) => (mode & (1 << (8-i))) ? b : "-").join("");
+  }
+}
+
+// ===========================================================================
+// REPL
+// ===========================================================================
+
+class ShRepl extends EventEmitter {
+  constructor(sh) {
+    super();
+    this._sh  = sh;
+    this._history = [];
+    this._histIdx = -1;
+    this.running = true;
+  }
+
+  /** Feed a line of input, returns { stdout, stderr, code } */
+  line(input) {
+    if (!this.running) return { stdout: "", stderr: "Session closed\n", code: 1 };
+    this._history.push(input);
+    this._histIdx = this._history.length;
+    const result = this._sh.exec(input);
+    this.emit("result", result);
+    return result;
+  }
+
+  historyUp()   { if (this._histIdx > 0) this._histIdx--; return this._history[this._histIdx] || ""; }
+  historyDown() { if (this._histIdx < this._history.length) this._histIdx++; return this._history[this._histIdx] || ""; }
+  close()       { this.running = false; this.emit("close"); }
+  prompt()      { return this._sh.env.PS1 || "$ "; }
+}
+
+// ===========================================================================
+// Main class: TeaF
+// ===========================================================================
+
+class TeaF extends EventEmitter {
+  /**
+   * @param {Object} opts
+   * @param {string} opts.label
+   * @param {number} opts.umask
+   * @param {string} opts.mode   - 'posix' (default) | 'win' | 'url'
+   * @param {number} opts.uid    - current uid for permission checks (0 = root)
+   * @param {number} opts.gid
+   * @param {boolean} opts.enforcePermissions
+   */
+  constructor(opts = {}) {
+    super();
+    this._db = null;
+    this._fds = new Map();
+    this._fdCounter = 3;
+    this._watchers = new Map();
+    this._mounts = new Map();
+    this._umask = opts.umask !== undefined ? opts.umask : 0o022;
+    this._uid   = opts.uid   !== undefined ? opts.uid   : 0;
+    this._gid   = opts.gid   !== undefined ? opts.gid   : 0;
+    this._enforcePerms = opts.enforcePermissions !== false; // default true
+    this._pathAdapter = new PathAdapter(opts.mode || "posix");
+    this._sh = null; // lazy-init shell
+    this._init(opts.label || "tea/f");
+  }
+
+  // -------------------------------------------------------------------------
+  // Internal bootstrap
+  // -------------------------------------------------------------------------
+
+  _init(label) {
+    const t = now();
+    this._db = {
+      meta: { created: t, label, version: VERSION },
+      tree: {
+        "/": { type: "dir", mode: 0o755, uid: 0, gid: 0, atime: t, mtime: t, ctime: t, nlink: 2, children: {} },
+      },
+      inodeCounter: 1,
+    };
+    // Create standard directories
+    for (const d of ["bin", "etc", "usr", "usr/bin", "usr/local", "usr/local/bin", "home", "root", "tmp", "var", "lib", "mnt", "proc", "dev"]) {
+      this._mkdirOne("/" + d, 0o755, ...this._parentAndBase("/" + d));
+    }
+  }
+
+  _parentAndBase(p) {
+    const { dir, base } = splitPath(p);
+    const parentId = this._resolve(dir);
+    return [parentId, base];
+  }
+
+  _newId() { this._db.inodeCounter++; return `node_${this._db.inodeCounter}`; }
+
+  // -------------------------------------------------------------------------
+  // Path translation (mode-aware)
+  // -------------------------------------------------------------------------
+
+  _p(path) {
+    const internal = this._pathAdapter.toInternal(path);
+    return normPath(internal);
+  }
+
+  _ext(path) { return this._pathAdapter.toExternal(path); }
+
+  // -------------------------------------------------------------------------
+  // Permission checking
+  // -------------------------------------------------------------------------
+
+  _checkPerm(node, need) {
+    if (!this._enforcePerms || this._uid === 0) return; // root bypasses
+    const mode = node.mode & 0o777;
+    let allowed = mode & 0o007; // other
+    if (node.gid === this._gid) allowed |= (mode >> 3) & 0o007;
+    if (node.uid === this._uid) allowed |= (mode >> 6) & 0o007;
+    // need: 4=read, 2=write, 1=exec
+    if ((allowed & need) !== need) throw err("EACCES");
+  }
+
+  _checkRead(node)  { this._checkPerm(node, 4); }
+  _checkWrite(node) { this._checkPerm(node, 2); }
+  _checkExec(node)  { this._checkPerm(node, 1); }
+
+  // -------------------------------------------------------------------------
+  // Node resolution
+  // -------------------------------------------------------------------------
+
+  _resolve(path, { followSymlinks = true, maxLinks = 40 } = {}) {
+    const p = normPath(typeof path === "string" ? path : "/");
+    if (p === "/") return "/";
+    const parts = p.split("/").filter(Boolean);
+    let cur = "/";
+    for (let i = 0; i < parts.length; i++) {
+      // Check for mount point at current position
+      const curPath = "/" + parts.slice(0, i).join("/") || "/";
+      if (this._mounts.has(curPath)) {
+        // Delegate to the mounted fs
+        const mounted = this._mounts.get(curPath);
+        const subPath = "/" + parts.slice(i).join("/");
+        return "__mount__:" + curPath + ":" + subPath;
+      }
+
+      const node = this._db.tree[cur];
+      if (!node) throw err("ENOENT", path);
+      if (node.type !== "dir") throw err("ENOTDIR", path);
+      this._checkExec(node);
+      const childId = node.children[parts[i]];
+      if (!childId) throw err("ENOENT", path);
+      const childNode = this._db.tree[childId];
+      if (!childNode) throw err("ENOENT", path);
+      if (childNode.type === "symlink" && (followSymlinks || i < parts.length - 1)) {
+        if (maxLinks <= 0) throw err("ELOOP", path);
+        const target = normPath(childNode.link.startsWith("/")
+          ? childNode.link
+          : "/" + parts.slice(0, i).join("/") + "/" + childNode.link);
+        cur = this._resolve(target, { followSymlinks: true, maxLinks: maxLinks - 1 });
+      } else {
+        cur = childId;
+      }
+    }
+    return cur;
+  }
+
+  _isMountRef(id) { return typeof id === "string" && id.startsWith("__mount__:"); }
+
+  _mountedOp(id, method, args) {
+    const [, mountPath, subPath] = id.split(":");
+    const mountedFs = this._mounts.get(mountPath);
+    if (!mountedFs) throw err("ENOENT");
+    return mountedFs[method](subPath, ...args);
+  }
+
+  _node(nodeId) { return this._db.tree[nodeId]; }
+
+  _getNode(path, opts) {
+    const normP = this._p(path);
+    const id = this._resolve(normP, opts);
+    if (this._isMountRef(id)) {
+      const [, , subPath] = id.split(":");
+      const [, mountPath] = id.split(":");
+      const mountedFs = this._mounts.get(mountPath);
+      return { id, node: { type: "mount", _fs: mountedFs, _sub: subPath } };
+    }
+    const node = this._db.tree[id];
+    if (!node) throw err("ENOENT", path);
+    return { id, node };
+  }
+
+  _touch(nodeId, fields = ["atime", "mtime", "ctime"]) {
+    if (this._isMountRef(nodeId)) return;
+    const n = now();
+    const node = this._db.tree[nodeId];
+    if (!node) return;
+    for (const f of fields) node[f] = n;
+  }
+
+  // -------------------------------------------------------------------------
+  // Watcher notification (real events)
+  // -------------------------------------------------------------------------
+
+  _notify(nodeId, eventType, filePath) {
+    for (const [, w] of this._watchers) {
+      // Check if this nodeId matches watcher's watched node or is a descendant
+      const matches = (w.id === nodeId) || this._isDescendantById(nodeId, w.id);
+      if (matches) {
+        try { w.emitter.emit(eventType, eventType, filePath || w.path); } catch(_) {}
+        if (w.listener) try { w.listener(eventType, filePath || w.path); } catch(_) {}
+      }
+    }
+    // Also fire top-level FS events
+    this.emit(eventType, filePath || nodeId);
+  }
+
+  _isDescendantById(childId, ancestorId) {
+    if (childId === ancestorId) return false;
+    // Walk all dirs to see if ancestorId is a parent
+    const ancestorNode = this._db.tree[ancestorId];
+    if (!ancestorNode || ancestorNode.type !== "dir") return false;
+    for (const cid of Object.values(ancestorNode.children)) {
+      if (cid === childId) return true;
+      if (this._isDescendantById(childId, cid)) return true;
+    }
+    return false;
+  }
+
+  // -------------------------------------------------------------------------
+  // Path utilities
+  // -------------------------------------------------------------------------
+
+  join(...parts)        { return this._ext(normPath(parts.map(p => this._p(p)).join("/"))); }
+  resolve(...parts)     { return this._ext(normPath(parts.map(p => this._p(p)).join("/"))); }
+  dirname(path)         { return this._ext(splitPath(this._p(path)).dir); }
+  basename(path, ext) {
+    let b = splitPath(this._p(path)).base || "/";
+    if (ext && b.endsWith(ext)) b = b.slice(0, -ext.length);
+    return b;
+  }
+  extname(path) { const b = this.basename(path); const dot = b.lastIndexOf("."); return dot > 0 ? b.slice(dot) : ""; }
+  relative(from, to) {
+    const f = this._p(from).split("/").filter(Boolean);
+    const t = this._p(to).split("/").filter(Boolean);
+    let i = 0;
+    while (i < f.length && i < t.length && f[i] === t[i]) i++;
+    return [...f.slice(i).map(() => ".."), ...t.slice(i)].join("/") || ".";
+  }
+
+  // -------------------------------------------------------------------------
+  // exists / access / stat
+  // -------------------------------------------------------------------------
+
+  exists(path) { try { this._resolve(this._p(path)); return true; } catch(_) { return false; } }
+
+  access(path, mode = 0) {
+    const { node } = this._getNode(path);
+    if (mode !== 0) this._checkPerm(node, mode);
+    return true;
+  }
+
+  stat(path) {
+    const p = this._p(path);
+    const { id, node } = this._getNode(p, { followSymlinks: true });
+    if (node.type === "mount") return node._fs.stat(node._sub);
+    this._checkRead(node);
+    this._touch(id, ["atime"]);
+    return new Stats(node, id);
+  }
+
+  lstat(path) {
+    const p = this._p(path);
+    const { id, node } = this._getNode(p, { followSymlinks: false });
+    if (node.type === "mount") return node._fs.lstat(node._sub);
+    return new Stats(node, id);
+  }
+
+  fstat(fd) {
+    const handle = this._fds.get(fd);
+    if (!handle) throw err("EBADF");
+    const node = this._db.tree[handle.nodeId];
+    if (!node) throw err("EBADF");
+    return new Stats(node, handle.nodeId);
+  }
+
+  // -------------------------------------------------------------------------
+  // mkdir / rmdir / readdir
+  // -------------------------------------------------------------------------
+
+  mkdir(path, opts = {}) {
+    const mode      = (typeof opts === "number" ? opts : (opts.mode || (0o777 & ~this._umask)));
+    const recursive = opts.recursive || false;
+    const p = this._p(path);
+
+    if (recursive) {
+      const parts = p.split("/").filter(Boolean);
+      let cur = "/";
+      for (let i = 0; i < parts.length; i++) {
+        const parentNode = this._db.tree[cur];
+        if (!parentNode.children[parts[i]]) {
+          const partial = "/" + parts.slice(0, i + 1).join("/");
+          const { dir: pdir, base: pbase } = splitPath(partial);
+          const parentId = this._resolve(pdir);
+          this._mkdirOne(partial, mode, parentId, pbase);
+        }
+        cur = this._db.tree[cur].children[parts[i]];
+      }
+      return;
+    }
+
+    const { dir, base } = splitPath(p);
+    if (!base) throw err("EEXIST", path);
+    const { id: parentId, node: parentNode } = this._getNode(dir, { followSymlinks: true });
+    if (parentNode.type !== "dir") throw err("ENOTDIR", dir);
+    this._checkWrite(parentNode);
+    if (parentNode.children[base]) throw err("EEXIST", path);
+    this._mkdirOne(p, mode, parentId, base);
+  }
+
+  _mkdirOne(path, mode, parentId, base) {
+    const t = now();
+    const id = this._newId();
+    this._db.tree[id] = { type: "dir", mode, uid: this._uid, gid: this._gid, atime: t, mtime: t, ctime: t, nlink: 2, children: {} };
+    this._db.tree[parentId].children[base] = id;
+    this._touch(parentId, ["mtime", "ctime"]);
+    this._notify(id, "mkdir", path);
+  }
+
+  rmdir(path, opts = {}) {
+    const p = this._p(path);
+    const { id, node } = this._getNode(p, { followSymlinks: true });
+    if (node.type !== "dir") throw err("ENOTDIR", path);
+    if (opts.recursive) { this._rmRecursive(p); return; }
+    if (Object.keys(node.children).length > 0) throw err("ENOTEMPTY", path);
+    const { dir, base } = splitPath(p);
+    const { id: parentId, node: parentNode } = this._getNode(dir);
+    this._checkWrite(parentNode);
+    delete this._db.tree[parentId].children[base];
+    delete this._db.tree[id];
+    this._touch(parentId, ["mtime", "ctime"]);
+    this._notify(parentId, "rmdir", path);
+  }
+
+  readdir(path, opts = {}) {
+    const { id, node } = this._getNode(path, { followSymlinks: true });
+    if (node.type === "mount") return node._fs.readdir(node._sub, opts);
+    if (node.type !== "dir") throw err("ENOTDIR", path);
+    this._checkRead(node);
+    this._touch(id, ["atime"]);
+    const names = Object.keys(node.children);
+    if (opts.withFileTypes) {
+      return names.map(name => ({
+        name,
+        isFile:        () => this._db.tree[node.children[name]]?.type === "file",
+        isDirectory:   () => this._db.tree[node.children[name]]?.type === "dir",
+        isSymbolicLink:() => this._db.tree[node.children[name]]?.type === "symlink",
+      }));
+    }
+    return names;
+  }
+
+  // -------------------------------------------------------------------------
+  // readFile / writeFile / appendFile / truncate
+  // -------------------------------------------------------------------------
+
+  readFile(path, opts = {}) {
+    const encoding = typeof opts === "string" ? opts : opts.encoding;
+    const { id, node } = this._getNode(path, { followSymlinks: true });
+    if (node.type === "mount") return node._fs.readFile(node._sub, opts);
+    if (node.type === "dir") throw err("EISDIR", path);
+    this._checkRead(node);
+    this._touch(id, ["atime"]);
+    const data = node.data || "";
+    return encoding ? data : (typeof Buffer !== "undefined" ? Buffer.from(data) : data);
+  }
+
+  writeFile(path, data, opts = {}) {
+    const mode  = typeof opts === "object" ? (opts.mode || (0o666 & ~this._umask)) : (0o666 & ~this._umask);
+    const flag  = typeof opts === "object" ? (opts.flag || "w") : "w";
+    const p = this._p(path);
+    const str = (data !== null && data !== undefined)
+      ? (typeof data === "object" && data.toString ? data.toString() : String(data))
+      : "";
+
+    let id, node;
+    try {
+      ({ id, node } = this._getNode(p, { followSymlinks: true }));
+      if (node.type === "mount") { node._fs.writeFile(node._sub, data, opts); return; }
+      if (node.type === "dir") throw err("EISDIR", path);
+      if (flag === "wx" || flag === "ax") throw err("EEXIST", path);
+      this._checkWrite(node);
+    } catch(e) {
+      if (e.code !== "ENOENT") throw e;
+      const { dir, base } = splitPath(p);
+      const { id: parentId, node: parentNode } = this._getNode(dir, { followSymlinks: true });
+      if (parentNode.type !== "dir") throw err("ENOTDIR", dir);
+      this._checkWrite(parentNode);
+      id = this._newId();
+      const t = now();
+      this._db.tree[id] = { type: "file", mode, uid: this._uid, gid: this._gid, atime: t, mtime: t, ctime: t, nlink: 1, data: "" };
+      this._db.tree[parentId].children[base] = id;
+      this._touch(parentId, ["mtime", "ctime"]);
+      node = this._db.tree[id];
+    }
+
+    node.data = (flag === "a" || flag === "ax") ? (node.data || "") + str : str;
+    this._touch(id, ["mtime", "ctime"]);
+    this._notify(id, "write", p);
+  }
+
+  appendFile(path, data, opts = {}) {
+    const o = typeof opts === "string" ? { encoding: opts } : opts;
+    this.writeFile(path, data, { ...o, flag: "a" });
+  }
+
+  truncate(path, len = 0) {
+    const { id, node } = this._getNode(path, { followSymlinks: true });
+    if (node.type !== "file") throw err("EINVAL", path);
+    this._checkWrite(node);
+    const d = node.data || "";
+    node.data = d.length >= len ? d.slice(0, len) : d.padEnd(len, "\0");
+    this._touch(id, ["mtime", "ctime"]);
+  }
+
+  ftruncate(fd, len = 0) {
+    const handle = this._fds.get(fd);
+    if (!handle) throw err("EBADF");
+    const node = this._db.tree[handle.nodeId];
+    if (!node || node.type !== "file") throw err("EBADF");
+    if (!handle.writable) throw err("EBADF");
+    const d = node.data || "";
+    node.data = d.length >= len ? d.slice(0, len) : d.padEnd(len, "\0");
+    this._touch(handle.nodeId, ["mtime", "ctime"]);
+  }
+
+  // -------------------------------------------------------------------------
+  // rename / unlink / rm
+  // -------------------------------------------------------------------------
+
+  rename(src, dst) {
+    const sp = this._p(src); const dp = this._p(dst);
+    if (sp === dp) return;
+    const { id: srcId } = this._getNode(sp, { followSymlinks: false });
+    const { dir: srcDir, base: srcBase } = splitPath(sp);
+    const { dir: dstDir, base: dstBase } = splitPath(dp);
+    const { id: srcParentId, node: srcParentNode } = this._getNode(srcDir);
+    this._checkWrite(srcParentNode);
+    const { id: dstParentId, node: dstParentNode } = this._getNode(dstDir);
+    this._checkWrite(dstParentNode);
+    if (dstParentNode.type !== "dir") throw err("ENOTDIR", dstDir);
+    if (dstParentNode.children[dstBase]) {
+      const existId = dstParentNode.children[dstBase];
+      const existNode = this._db.tree[existId];
+      if (existNode.type === "dir" && Object.keys(existNode.children).length > 0) throw err("ENOTEMPTY", dst);
+      if (existNode.type === "dir" && this._db.tree[srcId].type !== "dir") throw err("EISDIR", dst);
+      delete this._db.tree[existId];
+    }
+    dstParentNode.children[dstBase] = srcId;
+    delete this._db.tree[srcParentId].children[srcBase];
+    this._touch(srcParentId, ["mtime", "ctime"]);
+    this._touch(dstParentId, ["mtime", "ctime"]);
+    this._touch(srcId, ["ctime"]);
+    this._notify(srcId, "rename", dp);
+  }
+
+  unlink(path) {
+    const p = this._p(path);
+    const { id, node } = this._getNode(p, { followSymlinks: false });
+    if (node.type === "dir") throw err("EISDIR", path);
+    const { dir, base } = splitPath(p);
+    const { id: parentId, node: parentNode } = this._getNode(dir);
+    this._checkWrite(parentNode);
+    node.nlink = (node.nlink || 1) - 1;
+    delete this._db.tree[parentId].children[base];
+    if (node.nlink <= 0) delete this._db.tree[id];
+    this._touch(parentId, ["mtime", "ctime"]);
+    this._notify(parentId, "unlink", p);
+  }
+
+  rm(path, opts = {}) {
+    const p = this._p(path);
+    try {
+      const { node } = this._getNode(p, { followSymlinks: false });
+      if (node.type === "dir") {
+        if (!opts.recursive) throw err("EISDIR", path);
+        this._rmRecursive(p);
+      } else {
+        this.unlink(p);
+      }
+    } catch(e) {
+      if (opts.force && e.code === "ENOENT") return;
+      throw e;
+    }
+  }
+
+  _rmRecursive(path) {
+    const p = normPath(path);
+    const { id, node } = this._getNode(p, { followSymlinks: false });
+    if (node.type === "dir") {
+      for (const child of Object.keys(node.children))
+        this._rmRecursive(p === "/" ? "/" + child : p + "/" + child);
+      if (p !== "/") {
+        const { dir, base } = splitPath(p);
+        const { id: parentId } = this._getNode(dir);
+        delete this._db.tree[parentId].children[base];
+        delete this._db.tree[id];
+        this._touch(parentId, ["mtime", "ctime"]);
+      }
+    } else {
+      this.unlink(p);
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Links
+  // -------------------------------------------------------------------------
+
+  link(existingPath, newPath) {
+    const { id } = this._getNode(existingPath, { followSymlinks: true });
+    const node = this._db.tree[id];
+    if (node.type === "dir") throw err("EPERM", existingPath);
+    const dp = this._p(newPath);
+    const { dir, base } = splitPath(dp);
+    const { id: parentId, node: parentNode } = this._getNode(dir);
+    this._checkWrite(parentNode);
+    if (parentNode.type !== "dir") throw err("ENOTDIR", dir);
+    if (parentNode.children[base]) throw err("EEXIST", newPath);
+    parentNode.children[base] = id;
+    node.nlink = (node.nlink || 1) + 1;
+    this._touch(id, ["ctime"]);
+    this._touch(parentId, ["mtime", "ctime"]);
+  }
+
+  symlink(target, path) {
+    const p = this._p(path);
+    const { dir, base } = splitPath(p);
+    const { id: parentId, node: parentNode } = this._getNode(dir);
+    this._checkWrite(parentNode);
+    if (parentNode.type !== "dir") throw err("ENOTDIR", dir);
+    if (parentNode.children[base]) throw err("EEXIST", path);
+    const t = now();
+    const id = this._newId();
+    this._db.tree[id] = { type: "symlink", mode: 0o777, uid: this._uid, gid: this._gid, atime: t, mtime: t, ctime: t, nlink: 1, link: target };
+    parentNode.children[base] = id;
+    this._touch(parentId, ["mtime", "ctime"]);
+  }
+
+  readlink(path) {
+    const { node } = this._getNode(path, { followSymlinks: false });
+    if (node.type !== "symlink") throw err("EINVAL", path);
+    return node.link;
+  }
+
+  realpath(path) { return this._ext(normPath(this._p(path))); }
+
+  // -------------------------------------------------------------------------
+  // Permissions / ownership / timestamps
+  // -------------------------------------------------------------------------
+
+  chmod(path, mode) {
+    const { id, node } = this._getNode(path, { followSymlinks: true });
+    if (this._enforcePerms && this._uid !== 0 && node.uid !== this._uid) throw err("EPERM", path);
+    node.mode = mode;
+    this._touch(id, ["ctime"]);
+  }
+  lchmod(path, mode) {
+    const { id, node } = this._getNode(path, { followSymlinks: false });
+    if (this._enforcePerms && this._uid !== 0 && node.uid !== this._uid) throw err("EPERM", path);
+    node.mode = mode; this._touch(id, ["ctime"]);
+  }
+  fchmod(fd, mode) {
+    const handle = this._fds.get(fd);
+    if (!handle) throw err("EBADF");
+    const node = this._db.tree[handle.nodeId];
+    if (!node) throw err("EBADF");
+    if (this._enforcePerms && this._uid !== 0 && node.uid !== this._uid) throw err("EPERM");
+    node.mode = mode; this._touch(handle.nodeId, ["ctime"]);
+  }
+
+  chown(path, uid, gid) {
+    const { id, node } = this._getNode(path, { followSymlinks: true });
+    if (this._enforcePerms && this._uid !== 0) throw err("EPERM", path);
+    node.uid = uid; node.gid = gid; this._touch(id, ["ctime"]);
+  }
+  lchown(path, uid, gid) {
+    const { id, node } = this._getNode(path, { followSymlinks: false });
+    if (this._enforcePerms && this._uid !== 0) throw err("EPERM", path);
+    node.uid = uid; node.gid = gid; this._touch(id, ["ctime"]);
+  }
+  fchown(fd, uid, gid) {
+    const handle = this._fds.get(fd);
+    if (!handle) throw err("EBADF");
+    const node = this._db.tree[handle.nodeId];
+    if (!node) throw err("EBADF");
+    if (this._enforcePerms && this._uid !== 0) throw err("EPERM");
+    node.uid = uid; node.gid = gid; this._touch(handle.nodeId, ["ctime"]);
+  }
+
+  utimes(path, atime, mtime) {
+    const { id, node } = this._getNode(path, { followSymlinks: true });
+    this._checkWrite(node);
+    node.atime = new Date(atime).toISOString();
+    node.mtime = new Date(mtime).toISOString();
+    node.ctime = now();
+  }
+
+  // -------------------------------------------------------------------------
+  // File descriptors
+  // -------------------------------------------------------------------------
+
+  open(path, flags, mode) {
+    const p = this._p(path);
+    const flagStr  = typeof flags === "string" ? flags : String(flags);
+    const isCreate = flagStr.includes("w") || flagStr.includes("a") || (typeof flags === "number" && flags & O_CREAT);
+    const isExcl   = flagStr.includes("x") || (typeof flags === "number" && flags & O_EXCL);
+    const isAppend = flagStr.includes("a") || (typeof flags === "number" && flags & O_APPEND);
+    const isTrunc  = (flagStr.includes("w") && !isAppend) || (typeof flags === "number" && flags & O_TRUNC);
+    const isWrite  = flagStr.includes("w") || flagStr.includes("a") || flagStr.includes("+") || (typeof flags === "number" && (flags & (O_WRONLY | O_RDWR)));
+    const isRead   = !flagStr.includes("w") || flagStr.includes("+") || flagStr.includes("r") || (typeof flags === "number" && !(flags & O_WRONLY));
+
+    let nodeId;
+    try {
+      nodeId = this._resolve(p);
+      if (isExcl) throw err("EEXIST", path);
+      const node = this._db.tree[nodeId];
+      if (isRead)  this._checkRead(node);
+      if (isWrite) this._checkWrite(node);
+      if (isTrunc) { node.data = ""; this._touch(nodeId, ["mtime", "ctime"]); }
+    } catch(e) {
+      if (e.code !== "ENOENT" || !isCreate) throw e;
+      this.writeFile(p, "", { mode: mode || (0o666 & ~this._umask) });
+      nodeId = this._resolve(p);
+    }
+
+    const fd = this._fdCounter++;
+    this._fds.set(fd, {
+      nodeId, flags: flagStr,
+      pos: isAppend ? (this._db.tree[nodeId].data || "").length : 0,
+      readable: isRead, writable: isWrite, append: isAppend,
+    });
+    return fd;
+  }
+
+  close(fd) { if (!this._fds.has(fd)) throw err("EBADF"); this._fds.delete(fd); }
+
+  read(fd, buffer, offset = 0, length, position = null) {
+    const handle = this._fds.get(fd);
+    if (!handle || !handle.readable) throw err("EBADF");
+    const node = this._db.tree[handle.nodeId];
+    if (!node || node.type !== "file") throw err("EBADF");
+    const len = length !== undefined ? length : (buffer ? buffer.length : 0);
+    const pos = position !== null ? position : handle.pos;
+    const data = node.data || "";
+    const chunk = data.slice(pos, pos + len);
+    const bytesRead = chunk.length;
+    if (typeof buffer === "object" && buffer !== null && !Array.isArray(buffer)) {
+      for (let i = 0; i < bytesRead; i++) buffer[offset + i] = chunk.charCodeAt(i);
+    }
+    if (position === null) handle.pos += bytesRead;
+    this._touch(handle.nodeId, ["atime"]);
+    return { bytesRead, buffer: chunk };
+  }
+
+  write(fd, buffer, offset = 0, length, position = null) {
+    const handle = this._fds.get(fd);
+    if (!handle || !handle.writable) throw err("EBADF");
+    const node = this._db.tree[handle.nodeId];
+    if (!node || node.type !== "file") throw err("EBADF");
+    const str = typeof buffer === "string"
+      ? buffer.slice(offset, length != null ? offset + length : undefined)
+      : (typeof buffer === "object" && buffer.toString ? buffer.toString().slice(offset, length != null ? offset + length : undefined) : String(buffer));
+    const pos = handle.append ? (node.data || "").length : (position !== null ? position : handle.pos);
+    const d = node.data || "";
+    node.data = d.slice(0, pos) + str + d.slice(pos + str.length);
+    const bytesWritten = str.length;
+    if (!handle.append && position === null) handle.pos += bytesWritten;
+    this._touch(handle.nodeId, ["mtime", "ctime"]);
+    this._notify(handle.nodeId, "write", null);
+    return { bytesWritten };
+  }
+
+  fsync(fd)     { if (!this._fds.has(fd)) throw err("EBADF"); }
+  fdatasync(fd) { if (!this._fds.has(fd)) throw err("EBADF"); }
+
+  // -------------------------------------------------------------------------
+  // Streams
+  // -------------------------------------------------------------------------
+
+  createReadStream(path, opts = {}) {
+    const self = this; const em = new EventEmitter();
+    const start = opts.start || 0; const end = opts.end;
+    em.pipe = (dest) => {
+      try {
+        const { node } = self._getNode(path, { followSymlinks: true });
+        if (node.type !== "file") { em.emit("error", err("EISDIR", path)); return dest; }
+        const data = (node.data || "").slice(start, end != null ? end + 1 : undefined);
+        em.emit("data", data); em.emit("end");
+        if (dest && typeof dest.write === "function") dest.write(data);
+      } catch(e) { em.emit("error", e); }
+      return dest;
+    };
+    setTimeout(() => em.pipe(null), 0);
+    return em;
+  }
+
+  createWriteStream(path, opts = {}) {
+    const self = this; const flag = opts.flags || "w"; const em = new EventEmitter();
+    em.write = (chunk) => { self.appendFile(path, chunk); return true; };
+    em.end   = (chunk) => { if (chunk) em.write(chunk); em.emit("finish"); em.emit("close"); };
+    if (flag === "w") try { self.writeFile(path, "", opts); } catch(_) {}
+    return em;
+  }
+
+  // -------------------------------------------------------------------------
+  // copyFile / cp
+  // -------------------------------------------------------------------------
+
+  copyFile(src, dst, flags = 0) {
+    const excl = flags & COPYFILE_EXCL;
+    if (excl && this.exists(dst)) throw err("EEXIST", dst);
+    const { node: srcNode } = this._getNode(src, { followSymlinks: true });
+    this._checkRead(srcNode);
+    if (srcNode.type === "dir") throw err("EISDIR", src);
+    this.writeFile(dst, srcNode.data || "");
+  }
+
+  cp(src, dst, opts = {}) {
+    const sp = this._p(src); const dp = this._p(dst);
+    const { node: srcNode } = this._getNode(sp, { followSymlinks: true });
+    if (srcNode.type === "file") { this.copyFile(sp, dp, opts.errorOnExist ? COPYFILE_EXCL : 0); return; }
+    if (srcNode.type === "dir") {
+      if (!opts.recursive) throw err("EISDIR", src);
+      if (!this.exists(dp)) this.mkdir(dp, { recursive: true });
+      for (const child of Object.keys(srcNode.children)) this.cp(`${sp}/${child}`, `${dp}/${child}`, opts);
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Watchers (real EventEmitter-based with actual events)
+  // -------------------------------------------------------------------------
+
+  watch(path, opts = {}, listener) {
+    if (typeof opts === "function") { listener = opts; opts = {}; }
+    const p = this._p(path);
+    const id = this._resolve(p);
+    const watcher = new EventEmitter();
+    const key = Symbol();
+    this._watchers.set(key, { id, path: p, emitter: watcher, listener: listener || null });
+    watcher.close = () => { this._watchers.delete(key); watcher.emit("close"); };
+    return watcher;
+  }
+
+  watchFile(path, opts = {}, listener) {
+    if (typeof opts === "function") { listener = opts; opts = {}; }
+    const p = this._p(path);
+    let lastStat;
+    try { lastStat = this.stat(p); } catch(_) { lastStat = null; }
+    const key = Symbol();
+    const watcher = { path: p, listener: listener || (() => {}), stop: () => this._watchers.delete(key), id: null, emitter: new EventEmitter() };
+    // Hook into notify
+    this._watchers.set(key, watcher);
+    return { stop: watcher.stop };
+  }
+
+  unwatchFile(path) {
+    const p = this._p(path);
+    for (const [k, v] of this._watchers) { if (v.path === p) this._watchers.delete(k); }
+  }
+
+  // -------------------------------------------------------------------------
+  // Glob / find
+  // -------------------------------------------------------------------------
+
+  glob(pattern, opts = {}) {
+    const root = normPath(this._p(opts.cwd || "/"));
+    const results = [];
+    const search = (dir) => {
+      let node;
+      try { ({ node } = this._getNode(dir, { followSymlinks: true })); } catch(_) { return; }
+      if (node.type !== "dir") return;
+      for (const child of Object.keys(node.children)) {
+        const childPath = dir === "/" ? "/" + child : dir + "/" + child;
+        const rel = this.relative(root, childPath);
+        if (matchGlob(pattern, rel) || matchGlob(pattern, child)) results.push(this._ext(childPath));
+        search(childPath);
+      }
+    };
+    search(root);
+    return results;
+  }
+
+  find(path, opts = {}) {
+    const results = [];
+    const typeFilter = opts.type; const nameFilter = opts.name;
+    const search = (p) => {
+      let node;
+      try { ({ node } = this._getNode(p, { followSymlinks: false })); } catch(_) { return; }
+      const typeMatch = !typeFilter || (typeFilter === "f" && node.type === "file") || (typeFilter === "d" && node.type === "dir") || (typeFilter === "l" && node.type === "symlink");
+      const nameMatch = !nameFilter || matchGlob(nameFilter, this.basename(p));
+      if (typeMatch && nameMatch) results.push(this._ext(p));
+      if (node.type === "dir") {
+        for (const child of Object.keys(node.children)) search(p === "/" ? "/" + child : p + "/" + child);
+      }
+    };
+    search(normPath(this._p(path)));
+    return results;
+  }
+
+  // -------------------------------------------------------------------------
+  // df / du / tree
+  // -------------------------------------------------------------------------
+
+  df() {
+    let files = 0, dirs = 0, symlinks = 0, totalBytes = 0;
+    for (const [, node] of Object.entries(this._db.tree)) {
+      if (node.type === "file")    { files++;    totalBytes += (node.data || "").length; }
+      if (node.type === "dir")     dirs++;
+      if (node.type === "symlink") symlinks++;
+    }
+    return { files, dirs, symlinks, totalBytes, nodes: Object.keys(this._db.tree).length };
+  }
+
+  du(path) {
+    const p = normPath(this._p(path));
+    let bytes = 0;
+    const measure = (pt) => {
+      let node;
+      try { ({ node } = this._getNode(pt, { followSymlinks: false })); } catch(_) { return; }
+      if (node.type === "file") bytes += (node.data || "").length;
+      if (node.type === "dir") for (const child of Object.keys(node.children)) measure(pt === "/" ? "/" + child : pt + "/" + child);
+    };
+    measure(p);
+    return bytes;
+  }
+
+  tree(path = "/", opts = {}) {
+    const indent  = opts._indent || "";
+    const isLast  = opts._isLast !== false;
+    const p = normPath(this._p(path));
+    const name    = this.basename(p) || "/";
+    const connector = indent === "" ? "" : (isLast ? "└── " : "├── ");
+    let out = indent + connector + name + "\n";
+    let node;
+    try { ({ node } = this._getNode(p, { followSymlinks: false })); } catch(_) { return out; }
+    if (node.type === "symlink") return indent + connector + name + " -> " + node.link + "\n";
+    if (node.type === "dir") {
+      const children = Object.keys(node.children);
+      children.forEach((child, i) => {
+        const childPath = p === "/" ? "/" + child : p + "/" + child;
+        const last = i === children.length - 1;
+        const newIndent = indent + (isLast || indent === "" ? "    " : "│   ");
+        out += this.tree(childPath, { _indent: newIndent, _isLast: last });
+      });
+    }
+    return out;
+  }
+
+  // -------------------------------------------------------------------------
+  // Mount / unmount  (properly appends into /mnt/)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Mount another TeaF instance at path (defaults to /mnt/<label>).
+   * Handles duplicate-segment collisions by appending a counter.
+   * Always creates mount point inside /mnt/ if a relative name is given.
+   */
+  mount(mountPath, otherTF) {
+    if (!(otherTF instanceof TeaF)) throw new Error("mount: must provide another TeaF instance");
+    let p;
+    if (mountPath.startsWith("/")) {
+      p = normPath(mountPath);
+    } else {
+      // Treat as a name inside /mnt/
+      // Avoid collision with existing /mnt/ children
+      const mntNode = this._db.tree[this._resolve("/mnt")];
+      let name = mountPath;
+      let counter = 0;
+      while (mntNode && mntNode.children[name]) {
+        counter++;
+        name = mountPath + "_" + counter;
+      }
+      p = "/mnt/" + name;
+    }
+
+    // Ensure path exists
+    if (!this.exists(p)) this.mkdir(p, { recursive: true });
+    this._mounts.set(p, otherTF);
+    this.emit("mount", p);
+    return p;
+  }
+
+  unmount(path) {
+    const p = path.startsWith("/") ? normPath(path) : "/mnt/" + path;
+    if (!this._mounts.has(p)) throw new Error("unmount: not a mount point: " + p);
+    this._mounts.delete(p);
+    this.emit("unmount", p);
+  }
+
+  // -------------------------------------------------------------------------
+  // exec — run sh command/script in this FS
+  // -------------------------------------------------------------------------
+
+  /**
+   * Execute a shell command string in this filesystem.
+   * @param {string} cmd - command or sh script
+   * @param {Object} opts - { env, stdin, cwd, uid, gid }
+   * @returns {{ stdout: string, stderr: string, code: number }}
+   */
+  exec(cmd, opts = {}) {
+    if (!this._sh) {
+      this._sh = new Sh(this, { uid: this._uid, gid: this._gid });
+    }
+    if (opts.env) Object.assign(this._sh.env, opts.env);
+    if (opts.cwd) this._sh.env.PWD = normPath(this._p(opts.cwd));
+    if (opts.uid !== undefined) this._sh._uid = opts.uid;
+    if (opts.gid !== undefined) this._sh._gid = opts.gid;
+    return this._sh.exec(cmd, { stdin: opts.stdin || [], stdout: opts.stdout, stderr: opts.stderr });
+  }
+
+  /** Get or create the shell instance */
+  get sh() {
+    if (!this._sh) this._sh = new Sh(this, { uid: this._uid, gid: this._gid });
+    return this._sh;
+  }
+
+  /**
+   * Create an interactive REPL session for this FS.
+   * @returns {ShRepl}
+   */
+  repl(opts = {}) {
+    const sh = new Sh(this, { uid: this._uid, gid: this._gid, env: opts.env });
+    return new ShRepl(sh);
+  }
+
+  // -------------------------------------------------------------------------
+  // TeaBin helpers (install binary onto filesystem)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Assemble TeaBin source and install as an executable at path.
+   * @param {string} path - e.g. "/bin/hello"
+   * @param {string} src  - assembly source
+   */
+  installBin(path, src) {
+    const bytes = TeaBinVM.assemble(src);
+    // Store as a binary string in the file
+    let str = "";
+    for (let i = 0; i < bytes.length; i++) str += String.fromCharCode(bytes[i]);
+    this.writeFile(path, str);
+    this.chmod(path, 0o755);
+  }
+
+  /**
+   * Run a TeaBin binary file from the filesystem.
+   * @param {string} path
+   * @param {Object} opts - { ports, interrupts, maxCycles }
+   * @returns {{ stdout: string, exitCode: number }}
+   */
+  runBin(path, opts = {}) {
+    const data = this.readFile(path, "utf8");
+    const bytes = new Uint8Array(data.length);
+    for (let i = 0; i < data.length; i++) bytes[i] = data.charCodeAt(i) & 0xFF;
+    const vm = new TeaBinVM(opts);
+    vm.load(bytes);
+    const exitCode = vm.run();
+    const stdout = vm.stdout.map(o => typeof o === "number" ? String.fromCharCode(o) : String(o)).join("");
+    return { stdout, exitCode };
+  }
+
+  // -------------------------------------------------------------------------
+  // JSON persistence  (snaps/ directory)
+  // -------------------------------------------------------------------------
+
+  toJSON() { return JSON.stringify(this._db, null, 2); }
+
+  fromJSON(json) {
+    const data = typeof json === "string" ? JSON.parse(json) : json;
+    if (!data.tree || !data.meta) throw new Error("Invalid tea/f snapshot");
+    this._db = data;
+    return this;
+  }
+
+  /**
+   * Save snapshot to ./snaps/<filename>.json  (Node.js only).
+   * @param {string} name - just the base name (no path needed), e.g. "my-fs"
+   *                        or a full path starting with /
+   */
+  saveSnapshot(name) {
+    if (typeof require === "undefined") throw new Error("saveSnapshot requires Node.js");
+    const fs   = require("fs");
+    const path = require("path");
+
+    let filePath;
+    if (name.startsWith("/") || name.includes("\\") || name.includes(":")) {
+      filePath = name; // absolute path given
+    } else {
+      // Ensure ./snaps/ exists
+      if (!fs.existsSync(SNAP_DIR)) fs.mkdirSync(SNAP_DIR, { recursive: true });
+      const base = name.endsWith(".json") ? name : name + ".json";
+      filePath = path.join(SNAP_DIR, base);
+    }
+    fs.writeFileSync(filePath, this.toJSON(), "utf8");
+    return filePath;
+  }
+
+  /** Alias kept for compatibility */
+  saveToFile(filePath) { return this.saveSnapshot(filePath); }
+
+  /**
+   * Load snapshot from ./snaps/<name>.json or an absolute path (Node.js only).
+   */
+  loadSnapshot(name) {
+    if (typeof require === "undefined") throw new Error("loadSnapshot requires Node.js");
+    const fs   = require("fs");
+    const path = require("path");
+    let filePath;
+    // If it looks like a full/relative OS path (contains path sep or starts with . or /), use as-is
+    if (name.startsWith("/") || name.startsWith("./") || name.startsWith("../") ||
+        name.includes("\\") || name.includes(":") || name.includes(path.sep)) {
+      filePath = name;
+    } else {
+      const base = name.endsWith(".json") ? name : name + ".json";
+      filePath = path.join(SNAP_DIR, base);
+    }
+    const json = fs.readFileSync(filePath, "utf8");
+    return this.fromJSON(json);
+  }
+
+  /** Alias */
+  loadFromFile(filePath) { return this.loadSnapshot(filePath); }
+
+  // -------------------------------------------------------------------------
+  // Async wrappers
+  // -------------------------------------------------------------------------
+
+  get promises() {
+    const wrap = (method) => (...args) => {
+      try { return Promise.resolve(this[method](...args)); }
+      catch(e) { return Promise.reject(e); }
+    };
+    return {
+      readFile: wrap("readFile"), writeFile: wrap("writeFile"),
+      appendFile: wrap("appendFile"), truncate: wrap("truncate"),
+      mkdir: wrap("mkdir"), rmdir: wrap("rmdir"), readdir: wrap("readdir"),
+      stat: wrap("stat"), lstat: wrap("lstat"), rename: wrap("rename"),
+      unlink: wrap("unlink"), rm: wrap("rm"), link: wrap("link"),
+      symlink: wrap("symlink"), readlink: wrap("readlink"), realpath: wrap("realpath"),
+      chmod: wrap("chmod"), lchmod: wrap("lchmod"), chown: wrap("chown"),
+      lchown: wrap("lchown"), utimes: wrap("utimes"), copyFile: wrap("copyFile"),
+      cp: wrap("cp"), open: wrap("open"), access: wrap("access"),
+      exec: wrap("exec"),
+    };
+  }
+}
+
+// ===========================================================================
+// Factory
+// ===========================================================================
+
+function createFS(opts) { return new TeaF(opts); }
+createFS.TeaF           = TeaF;
+createFS.Stats          = Stats;
+createFS.TFError        = TFError;
+createFS.TeaBinVM       = TeaBinVM;
+createFS.Sh             = Sh;
+createFS.ShRepl         = ShRepl;
+createFS.PathAdapter    = PathAdapter;
+createFS.COPYFILE_EXCL  = COPYFILE_EXCL;
+createFS.O_RDONLY       = O_RDONLY;
+createFS.O_WRONLY       = O_WRONLY;
+createFS.O_RDWR         = O_RDWR;
+createFS.O_CREAT        = O_CREAT;
+createFS.O_EXCL         = O_EXCL;
+createFS.O_TRUNC        = O_TRUNC;
+createFS.O_APPEND       = O_APPEND;
+createFS.OP             = OP;
+createFS.VERSION        = VERSION;
+
+if (typeof module !== "undefined" && module.exports) module.exports = { kitdef: createFS };
+if (typeof window !== "undefined") window.tf = createFS;
+
+// ===========================================================================
+// Self-test
+// ===========================================================================
+
+if (typeof process !== "undefined" && process.argv[1] && process.argv[1].endsWith("tea-f.js")) {
+  const tf = createFS({ label: "test-fs", enforcePermissions: false });
+  const assert = (cond, msg) => { if (!cond) throw new Error("FAIL: " + msg); };
+  console.log("=== tea's F v2 — self-test ===\n");
+
+  // mkdir / exists
+  tf.mkdir("/etc/config", { recursive: true }); // /etc pre-exists from _init
+  tf.mkdir("/usr/local/bin", { recursive: true });
+  assert(tf.exists("/etc/config"), "mkdir /etc/config");
+  assert(tf.exists("/usr/local/bin"), "mkdir recursive");
+  console.log("✓ mkdir + exists");
+
+  // writeFile / readFile
+  tf.writeFile("/etc/hosts", "127.0.0.1 localhost\n");
+  assert(tf.readFile("/etc/hosts", "utf8") === "127.0.0.1 localhost\n", "writeFile/readFile");
+  console.log("✓ writeFile / readFile");
+
+  // appendFile
+  tf.appendFile("/etc/hosts", "::1 localhost\n");
+  assert(tf.readFile("/etc/hosts", "utf8").includes("::1"), "appendFile");
+  console.log("✓ appendFile");
+
+  // watcher events
+  const watched = [];
+  const watcher = tf.watch("/etc");
+  watcher.on("write", (ev, f) => watched.push(ev));
+  tf.writeFile("/etc/test-watch", "hello");
+  assert(watched.length > 0, "watcher received event");
+  watcher.close();
+  console.log("✓ watcher real events");
+
+  // stat
+  const s = tf.stat("/etc/hosts");
+  assert(s.isFile(), "stat isFile");
+  assert(s.size > 0, "stat size");
+  console.log("✓ stat");
+
+  // symlink / readlink / lstat
+  tf.symlink("/etc/hosts", "/etc/hosts.bak");
+  const ls = tf.lstat("/etc/hosts.bak");
+  assert(ls.isSymbolicLink(), "lstat symlink");
+  assert(tf.readlink("/etc/hosts.bak") === "/etc/hosts", "readlink");
+  console.log("✓ symlink / readlink / lstat");
+
+  // hard link
+  tf.link("/etc/hosts", "/etc/hosts2");
+  assert(tf.readFile("/etc/hosts2", "utf8") === tf.readFile("/etc/hosts", "utf8"), "hard link");
+  console.log("✓ hard link");
+
+  // rename
+  tf.rename("/etc/hosts2", "/etc/hosts.old");
+  assert(!tf.exists("/etc/hosts2"), "rename src gone");
+  assert(tf.exists("/etc/hosts.old"), "rename dst exists");
+  console.log("✓ rename");
+
+  // unlink
+  tf.unlink("/etc/hosts.old");
+  assert(!tf.exists("/etc/hosts.old"), "unlink");
+  console.log("✓ unlink");
+
+  // readdir
+  const entries = tf.readdir("/etc");
+  assert(entries.includes("hosts"), "readdir includes hosts");
+  console.log("✓ readdir");
+
+  // chmod / chown
+  tf.chmod("/etc/hosts", 0o644);
+  assert(tf.stat("/etc/hosts").mode & 0o644, "chmod");
+  tf.chown("/etc/hosts", 1000, 1000);
+  assert(tf.stat("/etc/hosts").uid === 1000, "chown uid");
+  console.log("✓ chmod / chown");
+
+  // truncate
+  tf.truncate("/etc/hosts", 5);
+  assert(tf.readFile("/etc/hosts", "utf8").length === 5, "truncate");
+  console.log("✓ truncate");
+
+  // File descriptors
+  tf.writeFile("/tmp/test.txt", "hello world");
+  const fd = tf.open("/tmp/test.txt", "r");
+  const { bytesRead } = tf.read(fd, new Uint8Array(5), 0, 5, 0);
+  assert(bytesRead === 5, "read bytesRead");
+  tf.close(fd);
+  const fd2 = tf.open("/tmp/test2.txt", "w");
+  tf.write(fd2, "abc");
+  tf.close(fd2);
+  assert(tf.readFile("/tmp/test2.txt", "utf8") === "abc", "write via fd");
+  console.log("✓ open / read / write / close");
+
+  // copyFile / cp recursive
+  tf.writeFile("/etc/hosts", "127.0.0.1 localhost\n");
+  tf.copyFile("/etc/hosts", "/etc/hosts.copy");
+  assert(tf.exists("/etc/hosts.copy"), "copyFile");
+  tf.mkdir("/backup");
+  tf.cp("/etc", "/backup/etc", { recursive: true });
+  assert(tf.exists("/backup/etc/hosts"), "cp recursive");
+  tf.rm("/backup", { recursive: true });
+  assert(!tf.exists("/backup"), "rm recursive");
+  console.log("✓ copyFile / cp / rm");
+
+  // glob / find / path helpers
+  tf.writeFile("/usr/local/bin/node", "#!/usr/bin/env node\n");
+  tf.writeFile("/usr/local/bin/npm",  "#!/usr/bin/env node\n");
+  const hits = tf.glob("**/bin/*");
+  assert(hits.length >= 2, "glob **");
+  const found = tf.find("/usr", { type: "f" });
+  assert(found.length >= 2, "find type:f");
+  assert(tf.join("/usr", "local", "bin") === "/usr/local/bin", "join");
+  assert(tf.dirname("/usr/local/bin") === "/usr/local", "dirname");
+  assert(tf.basename("/usr/local/bin/node") === "node", "basename");
+  assert(tf.extname("/etc/hosts.copy") === ".copy", "extname");
+  assert(tf.relative("/usr", "/usr/local/bin") === "local/bin", "relative");
+  console.log("✓ glob / find / path helpers");
+
+  // df / du / tree
+  const dfStats = tf.df();
+  assert(dfStats.files > 0, "df files");
+  const usage = tf.du("/etc");
+  assert(usage >= 0, "du");
+  const treeStr = tf.tree("/");
+  assert(treeStr.includes("etc"), "tree includes etc");
+  console.log("✓ df / du / tree");
+
+  // Win mode
+  const tfWin = createFS({ mode: "win", label: "win-test" });
+  tfWin.mkdir("C:\\Users\\Alice", { recursive: true });
+  tfWin.writeFile("C:\\Users\\Alice\\notes.txt", "hello windows");
+  assert(tfWin.readFile("C:\\Users\\Alice\\notes.txt", "utf8") === "hello windows", "win mode");
+  console.log("✓ win mode (C:\\...)");
+
+  // URL mode
+  const tfUrl = createFS({ mode: "url", label: "url-test" });
+  tfUrl.mkdir("http://example.com/api/v1", { recursive: true });
+  tfUrl.writeFile("http://example.com/api/v1/data.json", '{"ok":true}');
+  assert(tfUrl.readFile("http://example.com/api/v1/data.json", "utf8") === '{"ok":true}', "url mode read");
+  console.log("✓ url mode (http://...)");
+
+  // Mount with /mnt/ appending and duplicate prevention
+  const tf2 = createFS({ label: "sub-fs" });
+  tf2.writeFile("/hello.txt", "from mounted fs");
+  const mountAt = tf.mount("sub", tf2);
+  assert(mountAt === "/mnt/sub", "mount path");
+  // Mount duplicate
+  const tf3 = createFS({ label: "sub-fs-2" });
+  const mountAt2 = tf.mount("sub", tf3);
+  assert(mountAt2 === "/mnt/sub_1", "mount collision resolved");
+  console.log("✓ mount (into /mnt/, collision-safe)");
+
+  // Shell exec
+  tf.writeFile("/etc/motd", "Welcome to tea/f!\n");
+  const r1 = tf.exec("cat /etc/motd");
+  assert(r1.stdout.includes("Welcome"), "exec cat");
+  const r2 = tf.exec("echo hello world");
+  assert(r2.stdout.trim() === "hello world", "exec echo");
+  const r3 = tf.exec("ls /etc");
+  assert(r3.stdout.includes("hosts"), "exec ls");
+  const r4 = tf.exec("echo foo > /tmp/redir.txt && cat /tmp/redir.txt");
+  assert(tf.readFile("/tmp/redir.txt", "utf8").trim() === "foo", "exec redirect");
+  const r5 = tf.exec("echo a | grep a");
+  assert(r5.stdout.trim() === "a", "exec pipe+grep");
+  console.log("✓ shell exec (cat, echo, ls, redirect, pipe)");
+
+  // REPL
+  const repl = tf.repl();
+  const res = repl.line("echo repl-works");
+  assert(res.stdout.trim() === "repl-works", "repl line");
+  repl.close();
+  console.log("✓ repl");
+
+  // TeaBin VM — assemble + run simple program
+  const asmSrc = `
+.code
+  MOV R0, 42
+  OUT 0, R0
+  HALT 0
+`;
+  const bytes = TeaBinVM.assemble(asmSrc);
+  const vm = new TeaBinVM();
+  vm.load(bytes);
+  vm.run();
+  assert(vm.stdout[0] === 42, "TeaBin VM OUT");
+  console.log("✓ TeaBin VM (assemble + run + OUT)");
+
+  // installBin + runBin
+  const helloBinSrc = `
+.data
+msg "Hi from bin!\n"
+.code
+  MOV R2, 0
+  MOV R3, 14
+  MOV R0, 1
+  INT 0x80
+  HALT 0
+`;
+  tf.installBin("/bin/hello", helloBinSrc);
+  assert(tf.exists("/bin/hello"), "installBin");
+  const binResult = tf.runBin("/bin/hello");
+  assert(binResult.stdout.includes("Hi"), "runBin stdout");
+  console.log("✓ installBin / runBin");
+
+  // JSON round-trip
+  const json = tf.toJSON();
+  const tf4 = createFS();
+  tf4.fromJSON(json);
+  assert(tf4.exists("/etc/hosts"), "JSON round-trip");
+  console.log("✓ toJSON / fromJSON");
+
+  // saveSnapshot / loadSnapshot
+  const snapPath = tf.saveSnapshot("test-snap");
+  const tf5 = createFS();
+  tf5.loadSnapshot(snapPath);
+  assert(tf5.exists("/usr/local/bin/node"), "loadSnapshot");
+  // Cleanup
+  try { require("fs").unlinkSync(snapPath); require("fs").rmdirSync(SNAP_DIR); } catch(_) {}
+  console.log("✓ saveSnapshot / loadSnapshot (./snaps/)");
+
+  // Permission enforcement
+  const tfPerms = createFS({ uid: 0, gid: 0, enforcePermissions: true });
+  // As root: create a home dir for uid 1000 and a secret file
+  tfPerms.mkdir("/home/alice", { recursive: true });
+  tfPerms.chown("/home/alice", 1000, 1000);
+  tfPerms.chmod("/home/alice", 0o700);
+  tfPerms.writeFile("/home/alice/secret.txt", "private");
+  tfPerms.chown("/home/alice/secret.txt", 1000, 1000);
+  tfPerms.chmod("/home/alice/secret.txt", 0o600);
+  // Now act as uid 1000 — owner can read
+  tfPerms._uid = 1000; tfPerms._gid = 1000;
+  try {
+    tfPerms.readFile("/home/alice/secret.txt", "utf8");
+    console.log("✓ permission: owner can read 0o600 file");
+  } catch(e) { throw new Error("FAIL: owner should read own file: " + e.message); }
+  // Act as uid 2000 — should be denied
+  tfPerms._uid = 2000; tfPerms._gid = 2000;
+  let denied = false;
+  try { tfPerms.readFile("/home/alice/secret.txt", "utf8"); }
+  catch(e) { denied = e.code === "EACCES"; }
+  assert(denied, "permission: other user denied reading 0o600 file");
+  console.log("✓ permission enforcement");
+
+  tf.promises.readFile("/usr/local/bin/node", "utf8").then(v => {
+    assert(v.includes("node"), "promises.readFile");
+    console.log("✓ promises API");
+    console.log("\n=== all tests passed ===\n");
+    console.log("Filesystem snapshot:\n");
+    console.log(tf.tree("/"));
+    console.log("df:", tf.df());
+  });
+}