@rynx-ai/runtime 0.1.11-beta.32 → 0.1.11-beta.34

package/dist/codex-app-server/process-registry.js

@@ -0,0 +1,320 @@
+import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { rynxRuntimeDir } from "@rynx-ai/core";
+const REGISTRY_FILE = "process-registry.json";
+const TAG_PREFIX = "rynx_crash_teardown_tag=";
+const STATE_PREFIX = "rynx_crash_teardown_state_dir=";
+export function runtimeProcessRegistryPath() {
+    return join(rynxRuntimeDir(), REGISTRY_FILE);
+}
+export function runtimeProcessTagArg(sessionTag) {
+    if (!sessionTag)
+        throw new Error("sessionTag must be non-empty");
+    return `${TAG_PREFIX}${sessionTag}`;
+}
+export function runtimeProcessArgv0(cliPath, sessionTag) {
+    return `${basename(cliPath)} ${runtimeProcessTagArg(sessionTag)}`;
+}
+export function withRuntimeProcessStateArg(baseArgs, stateDir) {
+    const args = [...baseArgs];
+    const marker = ["-c", `${STATE_PREFIX}${JSON.stringify(stateDir)}`];
+    const subcommand = args.indexOf("app-server");
+    args.splice(subcommand >= 0 ? subcommand : 0, 0, ...marker);
+    return args;
+}
+export function registerRuntimeProcess(entry, registryPath = runtimeProcessRegistryPath()) {
+    if (!validEntry(entry))
+        return;
+    mutateRegistry(registryPath, (entries) => [
+        ...entries.filter((candidate) => candidate.sessionTag !== entry.sessionTag),
+        entry,
+    ]);
+}
+export function unregisterRuntimeProcess(sessionTag, registryPath = runtimeProcessRegistryPath()) {
+    if (!sessionTag)
+        return;
+    mutateRegistry(registryPath, (entries) => entries.filter((entry) => entry.sessionTag !== sessionTag));
+}
+export function reconcileRuntimeProcesses(opts = {}) {
+    return reconcileEntries(undefined, opts);
+}
+export function reapRuntimeProcessesForStateDir(stateDir, opts = {}) {
+    if (process.platform === "win32" && !opts.processListing)
+        return 0;
+    const listing = opts.processListing?.() ?? listProcesses();
+    if (!listing)
+        return 0;
+    const currentPgid = opts.currentPgid?.() ?? processGroupId(process.pid);
+    const signalGroup = opts.signalGroup ?? signalProcessGroup;
+    const childAlive = opts.childAlive ?? isProcessAlive;
+    const graceMs = opts.graceMs ?? 1_500;
+    const victims = new Map();
+    for (const line of listing.split("\n")) {
+        const match = /^\s*(\d+)\s+(\d+)\s+([\s\S]+)$/.exec(line);
+        if (!match)
+            continue;
+        const pid = Number.parseInt(match[1], 10);
+        const pgid = Number.parseInt(match[2], 10);
+        const command = match[3];
+        if (!command.includes(stateDir) || !command.includes("app-server"))
+            continue;
+        if (pid === process.pid || pgid <= 0 || pgid === currentPgid)
+            continue;
+        victims.set(pid, pgid);
+    }
+    if (victims.size === 0)
+        return 0;
+    for (const pgid of new Set(victims.values()))
+        signalGroup(pgid, "SIGTERM");
+    const deadline = Date.now() + graceMs;
+    while (Date.now() < deadline && [...victims.keys()].some(childAlive)) {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
+    }
+    for (const [pid, pgid] of victims) {
+        if (childAlive(pid))
+            signalGroup(pgid, "SIGKILL");
+    }
+    return victims.size;
+}
+function reconcileEntries(stateDir, opts) {
+    const registryPath = opts.registryPath ?? runtimeProcessRegistryPath();
+    const ownerAlive = opts.ownerAlive ?? isProcessAlive;
+    const ownerIdentity = opts.ownerIdentity ?? runtimeProcessOwnerIdentity;
+    const childAlive = opts.childAlive ?? isProcessAlive;
+    const commandLine = opts.commandLine ?? processCommandLine;
+    const terminateGroup = opts.terminateGroup ?? terminateProcessGroup;
+    let reaped = 0;
+    mutateRegistry(registryPath, (entries) => {
+        const survivors = [];
+        for (const entry of entries) {
+            if (stateDir !== undefined && entry.stateDir !== stateDir) {
+                survivors.push(entry);
+                continue;
+            }
+            if (ownerAlive(entry.ownerPid)) {
+                const currentOwnerIdentity = ownerIdentity(entry.ownerPid);
+                // Old registry entries have no start identity. Keep the conservative
+                // PID-only behavior for those entries; every newly registered process
+                // is protected against PID reuse.
+                if (!entry.ownerIdentity ||
+                    !currentOwnerIdentity ||
+                    currentOwnerIdentity === entry.ownerIdentity) {
+                    survivors.push(entry);
+                    continue;
+                }
+            }
+            if (!childAlive(entry.pid))
+                continue;
+            if (!commandLine(entry.pid).includes(runtimeProcessTagArg(entry.sessionTag)))
+                continue;
+            if (!terminateGroup(entry.pgid)) {
+                survivors.push(entry);
+                continue;
+            }
+            reaped += 1;
+        }
+        return survivors;
+    });
+    return reaped;
+}
+function validEntry(entry) {
+    return Number.isSafeInteger(entry.pid) && entry.pid > 0 &&
+        Number.isSafeInteger(entry.pgid) && entry.pgid > 0 &&
+        Number.isSafeInteger(entry.ownerPid) && entry.ownerPid > 0 &&
+        (entry.ownerIdentity === undefined ||
+            (typeof entry.ownerIdentity === "string" && entry.ownerIdentity.length > 0)) &&
+        Boolean(entry.sessionTag) && Boolean(entry.stateDir);
+}
+function readRegistry(path) {
+    let value;
+    try {
+        value = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((entry) => typeof entry === "object" && entry !== null && validEntry(entry));
+}
+function mutateRegistry(path, mutation) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const lockDir = `${path}.lock`;
+    const deadline = Date.now() + 2_000;
+    while (true) {
+        try {
+            mkdirSync(lockDir, { mode: 0o700 });
+            writeFileSync(join(lockDir, "owner.pid"), JSON.stringify({
+                pid: process.pid,
+                identity: runtimeProcessOwnerIdentity(process.pid),
+            }), { mode: 0o600 });
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                return;
+            let ownerPid = 0;
+            let ownerIdentity = "";
+            try {
+                const rawOwner = readFileSync(join(lockDir, "owner.pid"), "utf8");
+                try {
+                    const parsed = JSON.parse(rawOwner);
+                    ownerPid = typeof parsed.pid === "number" ? parsed.pid : 0;
+                    ownerIdentity = typeof parsed.identity === "string" ? parsed.identity : "";
+                }
+                catch {
+                    // Backward-compatible recovery for a lock written by the earlier
+                    // PID-only implementation.
+                    ownerPid = Number.parseInt(rawOwner, 10);
+                }
+            }
+            catch {
+                // A creator may be between mkdir and marker write; the bounded retry handles it.
+            }
+            const currentOwnerIdentity = ownerPid > 0
+                ? runtimeProcessOwnerIdentity(ownerPid)
+                : "";
+            const staleKnownOwner = ownerPid > 0 && (!isProcessAlive(ownerPid) ||
+                Boolean(ownerIdentity && currentOwnerIdentity && ownerIdentity !== currentOwnerIdentity));
+            let staleUnownedLock = false;
+            if (ownerPid <= 0) {
+                try {
+                    staleUnownedLock = Date.now() - statSync(lockDir).mtimeMs >= 1_000;
+                }
+                catch {
+                    staleUnownedLock = true;
+                }
+            }
+            if (staleKnownOwner || staleUnownedLock) {
+                rmSync(lockDir, { recursive: true, force: true });
+                continue;
+            }
+            if (Date.now() >= deadline)
+                return;
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+        }
+    }
+    try {
+        const entries = mutation(readRegistry(path));
+        const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+        writeFileSync(temp, `${JSON.stringify(entries)}\n`, { mode: 0o600 });
+        renameSync(temp, path);
+    }
+    finally {
+        rmSync(lockDir, { recursive: true, force: true });
+    }
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/** Return an OS process-start identity used to distinguish PID reuse. */
+export function runtimeProcessOwnerIdentity(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return "";
+    if (process.platform === "linux") {
+        try {
+            const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+            const commandEnd = stat.lastIndexOf(")");
+            if (commandEnd >= 0) {
+                // Fields after ')' begin at proc field 3; starttime is field 22.
+                const startTicks = stat.slice(commandEnd + 2).trim().split(/\s+/)[19];
+                if (startTicks)
+                    return `linux:${startTicks}`;
+            }
+        }
+        catch {
+            return "";
+        }
+    }
+    try {
+        const startedAt = execFileSync("ps", ["-p", String(pid), "-ww", "-o", "lstart="], {
+            encoding: "utf8",
+            timeout: 2_000,
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        return startedAt ? `${process.platform}:${startedAt}` : "";
+    }
+    catch {
+        return "";
+    }
+}
+function processCommandLine(pid) {
+    if (process.platform === "linux") {
+        try {
+            return readFileSync(`/proc/${pid}/cmdline`)
+                .toString("utf8")
+                .replaceAll("\0", " ");
+        }
+        catch {
+            // Fall through to ps for macOS and restricted procfs environments.
+        }
+    }
+    try {
+        return execFileSync("ps", ["-p", String(pid), "-ww", "-o", "command="], {
+            encoding: "utf8",
+            timeout: 2_000,
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return "";
+    }
+}
+function listProcesses() {
+    try {
+        return execFileSync("ps", ["-axww", "-o", "pid=,pgid=,command="], {
+            encoding: "utf8",
+            timeout: 5_000,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+    }
+    catch {
+        return "";
+    }
+}
+function processGroupId(pid) {
+    try {
+        const value = execFileSync("ps", ["-p", String(pid), "-o", "pgid="], {
+            encoding: "utf8",
+            timeout: 2_000,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        return Number.parseInt(value.trim(), 10) || -1;
+    }
+    catch {
+        return -1;
+    }
+}
+function signalProcessGroup(pgid, signal) {
+    if (process.platform === "win32")
+        return false;
+    try {
+        process.kill(-pgid, signal);
+        return true;
+    }
+    catch (error) {
+        return error.code === "ESRCH";
+    }
+}
+function terminateProcessGroup(pgid) {
+    if (process.platform === "win32")
+        return false;
+    try {
+        process.kill(-pgid, "SIGTERM");
+        return true;
+    }
+    catch (error) {
+        return error.code === "ESRCH";
+    }
+}
+export function newRuntimeProcessTag() {
+    return `native-${randomUUID().replaceAll("-", "")}`;
+}

package/dist/codex-app-server/ws-channel.d.ts

@@ -8,6 +8,8 @@ export interface WsRpcChannelOptions {
     logger?: TransportLogger;
     /** Ms to wait for the app-server to accept a connection. */
     readyTimeoutMs?: number;
+    /** Durable per-session runtime state used for targeted crash reconciliation. */
+    stateDir?: string;
 }
 export declare class WsRpcChannel implements RpcChannel {
     private readonly opts;
@@ -16,6 +18,8 @@ export declare class WsRpcChannel implements RpcChannel {
     private lineCb;
     private closeCb;
     private closedEmitted;
+    private processTag;
+    private stopTask;
     private readonly readyTimeoutMs;
     /** The `ws://IP:PORT` the app-server listens on — pass to the TUI's `--remote`. */
     url: string;
@@ -30,6 +34,9 @@ export declare class WsRpcChannel implements RpcChannel {
     start(): Promise<void>;
     send(line: string): Promise<void>;
     stop(signal?: NodeJS.Signals): Promise<void>;
+    private stopOwnedProcess;
+    private signalChild;
+    private unregisterProcess;
     private emitClose;
     private connectWithRetry;
     private tryConnect;

package/dist/codex-app-server/ws-channel.js

@@ -16,6 +16,7 @@ import { spawn } from "node:child_process";
 import { createServer } from "node:net";
 import { WebSocket } from "ws";
 import { createCodexChildEnv } from "../codex-child-env.js";
+import { newRuntimeProcessTag, reconcileRuntimeProcesses, registerRuntimeProcess, runtimeProcessArgv0, runtimeProcessOwnerIdentity, unregisterRuntimeProcess, withRuntimeProcessStateArg, } from "./process-registry.js";
 /** Reserve a free loopback TCP port (best-effort; racy but fine for local use). */
 async function freeLoopbackPort() {
     return await new Promise((resolve, reject) => {
@@ -36,6 +37,8 @@ export class WsRpcChannel {
     lineCb = null;
     closeCb = null;
     closedEmitted = false;
+    processTag = null;
+    stopTask = null;
     readyTimeoutMs;
     /** The `ws://IP:PORT` the app-server listens on — pass to the TUI's `--remote`. */
     url = "";
@@ -53,16 +56,48 @@ export class WsRpcChannel {
         return this.ws?.readyState === WebSocket.OPEN;
     }
     async start() {
+        this.stopTask = null;
+        this.closedEmitted = false;
+        if (this.opts.stateDir) {
+            reconcileRuntimeProcesses();
+        }
         const port = await freeLoopbackPort();
         this.url = `ws://127.0.0.1:${port}`;
-        const args = [...this.opts.baseArgs, "--listen", this.url];
+        const baseArgs = this.opts.stateDir
+            ? withRuntimeProcessStateArg(this.opts.baseArgs, this.opts.stateDir)
+            : this.opts.baseArgs;
+        const args = [...baseArgs, "--listen", this.url];
+        const processTag = this.opts.stateDir ? newRuntimeProcessTag() : null;
+        this.processTag = processTag;
         this.child = spawn(this.opts.cliPath, args, {
             stdio: ["ignore", "ignore", "pipe"],
             env: { ...createCodexChildEnv(process.env), ...(this.opts.extraEnv ?? {}) },
+            detached: process.platform !== "win32",
+            ...(processTag ? { argv0: runtimeProcessArgv0(this.opts.cliPath, processTag) } : {}),
+        });
+        const childPid = this.child.pid;
+        if (processTag && this.opts.stateDir && childPid) {
+            registerRuntimeProcess({
+                pid: childPid,
+                pgid: childPid,
+                ownerPid: process.pid,
+                ownerIdentity: runtimeProcessOwnerIdentity(process.pid),
+                sessionTag: processTag,
+                stateDir: this.opts.stateDir,
+            });
+        }
+        this.child.on("exit", (code, signal) => {
+            this.unregisterProcess();
+            this.emitClose(code, signal, null);
         });
-        this.child.on("exit", (code, signal) => this.emitClose(code, signal, null));
         this.child.on("error", (error) => this.emitClose(null, null, error));
-        this.ws = await this.connectWithRetry(this.url);
+        try {
+            this.ws = await this.connectWithRetry(this.url);
+        }
+        catch (error) {
+            await this.stop();
+            throw error;
+        }
         this.ws.on("message", (data) => {
             // One JSON-RPC object per frame (codex ws framing).
             this.lineCb?.(data.toString());
@@ -86,6 +121,12 @@ export class WsRpcChannel {
         });
     }
     async stop(signal = "SIGTERM") {
+        if (this.stopTask)
+            return await this.stopTask;
+        this.stopTask = this.stopOwnedProcess(signal);
+        return await this.stopTask;
+    }
+    async stopOwnedProcess(signal) {
         try {
             this.ws?.close();
         }
@@ -93,14 +134,33 @@ export class WsRpcChannel {
             /* already closing */
         }
         const child = this.child;
-        if (child) {
-            try {
-                child.kill(signal);
-            }
-            catch {
-                /* already gone */
+        if (child && child.exitCode === null && child.signalCode === null) {
+            this.signalChild(child, signal);
+            if (!await waitForExit(child, 5_000)) {
+                this.signalChild(child, "SIGKILL");
+                await waitForExit(child, 2_000);
             }
         }
+        this.unregisterProcess();
+        this.child = null;
+        this.ws = null;
+    }
+    signalChild(child, signal) {
+        try {
+            if (process.platform !== "win32" && child.pid)
+                process.kill(-child.pid, signal);
+            else
+                child.kill(signal);
+        }
+        catch {
+            // Already gone.
+        }
+    }
+    unregisterProcess() {
+        const tag = this.processTag;
+        this.processTag = null;
+        if (tag)
+            unregisterRuntimeProcess(tag);
     }
     emitClose(code, signal, error) {
         if (this.closedEmitted)
@@ -146,6 +206,22 @@ export class WsRpcChannel {
         });
     }
 }
+function waitForExit(child, timeoutMs) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return Promise.resolve(true);
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            child.off("exit", onExit);
+            resolve(false);
+        }, timeoutMs);
+        timer.unref?.();
+        const onExit = () => {
+            clearTimeout(timer);
+            resolve(true);
+        };
+        child.once("exit", onExit);
+    });
+}
 /**
  * Connect-only {@link RpcChannel}: attaches an ADDITIONAL client to an app-server
  * someone else already started (a {@link WsRpcChannel}'s `url`) — no spawn. This

package/dist/host.d.ts

@@ -143,6 +143,7 @@ export declare class LocalAgentHost implements CodexCapabilities {
     /** Claude forwarders stopped before their terminal is killed. Runner shutdown
      * finalizes these synchronously afterwards to scrub raw interaction answers. */
     private readonly pendingClaudeFinalizers;
+    private readonly pendingCleanupTasks;
     private readonly liveEnsuring;
     private readonly forkingTargets;
     /** Short-lived dedupe for managed fork notifications delivered after the
@@ -208,11 +209,16 @@ export declare class LocalAgentHost implements CodexCapabilities {
      * SAME thread the structured data channel drives.
      */
     codexTerminalSpec(localThreadId: string): Promise<{
+        lifecycle: "required" | "auxiliary";
         command: string;
         args: string[];
         cwd: string;
         env?: Record<string, string>;
         skipTraexStartupPrompts?: boolean;
+        scrollback?: number;
+        tmuxAllowPassthrough?: boolean;
+        tmuxStartOnAttach?: boolean;
+        keepAliveAfterExit?: boolean;
     } | null>;
     /**
      * Bring up (idempotently) a session's persistent codex forwarder and emit its
@@ -302,9 +308,11 @@ export declare class LocalAgentHost implements CodexCapabilities {
      * forwarder and per-session app-server as one disposable runtime envelope;
      * the next message recreates that envelope and cold-resumes the native id. */
     teardownLiveCodexSession(localThreadId: string, error?: Error): boolean;
+    teardownAuxiliaryTerminalRuntime(localThreadId: string): Promise<void>;
     /** Complete the second shutdown phase after the runner has killed all native
      * terminals and hook subprocesses. Must run before the runner process exits. */
-    finalizeStoppedLiveSessions(): void;
+    finalizeStoppedLiveSessions(): Promise<void>;
+    private trackCleanup;
     /** The interactive `claude` TUI spec for a claude-native live session: the real
      *  `claude` binary with rynx's hooks (`--settings`), resuming the bound session.
      *  Trust is pre-seeded so the daemon-spawned TUI never blocks on a first-run