@basein/runner 0.3.2 → 0.3.3

package/README.md

@@ -414,7 +414,7 @@ what to do when they register, so there is one switch and no second copy of it:
 | `BIR_REPLAY` | `0` turns replay off and any other value on, over the project's stored switch (`bir replay on` / `off`; a first plain `bir install` stores off). Nothing below matters while it is off. |
 | `BIR_REPLAY_ALLOW_SERVERS` | Server keys bir may call unattended: **direct** execution, and a steered plan's recovery. Unset means the list `bir replay allow` stored for the project, else every wrapped server; narrowing it is the recommendation. |
 | `BIR_BUILTIN_TOOLS` | Built-in tools bir may execute itself during a replay — in the session's own project directory, and confined to it. Default `Read,Glob,Grep` (read-only). Add `Edit,Write,Bash` only deliberately: a runner-side step never reaches Claude Code's permission prompts. `none` turns it off, and a built-in step hands the turn back as before. |
-| `BIR_BASH_ALLOW` | Command prefixes a runner-side `Bash` step may run (`*` for all). Unset, `Bash` never executes on the runner, even when `BIR_BUILTIN_TOOLS` lists it. |
+| `BIR_BASH_ALLOW` | Command prefixes a runner-side `Bash` step may run (`*` for all). Unset, `Bash` never executes on the runner, even when `BIR_BUILTIN_TOOLS` lists it. A plan's Bash steps share a working directory, as Claude Code's do (variables and functions do not persist, also as in Claude Code). |
 | `BIR_MIN_STEER_SIMILARITY` | Minimum match similarity to replay (default `0.92`, above the service's own `0.9` detection threshold). |
 | `BIR_DERIVE_API_KEY` | **Optional.** Working out what a new request is about — which fleet, which file, which date — is done for you by the service on its own key, as long as you are signed in. Set this (an Anthropic key) only to keep that reading on your machine, on your key. Signed out *and* unset, a scenario whose values change between requests is declined rather than replayed on stale ones. |
 | `ANTHROPIC_API_KEY` | Not used by the background recorder, which has Claude Code's environment and would bill your own key — unless `BIR_USE_ANTHROPIC_API_KEY=1`. A `bir-hooks` run by hand in a terminal uses that terminal's key. |

package/dist/replay/builtins.d.ts

@@ -94,6 +94,21 @@ export interface BuiltinContext {
     timeoutMs?: number;
     /** Parsed `BIR_BASH_ALLOW` ({@link parseBashAllow}). */
     bashAllow?: readonly string[];
+    /**
+     * Where this plan's *previous* `Bash` step left its shell — the host's own
+     * semantics, which a recorded chain was written against: the working
+     * directory persists between Bash calls, while variables and functions do
+     * not (each call is a fresh shell off the profile). Absent, or pointing at
+     * a directory that no longer exists, the step starts in {@link cwd}.
+     */
+    bashCwd?: string;
+    /**
+     * Told where a `Bash` step's shell ended up (`$PWD`, as a path the next
+     * spawn can use), so the caller can carry it into the plan's next Bash
+     * step. Best effort: a command that `exit`s explicitly, or is cut off by
+     * its clock, reports nothing and the previous directory stands.
+     */
+    onBashCwd?: (pwd: string) => void;
 }
 /**
  * Execute one built-in step and return its hook-shaped result (an object; the

package/dist/replay/builtins.js

@@ -37,6 +37,7 @@
  * hook-view threading fallback already carries ("shapes may differ").
  */
 import { execFile } from "node:child_process";
+import { randomBytes } from "node:crypto";
 import { existsSync } from "node:fs";
 import { readdir, readFile, realpath, stat, writeFile } from "node:fs/promises";
 import { dirname, join, resolve, sep } from "node:path";
@@ -491,13 +492,28 @@ async function runBash(input, ctx) {
         throw new BuiltinNotRunnable("the command does not match BIR_BASH_ALLOW, so bir does not run it unattended");
     }
     const timeoutMs = ctx.timeoutMs ?? 120_000;
+    // The host's Bash semantics, which the recorded chain was written against:
+    // the working directory carries over from the plan's previous Bash step,
+    // variables and functions do not (a fresh `-l` shell each call).
+    const startIn = ctx.bashCwd && existsSync(ctx.bashCwd) ? ctx.bashCwd : resolve(ctx.cwd);
+    // Where the shell *ends up* is asked of the shell itself, behind a marker
+    // no real output contains (random per call), printed to stderr and
+    // stripped before the output is threaded — the recording never carried it.
+    // `pwd -W` is Git Bash's Windows-path form; elsewhere it fails quietly and
+    // plain `pwd` answers. An explicit `exit` skips the marker, and the
+    // previous directory simply stands.
+    const mark = `__BIR_PWD_${randomBytes(8).toString("hex")}__`;
+    const script = `${command}\n__bir_rc=$?\nprintf '\\n%s%s%s' '${mark}' "$(pwd -W 2>/dev/null || pwd)" '${mark}' 1>&2\nexit "$__bir_rc"`;
     return new Promise((resolvePromise, rejectPromise) => {
-        execFile(bashExecutable(), ["-lc", command], {
-            cwd: resolve(ctx.cwd),
+        execFile(bashExecutable(), ["-lc", script], {
+            cwd: startIn,
             timeout: timeoutMs,
             maxBuffer: MAX_BASH_BUFFER,
             windowsHide: true,
         }, (err, stdout, stderr) => {
+            const cleaned = takePwdMarker(String(stderr ?? ""), mark);
+            if (cleaned.pwd)
+                ctx.onBashCwd?.(cleaned.pwd);
             if (err) {
                 const e = err;
                 if (e.code === "ENOENT") {
@@ -511,19 +527,36 @@ async function runBash(input, ctx) {
                     return;
                 }
                 const code = typeof e.code === "number" ? e.code : 1;
-                const detail = String(stderr || stdout || "").trim().slice(0, 500);
+                const detail = String(cleaned.text || stdout || "").trim().slice(0, 500);
                 rejectPromise(new Error(`the command exited with code ${code}${detail ? `: ${detail}` : ""}`));
                 return;
             }
             resolvePromise({
                 stdout: String(stdout ?? ""),
-                stderr: String(stderr ?? ""),
+                stderr: cleaned.text,
                 interrupted: false,
                 isImage: false,
             });
         });
     });
 }
+/**
+ * Split the shell's final `$PWD` out of stderr again: the marked chunk (and
+ * the newline the wrapper added before it) is removed, whatever else the
+ * command wrote stays byte-for-byte.
+ */
+function takePwdMarker(stderr, mark) {
+    const i = stderr.indexOf(mark);
+    if (i < 0)
+        return { text: stderr };
+    const j = stderr.indexOf(mark, i + mark.length);
+    if (j < 0)
+        return { text: stderr };
+    const pwd = stderr.slice(i + mark.length, j).trim();
+    const before = stderr.slice(0, i).replace(/\n$/, "");
+    const after = stderr.slice(j + mark.length);
+    return { text: before + after, pwd: pwd || undefined };
+}
 // ── shared walking and matching ─────────────────────────────────────────────
 /** Directories no scenario's step means to scan. */
 const SKIP_DIRS = new Set([".git", "node_modules", ".hg", ".svn"]);

package/dist/replay/controller.d.ts

@@ -356,6 +356,15 @@ export interface ReplayState {
      * no built-in executes: the step is `not_run`, exactly as before.
      */
     sessionCwd?: string;
+    /**
+     * Where this plan's last runner-side `Bash` step left its shell. The
+     * host's own semantics, which the recorded chain was written against: the
+     * working directory persists between Bash calls (variables and functions
+     * do not), so a chain of `cd sub` then `cat file` replays as it ran.
+     * Starts at {@link sessionCwd}; never read for `Read`/`Edit`/`Write`
+     * paths, which resolve against the project directory as the host's do.
+     */
+    bashCwd?: string;
     /**
      * Which kind of row was handed out (segmented.md R-OUT-7). A `segment` is a
      * named sub-task of a recording rather than a whole task, and it is judged

package/dist/replay/controller.js

@@ -2084,7 +2084,7 @@ export class ReplayController {
                 // the session can do the step itself or its recorded output can
                 // stand in (`BIR_REPLAY_RECORDED_OUTPUTS=1`).
                 if (this.builtinTools.has(name) && state.sessionCwd) {
-                    return this.executeBuiltin(name, input, state.sessionCwd, opts.deadline);
+                    return this.executeBuiltin(name, input, state, opts.deadline);
                 }
                 throw new StepRunError(`${name || "this step"} is a built-in tool, which only runs in the session`, "not_run");
             }
@@ -2130,14 +2130,24 @@ export class ReplayController {
      * Failures keep {@link ExecuteStep}'s contract: policy (`not_run`), a step
      * cut off by its clock (`uncertain`), a step that ran and broke (`failed`).
      */
-    async executeBuiltin(name, input, cwd, deadline) {
+    async executeBuiltin(name, input, state, deadline) {
+        const cwd = state.sessionCwd; // the caller executes only with one
         const left = deadline !== undefined ? deadline - Date.now() : Number.POSITIVE_INFINITY;
         const timeoutMs = Math.max(MIN_STEP_MS, Math.min(this.budgets.stepMs, left));
         // The audit line precedes the action, always (§13.2, mitigation 4).
         logDetail("replay.builtin", { tool: name, cwd });
         let result;
         try {
-            result = await runBuiltin(name, input, { cwd, timeoutMs, bashAllow: this.bashAllow });
+            result = await runBuiltin(name, input, {
+                cwd,
+                timeoutMs,
+                bashAllow: this.bashAllow,
+                // The plan's Bash steps share a working directory, as the host's do.
+                bashCwd: state.bashCwd,
+                onBashCwd: (pwd) => {
+                    state.bashCwd = pwd;
+                },
+            });
         }
         catch (err) {
             if (err instanceof BuiltinNotRunnable)

package/docs/calculatedReplay.md

@@ -259,7 +259,10 @@ step is `not_run`, the clean hand-over. `Bash` needs a second opt-in on top (`BI
 command prefixes), because a runner-side step never reaches the host's permission prompts. The
 results mimic the hook's view of each tool, which is what the recorder stored for built-in steps
 and what their `toolOutputLogic` was authored against; they pass through the same
-`serializeCapped(redact(…))` as every recorded payload.
+`serializeCapped(redact(…))` as every recorded payload. Bash keeps the host's own semantics a
+recorded chain was written against: each call is a fresh `-l` shell (variables and functions do
+not persist), while the **working directory carries over** from the plan's previous Bash step —
+`cd sub` then `cat file` replays as it ran.
 
 A **mixed** scenario in `steer` mode still gets direct execution for its wrapped steps once it
 diverges (§8), so coverage is not all-or-nothing at the divergence boundary — only at the arm-time

package/docs/calculatedReplayGuide.md

@@ -354,7 +354,7 @@ so there is exactly one switch and it cannot get out of step with itself.
 | `BIR_LOGIC_TIMEOUT_MS` | `1000` | How long one scenario logic body may run before it is stopped. At most 10 000 |
 | `BIR_REPLAY_RECORDED_OUTPUTS` | *(unset)* | `1` lets a step that could not be sent (a built-in off `BIR_BUILTIN_TOOLS`, no proxy, a server off the allowlist) stand on its recorded output instead of stopping the plan. Never for a timeout or an upstream error |
 | `BIR_BUILTIN_TOOLS` | `Read,Glob,Grep` | Built-ins the runner executes itself during a replay, in the session's own project directory and confined to it. A chain whose only non-MCP steps are on this list arms `direct`. Add `Edit,Write,Bash` only deliberately — a runner-side step never reaches the host's permission prompts. `none` restores the old behaviour: every built-in hands the turn back |
-| `BIR_BASH_ALLOW` | *(unset)* | Command prefixes a runner-side `Bash` step may run (`*` for all). Unset, `Bash` never executes on the runner, even when `BIR_BUILTIN_TOOLS` lists it |
+| `BIR_BASH_ALLOW` | *(unset)* | Command prefixes a runner-side `Bash` step may run (`*` for all). Unset, `Bash` never executes on the runner, even when `BIR_BUILTIN_TOOLS` lists it. A plan's Bash steps share a working directory, exactly as the host's own Bash tool does — variables and functions do not persist, also as the host's |
 | `BIR_INTENT_ARM` | *(unset)* | `1` lets a match found mid-turn arm a plan in the calling tool's place, which means waiting for it (`BIR_INTENT_ARM_BUDGET_MS`, 500); `0` never waits; unset follows `BIR_SEGMENT_ARM` |
 | `BIR_VERBOSE` | *(unset)* | `1` adds per-step `replay.*` detail lines |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basein/runner",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "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

@@ -993,7 +993,7 @@ Defaults were checked in `src/`.
 | `BIR_LOGIC_TIMEOUT_MS` | recorder | 1000 (capped at 10000) | Synchronous time limit for one scenario logic body. |
 | `BIR_REPLAY_RECORDED_OUTPUTS` | recorder | unset | `1`: a step that could not be sent may use its recorded output, labelled as such. |
 | `BIR_BUILTIN_TOOLS` | recorder | `Read,Glob,Grep` | Built-ins the runner executes itself during a replay, in the session's project directory and confined to it. Add `Edit,Write,Bash` deliberately — runner-side steps bypass the host's permission prompts. `none` turns it off. |
-| `BIR_BASH_ALLOW` | recorder | unset | Command prefixes a runner-side `Bash` step may run (`*` for all). Unset, `Bash` never executes on the runner even when listed. |
+| `BIR_BASH_ALLOW` | recorder | unset | Command prefixes a runner-side `Bash` step may run (`*` for all). Unset, `Bash` never executes on the runner even when listed. A plan's Bash steps share a working directory, as the host's do; variables do not persist, also as the host's. |
 | `BIR_DERIVE_RECENT_RESULTS` | recorder | 5 | How many of this prompt's tool results derivation may read (`0`: none). Never for plans with a command sink. |
 | `BIR_INTENT_MATCH` | recorder | on | `0` turns mid-turn intent probes off. |
 | `BIR_INTENT_MATCH_BUDGET_MS` | recorder | 4000 | One probe's own ceiling. It is not a hook wait. |