@basein/runner 0.2.5 → 0.2.6

package/README.md

@@ -110,10 +110,11 @@ between the two is not guaranteed.
   is a structural fact, not a limitation of this implementation.
 - **`claude-in-chrome`.** It is `scope: "dynamic"`, present in no config file, so
   there is no entry to rewrite.
-- **Replay, unless you turn it on.** Recording is the default and the whole of
-  what runs out of the box. Calculated replay — running a matched prompt's
-  scenario instead of rediscovering it — ships, but needs `bir install --replay`
-  *and* `BIR_REPLAY=1`, for the reason in the next section.
+- **Replay, unless you install it.** Recording is the whole of what runs out of
+  the box. Calculated replay — running a matched prompt's scenario instead of
+  rediscovering it — ships, but needs `bir install --replay`. Once installed it
+  is on by default; `BIR_REPLAY=0` turns it off, for the reason in the next
+  section.
 - **Change what the model does.** Tool descriptions are never edited. The
   model-visible changes are schema relaxation, below, and — only with
   `--replay` — one first-party tool.
@@ -134,7 +135,7 @@ record, calculate, check, enable, read the audit lines — is
 
 ```bash
 bir install --replay      # adds the `bir` MCP server; raises the prompt-hook timeout
-BIR_REPLAY=1 bir-hooks    # and this is the switch
+bir-hooks                 # replay is on by default; BIR_REPLAY=0 bir-hooks turns it off
 ```
 
 Two switches, not one, because of what replay is: **a scenario is a pre-approved
@@ -198,7 +199,7 @@ what to do when they register, so there is one switch and no second copy of it:
 
 | Variable | Effect |
 |---|---|
-| `BIR_REPLAY=1` | Enable replay. Nothing below matters until it is set. |
+| `BIR_REPLAY=0` | Disable replay. It is on by default; nothing below matters while this is `0`. |
 | `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` | **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. |

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

@@ -19,11 +19,12 @@
  *   BIR_NO_CORRELATION=1      never inject a call id; join on fingerprints
  *   BIR_VERBOSE=1             per-step detail lines
  *
- *   BIR_REPLAY=1              run a calculated scenario on a similar-meaning
- *                             match (docs/calculatedReplay.md). OFF by default,
- *                             and read §13.2 before turning it on: a replayed
- *                             step is auto-approved, and a directly executed one
- *                             never reaches the permission system at all.
+ *   BIR_REPLAY=0              turn OFF calculated replay — running a scenario on
+ *                             a similar-meaning match (docs/calculatedReplay.md).
+ *                             ON by default; unset or any value other than "0"
+ *                             keeps it on. Read §13.2: a replayed step is
+ *                             auto-approved, and a directly executed one never
+ *                             reaches the permission system at all.
  *   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)

package/dist/bin/bir-hooks.js

@@ -19,11 +19,12 @@
  *   BIR_NO_CORRELATION=1      never inject a call id; join on fingerprints
  *   BIR_VERBOSE=1             per-step detail lines
  *
- *   BIR_REPLAY=1              run a calculated scenario on a similar-meaning
- *                             match (docs/calculatedReplay.md). OFF by default,
- *                             and read §13.2 before turning it on: a replayed
- *                             step is auto-approved, and a directly executed one
- *                             never reaches the permission system at all.
+ *   BIR_REPLAY=0              turn OFF calculated replay — running a scenario on
+ *                             a similar-meaning match (docs/calculatedReplay.md).
+ *                             ON by default; unset or any value other than "0"
+ *                             keeps it on. Read §13.2: a replayed step is
+ *                             auto-approved, and a directly executed one never
+ *                             reaches the permission system at all.
  *   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)
