@basein/runner 0.3.20 → 0.3.22

package/dist/replay/builtins.js

@@ -5,7 +5,7 @@
  * A built-in lives inside the host session, not behind any MCP server, so there
  * is no proxy to relay it to: historically every built-in step threw `not_run`
  * and the plan handed the task back to the model. This module is the other
- * option: execute the step here, against the *session's own project directory*,
+ * option: execute the step here, from the *session's own project directory*,
  * so a chain that starts with a `Read` no longer costs a hand-over.
  *
  * THE RULES, because this bypasses the host's permission prompts entirely:
@@ -17,10 +17,17 @@
  *     already has — its pinned call is answered `allow` too. What running it
  *     here changes is that no model sees the call before it runs, so an
  *     operator who wants one in the loop takes the tool off the list.
- *   - **Path jail.** Every path is resolved against, and confined to, the
- *     session's project directory ({@link jailed}), symlinks included. The
- *     daemon's own cwd is never used: it is `~/.baseinstrunner`, not the
- *     project (§5.1 of the change plan).
+ *   - **Any path the agent could reach, unless `BIR_PATH_ALLOW` narrows it.**
+ *     A relative path resolves against the session's project directory, as
+ *     the host's tools resolve it; the daemon's own cwd is never used: it is
+ *     `~/.baseinstrunner`, not the project (§5.1 of the change plan). An
+ *     absolute path is taken as it is, inside the project or not: the agent's
+ *     own tools reach any folder its session allows — the recorded call was
+ *     one of them — and a runner-side `Bash` reaches any folder already. Up
+ *     to 0.3.20 every path was confined to the project directory;
+ *     `BIR_PATH_ALLOW=project` brings that back, and a list of folders
+ *     ({@link parsePathAllow}) confines the file tools to those, symlinks
+ *     included ({@link allowedPath}).
  *   - **Bash runs any command unless `BIR_BASH_ALLOW` narrows it.** Set, a
  *     command must match one of its prefixes ({@link bashAllowed}); `none`
  *     allows no command, and then `Bash` counts as off the list, so its steps
