@milpa/comal 0.0.0-stage → 0.1.0

package/src/permissions.mjs

@@ -0,0 +1,63 @@
+// Work controls write only the session ledger; nested effects still use the house judge.
+const READ_TOOLS = new Set(['Read', 'Glob', 'Grep', 'WebSearch', 'WebFetch', 'McpStatus', 'HouseContext', 'HouseSnapshot', 'OperationCatalog', 'ReadTable', 'PluginStatus', 'WorkSnapshot', 'AuditStatus', 'EvidenceRead', 'WorkPlanSet', 'WorkCheckRepair', 'WorkTaskUpdate', 'WorkStepRun', 'WorkDraft', 'WorkBoard']);
+const EDIT_TOOLS = new Set(['Write', 'Edit', 'McpConfigure']);
+import { inspectAutoAction, intentCoversAction } from './auto-guard.mjs';
+import { randomUUID } from 'node:crypto';
+import { readOnlyBashCheck, chromeLabObservation } from './read-only-check.mjs';
+READ_TOOLS.add('ToolPack');
+for (const name of ['ArtifactAccount','ArtifactList','ArtifactInspect']) READ_TOOLS.add(name);
+for (const name of ['ListDirectory', 'FileInfo']) READ_TOOLS.add(name);
+for (const name of ['ListAgents','SendMessage','ProviderCapabilities','ProviderSearch','AnalyzeMedia']) READ_TOOLS.add(name);
+
+export const PERMISSION_MODES = ['default', 'acceptEdits', 'plan', 'auto'];
+export function nextPermissionMode(mode) { return PERMISSION_MODES[(PERMISSION_MODES.indexOf(mode) + 1) % PERMISSION_MODES.length]; }
+
+export class PermissionPolicy {
+  constructor({ mode = 'default', allowed = [], denied = [], confirm, classifier, cwd, onDecision = () => {} } = {}) {
+    if (!PERMISSION_MODES.includes(mode)) throw new Error('Modo de permisos inválido. Usa default, plan, acceptEdits o auto.');
+    this.mode = mode; this.allowed = new Set(allowed); this.denied = new Set(denied); this.confirm = confirm;
+    this.classifier = classifier; this.cwd = cwd; this.onDecision = onDecision; this.context = { intentions: [], actions: [] };
+  }
+  setContext(context) { this.context = context; }
+  async authorize(name, input, { signal, onWaiting } = {}) {
+    signal?.throwIfAborted();
+    if (this.denied.has(name)) return { allowed: false, reason: 'Regla de denegación explícita' };
+    const knownRead = READ_TOOLS.has(name) || this.allowed.has(name) && chromeLabObservation(name);
+    if (name === 'Agent' || name === 'AgentBatch') return { allowed: true, reason: 'Delegación: cada acción del hijo conserva los permisos de la sesión' };
+    if (this.mode === 'plan' && !knownRead) return { allowed: false, reason: 'Modo plan: sólo lectura' };
+    if (name === 'Bash' && readOnlyBashCheck(input.command)) return { allowed: true, reason: 'Comprobación de lectura nativa con argv fijo; no requiere clasificador.' };
+    if (this.mode === 'auto' && !knownRead) return this.authorizeAuto(name, input, signal, onWaiting);
+    if (knownRead || this.allowed.has(name) || (this.mode === 'acceptEdits' && EDIT_TOOLS.has(name))) return { allowed: true, reason: 'Política de sesión' };
+    const allowed = await this.ask(name, input, signal, onWaiting);
+    return { allowed, reason: allowed ? 'Confirmación del usuario' : 'Sin autorización para esta herramienta' };
+  }
+  async ask(name, input, signal, onWaiting) {
+    if (!this.confirm) return false;
+    const questionId = randomUUID(); let allowed = false;
+    await onWaiting?.({ type: 'house_waiting', question_id: questionId });
+    try { signal?.throwIfAborted(); allowed = Boolean(await this.confirm(name, input)); return allowed; }
+    finally { await onWaiting?.({ type: 'house_answered', question_id: questionId, allowed }); }
+  }
+  async authorizeAuto(name, input, signal, onWaiting) {
+    const inspection = inspectAutoAction(name, input, this.cwd || process.cwd());
+    const data = { workspace: this.cwd, human_requests: this.context.intentions, previous_tool_calls: this.context.actions, proposed_action: { name, input } };
+    let verdict;
+    if (inspection.hard) verdict = { decision: 'deny', risk: 'destructive', reason: inspection.hard, intent_quote: '', source: 'guard' };
+    else if (!this.classifier || !data.human_requests.length || Buffer.byteLength(JSON.stringify(data)) > 64000) verdict = { decision: 'ask', risk: 'unknown', reason: 'No hay clasificador o contexto de intención suficiente para aprobar automáticamente.', intent_quote: '', source: 'guard' };
+    else try {
+      verdict = { ...await this.classifier.classify(data, signal), source: 'classifier' };
+      if (verdict.decision === 'allow' && (inspection.opaque || verdict.risk === 'unknown')) verdict = { ...verdict, decision: 'ask', reason: 'La acción contiene expansión, ejecución opaca o efectos desconocidos; requiere revisión.' };
+      if (verdict.decision === 'allow' && (inspection.destructive || verdict.risk === 'destructive') && !intentCoversAction(verdict, data.proposed_action, inspection, data.human_requests)) verdict = { ...verdict, decision: 'deny', reason: 'La intención más reciente no autoriza explícitamente la acción destructiva y su destino.' };
+      if (verdict.decision === 'allow' && verdict.risk === 'external' && (!verdict.intent_quote || !data.human_requests.at(-1)?.includes(verdict.intent_quote))) verdict = { ...verdict, decision: 'ask', reason: 'Falta autorización explícita para el efecto externo.' };
+    } catch (error) {
+      if (signal?.aborted || error.code === 'GOAL_BUDGET') throw error;
+      verdict = { decision: 'ask', risk: 'unknown', reason: `Verificador auto no disponible: ${error.message}`, intent_quote: '', source: 'classifier-error' };
+    }
+    signal?.throwIfAborted();
+    if (this.mode !== 'auto') return this.authorize(name, input, { signal, onWaiting });
+    await this.onDecision({ type: 'auto_decision', name, input, ...verdict });
+    let allowed = verdict.decision === 'allow';
+    if (verdict.decision === 'ask') allowed = await this.ask(name, input, signal, onWaiting);
+    return { allowed, reason: verdict.reason, decision: verdict.decision, risk: verdict.risk, source: verdict.source };
+  }
+}

