@rynx-ai/runtime 0.1.11-beta.3 → 0.1.11-beta.30

package/dist/terminal/tmux.js

@@ -16,7 +16,7 @@
  */
 import { execFile, execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, unlinkSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 const TMUX_TARGET = "main";
@@ -26,6 +26,15 @@ const DEFAULT_ROWS = 24;
  *  wheel-scroll (tmux copy-mode, enabled by `mouse on`) reaches as far back as
  *  the terminal shows. Mirrors reference implementation's `TerminalEnvSpec.scrollback`. */
 const DEFAULT_SCROLLBACK = 20000;
+/** Resolve the exact tmux executable selected by the current Rynx distribution. */
+export function resolveTmuxBin(explicit, env = process.env) {
+    if (explicit !== undefined)
+        return explicit;
+    if (Object.hasOwn(env, "RYNX_TMUX_BIN")) {
+        return env.RYNX_TMUX_BIN?.trim() ?? "";
+    }
+    return "tmux";
+}
 /** Deterministic private socket owned by one terminal name. Parent-side
  * shutdown uses the same mapping when the runner child is too wedged to clean
  * up its own tmux server. */
@@ -33,35 +42,72 @@ export function tmuxSocketPath(name) {
     const key = createHash("sha256").update(name).digest("hex").slice(0, 16);
     return join(tmpdir(), "rynx-term", `${key}.sock`);
 }
-/** Kill one private tmux server and verify it no longer answers. Missing
- * sockets are already stopped; an existing socket with an unusable tmux
- * command is unproven and returns false. */
-export function terminateTmuxServer(name, tmuxBin = "tmux") {
+/** Read tmux's own output-activity clock for a private terminal window.
+ *
+ * `#{window_activity}` is an epoch timestamp updated by tmux whenever the pane
+ * emits bytes. It is deliberately queried out-of-process rather than inferred
+ * from Rynx's forwarded PTY stream: the forwarder/status path is exactly what
+ * may have stalled when the idle reaper needs an independent liveness signal.
+ * Missing servers, command failures, timeouts, and unparseable output are all
+ * treated as unknown (`null`). */
+export function tmuxWindowActivityAt(name, tmuxBin = resolveTmuxBin()) {
+    const socketPath = tmuxSocketPath(name);
+    return new Promise((resolve) => {
+        execFile(tmuxBin, ["-S", socketPath, "display-message", "-p", "-t", TMUX_TARGET, "#{window_activity}"], { timeout: 2_000 }, (error, stdout) => {
+            if (error) {
+                resolve(null);
+                return;
+            }
+            const raw = stdout.toString().trim();
+            if (!raw) {
+                resolve(null);
+                return;
+            }
+            const value = Number(raw);
+            resolve(Number.isFinite(value) ? value : null);
+        });
+    });
+}
+/** Whether tmux itself reports an attached client for this private terminal.
+ * This remains authoritative if a parent-side attachment bookkeeping edge was
+ * missed during a transport failure. */
+export function tmuxHasAttachedClient(name, tmuxBin = resolveTmuxBin()) {
+    const socketPath = tmuxSocketPath(name);
+    return new Promise((resolve) => {
+        execFile(tmuxBin, ["-S", socketPath, "list-clients", "-t", TMUX_TARGET, "-F", "#{client_name}"], { timeout: 2_000 }, (error, stdout) => {
+            resolve(!error && stdout.toString().split("\n").some((line) => line.trim().length > 0));
+        });
+    });
+}
+/** Best-effort close of one private tmux server. Mirrors reference implementation's bounded
+ * `TerminalInstance.close`: attempt `kill-server`, then retire the private
+ * socket regardless of command outcome. The registry has already forgotten
+ * the resource, so cleanup failure is diagnostic rather than a second
+ * lifecycle state. */
+export function terminateTmuxServer(name, tmuxBin = resolveTmuxBin()) {
     const socketPath = tmuxSocketPath(name);
     if (!existsSync(socketPath))
         return true;
     const base = ["-u", "-S", socketPath];
     try {
-        execFileSync(tmuxBin, [...base, "kill-server"], { stdio: "ignore" });
+        execFileSync(tmuxBin, [...base, "kill-server"], {
+            stdio: "ignore",
+            timeout: 5_000,
+        });
     }
     catch {
-        // A server may have exited between existsSync and kill-server. Verify below.
+        // reference implementation treats close as best-effort and still retires the resource.
     }
     try {
-        execFileSync(tmuxBin, [...base, "has-session", "-t", TMUX_TARGET], {
-            stdio: "ignore",
-        });
-        return false;
+        unlinkSync(socketPath);
     }
-    catch (error) {
-        return !(error &&
-            typeof error === "object" &&
-            "code" in error &&
-            error.code === "ENOENT");
+    catch {
+        // Gone already, or best-effort filesystem cleanup failed.
     }
+    return true;
 }
 /** Is a usable `tmux` on PATH? Cheap probe for the capability gate. */
-export function isTmuxAvailable(tmuxBin = "tmux") {
+export function isTmuxAvailable(tmuxBin = resolveTmuxBin()) {
     try {
         execFileSync(tmuxBin, ["-V"], { stdio: "ignore" });
         return true;
@@ -94,6 +140,14 @@ export class TmuxTerminal {
     tmuxBin;
     injectedSpawn;
     started = false;
+    lastPaneSnapshot = "";
+    /** Shared by every attachment watcher and by the lifecycle watcher's
+     * pane-dead stage. One Terminal must never fan the same tmux control probe
+     * out once per attached client. */
+    paneLivenessFlight;
+    /** Shared by lifecycle callers so capture + pane-dead remains one ordered
+     * reference implementation-style observation per Terminal. */
+    lifecycleLivenessFlight;
     constructor(opts) {
         this.name = opts.name;
         this.cwd = opts.cwd;
@@ -102,7 +156,7 @@ export class TmuxTerminal {
         this.env = withUtf8Locale(opts.env ?? process.env);
         this.cols = opts.cols ?? DEFAULT_COLS;
         this.rows = opts.rows ?? DEFAULT_ROWS;
-        this.tmuxBin = opts.tmuxBin ?? "tmux";
+        this.tmuxBin = resolveTmuxBin(opts.tmuxBin);
         this.injectedSpawn = opts.ptySpawn;
         const dir = join(tmpdir(), "rynx-term");
         mkdirSync(dir, { recursive: true });
@@ -124,15 +178,8 @@ export class TmuxTerminal {
     start() {
         if (this.started)
             return;
-        // Clear any stale server on this socket (a crashed prior run / a test rerun
-        // reusing the name); the socket is unique per session, so this only ever
-        // reaps our own leftover, never a live sibling.
-        try {
-            execFileSync(this.tmuxBin, [...this.base(), "kill-server"], { stdio: "ignore" });
-        }
-        catch {
-            // No stale server — expected on a fresh start.
-        }
+        // Clear any stale server on this deterministic private socket before launch.
+        terminateTmuxServer(this.name, this.tmuxBin);
         // `new-session -d` starts detached; `-x/-y` seed the pane size so output
         // wraps sanely before the first client attaches and resizes it.
         execFileSync(this.tmuxBin, [
@@ -238,21 +285,95 @@ export class TmuxTerminal {
     /** Async pane-liveness probe — MUST NOT block the event loop. The attach
      *  pane-death watcher polls this on an interval; a synchronous `execFileSync`
      *  there stalls the runner child's event loop (freezing the PTY stream → the
-     *  terminal appears "stuck"). reference implementation's `_tmux_session_alive` uses an async
-     *  subprocess + timeout for exactly this reason. */
-    isAliveAsync() {
+     *  terminal appears "stuck"). Exactly like reference implementation's definitive pane probe,
+     *  every command error is `unknown`; only `#{pane_dead}=1` is `dead`. */
+    livenessAsync() {
         if (!this.started)
-            return Promise.resolve(false);
-        return new Promise((resolve) => {
+            return Promise.resolve("dead");
+        if (this.paneLivenessFlight)
+            return this.paneLivenessFlight;
+        const flight = new Promise((resolve) => {
             execFile(this.tmuxBin, [...this.base(), "list-panes", "-t", TMUX_TARGET, "-F", "#{pane_dead}"], { timeout: 2000 }, (err, stdout) => {
                 if (err) {
-                    resolve(false);
+                    resolve("unknown");
                     return;
                 }
                 const panes = stdout.toString().split(/\s+/).filter(Boolean);
-                resolve(panes.length > 0 && !panes.includes("1"));
+                if (panes.includes("1")) {
+                    resolve("dead");
+                }
+                else if (panes.length > 0) {
+                    resolve("alive");
+                }
+                else {
+                    resolve("unknown");
+                }
             });
         });
+        this.paneLivenessFlight = flight;
+        void flight.then(() => {
+            if (this.paneLivenessFlight === flight)
+                delete this.paneLivenessFlight;
+        }, () => {
+            if (this.paneLivenessFlight === flight)
+                delete this.paneLivenessFlight;
+        });
+        return flight;
+    }
+    /** reference implementation's always-on terminal lifecycle watcher first captures the pane:
+     * a control command that ran and reports the target missing is terminal exit;
+     * a probe that cannot spawn is inconclusive. If capture succeeds, the normal
+     * definitive `pane_dead` probe distinguishes live from exited. */
+    lifecycleLivenessAsync() {
+        if (!this.started)
+            return Promise.resolve("dead");
+        if (this.lifecycleLivenessFlight)
+            return this.lifecycleLivenessFlight;
+        const flight = new Promise((resolve) => {
+            execFile(this.tmuxBin, [...this.base(), "capture-pane", "-t", TMUX_TARGET, "-p", "-e"], (error, stdout) => {
+                if (error) {
+                    const code = typeof error === "object" && error && "code" in error
+                        ? error.code
+                        : undefined;
+                    resolve(typeof code === "number" ? "dead" : "unknown");
+                    return;
+                }
+                this.lastPaneSnapshot = stdout.toString();
+                void this.livenessAsync().then((liveness) => {
+                    // A successful capture proves the target exists. reference implementation treats a
+                    // subsequent pane-dead probe failure as non-dead for this tick.
+                    resolve(liveness === "dead" ? "dead" : "alive");
+                });
+            });
+        });
+        this.lifecycleLivenessFlight = flight;
+        void flight.then(() => {
+            if (this.lifecycleLivenessFlight === flight)
+                delete this.lifecycleLivenessFlight;
+        }, () => {
+            if (this.lifecycleLivenessFlight === flight)
+                delete this.lifecycleLivenessFlight;
+        });
+        return flight;
+    }
+    /** Compatibility boolean for callers that cannot represent an inconclusive
+     * probe. Unknown must remain live so a transient tmux failure cannot tear down
+     * a healthy native Session. */
+    async isAliveAsync() {
+        return await this.livenessAsync() !== "dead";
+    }
+    /** PID of the process currently owning the pane. */
+    panePid() {
+        if (!this.started)
+            return undefined;
+        try {
+            const value = execFileSync(this.tmuxBin, [...this.base(), "list-panes", "-t", TMUX_TARGET, "-F", "#{pane_pid}"], { stdio: ["ignore", "pipe", "ignore"] }).toString().trim().split(/\s+/)[0];
+            const pid = Number(value);
+            return Number.isSafeInteger(pid) && pid > 0 ? pid : undefined;
+        }
+        catch {
+            return undefined;
+        }
     }
     /** Type literal text into the pane (agent injection / co-drive from a
      *  non-PTY caller). `-l` sends the text literally rather than as key names. */
@@ -267,13 +388,15 @@ export class TmuxTerminal {
      */
     capturePane() {
         try {
-            return execFileSync(this.tmuxBin, [...this.base(), "capture-pane", "-t", TMUX_TARGET, "-p"], {
+            const snapshot = execFileSync(this.tmuxBin, [...this.base(), "capture-pane", "-t", TMUX_TARGET, "-p"], {
                 env: this.env,
                 encoding: "utf8",
             });
+            this.lastPaneSnapshot = snapshot;
+            return snapshot;
         }
         catch {
-            return "";
+            return this.lastPaneSnapshot;
         }
     }
     /** Send a submit Enter as a KEY NAME (no `-l`), committing the input line.
@@ -319,14 +442,17 @@ export class TmuxTerminal {
     }
     /**
      * Attach a client. `role: "read-only"` passes tmux `-r` so the viewer cannot
-     * type (defense-in-depth on top of the WS bridge dropping input frames).
+     * type and `ignore-size` so even its initial PTY dimensions cannot resize the
+     * owner's pane (defense-in-depth on top of the WS bridge dropping input and
+     * resize frames).
      */
     async attach(role, dims) {
         this.start();
         const spawn = this.injectedSpawn ?? (await loadPtySpawn());
-        const args = [...this.base(), "attach-session", "-t", TMUX_TARGET];
+        const args = [...this.base(), "attach-session"];
         if (role === "read-only")
-            args.push("-r");
+            args.push("-r", "-f", "ignore-size");
+        args.push("-t", TMUX_TARGET);
         const proc = spawn(this.tmuxBin, args, {
             name: "xterm-256color",
             cols: dims?.cols ?? this.cols,
@@ -363,8 +489,8 @@ export class TmuxTerminal {
                     return;
                 // ASYNC probe (never execFileSync here — that would block the event loop
                 // and freeze the PTY stream, making the terminal unresponsive).
-                void this.isAliveAsync().then((alive) => {
-                    if (!alive && !exited)
+                void this.livenessAsync().then((liveness) => {
+                    if (liveness === "dead" && !exited)
                         fireExit(0);
                 });
             }, 1000);
@@ -386,12 +512,7 @@ export class TmuxTerminal {
     }
     /** Kill the tmux server (ends the session and all attaches). */
     kill() {
-        try {
-            execFileSync(this.tmuxBin, [...this.base(), "kill-server"], { stdio: "ignore" });
-        }
-        catch {
-            // Already gone — nothing to clean up.
-        }
+        terminateTmuxServer(this.name, this.tmuxBin);
         this.started = false;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rynx-ai/runtime",
-  "version": "0.1.11-beta.3",
+  "version": "0.1.11-beta.30",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/rynx-ai/rynx.git",
@@ -24,9 +24,10 @@
     }
   },
   "dependencies": {
-    "node-pty": "^1.0.0",
+    "node-pty": "1.2.0-beta.15",
+    "smol-toml": "1.7.1",
     "ws": "^8.21.0",
-    "@rynx-ai/core": "0.1.11-beta.3"
+    "@rynx-ai/core": "0.1.11-beta.30"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1"