qlogicagent 2.13.4 → 2.13.5

package/dist/orchestration/solo-evaluator.js

@@ -0,0 +1,611 @@
+/**
+ * Solo Mode Evaluator — parallel N-agent PK with user-triggered evaluation.
+ *
+ * Flow:
+ *   1. solo.start → create N isolated git worktrees, spawn N agents in parallel
+ *   2. Each agent receives the same task prompt in its own worktree
+ *      (all agents share initial config: memory/rules from project .qlogicagent/)
+ *   3. On completion of initial task, agents enter "idle" state (process kept alive)
+ *   4. User can send follow-up messages to individual agents via solo.message
+ *   5. User triggers evaluation via solo.evaluate (or skips directly to solo.select)
+ *   6. solo.select → merge winning worktree, clean up others
+ *
+ * Key design:
+ *   - Solo = special project type (persisted in .qlogicagent/solos/)
+ *   - Agents share the same initial config but operate in isolated worktrees
+ *   - User controls the evaluation timing (not automatic)
+ *   - Follow-up instructions to individual agents supported
+ *
+ * Degradation: if K agents fail but ≥1 succeeds, session remains interactive.
+ */
+import { randomUUID } from "node:crypto";
+import { findGitRoot, createWorktree, getWorktreeDiff, removeWorktree, mergeWorktree, } from "./product-worktree.js";
+import { saveSoloState, listSoloSessions, deleteSoloState } from "./solo-persistence.js";
+/** Extract human-readable text from a sendTask result so the UI shows content, not raw JSON. */
+function extractResultText(result) {
+    if (typeof result === "string")
+        return result;
+    if (result && typeof result === "object") {
+        const r = result;
+        if (typeof r.content === "string")
+            return r.content;
+        if (typeof r.text === "string")
+            return r.text;
+    }
+    return result == null ? "" : JSON.stringify(result);
+}
+/** Render a SoloSpec as the <spec> block injected into each competitor's enrichedTask (spec §7). */
+function buildSpecBlock(spec) {
+    const lines = ["<spec>", `目标: ${spec.goal}`];
+    if (spec.constraints.length) {
+        lines.push("约束:");
+        spec.constraints.forEach((c, i) => lines.push(`  ${i + 1}. ${c}`));
+    }
+    if (spec.acceptance.length) {
+        lines.push("验收标准(必须全部满足):");
+        spec.acceptance.forEach((a, i) => lines.push(`  ${i + 1}. ${a}`));
+    }
+    lines.push("</spec>");
+    return lines.join("\n");
+}
+/**
+ * Assemble the prompt every competitor receives (Cut4). Shared context (rules/memory) + optional
+ * <spec> block, then the body. Body = spec.rawTask when a Spec was built (the task captured during
+ * specBuild), else the raw task. With neither sharedConfig nor spec the result is exactly `task`
+ * (regression-safe vs the pre-Spec path).
+ */
+export function buildEnrichedTask(task, sharedConfig, spec) {
+    const contextParts = [];
+    if (sharedConfig?.rules?.length) {
+        contextParts.push(`<rules>\n${sharedConfig.rules.join("\n")}\n</rules>`);
+    }
+    if (sharedConfig?.memory?.length) {
+        contextParts.push(`<memory>\n${sharedConfig.memory.join("\n")}\n</memory>`);
+    }
+    if (spec) {
+        contextParts.push(buildSpecBlock(spec));
+    }
+    const body = spec?.rawTask?.trim() || task;
+    return contextParts.length > 0 ? `${contextParts.join("\n\n")}\n\n${body}` : body;
+}
+/**
+ * Build the judge prompt (Cut4). When the Spec defines acceptance criteria, the judge scores
+ * per-criterion (满足/部分/不满足) instead of a subjective compare. The WINNER:/REASONING: output
+ * markers are unchanged so parseEvaluationResponse still works — only the basis of REASONING upgrades.
+ */
+export function buildEvaluationPrompt(originalTask, spec, succeeded) {
+    const sections = [
+        `# Task Evaluation`,
+        ``,
+        `## Original Task`,
+        originalTask,
+        ``,
+    ];
+    // Surface the Spec goal/constraints so the judge evaluates against the clarified intent. Gated on
+    // spec presence (not spec.goal) so an acceptance rubric always carries its goal/constraints header.
+    if (spec) {
+        sections.push(`## Spec`, ``, `**目标:** ${spec.goal}`);
+        if (spec.constraints.length) {
+            sections.push(`**约束:**`, ...spec.constraints.map((c, i) => `${i + 1}. ${c}`));
+        }
+        sections.push(``);
+    }
+    sections.push(`## Agent Results`, ``);
+    for (const agent of succeeded) {
+        sections.push(`### Agent: ${agent.displayId}`, ``, `**Result:**`, agent.resultText ?? "(no output)", ``, `**Changes (git diff stat):**`, agent.diff || "(no changes)", ``);
+    }
+    const hasRubric = !!spec?.acceptance?.length;
+    if (hasRubric) {
+        sections.push(`## 评比基准(Acceptance Criteria)`, ``, `逐条核对每个 agent 是否满足以下验收标准:`, ...spec.acceptance.map((a, i) => `${i + 1}. ${a}`), ``);
+    }
+    sections.push(`## Instructions`, ``, hasRubric
+        ? `Review all agent results above. For EACH agent, judge every acceptance criterion as 满足/部分/不满足, then select the agent that best satisfies the criteria overall.`
+        : `Review all agent results above. Select the best implementation and explain your reasoning.`, `Respond in this exact format:`, ``, `WINNER: <agent-id>`, hasRubric
+        ? `REASONING: <按每条验收标准逐条说明各 agent 的满足情况与最终取舍依据>`
+        : `REASONING: <your explanation>`);
+    return sections.join("\n");
+}
+// ── Solo Evaluator ──────────────────────────────────────────
+export class SoloEvaluator {
+    processManager;
+    acpDetector;
+    configStore;
+    callbacks;
+    sessions = new Map();
+    constructor(processManager, acpDetector, configStore, callbacks = {}) {
+        this.processManager = processManager;
+        this.acpDetector = acpDetector;
+        this.configStore = configStore;
+        this.callbacks = callbacks;
+    }
+    /** Persist current session data to disk (fire-and-forget). */
+    persistSession(session) {
+        const state = {
+            soloId: session.soloId,
+            state: session.state,
+            task: session.task,
+            cwd: session.cwd,
+            gitRoot: session.gitRoot,
+            agents: session.agents.map(a => ({
+                agentId: a.agentId,
+                displayId: a.displayId,
+                memberId: a.memberId,
+                worktreePath: a.worktreePath,
+                worktreeBranch: a.worktreeBranch,
+                state: a.state,
+                resultText: a.resultText,
+                diff: a.diff,
+                usage: a.usage,
+                error: a.error,
+                turns: a.turns,
+            })),
+            evaluation: session.evaluation,
+            spec: session.spec,
+            createdAt: session.createdAt,
+        };
+        saveSoloState(state, session.cwd).catch(() => { });
+    }
+    /** Restore sessions from disk (call once at startup). */
+    async restoreFromDisk(cwd) {
+        const persisted = await listSoloSessions(cwd);
+        for (const s of persisted) {
+            if (!this.sessions.has(s.soloId)) {
+                this.sessions.set(s.soloId, {
+                    soloId: s.soloId,
+                    state: s.state,
+                    task: s.task,
+                    cwd: s.cwd,
+                    gitRoot: s.gitRoot,
+                    agents: s.agents.map(a => ({ ...a, displayId: a.displayId ?? a.agentId, turns: a.turns ?? [] })),
+                    evaluation: s.evaluation,
+                    spec: s.spec,
+                    createdAt: s.createdAt,
+                });
+            }
+        }
+        return persisted.length;
+    }
+    /** Delete a solo session from memory and disk. */
+    async deleteSolo(soloId) {
+        this.sessions.delete(soloId);
+        return deleteSoloState(soloId);
+    }
+    /**
+     * Start a Solo Mode PK session.
+     * Creates worktrees, spawns agents in parallel, waits for completion, then evaluates.
+     */
+    async start(params) {
+        const { task, agents: agentIds, cwd, sharedConfig, spec } = params;
+        if (agentIds.length < 2) {
+            throw new Error("Solo Mode requires at least 2 agents");
+        }
+        // 启动 pre-check: every selected agent must be installed + configured. Block here rather than
+        // spawn N worktrees only to have an agent fail its turn ("No LLM provider"/auth). qlogicagent
+        // self-resolves; external agents need an ACP descriptor + (for key-auth) the key configured.
+        const unready = [...new Set(agentIds)].filter((id) => !this.acpDetector.isAgentReady(id));
+        if (unready.length > 0) {
+            throw new Error(`以下 agent 未安装或未配置,请先到欢迎页安装并配置:${unready.join("、")}`);
+        }
+        const gitRoot = await findGitRoot(cwd);
+        if (!gitRoot) {
+            throw new Error("Solo Mode requires a git repository");
+        }
+        // Build the prompt every competitor receives: shared context (rules/memory) + optional Spec
+        // (Cut4) so results are directly comparable. See buildEnrichedTask.
+        const enrichedTask = buildEnrichedTask(task, sharedConfig, spec);
+        const soloId = `solo-${randomUUID().slice(0, 8)}`;
+        const session = {
+            soloId,
+            state: "running",
+            task,
+            cwd,
+            gitRoot,
+            agents: [],
+            spec,
+            createdAt: Date.now(),
+        };
+        this.sessions.set(soloId, session);
+        this.persistSession(session);
+        this.callbacks.log?.info(`[solo] starting ${soloId} with ${agentIds.length} agents`);
+        // Per-agent runner: worktree → spawn → task → collect, emitting live progress/diff/usage.
+        // Runs in the BACKGROUND (see below) so start() can return soloId immediately.
+        const runOne = async (agent, worktreeName) => {
+            const { agentId, displayId, memberId } = agent;
+            try {
+                agent.worktreePath = await createWorktree(gitRoot, worktreeName);
+                const descriptor = this.acpDetector.buildExternalDescriptor(agentId);
+                if (!descriptor)
+                    throw new Error(`Agent ${agentId} is not available or not ACP-compatible`);
+                await this.processManager.spawn({
+                    memberId,
+                    name: `solo-${agentId}`,
+                    cwd: agent.worktreePath,
+                    prompt: enrichedTask,
+                    external: descriptor,
+                });
+                const handle = this.processManager.getHandle(memberId);
+                if (!handle || handle.state !== "ready")
+                    throw new Error(`Agent ${agentId} spawn did not reach ready state`);
+                // Child text deltas stream to the UI live via the pm's onNotification → solo.agentDelta
+                // (see solo-handler). sendTask resolves with the final turn result.
+                const result = await this.processManager.sendTask(memberId, enrichedTask);
+                agent.state = "completed";
+                agent.resultText = extractResultText(result);
+                agent.diff = await getWorktreeDiff(agent.worktreePath);
+                agent.turns.push({ role: "user", content: task, timestamp: Date.now() });
+                agent.turns.push({ role: "agent", content: agent.resultText, timestamp: Date.now() });
+                const usageTracker = this.processManager.getUsageTracker(memberId);
+                if (usageTracker?.hasData()) {
+                    const usage = usageTracker.getUsage();
+                    agent.usage = { inputTokens: usage.inputTokens, outputTokens: usage.outputTokens };
+                }
+                this.callbacks.onProgress?.(soloId, displayId, "completed");
+                if (agent.diff)
+                    this.callbacks.onAgentDiff?.(soloId, displayId, [{ path: ".", hunks: agent.diff }]);
+                if (agent.usage)
+                    this.callbacks.onAgentUsage?.(soloId, displayId, agent.usage.inputTokens, agent.usage.outputTokens);
+                this.callbacks.log?.info(`[solo] ${displayId} completed (diff: ${agent.diff ? "yes" : "none"})`);
+            }
+            catch (err) {
+                agent.state = "failed";
+                agent.error = err instanceof Error ? err.message : String(err);
+                this.callbacks.onProgress?.(soloId, displayId, "failed", agent.error);
+                this.callbacks.log?.warn(`[solo] ${displayId} failed: ${agent.error}`);
+            }
+            this.persistSession(session);
+        };
+        // Synchronously create every agent placeholder + emit "running" so the create-result returns
+        // instantly with all columns shown. Disambiguate duplicates (qlogicagent×2 → "#1"/"#2").
+        const placeholders = agentIds.map((agentId, idx) => {
+            const worktreeName = `${soloId}-${agentId}-${idx}`;
+            const memberId = `${soloId}:${agentId}:${idx}`;
+            const sameAgentTotal = agentIds.filter((a) => a === agentId).length;
+            const occurrence = agentIds.slice(0, idx).filter((a) => a === agentId).length;
+            const displayId = sameAgentTotal > 1 ? `${agentId} #${occurrence + 1}` : agentId;
+            const agent = {
+                agentId, displayId, memberId,
+                worktreePath: "", worktreeBranch: `solo/${worktreeName}`,
+                state: "running", turns: [],
+            };
+            session.agents.push(agent);
+            this.callbacks.onProgress?.(soloId, displayId, "running");
+            return { agent, worktreeName };
+        });
+        this.persistSession(session);
+        // Run all agents in the BACKGROUND (non-blocking). start() returns soloId now — a long
+        // competition never trips the RPC timeout, and progress/delta/diff/usage stream live. When the
+        // batch settles, flip completed→idle (process stays alive for follow-ups / winner selection).
+        void Promise.allSettled(placeholders.map((p) => runOne(p.agent, p.worktreeName))).then(async () => {
+            // If cancel() flipped this session terminal while agents were still running, the cancel path
+            // already set state="cancelled" + fired onTerminal. Killing the agents makes them all settle
+            // as "failed", so without this guard the all-failed branch below would clobber "cancelled" →
+            // "failed" and double-fire onTerminal (turning the project's planStatus from cancelled to
+            // completed). A cancelled race is terminal; nothing left to evaluate.
+            if (session.state === "cancelled")
+                return;
+            const succeeded = session.agents.filter((a) => a.state === "completed");
+            for (const agent of session.agents) {
+                if (agent.state === "completed")
+                    agent.state = "idle";
+            }
+            if (succeeded.length === 0) {
+                session.state = "failed";
+                this.persistSession(session);
+                this.callbacks.onTerminal?.(soloId, "failed");
+                this.callbacks.log?.warn(`[solo] all agents failed for ${soloId}`);
+                return;
+            }
+            this.persistSession(session);
+            this.callbacks.log?.info(`[solo] ${succeeded.length}/${session.agents.length} agents ready for interaction`);
+            // Auto-evaluate: the main agent (a qlogicagent instance, else the first finisher) judges
+            // all results + picks a winner, so the competition resolves itself with no manual step.
+            try {
+                const judge = succeeded.find((a) => a.agentId === "qlogicagent") ?? succeeded[0];
+                session.state = "evaluating";
+                this.persistSession(session);
+                this.callbacks.log?.info(`[solo] auto-evaluating ${soloId} via ${judge.displayId} (${succeeded.length} candidates)`);
+                const evaluation = await this.evaluate(session, succeeded, judge);
+                session.evaluation = evaluation;
+                session.state = "running"; // stay alive until the user selects/merges the winner
+                this.callbacks.onEvaluation?.(soloId, evaluation);
+                this.persistSession(session);
+                this.callbacks.log?.info(`[solo] auto-evaluation winner: ${evaluation.winnerId}`);
+            }
+            catch (err) {
+                session.state = "running";
+                this.persistSession(session);
+                this.callbacks.log?.warn(`[solo] auto-evaluation failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        });
+        return soloId;
+    }
+    /**
+     * Send a follow-up message to a specific agent within a solo session.
+     * Agent must be in "idle" or "completed" state.
+     */
+    async message(soloId, agentId, content, agentIndex) {
+        const session = this.sessions.get(soloId);
+        if (!session)
+            throw new Error(`Solo session ${soloId} not found`);
+        if (session.state !== "running") {
+            throw new Error(`Solo session ${soloId} is not active (state: ${session.state})`);
+        }
+        // Find the target agent (support agentIndex for duplicate IDs)
+        const candidates = session.agents.filter(a => a.agentId === agentId);
+        const agent = agentIndex !== undefined ? candidates[agentIndex] : candidates[0];
+        if (!agent) {
+            throw new Error(`Agent ${agentId} not found in solo session ${soloId}`);
+        }
+        const validStates = ["idle", "completed"];
+        if (!validStates.includes(agent.state)) {
+            throw new Error(`Agent ${agentId} is not ready for messages (state: ${agent.state})`);
+        }
+        // Record the user message
+        agent.turns.push({ role: "user", content, timestamp: Date.now() });
+        agent.state = "running";
+        this.callbacks.onProgress?.(soloId, agentId, "running");
+        try {
+            const result = await this.processManager.sendTask(agent.memberId, content);
+            const resultText = typeof result === "string"
+                ? result
+                : result?.content ?? JSON.stringify(result);
+            // Record agent response
+            agent.turns.push({ role: "agent", content: resultText, timestamp: Date.now() });
+            agent.resultText = resultText;
+            agent.diff = await getWorktreeDiff(agent.worktreePath);
+            agent.state = "idle";
+            // Update usage
+            const usageTracker = this.processManager.getUsageTracker(agent.memberId);
+            if (usageTracker?.hasData()) {
+                const usage = usageTracker.getUsage();
+                agent.usage = { inputTokens: usage.inputTokens, outputTokens: usage.outputTokens };
+            }
+            this.callbacks.onProgress?.(soloId, agentId, "idle");
+            this.persistSession(session);
+            return { resultText };
+        }
+        catch (err) {
+            agent.state = "failed";
+            agent.error = err instanceof Error ? err.message : String(err);
+            this.callbacks.onProgress?.(soloId, agentId, "failed", agent.error);
+            this.persistSession(session);
+            throw err;
+        }
+    }
+    /**
+     * User-triggered evaluation — compare all completed/idle agents' results.
+     * The user chooses which agent in the session performs the evaluation comparison.
+     */
+    async triggerEvaluation(soloId, evaluatorAgentId, evaluatorIndex) {
+        const session = this.sessions.get(soloId);
+        if (!session)
+            throw new Error(`Solo session ${soloId} not found`);
+        const ready = session.agents.filter(a => a.state === "completed" || a.state === "idle");
+        if (ready.length === 0) {
+            throw new Error(`No agents have completed work in session ${soloId}`);
+        }
+        // Find the evaluator agent (must be in the session)
+        const evaluatorCandidates = session.agents.filter(a => a.agentId === evaluatorAgentId);
+        const evaluator = evaluatorIndex !== undefined ? evaluatorCandidates[evaluatorIndex] : evaluatorCandidates[0];
+        if (!evaluator) {
+            throw new Error(`Evaluator agent ${evaluatorAgentId} not found in session ${soloId}`);
+        }
+        if (evaluator.state !== "idle" && evaluator.state !== "completed") {
+            throw new Error(`Evaluator agent ${evaluatorAgentId} is not ready (state: ${evaluator.state})`);
+        }
+        session.state = "evaluating";
+        this.callbacks.log?.info(`[solo] user-triggered evaluation for ${soloId} by ${evaluatorAgentId} (${ready.length} candidates)`);
+        try {
+            const evaluation = await this.evaluate(session, ready, evaluator);
+            session.evaluation = evaluation;
+            // Keep agents alive until user calls solo.select
+            session.state = "running";
+            this.callbacks.onEvaluation?.(soloId, evaluation);
+            this.persistSession(session);
+            return evaluation;
+        }
+        catch (err) {
+            session.state = "running"; // evaluation failed, session still active
+            this.persistSession(session);
+            throw new Error(`Evaluation failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /** Map a spawned member back to its solo run + UI column id (for live delta forwarding). */
+    getMemberContext(memberId) {
+        for (const session of this.sessions.values()) {
+            const agent = session.agents.find((a) => a.memberId === memberId);
+            if (agent) {
+                // During the evaluation turn the judge is one of the competitors; don't let its verdict
+                // text ("WINNER: …") leak into its own column — that surfaces via solo.evaluation instead.
+                if (session.state === "evaluating")
+                    return null;
+                return { soloId: session.soloId, displayId: agent.displayId };
+            }
+        }
+        return null;
+    }
+    /** Get the current status of a solo session. */
+    getStatus(soloId) {
+        const session = this.sessions.get(soloId);
+        if (!session)
+            return null;
+        return {
+            soloId: session.soloId,
+            state: session.state,
+            agents: session.agents.map(a => ({
+                id: a.displayId ?? a.agentId,
+                state: a.state,
+                progress: a.state === "running" ? "Working..." : undefined,
+                resultText: a.resultText,
+                diff: a.diff,
+                usage: a.usage,
+                error: a.error,
+                worktreePath: a.worktreePath,
+            })),
+            evaluation: session.evaluation,
+        };
+    }
+    /** Cancel a running solo session. Kill all agents and clean up worktrees. */
+    async cancel(soloId) {
+        const session = this.sessions.get(soloId);
+        if (!session)
+            throw new Error(`Solo session ${soloId} not found`);
+        if (session.state !== "running" && session.state !== "evaluating") {
+            throw new Error(`Solo session ${soloId} is not running (state: ${session.state})`);
+        }
+        session.state = "cancelled";
+        // Kill all running/idle agents (synchronous — kill is non-blocking).
+        for (const agent of session.agents) {
+            if (agent.state === "running" || agent.state === "pending" || agent.state === "idle") {
+                agent.state = "failed";
+                agent.error = "Cancelled by user";
+                try {
+                    this.processManager.kill(agent.memberId);
+                }
+                catch { /* already gone */ }
+            }
+        }
+        this.persistSession(session);
+        this.callbacks.onTerminal?.(soloId, "cancelled");
+        // Worktree cleanup is fire-and-forget: on Windows removing a worktree whose process just died
+        // can be slow/block on file locks, and awaiting it stalled the cancel RPC past the client's
+        // timeout (cancel felt broken). Return immediately; cleanupWorktrees has its own per-agent
+        // try/catch so a failure can't crash anything.
+        void this.cleanupWorktrees(session);
+        this.callbacks.log?.info(`[solo] cancelled ${soloId} (worktree cleanup running in background)`);
+    }
+    /**
+     * Select a winner and merge their worktree into the main branch.
+     */
+    async select(params) {
+        const session = this.sessions.get(params.soloId);
+        if (!session)
+            throw new Error(`Solo session ${params.soloId} not found`);
+        // Allow selection from running (agents idle) or completed state
+        if (session.state !== "completed" && session.state !== "running") {
+            throw new Error(`Solo session ${params.soloId} is not ready for selection (state: ${session.state})`);
+        }
+        const winner = session.agents.find(a => (a.displayId === params.winnerId || a.agentId === params.winnerId)
+            && (a.state === "completed" || a.state === "idle"));
+        if (!winner) {
+            throw new Error(`Agent ${params.winnerId} is not a completed participant in ${params.soloId}`);
+        }
+        // Merge winner's worktree branch
+        const mergeResult = await mergeWorktree(session.gitRoot, winner.worktreeBranch);
+        this.callbacks.log?.info(`[solo] merged ${winner.worktreeBranch}: ${mergeResult}`);
+        // Mark session completed
+        session.state = "completed";
+        // Clean up ALL worktrees (including winner's)
+        await this.cleanupWorktrees(session);
+        this.persistSession(session);
+        return winner.worktreeBranch;
+    }
+    /** List all solo sessions. */
+    listSessions() {
+        return [...this.sessions.values()].map(s => this.getStatus(s.soloId));
+    }
+    /** Delete a solo session, killing agents and cleaning up worktrees if still active. */
+    async delete(soloId) {
+        const session = this.sessions.get(soloId);
+        if (!session)
+            throw new Error(`Solo session ${soloId} not found`);
+        // Cancel first if still running
+        if (session.state === "running" || session.state === "evaluating") {
+            session.state = "cancelled";
+            for (const agent of session.agents) {
+                if (agent.state === "running" || agent.state === "pending" || agent.state === "idle") {
+                    agent.state = "failed";
+                    agent.error = "Deleted";
+                    try {
+                        this.processManager.kill(agent.memberId);
+                    }
+                    catch { /* already gone */ }
+                }
+            }
+            // Terminal writeback: deleting a still-running session must persist the bound project's
+            // planStatus (else it stays stuck "running" — same class as the cancel-clobber bug). cancel()
+            // does this; delete() must too.
+            this.callbacks.onTerminal?.(soloId, "cancelled");
+            await this.cleanupWorktrees(session);
+        }
+        this.sessions.delete(soloId);
+        await deleteSoloState(soloId, session?.cwd);
+        this.callbacks.log?.info(`[solo] deleted ${soloId}`);
+    }
+    // ── Internal ──────────────────────────────────────────────
+    /**
+     * Build an evaluation prompt and send to the user-chosen evaluator agent.
+     * Returns evaluation result.
+     */
+    async evaluate(session, succeeded, evaluatorAgent) {
+        if (succeeded.length === 1) {
+            // Only one success — auto-select as winner
+            return {
+                winnerId: succeeded[0].displayId,
+                reasoning: `Only one agent (${succeeded[0].displayId}) completed successfully.`,
+            };
+        }
+        // Build the judge prompt — spec-aware (acceptance rubric) when a Spec is present (Cut4).
+        const evaluationPrompt = buildEvaluationPrompt(session.task, session.spec, succeeded);
+        // Use the user-chosen evaluator agent's process
+        const evaluatorMemberId = evaluatorAgent.memberId;
+        try {
+            const result = await this.processManager.sendTask(evaluatorMemberId, evaluationPrompt);
+            // Extract the agent's actual text (content/text field) — NOT JSON.stringify(result), which
+            // wrapped the whole { content, stopReason } object and leaked `,"stopReason":"end_turn"}`
+            // into the parsed REASONING. Mirrors runOne's extractResultText(result).
+            const text = extractResultText(result);
+            return this.parseEvaluationResponse(text, succeeded);
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            // Surface WHY both in the server log and the user-visible reasoning (the bare `catch {}`
+            // here used to swallow the cause, leaving only a mystery fallback winner). Still degrade to
+            // the first completed agent so the run resolves.
+            this.callbacks.log?.warn(`[solo] evaluator ${evaluatorAgent.displayId} sendTask failed: ${detail}`);
+            return {
+                winnerId: succeeded[0].displayId,
+                reasoning: `Evaluation failed (${detail}); defaulting to first completed agent.`,
+            };
+        }
+    }
+    parseEvaluationResponse(text, candidates) {
+        // Match the WINNER by displayId (unique even for qlogicagent×N). Try exact "WINNER: <id>"
+        // first, then any displayId substring (longest first so "#10" beats "#1").
+        const reasoningMatch = text.match(/REASONING:\s*(.+)/is);
+        const ids = candidates.map(c => c.displayId).sort((a, b) => b.length - a.length);
+        const winnerLine = text.match(/WINNER:\s*(.+)/i)?.[1]?.trim();
+        const exact = winnerLine && ids.find(id => winnerLine === id || winnerLine.startsWith(id));
+        if (exact) {
+            return { winnerId: exact, reasoning: reasoningMatch?.[1]?.trim() || "Selected by evaluation." };
+        }
+        for (const id of ids) {
+            if (text.includes(id)) {
+                return { winnerId: id, reasoning: reasoningMatch?.[1]?.trim() || text.slice(0, 500) };
+            }
+        }
+        // Final fallback
+        return {
+            winnerId: candidates[0].displayId,
+            reasoning: `Could not parse evaluation. Full response: ${text.slice(0, 500)}`,
+        };
+    }
+    async cleanupWorktrees(session) {
+        for (const agent of session.agents) {
+            if (agent.worktreePath) {
+                try {
+                    // Kill the process first if still alive
+                    try {
+                        this.processManager.kill(agent.memberId);
+                    }
+                    catch { /* already gone */ }
+                    this.processManager.remove(agent.memberId);
+                    await removeWorktree(session.gitRoot, agent.worktreePath);
+                }
+                catch (err) {
+                    this.callbacks.log?.warn(`[solo] failed to clean worktree for ${agent.agentId}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        }
+    }
+}

package/dist/orchestration/solo-persistence.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Solo Persistence — read/write Solo Mode state to disk.
+ *
+ * State is stored at `<project>/.qlogicagent/solos/<soloId>/solo-state.json`.
+ * Mirrors the product-persistence.ts pattern.
+ */
+import type { PathService } from "../runtime/ports/index.js";
+import type { SoloState, SoloAgentState, SoloEvaluation, SoloSpec } from "../protocol/wire/acp-agent-management.js";
+export interface PersistedSoloState {
+    soloId: string;
+    state: SoloState;
+    task: string;
+    cwd: string;
+    gitRoot: string;
+    agents: Array<{
+        agentId: string;
+        memberId: string;
+        worktreePath: string;
+        worktreeBranch: string;
+        state: SoloAgentState;
+        resultText?: string;
+        diff?: string;
+        usage?: {
+            inputTokens: number;
+            outputTokens: number;
+        };
+        error?: string;
+        turns?: Array<{
+            role: "user" | "agent";
+            content: string;
+            timestamp: number;
+        }>;
+    }>;
+    evaluation?: SoloEvaluation;
+    spec?: SoloSpec;
+    createdAt: number;
+}
+export interface SoloPersistenceOptions {
+    pathService?: PathService;
+}
+/** Save solo state to disk. */
+export declare function saveSoloState(state: PersistedSoloState, cwd?: string, options?: SoloPersistenceOptions): Promise<void>;
+/** Load solo state from disk. Returns undefined if not found. */
+export declare function loadSoloState(soloId: string, cwd?: string, options?: SoloPersistenceOptions): Promise<PersistedSoloState | undefined>;
+/** List all solo session IDs with their persisted state. */
+export declare function listSoloSessions(cwd?: string, options?: SoloPersistenceOptions): Promise<PersistedSoloState[]>;
+/** Delete solo state from disk. */
+export declare function deleteSoloState(soloId: string, cwd?: string, options?: SoloPersistenceOptions): Promise<boolean>;