@basein/runner 0.3.11 → 0.3.12

package/dist/bin/bir.js

@@ -68,6 +68,7 @@ import { SCENARIO_EDIT_SUBCOMMANDS, scenarioEditCommand } from "./scenario-edit.
 import { loadCredentials } from "../auth/client.js";
 import { packageVersion } from "../util/version.js";
 import { runnerOutdated, serviceHeaders } from "../util/service-headers.js";
+import { localDay } from "../replay/derive.js";
 const VERSION = packageVersion();
 /**
  * The npx SessionStart hook's own budget, passed as `ensure --budget-ms <n>`
@@ -3630,6 +3631,9 @@ async function replayCommand(args) {
     if (args.dry) {
         const { status, body } = await service("POST", `/scenarios/${scenarioId}/replay`, {
             prompt: args.prompt,
+            // The day on this machine, as a session's reading sends it: a dry
+            // replay works a value like "tomorrow" out from the same day.
+            today: localDay(),
         });
         if (status !== 200) {
             out(`Dry replay failed (HTTP ${status}): ${JSON.stringify(body)}`);

package/dist/bin/investigate.js

@@ -217,6 +217,11 @@ export const DECLINES = {
         cause: "the plan was not ready before the hook that would have announced it had to answer: the prompt hook waits 7.5 s in all, match included, and a tool call that starts a plan mid-task waits 1.5 s. What arming waits for is the reading of the prompt's values (the derivation). A plan that was not announced is never run.",
         fix: "run the prompt again. If it keeps happening the reading is slow: the recorder's log (`bir status` names the file) shows when its `replay.derived` line landed, and a dry replay shows what the service's reading took, under `reading` (`bir scenario replay <scnId> --prompt \"…\" --dry --json`). BIR_HOOK_DERIVE_BUDGET_MS does not help here, because the hook's own limit was reached first. To read values on this machine instead of asking the service, set BIR_DERIVE_API_KEY where Claude Code starts.",
     },
+    // Nor is this one: the match itself was late, so nothing was armed at all.
+    match_late: {
+        cause: "the service's answer to the match landed too late: after the prompt hook had stopped waiting for it (3 s, BIR_MATCH_BUDGET_MS); while prompts were not waiting on the match at all — after one slow answer they stop waiting for a few minutes (`replay.match_gate state=holding`); or with the hook not waiting from the start, because a failure to reach the service was still on record (a `service.degraded` line, perhaps hours before, and no `service.recovered` until after this prompt) or the match request's first attempt failed. The agent did the task itself.",
+        fix: "nothing in the prompt has to change: run it again a few minutes later. A `service.recovered` line just after this turn's `run.start` means an old failure was still on record, and the next prompt waits again. If it keeps happening without one, the service answers matches slowly: `bir doctor` shows its state, and `/health.matchGate` when prompts wait again.",
+    },
     runner_update_required: {
         cause: "the service matched the prompt and handed over no plan: this runner is older than its plans need.",
         fix: "update the runner (`bir update`), then run `bir setup` in each project that uses it; `bir doctor` says when the service is satisfied.",

package/dist/control/server.d.ts

@@ -582,6 +582,12 @@ export declare class ControlServer {
      * plan. Memoized, because `ensureRun` is reached from five different hooks and
      * arming twice would run the scenario twice.
      *
+     * Two answers are followed. `pending` is what the prompt hook may wait for,
+     * and the recorder answers it null at once while a failure is on record or
+     * once the create's first attempt failed. `settled` is the service's own
+     * answer, whenever it lands: the hit that stops the recording, and a ticket
+     * the turn owes a report even when nobody waited for it.
+     *
      * Resolves with the steering directive to inject, or undefined.
      */
     private watchForMatch;
