@sentropic/h2a-runtime 0.98.0 → 0.98.2

package/dist/native-terminal/op.js

@@ -29,15 +29,20 @@
  *                                     (detach: Ctrl-\\ ; exits when session exits)
  *   host-stop                         SIGTERM the host process (sessions stop)
  */
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync, writeSync } from "node:fs";
 import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { NativeTerminalClient } from "./client.js";
 import { loadRegistry, registryEntriesForNativeTarget } from "../registry.js";
-import { NATIVE_TERMINAL_INTERACTIVE_READ_TIMEOUT_MS, NativeTerminalRemoteError, } from "./protocol.js";
+import { NATIVE_TERMINAL_INTERACTIVE_READ_TIMEOUT_MS, NATIVE_TERMINAL_PROTOCOL_VERSION, NativeTerminalRemoteError, } from "./protocol.js";
 import { NativeTerminalHostSupervisor } from "./supervisor.js";
-import { defaultNativeTerminalSocketPath } from "./socket-path.js";
+import { proveNativeTerminalEndpointAbsent } from "./server.js";
+import { defaultNativeTerminalSocketPath, knownNativeTerminalSocketPaths, inspectPrivateNativeTerminalSocket, sameNativeTerminalSocket } from "./socket-path.js";
+import { collectNativeInventory, resolveNativeOwner } from "./fleet.js";
 import { renderTerminalScreen } from "./screen.js";
