@basein/runner 0.2.6 → 0.2.7

package/dist/bin/bir-hooks.js

@@ -71,6 +71,7 @@ import { readSidecar } from "../config/generate.js";
 import { resolveServers } from "../config/resolve.js";
 import { isWrapped } from "../config/generate.js";
 import { logLine, errText } from "../util/log.js";
+import { openJournal } from "../util/journal.js";
 function parsePort(value) {
     const n = Number(value);
     return Number.isInteger(n) && n > 0 && n < 65536 ? n : DEFAULT_CONTROL_PORT;
@@ -207,6 +208,9 @@ async function main() {
     }
     const cwd = process.cwd();
     const sidecar = readSidecar();
+    // Open before anything logs: the journal is what `bir investigate` reads
+    // later, and the startup lines are part of the story.
+    const journalFile = openJournal(cwd);
     const auth = await buildRecorder();
     const server = new ControlServer({
         recorder: auth.recorder,
@@ -234,6 +238,7 @@ async function main() {
         url: address.url,
         cwd,
         discovery: discoveryFile,
+        journal: journalFile,
         machine: hostname(),
         wrapped: wrappedServersFor(cwd).join(",") || "(none)",
     });

package/dist/bin/bir.js

@@ -31,6 +31,9 @@ import { readGenericServers, setGenericServerEntry } from "../config/adapters/ge
 import { AUTH_URL_HINT, DeviceFlowAborted, DeviceFlowUnsupported, authenticate, deviceLogin, describeAuthService, legacyPasswordLogin, tokenLogin, logout, normalizeAuthUrl, resolveAuthUrl, } from "../auth/client.js";
 import { DEFAULT_CONTROL_PORT } from "../control/server.js";
 import { errText } from "../util/log.js";
+import { journalPath, readJournal } from "../util/journal.js";
+import { investigateCommand } from "./investigate.js";
+import { loadCredentials } from "../auth/client.js";
 import { packageVersion } from "../util/version.js";
 const VERSION = packageVersion();
 const out = (line = "") => {
@@ -54,6 +57,12 @@ Commands:
   scenario replay <scnId> --prompt "…" [--dry]
   replay --scenario <scnId> --prompt "…" [--dry]
 
+  investigate [<id>]                why the newest turn here (or run_/scn_/sexec_ <id>) did what
+                                    it did, what it cost, what to fix — journal + service
+  investigate list [--limit <n>]    recent turns in this directory and their verdicts
+  investigate executions [--limit <n>] [--user <email|id>]
+                                    the ledger, newest first (--user: admins only)
+
 Options:
   --config <path>   an explicit { "mcpServers": … } file, for clients with no adapter
   --server <name>   restrict install/uninstall to one server (repeatable)
@@ -68,7 +77,9 @@ Options:
   --dry             replay against recorded outputs only; run no real tools
   --no-browser      login: print the link and code, open nothing (SSH, headless)
   --token <value>   login: redeem a one-time setup token from the console (no browser)
-  --password        login: use the old email/password prompt (deprecated)`);
+  --password        login: use the old email/password prompt (deprecated)
+  --user <ref>      investigate executions: another account, by email or id (admin)
+  --limit <n>       investigate: how many turns / executions to show`);
     process.exit(code);
 }
 function parseArgs(argv) {
@@ -146,6 +157,18 @@ function parseArgs(argv) {
             case "--json":
                 args.json = true;
                 break;
+            case "--user":
+                args.user = argv[++i];
+                if (!args.user)
+                    usage(2);
+                break;
+            case "--limit": {
+                const n = Number(argv[++i]);
+                if (!Number.isInteger(n) || n <= 0)
+                    usage(2);
+                args.limit = n;
+                break;
+            }
             default:
                 if (arg.startsWith("-"))
                     usage(2);
@@ -933,6 +956,22 @@ async function main() {
             return scenarioCommand(args);
         case "replay":
             return replayCommand(args);
+        case "investigate":
+            return investigateCommand({ positionals: args.positionals, json: args.json, user: args.user, limit: args.limit }, {
+                cwd: process.cwd(),
+                out,
+                journal: (cwd) => readJournal(journalPath(cwd)),
+                journalPath,
+                viewerEmail: loadCredentials()?.user?.email,
+                service: async (path) => {
+                    try {
+                        return await service("GET", path);
+                    }
+                    catch (err) {
+                        return { error: errText(err) };
+                    }
+                },
+            });
         case "login": {
             // Settle the URL the way every other command does, then refuse to go on
             // when what is there is not the service. "Signed in" must mean the service

package/dist/bin/investigate.d.ts

@@ -0,0 +1,195 @@
+/**
+ * `bir investigate` — why did this turn do what it did, and what did it cost?
+ * (docs/calculatedReplayGuide.md §9.1)
+ *
+ * Two sources, merged:
+ *
+ *   1. The **journal** this directory's `bir-hooks` keeps (util/journal.ts):
+ *      the run boundaries, the match, every gate decision, the plan's mode and
+ *      coverage, the replay outcome and the execution report. This is the only
+ *      record of a *matched* turn, because the service deliberately keeps no
+ *      run for one.
+ *   2. The **service**'s `GET /investigate/:id`: the recording, its scenario,
+ *      the baseline, the execution ledger and the service's own findings.
+ *      Owner-only; an admin may look at anyone's.
+ *
+ * Each side diagnoses what only it can see. The journal knows which gate
+ * declined and what mode armed; the service knows the baseline, the ledger and
+ * whether a run ever became a recording. Both lists are printed, worst first.
+ */
+import type { JournalEntry } from "../util/journal.js";
+export interface Turn {
+    runId: string;
+    sessionId?: string;
+    startedAt: string;
+    finishedAt?: string;
+    prompt?: string;
+    matched?: {
+        runId: string;
+        scenarioId?: string;
+        similarity?: number;
+    };
+    decision?: {
+        verdict: string;
+        code?: string;
+        why?: string;
+        threshold?: number;
+    };
+    plan?: {
+        mode: string;
+        steps?: number;
+        coverage?: string[];
+        tools?: string[];
+        scenarioId?: string;
+        by?: string;
+    };
+    derived?: {
+        params?: number;
+        costUsd?: number;
+        source?: string;
+    };
+    done?: {
+        outcome: string;
+        steps?: string;
+        ms?: number;
+    };
+    reported?: {
+        outcome: string;
+        derive: number;
+        session: number;
+        fallback: number;
+        savedUsd?: number;
+        measured?: boolean;
+        ticket?: string;
+        scenarioId?: string;
+        declined?: string;
+    };
+    finish?: {
+        steps?: number;
+        durationMs?: number;
+        costUsd?: number;
+        measured?: boolean;
+        recorded?: boolean;
+    };
+    /** `replay.*_failed`, `replay.arm_failed`, `replay.diverge`, `replay.handover` … */
+    incidents: JournalEntry[];
+    events: JournalEntry[];
+}
+/**
+ * Group journal entries into turns. A turn opens at `run.start` and closes at
+ * `run.finish`; an entry joins the turn whose local run id it names, else the
+ * turn whose *matched* run id it names (the replay lines log the service's run),
+ * else the latest turn — which is where an older build's `execution.reported`,
+ * arriving after `run.finish` with no run id, belongs.
+ */
+export declare function turnsFromJournal(entries: readonly JournalEntry[]): Turn[];
+/** The turn an id names: its own run, the run it matched, its scenario or its ticket. */
+export declare function findTurn(turns: readonly Turn[], id: string): Turn | undefined;
+export interface Finding {
+    code: string;
+    severity: "problem" | "warn" | "info";
+    title: string;
+    cause: string;
+    fix: string;
+    evidence?: Record<string, unknown>;
+}
+/** The runner's own gate vocabulary, with the cause and the fix (guide §9). */
+export declare const DECLINES: Record<string, {
+    cause: string;
+    fix: string;
+}>;
+export declare const LOW_SAVING_PCT = 0.3;
+export declare function localFindings(turn: Turn): Finding[];
+/** `saved ÷ (saved + cost)`: the baseline is recoverable from the report alone. */
+export declare function savedPct(turn: Turn): number | null;
+export type ServiceReply = {
+    status: number;
+    body: unknown;
+} | {
+    error: string;
+};
+export interface InvestigateDeps {
+    cwd: string;
+    out: (line?: string) => void;
+    service: (path: string) => Promise<ServiceReply>;
+    journal: (cwd: string) => JournalEntry[];
+    journalPath: (cwd: string) => string;
+    /** The signed-in account, so "owner you" can be told from "owner <email>". */
+    viewerEmail?: string;
+}
+export interface InvestigateArgs {
+    positionals: string[];
+    json: boolean;
+    user?: string;
+    limit?: number;
+}
+interface ServiceInvestigation {
+    subject?: {
+        kind: string;
+        id: string;
+    };
+    owner?: {
+        id: string;
+        email: string | null;
+    };
+    run?: {
+        id: string;
+        input: string;
+        title: string | null;
+        finishedAt: string | null;
+        actionCount: number;
+        tools: string[];
+        originalCostUsd: number | null;
+        iterations: number;
+        isRecording: boolean;
+        embedded: boolean;
+        duplicateOf: string | null;
+    } | null;
+    scenario?: {
+        id: string;
+        state: string;
+        steps: Array<{
+            stepIndex: number;
+            toolName: string | null;
+            failureCount: number;
+        }>;
+        baseline: {
+            costUsd: number | null;
+            samples: number;
+            method: string | null;
+        };
+        lastDecline: {
+            reason: string;
+            at: string | null;
+        } | null;
+        hitCount: number | null;
+        disabledAt: string | null;
+        error: string | null;
+    } | null;
+    executions?: Array<{
+        id: string;
+        createdAt: string;
+        outcome: string;
+        costUsd: number;
+        deriveCostUsd: number | null;
+        sessionCostUsd: number | null;
+        fallbackCostUsd: number | null;
+        baselineCostUsd: number | null;
+        savedUsd: number | null;
+        savedPct: number | null;
+        measured: boolean;
+        durationMs: number | null;
+        steps: Array<{
+            stepIndex: number;
+            toolName?: string;
+            status: string;
+            error?: string;
+        }> | null;
+    }>;
+    findings?: Finding[];
+}
+export declare function renderTurn(out: (l?: string) => void, turn: Turn): void;
+export declare function renderService(out: (l?: string) => void, s: ServiceInvestigation, viewerIsOwner: boolean): void;
+export declare function investigateCommand(args: InvestigateArgs, deps: InvestigateDeps): Promise<number>;
+export {};
+//# sourceMappingURL=investigate.d.ts.map

package/dist/bin/investigate.js

@@ -0,0 +1,576 @@
+/**
+ * `bir investigate` — why did this turn do what it did, and what did it cost?
+ * (docs/calculatedReplayGuide.md §9.1)
+ *
+ * Two sources, merged:
+ *
+ *   1. The **journal** this directory's `bir-hooks` keeps (util/journal.ts):
+ *      the run boundaries, the match, every gate decision, the plan's mode and
+ *      coverage, the replay outcome and the execution report. This is the only
+ *      record of a *matched* turn, because the service deliberately keeps no
+ *      run for one.
+ *   2. The **service**'s `GET /investigate/:id`: the recording, its scenario,
+ *      the baseline, the execution ledger and the service's own findings.
+ *      Owner-only; an admin may look at anyone's.
+ *
+ * Each side diagnoses what only it can see. The journal knows which gate
+ * declined and what mode armed; the service knows the baseline, the ledger and
+ * whether a run ever became a recording. Both lists are printed, worst first.
+ */
+const num = (v) => {
+    if (v === undefined || v === null || v === "")
+        return undefined;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : undefined;
+};
+const str = (v) => (v === undefined || v === null ? undefined : String(v));
+const bool = (v) => v === true || v === "true" ? true : v === false || v === "false" ? false : undefined;
+const list = (v) => {
+    const s = str(v);
+    return s ? s.split(",").filter(Boolean) : undefined;
+};
+const INCIDENTS = new Set([
+    "replay.arm_failed",
+    "replay.derive_failed",
+    "replay.compose_failed",
+    "replay.flatten_failed",
+    "replay.thread_failed",
+    "replay.step_failed",
+    "replay.failed",
+    "replay.diverge",
+    "replay.handover",
+    "replay.thread_fallback",
+    "run.lossy",
+    "run.unmeasured",
+    "run.prompt_late",
+]);
+/**
+ * Group journal entries into turns. A turn opens at `run.start` and closes at
+ * `run.finish`; an entry joins the turn whose local run id it names, else the
+ * turn whose *matched* run id it names (the replay lines log the service's run),
+ * else the latest turn — which is where an older build's `execution.reported`,
+ * arriving after `run.finish` with no run id, belongs.
+ */
+export function turnsFromJournal(entries) {
+    const turns = [];
+    const owner = (e) => {
+        const run = str(e.run);
+        // The newest turn that is, or matched, this run. Newest wins: once a
+        // recording has been matched, `plan.armed run=<its id>` is about the
+        // matching turn, not about the recording's own (long finished) turn.
+        if (run) {
+            for (let i = turns.length - 1; i >= 0; i -= 1) {
+                if (turns[i].runId === run || turns[i].matched?.runId === run)
+                    return turns[i];
+            }
+        }
+        if (e.event === "execution.reported") {
+            for (let i = turns.length - 1; i >= 0; i -= 1) {
+                if (turns[i].plan && !turns[i].reported)
+                    return turns[i];
+            }
+        }
+        return turns[turns.length - 1];
+    };
+    for (const e of entries) {
+        if (e.event === "run.start") {
+            const runId = str(e.run) ?? `unknown-${turns.length}`;
+            const turn = { runId, sessionId: str(e.sess), startedAt: e.at, incidents: [], events: [e] };
+            turns.push(turn);
+            continue;
+        }
+        const turn = owner(e);
+        if (!turn)
+            continue;
+        turn.events.push(e);
+        switch (e.event) {
+            case "run.prompt":
+                turn.prompt = str(e.prompt);
+                break;
+            case "run.matched":
+                turn.matched = { runId: str(e.matchedRun) ?? "", scenarioId: str(e.scenario), similarity: num(e.similarity) };
+                break;
+            case "replay.decision":
+                turn.decision = {
+                    verdict: str(e.verdict) ?? "",
+                    code: str(e.code),
+                    why: str(e.why),
+                    threshold: num(e.threshold),
+                };
+                break;
+            case "plan.armed":
+                turn.plan = {
+                    mode: str(e.mode) ?? "",
+                    steps: num(e.steps),
+                    coverage: list(e.coverage),
+                    tools: list(e.tools),
+                    scenarioId: str(e.scenario),
+                    by: str(e.by),
+                };
+                break;
+            case "replay.derived":
+                turn.derived = { params: num(e.params), costUsd: num(e.costUsd), source: str(e.source) };
+                break;
+            case "replay.done":
+                turn.done = { outcome: str(e.outcome) ?? "", steps: str(e.steps), ms: num(e.ms) };
+                break;
+            case "execution.reported":
+                turn.reported = {
+                    outcome: str(e.outcome) ?? "",
+                    derive: num(e.derive) ?? 0,
+                    session: num(e.session) ?? 0,
+                    fallback: num(e.fallback) ?? 0,
+                    savedUsd: num(e.savedUsd),
+                    measured: bool(e.measured),
+                    ticket: str(e.ticket),
+                    scenarioId: str(e.scenario),
+                    declined: str(e.declined),
+                };
+                break;
+            case "run.finish":
+                turn.finishedAt = e.at;
+                turn.finish = {
+                    steps: num(e.steps),
+                    durationMs: num(e.durationMs),
+                    costUsd: num(e.costUsd),
+                    measured: bool(e.measured),
+                    recorded: bool(e.recorded),
+                };
+                break;
+            default:
+                if (INCIDENTS.has(e.event))
+                    turn.incidents.push(e);
+        }
+    }
+    return turns;
+}
+/** The turn an id names: its own run, the run it matched, its scenario or its ticket. */
+export function findTurn(turns, id) {
+    for (let i = turns.length - 1; i >= 0; i -= 1) {
+        const t = turns[i];
+        if (t.runId === id ||
+            t.matched?.runId === id ||
+            t.matched?.scenarioId === id ||
+            t.plan?.scenarioId === id ||
+            t.reported?.scenarioId === id ||
+            t.reported?.ticket === id) {
+            return t;
+        }
+    }
+    return undefined;
+}
+/** The runner's own gate vocabulary, with the cause and the fix (guide §9). */
+export const DECLINES = {
+    replay_disabled: {
+        cause: "calculated replay was off in this bir-hooks (BIR_REPLAY=0), or a sub-task was handed out with BIR_SEGMENT_ARM off.",
+        fix: "start bir-hooks with BIR_REPLAY=1 (the default); for sub-tasks set BIR_SEGMENT_ARM=1.",
+    },
+    not_ready: {
+        cause: "the matched recording had no ready scenario at that moment.",
+        fix: "wait for the calculation, or start one with `bir scenario calc <runId>`, then run the prompt again.",
+    },
+    similarity: {
+        cause: "the prompt was a hit on the recording but below the steering threshold (BIR_REPLAY_MIN_SIMILARITY, default 0.92).",
+        fix: "phrase the prompt closer to the recorded one, or lower BIR_REPLAY_MIN_SIMILARITY.",
+    },
+    coverage: {
+        cause: "no step of the scenario could run anywhere: its tools are neither wrapped MCP servers registered in this session nor built-ins.",
+        fix: "wrap the servers the scenario uses (`bir install --server <name>`) and start a fresh session; `bir doctor` lists what is registered.",
+    },
+    known_bad_first_step: {
+        cause: "the chain's first step is parked after repeated failures.",
+        fix: "recalculate the scenario (`bir scenario calc <runId> --force`).",
+    },
+    unusable_first_step: {
+        cause: "the first step calls a sub-task that is gone, switched off or stale.",
+        fix: "enable or recalculate that sub-task, or recalculate this scenario.",
+    },
+    missing_target: {
+        cause: "the prompt names a target the runner could not find where the recording had it.",
+        fix: "run from the recording's directory, or name the target as the recording did.",
+    },
+    no_derive_key: {
+        cause: "the scenario has parameters and the runner had no way to derive them: no service session and no ANTHROPIC_API_KEY.",
+        fix: "set BIR_AUTH_URL and `bir login` in the terminal that starts bir-hooks, or export ANTHROPIC_API_KEY there.",
+    },
+    flatten_failed: {
+        cause: "the chain could not be flattened — a sub-task it calls no longer resolves.",
+        fix: "recalculate the scenario.",
+    },
+};
+export const LOW_SAVING_PCT = 0.3;
+const usd = (v) => `$${v.toFixed(4)}`;
+const pct = (v) => `${(v * 100).toFixed(1)}%`;
+export function localFindings(turn) {
+    const out = [];
+    if (!turn.matched) {
+        out.push({
+            code: "no_match",
+            severity: "info",
+            title: "This turn matched no recording, so the agent did the task itself.",
+            cause: "The service found no recording whose prompt is similar enough (its SIMILARITY_THRESHOLD). A run that is below the recording threshold is never embedded and can never be matched.",
+            fix: "If a recording of this task exists, run the prompt closer to its wording. The service section below says whether this turn became a recording.",
+        });
+    }
+    else if (turn.decision?.verdict === "no-steer") {
+        const code = turn.decision.code ?? "";
+        const known = DECLINES[code];
+        out.push({
+            code: `declined_${code || "unknown"}`,
+            severity: code === "not_ready" && !turn.matched.scenarioId ? "info" : "problem",
+            title: `Matched ${turn.matched.runId} but declined to steer: ${turn.decision.why ?? code}.`,
+            cause: known?.cause ?? "the runner's log line carries the reason text.",
+            fix: known?.fix ??
+                (turn.matched.scenarioId
+                    ? "read the `replay.decision` line above."
+                    : "the matched recording has no scenario yet — calculate it, or let the service pick it up after enough hits."),
+            evidence: { code, similarity: turn.matched.similarity, threshold: turn.decision.threshold },
+        });
+    }
+    else if (!turn.plan) {
+        out.push({
+            code: "not_armed",
+            severity: "warn",
+            title: `Matched ${turn.matched.runId} but no plan was armed.`,
+            cause: "The match arrived but arming failed or timed out before the prompt hook answered (`replay.arm_failed`, or the match budget).",
+            fix: "Check the incidents below and `bir doctor`; the service section says whether the scenario is ready.",
+        });
+    }
+    if (turn.plan) {
+        const coverage = turn.plan.coverage ?? [];
+        const tools = turn.plan.tools ?? [];
+        const live = coverage
+            .map((c, i) => (c === "live" ? (tools[i] ?? `step ${i}`) : undefined))
+            .filter((t) => Boolean(t));
+        if (turn.plan.mode === "steer" && live.length > 0) {
+            const lowSaving = savedPct(turn) != null && savedPct(turn) < LOW_SAVING_PCT;
+            out.push({
+                code: "steer_mode",
+                severity: lowSaving ? "warn" : "info",
+                title: `The plan armed in steer mode: ${live.length} of ${coverage.length} steps are reachable only inside the session (${[...new Set(live)].join(", ")}).`,
+                cause: "In steer mode the runner pins each call's inputs and auto-approves it, but the model still emits every tool call, reads every result and writes the answer — so the whole live turn is still paid for. Direct mode, where the model makes no tool call, needs every step to be a wrapped MCP server tool.",
+                fix: "Put the data those tools reach behind an MCP server, wrap it (`bir install --server <name>`), and record the prompt again so its steps are MCP calls.",
+                evidence: { coverage, tools },
+            });
+        }
+        if (turn.plan.mode === "direct") {
+            out.push({
+                code: "direct_mode",
+                severity: "info",
+                title: `The plan armed in direct mode: ${turn.plan.steps ?? coverage.length} steps ran on the proxies, no model in the loop.`,
+                cause: "Every step is a wrapped MCP tool this session has a proxy for.",
+                fix: "",
+            });
+        }
+    }
+    for (const i of turn.incidents) {
+        const fields = Object.fromEntries(Object.entries(i).filter(([k]) => k !== "at" && k !== "event"));
+        out.push({
+            code: i.event.replace(/\./g, "_"),
+            severity: i.event.endsWith("_failed") || i.event === "replay.failed" ? "problem" : "warn",
+            title: `${i.event}${i.error ? `: ${String(i.error)}` : ""}`,
+            cause: Object.entries(fields)
+                .map(([k, v]) => `${k}=${String(v)}`)
+                .join("  "),
+            fix: i.event === "run.unmeasured"
+                ? "the turn's cost could not be read from the transcript, so its report is unmeasured; run bir-hooks where the Claude Code transcript is readable."
+                : i.event === "replay.diverge" || i.event === "replay.handover"
+                    ? "the model left the script or the runner handed the turn back; the service section shows what the fallback cost."
+                    : "see the guide's troubleshooting table for this line.",
+        });
+    }
+    const r = turn.reported;
+    if (r) {
+        if (r.measured === false) {
+            out.push({
+                code: "unmeasured",
+                severity: "warn",
+                title: "The execution report is unmeasured: the session's tokens could not be read.",
+                cause: "Without the transcript delta the report carries the derivation cost alone, and `baseline − cost` overstates the saving.",
+                fix: "Run bir-hooks on the machine and user that own the Claude Code transcript; `run.unmeasured` names what was missing.",
+            });
+        }
+        const p = savedPct(turn);
+        const cost = r.derive + r.session + r.fallback;
+        if (r.savedUsd != null && r.savedUsd < 0) {
+            out.push({
+                code: "saving_negative",
+                severity: "problem",
+                title: `This replay cost more than the agent: ${usd(cost)} against a baseline of ${usd(r.savedUsd + cost)}.`,
+                cause: `derive ${usd(r.derive)}, session ${usd(r.session)}, fallback ${usd(r.fallback)}.`,
+                fix: "The service findings below name the dominant cost and the fix.",
+                evidence: { ...r, costUsd: cost },
+            });
+        }
+        else if (p != null && p < LOW_SAVING_PCT && r.outcome === "steered_full") {
+            out.push({
+                code: "saving_low",
+                severity: "warn",
+                title: `Saved ${pct(p)}: ${usd(r.savedUsd ?? 0)} of a ${usd((r.savedUsd ?? 0) + cost)} baseline.`,
+                cause: `The live session cost ${usd(r.session)} of that baseline${turn.plan?.mode === "steer" ? " — steer mode pays for the whole turn." : "."}`,
+                fix: turn.plan?.mode === "steer"
+                    ? "Direct mode is the fix: wrap the servers so every step is an MCP call (see steer_mode)."
+                    : "Compare the baseline with a few unsteered runs (BIR_REPLAY=0); a single cheap source run makes any replay look poor.",
+                evidence: { ...r, costUsd: cost, savedPct: p },
+            });
+        }
+    }
+    else if (turn.plan && turn.finishedAt) {
+        out.push({
+            code: "not_reported",
+            severity: "warn",
+            title: "A plan armed but no execution report was sent.",
+            cause: "The turn ended without `execution.reported`: the report failed to send, or the ticket was missing (an older service).",
+            fix: "Look for `recorder.send_failed` in the bir-hooks log; the saving of this turn is not on the ledger.",
+        });
+    }
+    const rank = { problem: 0, warn: 1, info: 2 };
+    return out
+        .map((f, i) => ({ f, i }))
+        .sort((a, b) => rank[a.f.severity] - rank[b.f.severity] || a.i - b.i)
+        .map(({ f }) => f);
+}
+/** `saved ÷ (saved + cost)`: the baseline is recoverable from the report alone. */
+export function savedPct(turn) {
+    const r = turn.reported;
+    if (!r || r.savedUsd == null)
+        return null;
+    const baseline = r.savedUsd + r.derive + r.session + r.fallback;
+    return baseline > 0 ? r.savedUsd / baseline : null;
+}
+const short = (id) => (id ? id.slice(0, 13) : "—");
+const money = (v) => (v == null ? "—" : usd(v));
+const when = (iso) => (iso ? iso.replace("T", " ").replace(/\.\d+Z$/, "Z") : "—");
+function renderFindings(out, findings, heading) {
+    if (findings.length === 0)
+        return;
+    out();
+    out(heading);
+    findings.forEach((f, i) => {
+        out(`  ${i + 1}. [${f.severity}] ${f.title}`);
+        if (f.cause)
+            out(`     why:  ${f.cause}`);
+        if (f.fix)
+            out(`     fix:  ${f.fix}`);
+    });
+}
+export function renderTurn(out, turn) {
+    out(`Turn ${turn.runId}  ${when(turn.startedAt)}${turn.sessionId ? `  session ${turn.sessionId.slice(0, 8)}` : ""}`);
+    if (turn.prompt)
+        out(`  prompt    ${turn.prompt.replace(/\s+/g, " ").slice(0, 110)}`);
+    if (turn.matched) {
+        out(`  matched   ${turn.matched.runId}${turn.matched.similarity != null ? ` (similarity ${turn.matched.similarity.toFixed(3)})` : ""}${turn.matched.scenarioId ? ` → scenario ${turn.matched.scenarioId}` : " → no scenario"}`);
+    }
+    else {
+        out("  matched   no recording — the agent ran the task; this turn was recorded");
+    }
+    if (turn.decision?.verdict === "no-steer") {
+        out(`  decision  declined${turn.decision.code ? ` (${turn.decision.code})` : ""}: ${turn.decision.why ?? ""}`);
+    }
+    if (turn.plan) {
+        const cov = turn.plan.coverage?.map((c, i) => `${turn.plan?.tools?.[i] ?? "?"}:${c}`).join(" ");
+        out(`  plan      ${turn.plan.mode}${turn.plan.by ? ` (by ${turn.plan.by})` : ""}, ${turn.plan.steps ?? "?"} steps${cov ? `  ${cov}` : ""}`);
+    }
+    if (turn.derived) {
+        out(`  derived   ${turn.derived.params ?? "?"} params by ${turn.derived.source ?? "?"}  ${money(turn.derived.costUsd)}`);
+    }
+    if (turn.done) {
+        out(`  replay    ${turn.done.outcome}${turn.done.steps ? ` ${turn.done.steps} steps` : ""}${turn.done.ms != null ? ` in ${(turn.done.ms / 1000).toFixed(1)} s` : ""}`);
+    }
+    if (turn.reported) {
+        const r = turn.reported;
+        const p = savedPct(turn);
+        const cost = r.derive + r.session + r.fallback;
+        out(`  reported  ${r.outcome}${r.declined ? ` (${r.declined})` : ""}  derive ${usd(r.derive)}  session ${usd(r.session)}  fallback ${usd(r.fallback)}` +
+            (r.savedUsd != null
+                ? `  → saved ${usd(r.savedUsd)}${p != null ? ` (${pct(p)} of ${usd(r.savedUsd + cost)})` : ""}`
+                : "") +
+            (r.measured === false ? "  UNMEASURED" : ""));
+    }
+    if (turn.finish) {
+        const f = turn.finish;
+        out(`  finished  ${f.steps ?? "?"} steps, ${f.durationMs != null ? `${(f.durationMs / 1000).toFixed(1)} s` : "?"}${f.costUsd != null ? `, cost ${usd(f.costUsd)}` : f.measured === false ? ", cost unmeasured" : ""}, ${f.recorded ? "recorded" : "not recorded"}`);
+    }
+    else {
+        out("  finished  (not yet — the turn is still open, or the session ended without its Stop hook)");
+    }
+}
+export function renderService(out, s, viewerIsOwner) {
+    out();
+    out(`From the service${s.subject ? ` (${s.subject.kind} ${s.subject.id})` : ""}${s.owner ? `, owner ${viewerIsOwner ? "you" : (s.owner.email ?? s.owner.id)}` : ""}:`);
+    if (s.run) {
+        const r = s.run;
+        out(`  recording ${r.id}  ${r.isRecording ? "listed" : "below threshold"}${r.embedded ? ", embedded" : ", NOT embedded"}  ${r.actionCount} tool calls (${r.tools.join(", ") || "none"})  cost ${money(r.originalCostUsd)}  hits ${r.iterations}${r.duplicateOf ? `  duplicate of ${r.duplicateOf}` : ""}`);
+        if (r.title || r.input)
+            out(`            "${(r.title ?? r.input).replace(/\s+/g, " ").slice(0, 100)}"`);
+    }
+    else {
+        out("  recording none");
+    }
+    if (s.scenario) {
+        const sc = s.scenario;
+        out(`  scenario  ${sc.id}  ${sc.state}${sc.disabledAt ? " (switched off)" : ""}  ${sc.steps.length} steps (${[...new Set(sc.steps.map((x) => x.toolName ?? "?"))].join(", ")})  baseline ${money(sc.baseline.costUsd)} from ${sc.baseline.samples} sample(s)${sc.hitCount != null ? `  hits ${sc.hitCount}` : ""}`);
+        if (sc.lastDecline)
+            out(`            last decline ${sc.lastDecline.reason} at ${when(sc.lastDecline.at ?? undefined)}`);
+        if (sc.error)
+            out(`            error ${sc.error.slice(0, 160)}`);
+    }
+    else {
+        out("  scenario  none");
+    }
+    const ex = s.executions ?? [];
+    if (ex.length > 0) {
+        out(`  executions (${ex.length}, newest first)`);
+        for (const e of ex.slice(0, 10)) {
+            out(`    ${when(e.createdAt)}  ${short(e.id)}  ${e.outcome.padEnd(13)} cost ${usd(e.costUsd)}  saved ${money(e.savedUsd)}${e.savedPct != null ? ` (${pct(e.savedPct)})` : ""}${e.measured ? "" : "  unmeasured"}`);
+            const failed = e.steps?.filter((st) => st.status === "failed") ?? [];
+            for (const st of failed)
+                out(`        step ${st.stepIndex} ${st.toolName ?? ""} failed${st.error ? `: ${st.error.slice(0, 120)}` : ""}`);
+        }
+    }
+    renderFindings(out, s.findings ?? [], "Service findings");
+}
+// ── the command ───────────────────────────────────────────────────────────────
+async function fetchInvestigation(deps, id, limit) {
+    const reply = await deps.service(`/investigate/${id}${limit ? `?limit=${limit}` : ""}`);
+    if ("error" in reply)
+        return { note: `service not consulted: ${reply.error}` };
+    if (reply.status === 404)
+        return { note: `the service has nothing for ${id} (not yours, or never reached it)` };
+    if (reply.status !== 200)
+        return { note: `service answered HTTP ${reply.status}` };
+    return { data: reply.body };
+}
+/** Which id the service should be asked about for a turn. */
+function serviceIdFor(turn) {
+    return (turn.reported?.ticket ??
+        turn.reported?.scenarioId ??
+        turn.plan?.scenarioId ??
+        turn.matched?.scenarioId ??
+        turn.matched?.runId ??
+        turn.runId);
+}
+export async function investigateCommand(args, deps) {
+    const sub = args.positionals[0];
+    const { out } = deps;
+    if (sub === "executions") {
+        const params = new URLSearchParams();
+        if (args.limit)
+            params.set("limit", String(args.limit));
+        if (args.user)
+            params.set("user", args.user);
+        const reply = await deps.service(`/investigate/executions${params.size ? `?${params}` : ""}`);
+        if ("error" in reply) {
+            out(`Could not reach the service: ${reply.error}`);
+            return 1;
+        }
+        if (reply.status === 403) {
+            out("Only an admin may look at another account's executions.");
+            return 1;
+        }
+        if (reply.status === 404) {
+            out(`No such account: ${args.user}`);
+            return 1;
+        }
+        if (reply.status !== 200) {
+            out(`Could not list executions (HTTP ${reply.status}).`);
+            return 1;
+        }
+        const body = reply.body;
+        if (args.json) {
+            out(JSON.stringify(body, null, 2));
+            return 0;
+        }
+        const rows = body.executions ?? [];
+        out(`Executions of ${body.owner?.email ?? body.owner?.id ?? "you"} (${rows.length}, newest first)`);
+        if (rows.length === 0)
+            out("  none yet");
+        for (const e of rows) {
+            out(`  ${when(e.createdAt)}  ${e.id}  ${e.outcome.padEnd(13)} cost ${usd(e.costUsd)}  saved ${money(e.savedUsd)}${e.savedPct != null ? ` (${pct(e.savedPct)})` : ""}${e.measured ? "" : "  unmeasured"}`);
+            out(`      scenario ${e.scenarioId}${e.runId ? `  run ${e.runId}` : ""}${e.intent ? `  "${e.intent.slice(0, 60)}"` : ""}`);
+        }
+        out();
+        out("Investigate one with `bir investigate <sexec_…>`.");
+        return 0;
+    }
+    const entries = deps.journal(deps.cwd);
+    const turns = turnsFromJournal(entries);
+    if (sub === "list") {
+        const limit = args.limit ?? 20;
+        const recent = turns.slice(-limit).reverse();
+        if (args.json) {
+            out(JSON.stringify(recent, null, 2));
+            return 0;
+        }
+        if (recent.length === 0) {
+            out(`No turns in the journal for this directory (${deps.journalPath(deps.cwd)}).`);
+            out("Start `bir-hooks` here and run a prompt; every turn is journaled from then on.");
+            return 0;
+        }
+        out(`Recent turns in ${deps.cwd} (newest first)`);
+        for (const t of recent) {
+            const verdict = !t.matched
+                ? "recorded"
+                : t.decision?.verdict === "no-steer"
+                    ? `declined ${t.decision.code ?? ""}`.trim()
+                    : t.plan
+                        ? `${t.plan.mode} ${t.done?.outcome ?? t.reported?.outcome ?? "armed"}`
+                        : "matched";
+            const p = savedPct(t);
+            const saved = t.reported?.savedUsd != null ? `  saved ${usd(t.reported.savedUsd)}${p != null ? ` (${pct(p)})` : ""}` : "";
+            out(`  ${when(t.startedAt)}  ${t.runId}  ${verdict}${saved}`);
+            if (t.prompt)
+                out(`      "${t.prompt.replace(/\s+/g, " ").slice(0, 90)}"`);
+        }
+        out();
+        out("Investigate one with `bir investigate <run_…>`; the newest with `bir investigate`.");
+        return 0;
+    }
+    // One subject: an id, or the newest turn.
+    const id = sub;
+    let turn;
+    if (id) {
+        turn = findTurn(turns, id);
+    }
+    else {
+        turn = turns[turns.length - 1];
+        if (!turn) {
+            out(`No turns in the journal for this directory (${deps.journalPath(deps.cwd)}).`);
+            out("Start `bir-hooks` here and run a prompt, or name an id: `bir investigate <run_|scn_|sexec_ id>`.");
+            return 1;
+        }
+    }
+    if (id && !turn && !/^(run_|scn_|sexec_)/.test(id)) {
+        out(`Not an id this command knows: ${id}. Expected run_…, scn_… or sexec_…, or a subcommand (list, executions).`);
+        return 2;
+    }
+    const findings = turn ? localFindings(turn) : [];
+    const serviceId = turn ? serviceIdFor(turn) : id;
+    const service = await fetchInvestigation(deps, serviceId, args.limit);
+    // A matched turn's own run id is unknown to the service; when the scenario
+    // lookup fails, the matched run is still worth a try.
+    const fallbackId = turn && service.note && turn.matched?.runId && serviceId !== turn.matched.runId ? turn.matched.runId : undefined;
+    const second = fallbackId ? await fetchInvestigation(deps, fallbackId, args.limit) : undefined;
+    const chosen = service.data ? service : second?.data ? second : service;
+    if (args.json) {
+        out(JSON.stringify({ turn: turn ?? null, findings, service: chosen.data ?? null, note: chosen.note ?? null }, null, 2));
+        return 0;
+    }
+    if (turn) {
+        renderTurn(out, turn);
+        renderFindings(out, findings, "Runner findings");
+    }
+    else {
+        out(`Nothing in this directory's journal for ${id}; asking the service.`);
+    }
+    if (chosen.data) {
+        const viewerIsOwner = Boolean(deps.viewerEmail) && chosen.data.owner?.email === deps.viewerEmail;
+        renderService(out, chosen.data, viewerIsOwner);
+    }
+    else {
+        out();
+        out(`Service: ${chosen.note ?? "no data"}`);
+    }
+    return 0;
+}
+//# sourceMappingURL=investigate.js.map

package/dist/control/server.js

@@ -36,6 +36,7 @@ import { NullRecorder, isIntentMatcher, isMatchAware, isRunCreationAware, isScen
 import { ReplayController, POLL_HOLD_MS, } from "../replay/controller.js";
 import { calculateCostUsd } from "../replay/pricing.js";
 import { logDetail, logLine, errText } from "../util/log.js";
+import { journal } from "../util/journal.js";
 import { packageVersion } from "../util/version.js";
 /** How long a `/tool/post` waits for the proxy's own report before recording its own view. */
 const PROXY_REPORT_GRACE_MS = 1_500;
@@ -388,6 +389,10 @@ export class ControlServer {
         };
         session.run = run;
         logLine("run.start", { run: runId, sess: session.sessionId, tier: "bound" });
+        // Journal-only: the prompt is what `bir investigate` lists a turn by. Never
+        // on stderr, and never more than a preview.
+        if (input)
+            journal("run.prompt", { run: runId, prompt: input.slice(0, 200) });
         // Started here so the round trip overlaps whatever the caller does next;
         // `onPrompt` awaits the same memoized promise under its own budget.
         void this.watchForMatch(session, run);
@@ -521,6 +526,8 @@ export class ControlServer {
             run: run.runId,
             steps: run.ordering.next,
             durationMs,
+            costUsd: cost.measured ? cost.usd.toFixed(4) : undefined,
+            measured: cost.measured,
             lossy: this.lossy,
             recorded: run.recording,
         });
@@ -603,6 +610,7 @@ export class ControlServer {
                 durationMs: Math.max(0, windowMs),
                 prompt: run.input || undefined,
                 siblings: states,
+                runId: run.runId,
             });
             if (!report)
                 return;

package/dist/record/recorder.d.ts

@@ -216,6 +216,12 @@ export declare function isIntentMatcher(r: Recorder): r is Recorder & IntentMatc
  */
 export interface ExecutionReport {
     scenarioId: string;
+    /**
+     * The control server's run id for the turn this report closes. Journal-only:
+     * it lets `bir investigate` join the report to the turn's other lines. Never
+     * sent to the service, which has no row for a matched turn.
+     */
+    runId?: string;
     /** The match's claim token. It *is* the execution row's id, so a doubled report books once. */
     ticket?: string;
     outcome: "steered_full" | "diverged" | "not_steered" | "failed" | "fell_back";

package/dist/record/remote-recorder.js

@@ -219,7 +219,9 @@ export class RemoteRecorder {
             const r = (body ?? {});
             const failed = report.steps?.filter((s) => s.status === "failed").length ?? 0;
             logLine("execution.reported", {
+                run: report.runId,
                 scenario: report.scenarioId,
+                ticket: report.ticket,
                 outcome: report.outcome,
                 derive: report.deriveCostUsd.toFixed(4),
                 session: report.sessionCostUsd.toFixed(4),

package/dist/replay/controller.d.ts

@@ -342,6 +342,8 @@ export declare class ReplayController {
         prompt?: string;
         /** Every plan state of this turn, this one included (R-MONEY-5). */
         siblings?: readonly ReplayState[];
+        /** The control server's own run id for this turn — journal-only, never sent. */
+        runId?: string;
     }): ExecutionReport | undefined;
     /**
      * The step a failed replay is fairly blamed on: the first whose own logic

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),
@@ -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/calculatedReplayGuide.md

@@ -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

package/package.json

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