vibe-forge 0.8.1 → 0.8.2

package/{bin → src}/lib/database.sh

@@ -1,357 +1,357 @@
-#!/usr/bin/env bash
-#
-# Vibe Forge - SQLite Database Operations
-# Handles daemon state persistence and agent status aggregation
-#
-
-# Database file location (set after FORGE_ROOT is known)
-FORGE_DB=""
-
-# =============================================================================
-# Security Functions
-# =============================================================================
-
-# Escape a string for safe use in SQLite queries
-# Escapes single quotes by doubling them (SQL standard)
-# Also removes null bytes and other dangerous characters
-db_escape() {
-    local input="$1"
-    # Remove null bytes
-    input="${input//$'\0'/}"
-    # Escape single quotes by doubling them
-    input="${input//\'/\'\'}"
-    # Remove backslashes that could escape quotes
-    input="${input//\\/}"
-    echo "$input"
-}
-
-# Validate that input contains only safe characters for identifiers
-# Returns 0 if safe, 1 if unsafe
-db_validate_identifier() {
-    local input="$1"
-    # Allow only alphanumeric, underscore, hyphen
-    if [[ "$input" =~ ^[a-zA-Z0-9_-]+$ ]]; then
-        return 0
-    fi
-    return 1
-}
-
-# =============================================================================
-# Database Initialization
-# =============================================================================
-
-# Require FORGE_DB to be set before database operations
-# Call this at the start of database functions that need the path
-# Usage: db_require_init || return 1
-db_require_init() {
-    if [[ -z "$FORGE_DB" ]]; then
-        echo "Error: FORGE_DB not set. Set FORGE_DB path before calling database functions." >&2
-        return 1
-    fi
-    return 0
-}
-
-# Check if sqlite3 is available; attempt install if missing
-db_require_sqlite3() {
-    if command -v sqlite3 &>/dev/null; then
-        return 0
-    fi
-
-    echo "sqlite3 not found. Attempting to install..." >&2
-
-    # Try platform-appropriate package manager
-    if command -v apt-get &>/dev/null; then
-        echo "Installing sqlite3 via apt (may require sudo password)..." >&2
-        sudo apt-get install -y sqlite3 2>/dev/null && command -v sqlite3 &>/dev/null && return 0
-    elif command -v brew &>/dev/null; then
-        echo "Installing sqlite3 via Homebrew..." >&2
-        brew install sqlite3 2>/dev/null && command -v sqlite3 &>/dev/null && return 0
-    elif command -v pacman &>/dev/null; then
-        echo "Installing sqlite via pacman (may require sudo password)..." >&2
-        sudo pacman -S --noconfirm sqlite 2>/dev/null && command -v sqlite3 &>/dev/null && return 0
-    elif command -v dnf &>/dev/null; then
-        echo "Installing sqlite via dnf (may require sudo password)..." >&2
-        sudo dnf install -y sqlite 2>/dev/null && command -v sqlite3 &>/dev/null && return 0
-    elif command -v winget &>/dev/null; then
-        echo "Installing SQLite via winget. You may see a UAC prompt; please approve it." >&2
-        winget install --id SQLite.SQLite -e --silent 2>/dev/null
-        # winget installs to Program Files but doesn't add to Git Bash PATH
-        local winget_sqlite="/c/Program Files/SQLite/sqlite3.exe"
-        if [[ -f "$winget_sqlite" ]]; then
-            export PATH="$PATH:/c/Program Files/SQLite"
-            command -v sqlite3 &>/dev/null && return 0
-        fi
-    elif command -v choco &>/dev/null; then
-        echo "Installing sqlite via Chocolatey. You may see a UAC prompt; please approve it." >&2
-        choco install sqlite -y 2>/dev/null && command -v sqlite3 &>/dev/null && return 0
-    fi
-
-    echo "ERROR: sqlite3 is required but could not be installed automatically." >&2
-    echo "Please install sqlite3 manually:" >&2
-    echo "  macOS:   brew install sqlite3" >&2
-    echo "  Ubuntu:  sudo apt-get install sqlite3" >&2
-    echo "  Fedora:  sudo dnf install sqlite" >&2
-    echo "  Windows: choco install sqlite" >&2
-    echo "           or: winget install SQLite.SQLite" >&2
-    echo "           (then add the install folder to your PATH)" >&2
-    return 1
-}
-
-# Initialize the database with schema
-# Requires: FORGE_DB must be set before calling
-db_init() {
-    db_require_init || return 1
-    db_require_sqlite3 || return 1
-    local db_dir
-    db_dir=$(dirname "$FORGE_DB")
-
-    # Create directory if needed
-    mkdir -p "$db_dir"
-    chmod 700 "$db_dir"
-
-    # Enable WAL mode for concurrent reads without blocking writes.
-    # WAL + NORMAL synchronous is the recommended pairing for local tooling:
-    # faster than DELETE+FULL while still durable against OS crashes.
-    sqlite3 "$FORGE_DB" "PRAGMA journal_mode=WAL; PRAGMA synchronous=NORMAL;"
-
-    # Create tables if they don't exist
-    sqlite3 "$FORGE_DB" <<'SQL'
--- Daemon configuration (single row)
-CREATE TABLE IF NOT EXISTS daemon_config (
-    id INTEGER PRIMARY KEY CHECK (id = 1),
-    state TEXT DEFAULT 'idle',
-    poll_interval_ms INTEGER DEFAULT 5000,
-    last_activity_at TEXT,
-    updated_at TEXT DEFAULT CURRENT_TIMESTAMP
-);
-
--- Polling presets
-CREATE TABLE IF NOT EXISTS poll_presets (
-    state TEXT PRIMARY KEY,
-    interval_ms INTEGER NOT NULL
-);
-
--- Insert default presets if not exist
-INSERT OR IGNORE INTO poll_presets (state, interval_ms) VALUES
-    ('active', 5000),
-    ('idle', 30000),
-    ('stopped', 60000);
-
--- Initialize daemon_config if empty
-INSERT OR IGNORE INTO daemon_config (id, state, poll_interval_ms)
-VALUES (1, 'idle', 30000);
-
--- Agent status (aggregated from JSON files)
-CREATE TABLE IF NOT EXISTS agent_status (
-    agent TEXT PRIMARY KEY,
-    status TEXT DEFAULT 'unknown',
-    task TEXT,
-    message TEXT,
-    updated_at TEXT,
-    file_mtime INTEGER DEFAULT 0
-);
-
--- Status history for metrics (optional, pruned periodically)
-CREATE TABLE IF NOT EXISTS status_history (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    agent TEXT NOT NULL,
-    status TEXT NOT NULL,
-    task TEXT,
-    recorded_at TEXT DEFAULT CURRENT_TIMESTAMP
-);
-
--- Index for history queries
-CREATE INDEX IF NOT EXISTS idx_history_agent ON status_history(agent);
-CREATE INDEX IF NOT EXISTS idx_history_recorded ON status_history(recorded_at);
-SQL
-
-    # Set secure permissions on database file
-    chmod 600 "$FORGE_DB" 2>/dev/null || true
-}
-
-# =============================================================================
-# Daemon State Operations
-# =============================================================================
-
-# Get current daemon state (active/idle/stopped)
-db_get_daemon_state() {
-    db_require_init || return 1
-    sqlite3 "$FORGE_DB" "SELECT state FROM daemon_config WHERE id = 1;"
-}
-
-# Set daemon state and update poll interval accordingly
-db_set_daemon_state() {
-    db_require_init || return 1
-    local new_state="$1"
-    local interval
-
-    # SECURITY: Validate state is a known value
-    case "$new_state" in
-        active|idle|stopped) ;;
-        *)
-            echo "Invalid daemon state: $new_state" >&2
-            return 1
-            ;;
-    esac
-
-    # Get interval for this state from presets (safe - validated above)
-    interval=$(sqlite3 "$FORGE_DB" "SELECT interval_ms FROM poll_presets WHERE state = '$new_state';")
-    interval="${interval:-30000}"
-
-    sqlite3 "$FORGE_DB" <<SQL
-UPDATE daemon_config
-SET state = '$new_state',
-    poll_interval_ms = $interval,
-    updated_at = datetime('now')
-WHERE id = 1;
-SQL
-}
-
-# Get current poll interval in milliseconds
-db_get_poll_interval_ms() {
-    sqlite3 "$FORGE_DB" "SELECT poll_interval_ms FROM daemon_config WHERE id = 1;"
-}
-
-# Update last activity timestamp
-db_touch_activity() {
-    sqlite3 "$FORGE_DB" <<SQL
-UPDATE daemon_config
-SET last_activity_at = datetime('now'),
-    updated_at = datetime('now')
-WHERE id = 1;
-SQL
-}
-
-# =============================================================================
-# Agent Status Operations
-# =============================================================================
-
-# Upsert agent status (from JSON file data)
-db_upsert_agent_status() {
-    db_require_init || return 1
-    local agent="$1"
-    local status="$2"
-    local task="$3"
-    local message="$4"
-    local updated_at="$5"
-    local file_mtime="$6"
-
-    # SECURITY: Escape all string inputs to prevent SQL injection
-    agent=$(db_escape "$agent")
-    status=$(db_escape "$status")
-    task=$(db_escape "$task")
-    message=$(db_escape "$message")
-    updated_at=$(db_escape "$updated_at")
-
-    # Validate file_mtime is numeric
-    if ! [[ "$file_mtime" =~ ^[0-9]+$ ]]; then
-        file_mtime=0
-    fi
-
-    sqlite3 "$FORGE_DB" <<SQL
-INSERT INTO agent_status (agent, status, task, message, updated_at, file_mtime)
-VALUES ('$agent', '$status', '$task', '$message', '$updated_at', $file_mtime)
-ON CONFLICT(agent) DO UPDATE SET
-    status = excluded.status,
-    task = excluded.task,
-    message = excluded.message,
-    updated_at = excluded.updated_at,
-    file_mtime = excluded.file_mtime;
-SQL
-}
-
-# Get stored mtime for an agent's status file
-db_get_agent_mtime() {
-    local agent="$1"
-    # SECURITY: Escape agent name to prevent SQL injection
-    agent=$(db_escape "$agent")
-    sqlite3 "$FORGE_DB" "SELECT file_mtime FROM agent_status WHERE agent = '$agent';" 2>/dev/null || echo "0"
-}
-
-# Get all agent statuses
-db_get_all_agent_statuses() {
-    sqlite3 -separator '|' "$FORGE_DB" <<SQL
-SELECT agent, status, task, message, updated_at
-FROM agent_status
-ORDER BY agent;
-SQL
-}
-
-# Get agents with specific status
-db_get_agents_by_status() {
-    local status="$1"
-    # SECURITY: Escape status to prevent SQL injection
-    status=$(db_escape "$status")
-    sqlite3 "$FORGE_DB" "SELECT agent FROM agent_status WHERE status = '$status';"
-}
-
-# Count active workers (status = 'working')
-db_count_active_workers() {
-    sqlite3 "$FORGE_DB" "SELECT COUNT(*) FROM agent_status WHERE status = 'working';"
-}
-
-# Delete stale agent status entries
-db_cleanup_stale_agents() {
-    local minutes="${1:-30}"
-    # SECURITY: Validate minutes is numeric to prevent SQL injection
-    if ! [[ "$minutes" =~ ^[0-9]+$ ]]; then
-        minutes=30
-    fi
-    sqlite3 "$FORGE_DB" <<SQL
-DELETE FROM agent_status
-WHERE updated_at < datetime('now', '-$minutes minutes');
-SQL
-}
-
-# =============================================================================
-# History Operations (for future metrics)
-# =============================================================================
-
-# Record status change in history
-db_record_status_history() {
-    local agent="$1"
-    local status="$2"
-    local task="$3"
-
-    # SECURITY: Escape all inputs to prevent SQL injection
-    agent=$(db_escape "$agent")
-    status=$(db_escape "$status")
-    task=$(db_escape "$task")
-
-    sqlite3 "$FORGE_DB" <<SQL
-INSERT INTO status_history (agent, status, task)
-VALUES ('$agent', '$status', '$task');
-SQL
-}
-
-# Prune old history entries (keep last N days)
-db_prune_history() {
-    local days="${1:-7}"
-    # SECURITY: Validate days is numeric to prevent SQL injection
-    if ! [[ "$days" =~ ^[0-9]+$ ]]; then
-        days=7
-    fi
-    sqlite3 "$FORGE_DB" <<SQL
-DELETE FROM status_history
-WHERE recorded_at < datetime('now', '-$days days');
-SQL
-}
-
-# =============================================================================
-# Utility Functions
-# =============================================================================
-
-# Check if database exists and is valid
-db_exists() {
-    [[ -n "$FORGE_DB" ]] && [[ -f "$FORGE_DB" ]] && sqlite3 "$FORGE_DB" "SELECT 1 FROM daemon_config LIMIT 1;" &>/dev/null
-}
-
-# Get database stats for debugging
-db_stats() {
-    db_require_init || return 1
-    echo "Database: $FORGE_DB"
-    echo "Agent count: $(sqlite3 "$FORGE_DB" "SELECT COUNT(*) FROM agent_status;")"
-    echo "History entries: $(sqlite3 "$FORGE_DB" "SELECT COUNT(*) FROM status_history;")"
-    echo "Current state: $(db_get_daemon_state)"
-    echo "Poll interval: $(db_get_poll_interval_ms)ms"
-}
+#!/usr/bin/env bash
+#
+# Vibe Forge - SQLite Database Operations
+# Handles daemon state persistence and agent status aggregation
+#
+
+# Database file location (set after FORGE_ROOT is known)
+FORGE_DB=""
+
+# =============================================================================
+# Security Functions
+# =============================================================================
+
+# Escape a string for safe use in SQLite queries
+# Escapes single quotes by doubling them (SQL standard)
+# Also removes null bytes and other dangerous characters
+db_escape() {
+    local input="$1"
+    # Remove null bytes
+    input="${input//$'\0'/}"
+    # Escape single quotes by doubling them
+    input="${input//\'/\'\'}"
+    # Remove backslashes that could escape quotes
+    input="${input//\\/}"
+    echo "$input"
+}
+
+# Validate that input contains only safe characters for identifiers
+# Returns 0 if safe, 1 if unsafe
+db_validate_identifier() {
+    local input="$1"
+    # Allow only alphanumeric, underscore, hyphen
+    if [[ "$input" =~ ^[a-zA-Z0-9_-]+$ ]]; then
+        return 0
+    fi
+    return 1
+}
+
+# =============================================================================
+# Database Initialization
+# =============================================================================
+
+# Require FORGE_DB to be set before database operations
+# Call this at the start of database functions that need the path
+# Usage: db_require_init || return 1
+db_require_init() {
+    if [[ -z "$FORGE_DB" ]]; then
+        echo "Error: FORGE_DB not set. Set FORGE_DB path before calling database functions." >&2
+        return 1
+    fi
+    return 0
+}
+
+# Check if sqlite3 is available; attempt install if missing
+db_require_sqlite3() {
+    if command -v sqlite3 &>/dev/null; then
+        return 0
+    fi
+
+    echo "sqlite3 not found. Attempting to install..." >&2
+
+    # Try platform-appropriate package manager
+    if command -v apt-get &>/dev/null; then
+        echo "Installing sqlite3 via apt (may require sudo password)..." >&2
+        sudo apt-get install -y sqlite3 2>/dev/null && command -v sqlite3 &>/dev/null && return 0
+    elif command -v brew &>/dev/null; then
+        echo "Installing sqlite3 via Homebrew..." >&2
+        brew install sqlite3 2>/dev/null && command -v sqlite3 &>/dev/null && return 0
+    elif command -v pacman &>/dev/null; then
+        echo "Installing sqlite via pacman (may require sudo password)..." >&2
+        sudo pacman -S --noconfirm sqlite 2>/dev/null && command -v sqlite3 &>/dev/null && return 0
+    elif command -v dnf &>/dev/null; then
+        echo "Installing sqlite via dnf (may require sudo password)..." >&2
+        sudo dnf install -y sqlite 2>/dev/null && command -v sqlite3 &>/dev/null && return 0
+    elif command -v winget &>/dev/null; then
+        echo "Installing SQLite via winget. You may see a UAC prompt; please approve it." >&2
+        winget install --id SQLite.SQLite -e --silent 2>/dev/null
+        # winget installs to Program Files but doesn't add to Git Bash PATH
+        local winget_sqlite="/c/Program Files/SQLite/sqlite3.exe"
+        if [[ -f "$winget_sqlite" ]]; then
+            export PATH="$PATH:/c/Program Files/SQLite"
+            command -v sqlite3 &>/dev/null && return 0
+        fi
+    elif command -v choco &>/dev/null; then
+        echo "Installing sqlite via Chocolatey. You may see a UAC prompt; please approve it." >&2
+        choco install sqlite -y 2>/dev/null && command -v sqlite3 &>/dev/null && return 0
+    fi
+
+    echo "ERROR: sqlite3 is required but could not be installed automatically." >&2
+    echo "Please install sqlite3 manually:" >&2
+    echo "  macOS:   brew install sqlite3" >&2
+    echo "  Ubuntu:  sudo apt-get install sqlite3" >&2
+    echo "  Fedora:  sudo dnf install sqlite" >&2
+    echo "  Windows: choco install sqlite" >&2
+    echo "           or: winget install SQLite.SQLite" >&2
+    echo "           (then add the install folder to your PATH)" >&2
+    return 1
+}
+
+# Initialize the database with schema
+# Requires: FORGE_DB must be set before calling
+db_init() {
+    db_require_init || return 1
+    db_require_sqlite3 || return 1
+    local db_dir
+    db_dir=$(dirname "$FORGE_DB")
+
+    # Create directory if needed
+    mkdir -p "$db_dir"
+    chmod 700 "$db_dir"
+
+    # Enable WAL mode for concurrent reads without blocking writes.
+    # WAL + NORMAL synchronous is the recommended pairing for local tooling:
+    # faster than DELETE+FULL while still durable against OS crashes.
+    sqlite3 "$FORGE_DB" "PRAGMA journal_mode=WAL; PRAGMA synchronous=NORMAL;"
+
+    # Create tables if they don't exist
+    sqlite3 "$FORGE_DB" <<'SQL'
+-- Daemon configuration (single row)
+CREATE TABLE IF NOT EXISTS daemon_config (
+    id INTEGER PRIMARY KEY CHECK (id = 1),
+    state TEXT DEFAULT 'idle',
+    poll_interval_ms INTEGER DEFAULT 5000,
+    last_activity_at TEXT,
+    updated_at TEXT DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Polling presets
+CREATE TABLE IF NOT EXISTS poll_presets (
+    state TEXT PRIMARY KEY,
+    interval_ms INTEGER NOT NULL
+);
+
+-- Insert default presets if not exist
+INSERT OR IGNORE INTO poll_presets (state, interval_ms) VALUES
+    ('active', 5000),
+    ('idle', 30000),
+    ('stopped', 60000);
+
+-- Initialize daemon_config if empty
+INSERT OR IGNORE INTO daemon_config (id, state, poll_interval_ms)
+VALUES (1, 'idle', 30000);
+
+-- Agent status (aggregated from JSON files)
+CREATE TABLE IF NOT EXISTS agent_status (
+    agent TEXT PRIMARY KEY,
+    status TEXT DEFAULT 'unknown',
+    task TEXT,
+    message TEXT,
+    updated_at TEXT,
+    file_mtime INTEGER DEFAULT 0
+);
+
+-- Status history for metrics (optional, pruned periodically)
+CREATE TABLE IF NOT EXISTS status_history (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    agent TEXT NOT NULL,
+    status TEXT NOT NULL,
+    task TEXT,
+    recorded_at TEXT DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Index for history queries
+CREATE INDEX IF NOT EXISTS idx_history_agent ON status_history(agent);
+CREATE INDEX IF NOT EXISTS idx_history_recorded ON status_history(recorded_at);
+SQL
+
+    # Set secure permissions on database file
+    chmod 600 "$FORGE_DB" 2>/dev/null || true
+}
+
+# =============================================================================
+# Daemon State Operations
+# =============================================================================
+
+# Get current daemon state (active/idle/stopped)
+db_get_daemon_state() {
+    db_require_init || return 1
+    sqlite3 "$FORGE_DB" "SELECT state FROM daemon_config WHERE id = 1;"
+}
+
+# Set daemon state and update poll interval accordingly
+db_set_daemon_state() {
+    db_require_init || return 1
+    local new_state="$1"
+    local interval
+
+    # SECURITY: Validate state is a known value
+    case "$new_state" in
+        active|idle|stopped) ;;
+        *)
+            echo "Invalid daemon state: $new_state" >&2
+            return 1
+            ;;
+    esac
+
+    # Get interval for this state from presets (safe - validated above)
+    interval=$(sqlite3 "$FORGE_DB" "SELECT interval_ms FROM poll_presets WHERE state = '$new_state';")
+    interval="${interval:-30000}"
+
+    sqlite3 "$FORGE_DB" <<SQL
+UPDATE daemon_config
+SET state = '$new_state',
+    poll_interval_ms = $interval,
+    updated_at = datetime('now')
+WHERE id = 1;
+SQL
+}
+
+# Get current poll interval in milliseconds
+db_get_poll_interval_ms() {
+    sqlite3 "$FORGE_DB" "SELECT poll_interval_ms FROM daemon_config WHERE id = 1;"
+}
+
+# Update last activity timestamp
+db_touch_activity() {
+    sqlite3 "$FORGE_DB" <<SQL
+UPDATE daemon_config
+SET last_activity_at = datetime('now'),
+    updated_at = datetime('now')
+WHERE id = 1;
+SQL
+}
+
+# =============================================================================
+# Agent Status Operations
+# =============================================================================
+
+# Upsert agent status (from JSON file data)
+db_upsert_agent_status() {
+    db_require_init || return 1
+    local agent="$1"
+    local status="$2"
+    local task="$3"
+    local message="$4"
+    local updated_at="$5"
+    local file_mtime="$6"
+
+    # SECURITY: Escape all string inputs to prevent SQL injection
+    agent=$(db_escape "$agent")
+    status=$(db_escape "$status")
+    task=$(db_escape "$task")
+    message=$(db_escape "$message")
+    updated_at=$(db_escape "$updated_at")
+
+    # Validate file_mtime is numeric
+    if ! [[ "$file_mtime" =~ ^[0-9]+$ ]]; then
+        file_mtime=0
+    fi
+
+    sqlite3 "$FORGE_DB" <<SQL
+INSERT INTO agent_status (agent, status, task, message, updated_at, file_mtime)
+VALUES ('$agent', '$status', '$task', '$message', '$updated_at', $file_mtime)
+ON CONFLICT(agent) DO UPDATE SET
+    status = excluded.status,
+    task = excluded.task,
+    message = excluded.message,
+    updated_at = excluded.updated_at,
+    file_mtime = excluded.file_mtime;
+SQL
+}
+
+# Get stored mtime for an agent's status file
+db_get_agent_mtime() {
+    local agent="$1"
+    # SECURITY: Escape agent name to prevent SQL injection
+    agent=$(db_escape "$agent")
+    sqlite3 "$FORGE_DB" "SELECT file_mtime FROM agent_status WHERE agent = '$agent';" 2>/dev/null || echo "0"
+}
+
+# Get all agent statuses
+db_get_all_agent_statuses() {
+    sqlite3 -separator '|' "$FORGE_DB" <<SQL
+SELECT agent, status, task, message, updated_at
+FROM agent_status
+ORDER BY agent;
+SQL
+}
+
+# Get agents with specific status
+db_get_agents_by_status() {
+    local status="$1"
+    # SECURITY: Escape status to prevent SQL injection
+    status=$(db_escape "$status")
+    sqlite3 "$FORGE_DB" "SELECT agent FROM agent_status WHERE status = '$status';"
+}
+
+# Count active workers (status = 'working')
+db_count_active_workers() {
+    sqlite3 "$FORGE_DB" "SELECT COUNT(*) FROM agent_status WHERE status = 'working';"
+}
+
+# Delete stale agent status entries
+db_cleanup_stale_agents() {
+    local minutes="${1:-30}"
+    # SECURITY: Validate minutes is numeric to prevent SQL injection
+    if ! [[ "$minutes" =~ ^[0-9]+$ ]]; then
+        minutes=30
+    fi
+    sqlite3 "$FORGE_DB" <<SQL
+DELETE FROM agent_status
+WHERE updated_at < datetime('now', '-$minutes minutes');
+SQL
+}
+
+# =============================================================================
+# History Operations (for future metrics)
+# =============================================================================
+
+# Record status change in history
+db_record_status_history() {
+    local agent="$1"
+    local status="$2"
+    local task="$3"
+
+    # SECURITY: Escape all inputs to prevent SQL injection
+    agent=$(db_escape "$agent")
+    status=$(db_escape "$status")
+    task=$(db_escape "$task")
+
+    sqlite3 "$FORGE_DB" <<SQL
+INSERT INTO status_history (agent, status, task)
+VALUES ('$agent', '$status', '$task');
+SQL
+}
+
+# Prune old history entries (keep last N days)
+db_prune_history() {
+    local days="${1:-7}"
+    # SECURITY: Validate days is numeric to prevent SQL injection
+    if ! [[ "$days" =~ ^[0-9]+$ ]]; then
+        days=7
+    fi
+    sqlite3 "$FORGE_DB" <<SQL
+DELETE FROM status_history
+WHERE recorded_at < datetime('now', '-$days days');
+SQL
+}
+
+# =============================================================================
+# Utility Functions
+# =============================================================================
+
+# Check if database exists and is valid
+db_exists() {
+    [[ -n "$FORGE_DB" ]] && [[ -f "$FORGE_DB" ]] && sqlite3 "$FORGE_DB" "SELECT 1 FROM daemon_config LIMIT 1;" &>/dev/null
+}
+
+# Get database stats for debugging
+db_stats() {
+    db_require_init || return 1
+    echo "Database: $FORGE_DB"
+    echo "Agent count: $(sqlite3 "$FORGE_DB" "SELECT COUNT(*) FROM agent_status;")"
+    echo "History entries: $(sqlite3 "$FORGE_DB" "SELECT COUNT(*) FROM status_history;")"
+    echo "Current state: $(db_get_daemon_state)"
+    echo "Poll interval: $(db_get_poll_interval_ms)ms"
+}