package/src/plugin-config.mjs

@@ -0,0 +1,95 @@
+import { open, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createHash, randomUUID } from 'node:crypto';
+
+const MAX_BYTES = 1024 * 1024;
+const ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const hash = bytes => createHash('sha256').update(bytes).digest('hex');
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+function fields(value, allowed, subject) {
+  if (!object(value)) throw new Error(`${subject} debe ser un objeto`);
+  for (const key of Object.keys(value)) if (!allowed.includes(key)) throw new Error(`${subject}: campo desconocido ${key}`);
+}
+
+function pluginId(value) {
+  if (typeof value !== 'string' || value.length > 24 || !ID.test(value)) throw new Error('ID de plugin inválido: usa minúsculas, números y guiones (máximo 24 caracteres)');
+}
+
+function modulePath(value, directory) {
+  if (typeof value !== 'string' || !value || value.includes('\0') || /[?#]/.test(value)
+    || /^[a-z][a-z0-9+.-]*:/i.test(value) || !['.mjs', '.js'].includes(path.extname(value))) {
+    throw new Error('El módulo de plugin debe ser un archivo local .mjs o .js');
+  }
+  return path.resolve(directory, value);
+}
+
+// Read a bounded regular file without importing it or evaluating configuration.
+async function boundedRead(file) {
+  const handle = await open(file, 'r');
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile()) throw new Error(`El archivo de plugin no es regular: ${file}`);
+    if (stat.size > MAX_BYTES) throw new Error(`El archivo de plugin supera 1 MiB: ${file}`);
+    const buffer = Buffer.alloc(MAX_BYTES + 1);
+    let offset = 0;
+    while (offset < buffer.length) {
+      const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, null);
+      if (!bytesRead) break;
+      offset += bytesRead;
+    }
+    if (offset > MAX_BYTES) throw new Error(`El archivo de plugin supera 1 MiB: ${file}`);
+    return buffer.subarray(0, offset);
+  } finally { await handle.close(); }
+}
+
+/** Discovery reads only JSON. Module source and top-level code require separate host trust. */
+export async function readPluginConfig(file, { missing = false } = {}) {
+  const absolute = path.resolve(file);
+  let bytes;
+  try { bytes = await boundedRead(absolute); }
+  catch (error) {
+    if (missing && error.code === 'ENOENT') return { file: absolute, hash: null, entries: [] };
+    throw error;
+  }
+  let config;
+  try { config = JSON.parse(bytes.toString('utf8')); }
+  catch (error) { throw new Error(`Configuración de plugins JSON inválida: ${error.message}`); }
+  fields(config, ['plugins'], 'Configuración de plugins');
+  if (!Array.isArray(config.plugins) || config.plugins.length > 32) throw new Error('plugins debe ser un arreglo con máximo 32 entradas');
+  const seen = new Set();
+  const entries = config.plugins.map(entry => {
+    fields(entry, ['id', 'module', 'enabled', 'config'], 'Entrada de plugin');
+    pluginId(entry.id);
+    if (seen.has(entry.id)) throw new Error(`ID de plugin duplicado: ${entry.id}`);
+    seen.add(entry.id);
+    if (entry.enabled !== undefined && typeof entry.enabled !== 'boolean') throw new Error(`enabled debe ser booleano: ${entry.id}`);
+    if (entry.config !== undefined && !object(entry.config)) throw new Error(`config debe ser un objeto: ${entry.id}`);
+    return { id: entry.id, module: modulePath(entry.module, path.dirname(absolute)), enabled: entry.enabled ?? true, config: entry.config ?? {} };
+  });
+  return { file: absolute, hash: hash(bytes), entries };
+}
+
+/** Import executes trusted host code. Call only after explicit human plugin trust. */
+export async function importPluginEntry(entry) {
+  pluginId(entry.id);
+  if (entry.enabled === false) throw new Error(`Plugin deshabilitado: ${entry.id}`);
+  const requested = modulePath(entry.module, process.cwd());
+  const module = await realpath(requested);
+  // A symlink must still resolve to a JavaScript entrypoint.
+  modulePath(module, process.cwd());
+  const before = await boundedRead(module);
+  const fingerprint = hash(before);
+  const url = pathToFileURL(module);
+  url.searchParams.set('comal_revision', `${fingerprint}-${randomUUID()}`);
+  const imported = await import(url.href);
+  const after = await boundedRead(module);
+  if (hash(after) !== fingerprint || await realpath(requested) !== module) throw new Error(`El módulo cambió durante la importación: ${entry.id}`);
+  const definition = imported.default;
+  if (!object(definition) || definition.id !== entry.id || typeof definition.version !== 'string'
+    || !definition.version.trim() || typeof definition.activate !== 'function') {
+    throw new Error(`Plugin inválido ${entry.id}: export default requiere id coincidente, version y activate`);
+  }
+  return { definition, fingerprint, module };
+}

