@basein/runner 0.2.11 → 0.3.0

package/docs/BaseInstRunner.md

@@ -1,621 +1,694 @@
-# 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?
+# 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:** the design the runner was built from. Parts of it (the tiers,
+> correlation, the degradation matrix) have since been revised to match the
+> implementation. The production contract — measurements, environment variables,
+> the operations runbook — is [production.md](../production.md).
+> **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 and a passthrough that records nothing:
+
+| 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 |
+| **Passthrough** | No control server, for a Claude Code user-scope entry wrapped by `bir install`, in a directory that was never installed and has no recorder | Nobody | Nothing. The proxy relays and uploads nothing |
+
+Passthrough exists because a user-scope server is wrapped once, in one project, but
+Claude Code starts it in every project, and Tier 2 there would upload that project's
+tool traffic without anyone having asked. Every other entry — one written by
+`bir install --config`, a project- or local-scope entry, a `bir wrap` entry, one
+without `BIR_CONTROL_URL` — falls to Tier 2 from any directory, and `--standalone`
+forces Tier 2.
+
+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 the entry's static headers for
+   auth, since the host's own OAuth handling does not survive a proxy in front of it
+   (§9). `bir install` writes them into the entry's env as `BIR_UPSTREAM_HEADERS`, a
+   JSON object of name to value, which the proxy reads once and removes from its
+   environment; `--header 'K: V'` is still accepted and wins on a clash. A remote
+   server Claude Code signs in itself (an `oauth` block, a `headersHelper`, `${VAR}`
+   headers, or no credential header) is left unwrapped unless `--server <name>`
+   names it.
+3. Lifecycle: an upstream that dies for good takes the proxy with it. When a stdio
+   upstream exits or cannot be spawned, or a legacy-SSE upstream's first connect
+   fails, answer the requests in flight, then exit with the upstream's exit status
+   (1 when it has none). The host then sees what it would see unwrapped: the server
+   failed, a reconnect offered, its tools gone from the model's list. `--restart`
+   first restarts a stdio upstream once and replays the host's handshake to it.
+   `BIR_PROXY_STAY_UP=1` keeps the earlier behaviour: stay up and answer every
+   request with an error.
+
+**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. Where a control server may inject a call id (Phase 6), declare the `__bir_call_id__` key on each tool's input schema. 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 that name a secret, anything matching a bearer/JWT/`sk-` shape, and `env`
+   blocks. Applied to arguments *and* results. Keys are matched on whole name
+   segments (`token`, `accessToken`, `x-api-key`, `basic_auth`, `api_keys`), not
+   as the substring `/(token|secret|password|api[_-]?key|authorization|cookie)/i`
+   first planned here, which also caught `max_tokens` and `nextPageToken` and lost
+   real arguments (0.2.12's wider rule, with a bare `auth`, caught `author` too).
+   `BIR_REDACT_LEGACY_KEYS=1` applies
+   0.2.12's substring rule as well.
+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` together with
+`BIR_CONTROL_TOKEN` in its env (the only reliable channel for SDK sessions) → the
+discovery file for its cwd, URL and token both → give up. The `BIR_CONTROL_URL`
+that install writes into a generated entry is not registered against on its own:
+for a user-scope server it names another project's recorder. Give-up is bounded:
+**buffer steps in memory for up to 10 s while retrying**, then fall to Tier 2 and
+flush the buffer into a self-owned run (or to passthrough, §0.1, which drops it).
+The window exists because the host may spawn MCP servers before `SessionStart`
+fires; the ordering between the two is not guaranteed. It is not a one-way door:
+while unbound, the proxy looks again every 15 s and binds when a recorder answers.
+
+**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 may return
+`updatedInput = { ...original, [BIR_CALL_ID]: id }`. The proxy strips that key
+before relaying and echoes it on its step report. Where no id rides along, the
+control server joins the proxy's report to the hook's call by fingerprint
+(below). Either way it 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 costs knowingly:
+
+- **An id rides only with a permission decision.** Claude Code takes
+  `updatedInput` together with `permissionDecision: "allow"`, and `allow` skips
+  the prompt the user would have seen for that call. So the hook injects an id
+  only where `allow` changes nothing the user is asked (a session in
+  `bypassPermissions` mode) or is answered anyway (a step a replay pinned, whose
+  `updatedInput` must be applied; replay is its own consent). Never in `plan`
+  mode, and never into a server with no live proxy to strip it. Every other call
+  gets no decision from the hook and joins by fingerprint.
+  `BIR_CORRELATION_DECISION=allow` in the recorder's environment injects with
+  `allow` for every wrapped call, auto-approving them all (0.2.12's behaviour);
+  `=ask` injects with `ask`, which keeps the prompt.
+- **The key has to be declared in the tool's schema** —
+  `__bir_call_id__: { type: "string", description: "Reserved. Leave unset." }` —
+  and that declaration is visible to the model on every call, not only recorded
+  ones. `additionalProperties` stays whatever the upstream declared.
+
+Therefore:
+
+- Declare the key **only** where a control server may inject one: while bound,
+  or while still negotiating in a directory set up for it (a discovery file, an
+  SDK channel or an install record), so a warm and a cold start show the model
+  the same schemas. Tier 2, passthrough and `bir off` never declare it.
+- Declare it **only** on wrapped servers.
+- Provide `--no-correlation` on the proxy (`bir install --no-correlation` writes
+  it), which declares nothing, and `BIR_NO_CORRELATION=1` on the recorder, which
+  injects nothing. Steps then join by fingerprint —
+  `(serverName, toolName, hash(args))`, the arguments hashed as they ran, before
+  redaction, within 10 minutes of the `PreToolUse` (the user may be reading a
+  permission prompt) — as every ordinary call does by default. 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` — generate a wrapped entry for each resolved one, 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`, with their headers in
+   `env.BIR_UPSTREAM_HEADERS`.
+3. **Write to the winning scope.** If a local-scope entry shadows the project one,
+   rewriting `.mcp.json` changes nothing. So the wrapped copy goes into this
+   project's local scope (`~/.claude.json` → `projects[<key>].mcpServers`, keyed
+   the way Claude Code keys it), which beats both other scopes; `.mcp.json` and the
+   user scope are never wrapped in place (`--mcp-json` or `BIR_WRAP_MCP_JSON=1` keeps the
+   old in-place shape). Claude Code never asks about a local-scope server, so a
+   `.mcp.json` server is copied only once Claude Code has approved it (a rejected
+   one never; `--server <name>` wraps one it has not asked about yet), and under a
+   managed policy that allows only its own MCP servers, or matches them by command
+   or URL, nothing is wrapped.
+4. Reversibility: stash each original entry in a sidecar
+   (`~/.baseinstrunner/installed.json`) so `bir uninstall` restores it: project
+   files byte for byte unless edited since, `~/.claude.json` entry by entry.
+   Credential values are not stashed; uninstall reads them back from the wrapped
+   entry. `bir uninstall --all` does this for every project on the machine.
+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 approved MCP servers wraps all
+three, `bir doctor` reports three registered proxies, and `bir uninstall` puts back
+every entry and file it changed (the team's `.mcp.json` was never touched).
+
+### Phase 8 — Hardening
+
+- **Backpressure.** Bound the step queue (250 reports in the proxy,
+  `STEP_BACKLOG`). 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. So a remote server Claude Code signs in
+  itself is left unwrapped by default (Phase 2). Static headers reach the proxy in
+  `BIR_UPSTREAM_HEADERS`, which it removes from its environment once read, and go
+  only to the configured origin: a redirect to another origin drops them all, and
+  a redirect from https to plain http (off loopback) is refused.
+- 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 <= 10 s while retrying, then Tier 2 (passthrough for an entry that may not record here, §0.1). Keep looking every 15 s; bind when a recorder answers |
+| Control server dies mid-session | Log `tier.downgrade`; what follows goes to a Tier 2 run of the proxy's own (at most one per proxy; none where the entry may not record), flagged `lossy`, until a recorder answers again. A bound proxy in an installed project whose recorder died (pid gone, port refusing) starts it again in the background (`bir-hooks revive`); a recorder stopped with `bir down` stays stopped |
+| Recorder HTTP fails | Drop the send, log once per run, continue. Never retry inline: a background send is retried once, and only after a 429/503 or a connection that never reached the service. After a failure, hooks stop waiting on the service for a cool-down (5 s, doubling to 60 s) |
+| Upstream fails to start, or exits | Answer the requests in flight, then exit with the upstream's status (1 if it had none). The host shows that one server failed, with a reconnect offered, as it would unwrapped. `BIR_PROXY_STAY_UP=1` keeps the proxy up instead, answering every request `MCP server "x" is not available` |
+| A stdio upstream dies mid-call | Return `isError: true` with `MCP server "x" is not available` as content — a tool failure the model can react to, not a protocol error — then exit as above |
+| Remote upstream unreachable or refusing | The proxy stays up and answers each request with a short JSON-RPC error that never echoes the server's body (`upstream unreachable: …`, `upstream requires sign-in (HTTP 401)`). Only connecting is bounded (10 s, `BIR_UPSTREAM_CONNECT_TIMEOUT_MS`); a slow tool is the host's to time out |
+| Upstream answer too large (128 MiB by default) | End the host's call with an error instead of buffering it: `isError` `The result was too large to deliver (…)` from a stdio server (a -32000 error for other methods), `upstream answer too large` from a remote one (`BIR_UPSTREAM_MAX_MESSAGE_BYTES`). An oversized notification from a stdio server is dropped; an oversized server-to-client request is refused with -32600 |
+| Unknown JSON-RPC method | Forward it. If the upstream rejects, relay the rejection |
+| Step queue overflow | Drop oldest, flag the run `lossy` |
+| Call-id key unwanted, or an injected id never echoed | `--no-correlation` on the proxy declares nothing; `BIR_NO_CORRELATION=1` on the recorder injects nothing. An injected id that no report echoes stops further ids to that server for the session. Either way steps join by fingerprint (Phase 6) |
+| Runner switched off (`bir off`, `bir off --here`, `BIR_OFF=1`) | A stdio proxy started while off runs the real server itself, with inherited stdio and its exit code; a remote one relays without recording. Switched off mid-session, a proxy stops recording and declaring the key within about 1 s and keeps relaying. Hook routes answer `{}` |
+
+---
+
+## 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?