@mcptoolshop/claude-sfx 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-03-19
+
+### Added
+- **Streak awareness** — consecutive successful plays build intensity (1-5), adding harmonic layers, frequency lift, FM shimmer, and gain boost as momentum builds
+- **Error escalation** — consecutive errors progressively increase urgency (1-5), with deeper frequency drops, wider detuning, tremolo, and longer decay
+- **Completion fanfare** — session end sound is outcome-aware: triumphant ascending chord for great sessions (80%+ success), muted resolution for rough ones, standard chime for normal
+- New `--intensity` and `--escalation` flags for `play` command
+- `demo` command now showcases intensity levels 1-5 and error escalation 1-5
+- `export` command now includes intensity variants, escalation variants, fanfare, and muted end WAVs
+- New `streak.ts` module for tracking session momentum and error runs
+- 40 new tests (192 total)
+
+### Fixed
+- Ambient drone now self-terminates after 30 minutes (prevents orphaned loops)
+- Stale ambient PID/WAV files cleaned up on detection
+- Hook and player timeout reduced from 5s to 3s (sounds are 80-320ms)
+- npm audit now blocks CI on known vulnerabilities (removed `|| true`)
+- CI coverage thresholds enforced (80% lines/functions/statements, 70% branches)
+- SCORECARD.md filled with actual audit gate results
+
 ## [1.0.0] - 2026-02-27
 
 ### Added

package/README.md

@@ -1,7 +1,7 @@
-<p align="center">
-  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
-</p>
-
+<p align="center">
+  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
+</p>
+
 <p align="center">
   <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/claude-sfx/readme.jpg" width="400" alt="Claude-SFX">
 </p>
@@ -58,8 +58,42 @@ claude-sfx play navigate --status warn    # tremolo ping
 claude-sfx play sync --direction up       # rising whoosh (push)
 claude-sfx play sync --direction down     # falling whoosh (pull)
 claude-sfx play intake --scope remote     # longer tail (distance feel)
