zback 1.3.1 → 1.4.1

package/README.md

@@ -1,17 +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.1
+npm install -g .
 zback
 ```
 
-On the first run, ZBack explains the remote-shell capability and asks for authorization 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. 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:
 
@@ -25,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 and live activity |
+| `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 |
@@ -50,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
 

package/bin/zback.js

@@ -6,11 +6,18 @@ import { createInterface } from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
 import { fileURLToPath } from 'node:url';
 import { connectAgent, execute } from '../src/agent.js';
+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.1';
+const VERSION = '1.2.5';
 const DEFAULT_URL = 'wss://zb.soymaycol.icu/ws';
+const STALE_AFTER_MS = 60000;
+
+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
@@ -27,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++) {
@@ -53,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;
@@ -61,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);
@@ -70,17 +81,22 @@ export function parseArgs(args) {
   return { ...options, action };
 }
 
-async function confirmOnce() {
+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');
-  console.log('This module grants remote shell access to anyone holding your private session ID.');
-  console.log('Commands run with your user permissions. Keep the session ID private.');
+  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 {
-    const answer = await rl.question('Do you allow remote access to your shell? This is asked only once. [y/N] ');
-    if (!['y', 'yes'].includes(answer.trim().toLowerCase())) return false;
-    saveJson(consentFile, { approved: true, at: new Date().toISOString() });
-    return true;
+    const answer = await rl.question('Your choice [y/N]: ');
+    const approved = ['y', 'yes'].includes(answer.trim().toLowerCase());
+    if (approved) saveJson(consentFile, { approved: true, at: new Date().toISOString() });
+    terminal.consent(approved);
+    return approved;
   } finally { rl.close(); }
 }
 
@@ -91,14 +107,23 @@ async function worker() {
   const started = process.env.ZBACK_WORKER_NONCE;
   if (!started) throw new Error('Worker must be launched through zback');
   const key = agentKey();
+  const terminal = createTerminal();
+  const reporter = createEventReporter(terminal);
+  let lastId = null;
   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') {
+      reporter.clearProblem();
+      if (!lastId) terminal.connected(data.id, mcpEndpoint(settings.url));
+      else terminal.restored();
+      lastId = data.id;
+    }
   };
   mark({ status: 'connecting', id: null });
-  try { await connectAgent(settings, mark, key); }
-  finally { if (sameSession(process.pid, started)) mark({ status: 'stopped', id: null }); }
+  try { await connectAgent(settings, mark, key, reporter.event); }
+  finally { if (sameSession(process.pid, started)) mark({ status: 'stopped', id: lastId }); }
 }
 
 function mcpEndpoint(url) {
@@ -118,7 +143,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;
 }
@@ -138,6 +163,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 = () => {
@@ -156,7 +182,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);
@@ -165,43 +216,46 @@ async function follow() {
 }
 
 async function start(options) {
+  const terminal = createTerminal();
   const existing = activeSession();
   if (existing) {
     if (existing.version !== VERSION) {
-      console.error('An older ZBack agent is still running. Run zback --stop, then zback to start this version.');
+      terminal.error('An older ZBack agent is still running. Run zback --stop before starting this version.');
       process.exitCode = 1;
       return;
     }
-    console.log(`Agent already running (${existing.status}, PID ${existing.pid}).`);
-    if (existing.id) showConnection(existing.id, readJson(settingsFile)?.url || DEFAULT_URL);
+    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())) { console.log('Authorization declined'); 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 });
+  terminal.connecting();
   if (!options.background) {
     const started = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
     let lastId = null;
-    let previousStatus = 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') {
-        if (data.id !== lastId) {
-          console.log('Connected.');
-          showConnection(data.id, options.url);
-          console.log('Monitoring requests and connection errors. Press Ctrl+C to disconnect.');
-          lastId = data.id;
-        } else if (previousStatus !== 'connected') console.log('Connection restored.');
-      } else if (data.status === 'reconnecting' && previousStatus !== 'reconnecting') console.error('Connection lost. Attempting to reconnect...');
-      else if (data.status === 'stopped' && previousStatus !== 'stopped' && lastId) console.log('Disconnected.');
-      previousStatus = data.status;
+        reporter.clearProblem();
+        if (!lastId) terminal.connected(data.id, mcpEndpoint(options.url));
+        else terminal.restored();
+        lastId = data.id;
+      }
     };
-    console.log(`Connecting to ${options.url}...`);
     mark({ status: 'connecting', id: null });
