@milpa/comal 0.2.1 → 0.2.3

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

@@ -22,14 +22,14 @@ export async function remoteBridge(config, lines) {
     if (!valid) throw new Error('Invalid private attach diagnostic arguments.');
     return option;
   };
-  const cdp = (method, params = {}, sessionId, diagnostic) => new Promise((resolve, reject) => {
+  const cdp = (method, params = {}, sessionId, diagnostic, replyOwner) => new Promise((resolve, reject) => {
     const id = ++sequence, started = performance.now();
     const outcome = (state,reason,error) => ({diagnostic:{version:1,method,session_id:sessionId,state,reason,remote_dispatched:true,timeout_ms:diagnostic.timeout_ms,elapsed_ms:performance.now()-started,...(error?{error}: {})}});
     const timer = setTimeout(() => {
       pending.delete(id);
       diagnostic ? resolve(outcome('unknown','command_timeout')) : reject(new Error(`CDP timeout: ${method}; no se reintentó.`));
     }, diagnostic?.timeout_ms ?? config.timeoutMs);
-    pending.set(id, { resolve, reject, timer, method, params, diagnostic, outcome });
+    pending.set(id, { resolve, reject, timer, method, params, sessionId, diagnostic, outcome, replyOwner });
     try { socket.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) })); }
     catch(error) { pending.delete(id); clearTimeout(timer); reject(error); }
   });
@@ -60,6 +60,19 @@ export async function remoteBridge(config, lines) {
   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);
+    const matched = pending.get(message.id);
+    // Only the actual matched browser response can populate this lexical owner.
+    // Caller-shaped Errors, optional diagnostics and internal bridge commands
+    // never supply native reply provenance. Keep the untruncated raw response.
+    if (matched?.replyOwner && ['Page.bringToFront','DOM.focus'].includes(matched.method) &&
+        typeof event.data === 'string' && Buffer.byteLength(event.data) <= 8192) {
+      matched.replyOwner.nativeReply = {format:'comal-cdp-native-reply/1',
+        outer_request_id:matched.replyOwner.outerId, cdp_request_id:message.id,
+        method:matched.method, session_id:matched.sessionId,
+        params_sha256:digest(JSON.stringify(matched.params)),
+        browser_endpoint_id:/^\/devtools\/browser\/([^/]+)$/.exec(endpoint.pathname)?.[1] || null,
+        remote_dispatched:true, reply_json: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.params.flatten === true) flattened.add(message.result.sessionId); } if (entry.method === 'Target.detachFromTarget') { attached.delete(entry.params.sessionId); flattened.delete(entry.params.sessionId); } } if(entry.diagnostic) { if(message.error && (!Number.isInteger(message.error.code) || typeof message.error.message !== 'string')) entry.reject(new Error('Malformed diagnostic CDP error.')); else entry.resolve(message.error ? entry.outcome('rejected','command_error',{code:message.error.code,message:message.error.message.slice(0,1000)}) : entry.outcome('enabled','command_reply')); } else message.error ? entry.reject(Object.assign(new Error(`${message.error.code}: ${message.error.message}`), { cdpError: { method: entry.method, code: message.error.code, message: String(message.error.message).slice(0, 1000) } })) : 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)) {
       if(message.method === 'Target.detachedFromTarget') { attached.delete(message.params?.sessionId); flattened.delete(message.params?.sessionId); }
@@ -204,12 +217,12 @@ export async function remoteBridge(config, lines) {
     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;
+    let request, replyOwner;
     try {
       if (line.length > config.maxDeployBytes * 1.5 + 1000000) throw new Error('Mensaje demasiado grande.');
       request = JSON.parse(line); let result;
       const diagnostic = Object.hasOwn(request,'attachDiagnostic') ? diagnosticPolicy(request) : undefined;
-      if (request.action === 'cdp') result = await cdp(request.method, request.params, request.sessionId, diagnostic);
+      if (request.action === 'cdp') { replyOwner={outerId:request.id};result = await cdp(request.method, request.params, request.sessionId, diagnostic, replyOwner); }
       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) });
@@ -223,10 +236,10 @@ export async function remoteBridge(config, lines) {
       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 });
+      const output = JSON.stringify({ id: request.id, result, ...(replyOwner?.nativeReply ? {native_reply:replyOwner.nativeReply} : {}) });
       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, ...(error.cdpError ? { cdp_error: error.cdpError } : {}) }); }
+    } catch (error) { send({ id: request?.id, error: error.message, ...(error.cdpError ? { cdp_error: error.cdpError } : {}), ...(replyOwner?.nativeReply ? {native_reply:replyOwner.nativeReply} : {}) }); }
   });
   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

@@ -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;
   }
 }