@secure-exec/core 0.2.0-rc.1 → 0.2.0

package/dist/kernel/proc-backend.js

@@ -0,0 +1,428 @@
+/**
+ * Proc backend.
+ *
+ * Standalone VirtualFileSystem that handles /proc paths.
+ * Receives relative paths (e.g. "self/fd" not "/proc/self/fd").
+ * Designed to be mounted at /proc via MountTable.
+ */
+import { KernelError } from "./types.js";
+const S_IFREG = 0o100000;
+const S_IFDIR = 0o040000;
+const S_IFLNK = 0o120000;
+const PROC_INO_BASE = 0xfffe_0000;
+const PROC_PID_ENTRIES = [
+    { name: "fd", isDirectory: true },
+    { name: "cwd", isDirectory: false, isSymbolicLink: true },
+    { name: "exe", isDirectory: false, isSymbolicLink: true },
+    { name: "environ", isDirectory: false },
+];
+const PROC_ROOT_ENTRIES = [
+    { name: "self", isDirectory: false, isSymbolicLink: true },
+    { name: "sys", isDirectory: true },
+    { name: "mounts", isDirectory: false },
+];
+const PROC_SYS_ENTRIES = [
+    { name: "kernel", isDirectory: true },
+];
+const PROC_SYS_KERNEL_ENTRIES = [
+    { name: "hostname", isDirectory: false },
+];
+function procIno(seed) {
+    let hash = 0;
+    for (let i = 0; i < seed.length; i++) {
+        hash = ((hash * 33) ^ seed.charCodeAt(i)) >>> 0;
+    }
+    return PROC_INO_BASE + (hash & 0xffff);
+}
+function dirStat(seed) {
+    const now = Date.now();
+    return {
+        mode: S_IFDIR | 0o555,
+        size: 0,
+        isDirectory: true,
+        isSymbolicLink: false,
+        atimeMs: now,
+        mtimeMs: now,
+        ctimeMs: now,
+        birthtimeMs: now,
+        ino: procIno(seed),
+        nlink: 2,
+        uid: 0,
+        gid: 0,
+    };
+}
+function fileStat(seed, size) {
+    const now = Date.now();
+    return {
+        mode: S_IFREG | 0o444,
+        size,
+        isDirectory: false,
+        isSymbolicLink: false,
+        atimeMs: now,
+        mtimeMs: now,
+        ctimeMs: now,
+        birthtimeMs: now,
+        ino: procIno(seed),
+        nlink: 1,
+        uid: 0,
+        gid: 0,
+    };
+}
+function linkStat(seed, target) {
+    const now = Date.now();
+    return {
+        mode: S_IFLNK | 0o777,
+        size: target.length,
+        isDirectory: false,
+        isSymbolicLink: true,
+        atimeMs: now,
+        mtimeMs: now,
+        ctimeMs: now,
+        birthtimeMs: now,
+        ino: procIno(seed),
+        nlink: 1,
+        uid: 0,
+        gid: 0,
+    };
+}
+function encodeText(content) {
+    return new TextEncoder().encode(content);
+}
+function encodeEnviron(env) {
+    const entries = Object.entries(env);
+    if (entries.length === 0)
+        return new Uint8Array(0);
+    return encodeText(`${entries.map(([key, value]) => `${key}=${value}`).join("\0")}\0`);
+}
+function resolveExecPath(command) {
+    if (!command)
+        return "";
+    return command.startsWith("/") ? command : `/bin/${command}`;
+}
+function notFound(path) {
+    throw new KernelError("ENOENT", `no such proc entry: ${path}`);
+}
+function rejectWrite(path) {
+    throw new KernelError("EPERM", `cannot modify /proc/${path}`);
+}
+/**
+ * Resolve /proc/self references to the given PID.
+ * Paths are relative (no /proc prefix).
+ */
+export function resolveProcSelfPath(path, pid) {
+    if (path === "self")
+        return `${pid}`;
+    if (path.startsWith("self/"))
+        return `${pid}${path.slice(4)}`;
+    return path;
+}
+/**
+ * Parse a relative proc path into PID + tail components.
+ * "1/fd/0" -> { pid: 1, tail: ["fd", "0"] }
+ */
+function parsePidPath(path) {
+    const parts = path.split("/");
+    const pid = Number(parts[0]);
+    if (!Number.isInteger(pid) || pid < 0)
+        return null;
+    return { pid, tail: parts.slice(1) };
+}
+/**
+ * Format mount entries in Linux /proc/mounts format.
+ */
+function formatMounts(mounts) {
+    return mounts
+        .map((m) => {
+        const fsType = m.path === "/" ? "rootfs" : "mount";
+        const opts = m.readOnly ? "ro" : "rw";
+        return `${fsType} ${m.path} ${fsType} ${opts} 0 0`;
+    })
+        .join("\n")
+        .concat("\n");
+}
+/**
+ * Create a standalone proc backend VFS.
+ * All paths are relative to /proc (e.g. "self/fd", "1/environ", "mounts").
+ * Mount at /proc via MountTable.
+ */
+export function createProcBackend(options) {
+    const kernelHostname = encodeText(`${options.hostname ?? "sandbox"}\n`);
+    const getProcess = (pid) => {
+        const entry = options.processTable.get(pid);
+        if (!entry)
+            throw new KernelError("ENOENT", `no such process ${pid}`);
+        return entry;
+    };
+    const listPids = () => Array.from(options.processTable.listProcesses().keys()).sort((a, b) => a - b);
+    const listOpenFds = (pid) => {
+        const table = options.fdTableManager.get(pid);
+        if (!table)
+            return [];
+        const fds = [];
+        for (const entry of table)
+            fds.push(entry.fd);
+        return fds.sort((a, b) => a - b);
+    };
+    const getFdEntry = (pid, fd) => {
+        const table = options.fdTableManager.get(pid);
+        const entry = table?.get(fd);
+        if (!entry)
+            throw new KernelError("ENOENT", `no such fd ${fd} for process ${pid}`);
+        return entry;
+    };
+    const getLinkTarget = (pid, tail) => {
+        if (tail.length === 1 && tail[0] === "cwd")
+            return getProcess(pid).cwd;
+        if (tail.length === 1 && tail[0] === "exe")
+            return resolveExecPath(getProcess(pid).command);
+        if (tail.length === 2 && tail[0] === "fd") {
+            const fd = Number(tail[1]);
+            if (!Number.isInteger(fd) || fd < 0)
+                throw new KernelError("ENOENT", `invalid fd ${tail[1]}`);
+            return getFdEntry(pid, fd).description.path;
+        }
+        throw new KernelError("ENOENT", `unsupported proc link ${tail.join("/")}`);
+    };
+    const getProcFile = (pid, tail) => {
+        if (tail.length === 1 && tail[0] === "cwd")
+            return encodeText(getProcess(pid).cwd);
+        if (tail.length === 1 && tail[0] === "exe")
+            return encodeText(resolveExecPath(getProcess(pid).command));
+        if (tail.length === 1 && tail[0] === "environ")
+            return encodeEnviron(getProcess(pid).env);
+        if (tail.length === 2 && tail[0] === "fd")
+            return encodeText(getLinkTarget(pid, tail));
+        throw new KernelError("ENOENT", `unsupported proc file ${tail.join("/")}`);
+    };
+    const getMountsContent = () => {
+        if (!options.mountTable) {
+            return encodeText("rootfs / rootfs rw 0 0\n");
+        }
+        return encodeText(formatMounts(options.mountTable.getMounts()));
+    };
+    const getProcStat = (path, followSymlinks) => {
+        // Root /proc directory
+        if (path === "")
+            return dirStat("proc");
+        // /proc/self symlink
+        if (path === "self") {
+            return followSymlinks
+                ? dirStat("proc-self")
+                : linkStat("proc-self-link", "self");
+        }
+        // /proc/mounts
+        if (path === "mounts") {
+            const content = getMountsContent();
+            return fileStat("proc:mounts", content.length);
+        }
+        // /proc/sys tree
+        if (path === "sys")
+            return dirStat("proc:sys");
+        if (path === "sys/kernel")
+            return dirStat("proc:sys:kernel");
+        if (path === "sys/kernel/hostname") {
+            return fileStat("proc:sys:kernel:hostname", kernelHostname.length);
+        }
+        // /proc/[pid]/...
+        const parsed = parsePidPath(path);
+        if (!parsed)
+            notFound(path);
+        const { pid, tail } = parsed;
+        getProcess(pid);
+        if (tail.length === 0)
+            return dirStat(`proc:${pid}`);
+        if (tail.length === 1 && tail[0] === "fd")
+            return dirStat(`proc:${pid}:fd`);
+        if (tail.length === 1 && tail[0] === "environ") {
+            return fileStat(`proc:${pid}:environ`, encodeEnviron(getProcess(pid).env).length);
+        }
+        if ((tail.length === 1 && (tail[0] === "cwd" || tail[0] === "exe")) ||
+            (tail.length === 2 && tail[0] === "fd")) {
+            const target = getLinkTarget(pid, tail);
+            if (!followSymlinks)
+                return linkStat(`proc:${pid}:${tail.join(":")}`, target);
+            // For symlinks when following, return file stat for the target
+            return linkStat(`proc:${pid}:${tail.join(":")}`, target);
+        }
+        notFound(path);
+    };
+    const backend = {
+        async readFile(path) {
+            // Directories
+            if (path === "" ||
+                path === "self" ||
+                path === "sys" ||
+                path === "sys/kernel") {
+                throw new KernelError("EISDIR", `illegal operation on a directory, read '/proc/${path}'`);
+            }
+            // /proc/mounts
+            if (path === "mounts")
+                return getMountsContent();
+            // /proc/sys/kernel/hostname
+            if (path === "sys/kernel/hostname")
+                return kernelHostname;
+            // /proc/[pid]/...
+            const parsed = parsePidPath(path);
+            if (!parsed)
+                notFound(path);
+            const { pid, tail } = parsed;
+            if (tail.length === 0 || (tail.length === 1 && tail[0] === "fd")) {
+                throw new KernelError("EISDIR", `illegal operation on a directory, read '/proc/${path}'`);
+            }
+            return getProcFile(pid, tail);
+        },
+        async pread(path, offset, length) {
+            const content = await this.readFile(path);
+            if (offset >= content.length)
+                return new Uint8Array(0);
+            return content.slice(offset, offset + length);
+        },
+        async readTextFile(path) {
+            const content = await this.readFile(path);
+            return new TextDecoder().decode(content);
+        },
+        async readDir(path) {
+            return (await this.readDirWithTypes(path)).map((entry) => entry.name);
+        },
+        async readDirWithTypes(path) {
+            if (path === "") {
+                return [
+                    ...PROC_ROOT_ENTRIES,
+                    ...listPids().map((pid) => ({
+                        name: String(pid),
+                        isDirectory: true,
+                    })),
+                ];
+            }
+            if (path === "sys")
+                return PROC_SYS_ENTRIES;
+            if (path === "sys/kernel")
+                return PROC_SYS_KERNEL_ENTRIES;
+            if (path === "self") {
+                throw new KernelError("ENOENT", `no such file or directory: /proc/${path}`);
+            }
+            const parsed = parsePidPath(path);
+            if (!parsed)
+                throw new KernelError("ENOENT", `no such file or directory: /proc/${path}`);
+            const { pid, tail } = parsed;
+            getProcess(pid);
+            if (tail.length === 0)
+                return PROC_PID_ENTRIES;
+            if (tail.length === 1 && tail[0] === "fd") {
+                return listOpenFds(pid).map((fd) => ({
+                    name: String(fd),
+                    isDirectory: false,
+                    isSymbolicLink: true,
+                }));
+            }
+            throw new KernelError("ENOTDIR", `not a directory: /proc/${path}`);
+        },
+        async writeFile(path, _content) {
+            rejectWrite(path);
+        },
+        async createDir(path) {
+            rejectWrite(path);
+        },
+        async mkdir(path, _options) {
+            rejectWrite(path);
+        },
+        async exists(path) {
+            if (path === "" || path === "self" || path === "mounts")
+                return true;
+            if (path === "sys" ||
+                path === "sys/kernel" ||
+                path === "sys/kernel/hostname") {
+                return true;
+            }
+            const parsed = parsePidPath(path);
+            if (!parsed)
+                return false;
+            const { pid, tail } = parsed;
+            if (!options.processTable.get(pid))
+                return false;
+            if (tail.length === 0 || (tail.length === 1 && tail[0] === "fd"))
+                return true;
+            if (tail.length === 1 &&
+                (tail[0] === "cwd" || tail[0] === "exe" || tail[0] === "environ"))
+                return true;
+            if (tail.length === 2 && tail[0] === "fd") {
+                const fd = Number(tail[1]);
+                return (Number.isInteger(fd) &&
+                    fd >= 0 &&
+                    options.fdTableManager.get(pid)?.get(fd) !== undefined);
+            }
+            return false;
+        },
+        async stat(path) {
+            return getProcStat(path, true);
+        },
+        async removeFile(path) {
+            rejectWrite(path);
+        },
+        async removeDir(path) {
+            rejectWrite(path);
+        },
+        async rename(_oldPath, _newPath) {
+            throw new KernelError("EPERM", "cannot rename in /proc");
+        },
+        async realpath(path) {
+            if (path === "" || path === "mounts")
+                return path;
+            if (path === "self")
+                return path;
+            if (path === "sys" ||
+                path === "sys/kernel" ||
+                path === "sys/kernel/hostname") {
+                return path;
+            }
+            const parsed = parsePidPath(path);
+            if (!parsed)
+                notFound(path);
+            const { pid, tail } = parsed;
+            getProcess(pid);
+            if (tail.length === 0 || (tail.length === 1 && tail[0] === "fd"))
+                return path;
+            if (tail.length === 1 && tail[0] === "environ")
+                return path;
+            if ((tail.length === 1 && (tail[0] === "cwd" || tail[0] === "exe")) ||
+                (tail.length === 2 && tail[0] === "fd")) {
+                return getLinkTarget(pid, tail);
+            }
+            notFound(path);
+        },
+        async symlink(_target, _linkPath) {
+            throw new KernelError("EPERM", "cannot create symlink in /proc");
+        },
+        async readlink(path) {
+            if (path === "self")
+                return "self";
+            const parsed = parsePidPath(path);
+            if (!parsed)
+                throw new KernelError("EINVAL", `invalid argument: /proc/${path}`);
+            const { pid, tail } = parsed;
+            return getLinkTarget(pid, tail);
+        },
+        async lstat(path) {
+            return getProcStat(path, false);
+        },
+        async link(_oldPath, _newPath) {
+            throw new KernelError("EPERM", "cannot link in /proc");
+        },
+        async chmod(path, _mode) {
+            rejectWrite(path);
+        },
+        async chown(path, _uid, _gid) {
+            rejectWrite(path);
+        },
+        async utimes(path, _atime, _mtime) {
+            rejectWrite(path);
+        },
+        async truncate(path, _length) {
+            rejectWrite(path);
+        },
+        async pwrite(path, _offset, _data) {
+            rejectWrite(path);
+        },
+    };
+    return backend;
+}

