wotann 0.5.97 → 0.5.98

package/README.md

@@ -4,7 +4,7 @@
 
 **The All-Father of AI agent harnesses.**
 
-One install. Every model. Every channel. Full autonomy.
+One install. Your providers. Every channel. Full autonomy.
 
 <p>
   <a href="https://github.com/gabrielvuksani/wotann/actions/workflows/ci.yml"><img src="https://github.com/gabrielvuksani/wotann/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
@@ -25,7 +25,7 @@ One install. Every model. Every channel. Full autonomy.
 <td align="center">
 <strong>WOTANN treats the LLM as just the inference call.</strong><br/>
 Memory, tools, sandbox, orchestration, learning — all come from the harness.<br/>
-A local Gemma gets the same intelligence scaffolding as Claude Opus.
+Inference comes from a remote subscription or API-key provider you configure.
 </td>
 </tr>
 </table>
@@ -38,13 +38,13 @@ A local Gemma gets the same intelligence scaffolding as Claude Opus.
 
 ## Why WOTANN
 
-Most agent frameworks lock you to a vendor, degrade quietly when a model can't tool-call, and hand you a single UI. WOTANN inverts that. It lives at the layer above inference so your choice of model is always a drop-in. Switch from Claude → Gemini → Gemma mid-session and you keep the same memory, the same tools, the same capabilities.
+Most agent frameworks lock you to a vendor, degrade quietly when a model can't tool-call, and hand you a single UI. WOTANN inverts that. It lives at the layer above inference so your configured lab subscription or API-key provider remains replaceable without moving agent execution off your machine.
 
 |   | Most agents | **WOTANN** |
 |---|---|---|
 | **Provider** | Locked to one vendor | **25 providers** via openai-compat router; Anthropic + OpenAI subscriptions OR API keys |
-| **Capabilities** | Tool-calling, vision, thinking gated by model support | **Capability augmentation injects all three** for any model — even a 3B local Gemma |
-| **Free tier** | An afterthought | **First-class**: Ollama + Groq + Gemini 2.5 Flash free tier give the full experience |
+| **Capabilities** | Tool-calling, vision, thinking gated by model support | **Capability augmentation** normalizes provider capabilities |
+| **Inference economics** | Resold tokens or bundled inference | **BYO subscription or API key**: the user pays the lab |
 | **Memory** | Short-lived prompt context | **8-layer persistent**: SQLite + FTS5 + vector + graph-RAG + episodic + temporal + provenance |
 | **Surfaces** | One UI | **CLI + TUI + Desktop + iOS + Watch + CarPlay + 25 messaging channels** |
 | **Autonomy** | Vibes | **Proof bundles** (tests + typecheck + diff + screenshots) on every completion |
@@ -94,7 +94,7 @@ npx wotann@latest
 
 Node.js prerequisite on Windows: `winget install OpenJS.NodeJS.LTS` (Node 22.13+ required). The PowerShell installer enforces this; the npm path surfaces a friendly preflight error on older Node.
 
-That's the whole setup. WOTANN runs **entirely locally by default** (Ollama + free tiers). Drop an API key to upgrade selectively — no lock-in, no telemetry unless you opt in.
+Agent execution and trust enforcement run on your machine. Inference uses a provider subscription or API key that you configure; WOTANN does not run local models or silently route prompts to anonymous public endpoints.
 
 ```bash
 # Use frontier models when you want them
@@ -102,31 +102,11 @@ export ANTHROPIC_API_KEY=sk-ant-...
 export OPENAI_API_KEY=sk-...
 export GEMINI_API_KEY=AIza...
 
-# Or stay free
-ollama pull qwen2.5-coder:7b
-wotann                              # auto-detects Ollama
+# ChatGPT/Codex and Claude subscription paths are supported too
+wotann onboard
 ```
 
