@basein/runner 0.1.0

package/docs/BaseInstRunner.md

@@ -0,0 +1,621 @@
+# BaseInstRunnerMCP — Design & Implementation Plan
+
+> A recording MCP **proxy**: it sits between any MCP client (Claude Code, Cursor,
+> Codex, an Agent SDK session) and every MCP server that client uses, executes
+> each call on the client's behalf, and records the run as a reusable scenario in
+> the BaseIn service.
+>
+> **Status:** design. No code written yet.
+> **Relationship to RRepeat:** a separate solution. RRepeat records by *observing*
+> a Claude Code session through hooks; BaseInstRunnerMCP records by *being* the
+> execution path for MCP. They share a recorder contract and can run side by side.
+
+---
+
+## 0. Decisions locked
+
+| # | Decision | Choice | Consequence |
+|---|---|---|---|
+| D1 | Stack | TypeScript / Node, standalone repo | Ports `McpClient`, `McpBridge`, `RemoteRecorder`, the scope merge and the auth client from RRepeat instead of reinventing them |
+| D2 | Scope | MCP proxy **+ companion hook binary** | The only combination that reaches non-MCP tools (`Bash`, `Read`, `Edit`) |
+| D3 | Topology | Per-server shadow, **auto-generated** config | Preserves `mcp__<server>__<tool>` names; N proxy processes, one per upstream |
+| D4 | v1 scope | **Record only** | Replay/divergence deferred to v2 |
+| D5 | Run correlation | **Hook binary owns the run** | One monotonic step counter across built-in and MCP steps |
+| D6 | Persistence | BaseIn auth-service HTTP | Reuses `/recordings/*`, tenancy and the savings pipeline |
+| D7 | Protocol | **Full transparent passthrough** | Generic bidirectional relay, not a `tools/*` switch |
+| D8 | Callers | **Any MCP client** | No assumptions about config paths or tool-name conventions |
+
+### 0.1 The tension in D5 + D8, and how it is resolved
+
+D5 says the hook binary owns run identity. D8 says support any MCP client. Only
+Claude Code has hooks. Both cannot hold universally, so run ownership is
+**negotiated at proxy startup**, with two tiers:
+
+| Tier | When | Run owner | What gets recorded |
+|---|---|---|---|
+| **Tier 1 — Bound** | A BIR control server is discoverable for this cwd (Claude Code or Agent SDK with `bir-hooks` installed) | Control server | Built-ins **and** MCP, one ordered step stream, prompt and final answer included |
+| **Tier 2 — Standalone** | No control server found within the discovery window | The proxy itself | MCP calls only. No prompt, no final answer, no built-in steps — a partial scenario, explicitly flagged |
+
+Tier 2 is not a degraded bug, it is the honest ceiling of what an MCP proxy can
+observe. Scenarios record which tier produced them so downstream consumers never
+mistake a partial trace for a complete one.
+
+---
+
+## 1. Goals and non-goals
+
+**Goals**
+
+1. Execute every MCP `tools/call` the client makes, on the client's behalf, and
+   return the upstream's result **losslessly** — content blocks, `structuredContent`,
+   `isError`, `_meta` — so the client cannot tell the proxy is there.
+2. Record each call as a step in a BaseIn run: server, tool, arguments, result,
+   duration, error.
+3. Be transparent for everything that is not `tools/call`: prompts, resources,
+   logging, completion, progress, cancellation, and the **reverse** direction
+   (sampling, elicitation, roots, list-changed notifications).
+4. Never be the reason a host session fails. Every failure degrades to passthrough
+   or to not-recording; none propagates.
+5. Install itself: given a client's existing MCP configuration, produce the
+   proxied configuration automatically and reversibly.
+
+**Non-goals for v1**
+
+- Replay, divergence bundles, steering. (v2 — §12.)
+- Intercepting non-MCP tools *without* the hook binary. Structurally impossible.
+- Wrapping `claude-in-chrome`. It is `scope: "dynamic"`, present in no config file,
+  so there is no entry to rewrite.
+- Model-side behaviour change. The proxy never edits tool descriptions to steer
+  selection.
+
+---
+
+## 2. The structural constraint
+
+This is the single most important fact in the document, and every design choice
+below follows from it.
+
+**An MCP server sees only MCP traffic addressed to it.** The model does not choose
+the proxy — it emits `mcp__chrome-devtools__navigate_page`, and the client routes
+that name to whichever process is registered under the key `chrome-devtools`. That
+makes interception a *configuration* guarantee, not a prompting one, which is
+strong. But its reach is exactly the set of configured MCP servers:
+
+| Traffic | Proxy sees it? | Why |
+|---|---|---|
+| `mcp__<wrapped>__*` | **Yes, always** | Routed by config key |
+| `mcp__<unwrapped>__*` | No | Client connects to that server directly |
+| `Bash`, `Read`, `Edit`, `Grep`, `Glob`, `Task`, `WebFetch` | **No** | Not MCP. Hook binary only |
+| `claude-in-chrome` | No | Dynamic scope, no config entry |
+| User prompt, model reasoning, final answer | **No** | Not tool traffic. Hook binary only |
+
+Hence D2. The proxy and the hook binary are two halves of one recorder.
+
+---
+
+## 3. Architecture
+
+```mermaid
+graph TB
+  subgraph host["Host application (Claude Code / Cursor / SDK)"]
+    M[model loop]
+    H["hooks (Claude Code only)"]
+  end
+
+  subgraph bir["BaseInstRunnerMCP"]
+    C["bir-hooks<br/>control server<br/>:PORT"]
+    P1["bir-proxy<br/>server: chrome-devtools"]
+    P2["bir-proxy<br/>server: github"]
+  end
+
+  U1[chrome-devtools-mcp]
+  U2["github mcp (http)"]
+  R[("BaseIn auth-service<br/>/recordings/*")]
+
+  M -->|"mcp__chrome-devtools__*"| P1
+  M -->|"mcp__github__*"| P2
+  H -->|"built-in steps, prompt, stop"| C
+  P1 <-->|stdio JSON-RPC| U1
+  P2 <-->|http/sse JSON-RPC| U2
+  P1 -->|"step report + call id"| C
+  P2 -->|"step report + call id"| C
+  C -->|ordered run| R
+```
+
+### 3.1 Components
+
+| Component | Process | Responsibility |
+|---|---|---|
+| `bir-proxy` | one per wrapped upstream, spawned by the host | Bidirectional JSON-RPC relay. Executes `tools/call` against the upstream, reports the step, forwards everything else verbatim |
+| `bir-hooks` | one per host session | Claude Code hook receiver **and** control server. Owns run identity and the monotonic step counter. Records built-in tool steps, prompt, final answer |
+| `bir` | CLI | `install`, `uninstall`, `status`, `doctor`, `wrap` |
+| Recorder | library, inside `bir-hooks` (Tier 1) or `bir-proxy` (Tier 2) | Streams steps to the BaseIn service |
+
+### 3.2 Why a control server, rather than each proxy recording directly
+
+Three proxies recording independently would produce three interleaved step streams
+with no shared ordering, and would double-record every call the hook also sees. A
+single control server gives one `stepIndex` sequence, one run lifecycle, one HTTP
+chain to the recorder, and one place to dedupe. It is the role RRepeat's
+`HookServer` already plays, widened to accept proxy reports.
+
+---
+
+## 4. Solution layout
+
+```
+BaseInstRunnerMCP/
+├─ package.json                 # bin: bir, bir-proxy, bir-hooks
+├─ tsconfig.json
+├─ src/
+│  ├─ bin/
+│  │  ├─ bir-proxy.ts           # stdio MCP proxy entry point
+│  │  ├─ bir-hooks.ts           # hook receiver + control server entry point
+│  │  └─ bir.ts                 # install / status / doctor / wrap
+│  ├─ jsonrpc/
+│  │  ├─ framing.ts             # line-delimited JSON-RPC read/write
+│  │  └─ types.ts               # Request | Response | Notification
+│  ├─ proxy/
+│  │  ├─ relay.ts               # bidirectional relay, default-forward
+│  │  ├─ intercept.ts           # the small intercept table
+│  │  └─ session.ts             # per-proxy lifecycle, tier negotiation
+│  ├─ upstream/
+│  │  ├─ client.ts              # UpstreamClient interface
+│  │  ├─ stdio-client.ts        # spawn + framing
+│  │  └─ http-client.ts         # streamable-http and sse
+│  ├─ control/
+│  │  ├─ server.ts              # local HTTP control plane
+│  │  ├─ discovery.ts           # ~/.baseinstrunner/control/<key>.json
+│  │  ├─ correlation.ts         # __bir_call_id__ inject/extract/dedupe
+│  │  └─ ordering.ts            # monotonic stepIndex allocator
+│  ├─ record/
+│  │  ├─ recorder.ts            # Recorder interface
+│  │  ├─ remote-recorder.ts     # BaseIn HTTP implementation
+│  │  ├─ redact.ts              # secret scrubbing
+│  │  └─ truncate.ts            # payload size caps
+│  ├─ config/
+│  │  ├─ resolve.ts             # merged scope resolution per client
+│  │  ├─ generate.ts            # wrap entries → proxied config
+│  │  └─ adapters/
+│  │     ├─ claude-code.ts      # 3-scope merge, ~/.claude.json + .mcp.json
+│  │     └─ generic.ts          # explicit --config <path>
+│  └─ auth/client.ts            # login, token refresh
+└─ test/
+   ├─ fixtures/                 # golden JSON-RPC transcripts
+   ├─ fake-upstream.ts          # scriptable MCP server for tests
+   └─ *.test.ts
+```
+
+---
+
+## 5. Core contracts
+
+```ts
+// upstream/client.ts — every upstream transport implements this.
+export interface UpstreamClient {
+  /** Resolves when the handshake completed; rejects if the upstream is unusable. */
+  readonly ready: Promise<InitializeResult>;
+  /** Send any request and get the raw JSON-RPC result. No shape assumptions. */
+  request(method: string, params?: unknown, signal?: AbortSignal): Promise<unknown>;
+  /** Fire-and-forget notification toward the upstream. */
+  notify(method: string, params?: unknown): void;
+  /** Requests and notifications the upstream originates (sampling, elicitation, ...). */
+  onIncoming(handler: (msg: JsonRpcMessage) => void): void;
+  close(): void;
+}
+
+// record/recorder.ts — the surface both tiers use. Mirrors RRepeat's RemoteRecorder
+// so the BaseIn server needs no new endpoints for v1.
+export interface Recorder {
+  startRun(input: string, metadata?: Record<string, unknown>): string;
+  recordToolSelected(runId: string, stepIndex: number,
+    d: { toolName: string; toolInput: string; context?: string }): string;
+  recordToolResponse(runId: string, stepIndex: number,
+    d: { toolName: string; toolOutput?: string; toolError?: string }): string;
+  recordFinalAnswer(runId: string, stepIndex: number, d: { answer: string }): string;
+  finishRun(runId: string, finalOutput?: string, metrics?: RunMetrics): void;
+  flush(runId: string): Promise<void>;
+}
+
+// control/correlation.ts
+export const BIR_CALL_ID = "__bir_call_id__";
+
+// The step a proxy reports to the control server.
+export interface ProxyStepReport {
+  callId?: string;          // present in Tier 1 when the hook injected one
+  serverName: string;       // config key, e.g. "chrome-devtools"
+  toolName: string;         // upstream-local name, e.g. "navigate_page"
+  qualifiedName: string;    // client-rendered, e.g. "mcp__chrome-devtools__navigate_page"
+  args: unknown;            // post-redaction
+  result?: unknown;         // whole CallToolResult, post-redaction and truncation
+  isError: boolean;
+  errorMessage?: string;
+  startedAt: number;        // epoch ms
+  durationMs: number;
+}
+```
+
+`qualifiedName` is stored **alongside** `serverName` + `toolName`, never instead of
+them. `mcp__<server>__<tool>` is Claude Code's rendering; other clients differ.
+Storing the parts keeps scenarios portable across hosts (D8).
+
+---
+
+## 6. Implementation, phase by phase
+
+Each phase ends in something runnable and testable. Do not start a phase before
+its predecessor's acceptance test passes.
+
+### Phase 0 — Scaffold
+
+1. `npm init`; TypeScript strict, ESM (`"type": "module"`), Node >= 20.
+2. `package.json` bin map:
+   ```json
+   { "bir": "dist/bin/bir.js",
+     "bir-proxy": "dist/bin/bir-proxy.js",
+     "bir-hooks": "dist/bin/bir-hooks.js" }
+   ```
+3. Zero runtime dependencies beyond `zod` if you want schema validation. Node's
+   built-in `fetch`, `child_process` and `http` cover the rest. Resist adding an MCP
+   SDK — full passthrough means handling unknown methods, which a typed SDK fights.
+
+**Acceptance:** `npx bir --version` prints.
+
+### Phase 1 — Framing and the bidirectional relay
+
+This is the heart, and it is deliberately dumb.
+
+1. `jsonrpc/framing.ts` — read newline-delimited JSON from a stream, write the same.
+   Handle partial reads, oversized lines, and invalid JSON (respond `-32700`, never
+   crash).
+2. `proxy/relay.ts` — connect two message ports (host stdio ↔ upstream) and forward
+   every message in both directions, **by default**.
+
+   The design rule that makes full passthrough tractable:
+
+   > **Default-forward, intercept by exception.** Do not enumerate the protocol.
+   > Forward any message you have no specific reason to touch. The intercept table
+   > is three entries long.
+
+3. Id handling. Because the relay is 1:1, host ids can pass through unchanged. Keep
+   a `Map<hostId, { method, startedAt }>` anyway — you need it to time `tools/call`
+   and to match `notifications/cancelled`. Reserve a disjoint id space (a `bir:`
+   prefix) for any request the proxy ever originates, so collisions are impossible.
+
+**Acceptance:** `bir-proxy -- npx -y chrome-devtools-mcp@latest` behaves
+byte-identically to running the upstream directly, verified by a golden transcript
+in `test/fixtures/`.
+
+### Phase 2 — Upstream transports
+
+1. `stdio-client.ts` — `spawn(command, args, { env, stdio: ['pipe','pipe','pipe'] })`.
+   Forward upstream stderr to the proxy's own stderr **prefixed**, never to stdout;
+   a stray stdout byte corrupts the host's JSON-RPC stream. This is the single most
+   common way stdio MCP servers break.
+2. `http-client.ts` — streamable-http and sse. Carry `--header k:v` for auth, since
+   the host's own OAuth handling does not survive a proxy in front of it (§9).
+3. Lifecycle: upstream death is not proxy death. On exit, mark the upstream dead,
+   answer in-flight requests with a JSON-RPC error, optionally restart once with
+   backoff, then stay dead and answer `tools/list` with an error rather than exiting.
+
+**Acceptance:** the Phase 1 transcript test passes against a stdio upstream, an
+http upstream, and an upstream killed mid-call.
+
+### Phase 3 — The intercept table
+
+Only three methods are touched. Everything else relays untouched, both directions.
+
+| Method | Direction | Action |
+|---|---|---|
+| `initialize` | host → upstream | **Relay, and rewrite as little as possible.** Forward the host's `capabilities` verbatim so the upstream learns whether sampling/elicitation exist. Return the upstream's `capabilities` and `serverInfo` verbatim, so prompts/resources/logging stay advertised. Do **not** hard-code `{ tools: {} }` — that is exactly what makes a proxy silently swallow prompts and resources. |
+| `tools/list` | host → upstream | Relay. If Tier 1 correlation is active, apply schema relaxation (§6, Phase 6). Otherwise leave schemas untouched. |
+| `tools/call` | host → upstream | Extract and strip `__bir_call_id__`; time the call; relay; report the step; return the upstream result **verbatim**. |
+
+Everything else — `prompts/*`, `resources/*`, `completion/complete`,
+`logging/setLevel`, `ping`, `notifications/cancelled`, `notifications/progress`,
+and the reverse-direction `sampling/createMessage`, `elicitation/create`,
+`roots/list`, `notifications/*/list_changed`, `notifications/message` — passes
+through with no special case. That is the point of D7: unknown methods work
+*because* they are never enumerated.
+
+Two rules that are easy to get wrong:
+
+- **Never rewrite a `tools/call` result.** Return the upstream object as-is,
+  including `_meta` and `structuredContent`. Record a *copy*.
+- **Never let recording block the response.** Report the step on a fire-and-forget
+  queue after the result is already on its way to the host.
+
+**Acceptance:** an upstream exposing prompts and resources is fully usable through
+the proxy — `prompts/list` and `resources/read` reach it and return.
+
+### Phase 4 — Recorder and auth
+
+1. Port RRepeat's `auth/client.ts` (login, `saveCredentials`, refresh-on-401).
+2. Port `RemoteRecorder` unchanged in shape: client-generated `run_`/`step_` uuids,
+   a per-run ordered promise chain, best-effort sends, one token refresh on 401.
+   Endpoints, already live: `POST /recordings/runs`,
+   `POST /recordings/runs/:id/steps`, `PATCH /recordings/runs/:id/steps/:stepId`,
+   `POST /recordings/runs/:id/finish`.
+3. `redact.ts` — scrub before anything leaves the process. Minimum: values under
+   keys matching `/(token|secret|password|api[_-]?key|authorization|cookie)/i`,
+   anything matching a bearer/JWT/`sk-` shape, and `env` blocks. Applied to
+   arguments *and* results.
+4. `truncate.ts` — cap each payload (suggest 64 KiB) with an explicit
+   `{ truncated: true, originalBytes }` marker. Base64 image blocks from browser
+   MCPs will otherwise dominate every run.
+
+**Acceptance:** a Tier 2 run appears in the BaseIn service with correct steps and
+no secret material, verified by a redaction fixture.
+
+### Phase 5 — Control plane and the hook binary (Tier 1)
+
+**Discovery.** The control server writes
+`~/.baseinstrunner/control/<sha256(cwd).slice(0,16)>.json`:
+
+```json
+{ "url": "http://127.0.0.1:53411",
+  "token": "<random 32 bytes, hex>",
+  "sessionId": "...",
+  "pid": 12345,
+  "startedAt": 1756600000000 }
+```
+
+A proxy resolves it in this order: `BIR_CONTROL_URL` env (injected into generated
+config, and the only reliable channel for SDK sessions) → the discovery file for
+its cwd → give up. Give-up is bounded: **buffer steps in memory for up to 5 s while
+retrying**, then fall to Tier 2 and flush the buffer into a self-owned run. The
+window exists because the host may spawn MCP servers before `SessionStart` fires;
+the ordering between the two is not guaranteed.
+
+**Control server HTTP surface** (loopback only, ephemeral port, bearer token from
+the discovery file required on every route):
+
+| Route | Caller | Purpose |
+|---|---|---|
+| `POST /session/start` | hook | Open the run; returns `runId` |
+| `POST /session/prompt` | hook | `UserPromptSubmit` — the run's `input` |
+| `POST /tool/pre` | hook | Built-in step opened; returns `{ stepIndex, callId? }` |
+| `POST /tool/post` | hook | Built-in step closed with its result |
+| `POST /session/stop` | hook | Final answer |
+| `POST /session/end` | hook | `finishRun` + flush |
+| `POST /proxy/register` | proxy | `{ serverName, pid, cwd }` → `{ runId, sessionId }` |
+| `POST /proxy/step` | proxy | A `ProxyStepReport`; allocates `stepIndex` |
+| `GET /health` | CLI | `bir doctor` |
+
+**Ordering.** `ordering.ts` hands out `stepIndex` from one counter shared by hook
+and proxy reports. Allocation happens at *report* time, not call time, so
+concurrent MCP calls are ordered by completion — deterministic, and honest about
+what actually happened.
+
+**Hook wiring.** `bir-hooks` registers `UserPromptSubmit`, `PreToolUse`,
+`PostToolUse`, `PostToolUseFailure`, `Stop`, `StopFailure`, `SessionStart`,
+`SessionEnd`. Use `PostToolUseFailure` rather than inferring failure from
+`PostToolUse` shape, and `SubagentStart` / `SubagentStop` (which carry `agent_id`)
+to attribute subagent steps correctly.
+
+**Acceptance:** a Claude Code session running one built-in and one MCP tool
+produces a single run whose steps are in true execution order.
+
+### Phase 6 — Correlation and dedupe
+
+In Tier 1 a wrapped MCP call is seen **twice**: once by the hook at `PreToolUse`,
+once by the proxy at `tools/call`. Without correlation you double-record.
+
+**Mechanism.** At `PreToolUse` for a wrapped `mcp__*` tool, the hook returns
+`permissionDecision: "allow"` with `updatedInput = { ...original, [BIR_CALL_ID]: id }`.
+The proxy strips that key before relaying and echoes it on its step report. The
+control server merges the two views into one step:
+
+- the hook contributes identity, `tool_use_id`, ordering position, and the model's
+  original arguments;
+- the proxy contributes the true upstream result, `isError`, `structuredContent`,
+  and real execution duration.
+
+This is RRepeat's `RREPEAT_SENTINEL` trick generalised, so it is proven — but
+inherit its cost knowingly: **carrying an extra argument requires relaxing the
+tool's schema** (`additionalProperties: true` plus the declared key), and that
+relaxation is visible to the model on every call, not only recorded ones.
+Therefore:
+
+- Apply relaxation **only** when Tier 1 correlation is active. Tier 2 never relaxes.
+- Relax **only** wrapped servers.
+- Provide `--no-correlation`, falling back to fingerprint matching —
+  `(serverName, toolName, hash(args))` inside a 30 s window — for hosts where
+  schema relaxation is unacceptable. Document it as lossy under identical
+  concurrent calls.
+
+**Acceptance:** one MCP call in a Claude Code session produces exactly one step,
+carrying both the model's arguments and the upstream's real result.
+
+### Phase 7 — Config generation and the CLI
+
+1. `config/adapters/claude-code.ts` — merge the three scopes in Claude Code's own
+   precedence order: **Local** (`~/.claude.json` → `projects[<cwd>].mcpServers`)
+   beats **Project** (`<cwd>/.mcp.json`) beats **User** (`~/.claude.json` top-level).
+   Match the local-scope key on a *normalised* path: Claude Code stores forward
+   slashes on Windows while `process.cwd()` returns backslashes. Getting this wrong
+   is the number one cause of "the proxy is installed but never runs".
+2. `config/generate.ts` — rewrite each resolved entry in place, keeping the key:
+   ```json
+   "chrome-devtools": {
+     "command": "npx",
+     "args": ["-y", "-p", "baseinstrunner", "bir-proxy",
+              "--server-name", "chrome-devtools", "--",
+              "<original command>", "<original args...>"],
+     "env": { "BIR_CONTROL_URL": "http://127.0.0.1:53411" }
+   }
+   ```
+   Remote entries become
+   `bir-proxy --server-name X --url <url> --transport http`.
+3. **Write to the winning scope.** If a local-scope entry shadows the project one,
+   rewriting `.mcp.json` changes nothing. Detect this and warn loudly.
+4. Reversibility: stash each original entry in a sidecar
+   (`~/.baseinstrunner/installed.json`) so `bir uninstall` restores exactly.
+5. `bir doctor` — resolve config, list which servers are wrapped, query the control
+   server's `/health`, and confirm every wrapped name has a *registered* proxy.
+   Registration at the control server is the guarantee check; do not infer it from
+   the config file, and do not infer it from `serverInfo` (which must stay the
+   upstream's, per Phase 3).
+6. `bir wrap -- <cmd>` — manual single-server mode for clients with no adapter.
+   This is what makes D8 real: the generic path never needs to know where a client
+   stores its settings.
+
+**Acceptance:** `bir install` on a project with three MCP servers wraps all three,
+`bir doctor` reports three registered proxies, and `bir uninstall` restores the
+file byte-for-byte.
+
+### Phase 8 — Hardening
+
+- **Backpressure.** Bound the step queue (suggest 1000). On overflow, drop oldest
+  and set `lossy: true` on the run. Never block a tool call on the recorder.
+- **Degradation matrix** — §10, implemented as explicit branches, each with a test.
+- **Startup cost.** N upstreams means N proxy processes *plus* N upstream processes.
+  Measure session-start latency; if it matters, add `--lazy` to defer the upstream
+  spawn until the first `tools/list`.
+- **Windows.** `spawn` with `shell: false` and explicit `.cmd` resolution for `npx`;
+  path normalisation in the local-scope key; no assumptions about `$HOME`.
+
+---
+
+## 7. What a recorded step looks like
+
+Mapped onto the existing BaseIn endpoints, one MCP call becomes two rows, exactly
+as RRepeat records them today:
+
+```
+POST /recordings/runs/:runId/steps
+  { id, stepIndex: 7, type: "tool_selected",
+    toolName: "mcp__chrome-devtools__navigate_page",
+    toolInput: "{\"url\":\"https://example.com\"}",
+    context: "<model reasoning, Tier 1 only>" }
+
+POST /recordings/runs/:runId/steps
+  { id, stepIndex: 8, type: "tool_response",
+    toolName: "mcp__chrome-devtools__navigate_page",
+    toolOutput: "<serialised CallToolResult, redacted, truncated>" }
+```
+
+Run `metadata` carries what is new, and what BaseIn-side consumers will need:
+
+```json
+{ "recorder": "baseinstrunner",
+  "tier": "bound",
+  "host": { "app": "claude-code", "version": "2.1.251" },
+  "wrappedServers": ["chrome-devtools", "github"],
+  "lossy": false }
+```
+
+`tier` is the field that stops a Tier 2 partial trace being mistaken for a
+complete one.
+
+---
+
+## 8. Full-passthrough method map
+
+For implementers. The relay does not branch on these — the table documents what
+must *survive* the relay, and is the basis of the conformance suite.
+
+**Host → upstream:** `initialize`, `notifications/initialized`, `ping`,
+`tools/list`, `tools/call`, `prompts/list`, `prompts/get`, `resources/list`,
+`resources/templates/list`, `resources/read`, `resources/subscribe`,
+`resources/unsubscribe`, `completion/complete`, `logging/setLevel`,
+`notifications/cancelled`, `notifications/progress`,
+`notifications/roots/list_changed`.
+
+**Upstream → host:** `sampling/createMessage`, `elicitation/create`, `roots/list`,
+`notifications/message`, `notifications/progress`, `notifications/cancelled`,
+`notifications/tools/list_changed`, `notifications/resources/list_changed`,
+`notifications/resources/updated`, `notifications/prompts/list_changed`.
+
+The reverse direction is precisely why a `tools/*`-only bridge is not enough: an
+upstream that issues `elicitation/create` and receives no answer **hangs**. Claude
+Code surfaces these as the `Elicitation` hook event, so a dropped one is at least
+observable.
+
+---
+
+## 9. Security
+
+- The proxy sits on the credential path for every wrapped server. For remote
+  upstreams it holds the headers, because the host's own OAuth flow authenticates
+  the server it is *configured with* — which is now the proxy. Store nothing; read
+  from env or the OS keychain at spawn.
+- Every argument and result crosses a process boundary and then the network.
+  Redaction (Phase 4.3) runs before both.
+- The control server binds `127.0.0.1` only, on an ephemeral port, and requires the
+  token from the discovery file on every route. A local port that accepts
+  unauthenticated step reports is a local exfiltration channel.
+- Discovery files are mode `0600`.
+- `bir doctor` prints exactly which servers are wrapped, so a proxy can never sit
+  in the path invisibly.
+
+---
+
+## 10. Degradation matrix
+
+The governing rule: **the host session must never fail because of BaseInstRunner.**
+
+| Failure | Behaviour |
+|---|---|
+| Control server unreachable at startup | Buffer <= 5 s, then Tier 2; log once to stderr |
+| Control server dies mid-session | Proxy switches to Tier 2 for the remainder; run flagged `lossy` |
+| Recorder HTTP fails | Drop the send, log, continue. Never retry inline |
+| Upstream fails to start | `initialize` still answers; `tools/list` returns an error. The host shows one broken server, not a broken session |
+| Upstream dies mid-call | Return `isError: true` with the transport message as content — a tool failure the model can react to, not a protocol error |
+| Unknown JSON-RPC method | Forward it. If the upstream rejects, relay the rejection |
+| Step queue overflow | Drop oldest, flag the run `lossy` |
+| Schema relaxation rejected by host | Disable correlation, fall back to fingerprint matching |
+
+---
+
+## 11. Testing
+
+1. **Transcript identity (the core test).** Record a golden JSON-RPC transcript
+   against a real upstream directly, then through the proxy. Every host-visible
+   byte except timing must match. Run it for stdio, http and sse.
+2. **`fake-upstream.ts`** — a scriptable MCP server that can advertise arbitrary
+   capabilities, emit `notifications/tools/list_changed`, issue
+   `elicitation/create`, delay, and die on command. Everything below builds on it.
+3. **Passthrough conformance** — one case per row of §8, both directions.
+4. **Correlation** — a fake hook injecting `__bir_call_id__`; assert exactly one
+   merged step. Then the `--no-correlation` fingerprint path, including the known
+   ambiguity under identical concurrent calls.
+5. **Config adapter** — fixture `~/.claude.json` + `.mcp.json` pairs covering scope
+   precedence, the Windows path-normalisation case, remote entries, already-wrapped
+   entries (idempotent install), and reserved names.
+6. **Redaction** — assert no fixture secret reaches the recorder.
+7. **Integration** — a real Claude Code session against `fake-upstream`, asserting
+   run shape end to end. The only test that catches host-behaviour drift.
+
+---
+
+## 12. Milestones
+
+| Milestone | Phases | Deliverable |
+|---|---|---|
+| **M1 — Invisible proxy** | 0–2 | `bir-proxy` wraps any upstream with zero observable difference |
+| **M2 — Standalone recording** | 3–4 | Tier 2 runs land in BaseIn. Works with any MCP client, today |
+| **M3 — Bound recording** | 5–6 | Tier 1: built-ins + MCP, one ordered stream, deduped |
+| **M4 — Product** | 7–8 | `bir install / doctor / uninstall`, hardened, documented |
+| **v2 — Replay** | R0–R7 | Run a calculated scenario on a similar-meaning match. Designed in [calculatedReplay.md](calculatedReplay.md); the runbook is [calculatedReplayGuide.md](calculatedReplayGuide.md) |
+
+M2 is the first genuinely useful release, and it does not depend on hooks at all —
+ship it before touching the control plane.
+
+---
+
+## 13. Open questions
+
+1. **Does the BaseIn service need `tier` / `lossy` as real columns**, or is run
+   `metadata` enough for the savings pipeline to exclude partial traces from
+   baselines? A Tier 2 run has no prompt, so similarity matching on `input` behaves
+   differently.
+2. **Coexistence with RRepeat.** If both are installed, both record the same session
+   into the same service. Should `bir-hooks` detect `rrepeat-hooks` and refuse, or
+   should runs carry a `recorder` discriminator and be deduped server-side? §7's
+   metadata assumes the latter.
+3. **`--lazy` upstream spawn** — worth it, or are N idle upstream processes
+   acceptable? Needs a measurement on a realistic five-server config before deciding.
+4. **Fingerprint fallback under concurrency.** Two identical parallel `tools/call`s
+   are genuinely indistinguishable without a call id. Accept the ambiguity, or make
+   correlation mandatory for Tier 1?