@basein/runner 0.2.5 → 0.2.7

package/dist/replay/controller.js

@@ -146,6 +146,7 @@ export class ReplayController {
             state.declined = code;
             logLine("replay.decision", {
                 verdict: "no-steer",
+                code,
                 run: match.runId,
                 scenario: match.scenarioId ?? undefined,
                 similarity: match.similarity.toFixed(3),
@@ -165,7 +166,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)) {
@@ -726,6 +727,7 @@ export class ReplayController {
         const blame = this.blameStep(steps);
         return {
             scenarioId: state.scenarioId,
+            runId: d.runId,
             ticket: state.ticket,
             outcome: state.outcome,
             deriveCostUsd: state.deriveCostUsd,

package/dist/util/journal.d.ts

@@ -0,0 +1,38 @@
+/**
+ * journal — the audit lines that explain a turn, kept on disk for
+ * `bir investigate` (docs/calculatedReplayGuide.md §9.1).
+ *
+ * `logLine` prints to stderr and is gone when the terminal scrolls. The
+ * questions people ask afterwards — why did this prompt not run its scenario,
+ * which gate declined, what mode did the plan arm in, what did the execution
+ * report — are answered by exactly those lines. So `bir-hooks` opens a journal
+ * for its directory and every audit line whose event is in {@link isJournaled}
+ * lands in it too, as one JSON object per line with the same fields.
+ *
+ * One file per directory, keyed like the discovery file, so two projects on
+ * one machine never mix. Rotated at {@link JOURNAL_MAX_BYTES} by keeping the
+ * newest half. Written best-effort and synchronously: a full disk must never be
+ * the reason a hook fails (design §1, rule 4), and a hook's answer must not
+ * race the line that explains it.
+ */
+export interface JournalEntry {
+    /** ISO timestamp, written by the journal, not by the caller. */
+    at: string;
+    event: string;
+    [field: string]: unknown;
+}
+export declare function isJournaled(event: string): boolean;
+export declare const JOURNAL_MAX_BYTES: number;
+export declare function journalPath(cwd: string): string;
+/** Start journaling this directory's audit lines. Returns the file, for the startup log. */
+export declare function openJournal(cwd: string): string;
+export declare function closeJournal(): void;
+/**
+ * Append one entry, if a journal is open and the event is one we keep.
+ * Called by `logLine` for every audit line, and directly for the few facts
+ * that belong in the journal but not on stderr (a prompt preview).
+ */
+export declare function journal(event: string, fields?: Record<string, unknown>): void;
+/** Every entry in a journal file, oldest first. A malformed line is skipped, not fatal. */
+export declare function readJournal(path: string): JournalEntry[];
+//# sourceMappingURL=journal.d.ts.map

package/dist/util/journal.js

@@ -0,0 +1,97 @@
+/**
+ * journal — the audit lines that explain a turn, kept on disk for
+ * `bir investigate` (docs/calculatedReplayGuide.md §9.1).
+ *
+ * `logLine` prints to stderr and is gone when the terminal scrolls. The
+ * questions people ask afterwards — why did this prompt not run its scenario,
+ * which gate declined, what mode did the plan arm in, what did the execution
+ * report — are answered by exactly those lines. So `bir-hooks` opens a journal
+ * for its directory and every audit line whose event is in {@link isJournaled}
+ * lands in it too, as one JSON object per line with the same fields.
+ *
+ * One file per directory, keyed like the discovery file, so two projects on
+ * one machine never mix. Rotated at {@link JOURNAL_MAX_BYTES} by keeping the
+ * newest half. Written best-effort and synchronously: a full disk must never be
+ * the reason a hook fails (design §1, rule 4), and a hook's answer must not
+ * race the line that explains it.
+ */
+import { appendFileSync, existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { controlDir, controlKey, ensureDir } from "../control/paths.js";
+/** Events worth keeping: the run boundaries, every replay decision, the money. */
+const JOURNALED_PREFIXES = ["run.", "replay.", "plan.", "execution."];
+const JOURNALED_EVENTS = new Set(["session.start", "control.listening", "proxy.registered"]);
+export function isJournaled(event) {
+    return JOURNALED_EVENTS.has(event) || JOURNALED_PREFIXES.some((p) => event.startsWith(p));
+}
+export const JOURNAL_MAX_BYTES = 4 * 1024 * 1024;
+export function journalPath(cwd) {
+    return join(controlDir(), "journal", `${controlKey(cwd)}.jsonl`);
+}
+let current;
+/** Start journaling this directory's audit lines. Returns the file, for the startup log. */
+export function openJournal(cwd) {
+    const path = journalPath(cwd);
+    ensureDir(dirname(path));
+    current = path;
+    return path;
+}
+export function closeJournal() {
+    current = undefined;
+}
+/**
+ * Append one entry, if a journal is open and the event is one we keep.
+ * Called by `logLine` for every audit line, and directly for the few facts
+ * that belong in the journal but not on stderr (a prompt preview).
+ */
+export function journal(event, fields = {}) {
+    if (!current || !isJournaled(event))
+        return;
+    const entry = { at: new Date().toISOString(), event };
+    for (const [key, value] of Object.entries(fields)) {
+        if (value === undefined || value === null)
+            continue;
+        entry[key] = value;
+    }
+    try {
+        appendFileSync(current, `${JSON.stringify(entry)}\n`);
+        rotate(current);
+    }
+    catch {
+        /* best effort — never the reason a hook fails */
+    }
+}
+function rotate(path) {
+    let size = 0;
+    try {
+        size = statSync(path).size;
+    }
+    catch {
+        return;
+    }
+    if (size <= JOURNAL_MAX_BYTES)
+        return;
+    const lines = readFileSync(path, "utf8").split("\n").filter(Boolean);
+    const keep = lines.slice(Math.floor(lines.length / 2));
+    writeFileSync(path, keep.length ? `${keep.join("\n")}\n` : "");
+}
+/** Every entry in a journal file, oldest first. A malformed line is skipped, not fatal. */
+export function readJournal(path) {
+    if (!existsSync(path))
+        return [];
+    const out = [];
+    for (const line of readFileSync(path, "utf8").split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed.event === "string" && typeof parsed.at === "string")
+                out.push(parsed);
+        }
+        catch {
+            /* a torn last line from a crash, or a hand edit — ignore it */
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=journal.js.map

package/dist/util/log.js

@@ -18,8 +18,12 @@ export const VERBOSE = process.env.BIR_VERBOSE === "1";
  * session: the audit log is the only record of what the recorder decided.
  */
 export const QUIET = process.env.BIR_QUIET === "1";
+import { journal } from "./journal.js";
 /** Print one audit line: `[bir] <iso ts> <event> key=value …`. */
 export function logLine(event, fields = {}) {
+    // The journal keeps the decision lines for `bir investigate` (journal.ts).
+    // Before the QUIET check on purpose: silence is for the terminal, not the record.
+    journal(event, fields);
     if (QUIET)
         return;
     const pairs = [];

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` |
@@ -395,6 +395,38 @@ first prompt that states the task plainly.
 
 ---
 
+### 9.1 `bir investigate` — the table above, applied for you
+
+Every audit line that explains a turn is also kept in a **journal**, one JSON
+object per line, under `~/.baseinstrunner/control/journal/` (one file per
+directory, rotated at 4 MB). `bir-hooks` prints its path at start. Ask the
+journal and the service together:
+
+```
+bir investigate                       # the newest turn in this directory
+bir investigate <run_|scn_|sexec_ id> # that run, scenario or execution
+bir investigate list [--limit n]      # recent turns and their verdicts
+bir investigate executions [--limit n] [--user <email|id>]   # the ledger
+```
+
+The output is the turn as the journal tells it (matched what, which gate
+declined and why, what mode armed with which coverage, what the execution
+reported), then **runner findings**, then the service's view (the recording,
+the scenario, the baseline and its sample count, the executions with their
+saved $ and %) and **service findings**. Every finding is *problem → cause →
+fix*. The three questions it answers:
+
+| Question | Where the answer comes from |
+|---|---|
+| Why did this turn not run its calculated scenario? | `replay.decision code=…` in the journal, mapped to the cause and the fix; and the service: is the run a recording, is it embedded, how many hits, is the scenario ready / failed / switched off, which step is parked |
+| Why did it save so little, or cost more? | the execution's cost breakdown (derive, session, fallback) against the baseline; steer mode with built-in steps is the usual answer, a single-sample baseline the second |
+| What happened, step by step? | the turn's lines in order, the per-step verdicts on the execution, and `replay.*_failed`, `replay.diverge`, `replay.handover` as incidents |
+
+You see your own data. An admin of the service sees everyone's and may pass
+`--user` to `executions`. `--json` on any form prints the raw merge.
+
+---
+
 ## 10. What is built
 
 All of it. Phases R0–R7 of [calculatedReplay.md](calculatedReplay.md) §17 are implemented and
@@ -439,10 +471,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.7",
   "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",