@basein/runner 0.1.0

package/dist/config/resolve.js

@@ -0,0 +1,132 @@
+/**
+ * config/resolve — which MCP servers a client would actually use for a cwd.
+ *
+ * Ported from RRepeat's `mcp-registry.ts`, and extended to report **which scope
+ * won**, because that is what Phase 7.3 needs: rewriting a file whose entry is
+ * shadowed by a higher-precedence scope changes nothing at all, and the user is
+ * left with an install that never runs.
+ *
+ * Claude Code merges three scopes, highest precedence first. The whole winning
+ * entry is used — fields are never merged across scopes:
+ *   1. **Local**   — `~/.claude.json` → `projects[<cwd>].mcpServers`
+ *   2. **Project** — `<cwd>/.mcp.json` → `mcpServers`
+ *   3. **User**    — `~/.claude.json` → top-level `mcpServers`
+ *
+ * THE WINDOWS PATH TRAP (Phase 7.1). Claude Code stores the local-scope project
+ * key with forward slashes while `process.cwd()` returns backslashes, and it
+ * keeps one entry per spelling it has seen — so the backslash twin routinely
+ * exists carrying `mcpServers: {}` while the forward-slash one holds the real
+ * config. Matching the literal key misses every time; matching a *normalised*
+ * path, and refusing to stop at an empty twin, is what makes local scope work.
+ */
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { normalizePath } from "../control/paths.js";
+export function isRemote(config) {
+    return (config.type === "http" || config.type === "sse");
+}
+/**
+ * Strip a UTF-8 byte order mark.
+ *
+ * Notepad, VS Code's "UTF-8 with BOM", and PowerShell's `Out-File -Encoding utf8`
+ * all write one, so it is the normal shape of a config a Windows operator edited
+ * by hand. `readFileSync(path, "utf8")` decodes it to U+FEFF rather than
+ * consuming it, and `JSON.parse` then rejects the file as malformed — which
+ * surfaced as `bir install` reporting success while wrapping nothing.
+ */
+function stripBom(text) {
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+/** Parse a JSON file. `undefined` if absent; throws if present but malformed. */
+export function parseJsonFile(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        return undefined; // absent / unreadable — "not configured"
+    }
+    try {
+        return JSON.parse(stripBom(raw));
+    }
+    catch (err) {
+        throw new Error(`invalid JSON at ${path}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+function readMcpServers(path, required) {
+    const parsed = parseJsonFile(path);
+    if (parsed === undefined) {
+        if (required)
+            throw new Error(`MCP config not readable at ${path}`);
+        return {};
+    }
+    return parsed.mcpServers ?? {};
+}
+export function claudeJsonPath(override) {
+    return override ?? process.env.BIR_CLAUDE_JSON ?? join(homedir(), ".claude.json");
+}
+/**
+ * The local scope's servers for `cwd`. The literal key is tried first, then
+ * every key is compared as a normalised path — and a key resolving to *no*
+ * servers does not end the search, because the empty twin is exactly the shape
+ * the Windows miss takes on disk.
+ */
+export function projectScope(projects, cwd) {
+    if (!projects)
+        return {};
+    const exact = projects[cwd]?.mcpServers;
+    if (exact && Object.keys(exact).length > 0)
+        return exact;
+    const want = normalizePath(cwd);
+    for (const [key, entry] of Object.entries(projects)) {
+        const servers = entry?.mcpServers;
+        if (servers && Object.keys(servers).length > 0 && normalizePath(key) === want)
+            return servers;
+    }
+    return exact ?? {};
+}
+/** The key under which Claude Code stores (or would store) this cwd's local scope. */
+export function projectKeyFor(projects, cwd) {
+    if (!projects)
+        return cwd;
+    if (cwd in projects)
+        return cwd;
+    const want = normalizePath(cwd);
+    for (const key of Object.keys(projects)) {
+        if (normalizePath(key) === want)
+            return key;
+    }
+    return cwd;
+}
+/** Every MCP server that would be live for `cwd`, with the scope that won. */
+export function resolveServers(cwd, opts = {}) {
+    if (opts.configPath) {
+        const servers = readMcpServers(opts.configPath, true);
+        return Object.entries(servers).map(([name, config]) => ({
+            name,
+            config,
+            scope: "explicit",
+            shadowed: [],
+        }));
+    }
+    const parsed = parseJsonFile(claudeJsonPath(opts.claudeJsonPath));
+    const byScope = [
+        ["local", projectScope(parsed?.projects, cwd)],
+        ["project", readMcpServers(join(cwd, ".mcp.json"), false)],
+        ["user", parsed?.mcpServers ?? {}],
+    ];
+    const winners = new Map();
+    for (const [scope, servers] of byScope) {
+        for (const [name, config] of Object.entries(servers)) {
+            const existing = winners.get(name);
+            if (existing) {
+                existing.shadowed.push(scope);
+                continue;
+            }
+            winners.set(name, { name, config, scope, shadowed: [] });
+        }
+    }
+    return [...winners.values()];
+}
+//# sourceMappingURL=resolve.js.map

package/dist/control/client.d.ts

@@ -0,0 +1,56 @@
+/**
+ * control/client — the proxy's side of the control plane.
+ *
+ * A thin authenticated HTTP client. Every call is best-effort and returns rather
+ * than throws: the control server going away must downgrade a proxy to Tier 2,
+ * never break the tool call the host is waiting on (§10).
+ */
+import type { ProxyStepReport } from "./correlation.js";
+export interface RegisterResult {
+    ok: boolean;
+    sessionId?: string;
+    runId?: string;
+    correlation?: "injected" | "fingerprint";
+    /** Whether calculated replay is on, i.e. whether to open the work loop. */
+    replay?: boolean;
+    pollHoldMs?: number;
+}
+/** One `tools/call` the control server wants this proxy to run (§16.2). */
+export interface ProxyWork {
+    workId: string;
+    /** Upstream-local name — `navigate_page`, not `mcp__server__navigate_page`. */
+    toolName: string;
+    arguments: unknown;
+    timeoutMs: number;
+}
+export declare class ControlClient {
+    private readonly url;
+    private readonly token;
+    private readonly timeoutMs;
+    constructor(url: string, token: string, timeoutMs?: number);
+    register(info: {
+        serverName: string;
+        pid: number;
+        cwd: string;
+        /** This proxy's package version, so the server can spot a half-upgraded machine. */
+        version?: string;
+    }): Promise<RegisterResult | undefined>;
+    /** Report one completed MCP call. Resolves false when the send was dropped. */
+    report(step: ProxyStepReport): Promise<boolean>;
+    health(): Promise<Record<string, unknown> | undefined>;
+    /**
+     * Park until the control server has a tool call for this proxy, or the hold
+     * elapses (docs/calculatedReplay.md §16.2).
+     *
+     * Its own timeout must exceed the server's hold, or every poll would look like
+     * a failure to the client that is deliberately waiting. `undefined` covers both
+     * "nothing to do" and "the server went away"; the caller re-polls either way,
+     * with a small delay so a dead server is not busy-looped.
+     */
+    poll(serverName: string, holdMs: number): Promise<ProxyWork | undefined>;
+    /** Hand back one dispatched call's result, or the reason it could not run. */
+    result(workId: string, result?: unknown, error?: string): Promise<void>;
+    private post;
+    private request;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/control/client.js

@@ -0,0 +1,86 @@
+/**
+ * control/client — the proxy's side of the control plane.
+ *
+ * A thin authenticated HTTP client. Every call is best-effort and returns rather
+ * than throws: the control server going away must downgrade a proxy to Tier 2,
+ * never break the tool call the host is waiting on (§10).
+ */
+import { errText, logDetail } from "../util/log.js";
+export class ControlClient {
+    url;
+    token;
+    timeoutMs;
+    constructor(url, token, timeoutMs = 5_000) {
+        this.url = url.replace(/\/+$/, "");
+        this.token = token;
+        this.timeoutMs = timeoutMs;
+    }
+    async register(info) {
+        const body = await this.post("/proxy/register", info);
+        return body;
+    }
+    /** Report one completed MCP call. Resolves false when the send was dropped. */
+    async report(step) {
+        return (await this.post("/proxy/step", step)) !== undefined;
+    }
+    async health() {
+        return (await this.request("GET", "/health"));
+    }
+    /**
+     * Park until the control server has a tool call for this proxy, or the hold
+     * elapses (docs/calculatedReplay.md §16.2).
+     *
+     * Its own timeout must exceed the server's hold, or every poll would look like
+     * a failure to the client that is deliberately waiting. `undefined` covers both
+     * "nothing to do" and "the server went away"; the caller re-polls either way,
+     * with a small delay so a dead server is not busy-looped.
+     */
+    async poll(serverName, holdMs) {
+        const body = (await this.request("POST", "/proxy/poll", { serverName, holdMs }, holdMs + 10_000));
+        return body?.work;
+    }
+    /** Hand back one dispatched call's result, or the reason it could not run. */
+    async result(workId, result, error) {
+        await this.post("/proxy/result", { workId, result, error });
+    }
+    post(path, body) {
+        return this.request("POST", path, body);
+    }
+    async request(method, path, body, timeoutMs = this.timeoutMs) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        timer.unref?.();
+        try {
+            const res = await fetch(`${this.url}${path}`, {
+                method,
+                headers: {
+                    "content-type": "application/json",
+                    authorization: `Bearer ${this.token}`,
+                },
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                logDetail("control.http_error", { path, status: res.status });
+                return undefined;
+            }
+            const text = await res.text();
+            if (!text)
+                return {};
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                return {};
+            }
+        }
+        catch (err) {
+            logDetail("control.unreachable", { path, error: errText(err) });
+            return undefined;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/control/correlation.d.ts

@@ -0,0 +1,86 @@
+/**
+ * correlation — how one MCP call seen twice becomes one recorded step (Phase 6).
+ *
+ * In Tier 1 a wrapped `tools/call` is observed by the hook at `PreToolUse` *and*
+ * by the proxy at `tools/call`. Without correlation you double-record, and the
+ * two halves each carry something the other lacks:
+ *
+ *   - the **hook** contributes identity (`tool_use_id`), ordering position, the
+ *     model's original arguments, and the reasoning text;
+ *   - the **proxy** contributes the true upstream result, `isError`,
+ *     `structuredContent` and real execution duration.
+ *
+ * MECHANISM. At `PreToolUse` the hook answers `permissionDecision: "allow"` with
+ * `updatedInput = { ...original, [BIR_CALL_ID]: id }`. Claude Code passes those
+ * arguments through as the call's `arguments`, the proxy strips the key before
+ * relaying, and echoes it on the step report. The control server joins on it.
+ *
+ * THE COST, INHERITED KNOWINGLY from RRepeat's sentinel: carrying an extra
+ * argument requires **relaxing the tool's schema** (`additionalProperties: true`
+ * plus the declared key), and that relaxation is visible to the model on every
+ * call, not only recorded ones. Hence {@link relaxSchema} is applied only when
+ * Tier 1 correlation is actually active, and only to wrapped servers.
+ *
+ * THE FALLBACK. `--no-correlation` matches on `(serverName, toolName, hash(args))`
+ * inside a 30 s window instead. It is lossy under identical concurrent calls —
+ * two parallel calls with the same arguments are genuinely indistinguishable
+ * without an id — and says so rather than pretending otherwise.
+ */
+/** The argument key that carries the call id from hook to proxy. */
+export declare const BIR_CALL_ID = "__bir_call_id__";
+/** Window in which a fingerprint may still match its hook-side twin. */
+export declare const FINGERPRINT_WINDOW_MS = 30000;
+/** The step a proxy reports to the control server (§5). */
+export interface ProxyStepReport {
+    /** Present in Tier 1 when the hook injected one. */
+    callId?: string;
+    /** Config key, e.g. "chrome-devtools". */
+    serverName: string;
+    /** Upstream-local name, e.g. "navigate_page". */
+    toolName: string;
+    /** Client-rendered, e.g. "mcp__chrome-devtools__navigate_page". */
+    qualifiedName: string;
+    /** Post-redaction. */
+    args: unknown;
+    /** Whole CallToolResult, post-redaction and truncation. */
+    result?: unknown;
+    isError: boolean;
+    errorMessage?: string;
+    /** Epoch ms. */
+    startedAt: number;
+    durationMs: number;
+}
+export declare function newCallId(): string;
+/**
+ * Pull the call id out of a `tools/call` argument object.
+ * Returns the id (if any) and the arguments as the upstream must see them —
+ * the proxy relays `cleaned`, never the original, so the upstream never sees a
+ * key its schema does not declare.
+ */
+export declare function extractCallId(args: unknown): {
+    callId?: string;
+    cleaned: unknown;
+};
+/**
+ * Relax a tool's `inputSchema` so a host that validates `updatedInput` accepts
+ * the extra key. Original properties are preserved, so ordinary calls validate
+ * exactly as before.
+ */
+export declare function relaxSchema(schema: unknown): Record<string, unknown>;
+/** Apply {@link relaxSchema} to every tool in a `tools/list` result, in place-free form. */
+export declare function relaxToolsListResult(result: unknown): unknown;
+/**
+ * The `--no-correlation` join key. Stable across the hook/proxy boundary because
+ * both sides hash the *same* argument object — the model's — with sorted keys.
+ */
+export declare function fingerprint(serverName: string, toolName: string, args: unknown): string;
+/** JSON with object keys sorted, so key order cannot change a fingerprint. */
+export declare function stableStringify(value: unknown): string;
+/** Claude Code's rendering of an MCP tool name. Other hosts differ (D8). */
+export declare function qualifyToolName(serverName: string, toolName: string): string;
+/** Split `mcp__<server>__<tool>` back into its parts, or undefined if it is not one. */
+export declare function parseQualifiedName(name: string): {
+    serverName: string;
+    toolName: string;
+} | undefined;
+//# sourceMappingURL=correlation.d.ts.map

package/dist/control/discovery.d.ts

@@ -0,0 +1,50 @@
+/**
+ * discovery — how a proxy finds the control server for its project (Phase 5).
+ *
+ * The control server writes `~/.baseinstrunner/control/<key>.json`, where `<key>`
+ * is `sha256(normalised cwd)[0..16]`. A proxy resolves its control server in this
+ * order:
+ *
+ *   1. `BIR_CONTROL_URL` in the environment — injected into generated config, and
+ *      the only reliable channel for an Agent SDK session, which may not share a
+ *      cwd with anything on disk.
+ *   2. The discovery file for its own cwd.
+ *   3. Give up → Tier 2.
+ *
+ * Give-up is **bounded, not immediate**: the host may spawn MCP servers before
+ * `SessionStart` fires, and the ordering between the two is not guaranteed. So a
+ * proxy retries for up to 5 s while buffering steps in memory, then falls to
+ * Tier 2 and flushes the buffer into a run it owns itself.
+ *
+ * STALENESS. A discovery file outlives its process on a crash. Every read checks
+ * that the recorded pid is still alive (`kill(pid, 0)`) and that the file is not
+ * older than {@link MAX_DISCOVERY_AGE_MS}; a stale file is treated as absent, so
+ * a dead session can never capture a live proxy's steps.
+ *
+ * SECURITY (§9). Files are mode 0600 and carry the loopback bearer token. A local
+ * port that accepts unauthenticated step reports is a local exfiltration channel.
+ */
+/** A discovery file older than this is ignored even if its pid is somehow alive. */
+export declare const MAX_DISCOVERY_AGE_MS: number;
+export interface DiscoveryInfo {
+    url: string;
+    /** Random 32 bytes hex; required on every control-server route. */
+    token: string;
+    sessionId: string;
+    pid: number;
+    startedAt: number;
+    cwd: string;
+}
+export declare function writeDiscovery(info: DiscoveryInfo): string;
+export declare function removeDiscovery(cwd: string): void;
+/**
+ * Read the discovery file for `cwd`, or undefined when there is none, it is
+ * malformed, or it is stale.
+ */
+export declare function readDiscovery(cwd: string): DiscoveryInfo | undefined;
+/**
+ * Resolve the control server for `cwd`, retrying until `timeoutMs` elapses.
+ * `BIR_CONTROL_URL` short-circuits the search (with `BIR_CONTROL_TOKEN` for auth).
+ */
+export declare function resolveControl(cwd: string, timeoutMs: number, pollMs?: number): Promise<DiscoveryInfo | undefined>;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/control/discovery.js

@@ -0,0 +1,123 @@
+/**
+ * discovery — how a proxy finds the control server for its project (Phase 5).
+ *
+ * The control server writes `~/.baseinstrunner/control/<key>.json`, where `<key>`
+ * is `sha256(normalised cwd)[0..16]`. A proxy resolves its control server in this
+ * order:
+ *
+ *   1. `BIR_CONTROL_URL` in the environment — injected into generated config, and
+ *      the only reliable channel for an Agent SDK session, which may not share a
+ *      cwd with anything on disk.
+ *   2. The discovery file for its own cwd.
+ *   3. Give up → Tier 2.
+ *
+ * Give-up is **bounded, not immediate**: the host may spawn MCP servers before
+ * `SessionStart` fires, and the ordering between the two is not guaranteed. So a
+ * proxy retries for up to 5 s while buffering steps in memory, then falls to
+ * Tier 2 and flushes the buffer into a run it owns itself.
+ *
+ * STALENESS. A discovery file outlives its process on a crash. Every read checks
+ * that the recorded pid is still alive (`kill(pid, 0)`) and that the file is not
+ * older than {@link MAX_DISCOVERY_AGE_MS}; a stale file is treated as absent, so
+ * a dead session can never capture a live proxy's steps.
+ *
+ * SECURITY (§9). Files are mode 0600 and carry the loopback bearer token. A local
+ * port that accepts unauthenticated step reports is a local exfiltration channel.
+ */
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { controlDir, discoveryPath, ensureDir } from "./paths.js";
+import { logDetail, errText } from "../util/log.js";
+/** A discovery file older than this is ignored even if its pid is somehow alive. */
+export const MAX_DISCOVERY_AGE_MS = 24 * 60 * 60 * 1000;
+export function writeDiscovery(info) {
+    ensureDir(controlDir());
+    const path = discoveryPath(info.cwd);
+    writeFileSync(path, JSON.stringify(info, null, 2), { mode: 0o600 });
+    return path;
+}
+export function removeDiscovery(cwd) {
+    try {
+        const path = discoveryPath(cwd);
+        if (existsSync(path))
+            unlinkSync(path);
+    }
+    catch {
+        /* best effort */
+    }
+}
+/** True when a pid is still running (or when we cannot tell, which we treat as alive). */
+function pidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM means the process exists but belongs to someone else — still alive.
+        return err.code === "EPERM";
+    }
+}
+/**
+ * Read the discovery file for `cwd`, or undefined when there is none, it is
+ * malformed, or it is stale.
+ */
+export function readDiscovery(cwd) {
+    const path = discoveryPath(cwd);
+    try {
+        if (!existsSync(path))
+            return undefined;
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof parsed.url !== "string" ||
+            typeof parsed.token !== "string" ||
+            typeof parsed.pid !== "number") {
+            return undefined;
+        }
+        if (Date.now() - (parsed.startedAt ?? 0) > MAX_DISCOVERY_AGE_MS) {
+            logDetail("discovery.stale", { path, reason: "too old" });
+            return undefined;
+        }
+        if (!pidAlive(parsed.pid)) {
+            logDetail("discovery.stale", { path, reason: "pid gone", pid: parsed.pid });
+            return undefined;
+        }
+        return { cwd, ...parsed };
+    }
+    catch (err) {
+        logDetail("discovery.unreadable", { path, error: errText(err) });
+        return undefined;
+    }
+}
+/**
+ * Resolve the control server for `cwd`, retrying until `timeoutMs` elapses.
+ * `BIR_CONTROL_URL` short-circuits the search (with `BIR_CONTROL_TOKEN` for auth).
+ */
+export async function resolveControl(cwd, timeoutMs, pollMs = 250) {
+    const envUrl = process.env.BIR_CONTROL_URL;
+    if (envUrl) {
+        // The env channel may still race the server's own startup, so it is verified
+        // against the discovery file when one exists (that is where the token lives).
+        const fromFile = readDiscovery(cwd);
+        return {
+            url: envUrl.replace(/\/+$/, ""),
+            token: process.env.BIR_CONTROL_TOKEN ?? fromFile?.token ?? "",
+            sessionId: fromFile?.sessionId ?? "",
+            pid: fromFile?.pid ?? 0,
+            startedAt: fromFile?.startedAt ?? Date.now(),
+            cwd,
+        };
+    }
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const found = readDiscovery(cwd);
+        if (found)
+            return found;
+        if (Date.now() >= deadline)
+            return undefined;
+        await new Promise((resolve) => {
+            const t = setTimeout(resolve, Math.min(pollMs, Math.max(0, deadline - Date.now())));
+            t.unref?.();
+        });
+    }
+}
+//# sourceMappingURL=discovery.js.map

package/dist/control/ordering.d.ts

@@ -0,0 +1,38 @@
+/**
+ * ordering — the single monotonic `stepIndex` sequence for a run (Phase 5).
+ *
+ * D5's whole point: one counter shared by the hook's built-in steps and every
+ * proxy's MCP steps, so a scenario reads back in true execution order rather
+ * than as three interleaved streams with no common clock.
+ *
+ * WHERE ALLOCATION HAPPENS, AND WHY IT DIFFERS BY SOURCE:
+ *
+ *   - **Built-in steps** are allocated at `PreToolUse`. The hook is their only
+ *     observer, `pre`/`post` are strictly paired, and Claude Code runs built-ins
+ *     one at a time — so allocating at call time preserves selection order and
+ *     nothing can interleave between the pair.
+ *   - **MCP steps** are allocated when the proxy *reports*, i.e. at completion.
+ *     Concurrent `tools/call`s have no meaningful selection order across
+ *     processes, so ordering them by completion is both deterministic and honest
+ *     about what actually happened.
+ *
+ * Steps come in pairs (`tool_selected` then `tool_response`), so the unit of
+ * allocation is a pair — otherwise a concurrent allocation could land *between*
+ * a call and its own result.
+ */
+export interface StepPair {
+    selected: number;
+    response: number;
+}
+export declare class StepIndexAllocator {
+    private counter;
+    /** The next index that would be handed out. */
+    get next(): number;
+    /** Allocate one index (a final answer, a prompt step). */
+    allocate(): number;
+    /** Allocate an adjacent `tool_selected` / `tool_response` pair. */
+    allocatePair(): StepPair;
+    /** Start a new run. */
+    reset(): void;
+}
+//# sourceMappingURL=ordering.d.ts.map

package/dist/control/ordering.js

@@ -0,0 +1,44 @@
+/**
+ * ordering — the single monotonic `stepIndex` sequence for a run (Phase 5).
+ *
+ * D5's whole point: one counter shared by the hook's built-in steps and every
+ * proxy's MCP steps, so a scenario reads back in true execution order rather
+ * than as three interleaved streams with no common clock.
+ *
+ * WHERE ALLOCATION HAPPENS, AND WHY IT DIFFERS BY SOURCE:
+ *
+ *   - **Built-in steps** are allocated at `PreToolUse`. The hook is their only
+ *     observer, `pre`/`post` are strictly paired, and Claude Code runs built-ins
+ *     one at a time — so allocating at call time preserves selection order and
+ *     nothing can interleave between the pair.
+ *   - **MCP steps** are allocated when the proxy *reports*, i.e. at completion.
+ *     Concurrent `tools/call`s have no meaningful selection order across
+ *     processes, so ordering them by completion is both deterministic and honest
+ *     about what actually happened.
+ *
+ * Steps come in pairs (`tool_selected` then `tool_response`), so the unit of
+ * allocation is a pair — otherwise a concurrent allocation could land *between*
+ * a call and its own result.
+ */
+export class StepIndexAllocator {
+    counter = 0;
+    /** The next index that would be handed out. */
+    get next() {
+        return this.counter;
+    }
+    /** Allocate one index (a final answer, a prompt step). */
+    allocate() {
+        return this.counter++;
+    }
+    /** Allocate an adjacent `tool_selected` / `tool_response` pair. */
+    allocatePair() {
+        const selected = this.counter++;
+        const response = this.counter++;
+        return { selected, response };
+    }
+    /** Start a new run. */
+    reset() {
+        this.counter = 0;
+    }
+}
+//# sourceMappingURL=ordering.js.map

package/dist/control/paths.d.ts

@@ -0,0 +1,32 @@
+/**
+ * paths — where BaseInstRunner keeps its state on disk.
+ *
+ * One module so the discovery file, the credentials file and the install sidecar
+ * cannot drift apart, and so tests can redirect all three at once with
+ * `BIR_HOME`. Everything lives under `~/.baseinstrunner` (mode 0700), and no
+ * assumption is made about `$HOME` being set — Windows sets `USERPROFILE`
+ * instead, and `os.homedir()` already knows the difference.
+ */
+/** Root of BaseInstRunner's state. `BIR_HOME` overrides it (tests, sandboxes). */
+export declare function configDir(): string;
+/** Where control servers advertise themselves, one file per project cwd. */
+export declare function controlDir(): string;
+/** The sidecar holding original MCP entries so `bir uninstall` can restore them. */
+export declare function installedPath(): string;
+/** Create a directory with restrictive permissions. Idempotent, never throws. */
+export declare function ensureDir(dir: string, mode?: number): void;
+/**
+ * Separator- and case-normalised form of a path.
+ *
+ * Claude Code stores project keys with forward slashes on Windows while
+ * `process.cwd()` returns backslashes; comparing the literal strings is the
+ * number one cause of "the proxy is installed but never runs" (Phase 7.1). The
+ * same normalisation keys the discovery file, so a proxy started from
+ * `C:\proj` finds the control server registered by a hook reporting `C:/proj`.
+ */
+export declare function normalizePath(p: string): string;
+/** The discovery key for a project directory: `sha256(normalised cwd)[0..16]`. */
+export declare function controlKey(cwd: string): string;
+/** Absolute path of the discovery file for `cwd`. */
+export declare function discoveryPath(cwd: string): string;
+//# sourceMappingURL=paths.d.ts.map