agentlinkops 0.6.3 → 0.6.5

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agentlinkops",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "Connect an agent to AgentLinkOps and run backlink work with it: the connect skill (views, the three discovery verbs, evidence rules), local ledger and campaign skills, a portable CRM, the source-cited content pipeline, user-managed disavow lists, HTML reports and monitoring-event sync.",
   "author": {
     "name": "AgentLinkOps"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agentlinkops",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "Connect an agent to AgentLinkOps and run backlink work with it: the connect skill (views, the three discovery verbs, evidence rules), local ledger and campaign skills, a portable CRM, the source-cited content pipeline, user-managed disavow lists, HTML reports and monitoring-event sync.",
   "author": {
     "name": "AgentLinkOps"

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to the `agentlinkops` package are recorded here. The version follows the
 plugin manifests in `.claude-plugin/` and `.codex-plugin/`.
 
+## 0.6.5 (2026-09-20)
+
+- Browser measurement requires a configured proxy. Authorized direct diagnostics need an explicit setting; missing proxy configuration never selects direct traffic.
+- Bound proxy acquisition, callback and cleanup waits. Failed cleanup quarantines the lease and blocks reuse; errors exclude provider details that could contain credentials.
+- Keep supplied usage measurements separate from estimated costs. The standard URL proxy has no meter, and engine callback receipts are not persisted by the CLI runner.
+
+## 0.6.4 (2026-09-20)
+
+- Import and export immutable local IndexNow submission receipts, with hashes and replay checks. These commands send no submissions.
+- Join each submission attempt to later retained index observations for the exact URL and project. JSON and CSV preserve source, date, reason and unknown results.
+- Submission responses remain received, validation pending, failed or unknown. Later Google observations do not verify indexing by an IndexNow participant or establish that submission caused indexing.
+
 ## 0.6.3 (2026-09-20)
 
 - Agent installation preserves customer edits and supports previewed removal and interrupted-install recovery.

package/README.md

@@ -156,10 +156,16 @@ agentlinkops citation run panel.json --max-usd 1.00
 The panel is JSON: `targets` (domain or url, brand, aliases), `prompts`, `engines`
 (`mock` or `perplexity`), optional `samples` and `maxUsd`. Every run writes immutable
 content-addressed answer snapshots plus append-only observation and epoch rows under
-`.agentlinkops/citations/`. The USD cap is checked before each call, so it can be approached
-but never exceeded, and a budget abort leaves a partial-epoch receipt and exit code 2. A cell
+`.agentlinkops/citations/`. The runner reserves estimated cost before each call and retry. A reported supplier
+overrun stops later calls; estimates do not enforce a provider invoice cap. A budget
+abort leaves a partial-epoch receipt and exit code 2. A cell
 that declined with complete evidence exits 1, like an expected link observed absent.
 
+Browser measurement requires `AGENTLINKOPS_PROXY_URL` and refuses direct fallback.
+For an explicitly authorized direct diagnostic, set `AGENTLINKOPS_BROWSER_EGRESS=direct-diagnostic`
+and leave the proxy unset. The standard URL proxy provides no actual usage meter;
+its cost remains an estimate. Browser login and live account acceptance are separate.
+
 ## Environment variables
 
 | Variable | Purpose |
@@ -168,6 +174,8 @@ that declined with complete evidence exits 1, like an expected link observed abs
 | `AGENTLINKOPS_API_URL` | Hosted origin when it is not in `config.json`. |
 | `AGENTLINKOPS_WEBHOOK_SECRET` | Verifies signed deliveries in `agentlinkops receive`. |
 | `AGENTLINKOPS_GSC_TOKEN`, `AGENTLINKOPS_GA4_TOKEN` | First-party context commands under `agentlinkops context`. |
+| `AGENTLINKOPS_PROXY_URL` | Proxy URL for browser measurement; credentials are never printed. |
+| `AGENTLINKOPS_BROWSER_EGRESS` | Defaults to `proxy-required`; `direct-diagnostic` explicitly permits an authorized diagnostic without a proxy. |
 | `PERPLEXITY_API_KEY` | Live engine credential for `agentlinkops citation`. Presence is reported by `doctor`; the value is never printed. |
 
 No value is ever printed. The `LINKTRAIL_*` spellings, the `linktrail` command and a `.linktrail/`

package/cli/citation.js

@@ -68,7 +68,9 @@ Panel (JSON): targets (domain or url, brand, aliases), prompts, engines
 Live engines need their configured credentials or a usable browser session; the mock
 engine runs everything at zero cost. Every run states its estimated spend, and the
 cap reserves estimated cost before each call. A supplier charge above that estimate
-is recorded as an overrun and stops subsequent calls.
+is recorded as an overrun and stops subsequent calls. Browser measurement requires
+AGENTLINKOPS_PROXY_URL. Authorized direct diagnostics need
+AGENTLINKOPS_BROWSER_EGRESS=direct-diagnostic with no proxy configured.
 
 Output language: citation RATE with a Wilson interval and n, classified against the
 previous epoch as declined, grown or not_distinguishable — never "removed", never

package/cli/client.js

@@ -2,7 +2,7 @@ import {restResponseContract} from '../shared/response-contract.js';
 // A small HTTP client for the cloud. Scoped keys only; no human session ever reaches here.
 // DP-0036-T13: the CLI names itself so the usage counters can tell it from other REST callers.
 // The version follows the plugin manifests; bump it with them.
-export const CLI_VERSION = '0.6.3';
+export const CLI_VERSION = '0.6.5';
 export const CLI_USER_AGENT = `agentlinkops-cli/${CLI_VERSION}`;
 export class CloudError extends Error {
   constructor(code, status, details = null) {

package/cli/config.js

@@ -20,6 +20,7 @@ export const DEFAULTS = Object.freeze({
   receipts: 'receipts.jsonl',
   observations: 'observations.jsonl',
   indexObservations: 'index-observations.jsonl',
+  indexSubmissions: 'index-submissions.jsonl',
   events: 'events.jsonl',
   candidates: 'candidates.jsonl',
   state: 'state.json',
@@ -99,7 +100,7 @@ export async function loadConfig({ cwd = process.cwd(), root = null } = {}) {
     defaults: { ...DEFAULTS, ...file.defaults },
     paths: {
       ledger: at('ledger'), observations: at('observations'), events: at('events'),
-      candidates: at('candidates'), state: at('state'), receipts: at('receipts'), indexObservations: at('indexObservations'),
+      candidates: at('candidates'), state: at('state'), receipts: at('receipts'), indexObservations: at('indexObservations'), indexSubmissions: at('indexSubmissions'),
     },
   };
 }

package/cli/doctor.js

@@ -271,7 +271,7 @@ export async function doctorMain(argv = [], { cwd = process.cwd(), out = console
       execFile('camoufox', ['path'], { timeout: 8000 }, (error) => resolve(!error));
     });
     if (camoufoxOk) {
-      checks.push({ status: 'ok', name: 'browser', detail: 'playwright-core + camoufox present; browser engines available' });
+      checks.push({ status: 'ok', name: 'browser', detail: 'playwright-core + camoufox present; browser dependencies present; proxy and account access remain unverified' });
     } else {
       checks.push({ status: 'skip', name: 'browser', detail: 'playwright-core ok but camoufox missing', fix: 'python3 -m pip install cloverlabs-camoufox[geoip] && python3 -m camoufox fetch' });
     }

package/cli/index-observations.js

@@ -1,3 +1,4 @@
+import {boundedSubmissionText,readSubmissions,saveSubmissions,reconcileSubmissions,submissionCsv} from './index-submissions.js';
 import {readFile,writeFile,open,rename,unlink,mkdir,stat} from 'node:fs/promises';
 import {dirname,resolve} from 'node:path';
 import {createHash} from 'node:crypto';
@@ -9,7 +10,7 @@ import {indexEvidenceReference,describeEvidenceReference} from '../src/evidence-
 import {indexReceiptResponse} from '../shared/index-observation-contract.js';
 const sha=value=>createHash('sha256').update(value).digest('hex');
 const fail=message=>{throw new ConfigError(message);};
-export const INDEX_CLI_HELP='agentlinkops index pull --watch-id ID [--limit 50] [--before ID] | import RECEIPTS.json | export [--out FILE] | csv URLS.csv [--out FILE] | check-csv URLS.csv --connection-id ID --request-id ID --out FILE';
+export const INDEX_CLI_HELP='agentlinkops index pull --watch-id ID [--limit 50] [--before ID] | import RECEIPTS.json | export [--out FILE] | csv URLS.csv [--out FILE] | check-csv URLS.csv --connection-id ID --request-id ID --out FILE | submissions-import FILE | submissions-export --project-id ID [--out FILE] | reconcile-submissions --project-id ID [--format json|csv] [--out FILE]';
 function validate(row){
  if(row?.v!==1||! /^[\w-]{1,128}$/.test(row.project_id??'')||! /^[\w-]{1,128}$/.test(row.watch_id??''))fail('Invalid local index receipt scope');
  const receipt=indexReceiptResponse.parse(row.receipt);
@@ -61,6 +62,19 @@ function csvInput(text){
 }
 export async function indexMain(args,{cwd=process.cwd(),env=process.env,out=console.log,fetchImpl=globalThis.fetch}={}){
  const command=args._[1],config=await loadConfig({cwd}),path=config.paths.indexObservations;
+ if(['submissions-import','submissions-export','reconcile-submissions'].includes(command)){
+  const allowed=new Set(['_','tag','out','project-id','format']);
+  if(args.tag?.length||Object.keys(args).some(key=>!allowed.has(key))||args._.length!==(command==='submissions-import'?3:2))fail(INDEX_CLI_HELP);
+  if(command==='submissions-import'){
+   if(args.out||args['project-id']||args.format)fail(INDEX_CLI_HELP);
+   out(JSON.stringify(await saveSubmissions(config.paths.indexSubmissions,JSON.parse(await boundedSubmissionText(resolve(cwd,args._[2]))))));return 0;
+  }
+  if(args.format&&!['json','csv'].includes(args.format))fail('Submission format must be json or csv');
+  if(command==='submissions-export'&&args.format)fail(INDEX_CLI_HELP);
+  const report=reconcileSubmissions(await readSubmissions(config.paths.indexSubmissions),command==='reconcile-submissions'?await readIndexReceipts(path):[],args['project-id']);
+  const text=command==='submissions-export'?JSON.stringify(report.submissions.map(({outcome,observations,verification,...row})=>row),null,2):args.format==='csv'?submissionCsv(report):JSON.stringify(report,null,2);
+  if(args.out){if(typeof args.out!=='string')fail('--out requires a file');await atomicOutput(resolve(cwd,args.out),text);}else out(text);return 0;
+ }
  const allowed=new Set(['_','tag','out','watch-id','limit','before','connection-id','request-id']);if(args.tag?.length||Object.keys(args).some(key=>!allowed.has(key)))fail(INDEX_CLI_HELP);
  if(command==='import'){
   if(!args._[2])fail(INDEX_CLI_HELP);const parsed=JSON.parse(await boundedText(resolve(cwd,args._[2])));if(!Array.isArray(parsed)||parsed.length>100)fail('Import requires an array of at most 100 scoped index receipts');out(JSON.stringify(await saveIndexReceipts(path,parsed)));return 0;

package/cli/index-submissions.js

@@ -0,0 +1,50 @@
+import {readFile,writeFile,open,rename,unlink,mkdir,stat} from 'node:fs/promises';
+import {dirname} from 'node:path';
+import {createHash} from 'node:crypto';
+import {ConfigError} from './config.js';
+import {indexEvidenceReference} from '../src/evidence-reference.js';
+const fail=message=>{throw new ConfigError(message);};
+const digest=value=>createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const id=value=>typeof value==='string'&&/^[\w-]{1,128}$/.test(value);
+const fields=['v','id','project_id','url','channel','endpoint','submitted_at','http_status','evidence_sha256'];
+export const SUBMISSION_NOTE='Imported submission records describe reported HTTP responses. Hashes check local integrity, not provider authenticity. Later Google observations do not verify indexing by an IndexNow participant or show that submission caused indexing.';
+export function validateSubmission(row){
+ if(!row||Object.keys(row).some(k=>!fields.includes(k))||fields.some(k=>!Object.hasOwn(row,k))||row.v!==1||!id(row.id)||!id(row.project_id)||row.channel!=='indexnow'||row.endpoint!=='https://api.indexnow.org/indexnow')fail('Invalid IndexNow submission receipt');
+ let url;try{url=new URL(row.url);}catch{fail('Invalid submission URL');}
+ if(typeof row.url!=='string'||url.href!==row.url||!['https:','http:'].includes(url.protocol)||url.username||url.password||url.hash)fail('Submission URL must be exact HTTP(S) without credentials or fragment');
+ if(typeof row.submitted_at!=='string'||!Number.isFinite(Date.parse(row.submitted_at))||new Date(row.submitted_at).toISOString()!==row.submitted_at)fail('Submission date must be an ISO UTC timestamp');
+ if(row.http_status!==null&&(!Number.isInteger(row.http_status)||row.http_status<100||row.http_status>599))fail('Invalid submission HTTP status');
+ const body=Object.fromEntries(fields.filter(k=>k!=='evidence_sha256').map(k=>[k,row[k]]));
+ if(row.evidence_sha256!==digest(body))fail('Submission receipt hash mismatch');
+ return {...body,evidence_sha256:row.evidence_sha256};
+}
+export async function boundedSubmissionText(path){const info=await stat(path);if(info.size>32*1024*1024)fail('Submission input exceeds 32 MiB');return readFile(path,'utf8');}
+export async function readSubmissions(path){try{return (await boundedSubmissionText(path)).split('\n').filter(line=>line.trim()).map(line=>validateSubmission(JSON.parse(line)));}catch(error){if(error.code==='ENOENT')return [];throw error;}}
+export async function saveSubmissions(path,rows){
+ if(!Array.isArray(rows)||rows.length>100)fail('Import requires at most 100 submission receipts');
+ const checked=rows.map(validateSubmission);await mkdir(dirname(path),{recursive:true});let lock;
+ try{lock=await open(`${path}.lock`,'wx');}catch(error){if(error.code==='EEXIST')fail('Submission receipt writer already locked');throw error;}
+ const tmp=`${path}.${crypto.randomUUID()}.tmp`;
+ try{
+  const current=await readSubmissions(path),byId=new Map(current.map(r=>[`${r.project_id}:${r.id}`,r]));
+  for(const row of checked){const key=`${row.project_id}:${row.id}`,old=byId.get(key);if(old&&JSON.stringify(old)!==JSON.stringify(row))fail('Submission receipt identity conflict');byId.set(key,row);}
+  const text=[...byId.values()].sort((a,b)=>a.project_id.localeCompare(b.project_id)||a.submitted_at.localeCompare(b.submitted_at)||a.id.localeCompare(b.id)).map(r=>JSON.stringify(r)).join('\n')+'\n';
+  if(Buffer.byteLength(text)>32*1024*1024)fail('Submission receipts exceed 32 MiB; archive before importing more');
+  await writeFile(tmp,text,{flag:'wx'});await rename(tmp,path);return {imported:checked.length,total:byId.size};
+ }finally{await unlink(tmp).catch(()=>{});await lock.close();await unlink(`${path}.lock`);}
+}
+export function reconcileSubmissions(submissions,observations,projectId){
+ if(!id(projectId))fail('A valid --project-id is required');
+ return {v:1,project_id:projectId,note:SUBMISSION_NOTE,submissions:submissions.filter(r=>r.project_id===projectId).map(validateSubmission).map(row=>{
+  const subsequent=observations.filter(r=>r.project_id===projectId&&r.receipt.observation.url===row.url&&Date.parse(r.receipt.observation.checked_at)>Date.parse(row.submitted_at)).map(r=>{
+   const o=r.receipt.observation;return {watch_id:r.watch_id,observation_id:o.id,checked_at:o.checked_at,backend:o.backend,source_key:o.source_key,tier:o.tier,reason:o.reason,confidence:o.confidence,evidence_sha256:o.evidenceSha256,evidence_available:r.receipt.evidenceAvailable,evidence_reference:indexEvidenceReference({receiptId:o.id}),relationship:'observation_after_submission',participant_indexing_verified:false,causation_established:false};
+  }).sort((a,b)=>a.checked_at.localeCompare(b.checked_at)||a.observation_id.localeCompare(b.observation_id));
+  return {...row,outcome:row.http_status===200?'received':row.http_status===202?'key_validation_pending':row.http_status===null?'unknown':'failed',observations:subsequent,verification:'not_established'};
+ })};
+}
+const cell=value=>{const raw=String(value??''),safe=/^[\s]*[=+\-@]|^[\t\r]/.test(raw)?`'${raw}`:raw;return `"${safe.replaceAll('"','""')}"`;};
+export function submissionCsv(report){
+ const rows=[['Project','Submission ID','URL','Submitted At','HTTP Status','Submission Outcome','Submission Hash','Observation ID','Watch ID','Backend','Source','Check Date','Verdict','Reason','Confidence','Evidence Available','Observation Hash','Evidence Reference','Participant Indexing Verified','Causation Established','Reading Note']];
+ for(const s of report.submissions)for(const o of s.observations.length?s.observations:[null])rows.push([report.project_id,s.id,s.url,s.submitted_at,s.http_status,s.outcome,s.evidence_sha256,o?.observation_id,o?.watch_id,o?.backend,o?.source_key,o?.checked_at,o?.tier??'unknown',o?.reason??'no_later_observation',o?.confidence??'unknown',o?.evidence_available??false,o?.evidence_sha256,o?.evidence_reference,false,false,report.note]);
+ return rows.map(row=>row.map(cell).join(',')).join('\r\n')+'\r\n';
+}

package/cli/main.js

@@ -56,6 +56,8 @@ const USAGE = `agentlinkops — a backlink ledger that lives in your repository
   agentlinkops admission list|add|update|remove|evaluate|reevaluate|receipt --project ID
   agentlinkops disavow list|history|propose|import|export|approve|reject|delete
   agentlinkops index import FILE | export [--out FILE] | csv URLS.csv [--out FILE]
+  agentlinkops index submissions-import FILE | submissions-export --project-id ID [--out FILE]
+  agentlinkops index reconcile-submissions --project-id ID [--format json|csv] [--out FILE]
   agentlinkops index check-csv URLS.csv --connection-id ID --request-id ID --out FILE
   agentlinkops import FILE --target DOMAIN [--from SUPPLIER] [--map source=COL,target=COL]
                 [--exact-url] [--no-subdomains] [--generated-at ISO] [--json]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentlinkops",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "A backlink and AI citation ledger that lives in your repository: local link and citation checks with dated evidence, supplier-export imports and optional sync to the hosted AgentLinkOps service.",
   "author": "AgentLinkOps (https://agentlinkops.com)",
   "license": "Apache-2.0",

package/references/citation-panels.md

@@ -14,6 +14,8 @@ Use `--competitors competitors.json` to add domains to check beside your own. Th
 
 Choose a live engine explicitly after checking access and budget. For an existing browser setup, use `--engine chatgpt:web-own-browser` or `--engine grok:web-own-browser`. `--engine google-aio` requires your configured supplier access. This workflow does not create accounts or buy services.
 
+Starting with CLI 0.6.5, browser measurement requires `AGENTLINKOPS_PROXY_URL`. Missing, failed or quarantined proxy admission never selects direct traffic. An explicitly authorized direct diagnostic requires `AGENTLINKOPS_BROWSER_EGRESS=direct-diagnostic` with no proxy configured. The standard URL proxy has no usage meter; estimated costs are not a provider invoice cap.
+
 Set `--locale en-GB --country GB` for a British locale draft. The mock engine supports locale fixtures. The Google AIO supplier path supports US and GB location requests; other engine paths refuse non-default locale requests in this version. Legacy default browser observations do not prove US proxy egress. Reports disclose the requested context and its basis; they do not treat it as verified user geography.
 
 After reviewing the draft, run the [local CLI workflow](cli.md) and inspect the retained evidence:

package/src/citations/browser/engine.js

@@ -14,6 +14,7 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 
 import { EngineError } from '../adapter.js';
+import {createProxyAdmission,proxyFailureReason} from './proxy-admission.js';
 
 const MODULE_LOADERS = {
   'playwright-core': () => import('playwright-core'),
@@ -56,20 +57,6 @@ const ENGINE_NOMINAL_COST = Object.freeze({
 });
 const DEFAULT_NOMINAL_COST = 0.03;
 
-function parseProxyUrl(raw) {
-  if (!raw) return null;
-  try {
-    const url = new URL(raw);
-    return {
-      server: `${url.protocol}//${url.hostname}:${url.port}`,
-      username: decodeURIComponent(url.username),
-      password: decodeURIComponent(url.password),
-    };
-  } catch {
-    throw new EngineError(`AGENTLINKOPS_PROXY_URL is not a valid proxy URL (length ${raw.length}, value never printed)`);
-  }
-}
-
 export function createBrowserEngine({ engineName, env = process.env, onEvent = () => {}, runtime = {} } = {}) {
   if (!BROWSER_PROVIDERS.includes(engineName)) {
     throw new EngineError(`unknown browser engine: ${engineName} (known: ${BROWSER_PROVIDERS.join(', ')})`);
@@ -78,13 +65,21 @@ export function createBrowserEngine({ engineName, env = process.env, onEvent = (
   const sessionDir = runtime.sessionDir ?? join(homedir(), '.agentlinkops', 'citations', 'sessions');
   const load = runtime.loadModule ?? lazy;
   const platform = runtime.platform ?? process.platform;
+  const event=async text=>{
+    let timer;
+    try{await Promise.race([Promise.resolve().then(()=>onEvent(text)),new Promise((_,reject)=>{timer=setTimeout(()=>reject(Error()),runtime.supplierTimeoutMs??5000);})]);}
+    catch{throw new EngineError('Browser event reporting failed.');}
+    finally{clearTimeout(timer);}
+  };
 
+  const admission=createProxyAdmission({engine:engineName,env,supplier:runtime.proxySupplier,now:runtime.now,onReceipt:runtime.onEgressReceipt,timeoutMs:runtime.supplierTimeoutMs});
+  let running=false,contextCleanupFailed=false;
   let browserHandle = null;   // { browser, cleanup } for the whole epoch
   let displayHandle = null;
   let providerConfig = null;
   async function closeQuietly(action) {
     let timer;
-    try { await Promise.race([Promise.resolve().then(action).catch(() => null), new Promise(resolve => { timer = setTimeout(resolve, runtime.cleanupTimeoutMs ?? 5000); })]); }
+    try { return await Promise.race([Promise.resolve().then(action).then(() => true, () => false), new Promise(resolve => { timer = setTimeout(() => resolve(false), runtime.cleanupTimeoutMs ?? 5000); })]); }
     finally { clearTimeout(timer); }
   }
 
@@ -109,11 +104,11 @@ export function createBrowserEngine({ engineName, env = process.env, onEvent = (
     // engines that block headless render headfully inside a virtual display.
     if (platform === 'linux' && !display.detectDisplay()) {
       displayHandle = await display.ensureDisplay({ allowExistingDisplay: false });
-      onEvent(`display: ${displayHandle.display}`);
+      await event(`display: ${displayHandle.display}`);
     }
 
-    const proxy = parseProxyUrl(env.AGENTLINKOPS_PROXY_URL);
-    if (proxy) onEvent(`proxy: ${proxy.server}`);
+    const proxy = admission.proxy;
+    await event(proxy?'egress: proxy-required':'egress: direct-diagnostic');
 
     const options = await resolveCamoufoxLaunchOptions({
       provider: engineName,
@@ -127,14 +122,17 @@ export function createBrowserEngine({ engineName, env = process.env, onEvent = (
     });
     const launchOpts = { ...options, executablePath: options.executablePath };
     if (proxy) launchOpts.proxy = proxy;
+    admission.assertReady();
     const browser = await fw.launch(launchOpts);
 
     browserHandle = {
       browser,
       cleanup: async () => {
-        await closeQuietly(() => browser.close());
-        await displayHandle?.cleanup?.().catch(() => null);
+        const browserClosed=await closeQuietly(() => browser.close());
+        const displayClosed=await closeQuietly(() => displayHandle?.cleanup?.());
         displayHandle = null;
+        if(browserClosed)contextCleanupFailed=false;
+        return browserClosed&&displayClosed;
       },
     };
     return browserHandle;
@@ -193,13 +191,14 @@ export function createBrowserEngine({ engineName, env = process.env, onEvent = (
     return null;
   }
 
-  return {
+  const engine = {
     identity,
     estimateCostUsd: () => ENGINE_NOMINAL_COST[engineName] ?? DEFAULT_NOMINAL_COST,
 
     async run({ prompt }) {
       const config = await ensureProviderConfig();
       const { browser } = await ensureBrowser();
+      admission.assertReady();
       const storageState = await loadStorageState();
       const context = await browser.newContext({
         storageState,
@@ -318,9 +317,9 @@ export function createBrowserEngine({ engineName, env = process.env, onEvent = (
             : `${engineName}: answer extracted empty`;
           throw new EngineError(reason, { retriable: true });        }
         let extractionFailed = config.citationExtraction === 'unsupported';
-        const sources = await config.extractSources(page).catch(() => {
+        const sources = await config.extractSources(page).catch(async () => {
           extractionFailed = true;
-          onEvent('sources extraction failed; observation retained as unknown');
+          await event('sources extraction failed; observation retained as unknown');
           return [];
         });
         const screenshotPng = await page.screenshot({ fullPage: false }).catch(() => null);
@@ -347,16 +346,64 @@ export function createBrowserEngine({ engineName, env = process.env, onEvent = (
         error.unknown = true;
         throw error;
       } finally {
-        await closeQuietly(() => context.close());
+        if(!await closeQuietly(() => context.close()))contextCleanupFailed=true;
       }
     },
 
     // Called by the runner at epoch end.
     async close() {
-      await browserHandle?.cleanup?.();
-      await displayHandle?.cleanup?.().catch(() => null);
-      displayHandle = null;
-      browserHandle = null;
+      let confirmed=true;
+      try{if(browserHandle)confirmed=await browserHandle.cleanup();}
+      finally{
+        const displayClosed=await closeQuietly(() => displayHandle?.cleanup?.());
+        confirmed=confirmed&&displayClosed;displayHandle=null;browserHandle=null;
+      }
+      return confirmed;
     },
   };
+  const sample=engine.run.bind(engine),closeBrowser=engine.close.bind(engine);
+  const policyCodes=new Set(['PROXY_REQUIRED','PROXY_POLICY_INVALID','PROXY_POLICY_CONFLICT','PROXY_CONFIGURATION_INVALID','PROXY_ACQUIRE_FAILED','PROXY_SUPPLIER_INVALID','PROXY_LEASE_INVALID','PROXY_LEASE_EXPIRED','PROXY_QUARANTINE_FAILED','PROXY_RELEASE_FAILED','PROXY_RECEIPT_FAILED','PROXY_CUSTODY_UNAVAILABLE','BROWSER_CLEANUP_UNCONFIRMED','BROWSER_RUN_IN_PROGRESS']);
+  const safeError=cause=>{
+    const code=policyCodes.has(cause?.code)?cause.code:'BROWSER_RUN_FAILED';
+    const error=Object.assign(new EngineError(code==='BROWSER_RUN_FAILED'?'Browser sample failed.':'Browser admission or cleanup failed.',{retriable:code==='BROWSER_RUN_FAILED'&&cause?.retriable===true}),{code});
+    if(code==='BROWSER_RUN_FAILED'||cause?.unknown===true)error.unknown=true;
+    return error;
+  };
+  async function retire(phase,reason=null){
+    const hadResources=Boolean(browserHandle||displayHandle||admission.proxy);let error,confirmed=false;
+    try{
+      try{confirmed=await closeBrowser();}catch{confirmed=false;}
+      if(!confirmed)reason='cleanup_unconfirmed';
+      try{if(hadResources)await admission.record({outcome:confirmed?'closed':'cleanup_unconfirmed',phase,reason});}catch(cause){error=cause;}
+      try{if(reason)await admission.quarantine(reason);}catch(cause){error??=cause;}
+      if(!confirmed)error??=Object.assign(new EngineError('Browser cleanup could not be confirmed.'),{code:'BROWSER_CLEANUP_UNCONFIRMED'});
+    }finally{try{await admission.release();}catch(cause){error??=cause;}}
+    if(error)throw safeError(error);
+  }
+  engine.run=async input=>{
+    if(running)throw Object.assign(new EngineError('A browser sample is already running.'),{code:'BROWSER_RUN_IN_PROGRESS'});
+    running=true;let result,error,reason=null,admitted=false;
+    try{
+      if(admission.expired)await retire('lease_expiry');
+      await admission.begin();admitted=true;
+      result=await sample(input);
+      if(contextCleanupFailed)throw Object.assign(new EngineError('Browser cleanup could not be confirmed.'),{code:'BROWSER_CLEANUP_UNCONFIRMED'});
+    }catch(cause){reason=proxyFailureReason(cause);error=safeError(cause);}
+    try{
+      if(admitted){
+        try{const receipt=await admission.record({outcome:error?'failed':result?.unknown?'unknown':'observed',reason});if(result)result.egressReceipt=receipt;}
+        catch(cause){error=safeError(cause);}
+        if(error){try{await retire('failure_cleanup',reason);}catch(cause){error=safeError(cause);}}
+      }
+    }finally{running=false;}
+    if(error)throw error;
+    return result;
+  };
+  engine.close=async()=>{
+    if(running)throw Object.assign(new EngineError('A browser sample is already running.'),{code:'BROWSER_RUN_IN_PROGRESS'});
+    running=true;
+    try{await retire('cleanup');}finally{running=false;}
+  };
+  engine.getEgressReceipts=admission.receipts;
+  return engine;
 }

package/src/citations/browser/proxy-admission.js

@@ -0,0 +1,120 @@
+// Local proxy custody. Supplier callbacks perform no work until browser admission.
+// Meter values are supplier-observed cumulative counters, never nominal estimates.
+import {createHash,randomUUID} from 'node:crypto';
+import {EngineError} from '../adapter.js';
+const digest=value=>createHash('sha256').update(value).digest('hex');
+const quarantines=new Map();
+const safeInteger=value=>Number.isSafeInteger(value)&&value>=0;
+const failure=(code,message)=>Object.assign(new EngineError(message),{code});
+export function parseProxyUrl(raw){
+ try{
+  if(typeof raw!=='string'||raw.length>8192)throw Error();
+  const url=new URL(raw);
+  if(!['http:','https:','socks5:'].includes(url.protocol)||!url.hostname||url.search||url.hash||(url.pathname&&url.pathname!=='/')||(url.protocol==='socks5:'&&!url.port))throw Error();
+  const username=decodeURIComponent(url.username),password=decodeURIComponent(url.password);
+  if(/[\r\n\0]/.test(username+password))throw Error();
+  return {server:`${url.protocol}//${url.hostname}${url.port?':'+url.port:''}`,...(username?{username}:{}),...(password?{password}:{})};
+ }catch{throw failure('PROXY_CONFIGURATION_INVALID','The browser proxy configuration is invalid.');}
+}
+export function createUrlProxySupplier({url,now=()=>Date.now()}={}){
+ const key=typeof url==='string'?digest(url):null;
+ return {
+  async acquire({engine}){
+   if(!url)throw failure('PROXY_REQUIRED','Configure a proxy before browser measurement, or explicitly select direct-diagnostic egress.');
+   parseProxyUrl(url);
+   if((quarantines.get(engine+key)??0)>now())throw failure('PROXY_QUARANTINED','The browser proxy is quarantined.');
+   return {id:randomUUID(),proxyUrl:url,expiresAt:new Date(now()+10*60*1000).toISOString()};
+  },
+  async quarantine({engine,reason}){quarantines.set(engine+key,reason==='cleanup_unconfirmed'?Infinity:now()+10*60*1000);},
+  async release(){},
+ };
+}
+// Only explicit structured signals identify a block. Empty answers/selector errors
+// do not establish a proxy problem, and arbitrary exception text is never retained.
+export function proxyFailureReason(error){
+ for(const value of [error,error?.cause]){
+  if(value?.status===403||value?.failureType==='bot_detection')return 'blocked';
+  if(value?.status===429||value?.failureType==='rate_limited')return 'rate_limited';
+  if(['ERR_PROXY_CONNECTION_FAILED','ECONNREFUSED','ECONNRESET','ETIMEDOUT'].includes(value?.code)||value?.failureType==='connection_error'||/\bERR_PROXY_CONNECTION_FAILED\b/.test(String(value?.message??'')))return 'connection_error';
+ }
+ return null;
+}
+export function createProxyAdmission({engine,env={},supplier,now=()=>Date.now(),onReceipt=()=>{},timeoutMs=5000}={}){
+ const mode=env.AGENTLINKOPS_BROWSER_EGRESS??'proxy-required';
+ if(!['proxy-required','direct-diagnostic'].includes(mode))throw failure('PROXY_POLICY_INVALID','Choose proxy-required or direct-diagnostic browser egress.');
+ if(mode==='direct-diagnostic'&&(supplier||env.AGENTLINKOPS_PROXY_URL))throw failure('PROXY_POLICY_CONFLICT','Direct diagnostics cannot also configure a proxy.');
+ const injected=Boolean(supplier);
+ supplier??=createUrlProxySupplier({url:env.AGENTLINKOPS_PROXY_URL,now});
+ let lease=null,baseline=null,poisoned=false;const receipts=[];
+ async function bounded(action,code){
+  let timer;
+  try{return await Promise.race([Promise.resolve().then(action),new Promise((_,reject)=>{timer=setTimeout(()=>reject(Error()),timeoutMs);})]);}
+  catch{throw failure(code,'Browser proxy custody failed. No direct fallback was attempted.');}
+  finally{clearTimeout(timer);}
+ }
+ async function meter(){
+  if(!lease||typeof supplier.readMeter!=='function')return null;
+  try{
+   const value=await bounded(()=>supplier.readMeter({engine,leaseId:lease.id}),'PROXY_METER_UNAVAILABLE');
+   if(!value||!safeInteger(value.bytes)||!(value.costMicrousd===null||value.costMicrousd===undefined||safeInteger(value.costMicrousd)))return null;
+   return {bytes:value.bytes,costMicrousd:value.costMicrousd??null};
+  }catch{return null;}
+ }
+ async function release(){
+  if(!lease)return;
+  const previous=lease;lease=null;baseline=null;
+  try{await bounded(()=>supplier.release({engine,leaseId:previous.id,disposition:poisoned?'quarantined':'clean'}),'PROXY_RELEASE_FAILED');}
+  catch(error){poisoned=true;throw error;}
+ }
+ return {
+  get proxy(){return lease?.proxy;},
+  get expired(){return lease&&Date.parse(lease.expiresAt)<=now();},
+  assertReady(){
+   if(poisoned)throw failure('PROXY_CUSTODY_UNAVAILABLE','Browser proxy custody needs operator review.');
+   if(mode==='proxy-required'&&(!lease||Date.parse(lease.expiresAt)<=now()))throw failure('PROXY_LEASE_EXPIRED','The browser proxy lease has expired.');
+  },
+  async begin(){
+   if(poisoned)throw failure('PROXY_CUSTODY_UNAVAILABLE','Browser proxy custody needs operator review.');
+   if(mode==='direct-diagnostic')return;
+   if(!injected&&!env.AGENTLINKOPS_PROXY_URL)throw failure('PROXY_REQUIRED','Configure a proxy before browser measurement, or explicitly select direct-diagnostic egress.');
+   if(lease){if(Date.parse(lease.expiresAt)<=now())throw failure('PROXY_LEASE_EXPIRED','The browser proxy lease has expired.');return;}
+   if(!['acquire','release','quarantine'].every(name=>typeof supplier?.[name]==='function'))throw failure('PROXY_SUPPLIER_INVALID','The browser proxy supplier is incomplete.');
+   let acquired;
+   const acquiring=Promise.resolve().then(()=>supplier.acquire({engine}));
+   try{acquired=await bounded(()=>acquiring,'PROXY_ACQUIRE_FAILED');}
+   catch(error){
+    poisoned=true;
+    // A timed-out acquisition can resolve later; retire that lease without launching.
+    acquiring.then(value=>{if(typeof value?.id==='string')return bounded(()=>supplier.release({engine,leaseId:value.id}),'PROXY_RELEASE_FAILED');}).catch(()=>{});
+    throw error;
+   }
+   try{
+    if(!acquired||typeof acquired.id!=='string'||!/^[A-Za-z0-9_-]{1,128}$/.test(acquired.id)||typeof acquired.expiresAt!=='string'||!Number.isFinite(Date.parse(acquired.expiresAt))||Date.parse(acquired.expiresAt)<=now())throw Error();
+    lease={id:acquired.id,expiresAt:acquired.expiresAt,proxy:parseProxyUrl(acquired.proxyUrl)};
+   }catch{
+    poisoned=true;
+    if(acquired&&typeof acquired.id==='string')await bounded(()=>supplier.release({engine,leaseId:acquired.id}),'PROXY_RELEASE_FAILED').catch(()=>{});
+    throw failure('PROXY_LEASE_INVALID','The browser proxy lease is invalid.');
+   }
+   baseline=await meter();
+   if(Date.parse(lease.expiresAt)<=now()){poisoned=true;await release();throw failure('PROXY_LEASE_EXPIRED','The browser proxy lease has expired.');}
+  },
+  async record({outcome,reason=null,phase='sample'}){
+   const current=await meter(),valid=baseline&&current&&current.bytes>=baseline.bytes;
+   const bytes=valid?current.bytes-baseline.bytes:null;
+   const costMicrousd=valid&&baseline.costMicrousd!==null&&current.costMicrousd!==null&&current.costMicrousd>=baseline.costMicrousd?current.costMicrousd-baseline.costMicrousd:null;
+   const row=Object.freeze({version:1,sequence:receipts.length+1,engine,egress:mode,phase,outcome,reason,leaseHash:lease?digest(lease.id):null,observedAt:new Date(now()).toISOString(),meterState:outcome==='cleanup_unconfirmed'?'incomplete':mode==='direct-diagnostic'?'not_applicable':bytes===null?'unavailable':costMicrousd===null?'bytes_only':'measured',bytes,costMicrousd});
+   baseline=current;receipts.push(row);
+   try{await bounded(()=>onReceipt({...row}),'PROXY_RECEIPT_FAILED');}catch(error){poisoned=true;throw error;}
+   return {...row};
+  },
+  async quarantine(reason){
+   // Stop this engine instance even if an external supplier cannot quarantine.
+   poisoned=true;
+   if(!lease)return;
+   await bounded(()=>supplier.quarantine({engine,leaseId:lease.id,reason}),'PROXY_QUARANTINE_FAILED');
+  },
+  release,
+  receipts:()=>receipts.map(row=>({...row})),
+ };
+}