package/src/plugins/chrome-lab/bridge.mjs

@@ -0,0 +1,206 @@
+// Shipped over SSH stdin, not installed on the laptop. Keep this function self-contained.
+export async function remoteBridge(config, lines) {
+  const fs = await import('node:fs/promises'), path = await import('node:path');
+  const { createHash, randomUUID } = await import('node:crypto');
+  const { createServer } = await import('node:http');
+  const root = path.resolve(config.remoteRoot);
+  if (!path.isAbsolute(config.remoteRoot) || root === path.parse(root).root) throw new Error('remoteRoot debe ser un directorio de laboratorio absoluto.');
+  const send = value => process.stdout.write(JSON.stringify(value) + '\n');
+  const digest = data => createHash('sha256').update(data).digest('hex');
+  let socket, sequence = 0, closing = false; const pending = new Map(), servers = new Map(), attached = new Set();
+  const cdp = (method, params = {}, sessionId) => new Promise((resolve, reject) => {
+    const id = ++sequence, timer = setTimeout(() => { pending.delete(id); reject(new Error(`CDP timeout: ${method}; no se reintentó.`)); }, config.timeoutMs);
+    pending.set(id, { resolve, reject, timer, method, params });
+    socket.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
+  });
+  const shutdown = async (detach = true) => {
+    if (closing) return; closing = true;
+    if (detach) {
+      let timer;
+      await Promise.race([Promise.allSettled([...attached].map(sessionId => cdp('Target.detachFromTarget', { sessionId }))), new Promise(resolve => { timer = setTimeout(resolve, 700); })]);
+      clearTimeout(timer);
+    }
+    for (const server of servers.values()) server.close();
+    for (const entry of pending.values()) { clearTimeout(entry.timer); entry.reject(new Error('CDP desconectado; efecto pendiente desconocido.')); } pending.clear();
+    if (socket && detach) await new Promise(resolve => {
+      const timer = setTimeout(resolve, 400); socket.addEventListener('close', () => { clearTimeout(timer); resolve(); }, { once: true }); socket.close();
+    });
+  };
+  lines.on('close', () => { void shutdown().finally(() => process.exit(0)); });
+  const fetchJSON = async route => {
+    const response = await fetch(config.cdpURL.replace(/\/$/, '') + route, { signal: AbortSignal.timeout(config.timeoutMs) });
+    if (!response.ok) throw new Error(`CDP HTTP ${response.status}: ${route}`);
+    return response.json();
+  };
+  const [version, protocol] = await Promise.all([fetchJSON('/json/version'), fetchJSON('/json/protocol')]);
+  const endpoint = new URL(version.webSocketDebuggerUrl), base = new URL(config.cdpURL);
+  // Browser endpoints often advertise localhost rather than their reverse proxy address.
+  endpoint.host = base.host; endpoint.protocol = base.protocol === 'https:' ? 'wss:' : 'ws:';
+  socket = new WebSocket(endpoint);
+  await new Promise((resolve, reject) => { socket.addEventListener('open', resolve, { once: true }); socket.addEventListener('error', () => reject(new Error('No se pudo abrir WebSocket CDP.')), { once: true }); });
+  socket.addEventListener('message', event => {
+    const message = JSON.parse(event.data);
+    if (message.id) { const entry = pending.get(message.id); if (!entry) return; pending.delete(message.id); clearTimeout(entry.timer); if (!message.error) { if (entry.method === 'Target.attachToTarget' && message.result?.sessionId) attached.add(message.result.sessionId); if (entry.method === 'Target.detachFromTarget') attached.delete(entry.params.sessionId); } message.error ? entry.reject(new Error(`${message.error.code}: ${message.error.message}`)) : entry.resolve(message.result); }
+    else if (['Runtime.consoleAPICalled', 'Runtime.exceptionThrown', 'Runtime.executionContextCreated', 'Runtime.executionContextDestroyed', 'Runtime.executionContextsCleared', 'Log.entryAdded', 'Network.loadingFailed', 'Inspector.detached', 'Target.detachedFromTarget'].includes(message.method)) {
+      // Never ship arbitrary object previews or network bodies into the resident's context.
+      if (message.method === 'Runtime.consoleAPICalled') message.params.args = (message.params.args || []).slice(0, 12).map(arg => ({ type: arg.type, text: String(arg.value ?? arg.description ?? arg.type).slice(0, 2000) }));
+      if (JSON.stringify(message).length < 64000) send({ event: message });
+    }
+  });
+  socket.addEventListener('close', () => { if (closing) return; void shutdown(false).finally(() => { send({ fatal: 'CDP cerrado; las operaciones pendientes no se reintentaron.' }); process.exit(1); }); });
+  socket.addEventListener('error', () => { send({ fatal: 'Error WebSocket CDP.' }); socket.close(); });
+  const slug = value => { if (!/^[a-z][a-z0-9-]{0,39}$/.test(value)) throw new Error('Proyecto inválido.'); return value; };
+  const safeFile = value => { if (typeof value !== 'string' || value.length > 220 || value.split('/').some(part => !part || !/^[a-zA-Z0-9_.@ -]+$/.test(part) || part === '.' || part === '..' || /[. ]$/.test(part) || /^(con|prn|aux|nul|com[0-9]|lpt[0-9])(?:\.|$)/i.test(part))) throw new Error('Ruta de archivo incompatible con Windows.'); return value; };
+  const realDirectory = async dir => { const stat = await fs.lstat(dir); if (!stat.isDirectory() || stat.isSymbolicLink() || (await fs.realpath(dir)).toLowerCase() !== path.resolve(dir).toLowerCase()) throw new Error('El laboratorio no admite enlaces/reparse points.'); };
+  const projectDir = name => path.join(root, slug(name));
+  const owned = async name => {
+    await realDirectory(root); const dir = projectDir(name); await realDirectory(dir);
+    const marker = JSON.parse(await fs.readFile(path.join(dir, '.comal-lab.json'), 'utf8'));
+    if (marker.owner !== 'comal-chrome-lab-v1' || marker.project !== name) throw new Error('Directorio remoto sin marca de propiedad Comal.');
+    return dir;
+  };
+  const extensions = async () => (await cdp('Extensions.getExtensions')).extensions;
+  const ownExtensions = async () => {
+    const all = await extensions(), ours = [];
+    for (const item of all) {
+      const directory = path.resolve(item.path), relative = path.relative(root, directory).split(path.sep);
+      if (relative.length !== 2 || relative[1].toLowerCase() !== 'current') continue;
+      try { await owned(relative[0]); await realDirectory(directory); ours.push({ ...item, project: relative[0] }); } catch { /* Never adopt an unmarked or redirected directory. */ }
+    }
+    return { extensions: ours.sort((a, b) => a.project.localeCompare(b.project)), other_extensions_count: all.length - ours.length };
+  };
+  const checkURL = async value => {
+    const url = new URL(value);
+    if (!['http:', 'https:', 'chrome-extension:'].includes(url.protocol) || url.username || url.password) throw new Error('Usa una URL http(s) o chrome-extension propia, sin credenciales.');
+    if (url.protocol === 'chrome-extension:' && !(await ownExtensions()).extensions.some(item => item.id === url.hostname)) throw new Error('Extensión fuera de los proyectos propios de Comal; no se abrió ni adjuntó. Consulta Status y usa extension_id del project solicitado.');
+    return url.href;
+  };
+  const checkTarget = async targetId => {
+    let targetInfo;
+    try { ({ targetInfo } = await cdp('Target.getTargetInfo', { targetId })); }
+    catch (error) {
+      if (!/No target|not found/i.test(error.message)) throw error;
+      const { targetInfos } = await cdp('Target.getTargets'), ours = await ownExtensions();
+      const available = targetInfos.filter(item => /^https?:/.test(item.url) || ours.extensions.some(extension => item.url.startsWith(`chrome-extension://${extension.id}/`))).slice(0, 12).map(item => ({ target_id: item.targetId, type: item.type, url: item.url.slice(0, 300) }));
+      throw new Error(JSON.stringify({ code: 'CHROME_TARGET_MISSING', executed: false, target_id: targetId, available_targets: available, next_action: 'Select the exact live target_id by URL/project; do not guess characters or reuse a target closed by Deploy.' }));
+    }
+    if (targetInfo.type === 'page' && (!targetInfo.url || targetInfo.url === 'about:blank')) throw new Error(JSON.stringify({ code: 'CHROME_TARGET_NAVIGATING', executed: false, target_id: targetId, next_action: 'A read may wait for a real authorized URL; do not dispatch an interaction to this transient document.' }));
+    await checkURL(targetInfo.url); return targetInfo;
+  };
+  const extensionFor = async name => { const dir = await owned(name); const expected = path.join(dir, 'current').toLowerCase(); const extension = (await extensions()).find(item => path.resolve(item.path).toLowerCase() === expected); if (!extension) throw new Error('Extensión del proyecto no cargada. Usa Deploy.'); return extension; };
+  const deploy = async ({ project, files, attempt_id = randomUUID() }) => {
+    if (!/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(attempt_id)) throw new Error('Identidad de publicación inválida.');
+    slug(project); if (!Array.isArray(files) || !files.length || files.length > 1000) throw new Error('Límite de archivos de despliegue.');
+    let bytes = 0; const names = new Set();
+    const decoded = files.map(file => { safeFile(file.path); const key = file.path.toLowerCase(); if (names.has(key)) throw new Error('Rutas duplicadas en Windows.'); names.add(key); const data = Buffer.from(file.data, 'base64'); bytes += data.length; if (bytes > config.maxDeployBytes || digest(data) !== file.sha256) throw new Error('Tamaño/hash inválido en despliegue.'); return { ...file, data }; });
+    const manifestFile = decoded.find(file => file.path === 'manifest.json');
+    const manifest = manifestFile && JSON.parse(manifestFile.data.toString('utf8'));
+    if (manifest?.manifest_version !== 3 || !manifest.name || !manifest.version) throw new Error('Se requiere manifest.json MV3 válido.');
+    await fs.mkdir(root, { recursive: true }); await realDirectory(root);
+    const dir = projectDir(project);
+    try { await fs.mkdir(dir); await fs.writeFile(path.join(dir, '.comal-lab.json'), JSON.stringify({ owner: 'comal-chrome-lab-v1', project }), { flag: 'wx' }); } catch (error) { if (error.code !== 'EEXIST') throw error; }
+    await owned(project);
+    const lock = path.join(dir, '.deploy-lock'); await fs.mkdir(lock); // Fail closed if another Comal is deploying.
+    const stage = path.join(dir, `stage-${randomUUID()}`), current = path.join(dir, 'current'), backup = path.join(dir, `backup-${randomUUID()}`);
+    let moved = false, swapped = false;
+    try {
+      await fs.mkdir(stage);
+      for (const file of decoded) { const target = path.join(stage, ...file.path.split('/')); await fs.mkdir(path.dirname(target), { recursive: true }); await fs.writeFile(target, file.data, { flag: 'wx' }); }
+      try { await realDirectory(current); await fs.rename(current, backup); moved = true; } catch (error) { if (error.code !== 'ENOENT') throw error; }
+      await fs.rename(stage, current); swapped = true;
+      const loaded = await cdp('Extensions.loadUnpacked', { path: current });
+      const observed = (await extensions()).find(item => item.id === loaded.id && path.resolve(item.path).toLowerCase() === current.toLowerCase());
+      if (!observed?.enabled) throw new Error('Chrome no confirmó la extensión habilitada.');
+      const artifact = { project, attempt_id, extension_id: loaded.id, remote_path: current, manifest: { name: manifest.name, version: manifest.version }, bytes, files: files.map(({ path, sha256 }) => ({ path, sha256 })), observed_at: new Date().toISOString() };
+      const receipt = path.join(dir, `deployment-${attempt_id}.tmp`);
+      await fs.writeFile(receipt, JSON.stringify(artifact), { flag: 'wx' });
+      await fs.rename(receipt, path.join(dir, 'deployment.json'));
+      if (moved) await fs.rm(backup, { recursive: true, force: true });
+      return { ...artifact, files: artifact.files.slice(0, 30), file_count: artifact.files.length, files_truncated: artifact.files.length > 30, file_manifest_sha256: digest(JSON.stringify(artifact.files)), file_manifest_remote_path: path.join(dir, 'deployment.json'), note: 'Carga observada; prueba funcional pendiente. Recarga las páginas para renovar content scripts.' };
+    } catch (error) {
+      // Do not retry CDP: a lost reply may have installed the extension already.
+      if (swapped) await fs.rm(current, { recursive: true, force: true });
+      if (moved) await fs.rename(backup, current);
+      throw new Error(`${error.message} Archivos anteriores restaurados; estado de Chrome debe verificarse con Status/Targets antes de reintentar.`);
+    } finally { await fs.rm(stage, { recursive: true, force: true }); await fs.rmdir(lock); }
+  };
+  // Read-only reconciliation: a historical receipt alone cannot attest current files/Chrome.
+  const deployment = async ({ project }) => {
+    const dir = await owned(project), current = path.join(dir, 'current'), receipt = path.join(dir, 'deployment.json');
+    const locked = async () => { try { await fs.lstat(path.join(dir, '.deploy-lock')); return true; } catch (error) { if (error.code !== 'ENOENT') throw error; return false; } };
+    if (await locked()) return { status: 'busy', project };
+    const readReceipt = async () => {
+      const stat = await fs.lstat(receipt);
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1000000 || (await fs.realpath(receipt)).toLowerCase() !== receipt.toLowerCase()) throw new Error('Recibo remoto inválido.');
+      return fs.readFile(receipt, 'utf8');
+    };
+    let raw; try { raw = await readReceipt(); } catch (error) { if (error.code === 'ENOENT') return { status: 'unavailable', project }; throw error; }
+    const artifact = JSON.parse(raw);
+    if (artifact.project !== project || artifact.remote_path?.toLowerCase() !== current.toLowerCase() || !Array.isArray(artifact.files) || !artifact.files.length || artifact.files.length > 1000) throw new Error('Recibo de otro proyecto o snapshot inválido.');
+    await realDirectory(current);
+    const observedFiles = []; let bytes = 0;
+    const visit = async (directory, prefix = '') => {
+      await realDirectory(directory);
+      for (const entry of (await fs.readdir(directory, { withFileTypes: true })).sort((a,b)=>a.name.localeCompare(b.name))) {
+        const relative = prefix + entry.name; safeFile(relative); const absolute = path.join(directory, entry.name), before = await fs.lstat(absolute);
+        if (before.isDirectory() && !before.isSymbolicLink()) { await visit(absolute, relative+'/'); continue; }
+        if (!before.isFile() || before.isSymbolicLink() || (await fs.realpath(absolute)).toLowerCase() !== absolute.toLowerCase()) throw new Error('Snapshot remoto contiene enlaces o archivos inválidos.');
+        bytes += before.size; if (bytes > config.maxDeployBytes || observedFiles.length >= 1000) throw new Error('Snapshot remoto excesivo.');
+        const data = await fs.readFile(absolute), after = await fs.lstat(absolute);
+        if (before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ino !== after.ino || data.length !== before.size) throw new Error('Snapshot remoto cambió durante la lectura.');
+        observedFiles.push({ path: relative, sha256: digest(data) });
+      }
+    };
+    await visit(current);
+    const extension = (await extensions()).find(item=>item.id===artifact.extension_id && path.resolve(item.path).toLowerCase()===current.toLowerCase());
+    if (await locked() || await readReceipt() !== raw) return { status: 'busy', project };
+    if (!extension?.enabled || JSON.stringify(observedFiles) !== JSON.stringify(artifact.files)) return { status: 'conflict', project, attempt_id: artifact.attempt_id || null, reason: 'Loaded extension or physical snapshot no longer matches the receipt.' };
+    return { ...artifact, status: 'observed', files: artifact.files.slice(0,30), file_count: artifact.files.length, files_truncated: artifact.files.length>30, file_manifest_sha256: digest(JSON.stringify(artifact.files)), file_manifest_remote_path: receipt, checked_at: new Date().toISOString() };
+  };
+  const preview = async ({ project, file = 'fixture.html' }) => {
+    const dir = path.join(await owned(project), 'current'); safeFile(file);
+    await realDirectory(dir); const requested = path.join(dir, ...file.split('/'));
+    if (!(await fs.stat(requested)).isFile() || (await fs.realpath(requested)).toLowerCase() !== requested.toLowerCase()) throw new Error('Fixture no es un archivo regular del proyecto.');
+    let server = servers.get(project);
+    if (!server) {
+      server = createServer(async (request, response) => {
+        try {
+          const name = decodeURIComponent(new URL(request.url, 'http://localhost').pathname).slice(1); safeFile(name);
+          if (!['GET', 'HEAD'].includes(request.method)) { response.writeHead(405).end(); return; }
+          const target = path.join(dir, ...name.split('/')); const real = await fs.realpath(target);
+          if (real.toLowerCase() !== target.toLowerCase() || !(await fs.stat(real)).isFile()) throw new Error('Archivo inválido.');
+          const data = await fs.readFile(real); if (data.length > config.maxDeployBytes) throw new Error('Archivo demasiado grande.');
+          const mime = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript', '.css': 'text/css', '.json': 'application/json', '.svg': 'image/svg+xml' }[path.extname(real)] || 'application/octet-stream';
+          response.writeHead(200, { 'Content-Type': mime, 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff' }); response.end(request.method === 'HEAD' ? undefined : data);
+        } catch { response.writeHead(404).end('Not found'); }
+      });
+      await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve); }); servers.set(project, server);
+    }
+    return { url: `http://127.0.0.1:${server.address().port}/${file.split('/').map(encodeURIComponent).join('/')}`, lifetime: 'plugin_connection' };
+  };
+  lines.on('line', async line => {
+    let request;
+    try {
+      if (line.length > config.maxDeployBytes * 1.5 + 1000000) throw new Error('Mensaje demasiado grande.');
+      request = JSON.parse(line); let result;
+      if (request.action === 'cdp') result = await cdp(request.method, request.params, request.sessionId);
+      else if (request.action === 'status') result = await ownExtensions();
+      else if (request.action === 'checkTarget') result = await checkTarget(request.params.targetId);
+      else if (request.action === 'open') result = await cdp('Target.createTarget', { url: await checkURL(request.params.url) });
+      else if (request.action === 'navigate') { await checkTarget(request.params.targetId); result = await cdp('Page.navigate', { url: await checkURL(request.params.url) }, request.sessionId); }
+      else if (request.action === 'targets') {
+        const { targetInfos } = await cdp('Target.getTargets'), ours = await ownExtensions();
+        result = { targetInfos: targetInfos.filter(item => /^https?:/.test(item.url) || item.url.startsWith('chrome-extension://') && ours.extensions.some(extension => item.url.startsWith(`chrome-extension://${extension.id}/`))).map(item => ({ ...item, project: ours.extensions.find(extension => item.url.startsWith(`chrome-extension://${extension.id}/`))?.project })) };
+      }
+      else if (request.action === 'deploy') result = await deploy(request.params);
+      else if (request.action === 'deployment') result = await deployment(request.params);
+      else if (request.action === 'preview') result = await preview(request.params);
+      else if (request.action === 'unload') { const extension = await extensionFor(request.params.project); await cdp('Extensions.uninstall', { id: extension.id }); result = { extension_id: extension.id, unloaded: true }; }
+      else throw new Error('Acción del bridge desconocida.');
+      const output = JSON.stringify({ id: request.id, result });
+      if (output.length > 12000000) throw new Error('Respuesta excesiva; usa consultas acotadas.');
+      process.stdout.write(output + '\n');
+    } catch (error) { send({ id: request?.id, error: error.message }); }
+  });
+  send({ ready: { browser: version.Browser, browser_endpoint_id: /^\/devtools\/browser\/([^/]+)$/.exec(endpoint.pathname)?.[1] || null, protocol_version: version['Protocol-Version'], extensions: protocol.domains.find(domain => domain.domain === 'Extensions')?.commands.map(command => command.name) || [], remote_root: root, node: process.version } });
+}

