@umang-boss/claudemon 1.0.0 → 1.1.1

package/README.md

@@ -15,41 +15,62 @@ fill your Pokedex -- all while you code.
 - **Level up & evolve** -- Charmander -> Charmeleon -> Charizard
 - **Wild encounters** -- Pokemon appear based on your coding activity
 - **Catch 'em all** -- fill your 151-entry Pokedex
-- **Achievements** -- 18 milestones to unlock
+- **Achievements** -- 17 milestones to unlock
 - **Legendary quests** -- multi-step challenges for Articuno, Zapdos, Moltres, Mewtwo, Mew
 - **Colored terminal sprites** -- hand-crafted pixel art in your terminal
+- **Status line** -- sprite + name + model + buddy speech on the prompt line
 - **Type personalities** -- 15 unique reaction styles
+- **Nickname your Pokemon** -- give them custom names
 
-## Quick Start
+## Install
 
 ```bash
-# Install
-bun run cli/install.ts
-
-# Start a new Claude Code session, then:
-/buddy              # Pick your starter
-/buddy show         # See your Pokemon
-/buddy pet          # Bond with your companion
-/buddy stats        # Detailed stats
-/buddy evolve       # Check evolution status
-/buddy catch        # Catch wild Pokemon
-/buddy party        # Manage your party
-/buddy pokedex      # Track your collection
-/buddy achievements # View progress
-/buddy legendary    # Legendary quest chains
+npx @umang-boss/claudemon install
 ```
 
+That's it! Start a new Claude Code session and type `/buddy`.
+
+**Requirements:** Node.js 18+ (Bun optional, auto-detected for faster startup)
+
+### Other CLI Commands
+
+```bash
+npx @umang-boss/claudemon doctor     # Check installation health
+npx @umang-boss/claudemon update     # Re-register after updates
+npx @umang-boss/claudemon uninstall  # Remove (preserves save data)
+```
+
+## Commands
+
+Once installed, use `/buddy` in Claude Code:
+
+| Command | What it does |
+|---------|-------------|
+| `/buddy` | Show your Pokemon |
+| `/buddy pet` | Bond with your buddy (+XP, +happiness) |
+| `/buddy stats` | Detailed stat breakdown |
+| `/buddy rename Sparky` | Give a nickname |
+| `/buddy rename` | Reset to species name |
+| `/buddy evolve` | Check/trigger evolution |
+| `/buddy catch` | Catch wild Pokemon |
+| `/buddy catch confirm` | Throw a Pokeball! |
+| `/buddy party` | View party (6 max) |
+| `/buddy switch 2` | Switch active Pokemon |
+| `/buddy pokedex` | Track your 151 collection |
+| `/buddy achievements` | View progress |
+| `/buddy legendary` | Legendary quest chains |
+| `/buddy hide` | Hide sprite from status line |
+| `/buddy unhide` | Show sprite |
+
 ## How It Works
 
 Claudemon runs as an MCP (Model Context Protocol) server alongside Claude Code.
 It uses hooks to detect your coding activity and award XP automatically.
 
-### Architecture
-
 ```
 Claude Code -> MCP Server (Claudemon)
            -> Hooks (PostToolUse, Stop, UserPromptSubmit)
-           -> Status Line (name + level + XP bar)
+           -> Status Line (sprite + name + model + speech)
            -> /buddy Skill (slash commands)
 ```
 
@@ -70,10 +91,10 @@ Claude Code -> MCP Server (Claudemon)
 ### Evolution
 
 Pokemon evolve at the same levels as the original Gen 1 games:
-- Level-based: Charmander -> Charmeleon (L16) -> Charizard (L36)
-- Badge-based: Pikachu -> Raichu (Spark Badge -- 200 commits)
-- Collaboration: Kadabra -> Alakazam (10 PRs merged)
-- Stat-based: Eevee -> Flareon/Vaporeon/Jolteon (dominant coding stat)
+- **Level-based:** Charmander -> Charmeleon (L16) -> Charizard (L36)
+- **Badge-based:** Pikachu -> Raichu (Spark Badge -- 200 commits)
+- **Collaboration:** Kadabra -> Alakazam (10 PRs merged)
+- **Stat-based:** Eevee -> Flareon/Vaporeon/Jolteon (dominant coding stat)
 
 ### Badges
 
