free-coding-models 0.2.15 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,84 @@
 
 ---
 
+## 0.3.0
+
+### Added
+- **Always-on background proxy service**: FCM Proxy V2 can run as a persistent background service via `launchd` (macOS) or `systemd` (Linux). All tools get free model access 24/7 — no need to keep the TUI open.
+- **Anthropic wire format translation**: Native bidirectional translation between Anthropic Messages API (`POST /v1/messages`) and OpenAI Chat Completions. Claude Code works natively through FCM Proxy V2.
+- **Dedicated FCM Proxy V2 overlay**: New full-page overlay (from Settings → "FCM Proxy V2 settings →" or `J` key) with proxy config, service status, restart, stop, force-kill, and log viewer.
+- **`J` key — FCM Proxy V2 shortcut**: Opens the proxy settings directly from the main view. Footer shows a green `📡 FCM Proxy V2 On` badge when active, red `📡 FCM Proxy V2 Off` when disabled.
+- **CLI daemon subcommand**: `free-coding-models daemon [status|install|uninstall|restart|stop|logs]` for headless service control.
+- **Stable proxy identity**: Persistent token and preferred port (`18045`) survive daemon restarts — env files and tool configs remain valid across reboots.
+- **Health endpoint**: `GET /v1/health` returns uptime, version, and account/model counts for liveness probes.
+- **`GET /v1/stats` endpoint**: Authenticated endpoint returning per-account health, token stats, totals, and proxy uptime for monitoring and debugging.
+- **Hot-reload**: FCM Proxy V2 watches `~/.free-coding-models.json` and reloads proxy topology automatically when config changes.
+- **Version mismatch detection**: The overlay warns when the running service version differs from the installed FCM version.
+- **Dev environment guard**: `installDaemon()` is blocked when running from a git checkout to prevent hardcoding local repo paths in OS service files.
+- **Generalized proxy sync module** (`src/proxy-sync.js`): Single-endpoint proxy config sync for 12 tools (OpenCode, OpenClaw, Crush, Goose, Pi, Aider, Amp, Qwen, Claude Code, Codex, OpenHands). Writes one `fcm-proxy` provider with all models, cleans up old per-provider `fcm-*` vestiges.
+- **Retry backoff with jitter**: Progressive delays between retries (0ms, 300ms, 800ms + random jitter) to avoid re-hitting the same rate-limit window on 429s.
+- **Automatic account cooldown on consecutive failures**: When an account accumulates 3+ consecutive non-429 failures, it enters graduated cooldown (30s → 60s → 120s). Proxy routes around failing accounts automatically. Resets on success.
+
+### Changed
+- **Rebranded to FCM Proxy V2**: All user-facing references to "daemon", "FCM Proxy", and "Proxy & Daemon" renamed to "FCM Proxy V2" across CLI messages, TUI overlays, endpoint installer, and service descriptions.
+- **Proxy overlay generalized for all tools**: "Persist proxy in OpenCode" → "Auto-sync proxy to {tool}", "Clean OpenCode proxy config" → "Clean {tool} proxy config". New "Active tool" selector row cycles through all 12 proxy-syncable tools.
+- **Feedback overlay redesigned**: Renamed "Report bug" to "Feedback, bugs & requests", input is now left-aligned with a visible cursor, framed by horizontal separator lines. `I` key now covers all feedback types.
+- **Proxy settings moved to dedicated overlay**: The 5 proxy rows in Settings are replaced by a single entry that opens a full-page manager.
+- **Proxy topology extracted to shared module**: `src/proxy-topology.js` is now used by both TUI and daemon, eliminating code duplication.
+- **TUI delegates to background service**: `ensureProxyRunning()` checks for a running service first and reuses its port/token instead of starting an in-process proxy.
+- **Endpoint installer supports proxy mode**: When installing endpoints (Y key) with "FCM Proxy V2" connection mode, env files point to the service's stable token/port.
+- **Claude Code / Codex / Gemini require proxy**: These tools now refuse to launch without FCM Proxy V2 enabled, showing clear instructions to enable it. When proxy is on, they route through it automatically.
+- **Goose launcher rewritten**: Now writes proper custom provider JSON + updates `config.yaml` with `GOOSE_PROVIDER`/`GOOSE_MODEL` for guaranteed auto-selection (replaces obsolete `OPENAI_HOST`/`OPENAI_MODEL` env vars).
+- **Crush launcher improved**: Removed `disable_default_providers` flag, sets both `models.large` and `models.small` defaults for reliable auto-selection.
+- **Pi launcher improved**: Now passes `--provider` and `--model` CLI flags for guaranteed model pre-selection.
+
+### Fixed
+- **Terminal width warning behavior**: Warning now shows max 2 times per session with emojis and double spacing.
+- **Body size limit** (security): `readBody()` now enforces a 10 MB limit. Oversized payloads receive 413.
+- **Stack trace leak prevention** (security): Error responses no longer include `err.message`.
+- **SSE buffer overflow guard** (security): Anthropic SSE transformer limits buffer to 1 MB.
+- **`new URL()` crash protection**: Malformed upstream URLs caught instead of crashing.
+- **`execSync` timeout safety**: All `execSync` calls in daemon-manager use a 15-second timeout via `execSyncSafe()`.
+- **Daemon startup crash protection**: `loadConfig()`, `buildMergedModelsForDaemon()`, and `buildProxyTopologyFromConfig()` wrapped in try/catch.
+- **`resolveCloudflareUrl()` null guard**: Empty provider URLs skipped instead of crashing.
+- **Health check buffer limit**: Responses capped at 64 KB.
+- **SSE line buffering**: SSE tap now correctly handles lines split across chunk boundaries.
+- **Empty choices fallback**: `translateOpenAIToAnthropic` returns fallback content block when OpenAI response has empty choices.
+- **Tool calls streaming index tracking**: Proper `nextBlockIndex`/`currentBlockIndex` counters for correct indexing across multiple tool calls.
+- **Pipe error propagation**: Error handlers on both sides of SSE pipes to prevent uncaught errors on mid-stream disconnects.
+- **Input validation**: `translateAnthropicToOpenAI` guards against null/undefined/non-object input.
+- **Hot-reload race condition**: Config watcher uses `reloadInProgress` flag to prevent concurrent reloads.
+- **Fake response stubs**: Added `destroy()`, `removeListener()`, and `socket: null` for better compatibility.
+- **API key trimming**: Whitespace-trimmed and empty keys filtered out in topology builder.
+- **`writeFileSync` error messages**: Plist and systemd service file write failures now throw clear error messages.
+
+---
+
+## 0.2.17
+
+### Added
+- **All coding tools re-enabled in Z-cycle**: Aider, Claude Code, Codex CLI, Gemini CLI, Qwen Code, OpenHands, and Amp are now back in the public tool mode cycle alongside OpenCode, OpenClaw, Crush, Goose, and Pi — 13 tools total.
+- **All coding tools available in Install Endpoints (Y key)**: The endpoint installer now supports all 13 tools as install targets, not just the original 5. Each tool gets its proper config format (JSON, YAML, or env file).
+- **Connection mode choice in Install flow**: When installing endpoints (Y key), users now choose between **Direct Provider** (pure API connection) or **FCM Proxy** (local proxy with key rotation and usage tracking) — new Step 3 in the 5-step flow.
+- **Install support for new tools**: Pi (models.json + settings.json), Aider (.aider.conf.yml), Amp (settings.json), Gemini (settings.json), Qwen (modelProviders config), Claude Code/Codex/OpenHands (sourceable env files at ~/.fcm-*-env).
+
+### Changed
+- **Install Endpoints flow is now 5 steps**: Provider → Tool → Connection Mode → Scope → Models (was 4 steps without connection mode choice).
+- **Tool labels in install overlay use metadata**: Tool names and emojis in the Y overlay now come from `tool-metadata.js` instead of hard-coded ternary chains — easier to maintain and always in sync.
+- **Help overlay updated**: Z-cycle hint and CLI flag examples now list all 13 tools.
+
+---
+
+## 0.2.16
+
+### Fixed
+- **Changelog index viewport scrolling**: Cursor in changelog version list (N key) now scrolls the viewport to follow selection — previously scrolling past the last visible row would move the cursor off-screen into empty space.
+
+### Added
+- **Changelog version summaries**: Each version in the changelog index now shows a short summary (first change title, ~15 words) after the change count, displayed in dim for readability.
+
+---
+
 ## 0.2.15
 
 ### Changed