package/dist/kernel/proc-layer.js

@@ -183,6 +183,7 @@ export function createProcessScopedFileSystem(vfs, pid) {
         utimes: (path, atime, mtime) => vfs.utimes(resolveProcSelfPath(path, pid), atime, mtime),
         truncate: (path, length) => vfs.truncate(resolveProcSelfPath(path, pid), length),
         pread: (path, offset, length) => vfs.pread(resolveProcSelfPath(path, pid), offset, length),
+        pwrite: (path, offset, data) => vfs.pwrite(resolveProcSelfPath(path, pid), offset, data),
     };
 }
 export function createProcLayer(vfs, options) {
@@ -496,6 +497,11 @@ export function createProcLayer(vfs, options) {
             rejectMutation(normalized);
             return vfs.truncate(clonePathArg(path, normalized), length);
         },
+        async pwrite(path, offset, data) {
+            const normalized = normalizePath(path);
+            rejectMutation(normalized);
+            return vfs.pwrite(clonePathArg(path, normalized), offset, data);
+        },
     };
     return wrapped;
 }

package/dist/kernel/process-table.d.ts

@@ -5,7 +5,7 @@
  * parent-child relationships, waitpid, and signal routing. A WasmVM
  * shell can waitpid on a Node child process.
  */
-import type { DriverProcess, ProcessContext, ProcessEntry, ProcessInfo, SignalHandler, ProcessSignalState } from "./types.js";
+import type { DriverProcess, ProcessContext, ProcessEntry, ProcessInfo, SignalHandler, ProcessSignalState, KernelLogger } from "./types.js";
 export declare class ProcessTable {
     private entries;
     private nextPid;
@@ -13,10 +13,12 @@ export declare class ProcessTable {
     private zombieTimers;
     /** Pending alarm timers per PID: { timer, scheduledAt (ms epoch) }. */
     private alarmTimers;
+    private log;
     /** Called when a process exits, before waiters are notified. */
     onProcessExit: ((pid: number) => void) | null;
     /** Called when a zombie process is reaped (removed from the table). */
     onProcessReap: ((pid: number) => void) | null;
+    constructor(logger?: KernelLogger);
     /** Atomically allocate the next PID. */
     allocatePid(): number;
     /** Register a process with a pre-allocated PID. */

package/dist/kernel/process-table.js

@@ -5,7 +5,7 @@
  * parent-child relationships, waitpid, and signal routing. A WasmVM
  * shell can waitpid on a Node child process.
  */
-import { KernelError, SIGCHLD, SIGALRM, SIGCONT, SIGSTOP, SIGTSTP, SIGKILL, WNOHANG, SA_RESETHAND, SIG_BLOCK, SIG_UNBLOCK, SIG_SETMASK } from "./types.js";
+import { KernelError, SIGCHLD, SIGALRM, SIGCONT, SIGSTOP, SIGTSTP, SIGKILL, SIGWINCH, WNOHANG, SA_RESETHAND, SIG_BLOCK, SIG_UNBLOCK, SIG_SETMASK, noopKernelLogger } from "./types.js";
 import { WaitQueue } from "./wait.js";
 import { encodeExitStatus, encodeSignalStatus } from "./wstatus.js";
 const ZOMBIE_TTL_MS = 60_000;
@@ -16,10 +16,14 @@ export class ProcessTable {
     zombieTimers = new Map();
     /** Pending alarm timers per PID: { timer, scheduledAt (ms epoch) }. */
     alarmTimers = new Map();
+    log;
     /** Called when a process exits, before waiters are notified. */
     onProcessExit = null;
     /** Called when a zombie process is reaped (removed from the table). */
     onProcessReap = null;
+    constructor(logger) {
+        this.log = logger ?? noopKernelLogger;
+    }
     /** Atomically allocate the next PID. */
     allocatePid() {
         return this.nextPid++;
@@ -43,6 +47,7 @@ export class ProcessTable {
             exitCode: null,
             exitReason: null,
             termSignal: 0,
+            startTime: Date.now(),
             exitTime: null,
             env: { ...ctx.env },
             cwd: ctx.cwd,
@@ -61,6 +66,7 @@ export class ProcessTable {
             driverProcess,
         };
         this.entries.set(pid, entry);
+        this.log.debug({ pid, ppid: ctx.ppid, pgid, sid, driver, command, args }, "process registered");
         // Wire up exit callback to mark process as exited
         driverProcess.onExit = (code) => {
             this.markExited(pid, code);
@@ -90,6 +96,11 @@ export class ProcessTable {
             return;
         if (entry.status === "exited")
             return;
+        this.log.debug({
+            pid, exitCode, command: entry.command,
+            termSignal: entry.termSignal,
+            reason: entry.termSignal > 0 ? "signal" : "normal",
+        }, "process exited");
         entry.status = "exited";
         entry.exitCode = exitCode;
         entry.exitReason = entry.termSignal > 0 ? "signal" : "normal";
@@ -165,6 +176,7 @@ export class ProcessTable {
         if (signal < 0 || signal > 64) {
             throw new KernelError("EINVAL", `invalid signal ${signal}`);
         }
+        this.log.debug({ pid, signal }, "kill");
         if (pid < 0) {
             // Process group kill
             const pgid = -pid;
@@ -200,6 +212,7 @@ export class ProcessTable {
      */
     deliverSignal(entry, signal) {
         const { signalState } = entry;
+        this.log.trace({ pid: entry.pid, signal, command: entry.command }, "deliver signal");
         // SIGKILL and SIGSTOP always use default action — cannot be caught/blocked/ignored
         if (signal === SIGKILL || signal === SIGSTOP) {
             this.applyDefaultAction(entry, signal);
@@ -282,18 +295,21 @@ export class ProcessTable {
     /** Apply the kernel default action for a signal. */
     applyDefaultAction(entry, signal) {
         if (signal === SIGTSTP || signal === SIGSTOP) {
+            this.log.debug({ pid: entry.pid, signal, action: "stop" }, "signal default action");
             this.stop(entry.pid);
             entry.driverProcess.kill(signal);
         }
         else if (signal === SIGCONT) {
+            this.log.debug({ pid: entry.pid, signal, action: "continue" }, "signal default action");
             this.cont(entry.pid);
             entry.driverProcess.kill(signal);
         }
-        else if (signal === SIGCHLD) {
-            // Default SIGCHLD action: ignore (don't terminate)
+        else if (signal === SIGCHLD || signal === SIGWINCH) {
+            // Default action: ignore (POSIX — SIGCHLD and SIGWINCH don't terminate)
             return;
         }
         else {
+            this.log.debug({ pid: entry.pid, signal, action: "terminate", command: entry.command }, "signal default action");
             entry.termSignal = signal;
             entry.driverProcess.kill(signal);
         }
@@ -535,8 +551,12 @@ export class ProcessTable {
                 sid: entry.sid,
                 driver: entry.driver,
                 command: entry.command,
+                args: entry.args,
+                cwd: entry.cwd,
                 status: entry.status,
                 exitCode: entry.exitCode,
+                startTime: entry.startTime,
+                exitTime: entry.exitTime,
             });
         }
         return result;

package/dist/kernel/pty.d.ts

@@ -6,7 +6,7 @@
  * Writing to slave → readable from master (output direction).
  * Follows the same FileDescription/refCount pattern as PipeManager.
  */
-import type { FileDescription, Termios } from "./types.js";
+import type { FileDescription, Termios, KernelLogger } from "./types.js";
 import { FILETYPE_CHARACTER_DEVICE } from "./types.js";
 import type { ProcessFDTable } from "./fd-table.js";
 export interface LineDisciplineConfig {
@@ -37,7 +37,8 @@ export declare class PtyManager {
     private onSignal;
     private nextPtyId;
     private nextPtyDescId;
-    constructor(onSignal?: (pgid: number, signal: number, excludeLeaders: boolean) => number);
+    private log;
+    constructor(onSignal?: (pgid: number, signal: number, excludeLeaders: boolean) => number, logger?: KernelLogger);
     /**
      * Allocate a PTY pair. Returns two FileDescriptions:
      * one for the master and one for the slave.

package/dist/kernel/pty.js

@@ -6,7 +6,7 @@
  * Writing to slave → readable from master (output direction).
  * Follows the same FileDescription/refCount pattern as PipeManager.
  */
-import { FILETYPE_CHARACTER_DEVICE, O_RDWR, KernelError, defaultTermios, } from "./types.js";
+import { FILETYPE_CHARACTER_DEVICE, O_RDWR, KernelError, defaultTermios, noopKernelLogger, } from "./types.js";
 /** Maximum buffered bytes per PTY direction before writes are rejected (EAGAIN). */
 export const MAX_PTY_BUFFER_BYTES = 65_536; // 64 KB
 /** Maximum canonical-mode line buffer size (POSIX MAX_CANON). */
@@ -23,8 +23,10 @@ export class PtyManager {
     onSignal;
     nextPtyId = 0;
     nextPtyDescId = 200_000; // High range to avoid FD/pipe ID collisions
-    constructor(onSignal) {
+    log;
+    constructor(onSignal, logger) {
         this.onSignal = onSignal ?? null;
+        this.log = logger ?? noopKernelLogger;
     }
     /**
      * Allocate a PTY pair. Returns two FileDescriptions:
@@ -65,6 +67,7 @@ export class PtyManager {
         this.ptys.set(id, state);
         this.descToPty.set(masterDesc.id, { ptyId: id, end: "master" });
         this.descToPty.set(slaveDesc.id, { ptyId: id, end: "slave" });
+        this.log.debug({ ptyId: id, path, masterDescId: masterDesc.id, slaveDescId: slaveDesc.id }, "PTY created");
         return {
             master: { description: masterDesc, filetype: FILETYPE_CHARACTER_DEVICE },
             slave: { description: slaveDesc, filetype: FILETYPE_CHARACTER_DEVICE },
@@ -167,8 +170,10 @@ export class PtyManager {
             return;
         if (ref.end === "master") {
             state.closed.master = true;
+            this.log.debug({ ptyId: ref.ptyId, fgPgid: state.foregroundPgid }, "PTY master closed");
             // SIGHUP: when master closes, send SIGHUP to foreground process group
             if (state.foregroundPgid > 0 && this.onSignal) {
+                this.log.debug({ ptyId: ref.ptyId, pgid: state.foregroundPgid, signal: 1 }, "PTY SIGHUP delivery");
                 try {
                     this.onSignal(state.foregroundPgid, 1 /* SIGHUP */, false);
                 }
@@ -244,6 +249,7 @@ export class PtyManager {
         const state = this.ptys.get(ptyId);
         if (!state)
             throw new KernelError("EBADF", "PTY not found");
+        this.log.trace({ ptyId, pgid, prev: state.foregroundPgid }, "PTY set foreground pgid");
         state.foregroundPgid = pgid;
     }
     /** Set the session leader pgid for SIGINT interception on this PTY. */
@@ -252,6 +258,7 @@ export class PtyManager {
         const state = this.ptys.get(ptyId);
         if (!state)
             throw new KernelError("EBADF", "PTY not found");
+        this.log.trace({ ptyId, pgid }, "PTY set session leader");
         state.sessionLeaderPgid = pgid;
     }
     /** Get terminal attributes for the PTY containing this description. */
@@ -276,6 +283,7 @@ export class PtyManager {
         const state = this.ptys.get(ptyId);
         if (!state)
             throw new KernelError("EBADF", "PTY not found");
+        this.log.trace({ ptyId, termios }, "PTY setTermios");
         if (termios.icrnl !== undefined)
             state.termios.icrnl = termios.icrnl;
         if (termios.opost !== undefined)
@@ -360,6 +368,7 @@ export class PtyManager {
             if (termios.isig) {
                 const signal = this.signalForByte(state, byte);
                 if (signal !== null) {
+                    this.log.debug({ ptyId: state.id, signal, fgPgid: state.foregroundPgid, sessionLeader: state.sessionLeaderPgid }, "PTY signal char detected");
                     if (termios.icanon)
                         state.lineBuffer.length = 0;
                     // Session-leader SIGINT interception: echo ^C, protect
@@ -383,6 +392,7 @@ export class PtyManager {
                                 // Signal delivery failure must not break line discipline
                             }
                         }
+                        this.log.debug({ ptyId: state.id, childrenKilled, pgid: state.foregroundPgid }, "PTY session-leader SIGINT interception");
                         // No children running → shell is at the prompt blocking on
                         // fdRead. Inject a newline to unblock it and trigger a
                         // fresh prompt.
@@ -401,6 +411,7 @@ export class PtyManager {
                     }
                     // Normal signal delivery (non-SIGINT or non-session-leader)
                     if (state.foregroundPgid > 0) {
+                        this.log.debug({ ptyId: state.id, signal, pgid: state.foregroundPgid }, "PTY signal delivery to foreground group");
                         try {
                             this.onSignal?.(state.foregroundPgid, signal, false);
                         }