zback 1.3.0 → 1.4.0

package/DISCLOSURE

@@ -2,7 +2,7 @@ ZBack is an opt-in remote shell administration tool for devices owned or explici
 
 Security-sensitive functionality:
 - A user manually starts the ZBack command and approves remote shell administration on the first run. The decision is stored in a local user-scoped file; subsequent commands do not require repeated prompts.
-- A background Node.js worker may persist after the invoking terminal detaches. It can be stopped with `zback --stop`.
+- The agent runs in the foreground by default and stops on Ctrl+C. An explicitly requested background worker may persist after the terminal detaches and can be stopped with `zback --stop`.
 - Remote shell commands execute with the operating-system permissions of the account that launched the agent.
 - The worker connects outbound to the configured secure WebSocket endpoint. It does not open an inbound shell listener.
 - The server exposes an MCP endpoint that routes authorized commands to connected workers when the caller presents the private session capability.

package/README.md

@@ -1,17 +1,19 @@
 # ZBack CLI
 
-ZBack is a deliberately 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 22 or later, has **no third-party runtime dependencies** 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
 
 ```sh
-npm install -g zback@1.2.0
+npm install -g zback@1.2.2
 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, 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.
+
+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 default server is `wss://zb.soymaycol.icu/ws`. To use your own backend:
 
@@ -25,21 +27,21 @@ For development only:
 zback --url ws://127.0.0.1:8787/ws
 ```
 
-The client and backend must both be **version 1.2.0** because the connection handshake changed. The backend must be deployed before a remote client can connect.
+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.
 
 ## Terminal and process lifecycle
 
 | Command | Behavior |
 | --- | --- |
-| `zback` | Start if needed and attach the terminal to a live event display |
-| `zback --background` | Start the agent without keeping a live terminal display |
+| `zback` | Keep the agent in the foreground; display the session ID, MCP endpoint, colored connection notices, and command execution history |
+| `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 |
-| `zback --follow` | Attach to live events from the existing background agent |
+| `zback --follow` | Watch new events from an existing background agent without replaying old logs |
 | `zback --stop` | Stop the background agent |
 | `zback --reset-key` | Change the device identity after the agent is stopped |
 
-`Ctrl+C` while viewing events **detaches the display**, but the agent stays running. Use `zback --stop` to disconnect. The server session ID stays the same over ordinary network reconnections and backend restarts, as long as the private local agent credential remains unchanged.
+`Ctrl+C` in the default foreground mode **stops the agent**. In background mode, `Ctrl+C` detaches the log display only. Use `zback --stop` to disconnect a background agent. Before upgrading from version 1.1.x or an earlier running version, stop its existing background worker with `zback --stop`. The server session ID stays the same over ordinary network reconnections and backend restarts, as long as the private local agent credential remains unchanged.
 
 After a device restart, ZBack does **not** silently install an autostart service. Launch it again when needed. Android/Termux process and battery restrictions can still terminate background tasks; a Node.js program cannot override the operating system's lifecycle.
 
@@ -56,7 +58,7 @@ Files are under `~/.local/state/zback` on Linux/Termux and `%LOCALAPPDATA%/zback
 
 ## MCP
 
-The companion backend serves `POST /mcp` with `zback_status` and `zback_execute`. The client prints a **private** session ID for passing to these tools. 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. 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,18 +6,19 @@ 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.0';
+const VERSION = '1.2.2';
 const DEFAULT_URL = 'wss://zb.soymaycol.icu/ws';
 
 function help() {
   console.log(`ZBack ${VERSION} | Authorized remote shell administration
 
 Usage:
-  zback                     Start the agent and display live events
-  zback --background        Start without attaching the terminal
+  zback                     Start in the foreground and display live events
+  zback --background        Run as a background agent
   zback --status            Show agent status, PID and private session ID
   zback --logs              Show recent agent events
   zback --follow            Follow live events from a running agent
@@ -34,8 +35,8 @@ Options:
 
 ZBack runs shell commands with your account privileges. Initial interactive
 consent is required once, not for every command. Keep the session ID private.