+import { TerminalModeTracker } from "./terminal-modes.js";
+import { publishAttachReset } from "./attach-recovery.js";
+import { TerminalResetRelay } from "./reset-relay.js";
 const DETACH_BYTE = 0x1c; // Ctrl-\
 function parseArgv(argv) {
     const op = argv[2];
@@ -95,11 +100,81 @@ export function closeAllNativeTerminalOpClients() {
         client.close();
     openClients.clear();
 }
-async function connectExisting(socketPath) {
+async function connectExisting(socketPath, tracked = true) {
+    const identity = await inspectPrivateNativeTerminalSocket(socketPath);
     const client = await NativeTerminalClient.connect(socketPath);
-    openClients.add(client);
+    if (tracked)
+        openClients.add(client);
+    try {
+        const ping = await client.ping();
+        if (ping.protocolVersion !== NATIVE_TERMINAL_PROTOCOL_VERSION || !ping.generation?.trim() ||
+            !Number.isSafeInteger(ping.hostPid) || ping.hostPid <= 0 ||
+            !sameNativeTerminalSocket(identity, await inspectPrivateNativeTerminalSocket(socketPath))) {
+            throw new Error("native host identity changed or handshake is invalid");
+        }
+    }
+    catch (error) {
+        client.close();
+        throw error;
+    }
     return client;
 }
+class NativeOwnerError extends Error {
+    refusal;
+    constructor(refusal) {
+        super(`native session ${refusal.id}: ${refusal.code}${refusal.reason ? ` (${refusal.reason})` : ""}`);
+        this.refusal = refusal;
+    }
+}
+async function inventoryFor(parsed) {
+    const pinned = parsed.flags.get("socket");
+    return collectNativeInventory(pinned ? [pinned] : knownNativeTerminalSocketPaths(), connectExisting, proveNativeTerminalEndpointAbsent);
+}
+async function owningClient(parsed, id) {
+    const owner = resolveNativeOwner(id, await inventoryFor(parsed));
+    if (owner.state !== "found")
+        throw new NativeOwnerError({ code: owner.state, id,
+            ...(owner.state === "unknown" ? { reason: owner.reason } : {}),
+            ...(owner.state === "ambiguous-owner" ? { sockets: owner.sockets } : {}) });
+    return owner;
+}
+async function selectLaunchClient(fenced) {
+    const paths = knownNativeTerminalSocketPaths();
+    const imposed = process.env["H2A_NATIVE_SOCKET"];
+    if (imposed) {
+        const client = await launchClient(imposed);
+        // An imposed endpoint can never silently redirect, even when its mate is
+        // available. Capability certification is performed by the caller.
+        return { client, socketPath: imposed };
+    }
+    const historical = paths[0];
+    const client = await launchClient(historical);
+    const ping = await client.ping();
+    if (!fenced || paths.length === 1)
+        return { client, socketPath: historical };
+    const compatible = paths[1];
+    // Initialize the second known endpoint so admission obtains a complete
+    // inventory even when the historical host already provides the fence.
+    const second = await launchClient(compatible);
+    return ping.launchFence === true ? { client, socketPath: historical } : { client: second, socketPath: compatible };
+}
+async function launchClient(socketPath) {
+    try {
+        return await connectExisting(socketPath);
+    }
+    catch (error) {
+        let absent = false;
+        try {
+            absent = await proveNativeTerminalEndpointAbsent(socketPath, error);
+        }
+        catch (proofError) {
+            error = new Error(`${error instanceof Error ? error.message : String(error)}; absence proof failed: ${proofError instanceof Error ? proofError.message : String(proofError)}`);
+        }
+        if (absent)
+            return ensureClient(socketPath);
+        throw Object.assign(new Error(`${socketPath}: ${error instanceof Error ? error.message : String(error)}; owner death is unproven. Inspect endpoint permissions and the owning process identity, restore probe access, then retry; do not remove a socket or lock while ownership is unproven.`), { socketPath });
+    }
+}
 async function ensureClient(socketPath) {
     const supervisor = new NativeTerminalHostSupervisor({
         socketPath,
@@ -176,17 +251,37 @@ const ATTACH_RECONNECT_MIN_MS = 100;
 const ATTACH_RECONNECT_MAX_MS = 2_000;
 const ATTACH_PENDING_INPUT_MAX_BYTES = 64 * 1024;
 function defaultAttachRuntime(socketPath) {
+    const signals = { SIGTERM: 15, SIGHUP: 1, SIGINT: 2, SIGQUIT: 3 };
+    const handlers = new Map();
     return {
         // runAttach owns and closes every reconnecting client. Keeping these
         // long-lived clients in the one-shot op registry would retain each closed
         // connection until the user eventually detaches.
-        connect: () => NativeTerminalClient.connect(socketPath),
+        connect: () => connectExisting(socketPath, false),
         stdin: process.stdin,
         stdout: process.stdout,
         now: () => Date.now(),
         delay,
         onResize: (listener) => process.on("SIGWINCH", listener),
         offResize: (listener) => process.removeListener("SIGWINCH", listener),
+        saveTerminalReset: publishAttachReset,
+        onTerminate: (listener) => {
+            for (const [signal, number] of Object.entries(signals)) {
+                const handler = () => { listener(); process.exit(128 + number); };
+                handlers.set(signal, handler);
+                process.on(signal, handler);
+            }
+            process.on("exit", listener);
+            // Observe the fatal path without suppressing Node's error/exit behavior.
+            process.on("uncaughtExceptionMonitor", listener);
+        },
+        offTerminate: (listener) => {
+            for (const [signal, handler] of handlers)
+                process.removeListener(signal, handler);
+            handlers.clear();
+            process.removeListener("exit", listener);
+            process.removeListener("uncaughtExceptionMonitor", listener);
+        },
     };
 }
 function isDefinitiveNativeTerminalAbsence(error) {
@@ -205,10 +300,50 @@ function isDefinitiveNativeTerminalAbsence(error) {
 export async function runAttach(id, runtime = defaultAttachRuntime(socketPathFromEnv())) {
     const stdin = runtime.stdin;
     const stdout = runtime.stdout;
+    let modes = new TerminalModeTracker();
+    let modesSuspended = false;
+    let savedReset = "";
+    const saveReset = () => {
+        const reset = modesSuspended ? "" : modes.resetSequence();
+        if (reset === savedReset)
+            return;
+        runtime.saveTerminalReset?.(reset);
+        savedReset = reset;
+    };
+    const relayOutput = (data) => {
+        modes.feed(data);
+        saveReset();
+        stdout.write(data);
+    };
+    // Older protocol-v1 hosts relay the wrapper marker verbatim. New hosts
+    // consume it themselves so detached sessions also return to a clean shell.
+    let resetRelay = new TerminalResetRelay(relayOutput, () => modes.resetSequence());
+    const resetModes = () => {
+        if (modesSuspended)
+            return;
+        modesSuspended = true;
+        const reset = modes.resetSequence();
+        if (!reset) {
+            saveReset();
+            return;
+        }
+        // Signals and fatal exits cannot wait for an asynchronous pipe flush.
+        const fd = stdout.fd;
+        if (typeof fd === "number")
+            writeSync(fd, reset);
+        else
+            stdout.write(reset);
+        saveReset();
+    };
+    const resumeModes = () => {
+        if (!modesSuspended)
+            return;
+        modesSuspended = false;
+        saveReset();
+        stdout.write(modes.restoreSequence() + modes.replayPrefix());
+    };
     const isRawCapable = stdin.isTTY === true;
-    if (isRawCapable)
-        stdin.setRawMode(true);
-    stdin.resume();
+    const wasRaw = stdin.isRaw === true;
     let detached = false;
     let terminalEnded = false;
     let exitCode = 0;
@@ -223,6 +358,20 @@ export async function runAttach(id, runtime = defaultAttachRuntime(socketPathFro
         active = undefined;
         current?.client.close();
     };
+    const terminate = () => {
+        detached = true;
+        try {
+            resetRelay.flush();
+            resetModes();
+        }
+        finally {
+            if (isRawCapable)
+                stdin.setRawMode(wasRaw);
+            stdin.pause();
+            closeActive();
+        }
+    };
+    runtime.onTerminate?.(terminate);
     const markTransportFailure = (connection, error, inputDeliveryUncertain = false) => {
         if (inputDeliveryUncertain && !detached) {
             stdout.write("\r\n[h2a] terminal input delivery became uncertain during reconnect; " +
@@ -287,6 +436,8 @@ export async function runAttach(id, runtime = defaultAttachRuntime(socketPathFro
         pumpInput();
     };
     stdin.on("data", onInput);
+    const onEnd = () => { detached = true; closeActive(); };
+    stdin.on("end", onEnd);
     const resize = () => {
         const current = active;
         if (current && stdout.columns && stdout.rows) {
@@ -319,6 +470,9 @@ export async function runAttach(id, runtime = defaultAttachRuntime(socketPathFro
     // Paint the existing scrollback once, then follow the stream.
     let seq = 0;
     try {
+        if (isRawCapable)
+            stdin.setRawMode(true);
+        stdin.resume();
         const initial = await connectAndAcquire();
         if (initial.status === "exited")
             return initial.exit?.exitCode ?? 0;
@@ -334,6 +488,7 @@ export async function runAttach(id, runtime = defaultAttachRuntime(socketPathFro
                         "without restarting the session\r\n");
                     recoveryAnnounced = true;
                 }
+                resetModes();
                 let reconnectDelayMs = ATTACH_RECONNECT_MIN_MS;
                 for (;;) {
                     if (detached)
@@ -346,6 +501,7 @@ export async function runAttach(id, runtime = defaultAttachRuntime(socketPathFro
                             break;
                         }
                         stdout.write("\r\n[h2a] native terminal reconnected\r\n");
+                        resumeModes();
                         recoveryAnnounced = false;
                         idlePollMs = ATTACH_IDLE_POLL_MIN_MS;
                         nextStatePollAt = runtime.now() + ATTACH_STATE_POLL_MS;
@@ -353,7 +509,6 @@ export async function runAttach(id, runtime = defaultAttachRuntime(socketPathFro
                     }
                     catch (error) {
                         if (isDefinitiveNativeTerminalAbsence(error)) {
-                            stdout.write("\r\n[h2a] native session is no longer available; attach stopped\r\n");
                             exitCode = 1;
                             terminalEnded = true;
                             break;
@@ -369,10 +524,22 @@ export async function runAttach(id, runtime = defaultAttachRuntime(socketPathFro
             const current = active;
             try {
                 const replay = await current.client.readOutput(id, seq, NATIVE_TERMINAL_INTERACTIVE_READ_TIMEOUT_MS);
+                if (detached)
+                    break;
+                if (replay.gap) {
+                    resetModes();
+                    modes = new TerminalModeTracker();
+                    resetRelay = new TerminalResetRelay(relayOutput, () => modes.resetSequence());
+                    modesSuspended = false;
+                    if (replay.terminalModePrefix) {
+                        resetRelay.feed(replay.terminalModePrefix);
+                    }
+                }
                 for (const chunk of replay.chunks) {
-                    stdout.write(chunk.data);
+                    resetRelay.feed(chunk.data);
                     seq = chunk.seq;
                 }
+                seq = replay.latestSeq;
                 if (replay.chunks.length === 0) {
                     await runtime.delay(idlePollMs);
                     idlePollMs = Math.min(ATTACH_IDLE_POLL_MAX_MS, idlePollMs * 2);
@@ -406,55 +573,65 @@ export async function runAttach(id, runtime = defaultAttachRuntime(socketPathFro
         }
     }
     finally {
-        runtime.offResize(resize);
-        stdin.removeListener("data", onInput);
-        if (isRawCapable)
-            stdin.setRawMode(false);
-        stdin.pause();
-        if (inputPump !== undefined)
-            await inputPump.catch(() => { });
-        const current = active;
-        active = undefined;
-        if (current !== undefined) {
-            await current.client.releaseController(current.lease).catch(() => { });
-            current.client.close();
+        try {
+            resetRelay.flush();
+            if (detached)
+                stdout.write("\r\n[h2a] detached from native session (session keeps running)\r\n");
+            resetModes();
+        }
+        finally {
+            runtime.offTerminate?.(terminate);
+            runtime.offResize(resize);
+            stdin.removeListener("data", onInput);
+            stdin.removeListener("end", onEnd);
+            if (isRawCapable)
+                stdin.setRawMode(wasRaw);
+            stdin.pause();
+            if (inputPump !== undefined)
+                await inputPump.catch(() => { });
+            const current = active;
+            active = undefined;
+            if (current !== undefined) {
+                await current.client.releaseController(current.lease).catch(() => { });
+                current.client.close();
+            }
         }
-    }
-    if (detached) {
-        stdout.write("\r\n[h2a] detached from native session (session keeps running)\r\n");
     }
     return exitCode;
 }
 export async function runNativeTerminalOp(argv) {
     const parsed = parseArgv(argv);
-    const socketPath = socketPathFromEnv();
+    const socketPath = parsed.flags.get("socket") ?? socketPathFromEnv();
     switch (parsed.op) {
         case "ensure-host": {
-            const client = await ensureClient(socketPath);
+            let selected;
+            try {
+                selected = parsed.flags.has("socket") ? { client: await connectExisting(socketPath), socketPath }
+                    : await selectLaunchClient(parsed.flags.get("fenced") === "true");
+            }
+            catch (error) {
+                emit({ code: "native-inventory-unknown", hosts: [{ socketPath: error?.socketPath ?? socketPath,
+                            reason: error instanceof Error ? error.message : String(error) }] });
+                return 1;
+            }
+            const { client } = selected;
             const ping = await client.ping();
             client.close();
-            emit({ hostPid: ping.hostPid, generation: ping.generation, socketPath, launchFence: ping.launchFence === true });
+            emit({ hostPid: ping.hostPid, generation: ping.generation, socketPath: selected.socketPath, launchFence: ping.launchFence === true });
             return 0;
         }
         case "list": {
-            let client;
-            try {
-                client = await connectExisting(socketPath);
-            }
-            catch {
-                emit({ sessions: [] });
-                return 0;
-            }
-            const sessions = await client.list();
-            client.close();
-            emit({ sessions });
+            const inventory = await inventoryFor(parsed);
+            emit({ sessions: inventory.sessions, complete: inventory.complete,
+                hosts: inventory.hosts.map(({ socketPath, reason, absent }) => ({ socketPath, reachable: !absent && reason === undefined, ...(absent ? { absent } : {}), ...(reason ? { reason } : {}) })) });
             return 0;
         }
         case "state": {
-            const client = await connectExisting(socketPath);
+            const owner = await owningClient(parsed, required(parsed, "id"));
+            const { client } = owner;
             const state = await client.state(required(parsed, "id"));
             client.close();
-            emit(state);
+            emit({ ...state, socketPath: owner.socketPath });
             return 0;
         }
         case "probe": {
@@ -462,53 +639,46 @@ export async function runNativeTerminalOp(argv) {
             // generic nonzero exit, so the synchronous caller never has to guess
             // whether a failure meant "no session" or "the op broke":
             //  - live:    a reachable host answered and the session is running
-            //  - dead:    POSITIVE proof — a reachable host does not know the
-            //             session, or no host is listening at all (a PTY cannot
-            //             outlive its host process — the tmux-server death rule)
-            //  - unknown: anything else; never proof of death.
+            //  - dead:    every known reachable endpoint proves absence, or the
+            //             owning endpoint reports an exited session
+            //  - unknown: an incomplete inventory without a found owner; even
+            //             transport errors without an independent owner-death proof.
             const id = required(parsed, "id");
-            let client;
-            try {
-                client = await connectExisting(socketPath);
-            }
-            catch (error) {
-                const code = error.code;
-                if (code === "ECONNREFUSED" || code === "ENOENT") {
-                    emit({ verdict: "dead", reason: `native host is not running (${code})` });
-                }
-                else {
-                    emit({
-                        verdict: "unknown",
-                        reason: error instanceof Error ? error.message : String(error),
-                    });
-                }
-                return 0;
-            }
-            try {
-                const state = await client.state(id);
-                emit({
-                    verdict: state.status === "running" ? "live" : "dead",
-                    state,
-                });
-            }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                // The host's own "unknown terminal session" refusal is a POSITIVE
-                // absence verdict from a reachable host; any other remote/protocol
-                // error proves nothing (fail closed on the caller side).
-                emit(error instanceof NativeTerminalRemoteError &&
-                    message.includes("unknown terminal session")
-                    ? { verdict: "dead", reason: message }
-                    : { verdict: "unknown", reason: message });
-            }
-            finally {
-                client.close();
-            }
+            const owner = resolveNativeOwner(id, await inventoryFor(parsed));
+            if (owner.state === "found")
+                emit({ verdict: owner.session.status === "running" ? "live" : "dead",
+                    state: { ...owner.session, socketPath: owner.socketPath } });
+            else if (owner.state === "absent")
+                emit({ verdict: "dead" });
+            else
+                emit({ verdict: "unknown", code: owner.state,
+                    ...(owner.state === "unknown" ? { reason: owner.reason } : { sockets: owner.sockets, reason: "ambiguous-owner" }) });
+            return 0;
+        }
+        case "admit": {
+            const inventory = await inventoryFor({ ...parsed, flags: new Map() });
+            const ids = [required(parsed, "id"), parsed.flags.get("sidecar")].filter((id) => !!id);
+            const collision = inventory.sessions.find(session => ids.includes(session.id) &&
+                (session.status !== "exited" || session.socketPath !== parsed.flags.get("launch-socket")));
+            emit(collision ? { code: "native-name-collision", id: collision.id, socketPath: collision.socketPath }
+                : !inventory.complete ? { code: "native-inventory-unknown", hosts: inventory.hosts.map(({ socketPath, reason }) => ({ socketPath, reason })) }
+                    : { admitted: true });
             return 0;
         }
         case "create": {
-            const client = await ensureClient(socketPath);
+            const client = parsed.flags.has("socket") ? await connectExisting(socketPath) : await ensureClient(socketPath);
             const id = required(parsed, "id");
+            if (parsed.flags.has("incarnation") || socketPath.endsWith("/native-terminal.lf1.sock")) {
+                if (parsed.flags.has("incarnation") && (await client.ping()).launchFence !== true)
+                    throw new Error("selected native host does not provide launchFence");
+                const inventory = await inventoryFor({ ...parsed, flags: new Map() });
+                const ids = [id, ...(parsed.flags.has("sidecar") ? [required(parsed, "sidecar")]
+                        : !id.endsWith(".h2a") ? [`${id}.h2a`] : [])];
+                if (!inventory.complete || inventory.sessions.some(session => ids.includes(session.id) &&
+                    (session.status !== "exited" || session.socketPath !== socketPath))) {
+                    throw new Error("native creation admission changed; refusing possible name collision");
+                }
+            }
             const cwd = required(parsed, "cwd");
             const cols = Number(parsed.flags.get("cols") ?? 160);
             const rows = Number(parsed.flags.get("rows") ?? 48);
@@ -535,7 +705,8 @@ export async function runNativeTerminalOp(argv) {
             return 0;
         }
         case "drive": {
-            const target = nativeDriveSessionId(required(parsed, "target"));
+            const target = parsed.flags.has("id")
+                ? { state: "found", id: required(parsed, "id") } : nativeDriveSessionId(required(parsed, "target"));
             if (target.state === "unresolved") {
                 emit({ outcome: "unresolved" });
                 return 0;
@@ -552,7 +723,7 @@ export async function runNativeTerminalOp(argv) {
                 });
                 return 0;
             }
-            const client = await connectExisting(socketPath);
+            const { client } = await owningClient(parsed, target.id);
             try {
                 let lease;
                 try {
@@ -581,8 +752,8 @@ export async function runNativeTerminalOp(argv) {
         }
         case "write":
         case "paste": {
-            const client = await connectExisting(socketPath);
             const id = required(parsed, "id");
+            const { client } = await owningClient(parsed, id);
             const text = Buffer.from(required(parsed, "b64"), "base64").toString("utf8");
             await withController(client, id, async (lease) => {
                 if (parsed.op === "paste") {
@@ -598,14 +769,14 @@ export async function runNativeTerminalOp(argv) {
             return 0;
         }
         case "enter": {
-            const client = await connectExisting(socketPath);
+            const { client } = await owningClient(parsed, required(parsed, "id"));
             await withController(client, required(parsed, "id"), (lease) => client.write(lease, "\r"));
             client.close();
             emit({ ok: true });
             return 0;
         }
         case "capture": {
-            const client = await connectExisting(socketPath);
+            const { client } = await owningClient(parsed, required(parsed, "id"));
             const raw = await readAll(client, required(parsed, "id"));
             client.close();
             const budget = Number(parsed.flags.get("bytes") ?? 16384);
@@ -615,15 +786,23 @@ export async function runNativeTerminalOp(argv) {
             return 0;
         }
         case "pid": {
-            const client = await connectExisting(socketPath);
+            const { client } = await owningClient(parsed, required(parsed, "id"));
             const state = await client.state(required(parsed, "id"));
             client.close();
             emit({ pid: state.pid, status: state.status });
             return 0;
         }
+        case "resize": {
+            const id = required(parsed, "id");
+            const { client } = await owningClient(parsed, id);
+            await withController(client, id, lease => client.resize(lease, Number(required(parsed, "cols")), Number(required(parsed, "rows"))));
+            emit({ ok: true });
+            return 0;
+        }
+        case "stop":
         case "kill": {
-            const client = await connectExisting(socketPath);
             const id = required(parsed, "id");
+            const { client } = await owningClient(parsed, id);
             const signal = parsed.flags.get("signal") ?? "SIGTERM";
             if (signal !== "SIGTERM" && signal !== "SIGKILL" && signal !== "SIGINT" && signal !== "SIGHUP") {
                 throw new Error(`unsupported signal: ${signal}`);
@@ -653,9 +832,10 @@ export async function runNativeTerminalOp(argv) {
             emit(after);
             return after.status === "exited" ? 0 : 1;
         }
+        case "stop-if-incarnation":
         case "kill-if-incarnation": {
-            const client = await connectExisting(socketPath);
             const id = required(parsed, "id");
+            const { client } = await owningClient(parsed, id);
             const generation = required(parsed, "generation");
             const incarnation = required(parsed, "incarnation");
             const signal = parsed.flags.get("signal") ?? "SIGTERM";
@@ -687,7 +867,11 @@ export async function runNativeTerminalOp(argv) {
             return after.status === "exited" ? 0 : 1;
         }
         case "attach": {
-            return runAttach(required(parsed, "id"), defaultAttachRuntime(socketPath));
+            const id = required(parsed, "id");
+            const owner = await owningClient(parsed, id);
+            owner.client.close();
+            // Reconnects retain this owner for the entire interactive operation.
+            return runAttach(id, defaultAttachRuntime(owner.socketPath));
         }
         case "host-stop": {
             let client;
@@ -726,6 +910,8 @@ if (isEntryPoint()) {
         .then((code) => {
         process.exitCode = code;
     }, (error) => {
+        if (error instanceof NativeOwnerError)
+            emit(error.refusal);
         process.stderr.write(`[h2a-native-op] ${error instanceof Error ? error.message : String(error)}\n`);
         process.exitCode = 1;
     })