zback 1.4.0 → 1.4.2

package/README.md

@@ -1,19 +1,29 @@
 # ZBack CLI
 
-ZBack is an opt-in remote administration agent for systems you own or are authorized to manage. The package uses Node.js 22 or later, has **no third-party runtime dependencies** and runs no installation scripts.
+ZBack is an opt-in remote administration agent for systems you own or are authorized to manage. The package uses Node.js 20 or later, uses the `ws` WebSocket dependency and runs no installation scripts.
 
 > **Security:** ZBack grants remote shell access with your local user privileges to anyone who possesses its private session ID. Treat that ID as a password. Do not publish it, paste it in issue reports, or share screenshots containing it. Do not run ZBack as root or as an account with unnecessary permissions.
 
 ## Install and start
 
+Use Node.js 20 or later. Install dependencies before running `node bin/zback.js` directly from a source archive.
+
 ```sh
-npm install -g zback@1.2.2
+npm install -g .
 zback
 ```
 
-On the first run, ZBack presents a [Y]/[N] shell authorization question once. It stores that decision locally, then creates a private agent credential. There are no prompts for each command.
+On the first run in a terminal, ZBack presents a [Y]/[N] shell authorization question once. It stores the decision locally, then creates a private agent credential. There are no prompts for each command.
+
+For explicitly authorized non-interactive runs (such as GitHub Actions or containers), add `--accept-shell-access` on the first start. This flag grants the same persistent local authorization without needing a TTY. Without previous authorization or that flag, non-interactive startup fails safely. Never add the flag to scripts executed by untrusted contributors, and avoid running ZBack as root.
+
+```sh
+zback --accept-shell-access --url wss://your-domain.example/ws
+```
+
+When using CI, remember that remote execution access lasts for the duration of the workflow job and any person holding the session ID can execute commands with the process privileges. Use trusted workflows and keep the ID private.
 
-Terminal status markers are colored on supported interactive terminals: yellow `[+]` for progress, red `[×]` for errors and gray `>` for contextual hints. Plain text is used when output is redirected. The command history updates as commands complete and shows each command's exit code and cumulative successes/errors. Connection problems are summarized once per incident while reconnect attempts continue automatically.
+Terminal status markers are colored on supported interactive terminals: yellow `[+]` for progress, red `[×]` for errors and gray `>` for contextual hints. Plain text is used when output is redirected. The command history updates as commands complete and shows each command's exit code and cumulative successes/errors. Connection problems are summarized once per incident while reconnect attempts continue automatically. The agent sends WebSocket ping frames to detect silent connection failures, and the log viewer checks whether the background agent is still alive.
 
 The default server is `wss://zb.soymaycol.icu/ws`. To use your own backend:
 
@@ -27,13 +37,16 @@ For development only:
 zback --url ws://127.0.0.1:8787/ws
 ```
 
-The client requires **backend 1.2.0 or later**. The client rejects older servers rather than accepting unstable legacy session IDs. Deploy the updated backend before connecting a remote client.
+The client requires **backend 1.2.0 or later**, and backend **1.2.3 or later** to disable server-side execution timeouts. The client rejects older servers rather than accepting unstable legacy session IDs. Deploy the updated backend before connecting a remote client.
+
+The `ws` dependency is installed automatically by npm. It avoids relying on Node.js exposing a global `WebSocket` and does not run installation scripts.
 
 ## Terminal and process lifecycle
 
 | Command | Behavior |
 | --- | --- |
 | `zback` | Keep the agent in the foreground; display the session ID, MCP endpoint, colored connection notices, and command execution history |
+| `zback --accept-shell-access` | Explicitly authorize first-run shell access without a TTY (CI, non-interactive scripts) |
 | `zback --background` | Explicitly start a detached agent |
 | `zback --status` | Show connection status, process ID and private session ID |
 | `zback --logs` | Display recent connection and command activity |
@@ -52,13 +65,13 @@ zback --cwd ./workspace --timeout 300000 --max-output 524288
 zback --url wss://your-domain.example/ws --background
 ```
 
