@hraness/dawg 0.6.0 → 0.7.0

package/src/main.ts

@@ -1,11 +1,43 @@
 #!/usr/bin/env bun
+import { TOPIC_ALIASES } from "./lang/glossary.ts";
+import { isGuideInstrument, vocalChainPatch } from "../core/clips.ts";
+import { isSingWord } from "../core/sing.ts";
+import { commandParses, parseExact } from "./commands/parses.ts";
+import { paramRangeError } from "./commands/param-range.ts";
+import { noteName as midiNoteName } from "./media/notes.ts";
 import {
+  EVERYDAY_VERBS,
+  EXPORT_USAGE,
+  elsewhereHint,
+  FREE_TEXT_HINTS,
+  noTrack,
+  stemsReceipt,
+  LOOP_USAGE,
+  WINDOW_VERBS,
+  NO_AGENT,
+  RANGES,
+  canonicalWindowForm,
+  friendlyCoreError,
+  knownVerbs,
+  nearest,
+  noNote,
+  parseExportCommand,
+  parseLoopCommand,
+  recover,
+  usageCard,
+  usageError,
+  verbOf,
+} from "./commands/grammar.ts";
+import {
+  instrumentListLines,
   isUnknownInstrument,
   plainSineAdvice,
+  unknownInstrumentMessage,
 } from "./audio/instrument-check.ts";
 import { randomUUID } from "node:crypto";
 import { readFileSync, writeSync } from "node:fs";
