@basein/runner 0.2.12 → 0.3.1

package/dist/config/resolve.d.ts

@@ -8,7 +8,9 @@
  *
  * 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`
+ *   1. **Local**   — `~/.claude.json` → `projects[<project key>].mcpServers`,
+ *                    where the key is the canonical git root (see
+ *                    {@link claudeProjectKey}), not necessarily the cwd
  *   2. **Project** — `<cwd>/.mcp.json` → `mcpServers`
  *   3. **User**    — `~/.claude.json` → top-level `mcpServers`
  *
@@ -26,11 +28,17 @@ export interface StdioServerConfig {
     args?: string[];
     env?: Record<string, string>;
 }
-/** A remote server entry (streamable HTTP or legacy SSE). */
+/**
+ * A remote server entry (streamable HTTP or legacy SSE). `headersHelper` and
+ * `oauth` are Claude Code's own ways to authenticate one; nothing here can
+ * reproduce either, which is why such an entry is never wrapped by default.
+ */
 export interface RemoteServerConfig {
     type: "http" | "sse";
     url: string;
     headers?: Record<string, string>;
+    headersHelper?: string;
+    oauth?: unknown;
 }
 export type McpServerConfig = StdioServerConfig | RemoteServerConfig;
 export type Scope = "local" | "project" | "user" | "explicit";
@@ -51,17 +59,71 @@ export interface ResolveOptions {
 export declare function isRemote(config: McpServerConfig): config is RemoteServerConfig;
 /** Parse a JSON file. `undefined` if absent; throws if present but malformed. */
 export declare function parseJsonFile(path: string): unknown;
-export declare function claudeJsonPath(override?: string): string;
 /**
- * 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.
+ * Parse the text of a JSON file (BOM tolerated). Throws, naming `path`, when
+ * it is not JSON — a file with comments (JSONC) included, which is exactly the
+ * file that must be refused rather than rewritten without its comments.
+ */
+export declare function parseJsonText(raw: string, path: string): unknown;
+/**
+ * The file Claude Code keeps its user and local scopes in.
+ *
+ * `~/.claude.json` — unless `CLAUDE_CONFIG_DIR` is set, when Claude Code reads
+ * `$CLAUDE_CONFIG_DIR/.claude.json` instead (checked against Claude Code
+ * itself). Writing the home-directory file then wraps servers in a file no
+ * session reads: `bir setup` says "wrapped" and nothing is. `BIR_CLAUDE_JSON`
+ * (tests, a second profile) still names it outright. An empty variable counts
+ * as unset, the way Claude Code treats one.
+ */
+export declare function claudeJsonPath(override?: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * `CLAUDE_CONFIG_DIR` when it is set: where Claude Code keeps `.claude.json`,
+ * `settings.json` and the rest of what normally lives in `~/.claude`.
+ */
+export declare function claudeConfigHome(env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * The directory Claude Code keys this cwd's local scope (and its trust and
+ * permission state) under: the canonical git root, else `cwd` itself.
+ */
+export declare function claudeProjectRoot(cwd: string): string;
+/**
+ * The linked worktrees (`git worktree add`) of the repository whose main
+ * checkout is `root`, as directories that still exist.
+ *
+ * Claude Code keys their local scope under `root` too (see
+ * {@link canonicalGitRoot}), so a local-scope server written for `root` also
+ * runs in every one of them — sessions nobody set up, on branches whose
+ * `.mcp.json` may say something else. `bir install` names them, and leaves a
+ * server alone where a worktree's own `.mcp.json` defines it differently.
+ */
+export declare function linkedWorktrees(root: string): string[];
+/** {@link claudeProjectRoot} spelled the way Claude Code spells a `projects` key. */
+export declare function claudeProjectKey(cwd: string, platform?: NodeJS.Platform): string;
+/**
+ * Every existing `projects` key Claude Code could read for this cwd — the
+ * spellings of its canonical root that it wrote (forward slashes on Windows;
+ * both drive-letter cases when both exist) — or, when it has never run here,
+ * the one key it will create. Never a backslash key: Claude Code does not read
+ * one, and writing there is the trap that made entries invisible to `/mcp`.
+ */
+export declare function projectKeysFor(projects: Record<string, unknown> | undefined, cwd: string, platform?: NodeJS.Platform): string[];
+/**
+ * The local scope's servers for `cwd`, as Claude Code sees them: the first key
+ * it reads that holds any. Only when it has no key here at all is a legacy
+ * spelling of `cwd` itself (a backslash key, or the directory rather than its
+ * git root) consulted — so an install made by an older runner is still found
+ * and can be repaired, without reporting entries Claude Code never uses as live.
  */
 export declare function projectScope(projects: Record<string, {
     mcpServers?: Record<string, McpServerConfig>;
 }> | undefined, cwd: string): Record<string, McpServerConfig>;
-/** The key under which Claude Code stores (or would store) this cwd's local scope. */
+/**
+ * The key under which Claude Code stores (or would store) this cwd's local
+ * scope. A key spelled exactly like `cwd` is kept (it is where an older install
+ * put an entry, and where uninstall must look for it); otherwise the key
+ * Claude Code reads. It used to fall back to the raw cwd, which on Windows is a
+ * backslash key nothing ever reads.
+ */
 export declare function projectKeyFor(projects: Record<string, unknown> | undefined, cwd: string): string;
 /** Every MCP server that would be live for `cwd`, with the scope that won. */
 export declare function resolveServers(cwd: string, opts?: ResolveOptions): ResolvedServer[];

package/dist/config/resolve.js

@@ -8,7 +8,9 @@
  *
  * 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`
