diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index edf88713..a16ec17a 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -28,6 +28,9 @@ jobs:
   # codebase targets.
   zig:
     runs-on: ubuntu-latest
+    env:
+      # Integration tests are deterministic/offline; hosted MCP is covered separately.
+      GRAFF_NO_SMOLIFY: "1"
     steps:
       - uses: actions/checkout@v4
 
@@ -54,9 +57,6 @@ jobs:
       - name: Live JSON stream contains no raw stdout lines
         run: python3 scripts/test-json-live.py zig-out/bin/graff
 
-      - name: PTY spinner anti-stealth test
-        run: python3 scripts/test-pty-spinner.py zig-out/bin/graff
-
       - name: PTY REPL interaction test
         run: python3 scripts/test-pty-repl.py zig-out/bin/graff
 
diff --git a/README.md b/README.md
index 403f30ee..4d9764b6 100644
--- a/README.md
+++ b/README.md
@@ -450,6 +450,36 @@ turns it back on, and `/goal status` shows the objective and its current state.
 blocked, cancelled, or exhausted) once the work is done, you step in, or a safety
 limit is hit, instead of pausing for confirmation between routine steps.
 
+### MCP servers
+
+Graff speaks both MCP transports directly: local stdio servers and remote
+Streamable HTTP servers. Smolify (`https://app.smol.ly/mcp`) is connected as a
+core, anonymous documentation service; it needs no Node bridge or project
+configuration. This performs discovery requests at startup and tool queries may
+be sent to the hosted service; set `GRAFF_NO_SMOLIFY=1` for offline or
+privacy-sensitive sessions. Other servers can be added from the shell or during
+a session:
+
+```sh
+graff mcp add context7 -- npx -y @upstash/context7-mcp
+graff mcp add mobbin --url https://api.mobbin.com/mcp
+graff mcp login mobbin   # OAuth discovery + browser PKCE flow
+graff mcp login smolify  # optional access to authenticated Smolify tools
+# In the REPL: /mcp add mobbin --url https://api.mobbin.com/mcp
+```
+
+The equivalent `.mcp.json` URL entry is
+`{"mcpServers":{"mobbin":{"url":"https://api.mobbin.com/mcp"}}}`. Remote
+responses may use either `application/json` or `text/event-stream`; Graff keeps
+`Mcp-Session-Id` state and sends `MCP-Protocol-Version` on requests.
+For OAuth-protected endpoints, `graff mcp login <name>` performs protected
+resource and authorization-server discovery, dynamic client registration, and
+a browser PKCE flow. Tokens are stored outside the repository under
+`~/.simple-harness-mcp` with user-only permissions and refreshed automatically.
+Static HTTP headers can alternatively be added with
+`--header 'Authorization=Bearer TOKEN'` (they are stored in `.mcp.json`, so
+prefer a restricted token and do not commit that file).
+
 The line editor supports ↑/↓ history (persisted to `~/.simple-harness-history`),
 Tab completion (commands, and model names after `/model `), and emacs-style
 editing (Ctrl-A/E/W/U/K, Option+Delete, word moves). The selected model is
diff --git a/docs/debugging-the-harness.md b/docs/debugging-the-harness.md
index 485c8a60..2b4e0ce0 100644
--- a/docs/debugging-the-harness.md
+++ b/docs/debugging-the-harness.md
@@ -2,7 +2,7 @@
 
 How we chase down "why is graff slow / wrong here" bugs, distilled from real sessions
 (most recently #117, the first-turn latency hunt that found *three* stacked synchronous
-calls, and the 💩-spinner hunt that exposed non-representative testing).
+calls).
 
 ## The one core lesson
 Almost every "graff feels slow" bug is the **main thread blocking on a network or model
@@ -98,14 +98,12 @@ Find the `.await(io)` / join on the critical path. Real ones found this way:
 
 ## 6. Verify like you mean it
 - **Mutation-test the guard.** Reintroduce the bug and confirm the *exact* test reddens.
-  A green suite that doesn't fail when you break the code proves nothing — that blind spot
-  is how the runtime-built 💩 spinner survived `strings`/`grep` for hours.
-- **Representative > surface.** Scan rendered bytes from a real PTY, hit a real-socket
-  mock — not `strings`, not a frame-fn called in isolation (which can't see a
-  startup-gated override).
+  A green suite that doesn't fail when you break the code proves nothing.
+- **Representative > surface.** Exercise rendered output through a real PTY and use a
+  real-socket mock rather than testing only isolated helpers.
 - Let `ci.yml` gate it: `zig build`, `zig fmt --check`, `zig build test`, the JSON
-  live-control test, the **PTY anti-stealth scan**, and **SDK-drift regen** (CI was red for
-  the whole history once because a model/tool landed without regenerating `sdk/`).
+  live-control test, and **SDK-drift regen** (CI was red for the whole history once
+  because a model/tool landed without regenerating `sdk/`).
 
 ## Traps that cost real time
 - **Prompt caching neutralizes tool-list size.** With ~99% cached input (`9216/9289 in`),
diff --git a/scripts/codex_ws_test.py b/scripts/codex_ws_test.py
new file mode 100644
index 00000000..46cb1399
--- /dev/null
+++ b/scripts/codex_ws_test.py
@@ -0,0 +1,583 @@
+#!/usr/bin/env python3
+"""Deterministic real-PTY tests for Codex transport and mid-turn compaction.
+
+The transport smokes cover WebSocket primary, forced SSE fallback, and
+GRAFF_CODEX_WS=off. The regression scenarios drive real tool loops whose
+server-reported usage crosses compact@ while local history stays tiny. They
+prove both successful compaction and transactional rollback after an empty
+summary across WS -> quiet SSE compaction -> fresh WS.
+"""
+
+import json
+import os
+import re
+import sys
+import tempfile
+
+from codex_ws_mock import REPLY_TEXT, CodexMock, RecordedRequest
+from pty_harness import PtySession, terminal_text
+
+_arg = sys.argv[1] if len(sys.argv) > 1 else "graff"
+GRAFF = os.path.abspath(_arg) if os.sep in _arg else _arg
+
+
+# The reported 1500-token usage is conservatively floored by graff's serialized
+# request estimate, so the displayed used count can move with the built-in tool
+# schema. Assert the meter shape and invariants rather than freezing either the
+# prefill estimate or the Codex catalog window.
+METER_RE = re.compile(r"(\d+)(k?)/(\d+)k ctx \((\d+)% · compact@(\d+)k\)")
+COMPACTING_RE = re.compile(r"compacting ~(\d+) tokens")
+
+MIDTURN_PROMPT = "exercise the server-side context meter"
+MIDTURN_SUMMARY = "The user asked to exercise the server-side context meter."
+MIDTURN_FINAL = "done after mid-turn compact"
+# Cross compact@ (80%) but stay below the destructive recovery boundary (95%).
+# The smoke scenarios set this from the context meter emitted after the runtime
+# Codex catalog has loaded, rather than the static --schema catalog.
+MIDTURN_TOTAL_TOKENS = 0
+MIDTURN_CONTEXT_TOKENS = 0
+MIDTURN_REASONING_MARKER = "retained-active-reasoning:"
+MIDTURN_REASONING_BYTES = 128 * 1024
+
+TRANSACTIONAL_PROMPT = "prove failed compaction keeps the live tool loop"
+TRANSACTIONAL_FINAL = "done after transactional compaction failure"
+TRANSACTIONAL_REASONING_MARKER = "transactional-active-reasoning:"
+TRANSACTIONAL_CALL_ID = "call_transactional_1"
+
+
+def response_events(
+    item: dict | list[dict], response_id: str, total_tokens: int
+) -> list[dict]:
+    """Build the two Responses events parseResponses consumes."""
+    output_tokens = 1_000 if total_tokens > 2_000 else 100
+    items = item if isinstance(item, list) else [item]
+    return [
+        *(
+            {"type": "response.output_item.done", "item": output_item}
+            for output_item in items
+        ),
+        {
+            "type": "response.completed",
+            "response": {
+                "id": response_id,
+                "usage": {
+                    "input_tokens": total_tokens - output_tokens,
+                    "input_tokens_details": {"cached_tokens": 0},
+                    "output_tokens": output_tokens,
+                    "total_tokens": total_tokens,
+                },
+            },
+        },
+    ]
+
+
+def message_item(text: str, item_id: str) -> dict:
+    return {
+        "type": "message",
+        "id": item_id,
+        "status": "completed",
+        "role": "assistant",
+        "content": [{"type": "output_text", "text": text, "annotations": []}],
+    }
+
+
+def active_reasoning_item() -> dict:
+    """A large current-loop item that compact() must prune before full resend."""
+    encrypted = MIDTURN_REASONING_MARKER + "R" * (
+        MIDTURN_REASONING_BYTES - len(MIDTURN_REASONING_MARKER)
+    )
+    return {
+        "type": "reasoning",
+        "id": "rs_midturn_1",
+        "summary": [],
+        "encrypted_content": encrypted,
+    }
+
+
+def midturn_events(request: RecordedRequest) -> list[dict]:
+    """Script tool call -> compaction summary -> final answer."""
+    if request.ordinal == 1:
+        item = {
+            "type": "function_call",
+            "id": "fc_midturn_1",
+            "call_id": "call_midturn_1",
+            "name": "todo_read",
+            "arguments": "{}",
+            "status": "completed",
+        }
+        # Real high-effort Responses tool loops return reasoning immediately
+        # before the function call. It is current-turn history here, but once
+        # compact() appends its synthetic user turn it must be pruned before the
+        # full SSE summary resend.
+        return response_events(
+            [active_reasoning_item(), item],
+            "resp_midturn_1",
+            MIDTURN_TOTAL_TOKENS,
+        )
+    if request.ordinal == 2:
+        return response_events(
+            message_item(MIDTURN_SUMMARY, "msg_midturn_summary"),
+            "resp_midturn_summary",
+            1_100,
+        )
+    return response_events(
+        message_item(MIDTURN_FINAL, "msg_midturn_final"),
+        f"resp_midturn_{request.ordinal}",
+        1_300,
+    )
+
+
+def transactional_reasoning_item() -> dict:
+    encrypted = TRANSACTIONAL_REASONING_MARKER + "R" * (
+        MIDTURN_REASONING_BYTES - len(TRANSACTIONAL_REASONING_MARKER)
+    )
+    return {
+        "type": "reasoning",
+        "id": "rs_transactional_1",
+        "summary": [],
+        "encrypted_content": encrypted,
+    }
+
+
+def transactional_events(request: RecordedRequest) -> list[dict]:
+    """Script tool call -> empty summary -> answer from restored live history."""
+    if request.ordinal == 1:
+        call = {
+            "type": "function_call",
+            "id": "fc_transactional_1",
+            "call_id": TRANSACTIONAL_CALL_ID,
+            "name": "todo_read",
+            "arguments": "{}",
+            "status": "completed",
+        }
+        return response_events(
+            [transactional_reasoning_item(), call],
+            "resp_transactional_1",
+            MIDTURN_TOTAL_TOKENS,
+        )
+    if request.ordinal == 2:
+        # A syntactically valid Responses answer with no summary text exercises
+        # compact()'s EmptySummary rollback, rather than a transport failure.
+        return response_events(
+            message_item("", "msg_transactional_empty_summary"),
+            "resp_transactional_empty_summary",
+            1_100,
+        )
+    return response_events(
+        message_item(TRANSACTIONAL_FINAL, "msg_transactional_final"),
+        f"resp_transactional_{request.ordinal}",
+        1_300,
+    )
+
+
+def user_text(item: object) -> str | None:
+    if not isinstance(item, dict) or item.get("role") != "user":
+        return None
+    content = item.get("content")
+    return content if isinstance(content, str) else None
+
+
+def assert_compaction_meter(label: str, rendered: str) -> None:
+    match = COMPACTING_RE.search(rendered)
+    if match is None:
+        raise AssertionError(
+            f"{label}: server-reported usage did not trigger pre-send "
+            f"compaction:\n{rendered}"
+        )
+    observed = int(match.group(1))
+    # The provider sample is the lower bound. A tool result appended after that
+    # sample should increase the anchored effective meter slightly, while the
+    # compaction still runs before the advertised context wall.
+    if not MIDTURN_TOTAL_TOKENS <= observed < MIDTURN_CONTEXT_TOKENS:
+        raise AssertionError(
+            f"{label}: compacted at {observed} tokens, expected at least the "
+            f"{MIDTURN_TOTAL_TOKENS} provider sample and below the "
+            f"{MIDTURN_CONTEXT_TOKENS} context window"
+        )
+
+
+def run_scenario(
+    label: str,
+    tmp: str,
+    codex_home: str,
+    port: int,
+    mock: CodexMock,
+    extra_env: dict,
+    expect_ws: int,
+    expect_sse: int,
+    health: str,
+) -> int:
+    env = {
+        "HOME": tmp,
+        "CODEX_HOME": codex_home,
+        "CODEGRAFF_API_KEY": "local-pty-test",
+        "GRAFF_FLEET": "off",
+        "GRAFF_NO_TELEMETRY": "1",
+        "GRAFF_CODEX_URL": f"http://127.0.0.1:{port}/backend-api/codex/responses",
+    }
+    env.update(extra_env)
+    # PtySession builds the child env from os.environ.copy(), so ambient
+    # transport/credential knobs (an exported GRAFF_CODEX_WS=off, a leftover
+    # GRAFF_WS_FORCE_FAIL_ONCE=1, CODEX_DISABLED, ...) would leak into every
+    # scenario and flip its transport. Strip all ambient GRAFF_*/CODEX_* the
+    # scenario does not set itself; unset_env is applied AFTER env, so keys we
+    # set deliberately must be excluded.
+    ambient = tuple(
+        k
+        for k in os.environ
+        if (k.startswith("GRAFF_") or k.startswith("CODEX_") or k == "NO_COLOR")
+        and k not in env
+    )
+    with PtySession(
+        GRAFF,
+        ["--model", "codex", "--no-telemetry"],
+        cwd=tmp,
+        env=env,
+        unset_env=ambient,
+        timeout=20.0,
+    ) as session:
+        session.wait_for_literal("] ›")
+        cursor = len(session.raw)
+        session.send_line("ping")
+        session.wait_for_literal(REPLY_TEXT, start=cursor)
+        session.wait_for(METER_RE, start=cursor)
+        meter = METER_RE.search(terminal_text(bytes(session.raw[cursor:])))
+        used = int(meter.group(1)) * (1000 if meter.group(2) == "k" else 1)
+        ctx_k, pct, compact_k = map(int, meter.group(3, 4, 5))
+        if used <= 0 or not 0 <= pct <= 100:
+            raise AssertionError(
+                f"{label}: invalid context meter values used={used} pct={pct}"
+            )
+        if ctx_k <= 0 or not 79 * ctx_k <= 100 * compact_k <= 81 * ctx_k:
+            raise AssertionError(
+                f"{label}: inconsistent meter context={ctx_k}k compact@={compact_k}k"
+            )
+        if mock.ws_turns != expect_ws or mock.sse_turns != expect_sse:
+            raise AssertionError(
+                f"{label}: transport mismatch — ws_turns={mock.ws_turns} "
+                f"sse_turns={mock.sse_turns}, expected ws={expect_ws} sse={expect_sse}"
+            )
+        cursor = len(session.raw)
+        session.send_line("/models health")
+        session.wait_for_literal(f"Codex transport: {health}", start=cursor)
+        session.wait_for_literal("] ›", start=cursor)
+        session.send_key("ctrl-d")
+        result = session.read_until_exit(5.0)
+        if result.timed_out or result.exit_code != 0:
+            raise SystemExit(
+                f"{label}: REPL did not exit cleanly: "
+                f"exit={result.exit_code} timed_out={result.timed_out}"
+            )
+        return ctx_k * 1000
+
+
+def assert_midturn_requests(mock: CodexMock) -> None:
+    requests = mock.recorded_requests()
+    if len(requests) != 3:
+        raise AssertionError(
+            f"midturn: expected exactly 3 model requests, got {len(requests)}: {requests!r}"
+        )
+    first, compact, final = requests
+    if any("max_output_tokens" in request.body for request in requests):
+        raise AssertionError("midturn: Responses requests must omit max_output_tokens")
+    transports = [request.transport for request in requests]
+    if transports != ["ws", "sse", "ws"]:
+        raise AssertionError(f"midturn: expected WS -> SSE -> WS, got {transports!r}")
+    if mock.ws_turns != 2 or mock.sse_turns != 1 or mock.ws_connections != 2:
+        raise AssertionError(
+            "midturn: expected two turns on two fresh WS connections plus one SSE "
+            f"turn; ws_turns={mock.ws_turns} sse_turns={mock.sse_turns} "
+            f"ws_connections={mock.ws_connections}"
+        )
+    if first.connection_id == final.connection_id:
+        raise AssertionError("midturn: final request reused the pre-compaction WS")
+    for request in requests:
+        if "previous_response_id" in request.body:
+            raise AssertionError(
+                f"midturn: request {request.ordinal} carried stale previous_response_id: "
+                f"{request.body['previous_response_id']!r}"
+            )
+
+    first_input = first.body.get("input")
+    if (
+        first.body.get("type") != "response.create"
+        or not isinstance(first_input, list)
+        or not any(user_text(item) == MIDTURN_PROMPT for item in first_input)
+        or "tools" not in first.body
+    ):
+        raise AssertionError(
+            f"midturn: first WS request was not full tool-enabled input: {first.body!r}"
+        )
+
+    compact_input = compact.body.get("input")
+    compact_texts = (
+        [text for item in compact_input if (text := user_text(item)) is not None]
+        if isinstance(compact_input, list)
+        else []
+    )
+    compact_types = (
+        [item.get("type") for item in compact_input if isinstance(item, dict)]
+        if isinstance(compact_input, list)
+        else []
+    )
+    compact_json = json.dumps(compact.body, separators=(",", ":"))
+    if "reasoning" in compact_types or MIDTURN_REASONING_MARKER in compact_json:
+        raise AssertionError(
+            "midturn: SSE compaction request retained the active-loop reasoning item"
+        )
+    if (
+        compact.connection_id is not None
+        or "tools" in compact.body
+        or MIDTURN_PROMPT not in compact_texts
+        or "function_call" not in compact_types
+        or "function_call_output" not in compact_types
+        or not any(
+            text.startswith("Summarize this entire conversation")
+            for text in compact_texts
+        )
+    ):
+        raise AssertionError(
+            f"midturn: compaction request was not a full, tool-free SSE summary request: {compact.body!r}"
+        )
+
+    final_input = final.body.get("input")
+    final_texts = (
+        [text for item in final_input if (text := user_text(item)) is not None]
+        if isinstance(final_input, list)
+        else []
+    )
+    if (
+        final.body.get("type") != "response.create"
+        or not isinstance(final_input, list)
+        or len(final_input) != 1
+        or len(final_texts) != 1
+        or not final_texts[0].startswith(
+            "Context: the earlier conversation was compacted"
+        )
+        or MIDTURN_SUMMARY not in final_texts[0]
+        or "tools" not in final.body
+    ):
+        raise AssertionError(
+            "midturn: final WS request did not fully re-anchor on the handoff: "
+            f"{final.body!r}"
+        )
+
+
+def assert_transactional_requests(mock: CodexMock) -> None:
+    requests = mock.recorded_requests()
+    if len(requests) != 3:
+        raise AssertionError(
+            "transactional: expected exactly 3 model requests, "
+            f"got {len(requests)}: {requests!r}"
+        )
+    first, compact, final = requests
+    if any("max_output_tokens" in request.body for request in requests):
+        raise AssertionError("transactional: Responses requests must omit max_output_tokens")
+    transports = [request.transport for request in requests]
+    if transports != ["ws", "sse", "ws"]:
+        raise AssertionError(
+            f"transactional: expected WS -> SSE -> WS, got {transports!r}"
+        )
+    if mock.ws_turns != 2 or mock.sse_turns != 1 or mock.ws_connections != 2:
+        raise AssertionError(
+            "transactional: expected two turns on two fresh WS connections plus "
+            f"one SSE turn; ws_turns={mock.ws_turns} sse_turns={mock.sse_turns} "
+            f"ws_connections={mock.ws_connections}"
+        )
+    if first.connection_id == final.connection_id:
+        raise AssertionError(
+            "transactional: final request reused the pre-compaction WS"
+        )
+    for request in requests:
+        if "previous_response_id" in request.body:
+            raise AssertionError(
+                f"transactional: request {request.ordinal} carried stale "
+                f"previous_response_id: {request.body['previous_response_id']!r}"
+            )
+
+    first_input = first.body.get("input")
+    if (
+        first.body.get("type") != "response.create"
+        or not isinstance(first_input, list)
+        or not any(user_text(item) == TRANSACTIONAL_PROMPT for item in first_input)
+        or "tools" not in first.body
+    ):
+        raise AssertionError(
+            "transactional: first WS request was not full tool-enabled input: "
+            f"{first.body!r}"
+        )
+
+    compact_input = compact.body.get("input")
+    compact_texts = (
+        [text for item in compact_input if (text := user_text(item)) is not None]
+        if isinstance(compact_input, list)
+        else []
+    )
+    compact_json = json.dumps(compact.body, separators=(",", ":"))
+    if (
+        compact.connection_id is not None
+        or "tools" in compact.body
+        or TRANSACTIONAL_PROMPT not in compact_texts
+        or TRANSACTIONAL_REASONING_MARKER in compact_json
+        or not any(
+            text.startswith("Summarize this entire conversation")
+            for text in compact_texts
+        )
+    ):
+        raise AssertionError(
+            "transactional: second request was not the pruned, synthetic SSE "
+            f"summary request: {compact.body!r}"
+        )
+
+    final_input = final.body.get("input")
+    final_texts = (
+        [text for item in final_input if (text := user_text(item)) is not None]
+        if isinstance(final_input, list)
+        else []
+    )
+    final_objects = (
+        [item for item in final_input if isinstance(item, dict)]
+        if isinstance(final_input, list)
+        else []
+    )
+    reasoning = [
+        item
+        for item in final_objects
+        if item.get("type") == "reasoning" and item.get("id") == "rs_transactional_1"
+    ]
+    calls = [
+        item
+        for item in final_objects
+        if item.get("type") == "function_call"
+        and item.get("id") == "fc_transactional_1"
+        and item.get("call_id") == TRANSACTIONAL_CALL_ID
+    ]
+    outputs = [
+        item
+        for item in final_objects
+        if item.get("type") == "function_call_output"
+        and item.get("call_id") == TRANSACTIONAL_CALL_ID
+        and isinstance(item.get("output"), str)
+        and len(item["output"]) > 0
+    ]
+    leaked_summary_response = any(
+        item.get("id") == "msg_transactional_empty_summary" for item in final_objects
+    )
+    if (
+        final.body.get("type") != "response.create"
+        or not isinstance(final_input, list)
+        or "tools" not in final.body
+        or TRANSACTIONAL_PROMPT not in final_texts
+        or any(
+            text.startswith("Summarize this entire conversation")
+            for text in final_texts
+        )
+        or not any(
+            isinstance(item.get("encrypted_content"), str)
+            and item["encrypted_content"].startswith(TRANSACTIONAL_REASONING_MARKER)
+            and len(item["encrypted_content"]) == MIDTURN_REASONING_BYTES
+            for item in reasoning
+        )
+        or len(calls) != 1
+        or len(outputs) != 1
+        or leaked_summary_response
+    ):
+        raise AssertionError(
+            "transactional: final WS request did not restore the original prompt, "
+            "reasoning, function call, and output without the synthetic compact "
+            f"instruction: {final.body!r}"
+        )
+
+
+def run_midturn_compaction_scenario(
+    tmp: str, codex_home: str, port: int, mock: CodexMock
+) -> None:
+    env = {
+        "HOME": tmp,
+        "CODEX_HOME": codex_home,
+        "CODEGRAFF_API_KEY": "local-pty-test",
+        "GRAFF_FLEET": "off",
+        "GRAFF_NO_TELEMETRY": "1",
+        "GRAFF_CODEX_URL": f"http://127.0.0.1:{port}/backend-api/codex/responses",
+    }
+    ambient = tuple(
+        key
+        for key in os.environ
+        if (key.startswith("GRAFF_") or key.startswith("CODEX_") or key == "NO_COLOR")
+        and key not in env
+    )
+    with PtySession(
+        GRAFF,
+        ["--model", "codex", "--no-telemetry"],
+        cwd=tmp,
+        env=env,
+        unset_env=ambient,
+        timeout=20.0,
+    ) as session:
+        session.wait_for_literal("] ›")
+        cursor = len(session.raw)
+        session.send_line(MIDTURN_PROMPT)
+        session.wait_for_literal(MIDTURN_FINAL, start=cursor)
+        session.wait_for_literal("history compacted to a", start=cursor)
+        session.pump_for(0.1)
+        rendered = terminal_text(bytes(session.raw[cursor:]))
+        assert_compaction_meter("midturn", rendered)
+        assert_midturn_requests(mock)
+        session.send_key("ctrl-d")
+        result = session.read_until_exit(5.0)
+        if result.timed_out or result.exit_code != 0:
+            raise SystemExit(
+                "midturn: REPL did not exit cleanly: "
+                f"exit={result.exit_code} timed_out={result.timed_out}"
+            )
+
+
+def run_transactional_compaction_scenario(
+    tmp: str, codex_home: str, port: int, mock: CodexMock
+) -> None:
+    env = {
+        "HOME": tmp,
+        "CODEX_HOME": codex_home,
+        "CODEGRAFF_API_KEY": "local-pty-test",
+        "GRAFF_FLEET": "off",
+        "GRAFF_NO_TELEMETRY": "1",
+        "GRAFF_CODEX_URL": f"http://127.0.0.1:{port}/backend-api/codex/responses",
+    }
+    ambient = tuple(
+        key
+        for key in os.environ
+        if (key.startswith("GRAFF_") or key.startswith("CODEX_") or key == "NO_COLOR")
+        and key not in env
+    )
+    with PtySession(
+        GRAFF,
+        ["--model", "codex", "--no-telemetry"],
+        cwd=tmp,
+        env=env,
+        unset_env=ambient,
+        timeout=20.0,
+    ) as session:
+        session.wait_for_literal("] ›")
+        cursor = len(session.raw)
+        session.send_line(TRANSACTIONAL_PROMPT)
+        session.wait_for_literal(
+            "compaction failed: empty summary, history unchanged", start=cursor
+        )
+        session.wait_for_literal(TRANSACTIONAL_FINAL, start=cursor)
+        session.pump_for(0.1)
+        rendered = terminal_text(bytes(session.raw[cursor:]))
+        assert_compaction_meter("transactional", rendered)
+        if "history compacted to a" in rendered:
+            raise AssertionError(
+                f"transactional: empty summary was incorrectly installed:\n{rendered}"
+            )
+        assert_transactional_requests(mock)
+        session.send_key("ctrl-d")
+        result = session.read_until_exit(5.0)
+        if result.timed_out or result.exit_code != 0:
+            raise SystemExit(
+                "transactional: REPL did not exit cleanly: "
+                f"exit={result.exit_code} timed_out={result.timed_out}"
+            )
+
+
diff --git a/scripts/test-json-controls.py b/scripts/test-json-controls.py
index 04078ae8..e667f03e 100755
--- a/scripts/test-json-controls.py
+++ b/scripts/test-json-controls.py
@@ -89,6 +89,8 @@ def run():
         p = subprocess.run([BIN, "--json"], input=stdin, text=True,
                            capture_output=True, timeout=60, env=env)
         out = p.stdout
+        if p.returncode != 0:
+            print(f"graff exited {p.returncode}; stderr follows:\n{p.stderr}", file=sys.stderr)
     except subprocess.TimeoutExpired as e:
         out = (e.stdout or b"").decode("utf-8", "ignore") if isinstance(e.stdout, bytes) else (e.stdout or "")
 