-The client validates TLS on remote connections. Only loopback addresses are allowed for unencrypted `ws://`. Server resource protection and command timeouts are operational safety controls, not per-user paid quotas.
+The client validates TLS on remote connections. Only loopback addresses are allowed for unencrypted `ws://`. Command execution has no duration timeout by default (`--timeout 0`); you can choose a positive limit using `--timeout <ms>`. Connection watchdogs, queue waiting, output caps and resource safeguards still apply.
 
-Files are under `~/.local/state/zback` on Linux/Termux and `%LOCALAPPDATA%/zback` on Windows. To use a custom location, set `ZBACK_STATE_DIR`. `agent.key` and the local state files must not be shared. Use `zback --reset-key` to invalidate a previously disclosed session ID.
+Files are under `~/.local/state/zback` on Linux/Termux and `%LOCALAPPDATA%/zback` on Windows. To use a custom location, set `ZBACK_STATE_DIR`. `agent.key` and the local state files must not be shared. If a background agent becomes unavailable, `zback --status` will indicate whether its heartbeat is stale. Use `zback --reset-key` to invalidate a previously disclosed session ID.
 
 ## MCP
 
-The companion backend serves `POST /mcp` with `zback_status` and `zback_execute`. On connection, the client displays the MCP endpoint and a **private** session ID, which is supplied as the `id` argument to either tool. Only grant your own session ID to trusted applications. MCP clients, LLMs and tools that receive the ID can perform any command your operating-system account can perform.
+The companion backend serves `POST /mcp` with `zback_status` and `zback_execute`. On connection, the client displays the MCP endpoint and a **private** session ID, which is supplied as the `id` argument to either tool. When your backend uses `ALLOWED_ORIGINS=*`, configure the backend `MCP_ACCESS_TOKEN` as a Bearer credential in your MCP client as well as the private session ID; it is not a substitute for the ID. Never embed either secret in public front-end code. Only grant your own session ID to trusted applications. MCP clients, LLMs and tools that receive the ID can perform any command your operating-system account can perform.
 
 ## Security disclosure and review
 
@@ -69,3 +82,16 @@ The npm package declares its remote administration capabilities as dual-use soft
 ```sh
 npm test
 ```
+
+## Connection health (1.2.6)
+
+Normal WebSocket ping/pong checks update the local health timestamp silently. A
+`Connection restored` message is printed **only after a real WebSocket
+disconnection and a successful new handshake**, never after a routine pong.
+A delayed pong has a 60-second grace period before the client reconnects.
+The private session identifier remains derived from the local agent key and
+does not change on reconnection. If the connection truly closes, the terminal
+now reports the WebSocket close code and available server reason.
+
+Update the backend to 1.2.4 for relaxed server heartbeat handling too. This
+does not change `--timeout 0`, MCP tools, or interactive consent behavior.

package/bin/zback.js

@@ -10,8 +10,14 @@ import { createTerminal, createEventReporter } from '../src/terminal.js';
 import { activeSession, agentKey, consentFile, hasConsent, initStateDir, logFile, readJson, resetKey, sameSession, saveJson, settingsFile, stateFile, alive } from '../src/runtime.js';
 
 const ENTRY = fileURLToPath(import.meta.url);
-const VERSION = '1.2.2';
+const VERSION = '1.2.6';
 const DEFAULT_URL = 'wss://zb.soymaycol.icu/ws';
