morpheus-cli 0.9.1 → 0.9.4

package/README.md

@@ -266,6 +266,13 @@ Telegram responses use rich HTML formatting conversion with:
 
 Task results are delivered proactively with metadata (task id, agent, status) and output/error body.
 
+**Session commands:**
+- `/session` — Show current session info
+- `/session list` — List recent sessions
+- `/session new` — Create new session
+- `/session switch <id>` — Switch to existing session
+- `/session rename <name>` — Rename current session
+
 **Voice messages:** Telegram voice messages are automatically transcribed (Gemini / Whisper / OpenRouter) and processed as text through the Oracle.
 
 ## Discord Experience
@@ -279,7 +286,11 @@ Discord bot responds to **DMs only** from authorized user IDs (`allowedUsers`).
 | `/help` | Show available commands |
 | `/status` | Check Morpheus status |
 | `/stats` | Token usage statistics |
-| `/newsession` | Start a new session |
+| `/session` | Show current session info |
+| `/session_list` | List recent sessions |
+| `/session_new` | Start a new session |
+| `/session_switch id:` | Switch to existing session |
+| `/session_rename name:` | Rename current session |
 | `/mcps` | List MCP servers with tool counts |
 | `/mcpreload` | Reload MCP connections and tools |
 | `/mcp_enable name:` | Enable an MCP server |
