@cjhyy/code-shell-core 0.5.0-rc.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 maki maki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,162 @@
+# @cjhyy/code-shell-core
+
+UI-agnostic agent orchestration framework. The headless core of [`code-shell`](https://github.com/cjhyy/codeshell): turn an LLM + a tool registry + a transcript into a multi-turn agent loop, with permissions, hooks, MCP support, and pluggable approval backends.
+
+Compatible with Anthropic and OpenAI-protocol providers (Claude, DeepSeek, GPT, Gemini, Qwen, …). No terminal UI dependencies — embed it in a CLI, a web service, a Slack bot, a desktop app.
+
+## Install
+
+```bash
+npm install @cjhyy/code-shell-core
+# or
+bun add @cjhyy/code-shell-core
+```
+
+Requires Node ≥ 20.10.
+
+## Quickstart
+
+```ts
+import {
+  Engine,
+  HeadlessApprovalBackend,
+} from "@cjhyy/code-shell-core";
+
+const engine = new Engine({
+  llm: {
+    provider: "anthropic",
+    model: "claude-sonnet-4-6",
+    apiKey: process.env.ANTHROPIC_API_KEY!,
+  },
+  cwd: process.cwd(),
+  // Headless approval — "approve-all" trusts the model fully; use
+  // "approve-read-only" or a custom ApprovalBackend in production.
+  approvalBackend: new HeadlessApprovalBackend("approve-all"),
+  headless: true,
+});
+
+const result = await engine.run(
+  "list files in this directory and summarise their purpose",
+);
+
+console.log(result.text);
+console.log("turns:", result.turnCount, "reason:", result.reason);
+```
+
+Streaming events:
+
+```ts
+await engine.run("...", {
+  onStream(event) {
+    if (event.type === "text_delta") process.stdout.write(event.text);
+    if (event.type === "tool_use_start") console.log("→", event.toolCall);
+  },
+});
+```
+
+Restrict the tool set:
+
+```ts
+new Engine({
+  llm: { /* … */ },
+  // Whitelist — only these built-in tools are registered.
+  enabledBuiltinTools: ["Read", "Glob", "Grep", "WebFetch"],
+  // Or blacklist — registers every built-in except these.
+  // disabledBuiltinTools: ["Bash", "Write", "Edit"],
+});
+```
+
+## What's included
+
+- **Engine** — turn loop, transcript management, session persistence, resume.
+- **Tool system** — registry, executor, permission classifier, schema validation. Built-in tools for filesystem, shell, web fetch, sub-agents, plan mode, tasks.
+- **LLM clients** — Anthropic, OpenAI (and any OpenAI-protocol endpoint). Provider catalog covers DeepSeek, Qwen, OpenRouter, Gemini.
+- **MCP** — connect to Model Context Protocol servers (stdio / SSE / streamable-http / in-process).
+- **Hooks** — `pre_tool_use`, `post_tool_use`, `on_user_prompt_submit`, `on_session_start`, `on_session_end`, more.
+- **Protocol** — `AgentServer` / `AgentClient` over JSON-RPC for running the engine out-of-process.
+- **Run manager** — queue, schedule, and persist multi-engine workflows.
+
+## Designing for production
+
+- **Approval backend.** `HeadlessApprovalBackend("approve-all")` is fine for trusted prompts. For untrusted input, implement `ApprovalBackend` to gate destructive tools (Write/Edit/Bash) through your own auth.
+- **Permission rules.** Pass `permissionRules` to the engine for fine-grained allow/deny per tool + args pattern. Bash commands additionally get a built-in safety classifier (dangerous commands like `rm -rf` always require explicit approval).
+- **Hooks** are the right place for audit logging, prompt rewriting, and policy enforcement.
+- **Memory.** The engine ships with an extract-memories + auto-dream pipeline that persists to `~/.code-shell/memory/`. Disable by passing a no-op `MemoryOrchestrator`, or scope to a project by setting `CODE_SHELL_HOME`.
+
+## Recommended public API (B3 / standard §S7)
+
+The stable, recommended construction path for embedders is the
+`createServer` / `createClient` factory pair over a protocol transport.
+Direct `new Engine(...)` still works for advanced cases — but the
+protocol-mediated path is what we test, document, and avoid breaking.
+
+```ts
+import {
+  createServer,
+  createClient,
+  createInProcessTransport,
+} from "@cjhyy/code-shell-core";
+
+const [serverT, clientT] = createInProcessTransport();
+const handle = createServer({
+  transport: serverT,
+  cwd: process.cwd(),
+  llm: { provider: "anthropic", model: "claude-sonnet-4-6", apiKey: KEY },
+  permissionMode: "default",
+});
+const client = createClient({ transport: clientT });
+
+client.onStreamEvent(({ sessionId, event }) => {
+  if (event.type === "text_delta") process.stdout.write(event.text);
+});
+
+const result = await client.run({ sessionId: "main", task: "Summarize README.md" });
+console.log(result.text);
+
+handle.close();
+client.close();
+```
+
+For an out-of-process worker, swap `createInProcessTransport()` for a
+`StdioTransport` pair. The factory accepts any `Transport`, so a future
+`IpcAdapter` will compose without changing the call shape.
+
+`StreamEvent` includes `background_agent_completed` (B2.2) so embedders
+that don't poll `notificationQueue` still observe sub-agent finish/fail
+results. `client.onBackgroundAgentCompleted((sessionId, event) => …)` is
+the typed entry point; events also flow through the catch-all
+`onStreamEvent`.
+
+## Stable surface
+
+These exports are covered by the stability promise:
+
+| Area | Stable exports |
+| --- | --- |
+| Factories | `createServer`, `createClient`, `createInProcessTransport`, `StdioTransport` |
+| Server/client | `AgentServer`, `AgentClient` (direct use is supported but `createServer/Client` preferred) |
+| Engine | `Engine`, `EngineConfig`, `EngineRuntime`, `ChatSessionManager` |
+| Protocol types | `Methods`, `ErrorCodes`, `RpcMessage`, `RunResult`, `StreamEvent`, `StreamCallback`, `BackgroundAgentCompletedEvent` |
+| LLM | `LLMConfig`, `LLMResponse`, `ModelPool`, `createLLMClient`, `registerProvider` |
+| Tool authoring | `ToolDefinition`, `ToolCall`, `ToolResult`, `RegisteredTool`, `BUILTIN_TOOLS`, `HookContext`, `HookResult` |
+| Permissions | `PermissionClassifier`, `HeadlessApprovalBackend`, `AutoApprovalBackend`, `ApprovalBackend`, `PermissionMode`, `PermissionRule` |
+| Errors | `FrameworkError` + subclasses (`LLMError`, `ToolError`, `PermissionDeniedError`, …) |
+
+### Treat as internal
+
+Anything not in the table above — including direct imports from
+`./engine/...`, `./tool-system/...`, `./session/...`, `./hooks/...`
+subpaths and APIs marked `@internal` in their docstrings — may change
+between minor versions without notice. Plan to migrate via the protocol
+surface instead of deep-importing.
+
+## Stability
+
+Pre-1.0 — APIs may change between minor versions. The "stable surface"
+table above is the contract; everything else is mobile.
+
+See [CHANGELOG.md](https://github.com/cjhyy/codeshell/blob/main/CHANGELOG.md) in the monorepo.
+
+## License
+
+MIT © maki maki. See [LICENSE](./LICENSE).

package/dist/agent/coordinator.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Agent coordinator — agent registry + message bus for multi-agent communication.
+ */
+/** A registered named agent. */
+export interface AgentInfo {
+    id: string;
+    name: string;
+    status: "running" | "completed" | "failed";
+    description: string;
+    startedAt: number;
+    completedAt?: number;
+    result?: string;
+}
+/** A message between agents. */
+export interface AgentMessage {
+    from: string;
+    to: string;
+    content: string;
+    timestamp: number;
+}
+/**
+ * Singleton agent registry and message bus.
+ */
+declare class AgentCoordinator {
+    private agents;
+    private inbox;
+    /** Register a named agent. */
+    register(id: string, name: string, description: string): void;
+    /** Mark an agent as completed. */
+    complete(name: string, result?: string): void;
+    /** Mark an agent as failed. */
+    fail(name: string): void;
+    /** Get agent info by name. */
+    get(name: string): AgentInfo | undefined;
+    /** List all agents. */
+    list(): AgentInfo[];
+    /** List active (running) agents. */
+    listActive(): AgentInfo[];
+    /** Send a message to a named agent. */
+    send(from: string, to: string, content: string): boolean;
+    /** Read messages for a named agent (drains the inbox). */
+    receive(name: string): AgentMessage[];
+    /** Peek at messages without draining. */
+    peek(name: string): AgentMessage[];
+    /** Reset all state. */
+    reset(): void;
+}
+export declare const agentCoordinator: AgentCoordinator;
+export {};

package/dist/agent/coordinator.js

@@ -0,0 +1,77 @@
+/**
+ * Agent coordinator — agent registry + message bus for multi-agent communication.
+ */
+/**
+ * Singleton agent registry and message bus.
+ */
+class AgentCoordinator {
+    agents = new Map();
+    inbox = new Map();
+    /** Register a named agent. */
+    register(id, name, description) {
+        this.agents.set(name, {
+            id,
+            name,
+            status: "running",
+            description,
+            startedAt: Date.now(),
+        });
+        if (!this.inbox.has(name)) {
+            this.inbox.set(name, []);
+        }
+    }
+    /** Mark an agent as completed. */
+    complete(name, result) {
+        const agent = this.agents.get(name);
+        if (agent) {
+            agent.status = "completed";
+            agent.completedAt = Date.now();
+            agent.result = result;
+        }
+    }
+    /** Mark an agent as failed. */
+    fail(name) {
+        const agent = this.agents.get(name);
+        if (agent) {
+            agent.status = "failed";
+            agent.completedAt = Date.now();
+        }
+    }
+    /** Get agent info by name. */
+    get(name) {
+        return this.agents.get(name);
+    }
+    /** List all agents. */
+    list() {
+        return [...this.agents.values()];
+    }
+    /** List active (running) agents. */
+    listActive() {
+        return [...this.agents.values()].filter((a) => a.status === "running");
+    }
+    /** Send a message to a named agent. */
+    send(from, to, content) {
+        if (!this.agents.has(to))
+            return false;
+        const messages = this.inbox.get(to) ?? [];
+        messages.push({ from, to, content, timestamp: Date.now() });
+        this.inbox.set(to, messages);
+        return true;
+    }
+    /** Read messages for a named agent (drains the inbox). */
+    receive(name) {
+        const messages = this.inbox.get(name) ?? [];
+        this.inbox.set(name, []);
+        return messages;
+    }
+    /** Peek at messages without draining. */
+    peek(name) {
+        return this.inbox.get(name) ?? [];
+    }
+    /** Reset all state. */
+    reset() {
+        this.agents.clear();
+        this.inbox.clear();
+    }
+}
+export const agentCoordinator = new AgentCoordinator();

package/dist/arena/arena.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Arena — multi-model collaborative analysis engine.
+ *
+ * Evidence-Driven Pipeline:
+ *   0. Planner            → understand what the user wants (mode, lenses, sources)
+ *   1. EvidenceProviders   → collect artifacts from selected sources
+ *   2. Strategy + Lens     → compose prompts (mode flow + perspective)
+ *   3. ToolSelector        → determine which tools participants can use
+ *   4. ParticipantResearch  → each model investigates independently (parallel)
+ *   4b. ClaimRegistry      → register findings as claims, populate ledger
+ *   5. VerificationReview   → claim-aware cross-review with evidence digests
+ *   7. DebateRounds         → contested claims enter structured debate
+ *   8. Adjudication         → moderator rules on contested claims
+ *   6. ConsensusBuilder     → claim-aware structured consensus
+ */
+import type { ArenaConfig, ArenaResultV2 } from "./types.js";
+import type { PlannerFlags } from "./planner.js";
+export declare class Arena {
+    private config;
+    private strategy;
+    private limits;
+    constructor(config: ArenaConfig);
+    /**
+     * Run a full arena session.
+     *
+     * @param topic  - User's topic/request (natural language)
+     * @param flags  - Optional explicit overrides (mode, base, head)
+     */
+    run(topic: string, flags?: PlannerFlags): Promise<ArenaResultV2>;
+    /**
+     * Planning path: merge-oriented review → roadmap consensus → detail expansion.
+     *
+     * Planning mode does NOT enter heavy debate/adjudication. Contested findings
+     * are converted to open questions or dependency risks in the roadmap.
+     */
+    private runPlanningPath;
+    /**
+     * Review/Discussion path: verification review → debate → adjudication → consensus.
+     *
+     * This is the heavy trust loop for claim verification.
+     */
+    private runReviewDiscussionPath;
+}

package/dist/arena/arena.js

@@ -0,0 +1,334 @@
+/**
+ * Arena — multi-model collaborative analysis engine.
+ *
+ * Evidence-Driven Pipeline:
+ *   0. Planner            → understand what the user wants (mode, lenses, sources)
+ *   1. EvidenceProviders   → collect artifacts from selected sources
+ *   2. Strategy + Lens     → compose prompts (mode flow + perspective)
+ *   3. ToolSelector        → determine which tools participants can use
+ *   4. ParticipantResearch  → each model investigates independently (parallel)
+ *   4b. ClaimRegistry      → register findings as claims, populate ledger
+ *   5. VerificationReview   → claim-aware cross-review with evidence digests
+ *   7. DebateRounds         → contested claims enter structured debate
+ *   8. Adjudication         → moderator rules on contested claims
+ *   6. ConsensusBuilder     → claim-aware structured consensus
+ */
+import { logger } from "../logging/logger.js";
+import { ARENA_MODE_DEFAULTS, DEFAULT_EXECUTION_LIMITS, isStrategyPlanning } from "./types.js";
+import { getStrategy, getStrategyForPlan } from "./strategies/index.js";
+import { planArena } from "./planner.js";
+import { collectEvidence } from "./providers/index.js";
+import { selectTools } from "./tools/selector.js";
+import { runParticipantResearchWithDossiers } from "./phases/participant-research.js";
+import { runVerificationReview } from "./phases/cross-review.js";
+import { runDebateRounds } from "./phases/debate-rounds.js";
+import { runAdjudication } from "./phases/adjudication.js";
+import { buildConsensus } from "./phases/build-consensus.js";
+import { runDetailExpansion } from "./phases/planning-detail-expansion.js";
+import { withLanguage } from "./strategies/language-wrapper.js";
+import { ArenaLedger } from "./ledger.js";
+import { registerClaims } from "./phases/claim-registry.js";
+export class Arena {
+    config;
+    strategy;
+    limits;
+    constructor(config) {
+        if (config.participants.length < 2) {
+            throw new Error("Arena requires at least 2 participants");
+        }
+        const mode = config.mode ?? "review";
+        const defaults = ARENA_MODE_DEFAULTS[mode];
+        this.config = {
+            mode,
+            maxDiscussionRounds: config.maxDiscussionRounds ?? defaults.maxDiscussionRounds,
+            ...config,
+        };
+        this.limits = config.executionLimits ?? DEFAULT_EXECUTION_LIMITS;
+        // Initial strategy — will be overridden in run() with lens + language wrappers
+        this.strategy = config.strategy ?? getStrategy(mode);
+    }
+    /**
+     * Run a full arena session.
+     *
+     * @param topic  - User's topic/request (natural language)
+     * @param flags  - Optional explicit overrides (mode, base, head)
+     */
+    async run(topic, flags) {
+        const participantNames = this.config.participants.map((p) => p.name);
+        const signal = this.config.signal;
+        logger.info("arena.start", { mode: this.config.mode, participants: participantNames });
+        signal?.throwIfAborted();
+        // ─── Phase 0: Plan ────────────────────────────────────────
+        const llmConfig = this.config.participants[0].llm;
+        const plan = await planArena(topic, llmConfig, flags, signal);
+        this.config.onProgress?.({ type: "plan_resolved", plan });
+        logger.info("arena.plan", {
+            mode: plan.mode,
+            lenses: plan.lenses.map((l) => l.name),
+            sources: plan.sources.map((s) => s.kind),
+            subject: plan.subject.label,
+            confidence: plan.confidence,
+        });
+        if (!flags?.mode && plan.mode !== this.config.mode) {
+            this.config.mode = plan.mode;
+        }
+        signal?.throwIfAborted();
+        // ─── Phase 1: Collect Evidence ────────────────────────────
+        // Bridge collectEvidence's lifecycle events to the public
+        // ArenaProgressEvent stream so the UI sees "collecting from
+        // repo..." instead of a silent pause.
+        const onProgress = this.config.onProgress;
+        const { artifacts, quickFacts } = await collectEvidence(plan, topic, {
+            signal,
+            onProgress: (e) => {
+                if (e.type === "evidence_started") {
+                    onProgress?.({ type: "evidence_started", source: e.source });
+                }
+                else {
+                    onProgress?.({
+                        type: "evidence_source_done",
+                        source: e.source,
+                        count: e.count ?? 0,
+                        durationMs: e.durationMs ?? 0,
+                        timedOut: e.timedOut ?? false,
+                    });
+                }
+            },
+        });
+        onProgress?.({ type: "evidence_collected", artifacts });
+        logger.info("arena.evidence", {
+            artifactCount: artifacts.length,
+            sources: plan.sources.map((s) => s.kind),
+        });
+        const baseContext = { plan, artifacts, quickFacts };
+        // ─── Phase 2: Compose Strategy ────────────────────────────
+        this.strategy = this.config.strategy ?? getStrategyForPlan(plan);
+        this.strategy = withLanguage(this.strategy, topic);
+        // ─── Phase 3: Select Tools ────────────────────────────────
+        const contextTools = this.config.enableContextTools !== false
+            ? selectTools(plan)
+            : undefined;
+        signal?.throwIfAborted();
+        // ─── Phase 4: Participant Research (parallel) ─────────────
+        logger.info("arena.research_phase", { participants: participantNames });
+        const researchResults = await runParticipantResearchWithDossiers({
+            participants: this.config.participants,
+            strategy: this.strategy,
+            topic,
+            baseContext,
+            enableContextTools: this.config.enableContextTools ?? true,
+            contextTools,
+            signal,
+            onProgress: this.config.onProgress,
+        });
+        const reports = researchResults.map((r) => r.report);
+        const dossiers = researchResults.map((r) => r.dossier);
+        signal?.throwIfAborted();
+        // ─── Phase 4b: Claim Registry ─────────────────────────────
+        const ledger = new ArenaLedger();
+        // Populate ledger with dossiers
+        for (const dossier of dossiers) {
+            ledger.appendDossier(dossier);
+        }
+        // Register findings as claims
+        const claims = registerClaims({
+            dossiers,
+            ledger,
+            onProgress: this.config.onProgress,
+        });
+        logger.info("arena.claims_registered", {
+            claimCount: claims.length,
+            byOwner: Object.fromEntries(participantNames.map((name) => [
+                name,
+                claims.filter((c) => c.owner === name).length,
+            ])),
+        });
+        signal?.throwIfAborted();
+        // ─── Phase 5: Mode Policy Router ─────────────────────────
+        //
+        // Planning mode: merge-oriented review → roadmap consensus → detail expansion
+        // Review/Discussion mode: verification review → debate → adjudication → consensus
+        const concluderName = this.config.concluder ?? participantNames[0];
+        const concluderMatch = this.config.participants.find((p) => p.name === concluderName);
+        if (!concluderMatch && this.config.concluder) {
+            logger.warn("arena.concluder_not_found", {
+                requested: this.config.concluder,
+                fallback: this.config.participants[0].name,
+            });
+        }
+        const concluder = concluderMatch ?? this.config.participants[0];
+        const enableTools = this.config.enableContextTools !== false;
+        if (this.config.mode === "planning") {
+            return this.runPlanningPath({
+                topic, participantNames, plan, baseContext, reports, dossiers, ledger,
+                concluder, contextTools, enableContextTools: enableTools, signal,
+            });
+        }
+        return this.runReviewDiscussionPath({
+            topic, participantNames, plan, baseContext, reports, dossiers, ledger, concluder, signal,
+        });
+    }
+    /**
+     * Planning path: merge-oriented review → roadmap consensus → detail expansion.
+     *
+     * Planning mode does NOT enter heavy debate/adjudication. Contested findings
+     * are converted to open questions or dependency risks in the roadmap.
+     */
+    async runPlanningPath(ctx) {
+        const { topic, participantNames, plan, baseContext, reports, dossiers, ledger, concluder, contextTools, enableContextTools, signal, } = ctx;
+        // ─── Merge-Oriented Review ───────────────────────────────
+        logger.info("arena.planning_merge_review_phase");
+        const { reviews } = await runVerificationReview({
+            participants: this.config.participants,
+            strategy: this.strategy,
+            topic,
+            reports,
+            ledger,
+            limits: this.limits,
+            mode: "planning",
+            signal,
+            onProgress: this.config.onProgress,
+        });
+        signal?.throwIfAborted();
+        // ─── Roadmap Consensus ───────────────────────────────────
+        const allClaims = ledger.getAllClaims();
+        const claimSummary = {
+            verified: allClaims.filter((c) => c.status === "verified"),
+            contested: allClaims.filter((c) => c.status === "contested"),
+            unresolved: allClaims.filter((c) => c.status === "unresolved"),
+            rejected: allClaims.filter((c) => c.status === "rejected"),
+        };
+        logger.info("arena.planning_consensus_phase", { concluder: concluder.name });
+        const consensus = await buildConsensus({
+            concluder,
+            strategy: this.strategy,
+            topic,
+            reports,
+            reviews,
+            claimSummary,
+            signal,
+            onProgress: this.config.onProgress,
+        });
+        signal?.throwIfAborted();
+        // ─── Detail Expansion ────────────────────────────────────
+        if (consensus.roadmap.length > 0 && isStrategyPlanning(this.strategy)) {
+            logger.info("arena.detail_expansion_phase", { phaseCount: consensus.roadmap.length });
+            try {
+                const details = await runDetailExpansion({
+                    concluder,
+                    strategy: this.strategy,
+                    topic,
+                    phases: consensus.roadmap,
+                    ledger,
+                    limits: this.limits,
+                    enableContextTools,
+                    contextTools,
+                    signal,
+                    onProgress: this.config.onProgress,
+                });
+                consensus.roadmapDetails = details;
+            }
+            catch (err) {
+                // Detail expansion is non-critical — degrade gracefully
+                logger.warn("arena.detail_expansion_failed", {
+                    error: err.message,
+                    phaseCount: consensus.roadmap.length,
+                });
+            }
+        }
+        return {
+            topic,
+            mode: this.config.mode,
+            participants: participantNames,
+            plan,
+            baseContext,
+            reports,
+            dossiers,
+            claims: allClaims,
+            reviews,
+            consensus,
+        };
+    }
+    /**
+     * Review/Discussion path: verification review → debate → adjudication → consensus.
+     *
+     * This is the heavy trust loop for claim verification.
+     */
+    async runReviewDiscussionPath(ctx) {
+        const { topic, participantNames, plan, baseContext, reports, dossiers, ledger, concluder, signal } = ctx;
+        // ─── Verification Review (parallel) ──────────────────────
+        logger.info("arena.verification_review_phase");
+        const { reviews } = await runVerificationReview({
+            participants: this.config.participants,
+            strategy: this.strategy,
+            topic,
+            reports,
+            ledger,
+            limits: this.limits,
+            signal,
+            onProgress: this.config.onProgress,
+        });
+        signal?.throwIfAborted();
+        // ─── Debate Rounds ───────────────────────────────────────
+        logger.info("arena.debate_phase");
+        const debateRounds = await runDebateRounds({
+            participants: this.config.participants,
+            strategy: this.strategy,
+            topic,
+            ledger,
+            limits: this.limits,
+            maxRounds: this.config.maxDiscussionRounds,
+            signal,
+            onProgress: this.config.onProgress,
+        });
+        signal?.throwIfAborted();
+        // ─── Adjudication ────────────────────────────────────────
+        logger.info("arena.adjudication_phase", { concluder: concluder.name });
+        const adjudications = await runAdjudication({
+            concluder,
+            strategy: this.strategy,
+            topic,
+            ledger,
+            signal,
+            onProgress: this.config.onProgress,
+        });
+        signal?.throwIfAborted();
+        // ─── Consensus (claim-aware) ─────────────────────────────
+        const allClaims = ledger.getAllClaims();
+        const claimSummary = {
+            verified: allClaims.filter((c) => c.status === "verified"),
+            contested: allClaims.filter((c) => c.status === "contested"),
+            unresolved: allClaims.filter((c) => c.status === "unresolved"),
+            rejected: allClaims.filter((c) => c.status === "rejected"),
+        };
+        logger.info("arena.consensus_phase", {
+            concluder: concluder.name,
+            verified: claimSummary.verified.length,
+            unresolved: claimSummary.unresolved.length,
+        });
+        const consensus = await buildConsensus({
+            concluder,
+            strategy: this.strategy,
+            topic,
+            reports,
+            reviews,
+            claimSummary,
+            signal,
+            onProgress: this.config.onProgress,
+        });
+        return {
+            topic,
+            mode: this.config.mode,
+            participants: participantNames,
+            plan,
+            baseContext,
+            reports,
+            dossiers,
+            claims: allClaims,
+            reviews,
+            debateRounds,
+            adjudications,
+            consensus,
+        };
+    }
+}