-Ctrl+C detaches the live display; the agent continues running.
-Use --stop to actually disconnect the agent.`);
+Ctrl+C stops a foreground agent. Background mode must be requested explicitly.
+Use --stop to disconnect a background agent.`);
 }
 
 export function parseArgs(args) {
@@ -70,17 +71,17 @@ export function parseArgs(args) {
   return { ...options, action };
 }
 
-async function confirmOnce() {
+async function confirmOnce(terminal) {
   if (hasConsent()) return true;
   if (!stdin.isTTY || !stdout.isTTY) throw new Error('First-run shell authorization requires an interactive terminal');
-  console.log('ZBack permits remote shell commands through a private session credential.');
-  console.log('These commands run as your current user. Do not share your session ID.');
+  terminal.question();
   const rl = createInterface({ input: stdin, output: stdout });
   try {
-    const answer = await rl.question('Authorize remote shell administration on this device? [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,20 +92,44 @@ 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, updated: new Date().toISOString(), ...data });
+    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) {
+  const endpoint = new URL(url);
+  endpoint.protocol = endpoint.protocol === 'wss:' ? 'https:' : 'http:';
+  endpoint.pathname = '/mcp';
+  return endpoint.toString();
+}
+
+function showConnection(id, url) {
+  console.log(`Session ID: ${id}`);
+  console.log(`MCP endpoint: ${mcpEndpoint(url)}`);
+  console.log('MCP tools: zback_status, zback_execute (provide the ID as the id argument)');
+  console.log('Keep the session ID private; it grants remote shell access.');
 }
 
 function showStatus() {
   const state = activeSession();
   if (!state) { console.log('Status: stopped'); return false; }
-  console.log(`Status: ${state.status}\nPID: ${state.pid}${state.id ? `\nSession ID: ${state.id}` : ''}\nUpdated: ${state.updated || 'unknown'}`);
+  console.log(`Status: ${state.status}\nPID: ${state.pid}\nUpdated: ${state.updated || 'unknown'}`);
+  if (state.id) showConnection(state.id, readJson(settingsFile)?.url || DEFAULT_URL);
   return true;
 }
 
@@ -122,8 +147,7 @@ function recentLog() {
 
 async function follow() {
   if (!stdin.isTTY || !stdout.isTTY) return;
-  console.log('Live agent events. Ctrl+C detaches; the agent stays active.');
-  recentLog();
+  console.log('Monitoring background agent. Ctrl+C closes this view; the agent stays active.');
   let position = existsSync(logFile) ? statSync(logFile).size : 0;
   await new Promise(resolve => {
     const readNew = () => {
@@ -151,16 +175,45 @@ async function follow() {
 }
 
 async function start(options) {
+  const terminal = createTerminal();
   const existing = activeSession();
   if (existing) {
-    console.log(existing.id ? `Session ID: ${existing.id}` : `ZBack is ${existing.status} (PID ${existing.pid}).`);
+    if (existing.version !== VERSION) {
+      terminal.error('An older ZBack agent is still running. Run zback --stop before starting this version.');
+      process.exitCode = 1;
+      return;
+    }
+    terminal.section('+', `Agent already running (${existing.status}, PID ${existing.pid}).`);
+    if (existing.id) terminal.connected(existing.id, mcpEndpoint(readJson(settingsFile)?.url || DEFAULT_URL));
     if (!options.background) await follow();
     return;
   }
-  if (!(await confirmOnce())) { console.log('Authorization declined'); return; }
+  if (!(await confirmOnce(terminal))) return;
   initStateDir();
-  agentKey();
+  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;
+    const reporter = createEventReporter(terminal);
+    const mark = data => {
+      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(options.url));
+        else terminal.restored();
+        lastId = data.id;
+      }
+    };
+    mark({ status: 'connecting', id: null });
+    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);
   const started = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
   let child;
@@ -178,14 +231,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) {
-      console.log(`Session ID: ${state.id}`);
+      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; use zback --status for current state.`);
-  if (!options.background) await follow();
+  if (!connected) terminal.hint(`Agent started (PID ${child.pid}). Run zback --status to inspect the connection.`);
 }
 
 function stop() {
@@ -213,7 +265,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,7 +1,7 @@
 {
   "name": "zback",
-  "version": "1.3.0",
-  "description": "Opt-in remote shell administration with a persistent WebSocket agent, audit logs and a private session credential",
+  "version": "1.4.0",
+  "description": "Opt-in foreground remote shell administration with a persistent WebSocket agent and private session credential",
   "type": "module",
   "bin": {
     "zback": "bin/zback.js"

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;
@@ -54,16 +53,15 @@ export function execute(command, cwd, timeoutMs, maxOutput) {
   });
 }
 
-export async function connectAgent(options, onState, token) {
+export async function connectAgent(options, onState, token, onEvent = () => {}) {
   let stopped = false;
   let retries = 0;
   let socket;
   let cancelDelay;
-  let currentState = '';
-  const update = (status, data = {}) => {
-    onState({ status, ...data });
-    if (currentState !== status) { log(`Agent status: ${status}`); currentState = status; }
-  };
+  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 shutdown = () => {
     stopped = true;
     if (cancelDelay) cancelDelay();
@@ -75,7 +73,7 @@ export async function connectAgent(options, onState, token) {
   try {
     while (!stopped) {
       try {
-        update(retries ? 'reconnecting' : 'connecting');
+        update(retries ? 'reconnecting' : 'connecting', { id: lastId });
         const current = new WebSocket(options.url);
         socket = current;
         await new Promise((resolve, reject) => {
@@ -94,14 +92,31 @@ export async function connectAgent(options, onState, token) {
           const messageListener = event => {
             let message;
             try { message = JSON.parse(event.data); }
-            catch { log('Ignored invalid server message'); return; }
-            if (message.type === 'welcome' && typeof message.id === 'string') {
+            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);
+                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);
+                return;
+              }
               welcomed = true;
               clearTimeout(timer);
               retries = 0;
+              lastId = message.id;
+              lastError = null;
               update('connected', { id: message.id });
-              log('Connected and ready for authorized requests');
               return;
             }
             if (!welcomed || message.type !== 'command' || typeof message.requestId !== 'string') return;
@@ -110,26 +125,27 @@ export async function connectAgent(options, onState, token) {
               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 result = await execute(command, options.cwd, timeout, options.maxOutput);
-              log(`Request ${message.requestId}: ${result.timedOut ? 'timed out' : result.ok ? 'completed' : 'failed'}`);
+              emit({ type: 'command-result', command, result });
               if (current.readyState === WebSocket.OPEN && !stopped) current.send(JSON.stringify({ type: 'result', requestId: message.requestId, ...result }));
-            }).catch(error => log(`Request processing error: ${error.message}`));
+            }).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 { log(`Connection closed (${event.code}: ${event.reason || 'connection lost'})`); resolve(); }
+            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 });
         });
-      } catch (error) { if (!stopped) log(`Connection error: ${error.message}`); }
+      } 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; }
+      }
       killRunningCommands();
       if (stopped || !options.reconnect) break;
-      update('reconnecting', { id: null });
+      update('reconnecting', { id: lastId });
       const delay = Math.min(30000, 1000 * 2 ** Math.min(retries++, 5));
-      log(`Retrying connection in ${Math.ceil(delay / 1000)}s`);
       await new Promise(resolve => {
         const timer = setTimeout(() => { cancelDelay = null; resolve(); }, delay);
         cancelDelay = () => { clearTimeout(timer); cancelDelay = null; resolve(); };
@@ -138,6 +154,6 @@ export async function connectAgent(options, onState, token) {
   } finally {
     process.removeListener('SIGINT', shutdown);
     process.removeListener('SIGTERM', shutdown);
-    update('stopped', { id: null });
+    update('stopped', { id: lastId });
   }
 }

package/src/runtime.js

@@ -46,7 +46,7 @@ export function alive(pid) {
       try {
         if (readFileSync(`/proc/${pid}/stat`, 'utf8').split(') ')[1]?.[0] === 'Z') return false;
         const cmd = readFileSync(`/proc/${pid}/cmdline`, 'utf8');
-        if (!cmd.includes('--worker') || !cmd.includes('zback.js')) return false;
+        if (!/(?:^|[\x00/\\])zback(?:\.js)?(?:\x00|$)/.test(cmd)) return false;
       } catch {}
     }
     return true;

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);
+    }
+  };
+}