diff --git a/scripts/test-pty-codex-ws.py b/scripts/test-pty-codex-ws.py
index ce6fc057..07617519 100644
--- a/scripts/test-pty-codex-ws.py
+++ b/scripts/test-pty-codex-ws.py
@@ -1,589 +1,15 @@
 #!/usr/bin/env python3
-"""Deterministic real-PTY tests for Codex transport and mid-turn compaction.
-
-The transport smokes cover WebSocket primary, forced SSE fallback, and
-GRAFF_CODEX_WS=off. The regression scenarios drive real tool loops whose
-server-reported usage crosses compact@ while local history stays tiny. They
-prove both successful compaction and transactional rollback after an empty
-summary across WS -> quiet SSE compaction -> fresh WS.
-"""
+"""Entry point for the Codex WebSocket and compaction PTY scenarios."""
 
 import json
 import os
-import re
-import sys
 import tempfile
 
-from codex_ws_mock import REPLY_TEXT, CodexMock, RecordedRequest
-from pty_harness import PtySession, terminal_text
-
-_arg = sys.argv[1] if len(sys.argv) > 1 else "graff"
-GRAFF = os.path.abspath(_arg) if os.sep in _arg else _arg
-
-
-# The reported 1500-token usage is conservatively floored by graff's serialized
-# request estimate, so the displayed used count can move with the built-in tool
-# schema. Assert the meter shape and invariants rather than freezing either the
-# prefill estimate or the Codex catalog window.
-METER_RE = re.compile(r"(\d+)(k?)/(\d+)k ctx \((\d+)% · compact@(\d+)k\)")
-COMPACTING_RE = re.compile(r"compacting ~(\d+) tokens")
-
-MIDTURN_PROMPT = "exercise the server-side context meter"
-MIDTURN_SUMMARY = "The user asked to exercise the server-side context meter."
-MIDTURN_FINAL = "done after mid-turn compact"
-# Cross compact@ (80%) but stay below the destructive recovery boundary (95%).
-# The smoke scenarios set this from the context meter emitted after the runtime
-# Codex catalog has loaded, rather than the static --schema catalog.
-MIDTURN_TOTAL_TOKENS = 0
-MIDTURN_CONTEXT_TOKENS = 0
-MIDTURN_REASONING_MARKER = "retained-active-reasoning:"
-MIDTURN_REASONING_BYTES = 128 * 1024
-
-TRANSACTIONAL_PROMPT = "prove failed compaction keeps the live tool loop"
-TRANSACTIONAL_FINAL = "done after transactional compaction failure"
-TRANSACTIONAL_REASONING_MARKER = "transactional-active-reasoning:"
-TRANSACTIONAL_CALL_ID = "call_transactional_1"
-
-
-def response_events(
-    item: dict | list[dict], response_id: str, total_tokens: int
-) -> list[dict]:
-    """Build the two Responses events parseResponses consumes."""
-    output_tokens = 1_000 if total_tokens > 2_000 else 100
-    items = item if isinstance(item, list) else [item]
-    return [
-        *(
-            {"type": "response.output_item.done", "item": output_item}
-            for output_item in items
-        ),
-        {
-            "type": "response.completed",
-            "response": {
-                "id": response_id,
-                "usage": {
-                    "input_tokens": total_tokens - output_tokens,
-                    "input_tokens_details": {"cached_tokens": 0},
-                    "output_tokens": output_tokens,
-                    "total_tokens": total_tokens,
-                },
-            },
-        },
-    ]
-
-
-def message_item(text: str, item_id: str) -> dict:
-    return {
-        "type": "message",
-        "id": item_id,
-        "status": "completed",
-        "role": "assistant",
-        "content": [{"type": "output_text", "text": text, "annotations": []}],
-    }
-
-
-def active_reasoning_item() -> dict:
-    """A large current-loop item that compact() must prune before full resend."""
-    encrypted = MIDTURN_REASONING_MARKER + "R" * (
-        MIDTURN_REASONING_BYTES - len(MIDTURN_REASONING_MARKER)
-    )
-    return {
-        "type": "reasoning",
-        "id": "rs_midturn_1",
-        "summary": [],
-        "encrypted_content": encrypted,
-    }
-
-
-def midturn_events(request: RecordedRequest) -> list[dict]:
-    """Script tool call -> compaction summary -> final answer."""
-    if request.ordinal == 1:
-        item = {
-            "type": "function_call",
-            "id": "fc_midturn_1",
-            "call_id": "call_midturn_1",
-            "name": "todo_read",
-            "arguments": "{}",
-            "status": "completed",
-        }
-        # Real high-effort Responses tool loops return reasoning immediately
-        # before the function call. It is current-turn history here, but once
-        # compact() appends its synthetic user turn it must be pruned before the
-        # full SSE summary resend.
-        return response_events(
-            [active_reasoning_item(), item],
-            "resp_midturn_1",
-            MIDTURN_TOTAL_TOKENS,
-        )
-    if request.ordinal == 2:
-        return response_events(
-            message_item(MIDTURN_SUMMARY, "msg_midturn_summary"),
-            "resp_midturn_summary",
-            1_100,
-        )
-    return response_events(
-        message_item(MIDTURN_FINAL, "msg_midturn_final"),
-        f"resp_midturn_{request.ordinal}",
-        1_300,
-    )
-
-
-def transactional_reasoning_item() -> dict:
-    encrypted = TRANSACTIONAL_REASONING_MARKER + "R" * (
-        MIDTURN_REASONING_BYTES - len(TRANSACTIONAL_REASONING_MARKER)
-    )
-    return {
-        "type": "reasoning",
-        "id": "rs_transactional_1",
-        "summary": [],
-        "encrypted_content": encrypted,
-    }
-
-
-def transactional_events(request: RecordedRequest) -> list[dict]:
-    """Script tool call -> empty summary -> answer from restored live history."""
-    if request.ordinal == 1:
-        call = {
-            "type": "function_call",
-            "id": "fc_transactional_1",
-            "call_id": TRANSACTIONAL_CALL_ID,
-            "name": "todo_read",
-            "arguments": "{}",
-            "status": "completed",
-        }
-        return response_events(
-            [transactional_reasoning_item(), call],
-            "resp_transactional_1",
-            MIDTURN_TOTAL_TOKENS,
-        )
-    if request.ordinal == 2:
-        # A syntactically valid Responses answer with no summary text exercises
-        # compact()'s EmptySummary rollback, rather than a transport failure.
-        return response_events(
-            message_item("", "msg_transactional_empty_summary"),
-            "resp_transactional_empty_summary",
-            1_100,
-        )
-    return response_events(
-        message_item(TRANSACTIONAL_FINAL, "msg_transactional_final"),
-        f"resp_transactional_{request.ordinal}",
-        1_300,
-    )
-
-
-def user_text(item: object) -> str | None:
-    if not isinstance(item, dict) or item.get("role") != "user":
-        return None
-    content = item.get("content")
-    return content if isinstance(content, str) else None
-
-
-def assert_compaction_meter(label: str, rendered: str) -> None:
-    match = COMPACTING_RE.search(rendered)
-    if match is None:
-        raise AssertionError(
-            f"{label}: server-reported usage did not trigger pre-send "
-            f"compaction:\n{rendered}"
-        )
-    observed = int(match.group(1))
-    # The provider sample is the lower bound. A tool result appended after that
-    # sample should increase the anchored effective meter slightly, while the
-    # compaction still runs before the advertised context wall.
-    if not MIDTURN_TOTAL_TOKENS <= observed < MIDTURN_CONTEXT_TOKENS:
-        raise AssertionError(
-            f"{label}: compacted at {observed} tokens, expected at least the "
-            f"{MIDTURN_TOTAL_TOKENS} provider sample and below the "
-            f"{MIDTURN_CONTEXT_TOKENS} context window"
-        )
-
-
-def run_scenario(
-    label: str,
-    tmp: str,
-    codex_home: str,
-    port: int,
-    mock: CodexMock,
-    extra_env: dict,
-    expect_ws: int,
-    expect_sse: int,
-    health: str,
-) -> int:
-    env = {
-        "HOME": tmp,
-        "CODEX_HOME": codex_home,
-        "CODEGRAFF_API_KEY": "local-pty-test",
-        "GRAFF_FLEET": "off",
-        "GRAFF_NO_TELEMETRY": "1",
-        "GRAFF_CODEX_URL": f"http://127.0.0.1:{port}/backend-api/codex/responses",
-    }
-    env.update(extra_env)
-    # PtySession builds the child env from os.environ.copy(), so ambient
-    # transport/credential knobs (an exported GRAFF_CODEX_WS=off, a leftover
-    # GRAFF_WS_FORCE_FAIL_ONCE=1, CODEX_DISABLED, ...) would leak into every
-    # scenario and flip its transport. Strip all ambient GRAFF_*/CODEX_* the
-    # scenario does not set itself; unset_env is applied AFTER env, so keys we
-    # set deliberately must be excluded.
-    ambient = tuple(
-        k
-        for k in os.environ
-        if (k.startswith("GRAFF_") or k.startswith("CODEX_") or k == "NO_COLOR")
-        and k not in env
-    )
-    with PtySession(
-        GRAFF,
-        ["--model", "codex", "--no-telemetry"],
-        cwd=tmp,
-        env=env,
-        unset_env=ambient,
-        timeout=20.0,
-    ) as session:
-        session.wait_for_literal("] ›")
-        cursor = len(session.raw)
-        session.send_line("ping")
-        session.wait_for_literal(REPLY_TEXT, start=cursor)
-        session.wait_for(METER_RE, start=cursor)
-        meter = METER_RE.search(terminal_text(bytes(session.raw[cursor:])))
-        used = int(meter.group(1)) * (1000 if meter.group(2) == "k" else 1)
-        ctx_k, pct, compact_k = map(int, meter.group(3, 4, 5))
-        if used <= 0 or not 0 <= pct <= 100:
-            raise AssertionError(
-                f"{label}: invalid context meter values used={used} pct={pct}"
-            )
-        if ctx_k <= 0 or not 79 * ctx_k <= 100 * compact_k <= 81 * ctx_k:
-            raise AssertionError(
-                f"{label}: inconsistent meter context={ctx_k}k compact@={compact_k}k"
-            )
-        if mock.ws_turns != expect_ws or mock.sse_turns != expect_sse:
-            raise AssertionError(
-                f"{label}: transport mismatch — ws_turns={mock.ws_turns} "
-                f"sse_turns={mock.sse_turns}, expected ws={expect_ws} sse={expect_sse}"
-            )
-        cursor = len(session.raw)
-        session.send_line("/models health")
-        session.wait_for_literal(f"Codex transport: {health}", start=cursor)
-        session.wait_for_literal("] ›", start=cursor)
-        session.send_key("ctrl-d")
-        result = session.read_until_exit(5.0)
-        if result.timed_out or result.exit_code != 0:
-            raise SystemExit(
-                f"{label}: REPL did not exit cleanly: "
-                f"exit={result.exit_code} timed_out={result.timed_out}"
-            )
-        return ctx_k * 1000
-
-
-def assert_midturn_requests(mock: CodexMock) -> None:
-    requests = mock.recorded_requests()
-    if len(requests) != 3:
-        raise AssertionError(
-            f"midturn: expected exactly 3 model requests, got {len(requests)}: {requests!r}"
-        )
-    first, compact, final = requests
-    if [request.body.get("max_output_tokens") for request in requests] != [16000, 4096, 16000]:
-        raise AssertionError("midturn: expected root/compaction/root output caps 16k/4k/16k")
-    transports = [request.transport for request in requests]
-    if transports != ["ws", "sse", "ws"]:
-        raise AssertionError(f"midturn: expected WS -> SSE -> WS, got {transports!r}")
-    if mock.ws_turns != 2 or mock.sse_turns != 1 or mock.ws_connections != 2:
-        raise AssertionError(
-            "midturn: expected two turns on two fresh WS connections plus one SSE "
-            f"turn; ws_turns={mock.ws_turns} sse_turns={mock.sse_turns} "
-            f"ws_connections={mock.ws_connections}"
-        )
-    if first.connection_id == final.connection_id:
-        raise AssertionError("midturn: final request reused the pre-compaction WS")
-    for request in requests:
-        if "previous_response_id" in request.body:
-            raise AssertionError(
-                f"midturn: request {request.ordinal} carried stale previous_response_id: "
-                f"{request.body['previous_response_id']!r}"
-            )
-
-    first_input = first.body.get("input")
-    if (
-        first.body.get("type") != "response.create"
-        or not isinstance(first_input, list)
-        or not any(user_text(item) == MIDTURN_PROMPT for item in first_input)
-        or "tools" not in first.body
-    ):
-        raise AssertionError(
-            f"midturn: first WS request was not full tool-enabled input: {first.body!r}"
-        )
-
-    compact_input = compact.body.get("input")
-    compact_texts = (
-        [text for item in compact_input if (text := user_text(item)) is not None]
-        if isinstance(compact_input, list)
-        else []
-    )
-    compact_types = (
-        [item.get("type") for item in compact_input if isinstance(item, dict)]
-        if isinstance(compact_input, list)
-        else []
-    )
-    compact_json = json.dumps(compact.body, separators=(",", ":"))
-    if "reasoning" in compact_types or MIDTURN_REASONING_MARKER in compact_json:
-        raise AssertionError(
-            "midturn: SSE compaction request retained the active-loop reasoning item"
-        )
-    if (
-        compact.connection_id is not None
-        or "tools" in compact.body
-        or MIDTURN_PROMPT not in compact_texts
-        or "function_call" not in compact_types
-        or "function_call_output" not in compact_types
-        or not any(
-            text.startswith("Summarize this entire conversation")
-            for text in compact_texts
-        )
-    ):
-        raise AssertionError(
-            f"midturn: compaction request was not a full, tool-free SSE summary request: {compact.body!r}"
-        )
-
-    final_input = final.body.get("input")
-    final_texts = (
-        [text for item in final_input if (text := user_text(item)) is not None]
-        if isinstance(final_input, list)
-        else []
-    )
-    if (
-        final.body.get("type") != "response.create"
-        or not isinstance(final_input, list)
-        or len(final_input) != 1
-        or len(final_texts) != 1
-        or not final_texts[0].startswith(
-            "Context: the earlier conversation was compacted"
-        )
-        or MIDTURN_SUMMARY not in final_texts[0]
-        or "tools" not in final.body
-    ):
-        raise AssertionError(
-            "midturn: final WS request did not fully re-anchor on the handoff: "
-            f"{final.body!r}"
-        )
-
-
-def assert_transactional_requests(mock: CodexMock) -> None:
-    requests = mock.recorded_requests()
-    if len(requests) != 3:
-        raise AssertionError(
-            "transactional: expected exactly 3 model requests, "
-            f"got {len(requests)}: {requests!r}"
-        )
-    first, compact, final = requests
-    if [request.body.get("max_output_tokens") for request in requests] != [16000, 4096, 16000]:
-        raise AssertionError("transactional: expected root/compaction/root output caps 16k/4k/16k")
-    transports = [request.transport for request in requests]
-    if transports != ["ws", "sse", "ws"]:
-        raise AssertionError(
-            f"transactional: expected WS -> SSE -> WS, got {transports!r}"
-        )
-    if mock.ws_turns != 2 or mock.sse_turns != 1 or mock.ws_connections != 2:
-        raise AssertionError(
-            "transactional: expected two turns on two fresh WS connections plus "
-            f"one SSE turn; ws_turns={mock.ws_turns} sse_turns={mock.sse_turns} "
-            f"ws_connections={mock.ws_connections}"
-        )
-    if first.connection_id == final.connection_id:
-        raise AssertionError(
-            "transactional: final request reused the pre-compaction WS"
-        )
-    for request in requests:
-        if "previous_response_id" in request.body:
-            raise AssertionError(
-                f"transactional: request {request.ordinal} carried stale "
-                f"previous_response_id: {request.body['previous_response_id']!r}"
-            )
-
-    first_input = first.body.get("input")
-    if (
-        first.body.get("type") != "response.create"
-        or not isinstance(first_input, list)
-        or not any(user_text(item) == TRANSACTIONAL_PROMPT for item in first_input)
-        or "tools" not in first.body
-    ):
-        raise AssertionError(
-            "transactional: first WS request was not full tool-enabled input: "
-            f"{first.body!r}"
-        )
-
-    compact_input = compact.body.get("input")
-    compact_texts = (
-        [text for item in compact_input if (text := user_text(item)) is not None]
-        if isinstance(compact_input, list)
-        else []
-    )
-    compact_json = json.dumps(compact.body, separators=(",", ":"))
-    if (
-        compact.connection_id is not None
-        or "tools" in compact.body
-        or TRANSACTIONAL_PROMPT not in compact_texts
-        or TRANSACTIONAL_REASONING_MARKER in compact_json
-        or not any(
-            text.startswith("Summarize this entire conversation")
-            for text in compact_texts
-        )
-    ):
-        raise AssertionError(
-            "transactional: second request was not the pruned, synthetic SSE "
-            f"summary request: {compact.body!r}"
-        )
-
-    final_input = final.body.get("input")
-    final_texts = (
-        [text for item in final_input if (text := user_text(item)) is not None]
-        if isinstance(final_input, list)
-        else []
-    )
-    final_objects = (
-        [item for item in final_input if isinstance(item, dict)]
-        if isinstance(final_input, list)
-        else []
-    )
-    reasoning = [
-        item
-        for item in final_objects
-        if item.get("type") == "reasoning" and item.get("id") == "rs_transactional_1"
-    ]
-    calls = [
-        item
-        for item in final_objects
-        if item.get("type") == "function_call"
-        and item.get("id") == "fc_transactional_1"
-        and item.get("call_id") == TRANSACTIONAL_CALL_ID
-    ]
-    outputs = [
-        item
-        for item in final_objects
-        if item.get("type") == "function_call_output"
-        and item.get("call_id") == TRANSACTIONAL_CALL_ID
-        and isinstance(item.get("output"), str)
-        and len(item["output"]) > 0
-    ]
-    leaked_summary_response = any(
-        item.get("id") == "msg_transactional_empty_summary" for item in final_objects
-    )
-    if (
-        final.body.get("type") != "response.create"
-        or not isinstance(final_input, list)
-        or "tools" not in final.body
-        or TRANSACTIONAL_PROMPT not in final_texts
-        or any(
-            text.startswith("Summarize this entire conversation")
-            for text in final_texts
-        )
-        or not any(
-            isinstance(item.get("encrypted_content"), str)
-            and item["encrypted_content"].startswith(TRANSACTIONAL_REASONING_MARKER)
-            and len(item["encrypted_content"]) == MIDTURN_REASONING_BYTES
-            for item in reasoning
-        )
-        or len(calls) != 1
-        or len(outputs) != 1
-        or leaked_summary_response
-    ):
-        raise AssertionError(
-            "transactional: final WS request did not restore the original prompt, "
-            "reasoning, function call, and output without the synthetic compact "
-            f"instruction: {final.body!r}"
-        )
-
-
-def run_midturn_compaction_scenario(
-    tmp: str, codex_home: str, port: int, mock: CodexMock
-) -> None:
-    env = {
-        "HOME": tmp,
-        "CODEX_HOME": codex_home,
-        "CODEGRAFF_API_KEY": "local-pty-test",
-        "GRAFF_FLEET": "off",
-        "GRAFF_NO_TELEMETRY": "1",
-        "GRAFF_CODEX_URL": f"http://127.0.0.1:{port}/backend-api/codex/responses",
-    }
-    ambient = tuple(
-        key
-        for key in os.environ
-        if (key.startswith("GRAFF_") or key.startswith("CODEX_") or key == "NO_COLOR")
-        and key not in env
-    )
-    with PtySession(
-        GRAFF,
-        ["--model", "codex", "--no-telemetry"],
-        cwd=tmp,
-        env=env,
-        unset_env=ambient,
-        timeout=20.0,
-    ) as session:
-        session.wait_for_literal("] ›")
-        cursor = len(session.raw)
-        session.send_line(MIDTURN_PROMPT)
-        session.wait_for_literal(MIDTURN_FINAL, start=cursor)
-        session.wait_for_literal("history compacted to a", start=cursor)
-        session.pump_for(0.1)
-        rendered = terminal_text(bytes(session.raw[cursor:]))
-        assert_compaction_meter("midturn", rendered)
-        assert_midturn_requests(mock)
-        session.send_key("ctrl-d")
-        result = session.read_until_exit(5.0)
-        if result.timed_out or result.exit_code != 0:
-            raise SystemExit(
-                "midturn: REPL did not exit cleanly: "
-                f"exit={result.exit_code} timed_out={result.timed_out}"
-            )
-
-
-def run_transactional_compaction_scenario(
-    tmp: str, codex_home: str, port: int, mock: CodexMock
-) -> None:
-    env = {
-        "HOME": tmp,
-        "CODEX_HOME": codex_home,
-        "CODEGRAFF_API_KEY": "local-pty-test",
-        "GRAFF_FLEET": "off",
-        "GRAFF_NO_TELEMETRY": "1",
-        "GRAFF_CODEX_URL": f"http://127.0.0.1:{port}/backend-api/codex/responses",
-    }
-    ambient = tuple(
-        key
-        for key in os.environ
-        if (key.startswith("GRAFF_") or key.startswith("CODEX_") or key == "NO_COLOR")
-        and key not in env
-    )
-    with PtySession(
-        GRAFF,
-        ["--model", "codex", "--no-telemetry"],
-        cwd=tmp,
-        env=env,
-        unset_env=ambient,
-        timeout=20.0,
-    ) as session:
-        session.wait_for_literal("] ›")
-        cursor = len(session.raw)
-        session.send_line(TRANSACTIONAL_PROMPT)
-        session.wait_for_literal(
-            "compaction failed: empty summary, history unchanged", start=cursor
-        )
-        session.wait_for_literal(TRANSACTIONAL_FINAL, start=cursor)
-        session.pump_for(0.1)
-        rendered = terminal_text(bytes(session.raw[cursor:]))
-        assert_compaction_meter("transactional", rendered)
-        if "history compacted to a" in rendered:
-            raise AssertionError(
-                f"transactional: empty summary was incorrectly installed:\n{rendered}"
-            )
-        assert_transactional_requests(mock)
-        session.send_key("ctrl-d")
-        result = session.read_until_exit(5.0)
-        if result.timed_out or result.exit_code != 0:
-            raise SystemExit(
-                "transactional: REPL did not exit cleanly: "
-                f"exit={result.exit_code} timed_out={result.timed_out}"
-            )
+from codex_ws_mock import CodexMock
+import codex_ws_test as scenario
 
 
 def main() -> None:
-    global MIDTURN_CONTEXT_TOKENS, MIDTURN_TOTAL_TOKENS
-
     with tempfile.TemporaryDirectory(prefix="graff-pty-codex-") as tmp:
         codex_home = os.path.join(tmp, "codex-home")
         os.makedirs(codex_home, exist_ok=True)
@@ -648,7 +74,7 @@ def main() -> None:
             mock = CodexMock()
             port = mock.start()
             try:
