@basein/runner 0.3.8 → 0.3.10

package/dist/control/transcript.d.ts

@@ -44,6 +44,10 @@ export declare function forgetTranscripts(): void;
  * learned from a tool, not from the user (segmented.md R-PARAM-2).
  *
  * "This prompt" is everything after the last user-role line that carries text.
+ * That is only true once the prompt is in the transcript, and at the prompt
+ * hook it is not yet: asked there, this returns the *previous* prompt's
+ * results. So the prompt hook does not ask (control/server.ts,
+ * `recentResultsFor`) — a prompt just submitted has no results anyway.
  * A transcript compacted mid-turn yields whatever follows that line, which may
  * be nothing; a transcript with no user prompt at all (a run opened by a proxy
  * step) yields nothing. Results with `is_error: true` are kept: a failure is

package/dist/control/transcript.js

@@ -410,6 +410,10 @@ export function forgetTranscripts() {
  * learned from a tool, not from the user (segmented.md R-PARAM-2).
  *
  * "This prompt" is everything after the last user-role line that carries text.
+ * That is only true once the prompt is in the transcript, and at the prompt
+ * hook it is not yet: asked there, this returns the *previous* prompt's
+ * results. So the prompt hook does not ask (control/server.ts,
+ * `recentResultsFor`) — a prompt just submitted has no results anyway.
  * A transcript compacted mid-turn yields whatever follows that line, which may
  * be nothing; a transcript with no user prompt at all (a run opened by a proxy
  * step) yields nothing. Results with `is_error: true` are kept: a failure is

package/dist/proxy/session.js

@@ -716,6 +716,7 @@ export class ProxySession {
             this.recorder = await this.buildRecorder();
             this.runId = this.recorder.startRun("", {
                 recorder: "baseinstrunner",
+                runnerVersion: packageVersion(),
                 tier: "standalone",
                 host: { app: process.env.BIR_HOST_APP ?? "unknown", version: process.env.BIR_HOST_VERSION },
                 wrappedServers: [this.serverName],

package/dist/record/housekeeping.d.ts

@@ -68,8 +68,14 @@ export declare const RUN_SCENARIO_TOOL = "mcp__bir__run_scenario";
  * Whether one call is host housekeeping: never recorded as a step, never a
  * divergence from a plan. `toolInput` is what the hook saw (`tool_input`); only
  * a `Bash` call's `command` is read from it.
+ *
+ * `otherHost` is a session whose host is not Claude Code. Its tool names are
+ * its own: a tool it calls `TodoWrite` or `Bash` is the application's work and
+ * is recorded like any other. Only the runner's own `bir` server stays
+ * housekeeping there. (A host with bookkeeping tools of its own does not
+ * report them at all.)
  */
-export declare function isHousekeepingCall(toolName: string, toolInput?: unknown): boolean;
+export declare function isHousekeepingCall(toolName: string, toolInput?: unknown, otherHost?: boolean): boolean;
 /**
  * {@link isBirOnlyCommand} for PowerShell, whose rules differ enough that the
  * Bash reader would get it wrong: a backslash is a path separator, not an

package/dist/record/housekeeping.js

@@ -76,12 +76,20 @@ export const RUN_SCENARIO_TOOL = `${SCENARIO_SERVER_PREFIX}run_scenario`;
  * Whether one call is host housekeeping: never recorded as a step, never a
  * divergence from a plan. `toolInput` is what the hook saw (`tool_input`); only
  * a `Bash` call's `command` is read from it.
+ *
+ * `otherHost` is a session whose host is not Claude Code. Its tool names are
+ * its own: a tool it calls `TodoWrite` or `Bash` is the application's work and
+ * is recorded like any other. Only the runner's own `bir` server stays
+ * housekeeping there. (A host with bookkeeping tools of its own does not
+ * report them at all.)
  */
-export function isHousekeepingCall(toolName, toolInput) {
-    if (HOUSEKEEPING_TOOLS.has(toolName))
-        return true;
+export function isHousekeepingCall(toolName, toolInput, otherHost = false) {
     if (toolName.startsWith(SCENARIO_SERVER_PREFIX))
         return toolName !== RUN_SCENARIO_TOOL;
+    if (otherHost)
+        return false;
+    if (HOUSEKEEPING_TOOLS.has(toolName))
+        return true;
     if (toolName === "Bash" || toolName === "PowerShell") {
         const command = toolInput?.command;
         if (typeof command !== "string")

package/dist/record/recorder.d.ts

@@ -11,10 +11,31 @@ export interface StartRunOptions {
         scenarioId: string;
         stepIndex: number;
     };
+    /**
+     * The run's `framework`, when the session named a host that is not Claude
+     * Code: its `app`, or `app:scope` (`langchain`, `langchain:billing`). The
+     * service keeps a plan inside the host that recorded it by this text.
+     * Omitted, the recorder's own framework is sent, as before.
+     */
+    framework?: string;
 }
 export interface RunMetrics {
     costUsd?: number;
     durationMs?: number;
+    /**
+     * Why the run ended before its turn did, when it did. Sent as the run's
+     * `error`, cleaned and cut like any text; such a run has no final answer.
+     */
+    error?: string;
+    /**
+     * The caller's word on whether steps of this run were lost. Present only
+     * for a run whose finish may carry the service's `incomplete` mark: the
+     * recorder adds the step sends it lost itself, and sends the mark when
+     * either says so. A run that carries it is never calculated.
+     */
+    incomplete?: {
+        lossy: boolean;
+    };
 }
 /** How long a caller is prepared to wait for {@link Recorder.flush}. */
 export interface FlushOptions {
@@ -148,6 +169,13 @@ export interface RunMatch {
     verified?: MatchVerdict;
     /** The frozen name, beside the runtime `intent` the plan runs on (R-INTENT-12). */
     intentName?: string;
+    /**
+     * Why there is a match and no scenario to run, when the service says:
+     * `switched_off`, `repairing`, or `runner_update_required` — this runner is
+     * older than the plan needs (util/service-headers.ts). Absent or null on an
+     * ordinary hand-out, and from an older service.
+     */
+    withheld?: string | null;
 }
 /** Optional capability: `null` means "fresh run, keep recording". */
 export interface MatchAware {
@@ -206,6 +234,12 @@ export interface IntentMatchRequest {
     acceptSegments?: boolean;
     /** Always true from this runner (R-CALL-28). */
     supportsCalls?: boolean;
+    /**
+     * The host the turn runs in, as its runs' `framework` says it (see
+     * {@link StartRunOptions.framework}). Left out for Claude Code, which is
+     * what a missing value means to the service.
+     */
+    framework?: string;
 }
 /** Which text a step's intent came from. */
 export type IntentSourceName = "text" | "thinking" | "tool";

package/dist/record/remote-recorder.d.ts

@@ -69,6 +69,14 @@ export declare const TEXT_CAPS: {
     /** An execution report's error lines, rendered in a web page. */
     readonly reportError: number;
 };
+/**
+ * The most an execution report's request may weigh. The service reads this
+ * route with its 100 kB JSON parser — only `/recordings` has the larger one —
+ * and a report it refuses for its size loses the turn's cost with it. So the
+ * steps' tool payloads get what is left of this after everything else in the
+ * report: the costs, the prompt, the verdicts.
+ */
+export declare const REPORT_MAX_BYTES: number;
 /** Queued sends past which the oldest unsent step is dropped (`BIR_RECORDER_MAX_PENDING`). */
 export declare const DEFAULT_MAX_PENDING_SENDS = 500;
 /** Queued bytes past which the same happens (`BIR_RECORDER_MAX_PENDING_BYTES`). */
@@ -207,6 +215,12 @@ export declare class RemoteRecorder implements Recorder, RecorderHealthReporter
     /** Backfill a step's `context` (the model's reasoning) after the fact. */
     backfillContext(runId: string, stepId: string, context: string): void;
     finishRun(runId: string, finalOutput?: string, metrics?: RunMetrics): void;
+    /**
+     * The service's mark for a run that is not whole, or undefined for one that
+     * is. Read when the finish is sent, not when it was queued: a step dropped
+     * or refused in between is as lost as one before.
+     */
+    private incompleteOf;
     /**
      * Report what a matched turn cost (docs/calculatedReplay.md §11.2).
      *

package/dist/record/remote-recorder.js

@@ -50,9 +50,10 @@ import { randomUUID } from "node:crypto";
 import { statSync } from "node:fs";
 import { credentialsPath, describeBody, isAuthResponse, issuedFor, loadCredentials, saveCredentials, } from "../auth/client.js";
 import { errText, logDetail, logEvery, logLine } from "../util/log.js";
+import { serviceHeaders } from "../util/service-headers.js";
 import { isUnhealthyStatus, serviceHealth, serviceTimeoutMs, timeoutSignal, } from "../util/service-health.js";
 import { redactJsonText, redactText } from "./redact.js";
-import { capJsonText, capText, DEFAULT_MAX_PAYLOAD_BYTES, preCut } from "./truncate.js";
+import { capJsonText, capText, DEFAULT_MAX_PAYLOAD_BYTES, preCut, REPORT_PAYLOAD_MAX_BYTES, } from "./truncate.js";
 /**
  * Caps for the free text this recorder sends, in UTF-8 bytes. Tool payloads
  * arrive capped at 64 KiB by their producers; text never passed through one,
@@ -73,6 +74,14 @@ export const TEXT_CAPS = {
     /** An execution report's error lines, rendered in a web page. */
     reportError: 2 * 1024,
 };
+/**
+ * The most an execution report's request may weigh. The service reads this
+ * route with its 100 kB JSON parser — only `/recordings` has the larger one —
+ * and a report it refuses for its size loses the turn's cost with it. So the
+ * steps' tool payloads get what is left of this after everything else in the
+ * report: the costs, the prompt, the verdicts.
+ */
+export const REPORT_MAX_BYTES = 96 * 1024;
 /** Queued sends past which the oldest unsent step is dropped (`BIR_RECORDER_MAX_PENDING`). */
 export const DEFAULT_MAX_PENDING_SENDS = 500;
 /** Queued bytes past which the same happens (`BIR_RECORDER_MAX_PENDING_BYTES`). */
@@ -177,6 +186,61 @@ function sizeOf(...parts) {
         n += p?.text.length ?? 0;
     return n;
 }
+function pendStep(step) {
+    return {
+        step,
+        toolInput: pend(step.toolInput, REPORT_PAYLOAD_MAX_BYTES, true),
+        toolOutput: pend(step.toolOutput, REPORT_PAYLOAD_MAX_BYTES, true),
+    };
+}
+/**
+ * An execution report's request body: `fields`, and its steps as sent — each
+ * error and each tool payload capped and redacted, like every other field here.
+ *
+ * The payloads are what makes a report heavy, so they are added last and only
+ * while the whole body stays within {@link REPORT_MAX_BYTES}: the failed
+ * steps' first — theirs are the ones somebody will read — then every step's
+ * input, then the outputs, each in the order the steps ran. A payload that
+ * does not fit is left out; its step keeps its verdict, and the costs the
+ * report exists for are never what gives way.
+ */
+function reportBody(fields, steps) {
+    if (!steps)
+        return JSON.stringify(fields);
+    const sent = steps.map(({ step }) => ({
+        ...step,
+        error: typeof step.error === "string"
+            ? capText(step.error, TEXT_CAPS.reportError, redactText)
+            : step.error,
+        toolInput: undefined,
+        toolOutput: undefined,
+    }));
+    const bare = Buffer.byteLength(JSON.stringify({ ...fields, steps: sent }), "utf8");
+    let left = REPORT_MAX_BYTES - bare;
+    const add = (i, key) => {
+        if (sent[i][key] !== undefined)
+            return;
+        const text = out(steps[i][key]);
+        if (text === undefined)
+            return;
+        // The value as a JSON string, and `,"<key>":` in front of it.
+        const size = Buffer.byteLength(JSON.stringify(text), "utf8") + key.length + 4;
+        if (size > left)
+            return;
+        sent[i][key] = text;
+        left -= size;
+    };
+    const all = sent.map((_, i) => i);
+    for (const i of all.filter((n) => sent[n].status === "failed")) {
+        add(i, "toolInput");
+        add(i, "toolOutput");
+    }
+    for (const i of all)
+        add(i, "toolInput");
+    for (const i of all)
+        add(i, "toolOutput");
+    return JSON.stringify({ ...fields, steps: sent });
+}
 /** A tool error is JSON when a producer serialized it, and prose when it did not. */
 function pendError(text) {
     if (typeof text !== "string")
@@ -402,7 +466,8 @@ export class RemoteRecorder {
                 try {
                     const body = await this.request("POST", "/recordings/runs", JSON.stringify({
                         id,
-                        framework: this.framework,
+                        // The session's own host, when it named one that is not Claude Code.
+                        framework: options?.framework ?? this.framework,
                         input: out(prompt),
                         metadata,
                         // A fragment (fallbk.md D7). Omitted, not null, so an older service
@@ -586,12 +651,30 @@ export class RemoteRecorder {
     }
     finishRun(runId, finalOutput, metrics) {
         const output = pend(finalOutput, TEXT_CAPS.answer);
-        this.enqueueRun(runId, "finish", sizeOf(output), () => this.post(`/recordings/runs/${runId}/finish`, {
+        // An exception's text, more often than not: it can hold a password or a
+        // user's data, so it is cleaned and cut like every other text sent.
+        const error = pend(metrics?.error, TEXT_CAPS.reportError);
+        const asked = metrics?.incomplete;
+        this.enqueueRun(runId, "finish", sizeOf(output, error), () => 
+        // `error` and `incomplete` are omitted, not nulled, when absent, so the
+        // finish of an ordinary run is the body it has always been.
+        this.post(`/recordings/runs/${runId}/finish`, {
             finalOutput: out(output),
+            error: out(error),
             originalCostUsd: metrics?.costUsd,
             originalMs: metrics?.durationMs,
+            incomplete: asked ? this.incompleteOf(runId, asked.lossy) : undefined,
         }));
     }
+    /**
+     * The service's mark for a run that is not whole, or undefined for one that
+     * is. Read when the finish is sent, not when it was queued: a step dropped
+     * or refused in between is as lost as one before.
+     */
+    incompleteOf(runId, lossy) {
+        const lostSteps = this.runs.get(runId)?.lostSteps ?? 0;
+        return lossy || lostSteps > 0 ? { lostSteps, lossy } : undefined;
+    }
     /**
      * Report what a matched turn cost (docs/calculatedReplay.md §11.2).
      *
@@ -609,12 +692,21 @@ export class RemoteRecorder {
         const costUsd = report.deriveCostUsd + report.sessionCostUsd + report.fallbackCostUsd;
         const prompt = pend(report.prompt, TEXT_CAPS.prompt);
         const error = pend(report.error, TEXT_CAPS.reportError);
+        const steps = report.steps?.map(pendStep);
         this.enqueue({
             lane: EXECUTIONS,
             kind: "report",
-            bytes: sizeOf(prompt, error) + 1024,
+            bytes: sizeOf(prompt, error, ...(steps ?? []).flatMap((s) => [s.toolInput, s.toolOutput])) + 1024,
             send: async () => {
-                const body = await this.request("POST", `/scenarios/${report.scenarioId}/executions`, JSON.stringify({
+                const body = await this.request("POST", `/scenarios/${report.scenarioId}/executions`, 
+                // Per-step verdicts and the headline failure (errorshandling.md) ride
+                // beside the costs. All optional on the service side, so an older
+                // service ignores them rather than rejecting the report — and the
+                // costs still book. Errors are shown on a web page, so they are
+                // capped and redacted like any text; so is what each step sent and
+                // received, which the page shows under the verdict in place of the
+                // recording's sample (`reportBody`).
+                reportBody({
                     ticket: report.ticket,
                     outcome: report.outcome,
                     costUsd,
@@ -627,11 +719,6 @@ export class RemoteRecorder {
                     measured: report.measured,
                     pricingVersion: report.pricingVersion,
                     prompt: out(prompt),
-                    // Per-step verdicts and the headline failure (errorshandling.md). All
-                    // optional on the service side, so an older service ignores them rather
-                    // than rejecting the report — and the costs still book. Errors are
-                    // shown on a web page, so they are capped and redacted like any text.
-                    steps: report.steps?.map((s) => typeof s.error === "string" ? { ...s, error: capText(s.error, TEXT_CAPS.reportError, redactText) } : s),
                     error: out(error),
                     errorStage: report.errorStage,
                     errorStepIndex: report.errorStepIndex,
@@ -643,7 +730,7 @@ export class RemoteRecorder {
                     // Why nothing ran, when nothing ran. Additive: an older service drops
                     // the field and books the cost exactly as it always did.
                     declined: report.declined,
-                }), { retryTransient: Boolean(report.ticket) });
+                }, steps), { retryTransient: Boolean(report.ticket) });
                 const r = (body ?? {});
                 const failed = report.steps?.filter((s) => s.status === "failed").length ?? 0;
                 logLine("execution.reported", {
@@ -738,6 +825,7 @@ export class RemoteRecorder {
             lastUsed: Date.now(),
             failed: 0,
             dropped: 0,
+            lostSteps: 0,
         };
         return entry;
     }
@@ -971,8 +1059,11 @@ export class RemoteRecorder {
         // A matched turn records nothing by design: nothing was lost.
         if (why !== "not_created") {
             this.droppedSends += 1;
-            if (run)
+            if (run) {
                 run.dropped += 1;
+                if (job.kind === "step")
+                    run.lostSteps += 1;
+            }
         }
         if (job.kind === "finish" && run && job.runId)
             this.summarize(job.runId, run);
@@ -1004,6 +1095,8 @@ export class RemoteRecorder {
         const status = err instanceof ServiceError ? err.status : undefined;
         if (run && job.runId) {
             run.failed += 1;
+            if (job.kind === "step")
+                run.lostSteps += 1;
             if (job.kind === "create") {
                 // A definite refusal means there is no run; an ambiguous failure (a
                 // timeout, a 5xx) may have created it, and the first step will say.
@@ -1302,6 +1395,7 @@ export class RemoteRecorder {
                     headers: {
                         ...(body !== undefined ? { "content-type": "application/json" } : {}),
                         ...(opts.anonymous ? {} : { authorization: `Bearer ${token}` }),
+                        ...serviceHeaders(),
                     },
                     body,
                     signal,
@@ -1529,7 +1623,7 @@ export class RemoteRecorder {
         try {
             res = await fetch(`${this.baseUrl}/auth/refresh`, {
                 method: "POST",
-                headers: { "content-type": "application/json" },
+                headers: { "content-type": "application/json", ...serviceHeaders() },
                 body: JSON.stringify({ refreshToken: this.session.refreshToken }),
                 signal,
             });

package/dist/record/switchable-recorder.js

@@ -70,6 +70,7 @@ const INTERNAL = new Set([
     "entryFor",
     "execute",
     "healthyNow",
+    "incompleteOf",
     "laneIsIdle",
     "markDead",
     "mayHotWait",

package/dist/record/truncate.d.ts

@@ -20,6 +20,17 @@
 export declare const DEFAULT_MAX_PAYLOAD_BYTES: number;
 /** 8 KiB per individual string leaf. */
 export declare const DEFAULT_MAX_STRING_BYTES: number;
+/**
+ * What one tool payload may take inside an execution report. A report carries
+ * every step of a replay in one small request, so a step's input or output
+ * gets far less there than the 64 KiB a recorded step has to itself.
+ *
+ * 3,800 bytes, not a round 4 KiB: the service keeps 4,000 characters of each,
+ * and a payload cut here still fits that with its marker. So the scenario's
+ * page shows this cut, which says how large the payload was, and never a
+ * second one made on top of it.
+ */
+export declare const REPORT_PAYLOAD_MAX_BYTES = 3800;
 export interface TruncateOptions {
     maxPayloadBytes?: number;
     maxStringBytes?: number;

package/dist/record/truncate.js

@@ -20,6 +20,17 @@
 export const DEFAULT_MAX_PAYLOAD_BYTES = 64 * 1024;
 /** 8 KiB per individual string leaf. */
 export const DEFAULT_MAX_STRING_BYTES = 8 * 1024;
+/**
+ * What one tool payload may take inside an execution report. A report carries
+ * every step of a replay in one small request, so a step's input or output
+ * gets far less there than the 64 KiB a recorded step has to itself.
+ *
+ * 3,800 bytes, not a round 4 KiB: the service keeps 4,000 characters of each,
+ * and a payload cut here still fits that with its marker. So the scenario's
+ * page shows this cut, which says how large the payload was, and never a
+ * second one made on top of it.
+ */
+export const REPORT_PAYLOAD_MAX_BYTES = 3_800;
 const utf8 = (s) => Buffer.byteLength(s, "utf8");
 /** The marker {@link truncateString} appends, so a second cut can report the first size. */
 const MARKER = /… \[truncated \d+ of (\d+) bytes\]$/;

package/dist/replay/controller.d.ts

@@ -16,6 +16,7 @@ import { type ReplayMode, type StepReach } from "./coverage.js";
 import { deriveParameters, type DeriveContext } from "./derive.js";
 import { ProxyWorkQueue } from "./executor.js";
 import { ScenarioReplayPlan } from "./plan.js";
+import { type HostSinks } from "./safety.js";
 import { SourceRunOutputs } from "./source-run.js";
 import { type FlatStop } from "./flatten.js";
 import { type ExecutionOutcome, type ExecutionStepResult, type FallbackKind, type SerializedScenario, type SerializedScenarioStep } from "./types.js";
@@ -99,6 +100,57 @@ export interface PostToolOptions {
     uncertain?: boolean;
     /** The call was never sent: its upstream was already gone. Nothing of it happened. */
     notSent?: boolean;
+    /**
+     * A host that is not Claude Code stopped the step itself, and says so: the
+     * tool never ran and the host wrote its result (`rejected` — a person said
+     * no or answered in its place, or a call limit blocked it), or it ran with
+     * arguments a person chose (`edited`). Neither is a fault of the plan: the
+     * step is recorded `skipped`, never `failed`, and the plan hands over.
+     */
+    hostStop?: HostStop;
+}
+/** How a host that is not Claude Code stopped a planned step (see {@link PostToolOptions.hostStop}). */
+export type HostStop = "rejected" | "edited";
+/**
+ * What the control server knows of a session whose host is not Claude Code —
+ * a LangChain application, say — handed to {@link ReplayController.arm} and
+ * kept on the plan's state.
+ *
+ * In such a host the tools are the application's own and only it can run
+ * them: it steps through the plan by asking for each step's arguments, and
+ * its tool names carry none of Claude Code's meanings (`Bash`, `Read`,
+ * `TodoWrite`, an `mcp__` prefix). Most of what replay decides by a tool's
+ * name is decided where there is no session to ask, so the fact travels with
+ * the plan.
+ */
+export interface HostContext {
+    /** The host's `app`, for the audit lines (`langchain`). */
+    app: string;
+    /**
+     * The sinks the host declared for its own tools. Always present, empty or
+     * not: being there is what tells the safety rules whose names these are
+     * (safety.ts, `HostSinks`).
+     */
+    sinks: HostSinks;
+    /**
+     * The run's adapter did not ask for a plan with its prompt: it only
+     * records. A match is then declined at gate 2, under its own code.
+     */
+    recordsOnly?: boolean;
+}
+/**
+ * An armed plan as data, for a host that steps through it itself. The same
+ * steps the directive lists — those the plan will run — by their position.
+ */
+export interface PlanData {
+    scenarioId: string | null;
+    mode: ReplayMode;
+    steps: Array<{
+        stepIndex: number;
+        toolName: string;
+    }>;
+    /** Only when the plan stops before its end: the first step that will not run. */
+    stopAt?: number;
 }
 /**
  * The longest a direct run may take by its budgets, end to end.
@@ -273,6 +325,12 @@ interface PinnedCall {
     toolName: string;
     /** When it was pinned — a steered step's duration is measured across hooks. */
     pinnedAt: number;
+    /**
+     * The arguments the pin gave the call, for the step's verdict: the plan
+     * never sees a steered call, so this is the only place they are known when
+     * its result lands.
+     */
+    input?: Record<string, unknown>;
     /**
      * When the host said the call finished (`PostToolUse`), if the control
      * server told us ({@link ReplayController.hostCompleted}). A wrapped step
@@ -425,12 +483,31 @@ export interface ReplayState {
      * is waiting on the service, and obeys its breaker (util/service-health.ts).
      */
     deriveOnService?: boolean;
+    /**
+     * Set when the session's host is not Claude Code (see {@link HostContext}).
+     * Such a plan is always `steer` with every step `live`, and nothing here
+     * runs a step of it or reads a Claude Code meaning into a tool's name.
+     */
+    host?: HostContext;
+    /**
+     * The host stopped a planned step itself ({@link PostToolOptions.hostStop}).
+     * It decides what the report may claim: after `rejected` the task ended
+     * early, so the turn is no measure of it; after either, its cost is no
+     * sample of what the task costs unaided.
+     */
+    hostStop?: HostStop;
 }
 /**
  * Why a match did not arm. One code per gate of the ladder, so the caller can
  * act on a decline without parsing the sentence that explains it.
  */
-export type DeclineCode = "replay_disabled" | "not_ready" | "flatten_failed" | "known_bad_first_step" | "nondeterministic_first_step" | "unusable_first_step" | "coverage" | "missing_target" | "no_derive_key";
+export type DeclineCode = "replay_disabled" | "not_ready" | "flatten_failed" | "known_bad_first_step" | "nondeterministic_first_step" | "unusable_first_step" | "coverage" | "missing_target" | "no_derive_key"
+/** The service handed over no plan: this runner is too old for it. */
+ | "runner_update_required"
+/** The session's host only records: its adapter asked for no plan with the prompt. */
+ | "host_records_only"
+/** The plan names a tool the host's agent does not hold. */
+ | "host_tool_missing";
 /** What `PreToolUse` should do about this call. */
 export type PreToolAction = 
 /** Pin the arguments and let the real tool run. */
@@ -509,8 +586,46 @@ export declare class ReplayController {
      * Always returns a state — a declined match still has a ticket to redeem and a
      * baseline sample to contribute, and losing that is how a savings ledger ends
      * up with a denominator nobody measured.
+     *
+     * `host` is given for a session whose host is not Claude Code, and is kept
+     * on the state (see {@link HostContext}).
+     */
+    arm(match: RunMatchLike, prompt: string, wrapped: ReadonlySet<string>, armedBy?: "prompt" | "intent", ctx?: DeriveContext, host?: HostContext): Promise<ReplayState>;
+    /**
+     * The armed plan as data: the steps it will run, in order, and where it
+     * stops when that is before its end. For a host that steps through the plan
+     * itself and must not have to pick the tool names out of a directive
+     * written for a model — a reworded sentence would break every adapter in
+     * the field. Built from the same entries the directive lists.
+     */
+    planData(state: ReplayState): PlanData | undefined;
+    /**
+     * Take back a plan that armed and has run nothing, as a decline.
+     *
+     * For what `arm` could not know: which tools the agent of another host
+     * holds. Such a host shows its tools only when its model is about to be
+     * called, with the first request for a step, and a plan that names a tool
+     * the agent lacks cannot be finished there. It ends before any step runs,
+     * booked like any gate's decline: `not_steered` under `code`, no step
+     * marked failed or missing — either would count against a plan that is
+     * not at fault. Returns false, changing nothing, once a step has run.
      */
-    arm(match: RunMatchLike, prompt: string, wrapped: ReadonlySet<string>, armedBy?: "prompt" | "intent", ctx?: DeriveContext): Promise<ReplayState>;
+    declineArmed(state: ReplayState, code: DeclineCode, why: string): boolean;
+    /**
+     * Hand a live plan over for something its host did, not the plan: the
+     * model made a call of its own while the plan was live (`own_call`), the
+     * run was closed with the plan still live (`closed`), or the host was
+     * answered without a step's arguments because they were not ready in time
+     * (`late`).
+     *
+     * Only for a host that is not Claude Code, where a call the plan did not
+     * hand out is by definition the model's own — it is never pinned and never
+     * answered with a bundle. No step is marked failed, so nothing is counted
+     * against the plan; the outcome is `fell_back` when a step ran and `failed`
+     * when none did, as for every hand-over. The note is the caller's to
+     * deliver ({@link takeNote}). Returns false when there was no live plan.
+     */
+    hostHandOver(state: ReplayState, why: "own_call" | "closed" | "late"): boolean;
     /**
      * The directive to inject via `additionalContext`, or undefined when declined.
      *
@@ -553,8 +668,12 @@ export declare class ReplayController {
      * Deliver text to the model in place of the tool call it was about to make:
      * as genuine command output for `Bash`, as the denial reason otherwise — the
      * two channels a divergence bundle already uses.
+     *
+     * `otherHost` is a session whose host is not Claude Code: a tool it calls
+     * `Bash` is its own, and its command is never rewritten. The text is always
+     * the refusal reason there.
      */
-    deliverInstead(text: string, toolName: string): PreToolAction;
+    deliverInstead(text: string, toolName: string, otherHost?: boolean): PreToolAction;
     /**
      * `PreToolUse`, while a plan is active.
      *
@@ -633,6 +752,13 @@ export declare class ReplayController {
      * moves from `failed` to `fell_back` when it is the first that did.
      */
     private lateThread;
+    /**
+     * Record a step its host stopped ({@link PostToolOptions.hostStop}) as
+     * `skipped`, in plain words, and remember the stop for the report. Never
+     * `failed`: the service counts failures against the plan. And not counted
+     * in `stepsPinned`: the plan's own call did not run.
+     */
+    private hostStopped;
     /** Whether a pinned call's output is threaded from the proxy's report (§7.2). */
     threadsFromProxy(state: ReplayState, toolUseId: string): boolean;
     /**
@@ -679,6 +805,13 @@ export declare class ReplayController {
         siblings?: readonly ReplayState[];
         /** The control server's own run id for this turn — journal-only, never sent. */
         runId?: string;
+        /**
+         * The run was closed before its task ended for the caller — it failed,
+         * went quiet, or stopped with the plan still live. Its cost is no
+         * measure of the task: reported unmeasured, and never a sample of the
+         * usual cost.
+         */
+        cutShort?: boolean;
     }): ExecutionReport | undefined;
     /**
      * The step a failed replay is fairly blamed on: the first whose own logic
@@ -854,7 +987,14 @@ export declare class ReplayController {
      * never be told something the log does not also say.
      */
     private observeStep;
-    /** Upsert one step's verdict. Later news about a step replaces earlier news. */
+    /**
+     * Upsert one step's verdict. Later news about a step replaces earlier news.
+     *
+     * The verdict keeps what the step sent and what came back, when the caller
+     * has them. They are this run's, which the service can learn nowhere else:
+     * a matched turn is not recorded, so without them the scenario's page shows
+     * the recording's input and output beside this run's verdict.
+     */
     private recordStep;
     /** The step verdicts, in chain order, for the execution report. */
     private stepResultsOf;
@@ -880,6 +1020,8 @@ export interface RunMatchLike {
     verified?: MatchVerdict;
     /** The frozen name, beside the runtime intent the plan runs on (R-INTENT-12). */
     intentName?: string;
+    /** Why the service handed over no plan, when it says. Read for `runner_update_required`. */
+    withheld?: string | null;
 }
 /**
  * The old rule, for a service that sends no `stop`: the position of the first