+claude-sfx play commit --intensity 5      # full streak momentum
+claude-sfx play execute --status err --escalation 4  # urgent repeated error
 ```
 
+### Streak Awareness
+
+Sounds evolve with momentum. Consecutive successful tool calls build a streak that adds harmonic richness — your productive session *sounds* productive.
+
+| Streak | Intensity | Effect |
+|---|---|---|
+| 1 play | Level 1 | Clean base tone |
+| 3+ plays | Level 2 | Subtle octave harmonic |
+| 6+ plays | Level 3 | Harmonic + brighter frequency |
+| 10+ plays | Level 4 | FM shimmer added |
+| 15+ plays | Level 5 | Full richness — session is cooking |
+
+Streaks reset after 30 seconds of idle or on any error.
+
+### Error Escalation
+
+Repeated errors get progressively more urgent — so you know something is stuck without reading the output.
+
+| Consecutive Errors | Escalation | Effect |
+|---|---|---|
+| 1st error | Level 1 | Standard error tone (detuned, dropped pitch) |
+| 2nd error | Level 2 | Deeper frequency drop + more detuning |
+| 3rd error | Level 3 | Tremolo added (audible "wobble") |
+| 4th error | Level 4 | Wide detuning, slower tremolo, longer decay |
+| 5th+ error | Level 5 | Max urgency — deep, heavy, lingering |
+
+Resets on any successful play.
+
+### Completion Fanfare
+
+Session end sounds are outcome-aware. A great session (80%+ success rate, 5+ plays) gets a triumphant ascending chord. A rough session gets a muted, subdued resolution. Short sessions get the standard chime.
+
 ### Smart Bash Detection
 
 The hook handler inspects Bash commands to pick the right sound:
@@ -177,7 +211,7 @@ Zero audio files. Every sound is synthesized at runtime from math:
 - **Frequency sweeps** — linear interpolation for movement
 - **Loudness limiter** — soft-knee compression, hard ceiling
 
-The entire package is ~2,800 lines of TypeScript with zero production dependencies. Sounds are generated as PCM buffers, encoded to WAV in memory, and played through the OS native audio player (PowerShell on Windows, afplay on macOS, aplay on Linux).
+Sounds adapt over time through **streak awareness** (momentum builds harmonic layers), **error escalation** (repeated failures increase urgency), and **completion fanfare** (session outcome shapes the closing chord). The entire package is pure TypeScript with zero production dependencies. Sounds are generated as PCM buffers, encoded to WAV in memory, and played through the OS native audio player (PowerShell on Windows, afplay on macOS, aplay on Linux).
 
 ## Security & Privacy
 

package/dist/ambient.js

@@ -16,12 +16,15 @@ import { encodeWav } from "./synth.js";
 import { playSync } from "./player.js";
 const PID_FILE = join(tmpdir(), "claude-sfx-ambient.pid");
 const DRONE_WAV = join(tmpdir(), "claude-sfx-drone.wav");
+/** Max ambient lifetime in seconds — kills orphaned drones. */
+const MAX_LIFETIME_S = 30 * 60; // 30 minutes
 /** Check if an ambient drone is currently running. */
 export function isAmbientRunning() {
     if (!existsSync(PID_FILE))
         return false;
     try {
-        const pid = parseInt(readFileSync(PID_FILE, "utf-8").trim(), 10);
+        const raw = readFileSync(PID_FILE, "utf-8").trim();
+        const pid = parseInt(raw.split("\n")[0], 10);
         // Check if process is alive (signal 0 = existence check)
         process.kill(pid, 0);
         return true;
@@ -32,6 +35,10 @@ export function isAmbientRunning() {
             unlinkSync(PID_FILE);
         }
         catch { /* ignore */ }
+        try {
+            unlinkSync(DRONE_WAV);
+        }
+        catch { /* ignore */ }
         return false;
     }
 }
@@ -51,28 +58,28 @@ export function startAmbient(profile) {
     const platform = process.platform;
     let child;
     if (platform === "win32") {
-        // PowerShell loop: plays the WAV repeatedly until killed
+        // PowerShell loop: plays the WAV repeatedly until killed or max lifetime reached
         child = spawn("powershell", [
             "-NoProfile",
             "-Command",
-            `while($true){(New-Object Media.SoundPlayer '${DRONE_WAV}').PlaySync()}`,
+            `$start=[DateTime]::UtcNow; while(([DateTime]::UtcNow-$start).TotalSeconds -lt ${MAX_LIFETIME_S}){(New-Object Media.SoundPlayer '${DRONE_WAV}').PlaySync()}`,
         ], {
             stdio: "ignore",
             detached: true,
         });
     }
     else if (platform === "darwin") {
-        // macOS: loop with afplay
+        // macOS: loop with afplay, self-terminates after max lifetime
         child = spawn("bash", [
             "-c",
-            `while true; do afplay "${DRONE_WAV}"; done`,
+            `END=$((SECONDS+${MAX_LIFETIME_S})); while [ $SECONDS -lt $END ]; do afplay "${DRONE_WAV}"; done`,
         ], {
             stdio: "ignore",
             detached: true,
         });
     }
     else {
-        // Linux: loop with aplay/paplay
+        // Linux: loop with aplay/paplay, self-terminates after max lifetime
         const player = (() => {
             try {
                 execSync("which paplay", { stdio: "ignore" });
@@ -84,7 +91,7 @@ export function startAmbient(profile) {
         })();
         child = spawn("bash", [
             "-c",
-            `while true; do ${player} "${DRONE_WAV}"; done`,
+            `END=$((SECONDS+${MAX_LIFETIME_S})); while [ $SECONDS -lt $END ]; do ${player} "${DRONE_WAV}"; done`,
         ], {
             stdio: "ignore",
             detached: true,

package/dist/cli.js

@@ -3,7 +3,7 @@
  * claude-sfx CLI
  * Procedural audio feedback for Claude Code.
  */
-import { ALL_VERBS, VERB_LABELS, VERB_DESCRIPTIONS, generateVerb, generateSessionStart, generateSessionEnd, generateAmbientResolve, } from "./verbs.js";
+import { ALL_VERBS, VERB_LABELS, VERB_DESCRIPTIONS, generateVerb, generateSessionStart, generateSessionEnd, generateSessionEndWithOutcome, generateAmbientResolve, } from "./verbs.js";
 import { concatBuffers, applyVolume } from "./synth.js";
 import { playSync, saveWav } from "./player.js";
 import { resolveProfile, listBuiltinProfiles, } from "./profiles.js";
@@ -90,6 +90,20 @@ function cmdDemo(flags) {
             console.log("  [no audio output available]");
         }
     }
+    console.log("\n  Streak intensity (commit at levels 1-5):\n");
+    for (let i = 1; i <= 5; i++) {
+        process.stdout.write(`    Level ${i}   `);
+        const buf = generateVerb(profile, "commit", { intensity: i });
+        const r = playSync(buf);
+        console.log(r.played ? `(${r.durationMs}ms)` : "[no audio]");
+    }
+    console.log("\n  Error escalation (execute at levels 1-5):\n");
+    for (let i = 1; i <= 5; i++) {
+        process.stdout.write(`    Level ${i}   `);
+        const buf = generateVerb(profile, "execute", { status: "err", escalation: i });
+        const r = playSync(buf);
+        console.log(r.played ? `(${r.durationMs}ms)` : "[no audio]");
+    }
     console.log("\n  Session sounds:\n");
     process.stdout.write("    Start     boot chime");
     const startResult = playSync(generateSessionStart(profile));
@@ -97,6 +111,12 @@ function cmdDemo(flags) {
     process.stdout.write("    End       closure");
     const endResult = playSync(generateSessionEnd(profile));
     console.log(endResult.played ? `  (${endResult.durationMs}ms)` : "  [no audio]");
+    process.stdout.write("    Fanfare   great session");
+    const fanfareResult = playSync(generateSessionEndWithOutcome(profile, { successRatio: 1, totalPlays: 20 }));
+    console.log(fanfareResult.played ? `  (${fanfareResult.durationMs}ms)` : "  [no audio]");
+    process.stdout.write("    Muted     rough session");
+    const mutedResult = playSync(generateSessionEndWithOutcome(profile, { successRatio: 0.3, totalPlays: 20 }));
+    console.log(mutedResult.played ? `  (${mutedResult.durationMs}ms)` : "  [no audio]");
     process.stdout.write("    Resolve   stinger");
     const resolveResult = playSync(generateAmbientResolve(profile));
     console.log(resolveResult.played ? `  (${resolveResult.durationMs}ms)` : "  [no audio]");
@@ -152,6 +172,22 @@ function cmdPlay(positional, flags) {
         }
         options.direction = flags.direction;
     }
+    if (flags.intensity) {
+        const n = parseInt(flags.intensity, 10);
+        if (isNaN(n) || n < 1 || n > 5) {
+            console.error(`  Error: invalid intensity "${flags.intensity}". Use: 1-5`);
+            process.exit(1);
+        }
+        options.intensity = n;
+    }
+    if (flags.escalation) {
+        const n = parseInt(flags.escalation, 10);
+        if (isNaN(n) || n < 1 || n > 5) {
+            console.error(`  Error: invalid escalation "${flags.escalation}". Use: 1-5`);
+            process.exit(1);
+        }
+        options.escalation = n;
+    }
     let buffer = generateVerb(profile, verb, options);
     // Apply volume
     const gain = volumeToGain(config.volume);
@@ -448,17 +484,33 @@ function cmdExport(positional, flags) {
             console.log(`    ${filename}`);
         }
     }
+    // Intensity variants (commit at levels 1-5)
+    for (let i = 1; i <= 5; i++) {
+        const filename = `commit-intensity-${i}.wav`;
+        saveWav(generateVerb(profile, "commit", { intensity: i }), join(outputDir, filename));
+        console.log(`    ${filename}`);
+    }
+    // Escalation variants (execute-err at levels 1-5)
+    for (let i = 1; i <= 5; i++) {
+        const filename = `execute-err-escalation-${i}.wav`;
+        saveWav(generateVerb(profile, "execute", { status: "err", escalation: i }), join(outputDir, filename));
+        console.log(`    ${filename}`);
+    }
     saveWav(generateSessionStart(profile), join(outputDir, "session-start.wav"));
     console.log("    session-start.wav");
     saveWav(generateSessionEnd(profile), join(outputDir, "session-end.wav"));
     console.log("    session-end.wav");
+    saveWav(generateSessionEndWithOutcome(profile, { successRatio: 1, totalPlays: 20 }), join(outputDir, "session-fanfare.wav"));
+    console.log("    session-fanfare.wav");
+    saveWav(generateSessionEndWithOutcome(profile, { successRatio: 0.3, totalPlays: 20 }), join(outputDir, "session-muted.wav"));
+    console.log("    session-muted.wav");
     saveWav(generateAmbientResolve(profile), join(outputDir, "ambient-resolve.wav"));
     console.log("    ambient-resolve.wav");
     const demoBuffers = ALL_VERBS.map((v) => generateVerb(profile, v));
     const demoSequence = concatBuffers(demoBuffers, 0.3);
     saveWav(demoSequence, join(outputDir, "demo-sequence.wav"));
     console.log("    demo-sequence.wav");
-    const fileCount = ALL_VERBS.length * statuses.length + 4 + 3 + 1;
+    const fileCount = ALL_VERBS.length * statuses.length + 4 + 5 + 5 + 4 + 1;
     console.log(`\n  Exported ${fileCount} files.\n`);
 }
 // --- Init / Uninstall ---
@@ -534,6 +586,8 @@ function cmdHelp() {
     --status <ok|err|warn>          Status modifier
     --scope <local|remote>          Scope modifier
     --direction <up|down>           Direction (move/sync verbs)
+    --intensity <1-5>               Streak intensity (harmonic layering)
+    --escalation <1-5>              Error escalation (urgency level)
     --profile <name|path>           Sound profile (default: minimal)
     --force                         Bypass guard (debounce/rate/mute)
     --debug                         Show stack traces on errors

package/dist/hook-handler.js

@@ -9,13 +9,14 @@
  *   echo '{"tool_name":"Read",...}' | claude-sfx hook-handler PostToolUse
  *   echo '{"session_id":"..."}' | claude-sfx hook-handler SessionStart
  */
-import { generateVerb, generateSessionStart, generateSessionEnd, } from "./verbs.js";
+import { generateVerb, generateSessionStart, generateSessionEndWithOutcome, } from "./verbs.js";
 import { applyVolume } from "./synth.js";
 import { playSync } from "./player.js";
 import { resolveProfile } from "./profiles.js";
 import { loadConfig, resolveProfileName, volumeToGain } from "./config.js";
 import { guardPlay } from "./guard.js";
 import { resolveAmbient, isAmbientRunning } from "./ambient.js";
+import { recordSuccess, recordError, getSessionOutcome, resetStreak } from "./streak.js";
 /** Map a PostToolUse tool_name to a verb + options. */
 export function mapToolToVerb(toolName, input) {
     // Exact matches first
@@ -111,6 +112,16 @@ function playVerb(verb, options = {}) {
     const guard = guardPlay(verb, config);
     if (!guard.allowed)
         return;
+    // Streak tracking — record success/error and get intensity/escalation
+    const isError = options.status === "err";
+    if (isError) {
+        const { escalation } = recordError();
+        options = { ...options, escalation };
+    }
+    else {
+        const { intensity } = recordSuccess(verb);
+        options = { ...options, intensity };
+    }
     const profileName = resolveProfileName(config);
     const profile = resolveProfile(profileName);
     let buffer = generateVerb(profile, verb, options);
@@ -126,8 +137,18 @@ function playSession(type) {
         return;
     const profileName = resolveProfileName(config);
     const profile = resolveProfile(profileName);
-    const gen = type === "start" ? generateSessionStart : generateSessionEnd;
-    let buffer = gen(profile);
+    let buffer;
+    if (type === "start") {
+        // Reset streak for new session
+        resetStreak();
+        buffer = generateSessionStart(profile);
+    }
+    else {
+        // Outcome-aware session end (fanfare or muted)
+        const outcome = getSessionOutcome();
+        buffer = generateSessionEndWithOutcome(profile, outcome);
+        resetStreak();
+    }
     const gain = volumeToGain(config.volume);
     if (gain < 1) {
         buffer = applyVolume(buffer, gain);

package/dist/hooks.js

@@ -39,7 +39,7 @@ export function generateHooksConfig() {
                     {
                         type: "command",
                         command: makeHookCommand(sfxBin, "SessionStart"),
-                        timeout: 5,
+                        timeout: 3,
                     },
                 ],
             },
@@ -52,7 +52,7 @@ export function generateHooksConfig() {
                     {
                         type: "command",
                         command: makeHookCommand(sfxBin, "PostToolUse"),
-                        timeout: 5,
+                        timeout: 3,
                     },
                 ],
             },
@@ -64,7 +64,7 @@ export function generateHooksConfig() {
                     {
                         type: "command",
                         command: makeHookCommand(sfxBin, "PostToolUseFailure"),
-                        timeout: 5,
+                        timeout: 3,
                     },
                 ],
             },
@@ -75,7 +75,7 @@ export function generateHooksConfig() {
                     {
                         type: "command",
                         command: makeHookCommand(sfxBin, "SubagentStart"),
-                        timeout: 5,
+                        timeout: 3,
                     },
                 ],
             },
@@ -86,7 +86,7 @@ export function generateHooksConfig() {
                     {
                         type: "command",
                         command: makeHookCommand(sfxBin, "SubagentStop"),
-                        timeout: 5,
+                        timeout: 3,
                     },
                 ],
             },
@@ -97,7 +97,7 @@ export function generateHooksConfig() {
                     {
                         type: "command",
                         command: makeHookCommand(sfxBin, "Stop"),
-                        timeout: 5,
+                        timeout: 3,
                     },
                 ],
             },

package/dist/player.js

@@ -63,7 +63,7 @@ export function playSync(buffer) {
         }
         execSync(`${cmd.command} ${cmd.args.map((a) => `"${a}"`).join(" ")}`, {
             stdio: "ignore",
-            timeout: 5000,
+            timeout: 3000,
         });
         return {
             played: true,

package/dist/streak.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Streak tracker — momentum and error escalation state.
+ *
+ * Tracks two independent counters persisted in a temp file:
+ *   - streak: consecutive successful plays → drives intensity (harmonic layering)
+ *   - errorRun: consecutive error-status plays → drives escalation (urgency)
+ *
+ * State resets:
+ *   - streak resets on error, on idle (30s gap), or on session end
+ *   - errorRun resets on success or on session end
+ */
+/** Maximum intensity level (caps harmonic layering). */
+export declare const MAX_INTENSITY = 5;
+/** Maximum error escalation level (caps urgency increase). */
+export declare const MAX_ESCALATION = 5;
+export interface StreakState {
+    /** Current streak count (consecutive successful plays). */
+    streak: number;
+    /** Current error run count (consecutive errors). */
+    errorRun: number;
+    /** Timestamp of last play (for idle detection). */
+    lastPlayAt: number;
+    /** Total successful plays this session (for fanfare). */
+    sessionSuccesses: number;
+    /** Total error plays this session (for fanfare). */
+    sessionErrors: number;
+}
+/** Read the current streak state from disk. */
+export declare function readStreak(): StreakState;
+/** Write streak state to disk. */
+export declare function writeStreak(state: StreakState): void;
+/**
+ * Record a successful play and return the current intensity level (1-5).
+ * Resets error run. Resets streak if idle too long.
+ */
+export declare function recordSuccess(verb: string): {
+    intensity: number;
+    state: StreakState;
+};
+/**
+ * Record an error play and return the current escalation level (1-5).
+ * Resets streak.
+ */
+export declare function recordError(): {
+    escalation: number;
+    state: StreakState;
+};
+/** Convert streak count to intensity level (1-5). */
+export declare function streakToIntensity(streak: number): number;
+/** Convert error run count to escalation level (1-5). */
+export declare function errorRunToEscalation(errorRun: number): number;
+/**
+ * Get session outcome for fanfare generation.
+ * Returns a ratio (0.0 = all errors, 1.0 = all successes) and total count.
+ */
+export declare function getSessionOutcome(): {
+    successRatio: number;
+    totalPlays: number;
+    successes: number;
+    errors: number;
+};
+/** Reset streak state (for session start or testing). */
+export declare function resetStreak(): void;

package/dist/streak.js

@@ -0,0 +1,116 @@
+/**
+ * Streak tracker — momentum and error escalation state.
+ *
+ * Tracks two independent counters persisted in a temp file:
+ *   - streak: consecutive successful plays → drives intensity (harmonic layering)
+ *   - errorRun: consecutive error-status plays → drives escalation (urgency)
+ *
+ * State resets:
+ *   - streak resets on error, on idle (30s gap), or on session end
+ *   - errorRun resets on success or on session end
+ */
+import { readFileSync, writeFileSync, existsSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+const STREAK_FILE = join(tmpdir(), "claude-sfx-streak.json");
+/** Idle timeout — streak resets if no play within this window. */
+const IDLE_TIMEOUT_MS = 30_000; // 30 seconds
+/** Maximum intensity level (caps harmonic layering). */
+export const MAX_INTENSITY = 5;
+/** Maximum error escalation level (caps urgency increase). */
+export const MAX_ESCALATION = 5;
+/** Intensity thresholds — streak count required for each intensity level. */
+const INTENSITY_THRESHOLDS = [1, 3, 6, 10, 15];
+function defaultState() {
+    return {
+        streak: 0,
+        errorRun: 0,
+        lastPlayAt: 0,
+        sessionSuccesses: 0,
+        sessionErrors: 0,
+    };
+}
+/** Read the current streak state from disk. */
+export function readStreak() {
+    if (!existsSync(STREAK_FILE))
+        return defaultState();
+    try {
+        const raw = readFileSync(STREAK_FILE, "utf-8");
+        const parsed = JSON.parse(raw);
+        return { ...defaultState(), ...parsed };
+    }
+    catch {
+        return defaultState();
+    }
+}
+/** Write streak state to disk. */
+export function writeStreak(state) {
+    writeFileSync(STREAK_FILE, JSON.stringify(state));
+}
+/**
+ * Record a successful play and return the current intensity level (1-5).
+ * Resets error run. Resets streak if idle too long.
+ */
+export function recordSuccess(verb) {
+    const state = readStreak();
+    const now = Date.now();
+    // Reset streak if idle too long
+    if (state.lastPlayAt > 0 && (now - state.lastPlayAt) > IDLE_TIMEOUT_MS) {
+        state.streak = 0;
+    }
+    state.streak++;
+    state.errorRun = 0;
+    state.lastPlayAt = now;
+    state.sessionSuccesses++;
+    writeStreak(state);
+    return { intensity: streakToIntensity(state.streak), state };
+}
+/**
+ * Record an error play and return the current escalation level (1-5).
+ * Resets streak.
+ */
+export function recordError() {
+    const state = readStreak();
+    const now = Date.now();
+    state.streak = 0;
+    state.errorRun++;
+    state.lastPlayAt = now;
+    state.sessionErrors++;
+    writeStreak(state);
+    return { escalation: errorRunToEscalation(state.errorRun), state };
+}
+/** Convert streak count to intensity level (1-5). */
+export function streakToIntensity(streak) {
+    let level = 1;
+    for (const threshold of INTENSITY_THRESHOLDS) {
+        if (streak >= threshold)
+            level++;
+    }
+    return Math.min(level, MAX_INTENSITY);
+}
+/** Convert error run count to escalation level (1-5). */
+export function errorRunToEscalation(errorRun) {
+    // Escalation is more aggressive: 1, 2, 3, 4, 5+
+    return Math.min(Math.max(errorRun, 1), MAX_ESCALATION);
+}
+/**
+ * Get session outcome for fanfare generation.
+ * Returns a ratio (0.0 = all errors, 1.0 = all successes) and total count.
+ */
+export function getSessionOutcome() {
+    const state = readStreak();
+    const total = state.sessionSuccesses + state.sessionErrors;
+    return {
+        successRatio: total > 0 ? state.sessionSuccesses / total : 1,
+        totalPlays: total,
+        successes: state.sessionSuccesses,
+        errors: state.sessionErrors,
+    };
+}
+/** Reset streak state (for session start or testing). */
+export function resetStreak() {
+    try {
+        unlinkSync(STREAK_FILE);
+    }
+    catch { /* ignore */ }
+}

package/dist/verbs.d.ts

@@ -10,6 +10,10 @@ export interface PlayOptions {
     status?: Status;
     scope?: Scope;
     direction?: Direction;
+    /** Streak intensity level (1-5). Higher = richer harmonics, momentum feel. */
+    intensity?: number;
+    /** Error escalation level (1-5). Higher = more urgent, dissonant error tone. */
+    escalation?: number;
 }
 export type Verb = "intake" | "transform" | "commit" | "navigate" | "execute" | "move" | "sync";
 export declare const VERB_LABELS: Record<Verb, string>;
@@ -19,6 +23,21 @@ export declare const ALL_VERBS: Verb[];
 export declare function generateVerb(profile: Profile, verb: Verb, options?: PlayOptions): Float64Array;
 export declare function generateSessionStart(profile: Profile): Float64Array;
 export declare function generateSessionEnd(profile: Profile): Float64Array;
+export interface SessionOutcome {
+    /** 0.0 = all errors, 1.0 = all successes */
+    successRatio: number;
+    /** Total plays in the session */
+    totalPlays: number;
+}
+/**
+ * Generate an outcome-aware session end sound.
+ *
+ * Great session (ratio >= 0.8, 5+ plays): triumphant ascending chord
+ * Good session (ratio >= 0.6): standard descending chime (existing behavior)
+ * Rough session (ratio < 0.6): muted, lower, shorter resolution
+ * Empty session (< 5 plays): standard chime (not enough data)
+ */
+export declare function generateSessionEndWithOutcome(profile: Profile, outcome: SessionOutcome): Float64Array;
 /** Generate a single chunk of the ambient thinking drone. */
 export declare function generateAmbientChunk(profile: Profile): Float64Array;
 /** Generate the resolution stinger (two ascending notes). */

package/dist/verbs.js

@@ -89,6 +89,119 @@ function applyWhooshScope(params, scope) {
     }
     return params;
 }
+// --- Intensity modifiers (streak-driven layering) ---
+/**
+ * Apply streak intensity to tone params.
+ * Level 1: clean (no change)
+ * Level 2: subtle octave harmonic
+ * Level 3: harmonic + slight frequency lift
+ * Level 4: richer harmonics + FM shimmer
+ * Level 5: full chord feel — harmonics + FM + slight gain boost
+ */
+function applyToneIntensity(params, intensity) {
+    if (intensity <= 1)
+        return params;
+    const p = { ...params };
+    if (intensity >= 2) {
+        p.harmonicGain = Math.max(p.harmonicGain ?? 0, 0.08 + (intensity - 2) * 0.04);
+    }
+    if (intensity >= 3) {
+        // Slight frequency lift — sounds "brighter" with momentum
+        p.frequency *= 1 + (intensity - 2) * 0.02;
+        if (p.frequencyEnd)
+            p.frequencyEnd *= 1 + (intensity - 2) * 0.02;
+    }
+    if (intensity >= 4) {
+        // Add FM shimmer for texture
+        p.fmRatio = p.fmRatio ?? 2;
+        p.fmDepth = Math.max(p.fmDepth ?? 0, 10 + (intensity - 4) * 8);
+    }
+    if (intensity >= 5) {
+        // Subtle gain boost — session is cooking
+        p.gain = Math.min(p.gain * 1.1, 0.9);
+    }
+    return p;
+}
+function applyWhooshIntensity(params, intensity) {
+    if (intensity <= 1)
+        return params;
+    const p = { ...params };
+    if (intensity >= 2) {
+        // Wider sweep range
+        p.freqEnd = Math.min(p.freqEnd * (1 + (intensity - 1) * 0.08), 8000);
+    }
+    if (intensity >= 3) {
+        // Tighter bandwidth = more defined whoosh
+        p.bandwidth = Math.max(p.bandwidth * 0.85, 0.3);
+    }
+    if (intensity >= 4) {
+        // Slightly longer — more dramatic
+        p.duration *= 1.05;
+    }
+    return p;
+}
+// --- Error escalation modifiers ---
+/**
+ * Progressive error escalation for tones.
+ * Level 1: standard error (same as status:err)
+ * Level 2: deeper frequency drop + more detuning
+ * Level 3: add tremolo (something is wrong)
+ * Level 4: wider detuning + slower tremolo (stuck)
+ * Level 5: max urgency — deep drop, heavy tremolo, long decay
+ */
+function applyToneEscalation(params, escalation) {
+    if (escalation <= 1)
+        return params;
+    const p = { ...params };
+    if (escalation >= 2) {
+        p.frequency *= 0.9;
+        if (p.frequencyEnd)
+            p.frequencyEnd *= 0.9;
+        p.detune = (p.detune ?? 0) + 2;
+    }
+    if (escalation >= 3) {
+        p.tremoloRate = 6;
+        p.tremoloDepth = 0.4;
+    }
+    if (escalation >= 4) {
+        p.detune = (p.detune ?? 0) + 3;
+        p.tremoloRate = 4;
+        p.tremoloDepth = 0.6;
+        p.duration *= 1.15;
+    }
+    if (escalation >= 5) {
+        p.frequency *= 0.85;
+        if (p.frequencyEnd)
+            p.frequencyEnd *= 0.85;
+        p.tremoloDepth = 0.75;
+        p.duration *= 1.2;
+        p.envelope = { ...p.envelope, release: p.envelope.release * 2 };
+    }
+    return p;
+}
+function applyWhooshEscalation(params, escalation) {
+    if (escalation <= 1)
+        return params;
+    const p = { ...params };
+    if (escalation >= 2) {
+        p.freqStart *= 0.7;
+        p.freqEnd *= 0.7;
+    }
+    if (escalation >= 3) {
+        p.bandwidth = Math.min(p.bandwidth * 1.5, 2);
+        p.duration *= 1.2;
+    }
+    if (escalation >= 4) {
+        p.duration *= 1.2;
+        p.envelope = { ...p.envelope, release: p.envelope.release * 1.5 };
+    }
+    if (escalation >= 5) {
+        p.freqStart *= 0.8;
+        p.freqEnd *= 0.8;
+        p.duration *= 1.15;
+    }
+    return p;
+}
 // --- Config → Params conversion ---
 function toneConfigToParams(cfg) {
     return {
@@ -129,6 +242,10 @@ export function generateVerb(profile, verb, options = {}) {
             wp = applyWhooshStatus(wp, options.status);
         if (options.scope)
             wp = applyWhooshScope(wp, options.scope);
+        if (options.intensity)
+            wp = applyWhooshIntensity(wp, options.intensity);
+        if (options.escalation)
+            wp = applyWhooshEscalation(wp, options.escalation);
         const whoosh = generateWhoosh(wp);
         // Tonal anchor (sync)
         if (cfg.tonalAnchor) {
@@ -151,6 +268,10 @@ export function generateVerb(profile, verb, options = {}) {
         params = applyToneStatus(params, options.status);
     if (options.scope)
         params = applyToneScope(params, options.scope);
+    if (options.intensity)
+        params = applyToneIntensity(params, options.intensity);
+    if (options.escalation)
+        params = applyToneEscalation(params, options.escalation);
     const primary = generateTone(params);
     // Noise burst layer (execute)
     if (cfg.noiseBurst) {
@@ -199,6 +320,94 @@ export function generateSessionStart(profile) {
 export function generateSessionEnd(profile) {
     return generateChime(profile.sessionEnd);
 }
+/**
+ * Generate an outcome-aware session end sound.
+ *
+ * Great session (ratio >= 0.8, 5+ plays): triumphant ascending chord
+ * Good session (ratio >= 0.6): standard descending chime (existing behavior)
+ * Rough session (ratio < 0.6): muted, lower, shorter resolution
+ * Empty session (< 5 plays): standard chime (not enough data)
+ */
+export function generateSessionEndWithOutcome(profile, outcome) {
+    // Not enough data — use standard chime
+    if (outcome.totalPlays < 5) {
+        return generateChime(profile.sessionEnd);
+    }
+    if (outcome.successRatio >= 0.8) {
+        // Triumphant: 3-note ascending chord (C5 → E5 → G5) with harmonics
+        return generateFanfare(profile);
+    }
+    if (outcome.successRatio < 0.6) {
+        // Rough session: lower, shorter, muted resolution
+        return generateMutedEnd(profile);
+    }
+    // Normal session: standard chime
+    return generateChime(profile.sessionEnd);
+}
+/** Triumphant 3-note ascending fanfare. */
+function generateFanfare(profile) {
+    const waveform = profile.sessionEnd.tone1.waveform;
+    // C5 → E5 → G5 (major triad ascending)
+    const notes = [523, 659, 784];
+    const buffers = [];
+    for (let i = 0; i < notes.length; i++) {
+        const isLast = i === notes.length - 1;
+        buffers.push(generateTone({
+            waveform,
+            frequency: notes[i],
+            duration: isLast ? 0.35 : 0.18,
+            envelope: {
+                attack: 0.01,
+                decay: isLast ? 0.12 : 0.06,
+                sustain: isLast ? 0.35 : 0.25,
+                release: isLast ? 0.12 : 0.05,
+            },
+            gain: isLast ? 0.55 : 0.45,
+            harmonicGain: isLast ? 0.15 : 0.08,
+        }));
+    }
+    // Stagger: each note starts 70ms after the previous
+    const stagger = Math.floor(0.07 * SAMPLE_RATE);
+    const totalLen = stagger * (buffers.length - 1) + buffers[buffers.length - 1].length;
+    const total = new Float64Array(totalLen);
+    for (let ni = 0; ni < buffers.length; ni++) {
+        const buf = buffers[ni];
+        const offset = ni * stagger;
+        for (let i = 0; i < buf.length; i++) {
+            if (offset + i < total.length) {
+                total[offset + i] += buf[i];
+            }
+        }
+    }
+    return limitLoudness(total);
+}
+/** Muted session end — lower pitch, shorter, subdued. */
+function generateMutedEnd(profile) {
+    const cfg = profile.sessionEnd;
+    const tone1 = generateTone({
+        waveform: cfg.tone1.waveform,
+        frequency: cfg.tone1.frequency * 0.8,
+        duration: cfg.tone1.duration * 0.8,
+        envelope: { ...cfg.tone1.envelope, release: cfg.tone1.envelope.release * 0.6 },
+        gain: cfg.tone1.gain * 0.7,
+    });
+    const tone2 = generateTone({
+        waveform: cfg.tone2.waveform,
+        frequency: cfg.tone2.frequency * 0.75,
+        duration: cfg.tone2.duration * 0.7,
+        envelope: { ...cfg.tone2.envelope, release: cfg.tone2.envelope.release * 0.5 },
+        gain: cfg.tone2.gain * 0.6,
+    });
+    const offset = Math.floor(cfg.staggerSeconds * SAMPLE_RATE);
+    const total = new Float64Array(Math.max(tone1.length, offset + tone2.length));
+    total.set(tone1, 0);
+    for (let i = 0; i < tone2.length; i++) {
+        if (offset + i < total.length) {
+            total[offset + i] += tone2[i];
+        }
+    }
+    return limitLoudness(total);
+}
 // --- Ambient (long-running thinking) ---
 /** Generate a single chunk of the ambient thinking drone. */
 export function generateAmbientChunk(profile) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcptoolshop/claude-sfx",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Procedural audio feedback for Claude Code — UX for agentic coding",
   "type": "module",
   "bin": {