tumwater 0.4.0 → 0.4.2

package/dist/src/ui/tui/tui-editor-entry.js

@@ -31,174 +31,192 @@ export function createEntryEditor(session) {
         session.held.entry = null;
         restoreDraft();
     };
-    const handleKey = (_str, key, ctx) => {
-        if (key.ctrl && key.name === "n") {
-            // On the Backlog view Ctrl+N files a new entry: it opens the title editor with a null
-            // position (new plan), and pressed again inside that editor flips plan <-> bug.
-            if (entryEditFor !== null && entryEditFor.position === null) {
-                const other = entryEditFor.kind === "plan" ? "bug" : "plan";
-                entryEditFor = { ...entryEditFor, kind: other };
-                session.held.entry = entryEditFor;
-                session.flashMessage(`new ${other} — Enter to file, Ctrl+N switches to ${other === "plan" ? "bug" : "plan"}, Esc cancels`);
-                return true;
-            }
-            // A Ctrl+N on any other state (not the Backlog view's new-entry slot, or an editor
-            // already holding the line) is the notes/change/trail cycle, a pane arm the outer
-            // dispatch handles — this factory returns false so it runs.
-            if (ctx.view === ctx.roleIds.length + 1 &&
-                !session.anyEditorHeld()) {
+    // On the Backlog view Ctrl+N files a new entry: it opens the title editor with a null
+    // position (new plan), and pressed again inside that editor flips plan <-> bug.
+    const flipNewEntryKind = () => {
+        const other = entryEditFor.kind === "plan" ? "bug" : "plan";
+        entryEditFor = { ...entryEditFor, kind: other };
+        session.held.entry = entryEditFor;
+        session.flashMessage(`new ${other} — Enter to file, Ctrl+N switches to ${other === "plan" ? "bug" : "plan"}, Esc cancels`);
+        return true;
+    };
+    // A Ctrl+N on any other state (not the Backlog view's new-entry slot, or an editor
+    // already holding the line) is the notes/change/trail cycle, a pane arm the outer
+    // dispatch handles — this factory returns false so it runs.
+    const openNewEntry = () => {
+        restoreDraft = session.takeDraft();
+        entryEditFor = { kind: "plan", position: null, title: "" };
+        session.held.entry = entryEditFor;
+        session.input = "";
+        session.cursor = 0;
+        session.flashMessage("new plan — Enter to file, Ctrl+N switches to bug, Esc cancels");
+        return true;
+    };
+    // A second Ctrl+E inside the entry editor toggles the same prompt line into the file
+    // field, whose path's contents replace the whole entry (splitEntryFile's rule) through
+    // tryEditEntry — the terminal twin of `tumwater plan|bug --edit <n> --file <path>`. A
+    // third Ctrl+E returns to the title draft, parked in the saved pair; Esc cancels all.
+    const toggleEntryFileField = () => {
+        entryBodyFile = !entryBodyFile;
+        if (entryBodyFile) {
+            entryBodySavedInput = session.input;
+            entryBodySavedCursor = session.cursor;
+            session.input = "";
+            session.cursor = 0;
+            session.flashMessage(`replace ${entryEditFor.kind} #${entryEditFor.position} from a file — Enter to save, Ctrl+E back to the title, Esc cancels`);
+        }
+        else {
+            session.input = entryBodySavedInput;
+            session.cursor = entryBodySavedCursor;
+            session.flashMessage(`editing ${entryEditFor.kind} #${entryEditFor.position} title — Enter to save, Ctrl+E to replace from a file, Esc cancels`);
+        }
+        return true;
+    };
+    // Ctrl+E opens the title editor on the selected plan or bug (mnemonic: **E**dit); Enter
+    // saves through tryEditEntry, the non-exiting core the dashboard drawer shares, keeping
+    // the body and stamp. The prompt line is single-line, so only the title is editable here.
+    const openSelectedEntry = (ctx) => {
+        try {
+            const selected = selectedEditableEntry(session, ctx.selectedEntry, "edited");
+            if (selected !== null) {
+                const kind = selected.kind;
+                const position = selected.position;
                 restoreDraft = session.takeDraft();
-                entryEditFor = { kind: "plan", position: null, title: "" };
+                entryEditFor = { kind, position, title: selected.picked.title };
                 session.held.entry = entryEditFor;
-                session.input = "";
-                session.cursor = 0;
-                session.flashMessage("new plan — Enter to file, Ctrl+N switches to bug, Esc cancels");
-                return true;
+                session.input = stripEntryStamp(selected.picked.title);
+                session.cursor = session.input.length;
+                session.flashMessage(`editing ${kind} #${position} — Enter to save, Esc to cancel`);
             }
-            return false;
         }
-        if (key.ctrl && key.name === "e" && entryEditFor !== null && entryEditFor.position !== null) {
-            // A second Ctrl+E inside the entry editor toggles the same prompt line into the file
-            // field, whose path's contents replace the whole entry (splitEntryFile's rule) through
-            // tryEditEntry — the terminal twin of `tumwater plan|bug --edit <n> --file <path>`. A
-            // third Ctrl+E returns to the title draft, parked in the saved pair; Esc cancels all.
-            entryBodyFile = !entryBodyFile;
-            if (entryBodyFile) {
-                entryBodySavedInput = session.input;
-                entryBodySavedCursor = session.cursor;
-                session.input = "";
-                session.cursor = 0;
-                session.flashMessage(`replace ${entryEditFor.kind} #${entryEditFor.position} from a file — Enter to save, Ctrl+E back to the title, Esc cancels`);
+        catch (err) {
+            session.flashError(err);
+        }
+        return true;
+    };
+    // Esc cancels the title editor, restoring the previous prompt text; nothing is written.
+    const cancelEntryEdit = () => {
+        const filing = entryEditFor.position === null;
+        exitEntryEdit();
+        session.flashMessage(filing ? "new entry cancelled" : "edit cancelled");
+        return true;
+    };
+    // Shared tail of the title and file edit arms: re-read the entry by flat index and
+    // title, guard against a concurrent move (so a mismatch is treated as moved, not
+    // written), then settle the editor and commit through tryEditEntry. The only thing
+    // the two arms pass differently is the (title, body) pair taking the entry's place;
+    // an omitted body preserves the matched entry's own body (the title edit arm).
+    const applyEntryEdit = (target, newTitle, newBody) => {
+        try {
+            // Both call sites (the file arm's and the title arm's Entry-save paths) run only
+            // when `target.position` is non-null, so the position math never sees a null.
+            const position = target.position;
+            const entries = session.flat();
+            const plans = entries.filter((e) => e.label === "plan").length;
+            const entry = entries[target.kind === "plan" ? position - 1 : plans + position - 1];
+            const outcome = entry?.label === target.kind && entry.title === target.title
+                ? tryEditEntry(session.root, target.kind, position, target.title, newTitle, newBody ?? entry.body)
+                : { status: "moved", title: "" };
+            exitEntryEdit();
+            if (outcome.status === "edited") {
+                session.commitBacklogEdit(outcome.file, `Edit ${target.kind}: ${outcome.title}`);
+                const holds = backlogHolds(session.root);
+                const hold = (target.kind === "bug" ? holds.bugs : holds.plans)[position - 1] ?? null;
+                session.flashMessage(`edited ${target.kind} #${target.position}: ${outcome.title}${hold === null ? "" : ` — ${stillHeldNote(hold)}`}`);
+            }
+            else if (outcome.status === "unchanged") {
+                session.flashMessage(`unchanged ${target.kind} #${target.position}: ${outcome.title}`);
             }
             else {
-                session.input = entryBodySavedInput;
-                session.cursor = entryBodySavedCursor;
-                session.flashMessage(`editing ${entryEditFor.kind} #${entryEditFor.position} title — Enter to save, Ctrl+E to replace from a file, Esc cancels`);
+                session.clearBacklogSelection();
+                session.flashMessage(`that ${target.kind} was already removed or moved — nothing edited`);
             }
-            return true;
         }
-        if (key.ctrl && key.name === "e" &&
-            !session.anyEditorHeld() &&
-            ctx.view === ctx.roleIds.length + 1 && ctx.selectedEntry !== null) {
-            // Ctrl+E opens the title editor on the selected plan or bug (mnemonic: **E**dit); Enter
-            // saves through tryEditEntry, the non-exiting core the dashboard drawer shares, keeping
-            // the body and stamp. The prompt line is single-line, so only the title is editable here.
-            try {
-                const selected = selectedEditableEntry(session, ctx.selectedEntry, "edited");
-                if (selected !== null) {
-                    const kind = selected.kind;
-                    const position = selected.position;
-                    restoreDraft = session.takeDraft();
-                    entryEditFor = { kind, position, title: selected.picked.title };
-                    session.held.entry = entryEditFor;
-                    session.input = stripEntryStamp(selected.picked.title);
-                    session.cursor = session.input.length;
-                    session.flashMessage(`editing ${kind} #${position} — Enter to save, Esc to cancel`);
-                }
-            }
-            catch (err) {
-                session.flashError(err);
+        catch (err) {
+            session.flashError(err);
+        }
+    };
+    // File mode: the line holds a path whose contents replace title and body through the
+    // same title-checked tryEditEntry core the title edit uses, keeping the entry's
+    // position and its (planned …)/(found by …) stamp. A missing file, an empty path, a
+    // file with no title line, and a structurally unsound body all flash and stay here.
+    const commitEntryFromFile = (target) => {
+        const text = readEditorPath(session);
+        if (text === null)
+            return;
+        const { title: rawTitle, body } = splitEntryFile(text);
+        const newTitle = stripEntryStamp(rawTitle);
+        if (!newTitle) {
+            session.flashMessage("the file needs a title line");
+            return;
+        }
+        const problem = bodyStructureProblem(body);
+        if (problem !== null) {
+            session.flashMessage(problem);
+            return;
+        }
+        applyEntryEdit(target, newTitle, body);
+    };
+    // New entry (Ctrl+N): file by title with an empty body and wake its role, the same
+    // steps handleBacklogFile takes; a length problem or a throw stays in the editor.
+    const fileNewEntry = (target) => {
+        try {
+            const { role, wakeText } = OPERATOR_FILE_KINDS[target.kind];
+            const problem = promptLengthProblem(wakeText(collapseWhitespace(session.input)), role);
+            if (problem) {
+                session.flashMessage(problem);
+                return;
             }
+            const filed = fileEntryWithBody(session.root, target.kind, session.input, "");
+            session.commitBacklogEdit(filed.file, `File ${target.kind}: ${filed.title}`);
+            submitRolePromptAndWake(session.root, role, wakeText(filed.title));
+            exitEntryEdit();
+            session.flashMessage(`filed ${target.kind}: ${filed.title} — woke ${role}`);
+        }
+        catch (err) {
+            session.flashError(err);
+        }
+    };
+    const commitEntryTitle = (target) => {
+        applyEntryEdit(target, session.input);
+    };
+    // Enter saves the new title through tryEditEntry with the body re-read now, so a
+    // concurrent body edit is not clobbered by a stale copy. The entry is matched by flat
+    // index and title; a mismatch is treated as moved without writing. A blank title and a
+    // throw flash and STAY in the editor so the text survives.
+    const commitEntryEdit = () => {
+        const target = entryEditFor;
+        if (entryBodyFile && target.position !== null) {
+            commitEntryFromFile(target);
             return true;
         }
-        if (key.name === "escape" && entryEditFor) {
-            // Esc cancels the title editor, restoring the previous prompt text; nothing is written.
-            const filing = entryEditFor.position === null;
-            exitEntryEdit();
-            session.flashMessage(filing ? "new entry cancelled" : "edit cancelled");
+        if (!session.input.trim()) {
+            session.flashMessage("an entry needs a title");
             return true;
         }
-        if (key.name === "return" && entryEditFor) {
-            // Enter saves the new title through tryEditEntry with the body re-read now, so a
-            // concurrent body edit is not clobbered by a stale copy. The entry is matched by flat
-            // index and title; a mismatch is treated as moved without writing. A blank title and a
-            // throw flash and STAY in the editor so the text survives.
-            const target = entryEditFor;
-            // Shared tail of the title and file edit arms: re-read the entry by flat index and
-            // title, guard against a concurrent move (so a mismatch is treated as moved, not
-            // written), then settle the editor and commit through tryEditEntry. The only thing
-            // the two arms pass differently is the (title, body) pair taking the entry's place;
-            // an omitted body preserves the matched entry's own body (the title edit arm).
-            const applyEntryEdit = (newTitle, newBody) => {
-                try {
-                    // Both call sites (the file arm's and the title arm's Entry-save paths) run only
-                    // when `target.position` is non-null, so the position math never sees a null.
-                    const position = target.position;
-                    const entries = session.flat();
-                    const plans = entries.filter((e) => e.label === "plan").length;
-                    const entry = entries[target.kind === "plan" ? position - 1 : plans + position - 1];
-                    const outcome = entry?.label === target.kind && entry.title === target.title
-                        ? tryEditEntry(session.root, target.kind, position, target.title, newTitle, newBody ?? entry.body)
-                        : { status: "moved", title: "" };
-                    exitEntryEdit();
-                    if (outcome.status === "edited") {
-                        session.commitBacklogEdit(outcome.file, `Edit ${target.kind}: ${outcome.title}`);
-                        const holds = backlogHolds(session.root);
-                        const hold = (target.kind === "bug" ? holds.bugs : holds.plans)[position - 1] ?? null;
-                        session.flashMessage(`edited ${target.kind} #${target.position}: ${outcome.title}${hold === null ? "" : ` — ${stillHeldNote(hold)}`}`);
-                    }
-                    else if (outcome.status === "unchanged") {
-                        session.flashMessage(`unchanged ${target.kind} #${target.position}: ${outcome.title}`);
-                    }
-                    else {
-                        session.clearBacklogSelection();
-                        session.flashMessage(`that ${target.kind} was already removed or moved — nothing edited`);
-                    }
-                }
-                catch (err) {
-                    session.flashError(err);
-                }
-            };
-            // File mode: the line holds a path whose contents replace title and body through the
-            // same title-checked tryEditEntry core the title edit uses, keeping the entry's
-            // position and its (planned …)/(found by …) stamp. A missing file, an empty path, a
-            // file with no title line, and a structurally unsound body all flash and stay here.
-            if (entryBodyFile && target.position !== null) {
-                const text = readEditorPath(session);
-                if (text === null)
-                    return true;
-                const { title: rawTitle, body } = splitEntryFile(text);
-                const newTitle = stripEntryStamp(rawTitle);
-                if (!newTitle) {
-                    session.flashMessage("the file needs a title line");
-                    return true;
-                }
-                const problem = bodyStructureProblem(body);
-                if (problem !== null) {
-                    session.flashMessage(problem);
-                    return true;
-                }
-                applyEntryEdit(newTitle, body);
-                return true;
-            }
-            if (!session.input.trim()) {
-                session.flashMessage("an entry needs a title");
-                return true;
-            }
-            if (target.position === null) {
-                // New entry (Ctrl+N): file by title with an empty body and wake its role, the same
-                // steps handleBacklogFile takes; a length problem or a throw stays in the editor.
-                try {
-                    const { role, wakeText } = OPERATOR_FILE_KINDS[target.kind];
-                    const problem = promptLengthProblem(wakeText(collapseWhitespace(session.input)), role);
-                    if (problem) {
-                        session.flashMessage(problem);
-                        return true;
-                    }
-                    const filed = fileEntryWithBody(session.root, target.kind, session.input, "");
-                    session.commitBacklogEdit(filed.file, `File ${target.kind}: ${filed.title}`);
-                    submitRolePromptAndWake(session.root, role, wakeText(filed.title));
-                    exitEntryEdit();
-                    session.flashMessage(`filed ${target.kind}: ${filed.title} — woke ${role}`);
-                }
-                catch (err) {
-                    session.flashError(err);
-                }
-                return true;
-            }
-            applyEntryEdit(session.input);
+        if (target.position === null) {
+            fileNewEntry(target);
             return true;
         }
+        commitEntryTitle(target);
+        return true;
+    };
+    const handleKey = (_str, key, ctx) => {
+        if (key.ctrl && key.name === "n") {
+            if (entryEditFor !== null && entryEditFor.position === null)
+                return flipNewEntryKind();
+            if (ctx.view === ctx.roleIds.length + 1 && !session.anyEditorHeld())
+                return openNewEntry();
+            return false;
+        }
+        if (key.ctrl && key.name === "e" && entryEditFor !== null && entryEditFor.position !== null)
+            return toggleEntryFileField();
+        if (key.ctrl && key.name === "e" && !session.anyEditorHeld() && ctx.view === ctx.roleIds.length + 1 && ctx.selectedEntry !== null)
+            return openSelectedEntry(ctx);
+        if (key.name === "escape" && entryEditFor)
+            return cancelEntryEdit();
+        if (key.name === "return" && entryEditFor)
+            return commitEntryEdit();
         return false;
     };
     return { handleKey, exit: exitEntryEdit };

package/dist/src/ui/tui/tui-editor-instances.js

@@ -1,5 +1,6 @@
 import { setConfigKey, unsetConfigKey } from "../../config/config-write.js";
 import { rawRoleField } from "../../roles/role-view.js";
+import { isExponentSpelling } from "../../text/text.js";
 import { createRoleKeyEditor } from "./tui-editor-role-key.js";
 /** The Ctrl+G parallel-runner-count editor on the shared prompt line, the terminal twin of
  * `tumwater role <id> --instances` and the dashboard role drawer's instance-count editor. Enter
@@ -32,7 +33,7 @@ export function createInstancesEditor(session) {
             // refuses (and the dashboard drawer's instance editor), so this refuses it too, naming
             // the key and staying in edit mode. A non-exponent spelling falls through to
             // validateConfig, whose message names the key.
-            if (!/^\d*\.?\d+$/.test(text) && /^\d+(\.\d+)?[eE][+-]?\d+$/.test(text)) {
+            if (isExponentSpelling(text)) {
                 return { ok: false, error: `${cfgKey} must be a plain integer from 1 to 8 — no exponent notation` };
             }
             const r = setConfigKey(s.root, cfgKey, text);

package/dist/src/ui/tui/tui-editor-instructions.js

@@ -1,117 +1,60 @@
 import { setConfigKey, unsetConfigKey } from "../../config/config-write.js";
 import { baseRoleOf } from "../../roles/runner-ids.js";
-import { readEditorPath } from "./tui-editor-session.js";
+import { createRoleFileEditor } from "./tui-editor-role-file.js";
 /** The Transcript view's Ctrl+L replace-standing-instructions editor on the shared prompt line,
  * the terminal twin of `tumwater role <id> --instructions-file` and the dashboard role drawer's
- * `Instructions override` row. It owns its `instructionsFor` flag, its saved-draft pair, and the
- * role pinned when it opened, so a roster shift cannot redirect the write. Ctrl+L opens it on a
- * role transcript (the same in-range guard every transcript editor arm carries — the
- * instructions row is reachable from the plain transcript, not only the notes mode), flashes the
- * held-editor busy message when another prompt-line editor owns the line, settles the recall
- * draft, blanks the line, and flashes the enter/Esc framing. Enter trims the line as a file
- * path, reads it verbatim with the same readTextIfExists the CLI's non-interactive replacement
- * uses, and writes the BASE role's `roles.<base>.instructions` through the same
- * setConfigKey/unsetConfigKey family the CLI and dashboard drawer use — so validateConfig
- * (naming the dotted key and its ROLE_INSTRUCTIONS_MAX_CHARS cap) owns the value's truth. An
- * empty or whitespace-only file clears the key (unsetConfigKey, the dashboard's empty-clears
- * convention, giving the terminal a way to clear); an over-cap or unknown-role write flashes
- * the returned error and STAYS open. Esc, Ctrl+L again, and Ctrl+T cancel by restoring the
- * prompt draft. On success the notes repaints through the session's refreshNotes seam (the
- * notes view's cached Markdown recomputes the same role-inspection body the `Instructions
- * override` row renders). Unlike quiet hours' director refusal there is none here: the
- * dashboard editor and `--instructions-file` both accept the director, so it edits too. */
+ * `Instructions override` row. Ctrl+L opens it on a role transcript (the same in-range guard
+ * every transcript editor arm carries — the instructions row is reachable from the plain
+ * transcript, not only the notes mode). Enter trims the line as a file path, reads it verbatim
+ * with the same readTextIfExists the CLI's non-interactive replacement uses, and writes the
+ * BASE role's `roles.<base>.instructions` through the same setConfigKey/unsetConfigKey family
+ * the CLI and dashboard drawer use — so validateConfig (naming the dotted key and its
+ * ROLE_INSTRUCTIONS_MAX_CHARS cap) owns the value's truth. An empty or whitespace-only file
+ * clears the key (unsetConfigKey, the dashboard's empty-clears convention, giving the terminal
+ * a way to clear); an over-cap or unknown-role write flashes the returned error and STAYS open.
+ * On success the notes repaints through the session's refreshNotes seam (the notes view's
+ * cached Markdown recomputes the same role-inspection body the `Instructions override` row
+ * renders). Unlike quiet hours' director refusal there is none here: the dashboard editor and
+ * `--instructions-file` both accept the director, so it edits too. The open/exit/read framing
+ * lives in the shared createRoleFileEditor helper that also serves the notes editor. */
 export function createInstructionsEditor(session) {
-    let instructionsFor = null;
-    let restoreDraft = () => { };
-    // Leave the instructions editor (Esc, Ctrl+L again, or Ctrl+T): restore the saved prompt
-    // text with no override written.
-    const exitInstructionsMode = () => {
-        if (instructionsFor === null)
-            return;
-        instructionsFor = null;
-        session.held.instructions = null;
-        restoreDraft();
-    };
-    const handleKey = (_str, key, ctx) => {
-        if (key.ctrl && key.name === "l" &&
-            ctx.roleIds.length > 0 && ctx.view >= 1 && ctx.view <= ctx.roleIds.length) {
-            // Ctrl+L toggles the replace-instructions editor on a role's Transcript view (mnemonic:
-            // the instructions **l**ine, bound on no other TUI view except the Activity view's
-            // fallback editor and the Health view's retire-leftovers arm — the in-range role check
-            // keeps the arm from firing off a role transcript, and those other arms (which run before
-            // this one) keep Ctrl+L on Activity and Health).
-            // The line edits one file path that becomes the viewed role's whole
-            // `roles.<base>.instructions` override through the same setConfigKey write the CLI and
-            // the dashboard drawer use. Entering saves the prompt draft and blanks the line; leaving
-            // restores it.
-            if (session.editorEntryDenied("instructions"))
-                return true;
-            if (instructionsFor !== null) {
-                exitInstructionsMode();
-            }
-            else {
-                // Mid-recall, hand the arrows' saved draft back before the instructions editor takes
-                // the line — the same settle the role editors do — so leaving restores the draft, not
-                // a history entry, with no stale recall state riding along.
-                const role = ctx.roleIds[ctx.view - 1]; // defined: the open-arm range guard above pins the view into roleIds
-                restoreDraft = session.takeDraft();
-                instructionsFor = role;
-                session.held.instructions = role;
-                session.input = "";
-                session.cursor = 0;
-                session.flashMessage(`replace ${role}'s instructions from a file — Enter to save, Esc to cancel`);
-            }
-            return true;
-        }
-        if (key.name === "escape" && instructionsFor !== null) {
-            // Esc cancels the instructions editor, restoring the previous prompt text and writing
-            // nothing.
-            exitInstructionsMode();
-            session.flashMessage("instructions edit cancelled");
-            return true;
-        }
-        if (key.name === "return" && instructionsFor !== null) {
-            // Enter reads the typed path whole and writes it through the shared
-            // setConfigKey/unsetConfigKey family the CLI's `--instructions-file`/`--clear-instructions`
-            // and the dashboard drawer use, so ROLE_INSTRUCTIONS_MAX_CHARS and the unknown-role check
-            // (enforced by validateConfig inside writeConfigMutation) and their wording cannot drift.
-            // An empty path, a missing file, an unreadable file, an over-cap text, and an unknown id
-            // all flash and STAY in the editor so the operator can fix the path; an empty or
-            // whitespace-only file clears the override (the dashboard's empty-clears convention). On
-            // success the notes repaints the updated `Instructions override` row and the editor
-            // exits with the shared success wording.
-            const role = instructionsFor;
-            const text = readEditorPath(session);
-            if (text === null)
-                return true;
+    return createRoleFileEditor(session, {
+        held: "instructions",
+        openCtrl: "l",
+        mayOpen: (ctx) => 
+        // The in-range role guard every transcript editor arm carries: Ctrl+L is bound on no
+        // other TUI view except the Activity view's fallback editor and the Health view's
+        // retire-leftovers arm, and those other arms (which run before this one) keep Ctrl+L on
+        // Activity and Health — so no extra view restriction is needed here beyond the roster
+        // guard that keeps the arm from firing off a role transcript.
+        ctx.roleIds.length > 0 && ctx.view >= 1 && ctx.view <= ctx.roleIds.length,
+        openFlash: (role) => `replace ${role}'s instructions from a file — Enter to save, Esc to cancel`,
+        cancelFlash: "instructions edit cancelled",
+        commit: (s, role, text) => {
             const base = baseRoleOf(role);
             const cfgKey = `roles.${base}.instructions`;
             if (text.trim() === "") {
-                const result = unsetConfigKey(session.root, cfgKey);
-                if (!result.ok) {
-                    session.flashMessage(result.error); // broken config or write failure — stay in edit mode
-                    return true;
-                }
-                session.refreshNotes(role);
-                exitInstructionsMode();
-                session.flashMessage(result.oldValue === undefined
-                    ? `${role}: instructions is not set in tumwater.json, so nothing was cleared`
-                    : `${role}: instructions cleared`);
-                return true;
-            }
-            const result = setConfigKey(session.root, cfgKey, JSON.stringify(text));
-            if (!result.ok) {
-                session.flashMessage(result.error); // over the cap, unknown id, or write failure — stay in edit mode
-                return true;
+                const result = unsetConfigKey(s.root, cfgKey);
+                if (!result.ok)
+                    return { ok: false, reason: result.error };
+                return {
+                    ok: true,
+                    message: result.oldValue === undefined
+                        ? `${role}: instructions is not set in tumwater.json, so nothing was cleared`
+                        : `${role}: instructions cleared`,
+                };
             }
-            session.refreshNotes(role);
-            exitInstructionsMode();
-            session.flashMessage(result.unchanged
-                ? `${role}: instructions unchanged, so tumwater.json was not written`
-                : `${role}: instructions saved (${text.length} chars)`);
-            return true;
-        }
-        return false;
-    };
-    return { handleKey, exit: exitInstructionsMode };
+            const result = setConfigKey(s.root, cfgKey, JSON.stringify(text));
+            if (!result.ok)
+                return { ok: false, reason: result.error };
+            return {
+                ok: true,
+                message: result.unchanged
+                    ? `${role}: instructions unchanged, so tumwater.json was not written`
+                    : `${role}: instructions saved (${text.length} chars)`,
+            };
+        },
+        flashFailure: (s, reason) => s.flashMessage(reason),
+        refresh: (s, role) => s.refreshNotes(role),
+    });
 }