@williamzujkowski/live-coding-music-mcp 4.0.0 → 4.1.0

package/dist/server/tools/storage.js

@@ -4,6 +4,12 @@
  * Owns one consolidated tool (`pattern_store`) with save/load/list actions.
  */
 import { InputValidator } from '../../utils/InputValidator.js';
+import { ok, err, categorizeError, withStashNotice } from './types.js';
+import { readFile } from 'fs/promises';
+import path from 'path';
+import { ValidationError } from '../../utils/CategorisedError.js';
+/** Hard cap on .mid input size — protects @tonejs/midi from pathological allocations. */
+const MAX_MIDI_BYTES = 1_000_000; // 1 MB
 const SESSION_ID_PROP = {
     session_id: {
         type: 'string',
@@ -29,38 +35,201 @@ export const tools = [
                 },
                 name: { type: 'string', description: 'Pattern name (required for save/load)' },
                 tags: { type: 'array', items: { type: 'string' }, description: 'Tags to attach (save only)' },
+                overwrite: {
+                    type: 'boolean',
+                    description: 'save only: replace a pattern saved under a DIFFERENT name that maps to the '
+                        + 'same file (names are lowercased and stripped of punctuation, so "My Jam" '
+                        + 'and "my-jam" collide). Off by default; the replaced pattern is unrecoverable.',
+                },
                 tag: { type: 'string', description: 'Filter by tag (list only)' },
                 ...SESSION_ID_PROP,
             },
             required: ['action'],
         },
     },