-    try { await connectAgent(options, mark, key); }
-    finally { if (sameSession(process.pid, started)) saveJson(stateFile, { pid: process.pid, started, version: VERSION, status: 'stopped', id: lastId, updated: new Date().toISOString() }); }
+    try { await connectAgent(options, mark, key, reporter.event); }
+    finally {
+      if (sameSession(process.pid, started)) saveJson(stateFile, { pid: process.pid, started, version: VERSION, status: 'stopped', id: lastId, updated: new Date().toISOString() });
+      terminal.stopped();
+    }
     return;
   }
   const fd = openSync(logFile, 'a', 0o600);
@@ -221,14 +275,13 @@ async function start(options) {
     await new Promise(resolve => setTimeout(resolve, 100));
     const state = readJson(stateFile);
     if (state?.pid === child.pid && state.started === started && state.status === 'connected' && state.id) {
-      showConnection(state.id, options.url);
+      terminal.connected(state.id, mcpEndpoint(options.url));
       connected = true;
       break;
     }
-    if (!alive(child.pid) || (state?.pid === child.pid && state.status === 'stopped')) throw new Error(`Agent exited unexpectedly. Inspect logs with zback --logs`);
+    if (!alive(child.pid) || (state?.pid === child.pid && state.status === 'stopped')) throw new Error('Agent exited unexpectedly. Inspect logs with zback --logs');
   }
-  if (!connected) console.log(`Agent started (PID ${child.pid}). Waiting for backend; run zback --status to inspect.`);
-  if (!options.background) await follow();
+  if (!connected) terminal.hint(`Agent started (PID ${child.pid}). Run zback --status to inspect the connection.`);
 }
 
 function stop() {
@@ -256,7 +309,7 @@ export async function main(args = process.argv.slice(2)) {
     if (options.action === 'follow') { showStatus(); return follow(); }
     if (options.action === 'reset-key') return rotate();
     return await start(options);
-  } catch (error) { console.error(`ZBack error: ${error.message}`); process.exitCode = 1; }
+  } catch (error) { createTerminal().error(error.message); process.exitCode = 1; }
 }
 
 if (process.argv[1] && realpathSync(process.argv[1]) === ENTRY) main();

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "zback",
-  "version": "1.3.1",
+  "version": "1.4.1",
   "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

@@ -2,7 +2,6 @@ import { spawn } from 'node:child_process';
 
 const children = new Set();
 const wait = ms => new Promise(resolve => setTimeout(resolve, ms));
-const log = message => console.log(`[${new Date().toISOString()}] ${message}`);
 
 function killTree(child) {
   if (!child?.pid) return;
@@ -35,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;
@@ -54,90 +53,166 @@ export function execute(command, cwd, timeoutMs, maxOutput) {
   });
 }
 
-export async function connectAgent(options, onState, token) {
+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 ?? 12000;
   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 {} };
