@basein/runner 0.3.25 → 0.3.27

package/dist/replay/reads-only.js

@@ -0,0 +1,161 @@
+/**
+ * reads-only — whether one call of the agent's only looks, and changes nothing.
+ *
+ * WHY THE RUNNER ASKS (B2 is11.md, 2026-11-11). A direct plan is announced
+ * with "call run_scenario before any other tool", and a first call that is
+ * not `run_scenario` used to retire it on the spot (control/server.ts). The
+ * rule is there for one danger: a model that has no `run_scenario` makes its
+ * own calls, and a divergence would then run every step, writes included,
+ * inside a hook nobody approves. But the call that retired the plan in is11
+ * was the agent reading its own notes file: it had seen another person's name
+ * in the note (Olga, the recording's; the request said Carlos) and checked
+ * first. The plan would have done the task right — its steps take the person
+ * from the request — and the turn cost a full agent run.
+ *
+ * So a call that only looks no longer retires a direct plan: it runs as the
+ * agent wrote it, and the plan waits, still announced, for `run_scenario`.
+ * The first call that may change something still retires it, running nothing
+ * (and nothing ever runs in a hook in its place): a plan run after the agent
+ * changed something itself could do the same work twice.
+ *
+ * WHEN IN DOUBT, IT IS A CHANGE. A call judged "only looks" that does change
+ * something leaves a plan armed that could then repeat that change; a change
+ * judged a change only ends a replay early, as every call did before. So:
+ *
+ *  - Claude Code's built-ins by name: the reading ones only look, every other
+ *    built-in (a sub-agent, an edit, an unknown new tool) is a change;
+ *  - `Bash` by its command ({@link commandReadsOnly}), and `PowerShell` never;
+ *  - an MCP tool by what its own server says of it (`annotations`), else by
+ *    its name: a reading word and no writing word.
+ *
+ * The same rule as the service's `readsOnly` (correctionCheck.ts, AC13), kept
+ * in step by hand, stricter where a wrong "only looks" costs more here: a
+ * command substitution, a process substitution or an `awk` `system(` makes a
+ * command a change.
+ */
+/** Claude Code's built-ins that only read. `ToolSearch` and `TodoWrite` are housekeeping (record/housekeeping.ts). */
+const READ_BUILTINS = new Set([
+    "Read",
+    "Grep",
+    "Glob",
+    "LS",
+    "WebFetch",
+    "WebSearch",
+    "NotebookRead",
+    "TaskOutput",
+    "BashOutput",
+    // The conversation's own: a question to the person, plan mode in or out.
+    // Nothing outside the conversation changes, and the plan may still be
+    // what the person says yes to.
+    "AskUserQuestion",
+    "EnterPlanMode",
+    "ExitPlanMode",
+]);
+// Not `query`, `select` or `check`: a database query, a selected option, a
+// check-in can change something.
+const READ_WORDS = new Set([
+    "list", "get", "search", "find", "read", "fetch", "lookup", "count", "view", "show",
+    "describe", "retrieve", "browse", "peek", "inspect", "snapshot",
+]);
+/**
+ * A word that may change something: a name holding one writes, whatever else
+ * it says (`get_or_create_contact`, `find_and_replace`). Some are nouns too
+ * (`get_schedule`): such a look is then taken for a change, which only ends a
+ * replay early, never lets a change through.
+ */
+const WRITE_WORDS = new Set([
+    "create", "add", "set", "update", "upsert", "insert", "put", "post", "send", "delete",
+    "remove", "mark", "replace", "archive", "move", "assign", "book", "cancel", "write",
+    "edit", "modify", "save", "submit", "approve", "reject", "close", "open", "merge",
+    "push", "publish", "upload", "invite", "schedule", "reply", "forward", "transfer",
+    "pay", "refund", "notify", "run", "execute", "exec", "apply", "reset", "start", "stop",
+    "kill", "enable", "disable", "grant", "revoke", "rename", "tag", "label", "comment",
+]);
+/** A tool name's words: `getJiraIssue` → get, jira, issue; `calendar_search_events` → calendar, search, events. */
+function nameWords(name) {
+    return name
+        .replace(/([a-z\d])([A-Z])/g, "$1 $2")
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+        .toLowerCase()
+        .split(/[^a-z\d]+/)
+        .filter(Boolean);
+}
+/**
+ * Whether this call only looks. `toolInput` is the hook's `tool_input` (only a
+ * `Bash` call's `command` is read from it); `hints` is what the tool's own
+ * server listed for it, when it listed anything.
+ */
+export function readsOnlyCall(toolName, toolInput, hints) {
+    if (toolName === "Bash") {
+        const command = toolInput?.command;
+        return typeof command === "string" && commandReadsOnly(command);
+    }
+    if (READ_BUILTINS.has(toolName))
+        return true;
+    // Every other built-in — Write, Edit, PowerShell, a sub-agent, one added
+    // after this list was written — may change something.
+    if (!toolName.startsWith("mcp__"))
+        return false;
+    // A server's word beats any guess from the name.
+    if (hints?.readOnlyHint === false || hints?.destructiveHint === true)
+        return false;
+    if (hints?.readOnlyHint === true)
+        return true;
+    const words = nameWords(toolName.replace(/^mcp__.+?__/, ""));
+    if (words.some((w) => WRITE_WORDS.has(w)))
+        return false;
+    return words.some((w) => READ_WORDS.has(w));
+}
+/** Commands that only look (`ls`, `cat`, `grep …`). */
+const READ_COMMANDS = new Set([
+    "ls", "dir", "cat", "type", "head", "tail", "less", "more", "grep", "rg", "egrep", "fgrep",
+    "find", "wc", "pwd", "echo", "printf", "date", "whoami", "which", "where", "stat", "file",
+    "du", "df", "tree", "jq", "sort", "uniq", "cut", "awk", "diff", "cmp", "basename", "dirname",
+    "realpath", "readlink", "true", "false", "test", "ps", "uname", "hostname", "id", "nproc",
+    "free", "uptime", "node --version", "npm --version",
+]);
+const READ_GIT = new Set([
+    "status", "log", "diff", "show", "branch", "rev-parse", "ls-files", "blame", "remote",
+    "describe", "config --get", "grep", "shortlog", "tag --list",
+]);
+/**
+ * Whether a shell command only looks: every part of it is a looking command,
+ * nothing is written to a file, and nothing runs code it does not show.
+ */
+export function commandReadsOnly(command) {
+    const text = command.trim();
+    if (!text)
+        return false;
+    // Code that runs out of sight: a substitution (`$(…)`, backticks), a
+    // process substitution, awk's `system(`.
+    if (/`|\$\(|<\(|>\(|\bsystem\s*\(/.test(text))
+        return false;
+    // A redirect into a file (not into /dev/null, not 2>&1), tee, or an in-place edit changes something.
+    if (/(^|[^0-9&])>{1,2}\s*(?!&|\/dev\/null)\S/.test(text) ||
+        /&>{1,2}\s*(?!\/dev\/null)\S/.test(text) ||
+        /\btee\b/.test(text) ||
+        /\bsed\b[^|;&]*\s(-i|--in-place)/.test(text)) {
+        return false;
+    }
+    if (/\bfind\b[^|;&]*\s-(delete|exec|execdir|ok|okdir|fprint|fprintf|fls)\b/.test(text))
+        return false;
+    // A job sent to the background (`cmd &`): not something this reads.
+    if (/(?<![>&])&(?![>&])/.test(text.replace(/&&/g, "")))
+        return false;
+    const parts = text
+        .split(/\|\||&&|[|;\n]/)
+        .map((p) => p.trim())
+        .filter(Boolean);
+    if (parts.length === 0)
+        return false;
+    return parts.every((part) => {
+        const words = part.replace(/^(\w+=\S+\s+)+/, "").split(/\s+/);
+        const cmd = (words[0] ?? "").replace(/^.*[\\/]/, "");
+        if (cmd === "git")
+            return READ_GIT.has(words[1] ?? "") || READ_GIT.has(`${words[1] ?? ""} ${words[2] ?? ""}`);
+        if (cmd === "sed")
+            return !/\s(-i|--in-place)/.test(part);
+        return READ_COMMANDS.has(cmd) || READ_COMMANDS.has(`${cmd} ${words[1] ?? ""}`);
+    });
+}
+//# sourceMappingURL=reads-only.js.map

package/dist/replay/safety.js

@@ -49,7 +49,30 @@ const WRITE_BUILTINS = new Set(["Edit", "MultiEdit", "Write", "NotebookEdit"]);
  * with the server.
  */
 const MCP_SHELL_WORD = /(?:^|[_.-])(?:shell|bash|sh|zsh|ssh|exec|execute|command|cmd|terminal|powershell|pwsh)(?:$|[_.-])/i;
-const MCP_COMMAND_WORD = /(?:^|[_.-])(?:sql|tsql|query|exec|execute|shell|bash|sh|zsh|ssh|command|cmd|script|eval|terminal|psql|mysql|mssql|sqlite|duckdb|postgres|postgresql|powershell|pwsh)(?:$|[_.-])/i;
+const MCP_COMMAND_WORD = /(?:^|[_.-])(?:sql|tsql|query|exec|execute|shell|bash|sh|zsh|ssh|command|cmd|script|eval|cypher|terminal|psql|mysql|mssql|sqlite|duckdb|postgres|postgresql|powershell|pwsh)(?:$|[_.-])/i;
+/**
+ * A tool whose input is code runs it as surely as a shell runs a command:
+ * `run_code`, `execute_python`, `code_interpreter`, `python_repl`, a
+ * `javascript_tool`, `browser_evaluate`, `evaluate_script`. Known by the words
+ * that say the code is run, and not by the language's name alone: as words of
+ * their own, `code`, `python`, `javascript` and `evaluate` made a command of
+ * `search_code`, `get_postal_code`, `send_verification_code`, `evaluate_answer`
+ * and of every tool of a `python-docs` or `claude-code` server — and with one
+ * such step every value of the plan was held to a command's rules, so a query
+ * with a quote in it handed the plan over. Whole words only, as above:
+ * `decode_token` and a `barcode` have the letters of `code` and are not it.
+ */
+const MCP_CODE_RUNNER = new RegExp(`(?:^|[_.-])(?:${[
+    "(?:run|exec|execute|eval)[_.-](?:code|python|py|javascript|js|typescript|ts|node)",
+    "(?:code|python|py|javascript|js|typescript|node)[_.-](?:run|runner|exec|execute|executor|eval|interpreter|repl)",
+    "(?:javascript|js)[_.-]tool",
+    "(?:browser|page|puppeteer|playwright|frame|tab|chrome|devtools)[_.-]evaluate",
+    "evaluate[_.-](?:script|js|javascript|expression|code)",
+].join("|")})(?:$|[_.-])`, "i");
+/** Whether a name, split into words ({@link nameWords}), says its input is run. */
+function saysRun(words) {
+    return MCP_COMMAND_WORD.test(words) || MCP_CODE_RUNNER.test(words);
+}
 /**
  * A tool or server name as delimited words: camelCase, PascalCase and acronym
  * runs are split with `_`, so `executeSql` reads as `execute_Sql`, `runSQL` as
@@ -66,6 +89,18 @@ function mcpNameSays(toolName, words) {
         return false;
     return words.test(nameWords(mcp.toolName)) || words.test(nameWords(mcp.serverName));
 }
+/**
+ * Whether an MCP tool's name, its server's, or the two read together say its
+ * input is run: `mcp__python__run` says it only with both (`python_run`).
+ */
+function mcpRunsInput(toolName) {
+    const mcp = parseQualifiedName(toolName);
+    if (!mcp)
+        return false;
+    const tool = nameWords(mcp.toolName);
+    const server = nameWords(mcp.serverName);
+    return saysRun(tool) || saysRun(server) || MCP_CODE_RUNNER.test(`${server}_${tool}`);
+}
 /**
  * Characters and sequences that end a quoted string or begin another command
  * in a POSIX shell, PowerShell or SQL. Deliberately wide: an apostrophe in a
@@ -105,13 +140,13 @@ export function sinkOf(toolName, host) {
             return "command";
         if (host.write?.includes(name))
             return "write";
-        return plainNameSays(name, MCP_COMMAND_WORD) ? "command" : undefined;
+        return saysRun(nameWords(name)) ? "command" : undefined;
     }
     if (SHELL_BUILTINS.has(name))
         return "command";
     if (WRITE_BUILTINS.has(name))
         return "write";
-    return mcpNameSays(name, MCP_COMMAND_WORD) ? "command" : undefined;
+    return mcpRunsInput(name) ? "command" : undefined;
 }
 /** Whether this tool's input is run or written: a shell, a file edit, a query. */
 export function isCommandSink(toolName) {
@@ -189,8 +224,11 @@ const SQL_BOOLEAN_WORD = /\b(?:or|and|union)\b/gi;
  * keeps it.
  */
 function offShape(value, sample) {
-    // A number stays a number: `1 OR 1=1` is not a user id.
-    if (typeof sample === "number") {
+    // A number stays a number: `1 OR 1=1` is not a user id. A number kept as
+    // text (`"42"`) is a number all the same: with that sample, `"… WHERE
+    // user_id = " + parameters.v` took the value `user_id` and matched every
+    // row, where the sample 42 refused it.
+    if (typeof sample === "number" || (typeof sample === "string" && NUMERIC.test(sample))) {
         if (typeof value === "number")
             return Number.isFinite(value) ? undefined : String(value);
         if (typeof value !== "string" || !NUMERIC.test(value))

package/dist/upstream/http-client.d.ts

@@ -41,12 +41,14 @@
  *      `initialize` got a 405 and the server showed as failed every session).
  *      A stream that ends — cleanly or not — is noticed, the requests riding it
  *      are answered, and it is re-established with backoff; the new session is
- *      re-initialised with the host's own `initialize` before anything else.
+ *      re-initialised with the host's own `initialize` before anything else,
+ *      and a stream whose re-initialisation fails is a reconnect that failed.
  *   4. **Session expiry is survivable.** A 404 to a request that carried a
  *      session means the server forgot us (a redeploy, an idle timeout). The
  *      spec says start a new session; the proxy does it for the host — replays
  *      the host's cached `initialize` under a `bir:` id, sends `initialized`,
- *      and retries the request once.
+ *      and retries the request once. A replay that fails is tried again when
+ *      the next request meets the same 404.
  *   5. **No timeout shorter than the host's.** The transport (http-transport.ts)
  *      bounds the connect only; how long a tool may take is Claude Code's call,
  *      and its cancellation reaches the server immediately (rule 2). What no
@@ -200,7 +202,8 @@ export declare class HttpUpstreamClient extends BaseUpstreamClient {
     /**
      * Replay the host's `initialize` (under a `bir:` id) and `initialized`.
      * `news`: say it on stderr when it worked — after a forgotten session or an
-     * outage; after a routine reconnect it is detail. A failure is always said.
+     * outage; after a routine reconnect it is detail. A failure is said, unless
+     * `failureSaid`: it is one more of an outage whose first failure was.
      */
     private reinitialize;
     /**

package/dist/upstream/http-client.js

@@ -41,12 +41,14 @@
  *      `initialize` got a 405 and the server showed as failed every session).
  *      A stream that ends — cleanly or not — is noticed, the requests riding it
  *      are answered, and it is re-established with backoff; the new session is
- *      re-initialised with the host's own `initialize` before anything else.
+ *      re-initialised with the host's own `initialize` before anything else,
+ *      and a stream whose re-initialisation fails is a reconnect that failed.
  *   4. **Session expiry is survivable.** A 404 to a request that carried a
  *      session means the server forgot us (a redeploy, an idle timeout). The
  *      spec says start a new session; the proxy does it for the host — replays
  *      the host's cached `initialize` under a `bir:` id, sends `initialized`,
- *      and retries the request once.
+ *      and retries the request once. A replay that fails is tried again when
+ *      the next request meets the same 404.
  *   5. **No timeout shorter than the host's.** The transport (http-transport.ts)
  *      bounds the connect only; how long a tool may take is Claude Code's call,
  *      and its cancellation reaches the server immediately (rule 2). What no
@@ -72,7 +74,7 @@
  * recovery, a session the server forgot, and a stream that keeps dropping as
  * soon as it opens (once an hour per server at most).
  */
-import { readFrames } from "../jsonrpc/framing.js";
+import { readFrames, receivedText, rememberText } from "../jsonrpc/framing.js";
 import { paramsObject } from "../jsonrpc/types.js";
 import { logDetail, logEvery, logLine, logOnce, errText } from "../util/log.js";
 import { BaseUpstreamClient, BIR_ID_PREFIX, isBirId } from "./client.js";
@@ -341,7 +343,11 @@ export class HttpUpstreamClient extends BaseUpstreamClient {
                 accept: "application/json, text/event-stream",
                 ...this.sessionHeaders(method === "initialize"),
                 ...this.headers,
-            }, JSON.stringify(msg), controller.signal);
+            }, 
+            // The host's own line when this is the message as the relay read it
+            // (jsonrpc/framing.ts): serialised again, an integer past 2^53 in a
+            // tool's arguments reached the server rounded.
+            receivedText(msg) ?? JSON.stringify(msg), controller.signal);
         }
         catch (err) {
             clearTimeout(abandonTimer);
@@ -516,8 +522,16 @@ export class HttpUpstreamClient extends BaseUpstreamClient {
         if (Array.isArray(parsed))
             for (const item of parsed)
                 this.deliver(item);
-        else
+        else {
+            // One message, and this is its text: the relay writes it to the host as
+            // the server wrote it rather than as JavaScript read it (framing.ts).
+            // Without the white space around it — a body often ends in a newline —
+            // and only when it is one line; a batch's members have no text of their
+            // own, and are serialised as before.
+            if (parsed && typeof parsed === "object")
+                rememberText(parsed, raw.trim());
             this.deliver(parsed);
+        }
         return true;
     }
     /** Hand one inbound JSON-RPC message to the relay (or to a `bir:` waiter). */
@@ -601,7 +615,18 @@ export class HttpUpstreamClient extends BaseUpstreamClient {
             if (this.transport === "http") {
                 this.sessionId = undefined;
                 this.resetStandingStream();
-                return this.reinitialize();
+                if (await this.reinitialize())
+                    return true;
+                // No new session: a 503 from an instance still starting, a network
+                // error, no answer in time. Left without an id, every later request
+                // went out bare, the server answered 400 or 404, and none of that
+                // read as "forgotten" any more — errors for the rest of the host's
+                // session, with the proxy up. Holding the forgotten id again makes
+                // the next request's 404 start another attempt. An id this attempt
+                // was handed is dropped with it: its handshake never completed.
+                if (!this.dead)
+                    this.sessionId = staleKey;
+                return false;
             }
             // Legacy: the session *is* the event stream. Drop it and open a new one;
             // reconnect() replays the handshake. A reconnect already under way (the
@@ -634,9 +659,10 @@ export class HttpUpstreamClient extends BaseUpstreamClient {
     /**
      * Replay the host's `initialize` (under a `bir:` id) and `initialized`.
      * `news`: say it on stderr when it worked — after a forgotten session or an
-     * outage; after a routine reconnect it is detail. A failure is always said.
+     * outage; after a routine reconnect it is detail. A failure is said, unless
+     * `failureSaid`: it is one more of an outage whose first failure was.
      */
-    async reinitialize(news = true) {
+    async reinitialize(news = true, failureSaid = false) {
         if (this.initParams === undefined || this.dead)
             return false;
         this.reinitCount += 1;
@@ -663,7 +689,10 @@ export class HttpUpstreamClient extends BaseUpstreamClient {
             return false;
         if (!reply || !("result" in reply)) {
             const error = reply ? paramsObject(reply.error).message : "no answer";
-            logLine("upstream.reinitialize_failed", { server: this.label, error: String(error ?? "error") });
+            (failureSaid ? logDetail : logLine)("upstream.reinitialize_failed", {
+                server: this.label,
+                error: String(error ?? "error"),
+            });
             return false;
         }
         this.noteProtocolVersion(reply.result);
@@ -856,15 +885,27 @@ export class HttpUpstreamClient extends BaseUpstreamClient {
                 return false;
             }
             const recovered = this.reconnectFailures > 0;
+            // A new event stream is a new, uninitialised session: replay the host's
+            // handshake before anything else is let through. Until that has worked
+            // the reconnect has not: counted as done on the stream alone, a replay
+            // the server refused (it was still starting) left every later request
+            // posted to a session nobody had initialised, and nothing ever tried
+            // again. So the stream is dropped and the attempt counts as failed —
+            // backoff, and the next request pulls a new one forward.
+            if (this.initParams !== undefined && !(await this.reinitialize(recovered || afterExpiry, recovered))) {
+                if (this.dead)
+                    return false;
+                this.reconnectFailures += 1;
+                this.onSseStreamLost(this.generation, "re-initialise failed", true);
+                this.streamAbort?.abort();
+                this.scheduleReconnect();
+                return false;
+            }
             (recovered ? logLine : logDetail)("upstream.stream_reconnected", {
                 server: this.label,
                 failedAttempts: this.reconnectFailures,
             });
             this.reconnectFailures = 0;
-            // A new event stream is a new, uninitialised session: replay the host's
-            // handshake before anything else is let through.
-            if (this.initParams !== undefined)
-                await this.reinitialize(recovered || afterExpiry);
             return true;
         })();
         this.connecting = attempt;

package/dist/upstream/stdio-client.d.ts

@@ -22,6 +22,7 @@
  * {@link StdioUpstreamClient.shutdown} closes stdin first (the MCP-spec way to
  * ask a server to exit), waits briefly, and only then kills the whole tree.
  */
+import { type ChildProcessWithoutNullStreams } from "node:child_process";
 import { type JsonRpcMessage } from "../jsonrpc/types.js";
 import { BaseUpstreamClient } from "./client.js";
 export interface StdioUpstreamOptions {
@@ -80,6 +81,12 @@ export declare function whichSync(command: string, env?: NodeJS.ProcessEnv): str
  * On POSIX this is the identity. On Windows a batch file is wrapped in `cmd.exe`.
  */
 export declare function resolveCommand(command: string, args: string[], env?: NodeJS.ProcessEnv): ResolvedCommand;
+/**
+ * Kill `child` and everything it started. On Windows that takes `taskkill /T`
+ * (a plain kill terminates one process: `cmd.exe`, not the server behind it);
+ * elsewhere SIGTERM, then SIGKILL. Bounded; never throws.
+ */
+export declare function killTree(child: ChildProcessWithoutNullStreams): Promise<void>;
 export declare class StdioUpstreamClient extends BaseUpstreamClient {
     readonly ready: Promise<void>;
     private child?;

package/dist/upstream/stdio-client.js

@@ -161,7 +161,7 @@ function waitForExit(child, ms) {
  * (a plain kill terminates one process: `cmd.exe`, not the server behind it);
  * elsewhere SIGTERM, then SIGKILL. Bounded; never throws.
  */
-async function killTree(child) {
+export async function killTree(child) {
     const pid = child.pid;
     if (pid === undefined)
         return;

package/dist/util/atomic-write.d.ts

@@ -19,11 +19,19 @@
  *   - a symlinked target (dotfile managers do this to ~/.claude.json) must keep
  *     being a symlink, so the rename goes to the link's real target.
  *
- * The existing file's mode is kept; `mode` applies to a new file.
+ * The existing file's mode is kept; `mode` applies to a new file, and to an
+ * existing one too with `replaceMode`.
  */
 export interface AtomicWriteOptions {
     /** Mode for a file that does not exist yet. An existing file keeps its own. */
     mode?: number;
+    /**
+     * `mode` for an existing file as well: a file a credential goes in. Kept,
+     * the old file's mode went to the new one, and when the old file was not
+     * ours to chmod first (root's 0644, after `sudo claude`), the token went
+     * into a file that is ours and readable by every account.
+     */
+    replaceMode?: boolean;
 }
 export declare function writeFileAtomic(path: string, data: string | Uint8Array, opts?: AtomicWriteOptions): void;
 //# sourceMappingURL=atomic-write.d.ts.map

package/dist/util/atomic-write.js

@@ -19,7 +19,8 @@
  *   - a symlinked target (dotfile managers do this to ~/.claude.json) must keep
  *     being a symlink, so the rename goes to the link's real target.
  *
- * The existing file's mode is kept; `mode` applies to a new file.
+ * The existing file's mode is kept; `mode` applies to a new file, and to an
+ * existing one too with `replaceMode`.
  */
 import { chmodSync, lstatSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
 import { randomBytes } from "node:crypto";
@@ -42,11 +43,13 @@ function resolveTarget(path) {
 export function writeFileAtomic(path, data, opts = {}) {
     const target = resolveTarget(path);
     let mode = opts.mode;
-    try {
-        mode = statSync(target).mode & 0o777;
-    }
-    catch {
-        /* new file */
+    if (!(opts.replaceMode && mode !== undefined)) {
+        try {
+            mode = statSync(target).mode & 0o777;
+        }
+        catch {
+            /* new file */
+        }
     }
     const tmp = join(dirname(target), `.${basename(target)}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`);
     try {

package/dist/util/service-health.d.ts

@@ -35,6 +35,13 @@ export declare const MAX_COOLDOWN_MS = 60000;
  * and never answers, holding a socket and a chain slot the whole time.
  */
 export declare const DEFAULT_SERVICE_TIMEOUT_MS = 10000;
+/**
+ * The longest delay a Node timer takes. Given more, `setTimeout` warns and
+ * waits 1 ms instead — so `BIR_SERVICE_TIMEOUT_MS=3000000000`, set to switch
+ * the timeout off, ended every request at once. Every delay that comes from
+ * the environment or from a caller is held to this.
+ */
+export declare const MAX_TIMER_MS = 2147483647;
 export declare function serviceTimeoutMs(): number;
 export interface HealthSnapshot {
     /** False while a cool-down is running: hot paths do not wait. */

package/dist/util/service-health.js

@@ -36,9 +36,16 @@ export const MAX_COOLDOWN_MS = 60_000;
  * and never answers, holding a socket and a chain slot the whole time.
  */
 export const DEFAULT_SERVICE_TIMEOUT_MS = 10_000;
+/**
+ * The longest delay a Node timer takes. Given more, `setTimeout` warns and
+ * waits 1 ms instead — so `BIR_SERVICE_TIMEOUT_MS=3000000000`, set to switch
+ * the timeout off, ended every request at once. Every delay that comes from
+ * the environment or from a caller is held to this.
+ */
+export const MAX_TIMER_MS = 2_147_483_647;
 export function serviceTimeoutMs() {
     const n = Number(process.env.BIR_SERVICE_TIMEOUT_MS);
-    return Number.isFinite(n) && n > 0 ? n : DEFAULT_SERVICE_TIMEOUT_MS;
+    return Number.isFinite(n) && n > 0 ? Math.min(n, MAX_TIMER_MS) : DEFAULT_SERVICE_TIMEOUT_MS;
 }
 export class ServiceHealth {
     failures = 0;
@@ -170,7 +177,7 @@ export async function awaitWithin(pending, budgetMs, what, health = serviceHealt
         const winner = await Promise.race([
             pending,
             new Promise((resolve) => {
-                timer = setTimeout(() => resolve(timedOut), budgetMs);
+                timer = setTimeout(() => resolve(timedOut), Math.min(budgetMs, MAX_TIMER_MS));
                 timer.unref?.();
             }),
         ]);
@@ -197,7 +204,7 @@ export async function awaitWithin(pending, budgetMs, what, health = serviceHealt
  */
 export function timeoutSignal(ms = serviceTimeoutMs(), parent) {
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(new DOMException(`timed out after ${ms} ms`, "TimeoutError")), ms);
+    const timer = setTimeout(() => controller.abort(new DOMException(`timed out after ${ms} ms`, "TimeoutError")), Math.min(ms, MAX_TIMER_MS));
     timer.unref?.();
     if (parent) {
         if (parent.aborted) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basein/runner",
-  "version": "0.3.25",
+  "version": "0.3.27",
   "description": "A recording MCP proxy: sits between any MCP client and its MCP servers, executes each call on the client's behalf, and records the run as a reusable BaseIn scenario.",
   "type": "module",
   "license": "MIT",

package/production.md

@@ -523,7 +523,7 @@ Over 2-minute runs with one turn every 8 s (92 hooks):
 
 - **Backlog.** The backlog is bounded: 500 sends or 32 MiB, oldest steps dropped first. A queued send still facing a cool-down after 60 s is dropped unsent, not sent into the outage.
 - **Flush.** A flush waits at most 2 s (`BIR_FLUSH_TIMEOUT_MS`), and not at all while the service is cooling down.
-- **Retries.** A retry happens once, only after 429, 503, or a connection error that proves nothing reached the service. A 409 on the retry counts as "already landed". There is no retry after 502, 504 or a mid-request reset, until the service confirms it deduplicates ids (§10). What a 429 costs is in §3.3. The service's new build answers a report whose write failed with `503 report_not_booked`, so this one retry sends the report once more (built, not deployed yet).
+- **Retries.** A retry happens once, only after 429, 503, or a connection error that proves nothing reached the service. A 409 on the retry counts as "already landed". There is no retry after 502, 504 or a mid-request reset, until the service confirms it deduplicates ids (§10). What a 429 costs is in §3.3. The service's new build answers a report whose write failed with `503 report_not_booked`, so this one retry sends the report once more (built, not deployed yet). Three sends are different, because the service takes a second copy of each without harm: a run's finish and a patch (an update that keeps what it has), and an execution report that carries its ticket (a second copy answers `200 duplicate`). From 0.3.26 each of these goes back to the head of its lane when it fails with no answer or an unhealthy one (502, 504, a reset), up to 3 sends in all, and it is exempt from the 60 s give-up. Before, a run whose finish was lost never ended (never embedded, matched or calculated), and a turn whose report was lost was never booked. Any other 4xx stays final.
 
 **Size caps on uploads.**
 
@@ -1174,7 +1174,7 @@ Defaults were checked in `src/`.
 - **Two sessions in one project.** Direct replays for a session whose own proxy has not yet bound hand over instead of running.
 - **Revive gaps.** `bir-scenario` does not revive in its first 12 s; those first hooks are left to the SessionStart hook. A session with no wrapped server and no `bir` server is not revived until `/clear` or a new session. The revive window was not measured with real Claude Code.
 - **Direct-run worst case.** The worst case by budget is 120 s: 8 s of derivation, 100 s of plan, and 12 s of slack. It is reached only if every logic body hits its limit, and sits at Claude Code's 2-minute MCP auto-background. Setting `BIR_REPLAY_BUDGET_MS=120000` (the old default) makes it 140 s.
-- **Retries are conservative.** A send lost to a 502, 504 or mid-request reset is not retried until the service deduplicates ids.
+- **Retries are conservative.** A step or run create lost to a 502, 504 or mid-request reset is not retried until the service deduplicates ids. (A finish, a patch and a ticketed report are sent up to 3 times from 0.3.26: the service takes a second copy of each without harm, §6.5. The service now answers a repeated run or step id with 409.)
 - **Healthy-service prompt cost.** With an instant local service the prompt hook is about 6 ms slower than 0.2.12 (about 17 vs 11 ms median); the cause was not isolated. Under 503 or slow answers the recorder also keeps more idle keep-alive sockets. Both are small, but visible in measurements.
 - **A host other than Claude Code is not checked end to end.** What §3.2 describes ran on a bench only: a real LangChain agent against the real recorder, with a stand-in service and a fake model (`examples/langchain-proof/`). A real model, the real service and the production server have not been tried. The service's part is built and not deployed, and the Python package is not on PyPI. What that means for a LangChain application today is in `langChainGuide.md`, part 5.
 - **An interrupted or lossy Claude Code run is not marked.** Only a run of another host is finished with an `error` or with the `incomplete` mark today. A Claude Code run that was interrupted or lost steps is finished as before.

package/scripts/install.ps1

@@ -65,6 +65,11 @@ function Invoke-BirInstall {
     # child's environment only, set right before the spawn and removed after.
     $setupToken = $env:BIR_SETUP_TOKEN
     if ($setupToken) { Remove-Item -Path Env:BIR_SETUP_TOKEN -ErrorAction SilentlyContinue }
+    # The uninstall switch the same way: read once and taken out of the session,
+    # so pasting the ordinary install line later in this window installs, and
+    # does not uninstall again.
+    $uninstall = ($env:BIR_UNINSTALL -eq '1')
+    if ($null -ne $env:BIR_UNINSTALL) { Remove-Item -Path Env:BIR_UNINSTALL -ErrorAction SilentlyContinue }
 
     # Inside the function on purpose: under `irm | iex` these would otherwise
     # change the session the person keeps working in.
@@ -262,7 +267,14 @@ function Invoke-BirInstall {
                 Write-Note "node v$Version already at $exe"
                 return $exe
             }
-            # Half an extraction or a foreign file: removed, never extracted over.
+        }
+        # Half an extraction, a foreign file, or a folder whose node.exe is gone
+        # (an antivirus quarantine takes just that): removed, never extracted
+        # over. Whenever the folder is there, not only when node.exe is - a
+        # Move-Item onto a folder that exists moves the new one INSIDE it, so
+        # node.exe never appeared where it is looked for and every retry
+        # failed, 80 MB heavier. install.sh removes it the same way.
+        if (Test-Path -LiteralPath $nodeDir) {
             if ($dryRun) { Write-Would "remove the unusable $nodeDir" }
             else {
                 try { Remove-Item -LiteralPath $nodeDir -Recurse -Force }
@@ -459,7 +471,7 @@ public static extern IntPtr SendMessageTimeout(IntPtr hWnd, uint Msg, UIntPtr wP
         # before its files go. Every wrapped MCP server and every hook names a
         # file under ~\.baseinstrunner; deleting that first would break them
         # all, in every project, with no `bir` left to repair it.
-        if ($env:BIR_UNINSTALL -eq '1') {
+        if ($uninstall) {
             Write-Step 'Removing the runner from every project on this machine'
             $birCmd = Join-Path $birHome 'bin\bir.cmd'
             if (-not (Test-Path -LiteralPath $birCmd -PathType Leaf)) {