@basein/runner 0.3.10 → 0.3.12

package/README.md

@@ -488,7 +488,7 @@ what to do when they register, so there is one switch and no second copy of it:
 | `ANTHROPIC_API_KEY` | Not used by the background recorder, which has Claude Code's environment and would bill your own key — unless `BIR_USE_ANTHROPIC_API_KEY=1`. A `bir-hooks` run by hand in a terminal uses that terminal's key. |
 | `BIR_DERIVE_MODEL` | Derivation model, when you set a key of your own (default `claude-haiku-4-5-20251001`). |
 | `BIR_MATCH_BUDGET_MS` | How long the prompt hook waits for a match (default `3000`). After a match slower than `BIR_MATCH_SLOW_MS` (default `2000`), or one that timed out, prompts stop waiting for 5 min, doubling up to 30 min; a fast match ends that. |
-| `BIR_DERIVE_BUDGET_MS` / `BIR_HOOK_DERIVE_BUDGET_MS` | How long a direct run, and a hook, waits for parameters (default `8000` / `8000`; a hook waits the smaller, and the prompt hook never past its own 6 s). |
+| `BIR_DERIVE_BUDGET_MS` / `BIR_HOOK_DERIVE_BUDGET_MS` | How long a direct run, and a hook, waits for parameters (default `8000` / `8000`; a hook waits the smaller, and the prompt hook never past its own 7.5 s). |
 | `BIR_PRETOOL_REPLAY_BUDGET_MS` | Everything replay does inside one `PreToolUse` (default `9000`, at most `10000`). |
 | `BIR_REPLAY_BUDGET_MS` / `BIR_STEP_TIMEOUT_MS` | Whole-plan and per-step ceilings for direct execution (default `100000` / `60000`; `BIR_REPLAY_PLAN_BUDGET_MS` also sets the first). A direct run's parameter wait plus its plan are held under 270 s. |
 | `BIR_LOGIC_TIMEOUT_MS` | How long one scenario logic body may run before it is stopped and the plan hands over (default `1000`, at most `10000`). |
@@ -525,7 +525,7 @@ The governing rule: **a host session never fails because of BaseInstRunner.**
 | No recorder running at session start | the SessionStart hook starts one in the background; it always exits 0 and never holds the start longer than about 11.5 s |
 | Control server unreachable at startup | steps buffered ≤ 10 s, then Tier 2 (passthrough: nothing); the proxy keeps looking every 15 s and binds when one answers |
 | Control server dies mid-session | the proxy records to a Tier 2 run of its own (flagged lossy), starts the recorder again in the background (not after `bir down`), and binds to it once it answers |
-| A hook the recorder cannot answer in time | every route has a hard deadline (prompt 7 s, `PreToolUse` 12 s, the others 1–2 s) and answers `{}`; so does a hook with a stale token or a malformed body |
+| A hook the recorder cannot answer in time | every route has a hard deadline (prompt 8.5 s, `PreToolUse` 12 s, the others 1–2 s) and answers `{}`; so does a hook with a stale token or a malformed body |
 | BaseIn service slow or down | hooks stop waiting on it after one failure (a cool-down of 5 s, doubling to 60 s); sends go on in the background, retried once only when they cannot have arrived (429, 503, a refused connection); past 500 queued sends or 32 MiB the oldest steps are dropped |
 | BaseIn service answers `429`: the account is over one of its limits | the send — a run's create, a step, a report — goes once more, at most 2 s later, and is then dropped, with `recorder.send_failed … HTTP 429` on the log (one line per run). A dropped step is a hole in its recording; a run whose create was refused runs without its plan; a `429` the second try did not cure starts the cool-down above. The limits are settings of the service, per account — by default 120 runs and 3,000 steps a minute (a tool call is two steps), 10 title requests a minute, and 20 Calculate, Prefer and Recalculate requests in any one hour — and are built there, not deployed yet |
 | Upstream fails to start, or exits | calls in flight are answered (`MCP server "<name>" is not available`, `isError: true` for a `tools/call`), then `bir-proxy` exits with the server's own status, so Claude Code shows the server as failed, as it would unwrapped. `BIR_PROXY_STAY_UP=1` keeps the proxy up answering that instead |

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