+    {
+        name: 'import_midi',
+        description: 'Convert a .mid file into a playable Strudel pattern (Phase 1: literal transcription, #201). ' +
+            'Use source="base64" with data=<base64 string> for inline bytes, or source="path" with data=<basename> ' +
+            'to read from the patterns/midi/ directory (path traversal blocked). ' +
+            'Drum tracks (MIDI channel 10) emit one s() lane per sample so simultaneous kicks/hats do not collide. ' +
+            'Pitched tracks emit note("...").s("piano") with simultaneous notes merged into [a,b,c] chord tokens. ' +
+            'Phase 2+ (structural compression, voice separation, LLM idiomatic pass) tracked in separate issues. ' +
+            'Example: import_midi({ source: "path", data: "drumloop.mid", steps_per_cycle: 16 }). ' +
+            'For the reverse direction (Strudel → MIDI) use the export_midi tool.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                source: {
+                    type: 'string',
+                    enum: ['base64', 'path'],
+                    description: 'How to interpret `data` — raw base64 bytes or a filename under patterns/midi/',
+                },
+                data: {
+                    type: 'string',
+                    description: 'For source=base64: base64-encoded .mid bytes (≤1MB decoded). ' +
+                        'For source=path: basename of a .mid file under ./patterns/midi/ (path-traversal blocked).',
+                },
+                steps_per_cycle: {
+                    type: 'number',
+                    description: 'Grid resolution per bar (integer 1-64). Default 16.',
+                },
+                bars: {
+                    type: 'number',
+                    description: 'Cap on bars to emit. Default: full file.',
+                },
+                drum_map: {
+                    type: 'object',
+                    description: 'Optional override / extension to the default GM percussion map. ' +
+                        'Keys are MIDI note numbers (as strings, since JSON object keys), values are Strudel sample names. ' +
+                        'Example: { "60": "cp", "61": "rim" }. Unmapped drums fall back to rests and are surfaced in the result summary.',
+                    additionalProperties: { type: 'string' },
+                },
+            },
+            required: ['source', 'data'],
+        },
+    },
 ];
 export const toolNames = new Set(tools.map(t => t.name));
 async function doSave(args, ctx, sid) {
     InputValidator.validateStringLength(args.name, 'name', 255, false);
     const toSave = await ctx.getCurrentPatternSafe(sid);
-    if (!toSave) {
-        return 'No pattern to save';
+    // Whitespace counts as nothing. `!toSave` covered '' only, so a
+    // pattern of "  \n\t " was written to disk and reported as a real
+    // save (#293).
+    if (!toSave || toSave.trim().length === 0) {
+        // Nothing was written to disk, so this is a failure — but as a bare
+        // string it was none of the three things the dispatcher recognises
+        // (envelope, failure-shaped object, legacy 'Error: ' prefix), so it
+        // reached clients as { ok: true, data: 'No pattern to save' }. An
+        // agent branching on `ok` recorded a successful save and moved on,
+        // and the pattern was gone (#287).
+        return err('business', 'No pattern to save. Write or generate a pattern first.');
     }
-    await ctx.store.save(args.name, toSave, args.tags || []);
+    // A collision throws ValidationError, which `categorizeError` maps to
+    // the validation envelope at the dispatcher — so the caller gets a
+    // refusal naming the pattern in the way, not a success (#428).
+    await ctx.store.save(args.name, toSave, args.tags || [], {
+        overwrite: args.overwrite === true,
+    });
     return `Pattern saved as "${args.name}"`;
 }
 async function doLoad(args, ctx, sid) {
     InputValidator.validateStringLength(args.name, 'name', 255, false);
     const saved = await ctx.store.load(args.name);
     if (saved) {
-        await ctx.writePatternSafe(saved.content, sid);
-        return `Loaded pattern "${args.name}"`;
+        const written = await ctx.writePatternSafe(saved.content, sid);
+        return withStashNotice(`Loaded pattern "${args.name}"`, written);
     }
-    return `Pattern "${args.name}" not found`;
+    // Bare prose, so the dispatcher's legacy normalisation — which only
+    // recognises 'Error: ' and 'Browser not initialized' prefixes — let
+    // this through as { ok: true, data: 'Pattern "x" not found' }. Same
+    // false success as #287, twenty lines below the code that fixed it
+    // (#293).
+    return err('business', `Pattern "${args.name}" not found. ` +
+        'Use pattern_store({ action: "list" }) to see what is saved.');
 }
 async function doList(args, ctx) {
     if (args?.tag) {
         InputValidator.validateStringLength(args.tag, 'tag', 100, false);
     }
-    const patterns = await ctx.store.list(args?.tag);
-    return patterns.map(p => `• ${p.name} [${p.tags.join(', ')}] - ${p.timestamp}`).join('\n') || 'No patterns found';
+    const { patterns, skipped } = await ctx.store.listDetailed(args?.tag);
+    // A file the store could not read is not the same as a pattern that
+    // is not there, and the caller has no other way to learn the
+    // difference — the store logs it, and no MCP client reads the log
+    // (#426, same reasoning as the export warning in #335).
+    const note = skipped > 0
+        ? `\n\n(${String(skipped)} file(s) in the pattern directory could not be read and were skipped.)`
+        : '';
+    if (patterns.length === 0) {
+        return skipped > 0
+            ? `No readable patterns found.${note}`
+            : 'No patterns found';
+    }
+    return patterns.map(p => `• ${p.name} [${p.tags.join(', ')}] - ${p.timestamp}`).join('\n') + note;
+}
+/**
+ * Resolve `args.data` to a Buffer based on `args.source`. Enforces the
+ * 1 MB cap and, for path sources, blocks path traversal by clamping to
+ * `./patterns/midi/` via `path.basename` (mirrors PatternStore).
+ */
+async function loadMidiBuffer(args) {
+    const source = args?.source;
+    const data = args?.data;
+    if (typeof data !== 'string' || data.length === 0) {
+        throw new Error('Invalid data: must be a non-empty string');
+    }
+    if (source === 'base64') {
+        // Decoded length ≤ raw length × 3/4; reject before allocating.
+        if (data.length > MAX_MIDI_BYTES * 2) {
+            throw new ValidationError(`MIDI base64 input too large (>${MAX_MIDI_BYTES} bytes decoded).`);
+        }
+        const buf = Buffer.from(data, 'base64');
+        if (buf.length === 0) {
+            throw new Error('Invalid data: base64 decoded to zero bytes');
+        }
+        if (buf.length > MAX_MIDI_BYTES) {
+            throw new ValidationError(`MIDI input too large (${buf.length} > ${MAX_MIDI_BYTES} bytes).`);
+        }
+        return buf;
+    }
+    if (source === 'path') {
+        InputValidator.validateStringLength(data, 'data', 255, false);
+        const safeName = path.basename(data);
+        if (safeName !== data) {
+            throw new Error('Invalid filename: path traversal detected');
+        }
+        const fullPath = path.resolve('./patterns/midi', safeName);
+        const expectedRoot = path.resolve('./patterns/midi');
+        if (!fullPath.startsWith(expectedRoot + path.sep)) {
+            throw new Error('Invalid filename: must resolve under patterns/midi/');
+        }
+        const buf = await readFile(fullPath);
+        if (buf.length > MAX_MIDI_BYTES) {
+            throw new ValidationError(`MIDI input too large (${buf.length} > ${MAX_MIDI_BYTES} bytes).`);
+        }
+        return buf;
+    }
+    throw new Error(`Invalid source: ${source}. Must be "base64" or "path".`);
+}
+async function doImportMidi(args, ctx) {
+    let buffer;
+    try {
+        buffer = await loadMidiBuffer(args);
+    }
+    catch (e) {
+        return err('validation', e?.message ?? 'Failed to load MIDI input');
+    }
+    // Normalize drum_map keys: JSON object keys are strings, the service wants number keys.
+    let drumMapNormalized;
+    if (args?.drum_map && typeof args.drum_map === 'object') {
+        drumMapNormalized = {};
+        for (const [k, v] of Object.entries(args.drum_map)) {
+            const n = Number(k);
+            if (!Number.isInteger(n) || n < 0 || n > 127 || typeof v !== 'string' || v.length === 0) {
+                return err('validation', `Invalid drum_map entry: ${k} -> ${String(v)}`);
+            }
+            drumMapNormalized[n] = v;
+        }
+    }
+    try {
+        const result = ctx.midiImportService.convertBuffer(buffer, {
+            steps_per_cycle: args?.steps_per_cycle,
+            bars: args?.bars,
+            drum_map: drumMapNormalized,
+        });
+        return ok(result);
+    }
+    catch (e) {
+        // Use the shared categoriser rather than a second, narrower one.
+        // This local matcher knew only parse/invalid/must-be, so every cap
+        // added in #235 landed in `internal` — including "MIDI file spans too
+        // many bars (N > 512). Pass bars=<n> to import a prefix.", which is
+        // the most actionable message in the file and was being delivered as
+        // a server bug the caller could do nothing about (#280).
+        const msg = e instanceof Error ? e.message : String(e);
+        return err(categorizeError(e), msg);
+    }
 }
 export async function execute(name, args, ctx) {
     const sid = args?.session_id;
@@ -78,6 +247,8 @@ export async function execute(name, args, ctx) {
             // Unreachable due to enum check above, but TypeScript wants it.
             return undefined;
         }
+        case 'import_midi':
+            return await doImportMidi(args, ctx);
         default:
             throw new Error(`storage module does not handle tool: ${name}`);
     }

package/dist/server/tools/transform.js

@@ -8,7 +8,10 @@
  * - `shape` (dimension enum: mood/energy/refine)
  * - `set_tempo` — high-traffic standalone verb
  */
+import { empty, err, withStashField, withStashNotice } from './types.js';
 import { InputValidator } from '../../utils/InputValidator.js';
+import { BEATS_PER_CYCLE } from '../../utils/Tempo.js';
+import { lookup } from '../../utils/TableLookup.js';
 const ENERGY_LEVELS = {
     0: { tempoAdjust: -20, roomAmount: 0.5, densityAdjust: '.slow(4)', description: 'minimal/ambient' },
     1: { tempoAdjust: -15, roomAmount: 0.4, densityAdjust: '.slow(3)', description: 'very sparse' },
@@ -38,7 +41,7 @@ function transposePattern(pattern, semitones) {
             'f#': 6, 'g': 7, 'g#': 8, 'a': 9, 'a#': 10, 'b': 11,
         };
         const currentNote = note.toLowerCase();
-        const noteValue = noteMap[currentNote] || 0;
+        const noteValue = lookup(noteMap, currentNote, 0);
         const newNoteValue = (noteValue + semitones + 12) % 12;
         const noteNames = ['c', 'c#', 'd', 'd#', 'e', 'f', 'f#', 'g', 'g#', 'a', 'a#', 'b'];
         const newOctave = parseInt(octave) + Math.floor((noteValue + semitones) / 12);
@@ -89,7 +92,7 @@ export const tools = [
         name: 'effect',
         description: 'Add or remove a Strudel effect on the current session pattern. ' +
             'action=add appends `.<effect>(<params>)`. ' +
-            'action=remove strips the last `.<effect>(...)` call from the pattern. ' +
+            'action=remove strips EVERY `.<effect>(...)` call from the pattern, not just the last. ' +
             'Example: effect({ action: "add", effect: "lpf", params: "1000" }). ' +
             'For higher-level effect bundles (mood/energy/refine) use shape; for raw transforms use transform.',
         inputSchema: {
@@ -105,7 +108,7 @@ export const tools = [
     },
     {
         name: 'set_tempo',
-        description: 'Set BPM',
+        description: 'Set BPM. Writes setcpm(bpm/4), assuming one bar of 4/4 per cycle.',
         inputSchema: {
             type: 'object',
             properties: { bpm: { type: 'number', description: 'Tempo in BPM' }, ...SESSION_ID_PROP },
@@ -147,73 +150,139 @@ async function opTranspose(args, ctx, sid) {
         throw new Error('Semitones must be an integer');
     }
     const p = await ctx.getCurrentPatternSafe(sid);
-    await ctx.writePatternSafe(transposePattern(p, args.semitones), sid);
-    return `Transposed ${args.semitones} semitones`;
+    const written = await ctx.writePatternSafe(transposePattern(p, args.semitones), sid);
+    return withStashNotice(`Transposed ${args.semitones} semitones`, written);
 }
 async function opReverse(ctx, sid) {
     const p = await ctx.getCurrentPatternSafe(sid);
-    await ctx.writePatternSafe(p + '.rev', sid);
-    return 'Pattern reversed';
+    const written = await ctx.writePatternSafe(p + '.rev', sid);
+    return withStashNotice('Pattern reversed', written);
 }
 async function opStretch(args, ctx, sid) {
     InputValidator.validateGain(args.factor);
     const p = await ctx.getCurrentPatternSafe(sid);
-    await ctx.writePatternSafe(p + `.slow(${args.factor})`, sid);
-    return `Stretched by factor of ${args.factor}`;
+    const written = await ctx.writePatternSafe(p + `.slow(${args.factor})`, sid);
+    return withStashNotice(`Stretched by factor of ${args.factor}`, written);
 }
 async function opQuantize(args, ctx, sid) {
     InputValidator.validateStringLength(args.grid, 'grid', 50, false);
     const p = await ctx.getCurrentPatternSafe(sid);
-    await ctx.writePatternSafe(p + `.struct("${args.grid}")`, sid);
-    return `Quantized to ${args.grid} grid`;
+    const written = await ctx.writePatternSafe(p + `.struct("${args.grid}")`, sid);
+    return withStashNotice(`Quantized to ${args.grid} grid`, written);
 }
 async function opHumanize(args, ctx, sid) {
     if (args.amount !== undefined)
         InputValidator.validateNormalizedValue(args.amount, 'amount');
     const p = await ctx.getCurrentPatternSafe(sid);
     const amt = args.amount || 0.01;
-    await ctx.writePatternSafe(p + `.nudge(rand.range(-${amt}, ${amt}))`, sid);
-    return 'Added human timing';
+    const written = await ctx.writePatternSafe(p + `.nudge(rand.range(-${amt}, ${amt}))`, sid);
+    return withStashNotice('Added human timing', written);
 }
 async function opVary(args, ctx, sid) {
     const p = await ctx.getCurrentPatternSafe(sid);
     const varied = ctx.generator.generateVariation(p, args.type || 'subtle');
-    await ctx.writePatternSafe(varied, sid);
-    return `Added ${args.type || 'subtle'} variation`;
+    const written = await ctx.writePatternSafe(varied, sid);
+    return withStashNotice(`Added ${args.type || 'subtle'} variation`, written);
 }
 async function opSwing(args, ctx, sid) {
     InputValidator.validateNormalizedValue(args.amount, 'amount');
     const p = await ctx.getCurrentPatternSafe(sid);
-    await ctx.writePatternSafe(p + `.swing(${args.amount})`, sid);
-    return `Added swing: ${args.amount}`;
+    const written = await ctx.writePatternSafe(p + `.swing(${args.amount})`, sid);
+    return withStashNotice(`Added swing: ${args.amount}`, written);
 }
 async function opScale(args, ctx, sid) {
     InputValidator.validateStringLength(args.scale, 'scale', 50, false);
+    // Concatenated straight into the pattern source below, so it must be a
+    // scale name and not arbitrary code — the same reason `opEffectAdd`
+    // validates its effect name (#236). A length check is not a content
+    // check: `scale: 'minor") .gain(9) //'` closed the string literal and
+    // appended a call, which is how it got past `PatternValidator`'s
+    // dangerous-gain rule — that runs on the pattern before this is
+    // appended to it (#440).
+    //
+    // `validateScaleName` already existed and `generate.ts` already used
+    // it; this path never did.
+    InputValidator.validateScaleName(args.scale);
     InputValidator.validateRootNote(args.root);
     const p = await ctx.getCurrentPatternSafe(sid);
-    await ctx.writePatternSafe(p + `.scale("${args.root}:${args.scale}")`, sid);
-    return `Applied ${args.root} ${args.scale} scale`;
+    const written = await ctx.writePatternSafe(p + `.scale("${args.root}:${args.scale}")`, sid);
+    return withStashNotice(`Applied ${args.root} ${args.scale} scale`, written);
 }
 async function opEffectAdd(args, ctx, sid) {
     InputValidator.validateStringLength(args.effect, 'effect', 100, false);
+    // Concatenated straight into the pattern source, so it must be a plain
+    // method name and not arbitrary code (#236).
+    InputValidator.validateIdentifier(args.effect, 'effect');
     if (args.params)
         InputValidator.validateStringLength(args.params, 'params', 1000, true);
     const p = await ctx.getCurrentPatternSafe(sid);
     const withEffect = args.params
         ? p + `.${args.effect}(${args.params})`
         : p + `.${args.effect}()`;
-    await ctx.writePatternSafe(withEffect, sid);
-    return `Added ${args.effect} effect`;
+    const written = await ctx.writePatternSafe(withEffect, sid);
+    return withStashNotice(`Added ${args.effect} effect`, written);
+}
+/**
+ * Removes every `.effect(...)` call from a pattern.
+ *
+ * Deliberately not a RegExp. The old implementation interpolated the
+ * caller's effect name into `new RegExp(...)`, which handed the caller
+ * regex *syntax* — `(a+)+Z` against a crafted pattern blocked the event
+ * loop for 25 seconds, and a synchronous String.replace has no timeout to
+ * break out of (#236).
+ *
+ * Scanning also fixes a correctness bug the regex had: `[^)]*` stops at
+ * the FIRST `)`, so `.lpf(add(1,2))` was left as a stray `)`. This walks
+ * balanced parentheses instead.
+ *
+ * @param pattern - Pattern source to strip
+ * @param effect - Effect name (validated as an identifier by the caller)
+ * @returns The pattern with every matching call removed
+ */
+function stripEffectCalls(pattern, effect) {
+    const needle = `.${effect}(`;
+    let out = '';
+    let cursor = 0;
+    for (;;) {
+        const start = pattern.indexOf(needle, cursor);
+        if (start === -1)
+            break;
+        // Walk to the matching close paren, respecting nesting.
+        let depth = 0;
+        let end = -1;
+        for (let i = start + needle.length - 1; i < pattern.length; i++) {
+            const ch = pattern[i];
+            if (ch === '(')
+                depth++;
+            else if (ch === ')') {
+                depth--;
+                if (depth === 0) {
+                    end = i;
+                    break;
+                }
+            }
+        }
+        // Unbalanced: leave the rest untouched rather than mangling it.
+        if (end === -1)
+            break;
+        out += pattern.slice(cursor, start);
+        cursor = end + 1;
+    }
+    return out + pattern.slice(cursor);
 }
 async function opEffectRemove(args, ctx, sid) {
     InputValidator.validateStringLength(args.effect, 'effect', 100, false);
+    // Must be a plain identifier: it is matched literally below, and was
+    // previously interpolated into a RegExp (#236).
+    InputValidator.validateIdentifier(args.effect, 'effect');
     const p = await ctx.getCurrentPatternSafe(sid);
-    const regex = new RegExp(`\\.${args.effect}\\([^)]*\\)`, 'g');
-    const stripped = p.replace(regex, '');
+    const stripped = stripEffectCalls(p, args.effect);
+    // The strip ran and matched nothing. That is a valid-empty result,
+    // not a failure and not a plain success (#288).
     if (stripped === p)
-        return `No ${args.effect} effect found to remove`;
-    await ctx.writePatternSafe(stripped, sid);
-    return `Removed ${args.effect} effect`;
+        return empty(`No ${args.effect} effect found to remove`);
+    const written = await ctx.writePatternSafe(stripped, sid);
+    return withStashNotice(`Removed ${args.effect} effect`, written);
 }
 export async function execute(name, args, ctx) {
     const sid = args?.session_id;
@@ -248,8 +317,12 @@ export async function execute(name, args, ctx) {
         case 'set_tempo': {
             InputValidator.validateBPM(args.bpm);
             const p = await ctx.getCurrentPatternSafe(sid);
-            await ctx.writePatternSafe(`setcpm(${args.bpm})\n${p}`, sid);
-            return `Set tempo to ${args.bpm} BPM`;
+            // `setcpm` is CYCLES per minute, and the Strudel convention this
+            // project follows is one bar of four beats per cycle — so the
+            // divisor is what makes `set_tempo({ bpm: 130 })` produce 130 BPM
+            // rather than 520 (#395).
+            const written = await ctx.writePatternSafe(`setcpm(${String(args.bpm)}/${String(BEATS_PER_CYCLE)})\n${p}`, sid);
+            return withStashNotice(`Set tempo to ${args.bpm} BPM`, written);
         }
         case 'shape': {
             const dim = args?.dimension;
@@ -267,12 +340,24 @@ export async function execute(name, args, ctx) {
 }
 async function shiftMood(args, ctx, sid) {
     const mood = args.target_mood?.toLowerCase()?.trim();
-    const profile = MOOD_PROFILES[mood];
+    // hasOwn, not a bare index: MOOD_PROFILES is a plain object literal,
+    // so MOOD_PROFILES['constructor'] returned Object — truthy, so the
+    // `if (!profile)` guard below never fired. The result was
+    // s("bd*4").slow(NaN).lpf(NaN).room(NaN).gain(NaN) written into the
+    // editor and reported as success:true (#308).
+    const profile = typeof mood === 'string' && Object.hasOwn(MOOD_PROFILES, mood)
+        ? MOOD_PROFILES[mood]
+        : undefined;
     if (!profile) {
-        return {
-            success: false,
-            error: `Unknown mood: ${args.target_mood}. Valid moods: ${Object.keys(MOOD_PROFILES).join(', ')}.`,
-        };
+        // `err('validation', ...)`, not a failure-shaped object.
+        //
+        // The dispatcher categorises those by running the MESSAGE through
+        // the string matcher, and "Valid moods: ..." contains none of the
+        // phrases it looks for — so a caller's typo landed in `internal`,
+        // which is the non-retryable fall-through for a fault that is not
+        // the caller's (#453). This is the audit #382 describes, at four
+        // sites it did not reach.
+        return err('validation', `Unknown mood: ${args.target_mood}. Valid moods: ${Object.keys(MOOD_PROFILES).join(', ')}.`);
     }
     const pattern = await ctx.getCurrentPatternSafe(sid);
     if (!pattern || pattern.trim().length === 0) {
@@ -316,11 +401,11 @@ async function shiftMood(args, ctx, sid) {
         result += `.gain(${g.toFixed(2)})`;
         applied.push(`gain ${profile.gainMod > 0 ? '+' : ''}${Math.round(profile.gainMod * 100 * intensity)}%`);
     }
-    await ctx.writePatternSafe(result, sid);
+    const written = await ctx.writePatternSafe(result, sid);
     if (args.auto_play !== false && (sid || ctx.isInitialized())) {
         await ctx.getController(sid).play();
     }
-    return { success: true, target_mood: mood, intensity, applied_effects: applied };
+    return withStashField({ success: true, target_mood: mood, intensity, applied_effects: applied }, written);
 }
 async function setEnergyLevel(level, ctx, sid) {
     if (level < 0 || level > 10 || !Number.isInteger(level)) {
@@ -335,10 +420,10 @@ async function setEnergyLevel(level, ctx, sid) {
     if (config.densityAdjust)
         result += config.densityAdjust;
     result += `.room(${config.roomAmount})`;
-    await ctx.writePatternSafe(result, sid);
+    const written = await ctx.writePatternSafe(result, sid);
     if (sid || ctx.isInitialized())
         await ctx.getController(sid).play();
-    return { success: true, level, description: config.description };
+    return withStashField({ success: true, level, description: config.description }, written);
 }
 async function refinePattern(direction, ctx, sid) {
     const pattern = await ctx.getCurrentPatternSafe(sid);
@@ -373,14 +458,13 @@ async function refinePattern(direction, ctx, sid) {
             modification = '.room(0.1)';
             break;
         default:
-            return {
-                success: false,
-                error: `Unknown refinement direction: ${direction}. Supported: faster, slower, louder, quieter, brighter, darker, "more reverb", drier.`,
-            };
+            // See the mood branch above: the caller's argument, categorised
+            // `validation` rather than `internal` (#453).
+            return err('validation', `Unknown refinement direction: ${direction}. Supported: faster, slower, louder, quieter, brighter, darker, "more reverb", drier.`);
     }
-    await ctx.writePatternSafe(pattern + modification, sid);
+    const written = await ctx.writePatternSafe(pattern + modification, sid);
     if (sid || ctx.isInitialized())
         await ctx.getController(sid).play();
-    return { success: true, direction: dir, applied: modification };
+    return withStashField({ success: true, direction: dir, applied: modification }, written);
 }
 export const transformModule = { tools, toolNames, execute };