-import { readFile, stat, writeFile } from "node:fs/promises";
+import { mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import { join, relative, resolve } from "node:path";
 import { stdin, stdout } from "node:process";
 import {
@@ -14,6 +46,12 @@ import {
   type SessionRecord,
 } from "./session/store.ts";
 import { openSessionPort } from "./session/port.ts";
+import {
+  OwnWrites,
+  editedTrack,
+  foreignEvents,
+  otherWindowName,
+} from "./session/origin.ts";
 import { compositionDigest, monotonicEpochMs } from "./session/protocol.ts";
 import {
   formatSessionLine,
@@ -69,11 +107,31 @@ import {
   rigTrackFields,
   rigWordPatch,
 } from "./commands/rig.ts";
+import {
+  applyProgressionCommand,
+  parseProgressionCommand,
+} from "./commands/progression.ts";
+import {
+  applyGuitarCommand,
+  applyStrumCommand,
+  parseGuitarCommand,
+  parseStrumCommand,
+} from "./commands/strum.ts";
 import {
   applyModalCommand,
   modalListLines,
   parseModalCommand,
 } from "./commands/modal.ts";
+import {
+  applyWindCommand,
+  parseWindCommand,
+  windListLines,
+} from "./commands/wind.ts";
+import {
+  applySingCommand,
+  parseSingCommand,
+  singListLines,
+} from "./commands/sing.ts";
 import { applySynthCommand, parseSynthCommand } from "./commands/synth.ts";
 import { applyStringCommand, parseStringCommand } from "./commands/string.ts";
 import { instrumentPatchForWord, isModalWord } from "../core/resonators.ts";
@@ -94,26 +152,38 @@ import {
   parseTuningCommand,
   type TuningCommand,
 } from "./commands/tuning.ts";
+import {
+  applyCalibrationCommand,
+  parseCalibrationCommand,
+} from "./commands/calibration.ts";
 import { TuningError, displayTag, resolveTuning } from "../core/tuning.ts";
 import {
   applyMasterCommand,
   measurementLine,
   parseMasterCommand,
 } from "./commands/master.ts";
+import { applyStyleCommand, parseStyleCommand } from "./commands/style.ts";
 import { exportSampleRate, measureScoreOffThread } from "./audio/measure.ts";
 import {
   applySectionCommand,
+  loopSpan,
   parseSectionCommand,
 } from "./commands/arrange.ts";
 import {
-  HELP_TOPICS,
+  helpMiss,
   helpText,
+  helpTitle,
   helpTopicLines,
   nearestCommand,
   typoFix,
   usageHint,
 } from "./commands/help.ts";
-import { historyTarget, REDO_KIND, UNDO_KIND } from "./commands/history.ts";
+import {
+  historyReceipt,
+  historyTarget,
+  REDO_KIND,
+  UNDO_KIND,
+} from "./commands/history.ts";
 
 import {
   SamplePlacementError,
@@ -127,6 +197,32 @@ import {
   voiceNameFrom,
 } from "./commands/sample.ts";
 import { applyFitCommand, fitVoice, parseFitCommand } from "./commands/fit.ts";
+import { applyShiftCommand, parseShiftCommand } from "./commands/shift.ts";
+import { parseVocalCommand, runVocalCommand } from "./commands/vocal.ts";
+import {
+  applyFormantCommand,
+  parseFormantCommand,
+  parseVowelCommand,
+} from "./commands/formant.ts";
+import {
+  applyLyrics,
+  parseClipCommand,
+  parseLyricsCommand,
+  runClipCommand,
+  setClipImportDeps,
+} from "./commands/clips.ts";
+import { pitchTraceFor } from "./commands/vocal-pitch.ts";
+import {
+  applyVocoderCommand,
+  parseVocoderCommand,
+  vocoderListLines,
+} from "./commands/vocoder.ts";
+import {
+  applyAutotuneCommand,
+  autotuneListLines,
+  parseAutotuneCommand,
+} from "./commands/autotune.ts";
+import { parseResampleCommand, runResample } from "./commands/resample.ts";
 import { suggestFitMode } from "./audio/dsp/onset.ts";
 import {
   SampleLibrary,
@@ -135,7 +231,14 @@ import {
   type SampleBank,
   type SampleProblem,
 } from "./audio/samples.ts";
+import {
+  ANALYSIS_CACHE_BYTES,
+  analysisCacheStatus,
+  analysisDir,
+  pruneAnalysisCache,
+} from "./audio/analysis.ts";
 import { drumSnapshotFields, samplerSnapshotFields } from "../tui/drums.ts";
+import { clipSnapshots, loadClipPeaks } from "../tui/clip-row.ts";
 import { highwayLayers } from "../tui/layers.ts";
 import { drumVoicePitch, isDrumInstrument } from "../core/drums.ts";
 import {
@@ -144,6 +247,7 @@ import {
   type AgentEvent,
   type AgentHost,
 } from "./agent/agent.ts";
+import { routeDuringTurn } from "./agent/steer.ts";
 import {
   isApiSelection,
   providerFingerprint,
@@ -162,8 +266,24 @@ import {
   spendLine as formatSpendLine,
   webHostFor,
 } from "./agent/usage.ts";
-import { configDir } from "./auth/credentials.ts";
-import { runAuthCommand, runFirstRunLogin, runTuiLogin } from "./auth/cli.ts";
+import { configDir, readConfig, writeConfig } from "./auth/credentials.ts";
+import type { CommandOutcome } from "./agent/command-agent.ts";
+import {
+  GLIDE_STEP_MS,
+  NoteScheduler,
+  finishHint,
+  gestureFor,
+  glideValues,
+  agentPathsAllowed,
+  isAgentCommand,
+  isBrokenCommand,
+  brokenCommandReceipt,
+  parseShowMe,
+  toolCaption,
+  type ShowMeLevel,
+} from "./agent/show-me.ts";
+import { firstRunCard, runAuthCommand, runTuiLogin } from "./auth/cli.ts";
+import { musicalReceipt } from "./session/receipt.ts";
 import {
   modelPickerItems,
   tuiAuthCommand,
@@ -179,10 +299,16 @@ import {
   PlaySession,
   type LiveEngine,
 } from "./tui/play-session.ts";
-import { EditMenu, MENU_SECTIONS, type MenuContext } from "./tui/menu.ts";
+import {
+  EditMenu,
+  menuUsage,
+  menuSectionPath,
+  type MenuContext,
+} from "./tui/menu.ts";
 import {
   drawerView,
   faderChoose,
+  faderCommand,
   faderKeyPress,
   faderSetPosition,
   faderStep,
@@ -204,7 +330,15 @@ import {
   isStageable,
 } from "./tui/audition.ts";
 import { EuclidEditor, type EuclidContext } from "./tui/euclid.ts";
-import { HINTS, KEYS, keyLines, type KeySection } from "../tui/grammar.ts";
+import {
+  ARROW_DOWN,
+  ARROW_UP,
+  closesKeys,
+  HINTS,
+  KEYS,
+  keyLines,
+  type KeySection,
+} from "../tui/grammar.ts";
 import { renderAudition } from "./audio/audition.ts";
 import { exportScore, playbackTime, scoreBeatAt } from "./audio/arrange.ts";
 import { formatForm } from "../core/sections.ts";
@@ -252,6 +386,7 @@ import {
   applyScoreOperation,
   createScore,
   isSamplerInstrument,
+  isTrackAudible,
   PACK_PREFIX,
   scoreFromJSON,
   SCORE_LIMITS,
@@ -264,8 +399,19 @@ import { decodeLoop, encodeLoop } from "../core/loop.ts";
 import { scoreToMidi } from "../core/midi.ts";
 import type { TrackScoreSnapshot } from "../tui/render.ts";
 import { PromptModel } from "../tui/prompt.ts";
-import { TerminalInputDecoder } from "../tui/input.ts";
 import {
+  ESCAPE_FLUSH_MS,
+  INPUT_FLUSH,
+  PASTE_FLUSH_MS,
+  TerminalInputDecoder,
+} from "../tui/input.ts";
+import {
+  FrameGate,
+  IDLE_HEARTBEAT_MS,
+  MIN_FRAME_GAP_MS,
+} from "../tui/frame-gate.ts";
+import {
+  CARD_GLOW_MS,
   composeFrame,
   TuiApp,
   type AppView,
@@ -273,13 +419,19 @@ import {
   type SyncState,
   type TypesIndicator,
 } from "../tui/app.ts";
-import { fail, ok, toneOf, warn, type Receipt } from "../tui/activity.ts";
+import { fail, note, ok, toneOf, warn, type Receipt } from "../tui/activity.ts";
 import { systemRunner } from "./auth/runner.ts";
 import type { MediaServices } from "./media/types.ts";
 import { encodeBuffer } from "../tui/screen.ts";
 import { parseThemeName } from "../tui/theme.ts";
 import { formatDiagnostic } from "../core/sdk/eval.ts";
 import { isProject } from "./project/init.ts";
+import {
+  parseLaunchArgs,
+  parseSimpleArgv,
+  resolveTrackArg,
+} from "./launch-args.ts";
+import { RENDER_USAGE, runRenderCommand } from "./render.ts";
 import { typecheckProject } from "./project/typecheck.ts";
 import {
   startProjectSync,
@@ -287,107 +439,100 @@ import {
   type SyncHost,
 } from "./project/sync.ts";
 
+/** Set while `submit` runs a grammar reading, so it reads only once. */
+let recovering = false;
+
+/** Slash words `submit` handles itself (no parser in commandParses). */
+const SLASH_HANDLED: ReadonlySet<string> = new Set([
+  ...WINDOW_VERBS,
+  "chords",
+  "click",
+  "help",
+]);
+
 /** Whether a bare command parses (no side effects): for typo suggestions. */
 function parsesLocally(text: string): boolean {
-  return [
-    parsePrompt,
-    parseMusicCommand,
-    parseEditCommand,
-    parseRhythmCommand,
-    parseFxCommand,
-    parseSynthCommand,
-    parseStringCommand,
-    parseGranularCommand,
-    parseKeysCommand,
-    parseExpressionCommand,
-    parseMasterCommand,
-    (value: string) => parseSectionCommand(value, score),
-    parsePatternCommand,
-    parseKitCommand,
-    parsePackCommand,
-    parseSampleCommand,
-    parseFitCommand,
-    parseWavetableCommand,
-    parseTimeCommand,
-    parseTuningCommand,
-    parseRigCommand,
-    parseModalCommand,
-  ].some((parse) => parse(text) !== undefined);
+  return commandParses(text, score);
 }
 
 const ESC = "\u001b[";
 /** `/sessions` rows shown in the overlay. */
 const MAX_LISTED_SESSIONS = 64;
 
-const SUBCOMMANDS = [
-  "login",
-  "logout",
-  "auth",
-  "sessions",
-  "render",
-  "init",
-  "check",
-];
-const VALUE_FLAGS = ["--session", "--track", "--import", "--export", "--theme"];
-const FLAGS = [
-  ...VALUE_FLAGS,
-  "--new",
-  "--demo",
-  "--help",
-  "-h",
-  "--version",
-  "-v",
-  "--reduce-motion",
-  "--no-mouse",
-];
+/** Wraps a usage line at spaces before `width`, indenting continuations. */
+function wrapUsage(text: string, width: number, indent: string): string {
+  const lines: string[] = [];
+  let line = "";
+  for (const word of text.split(" ")) {
+    const prefix = lines.length === 0 ? "  " : indent;
+    if (line && prefix.length + line.length + 1 + word.length > width) {
+      lines.push(line);
+      line = word;
+    } else line = line ? `${line} ${word}` : word;
+  }
+  lines.push(line);
+  return lines.join(`\n${indent}`);
+}
 const HELP_TEXT = `dawg · local-first terminal music workstation
 
 Usage:
   dawg [--new] [--session <name|id>] [--track <name>]
-  dawg --import <file> --export <file>
+  dawg --import <file> --export <file>   convert a loop file (no session)
   dawg sessions
-  dawg render <out.wav|out.mid> [--session <name|id>] [--import <file>]
-               [--normalize <lufs|streaming|club|loud|…>] [--measure]
-  dawg init [dir]      project files: song.ts, tracks/<slug>/track.ts, .dawg/sdk
+  ${wrapUsage(RENDER_USAGE.replace(/^usage: /, ""), 76, "               ")}
+  dawg init [dir]      song.ts, tracks/<slug>/track.ts and .dawg/sdk
   dawg check           typecheck + evaluate the project; exit 1 on problems
-  dawg media doctor|download|stems|analyze|notes|sample|lyrics …  (dawg media --help)
+  dawg <command> --help  usage: sessions render init check media model
+  dawg doctor          audio backend, native sink and devices
+  dawg media doctor|download|stems|analyze|notes|sample|lyrics  (--help)
   dawg --version
 
-Usage flags:
+Display options:
   --reduce-motion   static hit/sustain states (also DAWG_REDUCE_MOTION=1)
   --theme <name>    default | high-contrast | mono (NO_COLOR forces mono)
   --no-mouse        keys only; no click/wheel reporting (also DAWG_MOUSE=0)
 
 Prompt:
-  Enter submit · Shift-Enter newline · Alt-Enter queue · Ctrl-Q toggle queue
-  Ctrl-Z undo · Ctrl-Y redo · Ctrl-O transcript · Esc cancel/close · Ctrl-C exit
+  Enter submit · Shift-Enter newline · Alt-Enter next · Ctrl-Q now / next
+  Ctrl-Z undo · Ctrl-Y redo · Ctrl-O transcript · Esc close · Ctrl-C exit
   Space on an empty prompt toggles playback
 
 Commands (bare music words; app commands take a slash):
 ${helpText()}
 
-Sign in (the choice is saved and reused until you log out):
-  dawg login                   find existing setups and pick a provider
-  dawg login gateway|openrouter|codex|claude
-  dawg model [alias]           pick a model, with the estimated cost per prompt
+Agent (optional; the choice is saved and reused until you log out):
+  dawg model key               find existing setups and pick a provider
+  dawg model key gateway|openrouter|codex|claude
+  dawg model [alias]           pick a model, with the cost per prompt
   dawg logout [provider] · dawg auth status [--check]
 Unrecognized requests go to the agent once a provider is configured
 (DAWG_PROVIDER=gateway|openrouter|codex|claude|auto, DAWG_MODEL=<alias>;
 DAWG_AI=0 disables the agent).`;
 const args = new Set(process.argv.slice(2));
-const requestedSession = optionValue("--session");
-const explicitTrack = optionValue("--track");
+/** One parse for every launch flag; problems are reported below. */
+const launch = parseLaunchArgs(process.argv.slice(2));
+const launchArgs = launch.ok ? launch.args : undefined;
+const requestedSession = launchArgs?.session;
+/** `--track` normalized as `/track` does; matched to an existing track below. */
+let explicitTrack = launchArgs?.track?.id;
 /** The focused track; claimed at startup unless `--track` is given. */
 let requestedTrack = explicitTrack ?? "main";
 const initialInstrument = isDrumInstrument(requestedTrack) ? "kit" : "sine";
-const importPath = optionValue("--import");
-const exportPath = optionValue("--export");
+const importPath = launchArgs?.importPath;
+const exportPath = launchArgs?.exportPath;
+// `dawg model key [provider]` is the canonical spelling of `dawg login`.
+if (process.argv[2] === "model" && process.argv[3] === "key")
+  process.exit(await runAuthCommand(["login", ...process.argv.slice(4)]));
 if (["login", "logout", "auth", "model"].includes(process.argv[2] ?? ""))
   process.exit(await runAuthCommand(process.argv.slice(2)));
 {
   // An unknown DAWG_MODEL is an error, never a silent fallback.
   const fromEnv = process.env.DAWG_MODEL?.trim();
-  if (fromEnv && !resolveModelChoice("gateway", fromEnv)) {
+  if (
+    fromEnv &&
+    !resolveModelChoice("gateway", fromEnv) &&
+    !resolveModelChoice("openrouter", fromEnv)
+  ) {
     process.stderr.write(
       `dawg: unknown DAWG_MODEL "${fromEnv.slice(0, 40)}"; use one of ${MODEL_CATALOG.map((row) => row.alias).join(", ")} or a vendor/model ID\n`,
     );
@@ -395,10 +540,14 @@ if (["login", "logout", "auth", "model"].includes(process.argv[2] ?? ""))
   }
 }
 if (process.argv[2] === "sessions") {
-  if (args.has("--help") || args.has("-h"))
-    stdout.write(
-      "usage: dawg sessions · lists this workspace's sessions, newest first (* marks the current one)\n",
-    );
+  const usage =
+    "usage: dawg sessions · lists this workspace's sessions, newest first (* marks the current one)";
+  const parsed = parseSimpleArgv(process.argv.slice(3), 0);
+  if (parsed.kind === "error") {
+    process.stderr.write(`${parsed.problem} · ${usage}\n`);
+    process.exit(2);
+  }
+  if (parsed.kind === "help") stdout.write(`${usage}\n`);
   else await printSessions(process.cwd(), stdout);
   process.exit(0);
 }
@@ -411,6 +560,10 @@ if (process.argv[2] === "init" || process.argv[2] === "check") {
     await command(process.argv.slice(2), process.cwd(), stdout, process.stderr),
   );
 }
+if (process.argv[2] === "doctor") {
+  const { runDoctorCommand } = await import("./audio/doctor.ts");
+  process.exit(await runDoctorCommand(process.argv.slice(3), stdout));
+}
 if (process.argv[2] === "media") {
   const { runMediaCommand } = await import("./media/cli.ts");
   process.exit(
@@ -443,18 +596,37 @@ if (args.has("--help") || args.has("-h")) {
 }
 // Argument mistakes are rejected here, before `.dawg/` could be created.
 {
-  const problem = argumentProblem(process.argv.slice(2));
-  if (problem) {
-    process.stderr.write(`${problem} · dawg --help\n`);
+  if (!launch.ok) {
+    process.stderr.write(`${launch.problem} · dawg --help\n`);
     process.exit(2);
   }
 }
+// `--import X --export Y` converts one loop file to another: no session.
+if (importPath && exportPath) {
+  try {
+    const converted = decodeLoop(await readLoopFile(importPath));
+    await writeFile(resolve(exportPath), encodeLoop(converted), "utf8");
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    const midi = /\.midi?$/i.test(importPath)
+      ? " · MIDI files are not imported; --import takes a .track.json loop"
+      : "";
+    process.stderr.write(
+      `dawg: cannot import ${importPath} · ${reason.split("\n")[0]!.slice(0, 160)}${midi}\n`,
+    );
+    process.exit(1);
+  }
+  stdout.write(`converted ${importPath} → ${exportPath}\n`);
+  process.exit(0);
+}
 const demo =
   args.has("--demo") || process.env.DAWG_DEMO === "1" || !stdin.isTTY;
-// First run with no provider (or a saved one that stopped working): the
-// sign-in picker, in the shell, before the TUI takes the screen.
-if (!demo && process.env.DAWG_AI !== "0" && stdout.isTTY)
-  await runFirstRunLogin();
+// Music first: the TUI opens directly. The first session with no provider
+// (or a saved one that stopped working) gets one card instead of a picker.
+const launchCard =
+  !demo && process.env.DAWG_AI !== "0" && stdout.isTTY
+    ? firstRunCard().catch(() => undefined)
+    : undefined;
 
 const initial = createScore({
   tracks: [
@@ -487,7 +659,32 @@ const freshWorkspace = !(await stat(join(process.cwd(), ".dawg")).then(
   () => true,
   () => false,
 ));
-const session = await ensureSession(initial.toJSON(), sessionOptions);
+// Decode the import before a session exists, so a bad file is one line.
+let importedScore: TrackScore | undefined;
+if (importPath) {
+  try {
+    importedScore = decodeLoop(await readLoopFile(importPath));
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    const midi = /\.midi?$/i.test(importPath)
+      ? " · MIDI files are not imported; --import takes a .track.json loop"
+      : "";
+    process.stderr.write(
+      `dawg: cannot import ${importPath} · ${reason.split("\n")[0]!.slice(0, 160)}${midi}\n`,
+    );
+    process.exit(1);
+  }
+}
+// A demo frame only renders: with no workspace yet (and nothing imported),
+// it runs on a throwaway session so the cwd gets no `.dawg/`.
+const ephemeralWorkspace =
+  demo && freshWorkspace && !importPath && selectedSession === undefined
+    ? await mkdtemp(join(tmpdir(), "dawg-demo-"))
+    : undefined;
+const session = await ensureSession(initial.toJSON(), {
+  ...sessionOptions,
+  ...(ephemeralWorkspace ? { workspace: ephemeralWorkspace } : {}),
+});
 // dawgd when connected, the file-lock path otherwise (see src/session/port.ts).
 let port = await openSessionPort<ReturnType<TrackScore["toJSON"]>>({
   paths: session.paths,
@@ -499,9 +696,14 @@ let port = await openSessionPort<ReturnType<TrackScore["toJSON"]>>({
 let record: SessionRecord<ReturnType<TrackScore["toJSON"]>> =
   port.mode === "daemon" ? await port.load() : session.record;
 let score = scoreFromJSON(record.composition);
-if (importPath) {
-  const imported = decodeLoop(await readLoopFile(importPath));
-  score = imported;
+if (importPath && importedScore) score = importedScore;
+// `--track Bass` focuses an existing `bass` (or a track named "Bass").
+if (launchArgs?.track) {
+  explicitTrack = resolveTrackArg(score.tracks, launchArgs.track);
+  requestedTrack = explicitTrack;
+}
+if (importPath && importedScore) {
+  score = importedScore;
   record = await port.append(
     record,
     {
@@ -540,7 +742,7 @@ const tui = new TuiApp({
     rows: () => stdout.rows ?? 24,
   },
   prompt,
-  theme: parseThemeName(optionValue("--theme") ?? process.env.DAWG_THEME),
+  theme: launchArgs?.theme ?? parseThemeName(process.env.DAWG_THEME),
   reducedMotion:
     args.has("--reduce-motion") || process.env.DAWG_REDUCE_MOTION === "1",
 });
@@ -597,8 +799,25 @@ let requestFrame: () => void = () => undefined;
 let runPromptLater: (command: string) => void = () => undefined;
 /** The fader drawer's focus and typing, while one is open over the menu. */
 let fader: FaderState | undefined;
-const KEY_UP = "\u001b[A";
-const KEY_DOWN = "\u001b[B";
+/** Show-me state (see the show-me section below). */
+const showMe: {
+  level: ShowMeLevel;
+  ghost?: string | undefined;
+  caption?: string | undefined;
+  commands: string[];
+  notes: NoteScheduler;
+  clear?: ReturnType<typeof setTimeout> | undefined;
+} = {
+  level: parseShowMe(process.env.DAWG_SHOWME ?? "") ?? "on",
+  commands: [],
+  notes: new NoteScheduler(() => score.tempoBpm),
+};
+if (!process.env.DAWG_SHOWME)
+  void readConfig({ dir: configDir() })
+    .then((config) => {
+      if (config.showMe) showMe.level = config.showMe;
+    })
+    .catch(() => undefined);
 /** The fader bar a left-button drag started on. */
 let dragging: { field: number; left: number; width: number } | undefined;
 /** The open drawer came from a command, not the menu. */
@@ -631,7 +850,8 @@ let handoff: <T>(flow: () => Promise<T>) => Promise<T> = (flow) => flow();
 function spendLine(): string {
   const width = stdout.columns ?? 80;
   if (!providerName || providerName === "offline")
-    return width >= 40 ? "no model · dawg login" : "";
+    // A state, not a nag: the first session's card already named /login.
+    return width >= 40 ? formatSpendLine({ kind: "offline" }) : "";
   const [model, provider] = providerName.split(" · ");
   return formatSpendLine(
     {
@@ -656,6 +876,10 @@ if (demo) {
     "add C4 at 0 for 1",
     0,
   );
+  if (ephemeralWorkspace) {
+    await port.close().catch(() => undefined);
+    await rm(ephemeralWorkspace, { recursive: true, force: true });
+  }
   process.exit(0);
 }
 
@@ -666,36 +890,8 @@ if (exportPath) {
 
 await runInteractive();
 
-/** Describes an unknown subcommand or option in `argv`, or undefined. */
-function argumentProblem(argv: readonly string[]): string | undefined {
-  if (argv[0] && !argv[0].startsWith("-") && !SUBCOMMANDS.includes(argv[0]))
-    return `unknown command · ${argv[0]}`;
-  if (argv[0] && SUBCOMMANDS.includes(argv[0])) return undefined;
-  for (let index = 0; index < argv.length; index += 1) {
-    const arg = argv[index]!;
-    if (VALUE_FLAGS.includes(arg)) {
-      index += 1;
-      continue;
-    }
-    if (arg.startsWith("-") && !FLAGS.includes(arg))
-      return `unknown option · ${arg}`;
-    if (!arg.startsWith("-")) return `unknown command · ${arg}`;
-  }
-  return undefined;
-}
-
 async function packageVersion(): Promise<string> {
-  const raw = await readFile(
-    new URL("../package.json", import.meta.url),
-    "utf8",
-  );
-  return (JSON.parse(raw) as { version?: string }).version ?? "0.0.0";
-}
-
-function optionValue(name: string): string | undefined {
-  const index = process.argv.indexOf(name);
-  const value = index >= 0 ? process.argv[index + 1] : undefined;
-  return value && !value.startsWith("--") ? value : undefined;
+  return (await import("./version.ts")).VERSION;
 }
 
 function seedDemo(value: TrackScore, trackId: string): TrackScore {
@@ -785,16 +981,24 @@ function snapshot(
         muted: focused?.muted,
         ...(tag?.cents !== undefined ? { cents: tag.cents } : {}),
         ...(tag?.name !== undefined ? { centsFrom: tag.name } : {}),
+        ...(note.lyric !== undefined ? { lyric: note.lyric } : {}),
       };
     });
+  // 0.7 clips: the clip row; peaks load off the frame path, then redraw.
+  const clips = clipSnapshots(value, requestedTrack);
+  if (clips)
+    void loadClipPeaks(process.cwd(), focused).then((changed) => {
+      if (changed) requestFrame();
+    });
   return {
     notes,
+    ...(clips ? { clips } : {}),
     trackName:
       value.tracks.find((track) => track.id === requestedTrack)?.name ??
       requestedTrack,
     trackId: requestedTrack,
     sessionId: record.sessionId,
-    revision: record.revision,
+    revision: shownRevision(record),
     bpm: value.time?.tempo
       ? bpmAtTick(value, beat * value.ticksPerBeat)
       : value.tempoBpm,
@@ -813,6 +1017,7 @@ function snapshot(
     currentBeat: scoreBeatAt(value, beat),
     playing: clock.playing,
     activity,
+    ...(focused?.instrument === "vocal" ? { vocal: true } : {}),
     ...drumSnapshotFields(
       value.tracks.find((track) => track.id === requestedTrack)?.instrument,
       notes,
@@ -824,6 +1029,7 @@ function snapshot(
     ...(table && table.linear && table.size !== 12
       ? { tuningPeriod: { size: table.size, root: table.root } }
       : {}),
+    pitchTrace: pitchTraceFor(requestedTrack, value),
     layers:
       tui.highwayView === "all"
         ? highwayLayers(
@@ -865,6 +1071,10 @@ function appView(value: TrackScore, beat: number): AppView {
       providerName && providerName !== "offline" ? providerName : undefined,
     spend: spendLine(),
     agentOffline: providerName === "offline" || process.env.DAWG_AI === "0",
+    showMe:
+      showMe.ghost || showMe.caption
+        ? { ghost: showMe.ghost, caption: showMe.caption }
+        : undefined,
     sync: syncState,
     sessionName: record.meta.name,
     windows: windowCount,
@@ -968,17 +1178,20 @@ function receipt(result: string | Receipt, base?: Baseline): void {
     tui.activity.pushError(message);
     return;
   }
+  // A receipt that names its own undo key needs no second hint.
   const hint =
-    scoreChanged && undoHintsShown < MAX_UNDO_HINTS
+    scoreChanged &&
+    undoHintsShown < MAX_UNDO_HINTS &&
+    !message.endsWith("ctrl-z undo")
       ? message.startsWith("undid")
-        ? "^y redo"
-        : "^z undo"
+        ? "ctrl-y redo"
+        : "ctrl-z undo"
       : undefined;
   if (hint) undoHintsShown += 1;
   tui.activity.pushCard(message, {
     tone,
-    baseRevision: changed ? base.revision : undefined,
-    resultRevision: changed ? record.revision : undefined,
+    baseRevision: changed ? shownRevision(record, base.revision) : undefined,
+    resultRevision: changed ? shownRevision(record) : undefined,
     hint,
     trackId: requestedTrack,
   });
@@ -990,6 +1203,10 @@ function describeError(command: string, error: unknown): string {
   const message = error instanceof Error ? error.message : String(error);
   if (detail?.code === "ENOENT" && typeof detail.path === "string")
     return `no such file · ${relative(process.cwd(), detail.path)}`;
+  // `tempo 900` → `tempo 900 · tempo takes 20…300 BPM · tempo 128`: no raw
+  // core keys (`tempoBpm`) on a card.
+  const friendly = friendlyCoreError(truncateForCard(command), message);
+  if (friendly) return friendly;
   const verb = command.trim().split(/\s+/)[0]?.replace(/^\//, "") || "command";
   return `${verb} failed · ${message}`;
 }
@@ -1016,25 +1233,108 @@ function mouseOn(): string {
   return mouseEnabled() ? MOUSE_ON : "";
 }
 
+/**
+ * Mouse off, plain colors, plain paste, cursor shown, main screen.  A
+ * function, not a const: `await runInteractive()` runs above this line.
+ */
+function terminalRestore(): string {
+  return `${MOUSE_OFF}${ESC}0m${ESC}?2004l${ESC}?25h${ESC}?1049l`;
+}
+
+/** `dawg: <stack>` for a crash printed after leaving the alternate screen. */
+function crashText(error: unknown): string {
+  const text =
+    error instanceof Error ? (error.stack ?? error.message) : String(error);
+  return `dawg: ${text}\n`;
+}
+
 async function runInteractive(): Promise<void> {
-  // A crash or a stray process.exit must not leave the terminal reporting
-  // mouse events into the shell.
-  process.once("exit", () => {
-    if (mouseEnabled()) writeSync(1, MOUSE_OFF);
-  });
-  // Nor may a kill or a closed terminal: restore it, then exit as killed.
+  // Every way out (quit, a failing teardown step, a crash, a kill, a stray
+  // process.exit) restores the whole terminal, once, synchronously: the
+  // shell must not stay on the alternate screen with paste brackets on.
+  let terminalRestored = false;
+  const restoreTerminal = () => {
+    if (terminalRestored) return;
+    terminalRestored = true;
+    try {
+      stdin.setRawMode?.(false);
+    } catch {
+      // stdin may already be closed.
+    }
+    try {
+      writeSync(1, terminalRestore());
+    } catch {
+      // The terminal may already be gone (SIGHUP).
+    }
+  };
+  process.once("exit", restoreTerminal);
+  // A kill or a closed terminal: restore it, then exit as killed.
   for (const [signal, code] of [
     ["SIGTERM", 143],
     ["SIGHUP", 129],
   ] as const)
     process.once(signal, () => {
+      restoreTerminal();
+      process.exit(code);
+    });
+  // An exception nothing caught leaves the editor in an unknown state: leave
+  // the alternate screen first, so the stack lands in the shell, then exit.
+  const onUncaught = (error: unknown) => {
+    restoreTerminal();
+    try {
+      writeSync(2, crashText(error));
+    } catch {
+      // Nowhere left to report it.
+    }
+    process.exit(1);
+  };
+  // A rejected fire-and-forget promise is one failed action, not a broken
+  // editor: report it on the activity strip and repaint over anything the
+  // runtime wrote.
+  const onRejection = (error: unknown) => {
+    if (terminalRestored || screenSuspended) {
       try {
-        writeSync(1, `${MOUSE_OFF}${ESC}0m${ESC}?2004l${ESC}?25h${ESC}?1049l`);
+        writeSync(2, crashText(error));
       } catch {
-        // The terminal may already be gone (SIGHUP).
+        // Nowhere left to report it.
       }
-      process.exit(code);
-    });
+      return;
+    }
+    tui.activity.pushError(
+      `failed · ${error instanceof Error ? error.message : String(error)}`,
+    );
+    tui.invalidate();
+    requestFrame();
+  };
+  // Runtime warnings and console output would land on top of the frame; the
+  // writer never repaints rows it did not change.  Route them to the
+  // transcript instead, and repaint.
+  const onWarning = (warning: Error) => {
+    if (screenSuspended || terminalRestored) return;
+    tui.activity.pushNote(`warning · ${warning.message}`, "error");
+    tui.invalidate();
+    requestFrame();
+  };
+  const consoleError = console.error;
+  const consoleWarn = console.warn;
+  const consoleToTranscript =
+    (original: (...data: unknown[]) => void) =>
+    (...data: unknown[]) => {
+      if (screenSuspended || terminalRestored) return original(...data);
+      tui.activity.pushNote(
+        data
+          .map((item) => (item instanceof Error ? item.message : String(item)))
+          .join(" "),
+        "error",
+      );
+      tui.invalidate();
+      requestFrame();
+    };
+  process.on("uncaughtException", onUncaught);
+  process.on("unhandledRejection", onRejection);
+  process.on("warning", onWarning);
+  console.error = consoleToTranscript(consoleError);
+  console.warn = consoleToTranscript(consoleWarn);
   stdin.setRawMode?.(true);
   stdin.resume();
   // Alternate screen, hidden cursor, bracketed paste.
@@ -1045,7 +1345,8 @@ async function runInteractive(): Promise<void> {
   const runPrompt = async (text: string): Promise<void> => {
     const ui = tui.command(text);
     if (ui !== undefined) {
-      tui.activity.pushCard(ui, { tone: "info" });
+      if (typeof ui === "string") tui.activity.pushCard(ui, { tone: "info" });
+      else tui.activity.pushCard(ui.text, { tone: toneOf(ui) });
       return;
     }
     tui.activity.pushRequest(text);
@@ -1069,6 +1370,16 @@ async function runInteractive(): Promise<void> {
     }
   };
   let agentReported = false;
+  /** A typed command during an agent turn; leaves the turn's receipt alone. */
+  const runLocalBesideAgent = async (text: string): Promise<void> => {
+    tui.activity.pushRequest(text);
+    const base = baseline();
+    try {
+      receipt(await submit(text), base);
+    } catch (error) {
+      tui.activity.pushError(describeError(text, error));
+    }
+  };
   const drainQueue = async (): Promise<void> => {
     if (processingQueue) return;
     processingQueue = true;
@@ -1089,17 +1400,64 @@ async function runInteractive(): Promise<void> {
       tui.activity.setQueueDepth(queuedPrompts.length);
     }
   };
+  // Builds a frame only when something can have changed (tui/frame-gate.ts):
+  // an idle editor no longer rebuilds the whole view 30 times a second.
+  const frameGate = new FrameGate(IDLE_HEARTBEAT_MS, MIN_FRAME_GAP_MS);
+  const unwatchActivity = tui.activity.subscribe(() => frameGate.markDirty());
+  const animating = (): boolean => {
+    if (clock.playing || play?.on || auditionLoop?.looping) return true;
+    const activity = tui.activity;
+    if (activity.spinner || activity.streaming) return true;
+    if (tui.delight.animating(Date.now())) return true;
+    const latest = activity.latest;
+    return (
+      !tui.ui.reducedMotion &&
+      latest !== undefined &&
+      Date.now() - latest.atMs < CARD_GLOW_MS
+    );
+  };
   const tick = (force = false) => {
     if (screenSuspended) return;
+    if (
+      !frameGate.shouldBuild({
+        nowMs: Date.now(),
+        force,
+        animating: animating(),
+        keys: [
+          score,
+          record.revision,
+          record.sessionId,
+          record.meta.name,
+          syncState,
+          windowCount,
+          typesIndicator,
+          menu.open,
+          euclid.open,
+          tui.ui.overlay,
+        ],
+      })
+    )
+      return;
     followCommitted();
+    tui.delight.song(record.sessionId, record.meta.heardLoop === true);
     play?.tick();
     // Values in the menu follow the score as edits land.
     if (menu.open) refreshMenu();
     if (euclid.open) refreshEuclid();
     refreshAuditionPicker();
-    tui.render(appView(score, clock.beatAt()), { force });
+    // The gate already paces frames; the app's own throttle would drop an
+    // approved frame that lands just after a forced one, and the gate would
+    // not ask again until the heartbeat.
+    tui.render(appView(score, clock.beatAt()), { force: true });
   };
   requestFrame = () => tick(true);
+  // The first wrap is remembered per song in .dawg metadata, never the score.
+  tui.onFirstLoop = () => {
+    void port
+      .updateMeta({ heardLoop: true })
+      .then((result) => adoptMeta(result.meta))
+      .catch(() => undefined);
+  };
   runPromptLater = (command) => {
     queuedPrompts.unshift(command);
     void drainQueue();
@@ -1109,6 +1467,16 @@ async function runInteractive(): Promise<void> {
   };
   agentEventSink = (event) => {
     if (event.type === "usage") return;
+    if (event.type === "command-typing") {
+      showMeTyping(event.text);
+      return;
+    }
+    if (event.type === "command") return;
+    if (event.type === "tool-start") {
+      const caption = toolCaption(event.name);
+      if (caption) showMeCaption(caption);
+    }
+    if (event.type === "done" || event.type === "error") showMeFinish();
     tui.activity.applyAgentEvent(event);
     if (event.type === "done" || event.type === "error") agentReported = true;
   };
@@ -1119,13 +1487,21 @@ async function runInteractive(): Promise<void> {
     tick(true);
   };
   stdout.on("resize", onResize);
+  const ownWrites = new OwnWrites();
+  let presenceClients: readonly {
+    clientId: string;
+    focusedTrackId?: string | null;
+  }[] = [];
   let applying: Promise<void> = Promise.resolve();
   const applyLatest = (latest: typeof record): Promise<void> =>
     (applying = applying.then(() => applyRecord(latest)));
   const applyRecord = async (latest: typeof record): Promise<void> => {
     try {
+      // Queued before a /fork or /resume swapped the session: stale.
+      if (latest.sessionId !== record.sessionId) return;
       if (latest.revision > record.revision) {
         const previousRevision = record.revision;
+        const before = score;
         record = latest;
         if (stageCapture)
           stageCapture.committed = scoreFromJSON(record.composition);
@@ -1162,11 +1538,27 @@ async function runInteractive(): Promise<void> {
           else if (payload.action === "toggle") await setTransport("toggle");
         }
         projectSync?.scoreChanged(score);
-        tui.activity.pushCard("synced from another window", {
-          tone: "info",
-          baseRevision: previousRevision,
-          resultRevision: record.revision,
-        });
+        // Another window's play/pause is followed, not announced, and this
+        // window's own writes (which can echo back before the append
+        // resolves) are never "synced".
+        const from = shownRevision(record, previousRevision);
+        const to = shownRevision(record);
+        await ownWrites.settled();
+        const foreign = foreignEvents(latest, previousRevision, ownWrites).some(
+          (event) => event.kind !== "transport",
+        );
+        if (to !== from && foreign)
+          tui.activity.pushCard(
+            `synced · ${otherWindowName(presenceClients, port.clientId, {
+              editedTrackId: editedTrack(
+                before,
+                scoreFromJSON(latest.composition),
+              ),
+              trackName: (id) =>
+                score.tracks.find((track) => track.id === id)?.name ?? id,
+            })}`,
+            { tone: "info", baseRevision: from, resultRevision: to },
+          );
       }
     } catch {
       // An invalid composition is skipped; the next update retries.
@@ -1177,8 +1569,10 @@ async function runInteractive(): Promise<void> {
       void applyLatest(update.record);
       adoptMeta(update.record.meta);
     } else if (update.type === "meta") adoptMeta(update.meta);
-    else if (update.type === "presence") windowCount = update.clients.length;
-    else if (update.type === "sync") syncState = update.sync;
+    else if (update.type === "presence") {
+      presenceClients = update.clients;
+      windowCount = update.clients.length;
+    } else if (update.type === "sync") syncState = update.sync;
     else if (update.type === "transport") {
       // Every window renders the same hit line from dawgd's timestamp.
       const { playing, beat, bpm, atMs } = update.transport;
@@ -1192,11 +1586,23 @@ async function runInteractive(): Promise<void> {
       });
     }
   };
-  let unsubscribe = port.subscribe(onUpdate);
+  // Each subscription answers only while its port is the live one: /fork and
+  // /resume swap the port, and a load the old port started before the swap
+  // could otherwise land afterwards and pull the old session's name and
+  // score into the new one.
+  const subscribeLive = (): (() => void) => {
+    const bound = port;
+    ownWrites.attach(bound);
+    return bound.subscribe((update) => {
+      if (bound === port) onUpdate(update);
+    });
+  };
+  let unsubscribe = subscribeLive();
   const refreshPresence = () =>
     void port
       .presence()
       .then((clients) => {
+        presenceClients = clients;
         windowCount = Math.max(1, clients.length);
       })
       .catch(() => undefined);
@@ -1208,12 +1614,13 @@ async function runInteractive(): Promise<void> {
   rebindPort = () => {
     unsubscribe();
     syncState = port.sync;
-    unsubscribe = port.subscribe(onUpdate);
+    unsubscribe = subscribeLive();
     refreshPresence();
   };
   if (freshWorkspace)
     tui.activity.pushCard("created .dawg/ · add it to .gitignore", {
       tone: "info",
+      once: true,
     });
   if (attachNotice)
     tui.activity.pushCard(attachNotice, {
@@ -1223,6 +1630,9 @@ async function runInteractive(): Promise<void> {
     });
   if (port.status !== "file session")
     tui.activity.pushCard(port.status, { tone: "info" });
+  void launchCard?.then((card) => {
+    if (card) tui.activity.pushCard(card.text, { tone: card.tone, once: true });
+  });
   if (await isProject(process.cwd()))
     projectSync = startProjectSync(syncHost());
   void currentProvider().then(() => tick(true));
@@ -1244,8 +1654,28 @@ async function runInteractive(): Promise<void> {
   stdin.on("end", onEnd);
   async function* chunks(): AsyncGenerator<string> {
     for (;;) {
-      while (inbox.length === 0)
-        await new Promise<void>((resolve) => (wake = resolve));
+      while (inbox.length === 0) {
+        // A partial escape (Alt+[, a cut-off paste) is flushed after a short
+        // idle so it never holds back the keys behind it.
+        const held = inputDecoder.pending();
+        const idle =
+          held === "paste"
+            ? PASTE_FLUSH_MS
+            : held === "escape"
+              ? ESCAPE_FLUSH_MS
+              : undefined;
+        let timeout: ReturnType<typeof setTimeout> | undefined;
+        const timedOut = await new Promise<boolean>((resolve) => {
+          wake = () => resolve(false);
+          if (idle !== undefined)
+            timeout = setTimeout(() => resolve(true), idle);
+        });
+        clearTimeout(timeout);
+        if (timedOut && inbox.length === 0) {
+          wake = undefined;
+          yield INPUT_FLUSH;
+        }
+      }
       wake = undefined;
       const next = inbox.shift()!;
       if (next === "\u0000eof") return;
@@ -1260,7 +1690,7 @@ async function runInteractive(): Promise<void> {
     stdin.pause();
     stdin.setRawMode?.(false);
     // Leave the alternate screen; restore the cursor and plain paste.
-    stdout.write(`${MOUSE_OFF}${ESC}0m${ESC}?2004l${ESC}?25h${ESC}?1049l`);
+    stdout.write(terminalRestore());
     try {
       return await flow();
     } finally {
@@ -1279,10 +1709,13 @@ async function runInteractive(): Promise<void> {
     let exiting = false;
     for await (const text of chunks()) {
       // A read that is exactly ESC is the Esc key, not the start of a sequence.
-      const values = [
-        ...inputDecoder.push(text),
-        ...(text === "\u001b" ? inputDecoder.flush() : []),
-      ];
+      const values =
+        text === INPUT_FLUSH
+          ? inputDecoder.flush()
+          : [
+              ...inputDecoder.push(text),
+              ...(text === "\u001b" ? inputDecoder.flush() : []),
+            ];
       while (values.length) {
         const value = values.shift()!;
         // A mouse report acts on what the last frame painted under it; some
@@ -1308,9 +1741,9 @@ async function runInteractive(): Promise<void> {
             continue;
           }
         }
-        // The `?` panel closes on any key (Ctrl-C still quits).
+        // The `?` panel closes on esc or ?; other keys wait (Ctrl-C quits).
         if (tui.ui.keys && typeof value === "string" && value !== "\u0003") {
-          tui.closeKeys();
+          if (closesKeys(value)) tui.closeKeys();
           tick(true);
           continue;
         }
@@ -1441,12 +1874,7 @@ async function runInteractive(): Promise<void> {
           // Never await a daemon round trip here: the key loop must stay
           // live for Esc, quit and redraws while the toggle is in flight.
           void toggleTransport()
-            .catch((error: unknown) => {
-              tui.activity.pushCard(
-                `transport failed · ${error instanceof Error ? error.message : String(error)}`,
-                { tone: "error" },
-              );
-            })
+            .catch((error: unknown) => transportFailed(error))
             .finally(() => tick(true));
         } else {
           const input = tui.input(value);
@@ -1475,7 +1903,9 @@ async function runInteractive(): Promise<void> {
             if (auditionLoop?.looping && isStageable(input.value))
               hoverItem(input.value, `picker:${input.picker}`);
             else if (input.picker === "pattern")
-              previewPattern(input.value.replace(/^\/pattern\s+/, ""));
+              previewPattern(
+                input.value.replace(/^\/(?:pattern|groove)\s+/, ""),
+              );
           } else if (input.type === "pick-audition") {
             pickerAuditionKey(input.key);
           } else if (input.type === "pick-cancel") {
@@ -1527,6 +1957,16 @@ async function runInteractive(): Promise<void> {
           else if (action?.kind === "cancel" && agentTurn) {
             agentTurn.controller.abort();
             tui.activity.setSpinner("cancelling");
+          } else if (
+            action?.kind === "submit" &&
+            action.value &&
+            agentTurn &&
+            routeDuringTurn(action.value, parsesLocally) === "local"
+          ) {
+            // A typed command never waits on the agent: it commits its own
+            // revision now, and the agent's next call re-reads the score.
+            const value = action.value;
+            void runLocalBesideAgent(value).finally(() => tick(true));
           } else if (action?.kind === "submit" && action.value && agentTurn) {
             // Enter during a turn steers it; Alt-Enter still queues a follow-up.
             agentTurn.steering.push(action.value);
@@ -1557,17 +1997,36 @@ async function runInteractive(): Promise<void> {
     stdin.off("end", onEnd);
     clearInterval(timer);
     clearInterval(presenceTimer);
-    await projectSync?.stop();
-    namer.dispose();
     stdout.off("resize", onResize);
-    unsubscribe();
-    await play?.exit().catch(() => undefined);
-    await monitorEngine?.dispose().catch(() => undefined);
-    audio.stop();
-    await port.close();
-    stdin.setRawMode?.(false);
+    // The terminal first: a teardown step that throws (a read-only .dawg,
+    // a dead engine) must not leave the shell on the alternate screen.
+    restoreTerminal();
     stdin.pause();
-    stdout.write(`${MOUSE_OFF}${ESC}0m${ESC}?2004l${ESC}?25h${ESC}?1049l`);
+    console.error = consoleError;
+    console.warn = consoleWarn;
+    process.off("warning", onWarning);
+    unwatchActivity();
+    // Each step on its own: one failure does not skip the rest.
+    const failures: unknown[] = [];
+    const steps: Array<() => unknown> = [
+      () => projectSync?.stop(),
+      () => namer.dispose(),
+      () => unsubscribe(),
+      () => play?.exit(),
+      () => monitorEngine?.dispose(),
+      () => audio.stop(),
+      () => port.close(),
+    ];
+    for (const step of steps) {
+      try {
+        await step();
+      } catch (error) {
+        failures.push(error);
+      }
+    }
+    process.off("unhandledRejection", onRejection);
+    process.off("uncaughtException", onUncaught);
+    if (failures.length > 0) throw failures[0];
   }
 }
 
@@ -1582,23 +2041,23 @@ function unknownCommand(command: string): string {
 
 async function submit(prompt: string): Promise<string | Receipt> {
   const command = prompt.trim();
+  // Canonical names for window commands: `model key` (login), `models`,
+  // `voice` (the Voice topic).
+  const canonical = canonicalWindowForm(command);
+  if (canonical) return submit(canonical);
   const helpCommand = command.match(/^\/?(?:help|\?)(?:\s+(\S+))?$/i);
   if (helpCommand) {
     const topic = helpCommand[1];
+    // The panel's inner width (tui/app.ts paintText): rows clip there with
+    // an ellipsis, the same as every other panel.
+    const columns = stdout.columns ?? 80;
     const lines = helpTopicLines(
       topic,
-      Math.max(40, (stdout.columns ?? 80) - 10),
-    );
-    if (!lines)
-      return fail(
-        `no help topic ${topic} · /help all · ${HELP_TOPICS.join(" ")}`,
-      );
-    tui.openText(topic ? `help · ${topic.toLowerCase()}` : "help", lines);
-    return ok(
-      topic
-        ? `help · ${topic.toLowerCase()}`
-        : "help · /help all for every command",
+      Math.max(10, columns - (columns >= 60 ? 8 : 4)),
     );
+    if (!lines) return fail(helpMiss(topic!));
+    tui.openText(helpTitle(topic), lines);
+    return ok(topic ? helpTitle(topic) : "help · help all for every command");
   }
   if (/^\/?tracks$/i.test(command)) {
     const problems = await sampleProblems(score);
@@ -1630,7 +2089,32 @@ async function submit(prompt: string): Promise<string | Receipt> {
         items.findIndex((item) => item.current),
       ),
     });
-    return ok(`${items.length} track${items.length === 1 ? "" : "s"}`);
+    return note(`${items.length} track${items.length === 1 ? "" : "s"}`);
+  }
+  if (/^\/?(?:instruments|instrument\s+(?:list|ls|presets))$/i.test(command)) {
+    // `instrument list`: every word `instrument <name>` takes, by family.
+    const columns = stdout.columns ?? 80;
+    const lines = instrumentListLines(
+      Math.max(10, columns - (columns >= 60 ? 8 : 4)),
+    );
+    tui.openText("instruments", lines);
+    return note("instruments · instrument <name> on the focused track");
+  }
+  if (/^\/?notes(?:\s+(?:list|ls))?$/i.test(command)) {
+    // `notes`: the focused track's note ids, the names `remove <id>` takes.
+    const notes = score.notes
+      .filter((entry) => entry.trackId === requestedTrack)
+      .slice()
+      .sort((a, b) => a.startTick - b.startTick);
+    const lines = notes.map(
+      (entry) =>
+        `${entry.id} · ${midiNoteName(entry.pitch)} · beat ${+(entry.startTick / score.ticksPerBeat).toFixed(2)}`,
+    );
+    if (lines.length === 0) return note(`notes · ${requestedTrack} has none`);
+    tui.openText(`notes · ${requestedTrack}`, lines);
+    return note(
+      `${lines.length} note${lines.length === 1 ? "" : "s"} · ${requestedTrack} · remove <id>`,
+    );
   }
   const playCommand = command.match(
     /^\/play(?:\s+(on|off|degrees|in-key|chromatic))?$/i,
@@ -1656,9 +2140,31 @@ async function submit(prompt: string): Promise<string | Receipt> {
   }
   const chordsCommand = command.match(/^\/chords(?:\s+(.+))?$/i);
   if (chordsCommand) {
-    const result = applyChordsCommand(chordSettings, chordsCommand[1] ?? "");
+    const result = applyChordsCommand(
+      chordSettings,
+      chordsCommand[1] ?? "",
+      score.tempoBpm,
+    );
     return result.ok ? ok(result.message) : fail(result.message);
   }
+  const showMeCommand = command.match(/^\/show-?me(?:\s+(\S+))?$/i);
+  if (showMeCommand) {
+    if (!showMeCommand[1])
+      return ok(`show me · ${showMe.level} · /showme on|quiet|off`);
+    const level = parseShowMe(showMeCommand[1]);
+    if (!level) return fail("usage · /showme on|quiet|off");
+    showMe.level = level;
+    void writeConfig({ dir: configDir() }, { showMe: level }).catch(
+      () => undefined,
+    );
+    return ok(
+      level === "off"
+        ? "show me off · the agent edits with tools"
+        : level === "quiet"
+          ? "show me quiet · the agent types commands, no captions"
+          : "show me on · the agent types commands, slides faders, plays keys",
+    );
+  }
   const countIn = command.match(/^\/count-?in\s+([0-2])$/i);
   if (countIn) return ok(playSession().setCountIn(Number(countIn[1])));
   const euclidCommand = command.match(/^\/euclid(?:\s+(\S+))?$/i);
@@ -1673,21 +2179,45 @@ async function submit(prompt: string): Promise<string | Receipt> {
   }
   const tryCommand = command.match(/^\/try(?:\s+(.+))?$/i);
   if (tryCommand) return tryPrompt(tryCommand[1]?.trim() ?? "");
-  // A bare parameter (`volume`, `pan`, `fx filter`, `fx reverb mix`)
-  // opens the fader drawer on it, with its related params stacked below.
-  if (/^\/?(?:volume|pan|fx\s+\S+(?:\s+\S+)?)$/i.test(command)) {
-    const label = menu.showFader(menuContext(), command);
+  // A bare scalar (`volume`, `pan`, `fx reverb mix`, and the song's
+  // `tempo`, `bars` and `meter`) opens the fader drawer on it, with its
+  // related params stacked below.
+  if (
+    /^\/?(?:volume|pan|tempo|bpm|bars|meter|fx\s+\S+(?:\s+\S+)?)$/i.test(
+      command,
+    )
+  ) {
+    const context = menuContext();
+    const label =
+      menu.showFader(context, command) ?? songFader(context, command);
     if (label) {
+      const field = menu
+        .faderFields(context)
+        .find((candidate) => candidate.label === label);
+      // The receipt names the value it opened on: `tempo · 120 BPM · …`.
+      const value =
+        field?.kind === "number"
+          ? field.value !== undefined
+            ? field.format(field.value)
+            : field.off
+          : undefined;
       openFader(label, true);
       refreshMenu();
-      return ok(`${label} · ←→ adjust · enter keep · esc revert`);
+      return ok(
+        `${label}${value ? ` · ${value}` : ""} · ←→ adjust · enter keep · esc revert`,
+      );
     }
   }
   const menuCommand = command.match(/^\/menu(?:\s+(\S+))?$/i);
   if (menuCommand) {
     const section = menuCommand[1]?.toLowerCase();
-    if (section && !(MENU_SECTIONS as readonly string[]).includes(section))
-      return fail(`/menu [${MENU_SECTIONS.join("|")}]`);
+    // §4: the keys topic has no menu page; it opens the ? panel.
+    if (section && (section === "keys" || TOPIC_ALIASES[section] === "keys")) {
+      tui.showKeys("keys", keyLines(KEYS.prompt));
+      return ok("keys");
+    }
+    if (section && !menuSectionPath(menuContext(), section))
+      return fail(menuUsage(menuContext(), section));
     openMenu(section);
     return ok("menu");
   }
@@ -1717,6 +2247,73 @@ async function submit(prompt: string): Promise<string | Receipt> {
     if (requestedTrack !== grainTrack[1]!.toLowerCase()) return focused;
     return submit(grainTrack[2]!);
   }
+  // `/track rm <name>` (aliases remove, delete) and `/track move <name>
+  // <position>`: the human surface for the removeTrack and moveTrack
+  // operations. Removing a track also drops any vocoder src or autotune from
+  // that named it; ^z brings everything back.
+  const trackEdit = command.match(
+    /^\/?track\s+(rm|remove|delete|move)\s+(.{1,64}?)\s*$/i,
+  );
+  if (trackEdit) {
+    const verb = trackEdit[1]!.toLowerCase() === "move" ? "move" : "rm";
+    let rest = trackEdit[2]!.trim();
+    let position: number | undefined;
+    if (verb === "move") {
+      const tail = rest.match(/^(.+?)\s+(\d{1,3})$/);
+      if (!tail)
+        return fail(`usage · /track move <name> <1..${score.tracks.length}>`);
+      rest = tail[1]!;
+      position = Number(tail[2]);
+    }
+    const wanted = rest
+      .replace(/^["']|["']$/g, "")
+      .trim()
+      .replace(/\s+/g, " ")
+      .toLowerCase();
+    const found = score.tracks.find(
+      (track) =>
+        track.id.toLowerCase() === wanted ||
+        track.id.toLowerCase() === wanted.replace(/ /g, "-") ||
+        (track.name ?? "").toLowerCase() === wanted,
+    );
+    if (!found) return fail(noTrack(rest));
+    if (verb === "move") {
+      if (position! < 1 || position! > score.tracks.length)
+        return fail(`usage · /track move <name> <1..${score.tracks.length}>`);
+      const next = applyScoreOperation(score, {
+        type: "moveTrack",
+        trackId: found.id,
+        index: position! - 1,
+      });
+      await commitScore(next, "track.move", { trackId: found.id });
+      await projectSync?.flushScore();
+      return ok(`moved ${found.id} to position ${position}`);
+    }
+    if (score.tracks.length <= 1)
+      return fail("the last track stays · /clear empties it");
+    const next = applyScoreOperation(score, {
+      type: "removeTrack",
+      trackId: found.id,
+    });
+    const dropped = score.tracks
+      .filter((track) => track.id !== found.id)
+      .filter((track) => {
+        const after = next.tracks.find((t) => t.id === track.id);
+        return (
+          (track.vocoder?.src !== undefined &&
+            after?.vocoder?.src === undefined) ||
+          (track.autotune?.from !== undefined &&
+            after?.autotune?.from === undefined)
+        );
+      })
+      .map((track) => track.id);
+    await commitScore(next, "track.remove", { trackId: found.id });
+    await projectSync?.flushScore();
+    if (found.id === requestedTrack) await focusTrack(next.tracks[0]!.id);
+    return ok(
+      `removed ${found.id}${dropped.length ? ` · dropped references on ${dropped.join(", ")}` : ""} · ctrl-z undoes`,
+    );
+  }
   // `/track piano b`: a name with spaces focuses the track of that name, or
   // creates `piano-b` named "piano b".
   const namedTrack = command.match(/^\/track\s+([a-z0-9._ -]{1,64})$/i);
@@ -1731,12 +2328,100 @@ async function submit(prompt: string): Promise<string | Receipt> {
   if (sample) return sampleCommand(sample);
   const fit = parseFitCommand(command);
   if (fit) return fitCommand(fit);
+  const shift = parseShiftCommand(command);
+  if (shift) {
+    const result = applyShiftCommand(score, requestedTrack, shift);
+    if (!result.ok) return fail(result.message);
+    await commitScore(result.next, "sample.set", { trackId: requestedTrack });
+    await projectSync?.flushScore();
+    return ok(result.message);
+  }
+  const resample = parseResampleCommand(command);
+  if (resample) return resampleCommand(resample);
+  // 0.7 clips: `/clip` edits and `/lyrics` on the focused track.
+  const clipCommand = parseClipCommand(command);
+  if (clipCommand) {
+    if ("error" in clipCommand) return fail(clipCommand.error);
+    const result = await runClipCommand(clipCommand, {
+      score,
+      trackId: requestedTrack,
+      cwd: process.cwd(),
+    });
+    if (!result.ok) return fail(result.message);
+    if (result.next && result.kind) {
+      await commitScore(result.next, result.kind, {
+        trackId: requestedTrack,
+        ...result.payload,
+      });
+      await projectSync?.flushScore();
+    }
+    return ok(result.message);
+  }
+  const lyricsCommand = parseLyricsCommand(command);
+  if (lyricsCommand) {
+    const result = applyLyrics(score, requestedTrack, lyricsCommand);
+    if (!result.ok) return fail(result.message);
+    if (result.next && result.kind) {
+      await commitScore(result.next, result.kind, {
+        trackId: requestedTrack,
+        ...result.payload,
+      });
+      await projectSync?.flushScore();
+    }
+    return ok(result.message);
+  }
+  // 0.7 autotune: `/autotune …` (and `/tune <preset>` pointing here).
+  // `/vocal autotune …` takes the same path (presets panel, draft, commit).
+  const autotune = parseAutotuneCommand(
+    command.replace(/^\/?vocal\s+(?=autotune\b)/i, ""),
+  );
+  if (autotune) {
+    if (autotune.type === "autotune-list")
+      tui.openText("autotune presets", autotuneListLines());
+    if (autotune.type !== "autotune-usage" && autotune.type !== "autotune-list")
+      await materializeDraft();
+    const result = applyAutotuneCommand(score, requestedTrack, autotune);
+    if (result.next && result.kind)
+      await commitScore(result.next, result.kind, result.payload);
+    return result.ok ? ok(result.message) : fail(result.message);
+  }
+  // 0.7 Voice: `/vocal <verb>`; lanes register verbs in VOCAL_VERBS.
+  setClipImportDeps({
+    media: {
+      ...mediaServices(),
+      signal: new AbortController().signal,
+      progress: () => undefined,
+    },
+  });
+  const vocal = parseVocalCommand(command);
+  if (vocal) {
+    if (vocal.kind === "verb") await materializeDraft();
+    const result = await runVocalCommand(vocal, {
+      score,
+      trackId: requestedTrack,
+      cwd: process.cwd(),
+    });
+    if (!result.ok) return fail(result.message);
+    if (result.next && result.kind) {
+      await commitScore(result.next, result.kind, {
+        trackId: requestedTrack,
+        ...result.payload,
+      });
+      await projectSync?.flushScore();
+    }
+    // A verb that made or chose another track (a vocoder carrier): focus it.
+    if (result.trackId && result.trackId !== requestedTrack) {
+      await port.focus(result.trackId);
+      requestedTrack = result.trackId;
+    }
+    return ok(result.message);
+  }
   const pack = parsePackCommand(command);
   if (pack) return packCommand(pack);
   const pattern = parsePatternCommand(command);
   if (pattern) return patternCommand(pattern);
   const kit = parseKitCommand(command);
-  if (kit) return kitCommand(kit, /^\/kit\s*$/i.test(command.trim()));
+  if (kit) return kitCommand(kit, /^\/?kits?\s*$/i.test(command.trim()));
   const wavetable = parseWavetableCommand(command);
   if (wavetable) return wavetableCommand(wavetable);
   const sessionReply = await sessionCommand(command);
@@ -1765,11 +2450,52 @@ async function submit(prompt: string): Promise<string | Receipt> {
       await commitScore(result.next, result.kind, result.payload);
     return result.ok ? ok(result.message) : fail(result.message);
   }
+  const guitar = parseGuitarCommand(command);
+  if (guitar) {
+    if (guitar.type !== "guitar-show" && guitar.type !== "guitar-hint")
+      await materializeDraft();
+    const result = applyGuitarCommand(score, requestedTrack, guitar);
+    if (result.next && result.kind)
+      await commitScore(result.next, result.kind, result.payload);
+    return result.ok ? ok(result.message) : fail(result.message);
+  }
+  const progression = parseProgressionCommand(command);
+  if (progression) {
+    if (progression.type === "progression") await materializeDraft();
+    const result = applyProgressionCommand(
+      score,
+      requestedTrack,
+      progression,
+      () => randomUUID().slice(0, 12),
+    );
+    if (result.next && result.kind)
+      await commitScore(result.next, result.kind, result.payload);
+    return result.ok ? ok(result.message) : fail(result.message);
+  }
+  const strum = parseStrumCommand(command);
+  if (strum) {
+    if (strum.type === "strum") await materializeDraft();
+    const result = applyStrumCommand(score, requestedTrack, strum, () =>
+      randomUUID().slice(0, 12),
+    );
+    if (result.next && result.kind)
+      await commitScore(result.next, result.kind, result.payload);
+    return result.ok ? ok(result.message) : fail(result.message);
+  }
   const rig = parseRigCommand(command);
   if (rig) {
     if (rig.type !== "rig-show" && rig.type !== "rig-hint")
       await materializeDraft();
     const result = applyRigCommand(score, requestedTrack, rig);
+    if (result.next && result.kind)
+      await commitScore(result.next, result.kind, result.payload);
+    return readOrDone(result);
+  }
+  // 0.7 `/formant` and `/vowel`: short forms of `fx formant|vowel`.
+  const formant = parseFormantCommand(command) ?? parseVowelCommand(command);
+  if (formant) {
+    if (formant.type === "fx") await materializeDraft();
+    const result = applyFormantCommand(score, requestedTrack, formant);
     if (result.next && result.kind)
       await commitScore(result.next, result.kind, result.payload);
     return result.ok ? ok(result.message) : fail(result.message);
@@ -1791,6 +2517,8 @@ async function submit(prompt: string): Promise<string | Receipt> {
     const result = applyFxCommand(score, requestedTrack, fx, pinnedIr);
     if (result.next && result.kind)
       await commitScore(result.next, result.kind, result.payload);
+    // Bare `fx` reads the chain (`•`); it changes nothing.
+    if (result.ok && fx.type === "fx-list") return note(result.message);
     return result.ok ? ok(result.message) : fail(result.message);
   }
   const unknownFx = unknownFxMessage(command);
@@ -1806,6 +2534,13 @@ async function submit(prompt: string): Promise<string | Receipt> {
   }
   const tuning = parseTuningCommand(command);
   if (tuning) return tuningCommand(tuning);
+  const calibration = parseCalibrationCommand(command);
+  if (calibration) {
+    const result = applyCalibrationCommand(score, calibration);
+    if (result.next && result.kind)
+      await commitScore(result.next, result.kind, result.payload);
+    return result.ok ? ok(result.message) : fail(result.message);
+  }
   const keysCommand = parseKeysCommand(command);
   if (keysCommand) {
     const reads =
@@ -1827,13 +2562,54 @@ async function submit(prompt: string): Promise<string | Receipt> {
       await commitScore(result.next, result.kind, result.payload);
     return result.ok ? ok(result.message) : fail(result.message);
   }
+  const vocoderCommand = parseVocoderCommand(command);
+  if (vocoderCommand) {
+    if (vocoderCommand.type === "vocoder-list")
+      tui.openText("vocoder presets", vocoderListLines());
+    if (
+      vocoderCommand.type !== "vocoder-list" &&
+      vocoderCommand.type !== "vocoder-usage"
+    )
+      await materializeDraft();
+    const result = applyVocoderCommand(score, requestedTrack, vocoderCommand);
+    if (result.next && result.kind)
+      await commitScore(result.next, result.kind, result.payload);
+    // `/vocoder` on a vocal makes a carrier track: focus it.
+    if (result.trackId && result.trackId !== requestedTrack) {
+      await port.focus(result.trackId);
+      requestedTrack = result.trackId;
+    }
+    return result.ok ? ok(result.message) : fail(result.message);
+  }
+  const windCommand = parseWindCommand(command);
+  if (windCommand) {
+    if (windCommand.type === "wind-list")
+      tui.openText("wind presets", windListLines());
+    if (windCommand.type !== "wind-show" && windCommand.type !== "wind-list")
+      await materializeDraft();
+    const result = applyWindCommand(score, requestedTrack, windCommand);
+    if (result.next && result.kind)
+      await commitScore(result.next, result.kind, result.payload);
+    return result.ok ? ok(result.message) : fail(result.message);
+  }
+  const singCommand = parseSingCommand(command);
+  if (singCommand) {
+    if (singCommand.type === "sing-list")
+      tui.openText("sing presets", singListLines());
+    if (singCommand.type !== "sing-show" && singCommand.type !== "sing-list")
+      await materializeDraft();
+    const result = applySingCommand(score, requestedTrack, singCommand);
+    if (result.next && result.kind)
+      await commitScore(result.next, result.kind, result.payload);
+    return result.ok ? ok(result.message) : fail(result.message);
+  }
   const synth = parseSynthCommand(command);
   if (synth) {
     if (synth.type !== "synth-list") await materializeDraft();
     const result = applySynthCommand(score, requestedTrack, synth);
     if (result.next && result.kind)
       await commitScore(result.next, result.kind, result.payload);
-    return result.ok ? ok(result.message) : fail(result.message);
+    return readOrDone(result);
   }
   const stringCommand = parseStringCommand(command);
   if (stringCommand) {
@@ -1845,7 +2621,7 @@ async function submit(prompt: string): Promise<string | Receipt> {
     const result = applyStringCommand(score, requestedTrack, stringCommand);
     if (result.next && result.kind)
       await commitScore(result.next, result.kind, result.payload);
-    return result.ok ? ok(result.message) : fail(result.message);
+    return readOrDone(result);
   }
   const grainHint = grainSrcHint(command);
   if (grainHint) return fail(grainHint);
@@ -1858,6 +2634,50 @@ async function submit(prompt: string): Promise<string | Receipt> {
       await commitScore(result.next, result.kind, result.payload);
     return result.ok ? ok(result.message) : fail(result.message);
   }
+  const styleCommand = parseStyleCommand(
+    /^\/?styles?\s+presets$/i.test(command) ? "style list" : command,
+  );
+  if (styleCommand) {
+    const writes =
+      styleCommand.type === "style-apply" ||
+      styleCommand.type === "style-again";
+    // Bare `style` opens Arrange › style; `style list|ls|presets` lists.
+    if (
+      styleCommand.type === "style-families" &&
+      /^\/?styles?$/i.test(command)
+    ) {
+      openMenu("style");
+      return ok(
+        "style · ↑/↓ browse · enter makes the song · style list prints it",
+      );
+    }
+    if (writes) await materializeDraft();
+    const result = applyStyleCommand(score, styleCommand);
+    if (result.next && result.kind)
+      await commitScore(result.next, result.kind, result.payload);
+    if (result.log) tui.activity.pushNote(result.log);
+    if (!result.ok) return fail(result.message);
+    // A multi-line listing opens as text; the card keeps its first line
+    // so lines never run together on the one-line strip.
+    if (!writes && result.message.includes("\n")) {
+      const [head = "styles", ...rest] = result.message.split("\n");
+      tui.openText(head, rest);
+      return note(head);
+    }
+    // A new song: focus its first melodic track, so play and the menu
+    // land on something tonal instead of a track the style replaced.
+    const melodic = writes
+      ? result.next?.tracks.find((track) => !isDrumInstrument(track.instrument))
+      : undefined;
+    if (melodic && melodic.id !== requestedTrack) {
+      await port.focus(melodic.id);
+      requestedTrack = melodic.id;
+      draftTrack = false;
+    }
+    return ok(
+      melodic ? `${result.message} · focused ${melodic.id}` : result.message,
+    );
+  }
   const masterCommand = parseMasterCommand(command);
   if (masterCommand) {
     if (masterCommand.type === "master-measure")
@@ -1870,7 +2690,33 @@ async function submit(prompt: string): Promise<string | Receipt> {
     const result = applyMasterCommand(score, masterCommand);
     if (result.next && result.kind)
       await commitScore(result.next, result.kind, result.payload);
-    return result.ok ? ok(result.message) : fail(result.message);
+    return readOrDone(result);
+  }
+  // `loop <section> | <a>-<b> | off`: what playback loops, a section.
+  const loop = parseLoopCommand(command);
+  if (loop) {
+    if (loop.type === "loop-show")
+      return note(
+        score.loopSection
+          ? `loop · ${score.loopSection} · loop off plays the song`
+          : `loop · the song · ${LOOP_USAGE}`,
+      );
+    if (loop.type === "loop-off") return submit("section loop off");
+    if (loop.type === "loop-section")
+      return submit(`section loop ${loop.name}`);
+    const span = score.sections.find(
+      (section) =>
+        section.startBar + 1 === loop.from &&
+        section.startBar + section.bars === loop.to,
+    );
+    if (span) return submit(`section loop ${span.name}`);
+    // No section spans the bars: mark (or move) the section named `loop`
+    // and loop it, as one revision.
+    await materializeDraft();
+    const result = loopSpan(score, requestedTrack, loop.from, loop.to);
+    if (!result.ok) return fail(result.message);
+    await commitScore(result.next, "score.sections", { loop: result.name });
+    return ok(result.message);
   }
   const arrange = parseSectionCommand(command, score);
   if (arrange) {
@@ -1884,7 +2730,7 @@ async function submit(prompt: string): Promise<string | Receipt> {
     if (result.next && result.kind)
       await commitScore(result.next, result.kind, result.payload);
     if (result.seekBeat !== undefined) await seekTransport(result.seekBeat);
-    return result.ok ? ok(result.message) : fail(result.message);
+    return readOrDone(result);
   }
   const music = parseMusicCommand(command);
   if (music) {
@@ -1896,20 +2742,21 @@ async function submit(prompt: string): Promise<string | Receipt> {
       await commitScore(result.next, result.kind, result.payload);
     return result.ok ? ok(result.message) : fail(result.message);
   }
-  const exportCommand = command.match(/^\/?export\s+([^\s]+)$/i);
+  const exportCommand = parseExportCommand(command);
   if (exportCommand) {
-    const path = resolve(exportCommand[1]!);
-    if (/\.midi?$/i.test(path)) {
+    const path = resolve(exportCommand.path);
+    if (exportCommand.format === "mid") {
       await writeFile(path, scoreToMidi(exportScore(score)));
-      return `exported midi · ${exportCommand[1]}`;
+      return `exported midi · ${exportCommand.path}`;
     }
-    // Audio comes from the offline renderer, never JSON under an audio name.
-    if (/\.(wav|aiff?|flac|mp3|ogg|m4a)$/i.test(path))
-      return fail(
-        `/export writes .track.json or .mid · render audio with: dawg render ${exportCommand[1]}`,
-      );
+    // Audio goes through the `dawg render` path, the same bytes as the CLI.
+    if (exportCommand.format === "wav")
+      return exportWav(exportCommand.path, exportCommand.stems);
+    // Other audio names are not formats dawg writes.
+    if (/\.(aiff?|flac|mp3|ogg|m4a)$/i.test(path))
+      return fail(`export · ${exportCommand.path} · ${EXPORT_USAGE}`);
     await writeFile(path, encodeLoop(score), "utf8");
-    return `exported · ${exportCommand[1]}`;
+    return `exported · ${exportCommand.path}`;
   }
   const importCommand = command.match(/^\/?import\s+([^\s]+)$/i);
   if (importCommand) {
@@ -1944,14 +2791,14 @@ async function submit(prompt: string): Promise<string | Receipt> {
         tui.activity.setSpinner(undefined);
       }
     }
-    const receiptText = await tuiSetModel(modelMatch[1]);
+    const result = await tuiSetModel(modelMatch[1]);
     provider = undefined;
     await currentProvider();
-    return receiptText;
+    return result.ok ? result.text : fail(result.text);
   }
   if (/^\/login\b/i.test(prompt.trim())) {
     const parsed = tuiLoginArgs(prompt.trim());
-    if (typeof parsed === "string") return `login · ${parsed}`;
+    if (typeof parsed === "string") return `model key · ${parsed}`;
     await handoff(() =>
       runTuiLogin(
         parsed.target === "auto" ? "pick" : parsed.target,
@@ -1961,8 +2808,8 @@ async function submit(prompt: string): Promise<string | Receipt> {
     provider = undefined;
     await currentProvider();
     return providerName === "offline"
-      ? "login · not signed in · direct commands still work"
-      : `signed in · ${providerName}`;
+      ? "no agent key · model key adds one · direct commands still work"
+      : `agent key · ${providerName}`;
   }
   if (/^\/(logout|auth)\b/i.test(prompt.trim())) {
     tui.activity.setSpinner(prompt.trim().split(/\s+/)[0]!.slice(1));
@@ -1977,8 +2824,46 @@ async function submit(prompt: string): Promise<string | Receipt> {
       tui.activity.setSpinner(undefined);
     }
   }
+  // The grammar's second reading (design §3): a line no handler took runs
+  // in its other spellings — `/x` ≡ `x`, aliases, `rm|remove|delete`,
+  // `list|presets|ls` — so only lines that failed before get one.
+  // A line the core prompt parser takes is already understood.
+  if (!recovering && !parsePrompt(prompt)) {
+    const retry = recover(
+      command,
+      (candidate) =>
+        parseExact(candidate, score) !== undefined ||
+        // Window verbs get only the slash toggle, never a listing word.
+        (candidate.startsWith("/") &&
+          SLASH_HANDLED.has(verbOf(candidate)) &&
+          candidate.split(/\s+/).length === command.trim().split(/\s+/).length),
+    );
+    if (retry !== undefined) {
+      recovering = true;
+      try {
+        return await submit(retry);
+      } finally {
+        recovering = false;
+      }
+    }
+  }
+  // Bare `rename`, `fork`, `resume`, `login` take free text: a hint only.
+  const freeText = FREE_TEXT_HINTS[command.toLowerCase()];
+  if (freeText !== undefined) return note(freeText);
+  const elsewhere = elsewhereHint(command);
+  if (elsewhere !== undefined) return note(elsewhere);
   // `/model` belongs to its own handler above; every other slash word that
   // reached here is unknown or misused, and never a question for the agent.
+  // `/instrument aah` is `instrument aah`; `instrument sing choir` is
+  // `instrument choir`.
+  const singWord = command.match(/^\/?instrument\s+sing\s+([a-z]+)$/i);
+  if (singWord && isSingWord(singWord[1]!.toLowerCase()))
+    return submit(`instrument ${singWord[1]!.toLowerCase()}`);
+  if (/^\/instrument\s/i.test(command) && parsePrompt(command.slice(1)))
+    return submit(command.slice(1));
+  // A synth or effect number out of range names its range.
+  const range = paramRangeError(command);
+  if (range) return fail(range);
   if (command.startsWith("/") && !/^\/model\b/i.test(command)) {
     const hint = usageHint(command);
     return fail(
@@ -1993,6 +2878,10 @@ async function submit(prompt: string): Promise<string | Receipt> {
     // A one-letter slip on a command whose arguments parse stays local.
     const fix = typoFix(command, parsesLocally);
     if (fix) return fail(`${truncateForCard(command)} · did you mean ${fix}?`);
+    // A grammar verb (not everyday English) never reaches the agent.
+    const verb = verbOf(command);
+    if (knownVerbs().has(verb) && !EVERYDAY_VERBS.has(verb))
+      return fail(usageCard(truncateForCard(command), `/help ${verb}`));
     if (process.env.DAWG_AI === "0")
       return fail(`unrecognized · ${truncateForCard(command)} · /help`);
     await materializeDraft();
@@ -2022,6 +2911,9 @@ async function submit(prompt: string): Promise<string | Receipt> {
     return parsed.action;
   }
   if (parsed.type === "set-tempo") {
+    const range = RANGES.tempo!;
+    if (parsed.tempoBpm < range.min || parsed.tempoBpm > range.max)
+      return fail(usageError(truncateForCard(command), range));
     const next = score.withTempo(parsed.tempoBpm);
     await commitScore(next, "score.tempo", { tempoBpm: parsed.tempoBpm });
     clock.follow(next);
@@ -2049,15 +2941,10 @@ async function submit(prompt: string): Promise<string | Receipt> {
   if (parsed.type === "track") {
     // An unknown word would store and play a plain sine: say so instead.
     const word = parsed.patch.instrument;
-    if (word !== undefined && isUnknownInstrument(word)) {
-      const advice = plainSineAdvice(word) ?? "";
-      const near = advice.match(/did you mean (\S+)\?/)?.[1];
-      return fail(
-        `instrument ${truncateForCard(word)} · not a dawg instrument${near ? ` · did you mean ${near}?` : ""} · /menu sounds lists them`,
-      );
-    }
+    if (word !== undefined && isUnknownInstrument(word))
+      return fail(unknownInstrumentMessage(word));
     // `instrument jangle`: a guitar alias also loads its rig.
-    const patch = parsed.word
+    const rigged = parsed.word
       ? {
           ...parsed.patch,
           ...rigWordPatch(
@@ -2066,6 +2953,11 @@ async function submit(prompt: string): Promise<string | Receipt> {
           ),
         }
       : parsed.patch;
+    // `instrument vocal` (0.7): the vocal chain fills unset effects.
+    const chain = isGuideInstrument(parsed.patch.instrument)
+      ? vocalChainPatch(score.tracks.find((t) => t.id === requestedTrack))
+      : {};
+    const patch = { ...chain, ...rigged };
     const next = applyScoreOperation(score, {
       type: "updateTrack",
       trackId: requestedTrack,
@@ -2078,11 +2970,21 @@ async function submit(prompt: string): Promise<string | Receipt> {
     // Plain `marimba` keeps the legacy tone; point at the mallet engine.
     if (parsed.patch.instrument === "marimba" && !("modal" in parsed.patch))
       return `track · ${requestedTrack} · marimba (legacy tone) · modal marimba for the mallet engine`;
+    // Plain `wind` keeps the legacy tone; point at the wind engine.
+    if (parsed.patch.instrument === "wind" && !("wind" in parsed.patch))
+      return `track · ${requestedTrack} · wind (legacy tone) · wind flute (or sax, trumpet …) for the wind engine`;
     const sine =
       word !== undefined && !("string" in parsed.patch)
         ? plainSineAdvice(word)
         : undefined;
     if (sine) return `track · ${requestedTrack} · ${sine}`;
+    const added = [
+      chain.filter ? "hpf 90 Hz" : "",
+      chain.fx?.compressor ? "compressor 3:1" : "",
+      chain.reverb ? "plate 0.14" : "",
+    ].filter(Boolean);
+    if (added.length)
+      return `track · ${requestedTrack} · vocal · added ${added.join(", ")} · fx … off to remove`;
     return `track · ${requestedTrack}`;
   }
   if (parsed.type === "automation") {
@@ -2127,6 +3029,9 @@ async function submit(prompt: string): Promise<string | Receipt> {
     return `cleared · ${requestedTrack}`;
   }
   if (parsed.type === "remove-note") {
+    // A receipt never claims a removal that did not happen.
+    if (!score.notes.some((note) => note.id === parsed.noteId))
+      return fail(noNote(parsed.noteId));
     const next = applyScoreOperation(score, {
       type: "removeNote",
       noteId: parsed.noteId,
@@ -2244,6 +3149,10 @@ async function focusTrack(trackId: string): Promise<Receipt> {
         ...newPianoTrack(trackId),
         // `track vibes`: a 0.6 modal word names the track and its preset.
         ...(isModalWord(trackId) ? instrumentPatchForWord(trackId) : {}),
+        // `track vocal` (0.7): a clip track with the vocal chain.
+        ...(isGuideInstrument(trackId)
+          ? { instrument: "vocal", ...vocalChainPatch(undefined) }
+          : {}),
       },
     });
     await commitScore(next, "track.create", { trackId });
@@ -2375,6 +3284,36 @@ async function fitCommand(
   );
 }
 
+async function resampleCommand(
+  command: NonNullable<ReturnType<typeof parseResampleCommand>>,
+): Promise<Receipt> {
+  await materializeDraft();
+  // The source's own samples must be loaded for the render.
+  if (hasSamplerTracks(score)) await sampleProblems(score);
+  const result = await runResample({
+    projectRoot: process.cwd(),
+    score,
+    command,
+    ...(liveSampleBank ? { samples: liveSampleBank } : {}),
+  });
+  if (!result.ok) return fail(result.message);
+  const problems = (await sampleProblems(result.next)).filter(
+    (problem) =>
+      problem.trackId === result.trackId && problem.level === "error",
+  );
+  if (problems.length > 0) return fail(`resample · ${problems[0]!.message}`);
+  await commitScore(result.next, "resample", {
+    trackId: result.trackId,
+    src: result.src,
+    sha256: result.sha256,
+  });
+  await port.focus(result.trackId);
+  requestedTrack = result.trackId;
+  draftTrack = false;
+  await projectSync?.flushScore();
+  return ok(result.message);
+}
+
 async function sampleCommand(
   command: NonNullable<ReturnType<typeof parseSampleCommand>>,
 ): Promise<Receipt> {
@@ -2514,11 +3453,19 @@ async function packCommand(command: PackCommand): Promise<Receipt> {
         const store = packs();
         const a = await store.pruneCache(to(store.maxFileCacheBytes));
         const b = await library.pruneCache(to(library.maxCacheBytes));
-        freed = { files: a.removed + b.removed, bytes: a.freed + b.freed };
+        const c = await pruneAnalysisCache(
+          analysisDir(process.cwd()),
+          to(ANALYSIS_CACHE_BYTES),
+        );
+        freed = {
+          files: a.removed + b.removed + c.removed,
+          bytes: a.freed + b.freed + c.freed,
+        };
       }
       const lines = cacheLines({
         packs: await packs().cacheStatus(),
         assets: await library.cacheStatus(),
+        analysis: await analysisCacheStatus(process.cwd()),
         ...(freed ? { freed } : {}),
       });
       tui.openText("cache", lines);
@@ -2593,27 +3540,38 @@ async function packCommand(command: PackCommand): Promise<Receipt> {
   }
 }
 
+/**
+ * A command result as a receipt: a refusal is ✗, a change is ✓, and a read
+ * that changed nothing (a listing or a show) is •.
+ */
+function readOrDone(
+  result: Readonly<{ ok: boolean; message: string; next?: unknown }>,
+): Receipt {
+  if (!result.ok) return fail(result.message);
+  return result.next ? ok(result.message) : note(result.message);
+}
+
 async function patternCommand(command: PatternCommand): Promise<Receipt> {
   if (command.kind === "list") {
-    tui.openText("patterns", DRUM_PATTERNS.map(patternLine));
-    return ok(`patterns · ${DRUM_PATTERNS.length} · /pattern <name>`);
+    tui.openText("grooves", DRUM_PATTERNS.map(patternLine));
+    return note(`grooves · ${DRUM_PATTERNS.length} · groove <name>`);
   }
   if (command.kind === "browse") {
     tui.openPicker({
       id: "pattern",
-      title: "drum patterns",
+      title: "grooves",
       hint: HINTS.audition,
       audition: true,
       items: DRUM_PATTERNS.map((entry) => ({
         label: `${entry.label.padEnd(22)} ${entry.tempo.bpm} BPM · ${entry.tags.join(", ")}`,
-        value: `/pattern ${entry.name}`,
+        value: `/groove ${entry.name}`,
       })),
       filterable: true,
       index: 0,
     });
     patternPreview = undefined;
     previewPattern(DRUM_PATTERNS[0]?.name);
-    return ok("patterns · ↑/↓ preview · Enter applies on the focused track");
+    return note("grooves · ↑/↓ preview · Enter applies on the focused track");
   }
   await materializeDraft();
   const result = applyDrumPattern(
@@ -2674,7 +3632,7 @@ function openKitPicker(): Receipt {
   }));
   tui.openPicker({
     id: "kit",
-    title: "drum kits",
+    title: "kits",
     hint: HINTS.audition,
     audition: true,
     items,
@@ -2706,7 +3664,7 @@ async function kitCommand(command: KitCommand, bare = false): Promise<Receipt> {
       .map((entry) => `${entry.name} · synth · ${entry.detail}`);
     lines.push(...kitListLines(await packs().bankAliases(ALIASED_PACK)));
     tui.openText("kits", lines);
-    return ok("kits · /kit <name or nickname> on the focused drum track");
+    return note("kits · /kit <name or nickname> on the focused drum track");
   }
   await materializeDraft();
   const trackId = kitTarget(score, requestedTrack);
@@ -2817,12 +3775,10 @@ function adoptMeta(meta: typeof record.meta): void {
   record = { ...record, meta };
   if (meta.name !== announcedName) {
     announcedName = meta.name;
-    tui.activity.pushCard(
-      meta.nameSource === "auto"
-        ? `${meta.name} (auto-named) · rename with /rename <name>`
-        : `session · ${meta.name}`,
-      { tone: "info" },
-    );
+    // The auto-name joins the receipt that earned it, as a quiet suffix.
+    if (meta.nameSource === "auto")
+      tui.activity.attachNote(`named “${meta.name}” · /rename`);
+    else tui.activity.pushCard(`session · ${meta.name}`, { tone: "info" });
   }
 }
 
@@ -2986,11 +3942,13 @@ function menuContext(): MenuContext {
       committedChords: chordSettings,
     },
     trackId: requestedTrack,
+    sessionName: record.meta.name,
     playing: clock.playing,
     grid: session?.grid ?? DEFAULT_GRID,
     grids: GRIDS.map((grid) => grid.label),
     clickOn: session?.clickOn ?? false,
     countInBars: session?.countInBars ?? 1,
+    showMe: showMe.level,
     chords: stagedChordSettings() ?? session?.chords.settings ?? chordSettings,
     projectRoot: process.cwd(),
   };
@@ -3167,7 +4125,11 @@ function stagedChordSettings(): ChordSettings | undefined {
   if (chords.length === 0) return undefined;
   const settings = { ...chordSettings };
   for (const command of chords)
-    applyChordsCommand(settings, command.match(CHORDS_COMMAND)![1]!);
+    applyChordsCommand(
+      settings,
+      command.match(CHORDS_COMMAND)![1]!,
+      score.tempoBpm,
+    );
   return settings;
 }
 
@@ -3224,7 +4186,11 @@ async function applyStaged(
   const chords = command.trim().match(CHORDS_COMMAND);
   if (chords) {
     // Window state: checked on a copy; kept settings apply on Enter.
-    const result = applyChordsCommand({ ...chordSettings }, chords[1]!);
+    const result = applyChordsCommand(
+      { ...chordSettings },
+      chords[1]!,
+      base.tempoBpm,
+    );
     return { next: base, ok: result.ok, message: result.message };
   }
   await prefetchStaged(base, command);
@@ -3272,7 +4238,7 @@ async function startAuditionLoop(): Promise<void> {
   loop.focus(requestedTrack);
   // One sound at a time: the song stops while the loop plays.
   if (clock.playing) await setTransport("pause");
-  previewEngine().setLeadMs(PLAY_LEAD_MS);
+  previewEngine().setLeadMs(previewEngine().playLeadMs);
   loop.start();
 }
 
@@ -3417,7 +4383,11 @@ async function keepStaged(): Promise<Receipt> {
     CHORDS_COMMAND.test(command),
   );
   for (const command of chordCommands)
-    applyChordsCommand(chordSettings, command.match(CHORDS_COMMAND)![1]!);
+    applyChordsCommand(
+      chordSettings,
+      command.match(CHORDS_COMMAND)![1]!,
+      score.tempoBpm,
+    );
   const scoreCommands = taken.commands.filter(
     (command) => !CHORDS_COMMAND.test(command),
   );
@@ -3484,12 +4454,17 @@ function refreshMenu(): void {
   if (fader) {
     const fields = menu.faderFields(context);
     if (fields.length === 0) closeFader();
-    else
+    else {
+      const focusedField = fields[focusIndex(fader, fields)];
       tui.drawer = drawerView(fader, fields, menu.faderCommitted(context), {
         title: menu.crumbs,
         dirty: context.audition?.dirty ?? false,
         status: context.audition?.status,
+        atOnce:
+          focusedField !== undefined &&
+          !stageableNow(faderCommand(focusedField)),
       });
+    }
   }
   const view = menu.view(context);
   tui.openPicker({
@@ -3507,6 +4482,73 @@ function refreshMenu(): void {
 // ── the fader drawer ─────────────────────────────────────────────────
 
 /** Enter on a number row (or a bare `volume`, `fx filter`): the drawer. */
+/**
+ * `export song.wav [stems]`: render the song as `dawg render song.wav` would
+ * (the offline renderer, deterministic), then with `stems` one WAV per
+ * audible track beside it (`song-bass.wav`), each that track soloed.
+ */
+async function exportWav(path: string, stems: boolean): Promise<Receipt> {
+  const directory = await mkdtemp(join(tmpdir(), "dawg-export-"));
+  const errors: string[] = [];
+  const sink = { write: (text: string) => errors.push(text.trim()) };
+  const quiet = { write: () => undefined };
+  const render = async (song: TrackScore, target: string): Promise<boolean> => {
+    const file = join(directory, "song.track.json");
+    await writeFile(file, encodeLoop(song), "utf8");
+    const code = await runRenderCommand(
+      ["render", target, "--import", file],
+      process.cwd(),
+      quiet,
+      sink,
+    );
+    return code === 0;
+  };
+  tui.activity.setSpinner(`export ${path}`);
+  try {
+    if (!(await render(score, path)))
+      return fail(errors.at(-1) ?? `export failed · ${path}`);
+    if (!stems) return ok(`exported · ${path}`);
+    const written: string[] = [];
+    const base = path.replace(/\.wav$/i, "");
+    for (const track of score.tracks) {
+      if (!isTrackAudible(score, track.id)) continue;
+      let solo = score;
+      for (const other of score.tracks)
+        solo = applyScoreOperation(solo, {
+          type: "updateTrack",
+          trackId: other.id,
+          patch: { solo: other.id === track.id },
+        });
+      const target = `${base}-${track.id}.wav`;
+      if (!(await render(solo, target)))
+        return fail(errors.at(-1) ?? `export failed · ${target}`);
+      written.push(target);
+    }
+    return ok(stemsReceipt(path, written));
+  } finally {
+    tui.activity.setSpinner(undefined);
+    await rm(directory, { recursive: true, force: true });
+  }
+}
+
+/** `tempo`, `bars`, `meter`: open Project and name its fader, if it has one. */
+function songFader(context: MenuContext, command: string): string | undefined {
+  // Bare song scalars and the Project fader each opens.
+  const faders: Readonly<Record<string, string>> = {
+    tempo: "tempo",
+    bpm: "tempo",
+    bars: "loop length",
+    meter: "beats per bar",
+  };
+  const label = faders[command.replace(/^\//, "").toLowerCase()];
+  if (!label) return undefined;
+  menu.show(context, "project");
+  if (menu.faderFields(context).some((field) => field.label === label))
+    return label;
+  menu.close();
+  return undefined;
+}
+
 /**
  * Open the drawer on `label`. `standalone` drawers came from a command or a
  * click, not from inside the menu, so closing one closes the menu too.
@@ -3609,7 +4651,7 @@ function mouseInput(event: MouseEvent): string[] {
       return [];
     }
     if (fader) return [];
-    if (tui.ui.overlay) return [event.delta < 0 ? KEY_UP : KEY_DOWN];
+    if (tui.ui.overlay) return [event.delta < 0 ? ARROW_UP : ARROW_DOWN];
     return [];
   }
   // A drag keeps moving the fader it started on, even past the bar's ends.
@@ -3699,7 +4741,9 @@ function mouseInput(event: MouseEvent): string[] {
     }
     case "transport":
       if (tui.ui.overlay) return [];
-      void toggleTransport().finally(() => requestFrame());
+      void toggleTransport()
+        .catch((error: unknown) => transportFailed(error))
+        .finally(() => requestFrame());
       return [];
     case "tracks":
       if (tui.ui.overlay) return [];
@@ -3730,13 +4774,13 @@ function playSession(): PlaySession {
 }
 
 async function enterPlay(): Promise<Receipt> {
-  if (play?.on) return ok(`play · ${play.track} · esc leaves`);
+  if (play?.on) return ok(`play mode · ${play.track} · esc leaves`);
   await materializeDraft();
   const session = playSession();
   await session.enter();
   if (hasSamplerTracks(score)) void sampleProblems(score);
   return ok(
-    `play · ${session.track} · ${session.keyboard.range} · ? keys · esc leaves`,
+    `play mode · ${session.track} · ${session.layout.drums ? "kit" : session.keyboard.range} · ? keys · esc leaves`,
   );
 }
 
@@ -3766,9 +4810,7 @@ function playKey(value: string): boolean {
     else if (result.command === "transport") {
       if (!session.startWithCountIn())
         void toggleTransport().catch((error: unknown) =>
-          tui.activity.pushError(
-            `transport failed · ${error instanceof Error ? error.message : String(error)}`,
-          ),
+          transportFailed(error),
         );
     } else if (result.command === "menu") return false;
     return true;
@@ -3830,13 +4872,18 @@ function playHost() {
     async stopTransport(): Promise<void> {
       await setTransport("pause");
     },
+    ghost(pitch: number) {
+      tui.delight.ghost(pitch, Date.now());
+      requestFrame();
+    },
     card(text: string, tone: "info" | "success" | "warning" | "error") {
       if (tone === "error") tui.activity.pushError(text);
       else
         tui.activity.pushCard(text, {
           tone,
           trackId: requestedTrack,
-          resultRevision: tone === "success" ? record.revision : undefined,
+          resultRevision:
+            tone === "success" ? shownRevision(record) : undefined,
         });
     },
     newNoteId: () => randomUUID().slice(0, 12),
@@ -3883,6 +4930,9 @@ function timingChanged(previous: TrackScore, next: TrackScore): boolean {
 function syncHost(): SyncHost {
   return {
     project: process.cwd(),
+    // The files belong to one session at a time; another session's window
+    // stays detached instead of reprinting over them.
+    sessionId: () => record.sessionId,
     current: () => score,
     async commit(plan, summary) {
       const baseRevision = record.revision;
@@ -3908,7 +4958,8 @@ function syncHost(): SyncHost {
         tui.activity.pushCard(text, {
           tone,
           hint,
-          resultRevision: tone === "success" ? record.revision : undefined,
+          resultRevision:
+            tone === "success" ? shownRevision(record) : undefined,
         });
     },
     types(state) {
@@ -3939,10 +4990,17 @@ async function stepHistory(direction: "undo" | "redo"): Promise<Receipt> {
       },
       restored.toJSON(),
     );
+    // Compare with what was undone, which another window may have written.
+    const before = scoreFromJSON(latest.composition);
     score = restored;
     if (clock.playing) void audio.play(score);
     return ok(
-      `${direction === "undo" ? "undid" : "redid"} · rev ${target.revision}`,
+      historyReceipt(
+        direction,
+        before,
+        restored,
+        shownRevision(record, target.revision),
+      ),
     );
   } catch (error) {
     if (error instanceof SessionConflictError)
@@ -3953,7 +5011,36 @@ async function stepHistory(direction: "undo" | "redo"): Promise<Receipt> {
   }
 }
 
-/** The space-bar toggle: flip the transport, then record it for other windows. */
+/** Space, the menu and a header click all report a failed toggle the same way. */
+function transportFailed(error: unknown): void {
+  tui.activity.pushCard(
+    `transport failed · ${error instanceof Error ? error.message : String(error)}`,
+    { tone: "error" },
+  );
+}
+
+/**
+ * The revision dawg shows (header, receipts, undo): edits to the song.
+ * Play and pause are logged so other windows follow them, but they are not
+ * edits, so they never move the number: a revision shows as itself minus
+ * the transport events at or before it.
+ */
+function shownRevision(
+  value: typeof record,
+  revision = value.revision,
+): number {
+  let transports = 0;
+  for (const event of value.events)
+    if (event.revision <= revision && event.kind === "transport")
+      transports += 1;
+  return revision - transports;
+}
+
+/**
+ * The space-bar toggle: flip the transport, then record it for other
+ * windows. The log entry keeps windows in step; the header's revision
+ * (`shownRevision`) skips it, since play/pause is not an edit.
+ */
 async function toggleTransport(): Promise<void> {
   await setTransport("toggle");
   try {
@@ -4023,11 +5110,11 @@ async function runAgent(text: string): Promise<string | Receipt> {
   if (agentTurn) return warn("agent busy · Esc cancels");
   const selection = await currentProvider();
   if (selection.kind === "offline")
-    return fail(
-      `unrecognized · ${truncateForCard(text)} · ${selection.reason}`,
-    );
+    return fail(`${truncateForCard(text)} · ${NO_AGENT}`);
   const turn = { controller: new AbortController(), steering: [] as string[] };
   agentTurn = turn;
+  // The turn ends on one musical receipt of what it changed.
+  const before = score;
   reportAgentActivity(`${providerName} · thinking…`);
   // xcb admits a pending account on its first call, which takes longer.
   let admitting = selection.kind === "xcb" && selection.admissionPending;
@@ -4060,6 +5147,8 @@ async function runAgent(text: string): Promise<string | Receipt> {
           }
           return;
         }
+        if (event.type === "done")
+          tui.activity.setTurnReceipt(musicalReceipt(before, score));
         agentEventSink(event);
       },
     });
@@ -4091,7 +5180,7 @@ function currentProvider(): Promise<ProviderSelection> {
     provider = selectProvider().catch((): ProviderSelection => ({
       kind: "offline",
       choice: "auto",
-      reason: "provider unavailable; run `dawg login`",
+      reason: "provider unavailable; run `dawg model key`",
     }));
   }
   return provider.then((selection) => {
@@ -4103,9 +5192,9 @@ function currentProvider(): Promise<ProviderSelection> {
       !invalidNoticeShown
     ) {
       invalidNoticeShown = true;
-      tui.activity.pushCard(`sign-in stopped working · ${selection.reason}`, {
+      tui.activity.pushCard(`agent key stopped working · ${selection.reason}`, {
         tone: "warning",
-        hint: "/login",
+        hint: "/model key",
       });
     }
     providerStamp.offline = selection.kind === "offline";
@@ -4180,6 +5269,180 @@ function agentPreviewHost(): PreviewHost {
   };
 }
 
+// ── show-me ──────────────────────────────────────────────────────────
+
+/**
+ * Show-me (docs/show-me.md): with an API provider the agent writes prompt
+ * commands, streamed. The line being written is ghost text in the empty
+ * prompt bar at the model's own speed; each complete line runs through
+ * `submit()`, the path a typed Enter takes, at once. A parameter value
+ * glides there over ~150 ms while the loop plays (you hear it), notes and
+ * hits sound as they arrive (in time when the stream is ahead of the tempo,
+ * as step entry when it is behind), and the caption names the key or fader
+ * a person would use. Nothing waits for the turn to end.
+ */
+
+function showMeTyping(text: string): void {
+  showMe.ghost = text || undefined;
+  if (text && showMe.level === "on") showMe.caption = undefined;
+  requestFrame();
+}
+
+function showMeCaption(text: string | undefined): void {
+  if (showMe.level !== "on") return;
+  showMe.caption = text;
+  if (showMe.clear) clearTimeout(showMe.clear);
+  showMe.clear = undefined;
+  requestFrame();
+}
+
+/** End of a turn: the ghost goes, the caption becomes the do-it-yourself hint. */
+function showMeFinish(): void {
+  showMe.ghost = undefined;
+  showMe.notes.reset();
+  const hint = finishHint(showMe.commands);
+  showMe.commands = [];
+  if (hint && showMe.level === "on") {
+    showMeCaption(hint);
+    showMe.clear = setTimeout(() => {
+      showMe.caption = undefined;
+      showMe.clear = undefined;
+      requestFrame();
+    }, 8_000);
+  } else {
+    showMe.caption = undefined;
+    requestFrame();
+  }
+}
+
+/**
+ * Slide a fader to its new value the way the drawer does: each eased step is
+ * the field's own command, staged on a scratch score and played, so the loop
+ * moves through the values. Only while the loop plays (otherwise nothing is
+ * heard and the glide would only cost time); never longer than ~150 ms.
+ */
+async function glideFader(param: string, target: number): Promise<void> {
+  if (!clock.playing || !stdout.isTTY) return;
+  const scratch = new EditMenu();
+  const context = { ...menuContext(), score };
+  const label = scratch.showFader(context, param);
+  if (!label) return;
+  const field = scratch
+    .faderFields(context)
+    .find((candidate) => candidate.label === label);
+  scratch.close();
+  if (field?.kind !== "number") return;
+  const from = field.value ?? field.start ?? target;
+  const steps = glideValues(from, target).slice(0, -1);
+  for (const value of steps) {
+    const staged = await applyStaged(score, field.command(value));
+    if (staged.next && clock.playing) void audio.play(staged.next);
+    await Bun.sleep(GLIDE_STEP_MS);
+  }
+}
+
+/** Sound one streamed note on the audition voice (the loop is stopped). */
+function soundStreamedNote(
+  value: TrackScore,
+  trackId: string,
+  pitch: number,
+  startBeat: number,
+): void {
+  if (clock.playing) return; // The loop itself plays it.
+  const engine = liveEngine();
+  if (!engine?.canMonitor) return;
+  const tick = Math.round(startBeat * value.ticksPerBeat);
+  const note = value.notes.find(
+    (candidate) =>
+      candidate.trackId === trackId &&
+      candidate.pitch === pitch &&
+      candidate.startTick === tick,
+  );
+  if (!note) return;
+  try {
+    const json = value.toJSON() as unknown as Record<string, unknown>;
+    const single = scoreFromJSON({
+      ...json,
+      notes: [{ ...note, startTick: 0 }],
+    });
+    const pcm = renderAudition({
+      score: single,
+      trackId,
+      sampleRate: engine.sampleRate,
+      ...(liveSampleBank ? { samples: liveSampleBank } : {}),
+    });
+    if (!pcm) return;
+    void engine
+      .monitor(true)
+      .then(() => engine.noteOn(AUDITION_VOICE, pcm))
+      .catch(() => undefined);
+  } catch {
+    // A note that cannot render is still in the score.
+  }
+}
+
+/** The command host the show-me agent loop runs lines through. */
+function showMeCommandHost(): AgentHost["commands"] {
+  return {
+    isCommand: (line) =>
+      isAgentCommand(line, score) || isBrokenCommand(line, score),
+    async run(line): Promise<CommandOutcome> {
+      if (!agentPathsAllowed(line)) {
+        const revision = shownRevision(record);
+        return {
+          ok: false,
+          message: `${line} · the agent works only inside this folder`,
+          baseRevision: revision,
+          resultRevision: revision,
+        };
+      }
+      if (isBrokenCommand(line, score)) {
+        // A command that does not parse is a red receipt, never prose.
+        const base = baseline();
+        receipt(fail(brokenCommandReceipt(line)), base);
+        return {
+          ok: false,
+          message: brokenCommandReceipt(line),
+          baseRevision: base.revision,
+          resultRevision: base.revision,
+        };
+      }
+      const gesture = gestureFor(line, { score, trackId: requestedTrack });
+      showMeCaption(gesture.caption);
+      showMe.commands.push(line);
+      if (gesture.kind === "fader" && showMe.level === "on")
+        await glideFader(gesture.param, gesture.value);
+      const base = baseline();
+      tui.activity.pushNote(`agent › ${line}`, "request");
+      let result: string | Receipt;
+      try {
+        result = await submit(line);
+      } catch (error) {
+        result = fail(describeError(line, error));
+      }
+      receipt(result, base);
+      if (gesture.kind === "keys" && showMe.level === "on") {
+        const trackId = requestedTrack;
+        const after = score;
+        for (const note of gesture.notes) {
+          const { atMs } = showMe.notes.schedule(note.start, performance.now());
+          const delay = Math.max(0, atMs - performance.now());
+          setTimeout(
+            () => soundStreamedNote(after, trackId, note.pitch, note.start),
+            delay,
+          );
+        }
+      }
+      return {
+        ok: toneOf(result) !== "error",
+        message: typeof result === "string" ? result : result.text,
+        baseRevision: shownRevision(record, base.revision),
+        resultRevision: shownRevision(record),
+      };
+    },
+  };
+}
+
 function agentHost(
   turn: { steering: string[] },
   selection: ProviderSelection,
@@ -4254,6 +5517,9 @@ function agentHost(
       }
     },
     takeSteering: () => turn.steering.splice(0),
+    ...(showMe.level !== "off" && stdout.isTTY
+      ? { commands: showMeCommandHost() }
+      : {}),
     workspace: { root: process.cwd() },
     // A written project source is applied before the tool result returns,
     // so the model reads the outcome and any type errors in the same step.