agentlinkops 0.6.5 → 0.6.6

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agentlinkops",
-  "version": "0.6.5",
+  "version": "0.6.6",
   "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.5",
+  "version": "0.6.6",
   "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,13 @@
 All notable changes to the `agentlinkops` package are recorded here. The version follows the
 plugin manifests in `.claude-plugin/` and `.codex-plugin/`.
 
+## 0.6.6 (2026-09-20)
+
+- Retain supplied browser usage receipts in a bounded local journal after each attempt and cleanup. Missing meter values remain unknown; failed writes stop the run.
+- Close browser adapters after failed runs and admission errors. Cleanup uncertainty stays explicit in retained receipts.
+- Check citation files against their recorded observation hashes before freezing reports or uploading evidence. Changed or unreferenced files cannot silently add samples.
+- Include retained inspection-attempt status and rolling website quota in the command response schema.
+
 ## 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.

package/README.md

@@ -149,14 +149,15 @@ its sample size, classified against the previous epoch as declined, grown or
 not_distinguishable, or `insufficient_data` when n is too thin to interpret.
 
 ```sh
-export PERPLEXITY_API_KEY=...          # live engine; omit it and the mock engine runs at $0
+agentlinkops citation panel --domain example.com --brand Example --out panel.json
 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 runner reserves estimated cost before each call and retry. A reported supplier
+New panels use the free mock engine. A live engine requires its own configuration and credentials;
+missing credentials never select mock results. The JSON panel contains `targets`, `prompts`,
+`engines`, optional `samples` and `maxUsd`. Answer snapshots live in
+`.agentlinkops/citations/evidence/`; observation and epoch ledgers live at the `.agentlinkops/` root.
+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.
@@ -166,6 +167,16 @@ For an explicitly authorized direct diagnostic, set `AGENTLINKOPS_BROWSER_EGRESS
 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.
 
+Browser epochs retain supplied usage and cleanup receipts in
+`.agentlinkops/citations/egress/<epochId>.jsonl`. Unknown meter values stay null. A missing
+final record means the journal is incomplete; it does not establish complete costs or cleanup.
+Journals stop at 10,000 records or 8 MiB, and a failed write stops further samples.
+
+Frozen inventories and evidence uploads check files against their retained observation hashes.
+Historical hashes verify the recorded answer fields and screenshot filename; they do not prove
+when an answer was captured or authenticate old screenshot pixels. Hosted uploads retain a
+separate hash of the exact uploaded file bytes.
+
 ## Environment variables
 
 | Variable | Purpose |

package/cli/catalog.js

@@ -14687,6 +14687,111 @@ export const CATALOG_COMMANDS = [
        "type": "null"
       }
      ]
