@rynx-ai/runtime 0.1.11-beta.20 → 0.1.11-beta.22

package/dist/runner/manager.js

@@ -22,9 +22,9 @@ import { fileURLToPath } from "node:url";
 import { AgentRuntimeError, } from "@rynx-ai/core";
 import { listRuntimeModels } from "../models-catalog.js";
 import { probeRuntimeStatus } from "../runtime-status.js";
-import { terminateTmuxServer } from "../terminal/tmux.js";
+import { terminateTmuxServer, tmuxHasAttachedClient, tmuxWindowActivityAt, } from "../terminal/tmux.js";
 import { fromWireError, } from "./protocol.js";
-import { isManagedNativeProvider } from "./startup-policy.js";
+import { isCodexLineageProvider, isManagedNativeProvider } from "./startup-policy.js";
 import { StdioRunnerTransport } from "./transport.js";
 /** Routing key for the shared capability runner (slash-command RPCs). */
 const CAP_KEY = "__cap__";
@@ -34,9 +34,8 @@ const STDERR_TAIL_LINES = 40;
 const DEFAULT_SHUTDOWN_GRACE_MS = 5_000;
 /** Time allowed for exit after SIGKILL before shutdown reports failure. */
 const DEFAULT_SHUTDOWN_KILL_GRACE_MS = 5_000;
-/** Setup-pane launch includes the app-server readiness phase but does not wait
- * for native thread discovery. Keep enough headroom around the app-server's
- * own 10s gate so scheduling/IPC overhead cannot win the same deadline. */
+/** Legacy setup-pane acknowledgement deadline for providers that do not own
+ * phase-specific startup errors. Codex/Traex are deliberately excluded. */
 const DEFAULT_LIVE_START_TIMEOUT_MS = 30_000;
 /** Legacy fallback for a provider without a native startup policy. */
 const DEFAULT_LIVE_READY_TIMEOUT_MS = 25_000;
@@ -51,12 +50,10 @@ const DEFAULT_TERMINAL_INPUT_HANDOFF_TIMEOUT_MS = 30_000;
 /** Retry transient terminal-server cleanup without spinning forever. */
 const DEFAULT_TERMINAL_INPUT_CLEANUP_RETRY_MS = 1_000;
 const MAX_TERMINAL_INPUT_CLEANUP_RETRY_MS = 30_000;
-/** A Provider that never closes its active response must not keep a detached
- * runner + tmux server alive forever. This is intentionally much longer than
- * the normal idle TTL so legitimate long-running turns are not treated as
- * stale. User input/control activity refreshes the deadline; Provider output
- * does not, because a runaway redraw loop is the failure mode this bounds. */
-const DEFAULT_STALE_ACTIVE_TTL_MS = 60 * 60_000;
+/** Full idle window before an inactive native pane becomes reapable. */
+const DEFAULT_NATIVE_PANE_IDLE_TTL_MS = 60 * 60_000;
+/** tmux output this recent independently proves that a native pane is busy. */
+const DEFAULT_NATIVE_PANE_OUTPUT_BUSY_WINDOW_MS = 120_000;
 /** Keep per-Session spawn context small enough to remain an environment handoff,
  * not an unbounded transport. */
 const MAX_SESSION_CONTEXT_ENV_ENTRIES = 32;