@@ -85,73 +106,66 @@ Pokemon evolve at the same levels as the original Gen 1 games:
 | Lunar Badge | 30-day streak | Moon Stone evolutions |
 | Growth Badge | Edit 500 files | Leaf Stone evolutions |
 
-### Trainer Titles
+### Wild Encounters
 
-Your title progresses as your Pokemon levels up:
+As you code, wild Pokemon appear based on your activity:
+- Fixing bugs -> Bug/Poison types
+- Writing tests -> Fighting/Normal types
+- Large refactors -> Psychic/Dragon types
+- Build/compile -> Fire/Rock types
 
-| Level | Title |
-|-------|-------|
-| 1 | Bug Catcher |
-| 6 | Youngster |
-| 11 | Hiker |
-| 21 | Ace Trainer |
-| 31 | Cooltrainer |
-| 41 | Veteran |
-| 51 | Elite Four |
-| 61 | Champion |
-| 76 | Pokemon Master |
-| 91 | Professor |
+Encounters trigger roughly every 500 XP earned. Use `/buddy catch` to try catching them!
 
-## CLI Tools
+### Legendary Quests
 
-```bash
-# Install Claudemon into Claude Code
-bun run cli/install.ts
+5 multi-step quest chains for legendary Pokemon:
+- **Articuno** -- The Ice Bird of Endurance (100-day streak)
+- **Zapdos** -- The Thunder of Testing (1000 tests passed)
+- **Moltres** -- The Flame of Debugging (500 bugs fixed)
+- **Mewtwo** -- The Ultimate Creation (140 Pokedex entries)
+- **Mew** -- The Myth (365-day coding streak)
+
+## Status Line
 
-# Uninstall (preserves your save data)
-bun run cli/uninstall.ts
+The status line shows your Pokemon sprite on the right side of the input prompt:
 
-# Diagnose installation issues
-bun run cli/doctor.ts
 ```
+*Pikachu hums softly*  Pikachu Lv.10
+Opus 4.6                [colored sprite]
+                        [colored sprite]
+                        [colored sprite]
+```
+
+- Buddy speech rotates every 30 seconds (zero API cost -- hardcoded messages)
+- Model name from Claude Code
+- `/buddy hide` to toggle sprite visibility
 
 ## Development
 
 ```bash
-# Run the MCP server directly
-bun run server
+# Clone and install
+git clone https://github.com/umang-dabhi/claudemon.git
+cd claudemon
+bun install
 
-# Run tests
+# Run tests (309 tests)
 bun test
 
 # Type checking
 bun run typecheck
 
-# Format code
+# Format
 bun run format
