auq-mcp-server 2.6.4 → 2.7.0

package/README.md

@@ -212,6 +212,38 @@ Whenever you need clarification on what you are working on, never guess, and cal
 
 When the AI asks questions, you'll see them appear in the AUQ TUI. Answer them **at your convenience**.
 
+### Renderer Selection
+
+AUQ supports two terminal rendering engines:
+
+| Renderer          | Description                                         | Status              |
+| ----------------- | --------------------------------------------------- | ------------------- |
+| **ink** (default) | React-based terminal renderer                       | Stable              |
+| **OpenTUI**       | Native Zig-based renderer with improved performance | Opt-in/Experimental |
+
+**To use OpenTUI**, set one of the following (in priority order):
+
+1. **Environment variable** (highest priority):
+
+   ```bash
+   AUQ_RENDERER=opentui auq
+   ```
+
+2. **Config file** (`.auqrc.json`):
+
+   ```json
+   {
+     "renderer": "opentui"
+   }
+   ```
+
+3. **CLI command**:
+   ```bash
+   auq config set renderer opentui
+   ```
+
+> **Note:** OpenTUI is currently opt-in and experimental. It provides native CJK character support, built-in markdown rendering with syntax highlighting, and mouse support. The environment variable overrides any config setting.
+
 ### Markdown rendering in question prompts
 
 Question prompts now support **Markdown formatting** in the `prompt` text.
