@basein/runner 0.3.3 → 0.3.5

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/bin/setup.d.ts

@@ -10,7 +10,11 @@
  *   2. the sign-in — a setup token from the console, a cached session, or the
  *      browser flow — stored the way `bir login` stores it;
  *   3. the project: MCP servers wrapped, hooks wired, the scenario server added
- *      and pre-approved (`bir install --global --replay`);
+ *      and pre-approved (`bir install --global --replay`) — and every one of
+ *      its tools with it: investigate and the scenario tools are offered as
+ *      well as run_scenario, and Claude Code runs them without asking (Eran,
+ *      2026-09-28: after setup, every `bir` tool works). A person's
+ *      `bir scenario editing off` is kept;
  *   4. the recorder, started in the background and from now on started by the
  *      SessionStart hook whenever it is missing;
  *   5. a summary that names the account, the servers, the recorder's log, and

package/dist/bin/setup.js

@@ -10,7 +10,11 @@
  *   2. the sign-in — a setup token from the console, a cached session, or the
  *      browser flow — stored the way `bir login` stores it;
  *   3. the project: MCP servers wrapped, hooks wired, the scenario server added
- *      and pre-approved (`bir install --global --replay`);
+ *      and pre-approved (`bir install --global --replay`) — and every one of
+ *      its tools with it: investigate and the scenario tools are offered as
+ *      well as run_scenario, and Claude Code runs them without asking (Eran,
+ *      2026-09-28: after setup, every `bir` tool works). A person's
+ *      `bir scenario editing off` is kept;
  *   4. the recorder, started in the background and from now on started by the
  *      SessionStart hook whenever it is missing;
  *   5. a summary that names the account, the servers, the recorder's log, and
@@ -35,8 +39,10 @@ import { pidAlive, readDiscovery } from "../control/discovery.js";
 import { AUTH_URL_HINT, DeviceFlowAborted, DeviceFlowUnsupported, authenticate, describeAuthService, deviceLogin, loadStoredConfig, normalizeAuthUrl, rememberAuthUrl, tokenLogin, } from "../auth/client.js";
 import { activeSessions, compareVersions, ensureDaemon, SETUP_TOKEN_ENV, stopDaemon, } from "../control/daemon.js";
 import { normalizePath } from "../control/paths.js";
-import { allocateReplacementPort, isScenarioServer, isWrapped, LOOPBACK_NO_PROXY, probeFreePort, proxyConfigured, projectRecord, readSidecar, SCENARIO_SERVER_KEY, setProjectRecord, writeSidecar, allocateFreeProjectPort, } from "../config/generate.js";
+import { allowRules, BIR_TOOLS_RULE, claudeCodePaths } from "../config/adapters/claude-code.js";
+import { allocateReplacementPort, editingEnabled, isScenarioServer, isWrapped, LOOPBACK_NO_PROXY, probeFreePort, proxyConfigured, projectRecord, readSidecar, SCENARIO_SERVER_KEY, setProjectRecord, writeSidecar, allocateFreeProjectPort, } from "../config/generate.js";
 import { resolveServers } from "../config/resolve.js";
+import { EDIT_TOOLS, READ_TOOLS } from "./scenario-edit.js";
 import { errText } from "../util/log.js";
 import { offSource } from "../util/off-switch.js";
 import { packageVersion } from "../util/version.js";
