@basein/runner 0.2.1 → 0.2.3

package/README.md

@@ -201,8 +201,8 @@ what to do when they register, so there is one switch and no second copy of it:
 | `BIR_REPLAY=1` | Enable replay. Nothing below matters until it is set. |
 | `BIR_REPLAY_ALLOW_SERVERS` | Server keys eligible for **direct** execution. Unset means every wrapped server; setting it is the recommendation. |
 | `BIR_MIN_STEER_SIMILARITY` | Minimum match similarity to replay (default `0.92`, above the service's own `0.9` detection threshold). |
-| `ANTHROPIC_API_KEY` | Enables parameter derivation. Without it, replay uses the scenario's recorded sample values — free, and often still correct. |
-| `BIR_DERIVE_MODEL` | Derivation model (default `claude-haiku-4-5-20251001`). |
+| `ANTHROPIC_API_KEY` | **Optional.** Working out what a new request is about — which fleet, which file, which date — is done for you by the service on its own key, as long as you are signed in. Set this only to keep that reading on your machine, on your key. Signed out *and* unset, a scenario whose values change between requests is declined rather than replayed on stale ones. |
+| `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 `2500`). |
 | `BIR_DERIVE_BUDGET_MS` | How long the first `PreToolUse` waits for parameters (default `8000`). |
 | `BIR_REPLAY_BUDGET_MS` / `BIR_STEP_TIMEOUT_MS` | Whole-plan and per-step ceilings for direct execution (default `120000` / `60000`). |

package/dist/bin/bir-hooks.d.ts

@@ -27,9 +27,11 @@
  *   BIR_REPLAY_ALLOW_SERVERS  comma-separated server keys eligible for *direct*
  *                             execution. Unset means every wrapped server
  *   BIR_MIN_STEER_SIMILARITY  minimum match similarity to replay (default 0.92)
- *   ANTHROPIC_API_KEY         enables parameter derivation. Without it, replay
- *                             uses the scenario's recorded sample values — free,
- *                             and often still correct
+ *   ANTHROPIC_API_KEY         OPTIONAL. Derivation — reading what this turn acts
+ *                             on — is done by the service for a signed-in
+ *                             runner. Set this only to keep that reading on this
+ *                             machine; signed out and unset, a scenario with a
+ *                             target does not run (segmented.md R-PARAM-5)
  *   BIR_DERIVE_MODEL          derivation model (default claude-haiku-4-5-…)
  *   BIR_MATCH_BUDGET_MS       prompt-hook match wait (default 2500)
  *   BIR_DERIVE_BUDGET_MS      first PreToolUse derivation wait (default 8000)

package/dist/bin/bir-hooks.js

@@ -27,9 +27,11 @@
  *   BIR_REPLAY_ALLOW_SERVERS  comma-separated server keys eligible for *direct*
  *                             execution. Unset means every wrapped server
  *   BIR_MIN_STEER_SIMILARITY  minimum match similarity to replay (default 0.92)
- *   ANTHROPIC_API_KEY         enables parameter derivation. Without it, replay
- *                             uses the scenario's recorded sample values — free,
- *                             and often still correct
+ *   ANTHROPIC_API_KEY         OPTIONAL. Derivation — reading what this turn acts
+ *                             on — is done by the service for a signed-in
+ *                             runner. Set this only to keep that reading on this
+ *                             machine; signed out and unset, a scenario with a
+ *                             target does not run (segmented.md R-PARAM-5)
  *   BIR_DERIVE_MODEL          derivation model (default claude-haiku-4-5-…)
  *   BIR_MATCH_BUDGET_MS       prompt-hook match wait (default 2500)
  *   BIR_DERIVE_BUDGET_MS      first PreToolUse derivation wait (default 8000)
@@ -182,7 +184,13 @@ function buildReplayOptions(auth) {
         logLine("replay.enabled", {
             minSimilarity: opts.minSimilarity,
             allowServers: allowServers ? [...allowServers].join(",") : "(all wrapped)",
-            derive: process.env.ANTHROPIC_API_KEY ? "anthropic" : "recorded sample values",
+            // Who reads what this turn acts on (segmented.md R-PARAM-5). Named at
+            // startup because the third state is a replay that silently never runs.
+            derive: process.env.ANTHROPIC_API_KEY
+                ? "this machine (ANTHROPIC_API_KEY)"
+                : auth.session && auth.baseUrl
+                    ? "the service"
+                    : "recorded sample values — sign in, or a scenario with a target will not run",
             intentMatch: opts.intentMatch?.enabled ? "on" : "off",
             why: "matched prompts will run their calculated scenario — steered steps are auto-approved",
         });

package/dist/bin/bir.js

@@ -576,6 +576,17 @@ async function doctor(args) {
         problems.push(`BIR_AUTH_URL in this shell (${shellAuthUrl}) is not a BaseIn service: ${shellAuthProblem}. ` +
             `\`bir login\` and \`bir scenario\` here will fail — ${AUTH_URL_HINT}`);
     }