@@ -593,6 +599,11 @@ export declare class ControlServer {
      * match. A match that misses its budget, or a plan still deriving when the
      * budget runs out, is never delivered: the turn runs as an ordinary one, and
      * one `replay.decision` line says why (docs/calculatedReplay.md §10).
+     *
+     * `pending` is what the prompt may wait for; `settled` is the service's own
+     * answer, whenever it lands (see {@link watchForMatch}). Every way of going
+     * ahead without a match follows `settled`, so a hand-out nobody waited for
+     * still has its ticket reported ({@link followLateMatch}).
      */
     private armFromMatch;
     /**
@@ -607,6 +618,25 @@ export declare class ControlServer {
      * not several, so the hold doubles at most once per hold (on its probe).
      */
     private noteMatchLatency;
+    /**
+     * The prompt went ahead without the match: when the service's own answer
+     * lands, a hit is a hand-out nobody used. It is said once, as `match_late`
+     * with `why`, and its ticket is carried to the turn's report
+     * ({@link noteLateMatch}). A miss says nothing: the service has no ticket out.
+     */
+    private followLateMatch;
+    /**
+     * A match that landed after its prompt had been answered, or while prompts
+     * were not waiting on it. Nothing is armed for it, and nothing derived. But
+     * the service issued a ticket with that hand-out, and without a report under
+     * it the console can only say the turn never reported — for a turn the agent
+     * simply did itself. So the turn carries the ticket to its report, as a
+     * decline with its own code, like a plan that was only late ({@link shelve}).
+     *
+     * Only a hand-out with a ticket: a match the service handed nothing for has
+     * its reason on the service already. And only while the turn is open.
+     */
+    private noteLateMatch;
     /**
      * {@link armFromMatch} with replay off: nothing can be announced, and no hook
      * waits for the answer (`onPrompt` has already returned). So there is no
@@ -614,7 +644,8 @@ export declare class ControlServer {
      * had, and must not mark the service slow (that would open the process-wide
      * cool-down, and `/health` would report a degradation the user never had).
      * A hit still books its decline — the ledger's baseline sample — whenever
-     * it lands, as long as the turn is still open to carry it.
+     * it lands, as long as the turn is still open to carry it. So `settled` is
+     * the service's own answer, not the one a hook may have been given at once.
      */
     private noteDisabledMatch;
     /**

package/dist/control/server.js

@@ -36,7 +36,7 @@ import { isHousekeepingCall } from "../record/housekeeping.js";
 import { redact, redactText } from "../record/redact.js";
 import { DEFAULT_MAX_STRING_BYTES, serializeCapped, truncateString, truncateStrings, } from "../record/truncate.js";
 import { StepQueue } from "../record/queue.js";
-import { NullRecorder, isIntentMatcher, isMatchAware, isRecorderHealthReporter, isRunCreationAware, isScenarioReporter, } from "../record/recorder.js";
+import { NullRecorder, isIntentMatcher, isMatchAware, isRecorderHealthReporter, isRunCreationAware, isScenarioReporter, isServiceProber, } from "../record/recorder.js";
 import { ReplayController, POLL_HOLD_MS, } from "../replay/controller.js";
 import { calculateCostUsd, hasModelPricing } from "../replay/pricing.js";
 import { logDetail, logLine, logOnce, errText } from "../util/log.js";
@@ -1640,6 +1640,12 @@ export class ControlServer {
      * plan. Memoized, because `ensureRun` is reached from five different hooks and
      * arming twice would run the scenario twice.
      *
+     * Two answers are followed. `pending` is what the prompt hook may wait for,
+     * and the recorder answers it null at once while a failure is on record or
+     * once the create's first attempt failed. `settled` is the service's own
+     * answer, whenever it lands: the hit that stops the recording, and a ticket
+     * the turn owes a report even when nobody waited for it.
+     *
      * Resolves with the steering directive to inject, or undefined.
      */
     watchForMatch(session, run, prompt = "") {
@@ -1650,7 +1656,10 @@ export class ControlServer {
         const runId = run.runId;
         const startedAt = Date.now();
         const pending = this.recorder.getMatch(runId).catch(() => null);
-        void pending.then((match) => {
+        const settled = this.recorder.settledMatch
+            ? this.recorder.settledMatch(runId).catch(() => null)
+            : pending;
+        void settled.then((match) => {
             if (!match || run.runId !== runId)
                 return;
             run.recording = false;
@@ -1662,7 +1671,7 @@ export class ControlServer {
                 why: "similar prompt — the service kept its own run; not recording this one",
             });
         });
-        run.matchWatch = this.armFromMatch(session, run, pending, prompt, startedAt).catch((err) => {
+        run.matchWatch = this.armFromMatch(session, run, pending, settled, prompt, startedAt).catch((err) => {
             // Replay is an optimisation; a broken one must never cost a turn.
             logLine("replay.arm_failed", { run: run.runId, error: errText(err) });
             return undefined;
@@ -1677,12 +1686,17 @@ export class ControlServer {
      * match. A match that misses its budget, or a plan still deriving when the
      * budget runs out, is never delivered: the turn runs as an ordinary one, and
      * one `replay.decision` line says why (docs/calculatedReplay.md §10).
+     *
+     * `pending` is what the prompt may wait for; `settled` is the service's own
+     * answer, whenever it lands (see {@link watchForMatch}). Every way of going
+     * ahead without a match follows `settled`, so a hand-out nobody waited for
+     * still has its ticket reported ({@link followLateMatch}).
      */
-    async armFromMatch(session, run, pending, prompt, startedAt) {
+    async armFromMatch(session, run, pending, settled, prompt, startedAt) {
         // Off for the recorder, or — in a session of another host — not asked
         // for by this run's adapter: either way nothing can be announced.
         if (!this.replay.enabled || this.recordsOnly(session, run)) {
-            return this.noteDisabledMatch(session, run, pending, prompt);
+            return this.noteDisabledMatch(session, run, settled, prompt);
         }
         const promptWaitMs = this.promptWaitMs();
         const matchBudget = Math.min(this.replay.budgets.matchMs, promptWaitMs);
@@ -1699,18 +1713,7 @@ export class ControlServer {
                 run: run.runId,
                 why: "the service has been answering matches slowly — not waited on; this turn runs normally",
             });
-            void pending.then((late) => {
-                if (!late)
-                    return;
-                logLine("replay.decision", {
-                    verdict: "no-steer",
-                    code: "match_late",
-                    run: run.runId,
-                    scenario: late.scenarioId ?? undefined,
-                    ms: Date.now() - startedAt,
-                    why: "the match landed while prompts were not waiting on it — not steered, and not recorded",
-                });
-            });
+            this.followLateMatch(session, run, settled, startedAt, "the match landed while prompts were not waiting on it — not steered, and not recorded");
             return undefined;
         }
         const cooling = !this.service.canWait();
@@ -1734,23 +1737,18 @@ export class ControlServer {
                         ? "the service is failing — not waited on; this turn runs normally"
                         : "the match did not answer inside its budget; this turn runs normally",
                 });
-                void pending.then((late) => {
-                    if (!late)
-                        return;
-                    logLine("replay.decision", {
-                        verdict: "no-steer",
-                        code: "match_late",
-                        run: run.runId,
-                        scenario: late.scenarioId ?? undefined,
-                        ms: Date.now() - startedAt,
-                        why: "the match landed after the prompt was answered — not steered, and not recorded",
-                    });
-                });
+                this.followLateMatch(session, run, settled, startedAt, "the match landed after the prompt was answered — not steered, and not recorded");
             }
             return undefined;
         }
-        if (!match)
+        if (!match) {
+            // "No match" — which may have come without waiting: the recorder answers
+            // the prompt so at once while a service failure is on record, however
+            // old, and once the create's first attempt failed. The service may have
+            // matched the prompt all the same, and issued a ticket.
+            this.followLateMatch(session, run, settled, startedAt, "the match landed after the prompt had gone ahead without it (a service failure was still on record, or the create's first attempt failed) — not steered, and not recorded");
             return undefined;
+        }
         // Awaited: a scenario with a target derives before the directive goes
         // out, so a plan that cannot find its target is never delivered
         // (segmented.md R-PARAM-4). Inside the prompt's own budget.
@@ -1869,6 +1867,45 @@ export class ControlServer {
             why: "the match answered fast again — prompts wait on it as before",
         });
     }
+    /**
+     * The prompt went ahead without the match: when the service's own answer
+     * lands, a hit is a hand-out nobody used. It is said once, as `match_late`
+     * with `why`, and its ticket is carried to the turn's report
+     * ({@link noteLateMatch}). A miss says nothing: the service has no ticket out.
+     */
+    followLateMatch(session, run, settled, startedAt, why) {
+        void settled.then((late) => {
+            if (!late)
+                return;
+            logLine("replay.decision", {
+                verdict: "no-steer",
+                code: "match_late",
+                run: run.runId,
+                scenario: late.scenarioId ?? undefined,
+                ms: Date.now() - startedAt,
+                why,
+            });
+            this.noteLateMatch(session, run, late);
+        });
+    }
+    /**
+     * A match that landed after its prompt had been answered, or while prompts
+     * were not waiting on it. Nothing is armed for it, and nothing derived. But
+     * the service issued a ticket with that hand-out, and without a report under
+     * it the console can only say the turn never reported — for a turn the agent
+     * simply did itself. So the turn carries the ticket to its report, as a
+     * decline with its own code, like a plan that was only late ({@link shelve}).
+     *
+     * Only a hand-out with a ticket: a match the service handed nothing for has
+     * its reason on the service already. And only while the turn is open.
+     */
+    noteLateMatch(session, run, match) {
+        if (run.finished || run.lateMatch || !match.scenarioId || !match.executionTicket)
+            return;
+        const state = this.replay.lateMatch(match, this.hostContext(session, run));
+        state.sessionId = session.sessionId;
+        run.lateMatch = state;
+    }
     /**
      * {@link armFromMatch} with replay off: nothing can be announced, and no hook
      * waits for the answer (`onPrompt` has already returned). So there is no
@@ -1876,10 +1913,11 @@ export class ControlServer {
      * had, and must not mark the service slow (that would open the process-wide
      * cool-down, and `/health` would report a degradation the user never had).
      * A hit still books its decline — the ledger's baseline sample — whenever
-     * it lands, as long as the turn is still open to carry it.
+     * it lands, as long as the turn is still open to carry it. So `settled` is
+     * the service's own answer, not the one a hook may have been given at once.
      */
-    async noteDisabledMatch(session, run, pending, prompt) {
-        const match = await pending;
+    async noteDisabledMatch(session, run, settled, prompt) {
+        const match = await settled;
         if (!match || run.finished)
             return undefined;
         // Declined at its first gate, before derivation: no transcript is read for it.
@@ -2436,6 +2474,25 @@ export class ControlServer {
             }
             this.queue.push(() => recorder.reportExecution(report));
         });
+        // The prompt match that landed too late (see `noteLateMatch`). Not when a
+        // plan of the same scenario armed later in the turn: that one has a ticket
+        // of its own, and says what happened. The turn's cost is a sample of the
+        // task's usual cost only when no plan ran in it at all.
+        const late = run.lateMatch;
+        if (late && !states.some((s) => s.scenarioId === late.scenarioId)) {
+            const alone = states.length === 0;
+            const report = this.replay.buildReport(late, {
+                sessionCostUsd: alone ? cost.usd : 0,
+                measured: alone && cost.measured,
+                durationMs,
+                prompt: run.input || undefined,
+                siblings: [...states, late],
+                runId: run.runId,
+                cutShort: cutShort || undefined,
+            });
+            if (report)
+                this.queue.push(() => recorder.reportExecution(report));
+        }
     }
     /**
      * Seal the session's run now, and drain it to the service in the background.
@@ -2513,6 +2570,12 @@ export class ControlServer {
             cwd: session.cwd,
             why: "run deferred to prompt",
         });
+        // The first prompt is seconds away, and its match is not waited for while
+        // a service failure is on record — one from hours ago included, when the
+        // machine slept or went offline and nothing was sent since. Find out now,
+        // in the background, whether the service answers again.
+        if (isServiceProber(this.recorder))
+            this.recorder.probeIfFailing();
         return {};
     }
     async onPrompt(payload) {

package/dist/record/recorder.d.ts

@@ -180,6 +180,16 @@ export interface RunMatch {
 /** Optional capability: `null` means "fresh run, keep recording". */
 export interface MatchAware {
     getMatch(runId: string): Promise<RunMatch | null>;
+    /**
+     * The create call's own answer, whenever it lands. `getMatch` is what a hook
+     * may wait for, and a recorder may answer it null without waiting — while
+     * the service has a failure on record, or once the create's first attempt
+     * failed. The service can still match the prompt then, hand out the scenario
+     * and issue a ticket the turn owes a report; this is how the turn finds out.
+     * Never for a hook to wait on. Absent where `getMatch` always waits for the
+     * create's answer: it is the same answer then.
+     */
+    settledMatch?(runId: string): Promise<RunMatch | null>;
 }
 export declare function isMatchAware(r: Recorder): r is Recorder & MatchAware;
 /**
@@ -201,6 +211,21 @@ export interface RunCreationAware {
     runCreated(runId: string): Promise<RunCreation>;
 }
 export declare function isRunCreationAware(r: Recorder): r is Recorder & RunCreationAware;
+/**
+ * Optional capability: a prompt is on its way, so the service verdict it will
+ * be decided by should be current.
+ *
+ * A hook never waits on a service with a failure on record, and is never the
+ * request that finds out whether it answers again. After hours with nothing
+ * sent — a laptop asleep, a network that dropped — the failure is still on
+ * record at the next prompt, whose match is then not waited for however fast
+ * the service answers. Called when a session starts, before its first prompt:
+ * it checks in the background, and sends nothing while no failure is on record.
+ */
+export interface ServiceProber {
+    probeIfFailing(): void;
+}
+export declare function isServiceProber(r: Recorder): r is Recorder & ServiceProber;
 /** What a ReAct iteration sends to find a scenario by its intent (fallbk.md §Runner 4). */
 export interface IntentMatchRequest {
     /**

package/dist/record/recorder.js

@@ -14,6 +14,9 @@ export function isMatchAware(r) {
 export function isRunCreationAware(r) {
     return typeof r.runCreated === "function";
 }
+export function isServiceProber(r) {
+    return typeof r.probeIfFailing === "function";
+}
 export function isIntentMatcher(r) {
     return typeof r.matchIntent === "function";
 }

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

@@ -43,8 +43,10 @@
  * SIMILAR-PROMPT HITS. `POST /recordings/runs` may answer `{ id: null, matched }`,
  * meaning the server recognised the prompt and did **not** create a run. Every
  * later step post for that id would then 404, so callers must stop recording —
- * {@link RemoteRecorder.getMatch} is how they find out — and this recorder skips
- * them itself too, for the caller that stopped waiting before the answer came.
+ * {@link RemoteRecorder.settledMatch} is how they find out, whenever the answer
+ * lands ({@link RemoteRecorder.getMatch} is only what a hook may wait for) — and
+ * this recorder skips them itself too, for the caller that stopped waiting
+ * before the answer came.
  */
 import { type AuthSession } from "../auth/client.js";
 import { type ServiceHealth } from "../util/service-health.js";
@@ -187,11 +189,34 @@ export declare class RemoteRecorder implements Recorder, RecorderHealthReporter
     matchIntent(req: IntentMatchRequest, opts?: IntentMatchOptions): Promise<IntentMatchAnswer | null>;
     /**
      * The similar-prompt match for a run's create call (null = fresh run). Like
-     * {@link runCreated}, answers null at once while the service is cooling down,
-     * and as soon as the create's first attempt fails — the first prompt of an
-     * outage is not held for the retry's sleep (up to 2 s behind a Retry-After).
+     * {@link runCreated}, answers null at once while a failure is on record —
+     * in a cool-down, and after it until an answer clears it, however long ago
+     * it was — and as soon as the create's first attempt fails: the first prompt
+     * of an outage is not held for the retry's sleep (up to 2 s behind a
+     * Retry-After). The create goes on, and its own answer is
+     * {@link settledMatch}'s.
      */
     getMatch(runId: string): Promise<RunMatch | null>;
+    /**
+     * The create's own match (null = fresh run), whenever it lands — after the
+     * cool-down and the retry, if it took them — however {@link getMatch}
+     * answered the hook. A hook told "no match" at once, because a failure was
+     * on record or the first attempt failed, may be about a prompt the service
+     * matched all the same: it then handed out the scenario and issued a ticket,
+     * and the turn owes that ticket a report. Never for a hook to wait on. Null
+     * for an id this recorder never opened.
+     */
+    settledMatch(runId: string): Promise<RunMatch | null>;
+    /**
+     * A prompt is on its way (a session just started). While a failure is on
+     * record no hook waits on the service, and none is the request that finds
+     * out whether it answers again ({@link mayHotWait}). After hours with
+     * nothing sent, the failure is still on record at the first prompt, and its
+     * match is not waited for however fast the service answers — so find out
+     * now: one background `GET /health`, once the cool-down is over. Nothing
+     * while no failure is on record, during a cool-down, or with a probe out.
+     */
+    probeIfFailing(): void;
     recordToolSelected(runId: string, stepIndex: number, data: {
         toolName: string;
         toolInput: string;

package/dist/record/remote-recorder.js

@@ -43,8 +43,10 @@
  * SIMILAR-PROMPT HITS. `POST /recordings/runs` may answer `{ id: null, matched }`,
  * meaning the server recognised the prompt and did **not** create a run. Every
  * later step post for that id would then 404, so callers must stop recording —
- * {@link RemoteRecorder.getMatch} is how they find out — and this recorder skips
- * them itself too, for the caller that stopped waiting before the answer came.
+ * {@link RemoteRecorder.settledMatch} is how they find out, whenever the answer
+ * lands ({@link RemoteRecorder.getMatch} is only what a hook may wait for) — and
+ * this recorder skips them itself too, for the caller that stopped waiting
+ * before the answer came.
  */
 import { randomUUID } from "node:crypto";
 import { statSync } from "node:fs";
@@ -479,7 +481,8 @@ export class RemoteRecorder {
                     }), 
                     // The id is client-generated, so the service can tell a repeat. A
                     // hook waiting on this answer is let go before the retry: a match
-                    // found by the retry is not the turn's any more.
+                    // found by the retry can no longer steer the turn, and only its
+                    // ticket's report is left to it (`settledMatch`).
                     { retryTransient: true, onRetry: () => entry.release() });
                     const b = body && typeof body === "object"
                         ? body
@@ -579,9 +582,12 @@ export class RemoteRecorder {
     }
     /**
      * The similar-prompt match for a run's create call (null = fresh run). Like
-     * {@link runCreated}, answers null at once while the service is cooling down,
-     * and as soon as the create's first attempt fails — the first prompt of an
-     * outage is not held for the retry's sleep (up to 2 s behind a Retry-After).
+     * {@link runCreated}, answers null at once while a failure is on record —
+     * in a cool-down, and after it until an answer clears it, however long ago
+     * it was — and as soon as the create's first attempt fails: the first prompt
+     * of an outage is not held for the retry's sleep (up to 2 s behind a
+     * Retry-After). The create goes on, and its own answer is
+     * {@link settledMatch}'s.
      */
     async getMatch(runId) {
         const entry = this.runs.get(runId);
@@ -595,6 +601,39 @@ export class RemoteRecorder {
         await entry.hot;
         return entry.settled?.match ?? null;
     }
+    /**
+     * The create's own match (null = fresh run), whenever it lands — after the
+     * cool-down and the retry, if it took them — however {@link getMatch}
+     * answered the hook. A hook told "no match" at once, because a failure was
+     * on record or the first attempt failed, may be about a prompt the service
+     * matched all the same: it then handed out the scenario and issued a ticket,
+     * and the turn owes that ticket a report. Never for a hook to wait on. Null
+     * for an id this recorder never opened.
+     */
+    async settledMatch(runId) {
+        const entry = this.runs.get(runId);
+        if (!entry)
+            return null;
+        entry.lastUsed = Date.now();
+        if (entry.settled)
+            return entry.settled.match;
+        return (await entry.answer) ?? null;
+    }
+    /**
+     * A prompt is on its way (a session just started). While a failure is on
+     * record no hook waits on the service, and none is the request that finds
+     * out whether it answers again ({@link mayHotWait}). After hours with
+     * nothing sent, the failure is still on record at the first prompt, and its
+     * match is not waited for however fast the service answers — so find out
+     * now: one background `GET /health`, once the cool-down is over. Nothing
+     * while no failure is on record, during a cool-down, or with a probe out.
+     */
+    probeIfFailing() {
+        this.checkCredentials();
+        if (this.state !== "recording" || this.healthyNow())
+            return;
+        this.probeSoon();
+    }
     recordToolSelected(runId, stepIndex, data) {
         const id = "step_" + randomUUID();
         const toolInput = pend(data.toolInput, DEFAULT_MAX_PAYLOAD_BYTES, true);
@@ -796,6 +835,7 @@ export class RemoteRecorder {
     newEntry() {
         let resolveHot;
         let resolveCreated;
+        let resolveAnswer;
         const entry = {
             userId: this.session.user.id,
             hot: new Promise((r) => {
@@ -804,6 +844,9 @@ export class RemoteRecorder {
             created: new Promise((r) => {
                 resolveCreated = r;
             }),
+            answer: new Promise((r) => {
+                resolveAnswer = r;
+            }),
             settle: (match, created) => {
                 if (entry.settled)
                     return;
@@ -811,9 +854,11 @@ export class RemoteRecorder {
                 entry.settledAt = Date.now();
                 resolveHot();
                 resolveCreated(created);
+                resolveAnswer(match);
                 // Callers that are waiting hold the promises themselves.
                 entry.hot = undefined;
                 entry.created = undefined;
+                entry.answer = undefined;
             },
             release: () => {
                 if (entry.settled || entry.released)

package/dist/record/switchable-recorder.js

@@ -46,10 +46,12 @@ import { NullRecorder, } from "./recorder.js";
  */
 const NEUTRAL = {
     getMatch: () => Promise.resolve(null),
+    settledMatch: () => Promise.resolve(null),
     runCreated: () => Promise.resolve({ created: true }),
     matchIntent: () => Promise.resolve(null),
     reportExecution: () => undefined,
     backfillContext: () => undefined,
+    probeIfFailing: () => undefined,
 };
 /**
  * `RemoteRecorder`'s private helpers. They are methods at runtime (TypeScript's

package/dist/replay/controller.d.ts

@@ -514,7 +514,13 @@ export type DeclineCode = "replay_disabled" | "not_ready" | "flatten_failed" | "
  * (`arm_unannounced`). Set by the control server, where a prompt's wait
  * ends, so the report can say why a matched turn was not steered.
  */
- | "arm_timeout" | "arm_unannounced";
+ | "arm_timeout" | "arm_unannounced"
+/**
+ * Nothing was armed at all: the service's answer to the match landed after
+ * the prompt had been answered, or while prompts were not waiting on it
+ * (the match gate). Set by the control server, like the two above.
+ */
+ | "match_late";
 /** What `PreToolUse` should do about this call. */
 export type PreToolAction = 
 /** Pin the arguments and let the real tool run. */
@@ -587,6 +593,17 @@ export declare class ReplayController {
      * covers both "no match" and "too slow", which are the same thing from here.
      */
     awaitMatch(pending: Promise<unknown>): Promise<RunMatchLike | null>;
+    /** A matched state before any gate has judged it: nothing planned, nothing run. */
+    private blankState;
+    /**
+     * The state of a prompt match that landed too late to be used
+     * (`match_late`). No gate is run and nothing is derived — a plan could no
+     * longer be announced, and a reading nobody waits for is money spent on
+     * nothing. It exists for the one thing the hand-out still owes: its ticket's
+     * report, with the reason, so the service does not show a turn the agent did
+     * itself as one that never reported.
+     */
+    lateMatch(match: RunMatchLike, host?: HostContext): ReplayState;
     /**
      * Run the gate ladder and, if every gate passes, arm a plan.
      *

package/dist/replay/controller.js

@@ -305,18 +305,9 @@ export class ReplayController {
                 clearTimeout(timer);
         }
     }
-    /**
-     * Run the gate ladder and, if every gate passes, arm a plan.
-     *
-     * 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}).
-     */
-    async arm(match, prompt, wrapped, armedBy = "prompt", ctx = {}, host) {
-        const state = {
+    /** A matched state before any gate has judged it: nothing planned, nothing run. */
+    blankState(match, wrapped, armedBy, host) {
+        return {
             scenarioId: match.scenarioId,
             ticket: match.executionTicket,
             similarity: match.similarity,
@@ -345,6 +336,33 @@ export class ReplayController {
             verified: match.verified,
             sharedWith: [],
         };
+    }
+    /**
+     * The state of a prompt match that landed too late to be used
+     * (`match_late`). No gate is run and nothing is derived — a plan could no
+     * longer be announced, and a reading nobody waits for is money spent on
+     * nothing. It exists for the one thing the hand-out still owes: its ticket's
+     * report, with the reason, so the service does not show a turn the agent did
+     * itself as one that never reported.
+     */
+    lateMatch(match, host) {
+        const state = this.blankState(match, new Set(), "prompt", host);
+        state.declined = "match_late";
+        state.retired = true;
+        return state;
+    }
+    /**
+     * Run the gate ladder and, if every gate passes, arm a plan.
+     *
+     * 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}).
+     */
+    async arm(match, prompt, wrapped, armedBy = "prompt", ctx = {}, host) {
+        const state = this.blankState(match, wrapped, armedBy, host);
         const isSegment = state.kind === "segment";
         const decline = (why, code) => {
             state.declined = code;

package/dist/replay/derive.d.ts

@@ -60,6 +60,8 @@ export interface DeriveOptions extends DeriveContext {
     prompt: string;
     intent: string;
     paramsObject: ParamsSchema | null;
+    /** The day on this machine. Injected by tests; defaults to {@link localDay}. */
+    today?: string;
     /** An override that keeps the reading on this machine. Absent → the service. */
     apiKey?: string;
     /** Used when there is no `apiKey`. Absent too → recorded samples. */
@@ -90,6 +92,16 @@ export interface DeriveResult {
     /** Settings filled from their recorded sample (R-PARAM-2). */
     sampled: string[];
 }
+/**
+ * The day on this machine, `YYYY-MM-DD`, in its own time zone.
+ *
+ * Sent to the service with every reading, because a prompt says "tomorrow" and
+ * the date is in no prompt: the service works such a value out, and it must
+ * count from the user's day. Its own day is the wrong one — a server on UTC is
+ * a day ahead of a user in Seattle for a third of the working day. Local on
+ * purpose, then, and never `toISOString`, which is UTC.
+ */
+export declare function localDay(now?: Date): string;
 /**
  * First balanced `{…}` in a text blob. Models wrap JSON in prose and fences more
  * often than they emit it bare, and a failed parse here costs a whole replay.

package/dist/replay/derive.js

@@ -75,6 +75,19 @@ function serviceOk(startedAt) {
     const ok = serviceHealth.ok.bind(serviceHealth);
     ok(startedAt);
 }
+/**
+ * The day on this machine, `YYYY-MM-DD`, in its own time zone.
+ *
+ * Sent to the service with every reading, because a prompt says "tomorrow" and
+ * the date is in no prompt: the service works such a value out, and it must
+ * count from the user's day. Its own day is the wrong one — a server on UTC is
+ * a day ahead of a user in Seattle for a third of the working day. Local on
+ * purpose, then, and never `toISOString`, which is UTC.
+ */
+export function localDay(now = new Date()) {
+    const two = (n) => String(n).padStart(2, "0");
+    return `${now.getFullYear()}-${two(now.getMonth() + 1)}-${two(now.getDate())}`;
+}
 /** Every parameter at its recorded sample value. The zero-cost fallback. */
 function sampleValues(schema) {
     const out = {};
@@ -251,6 +264,15 @@ export async function deriveParameters(opts) {
     const missing = [];
     const sampled = [];
     for (const key of keys) {
+        // A value worked out from the day ("tomorrow") cannot be read here: this
+        // copy of the text does not tell the model the day, and what comes back
+        // for such a value is then the recorded date or a guess. The service's
+        // reading does work it out; with a key of its own the value is missing.
+        if (isTarget(schema, key) && schema[key].from === "today") {
+            parsed[key] = null;
+            missing.push(key);
+            continue;
+        }
         if (parsed[key] !== null && parsed[key] !== undefined)
             continue;
         if (isTarget(schema, key)) {
@@ -318,6 +340,9 @@ async function deriveViaService(opts, service, schema, keys) {
                 prompt: outgoingPrompt(opts.prompt),
                 liveCall: context.liveCall,
                 recentResults: context.recentResults,
+                // What "tomorrow" is counted from. A service that does not know the
+                // field ignores it.
+                today: opts.today ?? localDay(),
             }),
             signal: opts.signal ?? timeoutSignal(),
         });

package/dist/replay/types.d.ts

@@ -138,6 +138,13 @@ export type ParamsSchema = Record<string, {
     sampleValue: unknown;
     description: string;
     kind?: ParameterKind;
+    /**
+     * Where the recorded value came from, when the service calculated the plan
+     * beside its request. Only `today` is read here: a value worked out from
+     * the day the request is made on ("tomorrow"), which the service works out
+     * again from the day this runner sends (replay/derive.ts, `localDay`).
+     */
+    from?: string;
 }>;
 /** Whether this schema has anything the runner may not guess (R-PARAM-4). */
 export declare function hasTargets(schema: ParamsSchema | null | undefined): boolean;

package/docs/calculatedReplay.md

@@ -194,7 +194,7 @@ Every gate that declines logs **one** `replay.decision` line carrying the reason
 
 | # | Gate | Declines when | Outcome floor |
 |---|---|---|---|
-| 1 | **A match arrived** | `getMatch()` resolved `null`, or the budget expired (§10) | (no report — nothing matched) |
+| 1 | **A match arrived** | `getMatch()` resolved `null`, or the budget expired (§10) | (no report — nothing matched; unless the create's own answer is a hit after all: `match_late`, below) |
 | 2 | **Replay enabled** | `BIR_REPLAY === "0"`, or, with it unset, the project's stored switch is off (`bir replay off`, or a `bir install` without `--replay`). In a session of another host, also when the run's adapter asked for no plan with its prompt (`host_records_only`, §7.4) | `not_steered` |
 | 3 | **Scenario ready** | `scenario == null`, `state !== "ready"`, or `steps.length === 0` | `not_steered` |
 | 4 | ~~**Similarity**~~ | Retired: a match is the decision to use the scenario (below) | — |
@@ -203,9 +203,15 @@ Every gate that declines logs **one** `replay.decision` line carrying the reason
 Past the table, a plan can still be refused before the model hears of it, each refusal with its own
 `replay.decision` code. The match is not waited on at all while the service is cooling down after a
 failure (`service_unhealthy`), or while prompts are holding off a service that answered matches
-slowly (`match_slow`, the match gate, §10). A match or a plan that is not ready
+slowly (`match_slow`, the match gate, §10). Nor after the cool-down, while the failure is still on
+record and no answer has cleared it: the recorder answers the prompt "no match" at once, and the
+create goes on without it. A match or a plan that is not ready
 inside the prompt's budget (§10) is dropped (`match_timeout`, `arm_timeout`), and one that lands
-after the prompt was answered is retired unannounced (`match_late`, `arm_unannounced`). A `direct`
+after the prompt was answered is retired unannounced (`match_late`, `arm_unannounced`). The turn's
+report carries that code as its decline, `match_late` included: nothing is armed or derived for a
+late match, but the ticket of its hand-out is still reported, so the service knows why the turn was
+not steered. That holds for a match the prompt never waited for, too: the turn follows the create's
+own answer (`settledMatch`), not the "no match" the prompt was given. A `direct`
 plan is declined when no running `bir-scenario` has said it serves `run_scenario`
 (`no_delivery_tool`, §6.3). In plan mode (`permission_mode: "plan"`) nothing is announced at all.
 In a session of another host (§7.4) a plan that armed is taken back, before any step of it runs,
@@ -915,7 +921,13 @@ minutes, while its steps keep starting. `bir replay` is not held to the ceiling.
 `BIR_MATCH_SLOW_MS` (**2000**), or not at all, also makes prompts stop waiting on the match for 5
 minutes, doubling up to 30 while the service stays slow; a fast match ends the hold
 (`replay.match_gate`). A healthy service answers in 300–450 ms, so past 2 s waiting would add
-that much to every prompt. The match is still asked meanwhile, so a hit still stops the recording. Derivation budget expired →
+that much to every prompt. The match is still asked meanwhile, so a hit still stops the recording.
+**A failure on record:** a prompt never waits on a service whose last request failed, until an
+answer clears that failure, and a prompt is never the request that finds out. After hours with
+nothing sent (a machine asleep, a network that dropped) the failure is still on record, so a
+session's start checks it in the background (`GET /health`) before the first prompt arrives. A match
+that lands after a prompt went ahead without it is `match_late`, and its ticket is reported as the
+turn's decline. Derivation budget expired →
 settings take their recorded `sampleValue`s and targets stay `null`, never `{}`; a plan that needs a
 missing target, or whose `paramsLogic` throws, hands over instead of running (in steer mode the
 note replaces the call, in direct mode `run_scenario` answers with it). The derivation request
@@ -1356,8 +1368,9 @@ fail because of BaseInstRunner.**
 
 | Failure | Behaviour |
 |---|---|
-| `getMatch()` slower than the match budget | No plan. Ordinary turn. One `replay.decision` line (`match_timeout`); a match that lands later is `match_late` and never steers. A slow match also makes prompts stop waiting on it for a while (`replay.match_gate`, §10) |
+| `getMatch()` slower than the match budget | No plan. Ordinary turn. One `replay.decision` line (`match_timeout`); a match that lands later is `match_late` and never steers; while the turn is open it is reported to the service as that turn's decline. A slow match also makes prompts stop waiting on it for a while (`replay.match_gate`, §10) |
 | The service is cooling down after a failure | Nothing waits on it: no match wait (`service_unhealthy`), no derivation wait, no intent probe. Ordinary turn |
+| A failure is still on record after the cool-down, with nothing sent since | No match wait and no intent probe: the prompt is answered "no match" at once and the create goes on. A hit that lands is `match_late`, and is reported as the turn's decline while the turn is open. A session's start checks the service in the background (`GET /health`), so an old failure does not decide its first prompt |
 | No derivation key here (`BIR_DERIVE_API_KEY`; the background recorder ignores `ANTHROPIC_API_KEY` unless `BIR_USE_ANTHROPIC_API_KEY=1`) | The service derives instead (segmented.md R-PARAM-5). Signed out as well: settings take their recorded `sampleValue`s, a scenario with a target declines `no_derive_key`, `deriveCostUsd: 0` |
 | The service declines, is slow, or cannot be reached | The same, with its reason carried into the `replay.derived` and `replay.decision` lines. Never a throw |
 | Derivation call fails or times out | Settings take their samples and targets stay `null`, never `{}`; a plan that needs a missing target hands over instead of running. Plus a `replay.derive_failed` or `replay.derive_timeout` line |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basein/runner",
-  "version": "0.3.11",
+  "version": "0.3.12",
   "description": "A recording MCP proxy: sits between any MCP client and its MCP servers, executes each call on the client's behalf, and records the run as a reusable BaseIn scenario.",
   "type": "module",
   "license": "MIT",

package/production.md

@@ -909,7 +909,7 @@ Lines read `[bir] <ISO time> <event> key=value …`, with each field clipped at
 
 | Topic | Lines and what they mean |
 |---|---|
-| Service health | `service.degraded` (first failure: reason, cool-down), `service.recovered`. `replay.decision code=service_unhealthy` (prompt did not wait: breaker open), `code=match_timeout` (prompt waited its budget), `code=match_late` (the answer landed after the prompt), `code=match_slow` (verbose: gate holding). `replay.match_gate state=holding\|open`. |
+| Service health | `service.degraded` (first failure: reason, cool-down), `service.recovered`. `replay.decision code=service_unhealthy` (prompt did not wait: breaker open), `code=match_timeout` (prompt waited its budget), `code=match_late` (the answer landed after the prompt, including one the prompt never waited for because a failure was still on record), `code=match_slow` (verbose: gate holding). `replay.match_gate state=holding\|open`. |
 | Recording backlog | `recorder.backlog_full` / `recorder.backlog_recovered` (oldest steps dropped). `recorder.run_incomplete` (a run lost steps). `recorder.run_abandoned` (`reason=service_down`: a create given up after a minute of cool-down). `recorder.flush_deferred`, `recorder.flush_incomplete`, `recorder.send_failed` (once per run), `recorder.matched_after_retry`, `run.lossy`. |
 | Sign-in | `auth.ok`, `auth.settling` (plain-http address being checked for https), `auth.refresh_deferred`, `auth.refresh_refused`, `auth.recovered`. `recorder.enabled`, `recorder.signed_out`, `recorder.disabled`, `recorder.paused` / `recorder.resumed`, `recorder.account_changed`, `recorder.report_dropped`, `derive.api_key_ignored`. |
 | Hooks | `control.listening` (port, `recorder=<state>`, `correlation=`). `control.correlation_allow` (auto-approval opted in). `control.hook_deadline`, `control.hook_unauthorized` (a token from another install), `control.hook_unknown`, `control.hook_oversize`, `control.hook_event_mismatch`, `control.route_failed`, `control.drain_abandoned`. |