@@ -368,6 +374,14 @@ export async function runSetup(args, deps) {
     else {
         out(`  replay     on — direct execution allowed for: ${allow?.length ? allow.join(", ") : `all wrapped (narrow it with \`bir replay allow ${wrapped[0]}\`)`}`);
     }
+    // What the `bir` server gives a session here, and whether Claude Code asks
+    // before each call — both set by install for setup (bir.ts, installWriting).
+    if (resolveServers(project).some((s) => s.name === SCENARIO_SERVER_KEY && isScenarioServer(s.config))) {
+        const asks = !allowRules(claudeCodePaths(project).settingsLocal).includes(BIR_TOOLS_RULE);
+        out(editingEnabled(readSidecar(), project)
+            ? `  tools      ${["run_scenario", ...READ_TOOLS, ...EDIT_TOOLS].join(", ")} — ${asks ? "Claude Code asks before each" : "Claude Code runs them without asking, except a forced change"}`
+            : "  tools      run_scenario only — scenario editing is off here (`bir scenario editing on` adds investigate and the scenario tools)");
+    }
     if (ensured) {
         const { info, health: h } = ensured.status;
         const theirs = String(h.hooksVersion ?? info.version ?? "");

package/dist/config/adapters/claude-code.d.ts

@@ -77,6 +77,33 @@ export declare function removeGitExclude(dir: string, line?: string): string | u
 export declare function enableMcpjsonServers(settingsPath: string, names: string[]): string;
 /** Undo {@link enableMcpjsonServers} for `names`; drops the key when empty. */
 export declare function disableMcpjsonServers(settingsPath: string, names: string[]): string | undefined;
+/**
+ * The rule that lets Claude Code run the runner's own `bir` server's tools
+ * without asking. In Claude Code's permission syntax `mcp__<server>` matches
+ * every tool that server offers, so it also covers the tools `bir scenario
+ * editing on` brings, and any a later runner adds.
+ *
+ * `bir setup` writes it (bir.ts, installWriting), into the person's own
+ * `.claude/settings.local.json` only, and only where `bir` IS the runner's
+ * scenario server: the rule matches a server by name, and a server of the
+ * person's own that is called `bir` must keep its prompts.
+ */
+export declare const BIR_TOOLS_RULE = "mcp__bir";
+/** The `permissions.allow` rules in a settings file; none when it is missing or unreadable. */
+export declare function allowRules(settingsPath: string): string[];
+/**
+ * Add `rules` to `permissions.allow`, leaving every other rule and key alone.
+ * Returns the file's new text and the rules that were not there before — the
+ * only ones {@link removeAllowRules} may take out again. A `permissions` or
+ * `allow` of the wrong shape is left as it is (nothing added): it is the
+ * person's to fix, and Claude Code reads neither.
+ */
+export declare function addAllowRules(settingsPath: string, rules: string[]): {
+    text: string;
+    added: string[];
+};
+/** Undo {@link addAllowRules} for `rules`; drops `allow`, then `permissions`, when left empty. */
+export declare function removeAllowRules(settingsPath: string, rules: string[]): string | undefined;
 /** True when `settingsPath` holds any hook of ours. */
 export declare function hasBirHooks(settingsPath: string): boolean;
 /** Which file holds a given scope's `mcpServers` for this cwd. */

package/dist/config/adapters/claude-code.js

@@ -24,7 +24,7 @@ import { createHash } from "node:crypto";
 import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
 import { dirname, join, parse as parsePath, resolve as resolvePath } from "node:path";
 import { writeFileAtomic } from "../../util/atomic-write.js";
-import { FIRST_PROJECT_PORT, PACKAGE_NAME } from "../generate.js";
+import { FIRST_PROJECT_PORT, PACKAGE_NAME, SCENARIO_SERVER_KEY } from "../generate.js";
 import { claudeJsonPath, parseJsonFile, parseJsonText, projectKeyFor, } from "../resolve.js";
 export function claudeCodePaths(cwd, claudeJsonOverride) {
     return {
@@ -176,6 +176,74 @@ export function disableMcpjsonServers(settingsPath, names) {
             fresh.enabledMcpjsonServers = kept;
     });
 }
+// ── permission rules ───────────────────────────────────────────────────────
+/**
+ * The rule that lets Claude Code run the runner's own `bir` server's tools
+ * without asking. In Claude Code's permission syntax `mcp__<server>` matches
+ * every tool that server offers, so it also covers the tools `bir scenario
+ * editing on` brings, and any a later runner adds.
+ *
+ * `bir setup` writes it (bir.ts, installWriting), into the person's own
+ * `.claude/settings.local.json` only, and only where `bir` IS the runner's
+ * scenario server: the rule matches a server by name, and a server of the
+ * person's own that is called `bir` must keep its prompts.
+ */
+export const BIR_TOOLS_RULE = `mcp__${SCENARIO_SERVER_KEY}`;
+/** The `permissions.allow` rules in a settings file; none when it is missing or unreadable. */
+export function allowRules(settingsPath) {
+    let parsed;
+    try {
+        parsed = parseJsonFile(settingsPath);
+    }
+    catch {
+        return [];
+    }
+    const allow = parsed?.permissions?.allow;
+    return Array.isArray(allow) ? allow.filter((r) => typeof r === "string") : [];
+}
+const plainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * Add `rules` to `permissions.allow`, leaving every other rule and key alone.
+ * Returns the file's new text and the rules that were not there before — the
+ * only ones {@link removeAllowRules} may take out again. A `permissions` or
+ * `allow` of the wrong shape is left as it is (nothing added): it is the
+ * person's to fix, and Claude Code reads neither.
+ */
+export function addAllowRules(settingsPath, rules) {
+    let added = [];
+    const text = editJson(settingsPath, (parsed) => {
+        added = [];
+        if (parsed.permissions !== undefined && !plainObject(parsed.permissions))
+            return;
+        const permissions = { ...(parsed.permissions ?? {}) };
+        if (permissions.allow !== undefined && !Array.isArray(permissions.allow))
+            return;
+        const allow = [...(permissions.allow ?? [])];
+        added = rules.filter((rule) => !allow.includes(rule));
+        if (added.length === 0)
+            return;
+        permissions.allow = [...allow, ...added];
+        parsed.permissions = permissions;
+    });
+    return { text, added };
+}
+/** Undo {@link addAllowRules} for `rules`; drops `allow`, then `permissions`, when left empty. */
+export function removeAllowRules(settingsPath, rules) {
+    if (!allowRules(settingsPath).some((rule) => rules.includes(rule)))
+        return undefined;
+    return editJson(settingsPath, (parsed) => {
+        const permissions = parsed.permissions;
+        if (!plainObject(permissions) || !Array.isArray(permissions.allow))
+            return;
+        const kept = permissions.allow.filter((rule) => !(typeof rule === "string" && rules.includes(rule)));
+        if (kept.length > 0)
+            permissions.allow = kept;
+        else
+            delete permissions.allow;
+        if (Object.keys(permissions).length === 0)
+            delete parsed.permissions;
+    });
+}
 /** True when `settingsPath` holds any hook of ours. */
 export function hasBirHooks(settingsPath) {
     let parsed;

package/dist/config/generate.d.ts

@@ -455,12 +455,23 @@ export interface ProjectRecord {
      * environment: their definitions ride along with every request of every
      * session, and only somebody working on a scenario calls them.
      *
-     * Per project, and off by default, because the `bir` server runs in every
-     * session of every installed project — a fleet included — and a plan must
-     * not change because some agent there decided it should. The `bir scenario`
-     * commands ignore it: a person in a terminal is asked before each one.
+     * Per project. `bir setup` turns it on (Eran, 2026-09-28: setup leaves every
+     * `bir` tool offered and working), except where a person turned it off —
+     * that `false` is kept by every later setup (see {@link settleEditing}). A
+     * bare `bir install` leaves it as it is, so a fleet wired by hand keeps the
+     * old default: the `bir` server runs in every session of every installed
+     * project, and there a plan must not change because some agent decided it
+     * should. The `bir scenario` commands ignore it: a person in a terminal is
+     * asked before each one.
      */
     editing?: boolean;
+    /**
+     * The `permissions.allow` rules `bir setup` added to this project's
+     * `.claude/settings.local.json` so Claude Code runs the `bir` server's tools
+     * without asking (adapters/claude-code.ts, BIR_TOOLS_RULE). Uninstall takes
+     * out only these: a rule that was there before is the person's own.
+     */
+    allowRules?: string[];
     /**
      * Every `.claude.json` an install for this project wrote local-scope entries
      * to. Claude Code reads `$CLAUDE_CONFIG_DIR/.claude.json` when that is set,
@@ -588,6 +599,12 @@ export declare function editingEnabled(sidecar: InstalledSidecar, cwd: string):
  * inventing a record would invent a port the hooks do not use.
  */
 export declare function setEditing(sidecar: InstalledSidecar, cwd: string, on: boolean): ProjectRecord | undefined;
+/**
+ * `bir setup`: scenario editing on for `cwd`, unless it was ever set — an
+ * `off` a person stored is theirs, and no setup turns it back on. Returns true
+ * when it was switched on now.
+ */
+export declare function settleEditing(sidecar: InstalledSidecar, cwd: string): boolean;
 /**
  * What an install or uninstall said about calculated replay:
  *