browser-use
diff --git a/UPSTREAM.md b/UPSTREAM.md
@@ -0,0 +1,84 @@
+# Upstream
+
+This doc tracks BrowserCode's relationship to its two upstream sources:
+
+1. **anomalyco/opencode** — forked in as the bulk of this repo.
+2. **browser-use/browser-harness** — vendored into `packages/bcode-browser/harness/` (planned, ROADMAP A2).
+
+Two sections: **modification zones** (where is it safe to change upstream code?) and **sync log** (when did we last pull each upstream and to what commit?).
+
+---
+
+## 1. Modification zones
+
+Every line of upstream code falls into one of three zones.
+
+### Red — never touch
+
+Wire-level or brand-level identifiers that would break upstream compatibility:
+
+- `@opencode-ai/*` package names.
+- `@opencode/ServiceName` Effect service IDs.
+- `x-opencode-*` wire headers.
+- `OPENCODE_*` environment variables.
+- Third-party provider User-Agents (Anthropic, OpenAI, etc.).
+
+These are contractual with upstream and with provider APIs. Renaming breaks compatibility, auth flows, or provider trust.
+
+### Yellow — touch, but log it
+
+Modifications to existing upstream source files are allowed when (a) required by a BrowserCode capability that has no hook-level alternative, and (b) recorded in `EXCEPTIONS.md` with a "can we upstream this?" column (ROADMAP F8).
+
+Current Yellow modifications (landed in the rebrand commit `866a1a9`):
+
+- CLI `scriptName` → `bcode`
+- Binary/bin rename
+- USER_AGENT prefix
+- mDNS domain
+- Banner/wordmark
+- Package name at root (`@browser-use/browsercode`)
+- API description strings
+
+Future Yellow modifications (per ROADMAP):
+
+- `packages/opencode/src/tool/webfetch.ts` routed through `FetchUse.Service` (B2)
+- Core-CLI phone-home triage (F7)
+
+### Green — add freely
+
+- New files under `packages/opencode/src/` that don't collide with upstream paths.
+- New packages (cf. `packages/bcode-browser/`, decisions.md §1d).
+- Vendored code inside `packages/bcode-browser/` (own tree, zero upstream friction).
+
+Every Yellow modification should be evaluated for conversion to a Green extension point via upstream PR. See decisions.md §1c and ROADMAP F8.
+
+---
+
+## 2. Sync log
+
+Each upstream has its own append-only table. Add a row every time you pull.
+
+### anomalyco/opencode → this repo
+
+**Upstream:** https://github.com/anomalyco/opencode
+**Upstream branch we track:** `dev` (upstream default)
+**Our default branch:** `main`
+
+| Date | From SHA | To SHA | By | Notes |
+|---|---|---|---|---|
+| 2026-04-20 | — (initial) | `3e8abac6` | user | Mirror push after fork creation. Tagged `baseline/pre-rename`. See `scripts/check-upstream.sh` output for current drift. |
+
+### browser-use/browser-harness → `packages/bcode-browser/harness/`
+
+**Upstream:** https://github.com/browser-use/browser-harness
+**In-tree provenance:** `packages/bcode-browser/harness/PROVENANCE.md` (per-file edit log lives there).
+
+| Date | From SHA | To SHA | By | Notes |
+|---|---|---|---|---|
+| — | — | — | — | Not vendored yet. First row lands with ROADMAP A2. |
+
+---
+
+## Drift checker
+
+Run `scripts/check-upstream.sh` to see whether we're behind either upstream. It reads the latest `To SHA` from each table above and reports "N commits behind" since that point.
diff --git a/bun.lock b/bun.lock
diff --git a/packages/bcode-browser/README.md b/packages/bcode-browser/README.md
@@ -0,0 +1,21 @@
+# @browser-use/bcode-browser
+
+Level-1 BrowserCode package: substantial, self-contained code with zero upstream-fork friction.
+
+See `decisions.md §1c` (three-level model) and `§1d` (this package) in the BrowserCode project memory.
+
+## Contents (planned)
+
+| Path | Purpose | Roadmap phase |
+|---|---|---|
+| `harness/` | Vendored `browser-use/browser-harness` | A2 |
+| `src/browser-execute/` | `browser_execute` tool body | A4 |
+| `src/fetch-use/` | `FetchUse.Service` implementation | B1 |
+| `src/cloud/` | Cloud deploy, skillbase, judge clients | D3–D4 |
+
+Integration into `packages/opencode` (tool registration, service wiring, CLI commands) is Level 2 and lives in `packages/opencode/src`. Per the one-line-hook rule, those hooks are pointers only — all logic lives here.
+
+## Upstream tracking
+
+- `harness/PROVENANCE.md` — source commit SHA + edit log for the vendored harness.
+- Root-level `UPSTREAM.md` — sync log across both upstreams (opencode and harness).
diff --git a/packages/bcode-browser/harness/.gitkeep b/packages/bcode-browser/harness/.gitkeep
diff --git a/packages/bcode-browser/harness/PROVENANCE.md b/packages/bcode-browser/harness/PROVENANCE.md
@@ -0,0 +1,28 @@
+# browser-harness provenance
+
+Vendored source for the `harness/` subtree.
+
+**Upstream:** https://github.com/browser-use/browser-harness
+**Last vendored commit:** _(none yet — harness not vendored; ROADMAP A2)_
+**Last vendored date:** —
+
+## Sync log
+
+| Date | From SHA | To SHA | By | Notes |
+|---|---|---|---|---|
+| — | — | — | — | Not vendored yet. Initial vendor lands in ROADMAP A2. |
+
+## Path-allowlist policy (decisions.md §3.7, §4.5)
+
+Once the harness is vendored, the following holds:
+
+- `harness/helpers.py` — **editable** for BrowserCode needs. Changes are ours to make.
+- `harness/daemon.py`, `harness/admin.py` — **protected**. Never modify. Pulled verbatim from upstream. If behavior change needed, upstream a PR to `browser-use/browser-harness`.
+
+## Per-file edit log
+
+Append a row here whenever a vendored file is modified.
+
+| Date | File | Summary | By | Upstream-PR? |
+|---|---|---|---|---|
+| — | — | — | — | — |
diff --git a/packages/bcode-browser/package.json b/packages/bcode-browser/package.json
@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "version": "0.0.0",
+  "name": "@browser-use/bcode-browser",
+  "description": "BrowserCode Level-1 code: vendored browser-harness, FetchUse service, cloud integrations, tool implementations",
+  "type": "module",
+  "license": "MIT",
+  "private": true,
+  "scripts": {
+    "typecheck": "tsgo --noEmit"
+  },
+  "exports": {
+    "./*": "./src/*.ts"
+  },
+  "devDependencies": {
+    "@tsconfig/bun": "catalog:",
+    "@types/bun": "catalog:"
+  }
+}
diff --git a/packages/bcode-browser/src/index.ts b/packages/bcode-browser/src/index.ts
@@ -0,0 +1,17 @@
+// @browser-use/bcode-browser
+//
+// This package holds all Level-1 BrowserCode code — substantial implementation
+// that is logically self-contained and has zero upstream-fork friction.
+//
+// See decisions.md §1c (three-level model) and §1d (this package) in the
+// BrowserCode memory docs.
+//
+// Contents (planned, by ROADMAP phase):
+//   harness/               — vendored browser-harness (ROADMAP A2)
+//   src/browser-execute/   — browser_execute tool body (ROADMAP A4)
+//   src/fetch-use/         — FetchUse.Service implementation (ROADMAP B1)
+//   src/cloud/             — cloud deploy, skillbase, judge clients (Phase D)
+//
+// Integration points into packages/opencode (tool registration, service wiring,
+// CLI commands) are Level 2 — they live in packages/opencode/src, not here,
+// and must stay as minimal as possible (one-line rule).
diff --git a/packages/bcode-browser/tsconfig.json b/packages/bcode-browser/tsconfig.json
@@ -0,0 +1,7 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@tsconfig/bun/tsconfig.json",
+  "compilerOptions": {
+    "noUncheckedIndexedAccess": false
+  }
+}
diff --git a/script/check-upstream.sh b/script/check-upstream.sh
@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# check-upstream.sh — report drift from each upstream recorded in UPSTREAM.md.
+#
+# Reads the latest `To SHA` from each sync-log table in UPSTREAM.md and runs
+# `git log <recorded-sha>..<remote-head>` against the matching remote to count
+# unmerged commits.
+#
+# Usage: script/check-upstream.sh
+# Exits 0 regardless of drift — this is informational, not a gate.
+
+set -euo pipefail
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+UPSTREAM_FILE="$REPO_ROOT/UPSTREAM.md"
+
+if [[ ! -f "$UPSTREAM_FILE" ]]; then
+  echo "error: $UPSTREAM_FILE not found" >&2
+  exit 1
+fi
+
+# Parse the latest `To SHA` under each section header.
+# Section anchors are the exact "### " lines in UPSTREAM.md.
+last_sha_after() {
+  local anchor="$1"
+  awk -v anchor="$anchor" '
+    $0 ~ "^### " anchor { in_section = 1; next }
+    in_section && /^### / { in_section = 0 }
+    in_section && /^\| [0-9]{4}-[0-9]{2}-[0-9]{2} \|/ {
+      # Columns: | Date | From SHA | To SHA | By | Notes |
+      n = split($0, cols, "|")
+      # cols[1] is empty (leading |); Date=cols[2], From=cols[3], To=cols[4]
+      gsub(/^[[:space:]]+|[[:space:]]+$/, "", cols[4])
+      # Skip placeholder dashes
+      if (cols[4] != "—" && cols[4] != "-" && cols[4] != "") last = cols[4]
+    }
+    END { if (last) print last }
+  ' "$UPSTREAM_FILE"
+}
+
+report_drift() {
+  local label="$1"
+  local remote="$2"
+  local remote_branch="$3"
+  local recorded_sha="$4"
+
+  echo "=== $label ==="
+
+  if [[ -z "$recorded_sha" ]]; then
+    echo "  no sync recorded yet (nothing to compare against)"
+    echo
+    return
+  fi
+
+  if ! git remote | grep -qx "$remote"; then
+    echo "  warning: remote '$remote' not configured. Add it to see drift:"
+    echo "    git remote add $remote <url>"
+    echo
+    return
+  fi
+
+  # Strip backticks if present in the markdown cell.
+  recorded_sha="${recorded_sha//\`/}"
+
+  git fetch --quiet "$remote" "$remote_branch" 2>/dev/null || {
+    echo "  warning: could not fetch $remote/$remote_branch"
+    echo
+    return
+  }
+
+  local remote_head
+  remote_head="$(git rev-parse "$remote/$remote_branch")"
+
+  local behind
+  behind="$(git rev-list --count "$recorded_sha..$remote_head" 2>/dev/null || echo "?")"
+
+  echo "  recorded:    $recorded_sha"
+  echo "  remote HEAD: $remote_head ($remote/$remote_branch)"
+  if [[ "$behind" == "0" ]]; then
+    echo "  status:      up to date"
+  else
+    echo "  status:      $behind commits behind — review with:"
+    echo "               git log --oneline $recorded_sha..$remote/$remote_branch"
+  fi
+  echo
+}
+
+opencode_sha="$(last_sha_after 'anomalyco/opencode → this repo')"
+harness_sha="$(last_sha_after 'browser-use/browser-harness →')"
+
+report_drift "anomalyco/opencode" "upstream" "dev" "$opencode_sha"
+report_drift "browser-use/browser-harness" "harness" "main" "$harness_sha"
+
+echo "Source of truth: UPSTREAM.md. Append a row when you pull."