+    },
+    "attemptSummary": {
+     "type": "object",
+     "properties": {
+      "observedAt": {
+       "type": "string"
+      },
+      "latestAttempt": {
+       "anyOf": [
+        {
+         "type": "object",
+         "properties": {
+          "id": {
+           "type": "string",
+           "pattern": "^[a-f0-9]{64}$"
+          },
+          "admittedAt": {
+           "type": "string"
+          },
+          "status": {
+           "type": "string",
+           "enum": [
+            "in_progress",
+            "unsettled",
+            "completed"
+           ]
+          },
+          "receiptId": {
+           "anyOf": [
+            {
+             "type": "string",
+             "pattern": "^[a-f0-9]{64}$"
+            },
+            {
+             "type": "null"
+            }
+           ]
+          },
+          "leaseExpiresAt": {
+           "type": [
+            "string",
+            "null"
+           ]
+          }
+         },
+         "required": [
+          "id",
+          "admittedAt",
+          "status",
+          "receiptId",
+          "leaseExpiresAt"
+         ],
+         "additionalProperties": false
+        },
+        {
+         "type": "null"
+        }
+       ]
+      },
+      "unsettledCount": {
+       "type": "integer",
+       "minimum": 0,
+       "maximum": 9007199254740991
+      }
+     },
+     "required": [
+      "observedAt",
+      "latestAttempt",
+      "unsettledCount"
+     ],
+     "additionalProperties": false
+    },
+    "websiteQuota": {
+     "type": "object",
+     "properties": {
+      "windowStart": {
+       "type": "string"
+      },
+      "observedAt": {
+       "type": "string"
+      },
+      "admitted": {
+       "type": "integer",
+       "minimum": 0,
+       "maximum": 9007199254740991
+      },
+      "limit": {
+       "type": "integer",
+       "exclusiveMinimum": 0,
+       "maximum": 9007199254740991
+      },
+      "remaining": {
+       "type": "integer",
+       "minimum": 0,
+       "maximum": 9007199254740991
+      }
+     },
+     "required": [
+      "windowStart",
+      "observedAt",
+      "admitted",
+      "limit",
+      "remaining"
+     ],
+     "additionalProperties": false
     }
    },
    "required": [

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.5';
+export const CLI_VERSION = '0.6.6';
 export const CLI_USER_AGENT = `agentlinkops-cli/${CLI_VERSION}`;
 export class CloudError extends Error {
   constructor(code, status, details = null) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentlinkops",
-  "version": "0.6.5",
+  "version": "0.6.6",
   "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/shared/index-observation-contract.js

@@ -10,5 +10,7 @@ export const indexSettingsResponse=z.object({projectId:id,enabled:z.boolean(),da
 export const indexObservation=z.looseObject({id:digest,observationId:id,checkedAt:time,recordedAt:time,expiresAt:time,evidenceSha256:digest,eventId:digest.nullable(),ignored:z.string().nullable(),version:z.literal(1),url:z.url(),lane:z.enum(['gsc','licensed_site']),backend:z.string(),source_key:z.string(),tier:z.enum(['indexed','not_indexed','likely_indexed','not_found_in_site_query','unknown']),confidence:z.enum(['google_index_snapshot','search_result_sample','unknown']),reason:z.string(),live_page_test:z.literal(false),submission_requested:z.literal(false)});
 export const indexReceiptResponse=z.object({observation:indexObservation,rawResponse:z.unknown(),evidenceAvailable:z.boolean()}).passthrough();
 export const indexInspectResponse=indexReceiptResponse.extend({replayed:z.boolean(),providerError:z.enum(['PROVIDER_PERMISSION_LOST','PROVIDER_RATE_LIMITED','PROVIDER_UNAVAILABLE','PROVIDER_RESPONSE_INVALID']).nullable().optional()});
-export const indexHistoryResponse=z.object({observations:z.array(indexObservation),nextCursor:digest.nullable()}).passthrough();
+export const indexAttemptSummary=z.object({observedAt:time,latestAttempt:z.object({id:digest,admittedAt:time,status:z.enum(['in_progress','unsettled','completed']),receiptId:digest.nullable(),leaseExpiresAt:time.nullable()}).nullable(),unsettledCount:z.number().int().nonnegative()});
+export const indexWebsiteQuota=z.object({windowStart:time,observedAt:time,admitted:z.number().int().nonnegative(),limit:z.number().int().positive(),remaining:z.number().int().nonnegative()});
+export const indexHistoryResponse=z.object({observations:z.array(indexObservation),nextCursor:digest.nullable(),attemptSummary:indexAttemptSummary.optional(),websiteQuota:indexWebsiteQuota.optional()}).passthrough();
 export const indexEventsResponse=z.object({events:z.array(z.looseObject({id:digest,receiptId:digest,type:z.enum(['index.deindexed','index.reindexed']),createdAt:time,url:z.url(),source_key:z.string(),before:z.enum(['indexed','not_indexed']),after:z.enum(['indexed','not_indexed']),observation_ids:z.array(id)}))}).passthrough();

package/skills/agentlinkops-connect/references/agentlinkops.md

@@ -9,7 +9,7 @@ records. This page is the complete agent reference: the same text prints from
 full once per session, then use `describe` for any command's exact schema.
 
 <!-- generated:skill-version begin (npm run generate:tools) -->
-Pack version 0.6.3. 125 commands in 13 toolsets.
+Pack version 0.6.5. 125 commands in 13 toolsets.
 <!-- generated:skill-version end -->
 
 ## Install and connect (once per machine)

package/src/citations/egress-receipts.js

@@ -0,0 +1,80 @@
+// Supplemental operational evidence; never part of citation-envelope hashes.
+import { open, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { EngineError } from './adapter.js';
+export const EGRESS_LIMITS = Object.freeze({ rows: 10000, bytes: 8 * 1024 * 1024 });
+const fail = code => Object.assign(new EngineError('Egress evidence could not be persisted; the epoch stopped.'), { code });
+const codes = 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_QUARANTINED','PROXY_QUARANTINE_FAILED','PROXY_RELEASE_FAILED','PROXY_RECEIPT_FAILED','PROXY_CUSTODY_UNAVAILABLE','BROWSER_CLEANUP_UNCONFIRMED','BROWSER_RUN_IN_PROGRESS','BROWSER_RUN_FAILED']);
+const safeCode = error => error ? codes.has(error.code) ? error.code : 'ENGINE_ERROR' : null;
+const enumeration = (value, values) => { if (!values.includes(value)) throw fail('EGRESS_RECEIPT_INVALID'); return value; };
+const count = value => { if (!Number.isSafeInteger(value) || value < 0) throw fail('EGRESS_RECEIPT_INVALID'); return value; };
+function sanitize(row) {
+  if (!row || row.version !== 1 || count(row.sequence) < 1) throw fail('EGRESS_RECEIPT_INVALID');
+  const observedAt = typeof row.observedAt === 'string' && row.observedAt.length <= 35 ? new Date(row.observedAt) : null;
+  if (!observedAt || !Number.isFinite(observedAt.getTime())) throw fail('EGRESS_RECEIPT_INVALID');
+  if (row.leaseHash !== null && !/^[a-f0-9]{64}$/.test(row.leaseHash ?? '')) throw fail('EGRESS_RECEIPT_INVALID');
+  const meterState = enumeration(row.meterState, ['measured','bytes_only','unavailable','not_applicable','incomplete']);
+  const bytes = row.bytes === null ? null : count(row.bytes);
+  const costMicrousd = row.costMicrousd === null ? null : count(row.costMicrousd);
+  if ((meterState === 'measured' && (bytes === null || costMicrousd === null)) || (meterState === 'bytes_only' && (bytes === null || costMicrousd !== null)) || (['unavailable','not_applicable'].includes(meterState) && (bytes !== null || costMicrousd !== null))) throw fail('EGRESS_RECEIPT_INVALID');
+  return { version: 1, sequence: row.sequence,
+    egress: enumeration(row.egress, ['proxy-required','direct-diagnostic']),
+    phase: enumeration(row.phase, ['sample','cleanup','failure_cleanup','lease_expiry']),
+    outcome: enumeration(row.outcome, ['observed','unknown','failed','closed','cleanup_unconfirmed']),
+    reason: enumeration(row.reason, [null,'blocked','rate_limited','connection_error','cleanup_unconfirmed']),
+    leaseHash: row.leaseHash, observedAt: observedAt.toISOString(), meterState, bytes, costMicrousd };
+}
+
+export async function createEgressJournal({ dir, epochId, engines, identityHashes = new Map(), limits = EGRESS_LIMITS }) {
+  if (typeof epochId !== 'string' || !/^[A-Za-z0-9_-]{1,100}$/.test(epochId)) throw fail('EGRESS_JOURNAL_UNAVAILABLE');
+  const tracked = new Map(engines.map((engine, index) => [engine, { index, retained: [] }]));
+  if (!tracked.size) return null;
+  if (!Number.isSafeInteger(limits.rows) || limits.rows < 1 || !Number.isSafeInteger(limits.bytes) || limits.bytes < 1) throw fail('EGRESS_LIMIT_INVALID');
+  // A reusable adapter may retain earlier epochs in memory. Establish the cursor
+  // before this epoch's first request; never count or rewrite those older deltas.
+  for (const [engine, state] of tracked) {
+    try {
+      const prior = engine.getEgressReceipts?.() ?? [];
+      if (!Array.isArray(prior) || prior.length > limits.rows) throw fail('EGRESS_RECEIPT_LIMIT');
+      state.retained = prior.map((row, index) => {
+        const value = sanitize(row);
+        if (value.sequence !== index + 1) throw fail('EGRESS_RECEIPT_INVALID');
+        return JSON.stringify(value);
+      });
+    } catch { throw fail('EGRESS_RECEIPT_UNAVAILABLE'); }
+  }
+  let file;
+  try { await mkdir(join(dir, 'citations/egress'), { recursive: true }); file = await open(join(dir, 'citations/egress', `${epochId}.jsonl`), 'wx', 0o600); }
+  catch { throw fail('EGRESS_JOURNAL_UNAVAILABLE'); }
+  let rows = 0, bytes = 0;
+  async function append(row) {
+    const text = JSON.stringify(row) + '\n', size = Buffer.byteLength(text);
+    if (rows + 1 > limits.rows || bytes + size > limits.bytes) throw fail('EGRESS_RECEIPT_LIMIT');
+    try { await file.writeFile(text); await file.sync(); }
+    catch { throw fail('EGRESS_WRITE_FAILED'); }
+    rows++; bytes += size;
+  }
+  try { await append({ type: 'start', version: 1, epochId, engines: [...tracked].map(([engine, state]) => ({ engineIndex: state.index, firstSequence: state.retained.length + 1, identityHash: /^[a-f0-9]{64}$/.test(identityHashes.get(engine) ?? '') ? identityHashes.get(engine) : null })), completeness: 'open', costBasis: 'supplier_meter_only', totals: null }); }
+  catch (error) { await file.close().catch(() => {}); throw error; }
+  return {
+    async capture(engine, { phase, error = null, cellHash = null, runIndex = null, attempt = null } = {}) {
+      const state = tracked.get(engine); if (!state) return;
+      if (cellHash !== null && !/^[a-f0-9]{64}$/.test(cellHash)) throw fail('EGRESS_RECEIPT_INVALID');
+      if (runIndex !== null) count(runIndex);
+      if (attempt !== null) count(attempt);
+      let receipts;
+      try { receipts = engine.getEgressReceipts?.() ?? []; }
+      catch { throw fail('EGRESS_RECEIPT_UNAVAILABLE'); }
+      if (!Array.isArray(receipts) || receipts.length > limits.rows || receipts.length < state.retained.length) throw fail('EGRESS_RECEIPT_LIMIT');
+      for (let i = 0; i < receipts.length; i++) {
+        const receipt = sanitize(receipts[i]), serialized = JSON.stringify(receipt);
+        if (receipt.sequence !== i + 1 || (i < state.retained.length && state.retained[i] !== serialized)) throw fail('EGRESS_RECEIPT_INVALID');
+        if (i < state.retained.length) continue;
+        await append({ type: 'receipt', engineIndex: state.index, receipt }); state.retained.push(serialized);
+      }
+      await append({ type: 'status', engineIndex: state.index, phase: enumeration(phase, ['attempt','cleanup']), outcome: error ? 'error' : 'returned', code: safeCode(error), cellHash, runIndex, attempt, receiptsAvailable: typeof engine.getEgressReceipts === 'function' });
+    },
+    async finish({ failed, cleanupUncertain, evidenceComplete }) { await append({ type: 'finish', outcome: failed ? 'failed' : 'returned', cleanupUncertain, evidenceComplete, totals: null }); },
+    async close() { try { await file.close(); } catch { throw fail('EGRESS_WRITE_FAILED'); } },
+  };
+}

package/src/citations/evidence-integrity.js

@@ -0,0 +1,51 @@
+import { createHash } from 'node:crypto';
+const hash = value => createHash('sha256').update(value).digest('hex');
+
+function suppliedFieldsPreserved(raw, parsed) {
+  if (raw === null || typeof raw !== 'object') return Object.is(raw, parsed);
+  if (Array.isArray(raw)) return Array.isArray(parsed) && raw.length === parsed.length && raw.every((value, index) => suppliedFieldsPreserved(value, parsed[index]));
+  return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) &&
+    Object.keys(raw).every(key => Object.hasOwn(parsed, key) && suppliedFieldsPreserved(raw[key], parsed[key]));
+}
+
+// Historical files were written by JSON.stringify. Retain whitespace and key
+// order compatibility, but reject duplicate keys and alternate encodings that
+// JSON.parse would discard before semantic reconstruction. Quoted whitespace
+// remains part of its token. This is not a replacement JSON grammar parser.
+function canonicalEncoding(text, raw) {
+  return (text.match(/"(?:\\[\s\S]|[^"\\])*"|[^\s]/g) ?? []).join('') === JSON.stringify(raw);
+}
+
+// The v1 runner hashes its construction-order object BEFORE schema parsing and
+// before adding screenshot_file. Do not rename or rewrite those historical files.
+export function verifyLocalEvidenceDigest({ envelope, text, digest }) {
+  if (!envelope || typeof text !== 'string' || !/^[a-f0-9]{64}$/.test(digest ?? '')) return false;
+  try {
+    const raw = JSON.parse(text);
+    if (!suppliedFieldsPreserved(raw, envelope) || !canonicalEncoding(text, raw)) return false;
+  } catch { return false; }
+  if (envelope.screenshot_file && envelope.screenshot_file !== `${digest}.screenshot.png`) return false;
+  if (hash(text) === digest) return true;
+  const original = {
+    schema_version: envelope.schema_version, epoch_id: envelope.epoch_id,
+    cell_id: envelope.cell_id, run_index: envelope.run_index, prompt: envelope.prompt,
+    engine_identity: envelope.engine_identity,
+    ...(envelope.locale_context ? { locale_context: envelope.locale_context } : {}),
+    provider_model_version: envelope.provider_model_version,
+    answer: envelope.answer, citations: envelope.citations, fan_out: envelope.fan_out,
+    usage: envelope.usage, cost_estimate_usd: envelope.cost_estimate_usd, at: envelope.at,
+    ...(envelope.provenance ? { provenance: envelope.provenance } : {}),
+    ...(envelope.browser_context ? { browser_context: envelope.browser_context } : {}),
+    ...(envelope.failure ? { failure: envelope.failure } : {}),
+  };
+  // Token counts default to zero at schema parse. Try only those lossless zero
+  // defaults, not arbitrary omitted evidence or alternative citation contents.
+  for (const omitInput of [false, true]) for (const omitOutput of [false, true]) {
+    if ((omitInput && envelope.usage.input_tokens !== 0) || (omitOutput && envelope.usage.output_tokens !== 0)) continue;
+    const usage = { ...envelope.usage };
+    if (omitInput) delete usage.input_tokens;
+    if (omitOutput) delete usage.output_tokens;
+    if (hash(JSON.stringify({ ...original, usage })) === digest) return true;
+  }
+  return false;
+}

package/src/citations/inventory.js

@@ -1,20 +1,45 @@
 import { readFile, readdir, lstat, realpath } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { createHash } from 'node:crypto';
-import { citationPanelSchema, evidenceEnvelopeSchema, targetKey } from './contract.js';
+import { citationPanelSchema, evidenceEnvelopeSchema, observationRowSchema, targetKey } from './contract.js';
 import { panelEpochs } from './report.js';
+import { verifyLocalEvidenceDigest } from './evidence-integrity.js';
 import { analyzeRetainedAnswer } from './match.js';
 import { parseOpportunityRecord, opportunityRecordId, ELIGIBILITY_GATES } from '../../shared/opportunity-record.js';
 const hash = value => createHash('sha256').update(value).digest('hex');
 
+async function observationReferences(root, epochId, cells) {
+  const path = join(root, 'citations-observations.jsonl');
+  let text;
+  try {
+    if (!(await lstat(path)).isFile() || !(await realpath(path)).startsWith(root + '/')) throw new Error('Unsafe observation ledger');
+    text = await readFile(path, 'utf8');
+  } catch (error) { if (error.code === 'ENOENT') return new Map(); throw error; }
+  const references = new Map();
+  for (const line of text.split('\n').filter(line => line.trim())) {
+    let raw;
+    try { raw = JSON.parse(line); } catch { throw new Error('Invalid observation ledger JSON'); }
+    if (raw.epoch_id !== epochId || !cells.some(cell => cell.cell_id === raw.cell_id)) continue;
+    const parsed = observationRowSchema.safeParse(raw);
+    if (!parsed.success || !/^[a-f0-9]{64}$/.test(parsed.data.evidence_sha256)) throw new Error('Invalid retained observation reference');
+    const row = parsed.data, identity = `${row.cell_id}|${row.run_index}`;
+    const previous = references.get(identity);
+    if (previous && JSON.stringify(previous) !== JSON.stringify(row)) throw new Error('Conflicting retained observation identity');
+    references.set(identity, row);
+  }
+  return references;
+}
+
 export async function freezeCitationInventory({ dir, panel: input, epochId }) {
   const panel = citationPanelSchema.parse(input);
   const epochs = await panelEpochs({ dir, panel });
   const cells = epochId ? epochs.find(rows => rows[0]?.epoch_id === epochId) : epochs[0];
   if (!cells) throw new Error('No matching panel epoch to freeze');
+  if (cells.some(cell => !Number.isSafeInteger(cell.n) || cell.n < 0 || !Number.isSafeInteger(cell.unknowns) || cell.unknowns < 0 || !Number.isSafeInteger(cell.n + cell.unknowns))) throw new Error('Invalid retained epoch sample counts');
   epochId = cells[0].epoch_id;
   if (!/^[A-Za-z0-9_.-]+$/.test(epochId) || ['.', '..'].includes(epochId)) throw new Error('Invalid epoch reference');
   const root = await realpath(resolve(dir)); const evidenceDir = join(root, 'citations/evidence', epochId);
+  const references = await observationReferences(root, epochId, cells);
   let files = [];
   try {
     if (!(await lstat(evidenceDir)).isDirectory() || !(await realpath(evidenceDir)).startsWith(root + '/')) throw new Error('Unsafe evidence directory');
@@ -28,21 +53,26 @@ export async function freezeCitationInventory({ dir, panel: input, epochId }) {
     let envelope, text;
     try { text = await readFile(path, 'utf8'); envelope = evidenceEnvelopeSchema.parse(JSON.parse(text)); }
     catch { invalid++; continue; }
-    if (envelope.epoch_id !== epochId || !cells.some(cell => cell.cell_id === envelope.cell_id)) continue;
+    const cell = cells.find(cell => cell.cell_id === envelope.cell_id);
+    if (envelope.epoch_id !== epochId || !cell) { invalid++; continue; }
     const identity = `${envelope.cell_id}|${envelope.run_index}`;
+    const reference = references.get(identity), digest = file.slice(0, -5);
+    if (!reference || reference.evidence_sha256 !== digest || envelope.run_index >= cell.n + cell.unknowns ||
+        !verifyLocalEvidenceDigest({ envelope, text, digest })) { invalid++; continue; }
     if (identities.has(identity)) throw new Error('Duplicate observation identity in retained evidence'); identities.add(identity);
     const [, promptId, key] = envelope.cell_id.split('|');
     const target = panel.targets.find(target => targetKey(target) === key);
     if (!target) continue;
     const prompt = panel.prompts.find(prompt => { const id = prompt.id ?? hash(prompt.text).slice(0, 10); return id === promptId || promptId?.startsWith(`${id}@`); });
-    const analysis = envelope.engine_identity.startsWith('google-aio:') && !envelope.provenance ? { mentioned: null, cited: null, outcome: 'unknown' } : analyzeRetainedAnswer(target, envelope);
+    if (!prompt || prompt.text !== envelope.prompt || envelope.engine_identity !== envelope.cell_id.split('|')[0]) { invalid++; continue; }
+    const analysis = reference.outcome === 'unknown' || (envelope.engine_identity.startsWith('google-aio:') && !envelope.provenance) ? { mentioned: null, cited: null, outcome: 'unknown' } : analyzeRetainedAnswer(target, envelope);
     observations.push({ cell_id: envelope.cell_id, run_index: envelope.run_index, engine_identity: envelope.engine_identity,
       prompt_id: promptId, prompt: envelope.prompt, headline_eligible: !prompt?.branded, prompt_provenance: prompt?.provenance ?? null,
       intent_cluster: prompt?.intent_cluster ?? null, target: key, observed_at: envelope.at,
       provider_model_version: envelope.provider_model_version, locale_context: envelope.locale_context ?? null,
       mentioned: analysis.mentioned, cited: analysis.cited, outcome: analysis.outcome,
       citations: analysis.outcome === 'unknown' ? [] : envelope.citations,
-      evidence_sha256: hash(text), fixture: envelope.engine_identity.startsWith('mock:') });
+      evidence_sha256: hash(text), local_evidence_sha256: digest, fixture: envelope.engine_identity.startsWith('mock:') });
   }
   const expected = cells.reduce((count, cell) => count + (cell.n ?? 0) + (cell.unknowns ?? 0), 0);
   const payload = { schema_version: 1, kind: 'frozen_citation_inventory', epoch_id: epochId, frozen_at: new Date().toISOString(),

package/src/citations/runner.js

@@ -14,6 +14,7 @@ import { citationPanelSchema, engineIdentity, cellId, targetKey, panelLocaleCont
 import { classifyOutcome, analyzeRetainedAnswer } from './match.js';
 import { wilsonInterval, smoothedRate, classifyEpoch, tallyOutcomes, confidenceSequence, compareEpochs, changepointPosterior } from './stats.js';
 import { EngineError } from './adapter.js';
+import { createEgressJournal } from './egress-receipts.js';
 
 const sha256 = (text) => createHash('sha256').update(text).digest('hex');
 const nowIso = () => new Date().toISOString();
@@ -50,157 +51,178 @@ async function readPriorEpochs(dir) {
  * Retriable failures receive one retry; exhausted attempts remain unknown.
  */
 export async function runEpoch(panelInput, options = {}) {
-  const panel = citationPanelSchema.parse(panelInput);
-  const dir = options.dir ?? '.agentlinkops';
-  const now = options.now ?? new Date();
-  const samples = panel.samples ?? CITATION_LIMITS.defaultSamples;
-  const maxUsd = panel.maxUsd ?? CITATION_LIMITS.defaultMaxUsd;
-  const delayMs = options.delayMs ?? 0; // mock/tests: 0; live callers pass pacing
+  // Supplied adapters transfer epoch cleanup responsibility to this runner.
+  const uniqueEngines = [...new Set(options.engines?.values() ?? [])];
+  let journal, primaryError;
+  try {
+    const panel = citationPanelSchema.parse(panelInput);
+    const dir = options.dir ?? '.agentlinkops';
+    const now = options.now ?? new Date();
+    const samples = panel.samples ?? CITATION_LIMITS.defaultSamples;
+    const maxUsd = panel.maxUsd ?? CITATION_LIMITS.defaultMaxUsd;
+    const delayMs = options.delayMs ?? 0; // mock/tests: 0; live callers pass pacing
 
-  const epochId = `${now.toISOString().slice(0, 10)}-${sha256(JSON.stringify({ panel, at: now.toISOString() })).slice(0, 10)}`;
-  const evidenceRoot = join(dir, CITATION_FILES.evidenceDir, epochId);
-  await mkdir(evidenceRoot, { recursive: true });
+    const epochId = `${now.toISOString().slice(0, 10)}-${sha256(JSON.stringify({ panel, at: now.toISOString() })).slice(0, 10)}`;
+    const evidenceRoot = join(dir, CITATION_FILES.evidenceDir, epochId);
+    await mkdir(evidenceRoot, { recursive: true });
 
-  const cells = [];
-  for (const engineSpec of panel.engines) {
-    const identity = engineIdentity(engineSpec);
-    const engine = options.engines?.get(identity);
-    const context = panelLocaleContext(panel, engineSpec);
-    if ((context.locale !== 'en-US' || context.country !== 'US') && !['mock', 'google-aio'].includes(engineSpec.engine)) throw new EngineError('this engine has only an unverified en-US/US context; use mock or a configured supplier for locale variants');
-    if (!engine) throw new EngineError(`no engine instance provided for ${identity}`);
-    for (const prompt of panel.prompts) {
-      for (const target of panel.targets) {
-        cells.push({ identity, prompt, target, engine, context, id: cellId(identity, localizedPromptId(prompt.id ?? sha256(prompt.text).slice(0, 10), context), targetKey(target)) });
+    const cells = [];
+    for (const engineSpec of panel.engines) {
+      const identity = engineIdentity(engineSpec);
+      const engine = options.engines?.get(identity);
+      const context = panelLocaleContext(panel, engineSpec);
+      if ((context.locale !== 'en-US' || context.country !== 'US') && !['mock', 'google-aio'].includes(engineSpec.engine)) throw new EngineError('this engine has only an unverified en-US/US context; use mock or a configured supplier for locale variants');
+      if (!engine) throw new EngineError(`no engine instance provided for ${identity}`);
+      for (const prompt of panel.prompts) {
+        for (const target of panel.targets) {
+          cells.push({ identity, prompt, target, engine, context, id: cellId(identity, localizedPromptId(prompt.id ?? sha256(prompt.text).slice(0, 10), context), targetKey(target)) });
+        }
       }
     }
-  }
 
-  let spent = 0;
-  let aborted = null;
-  const observationRows = [];
-  const outcomesByCell = new Map(cells.map((c) => [c.id, []]));
+    let spent = 0;
+    let aborted = null;
+    const observationRows = [];
+    const outcomesByCell = new Map(cells.map((c) => [c.id, []]));
 
-  outer:
-  for (const cell of cells) {
-    for (let runIndex = 0; runIndex < samples; runIndex += 1) {
-      const estimate = cell.engine.estimateCostUsd?.() ?? 0;
-      if (!Number.isFinite(estimate) || estimate < 0) throw new EngineError('engine cost estimate must be a finite nonnegative number');
-      let run = null, lastCause = null, attemptCost = 0;
-      for (let attempt = 0; attempt < 2 && !run; attempt += 1) {
-        // Reserve each attempt, including retries, before calling a supplier.
-        if (spent + estimate > maxUsd) {
-          aborted = { reason: 'budget', spent, nextEstimate: estimate, maxUsd };
-          break;
+    const browserEngines = uniqueEngines.filter(engine => typeof engine.getEgressReceipts === 'function' || cells.some(cell => cell.engine === engine && cell.identity.includes(':web-own-browser')));
+    journal = await createEgressJournal({ dir, epochId, engines: browserEngines, identityHashes: new Map(cells.map(cell => [cell.engine, sha256(cell.identity)])) });
+    outer:
+    for (const cell of cells) {
+      for (let runIndex = 0; runIndex < samples; runIndex += 1) {
+        const estimate = cell.engine.estimateCostUsd?.() ?? 0;
+        if (!Number.isFinite(estimate) || estimate < 0) throw new EngineError('engine cost estimate must be a finite nonnegative number');
+        let run = null, lastCause = null, attemptCost = 0;
+        for (let attempt = 0; attempt < 2 && !run; attempt += 1) {
+          // Reserve each attempt, including retries, before calling a supplier.
+          if (spent + estimate > maxUsd) {
+            aborted = { reason: 'budget', spent, nextEstimate: estimate, maxUsd };
+            break;
+          }
+          spent += estimate;
+          attemptCost += estimate;
+          let attemptError;
+          try {
+            run = await cell.engine.run({ prompt: cell.prompt.text, runIndex, localeContext: cell.context, maxCostUsd: estimate || maxUsd - spent });
+            const actual = run.costEstimateUsd ?? estimate;
+            if (!Number.isFinite(actual) || actual < 0) throw new EngineError('engine returned an invalid cost');
+            spent += actual - estimate;
+            attemptCost += actual - estimate;
+            if (spent > maxUsd) aborted = { reason: 'supplier_cost_exceeded', spent, maxUsd };
+          } catch (cause) {
+            attemptError = cause;
+            run = null;
+            lastCause = cause;
+            // Failed or timed-out requests may already be billed. Keep the
+            // reservation unless the supplier reports a greater charge.
+            const charged = Number.isFinite(cause?.costEstimateUsd) ? Math.max(estimate, cause.costEstimateUsd) : estimate;
+            spent += charged - estimate;
+            attemptCost += charged - estimate;
+            if (spent > maxUsd) aborted = { reason: 'supplier_cost_exceeded', spent, maxUsd };
+            if (!(cause instanceof EngineError) || (!cause.retriable && !cause.unknown)) throw cause;
+            if (!cause.retriable || aborted) break;
+            if (options.err && attempt === 0) options.err(`retrying observation (${cell.id}): ${cause.message}`);
+          } finally {
+            await journal?.capture(cell.engine, { phase: 'attempt', error: attemptError, cellHash: sha256(cell.id), runIndex, attempt });
+          }
         }
-        spent += estimate;
-        attemptCost += estimate;
-        try {
-          run = await cell.engine.run({ prompt: cell.prompt.text, runIndex, localeContext: cell.context, maxCostUsd: estimate || maxUsd - spent });
-          const actual = run.costEstimateUsd ?? estimate;
-          if (!Number.isFinite(actual) || actual < 0) throw new EngineError('engine returned an invalid cost');
-          spent += actual - estimate;
-          attemptCost += actual - estimate;
-          if (spent > maxUsd) aborted = { reason: 'supplier_cost_exceeded', spent, maxUsd };
-        } catch (cause) {
-          run = null;
-          lastCause = cause;
-          // Failed or timed-out requests may already be billed. Keep the
-          // reservation unless the supplier reports a greater charge.
-          const charged = Number.isFinite(cause?.costEstimateUsd) ? Math.max(estimate, cause.costEstimateUsd) : estimate;
-          spent += charged - estimate;
-          attemptCost += charged - estimate;
-          if (spent > maxUsd) aborted = { reason: 'supplier_cost_exceeded', spent, maxUsd };
-          if (!(cause instanceof EngineError) || (!cause.retriable && !cause.unknown)) throw cause;
-          if (!cause.retriable || aborted) break;
-          if (options.err && attempt === 0) options.err(`retrying observation (${cell.id}): ${cause.message}`);
+        if (!run) {
+          if (!lastCause && aborted) break outer;
+          if (options.err) options.err(`unknown observation (${cell.id}): ${lastCause?.message ?? 'unspecified'}`);
+          run = { engine: cell.engine.identity?.engine ?? 'unknown', model: cell.engine.identity?.model ?? 'unknown', answer: '', citations: [], unknown: true,
+            provenance: lastCause?.provenance, failure: { code: lastCause?.code ?? 'ENGINE_UNAVAILABLE', message: lastCause?.message ?? 'Engine unavailable' } };
         }
-      }
-      if (!run) {
-        if (!lastCause && aborted) break outer;
-        if (options.err) options.err(`unknown observation (${cell.id}): ${lastCause?.message ?? 'unspecified'}`);
-        run = { engine: cell.engine.identity?.engine ?? 'unknown', model: cell.engine.identity?.model ?? 'unknown', answer: '', citations: [], unknown: true,
-          provenance: lastCause?.provenance, failure: { code: lastCause?.code ?? 'ENGINE_UNAVAILABLE', message: lastCause?.message ?? 'Engine unavailable' } };
-      }
-      run.costEstimateUsd = attemptCost;
+        run.costEstimateUsd = attemptCost;
 
-      const envelope = {
-        schema_version: CITATIONS_VERSION,
-        epoch_id: epochId, cell_id: cell.id, run_index: runIndex, prompt: cell.prompt.text,
-        engine_identity: cell.identity,
-        locale_context: cell.context,
-        provider_model_version: run.providerModelVersion ?? `${run.engine}:${run.model}`,
-        answer: run.answer, citations: run.citations, fan_out: run.fanOut ?? [],
-        usage: run.usage ?? { input_tokens: 0, output_tokens: 0 },
-        cost_estimate_usd: run.costEstimateUsd ?? 0,
-        at: nowIso(),
-        ...(run.provenance ? { provenance: run.provenance } : {}),
-        ...(run.browserContext ? { browser_context: run.browserContext } : {}),
-        ...(run.failure ? { failure: run.failure } : {}),
-      };
-      const digest = sha256(JSON.stringify(envelope));
-      // The screenshot is a sibling of the envelope: same content-addressed
-      // directory, named by the envelope digest it belongs to. An observation
-      // of a rendered surface carries the pixels of that surface.
-      if (run.screenshotPng) {
-        const shotName = `${digest}.screenshot.png`;
-        await writeFile(join(evidenceRoot, shotName), run.screenshotPng);
-        envelope.screenshot_file = shotName;
-      }
-      await writeFile(join(evidenceRoot, `${digest}.json`), JSON.stringify(evidenceEnvelopeSchema.parse(envelope)), 'utf8');
+        const envelope = {
+          schema_version: CITATIONS_VERSION,
+          epoch_id: epochId, cell_id: cell.id, run_index: runIndex, prompt: cell.prompt.text,
+          engine_identity: cell.identity,
+          locale_context: cell.context,
+          provider_model_version: run.providerModelVersion ?? `${run.engine}:${run.model}`,
+          answer: run.answer, citations: run.citations, fan_out: run.fanOut ?? [],
+          usage: run.usage ?? { input_tokens: 0, output_tokens: 0 },
+          cost_estimate_usd: run.costEstimateUsd ?? 0,
+          at: nowIso(),
+          ...(run.provenance ? { provenance: run.provenance } : {}),
+          ...(run.browserContext ? { browser_context: run.browserContext } : {}),
+          ...(run.failure ? { failure: run.failure } : {}),
+        };
+        const digest = sha256(JSON.stringify(envelope));
+        // The screenshot is a sibling of the envelope: same content-addressed
+        // directory, named by the envelope digest it belongs to. An observation
+        // of a rendered surface carries the pixels of that surface.
+        if (run.screenshotPng) {
+          const shotName = `${digest}.screenshot.png`;
+          await writeFile(join(evidenceRoot, shotName), run.screenshotPng);
+          envelope.screenshot_file = shotName;
+        }
+        await writeFile(join(evidenceRoot, `${digest}.json`), JSON.stringify(evidenceEnvelopeSchema.parse(envelope)), 'utf8');
 
-      const tiered = run.unknown ? { outcome: 'unknown', citedUrls: [], verify: 'unknown' } : classifyOutcome(cell.target, run, options.verifyFetch ?? null);
-      const analysis = analyzeRetainedAnswer(cell.target, run);
-      outcomesByCell.get(cell.id).push(tiered.outcome);
-      observationRows.push(observationRowSchema.parse({
-        schema_version: CITATIONS_VERSION, epoch_id: epochId, cell_id: cell.id, run_index: runIndex,
-        outcome: tiered.outcome, brand_mentioned: analysis.mentioned, target_cited: analysis.cited, cited_urls: tiered.citedUrls, verify: tiered.verify,
-        evidence_sha256: digest, cost_estimate_usd: run.costEstimateUsd ?? 0, at: nowIso(),
-      }));
-      // Duck engines need extra pacing: their anonymous rate limit (~3-4 per exit)
-      // benefits from a cooldown between observations even with exit rotation.
-      if (aborted) break outer;
-      const cellDelay = cell.identity.startsWith('duck') ? Math.max(delayMs, 2000) : delayMs;
-      if (cellDelay > 0) await new Promise((r) => setTimeout(r, cellDelay));
+        const tiered = run.unknown ? { outcome: 'unknown', citedUrls: [], verify: 'unknown' } : classifyOutcome(cell.target, run, options.verifyFetch ?? null);
+        const analysis = analyzeRetainedAnswer(cell.target, run);
+        outcomesByCell.get(cell.id).push(tiered.outcome);
+        observationRows.push(observationRowSchema.parse({
+          schema_version: CITATIONS_VERSION, epoch_id: epochId, cell_id: cell.id, run_index: runIndex,
+          outcome: tiered.outcome, brand_mentioned: analysis.mentioned, target_cited: analysis.cited, cited_urls: tiered.citedUrls, verify: tiered.verify,
+          evidence_sha256: digest, cost_estimate_usd: run.costEstimateUsd ?? 0, at: nowIso(),
+        }));
+        // Duck engines need extra pacing: their anonymous rate limit (~3-4 per exit)
+        // benefits from a cooldown between observations even with exit rotation.
+        if (aborted) break outer;
+        const cellDelay = cell.identity.startsWith('duck') ? Math.max(delayMs, 2000) : delayMs;
+        if (cellDelay > 0) await new Promise((r) => setTimeout(r, cellDelay));
+      }
     }
-  }
 
-  const prior = await readPriorEpochs(dir);
-  const epochRows = [];
-  for (const cell of cells) {
-    const outcomes = outcomesByCell.get(cell.id);
-    const { k, n, unknowns, mentioned } = tallyOutcomes(outcomes);
-    const ci = wilsonInterval(k, n);
-    const baselineRow = prior.filter((r) => r.cell_id === cell.id && r.n >= CITATION_LIMITS.minSamplesForInterpretation).at(-1);
-    const baseline = baselineRow ? { k: baselineRow.k, n: baselineRow.n } : null;
-    const priorCount = prior.filter(row => row.cell_id === cell.id).length;
-    const pairAlpha = priorCount > 0 ? 0.05 / (priorCount * (priorCount + 1)) : 0.05;
-    const { run_length_posterior, ...changepoint } = changepointPosterior(outcomes);
-    const statistics = { scope: 'fixed-epoch-supplemental',
-      confidence_sequence: confidenceSequence(outcomes, { alpha: 0.05, comparisons: cells.length }).at(-1) ?? null,
-      epoch_comparison: baseline ? compareEpochs({ k, n }, baseline, { alpha: pairAlpha, comparisons: cells.length }) : null,
-      changepoint,
-    };
-    const row = epochRowSchema.parse({
-      schema_version: CITATIONS_VERSION, epoch_id: epochId, cell_id: cell.id,
-      k, n, unknowns, mentioned,
-      rate: smoothedRate(k, n), ci_low: ci?.[0] ?? null, ci_high: ci?.[1] ?? null,
-      classification: classifyEpoch({ k, n }, baseline, CITATION_LIMITS), statistics,
-      baseline: baselineRow ? { epoch_id: baselineRow.epoch_id, rate: baselineRow.rate, ci_low: baselineRow.ci_low, ci_high: baselineRow.ci_high } : undefined,
-      spent_estimate_usd: Number(spent.toFixed(6)), at: nowIso(),
-    });
-    epochRows.push(row);
-    // Incremental flush: every completed cell's row is on disk immediately, so
-    // a killed epoch loses nothing — the lesson of the lost 3x3 tallies.
-    await writeFile(join(dir, CITATION_FILES.epochs), JSON.stringify(row) + '\n', { flag: 'a' });
-  }
+    const prior = await readPriorEpochs(dir);
+    const epochRows = [];
+    for (const cell of cells) {
+      const outcomes = outcomesByCell.get(cell.id);
+      const { k, n, unknowns, mentioned } = tallyOutcomes(outcomes);
+      const ci = wilsonInterval(k, n);
+      const baselineRow = prior.filter((r) => r.cell_id === cell.id && r.n >= CITATION_LIMITS.minSamplesForInterpretation).at(-1);
+      const baseline = baselineRow ? { k: baselineRow.k, n: baselineRow.n } : null;
+      const priorCount = prior.filter(row => row.cell_id === cell.id).length;
+      const pairAlpha = priorCount > 0 ? 0.05 / (priorCount * (priorCount + 1)) : 0.05;
+      const { run_length_posterior, ...changepoint } = changepointPosterior(outcomes);
+      const statistics = { scope: 'fixed-epoch-supplemental',
+        confidence_sequence: confidenceSequence(outcomes, { alpha: 0.05, comparisons: cells.length }).at(-1) ?? null,
+        epoch_comparison: baseline ? compareEpochs({ k, n }, baseline, { alpha: pairAlpha, comparisons: cells.length }) : null,
+        changepoint,
+      };
+      const row = epochRowSchema.parse({
+        schema_version: CITATIONS_VERSION, epoch_id: epochId, cell_id: cell.id,
+        k, n, unknowns, mentioned,
+        rate: smoothedRate(k, n), ci_low: ci?.[0] ?? null, ci_high: ci?.[1] ?? null,
+        classification: classifyEpoch({ k, n }, baseline, CITATION_LIMITS), statistics,
+        baseline: baselineRow ? { epoch_id: baselineRow.epoch_id, rate: baselineRow.rate, ci_low: baselineRow.ci_low, ci_high: baselineRow.ci_high } : undefined,
+        spent_estimate_usd: Number(spent.toFixed(6)), at: nowIso(),
+      });
+      epochRows.push(row);
+      // Incremental flush: every completed cell's row is on disk immediately, so
+      // a killed epoch loses nothing — the lesson of the lost 3x3 tallies.
+      await writeFile(join(dir, CITATION_FILES.epochs), JSON.stringify(row) + '\n', { flag: 'a' });
+    }
 
-  await writeFile(join(dir, CITATION_FILES.observations), observationRows.map((r) => JSON.stringify(r)).join('\n') + (observationRows.length ? '\n' : ''), { flag: 'a' });
+    await writeFile(join(dir, CITATION_FILES.observations), observationRows.map((r) => JSON.stringify(r)).join('\n') + (observationRows.length ? '\n' : ''), { flag: 'a' });
 
-  // Browser engines hold a browser and maybe an Xvfb display for the whole
-  // epoch; release both once the tallies are written.
-  for (const engine of new Set(cells.map((c) => c.engine))) {
-    try { await engine.close?.(); } catch { /* cleanup is best-effort */ }
+    return { epochId, cells: epochRows, spentEstimateUsd: Number(spent.toFixed(6)), aborted, samples, maxUsd };
+  } catch (error) {
+    primaryError = error;
+    throw error;
+  } finally {
+    let persistenceError, cleanupError;
+    for (const engine of uniqueEngines) {
+      let error;
+      try { await engine.close?.(); } catch (cause) { error = cause; cleanupError ??= cause; }
+      try { await journal?.capture(engine, { phase: 'cleanup', error }); }
+      catch (cause) { persistenceError ??= cause; }
+    }
+    try { await journal?.finish({ failed: Boolean(primaryError || persistenceError || cleanupError), cleanupUncertain: Boolean(cleanupError), evidenceComplete: !persistenceError && !String(primaryError?.code ?? '').startsWith('EGRESS_') }); }
+    catch (cause) { persistenceError ??= cause; }
+    try { await journal?.close(); } catch (cause) { persistenceError ??= cause; }
+    if (persistenceError) throw persistenceError;
+    if (!primaryError && cleanupError && journal) throw Object.assign(new EngineError('Browser cleanup could not be confirmed; inspect the egress journal.'), { code: 'BROWSER_CLEANUP_UNCONFIRMED' });
   }
-
-  return { epochId, cells: epochRows, spentEstimateUsd: Number(spent.toFixed(6)), aborted, samples, maxUsd };
 }

package/src/citations/sync.js

@@ -8,6 +8,7 @@
 // truth; the hosted view is a projection.
 import { readFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
+import { verifyLocalEvidenceDigest } from './evidence-integrity.js';
 
 export async function syncEpochs({ dir, api, workspaceId, projectId }) {
   if (!api || !workspaceId || !projectId) {
@@ -83,7 +84,7 @@ export async function syncEvidence({ dir, api, projectId, cliVersion }) {
   try { text = await readFile(join(root, 'citations-observations.jsonl'), 'utf8'); }
   catch (error) { if (error.code !== 'ENOENT') throw error; return { synced: 0, total: 0, skipped: 0, errors: 0, reasons: {} }; }
   const rows = text.split('\n').filter(line => line.trim()).map(line => JSON.parse(line));
-  const records = []; const reasons = {}; const seen = new Set();
+  const records = []; const reasons = {}; const seen = new Map();
   const skip = reason => { reasons[reason] = (reasons[reason] ?? 0) + 1; };
   const hash = bytes => createHash('sha256').update(bytes).digest('hex');
   async function safeFile(path) {
@@ -95,13 +96,19 @@ export async function syncEvidence({ dir, api, projectId, cliVersion }) {
   for (const row of rows) {
     if (!/^[A-Za-z0-9_.-]+$/.test(row.epoch_id ?? '') || ['.', '..'].includes(row.epoch_id) || !/^[a-f0-9]{64}$/.test(row.evidence_sha256 ?? '')) throw new Error('Malformed local evidence reference');
     const path = join(root, 'citations/evidence', row.epoch_id, `${row.evidence_sha256}.json`);
-    if (seen.has(path)) continue; seen.add(path);
+    const identity = JSON.stringify([row.epoch_id, row.cell_id, row.run_index]);
+    if (seen.has(path)) {
+      if (seen.get(path) !== identity) throw new Error('Conflicting local evidence reference');
+      continue;
+    }
+    seen.set(path, identity);
     let file;
     try { file = await safeFile(path); } catch (error) { if (error.code === 'ENOENT') { skip('missing_envelope'); continue; } throw error; }
     if ((await lstat(file)).size > limits.envelopeBytes) throw new Error('Evidence envelope exceeds the upload limit');
     const envelopeJson = await readFile(file, 'utf8');
     const envelope = evidenceEnvelopeSchema.parse(JSON.parse(envelopeJson));
     if (envelope.epoch_id !== row.epoch_id || envelope.cell_id !== row.cell_id || envelope.run_index !== row.run_index) throw new Error('Evidence identity does not match its observation');
+    if (!verifyLocalEvidenceDigest({ envelope, text: envelopeJson, digest: row.evidence_sha256 })) throw new Error('Evidence digest does not match its retained observation');
     if (envelope.engine_identity.startsWith('google-aio:') && !envelope.provenance) { skip('legacy_aio_without_provenance'); continue; }
     const record = { envelopeJson, sha256: hash(envelopeJson), cliVersion, localEvidenceSha256: row.evidence_sha256 };
     if (envelope.screenshot_file) {