+ *   1. **Local**   — `~/.claude.json` → `projects[<project key>].mcpServers`,
+ *                    where the key is the canonical git root (see
+ *                    {@link claudeProjectKey}), not necessarily the cwd
  *   2. **Project** — `<cwd>/.mcp.json` → `mcpServers`
  *   3. **User**    — `~/.claude.json` → top-level `mcpServers`
  *
@@ -19,9 +21,9 @@
  * 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 { existsSync, lstatSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { basename, dirname, join, normalize as normalizeNative, resolve as resolvePath } from "node:path";
 import { normalizePath } from "../control/paths.js";
 export function isRemote(config) {
     return (config.type === "http" || config.type === "sse");
@@ -47,6 +49,14 @@ export function parseJsonFile(path) {
     catch {
         return undefined; // absent / unreadable — "not configured"
     }
+    return parseJsonText(raw, path);
+}
+/**
+ * Parse the text of a JSON file (BOM tolerated). Throws, naming `path`, when
+ * it is not JSON — a file with comments (JSONC) included, which is exactly the
+ * file that must be refused rather than rewritten without its comments.
+ */
+export function parseJsonText(raw, path) {
     try {
         return JSON.parse(stripBom(raw));
     }
@@ -63,18 +73,172 @@ function readMcpServers(path, required) {
     }
     return parsed.mcpServers ?? {};
 }
-export function claudeJsonPath(override) {
-    return override ?? process.env.BIR_CLAUDE_JSON ?? join(homedir(), ".claude.json");
+/**
+ * The file Claude Code keeps its user and local scopes in.
+ *
+ * `~/.claude.json` — unless `CLAUDE_CONFIG_DIR` is set, when Claude Code reads
+ * `$CLAUDE_CONFIG_DIR/.claude.json` instead (checked against Claude Code
+ * itself). Writing the home-directory file then wraps servers in a file no
+ * session reads: `bir setup` says "wrapped" and nothing is. `BIR_CLAUDE_JSON`
+ * (tests, a second profile) still names it outright. An empty variable counts
+ * as unset, the way Claude Code treats one.
+ */
+export function claudeJsonPath(override, env = process.env) {
+    if (override)
+        return override;
+    if (env.BIR_CLAUDE_JSON)
+        return env.BIR_CLAUDE_JSON;
+    return join(claudeConfigHome(env) ?? homedir(), ".claude.json");
+}
+/**
+ * `CLAUDE_CONFIG_DIR` when it is set: where Claude Code keeps `.claude.json`,
+ * `settings.json` and the rest of what normally lives in `~/.claude`.
+ */
+export function claudeConfigHome(env = process.env) {
+    return env.CLAUDE_CONFIG_DIR || undefined;
+}
+// ── the local scope's key, as Claude Code computes it ──────────────────────
+//
+// Read out of Claude Code itself rather than guessed, because a local-scope
+// entry written under any other key is silently never used: Claude Code keys
+// `projects` by the project's CANONICAL GIT ROOT when the directory is inside
+// a repository (walking up for a `.git` directory or file; a linked worktree
+// maps to its main checkout), and by the directory itself otherwise — then
+// normalises it and, on Windows, turns every backslash into a forward slash.
+// The drive letter keeps whatever case the launching shell reported, which is
+// why `c:/x` and `C:/x` routinely sit side by side: one per way Claude Code has
+// been started there.
+/** True when `dir` has a `.git` directory or gitfile (not a symlink). */
+function hasGitEntry(dir) {
+    try {
+        const st = lstatSync(join(dir, ".git"));
+        return st.isDirectory() || st.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A linked worktree's main checkout, the way Claude Code resolves it: only when
+ * the gitfile, the `commondir` file and the back-pointing `gitdir` file all
+ * agree. Anything unusual (a submodule, a hand-edited file) keeps `root`.
+ */
+function canonicalGitRoot(root) {
+    try {
+        const dotGit = join(root, ".git");
+        if (!statSync(dotGit).isFile())
+            return root;
+        const text = readFileSync(dotGit, "utf8").trim();
+        if (!text.startsWith("gitdir:"))
+            return root;
+        const gitdir = resolvePath(root, text.slice("gitdir:".length).trim());
+        const commondirFile = join(gitdir, "commondir");
+        if (!existsSync(commondirFile))
+            return root;
+        const common = resolvePath(gitdir, readFileSync(commondirFile, "utf8").trim());
+        if (normalizePath(dirname(gitdir)) !== normalizePath(join(common, "worktrees")))
+            return root;
+        const back = readFileSync(join(gitdir, "gitdir"), "utf8").trim();
+        if (normalizePath(resolvePath(gitdir, back)) !== normalizePath(dotGit))
+            return root;
+        if (basename(common) !== ".git")
+            return hasGitEntry(common) ? root : common;
+        return dirname(common);
+    }
+    catch {
+        return root;
+    }
+}
+/**
+ * The directory Claude Code keys this cwd's local scope (and its trust and
+ * permission state) under: the canonical git root, else `cwd` itself.
+ */
+export function claudeProjectRoot(cwd) {
+    let dir = resolvePath(cwd);
+    for (;;) {
+        if (hasGitEntry(dir))
+            return canonicalGitRoot(dir);
+        const parent = dirname(dir);
+        if (parent === dir)
+            return resolvePath(cwd);
+        dir = parent;
+    }
+}
+/**
+ * The linked worktrees (`git worktree add`) of the repository whose main
+ * checkout is `root`, as directories that still exist.
+ *
+ * Claude Code keys their local scope under `root` too (see
+ * {@link canonicalGitRoot}), so a local-scope server written for `root` also
+ * runs in every one of them — sessions nobody set up, on branches whose
+ * `.mcp.json` may say something else. `bir install` names them, and leaves a
+ * server alone where a worktree's own `.mcp.json` defines it differently.
+ */
+export function linkedWorktrees(root) {
+    const admin = join(root, ".git", "worktrees");
+    let names;
+    try {
+        if (!statSync(join(root, ".git")).isDirectory())
+            return [];
+        names = readdirSync(admin);
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const name of names) {
+        try {
+            const dotGit = resolvePath(join(admin, name), readFileSync(join(admin, name, "gitdir"), "utf8").trim());
+            const dir = dirname(dotGit);
+            if (existsSync(dotGit) && normalizePath(dir) !== normalizePath(root))
+                found.push(dir);
+        }
+        catch {
+            /* a pruned or half-made worktree */
+        }
+    }
+    return found.sort();
+}
+/** {@link claudeProjectRoot} spelled the way Claude Code spells a `projects` key. */
+export function claudeProjectKey(cwd, platform = process.platform) {
+    const root = normalizeNative(claudeProjectRoot(cwd));
+    return platform === "win32" ? root.replace(/\\/g, "/") : root;
+}
+/**
+ * Every existing `projects` key Claude Code could read for this cwd — the
+ * spellings of its canonical root that it wrote (forward slashes on Windows;
+ * both drive-letter cases when both exist) — or, when it has never run here,
+ * the one key it will create. Never a backslash key: Claude Code does not read
+ * one, and writing there is the trap that made entries invisible to `/mcp`.
+ */
+export function projectKeysFor(projects, cwd, platform = process.platform) {
+    const canonical = claudeProjectKey(cwd, platform);
+    const want = normalizePath(canonical);
+    const found = Object.keys(projects ?? {}).filter((key) => normalizePath(key) === want && !(platform === "win32" && key.includes("\\")));
+    if (found.length === 0)
+        return [canonical];
+    // The exact canonical spelling first, so single-key callers use it.
+    return found.sort((a, b) => Number(b === canonical) - Number(a === canonical));
 }
 /**
- * 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.
+ * The local scope's servers for `cwd`, as Claude Code sees them: the first key
+ * it reads that holds any. Only when it has no key here at all is a legacy
+ * spelling of `cwd` itself (a backslash key, or the directory rather than its
+ * git root) consulted — so an install made by an older runner is still found
+ * and can be repaired, without reporting entries Claude Code never uses as live.
  */
 export function projectScope(projects, cwd) {
     if (!projects)
         return {};
+    const readable = projectKeysFor(projects, cwd).filter((key) => key in projects);
+    if (readable.length > 0) {
+        for (const key of readable) {
+            const servers = projects[key]?.mcpServers;
+            if (servers && Object.keys(servers).length > 0)
+                return servers;
+        }
+        return projects[readable[0]]?.mcpServers ?? {};
+    }
     const exact = projects[cwd]?.mcpServers;
     if (exact && Object.keys(exact).length > 0)
         return exact;
@@ -86,18 +250,25 @@ export function projectScope(projects, cwd) {
     }
     return exact ?? {};
 }
-/** The key under which Claude Code stores (or would store) this cwd's local scope. */
+/**
+ * The key under which Claude Code stores (or would store) this cwd's local
+ * scope. A key spelled exactly like `cwd` is kept (it is where an older install
+ * put an entry, and where uninstall must look for it); otherwise the key
+ * Claude Code reads. It used to fall back to the raw cwd, which on Windows is a
+ * backslash key nothing ever reads.
+ */
 export function projectKeyFor(projects, cwd) {
-    if (!projects)
-        return cwd;
-    if (cwd in projects)
+    if (projects && cwd in projects)
         return cwd;
+    const keys = projectKeysFor(projects, cwd);
+    if (projects && keys[0] in projects)
+        return keys[0];
     const want = normalizePath(cwd);
-    for (const key of Object.keys(projects)) {
+    for (const key of Object.keys(projects ?? {})) {
         if (normalizePath(key) === want)
             return key;
     }
-    return cwd;
+    return keys[0];
 }
 /** Every MCP server that would be live for `cwd`, with the scope that won. */
 export function resolveServers(cwd, opts = {}) {

package/dist/control/client.d.ts

@@ -23,6 +23,19 @@ export interface ProxyWork {
     arguments: unknown;
     timeoutMs: number;
 }
+/** What one long-poll came back with (see {@link ControlClient.pollWork}). */
+export interface PollOutcome {
+    /** False when the control server could not be reached, or refused us. */
+    reachable: boolean;
+    work?: ProxyWork;
+    /**
+     * The server said calculated replay is off here (`{ replay: false }`). A
+     * proxy drops to its idle pace (one poll every 30 s) rather than ask again
+     * four times a second — but does not stop: replay is turned back on by a
+     * restart that never makes a bound proxy register again.
+     */
+    replayOff?: boolean;
+}
 /**
  * Who a proxy is, sent with every register, poll and step report. The control
  * server uses it to run a session's replay steps on that session's own upstream
@@ -65,9 +78,18 @@ export declare class ControlClient {
      * with a small delay so a dead server is not busy-looped.
      */
     poll(serverName: string, holdMs: number): Promise<ProxyWork | undefined>;
+    /**
+     * {@link poll}, with enough of the answer to pace the loop: whether the
+     * server was reachable at all, and whether it said replay is off. An empty
+     * answer that came back at once means the server is not holding polls for
+     * us, and the caller backs off.
+     */
+    pollWork(serverName: string, holdMs: number): Promise<PollOutcome>;
     /** 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;
+    /** One HTTP exchange. Never throws; `ok: false` covers refused, timed out and non-2xx. */
+    private exchange;
 }
 //# sourceMappingURL=client.d.ts.map

package/dist/control/client.js

@@ -47,8 +47,20 @@ export class ControlClient {
      * with a small delay so a dead server is not busy-looped.
      */
     async poll(serverName, holdMs) {
-        const body = (await this.request("POST", "/proxy/poll", { ...this.identity, serverName, holdMs }, holdMs + 10_000));
-        return body?.work;
+        return (await this.pollWork(serverName, holdMs)).work;
+    }
+    /**
+     * {@link poll}, with enough of the answer to pace the loop: whether the
+     * server was reachable at all, and whether it said replay is off. An empty
+     * answer that came back at once means the server is not holding polls for
+     * us, and the caller backs off.
+     */
+    async pollWork(serverName, holdMs) {
+        const outcome = await this.exchange("POST", "/proxy/poll", { ...this.identity, serverName, holdMs }, holdMs + 10_000);
+        if (!outcome.ok)
+            return { reachable: false };
+        const body = outcome.body;
+        return { reachable: true, work: body?.work, replayOff: body?.replay === false || undefined };
     }
     /** Hand back one dispatched call's result, or the reason it could not run. */
     async result(workId, result, error) {
@@ -58,6 +70,11 @@ export class ControlClient {
         return this.request("POST", path, body);
     }
     async request(method, path, body, timeoutMs = this.timeoutMs) {
+        const outcome = await this.exchange(method, path, body, timeoutMs);
+        return outcome.ok ? outcome.body : undefined;
+    }
+    /** One HTTP exchange. Never throws; `ok: false` covers refused, timed out and non-2xx. */
+    async exchange(method, path, body, timeoutMs = this.timeoutMs) {
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), timeoutMs);
         timer.unref?.();
@@ -73,21 +90,23 @@ export class ControlClient {
             });
             if (!res.ok) {
                 logDetail("control.http_error", { path, status: res.status });
-                return undefined;
+                // Drain, so the connection is released rather than held to its timeout.
+                await res.text().catch(() => undefined);
+                return { ok: false, status: res.status };
             }
             const text = await res.text();
             if (!text)
-                return {};
+                return { ok: true, status: res.status, body: {} };
             try {
-                return JSON.parse(text);
+                return { ok: true, status: res.status, body: JSON.parse(text) };
             }
             catch {
-                return {};
+                return { ok: true, status: res.status, body: {} };
             }
         }
         catch (err) {
             logDetail("control.unreachable", { path, error: errText(err) });
-            return undefined;
+            return { ok: false };
         }
         finally {
             clearTimeout(timer);

package/dist/control/correlation.d.ts

@@ -10,21 +10,32 @@
  *   - the **proxy** contributes the true upstream result, `isError`,
  *     `structuredContent` and real execution duration.
  *
- * MECHANISM. At `PreToolUse` the hook answers `permissionDecision: "allow"` with
+ * MECHANISM. At `PreToolUse` the hook may answer 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.
  *
+ * NOT BY DEFAULT. Carrying an id means answering `allow`, and `allow` skips
+ * the permission prompt the user would otherwise have seen for that call. So
+ * the control server injects only where that changes nothing (a session in
+ * `bypassPermissions` mode, a replay-pinned step) or where the operator opted
+ * in (`BIR_CORRELATION_DECISION=allow`); everywhere else the hook stays silent
+ * and the report joins by fingerprint — below.
+ *
  * 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 FINGERPRINT JOIN — the default, and all `--no-correlation` uses — matches
+ * on `(serverName, toolName, hash(args))`, the args hashed *raw*, as the model
+ * wrote them, before any redaction or clipping (the proxy sends that hash as
+ * `argsFingerprint`; an older proxy's report is hashed as reported), within
+ * the time a user may take to approve the call. 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__";
@@ -42,6 +53,13 @@ export interface ProxyStepReport {
     qualifiedName: string;
     /** Post-redaction. */
     args: unknown;
+    /**
+     * The fingerprint join key over the call's *raw* arguments, taken by the
+     * proxy before redaction and clipping (proxy/intercept.ts). `args` above is
+     * what is recorded, and hashing it would miss the hook-side twin whenever
+     * redaction or clipping changed anything. Absent from older proxies.
+     */
+    argsFingerprint?: string;
     /** Whole CallToolResult, post-redaction and truncation. */
     result?: unknown;
     isError: boolean;