@milpa/comal 0.2.2 → 0.2.4

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

@@ -1,15 +1,135 @@
 import { spawn } from 'node:child_process';
 import { createInterface } from 'node:readline';
-import { randomUUID } from 'node:crypto';
+import { randomUUID, createHash } from 'node:crypto';
+import { performance } from 'node:perf_hooks';
+import {AsyncLocalStorage} from 'node:async_hooks';
 import { remoteBridge } from './bridge.mjs';
 import { OPTIONAL_PHASE_MS, PUBLIC_DIAGNOSTIC_BYTES, diagnosticEnvelope } from './diagnostics.mjs';
+import { parseNativeReply } from './native-reply.mjs';
+import {legacyFill,takeLegacyFillOrigin} from './legacy-fill.mjs';
+const nativeSignalAborted=Object.getOwnPropertyDescriptor(AbortSignal.prototype,'aborted').get;
+const originalSignalState=signal=>{if(signal===undefined)return false;try{return nativeSignalAborted.call(signal);}catch{return null;}};
 
 export class ChromeLabClient {
+  #nativeReplies = new WeakMap();
+  #pendingReplies = new Map();
+  #replyConnectionGeneration = 0;
+  #replySessionGenerations = new Map();
+  #requestSequence = 0;
+  #replyAttachments = new Map();
+  #recentRequests = new Map();
+  #fillCompletions = new WeakMap();
+  #fillObservations = new WeakMap();
+  #fillOrder = 0;
+  #fillOwner = new AsyncLocalStorage();
+  async fillLegacy(input,options) {
+    const originalOptions=Object.freeze({signal:options.signal,sessionId:options.sessionId});
+    const frame=Object.freeze({owner:Object.freeze({}),start:this.#requestSequence,order:++this.#fillOrder,signal:originalOptions.signal});
+    return this.#fillOwner.run(frame,async()=>{
+      const result=await legacyFill(this,input,originalOptions),origin=takeLegacyFillOrigin(result);
+      if(origin)this.#recordFillCompletion(result,origin,frame);
+      return result;
+    });
+  }
+  #recordFillCompletion(result,origin,frame) {
+    if(origin.client!==this || typeof origin.input.selector!=='string'||origin.options.signal!==frame.signal||originalSignalState(frame.signal)!==false)return;
+    const a=this.#nativeReplies.get(origin.activation),f=this.#nativeReplies.get(origin.error);
+    const activation=this.nativeReplyProvenance(origin.activation),focus=this.nativeReplyProvenance(origin.error);
+    if(!a||!f||!activation||!focus||activation.method!=='Page.bringToFront'||activation.outcome!=='native_success_reply'||
+        focus.method!=='DOM.focus'||focus.outcome!=='native_error_reply')return;
+    const error=JSON.parse(focus.reply_json).error;
+    if(error.code!==-32000||error.message!=='Element is not focusable')return;
+    const first=a.capture.guard.id,last=f.capture.guard.id;
+    if(first!==frame.start+1||last!==first+3||last!==this.#requestSequence)return;
+    const captures=Array.from({length:4},(_,i)=>this.#recentRequests.get(first+i));
+    const methods=['Page.bringToFront','DOM.getDocument','DOM.querySelector','DOM.focus'];
+    if(captures.some((c,i)=>!c||c.guard.fillOwner!==frame.owner||c.guard.method!==methods[i]||c.guard.action!=='cdp'||!c.state.settled||!c.state.observedReply||c.state.nativeFailed!==(i===3)||
+        c.state.writeState!=='acknowledged'||c.state.failed!==(i===3)||
+        originalSignalState(c.guard.signal)!==false||c.guard.sessionId!==origin.options.sessionId||
+        !c.guard.binding||Object.keys(c.guard.binding).some(k=>c.guard.binding[k]!==a.capture.guard.binding[k])))return;
+    if(captures[0]!==a.capture||captures[3]!==f.capture||activation.target_id!==origin.input.target_id||focus.target_id!==origin.input.target_id)return;
+    const root=captures[1].state.nodeId,node=captures[2].state.nodeId;
+    if(!Number.isSafeInteger(root)||root<1||!Number.isSafeInteger(node)||node<1)return;
+    const params=[{}, {depth:0}, {nodeId:root,selector:origin.input.selector}, {nodeId:node}];
+    if(captures.some((c,i)=>c.guard.paramsSha256!==createHash('sha256').update(JSON.stringify(params[i])).digest('hex')))return;
+    Object.freeze(result.observation.cdp_error);Object.freeze(result.observation);Object.freeze(result);
+    this.#fillCompletions.set(result,{origin,captures,last,frame});
+  }
+  beginLegacyFillObservation(signal) {
+    if(signal===undefined||originalSignalState(signal)!==false)throw new Error('A live original handler signal is required for input observation.');
+    const token=Object.freeze({});this.#fillObservations.set(token,Object.freeze({signal,start:this.#requestSequence,order:++this.#fillOrder}));return token;
+  }
+  closeLegacyFillObservation(token){this.#fillObservations.delete(token);}
+  takeLegacyFillCompletion(result,observation) {
+    let boundary=null;
+    if(arguments.length>1){boundary=this.#fillObservations.get(observation);this.#fillObservations.delete(observation);if(!boundary||originalSignalState(boundary.signal)!==false)return null;}
+    const record=result&&typeof result==='object'?this.#fillCompletions.get(result):null;
+    if(!record)return null;this.#fillCompletions.delete(result);
+    const {origin,captures,last,frame}=record,activation=this.nativeReplyProvenance(origin.activation),focus=this.nativeReplyProvenance(origin.error);
+    if(boundary&&(frame.signal!==boundary.signal||frame.start<boundary.start||frame.order<=boundary.order))return null;
+    if(originalSignalState(frame.signal)!==false||last!==this.#requestSequence||!activation||!focus||captures.some(c=>c.state.writeState!=='acknowledged'||
+        originalSignalState(c.guard.signal)!==false||performance.now()>=c.guard.requestDeadline))return null;
+    return Object.freeze({format:'comal-legacy-fill-completion/1',outcome:'completed_blocked_before_keyboard',
+      target_id:origin.input.target_id,selector:origin.input.selector,
+      request_ids:Object.freeze(captures.map(c=>c.guard.id)),activation,focus,input_commands_started:0,
+      original_handler_signal_bound:frame.signal!==undefined,
+      native_boundary_bound:boundary!==null,
+      authority:false,behavior_acceptance:false,retry_authorized:false,remote_nonexecution_proved:false,phase_lifetime_bound:false});
+  }
+  #replyBinding(sessionId) {
+    const targets = [...this.sessions].filter(([, id]) => id === sessionId);
+    if (this.closed || this.failure || !this.connectionId || !this.info?.browser_endpoint_id ||
+        typeof sessionId !== 'string' || !sessionId || targets.length !== 1) return null;
+    const attached=this.#replyAttachments.get(sessionId);
+    if(!attached || attached.targetId!==targets[0][0] || attached.connectionId!==this.connectionId ||
+        attached.browserEndpointId!==this.info.browser_endpoint_id || attached.generation!==this.#replyConnectionGeneration)return null;
+    if(!this.#replySessionGenerations.has(sessionId))this.#replySessionGenerations.set(sessionId,Object.freeze({}));
+    return {connectionId:this.connectionId, browserEndpointId:this.info.browser_endpoint_id,
+      sessionId, targetId:targets[0][0], contextEpoch:this.collections.get(sessionId)?.epoch ?? null,
+      connectionGeneration:this.#replyConnectionGeneration,sessionGeneration:this.#replySessionGenerations.get(sessionId)};
+  }
+  #recordNativeReply(message, entry, error, result) {
+    const capture=this.#pendingReplies.get(message.id),guard=capture?.guard;
+    if (!guard || guard.id!==message.id || capture.entry!==entry || capture.state.settled || guard.action !== 'cdp')return;
+    capture.state.observedReply=true;capture.state.nativeFailed=Boolean(error);
+    capture.state.nodeId=guard.method==='DOM.getDocument'?result?.root?.nodeId:guard.method==='DOM.querySelector'?result?.nodeId:null;
+    const current=guard.connectionId===this.connectionId && guard.browserEndpointId===this.info?.browser_endpoint_id && guard.connectionGeneration===this.#replyConnectionGeneration;
+    if(current && !error && guard.method==='Target.attachToTarget' && guard.attachTargetId &&
+        result && Object.keys(result).join()==='sessionId' && typeof result.sessionId==='string' && result.sessionId) {
+      this.#replySessionGenerations.delete(result.sessionId);
+      this.#replyAttachments.set(result.sessionId,this.#replyAttachments.has(result.sessionId)?null:Object.freeze({targetId:guard.attachTargetId,
+        connectionId:guard.connectionId,browserEndpointId:guard.browserEndpointId,generation:guard.connectionGeneration}));
+    }
+    if(current && !error && guard.method==='Target.detachFromTarget'){this.#replyAttachments.delete(guard.detachSessionId);this.#replySessionGenerations.delete(guard.detachSessionId);}
+    if (!guard.binding ||
+        !Number.isFinite(guard.requestDeadline) || !Number.isSafeInteger(guard.requestBudgetMs) ||
+        guard.requestBudgetMs<1 || guard.requestBudgetMs>2147483647) return;
+    const proof = parseNativeReply(message.native_reply, {id:guard.id, method:guard.method,
+      sessionId:guard.sessionId, paramsSha256:guard.paramsSha256,
+      browserEndpointId:guard.binding.browserEndpointId, error, cdpError:error?.cdpError, result});
+    const value = error || result;
+    if (proof && value && typeof value === 'object') this.#nativeReplies.set(value, {capture, proof});
+  }
+  nativeReplyProvenance(value) {
+    const record = value && typeof value === 'object' ? this.#nativeReplies.get(value) : null;
+    if (!record) return null;
+    const {capture, proof} = record,{guard,state}=capture,binding = this.#replyBinding(guard.sessionId);
+    if (state.writeState !== 'acknowledged' || !state.settled || originalSignalState(guard.signal)!==false ||
+        performance.now() >= guard.requestDeadline || !binding ||
+        Object.keys(binding).some(k => binding[k] !== guard.binding[k])) return null;
+    // This is an observation of this original object, never a live host-phase
+    // capability. The admitting House invocation/deadline must be bound separately.
+    return Object.freeze({...proof, target_id:binding.targetId, connection_id:binding.connectionId,
+      original_signal_bound:guard.signal!==undefined});
+  }
   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.collections = new Map(); this.events = []; this.sequence = 0; this.closed = false; this.attachDiagnostics = new Map();
+    // Ownership recorded by this connection: only these are cleaned up in relay mode.
+    this.openedTargets = new Set(); this.deployedProjects = new Set(); this.lastCleanup = null;
   }
   async connect(signal) {
     signal?.throwIfAborted(); if (this.closed) throw new Error('Plugin Chrome Lab cerrado.');
+    if (this.preempted() && !this.pending.size && !this.attaching.size && !this.reconnecting) this.forgetPreemptedTransport();
     if (!this.connection) this.connection = this.start();
     if (!signal) return this.connection;
     return new Promise((resolve, reject) => {
@@ -19,17 +139,31 @@ export class ChromeLabClient {
       if (signal.aborted) abort();
     });
   }
+  // Relay mode: relayd cut the SSH bridge because another attempt or check was waiting for the
+  // host (it says so on stderr) and closed this attempt's tabs. That is not an uncertain
+  // transport: whatever was pending already failed, so the next operation is new and may open
+  // another connection, which waits for its turn in relayd's lease queue. Nothing is replayed.
+  preempted() {
+    return Boolean(this.failure) && this.failureReason === 'connection_lost' && Boolean(process.env.RELAY_REMOTE_NAMESPACE) && /relay-ssh: LEASE_EXPIRED/.test(this.transportStderr?.() || '');
+  }
+  forgetPreemptedTransport() {
+    for (const record of this.attachDiagnostics.values()) this.retireDiagnostic(record.session_id, 'lease_preempted');
+    this.child = undefined; this.connection = undefined; this.failure = undefined; this.failureReason = undefined; this.info = undefined; this.transportStderr = undefined;
+    this.attachDiagnostics.clear(); this.sessions.clear(); this.contexts.clear(); this.collections.clear(); this.targetInfo.clear(); this.events = []; this.openedTargets.clear();
+  }
   start() {
+    this.#replyConnectionGeneration++;
     this.connectionId = randomUUID();
     return new Promise((resolve, reject) => {
       let ready = false, stderr = '';
+      this.transportStderr = () => 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,reason='transport_uncertain') => { clearTimeout(timer); if (this.child !== child) return; for(const record of this.attachDiagnostics.values()) this.retireDiagnostic(record.session_id,reason); this.failure = error; if (!ready) reject(error); for (const entry of this.pending.values()) entry.finish(error); this.pending.clear(); };
+      const fail = (error,reason='transport_uncertain') => { clearTimeout(timer); if (this.child !== child) return; this.#replyConnectionGeneration++;this.#replyAttachments.clear();for(const record of this.attachDiagnostics.values()) this.retireDiagnostic(record.session_id,reason); this.failure = error; this.failureReason = reason; 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}`),'connection_lost'));
+      child.on('exit', (code, sig) => fail(new Error(`Chrome Lab desconectado (${code ?? sig}); no se reintentaron efectos pendientes. ${stderr}${process.env.RELAY_REMOTE_NAMESPACE ? ' Si relayd cedió el host (LEASE_EXPIRED), la siguiente operación reconecta y espera su turno; tus pestañas se cerraron, vuelve a abrirlas.' : ''}`),'connection_lost'));
       const lines = createInterface({ input: child.stdout });
       lines.on('line', line => {
         if (this.child !== child) return;
@@ -39,7 +173,7 @@ export class ChromeLabClient {
           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) { const error = message.error ? new Error(message.error) : null; if(error && entry.action==='cdp' && message.cdp_error?.method===entry.method && Number.isInteger(message.cdp_error.code) && typeof message.cdp_error.message==='string')error.cdpError={method:entry.method,code:message.cdp_error.code,message:message.cdp_error.message.slice(0,1000)};let result=message.result; if(!error && entry.attachDiagnostic) diagnosticEnvelope(result,{method:entry.method,sessionId:entry.sessionId,timeout_ms:entry.attachDiagnostic.timeout_ms}); entry.finish(error,result); } }
+          else { const entry = this.pending.get(message.id); if (entry) { const error = message.error ? new Error(message.error) : null; if(error && entry.action==='cdp' && message.cdp_error?.method===entry.method && Number.isInteger(message.cdp_error.code) && typeof message.cdp_error.message==='string')error.cdpError={method:entry.method,code:message.cdp_error.code,message:message.cdp_error.message.slice(0,1000)};let result=message.result; if(!error && entry.attachDiagnostic) diagnosticEnvelope(result,{method:entry.method,sessionId:entry.sessionId,timeout_ms:entry.attachDiagnostic.timeout_ms}); this.#recordNativeReply(message,entry,error,result); entry.finish(error,result); } }
         } catch (error) { fail(error); child.kill(); }
       });
       child.stdin.write(JSON.stringify({ source: `(${remoteBridge.toString()})`, config: this.config }) + '\n');
@@ -47,6 +181,9 @@ export class ChromeLabClient {
   }
   observe(event) {
     const { method, params = {}, sessionId } = event;
+    const retiredSession=method==='Target.detachedFromTarget'?params.sessionId:sessionId;
+    if(['Target.detachedFromTarget','Inspector.detached'].includes(method)){this.#replySessionGenerations.delete(retiredSession);this.#replyAttachments.delete(retiredSession);}
+    else if(['Runtime.executionContextCreated','Runtime.executionContextDestroyed','Runtime.executionContextsCleared'].includes(method)&&this.#replySessionGenerations.has(sessionId))this.#replySessionGenerations.set(sessionId,Object.freeze({}));
     if (method === 'Target.detachedFromTarget') { this.retireDiagnostic(params.sessionId); for (const [target, session] of this.sessions) if (session === params.sessionId) this.sessions.delete(target); this.contexts.delete(params.sessionId); }
     if (method === 'Inspector.detached') { this.retireDiagnostic(sessionId); for (const [target, session] of this.sessions) if (session === sessionId) this.sessions.delete(target); this.contexts.delete(sessionId); }
     if (method === 'Runtime.executionContextCreated') {
@@ -74,18 +211,54 @@ export class ChromeLabClient {
     if (this.events.length > 200) this.events.shift();
   }
   async request(action, params, { signal, expectedBinding, onDispatch, ...extra } = {}) {
+    if(['id','action','params','toJSON'].some(key=>Object.hasOwn(extra,key)))throw Object.assign(new Error('Reserved Chrome Lab request option.'),{code:'CHROME_REQUEST_OPTIONS'});
+    const fillFrame=this.#fillOwner.getStore();
+    // Preserve the private handler signal even when an instrumentation layer
+    // adds its original expiry signal or supplies a different request signal.
+    if(fillFrame?.signal!==undefined && signal!==fillFrame.signal)signal=AbortSignal.any(signal===undefined?[fillFrame.signal]:[fillFrame.signal,signal]);
     // Optional original transport ownership, checked again after connect's async boundary.
     // This protects a pinned caller from known local replacement before the write.
     const checkBinding=()=>{if(expectedBinding&&(this.closed||this.failure||this.connectionId!==expectedBinding.connectionId||this.info?.browser_endpoint_id!==expectedBinding.browserEndpointId||extra.sessionId!==expectedBinding.sessionId||this.sessions.get(expectedBinding.targetId)!==expectedBinding.sessionId))throw Object.assign(new Error('Original CDP connection/session binding changed before dispatch.'),{code:'CHROME_CDP_BINDING_CHANGED',details:{remote_dispatched:false}});};
     checkBinding();await this.connect(signal); signal?.throwIfAborted();checkBinding();if (this.failure) throw this.failure;
     return new Promise((resolve, reject) => {
-      const id = ++this.sequence;
+      const id = ++this.#requestSequence;this.sequence=id;
+      if(!Number.isSafeInteger(id))throw new Error('Chrome Lab request sequence exhausted.');
+      const requestBudgetMs=this.config.timeoutMs+2000,requestDeadline=performance.now()+requestBudgetMs;
       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, action, method: extra.method, sessionId:extra.sessionId, attachDiagnostic:extra.attachDiagnostic }); signal?.addEventListener('abort', abort, { once: true });
+      const timer = setTimeout(() => finish(new Error('Timeout Chrome Lab; efecto remoto desconocido, no se reintentó.')), requestBudgetMs);
+      const entry = {action, method:extra.method, sessionId:extra.sessionId, attachDiagnostic:extra.attachDiagnostic};
+      // The public pending registry remains useful transport bookkeeping. Its
+      // entries never own provenance's original signal, deadline or binding.
+      const capture={entry,guard:null,state:{settled:false,writeState:'not_sent'}};
+      const finish = (error, value) => { if(capture.state.settled)return;capture.state.settled=true;capture.state.failed=Boolean(error);clearTimeout(timer); signal?.removeEventListener('abort', abort); this.pending.delete(id);this.#pendingReplies.delete(id);
+        // Open/Preview targets and deployed projects stay owned by this connection.
+        if (!error) { if (action === 'open' && typeof value?.targetId === 'string' && value.targetId) this.openedTargets.add(value.targetId); if (action === 'deploy' && typeof value?.project === 'string' && value.project) this.deployedProjects.add(value.project); if (action === 'unload' && typeof params?.project === 'string') this.deployedProjects.delete(params.project); }
+        error ? reject(error) : resolve(value); };
+      this.#pendingReplies.set(id,capture);
+      entry.finish=finish;this.pending.set(id, entry); signal?.addEventListener('abort', abort, { once: true });
       try { onDispatch?.(); } catch(error) { finish(error); return; }
-      this.child.stdin.write(JSON.stringify({ id, action, params, ...extra }) + '\n', error => { if (error) finish(error); });
+      try {
+        signal?.throwIfAborted();if(capture.state.settled)return;checkBinding();
+        const envelope=Object.assign(Object.create(null),extra,{id,action,params});
+        const wire=JSON.stringify(envelope),sent=JSON.parse(wire);
+        if(!sent || Array.isArray(sent) || sent.id!==id || sent.action!==action)throw Object.assign(new Error('Chrome Lab serialized request identity changed.'),{code:'CHROME_REQUEST_OPTIONS'});
+        entry.method=sent.method;entry.sessionId=sent.sessionId;
+        const binding=this.#replyBinding(sent.sessionId);
+        capture.guard=Object.freeze({id,action:sent.action,method:sent.method,sessionId:sent.sessionId,fillOwner:fillFrame?.owner??null,
+          connectionId:this.connectionId,browserEndpointId:this.info?.browser_endpoint_id,connectionGeneration:this.#replyConnectionGeneration,
+          attachTargetId:sent.method==='Target.attachToTarget'&&typeof sent.params?.targetId==='string'?sent.params.targetId:null,
+          detachSessionId:sent.method==='Target.detachFromTarget'?sent.params?.sessionId:null,
+          binding:binding?Object.freeze(binding):null,signal,requestDeadline,requestBudgetMs,
+          paramsSha256:createHash('sha256').update(JSON.stringify(sent.params ?? {})).digest('hex')});
+        this.#recentRequests.set(id,capture);if(this.#recentRequests.size>32)this.#recentRequests.delete(this.#recentRequests.keys().next().value);
+        capture.state.writeState='pending';
+        this.child.stdin.write(wire + '\n', error => {
+          if(error)capture.state.writeState='failed';
+          else if(capture.state.writeState==='pending')capture.state.writeState='acknowledged';
+          if(error)finish(error);
+        });
+      }
+      catch(error){capture.state.writeState='failed';finish(error);}
     });
   }
   cdp(method, params = {}, { signal, sessionId, expectedBinding, attachDiagnostic, onDispatch } = {}) { return this.request('cdp', params, { signal, method, sessionId, expectedBinding, onDispatch, ...(attachDiagnostic !== undefined ? {attachDiagnostic} : {}) }); }
@@ -112,6 +285,27 @@ export class ChromeLabClient {
     if (!this.connectionId || !this.info?.browser_endpoint_id || !session || !collection || !Number.isInteger(context.id) || context.id < 1 || typeof context.uniqueId !== 'string' || !context.uniqueId || context.origin !== target.url) return null;
     return { realm: 'extension_service_worker', target_id: targetId, url: target.url, connection_id: this.connectionId, browser_endpoint_id: this.info.browser_endpoint_id, session_id: session, context_unique_id: context.uniqueId, context_id: context.id, context_epoch: collection.epoch, collection_start: collection.started_at };
   }
+  // A page this connection opened stops being owned once CloseTab closed it (or found it gone).
+  forgetTarget(targetId) { this.openedTargets.delete(targetId); }
+  // Relay mode: the SSH bridge is what holds relayd's lease on the remote host. Once this
+  // connection owns nothing (every own tab closed, every own extension unloaded) and nothing
+  // is in flight, close the transport so relayd can free the host after its idle grace; the
+  // next operation reconnects lazily. Nothing is replayed because nothing is pending. Local
+  // mode keeps the connection as before.
+  async releaseIfIdle() {
+    if (!process.env.RELAY_REMOTE_NAMESPACE) return { released: false, reason: 'not_relay_mode' };
+    const child = this.child;
+    if (this.closed || this.reconnecting || this.failure || !child || child.exitCode !== null || child.signalCode !== null) return { released: false, reason: 'no_live_connection' };
+    if (this.openedTargets.size || this.deployedProjects.size) return { released: false, reason: 'still_owned', open_targets: this.openedTargets.size, deployed_projects: this.deployedProjects.size };
+    if (this.pending.size || this.attaching.size) return { released: false, reason: 'busy' };
+    // Detach first: the exit handler ignores a child that is no longer this.child, so the
+    // release is not recorded as a transport failure.
+    for (const record of this.attachDiagnostics.values()) this.retireDiagnostic(record.session_id, 'connection_released');
+    this.child = undefined; this.connection = undefined; this.failure = undefined; this.info = undefined;
+    this.attachDiagnostics.clear(); this.sessions.clear(); this.contexts.clear(); this.collections.clear(); this.targetInfo.clear(); this.events = [];
+    await new Promise(resolve => { const timer = setTimeout(() => { child.kill('SIGKILL'); resolve(); }, 1500); child.once('exit', () => { clearTimeout(timer); resolve(); }); child.stdin.end(); });
+    return { released: true, reason: 'nothing_owned' };
+  }
   // Explicit recovery only. A new connection does not replay any request or resolve its effect.
   async reconnect(signal) {
     signal?.throwIfAborted();
@@ -143,14 +337,18 @@ export class ChromeLabClient {
     const current=()=>!record.retired && this.attachDiagnostics.get(targetId)===record && !this.closed && !this.failure && this.connectionId===binding.connectionId && this.info?.browser_endpoint_id===binding.browserEndpointId && this.sessions.get(targetId)===sessionId;
     const check=()=>{signal?.throwIfAborted();if(!current())throw Object.assign(new Error('Original attach diagnostic session retired.'),{code:'CHROME_CDP_BINDING_CHANGED'});};
     const started=performance.now(), budget=Math.min(OPTIONAL_PHASE_MS,this.config.timeoutMs);
+    let phaseExhausted=false;
     for(const domain of record.domains) {
       check();const remaining=Math.floor(budget-(performance.now()-started));
-      if(remaining < 1) {domain.completed_at=new Date().toISOString();continue;}
+      if(phaseExhausted || remaining < 1) {domain.completed_at=new Date().toISOString();continue;}
       domain.timeout_ms=remaining;const begin=performance.now();
       try {
         const value=await this.cdp(domain.method,domain.method==='Log.enable'?{}:{maxTotalBufferSize:100000,maxResourceBufferSize:10000},{signal,sessionId,expectedBinding:binding,attachDiagnostic:{timeout_ms:remaining},onDispatch:()=>{check();if(performance.now()-started>=budget)throw Object.assign(new Error('Optional phase expired before dispatch.'),{code:'CHROME_DIAGNOSTIC_BUDGET'});domain.command_count=1;domain.started_at=new Date().toISOString();}});
         check();const result=diagnosticEnvelope(value,{method:domain.method,sessionId,timeout_ms:remaining});
         Object.assign(domain,{state:result.state,reason:result.reason,remote_dispatched:result.remote_dispatched,bridge_elapsed_ms:result.elapsed_ms,elapsed_ms:performance.now()-begin,completed_at:new Date().toISOString(),...(result.error?{error:result.error}: {})});
+        // A wait for the whole remaining phase has timed out. Do not spend a
+        // timer-rounding residue on another command in the other process.
+        if(result.reason==='command_timeout')phaseExhausted=true;
         if(result.state==='enabled')domain.enabled_acknowledged_at=domain.completed_at;
       } catch(error) {
         if(error.code==='CHROME_DIAGNOSTIC_BUDGET' && domain.command_count===0) {Object.assign(domain,{reason:'phase_budget_exhausted',completed_at:new Date().toISOString(),elapsed_ms:performance.now()-begin});continue;}
@@ -193,9 +391,41 @@ export class ChromeLabClient {
     if (serialized.length > 24000) return { ok: true, truncated: true, preview: serialized.subarray(0, 24000).toString('utf8') };
     return { ok: true, value };
   }
+  // Relay mode owns a per-attempt remoteRoot: closing that connection closes only the
+  // targets it opened (Open/Preview) and unloads the extensions the bridge reports as
+  // own (same ownExtensions rule). Foreign targets/extensions are never selected.
+  async relayCleanup() {
+    const namespace = process.env.RELAY_REMOTE_NAMESPACE;
+    if (!namespace) return { mode: 'local', cleaned: false, reason: 'not_relay_mode' };
+    if (this.reconnecting) return { mode: 'relay', namespace, cleaned: false, reason: 'reconnect' };
+    if (this.failure || !this.child || this.child.exitCode !== null || this.child.signalCode !== null) return { mode: 'relay', namespace, cleaned: false, reason: 'no_live_connection' };
+    if (!this.openedTargets.size && !this.deployedProjects.size) return { mode: 'relay', namespace, cleaned: false, reason: 'nothing_owned' };
+    const closed_targets = [], already_closed = [], unloaded = [], errors = [];
+    for (const targetId of [...this.openedTargets]) {
+      try { await this.cdp('Target.closeTarget', { targetId }); closed_targets.push(targetId); }
+      catch (error) { if (/No target|not found/i.test(error.message)) already_closed.push(targetId); else errors.push({ target_id: targetId, error: error.message }); }
+    }
+    let other_extensions_untouched = null;
+    try {
+      const status = await this.request('status', {});
+      other_extensions_untouched = status.other_extensions_count ?? null;
+      for (const extension of status.extensions) {
+        try { const result = await this.request('unload', { project: extension.project }); unloaded.push({ project: extension.project, extension_id: result.extension_id ?? extension.id }); }
+        catch (error) { errors.push({ project: extension.project, error: error.message }); }
+      }
+    } catch (error) { errors.push({ status: error.message }); }
+    return { mode: 'relay', namespace, cleaned: true, closed_targets, already_closed, unloaded, other_extensions_untouched, errors,
+      note: 'Cierre en modo relay: sólo los targets abiertos por esta conexión y las extensiones propias bajo su remoteRoot.' };
+  }
   async close() {
-    if (this.closed) return; this.closed = true; for(const record of this.attachDiagnostics.values())this.retireDiagnostic(record.session_id);
-    if (!this.child || this.child.exitCode !== null || this.child.signalCode !== null) return;
+    if (this.closed) return this.lastCleanup;
+    // Cleanup happens before the transport is marked closed: it is the only chance to
+    // ask the bridge which extensions are still owned under remoteRoot. A cleanup
+    // failure is reported in the result, never silently dropped and never fatal.
+    const cleanup = await this.relayCleanup().catch(error => ({ mode: process.env.RELAY_REMOTE_NAMESPACE ? 'relay' : 'local', cleaned: false, errors: [{ cleanup: error.message }] }));
+    this.lastCleanup = cleanup; this.closed = true;this.#replyConnectionGeneration++;this.#replySessionGenerations.clear();this.#replyAttachments.clear();for(const record of this.attachDiagnostics.values())this.retireDiagnostic(record.session_id);
+    if (!this.child || this.child.exitCode !== null || this.child.signalCode !== null) return cleanup;
     await new Promise(resolve => { const timer = setTimeout(() => { this.child.kill('SIGKILL'); resolve(); }, 1500); this.child.once('exit', () => { clearTimeout(timer); resolve(); }); this.child.stdin.end(); });
+    return cleanup;
   }
 }

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

@@ -4,7 +4,11 @@ import { randomUUID, createHash } from 'node:crypto';
 import { ChromeLabClient } from './client.mjs';
 import { snapshotProject, safeRelative, evidenceDirectory, chromeProjectNameSchema } from './project.mjs';
 import {scopedInteract,inputScopeSchema} from './scoped-input.mjs';
+import {legacyFill} from './legacy-fill.mjs';
 import { observeOwnedWorker, workerDiagnosticSchema } from './worker-diagnostics.mjs';
+import { comalEnvironment } from '../../compat.mjs';
+// Same pixel ceiling the resident enforces for image receipts (src/vision.mjs).
+import { IMAGE_LIMIT } from '../../vision.mjs';
 
 export const CHROME_LAB_TOOLS = Object.freeze(['Status', 'Deploy', 'Deployment', 'Targets', 'Open', 'Preview', 'ReadDOM', 'Assert', 'Contexts', 'InspectValue', 'Evaluate', 'Interact', 'Message', 'Console', 'WorkerDiagnostics', 'Screenshot', 'CloseTab', 'Unload'].map(name => `plugin__chrome-lab__${name}`));
 const object = (properties = {}, required = []) => ({ type: 'object', properties, required, additionalProperties: false });
@@ -68,6 +72,75 @@ function frameDocuments(tree, contexts, identity, usable) {
   const result = { version: FRAME_DOCUMENTS_VERSION, status: 'observed', complete: true, frames };
   return Buffer.byteLength(JSON.stringify(result), 'utf8') <= 4000 ? result : unavailable('projection_byte_limit');
 }
+// Pixel delivery to the model is the same receipt mechanism Read uses (src/vision.mjs):
+// COMAL_VISION=off never sends pixels, and the tool result says so explicitly.
+export function screenshotAttach(env = process.env) {
+  const value = comalEnvironment(env).COMAL_VISION ?? 'auto';
+  if (!['auto', 'on', 'off'].includes(value)) throw new Error('COMAL_VISION debe ser auto, on u off.');
+  return { vision: value, attach: value !== 'off' };
+}
+// Strict ranges; an out-of-range clip is refused before any CDP or SSH call.
+export function screenshotClip(value) {
+  if (value === undefined) return null;
+  if (typeof value === 'string') { if (!value.length || value.length > 1000) throw new Error('clip selector debe tener entre 1 y 1000 caracteres.'); return { selector: value }; }
+  const number = key => typeof value?.[key] === 'number' && Number.isFinite(value[key]);
+  if (!value || typeof value !== 'object' || Array.isArray(value) || ['x', 'y', 'width', 'height'].some(key => !number(key))) throw new Error('clip requiere x, y, width y height numéricos, o un selector CSS.');
+  const { x, y, width, height } = value;
+  if (x < 0 || y < 0 || width <= 0 || height <= 0 || x > 100000 || y > 100000 || width > 100000 || height > 100000) throw new Error('clip exige x,y >= 0, width,height > 0 y ningún valor mayor de 100000 px.');
+  return { x, y, width, height };
+}
+export function screenshotScale(value) {
+  if (value === undefined) return 1;
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0.1 || value > 2) throw new Error('scale debe ser un número entre 0.1 y 2.');
+  return value;
+}
+export const SCREENSHOT_MAX_BYTES = 8000000;
+// PNG IHDR: the capture's real pixel size, used for the documented token estimate.
+export function pngSize(bytes) {
+  return bytes.length >= 24 && bytes.subarray(0, 8).equals(Buffer.from('89504e470d0a1a0a', 'hex')) && bytes.subarray(12, 16).toString('latin1') === 'IHDR'
+    ? { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) } : null;
+}
+// Rough provider-independent estimate (28x28 px tiles), not exact attribution.
+export const imageTokenEstimate = size => size ? Math.ceil(size.width / 28) * Math.ceil(size.height / 28) : null;
+const clipFailure = (code, details) => Object.assign(new Error(JSON.stringify({ code, executed: false, ...details })), { code });
+// Resolve the exact capture rectangle before the single capture. No scrolling, no JS.
+export async function screenshotRect(client, options, clip, scale, targetId) {
+  if (!clip) {
+    if (scale === 1) return null;
+    const metrics = await client.cdp('Page.getLayoutMetrics', {}, options), view = metrics.cssVisualViewport || metrics.cssLayoutViewport;
+    if (!(view?.clientWidth > 0) || !(view?.clientHeight > 0)) throw clipFailure('CHROME_SCREENSHOT_VIEWPORT_UNAVAILABLE', { target_id: targetId, next_action: 'El viewport no se pudo medir. Activa el target y reintenta sin scale; no se capturó nada.' });
+    return { x: 0, y: 0, width: Math.floor(view.clientWidth), height: Math.floor(view.clientHeight) };
+  }
+  if (!clip.selector) return clip;
+  const { root } = await client.cdp('DOM.getDocument', { depth: 0 }, options);
+  const { nodeId } = await client.cdp('DOM.querySelector', { nodeId: root.nodeId, selector: clip.selector }, options);
+  if (!nodeId) throw clipFailure('CHROME_SCREENSHOT_CLIP_MISSING', { target_id: targetId, selector: clip.selector, next_action: 'El selector de clip no existe en el documento actual. Corrige el selector o espera la carga; no se capturó nada.' });
+  let model;
+  try { ({ model } = await client.cdp('DOM.getBoxModel', { nodeId }, options)); }
+  catch (error) {
+    if (error.cdpError?.method !== 'DOM.getBoxModel' || error.cdpError.code !== -32000 || error.cdpError.message !== 'Node does not have a layout object') throw error;
+    throw clipFailure('CHROME_SCREENSHOT_CLIP_HIDDEN', { target_id: targetId, selector: clip.selector, next_action: 'El elemento de clip no tiene layout (oculto o sin caja). Corrige su visibilidad; no se capturó nada.' });
+  }
+  const quad = model?.content;
+  if (!Array.isArray(quad) || quad.length !== 8 || quad.some(value => !Number.isFinite(value))) throw clipFailure('CHROME_SCREENSHOT_CLIP_UNOBSERVED', { target_id: targetId, selector: clip.selector });
+  const xs = [quad[0], quad[2], quad[4], quad[6]], ys = [quad[1], quad[3], quad[5], quad[7]];
+  const rect = { x: Math.min(...xs), y: Math.min(...ys), width: Math.max(...xs) - Math.min(...xs), height: Math.max(...ys) - Math.min(...ys) };
+  if (!(rect.width > 0) || !(rect.height > 0)) throw clipFailure('CHROME_SCREENSHOT_CLIP_EMPTY', { target_id: targetId, selector: clip.selector });
+  return rect;
+}
+// The PNG stays local evidence; only the recorded receipt can carry pixels to the model.
+export function screenshotResult({ file, bytes, sha256, size, rect, scale, target_id, policy, attach }) {
+  const requested = attach ?? policy.attach;
+  const blocked = policy.vision === 'off' ? 'vision_off' : !requested ? 'attach_false' : bytes.length > IMAGE_LIMIT ? 'over_image_limit' : null;
+  return { path: file, evidence_relative: `evidence/chrome-lab/${path.basename(file)}`, bytes: bytes.length, sha256, target_id, observed_at: new Date().toISOString(),
+    width: size?.width ?? null, height: size?.height ?? null, clip: rect, scale, attached: !blocked, ...(blocked ? { attach_blocked: blocked } : {}),
+    image_token_estimate: imageTokenEstimate(size), vision: policy.vision, candidate: 'excluded',
+    evidence_note: 'El PNG vive en evidence/chrome-lab y queda fuera del candidato: sirve para inspección visual, nunca es la evidencia de la tarea.',
+    ...(blocked ? { attach_note: blocked === 'vision_off' ? 'COMAL_VISION=off: la imagen NO se envía al modelo; sólo queda el PNG en evidence/chrome-lab.'
+      : blocked === 'attach_false' ? 'attach:false: no se envía ninguna imagen al modelo en este turno; sólo queda el PNG en evidence/chrome-lab.'
+      : `El PNG (${bytes.length} bytes) excede IMAGE_LIMIT (${IMAGE_LIMIT}): no se adjunta imagen al modelo; sólo queda el archivo en evidence/chrome-lab.` }
+      : { image: { type: 'image', mimeType: 'image/png', data: bytes.toString('base64') }, attach_note: 'Los píxeles se adjuntan al recibo y llegan al modelo en el turno siguiente si anuncia visión (reserva 4096 tokens por imagen; la estimación es aproximada).' }) };
+}
 // Builtin1.4.1 adopts awaited optional attach diagnostics; tests may inject the same client over a fixture transport.
 export function createChromeLabPlugin({ clientFactory = config => new ChromeLabClient(config) } = {}) { return {
   id: 'chrome-lab', version: '1.4.1', requires: ['comal.workspace'],
@@ -76,7 +149,14 @@ export function createChromeLabPlugin({ clientFactory = config => new ChromeLabC
     const cwd = ctx.service('comal.workspace').cwd;
     const client = clientFactory({ cdpURL: 'http://127.0.0.1:9222', timeoutMs: 20000, maxDeployBytes: 10000000, ...config });
     const endpoint = new URL(client.config.cdpURL); if (!['http:', 'https:'].includes(endpoint.protocol) || endpoint.username || endpoint.password || endpoint.search || endpoint.hash) throw new Error('cdpURL debe ser HTTP(S) sin credenciales, query ni fragmento.');
-    ctx.defer(() => client.close());
+    // Desactivar/recargar el plugin y cerrar el runtime pasan por aquí: en modo relay
+    // close() cierra los targets propios y descarga las extensiones propias del remoteRoot.
+    // Una limpieza parcial se avisa; nunca se convierte en éxito silencioso.
+    ctx.defer(async () => {
+      const cleanup = await client.close();
+      if (!cleanup?.errors?.length) return;
+      try { await ctx.notify({ kind: 'chrome_lab_cleanup', title: 'Chrome Lab cleanup was incomplete', body: `Relay cleanup left owned resources behind: ${JSON.stringify(cleanup.errors).slice(0, 1200)}`, ref: `chrome-lab-cleanup-${Date.now()}` }); } catch { /* el aviso es best-effort durante el retiro */ }
+    });
     const operation = (name, description, input_schema, effects, run, output_schema) => ctx.operation({ name, description, input_schema, effects, run, ...(output_schema ? { output_schema } : {}) });
     // attach validates the current URL even for cached sessions; do not repeat that round trip.
     const session = async (id, signal) => ({ signal, sessionId: await client.attach(id, signal) });
@@ -155,7 +235,8 @@ export function createChromeLabPlugin({ clientFactory = config => new ChromeLabC
     operation('Interact', 'Native click/fill/key/reload/navigation. Optional scope:{context_unique_id,shadow_path:[]} for click/fill selects exactly one element in that current default document through exposed shadow hosts. Same-origin child contexts must be explicitly selected from Contexts; unsupported/foreign/stale scopes refuse. Scoped clicks check native frame/hit; fills check exact deep focus before keyboard/text. No JS fallback. Missing/ambiguous/blocked elements return dispatched:false; any failure after input begins is uncertain and must not be replayed. Checks and physical dispatch are separate requests, not atomic. Legacy no-scope input keeps its existing top-document behavior.', object({ ...target, action: { enum: ['click', 'fill', 'key', 'reload', 'navigate'] }, scope:inputScopeSchema, selector: string(1000), text: { type: 'string', maxLength: 10000 }, key: { enum: ['Enter', 'Tab', 'Escape', 'Backspace', 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight'] }, url: string(3000) }, ['target_id', 'action']), write, async (input, { signal }) => {
       if(input.scope!==undefined)return scopedInteract(client,input,{signal});
       const options = await session(input.target_id, signal);
-      if(['click','fill','key'].includes(input.action))await client.cdp('Page.bringToFront',{},options);
+      if(input.action==='fill')return typeof client.fillLegacy==='function'?client.fillLegacy(input,options):legacyFill(client,input,options);
+      if(['click','key'].includes(input.action))await client.cdp('Page.bringToFront',{},options);
       if (input.action === 'reload') await client.cdp('Page.reload', { ignoreCache: true }, options);
       else if (input.action === 'navigate') { if (!input.url) throw new Error('navigate requiere url.'); const result = await client.request('navigate', { targetId: input.target_id, url: browserURL(input.url) }, options); if (result.errorText) throw new Error(result.errorText); }
       else if (input.action === 'key') { if (!input.key) throw new Error('key requiere key.'); for (const type of ['keyDown', 'keyUp']) await client.cdp('Input.dispatchKeyEvent', { type, key: input.key, ...(input.key === 'Enter' ? { text: '\r', windowsVirtualKeyCode: 13 } : {}) }, options); }
@@ -164,16 +245,7 @@ export function createChromeLabPlugin({ clientFactory = config => new ChromeLabC
         const { root } = await client.cdp('DOM.getDocument', { depth: 0 }, options);
         const { nodeId } = await client.cdp('DOM.querySelector', { nodeId: root.nodeId, selector: input.selector }, options);
         if (!nodeId) return {dispatched:false,blocked:true,code:'CHROME_INPUT_BLOCKED',action:input.action,target_id:input.target_id,selector:input.selector,observation:{phase:'selector_resolution',selector_found:false},next_action:'The selector has no element in the current document. Correct source or inspect readiness. No keyboard or pointer event was dispatched.'};
-        if (input.action === 'fill') {
-          if (input.text === undefined) throw new Error('fill requiere text.');
-          try { await client.cdp('DOM.focus', { nodeId }, options); }
-          catch (error) {
-            if (error.cdpError?.method !== 'DOM.focus' || error.cdpError.code !== -32000 || error.cdpError.message !== 'Element is not focusable' || signal?.aborted) throw error;
-            return { dispatched:false,blocked:true,code:'CHROME_INPUT_BLOCKED',action:input.action,target_id:input.target_id,selector:input.selector,observation:{phase:'before_keyboard_input',focus:'rejected',cdp_error:error.cdpError},next_action:'Correct the source visibility, disabled state, or field type. DOM.focus returned a native not-focusable error; no keyboard or text input was dispatched. Inspect the DOM instead of retrying unchanged input.' };
-          }
-          for (const type of ['keyDown', 'keyUp']) await client.cdp('Input.dispatchKeyEvent', { type, key: 'a', code: 'KeyA', modifiers: 2, windowsVirtualKeyCode: 65 }, options);
-          await client.cdp('Input.insertText', { text: input.text }, options);
-        } else {
+        {
           let layoutMethod='DOM.scrollIntoViewIfNeeded',model;
           try {
             await client.cdp(layoutMethod, { nodeId }, options);
@@ -205,24 +277,34 @@ export function createChromeLabPlugin({ clientFactory = config => new ChromeLabC
       return { events, collection: 'since_attach', bounded: true, truncated: events.length < candidates.length, ...(target_id?{attach_diagnostics:client.diagnostics(target_id)}:{}) };
     });
     operation('WorkerDiagnostics', 'Observe bounded console/exception text for the exact current owned publication and native service-worker generation. Reads physical deployment before/after, selects its declared worker, may attach a debugger. Missing/ambiguous/changed state is unavailable, never healthy. No arbitrary JavaScript, application message, restart, wake-up request, reconnect or test verdict. Application-logged text is untrusted and may contain application data.', workerDiagnosticSchema, read, (input,options)=>observeOwnedWorker(client,input,options));
-    operation('Screenshot', 'Activates the exact validated target, captures its viewport and saves a PNG in workspace evidence/chrome-lab. Hidden tabs may not produce a Chrome frame. Returns path and SHA256, not image bytes. No capture retry; use vision to judge appearance.', object(target, ['target_id']), { ...read, workspace: 'write' }, async ({ target_id }, { signal }) => {
-      const options = await session(target_id, signal);
+    operation('Screenshot', 'Activa el target validado, captura su viewport y guarda un PNG en evidence/chrome-lab. Los píxeles llegan al modelo en el turno siguiente como imagen del recibo (mismo mecanismo que Read), nunca como texto; con COMAL_VISION=off o attach:false sólo se guarda el archivo y el resultado lo dice. clip (selector CSS o rectángulo) y scale (0.1-2) recortan y bajan resolución para gastar menos tokens. Devuelve path y sha256; el PNG de evidence/chrome-lab nunca es la evidencia de la tarea. No hay reintento de captura.', object({ ...target, attach: { type: 'boolean' }, clip: { anyOf: [string(1000), { type: 'object', additionalProperties: false, properties: { x: { type: 'number' }, y: { type: 'number' }, width: { type: 'number' }, height: { type: 'number' } }, required: ['x', 'y', 'width', 'height'] }] }, scale: { type: 'number', minimum: 0.1, maximum: 2 } }, ['target_id']), { ...read, workspace: 'write' }, async (input, { signal }) => {
+      const clip = screenshotClip(input.clip), scale = screenshotScale(input.scale), policy = screenshotAttach(process.env);
+      const options = await session(input.target_id, signal);
       await client.cdp('Page.bringToFront', {}, options);
-      const screenshot = await client.cdp('Page.captureScreenshot', { format: 'png', captureBeyondViewport: false }, options);
-      const bytes = Buffer.from(screenshot.data, 'base64'); if (bytes.length > 8000000) throw new Error('Screenshot excede 8MB.');
+      const rect = await screenshotRect(client, options, clip, scale, input.target_id);
+      const screenshot = await client.cdp('Page.captureScreenshot', { format: 'png', captureBeyondViewport: false, ...(rect ? { clip: { ...rect, scale } } : {}) }, options);
+      const bytes = Buffer.from(screenshot.data, 'base64'); if (bytes.length > SCREENSHOT_MAX_BYTES) throw new Error('Screenshot excede 8MB.');
       const dir = await evidenceDirectory(cwd);
       const file = path.join(dir, `${Date.now()}-${randomUUID()}.png`); await writeFile(file, bytes, { flag: 'wx' });
-      return { path: file, bytes: bytes.length, sha256: createHash('sha256').update(bytes).digest('hex'), target_id, observed_at: new Date().toISOString() };
+      return screenshotResult({ file, bytes, sha256: createHash('sha256').update(bytes).digest('hex'), size: pngSize(bytes), rect, scale, target_id: input.target_id, policy, attach: input.attach });
     });
-    operation('CloseTab', 'Cierra un target de página indicado explícitamente. No cierra Chrome ni cambia perfiles. Tiene efectos: no lo uses para pestañas ajenas al encargo. Si Deploy ya cerró el popup, devuelve already_closed.', object(target, ['target_id']), write, async ({ target_id }, { signal }) => {
+    // En modo relay, al no quedar nada propio en el host (pestañas cerradas, extensiones
+    // descargadas) se suelta la conexión: relayd libera el host tras su gracia y la próxima
+    // herramienta reconecta.
+    const release = async () => { try { return (await client.releaseIfIdle()).released ? { connection_released: true, release_note: 'No queda nada propio en el host: Chrome Lab cerró su conexión y el host queda libre para otros. La próxima herramienta de Chrome Lab reconecta.' } : {}; } catch { return {}; } };
+    operation('CloseTab', 'Cierra un target de página indicado explícitamente. No cierra Chrome ni cambia perfiles. Tiene efectos: no lo uses para pestañas ajenas al encargo. Si Deploy ya cerró el popup, devuelve already_closed. Si ya no queda nada propio abierto, suelta la conexión (connection_released).', object(target, ['target_id']), write, async ({ target_id }, { signal }) => {
       const exists = async () => (await client.cdp('Target.getTargets', {}, { signal })).targetInfos.find(item => item.targetId === target_id);
-      const item = await exists(); if (!item) return { closed: true, already_closed: true, target_id };
-      if (item.type !== 'page') throw new Error('CloseTab sólo cierra páginas, no workers/browser.');
-      await client.request('checkTarget', { targetId: target_id }, { signal });
-      try { return await client.cdp('Target.closeTarget', { targetId: target_id }, { signal }); }
-      catch (error) { if (!await exists()) return { closed: true, already_closed: true, target_id }; throw error; }
+      const closeTab = async () => {
+        const item = await exists(); if (!item) return { closed: true, already_closed: true, target_id };
+        if (item.type !== 'page') throw new Error('CloseTab sólo cierra páginas, no workers/browser.');
+        await client.request('checkTarget', { targetId: target_id }, { signal });
+        try { return await client.cdp('Target.closeTarget', { targetId: target_id }, { signal }); }
+        catch (error) { if (!await exists()) return { closed: true, already_closed: true, target_id }; throw error; }
+      };
+      const result = await closeTab(); client.forgetTarget(target_id);
+      return { ...result, ...await release() };
     });
-    operation('Unload', 'Desinstala sólo la extensión desempaquetada correspondiente a project bajo la raíz propia Comal. Puede borrar su storage. Conserva archivos remotos. Nunca toma un id de una extensión ajena.', object(project, ['project']), write, (input, { signal }) => client.request('unload', input, { signal }));
+    operation('Unload', 'Desinstala sólo la extensión desempaquetada correspondiente a project bajo la raíz propia Comal. Puede borrar su storage. Conserva archivos remotos. Nunca toma un id de una extensión ajena. Si ya no queda nada propio abierto, suelta la conexión (connection_released).', object(project, ['project']), write, async (input, { signal }) => ({ ...await client.request('unload', input, { signal }), ...await release() }));
     const bindRecovery=ctx.service('comal.workspace').bindChromePageRecoveryClient;
     if(bindRecovery)ctx.defer(bindRecovery(client));
   },

package/src/plugins/chrome-lab/legacy-fill.mjs

@@ -0,0 +1,25 @@
+// Fixed legacy fill flow. Only this branch creates an origin record for its own
+// returned object; origin records alone never authorize or certify anything.
+const origins=new WeakMap();
+export function takeLegacyFillOrigin(result){const origin=origins.get(result);origins.delete(result);return origin??null;}
+export async function legacyFill(client,input,options){
+  const {action,target_id,selector,text,scope}=input;
+  if(action!=='fill'||scope!==undefined)throw new Error('Legacy fill requires an unscoped fill action.');
+  const originalOptions=Object.freeze({signal:options.signal,sessionId:options.sessionId});
+  const activation=await client.cdp('Page.bringToFront',{},originalOptions);
+  if(!selector)throw new Error('click/fill requiere selector.');
+  const {root}=await client.cdp('DOM.getDocument',{depth:0},originalOptions);
+  const {nodeId}=await client.cdp('DOM.querySelector',{nodeId:root.nodeId,selector},originalOptions);
+  if(!nodeId)return{dispatched:false,blocked:true,code:'CHROME_INPUT_BLOCKED',action,target_id,selector,observation:{phase:'selector_resolution',selector_found:false},next_action:'The selector has no element in the current document. Correct source or inspect readiness. No keyboard or pointer event was dispatched.'};
+  if(text===undefined)throw new Error('fill requiere text.');
+  try{await client.cdp('DOM.focus',{nodeId},originalOptions);}
+  catch(error){
+    if(error.cdpError?.method!=='DOM.focus'||error.cdpError.code!==-32000||error.cdpError.message!=='Element is not focusable'||originalOptions.signal?.aborted)throw error;
+    const result={dispatched:false,blocked:true,code:'CHROME_INPUT_BLOCKED',action,target_id,selector,observation:{phase:'before_keyboard_input',focus:'rejected',cdp_error:{...error.cdpError}},next_action:'Correct the source visibility, disabled state, or field type. DOM.focus returned a native not-focusable error; no keyboard or text input was dispatched. Inspect the DOM instead of retrying unchanged input.'};
+    origins.set(result,Object.freeze({client,activation,error,input:Object.freeze({action,target_id,selector}),options:originalOptions}));
+    return result;
+  }
+  for(const type of ['keyDown','keyUp'])await client.cdp('Input.dispatchKeyEvent',{type,key:'a',code:'KeyA',modifiers:2,windowsVirtualKeyCode:65},originalOptions);
+  await client.cdp('Input.insertText',{text},originalOptions);
+  return{dispatched:true,action,target_id,note:'Despacho observado; usa Assert/ReadDOM para comprobar resultado.'};
+}

package/src/plugins/chrome-lab/native-reply.mjs

@@ -0,0 +1,31 @@
+import {createHash} from 'node:crypto';
+
+// Parsed wire DATA only. Eligibility is held privately by the receiving client;
+// calling this parser never grants an operation, retry or application acceptance.
+export function parseNativeReply(value, expected) {
+  const keys = (v, names) => v && typeof v === 'object' && !Array.isArray(v) &&
+    Object.keys(v).sort().join() === names.slice().sort().join();
+  if (!keys(value, ['format','outer_request_id','cdp_request_id','method','session_id','params_sha256','browser_endpoint_id','remote_dispatched','reply_json']) ||
+      value.format !== 'comal-cdp-native-reply/1' || value.remote_dispatched !== true ||
+      !Number.isSafeInteger(value.cdp_request_id) || value.cdp_request_id < 1 ||
+      !['Page.bringToFront','DOM.focus'].includes(value.method) ||
+      value.outer_request_id !== expected.id || value.method !== expected.method ||
+      value.session_id !== expected.sessionId || value.params_sha256 !== expected.paramsSha256 ||
+      value.browser_endpoint_id !== expected.browserEndpointId ||
+      typeof value.reply_json !== 'string' || Buffer.byteLength(value.reply_json) > 8192) return null;
+  let raw;
+  try { raw = JSON.parse(value.reply_json); } catch { return null; }
+  const field = expected.error ? 'error' : 'result';
+  if (!keys(raw, ['id','sessionId',field]) || raw.id !== value.cdp_request_id || raw.sessionId !== expected.sessionId) return null;
+  if (expected.error) {
+    const error = raw.error;
+    if (!(keys(error,['code','message']) || keys(error,['code','message','data'])) ||
+        !Number.isSafeInteger(error.code) || typeof error.message !== 'string' ||
+        expected.cdpError?.method !== value.method || expected.cdpError.code !== error.code ||
+        expected.cdpError.message !== error.message || expected.error.message !== `${error.code}: ${error.message}`) return null;
+  } else if (JSON.stringify(raw.result) !== JSON.stringify(expected.result)) return null;
+  return Object.freeze({ ...value, reply_sha256:createHash('sha256').update(value.reply_json).digest('hex'),
+    outcome:expected.error ? 'native_error_reply' : 'native_success_reply',
+    authority:false, behavior_acceptance:false, retry_authorized:false,
+    remote_nonexecution_proved:false, phase_lifetime_bound:false });
+}