@basein/runner 0.2.8 → 0.2.11

package/dist/control/server.d.ts

@@ -53,6 +53,14 @@ export interface ControlServerOptions {
     cwd: string;
     /** Preferred port; 0 (or a busy port) falls back to an ephemeral one. */
     port?: number;
+    /**
+     * Whether a busy `port` may fall back to an ephemeral one. Default true — a
+     * recorder in a terminal is better on some port than not at all. A background
+     * recorder whose port is written into a project's hooks passes false: on a
+     * fallback port it would answer SessionStart and then every other hook would
+     * post into the void, which is worse than exiting with a reason.
+     */
+    portFallback?: boolean;
     /** Loopback bearer token. Generated when omitted. */
     token?: string;
     /** Config keys of the servers a proxy wraps. Grows as proxies register. */
@@ -90,6 +98,26 @@ export interface ControlServerOptions {
      * recording and nothing else happens.
      */
     replay?: ReplayOptions;
+    /**
+     * Where the replay switches came from — the environment, the project's
+     * stored policy, or the defaults. Reported on `/health` so `bir doctor` can
+     * say which, because "the allow-list I set is gone" has exactly one cause.
+     */
+    replaySource?: "env" | "sidecar" | "default";
+    /**
+     * Whose account the recordings land in, for `/health` and `bir doctor`. "The
+     * run is not in Recordings" is, more often than not, "it is in somebody
+     * else's", and nothing said which until now.
+     */
+    account?: string;
+    /**
+     * What 'POST /control/stop' does after answering. 'bir-hooks' passes its own
+     * shutdown; a test passes nothing and the route merely says it would. The
+     * route exists so a background recorder can be stopped the way Ctrl-C stops
+     * one in a terminal — finishing the run and draining the queue — rather than
+     * killed, which on Windows is the only other option.
+     */
+    onStopRequested?: () => void;
 }
 export interface ControlServerAddress {
     url: string;

package/dist/control/server.js

@@ -38,6 +38,7 @@ 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";
+import { resolveAuthUrl } from "../auth/client.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;
 /** One MCP call, as seen from up to two sides. */
@@ -127,7 +128,7 @@ export class ControlServer {
                     resolve(this.address);
                 });
             };