@@ -240,6 +272,15 @@ It is recommended to **disable** the built-in questioning tool in your harness (
 | `Ctrl+R` | Quick Submit  | Auto-select recommended options for all questions and go to review |
 | `Esc`    | Reject        | Reject the whole question set and optionally explain why to the AI |
 | `Ctrl+T` | Theme         | Cycle through available color themes                               |
+| `[`/`]`  | Sessions      | Switch to previous/next session (OpenTUI: also click session dots) |
+
+**Mouse Support (OpenTUI renderer only):**
+
+| Action            | Description                                     |
+| ----------------- | ----------------------------------------------- |
+| Click option      | Select/toggle option                            |
+| Scroll            | Scroll through session picker or update overlay |
+| Click session dot | Switch to that session                          |
 
 <details>
 <summary><strong>More Commands (advanced)</strong></summary>
@@ -372,10 +413,21 @@ Update checks are automatically disabled in CI environments (`CI=true`).
 
 The `auq update` command always works regardless of these settings.
 
-### 🎨 Themes
+### Theme System
 
 AUQ supports **16 built-in color themes** with automatic persistence. Press `Ctrl+T` to cycle through themes.
 
+#### Theme Differences by Renderer
+
+| Feature          | ink                | OpenTUI                                   |
+| ---------------- | ------------------ | ----------------------------------------- |
+| Header text      | Gradient animation | Solid accent color                        |
+| Toast animations | `setTimeout` based | `useTimeline` based                       |
+| Markdown syntax  | Basic highlighting | Tree-sitter powered                       |
+| Mouse support    | No                 | Yes (click options, scroll, session dots) |
+
+> Both renderers support all 16 built-in themes and custom themes. Colors are consistent; only implementation details differ.
+
 <details>
 <summary><strong>Built-in Themes</strong></summary>
 
@@ -547,12 +599,13 @@ _Settings from local config override global config, which overrides defaults._
 
 ```json
 {
+  "renderer": "ink",
   "maxOptions": 5,
   "maxQuestions": 5,
   "recommendedOptions": 4,
   "recommendedQuestions": 4,
   "sessionTimeout": 0,
-  "retentionPeriod": 604800000, // 7 days
+  "retentionPeriod": 604800000,
   "language": "auto",
   "theme": "system",
   "autoSelectRecommended": true,
@@ -569,6 +622,7 @@ _Settings from local config override global config, which overrides defaults._
 
 | Setting                 | Type    | Default   | Range/Values                    | Description                                           |
 | ----------------------- | ------- | --------- | ------------------------------- | ----------------------------------------------------- |
+| `renderer`              | string  | "ink"     | "ink", "opentui"                | Terminal rendering engine (ink or OpenTUI)            |
 | `maxOptions`            | number  | 5         | 2-10                            | Maximum options per question                          |
 | `maxQuestions`          | number  | 5         | 1-10                            | Maximum questions per session                         |
 | `recommendedOptions`    | number  | 4         | 1-10                            | Suggested number of options (for AI guidance)         |

package/dist/bin/auq.js

@@ -21,10 +21,19 @@ Commands:
   sessions <sub> [flags] List/dismiss sessions
   config <sub> [flags]   Get/set configuration
   update                 Check for and install updates
+  fetch-answers [flags]  Fetch answers for non-blocking sessions
+  history [sub] [flags]  Browse session history
+
+Ask:
+  auq ask '<json>'
+  auq ask -                              (read JSON from stdin)
+  Format: {"questions":[{"prompt":"...","title":"...","options":[{"label":"..."}]}]}
 
 Answer:
-  auq answer <id> --answers '<json>'    Submit answers
-  auq answer <id> --reject [--reason]   Reject session
+  auq answer <id> --answers '<json>'         Submit answers
+  auq answer <id> --reject [--reason "text"]  Reject session
+  Format: --answers '{"0":{"selectedOption":"Label"}}'
+          Keys = question indices (0,1,2…); values: selectedOption, selectedOptions[], customText
   Flags: --force  --json
 
 Sessions:
@@ -32,9 +41,19 @@ Sessions:
   auq sessions show <id> [--json]
   auq sessions dismiss <id> [--force] [--json]
 
+Fetch Answers:
+  auq fetch-answers [session-id] [--blocking] [--json]
+  auq fetch-answers --unread [--json]
+
+History:
+  auq history [--all] [--json] [--limit N] [--unread] [--search TEXT]
+  auq history show <id> [--json]
+
 Config:
   auq config get [key] [--json]
   auq config set <key> <value> [--global] [--json]
+  Keys: maxOptions (2-10)  maxQuestions (1-10)  sessionTimeout (ms)
+        theme  language  renderer (ink|opentui)  staleAction (warn|remove|archive)
 
 Options:
   -h, --help      Show this help
@@ -46,7 +65,7 @@ Keys (TUI):
   [/] sessions  1-9 jump  Ctrl+S picker  Ctrl+T theme
 
 Config: ./.auqrc.json (local) > ~/.config/auq/.auqrc.json (global)
-Env:    AUQ_SESSION_DIR  XDG_CONFIG_HOME`);
+Env:    AUQ_SESSION_DIR  XDG_CONFIG_HOME  AUQ_RENDERER`);
     process.exit(0);
 }
 // Display version
@@ -214,6 +233,20 @@ if (command === "config") {
     await updateNotification;
     process.exit(0);
 }
+// Handle 'fetch-answers' command
+if (command === "fetch-answers") {
+    const { runFetchAnswersCommand } = await import("../src/cli/commands/fetch-answers.js");
+    await runFetchAnswersCommand(args.slice(1));
+    await updateNotification;
+    process.exit(0);
+}
+// Handle 'history' command
+if (command === "history") {
+    const { runHistoryCommand } = await import("../src/cli/commands/history.js");
+    await runHistoryCommand(args.slice(1));
+    await updateNotification;
+    process.exit(0);
+}
 // Default: Start TUI
 // Important: Lazy-load Ink/React so non-interactive commands (ask/server) don't pull them in.
 // Also force production mode before importing React/Ink to avoid perf_hooks measure accumulation warnings.

package/dist/bin/tui-app.js

@@ -1,6 +1,7 @@
 import { Box, render, Text, useInput } from "ink";
 import { promises as fs } from "fs";
 import React, { useCallback, useEffect, useMemo, useRef, useState, } from "react";
+import { DEFAULT_CONFIG } from "../src/config/defaults.js";
 import { ensureDirectoryExists, getSessionDirectory, } from "../src/session/utils.js";
 import { Header } from "../src/tui/components/Header.js";
 import { SessionDots } from "../src/tui/components/SessionDots.js";
@@ -11,10 +12,10 @@ import { Toast } from "../src/tui/components/Toast.js";
 import { WaitingScreen } from "../src/tui/components/WaitingScreen.js";
 import { createNotificationBatcher, showProgress, clearProgress, calculateProgress, checkLinuxDependencies, } from "../src/tui/notifications/index.js";
 import { createTUIWatcher } from "../src/tui/session-watcher.js";
-import { isSessionStale, isSessionAbandoned, formatStaleToastMessage, } from "../src/tui/utils/staleDetection.js";
+import { isSessionStale, isSessionAbandoned, formatStaleToastMessage, } from "../src/tui/shared/utils/staleDetection.js";
 import { ThemeProvider } from "../src/tui/ThemeProvider.js";
 import { ConfigProvider } from "../src/tui/ConfigContext.js";
-import { getAdjustedIndexAfterRemoval, getDirectJumpIndex, getNextSessionIndex, getPrevSessionIndex, } from "../src/tui/utils/sessionSwitching.js";
+import { getAdjustedIndexAfterRemoval, getDirectJumpIndex, getNextSessionIndex, getPrevSessionIndex, } from "../src/tui/shared/utils/sessionSwitching.js";
 import { UpdateChecker, fetchChangelog, installUpdate, detectPackageManager, readCache, writeCache, } from "../src/update/index.js";
 import { UpdateOverlay } from "../src/tui/components/UpdateOverlay.js";
 import { KEYS } from "../src/tui/constants/keybindings.js";
@@ -37,6 +38,7 @@ const App = ({ config }) => {
     const [installError, setInstallError] = useState(null);
     const [changelogContent, setChangelogContent] = useState(null);
     const [updateDismissed, setUpdateDismissed] = useState(false);
+    const [isCheckingUpdate, setIsCheckingUpdate] = useState(false);
     // Get session directory for logging
     const sessionDir = getSessionDirectory();
     // Notification configuration from config
@@ -182,7 +184,8 @@ const App = ({ config }) => {
                 // Silently fail — update checks should never break the TUI
             }
         };
-        runCheck();
+        setIsCheckingUpdate(true);
+        void runCheck().finally(() => { setIsCheckingUpdate(false); });
         intervalId = setInterval(() => {
             checker.clearCache();
             runCheck();
@@ -540,7 +543,7 @@ const App = ({ config }) => {
                             updateType: updateInfo.updateType,
                             latestVersion: updateInfo.latestVersion,
                         }
-                        : null, onUpdateBadgeActivate: () => setShowUpdateOverlay(true) }),
+                        : null, onUpdateBadgeActivate: () => setShowUpdateOverlay(true), isCheckingUpdate: isCheckingUpdate }),
                 mainContent,
                 state.mode === "PROCESSING" && sessionQueue.length >= 2 && (React.createElement(SessionDots, { sessions: sessionQueue.map((s) => ({
                         ...s,
@@ -564,7 +567,7 @@ const App = ({ config }) => {
                 showUpdateOverlay && updateInfo && (React.createElement(UpdateOverlay, { isOpen: showUpdateOverlay, currentVersion: updateInfo.currentVersion, latestVersion: updateInfo.latestVersion, updateType: updateInfo.updateType, changelog: changelogContent, changelogUrl: updateInfo.changelogUrl, isInstalling: isInstallingUpdate, installError: installError, onInstall: handleUpdateInstall, onSkipVersion: handleSkipVersion, onRemindLater: handleRemindLater })),
                 React.createElement(ThemeIndicator, null)))));
 };
-export const runTui = (config) => {
+async function runInkTui(config) {
     // Clear terminal before showing app
     console.clear();
     // 1-tick AI agent hint: ANSI hidden attribute makes it invisible to humans,
@@ -576,8 +579,26 @@ export const runTui = (config) => {
         process.exit(0);
     });
     // Show goodbye after Ink unmounts
-    waitUntilExit().then(() => {
+    await waitUntilExit().then(() => {
         process.stdout.write("\n");
         console.log("👋 Goodbye! See you next time.");
     });
+}
+export const runTui = async (config) => {
+    const mergedConfig = { ...DEFAULT_CONFIG, ...config };
+    const rendererType = process.env.AUQ_RENDERER || mergedConfig.renderer || "opentui";
+    if (rendererType === "opentui") {
+        try {
+            const opentuiPath = "../src/tui-opentui/app.js";
+            const { runTui: runOpenTui } = (await import(opentuiPath));
+            await runOpenTui(mergedConfig);
+        }
+        catch (err) {
+            console.warn(`⚠️ OpenTUI failed to initialize: ${err instanceof Error ? err.message : String(err)}. Falling back to ink renderer.`);
+            await runInkTui(mergedConfig);
+        }
+    }
+    else {
+        await runInkTui(mergedConfig);
+    }
 };

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "auq-mcp-server",
-    "version": "2.6.4",
+    "version": "2.7.0",
     "main": "dist/index.js",
     "bin": {
         "auq": "dist/bin/auq.js"
@@ -28,7 +28,10 @@
         "generate:skill": "bun run scripts/generate-skill.ts",
         "validate:skill": "bunx skills-ref validate skills/ask-user-questions",
         "test": "vitest run",
-        "format": "prettier --write . && eslint --fix ."
+        "format": "prettier --write . && eslint --fix .",
+        "build:opentui": "tsc -p tsconfig.opentui.json --noEmit",
+        "test:opentui": "bun test src/tui-opentui",
+        "typecheck:all": "tsc --noEmit && tsc -p tsconfig.opentui.json --noEmit"
     },
     "keywords": [
         "fastmcp",
@@ -50,6 +53,8 @@
     "description": "An MCP server that provides a tool to ask a user questions via the terminal",
     "dependencies": {
         "@inkjs/ui": "^2.0.0",
+        "@opentui/core": "0.1.87",
+        "@opentui/react": "0.1.87",
         "@modelcontextprotocol/sdk": "1.17.2",
         "@types/uuid": "^10.0.0",
         "chalk": "^5.6.2",

package/dist/src/__tests__/schema-validation.test.js

@@ -3,7 +3,8 @@
  * Tests the most common edge cases to catch obvious bugs
  */
 import { describe, expect, it } from "vitest";
-import { QuestionSchema, QuestionsSchema } from "../core/ask-user-questions.js";
+import { QuestionSchema, QuestionsSchema, AskUserQuestionsParametersSchema } from "../core/ask-user-questions.js";
+import { GetAnsweredQuestionsArgsSchema } from "../shared/schemas.js";
 describe("Schema Validation - Edge Cases", () => {
     describe("Invalid Input (should reject)", () => {
         it("should reject missing title field", () => {
@@ -176,3 +177,62 @@ describe("Schema Validation - Edge Cases", () => {
         });
     });
 });
+describe("nonBlocking parameter", () => {
+    const validQuestion = {
+        options: [{ label: "Option A" }, { label: "Option B" }],
+        prompt: "Which do you prefer?",
+        title: "Preference",
+        multiSelect: false,
+    };
+    it("should accept nonBlocking: true", () => {
+        const result = AskUserQuestionsParametersSchema.parse({
+            questions: [validQuestion],
+            nonBlocking: true,
+        });
+        expect(result.nonBlocking).toBe(true);
+    });
+    it("should accept nonBlocking: false", () => {
+        const result = AskUserQuestionsParametersSchema.parse({
+            questions: [validQuestion],
+            nonBlocking: false,
+        });
+        expect(result.nonBlocking).toBe(false);
+    });
+    it("should default nonBlocking to false when omitted", () => {
+        const result = AskUserQuestionsParametersSchema.parse({
+            questions: [validQuestion],
+        });
+        expect(result.nonBlocking).toBe(false);
+    });
+    it("should reject non-boolean nonBlocking", () => {
+        expect(() => AskUserQuestionsParametersSchema.parse({
+            questions: [validQuestion],
+            nonBlocking: "yes",
+        })).toThrow();
+    });
+});
+describe("GetAnsweredQuestionsArgsSchema", () => {
+    it("should accept valid session_id", () => {
+        const result = GetAnsweredQuestionsArgsSchema.parse({
+            session_id: "a3f2e8b1-1234-4567-89ab-cdef01234567",
+        });
+        expect(result.session_id).toBe("a3f2e8b1-1234-4567-89ab-cdef01234567");
+        expect(result.blocking).toBe(false);
+    });
+    it("should accept session_id with blocking: true", () => {
+        const result = GetAnsweredQuestionsArgsSchema.parse({
+            session_id: "a3f2e8b1",
+            blocking: true,
+        });
+        expect(result.blocking).toBe(true);
+    });
+    it("should reject missing session_id", () => {
+        expect(() => GetAnsweredQuestionsArgsSchema.parse({})).toThrow();
+    });
+    it("should reject non-boolean blocking", () => {
+        expect(() => GetAnsweredQuestionsArgsSchema.parse({
+            session_id: "test",
+            blocking: "yes",
+        })).toThrow();
+    });
+});

package/dist/src/cli/commands/__tests__/fetch-answers.test.js

@@ -0,0 +1,310 @@
+/**
+ * Integration tests for the `auq fetch-answers` CLI command.
+ */
+import { promises as fs } from "fs";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { SessionManager } from "../../../session/SessionManager.js";
+import { runFetchAnswersCommand } from "../fetch-answers.js";
+// ── Helpers ────────────────────────────────────────────────────────────────
+const testBaseDir = "/tmp/auq-test-cli-fetch-answers";
+const sampleQuestions = [
+    {
+        title: "Language",
+        prompt: "Which language do you prefer?",
+        options: [
+            { label: "TypeScript", description: "Typed JS" },
+            { label: "Python", description: "Scripting" },
+        ],
+    },
+    {
+        title: "Framework",
+        prompt: "Pick a framework",
+        options: [
+            { label: "React" },
+            { label: "Vue" },
+        ],
+    },
+];
+// Stub getSessionDirectory so the fetch-answers command always targets our temp dir.
+vi.mock("../../../session/utils.js", async (importOriginal) => {
+    const actual = (await importOriginal());
+    return {
+        ...actual,
+        getSessionDirectory: () => testBaseDir,
+    };
+});
+/**
+ * Helper: create a completed session with answers saved.
+ */
+async function createCompletedSession(sessionManager, questions = sampleQuestions) {
+    const sessionId = await sessionManager.createSession(questions);
+    const answersData = {
+        sessionId,
+        timestamp: new Date().toISOString(),
+        answers: questions.map((q, i) => ({
+            questionIndex: i,
+            timestamp: new Date().toISOString(),
+            selectedOption: q.options[0].label,
+        })),
+    };
+    await sessionManager.saveSessionAnswers(sessionId, answersData);
+    await sessionManager.updateSessionStatus(sessionId, "completed");
+    return sessionId;
+}
+// ── Test Suite ─────────────────────────────────────────────────────────────
+describe("fetch-answers command", () => {
+    let sessionManager;
+    let consoleLogSpy;
+    let consoleErrorSpy;
+    beforeEach(async () => {
+        await fs.rm(testBaseDir, { force: true, recursive: true }).catch(() => { });
+        sessionManager = new SessionManager({ baseDir: testBaseDir });
+        await sessionManager.initialize();
+        process.exitCode = undefined;
+        consoleLogSpy = vi.spyOn(console, "log").mockImplementation(() => { });
+        consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => { });
+    });
+    afterEach(async () => {
+        consoleLogSpy.mockRestore();
+        consoleErrorSpy.mockRestore();
+        vi.restoreAllMocks();
+        process.exitCode = undefined;
+        await fs.rm(testBaseDir, { force: true, recursive: true }).catch(() => { });
+    });
+    // ── Fetch specific session ──────────────────────────────────────────────
+    describe("fetch specific session", () => {
+        it("should display formatted answers for completed session", async () => {
+            const sessionId = await createCompletedSession(sessionManager);
+            await runFetchAnswersCommand([sessionId]);
+            expect(process.exitCode).toBeUndefined();
+            const allOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            // Should contain answer content from the session
+            expect(allOutput).toBeTruthy();
+            expect(allOutput.length).toBeGreaterThan(0);
+        });
+        it("should mark session as read after fetching", async () => {
+            const sessionId = await createCompletedSession(sessionManager);
+            // Should not be in unread before fetching (actually it IS unread)
+            const unreadBefore = await sessionManager.getUnreadSessions();
+            expect(unreadBefore).toContain(sessionId);
+            await runFetchAnswersCommand([sessionId]);
+            // After fetching, session should be marked as read
+            const unreadAfter = await sessionManager.getUnreadSessions();
+            expect(unreadAfter).not.toContain(sessionId);
+        });
+        it("should display pending status for pending session (non-blocking)", async () => {
+            const sessionId = await sessionManager.createSession(sampleQuestions);
+            await runFetchAnswersCommand([sessionId]);
+            expect(process.exitCode).toBeUndefined();
+            const allOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            // Should contain some output (pending status)
+            expect(allOutput).toBeTruthy();
+        });
+        it("should display rejected status", async () => {
+            const sessionId = await sessionManager.createSession(sampleQuestions);
+            await sessionManager.updateSessionStatus(sessionId, "rejected");
+            await runFetchAnswersCommand([sessionId]);
+            expect(process.exitCode).toBeUndefined();
+            const allOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(allOutput).toBeTruthy();
+        });
+        it("should resolve short session ID (8-char prefix)", async () => {
+            const sessionId = await createCompletedSession(sessionManager);
+            const shortId = sessionId.slice(0, 8);
+            await runFetchAnswersCommand([shortId]);
+            expect(process.exitCode).toBeUndefined();
+            const allOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(allOutput).toBeTruthy();
+        });
+        it("should error for non-existent full-UUID session", async () => {
+            const fakeId = "00000000-0000-4000-a000-000000000000";
+            await runFetchAnswersCommand([fakeId]);
+            expect(process.exitCode).toBe(1);
+            const errOutput = consoleErrorSpy.mock.calls.map((c) => c[0]).join("\n");
+            const logOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            const combined = errOutput + logOutput;
+            expect(combined).toContain(fakeId);
+        });
+        it("should error for non-existent 8-char prefix", async () => {
+            const fakeShortId = "deadbeef";
+            await runFetchAnswersCommand([fakeShortId]);
+            expect(process.exitCode).toBe(1);
+        });
+    });
+    // ── --json flag ─────────────────────────────────────────────────────────
+    describe("--json flag", () => {
+        it("should output valid JSON for completed session", async () => {
+            const sessionId = await createCompletedSession(sessionManager);
+            await runFetchAnswersCommand([sessionId, "--json"]);
+            expect(process.exitCode).toBeUndefined();
+            // Find valid JSON in console.log calls
+            const jsonCalls = consoleLogSpy.mock.calls.filter((c) => {
+                try {
+                    JSON.parse(c[0]);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            });
+            expect(jsonCalls.length).toBeGreaterThanOrEqual(1);
+            const parsed = JSON.parse(jsonCalls[0][0]);
+            expect(parsed.sessionId).toBe(sessionId);
+            expect(parsed.status).toBe("completed");
+            expect(Array.isArray(parsed.answers)).toBe(true);
+            expect(parsed.answers).toHaveLength(2);
+            expect(parsed.lastReadAt).toBeDefined();
+        });
+        it("should output valid JSON for pending session", async () => {
+            const sessionId = await sessionManager.createSession(sampleQuestions);
+            await runFetchAnswersCommand([sessionId, "--json"]);
+            const jsonCalls = consoleLogSpy.mock.calls.filter((c) => {
+                try {
+                    JSON.parse(c[0]);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            });
+            expect(jsonCalls.length).toBeGreaterThanOrEqual(1);
+            const parsed = JSON.parse(jsonCalls[0][0]);
+            expect(parsed.sessionId).toBe(sessionId);
+            expect(parsed.status).toBe("pending");
+            expect(parsed.answers).toBeNull();
+        });
+        it("should output valid JSON for rejected session", async () => {
+            const sessionId = await sessionManager.createSession(sampleQuestions);
+            await sessionManager.updateSessionStatus(sessionId, "rejected");
+            await runFetchAnswersCommand([sessionId, "--json"]);
+            const jsonCalls = consoleLogSpy.mock.calls.filter((c) => {
+                try {
+                    JSON.parse(c[0]);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            });
+            expect(jsonCalls.length).toBeGreaterThanOrEqual(1);
+            const parsed = JSON.parse(jsonCalls[0][0]);
+            expect(parsed.sessionId).toBe(sessionId);
+            expect(parsed.status).toBe("rejected");
+        });
+    });
+    // ── Unread / no session-id mode ─────────────────────────────────────────
+    describe("unread / default mode (no session-id)", () => {
+        it("should list unread sessions when no session-id provided", async () => {
+            const id1 = await createCompletedSession(sessionManager);
+            const id2 = await createCompletedSession(sessionManager);
+            await runFetchAnswersCommand([]);
+            expect(process.exitCode).toBeUndefined();
+            const allOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(allOutput).toContain(id1.slice(0, 8));
+            expect(allOutput).toContain(id2.slice(0, 8));
+        });
+        it("should show message when no unread sessions", async () => {
+            await runFetchAnswersCommand([]);
+            expect(process.exitCode).toBeUndefined();
+            const allOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(allOutput.toLowerCase()).toContain("no unread");
+        });
+        it("should exclude already-read sessions from default unread list", async () => {
+            const sessionId = await createCompletedSession(sessionManager);
+            // Mark as read first
+            await sessionManager.markSessionAsRead(sessionId);
+            await runFetchAnswersCommand([]);
+            const allOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            // Session should NOT appear in unread list
+            expect(allOutput).not.toContain(sessionId.slice(0, 8));
+        });
+        it("should list unread sessions with explicit --unread flag", async () => {
+            const sessionId = await createCompletedSession(sessionManager);
+            await runFetchAnswersCommand(["--unread"]);
+            expect(process.exitCode).toBeUndefined();
+            const allOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(allOutput).toContain(sessionId.slice(0, 8));
+        });
+        it("should output valid JSON array for unread list with --json", async () => {
+            const id1 = await createCompletedSession(sessionManager);
+            const id2 = await createCompletedSession(sessionManager);
+            await runFetchAnswersCommand(["--json"]);
+            expect(process.exitCode).toBeUndefined();
+            const jsonCalls = consoleLogSpy.mock.calls.filter((c) => {
+                try {
+                    JSON.parse(c[0]);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            });
+            expect(jsonCalls.length).toBeGreaterThanOrEqual(1);
+            const parsed = JSON.parse(jsonCalls[0][0]);
+            expect(Array.isArray(parsed)).toBe(true);
+            expect(parsed.length).toBe(2);
+            // Both session IDs appear in result
+            const ids = parsed.map((e) => e.sessionId);
+            expect(ids).toContain(id1);
+            expect(ids).toContain(id2);
+        });
+        it("should output empty JSON array when no unread sessions with --json", async () => {
+            await runFetchAnswersCommand(["--json"]);
+            const jsonCalls = consoleLogSpy.mock.calls.filter((c) => {
+                try {
+                    JSON.parse(c[0]);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            });
+            expect(jsonCalls.length).toBeGreaterThanOrEqual(1);
+            const parsed = JSON.parse(jsonCalls[0][0]);
+            expect(Array.isArray(parsed)).toBe(true);
+            expect(parsed.length).toBe(0);
+        });
+    });
+    // ── --blocking with no session id ───────────────────────────────────────
+    describe("--blocking flag validation", () => {
+        it("should error when --blocking used without a session ID", async () => {
+            await runFetchAnswersCommand(["--blocking"]);
+            expect(process.exitCode).toBe(1);
+            // Should have some error output (either console.error or console.log JSON error)
+            const logOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            const errOutput = consoleErrorSpy.mock.calls.map((c) => c[0]).join("\n");
+            const combined = logOutput + errOutput;
+            expect(combined.toLowerCase()).toMatch(/blocking|session id/i);
+        });
+    });
+    // ── lastReadAt tracking ─────────────────────────────────────────────────
+    describe("read tracking", () => {
+        it("should set lastReadAt when fetching a completed session", async () => {
+            const sessionId = await createCompletedSession(sessionManager);
+            const before = new Date();
+            await runFetchAnswersCommand([sessionId]);
+            const after = new Date();
+            const answers = await sessionManager.getSessionAnswers(sessionId);
+            expect(answers).not.toBeNull();
+            expect(answers.lastReadAt).toBeDefined();
+            const readAt = new Date(answers.lastReadAt);
+            expect(readAt.getTime()).toBeGreaterThanOrEqual(before.getTime() - 1000);
+            expect(readAt.getTime()).toBeLessThanOrEqual(after.getTime() + 1000);
+        });
+        it("should not appear in unread list after being fetched", async () => {
+            const sessionId = await createCompletedSession(sessionManager);
+            // Before fetch — should be unread
+            const unreadBefore = await sessionManager.getUnreadSessions();
+            expect(unreadBefore).toContain(sessionId);
+            await runFetchAnswersCommand([sessionId]);
+            // After fetch — should be removed from unread list
+            const unreadAfter = await sessionManager.getUnreadSessions();
+            expect(unreadAfter).not.toContain(sessionId);
+            // Running --unread should also not show it
+            consoleLogSpy.mockClear();
+            await runFetchAnswersCommand(["--unread"]);
+            const unreadOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(unreadOutput).not.toContain(sessionId.slice(0, 8));
+        });
+    });
+});