-```
-
-### Project Structure
 
-```
-src/
-  engine/          # Game logic: XP, evolution, encounters, stats
-  gamification/    # Achievements, milestones, legendary quests
-  server/          # MCP server and tool handlers
-  sprites/         # Terminal sprite rendering
-  state/           # Save state management
-cli/               # Install, uninstall, doctor scripts
-hooks/             # PostToolUse, Stop, UserPromptSubmit shell scripts
-skills/buddy/      # /buddy slash command definition
-sprites/full/      # 151 colored terminal sprite files
-statusline/        # Status bar shell script
-tests/             # Test suites
+# Build for npm (compiles TS to JS)
+npm run build
 ```
 
 ## Requirements
 
-- [Claude Code](https://claude.ai/code) v2.1.80+
-- [Bun](https://bun.sh) v1.0+
+- [Claude Code](https://claude.ai/code)
+- Node.js 18+ (or [Bun](https://bun.sh) for faster startup)
+- `jq` for status line (`sudo apt install jq` on Ubuntu)
 
 ## Disclaimer
 

package/bin/claudemon.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
- * Claudemon CLI wrapper — detects Bun and delegates to it.
- * Works with `npx claudemon` even on systems with only Node.js.
+ * Claudemon CLI — works with Node.js (no Bun required for users).
+ * Routes to install/uninstall/update/doctor.
  */
 
 import { spawnSync } from "node:child_process";
@@ -10,43 +10,53 @@ import { resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const cliEntry = resolve(__dirname, "..", "cli", "index.ts");
 const args = process.argv.slice(2);
 
-// Find bun binary
-function findBun() {
-  const home = process.env.HOME || "";
-  const candidates = [
-    `${home}/.bun/bin/bun`,
-    "/usr/local/bin/bun",
-    "/usr/bin/bun",
-  ];
-  for (const p of candidates) {
-    if (existsSync(p)) return p;
-  }
-  // Try PATH
-  const result = spawnSync("which", ["bun"], { stdio: "pipe" });
-  if (result.status === 0) return "bun";
-  return null;
-}
-
-const bunPath = findBun();
+// Try compiled JS first (dist/), then fall back to TS with bun
+const distCli = resolve(__dirname, "..", "dist", "cli", "index.js");
+const srcCli = resolve(__dirname, "..", "cli", "index.ts");
 
-if (bunPath) {
-  const result = spawnSync(bunPath, ["run", cliEntry, ...args], {
+if (existsSync(distCli)) {
+  // Run compiled JS with node
+  const result = spawnSync("node", [distCli, ...args], {
     stdio: "inherit",
     env: process.env,
   });
   process.exit(result.status ?? 1);
 } else {
+  // Fallback: try bun with source TS
+  const home = process.env.HOME || "";
+  const bunPaths = [`${home}/.bun/bin/bun`, "/usr/local/bin/bun", "/usr/bin/bun"];
+  let bunPath = null;
+
+  for (const p of bunPaths) {
+    if (existsSync(p)) {
+      bunPath = p;
+      break;
+    }
+  }
+
+  if (!bunPath) {
+    const which = spawnSync("which", ["bun"], { stdio: "pipe" });
+    if (which.status === 0) bunPath = "bun";
+  }
+
+  if (bunPath && existsSync(srcCli)) {
+    const result = spawnSync(bunPath, ["run", srcCli, ...args], {
+      stdio: "inherit",
+      env: process.env,
+    });
+    process.exit(result.status ?? 1);
+  }
+
   console.error(`
