@milpa/comal 0.1.7 → 0.2.0

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

@@ -7,11 +7,31 @@ export async function remoteBridge(config, lines) {
   if (!path.isAbsolute(config.remoteRoot) || root === path.parse(root).root) throw new Error('remoteRoot debe ser un directorio de laboratorio absoluto.');
   const send = value => process.stdout.write(JSON.stringify(value) + '\n');
   const digest = data => createHash('sha256').update(data).digest('hex');
-  let socket, sequence = 0, closing = false; const pending = new Map(), servers = new Map(), attached = new Set();
-  const cdp = (method, params = {}, sessionId) => new Promise((resolve, reject) => {
-    const id = ++sequence, timer = setTimeout(() => { pending.delete(id); reject(new Error(`CDP timeout: ${method}; no se reintentó.`)); }, config.timeoutMs);
-    pending.set(id, { resolve, reject, timer, method, params });
-    socket.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
+  let socket, sequence = 0, closing = false; const pending = new Map(), servers = new Map(), attached = new Set(), flattened = new Set();
+  // Only this private, validated optional path gets the smaller response-wait timer.
+  const diagnosticPolicy = request => {
+    const option = request.attachDiagnostic;
+    if (!option || typeof option !== 'object' || Array.isArray(option) || Object.keys(option).join() !== 'timeout_ms' ||
+        request.action !== 'cdp' || !['Log.enable','Network.enable'].includes(request.method) ||
+        typeof request.sessionId !== 'string' || !request.sessionId || !flattened.has(request.sessionId) ||
+        !Number.isInteger(option.timeout_ms) || option.timeout_ms < 1 || option.timeout_ms > Math.min(config.timeoutMs,2000)) throw new Error('Invalid private attach diagnostic policy.');
+    const params = request.params;
+    const valid = params && typeof params === 'object' && !Array.isArray(params) && (request.method === 'Log.enable'
+      ? Object.keys(params).length === 0
+      : Object.keys(params).sort().join() === 'maxResourceBufferSize,maxTotalBufferSize' && params.maxTotalBufferSize === 100000 && params.maxResourceBufferSize === 10000);
+    if (!valid) throw new Error('Invalid private attach diagnostic arguments.');
+    return option;
+  };
+  const cdp = (method, params = {}, sessionId, diagnostic) => 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 });
+    try { socket.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) })); }
+    catch(error) { pending.delete(id); clearTimeout(timer); reject(error); }
   });
   const shutdown = async (detach = true) => {
     if (closing) return; closing = true;
@@ -40,8 +60,10 @@ 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);
-    if (message.id) { const entry = pending.get(message.id); if (!entry) return; pending.delete(message.id); clearTimeout(entry.timer); if (!message.error) { if (entry.method === 'Target.attachToTarget' && message.result?.sessionId) attached.add(message.result.sessionId); if (entry.method === 'Target.detachFromTarget') attached.delete(entry.params.sessionId); } message.error ? entry.reject(new Error(`${message.error.code}: ${message.error.message}`)) : entry.resolve(message.result); }
+    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); }
+      if(message.method === 'Inspector.detached') { attached.delete(message.sessionId); flattened.delete(message.sessionId); }
       // Never ship arbitrary object previews or network bodies into the resident's context.
       if (message.method === 'Runtime.consoleAPICalled') message.params.args = (message.params.args || []).slice(0, 12).map(arg => ({ type: arg.type, text: String(arg.value ?? arg.description ?? arg.type).slice(0, 2000) }));
       if (JSON.stringify(message).length < 64000) send({ event: message });
@@ -88,7 +110,7 @@ export async function remoteBridge(config, lines) {
     await checkURL(targetInfo.url); return targetInfo;
   };
   const extensionFor = async name => { const dir = await owned(name); const expected = path.join(dir, 'current').toLowerCase(); const extension = (await extensions()).find(item => path.resolve(item.path).toLowerCase() === expected); if (!extension) throw new Error('Extensión del proyecto no cargada. Usa Deploy.'); return extension; };
