@hraness/dawg 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to dawg are recorded here. Versions follow [semantic versioning](https://semver.org); releases are published as immutable GitHub Releases with a tarball, `SHA256SUMS` and a build provenance attestation.
+
+## 0.2.0
+
+The first tagged release. Open a session in several terminals, give each window its own instrument, let an agent write parts, and every window stays on the same song.
+
+### Renamed from Track to dawg
+
+The project, CLI and package are now **dawg**: the command is `dawg`, the daemon `dawgd`, the package `@hraness/dawg` and the repository [hraness/dawg](https://github.com/hraness/dawg) (the old `hraness/track` URLs redirect). Environment variables are `DAWG_*`, workspace state lives in `.dawg/`, config in `~/.config/dawg`, and gateway keys in the Keychain service `dawg` (new keys are named `dawg-<host>`).
+
+### Install
+
+```sh
+curl -fsSL https://dawg.sh/install | sh
+# or
+bun add -g https://github.com/hraness/dawg/releases/download/v0.2.0/hraness-dawg-0.2.0.tgz
+```
+
+### Added
+
+- **Stereo renderer.** Renders and `dawg render` WAVs are now interleaved stereo with equal-power pan, a ping-pong stereo delay and a stereo reverb, and stay byte-identical across runs.
+- **Reverb send.** `reverb <mix> [size]` / `reverb off` per track, a deterministic Freeverb-style network (eight damped combs and four allpasses per channel). The agent's `set_effects` tool takes `reverb {mix, size}` or `null`.
+- **More automation lanes.** `automate resonance|delay-feedback|delay-mix at <beat> <value>` (and `clear <lane> automation`), validated by the planner and available to the agent's `set_automation` tool.
+- **Gapless audio engine.** Playback streams a seamless loop as raw PCM into one long-lived `ffplay` (or SoX `play`) process. Edits, tempo changes and seeks swap the buffer in place without restarting playback, and the write position stays anchored to the shared transport clock. On macOS without either, `afplay` replays a re-rendered loop. `dawg auth status` and `/auth` show the backend; `DAWG_AUDIO_BACKEND` and `DAWG_AUDIO_PLAYER` override it.
+- **Drums and effects (#8).** A `kit` instrument with kick, rim, snare, clap, hats and tom, written with `hit <voice> at <beat>`, `pattern <voice> <beats...>` or `pattern <voice> every <step>`. A track named `drums` gets the kit automatically. Per-track low-pass filter (`filter <hz> [res]`), tempo-synced delay (`delay <beats> [fb] [mix]`), filter automation, `solo`/`unsolo` and `redo`.
+- **Streaming agent (#9).** Requests that aren't direct commands go to a streaming, tool-calling agent on Vercel AI Gateway (`opus-5.5` or `sol-6.1`, switch with `/model`). It edits only through typed, validated tools, and each accepted call becomes its own revision. Esc cancels and keeps what was accepted. Enter steers the turn in progress.
+- **dawgd (#10).** One local daemon per session, started by the first window. Every window sees the same revisions, presence and transport, so play in one window plays everywhere. It recovers from crashes, and if the daemon can't start, windows fall back to the file lock. `dawg sessions` lists the sessions in a workspace.
+- **New terminal UI (#11).** A highway where notes stream toward a hit line, with sustain beams, hit bursts and drum lanes. It adds an activity strip of operation cards, a themed multiline prompt with steer and queue modes, and a transcript (`Ctrl+O` or `/log`). Themes are `/theme default|high-contrast|mono`. `/motion off` or `--reduce-motion` gives static states. `NO_COLOR` is respected.
+- **Login and providers (#12).** `dawg login` creates an AI Gateway key with the Vercel CLI, or takes a pasted key. `dawg login --xcb` uses a Claude, Codex or Devin subscription through xcb. `dawg auth status` and `dawg logout` manage it. Keys are kept in the macOS Keychain or a 0600 file and never in `.dawg/`.
+- **Named sessions (#13).** Sessions are named automatically from what you play, and you can rename them with `/rename <name>` (or hand the name back with `/rename --auto`). `/fork [name]` branches a song (`night drive` → `night drive 2`). `/sessions` lists them and `/resume` picks one. Plain `dawg` windows claim the next open track, so three windows on a three-track song restore drums, bass and keys, and a fourth gets a draft track.
+- **`dawg render <out.wav>`** writes the current session (or `--session`, or `--import file.track.json`) to a WAV without starting audio. The same score always produces the same bytes, and the sha256 is printed.
+- **`/status`** shows the session name, revision, composition digest and whether the window is on dawgd or the file fallback.
+- An end-to-end suite that runs real `dawg` windows in PTYs against a live dawgd, now part of `bun run check` and CI.
+
+### Fixed
+
+- In demo mode, `--track drums` seeded the melodic demo notes, which played as rim hits. It now seeds a kick, snare and hat groove.
+
+### Not yet
+
+- dawg is not published to npm. Install from the GitHub Release tarball until a trusted publisher is configured.
+
+## 0.1.0
+
+Initial release (untagged): a local-first terminal piano roll with a shared `.track` session, direct note, tempo, instrument, volume and pan commands, volume and pan automation, undo, deterministic WAV playback through `afplay` or `ffplay`, and `track.loop/v1` import and export.

package/DAWG.md

@@ -0,0 +1,142 @@
+# dawg
+
+dawg is a local-first terminal music workstation with a Pi-like agent loop. Each terminal window can focus on one track while a shared local session keeps the score, transport, and agent operations in sync. It is designed for `dawg` to feel like a coding agent session where the artifact is a loop you can hear and edit.
+
+The first steel thread includes a typed `track.loop/v1` score, an append-only local session with a cross-window writer lock, a terminal piano-roll projection, a multiline prompt, a bounded streaming tool-calling agent on the Vercel AI Gateway, and a local PCM synthesizer. Provider and audio adapters remain behind explicit ports so the TUI can still be exercised without credentials or a sound device.
+
+## Run
+
+```sh
+bun install
+bun run dawg
+```
+
+Run `dawg` from any directory. It creates `.dawg/session` on first use and reuses that session in later terminal windows. Use `dawg --new` for a separate composition, `dawg --session <id>` to attach explicitly, and `dawg --track bass` to focus a named track. Every window connects to `dawgd`, a per-session daemon the first window starts in the background. It is the single writer: windows send operations with a base revision and an idempotency key, duplicate keys are no-ops, a stale full composition receives a typed rebase diagnostic, and a stale `operations` intent (what the agent sends) is replayed on the current score when nothing it touches changed since its base (the notes it updates or removes, the tracks it rewrites or clears, tempo and length, and ids it creates; at most 64 revisions back, with the base recovered from the event log's `before`); anything else still gets the rebase diagnostic. Rebased events record `rebasedFrom` and the score they replayed on as `before`, so undo drops only that change, and on the file fallback the agent commits the full composition with the strict base check. Accepted commits are persisted through the same atomic snapshot store before being broadcast to every window. The daemon also owns the only transport and audio player, broadcasting play, pause, seek, and tempo with a timestamp so every window draws the same hit line. It keeps a presence table (`clientId`, `pid`, focused track) and can atomically claim the first unfocused track for a new window. The daemon exits 30 seconds after its last window closes, removes its socket on SIGTERM, and a crashed daemon's socket and lock are reclaimed by the next window. If `dawgd` cannot be started (or `DAWG_DAEMON=0`), windows fall back to the snapshot under the file lock, watching the session directory with `fs.watch` (so renames and edits from other windows arrive immediately) with a 1 s backstop poll, or a 200 ms poll where watching is unavailable, with presence kept in per-window heartbeat files. `dawg sessions` lists sessions in the current workspace. `dawg render <out.wav> [--session <name|id>] [--import <file>]` reads the session record from disk (no daemon, no audio) and writes a mono 16-bit WAV through the playback renderer; the same score always yields the same bytes, and the command prints the size and sha256. `/status` reports `status · <name> · rev <n> · <digest> · daemon|file`, where the digest is the 16-hex composition digest dawgd broadcasts. In demo mode a drum track is seeded with a one-bar kick, snare and hat groove instead of melodic notes.
+
+### Sessions, names and forks
+
+Each session record carries bounded metadata alongside the score: `name` (1–40 printable characters), `nameSource` (`auto` or `user`), an optional `forkOf {sessionId, revision}`, the fingerprint the current auto-name was computed from, and a `version` counter. Records written before metadata existed load with an id-based auto name. Metadata writes are conditional (`expect {name?, nameSource?}`) and never touch the score revision or event log. Through `dawgd` they are a `meta` frame that the daemon applies, persists atomically and broadcasts; on the file fallback they run under the session lock, and polling windows pick up the newer `meta.version`. `/rename <name>` is unconditional and sets `nameSource=user`, so it wins over any auto-name computed against the old name, which arrives `stale` and is dropped. `/rename --auto` sets `nameSource=auto` and clears the stored fingerprint.
+
+`/fork [name]` writes a new session with a snapshot of the composition at the current revision (not the event log), `forkOf` lineage and a numbered name: strip a trailing ` N` (N ≥ 2) from the parent, then take one more than the highest ` N` among sessions with that base. An explicit name that collides is suffixed the same way. The workspace pointer moves to the fork, so plain `dawg` resumes it. Undo does not stop at the fork point: the fork's history is its own events preceded by each ancestor's events up to the revision it was forked at, following `forkOf` at most 8 levels (stopping at cycles, missing parents or revisions beyond the parent's log) and keeping at most the store's event cap.
+
+On launch, and after `/fork` or `/resume`, a window without `--track` sends an atomic `claim {draft: true}`. dawgd serializes claims on its event loop; the file fallback serializes them under the presence lock. The reply is the first track in score order that no live window has focused, or, when every track is taken, a fresh `track-N` id that is neither in the score nor focused by another window. A draft is only appended to the score (`track.attach`) on the window's first edit. `--session <name|id>` resolves an exact id, then an exact case-insensitive name, then a unique id prefix of at least four characters; ambiguous names list the candidates and exit.
+
+The header shows the session name and, when more than one window is open, the window count. Renames, forks, claims and the all-tracks-open hint appear as activity cards. The session port exposes a structured sync status (`synced`, `syncing`, `conflict`, `offline`, `local`) that drives the header directly.
+
+Auto-naming (`src/session/naming.ts`) is gated on a local musical fingerprint: tempo, a scale-fit key estimate from the pitch-class histogram (tonic and fifth weighted), sorted instrument families, register and density buckets, and effects, hashed into an order- and id-independent digest. After an accepted turn the namer waits for a quiet period, and skips the model when the fingerprint equals the one the current name came from or when fewer than three turns have passed since the last name (a structure change, such as a new instrument family, bypasses the turn gate). The prompt is one fingerprint line, the last two prompts truncated to 60 characters each, and the current name, with `max_tokens: 12`. The reply is untrusted: it is stripped to 2–4 lowercase words of at most 32 characters, and a reply equal to the current name keeps it (hysteresis). The write is conditional on the name and `nameSource` the request started from, and a newer request supersedes an older one, so a slow provider (xcb takes about 7 s) can never overwrite a user rename. Forks keep their ` N` suffix through auto-renames, and a name already used by another session is suffixed. The generator is an injectable `NameGenerator`; the default calls `generateText` from `src/agent/provider.ts` and falls back to the deterministic local name.
+
+The `dawgd` protocol is newline-delimited JSON over a Unix socket in the session directory, or a hashed path under `$TMPDIR` when that path would exceed the platform socket-path limit. Every frame carries `v: 1`, frames are size-bounded, and every inbound frame is parsed from `unknown`. Clients send `hello`, `apply`, `transport`, `sync`, `focus`, `claim`, and `ping`; the daemon replies with `welcome`, `result`, `snapshot`, `claimed`, `pong`, and typed `error` frames, and pushes `commit`, `transport`, and `presence`.
+
+The header (track · session · ▶/⏸ BPM · model · rev · sync) sits above the highway. The highway sits above the activity strip and the prompt. Notes stream toward the hit line, and velocity sets glyph density (`░▒▓█`) and saturation. Beat and bar rules get stronger at each level. Sustains draw as beams with a decaying tail and a short ghost after release. Each hit runs approach glow → flash/burst at the line → fade. The hit line pulses on the beat, and a sweep marks the loop wrap. Drum tracks use one lane per voice with a legend; lane projection is pluggable (`LaneProjection` in `tui/highway.ts`). By default every unmuted track is overlaid through its own projection and accent, the focused track drawn on top at full strength and the others dimmed; `/view focus` restores the single-track view. Animation is derived from transport time, so frame rate never changes timing. Frames render into a retained cell buffer, only changed rows are written, and output is capped at about 30 fps.
+
+Keys: `Space` (empty prompt) toggles playback. `Enter` submits, or queues in QUEUE mode. `Shift+Enter`/`Ctrl+J` inserts a newline, `Alt+Enter` queues and `Ctrl+Q` toggles STEER/QUEUE. `Ctrl+Z`/`Ctrl+Y` undo and redo, and `Ctrl+O` or `/log` opens the transcript, which scrolls with ↑/↓, PgUp/PgDn and Home/End, and `/` cycles its filter (all, requests, ops, errors). `Esc` cancels an agent turn, closes the overlay or clears the draft. `Ctrl+L` redraws and `Ctrl+C` exits. Bracketed paste keeps multiline text intact.
+
+Themes: `/theme default|high-contrast|mono`, `--theme`, `DAWG_THEME`. Color falls back through truecolor, 256-color, 16-color and monochrome. `NO_COLOR` and `TERM=dumb` are supported. `/motion off`, `--reduce-motion` and `DAWG_REDUCE_MOTION=1` switch to static states in the same positions.
+
+Other code reports into the activity strip through `ActivityFeed` (`tui/activity.ts`): `pushCard(text, {tone, baseRevision, resultRevision, hint})`, `pushError(text)`, `setSpinner(label | undefined)`, `setQueueDepth(n)` and `applyAgentEvent(event)`, which accepts the agent's streaming `AgentEvent`s unchanged.
+
+The local command path understands requests such as:
+
+```text
+add C4 at 0 for 1
+play
+pause
+tempo 128
+instrument piano
+volume 0.7
+pan -0.4
+automate volume at 0 0.2
+automate volume at 4 1
+automate pan at 0 -1
+automate pan at 4 1
+clear pan automation
+track drums
+instrument kit
+hit kick at 0
+hit snare at 1 vel 0.7
+pattern kick 0 1 2 3
+pattern hat every 0.5 from 0.25
+clear hat
+filter 1200
+filter 800 0.6
+filter off
+delay 0.375 0.3
+delay 0.75 0.4 0.5
+delay off
+reverb 0.3
+reverb 0.4 0.8
+reverb off
+automate filter at 0 400
+automate filter at 4 6000
+automate resonance at 0 0.2
+automate delay-feedback at 0 0.6
+automate delay-mix at 4 0
+clear filter automation
+bars 8
+extend 4 bars
+clear automation
+mute
+solo
+unsolo
+clear
+undo
+redo
+move note <id> to 2.5
+duration note <id> 0.25
+/tracks
+/status
+/export loop.track.json
+/import loop.track.json
+/model opus-5.5
+```
+
+Drum tracks use the `kit` instrument (a track named `drums` gets it automatically). Notes on a kit track keep the score's MIDI pitch field, using General MIDI percussion numbers (kick 36, rim 37, snare 38, clap 39, closed hat 42, tom 45, open hat 46), so drum hits round-trip through `track.loop/v1` unchanged and the highway draws them in one lane per voice. Grammar, one command per prompt, beats in score beats:
+
+```text
+hit <voice> [at] <beat> [vel <0..1>]
+pattern <voice> <beat> [<beat> ...] [vel <0..1>]        up to 64 beats
+pattern <voice> every <step> [from <beat>] [vel <0..1>]  step >= 0.125, fills the loop, at most 256 hits
+clear <voice>
+filter <cutoff 20..20000> [<resonance 0..1>] | filter off
+delay <beats 0.0625..4> [<feedback 0..0.9> [<mix 0..1>]] | delay off
+reverb <mix 0..1> [<size 0..1>] | reverb off     size defaults to 0.5
+automate filter at <beat> <cutoff> | clear filter automation
+automate resonance at <beat> <0..1> | clear resonance automation
+automate delay-feedback at <beat> <0..0.9> | clear delay-feedback automation
+automate delay-mix at <beat> <0..1> | clear delay-mix automation
+solo | unsolo
+undo | redo
+```
+
+Effects live on the track as optional `filter {cutoff, resonance}`, `delay {beats, feedback, mix}`, `reverb {mix, size}`, `filterAutomation`, `resonanceAutomation`, `delayFeedbackAutomation`, `delayMixAutomation`, and `solo` fields. Effect lanes modulate an existing effect: a resonance lane needs a filter and the delay lanes need a delay. Documents written before these fields existed still parse; out-of-range or non-finite values are rejected. Undo and redo append ordinary session events, so history is shared by every window and a new edit clears the redo stack.
+
+Unrecognized prompts go to the agent whenever a provider is configured (`DAWG_AI=0` disables it). `dawg login` creates and stores an AI Gateway key; see **Providers and auth** below. `DAWG_MODEL=opus-5.5` or `DAWG_MODEL=sol-6.1` selects the initial friendly model label, and `/model opus-5.5` or `/model sol-6.1` switches it during a session. `DAWG_OPUS_MODEL` / `DAWG_SOL_MODEL` can map those labels to the provider IDs available in the account. By default the labels map to `anthropic/claude-opus-5.5` and `openai/gpt-6.1-sol`. Both IDs were checked against `GET https://ai-gateway.vercel.sh/v1/models` and are tagged `tool-use`. Labels outside the allowlist are rejected before any request is sent.
+
+### Agent turns
+
+A turn calls `POST /v1/chat/completions` with `stream: true` and one JSON-schema tool for each operation family. The OpenAI-compatible SSE stream is parsed locally with `fetch`, so the agent adds no runtime dependency. Each request sends a compact, deterministic **composition brief** instead of raw logs. It contains revision, tempo, meter, bars, key, tracks with instrument, mix, note count and pitch range, the focused track's notes, recent accepted operations and the instrument list. It is capped at 12 KiB and never includes environment values.
+
+When a tool call finishes streaming, it passes three checks: the tool's own argument checks, the planner's bounded operation validator, and a dry run of the score reducer. Only then is it committed through the session as a separate revision pinned to the revision it was planned against. If the call fails a check, or another window committed first (stale revision), dawg rejects it without changing the score. The model receives the diagnostic as the tool result and can correct itself. A turn is bounded to 8 steps, 32 tool calls, 256 KiB of streamed response and a 90 s timeout.
+
+`runAgentTurn` (`src/agent/agent.ts`) emits structured progress events for the TUI: `step`, `text-delta`, `tool-start`, `tool-applied` (with `summary`, `baseRevision`, `resultRevision` and `trackId`), `tool-rejected` (with `diagnostic`), and a final `done` or `error` (`aborted`, `timeout`, `budget`, `provider`). To add an operation family, append a tool to `AGENT_TOOLS` in `src/agent/tools.ts`. The schema, dispatch and validation all come from that one entry.
+
+### Providers and auth
+
+`src/agent/provider.ts` picks a backend per turn: `DAWG_PROVIDER`, then the choice saved by `dawg login` in `~/.config/dawg/config.json` (no secrets), then `auto` (a gateway key, else an available xcb account, else offline with a `dawg login` hint). Gateway keys resolve from `AI_GATEWAY_API_KEY`, then the macOS Keychain (`security find-generic-password -s dawg -a ai-gateway -w`), then `~/.config/dawg/credentials.json` (0600 under a 0700 directory, written atomically through a temp file and rename). Storing uses `security -i` with the command on stdin, so the key never appears on an argv. Keys must match `[A-Za-z0-9._-]{16,256}` and are shown only masked (`vck_…abcd`).
+
+`dawg login` (`src/auth/login.ts`) runs `vercel whoami --format json`. If you are not logged in, it hands the terminal to `vercel login`, then runs `vercel ai-gateway api-keys create --name dawg-<host> --non-interactive [--limit <dollars>]`. That command prints only the key on stdout. dawg validates the key with `GET /v1/credits` and reports valid, rejected or unverified (offline). Every subprocess goes through the injectable `CommandRunner` in `src/auth/runner.ts`, which bounds output, writes stdin and on abort sends SIGTERM (SIGKILL after 15 s) and waits for exit. Tests script `vercel`, `security` and `xcb` through it.
+
+The xcb provider (`src/agent/xcb.ts`, `src/agent/xcb-agent.ts`) calls `xcb --json generate` with one `{version:1, account, model, prompt, timeoutMs, maxOutputBytes}` request on stdin. xcb exposes zero tools and does not stream, so the prompt carries the system rules, the composition brief and the tool catalog as JSON schemas, and asks for exactly one `{ops:[{tool,args}], say?, done}` object. The reply is untrusted. dawg takes the first balanced JSON object in at most 64 KiB, allows at most 16 ops and caps `say` at 400 characters. Each op then goes through `executeCall`, the same argument checks, operation validator, reducer dry run and per-op revision commit used by the gateway loop, and emits the same `tool-applied`/`tool-rejected`/`text-delta` events. If a reply cannot be parsed, an op is rejected or `done` is false, dawg makes another call with the per-op results, up to 3 calls and within the normal turn budgets. Esc aborts the turn, which terminates the xcb child and keeps every accepted revision. Accounts come from `xcb --json generate --capabilities`, parsed field by field from `unknown`. An account is usable only when xcb reports it `available` with at least one model, which requires xcb's application qualification. An account whose `admission` is `pending` (xcb admits it on first use) is also usable; `denied` never is, and the field may be absent. dawg never runs qualification or the xcb installer.
+
+`generateText(prompt, {maxTokens, signal?, timeoutMs?, selection?})` from `src/agent/provider.ts` is a tool-free one-shot completion for helpers like session naming. On the gateway it uses `anthropic/claude-haiku-4.5` with `max_tokens`. On xcb it uses the selected account with `maxOutputBytes ≈ 8 × maxTokens`. It returns at most 512 trimmed characters of untrusted text and throws when offline, so callers should fall back to a local default.
+
+Playback renders the score to interleaved stereo 16-bit PCM with deterministic sine, piano, pluck, bass, saw, square, and triangle voices and a synthesized kit whose noise comes from a PRNG seeded by each note, so every render is byte-identical. Track volume and pan automation, the low-pass filter (with cutoff and resonance lanes), the delay send (with feedback and mix lanes), and the reverb send are applied per track; mute always silences a track and any solo silences unsoloed tracks. Pan uses an equal-power law (-1 left, 1 right). The delay is a stereo ping-pong (first repeat on the panned side, later repeats alternate) and the reverb is a Freeverb-style network of eight parallel damped combs and four series allpasses per channel, with the right channel's delay lines offset for width; both use only integer delay lengths and fixed coefficients, so renders stay deterministic.
+
+Audio engine. With `dawgd` running only the daemon plays audio; on the file-lock fallback a per-session audio lock keeps multiple TUI windows from starting duplicate voices. The engine renders one loop with every tail (release, delay, reverb) folded back onto the loop start, so the buffer repeats seamlessly, and streams it as raw s16le stereo into one long-lived player process, paced by the wall clock with about 200 ms queued. An edit renders the new loop and swaps it in at the current loop position without restarting the player; a tempo change keeps the musical beat; a seek or a drift above 30 ms re-anchors the write position to the shared transport clock, offset by the queued audio, so the transport matches what you hear. Backends, in order: `ffplay -f s16le -i -`, then SoX `play -t raw -`, then (macOS) `afplay` re-rendering a loop-folded WAV rotated to the current beat on each edit, the only backend that restarts. `DAWG_AUDIO_BACKEND=ffplay|sox|afplay|none` forces one, `DAWG_AUDIO_PLAYER="cmd {rate} {channels}"` streams into any stdin player, and `DAWG_AUDIO=0` disables sound. `dawg auth status` and `/auth` print the detected backend. The renderer is deterministic and independently testable; a native or sample-backed instrument backend can replace it behind the same player port.
+Set `DAWG_AUDIO=0` for headless sessions.
+
+Use `DAWG_DEMO=1 bun run src/main.ts` for a deterministic non-interactive frame stream while developing the renderer.
+
+## Release
+
+Bump `version` in `package.json` and add its section to `CHANGELOG.md` in a pull request, then merge it. When Check passes on `main`, the annotated `v<version>` tag, the immutable GitHub Release (tarball, `SHA256SUMS` and a provenance attestation) and the npm publish of `@hraness/dawg` follow automatically. See [docs/publishing.md](./docs/publishing.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hraness
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,165 @@
-# Temporary Holding Version
+# dawg
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+dawg is a local-first terminal music workstation with an agent-driven piano roll. Run `dawg` in a project directory, open it in more than one terminal window, and each window can focus on a different track in the same composition.
+
+The highway sits above a multiline prompt. Notes stream toward a hit line, sustains stretch across beats, and transport controls stay live while you ask the agent to add or reshape music. The session is stored locally in `.dawg`, so there is no account, login, hosted session, or required service for the core workflow.
+
+## Install
+
+dawg requires [Bun](https://bun.sh) 1.3.14 or newer. Install it with the script from [dawg.sh](https://dawg.sh):
+
+```sh
+curl -fsSL https://dawg.sh/install | sh
+```
+
+or install the release tarball from GitHub directly:
+
+```sh
+bun add -g https://github.com/hraness/dawg/releases/download/v0.2.0/hraness-dawg-0.2.0.tgz
+dawg --help
+```
+
+Each [release](https://github.com/hraness/dawg/releases) is immutable and ships the tarball, a `SHA256SUMS` file and a build provenance attestation. To check a download before installing it:
+
+```sh
+gh release download v0.2.0 --repo hraness/dawg
+shasum -a 256 -c SHA256SUMS
+gh attestation verify hraness-dawg-0.2.0.tgz --repo hraness/dawg
+bun add -g "$PWD/hraness-dawg-0.2.0.tgz"
+```
+
+dawg is not published to npm yet. To run from source instead:
+
+```sh
+git clone https://github.com/hraness/dawg.git
+cd dawg
+bun install --frozen-lockfile
+bun run dawg
+```
+
+Running `dawg` creates `.dawg/session` when needed and attaches to that session on later launches. Use `dawg --new` for a new composition, `dawg --session <name|id>` to attach explicitly, or `dawg --track bass` to focus a named track.
+
+### Sessions
+
+Every window you open on a session takes the first track no other window has focused, in score order. Open three terminals on a three-track session and each one restores a different instrument. A fourth window gets a draft track (`track-4`, "all tracks open · new track") that is added to the score on its first edit, so idle windows never clutter the song. `--track` always wins over auto-claim.
+
+Sessions have names. A new session starts as `untitled` and is named automatically from what you play (`a minor bass groove`, `dusty basement funk`). `/rename <name>` sets your own name and stops auto-naming for good; `/rename --auto` hands it back. A user rename always beats an auto-name that was still in flight, and every window updates. `/fork [name]` snapshots the current song into a new session (`night drive` → `night drive 2` → `night drive 3`; a fork of `night drive 2` is `night drive 3`) and switches this window to it. `/sessions` lists recent sessions, `/resume` opens a picker (↑/↓, Enter, Esc) and `/resume <n|name|id>` switches directly. Undo in a fork steps back past the fork point into the parent's history. `dawg sessions` prints the same list from the shell.
+
+Auto-naming is cheap. dawg keeps a local musical fingerprint (tempo, key estimate, instruments, register, density and effects) and only asks a model when the music actually changed, at most once every few turns, after three quiet seconds. The request is about 120 tokens in and 12 out through the configured provider (gateway `anthropic/claude-haiku-4.5`, or xcb), runs in the background so it never blocks the prompt, and falls back to a local name such as `96 bpm drums` when offline or with `DAWG_AI=0`. In tests a typical 10-prompt session makes 2–3 naming calls.
+
+## Use
+
+The first steel thread understands direct requests:
+
+```text
+add C4 at 0 for 1
+play
+pause
+tempo 128
+instrument piano
+volume 0.7
+pan -0.4
+automate volume at 0 0.2
+automate volume at 4 1
+automate pan at 0 -1
+automate pan at 4 1
+track drums
+instrument kit
+hit kick at 0
+hit snare at 1 vel 0.7
+pattern kick 0 1 2 3
+pattern hat every 0.5 from 0.25
+clear hat
+filter 1200
+filter 800 0.6
+filter off
+delay 0.375 0.3
+delay 0.75 0.4 0.5
+delay off
+reverb 0.3
+reverb 0.4 0.8
+reverb off
+automate filter at 0 400
+automate filter at 4 6000
+automate resonance at 0 0.2
+automate delay-feedback at 0 0.6
+automate delay-mix at 4 0
+clear filter automation
+bars 8
+extend 4 bars
+clear automation
+mute
+solo
+unsolo
+clear
+undo
+redo
+move note <id> to 2.5
+duration note <id> 0.25
+/export loop.track.json
+/import loop.track.json
+/model opus-5.5
+```
+
+A track named `drums` (or `kit`) starts with the `kit` instrument; `instrument kit` turns any track into a drum track. Drum voices are `kick` (`bd`), `snare` (`sd`), `clap` (`cp`), `rim` (`perc`), `tom`, `hat` (`hh`), and `openhat` (`oh`); the highway shows one lane per voice. `pattern <voice> <beats...>` takes up to 64 beats, `pattern <voice> every <step>` (step ≥ 0.125) fills the loop, `vel <0..1>` sets velocity, and `clear <voice>` removes only that voice. `filter <hz> [resonance]` is a per-track low-pass (20–20000 Hz, resonance 0–1), `delay <beats> [feedback] [mix]` is a tempo-synced stereo ping-pong echo send (0.0625–4 beats, feedback ≤ 0.9, mix 0–1), `reverb <mix> [size]` is an algorithmic stereo reverb send (mix 0–1, size 0–1, default 0.5; `reverb off` removes it), and `automate filter|resonance|delay-feedback|delay-mix at <beat> <value>` writes the cutoff (Hz), resonance (0–1), delay feedback (0–0.9) and delay mix (0–1) lanes. `solo` isolates the focused track in playback across every window; `redo` re-applies the last undone edit.
+
+The screen has four parts. A one-line header shows track · session · ▶/⏸ BPM · key · model · revision · sync state. The highway overlays every unmuted track, each in its own stable accent, with the focused track bright and the others dimmed; `/view focus` shows only the focused track and `/view all` (the default) brings the rest back. Below it, an activity strip shows operation cards (`✓ +8 bass notes · rev 41→42 · ^z undo`), queue depth, a braille spinner while the agent works, and errors in red with an `✗` prefix. The prompt panel is filled with a background color. It wraps by grapheme, grows from 1 to 8 rows (capped at 30% of the screen, then scrolls internally) and keeps the draft when the terminal is resized. Narrow terminals collapse the header and hints, and below 24×8 the screen shows a resize hint.
+
+| Key                  | Action                                                                       |
+| -------------------- | ---------------------------------------------------------------------------- |
+| Space (empty prompt) | play / pause                                                                 |
+| Enter                | submit (STEER) or queue (QUEUE mode)                                         |
+| Shift+Enter, Ctrl+J  | newline                                                                      |
+| Alt+Enter            | queue this prompt                                                            |
+| Ctrl+Q               | toggle the STEER / QUEUE mode pill                                           |
+| Ctrl+Z / Ctrl+Y      | undo / redo                                                                  |
+| Ctrl+O or `/log`     | transcript overlay: ↑/↓, PgUp/PgDn scroll, `/` filters requests, ops, errors |
+| Esc                  | cancel the agent turn, close the overlay, or clear the draft                 |
+| Ctrl+L               | full redraw                                                                  |
+| Ctrl+C               | exit                                                                         |
+
+A STEER submit runs ahead of queued work. Bracketed paste preserves multiline input.
+
+`/theme default|high-contrast|mono` and `--theme <name>` (or `DAWG_THEME`) pick a theme. Semantic color tokens map to truecolor, 256, 16 or no color. `NO_COLOR` and `TERM=dumb` force monochrome. `/motion off`, `--reduce-motion` or `DAWG_REDUCE_MOTION=1` replace animations with static states in the same positions. Every color has a non-color cue as well: glyph density, `✓`/`✗`/`!` prefixes, the mode pill text and `▶`/`⏸`.
+
+## Auth
+
+Run `dawg login` once to give the agent a model. With the Vercel CLI it signs you in (if needed) and creates an AI Gateway key named `dawg-<hostname>`; `--budget <dollars>` sets its spend limit. Without the CLI it prints `bun add -g vercel` and lets you paste a key instead (`dawg login --key`, hidden input, Enter opens the key page).
+
+- `dawg login --xcb` uses a Claude, Codex or Devin subscription through [xcb](https://github.com/hraness/xcb) (`curl -fsSL https://xcb.sh/install.sh | sh`). It lists the accounts that `xcb --json generate --capabilities` reports as available and saves your pick; inside the TUI, `/login --xcb` opens the same choice as a picker of accounts and models. An account whose admission xcb reports as `pending` counts as available, and its first turn shows `admitting account…` while xcb admits it. The provider is re-resolved when `~/.config/dawg` credentials or config change, so a login in another terminal applies on the next turn. An account only appears after xcb's [application qualification](https://github.com/hraness/xcb/blob/main/docs/application-api.md); if none qualify, the command prints the read-only `xcb --json qualify-application --inspect` line for each connected account.
+- `dawg auth status` (or `/auth` in the TUI; `--check` verifies the key online) shows the provider, a masked key such as `vck_…abcd` and its source, plus the audio backend. `dawg logout` removes the stored key and the provider choice. `/login` works in the TUI too; flows that need hidden input or a browser tell you to use a shell.
+- Keys go to the macOS Keychain (service `dawg`, account `ai-gateway`, passed to `security -i` on stdin so the key never appears in a process list) or to `~/.config/dawg/credentials.json` (0600, directory 0700). They are never written to `.dawg/`. `AI_GATEWAY_API_KEY` in the environment always wins. `DAWG_CREDENTIAL_STORE=file` skips the Keychain and `DAWG_CONFIG_DIR` moves the config directory.
+- `DAWG_PROVIDER=gateway|xcb|auto` overrides the saved choice. `auto` (the default) uses the gateway when a key exists, then an available xcb account, otherwise direct commands only with a hint to run `dawg login`. `DAWG_AI=0` turns the agent off. The header shows the active provider, for example `opus-5.5 · gateway` or `devin/swe-2-high · xcb`.
+
+On the gateway, unrecognized requests go to a streaming, tool-calling agent. Choose `DAWG_MODEL=opus-5.5` or `DAWG_MODEL=sol-6.1`, or switch with `/model`. By default these labels map to `anthropic/claude-opus-5.5` and `openai/gpt-6.1-sol` from the gateway catalog. Override them with `DAWG_OPUS_MODEL` and `DAWG_SOL_MODEL`. Other labels are rejected. xcb has no tool calling, so dawg asks for one JSON object of ops per call and runs each op through the same checks; it retries with diagnostics up to 3 calls per turn.
+
+The agent edits the score only through typed tools: `add_notes`, `add_drums`, `remove_notes`, `update_notes`, `set_instrument`, `set_mix` (with solo), `set_effects` (filter, delay and reverb), `set_automation` (volume, pan, filter cutoff and resonance, delay feedback and mix), `extend_loop`, `set_tempo`, `create_track`, `transport` and `explain`. Each call is validated, then committed as its own revision, and the status line shows its result (for example `✓ +8 bass notes`). While the agent is working, Esc cancels and keeps every change accepted so far. Enter sends a steering message that the agent reads at its next step. A queued submit (Ctrl+Q queue mode) waits until the turn ends.
+
+Playback renders deterministic stereo PCM with sine, piano, pluck, bass, saw, square, and triangle voices plus a synthesized drum kit (pitch-swept sine kick, seeded-noise snare and hats), applies per-track volume, equal-power pan (-1 left to 1 right), low-pass filter, ping-pong delay, and a Freeverb-style reverb, and honors mute and solo. Renders are byte-identical across runs. Playback is gapless: one long-lived player (`ffplay`, else SoX `play`) reads a seamless loop as raw PCM on stdin, and edits, tempo changes and seeks swap the buffer in place at the current position without restarting it, so the transport stays aligned with what you hear. On macOS without either, `afplay` replays a re-rendered loop on each edit. `dawg auth status` shows the backend; `DAWG_AUDIO_BACKEND=ffplay|sox|afplay|none` forces one, `DAWG_AUDIO_PLAYER="cmd {rate} {channels}"` streams to any stdin player, and `DAWG_AUDIO=0` runs headless. `dawg --export file.track.json` and `dawg --import file.track.json` exchange the bounded `track.loop/v1` document. `dawg render out.wav` writes the current session (or `--session <name|id>`, or `--import file.track.json`) to a WAV through the same renderer, without starting dawgd or playing audio; the same score always produces the same bytes, and the command prints the file's sha256. `/status` prints the session name, revision, composition digest and connection mode. `DAWG_DEMO=1 bun run src/main.ts` prints a deterministic renderer frame for development.
+
+## Architecture
+
+- `core/` defines the bounded immutable `track.loop/v1` score and operations.
+- `src/session/` provides an append-only local event log, atomic snapshots, and `dawgd`: one local daemon per session (`src/daemon.ts`), started automatically by the first window. Windows connect over a Unix socket, send idempotent intents, and receive accepted changes, presence, and one shared transport clock. If the daemon cannot start, windows fall back to the file-lock path and say so in the status line. `dawg sessions` lists the workspace's sessions with revision, update time, and live daemon.
+- `src/agent/` runs the bounded streaming tool-calling agent: the SSE gateway client, the tool registry, the composition brief, and operation validation.
+- `src/audio/` owns the transport clock, deterministic instrument-bank WAV rendering, and per-session playback lock. When `dawgd` is running it is the only process that plays audio.
+- `tui/` owns terminal capability detection, semantic colors, animation phases, piano-roll rendering, and the multiline prompt editor.
+
+The runtime is intentionally adapter-shaped. The local synthesizer is deterministic and works without a sound device; native or sample-backed players can replace it behind the same score boundary.
+
+See [DAWG.md](./DAWG.md) for the detailed command and interaction contract.
+
+## Development
+
+```sh
+bun install --frozen-lockfile
+bun run check
+```
+
+`bun run check` includes `test/e2e.test.ts`, which drives real `dawg` processes in real PTYs against a temporary workspace and a live dawgd: three windows converging on one revision and digest, shared transport, rename, auto-claim and drafts, undo and redo across windows, fork, `kill -9` recovery and a deterministic render. It needs no network or credentials. See [CHANGELOG.md](./CHANGELOG.md) for release history.
+
+## Release
+
+Bump `version` in `package.json` and add its section to `CHANGELOG.md` in a pull request, then merge it. When Check passes on `main`, the annotated `v<version>` tag, the immutable GitHub Release (tarball, `SHA256SUMS` and a provenance attestation) and the npm publish of `@hraness/dawg` follow automatically. See [docs/publishing.md](./docs/publishing.md).
+
+dawg is MIT licensed. Contributions should preserve bounded inputs, deterministic score operations, local session safety, and a working terminal fallback when color or animation is unavailable.

package/core/drums.ts

@@ -0,0 +1,102 @@
+/**
+ * Drum vocabulary shared by the parser, renderer, highway, and planner.
+ *
+ * A drum track is an ordinary track whose instrument is a kit (`kit`,
+ * `drums`, `drum`, or `drumkit`). Its notes keep the score's MIDI `pitch`
+ * field, using General MIDI percussion numbers to select a voice, so drum
+ * hits round-trip through `track.loop/v1` without a new note shape.
+ */
+
+export type DrumVoice =
+  "kick" | "snare" | "clap" | "rim" | "tom" | "hat" | "openhat";
+
+export type DrumVoiceInfo = Readonly<{
+  voice: DrumVoice;
+  pitch: number;
+  label: string;
+}>;
+
+/** Ordered left to right as highway lanes. */
+export const DRUM_VOICES: readonly DrumVoiceInfo[] = Object.freeze([
+  Object.freeze({ voice: "kick", pitch: 36, label: "kick" }),
+  Object.freeze({ voice: "snare", pitch: 38, label: "snare" }),
+  Object.freeze({ voice: "clap", pitch: 39, label: "clap" }),
+  Object.freeze({ voice: "rim", pitch: 37, label: "rim" }),
+  Object.freeze({ voice: "tom", pitch: 45, label: "tom" }),
+  Object.freeze({ voice: "hat", pitch: 42, label: "hat" }),
+  Object.freeze({ voice: "openhat", pitch: 46, label: "open" }),
+] as const);
+
+export const DRUM_INSTRUMENTS = Object.freeze([
+  "kit",
+  "drums",
+  "drum",
+  "drumkit",
+] as const);
+
+const VOICE_ALIASES: Readonly<Record<string, DrumVoice>> = Object.freeze({
+  kick: "kick",
+  bd: "kick",
+  snare: "snare",
+  sd: "snare",
+  clap: "clap",
+  cp: "clap",
+  rim: "rim",
+  rimshot: "rim",
+  perc: "rim",
+  tom: "tom",
+  lt: "tom",
+  hat: "hat",
+  hh: "hat",
+  hihat: "hat",
+  "hi-hat": "hat",
+  closedhat: "hat",
+  "closed-hat": "hat",
+  chh: "hat",
+  openhat: "openhat",
+  "open-hat": "openhat",
+  ohh: "openhat",
+  oh: "openhat",
+  open: "openhat",
+});
+
+/** Extra General MIDI numbers folded onto the nearest local voice. */
+const PITCH_ALIASES: Readonly<Record<number, DrumVoice>> = Object.freeze({
+  35: "kick",
+  40: "snare",
+  41: "tom",
+  43: "tom",
+  44: "hat",
+  47: "tom",
+  48: "tom",
+  50: "tom",
+});
+
+export function isDrumInstrument(instrument: string | undefined): boolean {
+  if (typeof instrument !== "string") return false;
+  return (DRUM_INSTRUMENTS as readonly string[]).includes(
+    instrument.trim().toLowerCase(),
+  );
+}
+
+export function parseDrumVoice(value: string): DrumVoice | undefined {
+  return VOICE_ALIASES[value.trim().toLowerCase()];
+}
+
+export function drumVoicePitch(voice: DrumVoice): number {
+  return DRUM_VOICES.find((info) => info.voice === voice)!.pitch;
+}
+
+/** Any MIDI pitch resolves to a voice; unknown numbers play as `rim`. */
+export function drumVoiceForPitch(pitch: number): DrumVoice {
+  return (
+    DRUM_VOICES.find((info) => info.pitch === pitch)?.voice ??
+    PITCH_ALIASES[pitch] ??
+    "rim"
+  );
+}
+
+export function drumLane(pitch: number): number {
+  const voice = drumVoiceForPitch(pitch);
+  return DRUM_VOICES.findIndex((info) => info.voice === voice);
+}

package/core/loop.ts

@@ -0,0 +1,78 @@
+import {
+  SCORE_VERSION,
+  TrackScore,
+  ScoreValidationError,
+  scoreFromJSON,
+  type Note,
+  type Track,
+} from "./score.ts";
+
+export const LOOP_FORMAT = "track.loop/v1" as const;
+
+export type TrackLoopV1 = Readonly<{
+  format: typeof LOOP_FORMAT;
+  version: typeof SCORE_VERSION;
+  tempoBpm: number;
+  beatsPerBar: number;
+  bars: number;
+  ticksPerBeat: number;
+  key: string | null;
+  tracks: readonly Track[];
+  notes: readonly Note[];
+}>;
+
+/** Return the stable object form used by files and IPC messages. */
+export function encodeLoopDocument(score: TrackScore): TrackLoopV1 {
+  if (!(score instanceof TrackScore))
+    throw new ScoreValidationError("encodeLoop requires a TrackScore");
+  return Object.freeze({
+    format: LOOP_FORMAT,
+    version: SCORE_VERSION,
+    tempoBpm: score.tempoBpm,
+    beatsPerBar: score.beatsPerBar,
+    bars: score.bars,
+    ticksPerBeat: score.ticksPerBeat,
+    key: score.key,
+    tracks: score.tracks,
+    notes: score.notes,
+  });
+}
+
+/** Encode with deterministic property and note ordering. */
+export function encodeLoop(score: TrackScore): string {
+  return JSON.stringify(encodeLoopDocument(score));
+}
+
+export function decodeLoopDocument(value: unknown): TrackScore {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new ScoreValidationError("track.loop/v1 must be an object");
+  }
+  const envelope = value as Record<string, unknown>;
+  if (envelope.format !== LOOP_FORMAT)
+    throw new ScoreValidationError(
+      `unsupported loop format: ${String(envelope.format)}`,
+    );
+  if (envelope.version !== SCORE_VERSION)
+    throw new ScoreValidationError(
+      `unsupported loop version: ${String(envelope.version)}`,
+    );
+  return scoreFromJSON(envelope);
+}
+
+export function decodeLoop(serialized: unknown): TrackScore {
+  let value: unknown = serialized;
+  if (typeof serialized === "string") {
+    try {
+      value = JSON.parse(serialized) as unknown;
+    } catch (error) {
+      throw new ScoreValidationError(
+        `invalid track.loop/v1 JSON: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+  return decodeLoopDocument(value);
+}
+
+// Explicit aliases make the format boundary easy to discover from callers.
+export const encodeTrackLoop = encodeLoop;
+export const decodeTrackLoop = decodeLoop;