-### Zero-config public tier (no signup, no key)
-
-If you have no API keys and no local Ollama, WOTANN still works out of the box. The runtime auto-falls through to an anonymous public-tier chain — no account, no credit card, no environment variable required.
-
-```bash
-# Cold-start with nothing configured. The TUI mounts and the first
-# message routes through the public tier automatically.
-npx wotann@latest
-```
-
-The chain is ordered by latency + rate-limit headroom (you can introspect with `wotann providers list`):
-
-| Order | Provider | Model surface | Why |
-|---|---|---|---|
-| 1 | Pollinations.ai anonymous | `openai-fast` (GPT-OSS 20B reasoning, OVH backend) | Fast, ~1 req queued/IP |
-| 2 | LLM7.io anonymous | GLM-4.6V (vision) + Codestral (code) | 30 RPM, vision-capable |
-| 3 | OVHcloud anonymous | Llama 3.3 70B, GPT-OSS 120B, Qwen2.5-VL 72B | 2 RPM/IP, vision-capable |
-| 4 | AI Horde | Community-pooled models | Uncensored fallback; queue-dependent |
-
-Rate-limit errors fall through to the next adapter without surfacing to the user. When all four are saturated WOTANN reports honestly — no silent retries, no fake success. Disable the public tier entirely with `WOTANN_DISABLE_PUBLIC=1` for sandboxed/offline runs.
+There is no anonymous zero-config inference tier. If no authenticated remote processor is configured, WOTANN reports that honestly.
 
 ---
 
@@ -160,21 +140,21 @@ $ wotann link
 
 ### Provider freedom (the moat)
 
-25 providers via one router with automatic fallback chaining: `preferred → other paid → Gemini → Ollama → free`. **The model is never silently degraded** — if your chosen Opus is rate-limited, WOTANN tries Opus via another provider first; only when all paid paths exhaust does it fall back to Gemini/local.
+Remote providers share one router with authenticated fallback chaining: `preferred → other configured remote processors`. Local runtimes and anonymous endpoints are excluded from executable fallback. If configured processors exhaust, WOTANN reports that honestly.
 
 Runtime providers can be added without editing source: drop a strict `provider.json` under `.wotann/providers/<name>/` with an OpenAI-compatible `baseUrl`, model list, capabilities, and an `auth.envKey`. WOTANN validates the manifest, refuses token-bearing manifests, and routes it through the same provider registry as built-ins.
 
 ```
 Anthropic API    Anthropic Subscription   OpenAI    Codex (ChatGPT OAuth)
-GitHub Copilot   Ollama                   Gemini    HuggingFace
+GitHub Copilot   OpenRouter               Gemini    HuggingFace
 Azure            Bedrock                  Vertex    Mistral
 DeepSeek         Perplexity               xAI       Together
 Fireworks        SambaNova                Groq      Cerebras
 ```
 
-### The harness amplifies — even on a 3B local model
+### The harness amplifies provider capabilities
 
-`capability-augmenter` injects tool-calling, vision (via OCR + a11y tree), and extended thinking ("step by step" prompts) into providers that lack native support. Combined with hash-anchored editing, line-bucketed loop detection, and 41 forced-verification middleware layers in the PIPELINE, a **Qwen2.5-Coder:7B running locally gets the same forced verification, frustration detection, doom-loop guards, and memory system as Claude Opus**.
+`capability-augmenter` injects tool-calling, vision (via OCR + a11y tree), and extended thinking prompts into configured providers that lack native support. The trust layer stays independent of any one model family.
 
 ### Multi-surface, one agent, one memory
 
@@ -204,7 +184,7 @@ Runs **Ralph mode** (verify-fix loop) + **self-healing** (provider fallback) + *
 - **Guardian** post-response LLM-as-judge review (`WOTANN_GUARDIAN=1`)
 - **Self-consistency voting** — N parallel samples with confidence score
 - **Council deliberation** — 3-stage multi-provider peer review + chairman synthesis
-- **Unified knowledge fabric** — single search API across memory / context-tree / graph-RAG / vector / FTS5, with `wotann memory embeddings warmup` for local BGE embeddings that keep semantic memory usable offline after the model is cached
+- **Unified knowledge fabric** — single search API across memory / context-tree / graph-RAG / vector / FTS5, with deterministic retrieval fallbacks when no authenticated remote embedding processor is configured
 - **Context replay** — priority-weighted reassembly under an explicit token budget
 - **Dream pipeline** — nightly consolidation 02:00-04:00, extracts skills from successful runs
 