package/src/plugins/chrome-lab/client.mjs

@@ -0,0 +1,123 @@
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { randomUUID } from 'node:crypto';
+import { remoteBridge } from './bridge.mjs';
+
+export class ChromeLabClient {
+  constructor(config, { spawnProcess = spawn } = {}) {
+    this.config = config; this.spawnProcess = spawnProcess; this.pending = new Map(); this.sessions = new Map(); this.attaching = new Map(); this.targetInfo = new Map(); this.contexts = new Map(); this.events = []; this.sequence = 0; this.closed = false;
+  }
+  async connect(signal) {
+    signal?.throwIfAborted(); if (this.closed) throw new Error('Plugin Chrome Lab cerrado.');
+    if (!this.connection) this.connection = this.start();
+    if (!signal) return this.connection;
+    return new Promise((resolve, reject) => {
+      const abort = () => reject(signal.reason || new Error('Conexión cancelada.'));
+      signal.addEventListener('abort', abort, { once: true });
+      this.connection.then(value => { signal.removeEventListener('abort', abort); resolve(value); }, error => { signal.removeEventListener('abort', abort); reject(error); });
+      if (signal.aborted) abort();
+    });
+  }
+  start() {
+    this.connectionId = randomUUID();
+    return new Promise((resolve, reject) => {
+      let ready = false, stderr = '';
+      const bootstrap = "const r=require('readline').createInterface({input:process.stdin});r.once('line',l=>{const p=JSON.parse(l);eval(p.source)(p.config,r).catch(e=>{console.log(JSON.stringify({fatal:e.message}));process.exit(1)})})";
+      const child = this.child = this.spawnProcess('ssh', ['-T', '-o', 'BatchMode=yes', '-o', 'ClearAllForwardings=yes', '-o', 'ConnectTimeout=10', '-o', 'ServerAliveInterval=10', '-o', 'ServerAliveCountMax=2', this.config.sshHost, `node -e "${bootstrap}"`], { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
+      const timer = setTimeout(() => { fail(new Error('Timeout iniciando Chrome Lab por SSH.')); child.kill(); }, this.config.timeoutMs);
+      const fail = error => { clearTimeout(timer); if (this.child !== child) return; this.failure = error; if (!ready) reject(error); for (const entry of this.pending.values()) entry.finish(error); this.pending.clear(); };
+      child.on('error', fail); child.stdin.on('error', fail);
+      child.stderr.on('data', chunk => { stderr = (stderr + chunk.toString()).slice(-1500); });
+      child.on('exit', (code, sig) => fail(new Error(`Chrome Lab desconectado (${code ?? sig}); no se reintentaron efectos pendientes. ${stderr}`)));
+      const lines = createInterface({ input: child.stdout });
+      lines.on('line', line => {
+        if (this.child !== child) return;
+        try {
+          if (line.length > 12000000) throw new Error('Salida del bridge excesiva.');
+          const message = JSON.parse(line);
+          if (message.fatal) { fail(new Error(message.fatal)); child.kill(); }
+          else if (message.ready) { ready = true; clearTimeout(timer); this.info = message.ready; resolve(message.ready); }
+          else if (message.event) this.observe(message.event);
+          else { const entry = this.pending.get(message.id); if (entry) entry.finish(message.error ? new Error(message.error) : null, message.result); }
+        } catch (error) { fail(error); child.kill(); }
+      });
+      child.stdin.write(JSON.stringify({ source: `(${remoteBridge.toString()})`, config: this.config }) + '\n');
+    });
+  }
+  observe(event) {
+    const { method, params = {}, sessionId } = event;
+    if (method === 'Target.detachedFromTarget') { for (const [target, session] of this.sessions) if (session === params.sessionId) this.sessions.delete(target); this.contexts.delete(params.sessionId); }
+    if (method === 'Inspector.detached') { for (const [target, session] of this.sessions) if (session === sessionId) this.sessions.delete(target); this.contexts.delete(sessionId); }
+    if (method === 'Runtime.executionContextCreated') { const contexts = this.contexts.get(sessionId) || new Map(); contexts.set(params.context.id, params.context); this.contexts.set(sessionId, contexts); return; }
+    if (method === 'Runtime.executionContextDestroyed') { this.contexts.get(sessionId)?.delete(params.executionContextId); return; }
+    if (method === 'Runtime.executionContextsCleared') { this.contexts.delete(sessionId); return; }
+    const target_id = [...this.sessions].find(([, session]) => session === sessionId)?.[0];
+    const raw = JSON.stringify(params);
+    this.events.push({ method, target_id, observed_at: new Date().toISOString(), details: raw.length > 4000 ? { truncated: true, preview: raw.slice(0, 4000) } : params });
+    if (this.events.length > 200) this.events.shift();
+  }
+  async request(action, params, { signal, ...extra } = {}) {
+    await this.connect(signal); signal?.throwIfAborted(); if (this.failure) throw this.failure;
+    return new Promise((resolve, reject) => {
+      const id = ++this.sequence;
+      const abort = () => finish(new Error('Operación abortada tras despacho; el efecto remoto puede haber ocurrido. Verifica antes de repetir.'));
+      const timer = setTimeout(() => finish(new Error('Timeout Chrome Lab; efecto remoto desconocido, no se reintentó.')), this.config.timeoutMs + 2000);
+      const finish = (error, value) => { clearTimeout(timer); signal?.removeEventListener('abort', abort); this.pending.delete(id); error ? reject(error) : resolve(value); };
+      this.pending.set(id, { finish }); signal?.addEventListener('abort', abort, { once: true });
+      this.child.stdin.write(JSON.stringify({ id, action, params, ...extra }) + '\n', error => { if (error) finish(error); });
+    });
+  }
+  cdp(method, params = {}, { signal, sessionId } = {}) { return this.request('cdp', params, { signal, method, sessionId }); }
+  resourceIdentity(targetId) {
+    const contexts = [...(this.contexts.get(this.sessions.get(targetId))?.values() || [])];
+    const defaults = contexts.filter(item => item.auxData?.isDefault === true && typeof item.uniqueId === 'string' && item.uniqueId);
+    return { connection_id: this.connectionId || null, browser_endpoint_id: this.info?.browser_endpoint_id || null,
+      context_unique_id: defaults.length === 1 ? defaults[0].uniqueId : null,
+      frame_id: defaults.length === 1 ? defaults[0].auxData.frameId || null : null };
+  }
+  // Explicit recovery only. A new connection does not replay any request or resolve its effect.
+  async reconnect(signal) {
+    signal?.throwIfAborted();
+    if (this.pending.size || this.attaching.size || this.reconnecting || this.connection && !this.info && !this.failure) throw new Error('Chrome Lab ocupado; no se interrumpe otra operación para reconciliar.');
+    this.reconnecting = true;
+    try {
+      await this.close(); this.child = undefined; this.connection = undefined; this.failure = undefined; this.info = undefined; this.closed = false;
+      this.sessions.clear(); this.contexts.clear(); this.attaching.clear(); this.targetInfo.clear(); this.events = [];
+      return await this.connect(signal);
+    } finally { this.reconnecting = false; }
+  }
+  async attach(targetId, signal) {
+    this.targetInfo.set(targetId, await this.request('checkTarget', { targetId }, { signal }));
+    if (this.attaching.has(targetId)) return this.attaching.get(targetId);
+    if (this.sessions.has(targetId)) return this.sessions.get(targetId);
+    const attaching = (async () => {
+      const { sessionId } = await this.cdp('Target.attachToTarget', { targetId, flatten: true }, { signal });
+      this.sessions.set(targetId, sessionId);
+      try {
+        await this.cdp('Runtime.enable', {}, { signal, sessionId });
+        await this.cdp('Log.enable', {}, { signal, sessionId }).catch(() => {});
+        await this.cdp('Network.enable', { maxTotalBufferSize: 100000, maxResourceBufferSize: 10000 }, { signal, sessionId }).catch(() => {});
+        return sessionId;
+      } catch (error) { this.sessions.delete(targetId); this.contexts.delete(sessionId); await this.cdp('Target.detachFromTarget', { sessionId }).catch(() => {}); throw error; }
+    })();
+    this.attaching.set(targetId, attaching);
+    try { return await attaching; } finally { this.attaching.delete(targetId); }
+  }
+  async evaluate(targetId, expression, { signal, context_id, await_promise = false } = {}) {
+    const sessionId = await this.attach(targetId, signal);
+    const result = await this.cdp('Runtime.evaluate', { expression, returnByValue: true, awaitPromise: await_promise, timeout: Math.min(10000, this.config.timeoutMs), allowUnsafeEvalBlockedByCSP: false, ...(context_id !== undefined ? { contextId: context_id } : {}) }, { signal, sessionId });
+    if (result.exceptionDetails) {
+      const info = this.targetInfo.get(targetId);
+      return { ok: false, error: (result.exceptionDetails.exception?.description || result.exceptionDetails.text).slice(0, 4000), ...(info ? { target: { target_id: targetId, type: info.type, url: info.url } } : {}), ...(/^https?:/.test(info?.url || '') && context_id === undefined ? { next_action: 'This is the HTTP page main world. chrome.storage/tabs extension APIs belong to the OWN extension target, or a suitable isolated context from Contexts. Use the exact target by project URL; await Promise APIs with await_promise:true.' } : {}) };
+    }
+    const value = result.result.value ?? result.result.unserializableValue ?? null;
+    const serialized = Buffer.from(JSON.stringify(value));
+    if (serialized.length > 24000) return { ok: true, truncated: true, preview: serialized.subarray(0, 24000).toString('utf8') };
+    return { ok: true, value };
+  }
+  async close() {
+    if (this.closed) return; this.closed = true;
+    if (!this.child || this.child.exitCode !== null || this.child.signalCode !== null) return;
+    await new Promise(resolve => { const timer = setTimeout(() => { this.child.kill('SIGKILL'); resolve(); }, 1500); this.child.once('exit', () => { clearTimeout(timer); resolve(); }); this.child.stdin.end(); });
+  }
+}