@basein/runner 0.3.8 → 0.3.10

package/dist/replay/derive.js

@@ -32,6 +32,7 @@
  */
 import { redactText } from "../record/redact.js";
 import { isUnhealthyStatus, serviceHealth, timeoutSignal } from "../util/service-health.js";
+import { serviceHeaders } from "../util/service-headers.js";
 import { calculateCostUsd } from "./pricing.js";
 export const DEFAULT_DERIVE_MODEL = "claude-haiku-4-5-20251001";
 const ANTHROPIC_URL = "https://api.anthropic.com/v1/messages";
@@ -311,6 +312,7 @@ async function deriveViaService(opts, service, schema, keys) {
             headers: {
                 "content-type": "application/json",
                 authorization: `Bearer ${service.token}`,
+                ...serviceHeaders(),
             },
             body: JSON.stringify({
                 prompt: outgoingPrompt(opts.prompt),

package/dist/replay/handover.d.ts

@@ -45,7 +45,19 @@ export type HandoverStopReason =
 /** The run was cancelled before it. */
  | "cancelled"
 /** Another of the plan's calls was still in flight (steer mode runs one at a time). */
- | "concurrent";
+ | "concurrent"
+/**
+ * A host that is not Claude Code wrote the step's result itself, and its
+ * tool never ran: a person said no, a person answered in the tool's place,
+ * or a call limit blocked the call. Not a fault of the plan.
+ */
+ | "host_rejected"
+/**
+ * The step's tool ran in such a host, with arguments a person chose in
+ * place of the plan's. Its result is real; the plan's later steps were
+ * computed for the call it planned, so it stops there.
+ */
+ | "host_edited";
 export interface HandoverNoteInput {
     intent: string;
     kind: FallbackKind;

package/dist/replay/handover.js

@@ -56,6 +56,12 @@ export function buildHandoverNote(n) {
         // says it may have completed.
         lines.push("No step of the scenario is known to have finished; the task is yours.");
     }
+    else if (n.stopReason === "host_rejected" || n.stopReason === "host_edited") {
+        // The first step was answered by the host, or ran with a person's
+        // arguments: "the whole task is yours" would invite the model to do that
+        // step over, which the next line tells it not to.
+        lines.push("No step of the scenario ran as it was planned.");
+    }
     else {
         lines.push("No step of the scenario ran; the whole task is yours.");
     }
@@ -109,6 +115,19 @@ export function buildHandoverNote(n) {
 function stepFailedLine(n, human, tool) {
     const at = `Step ${human} of ${n.totalSteps}${tool}`;
     const detail = n.error ? truncate(n.error, MAX_ERROR_CHARS) : "";
+    // The two stops a host that is not Claude Code reports, first: neither is
+    // a failure, and neither is the model's to make good.
+    if (n.stopReason === "host_rejected") {
+        // One sentence for three causes — a person said no, a person answered in
+        // the tool's place, a call limit blocked the call — so it names none of
+        // them, and never says "do it yourself": the person may have meant no.
+        return (`${at} was not run by the host. The result above was written by the host, not by the tool. ` +
+            "Do not run the step again unless the user asks.");
+    }
+    if (n.stopReason === "host_edited") {
+        return (`${at} ran with arguments a person chose, not the scenario's. Its result above is real ` +
+            "and its side effects are in place. Do not run it again.");
+    }
     if (n.ranThisStep) {
         // Its tool ran and did its work; only the scenario's reading of the result
         // broke. A model told "failed" here runs the write again.

package/dist/replay/plan.d.ts

@@ -105,6 +105,12 @@ export interface StepInfo {
      */
     entry?: FlatEntry;
     input: Record<string, unknown>;
+    /**
+     * What the step's output logic was given: the tool's answer, or for
+     * `recorded` the source run's output that stood in for it. Absent when the
+     * call produced none — `skipped`, or a failure before the tool ran.
+     */
+    output?: string;
     outcome: "executed" | "recorded" | "skipped" | "failed";
     /** Which part of the step broke. Only set for `failed`. */
     stage?: ExecutionStage;

package/dist/replay/plan.js

@@ -215,8 +215,11 @@ function settingsOf(paramsObject, mapped) {
  * still abandons the whole bundle rather than shipping a half-computed one. All
  * this adds is that the failure is now *attributable* — "step 2's tool input
  * logic", rather than a stack trace the console cannot line up against a chain.
+ *
+ * `output` is what the body was given, for a stage that runs on one: a throw
+ * in the output logic is only readable next to the output it threw on.
  */
-function reportingStage(onStep, entry, stage, input, startedAt, fn) {
+function reportingStage(onStep, entry, stage, input, startedAt, fn, output) {
     try {
         return fn();
     }
@@ -225,6 +228,7 @@ function reportingStage(onStep, entry, stage, input, startedAt, fn) {
             step: entry.step,
             entry,
             input,
+            output,
             outcome: "failed",
             stage,
             error: err instanceof Error ? err.message : String(err),
@@ -817,6 +821,7 @@ export class ScenarioReplayPlan {
                         step,
                         entry,
                         input: computed,
+                        output: response,
                         outcome: "failed",
                         stage: "tool_call",
                         error: toolError,
@@ -845,7 +850,7 @@ export class ScenarioReplayPlan {
                         Object.assign(resp.get(entry.frame.id) ?? {}, derived);
                     }
                     this.leaveFrame(entry, resp);
-                });
+                }, response);
             }
             catch (err) {
                 if (!stopOnFailure)
@@ -872,6 +877,7 @@ export class ScenarioReplayPlan {
                     step,
                     entry,
                     input: computed,
+                    output: response,
                     outcome: error ? "failed" : "executed",
                     stage: error ? "tool_call" : undefined,
                     error,
@@ -977,6 +983,7 @@ export class ScenarioReplayPlan {
                         step,
                         entry,
                         input: computed,
+                        output: response,
                         outcome: "failed",
                         stage: "tool_call",
                         error: toolError,
@@ -997,7 +1004,7 @@ export class ScenarioReplayPlan {
             }
             let derivedKeys;
             try {
-                derivedKeys = reportingStage(onStep, entry, "tool_output_logic", computed, startedAt, () => this.applyOutput(response));
+                derivedKeys = reportingStage(onStep, entry, "tool_output_logic", computed, startedAt, () => this.applyOutput(response), response);
             }
             catch (err) {
                 if (!stopOnFailure)
@@ -1024,6 +1031,7 @@ export class ScenarioReplayPlan {
                     step,
                     entry,
                     input: computed,
+                    output: response,
                     outcome: error ? "failed" : "executed",
                     stage: error ? "tool_call" : undefined,
                     error,
@@ -1095,6 +1103,8 @@ export class ScenarioReplayPlan {
                 step,
                 entry,
                 input: computed,
+                // The stand-in is what the step's output logic runs on from here.
+                output: standIn,
                 outcome: standIn !== undefined ? "recorded" : "skipped",
                 error,
                 toolMissing: isMissingToolError(error) || undefined,

package/dist/replay/safety.d.ts

@@ -43,16 +43,27 @@ import type { ParamsSchema } from "./types.js";
  * or a database, `write` is only written into a file.
  */
 export type SinkKind = "command" | "write";
+/**
+ * The sinks a host that is not Claude Code declared for its own tools, by
+ * tool name. Passing one — even an empty one — says the tool names are that
+ * host's: `Bash`, `Edit` and `mcp__server__tool` then mean nothing by
+ * themselves. A tool the host declared is what it was declared; any other is
+ * judged by the words of its plain name (`run_sql`, `execQuery`).
+ */
+export interface HostSinks {
+    command?: readonly string[];
+    write?: readonly string[];
+}
 /** Whether this tool's input is run by a shell. */
-export declare function isShellTool(toolName: string | null | undefined): boolean;
+export declare function isShellTool(toolName: string | null | undefined, host?: HostSinks): boolean;
 /** How this tool consumes its input, or undefined when it is neither run nor written. */
-export declare function sinkOf(toolName: string | null | undefined): SinkKind | undefined;
+export declare function sinkOf(toolName: string | null | undefined, host?: HostSinks): SinkKind | undefined;
 /** Whether this tool's input is run or written: a shell, a file edit, a query. */
 export declare function isCommandSink(toolName: string | null | undefined): boolean;
 /** The strictest sink among the planned steps, or undefined when there is none. */
-export declare function sinkOfPlan(entries: readonly FlatEntry[]): SinkKind | undefined;
+export declare function sinkOfPlan(entries: readonly FlatEntry[], host?: HostSinks): SinkKind | undefined;
 /** Whether any planned step runs its input through a shell. */
-export declare function hasShellStep(entries: readonly FlatEntry[]): boolean;
+export declare function hasShellStep(entries: readonly FlatEntry[], host?: HostSinks): boolean;
 /** Whether any planned step's input is run or written. */
 export declare function hasCommandSink(entries: readonly FlatEntry[]): boolean;
 /**

package/dist/replay/safety.js

@@ -84,16 +84,29 @@ const UNSAFE = /[`$;&|<>\\"'\r\n\u0000]|--|\/\*/;
  * apostrophe, at the cost of a denied call and a model round trip each time.
  */
 const WRITE_UNSAFE = /[\r\n\u0000]/;
+/** Whether a plain tool name of another host says its input is run. */
+function plainNameSays(name, words) {
+    return words.test(nameWords(name));
+}
 /** Whether this tool's input is run by a shell. */
-export function isShellTool(toolName) {
+export function isShellTool(toolName, host) {
     const name = toolName ?? "";
+    if (host)
+        return plainNameSays(name, MCP_SHELL_WORD);
     if (SHELL_BUILTINS.has(name))
         return true;
     return mcpNameSays(name, MCP_SHELL_WORD);
 }
 /** How this tool consumes its input, or undefined when it is neither run nor written. */
-export function sinkOf(toolName) {
+export function sinkOf(toolName, host) {
     const name = toolName ?? "";
+    if (host) {
+        if (host.command?.includes(name))
+            return "command";
+        if (host.write?.includes(name))
+            return "write";
+        return plainNameSays(name, MCP_COMMAND_WORD) ? "command" : undefined;
+    }
     if (SHELL_BUILTINS.has(name))
         return "command";
     if (WRITE_BUILTINS.has(name))
@@ -105,10 +118,10 @@ export function isCommandSink(toolName) {
     return sinkOf(toolName) !== undefined;
 }
 /** The strictest sink among the planned steps, or undefined when there is none. */
-export function sinkOfPlan(entries) {
+export function sinkOfPlan(entries, host) {
     let found;
     for (const e of entries) {
-        const sink = sinkOf(e.step.toolName);
+        const sink = sinkOf(e.step.toolName, host);
         if (sink === "command")
             return sink;
         found ??= sink;
@@ -116,8 +129,8 @@ export function sinkOfPlan(entries) {
     return found;
 }
 /** Whether any planned step runs its input through a shell. */
-export function hasShellStep(entries) {
-    return entries.some((e) => isShellTool(e.step.toolName));
+export function hasShellStep(entries, host) {
+    return entries.some((e) => isShellTool(e.step.toolName, host));
 }
 /** Whether any planned step's input is run or written. */
 export function hasCommandSink(entries) {

package/dist/replay/source-run.js

@@ -40,6 +40,7 @@
  */
 import { logDetail, logLine, errText } from "../util/log.js";
 import { isUnhealthyStatus, serviceHealth, serviceTimeoutMs, timeoutSignal, } from "../util/service-health.js";
+import { serviceHeaders } from "../util/service-headers.js";
 export class SourceRunCache {
     opts;
     /** run id → every recorded output of that run, in order. */
@@ -109,7 +110,7 @@ export class SourceRunCache {
         let res;
         try {
             res = await doFetch(`${this.opts.baseUrl.replace(/\/+$/, "")}/recordings/runs/${runId}`, {
-                headers: { authorization: `Bearer ${token}` },
+                headers: { authorization: `Bearer ${token}`, ...serviceHeaders() },
                 signal: timeoutSignal(this.opts.timeoutMs ?? serviceTimeoutMs()),
             });
         }

package/dist/replay/types.d.ts

@@ -249,6 +249,22 @@ export interface ExecutionStepResult {
     /** Message only — never a tool payload; this is rendered in a web page. */
     error?: string;
     durationMs?: number;
+    /**
+     * What the step sent its tool on this run: the arguments its input logic
+     * computed, serialized and redacted as a recorded step's are, and cut to
+     * what a report carries. Absent when the step broke before it had any.
+     *
+     * Without the two payloads the scenario's page can only put the recording's
+     * sample under this run's verdict and time — a call that was not made, and
+     * an answer that was not given, on a card that says "passed".
+     */
+    toolInput?: string;
+    /**
+     * What the step's output logic was given, on the same terms: the tool's
+     * answer, or for `recorded` the source run's output that stood in for it.
+     * Absent on a step that got none.
+     */
+    toolOutput?: string;
     /**
      * The step's tool no longer exists on its server, read from the error text
      * (plan-services.md D8, kind 2). The service then repairs the plan without

package/dist/util/service-headers.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The contract this runner follows. It goes up by one, together with the
+ * service's own number, when the service starts to rely on something a runner
+ * must do — never for a field a runner may ignore.
+ *
+ * - **1** — stops in front of a step that carries `stop`, and reads
+ *   `withheld: "runner_update_required"` on a match.
+ */
+export declare const CONTRACT = 1;
+/** Spread into the `headers` of a request to the service. */
+export declare function serviceHeaders(): Record<string, string>;
+/**
+ * `bir doctor`'s line for a service that hands plans only to a newer runner
+ * than this one: its `/health` names the lowest contract it serves
+ * (`minRunner`). Undefined when this runner is new enough, and when the
+ * service is an older one that names no minimum.
+ */
+export declare function runnerOutdated(service: {
+    minRunner?: number;
+} | undefined, ours?: {
+    contract: number;
+    version: string;
+}): string | undefined;
+//# sourceMappingURL=service-headers.d.ts.map

package/dist/util/service-headers.js

@@ -0,0 +1,47 @@
+/**
+ * The two headers every call to the BaseIn service carries, so the service
+ * knows which runner it is talking to.
+ *
+ * WHY. The service hands every runner the same plan, and a safety mark added to
+ * a plan later works only in a runner that knows it. With these the service can
+ * count the versions in use, and hand no plan to a runner too old for it — the
+ * agent then does the task, and `bir doctor` says to update.
+ *
+ * `x-bir-version` is this package's version. `x-bir-contract` is
+ * {@link CONTRACT}: the newest set of rules this runner follows.
+ *
+ * On every call to the service, signed in or not, and never on a call to
+ * anyone else: not to Anthropic (replay/derive.ts), not to an upstream MCP
+ * server, not to the local control server.
+ */
+import { packageVersion } from "./version.js";
+/**
+ * The contract this runner follows. It goes up by one, together with the
+ * service's own number, when the service starts to rely on something a runner
+ * must do — never for a field a runner may ignore.
+ *
+ * - **1** — stops in front of a step that carries `stop`, and reads
+ *   `withheld: "runner_update_required"` on a match.
+ */
+export const CONTRACT = 1;
+/** Spread into the `headers` of a request to the service. */
+export function serviceHeaders() {
+    return {
+        "x-bir-version": packageVersion(),
+        "x-bir-contract": String(CONTRACT),
+    };
+}
+/**
+ * `bir doctor`'s line for a service that hands plans only to a newer runner
+ * than this one: its `/health` names the lowest contract it serves
+ * (`minRunner`). Undefined when this runner is new enough, and when the
+ * service is an older one that names no minimum.
+ */
+export function runnerOutdated(service, ours = { contract: CONTRACT, version: packageVersion() }) {
+    if (service?.minRunner === undefined || service.minRunner <= ours.contract)
+        return undefined;
+    return (`the BaseIn service hands plans only to a newer runner than this one (${ours.version}): ` +
+        "it still records, but nothing is replayed until it is updated — run `bir update`, " +
+        "then `bir setup` in each project that uses it");
+}
+//# sourceMappingURL=service-headers.js.map

package/docs/BaseInstRunner.md

@@ -411,7 +411,7 @@ the discovery file required on every route):
 | `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` |
+| `GET /health` | CLI, adapter | `bir doctor`; the adapter of another host reads `hostFields` (below) |
 
 **Ordering.** `ordering.ts` hands out `stepIndex` from one counter shared by hook
 and proxy reports. Allocation happens at *report* time, not call time, so
@@ -424,6 +424,99 @@ what actually happened.
 `PostToolUse` shape, and `SubagentStart` / `SubagentStop` (which carry `agent_id`)
 to attribute subagent steps correctly.
 
+**A host that is not Claude Code.** The same routes serve an agent that runs
+somewhere else. The one host `bir setup --host` knows is a LangChain
+application: a Python program whose agent is built with LangChain's
+`create_agent` and the package `langchain-basic2202`. The package (the adapter)
+is a LangChain middleware. It runs inside the application, sees every tool call
+itself, and finds the recorder by the folder's discovery file. The folder is set
+up with `bir setup --host langchain`, which gives it a port and a token of its
+own and starts the recorder. It writes no hooks and wraps no server
+([production.md](../production.md) §3.2). The how-to is `langChainGuide.md` in
+the repository's root; it is not in the npm package, and the Python package is
+not on PyPI yet.
+
+Claude Code's hooks are unchanged, and every new field is optional. A session
+whose requests carry `host` with an `app` other than `claude-code` is a session
+of another host. What such a host adds:
+
+| Route | Added | Meaning |
+|---|---|---|
+| every request | `host: { app, version?, adapter?, scope? }` | The host the session runs in. The session keeps the first one it names |
+| `POST /session/prompt` | `replay: true` | The adapter can step through a plan, and asks for one |
+| `POST /session/prompt` | `sinks: { command?: string[], write?: string[] }` | The host's tools whose input is run, or written into a file |
+| `POST /session/prompt` | answer: `plan: { scenarioId, mode, steps: [{ stepIndex, toolName }], stopAt? }` | The plan as data, beside the directive |
+| `POST /tool/pre` | `context: string`, `thinking: string` | What the model wrote, and what it reasoned, before the call |
+| `POST /tool/pre` | `scripted: true` | The adapter asks for the next step's arguments |
+| `POST /tool/pre` | `tools: [{ name }]` | The tools the agent holds, with the first such request of a run |
+| `POST /tool/pre` | answer: `noPlan: true`, or `declined: "host_tool_missing"` | Why a request for a step got none |
+| `POST /tool/post` | `scripted: true` | The result of a call the adapter made for a step of the plan |
+| `POST /tool/post` | `host_stop: "rejected" \| "edited"` | The host stopped the step itself |
+| `POST /session/stop` | `final_answer: string` | The run's final answer |
+| `POST /session/stop` | `usage: [{ model, input_tokens, output_tokens, cache_read_input_tokens?, cache_creation_input_tokens? }]` | The tokens the run's model calls used, per model |
+| `POST /session/stop` | `failed: string`, `incomplete: string` | The run failed, or its recording is not the whole run, and why |
+| `GET /health` | answer: `hostFields: 2` | How much of this protocol the recorder understands. An adapter reads it before it relies on a field: with 1 it records, from 2 it may also ask for a plan and step through it |
+
+A prompt's `recent_results` (the conversation's earlier tool results, which an
+adapter used to send for the reading of new values) is no longer read. A new
+prompt's values are read from the prompt alone: an earlier turn's results are
+not this task's (the service's segmented.md, R-PARAM-2a).
+
+What the control server does for such a session:
+
+- **The run.** It is created with `framework` set to the app, or `app:scope`
+  (`langchain`, `langchain:billing`), and with the host in `metadata.host`. A
+  Claude Code run is created as before (`framework: "baseinstrunner"`). Only
+  `/session/prompt` opens a run. Any other request that finds none open records
+  nothing and is answered `{}`, or `{ noPlan: true }` when it asked for a step.
+- **The scope.** It keeps plans apart inside one account, and is part of the
+  run's `framework`. It is 1 to 64 characters and is never cut or dropped. A
+  session that names one the recorder cannot keep (empty, longer, or not a
+  text) has every request answered `{}`, and nothing of it is recorded or
+  replayed (`session.host_refused`).
+- **The plan.** One starts only for a prompt that said `replay: true`.
+  Otherwise a match is declined with `host_records_only`. The plan's mode is
+  always `steer`, and the runner runs no step itself: the host runs its own
+  tools. The prompt's answer carries the plan as data (`plan`), because the
+  directive beside it is a text written for a model.
+- **Tool names.** They carry no Claude Code meaning. `Bash`, `Read`,
+  `TodoWrite` or `ToolSearch` are the application's own tools there, and
+  nothing is skipped as housekeeping except the `bir` server's own tools.
+- **A step.** The adapter asks for each one (`scripted: true`). The answer is
+  the step's arguments (`hookSpecificOutput.updatedInput`), or
+  `{ noPlan: true }` when the recorder holds no live plan, or
+  `{ declined: "host_tool_missing" }` when the plan names a tool that is not in
+  `tools`.
+- **The model's own call.** A `/tool/pre` without `scripted` is the model's own
+  call, and is never given the plan's arguments. A plan that is live then is
+  handed over, and the hand-over note comes with that call's `/tool/post`.
+- **A step the host stopped.** `host_stop: "rejected"` means a person said no,
+  or answered in the tool's place, or a call limit blocked the call. `"edited"`
+  means a person changed the call. Either way the step's verdict is `skipped`,
+  not `failed`, and nothing is counted against the plan. After `rejected` the
+  report is `measured: false`; after `edited` the cost stays measured. Both are
+  `baselineEligible: false`.
+- **The cost.** It comes from `usage`, not from a transcript. It is measured
+  only when at least one entry has tokens and every model in the list has a
+  price. With more than one plan in one run, none is measured.
+- **The end.** `failed` closes the run with that text as its `error` (cleaned
+  of secrets, cut) and no final answer. `incomplete` marks the finish
+  `incomplete: { lostSteps, lossy }`; the finish carries that mark too when the
+  recorder itself lost one of the run's step sends. A run sealed after two
+  hours of silence is closed with `error: "turn ended early: idle"`. A run that
+  is closed while its plan is still live has the plan handed over first, so the
+  report says `fell_back` (a step ran) or `failed` (none ran), with
+  `measured: false` and `baselineEligible: false`.
+- **Sinks.** A value that a plan reads from the prompt is checked before it goes
+  into a tool the host declared in `sinks`, or one whose plain name has a
+  command word (`sql`, `query`, `exec`, `shell`, `command`, `script` and `eval`
+  among them).
+
+On the service's side, matching stays inside a host: a run created with
+`framework` `langchain` or `langchain:<scope>` is matched only against
+recordings and plans of that same text. Everything else is Claude Code's pool,
+as before. That part of the service is built and not deployed yet.
+
 **Acceptance:** a Claude Code session running one built-in and one MCP tool
 produces a single run whose steps are in true execution order.
 
@@ -574,6 +667,11 @@ Run `metadata` carries what is new, and what BaseIn-side consumers will need:
 `tier` is the field that stops a Tier 2 partial trace being mistaken for a
 complete one.
 
+A run of a host that is not Claude Code (Phase 5) names that host in
+`metadata.host` (`{ "app": "langchain", … }`), and is created with a `framework`
+of its own: the app, or `app:scope`. Its finish may carry an `error`, and the
+`incomplete` mark.
+
 ---
 
 ## 8. Full-passthrough method map
@@ -618,6 +716,11 @@ observable.
 - Discovery files are mode `0600`.
 - `bir doctor` prints exactly which servers are wrapped, so a proxy can never sit
   in the path invisibly.
+- A recorder started for a folder that is set up for another host and not for
+  Claude Code (Phase 5) gets a small environment, not the whole environment of
+  the window that started it. A plan's step code runs inside the recorder with
+  no sandbox, so a model key or a database password of the application must not
+  reach it. The names it keeps are in [production.md](../production.md) §9.
 
 ---
 
@@ -630,6 +733,7 @@ The governing rule: **the host session must never fail because of BaseInstRunner
 | 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) |
+| The service answers `429`: the account is over one of its limits (these are built in the service, and not deployed yet) | Send the create, the step or the report once more, at most 2 s later, then drop it (`recorder.send_failed` with `HTTP 429`). A dropped step is a hole in its recording, and a run whose create got a `429` runs without its plan. A `429` that the second try did not cure starts the same cool-down. The limits are in [production.md](../production.md) §3.3 |
 | 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 |
@@ -659,6 +763,9 @@ The governing rule: **the host session must never fail because of BaseInstRunner
 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.
+8. **Another host** — `examples/langchain-proof/`, in the repository and not in
+   the npm package: a real LangChain agent against the real recorder, with a
+   stand-in service and a fake model (Phase 5). Its README lists the cases.
 
 ---
 
@@ -683,6 +790,13 @@ ship it before touching the control plane.
    `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.
+   *Answered in part.* The service's new build (built, not deployed yet) lets a
+   finish say that the recording is not whole: `incomplete: { lostSteps, lossy }`.
+   A run with an `error`, or with that mark, is never picked for automatic
+   calculation and no longer catches its prompt, unless its owner preferred it
+   or it already has a plan. Today only a run of a host that is not Claude Code
+   (Phase 5) sends either: a Claude Code run that was interrupted or lost steps
+   is finished as before. The runner still sends `tier` in `metadata` only.
 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