@@ -314,16 +325,19 @@ Adding a new channel requires only implementing `IChannelAdapter` (`channel`, `s
 ## Web UI
 
 The dashboard includes:
-- Chat with session management
-- Tasks page (stats, filters, details, retry)
+- Chat with session management and browser notifications
+- Tasks page (stats, filters, details, retry, pagination)
 - Agent settings (Oracle/Sati/Neo/Apoc/Trinity/Smiths)
 - MCP manager (add/edit/delete/toggle/reload)
-- Sati memories (search, bulk delete)
+- Sati memories (search, bulk delete, pagination)
 - Usage stats and model pricing
 - Trinity databases (register/test/refresh schema)
 - Chronos scheduler (create/edit/delete jobs, execution history)
+- Smiths management (add/edit/delete, real-time status, ping)
+- Audit dashboard (session audit, tool call tracking, cost breakdowns)
 - Webhooks and notification inbox
 - Logs viewer
+- Danger Zone (Settings → reset sessions, tasks, jobs, audit, or factory reset)
 
 Chat-specific rendering:
 - AI messages rendered as markdown

package/dist/config/manager.js

@@ -328,6 +328,10 @@ export class ConfigManager {
                 entries: config.smiths?.entries ?? [],
             },
             verbose_mode: resolveBoolean('MORPHEUS_VERBOSE_MODE', config.verbose_mode, true),
+            setup: {
+                enabled: resolveBoolean('MORPHEUS_SETUP_ENABLED', config.setup?.enabled, true),
+                fields: config.setup?.fields ?? ['name', 'timezone', 'preferred_language'],
+            },
         };
     }
     get() {
@@ -411,6 +415,13 @@ export class ConfigManager {
         }
         return defaults;
     }
+    getSetupConfig() {
+        const defaults = { enabled: true, fields: ['name', 'timezone', 'preferred_language'] };
+        if (this.config.setup) {
+            return { ...defaults, ...this.config.setup };
+        }
+        return defaults;
+    }
     getSmithsConfig() {
         const defaults = {
             enabled: false,

package/dist/config/schemas.js

@@ -63,6 +63,10 @@ export const SmithEntrySchema = z.object({
     auth_token: z.string().min(1),
     tls: z.boolean().default(false),
 });
+export const SetupConfigSchema = z.object({
+    enabled: z.boolean().default(true),
+    fields: z.array(z.string()).default(['name', 'timezone', 'preferred_language']),
+});
 export const SmithsConfigSchema = z.object({
     enabled: z.boolean().default(false),
     execution_mode: z.enum(['sync', 'async']).default('async'),
@@ -96,6 +100,7 @@ export const ConfigSchema = z.object({
     chronos: ChronosConfigSchema.optional(),
     devkit: DevKitConfigSchema.optional(),
     smiths: SmithsConfigSchema.optional(),
+    setup: SetupConfigSchema.optional(),
     verbose_mode: z.boolean().default(true),
     channels: z.object({
         telegram: z.object({

package/dist/http/api.js

@@ -20,6 +20,7 @@ import { ChronosWorker } from '../runtime/chronos/worker.js';
 import { createChronosJobRouter, createChronosConfigRouter } from './routers/chronos.js';
 import { createSkillsRouter } from './routers/skills.js';
 import { createSmithsRouter } from './routers/smiths.js';
+import { createDangerRouter } from './routers/danger.js';
 import { getActiveEnvOverrides } from '../config/precedence.js';
 import { hotReloadConfig, getRestartRequiredChanges } from '../runtime/hot-reload.js';
 import { AuditRepository } from '../runtime/audit/repository.js';
@@ -49,6 +50,8 @@ export function createApiRouter(oracle, chronosWorker) {
     router.use('/skills', createSkillsRouter());
     // Mount Smiths router
     router.use('/smiths', createSmithsRouter());
+    // Mount Danger Zone router
+    router.use('/danger', createDangerRouter());
     // --- Session Management ---
     router.get('/sessions', async (req, res) => {
         try {

package/dist/http/routers/danger.js

@@ -0,0 +1,137 @@
+import { Router } from 'express';
+import Database from 'better-sqlite3';
+import path from 'path';
+import { homedir } from 'os';
+import fs from 'fs-extra';
+import { z } from 'zod';
+import { SatiRepository } from '../../runtime/memory/sati/repository.js';
+import { DisplayManager } from '../../runtime/display.js';
+/**
+ * Valid categories the user can choose to delete.
+ */
+const VALID_CATEGORIES = [
+    'sessions', // sessions + messages
+    'memories', // sati-memory.db (long-term memory, embeddings, session chunks)
+    'tasks', // background tasks
+    'audit', // audit_events
+    'chronos', // chronos_jobs + chronos_executions
+    'webhooks', // webhooks + webhook_notifications
+];
+const ResetBodySchema = z.object({
+    categories: z.array(z.enum(VALID_CATEGORIES)).min(1, 'At least one category must be selected'),
+});
+/**
+ * Creates the Danger Zone API router.
+ * Provides destructive operations for resetting user data.
+ */
+export function createDangerRouter() {
+    const router = Router();
+    const display = DisplayManager.getInstance();
+    /**
+     * GET /api/danger/categories — List available reset categories
+     */
+    router.get('/categories', (_req, res) => {
+        res.json({
+            categories: VALID_CATEGORIES.map((id) => ({ id })),
+        });
+    });
+    /**
+     * DELETE /api/danger/reset — Purge selected user data
+     *
+     * Body: { categories: ['sessions', 'memories', 'tasks', 'audit', 'chronos', 'webhooks'] }
+     */
+    router.delete('/reset', async (req, res) => {
+        // Validate body
+        const parsed = ResetBodySchema.safeParse(req.body);
+        if (!parsed.success) {
+            return res.status(400).json({
+                error: 'Invalid request',
+                details: parsed.error.issues.map((i) => i.message),
+            });
+        }
+        const { categories } = parsed.data;
+        try {
+            const memoryDir = path.join(homedir(), '.morpheus', 'memory');
+            const shortMemoryPath = path.join(memoryDir, 'short-memory.db');
+            const satiMemoryPath = path.join(memoryDir, 'sati-memory.db');
+            const counts = {};
+            // ─── 1. Purge short-memory.db tables based on selected categories ───
+            const needsShortDb = categories.some((c) => ['sessions', 'tasks', 'audit', 'chronos', 'webhooks'].includes(c));
+            if (needsShortDb && fs.existsSync(shortMemoryPath)) {
+                const db = new Database(shortMemoryPath, { timeout: 5000 });
+                db.pragma('journal_mode = WAL');
+                const transaction = db.transaction(() => {
+                    if (categories.includes('sessions')) {
+                        const msgResult = db.prepare('DELETE FROM messages').run();
+                        counts.messages = msgResult.changes;
+                        const sessResult = db.prepare('DELETE FROM sessions').run();
+                        counts.sessions = sessResult.changes;
+                        // Also clear first-time setup state so onboarding runs again after reset
+                        try {
+                            db.prepare('DELETE FROM setup_state').run();
+                        }
+                        catch {
+                            // Table may not exist on older installations — safe to ignore
+                        }
+                    }
+                    if (categories.includes('tasks')) {
+                        const taskResult = db.prepare('DELETE FROM tasks').run();
+                        counts.tasks = taskResult.changes;
+                    }
+                    if (categories.includes('audit')) {
+                        const auditResult = db.prepare('DELETE FROM audit_events').run();
+                        counts.audit_events = auditResult.changes;
+                    }
+                    if (categories.includes('chronos')) {
+                        const jobsResult = db.prepare('DELETE FROM chronos_jobs').run();
+                        counts.chronos_jobs = jobsResult.changes;
+                        const execResult = db.prepare('DELETE FROM chronos_executions').run();
+                        counts.chronos_executions = execResult.changes;
+                    }
+                    if (categories.includes('webhooks')) {
+                        const notifResult = db.prepare('DELETE FROM webhook_notifications').run();
+                        counts.webhook_notifications = notifResult.changes;
+                        const whResult = db.prepare('DELETE FROM webhooks').run();
+                        counts.webhooks = whResult.changes;
+                    }
+                });
+                transaction();
+                db.close();
+            }
+            // ─── 2. Purge sati-memory.db (close, delete, recreate) ───
+            if (categories.includes('memories')) {
+                const satiRepo = SatiRepository.getInstance();
+                satiRepo.close();
+                if (fs.existsSync(satiMemoryPath)) {
+                    fs.removeSync(satiMemoryPath);
+                    fs.removeSync(satiMemoryPath + '-wal');
+                    fs.removeSync(satiMemoryPath + '-shm');
+                    counts.sati_memory = 1;
+                }
+                // Reinitialize so schema is recreated cleanly
+                satiRepo.initialize();
+            }
+            display.log(`🗑️ Data reset via Danger Zone: [${categories.join(', ')}]`, {
+                source: 'DangerZone',
+                level: 'warning',
+            });
+            res.json({
+                success: true,
+                message: 'Selected data has been reset successfully.',
+                categories,
+                deleted: counts,
+            });
+        }
+        catch (error) {
+            display.log(`❌ Danger Zone reset failed: ${error}`, {
+                source: 'DangerZone',
+                level: 'error',
+            });
+            res.status(500).json({
+                error: 'Failed to reset data',
+                details: error instanceof Error ? error.message : String(error),
+            });
+        }
+    });
+    return router;
+}

package/dist/runtime/audit/repository.js

@@ -190,6 +190,7 @@ export class AuditRepository {
         SUM(CASE WHEN ae.event_type = 'mcp_tool'        THEN 1 ELSE 0 END) as mcpToolCount,
         SUM(CASE WHEN ae.event_type = 'skill_executed'  THEN 1 ELSE 0 END) as skillCount,
         SUM(CASE WHEN ae.event_type = 'memory_recovery' THEN 1 ELSE 0 END) as memoryRecoveryCount,
+        SUM(CASE WHEN ae.event_type = 'memory_persist'  THEN 1 ELSE 0 END) as memoryPersistCount,
         SUM(CASE WHEN ae.event_type = 'chronos_job'     THEN 1 ELSE 0 END) as chronosJobCount,
         SUM(CASE WHEN ae.event_type = 'task_created'    THEN 1 ELSE 0 END) as taskCreatedCount,
         SUM(CASE WHEN ae.event_type = 'task_completed'  THEN 1 ELSE 0 END) as taskCompletedCount,
@@ -304,6 +305,7 @@ export class AuditRepository {
                 mcpToolCount: totalsRow?.mcpToolCount ?? 0,
                 skillCount: totalsRow?.skillCount ?? 0,
                 memoryRecoveryCount: totalsRow?.memoryRecoveryCount ?? 0,
+                memoryPersistCount: totalsRow?.memoryPersistCount ?? 0,
                 chronosJobCount: totalsRow?.chronosJobCount ?? 0,
                 taskCreatedCount: totalsRow?.taskCreatedCount ?? 0,
                 taskCompletedCount: totalsRow?.taskCompletedCount ?? 0,

package/dist/runtime/memory/sati/index.js

@@ -65,7 +65,7 @@ export class SatiMemoryMiddleware {
     async afterAgent(generatedResponse, history, userSessionId) {
         try {
             await this.service.evaluateAndPersist([
-                ...history.slice(-5).map(m => ({
+                ...history.map(m => ({
                     role: m._getType() === 'human' ? 'user' : 'assistant',
                     content: m.content.toString()
                 })),

package/dist/runtime/memory/sati/service.js

@@ -209,6 +209,33 @@ export class SatiService {
                     display.log(`Deletion skipped — memory not found: ${deletion.id}`, { source: 'Sati', level: 'warning' });
                 }
             }
+            // Emit audit event for memory persistence results
+            const inclusionsCount = (result.inclusions ?? []).filter(i => i.summary && i.category && i.importance).length;
+            const editsCount = (result.edits ?? []).filter(e => !!e.id).length;
+            const deletionsCount = (result.deletions ?? []).filter(d => !!d.id).length;
+            const totalOps = inclusionsCount + editsCount + deletionsCount;
+            if (totalOps > 0) {
+                try {
+                    AuditRepository.getInstance().insert({
+                        session_id: userSessionId ?? 'sati-persist',
+                        event_type: 'memory_persist',
+                        agent: 'sati',
+                        duration_ms: Date.now() - satiStartMs,
+                        status: 'success',
+                        metadata: {
+                            inclusions_count: inclusionsCount,
+                            edits_count: editsCount,
+                            deletions_count: deletionsCount,
+                            inclusions: (result.inclusions ?? []).filter(i => i.summary && i.category && i.importance).map(i => ({ category: i.category, importance: i.importance, summary: i.summary })),
+                            edits: (result.edits ?? []).filter(e => !!e.id).map(e => ({ id: e.id, summary: e.summary, reason: e.reason })),
+                            deletions: (result.deletions ?? []).filter(d => !!d.id).map(d => ({ id: d.id, reason: d.reason })),
+                        },
+                    });
+                }
+                catch {
+                    console.warn('[SatiService] Failed to log memory persistence audit event');
+                }
+            }
         }
         catch (error) {
             console.error('[SatiService] Evaluation failed:', error);

package/dist/runtime/memory/session-embedding-worker.js

@@ -18,77 +18,84 @@ export async function runSessionEmbeddingWorker() {
     // 🔥 importante: carregar vec0 no DB onde existe a tabela vetorial
     loadVecExtension(satiDb);
     const embeddingService = await EmbeddingService.getInstance();
-    while (true) {
-        const sessions = shortDb.prepare(`
+    try {
+        while (true) {
+            const sessions = shortDb.prepare(`
       SELECT id
       FROM sessions
       WHERE ended_at IS NOT NULL
         AND embedding_status = 'pending'
       LIMIT ?
     `).all(BATCH_LIMIT);
-        if (sessions.length === 0) {
-            // display.log('✅ Nenhuma sessão pendente.', { level: 'debug', source: 'SessionEmbeddingWorker' });
-            break;
-        }
-        for (const session of sessions) {
-            const sessionId = session.id;
-            display.log(`🧠 Processando sessão ${sessionId}...`, { source: 'SessionEmbeddingWorker' });
-            try {
-                // Skip setting 'processing' as it violates CHECK constraint
-                // active_processing.add(sessionId); // If we needed concurrency control
-                const chunks = satiDb.prepare(`
+            if (sessions.length === 0) {
+                // display.log('✅ Nenhuma sessão pendente.', { level: 'debug', source: 'SessionEmbeddingWorker' });
+                break;
+            }
+            for (const session of sessions) {
+                const sessionId = session.id;
+                display.log(`🧠 Processando sessão ${sessionId}...`, { source: 'SessionEmbeddingWorker' });
+                try {
+                    // Skip setting 'processing' as it violates CHECK constraint
+                    // active_processing.add(sessionId); // If we needed concurrency control
+                    const chunks = satiDb.prepare(`
           SELECT id, content
           FROM session_chunks
           WHERE session_id = ?
           ORDER BY chunk_index
         `).all(sessionId);
-                if (chunks.length === 0) {
-                    display.log(`⚠️ Sessão ${sessionId} não possui chunks.`, { source: 'SessionEmbeddingWorker' });
-                    shortDb.prepare(`
+                    if (chunks.length === 0) {
+                        display.log(`⚠️ Sessão ${sessionId} não possui chunks.`, { source: 'SessionEmbeddingWorker' });
+                        shortDb.prepare(`
             UPDATE sessions
             SET embedding_status = 'embedded',
                 embedded = 1
             WHERE id = ?
           `).run(sessionId);
-                    continue;
-                }
-                const insertVec = satiDb.prepare(`
+                        continue;
+                    }
+                    const insertVec = satiDb.prepare(`
           INSERT INTO session_vec (embedding)
           VALUES (?)
         `);
-                const insertMap = satiDb.prepare(`
+                    const insertMap = satiDb.prepare(`
           INSERT OR REPLACE INTO session_embedding_map
           (session_chunk_id, vec_rowid)
           VALUES (?, ?)
         `);
-                for (const chunk of chunks) {
-                    display.log(`   ↳ Embedding chunk ${chunk.id}`, { source: 'SessionEmbeddingWorker' });
-                    const embedding = await embeddingService.generate(chunk.content);
-                    if (!embedding || embedding.length !== EMBEDDING_DIM) {
-                        throw new Error(`Embedding inválido. Esperado ${EMBEDDING_DIM}, recebido ${embedding?.length}`);
+                    for (const chunk of chunks) {
+                        display.log(`   ↳ Embedding chunk ${chunk.id}`, { source: 'SessionEmbeddingWorker' });
+                        const embedding = await embeddingService.generate(chunk.content);
+                        if (!embedding || embedding.length !== EMBEDDING_DIM) {
+                            throw new Error(`Embedding inválido. Esperado ${EMBEDDING_DIM}, recebido ${embedding?.length}`);
+                        }
+                        const result = insertVec.run(new Float32Array(embedding));
+                        const vecRowId = result.lastInsertRowid;
+                        insertMap.run(chunk.id, vecRowId);
                     }
-                    const result = insertVec.run(new Float32Array(embedding));
-                    const vecRowId = result.lastInsertRowid;
-                    insertMap.run(chunk.id, vecRowId);
-                }
-                // ✅ finalizar sessão
-                shortDb.prepare(`
+                    // ✅ finalizar sessão
+                    shortDb.prepare(`
           UPDATE sessions
           SET embedding_status = 'embedded',
               embedded = 1
           WHERE id = ?
         `).run(sessionId);
-                display.log(`✅ Sessão ${sessionId} embedada com sucesso.`, { source: 'SessionEmbeddingWorker' });
-            }
-            catch (err) {
-                display.log(`❌ Erro na sessão ${sessionId}: ${err}`, { source: 'SessionEmbeddingWorker' });
-                shortDb.prepare(`
+                    display.log(`✅ Sessão ${sessionId} embedada com sucesso.`, { source: 'SessionEmbeddingWorker' });
+                }
+                catch (err) {
+                    display.log(`❌ Erro na sessão ${sessionId}: ${err}`, { source: 'SessionEmbeddingWorker' });
+                    shortDb.prepare(`
           UPDATE sessions
           SET embedding_status = 'failed'
           WHERE id = ?
         `).run(sessionId);
+                }
             }
         }
     }
+    finally {
+        // Always close connections when done
+        shortDb.close();
+        satiDb.close();
+    }
     // display.log('🏁 Worker finalizado.', { source: 'SessionEmbeddingWorker' });
 }

package/dist/runtime/oracle.js

@@ -17,6 +17,8 @@ import { MCPManager } from "../config/mcp-manager.js";
 import { SkillRegistry, SkillExecuteTool, SkillDelegateTool, updateSkillToolDescriptions } from "./skills/index.js";
 import { SmithRegistry } from "./smiths/registry.js";
 import { AuditRepository } from "./audit/repository.js";
+import { SetupRepository } from './setup/repository.js';
+import { buildSetupTool } from './tools/setup-tool.js';
 import { emitToolAuditEvents } from "./subagent-utils.js";
 const ORACLE_DELEGATION_TOOLS = new Set([
     'apoc_delegate', 'neo_delegate', 'trinity_delegate', 'smith_delegate',
@@ -154,7 +156,10 @@ export class Oracle {
             await Trinity.refreshDelegateCatalog().catch(() => { });
             updateSkillToolDescriptions();
             // Build tool list — conditionally include SmithDelegateTool based on config
+            // Initialize setup repository (creates table if needed)
+            SetupRepository.getInstance();
             const coreTools = [
+                buildSetupTool(),
                 TaskQueryTool,
                 Neo.getInstance().createDelegateTool(),
                 Apoc.getInstance().createDelegateTool(),
@@ -222,8 +227,25 @@ export class Oracle {
             if (extraUsage) {
                 userMessage.usage_metadata = extraUsage;
             }
-            const systemMessage = new SystemMessage(`
-You are ${this.config.agent.name}, ${this.config.agent.personality}, the Oracle.
+            // Build first-time setup block if setup is not yet completed
+            const setupRepo = SetupRepository.getInstance();
+            let setupBlock = '';
+            if (!setupRepo.isCompleted()) {
+                const missingFields = setupRepo.getMissingFields();
+                if (missingFields.length > 0) {
+                    setupBlock = `## [FIRST-TIME SETUP — ACTIVE]
+Before responding to any other request, you MUST collect the user's basic information.
+Ask for the following fields conversationally (one or two at a time — do NOT list them all at once):
+${missingFields.map((f) => `- ${f}`).join('\n')}
+
+Once the user provides a value, immediately call \`setup_save\` with the collected fields.
+Do NOT proceed with other tasks until all required fields have been collected and saved.
+---
+
+`;
+                }
+            }
+            const systemMessage = new SystemMessage(`${setupBlock}You are ${this.config.agent.name}, ${this.config.agent.personality}, the Oracle.
 
 You are an orchestrator and task router.
 
@@ -360,6 +382,11 @@ ${SmithRegistry.getInstance().getSystemPromptSection()}
                 databasePath: this.databasePath,
                 limit: this.config.llm?.context_window ?? 100,
             });
+            // Ensure the session row exists in the DB before we try to persist
+            // messages.  Without this, external callers (webhooks, chronos) that
+            // supply a custom session_id would hit "Sessão não encontrada" inside
+            // addMessages → setSessionTitleIfNeeded → renameSession.
+            callHistory.ensureSession(currentSessionId ?? 'default');
             // Load existing history from database in reverse order (most recent first)
             let previousMessages = await callHistory.getMessages();
             previousMessages = previousMessages.reverse();
@@ -623,6 +650,7 @@ Use it to inform your response and tool selection (if needed), but do not assume
         await Trinity.refreshDelegateCatalog().catch(() => { });
         updateSkillToolDescriptions();
         this.provider = await ProviderFactory.create(this.config.llm, [
+            buildSetupTool(),
             TaskQueryTool,
             Neo.getInstance().createDelegateTool(),
             Apoc.getInstance().createDelegateTool(),

package/dist/runtime/setup/__tests__/repository.test.js

@@ -0,0 +1,115 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import * as fs from 'fs-extra';
+import * as path from 'path';
+import { tmpdir } from 'os';
+import { SetupRepository } from '../repository.js';
+import { ConfigManager } from '../../../config/manager.js';
+// Mock ConfigManager so tests are not coupled to the real config file
+vi.mock('../../../config/manager.js', () => ({
+    ConfigManager: {
+        getInstance: vi.fn(() => ({
+            getSetupConfig: vi.fn(() => ({ enabled: true, fields: ['name', 'city'] })),
+        })),
+    },
+}));
+describe('SetupRepository', () => {
+    let testDbPath;
+    beforeEach(() => {
+        const tempDir = path.join(tmpdir(), 'morpheus-setup-test', Date.now().toString());
+        fs.ensureDirSync(tempDir);
+        testDbPath = path.join(tempDir, 'short-memory.db');
+        // Reset singleton so each test gets a fresh instance
+        SetupRepository.resetInstance();
+    });
+    afterEach(() => {
+        SetupRepository.resetInstance();
+        // Clean up temp DB
+        const tempDir = path.dirname(testDbPath);
+        try {
+            fs.removeSync(tempDir);
+        }
+        catch {
+            // ignore — Windows may delay file release
+        }
+    });
+    describe('initialize()', () => {
+        it('should create setup_state table on construction', () => {
+            const repo = SetupRepository.getInstance(testDbPath);
+            // If table was created, isCompleted() should not throw
+            expect(() => repo.isCompleted()).not.toThrow();
+        });
+    });
+    describe('isCompleted()', () => {
+        it('returns false when __completed__ record does not exist', () => {
+            const repo = SetupRepository.getInstance(testDbPath);
+            expect(repo.isCompleted()).toBe(false);
+        });
+        it('returns true after markCompleted() is called', () => {
+            const repo = SetupRepository.getInstance(testDbPath);
+            repo.markCompleted();
+            expect(repo.isCompleted()).toBe(true);
+        });
+        it('returns true when setup.enabled is false even without __completed__ record', () => {
+            // Override mock for this test only
+            vi.mocked(ConfigManager.getInstance).mockReturnValueOnce({
+                getSetupConfig: vi.fn(() => ({ enabled: false, fields: ['name'] })),
+            });
+            const repo = SetupRepository.getInstance(testDbPath);
+            expect(repo.isCompleted()).toBe(true);
+        });
+    });
+    describe('saveField() / getMissingFields()', () => {
+        it('getMissingFields returns all configured fields initially', () => {
+            const repo = SetupRepository.getInstance(testDbPath);
+            const missing = repo.getMissingFields();
+            expect(missing).toEqual(['name', 'city']);
+        });
+        it('removes a field from missing list after saving it', () => {
+            const repo = SetupRepository.getInstance(testDbPath);
+            repo.saveField('name', 'João');
+            const missing = repo.getMissingFields();
+            expect(missing).toEqual(['city']);
+            expect(missing).not.toContain('name');
+        });
+        it('returns empty array when all fields are saved', () => {
+            const repo = SetupRepository.getInstance(testDbPath);
+            repo.saveField('name', 'João');
+            repo.saveField('city', 'Brasília');
+            expect(repo.getMissingFields()).toEqual([]);
+        });
+        it('upserts a field on second save', () => {
+            const repo = SetupRepository.getInstance(testDbPath);
+            repo.saveField('name', 'João');
+            repo.saveField('name', 'Carlos');
+            // Should still have only one entry for name (no duplicate)
+            expect(repo.getMissingFields()).toEqual(['city']);
+        });
+    });
+    describe('markCompleted()', () => {
+        it('is idempotent (can be called multiple times without error)', () => {
+            const repo = SetupRepository.getInstance(testDbPath);
+            expect(() => {
+                repo.markCompleted();
+                repo.markCompleted();
+                repo.markCompleted();
+            }).not.toThrow();
+            expect(repo.isCompleted()).toBe(true);
+        });
+    });
+    describe('reset()', () => {
+        it('clears all records including __completed__', () => {
+            const repo = SetupRepository.getInstance(testDbPath);
+            repo.saveField('name', 'João');
+            repo.saveField('city', 'Brasília');
+            repo.markCompleted();
+            expect(repo.isCompleted()).toBe(true);
+            repo.reset();
+            expect(repo.isCompleted()).toBe(false);
+            expect(repo.getMissingFields()).toEqual(['name', 'city']);
+        });
+        it('is safe to call on empty table', () => {
+            const repo = SetupRepository.getInstance(testDbPath);
+            expect(() => repo.reset()).not.toThrow();
+        });
+    });
+});