package/README.md

@@ -69,8 +69,8 @@ By Vanessa Depraute
 
 - **🎯 Coding-focused** — Only LLM models optimized for code generation, not chat or vision
 - **🌐 Multi-provider** — Models from NVIDIA NIM, Groq, Cerebras, SambaNova, OpenRouter, Hugging Face Inference, Replicate, DeepInfra, Fireworks AI, Codestral, Hyperbolic, Scaleway, Google AI, SiliconFlow, Together AI, Cloudflare Workers AI, Perplexity API, Alibaba Cloud (DashScope), ZAI, and iFlow
-- **⚙️ Settings screen** — Press `P` to manage provider API keys, enable/disable providers, configure the proxy, clean OpenCode proxy sync, and manually check/install updates
-- **🔀 Multi-account Proxy (`fcm-proxy`)** — Automatically starts a local reverse proxy that groups all your accounts into a single provider in OpenCode; supports multi-account rotation and auto-detects usage limits to swap between providers.
+- **⚙️ Settings screen** — Press `P` to manage provider API keys, enable/disable providers, access FCM Proxy V2 settings, and check/install updates
+- **📡 FCM Proxy V2** — Built-in reverse proxy with multi-key rotation, rate-limit failover, and Anthropic wire format translation for Claude Code. Optional always-on background service (`launchd`/`systemd`) keeps the proxy running 24/7 — even without the TUI. Dedicated overlay with full status, restart, stop, force-kill, and log viewer.
 - **🚀 Parallel pings** — All models tested simultaneously via native `fetch`
 - **📊 Real-time animation** — Watch latency appear live in alternate screen buffer
 - **🏆 Smart ranking** — Top 3 fastest models highlighted with medals 🥇🥈🥉
