@ictechgy/context-guard 0.4.8 → 0.4.9

package/context-guard-kit/experimental_registry.py

@@ -11,6 +11,8 @@ from __future__ import annotations
 import argparse
 from dataclasses import asdict, dataclass
 from datetime import datetime, timezone
+import http.client
+from http.server import BaseHTTPRequestHandler, HTTPServer
 import hashlib
 import ipaddress
 import json
@@ -19,6 +21,8 @@ import os
 import re
 import secrets
 import shlex
+import socket
+from socketserver import TCPServer
 from pathlib import Path
 import stat
 import sys
@@ -31,8 +35,14 @@ CONFIG_SCHEMA_VERSION = "contextguard.experiments.v1"
 DEFAULT_CONFIG = Path(".context-guard") / "experiments.json"
 MAX_CONFIG_BYTES = 64_000
 MAX_CONTEXT_DIFF_INPUT_BYTES = 256_000
+MAX_CONTEXT_DIFF_REPLACEMENT_BYTES = 128_000
+MAX_CONTEXT_DIFF_ARTIFACT_METADATA_BYTES = 64_000
+DEFAULT_CONTEXT_DIFF_ARTIFACT_DIR = Path(".context-guard") / "artifacts"
+LEGACY_CONTEXT_DIFF_ARTIFACT_DIR = Path(".claude-token-optimizer") / "artifacts"
 MAX_VISUAL_OCR_TEXT_BYTES = 64_000
 MAX_LEARNED_COMPRESSION_INPUT_BYTES = 128_000
+MAX_LEARNED_COMPRESSION_REPLACEMENT_BYTES = 64_000
+MAX_LEARNED_COMPRESSION_ARTIFACT_METADATA_BYTES = 64_000
 MAX_SELF_HOSTED_METRICS_INPUT_BYTES = 64_000
 SELF_HOSTED_METRICS_SCHEMA_VERSION = "contextguard.bench.self-hosted-metrics.v1"
 SELF_HOSTED_METRICS_KEY = "self_hosted_metrics"
@@ -48,11 +58,47 @@ TOKEN_PROXY_BYTES_PER_TOKEN = 4
 MAX_SELF_HOSTED_JSON_DEPTH = 100
 MAX_SELF_HOSTED_JSON_NODES = 10_000
 LOCAL_PROXY_SCHEMA_VERSION = "contextguard.experiments.local-proxy-plan.v1"
+LOCAL_PROXY_GATE_SCHEMA_VERSION = "contextguard.experiments.local-proxy-gate.v1"
+LOCAL_PROXY_FORWARD_SCHEMA_VERSION = "contextguard.experiments.local-proxy-forward.v1"
+LOCAL_PROXY_DIAGNOSTIC_SCHEMA_VERSION = "contextguard.experiments.local-proxy-forward-diagnostic.v1"
+LOCAL_PROXY_READY_SCHEMA_VERSION = "contextguard.experiments.local-proxy-ready.v1"
+LOCAL_PROXY_EXTERNAL_DESIGN_SCHEMA_VERSION = "contextguard.experiments.local-proxy-external-forwarding-design.v1"
 LOCAL_PROXY_DEFAULT_BIND_HOST = "127.0.0.1"
 LOCAL_PROXY_DEFAULT_BIND_PORT = 0
 LOCAL_PROXY_DEFAULT_TARGET_HOST = "127.0.0.1"
 LOCAL_PROXY_DEFAULT_TARGET_PORT = 0
 LOCAL_PROXY_LOCALHOST_NAMES = {"localhost"}
