@basein/runner 0.2.6 → 0.2.8

package/dist/bin/investigate.js

@@ -0,0 +1,580 @@
+/**
+ * `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: "wait: the service retries it once an hour for a day, then repairs the plan from the next run of the prompt. To repair now: `bir scenario calc <runId> --force`.",
+    },
+    nondeterministic_first_step: {
+        cause: "the chain's first step needs a judgement the calculation could not write code for, so the plan cannot start.",
+        fix: "the agent does this task itself; a model step for such judgements is planned (plan-services.md W3.1).",
+    },
+    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;
@@ -936,11 +944,14 @@ export class ControlServer {
                 continue;
             let position;
             if (!state.plan) {
-                // Only a known-bad first step means the turn is committed to doing this
-                // recording's work itself from position 0 (R-HIT-14); every other
-                // decline leaves the recording untouched.
-                if (state.declined === "known_bad_first_step")
+                // Only a first step the plan cannot start on — parked, or a judgement
+                // — means the turn is committed to doing this recording's work itself
+                // from position 0 (R-HIT-14); every other decline leaves the recording
+                // untouched.
+                if (state.declined === "known_bad_first_step" ||
+                    state.declined === "nondeterministic_first_step") {
                     position = 0;
+                }
             }
             else if (state.handover) {
                 position = state.handover.stepIndex;

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),