-            bind(preferred, preferred !== 0);
+            bind(preferred, preferred !== 0 && this.opts.portFallback !== false);
         });
     }
     async close() {
@@ -150,6 +151,10 @@ export class ControlServer {
         const sessions = [...this.sessions.values()].map((s) => ({
             sessionId: s.sessionId,
             runId: s.run?.runId,
+            // Mid-run right now. What 'ensureDaemon' reads before it dares to restart
+            // an out-of-date recorder: a restart between turns costs nothing, one
+            // during a turn loses the turn.
+            active: Boolean(s.run) && !s.run.finished,
             steps: s.run?.ordering.next ?? 0,
             recording: s.run?.recording ?? false,
             replay: s.run?.replay
@@ -187,12 +192,13 @@ export class ControlServer {
             tier: "bound",
             // The authoritative answer to "is anything actually being saved?".
             recording: this.opts.recording ?? !(this.recorder instanceof NullRecorder),
+            account: this.opts.account ?? null,
             // Whether a handed-out segment may actually run mid-task, or whether the
             // runner is only watching (R-OUT-10, R-LIFE-8). Observe-only must never
             // be invisible: an operator has to be able to see which of the two this
             // machine is doing without reading a log file.
             segmentArm: this.replay.segmentArm,
-            authUrl: process.env.BIR_AUTH_URL ?? null,
+            authUrl: resolveAuthUrl() || null,
             sessionId: this.sessionId,
             pid: process.pid,
             cwd: this.opts.cwd,
@@ -210,6 +216,7 @@ export class ControlServer {
             // (docs/calculatedReplay.md §13.2, mitigation 3).
             replay: {
                 enabled: this.replay.enabled,
+                source: this.opts.replaySource ?? null,
                 minSimilarity: this.opts.replay?.minSimilarity ?? null,
                 allowServers: this.opts.replay?.allowServers ? [...this.opts.replay.allowServers] : null,
                 deriveKey: Boolean(this.opts.replay?.apiKey ?? process.env.ANTHROPIC_API_KEY),
@@ -248,6 +255,12 @@ export class ControlServer {
             }
             const body = await this.readJson(req);
             switch (route) {
+                case "/control/stop":
+                    // Answer first, then leave: the caller is polling for the pid to go.
+                    this.send(res, 200, { ok: Boolean(this.opts.onStopRequested) });
+                    if (this.opts.onStopRequested)
+                        setImmediate(() => this.opts.onStopRequested?.());
+                    return;
                 case "/session/start":
                     this.send(res, 200, this.onSessionStart(body));
                     return;

package/dist/proxy/session.d.ts

@@ -25,7 +25,14 @@ import type { UpstreamClient } from "../upstream/client.js";
 import type { ProxyStepReport } from "../control/correlation.js";
 import { type Recorder } from "../record/recorder.js";
 /** How long a proxy waits for a control server before falling to Tier 2. */
-export declare const DISCOVERY_WINDOW_MS = 5000;
+/**
+ * Ten seconds, not five: the recorder is now started by the SessionStart hook,
+ * which fires while the host is also spawning this proxy, and a cold start
+ * (sign-in refresh, the service's /health probe, then listen) has been
+ * measured at one to four seconds. Steps are buffered meanwhile, never
+ * dropped, and a host session is never waiting on this.
+ */
+export declare const DISCOVERY_WINDOW_MS = 10000;
 export type Tier = "bound" | "standalone" | "pending";
 export interface ProxySessionOptions {
     serverName: string;

package/dist/proxy/session.js

@@ -26,7 +26,7 @@ import { hostname } from "node:os";
 import { ControlClient } from "../control/client.js";
 import { resolveControl } from "../control/discovery.js";
 import { qualifyToolName } from "../control/correlation.js";
-import { authenticate } from "../auth/client.js";
+import { authenticate, resolveAuthUrl } from "../auth/client.js";
 import { NullRecorder } from "../record/recorder.js";
 import { RemoteRecorder } from "../record/remote-recorder.js";
 import { StepQueue } from "../record/queue.js";
@@ -36,7 +36,14 @@ import { redact } from "../record/redact.js";
 import { logLine, logDetail, errText } from "../util/log.js";
 import { packageVersion } from "../util/version.js";
 /** How long a proxy waits for a control server before falling to Tier 2. */
-export const DISCOVERY_WINDOW_MS = 5_000;
+/**
+ * Ten seconds, not five: the recorder is now started by the SessionStart hook,
+ * which fires while the host is also spawning this proxy, and a cold start
+ * (sign-in refresh, the service's /health probe, then listen) has been
+ * measured at one to four seconds. Steps are buffered meanwhile, never
+ * dropped, and a host session is never waiting on this.
+ */
+export const DISCOVERY_WINDOW_MS = 10_000;
 export class ProxySession {
     serverName;
     /** This proxy process, as the control server tells proxies apart (replay/executor.ts). */
@@ -98,6 +105,7 @@ export class ProxySession {
             return;
         }
         const window = this.opts.discoveryWindowMs ?? DISCOVERY_WINDOW_MS;
+        const deadline = Date.now() + window;
         const found = await resolveControl(this.opts.cwd, window);
         if (!found?.url) {
             await this.becomeStandalone(`no control server within ${window}ms`);
@@ -108,12 +116,24 @@ export class ProxySession {
             startedAt: this.startedAt,
             pid: process.pid,
         });
-        const registered = await client.register({
+        const info = {
             serverName: this.serverName,
             pid: process.pid,
             cwd: this.opts.cwd,
             version: packageVersion(),
-        });
+        };
+        // A control server that is still coming up — the SessionStart hook is
+        // starting it while the host spawns us — answers nothing for a moment.
+        // Keep trying inside the same window rather than settle for Tier 2 on the
+        // first refusal.
+        let registered = await client.register(info);
+        while (!registered && Date.now() < deadline) {
+            await new Promise((resolve) => {
+                const t = setTimeout(resolve, 250);
+                t.unref?.();
+            });
+            registered = await client.register(info);
+        }
         if (!registered) {
             await this.becomeStandalone("control server did not answer /proxy/register");
             return;
@@ -216,9 +236,11 @@ export class ProxySession {
         if (this.opts.recorderFactory) {
             return (await this.opts.recorderFactory()) ?? new NullRecorder();
         }
-        const baseUrl = (process.env.BIR_AUTH_URL ?? "").replace(/\/+$/, "");
+        // BIR_AUTH_URL, or the address 'bir setup' stored — the same lookup the
+        // control server and the CLI make, so no two processes disagree about it.
+        const baseUrl = resolveAuthUrl();
         if (!baseUrl) {
-            logLine("recorder.disabled", { why: "BIR_AUTH_URL is not set" });
+            logLine("recorder.disabled", { why: "no service address — run 'bir setup', or set BIR_AUTH_URL" });
             return new NullRecorder();
         }
         // A proxy runs inside the host's process tree with its stdio bound to the

package/docs/calculatedReplay.md

@@ -814,6 +814,23 @@ What actually constrains it:
 If that is not enough for a deployment, the mitigation is a real one and is out of scope here:
 evaluate the logic in a `node:vm` context with a frozen, minimal global. Filed as §20 question 3.
 
+**A hand-edited step is the same code, and runs the same way.** Since 2026-09-25 (the service's
+`editSteps.md`, not yet released) the owner — or Claude working for them — can change a step's
+logic with `bir scenario edit`. The service checks the change against the recording before it saves
+it, but that check is about *what the code computes*. Once saved, the step arrives in the same
+payload and runs here unattended, with `new Function`, next to the same credentials, exactly like
+calculated code. The provenance argument still holds: only the owner can edit, over their own token,
+and anyone else — an admin included — gets `404`. What changes is that *"the model wrote it"* is no
+longer always true.
+
+The service now sandboxes its own evaluation of every logic body: one worker thread with an empty
+environment and a memory cap, a fresh `node:vm` context per evaluation with a time limit and nothing
+but JavaScript's own built-ins, values in and out as JSON text only. It had to: there, one account's
+code runs in the process that holds every account's data and the service's secrets. **The runner
+still does not sandbox.** Here the code runs on the owner's machine, for the owner's account. One
+consequence to know: code that uses `fetch`, `process` or a timer throws in the service's check, so
+it cannot be saved without `--force`; a forced step would run here with all of them.
+
 ### 13.2 Replay bypasses permission prompts
 
 This is the sharpest edge in the whole design, and it must not be buried.
@@ -1038,12 +1055,46 @@ bir uninstall --replay        reverse exactly that, leaving the rest of the inst
 
 bir scenario list             GET  /recordings/runs               runs, iterations, scenario state
 bir scenario show <runId>     GET  /recordings/runs/:id/scenario  intent, params, steps, logic
+bir scenario show <scnId>     GET  /scenarios/:id                 the same, by scenario id (segments too)
+                                   [--step <n>: one step]
 bir scenario calc <runId>     POST /recordings/runs/:id/calculate     [--force to re-derive in place]
+                                   [--force --discard-edits: re-derive a plan with hand edits]
 bir scenario replay <scnId> --prompt "…" [--dry]
 
+bir scenario check <id> --step <n>    POST  /scenarios/:id/steps/:n/check        try a change; writes nothing
+bir scenario edit  <id> --step <n>    PATCH /scenarios/:id/steps/:n              the same check, then save
+bir scenario edits <id>               GET   /scenarios/:id/edits                 the history, newest first
+bir scenario undo  <id> [--edit <e>]  POST  /scenarios/:id/edits/:e/revert       put one step back
+bir scenario editing on|off|status    (no route) ~/.baseinstrunner/installed.json  which `bir` MCP tools are offered
+
 bir replay --scenario <scnId> --prompt "…" [--dry]     alias; the Tier 2 / debugging path (§12.1)
 ```
 
+The second group, and `show <scnId>`, `--step` and `--discard-edits`, were added on 2026-09-25 by
+the service's `editSteps.md` and are not yet released; their routes are new on the service. They
+are the one place `bir` changes a scenario, so the rules are strict:
+
+- **Owner only.** Anyone else, an admin included, gets `404`, never `403`.
+- **A change is saved only if it reproduces the recording and is not a copy**, or on purpose with
+  `--force --note "<why>"`. `check` and `edit` run the same check; `check` never writes.
+- `<id>` is a `run_` id, resolved to its whole-run scenario with `GET /recordings/runs/:id/scenario`,
+  or a `scn_` id, used as it is. Logic goes in with `--input-logic` / `--output-logic` from a file,
+  or `-` for stdin — never inline, because shell quoting mangles JavaScript. `edit` also takes
+  `--freeze`, `--unfreeze`, `--note` and `--revision <n>` (the `expectedRevision` of the body).
+- `undo` without `--edit` undoes the newest edit that can be undone. Every save and every undo bumps
+  the scenario's `chainRevision`.
+- `calc --force` answers `409 scenario_has_edits` on a plan with hand edits, unless
+  `--discard-edits` is given.
+- Exit codes: `0` checked OK, saved or undone; `1` refused, not found, or a service error; `2`
+  usage. `--json` prints the service's body unchanged.
+
+The same commands are tools on the `bir` MCP server. `scenario_show`, `scenario_edits` and
+`investigate` only read, and are always offered. `scenario_check`, `scenario_edit` and
+`scenario_undo` are offered only in a project where `bir scenario editing on` was run, because that
+server runs in every session of every installed project. Each tool runs the installed `bir … --json`;
+a refusal comes back as an MCP error result carrying the report. The operator's walk-through is
+[calculatedReplayGuide.md](calculatedReplayGuide.md) §9.2.
+
 `--dry` maps to BaseIn's `POST /scenarios/:id/replay`, which evaluates the stored logic against the
 source run's *recorded* outputs — no real tools, no side effects, one Haiku call. Without `--dry`,
 `bir replay` runs the same plan through the same executor against the live proxies. `bir doctor`