@hraness/dawg 0.2.0 → 0.3.0

package/src/main.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { randomUUID } from "node:crypto";
-import { readFile, writeFile } from "node:fs/promises";
-import { resolve } from "node:path";
+import { readFile, stat, writeFile } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
 import { stdin, stdout } from "node:process";
 import {
   ensureSession,
@@ -30,8 +30,26 @@ import { AutoNamer, providerNameGenerator } from "./session/naming.ts";
 import { normalizeSessionName } from "./session/meta.ts";
 import { parsePrompt } from "./agent/ops.ts";
 import { applyMusicCommand, parseMusicCommand } from "./commands/music.ts";
+import { applyEditCommand, parseEditCommand } from "./commands/edit.ts";
+import { helpLines, helpText, usageHint } from "./commands/help.ts";
 import { historyTarget, REDO_KIND, UNDO_KIND } from "./commands/history.ts";
-import { drumSnapshotFields } from "../tui/drums.ts";
+import {
+  SamplePlacementError,
+  addSampleVoice,
+  freeVoiceName,
+  listSampleVoices,
+  parseSampleCommand,
+  placeSampleFile,
+  samplerTarget,
+  voiceNameFrom,
+} from "./commands/sample.ts";
+import {
+  SampleLibrary,
+  hasSamplerTracks,
+  type SampleBank,
+  type SampleProblem,
+} from "./audio/samples.ts";
+import { drumSnapshotFields, samplerSnapshotFields } from "../tui/drums.ts";
 import { highwayLayers } from "../tui/layers.ts";
 import { drumVoicePitch, isDrumInstrument } from "../core/drums.ts";
 import {
@@ -40,17 +58,41 @@ import {
   type AgentEvent,
   type AgentHost,
 } from "./agent/agent.ts";
-import { type GatewayModel } from "./agent/gateway.ts";
 import {
+  isApiSelection,
   providerFingerprint,
   providerLabel,
   runProviderTurn,
   selectProvider,
   type ProviderSelection,
 } from "./agent/provider.ts";
-import { runAuthCommand } from "./auth/cli.ts";
-import { tuiAuthCommand, xcbPickerItems } from "./auth/tui.ts";
+import {
+  MODEL_CATALOG,
+  priceForModel,
+  resolveModelChoice,
+} from "./agent/models.ts";
+import {
+  SpendMeter,
+  spendLine as formatSpendLine,
+  webHostFor,
+} from "./agent/usage.ts";
+import { configDir } from "./auth/credentials.ts";
+import { runAuthCommand, runFirstRunLogin, runTuiLogin } from "./auth/cli.ts";
+import {
+  modelPickerItems,
+  tuiAuthCommand,
+  tuiLoginArgs,
+  tuiSetModel,
+} from "./auth/tui.ts";
 import { TransportClock } from "./audio/clock.ts";
+import { AudioEngine } from "./audio/engine.ts";
+import {
+  DEFAULT_GRID,
+  GRIDS,
+  PlaySession,
+  type LiveEngine,
+} from "./tui/play-session.ts";
+import { EditMenu, MENU_SECTIONS, type MenuContext } from "./tui/menu.ts";
 import {
   addNote,
   applyScoreOperation,
@@ -69,12 +111,46 @@ import {
   TuiApp,
   type AppView,
   type SyncState,
+  type TypesIndicator,
 } from "../tui/app.ts";
-import { receiptTone } from "../tui/activity.ts";
+import { fail, 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 { typecheckProject } from "./project/typecheck.ts";
+import {
+  startProjectSync,
+  type ProjectSync,
+  type SyncHost,
+} from "./project/sync.ts";
 
 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",
+];
 const HELP_TEXT = `dawg · local-first terminal music workstation
 
 Usage:
@@ -82,6 +158,10 @@ Usage:
   dawg --import <file> --export <file>
   dawg sessions
   dawg render <out.wav> [--session <name|id>] [--import <file>]
+  dawg init [dir]      project files: song.ts, tracks/<slug>/track.ts, .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 --version
 
 Usage flags:
   --reduce-motion   static hit/sustain states (also DAWG_REDUCE_MOTION=1)
@@ -92,24 +172,17 @@ Prompt:
   Ctrl-Z undo · Ctrl-Y redo · Ctrl-O transcript · Esc cancel/close · Ctrl-C exit
   Space on an empty prompt toggles playback
 
-Commands:
-  play, pause, tempo <bpm>, instrument <name>, volume <0..1>, pan <-1..1>
-  automate <lane> at <beat> <value>, clear automation, mute, clear
-    lanes: volume pan filter resonance delay-feedback delay-mix
-  undo, redo, solo, unsolo, filter <hz> [res], delay <beats> [fb] [mix]
-  reverb <mix> [size], reverb off
-  instrument kit, hit <voice> at <beat>, pattern <voice> <beats...>|every <step>
-  track <name>, bars <count>, extend <count> bars
-  /tracks, /status, /export <file>, /import <file>, /model opus-5.5|sol-6.1
-  /sessions, /resume [n|name|id], /rename <name>|--auto, /fork [name]
-  /log, /view focus|all, /theme default|high-contrast|mono, /motion on|off
-  /login [--xcb], /logout, /auth [--check]
+Commands (bare music words; app commands take a slash):
+${helpText()}
 
-Auth:
-  dawg login [--gateway|--key|--xcb] [--budget <dollars>]
-  dawg logout · dawg auth status [--check]
+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
+  dawg logout [provider] · dawg auth status [--check]
 Unrecognized requests go to the agent once a provider is configured
-(DAWG_PROVIDER=gateway|xcb|auto; DAWG_AI=0 disables the agent).`;
+(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");
@@ -118,16 +191,46 @@ let requestedTrack = explicitTrack ?? "main";
 const initialInstrument = isDrumInstrument(requestedTrack) ? "kit" : "sine";
 const importPath = optionValue("--import");
 const exportPath = optionValue("--export");
-if (["login", "logout", "auth"].includes(process.argv[2] ?? ""))
+if (["login", "logout", "auth", "model"].includes(process.argv[2] ?? ""))
   process.exit(await runAuthCommand(process.argv.slice(2)));
-if (args.has("--help") || args.has("-h")) {
-  stdout.write(`${HELP_TEXT}\n`);
-  process.exit(0);
+{
+  // An unknown DAWG_MODEL is an error, never a silent fallback.
+  const fromEnv = process.env.DAWG_MODEL?.trim();
+  if (fromEnv && !resolveModelChoice("gateway", 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`,
+    );
+    process.exit(2);
+  }
 }
 if (process.argv[2] === "sessions") {
-  await printSessions(process.cwd(), stdout);
+  if (args.has("--help") || args.has("-h"))
+    stdout.write(
+      "usage: dawg sessions · lists this workspace's sessions, newest first (* marks the current one)\n",
+    );
+  else await printSessions(process.cwd(), stdout);
   process.exit(0);
 }
+if (process.argv[2] === "init" || process.argv[2] === "check") {
+  const command =
+    process.argv[2] === "init"
+      ? (await import("./project/init.ts")).runInitCommand
+      : (await import("./project/check.ts")).runCheckCommand;
+  process.exit(
+    await command(process.argv.slice(2), process.cwd(), stdout, process.stderr),
+  );
+}
+if (process.argv[2] === "media") {
+  const { runMediaCommand } = await import("./media/cli.ts");
+  process.exit(
+    await runMediaCommand(
+      process.argv.slice(2),
+      process.cwd(),
+      stdout,
+      process.stderr,
+    ),
+  );
+}
 if (process.argv[2] === "render") {
   const { runRenderCommand } = await import("./render.ts");
   process.exit(
@@ -139,8 +242,28 @@ if (process.argv[2] === "render") {
     ),
   );
 }
+if (args.has("--version") || args.has("-v")) {
+  stdout.write(`dawg ${await packageVersion()}\n`);
+  process.exit(0);
+}
+if (args.has("--help") || args.has("-h")) {
+  stdout.write(`${HELP_TEXT}\n`);
+  process.exit(0);
+}
+// 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`);
+    process.exit(2);
+  }
+}
 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();
 
 const initial = createScore({
   tracks: [
@@ -162,6 +285,11 @@ const selectedSession = args.has("--new")
         },
       );
 if (selectedSession !== undefined) sessionOptions.sessionId = selectedSession;
+/** True when this launch creates `.dawg/`; the strip says so once. */
+const freshWorkspace = !(await stat(join(process.cwd(), ".dawg")).then(
+  () => true,
+  () => false,
+));
 const session = await ensureSession(initial.toJSON(), sessionOptions);
 // dawgd when connected, the file-lock path otherwise (see src/session/port.ts).
 let port = await openSessionPort<ReturnType<TrackScore["toJSON"]>>({
@@ -181,7 +309,7 @@ if (importPath) {
     record,
     {
       kind: "score.import",
-      payload: { path: importPath, before: record.composition },
+      payload: { path: importPath },
     },
     score.toJSON(),
   );
@@ -204,8 +332,9 @@ if (!draftTrack) await ensureFocusedTrack();
 
 const clock = new TransportClock(score.tempoBpm);
 let audio = port.player;
-let selectedModel: GatewayModel =
-  process.env.DAWG_MODEL === "opus-5.5" ? "opus-5.5" : "sol-6.1";
+/** Session and today's spend, from the usage each response reports. */
+const meter = new SpendMeter(configDir());
+void meter.load().catch(() => undefined);
 const prompt = new PromptModel({ width: 72, maxVisualRows: 8 });
 const tui = new TuiApp({
   io: {
@@ -220,10 +349,21 @@ const tui = new TuiApp({
 });
 let syncState: SyncState = port.sync;
 let windowCount = 1;
+/** Project file sync when `dawg.json` is in the working directory. */
+let projectSync: ProjectSync | undefined;
+let typesIndicator: TypesIndicator | undefined;
 let announcedName = record.meta.name;
 let namer = makeNamer();
 /** Re-subscribes the TUI after /fork or /resume replaces `port`. */
 let rebindPort: () => void = () => undefined;
+/** Play mode's controller; kept across entries so settings persist. */
+let play: PlaySession | undefined;
+/** The hand-editing menu (`/menu`, Ctrl-K), drawn as the picker overlay. */
+const menu = new EditMenu();
+/** Daemon windows play no loop; play mode monitors through its own engine. */
+let monitorEngine: AudioEngine | undefined;
+/** The decoded sampler voices, for play mode's live voices. */
+let liveSampleBank: SampleBank | undefined;
 /** The in-flight agent turn: Esc aborts it, Enter steers it. */
 let agentTurn: { controller: AbortController; steering: string[] } | undefined;
 let reportAgentActivity: (text: string) => void = () => undefined;
@@ -233,6 +373,35 @@ let agentEventSink: (event: AgentEvent) => void = () => undefined;
 let provider: Promise<ProviderSelection> | undefined;
 let providerStamp = { fingerprint: "", at: 0, offline: false };
 let providerName = "";
+/** Undo/redo key hints shown so far; only the first few receipts carry one. */
+let undoHintsShown = 0;
+const MAX_UNDO_HINTS = 3;
+let invalidNoticeShown = false;
+/** True while /login has handed the terminal to a shell flow. */
+let screenSuspended = false;
+/** Redraw from outside the input loop (usage arrives asynchronously). */
+let tickUi: () => void = () => undefined;
+/** Suspend the TUI around an interactive shell flow (set by runInteractive). */
+let handoff: <T>(flow: () => Promise<T>) => Promise<T> = (flow) => flow();
+
+/** `$0.12 session · $0.48 today · opus-5.5 · gateway`, sized to the width. */
+function spendLine(): string {
+  const width = stdout.columns ?? 80;
+  if (!providerName || providerName === "offline")
+    return width >= 40 ? "no model · dawg login" : "";
+  const [model, provider] = providerName.split(" · ");
+  return formatSpendLine(
+    {
+      kind: providerSnapshot?.kind === "xcb" ? "subscription" : "api",
+      ...(model ? { model } : {}),
+      ...(provider ? { provider } : {}),
+      sessionUsd: meter.sessionUsd,
+      todayUsd: meter.todayUsd,
+    },
+    Math.max(0, width - 8),
+  );
+}
+let providerSnapshot: ProviderSelection | undefined;
 if (demo) {
   if (score.notes.length === 0) score = seedDemo(score, requestedTrack);
   if (exportPath)
@@ -254,6 +423,32 @@ 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;
@@ -356,6 +551,10 @@ function snapshot(
       value.tracks.find((track) => track.id === requestedTrack)?.instrument,
       notes,
     ),
+    ...samplerSnapshotFields(
+      value.tracks.find((track) => track.id === requestedTrack),
+      notes,
+    ),
     layers:
       tui.highwayView === "all"
         ? highwayLayers(
@@ -390,33 +589,65 @@ function appView(value: TrackScore, beat: number): AppView {
   return {
     score: snapshot(value, beat),
     beat,
-    // `opus-5.5 · gateway`, `claude/sonnet · xcb`; hidden when offline.
+    // `opus-5.5 · gateway`, `sonnet · claude`; hidden when offline.
     model:
       providerName && providerName !== "offline" ? providerName : undefined,
+    spend: spendLine(),
+    agentOffline: providerName === "offline" || process.env.DAWG_AI === "0",
     sync: syncState,
     sessionName: record.meta.name,
     windows: windowCount,
+    types: typesIndicator,
+    play: play?.on ? play.header() : undefined,
   };
 }
 
-/** Show a command receipt in the activity strip with a tone and undo hint. */
-function receipt(message: string, baseRevision?: number): void {
-  const tone = receiptTone(message);
-  const changed =
-    baseRevision !== undefined && record.revision !== baseRevision;
-  if (tone === "error") tui.activity.pushError(message);
-  else
-    tui.activity.pushCard(message, {
-      tone,
-      baseRevision: changed ? baseRevision : undefined,
-      resultRevision: changed ? record.revision : undefined,
-      hint: changed
-        ? message.startsWith("undid")
-          ? "^y redo"
-          : "^z undo"
-        : undefined,
-      trackId: requestedTrack,
-    });
+/** What the strip compares a receipt against: the revision and score before. */
+type Baseline = { revision: number; score: TrackScore };
+function baseline(): Baseline {
+  return { revision: record.revision, score };
+}
+
+/**
+ * Show a command receipt in the activity strip. The tone comes from the
+ * receipt itself (strings fall back to a legacy regex); the revision label
+ * appears when the revision moved, and the undo hint only when the score
+ * changed in this session (not for forks, resumes or transport).
+ */
+function receipt(result: string | Receipt, base?: Baseline): void {
+  const message = typeof result === "string" ? result : result.text;
+  const tone = toneOf(result);
+  const changed = base !== undefined && record.revision !== base.revision;
+  const scoreChanged =
+    changed && record.sessionId !== undefined && score !== base.score;
+  if (tone === "error") {
+    tui.activity.pushError(message);
+    return;
+  }
+  const hint =
+    scoreChanged && undoHintsShown < MAX_UNDO_HINTS
+      ? message.startsWith("undid")
+        ? "^y redo"
+        : "^z undo"
+      : undefined;
+  if (hint) undoHintsShown += 1;
+  tui.activity.pushCard(message, {
+    tone,
+    baseRevision: changed ? base.revision : undefined,
+    resultRevision: changed ? record.revision : undefined,
+    hint,
+    trackId: requestedTrack,
+  });
+}
+
+/** One shape for thrown errors: `<what> · <why> · <next step>`. */
+function describeError(command: string, error: unknown): string {
+  const detail = error as { code?: unknown; path?: unknown } | undefined;
+  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)}`;
+  const verb = command.trim().split(/\s+/)[0]?.replace(/^\//, "") || "command";
+  return `${verb} failed · ${message}`;
 }
 
 function truncateForCard(value: string): string {
@@ -439,7 +670,7 @@ async function runInteractive(): Promise<void> {
       return;
     }
     tui.activity.pushRequest(text);
-    const base = record.revision;
+    const base = baseline();
     const baseSession = record.sessionId;
     try {
       const message = await submit(text);
@@ -450,12 +681,10 @@ async function runInteractive(): Promise<void> {
         namer.noteTurn({
           score,
           prompt: text,
-          accepted: record.revision !== base,
+          accepted: record.revision !== base.revision,
         });
     } catch (error) {
-      tui.activity.pushError(
-        `error · ${error instanceof Error ? error.message : String(error)}`,
-      );
+      tui.activity.pushError(describeError(text, error));
     } finally {
       agentReported = false;
     }
@@ -477,17 +706,22 @@ async function runInteractive(): Promise<void> {
     }
   };
   const tick = (force = false) => {
+    if (screenSuspended) return;
+    play?.tick();
+    // Values in the menu follow the score as edits land.
+    if (menu.open) refreshMenu();
     tui.render(appView(score, clock.beatAt()), { force });
   };
   reportAgentActivity = () => {
     tui.activity.applyAgentEvent({ type: "start", model: providerName });
   };
   agentEventSink = (event) => {
+    if (event.type === "usage") return;
     tui.activity.applyAgentEvent(event);
     if (event.type === "done" || event.type === "error") agentReported = true;
   };
   // ~30 fps cap; the differential writer only emits changed rows.
-  const timer = setInterval(tick, tui.frameIntervalMs);
+  let timer = setInterval(tick, tui.frameIntervalMs);
   const onResize = () => {
     tui.invalidate();
     tick(true);
@@ -533,6 +767,7 @@ async function runInteractive(): Promise<void> {
           else if (payload.action === "pause") await setTransport("pause");
           else if (payload.action === "toggle") await setTransport("toggle");
         }
+        projectSync?.scoreChanged(score);
         tui.activity.pushCard("synced from another window", {
           tone: "info",
           baseRevision: previousRevision,
@@ -581,6 +816,10 @@ async function runInteractive(): Promise<void> {
     unsubscribe = port.subscribe(onUpdate);
     refreshPresence();
   };
+  if (freshWorkspace)
+    tui.activity.pushCard("created .dawg/ · add it to .gitignore", {
+      tone: "info",
+    });
   if (attachNotice)
     tui.activity.pushCard(attachNotice, {
       tone: "info",
@@ -589,45 +828,124 @@ async function runInteractive(): Promise<void> {
     });
   if (port.status !== "file session")
     tui.activity.pushCard(port.status, { tone: "info" });
+  if (await isProject(process.cwd()))
+    projectSync = startProjectSync(syncHost());
   void currentProvider().then(() => tick(true));
+  tickUi = () => tick(true);
+  reportSampleProblems(score);
+  // Input arrives through a detachable listener (not `for await`), so /login
+  // can hand the terminal to an interactive shell flow and take it back.
+  const inbox: string[] = [];
+  let wake: (() => void) | undefined;
+  const onData = (chunk: Buffer | string) => {
+    inbox.push(String(chunk));
+    wake?.();
+  };
+  const onEnd = () => {
+    inbox.push("\u0000eof");
+    wake?.();
+  };
+  stdin.on("data", onData);
+  stdin.on("end", onEnd);
+  async function* chunks(): AsyncGenerator<string> {
+    for (;;) {
+      while (inbox.length === 0)
+        await new Promise<void>((resolve) => (wake = resolve));
+      wake = undefined;
+      const next = inbox.shift()!;
+      if (next === "\u0000eof") return;
+      yield next;
+    }
+  }
+  handoff = async <T>(flow: () => Promise<T>): Promise<T> => {
+    if (screenSuspended) return flow();
+    screenSuspended = true;
+    clearInterval(timer);
+    stdin.off("data", onData);
+    stdin.pause();
+    stdin.setRawMode?.(false);
+    // Leave the alternate screen; restore the cursor and plain paste.
+    stdout.write(`${ESC}0m${ESC}?2004l${ESC}?25h${ESC}?1049l`);
+    try {
+      return await flow();
+    } finally {
+      stdout.write(`${ESC}?1049h${ESC}?25l${ESC}?2004h${ESC}2J`);
+      stdin.setRawMode?.(true);
+      stdin.on("data", onData);
+      stdin.resume();
+      screenSuspended = false;
+      timer = setInterval(tick, tui.frameIntervalMs);
+      tui.invalidate();
+      tick(true);
+    }
+  };
   tick(true);
   try {
     let exiting = false;
-    for await (const chunk of stdin) {
-      const text = String(chunk);
+    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() : []),
       ];
       for (const value of values) {
+        // The edit menu owns every key while it is up (Esc backs out).
+        if (typeof value === "string" && menu.open) {
+          if (tui.ui.overlay !== "picker" || tui.ui.picker?.id !== "menu")
+            menu.close();
+          else {
+            const result = menu.key(value, menuContext());
+            if (result.type === "close") tui.closePicker();
+            else if (result.type === "run") {
+              queuedPrompts.unshift(result.command);
+              void drainQueue();
+            }
+            if (result.type !== "pass") {
+              refreshMenu();
+              tick(true);
+              continue;
+            }
+          }
+        }
+        // Ctrl-K opens the menu on an empty prompt (in play mode too); with
+        // text it keeps its kill-to-end-of-line meaning.
+        if (
+          value === "\u000b" &&
+          prompt.value.length === 0 &&
+          tui.ui.overlay === undefined
+        ) {
+          openMenu();
+          tick(true);
+          continue;
+        }
+        if (typeof value === "string" && play?.on && playKey(value)) {
+          tick(true);
+          continue;
+        }
+        // Ctrl-P enters play mode. A bare `p` would steal the first letter of
+        // `pan`, `pattern`, `play` and every prose request starting with p.
+        if (value === "\u0010" && tui.ui.overlay === undefined) {
+          void enterPlay()
+            .then((outcome) => receipt(outcome))
+            .finally(() => tick(true));
+          continue;
+        }
         // The prompt is always focused, so ordinary `q` must remain typeable in
         // requests (for example, "quiet hi-hat"). Ctrl-C is the unambiguous
         // shell exit key; Ctrl-Q is reserved for prompt mode switching.
         // Keep the empty-prompt space shortcut for transport, while allowing
         // ordinary spaces once a request is being composed.
         if (value === " " && prompt.value.length === 0) {
-          await setTransport("toggle");
-          try {
-            record = await port.append(
-              record,
-              {
-                kind: "transport",
-                payload: {
-                  action: "toggle",
-                  playing: clock.playing,
-                  beat: clock.beatAt(),
-                },
-              },
-              score.toJSON(),
-            );
-          } catch (error) {
-            if (error instanceof SessionConflictError)
-              tui.activity.pushCard("transport changed in another window", {
-                tone: "warning",
-              });
-            else throw error;
-          }
+          // 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" },
+              );
+            })
+            .finally(() => tick(true));
         } else {
           const input = tui.input(value);
           const action = input.type === "action" ? input.action : undefined;
@@ -637,8 +955,17 @@ async function runInteractive(): Promise<void> {
               (input.command === "undo" || input.command === "redo") &&
               !agentTurn
             ) {
-              const base = record.revision;
-              receipt(await stepHistory(input.command), base);
+              const base = baseline();
+              const command = input.command;
+              void stepHistory(command)
+                .then((outcome) => receipt(outcome, base))
+                .catch((error: unknown) => {
+                  tui.activity.pushCard(
+                    `${command} failed · ${error instanceof Error ? error.message : String(error)}`,
+                    { tone: "error" },
+                  );
+                })
+                .finally(() => tick(true));
             }
           } else if (input.type === "pick") {
             // Picker choices run as the command they stand for.
@@ -678,11 +1005,16 @@ async function runInteractive(): Promise<void> {
       if (exiting) break;
     }
   } finally {
+    stdin.off("data", onData);
+    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);
@@ -691,23 +1023,84 @@ async function runInteractive(): Promise<void> {
   }
 }
 
-async function submit(prompt: string): Promise<string> {
+async function submit(prompt: string): Promise<string | Receipt> {
   const command = prompt.trim();
-  if (/^\/?help$|^\/?\?$/.test(command.toLowerCase()))
-    return "commands · play pause tempo <bpm> instrument <name> volume <0..1> pan <-1..1> automate volume|pan|filter|resonance|delay-feedback|delay-mix at <beat> <value> clear automation track <name> bars <count> extend <count> bars mute solo unsolo filter <hz> [res] delay <beats> [fb] [mix] reverb <mix> [size] hit <voice> at <beat> pattern <voice> <beats...>|every <step> clear <voice> clear undo redo export <file> import <file>";
-  if (/^\/?tracks?$/i.test(command))
-    return score.tracks
-      .map(
-        (track) =>
-          `${track.id}${track.muted ? " [muted]" : ""}${track.solo ? " [solo]" : ""} · ${track.instrument}`,
-      )
-      .join("  ");
+  if (/^\/?help$|^\/?\?$/.test(command.toLowerCase())) {
+    tui.openText("help", helpLines(Math.max(40, (stdout.columns ?? 80) - 8)));
+    return ok("help · esc closes");
+  }
+  if (/^\/?tracks$/i.test(command)) {
+    const problems = await sampleProblems(score);
+    const lines = score.tracks.map((track) => {
+      const voices = track.sampler
+        ? Object.keys(track.sampler.voices).length
+        : 0;
+      const missing = problems.filter(
+        (problem) => problem.trackId === track.id && problem.level === "error",
+      ).length;
+      const samples = track.sampler
+        ? ` · ${voices} sample${voices === 1 ? "" : "s"}${missing ? ` · ${missing} missing` : ""}`
+        : "";
+      return `${track.id === requestedTrack ? "*" : " "} ${track.id} · ${track.instrument}${samples}${track.muted ? " · muted" : ""}${track.solo ? " · solo" : ""}`;
+    });
+    tui.openText("tracks · * focused", lines);
+    return ok(
+      `${lines.length} track${lines.length === 1 ? "" : "s"} · esc closes`,
+    );
+  }
+  const playCommand = command.match(/^\/play(?:\s+(on|off))?$/i);
+  if (playCommand) {
+    const wanted = playCommand[1]?.toLowerCase();
+    if (wanted === "off" || (wanted === undefined && play?.on))
+      return exitPlay();
+    return enterPlay();
+  }
+  const clickCommand = command.match(/^\/click(?:\s+(.+))?$/i);
+  if (clickCommand) {
+    const message = playSession().clickCommand(clickCommand[1] ?? "");
+    return message.startsWith("usage") || message.startsWith("click volume")
+      ? fail(message)
+      : ok(message);
+  }
+  const countIn = command.match(/^\/count-?in\s+([0-2])$/i);
+  if (countIn) return ok(playSession().setCountIn(Number(countIn[1])));
+  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("|")}]`);
+    openMenu(section);
+    return ok("menu · esc closes");
+  }
+  const gridCommand = command.match(/^\/grid\s+(\S+)$/i);
+  if (gridCommand) {
+    const message = playSession().setGrid(gridCommand[1]!);
+    return message
+      ? ok(message)
+      : fail("usage: /grid 1/4|1/8|1/8T|1/16|1/16T|1/32");
+  }
   if (/^\/status$/i.test(command))
-    return `status · ${record.meta.name} · rev ${record.revision} · ${compositionDigest(record.composition)} · ${port.mode}`;
+    return ok(
+      `status · ${record.meta.name} · rev ${record.revision} · ${compositionDigest(record.composition)} · ${port.mode === "daemon" ? "shared via dawgd" : "saved locally · no daemon"}`,
+    );
   if (/^\/?undo$/i.test(command)) return stepHistory("undo");
   if (/^\/?redo$/i.test(command)) return stepHistory("redo");
+  const trackCommand = command.match(
+    /^\/?(?:add\s+)?track\s+([a-z0-9._-]{1,64})$/i,
+  );
+  if (trackCommand) return focusTrack(trackCommand[1]!.toLowerCase());
+  const sample = parseSampleCommand(command);
+  if (sample) return sampleCommand(sample);
   const sessionReply = await sessionCommand(command);
   if (sessionReply !== undefined) return sessionReply;
+  const edit = parseEditCommand(command);
+  if (edit) {
+    await materializeDraft();
+    const result = applyEditCommand(score, requestedTrack, edit);
+    if (result.next && result.kind)
+      await commitScore(result.next, result.kind, result.payload);
+    return result.ok ? ok(result.message) : fail(result.message);
+  }
   const music = parseMusicCommand(command);
   if (music) {
     await materializeDraft();
@@ -716,7 +1109,7 @@ async function submit(prompt: string): Promise<string> {
     );
     if (result.next && result.kind)
       await commitScore(result.next, result.kind, result.payload);
-    return result.message;
+    return result.ok ? ok(result.message) : fail(result.message);
   }
   const exportCommand = command.match(/^\/?export\s+([^\s]+)$/i);
   if (exportCommand) {
@@ -731,33 +1124,56 @@ async function submit(prompt: string): Promise<string> {
     await commitScore(imported, "score.import", { path: importCommand[1] });
     return `imported · ${importCommand[1]}`;
   }
-  const modelCommand = prompt.trim().match(/^\/model\s+(opus-5\.5|sol-6\.1)$/i);
-  if (modelCommand) {
-    selectedModel = modelCommand[1]!.toLowerCase() as GatewayModel;
-    if (provider) void currentProvider();
-    return `model · ${selectedModel}`;
-  }
-  if (/^\/login\s+--xcb$/i.test(prompt.trim())) {
-    tui.activity.setSpinner("xcb accounts");
-    try {
-      const items = await xcbPickerItems();
-      if (items && items.length > 1) {
+  const modelMatch = prompt.trim().match(/^\/model(?:\s+(\S+))?\s*$/i);
+  if (modelMatch) {
+    const selection = await currentProvider();
+    if (!modelMatch[1]) {
+      if (selection.kind === "offline")
+        return `model · none · ${selection.reason}`;
+      tui.activity.setSpinner("models");
+      try {
+        const items = await modelPickerItems(selection);
+        if (items.length === 0)
+          return `model · ${providerName} · no other models listed`;
         tui.openPicker({
-          id: "xcb",
-          title: "xcb account · model · ↑/↓ Enter · Esc",
+          id: "model",
+          title: `model · ${providerName}`,
           items,
+          filterable: true,
+          index: Math.max(
+            0,
+            items.findIndex((item) => item.current),
+          ),
         });
-        return `xcb · ${items.length} choices`;
+        return `model · ${providerName} · pick one (or /model <alias>)`;
+      } finally {
+        tui.activity.setSpinner(undefined);
       }
-    } finally {
-      tui.activity.setSpinner(undefined);
     }
-    // Zero or one choice: the plain flow saves it or prints guidance.
+    const receiptText = await tuiSetModel(modelMatch[1]);
+    provider = undefined;
+    await currentProvider();
+    return receiptText;
+  }
+  if (/^\/login\b/i.test(prompt.trim())) {
+    const parsed = tuiLoginArgs(prompt.trim());
+    if (typeof parsed === "string") return `login · ${parsed}`;
+    await handoff(() =>
+      runTuiLogin(
+        parsed.target === "auto" ? "pick" : parsed.target,
+        parsed.options,
+      ),
+    );
+    provider = undefined;
+    await currentProvider();
+    return providerName === "offline"
+      ? "login · not signed in · direct commands still work"
+      : `signed in · ${providerName}`;
   }
-  if (/^\/(login|logout|auth)\b/i.test(prompt.trim())) {
+  if (/^\/(logout|auth)\b/i.test(prompt.trim())) {
     tui.activity.setSpinner(prompt.trim().split(/\s+/)[0]!.slice(1));
     try {
-      const lines = await tuiAuthCommand(prompt.trim(), selectedModel);
+      const lines = await tuiAuthCommand(prompt.trim());
       provider = undefined;
       await currentProvider();
       for (const line of lines.slice(0, -1))
@@ -767,9 +1183,23 @@ async function submit(prompt: string): Promise<string> {
       tui.activity.setSpinner(undefined);
     }
   }
+  // `/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.
+  if (command.startsWith("/") && !/^\/model\b/i.test(command)) {
+    const hint = usageHint(command);
+    return fail(
+      hint
+        ? `${truncateForCard(command)} · ${hint}`
+        : `unknown command ${command.split(/\s+/)[0]} · /help`,
+    );
+  }
   const parsed = parsePrompt(prompt);
   if (!parsed) {
-    if (process.env.DAWG_AI === "0") return `unrecognized request: ${prompt}`;
+    // A known verb with bad arguments gets usage, not a model call.
+    const hint = usageHint(command);
+    if (hint) return fail(`${truncateForCard(command)} · ${hint}`);
+    if (process.env.DAWG_AI === "0")
+      return fail(`unrecognized · ${truncateForCard(command)} · /help`);
     await materializeDraft();
     return runAgent(prompt);
   }
@@ -791,7 +1221,7 @@ async function submit(prompt: string): Promise<string> {
       );
     } catch (error) {
       if (error instanceof SessionConflictError)
-        return "transport changed in another window";
+        return warn("transport changed in another window");
       throw error;
     }
     return parsed.action;
@@ -802,20 +1232,7 @@ async function submit(prompt: string): Promise<string> {
     clock.setTempo?.(next.tempoBpm);
     return `tempo · ${next.tempoBpm} BPM`;
   }
-  if (parsed.type === "add-track") {
-    if (score.tracks.some((track) => track.id === parsed.trackId))
-      return `track exists · ${parsed.trackId}`;
-    const next = applyScoreOperation(score, {
-      type: "addTrack",
-      track: {
-        id: parsed.trackId,
-        name: parsed.trackId,
-        instrument: isDrumInstrument(parsed.trackId) ? "kit" : "sine",
-      },
-    });
-    await commitScore(next, "track.create", { trackId: parsed.trackId });
-    return `track created · ${parsed.trackId}`;
-  }
+  if (parsed.type === "add-track") return focusTrack(parsed.trackId);
   if (parsed.type === "set-bars" || parsed.type === "extend-bars") {
     const bars =
       parsed.type === "set-bars"
@@ -940,7 +1357,7 @@ async function submit(prompt: string): Promise<string> {
         latest,
         {
           kind: "score.operation",
-          payload: { operation, before: latest.composition },
+          payload: { operation },
         },
         next.toJSON(),
       );
@@ -951,7 +1368,151 @@ async function submit(prompt: string): Promise<string> {
       if (!(error instanceof SessionConflictError)) throw error;
     }
   }
-  return "session busy; retry the note";
+  return warn("session busy · retry the note");
+}
+
+/**
+ * `/track <name>`: focus `trackId` in this window, creating it when it is
+ * not in the score yet. A track another live window has focused stays
+ * theirs; focus goes through the port so presence is right everywhere.
+ */
+async function focusTrack(trackId: string): Promise<Receipt> {
+  if (trackId === requestedTrack && !draftTrack)
+    return warn(`already on ${trackId}`);
+  const clients = await port.presence().catch(() => []);
+  if (
+    clients.some(
+      (client) =>
+        client.clientId !== port.clientId && client.focusedTrackId === trackId,
+    )
+  )
+    return warn(`${trackId} is open in another window`);
+  const exists = score.tracks.some((track) => track.id === trackId);
+  if (!exists) {
+    const next = applyScoreOperation(score, {
+      type: "addTrack",
+      track: {
+        id: trackId,
+        name: trackId,
+        instrument: isDrumInstrument(trackId) ? "kit" : "sine",
+      },
+    });
+    await commitScore(next, "track.create", { trackId });
+  }
+  await port.focus(trackId);
+  requestedTrack = trackId;
+  draftTrack = false;
+  return ok(exists ? `track · ${trackId}` : `track created · ${trackId}`);
+}
+
+let sampleLibrary: SampleLibrary | undefined;
+let reportedSampleProblems = "";
+
+/** Decode every sampler voice (cached) and return what failed to load. */
+async function sampleProblems(
+  value: TrackScore,
+): Promise<readonly SampleProblem[]> {
+  if (!hasSamplerTracks(value)) return [];
+  sampleLibrary ??= new SampleLibrary({ projectRoot: process.cwd() });
+  try {
+    const bank = await sampleLibrary.load(value);
+    liveSampleBank = bank;
+    return bank.problems;
+  } catch (error) {
+    return [
+      {
+        trackId: "",
+        voice: "",
+        src: "",
+        level: "error",
+        message: `samples · ${error instanceof Error ? error.message : String(error)} · check the sample files`,
+      },
+    ];
+  }
+}
+
+/** Surface sample load problems once per distinct set, as receipts. */
+function reportSampleProblems(value: TrackScore): void {
+  if (!hasSamplerTracks(value)) return;
+  void sampleProblems(value).then((problems) => {
+    const key = problems.map((problem) => problem.message).join("\n");
+    if (key === reportedSampleProblems) return;
+    reportedSampleProblems = key;
+    for (const problem of problems.slice(0, 3))
+      tui.activity.pushCard(`sample ${problem.voice} · ${problem.message}`, {
+        tone: problem.level === "error" ? "error" : "warning",
+        trackId: problem.trackId || undefined,
+      });
+    if (problems.length > 3)
+      tui.activity.pushCard(
+        `${problems.length - 3} more sample problems · /tracks`,
+        {
+          tone: "warning",
+        },
+      );
+    tickUi();
+  });
+}
+
+async function sampleCommand(
+  command: NonNullable<ReturnType<typeof parseSampleCommand>>,
+): Promise<Receipt> {
+  if (command.kind === "list") {
+    const track = score.tracks.find((item) => item.id === requestedTrack);
+    const lines = listSampleVoices(track);
+    if (lines.length === 0)
+      return warn(
+        `sample · ${requestedTrack} has no samples · /sample <path> [as <voice>]`,
+      );
+    tui.openText(`samples · ${requestedTrack}`, lines);
+    return ok(
+      `${lines.length} sample${lines.length === 1 ? "" : "s"} · esc closes`,
+    );
+  }
+  await materializeDraft();
+  const trackId = samplerTarget(score, requestedTrack);
+  const voice =
+    command.voice ?? freeVoiceName(score, trackId, voiceNameFrom(command.path));
+  let placed;
+  try {
+    placed = await placeSampleFile({
+      projectRoot: process.cwd(),
+      cwd: process.cwd(),
+      input: command.path,
+      score,
+      trackId,
+      voice,
+    });
+  } catch (error) {
+    if (error instanceof SamplePlacementError)
+      return fail(`sample · ${error.message} · check the path and retry`);
+    throw error;
+  }
+  const result = addSampleVoice(score, trackId, voice, {
+    src: placed.src,
+    sha256: placed.sha256,
+  });
+  if (!result.ok) return fail(result.message);
+  // Decode before committing so a bad file is a receipt, not a silent voice.
+  const problems = (await sampleProblems(result.next)).filter(
+    (problem) => problem.trackId === trackId && problem.voice === voice,
+  );
+  if (problems.some((problem) => problem.level === "error"))
+    return fail(`sample · ${problems[0]!.message}`);
+  await commitScore(result.next, "sample.add", {
+    trackId,
+    voice,
+    src: placed.src,
+  });
+  if (trackId !== requestedTrack) {
+    await port.focus(trackId);
+    requestedTrack = trackId;
+    draftTrack = false;
+  }
+  await projectSync?.flushScore();
+  return ok(
+    `${result.message}${placed.copied ? ` · copied to ${placed.src}` : ""}`,
+  );
 }
 
 async function readLoopFile(path: string): Promise<string> {
@@ -1002,7 +1563,12 @@ function adoptMeta(meta: typeof record.meta): void {
   record = { ...record, meta };
   if (meta.name !== announcedName) {
     announcedName = meta.name;
-    tui.activity.pushCard(`session · ${meta.name}`, { tone: "info" });
+    tui.activity.pushCard(
+      meta.nameSource === "auto"
+        ? `${meta.name} (auto-named) · rename with /rename <name>`
+        : `session · ${meta.name}`,
+      { tone: "info" },
+    );
   }
 }
 
@@ -1022,7 +1588,9 @@ function makeNamer(): AutoNamer {
 }
 
 /** `/sessions`, `/resume`, `/rename`, `/fork`; undefined when not one. */
-async function sessionCommand(command: string): Promise<string | undefined> {
+async function sessionCommand(
+  command: string,
+): Promise<string | Receipt | undefined> {
   const match = command.match(/^\/(sessions|resume|rename|fork)(?:\s+(.*))?$/i);
   if (!match) return undefined;
   const verb = match[1]!.toLowerCase();
@@ -1030,7 +1598,9 @@ async function sessionCommand(command: string): Promise<string | undefined> {
   const workspace = process.cwd();
   if (verb === "rename") {
     if (!arg)
-      return `session · ${record.meta.name} (${record.meta.nameSource}) · /rename <name> | --auto`;
+      return record.meta.nameSource === "auto"
+        ? `${record.meta.name} (auto-named) · rename with /rename <name>`
+        : `${record.meta.name} (named by you) · /rename --auto to auto-name`;
     if (arg === "--auto") {
       const result = await port.updateMeta({
         nameSource: "auto",
@@ -1051,7 +1621,7 @@ async function sessionCommand(command: string): Promise<string | undefined> {
   const sessions = await listSessions(workspace);
   if (verb === "resume" && !arg) {
     const readable = sessions.filter((session) => !session.error).slice(0, 64);
-    if (readable.length === 0) return "no sessions to resume";
+    if (readable.length === 0) return warn("no sessions to resume");
     const current = readable.findIndex(
       (session) => session.sessionId === record.sessionId,
     );
@@ -1064,35 +1634,48 @@ async function sessionCommand(command: string): Promise<string | undefined> {
       })),
       index: Math.max(0, current),
     });
-    return "resume · pick a session (or /resume <n|name|id>)";
+    return "resume · 1-9 shown · /resume <name|id>";
   }
   if (verb === "sessions") {
-    const lines = pickerLines(sessions, record.sessionId, (session) =>
-      formatSessionLine(session, sessions),
+    const lines = pickerLines(
+      sessions,
+      record.sessionId,
+      (session) => formatSessionLine(session, sessions),
+      MAX_LISTED_SESSIONS,
+    );
+    tui.openText("sessions · * current · /resume <n>", lines);
+    return ok(
+      `${lines.length} session${lines.length === 1 ? "" : "s"} · esc closes`,
     );
-    for (const line of lines) tui.activity.pushCard(line, { tone: "info" });
-    return `${lines.length} sessions`;
   }
-  if (agentTurn) return "agent busy; finish or Esc first";
+  if (agentTurn) return warn("agent busy · finish or Esc first");
   if (verb === "fork") {
     const forked = await forkSession(workspace, record, arg || undefined);
     await switchSession(forked.sessionId);
     return `forked · ${forked.meta.name}`;
   }
   const readable = sessions.filter((session) => !session.error);
-  const index = /^[1-9]$/.test(arg) ? Number(arg) - 1 : -1;
-  const sessionId =
-    readable[index]?.sessionId ??
-    (await resolveSessionArg(workspace, arg, sessions));
-  if (!sessions.some((session) => session.sessionId === sessionId))
-    return `no session named "${arg}"`;
-  if (sessionId === record.sessionId) return `already in ${record.meta.name}`;
+  // Any list index works, not only the digits the picker binds.
+  const index = /^\d+$/.test(arg) ? Number(arg) - 1 : -1;
+  let sessionId = readable[index]?.sessionId;
+  if (sessionId === undefined)
+    try {
+      sessionId = await resolveSessionArg(workspace, arg, sessions);
+    } catch (error) {
+      if (!(error instanceof SessionLookupError)) throw error;
+      return fail(error.message.replace(" · dawg sessions", " · /sessions"));
+    }
+  if (sessionId === record.sessionId)
+    return warn(`already in ${record.meta.name}`);
   await switchSession(sessionId);
   return `resumed · ${record.meta.name} · ${requestedTrack}${draftTrack ? " (new)" : ""}`;
 }
 
 /** Leaves the current session and attaches this window to `sessionId`. */
 async function switchSession(sessionId: string): Promise<void> {
+  // Play mode belongs to the old session's engine and track.
+  await play?.exit();
+  play = undefined;
   if (clock.playing) await setTransport("pause");
   namer.dispose();
   await port.close();
@@ -1123,29 +1706,237 @@ async function switchSession(sessionId: string): Promise<void> {
     });
 }
 
+function liveEngine(): LiveEngine | undefined {
+  if (audio instanceof AudioEngine) return audio;
+  monitorEngine ??= new AudioEngine({ projectRoot: process.cwd() });
+  return monitorEngine;
+}
+
+/** The play session for the focused track (re-made when focus moves). */
+function menuContext(): MenuContext {
+  const session = play;
+  return {
+    score,
+    trackId: requestedTrack,
+    playing: clock.playing,
+    grid: session?.grid ?? DEFAULT_GRID,
+    grids: GRIDS.map((grid) => grid.label),
+    clickOn: session?.clickOn ?? false,
+    countInBars: session?.countInBars ?? 1,
+  };
+}
+
+function openMenu(section?: string): void {
+  menu.show(menuContext(), section);
+  refreshMenu();
+}
+
+function refreshMenu(): void {
+  if (!menu.open) return;
+  if (tui.ui.overlay !== undefined && tui.ui.picker?.id !== "menu") {
+    // Another overlay (help, a picker) replaced the menu.
+    menu.close();
+    return;
+  }
+  const view = menu.view(menuContext());
+  tui.openPicker({
+    id: "menu",
+    title: view.title,
+    items: view.items.length
+      ? view.items
+      : [{ label: "no matches", value: "none" }],
+    index: view.index,
+    hint: view.hint,
+  });
+}
+
+function playSession(): PlaySession {
+  if (play && play.track === requestedTrack) return play;
+  const previous = play;
+  play = new PlaySession(playHost(), {
+    clickOn: previous?.clickOn,
+    clickVolume: previous?.clickVolume,
+  });
+  if (previous) {
+    play.countInBars = previous.countInBars;
+    play.grid = previous.grid;
+  }
+  return play;
+}
+
+async function enterPlay(): Promise<Receipt> {
+  if (play?.on) return ok(`play · ${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} · z/x octave · r record · m click · esc leaves`,
+  );
+}
+
+async function exitPlay(): Promise<Receipt> {
+  if (!play?.on) return ok("play mode is off");
+  await play.exit();
+  return ok("play off");
+}
+
+/**
+ * One key in play mode. True when play mode consumed it; false sends it on
+ * to the normal bindings (overlays, a command being typed, Ctrl-C, arrows).
+ */
+function playKey(value: string): boolean {
+  const session = play;
+  if (!session?.on) return false;
+  if (tui.ui.overlay !== undefined) return false;
+  // `/play off`, `/click 50%`: once a command is being typed, keys are text.
+  if (prompt.value.length > 0) return false;
+  if (value === "/") return false;
+  if (value === "\u0003") return false;
+  const result = session.press(value);
+  if (result.type === "handled") return true;
+  if (result.type === "command") {
+    if (result.command === "exit")
+      void exitPlay().then((outcome) => receipt(outcome));
+    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)}`,
+          ),
+        );
+    } else if (result.command === "menu") return false;
+    return true;
+  }
+  // Unmapped: printable keys are swallowed so a stray letter never lands in
+  // the prompt; control keys (Enter, arrows, Ctrl-Z) keep their bindings.
+  return value.length === 1 && value >= " " && value !== "\u007f";
+}
+
+function playHost() {
+  return {
+    score: () => score,
+    trackId: () => requestedTrack,
+    now: () => performance.now(),
+    playing: () => clock.playing,
+    beatAt: (ms: number) => clock.beatAt(ms),
+    engine: liveEngine,
+    samples: () => liveSampleBank,
+    async commit(
+      next: TrackScore,
+      kind: string,
+      payload: Record<string, unknown>,
+    ): Promise<void> {
+      const operations = (payload.operations ?? []) as ScoreOperation[];
+      let target = next;
+      for (let attempt = 0; attempt < 3; attempt += 1) {
+        try {
+          record = await port.appendOperations(
+            record,
+            { kind, payload },
+            operations,
+            target.toJSON(),
+          );
+          score = scoreFromJSON(record.composition);
+          if (clock.playing) void audio.play(score);
+          projectSync?.scoreChanged(score);
+          return;
+        } catch (error) {
+          if (!(error instanceof SessionConflictError)) throw error;
+          record = await port.load();
+          score = scoreFromJSON(record.composition);
+          target = operations.reduce(
+            (value, operation) => applyScoreOperation(value, operation),
+            score,
+          );
+        }
+      }
+      throw new Error("session busy");
+    },
+    async startTransport(beat: number): Promise<void> {
+      if (port.mode === "daemon") {
+        await port.transport("play", { beat });
+        return;
+      }
+      clock.sync(beat, false);
+      await setTransport("play");
+    },
+    async stopTransport(): Promise<void> {
+      await setTransport("pause");
+    },
+    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,
+        });
+    },
+    newNoteId: () => randomUUID().slice(0, 12),
+  };
+}
+
 async function commitScore(
   next: TrackScore,
   kind: string,
   payload: Record<string, unknown> = {},
 ): Promise<void> {
   if (next === score) return;
-  record = await port.append(
-    record,
-    { kind, payload: { ...payload, before: record.composition } },
-    next.toJSON(),
-  );
+  record = await port.append(record, { kind, payload }, next.toJSON());
   score = next;
   if (clock.playing) void audio.play(score);
+  projectSync?.scoreChanged(score);
+  reportSampleProblems(score);
+}
+
+/** The window's side of the project file sync (see src/project/sync.ts). */
+function syncHost(): SyncHost {
+  return {
+    project: process.cwd(),
+    current: () => score,
+    async commit(plan, summary) {
+      const baseRevision = record.revision;
+      record = await port.appendOperations(
+        record,
+        {
+          kind: "files.apply",
+          payload: { summary },
+        },
+        plan.operations,
+        plan.next.toJSON(),
+      );
+      score = scoreFromJSON(record.composition);
+      clock.setTempo(score.tempoBpm);
+      if (clock.playing) void audio.play(score);
+      reportSampleProblems(score);
+      void baseRevision;
+      return score;
+    },
+    card(text, tone, hint) {
+      if (tone === "error") tui.activity.pushError(text);
+      else
+        tui.activity.pushCard(text, {
+          tone,
+          hint,
+          resultRevision: tone === "success" ? record.revision : undefined,
+        });
+    },
+    types(state) {
+      typesIndicator = state;
+    },
+  };
 }
 
-async function stepHistory(direction: "undo" | "redo"): Promise<string> {
+async function stepHistory(direction: "undo" | "redo"): Promise<Receipt> {
   const latest = await port.load();
   // A fork's undo continues into its parent's history past the fork point.
   const target = historyTarget(
+    latest.composition,
     await historyEvents(process.cwd(), latest),
     direction,
   );
-  if (!target) return `nothing to ${direction}`;
+  if (!target) return warn(`nothing to ${direction}`);
   try {
     const restored = scoreFromJSON(target.composition);
     record = await port.append(
@@ -1155,18 +1946,46 @@ async function stepHistory(direction: "undo" | "redo"): Promise<string> {
         payload: {
           [direction === "undo" ? "undoneRevision" : "redoneRevision"]:
             target.revision,
-          before: latest.composition,
         },
       },
       restored.toJSON(),
     );
     score = restored;
     if (clock.playing) void audio.play(score);
-    return `${direction === "undo" ? "undid" : "redid"} · rev ${target.revision}`;
+    return ok(
+      `${direction === "undo" ? "undid" : "redid"} · rev ${target.revision}`,
+    );
   } catch (error) {
     if (error instanceof SessionConflictError)
-      return `session changed; retry ${direction}`;
-    return `${direction} error · ${error instanceof Error ? error.message : String(error)}`;
+      return warn(`session changed · retry ${direction}`);
+    return fail(
+      `${direction} failed · ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
+/** The space-bar toggle: flip the transport, then record it for other windows. */
+async function toggleTransport(): Promise<void> {
+  await setTransport("toggle");
+  try {
+    record = await port.append(
+      record,
+      {
+        kind: "transport",
+        payload: {
+          action: "toggle",
+          playing: clock.playing,
+          beat: clock.beatAt(),
+        },
+      },
+      score.toJSON(),
+    );
+  } catch (error) {
+    if (error instanceof SessionConflictError)
+      tui.activity.pushCard("transport changed in another window", {
+        tone: "warning",
+      });
+    else throw error;
   }
 }
 
@@ -1198,11 +2017,13 @@ async function setTransport(
  * own revision through `agentHost`, so cancelling keeps every accepted change
  * and never leaves a half-applied call.
  */
-async function runAgent(text: string): Promise<string> {
-  if (agentTurn) return "agent busy";
+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 `unrecognized request · ${selection.reason}`;
+    return fail(
+      `unrecognized · ${truncateForCard(text)} · ${selection.reason}`,
+    );
   const turn = { controller: new AbortController(), steering: [] as string[] };
   agentTurn = turn;
   reportAgentActivity(`${providerName} · thinking…`);
@@ -1213,8 +2034,7 @@ async function runAgent(text: string): Promise<string> {
     const result = await runProviderTurn({
       selection,
       prompt: text,
-      model: selectedModel,
-      host: agentHost(turn),
+      host: agentHost(turn, selection),
       signal: turn.controller.signal,
       onEvent: (event) => {
         if (admitting && event.type === "step" && event.step <= 1) return;
@@ -1222,6 +2042,22 @@ async function runAgent(text: string): Promise<string> {
           admitting = false;
           provider = undefined; // Re-read capabilities: now admitted.
         }
+        if (event.type === "usage") {
+          // Subscriptions are included; API responses are priced once.
+          if (isApiSelection(selection)) {
+            const { type: _type, ...usage } = event;
+            void priceForModel(selection.kind, selection.modelId, {
+              configDir: configDir(),
+              apiKey: selection.apiKey,
+            })
+              .catch(() => undefined)
+              .then((price) => {
+                meter.add(usage, price);
+                tickUi();
+              });
+          }
+          return;
+        }
         agentEventSink(event);
       },
     });
@@ -1257,13 +2093,33 @@ function currentProvider(): Promise<ProviderSelection> {
     }));
   }
   return provider.then((selection) => {
-    providerName = providerLabel(selection, selectedModel);
+    providerSnapshot = selection;
+    providerName = providerLabel(selection);
+    if (
+      selection.kind === "offline" &&
+      selection.invalidSaved &&
+      !invalidNoticeShown
+    ) {
+      invalidNoticeShown = true;
+      tui.activity.pushCard(`sign-in stopped working · ${selection.reason}`, {
+        tone: "warning",
+        hint: "/login",
+      });
+    }
     providerStamp.offline = selection.kind === "offline";
     return selection;
   });
 }
 
-function agentHost(turn: { steering: string[] }): AgentHost {
+/** Media tools write under the workspace's `tracks/<slug>/downloads/`. */
+function mediaServices(): MediaServices {
+  return { runner: systemRunner, env: process.env };
+}
+
+function agentHost(
+  turn: { steering: string[] },
+  selection: ProviderSelection,
+): AgentHost {
   return {
     snapshot: () => ({
       score,
@@ -1276,6 +2132,7 @@ function agentHost(turn: { steering: string[] }): AgentHost {
           : event.kind;
       }),
     }),
+    media: mediaServices(),
     async commit(change) {
       // dawgd rebases operation intents onto newer revisions when nothing
       // they touch changed; the file port keeps the strict base check.
@@ -1291,7 +2148,6 @@ function agentHost(turn: { steering: string[] }): AgentHost {
               callId: change.callId,
               summary: change.summary,
               operations: change.operations,
-              before: record.composition,
             },
           },
           change.operations,
@@ -1328,5 +2184,26 @@ function agentHost(turn: { steering: string[] }): AgentHost {
       }
     },
     takeSteering: () => turn.steering.splice(0),
+    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.
+    async onWorkspaceWrite(path) {
+      if (!projectSync || !/\.ts$/.test(path)) return;
+      const outcome = await projectSync.checkFiles();
+      const types = await typecheckProject(process.cwd());
+      const errors = types.diagnostics.slice(0, 8).map(formatDiagnostic);
+      return [
+        outcome,
+        types.ok ? "types ✓" : `types ✗ ${types.diagnostics.length}`,
+        ...errors,
+      ].join("\n");
+    },
+    // web_search uses the turn's own gateway or OpenRouter key; billed
+    // searches go to the spend meter and daily ledger.
+    web: webHostFor(
+      isApiSelection(selection) ? selection : { kind: selection.kind },
+      meter,
+      tickUi,
+    ),
   };
 }