zback 1.0.0 → 1.1.1

package/README.md

@@ -1,31 +1,40 @@
-# zback (CLI global)
+# ZBack CLI
 
-Agente CLI para **Node.js 22 o superior**, sin dependencias npm externas. Se conecta a tu backend por WebSocket cifrado, enseña un ID temporal y solicita **autorización presencial para cada comando**.
+Global command for Node.js 22+. No npm dependencies, login, API key, or password.
 
-## Instalar
+## Install
 
 ```bash
 npm install -g .
-zback --help
 zback
 ```
 
-Extrae este ZIP antes de ejecutar `npm install -g .` dentro de su directorio.
+The first time, ZBack asks exactly once for permission to access **your own shell**. Answer `y` to run it as a detached background process. When connected, it prints:
 
-Opciones:
+```
+Okay, here's your session ID "..."
+```
+
+Closing the terminal does not normally stop the agent. Later calls to `zback` show its current session ID without requesting permission again. To view the connection state or terminate the worker:
 
 ```bash
-zback --url wss://zb.soymaycol.icu/ws
-zback --cwd /ruta/a/proyecto --timeout 15000 --max-output 32768
-zback --no-reconnect
+zback --status
+zback --stop
 ```
 
-Para pruebas locales: `zback --url ws://127.0.0.1:8787/ws`.
+Advanced options at first launch (or after stopping it):
+
+```bash
+zback --url wss://zb.soymaycol.icu/ws --cwd /path/to/project
+zback --timeout 120000 --max-output 131072
+```
+
+Local development: `zback --url ws://127.0.0.1:8787/ws`.
+
+The agent automatically reconnects, potentially receiving a **new session ID**; check `zback --status` if the previous ID stops working. There are no per-command approvals after initial permission. The session ID grants anyone who possesses it remote shell access for the lifetime of that session; **keep it private**. TLS (`wss://`) is required remotely.
+
+Status, consent, and log files are stored in the OS user state directory (`~/.local/state/zback` on most Linux systems or `%LOCALAPPDATA%/zback` on Windows). They are local and not published by the backend. Optionally set `ZBACK_STATE_DIR` to change this location.
 
-- Escribe `ACEPTO` para iniciar la sesión.
-- Verás un **ID nuevo por cada conexión**. No es una contraseña creada por el usuario, pero funciona como credencial temporal: mantenlo privado.
-- Cuando el MCP pida ejecutar un comando, verás su contenido completo y tendrás que escribir `s` para autorizarlo. Pulsar Enter, responder `n` o agotar el tiempo lo rechaza.
-- Ctrl+C termina la conexión; desconectarse invalida el ID.
-- Conexiones públicas `ws://` sin TLS están bloqueadas.
+Closing a terminal normally leaves the detached worker running. Force-stopping an Android app, battery restrictions, shutdown or network loss may still terminate or interrupt it; this CLI does not auto-start itself on device boot.
 
-**Advertencia:** revisar antes de aprobar es fundamental: cualquier comando autorizado se ejecuta con los permisos de tu usuario. El backend no hace que un comando sea confiable.
+Test with `npm test`.

package/bin/zback.js