@@ -214,8 +214,13 @@ export const DECLINES = {
     // Not a gate of the ladder: the control server's own verdict, when arming
     // outlived the hook that would have announced the plan.
     arm_timeout: {
-        cause: "the plan was not ready before the hook that would have announced it had to answer: the prompt hook waits 6 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. 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.",
+        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.",
@@ -287,7 +292,7 @@ function readingDecline(code, why) {
         return {
             cause: `the plan needs a target, a value read from the prompt, and that reading (the derivation) had not answered when the runner stopped waiting for it: its wait is ${waitedMs} ms, and none while the service is cooling down after a slow or failed call. ` +
                 "Whether the prompt names the target was never learned. A replay never takes a target from the recording.",
-            fix: "nothing in the prompt needs to change: run it again. If it keeps happening the reading is slower than the wait, and the recorder's log (`bir status` names the file) has its `replay.derived` line after this decline. Give it longer: set BIR_HOOK_DERIVE_BUDGET_MS where the recorder starts, then `bir up --restart`. The prompt hook stops 6 s after the prompt arrived, whatever is set.",
+            fix: "nothing in the prompt needs to change: run it again. If it keeps happening the reading is slower than the wait, and the recorder's log (`bir status` names the file) has its `replay.derived` line after this decline. Give it longer: set BIR_HOOK_DERIVE_BUDGET_MS where the recorder starts, then `bir up --restart`. The prompt hook stops 7.5 s after the prompt arrived, whatever is set.",
         };
     }
     // Gate 7 writes `<reason>: target <name>`, and `no_derive_key` itself as the

package/dist/config/adapters/claude-code.d.ts

@@ -182,7 +182,7 @@ export declare function setLocalEntries(claudeJson: string, keys: string[], name
  * to its `timeout`, so each number here is how long a slow or blackholed
  * service could make a person wait — at every prompt, every tool call, every
  * `/exit`. The control server keeps its own per-route deadlines well inside
- * them (prompt ≤ 7 s, tool/pre ≤ 12 s, tool/post and stop ≤ 2 s, end ≤ 1 s,
+ * them (prompt ≤ 8.5 s, tool/pre ≤ 12 s, tool/post and stop ≤ 2 s, end ≤ 1 s,
  * start ≤ 2 s) and answers `{}` on overrun, so these are the second line of
  * defence, not a budget to spend. SessionEnd matters twice: Claude Code's own
  * default for it is 1.5 s, and whatever is written here RAISES that — the 30 it

package/dist/config/adapters/claude-code.js

@@ -448,7 +448,7 @@ export function setLocalEntries(claudeJson, keys, name, entry, shouldTouch = ()
  * to its `timeout`, so each number here is how long a slow or blackholed
  * service could make a person wait — at every prompt, every tool call, every
  * `/exit`. The control server keeps its own per-route deadlines well inside
- * them (prompt ≤ 7 s, tool/pre ≤ 12 s, tool/post and stop ≤ 2 s, end ≤ 1 s,
+ * them (prompt ≤ 8.5 s, tool/pre ≤ 12 s, tool/post and stop ≤ 2 s, end ≤ 1 s,
  * start ≤ 2 s) and answers `{}` on overrun, so these are the second line of
  * defence, not a budget to spend. SessionEnd matters twice: Claude Code's own
  * default for it is 1.5 s, and whatever is written here RAISES that — the 30 it
@@ -460,7 +460,7 @@ export const HOOK_ROUTES = [
     { event: "SessionStart", route: "/session/start", matcher: "", timeout: 5 },
     // Awaits the similar-prompt match and the derivation before it can return a
     // steering directive (docs/calculatedReplay.md §10); the server caps the
-    // whole route at 7 s.
+    // whole route at 8.5 s.
     //
     // It must NEVER become `async`. An async hook is fire-and-forget, so it cannot
     // return `additionalContext` at all — replay would silently never arm.

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;
     /**
@@ -712,6 +743,11 @@ export declare class ControlServer {
      * told of it, so it must never steer or diverge a call: it is kept only as
      * what it now is — a matched turn the agent does itself, which still owes the
      * ledger its baseline sample (§11.1) — exactly like a declined match.
+     *
+     * `why` is the code the report carries when the plan was only late. Without
+     * it the service got a matched turn that was not steered and no reason, and
+     * its console could only say that the runner had given none. A plan a gate
+     * declined keeps the gate's own code.
      */
     private shelve;
     /**

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";
@@ -64,7 +64,9 @@ const PROXY_REPORT_GRACE_MS = 1_500;
  */
 const HOOK_DEADLINE_MS = {
     "/session/start": 2_000,
-    "/session/prompt": 7_000,
+    // A second past {@link PROMPT_WAIT_MS}, and a second and a half inside the
+    // 10 s Claude Code gives the hook.
+    "/session/prompt": 8_500,
     "/tool/pre": 12_000,
     "/tool/post": 2_000,
     "/session/agent": 2_000,
@@ -79,10 +81,19 @@ const PREVIEW_RESERVE_MS = 500;
 /**
  * What `UserPromptSubmit` may spend on replay: the similar-prompt match plus
  * any derivation a matched scenario with a target needs before its directive
- * can go out (segmented.md R-PARAM-4). Below the route's 7 s deadline, so the
- * decision to steer is always taken here and never by the guard.
+ * can go out (segmented.md R-PARAM-4). Below the route's 8.5 s deadline, so
+ * the decision to steer is always taken here and never by the guard.
+ *
+ * LONGER THAN THE SERVICE MAY TAKE TO READ, ON PURPOSE. The service gives a
+ * reading 6 s (its RUNNER_DERIVE_TIMEOUT_MS) and answers either way, so with
+ * the match and the round trip an answer can be 6.5 s after the prompt. At
+ * 6 s this wait ended before that answer could arrive: on 2026-10-08 a
+ * reading that took 6.0 s armed its plan 0.3 s after the prompt had been
+ * answered, and a good 20-step plan was thrown away (`arm_timeout`) for a
+ * turn the agent then spent 39 s on. The wait is only ever this long while a
+ * matched plan's values are still being read.
  */
-const PROMPT_WAIT_MS = 6_000;
+const PROMPT_WAIT_MS = 7_500;
 /**
  * How long a `PreToolUse` waits for the intent probe when that probe may arm a
  * plan in the call's place (`BIR_INTENT_ARM_BUDGET_MS`). A clear match or a
@@ -1629,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 = "") {
@@ -1639,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;
@@ -1651,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;
@@ -1666,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);
@@ -1688,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();
@@ -1723,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.
@@ -1768,12 +1777,12 @@ export class ControlServer {
                 });
             }
             if (state) {
-                this.shelve(session, run, state);
+                this.shelve(session, run, state, "arm_unannounced");
             }
             else {
                 void arming.then((late) => {
                     if (late)
-                        this.shelve(session, run, late);
+                        this.shelve(session, run, late, "arm_timeout");
                 });
             }
             return undefined;
@@ -1858,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
@@ -1865,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.
@@ -2128,7 +2177,7 @@ export class ControlServer {
                 scenario: state.scenarioId ?? undefined,
                 why: "the prompt was answered without this plan's directive — retired unannounced, so never run",
             });
-            this.shelve(session, run, state);
+            this.shelve(session, run, state, "arm_unannounced");
         }
     }
     /**
@@ -2136,14 +2185,20 @@ export class ControlServer {
      * told of it, so it must never steer or diverge a call: it is kept only as
      * what it now is — a matched turn the agent does itself, which still owes the
      * ledger its baseline sample (§11.1) — exactly like a declined match.
+     *
+     * `why` is the code the report carries when the plan was only late. Without
+     * it the service got a matched turn that was not steered and no reason, and
+     * its console could only say that the runner had given none. A plan a gate
+     * declined keeps the gate's own code.
      */
-    shelve(session, run, late) {
+    shelve(session, run, late, why) {
         if (late.plan && !late.retired) {
             logDetail("replay.shelved", {
                 run: run.runId,
                 scenario: late.scenarioId ?? undefined,
                 why: "armed without its directive reaching the model — retired, never steers",
             });
+            late.declined ??= why;
         }
         late.sessionId = session.sessionId;
         late.plan = undefined;
@@ -2419,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.
@@ -2496,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

@@ -507,7 +507,20 @@ export type DeclineCode = "replay_disabled" | "not_ready" | "flatten_failed" | "
 /** 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";
+ | "host_tool_missing"
+/**
+ * No gate said no: the plan was good, and late. Not ready when the prompt
+ * had to be answered (`arm_timeout`), or ready just after it had been
+ * (`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"
+/**
+ * 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. */
@@ -580,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,
@@ -878,7 +884,7 @@ The hook is on the user's critical path. Every await here is a stall the user wa
 
 | Moment | Route | Hook timeout | Answered by | What may be awaited | Budget |
 |---|---|---|---|---|---|
-| `UserPromptSubmit` | `/session/prompt` | 10 s | 7 s | the match; for a scenario with a target, its derivation; a steer plan's argument preview | match `BIR_MATCH_BUDGET_MS` = **3000**; match and arming together ≤ **6 s**; derivation ≤ `BIR_HOOK_DERIVE_BUDGET_MS` = **8000**, cut short by the 6 s |
+| `UserPromptSubmit` | `/session/prompt` | 10 s | 8.5 s | the match; for a scenario with a target, its derivation; a steer plan's argument preview | match `BIR_MATCH_BUDGET_MS` = **3000**; match and arming together ≤ **7.5 s**; derivation ≤ `BIR_HOOK_DERIVE_BUDGET_MS` = **8000**, cut short by the 7.5 s |
 | `PreToolUse` | `/tool/pre` | 15 s | 12 s | `plan.ready()` (derivation); on a divergence, the remaining steps | derivation ≤ min(`BIR_DERIVE_BUDGET_MS`, `BIR_HOOK_DERIVE_BUDGET_MS`) = **8000**; all replay work ≤ `BIR_PRETOOL_REPLAY_BUDGET_MS` = **9000** (held at ≤ 10 000) |
 | `run_scenario` | `/scenario/run` | `bir-scenario`'s own, **290 s** (`BIR_SCENARIO_RUN_TIMEOUT_MS`) | — | `ready()` + N steps | derivation `BIR_DERIVE_BUDGET_MS` = **8000**; plan `BIR_REPLAY_PLAN_BUDGET_MS` = **100000** (`BIR_REPLAY_BUDGET_MS` overrides it where set); per step `BIR_STEP_TIMEOUT_MS` = **60000**, clipped to what the plan has left |
 | `PostToolUse` | `/tool/post` | 5 s | 2 s | nothing | — |
@@ -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/docs/calculatedReplayGuide.md

@@ -638,7 +638,7 @@ Code's pool, as before.
 | No `run.matched`, ever | Prompt below the server's `SIMILARITY_THRESHOLD` | Rephrase closer, or lower it server-side. Confirm the original run is in the list — a sub-`RECORDING_MIN_ACTIONS` run is never embedded |
 | `run.matched` but no `plan.armed` | A gate declined | Read the `replay.decision` line's `why=`. Ranked by frequency: replay off — `bir replay off`, `BIR_REPLAY=0`, or never switched on here (a `bir install` without `--replay`; `bir replay status` says which) · scenario not `ready` · similarity below threshold · no step is executable |
 | `replay.decision … code=match_timeout` or `code=service_unhealthy` on many prompts | The service answered the match slower than `BIR_MATCH_BUDGET_MS` (3 s), or is failing and in its cool-down | Nothing breaks: those turns run normally, and after a slow match prompts stop waiting on it for a while by themselves (`replay.match_gate`). `bir doctor` shows the service's state. Raise `BIR_MATCH_BUDGET_MS` only if the service is reliably just over it — every prompt pays it |
-| `replay.decision … code=arm_timeout`, `code=missing_target … derivation did not answer within …ms`, or `code=no_derive_key why="service: …"`, on a prompt that names its values | The reading of the prompt's values (the derivation) was too slow for the hook, or failed on the service. A hook waits `BIR_HOOK_DERIVE_BUDGET_MS` (8 s) for it, and the prompt hook never past 6 s from the prompt, match included; the service gives one reading `RUNNER_DERIVE_TIMEOUT_MS` (6 s) and then answers `service: error` or `service: timeout` | Nothing to change in the prompt, and nothing to sign in to: that turn ran normally. The `replay.derived` line that follows says when the reading landed and what it cost. If it is slow every time, the service's reading model is the cause; `BIR_DERIVE_API_KEY` where Claude Code starts moves the reading to this machine |
+| `replay.decision … code=arm_timeout`, `code=missing_target … derivation did not answer within …ms`, or `code=no_derive_key why="service: …"`, on a prompt that names its values | The reading of the prompt's values (the derivation) was too slow for the hook, or failed on the service. A hook waits `BIR_HOOK_DERIVE_BUDGET_MS` (8 s) for it, and the prompt hook never past 7.5 s from the prompt, match included; the service gives one reading `RUNNER_DERIVE_TIMEOUT_MS` (6 s) and then answers `service: error` or `service: timeout`, so its answer arrives inside the prompt's wait either way | Nothing to change in the prompt, and nothing to sign in to: that turn ran normally. The `replay.derived` line that follows says when the reading landed and what it cost. If it is slow every time, the service's reading model is the cause; `BIR_DERIVE_API_KEY` where Claude Code starts moves the reading to this machine |
 | `replay.decision … code=no_delivery_tool` | A direct plan, and no running `bir` server has told the recorder it serves `run_scenario`: the server is missing, disabled or failed in `/mcp`, was not added (a subdirectory or worktree of a repository), or the session was started with `BIR_OFF=1` | `/mcp` shows whether `bir` is connected. `bir install --replay` adds it, in the project's own directory; then start a new session |
 | `replay.vetoed … the model's first call was …, not run_scenario` | A direct plan, and the model reached for another tool first — usually because it has no `run_scenario` | As for `no_delivery_tool`. Nothing ran; the model did the task |
 | `replay.decision … code=host_records_only` | A LangChain application (§6.5) whose adapter asked for no plan with its prompt: it only records. `bir investigate` gives the cause: the runner in that application's folder is older than replay for LangChain needs, so the LangChain package only records | In `bir investigate`'s words: nothing to do while replay for LangChain is not released. After that: update the runner. Until then the model does the task, and the run counts as a sample of the usual cost |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basein/runner",
-  "version": "0.3.10",
+  "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

@@ -122,7 +122,7 @@ In practice: the runner must never be the reason a Claude Code session is slow,
 |---|---|---|---|---|---|
 | SessionStart: command hook `bir-hooks ensure` | the payload on stdin (≤ 2 s); finding or starting the recorder (local only, never the service); relaying the payload (≤ 2.5 s); a read-only stale-copy check (only with ≥ 3 s left) | warm about 0.1 s (Node start-up); cold about 0.7 s on Windows, once per project per boot | 11.5 s (11 s budget plus a 0.5 s hard exit). npx installs pass `--budget-ms 8000`, after npx's own start-up | `/session/start`: 2 s | 15 s (30) |
 | SessionStart: HTTP form (older installs only; `bir install` now always writes the command hook, and `bir setup` replaces the HTTP one) | nothing | milliseconds | 2 s | 2 s | 5 s (10) |
-| UserPromptSubmit | replay on: the similar-prompt match (≤ 3 s; skipped while the breaker is open or the match gate holds). For a matched scenario: arming, derivation (budget 8 s, cut short by this hook's 6 s) and the directive's argument preview (≤ 1.2 s), all inside 6 s. Replay off: nothing | about 17 ms with an instant local service; plus one service round trip (about 0.3-0.5 s) with replay on | 6 s, only for a matched scenario that must derive; 3 s on the first prompt of a hang | 7 s | 10 s (15) |
+| UserPromptSubmit | replay on: the similar-prompt match (≤ 3 s; skipped while the breaker is open or the match gate holds). For a matched scenario: arming, derivation (budget 8 s, cut short by this hook's 7.5 s) and the directive's argument preview (≤ 1.2 s), all inside 7.5 s. Replay off: nothing | about 17 ms with an instant local service; plus one service round trip (about 0.3-0.5 s) with replay on | 7.5 s, only for a matched scenario whose values are still being read; 3 s on the first prompt of a hang | 8.5 s | 10 s (15) |
 | PreToolUse | nothing, unless a replay plan steers this turn. Then: in-hook steps (≤ 9 s, `BIR_PRETOOL_REPLAY_BUDGET_MS`), derivation at the first call (≤ 8 s), the previous pinned step (≤ 1.75 s), and after a hand-over the new fragment run's create (≤ 0.3 s, breaker-gated). Intent arming only when opted in (≤ 0.5 s probe + 1.5 s arming) | 2-5 ms | 12 s, replay only | 12 s | 15 s (30) |
 | PostToolUse, PostToolUseFailure | nothing: the proxy's report is joined in the background | 1-2 ms | 2 s | 2 s | 5 s (30) |
 | SubagentStart, SubagentStop | nothing | not measured (bookkeeping only) | 2 s | 2 s | 3 s (5) |
@@ -135,7 +135,7 @@ Hard deadlines are in `HOOK_DEADLINE_MS` (`src/control/server.ts`). The timeouts
 
 - **What setup does.** It signs in, gives the folder an entry of its own in `installed.json` (a fixed port, a token and `hosts: ["langchain"]`), stores replay on (off with `--no-replay`), starts the recorder in the background and prints the two lines of Python to add to the agent.
 - **What it leaves alone.** It writes nothing under `.claude/` and nothing into `~/.claude.json`: no hooks, no wrapped servers, no `bir` MCP server. A folder that is already set up for Claude Code keeps that set-up as it is, and only its entry notes the host.
-- **Deadlines.** The server deadlines above are set per route, so they hold for the adapter's requests too: `/session/prompt` 7 s, `/tool/pre` 12 s, `/tool/post` and `/session/stop` 2 s. The timeouts `bir install` writes are Claude Code's own.
+- **Deadlines.** The server deadlines above are set per route, so they hold for the adapter's requests too: `/session/prompt` 8.5 s, `/tool/pre` 12 s, `/tool/post` and `/session/stop` 2 s. The timeouts `bir install` writes are Claude Code's own.
 
 The fields the adapter adds to each route, and what the recorder does for such a session, are in `docs/BaseInstRunner.md`, Phase 5. The how-to is `langChainGuide.md` in the repository's root; it is not in the npm package. The runner's part is all in this package. The Python package is not on PyPI, and the service's part is built and not deployed yet.
 
@@ -370,7 +370,7 @@ Over 2-minute runs with one turn every 8 s (92 hooks):
 
 **Deadlines and fail-open answers.**
 
-- **Deadlines.** Hard per-route deadlines apply: start 2 s, prompt 7 s, pre 12 s, post, agent and stop 2 s, end 1 s. Past a deadline the route answers `{}`, or an honest note mid-replay.
+- **Deadlines.** Hard per-route deadlines apply: start 2 s, prompt 8.5 s, pre 12 s, post, agent and stop 2 s, end 1 s. Past a deadline the route answers `{}`, or an honest note mid-replay.
 - **Fail-open answers.** Stale or wrong tokens, unknown routes, non-POST requests, bodies over 64 MB (read and discarded) and non-object bodies all get `200 {}`. They are counted in `/health.hooks`. Non-hook routes keep 401, 404 and 405.
 - **Event name.** Every answer's `hookEventName` matches the event that fired. The final review found a PostToolUseFailure answered as PostToolUse, which Claude Code rejects with a visible hook error that dumps the runner's JSON.
 - **Token.** The project's current token is read from `installed.json`: re-read at most every 3 s, and only when the file changed. A reinstall on the same port needs no recorder restart.
@@ -379,7 +379,7 @@ Over 2-minute runs with one turn every 8 s (92 hooks):
 
 - The match waits up to 3 s, and only while the breaker allows it.
 - The match gate: over 2 s, prompts stop waiting for 5 min, doubling to 30 min.
-- Arming a matched scenario, including derivation and the directive's argument preview, stays inside 6 s.
+- Arming a matched scenario, including derivation and the directive's argument preview, stays inside 7.5 s. That is longer than the service may take to read a prompt's values (6 s, its `RUNNER_DERIVE_TIMEOUT_MS`) plus the match and the round trip: at 6 s the hook gave up before the service could answer, and a good plan was thrown away (`arm_timeout`).
 - A plan that is ready only after the prompt was answered is retired unannounced, so it never steers (`replay.decision code=arm_unannounced` or `arm_timeout`).
 - With replay off, the prompt never waits.
 - The prompt after an interrupted turn, and SessionEnd, seal synchronously and drain in the background. They used to wait for the whole backlog to reach the service (0.5 s healthy, over 30 s hung).
@@ -601,7 +601,7 @@ Truncation is always marked with the original size.
 
 **Budgets.**
 
-- The hook derivation wait is 8 s (the prompt hook stops at its own 6 s). All replay work in one PreToolUse is capped at 9 s (maximum 10 s).
+- The hook derivation wait is 8 s (the prompt hook stops at its own 7.5 s). All replay work in one PreToolUse is capped at 9 s (maximum 10 s).
 - The direct plan budget is 100 s (was 120 s). Direct runs are clamped so that derivation, plan and slack stay within 270 s, under `run_scenario`'s 290 s client timeout.
 - The worst case by budget is 120 s: 8 s of derivation, 100 s of plan, and 12 s of slack.
 
@@ -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`. |