@@ -141,7 +142,7 @@ function parseIntentSources(value) {
  * part of the live task.
  */
 function buildReplayOptions(auth) {
-    const enabled = process.env.BIR_REPLAY === "1";
+    const enabled = process.env.BIR_REPLAY !== "0";
     const allowServers = parseAllowList(process.env.BIR_REPLAY_ALLOW_SERVERS);
     const minSimilarity = Number(process.env.BIR_MIN_STEER_SIMILARITY);
     const opts = {

package/dist/bin/bir.js

@@ -369,10 +369,10 @@ function install(args) {
     }
     if (args.replay) {
         out();
-        out("Calculated replay is INSTALLED but not ON. Set BIR_REPLAY=1 where you run");
-        out("`bir-hooks` to enable it — and read docs/calculatedReplayGuide.md §5.1 first:");
-        out("a replayed step is auto-approved, and a directly executed one never reaches");
-        out("the permission system at all.");
+        out("Calculated replay is INSTALLED and ON by default once `bir-hooks` runs. Set");
+        out("BIR_REPLAY=0 where you run `bir-hooks` to turn it off — and read");
+        out("docs/calculatedReplayGuide.md §5.1 first: a replayed step is auto-approved,");
+        out("and a directly executed one never reaches the permission system at all.");
     }
     return 0;
 }

package/dist/replay/controller.d.ts

@@ -35,7 +35,7 @@ export interface ReplayBudgets {
 }
 export declare const DEFAULT_BUDGETS: ReplayBudgets;
 export interface ReplayOptions {
-    /** `BIR_REPLAY=1`. Everything here is inert when false. */
+    /** On unless `BIR_REPLAY=0`. Everything here is inert when false. */
     enabled: boolean;
     /** Minimum similarity to steer — deliberately above the service's detection threshold. */
     minSimilarity: number;

package/dist/replay/controller.js

@@ -165,7 +165,7 @@ export class ReplayController {
         }
         // Gate 2 — replay enabled.
         if (!this.enabled)
-            return decline("BIR_REPLAY is not set", "replay_disabled");
+            return decline("BIR_REPLAY=0", "replay_disabled");
         // Gate 3 — a ready scenario with steps.
         const scenario = match.scenario;
         if (!match.scenarioId || !isReadyScenario(scenario)) {

package/docs/calculatedReplay.md

@@ -59,7 +59,7 @@ Continuing v1's D1–D8.
 | **D11** | Execution ownership for MCP steps | **The proxy that owns the upstream** | No second connection, no double-spawned browser, no Agent SDK dependency |
 | **D12** | Control → proxy channel | **Long-poll**, proxy dials out | No new listeners, no new ports, no new tokens (§13.3, §19.2) |
 | **D13** | Result delivery in direct mode | A **first-party MCP server** (`bir`), one tool | The model reads a genuine `tool_result`, never a `deny` reason it distrusts (§19.1) |
-| **D14** | Default state | **Off.** `BIR_REPLAY=1` plus `bir install --replay` | Replay bypasses permission prompts (§13.2); opt-in is the only defensible default |
+| **D14** | Default state | **On** once `bir install --replay` has run; `BIR_REPLAY=0` turns it off | Replay bypasses permission prompts (§13.2); the install flag is the opt-in, the env var is the kill switch |
 | **D15** | Parameter derivation | One Haiku call over raw `fetch`; **no API key ⇒ recorded sample values** | Preserves v1's zero-runtime-dependency property, and degrades to a free replay |
 | **D16** | Savings reporting | Every armed match reports to `POST /scenarios/:id/executions`, including declines | A decline is a *baseline sample*, not silence — it is what keeps the ledger honest |
 
@@ -189,7 +189,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) |
-| 2 | **Replay enabled** | `BIR_REPLAY !== "1"` | `not_steered` |
+| 2 | **Replay enabled** | `BIR_REPLAY === "0"` | `not_steered` |
 | 3 | **Scenario ready** | `scenario == null`, `state !== "ready"`, or `steps.length === 0` | `not_steered` |
 | 4 | **Similarity** | `similarity < BIR_MIN_STEER_SIMILARITY` (default **0.92**) | `not_steered` |
 | 5 | **Tool coverage** | No step is executable anywhere (§5 → `mode: "none"`) | `not_steered` |
@@ -828,7 +828,7 @@ So a scenario is, in effect, a **pre-approved list of tool calls with computed a
 precisely what makes it valuable, and precisely what makes it dangerous. Four mitigations, all
 required:
 
-1. `BIR_REPLAY` off by default; `bir install --replay` a distinct, non-default flag.
+1. `bir install --replay` a distinct, non-default flag; `BIR_REPLAY=0` a one-line kill switch once installed.
 2. `BIR_REPLAY_ALLOW_SERVERS` — a comma-separated allowlist of server keys eligible for **direct**
    execution. Unset means *all wrapped servers*; the guide (§4 of `calculatedReplayGuide.md`)
    recommends setting it.

package/docs/calculatedReplayGuide.md

@@ -206,7 +206,7 @@ That is what makes replay fast, and it is the whole risk. Two things follow:
 
 ```bash
 bir install --replay          # adds the `bir` MCP server; raises the prompt-hook timeout
-export BIR_REPLAY=1           # in the terminal that runs bir-hooks
+unset BIR_REPLAY              # on by default; only BIR_REPLAY=0 turns it off
 bir-hooks                     # restart it
 ```
 
@@ -243,7 +243,7 @@ there is exactly one switch and it cannot get out of step with itself.
 
 | Variable | Default | What it does |
 |---|---|---|
-| `BIR_REPLAY` | *(unset)* | `1` enables replay. Nothing below matters until it is set |
+| `BIR_REPLAY` | *(on)* | `0` disables replay. Unset or any other value keeps it on; nothing below matters while it is `0` |
 | `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)* | **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 |
@@ -381,7 +381,7 @@ first prompt that states the task plainly.
 | Symptom | Cause | Fix |
 |---|---|---|
 | 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: `BIR_REPLAY` unset · scenario not `ready` · similarity below threshold · no step is executable |
+| `run.matched` but no `plan.armed` | A gate declined | Read the `replay.decision` line's `why=`. Ranked by frequency: `BIR_REPLAY=0` · scenario not `ready` · similarity below threshold · no step is executable |
 | `why="no step is executable"` | None of the scenario's tools is a wrapped MCP server and none is a built-in reachable in this session | Wrap the servers the scenario uses (`bir install --server …`) and recalculate |
 | `plan.armed mode=steer` where you expected `direct` | At least one step is a built-in, an unwrapped MCP server, or `claude-in-chrome` | `bir status` shows what is wrapped. `claude-in-chrome` is `scope: "dynamic"` and can never be wrapped |
 | Model ignores the directive and diverges every turn | Steering is advisory — the model chooses; `bir` only pins arguments | Expected occasionally. Persistent divergence usually means the scenario's tools do not fit the live task; check `intent` |
@@ -439,10 +439,10 @@ Three things the implementation settled that the design left open:
 Three levels, least to most.
 
 ```bash
-unset BIR_REPLAY        # stop arming. Matches still detected; recording still stops on a match
+export BIR_REPLAY=0     # stop arming. Matches still detected; recording still stops on a match
 bir uninstall --replay  # remove the `bir` MCP server, restore the prompt-hook timeout
 bir uninstall           # remove everything: proxies, hooks, files restored byte-for-byte
 ```
 
-With `BIR_REPLAY` unset the system is exactly v1 again: it recognises a repeated prompt, declines to
+With `BIR_REPLAY=0` the system is exactly v1 again: it recognises a repeated prompt, declines to
 record it a second time, and lets the model do the work.

package/docs/my-first-sample.md

@@ -357,7 +357,7 @@ Leave this running in its own terminal, **in the run folder**:
 
 ```bash
 export BIR_AUTH_URL=https://api.your-domain.com
-export BIR_REPLAY=1                       # the replay switch — off by default
+unset BIR_REPLAY                          # replay is on by default; BIR_REPLAY=0 turns it off
 export BIR_REPLAY_ALLOW_SERVERS=postgres  # servers allowed to run unattended
 bir-hooks 2>&1 | tee -a bir-hooks.log
 ```
@@ -539,7 +539,7 @@ real work for zero tokens, and the saving is real and positive.**
 - **[quickstart.md](quickstart.md)** — setting up a fresh machine to record from
   your *own* work, not just this benchmark.
 
-> **Turning replay off** is one line: `unset BIR_REPLAY`. The system is then
+> **Turning replay off** is one line: `export BIR_REPLAY=0`. The system is then
 > exactly a recorder again — it recognises a repeated prompt and declines to
 > record it twice, and the model does the work. Nothing is skipped, nothing is
 > risked.

package/package.json

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