@basein/runner 0.1.1 → 0.2.1

package/README.md

@@ -51,11 +51,20 @@ byte-for-byte.
 
 ```bash
 export BIR_AUTH_URL=https://your-basein-service   # required to record anything
-bir login                                        # once
+bir login                                        # once; approve it in the browser
 bir-hooks                                        # leave running; Ctrl-C to stop
 claude                                           # your session, now recorded
 ```
 
+`bir login` prints a link and a short code and waits for you to approve it in
+the browser — the OAuth device grant, the same shape `gh auth login` uses. It
+never handles a password, so it works for accounts that only sign in with
+Google, and the link can be opened on any device, which is what makes it usable
+on a headless runner. `--no-browser` prints the link without opening one;
+`--token <value>` redeems a one-time setup token made on the console's *Set up
+the runner* page, with no browser step at all (service 2026-09 or newer);
+`--password` is the deprecated email-and-password prompt, removed next release.
+
 Check it:
 
 ```bash

package/dist/auth/client.d.ts

@@ -1,21 +1,35 @@
 /**
- * auth client — ported from RRepeat's `src/auth/client.ts` (Phase 4.1).
+ * auth client — the CLI's session with the BaseIn service.
  *
- * Authenticates the CLI user against the BaseIn auth-service and returns a JWT
- * session. Every recording call carries that access token; the recording's owner
- * is the JWT subject on the server side, which is what makes tenancy work
- * without BaseInstRunner knowing anything about it.
+ * Every recording call carries an access token; the recording's owner is the
+ * JWT subject on the server side, which is what makes tenancy work without
+ * BaseInstRunner knowing anything about it.
+ *
+ * TWO HALVES, AND ONLY ONE OF THEM MAY PROMPT.
+ *
+ * `authenticate()` is the silent half, and every process calls it — `bir-hooks`
+ * at startup, each `bir-proxy`, and the CLI:
  *
- * Flow:
  *   1. Load the cached session from ~/.baseinstrunner/credentials.json.
  *   2. If the access token is still valid, reuse it.
  *   3. Else if a refresh token is present, POST /auth/refresh (silent).
- *   4. Else prompt for email + password and POST /auth/login.
- *   5. Persist the result (mode 0600) and return it.
+ *   4. Else give up and return undefined.
+ *
+ * It used to have a fifth step — prompt for a password — and that had to go
+ * when sign-in moved to the browser. A device flow prints a code and waits up
+ * to ten minutes for someone to approve it in a browser; a control server doing
+ * that at startup, possibly under a supervisor where nobody can see the code,
+ * would hang instead of degrading. So interaction lives in `deviceLogin()`,
+ * which only `bir login` calls.
  *
- * WHY IT NEVER `process.exit`s: `bir-proxy` runs inside the host's process tree.
- * Failing to authenticate must degrade to not-recording (§10), not kill a server
- * the host is waiting on. Callers get `undefined` and decide.
+ * `deviceLogin()` is the interactive half: the OAuth 2.0 device authorization
+ * grant (RFC 8628). It mints a code, prints a link, and polls until the person
+ * approves in the console. It never handles a password, which is what makes it
+ * work for Google-only accounts — they have no password to type.
+ *
+ * WHY NOTHING HERE `process.exit`s: `bir-proxy` runs inside the host's process
+ * tree. Failing to authenticate must degrade to not-recording (§10), not kill a
+ * server the host is waiting on. Callers get `undefined` and decide.
  *
  * Config:
  *   BIR_AUTH_URL      base URL of the BaseIn auth-service (required).
@@ -36,8 +50,13 @@ export interface AuthSession {
 export interface AuthenticateOptions {
     /** Base URL of the auth service. Defaults to BIR_AUTH_URL. */
     authUrl?: string;
-    /** Never prompt: fail (return undefined) if no valid/refreshable session exists. */
-    nonInteractive?: boolean;
+}
+interface AuthResponse {
+    accessToken: string;
+    refreshToken: string;
+    /** Access token lifetime in seconds. */
+    expiresIn: number;
+    user: AuthUser;
 }
 /**
  * Where the cached session lives.
@@ -105,4 +124,113 @@ export declare function describeAuthService(baseUrl: string, fetchImpl?: typeof
  * obtained. Callers degrade to not-recording rather than failing the session.
  */
 export declare function authenticate(opts?: AuthenticateOptions): Promise<AuthSession | undefined>;
+/**
+ * The service has no device endpoints — it predates browser sign-in.
+ *
+ * Thrown so `bir login` can fall back to the password flow rather than leaving
+ * someone stranded on a runner that is newer than the service it talks to.
+ */
+export declare class DeviceFlowUnsupported extends Error {
+    constructor();
+}
+/** The CLI's view of a started device authorization. */
+export interface DeviceCodeGrant {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete?: string;
+    expiresIn: number;
+    interval: number;
+}
+/**
+ * Start a sign-in. Returns the codes; the caller shows one and polls with the
+ * other.
+ *
+ * `clientName`/`clientVersion` are shown on the approval page so the person can
+ * tell their own `bir login` from somebody else's — the one defence a device
+ * flow has against being talked into approving a stranger's code.
+ */
+export declare function startDeviceCode(authUrl: string, client: {
+    name?: string;
+    version?: string;
+}, fetchImpl?: typeof fetch): Promise<DeviceCodeGrant>;
+/** The user gave up, or the code died before anyone approved it. */
+export declare class DeviceFlowAborted extends Error {
+    readonly reason: "access_denied" | "expired_token" | "timeout" | "cancelled";
+    constructor(message: string, reason: "access_denied" | "expired_token" | "timeout" | "cancelled");
+}
+export interface PollOptions {
+    interval: number;
+    expiresIn: number;
+    fetchImpl?: typeof fetch;
+    /** Injected so tests run in milliseconds rather than minutes. */
+    sleep?: (ms: number) => Promise<void>;
+    signal?: AbortSignal;
+    now?: () => number;
+}
+/**
+ * Poll until the sign-in is approved, refused, or dies.
+ *
+ * RFC 8628 §3.5's loop, including the part people skip: `slow_down` is not an
+ * error, it is the server asking for a longer gap, and the interval must
+ * *stay* longer afterwards. Ignoring it turns a slow client into a blocked one.
+ */
+export declare function pollDeviceToken(authUrl: string, deviceCode: string, opts: PollOptions): Promise<AuthResponse>;
+/**
+ * Open a URL in the user's browser. Best effort, and never fatal.
+ *
+ * No dependency and no shell: this package ships zero runtime dependencies, and
+ * passing a URL through a shell is how a URL becomes a command. The link is
+ * printed either way, so a failure here costs nothing.
+ */
+export declare function openBrowser(url: string): void;
+export interface DeviceLoginOptions {
+    /** `--no-browser`, or a machine where opening one is wrong. */
+    openBrowser?: boolean;
+    fetchImpl?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    signal?: AbortSignal;
+    /** Where the human-readable lines go. stderr, so stdout stays parseable. */
+    write?: (text: string) => void;
+}
+/**
+ * Sign in through the browser and cache the session.
+ *
+ * Everything a person sees goes to stderr: `bir login`'s stdout is one line
+ * that a script may read, and the code block is not it.
+ */
+export declare function deviceLogin(authUrl: string, opts?: DeviceLoginOptions): Promise<AuthSession | undefined>;
+/**
+ * Sign in with a setup token and cache the session.
+ *
+ * A setup token is a device code the console minted already approved for the
+ * person who was signed in there (`POST /auth/device/setup-token`), so this is
+ * the browser flow with the waiting removed: one redemption, no polling. It is
+ * the secret that opens a session, so it is never printed or logged here, for
+ * the same reason a device code never is.
+ */
+export declare function tokenLogin(authUrl: string, token: string, opts?: {
+    fetchImpl?: typeof fetch;
+}): Promise<AuthSession>;
+/**
+ * Sign in with an email and a password.
+ *
+ * DEPRECATED, and kept for exactly two cases: `bir login --password`, and a
+ * runner talking to a service that predates the device endpoints. Both go in
+ * the release after this one, and this function goes with them.
+ *
+ * It cannot work at all for an account created through Google — there is no
+ * password on it to send — which is the main reason sign-in moved.
+ */
+export declare function legacyPasswordLogin(authUrl: string): Promise<AuthSession | undefined>;
+/**
+ * Sign out: revoke the refresh token server-side, then forget it locally.
+ *
+ * Deleting the file alone left the token live for its full 30 days, which made
+ * `bir logout` a tidy-up rather than a revocation. The endpoint is idempotent
+ * and its failure is not worth blocking on — the local half must happen either
+ * way, or "logged out" would be a lie on a machine with no network.
+ */
+export declare function logout(authUrl?: string): Promise<void>;
+export {};
 //# sourceMappingURL=client.d.ts.map

package/dist/auth/client.js

@@ -1,31 +1,48 @@
 /**
- * auth client — ported from RRepeat's `src/auth/client.ts` (Phase 4.1).
+ * auth client — the CLI's session with the BaseIn service.
  *
- * Authenticates the CLI user against the BaseIn auth-service and returns a JWT
- * session. Every recording call carries that access token; the recording's owner
- * is the JWT subject on the server side, which is what makes tenancy work
- * without BaseInstRunner knowing anything about it.
+ * Every recording call carries an access token; the recording's owner is the
+ * JWT subject on the server side, which is what makes tenancy work without
+ * BaseInstRunner knowing anything about it.
+ *
+ * TWO HALVES, AND ONLY ONE OF THEM MAY PROMPT.
+ *
+ * `authenticate()` is the silent half, and every process calls it — `bir-hooks`
+ * at startup, each `bir-proxy`, and the CLI:
  *
- * Flow:
  *   1. Load the cached session from ~/.baseinstrunner/credentials.json.
  *   2. If the access token is still valid, reuse it.
  *   3. Else if a refresh token is present, POST /auth/refresh (silent).
- *   4. Else prompt for email + password and POST /auth/login.
- *   5. Persist the result (mode 0600) and return it.
+ *   4. Else give up and return undefined.
+ *
+ * It used to have a fifth step — prompt for a password — and that had to go
+ * when sign-in moved to the browser. A device flow prints a code and waits up
+ * to ten minutes for someone to approve it in a browser; a control server doing
+ * that at startup, possibly under a supervisor where nobody can see the code,
+ * would hang instead of degrading. So interaction lives in `deviceLogin()`,
+ * which only `bir login` calls.
  *
- * WHY IT NEVER `process.exit`s: `bir-proxy` runs inside the host's process tree.
- * Failing to authenticate must degrade to not-recording (§10), not kill a server
- * the host is waiting on. Callers get `undefined` and decide.
+ * `deviceLogin()` is the interactive half: the OAuth 2.0 device authorization
+ * grant (RFC 8628). It mints a code, prints a link, and polls until the person
+ * approves in the console. It never handles a password, which is what makes it
+ * work for Google-only accounts — they have no password to type.
+ *
+ * WHY NOTHING HERE `process.exit`s: `bir-proxy` runs inside the host's process
+ * tree. Failing to authenticate must degrade to not-recording (§10), not kill a
+ * server the host is waiting on. Callers get `undefined` and decide.
  *
  * Config:
  *   BIR_AUTH_URL      base URL of the BaseIn auth-service (required).
  *   BIR_AUTH_DISABLE  "1" to skip auth entirely (local dev / CI).
  */
+import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
 import { configDir } from "../control/paths.js";
 import { join } from "node:path";
 import { logLine, errText } from "../util/log.js";
+import { packageVersion } from "../util/version.js";
 /**
  * Where the cached session lives.
  *
@@ -323,10 +340,253 @@ export async function authenticate(opts) {
             return refreshed;
         }
     }
-    if (opts?.nonInteractive || !process.stdin.isTTY) {
-        logLine("auth.no_session", {
-            why: "no valid session and no terminal to log in on — run `bir login`",
+    // No session, and this function does not make one. Signing in is a browser
+    // round trip that can take minutes; a proxy or control server blocking on it
+    // would hang the host instead of degrading to not-recording.
+    logLine("auth.no_session", {
+        why: "no valid session — run `bir login`",
+    });
+    return undefined;
+}
+// ── Device authorization grant (RFC 8628) ──────────────────────────────────
+/**
+ * The service has no device endpoints — it predates browser sign-in.
+ *
+ * Thrown so `bir login` can fall back to the password flow rather than leaving
+ * someone stranded on a runner that is newer than the service it talks to.
+ */
+export class DeviceFlowUnsupported extends Error {
+    constructor() {
+        super("this BaseIn service does not offer browser sign-in");
+        this.name = "DeviceFlowUnsupported";
+    }
+}
+/**
+ * Start a sign-in. Returns the codes; the caller shows one and polls with the
+ * other.
+ *
+ * `clientName`/`clientVersion` are shown on the approval page so the person can
+ * tell their own `bir login` from somebody else's — the one defence a device
+ * flow has against being talked into approving a stranger's code.
+ */
+export async function startDeviceCode(authUrl, client, fetchImpl = fetch) {
+    const res = await fetchImpl(`${authUrl}/auth/device/code`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ clientName: client.name, clientVersion: client.version }),
+    });
+    // A service without the endpoint 404s. Anything else is a real failure.
+    if (res.status === 404)
+        throw new DeviceFlowUnsupported();
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        const isHtml = (res.headers.get("content-type") ?? "").includes("html") || /^\s*<(!doctype|html)/i.test(text);
+        throw new Error(`HTTP ${res.status}${isHtml
+            ? " — the answer was a web page, not JSON: this URL is a website, not the BaseIn API"
+            : text
+                ? ` — ${text.slice(0, 300)}`
+                : ""}`);
+    }
+    return (await res.json());
+}
+/** The user gave up, or the code died before anyone approved it. */
+export class DeviceFlowAborted extends Error {
+    reason;
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+        this.name = "DeviceFlowAborted";
+    }
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Poll until the sign-in is approved, refused, or dies.
+ *
+ * RFC 8628 §3.5's loop, including the part people skip: `slow_down` is not an
+ * error, it is the server asking for a longer gap, and the interval must
+ * *stay* longer afterwards. Ignoring it turns a slow client into a blocked one.
+ */
+export async function pollDeviceToken(authUrl, deviceCode, opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const sleep = opts.sleep ?? defaultSleep;
+    const now = opts.now ?? Date.now;
+    const deadline = now() + opts.expiresIn * 1000;
+    let interval = opts.interval;
+    for (;;) {
+        if (opts.signal?.aborted) {
+            throw new DeviceFlowAborted("sign-in cancelled", "cancelled");
+        }
+        if (now() >= deadline) {
+            throw new DeviceFlowAborted("the code expired before it was approved — run `bir login` again", "timeout");
+        }
+        await sleep(interval * 1000);
+        const res = await fetchImpl(`${authUrl}/auth/device/token`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ deviceCode }),
+        });
+        if (res.ok)
+            return (await res.json());
+        const body = (await res.json().catch(() => ({})));
+        switch (body.error) {
+            case "authorization_pending":
+                continue;
+            case "slow_down":
+                // Adopt the server's number when it sends one; otherwise back off the
+                // way the RFC suggests. Either way the wider gap persists.
+                interval = typeof body.interval === "number" ? body.interval : interval + 5;
+                continue;
+            case "access_denied":
+                throw new DeviceFlowAborted("the sign-in was refused in the browser", "access_denied");
+            case "expired_token":
+                throw new DeviceFlowAborted("the code expired before it was approved — run `bir login` again", "expired_token");
+            default:
+                throw new Error(`sign-in failed: ${body.error ?? `HTTP ${res.status}`}`);
+        }
+    }
+}
+/**
+ * Open a URL in the user's browser. Best effort, and never fatal.
+ *
+ * No dependency and no shell: this package ships zero runtime dependencies, and
+ * passing a URL through a shell is how a URL becomes a command. The link is
+ * printed either way, so a failure here costs nothing.
+ */
+export function openBrowser(url) {
+    try {
+        const [command, args] = process.platform === "win32"
+            ? // The empty string is `start`'s title argument. Without it, a quoted
+                // URL is taken *as* the title and nothing opens.
+                ["cmd", ["/c", "start", "", url]]
+            : process.platform === "darwin"
+                ? ["open", [url]]
+                : ["xdg-open", [url]];
+        const child = spawn(command, [...args], { detached: true, stdio: "ignore" });
+        child.on("error", () => {
+            /* no browser here; the printed link is the fallback */
         });
+        child.unref();
+    }
+    catch {
+        /* see above */
+    }
+}
+/**
+ * Should we try to open a browser at all?
+ *
+ * Over SSH the browser would open on the wrong machine, and with no terminal
+ * there is nobody watching. In both cases the link still gets printed — it can
+ * be opened on a phone, which is the point of this grant.
+ */
+function shouldOpenBrowser() {
+    if (process.env.SSH_CONNECTION || process.env.SSH_TTY)
+        return false;
+    return Boolean(process.stderr.isTTY);
+}
+/**
+ * Sign in through the browser and cache the session.
+ *
+ * Everything a person sees goes to stderr: `bir login`'s stdout is one line
+ * that a script may read, and the code block is not it.
+ */
+export async function deviceLogin(authUrl, opts = {}) {
+    const write = opts.write ?? ((text) => process.stderr.write(text));
+    const grant = await startDeviceCode(authUrl, { name: clientName(), version: packageVersion() }, opts.fetchImpl);
+    const link = grant.verificationUriComplete ?? grant.verificationUri;
+    write(`\n[bir] Sign in to ${authUrl}\n\n`);
+    write(`  Open   ${link}\n`);
+    write(`  Code   ${grant.userCode}\n\n`);
+    const wantsBrowser = opts.openBrowser ?? shouldOpenBrowser();
+    if (wantsBrowser) {
+        write("  Opening your browser…\n");
+        openBrowser(link);
+    }
+    else {
+        write("  Open that link on any device — a phone is fine.\n");
+    }
+    write("  Waiting for approval…  (Ctrl-C to cancel)\n\n");
+    logLine("auth.device_started", { url: authUrl, expiresIn: grant.expiresIn });
+    const res = await pollDeviceToken(authUrl, grant.deviceCode, {
+        interval: grant.interval,
+        expiresIn: grant.expiresIn,
+        fetchImpl: opts.fetchImpl,
+        sleep: opts.sleep,
+        signal: opts.signal,
+    });
+    const session = toSession(res);
+    saveCredentials(session);
+    return session;
+}
+/**
+ * Sign in with a setup token and cache the session.
+ *
+ * A setup token is a device code the console minted already approved for the
+ * person who was signed in there (`POST /auth/device/setup-token`), so this is
+ * the browser flow with the waiting removed: one redemption, no polling. It is
+ * the secret that opens a session, so it is never printed or logged here, for
+ * the same reason a device code never is.
+ */
+export async function tokenLogin(authUrl, token, opts = {}) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const res = await fetchImpl(`${authUrl}/auth/device/token`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ deviceCode: token.trim() }),
+    });
+    if (res.status === 404)
+        throw new DeviceFlowUnsupported();
+    if (res.ok) {
+        const session = toSession((await res.json()));
+        saveCredentials(session);
+        logLine("auth.token_login", { url: authUrl });
+        return session;
+    }
+    const body = (await res.json().catch(() => ({})));
+    switch (body.error) {
+        case "expired_token":
+            throw new DeviceFlowAborted("this setup token has expired or was already used — make a new one on the console's " +
+                "Set up the runner page and paste it within ten minutes", "expired_token");
+        case "invalid_grant":
+        case "authorization_pending":
+        case "slow_down":
+        case "access_denied":
+            // A pending or unknown code is not a setup token: the console only hands
+            // out codes that are already approved.
+            throw new DeviceFlowAborted("that is not a valid setup token — copy the whole token from the console's " +
+                "Set up the runner page", "access_denied");
+        default:
+            throw new Error(`sign-in failed: ${body.error ?? `HTTP ${res.status}`}`);
+    }
+}
+/**
+ * A name for this machine, shown on the approval page.
+ *
+ * This is the string someone reads to decide whether the request is theirs, so
+ * it names the tool and the host. Never fatal: an unnamed client still works,
+ * it just tells the approver less.
+ */
+function clientName() {
+    try {
+        return `bir on ${hostname()}`;
+    }
+    catch {
+        return "bir";
+    }
+}
+// ── The password flow, on its way out ──────────────────────────────────────
+/**
+ * Sign in with an email and a password.
+ *
+ * DEPRECATED, and kept for exactly two cases: `bir login --password`, and a
+ * runner talking to a service that predates the device endpoints. Both go in
+ * the release after this one, and this function goes with them.
+ *
+ * It cannot work at all for an account created through Google — there is no
+ * password on it to send — which is the main reason sign-in moved.
+ */
+export async function legacyPasswordLogin(authUrl) {
+    if (!process.stdin.isTTY) {
+        logLine("auth.no_session", { why: "no terminal to read a password on" });
         return undefined;
     }
     // Never send a password to something that is not the service. The website
@@ -353,4 +613,31 @@ export async function authenticate(opts) {
         return undefined;
     }
 }
+/**
+ * Sign out: revoke the refresh token server-side, then forget it locally.
+ *
+ * Deleting the file alone left the token live for its full 30 days, which made
+ * `bir logout` a tidy-up rather than a revocation. The endpoint is idempotent
+ * and its failure is not worth blocking on — the local half must happen either
+ * way, or "logged out" would be a lie on a machine with no network.
+ */
+export async function logout(authUrl) {
+    const cached = loadCredentials();
+    if (authUrl && cached?.refreshToken) {
+        try {
+            await fetch(`${authUrl}/auth/logout`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ refreshToken: cached.refreshToken }),
+            });
+        }
+        catch (err) {
+            logLine("auth.logout_remote_failed", {
+                error: errText(err),
+                why: "the local credentials are cleared regardless",
+            });
+        }
+    }
+    clearCredentials();
+}
 //# sourceMappingURL=client.js.map

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

@@ -33,6 +33,19 @@
  *   BIR_DERIVE_MODEL          derivation model (default claude-haiku-4-5-…)
  *   BIR_MATCH_BUDGET_MS       prompt-hook match wait (default 2500)
  *   BIR_DERIVE_BUDGET_MS      first PreToolUse derivation wait (default 8000)
+ *   BIR_DERIVE_RECENT_RESULTS how many of this prompt's tool results derivation
+ *                             reads, so a target named by an earlier step can be
+ *                             found (default 5; 0 off)
+ *   BIR_INTENT_SOURCES        which text a step's intent may come from
+ *                             (default text,thinking,tool)
+ *   BIR_INTENT_REQUESTS_PER_TURN  probes one turn may send (default 40).
+ *                             Separate from BIR_INTENT_MATCHES_PER_TURN: arming
+ *                             is a claim on the turn, counting hits is not
+ *   BIR_SEGMENT_ARM           1 lets a handed-out segment actually run mid-task.
+ *                             Unset is observe-only: what would have armed is
+ *                             logged and nothing is replaced
+ *   BIR_MIN_SEGMENT_STEER_SIMILARITY  minimum similarity to steer a segment
+ *                             (default 0.95)
  *   BIR_REPLAY_BUDGET_MS      whole-plan ceiling, direct mode (default 120000)
  *   BIR_STEP_TIMEOUT_MS       one direct tools/call (default 60000)
  *

package/dist/bin/bir-hooks.js

@@ -33,6 +33,19 @@
  *   BIR_DERIVE_MODEL          derivation model (default claude-haiku-4-5-…)
  *   BIR_MATCH_BUDGET_MS       prompt-hook match wait (default 2500)
  *   BIR_DERIVE_BUDGET_MS      first PreToolUse derivation wait (default 8000)
+ *   BIR_DERIVE_RECENT_RESULTS how many of this prompt's tool results derivation
+ *                             reads, so a target named by an earlier step can be
+ *                             found (default 5; 0 off)
+ *   BIR_INTENT_SOURCES        which text a step's intent may come from
+ *                             (default text,thinking,tool)
+ *   BIR_INTENT_REQUESTS_PER_TURN  probes one turn may send (default 40).
+ *                             Separate from BIR_INTENT_MATCHES_PER_TURN: arming
+ *                             is a claim on the turn, counting hits is not
+ *   BIR_SEGMENT_ARM           1 lets a handed-out segment actually run mid-task.
+ *                             Unset is observe-only: what would have armed is
+ *                             logged and nothing is replaced
+ *   BIR_MIN_SEGMENT_STEER_SIMILARITY  minimum similarity to steer a segment
+ *                             (default 0.95)
  *   BIR_REPLAY_BUDGET_MS      whole-plan ceiling, direct mode (default 120000)
  *   BIR_STEP_TIMEOUT_MS       one direct tools/call (default 60000)
  *
@@ -93,6 +106,29 @@ function positiveInt(value, fallback) {
     const n = Number(value);
     return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
 }
+/** Like {@link positiveInt}, but 0 is a meaningful setting rather than unset. */
+function nonNegativeInt(value, fallback) {
+    const n = Number(value);
+    return Number.isFinite(n) && n >= 0 ? Math.floor(n) : fallback;
+}
+/**
+ * `BIR_INTENT_SOURCES` — which text a step's intent may be read from
+ * (segmented.md R-INTENT-3). Unset or unparseable means all three.
+ *
+ * It governs only what is *sent*. Turning every source off does not stop a
+ * probe: the request still goes out with an empty text and the server builds a
+ * line from the tool name and arguments (R-HIT-4).
+ */
+function parseIntentSources(value) {
+    if (value === undefined)
+        return undefined;
+    const allowed = ["text", "thinking", "tool"];
+    const wanted = value
+        .split(",")
+        .map((s) => s.trim().toLowerCase())
+        .filter((s) => allowed.includes(s));
+    return new Set(wanted);
+}
 /**
  * Assemble the replay configuration (docs/calculatedReplay.md §5.3 of the guide).
  *
@@ -116,6 +152,25 @@ function buildReplayOptions(auth) {
             planMs: positiveInt(process.env.BIR_REPLAY_BUDGET_MS, 120_000),
             stepMs: positiveInt(process.env.BIR_STEP_TIMEOUT_MS, 60_000),
         },
+        // Intent matching in the ReAct loop (fallbk.md §Runner 4). On with replay;
+        // BIR_INTENT_MATCH=0 turns it off on its own.
+        intentMatch: {
+            enabled: process.env.BIR_INTENT_MATCH !== "0",
+            // 4 000, not 1 500: a request whose best segment lands in the not-clear
+            // band has one live question to ask under the server's own 2 500 ms
+            // attempt, and must still answer inside the hook's 30 s (segmented.md
+            // R-HIT-11).
+            budgetMs: positiveInt(process.env.BIR_INTENT_MATCH_BUDGET_MS, 4_000),
+            maxPerTurn: positiveInt(process.env.BIR_INTENT_MATCHES_PER_TURN, 3),
+            maxRequestsPerTurn: positiveInt(process.env.BIR_INTENT_REQUESTS_PER_TURN, 40),
+        },
+        // Observe-only until an operator has read the logs and turned it on
+        // (segmented.md R-OUT-10, R-LIFE-7). Arming is never the way to find out.
+        segmentArm: process.env.BIR_SEGMENT_ARM === "1",
+        minSegmentSimilarity: (() => {
+            const n = Number(process.env.BIR_MIN_SEGMENT_STEER_SIMILARITY);
+            return Number.isFinite(n) ? n : 0.95;
+        })(),
         authUrl: auth.baseUrl,
         // Read late, not captured: `RemoteRecorder` refreshes the access token as the
         // session outlives it, and a snapshot taken here would go stale mid-run.
@@ -128,6 +183,7 @@ function buildReplayOptions(auth) {
             minSimilarity: opts.minSimilarity,
             allowServers: allowServers ? [...allowServers].join(",") : "(all wrapped)",
             derive: process.env.ANTHROPIC_API_KEY ? "anthropic" : "recorded sample values",
+            intentMatch: opts.intentMatch?.enabled ? "on" : "off",
             why: "matched prompts will run their calculated scenario — steered steps are auto-approved",
         });
     }
@@ -152,6 +208,8 @@ async function main() {
         host: { app: "claude-code" },
         correlationDecision: process.env.BIR_CORRELATION_DECISION === "ask" ? "ask" : "allow",
         noCorrelation: process.env.BIR_NO_CORRELATION === "1",
+        deriveRecentResults: nonNegativeInt(process.env.BIR_DERIVE_RECENT_RESULTS, 5),
+        intentSources: parseIntentSources(process.env.BIR_INTENT_SOURCES),
         replay: buildReplayOptions(auth),
     });
     const address = await server.listen();