-  const deploy = async ({ project, files, attempt_id = randomUUID() }) => {
+  const deploy = async ({ project, files, attempt_id = randomUUID(), create_only=false }) => {
     if (!/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(attempt_id)) throw new Error('Identidad de publicación inválida.');
     slug(project); if (!Array.isArray(files) || !files.length || files.length > 1000) throw new Error('Límite de archivos de despliegue.');
     let bytes = 0; const names = new Set();
@@ -98,7 +120,7 @@ export async function remoteBridge(config, lines) {
     if (manifest?.manifest_version !== 3 || !manifest.name || !manifest.version) throw new Error('Se requiere manifest.json MV3 válido.');
     await fs.mkdir(root, { recursive: true }); await realDirectory(root);
     const dir = projectDir(project);
-    try { await fs.mkdir(dir); await fs.writeFile(path.join(dir, '.comal-lab.json'), JSON.stringify({ owner: 'comal-chrome-lab-v1', project }), { flag: 'wx' }); } catch (error) { if (error.code !== 'EEXIST') throw error; }
+    try { await fs.mkdir(dir); await fs.writeFile(path.join(dir, '.comal-lab.json'), JSON.stringify({ owner: 'comal-chrome-lab-v1', project }), { flag: 'wx' }); } catch (error) { if (error.code !== 'EEXIST') throw error; if(create_only)throw new Error(JSON.stringify({code:'CHROME_PROJECT_EXISTS',executed:false,project,reason:'Atomic creation requires a new project directory; no source changed and no Chrome load dispatched.'})); }
     await owned(project);
     const lock = path.join(dir, '.deploy-lock'); await fs.mkdir(lock); // Fail closed if another Comal is deploying.
     const stage = path.join(dir, `stage-${randomUUID()}`), current = path.join(dir, 'current'), backup = path.join(dir, `backup-${randomUUID()}`);
@@ -138,7 +160,7 @@ export async function remoteBridge(config, lines) {
     const artifact = JSON.parse(raw);
     if (artifact.project !== project || artifact.remote_path?.toLowerCase() !== current.toLowerCase() || !Array.isArray(artifact.files) || !artifact.files.length || artifact.files.length > 1000) throw new Error('Recibo de otro proyecto o snapshot inválido.');
     await realDirectory(current);
-    const observedFiles = []; let bytes = 0;
+    const observedFiles = []; let bytes = 0, manifestBytes;
     const visit = async (directory, prefix = '') => {
       await realDirectory(directory);
       for (const entry of (await fs.readdir(directory, { withFileTypes: true })).sort((a,b)=>a.name.localeCompare(b.name))) {
@@ -149,13 +171,16 @@ export async function remoteBridge(config, lines) {
         const data = await fs.readFile(absolute), after = await fs.lstat(absolute);
         if (before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ino !== after.ino || data.length !== before.size) throw new Error('Snapshot remoto cambió durante la lectura.');
         observedFiles.push({ path: relative, sha256: digest(data) });
+        if (relative === 'manifest.json') manifestBytes = data;
       }
     };
     await visit(current);
     const extension = (await extensions()).find(item=>item.id===artifact.extension_id && path.resolve(item.path).toLowerCase()===current.toLowerCase());
     if (await locked() || await readReceipt() !== raw) return { status: 'busy', project };
     if (!extension?.enabled || JSON.stringify(observedFiles) !== JSON.stringify(artifact.files)) return { status: 'conflict', project, attempt_id: artifact.attempt_id || null, reason: 'Loaded extension or physical snapshot no longer matches the receipt.' };
-    return { ...artifact, status: 'observed', files: artifact.files.slice(0,30), file_count: artifact.files.length, files_truncated: artifact.files.length>30, file_manifest_sha256: digest(JSON.stringify(artifact.files)), file_manifest_remote_path: receipt, checked_at: new Date().toISOString() };
+    const workerScript = manifestBytes && JSON.parse(manifestBytes).background?.service_worker;
+    if (workerScript !== undefined) safeFile(workerScript);
+    return { ...artifact, status: 'observed', worker_script: typeof workerScript === 'string' ? workerScript : null, files: artifact.files.slice(0,30), file_count: artifact.files.length, files_truncated: artifact.files.length>30, file_manifest_sha256: digest(JSON.stringify(artifact.files)), file_manifest_remote_path: receipt, checked_at: new Date().toISOString() };
   };
   const preview = async ({ project, file = 'fixture.html' }) => {
     const dir = path.join(await owned(project), 'current'); safeFile(file);
@@ -183,7 +208,8 @@ export async function remoteBridge(config, lines) {
     try {
       if (line.length > config.maxDeployBytes * 1.5 + 1000000) throw new Error('Mensaje demasiado grande.');
       request = JSON.parse(line); let result;
-      if (request.action === 'cdp') result = await cdp(request.method, request.params, request.sessionId);
+      const diagnostic = Object.hasOwn(request,'attachDiagnostic') ? diagnosticPolicy(request) : undefined;
+      if (request.action === 'cdp') result = await cdp(request.method, request.params, request.sessionId, diagnostic);
       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) });
@@ -200,7 +226,7 @@ export async function remoteBridge(config, lines) {
       const output = JSON.stringify({ id: request.id, result });
       if (output.length > 12000000) throw new Error('Respuesta excesiva; usa consultas acotadas.');
       process.stdout.write(output + '\n');
-    } catch (error) { send({ id: request?.id, error: error.message }); }
+    } catch (error) { send({ id: request?.id, error: error.message, ...(error.cdpError ? { cdp_error: error.cdpError } : {}) }); }
   });
   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

@@ -2,10 +2,11 @@ import { spawn } from 'node:child_process';
 import { createInterface } from 'node:readline';
 import { randomUUID } from 'node:crypto';
 import { remoteBridge } from './bridge.mjs';
+import { OPTIONAL_PHASE_MS, PUBLIC_DIAGNOSTIC_BYTES, diagnosticEnvelope } from './diagnostics.mjs';
 
 export class ChromeLabClient {
   constructor(config, { spawnProcess = spawn } = {}) {
-    this.config = config; this.spawnProcess = spawnProcess; this.pending = new Map(); this.sessions = new Map(); this.attaching = new Map(); this.targetInfo = new Map(); this.contexts = new Map(); this.events = []; this.sequence = 0; this.closed = false;
+    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();
   }
   async connect(signal) {
     signal?.throwIfAborted(); if (this.closed) throw new Error('Plugin Chrome Lab cerrado.');
@@ -25,10 +26,10 @@ export class ChromeLabClient {
       const bootstrap = "const r=require('readline').createInterface({input:process.stdin});r.once('line',l=>{const p=JSON.parse(l);eval(p.source)(p.config,r).catch(e=>{console.log(JSON.stringify({fatal:e.message}));process.exit(1)})})";
       const child = this.child = this.spawnProcess('ssh', ['-T', '-o', 'BatchMode=yes', '-o', 'ClearAllForwardings=yes', '-o', 'ConnectTimeout=10', '-o', 'ServerAliveInterval=10', '-o', 'ServerAliveCountMax=2', this.config.sshHost, `node -e "${bootstrap}"`], { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
       const timer = setTimeout(() => { fail(new Error('Timeout iniciando Chrome Lab por SSH.')); child.kill(); }, this.config.timeoutMs);
-      const fail = error => { clearTimeout(timer); if (this.child !== child) return; this.failure = error; if (!ready) reject(error); for (const entry of this.pending.values()) entry.finish(error); this.pending.clear(); };
+      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(); };
       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}`)));
+      child.on('exit', (code, sig) => fail(new Error(`Chrome Lab desconectado (${code ?? sig}); no se reintentaron efectos pendientes. ${stderr}`),'connection_lost'));
       const lines = createInterface({ input: child.stdout });
       lines.on('line', line => {
         if (this.child !== child) return;
@@ -38,7 +39,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) entry.finish(message.error ? new Error(message.error) : null, message.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}); entry.finish(error,result); } }
         } catch (error) { fail(error); child.kill(); }
       });
       child.stdin.write(JSON.stringify({ source: `(${remoteBridge.toString()})`, config: this.config }) + '\n');
@@ -46,35 +47,71 @@ export class ChromeLabClient {
   }
   observe(event) {
     const { method, params = {}, sessionId } = event;
-    if (method === 'Target.detachedFromTarget') { for (const [target, session] of this.sessions) if (session === params.sessionId) this.sessions.delete(target); this.contexts.delete(params.sessionId); }
-    if (method === 'Inspector.detached') { for (const [target, session] of this.sessions) if (session === sessionId) this.sessions.delete(target); this.contexts.delete(sessionId); }
-    if (method === 'Runtime.executionContextCreated') { const contexts = this.contexts.get(sessionId) || new Map(); contexts.set(params.context.id, params.context); this.contexts.set(sessionId, contexts); return; }
-    if (method === 'Runtime.executionContextDestroyed') { this.contexts.get(sessionId)?.delete(params.executionContextId); return; }
-    if (method === 'Runtime.executionContextsCleared') { this.contexts.delete(sessionId); return; }
+    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') {
+      const contexts = this.contexts.get(sessionId) || new Map(), collection = this.collection(sessionId), context = params.context;
+      collection.epoch++;
+      const seen = collection.seen.get(context.id);
+      if (collection.seen.has(context.id) && seen !== context.uniqueId) collection.reused.add(context.id);
+      if (collection.seen.size < 512) collection.seen.set(context.id, context.uniqueId); else collection.ambiguous = true;
+      contexts.set(context.id, context); this.contexts.set(sessionId, contexts); return;
+    }
+    if (method === 'Runtime.executionContextDestroyed') {
+      const contexts = this.contexts.get(sessionId);
+      // A delayed destruction for an old unique context must not remove a reused numeric ID.
+      if (typeof params.executionContextUniqueId === 'string') { for (const [id, context] of contexts || []) if (context.uniqueId === params.executionContextUniqueId) contexts.delete(id); }
+      else contexts?.delete(params.executionContextId);
+      this.collection(sessionId).epoch++; return;
+    }
+    if (method === 'Runtime.executionContextsCleared') { this.contexts.delete(sessionId); this.collection(sessionId).epoch++; return; }
     const target_id = [...this.sessions].find(([, session]) => session === sessionId)?.[0];
     const raw = JSON.stringify(params);
-    this.events.push({ method, target_id, observed_at: new Date().toISOString(), details: raw.length > 4000 ? { truncated: true, preview: raw.slice(0, 4000) } : params });
+    const contextId = method === 'Runtime.consoleAPICalled' ? params.executionContextId : method === 'Runtime.exceptionThrown' ? params.exceptionDetails?.executionContextId : undefined;
+    const collection = this.collections.get(sessionId), context = this.contexts.get(sessionId)?.get(contextId);
+    const unique = context && !collection?.ambiguous && !collection?.reused.has(contextId) ? context.uniqueId : null;
+    this.events.push({ method, target_id, observed_at: new Date().toISOString(), binding: { connection_id: this.connectionId || null, browser_endpoint_id: this.info?.browser_endpoint_id || null, session_id: sessionId || null, context_unique_id: unique || null, context_epoch: collection?.epoch ?? null }, details: raw.length > 4000 ? { truncated: true, preview: raw.slice(0, 4000) } : params });
     if (this.events.length > 200) this.events.shift();
   }
-  async request(action, params, { signal, ...extra } = {}) {
-    await this.connect(signal); signal?.throwIfAborted(); if (this.failure) throw this.failure;
+  async request(action, params, { signal, expectedBinding, onDispatch, ...extra } = {}) {
+    // 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 abort = () => finish(new Error('Operación abortada tras despacho; el efecto remoto puede haber ocurrido. Verifica antes de repetir.'));
       const timer = setTimeout(() => finish(new Error('Timeout Chrome Lab; efecto remoto desconocido, no se reintentó.')), this.config.timeoutMs + 2000);
       const finish = (error, value) => { clearTimeout(timer); signal?.removeEventListener('abort', abort); this.pending.delete(id); error ? reject(error) : resolve(value); };
-      this.pending.set(id, { finish }); signal?.addEventListener('abort', abort, { once: true });
+      this.pending.set(id, { finish, action, method: extra.method, sessionId:extra.sessionId, attachDiagnostic:extra.attachDiagnostic }); 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); });
     });
   }
-  cdp(method, params = {}, { signal, sessionId } = {}) { return this.request('cdp', params, { signal, method, sessionId }); }
-  resourceIdentity(targetId) {
+  cdp(method, params = {}, { signal, sessionId, expectedBinding, attachDiagnostic, onDispatch } = {}) { return this.request('cdp', params, { signal, method, sessionId, expectedBinding, onDispatch, ...(attachDiagnostic !== undefined ? {attachDiagnostic} : {}) }); }
+  resourceIdentity(targetId, { frameId, sessionId, connectionId } = {}) {
+    // A sole default context may belong to a child frame. Bind only to the
+    // root frame observed in the same attached session and connection.
+    const owned = typeof frameId === 'string' && frameId.length > 0 &&
+      typeof sessionId === 'string' && sessionId.length > 0 && sessionId === this.sessions.get(targetId) &&
+      typeof connectionId === 'string' && connectionId.length > 0 && connectionId === this.connectionId && !this.failure && !this.closed;
     const contexts = [...(this.contexts.get(this.sessions.get(targetId))?.values() || [])];
-    const defaults = contexts.filter(item => item.auxData?.isDefault === true && typeof item.uniqueId === 'string' && item.uniqueId);
+    const defaults = owned ? contexts.filter(item => item.auxData?.isDefault === true && item.auxData.frameId === frameId && typeof item.uniqueId === 'string' && item.uniqueId) : [];
     return { connection_id: this.connectionId || null, browser_endpoint_id: this.info?.browser_endpoint_id || null,
       context_unique_id: defaults.length === 1 ? defaults[0].uniqueId : null,
       frame_id: defaults.length === 1 ? defaults[0].auxData.frameId || null : null };
   }
+  collection(sessionId) {
+    if (!this.collections.has(sessionId)) this.collections.set(sessionId, { started_at: new Date().toISOString(), epoch: 0, seen: new Map(), reused: new Set(), ambiguous: false });
+    return this.collections.get(sessionId);
+  }
+  workerIdentity(targetId) {
+    const target = this.targetInfo.get(targetId), session = this.sessions.get(targetId), contexts = [...(this.contexts.get(session)?.values() || [])];
+    if (this.failure || this.closed || target?.type !== 'service_worker' || typeof target.url !== 'string' || !target.url.startsWith('chrome-extension://') || contexts.length !== 1) return null;
+    const context = contexts[0], collection = this.collections.get(session);
+    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 };
+  }
   // Explicit recovery only. A new connection does not replay any request or resolve its effect.
   async reconnect(signal) {
     signal?.throwIfAborted();
@@ -82,10 +119,49 @@ export class ChromeLabClient {
     this.reconnecting = true;
     try {
       await this.close(); this.child = undefined; this.connection = undefined; this.failure = undefined; this.info = undefined; this.closed = false;
-      this.sessions.clear(); this.contexts.clear(); this.attaching.clear(); this.targetInfo.clear(); this.events = [];
+      this.attachDiagnostics.clear(); this.sessions.clear(); this.contexts.clear(); this.collections.clear(); this.attaching.clear(); this.targetInfo.clear(); this.events = [];
       return await this.connect(signal);
     } finally { this.reconnecting = false; }
   }
+  retireDiagnostic(sessionId, reason = 'session_retired') {
+    for(const record of this.attachDiagnostics.values()) if(record.session_id === sessionId && !record.retired) {
+      record.retired = true;
+      for(const domain of record.domains) if(!domain.completed_at) Object.assign(domain,{state:domain.command_count?'unknown':'not_attempted',reason,completed_at:new Date().toISOString()});
+    }
+  }
+  diagnostics(targetId) {
+    const record=this.attachDiagnostics.get(targetId);
+    if(!record || record.retired || this.closed || this.failure || record.connection_id !== this.connectionId || record.browser_endpoint_id !== this.info?.browser_endpoint_id || this.sessions.get(targetId) !== record.session_id)return null;
+    const value=structuredClone(record);
+    return Buffer.byteLength(JSON.stringify(value))<=PUBLIC_DIAGNOSTIC_BYTES ? value : {version:1,state:'unavailable',reason:'details_omitted_due_to_limit',history_complete:false};
+  }
+  async optionalDiagnostics(targetId, sessionId, signal) {
+    const binding={targetId,sessionId,connectionId:this.connectionId,browserEndpointId:this.info?.browser_endpoint_id};
+    const record={version:1,policy:'awaited-optional-2000ms/1',connection_id:binding.connectionId,browser_endpoint_id:binding.browserEndpointId,target_id:targetId,session_id:sessionId,generation:randomUUID(),history_complete:false,runtime_collection:'since_attach',domains:['Log.enable','Network.enable'].map(method=>({method,state:'not_attempted',reason:'phase_budget_exhausted',command_count:0,timeout_ms:0,started_at:null,completed_at:null,elapsed_ms:0}))};
+    // One live record per target. A replacement generation cannot be updated by this closure.
+    this.attachDiagnostics.set(targetId,record);
+    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);
+    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;}
+      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}: {})});
+        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;}
+        // Only a validated command envelope is optional. Abort, retirement, protocol
+        // and transport failure propagate, including after an enable was dispatched.
+        if(this.attachDiagnostics.get(targetId)===record && !domain.completed_at) Object.assign(domain,{state:domain.command_count?'unknown':'not_attempted',reason:signal?.aborted?'operation_aborted':record.retired||error.code==='CHROME_CDP_BINDING_CHANGED'?'session_retired':'transport_uncertain',elapsed_ms:performance.now()-begin,completed_at:new Date().toISOString()});
+        throw error;
+      }
+    }
+    check();record.elapsed_ms=performance.now()-started;
+  }
   async attach(targetId, signal) {
     this.targetInfo.set(targetId, await this.request('checkTarget', { targetId }, { signal }));
     if (this.attaching.has(targetId)) return this.attaching.get(targetId);
@@ -93,22 +169,24 @@ export class ChromeLabClient {
     const attaching = (async () => {
       const { sessionId } = await this.cdp('Target.attachToTarget', { targetId, flatten: true }, { signal });
       this.sessions.set(targetId, sessionId);
+      this.collection(sessionId);
       try {
         await this.cdp('Runtime.enable', {}, { signal, sessionId });
-        await this.cdp('Log.enable', {}, { signal, sessionId }).catch(() => {});
-        await this.cdp('Network.enable', { maxTotalBufferSize: 100000, maxResourceBufferSize: 10000 }, { signal, sessionId }).catch(() => {});
+        await this.optionalDiagnostics(targetId,sessionId,signal);
         return sessionId;
-      } catch (error) { this.sessions.delete(targetId); this.contexts.delete(sessionId); await this.cdp('Target.detachFromTarget', { sessionId }).catch(() => {}); throw error; }
+      } catch (error) { this.retireDiagnostic(sessionId); if(this.sessions.get(targetId)===sessionId)this.sessions.delete(targetId); this.contexts.delete(sessionId); await this.cdp('Target.detachFromTarget', { sessionId }).catch(() => {}); throw error; }
     })();
     this.attaching.set(targetId, attaching);
-    try { return await attaching; } finally { this.attaching.delete(targetId); }
+    try { return await attaching; } finally { if(this.attaching.get(targetId)===attaching)this.attaching.delete(targetId); }
   }
-  async evaluate(targetId, expression, { signal, context_id, await_promise = false } = {}) {
+  async evaluate(targetId, expression, { signal, context_id, unique_context_id, read_only = false, await_promise = false, extension_only = false } = {}) {
+    if (read_only && (!unique_context_id || await_promise || context_id !== undefined)) throw Object.assign(new Error('Read-only inspection requires an exact unique context and synchronous evaluation.'), { code: 'CHROME_INSPECTION_CONTEXT' });
     const sessionId = await this.attach(targetId, signal);
-    const result = await this.cdp('Runtime.evaluate', { expression, returnByValue: true, awaitPromise: await_promise, timeout: Math.min(10000, this.config.timeoutMs), allowUnsafeEvalBlockedByCSP: false, ...(context_id !== undefined ? { contextId: context_id } : {}) }, { signal, sessionId });
+    if (extension_only && (this.targetInfo.get(targetId)?.type !== 'page' || !this.targetInfo.get(targetId)?.url.startsWith('chrome-extension://'))) throw Object.assign(new Error('Typed runtime messages require an owned extension page.'),{code:'CHROME_MESSAGE_TARGET'});
+    const result = await this.cdp('Runtime.evaluate', { expression, returnByValue: true, awaitPromise: await_promise, timeout: Math.min(10000, this.config.timeoutMs), allowUnsafeEvalBlockedByCSP: false, ...(context_id !== undefined ? { contextId: context_id } : {}), ...(unique_context_id ? { uniqueContextId: unique_context_id } : {}), ...(read_only ? { throwOnSideEffect: true, disableBreaks: true } : {}) }, { signal, sessionId });
     if (result.exceptionDetails) {
       const info = this.targetInfo.get(targetId);
-      return { ok: false, error: (result.exceptionDetails.exception?.description || result.exceptionDetails.text).slice(0, 4000), ...(info ? { target: { target_id: targetId, type: info.type, url: info.url } } : {}), ...(/^https?:/.test(info?.url || '') && context_id === undefined ? { next_action: 'This is the HTTP page main world. chrome.storage/tabs extension APIs belong to the OWN extension target, or a suitable isolated context from Contexts. Use the exact target by project URL; await Promise APIs with await_promise:true.' } : {}) };
+      return { ok: false, error: (result.exceptionDetails.exception?.description || result.exceptionDetails.text).slice(0, 4000), ...(info ? { target: { target_id: targetId, type: info.type, url: info.url } } : {}), ...(read_only ? { next_action: 'Read-only inspection failed. Use a synchronous expression whose side effects V8 can rule out in the exact accepted document. Do not fall back to effectful evaluation or await a Promise.' } : /^https?:/.test(info?.url || '') && context_id === undefined ? { next_action: 'This is the HTTP page main world. chrome.storage/tabs extension APIs belong to the OWN extension target, or a suitable isolated context from Contexts. Use the exact target by project URL; await Promise APIs with await_promise:true.' } : {}) };
     }
     const value = result.result.value ?? result.result.unserializableValue ?? null;
     const serialized = Buffer.from(JSON.stringify(value));
@@ -116,7 +194,7 @@ export class ChromeLabClient {
     return { ok: true, value };
   }
   async close() {
-    if (this.closed) return; this.closed = true;
+    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;
     await new Promise(resolve => { const timer = setTimeout(() => { this.child.kill('SIGKILL'); resolve(); }, 1500); this.child.once('exit', () => { clearTimeout(timer); resolve(); }); this.child.stdin.end(); });
   }

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

@@ -0,0 +1,19 @@
+// Builtin private attach protocol adopted from reviewed candidate03. No resident-controlled input or global health verdict.
+export const OPTIONAL_PHASE_MS = 2000;
+// UTF8 serialized JSON bytes. Oversize identity metadata becomes unavailable;
+// identities are never truncated into a different, apparently exact binding.
+export const PUBLIC_DIAGNOSTIC_BYTES = 16000;
+export function diagnosticEnvelope(value, { method, sessionId, timeout_ms }) {
+  const fail = () => { throw Object.assign(new Error('Invalid attach diagnostic response envelope.'), { code: 'CHROME_DIAGNOSTIC_PROTOCOL' }); };
+  if (!value || Object.keys(value).length !== 1 || !value.diagnostic) return fail();
+  const d = value.diagnostic;
+  if (Object.keys(d).some(k => !['version','method','session_id','state','reason','remote_dispatched','timeout_ms','elapsed_ms','error'].includes(k)) ||
+      d.version !== 1 || d.method !== method || d.session_id !== sessionId || d.timeout_ms !== timeout_ms || d.remote_dispatched !== true ||
+      !Number.isFinite(d.elapsed_ms) || d.elapsed_ms < 0 ||
+      !['enabled','rejected','unknown'].includes(d.state) ||
+      !({enabled:'command_reply',rejected:'command_error',unknown:'command_timeout'}[d.state] === d.reason)) return fail();
+  if (d.state === 'rejected') {
+    if (!d.error || Object.keys(d.error).sort().join() !== 'code,message' || !Number.isInteger(d.error.code) || typeof d.error.message !== 'string' || d.error.message.length > 1000) return fail();
+  } else if (d.error !== undefined) return fail();
+  return structuredClone(d);
+}