@@ -272,12 +252,12 @@ src/
 ├── intelligence/     85 modules that meaningfully affect model behavior
 ├── orchestration/    79 modules — coordinator · waves · PWR · Ralph · council · squads · canary · ...
 ├── memory/           80 modules · SQLite + FTS5 · 8 layers · vector · graph-RAG · episodic
-├── context/          5 compaction strategies · Ollama KV cache compression
+├── context/          5 compaction strategies · legacy local-runtime code slated for subtraction
 ├── prompt/           Engine · 18 prompt modules · instruction provenance
 ├── hooks/            31 events (28 producer-wired · 3 advisory) · 23 guards · DoomLoop
 ├── computer-use/     4-layer perception + action stack (text-mediated for any model)
 ├── channels/         25+ adapters + DM pairing + node registry
-├── voice/            Push-to-talk · STT/TTS · WhisperKit · Edge TTS · faster-whisper
+├── voice/            Push-to-talk · authenticated remote STT/TTS adapters
 ├── learning/         autoDream · instincts · skill-forge · pattern-crystallizer
 ├── identity/         Persona system · soul/identity loading · Norse mythology
 ├── security/         Anti-distillation · PII redaction · sandbox · guardrails · SSRF guard
@@ -332,13 +312,13 @@ Run `wotann --help` for the full 78+ command surface.
 
 - **Node ≥ 22.13** (current LTS; install via `winget install OpenJS.NodeJS.LTS` on Windows or `brew install node@22` on macOS)
 - **macOS 13+ / Linux / Windows 11**
-- **Optional**: Ollama (local models), Python 3.11+ (for camoufox stealth browser backend), Xcode 16 (iOS builds)
+- **Optional**: Python 3.11+ (for camoufox stealth browser backend), Xcode 16 (iOS builds)
 
 ---
 
 ## Privacy
 
-Runs entirely locally by default. Telemetry is opt-out and triple-gated — industry-standard `DO_NOT_TRACK=1` is honored, plus WOTANN-specific `WOTANN_NO_TELEMETRY=1`, plus a sentinel file at `~/.wotann/no-telemetry`.
+Agent execution and trust enforcement run locally. Inference payloads go only to the configured lab provider. Telemetry is opt-out and triple-gated — industry-standard `DO_NOT_TRACK=1` is honored, plus WOTANN-specific `WOTANN_NO_TELEMETRY=1`, plus a sentinel file at `~/.wotann/no-telemetry`.
 
 ```bash
 export WOTANN_NO_TELEMETRY=1

package/dist/api/anthropic-gateway.d.ts

@@ -8,14 +8,13 @@
  * Messages protocol natively. Today they hit api.anthropic.com
  * directly, paying per-token to Anthropic. With this gateway, they
  * can hit `http://localhost:8420/v1/messages` and WOTANN routes the
- * call to whichever provider is cheapest/free (Ollama, OpenRouter
- * free tier, Groq, Gemini free tier, etc.) while still returning
- * the response in Anthropic's expected format.
+ * call to a configured authenticated remote provider while still
+ * returning the response in Anthropic's expected format.
  *
  * The harness's middleware (memory injection, hooks, sandbox guards,
  * cost tracking) runs every call regardless of which provider serves
- * the response. Free-tier first-class becomes consumable by every
- * tool in the ecosystem.
+ * the response. Authenticated remote provider routing becomes
+ * consumable by every tool in the ecosystem.
  *
  * SUPPORTED
  *

package/dist/api/anthropic-gateway.js

@@ -8,14 +8,13 @@
  * Messages protocol natively. Today they hit api.anthropic.com
  * directly, paying per-token to Anthropic. With this gateway, they
  * can hit `http://localhost:8420/v1/messages` and WOTANN routes the
- * call to whichever provider is cheapest/free (Ollama, OpenRouter
- * free tier, Groq, Gemini free tier, etc.) while still returning
- * the response in Anthropic's expected format.
+ * call to a configured authenticated remote provider while still
+ * returning the response in Anthropic's expected format.
  *
  * The harness's middleware (memory injection, hooks, sandbox guards,
  * cost tracking) runs every call regardless of which provider serves
