@basein/runner 0.3.2 → 0.3.4

package/README.md

@@ -347,6 +347,18 @@ bir scenario calc  scn_… --force --discard-edits           # recalculate this
 bir scenario editing on                                    # let Claude's `bir` tools change scenarios here
 ```
 
+**A value no prompt names.** Built 2026-09-28, not yet released. Every
+parameter is a *target* (a prompt must name it, or the plan is declined:
+`missing_target`) or a *setting* (its recorded value is used when a prompt
+names none). When the calculation made a database, a host or a working folder a
+target, the plan never runs. Make it a setting, with a note; a recalculation
+keeps the change ([the guide's §9.2](docs/calculatedReplayGuide.md)):
+
+```bash
+bir scenario edit  scn_… --param database --kind setting --note "why"   # use the recorded database when a prompt names none
+bir scenario undo  scn_… --param database                  # take that back
+```
+
 ---
 
 ## Two things to know before you turn it on
@@ -414,7 +426,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/bin/bir-scenario.js

@@ -442,6 +442,31 @@ function note(args) {
         throw new BadArguments("`note` must be a string");
     return ["--note", value];
 }
+/** `--revision <n>`, the chainRevision a change was made against. */
+function revision(args) {
+    const value = args.revision;
+    if (value === undefined || value === null)
+        return [];
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+        throw new BadArguments("`revision` must be a whole number from 1");
+    }
+    return ["--revision", String(value)];
+}
+const PARAM = {
+    type: "string",
+    description: "A parameter's name, as scenario_show lists it under `parameters` (for example `database`).",
+};
+/** A parameter's name: one argv element after `--param`, so it cannot read as a flag. */
+function param(args) {
+    const value = args.param;
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string" || value.length === 0 || value.length > 200 || /[\u0000-\u001f\u007f]/.test(value)) {
+        throw new BadArguments("`param` must be a parameter's name, as scenario_show lists it");
+    }
+    return value;
+}
+const given = (value) => value !== undefined && value !== null && value !== false;
 const SCENARIO_TOOLS = [
     {
         name: "scenario_show",
@@ -462,8 +487,8 @@ const SCENARIO_TOOLS = [
         name: "scenario_edits",
         changes: false,
         service: true,
-        description: "List a calculated scenario's hand edits, newest first: step, note, revision, and whether each was forced, " +
-            "undone or replaced by a recalculation.",
+        description: "List a calculated scenario's hand edits, newest first — step edits and parameter kind changes: step or " +
+            "parameter, note, revision, and whether each was forced, undone or replaced by a recalculation.",
         inputSchema: {
             type: "object",
             properties: { target: TARGET },
@@ -532,12 +557,24 @@ const SCENARIO_TOOLS = [
             "meanwhile is not overwritten. " +
             "`force` saves what the check refused and is only for a recording that was itself wrong — never a way past a " +
             "failing check. A save can be taken back with scenario_undo, which the service checks too: it refuses an undo " +
-            "that would break a later step, and a recalculation with --discard-edits replaces edits for good.",
+            "that would break a later step, and a recalculation with --discard-edits replaces edits for good. " +
+            "Instead of `step`, `param` with `kind` changes what a prompt must name: a target must be named or the plan is " +
+            "declined (missing_target); a setting uses its recorded value when a prompt names none — for a value that is the " +
+            "same every time, such as a database, a host or a working folder. Making one a setting needs `note`.",
         inputSchema: {
             type: "object",
             properties: {
                 target: TARGET,
                 step: STEP,
+                param: {
+                    ...PARAM,
+                    description: `${PARAM.description} Changes that parameter's kind (with \`kind\`) instead of a step. Not with \`step\`.`,
+                },
+                kind: {
+                    type: "string",
+                    enum: ["target", "setting"],
+                    description: "With `param`: target (a prompt must name it) or setting (its recorded value is used when a prompt names none; needs `note`).",
+                },
                 inputLogic: INPUT_LOGIC,
                 outputLogic: OUTPUT_LOGIC,
                 freeze: {
@@ -549,17 +586,34 @@ const SCENARIO_TOOLS = [
                     type: "boolean",
                     description: "Save although the check refused it. Needs `note`. Only when the recording itself was wrong.",
                 },
-                note: { type: "string", description: "Why the step is changed; kept in the history. Required with `force`." },
+                note: {
+                    type: "string",
+                    description: "Why the step (or the parameter's kind) is changed; kept in the history. Required with `force`, and to make a parameter a setting.",
+                },
                 revision: {
                     type: "integer",
                     minimum: 1,
                     description: "The chainRevision the change was made against — at the top of a scenario_show answer with `step`; the save is refused if the plan moved on.",
                 },
             },
-            required: ["target", "step"],
+            // `step`, or `param` with `kind`: which one is checked below, in words.
+            required: ["target"],
             additionalProperties: false,
         },
         plan: (a) => {
+            const name = param(a);
+            if (name !== undefined || given(a.kind)) {
+                // A parameter's kind (findoffer.md): nothing runs, so nothing of a step's belongs here.
+                if (name === undefined)
+                    throw new BadArguments("`kind` needs `param`: the parameter to change");
+                if (a.kind !== "target" && a.kind !== "setting")
+                    throw new BadArguments("`kind` must be target or setting");
+                for (const key of ["step", "inputLogic", "outputLogic", "freeze", "unfreeze", "force"]) {
+                    if (given(a[key]))
+                        throw new BadArguments(`\`param\` changes only a parameter's kind; \`${key}\` belongs to a step`);
+                }
+                return { argv: ["scenario", "edit", target(a), "--param", name, "--kind", a.kind, ...note(a), ...revision(a)] };
+            }
             if (a.freeze === true && a.unfreeze === true)
                 throw new BadArguments("`freeze` and `unfreeze` ask for opposite things");
             const argv = [
@@ -571,13 +625,7 @@ const SCENARIO_TOOLS = [
                 ...flag(a, "unfreeze", "--unfreeze"),
                 ...flag(a, "force", "--force"),
             ];
-            argv.push(...note(a));
-            if (a.revision !== undefined && a.revision !== null) {
-                if (typeof a.revision !== "number" || !Number.isInteger(a.revision) || a.revision < 1) {
-                    throw new BadArguments("`revision` must be a whole number from 1");
-                }
-                argv.push("--revision", String(a.revision));
-            }
+            argv.push(...note(a), ...revision(a));
             return { argv, inputLogic: logic(a, "inputLogic"), outputLogic: logic(a, "outputLogic") };
         },
     },
