coding-artifact-evaluation-shell 0.0.0-stage → 0.1.0-eidolon.a1b37cbcd7c07

package/support/browser-channel.ts

@@ -0,0 +1,209 @@
+/** A single owner for an acceptance Page. No application-specific test logic. */
+export interface Dialog { type: string; message: string; defaultPrompt?: string; url?: string }
+export interface BrowserRequest { id: string; op: string; args: unknown[] }
+export interface BrowserResponse {
+  id: string; sequence: number; status: 'ok' | 'dialog-open' | 'error';
+  result?: { value?: unknown; snapshot?: string; observationId?: string; url?: string; dialog?: Dialog | null };
+  error?: string;
+  failure?: {kind: 'invalid-request' | 'precondition-rejected' | 'predicate-unmet' | 'execution-uncertain' | 'control-lost' | 'provider-error'; recoverable: boolean; mayHaveLateEffects: boolean};
+}
+export interface BrowserPort {
+  invoke(method: string, args: unknown[]): Promise<unknown>;
+  events(): Promise<unknown[]>;
+  control(): Promise<boolean>;
+  url(): Promise<string>;
+}
+export interface ChannelRuntime {
+  page: BrowserPort; origin: string; timeoutMs: number;
+  /** AI-selected actions require native snapshot refs; caller-declared probes remain compatible. */
+  groundedTargets?:boolean;
+  pause(ms: number): Promise<void>;
+  armDeadline(ms: number, callback: () => void): () => void;
+}
+export interface ChannelState {
+  sequence: number; dialog: Dialog | null; stopped: string | null;
+  queue: Promise<void>; requests: Map<string, { digest: string; response: Promise<BrowserResponse> }>;
+  snapshotRefs:Set<string>;
+}
+export const channelState = (): ChannelState => ({ sequence: 0, dialog: null, stopped: null, queue: Promise.resolve(), requests: new Map(),snapshotRefs:new Set() });
+const arities: Record<string, [number, number]> = {
+  goto: [1,1], snapshot: [0,1], click: [1,2], fill: [2,2], selectOption: [2,2], press: [2,2],
+  acceptDialog: [0,1], dismissDialog: [0,0], info: [0,0], waitForSelector: [1,2],
+};
+const selectorOperations = new Set(['click','fill','selectOption','press','waitForSelector']);
+export const BROWSER_SELECTOR_GUIDANCE = 'Snapshot annotations are display text, not selector syntax. A current [ref=N] annotation must be addressed as "@N" or "ref=N", never "[ref=N]"; do not copy enclosing brackets or a combined ref/loc annotation. Alternatively use a current loc=css:, loc=role:, loc=href:, text=, xpath= or raw CSS selector. Quote CSS attribute values. Derive targets from the current snapshot; stale references require a new snapshot. Invalid requests dispatch no input: inspect the error, explicitly correct the selector and submit a NEW request ID, never automatically replay a mutation.';
+export const GROUNDED_BROWSER_GUIDANCE='For this AI collector, click/fill/selectOption/press accept ONLY @N or ref=N from the latest native snapshot; guessed CSS/text targets are refused BEFORE dispatch. Start with snapshot. Navigation waits for DOMContentLoaded, not all passive resources or business readiness. Successful mutations return a fresh snapshot with the receipt in the same native response (unless a dialog blocks it); read that complete object before choosing next targets. A stale-ref refusal requires a new snapshot/new request ID. waitForSelector may use a goal-derived read-only predicate; unknown action timeouts still fence, never replay.';
+const targetMutations=new Set(['click','fill','selectOption','press']);
+function retainSnapshot(state:ChannelState,snapshot:string):void {
+  state.snapshotRefs=new Set([...snapshot.matchAll(/\[ref=(\d+)(?:\s*,[^\]]*)?\]/g)].map(m=>m[1]!));
+}
+function validateSelector(selector:string):void {
+  // Display annotations are not SDK selectors. Refuse before any provider IO,
+  // rather than guessing a target or trusting a generic SyntaxError afterward.
+  if (/^(?:(?:loc=)?css[:=])?\[\s*ref\s*=\s*\d+(?:\s*,\s*loc=[\s\S]*)?\s*\]$/.test(selector)) {
+    throw new TypeError('Invalid selector: snapshot display notation is not a selector. Use the current @N or ref=N without brackets, or a valid loc= selector. No browser input was dispatched; correct with a NEW request ID.');
+  }
+}
+function validSelection(value: unknown): boolean {
+  if (typeof value === 'string') return true;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const option = value as Record<string, unknown>;
+  const keys = Object.keys(option);
+  return keys.length > 0 && keys.every(key =>
+    key === 'index' ? Number.isSafeInteger(option[key]) && Number(option[key]) >= 0
+      : ['value', 'label'].includes(key) && typeof option[key] === 'string');
+}
+const quotedOption = String.raw`"(?:\\.|[^"\\\n])*"`;
+const availableOption = String.raw`\d+: value=${quotedOption}, label=${quotedOption}`;
+const missingSingleOption = new RegExp(String.raw`^ElementResolutionError: page\.selectOption timed out after \d+ms: page\.selectOption failed: option ${quotedOption} was not found; available options: ${availableOption}(?:; ${availableOption})*$`);
+/** Known native resolution refusal, not a timeout or a generic exception class.
+ * Match the complete provider diagnostic and the requested selector. An explicit
+ * late-effect report/after-dispatch stage still takes precedence in classification.
+ */
+function ambiguousClick(diagnostic: string, args?: readonly unknown[]): boolean {
+  const match = /^ElementResolutionError: Locator (.+) matched ([1-9]\d*) elements \((\d+) visible, (\d+) hidden\)\. Candidates: (.+)\. Use a current snapshot ref or a more specific role, text, or CSS selector\.$/.exec(diagnostic);
+  if (!match || match[1] !== args?.[0]) return false;
+  const count = Number(match[2]);
+  return count >= 2 && Number(match[3]) + Number(match[4]) === count && match[5]!.startsWith('1. ');
+}
+export function validateRequest(value: unknown, origin: string): BrowserRequest {
+  const v = value as BrowserRequest;
+  if (!v || typeof v.id !== 'string' || !/^[\w-]{1,100}$/.test(v.id) || !Object.hasOwn(arities,v.op) || !Array.isArray(v.args)) throw Error('Invalid browser command');
+  const [min,max] = arities[v.op]!;
+  if(v.args.length < min || v.args.length > max) throw Error('Invalid browser arguments');
+  if (['goto','click','fill','selectOption','press','waitForSelector'].includes(v.op) && typeof v.args[0] !== 'string') throw Error('Selector/URL must be a string');
+  if (selectorOperations.has(v.op)) validateSelector(v.args[0] as string);
+  if (['fill','press'].includes(v.op) && typeof v.args[1] !== 'string') throw Error('Text must be a string');
+  if (v.op === 'selectOption') {
+    const selection = v.args[1];
+    if (selection !== null && !(Array.isArray(selection) ? selection.every(validSelection) : validSelection(selection))) throw new TypeError('Selection must be a value/label string, option descriptor, array or null');
+  }
+  if(v.op === 'acceptDialog' && v.args.length && typeof v.args[0] !== 'string') throw Error('Prompt text must be a string');
+  let optionsIndex: number | null = null;
+  if (v.op === 'snapshot') optionsIndex = 0;
+  if (v.op === 'click' || v.op === 'waitForSelector') optionsIndex = 1;
+  if (optionsIndex !== null && v.args.length > optionsIndex) {
+    const options = v.args[optionsIndex];
+    if (options === null || typeof options !== 'object' || Array.isArray(options)) throw new TypeError(`${v.op} options must be an object`);
+  }
+  if(v.op === 'goto' && new URL(v.args[0] as string).origin !== origin) throw Error('Navigation outside leased origin');
+  if(v.op === 'snapshot') v.args = [{ scope: 'full_page', ...(v.args[0] as object ?? {}) }];
+  if(v.op === 'waitForSelector') {
+    const options = {...(v.args[1] as {timeout?:number} ?? {})};
+    if(options.timeout !== undefined && (!Number.isFinite(options.timeout) || options.timeout < 50 || options.timeout > 8000)) throw new TypeError('waitForSelector timeout must be 50..8000ms');
+    v.args[1] = {...options,timeout:options.timeout ?? 8000};
+  }
+  return v;
+}
+function applyEvents(state: ChannelState, events: unknown[]) {
+  for(const e of events as {method?:string;params?:Dialog}[]) {
+    if(e.method === 'Page.javascriptDialogClosed') state.dialog = null;
+    if(e.method === 'Page.javascriptDialogOpening' && e.params) state.dialog = e.params;
+  }
+}
+export function classifyBrowserFailure(error: unknown, op: string, stage = 'invoke', args?: readonly unknown[]): NonNullable<BrowserResponse['failure']> {
+  const failure = error as {name?: string; timedOut?: boolean; mayHaveLateEffects?: boolean; dispatchPhase?: string; kind?: string} | null;
+  const result = (kind: NonNullable<BrowserResponse['failure']>['kind'], recoverable: boolean, mayHaveLateEffects = false) => ({kind,recoverable,mayHaveLateEffects});
+  if (stage === 'control') return result('control-lost',false);
+  if (failure?.mayHaveLateEffects === true) return result('execution-uncertain',false,true);
+  if (stage === 'validation') return result('invalid-request',true);
+  if (stage === 'after-dispatch') return result('execution-uncertain',false,true);
+  if (failure?.dispatchPhase === 'pre-dispatch') return result('precondition-rejected',true);
+  if (op === 'waitForSelector' && failure?.kind === 'predicate-unmet') return result('predicate-unmet',true);
+  const diagnostic = String(error);
+  // Only the provider's exact read-only predicate diagnostic is recoverable.
+  if (op === 'waitForSelector' && /^Error: page\.waitForSelector timed out after \d+ms(?:$|:)/.test(diagnostic)) return result('predicate-unmet',true);
+  if (failure?.timedOut === true || /timeout/i.test(failure?.name ?? '')) return result('execution-uncertain',false,true);
+  // Exception class alone is not a dispatch fact. Only the known, complete SDK
+  // options rejection is safe; its usage word `timeout?` is not a deadline.
+  if (op === 'click' && diagnostic === 'TypeError: page.click options must be an object. Expected: await page.click(selector, { timeout?, label? })') return result('invalid-request',true);
+  // Real neutral-page conformance proves ambiguity is rejected before input.
+  // Unknown diagnostics (even ElementResolutionError) remain fail-closed.
+  if (op === 'click' && ambiguousClick(diagnostic,args)) return result('precondition-rejected',true);
+  // Ego's click timeout also bounds waiting for an element to become usable.
+  // This exact disabled-element rejection precedes native input dispatch.
+  if (/^ElementResolutionError: page\.click timed out after \d+ms: (?:page\.click failed:|Selector .+ matched \d+ elements, but none can receive input;) element is disabled$/.test(diagnostic)) return result('precondition-rejected',true);
+  // An exact native hit-test refusal precedes input dispatch. Do not generalize
+  // this to provider deadlines, appended diagnostics or late-effect reports.
+  const intercepted = /^ElementResolutionError: page\.(click|fill) timed out after \d+ms: (?:page\.\1 failed:|Selector [^\n]+ matched \d+ elements, but none can receive input;) <[^>\n]+> intercepts pointer events$/.exec(diagnostic);
+  if (intercepted?.[1] === op) return result('precondition-rejected',true);
+  // Calibrated only for one string selection. Array/descriptor failures may
+  // involve partial effects and are not generalized from this native refusal.
+  if (op === 'selectOption' && typeof args?.[1] === 'string' && missingSingleOption.test(diagnostic)) return result('precondition-rejected',true);
+  if (/^ElementResolutionError: Stale ref: @\d+; take a new snapshot$/.test(diagnostic)) return result('precondition-rejected',true);
+  // Confirmed by live calibration: a non-editable target is rejected before
+  // input dispatch. Keep this diagnostic exact; unrelated fill failures fence.
+  if (op === 'fill' && /^Error: page\.fill failed: element is not an input, textarea, or contenteditable element$/.test(diagnostic)) return result('precondition-rejected',true);
+  if (/\btimeout\b|\btimed out\b/i.test(diagnostic)) return result('execution-uncertain',false,true);
+  // Unknown mutation errors cannot establish that input was never dispatched.
+  if (['click','fill','selectOption','press','acceptDialog','dismissDialog','goto'].includes(op)) return result('execution-uncertain',false,true);
+  return result('provider-error',true);
+}
+async function perform(runtime: ChannelRuntime, state: ChannelState, request: BrowserRequest): Promise<BrowserResponse> {
+  const response: BrowserResponse = { id: request.id, sequence: ++state.sequence, status: 'ok' };
+  if(state.stopped) return {...response,status:'error',error:state.stopped,failure:{kind:'execution-uncertain',recoverable:false,mayHaveLateEffects:true}};
+  let stage = 'invoke';
+  try {
+    if(!await runtime.page.control()) { stage='control';state.stopped='User or inactive browser control'; throw Error(state.stopped); }
+    applyEvents(state,await runtime.page.events());
+    const dialogAction = ['acceptDialog','dismissDialog'].includes(request.op);
+    if(state.dialog && !dialogAction) return {...response,status:'dialog-open',result:{dialog:state.dialog}};
+    stage = 'validation';
+    if(runtime.groundedTargets&&targetMutations.has(request.op)){
+      const match=/^(?:@|ref=)(\d+)$/.exec(request.args[0] as string);
+      if(!match||!state.snapshotRefs.has(match[1]!))throw Error('Unobserved browser target; use a ref from the latest native snapshot. No browser input was dispatched; request a snapshot and use a NEW request ID.');
+    }
+    if(dialogAction && state.dialog?.type === 'prompt' && request.op === 'acceptDialog' && request.args.length === 0) throw Error('Prompt requires explicit text; default is not automatically preserved');
+    if(dialogAction && !state.dialog) throw Error('No observed dialog to answer');
+    stage = 'invoke';
+    const value = await runtime.page.invoke(request.op, request.args);
+    stage = 'after-dispatch';
+    if(dialogAction) state.dialog=null;
+    const receipt = value as {dialog?:Dialog} | null;
+    if(receipt?.dialog) state.dialog=receipt.dialog;
+    applyEvents(state,await runtime.page.events());
+    // The same live SDK listener captures follow-on prompt events before replying.
+    // No default answers or generated-application operations are supplied here.
+    if(dialogAction) {
+      for(let i=0;i<4 && !state.dialog;i++) { await runtime.pause(50); applyEvents(state,await runtime.page.events()); }
+    }
+    response.result = request.op === 'snapshot' ? {snapshot:String(value),observationId:request.id,dialog:state.dialog} : {value,dialog:state.dialog};
+    if(runtime.groundedTargets){
+      if(request.op==='snapshot')retainSnapshot(state,String(value));
+      else if(targetMutations.has(request.op)||['goto','acceptDialog','dismissDialog'].includes(request.op)){
+        state.snapshotRefs.clear();
+        if(!state.dialog){
+          const snapshot=String(await runtime.page.invoke('snapshot',[{scope:'full_page'}]));
+          response.result.snapshot=snapshot;retainSnapshot(state,snapshot);
+        }
+      }
+    }
+    if(!state.dialog) {
+      response.result.url=await runtime.page.url();
+      if(new URL(response.result.url).origin !== runtime.origin) {state.stopped='Page left leased origin';throw Error(state.stopped);}
+    }
+    if(state.dialog?.url && new URL(state.dialog.url).origin !== runtime.origin) { state.stopped='Dialog outside leased origin'; throw Error(state.stopped); }
+    return response;
+  } catch(error) {
+    const diagnostic=String(error);
+    const failure = classifyBrowserFailure(error,request.op,stage,request.args);
+    if(!failure.recoverable) state.stopped ??= `Native browser failure; outcome uncertain, session fenced: ${diagnostic}`;
+    return {...response,status:'error',error:state.stopped??diagnostic,failure};
+  }
+}
+/** Requests serialize even when agents yield shell commands and call concurrently. */
+export function dispatchBrowser(runtime: ChannelRuntime, state: ChannelState, raw: unknown): Promise<BrowserResponse> {
+  let request: BrowserRequest;
+  try { request=validateRequest(raw,runtime.origin); } catch(error) { return Promise.resolve({id:'invalid',sequence:state.sequence,status:'error',error:String(error),failure:classifyBrowserFailure(error,'unknown','validation')}); }
+  const digest=JSON.stringify(request); const previous=state.requests.get(request.id);
+  if(previous) return previous.digest===digest ? previous.response : Promise.resolve({id:request.id,sequence:state.sequence,status:'error',error:'Request ID reused with different command'});
+  const response=state.queue.then(async()=> {
+    let cancelDeadline:()=>void;
+    const timeout=new Promise<BrowserResponse>(resolve=> {cancelDeadline=runtime.armDeadline(runtime.timeoutMs,()=> {
+      state.stopped='Native browser timeout; outcome uncertain, session fenced, no action replay';
+      resolve({id:request.id,sequence:state.sequence,status:'error',error:state.stopped,failure:{kind:'execution-uncertain',recoverable:false,mayHaveLateEffects:true}});
+    });});
+    const result=await Promise.race([perform(runtime,state,request),timeout]); cancelDeadline!(); return result;
+  });
+  state.requests.set(request.id,{digest,response}); state.queue=response.then(()=>{}); return response;
+}