-  Claudemon requires Bun (https://bun.sh) to run.
+  Error: Could not find compiled files (dist/) or Bun runtime.
 
-  Install Bun:
-    curl -fsSL https://bun.sh/install | bash
+  If you installed via npm, try reinstalling:
+    npm install -g @umang-boss/claudemon
 
-  Then run:
-    npx claudemon install
+  Or install Bun and run from source:
+    curl -fsSL https://bun.sh/install | bash
   `);
   process.exit(1);
 }

package/cli/doctor.ts

@@ -5,9 +5,11 @@
  * Usage: bun run cli/doctor.ts
  */
 
-import { access, stat, unlink, readdir } from "node:fs/promises";
+import { access, stat, unlink, readdir, readFile } from "node:fs/promises";
 import { constants as fsConstants } from "node:fs";
 import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
 import { StateManager } from "../src/state/state-manager.js";
 import { PlayerStateSchema } from "../src/state/schemas.js";
 
@@ -28,7 +30,9 @@ const STATE_FILE = `${STATE_DIR}/state.json`;
 const LOCK_FILE = `${STATE_DIR}/state.lock`;
 const LOCK_MAX_AGE_MS = 5000;
 const EXPECTED_SPRITE_COUNT = 151;
-const COLORSCRIPT_DIR = resolve(dirname(import.meta.dir), "sprites/colorscripts/small");
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const COLORSCRIPT_DIR = resolve(dirname(__dirname), "sprites/colorscripts/small");
 
 // ── Helpers ──────────────────────────────────────────────────
 
@@ -47,10 +51,10 @@ function formatCheck(result: CheckResult): string {
 
 async function checkBun(): Promise<CheckResult> {
   try {
-    const proc = Bun.spawn(["bun", "--version"], { stdout: "pipe", stderr: "pipe" });
-    const output = await new Response(proc.stdout).text();
-    await proc.exited;
-    return { label: "Bun runtime", passed: true, detail: `v${output.trim()}` };
+    const result = spawnSync("bun", ["--version"], { stdio: "pipe" });
+    if (result.error) throw result.error;
+    const output = result.stdout?.toString().trim();
+    return { label: "Bun runtime", passed: true, detail: `v${output}` };
   } catch {
     return { label: "Bun runtime", passed: false, detail: "not found" };
   }
@@ -74,13 +78,14 @@ async function checkStateDir(): Promise<CheckResult> {
 // ── Check 3: State File ──────────────────────────────────────
 
 async function checkStateFile(): Promise<CheckResult> {
-  const file = Bun.file(STATE_FILE);
-  if (!(await file.exists())) {
+  try {
+    await access(STATE_FILE, fsConstants.F_OK);
+  } catch {
     return { label: "State file", passed: false, detail: "not found (run /buddy starter first)" };
   }
 
   try {
-    const text = await file.text();
+    const text = await readFile(STATE_FILE, "utf-8");
     const data = JSON.parse(text) as Record<string, unknown>;
 
     // Check for active pokemon
@@ -150,11 +155,12 @@ async function checkHooks(): Promise<CheckResult> {
 // ── Check 6: Skill ───────────────────────────────────────────
 
 async function checkSkill(): Promise<CheckResult> {
-  const file = Bun.file(SKILL_DEST);
-  if (await file.exists()) {
+  try {
+    await access(SKILL_DEST, fsConstants.F_OK);
     return { label: "Skill", passed: true, detail: "/buddy command installed" };
+  } catch {
+    return { label: "Skill", passed: false, detail: "~/.claude/skills/buddy/SKILL.md not found" };
   }
-  return { label: "Skill", passed: false, detail: "~/.claude/skills/buddy/SKILL.md not found" };
 }
 
 // ── Check 7: Hook Script Executable ──────────────────────────
@@ -164,15 +170,16 @@ async function checkHookScript(): Promise<CheckResult> {
     await access(HOOK_SCRIPT, fsConstants.X_OK);
     return { label: "Hook script", passed: true, detail: "executable" };
   } catch {
-    const file = Bun.file(HOOK_SCRIPT);
-    if (await file.exists()) {
+    try {
+      await access(HOOK_SCRIPT, fsConstants.F_OK);
       return {
         label: "Hook script",
         passed: false,
         detail: "exists but not executable (run chmod +x)",
       };
+    } catch {
+      return { label: "Hook script", passed: false, detail: "not found" };
     }
-    return { label: "Hook script", passed: false, detail: "not found" };
   }
 }
 
@@ -255,13 +262,14 @@ async function checkSpriteCount(): Promise<CheckResult> {
 // ── Check 11: State File Validity (Zod) ─────────────────────
 
 async function checkStateValidity(): Promise<CheckResult> {
-  const file = Bun.file(STATE_FILE);
-  if (!(await file.exists())) {
+  try {
+    await access(STATE_FILE, fsConstants.F_OK);
+  } catch {
     return { label: "State validity", passed: true, detail: "no state file yet" };
   }
 
   try {
-    const text = await file.text();
+    const text = await readFile(STATE_FILE, "utf-8");
     if (!text.trim()) {
       return { label: "State validity", passed: false, detail: "state file is empty" };
     }

package/cli/install.ts

@@ -7,6 +7,7 @@
 
 import { mkdir, copyFile, chmod, access } from "node:fs/promises";
 import { constants as fsConstants } from "node:fs";
+import { spawnSync } from "node:child_process";
 
 import type { ClaudeConfig, ClaudeSettings, HookCommand, HookMatcher } from "./shared.js";
 import {
@@ -25,8 +26,7 @@ import {
   STOP_HOOK_SCRIPT,
   USER_PROMPT_HOOK_SCRIPT,
   STATUSLINE_SCRIPT,
-  SERVER_ENTRY,
-  getBunPath,
+  getRuntime,
 } from "./shared.js";
 
 // ── Step 1: Check Prerequisites ──────────────────────────────
@@ -36,10 +36,10 @@ async function checkPrerequisites(): Promise<boolean> {
 
   // Check bun (sanity)
   try {
-    const proc = Bun.spawn(["bun", "--version"], { stdout: "pipe", stderr: "pipe" });
-    const output = await new Response(proc.stdout).text();
-    await proc.exited;
-    ok(`Bun runtime: v${output.trim()}`);
+    const result = spawnSync("bun", ["--version"], { stdio: "pipe" });
+    if (result.error) throw result.error;
+    const output = result.stdout?.toString().trim();
+    ok(`Bun runtime: v${output}`);
   } catch {
     fail("Bun runtime not found. Install from https://bun.sh");
     allGood = false;
@@ -76,8 +76,8 @@ async function registerMcpServer(): Promise<void> {
   }
 
   config.mcpServers["claudemon"] = {
-    command: getBunPath(),
-    args: ["run", SERVER_ENTRY],
+    command: getRuntime().command,
+    args: [getRuntime().serverEntry],
     env: {},
   };
 

package/cli/shared.ts

@@ -4,6 +4,7 @@
  */
 
 import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 
 // ── Config shape interfaces ──────────────────────────────────
 
@@ -50,7 +51,9 @@ if (!HOME) {
 }
 
 export const CLI_HOME = HOME;
-export const PROJECT_DIR = resolve(dirname(import.meta.dir));
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+export const PROJECT_DIR = resolve(dirname(__dirname));
 export const CLAUDE_DIR = `${HOME}/.claude`;
 export const CLAUDE_CONFIG = `${HOME}/.claude.json`;
 export const CLAUDE_SETTINGS = `${CLAUDE_DIR}/settings.json`;
@@ -62,16 +65,28 @@ export const HOOK_SCRIPT = `${PROJECT_DIR}/hooks/post-tool-use.sh`;
 export const STOP_HOOK_SCRIPT = `${PROJECT_DIR}/hooks/stop.sh`;
 export const USER_PROMPT_HOOK_SCRIPT = `${PROJECT_DIR}/hooks/user-prompt-submit.sh`;
 export const STATUSLINE_SCRIPT = `${PROJECT_DIR}/statusline/buddy-status.sh`;
-export const SERVER_ENTRY = `${PROJECT_DIR}/src/server/index.ts`;
+export const SERVER_ENTRY_TS = `${PROJECT_DIR}/src/server/index.ts`;
+export const SERVER_ENTRY_JS = `${PROJECT_DIR}/dist/src/server/index.js`;
 
-/** Resolve full path to bun binary (Claude Code may not have bun in PATH) */
-export function getBunPath(): string {
+/** Find the best runtime and server entry — prefers bun (fast), falls back to node (compiled JS) */
+export function getRuntime(): { command: string; serverEntry: string } {
   const { existsSync } = require("node:fs") as { existsSync: (p: string) => boolean };
-  const candidates = [`${HOME}/.bun/bin/bun`, "/usr/local/bin/bun", "/usr/bin/bun"];
-  for (const p of candidates) {
-    if (existsSync(p)) return p;
+
+  // Check for bun (can run .ts directly)
+  const bunCandidates = [`${HOME}/.bun/bin/bun`, "/usr/local/bin/bun", "/usr/bin/bun"];
+  for (const p of bunCandidates) {
+    if (existsSync(p)) {
+      return { command: p, serverEntry: SERVER_ENTRY_TS };
+    }
+  }
+
+  // Fall back to node (needs compiled .js from dist/)
+  if (existsSync(SERVER_ENTRY_JS)) {
+    return { command: "node", serverEntry: SERVER_ENTRY_JS };
   }
-  return "bun";
+
+  // Last resort: assume bun in PATH
+  return { command: "bun", serverEntry: SERVER_ENTRY_TS };
 }
 
 // ── Helpers ──────────────────────────────────────────────────
@@ -89,14 +104,18 @@ export function info(msg: string): void {
 }
 
 export async function readJson<T>(path: string): Promise<T | null> {
-  const file = Bun.file(path);
-  if (!(await file.exists())) {
+  const { readFile, access } = await import("node:fs/promises");
+  const { constants } = await import("node:fs");
+  try {
+    await access(path, constants.F_OK);
+    const text = await readFile(path, "utf-8");
+    return JSON.parse(text) as T;
+  } catch {
     return null;
   }
-  const text = await file.text();
-  return JSON.parse(text) as T;
 }
 
 export async function writeJson(path: string, data: unknown): Promise<void> {
-  await Bun.write(path, JSON.stringify(data, null, 2) + "\n");
+  const { writeFile } = await import("node:fs/promises");
+  await writeFile(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
 }

package/cli/uninstall.ts

@@ -5,7 +5,8 @@
  * Usage: bun run cli/uninstall.ts
  */
 
-import { rm } from "node:fs/promises";
+import { rm, access } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
 
 import type { ClaudeConfig, ClaudeSettings } from "./shared.js";
 import {
@@ -106,8 +107,9 @@ async function removeHooks(): Promise<void> {
 // ── Step 3: Remove Skill ─────────────────────────────────────
 
 async function removeSkill(): Promise<void> {
-  const file = Bun.file(`${SKILL_DEST_DIR}/SKILL.md`);
-  if (!(await file.exists())) {
+  try {
+    await access(`${SKILL_DEST_DIR}/SKILL.md`, fsConstants.F_OK);
+  } catch {
     info("Skill: ~/.claude/skills/buddy/ not found (nothing to remove)");
     return;
   }
@@ -119,10 +121,10 @@ async function removeSkill(): Promise<void> {
 // ── Step 4: Preserve State Data ──────────────────────────────
 
 async function preserveStateData(): Promise<void> {
-  const stateFile = Bun.file(`${STATE_DIR}/state.json`);
-  if (await stateFile.exists()) {
+  try {
+    await access(`${STATE_DIR}/state.json`, fsConstants.F_OK);
     info(`Your Pokemon data is preserved at ${STATE_DIR}/. Delete manually to remove.`);
-  } else {
+  } catch {
     info(`State directory: ${STATE_DIR}/ (kept, no state file found)`);
   }
 }

package/cli/update.ts

@@ -10,9 +10,9 @@
  */
 
 import { mkdir, copyFile, chmod, access } from "node:fs/promises";
-import { constants as fsConstants } from "node:fs";
+import { constants as fsConstants, existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
-import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
 
 import type { ClaudeConfig, ClaudeSettings, HookCommand, HookMatcher } from "./shared.js";
 import {
@@ -32,9 +32,8 @@ import {
   STOP_HOOK_SCRIPT,
   USER_PROMPT_HOOK_SCRIPT,
   STATUSLINE_SCRIPT,
-  SERVER_ENTRY,
   PROJECT_DIR,
-  getBunPath,
+  getRuntime,
 } from "./shared.js";
 
 // ── Step 1: Check Prerequisites ──────────────────────────────
@@ -43,10 +42,10 @@ async function checkPrerequisites(): Promise<boolean> {
   let allGood = true;
 
   try {
-    const proc = Bun.spawn(["bun", "--version"], { stdout: "pipe", stderr: "pipe" });
-    const output = await new Response(proc.stdout).text();
-    await proc.exited;
-    ok(`Bun runtime: v${output.trim()}`);
+    const result = spawnSync("bun", ["--version"], { stdio: "pipe" });
+    if (result.error) throw result.error;
+    const output = result.stdout?.toString().trim();
+    ok(`Bun runtime: v${output}`);
   } catch {
     fail("Bun runtime not found.");
     allGood = false;
@@ -122,8 +121,8 @@ async function registerMcpServer(): Promise<void> {
   }
 
   config.mcpServers["claudemon"] = {
-    command: getBunPath(),
-    args: ["run", SERVER_ENTRY],
+    command: getRuntime().command,
+    args: [getRuntime().serverEntry],
     env: {},
   };
 
@@ -240,7 +239,7 @@ async function checkColorscripts(): Promise<{ missing: number; total: number }>
     }
 
     // Check for files matching the pattern
-    const files = await Array.fromAsync(new Bun.Glob(`${prefix}*.txt`).scan(smallDir));
+    const files = readdirSync(smallDir).filter((f) => f.startsWith(prefix) && f.endsWith(".txt"));
     if (files.length === 0) {
       missing++;
     }
@@ -252,10 +251,10 @@ async function checkColorscripts(): Promise<{ missing: number; total: number }>
 // ── Step 5: State Preservation Check ─────────────────────────
 
 async function checkStatePreserved(): Promise<void> {
-  const stateFile = Bun.file(`${STATE_DIR}/state.json`);
-  if (await stateFile.exists()) {
+  try {
+    await access(`${STATE_DIR}/state.json`, fsConstants.F_OK);
     ok("State data: preserved (not modified)");
-  } else {
+  } catch {
     info("State data: no save file found (run /buddy starter to begin)");
   }
 }