+LOCAL_PROXY_TRUE_VALUES = {"1", "on", "true", "yes", "y"}
+LOCAL_PROXY_FALSE_VALUES = {"", "0", "false", "n", "no", "off"}
+LOCAL_PROXY_DEFAULT_MAX_REQUEST_BYTES = 64 * 1024
+LOCAL_PROXY_DEFAULT_MAX_RESPONSE_BYTES = 256 * 1024
+LOCAL_PROXY_MAX_FORWARD_BYTES = 2 * 1024 * 1024
+LOCAL_PROXY_DEFAULT_TIMEOUT_SECONDS = 5.0
+LOCAL_PROXY_MAX_TIMEOUT_SECONDS = 30.0
+LOCAL_PROXY_EXTERNAL_ALLOWED_SCHEMES = {"https"}
+LOCAL_PROXY_EXTERNAL_CREDENTIAL_REDACTION_POLICY = "strip-sensitive-headers"
+LOCAL_PROXY_EXTERNAL_PROVIDER_EVIDENCE_BOUNDARY = "diagnostic-only-provider-measured-required"
+LOCAL_PROXY_SENSITIVE_HEADER_NAMES = {
+    "authorization",
+    "proxy-authorization",
+    "x-api-key",
+    "api-key",
+    "x-anthropic-api-key",
+    "x-openai-api-key",
+    "openai-api-key",
+    "cookie",
+    "set-cookie",
+}
+LOCAL_PROXY_HOP_BY_HOP_HEADERS = {
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+}
 ALLOWED_FIRST_COMPONENT_SYMLINKS = {
     "tmp": Path("/private/tmp"),
     "var": Path("/private/var"),
@@ -145,37 +191,51 @@ EXPERIMENTS: tuple[Experiment, ...] = (
     Experiment(
         id="context-diff-compaction",
         name="Reviewable context-diff compaction",
-        summary="Dry-run advisory lane for human-reviewable compaction plans with stable exact handles.",
+        summary="Explicit receipt-backed runtime for caller-supplied compact diff replacements with stable exact handles.",
         stability="experimental",
         default_enabled=False,
         risk_level="medium",
         claim_boundary="Smaller local diffs are proxy evidence only; hosted savings require provider-measured matched tasks.",
         gate_requirements=("explicit opt-in", "human-reviewable diff", "local receipt", "exact re-expand handle"),
-        runtime_status="available-dry-run",
-        commands=("context-guard experiments plan context-diff-compaction",),
-        opt_in_flags=("plan context-diff-compaction", "--receipt-id", "--reexpand-command"),
+        runtime_status="available-explicit-runtime",
+        commands=(
+            "context-guard experiments plan context-diff-compaction",
+            "context-guard experiments emit context-diff-compaction --receipt-id <id> --reexpand-command <cmd>",
+        ),
+        opt_in_flags=(
+            "plan context-diff-compaction",
+            "emit context-diff-compaction",
+            "--receipt-id",
+            "--reexpand-command",
+            "--replacement-text|--replacement-file",
+        ),
         config_effect=(
-            "Registry enablement records project-local intent only; context-diff compaction remains a dry-run plan "
-            "unless a future story adds an explicit replacement command."
+            "Registry enablement records project-local intent only; context-diff replacement emits only through the "
+            "explicit emit command with exact retrieval metadata and caller-supplied compact text."
         ),
         evidence_contract=(
-            "Dry-run plans require human-reviewable hunks plus user-supplied exact receipt and re-expand handles before "
-            "any future lossy replacement can be reviewed."
+            "Emitted replacements require human-reviewable hunks, caller-supplied compact text, and exact local "
+            "artifact content that matches the input diff plus re-expand metadata; smaller local diffs remain proxy "
+            "evidence only."
         ),
     ),
     Experiment(
         id="visual-crop-ocr",
-        name="Visual crop/OCR evidence planning",
-        summary="Dry-run fixture lane for comparing full visual evidence with cropped or OCR-derived evidence.",
+        name="Visual crop/OCR evidence pack",
+        summary="Explicit local runtime for caller-supplied visual crop/OCR evidence packs.",
         stability="experimental",
         default_enabled=False,
         risk_level="medium",
         claim_boundary="Image/OCR byte reductions are proxy evidence until provider image/text token fields are measured.",
         gate_requirements=("explicit opt-in", "original evidence preserved", "confidence/error notes", "missed-context guardrail"),
-        runtime_status="available-dry-run",
-        commands=("context-guard experiments plan visual-crop-ocr",),
+        runtime_status="available-explicit-runtime",
+        commands=(
+            "context-guard experiments plan visual-crop-ocr",
+            "context-guard experiments emit visual-crop-ocr",
+        ),
         opt_in_flags=(
             "plan visual-crop-ocr",
+            "emit visual-crop-ocr",
             "--full-evidence-receipt",
             "--crop-bounds",
             "--image-size",
@@ -185,48 +245,64 @@ EXPERIMENTS: tuple[Experiment, ...] = (
             "--missed-context-note",
         ),
         config_effect=(
-            "Registry enablement records project-local intent only; visual crop/OCR planning remains a dry-run "
-            "metadata surface and does not run OCR, crop images, call providers, or change stable behavior."
+            "Registry enablement records project-local intent only; visual crop/OCR evidence packs emit only through "
+            "the explicit emit command and do not run OCR, crop images, call providers, write files, or change stable behavior."
         ),
         evidence_contract=(
-            "Dry-run plans require retrievable full visual evidence plus crop/OCR confidence, error, and "
-            "missed-context guardrails before human review."
+            "Emitted evidence packs require the full visual evidence receipt plus caller-supplied crop/OCR evidence, "
+            "OCR confidence/error notes when OCR is present, and missed-context guardrails before human review."
         ),
     ),
     Experiment(
         id="learned-compression",
-        name="Learned/synthetic compression safe gate",
-        summary="Deny-by-default dry-run safety gate for already-sanitized unprotected prose only.",
+        name="Learned/synthetic compression candidate gate",
+        summary="Explicit local runtime for caller-supplied compact prose candidates with verified exact fallback.",
         stability="experimental",
         default_enabled=False,
         risk_level="high",
         claim_boundary="Semantic compression cannot claim savings or correctness without matched-task quality and provider token evidence.",
         gate_requirements=("explicit opt-in", "sanitized unprotected prose only", "protected-zone denial", "exact fallback or receipt"),
-        runtime_status="available-dry-run",
-        commands=("context-guard experiments plan learned-compression",),
-        opt_in_flags=("plan learned-compression", "--sanitized", "--trusted-source", "--exact-fallback-receipt", "--reexpand-command"),
+        runtime_status="available-explicit-runtime",
+        commands=(
+            "context-guard experiments plan learned-compression",
+            "context-guard experiments emit learned-compression --exact-fallback-receipt <id> --reexpand-command <cmd>",
+        ),
+        opt_in_flags=(
+            "plan learned-compression",
+            "emit learned-compression",
+            "--sanitized",
+            "--trusted-source",
+            "--exact-fallback-receipt",
+            "--reexpand-command",
+            "--replacement-text|--replacement-file",
+        ),
         config_effect=(
-            "Registry enablement records project-local intent only; learned compression remains a dry-run policy check "
-            "and does not run learned compressors, embeddings, model calls, or replacements."
+            "Registry enablement records project-local intent only; learned-compression candidates emit only through "
+            "the explicit emit command and do not run learned compressors, embeddings, rerankers, model calls, subprocesses, or external services."
         ),
         evidence_contract=(
-            "Dry-run eligibility requires caller-asserted sanitized trusted prose, exact local fallback handles, and "
-            "denial of protected or prompt-like signals."
+            "Emitted candidates require caller-asserted sanitized trusted prose, verified exact local fallback content, "
+            "a smaller caller-supplied prose candidate, and denial of protected or prompt-like signals."
         ),
     ),
     Experiment(
         id="self-hosted-metrics-ledger",
         name="Self-hosted metrics ledger",
-        summary="Dry-run checker for self-hosted/local metrics ledger sidecars kept separate from hosted API claims.",
+        summary="Explicit local ledger runtime for self-hosted/local metrics sidecars kept separate from hosted API claims.",
         stability="experimental",
         default_enabled=False,
         risk_level="low",
         claim_boundary="Self-hosted memory/latency metrics must stay separate from hosted API token/cost claims.",
         gate_requirements=("explicit opt-in", "separate ledger fields", "shifted-cost accounting"),
-        runtime_status="available-dry-run",
-        commands=("context-guard experiments plan self-hosted-metrics-ledger",),
+        runtime_status="available-explicit-runtime",
+        commands=(
+            "context-guard experiments plan self-hosted-metrics-ledger",
+            "context-guard experiments record self-hosted-metrics-ledger --ledger-jsonl <path>",
+        ),
         opt_in_flags=(
             "plan self-hosted-metrics-ledger",
+            "record self-hosted-metrics-ledger",
+            "--ledger-jsonl",
             "--input",
             "--latency-ms",
             "--peak-memory-mb",
@@ -238,43 +314,68 @@ EXPERIMENTS: tuple[Experiment, ...] = (
             "--optimization",
         ),
         config_effect=(
-            "Registry enablement records project-local intent only; self-hosted metrics planning remains a dry-run "
-            "ledger-preview surface and does not write ledgers or alter benchmark/report behavior."
+            "Registry enablement records project-local intent only; self-hosted metrics still write a ledger only "
+            "when the explicit record command is invoked with --ledger-jsonl."
         ),
         evidence_contract=(
-            "Real evidence belongs in context-guard-bench JSONL ledger sidecars; self-hosted metrics remain separate "
-            "from hosted API token/cost savings."
+            "The explicit record command writes context-guard-bench JSONL ledger sidecars; self-hosted metrics "
+            "remain separate from hosted API token/cost savings."
         ),
     ),
     Experiment(
         id="local-proxy",
-        name="Local proxy advisory lane",
-        summary="Dry-run localhost-only proxy advisory plan with no hidden forwarding or API-key persistence.",
+        name="Local proxy runtime gate",
+        summary="Explicit local gate-record runtime for localhost-only proxy experiments with no hidden forwarding or API-key persistence.",
         stability="experimental",
         default_enabled=False,
         risk_level="high",
         claim_boundary="Proxy metrics are diagnostic only; no hosted savings claim without provider-measured evidence.",
         gate_requirements=("explicit opt-in", "localhost-only default", "no API-key persistence", "no hidden external forwarding"),
-        runtime_status="available-dry-run",
-        commands=("context-guard experiments plan local-proxy",),
+        runtime_status="available-explicit-runtime",
+        commands=(
+            "context-guard experiments plan local-proxy",
+            "context-guard experiments plan local-proxy-external-forwarding",
+            "context-guard experiments record local-proxy-runtime-gate --ledger-jsonl <path>",
+            "context-guard experiments serve local-proxy --bind-host 127.0.0.1 --bind-port <port> --target-host 127.0.0.1 --target-port <port> --runtime-gate-ack --forwarding-gate-ack --once",
+            "context-guard experiments serve local-proxy --diagnostic-ledger-jsonl <path> ...",
+        ),
         opt_in_flags=(
             "plan local-proxy",
+            "plan local-proxy-external-forwarding",
+            "record local-proxy-runtime-gate",
+            "serve local-proxy",
             "--bind-host",
             "--bind-port",
             "--target-host",
             "--target-port",
             "--upstream-url",
+            "--ledger-jsonl",
             "--runtime-gate-ack",
+            "--forwarding-gate-ack",
+            "--once",
+            "--max-request-bytes",
+            "--max-response-bytes",
+            "--diagnostic-ledger-jsonl",
             "--external-forwarding-intent",
+            "--external-forwarding-design-ack",
+            "--allow-host",
+            "--allow-scheme",
+            "--threat-model-note",
+            "--credential-redaction-policy",
+            "--provider-evidence-boundary",
             "--persist-api-key",
         ),
         config_effect=(
-            "Registry enablement records project-local intent only; local proxy planning remains a dry-run advisory "
-            "surface and does not bind sockets, forward traffic, persist API keys, or write ledgers."
+            "Registry enablement records project-local intent only; local proxy record/serve runtimes run only through "
+            "explicit commands. Serve binds and forwards only literal loopback addresses, blocks credential material, "
+            "and never persists API keys or calls non-local services; external-forwarding planning is design-only."
         ),
         evidence_contract=(
-            "Dry-run plans require localhost-only bind/target metadata, explicit runtime gate acknowledgement before "
-            "any future forwarding, and no raw API-key persistence."
+            "Gate rows require localhost-only bind/target metadata and explicit runtime gate acknowledgement. Serve "
+            "evidence requires loopback-only bind/target IPs, explicit forwarding acknowledgement, no credential "
+            "forwarding or persistence, bounded bytes/timeouts, and optional diagnostic ledger rows that remain "
+            "shifted-cost evidence only. External-forwarding design plans require threat model notes, explicit "
+            "allowlists, credential redaction policy, and provider-evidence boundaries before any future runtime."
         ),
     ),
 )
@@ -337,6 +438,18 @@ def _temp_file_open_flags(*, label: str) -> int:
     return flags
 
 
+def _append_file_open_flags(*, label: str) -> int:
+    flags = os.O_WRONLY | os.O_CREAT | os.O_APPEND
+    flags |= _no_follow_flag(label=label)
+    if hasattr(os, "O_CLOEXEC"):
+        flags |= os.O_CLOEXEC
+    if hasattr(os, "O_NONBLOCK"):
+        flags |= os.O_NONBLOCK
+    if hasattr(os, "O_NOCTTY"):
+        flags |= os.O_NOCTTY
+    return flags
+
+
 def _leaf_name(path: Path, *, label: str) -> str:
     name = path.name
     if name in {"", ".", ".."}:
@@ -591,6 +704,149 @@ def write_regular_file_no_follow(path: Path, data: bytes, *, label: str) -> None
             pass
 
 
+def _reject_parent_traversal(path: Path, *, label: str) -> None:
+    if any(part == ".." for part in path.parts):
+        raise RegistryError(f"{label} must not contain parent traversal")
+
+
+def write_regular_file_no_follow_exclusive(path: Path, data: bytes, *, label: str, mode: int = 0o600) -> None:
+    _reject_parent_traversal(path, label=label)
+    path = normalize_local_path(path)
+    parent_fd = open_directory_no_follow(path.parent, label=f"{label} parent")
+    if parent_fd is None:  # pragma: no cover - missing_ok is not enabled.
+        raise RegistryError(f"could not inspect {label} parent")
+    fd = -1
+    created = False
+    success = False
+    try:
+        leaf = _leaf_name(path, label=label)
+        exists = _precheck_regular_leaf(parent_fd, leaf, label=label, missing_ok=True)
+        if exists:
+            raise RegistryError(f"{label} must not already exist")
+        flags = _temp_file_open_flags(label=label)
+        fd = os.open(leaf, flags, mode, dir_fd=parent_fd)
+        created = True
+        if not stat.S_ISREG(os.fstat(fd).st_mode):
+            raise RegistryError(f"{label} must be a regular file")
+        try:
+            os.fchmod(fd, mode)
+        except OSError:
+            pass
+        write_all_fd(fd, data)
+        try:
+            os.fsync(fd)
+        except OSError:
+            pass
+        success = True
+    except FileExistsError as exc:
+        raise RegistryError(f"{label} must not already exist") from exc
+    except OSError as exc:
+        raise RegistryError(f"could not write {label}: {os_error_detail(exc)}") from exc
+    finally:
+        if fd >= 0:
+            try:
+                os.close(fd)
+            except OSError:
+                pass
+        if created and not success:
+            try:
+                os.unlink(_leaf_name(path, label=label), dir_fd=parent_fd)
+            except OSError:
+                pass
+        try:
+            os.fsync(parent_fd)
+        except OSError:
+            pass
+        try:
+            os.close(parent_fd)
+        except OSError:
+            pass
+
+
+def append_jsonl_no_follow(path: Path, payload: dict[str, Any], *, label: str) -> int:
+    path = normalize_local_path(path)
+    parent_fd = open_directory_no_follow(path.parent, label=f"{label} parent", create=True)
+    if parent_fd is None:  # pragma: no cover - create=True never returns None.
+        raise RegistryError(f"could not inspect {label} parent")
+    fd = -1
+    try:
+        leaf = _leaf_name(path, label=label)
+        _precheck_regular_leaf(parent_fd, leaf, label=label, missing_ok=True)
+        fd = os.open(leaf, _append_file_open_flags(label=label), 0o600, dir_fd=parent_fd)
+        if not stat.S_ISREG(os.fstat(fd).st_mode):
+            raise RegistryError(f"{label} must be a regular file")
+        data = json.dumps(payload, ensure_ascii=False, sort_keys=True).encode("utf-8") + b"\n"
+        write_all_fd(fd, data)
+        try:
+            os.fsync(fd)
+        except OSError:
+            pass
+        return len(data)
+    except OSError as exc:
+        raise RegistryError(f"could not append {label}: {os_error_detail(exc)}") from exc
+    finally:
+        if fd >= 0:
+            try:
+                os.close(fd)
+            except OSError:
+                pass
+        try:
+            os.fsync(parent_fd)
+        except OSError:
+            pass
+        try:
+            os.close(parent_fd)
+        except OSError:
+            pass
+
+
+def preflight_append_jsonl_no_follow(path: Path, *, label: str) -> None:
+    """Validate that a JSONL append target is no-follow appendable before side effects."""
+    path = normalize_local_path(path)
+    parent_fd = open_directory_no_follow(path.parent, label=f"{label} parent", create=True)
+    if parent_fd is None:  # pragma: no cover - create=True never returns None.
+        raise RegistryError(f"could not inspect {label} parent")
+    fd = -1
+    temp_leaf: str | None = None
+    try:
+        leaf = _leaf_name(path, label=label)
+        exists = _precheck_regular_leaf(parent_fd, leaf, label=label, missing_ok=True)
+        if exists:
+            fd = os.open(leaf, _append_file_open_flags(label=label), 0o600, dir_fd=parent_fd)
+            if not stat.S_ISREG(os.fstat(fd).st_mode):
+                raise RegistryError(f"{label} must be a regular file")
+            return
+        for _attempt in range(20):
+            candidate = _leaf_name(Path(f".{leaf}.{os.getpid()}.{secrets.token_hex(8)}.preflight"), label=f"{label} preflight")
+            try:
+                fd = os.open(candidate, _temp_file_open_flags(label=f"{label} preflight"), 0o600, dir_fd=parent_fd)
+                temp_leaf = candidate
+                break
+            except FileExistsError:
+                continue
+        if fd < 0 or temp_leaf is None:
+            raise RegistryError(f"could not create temporary {label} preflight")
+        if not stat.S_ISREG(os.fstat(fd).st_mode):
+            raise RegistryError(f"{label} preflight temp must be a regular file")
+    except OSError as exc:
+        raise RegistryError(f"could not append {label}: {os_error_detail(exc)}") from exc
+    finally:
+        if fd >= 0:
+            try:
+                os.close(fd)
+            except OSError:
+                pass
+        if temp_leaf is not None:
+            try:
+                os.unlink(temp_leaf, dir_fd=parent_fd)
+            except OSError:
+                pass
+        try:
+            os.close(parent_fd)
+        except OSError:
+            pass
+
+
 def resolve_root(raw_root: str | None) -> Path:
     root = Path(raw_root) if raw_root else Path.cwd()
     try:
@@ -762,6 +1018,7 @@ def command_disable(args: argparse.Namespace) -> int:
 
 DIFF_GIT_RE = re.compile(r"^diff --git (?P<old>\S+) (?P<new>\S+)$")
 HUNK_RE = re.compile(r"^@@\s+-(?P<old_start>\d+)(?:,(?P<old_count>\d+))?\s+\+(?P<new_start>\d+)(?:,(?P<new_count>\d+))?\s+@@(?P<section>.*)$")
+CONTEXT_DIFF_ARTIFACT_ID_RE = re.compile(r"^[a-f0-9]{16,64}$")
 
 
 def read_bounded_input(args: argparse.Namespace) -> tuple[str, dict[str, Any]]:
@@ -800,13 +1057,16 @@ def strip_diff_prefix(path: str) -> str:
 def summarize_diff(text: str, *, max_files: int = 50, max_hunks: int = 200) -> dict[str, Any]:
     files: list[dict[str, Any]] = []
     current: dict[str, Any] | None = None
+    current_hunk: dict[str, Any] | None = None
     total_hunks = 0
+    summarized_hunks = 0
     lines = text.splitlines()
     diff_header_count = 0
     for line_number, line in enumerate(lines, start=1):
         match = DIFF_GIT_RE.match(line)
         if match:
             diff_header_count += 1
+            current_hunk = None
             if len(files) >= max_files:
                 current = None
                 continue
@@ -823,28 +1083,199 @@ def summarize_diff(text: str, *, max_files: int = 50, max_hunks: int = 200) -> d
             total_hunks += 1
             if current is None:
                 if len(files) >= max_files:
+                    current_hunk = None
                     continue
                 current = {"old_path": None, "new_path": None, "diff_header_line": None, "hunks": []}
                 files.append(current)
             if len(current["hunks"]) < max_hunks:
-                current["hunks"].append(
-                    {
-                        "line": line_number,
-                        "old_start": int(hunk.group("old_start")),
-                        "old_count": int(hunk.group("old_count") or "1"),
-                        "new_start": int(hunk.group("new_start")),
-                        "new_count": int(hunk.group("new_count") or "1"),
-                        "section": hunk.group("section").strip()[:120],
-                    }
-                )
+                current_hunk = {
+                    "line": line_number,
+                    "old_start": int(hunk.group("old_start")),
+                    "old_count": int(hunk.group("old_count") or "1"),
+                    "new_start": int(hunk.group("new_start")),
+                    "new_count": int(hunk.group("new_count") or "1"),
+                    "section": hunk.group("section").strip()[:120],
+                    "added_lines": 0,
+                    "removed_lines": 0,
+                    "context_lines": 0,
+                    "body_lines": 0,
+                    "reviewable": False,
+                }
+                current["hunks"].append(current_hunk)
+                summarized_hunks += 1
+            else:
+                current_hunk = None
+            continue
+        if current_hunk is not None:
+            changed = False
+            if line.startswith("+") and not line.startswith("+++"):
+                current_hunk["added_lines"] += 1
+                changed = True
+            elif line.startswith("-") and not line.startswith("---"):
+                current_hunk["removed_lines"] += 1
+                changed = True
+            elif line.startswith(" "):
+                current_hunk["context_lines"] += 1
+            else:
+                continue
+            current_hunk["body_lines"] += 1
+    reviewable_hunks = 0
+    malformed_hunks = 0
+    for file_summary in files:
+        for hunk_summary in file_summary["hunks"]:
+            old_body_lines = hunk_summary["removed_lines"] + hunk_summary["context_lines"]
+            new_body_lines = hunk_summary["added_lines"] + hunk_summary["context_lines"]
+            has_changes = bool(hunk_summary["added_lines"] or hunk_summary["removed_lines"])
+            well_formed = (
+                old_body_lines == hunk_summary["old_count"]
+                and new_body_lines == hunk_summary["new_count"]
+            )
+            hunk_summary["old_body_lines"] = old_body_lines
+            hunk_summary["new_body_lines"] = new_body_lines
+            hunk_summary["has_changes"] = has_changes
+            hunk_summary["well_formed"] = well_formed
+            hunk_summary["reviewable"] = bool(has_changes and well_formed)
+            if hunk_summary["reviewable"]:
+                reviewable_hunks += 1
+            elif not well_formed:
+                malformed_hunks += 1
     return {
         "file_count": len(files),
         "hunk_count": total_hunks,
+        "summarized_hunk_count": summarized_hunks,
+        "reviewable_hunk_count": reviewable_hunks,
+        "malformed_hunk_count": malformed_hunks,
         "truncated_files": max(0, diff_header_count - len(files)),
+        "truncated_hunks": max(0, total_hunks - summarized_hunks),
         "files": files,
     }
 
 
+def valid_context_diff_reexpand_command(receipt_id: str | None, command: str | None) -> tuple[bool, str | None]:
+    if not receipt_id or not command:
+        return False, "missing_exact_receipt_or_reexpand_command"
+    if not CONTEXT_DIFF_ARTIFACT_ID_RE.fullmatch(receipt_id):
+        return False, "invalid_reexpand_command"
+    if any(token in command for token in (";", "|", "&", ">", "<", "`", "$", "\n", "\r")):
+        return False, "invalid_reexpand_command"
+    try:
+        argv = shlex.split(command)
+    except ValueError:
+        return False, "invalid_reexpand_command"
+    if argv == ["context-guard-artifact", "get", receipt_id, "--full"]:
+        return True, None
+    if argv == ["context-guard", "artifact", "get", receipt_id, "--full"]:
+        return True, None
+    return False, "invalid_reexpand_command"
+
+
+def context_diff_artifact_read_dirs() -> list[Path]:
+    return [DEFAULT_CONTEXT_DIFF_ARTIFACT_DIR, LEGACY_CONTEXT_DIFF_ARTIFACT_DIR]
+
+
+def context_diff_artifact_paths(directory: Path, receipt_id: str) -> tuple[Path, Path]:
+    return directory / f"{receipt_id}.txt", directory / f"{receipt_id}.json"
+
+
+def verify_context_diff_artifact(
+    receipt_id: str | None,
+    *,
+    expected_sha256: str,
+    expected_bytes: int,
+) -> tuple[bool, str | None, dict[str, Any]]:
+    if not receipt_id or not CONTEXT_DIFF_ARTIFACT_ID_RE.fullmatch(receipt_id):
+        return False, "invalid_reexpand_command", {"checked": False, "read_directories": []}
+    read_dirs = context_diff_artifact_read_dirs()
+    details: dict[str, Any] = {
+        "checked": True,
+        "read_directories": [str(path) for path in read_dirs],
+        "matched_directory": None,
+        "content_sha256": None,
+        "content_bytes": None,
+    }
+    for directory in read_dirs:
+        content_path, meta_path = context_diff_artifact_paths(directory, receipt_id)
+        meta_loaded = read_bounded_regular_file(
+            meta_path,
+            max_bytes=MAX_CONTEXT_DIFF_ARTIFACT_METADATA_BYTES,
+            label="context-diff artifact metadata",
+            missing_ok=True,
+        )
+        content_loaded = read_bounded_regular_file(
+            content_path,
+            max_bytes=max(MAX_CONTEXT_DIFF_INPUT_BYTES, expected_bytes),
+            label="context-diff artifact content",
+            missing_ok=True,
+        )
+        if meta_loaded is None and content_loaded is None:
+            continue
+        if meta_loaded is None or content_loaded is None:
+            return False, "artifact_receipt_invalid", details
+        meta_raw, meta_truncated = meta_loaded
+        content_raw, content_truncated = content_loaded
+        if meta_truncated or content_truncated:
+            return False, "artifact_receipt_invalid", details
+        try:
+            metadata = json.loads(meta_raw.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError):
+            return False, "artifact_receipt_invalid", details
+        if not isinstance(metadata, dict) or metadata.get("artifact_id") != receipt_id:
+            return False, "artifact_receipt_invalid", details
+        stored = metadata.get("stored_output")
+        stored_sha = stored.get("sha256") if isinstance(stored, dict) else None
+        stored_bytes = stored.get("bytes") if isinstance(stored, dict) else None
+        actual_sha = hashlib.sha256(content_raw).hexdigest()
+        actual_bytes = len(content_raw)
+        details.update({
+            "matched_directory": str(directory),
+            "content_sha256": actual_sha,
+            "content_bytes": actual_bytes,
+        })
+        if stored_sha != actual_sha or stored_bytes != actual_bytes:
+            return False, "artifact_receipt_invalid", details
+        if actual_sha != expected_sha256 or actual_bytes != expected_bytes:
+            return False, "artifact_content_mismatch", details
+        return True, None, details
+    return False, "artifact_receipt_not_found", details
+
+
+def read_context_diff_replacement(args: argparse.Namespace) -> tuple[str | None, dict[str, Any]]:
+    if args.replacement_text is not None and args.replacement_file:
+        raise RegistryError("context-diff-compaction emit accepts only one of --replacement-text or --replacement-file")
+    if args.replacement_text is not None:
+        text = str(args.replacement_text)
+        raw = text.encode("utf-8")
+        truncated = len(raw) > MAX_CONTEXT_DIFF_REPLACEMENT_BYTES
+        raw = raw[:MAX_CONTEXT_DIFF_REPLACEMENT_BYTES]
+        text = raw.decode("utf-8", errors="replace")
+        source_label = "inline"
+    elif args.replacement_file:
+        path = Path(args.replacement_file)
+        loaded = read_bounded_regular_file(
+            path,
+            max_bytes=MAX_CONTEXT_DIFF_REPLACEMENT_BYTES,
+            label="context-diff replacement",
+        )
+        assert loaded is not None
+        raw, truncated = loaded
+        text = raw.decode("utf-8", errors="replace")
+        source_label = str(path)
+    else:
+        text = None
+        raw = b""
+        truncated = False
+        source_label = None
+    metadata = {
+        "source_label": source_label,
+        "bytes": len(raw),
+        "lines": len(text.splitlines()) if text is not None else 0,
+        "sha256": hashlib.sha256(raw).hexdigest() if text is not None else None,
+        "truncated": truncated,
+        "max_bytes": MAX_CONTEXT_DIFF_REPLACEMENT_BYTES,
+    }
+    return text, metadata
+
+
 def context_diff_plan_payload(args: argparse.Namespace) -> dict[str, Any]:
     text, input_meta = read_bounded_input(args)
     summary = summarize_diff(text)
@@ -856,7 +1287,11 @@ def context_diff_plan_payload(args: argparse.Namespace) -> dict[str, Any]:
         readiness_blockers.append("missing_exact_receipt_or_reexpand_command")
     if input_meta["truncated"]:
         readiness_blockers.append("input_truncated")
-    if summary["file_count"] == 0 or summary["hunk_count"] == 0:
+    if summary.get("truncated_files", 0) or summary.get("truncated_hunks", 0):
+        readiness_blockers.append("diff_summary_truncated")
+    if summary.get("malformed_hunk_count", 0):
+        readiness_blockers.append("malformed_diff_hunks")
+    if summary["file_count"] == 0 or summary.get("reviewable_hunk_count", 0) == 0:
         readiness_blockers.append("no_reviewable_diff_hunks")
     status = (
         "ready_for_human_review"
@@ -885,7 +1320,7 @@ def context_diff_plan_payload(args: argparse.Namespace) -> dict[str, Any]:
             "artifact_id": receipt_id,
             "cli": reexpand_command,
             "verified": False,
-            "note": "G003 records user-supplied handles for human review only; it does not verify local receipt storage.",
+            "note": "Dry-run planning records user-supplied handles for human review only; it does not verify local receipt storage.",
         },
         "review_plan": {
             "summary": summary,
@@ -928,6 +1363,119 @@ def command_plan_context_diff_compaction(args: argparse.Namespace) -> int:
     return 0
 
 
+def context_diff_emit_payload(args: argparse.Namespace) -> dict[str, Any]:
+    payload = context_diff_plan_payload(args)
+    receipt_id = args.receipt_id.strip() if args.receipt_id else None
+    reexpand_command = args.reexpand_command.strip() if args.reexpand_command else None
+    reexpand_valid, reexpand_blocker = valid_context_diff_reexpand_command(receipt_id, reexpand_command)
+    replacement_text, replacement_meta = read_context_diff_replacement(args)
+    artifact_verified = False
+    artifact_blocker = None
+    artifact_verification: dict[str, Any] = {"checked": False, "read_directories": []}
+    if reexpand_valid:
+        artifact_verified, artifact_blocker, artifact_verification = verify_context_diff_artifact(
+            receipt_id,
+            expected_sha256=payload["input"]["sha256"],
+            expected_bytes=payload["input"]["bytes"],
+        )
+
+    blockers = list(payload["review_plan"]["readiness_blockers"])
+    if reexpand_blocker:
+        blockers.append(reexpand_blocker)
+    if artifact_blocker:
+        blockers.append(artifact_blocker)
+    if replacement_text is None or not replacement_text.strip():
+        blockers.append("missing_compacted_replacement")
+    if replacement_meta["truncated"]:
+        blockers.append("replacement_truncated")
+    if (
+        replacement_text is not None
+        and not replacement_meta["truncated"]
+        and replacement_meta["bytes"] >= payload["input"]["bytes"]
+    ):
+        blockers.append("replacement_not_smaller_than_input")
+    blockers = list(dict.fromkeys(blockers))
+    ready = not blockers
+
+    replacement_record = None
+    if ready and replacement_text is not None:
+        replacement_record = {
+            "text": replacement_text,
+            "bytes": replacement_meta["bytes"],
+            "lines": replacement_meta["lines"],
+            "sha256": replacement_meta["sha256"],
+            "source_label": replacement_meta["source_label"],
+        }
+
+    payload["mode"] = "emit"
+    payload["status"] = "replacement_emitted" if ready else "blocked_until_emit_ready"
+    payload["transform_policy"] = {
+        "automatic_compaction": False,
+        "lossy_replacement_allowed": ready,
+        "semantic_rewrite_allowed": False,
+        "caller_supplied_replacement_required": True,
+        "human_review_required": True,
+        "stable_runtime_behavior_changed": False,
+    }
+    payload["exact_retrieval"] = {
+        "required": True,
+        "available": bool(receipt_id and reexpand_command and reexpand_valid and artifact_verified),
+        "artifact_id": receipt_id,
+        "cli": reexpand_command,
+        "verified": artifact_verified,
+        "valid_command_shape": reexpand_valid,
+        "verification": artifact_verification,
+        "note": "Emit mode validates exact local artifact command shape and verifies local artifact content matches the input diff.",
+    }
+    payload["replacement"] = replacement_meta
+    payload["review_plan"]["readiness_blockers"] = blockers
+    payload["review_plan"]["bounded_loss_disclosure"] = (
+        "Compacted replacement is caller supplied and lossy; use exact_retrieval.cli to recover the original diff "
+        "before relying on omitted details."
+    )
+    payload["review_plan"]["next_steps"] = [
+        "Human-review the compacted replacement against the original diff before use.",
+        "Use exact_retrieval.cli to recover the original diff whenever omitted details matter.",
+        "Treat bytes_before/bytes_after as local proxy evidence only; do not claim hosted token/cost savings.",
+    ]
+    payload["claim_boundary"] = (
+        "Explicit local context-diff replacement emission only; smaller local diffs are proxy evidence and are not "
+        "hosted API token or cost savings evidence."
+    )
+    bytes_after = replacement_meta["bytes"] if replacement_text is not None else 0
+    payload["compaction_evidence"] = {
+        "bytes_before": payload["input"]["bytes"],
+        "bytes_after": bytes_after,
+        "byte_reduction": max(0, payload["input"]["bytes"] - bytes_after),
+        "byte_reduction_proxy_only": True,
+        "hosted_api_token_savings_claim_allowed": False,
+        "hosted_api_cost_savings_claim_allowed": False,
+    }
+    payload["compacted_replacement"] = replacement_record
+    return payload
+
+
+def command_emit_context_diff_compaction(args: argparse.Namespace) -> int:
+    payload = context_diff_emit_payload(args)
+    if args.json:
+        emit_json(payload)
+    else:
+        if payload["status"] == "replacement_emitted":
+            print("ContextGuard context-diff compact replacement emitted")
+            print(
+                f"Replacement: bytes={payload['replacement']['bytes']} "
+                f"sha256={payload['replacement']['sha256']}"
+            )
+            print(f"Exact re-expand: {payload['exact_retrieval']['cli']}")
+        else:
+            print("ContextGuard context-diff compact replacement blocked")
+            print(f"Status: {payload['status']}")
+            if payload["review_plan"]["readiness_blockers"]:
+                print(f"Readiness blockers: {', '.join(payload['review_plan']['readiness_blockers'])}")
+        print(payload["claim_boundary"])
+    return 0 if payload["status"] == "replacement_emitted" else 1
+
+
 def clean_values(values: list[str] | None) -> list[str]:
     return [value.strip() for value in values or [] if value.strip()]
 
@@ -1016,6 +1564,7 @@ def read_visual_ocr_text(args: argparse.Namespace) -> dict[str, Any]:
         "truncated": truncated,
         "max_bytes": MAX_VISUAL_OCR_TEXT_BYTES,
         "valid_utf8": valid_encoding,
+        "text": text,
         "text_preview": text,
         "has_text": bool(text.strip()),
     }
@@ -1178,6 +1727,93 @@ def command_plan_visual_crop_ocr(args: argparse.Namespace) -> int:
     return 0
 
 
+def visual_crop_ocr_evidence_pack_payload(args: argparse.Namespace) -> dict[str, Any]:
+    payload = visual_crop_ocr_plan_payload(args)
+    blockers = list(payload["review_plan"]["readiness_blockers"])
+    ready = not blockers
+    crop = payload["derived_evidence"]["crop"]
+    ocr = payload["derived_evidence"]["ocr"]
+
+    image_area = None
+    crop_area = None
+    if crop["bounds"] is not None and crop["image_size"] is not None:
+        image_area = crop["image_size"]["width"] * crop["image_size"]["height"]
+        crop_area = crop["bounds"]["width"] * crop["bounds"]["height"]
+
+    payload["mode"] = "emit"
+    payload["status"] = "evidence_pack_emitted" if ready else "blocked_until_visual_evidence_pack_ready"
+    payload["guardrails"] = dict(payload["guardrails"])
+    payload["guardrails"].update({
+        "candidate_replacement_allowed": False,
+        "evidence_pack_allowed": ready,
+        "runtime_writes_files": False,
+        "external_services_called": False,
+    })
+    payload["claim_boundary"] = (
+        "Explicit local visual crop/OCR evidence-pack emission only; image area and OCR byte reductions are proxy "
+        "evidence and are not hosted API token or cost savings evidence."
+    )
+    payload["reduction_evidence"] = {
+        "image_area_before": image_area,
+        "crop_area_after": crop_area if crop["available"] else None,
+        "crop_area_reduction": (image_area - crop_area) if crop["available"] and image_area is not None and crop_area is not None else None,
+        "ocr_text_bytes": ocr["metadata"]["bytes"] if ocr["available"] else None,
+        "proxy_only": True,
+        "hosted_api_token_savings_claim_allowed": False,
+        "hosted_api_cost_savings_claim_allowed": False,
+    }
+    payload["review_plan"]["next_steps"] = [
+        "Human-review crop/OCR evidence against the full visual evidence receipt before using it as a substitute.",
+        "Read missed-context notes before relying on omitted visual regions.",
+        "Treat image area/OCR byte reductions as local proxy evidence only; do not claim hosted token/cost savings.",
+    ]
+    if ready:
+        payload["evidence_pack"] = {
+            "schema_version": "contextguard.visual-evidence-pack.v1",
+            "full_visual_evidence": payload["full_visual_evidence"],
+            "crop_evidence": crop if crop["available"] else None,
+            "ocr_evidence": (
+                {
+                    "source_type": ocr["source_type"],
+                    "source_label": ocr["source_label"],
+                    "text": ocr["text_preview"],
+                    "metadata": ocr["metadata"],
+                    "confidence": ocr["confidence"],
+                    "error_notes": ocr["error_notes"],
+                }
+                if ocr["available"]
+                else None
+            ),
+            "missed_context_notes": payload["review_plan"]["missed_context_notes"],
+            "guardrails": payload["guardrails"],
+            "reduction_evidence": payload["reduction_evidence"],
+            "claim_boundary": payload["claim_boundary"],
+        }
+    return payload
+
+
+def command_emit_visual_crop_ocr(args: argparse.Namespace) -> int:
+    payload = visual_crop_ocr_evidence_pack_payload(args)
+    if args.json:
+        emit_json(payload)
+    else:
+        if payload["status"] == "evidence_pack_emitted":
+            print("ContextGuard visual crop/OCR evidence pack emitted")
+            print(f"Full evidence receipt: {payload['full_visual_evidence']['receipt_id']}")
+            print(
+                "Derived evidence: "
+                f"crop={payload['derived_evidence']['crop']['available']} "
+                f"ocr={payload['derived_evidence']['ocr']['available']}"
+            )
+        else:
+            print("ContextGuard visual crop/OCR evidence pack blocked")
+            print(f"Status: {payload['status']}")
+            if payload["review_plan"]["readiness_blockers"]:
+                print(f"Readiness blockers: {', '.join(payload['review_plan']['readiness_blockers'])}")
+        print(payload["claim_boundary"])
+    return 0 if payload["status"] == "evidence_pack_emitted" else 1
+
+
 SECRET_LABEL_KEY_RE = (
     r"[A-Za-z0-9_.-]*(?:"
     r"api[-_]?key|apikey|token|secret|password|passwd|pwd|client[-_]?secret|"
@@ -1434,6 +2070,70 @@ def select_self_hosted_envelope(payload: Any) -> tuple[Any, str | None, list[str
     return None, None, ignored
 
 
+def parse_optional_success(value: str | None) -> bool | None:
+    if value is None or value == "unknown":
+        return None
+    return value == "true"
+
+
+def self_hosted_metrics_ledger_row(
+    sidecar: dict[str, Any],
+    *,
+    task_id: str = "self-hosted-metrics-manual",
+    variant: str = "self-hosted-metrics-ledger",
+    success: bool | None = None,
+    notes: str = "explicit self-hosted metrics record; no hosted API savings claim",
+    claude_version: str = "manual",
+    wall_time_seconds: float = 0.0,
+) -> dict[str, Any]:
+    return {
+        "schema_version": BENCH_RUN_EVIDENCE_SCHEMA_VERSION,
+        "date": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "claude_version": sanitize_self_hosted_text(claude_version) or "manual",
+        "task_id": sanitize_self_hosted_text(task_id) or "self-hosted-metrics-manual",
+        "variant": sanitize_self_hosted_text(variant) or "self-hosted-metrics-ledger",
+        "transform_id": "self-hosted-metrics-ledger",
+        "success": success,
+        "primary_tokens_measured": False,
+        "primary_tokens": 0,
+        "primary_cost_measured": False,
+        "primary_cost_usd": 0.0,
+        "provider_cached_tokens": None,
+        "provider_cached_tokens_measured": False,
+        "wall_time_seconds": wall_time_seconds,
+        "external_tokens_measured": False,
+        "external_tokens": 0,
+        "external_cost_measured": False,
+        "external_cost_usd": 0.0,
+        "total_cost_with_shift_usd": None,
+        "artifacts_used": 0,
+        "bytes_before": 0,
+        "bytes_after": 0,
+        "hook_triggers": 0,
+        "turns": 0,
+        "notes": sanitize_self_hosted_text(notes)
+        or "explicit self-hosted metrics record; no hosted API savings claim",
+        "measurement_availability": {
+            "primary_tokens": False,
+            "primary_cost": False,
+            "external_tokens": False,
+            "external_cost": False,
+            "shifted_cost": False,
+            "provider_cache": False,
+            "byte_metrics": False,
+            "wall_time": False,
+            "self_hosted_metrics": True,
+        },
+        "self_hosted_metrics": sidecar,
+        "proxy_metrics": {
+            "byte_metrics_observed": False,
+            "token_proxy": "chars_div_4",
+            "bytes_per_token": TOKEN_PROXY_BYTES_PER_TOKEN,
+            "claim_boundary": "proxy_only_not_hosted_token_savings",
+        },
+    }
+
+
 def self_hosted_metrics_plan_payload(args: argparse.Namespace) -> dict[str, Any]:
     cli_metrics = cli_self_hosted_metrics(args)
     if cli_metrics:
@@ -1493,51 +2193,12 @@ def self_hosted_metrics_plan_payload(args: argparse.Namespace) -> dict[str, Any]
     ready = not blockers
     ledger_preview = None
     if sidecar is not None:
-        ledger_preview = {
-            "schema_version": BENCH_RUN_EVIDENCE_SCHEMA_VERSION,
-            "date": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
-            "claude_version": "dry-run",
-            "task_id": "self-hosted-metrics-dry-run",
-            "variant": "self-hosted-metrics-ledger",
-            "transform_id": "self-hosted-metrics-ledger",
-            "success": None,
-            "primary_tokens_measured": False,
-            "primary_tokens": 0,
-            "primary_cost_measured": False,
-            "primary_cost_usd": 0.0,
-            "provider_cached_tokens": None,
-            "provider_cached_tokens_measured": False,
-            "wall_time_seconds": 0.0,
-            "external_tokens_measured": False,
-            "external_tokens": 0,
-            "external_cost_measured": False,
-            "external_cost_usd": 0.0,
-            "total_cost_with_shift_usd": None,
-            "artifacts_used": 0,
-            "bytes_before": 0,
-            "bytes_after": 0,
-            "hook_triggers": 0,
-            "turns": 0,
-            "notes": "dry-run preview; no ledger file written",
-            "measurement_availability": {
-                "primary_tokens": False,
-                "primary_cost": False,
-                "external_tokens": False,
-                "external_cost": False,
-                "shifted_cost": False,
-                "provider_cache": False,
-                "byte_metrics": False,
-                "wall_time": False,
-                "self_hosted_metrics": True,
-            },
-            "self_hosted_metrics": sidecar,
-            "proxy_metrics": {
-                "byte_metrics_observed": False,
-                "token_proxy": "chars_div_4",
-                "bytes_per_token": TOKEN_PROXY_BYTES_PER_TOKEN,
-                "claim_boundary": "proxy_only_not_hosted_token_savings",
-            },
-        }
+        ledger_preview = self_hosted_metrics_ledger_row(
+            sidecar,
+            task_id="self-hosted-metrics-dry-run",
+            notes="dry-run preview; no ledger file written",
+            claude_version="dry-run",
+        )
     return {
         "tool": TOOL_NAME,
         "schema_version": CONFIG_SCHEMA_VERSION,
@@ -1583,6 +2244,65 @@ def command_plan_self_hosted_metrics_ledger(args: argparse.Namespace) -> int:
     return 0
 
 
+def self_hosted_metrics_record_payload(args: argparse.Namespace) -> dict[str, Any]:
+    payload = self_hosted_metrics_plan_payload(args)
+    payload["mode"] = "record"
+    payload["claim_boundary"] = (
+        "Explicit local self-hosted metrics ledger record only; local/model-server metrics are diagnostic sidecars "
+        "and are not hosted API token or cost savings evidence."
+    )
+    payload["policy"]["ledger_write_performed"] = False
+    payload["policy"]["stable_runtime_behavior_changed"] = False
+    payload["ledger_record"] = None
+    payload["ledger_jsonl"] = {
+        "path": sanitize_self_hosted_text(args.ledger_jsonl),
+        "write_performed": False,
+        "bytes_written": 0,
+    }
+    if payload["self_hosted_metrics"] is None or payload["review_plan"]["readiness_blockers"]:
+        payload["status"] = "blocked_until_metrics"
+        return payload
+
+    row = self_hosted_metrics_ledger_row(
+        payload["self_hosted_metrics"],
+        task_id=args.task_id,
+        variant=args.variant,
+        success=parse_optional_success(args.success),
+        notes=args.notes,
+        claude_version="manual",
+    )
+    bytes_written = append_jsonl_no_follow(Path(args.ledger_jsonl), row, label="self-hosted metrics ledger")
+    payload["status"] = "recorded"
+    payload["ledger_preview"] = row
+    payload["ledger_record"] = row
+    payload["policy"]["ledger_write_performed"] = True
+    payload["ledger_jsonl"]["write_performed"] = True
+    payload["ledger_jsonl"]["bytes_written"] = bytes_written
+    payload["review_plan"]["next_steps"] = [
+        "Use this JSONL row only as self-hosted/local diagnostic evidence.",
+        "Keep hosted API token/cost savings claims behind provider-measured matched successful tasks.",
+        "Compare this sidecar with benchmark rows only through explicit shifted-cost accounting.",
+    ]
+    return payload
+
+
+def command_record_self_hosted_metrics_ledger(args: argparse.Namespace) -> int:
+    payload = self_hosted_metrics_record_payload(args)
+    if args.json:
+        emit_json(payload)
+    else:
+        if payload["status"] == "recorded":
+            print("ContextGuard self-hosted metrics ledger record written")
+            print(f"Ledger: {payload['ledger_jsonl']['path']} bytes={payload['ledger_jsonl']['bytes_written']}")
+        else:
+            print("ContextGuard self-hosted metrics ledger record blocked")
+            print(f"Status: {payload['status']}")
+            if payload["review_plan"]["readiness_blockers"]:
+                print(f"Readiness blockers: {', '.join(payload['review_plan']['readiness_blockers'])}")
+        print(payload["claim_boundary"])
+    return 0
+
+
 def sanitize_local_proxy_value(value: Any) -> str:
     return sanitize_self_hosted_text(value)
 
@@ -1593,22 +2313,218 @@ def local_proxy_secret_like(value: Any) -> bool:
     return "[REDACTED]" in sanitize_local_proxy_value(value)
 
 
-def is_localhost_host(value: Any) -> bool:
-    if not isinstance(value, str):
-        return False
-    host = value.strip().strip("[]").lower().rstrip(".")
-    if host in LOCAL_PROXY_LOCALHOST_NAMES:
-        return True
-    try:
-        return ipaddress.ip_address(host).is_loopback
-    except ValueError:
-        return False
+def local_proxy_bytes_secret_like(value: bytes) -> bool:
+    return local_proxy_secret_like(value.decode("utf-8", errors="replace"))
 
 
-def normalize_local_proxy_host(value: Any, *, default: str) -> tuple[str, bool, bool]:
-    if value is None or str(value).strip() == "":
-        host = default
-    else:
+def local_proxy_request_target_meta(value: Any) -> dict[str, Any]:
+    text = "" if value is None else str(value)
+    raw = text.encode("utf-8", errors="replace")
+    return {
+        "request_target_sha256": hashlib.sha256(raw).hexdigest(),
+        "request_target_bytes": len(raw),
+    }
+
+
+def normalize_external_allow_host(value: Any) -> tuple[str, list[str]]:
+    raw = "" if value is None else str(value).strip()
+    sanitized = sanitize_local_proxy_value(raw)
+    blockers: list[str] = []
+    host = raw.strip().strip("[]").lower().rstrip(".")
+    if not host:
+        return sanitized, ["invalid_external_allow_host"]
+    if "[REDACTED]" in sanitized:
+        blockers.append("secret_like_external_forwarding_design_metadata")
+    if any(ch in host for ch in ("*", "/", "\\", "@", ":", " ")) or len(host) > 253:
+        blockers.append("invalid_external_allow_host")
+    elif is_localhost_host(host):
+        blockers.append("localhost_external_allow_host_not_allowed")
+    else:
+        try:
+            ip = ipaddress.ip_address(host)
+        except ValueError:
+            labels = host.split(".")
+            label_re = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$")
+            if len(labels) < 2 or any(not label_re.fullmatch(label) for label in labels):
+                blockers.append("invalid_external_allow_host")
+        else:
+            if not ip.is_global:
+                blockers.append("non_global_external_allow_host_not_allowed")
+    return sanitized, blockers
+
+
+def local_proxy_external_forwarding_design_payload(args: argparse.Namespace) -> dict[str, Any]:
+    intent = bool(args.external_forwarding_intent)
+    design_ack = bool(args.external_forwarding_design_ack)
+    raw_hosts = args.allow_host or []
+    raw_schemes = args.allow_scheme or []
+    raw_notes = args.threat_model_note or []
+    redaction_policy = sanitize_local_proxy_value(args.credential_redaction_policy)
+    provider_boundary = sanitize_local_proxy_value(args.provider_evidence_boundary)
+
+    blockers: list[str] = []
+    if not intent:
+        blockers.append("missing_external_forwarding_intent")
+    if not design_ack:
+        blockers.append("missing_external_forwarding_design_ack")
+
+    hosts: list[str] = []
+    if not raw_hosts:
+        blockers.append("missing_external_allow_host")
+    for raw_host in raw_hosts:
+        host, host_blockers = normalize_external_allow_host(raw_host)
+        if host:
+            hosts.append(host)
+        blockers.extend(host_blockers)
+    hosts = sorted(set(hosts))
+
+    schemes = sorted(set(sanitize_local_proxy_value(str(value).strip().lower()) for value in raw_schemes if str(value).strip()))
+    if not schemes:
+        blockers.append("missing_external_allow_scheme")
+    for scheme in schemes:
+        if "[REDACTED]" in scheme:
+            blockers.append("secret_like_external_forwarding_design_metadata")
+        elif scheme not in LOCAL_PROXY_EXTERNAL_ALLOWED_SCHEMES:
+            blockers.append("https_only_external_allow_scheme_required")
+
+    threat_model_notes = [sanitize_local_proxy_value(note) for note in clean_values(raw_notes)]
+    if not threat_model_notes:
+        blockers.append("missing_threat_model_note")
+    if any(local_proxy_secret_like(note) for note in raw_notes):
+        blockers.append("secret_like_external_forwarding_design_metadata")
+
+    if not redaction_policy:
+        blockers.append("missing_credential_redaction_policy")
+    elif redaction_policy != LOCAL_PROXY_EXTERNAL_CREDENTIAL_REDACTION_POLICY:
+        blockers.append("unsupported_credential_redaction_policy")
+    if not provider_boundary:
+        blockers.append("missing_provider_evidence_boundary")
+    elif provider_boundary != LOCAL_PROXY_EXTERNAL_PROVIDER_EVIDENCE_BOUNDARY:
+        blockers.append("unsupported_provider_evidence_boundary")
+    if local_proxy_secret_like(redaction_policy) or local_proxy_secret_like(provider_boundary):
+        blockers.append("secret_like_external_forwarding_design_metadata")
+
+    blockers = list(dict.fromkeys(blockers))
+    ready = not blockers
+    return {
+        "tool": TOOL_NAME,
+        "schema_version": LOCAL_PROXY_EXTERNAL_DESIGN_SCHEMA_VERSION,
+        "experiment_id": "local-proxy",
+        "mode": "external_forwarding_design",
+        "status": "ready_for_external_forwarding_design_review" if ready else "blocked_until_external_forwarding_design_constraints",
+        "policy": {
+            "default_off": True,
+            "design_only": True,
+            "external_forwarding_runtime_implemented": False,
+            "external_forwarding_allowed": False,
+            "hidden_external_forwarding": False,
+            "api_key_persistence_allowed": False,
+            "credential_material_forwarded": False,
+            "stable_runtime_behavior_changed": False,
+            "hosted_api_token_savings_claim_allowed": False,
+            "hosted_api_cost_savings_claim_allowed": False,
+        },
+        "network_actions": {
+            "listener_started": False,
+            "outbound_forwarding_attempted": False,
+            "dns_lookup_attempted": False,
+            "external_services_called": False,
+        },
+        "external_forwarding_design": {
+            "intent_acknowledged": intent,
+            "design_acknowledged": design_ack,
+            "allowlist_required": True,
+            "allowlist": {
+                "hosts": hosts,
+                "schemes": schemes,
+                "wildcards_allowed": False,
+                "localhost_allowed": False,
+                "non_global_ip_allowed": False,
+            },
+            "credential_redaction": {
+                "policy": redaction_policy,
+                "required_policy": LOCAL_PROXY_EXTERNAL_CREDENTIAL_REDACTION_POLICY,
+                "blocked_header_names": sorted(LOCAL_PROXY_SENSITIVE_HEADER_NAMES),
+                "raw_headers_persisted": False,
+                "request_bodies_persisted": False,
+                "response_bodies_persisted": False,
+            },
+            "threat_model": {
+                "required": True,
+                "notes": threat_model_notes,
+                "future_review_required": True,
+            },
+            "provider_evidence_boundary": {
+                "policy": provider_boundary,
+                "required_policy": LOCAL_PROXY_EXTERNAL_PROVIDER_EVIDENCE_BOUNDARY,
+                "diagnostic_only": True,
+                "provider_measured_matched_tasks_required_for_hosted_claims": True,
+                "hosted_api_token_savings_claim_allowed": False,
+                "hosted_api_cost_savings_claim_allowed": False,
+            },
+            "future_runtime_requirements": [
+                "separate future runtime gate and review",
+                "explicit host/scheme allowlist enforcement before any network connection",
+                "credential-bearing requests blocked or stripped before forwarding",
+                "no CONNECT/TLS interception without a separate reviewed gate",
+                "diagnostic shifted-cost accounting only unless provider-measured matched-task evidence exists",
+            ],
+        },
+        "review_plan": {
+            "readiness_blockers": blockers,
+            "next_steps": [
+                "Treat this as design evidence only; do not forward external traffic from this command.",
+                "Keep existing local-proxy serve runtime literal-loopback-only.",
+                "Require a separate future runtime gate before any external forwarding implementation.",
+            ],
+        },
+        "claim_boundary": (
+            "Dry-run external forwarding design gate only; no listener, DNS lookup, external service call, credential "
+            "persistence, traffic forwarding, or hosted API token/cost savings claim is performed."
+        ),
+    }
+
+
+def command_plan_local_proxy_external_forwarding(args: argparse.Namespace) -> int:
+    payload = local_proxy_external_forwarding_design_payload(args)
+    if args.json:
+        emit_json(payload)
+    else:
+        print("ContextGuard local proxy external-forwarding design gate (dry-run only)")
+        print("No listener was started, no traffic was forwarded, no DNS lookup was performed, and no API key was persisted.")
+        print(f"Status: {payload['status']}")
+        if payload["review_plan"]["readiness_blockers"]:
+            print(f"Readiness blockers: {', '.join(payload['review_plan']['readiness_blockers'])}")
+        print(payload["claim_boundary"])
+    return 0
+
+
+def is_localhost_host(value: Any) -> bool:
+    if not isinstance(value, str):
+        return False
+    host = value.strip().strip("[]").lower().rstrip(".")
+    if host in LOCAL_PROXY_LOCALHOST_NAMES:
+        return True
+    try:
+        return ipaddress.ip_address(host).is_loopback
+    except ValueError:
+        return False
+
+
+def is_loopback_ip_literal(value: Any) -> bool:
+    if not isinstance(value, str):
+        return False
+    host = value.strip().strip("[]").lower().rstrip(".")
+    try:
+        return ipaddress.ip_address(host).is_loopback
+    except ValueError:
+        return False
+
+
+def normalize_local_proxy_host(value: Any, *, default: str) -> tuple[str, bool, bool]:
+    if value is None or str(value).strip() == "":
+        host = default
+    else:
         host = str(value).strip().strip("[]")
     sanitized = sanitize_local_proxy_value(host)
     return sanitized, is_localhost_host(host), "[REDACTED]" in sanitized
@@ -1626,6 +2542,30 @@ def normalize_local_proxy_port(value: Any, *, default: int) -> tuple[int, bool]:
     return port, 0 <= port <= 65535
 
 
+def normalize_local_proxy_int_limit(value: Any, *, default: int, maximum: int) -> tuple[int, bool]:
+    if value is None or value == "":
+        return default, True
+    if isinstance(value, bool):
+        return default, False
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return default, False
+    return parsed, 1 <= parsed <= maximum
+
+
+def normalize_local_proxy_timeout(value: Any) -> tuple[float, bool]:
+    if value is None or value == "":
+        return LOCAL_PROXY_DEFAULT_TIMEOUT_SECONDS, True
+    if isinstance(value, bool):
+        return LOCAL_PROXY_DEFAULT_TIMEOUT_SECONDS, False
+    try:
+        parsed = float(value)
+    except (TypeError, ValueError):
+        return LOCAL_PROXY_DEFAULT_TIMEOUT_SECONDS, False
+    return parsed, 0.1 <= parsed <= LOCAL_PROXY_MAX_TIMEOUT_SECONDS
+
+
 def read_local_proxy_payload(args: argparse.Namespace) -> tuple[dict[str, Any], dict[str, Any]]:
     if not args.input:
         return {}, {
@@ -1696,6 +2636,12 @@ def read_local_proxy_payload(args: argparse.Namespace) -> tuple[dict[str, Any],
         "persist_api_key",
         "external_forwarding_intent",
         "runtime_gate_ack",
+        "forwarding_gate_ack",
+        "once",
+        "max_request_bytes",
+        "max_response_bytes",
+        "timeout_seconds",
+        "diagnostic_ledger_jsonl",
     }
     ignored.extend(sanitize_self_hosted_ignored_key(key) for key in envelope if key not in allowed)
     return dict(envelope), {
@@ -1708,14 +2654,34 @@ def read_local_proxy_payload(args: argparse.Namespace) -> tuple[dict[str, Any],
 
 
 def coalesce_local_proxy_value(args: argparse.Namespace, payload: dict[str, Any], attr: str, key: str) -> Any:
-    value = getattr(args, attr)
+    value = getattr(args, attr, None)
     return value if value is not None else payload.get(key)
 
 
-def coalesce_local_proxy_bool(args: argparse.Namespace, payload: dict[str, Any], attr: str, key: str) -> bool:
-    if getattr(args, attr):
-        return True
-    return bool(payload.get(key))
+def parse_local_proxy_json_bool(value: Any) -> tuple[bool, bool]:
+    if value is None:
+        return False, True
+    if isinstance(value, bool):
+        return value, True
+    if isinstance(value, str):
+        normalized = value.strip().lower()
+        if normalized in LOCAL_PROXY_TRUE_VALUES:
+            return True, True
+        if normalized in LOCAL_PROXY_FALSE_VALUES:
+            return False, True
+        return False, False
+    if isinstance(value, int) and not isinstance(value, bool):
+        if value == 1:
+            return True, True
+        if value == 0:
+            return False, True
+    return False, False
+
+
+def coalesce_local_proxy_bool(args: argparse.Namespace, payload: dict[str, Any], attr: str, key: str) -> tuple[bool, bool]:
+    if getattr(args, attr, False):
+        return True, True
+    return parse_local_proxy_json_bool(payload.get(key))
 
 
 def local_proxy_plan_payload(args: argparse.Namespace) -> dict[str, Any]:
@@ -1729,14 +2695,24 @@ def local_proxy_plan_payload(args: argparse.Namespace) -> dict[str, Any]:
     proxy_label_raw = coalesce_local_proxy_value(args, input_payload, "proxy_label", "proxy_label")
     api_key_raw = coalesce_local_proxy_value(args, input_payload, "api_key", "api_key")
     authorization_raw = coalesce_local_proxy_value(args, input_payload, "authorization_header", "authorization_header")
-    persist_api_key = coalesce_local_proxy_bool(args, input_payload, "persist_api_key", "persist_api_key")
-    external_forwarding_intent = coalesce_local_proxy_bool(
+    persist_api_key, persist_api_key_valid = coalesce_local_proxy_bool(
+        args,
+        input_payload,
+        "persist_api_key",
+        "persist_api_key",
+    )
+    external_forwarding_intent, external_forwarding_intent_valid = coalesce_local_proxy_bool(
         args,
         input_payload,
         "external_forwarding_intent",
         "external_forwarding_intent",
     )
-    runtime_gate_ack = coalesce_local_proxy_bool(args, input_payload, "runtime_gate_ack", "runtime_gate_ack")
+    runtime_gate_ack, runtime_gate_ack_valid = coalesce_local_proxy_bool(
+        args,
+        input_payload,
+        "runtime_gate_ack",
+        "runtime_gate_ack",
+    )
 
     upstream_url = sanitize_local_proxy_value(upstream_url_raw) if upstream_url_raw else None
     upstream_host = None
@@ -1805,6 +2781,12 @@ def local_proxy_plan_payload(args: argparse.Namespace) -> dict[str, Any]:
     blockers: list[str] = []
     if input_meta["truncated"]:
         blockers.append("input_truncated")
+    if not persist_api_key_valid:
+        blockers.append("invalid_persist_api_key")
+    if not external_forwarding_intent_valid:
+        blockers.append("invalid_external_forwarding_intent")
+    if not runtime_gate_ack_valid:
+        blockers.append("invalid_runtime_gate_ack")
     if not bind_port_valid:
         blockers.append("invalid_bind_port")
     if not target_port_valid:
@@ -1920,6 +2902,610 @@ def command_plan_local_proxy(args: argparse.Namespace) -> int:
     return 0
 
 
+def local_proxy_gate_row(payload: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "schema_version": LOCAL_PROXY_GATE_SCHEMA_VERSION,
+        "date": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "experiment_id": "local-proxy",
+        "proxy_label": payload["ledger_preview"]["proxy_label"],
+        "bind": payload["bind"],
+        "target": payload["target"],
+        "policy": {
+            "localhost_only": True,
+            "runtime_gate_acknowledged": payload["policy"]["runtime_gate_acknowledged"],
+            "listener_started": False,
+            "traffic_forwarded": False,
+            "dns_lookup_attempted": False,
+            "api_key_persisted": False,
+            "hidden_external_forwarding": False,
+        },
+        "network_actions": payload["network_actions"],
+        "api_key_persistence": payload["api_key_persistence"],
+        "forwarding": payload["forwarding"],
+        "claim_boundary": {
+            "id": "local_proxy_runtime_gate_not_hosted_savings",
+            "hosted_api_token_savings_claim_allowed": False,
+            "hosted_api_cost_savings_claim_allowed": False,
+            "requires_provider_measured_matched_tasks_for_hosted_claims": True,
+            "reason": "This row records a local proxy runtime gate only; it starts no listener and forwards no traffic.",
+        },
+        "shifted_cost_accounting_required": True,
+    }
+
+
+def local_proxy_record_payload(args: argparse.Namespace) -> dict[str, Any]:
+    payload = local_proxy_plan_payload(args)
+    payload["mode"] = "record"
+    payload["claim_boundary"] = (
+        "Explicit local proxy runtime-gate record only; no listener, forwarding, DNS lookup, API-key persistence, "
+        "external service call, or hosted API token/cost savings claim is performed."
+    )
+    payload["policy"] = dict(payload["policy"])
+    payload["policy"].update({
+        "dry_run_only": False,
+        "runtime_gate_record_only": True,
+        "runtime_gate_recorded": False,
+        "listener_started": False,
+        "traffic_forwarded": False,
+        "stable_runtime_behavior_changed": False,
+    })
+    payload["ledger_record"] = None
+    payload["ledger_jsonl"] = {
+        "path": sanitize_local_proxy_value(args.ledger_jsonl),
+        "write_performed": False,
+        "bytes_written": 0,
+    }
+    blockers = list(payload["review_plan"]["readiness_blockers"])
+    if not payload["policy"]["runtime_gate_acknowledged"]:
+        blockers.append("missing_runtime_gate_ack")
+    blockers = list(dict.fromkeys(blockers))
+    payload["review_plan"]["readiness_blockers"] = blockers
+    payload["ledger_preview"]["schema_version"] = LOCAL_PROXY_GATE_SCHEMA_VERSION
+    payload["ledger_preview"]["ledger_jsonl"] = sanitize_local_proxy_value(args.ledger_jsonl)
+    payload["ledger_preview"]["ledger_write_performed"] = False
+    if blockers:
+        payload["status"] = "blocked_until_local_proxy_gate_ready"
+        return payload
+
+    row = local_proxy_gate_row(payload)
+    bytes_written = append_jsonl_no_follow(Path(args.ledger_jsonl), row, label="local proxy runtime gate ledger")
+    payload["status"] = "recorded"
+    payload["ledger_preview"] = row
+    payload["ledger_record"] = row
+    payload["ledger_jsonl"]["write_performed"] = True
+    payload["ledger_jsonl"]["bytes_written"] = bytes_written
+    payload["policy"]["runtime_gate_recorded"] = True
+    payload["review_plan"]["next_steps"] = [
+        "Use this JSONL row only as a local proxy runtime-gate record.",
+        "Keep any actual proxy listener or forwarding implementation behind a separate reviewed runtime.",
+        "Do not persist API keys or claim hosted token/cost savings from this gate record.",
+    ]
+    return payload
+
+
+def command_record_local_proxy_runtime_gate(args: argparse.Namespace) -> int:
+    payload = local_proxy_record_payload(args)
+    if args.json:
+        emit_json(payload)
+    else:
+        if payload["status"] == "recorded":
+            print("ContextGuard local proxy runtime-gate record written")
+            print(f"Ledger: {payload['ledger_jsonl']['path']} bytes={payload['ledger_jsonl']['bytes_written']}")
+        else:
+            print("ContextGuard local proxy runtime-gate record blocked")
+            print(f"Status: {payload['status']}")
+            if payload["review_plan"]["readiness_blockers"]:
+                print(f"Readiness blockers: {', '.join(payload['review_plan']['readiness_blockers'])}")
+        print(payload["claim_boundary"])
+    return 0 if payload["status"] == "recorded" else 1
+
+
+def local_proxy_forward_payload(args: argparse.Namespace) -> dict[str, Any]:
+    payload = local_proxy_plan_payload(args)
+    input_payload, _input_meta = read_local_proxy_payload(args)
+    forwarding_gate_ack, forwarding_gate_ack_valid = coalesce_local_proxy_bool(
+        args,
+        input_payload,
+        "forwarding_gate_ack",
+        "forwarding_gate_ack",
+    )
+    once, once_valid = coalesce_local_proxy_bool(args, input_payload, "once", "once")
+    max_request_bytes, max_request_valid = normalize_local_proxy_int_limit(
+        coalesce_local_proxy_value(args, input_payload, "max_request_bytes", "max_request_bytes"),
+        default=LOCAL_PROXY_DEFAULT_MAX_REQUEST_BYTES,
+        maximum=LOCAL_PROXY_MAX_FORWARD_BYTES,
+    )
+    max_response_bytes, max_response_valid = normalize_local_proxy_int_limit(
+        coalesce_local_proxy_value(args, input_payload, "max_response_bytes", "max_response_bytes"),
+        default=LOCAL_PROXY_DEFAULT_MAX_RESPONSE_BYTES,
+        maximum=LOCAL_PROXY_MAX_FORWARD_BYTES,
+    )
+    timeout_seconds, timeout_valid = normalize_local_proxy_timeout(
+        coalesce_local_proxy_value(args, input_payload, "timeout_seconds", "timeout_seconds")
+    )
+    diagnostic_ledger_raw = coalesce_local_proxy_value(
+        args,
+        input_payload,
+        "diagnostic_ledger_jsonl",
+        "diagnostic_ledger_jsonl",
+    )
+    diagnostic_ledger_path = sanitize_local_proxy_value(diagnostic_ledger_raw) if diagnostic_ledger_raw else None
+    diagnostic_ledger_write_path = str(diagnostic_ledger_raw) if diagnostic_ledger_raw else None
+    bind_host = payload["bind"]["host"]
+    target_host = payload["target"]["host"]
+    bind_ip_literal = is_loopback_ip_literal(bind_host)
+    target_ip_literal = is_loopback_ip_literal(target_host)
+    upstream_url = payload["target"].get("upstream_url")
+    upstream_scheme = ""
+    if upstream_url:
+        try:
+            upstream_scheme = urlparse(str(upstream_url)).scheme.lower()
+        except ValueError:
+            upstream_scheme = "invalid"
+
+    payload["mode"] = "serve"
+    payload["schema_version"] = LOCAL_PROXY_FORWARD_SCHEMA_VERSION
+    payload["claim_boundary"] = (
+        "Explicit local proxy forwarding MVP only; binds and forwards literal loopback IPs, blocks credential "
+        "material, persists no API keys, performs no DNS lookup, calls no external services, and makes no hosted "
+        "API token/cost savings claim."
+    )
+    payload["policy"] = dict(payload["policy"])
+    payload["policy"].update({
+        "dry_run_only": False,
+        "forwarding_runtime": True,
+        "forwarding_gate_acknowledged": forwarding_gate_ack,
+        "once_required": True,
+        "once": once,
+        "literal_loopback_ip_only": True,
+        "listener_started": False,
+        "traffic_forwarded": False,
+        "stable_runtime_behavior_changed": False,
+    })
+    payload["forwarding"] = dict(payload["forwarding"])
+    payload["forwarding"].update({
+        "actual_local_forwarding_runtime": True,
+        "forwarding_gate_acknowledged": forwarding_gate_ack,
+        "external_forwarding_allowed": False,
+        "connect_tunneling_allowed": False,
+        "https_mitm_allowed": False,
+    })
+    payload["runtime_limits"] = {
+        "once": once,
+        "max_request_bytes": max_request_bytes,
+        "max_response_bytes": max_response_bytes,
+        "timeout_seconds": timeout_seconds,
+    }
+    payload["diagnostic_ledger"] = {
+        "schema_version": LOCAL_PROXY_DIAGNOSTIC_SCHEMA_VERSION,
+        "path": diagnostic_ledger_path,
+        "path_sha256": hashlib.sha256(str(diagnostic_ledger_raw).encode("utf-8", errors="replace")).hexdigest() if diagnostic_ledger_raw else None,
+        "write_requested": bool(diagnostic_ledger_raw),
+        "write_performed": False,
+        "bytes_written": 0,
+        "reason": None if diagnostic_ledger_raw else "not_requested",
+    }
+    payload["_diagnostic_ledger_write_path"] = diagnostic_ledger_write_path
+    payload["forward_result"] = None
+
+    blockers = list(payload["review_plan"]["readiness_blockers"])
+    if diagnostic_ledger_raw is not None and local_proxy_secret_like(diagnostic_ledger_raw):
+        blockers.append("secret_like_diagnostic_ledger_path")
+    if not payload["policy"]["runtime_gate_acknowledged"]:
+        blockers.append("missing_runtime_gate_ack")
+    if not forwarding_gate_ack_valid:
+        blockers.append("invalid_forwarding_gate_ack")
+    if not once_valid:
+        blockers.append("invalid_once")
+    if not forwarding_gate_ack:
+        blockers.append("missing_forwarding_gate_ack")
+    if not once:
+        blockers.append("once_required_for_forwarding_mvp")
+    if payload["bind"]["port"] <= 0:
+        blockers.append("bind_port_required_for_listener")
+    if payload["target"]["port"] <= 0:
+        blockers.append("target_port_required_for_forwarding")
+    if not bind_ip_literal:
+        blockers.append("bind_host_must_be_loopback_ip_literal")
+    if not target_ip_literal:
+        blockers.append("target_host_must_be_loopback_ip_literal")
+    if upstream_scheme and upstream_scheme != "http":
+        blockers.append("unsupported_upstream_url_scheme")
+    if not max_request_valid:
+        blockers.append("invalid_max_request_bytes")
+    if not max_response_valid:
+        blockers.append("invalid_max_response_bytes")
+    if not timeout_valid:
+        blockers.append("invalid_timeout_seconds")
+    blockers = list(dict.fromkeys(blockers))
+    payload["review_plan"]["readiness_blockers"] = blockers
+    payload["review_plan"]["next_steps"] = [
+        "Use this MVP only for local loopback HTTP forwarding.",
+        "Keep external forwarding, CONNECT tunneling, credential persistence, and hosted savings claims behind later gates.",
+        "Use --once plus byte/time limits for bounded operation.",
+    ]
+    payload["status"] = "ready_to_serve" if not blockers else "blocked_until_local_proxy_forwarding_ready"
+    return payload
+
+
+def local_proxy_forward_diagnostic_row(payload: dict[str, Any]) -> dict[str, Any]:
+    result = payload.get("forward_result") or {}
+    return {
+        "schema_version": LOCAL_PROXY_DIAGNOSTIC_SCHEMA_VERSION,
+        "date": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "experiment_id": "local-proxy",
+        "mode": "serve",
+        "proxy_label": payload["ledger_preview"]["proxy_label"],
+        "bind": payload["bind"],
+        "target": {
+            "host": payload["target"]["host"],
+            "port": payload["target"]["port"],
+            "localhost_only": payload["target"]["localhost_only"],
+        },
+        "request": {
+            "method": result.get("request_method"),
+            "target_sha256": result.get("request_target_sha256"),
+            "target_bytes": result.get("request_target_bytes", 0),
+            "body_bytes": result.get("inbound_request_bytes", 0),
+            "headers_persisted": False,
+            "body_persisted": False,
+            "credential_material_forwarded": False,
+        },
+        "response": {
+            "upstream_status": result.get("upstream_status"),
+            "upstream_response_bytes": result.get("upstream_response_bytes", 0),
+            "body_persisted": False,
+        },
+        "runtime_limits": payload["runtime_limits"],
+        "network_actions": payload["network_actions"],
+        "policy": {
+            "localhost_only": True,
+            "literal_loopback_ip_only": True,
+            "forwarded": bool(result.get("forwarded")),
+            "api_key_persisted": False,
+            "hidden_external_forwarding": False,
+            "external_services_called": False,
+            "dns_lookup_attempted": False,
+            "connect_tunneling_allowed": False,
+            "https_mitm_allowed": False,
+            "hosted_api_token_savings_claim_allowed": False,
+            "hosted_api_cost_savings_claim_allowed": False,
+        },
+        "shifted_cost_accounting": {
+            "required": True,
+            "local_proxy_request": True,
+            "diagnostic_only": True,
+            "provider_measured_matched_tasks_required_for_hosted_claims": True,
+        },
+        "claim_boundary": {
+            "id": "local_proxy_forward_diagnostic_not_hosted_savings",
+            "reason": "This row records one explicit literal-loopback forwarded request as shifted-cost diagnostic evidence only.",
+            "hosted_api_token_savings_claim_allowed": False,
+            "hosted_api_cost_savings_claim_allowed": False,
+        },
+    }
+
+
+def maybe_write_local_proxy_forward_diagnostic(payload: dict[str, Any]) -> None:
+    ledger = payload.get("diagnostic_ledger")
+    if not isinstance(ledger, dict) or not ledger.get("write_requested"):
+        return
+    if payload.get("status") != "served_once" or not (payload.get("forward_result") or {}).get("forwarded"):
+        if ledger.get("reason") != "preflight_failed":
+            ledger["reason"] = "not_forwarded"
+        return
+    row = local_proxy_forward_diagnostic_row(payload)
+    write_path = payload.get("_diagnostic_ledger_write_path")
+    if not write_path:
+        ledger["reason"] = "not_requested"
+        return
+    bytes_written = append_jsonl_no_follow(Path(str(write_path)), row, label="local proxy forwarding diagnostic ledger")
+    ledger["write_performed"] = True
+    ledger["bytes_written"] = bytes_written
+    ledger["reason"] = None
+    ledger["row_preview"] = row
+
+
+def local_proxy_has_sensitive_headers(headers: Any) -> list[str]:
+    found: list[str] = []
+    for name, value in headers.items():
+        lower = str(name).lower()
+        if lower in LOCAL_PROXY_SENSITIVE_HEADER_NAMES:
+            found.append(lower)
+        elif local_proxy_secret_like(name):
+            found.append("redacted_sensitive_header")
+        elif local_proxy_secret_like(value):
+            found.append(lower)
+    return sorted(set(found))
+
+
+def local_proxy_safe_forward_headers(headers: Any, *, target_host: str, target_port: int) -> dict[str, str]:
+    return {
+        "Host": f"{target_host}:{target_port}",
+        "Connection": "close",
+    }
+
+
+def local_proxy_response_headers(headers: Any) -> list[tuple[str, str]]:
+    result: list[tuple[str, str]] = []
+    for name, value in headers.items():
+        lower = str(name).lower()
+        if lower in LOCAL_PROXY_SENSITIVE_HEADER_NAMES or lower in LOCAL_PROXY_HOP_BY_HOP_HEADERS:
+            continue
+        if lower not in {"content-type"}:
+            continue
+        if local_proxy_secret_like(name) or local_proxy_secret_like(value):
+            continue
+        result.append((str(name), str(value)))
+    return result
+
+
+def write_local_proxy_ready_file(path: str | None, *, bind_host: str, bind_port: int) -> None:
+    if not path:
+        return
+    ready_payload = {
+        "schema_version": LOCAL_PROXY_READY_SCHEMA_VERSION,
+        "experiment_id": "local-proxy",
+        "mode": "serve",
+        "status": "listener_ready",
+        "diagnostic_only": True,
+        "pid": os.getpid(),
+        "bind": {
+            "host": bind_host,
+            "port": bind_port,
+        },
+    }
+    data = json.dumps(ready_payload, sort_keys=True).encode("utf-8") + b"\n"
+    write_regular_file_no_follow_exclusive(Path(path), data, label="local proxy ready file", mode=0o600)
+
+
+def serve_local_proxy_once(payload: dict[str, Any], *, ready_file: str | None = None) -> dict[str, Any]:
+    bind_host = payload["bind"]["host"]
+    bind_port = int(payload["bind"]["port"])
+    target_host = payload["target"]["host"]
+    target_port = int(payload["target"]["port"])
+    limits = payload["runtime_limits"]
+    max_request_bytes = int(limits["max_request_bytes"])
+    max_response_bytes = int(limits["max_response_bytes"])
+    timeout_seconds = float(limits["timeout_seconds"])
+    server_result: dict[str, Any] = {
+        "served_once": False,
+        "forwarded": False,
+        "blocked_reason": None,
+        "forward_attempted": False,
+        "request_method": None,
+        "request_target_sha256": None,
+        "request_target_bytes": 0,
+        "inbound_request_bytes": 0,
+        "upstream_status": None,
+        "upstream_response_bytes": 0,
+        "downstream_status": None,
+        "sensitive_headers_blocked": [],
+        "listener_started": False,
+        "ready_file_written": False,
+    }
+
+    def finish_blocked(handler: BaseHTTPRequestHandler, status_code: int, reason: str, *, sensitive: list[str] | None = None) -> None:
+        server_result.update({
+            "served_once": True,
+            "forwarded": False,
+            "blocked_reason": reason,
+            "downstream_status": status_code,
+            "sensitive_headers_blocked": sorted(set(sensitive or [])),
+        })
+        body = json.dumps({"status": "blocked", "reason": reason}, sort_keys=True).encode("utf-8")
+        handler.send_response(status_code)
+        handler.send_header("Content-Type", "application/json")
+        handler.send_header("Content-Length", str(len(body)))
+        handler.send_header("Connection", "close")
+        handler.end_headers()
+        if handler.command != "HEAD":
+            handler.wfile.write(body)
+
+    class LocalProxyHandler(BaseHTTPRequestHandler):
+        server_version = "ContextGuardLocalProxy/0"
+        protocol_version = "HTTP/1.1"
+
+        def log_message(self, format: str, *args: Any) -> None:  # noqa: A002 - BaseHTTPRequestHandler API.
+            return
+
+        def do_CONNECT(self) -> None:
+            server_result["request_method"] = "CONNECT"
+            server_result.update(local_proxy_request_target_meta(self.path))
+            finish_blocked(self, 405, "connect_tunneling_not_allowed")
+
+        def do_HEAD(self) -> None:
+            self.forward_request()
+
+        def do_GET(self) -> None:
+            self.forward_request()
+
+        def do_POST(self) -> None:
+            self.block_method()
+
+        def do_PUT(self) -> None:
+            self.block_method()
+
+        def do_PATCH(self) -> None:
+            self.block_method()
+
+        def block_method(self) -> None:
+            server_result["request_method"] = self.command
+            server_result.update(local_proxy_request_target_meta(self.path))
+            finish_blocked(self, 405, "method_not_allowed")
+
+        def do_DELETE(self) -> None:
+            self.block_method()
+
+        def do_OPTIONS(self) -> None:
+            self.block_method()
+
+        def do_TRACE(self) -> None:
+            self.block_method()
+
+        def forward_request(self) -> None:
+            server_result["request_method"] = self.command
+            server_result.update(local_proxy_request_target_meta(self.path))
+            if local_proxy_secret_like(self.path):
+                finish_blocked(self, 400, "secret_like_request_target")
+                return
+            parsed_target = urlparse(self.path)
+            if parsed_target.scheme or parsed_target.netloc:
+                finish_blocked(self, 400, "absolute_proxy_url_not_allowed")
+                return
+            if str(self.headers.get("Transfer-Encoding", "")).strip():
+                finish_blocked(self, 400, "transfer_encoding_not_allowed")
+                return
+            sensitive_headers = local_proxy_has_sensitive_headers(self.headers)
+            if sensitive_headers:
+                finish_blocked(self, 403, "sensitive_request_headers_blocked", sensitive=sensitive_headers)
+                return
+            raw_length = self.headers.get("Content-Length")
+            try:
+                content_length = int(raw_length) if raw_length else 0
+            except ValueError:
+                finish_blocked(self, 400, "invalid_content_length")
+                return
+            if content_length < 0 or content_length > max_request_bytes:
+                finish_blocked(self, 413, "request_body_exceeds_limit")
+                return
+            if content_length:
+                finish_blocked(self, 400, "request_body_not_allowed_for_forwarding_mvp")
+                return
+            body = self.rfile.read(content_length) if content_length else b""
+            server_result["inbound_request_bytes"] = len(body)
+            path = self.path if self.path.startswith("/") else f"/{self.path}"
+            conn = http.client.HTTPConnection(target_host, target_port, timeout=timeout_seconds)
+            try:
+                server_result["forward_attempted"] = True
+                conn.request(
+                    self.command,
+                    path,
+                    body=body,
+                    headers=local_proxy_safe_forward_headers(self.headers, target_host=target_host, target_port=target_port),
+                )
+                response = conn.getresponse()
+                response_body = response.read(max_response_bytes + 1)
+                if len(response_body) > max_response_bytes:
+                    finish_blocked(self, 502, "upstream_response_exceeds_limit")
+                    return
+                if local_proxy_bytes_secret_like(response_body):
+                    finish_blocked(self, 502, "upstream_response_sensitive_content_blocked")
+                    return
+                self.send_response(response.status, response.reason)
+                for header_name, header_value in local_proxy_response_headers(response.headers):
+                    self.send_header(header_name, header_value)
+                self.send_header("Content-Length", str(len(response_body)))
+                self.send_header("Connection", "close")
+                self.end_headers()
+                if self.command != "HEAD":
+                    self.wfile.write(response_body)
+                server_result.update({
+                    "served_once": True,
+                    "forwarded": True,
+                    "blocked_reason": None,
+                    "upstream_status": response.status,
+                    "upstream_response_bytes": len(response_body),
+                    "downstream_status": response.status,
+                })
+            except (OSError, http.client.HTTPException, TimeoutError) as exc:
+                finish_blocked(self, 502, "upstream_forward_error")
+                server_result["error"] = sanitize_local_proxy_value(str(exc))
+            finally:
+                conn.close()
+
+    address_family = socket.AF_INET6 if ":" in bind_host else socket.AF_INET
+    class LocalProxyHTTPServer(HTTPServer):
+        def server_bind(self) -> None:
+            TCPServer.server_bind(self)
+            host, port = self.server_address[:2]
+            self.server_name = str(host)
+            self.server_port = int(port)
+
+        def get_request(self) -> tuple[Any, Any]:
+            request, client_address = super().get_request()
+            request.settimeout(timeout_seconds)
+            return request, client_address
+
+    LocalProxyHTTPServer.address_family = address_family
+    try:
+        httpd = LocalProxyHTTPServer((bind_host, bind_port), LocalProxyHandler)
+    except OSError as exc:
+        raise RegistryError(f"could not start local proxy listener: {os_error_detail(exc)}") from exc
+    httpd.timeout = timeout_seconds
+    try:
+        try:
+            write_local_proxy_ready_file(ready_file, bind_host=bind_host, bind_port=bind_port)
+            server_result["ready_file_written"] = bool(ready_file)
+            server_result["listener_started"] = True
+        except RegistryError as exc:
+            server_result.update({
+                "served_once": False,
+                "forwarded": False,
+                "blocked_reason": "ready_file_write_failed",
+                "downstream_status": None,
+                "error": sanitize_local_proxy_value(str(exc)),
+            })
+            return server_result
+        httpd.handle_request()
+        if not server_result["served_once"]:
+            server_result.update({
+                "blocked_reason": "timeout_waiting_for_request",
+                "downstream_status": None,
+            })
+    finally:
+        httpd.server_close()
+    return server_result
+
+
+def command_serve_local_proxy(args: argparse.Namespace) -> int:
+    payload = local_proxy_forward_payload(args)
+    diagnostic_ledger = payload.get("diagnostic_ledger") if isinstance(payload.get("diagnostic_ledger"), dict) else {}
+    if payload["status"] == "ready_to_serve" and diagnostic_ledger.get("write_requested"):
+        try:
+            preflight_append_jsonl_no_follow(
+                Path(str(payload.get("_diagnostic_ledger_write_path"))),
+                label="local proxy forwarding diagnostic ledger",
+            )
+        except RegistryError as exc:
+            payload["status"] = "blocked_until_local_proxy_forwarding_ready"
+            payload["review_plan"]["readiness_blockers"].append("diagnostic_ledger_preflight_failed")
+            diagnostic_ledger["reason"] = "preflight_failed"
+            diagnostic_ledger["error"] = sanitize_local_proxy_value(str(exc))
+    if payload["status"] == "ready_to_serve":
+        result = serve_local_proxy_once(payload, ready_file=args.ready_file)
+        payload["forward_result"] = result
+        payload["network_actions"]["listener_started"] = bool(result.get("listener_started"))
+        payload["network_actions"]["outbound_forwarding_attempted"] = bool(result["forward_attempted"])
+        payload["network_actions"]["dns_lookup_attempted"] = False
+        payload["network_actions"]["external_services_called"] = False
+        payload["policy"]["listener_started"] = bool(result.get("listener_started"))
+        payload["policy"]["traffic_forwarded"] = bool(result["forwarded"])
+        if result["forwarded"]:
+            payload["status"] = "served_once"
+        elif result.get("blocked_reason") == "ready_file_write_failed":
+            payload["status"] = "blocked_until_local_proxy_forwarding_ready"
+            payload["review_plan"]["readiness_blockers"].append("ready_file_write_failed")
+        else:
+            payload["status"] = "blocked_request"
+    maybe_write_local_proxy_forward_diagnostic(payload)
+    payload.pop("_diagnostic_ledger_write_path", None)
+    if args.json:
+        emit_json(payload)
+    else:
+        if payload["status"] == "served_once":
+            print("ContextGuard local proxy served one loopback request")
+        else:
+            print("ContextGuard local proxy serve blocked")
+            print(f"Status: {payload['status']}")
+            if payload["review_plan"]["readiness_blockers"]:
+                print(f"Readiness blockers: {', '.join(payload['review_plan']['readiness_blockers'])}")
+            if payload.get("forward_result") and payload["forward_result"].get("blocked_reason"):
+                print(f"Request blocker: {payload['forward_result']['blocked_reason']}")
+        print(payload["claim_boundary"])
+    return 0 if payload["status"] == "served_once" else 1
+
+
 LEARNED_CODE_FENCE_RE = re.compile(r"(?m)^\s*(?:```|~~~)")
 LEARNED_DIFF_RE = re.compile(r"(?m)^\s*(diff --git |@@\s+-|--- |\+\+\+ |[+-].*)")
 LEARNED_IDENTIFIER_RE = re.compile(
@@ -2072,6 +3658,104 @@ def valid_learned_reexpand_command(receipt_id: str | None, command: str | None)
     return False, "invalid_reexpand_command"
 
 
+def verify_learned_fallback_artifact(
+    receipt_id: str | None,
+    *,
+    expected_sha256: str,
+    expected_bytes: int,
+) -> tuple[bool, str | None, dict[str, Any]]:
+    if not receipt_id or not LEARNED_ARTIFACT_ID_RE.fullmatch(receipt_id):
+        return False, "invalid_reexpand_command", {"checked": False, "read_directories": []}
+    read_dirs = context_diff_artifact_read_dirs()
+    details: dict[str, Any] = {
+        "checked": True,
+        "read_directories": [str(path) for path in read_dirs],
+        "matched_directory": None,
+        "content_sha256": None,
+        "content_bytes": None,
+    }
+    for directory in read_dirs:
+        content_path, meta_path = context_diff_artifact_paths(directory, receipt_id)
+        meta_loaded = read_bounded_regular_file(
+            meta_path,
+            max_bytes=MAX_LEARNED_COMPRESSION_ARTIFACT_METADATA_BYTES,
+            label="learned-compression fallback metadata",
+            missing_ok=True,
+        )
+        content_loaded = read_bounded_regular_file(
+            content_path,
+            max_bytes=max(MAX_LEARNED_COMPRESSION_INPUT_BYTES, expected_bytes),
+            label="learned-compression fallback content",
+            missing_ok=True,
+        )
+        if meta_loaded is None and content_loaded is None:
+            continue
+        if meta_loaded is None or content_loaded is None:
+            return False, "fallback_receipt_invalid", details
+        meta_raw, meta_truncated = meta_loaded
+        content_raw, content_truncated = content_loaded
+        if meta_truncated or content_truncated:
+            return False, "fallback_receipt_invalid", details
+        try:
+            metadata = json.loads(meta_raw.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError):
+            return False, "fallback_receipt_invalid", details
+        if not isinstance(metadata, dict) or metadata.get("artifact_id") != receipt_id:
+            return False, "fallback_receipt_invalid", details
+        stored = metadata.get("stored_output")
+        stored_sha = stored.get("sha256") if isinstance(stored, dict) else None
+        stored_bytes = stored.get("bytes") if isinstance(stored, dict) else None
+        actual_sha = hashlib.sha256(content_raw).hexdigest()
+        actual_bytes = len(content_raw)
+        details.update({
+            "matched_directory": str(directory),
+            "content_sha256": actual_sha,
+            "content_bytes": actual_bytes,
+        })
+        if stored_sha != actual_sha or stored_bytes != actual_bytes:
+            return False, "fallback_receipt_invalid", details
+        if actual_sha != expected_sha256 or actual_bytes != expected_bytes:
+            return False, "fallback_content_mismatch", details
+        return True, None, details
+    return False, "fallback_receipt_not_found", details
+
+
+def read_learned_candidate_replacement(args: argparse.Namespace) -> tuple[str | None, dict[str, Any]]:
+    if args.replacement_text is not None and args.replacement_file:
+        raise RegistryError("learned-compression emit accepts only one of --replacement-text or --replacement-file")
+    if args.replacement_text is not None:
+        text = str(args.replacement_text)
+        raw = text.encode("utf-8")
+        truncated = len(raw) > MAX_LEARNED_COMPRESSION_REPLACEMENT_BYTES
+        raw = raw[:MAX_LEARNED_COMPRESSION_REPLACEMENT_BYTES]
+        text = raw.decode("utf-8", errors="replace")
+        source_label = "inline"
+    elif args.replacement_file:
+        path = Path(args.replacement_file)
+        loaded = read_bounded_regular_file(
+            path,
+            max_bytes=MAX_LEARNED_COMPRESSION_REPLACEMENT_BYTES,
+            label="learned-compression candidate replacement",
+        )
+        assert loaded is not None
+        raw, truncated = loaded
+        text = raw.decode("utf-8", errors="replace")
+        source_label = path.name
+    else:
+        text = None
+        raw = b""
+        truncated = False
+        source_label = None
+    return text, {
+        "source_label": source_label,
+        "bytes": len(raw),
+        "lines": len(text.splitlines()) if text is not None else 0,
+        "sha256": hashlib.sha256(raw).hexdigest() if text is not None else None,
+        "truncated": truncated,
+        "max_bytes": MAX_LEARNED_COMPRESSION_REPLACEMENT_BYTES,
+    }
+
+
 def learned_compression_plan_payload(args: argparse.Namespace) -> dict[str, Any]:
     text, input_meta = read_learned_input(args)
     receipt_id = args.exact_fallback_receipt.strip() if args.exact_fallback_receipt else None
@@ -2165,6 +3849,133 @@ def command_plan_learned_compression(args: argparse.Namespace) -> int:
     return 0
 
 
+def learned_compression_emit_payload(args: argparse.Namespace) -> dict[str, Any]:
+    payload = learned_compression_plan_payload(args)
+    receipt_id = args.exact_fallback_receipt.strip() if args.exact_fallback_receipt else None
+    reexpand_command = args.reexpand_command.strip() if args.reexpand_command else None
+    reexpand_valid, _fallback_blocker = valid_learned_reexpand_command(receipt_id, reexpand_command)
+    fallback_verified = False
+    fallback_blocker = None
+    fallback_verification: dict[str, Any] = {"checked": False, "read_directories": []}
+    if reexpand_valid:
+        fallback_verified, fallback_blocker, fallback_verification = verify_learned_fallback_artifact(
+            receipt_id,
+            expected_sha256=payload["input"]["sha256"],
+            expected_bytes=payload["input"]["bytes"],
+        )
+
+    candidate_text, candidate_meta = read_learned_candidate_replacement(args)
+    candidate_counts = learned_signal_counts(candidate_text or "")
+    candidate_content_type = learned_content_type(candidate_text or "", candidate_counts)
+
+    blockers = list(payload["review_plan"]["readiness_blockers"])
+    if fallback_blocker:
+        blockers.append(fallback_blocker)
+    if candidate_text is None or not candidate_text.strip():
+        blockers.append("missing_candidate_replacement")
+    if candidate_meta["truncated"]:
+        blockers.append("candidate_replacement_truncated")
+    if (
+        candidate_text is not None
+        and not candidate_meta["truncated"]
+        and candidate_meta["bytes"] >= payload["input"]["bytes"]
+    ):
+        blockers.append("candidate_not_smaller_than_input")
+    if candidate_text is not None and candidate_text.strip() and candidate_content_type != "prose":
+        blockers.append("candidate_non_prose_input")
+    for blocker, count in candidate_counts.items():
+        if count:
+            blockers.append(f"candidate_{blocker}")
+    blockers = list(dict.fromkeys(blockers))
+    ready = not blockers
+
+    payload["mode"] = "emit"
+    payload["status"] = "candidate_emitted" if ready else "blocked_until_candidate_ready"
+    payload["policy"] = dict(payload["policy"])
+    payload["policy"].update({
+        "runtime_compression_allowed": False,
+        "caller_supplied_candidate_required": True,
+        "caller_supplied_candidate_allowed": ready,
+        "lossy_replacement_allowed": ready,
+        "learned_compressor_called": False,
+        "embedding_or_reranker_called": False,
+        "model_call_allowed": False,
+        "subprocess_allowed": False,
+    })
+    payload["exact_fallback"] = {
+        "required": True,
+        "available": bool(receipt_id and reexpand_command and reexpand_valid and fallback_verified),
+        "receipt_id": receipt_id,
+        "cli": reexpand_command,
+        "verified": fallback_verified,
+        "valid_command_shape": reexpand_valid,
+        "verification": fallback_verification,
+        "note": "Emit mode validates exact local fallback command shape and verifies local artifact content matches the input prose.",
+    }
+    payload["candidate_scan"] = {
+        "content_type": candidate_content_type,
+        "counts": candidate_counts,
+        "protected_signals": [name for name, count in candidate_counts.items() if count],
+    }
+    payload["replacement"] = candidate_meta
+    payload["review_plan"]["readiness_blockers"] = blockers
+    payload["review_plan"]["protected_signals"] = [name for name, count in payload["protected_signal_scan"]["counts"].items() if count]
+    payload["review_plan"]["candidate_protected_signals"] = [
+        name for name, count in candidate_counts.items() if count
+    ]
+    payload["review_plan"]["next_steps"] = [
+        "Human-review the caller-supplied candidate against the exact fallback before using it.",
+        "Reject candidates that omit protected facts, prompt-like text, paths, code, diffs, identifiers, or numeric constants.",
+        "Treat byte reduction as local proxy evidence only; do not claim hosted token/cost savings.",
+    ]
+    payload["claim_boundary"] = (
+        "Explicit local learned-compression candidate emission only; ContextGuard does not run a learned compressor, "
+        "model, embedding, reranker, subprocess, or external service, and byte reduction is not hosted API token or cost evidence."
+    )
+    bytes_after = candidate_meta["bytes"] if candidate_text is not None else 0
+    payload["compression_evidence"] = {
+        "bytes_before": payload["input"]["bytes"],
+        "bytes_after": bytes_after,
+        "byte_reduction": max(0, payload["input"]["bytes"] - bytes_after),
+        "byte_reduction_proxy_only": True,
+        "hosted_api_token_savings_claim_allowed": False,
+        "hosted_api_cost_savings_claim_allowed": False,
+    }
+    if ready and candidate_text is not None:
+        payload["candidate_replacement"] = {
+            "text": candidate_text,
+            "bytes": candidate_meta["bytes"],
+            "lines": candidate_meta["lines"],
+            "sha256": candidate_meta["sha256"],
+            "source_label": candidate_meta["source_label"],
+            "caller_supplied": True,
+        }
+    else:
+        payload.pop("candidate_replacement", None)
+    return payload
+
+
+def command_emit_learned_compression(args: argparse.Namespace) -> int:
+    payload = learned_compression_emit_payload(args)
+    if args.json:
+        emit_json(payload)
+    else:
+        if payload["status"] == "candidate_emitted":
+            print("ContextGuard learned-compression candidate emitted")
+            print(
+                f"Candidate: bytes={payload['replacement']['bytes']} "
+                f"sha256={payload['replacement']['sha256']}"
+            )
+            print(f"Exact fallback: {payload['exact_fallback']['cli']}")
+        else:
+            print("ContextGuard learned-compression candidate blocked")
+            print(f"Status: {payload['status']}")
+            if payload["review_plan"]["readiness_blockers"]:
+                print(f"Readiness blockers: {', '.join(payload['review_plan']['readiness_blockers'])}")
+        print(payload["claim_boundary"])
+    return 0 if payload["status"] == "candidate_emitted" else 1
+
+
 def add_common_args(parser: argparse.ArgumentParser) -> None:
     parser.add_argument("--root", help="Project root for default project-local experiment config (default: cwd).")
     parser.add_argument("--config", help="Project-local config path. Relative paths resolve under --root; absolute paths must stay inside --root.")
@@ -2283,6 +4094,34 @@ def build_parser() -> argparse.ArgumentParser:
     local_proxy.add_argument("--json", action="store_true", help="Emit JSON output.")
     local_proxy.set_defaults(func=command_plan_local_proxy)
 
+    external_proxy = plan_sub.add_parser(
+        "local-proxy-external-forwarding",
+        help="Dry-run an external-forwarding opt-in design gate without forwarding traffic.",
+    )
+    external_proxy.add_argument(
+        "--external-forwarding-intent",
+        action="store_true",
+        help="Acknowledge intent to design a future external-forwarding proxy surface.",
+    )
+    external_proxy.add_argument(
+        "--external-forwarding-design-ack",
+        action="store_true",
+        help="Acknowledge this command is design-only and does not enable external forwarding.",
+    )
+    external_proxy.add_argument("--allow-host", action="append", help="Explicit non-wildcard public host allowed by the future design. Repeatable.")
+    external_proxy.add_argument("--allow-scheme", action="append", help="Allowed scheme for the future design; HTTPS is required. Repeatable.")
+    external_proxy.add_argument("--threat-model-note", action="append", help="Threat-model note for the future external-forwarding design. Repeatable.")
+    external_proxy.add_argument(
+        "--credential-redaction-policy",
+        help=f"Required policy: {LOCAL_PROXY_EXTERNAL_CREDENTIAL_REDACTION_POLICY}.",
+    )
+    external_proxy.add_argument(
+        "--provider-evidence-boundary",
+        help=f"Required policy: {LOCAL_PROXY_EXTERNAL_PROVIDER_EVIDENCE_BOUNDARY}.",
+    )
+    external_proxy.add_argument("--json", action="store_true", help="Emit JSON output.")
+    external_proxy.set_defaults(func=command_plan_local_proxy_external_forwarding)
+
     learned = plan_sub.add_parser(
         "learned-compression",
         help="Dry-run a deny-by-default learned/synthetic compression safety gate.",
@@ -2296,6 +4135,176 @@ def build_parser() -> argparse.ArgumentParser:
     learned.add_argument("--json", action="store_true", help="Emit JSON output.")
     learned.set_defaults(func=command_plan_learned_compression)
 
+    emit_parser = sub.add_parser("emit", help="Emit explicit local runtime outputs for experimental lanes.")
+    emit_sub = emit_parser.add_subparsers(dest="emit_command", required=True)
+    emit_context_diff = emit_sub.add_parser(
+        "context-diff-compaction",
+        help="Emit a caller-supplied compact diff replacement only with exact retrieval metadata.",
+    )
+    emit_context_diff.add_argument("--input", help="Read original diff text from a file instead of stdin.")
+    emit_context_diff.add_argument("--source-label", help="Safe label to use for the diff input source in reports.")
+    emit_context_diff.add_argument("--receipt-id", required=True, help="Exact local artifact receipt id for the original diff.")
+    emit_context_diff.add_argument("--reexpand-command", required=True, help="Exact command that restores the original diff.")
+    replacement_group = emit_context_diff.add_mutually_exclusive_group(required=True)
+    replacement_group.add_argument("--replacement-text", help="Caller-supplied compact replacement text to emit.")
+    replacement_group.add_argument("--replacement-file", help="Read caller-supplied compact replacement text from a file.")
+    emit_context_diff.add_argument("--json", action="store_true", help="Emit JSON output.")
+    emit_context_diff.set_defaults(func=command_emit_context_diff_compaction)
+
+    emit_visual_ocr = emit_sub.add_parser(
+        "visual-crop-ocr",
+        help="Emit a caller-supplied visual crop/OCR evidence pack without image/OCR services.",
+    )
+    emit_visual_ocr.add_argument("--full-evidence-receipt", help="User-supplied receipt/id for the original full visual evidence.")
+    emit_visual_ocr.add_argument("--full-evidence-label", help="Safe label for the full visual evidence.")
+    emit_visual_ocr.add_argument("--crop-label", help="Safe label for the cropped region or crop fixture.")
+    emit_visual_ocr.add_argument("--crop-bounds", help="Crop bounds as x,y,width,height integers.")
+    emit_visual_ocr.add_argument("--image-size", help="Original image size as width,height integers.")
+    emit_visual_ocr.add_argument("--ocr-text", help="Bounded OCR fixture text supplied inline.")
+    emit_visual_ocr.add_argument("--ocr-text-file", help="Read bounded OCR fixture text from a UTF-8 text file.")
+    emit_visual_ocr.add_argument("--ocr-source-label", help="Safe label for OCR text source; defaults to inline or file basename.")
+    emit_visual_ocr.add_argument("--ocr-confidence", help="OCR confidence as a finite decimal from 0.0 to 1.0.")
+    emit_visual_ocr.add_argument("--ocr-error-note", action="append", help="Known OCR error/uncertainty note. Repeatable.")
+    emit_visual_ocr.add_argument("--missed-context-note", action="append", help="Potential context outside crop/OCR text. Repeatable.")
+    emit_visual_ocr.add_argument("--json", action="store_true", help="Emit JSON output.")
+    emit_visual_ocr.set_defaults(func=command_emit_visual_crop_ocr)
+
+    emit_learned = emit_sub.add_parser(
+        "learned-compression",
+        help="Emit a caller-supplied compact prose candidate only with verified exact fallback.",
+    )
+    emit_learned.add_argument("--input", help="Read original prose text from a file instead of stdin.")
+    emit_learned.add_argument("--source-label", help="Safe label to use for the input source in reports.")
+    emit_learned.add_argument("--sanitized", action="store_true", help="Assert input is already sanitized.")
+    emit_learned.add_argument("--trusted-source", action="store_true", help="Assert input came from a trusted source.")
+    emit_learned.add_argument("--exact-fallback-receipt", required=True, help="Local exact fallback receipt id for the original text.")
+    emit_learned.add_argument("--reexpand-command", required=True, help="Local exact re-expand command bound to the receipt id.")
+    learned_replacement_group = emit_learned.add_mutually_exclusive_group(required=True)
+    learned_replacement_group.add_argument("--replacement-text", help="Caller-supplied compact prose candidate to emit.")
+    learned_replacement_group.add_argument("--replacement-file", help="Read caller-supplied compact prose candidate from a file.")
+    emit_learned.add_argument("--json", action="store_true", help="Emit JSON output.")
+    emit_learned.set_defaults(func=command_emit_learned_compression)
+
+    record_parser = sub.add_parser("record", help="Run explicit local runtime recorders for experimental lanes.")
+    record_sub = record_parser.add_subparsers(dest="record_command", required=True)
+    record_self_hosted = record_sub.add_parser(
+        "self-hosted-metrics-ledger",
+        help="Append one self-hosted/local metrics sidecar row to a JSONL ledger.",
+    )
+    record_self_hosted.add_argument("--ledger-jsonl", required=True, help="Local JSONL ledger path to append.")
+    record_self_hosted.add_argument("--input", help="Read an explicit self_hosted_metrics JSON envelope from a file instead of stdin.")
+    record_self_hosted.add_argument("--source-label", help="Safe label to use for the input source in reports.")
+    record_self_hosted.add_argument("--latency-ms", type=float, default=None, help="Local/model-server latency in milliseconds.")
+    record_self_hosted.add_argument("--peak-memory-mb", type=float, default=None, help="Peak local/model-server memory in MiB/MB.")
+    record_self_hosted.add_argument("--quality-score", type=float, default=None, help="Quality score from 0.0 to 1.0.")
+    record_self_hosted.add_argument("--energy-wh", type=float, default=None, help="Diagnostic local energy use in watt-hours.")
+    record_self_hosted.add_argument("--local-cost-usd", type=float, default=None, help="Diagnostic local/self-hosted cost in USD.")
+    record_self_hosted.add_argument("--tokens-per-second", type=float, default=None, help="Diagnostic local throughput.")
+    record_self_hosted.add_argument("--model-server", help="Sanitized label for local model server/runtime.")
+    record_self_hosted.add_argument("--optimization", help="Sanitized label for the local optimization under test.")
+    record_self_hosted.add_argument("--quality-metric", help="Sanitized label for quality metric.")
+    record_self_hosted.add_argument("--hardware", help="Sanitized local hardware label.")
+    record_self_hosted.add_argument("--runtime", help="Sanitized local runtime label.")
+    record_self_hosted.add_argument("--dataset", help="Sanitized dataset label.")
+    record_self_hosted.add_argument("--task-id", default="self-hosted-metrics-manual", help="Sanitized task id for the ledger row.")
+    record_self_hosted.add_argument("--variant", default="self-hosted-metrics-ledger", help="Sanitized variant label for the ledger row.")
+    record_self_hosted.add_argument(
+        "--success",
+        choices=("true", "false", "unknown"),
+        default="unknown",
+        help="Optional success value for the local run; unknown writes JSON null.",
+    )
+    record_self_hosted.add_argument(
+        "--notes",
+        default="explicit self-hosted metrics record; no hosted API savings claim",
+        help="Sanitized note for the ledger row.",
+    )
+    record_self_hosted.add_argument("--json", action="store_true", help="Emit JSON output.")
+    record_self_hosted.set_defaults(func=command_record_self_hosted_metrics_ledger)
+
+    record_local_proxy = record_sub.add_parser(
+        "local-proxy-runtime-gate",
+        help="Append one localhost-only local proxy runtime-gate row without starting a proxy.",
+    )
+    record_local_proxy.add_argument("--input", help="Read a local_proxy JSON envelope from a file instead of CLI flags.")
+    record_local_proxy.add_argument("--bind-host", help="Advisory bind host; must be localhost/loopback.")
+    record_local_proxy.add_argument("--bind-port", default=None, help="Advisory bind port; 0 means unspecified/ephemeral.")
+    record_local_proxy.add_argument("--target-host", help="Advisory target host; must be localhost/loopback.")
+    record_local_proxy.add_argument("--target-port", default=None, help="Advisory target port; 0 means unspecified.")
+    record_local_proxy.add_argument("--upstream-url", help="Advisory upstream URL; host must be localhost/loopback.")
+    record_local_proxy.add_argument("--ledger-jsonl", required=True, help="Local JSONL ledger path to append the gate row.")
+    record_local_proxy.add_argument("--proxy-label", help="Safe label for this local proxy gate record.")
+    record_local_proxy.add_argument("--api-key", help="Blocked/redacted API key material; never persisted or emitted raw.")
+    record_local_proxy.add_argument("--authorization-header", help="Blocked/redacted Authorization header; never persisted or emitted raw.")
+    record_local_proxy.add_argument("--persist-api-key", action="store_true", help="Declare API-key persistence intent; blocked.")
+    record_local_proxy.add_argument(
+        "--external-forwarding-intent",
+        action="store_true",
+        help="Declare future external forwarding intent; blocked in this gate recorder.",
+    )
+    record_local_proxy.add_argument(
+        "--runtime-gate-ack",
+        action="store_true",
+        help="Acknowledge this is only a local gate record and any forwarding needs a separate runtime gate.",
+    )
+    record_local_proxy.add_argument("--json", action="store_true", help="Emit JSON output.")
+    record_local_proxy.set_defaults(func=command_record_local_proxy_runtime_gate)
+
+    serve_parser = sub.add_parser("serve", help="Run explicit bounded local servers for experimental lanes.")
+    serve_sub = serve_parser.add_subparsers(dest="serve_command", required=True)
+    serve_local_proxy = serve_sub.add_parser(
+        "local-proxy",
+        help="Serve one bounded localhost-only HTTP forwarding request.",
+    )
+    serve_local_proxy.add_argument("--input", help="Read a local_proxy JSON envelope from a file instead of CLI flags.")
+    serve_local_proxy.add_argument("--bind-host", help="Bind host; actual serving requires a literal loopback IP.")
+    serve_local_proxy.add_argument("--bind-port", default=None, help="Bind port; must be a nonzero explicit port for serving.")
+    serve_local_proxy.add_argument("--target-host", help="Target host; actual forwarding requires a literal loopback IP.")
+    serve_local_proxy.add_argument("--target-port", default=None, help="Target port; must be a nonzero explicit port for forwarding.")
+    serve_local_proxy.add_argument("--upstream-url", help="Optional upstream URL; host must be a literal loopback IP for serving.")
+    serve_local_proxy.add_argument("--proxy-label", help="Safe label for this local proxy serve run.")
+    serve_local_proxy.add_argument(
+        "--diagnostic-ledger-jsonl",
+        help="Append one shifted-cost diagnostic JSONL row only after a successful loopback forwarded request.",
+    )
+    serve_local_proxy.add_argument("--api-key", help="Blocked/redacted API key material; never persisted or emitted raw.")
+    serve_local_proxy.add_argument("--authorization-header", help="Blocked/redacted Authorization header; never persisted or emitted raw.")
+    serve_local_proxy.add_argument("--persist-api-key", action="store_true", help="Declare API-key persistence intent; blocked.")
+    serve_local_proxy.add_argument(
+        "--external-forwarding-intent",
+        action="store_true",
+        help="Declare external forwarding intent; blocked in this local-only runtime.",
+    )
+    serve_local_proxy.add_argument(
+        "--runtime-gate-ack",
+        action="store_true",
+        help="Acknowledge this is an explicit experimental runtime.",
+    )
+    serve_local_proxy.add_argument(
+        "--forwarding-gate-ack",
+        action="store_true",
+        help="Acknowledge this starts a loopback-only forwarding listener for one bounded request.",
+    )
+    serve_local_proxy.add_argument("--once", action="store_true", help="Serve exactly one accepted or blocked request; required for this MVP.")
+    serve_local_proxy.add_argument(
+        "--max-request-bytes",
+        default=None,
+        help=f"Maximum request body bytes, 1..{LOCAL_PROXY_MAX_FORWARD_BYTES}.",
+    )
+    serve_local_proxy.add_argument(
+        "--max-response-bytes",
+        default=None,
+        help=f"Maximum upstream response bytes, 1..{LOCAL_PROXY_MAX_FORWARD_BYTES}.",
+    )
+    serve_local_proxy.add_argument(
+        "--timeout-seconds",
+        default=None,
+        help=f"Listener/upstream timeout seconds, 0.1..{LOCAL_PROXY_MAX_TIMEOUT_SECONDS}.",
+    )
+    serve_local_proxy.add_argument("--ready-file", help=argparse.SUPPRESS)
+    serve_local_proxy.add_argument("--json", action="store_true", help="Emit JSON output after the single request completes.")
+    serve_local_proxy.set_defaults(func=command_serve_local_proxy)
+
     return parser