typescript-virtual-container 1.5.11 → 1.6.0

package/dist/VirtualFileSystem/index.js

@@ -50,6 +50,12 @@ class VirtualFileSystem extends EventEmitter {
     mounts = new Map();
     /** Sorted mounts cache (longest-path-first). Rebuilt lazily on mount/unmount. */
     _sortedMounts = null;
+    /** Read hooks: path prefix → callback invoked before reading any file under that prefix. */
+    readHooks = new Map();
+    /** Sorted read hook prefixes (longest-first) for matching. */
+    _sortedReadHooks = null;
+    /** Re-entrancy guard for read hooks — prevents infinite loop when hook triggers another read. */
+    _inReadHook = false;
     /** True when running in a browser environment (no host FS access). */
     static isBrowser = typeof process === "undefined" || typeof process.versions?.node === "undefined";
     constructor(options = {}) {
@@ -85,12 +91,14 @@ class VirtualFileSystem extends EventEmitter {
         this.root = this.makeDir("", 0o755);
     }
     // ── Internal helpers ──────────────────────────────────────────────────────
-    makeDir(name, mode) {
+    makeDir(name, mode, uid = 0, gid = 0) {
         const now = Date.now();
         return {
             type: "directory",
             name,
             mode,
+            uid,
+            gid,
             createdAt: now,
             updatedAt: now,
             children: Object.create(null),
@@ -98,21 +106,23 @@ class VirtualFileSystem extends EventEmitter {
             _sortedKeys: null,
         };
     }
-    makeFile(name, content, mode, compressed) {
+    makeFile(name, content, mode, compressed, uid = 0, gid = 0) {
         const now = Date.now();
         return {
             type: "file",
             name,
             content,
             mode,
+            uid,
+            gid,
             compressed,
             createdAt: now,
             updatedAt: now,
         };
     }
-    makeStub(name, content, mode) {
+    makeStub(name, content, mode, uid = 0, gid = 0) {
         const now = Date.now();
-        return { type: "stub", name, stubContent: content, mode, createdAt: now, updatedAt: now };
+        return { type: "stub", name, stubContent: content, mode, uid, gid, createdAt: now, updatedAt: now };
     }
     /**
      * Write a lazy stub — stores content as a plain string with no Buffer allocation.
@@ -520,6 +530,43 @@ class VirtualFileSystem extends EventEmitter {
             vPath, ...opts,
         }));
     }
+    /**
+     * Register a callback that is invoked before any read under `prefix`.
+     * Used by /proc to refresh dynamic content on every access.
+     */
+    onBeforeRead(prefix, cb) {
+        const normalized = normalizePath(prefix);
+        this.readHooks.set(normalized, cb);
+        this._sortedReadHooks = [...this.readHooks.keys()].sort((a, b) => b.length - a.length);
+    }
+    /** Remove a previously registered read hook. */
+    offBeforeRead(prefix) {
+        const normalized = normalizePath(prefix);
+        this.readHooks.delete(normalized);
+        this._sortedReadHooks = [...this.readHooks.keys()].sort((a, b) => b.length - a.length);
+    }
+    /** Invoke any matching read hook for `normalizedPath`. */
+    _triggerReadHook(normalizedPath) {
+        if (this._inReadHook)
+            return;
+        if (!this._sortedReadHooks)
+            return;
+        for (const prefix of this._sortedReadHooks) {
+            if (normalizedPath === prefix || normalizedPath.startsWith(`${prefix}/`)) {
+                const cb = this.readHooks.get(prefix);
+                if (cb) {
+                    this._inReadHook = true;
+                    try {
+                        cb();
+                    }
+                    finally {
+                        this._inReadHook = false;
+                    }
+                    return;
+                }
+            }
+        }
+    }
     /**
      * If `targetPath` is inside a mount, return `{ hostPath, readOnly, relPath }`.
      * `relPath` is the path relative to the mount's host directory.
@@ -614,6 +661,7 @@ class VirtualFileSystem extends EventEmitter {
             return fsSync.readFileSync(m.fullHostPath, "utf8");
         }
         const normalized = normalizePath(targetPath);
+        this._triggerReadHook(normalized);
         const node = getNodeNormalized(this.root, normalized);
         if (node.type === "stub") {
             this.emit("file:read", { path: normalized, size: node.stubContent.length });
@@ -638,6 +686,7 @@ class VirtualFileSystem extends EventEmitter {
             return fsSync.readFileSync(m.fullHostPath);
         }
         const normalized = normalizePath(targetPath);
+        this._triggerReadHook(normalized);
         const node = getNodeNormalized(this.root, normalized);
         if (node.type === "stub") {
             const buf = Buffer.from(node.stubContent, "utf8");
@@ -659,8 +708,9 @@ class VirtualFileSystem extends EventEmitter {
         const m = this.resolveMount(targetPath);
         if (m)
             return fsSync.existsSync(m.fullHostPath);
+        const normalized = normalizePath(targetPath);
         try {
-            getNodeNormalized(this.root, normalizePath(targetPath));
+            getNodeNormalized(this.root, normalized);
             return true;
         }
         catch {
@@ -673,6 +723,51 @@ class VirtualFileSystem extends EventEmitter {
         getNodeNormalized(this.root, normalized).mode = mode;
         this._journal({ op: JournalOp.CHMOD, path: normalized, mode });
     }
+    /** Changes ownership (uid/gid) of a file or directory. */
+    chown(targetPath, uid, gid) {
+        const normalized = normalizePath(targetPath);
+        const node = getNodeNormalized(this.root, normalized);
+        node.uid = uid;
+        node.gid = gid;
+        this._journal({ op: JournalOp.CHMOD, path: normalized, mode: node.mode });
+    }
+    /** Returns the uid and gid of a node. */
+    getOwner(targetPath) {
+        const node = getNodeNormalized(this.root, normalizePath(targetPath));
+        return { uid: node.uid, gid: node.gid };
+    }
+    /**
+     * POSIX-style access check: does `uid`/`gid` have `want` permission on `targetPath`?
+     * `want` is a bitmask of R_OK (4), W_OK (2), X_OK (1).
+     * Root (uid === 0) is granted everything except X_OK without at least one x bit set.
+     * Returns true when access is granted.
+     */
+    checkAccess(targetPath, uid, gid, want) {
+        try {
+            const node = getNodeNormalized(this.root, normalizePath(targetPath));
+            const mode = node.mode;
+            // Root: allowed everything except execute (at least one x bit needed)
+            if (uid === 0) {
+                if (want & 1)
+                    return (mode & 0o111) !== 0;
+                return true;
+            }
+            let perm = 0;
+            if (uid === node.uid) {
+                perm = (mode >> 6) & 7; // owner bits
+            }
+            else if (gid === node.gid) {
+                perm = (mode >> 3) & 7; // group bits
+            }
+            else {
+                perm = mode & 7; // other bits
+            }
+            return (perm & want) === want;
+        }
+        catch {
+            return false;
+        }
+    }
     /** Returns metadata for a file or directory. */
     stat(targetPath) {
         const m = this.resolveMount(targetPath);
@@ -688,6 +783,8 @@ class VirtualFileSystem extends EventEmitter {
                     name,
                     path: normalizePath(targetPath),
                     mode: 0o755,
+                    uid: 0,
+                    gid: 0,
                     createdAt: hst.birthtime,
                     updatedAt: now,
                     childrenCount: fsSync.readdirSync(m.fullHostPath).length,
@@ -698,6 +795,8 @@ class VirtualFileSystem extends EventEmitter {
                 name,
                 path: normalizePath(targetPath),
                 mode: m.readOnly ? 0o444 : 0o644,
+                uid: 0,
+                gid: 0,
                 createdAt: hst.birthtime,
                 updatedAt: now,
                 compressed: false,
@@ -705,6 +804,8 @@ class VirtualFileSystem extends EventEmitter {
             };
         }
         const normalized = normalizePath(targetPath);
+        if (normalized.startsWith("/proc"))
+            this._triggerReadHook(normalized);
         const node = getNodeNormalized(this.root, normalized);
         const name = normalized === "/" ? "" : path.posix.basename(normalized);
         if (node.type === "stub") {
@@ -714,6 +815,8 @@ class VirtualFileSystem extends EventEmitter {
                 name,
                 path: normalized,
                 mode: s.mode,
+                uid: s.uid,
+                gid: s.gid,
                 createdAt: new Date(s.createdAt),
                 updatedAt: new Date(s.updatedAt),
                 compressed: false,
@@ -727,6 +830,8 @@ class VirtualFileSystem extends EventEmitter {
                 name,
                 path: normalized,
                 mode: f.mode,
+                uid: f.uid,
+                gid: f.gid,
                 createdAt: new Date(f.createdAt),
                 updatedAt: new Date(f.updatedAt),
                 compressed: f.compressed,
@@ -739,6 +844,8 @@ class VirtualFileSystem extends EventEmitter {
             name,
             path: normalized,
             mode: d.mode,
+            uid: d.uid,
+            gid: d.gid,
             createdAt: new Date(d.createdAt),
             updatedAt: new Date(d.updatedAt),
             childrenCount: d._childCount,
@@ -778,6 +885,8 @@ class VirtualFileSystem extends EventEmitter {
             }
         }
         const normalized = normalizePath(dirPath);
+        if (normalized.startsWith("/proc"))
+            this._triggerReadHook(normalized);
         const node = getNodeNormalized(this.root, normalized);
         if (node.type !== "directory") {
             throw new Error(`Cannot list '${dirPath}': not a directory.`);
@@ -873,6 +982,8 @@ class VirtualFileSystem extends EventEmitter {
             name,
             content: Buffer.from(normalizedTarget, "utf8"),
             mode: 0o120777,
+            uid: 0,
+            gid: 0,
             compressed: false,
             createdAt: Date.now(),
             updatedAt: Date.now(),
@@ -997,6 +1108,8 @@ class VirtualFileSystem extends EventEmitter {
                     type: "file",
                     name: child.name,
                     mode: child.mode,
+                    uid: child.uid,
+                    gid: child.gid,
                     createdAt: new Date(child.createdAt).toISOString(),
                     updatedAt: new Date(child.updatedAt).toISOString(),
                     compressed: false,
@@ -1014,6 +1127,8 @@ class VirtualFileSystem extends EventEmitter {
             type: "directory",
             name: dir.name,
             mode: dir.mode,
+            uid: dir.uid,
+            gid: dir.gid,
             createdAt: new Date(dir.createdAt).toISOString(),
             updatedAt: new Date(dir.updatedAt).toISOString(),
             children,
@@ -1024,6 +1139,8 @@ class VirtualFileSystem extends EventEmitter {
             type: "file",
             name: file.name,
             mode: file.mode,
+            uid: file.uid,
+            gid: file.gid,
             createdAt: new Date(file.createdAt).toISOString(),
             updatedAt: new Date(file.updatedAt).toISOString(),
             compressed: file.compressed,
@@ -1061,6 +1178,8 @@ class VirtualFileSystem extends EventEmitter {
             type: "directory",
             name,
             mode: snap.mode,
+            uid: snap.uid ?? 0,
+            gid: snap.gid ?? 0,
             createdAt: Date.parse(snap.createdAt),
             updatedAt: Date.parse(snap.updatedAt),
             children: Object.create(null),
@@ -1074,6 +1193,8 @@ class VirtualFileSystem extends EventEmitter {
                     type: "file",
                     name: f.name,
                     mode: f.mode,
+                    uid: f.uid ?? 0,
+                    gid: f.gid ?? 0,
                     createdAt: Date.parse(f.createdAt),
                     updatedAt: Date.parse(f.updatedAt),
                     compressed: f.compressed,

package/dist/VirtualFileSystem/internalTypes.d.ts

@@ -3,6 +3,10 @@ export type InternalNode = InternalFileNode | InternalStubNode | InternalDirecto
 interface InternalBaseNode {
     name: string;
     mode: number;
+    /** Owner user ID (0 = root). */
+    uid: number;
+    /** Owner group ID (0 = root). */
+    gid: number;
     /** Unix timestamp in ms — avoids Date object overhead (~80 bytes each). */
     createdAt: number;
     /** Unix timestamp in ms. */

package/dist/VirtualFileSystem/journal.d.ts

@@ -18,6 +18,16 @@
  *   0x06 SYMLINK — [2B target_len] [target bytes]
  */
 /** biome-ignore-all lint/style/useNamingConvention: JournalOp modes */
+/**
+ * Journal operation type codes used in VFS write-ahead log entries.
+ *
+ * - `WRITE`  — Write file content and mode.
+ * - `MKDIR`  — Create a directory.
+ * - `REMOVE` — Delete a file or directory.
+ * - `CHMOD`  — Change file mode.
+ * - `MOVE`   — Rename / move a node.
+ * - `SYMLINK`— Create a symbolic link.
+ */
 export declare const JournalOp: {
     readonly WRITE: 1;
     readonly MKDIR: 2;
@@ -35,10 +45,6 @@ export interface JournalEntry {
     mode?: number;
     dest?: string;
 }
-/** Serialise one entry to a Buffer. */
-export declare function encodeEntry(e: JournalEntry): Buffer;
-/** Parse all entries from a journal Buffer. Returns empty array on corrupt data. */
-export declare function decodeJournal(buf: Buffer): JournalEntry[];
 /** Append a single entry to the journal file (O_APPEND, atomic write). */
 export declare function appendJournalEntry(journalPath: string, entry: JournalEntry): void;
 /** Read and decode all entries from a journal file. Returns [] if file is absent/empty. */

package/dist/VirtualFileSystem/journal.js

@@ -19,6 +19,16 @@
  */
 /** biome-ignore-all lint/style/useNamingConvention: JournalOp modes */
 import * as fsSync from "node:fs";
+/**
+ * Journal operation type codes used in VFS write-ahead log entries.
+ *
+ * - `WRITE`  — Write file content and mode.
+ * - `MKDIR`  — Create a directory.
+ * - `REMOVE` — Delete a file or directory.
+ * - `CHMOD`  — Change file mode.
+ * - `MOVE`   — Rename / move a node.
+ * - `SYMLINK`— Create a symbolic link.
+ */
 export const JournalOp = {
     WRITE: 0x01,
     MKDIR: 0x02,
@@ -35,7 +45,7 @@ function writeString2(buf, offset, s) {
     return 2 + b.length;
 }
 /** Serialise one entry to a Buffer. */
-export function encodeEntry(e) {
+function encodeEntry(e) {
     const pathBuf = Buffer.from(e.path, ENC);
     let payloadLen = 0;
     if (e.op === JournalOp.WRITE) {
@@ -84,7 +94,7 @@ export function encodeEntry(e) {
     return buf;
 }
 /** Parse all entries from a journal Buffer. Returns empty array on corrupt data. */
-export function decodeJournal(buf) {
+function decodeJournal(buf) {
     const entries = [];
     let off = 0;
     try {

package/dist/VirtualFileSystem/path.d.ts

@@ -1,12 +1,34 @@
 import type { InternalDirectoryNode, InternalNode } from "./internalTypes";
+/**
+ * Normalizes a VFS path by resolving `.` and `..` segments and removing trailing slash.
+ * Empty or blank input returns `"/"`.
+ * @param rawPath - The path to normalize (may be relative — leading `/` is added if missing).
+ * @returns The normalized absolute POSIX path.
+ */
 export declare function normalizePath(rawPath: string): string;
-export declare function splitPath(normalizedPath: string): string[];
+/**
+ * Retrieves a node from the VFS tree by path string. Normalizes the path first.
+ * @param root - The root directory node of the virtual filesystem.
+ * @param targetPath - The path to look up (e.g. `"/usr/bin"`).
+ * @returns The internal node at the given path.
+ * @throws If any path component does not exist or an intermediate entry is not a directory.
+ */
 export declare function getNode(root: InternalDirectoryNode, targetPath: string): InternalNode;
 /**
  * Like getNode but skips normalization — caller must pass an already-normalized path.
  * Avoids double normalizePath() when the caller has already normalized.
  */
 export declare function getNodeNormalized(root: InternalDirectoryNode, normalized: string): InternalNode;
+/**
+ * Resolves a path to its parent directory node and the final path component name.
+ * Optionally creates intermediate directories when `createIfMissing` is set.
+ * @param root - The root directory node of the virtual filesystem.
+ * @param targetPath - The path whose parent to resolve.
+ * @param createIfMissing - If true, missing parent directories are created via `createPath`.
+ * @param createPath - Callback invoked with each missing directory path to create it.
+ * @returns An object with the parent directory node and the final component name.
+ * @throws If the path is root or the resolved parent is not a directory.
+ */
 export declare function getParentDirectory(root: InternalDirectoryNode, targetPath: string, createIfMissing: boolean, createPath: (pathToCreate: string) => void): {
     parent: InternalDirectoryNode;
     name: string;

package/dist/VirtualFileSystem/path.js

@@ -1,4 +1,10 @@
 import * as path from "node:path";
+/**
+ * Normalizes a VFS path by resolving `.` and `..` segments and removing trailing slash.
+ * Empty or blank input returns `"/"`.
+ * @param rawPath - The path to normalize (may be relative — leading `/` is added if missing).
+ * @returns The normalized absolute POSIX path.
+ */
 export function normalizePath(rawPath) {
     if (!rawPath || rawPath.trim() === "") {
         return "/";
@@ -6,9 +12,13 @@ export function normalizePath(rawPath) {
     const normalized = path.posix.normalize(rawPath.startsWith("/") ? rawPath : `/${rawPath}`);
     return normalized === "" ? "/" : normalized;
 }
-export function splitPath(normalizedPath) {
-    return normalizedPath.split("/").filter(Boolean);
-}
+/**
+ * Retrieves a node from the VFS tree by path string. Normalizes the path first.
+ * @param root - The root directory node of the virtual filesystem.
+ * @param targetPath - The path to look up (e.g. `"/usr/bin"`).
+ * @returns The internal node at the given path.
+ * @throws If any path component does not exist or an intermediate entry is not a directory.
+ */
 export function getNode(root, targetPath) {
     const normalized = normalizePath(targetPath);
     return getNodeNormalized(root, normalized);
@@ -41,6 +51,16 @@ export function getNodeNormalized(root, normalized) {
     }
     return current;
 }
+/**
+ * Resolves a path to its parent directory node and the final path component name.
+ * Optionally creates intermediate directories when `createIfMissing` is set.
+ * @param root - The root directory node of the virtual filesystem.
+ * @param targetPath - The path whose parent to resolve.
+ * @param createIfMissing - If true, missing parent directories are created via `createPath`.
+ * @param createPath - Callback invoked with each missing directory path to create it.
+ * @returns An object with the parent directory node and the final component name.
+ * @throws If the path is root or the resolved parent is not a directory.
+ */
 export function getParentDirectory(root, targetPath, createIfMissing, createPath) {
     const normalized = normalizePath(targetPath);
     if (normalized === "/") {

package/dist/VirtualPackageManager/index.js

@@ -819,7 +819,7 @@ export class VirtualPackageManager {
                     if (this.vfs.exists(filePath))
                         this.vfs.remove(filePath);
                 }
-                catch { }
+                catch { /* best-effort cleanup */ }
             }
             // Run remove hook
             const def = this.findInRegistry(pkg.name);

package/dist/VirtualShell/index.d.ts

@@ -1,4 +1,5 @@
 import { EventEmitter } from "node:events";
+import { VirtualNetworkManager } from "../modules/VirtualNetworkManager";
 import type { CommandContext, CommandResult } from "../types/commands";
 import type { ShellStream } from "../types/streams";
 import type { VfsNodeStats } from "../types/vfs";
@@ -88,6 +89,8 @@ declare class VirtualShell extends EventEmitter {
     users: VirtualUserManager;
     /** APT/dpkg package manager backed by the built-in package registry. */
     packageManager: VirtualPackageManager;
+    /** Virtual network stack with interfaces, routes, and ARP cache. */
+    network: VirtualNetworkManager;
     /** Hostname shown in the shell prompt and SSH ident string. */
     hostname: string;
     /** Distro identity strings surfaced by `uname`, `neofetch`, etc. */

package/dist/VirtualShell/index.js

@@ -2,6 +2,7 @@ import { EventEmitter } from "node:events";
 import { createCustomCommand, registerCommand } from "../commands/registry";
 import { runCommand } from "../commands/runtime";
 import { bootstrapLinuxRootfs, refreshProc, syncEtcPasswd, } from "../modules/linuxRootfs";
+import { VirtualNetworkManager } from "../modules/VirtualNetworkManager";
 import { createPerfLogger } from "../utils/perfLogger";
 import VirtualFileSystem, {} from "../VirtualFileSystem";
 import { VirtualPackageManager } from "../VirtualPackageManager";
@@ -70,6 +71,8 @@ class VirtualShell extends EventEmitter {
     users;
     /** APT/dpkg package manager backed by the built-in package registry. */
     packageManager;
+    /** Virtual network stack with interfaces, routes, and ARP cache. */
+    network;
     /** Hostname shown in the shell prompt and SSH ident string. */
     hostname;
     /** Distro identity strings surfaced by `uname`, `neofetch`, etc. */
@@ -103,18 +106,24 @@ class VirtualShell extends EventEmitter {
         }
         this.users = new VirtualUserManager(this.vfs, resolveAutoSudoForNewUsers());
         this.packageManager = new VirtualPackageManager(this.vfs, this.users);
+        this.network = new VirtualNetworkManager();
         // Store references to avoid TypeScript "used before assigned" errors
         const vfs = this.vfs;
         const users = this.users;
         const shellProps = this.properties;
         const shellHostname = this.hostname;
         const startTime = this.startTime;
+        const network = this.network;
         // Initialize both VFS mirror and users, ensuring all is ready before auth
         this.initialized = (async () => {
             await vfs.restoreMirror();
             await users.initialize();
             // Bootstrap Linux rootfs (idempotent)
-            bootstrapLinuxRootfs(vfs, users, shellHostname, shellProps, startTime);
+            bootstrapLinuxRootfs(vfs, users, shellHostname, shellProps, startTime, [], network);
+            // Register read hook: refresh /proc dynamically on every access
+            vfs.onBeforeRead("/proc", () => {
+                refreshProc(vfs, shellProps, shellHostname, startTime, users.listActiveSessions(), network);
+            });
             this.emit("initialized");
         })();
     }
@@ -195,7 +204,7 @@ class VirtualShell extends EventEmitter {
      * reading `/proc` files for up-to-date values.
      */
     refreshProcFs() {
-        refreshProc(this.vfs, this.properties, this.hostname, this.startTime, this.users.listActiveSessions());
+        refreshProc(this.vfs, this.properties, this.hostname, this.startTime, this.users.listActiveSessions(), this.network);
     }
     /**
      * Mount a host directory into the VFS at `vPath`.
@@ -232,7 +241,7 @@ class VirtualShell extends EventEmitter {
      * whenever a session is registered or unregistered.
      */
     refreshProcSessions() {
-        refreshProc(this.vfs, this.properties, this.hostname, this.startTime, this.users.listActiveSessions());
+        refreshProc(this.vfs, this.properties, this.hostname, this.startTime, this.users.listActiveSessions(), this.network);
     }
     /**
      * Syncs `/etc/passwd`, `/etc/group`, and `/etc/shadow` from the current

package/dist/VirtualUserManager/index.d.ts

@@ -7,11 +7,16 @@ import type VirtualFileSystem from "../VirtualFileSystem";
 export interface VirtualUserRecord {
     /** Unique login name. */
     username: string;
+    /** Numeric user ID. */
+    uid: number;
+    /** Primary group ID. */
+    gid: number;
     /** Per-user random salt used for password hashing. */
     salt: string;
     /** Scrypt-derived password hash in hex encoding. */
     passwordHash: string;
 }
+export type ProcessStatus = "running" | "stopped" | "done";
 /** Runtime representation of a command currently executing in a session. */
 export interface VirtualProcess {
     /** Unique process identifier (auto-incremented). */
@@ -26,6 +31,10 @@ export interface VirtualProcess {
     tty: string;
     /** ISO-8601 start timestamp. */
     startedAt: string;
+    /** Current process state. */
+    status: ProcessStatus;
+    /** AbortController for terminating the process. */
+    abortController?: AbortController;
 }
 /** Runtime representation of authenticated SSH session. */
 export interface VirtualActiveSession {
@@ -61,6 +70,8 @@ export declare class VirtualUserManager extends EventEmitter {
     private readonly activeProcesses;
     private nextTty;
     private nextPid;
+    private nextUid;
+    private nextGid;
     /**
      * Creates a user manager instance backed by a virtual filesystem.
      *
@@ -213,15 +224,23 @@ export declare class VirtualUserManager extends EventEmitter {
      * @returns Array of username strings sorted alphabetically.
      */
     listUsers(): string[];
+    /** Returns the numeric UID for a username, or 0 if unknown. */
+    getUid(username: string): number;
+    /** Returns the primary GID for a username, or 0 if unknown. */
+    getGid(username: string): number;
     /**
      * Registers a running command as a virtual process.
      * Returns the assigned PID so the caller can deregister on completion.
      */
-    registerProcess(username: string, command: string, argv: string[], tty: string): number;
+    registerProcess(username: string, command: string, argv: string[], tty: string, abortController?: AbortController): number;
     /** Removes a process record when the command exits. */
     unregisterProcess(pid: number): void;
+    /** Marks a process as done (keeps it in the table briefly for jobs/ps). */
+    markProcessDone(pid: number): void;
     /** Returns all currently running processes sorted by PID. */
     listProcesses(): VirtualProcess[];
+    /** Terminate a process by PID. Returns true if the process was found and signalled. */
+    killProcess(pid: number): boolean;
     private loadFromVfs;
     private loadSudoersFromVfs;
     private loadQuotasFromVfs;