@basein/runner 0.3.3 → 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

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/docs/calculatedReplayGuide.md

@@ -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.3",
+  "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",