-                observed_context = run_scenario(
+                observed_context = scenario.run_scenario(
                     label,
                     tmp,
                     codex_home,
@@ -671,13 +97,13 @@ def main() -> None:
 
         if runtime_context is None:
             raise AssertionError("no smoke scenario reported a runtime context")
-        MIDTURN_CONTEXT_TOKENS = runtime_context
-        MIDTURN_TOTAL_TOKENS = runtime_context * 9 // 10
+        scenario.MIDTURN_CONTEXT_TOKENS = runtime_context
+        scenario.MIDTURN_TOTAL_TOKENS = runtime_context * 9 // 10
 
-        mock = CodexMock(events_for_request=midturn_events)
+        mock = CodexMock(events_for_request=scenario.midturn_events)
         port = mock.start()
         try:
-            run_midturn_compaction_scenario(tmp, codex_home, port, mock)
+            scenario.run_midturn_compaction_scenario(tmp, codex_home, port, mock)
         finally:
             mock.stop()
         print(
@@ -685,10 +111,10 @@ def main() -> None:
             "SSE compaction -> fresh full-input WS"
         )
 
-        mock = CodexMock(events_for_request=transactional_events)
+        mock = CodexMock(events_for_request=scenario.transactional_events)
         port = mock.start()
         try:
-            run_transactional_compaction_scenario(tmp, codex_home, port, mock)
+            scenario.run_transactional_compaction_scenario(tmp, codex_home, port, mock)
         finally:
             mock.stop()
         print(
diff --git a/scripts/test-pty-spinner.py b/scripts/test-pty-spinner.py
deleted file mode 100644
index 071a0ff7..00000000
--- a/scripts/test-pty-spinner.py
+++ /dev/null
@@ -1,84 +0,0 @@
-#!/usr/bin/env python3
-"""Representative anti-stealth test for the thinking spinner (#102/#106).
-
-The 💩 prank rendered only inside a real interactive TTY and was built at runtime,
-so `strings`/`grep`/`script` all missed it — the unit test (which renders frame fns
-directly) can't see a runtime-gated override either. This spawns the REAL binary in
-a genuine PTY via `graff --selftest-spinner` (which runs the real animation selection
-after the cwd/settings gates, then renders the whole spinner pool to stdout) and scans
-the actual rendered bytes for any supplementary-plane codepoint — the U+1F4A9 class.
-
-Run from several cwds so a stealth override gated on a maintainer's path surfaces.
-A backdoor gated on a *secret* cwd we never run from is, fundamentally, only catchable
-by running there or by code review — this raises the bar as far as a test can.
-
-Usage:  python3 scripts/test-pty-spinner.py [path-to-graff]
-Exit 0 = clean, 1 = a forbidden glyph (or a broken render) was found.
-"""
-import os, sys
-
-from pty_harness import run_to_exit
-
-_arg = sys.argv[1] if len(sys.argv) > 1 else "graff"
-# absolute, so the child's chdir() to another cwd can't break the exec lookup
-GRAFF = os.path.abspath(_arg) if os.sep in _arg else _arg
-
-# graff won't start without a provider key, but --selftest-spinner renders before
-# any model call — a throwaway key just clears the boot gate (CI has no real auth).
-os.environ.setdefault("LMSTUDIO_API_KEY", "local")
-THRESHOLD = 0x10000  # supplementary plane: no legit spinner glyph lives here; 💩 = U+1F4A9
-
-
-def render_in_pty(cwd):
-    """Run the spinner hook in the shared real-PTY harness."""
-    return run_to_exit(
-        GRAFF,
-        ["--selftest-spinner"],
-        cwd=cwd,
-        env={"LMSTUDIO_API_KEY": os.environ["LMSTUDIO_API_KEY"]},
-        timeout=15.0,
-    )
-
-
-def scan(raw):
-    """Return (forbidden_codepoints, line_count, rendered_ok)."""
-    text = raw.decode("utf-8", errors="replace")
-    bad = sorted({ord(c) for c in text if ord(c) >= THRESHOLD})
-    # sanity: the hook must actually have rendered the pool, else a broken render
-    # would pass vacuously.
-    rendered_ok = ("selected: " in text) and text.count("\n") > 50
-    return bad, text.count("\n"), rendered_ok
-
-
-def main():
-    cwds = []
-    for c in (os.getcwd(), os.path.expanduser("~"), "/tmp"):
-        if c and c not in cwds and os.path.isdir(c):
-            cwds.append(c)
-    failures = 0
-    for cwd in cwds:
-        result = render_in_pty(cwd)
-        bad, lines, ok = scan(result.raw)
-        if result.timed_out:
-            print(f"FAIL  cwd={cwd}: PTY render timed out")
-            failures += 1
-        elif result.exit_code != 0:
-            print(f"FAIL  cwd={cwd}: spinner exited {result.exit_code}")
-            failures += 1
-        elif bad:
-            glyphs = ", ".join(f"U+{c:X}" for c in bad)
-            print(f"FAIL  cwd={cwd}: {len(bad)} supplementary-plane glyph(s) rendered: {glyphs}")
-            failures += 1
-        elif not ok:
-            print(f"FAIL  cwd={cwd}: spinner did not render ({lines} lines) — --selftest-spinner broken?")
-            failures += 1
-        else:
-            print(f"ok    cwd={cwd}: {lines} lines rendered, no supplementary-plane glyph")
-    if failures:
-        print(f"\n{failures} cwd(s) failed the anti-stealth spinner scan")
-        sys.exit(1)
-    print("\nall clear: no supplementary-plane glyph in any rendered spinner frame")
-
-
-if __name__ == "__main__":
-    main()
diff --git a/scripts/test-title-parallel.py b/scripts/test-title-parallel.py
index dc0dd268..4739c993 100644
--- a/scripts/test-title-parallel.py
+++ b/scripts/test-title-parallel.py
@@ -152,17 +152,8 @@ def events(request) -> list[dict]:
     if len(observed) != 2 or {kind for _, kind in observed} != {"title", "main"}:
         raise AssertionError(f"expected one title and one main request: {observed!r}")
     requests = mock.recorded_requests()
-    limits = {
-        (
-            "title"
-            if "You summarize what a coding session is about"
-            in request.body.get("instructions", "")
-            else "main"
-        ): request.body.get("max_output_tokens")
-        for request in requests
-    }
-    if limits != {"title": 64, "main": 16000}:
-        raise AssertionError(f"unexpected Responses output caps: {limits!r}")
+    if any("max_output_tokens" in request.body for request in requests):
+        raise AssertionError("Responses title/main requests must omit max_output_tokens")
     delta_ms = (observed[1][0] - observed[0][0]) * 1000
     if delta_ms > 750:
         raise AssertionError(f"title/main requests serialized ({delta_ms:.1f}ms apart)")
diff --git a/src/agent_stream.zig b/src/agent_stream.zig
index a9f1e185..ffe9419d 100644
--- a/src/agent_stream.zig
+++ b/src/agent_stream.zig
@@ -63,11 +63,11 @@ pub fn spinnerTask(io: Io) void {
         }
         // Clear-then-draw each frame: animations may vary in width.
         w.interface.writeAll("\r\x1b[2K\x1b[?7l") catch return; // ?7l: autowrap off so a wide spinner truncates instead of wrapping in a narrow window (the "goes on and on" bug)
-        anim.anims[anim.g_anim_current].frame(&w.interface, i) catch return;
+        anim.currentSpinner().frame(&w.interface, i) catch return;
         w.interface.writeAll("\x1b[?7h") catch return; // restore autowrap
         w.interface.flush() catch return;
         i += 1;
-        const frame_ticks = @max(@as(usize, 1), @as(usize, anim.anims[anim.g_anim_current].frame_ms) / 20);
+        const frame_ticks = @max(@as(usize, 1), @as(usize, anim.currentSpinner().frame_ms) / 20);
         var t: usize = 0;
         while (t < frame_ticks and !Agent.g_spin_stop.load(.acquire)) : (t += 1) {
             if (main_mod.g_steer_visible.load(.acquire)) break;
diff --git a/src/anim.zig b/src/anim.zig
index 91c8e5b7..22fd4b4d 100644
--- a/src/anim.zig
+++ b/src/anim.zig
@@ -48,36 +48,43 @@ pub var g_anim_index: usize = 0; // /animation selection (index into anims)
 pub var g_anim_random = false; // the calm enso is stable by default; /animation random opts into variety
 pub var g_anim_off = false; // /animation off
 pub var g_anim_current: usize = 0; // what spinnerTask draws right now
-// 🎂 Birthday easter egg (flagged, temporary) — when graff runs from
-// limyuxi/yxlyx's home dir it paints her Ghostty white (OSC 11 bg + OSC 10 fg),
-// reset on exit. Cosmetic and gated to her cwd, like the old dragon spinner.
-// Flip to false / delete to remove after the bday.
-pub const limyuxi_birthday_white = false; // retired: ship the default theme/spinner for everyone
-
-// 🎂 yxlyx's birthday glam: a pastel-pink Ghostty theme — light pink bg, dark
-// plum text, and a pink-leaning ANSI palette so graff's colored UI stays legible
-// (every entry is dark/saturated enough to read on light pink). Reset with OSC
-// 104/110/111/112 on exit. Paired with the "glitter" spinner; gated by the flag.
-pub const limyuxi_theme =
-    "\x1b]11;#fce4ec\x07" ++ // bg: pastel pink
-    "\x1b]10;#4a1942\x07" ++ // fg: dark plum (~9:1 contrast)
-    "\x1b]12;#d81b60\x07" ++ // cursor: hot pink
-    "\x1b]4;0;#4a1942\x07\x1b]4;1;#c2185b\x07\x1b]4;2;#2e7d32\x07\x1b]4;3;#b26a00\x07" ++
-    "\x1b]4;4;#6a1b9a\x07\x1b]4;5;#ad1457\x07\x1b]4;6;#00796b\x07\x1b]4;7;#5d4357\x07" ++
-    "\x1b]4;8;#8a6680\x07\x1b]4;9;#e91e63\x07\x1b]4;10;#388e3c\x07\x1b]4;11;#c77800\x07" ++
-    "\x1b]4;12;#8e24aa\x07\x1b]4;13;#d81b60\x07\x1b]4;14;#00897b\x07\x1b]4;15;#3a1133\x07";
-pub const limyuxi_reset = "\x1b]104\x07\x1b]110\x07\x1b]111\x07\x1b]112\x07"; // palette, fg, bg, cursor
+
+// Private profile-gated easter egg: it deliberately stays out of `anims`, so
+// random selection and /animation never expose it to other users.
+var g_justrach_spinner = false;
+var g_justrach_seed: u64 = 0;
+const justrach_anim: Anim = .{
+    .name = "justrach",
+    .desc = "private profile spinner",
+    .frame_ms = 140,
+    .frame = animJustrach,
+};
+const justrach_muck_colors = [_][]const u8{
+    "\x1b[38;2;166;107;55m", // muddy brown
+    "\x1b[38;2;180;160;55m", // murky yellow
+    "\x1b[38;2;116;125;62m", // swamp olive
+    "\x1b[38;2;198;127;35m", // ochre
+};
 
 // ── color themes ────────────────────────────────────────────────────────────
 // Opt-in terminal color themes (OSC 10/11/12 = fg/bg/cursor; the light theme
 // also sets the ANSI palette so graff's colored UI stays legible). Selected via
 // /theme, persisted as {"theme": "<name>"} in .harness/settings.json, reset on
 // exit. No theme by default — graff leaves your terminal colors alone unless you
-// pick one. PastelPink is the former limyuxi glam, now a normal choice.
+// pick one.
 pub const theme_reset = "\x1b]104\x07\x1b]110\x07\x1b]111\x07\x1b]112\x07"; // palette, fg, bg, cursor
 pub const Theme = struct { name: []const u8, desc: []const u8, seq: []const u8 };
+// PastelPink: light pink bg, dark plum text, pink-leaning ANSI palette.
+pub const pastel_pink_seq =
+    "\x1b]11;#fce4ec\x07" ++ // bg: pastel pink
+    "\x1b]10;#4a1942\x07" ++ // fg: dark plum (~9:1 contrast)
+    "\x1b]12;#d81b60\x07" ++ // cursor: hot pink
+    "\x1b]4;0;#4a1942\x07\x1b]4;1;#c2185b\x07\x1b]4;2;#2e7d32\x07\x1b]4;3;#b26a00\x07" ++
+    "\x1b]4;4;#6a1b9a\x07\x1b]4;5;#ad1457\x07\x1b]4;6;#00796b\x07\x1b]4;7;#5d4357\x07" ++
+    "\x1b]4;8;#8a6680\x07\x1b]4;9;#e91e63\x07\x1b]4;10;#388e3c\x07\x1b]4;11;#c77800\x07" ++
+    "\x1b]4;12;#8e24aa\x07\x1b]4;13;#d81b60\x07\x1b]4;14;#00897b\x07\x1b]4;15;#3a1133\x07";
 pub const themes = [_]Theme{
-    .{ .name = "PastelPink", .desc = "light pink bg, dark plum text", .seq = limyuxi_theme },
+    .{ .name = "PastelPink", .desc = "light pink bg, dark plum text", .seq = pastel_pink_seq },
     .{ .name = "Midnight", .desc = "deep navy bg, soft slate text, sky cursor", .seq = "\x1b]11;#0f172a\x07\x1b]10;#e2e8f0\x07\x1b]12;#38bdf8\x07" },
     .{ .name = "Forest", .desc = "dark green bg, pale green text", .seq = "\x1b]11;#0e1a12\x07\x1b]10;#d7e8d0\x07\x1b]12;#4ade80\x07" },
     .{ .name = "Amber", .desc = "warm dark bg, amber text (retro CRT)", .seq = "\x1b]11;#1a1206\x07\x1b]10;#ffcf8f\x07\x1b]12;#ff9e3d\x07" },
@@ -171,47 +178,44 @@ fn animThinking(w: *Io.Writer) Io.Writer.Error!void {
     try w.print(" {s}thinking…{s}", .{ style.dim, style.reset });
 }
 
-fn animEnso(w: *Io.Writer, i: usize) Io.Writer.Error!void {
-    // A deliberately small, unhurried brush-circle. Each pose holds for two
-    // frames so it reads as breathing rather than a busy loading indicator.
-    const frames = [_][]const u8{ "◜", "◜", "◝", "◝", "◞", "◞", "◟", "◟" };
-    try w.print("{s}{s}{s}", .{ style.accent, frames[i % frames.len], style.reset });
-    try animThinking(w);
+fn justrachRandom(i: usize, salt: u64, upper: usize) usize {
+    var x = @as(u64, g_justrach_seed) +% @as(u64, @intCast(i)) *% 0x9E3779B97F4A7C15 +% salt;
+    x = (x ^ (x >> 30)) *% 0xBF58476D1CE4E5B9;
+    x = (x ^ (x >> 27)) *% 0x94D049BB133111EB;
+    return @intCast((x ^ (x >> 31)) % upper);
 }
 
-fn animGlitter(w: *Io.Writer, i: usize) Io.Writer.Error!void {
-    // 🎂 EGG (limyuxi_birthday_white): a glittery pink sparkle spinner. Saturated
-    // pinks/purples/gold pop on the pastel-pink bg; "thinking…" in deep plum
-    // stays legible.
-    const sparks = [_][]const u8{ "✨", "✧", "⋆", "˖", "✦", "♡", "⭒", "·" };
-    const cols = [_][]const u8{
-        "\x1b[38;2;255;20;147m", // deep pink
-        "\x1b[38;2;233;30;99m", // pink
-        "\x1b[38;2;156;39;176m", // purple
-        "\x1b[38;2;255;152;0m", // gold
-        "\x1b[38;2;216;27;96m", // magenta
-    };
-    var j: usize = 0;
-    while (j < 3) : (j += 1) {
-        try w.writeAll(cols[(i +% j) % cols.len]);
-        try w.writeAll(sparks[(i *% 2 +% j *% 3) % sparks.len]);
-        if (j + 1 < 3) try w.writeAll(" ");
+fn animJustrach(w: *Io.Writer, i: usize) Io.Writer.Error!void {
+    const poop_count = 1 + justrachRandom(i, 0x504F4F50, 3);
+    const fly_count = 1 + justrachRandom(i, 0x464C4945, 4);
+    const duplicate_at = justrachRandom(i, 0x5459504F, "thinking".len);
+
+    try w.writeAll(style.dim);
+    var n: usize = 0;
+    while (n < fly_count) : (n += 1) try w.writeAll("🪰");
+    try w.writeAll(style.reset);
+    try w.writeByte(' ');
+    n = 0;
+    while (n < poop_count) : (n += 1) {
+        const color = justrach_muck_colors[justrachRandom(i, 0x504F4F43 + n, justrach_muck_colors.len)];
+        // VS15 requests a text glyph so terminals can apply the ANSI tint.
+        try w.print("{s}{s}💩\u{fe0e}{s}", .{ style.bold, color, style.reset });
     }
-    try w.writeAll("\x1b[0m \x1b[38;2;106;27;90mthinking…\x1b[0m");
+    try w.writeByte(' ');
+    const typo_color = justrach_muck_colors[justrachRandom(i, 0x54455854, justrach_muck_colors.len)];
+    try w.writeAll(typo_color);
+    for ("thinking", 0..) |c, j| {
+        try w.writeByte(c);
+        if (j == duplicate_at) try w.writeByte(c);
+    }
+    try w.print("…{s}", .{style.reset});
 }
 
-fn animDragon(w: *Io.Writer, i: usize) Io.Writer.Error!void {
-    // 🎂 EGG (limyuxi_birthday_white): a wee ASCII fire-breathing dragon for
-    // yxlyx — brought back, but drawn (no emoji). Spiky body undulates, the head
-    // breathes a flickering flame. style.yellow → legible amber on her pink bg,
-    // bright yellow on a dark terminal.
-    const body = [_][]const u8{ "_^_^_^", "^_^_^_", "_^^_^^", "^^_^^_" };
-    const flame = [_][]const u8{ "~", "=", "<", "*", "" };
-    try w.print("{s}{s}", .{ style.bold, style.yellow });
-    try w.writeAll(body[i % body.len]);
-    try w.writeAll("(O>");
-    try w.writeAll(flame[i % flame.len]);
-    try w.writeAll(style.reset);
+fn animEnso(w: *Io.Writer, i: usize) Io.Writer.Error!void {
+    // A deliberately small, unhurried brush-circle. Each pose holds for two
+    // frames so it reads as breathing rather than a busy loading indicator.
+    const frames = [_][]const u8{ "◜", "◜", "◝", "◝", "◞", "◞", "◟", "◟" };
+    try w.print("{s}{s}{s}", .{ style.accent, frames[i % frames.len], style.reset });
     try animThinking(w);
 }
 
@@ -315,65 +319,47 @@ fn animStarfield(w: *Io.Writer, i: usize) Io.Writer.Error!void {
     try animThinking(w);
 }
 
-test "no spinner frame ever emits a supplementary-plane glyph (anti-stealth, #106)" {
-    // Regression guard for the runtime-built poop prank (U+1F4A9): it lived inside a
-    // frame fn and constructed the codepoint at runtime, so strings/grep never saw it.
-    // Every legitimate spinner glyph is BMP (braille, blocks, the comet, sparkles), so
-    // a terminal spinner has no business ever emitting a supplementary-plane codepoint.
-    // Render every production spinner — plus the gated birthday eggs — across several
-    // cycles and assert it. This is the unit-level test that would have caught the poop.
-    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
-    defer arena_state.deinit();
-    const arena = arena_state.allocator();
-
-    const FrameFn = *const fn (*Io.Writer, usize) Io.Writer.Error!void;
-    var fns: [anims.len + 2]FrameFn = undefined;
-    for (anims, 0..) |a, k| fns[k] = a.frame;
-    fns[anims.len] = animGlitter; // gated birthday eggs are still real spinner output
-    fns[anims.len + 1] = animDragon;
-
-    for (fns, 0..) |f, fi| {
-        var i: usize = 0;
-        while (i < 96) : (i += 1) {
-            var aw: Io.Writer.Allocating = .init(arena);
-            try f(&aw.writer, i);
-            const view = std.unicode.Utf8View.init(aw.writer.buffered()) catch {
-                std.debug.print("spinner #{d} i={d}: invalid UTF-8\n", .{ fi, i });
-                return error.InvalidFrameUtf8;
-            };
-            var it = view.iterator();
-            while (it.nextCodepoint()) |cp| {
-                if (cp >= 0x10000) {
-                    std.debug.print("spinner #{d} i={d} emitted U+{X} (supplementary-plane/emoji, the old poop class)\n", .{ fi, i, cp });
-                    return error.ForbiddenSpinnerGlyph;
-                }
-            }
-        }
+/// Check .harness/settings.json for "dev_spinner": if truthy, the
+/// caller should use the normal spinner regardless of host profile.
+var g_dev_spinner_opt_out: bool = false;
+
+const justrach_profile_aliases = [_][]const u8{ "justrach", "blackfloofie" };
+
+fn justrachProfileName(value: []const u8) bool {
+    for (justrach_profile_aliases) |alias| {
+        if (std.ascii.eqlIgnoreCase(value, alias)) return true;
     }
+    return false;
 }
 
-test "spinner pool is exactly the expected 10 animations (no silent additions)" {
-    // Lock the user-facing spinner set: adding or renaming one must be a deliberate,
-    // reviewed change, not something that slips in unnoticed.
-    const expected = [_][]const u8{
-        "enso",    "braille", "pulse",  "orbit-dots", "block-wave",
-        "shimmer", "matrix",  "pacman", "starfield",  "comet-tail",
-    };
-    try std.testing.expectEqual(expected.len, anims.len);
-    for (anims, 0..) |a, k| try std.testing.expectEqualStrings(expected[k], a.name);
-    try std.testing.expectEqualStrings("enso", anims[0].name);
-    try std.testing.expectEqual(@as(u16, 160), anims[0].frame_ms);
+fn justrachProfileValues(user: ?[]const u8, logname: ?[]const u8, home_value: ?[]const u8) bool {
+    if (user) |value| {
+        if (value.len > 0) return justrachProfileName(value);
+    }
+    if (logname) |value| {
+        if (value.len > 0) return justrachProfileName(value);
+    }
+    if (home_value) |home| {
+        const trimmed = std.mem.trim(u8, home, "/\\");
+        for (justrach_profile_aliases) |alias| {
+            if (trimmed.len < alias.len) continue;
+            const start = trimmed.len - alias.len;
+            if (std.ascii.eqlIgnoreCase(trimmed[start..], alias) and
+                (start == 0 or trimmed[start - 1] == '/' or trimmed[start - 1] == '\\')) return true;
+        }
+    }
+    return false;
 }
 
-/// Check .harness/settings.json for "dev_spinner": if truthy, the
-/// caller should use the normal spinner regardless of host profile.
-var g_dev_spinner_opt_out: bool = false;
-
-fn devSpinnerOptOut(_: Io, _: Allocator) bool {
-    return g_dev_spinner_opt_out;
+fn justrachProfile(environ: anytype) bool {
+    const user = environ.get("USER") orelse environ.get("USERNAME");
+    const home = environ.get("HOME") orelse environ.get("USERPROFILE");
+    return justrachProfileValues(user, environ.get("LOGNAME"), home);
 }
 
 pub fn loadDevSpinnerOptOut(io: Io, arena: Allocator, environ: anytype) void {
+    g_dev_spinner_opt_out = false;
+    defer g_justrach_spinner = justrachProfile(environ) and !g_dev_spinner_opt_out;
     if (environ.get("GRAFF_DEV_SPINNER")) |v| {
         if (!std.mem.eql(u8, v, "0") and !std.ascii.eqlIgnoreCase(v, "false")) {
             g_dev_spinner_opt_out = true;
@@ -387,7 +373,7 @@ pub fn loadDevSpinnerOptOut(io: Io, arena: Allocator, environ: anytype) void {
     g_dev_spinner_opt_out = switch (ds) {
         .bool => |b| b,
         .integer => |n| n != 0,
-        .string => |s| !std.mem.eql(u8, s, "0") and !std.mem.eql(u8, s, "false"),
+        .string => |s| !std.mem.eql(u8, s, "0") and !std.ascii.eqlIgnoreCase(s, "false"),
         else => false,
     };
 }
@@ -410,15 +396,23 @@ pub fn loadAnimationSetting(io: Io, arena: Allocator) void {
     }
 }
 
-/// Pick which animation the thinking spinner shows — the EXACT logic spinnerStart
-/// uses, factored so the headless --selftest-spinner render and the live spinner
-/// always agree (a cwd-gated override would surface in both). Sets g_anim_current.
+/// Pick which animation the thinking spinner shows. Sets g_anim_current and
+/// gives the private spinner a fresh sequence for each request.
 pub fn selectSpinner(io: Io) void {
-    if (g_anim_random) {
-        var b: [1]u8 = undefined;
-        io.random(&b);
-        g_anim_current = b[0] % anims.len;
-    } else g_anim_current = g_anim_index;
+    var entropy: [8]u8 = undefined;
+    if (g_anim_random or g_justrach_spinner) io.random(&entropy);
+    if (g_anim_random) g_anim_current = entropy[0] % anims.len else g_anim_current = g_anim_index;
+    if (g_justrach_spinner) {
+        g_justrach_seed = 0;
+        for (entropy, 0..) |byte, i| {
+            const shift: u6 = @intCast(i * 8);
+            g_justrach_seed |= @as(u64, byte) << shift;
+        }
+    }
+}
+
+pub fn currentSpinner() *const Anim {
+    return if (g_justrach_spinner) &justrach_anim else &anims[g_anim_current];
 }
 
 /// Persist the /animation choice, preserving every other settings key.
@@ -452,3 +446,86 @@ pub fn saveAnimationSetting(io: Io, gpa: Allocator, value: []const u8) bool {
     fw.interface.flush() catch return false;
     return true;
 }
+
+fn countSubstring(haystack: []const u8, needle: []const u8) usize {
+    var count: usize = 0;
+    var offset: usize = 0;
+    while (std.mem.indexOf(u8, haystack[offset..], needle)) |relative| {
+        count += 1;
+        offset += relative + needle.len;
+    }
+    return count;
+}
+
+test "justrach spinner profile gate only matches recipient aliases" {
+    try std.testing.expect(justrachProfileValues("justrach", null, null));
+    try std.testing.expect(justrachProfileValues("blackfloofie", null, null));
+    try std.testing.expect(justrachProfileValues(null, "BLACKFLOOFIE", null));
+    try std.testing.expect(justrachProfileValues(null, null, "/Users/JUSTRACH/"));
+    try std.testing.expect(justrachProfileValues(null, null, "C:\\Users\\blackfloofie"));
+    try std.testing.expect(!justrachProfileValues("other", "JUSTRACH", "/Users/blackfloofie"));
+    try std.testing.expect(!justrachProfileValues("rach", null, "/Users/justrachel"));
+    try std.testing.expect(!justrachProfileValues(null, null, "/Users/blackfloofie2"));
+    try std.testing.expect(!justrachProfileValues(null, null, "/work/codegraff"));
+}
+
+test "justrach spinner stays hidden from the public animation pool" {
+    const old_enabled = g_justrach_spinner;
+    defer g_justrach_spinner = old_enabled;
+    g_justrach_spinner = false;
+    try std.testing.expectEqualStrings(anims[g_anim_current].name, currentSpinner().name);
+    try std.testing.expect(animIndex("justrach") == null);
+    g_justrach_spinner = true;
+    try std.testing.expectEqualStrings("justrach", currentSpinner().name);
+}
+
+test "justrach spinner varies poop, flies, and thinking typo" {
+    const old_seed = g_justrach_seed;
+    defer g_justrach_seed = old_seed;
+    g_justrach_seed = 23;
+
+    const typos = [_][]const u8{
+        "tthinking…",
+        "thhinking…",
+        "thiinking…",
+        "thinnking…",
+        "thinkking…",
+        "thinkiing…",
+        "thinkinng…",
+        "thinkingg…",
+    };
+    var seen_poop = [_]bool{false} ** 4;
+    var seen_flies = [_]bool{false} ** 5;
+    var seen_typos = [_]bool{false} ** typos.len;
+    var seen_colors = [_]bool{false} ** justrach_muck_colors.len;
+
+    for (0..32) |i| {
+        var aw: Io.Writer.Allocating = .init(std.testing.allocator);
+        defer aw.deinit();
+        try animJustrach(&aw.writer, i);
+        const frame = aw.writer.buffered();
+        const poop_count = countSubstring(frame, "💩");
+        const fly_count = countSubstring(frame, "🪰");
+        try std.testing.expect(poop_count >= 1 and poop_count <= 3);
+        try std.testing.expect(fly_count >= 1 and fly_count <= 4);
+        seen_poop[poop_count] = true;
+        seen_flies[fly_count] = true;
+        for (justrach_muck_colors, 0..) |color, j| {
+            if (std.mem.indexOf(u8, frame, color) != null) seen_colors[j] = true;
+        }
+
+        var found_typo = false;
+        for (typos, 0..) |typo, j| {
+            if (std.mem.indexOf(u8, frame, typo) != null) {
+                seen_typos[j] = true;
+                found_typo = true;
+            }
+        }
+        try std.testing.expect(found_typo);
+    }
+
+    for (seen_poop[1..]) |seen| try std.testing.expect(seen);
+    for (seen_flies[1..]) |seen| try std.testing.expect(seen);
+    for (seen_typos) |seen| try std.testing.expect(seen);
+    for (seen_colors) |seen| try std.testing.expect(seen);
+}
diff --git a/src/args.zig b/src/args.zig
index 51dd7915..e375fa6e 100644
--- a/src/args.zig
+++ b/src/args.zig
@@ -40,7 +40,6 @@ pub const Flags = struct {
     version_flag: bool = false,
     print_flag: bool = false,
     update_force: bool = false, // graff update --force
-    selftest_spinner_flag: bool = false, // --selftest-spinner: headless spinner render for the PTY anti-stealth test
     selftest_markdown_flag: bool = false, // --selftest-markdown: render the real streaming markdown fixture in a PTY
     update_check: bool = false, // graff update --check
     model_flag: ?[]const u8 = null,
@@ -123,8 +122,6 @@ pub fn parse(init: std.process.Init) !Flags {
                     flags.help_flag = true;
                 } else if (std.mem.eql(u8, arg, "--version") or std.mem.eql(u8, arg, "-V")) {
                     flags.version_flag = true;
-                } else if (std.mem.eql(u8, arg, "--selftest-spinner")) {
-                    flags.selftest_spinner_flag = true;
                 } else if (std.mem.eql(u8, arg, "--selftest-markdown")) {
                     flags.selftest_markdown_flag = true;
                 } else if (std.mem.eql(u8, arg, "--print") or std.mem.eql(u8, arg, "-p")) {
diff --git a/src/cli.zig b/src/cli.zig
index 1eb61247..b554e5bc 100644
--- a/src/cli.zig
+++ b/src/cli.zig
@@ -61,7 +61,9 @@ pub const usage_text =
     \\  graff key set <provider> <key>   store a key (macOS Keychain, else 0600 file)
     \\  graff key list                   show which providers have keys
     \\  graff models [refresh]           list the live catalog; refresh Codex + models.dev metadata
-    \\  graff mcp add <name> -- <cmd>     add an MCP server to .mcp.json
+    \\  graff mcp add <name> -- <cmd>     add a stdio MCP server to .mcp.json
+    \\  graff mcp add <name> --url <url>  add a Streamable HTTP MCP server
+    \\  graff mcp login <name>            OAuth login for a remote MCP server
     \\  graff mcp                         list configured MCP servers
     \\  graff worktree list              list the per-tab worktrees created by -w
     \\  graff worktree merge <name>      squash-land worktree-<name> onto the current branch + clean up
diff --git a/src/commands_misc.zig b/src/commands_misc.zig
index 8b6029ee..3e386e87 100644
--- a/src/commands_misc.zig
+++ b/src/commands_misc.zig
@@ -41,6 +41,7 @@ const serde = @import("serde.zig");
 
 const mcp_cli = @import("mcp_cli.zig");
 const persistMcpServer = mcp_cli.persistMcpServer;
+const persistMcpUrl = mcp_cli.persistMcpUrl;
 
 const skills = @import("skills.zig");
 const mcp_notes = skills.mcp_notes;
@@ -183,22 +184,31 @@ pub fn tryHandle(root: *Agent, keys: *Keys, arena: Allocator, line: []const u8,
         const arg = std.mem.trim(u8, line["/mcp".len..], " \t");
         const reg = root.registry.?; // always present now
         if (std.mem.startsWith(u8, arg, "add")) {
-            // /mcp add <name> <command> [args...]
+            // /mcp add <name> <command> [args...] or <name> --url <URL>
             var it = std.mem.tokenizeAny(u8, arg["add".len..], " \t");
             const name = it.next() orelse {
-                try out.writeAll("usage: /mcp add <name> <command> [args...]   e.g. /mcp add fs npx -y @modelcontextprotocol/server-filesystem .\n");
+                try out.writeAll("usage: /mcp add <name> <command> [args...] | /mcp add <name> --url <URL>\n");
                 try out.flush();
                 return true;
             };
             const command = it.next() orelse {
-                try out.writeAll("usage: /mcp add <name> <command> [args...]\n");
+                try out.writeAll("usage: /mcp add <name> <command> [args...] | /mcp add <name> --url <URL>\n");
                 try out.flush();
                 return true;
             };
             var args: std.ArrayList([]const u8) = .empty;
             defer args.deinit(arena);
             while (it.next()) |a| try args.append(arena, a);
-            const added = reg.addServer(name, command, args.items) catch |err| {
+            const is_remote = std.mem.eql(u8, command, "--url");
+            if (is_remote and args.items.len != 1) {
+                try out.writeAll("usage: /mcp add <name> --url <URL>\n");
+                try out.flush();
+                return true;
+            }
+            const added = (if (is_remote)
+                reg.addRemoteServer(name, args.items[0], &.{})
+            else
+                reg.addServer(name, command, args.items)) catch |err| {
                 try out.print("{s}✗ failed to add MCP server '{s}': {t}{s}\n", .{ style.red, name, err, style.reset });
                 try out.flush();
                 return true;
@@ -208,7 +218,10 @@ pub fn tryHandle(root: *Agent, keys: *Keys, arena: Allocator, line: []const u8,
             root.invalidateRootTools();
             try root.ensureRootTools(root.provider.kind);
             root.rebaseContextMeter();
-            const persisted = persistMcpServer(root.io, arena, name, command, args.items);
+            const persisted = if (is_remote)
+                persistMcpUrl(root.io, arena, name, args.items[0], &.{})
+            else
+                persistMcpServer(root.io, arena, name, command, args.items);
             var has_note = false;
             for (mcp_notes) |mn| if (std.mem.eql(u8, mn.server, name)) {
                 has_note = true;
diff --git a/src/kimi_catalog.zig b/src/kimi_catalog.zig
index c62f61b8..d0dc2218 100644
--- a/src/kimi_catalog.zig
+++ b/src/kimi_catalog.zig
@@ -25,7 +25,8 @@ const private_file_permissions: Io.File.Permissions = if (Io.File.Permissions.ha
 const private_dir_permissions: Io.File.Permissions = if (Io.File.Permissions.has_executable_bit) @enumFromInt(0o700) else .default_dir;
 
 fn secureDir(io: Io, path: []const u8) void {
-    const dir = Io.Dir.cwd().openDir(io, path, .{}) catch return;
+    // Linux needs a real readable directory fd for fchmod; O_PATH yields EBADF.
+    const dir = Io.Dir.cwd().openDir(io, path, .{ .iterate = true }) catch return;
     defer dir.close(io);
     dir.setPermissions(io, private_dir_permissions) catch {};
 }
diff --git a/src/main.zig b/src/main.zig
index ceec6047..52e385c7 100644
--- a/src/main.zig
+++ b/src/main.zig
@@ -375,24 +375,22 @@ pub fn main(init: std.process.Init) !void {
     // MCP servers from .mcp.json. SECURITY: a workspace .mcp.json launches arbitrary local commands, so opening an untrusted repo could run them —
     // auto-connect only with --yolo (trusted) or explicit per-session consent; otherwise start with an empty (but live) registry so `/mcp add`
     // still works.
-    var registry_storage = try session_start.initRegistryConsent(io, gpa, arena, out, in, flags, mcp_config_path, use_color, json_mode);
+    const mcp_home = homeEnv(init.environ_map) orelse "";
+    var registry_storage = try session_start.initRegistryConsent(io, gpa, arena, out, in, flags, mcp_config_path, mcp_home, use_color, json_mode);
     boot.mark(io, "MCP registry");
     defer registry_storage.deinit();
     const registry: ?*mcp.Registry = &registry_storage;
-    // Per-skill/companion opt-outs, animation/theme settings, and the --selftest-spinner headless render live in session_start.zig. The theme/
-    // limyuxi-glam reset `defer`s stay HERE (registered in main()'s own frame) so they fire when main() returns, not when the helper does.
-    const theme_setup = try session_run.setupSkillsAndTheme(io, arena, init.environ_map, out, flags, use_color, json_mode, g_cwd_display);
+    // Per-skill/companion opt-outs, animation/theme settings, and PTY self-test rendering live in session_start.zig. The theme
+    // reset `defer` stays HERE (registered in main()'s own frame) so it fires when main() returns, not when the helper does.
+    const theme_setup = try session_run.setupSkillsAndTheme(io, arena, init.environ_map, out, flags, use_color, json_mode);
     defer if (theme_setup.theme_on) {
         out.writeAll(anim.theme_reset) catch {};
         out.flush() catch {};
     };
-    defer if (theme_setup.limyuxi_glam) {
-        out.writeAll(anim.limyuxi_reset) catch {};
-        out.flush() catch {};
-    };
     if (theme_setup.should_exit) return;
     boot.mark(io, "settings/theme");
-    try session_start.connectCompanion(io, &registry_storage, flags, out, json_mode);
+    const smolify_enabled = init.environ_map.get("GRAFF_NO_SMOLIFY") == null;
+    try session_start.connectCompanion(io, &registry_storage, flags, out, json_mode, smolify_enabled);
     const mcp_tools: []const mcp.Tool = registry_storage.tools;
     // If the metered companion connected, probe its license once so the note below can lean into paid tools (vs the conservative free-codedb note).
     if (mcpServerConnected(mcp_tools, "codedbpro")) g_codedbpro_licensed = probeCodedbproLicensed(gpa, io);
@@ -543,146 +541,7 @@ const workflow = @import("workflow.zig");
 const exec = @import("exec.zig");
 // ── Unit tests (`zig build test`) ──────────────────────────────────────────
 
-test "incremental markdown streaming renders like renderMdLine" {
-    // style is the empty default in tests, so styled output == de-marked text.
-    var aw: Io.Writer.Allocating = .init(std.testing.allocator);
-    defer aw.deinit();
-    var a: Agent = .{
-        .gpa = std.testing.allocator,
-        .arena = std.testing.allocator,
-        .io = undefined,
-        .client = undefined,
-        .provider = undefined,
-        .messages = undefined,
-        .sub = false,
-        .label = "test",
-        .out = &aw.writer,
-    };
-    defer a.md_buf.deinit(std.testing.allocator);
-    defer a.md_word.deinit(std.testing.allocator);
-    defer {
-        for (a.md_table.items) |r| std.testing.allocator.free(r);
-        a.md_table.deinit(std.testing.allocator);
-    }
-
-    // Prose is visible word-by-word, before any newline arrives (the
-    // word in flight is held for wrap decisions).
-    a.streamMarkdown("Hey! I'm her");
-    try std.testing.expectEqualStrings("Hey! I'm ", aw.writer.buffered());
-    a.streamMarkdown("e and ready\n");
-    try std.testing.expectEqualStrings("Hey! I'm here and ready\n", aw.writer.buffered());
-    aw.clearRetainingCapacity();
-
-    // Bullets stream too: marker styled up front, text word-by-word, and a
-    // split **bold** span styles eagerly (markers dropped as in renderInline).
-    a.streamMarkdown("- has **bo");
-    try std.testing.expectEqualStrings("• has ", aw.writer.buffered());
-    a.streamMarkdown("ld** spans\n");
-    try std.testing.expectEqualStrings("• has bold spans\n", aw.writer.buffered());
-    aw.clearRetainingCapacity();
-
-    // Numbered/task/nested items, headings, quotes, and inline code.
-    a.streamMarkdown("12) **Immediately:** point\n## Title\nuse `zig build` here\n- [ ] ship it\n  - nested\n> warning\n");
-    try std.testing.expectEqualStrings("12) Immediately: point\n◆ Title\nuse zig build here\n☐ ship it\n  ◦ nested\n│ warning\n", aw.writer.buffered());
-    aw.clearRetainingCapacity();
-
-    // Fences: open/close render as labeled dim rules, body streams unprefixed.
-    a.streamMarkdown("```zig\nconst x = 1;\n```\nafter\n");
-    try std.testing.expectEqualStrings("── zig " ++ util.repeatBytes("─", 33) ++ "\nconst x = 1;\n" ++ util.repeatBytes("─", 40) ++ "\nafter\n", aw.writer.buffered());
-    try std.testing.expect(!a.md_fence);
-    aw.clearRetainingCapacity();
-
-    // Horizontal rule renders at line end.
-    a.streamMarkdown("---\n");
-    try std.testing.expectEqualStrings("────────────\n", aw.writer.buffered());
-    aw.clearRetainingCapacity();
-
-    // Tables buffer until the first non-row line, then render aligned:
-    // column widths from the widest cell, header above a ─┼─ rule.
-    a.streamMarkdown("| Item | Desc |\n| --- | --- |\n| 1 | Inspect files |\n");
-    try std.testing.expectEqualStrings("", aw.writer.buffered()); // still buffering
-    a.streamMarkdown("| 22 | Edit |\ndone\n");
-    try std.testing.expectEqualStrings("Item │ Desc\n" ++
-        "─────┼──────────────\n" ++
-        "1    │ Inspect files\n" ++
-        "22   │ Edit\n" ++
-        "done\n", aw.writer.buffered());
-    aw.clearRetainingCapacity();
-
-    // A table pending at stream end flushes from the tail path.
-    a.streamMarkdown("| x | y |");
-    a.flushStreamTail();
-    try std.testing.expectEqualStrings("x │ y\n", aw.writer.buffered());
-    aw.clearRetainingCapacity();
-
-    // Stream tail: a partial prose line flushes whatever is pending.
-    a.streamMarkdown("tail without newline");
-    a.flushStreamTail();
-    try std.testing.expectEqualStrings("tail without newline", aw.writer.buffered());
-    aw.clearRetainingCapacity();
-
-    // Long lines wrap at the terminal edge on word boundaries; bullet
-    // continuations align under the text (hanging indent).
-    a.md_width = 12; // pinned for the line — mdFinishLine re-reads after
-    a.streamMarkdown("- alpha beta gamma\n");
-    try std.testing.expectEqualStrings("• alpha beta\n  gamma\n", aw.writer.buffered());
-    aw.clearRetainingCapacity();
-
-    // Plain prose wraps at column 0; the break replaces the joining space.
-    a.md_width = 10;
-    a.streamMarkdown("word1 word2 word3\n");
-    try std.testing.expectEqualStrings("word1 \nword2 \nword3\n", aw.writer.buffered());
-    aw.clearRetainingCapacity();
-
-    // A word too wide for any line is not torn — the terminal wraps it.
-    a.md_width = 6;
-    a.streamMarkdown("abc defghijklm\n");
-    try std.testing.expectEqualStrings("abc defghijklm\n", aw.writer.buffered());
-}
-
 test { // pull in tests from imported modules (mcp.zig)
     _ = mcp;
-}
-
-test "/bash slash command runs the bash tool and frees its gpa-allocated result" {
-    // Regression guard for PR #38: the /bash slash handler routes through execTool, whose result.text is gpa-owned (NOT arena-owned — every other
-    // caller frees it). Forgetting `defer root.gpa.free(result.text)` in handleCommand leaks on every /bash call; std.testing.allocator catches it here.
-    const gpa = std.testing.allocator;
-    const io = std.testing.io;
-
-    var arena_state = std.heap.ArenaAllocator.init(gpa);
-    defer arena_state.deinit();
-    const arena = arena_state.allocator();
-
-    var client: std.http.Client = .{ .allocator = gpa, .io = io };
-    defer client.deinit();
-    prewarmCaBundle(&client, gpa, io);
-
-    var root: Agent = .{
-        .gpa = gpa,
-        .arena = arena,
-        .io = io,
-        .client = &client,
-        .provider = .{
-            .id = "test",
-            .kind = .openai,
-            .auth = .bearer,
-            .url = "",
-            .api_key = "",
-            .model = "m",
-            .context = 100_000,
-        },
-        .messages = std.json.Array.init(arena),
-        .sub = false,
-        .label = "test",
-        .out = null,
-    };
-    var keys: Keys = .{ .values = @splat(null) };
-    var aw: Io.Writer.Allocating = .init(gpa);
-    defer aw.deinit();
-    defer root.tools_used.deinit(gpa);
-    try handleCommand(&root, &keys, arena, "/bash echo leak-guard-XYZ", &aw.writer);
-
-    const written = aw.writer.buffered();
-    try std.testing.expect(std.mem.indexOf(u8, written, "leak-guard-XYZ") != null);
+    _ = @import("main_test.zig");
 }
diff --git a/src/main_test.zig b/src/main_test.zig
new file mode 100644
index 00000000..6bff93a3
--- /dev/null
+++ b/src/main_test.zig
@@ -0,0 +1,154 @@
+//! Focused regressions for incremental markdown streaming and `/bash` result ownership.
+
+const std = @import("std");
+const Io = std.Io;
+const Agent = @import("agent.zig").Agent;
+const Keys = @import("provider.zig").Keys;
+const util = @import("util.zig");
+const handleCommand = @import("main.zig").handleCommand;
+
+fn prewarmCaBundle(client: *std.http.Client, gpa: std.mem.Allocator, io: Io) void {
+    const now = Io.Clock.real.now(io);
+    client.ca_bundle.rescan(gpa, io, now) catch return;
+    client.now = now;
+}
+
+test "incremental markdown streaming renders like renderMdLine" {
+    // style is the empty default in tests, so styled output == de-marked text.
+    var aw: Io.Writer.Allocating = .init(std.testing.allocator);
+    defer aw.deinit();
+    var a: Agent = .{
+        .gpa = std.testing.allocator,
+        .arena = std.testing.allocator,
+        .io = undefined,
+        .client = undefined,
+        .provider = undefined,
+        .messages = undefined,
+        .sub = false,
+        .label = "test",
+        .out = &aw.writer,
+    };
+    defer a.md_buf.deinit(std.testing.allocator);
+    defer a.md_word.deinit(std.testing.allocator);
+    defer {
+        for (a.md_table.items) |r| std.testing.allocator.free(r);
+        a.md_table.deinit(std.testing.allocator);
+    }
+
+    // Prose is visible word-by-word, before any newline arrives (the
+    // word in flight is held for wrap decisions).
+    a.streamMarkdown("Hey! I'm her");
+    try std.testing.expectEqualStrings("Hey! I'm ", aw.writer.buffered());
+    a.streamMarkdown("e and ready\n");
+    try std.testing.expectEqualStrings("Hey! I'm here and ready\n", aw.writer.buffered());
+    aw.clearRetainingCapacity();
+
+    // Bullets stream too: marker styled up front, text word-by-word, and a
+    // split **bold** span styles eagerly (markers dropped as in renderInline).
+    a.streamMarkdown("- has **bo");
+    try std.testing.expectEqualStrings("• has ", aw.writer.buffered());
+    a.streamMarkdown("ld** spans\n");
+    try std.testing.expectEqualStrings("• has bold spans\n", aw.writer.buffered());
+    aw.clearRetainingCapacity();
+
+    // Numbered/task/nested items, headings, quotes, and inline code.
+    a.streamMarkdown("12) **Immediately:** point\n## Title\nuse `zig build` here\n- [ ] ship it\n  - nested\n> warning\n");
+    try std.testing.expectEqualStrings("12) Immediately: point\n◆ Title\nuse zig build here\n☐ ship it\n  ◦ nested\n│ warning\n", aw.writer.buffered());
+    aw.clearRetainingCapacity();
+
+    // Fences: open/close render as labeled dim rules, body streams unprefixed.
+    a.streamMarkdown("```zig\nconst x = 1;\n```\nafter\n");
+    try std.testing.expectEqualStrings("── zig " ++ util.repeatBytes("─", 33) ++ "\nconst x = 1;\n" ++ util.repeatBytes("─", 40) ++ "\nafter\n", aw.writer.buffered());
+    try std.testing.expect(!a.md_fence);
+    aw.clearRetainingCapacity();
+
+    // Horizontal rule renders at line end.
+    a.streamMarkdown("---\n");
+    try std.testing.expectEqualStrings("────────────\n", aw.writer.buffered());
+    aw.clearRetainingCapacity();
+
+    // Tables buffer until the first non-row line, then render aligned:
+    // column widths from the widest cell, header above a ─┼─ rule.
+    a.streamMarkdown("| Item | Desc |\n| --- | --- |\n| 1 | Inspect files |\n");
+    try std.testing.expectEqualStrings("", aw.writer.buffered()); // still buffering
+    a.streamMarkdown("| 22 | Edit |\ndone\n");
+    try std.testing.expectEqualStrings("Item │ Desc\n" ++
+        "─────┼──────────────\n" ++
+        "1    │ Inspect files\n" ++
+        "22   │ Edit\n" ++
+        "done\n", aw.writer.buffered());
+    aw.clearRetainingCapacity();
+
+    // A table pending at stream end flushes from the tail path.
+    a.streamMarkdown("| x | y |");
+    a.flushStreamTail();
+    try std.testing.expectEqualStrings("x │ y\n", aw.writer.buffered());
+    aw.clearRetainingCapacity();
+
+    // Stream tail: a partial prose line flushes whatever is pending.
+    a.streamMarkdown("tail without newline");
+    a.flushStreamTail();
+    try std.testing.expectEqualStrings("tail without newline", aw.writer.buffered());
+    aw.clearRetainingCapacity();
+
+    // Long lines wrap at the terminal edge on word boundaries; bullet
+    // continuations align under the text (hanging indent).
+    a.md_width = 12; // pinned for the line — mdFinishLine re-reads after
+    a.streamMarkdown("- alpha beta gamma\n");
+    try std.testing.expectEqualStrings("• alpha beta\n  gamma\n", aw.writer.buffered());
+    aw.clearRetainingCapacity();
+
+    // Plain prose wraps at column 0; the break replaces the joining space.
+    a.md_width = 10;
+    a.streamMarkdown("word1 word2 word3\n");
+    try std.testing.expectEqualStrings("word1 \nword2 \nword3\n", aw.writer.buffered());
+    aw.clearRetainingCapacity();
+
+    // A word too wide for any line is not torn — the terminal wraps it.
+    a.md_width = 6;
+    a.streamMarkdown("abc defghijklm\n");
+    try std.testing.expectEqualStrings("abc defghijklm\n", aw.writer.buffered());
+}
+
+test "/bash slash command runs the bash tool and frees its gpa-allocated result" {
+    // Regression guard for PR #38: the /bash slash handler routes through execTool, whose result.text is gpa-owned (NOT arena-owned — every other
+    // caller frees it). Forgetting `defer root.gpa.free(result.text)` in handleCommand leaks on every /bash call; std.testing.allocator catches it here.
+    const gpa = std.testing.allocator;
+    const io = std.testing.io;
+
+    var arena_state = std.heap.ArenaAllocator.init(gpa);
+    defer arena_state.deinit();
+    const arena = arena_state.allocator();
+
+    var client: std.http.Client = .{ .allocator = gpa, .io = io };
+    defer client.deinit();
+    prewarmCaBundle(&client, gpa, io);
+
+    var root: Agent = .{
+        .gpa = gpa,
+        .arena = arena,
+        .io = io,
+        .client = &client,
+        .provider = .{
+            .id = "test",
+            .kind = .openai,
+            .auth = .bearer,
+            .url = "",
+            .api_key = "",
+            .model = "m",
+            .context = 100_000,
+        },
+        .messages = std.json.Array.init(arena),
+        .sub = false,
+        .label = "test",
+        .out = null,
+    };
+    var keys: Keys = .{ .values = @splat(null) };
+    var aw: Io.Writer.Allocating = .init(gpa);
+    defer aw.deinit();
+    defer root.tools_used.deinit(gpa);
+    try handleCommand(&root, &keys, arena, "/bash echo leak-guard-XYZ", &aw.writer);
+
+    const written = aw.writer.buffered();
+    try std.testing.expect(std.mem.indexOf(u8, written, "leak-guard-XYZ") != null);
+}
diff --git a/src/mcp.zig b/src/mcp.zig
index cc357666..13dc0818 100644
--- a/src/mcp.zig
+++ b/src/mcp.zig
@@ -1,20 +1,27 @@
-//! Minimal MCP (Model Context Protocol) client over the stdio transport.
+//! Minimal MCP (Model Context Protocol) client over stdio and Streamable HTTP.
 //!
-//! For each server in .mcp.json we spawn the configured command, speak
-//! newline-delimited JSON-RPC 2.0 over its stdin/stdout, run the
-//! initialize -> initialized -> tools/list handshake, and expose the
-//! discovered tools to the agent. Tool calls are routed back via tools/call.
+//! A .mcp.json entry may contain either `command`/`args` (a child process using
+//! newline-delimited JSON-RPC on stdio) or `url` (JSON-RPC POSTs using MCP's
+//! Streamable HTTP transport). Both run the initialize -> initialized ->
+//! tools/list handshake and expose discovered tools to the agent.
 //!
-//! Concurrency: tool calls arrive from agent pool threads, but a single
-//! server is one bidirectional pipe — so every request/response round trip
-//! holds `mutex`, serializing access per registry. MCP calls are rare and
-//! fast relative to LLM calls, so global serialization is fine.
+//! Concurrency: tool calls arrive from agent pool threads, but transport state
+//! (stdio pipes, HTTP session IDs) is sequential, so every request/response
+//! round trip holds `mutex`. MCP calls are rare relative to LLM calls, so
+//! registry-wide serialization is fine.
 
 const std = @import("std");
-const builtin = @import("builtin");
 const Io = std.Io;
 const Value = std.json.Value;
 const Allocator = std.mem.Allocator;
+const mcp_http = @import("mcp_http.zig");
+const mcp_protocol = @import("mcp_protocol.zig");
+const mcp_stdio = @import("mcp_stdio.zig");
+
+const latest_protocol = mcp_protocol.latest_protocol;
+const rewriteOneOf = mcp_protocol.rewriteOneOf;
+const HttpTransport = mcp_http.HttpTransport;
+pub const validRemoteUrl = mcp_http.validRemoteUrl;
 
 pub const Tool = struct {
     server_index: usize,
@@ -23,107 +30,32 @@ pub const Tool = struct {
     description: []const u8,
     input_schema: Value, // arena-owned parsed JSON Schema
 };
+pub const smolify_url = "https://app.smol.ly/mcp";
 
-/// Recursively rewrite the JSON Schema keyword `oneOf` to `anyOf` (graff's
-/// rewrite_one_of_to_any_of). OpenAI's tool-schema validator — including the
-/// chatgpt.com /codex/responses endpoint — rejects `oneOf` outright with
-/// "'oneOf' is not permitted"; `anyOf` is accepted by both OpenAI and
-/// Anthropic and is equivalent for the discriminated unions MCP servers emit
-/// in practice. When both keywords are present (rare, ambiguous to merge),
-/// the existing `anyOf` wins and `oneOf` is dropped. Runs once per tool at
-/// discovery, so the rendered tools JSON stays KV-cache-stable.
-fn rewriteOneOf(a: Allocator, v: *Value) Allocator.Error!void {
-    switch (v.*) {
-        .object => |*obj| {
-            if (obj.get("oneOf")) |branches| {
-                if (obj.get("anyOf") == null) try obj.put(a, "anyOf", branches);
-                _ = obj.swapRemove("oneOf");
-            }
-            var it = obj.iterator();
-            while (it.next()) |e| try rewriteOneOf(a, e.value_ptr);
-        },
-        .array => |*arr| for (arr.items) |*item| try rewriteOneOf(a, item),
-        else => {},
-    }
-}
-/// Latest MCP revision we advertise in `initialize`. MCP versions are dated
-/// (there is no "MCP 2.0"); negotiation is built in: the client sends the
-/// newest revision it supports and the server answers with that version or
-/// the newest *it* supports — we accept whatever it picks because the entire
-/// surface we use (initialize / notifications/initialized / tools/list /
-/// tools/call with text content blocks) is identical from 2024-11-05 through
-/// 2025-11-25. Everything 2025-11-25 added (tasks, extensions, URL-mode
-/// elicitation, sampling tool-calls) is opt-in via capabilities, and we
-/// declare `capabilities:{}`, so servers can't expect any of it from us.
-/// The HTTP-only parts of the spec (MCP-Protocol-Version header, the
-/// HTTP+SSE removal) don't apply to this stdio-only client.
-const latest_protocol = "2025-11-25";
-
-const shutdown_grace = std.Io.Duration.fromMilliseconds(100);
-
-fn waitChild(child: *std.process.Child, io: Io) std.process.Child.WaitError!std.process.Child.Term {
-    return child.wait(io);
-}
-
-fn shutdownDeadline(io: Io) void {
-    io.sleep(shutdown_grace, .awake) catch {};
-}
-
-/// Signal a normal stdio-server shutdown with EOF, but never let a server's
-/// SIGTERM handler stall the CLI. A child that does not exit within the grace
-/// window is force-killed and reaped so one-shot/SDK callers do not inherit
-/// teardown latency or zombies.
-fn stopChild(io: Io, child: *std.process.Child) void {
-    if (child.id == null) return;
-    if (child.stdin) |stdin| {
-        stdin.close(io);
-        child.stdin = null;
-    }
+const StdioTransport = struct {
+    child: std.process.Child,
+    stdin_writer: Io.File.Writer,
+    stdout_reader: Io.File.Reader,
+};
 
-    const Done = union(enum) { exited: std.process.Child.WaitError!std.process.Child.Term, deadline: void };
-    var done_buf: [2]Done = undefined;
-    var sel: Io.Select(Done) = .init(io, &done_buf);
-    sel.concurrent(.exited, waitChild, .{ child, io }) catch {
-        child.kill(io);
-        return;
-    };
-    sel.concurrent(.deadline, shutdownDeadline, .{io}) catch {
-        _ = sel.await() catch {};
-        sel.cancelDiscard();
-        return;
-    };
-    const first = sel.await() catch {
-        sel.cancelDiscard();
-        child.kill(io);
-        return;
-    };
-    sel.cancelDiscard();
-    if (first == .exited or child.id == null) return;
-
-    switch (builtin.os.tag) {
-        .windows => child.kill(io),
-        .wasi => unreachable,
-        else => {
-            std.posix.kill(child.id.?, .KILL) catch {};
-            _ = child.wait(io) catch child.kill(io);
-        },
-    }
-}
+const Transport = union(enum) {
+    stdio: StdioTransport,
+    http: HttpTransport,
+};
 
 const Server = struct {
     name: []const u8,
-    child: std.process.Child,
-    stdin_writer: Io.File.Writer,
-    stdout_reader: Io.File.Reader,
+    transport: Transport,
     next_id: i64 = 1,
-    /// Revision the server negotiated in its `initialize` response ("?" if
-    /// it didn't say) — shown in `/mcp` so version skew is visible.
+    /// Revision the server negotiated in its validated `initialize` response,
+    /// shown in `/mcp` so version skew is visible.
     protocol_version: []const u8 = "?",
 };
 
 pub const Registry = struct {
     gpa: Allocator,
     io: Io,
+    home: []const u8,
     arena_state: std.heap.ArenaAllocator,
     mutex: Io.Mutex = .init,
     servers: []*Server = &.{},
@@ -133,10 +65,11 @@ pub const Registry = struct {
         return self.arena_state.allocator();
     }
 
-    /// Load .mcp.json (`{"mcpServers": {"name": {"command","args","env"}}}`),
-    /// spawn each server, handshake, and collect their tools. Returns null
+    /// Load .mcp.json entries containing either `command`/`args`/`env` or a
+    /// Streamable HTTP `url`, handshake each server, and collect their tools.
+    /// Returns null
     /// (no error) when the config file is absent — MCP is optional.
-    pub fn init(gpa: Allocator, io: Io, config_path: []const u8) !?Registry {
+    pub fn init(gpa: Allocator, io: Io, config_path: []const u8, home: []const u8) !?Registry {
         const text = Io.Dir.cwd().readFileAlloc(io, config_path, gpa, .limited(1 << 20)) catch |err| switch (err) {
             error.FileNotFound => return null,
             else => return err,
@@ -146,6 +79,7 @@ pub const Registry = struct {
         var reg: Registry = .{
             .gpa = gpa,
             .io = io,
+            .home = home,
             .arena_state = std.heap.ArenaAllocator.init(gpa),
         };
         errdefer reg.deinit();
@@ -159,6 +93,9 @@ pub const Registry = struct {
 
         var it = servers_obj.iterator();
         while (it.next()) |entry| {
+            // The core Smolify name is pinned below and cannot be shadowed by
+            // repository configuration.
+            if (std.mem.eql(u8, entry.key_ptr.*, "smolify")) continue;
             const name = try a.dupe(u8, entry.key_ptr.*);
             const cfg = entry.value_ptr.*.object;
             reg.startServer(a, &servers, &tools, name, cfg) catch |err| {
@@ -174,7 +111,12 @@ pub const Registry = struct {
     /// An empty registry (no config file present), so the harness can still
     /// accept servers added at runtime via `addServer`.
     pub fn empty(gpa: Allocator, io: Io) Registry {
-        return .{ .gpa = gpa, .io = io, .arena_state = std.heap.ArenaAllocator.init(gpa) };
+        return emptyWithOAuthHome(gpa, io, "");
+    }
+
+    /// An empty registry that can load OAuth tokens rooted under `home`.
+    pub fn emptyWithOAuthHome(gpa: Allocator, io: Io, home: []const u8) Registry {
+        return .{ .gpa = gpa, .io = io, .home = home, .arena_state = std.heap.ArenaAllocator.init(gpa) };
     }
 
     /// Spawn + handshake a server at runtime and append its tools. Returns the
@@ -182,6 +124,8 @@ pub const Registry = struct {
     /// callers must re-render their tool list afterward. Run between turns only
     /// (no tool calls in flight).
     pub fn addServer(reg: *Registry, name: []const u8, command: []const u8, args: []const []const u8) !usize {
+        for (reg.servers) |server| if (std.mem.eql(u8, server.name, name)) return error.McpServerAlreadyConnected;
+        if (std.mem.eql(u8, name, "smolify")) return error.ReservedMcpServerName;
         const a = reg.arena();
         var servers: std.ArrayList(*Server) = .empty;
         try servers.appendSlice(a, reg.servers);
@@ -201,6 +145,40 @@ pub const Registry = struct {
         return tools.items.len - before;
     }
 
+    /// Connect a Streamable HTTP server at runtime. `headers` are copied into
+    /// registry storage and sent on every request (for example Authorization).
+    pub fn addRemoteServer(reg: *Registry, name: []const u8, url: []const u8, headers: []const std.http.Header) !usize {
+        for (reg.servers) |server| if (std.mem.eql(u8, server.name, name)) return error.McpServerAlreadyConnected;
+        if (std.mem.eql(u8, name, "smolify") and (!std.mem.eql(u8, url, smolify_url) or headers.len != 0)) return error.ReservedMcpServerName;
+        const a = reg.arena();
+        var servers: std.ArrayList(*Server) = .empty;
+        try servers.appendSlice(a, reg.servers);
+        var tools: std.ArrayList(Tool) = .empty;
+        try tools.appendSlice(a, reg.tools);
+        const before = tools.items.len;
+
+        var cfg: std.json.ObjectMap = .empty;
+        try cfg.put(a, "url", .{ .string = try a.dupe(u8, url) });
+        if (headers.len > 0) {
+            var header_obj: std.json.ObjectMap = .empty;
+            for (headers) |header| try header_obj.put(a, try a.dupe(u8, header.name), .{ .string = try a.dupe(u8, header.value) });
+            try cfg.put(a, "headers", .{ .object = header_obj });
+        }
+
+        try reg.startServer(a, &servers, &tools, try a.dupe(u8, name), cfg);
+        reg.servers = try a.dupe(*Server, servers.items);
+        reg.tools = try a.dupe(Tool, tools.items);
+        return tools.items.len - before;
+    }
+
+    /// Connect Smolify's public documentation MCP as a core service. It is a
+    /// stateless Streamable HTTP endpoint, so no helper process or Node runtime
+    /// is required. Public search/read tools work anonymously.
+    pub fn connectSmolify(reg: *Registry) !usize {
+        for (reg.servers) |server| if (std.mem.eql(u8, server.name, "smolify")) return 0;
+        return reg.addRemoteServer("smolify", smolify_url, &.{});
+    }
+
     /// Connect any workspace `.mcp.json` servers not already running — the
     /// in-session equivalent of having started with `--yolo`, so a user who
     /// declined the startup consent prompt can opt in later without a restart.
@@ -229,6 +207,7 @@ pub const Registry = struct {
         var it = servers_v.object.iterator();
         while (it.next()) |entry| {
             const name = entry.key_ptr.*;
+            if (std.mem.eql(u8, name, "smolify")) continue;
             if (entry.value_ptr.* != .object) continue;
             // Already connected (auto-activated muonry, or a prior /mcp trust)? skip.
             var present = false;
@@ -259,6 +238,7 @@ pub const Registry = struct {
         var n: usize = 0;
         var it = servers_v.object.iterator();
         while (it.next()) |entry| {
+            if (std.mem.eql(u8, entry.key_ptr.*, "smolify")) continue;
             if (entry.value_ptr.* != .object) continue;
             var present = false;
             for (reg.servers) |s| if (std.mem.eql(u8, s.name, entry.key_ptr.*)) {
@@ -286,66 +266,97 @@ pub const Registry = struct {
         name: []const u8,
         cfg: std.json.ObjectMap,
     ) !void {
-        const command = if (cfg.get("command")) |c| (if (c == .string) c.string else return error.BadMcpConfig) else return error.BadMcpConfig;
-        var argv: std.ArrayList([]const u8) = .empty;
-        try argv.append(a, command);
-        if (cfg.get("args")) |args| if (args == .array) {
-            for (args.array.items) |arg| if (arg == .string) try argv.append(a, arg.string);
-        };
+        const command_v = cfg.get("command");
+        const url_v = cfg.get("url");
+        if ((command_v == null) == (url_v == null)) return error.BadMcpConfig;
 
-        // Optional per-server env overlaid on the parent environment.
-        var env_map: ?*std.process.Environ.Map = null;
-        if (cfg.get("env")) |env| if (env == .object) {
-            const m = try a.create(std.process.Environ.Map);
-            m.* = std.process.Environ.Map.init(reg.gpa);
-            var env_it = env.object.iterator();
-            while (env_it.next()) |e| try m.put(e.key_ptr.*, e.value_ptr.*.string);
-            env_map = m;
-        };
+        const server = try a.create(Server);
+        if (url_v) |url| {
+            if (url != .string) return error.BadMcpConfig;
+            if (!validRemoteUrl(url.string)) return error.BadMcpUrl;
+
+            var headers: std.ArrayList(std.http.Header) = .empty;
+            var has_authorization = false;
+            if (cfg.get("headers")) |headers_v| {
+                if (headers_v != .object) return error.BadMcpConfig;
+                var header_it = headers_v.object.iterator();
+                while (header_it.next()) |entry| {
+                    if (entry.value_ptr.* != .string) return error.BadMcpConfig;
+                    if (std.ascii.eqlIgnoreCase(entry.key_ptr.*, "authorization")) has_authorization = true;
+                    try headers.append(a, .{
+                        .name = try a.dupe(u8, entry.key_ptr.*),
+                        .value = try a.dupe(u8, entry.value_ptr.*.string),
+                    });
+                }
+            }
+            server.* = .{
+                .name = name,
+                .transport = .{ .http = .{
+                    .url = try a.dupe(u8, url.string),
+                    .client = .{ .allocator = reg.gpa, .io = reg.io },
+                    .headers = try a.dupe(std.http.Header, headers.items),
+                    .oauth_home = if (!has_authorization and reg.home.len != 0) try a.dupe(u8, reg.home) else null,
+                } },
+            };
+        } else {
+            const command = if (command_v.? == .string) command_v.?.string else return error.BadMcpConfig;
+            var argv: std.ArrayList([]const u8) = .empty;
+            try argv.append(a, command);
+            if (cfg.get("args")) |args| {
+                if (args != .array) return error.BadMcpConfig;
+                for (args.array.items) |arg| {
+                    if (arg != .string) return error.BadMcpConfig;
+                    try argv.append(a, arg.string);
+                }
+            }
 
-        var child = try std.process.spawn(reg.io, .{
-            .argv = argv.items,
-            .stdin = .pipe,
-            .stdout = .pipe,
-            .stderr = .ignore, // server logs/banners stay off our JSON channel
-            .environ_map = env_map,
-        });
-        // Until the server is appended below, we own the child and must kill
-        // it on any error path. Once it's in `reg.servers`, `deinit` becomes
-        // the sole owner: killing here *and* there would reap the pid twice,
-        // and the second kill panics on ESRCH in debug builds (a server whose
-        // handshake fails — McpClosed — has an already-dead child).
-        var registry_owns_child = false;
-        errdefer if (!registry_owns_child) {
-            stopChild(reg.io, &child);
-        };
+            // Optional per-server env overlaid on the parent environment.
+            var env_map: ?*std.process.Environ.Map = null;
+            if (cfg.get("env")) |env| {
+                if (env != .object) return error.BadMcpConfig;
+                const m = try a.create(std.process.Environ.Map);
+                m.* = std.process.Environ.Map.init(reg.gpa);
+                var env_it = env.object.iterator();
+                while (env_it.next()) |entry| {
+                    if (entry.value_ptr.* != .string) return error.BadMcpConfig;
+                    try m.put(entry.key_ptr.*, entry.value_ptr.*.string);
+                }
+                env_map = m;
+            }
 
-        const server = try a.create(Server);
-        const in_buf = try a.alloc(u8, 64 * 1024);
-        const out_buf = try a.alloc(u8, 1 << 20);
-        server.* = .{
-            .name = name,
-            .child = child,
-            .stdin_writer = child.stdin.?.writerStreaming(reg.io, in_buf),
-            .stdout_reader = child.stdout.?.readerStreaming(reg.io, out_buf),
-        };
+            var child = try std.process.spawn(reg.io, .{
+                .argv = argv.items,
+                .stdin = .pipe,
+                .stdout = .pipe,
+                .stderr = .ignore,
+                .environ_map = env_map,
+            });
+            var server_owns_child = false;
+            errdefer if (!server_owns_child) {
+                mcp_stdio.stopChild(reg.io, &child);
+            };
+            const in_buf = try a.alloc(u8, 64 * 1024);
+            const out_buf = try a.alloc(u8, 1 << 20);
+            server.* = .{
+                .name = name,
+                .transport = .{ .stdio = .{
+                    .child = child,
+                    .stdin_writer = child.stdin.?.writerStreaming(reg.io, in_buf),
+                    .stdout_reader = child.stdout.?.readerStreaming(reg.io, out_buf),
+                } },
+            };
+            server_owns_child = true;
+        }
+
+        var registry_owns_server = false;
+        errdefer if (!registry_owns_server) deinitServer(server, reg.io);
         const server_index = servers.items.len;
-        try servers.append(a, server);
-        registry_owns_child = true; // deinit now owns the child; don't double-kill
+        const tools_before = tools.items.len;
+        errdefer tools.shrinkRetainingCapacity(tools_before);
 
         // Handshake. The server's reply tells us which revision it picked;
         // record it (we proceed regardless — see `latest_protocol`).
-        const init_resp = try request(server, a,
-            \\{"protocolVersion":"
-        ++ latest_protocol ++
-            \\","capabilities":{},"clientInfo":{"name":"simple-harness","version":"0.1"}}
-        , "initialize");
-        if (init_resp.object.get("result")) |res| if (res == .object) {
-            if (res.object.get("protocolVersion")) |pv| if (pv == .string) {
-                server.protocol_version = try a.dupe(u8, pv.string);
-            };
-        };
-        try notify(server, "notifications/initialized");
+        try initializeServer(server, a, a);
 
         const listed = try request(server, a, "{}", "tools/list");
         const result_v = listed.object.get("result") orelse return error.BadMcpResponse;
@@ -371,11 +382,13 @@ pub const Registry = struct {
                 .input_schema = schema,
             });
         }
+        try servers.append(a, server);
+        registry_owns_server = true;
         std.debug.print("  [mcp:{s}] connected (mcp {s}) — {d} tool(s)\n", .{ name, server.protocol_version, tools_v.array.items.len });
     }
 
     pub fn deinit(reg: *Registry) void {
-        for (reg.servers) |server| stopChild(reg.io, &server.child);
+        for (reg.servers) |server| deinitServer(server, reg.io);
         reg.arena_state.deinit();
     }
 
@@ -407,16 +420,34 @@ pub const Registry = struct {
         reg.mutex.lockUncancelable(reg.io);
         defer reg.mutex.unlock(reg.io);
 
-        const a = reg.arena(); // response Values; freed at session end
-        const resp = try request(server, a, pw.writer.buffered(), "tools/call");
+        // Tool responses can be large and numerous; keep them out of the
+        // session arena. Only the returned text is copied to `out_alloc`.
+        var response_arena_state = std.heap.ArenaAllocator.init(reg.gpa);
+        defer response_arena_state.deinit();
+        const response_alloc = response_arena_state.allocator();
+        const resp = request(server, response_alloc, pw.writer.buffered(), "tools/call") catch |err| switch (err) {
+            // Streamable HTTP servers use 404 to expire a session. Re-run the
+            // MCP handshake once, then retry the call without the stale ID.
+            error.McpSessionExpired => retry: {
+                try initializeServer(server, response_alloc, reg.arena());
+                break :retry try request(server, response_alloc, pw.writer.buffered(), "tools/call");
+            },
+            else => return err,
+        };
 
         if (resp.object.get("error")) |e| {
             // Protocol-level failure (unknown tool, invalid args, server
             // crash) — distinct from a tool that ran and *returned* an error
             // (isError below). Keep the JSON-RPC code: models retry better
             // when they can tell -32602 bad-params from a tool-side failure.
-            const msg = if (e.object.get("message")) |m| m.string else "MCP error";
-            const code: i64 = if (e.object.get("code")) |c| (if (c == .integer) c.integer else 0) else 0;
+            const msg = if (e == .object) blk: {
+                const m = e.object.get("message") orelse break :blk "MCP error";
+                break :blk if (m == .string) m.string else "MCP error";
+            } else "MCP error";
+            const code: i64 = if (e == .object) blk: {
+                const c = e.object.get("code") orelse break :blk 0;
+                break :blk if (c == .integer) c.integer else 0;
+            } else 0;
             const text = if (code != 0)
                 try std.fmt.allocPrint(out_alloc, "MCP error {d}: {s}", .{ code, msg })
             else
@@ -456,76 +487,80 @@ pub const Registry = struct {
     }
 };
 
-/// JSON-RPC request/response over one server's stdio pipe. `params` is a raw
-/// JSON object string. Skips interleaved notifications (messages without our
-/// id) until the matching response arrives. Result Values are arena-owned.
-fn request(server: *Server, a: Allocator, params: []const u8, method: []const u8) !Value {
-    const id = server.next_id;
-    server.next_id += 1;
-
-    const w = &server.stdin_writer.interface;
-    try w.print(
-        \\{{"jsonrpc":"2.0","id":{d},"method":"{s}","params":{s}}}
-    ++ "\n", .{ id, method, params });
-    try w.flush();
-
-    const r = &server.stdout_reader.interface;
-    while (true) {
-        const line = (try r.takeDelimiter('\n')) orelse return error.McpClosed;
-        if (line.len == 0) continue;
-        const parsed = std.json.parseFromSliceLeaky(Value, a, line, .{ .allocate = .alloc_always }) catch continue;
-        if (parsed != .object) continue;
-        const got = parsed.object.get("id") orelse continue; // notification
-        if (got == .integer and got.integer == id) return parsed;
+fn deinitServer(server: *Server, io: Io) void {
+    switch (server.transport) {
+        .stdio => |*stdio| mcp_stdio.stopChild(io, &stdio.child),
+        .http => |*http| {
+            if (http.session_id) |session_id| http.client.allocator.free(session_id);
+            http.client.deinit();
+        },
     }
 }
 
-/// Fire-and-forget JSON-RPC notification (no id, no response).
-fn notify(server: *Server, method: []const u8) !void {
-    const w = &server.stdin_writer.interface;
-    try w.print(
-        \\{{"jsonrpc":"2.0","method":"{s}","params":{{}}}}
-    ++ "\n", .{method});
-    try w.flush();
+fn initializeServer(server: *Server, response_alloc: Allocator, session_alloc: Allocator) !void {
+    const init_resp = try request(server, response_alloc,
+        \\{"protocolVersion":"
+    ++ latest_protocol ++
+        \\","capabilities":{},"clientInfo":{"name":"simple-harness","version":"0.1"}}
+    , "initialize");
+    const protocol_transport: mcp_protocol.Transport = switch (server.transport) {
+        .stdio => .stdio,
+        .http => .streamable_http,
+    };
+    const protocol_version = try mcp_protocol.negotiatedProtocol(init_resp, protocol_transport);
+    server.protocol_version = try session_alloc.dupe(u8, protocol_version);
+    try notify(server, response_alloc, "notifications/initialized");
 }
 
-test "rewriteOneOf: converts oneOf to anyOf, recursively" {
-    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
-    defer arena_state.deinit();
-    const a = arena_state.allocator();
-    var v = try std.json.parseFromSliceLeaky(Value, a,
-        \\{"oneOf":[{"type":"string"}],"properties":{"x":{"oneOf":[{"type":"number"},{"type":"null"}]}}}
-    , .{});
-    try rewriteOneOf(a, &v);
-    try std.testing.expect(v.object.get("oneOf") == null);
-    try std.testing.expectEqual(@as(usize, 1), v.object.get("anyOf").?.array.items.len);
-    const x = v.object.get("properties").?.object.get("x").?;
-    try std.testing.expect(x.object.get("oneOf") == null);
-    try std.testing.expectEqual(@as(usize, 2), x.object.get("anyOf").?.array.items.len);
-}
+/// JSON-RPC request/response over either transport. `params` is a raw JSON
+/// object string. Result Values use `response_alloc`.
+fn request(server: *Server, response_alloc: Allocator, params: []const u8, method: []const u8) !Value {
+    const id = server.next_id;
+    server.next_id += 1;
 
-test "rewriteOneOf: existing anyOf wins when both are present" {
-    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
-    defer arena_state.deinit();
-    const a = arena_state.allocator();
-    var v = try std.json.parseFromSliceLeaky(Value, a,
-        \\{"anyOf":[{"type":"string"}],"oneOf":[{"type":"number"},{"type":"boolean"}]}
-    , .{});
-    try rewriteOneOf(a, &v);
-    try std.testing.expect(v.object.get("oneOf") == null);
-    // the pre-existing single-branch anyOf survives, the oneOf is dropped
-    try std.testing.expectEqual(@as(usize, 1), v.object.get("anyOf").?.array.items.len);
+    switch (server.transport) {
+        .stdio => |*stdio| {
+            const w = &stdio.stdin_writer.interface;
+            try w.print(
+                \\{{"jsonrpc":"2.0","id":{d},"method":"{s}","params":{s}}}
+            ++ "\n", .{ id, method, params });
+            try w.flush();
+
+            const r = &stdio.stdout_reader.interface;
+            while (true) {
+                const line = (try r.takeDelimiter('\n')) orelse return error.McpClosed;
+                if (mcp_http.matchingResponse(response_alloc, line, id)) |parsed| return parsed;
+            }
+        },
+        .http => |*http| {
+            const body = try std.fmt.allocPrint(response_alloc,
+                \\{{"jsonrpc":"2.0","id":{d},"method":"{s}","params":{s}}}
+            , .{ id, method, params });
+            const protocol_version = if (std.mem.eql(u8, method, "initialize")) latest_protocol else server.protocol_version;
+            const response_body = (try mcp_http.post(http, body, protocol_version, id)) orelse return error.BadMcpResponse;
+            defer http.client.allocator.free(response_body);
+            return mcp_http.parseHttpResponse(response_alloc, response_body, id) orelse error.BadMcpResponse;
+        },
+    }
 }
 
-test "rewriteOneOf: arrays and scalars pass through untouched" {
-    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
-    defer arena_state.deinit();
-    const a = arena_state.allocator();
-    var v = try std.json.parseFromSliceLeaky(Value, a,
-        \\{"items":[{"oneOf":[1,2]},"plain",42]}
-    , .{});
-    try rewriteOneOf(a, &v);
-    const first = v.object.get("items").?.array.items[0];
-    try std.testing.expect(first.object.get("oneOf") == null);
-    try std.testing.expect(first.object.get("anyOf") != null);
+/// Fire-and-forget JSON-RPC notification (no id, no response).
+fn notify(server: *Server, response_alloc: Allocator, method: []const u8) !void {
+    switch (server.transport) {
+        .stdio => |*stdio| {
+            const w = &stdio.stdin_writer.interface;
+            try w.print(
+                \\{{"jsonrpc":"2.0","method":"{s}","params":{{}}}}
+            ++ "\n", .{method});
+            try w.flush();
+        },
+        .http => |*http| {
+            const body = try std.fmt.allocPrint(response_alloc,
+                \\{{"jsonrpc":"2.0","method":"{s}","params":{{}}}}
+            , .{method});
+            if (try mcp_http.post(http, body, server.protocol_version, null)) |response_body| {
+                http.client.allocator.free(response_body);
+            }
+        },
+    }
 }
diff --git a/src/mcp_cli.zig b/src/mcp_cli.zig
index 0ce0d90d..8e6cafe1 100644
--- a/src/mcp_cli.zig
+++ b/src/mcp_cli.zig
@@ -11,6 +11,8 @@ const Allocator = std.mem.Allocator;
 
 const root = @import("main.zig");
 const skills = @import("skills.zig");
+const mcp = @import("mcp.zig");
+const mcp_oauth = @import("mcp_oauth.zig");
 const mcp_config_path = root.mcp_config_path;
 const companion_servers = skills.companion_servers;
 
@@ -41,6 +43,9 @@ pub fn countMcpServers(io: Io, arena: Allocator) usize {
     var n: usize = 0;
     var it = servers.object.iterator();
     while (it.next()) |entry| {
+        // `smolify` is a reserved core server; workspace entries cannot shadow
+        // its pinned endpoint and therefore need no workspace consent.
+        if (std.mem.eql(u8, entry.key_ptr.*, "smolify")) continue;
         if (!trustedMcpEntry(entry.key_ptr.*, entry.value_ptr.*)) n += 1;
     }
     return n;
@@ -49,6 +54,7 @@ pub fn countMcpServers(io: Io, arena: Allocator) usize {
 /// Best-effort write of a server entry into .mcp.json (so `/mcp add` survives
 /// a restart). Merges into any existing config. Returns false on any error.
 const McpEnvPair = struct { key: []const u8, value: []const u8 };
+pub const McpHeaderPair = struct { key: []const u8, value: []const u8 };
 
 pub fn persistMcpServer(io: Io, arena: Allocator, name: []const u8, command: []const u8, args: []const []const u8) bool {
     return persistMcpServerWithEnv(io, arena, name, command, args, &.{});
@@ -92,14 +98,56 @@ fn persistMcpServerWithEnv(io: Io, arena: Allocator, name: []const u8, command:
     return true;
 }
 
+/// Persist a native Streamable HTTP entry. Headers are optional and intended
+/// for static bearer/API tokens; OAuth-capable servers can remain anonymous
+/// until an authorization flow is configured.
+pub fn persistMcpUrl(io: Io, arena: Allocator, name: []const u8, url: []const u8, headers: []const McpHeaderPair) bool {
+    var root_obj: std.json.ObjectMap = .empty;
+    if (Io.Dir.cwd().readFileAlloc(io, mcp_config_path, arena, .limited(1 << 20))) |text| {
+        if (std.json.parseFromSliceLeaky(Value, arena, text, .{ .allocate = .alloc_always })) |v| {
+            if (v == .object) root_obj = v.object;
+        } else |_| {}
+    } else |_| {}
+
+    var servers: std.json.ObjectMap = .empty;
+    if (root_obj.get("mcpServers")) |m| if (m == .object) {
+        servers = m.object;
+    };
+    var entry: std.json.ObjectMap = .empty;
+    entry.put(arena, "url", .{ .string = url }) catch return false;
+    if (headers.len > 0) {
+        var header_obj: std.json.ObjectMap = .empty;
+        for (headers) |header| header_obj.put(arena, header.key, .{ .string = header.value }) catch return false;
+        entry.put(arena, "headers", .{ .object = header_obj }) catch return false;
+    }
+    servers.put(arena, name, .{ .object = entry }) catch return false;
+    root_obj.put(arena, "mcpServers", .{ .object = servers }) catch return false;
+
+    var aw: Io.Writer.Allocating = .init(arena);
+    var stringify: std.json.Stringify = .{ .writer = &aw.writer };
+    stringify.write(Value{ .object = root_obj }) catch return false;
+    const file = Io.Dir.cwd().createFile(io, mcp_config_path, .{}) catch return false;
+    defer file.close(io);
+    var buffer: [4096]u8 = undefined;
+    var writer = file.writer(io, &buffer);
+    writer.interface.writeAll(aw.writer.buffered()) catch return false;
+    writer.interface.flush() catch return false;
+    return true;
+}
+
 fn mcpCliUsage(w: *Io.Writer) !void {
     try w.writeAll(
         \\usage:
         \\  graff mcp                      list servers in .mcp.json
+        \\  graff mcp add <name> --url <https://...> [--header KEY=VALUE ...]
+        \\  graff mcp login <name>        OAuth login for a remote server
         \\  graff mcp add <name> [--env KEY=VALUE ...] -- <command> [args...]
         \\  graff mcp add <name> <command> [args...]
         \\
         \\examples:
+        \\  graff mcp add mobbin --url https://api.mobbin.com/mcp
+        \\  graff mcp login mobbin
+        \\  graff mcp login smolify
         \\  graff mcp add context7 -- npx -y @upstash/context7-mcp
         \\  graff mcp add playwright -- npx -y @playwright/mcp
         \\  graff mcp add sentry --env SENTRY_AUTH_TOKEN=... -- npx -y @sentry/mcp-server
@@ -107,7 +155,7 @@ fn mcpCliUsage(w: *Io.Writer) !void {
     );
 }
 
-pub fn mcpCommand(io: Io, arena: Allocator, args: []const []const u8) !void {
+pub fn mcpCommand(io: Io, gpa: Allocator, arena: Allocator, home: []const u8, args: []const []const u8) !void {
     var obuf: [4096]u8 = undefined;
     var out = Io.File.stdout().writer(io, &obuf);
 
@@ -134,11 +182,15 @@ pub fn mcpCommand(io: Io, arena: Allocator, args: []const []const u8) !void {
             while (it.next()) |entry| {
                 const cfg = entry.value_ptr.*;
                 if (cfg != .object) continue;
-                const command = if (cfg.object.get("command")) |c| if (c == .string) c.string else "?" else "?";
-                try out.interface.print("  {s}: {s}", .{ entry.key_ptr.*, command });
-                if (cfg.object.get("args")) |argv| if (argv == .array) for (argv.array.items) |a| {
-                    if (a == .string) try out.interface.print(" {s}", .{a.string});
-                };
+                if (cfg.object.get("url")) |url| {
+                    try out.interface.print("  {s}: {s}", .{ entry.key_ptr.*, if (url == .string) url.string else "?" });
+                } else {
+                    const command = if (cfg.object.get("command")) |c| if (c == .string) c.string else "?" else "?";
+                    try out.interface.print("  {s}: {s}", .{ entry.key_ptr.*, command });
+                    if (cfg.object.get("args")) |argv| if (argv == .array) for (argv.array.items) |arg| {
+                        if (arg == .string) try out.interface.print(" {s}", .{arg.string});
+                    };
+                }
                 try out.interface.writeByte('\n');
             }
         }
@@ -152,6 +204,33 @@ pub fn mcpCommand(io: Io, arena: Allocator, args: []const []const u8) !void {
         return;
     }
 
+    if (std.mem.eql(u8, args[0], "login")) {
+        if (args.len != 2) {
+            try out.interface.writeAll("usage: graff mcp login <name>\n");
+            try out.interface.flush();
+            return;
+        }
+        const name = args[1];
+        const url = if (std.mem.eql(u8, name, "smolify"))
+            mcp.smolify_url
+        else url: {
+            const data = Io.Dir.cwd().readFileAlloc(io, mcp_config_path, arena, .limited(1 << 20)) catch
+                std.process.fatal("mcp login: no .mcp.json; add the remote server first", .{});
+            const config = std.json.parseFromSliceLeaky(Value, arena, data, .{ .allocate = .alloc_always }) catch
+                std.process.fatal("mcp login: .mcp.json is not valid JSON", .{});
+            if (config != .object) std.process.fatal("mcp login: .mcp.json is not an object", .{});
+            const servers = config.object.get("mcpServers") orelse std.process.fatal("mcp login: server '{s}' is not configured", .{name});
+            if (servers != .object) std.process.fatal("mcp login: mcpServers is not an object", .{});
+            const entry = servers.object.get(name) orelse std.process.fatal("mcp login: server '{s}' is not configured", .{name});
+            if (entry != .object) std.process.fatal("mcp login: server '{s}' has invalid config", .{name});
+            const remote = entry.object.get("url") orelse std.process.fatal("mcp login: server '{s}' is not a remote URL server", .{name});
+            if (remote != .string or !mcp.validRemoteUrl(remote.string)) std.process.fatal("mcp login: server '{s}' has an invalid URL", .{name});
+            break :url remote.string;
+        };
+        try mcp_oauth.login(io, gpa, arena, home, name, url);
+        return;
+    }
+
     if (!std.mem.eql(u8, args[0], "add")) {
         try mcpCliUsage(&out.interface);
         try out.interface.flush();
@@ -164,6 +243,36 @@ pub fn mcpCommand(io: Io, arena: Allocator, args: []const []const u8) !void {
     }
 
     const name = args[1];
+    if (std.mem.eql(u8, name, "smolify")) std.process.fatal("mcp add: 'smolify' is a reserved core server", .{});
+    if (std.mem.eql(u8, args[2], "--url") or std.mem.startsWith(u8, args[2], "--url=")) {
+        const url = if (std.mem.eql(u8, args[2], "--url")) blk: {
+            if (args.len < 4) std.process.fatal("mcp add: --url needs an HTTP(S) URL", .{});
+            break :blk args[3];
+        } else args[2]["--url=".len..];
+        if (!mcp.validRemoteUrl(url)) std.process.fatal("mcp add: URL must use HTTPS (HTTP is allowed only for localhost)", .{});
+        const first_option: usize = if (std.mem.eql(u8, args[2], "--url")) 4 else 3;
+        var headers: std.ArrayList(McpHeaderPair) = .empty;
+        defer headers.deinit(arena);
+        var j = first_option;
+        while (j < args.len) : (j += 1) {
+            const arg = args[j];
+            const raw = if (std.mem.eql(u8, arg, "--header")) value: {
+                j += 1;
+                if (j >= args.len) std.process.fatal("mcp add: --header needs KEY=VALUE", .{});
+                break :value args[j];
+            } else if (std.mem.startsWith(u8, arg, "--header="))
+                arg["--header=".len..]
+            else
+                std.process.fatal("mcp add: unexpected URL option '{s}'", .{arg});
+            const eq = std.mem.indexOfScalar(u8, raw, '=') orelse std.process.fatal("mcp add: --header expects KEY=VALUE", .{});
+            try headers.append(arena, .{ .key = raw[0..eq], .value = raw[eq + 1 ..] });
+        }
+        if (!persistMcpUrl(io, arena, name, url, headers.items)) std.process.fatal("could not write .mcp.json", .{});
+        try out.interface.print("saved Streamable HTTP MCP server '{s}' to .mcp.json\n", .{name});
+        try out.interface.flush();
+        return;
+    }
+
     var env_pairs: std.ArrayList(McpEnvPair) = .empty;
     defer env_pairs.deinit(arena);
     var command_index: ?usize = null;
@@ -217,4 +326,10 @@ test "trustedMcpEntry: only the exact companion shape skips the consent gate" {
     try std.testing.expect(!trustedMcpEntry("muonry", parse(a, "{\"command\":\"muonry\",\"args\":[\"--mcp\",\"--evil\"]}")));
     try std.testing.expect(!trustedMcpEntry("muonry", parse(a, "{\"command\":\"./muonry\",\"args\":[\"--mcp\"]}")));
     try std.testing.expect(!trustedMcpEntry("other", parse(a, "{\"command\":\"muonry\"}")));
+    // Workspace remote servers cross a network/data boundary and need consent
+    // just like local commands.
+    try std.testing.expect(!trustedMcpEntry("remote", parse(a, "{\"url\":\"https://example.com/mcp\"}")));
+    try std.testing.expect(!trustedMcpEntry("local-http", parse(a, "{\"url\":\"http://127.0.0.1:3000/mcp\"}")));
+    try std.testing.expect(!trustedMcpEntry("remote", parse(a, "{\"url\":\"file:///tmp/mcp\"}")));
+    try std.testing.expect(!trustedMcpEntry("remote", parse(a, "{\"url\":\"https://example.com/mcp\",\"command\":\"evil\"}")));
 }
diff --git a/src/mcp_http.zig b/src/mcp_http.zig
new file mode 100644
index 00000000..ac86bd03
--- /dev/null
+++ b/src/mcp_http.zig
@@ -0,0 +1,297 @@
+//! MCP Streamable HTTP transport.
+
+const std = @import("std");
+const Io = std.Io;
+const Value = std.json.Value;
+const Allocator = std.mem.Allocator;
+const mcp_oauth = @import("mcp_oauth.zig");
+
+const max_http_response = 1 << 20;
+
+pub const HttpTransport = struct {
+    url: []const u8,
+    client: std.http.Client,
+    headers: []const std.http.Header = &.{},
+    oauth_home: ?[]const u8 = null,
+    session_id: ?[]const u8 = null,
+};
+
+fn validRemoteUri(uri: std.Uri) bool {
+    if (uri.host == null) return false;
+    if (std.ascii.eqlIgnoreCase(uri.scheme, "https")) return true;
+    if (!std.ascii.eqlIgnoreCase(uri.scheme, "http")) return false;
+    const host = uri.host.?.percent_encoded;
+    return std.ascii.eqlIgnoreCase(host, "localhost") or
+        std.mem.eql(u8, host, "127.0.0.1") or
+        std.mem.eql(u8, host, "[::1]") or
+        std.mem.eql(u8, host, "::1");
+}
+
+pub fn validRemoteUrl(url: []const u8) bool {
+    return validRemoteUri(std.Uri.parse(url) catch return false);
+}
+
+pub fn matchingResponse(a: Allocator, bytes: []const u8, id: i64) ?Value {
+    const trimmed = std.mem.trim(u8, bytes, " \t\r\n");
+    if (trimmed.len == 0) return null;
+    const parsed = std.json.parseFromSliceLeaky(Value, a, trimmed, .{ .allocate = .alloc_always }) catch return null;
+    if (parsed != .object) return null;
+    const got = parsed.object.get("id") orelse return null;
+    if (got != .integer or got.integer != id) return null;
+    return parsed;
+}
+
+/// Streamable HTTP permits either a plain application/json body or an SSE
+/// response. MCP JSON-RPC payloads are compact one-line `data:` events; ignore
+/// comments/notifications and return the event matching our request id.
+pub fn parseHttpResponse(a: Allocator, body: []const u8, id: i64) ?Value {
+    if (matchingResponse(a, body, id)) |parsed| return parsed;
+    var lines = std.mem.splitScalar(u8, body, '\n');
+    while (lines.next()) |raw_line| {
+        const line = std.mem.trimEnd(u8, raw_line, "\r");
+        if (!std.mem.startsWith(u8, line, "data:")) continue;
+        if (matchingResponse(a, std.mem.trimStart(u8, line["data:".len..], " \t"), id)) |parsed| return parsed;
+    }
+    return null;
+}
+
+fn jsonResponseMatches(gpa: Allocator, bytes: []const u8, expected_id: i64) bool {
+    const parsed = std.json.parseFromSlice(Value, gpa, bytes, .{}) catch return false;
+    defer parsed.deinit();
+    if (parsed.value != .object) return false;
+    const id = parsed.value.object.get("id") orelse return false;
+    return id == .integer and id.integer == expected_id;
+}
+
+/// Read SSE one event at a time and return as soon as the matching JSON-RPC
+/// response arrives. This is important for servers that keep the POST stream
+/// open after emitting the response. Multiple `data:` fields are joined with
+/// newlines per the SSE specification.
+fn readSseResponse(gpa: Allocator, reader: *Io.Reader, expected_id: ?i64) !?[]u8 {
+    const line_buf = try gpa.alloc(u8, max_http_response);
+    defer gpa.free(line_buf);
+    var event_data: std.ArrayList(u8) = .empty;
+    defer event_data.deinit(gpa);
+    var consumed: usize = 0;
+
+    while (consumed < max_http_response) {
+        var line_writer = Io.Writer.fixed(line_buf);
+        const remaining = max_http_response - consumed;
+        const n = reader.streamDelimiterLimit(&line_writer, '\n', .limited(remaining)) catch |err| switch (err) {
+            error.StreamTooLong, error.WriteFailed => return error.McpResponseTooLarge,
+            else => return err,
+        };
+        consumed += n;
+        const line = std.mem.trimEnd(u8, line_writer.buffered(), "\r");
+
+        var at_eof = false;
+        const delimiter = reader.takeByte() catch |err| switch (err) {
+            error.EndOfStream => blk: {
+                at_eof = true;
+                break :blk 0;
+            },
+            else => return err,
+        };
+        if (!at_eof) {
+            std.debug.assert(delimiter == '\n');
+            consumed += 1;
+        }
+
+        if (std.mem.startsWith(u8, line, "data:")) {
+            const data = std.mem.trimStart(u8, line["data:".len..], " \t");
+            if (event_data.items.len > 0) try event_data.append(gpa, '\n');
+            if (event_data.items.len + data.len > max_http_response) return error.McpResponseTooLarge;
+            try event_data.appendSlice(gpa, data);
+        }
+
+        if (line.len == 0 or at_eof) {
+            if (event_data.items.len > 0) {
+                const matches = if (expected_id) |id| jsonResponseMatches(gpa, event_data.items, id) else true;
+                if (matches) return try gpa.dupe(u8, event_data.items);
+                event_data.clearRetainingCapacity();
+            }
+        }
+        if (at_eof) break;
+    }
+    if (consumed >= max_http_response) return error.McpResponseTooLarge;
+    return null;
+}
+
+/// Perform one bounded Streamable HTTP POST, retaining the MCP session ID from
+/// initialize and accepting both JSON and SSE responses. A 202 with no body is
+/// the normal response to a notification.
+fn httpPostUnwatched(http: *HttpTransport, body: []const u8, protocol_version: []const u8, expected_id: ?i64) !?[]u8 {
+    var oauth_arena_state = std.heap.ArenaAllocator.init(http.client.allocator);
+    defer oauth_arena_state.deinit();
+    const oauth_arena = oauth_arena_state.allocator();
+
+    var extra: std.ArrayList(std.http.Header) = .empty;
+    defer extra.deinit(http.client.allocator);
+    try extra.appendSlice(http.client.allocator, http.headers);
+    if (http.oauth_home) |home| if (mcp_oauth.loadAccessToken(http.client.io, http.client.allocator, oauth_arena, home, http.url)) |token| {
+        try extra.append(http.client.allocator, .{
+            .name = "authorization",
+            .value = try std.fmt.allocPrint(oauth_arena, "Bearer {s}", .{token}),
+        });
+    };
+    try extra.append(http.client.allocator, .{ .name = "accept", .value = "application/json, text/event-stream" });
+    try extra.append(http.client.allocator, .{ .name = "mcp-protocol-version", .value = protocol_version });
+    if (http.session_id) |session_id| try extra.append(http.client.allocator, .{ .name = "mcp-session-id", .value = session_id });
+
+    var req = try http.client.request(.POST, try std.Uri.parse(http.url), .{
+        .redirect_behavior = .unhandled,
+        .headers = .{
+            .content_type = .{ .override = "application/json" },
+            .accept_encoding = .omit,
+            .user_agent = .{ .override = "codegraff-mcp/1" },
+        },
+        .extra_headers = extra.items,
+    });
+    defer req.deinit();
+    errdefer {
+        if (req.connection) |connection| connection.closing = true;
+    }
+
+    req.transfer_encoding = .{ .content_length = body.len };
+    var body_writer = try req.sendBodyUnflushed(&.{});
+    try body_writer.writer.writeAll(body);
+    try body_writer.end();
+    try req.connection.?.flush();
+    var response = try req.receiveHead(&.{});
+
+    const status = @intFromEnum(response.head.status);
+    if (status == 401 or status == 403) {
+        if (req.connection) |connection| connection.closing = true;
+        return error.McpAuthenticationRequired;
+    }
+    if (status == 404 and http.session_id != null) {
+        if (req.connection) |connection| connection.closing = true;
+        http.client.allocator.free(http.session_id.?);
+        http.session_id = null;
+        return error.McpSessionExpired;
+    }
+    if (status < 200 or status >= 300) {
+        if (req.connection) |connection| connection.closing = true;
+        return error.McpHttpStatus;
+    }
+
+    var header_it = response.head.iterateHeaders();
+    while (header_it.next()) |header| {
+        if (std.ascii.eqlIgnoreCase(header.name, "mcp-session-id")) {
+            if (http.session_id) |session_id| {
+                if (!std.mem.eql(u8, session_id, header.value)) return error.McpSessionChanged;
+            } else {
+                http.session_id = try http.client.allocator.dupe(u8, header.value);
+            }
+        }
+    }
+
+    if (response.head.content_length == 0) return null;
+    const is_sse = if (response.head.content_type) |content_type|
+        std.ascii.startsWithIgnoreCase(content_type, "text/event-stream")
+    else
+        false;
+    var transfer_buf: [4096]u8 = undefined;
+    const reader = response.reader(&transfer_buf);
+    if (is_sse) return readSseResponse(http.client.allocator, reader, expected_id);
+
+    const response_buf = try http.client.allocator.alloc(u8, max_http_response);
+    errdefer http.client.allocator.free(response_buf);
+    var fixed = Io.Writer.fixed(response_buf);
+    _ = reader.streamRemaining(&fixed) catch |err| switch (err) {
+        error.WriteFailed => return error.McpResponseTooLarge,
+        else => return err,
+    };
+    const len = fixed.buffered().len;
+    if (len == 0) {
+        http.client.allocator.free(response_buf);
+        return null;
+    }
+    return try http.client.allocator.realloc(response_buf, len);
+}
+
+const HttpPostDone = union(enum) {
+    posted: anyerror!?[]u8,
+    timeout,
+};
+
+fn httpPostTask(http: *HttpTransport, body: []const u8, protocol_version: []const u8, expected_id: ?i64) anyerror!?[]u8 {
+    return httpPostUnwatched(http, body, protocol_version, expected_id);
+}
+
+fn httpPostTimeout(io: Io) void {
+    io.sleep(.fromSeconds(15), .awake) catch {};
+}
+
+fn freeLateHttpPost(allocator: Allocator, result: anyerror!?[]u8) void {
+    if (result) |body| {
+        if (body) |bytes| allocator.free(bytes);
+    } else |_| {}
+}
+
+fn cancelHttpPost(select: *Io.Select(HttpPostDone), allocator: Allocator) void {
+    while (select.cancel()) |late| switch (late) {
+        .posted => |result| freeLateHttpPost(allocator, result),
+        .timeout => {},
+    };
+}
+
+/// Race network I/O against a hard deadline. Cancellation unwinds the request,
+/// whose errdefer poisons the connection so a timed-out socket is never pooled.
+pub fn post(http: *HttpTransport, body: []const u8, protocol_version: []const u8, expected_id: ?i64) !?[]u8 {
+    var done_buf: [2]HttpPostDone = undefined;
+    var select: Io.Select(HttpPostDone) = .init(http.client.io, &done_buf);
+    select.concurrent(.posted, httpPostTask, .{ http, body, protocol_version, expected_id }) catch
+        return error.McpRequestTimedOut;
+    select.concurrent(.timeout, httpPostTimeout, .{http.client.io}) catch {
+        const only = select.await() catch |err| {
+            cancelHttpPost(&select, http.client.allocator);
+            return err;
+        };
+        select.cancelDiscard();
+        return only.posted;
+    };
+
+    const first = select.await() catch |err| {
+        cancelHttpPost(&select, http.client.allocator);
+        return err;
+    };
+    switch (first) {
+        .posted => |result| {
+            select.cancelDiscard();
+            return result;
+        },
+        .timeout => {
+            while (select.cancel()) |late| switch (late) {
+                .posted => |result| freeLateHttpPost(http.client.allocator, result),
+                .timeout => {},
+            };
+            return error.McpRequestTimedOut;
+        },
+    }
+}
+
+test "remote URLs require HTTPS except on loopback" {
+    try std.testing.expect(validRemoteUrl("https://api.mobbin.com/mcp"));
+    try std.testing.expect(validRemoteUrl("http://localhost:3000/mcp"));
+    try std.testing.expect(validRemoteUrl("http://127.0.0.1:3000/mcp"));
+    try std.testing.expect(validRemoteUrl("http://[::1]:3000/mcp"));
+    try std.testing.expect(!validRemoteUrl("http://api.mobbin.com/mcp"));
+    try std.testing.expect(!validRemoteUrl("ftp://localhost/mcp"));
+    try std.testing.expect(!validRemoteUrl("not a URL"));
+}
+
+test "parseHttpResponse accepts JSON and Streamable HTTP SSE" {
+    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+    defer arena_state.deinit();
+    const a = arena_state.allocator();
+
+    const json = parseHttpResponse(a, "{\"jsonrpc\":\"2.0\",\"id\":7,\"result\":{}}", 7).?;
+    try std.testing.expect(json.object.get("result") != null);
+
+    const sse = "event: message\r\ndata: {\"jsonrpc\":\"2.0\",\"method\":\"notifications/progress\"}\r\n\r\n" ++
+        "event: message\r\ndata: {\"jsonrpc\":\"2.0\",\"id\":8,\"result\":{\"tools\":[]}}\r\n\r\n";
+    const event = parseHttpResponse(a, sse, 8).?;
+    try std.testing.expectEqual(@as(i64, 8), event.object.get("id").?.integer);
+    try std.testing.expect(parseHttpResponse(a, sse, 9) == null);
+}
diff --git a/src/mcp_oauth.zig b/src/mcp_oauth.zig
new file mode 100644
index 00000000..cda0d787
--- /dev/null
+++ b/src/mcp_oauth.zig
@@ -0,0 +1,552 @@
+//! OAuth 2.1 support for remote MCP servers.  This is deliberately a leaf
+//! module: callers supply all allocators, I/O, and the user's home directory.
+
+const std = @import("std");
+const builtin = @import("builtin");
+const util = @import("util.zig");
+const discovery = @import("mcp_oauth_discovery.zig");
+
+const Io = std.Io;
+const Allocator = std.mem.Allocator;
+const Value = std.json.Value;
+const max_response = 1024 * 1024;
+const redirect_uri = "http://127.0.0.1:1456/callback";
+const smolify_resource = "https://app.smol.ly/mcp";
+const smolify_read_scopes = "profile email offline_access projects:read docs:read";
+
+const EndpointSet = struct {
+    issuer: []const u8,
+    authorization: []const u8,
+    token: []const u8,
+    registration: []const u8,
+    scope: []const u8 = "",
+};
+
+const ClientInfo = struct {
+    id: []const u8,
+    secret: []const u8 = "",
+};
+
+const TokenSet = struct {
+    access: []const u8,
+    refresh: []const u8 = "",
+    expires_at_ms: i64,
+};
+
+const requireHttps = discovery.requireHttps;
+
+fn writePercentEncoded(w: *Io.Writer, value: []const u8) !void {
+    const hex = "0123456789ABCDEF";
+    for (value) |c| {
+        if (std.ascii.isAlphanumeric(c) or c == '-' or c == '.' or c == '_' or c == '~') {
+            try w.writeByte(c);
+        } else {
+            try w.writeAll(&.{ '%', hex[c >> 4], hex[c & 15] });
+        }
+    }
+}
+
+fn formEncode(arena: Allocator, fields: []const struct { []const u8, []const u8 }) ![]const u8 {
+    var aw: Io.Writer.Allocating = .init(arena);
+    for (fields, 0..) |field, i| {
+        if (i != 0) try aw.writer.writeByte('&');
+        try writePercentEncoded(&aw.writer, field[0]);
+        try aw.writer.writeByte('=');
+        try writePercentEncoded(&aw.writer, field[1]);
+    }
+    return aw.writer.buffered();
+}
+
+fn jsonObject(body: []const u8, arena: Allocator) !std.json.ObjectMap {
+    const v = try std.json.parseFromSliceLeaky(Value, arena, body, .{ .allocate = .alloc_always });
+    if (v != .object) return error.BadOAuthResponse;
+    return v.object;
+}
+
+fn stringField(obj: std.json.ObjectMap, name: []const u8) ?[]const u8 {
+    const v = obj.get(name) orelse return null;
+    return if (v == .string) v.string else null;
+}
+
+fn integerField(obj: std.json.ObjectMap, name: []const u8) ?i64 {
+    const v = obj.get(name) orelse return null;
+    return if (v == .integer) v.integer else null;
+}
+
+fn supportedScopes(arena: Allocator, metadata: std.json.ObjectMap) ![]const u8 {
+    const scopes = metadata.get("scopes_supported") orelse return "";
+    if (scopes != .array) return error.BadOAuthResponse;
+    var aw: Io.Writer.Allocating = .init(arena);
+    for (scopes.array.items) |scope| {
+        if (scope != .string) return error.BadOAuthResponse;
+        if (aw.writer.buffered().len != 0) try aw.writer.writeByte(' ');
+        try aw.writer.writeAll(scope.string);
+    }
+    return aw.writer.buffered();
+}
+
+fn fetchJson(io: Io, gpa: Allocator, arena: Allocator, url: []const u8) !std.json.ObjectMap {
+    try requireHttps(url);
+    var client: std.http.Client = .{ .allocator = gpa, .io = io };
+    defer client.deinit();
+    const storage = try arena.alloc(u8, max_response);
+    var writer: Io.Writer = .fixed(storage);
+    const headers = [_]std.http.Header{.{ .name = "Accept", .value = "application/json" }};
+    const res = try client.fetch(.{
+        .location = .{ .url = url },
+        .method = .GET,
+        .response_writer = &writer,
+        .redirect_behavior = .not_allowed,
+        .extra_headers = &headers,
+    });
+    if (@intFromEnum(res.status) < 200 or @intFromEnum(res.status) >= 300) return error.OAuthHttpFailure;
+    return jsonObject(writer.buffered(), arena);
+}
+
+fn postJson(io: Io, gpa: Allocator, arena: Allocator, url: []const u8, payload: []const u8) !std.json.ObjectMap {
+    try requireHttps(url);
+    var client: std.http.Client = .{ .allocator = gpa, .io = io };
+    defer client.deinit();
+    const storage = try arena.alloc(u8, max_response);
+    var writer: Io.Writer = .fixed(storage);
+    const headers = [_]std.http.Header{.{ .name = "Accept", .value = "application/json" }};
+    const res = try client.fetch(.{
+        .location = .{ .url = url },
+        .method = .POST,
+        .payload = payload,
+        .response_writer = &writer,
+        .redirect_behavior = .not_allowed,
+        .headers = .{ .content_type = .{ .override = "application/json" } },
+        .extra_headers = &headers,
+    });
+    if (@intFromEnum(res.status) < 200 or @intFromEnum(res.status) >= 300) return error.OAuthHttpFailure;
+    return jsonObject(writer.buffered(), arena);
+}
+
+fn postForm(io: Io, gpa: Allocator, arena: Allocator, url: []const u8, payload: []const u8) !std.json.ObjectMap {
+    try requireHttps(url);
+    var client: std.http.Client = .{ .allocator = gpa, .io = io };
+    defer client.deinit();
+    const storage = try arena.alloc(u8, max_response);
+    var writer: Io.Writer = .fixed(storage);
+    const headers = [_]std.http.Header{.{ .name = "Accept", .value = "application/json" }};
+    const res = try client.fetch(.{
+        .location = .{ .url = url },
+        .method = .POST,
+        .payload = payload,
+        .response_writer = &writer,
+        .redirect_behavior = .not_allowed,
+        .headers = .{ .content_type = .{ .override = "application/x-www-form-urlencoded" } },
+        .extra_headers = &headers,
+    });
+    if (@intFromEnum(res.status) < 200 or @intFromEnum(res.status) >= 300) return error.OAuthHttpFailure;
+    return jsonObject(writer.buffered(), arena);
+}
+
+fn authorizationEndpoints(io: Io, gpa: Allocator, arena: Allocator, issuer: []const u8, metadata_url: []const u8) !EndpointSet {
+    const metadata = try fetchJson(io, gpa, arena, metadata_url);
+    const advertised_issuer = stringField(metadata, "issuer") orelse return error.AuthorizationServerMismatch;
+    if (!std.mem.eql(u8, advertised_issuer, issuer)) return error.AuthorizationServerMismatch;
+    if (!discovery.supportsS256(metadata)) return error.PkceS256Unsupported;
+
+    const authorization = stringField(metadata, "authorization_endpoint") orelse return error.BadOAuthResponse;
+    const token = stringField(metadata, "token_endpoint") orelse return error.BadOAuthResponse;
+    const registration = stringField(metadata, "registration_endpoint") orelse return error.DynamicRegistrationUnsupported;
+    try requireHttps(authorization);
+    try requireHttps(token);
+    try requireHttps(registration);
+    return .{
+        .issuer = issuer,
+        .authorization = authorization,
+        .token = token,
+        .registration = registration,
+        .scope = try supportedScopes(arena, metadata),
+    };
+}
+
+fn discover(io: Io, gpa: Allocator, arena: Allocator, resource_url: []const u8) !EndpointSet {
+    // RFC 9728 challenges are authoritative hints and must be obtained before
+    // attempting either protected-resource well-known location.
+    const challenge = try discovery.probe(io, gpa, arena, resource_url);
+    const resource_metadata = if (challenge.resource_metadata) |url|
+        try fetchJson(io, gpa, arena, url)
+    else
+        fetchJson(io, gpa, arena, try discovery.protectedMetadataUrl(arena, resource_url)) catch
+            try fetchJson(io, gpa, arena, try discovery.rootProtectedMetadataUrl(arena, resource_url));
+    const advertised_resource = stringField(resource_metadata, "resource") orelse return error.ResourceMetadataMismatch;
+    if (!std.mem.eql(u8, advertised_resource, resource_url)) return error.ResourceMetadataMismatch;
+
+    const servers = resource_metadata.get("authorization_servers") orelse return error.MissingAuthorizationServer;
+    if (servers != .array or servers.array.items.len == 0) return error.MissingAuthorizationServer;
+    var issuer: ?[]const u8 = null;
+    for (servers.array.items) |server| {
+        if (server != .string) continue;
+        requireHttps(server.string) catch continue;
+        issuer = server.string;
+        break;
+    }
+    const selected = issuer orelse return error.InsecureOAuthEndpoint;
+
+    var endpoints = authorizationEndpoints(io, gpa, arena, selected, try discovery.authorizationMetadataUrl(arena, selected)) catch
+        authorizationEndpoints(io, gpa, arena, selected, try discovery.oidcInsertedMetadataUrl(arena, selected)) catch
+        try authorizationEndpoints(io, gpa, arena, selected, try discovery.oidcAppendedMetadataUrl(arena, selected));
+    var scope = discovery.preferredScope(
+        challenge.scope,
+        try supportedScopes(arena, resource_metadata),
+        endpoints.scope,
+    );
+    // Core Smolify remains read-only. An explicit challenge is authoritative,
+    // but fail closed if it requests permissions outside the pinned allowlist.
+    if (std.mem.eql(u8, resource_url, smolify_resource)) {
+        if (challenge.scope) |challenged| {
+            if (challenged.len == 0) {
+                scope = smolify_read_scopes;
+            } else if (!discovery.scopeSubsetOf(challenged, smolify_read_scopes)) {
+                return error.SmolifyScopeNotReadOnly;
+            }
+        } else {
+            scope = smolify_read_scopes;
+        }
+    }
+    endpoints.scope = scope;
+    return endpoints;
+}
+
+fn registerClient(io: Io, gpa: Allocator, arena: Allocator, endpoint: []const u8, server_name: []const u8) !ClientInfo {
+    var obj: std.json.ObjectMap = .empty;
+    try obj.put(arena, "client_name", .{ .string = server_name });
+    try obj.put(arena, "token_endpoint_auth_method", .{ .string = "none" });
+    var redirects = std.json.Array.init(arena);
+    try redirects.append(.{ .string = redirect_uri });
+    try obj.put(arena, "redirect_uris", .{ .array = redirects });
+    var grants = std.json.Array.init(arena);
+    try grants.append(.{ .string = "authorization_code" });
+    try grants.append(.{ .string = "refresh_token" });
+    try obj.put(arena, "grant_types", .{ .array = grants });
+    var responses = std.json.Array.init(arena);
+    try responses.append(.{ .string = "code" });
+    try obj.put(arena, "response_types", .{ .array = responses });
+    var aw: Io.Writer.Allocating = .init(arena);
+    var stringify: std.json.Stringify = .{ .writer = &aw.writer };
+    try stringify.write(Value{ .object = obj });
+    const response = try postJson(io, gpa, arena, endpoint, aw.writer.buffered());
+    return .{
+        .id = stringField(response, "client_id") orelse return error.BadOAuthResponse,
+        .secret = stringField(response, "client_secret") orelse "",
+    };
+}
+
+fn b64url(arena: Allocator, bytes: []const u8) ![]const u8 {
+    const encoder = std.base64.url_safe_no_pad.Encoder;
+    const result = try arena.alloc(u8, encoder.calcSize(bytes.len));
+    return encoder.encode(result, bytes);
+}
+
+fn openBrowser(io: Io, url: []const u8) void {
+    const argv: []const []const u8 = if (builtin.os.tag == .macos)
+        &.{ "open", url }
+    else if (builtin.os.tag == .windows)
+        // Avoid cmd.exe: OAuth URLs contain '&', and passing discovered URLs
+        // through a shell would both truncate them and permit injection.
+        &.{ "rundll32.exe", "url.dll,FileProtocolHandler", url }
+    else
+        &.{ "xdg-open", url };
+    var child = std.process.spawn(io, .{ .argv = argv, .stdin = .ignore, .stdout = .ignore, .stderr = .ignore }) catch return;
+    _ = child.wait(io) catch {};
+}
+
+fn hexNibble(c: u8) ?u8 {
+    return switch (c) {
+        '0'...'9' => c - '0',
+        'a'...'f' => c - 'a' + 10,
+        'A'...'F' => c - 'A' + 10,
+        else => null,
+    };
+}
+
+fn percentDecode(arena: Allocator, encoded: []const u8) ![]const u8 {
+    const out = try arena.alloc(u8, encoded.len);
+    var src: usize = 0;
+    var dst: usize = 0;
+    while (src < encoded.len) {
+        if (encoded[src] == '%') {
+            if (src + 2 >= encoded.len) return error.BadOAuthResponse;
+            const hi = hexNibble(encoded[src + 1]) orelse return error.BadOAuthResponse;
+            const lo = hexNibble(encoded[src + 2]) orelse return error.BadOAuthResponse;
+            out[dst] = (hi << 4) | lo;
+            src += 3;
+        } else {
+            out[dst] = if (encoded[src] == '+') ' ' else encoded[src];
+            src += 1;
+        }
+        dst += 1;
+    }
+    return out[0..dst];
+}
+
+fn queryParam(arena: Allocator, request_line: []const u8, name: []const u8) !?[]const u8 {
+    const target_start = std.mem.indexOfScalar(u8, request_line, ' ') orelse return error.BadOAuthResponse;
+    const target_tail = request_line[target_start + 1 ..];
+    const target_end = std.mem.indexOfScalar(u8, target_tail, ' ') orelse return error.BadOAuthResponse;
+    const target = target_tail[0..target_end];
+    const qmark = std.mem.indexOfScalar(u8, target, '?') orelse return null;
+    var pairs = std.mem.splitScalar(u8, target[qmark + 1 ..], '&');
+    while (pairs.next()) |pair| {
+        const equal = std.mem.indexOfScalar(u8, pair, '=') orelse continue;
+        if (std.mem.eql(u8, pair[0..equal], name)) return try percentDecode(arena, pair[equal + 1 ..]);
+    }
+    return null;
+}
+
+fn tokenFromResponse(obj: std.json.ObjectMap, io: Io) !TokenSet {
+    const access = stringField(obj, "access_token") orelse return error.BadOAuthResponse;
+    const now = util.unixMs(io);
+    const expires_at = if (integerField(obj, "expires_in")) |expires_in|
+        if (expires_in <= 0)
+            now
+        else if (expires_in > @divTrunc(std.math.maxInt(i64) - now, 1000))
+            std.math.maxInt(i64)
+        else
+            now + expires_in * 1000
+    else
+        std.math.maxInt(i64);
+    return .{
+        .access = access,
+        .refresh = stringField(obj, "refresh_token") orelse "",
+        .expires_at_ms = expires_at,
+    };
+}
+
+fn credentialPath(arena: Allocator, home: []const u8, resource_url: []const u8) ![]const u8 {
+    var digest: [32]u8 = undefined;
+    std.crypto.hash.sha2.Sha256.hash(resource_url, &digest, .{});
+    const hex = std.fmt.bytesToHex(digest, .lower);
+    return std.fmt.allocPrint(arena, "{s}/.simple-harness-mcp/{s}.json", .{ home, &hex });
+}
+
+fn secureWindowsCredentials(io: Io, dir: []const u8, path: []const u8) !void {
+    // Zig 0.16 does not implement chmod on Windows. Remove inherited ACLs and
+    // grant full control only to the file owner, using a fixed SID and a
+    // hash-only basename so no shell or user-controlled command text is used.
+    const argv: []const []const u8 = &.{
+        "icacls.exe",
+        std.fs.path.basename(path),
+        "/inheritance:r",
+        "/grant:r",
+        "*S-1-3-4:F",
+    };
+    var child = try std.process.spawn(io, .{
+        .argv = argv,
+        .cwd = .{ .path = dir },
+        .stdin = .ignore,
+        .stdout = .ignore,
+        .stderr = .ignore,
+    });
+    const term = try child.wait(io);
+    if (term != .exited or term.exited != 0) return error.CredentialPermissionsFailed;
+}
+
+fn writeCredentials(io: Io, arena: Allocator, home: []const u8, resource_url: []const u8, endpoints: EndpointSet, client: ClientInfo, tokens: TokenSet) !void {
+    const dir = try std.fmt.allocPrint(arena, "{s}/.simple-harness-mcp", .{home});
+    Io.Dir.cwd().createDir(io, dir, .default_dir) catch |err| switch (err) {
+        error.PathAlreadyExists => {},
+        else => return err,
+    };
+    const path = try credentialPath(arena, home, resource_url);
+    var obj: std.json.ObjectMap = .empty;
+    try obj.put(arena, "resource", .{ .string = resource_url });
+    try obj.put(arena, "issuer", .{ .string = endpoints.issuer });
+    try obj.put(arena, "authorization_endpoint", .{ .string = endpoints.authorization });
+    try obj.put(arena, "token_endpoint", .{ .string = endpoints.token });
+    try obj.put(arena, "registration_endpoint", .{ .string = endpoints.registration });
+    try obj.put(arena, "scope", .{ .string = endpoints.scope });
+    try obj.put(arena, "client_id", .{ .string = client.id });
+    try obj.put(arena, "client_secret", .{ .string = client.secret });
+    try obj.put(arena, "access_token", .{ .string = tokens.access });
+    try obj.put(arena, "refresh_token", .{ .string = tokens.refresh });
+    try obj.put(arena, "expires_at_ms", .{ .integer = tokens.expires_at_ms });
+    var aw: Io.Writer.Allocating = .init(arena);
+    var stringify: std.json.Stringify = .{ .writer = &aw.writer };
+    try stringify.write(Value{ .object = obj });
+    const user_only: Io.Dir.Permissions = @enumFromInt(0o600);
+    {
+        const file = try Io.Dir.cwd().createFile(io, path, .{ .permissions = user_only });
+        defer file.close(io);
+        var buffer: [4096]u8 = undefined;
+        var fw = file.writer(io, &buffer);
+        try fw.interface.writeAll(aw.writer.buffered());
+        try fw.interface.flush();
+    }
+    if (builtin.os.tag == .windows)
+        try secureWindowsCredentials(io, dir, path)
+    else
+        try Io.Dir.cwd().setFilePermissions(io, path, user_only, .{});
+}
+
+fn loginInner(io: Io, gpa: Allocator, arena: Allocator, home: []const u8, server_name: []const u8, resource_url: []const u8, out: *Io.Writer) !void {
+    try requireHttps(resource_url);
+    try out.print("Discovering OAuth configuration for {s}…\n", .{resource_url});
+    try out.flush();
+    const endpoints = try discover(io, gpa, arena, resource_url);
+    try out.print("Registering {s} with {s}…\n", .{ server_name, endpoints.issuer });
+    try out.flush();
+    const client = try registerClient(io, gpa, arena, endpoints.registration, server_name);
+
+    var verifier_bytes: [48]u8 = undefined;
+    io.random(&verifier_bytes);
+    const verifier = try b64url(arena, &verifier_bytes);
+    var challenge_bytes: [32]u8 = undefined;
+    std.crypto.hash.sha2.Sha256.hash(verifier, &challenge_bytes, .{});
+    const challenge = try b64url(arena, &challenge_bytes);
+    var state_bytes: [24]u8 = undefined;
+    io.random(&state_bytes);
+    const state = try b64url(arena, &state_bytes);
+
+    var authorization_fields: std.ArrayList(struct { []const u8, []const u8 }) = .empty;
+    try authorization_fields.append(arena, .{ "response_type", "code" });
+    try authorization_fields.append(arena, .{ "client_id", client.id });
+    try authorization_fields.append(arena, .{ "redirect_uri", redirect_uri });
+    try authorization_fields.append(arena, .{ "code_challenge", challenge });
+    try authorization_fields.append(arena, .{ "code_challenge_method", "S256" });
+    try authorization_fields.append(arena, .{ "state", state });
+    if (endpoints.scope.len != 0) try authorization_fields.append(arena, .{ "scope", endpoints.scope });
+    try authorization_fields.append(arena, .{ "resource", resource_url });
+    const query = try formEncode(arena, authorization_fields.items);
+    const authorization_url = try std.fmt.allocPrint(arena, "{s}{c}{s}", .{
+        endpoints.authorization,
+        @as(u8, if (std.mem.indexOfScalar(u8, endpoints.authorization, '?') == null) '?' else '&'),
+        query,
+    });
+
+    var address = std.Io.net.IpAddress.parseLiteral("127.0.0.1:1456") catch return error.BadOAuthResponse;
+    var listener = try std.Io.net.IpAddress.listen(&address, io, .{});
+    defer listener.deinit(io);
+    try out.print("\nOpen this URL to authorize (the browser should open automatically):\n\n{s}\n\nWaiting for the callback on {s} …\n", .{ authorization_url, redirect_uri });
+    try out.flush();
+    openBrowser(io, authorization_url);
+
+    const stream = try listener.accept(io);
+    defer stream.close(io);
+    var read_buffer: [16 * 1024]u8 = undefined;
+    var reader = std.Io.net.Stream.Reader.init(stream, io, &read_buffer);
+    const request_line = (reader.interface.takeDelimiter('\n') catch null) orelse return error.BadOAuthResponse;
+    const code = try queryParam(arena, request_line, "code") orelse {
+        const description = try queryParam(arena, request_line, "error_description") orelse
+            try queryParam(arena, request_line, "error") orelse "authorization server returned no code";
+        try out.print("OAuth authorization failed: {s}\n", .{description});
+        try out.flush();
+        return error.AuthorizationDenied;
+    };
+    const returned_state = try queryParam(arena, request_line, "state") orelse return error.StateMismatch;
+
+    var write_buffer: [2048]u8 = undefined;
+    var stream_writer = std.Io.net.Stream.Writer.init(stream, io, &write_buffer);
+    if (!std.mem.eql(u8, state, returned_state)) {
+        try stream_writer.interface.writeAll("HTTP/1.1 400 Bad Request\r\nContent-Type: text/plain\r\nConnection: close\r\n\r\nOAuth state mismatch. Return to the CLI and try again.\n");
+        try stream_writer.interface.flush();
+        return error.StateMismatch;
+    }
+    try stream_writer.interface.writeAll("HTTP/1.1 200 OK\r\nContent-Type: text/plain; charset=utf-8\r\nConnection: close\r\n\r\nMCP authorization complete. You can close this tab.\n");
+    try stream_writer.interface.flush();
+
+    var fields = [_]struct { []const u8, []const u8 }{
+        .{ "grant_type", "authorization_code" },
+        .{ "client_id", client.id },
+        .{ "code", code },
+        .{ "redirect_uri", redirect_uri },
+        .{ "code_verifier", verifier },
+        .{ "resource", resource_url },
+        .{ "client_secret", client.secret },
+    };
+    const field_count: usize = if (client.secret.len == 0) fields.len - 1 else fields.len;
+    const response = try postForm(io, gpa, arena, endpoints.token, try formEncode(arena, fields[0..field_count]));
+    const tokens = try tokenFromResponse(response, io);
+    try writeCredentials(io, arena, home, resource_url, endpoints, client, tokens);
+    try out.print("✓ {s} authorized; credentials saved to {s}\n", .{ server_name, try credentialPath(arena, home, resource_url) });
+    try out.flush();
+}
+
+/// Discover, register, and run an OAuth 2.1 authorization-code + PKCE flow for
+/// an MCP protected resource, then persist the resulting credentials.
+pub fn login(io: Io, gpa: Allocator, arena: Allocator, home: []const u8, server_name: []const u8, resource_url: []const u8) !void {
+    if (home.len == 0) return error.HomeDirectoryUnavailable;
+    var buffer: [4096]u8 = undefined;
+    var stdout = Io.File.stdout().writer(io, &buffer);
+    loginInner(io, gpa, arena, home, server_name, resource_url, &stdout.interface) catch |err| {
+        try stdout.interface.print("✗ MCP OAuth login failed: {t}. Check the server URL and authorization-server metadata, then try again.\n", .{err});
+        try stdout.interface.flush();
+        return err;
+    };
+}
+
+/// Load a resource's persisted access token.  Tokens within one minute of
+/// expiry are refreshed first; any malformed, insecure, or failed credential
+/// set is treated as unavailable.
+pub fn loadAccessToken(io: Io, gpa: Allocator, arena: Allocator, home: []const u8, resource_url: []const u8) ?[]const u8 {
+    if (home.len == 0) return null;
+    requireHttps(resource_url) catch return null;
+    const path = credentialPath(arena, home, resource_url) catch return null;
+    const data = Io.Dir.cwd().readFileAlloc(io, path, arena, .limited(max_response)) catch return null;
+    const obj = jsonObject(data, arena) catch return null;
+    const stored_resource = stringField(obj, "resource") orelse return null;
+    if (!std.mem.eql(u8, stored_resource, resource_url)) return null;
+    const access = stringField(obj, "access_token") orelse return null;
+    const expires_at = integerField(obj, "expires_at_ms") orelse return null;
+    if (expires_at > util.unixMs(io) + 60_000) return access;
+
+    const refresh = stringField(obj, "refresh_token") orelse return null;
+    if (refresh.len == 0) return null;
+    const token_endpoint = stringField(obj, "token_endpoint") orelse return null;
+    requireHttps(token_endpoint) catch return null;
+    const client = ClientInfo{
+        .id = stringField(obj, "client_id") orelse return null,
+        .secret = stringField(obj, "client_secret") orelse "",
+    };
+    const fields = [_]struct { []const u8, []const u8 }{
+        .{ "grant_type", "refresh_token" },
+        .{ "client_id", client.id },
+        .{ "refresh_token", refresh },
+        .{ "resource", resource_url },
+        .{ "client_secret", client.secret },
+    };
+    const field_count: usize = if (client.secret.len == 0) fields.len - 1 else fields.len;
+    const response = postForm(io, gpa, arena, token_endpoint, formEncode(arena, fields[0..field_count]) catch return null) catch return null;
+    var tokens = tokenFromResponse(response, io) catch return null;
+    if (tokens.refresh.len == 0) tokens.refresh = refresh;
+    const endpoints = EndpointSet{
+        .issuer = stringField(obj, "issuer") orelse return null,
+        .authorization = stringField(obj, "authorization_endpoint") orelse return null,
+        .token = token_endpoint,
+        .registration = stringField(obj, "registration_endpoint") orelse return null,
+        .scope = stringField(obj, "scope") orelse "",
+    };
+    writeCredentials(io, arena, home, resource_url, endpoints, client, tokens) catch return null;
+    return tokens.access;
+}
+
+test "form encoding uses RFC 3986 percent encoding" {
+    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+    defer arena_state.deinit();
+    const encoded = try formEncode(arena_state.allocator(), &.{
+        .{ "plain", "AZaz09-._~" },
+        .{ "space + slash", "a b+c/d" },
+    });
+    try std.testing.expectEqualStrings("plain=AZaz09-._~&space%20%2B%20slash=a%20b%2Bc%2Fd", encoded);
+}
+
+test "supported scopes are joined for authorization requests" {
+    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+    defer arena_state.deinit();
+    const arena = arena_state.allocator();
+    const metadata = try jsonObject("{\"scopes_supported\":[\"openid\",\"docs:read\",\"offline_access\"]}", arena);
+    try std.testing.expectEqualStrings("openid docs:read offline_access", try supportedScopes(arena, metadata));
+}
+
+test "credential path is stable and resource-specific" {
+    const path = try credentialPath(std.testing.allocator, "/home/alice", "https://mcp.example/api");
+    defer std.testing.allocator.free(path);
+    try std.testing.expectEqualStrings(
+        "/home/alice/.simple-harness-mcp/d48481de503249e9a60247e669c522a432c2685e9af626d9d7e15794ab8f092e.json",
+        path,
+    );
+}
diff --git a/src/mcp_oauth_discovery.zig b/src/mcp_oauth_discovery.zig
new file mode 100644
index 00000000..ef2a5ab7
--- /dev/null
+++ b/src/mcp_oauth_discovery.zig
@@ -0,0 +1,281 @@
+const std = @import("std");
+
+const Io = std.Io;
+const Allocator = std.mem.Allocator;
+const mcp_protocol = @import("mcp_protocol.zig");
+
+pub const Challenge = struct {
+    resource_metadata: ?[]const u8 = null,
+    scope: ?[]const u8 = null,
+};
+
+pub fn requireHttps(url: []const u8) !void {
+    const uri = std.Uri.parse(url) catch return error.InvalidOAuthUrl;
+    if (!std.ascii.eqlIgnoreCase(uri.scheme, "https")) return error.InsecureOAuthEndpoint;
+    if (uri.host == null or uri.user != null or uri.password != null or uri.fragment != null)
+        return error.InvalidOAuthUrl;
+}
+
+fn splitOrigin(url: []const u8) !struct { origin: []const u8, path: []const u8 } {
+    try requireHttps(url);
+    const authority_start = "https://".len;
+    var authority_end = url.len;
+    for (url[authority_start..], authority_start..) |c, i| {
+        if (c == '/' or c == '?' or c == '#') {
+            authority_end = i;
+            break;
+        }
+    }
+    if (authority_end == authority_start) return error.InvalidOAuthUrl;
+    const tail = url[authority_end..];
+    const path_end = std.mem.indexOfAny(u8, tail, "?#") orelse tail.len;
+    const path = if (path_end == 0 or tail[0] != '/') "/" else tail[0..path_end];
+    return .{ .origin = url[0..authority_end], .path = path };
+}
+
+/// RFC 9728 section 3.1: insert the well-known name between the origin and the
+/// protected resource's path.
+pub fn protectedMetadataUrl(arena: Allocator, resource_url: []const u8) ![]const u8 {
+    const p = try splitOrigin(resource_url);
+    return std.fmt.allocPrint(arena, "{s}/.well-known/oauth-protected-resource{s}", .{
+        p.origin,
+        if (std.mem.eql(u8, p.path, "/")) "" else p.path,
+    });
+}
+
+pub fn rootProtectedMetadataUrl(arena: Allocator, resource_url: []const u8) ![]const u8 {
+    const p = try splitOrigin(resource_url);
+    return std.fmt.allocPrint(arena, "{s}/.well-known/oauth-protected-resource", .{p.origin});
+}
+
+/// RFC 8414 section 3: issuer paths follow the well-known component.
+pub fn authorizationMetadataUrl(arena: Allocator, issuer: []const u8) ![]const u8 {
+    const p = try splitOrigin(issuer);
+    return std.fmt.allocPrint(arena, "{s}/.well-known/oauth-authorization-server{s}", .{
+        p.origin,
+        if (std.mem.eql(u8, p.path, "/")) "" else p.path,
+    });
+}
+
+pub fn oidcInsertedMetadataUrl(arena: Allocator, issuer: []const u8) ![]const u8 {
+    const p = try splitOrigin(issuer);
+    return std.fmt.allocPrint(arena, "{s}/.well-known/openid-configuration{s}", .{
+        p.origin,
+        if (std.mem.eql(u8, p.path, "/")) "" else p.path,
+    });
+}
+
+pub fn oidcAppendedMetadataUrl(arena: Allocator, issuer: []const u8) ![]const u8 {
+    try requireHttps(issuer);
+    return std.fmt.allocPrint(arena, "{s}/.well-known/openid-configuration", .{std.mem.trimEnd(u8, issuer, "/")});
+}
+
+fn skipOws(value: []const u8, pos: *usize) void {
+    while (pos.* < value.len and (value[pos.*] == ' ' or value[pos.*] == '\t')) pos.* += 1;
+}
+
+fn tokenEnd(value: []const u8, start: usize) usize {
+    var end = start;
+    while (end < value.len and std.ascii.isAlphanumeric(value[end]) or
+        (end < value.len and std.mem.indexOfScalar(u8, "!#$%&'*+-.^_`|~", value[end]) != null)) end += 1;
+    return end;
+}
+
+fn parseValue(arena: Allocator, value: []const u8, pos: *usize) !?[]const u8 {
+    if (pos.* >= value.len) return null;
+    if (value[pos.*] != '"') {
+        const end = tokenEnd(value, pos.*);
+        if (end == pos.*) return null;
+        const result = value[pos.*..end];
+        pos.* = end;
+        return result;
+    }
+    pos.* += 1;
+    var result: std.ArrayList(u8) = .empty;
+    while (pos.* < value.len) {
+        const c = value[pos.*];
+        pos.* += 1;
+        if (c == '"') return try result.toOwnedSlice(arena);
+        if (c == '\\') {
+            if (pos.* >= value.len) return error.InvalidAuthenticationChallenge;
+            try result.append(arena, value[pos.*]);
+            pos.* += 1;
+        } else {
+            if (c == '\r' or c == '\n') return error.InvalidAuthenticationChallenge;
+            try result.append(arena, c);
+        }
+    }
+    return error.InvalidAuthenticationChallenge;
+}
+
+/// Parse a WWW-Authenticate field value, including multiple challenges and
+/// quoted-string escaping, and return the first Bearer challenge with MCP params.
+pub fn parseChallenge(arena: Allocator, value: []const u8) !Challenge {
+    var pos: usize = 0;
+    while (pos < value.len) {
+        skipOws(value, &pos);
+        while (pos < value.len and value[pos] == ',') {
+            pos += 1;
+            skipOws(value, &pos);
+        }
+        const scheme_end = tokenEnd(value, pos);
+        if (scheme_end == pos) break;
+        const bearer = std.ascii.eqlIgnoreCase(value[pos..scheme_end], "Bearer");
+        pos = scheme_end;
+        var found: Challenge = .{};
+        while (pos < value.len) {
+            skipOws(value, &pos);
+            if (pos >= value.len) break;
+            if (value[pos] == ',') {
+                pos += 1;
+                skipOws(value, &pos);
+            }
+            const name_start = pos;
+            const name_end = tokenEnd(value, pos);
+            if (name_end == pos) break;
+            pos = name_end;
+            skipOws(value, &pos);
+            if (pos >= value.len or value[pos] != '=') {
+                pos = name_start;
+                break;
+            }
+            pos += 1;
+            skipOws(value, &pos);
+            const param_value = (try parseValue(arena, value, &pos)) orelse break;
+            if (bearer and std.ascii.eqlIgnoreCase(value[name_start..name_end], "resource_metadata"))
+                found.resource_metadata = param_value;
+            if (bearer and std.ascii.eqlIgnoreCase(value[name_start..name_end], "scope"))
+                found.scope = param_value;
+        }
+        if (bearer and (found.resource_metadata != null or found.scope != null)) return found;
+    }
+    return .{};
+}
+
+pub fn probe(io: Io, gpa: Allocator, arena: Allocator, resource_url: []const u8) !Challenge {
+    try requireHttps(resource_url);
+    var client: std.http.Client = .{ .allocator = gpa, .io = io };
+    defer client.deinit();
+    const body =
+        \\{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"
+    ++ mcp_protocol.latest_protocol ++
+        \\","capabilities":{},"clientInfo":{"name":"codegraff-mcp-login","version":"1"}}}
+    ;
+    const extra_headers = [_]std.http.Header{
+        .{ .name = "accept", .value = "application/json, text/event-stream" },
+        .{ .name = "mcp-protocol-version", .value = mcp_protocol.latest_protocol },
+    };
+    var request = try client.request(.POST, try std.Uri.parse(resource_url), .{
+        .redirect_behavior = .unhandled,
+        .headers = .{
+            .content_type = .{ .override = "application/json" },
+            .accept_encoding = .omit,
+            .user_agent = .{ .override = "codegraff-mcp/1" },
+        },
+        .extra_headers = &extra_headers,
+    });
+    defer request.deinit();
+    errdefer {
+        if (request.connection) |connection| connection.closing = true;
+    }
+    request.transfer_encoding = .{ .content_length = body.len };
+    var body_writer = try request.sendBodyUnflushed(&.{});
+    try body_writer.writer.writeAll(body);
+    try body_writer.end();
+    try request.connection.?.flush();
+    const response = try request.receiveHead(&.{});
+    if (request.connection) |connection| connection.closing = true;
+
+    var challenge: Challenge = .{};
+    var headers = response.head.iterateHeaders();
+    while (headers.next()) |header| {
+        if (!std.ascii.eqlIgnoreCase(header.name, "WWW-Authenticate")) continue;
+        const parsed = try parseChallenge(arena, header.value);
+        if (challenge.resource_metadata == null) challenge.resource_metadata = parsed.resource_metadata;
+        if (challenge.scope == null) challenge.scope = parsed.scope;
+    }
+    return challenge;
+}
+
+pub fn preferredScope(challenge: ?[]const u8, resource: []const u8, authorization_server: []const u8) []const u8 {
+    if (challenge) |scope| if (scope.len != 0) return scope;
+    if (resource.len != 0) return resource;
+    return authorization_server;
+}
+
+pub fn scopeSubsetOf(scope: []const u8, allowed: []const u8) bool {
+    var requested = std.mem.tokenizeScalar(u8, scope, ' ');
+    while (requested.next()) |item| {
+        var candidates = std.mem.tokenizeScalar(u8, allowed, ' ');
+        while (candidates.next()) |candidate| {
+            if (std.mem.eql(u8, item, candidate)) break;
+        } else return false;
+    }
+    return true;
+}
+
+pub fn supportsS256(metadata: std.json.ObjectMap) bool {
+    const methods = metadata.get("code_challenge_methods_supported") orelse return false;
+    if (methods != .array) return false;
+    for (methods.array.items) |method|
+        if (method == .string and std.mem.eql(u8, method.string, "S256")) return true;
+    return false;
+}
+
+test "OAuth URLs require a parsed HTTPS URI without userinfo or fragments" {
+    try requireHttps("HTTPS://login.example/token?audience=mcp");
+    try std.testing.expectError(error.InsecureOAuthEndpoint, requireHttps("http://login.example/token"));
+    try std.testing.expectError(error.InvalidOAuthUrl, requireHttps("https://user@login.example/token"));
+    try std.testing.expectError(error.InvalidOAuthUrl, requireHttps("https://login.example/token#fragment"));
+    try std.testing.expectError(error.InvalidOAuthUrl, requireHttps("https:///missing-host"));
+}
+
+test "metadata URL construction covers RFC and OIDC issuer paths" {
+    const allocator = std.testing.allocator;
+    const protected = try protectedMetadataUrl(allocator, "https://mcp.example:8443/a/b?x=1");
+    defer allocator.free(protected);
+    try std.testing.expectEqualStrings("https://mcp.example:8443/.well-known/oauth-protected-resource/a/b", protected);
+    const root = try rootProtectedMetadataUrl(allocator, "https://mcp.example:8443/a/b");
+    defer allocator.free(root);
+    try std.testing.expectEqualStrings("https://mcp.example:8443/.well-known/oauth-protected-resource", root);
+    const rfc = try authorizationMetadataUrl(allocator, "https://login.example/tenant");
+    defer allocator.free(rfc);
+    try std.testing.expectEqualStrings("https://login.example/.well-known/oauth-authorization-server/tenant", rfc);
+    const inserted = try oidcInsertedMetadataUrl(allocator, "https://login.example/tenant");
+    defer allocator.free(inserted);
+    try std.testing.expectEqualStrings("https://login.example/.well-known/openid-configuration/tenant", inserted);
+    const appended = try oidcAppendedMetadataUrl(allocator, "https://login.example/tenant/");
+    defer allocator.free(appended);
+    try std.testing.expectEqualStrings("https://login.example/tenant/.well-known/openid-configuration", appended);
+}
+
+test "Bearer challenge parsing handles other challenges and quoted escapes" {
+    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+    defer arena_state.deinit();
+    const challenge = try parseChallenge(arena_state.allocator(), "Bearer realm=\"old\", Basic realm=\"legacy\", Bearer resource_metadata=\"https://mcp.example/meta\\?v=1\", scope=\"docs:read profile\", Digest realm=\"later\"");
+    try std.testing.expectEqualStrings("https://mcp.example/meta?v=1", challenge.resource_metadata.?);
+    try std.testing.expectEqualStrings("docs:read profile", challenge.scope.?);
+}
+
+test "challenge scope takes priority over metadata scopes" {
+    try std.testing.expectEqualStrings("challenge:read", preferredScope("challenge:read", "resource:write", "server:write"));
+    try std.testing.expectEqualStrings("resource:read", preferredScope(null, "resource:read", "server:write"));
+    try std.testing.expectEqualStrings("server:read", preferredScope(null, "", "server:read"));
+}
+
+test "scope subset rejects unapproved challenge permissions" {
+    try std.testing.expect(scopeSubsetOf("docs:read profile", "profile email docs:read"));
+    try std.testing.expect(!scopeSubsetOf("docs:read docs:write", "profile email docs:read"));
+}
+
+test "PKCE metadata requires exact S256 array member" {
+    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+    defer arena_state.deinit();
+    const arena = arena_state.allocator();
+    const good = (try std.json.parseFromSliceLeaky(std.json.Value, arena, "{\"code_challenge_methods_supported\":[\"plain\",\"S256\"]}", .{})).object;
+    const wrong_case = (try std.json.parseFromSliceLeaky(std.json.Value, arena, "{\"code_challenge_methods_supported\":[\"s256\"]}", .{})).object;
+    const wrong_type = (try std.json.parseFromSliceLeaky(std.json.Value, arena, "{\"code_challenge_methods_supported\":\"S256\"}", .{})).object;
+    try std.testing.expect(supportsS256(good));
+    try std.testing.expect(!supportsS256(wrong_case));
+    try std.testing.expect(!supportsS256(wrong_type));
+}
diff --git a/src/mcp_protocol.zig b/src/mcp_protocol.zig
new file mode 100644
index 00000000..2ca6c697
--- /dev/null
+++ b/src/mcp_protocol.zig
@@ -0,0 +1,138 @@
+//! MCP protocol negotiation and tool JSON Schema normalization.
+
+const std = @import("std");
+const Value = std.json.Value;
+const Allocator = std.mem.Allocator;
+
+/// Recursively rewrite the JSON Schema keyword `oneOf` to `anyOf` (graff's
+/// rewrite_one_of_to_any_of). OpenAI's tool-schema validator — including the
+/// chatgpt.com /codex/responses endpoint — rejects `oneOf` outright with
+/// "'oneOf' is not permitted"; `anyOf` is accepted by both OpenAI and
+/// Anthropic and is equivalent for the discriminated unions MCP servers emit
+/// in practice. When both keywords are present (rare, ambiguous to merge),
+/// the existing `anyOf` wins and `oneOf` is dropped. Runs once per tool at
+/// discovery, so the rendered tools JSON stays KV-cache-stable.
+pub fn rewriteOneOf(a: Allocator, v: *Value) Allocator.Error!void {
+    switch (v.*) {
+        .object => |*obj| {
+            if (obj.get("oneOf")) |branches| {
+                if (obj.get("anyOf") == null) try obj.put(a, "anyOf", branches);
+                _ = obj.swapRemove("oneOf");
+            }
+            var it = obj.iterator();
+            while (it.next()) |e| try rewriteOneOf(a, e.value_ptr);
+        },
+        .array => |*arr| for (arr.items) |*item| try rewriteOneOf(a, item),
+        else => {},
+    }
+}
+
+/// Latest MCP revision advertised during initialization.
+pub const latest_protocol = "2025-11-25";
+
+/// Revisions whose initialize, tools, and content schemas are compatible with
+/// the subset implemented by this client.
+pub const supported_protocols = [_][]const u8{
+    latest_protocol,
+    "2025-06-18",
+    "2025-03-26",
+    "2024-11-05",
+};
+
+pub const Transport = enum {
+    stdio,
+    streamable_http,
+};
+
+fn supportsProtocol(transport: Transport, version: []const u8) bool {
+    for (supported_protocols) |supported| {
+        if (!std.mem.eql(u8, version, supported)) continue;
+        // Streamable HTTP replaced the legacy HTTP+SSE transport in
+        // 2025-03-26. The older revision remains compatible over stdio only.
+        return transport == .stdio or !std.mem.eql(u8, version, "2024-11-05");
+    }
+    return false;
+}
+
+pub fn negotiatedProtocol(response: Value, transport: Transport) ![]const u8 {
+    if (response != .object) return error.BadMcpInitializeResponse;
+    const result = response.object.get("result") orelse return error.BadMcpInitializeResponse;
+    if (result != .object) return error.BadMcpInitializeResponse;
+    const version = result.object.get("protocolVersion") orelse return error.MissingMcpProtocolVersion;
+    if (version != .string) return error.InvalidMcpProtocolVersion;
+    if (supportsProtocol(transport, version.string)) return version.string;
+    return error.UnsupportedMcpProtocolVersion;
+}
+
+test "rewriteOneOf: converts oneOf to anyOf, recursively" {
+    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+    defer arena_state.deinit();
+    const a = arena_state.allocator();
+    var v = try std.json.parseFromSliceLeaky(Value, a,
+        \\{"oneOf":[{"type":"string"}],"properties":{"x":{"oneOf":[{"type":"number"},{"type":"null"}]}}}
+    , .{});
+    try rewriteOneOf(a, &v);
+    try std.testing.expect(v.object.get("oneOf") == null);
+    try std.testing.expectEqual(@as(usize, 1), v.object.get("anyOf").?.array.items.len);
+    const x = v.object.get("properties").?.object.get("x").?;
+    try std.testing.expect(x.object.get("oneOf") == null);
+    try std.testing.expectEqual(@as(usize, 2), x.object.get("anyOf").?.array.items.len);
+}
+
+test "rewriteOneOf: existing anyOf wins when both are present" {
+    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+    defer arena_state.deinit();
+    const a = arena_state.allocator();
+    var v = try std.json.parseFromSliceLeaky(Value, a,
+        \\{"anyOf":[{"type":"string"}],"oneOf":[{"type":"number"},{"type":"boolean"}]}
+    , .{});
+    try rewriteOneOf(a, &v);
+    try std.testing.expect(v.object.get("oneOf") == null);
+    // the pre-existing single-branch anyOf survives, the oneOf is dropped
+    try std.testing.expectEqual(@as(usize, 1), v.object.get("anyOf").?.array.items.len);
+}
+
+test "rewriteOneOf: arrays and scalars pass through untouched" {
+    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+    defer arena_state.deinit();
+    const a = arena_state.allocator();
+    var v = try std.json.parseFromSliceLeaky(Value, a,
+        \\{"items":[{"oneOf":[1,2]},"plain",42]}
+    , .{});
+    try rewriteOneOf(a, &v);
+    const first = v.object.get("items").?.array.items[0];
+    try std.testing.expect(first.object.get("oneOf") == null);
+    try std.testing.expect(first.object.get("anyOf") != null);
+}
+
+test "initialize negotiation accepts transport-compatible protocol versions" {
+    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+    defer arena_state.deinit();
+    const a = arena_state.allocator();
+
+    for (supported_protocols) |version| {
+        const json = try std.fmt.allocPrint(a,
+            \\{{"jsonrpc":"2.0","id":1,"result":{{"protocolVersion":"{s}"}}}}
+        , .{version});
+        const response = try std.json.parseFromSliceLeaky(Value, a, json, .{});
+        try std.testing.expectEqualStrings(version, try negotiatedProtocol(response, .stdio));
+        if (std.mem.eql(u8, version, "2024-11-05")) {
+            try std.testing.expectError(error.UnsupportedMcpProtocolVersion, negotiatedProtocol(response, .streamable_http));
+        } else {
+            try std.testing.expectEqualStrings(version, try negotiatedProtocol(response, .streamable_http));
+        }
+    }
+}
+
+test "initialize negotiation rejects missing, non-string, and unsupported versions" {
+    const cases = [_]struct { json: []const u8, expected: anyerror }{
+        .{ .json = "{\"result\":{}}", .expected = error.MissingMcpProtocolVersion },
+        .{ .json = "{\"result\":{\"protocolVersion\":20251125}}", .expected = error.InvalidMcpProtocolVersion },
+        .{ .json = "{\"result\":{\"protocolVersion\":\"2099-01-01\"}}", .expected = error.UnsupportedMcpProtocolVersion },
+    };
+    for (cases) |case| {
+        var parsed = try std.json.parseFromSlice(Value, std.testing.allocator, case.json, .{});
+        defer parsed.deinit();
+        try std.testing.expectError(case.expected, negotiatedProtocol(parsed.value, .streamable_http));
+    }
+}
diff --git a/src/mcp_stdio.zig b/src/mcp_stdio.zig
new file mode 100644
index 00000000..7f91193f
--- /dev/null
+++ b/src/mcp_stdio.zig
@@ -0,0 +1,56 @@
+//! MCP stdio child-process shutdown.
+
+const std = @import("std");
+const builtin = @import("builtin");
+const Io = std.Io;
+
+const shutdown_grace = std.Io.Duration.fromMilliseconds(100);
+
+fn waitChild(child: *std.process.Child, io: Io) std.process.Child.WaitError!std.process.Child.Term {
+    return child.wait(io);
+}
+
+fn shutdownDeadline(io: Io) void {
+    io.sleep(shutdown_grace, .awake) catch {};
+}
+
+/// Signal a normal stdio-server shutdown with EOF, but never let a server's
+/// SIGTERM handler stall the CLI. A child that does not exit within the grace
+/// window is force-killed and reaped so one-shot/SDK callers do not inherit
+/// teardown latency or zombies.
+pub fn stopChild(io: Io, child: *std.process.Child) void {
+    if (child.id == null) return;
+    if (child.stdin) |stdin| {
+        stdin.close(io);
+        child.stdin = null;
+    }
+
+    const Done = union(enum) { exited: std.process.Child.WaitError!std.process.Child.Term, deadline: void };
+    var done_buf: [2]Done = undefined;
+    var sel: Io.Select(Done) = .init(io, &done_buf);
+    sel.concurrent(.exited, waitChild, .{ child, io }) catch {
+        child.kill(io);
+        return;
+    };
+    sel.concurrent(.deadline, shutdownDeadline, .{io}) catch {
+        _ = sel.await() catch {};
+        sel.cancelDiscard();
+        return;
+    };
+    const first = sel.await() catch {
+        sel.cancelDiscard();
+        child.kill(io);
+        return;
+    };
+    sel.cancelDiscard();
+    if (first == .exited or child.id == null) return;
+
+    switch (builtin.os.tag) {
+        .windows => child.kill(io),
+        .wasi => unreachable,
+        else => {
+            std.posix.kill(child.id.?, .KILL) catch {};
+            _ = child.wait(io) catch child.kill(io);
+        },
+    }
+}
diff --git a/src/session_run.zig b/src/session_run.zig
index 20e6a770..bd7a3e47 100644
--- a/src/session_run.zig
+++ b/src/session_run.zig
@@ -327,23 +327,21 @@ pub fn finalizeSession(gpa: Allocator, io: Io, arena: Allocator, out: *Io.Writer
 
 pub const ThemeSetup = struct {
     theme_on: bool,
-    limyuxi_glam: bool,
     /// True when a PTY self-test already ran + printed its render — main()
     /// should return immediately without going any
-    /// further (but AFTER registering the theme/limyuxi reset defers below,
+    /// further (but AFTER registering the theme reset defer below,
     /// exactly like the original inline code did).
     should_exit: bool,
 };
 
 /// Per-skill/companion opt-outs, animation + terminal-theme settings, the
-/// headless PTY render self-tests, and the
-/// yxlyx-birthday cosmetic theme. Moved out of main() verbatim (600-line
-/// goal). Returns which reset defers main() needs to register — the
-/// escape-code RESETS must fire when main() itself returns (not when this
-/// helper returns), so the `defer`s stay in main(), gated on the booleans
-/// this returns; main() registers them in the same order as the original
+/// headless PTY render self-tests. Moved out of main() verbatim (600-line
+/// goal). Returns which reset defer main() needs to register — the
+/// escape-code RESET must fire when main() itself returns (not when this
+/// helper returns), so the `defer` stays in main(), gated on the boolean
+/// this returns; main() registers it in the same order as the original
 /// inline code so LIFO defer-firing order is unchanged.
-pub fn setupSkillsAndTheme(io: Io, arena: Allocator, environ_map: anytype, out: *Io.Writer, flags: args.Flags, use_color: bool, json_mode: bool, cwd_display: []const u8) !ThemeSetup {
+pub fn setupSkillsAndTheme(io: Io, arena: Allocator, environ_map: anytype, out: *Io.Writer, flags: args.Flags, use_color: bool, json_mode: bool) !ThemeSetup {
     // Companion auto-activation: if the metered code-intelligence companion
     // (codedb-pro, formerly muonry) is installed but nothing connected it (no
     // workspace .mcp.json entry, or consent declined), spawn it directly — a
@@ -422,38 +420,6 @@ pub fn setupSkillsAndTheme(io: Io, arena: Allocator, environ_map: anytype, out:
         out.writeAll(anim.themes[anim.g_theme.?].seq) catch {};
         out.flush() catch {};
     }
-    // 🎂 yxlyx's birthday glam — when graff runs from her home dir, dress her
-    // Ghostty in the pastel-pink theme (limyuxi_theme: light pink bg, dark plum
-    // text, pink-leaning palette) and switch the spinner to glittery sparkles.
-    // Cosmetic, flagged, gated to her cwd; resets everything on exit.
-    const limyuxi_glam = anim.limyuxi_birthday_white and use_color and !json_mode and
-        (std.mem.eql(u8, cwd_display, "/Users/limyuxi") or std.mem.startsWith(u8, cwd_display, "/Users/limyuxi/"));
-    if (limyuxi_glam) {
-        out.writeAll(anim.limyuxi_theme) catch {};
-        out.flush() catch {};
-        if (anim.animIndex("dragon")) |gi| {
-            anim.g_anim_index = gi;
-            anim.g_anim_off = false;
-            anim.g_anim_random = false;
-        }
-    }
-    if (flags.selftest_spinner_flag) {
-        // Headless render of the real thinking-spinner pool for the PTY anti-stealth
-        // test (scripts/test-pty-spinner.py): runs the real selection (so a cwd-gated
-        // pick surfaces) and prints every frame fn's output to stdout, where the test
-        // scans for the U+1F4A9 / supplementary-plane glyph class the poop hid in.
-        anim.selectSpinner(io);
-        out.print("selected: {s}\n", .{anim.anims[anim.g_anim_current].name}) catch {};
-        for (anim.anims) |a| {
-            var i: usize = 0;
-            while (i < 48) : (i += 1) {
-                a.frame(out, i) catch {};
-                out.writeByte('\n') catch {};
-            }
-        }
-        out.flush() catch {};
-        return .{ .theme_on = theme_on, .limyuxi_glam = limyuxi_glam, .should_exit = true };
-    }
     if (flags.selftest_markdown_flag) {
         var probe: agent_mod.Agent = .{
             .gpa = arena,
@@ -482,8 +448,8 @@ pub fn setupSkillsAndTheme(io: Io, arena: Allocator, environ_map: anytype, out:
         probe.flushStreamTail();
         out.writeByte('\n') catch {};
         out.flush() catch {};
-        return .{ .theme_on = theme_on, .limyuxi_glam = limyuxi_glam, .should_exit = true };
+        return .{ .theme_on = theme_on, .should_exit = true };
     }
     anim.loadDevSpinnerOptOut(io, arena, environ_map);
-    return .{ .theme_on = theme_on, .limyuxi_glam = limyuxi_glam, .should_exit = false };
+    return .{ .theme_on = theme_on, .should_exit = false };
 }
diff --git a/src/session_start.zig b/src/session_start.zig
index 276ac698..13a62342 100644
--- a/src/session_start.zig
+++ b/src/session_start.zig
@@ -246,22 +246,22 @@ pub fn initTelemetry(io: Io, gpa: Allocator, client: *std.http.Client, environ_m
 /// `/mcp add` still works. Moved out of main() (600-line goal). Returns the
 /// Registry by value — mcp.Registry holds no self-references (its storage
 /// is ArrayList/HashMap-backed), so returning it is safe.
-pub fn initRegistryConsent(io: Io, gpa: Allocator, arena: Allocator, out: *Io.Writer, in: *Io.Reader, flags: args.Flags, mcp_config_path: []const u8, use_color: bool, json_mode: bool) !mcp.Registry {
+pub fn initRegistryConsent(io: Io, gpa: Allocator, arena: Allocator, out: *Io.Writer, in: *Io.Reader, flags: args.Flags, mcp_config_path: []const u8, home: []const u8, use_color: bool, json_mode: bool) !mcp.Registry {
     const mcp_count = mcp_cli.countMcpServers(io, arena);
     var connect_mcp = flags.yolo_flag or mcp_count == 0;
     if (mcp_count > 0 and !flags.yolo_flag and !json_mode and use_color) {
-        try out.print("{s}⚠ this workspace's .mcp.json defines {d} MCP server(s) that run local commands. Connect them this session? [y/N] {s}", .{ ansi.style.bold, mcp_count, ansi.style.reset });
+        try out.print("{s}⚠ this workspace's .mcp.json defines {d} untrusted MCP server(s). They may run local commands or receive data over the network. Connect them this session? [y/N] {s}", .{ ansi.style.bold, mcp_count, ansi.style.reset });
         try out.flush();
         const ans = in.takeDelimiter('\n') catch null;
         connect_mcp = ans != null and ans.?.len > 0 and (ans.?[0] == 'y' or ans.?[0] == 'Y');
     }
-    return if (connect_mcp) ((mcp.Registry.init(gpa, io, mcp_config_path) catch |err| inner: {
+    return if (connect_mcp) ((mcp.Registry.init(gpa, io, mcp_config_path, home) catch |err| inner: {
         try out.print("[mcp] init failed: {t} — continuing without MCP\n", .{err});
         if (telemetry.g_telem) |t| t.errorEvent("mcp", @errorName(err));
         break :inner null;
-    }) orelse mcp.Registry.empty(gpa, io)) else outer: {
+    }) orelse mcp.Registry.emptyWithOAuthHome(gpa, io, home)) else outer: {
         if (mcp_count > 0) try out.print("{s}skipped {d} workspace MCP server(s) — /mcp trust to connect them now (or re-run with --yolo){s}\n", .{ ansi.style.dim, mcp_count, ansi.style.reset });
-        break :outer mcp.Registry.empty(gpa, io);
+        break :outer mcp.Registry.emptyWithOAuthHome(gpa, io, home);
     };
 }
 
@@ -274,7 +274,7 @@ pub fn initRegistryConsent(io: Io, gpa: Allocator, arena: Allocator, out: *Io.Wr
 /// Moved out of main() (600-line goal); mutates `registry` in place (it's
 /// already main()-owned and stable by the time this is called, so a pointer
 /// is all that's needed — no return-by-value trickery here).
-pub fn connectCompanion(io: Io, registry: *mcp.Registry, flags: args.Flags, out: *Io.Writer, json_mode: bool) !void {
+pub fn connectCompanion(io: Io, registry: *mcp.Registry, flags: args.Flags, out: *Io.Writer, json_mode: bool, smolify_enabled: bool) !void {
     connect: {
         for (skills.companion_servers) |c| if (skills.mcpServerConnected(registry.tools, c.server)) break :connect;
         for (skills.companion_servers) |c| {
@@ -289,4 +289,14 @@ pub fn connectCompanion(io: Io, registry: *mcp.Registry, flags: args.Flags, out:
             }
         }
     }
+
+    // Smolify is a core, hosted Streamable HTTP MCP. It can be disabled with
+    // GRAFF_NO_SMOLIFY=1 for offline or privacy-sensitive sessions.
+    if (!smolify_enabled) return;
+    _ = registry.connectSmolify() catch |err| {
+        if (!json_mode and flags.oneshot_prompt == null) {
+            try out.print("{s}[mcp:smolify] auto-connect failed ({t}) — continuing offline{s}\n", .{ ansi.style.dim, err, ansi.style.reset });
+            try out.flush();
+        }
+    };
 }
diff --git a/src/skills.zig b/src/skills.zig
index 37822e7f..6de182ab 100644
--- a/src/skills.zig
+++ b/src/skills.zig
@@ -78,6 +78,10 @@ pub const mcp_notes = [_]McpNote{
         .server = "muonry",
         .note = "The muonry MCP server is connected (mcp__muonry__* tools). SEARCH ORDER: the native codedb tool is free and indexed — always try it first for code search (search/symbol/callers/outline/find); use mcp__muonry__search or faster_search only when codedb can't answer (raw literal/regex content matches, non-code or non-indexed files) — muonry is metered. Prefer mcp__muonry__read (mode=outline first, then symbol) over read_file for navigating large code files, and mcp__muonry__batch to run several independent reads/searches/edits in one round-trip. Keep edits inside the cwd on the native edit_file/write_file tools (they are snapshot-tracked for /rewind); for an explicitly user-requested external target, use permission-gated bash with quoted paths and disclose that /rewind does not cover it. These tools are accelerators, not requirements: whenever an mcp__muonry__ call fails or is unavailable, fall back to read_file/codedb/bash and continue.",
     },
+    .{
+        .server = "smolify",
+        .note = "The core Smolify MCP is connected (mcp__smolify__* tools). Use it to discover and search generated API documentation when a task involves an unfamiliar public project or library; prefer local repository code and its own docs when they already answer the question.",
+    },
 };
 
 /// The metered code-intelligence companion. It first shipped as `muonry` and
diff --git a/src/startup.zig b/src/startup.zig
index 21518721..4fd1bfe3 100644
--- a/src/startup.zig
+++ b/src/startup.zig
@@ -11,7 +11,7 @@
 //! fields point into the HELPER's own stack frame — invalid the instant the
 //! helper returns. So that construction (and the MCP-registry/approvals/
 //! hooks/theme block, which is additionally tangled with several `defer`s
-//! and a mid-block early `return` for --selftest-spinner) is intentionally
+//! and a mid-block early `return` for PTY self-tests) is intentionally
 //! left inline in main(), per the split's own guidance: don't force an
 //! extraction that can't be done without an address-capture or defer-order
 //! hazard.
@@ -408,9 +408,10 @@ pub fn runSubcommand(io: Io, gpa: Allocator, arena: Allocator, init: std.process
         return true;
     }
 
-    // `harness mcp add <name> -- <command> [args...]`: write workspace MCP config.
+    // MCP list/add only use workspace config; OAuth login validates HOME itself.
     if (flags.positionals.items.len > 0 and std.mem.eql(u8, flags.positionals.items[0], "mcp")) {
-        try mcp_cli.mcpCommand(io, arena, flags.positionals.items[1..]);
+        const home = keys_cli.homeEnv(init.environ_map) orelse "";
+        try mcp_cli.mcpCommand(io, gpa, arena, home, flags.positionals.items[1..]);
         return true;
     }