+const STALE_AFTER_MS = 120000;
+
+function connectionStatus(state) {
+  if (state.status === 'connected' && (!Number.isFinite(Date.parse(state.updated)) || Date.now() - Date.parse(state.updated) > STALE_AFTER_MS)) return 'unresponsive';
+  return state.status;
+}
 
 function help() {
   console.log(`ZBack ${VERSION} | Authorized remote shell administration
@@ -28,19 +34,22 @@ Usage:
 Options:
   --url <wss://.../ws>      Server endpoint (default: ${DEFAULT_URL})
   --cwd <directory>        Working directory for commands
-  --timeout <ms>           Command timeout (1000-3600000)
+  --timeout <ms>           Command timeout (0 = no limit, default: 0)
   --max-output <bytes>     Captured output (1024-786432)
   --no-reconnect           Stop after a connection is lost
+  --accept-shell-access    Authorize remote shell access non-interactively (CI)
   --help                   Display this help
 
 ZBack runs shell commands with your account privileges. Initial interactive
-consent is required once, not for every command. Keep the session ID private.
+consent is required once, not for every command. For CI or other non-TTY
+environments, use --accept-shell-access as an explicit first-run authorization.
+Keep the session ID private; do not run as root unless strictly necessary.
 Ctrl+C stops a foreground agent. Background mode must be requested explicitly.
 Use --stop to disconnect a background agent.`);
 }
 
 export function parseArgs(args) {
-  const options = { url: DEFAULT_URL, cwd: process.cwd(), timeout: 120000, maxOutput: 262144, reconnect: true, background: false };
+  const options = { url: DEFAULT_URL, cwd: process.cwd(), timeout: 0, maxOutput: 262144, reconnect: true, background: false, acceptShellAccess: false };
   const values = new Set(['--url', '--cwd', '--timeout', '--max-output']);
   let action = 'start';
   for (let i = 0; i < args.length; i++) {
@@ -54,6 +63,7 @@ export function parseArgs(args) {
     }
     if (flag === '--background' || flag === '--detach') { options.background = true; continue; }
     if (flag === '--no-reconnect') { options.reconnect = false; continue; }
+    if (flag === '--accept-shell-access') { options.acceptShellAccess = true; continue; }
     if (!values.has(flag) || i + 1 >= args.length) throw new Error(`Unknown or incomplete argument: ${flag}`);
     const value = args[++i];
     if (flag === '--url') options.url = value;
@@ -62,7 +72,7 @@ export function parseArgs(args) {
     if (flag === '--max-output') options.maxOutput = Number(value);
   }
   if (action !== 'start') return { action };
-  if (!Number.isSafeInteger(options.timeout) || options.timeout < 1000 || options.timeout > 3600000) throw new Error('--timeout must be between 1000 and 3600000 ms');
+  if (!Number.isSafeInteger(options.timeout) || options.timeout < 0 || options.timeout > 3600000) throw new Error('--timeout must be between 0 and 3600000 ms');
   if (!Number.isSafeInteger(options.maxOutput) || options.maxOutput < 1024 || options.maxOutput > 786432) throw new Error('--max-output must be between 1024 and 786432 bytes');
   if (!existsSync(options.cwd) || !statSync(options.cwd).isDirectory()) throw new Error('--cwd must be an existing directory');
   const url = new URL(options.url);
@@ -71,9 +81,14 @@ export function parseArgs(args) {
   return { ...options, action };
 }
 
-async function confirmOnce(terminal) {
+async function confirmOnce(terminal, explicitApproval = false) {
   if (hasConsent()) return true;
-  if (!stdin.isTTY || !stdout.isTTY) throw new Error('First-run shell authorization requires an interactive terminal');
+  if (explicitApproval) {
+    saveJson(consentFile, { approved: true, at: new Date().toISOString(), method: 'explicit-cli-flag' });
+    terminal.hint('Shell access authorized by --accept-shell-access. This decision has been saved.');
+    return true;
+  }
+  if (!stdin.isTTY || !stdout.isTTY) throw new Error('First-run shell authorization requires a terminal or the explicit --accept-shell-access option');
   terminal.question();
   const rl = createInterface({ input: stdin, output: stdout });
   try {
@@ -98,8 +113,9 @@ async function worker() {
   const mark = data => {
     const previous = readJson(stateFile);
     if (previous && previous.status !== 'stopped' && previous.pid !== process.pid && alive(previous.pid)) return;
-    saveJson(stateFile, { pid: process.pid, started, version: VERSION, updated: new Date().toISOString(), ...data });
-    if (data.status === 'connected') {
+    const { heartbeat, ...state } = data;
+    saveJson(stateFile, { pid: process.pid, started, version: VERSION, updated: new Date().toISOString(), ...state });
+    if (data.status === 'connected' && !heartbeat) {
       reporter.clearProblem();
       if (!lastId) terminal.connected(data.id, mcpEndpoint(settings.url));
       else terminal.restored();
@@ -128,7 +144,7 @@ function showConnection(id, url) {
 function showStatus() {
   const state = activeSession();
   if (!state) { console.log('Status: stopped'); return false; }
-  console.log(`Status: ${state.status}\nPID: ${state.pid}\nUpdated: ${state.updated || 'unknown'}`);
+  console.log(`Status: ${connectionStatus(state)}\nPID: ${state.pid}\nUpdated: ${state.updated || 'unknown'}`);
   if (state.id) showConnection(state.id, readJson(settingsFile)?.url || DEFAULT_URL);
   return true;
 }
@@ -148,6 +164,7 @@ function recentLog() {
 async function follow() {
   if (!stdin.isTTY || !stdout.isTTY) return;
   console.log('Monitoring background agent. Ctrl+C closes this view; the agent stays active.');
+  const terminal = createTerminal();
   let position = existsSync(logFile) ? statSync(logFile).size : 0;
   await new Promise(resolve => {
     const readNew = () => {
@@ -166,7 +183,32 @@ async function follow() {
         } finally { closeSync(fd); }
       } catch (error) { console.error(`Log monitor: ${error.message}`); }
     };
-    const stop = () => { unwatchFile(logFile, readNew); process.removeListener('SIGINT', stop); process.removeListener('SIGTERM', stop); console.log('\nDetached. Agent continues in the background.'); resolve(); };
+    let finished = false;
+    let wasUnresponsive = false;
+    const stop = (detached = true) => {
+      if (finished) return;
+      finished = true;
+      clearInterval(monitor);
+      unwatchFile(logFile, readNew);
+      process.removeListener('SIGINT', stop);
+      process.removeListener('SIGTERM', stop);
+      if (detached) console.log('\nDetached. Agent continues in the background.');
+      resolve();
+    };
+    const monitor = setInterval(() => {
+      readNew();
+      const session = activeSession();
+      if (!session) {
+        terminal.error(readJson(stateFile)?.status === 'stopped' ? 'Background agent stopped.' : 'Background agent stopped unexpectedly. Use zback to restart it.');
+        stop(false);
+        return;
+      }
+      const unresponsive = connectionStatus(session) === 'unresponsive';
+      if (unresponsive && !wasUnresponsive) {
+        terminal.error('No heartbeat from the agent. Its connection may be unresponsive.', true);
+      }
+      wasUnresponsive = unresponsive;
+    }, 2000);
     watchFile(logFile, { interval: 400 }, readNew);
     process.once('SIGINT', stop);
     process.once('SIGTERM', stop);
@@ -183,12 +225,15 @@ async function start(options) {
       process.exitCode = 1;
       return;
     }
-    terminal.section('+', `Agent already running (${existing.status}, PID ${existing.pid}).`);
+    const status = connectionStatus(existing);
+    terminal.section('+', `Agent already running (${status}, PID ${existing.pid}).`);
     if (existing.id) terminal.connected(existing.id, mcpEndpoint(readJson(settingsFile)?.url || DEFAULT_URL));
+    if (status === 'unresponsive') terminal.error('No recent heartbeat from the agent.', true);
+    else if (status === 'reconnecting') terminal.error('Connection lost', true);
     if (!options.background) await follow();
     return;
   }
-  if (!(await confirmOnce(terminal))) return;
+  if (!(await confirmOnce(terminal, options.acceptShellAccess))) return;
   initStateDir();
   const key = agentKey();
   saveJson(settingsFile, { url: options.url, cwd: options.cwd, timeout: options.timeout, maxOutput: options.maxOutput, reconnect: options.reconnect });
@@ -198,8 +243,9 @@ async function start(options) {
     let lastId = null;
     const reporter = createEventReporter(terminal);
     const mark = data => {
-      saveJson(stateFile, { pid: process.pid, started, version: VERSION, updated: new Date().toISOString(), ...data });
-      if (data.status === 'connected') {
+      const { heartbeat, ...state } = data;
+      saveJson(stateFile, { pid: process.pid, started, version: VERSION, updated: new Date().toISOString(), ...state });
+      if (data.status === 'connected' && !heartbeat) {
         reporter.clearProblem();
         if (!lastId) terminal.connected(data.id, mcpEndpoint(options.url));
         else terminal.restored();

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "zback",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "description": "Opt-in foreground remote shell administration with a persistent WebSocket agent and private session credential",
   "type": "module",
   "bin": {
     "zback": "bin/zback.js"
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=20.0.0"
   },
   "scripts": {
     "test": "node --test"
@@ -15,8 +15,23 @@
   "contentPolicy": {
     "class": "dual-use"
   },
-  "keywords": ["remote-administration", "websocket", "cli", "mcp", "opt-in"],
-  "files": ["bin/", "src/", "README.md", "DISCLOSURE", "LICENSE"],
+  "keywords": [
+    "remote-administration",
+    "websocket",
+    "cli",
+    "mcp",
+    "opt-in"
+  ],
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "DISCLOSURE",
+    "LICENSE"
+  ],
   "license": "MIT",
-  "author": "SoyMaycol"
+  "author": "SoyMaycol",
+  "dependencies": {
+    "ws": "^8.22.0"
+  }
 }

package/src/agent.js

@@ -34,7 +34,7 @@ export function execute(command, cwd, timeoutMs, maxOutput) {
     };
     child.stdout.on('data', b => add('stdout', b));
     child.stderr.on('data', b => add('stderr', b));
-    const timer = setTimeout(() => { timedOut = true; killTree(child); }, timeoutMs);
+    const timer = timeoutMs > 0 ? setTimeout(() => { timedOut = true; killTree(child); }, timeoutMs) : null;
     const finish = (code, message = '') => {
       if (finished) return;
       finished = true;
@@ -53,98 +53,166 @@ export function execute(command, cwd, timeoutMs, maxOutput) {
   });
 }
 
-export async function connectAgent(options, onState, token, onEvent = () => {}) {
+export async function connectAgent(options, onState, token, onEvent = () => {}, socketConstructor) {
+  let WebSocketClient = socketConstructor;
+  if (!WebSocketClient) {
+    try { WebSocketClient = (await import('ws')).default; }
+    catch (error) {
+      if (error.code === 'ERR_MODULE_NOT_FOUND') throw new Error('WebSocket dependency is missing. Run npm install in the zback-client directory, or reinstall ZBack globally.');
+      throw error;
+    }
+  }
+  const heartbeatInterval = options.heartbeatIntervalMs ?? 20000;
+  const pongTimeout = options.pongTimeoutMs ?? 60000;
   let stopped = false;
   let retries = 0;
-  let socket;
-  let cancelDelay;
+  let socket = null;
+  let cancelDelay = null;
   let lastId = null;
-  let lastError = null;
-  const update = (status, data = {}) => onState({ status, ...data });
-  const emit = event => { try { onEvent(event); } catch { /* UI failures must not interrupt command execution. */ } };
+
+  const emit = event => { try { onEvent(event); } catch {} };
+  const update = (status, data = {}) => {
+    try { onState({ status, id: lastId, ...data }); }
+    catch (error) { emit({ type: 'agent-error', problem: `Could not save connection state: ${error.message}` }); }
+  };
   const shutdown = () => {
     stopped = true;
-    if (cancelDelay) cancelDelay();
-    try { socket?.close(1000, 'Agent stopped'); } catch {}
+    cancelDelay?.();
+    try { socket?.terminate(); } catch {}
     killRunningCommands();
   };
+
   process.once('SIGINT', shutdown);
   process.once('SIGTERM', shutdown);
   try {
     while (!stopped) {
+      update(retries ? 'reconnecting' : 'connecting');
+      let reachedServer = false;
       try {
-        update(retries ? 'reconnecting' : 'connecting', { id: lastId });
-        const current = new WebSocket(options.url);
+        const current = new WebSocketClient(options.url, { handshakeTimeout: 15000, perMessageDeflate: false });
         socket = current;
         await new Promise((resolve, reject) => {
-          const timer = setTimeout(() => { try { current.close(); } catch {} reject(new Error('Connection timed out')); }, 15000);
-          const success = () => { clearTimeout(timer); resolve(); };
-          const failure = () => { clearTimeout(timer); reject(new Error('Could not reach backend')); };
-          current.addEventListener('open', success, { once: true });
-          current.addEventListener('error', failure, { once: true });
-        });
-        if (stopped) break;
-        current.send(JSON.stringify({ type: 'hello', protocolVersion: 2, token }));
-        await new Promise((resolve, reject) => {
+          let settled = false;
           let welcomed = false;
-          const timer = setTimeout(() => { try { current.close(); } catch {} reject(new Error('Server handshake timed out')); }, 10000);
+          let fatal = null;
+          let heartbeatTimer = null;
+          let pongTimer = null;
+          let handshakeTimer = null;
           let queue = Promise.resolve();
-          const messageListener = event => {
+
+          const cleanup = () => {
+            clearInterval(heartbeatTimer);
+            clearTimeout(pongTimer);
+            clearTimeout(handshakeTimer);
+            current.removeListener('open', opened);
+            current.removeListener('message', received);
+            current.removeListener('pong', pong);
+            current.removeListener('error', failed);
+            current.removeListener('close', closed);
+          };
+          const finish = error => {
+            if (settled) return;
+            settled = true;
+            cleanup();
+            current.on('error', () => {});
+            try { current.terminate(); } catch {}
+            if (error) reject(error);
+            else resolve();
+          };
+          const fail = (reason, code) => {
+            const error = new Error(reason);
+            if (code) error.code = code;
+            fatal = error;
+            finish(error);
+          };
+          const disconnected = reason => {
+            if (stopped) return finish();
+            if (welcomed) {
+              update('reconnecting');
+              emit({ type: 'connection-lost', problem: reason });
+              finish();
+            } else finish(fatal ?? new Error(reason));
+          };
+          const pong = () => {
+            clearTimeout(pongTimer);
+            pongTimer = null;
+            if (welcomed && !stopped) update('connected', { id: lastId, heartbeat: true });
+          };
+          const checkConnection = () => {
+            if (current.readyState !== WebSocketClient.OPEN || pongTimer || stopped) return;
+            try {
+              current.ping();
+              pongTimer = setTimeout(() => disconnected('Connection unresponsive (heartbeat timeout)'), pongTimeout);
+            } catch (error) { disconnected(`Connection health check failed: ${error.message}`); }
+          };
+          const opened = () => {
+            if (stopped) return finish();
+            try {
+              current.send(JSON.stringify({ type: 'hello', protocolVersion: 2, token }));
+              handshakeTimer = setTimeout(() => disconnected('Server handshake timed out'), 10000);
+            } catch (error) { disconnected(`Could not authenticate connection: ${error.message}`); }
+          };
+          const received = (data, isBinary) => {
+            if (isBinary) return emit({ type: 'protocol-warning', problem: 'Unexpected binary message from server' });
             let message;
-            try { message = JSON.parse(event.data); }
+            try { message = JSON.parse(data.toString()); }
             catch { emit({ type: 'protocol-warning', problem: 'Received an invalid server message' }); return; }
             if (message.type === 'welcome') {
               if (welcomed) return;
               if (message.protocolVersion !== 2 || typeof message.id !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(message.id)) {
-                clearTimeout(timer);
-                current.close(1000, 'Incompatible protocol');
-                const mismatch = new Error('Incompatible backend. Deploy ZBack backend 1.2.0 or later; this server issues legacy session IDs.');
-                mismatch.code = 'INCOMPATIBLE_BACKEND';
-                reject(mismatch);
+                fail('Incompatible backend. Deploy ZBack backend 1.2.0 or later.', 'INCOMPATIBLE_BACKEND');
                 return;
               }
               if (lastId && message.id !== lastId) {
-                clearTimeout(timer);
-                current.close(1000, 'Session identifier changed');
-                const mismatch = new Error('The server returned a different session identifier after reconnecting');
-                mismatch.code = 'SESSION_MISMATCH';
-                reject(mismatch);
+                fail('The server returned a different session identifier after reconnecting', 'SESSION_MISMATCH');
                 return;
               }
               welcomed = true;
-              clearTimeout(timer);
+              reachedServer = true;
+              clearTimeout(handshakeTimer);
               retries = 0;
               lastId = message.id;
-              lastError = null;
-              update('connected', { id: message.id });
+              update('connected', { id: lastId });
+              heartbeatTimer = setInterval(checkConnection, heartbeatInterval);
               return;
             }
             if (!welcomed || message.type !== 'command' || typeof message.requestId !== 'string') return;
             queue = queue.then(async () => {
-              if (stopped || current.readyState !== WebSocket.OPEN) return;
+              if (stopped || current.readyState !== WebSocketClient.OPEN) return;
               const command = message.command;
               if (typeof command !== 'string' || !command.trim() || command.length > 4096 || command.includes('\0')) return;
-              const timeout = Math.min(options.timeout, Number.isInteger(message.timeoutMs) && message.timeoutMs > 0 ? message.timeoutMs : options.timeout);
+              const positiveLimits = [options.timeout, message.timeoutMs].filter(value => Number.isInteger(value) && value > 0);
+              const timeout = positiveLimits.length ? Math.min(...positiveLimits) : 0;
               const result = await execute(command, options.cwd, timeout, options.maxOutput);
               emit({ type: 'command-result', command, result });
-              if (current.readyState === WebSocket.OPEN && !stopped) current.send(JSON.stringify({ type: 'result', requestId: message.requestId, ...result }));
+              if (!stopped && current.readyState === WebSocketClient.OPEN) {
+                current.send(JSON.stringify({ type: 'result', requestId: message.requestId, ...result }));
+              }
             }).catch(error => emit({ type: 'agent-error', problem: `Request processing failed: ${error.message}` }));
           };
-          current.addEventListener('message', messageListener);
-          current.addEventListener('close', event => {
-            clearTimeout(timer);
-            if (!welcomed) reject(new Error(`Backend rejected connection (WebSocket ${event.code}: ${event.reason || 'no reason'})`));
-            else { if (!stopped) emit({ type: 'connection-lost', problem: 'Connection lost' }); resolve(); }
-          }, { once: true });
-          current.addEventListener('error', () => { if (!welcomed) { clearTimeout(timer); reject(new Error('WebSocket connection failed')); } }, { once: true });
+          const failed = error => disconnected(error?.message || 'WebSocket connection failed');
+          const closed = (code, reason) => {
+            const detail = reason?.toString();
+            disconnected(welcomed ? `Connection lost (WebSocket ${code}${detail ? `: ${detail}` : ''})` : `Backend closed the connection (WebSocket ${code}${detail ? `: ${detail}` : ''})`);
+          };
+          current.on('open', opened);
+          current.on('message', received);
+          current.on('pong', pong);
+          current.on('error', failed);
+          current.on('close', closed);
         });
       } catch (error) {
         if (!stopped && ['INCOMPATIBLE_BACKEND', 'SESSION_MISMATCH'].includes(error.code)) throw error;
-        if (!stopped && error.message !== lastError) { emit({ type: 'connection-error', problem: error.message }); lastError = error.message; }
+        if (!stopped) {
+          update('reconnecting');
+          emit({ type: reachedServer ? 'connection-lost' : 'connection-error', problem: error.message });
+        }
+      } finally {
+        socket = null;
+        killRunningCommands();
       }
-      killRunningCommands();
       if (stopped || !options.reconnect) break;
-      update('reconnecting', { id: lastId });
+      update('reconnecting');
       const delay = Math.min(30000, 1000 * 2 ** Math.min(retries++, 5));
       await new Promise(resolve => {
         const timer = setTimeout(() => { cancelDelay = null; resolve(); }, delay);
@@ -154,6 +222,6 @@ export async function connectAgent(options, onState, token, onEvent = () => {})
   } finally {
     process.removeListener('SIGINT', shutdown);
     process.removeListener('SIGTERM', shutdown);
-    update('stopped', { id: lastId });
+    update('stopped');
   }
 }