@basein/runner 0.2.12 → 0.3.0

package/dist/replay/derive.d.ts

@@ -65,6 +65,7 @@ export interface DeriveOptions extends DeriveContext {
     /** Used when there is no `apiKey`. Absent too → recorded samples. */
     service?: DeriveService;
     model?: string;
+    /** Ends the request. Absent → the service timeout (`BIR_SERVICE_TIMEOUT_MS`). */
     signal?: AbortSignal;
     /** Injected by tests. Defaults to global `fetch`. */
     fetchImpl?: typeof fetch;

package/dist/replay/derive.js

@@ -30,10 +30,50 @@
  * parameters from the same prompt — otherwise a scenario would behave one way
  * under RRepeat and another under BaseInstRunner.
  */
+import { redactText } from "../record/redact.js";
+import { isUnhealthyStatus, serviceHealth, timeoutSignal } from "../util/service-health.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";
 const ANTHROPIC_VERSION = "2023-06-01";
+/**
+ * The turn's context as it may leave this machine.
+ *
+ * Tool results are whatever the agent read — a config file, an `.env`, a page
+ * of logs — and they travel to the service (or to the model API) inside the
+ * extraction prompt. The transcript reader redacts them already; this is the
+ * same pass again at the point they leave, so no future caller of `derive` can
+ * forget it. `redactText` is idempotent.
+ */
+function outgoingContext(ctx) {
+    return {
+        liveCall: ctx.liveCall
+            ? { toolName: ctx.liveCall.toolName, toolInput: redactText(ctx.liveCall.toolInput) }
+            : undefined,
+        recentResults: ctx.recentResults?.map((r) => redactText(r)),
+    };
+}
+/**
+ * The prompt as it may leave this machine — the user's words, or on an intent
+ * arm the model's own reasoning, which often quotes a file it just read. The
+ * recorder redacts the same text before it sends it anywhere; derivation used
+ * to be the one copy that went out whole, to the service or to the model API.
+ * A redacted secret is never a parameter value a scenario could use, and
+ * `redactText` leaves ordinary prose (`region=EMEA`) as it is.
+ */
+function outgoingPrompt(prompt) {
+    return redactText(prompt);
+}
+/**
+ * Report a service answer to the breaker with the time its request started,
+ * so an answer to a request sent *before* a hot path gave up on the service
+ * does not end the cool-down that give-up began (util/service-health.ts).
+ * A breaker that takes no start time reads the call as a plain `ok()`.
+ */
+function serviceOk(startedAt) {
+    const ok = serviceHealth.ok.bind(serviceHealth);
+    ok(startedAt);
+}
 /** Every parameter at its recorded sample value. The zero-cost fallback. */
 function sampleValues(schema) {
     const out = {};
@@ -102,19 +142,19 @@ export function buildExtractionPrompt(prompt, intent, schema, ctx = {}) {
             .map((r) => `\`\`\`\n${r}\n\`\`\``)
             .join("\n")}\n`
         : "";
-    return `You are extracting parameter values from a user prompt to execute a pre-defined scenario.
-
-Scenario intent: ${intent}
-${live}
-Parameters needed (with sample values from past runs):
-${descriptions}
-
-User prompt:
-${prompt}
-${recent}
-Extract the parameter values. A setting you cannot find takes its sample value. A target you cannot find in the prompt, the reasoning, the call or the results is null — never invent it and never copy the sample.
-
-Respond ONLY with a valid JSON object mapping each parameter name to its value. No markdown fences, no prose.
+    return `You are extracting parameter values from a user prompt to execute a pre-defined scenario.
+
+Scenario intent: ${intent}
+${live}
+Parameters needed (with sample values from past runs):
+${descriptions}
+
+User prompt:
+${prompt}
+${recent}
+Extract the parameter values. A setting you cannot find takes its sample value. A target you cannot find in the prompt, the reasoning, the call or the results is null — never invent it and never copy the sample.
+
+Respond ONLY with a valid JSON object mapping each parameter name to its value. No markdown fences, no prose.
 Example: { "directory": "src/utils", "pattern": "*.ts" }`;
 }
 /**
@@ -161,14 +201,11 @@ export async function deriveParameters(opts) {
             messages: [
                 {
                     role: "user",
-                    content: buildExtractionPrompt(opts.prompt, opts.intent, schema, {
-                        liveCall: opts.liveCall,
-                        recentResults: opts.recentResults,
-                    }),
+                    content: buildExtractionPrompt(outgoingPrompt(opts.prompt), opts.intent, schema, outgoingContext({ liveCall: opts.liveCall, recentResults: opts.recentResults })),
                 },
             ],
         }),
-        signal: opts.signal,
+        signal: opts.signal ?? timeoutSignal(),
     });
     if (!res.ok) {
         const detail = await res.text().catch(() => "");
@@ -262,6 +299,12 @@ async function deriveViaService(opts, service, schema, keys) {
     const doFetch = opts.fetchImpl ?? fetch;
     const url = `${service.baseUrl.replace(/\/+$/, "")}/scenarios/${service.scenarioId}/derive`;
     let body;
+    // Every answer and every failure is reported to the process-wide breaker
+    // (util/service-health.ts): a derivation that timed out is the same news
+    // about the service as a step upload that did, and the next hook that would
+    // wait on it should know.
+    const context = outgoingContext({ liveCall: opts.liveCall, recentResults: opts.recentResults });
+    const startedAt = Date.now();
     try {
         const res = await doFetch(url, {
             method: "POST",
@@ -270,17 +313,31 @@ async function deriveViaService(opts, service, schema, keys) {
                 authorization: `Bearer ${service.token}`,
             },
             body: JSON.stringify({
-                prompt: opts.prompt,
-                liveCall: opts.liveCall,
-                recentResults: opts.recentResults,
+                prompt: outgoingPrompt(opts.prompt),
+                liveCall: context.liveCall,
+                recentResults: context.recentResults,
             }),
-            signal: opts.signal,
+            signal: opts.signal ?? timeoutSignal(),
         });
-        if (!res.ok)
+        if (!res.ok) {
+            if (isUnhealthyStatus(res.status))
+                serviceHealth.fail(`derive: HTTP ${res.status}`);
+            else
+                serviceOk(startedAt);
             return samples(`service HTTP ${res.status}`);
-        body = (await res.json());
+        }
+        try {
+            body = (await res.json());
+        }
+        catch (err) {
+            // A 200 that is not the API's JSON — a captive portal, a proxy's page.
+            serviceHealth.fail("derive: the answer was not JSON");
+            return samples(err instanceof Error ? err.message : String(err));
+        }
+        serviceOk(startedAt);
     }
     catch (err) {
+        serviceHealth.fail(`derive: ${err instanceof Error ? err.message : String(err)}`);
         return samples(err instanceof Error ? err.message : String(err));
     }
     if (!body || typeof body !== "object")

package/dist/replay/executor.d.ts

@@ -16,8 +16,8 @@
  * already dominated by the upstream's own round trip.
  *
  * A proxy that never polls (an old build, or one started without `BIR_REPLAY`)
- * is not an error: `call` rejects with `no_proxy`, and the caller falls back to
- * the step's recorded output.
+ * is not an error: `call` rejects with `no_proxy`, and the plan stops at that
+ * step and hands the rest to the model (plan.ts, `DriveOptions`).
  *
  * WHICH PROXY. Several proxies can poll for the same server at once — one per
  * Claude Code session in the project, and a session's proxy outlives a
@@ -30,14 +30,21 @@
  *
  *   1. a proxy bound to the step's session — learned from a correlated step the
  *      proxy reported, or from an earlier step of this session it ran;
- *   2. otherwise the newest unbound proxy (latest process start) — a session's
- *      proxies are spawned when it starts, so the newest is the best guess for
- *      a session that has not called the server yet;
- *   3. otherwise NOBODY. A proxy bound to another session is never used for
- *      this one: the step resolves as a tool error, so the plan stops and hands
- *      over to the agent, who calls the tool on its own upstream. It does not
- *      reject — a rejection lets a recorded output stand in, or skips the step
- *      and runs the rest of the plan past it.
+ *   2. otherwise an unbound proxy, but ONLY while no other session is live
+ *      (none bound elsewhere, and no server with two proxies polling — each
+ *      session starts its own). A lone session's unbound proxy can only be
+ *      its own. With two sessions open, the one that has not called the server
+ *      yet cannot be told apart from the other: "the newest" was a guess, and
+ *      when the older session asked it ran the step on the newer one's
+ *      upstream — another browser page, another database session — and
+ *      answered wrongly;
+ *   3. otherwise NOBODY. A proxy bound, or possibly belonging, to another
+ *      session is never used for this one: the call rejects with a
+ *      {@link NoSessionProxyError} — nothing was sent, exactly like
+ *      {@link NO_PROXY} — so the step is recorded as not run (never as a
+ *      failure of the scenario: two sessions open is the environment, not the
+ *      scenario being wrong), the plan stops, and the agent gets the hand-over
+ *      and calls the tool on its own upstream, with the reason in front of it.
  *
  * A session's bindings are released when it ends (a `/clear` starts a new
  * session on the same proxies). Legacy proxies, which send no id, share one
@@ -72,6 +79,20 @@ export interface PollerIdentity {
 }
 /** Rejection reason when no proxy is polling for a server. */
 export declare const NO_PROXY = "no_proxy";
+/**
+ * Rejection when proxies poll for the server but none can be shown to be the
+ * asking session's: every one is bound to another session, or the unbound ones
+ * may be another open session's. Like {@link NO_PROXY}, nothing was sent; the
+ * message is the explanation the model reads in the hand-over.
+ */
+export declare class NoSessionProxyError extends Error {
+    readonly code = "no_session_proxy";
+    constructor(message: string);
+}
+/** Rejection reason at shutdown for work no proxy had taken yet: never sent. */
+export declare const QUEUE_CLOSED = "control server closed";
+/** Rejection reason at shutdown for work a proxy had already taken: it may have run. */
+export declare const QUEUE_CLOSED_IN_FLIGHT = "control server closed while the call was in flight";
 export declare class ProxyWorkQueue {
     /** Work held for a proxy that was mid-round-trip when it was dispatched, per proxy id. */
     private readonly pending;
@@ -103,10 +124,13 @@ export declare class ProxyWorkQueue {
     /**
      * Dispatch one call and await its result.
      *
-     * Rejects with {@link NO_PROXY} when nothing is polling for `serverName`, and
-     * with `timeout` when the proxy takes the work but never answers. Both are
-     * "could not be run here", which is exactly the condition under which the
-     * caller may substitute a recorded output.
+     * Rejects with {@link NO_PROXY} when nothing is polling for `serverName`, with
+     * a {@link NoSessionProxyError} when proxies poll but none can be shown to be
+     * `route.sessionId`'s (nothing sent either), and with `timeout` when the
+     * proxy takes the work but never answers. The two
+     * are not the same news: `no_proxy` means nothing was sent, while a timeout
+     * means the call may well have done its work upstream — the controller tells
+     * the model which (controller.ts, `classifyWorkError`).
      */
     call(serverName: string, toolName: string, args: unknown, timeoutMs: number, route?: WorkRoute): Promise<unknown>;
     /** Remove queued work that timed out, so a later poll never gets stale work. */
@@ -121,10 +145,21 @@ export declare class ProxyWorkQueue {
     private present;
     /**
      * The proxy a step for `sessionId` should run on — see the file comment.
-     * Undefined when no proxy is live at all; `other_sessions` when every live
-     * one belongs to a different session.
+     * Undefined when no proxy is live at all; `other_sessions` when none can be
+     * shown to be this session's: every live one belongs to a different session,
+     * or the unbound ones might, because another session is live too.
      */
     private pickProxy;
+    /**
+     * Whether a session other than `sessionId` is evidently live.
+     *
+     * Two signs, both from proxies that are polling right now: one is bound to
+     * another session, or one server has two proxies polling. Claude Code starts
+     * one proxy per server per session, so a second proxy for the same server is
+     * a second session, whether or not it has called anything yet. A pool of
+     * legacy proxies shares one record and says nothing either way.
+     */
+    private otherSessionLive;
     /**
      * Free every proxy bound to `sessionId`: the session ended. After a `/clear`
      * the same proxies serve the next session, which must be able to pick them.

package/dist/replay/executor.js

@@ -16,8 +16,8 @@
  * already dominated by the upstream's own round trip.
  *
  * A proxy that never polls (an old build, or one started without `BIR_REPLAY`)
- * is not an error: `call` rejects with `no_proxy`, and the caller falls back to
- * the step's recorded output.
+ * is not an error: `call` rejects with `no_proxy`, and the plan stops at that
+ * step and hands the rest to the model (plan.ts, `DriveOptions`).
  *
  * WHICH PROXY. Several proxies can poll for the same server at once — one per
  * Claude Code session in the project, and a session's proxy outlives a
@@ -30,14 +30,21 @@
  *
  *   1. a proxy bound to the step's session — learned from a correlated step the
  *      proxy reported, or from an earlier step of this session it ran;
- *   2. otherwise the newest unbound proxy (latest process start) — a session's
- *      proxies are spawned when it starts, so the newest is the best guess for
- *      a session that has not called the server yet;
- *   3. otherwise NOBODY. A proxy bound to another session is never used for
- *      this one: the step resolves as a tool error, so the plan stops and hands
- *      over to the agent, who calls the tool on its own upstream. It does not
- *      reject — a rejection lets a recorded output stand in, or skips the step
- *      and runs the rest of the plan past it.
+ *   2. otherwise an unbound proxy, but ONLY while no other session is live
+ *      (none bound elsewhere, and no server with two proxies polling — each
+ *      session starts its own). A lone session's unbound proxy can only be
+ *      its own. With two sessions open, the one that has not called the server
+ *      yet cannot be told apart from the other: "the newest" was a guess, and
+ *      when the older session asked it ran the step on the newer one's
+ *      upstream — another browser page, another database session — and
+ *      answered wrongly;
+ *   3. otherwise NOBODY. A proxy bound, or possibly belonging, to another
+ *      session is never used for this one: the call rejects with a
+ *      {@link NoSessionProxyError} — nothing was sent, exactly like
+ *      {@link NO_PROXY} — so the step is recorded as not run (never as a
+ *      failure of the scenario: two sessions open is the environment, not the
+ *      scenario being wrong), the plan stops, and the agent gets the hand-over
+ *      and calls the tool on its own upstream, with the reason in front of it.
  *
  * A session's bindings are released when it ends (a `/clear` starts a new
  * session on the same proxies). Legacy proxies, which send no id, share one
@@ -53,6 +60,23 @@ import { randomUUID } from "node:crypto";
 import { logDetail } from "../util/log.js";
 /** Rejection reason when no proxy is polling for a server. */
 export const NO_PROXY = "no_proxy";
+/**
+ * Rejection when proxies poll for the server but none can be shown to be the
+ * asking session's: every one is bound to another session, or the unbound ones
+ * may be another open session's. Like {@link NO_PROXY}, nothing was sent; the
+ * message is the explanation the model reads in the hand-over.
+ */
+export class NoSessionProxyError extends Error {
+    code = "no_session_proxy";
+    constructor(message) {
+        super(message);
+        this.name = "NoSessionProxyError";
+    }
+}
+/** Rejection reason at shutdown for work no proxy had taken yet: never sent. */
+export const QUEUE_CLOSED = "control server closed";
+/** Rejection reason at shutdown for work a proxy had already taken: it may have run. */
+export const QUEUE_CLOSED_IN_FLIGHT = "control server closed while the call was in flight";
 /**
  * How long after its last poll a proxy is still considered present.
  *
@@ -173,10 +197,13 @@ export class ProxyWorkQueue {
     /**
      * Dispatch one call and await its result.
      *
-     * Rejects with {@link NO_PROXY} when nothing is polling for `serverName`, and
-     * with `timeout` when the proxy takes the work but never answers. Both are
-     * "could not be run here", which is exactly the condition under which the
-     * caller may substitute a recorded output.
+     * Rejects with {@link NO_PROXY} when nothing is polling for `serverName`, with
+     * a {@link NoSessionProxyError} when proxies poll but none can be shown to be
+     * `route.sessionId`'s (nothing sent either), and with `timeout` when the
+     * proxy takes the work but never answers. The two
+     * are not the same news: `no_proxy` means nothing was sent, while a timeout
+     * means the call may well have done its work upstream — the controller tells
+     * the model which (controller.ts, `classifyWorkError`).
      */
     call(serverName, toolName, args, timeoutMs, route = {}) {
         if (this.closed)
@@ -186,19 +213,22 @@ export class ProxyWorkQueue {
             // No proxy has ever polled for this server, or one has been gone for a
             // minute. Do NOT queue: the caller is inside a turn the user is waiting on,
             // and work that sits until some proxy happens to appear would stall it past
-            // every budget. Fail fast, and let the recorded-output fallback decide.
+            // every budget. Fail fast: the plan stops here and says so.
             return Promise.reject(new Error(NO_PROXY));
         }
         if (picked === "other_sessions") {
-            const others = this.present(serverName).length;
+            const live = this.present(serverName);
+            const unbound = live.some((p) => !p.sessionId);
             logDetail("replay.no_session_proxy", {
                 server: serverName,
                 tool: toolName,
                 sess: route.sessionId,
-                others,
-                why: "only other sessions' proxies are here — the step is not run on their upstream",
+                others: live.length,
+                why: unbound
+                    ? "this session has no proxy of its own for the server yet, and another session is live — an unbound proxy may be theirs, so none is guessed"
+                    : "only other sessions' proxies are here — the step is not run on their upstream",
             });
-            return Promise.resolve(noSessionProxy(serverName, others));
+            return Promise.reject(noSessionProxy(serverName, live.length, unbound));
         }
         const { info, why } = picked;
         if (route.sessionId && !info.sessionId && !isLegacy(info.proxyId)) {
@@ -262,12 +292,22 @@ export class ProxyWorkQueue {
             }
         }
         this.waiters.clear();
+        // Work still held for a proxy that never came back for it was never sent:
+        // that, and only that, may be said to have not run. Work already handed to
+        // a proxy may be running on its upstream right now, and is said to be
+        // exactly that (controller.ts, `classifyWorkError`) — "nothing happened, do
+        // it yourself" about a write in flight is how it gets done twice.
+        const unsent = new Set();
+        for (const list of this.pending.values()) {
+            for (const work of list)
+                unsent.add(work.workId);
+        }
         this.pending.clear();
         // A closed queue has no proxies, whatever they were doing a moment ago.
         this.proxies.clear();
-        for (const [, entry] of this.inFlight) {
+        for (const [workId, entry] of this.inFlight) {
             clearTimeout(entry.timer);
-            entry.reject(new Error("control server closed"));
+            entry.reject(new Error(unsent.has(workId) ? QUEUE_CLOSED : QUEUE_CLOSED_IN_FLIGHT));
         }
         this.inFlight.clear();
     }
@@ -300,8 +340,9 @@ export class ProxyWorkQueue {
     }
     /**
      * The proxy a step for `sessionId` should run on — see the file comment.
-     * Undefined when no proxy is live at all; `other_sessions` when every live
-     * one belongs to a different session.
+     * Undefined when no proxy is live at all; `other_sessions` when none can be
+     * shown to be this session's: every live one belongs to a different session,
+     * or the unbound ones might, because another session is live too.
      */
     pickProxy(serverName, sessionId) {
         const live = this.present(serverName);
@@ -316,9 +357,40 @@ export class ProxyWorkQueue {
         if (mine[0])
             return { info: mine[0], why: "session" };
         const unbound = live.find((p) => !p.sessionId);
-        if (unbound)
-            return { info: unbound, why: "newest" };
-        return "other_sessions";
+        if (!unbound)
+            return "other_sessions";
+        // Nothing ties an unbound proxy to this session. With another session
+        // live, it may well be that session's — a browser on its page, a database
+        // session in its state — and a wrong guess returns a wrong answer here,
+        // where not running the step only costs the saving.
+        if (this.otherSessionLive(sessionId))
+            return "other_sessions";
+        return { info: unbound, why: "only" };
+    }
+    /**
+     * Whether a session other than `sessionId` is evidently live.
+     *
+     * Two signs, both from proxies that are polling right now: one is bound to
+     * another session, or one server has two proxies polling. Claude Code starts
+     * one proxy per server per session, so a second proxy for the same server is
+     * a second session, whether or not it has called anything yet. A pool of
+     * legacy proxies shares one record and says nothing either way.
+     */
+    otherSessionLive(sessionId) {
+        const perServer = new Map();
+        for (const info of this.proxies.values()) {
+            if (!this.isLive(info))
+                continue;
+            if (info.sessionId && info.sessionId !== sessionId)
+                return true;
+            if (isLegacy(info.proxyId))
+                continue;
+            const n = (perServer.get(info.serverName) ?? 0) + 1;
+            if (n > 1)
+                return true;
+            perServer.set(info.serverName, n);
+        }
+        return false;
     }
     /**
      * Free every proxy bound to `sessionId`: the session ended. After a `/clear`
@@ -406,21 +478,22 @@ function shortId(proxyId) {
     return isLegacy(proxyId) ? proxyId : proxyId.slice(-8);
 }
 /**
- * The step's result when only other sessions' proxies are here: an MCP tool
- * error, so the plan stops on it and hands over (tool-error.ts), and the agent
- * reads why.
+ * The rejection when no proxy can be shown to be this session's. A rejection,
+ * not a tool-error result: a result is a call that ran, and the plan would
+ * count it as an executed step that failed — blaming the scenario for two
+ * sessions being open, and telling the model both that the step ran and that
+ * nothing did. As a rejection the controller records it as not run
+ * (controller.ts, `classifyWorkError`) and the plan hands the task over.
+ * `unsure` — some of them are unbound, and other sessions are live — words it
+ * as the doubt it is.
  */
-function noSessionProxy(serverName, others) {
-    return {
-        isError: true,
-        content: [
-            {
-                type: "text",
-                text: `Error: bir did not run this step. No ${serverName} proxy of this session is ` +
-                    `connected; the ${others} that are belong to other sessions, and a step never ` +
-                    `runs on another session's upstream. Call the tool yourself.`,
-            },
-        ],
-    };
+function noSessionProxy(serverName, others, unsure = false) {
+    const why = unsure
+        ? `no ${serverName} connection is known to be this session's yet, and other sessions ` +
+            `are open, so the ${others} connected may belong to them; a step never runs on ` +
+            `another session's upstream`
+        : `no ${serverName} proxy of this session is connected; the ${others} that are belong ` +
+            `to other sessions, and a step never runs on another session's upstream`;
+    return new NoSessionProxyError(why);
 }
 //# sourceMappingURL=executor.js.map

package/dist/replay/handover.d.ts

@@ -18,7 +18,34 @@ export type HandoverDelivery =
 /** Steer mode: the steps that ran are the model's own tool calls, just above. */
 "above"
 /** Direct mode: the steps that ran are in the bundle that follows the note. */
- | "below";
+ | "below"
+/**
+ * Neither: the note travels alone — a run whose caller went away, or one
+ * whose tool answer is an error. The steps that ran are real, and the model
+ * is told so, but it has no results to read.
+ */
+ | "none";
+/**
+ * Why the stopped step did not do its work, when it is not simply "it failed".
+ *
+ * The wording matters more than it looks. A step that timed out may well have
+ * finished on the upstream — the proxy stops waiting, the database does not —
+ * and a model told only "failed" reasonably runs it again: a second INSERT, a
+ * second deploy. So each reason says what the model may and may not assume.
+ */
+export type HandoverStopReason = 
+/** Nothing was sent: no proxy for its server, a built-in, the allowlist. */
+"not_run"
+/** Sent and never answered (a timeout, a dropped connection). */
+ | "uncertain"
+/** Sent, and the upstream answered with an error. */
+ | "failed"
+/** The plan's time budget ran out before it. */
+ | "budget"
+/** 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";
 export interface HandoverNoteInput {
     intent: string;
     kind: FallbackKind;
@@ -29,8 +56,34 @@ export interface HandoverNoteInput {
     failureCount?: number;
     /** Why it stopped (step_failed). */
     error?: string;
+    /** For `step_failed`: what kind of stop it was. Absent reads as a failure. */
+    stopReason?: HandoverStopReason;
     /** Steps that ran under the scenario before the stop. */
     executed: number;
+    /**
+     * Of {@link executed}, how many are the model's own tool calls above — the
+     * steps a steered session ran before a divergence took over. Only read when
+     * `delivery` is not `above` (where every step is), and only when it is
+     * fewer than `executed`; otherwise the delivery's own wording is right.
+     */
+    executedAbove?: number;
+    /**
+     * A pinned step the host was asked to run and has not reported back on —
+     * neither counted in {@link executed} nor said to be undone. It may be
+     * running still, or it may never run at all: the user's own deny rule or
+     * PreToolUse hook can block a call the plan approved, and then no report
+     * ever comes. `stepIndex` is its position in the chain.
+     */
+    inFlight?: {
+        stepIndex: number;
+        toolName?: string;
+    };
+    /**
+     * The stopped step's own tool ran and its result is real; what failed is the
+     * scenario reading that result (its output logic). It is counted in
+     * `executed` and absent from `remainingTools`, and must not be run again.
+     */
+    ranThisStep?: boolean;
     totalSteps: number;
     /** Tool names of the planned steps from the stopped one to the end. */
     remainingTools: string[];

package/dist/replay/handover.js

@@ -36,13 +36,35 @@ export function buildHandoverNote(n) {
     if (intent)
         lines.push(`Intent: ${intent}`);
     if (n.executed > 0) {
-        lines.push(n.delivery === "above"
-            ? `Steps 1–${n.executed} of ${n.totalSteps} ran under the scenario; their calls and results are the tool calls above. Do not repeat them.`
-            : `Steps 1–${n.executed} of ${n.totalSteps} ran under the scenario; their calls and results are below. Do not repeat them.`);
+        // Part of the work may be the model's own calls above (a steered session
+        // that diverged), and the rest the bundle below or side effects only.
+        const above = Math.max(0, Math.min(n.executedAbove ?? 0, n.executed));
+        const delivery = above >= n.executed ? "above" : n.delivery;
+        const ran = `Steps 1–${n.executed} of ${n.totalSteps} ran under the scenario`;
+        lines.push(delivery === "above"
+            ? `${ran}; their calls and results are the tool calls above. Do not repeat them.`
+            : above > 0
+                ? delivery === "none"
+                    ? `${ran}: steps 1–${above} are the tool calls above, and the side effects of the rest are in place. Do not repeat them.`
+                    : `${ran}: steps 1–${above} are the tool calls above, and the rest are below. Do not repeat them.`
+                : delivery === "none"
+                    ? `${ran}, and their side effects are in place. Do not repeat them.`
+                    : `${ran}; their calls and results are below. Do not repeat them.`);
+    }
+    else if (n.stopReason === "uncertain" || n.inFlight) {
+        // The stopped step was sent: "no step ran" would contradict the line that
+        // says it may have completed.
+        lines.push("No step of the scenario is known to have finished; the task is yours.");
     }
     else {
         lines.push("No step of the scenario ran; the whole task is yours.");
     }
+    if (n.inFlight) {
+        // Never "ran", never "did not run": the host has not said which.
+        const inTool = n.inFlight.toolName ? ` (${n.inFlight.toolName})` : "";
+        lines.push(`Step ${n.inFlight.stepIndex + 1} of ${n.totalSteps}${inTool} was started and has not reported back: ` +
+            "it may not have run, or may still complete. Check whether its work happened before you repeat it.");
+    }
     if (n.kind === "unusable_call") {
         // A call is a stretch of work, not a tool: the agent is told what the
         // sub-task was, not which tool did not run.
@@ -66,8 +88,7 @@ export function buildHandoverNote(n) {
         lines.push(`Step ${human} of ${n.totalSteps}${tool} did not run: its input needs a judgement the scenario cannot compute. Make that choice yourself and carry on.`);
     }
     else {
-        const error = n.error ? `: ${truncate(n.error, MAX_ERROR_CHARS)}` : "";
-        lines.push(`Step ${human} of ${n.totalSteps}${tool} failed${error}`);
+        lines.push(stepFailedLine(n, human, tool));
     }
     if (n.remainingTools.length > 0) {
         lines.push(`The remaining planned steps were: ${n.remainingTools.join(", ")}.`);
@@ -84,4 +105,33 @@ export function buildHandoverNote(n) {
     }
     return truncate(lines.join("\n"), MAX_HANDOVER_NOTE);
 }
+/** The line that names a stopped step and says what may be assumed about it. */
+function stepFailedLine(n, human, tool) {
+    const at = `Step ${human} of ${n.totalSteps}${tool}`;
+    const detail = n.error ? truncate(n.error, MAX_ERROR_CHARS) : "";
+    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.
+        return (`${at} ran — its result is real and its side effects are in place — but the scenario ` +
+            `could not read its output${detail ? ` (${detail})` : ""}, so it stops there. Do not run it again.`);
+    }
+    switch (n.stopReason) {
+        case "not_run":
+            return `${at} did not run${detail ? `: ${detail}` : ""}. Nothing of it happened; do it yourself.`;
+        case "uncertain":
+            // Never "failed": the upstream may have finished what the proxy stopped
+            // waiting for, and a model told "failed" runs a write a second time.
+            return (`${at} was sent but did not answer${detail ? ` (${detail})` : ""}. It may or may not ` +
+                "have completed: check whether its work happened before you run it again.");
+        case "budget":
+            return `${at} did not run: the scenario's time budget ran out before it.`;
+        case "cancelled":
+            return `${at} did not run: the scenario run was cancelled before it.`;
+        case "concurrent":
+            return (`${at} was not run by the scenario: another of its calls was still in flight, ` +
+                "and a scenario runs one call at a time.");
+        default:
+            return `${at} failed${detail ? `: ${detail}` : ""}`;
+    }
+}
 //# sourceMappingURL=handover.js.map