@@ -157,7 +154,8 @@ export class RunnerManager {
     sessionStore;
     runnerEntry;
     idleTtlMs;
-    staleActiveTtlMs;
+    nativePaneIdleTtlMs;
+    nativePaneOutputBusyWindowMs;
     spawn;
     childEnv;
     sessionContextProvider;
@@ -174,12 +172,16 @@ export class RunnerManager {
     shutdownKillGraceMs;
     signalChild;
     terminateTerminalServer;
+    terminalWindowActivityAt;
+    terminalHasAttachedClient;
+    wallNow;
     liveStartTimeoutMs;
     liveReadyTimeoutMs;
     nativeLiveStartTimeoutMs;
     liveInterruptTimeoutMs;
     terminalInputHandoffTimeoutMs;
     terminalInputCleanupRetryMs;
+    reapPromise = null;
     stopping = false;
     stopPromise;
     /** Sink for mirrored {@link SessionEvent}s from every session's forwarder. */
@@ -213,18 +215,22 @@ export class RunnerManager {
         this.sessionStore = opts.sessionStore;
         this.runnerEntry = opts.runnerEntry ?? defaultRunnerEntry();
         this.idleTtlMs = opts.idleTtlMs ?? 300_000;
-        this.staleActiveTtlMs = Math.max(this.idleTtlMs, opts.staleActiveTtlMs ?? DEFAULT_STALE_ACTIVE_TTL_MS);
+        this.nativePaneIdleTtlMs = opts.nativePaneIdleTtlMs ?? DEFAULT_NATIVE_PANE_IDLE_TTL_MS;
+        this.nativePaneOutputBusyWindowMs = Math.max(0, opts.nativePaneOutputBusyWindowMs ?? DEFAULT_NATIVE_PANE_OUTPUT_BUSY_WINDOW_MS);
         this.spawn = opts.spawn ?? nodeSpawn;
         this.childEnv = opts.childEnv ?? {};
         this.sessionContextProvider = opts.sessionContextProvider;
         this.admissionOpen = opts.admissionOpen ?? (() => true);
         this.admissionReserve = opts.admissionReserve;
         this.now = opts.now ?? (() => Date.now());
+        this.wallNow = opts.wallNow ?? (() => Date.now());
         this.defaultRuntime = opts.config.DEFAULT_RUNTIME ?? "codex";
         this.shutdownGraceMs = Math.max(0, opts.shutdownGraceMs ?? DEFAULT_SHUTDOWN_GRACE_MS);
         this.shutdownKillGraceMs = Math.max(0, opts.shutdownKillGraceMs ?? DEFAULT_SHUTDOWN_KILL_GRACE_MS);
         this.signalChild = opts.signalChild ?? signalRunnerChild;
         this.terminateTerminalServer = opts.terminateTerminalServer ?? terminateTmuxServer;
+        this.terminalWindowActivityAt = opts.terminalWindowActivityAt ?? tmuxWindowActivityAt;
+        this.terminalHasAttachedClient = opts.terminalHasAttachedClient ?? tmuxHasAttachedClient;
         this.liveStartTimeoutMs = Math.max(1, opts.liveStartTimeoutMs ?? DEFAULT_LIVE_START_TIMEOUT_MS);
         this.liveReadyTimeoutMs = Math.max(1, opts.liveReadyTimeoutMs ?? DEFAULT_LIVE_READY_TIMEOUT_MS);
         this.nativeLiveStartTimeoutMs = Math.max(1, opts.nativeLiveStartTimeoutMs ?? DEFAULT_NATIVE_LIVE_START_TIMEOUT_MS);
@@ -233,7 +239,7 @@ export class RunnerManager {
         this.terminalInputCleanupRetryMs = Math.max(1, opts.terminalInputCleanupRetryMs ?? DEFAULT_TERMINAL_INPUT_CLEANUP_RETRY_MS);
         const reapIntervalMs = opts.reapIntervalMs ?? 60_000;
         if (reapIntervalMs > 0) {
-            this.reapTimer = setInterval(() => this.reapIdle(), reapIntervalMs);
+            this.reapTimer = setInterval(() => void this.reapIdle(), reapIntervalMs);
             this.reapTimer.unref?.();
         }
         else {
@@ -502,9 +508,10 @@ export class RunnerManager {
     /**
      * Eagerly bring up a session's codex-native live view (persistent forwarder +
      * detached `codex --remote` TUI) in its runner child, spawning the runner if
-     * needed. Idempotent. For Codex-lineage fresh sessions, resolves after the
-     * app-server/observer and pane are launched; thread discovery continues in
-     * parallel with injection. Other providers retain their readiness gate.
+     * needed. Idempotent. For Codex-lineage sessions, resolves after backend
+     * preload and pane launch; known-thread observer attach and fresh-thread
+     * discovery continue in the background. Other providers retain their
+     * readiness gate.
      */
     ensureLiveSession(localThreadId, opts) {
         const admission = this.reserveAdmission();
@@ -543,55 +550,66 @@ export class RunnerManager {
         this.liveSessionKeys.add(localThreadId);
         const reqId = randomUUID();
         return new Promise((resolve) => {
-            const timeoutMs = !waitForReady
-                ? this.liveStartTimeoutMs
-                : opts.execution.provider === "claude"
-                    ? this.nativeLiveStartTimeoutMs
-                    : isManagedNativeProvider(opts.execution.provider)
-                        ? this.liveStartTimeoutMs
+            const provider = opts.execution.provider;
+            const timeoutMs = isCodexLineageProvider(provider)
+                ? null
+                : !waitForReady
+                    ? this.liveStartTimeoutMs
+                    : provider === "claude"
+                        ? this.nativeLiveStartTimeoutMs
                         : this.liveReadyTimeoutMs;
-            const timeout = setTimeout(() => {
-                if (!handle.live.delete(reqId))
-                    return;
-                const finishTimeout = () => {
-                    const provider = opts.execution.provider;
-                    const reason = !waitForReady
-                        ? `runner did not acknowledge terminal start within ${timeoutMs}ms`
-                        : provider === "claude"
-                            ? `Claude SessionStart was not observed within ${Math.round(timeoutMs / 1_000)}s; the runner process was reset before retry`
-                            : provider === "codex" || provider === "traex"
-                                ? `${provider === "traex" ? "Traex" : "Codex"} app-server/observer/Terminal launch was not acknowledged within ${Math.round(timeoutMs / 1_000)}s; the runner process was reset before retry`
+            const timeout = timeoutMs === null
+                ? undefined
+                : setTimeout(() => {
+                    if (!handle.live.delete(reqId))
+                        return;
+                    const finishTimeout = () => {
+                        const reason = !waitForReady
+                            ? `runner did not acknowledge terminal start within ${timeoutMs}ms`
+                            : provider === "claude"
+                                ? `Claude SessionStart was not observed within ${Math.round(timeoutMs / 1_000)}s; the runner process was reset before retry`
                                 : `runner did not acknowledge live readiness within ${timeoutMs}ms`;
-                    this.liveErrors.set(localThreadId, reason);
-                    this.liveSessionKeys.delete(localThreadId);
-                    // A child that cannot answer a bounded control round-trip is unsafe
-                    // to reuse. Reap it so the next click gets a fresh runner.
-                    void this.terminateHandle(handle, reason).catch((error) => {
-                        logTerminationFailure(handle, error);
-                    });
-                    return false;
-                };
-                const reservation = allowReservedForkTarget
-                    ? undefined
-                    : this.forkReservations.get(localThreadId);
-                if (reservation) {
-                    void reservation
-                        .then(() => finishTimeout())
-                        .then(resolve, () => resolve(false));
-                    return;
-                }
-                resolve(finishTimeout());
-            }, timeoutMs);
-            timeout.unref?.();
+                        this.liveErrors.set(localThreadId, {
+                            message: reason,
+                            code: provider === "claude"
+                                ? "claude_session_start_timeout"
+                                : "native_runner_ack_timeout",
+                            statusCode: 503,
+                        });
+                        this.liveSessionKeys.delete(localThreadId);
+                        // Legacy providers without phase-owned startup errors retain the
+                        // bounded control guard. Codex/Traex never enter this branch.
+                        void this.terminateHandle(handle, reason).catch((error) => {
+                            logTerminationFailure(handle, error);
+                        });
+                        return false;
+                    };
+                    const reservation = allowReservedForkTarget
+                        ? undefined
+                        : this.forkReservations.get(localThreadId);
+                    if (reservation) {
+                        void reservation
+                            .then(() => finishTimeout())
+                            .then(resolve, () => resolve(false));
+                        return;
+                    }
+                    resolve(finishTimeout());
+                }, timeoutMs);
+            timeout?.unref?.();
             handle.live.set(reqId, (res) => {
-                clearTimeout(timeout);
+                if (timeout)
+                    clearTimeout(timeout);
                 const ok = res.ok ?? false;
                 const finish = () => {
                     if (ok) {
                         this.liveErrors.delete(localThreadId);
                     }
                     else {
-                        this.liveErrors.set(localThreadId, res.error ?? "live session did not become ready");
+                        this.liveErrors.set(localThreadId, res.error ?? {
+                            message: "live session did not become ready",
+                            code: "native_readiness_failed",
+                            statusCode: 503,
+                        });
                     }
                     return ok;
                 };
@@ -619,7 +637,11 @@ export class RunnerManager {
         });
     }
     lastLiveSessionError(localThreadId) {
-        return this.liveErrors.get(localThreadId);
+        return this.liveErrors.get(localThreadId)?.message;
+    }
+    lastLiveSessionFailure(localThreadId) {
+        const failure = this.liveErrors.get(localThreadId);
+        return failure ? { ...failure } : undefined;
     }
     /**
      * Inject a user turn into a session's live codex thread — reference implementation's
@@ -648,11 +670,19 @@ export class RunnerManager {
             handle.live.set(reqId, (res) => {
                 const outcome = res.outcome ?? "failed";
                 const finish = () => {
-                    if (outcome === "injected") {
+                    if (outcome === "injected" || outcome === "steered") {
                         this.liveErrors.delete(localThreadId);
                     }
                     else {
-                        this.liveErrors.set(localThreadId, res.error ?? `live injection ${outcome}`);
+                        this.liveErrors.set(localThreadId, res.error ?? {
+                            message: `live injection ${outcome}`,
+                            code: outcome === "notReady"
+                                ? "native_thread_not_ready"
+                                : outcome === "notLive"
+                                    ? "native_session_not_live"
+                                    : "native_message_injection_failed",
+                            statusCode: 503,
+                        });
                     }
                     return outcome;
                 };
@@ -707,7 +737,7 @@ export class RunnerManager {
             handle.live.set(reqId, (reply) => {
                 resolve(reply.interactionResult ?? {
                     disposition: "invalid",
-                    message: reply.error ?? "runner did not return an interaction result",
+                    message: reply.error?.message ?? "runner did not return an interaction result",
                 });
             });
             handle.transport.send({
@@ -902,7 +932,6 @@ export class RunnerManager {
                 !allowReservedForkTarget) {
                 throw new AgentRuntimeError("Session fork is still being committed", 409, "session_fork_pending");
             }
-            this.reapIdle();
             const existing = this.handles.get(key);
             if (existing && !existing.dead) {
                 existing.lastUsedAt = this.now();
@@ -1312,7 +1341,10 @@ export class RunnerManager {
             terminal._fail(message);
         }
         for (const resolve of handle.live.values()) {
-            resolve({ ok: false, error: message });
+            resolve({
+                ok: false,
+                error: { message, code: "runner_crashed", statusCode: 500 },
+            });
         }
         handle.caps.clear();
         handle.terminals.clear();
@@ -1369,8 +1401,24 @@ export class RunnerManager {
         return attempt;
     }
     reapIdle() {
+        if (this.reapPromise)
+            return this.reapPromise;
+        const attempt = this.reapIdleOnce();
+        this.reapPromise = attempt;
+        const clear = () => {
+            if (this.reapPromise === attempt)
+                this.reapPromise = null;
+        };
+        void attempt.then(clear, clear);
+        return attempt;
+    }
+    async reapIdleOnce() {
         const now = this.now();
         for (const [key, handle] of this.handles) {
+            if (this.isManagedNativeHandle(handle)) {
+                await this.reapNativePane(handle, now);
+                continue;
+            }
             if (handle.caps.size > 0 || handle.terminals.size > 0 || handle.live.size > 0) {
                 continue;
             }
@@ -1379,28 +1427,74 @@ export class RunnerManager {
                 continue;
             }
             const hasActiveResponse = handle.activeResponseIds.size > 0;
-            if (hasActiveResponse && idleForMs < this.staleActiveTtlMs) {
+            if (hasActiveResponse)
                 continue;
-            }
-            const reason = hasActiveResponse
-                ? "stale active runner reaped"
-                : this.liveSessionKeys.has(key)
-                    ? "idle live runner reaped"
-                    : "idle runner reaped";
-            if (hasActiveResponse) {
-                this.failStaleActiveResponses(handle, idleForMs);
-            }
+            const reason = this.liveSessionKeys.has(key)
+                ? "idle live runner reaped"
+                : "idle runner reaped";
             void this.terminateHandle(handle, reason).catch((error) => {
                 logTerminationFailure(handle, error);
             });
         }
     }
-    /** Close server-side runtime state before fencing a Provider that stayed
-     * active past its hard inactivity deadline. The child transport is closed by
-     * terminateHandle immediately afterwards, so these are the final events for
-     * the abandoned responses. */
-    failStaleActiveResponses(handle, idleForMs) {
-        this.failActiveResponses(handle, "stale_runner_reaped", `Runner was reaped after ${Math.floor(idleForMs / 1000)}s without user activity`);
+    /** Provider-authoritative turn state is the lifecycle truth; attached clients
+     * and tmux's own activity clock are independent busy evidence. There is no
+     * "user was inactive for an hour" override for an active turn. */
+    async reapNativePane(handle, now) {
+        if (this.nativePaneIdleTtlMs <= 0 || handle.dead)
+            return;
+        if (await this.isNativePaneBusy(handle)) {
+            handle.nativePaneLastBusyAt = now;
+            return;
+        }
+        const lastBusyAt = handle.nativePaneLastBusyAt;
+        if (lastBusyAt === undefined) {
+            // First idle observation starts a full grace window.
+            handle.nativePaneLastBusyAt = now;
+            return;
+        }
+        if (now - lastBusyAt < this.nativePaneIdleTtlMs)
+            return;
+        // Close the select→reap race: activity may begin after classification but
+        // before teardown.
+        if (await this.isNativePaneBusy(handle)) {
+            handle.nativePaneLastBusyAt = this.now();
+            return;
+        }
+        // A failed teardown must re-arm on the next scan instead of retrying on
+        // every sweep forever.
+        delete handle.nativePaneLastBusyAt;
+        await this.terminateHandle(handle, "idle native pane reaped").catch((error) => logTerminationFailure(handle, error));
+    }
+    async isNativePaneBusy(handle) {
+        if (handle.activeResponseIds.size > 0 ||
+            handle.caps.size > 0 ||
+            handle.live.size > 0 ||
+            handle.terminals.size > 0) {
+            return true;
+        }
+        const terminalName = `${handle.key}-main`;
+        try {
+            if (await this.terminalHasAttachedClient(terminalName))
+                return true;
+        }
+        catch {
+            // A failed probe contributes no busy evidence; check activity next.
+        }
+        let activityAt = null;
+        try {
+            activityAt = await this.terminalWindowActivityAt(terminalName);
+        }
+        catch {
+            // A failed probe contributes no busy evidence.
+        }
+        return activityAt !== null &&
+            this.wallNow() - activityAt * 1_000 < this.nativePaneOutputBusyWindowMs;
+    }
+    isManagedNativeHandle(handle) {
+        const sessionId = this.currentTerminalSessionId(handle, handle.key);
+        const provider = this.liveOptions.get(sessionId)?.execution.provider;
+        return isManagedNativeProvider(provider);
     }
     failActiveResponses(handle, code, message) {
         const responseIds = [...handle.activeResponseIds];
@@ -1418,8 +1512,9 @@ export class RunnerManager {
             });
         }
     }
-    /** Track only response lifecycle, not output volume. Output deltas from a
-     * runaway TUI/Provider must not refresh the stale-active deadline. */
+    /** Track the provider-authoritative response lifecycle. Native-pane busy
+     * classification consumes this level directly; output volume is separately
+     * grounded in tmux's own activity clock. */
     observeHandleRuntimeEvent(handle, event) {
         switch (event.type) {
             case "response.created":

package/dist/runner/protocol.d.ts

@@ -6,7 +6,8 @@
  * (`live.ensure` / `inject` / `live.interrupt`) plus per-thread capabilities and
  * terminal attachment; the reply channels mirror each request's `reqId`.
  */
-import { AgentRuntimeError, type ResolvedExecutionSnapshot, type RuntimeUserInput, type SessionInteractionResolution, type SessionEvent, type SessionWorkspaceSnapshot } from "@rynx-ai/core";
+import { AgentRuntimeError, type InjectOutcome, type ResolvedExecutionSnapshot, type RuntimeUserInput, type SessionInteractionResolution, type SessionEvent, type SessionWorkspaceSnapshot } from "@rynx-ai/core";
+export type { InjectOutcome } from "@rynx-ai/core";
 import type { ResolveInteractionResult } from "../interactions.js";
 /** A runtime error flattened for the wire; rebuilt parent-side as `AgentRuntimeError`. */
 export interface WireError {
@@ -22,13 +23,6 @@ export type TerminalRole = "owner" | "read-only";
 /** Stable reason for a terminal attach failure. `terminal_not_live` is an
  * expected, retryable absence; `terminal_open_failed` is an infrastructure error. */
 export type TerminalOpenErrorCode = "terminal_not_live" | "terminal_open_failed";
-/** Outcome of an `inject`. `injected` = the app-server / tmux accepted the turn.
- *  `notLive` = no live forwarder for this session (caller may use the run path).
- *  `notReady` = live but not ready within the park window; `failed` = injection
- *  threw. For BOTH notReady and failed the caller reports an error and MUST NOT
- *  re-run the turn (re-running would double-write alongside the forwarder).
- *  Mirrors reference implementation's "inject failure ⇒ response.failed, never re-run locally". */
-export type InjectOutcome = "injected" | "notLive" | "notReady" | "failed";
 /** Parent → child. Terminal PTY bytes ride `term.input` base64-encoded so the
  *  NDJSON line framing stays intact (raw bytes contain newlines). */
 export type ToChild = {
@@ -70,9 +64,9 @@ export type ToChild = {
 }
 /** Eagerly bring up a session's live codex TUI + forwarder (codex-native), so
  *  its turns mirror to the bus regardless of whether the web has attached the
- *  terminal. For Codex-lineage fresh sessions, `live.ready` acknowledges that
- *  the pane and observer exist; background thread discovery races the
- *  executor's bridge wait. */
+ *  terminal. Fresh sessions connect the discovery listener before TUI launch;
+ *  known-thread resumes launch the TUI after backend preload and attach their
+ *  observer in the background. */
  | {
     t: "live.ensure";
     reqId: string;
@@ -161,25 +155,26 @@ export type FromChild = {
     execution: ResolvedExecutionSnapshot;
     parentSessionId?: string;
 }
-/** Result of a `live.ensure`: for Codex-lineage sessions `ok` means the pane
- *  and observer started; thread discovery continues in parallel with
- *  injection. Other Providers retain their own readiness gate. */
+/** Result of a `live.ensure`: for Codex-lineage sessions `ok` means backend
+ *  preload and pane launch completed. A resume observer and fresh-thread
+ *  discovery may continue in the background. Other Providers retain their
+ *  own readiness gate. */
  | {
     t: "live.ready";
     reqId: string;
     localThreadId: string;
     ok: boolean;
-    error?: string;
+    error?: WireError;
 }
-/** Result of an `inject`: `outcome` distinguishes injected / notLive / notReady /
- *  failed so the caller never falls back to a second output path on a live
- *  session. Echoes the request `reqId`. */
+/** Result of an `inject`: `outcome` distinguishes a new turn, an active-turn
+ *  steer, and failures so the caller never falls back to a second output path.
+ *  Echoes the request `reqId`. */
  | {
     t: "injected";
     reqId: string;
     localThreadId: string;
     outcome: InjectOutcome;
-    error?: string;
+    error?: WireError;
 }
 /** Result of a `live.interrupt`: `ok` when an active turn was interrupted (false
  *  when there was none). Echoes the request `reqId`. */
@@ -188,7 +183,7 @@ export type FromChild = {
     reqId: string;
     localThreadId: string;
     ok: boolean;
-    error?: string;
+    error?: WireError;
 } | {
     t: "interaction.resolved";
     reqId: string;

package/dist/runner/startup-policy.d.ts

@@ -2,3 +2,6 @@ import type { AgentRuntimeId } from "@rynx-ai/core";
 /** Current live providers are native CLI sessions. Keep this explicit so a
  * future non-native provider does not silently inherit their startup budget. */
 export declare function isManagedNativeProvider(provider: AgentRuntimeId | undefined): provider is AgentRuntimeId;
+/** Codex-lineage providers own app-server, thread-discovery, and injection
+ * phase errors. Claude instead retains its parent-owned SessionStart gate. */
+export declare function isCodexLineageProvider(provider: AgentRuntimeId | undefined): provider is Exclude<AgentRuntimeId, "claude">;

package/dist/runner/startup-policy.js

@@ -3,3 +3,8 @@
 export function isManagedNativeProvider(provider) {
     return provider === "codex" || provider === "traex" || provider === "claude";
 }
+/** Codex-lineage providers own app-server, thread-discovery, and injection
+ * phase errors. Claude instead retains its parent-owned SessionStart gate. */
+export function isCodexLineageProvider(provider) {
+    return provider === "codex" || provider === "traex";
+}

package/dist/terminal/tmux.d.ts

@@ -49,6 +49,19 @@ export declare function resolveTmuxBin(explicit?: string, env?: NodeJS.ProcessEn
  * shutdown uses the same mapping when the runner child is too wedged to clean
  * up its own tmux server. */
 export declare function tmuxSocketPath(name: string): string;
+/** 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 declare function tmuxWindowActivityAt(name: string, tmuxBin?: string): Promise<number | 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 declare function tmuxHasAttachedClient(name: string, tmuxBin?: string): Promise<boolean>;
 /** 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. */
@@ -113,6 +126,8 @@ export declare class TmuxTerminal {
      *  terminal appears "stuck"). reference implementation's `_tmux_session_alive` uses an async
      *  subprocess + timeout for exactly this reason. */
     isAliveAsync(): Promise<boolean>;
+    /** PID of the process currently owning the pane. */
+    panePid(): number | 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. */
     sendKeys(text: string): void;

package/dist/terminal/tmux.js

@@ -42,6 +42,43 @@ export function tmuxSocketPath(name) {
     const key = createHash("sha256").update(name).digest("hex").slice(0, 16);
     return join(tmpdir(), "rynx-term", `${key}.sock`);
 }
+/** 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));
+        });
+    });
+}
 /** 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. */
@@ -281,6 +318,19 @@ export class TmuxTerminal {
             });
         });
     }
+    /** 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. */
     sendKeys(text) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rynx-ai/runtime",
-  "version": "0.1.11-beta.20",
+  "version": "0.1.11-beta.22",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/rynx-ai/rynx.git",
@@ -27,7 +27,7 @@
     "node-pty": "1.2.0-beta.15",
     "smol-toml": "1.7.1",
     "ws": "^8.21.0",
-    "@rynx-ai/core": "0.1.11-beta.20"
+    "@rynx-ai/core": "0.1.11-beta.22"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1"