@@ -87,7 +87,7 @@ By Vanessa Depraute
 - **💻 OpenCode integration** — Auto-detects NIM setup, sets model as default, launches OpenCode
 - **🦞 OpenClaw integration** — Sets selected model as default provider in `~/.openclaw/openclaw.json`
 - **🧰 Public tool launchers** — `Enter` auto-configures and launches 10+ tools: `OpenCode CLI`, `OpenCode Desktop`, `OpenClaw`, `Crush`, `Goose`, `Aider`, `Claude Code`, `Codex`, `Gemini`, `Qwen`, `OpenHands`, `Amp`, and `Pi`. All tools auto-select the chosen model on launch.
-- **🔌 Install Endpoints flow** — Press `Y` to install one configured provider directly into `OpenCode CLI`, `OpenCode Desktop`, `OpenClaw`, `Crush`, `Goose`, `Aider`, or `Gemini`, either with the full provider catalog or a curated subset of models
+- **🔌 Install Endpoints flow** — Press `Y` to install one configured provider into any of the 13 supported tools, with a choice between **Direct Provider** (pure API) or **FCM Proxy V2** (key rotation + usage tracking), then pick all models or a curated subset
 - **📝 Feature Request (J key)** — Send anonymous feedback directly to the project team
 - **🐛 Bug Report (I key)** — Send anonymous bug reports directly to the project team
  - **🎨 Clean output** — Zero scrollback pollution, interface stays open until Ctrl+C
@@ -237,8 +237,8 @@ free-coding-models --tier S --json
 
 Running `free-coding-models` with no launcher flag starts in **OpenCode CLI** mode.
 
-- Press **`Z`** in the TUI to cycle the public launch targets: `OpenCode CLI` → `OpenCode Desktop` → `OpenClaw` → `Crush` → `Goose`
-- Or start directly in the target mode with a CLI flag such as `--opencode-desktop`, `--openclaw`, `--crush`, or `--goose`
+- Press **`Z`** in the TUI to cycle the public launch targets: `OpenCode CLI` → `OpenCode Desktop` → `OpenClaw` → `Crush` → `Goose` → `Pi` → `Aider` → `Claude Code` → `Codex` → `Gemini` → `Qwen` → `OpenHands` → `Amp`
+- Or start directly in the target mode with a CLI flag such as `--opencode-desktop`, `--openclaw`, `--crush`, `--goose`, `--pi`, `--aider`, `--claude-code`, `--codex`, `--gemini`, `--qwen`, `--openhands`, or `--amp`
 - The active target is always visible in the header badge before you press `Enter`
 
 **How it works:**
@@ -554,31 +554,92 @@ Stability = 0.30 × p95_score
 
 ---
 
-## 🔀 Multi-Account Proxy (`fcm-proxy`)
+## 📡 FCM Proxy V2
 