@@ -585,19 +633,27 @@ const SCENARIO_TOOLS = [
         name: "scenario_undo",
         changes: true,
         service: true,
-        description: "Take back a hand edit of a calculated scenario: its step goes back as it was before that edit. Without `edit`, " +
-            "the newest edit that can be undone (of `step`, when given); calling it again goes one further back. The service " +
-            "checks the undo like a save and refuses it when a later step or the final answer would break — `force` with a " +
-            "`note` undoes it anyway. To redo, undo the undo: pass its sedit_ id as `edit` (the answer names it).",
+        description: "Take back a hand edit of a calculated scenario: its step (or a parameter's kind) goes back as it was before that " +
+            "edit. Without `edit`, the newest edit that can be undone (of `step` or `param`, when given); calling it again goes " +
+            "one further back. The service checks a step's undo like a save and refuses it when a later step or the final " +
+            "answer would break — `force` with a `note` undoes it anyway. To redo, undo the undo: pass its id as `edit` (the " +
+            "answer names it).",
         inputSchema: {
             type: "object",
             properties: {
                 target: TARGET,
-                edit: { type: "string", description: "The sedit_ id to undo, as scenario_edits lists it. Not with `step`." },
+                edit: {
+                    type: "string",
+                    description: "The sedit_ or pedit_ id to undo, as scenario_edits lists it. Not with `step` or `param`.",
+                },
                 step: {
                     ...STEP,
                     description: "Undo the newest edit of this step (its stepIndex, as scenario_show prints it). Not with `edit`.",
                 },
+                param: {
+                    ...PARAM,
+                    description: `${PARAM.description} Undo the newest kind change of this parameter. Not with \`edit\` or \`step\`.`,
+                },
                 force: {
                     type: "boolean",
                     description: "Undo although the check refused it (a later step or the answer would break). Needs `note`.",
@@ -609,15 +665,21 @@ const SCENARIO_TOOLS = [
         },
         plan: (a) => {
             const argv = ["scenario", "undo", target(a)];
+            const name = param(a);
+            if (name !== undefined && (given(a.edit) || given(a.step))) {
+                throw new BadArguments("`edit`, `step` and `param` each pick what to undo; give one of them");
+            }
             if (a.edit !== undefined && a.edit !== null) {
-                if (typeof a.edit !== "string" || !/^sedit_[\w-]+$/.test(a.edit)) {
-                    throw new BadArguments("`edit` must be a sedit_… id");
+                if (typeof a.edit !== "string" || !/^(sedit|pedit)_[\w-]+$/.test(a.edit)) {
+                    throw new BadArguments("`edit` must be a sedit_… or pedit_… id");
                 }
                 if (a.step !== undefined && a.step !== null) {
                     throw new BadArguments("`edit` names one entry and `step` picks one; give one of them");
                 }
                 argv.push("--edit", a.edit);
             }
+            if (name !== undefined)
+                argv.push("--param", name);
             argv.push(...step(a, false), ...flag(a, "force", "--force"), ...note(a));
             return { argv };
         },

package/dist/bin/bir.d.ts

@@ -15,7 +15,8 @@
  *
  *   bir scenario list | show <runId|scnId> [--step <n>] | calc <runId|scnId> [--force [--discard-edits]]
  *   bir scenario check|edit <runId|scnId> --step <n> --input-logic <file|-> …   ← fix one step
- *   bir scenario edits | undo <runId|scnId> [--edit <sedit_id> | --step <n>] [--force --note "why"]
+ *   bir scenario edit <runId|scnId> --param <name> --kind target|setting …      ← what a prompt must name
+ *   bir scenario edits | undo <runId|scnId> [--edit <id> | --step <n> | --param <name>] [--force --note "why"]
  *   bir scenario editing on|off|status   ← may this project's `bir` MCP server change a scenario?
  *   bir scenario replay <scnId> --prompt "…" [--dry]  |  bir replay status|on|off|allow …
  *   bir investigate [<id>] | list | executions

package/dist/bin/bir.js

@@ -15,7 +15,8 @@
  *
  *   bir scenario list | show <runId|scnId> [--step <n>] | calc <runId|scnId> [--force [--discard-edits]]
  *   bir scenario check|edit <runId|scnId> --step <n> --input-logic <file|-> …   ← fix one step
- *   bir scenario edits | undo <runId|scnId> [--edit <sedit_id> | --step <n>] [--force --note "why"]
+ *   bir scenario edit <runId|scnId> --param <name> --kind target|setting …      ← what a prompt must name
+ *   bir scenario edits | undo <runId|scnId> [--edit <id> | --step <n> | --param <name>] [--force --note "why"]
  *   bir scenario editing on|off|status   ← may this project's `bir` MCP server change a scenario?
  *   bir scenario replay <scnId> --prompt "…" [--dry]  |  bir replay status|on|off|allow …
  *   bir investigate [<id>] | list | executions
@@ -109,10 +110,14 @@ Commands:
   scenario edit <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->]
                 [--freeze | --unfreeze] [--note "why"] [--force --note "why"] [--revision <n>]
                                     the same check, and save the change if it passes
+  scenario edit <runId|scnId> --param <name> --kind target|setting [--note "why"]
+                                    a target must be named by the prompt or the plan is
+                                    declined; a setting uses its recorded value when the
+                                    prompt names none (needs --note)
   scenario edits <runId|scnId>      a scenario's hand edits, newest first
-  scenario undo <runId|scnId> [--edit <sedit_id> | --step <n>] [--force --note "why"]
-                                    take back the newest edit (of step n); run it again to go
-                                    one further back; undo an undo's sedit_ id to redo
+  scenario undo <runId|scnId> [--edit <id> | --step <n> | --param <name>] [--force --note "why"]
+                                    take back the newest edit (of step n, or parameter name);
+                                    run it again to go one further back; undo an undo's id to redo
   scenario editing on|off|status    whether this project's bir MCP server offers the tools
                                     that change a scenario (restart Claude Code after)
   scenario replay <scnId> --prompt "…" [--dry]
@@ -156,7 +161,10 @@ Options:
   --unfreeze        scenario check|edit: ask to remove that mark; the check decides
   --note <text>     scenario edit|undo: why, kept in the history (required with --force)
   --revision <n>    scenario edit|undo: only if the plan is still at this chainRevision
-  --edit <id>       scenario undo: the sedit_ id to undo (default: the newest edit that can be)
+  --edit <id>       scenario undo: the sedit_ or pedit_ id to undo (default: the newest that can be)
+  --param <name>    scenario edit: the parameter whose kind changes · scenario undo: its newest change
+  --kind <kind>     scenario edit --param: target (a prompt must name it) or setting (its
+                    recorded value is used when a prompt names none; needs --note)
   --discard-edits   scenario calc --force: recalculate a plan with hand edits, replacing them
   --no-browser      login: print the link and code, open nothing (SSH, headless)
   --token <value>   login: redeem a one-time setup token from the console (no browser)
@@ -355,6 +363,18 @@ function parseArgs(argv) {
             case "--discard-edits":
                 args.discardEdits = true;
                 break;
+            case "--param":
+                // A value flag, like --note: the name is whatever follows, and
+                // scenario-edit.ts says what is wrong with it in words.
+                args.param = argv[++i];
+                if (!args.param)
+                    usage(2);
+                break;
+            case "--kind":
+                args.kind = argv[++i];
+                if (!args.kind)
+                    usage(2);
+                break;
             case "--here":
                 args.here = true;
                 break;
@@ -3374,6 +3394,8 @@ async function scenarioCommand(args) {
             edit: args.edit,
             revision: args.revision,
             discardEdits: args.discardEdits,
+            param: args.param,
+            kind: args.kind,
         }, {
             cwd: process.cwd(),
             out,

package/dist/bin/investigate.js

@@ -191,8 +191,8 @@ export const DECLINES = {
         fix: "enable or recalculate that sub-task, or recalculate this scenario.",
     },
     missing_target: {
-        cause: "the prompt names a target the runner could not find where the recording had it.",
-        fix: "run from the recording's directory, or name the target as the recording did.",
+        cause: "the plan needs a target — a value a prompt must name, such as a file, a table or a region — and the prompt did not name it. A replay never takes a target from the recording.",
+        fix: 'name it in the prompt. If the value is the same every time — a database, a host, a working folder — it is a setting, not a target: `bir scenario edit <scnId> --param <name> --kind setting --note "why"` lets the runner use its recorded value when a prompt names none (`bir scenario show <scnId>` lists the parameters and their kinds).',
     },
     no_derive_key: {
         cause: "the scenario has parameters and the runner had no way to derive them: no service session and no ANTHROPIC_API_KEY.",
@@ -203,6 +203,22 @@ export const DECLINES = {
         fix: "recalculate the scenario.",
     },
 };
+/**
+ * The `missing_target` fix with what this turn knows put in: the scenario, and
+ * the target the gate named (`target database not found`). The code alone once
+ * sent a reader after a lookup that failed, when the prompt had simply not
+ * named the value.
+ */
+function missingTargetFix(fix, turn) {
+    let text = fix;
+    const scenarioId = turn.matched?.scenarioId ?? turn.plan?.scenarioId;
+    if (scenarioId)
+        text = text.replaceAll("<scnId>", scenarioId);
+    const name = /\btarget (\S+) not found/.exec(turn.decision?.why ?? "")?.[1];
+    if (name)
+        text = text.replaceAll("<name>", name);
+    return text;
+}
 export const LOW_SAVING_PCT = 0.3;
 const usd = (v) => `$${v.toFixed(4)}`;
 const pct = (v) => `${(v * 100).toFixed(1)}%`;
@@ -225,7 +241,7 @@ export function localFindings(turn) {
             severity: code === "not_ready" && !turn.matched.scenarioId ? "info" : "problem",
             title: `Matched ${turn.matched.runId} but declined to steer: ${turn.decision.why ?? code}.`,
             cause: known?.cause ?? "the runner's log line carries the reason text.",
-            fix: known?.fix ??
+            fix: (known && code === "missing_target" ? missingTargetFix(known.fix, turn) : known?.fix) ??
                 (turn.matched.scenarioId
                     ? "read the `replay.decision` line above."
                     : "the matched recording has no scenario yet — calculate it, or let the service pick it up after enough hits."),

package/dist/bin/scenario-edit.d.ts

@@ -6,8 +6,9 @@
  *   bir scenario check <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->] [--unfreeze]
  *   bir scenario edit  <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->]
  *                      [--freeze | --unfreeze] [--note "why"] [--force --note "why"] [--revision <n>]
+ *   bir scenario edit  <runId|scnId> --param <name> --kind target|setting [--note "why"] [--revision <n>]
  *   bir scenario edits <runId|scnId>
- *   bir scenario undo  <runId|scnId> [--edit <sedit_id> | --step <n>] [--force --note "why"]
+ *   bir scenario undo  <runId|scnId> [--edit <sedit_id|pedit_id> | --step <n> | --param <name>] [--force --note "why"]
  *   bir scenario calc  <runId|scnId> [--force [--discard-edits]]
  *   bir scenario editing on|off|status
  *
@@ -23,6 +24,12 @@
  * of quotes, braces and `$`, and every shell mangles a different subset of
  * them; a file, or stdin with `-`, arrives byte for byte.
  *
+ * A parameter's kind (`--param <name> --kind target|setting`, findoffer.md in
+ * the BaseIn repository) is the one change here that runs no code: a target
+ * is a value a prompt must name, and the plan is declined without it; a
+ * setting takes its recorded value when a prompt names none. Making one a
+ * setting needs a note, because it is exactly what a target forbids.
+ *
  * Everything the commands touch is injected ({@link ScenarioEditDeps}), as in
  * `investigate.ts`, so all of it is tested in-process against a fake service.
  * The exception is `editing`, which writes the install sidecar — tests point
@@ -107,6 +114,30 @@ export interface EditEntry {
     /** A recalculation replaced the chain; the entry is history now. */
     replacedAt: string | null;
 }
+/** A parameter's kind: a prompt must name a target; a setting takes its recorded value when none does. */
+export type ParamKind = "target" | "setting";
+/** A parameter's kind changed by hand, or such a change undone: the service's `paramEdits` (findoffer.md). */
+export interface ParamEditEntry {
+    id: string;
+    scenarioId: string;
+    param: string;
+    kind: "edit" | "revert";
+    revertsEditId: string | null;
+    note: string | null;
+    chainRevisionBefore: number;
+    chainRevisionAfter: number;
+    /** `null` is no kind, which reads as a target. */
+    before: {
+        kind: ParamKind | null;
+    };
+    after: {
+        kind: ParamKind | null;
+    };
+    createdAt: string;
+    revertedAt: string | null;
+    /** A recalculation dropped the parameter; the entry is history now. */
+    replacedAt: string | null;
+}
 export type ServiceReply = {
     status: number;
     body: unknown;
@@ -135,11 +166,15 @@ export interface ScenarioEditArgs {
     freeze: boolean;
     unfreeze: boolean;
     note?: string;
-    /** `undo --edit`: the `sedit_` id to put back. `undo --step` is {@link step}. */
+    /** `undo --edit`: the `sedit_` (or `pedit_`) id to put back. `undo --step` is {@link step}. */
     edit?: string;
     /** `--revision`: save only if the plan is still at this `chainRevision`. */
     revision?: number;
     discardEdits: boolean;
+    /** `edit --param <name>`: the parameter whose kind changes; `undo --param`: its newest change. */
+    param?: string;
+    /** `edit --kind target|setting`, with `--param`. Checked here, so any word reaches the usage line. */
+    kind?: string;
 }
 /** The `bir scenario` words this module answers; `list` and `replay` stay in bir.ts. */
 export declare const SCENARIO_EDIT_SUBCOMMANDS: ReadonlySet<string>;
@@ -202,5 +237,7 @@ export declare function around(text: string, at: number): string;
  * question, not this list's: it answers `not_latest_edit` when it is not.
  */
 export declare function newestUndoable(edits: EditEntry[], step?: number): EditEntry | undefined;
+/** {@link newestUndoable} for kind changes: the newest that stands, of `param` when it is given. */
+export declare function newestUndoableParam(paramEdits: ParamEditEntry[], param?: string): ParamEditEntry | undefined;
 export {};
 //# sourceMappingURL=scenario-edit.d.ts.map

package/dist/bin/scenario-edit.js

@@ -6,8 +6,9 @@
  *   bir scenario check <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->] [--unfreeze]
  *   bir scenario edit  <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->]
  *                      [--freeze | --unfreeze] [--note "why"] [--force --note "why"] [--revision <n>]
+ *   bir scenario edit  <runId|scnId> --param <name> --kind target|setting [--note "why"] [--revision <n>]
  *   bir scenario edits <runId|scnId>
- *   bir scenario undo  <runId|scnId> [--edit <sedit_id> | --step <n>] [--force --note "why"]
+ *   bir scenario undo  <runId|scnId> [--edit <sedit_id|pedit_id> | --step <n> | --param <name>] [--force --note "why"]
  *   bir scenario calc  <runId|scnId> [--force [--discard-edits]]
  *   bir scenario editing on|off|status
  *
@@ -23,6 +24,12 @@
  * of quotes, braces and `$`, and every shell mangles a different subset of
  * them; a file, or stdin with `-`, arrives byte for byte.
  *
+ * A parameter's kind (`--param <name> --kind target|setting`, findoffer.md in
+ * the BaseIn repository) is the one change here that runs no code: a target
+ * is a value a prompt must name, and the plan is declined without it; a
+ * setting takes its recorded value when a prompt names none. Making one a
+ * setting needs a note, because it is exactly what a target forbids.
+ *
  * Everything the commands touch is injected ({@link ScenarioEditDeps}), as in
  * `investigate.ts`, so all of it is tested in-process against a fake service.
  * The exception is `editing`, which writes the install sidecar — tests point
@@ -56,9 +63,10 @@ const USAGE = {
     show: "usage: bir scenario show <runId|scnId> [--step <n>]",
     check: "usage: bir scenario check <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->] [--unfreeze] [--json]",
     edit: "usage: bir scenario edit <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->]\n" +
-        '                          [--freeze | --unfreeze] [--note "why"] [--force --note "why"] [--revision <n>] [--json]',
+        '                          [--freeze | --unfreeze] [--note "why"] [--force --note "why"] [--revision <n>] [--json]\n' +
+        '       bir scenario edit <runId|scnId> --param <name> --kind target|setting [--note "why"] [--revision <n>] [--json]',
     edits: "usage: bir scenario edits <runId|scnId> [--json]",
-    undo: 'usage: bir scenario undo <runId|scnId> [--edit <sedit_id> | --step <n>] [--force --note "why"] [--json]',
+    undo: 'usage: bir scenario undo <runId|scnId> [--edit <sedit_id|pedit_id> | --step <n> | --param <name>] [--force --note "why"] [--json]',
     calc: "usage: bir scenario calc <runId|scnId> [--force [--discard-edits]]",
     editing: "usage: bir scenario editing on|off|status",
 };
@@ -141,8 +149,16 @@ async function checkOrEdit(args, deps, save) {
     const target = args.positionals[1];
     if (!target)
         return usageError(deps, sub);
+    if (args.param !== undefined || args.kind !== undefined) {
+        if (!save) {
+            return usageError(deps, sub, "A parameter's kind is not checked: no code runs. Save it with `bir scenario edit <id> --param <name> --kind target|setting`.");
+        }
+        return editParam(target, args, deps);
+    }
     if (args.step === undefined) {
-        return usageError(deps, sub, "Which step? Give --step <n>, the stepIndex `bir scenario show` prints.");
+        return usageError(deps, sub, save
+            ? "Which step? Give --step <n>, the stepIndex `bir scenario show` prints — or --param <name> --kind target|setting to change a parameter."
+            : "Which step? Give --step <n>, the stepIndex `bir scenario show` prints.");
     }
     if (!save && (args.freeze || args.force)) {
         return usageError(deps, sub, "`check` never saves, so --freeze and --force belong to `bir scenario edit`.");
@@ -254,6 +270,90 @@ async function checkOrEdit(args, deps, save) {
     }
     return 0;
 }
+/** A kind in the words the history uses; no kind reads as a target, as it does in the gate. */
+const kindWord = (kind) => (kind ? kind : "no kind (a target)");
+/** What the new kind means for the next prompt, in one line. */
+function kindMeaning(name, kind, sample) {
+    if (kind === "setting") {
+        const text = JSON.stringify(sample);
+        const shown = text === undefined ? "" : ` (${text.length > 60 ? `${text.slice(0, 59)}…` : text})`;
+        return `When a prompt names no ${name}, the runner now uses its recorded value${shown}; a prompt that names one still wins.`;
+    }
+    return `A prompt must now name ${name}, or the runner declines the plan (missing_target).`;
+}
+/**
+ * `edit --param <name> --kind target|setting` (findoffer.md). Nothing runs, so
+ * there is no check to print: the service answers with the change, and this
+ * says what it means for the next prompt. Every flag that belongs to a step is
+ * refused before any request, and so is a setting without a note — the one
+ * direction that lets a replay use a recorded value.
+ */
+async function editParam(target, args, deps) {
+    const { out } = deps;
+    const name = args.param;
+    if (name === undefined || name === "") {
+        return usageError(deps, "edit", "--kind needs --param <name>: the parameter to change, as `bir scenario show` lists it.");
+    }
+    if (args.step !== undefined) {
+        return usageError(deps, "edit", "--param changes a parameter and --step a step; give one of them.");
+    }
+    if (args.inputLogic || args.outputLogic || args.freeze || args.unfreeze || args.force) {
+        return usageError(deps, "edit", "--param changes only a parameter's kind; --input-logic, --output-logic, --freeze, --unfreeze and --force belong to a step (--step).");
+    }
+    if (args.kind !== "target" && args.kind !== "setting") {
+        return usageError(deps, "edit", args.kind === undefined ? "Which kind? Give --kind setting or --kind target." : `--kind is target or setting; got ${args.kind}.`);
+    }
+    const kind = args.kind;
+    const note = args.note?.trim() ? args.note : undefined;
+    if (kind === "setting" && !note) {
+        return usageError(deps, "edit", '--kind setting needs --note "why" (note_required): a setting lets the runner use the recorded value when a prompt names none, and the history keeps why.');
+    }
+    const resolved = await resolveTarget(target, args, deps);
+    if ("code" in resolved)
+        return resolved.code;
+    const body = { kind };
+    if (note)
+        body.note = note;
+    if (args.revision !== undefined)
+        body.expectedRevision = args.revision;
+    const reply = await deps.service("PATCH", `/scenarios/${seg(resolved.id)}/params/${seg(name)}`, body);
+    if ("error" in reply || reply.status !== 200)
+        return explainParam(reply, args, deps, target, "Not saved");
+    if (args.json) {
+        out(jsonText(reply.body));
+        return 0;
+    }
+    const answer = reply.body;
+    const edit = answer?.edit;
+    const revision = answer?.chainRevision ?? edit?.chainRevisionAfter;
+    out(`Parameter ${name}: ${kindWord(edit?.before.kind)} → ${kindWord(edit?.after.kind ?? kind)} (revision ${revision ?? "?"}).` +
+        (edit?.id ? ` Undo: bir scenario undo ${target} --edit ${edit.id}` : ""));
+    out(`  ${kindMeaning(name, edit?.after.kind ?? kind, answer?.parameter?.sampleValue)}`);
+    return 0;
+}
+/**
+ * The answers a kind change has words of its own for; everything else as
+ * {@link explain} says it. A 404 here is most often a name that is not the
+ * scenario's, so it says where the names are.
+ */
+function explainParam(reply, args, deps, target, verb) {
+    if (!("error" in reply) && !args.json) {
+        const code = reply.body?.error;
+        if (reply.status === 404) {
+            deps.out(`${verb} (not_found): ${target} has no parameter ${args.param}, or it is not yours. \`bir scenario show ${target}\` lists its parameters.`);
+            return 1;
+        }
+        if (code === "nothing_to_change") {
+            deps.out(`Nothing to change: ${args.param} is already a ${args.kind}.`);
+            return 1;
+        }
+        if (code === "note_required") {
+            deps.out(`${verb} (note_required): making a parameter a setting needs --note "why".`);
+            return 1;
+        }
+    }
+    return explain(reply, args, deps, { verb, target, param: args.param });
+}
 /** What `check` printed, turned into the `edit` that would save it. */
 function editCommand(target, args) {
     const parts = ["bir scenario edit", target, "--step", String(args.step)];
@@ -495,12 +595,19 @@ function refusal(out, report, opening, hint) {
     out(hint);
 }
 // ── edits / undo ──────────────────────────────────────────────────────────────
+/** The service's history: step edits, and — from a service that has them — kind changes. */
+function historyOf(body) {
+    const b = body;
+    return {
+        edits: Array.isArray(b?.edits) ? b.edits : [],
+        paramEdits: Array.isArray(b?.paramEdits) ? b.paramEdits : [],
+    };
+}
 async function fetchEdits(scenarioId, deps) {
     const reply = await readWithin(deps.service("GET", `/scenarios/${seg(scenarioId)}/edits`));
     if ("error" in reply || reply.status !== 200)
         return { reply };
-    const edits = reply.body?.edits;
-    return { edits: Array.isArray(edits) ? edits : [] };
+    return historyOf(reply.body);
 }
 async function listEdits(args, deps) {
     const { out } = deps;
@@ -521,21 +628,46 @@ async function listEdits(args, deps) {
         out(jsonText(reply.body));
         return 0;
     }
-    const edits = reply.body?.edits ?? [];
-    if (edits.length === 0) {
+    const { edits, paramEdits } = historyOf(reply.body);
+    if (edits.length === 0 && paramEdits.length === 0) {
         out(`No hand edits of ${target}.`);
         return 0;
     }
     // Ids are printed whole: they are what `undo --edit` takes. The detail line
     // is indented rather than aligned under the date, which a 42-character id
-    // would push past most terminals' width.
-    for (const e of edits) {
-        const note = e.note ? `  "${e.note.replace(/\s+/g, " ")}"` : "";
-        out(`${e.id}  ${when(e.createdAt)}  step ${e.stepIndex}  ${String(e.kind).padEnd(7)} revision ${e.chainRevisionBefore} → ${e.chainRevisionAfter}${note}`);
-        out(`    ${editSummary(e)}`);
+    // would push past most terminals' width. One list, newest first: a step's
+    // edits and a parameter's kind changes are walked back by the same `undo`.
+    const noteOf = (note) => (note ? `  "${note.replace(/\s+/g, " ")}"` : "");
+    const rows = [
+        ...edits.map((e) => ({
+            at: e.createdAt,
+            line: `${e.id}  ${when(e.createdAt)}  step ${e.stepIndex}  ${String(e.kind).padEnd(7)} revision ${e.chainRevisionBefore} → ${e.chainRevisionAfter}${noteOf(e.note)}`,
+            detail: editSummary(e),
+        })),
+        ...paramEdits.map((p) => ({
+            at: p.createdAt,
+            line: `${p.id}  ${when(p.createdAt)}  param ${p.param}  ${String(p.kind).padEnd(7)} revision ${p.chainRevisionBefore} → ${p.chainRevisionAfter}${noteOf(p.note)}`,
+            detail: paramSummary(p),
+        })),
+    ].sort((x, y) => (x.at < y.at ? 1 : x.at > y.at ? -1 : 0));
+    for (const r of rows) {
+        out(r.line);
+        out(`    ${r.detail}`);
     }
     return 0;
 }
+/** The second line of a kind change in `edits`: the kinds, and what became of it. */
+function paramSummary(p) {
+    const parts = [];
+    if (p.kind === "revert" && p.revertsEditId)
+        parts.push(`undoes ${p.revertsEditId}`);
+    parts.push(`${kindWord(p.before?.kind)} → ${kindWord(p.after?.kind)}`);
+    if (p.revertedAt)
+        parts.push(`undone ${when(p.revertedAt)}`);
+    if (p.replacedAt)
+        parts.push(`the parameter was dropped by a recalculation ${when(p.replacedAt)}`);
+    return parts.join("; ");
+}
 /** The second line of an `edits` entry: what the edit changed, and what became of it. */
 function editSummary(e) {
     const parts = [];
@@ -584,16 +716,29 @@ export function newestUndoable(edits, step) {
         !e.replacedAt &&
         (step === undefined || e.stepIndex === step));
 }
+/** {@link newestUndoable} for kind changes: the newest that stands, of `param` when it is given. */
+export function newestUndoableParam(paramEdits, param) {
+    return [...paramEdits]
+        .sort((x, y) => (x.createdAt < y.createdAt ? 1 : x.createdAt > y.createdAt ? -1 : 0))
+        .find((e) => e.kind !== "revert" && !e.revertedAt && !e.replacedAt && (param === undefined || e.param === param));
+}
+const isParamEditId = (id) => id.startsWith("pedit_");
 async function undo(args, deps) {
     const { out } = deps;
     const target = args.positionals[1];
     if (!target)
         return usageError(deps, "undo");
-    if (args.edit !== undefined && !/^sedit_[\w-]+$/.test(args.edit)) {
-        return usageError(deps, "undo", `--edit takes a sedit_… id, as \`bir scenario edits\` prints it; got ${args.edit}.`);
+    if (args.edit !== undefined && !/^(sedit|pedit)_[\w-]+$/.test(args.edit)) {
+        return usageError(deps, "undo", `--edit takes a sedit_… or pedit_… id, as \`bir scenario edits\` prints it; got ${args.edit}.`);
+    }
+    const picks = [args.edit, args.step, args.param].filter((v) => v !== undefined).length;
+    if (picks > 1) {
+        return usageError(deps, "undo", args.param === undefined
+            ? "--edit names one entry and --step picks one; give one of them."
+            : "--edit names one entry, --step picks a step's newest edit and --param a parameter's; give one of them.");
     }
-    if (args.edit !== undefined && args.step !== undefined) {
-        return usageError(deps, "undo", "--edit names one entry and --step picks one; give one of them.");
+    if (args.kind !== undefined) {
+        return usageError(deps, "undo", "An undo puts back the kind that was there; --kind belongs to `bir scenario edit --param`.");
     }
     const note = args.note?.trim() ? args.note : undefined;
     if (args.force && !note) {
@@ -609,11 +754,17 @@ async function undo(args, deps) {
         const listed = await fetchEdits(resolved.id, deps);
         if ("reply" in listed)
             return explain(listed.reply, args, deps, { verb: "Could not read the history", target });
-        const pick = newestUndoable(listed.edits, args.step);
+        // Undo walks back across both lists (D9): the newest change of either
+        // kind goes first, unless --step or --param narrows it to one.
+        const stepPick = args.param === undefined ? newestUndoable(listed.edits, args.step) : undefined;
+        const paramPick = args.step === undefined ? newestUndoableParam(listed.paramEdits, args.param) : undefined;
+        const pick = !stepPick ? paramPick : !paramPick ? stepPick : paramPick.createdAt > stepPick.createdAt ? paramPick : stepPick;
         if (!pick) {
-            return localFailure(args, deps, "nothing_to_undo", args.step === undefined
-                ? `Nothing to undo: ${target} has no hand edit that can be undone.`
-                : `Nothing to undo: step ${args.step} of ${target} has no hand edit that can be undone.`);
+            return localFailure(args, deps, "nothing_to_undo", args.step !== undefined
+                ? `Nothing to undo: step ${args.step} of ${target} has no hand edit that can be undone.`
+                : args.param !== undefined
+                    ? `Nothing to undo: parameter ${args.param} of ${target} has no kind change that can be undone.`
+                    : `Nothing to undo: ${target} has no hand edit that can be undone.`);
         }
         editId = pick.id;
     }
@@ -633,12 +784,15 @@ async function undo(args, deps) {
             target,
             editId,
             notFound: `Not undone (not_found): ${target} has no edit ${editId}, or it is not yours.`,
+            param: args.param,
         });
     }
     if (args.json) {
         out(jsonText(reply.body));
         return refused ? 1 : 0;
     }
+    if (isParamEditId(editId))
+        return paramUndone(reply.body, editId, target, args, deps);
     if (answer?.report)
         renderReport(out, answer.report, { brief: true, undo: true });
     if (refused && answer?.report) {
@@ -666,6 +820,22 @@ async function undo(args, deps) {
     }
     return 0;
 }
+/**
+ * A kind change undone. Nothing ran, so there is no report: the parameter's
+ * kind as it is now, what that means for the next prompt, and the way on —
+ * redo, or one further back (of that parameter, when one was named).
+ */
+function paramUndone(answer, editId, target, args, deps) {
+    const entry = answer?.edit;
+    const revision = answer?.chainRevision ?? entry?.chainRevisionAfter;
+    const name = entry?.param ?? answer?.parameter?.name ?? args.param ?? "?";
+    deps.out(`Parameter ${name} is back to ${kindWord(entry?.after.kind)}, as it was before ${entry?.revertsEditId ?? editId} (revision ${revision ?? "?"}).` +
+        (entry?.id ? ` Redo: bir scenario undo ${target} --edit ${entry.id}` : ""));
+    deps.out(`  ${kindMeaning(name, entry?.after.kind, answer?.parameter?.sampleValue)}`);
+    const further = args.param !== undefined || args.edit !== undefined ? ` --param ${name}` : "";
+    deps.out(`  One further back: bir scenario undo ${target}${further}`);
+    return 0;
+}
 // ── calc ──────────────────────────────────────────────────────────────────────
 /**
  * `calc` lives here because of one answer: a recalculation rebuilds every
@@ -885,6 +1055,8 @@ function explain(reply, args, deps, e) {
     const code = typeof body.error === "string" ? body.error : "";
     const target = e.target ?? "<id>";
     const stepFlag = e.step !== undefined ? ` --step ${e.step}` : "";
+    // A kind change (findoffer.md) is about a parameter, and nothing in it is checked.
+    const aboutParam = e.param !== undefined || (e.editId?.startsWith("pedit_") ?? false);
     if (reply.status === 404) {
         out(e.notFound ??
             `${e.verb} (not_found): no such scenario, step or edit — or it is not yours. Only a scenario's owner can see or change it.`);
@@ -928,7 +1100,9 @@ function explain(reply, args, deps, e) {
             return 1;
         case "revision_changed": {
             const now = typeof body.chainRevision === "number" ? ` — it is at revision ${body.chainRevision} now` : "";
-            out(`${e.verb} (revision_changed): the plan changed since it was read${now}. Show it again (\`bir scenario show ${target}${stepFlag}\`), check again, then save again.`);
+            out(aboutParam
+                ? `${e.verb} (revision_changed): the plan changed since it was read${now}. Show it again (\`bir scenario show ${target}\`), then try again.`
+                : `${e.verb} (revision_changed): the plan changed since it was read${now}. Show it again (\`bir scenario show ${target}${stepFlag}\`), check again, then save again.`);
             return 1;
         }
         case "not_latest_edit": {
@@ -936,7 +1110,7 @@ function explain(reply, args, deps, e) {
             // newer entry puts the step back as this one left it, and then this one
             // can be undone. It used to loop, when undo only toggled (C23).
             const latest = typeof body.latestEditId === "string" ? body.latestEditId : "<the newer edit>";
-            out(`${e.verb} (not_latest_edit): the step has changed since that edit — ${latest} changed it after. Undo the newer one first, then this one:`);
+            out(`${e.verb} (not_latest_edit): the ${aboutParam ? "parameter" : "step"} has changed since that edit — ${latest} changed it after. Undo the newer one first, then this one:`);
             out(`  bir scenario undo ${target} --edit ${latest}`);
             out(`  bir scenario undo ${target} --edit ${e.editId ?? "<this edit>"}`);
             return 1;
@@ -948,7 +1122,9 @@ function explain(reply, args, deps, e) {
             return 1;
         }
         case "edit_replaced":
-            out(`${e.verb} (edit_replaced): a recalculation replaced the plan after that edit. It stays in \`bir scenario edits\`, but there is nothing left to undo.`);
+            out(aboutParam
+                ? `${e.verb} (edit_replaced): a recalculation dropped that parameter after the change. It stays in \`bir scenario edits\`, but there is nothing left to undo.`
+                : `${e.verb} (edit_replaced): a recalculation replaced the plan after that edit. It stays in \`bir scenario edits\`, but there is nothing left to undo.`);
             return 1;
         case "rate_limited": {
             const ms = typeof body.retryAfterMs === "number" ? body.retryAfterMs : undefined;

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 |
 
@@ -630,8 +630,9 @@ bir scenario show  <runId|scnId> [--step <n>]
 bir scenario check <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->] [--unfreeze]
 bir scenario edit  <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->]
                    [--freeze | --unfreeze] [--note "<why>"] [--force --note "<why>"] [--revision <n>]
+bir scenario edit  <runId|scnId> --param <name> --kind target|setting [--note "<why>"] [--revision <n>]
 bir scenario edits <runId|scnId>
-bir scenario undo  <runId|scnId> [--edit <sedit_id> | --step <n>] [--force --note "<why>"]
+bir scenario undo  <runId|scnId> [--edit <sedit_id|pedit_id> | --step <n> | --param <name>] [--force --note "<why>"]
 bir scenario calc  <runId|scnId> [--force [--discard-edits]]
 bir scenario editing on|off|status
 ```
@@ -666,8 +667,9 @@ never take, is never reached in the check. A `fetch` inside a `try` fails in the
 code in its own process, with the global scope and only a time limit, where `fetch` and `process`
 do exist. So read every change before it is saved — yours and Claude's.
 
-**Only a step's code and its mark can be changed.** Not the parameters, not their sample values, not
-the logic that builds the final answer. Only tool steps: a sub-task call row belongs to the service.
+**Only a step's code and its mark can be changed — and a parameter's kind (below, *A value no prompt names*).**
+Not the parameters' sample values, not the logic that builds the final answer. Only tool steps: a
+sub-task call row belongs to the service.
 
 #### The fix, step by step
 
@@ -1047,8 +1049,8 @@ The tools, as the `bir` server defines them. **Bold** arguments are required.
 | `scenario_edits` | after `bir scenario editing on`, or with `BIR_SCENARIO_TOOLS=read` | **`target`** | `bir scenario edits` |
 | `investigate` | after `bir scenario editing on`, or with `BIR_SCENARIO_TOOLS=read` | `id` — a `run_`, `scn_` or `sexec_` id; without it, the newest turn here | `bir investigate` |
 | `scenario_check` | after `bir scenario editing on` | **`target`**, **`step`**, `inputLogic`, `outputLogic`, `unfreeze` | `bir scenario check` |
-| `scenario_edit` | after `bir scenario editing on` | **`target`**, **`step`**, `inputLogic`, `outputLogic`, `freeze`, `unfreeze`, `force`, `note`, `revision` | `bir scenario edit` |
-| `scenario_undo` | after `bir scenario editing on` | **`target`**, `edit` or `step` (not both), `force`, `note` | `bir scenario undo` |
+| `scenario_edit` | after `bir scenario editing on` | **`target`**, and **`step`** with `inputLogic`, `outputLogic`, `freeze`, `unfreeze`, `force` — or **`param`** with **`kind`**; `note`, `revision` | `bir scenario edit` |
+| `scenario_undo` | after `bir scenario editing on` | **`target`**, one of `edit`, `step` or `param`, `force`, `note` | `bir scenario undo` |
 
 - `target` is a `scn_` id, or the `run_` id of a whole-run scenario. `step` is the `stepIndex`.
 - `inputLogic` and `outputLogic` are the code itself, as text. The server writes them to temporary
@@ -1095,6 +1097,59 @@ For the hiring-year case, Claude's report would be: *step 4's code is a copy of
 so it was marked; the new code builds the query from `summary_table`; the check says it reproduces
 the recording, and the step will run by itself.*
 
+#### A value no prompt names — `--param <name> --kind setting`
+
+> Built 2026-09-28, **not yet released**: it needs the next service deploy, then the next
+> `@basein/runner` version. The design is `findoffer.md` and `editSteps.md` ("Parameter kinds") in
+> the BaseIn repository.
+
+Every parameter of a plan is one of two kinds:
+
+| Kind | Means | When the prompt does not name it |
+|---|---|---|
+| **target** | what the task acts on — a file, a table, a region | the plan is declined: `missing_target`. A target is never guessed |
+| **setting** | a value nobody states, the same every time — a database, a host, a working folder | the recorded value is used |
+
+A prompt that names a value always wins, whatever its kind. The calculation decides the kinds, and
+it can get one wrong. The hiring-year plan `scn_09dbd4e6` never ran: its `database` was a target,
+and the MCPMark prompt never names the database — it is simply the one the agent is connected to.
+`bir investigate` names such a target: `declined … missing_target (database not named in the
+prompt)`.
+
+**Do this.** Make it a setting, and say why:
+
+```bash
+bir scenario edit scn_09dbd4e6-… --param database --kind setting --note "The database is the connection; the prompt never names it."
+```
+
+**You should see:**
+
+```
+Parameter database: target → setting (revision 4). Undo: bir scenario undo scn_09dbd4e6-… --edit pedit_…
+  When a prompt names no database, the runner now uses its recorded value ("hys_trial"); a prompt that names one still wins.
+```
+
+- `--kind setting` needs `--note`: it is the one change that lets a replay use a recorded value.
+  `--kind target` does not.
+- No code runs, so nothing is checked. The revision goes up by one, as for a step edit.
+- **A recalculation keeps the kind** while the parameter keeps its name, so unlike a step edit it
+  does not hold a recalculation back. When a recalculation drops the parameter, the change is
+  history.
+- `bir scenario edits` lists it as `param database`, and `bir investigate` reports it on every run
+  (`param_kind_edited`).
+- `bir scenario undo … --param database` takes it back. A plain `bir scenario undo` takes back the
+  newest change, a step's or a parameter's.
+- The `scenario_edit` tool takes `param` and `kind` instead of `step`; `scenario_undo` takes `param`.
+
+**If it goes wrong:**
+
+| Symptom | Fix |
+|---|---|
+| `--kind setting needs --note "why" (note_required)` | Add `--note "why"` |
+| `Not saved (not_found): … has no parameter …` | Use a name that `bir scenario show <id>` lists under `parameters` |
+| `Nothing to change: database is already a setting.` | Nothing to do |
+| `A parameter's kind is not checked` | `check` runs code, and a kind has none. Use `bir scenario edit` |
+
 #### When it does not work
 
 | Symptom | Cause | Fix |

package/package.json

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