@@ -1,175 +1,151 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process';
-import { existsSync, realpathSync, statSync } from 'node:fs';
+import { openSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
 import { fileURLToPath } from 'node:url';
+import { existsSync, statSync } from 'node:fs';
+import { connectAgent, execute } from '../src/agent.js';
+import { activeSession, alive, consentFile, hasConsent, initStateDir, logFile, readJson, sameSession, saveJson, settingsFile, stateFile } from '../src/runtime.js';
 
+const ENTRY = fileURLToPath(import.meta.url);
 const DEFAULT_URL = 'wss://zb.soymaycol.icu/ws';
 
 function help() {
-  console.log(`ZBack 1.0.0 - WebSocket agent (Node.js >=22)
-
-Uso: zback [opciones]
-
-  --url <wss://.../ws>   WebSocket de destino (default: ${DEFAULT_URL})
-  --cwd <directorio>     Directorio desde el cual ejecutar comandos
-  --timeout <ms>        Máximo tiempo de ejecución por comando (1000-300000)
-  --max-output <bytes>  Límite combinado de stdout+stderr (1024-262144)
-  --no-reconnect        Desactivar reconexión automática
-  --help                Mostrar esta ayuda
-
-Se solicita permiso al inicio y cada vez que un comando remoto llega.
-No hay API keys ni ejecución sin confirmación.`);
+  console.log(`ZBack 1.1.0\n\nUsage: zback [options]\n\n  --url <wss://.../ws>   WebSocket endpoint (default: ${DEFAULT_URL})\n  --cwd <directory>     Directory for shell commands\n  --timeout <ms>        Command timeout (1000-300000)\n  --max-output <bytes>  Maximum command output (1024-262144)\n  --no-reconnect        Disable automatic reconnection\n  --status              Show background agent status and session ID\n  --stop                Stop background agent\n  --help                Display help\n\nThe first launch asks for shell access permission only once.\nThe agent runs in the background until stopped.`);
 }
 
 export function parseArgs(args) {
   const options = { url: DEFAULT_URL, cwd: process.cwd(), timeout: 30000, maxOutput: 65536, reconnect: true };
-  const set = new Set(['--url', '--cwd', '--timeout', '--max-output']);
+  const values = new Set(['--url', '--cwd', '--timeout', '--max-output']);
+  let action = 'start';
   for (let i = 0; i < args.length; i++) {
     const flag = args[i];
     if (flag === '--help' || flag === '-h') return { help: true };
+    if (flag === '--worker') return { worker: true };
+    if (flag === '--status' || flag === '--stop') {
+      if (action !== 'start') throw new Error('Specify one action');
+      action = flag.slice(2);
+      continue;
+    }
     if (flag === '--no-reconnect') { options.reconnect = false; continue; }
-    if (!set.has(flag) || i + 1 >= args.length) throw new Error(`Argumento desconocido o incompleto: ${flag}`);
+    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;
     if (flag === '--cwd') options.cwd = resolve(value);
     if (flag === '--timeout') options.timeout = Number(value);
     if (flag === '--max-output') options.maxOutput = Number(value);
   }
-  if (!Number.isSafeInteger(options.timeout) || options.timeout < 1000 || options.timeout > 300000) throw new Error('--timeout debe estar entre 1000 y 300000 ms');
-  if (!Number.isSafeInteger(options.maxOutput) || options.maxOutput < 1024 || options.maxOutput > 262144) throw new Error('--max-output debe estar entre 1024 y 262144 bytes');
-  if (!existsSync(options.cwd) || !statSync(options.cwd).isDirectory()) throw new Error('--cwd debe ser un directorio existente');
+  if (action !== 'start') return { action };
+  if (!Number.isSafeInteger(options.timeout) || options.timeout < 1000 || options.timeout > 300000) throw new Error('--timeout must be between 1000 and 300000 ms');
+  if (!Number.isSafeInteger(options.maxOutput) || options.maxOutput < 1024 || options.maxOutput > 262144) throw new Error('--max-output must be between 1024 and 262144 bytes');
+  if (!existsSync(options.cwd) || !statSync(options.cwd).isDirectory()) throw new Error('--cwd must be an existing directory');
   const url = new URL(options.url);
-  if (url.protocol !== 'wss:' && !(url.protocol === 'ws:' && ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname))) {
-    throw new Error('Solo se permite wss:// público o ws:// local. Usa TLS para conexiones remotas.');
+  if (url.protocol !== 'wss:' && !(url.protocol === 'ws:' && ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname))) throw new Error('Use wss:// for remote connections or ws:// on localhost');
+  if (url.username || url.password || url.search || url.hash || url.pathname !== '/ws') throw new Error('Expected a WebSocket URL ending in /ws');
+  return { ...options, action };
+}
+
+async function confirmOnce() {
+  if (hasConsent()) return true;
+  if (!stdin.isTTY || !stdout.isTTY) throw new Error('An interactive terminal is required for initial permission.');
+  const rl = createInterface({ input: stdin, output: stdout });
+  try {
+    const answer = await rl.question('This module accesses your shell. Do you allow it to use your shell? Permission will not be requested again. [y/N] ');
+    if (!['y', 'yes'].includes(answer.trim().toLowerCase())) return false;
+    saveJson(consentFile, { approved: true, at: new Date().toISOString() });
+    return true;
+  } finally { rl.close(); }
+}
+
+async function worker() {
+  if (!hasConsent()) throw new Error('Permission has not been granted. Run zback interactively first.');
+  const settings = readJson(settingsFile);
+  if (!settings || !settings.url || !settings.cwd) throw new Error('Missing agent settings');
+  const started = process.env.ZBACK_WORKER_NONCE;
+  if (!started) throw new Error('Not a valid ZBack background worker');
+  const mark = data => {
+    const current = readJson(stateFile);
+    if (current && current.status !== 'stopped' && current.pid !== process.pid && alive(current.pid)) return;
+    saveJson(stateFile, { pid: process.pid, started, updated: new Date().toISOString(), ...data });
+  };
+  mark({ status: 'connecting', id: null });
+  const hardStop = () => {
+    if (sameSession(process.pid, started)) mark({ status: 'stopped', id: null });
+    setTimeout(() => process.exit(0), 150).unref();
+  };
+  process.once('SIGTERM', hardStop);
+  process.once('SIGINT', hardStop);
+  try { await connectAgent(settings, mark); }
+  finally {
+    if (sameSession(process.pid, started)) mark({ status: 'stopped', id: null });
   }
-  if (url.username || url.password || url.search || url.hash || url.pathname !== '/ws') throw new Error('URL inválida: usa una dirección WebSocket terminada en /ws sin credenciales ni parámetros');
-  return options;
 }
 