+    // THE SCENARIO SERVER IS ON THE CRITICAL PATH OF THE FIRST TURN. A plan armed
+    // at `UserPromptSubmit` is delivered through `mcp__bir__run_scenario`, so a
+    // `bir` entry that starts with `npx` has to resolve and unpack the package
+    // before the tool exists at all — measured at ~13s, against a first tool call
+    // ~6s in. The turn does not fail; it just quietly runs the ordinary way, which
+    // is the failure this whole command exists to make visible.
+    const scenarioEntry = entries.find((e) => e.name === SCENARIO_SERVER_KEY);
+    if (scenarioEntry && !isRemote(scenarioEntry.config) && scenarioEntry.config.command === "npx") {
+        notes.push("the bir scenario server starts via npx, which can take longer than the first tool call " +
+            "of a turn — reinstall with `bir install --replay --global` to pin it to the installed copy");
+    }
     const sidecar = readSidecar();
     if (sidecar.controlPort && discovery && !discovery.url.endsWith(`:${sidecar.controlPort}`)) {
         problems.push(`hooks were installed for port ${sidecar.controlPort} but the control server is on ${discovery.url}`);
@@ -600,7 +611,20 @@ async function doctor(args) {
     if (replay?.enabled) {
         out(`Replay            : ON  servers=${replay.allowServers?.join(",") || "(all wrapped)"}  ` +
             `minSimilarity=${replay.minSimilarity ?? "?"}`);
-        out(`                    derive=${replay.deriveKey ? "anthropic" : "recorded sample values (no ANTHROPIC_API_KEY)"}`);
+        // An older control server sends only `deriveKey`; read it as the two states
+        // it could describe then.
+        const via = replay.deriveVia ?? (replay.deriveKey ? "key" : "samples");
+        const derive = via === "key"
+            ? "this machine (ANTHROPIC_API_KEY)"
+            : via === "service"
+                ? "the service (no key needed here)"
+                : "recorded sample values — scenarios with a target will NOT run";
+        out(`                    derive=${derive}`);
+        if (via === "samples") {
+            notes.push("nothing can read what this turn acts on: sign in with `bir login` so the " +
+                "service derives, or set ANTHROPIC_API_KEY to derive here. Until then a " +
+                "matched scenario with a target is declined and the agent does the task");
+        }
         const idle = wantWrapped.filter((n) => !(replay.pollingProxies ?? []).includes(n));
         if (idle.length > 0) {
             notes.push(`these proxies are not polling for replay work: ${idle.join(", ")} — ` +
@@ -783,6 +807,14 @@ async function replayCommand(args) {
         }
         const r = body;
         out(`params      ${JSON.stringify(r.params ?? {})}`);
+        // The difference between "this scenario works" and "this scenario works on
+        // last week's values". A dry replay fills an unnamed target from the
+        // recording; a real turn never does, so without this line a green trace here
+        // is no evidence at all that a session would steer.
+        if (r.targetsFromSamples?.length) {
+            out(`            ↑ not named by the prompt: ${r.targetsFromSamples.join(", ")}`);
+            out("              (a live turn finds these in an earlier step, or does not run)");
+        }
         (r.steps ?? []).forEach((s, i) => {
             out(`step ${i}      ${s.toolName}  ${JSON.stringify(s.input)}`);
             const emitted = Object.keys(s.emitted ?? {});

package/dist/control/server.js

@@ -212,6 +212,15 @@ export class ControlServer {
                 minSimilarity: this.opts.replay?.minSimilarity ?? null,
                 allowServers: this.opts.replay?.allowServers ? [...this.opts.replay.allowServers] : null,
                 deriveKey: Boolean(this.opts.replay?.apiKey ?? process.env.ANTHROPIC_API_KEY),
+                // Who reads the turn for its parameters (segmented.md R-PARAM-5). The
+                // ordinary answer is `service`; a key here is an override; `samples`
+                // means no scenario with a target can run, which is the one state an
+                // operator must be able to see without reading a log.
+                deriveVia: (this.opts.replay?.apiKey ?? process.env.ANTHROPIC_API_KEY)
+                    ? "key"
+                    : this.opts.replay?.authUrl && this.opts.replay?.authToken
+                        ? "service"
+                        : "samples",
                 pollingProxies: this.replay.work.pollingServers(),
             },
             lossy: this.lossy,

package/dist/record/recorder.d.ts

@@ -263,6 +263,17 @@ export interface ExecutionReport {
      * two baselines of one turn. The segments' own rows are untouched.
      */
     sharedWith?: string[];
+    /**
+     * Which gate of the ladder declined, on a `not_steered` report.
+     *
+     * The one thing the recording page could never learn. "Replay on, scenario
+     * ready, prompt matched, nothing steered" has exactly one explanation and it
+     * used to live only in a stderr line on the machine that decided it — so the
+     * owner of a scenario that never runs had nothing to look at. It travels as
+     * the gate's own code rather than the sentence beside it: the prose is for a
+     * person reading the audit log, this is for the console.
+     */
+    declined?: string;
 }
 /** Optional capability: reporting needs a service, and a NullRecorder has none. */
 export interface ScenarioReporter {

package/dist/record/remote-recorder.js

@@ -212,6 +212,9 @@ export class RemoteRecorder {
                 fallbackKind: report.fallbackKind,
                 baselineEligible: report.baselineEligible,
                 sharedWith: report.sharedWith,
+                // Why nothing ran, when nothing ran. Additive: an older service drops
+                // the field and books the cost exactly as it always did.
+                declined: report.declined,
             });
             const r = (body ?? {});
             const failed = report.steps?.filter((s) => s.status === "failed").length ?? 0;
@@ -228,6 +231,7 @@ export class RemoteRecorder {
                 stepsFailed: failed || undefined,
                 baselineEligible: report.baselineEligible === false ? false : undefined,
                 sharedWith: report.sharedWith?.length,
+                declined: report.declined,
             });
         });
     }

package/dist/replay/controller.d.ts

@@ -54,7 +54,10 @@ export interface ReplayOptions {
     /** `BIR_REPLAY_ALLOW_SERVERS`; undefined means every wrapped server. */
     allowServers?: ReadonlySet<string>;
     budgets?: Partial<ReplayBudgets>;
-    /** For the lazy source-run fetch and nothing else. */
+    /**
+     * The service: the lazy source-run fetch, and the parameter derivation this
+     * runner no longer needs a key of its own for (segmented.md R-PARAM-5).
+     */
     authUrl?: string;
     authToken?: () => string;
     /** Injected by tests. */
@@ -378,6 +381,17 @@ export declare class ReplayController {
      * directive the moment the match lands; the first `PreToolUse` — or
      * `/scenario/run`, which has no hook timeout at all — is where the wait lands.
      */
+    /**
+     * Where to ask the service to read this turn (segmented.md R-PARAM-5).
+     *
+     * Undefined when there is nobody to ask — an unauthenticated session, or one
+     * whose token has gone. `derive` then falls back to the recorded samples, and
+     * a scenario with a target declines, exactly as a keyless runner always did.
+     *
+     * The token is read here rather than captured, because the recorder refreshes
+     * it as a session outlives it.
+     */
+    private deriveService;
     private startDerivation;
     /**
      * Divergence (§8). Execute the remaining steps for real, then deliver.

package/dist/replay/controller.js

@@ -25,6 +25,7 @@ import { ScenarioReplayPlan } from "./plan.js";
 import { PRICING_VERSION } from "./pricing.js";
 import { SourceRunOutputs } from "./source-run.js";
 import { clampToFrameStart, flattenChain, } from "./flatten.js";
+import { blockingTargets } from "./targets.js";
 import { toolResultError } from "./tool-error.js";
 import { OUTCOME_RANK, hasTargets, isReadyScenario, } from "./types.js";
 /** The first-party tool a `direct` plan is delivered through (§6.3). */
@@ -233,26 +234,60 @@ export class ReplayController {
         // because it is the only one that spends a model call and waits. A scenario
         // whose parameters are all settings arms at once, as before: there is
         // nothing the turn has to supply.
+        //
+        // A target the turn did not name stops the plan only when *this* plan could
+        // act on its recorded value; a target the chain discovers for itself does
+        // not ({@link ./targets.ts}). The unnamed value stays null either way, so
+        // nothing here ever runs on last week's.
         if (hasTargets(scenario.paramsObject)) {
+            // Of the targets this answer left unnamed, the ones this plan could act
+            // on the recorded value of. Empty means the chain finds them for itself.
+            const blocking = (missing) => blockingTargets(missing, scenario.paramsObject, planned);
             let result;
             try {
                 result = await this.withBudget(derivation, this.budgets.deriveMs, "derivation");
             }
             catch (err) {
-                // Out of budget, or the call threw. Either way the turn has not said
-                // what this task is to act on, and running it would act on something
-                // else (R-PARAM-3).
-                const first = firstTargetKey(scenario.paramsObject);
-                return decline(`target ${first ?? "(unknown)"} not found — ${errText(err)}`, "missing_target");
+                // Out of budget, or the call threw. The turn has not said what this task
+                // is to act on, so every target is unnamed (R-PARAM-3).
+                const blocked = blocking(targetKeys(scenario.paramsObject));
+                if (blocked.length > 0) {
+                    return decline(`target ${blocked[0]} not found — ${errText(err)}`, "missing_target");
+                }
+                logLine("replay.targets_unread", {
+                    scenario: scenario.id,
+                    why: "the derivation did not answer, and this chain takes no target from the caller",
+                    error: errText(err),
+                });
             }
-            if (!result.derived) {
-                // No key: settings can still take their recorded values, but a target
-                // is a guess nobody is allowed to make (R-PARAM-5).
-                const first = firstTargetKey(scenario.paramsObject);
-                return decline(`no_derive_key: target ${first ?? "(unknown)"}`, "no_derive_key");
+            if (result && !result.derived) {
+                // Nobody read the turn — no key here and no service to ask, or the
+                // service declined. Settings can still take their recorded values, but a
+                // target is a guess nobody is allowed to make (R-PARAM-5). The reason
+                // travels into the line, because "it did not run" without one is how
+                // this stayed invisible before.
+                //
+                // Every target is judged, not `missing`: an answer that derived nothing
+                // carries the recorded sample for *all* of them, so a chain that reads
+                // one would run on last week's value rather than on nothing.
+                const blocked = blocking(targetKeys(scenario.paramsObject));
+                if (blocked.length > 0) {
+                    return decline(`${result.reason ?? "no_derive_key"}: target ${blocked[0]}`, "no_derive_key");
+                }
             }
-            if (result.missing.length > 0) {
-                return decline(`target ${result.missing[0]} not found`, "missing_target");
+            else if (result && result.missing.length > 0) {
+                const blocked = blocking(result.missing);
+                if (blocked.length > 0) {
+                    return decline(`target ${blocked[0]} not found`, "missing_target");
+                }
+                // Worth a line of its own: this is the difference between a scenario
+                // that never runs and one that does, and it is the first thing to look
+                // at when a replay acts on the wrong thing.
+                logLine("replay.targets_found_by_chain", {
+                    scenario: scenario.id,
+                    unnamed: result.missing.join(","),
+                    why: "the chain computes these from its own steps; none is read from the caller",
+                });
             }
         }
         // A plan armed by intent runs inside a task the agent is already doing, so
@@ -678,10 +713,14 @@ export class ReplayController {
         const total = state.deriveCostUsd + d.sessionCostUsd + state.fallbackCostUsd;
         const steps = this.stepResultsOf(state);
         const isBaseline = state.outcome === "not_steered" || state.outcome === "failed";
-        // A costless decline is noise on both sides — *unless* a step actually broke,
-        // which is the one thing the recording page cannot learn any other way. The
-        // service accepts a costless report that says why (its errorshandling.md).
-        if (isBaseline && total <= 0 && !steps?.some((s) => s.status === "failed")) {
+        // A costless decline is noise on both sides — *unless* it says something the
+        // recording page cannot learn any other way: a step that actually broke, or
+        // the gate that declined. The service accepts a costless report that carries
+        // either (its errorshandling.md).
+        if (isBaseline &&
+            total <= 0 &&
+            !state.declined &&
+            !steps?.some((s) => s.status === "failed")) {
             return undefined;
         }
         const blame = this.blameStep(steps);
@@ -706,6 +745,10 @@ export class ReplayController {
             errorStage: blame?.stage,
             errorStepIndex: blame?.stepIndex,
             errorToolName: blame?.toolName,
+            // Which gate said no. Only ever set on a decline, and the decline is
+            // always `not_steered`, so a steered report carries it byte-identically
+            // to before.
+            declined: state.declined,
             // Where the plan handed the task to the model (fallbk.md). Only on
             // `fell_back`: a hand-over before any step ran is `failed`, and a parked
             // step found after a divergence is still a divergence.
@@ -886,6 +929,22 @@ export class ReplayController {
      * directive the moment the match lands; the first `PreToolUse` — or
      * `/scenario/run`, which has no hook timeout at all — is where the wait lands.
      */
+    /**
+     * Where to ask the service to read this turn (segmented.md R-PARAM-5).
+     *
+     * Undefined when there is nobody to ask — an unauthenticated session, or one
+     * whose token has gone. `derive` then falls back to the recorded samples, and
+     * a scenario with a target declines, exactly as a keyless runner always did.
+     *
+     * The token is read here rather than captured, because the recorder refreshes
+     * it as a session outlives it.
+     */
+    deriveService(scenarioId) {
+        const token = this.opts.authToken?.();
+        if (!this.opts.authUrl || !token)
+            return undefined;
+        return { baseUrl: this.opts.authUrl, token, scenarioId };
+    }
     startDerivation(scenario, prompt, state, ctx = {}) {
         const derive = this.opts.deriveImpl ?? deriveParameters;
         return derive({
@@ -893,6 +952,9 @@ export class ReplayController {
             intent: scenario.intent ?? "",
             paramsObject: scenario.paramsObject,
             apiKey: this.opts.apiKey ?? process.env.ANTHROPIC_API_KEY,
+            // Where to ask when there is no key here, which is the ordinary case
+            // (segmented.md R-PARAM-5).
+            service: this.deriveService(scenario.id),
             fetchImpl: this.opts.fetchImpl,
             liveCall: ctx.liveCall,
             recentResults: ctx.recentResults,
@@ -903,7 +965,12 @@ export class ReplayController {
                 scenario: scenario.id,
                 params: Object.keys(r.params).length,
                 costUsd: r.costUsd.toFixed(4),
-                source: r.derived ? "prompt" : "recorded samples",
+                source: r.derived
+                    ? r.via === "service"
+                        ? "the service"
+                        : "prompt"
+                    : "recorded samples",
+                why: r.derived ? undefined : r.reason,
                 missing: r.missing.length > 0 ? r.missing.join(",") : undefined,
                 sampled: r.sampled.length > 0 ? r.sampled.join(",") : undefined,
             });
@@ -1265,11 +1332,11 @@ export class ReplayController {
         });
     }
 }
-/** The first target of a schema, for the sentence a decline logs. */
-function firstTargetKey(schema) {
+/** Every target of a schema. A parameter with no kind is one (R-PARAM-3). */
+function targetKeys(schema) {
     if (!schema)
-        return undefined;
-    return Object.keys(schema).find((k) => schema[k]?.kind !== "setting");
+        return [];
+    return Object.keys(schema).filter((k) => schema[k]?.kind !== "setting");
 }
 /**
  * Position of the first step whose failure count is above `maxStepFailures`

package/dist/replay/derive.d.ts

@@ -10,11 +10,20 @@
  * most sessions never arm. This is ~40 lines of `fetch` and it keeps the package
  * at zero runtime dependencies.
  *
- * NO KEY IS A SUPPORTED CONFIGURATION. Without `ANTHROPIC_API_KEY` the extraction
- * is skipped entirely and every parameter takes the value it had in the recorded
- * run — a plain replay of the recorded parameters, at zero cost. For a scenario
- * whose parameters rarely change that is a complete, free replay; for one that
- * keys off the prompt, it is why you want the key.
+ * NO KEY IS THE ORDINARY CONFIGURATION (segmented.md R-PARAM-5). Without
+ * `ANTHROPIC_API_KEY` the reading is done by the **service**, over one authorized
+ * POST to `/scenarios/:id/derive`, under the key it already uses to calculate
+ * scenarios and to ask its live question. That is the path nearly every session
+ * takes: the people this runs for are inside Claude Code on a subscription and
+ * have no API key to give it.
+ *
+ * A key here is an override, not a requirement. It keeps the reading on this
+ * machine — the prompt never reaches the service — which is what an in-house
+ * deployment wants, and it is one round trip faster.
+ *
+ * NEITHER is still supported and still means the same thing it always did:
+ * settings take their recorded samples and a scenario with a target declines,
+ * because a target is never guessed.
  *
  * The prompt and the parsing tolerances mirror RRepeat's
  * `deriveParametersFromScenarioPayload` exactly, so the two produce the same
@@ -34,12 +43,27 @@ export interface DeriveContext {
     liveCall?: LiveCall;
     recentResults?: string[];
 }
+/**
+ * The service, which derives when this runner has no key of its own
+ * (R-PARAM-5). All three fields or none: a session that is not signed in has
+ * nowhere to ask.
+ */
+export interface DeriveService {
+    /** `BIR_AUTH_URL`, the same base the recorder reports to. */
+    baseUrl: string;
+    /** A live access token. Read late — the recorder refreshes it mid-session. */
+    token: string;
+    /** Whose parameters to read. The service takes the schema from its own row. */
+    scenarioId: string;
+}
 export interface DeriveOptions extends DeriveContext {
     prompt: string;
     intent: string;
     paramsObject: ParamsSchema | null;
-    /** Absent → sample values, at zero cost. */
+    /** An override that keeps the reading on this machine. Absent → the service. */
     apiKey?: string;
+    /** Used when there is no `apiKey`. Absent too → recorded samples. */
+    service?: DeriveService;
     model?: string;
     signal?: AbortSignal;
     /** Injected by tests. Defaults to global `fetch`. */
@@ -50,6 +74,10 @@ export interface DeriveResult {
     costUsd: number;
     /** False when the values came from the recorded samples rather than the model. */
     derived: boolean;
+    /** Who read the turn. For the audit line, and for nothing else. */
+    via?: "key" | "service" | "samples";
+    /** Why nothing was derived, when the service said. */
+    reason?: string;
     model?: string;
     inputTokens?: number;
     outputTokens?: number;

package/dist/replay/derive.js

@@ -10,11 +10,20 @@
  * most sessions never arm. This is ~40 lines of `fetch` and it keeps the package
  * at zero runtime dependencies.
  *
- * NO KEY IS A SUPPORTED CONFIGURATION. Without `ANTHROPIC_API_KEY` the extraction
- * is skipped entirely and every parameter takes the value it had in the recorded
- * run — a plain replay of the recorded parameters, at zero cost. For a scenario
- * whose parameters rarely change that is a complete, free replay; for one that
- * keys off the prompt, it is why you want the key.
+ * NO KEY IS THE ORDINARY CONFIGURATION (segmented.md R-PARAM-5). Without
+ * `ANTHROPIC_API_KEY` the reading is done by the **service**, over one authorized
+ * POST to `/scenarios/:id/derive`, under the key it already uses to calculate
+ * scenarios and to ask its live question. That is the path nearly every session
+ * takes: the people this runs for are inside Claude Code on a subscription and
+ * have no API key to give it.
+ *
+ * A key here is an override, not a requirement. It keeps the reading on this
+ * machine — the prompt never reaches the service — which is what an in-house
+ * deployment wants, and it is one round trip faster.
+ *
+ * NEITHER is still supported and still means the same thing it always did:
+ * settings take their recorded samples and a scenario with a target declines,
+ * because a target is never guessed.
  *
  * The prompt and the parsing tolerances mirror RRepeat's
  * `deriveParametersFromScenarioPayload` exactly, so the two produce the same
@@ -120,14 +129,20 @@ export async function deriveParameters(opts) {
     if (keys.length === 0)
         return { params: {}, costUsd: 0, derived: false, missing: [], sampled: [] };
     const apiKey = opts.apiKey ?? process.env.ANTHROPIC_API_KEY;
-    // No key is a supported configuration, and `derived: false` is how the caller
-    // tells it apart from a real extraction: it declines any scenario that has a
-    // target and arms an all-settings one on its recorded values (R-PARAM-5).
+    // No key of our own is the ordinary case: the service reads the turn instead,
+    // under the key it already spends on this account (R-PARAM-5).
+    if (!apiKey && opts.service)
+        return deriveViaService(opts, opts.service, schema, keys);
+    // No key and nowhere to ask — an unauthenticated session, or a deployment that
+    // turned service derivation off. `derived: false` is how the caller tells this
+    // apart from a real extraction: it declines any scenario that has a target and
+    // arms an all-settings one on its recorded values.
     if (!apiKey)
         return {
             params: sampleValues(schema),
             costUsd: 0,
             derived: false,
+            via: "samples",
             missing: [],
             sampled: keys,
         };
@@ -213,6 +228,7 @@ export async function deriveParameters(opts) {
         params: parsed,
         costUsd,
         derived: true,
+        via: "key",
         model,
         inputTokens,
         outputTokens,
@@ -220,4 +236,88 @@ export async function deriveParameters(opts) {
         sampled,
     };
 }
+/**
+ * Ask the service to read the turn (segmented.md R-PARAM-5).
+ *
+ * One authorized POST. The body carries the turn — the prompt, and whatever else
+ * this turn has said about its target — and never the schema: the service reads
+ * that from the scenario row it owns, so a stale copy here cannot change what is
+ * asked for.
+ *
+ * Never throws, and never worse than no key. A service that is off, out of
+ * budget, too slow or simply down answers `derived: false`, and so does every
+ * failure on this side, which is precisely the keyless behaviour this replaced:
+ * settings stand on their samples, and a target does not run.
+ */
+async function deriveViaService(opts, service, schema, keys) {
+    const samples = (reason) => ({
+        params: sampleValues(schema),
+        costUsd: 0,
+        derived: false,
+        via: "service",
+        reason,
+        missing: [],
+        sampled: keys,
+    });
+    const doFetch = opts.fetchImpl ?? fetch;
+    const url = `${service.baseUrl.replace(/\/+$/, "")}/scenarios/${service.scenarioId}/derive`;
+    let body;
+    try {
+        const res = await doFetch(url, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${service.token}`,
+            },
+            body: JSON.stringify({
+                prompt: opts.prompt,
+                liveCall: opts.liveCall,
+                recentResults: opts.recentResults,
+            }),
+            signal: opts.signal,
+        });
+        if (!res.ok)
+            return samples(`service HTTP ${res.status}`);
+        body = (await res.json());
+    }
+    catch (err) {
+        return samples(err instanceof Error ? err.message : String(err));
+    }
+    if (!body || typeof body !== "object")
+        return samples("service sent no answer");
+    if (body.derived !== true)
+        return samples(`service: ${body.reason ?? "declined"}`);
+    // Normalised again on this side, over *our* copy of the schema. The service
+    // answers in the same shape, but the plan runs on these values and the gate
+    // reads this `missing`: an older or newer service must not be able to leave a
+    // target unaccounted for.
+    const params = { ...(body.params ?? {}) };
+    const missing = [];
+    const sampled = [];
+    for (const key of keys) {
+        const value = params[key];
+        if (value !== null && value !== undefined)
+            continue;
+        if (isTarget(schema, key)) {
+            params[key] = null;
+            missing.push(key);
+        }
+        else {
+            params[key] = schema[key].sampleValue;
+            sampled.push(key);
+        }
+    }
+    return {
+        params,
+        // What the service spent on this turn, reported back on the execution so a
+        // replay's cost stays the whole truth about it (R-MONEY-2). The account is
+        // not billed for it; the service books it on its own ledger as well.
+        costUsd: typeof body.costUsd === "number" ? body.costUsd : 0,
+        derived: true,
+        via: "service",
+        model: body.model,
+        missing,
+        sampled,
+    };
+}
 //# sourceMappingURL=derive.js.map

package/dist/replay/targets.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Which missing targets actually stop a plan (segmented.md R-PARAM-3).
+ *
+ * The rule a target exists for is "never do the right work on the wrong thing":
+ * a value the turn did not name must never be filled in from the recording. The
+ * gate that enforces it used to read `missing.length > 0` and decline, which is
+ * the same thing only when every target is something the chain *takes from the
+ * caller*.
+ *
+ * It often is not. An analysis routinely lists a value that a later step
+ * computes from an earlier step's output and keeps the caller's copy as a bare
+ * fallback:
+ *
+ *     step 0  return { fleet: parameters.fleet };
+ *     step 1  return { id: (respParams.rankedDeviceIds || [])[0] ?? parameters.id };
+ *
+ * `id` is classified a target — it is what the second call acts on and it does
+ * change between requests — but no prompt ever names it, because the chain
+ * discovers it. Declining on it meant a scenario that matched, was ready, was
+ * enabled and would have run perfectly never ran at all, on every turn, with the
+ * reason only in a stderr line.
+ *
+ * So the question is not "did the turn name every target" but the narrower one
+ * the rule actually cares about: **could this plan act on the recorded value of
+ * a target the turn did not name?** It could, in exactly two ways:
+ *
+ *  1. some step reads `parameters.<key>` outright, rather than as the fallback
+ *     of a value computed at run time; or
+ *  2. some step's logic carries the recorded sample as a literal, so the value
+ *     is baked into the chain whether or not anybody reads the parameter.
+ *
+ * Neither true means the recorded value cannot reach a tool. The missing target
+ * stays `null` all the way through — {@link ./derive.ts} sets it, `paramsLogic`
+ * copies it, the `??` passes over it — so a chain that can compute the value
+ * runs on this turn's value, and one that cannot calls a tool with `null` and
+ * falls back to the model. What never happens, either way, is last week's fleet.
+ *
+ * Only frame 0 is judged here. A called segment runs on the parameters its
+ * call's `paramMapLogic` builds, not on these, so that body is scanned as a
+ * consumer and the segment's own steps are not (R-CALL-29).
+ */
+import type { FlatEntry } from "./flatten.js";
+import type { ParamsSchema } from "./types.js";
+/**
+ * The subset of `missing` this plan must decline on.
+ *
+ * Empty means every target the turn left unnamed is one the chain finds for
+ * itself. `missing` is returned unchanged whenever the schema or the plan is
+ * missing, so a caller that knows less than this one is never made to guess.
+ */
+export declare function blockingTargets(missing: readonly string[], schema: ParamsSchema | null | undefined, planned: readonly FlatEntry[]): string[];
+//# sourceMappingURL=targets.d.ts.map

package/dist/replay/targets.js

@@ -0,0 +1,133 @@
+/**
+ * Which missing targets actually stop a plan (segmented.md R-PARAM-3).
+ *
+ * The rule a target exists for is "never do the right work on the wrong thing":
+ * a value the turn did not name must never be filled in from the recording. The
+ * gate that enforces it used to read `missing.length > 0` and decline, which is
+ * the same thing only when every target is something the chain *takes from the
+ * caller*.
+ *
+ * It often is not. An analysis routinely lists a value that a later step
+ * computes from an earlier step's output and keeps the caller's copy as a bare
+ * fallback:
+ *
+ *     step 0  return { fleet: parameters.fleet };
+ *     step 1  return { id: (respParams.rankedDeviceIds || [])[0] ?? parameters.id };
+ *
+ * `id` is classified a target — it is what the second call acts on and it does
+ * change between requests — but no prompt ever names it, because the chain
+ * discovers it. Declining on it meant a scenario that matched, was ready, was
+ * enabled and would have run perfectly never ran at all, on every turn, with the
+ * reason only in a stderr line.
+ *
+ * So the question is not "did the turn name every target" but the narrower one
+ * the rule actually cares about: **could this plan act on the recorded value of
+ * a target the turn did not name?** It could, in exactly two ways:
+ *
+ *  1. some step reads `parameters.<key>` outright, rather than as the fallback
+ *     of a value computed at run time; or
+ *  2. some step's logic carries the recorded sample as a literal, so the value
+ *     is baked into the chain whether or not anybody reads the parameter.
+ *
+ * Neither true means the recorded value cannot reach a tool. The missing target
+ * stays `null` all the way through — {@link ./derive.ts} sets it, `paramsLogic`
+ * copies it, the `??` passes over it — so a chain that can compute the value
+ * runs on this turn's value, and one that cannot calls a tool with `null` and
+ * falls back to the model. What never happens, either way, is last week's fleet.
+ *
+ * Only frame 0 is judged here. A called segment runs on the parameters its
+ * call's `paramMapLogic` builds, not on these, so that body is scanned as a
+ * consumer and the segment's own steps are not (R-CALL-29).
+ */
+/**
+ * The subset of `missing` this plan must decline on.
+ *
+ * Empty means every target the turn left unnamed is one the chain finds for
+ * itself. `missing` is returned unchanged whenever the schema or the plan is
+ * missing, so a caller that knows less than this one is never made to guess.
+ */
+export function blockingTargets(missing, schema, planned) {
+    if (missing.length === 0)
+        return [];
+    if (!schema || planned.length === 0)
+        return [...missing];
+    const bodies = callerBodies(planned);
+    // Nothing to read the parameters: a plan with no logic at all cannot act on
+    // anything, but it is also not a shape worth reasoning about — keep it strict.
+    if (bodies.length === 0)
+        return [...missing];
+    return missing.filter((key) => bodies.some((body) => readsOutright(body, key) || carriesLiteral(body, schema[key]?.sampleValue)));
+}
+/**
+ * Every logic body that runs with the caller's own `parameters`.
+ *
+ * Both of a step's bodies, because `toolOutputLogic` is handed `parameters`
+ * too and a value baked in there travels just as far. Plus the `paramMapLogic`
+ * of each segment called directly from frame 0: it reads the caller's
+ * parameters to build the segment's.
+ */
+function callerBodies(planned) {
+    const bodies = [];
+    const seenFrames = new Set();
+    for (const entry of planned) {
+        if (entry.depth === 0) {
+            if (entry.step.toolInputLogic)
+                bodies.push(entry.step.toolInputLogic);
+            if (entry.step.toolOutputLogic)
+                bodies.push(entry.step.toolOutputLogic);
+            continue;
+        }
+        // The frame's own mapping, once, and only when its caller is frame 0.
+        const frame = entry.frame;
+        if (frame.depth !== 1 || seenFrames.has(frame.id))
+            continue;
+        seenFrames.add(frame.id);
+        if (frame.paramMapLogic)
+            bodies.push(frame.paramMapLogic);
+    }
+    return bodies;
+}
+/** `parameters.key`, `parameters["key"]`, `parameters['key']` — all three forms. */
+function referencePattern(key) {
+    const k = escapeRegExp(key);
+    return new RegExp(`parameters\\s*(?:\\.\\s*${k}\\b|\\[\\s*["']${k}["']\\s*\\])`, "g");
+}
+/**
+ * Whether `body` reads `key` other than as a fallback.
+ *
+ * A reference is a fallback when what stands immediately before it is `??` or
+ * `||` — the shape an analysis writes when the chain computes the value and
+ * keeps the caller's as a last resort. Every other reference is a read: the
+ * step wants the caller's value and nothing else will do.
+ */
+function readsOutright(body, key) {
+    const pattern = referencePattern(key);
+    for (let m = pattern.exec(body); m; m = pattern.exec(body)) {
+        const before = body.slice(0, m.index).trimEnd();
+        if (!before.endsWith("??") && !before.endsWith("||"))
+            return true;
+    }
+    return false;
+}
+/**
+ * Whether `body` carries the recorded sample as a literal.
+ *
+ * This is the case the parameter reference cannot see: `return { id: 'dev_4411' }`
+ * acts on last week's device without mentioning `parameters` at all. Read
+ * generously — a sample too short to search for (`1`, `on`) counts as carried,
+ * because a false "this plan is safe" is the one answer this file must not give.
+ */
+function carriesLiteral(body, sample) {
+    if (sample === null || sample === undefined)
+        return false;
+    const text = typeof sample === "string" ? sample : JSON.stringify(sample);
+    if (typeof text !== "string" || text.length === 0)
+        return false;
+    if (text.length < 3)
+        return true;
+    return body.includes(text);
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+//# sourceMappingURL=targets.js.map

package/docs/calculatedReplay.md

@@ -853,7 +853,8 @@ fail because of BaseInstRunner.**
 | Failure | Behaviour |
 |---|---|
 | `getMatch()` slower than the match budget | No plan. Ordinary turn. One `replay.decision` line |
-| No `ANTHROPIC_API_KEY` | Derivation skipped; the scenario's recorded `sampleValue`s are used. `deriveCostUsd: 0` |
+| No `ANTHROPIC_API_KEY` | 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 | Same as above, plus a `replay.derive_failed` line |
 | `toolInputLogic` throws | Divergence (§8) — never a crash |
 | `toolOutputLogic` throws | Retire the plan, abort to an ordinary turn, outcome `failed` |
@@ -982,7 +983,8 @@ export async function deriveParameters(opts: {
   prompt: string;
   intent: string;
   paramsObject: Record<string, { sampleValue: unknown; description: string }> | null;
-  apiKey?: string;                       // ANTHROPIC_API_KEY
+  apiKey?: string;                       // ANTHROPIC_API_KEY — an override
+  service?: { baseUrl: string; token: string; scenarioId: string };  // the default path
   model?: string;                        // default claude-haiku-4-5-20251001
   signal?: AbortSignal;
 }): Promise<{ params: Record<string, unknown>; costUsd: number; derived: boolean }>;
@@ -992,11 +994,16 @@ Behaviour, matching RRepeat's `deriveParametersFromScenarioPayload` exactly so t
 same parameters from the same prompt:
 
 - No `paramsObject` keys → `{}`, `costUsd: 0`.
-- **No `apiKey` → return every key's recorded `sampleValue`**, `costUsd: 0`, `derived: false`. A plain
-  replay of the recorded parameters, free, and the documented default for anyone without a key.
-- Otherwise `POST https://api.anthropic.com/v1/messages` with the same extraction prompt, tolerant
-  JSON extraction (first balanced `{…}`, `undefined` → `null`), and any `null`/missing key filled
-  from its `sampleValue`.
+- **No `apiKey` but a `service` → `POST {baseUrl}/scenarios/{id}/derive`** with the turn (prompt,
+  live call, recent results) and a bearer token, `derived` as the service answered. This is the
+  ordinary path: nearly every session runs inside Claude Code on a subscription and has no key of
+  its own (segmented.md R-PARAM-5). The answer is re-normalised here against this runner's own copy
+  of the schema, so the gate reads a `missing` computed from what will actually run.
+- **Neither → return every key's recorded `sampleValue`**, `costUsd: 0`, `derived: false`. Settings
+  stand on their samples; a scenario with a target declines rather than run on a stale one.
+- With an `apiKey`, `POST https://api.anthropic.com/v1/messages` with the same extraction prompt,
+  tolerant JSON extraction (first balanced `{…}`, `undefined` → `null`), and any `null`/missing
+  **setting** filled from its `sampleValue` — a `null` target is named in `missing` instead.
 
 Keeping this dependency-free is not purity. `bir-proxy` is spawned inside the host's process tree for
 *every* wrapped server; an npm install that pulls a model SDK into that path is a startup-latency and
@@ -1041,7 +1048,8 @@ bir replay --scenario <scnId> --prompt "…" [--dry]     alias; the Tier 2 / deb
 source run's *recorded* outputs — no real tools, no side effects, one Haiku call. Without `--dry`,
 `bir replay` runs the same plan through the same executor against the live proxies. `bir doctor`
 gains a `replay` block: on/off, the effective `BIR_REPLAY_ALLOW_SERVERS` allowlist,
-`BIR_MIN_STEER_SIMILARITY`, and whether an `ANTHROPIC_API_KEY` was found (§13.2, mitigation 3).
+`BIR_MIN_STEER_SIMILARITY`, and who derives — this machine, the service, or nobody, which is the
+state in which a scenario with a target never runs (§13.2, mitigation 3).
 
 ---
 

package/docs/calculatedReplayGuide.md

@@ -34,7 +34,7 @@ end-to-end smoke test.
 | 3 | `SIMILARITY_DETECTION_ENABLED=true` on the server (default) | otherwise no prompt ever matches |
 | 4 | BaseInstRunnerMCP built and installed in your project | `bir status` |
 | 5 | Tier 1 — the hooks wired and `bir-hooks` running | `bir doctor` |
-| 6 | *(replay only)* `ANTHROPIC_API_KEY` in the `bir-hooks` environment | optional — see §5.3 |
+| 6 | *(replay only)* signed in, so the service can read what each request acts on | `bir doctor` — `derive=the service`; an `ANTHROPIC_API_KEY` here replaces it, see §5.3 |
 
 Tier 1 is not optional for replay. A match is a match on **the prompt**, and a standalone proxy never
 sees one (design §1.1). If `bir doctor` says `tier: standalone`, replay cannot arm, and that is the
@@ -229,7 +229,7 @@ bir doctor
 
 ```
 replay          ON      servers=chrome-devtools,fleet-api   minSimilarity=0.92
-                derive=claude-haiku-4-5-20251001 (ANTHROPIC_API_KEY present)
+                derive=the service (no key needed here)
 control         http://127.0.0.1:53411   sess=birsess_…
 wrapped         chrome-devtools ✓ proxy pid 41822   fleet-api ✓ proxy pid 41823
 recording       yes  (https://your-basein-service)
@@ -246,8 +246,8 @@ there is exactly one switch and it cannot get out of step with itself.
 | `BIR_REPLAY` | *(unset)* | `1` enables replay. Nothing below matters until it is set |
 | `BIR_REPLAY_ALLOW_SERVERS` | *(all wrapped)* | Comma-separated server keys eligible for **direct** execution. **Set this** |
 | `BIR_MIN_STEER_SIMILARITY` | `0.92` | Below this a match is detected but not replayed (§8) |
-| `ANTHROPIC_API_KEY` | *(unset)* | Enables parameter derivation. Without it, replay uses the scenario's **recorded sample values** — free, and often still correct |
-| `BIR_DERIVE_MODEL` | `claude-haiku-4-5-20251001` | The derivation model |
+| `ANTHROPIC_API_KEY` | *(unset)* | **Not required.** Derivation — reading what this request acts on — is done by the service on its key for a signed-in runner. Set this to keep the reading on this machine instead: the prompt then never leaves it, and it is one round trip faster. Signed out *and* unset, only a scenario with nothing to work out replays |
+| `BIR_DERIVE_MODEL` | `claude-haiku-4-5-20251001` | The derivation model, when this machine does the reading |
 | `BIR_MATCH_BUDGET_MS` | `2500` | How long the prompt hook waits for a match before giving up |
 | `BIR_DERIVE_BUDGET_MS` | `8000` | How long the first `PreToolUse` waits for parameters |
 | `BIR_REPLAY_BUDGET_MS` | `120000` | Whole-plan ceiling for direct execution |

package/package.json

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