+  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 });
+          };
+          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); }
-            catch { log('Ignored invalid server message'); return; }
+            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) {
+                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);
-              log(`Running authorized request ${message.requestId}`);
+              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);
-              log(`Request ${message.requestId}: ${result.timedOut ? 'timed out' : result.ok ? 'completed' : 'failed'}`);
-              if (current.readyState === WebSocket.OPEN && !stopped) current.send(JSON.stringify({ type: 'result', requestId: message.requestId, ...result }));
-            }).catch(error => log(`Request processing error: ${error.message}`));
+              emit({ type: 'command-result', command, 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}` }));
+          };
+          const failed = error => disconnected(error?.message || 'WebSocket connection failed');
+          const closed = (code, reason) => {
+            const detail = reason?.toString();
+            disconnected(welcomed ? 'Connection lost' : `Backend closed the connection (WebSocket ${code}${detail ? `: ${detail}` : ''})`);
           };
-          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) log(`Connection closed (${event.code}: ${event.reason || 'connection lost'})`); resolve(); }
-          }, { once: true });
-          current.addEventListener('error', () => { if (!welcomed) { clearTimeout(timer); reject(new Error('WebSocket connection failed')); } }, { once: true });
+          current.on('open', opened);
+          current.on('message', received);
+          current.on('pong', pong);
+          current.on('error', failed);
+          current.on('close', closed);
         });
       } catch (error) {
-        if (!stopped && error.code === 'INCOMPATIBLE_BACKEND') throw error;
-        if (!stopped && error.message !== lastError) { log(`Connection error: ${error.message}`); lastError = error.message; }
+        if (!stopped && ['INCOMPATIBLE_BACKEND', 'SESSION_MISMATCH'].includes(error.code)) throw error;
+        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);
@@ -147,6 +222,6 @@ export async function connectAgent(options, onState, token) {
   } finally {
     process.removeListener('SIGINT', shutdown);
     process.removeListener('SIGTERM', shutdown);
-    update('stopped', { id: lastId });
+    update('stopped');
   }
 }

package/src/terminal.js

@@ -0,0 +1,98 @@
+const ANSI = Object.freeze({ yellow: '\x1b[33m', red: '\x1b[31m', gray: '\x1b[90m', white: '\x1b[37m', reset: '\x1b[0m' });
+
+// Never allow server-supplied text to inject terminal control sequences.
+export function terminalText(value, maxLength = 240) {
+  const text = String(value ?? 'unknown')
+    .replace(/\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07]*(?:\x07|\x1b\\)?)/g, '')
+    .replace(/[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return text.length <= maxLength ? text : `${text.slice(0, maxLength - 1)}…`;
+}
+
+export function createTerminal({ output = process.stdout, color = Boolean(output.isTTY && !process.env.NO_COLOR) } = {}) {
+  const tint = (s, name) => color ? `${ANSI[name]}${s}${ANSI.reset}` : s;
+  const write = line => output.write(`${line}\n`);
+  const section = (symbol, text, tone = 'yellow') => write(`${tint(`[${symbol}]`, tone)} ${tint(text, 'white')}`);
+  const detail = line => write(`${tint(' -', 'gray')} ${tint(line, 'white')}`);
+  const hint = line => write(`${tint('>', 'gray')} ${tint(line, 'gray')}`);
+  const gap = () => write('');
+
+  return {
+    section, detail, hint, gap,
+    question() {
+      section('?', 'Shell access authorization');
+      write(tint('Do you allow ZBack to provide remote shell access to holders of your private session ID?', 'white'));
+      write(`${tint('[Y]', 'yellow')} ${tint('Yes, I accept', 'white')}  ${tint('[N]', 'yellow')} ${tint('No, I do not accept', 'white')}`);
+      hint('Your decision is saved. Individual commands will not trigger additional prompts.');
+    },
+    consent(approved) {
+      hint(approved ? 'Selected: Yes. Remote shell access is authorized.' : 'Selected: No. Remote shell access remains disabled.');
+      gap();
+    },
+    connecting() {
+      section('+', 'Connecting to the server, hang on a minute.');
+      hint('This may take a moment depending on your internet connection.');
+      gap();
+    },
+    connected(id, endpoint) {
+      section('+', 'Setting up our environment');
+      detail(`Session Identifier: "${terminalText(id, 90)}"`);
+      detail(`MCP Server: "${terminalText(endpoint, 512)}"`);
+      detail('MCP Tools: "zback_status", "zback_execute"');
+      hint('Enjoy being able to have a model manage your environment. Keep your ID private.');
+      gap();
+    },
+    restored() {
+      section('+', 'Connection restored.');
+      hint('Your session identifier has not changed.');
+      gap();
+    },
+    error(problem, retrying = false) {
+      section('×', 'Oops, an error has occurred.', 'red');
+      detail(`Problem: "${terminalText(problem, 240)}"`);
+      hint(retrying ? 'This error is being handled. Reconnecting automatically, please wait.' : 'The connection cannot continue. Check the problem above.');
+      gap();
+    },
+    stopped() {
+      section('+', 'Disconnected.');
+    },
+    command(result, totals) {
+      if (totals.count === 1) section('+', 'History of executed commands');
+      const code = Number.isInteger(result.code) ? result.code : result.timedOut ? 'timeout' : 'unknown';
+      detail(`${JSON.stringify(terminalText(result.command))} was executed with exit code ${code}.`);
+      const countWord = totals.count === 1 ? 'command was' : 'commands were';
+      const errorWord = totals.errors === 1 ? 'an error' : 'errors';
+      hint(`Currently, ${totals.count} ${countWord} executed, ${totals.errors} with ${errorWord} and ${totals.successes} successfully.`);
+    }
+  };
+}
+
+export function createCommandTracker(terminal) {
+  const totals = { count: 0, successes: 0, errors: 0 };
+  return event => {
+    if (event.type !== 'command-result') return;
+    totals.count++;
+    if (event.result.ok) totals.successes++;
+    else totals.errors++;
+    terminal.command({ command: event.command, ...event.result }, totals);
+  };
+}
+
+export function createEventReporter(terminal) {
+  const reportCommand = createCommandTracker(terminal);
+  let activeProblem = null;
+  return {
+    clearProblem() { activeProblem = null; },
+    event(event) {
+      if (event.type === 'command-result') return reportCommand(event);
+      if (event.type === 'connection-lost' || event.type === 'connection-error') {
+        // A dropped connection may lead to many retries; report the incident once.
+        if (activeProblem !== null) return;
+        activeProblem = event.problem;
+        return terminal.error(event.problem, true);
+      }
+      if (event.type === 'agent-error' || event.type === 'protocol-warning') terminal.error(event.problem, false);
+    }
+  };
+}