- * the response. Free-tier first-class becomes consumable by every
- * tool in the ecosystem.
+ * the response. Authenticated remote provider routing becomes
+ * consumable by every tool in the ecosystem.
  *
  * SUPPORTED
  *

package/dist/api/server.js

@@ -30,6 +30,7 @@ import { handleComputerSessionSseRequest } from "./sse-computer-session.js";
 // the canonical provider table instead of a hardcoded Anthropic+OpenAI
 // pair. Adding a provider in model-defaults.ts surfaces it here.
 import { PROVIDER_DEFAULTS, detectProviderFromEnv } from "../providers/model-defaults.js";
+import { isForbiddenTrustLayerProvider } from "../providers/fallback-chain.js";
 // Round 12 — Anthropic Messages API gateway. Lets Claude Code/Cursor
 // hit our daemon instead of api.anthropic.com so they get free-tier
 // orchestration + harness middleware (memory, hooks, sandbox) on
@@ -258,9 +259,10 @@ export class WotannAPIServer {
         // Dedupe model ids across the (default/worker/oracle) tiers because
         // many providers point all three at the same model.
         const seen = new Set();
+        const remoteProviderNames = Object.keys(PROVIDER_DEFAULTS).filter((name) => !isForbiddenTrustLayerProvider(name));
         const orderedNames = activeProvider
-            ? [activeProvider, ...Object.keys(PROVIDER_DEFAULTS).filter((n) => n !== activeProvider)]
-            : Object.keys(PROVIDER_DEFAULTS);
+            ? [activeProvider, ...remoteProviderNames.filter((n) => n !== activeProvider)]
+            : remoteProviderNames;
         for (const providerName of orderedNames) {
             const defaults = PROVIDER_DEFAULTS[providerName];
             if (!defaults)

package/dist/api/ws-hardening.d.ts

@@ -14,8 +14,8 @@
  *
  * Design notes:
  *   - `withInsecureWsAllowance` reads the env var ONCE per call. Centralizing
- *     this here avoids the ?? "ollama" class bug (Session 1 quality bar #1)
- *     where vendor-biased fallbacks scatter across the codebase.
+ *     this here avoids vendor-biased fallback bugs where provider
+ *     defaults scatter across the codebase.
  *   - `wsBackoff` returns a number (next sleep ms), never sleeps itself.
  *     Caller composes it with their preferred timer/scheduler. This keeps
  *     the helper testable without fake timers.

package/dist/api/ws-hardening.js

@@ -14,8 +14,8 @@
  *
  * Design notes:
  *   - `withInsecureWsAllowance` reads the env var ONCE per call. Centralizing
- *     this here avoids the ?? "ollama" class bug (Session 1 quality bar #1)
- *     where vendor-biased fallbacks scatter across the codebase.
+ *     this here avoids vendor-biased fallback bugs where provider
+ *     defaults scatter across the codebase.
  *   - `wsBackoff` returns a number (next sleep ms), never sleeps itself.
  *     Caller composes it with their preferred timer/scheduler. This keeps
  *     the helper testable without fake timers.

package/dist/auth/login.d.ts

@@ -6,8 +6,7 @@
  * 2. Codex/ChatGPT: PKCE browser flow via auth.openai.com, stores to ~/.codex/auth.json
  * 3. GitHub Copilot: device code flow (shows code, user enters in browser)
  * 4. Gemini: opens browser to AI Studio API key page (user copies key)
- * 5. Ollama: no login needed — verifies server and suggests models
- * 6. OpenAI-compatible API providers: env var check + instructions
+ * 5. OpenAI-compatible API providers: env var check + instructions
  *
  * PORT FALLBACK: If the OAuth callback port is taken (18920-18930),
  * the browser flow falls back to device code flow automatically.

package/dist/auth/login.js

@@ -6,8 +6,7 @@
  * 2. Codex/ChatGPT: PKCE browser flow via auth.openai.com, stores to ~/.codex/auth.json
  * 3. GitHub Copilot: device code flow (shows code, user enters in browser)
  * 4. Gemini: opens browser to AI Studio API key page (user copies key)
- * 5. Ollama: no login needed — verifies server and suggests models
- * 6. OpenAI-compatible API providers: env var check + instructions
+ * 5. OpenAI-compatible API providers: env var check + instructions
  *
  * PORT FALLBACK: If the OAuth callback port is taken (18920-18930),
  * the browser flow falls back to device code flow automatically.
@@ -339,50 +338,11 @@ async function loginApiKeyProvider(provider) {
 }
 // ── Ollama Check ───────────────────────────────────────────
 async function loginOllama() {
-    console.log(chalk.dim("  Checking Ollama status...\n"));
-    try {
-        const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), 3000);
-        const { ollamaUrl } = await import("../providers/ollama-host.js");
-        const response = await fetch(ollamaUrl("/api/tags"), { signal: controller.signal });
-        clearTimeout(timeout);
-        if (response.ok) {
-            const data = (await response.json());
-            const models = data.models ?? [];
-            const modelCount = models.length;
-            console.log(chalk.green(`  Ollama is running with ${modelCount} model(s):`));
-            for (const m of models.slice(0, 10)) {
-                const sizeGB = (m.size / 1e9).toFixed(1);
-                console.log(chalk.dim(`    - ${m.name} (${sizeGB}GB)`));
-            }
-            if (modelCount === 0) {
-                console.log(chalk.yellow("\n  No models installed. Recommended for coding:"));
-                console.log(chalk.dim("    ollama pull qwen3-coder-next    # 80B MoE, best coding (18GB VRAM)"));
-                console.log(chalk.dim("    ollama pull qwen3.5:27b         # multimodal, 256K context (20GB)"));
-                console.log(chalk.dim("    ollama pull devstral:24b         # fast coding agent (16GB)"));
-                console.log(chalk.dim("    ollama pull qwen3-coder:7b       # entry level (5GB)"));
-            }
-            return {
-                provider: "ollama",
-                success: true,
-                message: `Ollama is running with ${modelCount} model(s). No login needed.`,
-                method: "local-check",
-            };
-        }
-    }
-    catch {
-        // Not running
-    }
-    console.log(chalk.yellow("  Ollama is not running."));
-    console.log(chalk.dim("\n  Install:  https://ollama.ai"));
-    console.log(chalk.dim("  Start:    ollama serve"));
-    console.log(chalk.dim("  Pull:     ollama pull qwen3-coder-next"));
-    console.log(chalk.dim("  Verify:   ollama list\n"));
     return {
         provider: "ollama",
         success: false,
-        message: "Ollama is not running. Install from https://ollama.ai, then: ollama serve && ollama pull qwen3-coder-next",
-        method: "local-check",
+        message: "Local models are disabled in the WOTANN trust layer. Configure a remote subscription or API key.",
+        method: "disabled",
     };
 }
 // ── OpenAI API Key ─────────────────────────────────────────
@@ -464,7 +424,6 @@ export async function runLogin(provider, options = {}) {
     console.log(chalk.dim("           wotann login codex"));
     console.log(chalk.dim("           wotann login copilot"));
     console.log(chalk.dim("           wotann login gemini"));
-    console.log(chalk.dim("           wotann login ollama"));
     console.log(chalk.dim("           wotann login nvidia"));
     console.log(chalk.dim("           wotann login huggingface\n"));
 }

package/dist/browser/agentic-browser.d.ts

@@ -53,6 +53,8 @@
  *  - QB #14 claim verification: tests in tests/browser/agentic-browser
  *    .test.ts cover all halt paths + the happy-path to closure.
  */
+import type { TaintApprovalCoordinator } from "../security/taint-approval-coordinator.js";
+import { type VisualTaintAdvisory } from "../security/visual-taint.js";
 /**
  * The kind of atomic step the planner can emit. Kept narrow on purpose
  * — expanding this union is a breaking change because every step kind
@@ -108,6 +110,8 @@ export interface BrowseTurnRecord {
     readonly hiddenTextReport?: unknown;
     /** From src/middleware/trifecta-guard.ts */
     readonly trifectaVerdict?: unknown;
+    /** Advisory-only cross-modal DOM/AX disagreement evidence. */
+    readonly visualTaintAdvisories?: readonly VisualTaintAdvisory[];
     readonly approved?: boolean;
     readonly timestamp: number;
     readonly haltReason?: string;
@@ -147,6 +151,8 @@ export interface BrowserDriverNavigateResult {
     readonly pageText: string;
     readonly elements: readonly BrowseElement[];
     readonly finalUrl?: string;
+    /** Optional accessibility-tree text when the driver extracts it separately. */
+    readonly accessibilityText?: string;
 }
 export interface BrowserDriver {
     readonly navigate: (url: string) => Promise<BrowserDriverNavigateResult>;
@@ -219,6 +225,14 @@ export interface BrowseOrchestratorOptions {
         readonly x: number;
         readonly y: number;
     };
+    /** Optional session-scoped deterministic provenance gate. */
+    readonly taintCoordinator?: TaintApprovalCoordinator;
+    /** Required whenever `taintCoordinator` is installed. */
+    readonly taintSessionId?: string;
+    /** Working directory recorded in taint receipts. Defaults to ".". */
+    readonly taintCwd?: string;
+    /** Explicit simulation mode. Live execution is the fail-closed default. */
+    readonly executionMode?: "live" | "dry-run";
 }
 /**
  * Remove hidden-text substrings from the page text before quarantine

package/dist/browser/agentic-browser.js

@@ -54,8 +54,54 @@
  *    .test.ts cover all halt paths + the happy-path to closure.
  */
 import { randomUUID } from "node:crypto";
+import { compareVisualLanes } from "../security/visual-taint.js";
 // ═══ Internal helpers ════════════════════════════════════════════════════
 const DEFAULT_PREVIEW_MAX = 2048;
+function snapshotBrowserActionArgs(args) {
+    return freezeBrowserSnapshot(structuredClone(args));
+}
+function freezeBrowserSnapshot(value, seen = new Set()) {
+    if (value === null || typeof value !== "object" || seen.has(value))
+        return value;
+    seen.add(value);
+    for (const nested of Object.values(value))
+        freezeBrowserSnapshot(nested, seen);
+    return Object.freeze(value);
+}
+async function authorizeBrowserAction(options, tool, args) {
+    if (!options.taintCoordinator) {
+        return options.executionMode === "dry-run"
+            ? { authorized: true }
+            : { authorized: false, reason: "runtime taint substrate is unavailable" };
+    }
+    const sessionId = options.taintSessionId?.trim();
+    if (!sessionId)
+        return { authorized: false, reason: "taint policy session is unavailable" };
+    const action = Object.freeze({
+        tool,
+        args: snapshotBrowserActionArgs(args),
+        cwd: options.taintCwd?.trim() || ".",
+    });
+    const authorization = await options.taintCoordinator.authorize({ sessionId, action });
+    if (!authorization.authorized) {
+        return { authorized: false, reason: authorization.reason };
+    }
+    const verification = options.taintCoordinator.verifyExecution({ authorization, action });
+    return verification.ok
+        ? { authorized: true }
+        : { authorized: false, reason: `execution re-pin failed: ${verification.reason}` };
+}
+function registerBrowserSource(options, kind, content) {
+    if (!options.taintCoordinator || content.length === 0)
+        return null;
+    try {
+        options.taintCoordinator.registerSource({ kind, content, integrity: "untrusted" });
+        return null;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+}
 /**
  * Pull `hiddenText` off the hidden-text report shape without coupling
  * to the concrete type. Reports without the field are treated as
@@ -215,8 +261,21 @@ async function executeNavigate(step, options, now) {
             halted: true,
         };
     }
-    // Emit a cursor frame for the overlay BEFORE we navigate so the UI
-    // animation starts in sync with the agent's action.
+    const taintGate = await authorizeBrowserAction(options, "browser.navigate", { url });
+    if (!taintGate.authorized) {
+        return {
+            record: {
+                step,
+                url,
+                urlVerdict,
+                timestamp: now(),
+                haltReason: `taint-policy:${taintGate.reason}`,
+            },
+            halted: true,
+        };
+    }
+    // Emit a cursor frame for the overlay immediately before navigation
+    // so a denied taint gate never animates an action that did not happen.
     if (options.cursorEmit) {
         const xy = options.defaultCursorXY ?? { x: 0, y: 0 };
         options.cursorEmit({
@@ -252,6 +311,38 @@ async function executeNavigate(step, options, now) {
     const hiddenTextReport = await options.hiddenTextScan(driverResult.elements);
     const hiddenText = extractHiddenText(hiddenTextReport);
     const visibleText = subtractHiddenText(driverResult.pageText, hiddenText);
+    const sourceRegistrationError = registerBrowserSource(options, "browser-dom", visibleText) ??
+        registerBrowserSource(options, "browser-dom", hiddenText) ??
+        (driverResult.accessibilityText !== undefined
+            ? registerBrowserSource(options, "browser-ax", driverResult.accessibilityText)
+            : null);
+    if (sourceRegistrationError) {
+        return {
+            record: {
+                step,
+                url: driverResult.finalUrl ?? url,
+                urlVerdict,
+                hiddenTextReport,
+                timestamp: now(),
+                haltReason: `taint-source-registration-failed:${sourceRegistrationError.slice(0, 200)}`,
+                error: sourceRegistrationError,
+            },
+            halted: true,
+        };
+    }
+    const visualTaintAdvisories = compareVisualLanes({
+        dom: visibleText,
+        ...(driverResult.accessibilityText !== undefined
+            ? { ax: driverResult.accessibilityText }
+            : {}),
+        now,
+    });
+    const taintSessionId = options.taintSessionId?.trim();
+    if (options.taintCoordinator && taintSessionId) {
+        for (const advisory of visualTaintAdvisories) {
+            options.taintCoordinator.recordVisualAdvisory(taintSessionId, advisory);
+        }
+    }
     // Gate D — prompt-injection quarantine on the VISIBLE page text.
     const injectionVerdict = await options.contentQuarantine(visibleText);
     if (extractQuarantineHalted(injectionVerdict)) {
@@ -263,6 +354,7 @@ async function executeNavigate(step, options, now) {
                 urlVerdict,
                 hiddenTextReport,
                 injectionVerdict,
+                visualTaintAdvisories,
                 pageContentPreview: buildPageContentPreview(visibleText, options.pageContentPreviewMax ?? DEFAULT_PREVIEW_MAX),
                 timestamp: now(),
                 haltReason: `quarantine:${reason}`,
@@ -288,6 +380,7 @@ async function executeNavigate(step, options, now) {
                 hiddenTextReport,
                 injectionVerdict,
                 trifectaVerdict,
+                visualTaintAdvisories,
                 pageContentPreview: buildPageContentPreview(visibleText, options.pageContentPreviewMax ?? DEFAULT_PREVIEW_MAX),
                 timestamp: now(),
                 haltReason: `trifecta:BLOCK`,
@@ -305,6 +398,7 @@ async function executeNavigate(step, options, now) {
                     hiddenTextReport,
                     injectionVerdict,
                     trifectaVerdict,
+                    visualTaintAdvisories,
                     approved: false,
                     pageContentPreview: buildPageContentPreview(visibleText, options.pageContentPreviewMax ?? DEFAULT_PREVIEW_MAX),
                     timestamp: now(),
@@ -323,6 +417,7 @@ async function executeNavigate(step, options, now) {
             hiddenTextReport,
             injectionVerdict,
             trifectaVerdict,
+            visualTaintAdvisories,
             approved: trifectaVerdict.verdict === "REQUIRE_APPROVAL" ? true : undefined,
             pageContentPreview: buildPageContentPreview(visibleText, options.pageContentPreviewMax ?? DEFAULT_PREVIEW_MAX),
             timestamp: now(),
@@ -394,6 +489,11 @@ async function executeInteraction(step, options, now) {
                     halted: true,
                 };
             }
+            const taintGate = await authorizeBrowserAction(options, "browser.click", {
+                selector: step.target,
+            });
+            if (!taintGate.authorized)
+                return taintPolicyHalt(step, trifectaVerdict, taintGate.reason, now);
             await options.browserDriver.click(step.target);
         }
         else if (step.kind === "type") {
@@ -411,6 +511,12 @@ async function executeInteraction(step, options, now) {
             }
             const textRaw = step.args?.["text"];
             const text = typeof textRaw === "string" ? textRaw : "";
+            const taintGate = await authorizeBrowserAction(options, "browser.type", {
+                selector: step.target,
+                text,
+            });
+            if (!taintGate.authorized)
+                return taintPolicyHalt(step, trifectaVerdict, taintGate.reason, now);
             await options.browserDriver.type(step.target, text);
         }
         else if (step.kind === "extract" && options.browserDriver.extract) {
@@ -426,7 +532,37 @@ async function executeInteraction(step, options, now) {
                     halted: true,
                 };
             }
-            await options.browserDriver.extract(step.target);
+            const taintGate = await authorizeBrowserAction(options, "browser.read_page", {
+                selector: step.target,
+            });
+            if (!taintGate.authorized)
+                return taintPolicyHalt(step, trifectaVerdict, taintGate.reason, now);
+            const extracted = await options.browserDriver.extract(step.target);
+            const sourceRegistrationError = registerBrowserSource(options, "browser-dom", extracted);
+            if (sourceRegistrationError) {
+                return {
+                    record: {
+                        step,
+                        trifectaVerdict,
+                        timestamp: now(),
+                        haltReason: `taint-source-registration-failed:${sourceRegistrationError.slice(0, 200)}`,
+                        error: sourceRegistrationError,
+                    },
+                    halted: true,
+                };
+            }
+        }
+        else if (step.kind === "read") {
+            const taintGate = await authorizeBrowserAction(options, "browser.read_page", {});
+            if (!taintGate.authorized)
+                return taintPolicyHalt(step, trifectaVerdict, taintGate.reason, now);
+        }
+        else if (step.kind === "approve") {
+            const taintGate = await authorizeBrowserAction(options, "browser.approve_action", {
+                ...(step.args ?? {}),
+            });
+            if (!taintGate.authorized)
+                return taintPolicyHalt(step, trifectaVerdict, taintGate.reason, now);
         }
         // `read` and `approve` have no driver-side side-effect; the record
         // is purely audit.
@@ -454,6 +590,17 @@ async function executeInteraction(step, options, now) {
         halted: false,
     };
 }
+function taintPolicyHalt(step, trifectaVerdict, reason, now) {
+    return {
+        record: {
+            step,
+            trifectaVerdict,
+            timestamp: now(),
+            haltReason: `taint-policy:${reason}`,
+        },
+        halted: true,
+    };
+}
 // ═══ Main API ════════════════════════════════════════════════════════════
 /**
  * Run an agentic browse session from natural-language task to terminal

package/dist/browser/browser-tools.d.ts

@@ -15,6 +15,7 @@
 import type { ToolDefinition } from "../core/types.js";
 import { ChromeBridge } from "./chrome-bridge.js";
 import { CamoufoxBrowser } from "./camoufox-backend.js";
+import type { TaintApprovalCoordinator } from "../security/taint-approval-coordinator.js";
 import type { BrowsePlan, BrowsePlanStep } from "./agentic-browser.js";
 import type { TabRegistry } from "./tab-registry.js";
 export type BrowserToolOk<T> = {
@@ -64,6 +65,11 @@ export interface BrowserDep {
     chrome?: ChromeBridge | null;
     camoufox?: CamoufoxBrowser | null;
     agentic?: BrowserAgenticDep;
+    taint?: {
+        readonly coordinator: TaintApprovalCoordinator;
+        readonly sessionId: string;
+        readonly cwd?: string;
+    };
 }
 export declare function dispatchBrowserTool(toolName: BrowserToolName, input: Record<string, unknown>, dep: BrowserDep): Promise<BrowserToolResult<unknown>>;
 /**