-export function execute(command, cwd, timeoutMs, maxOutput) {
-  return new Promise(resolveResult => {
-    let finished = false, timedOut = false, truncated = false;
-    const chunks = { stdout: [], stderr: [] };
-    let collected = 0;
-    let child;
-    try {
-      child = spawn(command, { cwd, shell: true, windowsHide: true, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'] });
-    } catch (err) {
-      resolveResult({ ok: false, code: null, stdout: '', stderr: String(err.message) });
+async function start(options) {
+  const running = activeSession();
+  if (running) {
+    console.log(running.id ? `Okay, here's your session ID "${running.id}"` : `ZBack is ${running.status}.`);
+    console.log('Use zback --status to inspect the agent or zback --stop to stop it.');
+    return;
+  }
+  if (!(await confirmOnce())) { console.log('Permission declined.'); return; }
+  initStateDir();
+  saveJson(settingsFile, { url: options.url, cwd: options.cwd, timeout: options.timeout, maxOutput: options.maxOutput, reconnect: options.reconnect });
+  const fd = openSync(logFile, 'a', 0o600);
+  const started = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  let child;
+  try {
+    child = spawn(process.execPath, [ENTRY, '--worker'], {
+      detached: true, windowsHide: true,
+      stdio: ['ignore', fd, fd],
+      env: { ...process.env, ZBACK_WORKER_NONCE: started }
+    });
+    child.unref();
+  } finally {
+    const { closeSync } = await import('node:fs');
+    closeSync(fd);
+  }
+  if (!child?.pid) throw new Error('Could not launch background process');
+  for (let i = 0; i < 80; i++) {
+    await new Promise(r => setTimeout(r, 100));
+    const state = readJson(stateFile);
+    if (state?.pid === child.pid && state.started === started && state.id && state.status === 'connected') {
+      console.log(`Okay, here's your session ID "${state.id}"`);
       return;
     }
-    const add = (kind, chunk) => {
-      const remaining = maxOutput - collected;
-      if (remaining <= 0) { truncated = true; return; }
-      if (chunk.length > remaining) truncated = true;
-      const part = chunk.subarray(0, remaining);
-      collected += part.length;
-      chunks[kind].push(part);
-    };
-    child.stdout.on('data', b => add('stdout', b));
-    child.stderr.on('data', b => add('stderr', b));
-    const timer = setTimeout(() => {
-      timedOut = true;
-      try {
-        if (process.platform === 'win32') spawn('taskkill', ['/PID', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
-        else process.kill(-child.pid, 'SIGKILL');
-      } catch { try { child.kill('SIGKILL'); } catch {} }
-    }, timeoutMs);
-    const finish = (code, message = '') => {
-      if (finished) return;
-      finished = true;
-      clearTimeout(timer);
-      resolveResult({ ok: code === 0 && !timedOut, code: Number.isInteger(code) ? code : null,
-        stdout: Buffer.concat(chunks.stdout).toString('utf8'),
-        stderr: Buffer.concat(chunks.stderr).toString('utf8') + message,
-        truncated, timedOut });
-    };
-    child.once('error', error => finish(null, `\n${error.message}`));
-    child.once('close', code => finish(code));
-  });
+    if (!alive(child.pid) || (state?.pid === child.pid && state.status === 'stopped')) {
+      throw new Error(`Background process exited. See ${logFile}`);
+    }
+  }
+  console.log(`Background agent started (PID ${child.pid}); waiting for the server.`);
+  console.log('Use zback --status to see the session ID once connected.');
 }
 
-export async function main(args = process.argv.slice(2)) {
-  let options;
-  try { options = parseArgs(args); }
-  catch (error) { console.error(`Error: ${error.message}`); process.exitCode = 2; return; }
-  if (options.help) return help();
-  if (!stdin.isTTY || !stdout.isTTY) {
-    console.error('Error: se requiere una terminal interactiva para confirmar comandos.');
-    process.exitCode = 2; return;
-  }
-  console.log('\nZBack - acceso remoto a tu shell');
-  console.log('ADVERTENCIA: ejecutar comandos ajenos puede borrar archivos, modificar el sistema o comprometer información.');
-  console.log('Conéctate solo a tu propio servidor. Revisa cada comando antes de aprobarlo.');
-  console.log(`Servidor: ${options.url}`);
-  console.log(`Directorio: ${options.cwd}`);
-  const rl = createInterface({ input: stdin, output: stdout });
-  const consent = await rl.question('Escribe ACEPTO para habilitar solicitudes remotas: ');
-  if (consent.trim() !== 'ACEPTO') { console.log('Cancelado.'); rl.close(); return; }
+function status() {
+  const state = activeSession();
+  if (!state) return console.log('ZBack is stopped.');
+  console.log(`Status: ${state.status}\nPID: ${state.pid}${state.id ? `\nSession ID: ${state.id}` : ''}`);
+}
 
-  let ws, active = false, stopped = false, retries = 0;
-  let queue = Promise.resolve();
-  const wait = ms => new Promise(resolveWait => setTimeout(resolveWait, ms));
-  const shutdown = () => { stopped = true; try { ws?.close(); } catch {} rl.close(); };
-  process.once('SIGINT', shutdown);
-  process.once('SIGTERM', shutdown);
+function stop() {
+  const state = activeSession();
+  if (!state) return console.log('ZBack is not running.');
+  process.kill(state.pid, 'SIGTERM');
+  console.log('ZBack stop requested.');
+}
 
-  while (!stopped) {
-    try {
-      ws = new WebSocket(options.url);
-      await new Promise((accept, reject) => {
-        ws.addEventListener('open', accept, { once: true });
-        ws.addEventListener('error', () => reject(new Error('Conexión fallida')), { once: true });
-      });
-      active = true;
-      retries = 0;
-      console.log('\nConectado. Esperando solicitudes...');
-      const closed = new Promise(resolveClosed => ws.addEventListener('close', resolveClosed, { once: true }));
-      ws.addEventListener('message', event => {
-        let message;
-        try { message = JSON.parse(event.data); } catch { return; }
-        if (message.type === 'welcome') {
-          console.log(`\nID temporal: ${message.id}`);
-          console.log('Comparte el ID solo con el cliente MCP autorizado. No se mostrará en el backend.');
-        }
-        if (message.type === 'command' && typeof message.requestId === 'string') {
-          queue = queue.then(async () => {
-            const command = message.command;
-            if (typeof command !== 'string' || !command.trim() || command.length > 1000 || command.includes('\0')) return;
-            console.log(`\nSolicitud de ejecución recibida:\n  ${JSON.stringify(command)}`);
-            let approval;
-            try {
-              approval = await rl.question('¿Autorizar este comando? [s/N]: ', { signal: AbortSignal.timeout(Math.min(message.approvalTimeoutMs ?? 60000, 300000)) });
-            } catch { approval = ''; }
-            let result;
-            if (approval.trim().toLowerCase() !== 's') {
-              result = { ok: false, rejected: true, code: null, stdout: '', stderr: 'Rechazado por la persona conectada.' };
-              console.log('Comando rechazado.');
-            } else {
-              const timeout = Math.min(options.timeout, Number.isInteger(message.timeoutMs) ? message.timeoutMs : options.timeout);
-              console.log('Ejecutando...');
-              result = await execute(command, options.cwd, timeout, options.maxOutput);
-              console.log(result.ok ? 'Comando completado.' : 'Comando terminado con error o límite.');
-            }
-            if (ws?.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ type: 'result', requestId: message.requestId, ...result }));
-          }).catch(error => console.error(`Error al procesar solicitud: ${error.message}`));
-        }
-      });
-      await closed;
-      console.log('\nDesconectado. El ID anterior ya no es válido.');
-    } catch (error) { console.error(`Conexión: ${error.message}`); }
-    active = false;
-    if (!options.reconnect || stopped) break;
-    const delay = Math.min(30000, 1000 * 2 ** Math.min(retries++, 5));
-    console.log(`Reconectando en ${Math.ceil(delay / 1000)} s...`);
-    await wait(delay);
-  }
-  shutdown();
+export { execute };
+export async function main(args = process.argv.slice(2)) {
+  try {
+    const options = parseArgs(args);
+    if (options.help) return help();
+    if (options.worker) return worker();
+    if (options.action === 'status') return status();
+    if (options.action === 'stop') return stop();
+    return await start(options);
+  } catch (error) { console.error(`Error: ${error.message}`); process.exitCode = 1; }
 }
 
-if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) main().catch(error => {
-  console.error(error.message); process.exitCode = 1;
-});
+if (process.argv[1] && resolve(process.argv[1]) === ENTRY) main();

package/package.json

@@ -1,10 +1,16 @@
 {
   "name": "zback",
-  "version": "1.0.0",
-  "description": "Consent-based remote shell agent via WebSocket and MCP",
+  "version": "1.1.1",
+  "description": "Background WebSocket shell agent with one-time local consent",
   "type": "module",
-  "bin": { "zback": "./bin/zback.js" },
-  "engines": { "node": ">=22.0.0" },
-  "scripts": { "test": "node --test" },
+  "bin": {
+    "zback": "bin/zback.js"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
   "license": "MIT"
 }

package/src/agent.js

@@ -0,0 +1,98 @@
+import { spawn } from 'node:child_process';
+
+const children = new Set();
+const wait = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+function killTree(child) {
+  if (!child?.pid) return;
+  try {
+    if (process.platform === 'win32') {
+      const killer = spawn('taskkill', ['/PID', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+      killer.unref();
+    } else process.kill(-child.pid, 'SIGKILL');
+  } catch { try { child.kill('SIGKILL'); } catch {} }
+}
+
+export function killRunningCommands() { for (const child of children) killTree(child); }
+
+export function execute(command, cwd, timeoutMs, maxOutput) {
+  return new Promise(resolveResult => {
+    let finished = false, timedOut = false, truncated = false;
+    const chunks = { stdout: [], stderr: [] };
+    let collected = 0;
+    let child;
+    try {
+      child = spawn(command, { cwd, shell: true, windowsHide: true, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'] });
+      children.add(child);
+    } catch (err) {
+      resolveResult({ ok: false, code: null, stdout: '', stderr: String(err.message) });
+      return;
+    }
+    const add = (kind, chunk) => {
+      const remaining = maxOutput - collected;
+      if (remaining <= 0) { truncated = true; return; }
+      if (chunk.length > remaining) truncated = true;
+      const part = chunk.subarray(0, remaining);
+      collected += part.length;
+      chunks[kind].push(part);
+    };
+    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 finish = (code, message = '') => {
+      if (finished) return;
+      finished = true;
+      children.delete(child);
+      clearTimeout(timer);
+      resolveResult({ ok: code === 0 && !timedOut, code: Number.isInteger(code) ? code : null,
+        stdout: Buffer.concat(chunks.stdout).toString('utf8'),
+        stderr: Buffer.concat(chunks.stderr).toString('utf8') + message,
+        truncated, timedOut });
+    };
+    child.once('error', error => finish(null, `\n${error.message}`));
+    child.once('close', code => finish(code));
+  });
+}
+
+export async function connectAgent(options, onState) {
+  let stopped = false, retries = 0, socket;
+  const shutdown = () => { stopped = true; try { socket?.close(); } catch {} killRunningCommands(); };
+  process.once('SIGINT', shutdown);
+  process.once('SIGTERM', shutdown);
+  while (!stopped) {
+    try {
+      socket = new WebSocket(options.url);
+      await new Promise((resolve, reject) => {
+        socket.addEventListener('open', resolve, { once: true });
+        socket.addEventListener('error', () => reject(new Error('Connection failed')), { once: true });
+      });
+      if (stopped) break;
+      retries = 0;
+      onState({ status: 'connected', id: null });
+      let queue = Promise.resolve();
+      socket.addEventListener('message', event => {
+        let message;
+        try { message = JSON.parse(event.data); } catch { return; }
+        if (message.type === 'welcome' && typeof message.id === 'string') {
+          onState({ status: 'connected', id: message.id });
+          console.log(`[zback] Connected; session ${message.id}`);
+        }
+        if (message.type === 'command' && typeof message.requestId === 'string') {
+          queue = queue.then(async () => {
+            const command = message.command;
+            if (typeof command !== 'string' || !command.trim() || command.length > 1000 || command.includes('\0')) return;
+            const timeout = Math.min(options.timeout, Number.isInteger(message.timeoutMs) && message.timeoutMs > 0 ? message.timeoutMs : options.timeout);
+            console.log(`[zback] Executing request ${message.requestId}`);
+            const result = await execute(command, options.cwd, timeout, options.maxOutput);
+            if (socket.readyState === WebSocket.OPEN && !stopped) socket.send(JSON.stringify({ type: 'result', requestId: message.requestId, ...result }));
+          }).catch(error => console.error(`[zback] Request failed: ${error.message}`));
+        }
+      });
+      await new Promise(resolve => socket.addEventListener('close', resolve, { once: true }));
+    } catch (error) { if (!stopped) console.error(`[zback] ${error.message}`); }
+    if (stopped || !options.reconnect) break;
+    onState({ status: 'reconnecting', id: null });
+    await wait(Math.min(30000, 1000 * 2 ** Math.min(retries++, 5)));
+  }
+  onState({ status: 'stopped', id: null });
+}

package/src/runtime.js

@@ -0,0 +1,39 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const stateDir = process.env.ZBACK_STATE_DIR || join(process.env.XDG_STATE_HOME || (process.platform === 'win32' ? process.env.LOCALAPPDATA || homedir() : join(homedir(), '.local', 'state')), 'zback');
+export const consentFile = join(stateDir, 'consent.json');
+export const stateFile = join(stateDir, 'session.json');
+export const settingsFile = join(stateDir, 'settings.json');
+export const logFile = join(stateDir, 'zback.log');
+
+export function initStateDir() { mkdirSync(stateDir, { recursive: true, mode: 0o700 }); }
+export function readJson(file) { try { return JSON.parse(readFileSync(file, 'utf8')); } catch { return null; } }
+export function saveJson(file, data) {
+  initStateDir();
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 });
+  renameSync(tmp, file);
+}
+export function hasConsent() { return readJson(consentFile)?.approved === true; }
+export function alive(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    if (process.platform === 'linux') {
+      try { if (readFileSync(`/proc/${pid}/stat`, 'utf8').split(') ')[1]?.[0] === 'Z') return false; } catch {}
+    }
+    return true;
+  }
+  catch (e) { return e.code === 'EPERM'; }
+}
+export function activeSession() {
+  const data = readJson(stateFile);
+  return data && data.status !== 'stopped' && alive(data.pid) ? data : null;
+}
+export function sameSession(pid, started) {
+  const data = readJson(stateFile);
+  return data?.pid === pid && data?.started === started;
+}
+export function hasState() { return existsSync(stateFile); }