sid-harness 0.3.0__py3-none-any.whl

sid_harness/bridge.py

@@ -0,0 +1,851 @@
+"""sid bridge — a localhost filesystem companion for the Studio web UI.
+
+SID's web Studio runs in a browser, which cannot read the local disk (Brave also
+blocks the File System Access API by default). Claude Code / Codex / OpenCode
+avoid that limit by running a local process with filesystem tools. This bridge is
+that local process: a tiny stdlib-only HTTP server bound to 127.0.0.1 that runs
+SID's own native loop over a directory the user explicitly grants, with tools
+backed by the REAL tree (list/read on demand), and reports the proposed change
+back to the Studio.
+
+Security model:
+  * binds 127.0.0.1 only (never a public interface);
+  * a per-launch bearer token, handed to the Studio by a one-click pairing code
+    instead of a manual paste;
+  * accepts browser requests only from the SID origins (CORS + Private Network
+    Access preflight headers); a disallowed Origin is refused server-side, not
+    merely hidden by CORS;
+  * the workspace root is fixed at launch (``--dir``) and every path goes
+    through the shared denylist (``native_agent._safe_path`` / safe_rel_path);
+  * READ-ONLY by default. ``--write`` makes write mode *available*, but a write
+    still requires an explicit, per-session user grant (``POST /grant-write``)
+    before ``POST /apply`` will touch disk;
+  * an applied change is only ever a proposal the bridge itself computed, bound
+    to a digest the user reviewed, validated all-or-nothing against the shared
+    denylist, written atomically, and recorded in a receipt under the bridge
+    state directory.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import os
+import secrets
+import threading
+import time
+from dataclasses import dataclass, field
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any
+
+from .client import SIDClient
+from .gateway import native_agent
+from .local_workspace import LocalWorkspace, LocalWorkspaceError, safe_rel_path
+from .loop import run_loop
+from .receipt import utc_now
+
+DEFAULT_PORT = 8787
+MAX_LIST_PATHS = 20000
+MAX_READ_CHARS = 40000
+SKIP_DIRS = {".git", "node_modules", ".venv", "venv", "__pycache__", ".next", "dist", "build"}
+ALLOWED_ORIGINS = (
+    "https://app.superintelligencedog.com",
+    "https://superintelligencedog.com",
+)
+SEED_PATH = "WORKSPACE.md"
+SEED_CONTENT = (
+    "This is a disk-backed workspace. Use list_files to discover paths and "
+    "read_file to read any file on demand. Files are read from the real tree; "
+    "edits are returned as a proposal, not written."
+)
+
+PREVIEW_MAX_BYTES = 2_000_000
+PAIR_TTL_SECONDS = 600
+PROPOSAL_TTL_SECONDS = 3600
+MAX_PENDING_PROPOSALS = 20
+MAX_BODY_BYTES = 1_000_000
+MAX_SMALL_BODY_BYTES = 16_384
+# Paths the write path refuses in addition to the shared secret/VCS denylist.
+WRITE_BLOCKED_PARTS = frozenset({".sid"})
+WRITE_GRANT_CONFIRM = "enable-write"
+
+
+def bridge_state_dir() -> Path:
+    """Per-user bridge state (receipts, pairing metadata) — never the workspace."""
+    return Path.home() / ".sid" / "bridge"
+
+
+def _sha256_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def _sha256_text(text: str) -> str:
+    return _sha256_bytes(text.encode("utf-8"))
+
+
+def _write_json(path: Path, payload: dict[str, Any]) -> Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(path.name + ".tmp")
+    tmp.write_text(
+        json.dumps(payload, indent=2, sort_keys=True, ensure_ascii=False) + "\n",
+        encoding="utf-8",
+    )
+    os.replace(tmp, path)
+    return path
+
+
+def _decode_text(data: bytes) -> str | None:
+    if b"\x00" in data:
+        return None
+    try:
+        return data.decode("utf-8")
+    except UnicodeDecodeError:
+        return None
+
+
+def _preview_for_directory(root: str | os.PathLike[str]) -> dict[str, Any] | None:
+    base = Path(root)
+    files: list[dict[str, str]] = []
+    total = 0
+    for dirpath, dirnames, filenames in os.walk(base):
+        dirnames[:] = [d for d in dirnames if d.lower() not in SKIP_DIRS]
+        for name in filenames:
+            full = Path(dirpath) / name
+            try:
+                rel = full.relative_to(base).as_posix()
+            except ValueError:
+                continue
+            try:
+                safe = safe_rel_path(rel)
+                data = full.read_bytes()
+            except (LocalWorkspaceError, OSError):
+                continue
+            text = _decode_text(data)
+            if text is None:
+                continue
+            if total + len(text) > PREVIEW_MAX_BYTES:
+                return _finish_preview(files)
+            files.append({"path": safe, "content": text})
+            total += len(text)
+    return _finish_preview(files)
+
+
+def _finish_preview(files: list[dict[str, str]]) -> dict[str, Any] | None:
+    paths = [f["path"] for f in files]
+    entry = "index.html" if "index.html" in paths else next(
+        (p for p in sorted(paths) if p.lower().endswith((".html", ".htm"))), ""
+    )
+    if not entry:
+        return None
+    return {"entry": entry, "files": files}
+
+
+class DiskTools:
+    """The loop's ONE dispatch seam, backed by the real tree.
+
+    list_files / read_file hit disk on demand (no snapshot cap). write_file uses
+    the base contract so the loop still computes changed/readback; the loop never
+    writes disk — ``POST /apply`` is the only write path.
+    """
+
+    def __init__(self, workspace: LocalWorkspace) -> None:
+        self.ws = workspace
+        self.root = workspace.root
+
+    def schemas(self) -> list[dict[str, Any]]:
+        return native_agent.TOOLS
+
+    def _iter_paths(self) -> list[str]:
+        out: list[str] = []
+        for dirpath, dirnames, filenames in os.walk(self.root):
+            dirnames[:] = [d for d in dirnames if d.lower() not in SKIP_DIRS]
+            for name in filenames:
+                full = Path(dirpath) / name
+                try:
+                    rel = full.relative_to(self.root).as_posix()
+                except ValueError:
+                    continue
+                try:
+                    safe = safe_rel_path(rel)
+                except LocalWorkspaceError:
+                    continue
+                if self.ws.gitignore.ignored(safe):
+                    continue
+                out.append(safe)
+                if len(out) >= MAX_LIST_PATHS:
+                    return sorted(out)
+        return sorted(out)
+
+    def dispatch(self, name: str, arguments: dict[str, Any], files: dict[str, str], run_tests: Any) -> Any:
+        if name == "list_files":
+            return {"files": self._iter_paths()}
+        if name == "read_file":
+            try:
+                rel = safe_rel_path(arguments.get("path"))
+                content = self.ws.read(rel)
+            except LocalWorkspaceError as exc:
+                return {"error": str(exc)}
+            truncated = len(content) > MAX_READ_CHARS
+            return {"path": rel, "content": content[:MAX_READ_CHARS], "truncated": truncated}
+        if name == "write_file":
+            # Base contract: mutate the in-memory workspace so changed/readback
+            # are computed; nothing is written to disk here.
+            return native_agent._tool_result(
+                name, arguments, files, run_tests,
+                max_files=10**9, max_file_bytes=10**9, max_workspace_bytes=10**12,
+            )
+        if name == "run_approved_tests":
+            return run_tests(files)
+        return {"error": f"unknown tool: {name}"}
+
+
+def run_task(
+    *,
+    directory: str | os.PathLike[str],
+    task: str,
+    api_key: str,
+    base_url: str | None = None,
+    model: str = "auto",
+    test_argv: list[str] | None = None,
+) -> dict[str, Any]:
+    """Run one loop turn over the real directory; return the receipt."""
+    ws = LocalWorkspace.open(directory)
+    client = SIDClient(base_url=base_url, api_key=api_key)
+    seed = {SEED_PATH: SEED_CONTENT}
+    # SUB-94: the bridge's loop workspace is disk-backed (DiskTools), but the
+    # project policy files must travel IN the workspace map so the ONE loop
+    # loader sees them exactly as the CLI, Studio and workbench do. Reading is
+    # bounded by LocalWorkspace.read; a missing file is simply absent.
+    for rel in (*native_agent.PROJECT_RULE_FILES, native_agent.PROJECT_CONFIG_PATH):
+        try:
+            seed[rel] = ws.read(rel)
+        except (LocalWorkspaceError, OSError):
+            continue
+    return asyncio.run(
+        run_loop(
+            client=client,
+            task=task,
+            workspace_files=seed,
+            acceptance_criteria=[f"Satisfy the user's request: {task}"],
+            out_of_scope=[],
+            test_argv=list(test_argv or []),
+            workspace_root=ws.root,
+            model=model,
+            registry=DiskTools(ws),
+        )
+    )
+
+
+@dataclass
+class Proposal:
+    """One reviewed, in-memory change set. Content never leaves the process."""
+
+    id: str
+    digest: str
+    changed: list[str]
+    files: dict[str, str]
+    diff: str
+    task: str
+    created_at: float
+    public: dict[str, Any] = field(default_factory=dict)
+
+    def expired(self, ttl: float = PROPOSAL_TTL_SECONDS) -> bool:
+        return (time.time() - self.created_at) > ttl
+
+
+def proposal_digest(changed: list[str], files: dict[str, str]) -> str:
+    """Bind the reviewed paths and their exact bytes to one digest."""
+    h = hashlib.sha256()
+    for path in sorted(changed):
+        h.update(path.encode("utf-8"))
+        h.update(b"\x00")
+        h.update(bytes.fromhex(_sha256_text(files[path])))
+    return h.hexdigest()
+
+
+def _prepare_write_targets(workspace: LocalWorkspace, paths: list[str]) -> list[tuple[str, Path]]:
+    """Validate EVERY target before a single byte is written (all-or-nothing)."""
+    if not paths:
+        raise LocalWorkspaceError("no changed paths in the proposal")
+    root = workspace.root.resolve()
+    prepared: list[tuple[str, Path]] = []
+    seen: set[str] = set()
+    for raw in paths:
+        if not isinstance(raw, str):
+            raise LocalWorkspaceError("proposal paths must be strings")
+        safe = safe_rel_path(raw)
+        if safe != raw.replace("\\", "/"):
+            raise LocalWorkspaceError(f"path is not normalized: {raw!r}")
+        if safe in seen:
+            raise LocalWorkspaceError(f"duplicate path in proposal: {safe!r}")
+        if any(part.lower() in WRITE_BLOCKED_PARTS for part in safe.split("/")):
+            raise LocalWorkspaceError(f"bridge refuses to write reserved path: {safe!r}")
+        target = (root / safe).resolve()
+        if target == root or root not in target.parents:
+            raise LocalWorkspaceError(f"path escapes the workspace root: {safe!r}")
+        if target.is_dir():
+            raise LocalWorkspaceError(f"path is a directory: {safe!r}")
+        seen.add(safe)
+        prepared.append((safe, target))
+    return prepared
+
+
+def apply_proposal(
+    workspace: LocalWorkspace,
+    proposal: Proposal,
+    *,
+    receipts_dir: str | os.PathLike[str],
+    origin: str | None,
+    grant_id: str,
+) -> dict[str, Any]:
+    """Write a stored proposal after full validation; roll back on IO failure."""
+    prepared = _prepare_write_targets(workspace, list(proposal.changed))
+    for path in proposal.changed:
+        if path not in proposal.files:
+            raise LocalWorkspaceError(f"proposal changed {path!r} but has no content for it")
+
+    backups: dict[str, bytes | None] = {}
+    written: list[str] = []
+    started = utc_now()
+    try:
+        for safe, target in prepared:
+            backups[safe] = target.read_bytes() if target.is_file() else None
+            workspace.write(safe, proposal.files[safe])
+            written.append(safe)
+    except Exception:
+        for safe, old in backups.items():
+            target = workspace.root.resolve() / safe
+            try:
+                if old is None:
+                    target.unlink(missing_ok=True)
+                else:
+                    target.write_bytes(old)
+            except OSError:
+                pass
+        raise
+    finished = utc_now()
+
+    receipt = {
+        "receipt_version": 1,
+        "kind": "bridge-apply",
+        "proposal_id": proposal.id,
+        "proposal_digest": proposal.digest,
+        "task": proposal.task,
+        "dir": str(workspace.root),
+        "origin": origin or "cli",
+        "grant_id": grant_id,
+        "started_at": started,
+        "finished_at": finished,
+        "written": written,
+        "files": {
+            safe: {
+                "bytes_before": len(backups[safe] or b""),
+                "bytes_after": len(proposal.files[safe].encode("utf-8")),
+                "sha256_before": _sha256_bytes(backups[safe]) if backups[safe] is not None else None,
+                "sha256_after": _sha256_text(proposal.files[safe]),
+            }
+            for safe in written
+        },
+        "diff": proposal.diff,
+    }
+    stamp = time.strftime("%Y%m%dT%H%M%SZ", time.gmtime())
+    target = Path(receipts_dir) / f"apply_{stamp}_{proposal.id}.json"
+    receipt["receipt_path"] = str(_write_json(target, receipt))
+    return receipt
+
+
+def _cors_headers(origin: str | None, allowed_origins: tuple[str, ...] = ALLOWED_ORIGINS) -> dict[str, str]:
+    headers = {
+        "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+        "Access-Control-Allow-Headers": "Content-Type, Authorization, X-SID-Bridge-Token, X-SID-Api-Key, X-SID-Origin",
+        "Access-Control-Allow-Private-Network": "true",
+        "Access-Control-Max-Age": "600",
+    }
+    if origin and origin in allowed_origins:
+        headers["Access-Control-Allow-Origin"] = origin
+        headers["Vary"] = "Origin"
+    return headers
+
+
+class BridgeServer(ThreadingHTTPServer):
+    """Loopback-only bridge server with pairing, write grants, and proposals."""
+
+    daemon_threads = True
+    allow_reuse_address = True
+
+    def __init__(
+        self,
+        address: tuple[str, int],
+        handler: type[BaseHTTPRequestHandler],
+        *,
+        directory: Path,
+        token: str,
+        write_capable: bool,
+        pair_code: str,
+        pair_ttl: float,
+        state_dir: Path,
+        allowed_origins: tuple[str, ...],
+        base_url: str | None,
+    ) -> None:
+        super().__init__(address, handler)
+        self.bridge_dir = directory
+        self.bridge_token = token
+        self.bridge_write_capable = bool(write_capable)
+        self.bridge_pair_code = pair_code
+        self.bridge_pair_expires_at = time.time() + max(0.0, float(pair_ttl))
+        self.bridge_state_dir = state_dir
+        self.bridge_allowed_origins = tuple(allowed_origins)
+        self.bridge_base_url = base_url
+        self.bridge_paired = False
+        self.bridge_paired_at: str | None = None
+        self.bridge_write_grant: dict[str, Any] | None = None
+        self.bridge_proposals: dict[str, Proposal] = {}
+        self.bridge_lock = threading.Lock()
+
+    @property
+    def read_only(self) -> bool:
+        return self.bridge_write_grant is None
+
+    def prune_proposals(self) -> None:
+        with self.bridge_lock:
+            dead = [key for key, value in self.bridge_proposals.items() if value.expired()]
+            for key in dead:
+                self.bridge_proposals.pop(key, None)
+            while len(self.bridge_proposals) > MAX_PENDING_PROPOSALS:
+                oldest = min(self.bridge_proposals.items(), key=lambda item: item[1].created_at)[0]
+                self.bridge_proposals.pop(oldest, None)
+
+
+class BridgeHandler(BaseHTTPRequestHandler):
+    server_version = "sid-bridge/2"
+
+    def log_message(self, fmt: str, *args: Any) -> None:  # quiet by default
+        pass
+
+    @property
+    def bridge(self) -> BridgeServer:
+        return self.server  # type: ignore[return-value]
+
+    def _send(self, status: int, payload: dict[str, Any]) -> None:
+        body = json.dumps(payload).encode("utf-8")
+        try:
+            self.send_response(status)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(body)))
+            for key, value in _cors_headers(
+                self.headers.get("Origin"), self.bridge.bridge_allowed_origins
+            ).items():
+                self.send_header(key, value)
+            self.end_headers()
+            self.wfile.write(body)
+        except (BrokenPipeError, ConnectionAbortedError, ConnectionResetError):
+            pass  # a browser that navigates away mid-response is not an error
+
+    def _authed(self) -> bool:
+        token = self.bridge.bridge_token
+        supplied = (self.headers.get("X-SID-Bridge-Token") or "").strip()
+        auth = (self.headers.get("Authorization") or "").strip()
+        if auth.lower().startswith("bearer "):
+            supplied = supplied or auth[7:].strip()
+        return bool(token) and secrets.compare_digest(supplied, token)
+
+    def _origin_ok(self) -> bool:
+        """Server-side origin allowlist (CORS alone cannot protect a POST)."""
+        origin = self.headers.get("Origin")
+        return not origin or origin in self.bridge.bridge_allowed_origins
+
+    def _read_json(self, *, max_bytes: int = MAX_SMALL_BODY_BYTES) -> dict[str, Any] | None:
+        length = int(self.headers.get("Content-Length") or 0)
+        if length <= 0 or length > max_bytes:
+            self._send(400, {"error": "invalid body"})
+            return None
+        try:
+            body = json.loads(self.rfile.read(length).decode("utf-8"))
+        except Exception:
+            self._send(400, {"error": "invalid JSON"})
+            return None
+        if not isinstance(body, dict):
+            self._send(400, {"error": "JSON body must be an object"})
+            return None
+        return body
+
+    def _guard(self, *, write: bool = False) -> dict[str, Any] | None:
+        """Origin + token (+ write grant) gate shared by every state change."""
+        if not self._origin_ok():
+            self._send(403, {"error": "origin is not allowed by this bridge"})
+            return None
+        if not self._authed():
+            self._send(401, {"error": "missing or invalid bridge token"})
+            return None
+        if write:
+            grant = self.bridge.bridge_write_grant
+            if not self.bridge.bridge_write_capable:
+                self._send(403, {"error": "bridge was started read-only; restart it with --write to enable write mode"})
+                return None
+            if grant is None:
+                self._send(403, {"error": "write mode has not been granted for this session"})
+                return None
+            return grant
+        return {}
+
+    def do_OPTIONS(self) -> None:  # noqa: N802 (stdlib naming)
+        self.send_response(204)
+        for key, value in _cors_headers(
+            self.headers.get("Origin"), self.bridge.bridge_allowed_origins
+        ).items():
+            self.send_header(key, value)
+        self.send_header("Content-Length", "0")
+        self.end_headers()
+
+    def do_GET(self) -> None:  # noqa: N802
+        if self.path == "/health":
+            self._send(200, {
+                "ok": True,
+                "bridge": "sid",
+                "version": 2,
+                "dir": str(self.bridge.bridge_dir),
+                "read_only": self.bridge.read_only,
+                "write_capable": self.bridge.bridge_write_capable,
+                "write_enabled": not self.bridge.read_only,
+                "paired": self.bridge.bridge_paired,
+                "paired_at": self.bridge.bridge_paired_at,
+            })
+            return
+        self._send(404, {"error": "not found"})
+
+    def do_POST(self) -> None:  # noqa: N802
+        route = self.path.split("?", 1)[0]
+        if route == "/pair":
+            self._post_pair()
+            return
+        if route == "/grant-write":
+            self._post_grant_write()
+            return
+        if route == "/revoke-write":
+            self._post_revoke_write()
+            return
+        if route == "/run":
+            self._post_run()
+            return
+        if route == "/apply":
+            self._post_apply()
+            return
+        self._send(404, {"error": "not found"})
+
+    def _post_pair(self) -> None:
+        if not self._origin_ok():
+            self._send(403, {"error": "origin is not allowed by this bridge"})
+            return
+        body = self._read_json()
+        if body is None:
+            return
+        supplied = str(body.get("code") or "").strip()
+        if (
+            time.time() > self.bridge.bridge_pair_expires_at
+            or not supplied
+            or not secrets.compare_digest(supplied, self.bridge.bridge_pair_code)
+        ):
+            self._send(401, {"error": "invalid or expired pairing code"})
+            return
+        self.bridge.bridge_paired = True
+        self.bridge.bridge_paired_at = utc_now()
+        self._send(200, {
+            "ok": True,
+            "token": self.bridge.bridge_token,
+            "dir": str(self.bridge.bridge_dir),
+            "read_only": self.bridge.read_only,
+            "write_capable": self.bridge.bridge_write_capable,
+            "write_enabled": not self.bridge.read_only,
+        })
+
+    def _post_grant_write(self) -> None:
+        if not self._origin_ok():
+            self._send(403, {"error": "origin is not allowed by this bridge"})
+            return
+        if not self._authed():
+            self._send(401, {"error": "missing or invalid bridge token"})
+            return
+        if not self.bridge.bridge_write_capable:
+            self._send(403, {"error": "bridge was started read-only; restart it with --write to enable write mode"})
+            return
+        body = self._read_json()
+        if body is None:
+            return
+        if body.get("granted") is not True or body.get("confirm") != WRITE_GRANT_CONFIRM:
+            self._send(400, {"error": "write mode needs an explicit grant (granted=true, confirm='enable-write')"})
+            return
+        grant = {
+            "id": "grant_" + secrets.token_hex(8),
+            "granted_at": utc_now(),
+            "origin": self.headers.get("Origin") or "cli",
+            "mode": "session",
+        }
+        self.bridge.bridge_write_grant = grant
+        _write_json(
+            self.bridge.bridge_state_dir / "grants" / f"{grant['id']}.json",
+            {"kind": "bridge-write-grant", "dir": str(self.bridge.bridge_dir), **grant},
+        )
+        self._send(200, {"ok": True, "read_only": False, "grant": grant})
+
+    def _post_revoke_write(self) -> None:
+        if not self._origin_ok():
+            self._send(403, {"error": "origin is not allowed by this bridge"})
+            return
+        if not self._authed():
+            self._send(401, {"error": "missing or invalid bridge token"})
+            return
+        grant = self.bridge.bridge_write_grant
+        self.bridge.bridge_write_grant = None
+        self._send(200, {"ok": True, "read_only": True, "revoked": grant["id"] if grant else None})
+
+    def _post_run(self) -> None:
+        if not self._origin_ok():
+            self._send(403, {"error": "origin is not allowed by this bridge"})
+            return
+        if not self._authed():
+            self._send(401, {"error": "missing or invalid bridge token"})
+            return
+        body = self._read_json(max_bytes=MAX_BODY_BYTES)
+        if body is None:
+            return
+        task = str(body.get("task") or "").strip()
+        if not task:
+            self._send(400, {"error": "task is required"})
+            return
+        api_key = (self.headers.get("X-SID-Api-Key") or "").strip()
+        if not api_key:
+            self._send(400, {"error": "missing X-SID-Api-Key (the Studio passes your SID key)"})
+            return
+        test_argv = body.get("test_argv") if isinstance(body.get("test_argv"), list) else None
+        if test_argv and self.bridge.bridge_write_grant is None:
+            self._send(403, {"error": "running tests changes the machine; grant write mode first"})
+            return
+        # The browser may not choose the backend: an attacker-controlled
+        # base_url would receive the user's SID key.
+        try:
+            receipt = run_task(
+                directory=self.bridge.bridge_dir,
+                task=task,
+                api_key=api_key,
+                base_url=self.bridge.bridge_base_url,
+                model=str(body.get("model") or "auto"),
+                test_argv=test_argv,
+            )
+        except Exception as exc:  # fail closed, name it
+            self._send(502, {"error": f"{type(exc).__name__}: {exc}"})
+            return
+
+        readback = receipt.get("readback") if isinstance(receipt.get("readback"), dict) else {}
+        changed = sorted(
+            path for path in receipt.get("changed") or []
+            if isinstance(path, str) and path in readback
+        )
+        proposal_public: dict[str, Any] | None = None
+        if changed:
+            files = {path: readback[path] for path in changed}
+            proposal = Proposal(
+                id="prop_" + secrets.token_hex(8),
+                digest=proposal_digest(changed, files),
+                changed=changed,
+                files=files,
+                diff=str(receipt.get("diff") or ""),
+                task=task,
+                created_at=time.time(),
+                public={},
+            )
+            proposal.public = {
+                "id": proposal.id,
+                "digest": proposal.digest,
+                "changed": changed,
+                "diff": proposal.diff,
+                "files": [
+                    {"path": path, "bytes": len(files[path].encode("utf-8"))}
+                    for path in changed
+                ],
+                "created_at": utc_now(),
+            }
+            self.bridge.prune_proposals()
+            with self.bridge.bridge_lock:
+                self.bridge.bridge_proposals[proposal.id] = proposal
+            proposal_public = proposal.public
+
+        # The response describes the review surface; raw file contents and the
+        # full artifact map stay in the process (apply reads the stored proposal).
+        safe_receipt = {
+            key: value for key, value in receipt.items()
+            if key not in ("readback", "artifact_files", "tested_artifact_hash")
+        }
+        run_receipt = {
+            "kind": "bridge-run",
+            "task": task,
+            "dir": str(self.bridge.bridge_dir),
+            "created_at": utc_now(),
+            "read_only": self.bridge.read_only,
+            "changed": changed,
+            "proposal": proposal_public,
+            "diff": safe_receipt.get("diff"),
+            "model": safe_receipt.get("model"),
+            "steps": safe_receipt.get("steps"),
+            "tool_calls": safe_receipt.get("tool_calls"),
+            "project_rules": safe_receipt.get("project_rules"),
+        }
+        _write_json(
+            self.bridge.bridge_state_dir / "runs" / f"run_{secrets.token_hex(8)}.json",
+            run_receipt,
+        )
+        self._send(200, {
+            "ok": True,
+            "receipt": safe_receipt,
+            "proposal": proposal_public,
+            "preview": _preview_for_directory(self.bridge.bridge_dir),
+            "read_only": self.bridge.read_only,
+        })
+
+    def _post_apply(self) -> None:
+        grant = self._guard(write=True)
+        if grant is None:
+            return
+        body = self._read_json()
+        if body is None:
+            return
+        proposal_id = str(body.get("proposal_id") or "").strip()
+        digest = str(body.get("digest") or "").strip()
+        if not proposal_id or not digest:
+            self._send(400, {"error": "proposal_id and digest are required"})
+            return
+        with self.bridge.bridge_lock:
+            proposal = self.bridge.bridge_proposals.get(proposal_id)
+            if proposal is not None and proposal.expired():
+                self.bridge.bridge_proposals.pop(proposal_id, None)
+                proposal = None
+        if proposal is None:
+            self._send(409, {"error": "unknown or expired proposal; run the task again"})
+            return
+        if not secrets.compare_digest(digest, proposal.digest):
+            self._send(409, {"error": "proposal digest does not match the reviewed change"})
+            return
+        with self.bridge.bridge_lock:
+            if self.bridge.bridge_proposals.pop(proposal_id, None) is None:
+                self._send(409, {"error": "proposal was already applied"})
+                return
+        try:
+            workspace = LocalWorkspace.open(self.bridge.bridge_dir)
+            receipt = apply_proposal(
+                workspace,
+                proposal,
+                receipts_dir=self.bridge.bridge_state_dir / "receipts",
+                origin=self.headers.get("Origin"),
+                grant_id=str(grant.get("id") or ""),
+            )
+        except LocalWorkspaceError as exc:
+            self._send(403, {"error": str(exc), "written": []})
+            return
+        except Exception as exc:  # fail closed, name it
+            self._send(500, {"error": f"{type(exc).__name__}: {exc}", "written": []})
+            return
+        self._send(200, {
+            "ok": True,
+            "written": receipt["written"],
+            "receipt": receipt,
+            "receipt_path": receipt["receipt_path"],
+            "read_only": False,
+        })
+
+
+def serve(
+    directory: str | os.PathLike[str],
+    *,
+    port: int = DEFAULT_PORT,
+    token: str | None = None,
+    write_capable: bool = False,
+    pair_code: str | None = None,
+    pair_ttl: float = PAIR_TTL_SECONDS,
+    state_dir: str | os.PathLike[str] | None = None,
+    allowed_origins: tuple[str, ...] | list[str] | None = None,
+    base_url: str | None = None,
+) -> BridgeServer:
+    """Create the loopback-only bridge. Read-only unless ``write_capable``.
+
+    ``write_capable`` only makes write mode available; an explicit per-session
+    grant (``POST /grant-write``) is still required before ``POST /apply``.
+    """
+    root = Path(directory).expanduser().resolve()
+    if not root.is_dir():
+        raise SystemExit(f"sid bridge: --dir is not a directory: {root}")
+    token = token or secrets.token_urlsafe(24)
+    pair_code = pair_code or secrets.token_urlsafe(18)
+    state = Path(state_dir).expanduser().resolve() if state_dir else bridge_state_dir()
+    origins = tuple(allowed_origins) if allowed_origins is not None else ALLOWED_ORIGINS
+    return BridgeServer(
+        ("127.0.0.1", port),
+        BridgeHandler,
+        directory=root,
+        token=token,
+        write_capable=write_capable,
+        pair_code=pair_code,
+        pair_ttl=pair_ttl,
+        state_dir=state,
+        allowed_origins=origins,
+        base_url=base_url,
+    )
+
+
+def _pair_url(base_url: str, studio_url: str, code: str) -> str:
+    from urllib.parse import urlencode
+
+    fragment = urlencode({"sid-pair": code, "sid-bridge": base_url})
+    return f"{studio_url}#{fragment}"
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+
+    ap = argparse.ArgumentParser(prog="sid bridge", description="Run the localhost filesystem bridge for the SID Studio.")
+    ap.add_argument("--dir", required=True, help="Directory the Studio may read (fixed at launch).")
+    ap.add_argument("--port", type=int, default=DEFAULT_PORT)
+    ap.add_argument("--token", default=None, help="Fixed token (default: generated per launch).")
+    ap.add_argument("--pair-code", default=None, help="Fixed pairing code (default: generated per launch).")
+    ap.add_argument("--pair-ttl", type=float, default=PAIR_TTL_SECONDS)
+    ap.add_argument("--write", action="store_true", help="Make write mode available (still needs an explicit grant).")
+    ap.add_argument("--state-dir", default=None, help="Receipts/grant state directory (default: ~/.sid/bridge).")
+    ap.add_argument("--studio-url", default="https://app.superintelligencedog.com/studio.html")
+    ap.add_argument(
+        "--allow-origin",
+        action="append",
+        default=None,
+        metavar="ORIGIN",
+        help="Add a trusted Studio origin (self-hosted deployment); repeatable.",
+    )
+    ap.add_argument("--base-url", default=None, help="SID /v1 base URL used for runs (never taken from the browser).")
+    args = ap.parse_args(argv)
+    origins = ALLOWED_ORIGINS + tuple(args.allow_origin or [])
+    httpd = serve(
+        args.dir,
+        port=args.port,
+        token=args.token,
+        write_capable=args.write,
+        pair_code=args.pair_code,
+        pair_ttl=args.pair_ttl,
+        state_dir=args.state_dir,
+        allowed_origins=origins,
+        base_url=args.base_url,
+    )
+    base = f"http://127.0.0.1:{httpd.server_address[1]}"
+    print(f"sid bridge: {base}")
+    print(f"mode: {'write available (grant required)' if args.write else 'read-only'}")
+    print(f"workspace: {httpd.bridge_dir}")
+    print(f"pair this browser (one click, no token paste): {_pair_url(base, args.studio_url, httpd.bridge_pair_code)}")
+    print(f"pairing code expires: {int(max(0, httpd.bridge_pair_expires_at - time.time()))}s")
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        print("\nsid bridge: stopped")
+    finally:
+        httpd.server_close()
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())