package/support/browser-client.ts

@@ -0,0 +1,33 @@
+/** One transport command, not an application test. Args are authored by the AI. */
+import { readFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import {readContent} from './evidence-object';
+export {readContent} from './evidence-object';
+
+/** Same authenticated transport for CLI and serial scratch scripts. No policy/retry. */
+export async function observe(configPath:string,request:Record<string,unknown>):Promise<any>{
+  if(!request||typeof request!=='object'||Array.isArray(request))throw Error('Native request must be an object');
+  const config=JSON.parse(readFileSync(configPath,'utf8'));
+  const timeout=config.deadlineAt?Math.max(1,Math.min(190000,config.deadlineAt-Date.now())):35000;
+  const response=await fetch(config.endpoint+'/command',{method:'POST',headers:{authorization:`Bearer ${config.token}`,'content-type':'application/json'},body:JSON.stringify({...request,id:request.id??randomUUID()}),signal:AbortSignal.timeout(timeout)});
+  const value=await response.json() as Record<string,any>;
+  if(!value||!['ok','error'].includes(value.status))throw Error('Native transport returned an invalid response');
+  if(!response.ok&&value.status!=='error')throw Error(`Native transport refused: HTTP ${response.status}`);
+  // Small action results are useful immediately. Keep complete file/large
+  // objects at their absolute entries; never truncate, summarize or dispatch
+  // another request to obtain the same fact. Both entrances use this projection.
+  const observation=value.observation;
+  if(observation&&observation.channel!=='file'&&Number.isSafeInteger(observation.bytes)&&observation.bytes>=0&&observation.bytes<=16384){
+    return {...value,observation:{...observation,content:readContent(observation)}};
+  }
+  return value;
+}
+
+if(import.meta.main){
+  const [configPath,raw]=process.argv.slice(2);
+  if(!configPath||!raw)throw Error('Usage: bun browser-client.ts <connection.json> <JSON request>');
+  // Source quotations are data: @file avoids shell interpolation of quotes/backticks.
+  const request=JSON.parse(raw.startsWith('@')?readFileSync(raw.slice(1),'utf8'):raw);
+  const value=await observe(configPath,request);console.log(JSON.stringify(value,null,2));
+  process.exitCode=value.status==='error'?1:0;
+}

package/support/browser-owner.ts

@@ -0,0 +1,69 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import type { AgentRun } from './agent-runtime';
+import { resolveEgo } from './ego-tools';
+
+export async function closeBrowserWorker(endpoint:string,adminToken:string):Promise<void>{
+  const response=await fetch(endpoint+'/close',{method:'POST',headers:{authorization:`Bearer ${adminToken}`},signal:AbortSignal.timeout(2000)});
+  if(!response.ok)throw Error(`Native browser cleanup failed: HTTP ${response.status}; ${await response.text()}`);
+}
+
+/** Harness Effect lifecycle. It owns the log; agents cannot write native evidence. */
+export async function startBrowserChannel(run: AgentRun, origin: string, space: number, name: string, boundary: { sandbox(argv: string[]): string[]; deadlineAt?:number;groundedTargets?:boolean }) {
+  if (!Number.isSafeInteger(space) || space<=0 || !/^[a-zA-Z0-9-]+$/.test(name)) throw Error('Invalid browser ownership input');
+  const writeJson=(file:string,value:unknown)=>fs.writeFileSync(file,JSON.stringify(value)+'\n');
+  const worker=path.join(run.root,'bin/browser-worker.mjs');
+  const build=await Bun.build({entrypoints:[path.join(import.meta.dir,'browser-worker.ts')],target:'node',format:'esm'});
+  if(!build.success) throw Error(`Browser worker build failed: ${build.logs}`);
+  fs.writeFileSync(worker,await build.outputs[0]!.text());
+  const client=path.join(run.root,'bin/browser-client.ts');fs.copyFileSync(path.join(import.meta.dir,'browser-client.ts'),client);
+  const log=path.join(run.root,`logs/${name}-browser-channel.jsonl`),token=randomUUID(),adminToken=randomUUID();
+  fs.closeSync(fs.openSync(log,'wx',0o600));
+  const stderr=path.join(run.root,`logs/${name}-browser-process.log`),fd=fs.openSync(stderr,'wx',0o600);
+  const privateConfig=path.join(run.root,'bin',`browser-private-${name}.json`);
+  writeJson(privateConfig,{space,origin,token,adminToken,log,groundedTargets:boundary.groundedTargets??false});fs.chmodSync(privateConfig,0o600);
+  // Owner capabilities never appear in process argv, which is visible to tools.
+  const script=`const fs=await import("node:fs"); const config=JSON.parse(fs.readFileSync(${JSON.stringify(privateConfig)},"utf8")); const {startBrowserWorker}=await import(${JSON.stringify(worker)}); await startBrowserWorker(taskSpace,config);`;
+  const argv=boundary.sandbox([resolveEgo().executable,'nodejs','-e',script]);
+  // Only the harness worker may append this one native log. Reviewer sandbox
+  // keeps its deny-write rule; the model cannot forge channel evidence.
+  argv[2] += `(allow file-write* (literal ${JSON.stringify(log)}))`;
+  const child=spawn(argv[0]!,argv.slice(1),{cwd:run.workspace,env:run.env,detached:true,stdio:['ignore',fd,fd]});fs.closeSync(fd);
+  let spawnError:unknown;child.on('error',e=>{spawnError=e;});
+  const stop=()=> {try{process.kill(-child.pid!,'SIGKILL');}catch{/* terminal */}};
+  process.once('SIGTERM',stop);process.once('SIGINT',stop);
+  let endpoint:string|undefined;let connection:string|undefined;let heartbeat:ReturnType<typeof setInterval>|undefined;
+  let closing:Promise<void>|undefined;
+  const close=()=> closing??=(async()=> {
+    if(heartbeat)clearInterval(heartbeat);process.off('SIGTERM',stop);process.off('SIGINT',stop);
+    let closeError:unknown;
+    if(endpoint) {
+      try {await closeBrowserWorker(endpoint,adminToken);}catch(error){closeError=error;}
+      await Bun.sleep(100);
+    }
+    stop();
+    fs.rmSync(privateConfig,{force:true});
+    if(connection)fs.rmSync(connection,{force:true});
+    if(closeError)throw closeError;
+  })();
+  try {
+    const deadline=Math.min(Date.now()+15000,boundary.deadlineAt??Infinity);
+    while(Date.now()<deadline) {
+      for(const line of fs.readFileSync(log,'utf8').split('\n')) {try{endpoint=JSON.parse(line).channelReady??endpoint;}catch{/* native diagnostic */}}
+      if(endpoint)break;
+      if(spawnError || child.exitCode!==null)throw Error(`Browser worker exited: ${spawnError??fs.readFileSync(stderr,'utf8')}`);
+      await Bun.sleep(50);
+    }
+    if(!endpoint)throw Error(`Browser worker not ready: ${fs.readFileSync(stderr,'utf8')}`);
+    heartbeat=setInterval(()=>{void fetch(endpoint!+'/heartbeat',{method:'POST',headers:{authorization:`Bearer ${adminToken}`},signal:AbortSignal.timeout(2000)}).catch(()=>{});},15000);
+    connection=path.join(run.home,'tmp',`${name}-browser-connection.json`);writeJson(connection,{endpoint,token});
+    return {client,connection,log,close,async command(op:string,args:unknown[]=[],id=randomUUID(),phaseDeadlineAt=Infinity) {
+      const remaining=Math.min(boundary.deadlineAt??Infinity,phaseDeadlineAt)-Date.now();
+      if(remaining<=0)throw Error('Browser evaluation deadline exhausted; no dispatch');
+      const response=await fetch(endpoint+'/command',{method:'POST',headers:{authorization:`Bearer ${token}`},body:JSON.stringify({id,op,args}),signal:AbortSignal.timeout(Math.min(35000,Math.ceil(remaining)))});
+      return response.json() as Promise<import('./browser-channel').BrowserResponse>;
+    }};
+  }catch(error){await close();throw error;}
+}

package/support/browser-worker.ts

@@ -0,0 +1,61 @@
+import * as http from 'node:http';
+import { appendFileSync } from 'node:fs';
+import { channelState, dispatchBrowser, type BrowserPort } from './browser-channel';
+
+/** Lifecycle cancellation only; never answers a prompt or produces score evidence. */
+export async function cancelOwnedDialog(page:Record<string,any>,control:()=>Promise<boolean>,origin:string):Promise<unknown>{
+  if(!await control())return {status:'control-lost',dismissed:false};
+  const info=await page.info(),dialog=info?.dialog;
+  if(!dialog)return {status:'no-dialog',dismissed:false};
+  if(!['alert','confirm','prompt','beforeunload'].includes(dialog.type)||typeof dialog.url!=='string'||new URL(dialog.url).origin!==origin)return {status:'outside-lease',dismissed:false};
+  if(!await control())return {status:'control-lost',dismissed:false};
+  await page.dismissDialog();
+  const after=await page.info();
+  if(after?.dialog)throw Error('Owned dialog cancellation did not quiesce; no default answer or repeated dismissal');
+  return {status:'cancelled',dismissed:true,dialogType:dialog.type,origin};
+}
+
+export async function startBrowserWorker(
+  connect: (space: number) => Promise<{ ownership: string; page(label: string): Record<string, any> }>,
+  config: {space:number;origin:string;token:string;adminToken:string;log:string;groundedTargets?:boolean},
+) {
+  const task=await connect(config.space); if(task.ownership!=='agent') throw Error('User or inactive browser control');
+  const page=task.page('p1');
+  const port: BrowserPort={
+    // Navigation establishes a committed DOM, not every passive resource's load.
+    // Keep the SDK deadline inside the owner fence so native diagnostics survive.
+    // A fresh snapshot still supplies actual state; never infer business readiness.
+    invoke: (method,args)=>method==='goto'
+      ?page.goto(args[0],{waitUntil:'domcontentloaded',timeout:10000})
+      :page[method](...args), events:()=>page.events(),
+    control: async()=> (await connect(config.space)).ownership === 'agent',
+    url:()=>page.url(),
+  };
+  const runtime={page:port,origin:config.origin,groundedTargets:config.groundedTargets,timeoutMs:15000,pause:(ms:number)=>new Promise<void>(r=>setTimeout(r,ms)),armDeadline:(ms:number,callback:()=>void)=>{const timer=setTimeout(callback,ms);return ()=>clearTimeout(timer);}};
+  const state=channelState();
+  let resolveClosed:()=>void;const closed=new Promise<void>(resolve=>{resolveClosed=resolve;});
+  let heartbeat=Date.now();
+  const shutdown=()=> {state.stopped='Browser channel closed by owner';clearInterval(watchdog);server.close(()=>resolveClosed());server.closeAllConnections();};
+  const watchdog=setInterval(()=>{if(Date.now()-heartbeat>90000)shutdown();},5000);
+  const server=http.createServer(async(req,res)=> {
+    if(req.method==='POST' && req.headers.authorization===`Bearer ${config.adminToken}` && ['/close','/heartbeat'].includes(req.url??'')) {
+      heartbeat=Date.now();
+      if(req.url==='/close'){
+        try{const cleanup=await cancelOwnedDialog(page,port.control,config.origin);appendFileSync(config.log,JSON.stringify({kind:'owner-dialog-cleanup',space:config.space,cleanup,semanticAuthority:false})+'\n');res.writeHead(200);res.end(JSON.stringify({cleanup}));}
+        catch(error){appendFileSync(config.log,JSON.stringify({kind:'owner-dialog-cleanup-failed',error:String(error),semanticAuthority:false})+'\n');res.writeHead(500);res.end(JSON.stringify({error:String(error)}));}
+        setImmediate(shutdown);return;
+      }
+      res.writeHead(200);res.end('{}');return;
+    }
+    if(req.method!=='POST' || req.url!=='/command' || req.headers.authorization!==`Bearer ${config.token}`) {res.writeHead(403);res.end();return;}
+    let body='';
+    try {
+      for await(const chunk of req) {body+=chunk; if(body.length>65536) throw Error('Request too large');}
+      const request=JSON.parse(body); const response=await dispatchBrowser(runtime,state,request);
+      appendFileSync(config.log,JSON.stringify({channel:'browser-channel-v1',space:config.space,origin:config.origin,request,response})+'\n');
+      res.writeHead(200,{'content-type':'application/json'});res.end(JSON.stringify(response));
+    }catch(error){res.writeHead(400);res.end(JSON.stringify({status:'error',error:String(error)}));}
+  });
+  server.listen(0,'127.0.0.1',()=>appendFileSync(config.log,JSON.stringify({channelReady:`http://127.0.0.1:${(server.address() as {port:number}).port}`,workerPid:process.pid})+'\n'));
+  await closed;
+}

package/support/campaign-ledger.ts

@@ -0,0 +1,66 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type {Budget} from '../budget';
+import {validateBudget} from '../budget';
+import type {Invocation} from '../contract';
+
+interface Reservation {
+  id:string; phase:Invocation['phase']; counter:number;
+  startedAt:number; deadlineMs:number; maxInvocations:number;
+}
+function readLines<T>(root:string,file:string):T[] {
+  const location=path.join(root,file);
+  if(!fs.existsSync(location))return [];
+  return fs.readFileSync(location,'utf8').split('\n').filter(Boolean).map(line=>JSON.parse(line) as T);
+}
+
+/** A reservation survives a controller crash. Unknown usage never refunds a call. */
+export function campaignCalls(budget:Budget,roots:string[]):Invocation[] {
+  validateBudget(budget);
+  const calls:Invocation[]=[],seen=new Set<string>();
+  for(const root of roots) {
+    const reservations=readLines<Reservation>(root,'reservations.jsonl');
+    const finished=readLines<Invocation>(root,'invocations.jsonl');
+    const completed=new Map(finished.map(call=>[call.id,call]));
+    if(completed.size!==finished.length)throw Error('Duplicate native invocation');
+    for(const reservation of reservations) {
+      if(!reservation.id||!['preparation','judgment','representation-repair'].includes(reservation.phase)||reservation.startedAt!==budget.startedAt||reservation.deadlineMs!==budget.deadlineMs||reservation.maxInvocations!==budget.maxInvocations||reservation.counter!==calls.length+1||seen.has(reservation.id))throw Error('Native reservation identity/budget drift');
+      seen.add(reservation.id);
+      const call=completed.get(reservation.id);
+      if(call&&call.phase!==reservation.phase)throw Error('Invocation/reservation phase drift');
+      calls.push(call??{id:reservation.id,phase:reservation.phase,elapsedMs:0,usage:null,completed:false,model:'unknown',effort:null});
+      completed.delete(reservation.id);
+    }
+    // Earlier runs recorded final invocations but not reservations. Keep them,
+    // without inventing a reservation or recovering an unrecorded early launch.
+    if(reservations.length&&completed.size)throw Error('Invocation without native reservation');
+    for(const call of completed.values()) {
+      if(!call.id||seen.has(call.id))throw Error('Duplicate native invocation');
+      seen.add(call.id);calls.push(call);
+    }
+  }
+  if(calls.length<budget.invocations||calls.length>budget.maxInvocations)throw Error('Campaign budget differs from native ledger');
+  return calls;
+}
+
+export function recoverCampaignBudget(budget:Budget,roots:string[]):Invocation[] {
+  const calls=campaignCalls(budget,roots);
+  budget.invocations=calls.length; // Forward only, including incomplete reservations.
+  return calls;
+}
+
+export function assertCampaignRoot(output:string):void {
+  if(!path.isAbsolute(output)||path.resolve(output)!==output||!/^\/(private\/)?tmp\/depa-codument-eval-[^/]+$/.test(output))throw Error('New owned temporary campaign root required');
+  if(fs.existsSync(output)&&fs.lstatSync(output).isSymbolicLink())throw Error('Campaign root cannot be a symlink');
+  const parent=fs.realpathSync(path.dirname(output));
+  if(!['/private/tmp','/tmp'].includes(parent))throw Error('Campaign root escapes temporary ownership');
+}
+
+export function assertRunRoots(output:string,roots:string[]):void {
+  const canonical=fs.realpathSync(output);
+  if(new Set(roots).size!==roots.length)throw Error('Duplicate campaign run root');
+  for(const root of roots) {
+    if(path.dirname(path.resolve(root))!==path.resolve(output))throw Error('Run root escapes campaign');
+    if(fs.existsSync(root)&&(fs.lstatSync(root).isSymbolicLink()||path.dirname(fs.realpathSync(root))!==canonical))throw Error('Run root symlink escapes campaign');
+  }
+}

package/support/code-knowledge.ts

@@ -0,0 +1,73 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {digest} from './isolation';
+import type {Manifest} from '../contract';
+
+/** Caller-selected, optional navigation. No tool process, graph DB or new judge authority. */
+export interface CodeEvidenceSelection {path:string;sourceRoot:string}
+interface ByteIdentity {path:string;sha256:string;bytes:number}
+export function sourceByteInventory(root:string):ByteIdentity[] {
+  const result:ByteIdentity[]=[];let bytes=0;
+  function visit(dir:string):void {
+    if(fs.lstatSync(dir).isSymbolicLink())throw Error('Code evidence cannot follow links');
+    for(const name of fs.readdirSync(dir)){
+      const file=path.join(dir,name),stat=fs.lstatSync(file);
+      if(stat.isSymbolicLink())throw Error('Code evidence cannot follow links');
+      if(stat.isDirectory()){visit(file);continue;}
+      if(!stat.isFile())throw Error('Code evidence requires regular files');
+      const relative=path.relative(root,file).split(path.sep).join('/');
+      if(/[\0\r\n\\]/.test(relative))throw Error('Unsupported snapshot path');
+      bytes+=stat.size;if(result.length>=10000||bytes>128*1024*1024)throw Error('Code snapshot exceeds inventory bound');
+      result.push({path:relative,sha256:digest(fs.readFileSync(file)),bytes:stat.size});
+    }
+  }
+  visit(root);return result.sort((a,b)=>a.path<b.path?-1:a.path>b.path?1:0);
+}
+export function sourceByteDigest(files:ByteIdentity[]):string {
+  return digest(files.map(f=>`${f.path}\0${f.sha256}\0${f.bytes}\n`).join(''));
+}
+function owned(root:string,relative:string):string {
+  if(!relative||path.isAbsolute(relative)||relative.split(/[\\/]/).some(p=>p==='..'||p==='.'||p===''))throw Error('Code evidence path escapes artifact');
+  let current=root;
+  for(const part of relative.split('/')){
+    current=path.join(current,part);
+    if(fs.lstatSync(current).isSymbolicLink())throw Error('Code evidence cannot follow links');
+  }
+  return current;
+}
+
+/** Called after native artifact freezing; stale envelopes fail before model invocation.
+ * The ordinary file observer reads this envelope plus bounded candidate source files.
+ * Unsupported/unreadable sources remain in inventory; no observation is invented. */
+export function attachCodeKnowledgeEvidence(manifest:Manifest,selection:CodeEvidenceSelection):Manifest {
+  const root=fs.realpathSync(manifest.artifact),source=owned(root,selection.sourceRoot),file=owned(root,selection.path);
+  if(file===source||file.startsWith(source+path.sep))throw Error('Evidence must be outside its source snapshot');
+  if(fs.statSync(file).size>1048576)throw Error('Code evidence exceeds file observation bound');
+  const evidence=JSON.parse(fs.readFileSync(file,'utf8'));
+  if(evidence.format!=='depa-code-navigation-v1')throw Error('Unknown code evidence format');
+  const inventory=sourceByteInventory(source),identity=sourceByteDigest(inventory);
+  if(evidence.snapshotDigest!==identity||JSON.stringify(evidence.inventory)!==JSON.stringify(inventory))throw Error('Stale or different code evidence snapshot');
+  if(!Array.isArray(evidence.coverage)||evidence.coverage.length!==inventory.length)throw Error('Incomplete code evidence coverage');
+  const seen=new Set<string>(),fileIds=new Map<string,string>();
+  for(const row of evidence.coverage){
+    const original=inventory.find(f=>f.path===row.path);
+    if(!original||seen.has(row.path)||original.sha256!==row.sha256||original.bytes!==row.bytes||!['document','text-or-regex-fallback','semantic-candidate','over-size-or-excluded','skipped','unsupported-or-excluded'].includes(row.status)||!Array.isArray(row.resolvers))throw Error('Invalid code evidence coverage');
+    seen.add(row.path);if(row.fileId)fileIds.set(row.fileId,row.path);
+  }
+  if(!Array.isArray(evidence.symbols)||!Array.isArray(evidence.edges)||evidence.symbols.length>200||evidence.edges.length>400||!evidence.parser||!evidence.settings||!Array.isArray(evidence.limitations)||!evidence.limitations.length)throw Error('Incomplete bounded code evidence');
+  for(const kind of ['symbols','edges'] as const){
+    const omitted=kind==='symbols'?'omittedSymbols':'omittedEdges';
+    if(!Number.isSafeInteger(evidence.totals?.[kind])||evidence.totals[kind]<evidence[kind].length||evidence.totals[omitted]!==evidence.totals[kind]-evidence[kind].length)throw Error('Invalid code evidence truncation');
+  }
+  for(const row of [...evidence.symbols,...evidence.edges])if(row.fileId&&!fileIds.has(row.fileId))throw Error('Code location outside frozen inventory');
+  const probes=[...(manifest.files??[])];
+  const add=(relative:string,conditions:string)=>{if(!probes.some(p=>p.path===relative))probes.push({path:relative,conditions});};
+  add(selection.path,'Optional static code navigation from byte-bound frozen source. Inspect coverage, parser/resolvers, unresolved calls and truncation. Missing hits prove no absence; paths prove no execution or past event. Back-read source before using a candidate; original requirements and judge authority are unchanged.');
+  for(const relative of new Set<string>(evidence.symbols.map((s:{fileId:string})=>fileIds.get(s.fileId)).filter(Boolean))){
+    const content=fs.readFileSync(path.join(source,relative));
+    try{if(content.length>1048576)continue;new TextDecoder('utf-8',{fatal:true}).decode(content);}
+    catch{continue;}
+    add(selection.sourceRoot+'/'+relative,'Actual frozen source read to check optional navigation candidates. Static inspection establishes neither runtime execution nor completeness of unsupported files.');
+  }
+  return {...manifest,files:probes};
+}

package/support/counter-review.ts

@@ -0,0 +1,35 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type {Decision,EvaluationConfig,EvaluationInput,Invocation} from '../contract';
+import {counterCandidateView,eligibleCandidate,resolveCounterReview,unavailableCounterReview,type CounterReviewResult} from '../counter-review';
+import type {Budget} from '../budget';
+import {JudgeProtocolError} from '../proposal';
+import {modelTurn} from './model-turn';
+import type {AgentRun,AgentRuntime} from './agent-runtime';
+import type {ProcessState} from './process';
+import {JUDGE_GUIDANCE,SERVICE_FACT_GUIDANCE} from './judge';
+import {PROPOSAL_GUIDANCE,COUNTER_REVIEW_GUIDANCE} from './guidance';
+import {NEED_GUIDANCE} from '../needs';
+
+export {candidateWindow} from '../budget';
+
+export function counterGuidance(replacementGuide:string):string {
+  return [JUDGE_GUIDANCE.replace('Interpret native facts, not prior verdicts or execution inferred from code.','Interpret native facts. Only the explicitly supplied candidate is a fallible claim to challenge, never authority/evidence. No other assessment may be read. Do not infer execution from code.'),SERVICE_FACT_GUIDANCE,
+    COUNTER_REVIEW_GUIDANCE.replace('{{replacementGuide}}',JSON.stringify(replacementGuide))].join('\n');
+}
+
+/** Explicit opt-in effect. Exactly one fresh review, using the original budget. */
+export async function counterReview(runtime:{run:AgentRun;budget:Budget;state:ProcessState;agent?:AgentRuntime},input:EvaluationInput,candidate:Decision,config:EvaluationConfig):Promise<CounterReviewResult> {
+  if(!eligibleCandidate(input,candidate,config))return {candidate,review:null,decision:candidate,resolution:'not-required'};
+  if(runtime.budget.invocations>=runtime.budget.maxInvocations||Date.now()>=runtime.budget.startedAt+runtime.budget.deadlineMs)return unavailableCounterReview(candidate,candidate.invocations,'No original budget remains for required experimental counter-review','budget');
+  const invocations:Invocation[]=[];
+  try{
+    const guide=path.join(runtime.run.root,'input','counter-replacement-guide.md');
+    fs.writeFileSync(guide,[PROPOSAL_GUIDANCE,...(input.needs?.length?[NEED_GUIDANCE]:[])].join('\n'),{flag:'wx'});
+    const payload={...input,policy:config,candidate:counterCandidateView(input,candidate,config)};
+    const value=await modelTurn({...runtime,invocations},{evaluation:input,payload,guidance:counterGuidance(guide),phase:'counter-review'});
+    return resolveCounterReview(input,candidate,value,[...candidate.invocations,...invocations],config);
+  }catch(error){
+    return unavailableCounterReview(candidate,[...candidate.invocations,...invocations],String(error),error instanceof JudgeProtocolError?'protocol':'infrastructure');
+  }
+}

package/support/ego-tools.ts

@@ -0,0 +1,19 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+
+export const EGO_SKILL = path.join(os.homedir(), '.agents/skills/ego-browser');
+export function resolveEgo(): { executable: string; installRoot: string } {
+  const executable = process.env.E2E_EGO_BINARY ?? path.join(os.homedir(), '.local/bin/ego-browser');
+  const real = fs.realpathSync(executable);
+  return { executable, installRoot: path.dirname(path.dirname(real)) };
+}
+export function egoToolPaths(): { read: string[]; write: string[] } {
+  return { read: [resolveEgo().installRoot, path.join(os.homedir(), '.local/share/ego'), EGO_SKILL], write: [] };
+}
+/** Supplied by the owner; never create/claim a replacement space on failure. */
+export function egoSpace(): number {
+  const id = Number(process.env.E2E_EGO_SPACE_ID);
+  if (!Number.isSafeInteger(id) || id <= 0) throw new Error('E2E_EGO_SPACE_ID must identify the owner-created Ego TaskSpace');
+  return id;
+}

package/support/evidence-catalog.ts

@@ -0,0 +1,37 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {readContent} from './evidence-object';
+
+/** Native immutable index transport; metadata is never a semantic observation. */
+export function evidenceCatalog(indexFile:string) {
+  if(!path.isAbsolute(indexFile))throw Error('Absolute current index required');
+  const index=JSON.parse(fs.readFileSync(indexFile,'utf8'));
+  if(!Array.isArray(index.observations))throw Error('Native observation catalog required');
+  const seen=new Set<string>();
+  const observations=index.observations.map((o:any)=>{
+    if(!/^obs:[1-9]\d*$/.test(o.observationRef)||seen.has(o.observationRef))throw Error('Unknown or ambiguous observation reference');
+    if(!path.isAbsolute(o.contentPath)||!Number.isSafeInteger(o.bytes)||o.bytes<0||!/^[a-f0-9]{64}$/.test(o.contentDigest))throw Error('Invalid complete object metadata');
+    seen.add(o.observationRef);
+    // Strip bodies even if a malformed caller duplicated them in the index.
+    const {content:_content,...metadata}=o;
+    return metadata;
+  });
+  return {indexPath:indexFile,metadataOnly:true,observations,
+    usage:'Choose current observationRef values and read complete objects. Empty refs lists metadata only; metadata does not prove any requirement.'};
+}
+
+/** Mechanical selection only; no action, score, summary, range or invented ref. */
+export function readIndexedEvidence(indexFile:string,refs:string[]) {
+  if(!Array.isArray(refs)||!refs.length||refs.length>32||new Set(refs).size!==refs.length||refs.some(ref=>!/^obs:[1-9]\d*$/.test(ref)))throw Error('1..32 distinct obs:N references required');
+  const index=evidenceCatalog(indexFile);
+  return refs.map(ref=>{
+    const observation=index.observations.find((o:any)=>o.observationRef===ref);
+    if(!observation)throw Error('Unknown observation reference: '+ref);
+    return {...observation,content:readContent(observation)};
+  });
+}
+
+/** One discovery/read entrance shared by Halfcode and isolated native turns. */
+export function inspectEvidence(indexFile:string,refs:string[]=[]) {
+  return refs.length?readIndexedEvidence(indexFile,refs):evidenceCatalog(indexFile);
+}