-`free-coding-models` includes a built-in reverse proxy that can group all your provider accounts into a single virtual provider.
+`free-coding-models` includes a local reverse proxy that merges all your provider API keys into one endpoint. Optional background service mode keeps it running 24/7 — even without the TUI.
 
-Important:
-- **Disabled by default** — proxy mode is now opt-in from the Settings screen (`P`)
-- **Direct OpenCode launch remains the default** when proxy mode is off
-- **Token/request logs are only populated by proxied requests** today
+> **Disabled by default** — enable in Settings (`P`) → FCM Proxy V2 settings.
 
-### Why use the proxy?
-- **Unified Provider**: Instead of managing 20+ providers in your coding assistant, just use `fcm-proxy`.
-- **Automatic Rotation**: When one account hits its rate limit (429), the proxy automatically swaps to the next available account for that model.
-- **Quota Awareness**: The proxy tracks usage in real-time and prioritizes accounts with the most remaining bandwidth.
-- **Transparent Bridging**: Automatically handles non-standard API paths (like ZAI's `/api/coding/paas/v4/`) and converts them to standard OpenAI-compatible `/v1/` calls.
+### What the proxy does
 
-### How to use it
-1. Open **Settings** with `P`
-2. Enable **Proxy mode (opt-in)**
-3. Optionally enable **Persist proxy in OpenCode** if you explicitly want `fcm-proxy` written to `~/.config/opencode/opencode.json`
-4. Optionally set **Preferred proxy port** (`0` = auto)
-5. Use `S` in Settings to sync the proxy catalog into OpenCode only when you actually want that persistent config
+| Feature | Description |
+|---------|-------------|
+| **Unified endpoint** | One URL (`http://127.0.0.1:18045/v1`) replaces 20+ provider endpoints |
+| **Key rotation** | Automatically swaps to the next API key when one hits rate limits (429) |
+| **Usage tracking** | Tracks token consumption per provider/model pair in real-time |
+| **Anthropic translation** | Claude Code sends `POST /v1/messages` — the proxy translates to OpenAI format upstream |
+| **Path normalization** | Converts non-standard API paths (ZAI, Cloudflare) to standard `/v1/` calls |
 
-Cleanup:
-- Use the Settings action **Clean OpenCode proxy config**
-- Or run `free-coding-models --clean-proxy`
+### In-process vs Background Service mode
+
+| | In-process (default) | Background Service (always-on) |
+|---|---|---|
+| **Lifetime** | Starts/stops with TUI | Survives reboots |
+| **Use case** | Quick sessions | 24/7 access from any tool |
+| **Setup** | Toggle in Settings | One-time install via TUI or CLI |
+| **Port** | Random or configured | Stable (`18045` by default) |
+| **Token** | New each session | Persistent (env files stay valid) |
+
+### Quick setup
+
+**Via TUI (recommended):**
+1. Press `P` to open Settings
+2. Select **FCM Proxy V2 settings →** and press Enter
+3. Enable **Proxy mode**, then select **Install background service**
+
+**Via CLI:**
+```bash
+free-coding-models daemon install     # Install + start as OS service
+free-coding-models daemon status      # Check running status
+free-coding-models daemon restart     # Restart after config changes
+free-coding-models daemon stop        # Graceful stop (SIGTERM)
+free-coding-models daemon uninstall   # Remove OS service completely
+free-coding-models daemon logs        # Show recent service logs
+```
+
+### Service management
+
+The dedicated **FCM Proxy V2** overlay (accessible via `J` from main TUI, or Settings → Enter) provides full control:
+
+- **Active tool selector** — Choose which AI coding tool receives proxy config (cycles through all 12 syncable tools)
+- **Auto-sync toggle** — Automatically write the `fcm-proxy` provider to the active tool's config when the proxy starts
+- **Cleanup** — Remove `fcm-proxy` entries from the active tool's config (works for any syncable tool)
+- **Status display** — Running/Stopped/Stale/Unhealthy with PID, port, uptime, account/model counts
+- **Version mismatch detection** — warns if service version differs from installed FCM version
+- **Restart** — stop + start via the OS service manager
+- **Stop** — graceful SIGTERM (service may auto-restart if installed)
+- **Force kill** — emergency SIGKILL for stuck processes
+- **View logs** — last 50 lines from `~/.free-coding-models/daemon-stdout.log`
+
+### Platform support
+
+| Platform | Service type | Config path |
+|----------|-------------|-------------|
+| macOS | `launchd` LaunchAgent | `~/Library/LaunchAgents/com.fcm.proxy.plist` |
+| Linux | `systemd` user service | `~/.config/systemd/user/fcm-proxy.service` |
+| Windows | Not supported | Falls back to in-process proxy |
+
+### Config files
+
+| File | Purpose |
+|------|---------|
+| `~/.free-coding-models.json` | API keys, proxy settings, service consent |
+| `~/.free-coding-models/daemon.json` | Status file (PID, port, token) — written by the background service |
+| `~/.free-coding-models/daemon-stdout.log` | Service output log |
+
+The `proxy.activeTool` field in the config file tracks which tool the proxy auto-syncs to (e.g. `"opencode"`, `"aider"`, `"claude-code"`).
+
+### Cleanup
+
+- From the FCM Proxy V2 overlay: **Clean {tool} proxy config** — removes `fcm-proxy` entries from whichever tool is currently selected
+- Or: `free-coding-models --clean-proxy`
+
+### Safety
+
+- **Dev guard**: `installDaemon()` is blocked when running from a git checkout — prevents hardcoding local repo paths in OS service files
+- **Localhost only**: The proxy listens on `127.0.0.1`, never exposed to the network
+- **Consent required**: Service installation requires explicit user action — never auto-installs
+- **Hot-reload**: Config changes are picked up automatically without restarting the service
 
 ---
 
@@ -605,17 +666,21 @@ You can use `free-coding-models` with 12+ AI coding tools. When you select a mod
 | OpenCode Desktop | `--opencode-desktop` | Opens Desktop app |
 | OpenClaw | `--openclaw` | ~/.openclaw/openclaw.json |
 | Crush | `--crush` | ~/.config/crush/crush.json |
-| Goose | `--goose` | Environment variables |
+| Goose | `--goose` | ~/.config/goose/config.yaml + custom_providers/ |
 | **Aider** | `--aider` | ~/.aider.conf.yml |
-| **Claude Code** | `--claude-code` | CLI flag |
-| **Codex** | `--codex` | CLI flag |
-| **Gemini** | `--gemini` | ~/.gemini/settings.json |
+| **Claude Code** ⚡ | `--claude-code` | Requires FCM Proxy V2 |
+| **Codex** ⚡ | `--codex` | Requires FCM Proxy V2 |
+| **Gemini** ⚡ | `--gemini` | Requires FCM Proxy V2 |
 | **Qwen** | `--qwen` | ~/.qwen/settings.json |
 | **OpenHands** | `--openhands` | LLM_MODEL env var |
 | **Amp** | `--amp` | ~/.config/amp/settings.json |
 | **Pi** | `--pi` | ~/.pi/agent/settings.json |
 
-Press **Z** to cycle through different tool modes in the TUI, or use flags to start in your preferred mode.
+Press **Z** to cycle through all 13 tool modes in the TUI, or use flags to start in your preferred mode.
+
+⚡ = Requires FCM Proxy V2 background service (press `J` to enable). These tools cannot connect to free providers without the proxy.
+
+All tools are also available as install targets in the **Install Endpoints** flow (`Y` key) — install an entire provider catalog into any tool with one flow, choosing between Direct Provider or FCM Proxy V2 connection.
 
 ---
 
@@ -914,7 +979,7 @@ This script:
 | `--tier C` | Show only C tier models |
 | `--profile <name>` | Load a saved config profile on startup |
 | `--recommend` | Auto-open Smart Recommend overlay on start |
-| `--clean-proxy` | Remove persisted `fcm-proxy` config from OpenCode |
+| `--clean-proxy` | Remove persisted `fcm-proxy` config from the active tool |
 
 **Keyboard shortcuts (main TUI):**
 - **↑↓** — Navigate models
@@ -924,17 +989,18 @@ This script:
 - **T** — Cycle tier filter (All → S+ → S → A+ → A → A- → B+ → B → C → All)
 - **D** — Cycle provider filter (All → NIM → Groq → ...)
 - **E** — Toggle configured-only mode (on by default, persisted across sessions and profiles)
-- **Z** — Cycle target tool (OpenCode CLI → OpenCode Desktop → OpenClaw → Crush → Goose)
+- **Z** — Cycle target tool (OpenCode CLI → Desktop → OpenClaw → Crush → Goose → Pi → Aider → Claude Code → Codex → Gemini → Qwen → OpenHands → Amp)
 - **X** — Toggle request logs (recent proxied request/token usage logs, up to 500 entries)
 - **A (in logs)** — Toggle between showing 500 entries or ALL logs
 - **P** — Open Settings (manage API keys, toggles, updates, profiles)
-- **Y** — Open Install Endpoints (`provider → tool → all models` or `selected models only`, no proxy)
+- **Y** — Open Install Endpoints (`provider → tool → connection mode → scope → models`, Direct or FCM Proxy V2)
 - **Shift+P** — Cycle through saved profiles (switches live TUI settings)
 - **Shift+S** — Save current TUI settings as a named profile (inline prompt)
 - **Q** — Open Smart Recommend overlay (find the best model for your task)
 - **N** — Open Changelog overlay (browse index of all versions, `Enter` to view details, `B` to go back)
 - **W** — Cycle ping mode (`FAST` 2s → `NORMAL` 10s → `SLOW` 30s → `FORCED` 4s)
-- **J / I** — Request feature / Report bug
+- **J** — Open FCM Proxy V2 settings (shows green "Proxy On" / red "Proxy Off" badge in footer)
+- **I** — Feedback, bugs & requests
 - **K / Esc** — Show help overlay / Close overlay
 - **Ctrl+C** — Exit
 
@@ -942,18 +1008,25 @@ Pressing **K** now shows a full in-app reference: main hotkeys, settings hotkeys
 
 ### 🔌 Install Endpoints (`Y`)
 
-`Y` opens a dedicated install flow for configured providers. The flow is:
+`Y` opens a dedicated install flow for configured providers. The 5-step flow is:
 
-1. Pick one provider that already has an API key in Settings
-2. Pick the target tool: `OpenCode CLI`, `OpenCode Desktop`, `OpenClaw`, `Crush`, or `Goose`
-3. Choose either `Install all models` or `Install selected models only`
+1. **Provider** — Pick one provider that already has an API key in Settings
+2. **Tool** — Pick the target tool from all 13 supported tools:
+   - Config-based: `OpenCode CLI`, `OpenCode Desktop`, `OpenClaw`, `Crush`, `Goose`, `Pi`, `Aider`, `Amp`, `Gemini`, `Qwen`
+   - Env-file based: `Claude Code`, `Codex CLI`, `OpenHands` (writes `~/.fcm-{tool}-env` — source it before launching)
+3. **Connection Mode** — Choose how the tool connects to the provider:
+   - **⚡ Direct Provider** — pure API connection, no proxy involved
+   - **🔄 FCM Proxy V2** — route through FCM Proxy V2 with key rotation and usage tracking
+4. **Scope** — Choose `Install all models` or `Install selected models only`
+5. **Models** (if scope = selected) — Multi-select individual models from the provider catalog
 
 Important behavior:
 
-- Installs are written directly into the target tool config as FCM-managed entries, without going through `fcm-proxy`
+- Installs are written into the target tool config as FCM-managed entries (namespaced under `fcm-*`)
 - `Install all models` is the recommended path because FCM can refresh that catalog automatically on later launches when the provider model list changes
 - `Install selected models only` is useful when you want a smaller curated picker inside the target tool
 - `OpenCode CLI` and `OpenCode Desktop` share the same `opencode.json`, so the managed provider appears in both
+- For env-based tools (Claude Code, Codex, OpenHands), FCM writes a sourceable file at `~/.fcm-{tool}-env` — run `source ~/.fcm-claude-code-env` before launching
 
  **Keyboard shortcuts (Settings screen — `P` key):**
  - **↑↓** — Navigate providers, maintenance row, and profile rows

package/bin/fcm-proxy-daemon.js

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+
+/**
+ * @file bin/fcm-proxy-daemon.js
+ * @description Standalone headless FCM proxy daemon — runs independently of the TUI.
+ *
+ * 📖 This is the always-on background proxy server. It reads the user's config
+ *    (~/.free-coding-models.json), builds the proxy topology (merged models × API keys),
+ *    and starts a ProxyServer on a stable port with a stable token.
+ *
+ * 📖 When installed as a launchd LaunchAgent (macOS) or systemd user service (Linux),
+ *    this daemon starts at login and persists across reboots, allowing Claude Code,
+ *    Gemini CLI, OpenCode, and all other tools to access free models 24/7.
+ *
+ * 📖 Status file: ~/.free-coding-models/daemon.json
+ *    Contains PID, port, token, version, model/account counts. The TUI reads this
+ *    to detect a running daemon and delegate instead of starting an in-process proxy.
+ *
+ * 📖 Hot-reload: Watches ~/.free-coding-models.json for changes and reloads the
+ *    proxy topology (accounts, models) without restarting the process.
+ *
+ * @see src/proxy-topology.js — shared topology builder
+ * @see src/proxy-server.js — ProxyServer implementation
+ * @see src/daemon-manager.js — install/uninstall/status management
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync, watch } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import { createRequire } from 'node:module'
+import { fileURLToPath } from 'node:url'
+
+// 📖 Resolve package.json for version info
+const __dirname = fileURLToPath(new URL('.', import.meta.url))
+let PKG_VERSION = 'unknown'
+try {
+  const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'))
+  PKG_VERSION = pkg.version || 'unknown'
+} catch { /* ignore */ }
+
+// 📖 Config + data paths
+const CONFIG_PATH = join(homedir(), '.free-coding-models.json')
+const DATA_DIR = join(homedir(), '.free-coding-models')
+const DAEMON_STATUS_FILE = join(DATA_DIR, 'daemon.json')
+const LOG_PREFIX = '[fcm-daemon]'
+
+// 📖 Default daemon port — high port unlikely to conflict
+const DEFAULT_DAEMON_PORT = 18045
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function log(msg) {
+  console.log(`${LOG_PREFIX} ${new Date().toISOString()} ${msg}`)
+}
+
+function logError(msg) {
+  console.error(`${LOG_PREFIX} ${new Date().toISOString()} ERROR: ${msg}`)
+}
+
+/**
+ * 📖 Write daemon status file so TUI and tools can discover the running daemon.
+ */
+function writeDaemonStatus(info) {
+  if (!existsSync(DATA_DIR)) {
+    mkdirSync(DATA_DIR, { mode: 0o700, recursive: true })
+  }
+  writeFileSync(DAEMON_STATUS_FILE, JSON.stringify(info, null, 2), { mode: 0o600 })
+}
+
+/**
+ * 📖 Remove daemon status file on shutdown.
+ */
+function removeDaemonStatus() {
+  try {
+    if (existsSync(DAEMON_STATUS_FILE)) unlinkSync(DAEMON_STATUS_FILE)
+  } catch { /* best-effort */ }
+}
+
+// ─── Main ────────────────────────────────────────────────────────────────────
+
+async function main() {
+  log(`Starting FCM Proxy V2 v${PKG_VERSION} (PID: ${process.pid})`)
+
+  // 📖 Dynamic imports — keep startup fast, avoid loading TUI-specific modules
+  const { loadConfig, getProxySettings } = await import('../src/config.js')
+  const { ProxyServer } = await import('../src/proxy-server.js')
+  const { buildProxyTopologyFromConfig, buildMergedModelsForDaemon } = await import('../src/proxy-topology.js')
+  const { sources } = await import('../sources.js')
+
+  // 📖 Load config and build initial topology — wrapped in try/catch to provide clear error on startup failures
+  let fcmConfig, proxySettings, mergedModels, accounts, proxyModels
+  try {
+    fcmConfig = loadConfig()
+    proxySettings = getProxySettings(fcmConfig)
+  } catch (err) {
+    logError(`Fatal: Failed to load config: ${err.message}`)
+    process.exit(1)
+  }
+
+  if (!proxySettings.stableToken) {
+    logError('No stableToken in proxy settings — run the TUI first to initialize config.')
+    process.exit(1)
+  }
+
+  const port = proxySettings.preferredPort || DEFAULT_DAEMON_PORT
+  const token = proxySettings.stableToken
+
+  try {
+    log(`Building merged model catalog...`)
+    mergedModels = await buildMergedModelsForDaemon()
+    log(`Merged ${mergedModels.length} model groups`)
+
+    const topology = buildProxyTopologyFromConfig(fcmConfig, mergedModels, sources)
+    accounts = topology.accounts
+    proxyModels = topology.proxyModels
+  } catch (err) {
+    logError(`Fatal: Failed to build initial topology: ${err.message}`)
+    process.exit(1)
+  }
+
+  if (accounts.length === 0) {
+    logError('No API keys configured — FCM Proxy V2 has no accounts to serve. Add keys via the TUI.')
+    process.exit(1)
+  }
+
+  log(`Built proxy topology: ${accounts.length} accounts across ${Object.keys(proxyModels).length} models`)
+
+  // 📖 Start the proxy server
+  const proxy = new ProxyServer({
+    port,
+    accounts,
+    proxyApiKey: token,
+  })
+
+  try {
+    const { port: listeningPort } = await proxy.start()
+    log(`Proxy listening on 127.0.0.1:${listeningPort}`)
+
+    // 📖 Write status file for TUI discovery
+    const statusInfo = {
+      pid: process.pid,
+      port: listeningPort,
+      token,
+      startedAt: new Date().toISOString(),
+      version: PKG_VERSION,
+      modelCount: Object.keys(proxyModels).length,
+      accountCount: accounts.length,
+    }
+    writeDaemonStatus(statusInfo)
+    log(`Status file written to ${DAEMON_STATUS_FILE}`)
+
+    // 📖 Set up config file watcher for hot-reload
+    let reloadTimeout = null
+    // 📖 Prevents concurrent reloads — if a reload is in progress, the next
+    //    watcher event will be queued (one pending max) instead of stacking
+    let reloadInProgress = false
+    let reloadQueued = false
+    const configWatcher = watch(CONFIG_PATH, () => {
+      // 📖 Debounce 1s — config writes can trigger multiple fs events
+      if (reloadTimeout) clearTimeout(reloadTimeout)
+      reloadTimeout = setTimeout(async () => {
+        if (reloadInProgress) {
+          reloadQueued = true
+          return
+        }
+        reloadInProgress = true
+        try {
+          log('Config file changed — reloading topology...')
+          fcmConfig = loadConfig()
+          mergedModels = await buildMergedModelsForDaemon()
+          const newTopology = buildProxyTopologyFromConfig(fcmConfig, mergedModels, sources)
+
+          if (newTopology.accounts.length === 0) {
+            log('Warning: new topology has 0 accounts — keeping current topology')
+            return
+          }
+
+          proxy.updateAccounts(newTopology.accounts)
+          accounts = newTopology.accounts
+          proxyModels = newTopology.proxyModels
+
+          // 📖 Update status file
+          writeDaemonStatus({
+            ...statusInfo,
+            modelCount: Object.keys(proxyModels).length,
+            accountCount: accounts.length,
+          })
+
+          log(`Topology reloaded: ${accounts.length} accounts, ${Object.keys(proxyModels).length} models`)
+        } catch (err) {
+          logError(`Hot-reload failed: ${err.message}`)
+        } finally {
+          reloadInProgress = false
+          // 📖 If another reload was queued during this one, trigger it now
+          if (reloadQueued) {
+            reloadQueued = false
+            configWatcher.emit('change')
+          }
+        }
+      }, 1000)
+    })
+
+    // 📖 Graceful shutdown
+    const shutdown = async (signal) => {
+      log(`Received ${signal} — shutting down...`)
+      if (reloadTimeout) clearTimeout(reloadTimeout)
+      configWatcher.close()
+      try {
+        await proxy.stop()
+      } catch { /* best-effort */ }
+      removeDaemonStatus()
+      log('FCM Proxy V2 stopped cleanly.')
+      process.exit(0)
+    }
+
+    process.on('SIGINT', () => shutdown('SIGINT'))
+    process.on('SIGTERM', () => shutdown('SIGTERM'))
+    process.on('exit', () => removeDaemonStatus())
+
+    // 📖 Keep the process alive
+    log('FCM Proxy V2 ready. Waiting for requests...')
+
+  } catch (err) {
+    if (err.code === 'EADDRINUSE') {
+      logError(`Port ${port} is already in use. Another FCM Proxy V2 instance may be running, or another process occupies this port.`)
+      logError(`Change proxy.preferredPort in ~/.free-coding-models.json or stop the conflicting process.`)
+      process.exit(2)
+    }
+    logError(`Failed to start proxy: ${err.message}`)
+    removeDaemonStatus()
+    process.exit(1)
+  }
+}
+
+main().catch(err => {
+  logError(`Fatal: ${err.message}`)
+  removeDaemonStatus()
+  process.exit(1)
+})