@@ -43,7 +50,8 @@ 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";
+import { homedir } from "node:os";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
 // ── configuration ────────────────────────────────────────────────────────────
 /** The built-ins {@link runBuiltin} actually implements. */
 export const EXECUTABLE_BUILTINS = new Set([
@@ -61,8 +69,24 @@ export const EXECUTABLE_BUILTINS = new Set([
  * set (`Read,Glob,Grep`).
  */
 export const DEFAULT_BUILTIN_TOOLS = [...EXECUTABLE_BUILTINS];
+/**
+ * The built-ins that reach files by a path, the ones `BIR_PATH_ALLOW`
+ * governs. `Bash` is not among them: what a command touches is
+ * `BIR_BASH_ALLOW`'s business.
+ */
+export const FILE_BUILTINS = new Set(["Read", "Glob", "Grep", "Edit", "Write"]);
 /** `read` → `Read`: the vocabulary is small enough to forgive casing. */
 const CANONICAL_BUILTIN = new Map([...EXECUTABLE_BUILTINS].map((name) => [name.toLowerCase(), name]));
+/**
+ * A switch's list once it is set: comma-separated, trimmed, empty entries
+ * dropped, and `none` / `off` / `0` meaning nothing at all.
+ */
+function parseList(value) {
+    return value
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0 && !["none", "off", "0"].includes(s.toLowerCase()));
+}
 /**
  * Parse `BIR_BUILTIN_TOOLS`. Unset means {@link DEFAULT_BUILTIN_TOOLS}; set,
  * it is the whole list — `none` (or an empty value) turns built-ins off
@@ -73,12 +97,7 @@ const CANONICAL_BUILTIN = new Map([...EXECUTABLE_BUILTINS].map((name) => [name.t
 export function parseBuiltinTools(value) {
     if (value === undefined)
         return new Set(DEFAULT_BUILTIN_TOOLS);
-    const names = value
-        .split(",")
-        .map((s) => s.trim())
-        .filter((s) => s.length > 0 && !["none", "off", "0"].includes(s.toLowerCase()))
-        .map((s) => CANONICAL_BUILTIN.get(s.toLowerCase()) ?? s);
-    return new Set(names);
+    return new Set(parseList(value).map((s) => CANONICAL_BUILTIN.get(s.toLowerCase()) ?? s));
 }
 /**
  * Parse `BIR_BASH_ALLOW`: comma-separated command prefixes, `*` for
@@ -89,10 +108,24 @@ export function parseBuiltinTools(value) {
 export function parseBashAllow(value) {
     if (value === undefined)
         return ["*"];
-    return value
-        .split(",")
-        .map((s) => s.trim())
-        .filter((s) => s.length > 0 && !["none", "off", "0"].includes(s.toLowerCase()));
+    return parseList(value);
+}
+/**
+ * Parse `BIR_PATH_ALLOW`: the folders a runner-side `Read`, `Glob`, `Grep`,
+ * `Edit` or `Write` may touch, comma-separated, `*` for anywhere. Unset means
+ * anywhere, as the agent's own tools reach any folder its session allows (up
+ * to 0.3.20 it was the project directory alone). In a list, `project` is the
+ * session's project directory, `~` the home folder (`~/.claude` a folder in
+ * it), and any other relative folder resolves against the project directory.
+ * Set, it is the whole list, as `BIR_BASH_ALLOW` is: `none` (or an empty
+ * value) allows no folder, and the file tools then count as off
+ * `BIR_BUILTIN_TOOLS`, so their steps are steered in the session
+ * (controller.ts).
+ */
+export function parsePathAllow(value) {
+    if (value === undefined)
+        return ["*"];
+    return parseList(value);
 }
 /**
  * Whether `command` matches the `BIR_BASH_ALLOW` prefixes. A prefix that ends
@@ -117,8 +150,9 @@ export function bashAllowed(command, allow) {
 // ── the failure contract ─────────────────────────────────────────────────────
 /**
  * The step cannot run here — policy, not breakage: the tool is not
- * implemented, its path leaves the project, `Bash` is not allowed, or the
- * input is not even the right shape. Maps to `not_run`: nothing happened, the
+ * implemented, its path is outside the folders `BIR_PATH_ALLOW` names, the
+ * command is not one `BIR_BASH_ALLOW` allows, or the input is not even the
+ * right shape. Maps to `not_run`: nothing happened, the
  * session may still do it, a recorded output may stand in.
  */
 export class BuiltinNotRunnable extends Error {
@@ -186,7 +220,9 @@ export async function runBuiltin(toolName, input, ctx) {
             throw new BuiltinNotRunnable(`no runner-side implementation for ${toolName}`);
     }
 }
-// ── the path jail ────────────────────────────────────────────────────────────
+// ── which paths a file step may touch ────────────────────────────────────────
+/** The word in `BIR_PATH_ALLOW` that stands for the session's project directory. */
+const PROJECT_WORD = "project";
 /** Case-blind on Windows, where `C:\Repo` and `c:\repo` are one directory. */
 function samePath(a, b) {
     return process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
@@ -199,54 +235,87 @@ function underRoot(root, abs) {
             : abs.startsWith(prefix)));
 }
 /**
- * Resolve `p` against the session root and refuse anything outside it — first
- * textually, then through `realpath` so a symlink inside the project cannot
- * point the step at a file beyond it. The nearest existing ancestor is what
- * gets resolved, so a `Write` to a new file is judged by its real directory.
+ * The folders the context's `BIR_PATH_ALLOW` list names, as absolute paths,
+ * or `anywhere` for `*`. `project` is the session's project directory, `~`
+ * the home folder, and any other relative entry resolves against the project.
  */
-async function jailed(root, p, what = "file_path") {
-    if (typeof p !== "string" || p.trim() === "") {
-        throw new BuiltinNotRunnable(`${what} is required`);
-    }
-    const r = resolve(root);
-    const abs = resolve(r, p);
-    const outside = () => {
-        throw new BuiltinNotRunnable(`${p} is outside the session's project directory, so bir does not touch it unattended`);
-    };
-    if (!underRoot(r, abs))
-        outside();
-    // The textual check passed; now the physical one. Walk up to what exists,
-    // realpath it, and require *that* to sit under the root's own realpath.
+function allowedFolders(ctx) {
+    const allow = ctx.pathAllow ?? [PROJECT_WORD];
+    if (allow.includes("*"))
+        return "anywhere";
+    const project = resolve(ctx.cwd);
+    return allow.map((entry) => {
+        if (entry.toLowerCase() === PROJECT_WORD)
+            return project;
+        if (entry === "~")
+            return homedir();
+        if (entry.startsWith("~/") || entry.startsWith("~\\"))
+            return resolve(homedir(), entry.slice(2));
+        return resolve(project, entry);
+    });
+}
+/** Why a path was refused, naming the switch that refused it. */
+function outsideMessage(p, allow) {
+    return allow.length === 1 && allow[0].toLowerCase() === PROJECT_WORD
+        ? `${p} is outside the session's project directory, and BIR_PATH_ALLOW=project keeps bir inside it`
+        : `${p} is outside the folders BIR_PATH_ALLOW names (${allow.join(", ")}), so bir does not touch it unattended`;
+}
+/**
+ * `abs` as it is on disk: its longest existing ancestor replaced by that
+ * ancestor's realpath (symlinks resolved, and on macOS `/var` read as
+ * `/private/var`), the rest kept as written. A path none of which exists
+ * comes back as it is.
+ */
+async function physical(abs) {
     let probe = abs;
-    let real;
+    const rest = [];
     for (;;) {
         try {
-            real = await realpath(probe);
-            break;
+            const real = await realpath(probe);
+            return rest.length > 0 ? join(real, ...rest.reverse()) : real;
         }
         catch {
             const parent = dirname(probe);
             if (samePath(parent, probe))
-                break; // hit the filesystem root: nothing exists
+                return abs; // the filesystem root: nothing exists
+            rest.push(basename(probe));
             probe = parent;
         }
     }
-    if (real !== undefined) {
-        let realRoot;
-        try {
-            realRoot = await realpath(r);
-        }
-        catch {
-            throw new BuiltinNotRunnable(`the session's project directory does not exist: ${root}`);
-        }
-        if (!underRoot(realRoot, real))
-            outside();
+}
+/**
+ * Resolve `p` as the host does — against the session's project directory
+ * when it is relative — and allow it anywhere, as the agent's own tools
+ * would, unless `BIR_PATH_ALLOW` names folders. Then anything outside them is
+ * refused: first as written, then physically ({@link physical}, both sides),
+ * so a symlink inside an allowed folder cannot point the step at a file
+ * beyond it, and a `Write` to a new file is judged by its real folder.
+ */
+async function allowedPath(ctx, p, what = "file_path") {
+    if (typeof p !== "string" || p.trim() === "") {
+        throw new BuiltinNotRunnable(`${what} is required`);
     }
+    const abs = resolve(ctx.cwd, p);
+    const folders = allowedFolders(ctx);
+    if (folders === "anywhere")
+        return abs;
+    if (folders.length === 0) {
+        throw new BuiltinNotRunnable("BIR_PATH_ALLOW allows no folder, so bir touches no file unattended");
+    }
+    const outside = () => {
+        throw new BuiltinNotRunnable(outsideMessage(p, ctx.pathAllow ?? [PROJECT_WORD]));
+    };
+    if (!folders.some((folder) => underRoot(folder, abs)))
+        outside();
+    const real = await physical(abs);
+    const realFolders = await Promise.all(folders.map(physical));
+    if (!realFolders.some((folder) => underRoot(folder, real)))
+        outside();
     return abs;
 }
 // ── Read ─────────────────────────────────────────────────────────────────────
 async function runRead(input, ctx) {
-    const filePath = await jailed(ctx.cwd, input.file_path);
+    const filePath = await allowedPath(ctx, input.file_path);
     const size = (await stat(filePath)).size;
     if (size > MAX_FILE_BYTES) {
         throw new Error(`file is ${size} bytes, more than the ${MAX_FILE_BYTES} this runner reads`);
@@ -276,7 +345,7 @@ async function runGlob(input, ctx, deadline) {
     if (typeof pattern !== "string" || pattern.trim() === "") {
         throw new BuiltinNotRunnable("pattern is required");
     }
-    const root = await jailed(ctx.cwd, typeof input.path === "string" ? input.path : ".", "path");
+    const root = await allowedPath(ctx, typeof input.path === "string" ? input.path : ".", "path");
     const startedAt = Date.now();
     const re = globToRegExp(pattern);
     const found = [];
@@ -324,7 +393,7 @@ async function runGrep(input, ctx, deadline) {
     catch (err) {
         throw new BuiltinNotRunnable(`the pattern is not a regular expression this runner can run: ${err.message}`);
     }
-    const target = await jailed(ctx.cwd, typeof input.path === "string" ? input.path : ".", "path");
+    const target = await allowedPath(ctx, typeof input.path === "string" ? input.path : ".", "path");
     // ripgrep's `-g '*.ts'` matches the basename at any depth; only a pattern
     // with a `/` in it speaks about the path.
     const globRe = typeof input.glob === "string" && input.glob
@@ -417,7 +486,7 @@ async function matchFile(path, re, firstOnly) {
 }
 // ── Edit / Write ─────────────────────────────────────────────────────────────
 async function runEdit(input, ctx) {
-    const filePath = await jailed(ctx.cwd, input.file_path);
+    const filePath = await allowedPath(ctx, input.file_path);
     const oldString = input.old_string;
     const newString = input.new_string;
     if (typeof oldString !== "string" || oldString === "") {
@@ -452,7 +521,7 @@ async function runEdit(input, ctx) {
     };
 }
 async function runWrite(input, ctx) {
-    const filePath = await jailed(ctx.cwd, input.file_path);
+    const filePath = await allowedPath(ctx, input.file_path);
     const content = input.content;
     if (typeof content !== "string")
         throw new BuiltinNotRunnable("content is required");
@@ -579,9 +648,10 @@ function takePwdMarker(stderr, mark) {
 const SKIP_DIRS = new Set([".git", "node_modules", ".hg", ".svn"]);
 /**
  * Walk `root`, calling `visit(relativePath, absolutePath, mtimeMs)` for every
- * regular file. Never follows directory symlinks — the jail was checked at
- * the root, and a link out of it must not re-open the door. Returns whether
- * the walk was cut short (entry cap, deadline, or `visit` saying stop).
+ * regular file. Never follows directory symlinks — the folder was checked at
+ * the root, and under a `BIR_PATH_ALLOW` list a link out of it must not
+ * re-open the door (nor may a link loop the walk). Returns whether the walk
+ * was cut short (entry cap, deadline, or `visit` saying stop).
  */
 async function walk(root, deadline, visit) {
     let seen = 0;
@@ -617,7 +687,9 @@ async function walk(root, deadline, visit) {
             catch {
                 continue;
             }
-            const rel = abs.slice(resolve(root).length + 1).split(sep).join("/");
+            // `relative`, not a slice: a walk may now start at a drive's or the
+            // disk's root (`C:\`, `/`), which already ends in a separator.
+            const rel = relative(root, abs).split(sep).join("/");
             if (!visit(rel, abs, mtime))
                 return true;
         }

package/dist/replay/bundle.d.ts

@@ -51,8 +51,8 @@ export interface AssembleOptions {
     /** The plan stopped part-way and the model is to carry on (fallbk.md). */
     handover?: boolean;
     /**
-     * The plan was armed mid-task by intent (segmented.md R-OUT-13). Its results
-     * feed the agent's own task, which continues. `handover` wins over this.
+     * The plan was armed mid-task by intent. Its results feed the agent's own
+     * task, which continues. `handover` wins over this.
      */
     subTask?: boolean;
     /**

package/dist/replay/bundle.js

@@ -100,8 +100,8 @@ const HANDOVER_HEADER = "[BaseInstRunner calculated replay] The tool calls below
     "continue the task yourself from where they end.";
 const HANDOVER_FOOTER = "\n\nThe calls above are done. Continue the rest of the task yourself, calling tools as needed.";
 /**
- * The plan ran inside the agent's own task (segmented.md R-OUT-13): it finished,
- * but the task did not, so the model must not be told to answer without tools.
+ * The plan ran inside the agent's own task (armed mid-task by intent): it
+ * finished, but the task did not, so the model must not be told to answer without tools.
  * This is {@link HANDOVER_HEADER} without "The scenario stopped before the task
  * was finished" — nothing stopped, the sub-task is simply done.
  */
@@ -121,7 +121,7 @@ export function assembleBundle(entries, maxChars, opts = {}) {
     const anyRecorded = entries.some((e) => e.recorded);
     // A hand-over outranks a sub-task: it says "continue" too, and it also has to
     // say that the plan stopped short. A sub-task outranks the live and mixed
-    // headers, whose wording forbids further tool calls (segmented.md 10.8 §6).
+    // headers, whose wording forbids further tool calls.
     const header = opts.handover
         ? HANDOVER_HEADER
         : opts.subTask

package/dist/replay/controller.d.ts

@@ -11,14 +11,13 @@
  * degrades to "run the turn normally" or returns something the session can
  * ignore. Nothing throws at a hook.
  */
-import type { ExecutionReport, MatchKey, MatchSegment, MatchVerdict } from "../record/recorder.js";
+import type { ExecutionReport } from "../record/recorder.js";
 import { type ReplayMode, type StepReach } from "./coverage.js";
 import { deriveParameters, type AgentDay, type DeriveContext, type DeriveResult } from "./derive.js";
 import { ProxyWorkQueue } from "./executor.js";
 import { ScenarioReplayPlan } from "./plan.js";
 import { type HostSinks } from "./safety.js";
 import { SourceRunOutputs } from "./source-run.js";
-import { type FlatStop } from "./flatten.js";
 import { type ExecutionOutcome, type ExecutionStepResult, type FallbackKind, type SerializedScenario, type SerializedScenarioStep } from "./types.js";
 /** The first-party tool a `direct` plan is delivered through (§6.3). */
 export declare const DIRECT_TOOL_NAME = "mcp__bir__run_scenario";
@@ -239,14 +238,6 @@ export declare const RUN_NO_PLAN = "no_plan";
 export interface ReplayOptions {
     /** On unless `BIR_REPLAY=0`. Everything here is inert when false. */
     enabled: boolean;
-    /**
-     * Whether a handed-out segment may run mid-task. The recorder sets it from
-     * `BIR_SEGMENT_ARM`: on unless that is `0`, from runner 0.3.19 (the
-     * service's segmentsbreakdown.md SB-21). Omitted, as by a test or an
-     * embedder, it is off: observe-only, where the runner asks for no segment,
-     * arms none, and only logs what would have armed (R-OUT-10).
-     */
-    segmentArm?: boolean;
     /** `BIR_REPLAY_ALLOW_SERVERS`; undefined means every wrapped server. */
     allowServers?: ReadonlySet<string>;
     /**
@@ -266,6 +257,16 @@ export interface ReplayOptions {
      * rather than armed `direct` and stopped at the first one.
      */
     bashAllow?: readonly string[];
+    /**
+     * `BIR_PATH_ALLOW` — the folders a runner-side `Read`, `Glob`, `Grep`,
+     * `Edit` or `Write` may touch (`*` for any; `project` is the session's
+     * project directory). Omitted, the environment decides; the default is
+     * `*`, any path the agent's own tools could reach (up to 0.3.20 the
+     * project directory alone). Empty allows no folder, and then the file tools
+     * count as off {@link ReplayOptions.builtinTools}, as `Bash` does under an
+     * empty {@link ReplayOptions.bashAllow}.
+     */
+    pathAllow?: readonly string[];
     budgets?: Partial<ReplayBudgets>;
     /**
      * The service: the lazy source-run fetch, and the parameter derivation this
@@ -297,21 +298,13 @@ export interface ReplayOptions {
 export interface IntentMatchOptions {
     /** `BIR_INTENT_MATCH`. */
     enabled: boolean;
-    /**
-     * How long a `PreToolUse` waits for the service. A timeout is a miss.
-     *
-     * 4 000 ms, not the 1 500 of Part 1: a request whose best segment lands in
-     * the *not clear* band has one live question to ask under the server's own
-     * 2 500 ms attempt, and must still answer well inside the hook's 30 s
-     * (segmented.md R-HIT-11). A clear match or a miss answers as fast as before.
-     */
+    /** How long a probe's request may take. A timeout is a miss. */
     budgetMs: number;
     /** Plans intent matching may arm in one turn. */
     maxPerTurn: number;
     /**
-     * Probes one turn may *send*. Separate from `maxPerTurn`, and much larger:
-     * arming three plans is a claim on the turn, while counting hits is only
-     * bookkeeping, and it must not stop at the third arm (R-HIT-5).
+     * Probes one turn may *send*. Separate from `maxPerTurn`, and larger: most
+     * probes find nothing, and a turn that armed nothing yet may still match.
      */
     maxRequestsPerTurn: number;
 }
@@ -391,24 +384,10 @@ export interface ReplayState {
     armedAt: number;
     reported: boolean;
     sourceRun?: SourceRunOutputs;
-    /**
-     * Why the flattener stopped the plan, when it is what stopped it: a call this
-     * chain cannot run right now (segmented.md R-CALL-29). The note names the
-     * sub-task and the reason, and the report carries `unusable_call`.
-     */
-    flatStop?: FlatStop;
     /** Set once a plan has been retired, so nothing re-arms mid-turn. */
     retired: boolean;
     /** What armed it: the prompt, or a ReAct iteration's intent (fallbk.md). */
     armedBy: "prompt" | "intent";
-    /**
-     * The user's request this plan serves, in their own words: the prompt for a
-     * plan the prompt armed (set in `arm`), the turn's prompt for one an intent
-     * match armed (set by the control server). Read only for the note of a plan
-     * stopped at its decision, which quotes the request's condition sentences
-     * (the service's segmentsbreakdown.md SB-18). Never sent anywhere.
-     */
-    request?: string;
     /**
      * The Claude Code session this plan serves, set by the control server. Its
      * steps run on that session's own proxies (executor.ts). Absent for `bir
@@ -418,8 +397,9 @@ export interface ReplayState {
     /**
      * That session's project directory, set by the control server from the
      * hook payloads — never the daemon's own cwd, which is `~/.baseinstrunner`.
-     * It is where an allow-listed built-in step executes and the jail it may
-     * not leave (replay/builtins.ts). Absent — `bir replay`, an older server —
+     * It is where an allow-listed built-in step executes and what its relative
+     * paths resolve against (replay/builtins.ts; `BIR_PATH_ALLOW=project`
+     * confines the file tools to it). Absent — `bir replay`, an older server —
      * no built-in executes: the step is `not_run`, exactly as before.
      */
     sessionCwd?: string;
@@ -432,25 +412,6 @@ export interface ReplayState {
      * 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
-     * against its own similarity gate. Absent from an older server, and then read
-     * as `scenario` (R-COMPAT-2).
-     */
-    kind: "scenario" | "segment";
-    /** Where a handed-out segment sits in its recording (R-OUT-8). */
-    segment?: MatchSegment;
-    /** Which of the segment's two keys scored (R-OUT-3). For logs. */
-    key?: MatchKey;
-    /** The cheap model's answer, when the score sat in the not-clear band. */
-    verified?: MatchVerdict;
-    /**
-     * Segments of this plan's own recording that armed later in the same turn
-     * (R-MONEY-4). Their share comes off this plan's baseline, so one recording's
-     * steps are never counted in two baselines of one turn.
-     */
-    sharedWith: string[];
     /** Set when the plan handed the task to the model part-way (fallbk.md). */
     handover?: Handover;
     /**
@@ -472,11 +433,9 @@ export interface ReplayState {
      */
     diverging?: boolean;
     /**
-     * Which gate declined, as a fixed code (segmented.md R-HIT-14). The prose
-     * `why` that `decline()` logs stays free text; this is what code reads — the
-     * position rule (R-OUT-6) reports a position only for `known_bad_first_step`,
-     * and reading prose for that would break the first time a sentence was
-     * reworded.
+     * Which gate declined, as a fixed code. The prose `why` that `decline()`
+     * logs stays free text; this is what code and the report read, and reading
+     * prose would break the first time a sentence was reworded.
      */
     declined?: DeclineCode;
     /**
@@ -496,10 +455,7 @@ export interface ReplayState {
      * A plan that finished its work stops costing at that moment: the agent's
      * later work in the same turn is the agent's, not this plan's. A plan that
      * handed over or diverged takes no mark, because the follow-on work is the
-     * direct consequence of its stopping (R-MONEY-3, R-FALL-5) — except a plan
-     * stopped at its decision after a step ran: it did all it was for, and the
-     * agent's decision and the half it chose are the agent's own (the service's
-     * segmentsbreakdown.md SB-26).
+     * direct consequence of its stopping (R-MONEY-3, R-FALL-5).
      */
     retiredMark?: unknown;
     retiredAt?: number;
@@ -567,10 +523,7 @@ export interface ReplayState {
      * copies are cut to 3,800 bytes, and the agent's work is built on them.
      */
     keepCalls?: boolean;
-    /**
-     * Those calls, in the order the plan made them, keyed by frame and step —
-     * a sub-task called twice keeps both calls of each step.
-     */
+    /** Those calls, in the order the plan made them, keyed by step. */
     turnCalls?: Map<string, TurnCall>;
     /** What they hold, in characters: bounded by {@link TURN_CALLS_MAX_CHARS}. */
     turnCallChars?: number;
@@ -613,7 +566,7 @@ export interface TurnCall {
  * Why a match did not arm. One code per gate of the ladder, so the caller can
  * act on a decline without parsing the sentence that explains it.
  */
-export type DeclineCode = "replay_disabled" | "not_ready" | "flatten_failed" | "known_bad_first_step" | "nondeterministic_first_step" | "unusable_first_step" | "coverage" | "missing_target" | "no_derive_key"
+export type DeclineCode = "replay_disabled" | "not_ready" | "known_bad_first_step" | "nondeterministic_first_step" | "coverage" | "missing_target" | "no_derive_key"
 /** The service handed over no plan: this runner is too old for it. */
  | "runner_update_required"
 /**
@@ -689,6 +642,8 @@ export declare class ReplayController {
     private readonly builtinTools;
     /** See {@link ReplayOptions.bashAllow}. */
     private readonly bashAllow;
+    /** See {@link ReplayOptions.pathAllow}. */
+    private readonly pathAllow;
     /** Calls waiting for a plan's pins to change (see `awaitPins`). */
     private readonly pinWaiters;
     /**
@@ -698,16 +653,6 @@ export declare class ReplayController {
      */
     private hostSignals;
     constructor(opts: ReplayOptions);
-    /**
-     * Whether a handed-out segment may actually arm (segmented.md R-OUT-10).
-     *
-     * Only when the option says so. The recorder passes it on unless
-     * `BIR_SEGMENT_ARM=0` (from 0.3.19; the service's segmentsbreakdown.md
-     * SB-21); a controller built without it stays observe-only, asks for no
-     * segment and arms none. The server enforces the same thing from its side
-     * (R-OUT-9).
-     */
-    get segmentArm(): boolean;
     /** The plan's own delivery vehicle is never a scenario step. */
     isDirectTool(toolName: string): boolean;
     /**
@@ -745,16 +690,9 @@ export declare class ReplayController {
      * stops when that is before its end. For a host that steps through the plan
      * itself and must not have to pick the tool names out of a directive
      * written for a model — a reworded sentence would break every adapter in
-     * the field. Built from the same entries the directive lists.
+     * the field. Built from the same steps the directive lists.
      */
     planData(state: ReplayState): PlanData | undefined;
-    /**
-     * Whether the plan's steps end in front of a decision (the service's
-     * segmentsbreakdown.md SB-6): it runs the steps before it, then hands the
-     * task back there. The control server gives such a plan a usage mark, so
-     * that it is billed only up to the stop (SB-26).
-     */
-    stopsAtDecision(state: ReplayState): boolean;
     /**
      * Take back a plan that armed and has run nothing, as a decline.
      *
@@ -901,9 +839,9 @@ export declare class ReplayController {
      */
     postTool(state: ReplayState, toolUseId: string, output: string, failed?: string, how?: PostToolOptions): boolean;
     /**
-     * A steer plan whose cursor reached its end: in front of a parked step (or a
-     * call the service could not answer), which hands over; otherwise it ran to
-     * its end — and from here every call is the model's own.
+     * A steer plan whose cursor reached its end: in front of a parked step,
+     * which hands over; otherwise it ran to its end — and from here every call
+     * is the model's own.
      */
     private finishSteer;
     /**
@@ -1044,10 +982,6 @@ export declare class ReplayController {
      * there is nothing to be similar *to* and nothing to decline. It books no
      * execution either — there is no ticket, and inventing a saving for a manual
      * invocation is exactly the kind of number a ledger must never contain.
-     *
-     * One served stop is kept: a plan's decision (the service's
-     * segmentsbreakdown.md SB-6). The run stops in front of it, and `stopped`
-     * says so with the reason `decision`.
      */
     runAdHoc(scenario: SerializedScenario, prompt: string, wrapped: ReadonlySet<string>): Promise<{
         ok: boolean;
@@ -1117,23 +1051,10 @@ export declare class ReplayController {
      */
     private handOver;
     /**
-     * Which kind of stop a plan's end is (plan-services.md D8). The stopping
-     * step's own served reason wins — the calculation's verdict is more exact
-     * than a counter — then a call the service could not answer, then a parked
-     * step.
-     */
-    private stopKindOf;
-    /**
-     * A divergence's bundle that ended at the plan's decision (SB-17): logged
-     * as `handOver` logs every other hand-over, and its usage mark taken there
-     * when a step of the plan ran (SB-26).
-     */
-    private decidedInDivergence;
-    /**
-     * The steps before flat position `bound` that ran, 1-based, and the ones
-     * their tests left out (AC5) — the plan cursor's own, and a divergence
-     * bundle's (`extra`). `left` is empty when no step was left out; `ran` is
-     * then not filled, since every step before `bound` ran.
+     * The steps before position `bound` that ran, 1-based, and the ones their
+     * tests left out (AC5) — the plan cursor's own, and a divergence bundle's
+     * (`extra`). `left` is empty when no step was left out; `ran` is then not
+     * filled, since every step before `bound` ran.
      */
     private ranBefore;
     private noteFor;
@@ -1242,12 +1163,6 @@ export declare class ReplayController {
     /** Outcomes only move forward; `not_steered` is the floor (§11.1). */
     private upgrade;
     private retire;
-    /**
-     * Where the plan's work ended, for its bill: now, and the transcript's
-     * watermark now. Taken at a completing retire, and at a decision hand-over
-     * after a step ran (the service's segmentsbreakdown.md SB-26).
-     */
-    private markRetired;
 }
 /** The subset of `RunMatch` replay consumes. Structural, so tests need no recorder. */
 export interface RunMatchLike {
@@ -1259,11 +1174,6 @@ export interface RunMatchLike {
     fallback?: {
         maxStepFailures: number;
     };
-    /** All absent from an older server (segmented.md R-COMPAT-2). */
-    kind?: "scenario" | "segment";
-    segment?: MatchSegment;
-    key?: MatchKey;
-    verified?: MatchVerdict;
     /** The frozen name, beside the runtime intent the plan runs on (R-INTENT-12). */
     intentName?: string;
     /** Why the service handed over no plan, when it says. Read for `runner_update_required`. */
@@ -1282,8 +1192,7 @@ export declare function knownBadStepIndex(steps: readonly SerializedScenarioStep
  *
  * A step that carries `stop` was decided by the service — `null` means run it,
  * even when its count is past the limit: its retry is due. A step without the
- * field came from an older service, and the old counter rule decides it. Both
- * can sit in one chain, since a called segment is served on its own terms.
+ * field came from an older service, and the old counter rule decides it.
  */
 export declare function stopIndex(steps: readonly SerializedScenarioStep[], maxStepFailures: number | undefined): number | undefined;
 export {};