xcoder-dna 0.0.0-stage → 1.3.0

package/LICENSE

@@ -0,0 +1,66 @@
+Copyright (c) 2026 Sir John M. Nueva
+All Rights Reserved.
+
+PROPRIETARY AND CONFIDENTIAL
+
+This repository and all of its contents — including but not limited to source code,
+documentation, system designs, component contracts, methodology specifications,
+blueprints, templates, diagrams, data schemas, configuration files, and all other
+associated materials (collectively, the "Work") — are the exclusive intellectual
+property of Sir John M. Nueva.
+
+RESTRICTIONS
+
+No part of the Work may, without the prior explicit written permission of
+Sir John M. Nueva:
+
+  1. Be reproduced, copied, or duplicated in any form or by any means,
+     electronic or mechanical.
+
+  2. Be modified, adapted, translated, or used to create derivative works.
+
+  3. Be distributed, published, transmitted, sold, sublicensed, or otherwise
+     made available to any third party.
+
+  4. Be used for commercial, educational, research, or any other purpose,
+     whether for profit or not.
+
+  5. Be reverse-engineered, decompiled, or disassembled.
+
+OWNERSHIP
+
+The Work is protected under applicable copyright laws and international
+treaty provisions. Sir John M. Nueva retains all intellectual property rights,
+title, and interest in and to the Work, including all copies, modifications,
+and derivative works thereof, regardless of the form in which they exist.
+
+NO LICENSE GRANTED
+
+Nothing in this repository constitutes a grant — express, implied, or by
+estoppel — of any license, right, or permission to use, copy, modify,
+distribute, or otherwise exploit the Work or any portion thereof.
+
+NO WARRANTY
+
+THE WORK 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 NON-INFRINGEMENT. IN NO EVENT SHALL
+SIR JOHN M. NUEVA 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 WORK OR THE USE OR OTHER DEALINGS IN THE WORK.
+
+ENFORCEMENT
+
+Any unauthorized use, reproduction, distribution, or modification of the Work
+constitutes copyright infringement and may result in civil and criminal penalties
+to the maximum extent permitted by applicable law.
+
+CONTACT
+
+For licensing inquiries or written permission requests, contact:
+
+  Sir John M. Nueva
+
+-------------------------------------------------------------------------------
+Copyright (c) 2026 Sir John M. Nueva. All Rights Reserved.
+-------------------------------------------------------------------------------

package/README.md

@@ -1,3 +1,88 @@
-# Temporary Holding Version
+<!-- xcoder:version 3 | xcoder:task task-295e1f | xcoder:updated 2026-11-04T20:17:09.582Z | xcoder:subtask document-st-dd8fa0 -->
+# xcoder-dna — shared runtime for the Xcoder agents
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`xcoder-dna` is a **library**, not a CLI. It has no binary and nothing to run directly: it holds the reusable tools, skills, swarm, sub-agent runtime and orchestration primitives that the Xcoder agents are built from. Its public barrel, `src/index.ts`, is the only import path other packages may use.
+
+## Install
+
+```
+npm install xcoder-dna
+```
+
+Node >= 20 is required. Do not install this package globally — there is no executable to put on your PATH.
+
+## Quick start
+
+```ts
+import { createLlmClient, log, buildIndex, ensureFreshIndex } from "xcoder-dna";
+
+const index = buildIndex(process.cwd());
+await ensureFreshIndex(process.cwd());
+log.orchestrator(`indexed ${index.files.length} files`);
+
+const llm = createLlmClient("orchestrator", { workspaceRoot: process.cwd() });
+```
+
+## Public API
+
+The barrel is grouped by concern. Each identifier below is a real export; import it from the package root, never from a deep path.
+
+| Area | Exports |
+|---|---|
+| LLM access | `createLlmClient`, `LlmClient`, `requestScope` |
+| Logging and output | `log`, `getOutputHandler`, `getOutputPaths`, `redactSecrets`, `sanitizeForTerminal` |
+| Workspace index | `buildIndex`, `ensureFreshIndex`, `createXcoderPaths` |
+| Agents and runtime | `SubAgent`, `GenesisReActOrchestrator`, `SamuraiAgent`, `WorkerOrchestrator`, `InstanceSwarmOrchestrator`, `DuplicateActionDetector`, `runDebate`, `writeReport` |
+| Orchestration | `decideHealing`, `getOrchestratorEngine`, `buildProgressSummaryMarkdown`, `resolveLessonFlag`, `loadLessons`, `recordLesson` |
+| Defects | `scanForDefects`, `classifyDefectRouting`, `resolveDefect`, `loadDefectsIndex`, `upsertDefect` |
+| Planning and DAG | `inlineIntoDependents`, `dagSnapshot`, `recomputeReady` |
+| Backlog and sprints | `addBacklogItem`, `listBacklogItems`, `getBacklogItem`, `updateBacklogItem`, `runPoPick` |
+| Benchmarking | `runBenchmark`, `compareReports` |
+| Terminal and spinner | `setSpinnerStyle`, `getSpinnerStyle`, `createSpinner`, `AVAILABLE_SPINNER_STYLES`, `taskIntro`, `taskOutro`, `orchestratorNote`, `printCrash`, `printInterruptSummary` |
+| Events and diagnostics | `xcoderEvents`, `emitXcoderEvent`, `enableProtocolErrorLogging`, `enableToolErrorLogging`, `maybePrintBanner` |
+| Licensing | `requireLicense`, `isLicensedFeature`, `maybeRefreshLicense`, `createDefaultLicenseManager`, `LICENSE_REQUIRED_EXIT_CODE` |
+| Command registrars | `registerTestCommand`, `registerSwarmCommand`, `registerTaskCommand`, `registerLicenseCommand` |
+| Version | `XCODER_VERSION` |
+
+Types such as `TaskRun`, `TaskSpec`, `SubtaskNode`, `SubtaskResult`, `LessonEntry`, `AgentRole`, `SdlcStage` and `SpinnerHandle` are exported alongside their values.
+
+## Process exit
+
+This is a library; it never calls `process.exit` and sets no exit code itself. It does export `LICENSE_REQUIRED_EXIT_CODE` (`4`), which the CLIs relay when a licensed command runs without an active license.
+
+## Environment variables
+
+`xcoder-dna` reads credentials and provider settings through the host agent's config (`~/.xcoder/config.json` or environment variables such as `XCODER_MODEL`); it never prompts for a key itself. Secrets are redacted by `redactSecrets` before they reach logs.
+
+## Dependency direction
+
+`xcoder-dna` has **no internal dependencies** — it is the base of the workspace graph and imports no other workspace package. Everyone else depends on it:
+
+```
+xcoder-dna  <-  @xcoder/litebro
+            <-  @xcoder/qa-agent
+            <-  @xcoder/sdlc-agent
+```
+
+## Build output
+
+`npm run build` compiles TypeScript to `dist/` and then copies `skills/` to `dist/skills/`, so the skills catalogue ships inside the package. Only `dist/`, `README.md` and `LICENSE` are published.
+
+## Documentation contract
+
+This README ships to npm, so it is gated like code by `packages/xcoder-dna/src/doc-readme.test.ts`. It asserts differently from the agent packages because this is a library: there is no bin, so no CLI section and no exit-code table are allowed. Instead every identifier named in the Public API table is checked against the barrel at `src/index.ts` — the single legal import path — so the README cannot claim an export the library does not have. Run it in isolation with:
+
+```
+npx vitest run packages/xcoder-dna/src/doc-readme.test.ts
+```
+
+## Related packages
+
+- [@xcoder/sdlc-agent](https://github.com/org/xcoder-sdlc/tree/main/packages/sdlc-agent) — the `xcoder` SDLC agent and `ba-v1`.
+- [@xcoder/qa-agent](https://github.com/org/xcoder-sdlc/tree/main/packages/qa-agent) — the `bugfinder` QA agent.
+- [@xcoder/litebro](https://github.com/org/xcoder-sdlc/tree/main/packages/litebro) — the tool-less planner/broker.
+- [blueprint.md](https://github.com/org/xcoder-sdlc/blob/main/docs/blueprint.md) — architecture and component decomposition.
+
+## License
+
+see [LICENSE](./LICENSE) for details.

package/dist/agents/ai-chat-debate.d.ts

@@ -0,0 +1,36 @@
+import type { RaoStep, TokenUsage } from "../types.js";
+import { LlmClient } from "../llm/client.js";
+export interface DebateOptions {
+    workspaceRoot: string;
+    llm: LlmClient;
+    topic: string;
+    maxExchanges?: number;
+    model?: string;
+    debateId?: string;
+}
+export interface DebateTurn {
+    agent: "Sumurai" | "Ninj";
+    turnNumber: number;
+    raoTrace: RaoStep[];
+    finalAnswer: string | null;
+    tokenUsage: TokenUsage;
+}
+export interface DebateResult {
+    topic: string;
+    turns: DebateTurn[];
+    status: "resolved" | "unresolved" | "error";
+    errorMessage?: string;
+    totalTokenUsage: TokenUsage;
+    startedAt: string;
+    endedAt: string;
+}
+/**
+ * Orchestrates a turn-based debate between two SamuraiAgent instances
+ * (Sumurai and Ninj). Manages the transcript, iteration budget, and
+ * convergence detection. Returns a structured debate result regardless
+ * of whether the debate completed or failed mid-turn.
+ *
+ * Execution is sequential: Sumurai speaks first, then Ninj responds,
+ * alternating up to maxExchanges each.
+ */
+export declare function runDebate(opts: DebateOptions): Promise<DebateResult>;

package/dist/agents/ai-chat-debate.js

@@ -0,0 +1,300 @@
+import { SamuraiAgent } from "./samurai-agent.js";
+import { emitXcoderEvent } from "../events/bus.js";
+import { randomUUID } from "node:crypto";
+/**
+ * Orchestrates a turn-based debate between two SamuraiAgent instances
+ * (Sumurai and Ninj). Manages the transcript, iteration budget, and
+ * convergence detection. Returns a structured debate result regardless
+ * of whether the debate completed or failed mid-turn.
+ *
+ * Execution is sequential: Sumurai speaks first, then Ninj responds,
+ * alternating up to maxExchanges each.
+ */
+export async function runDebate(opts) {
+    const maxExchanges = opts.maxExchanges ?? 20;
+    const debateId = opts.debateId ?? randomUUID();
+    const startedAt = new Date().toISOString();
+    const turns = [];
+    const totalTokenUsage = { inputTokens: 0, outputTokens: 0 };
+    // Emit debate:intro
+    emitXcoderEvent({
+        type: "debate:intro",
+        taskId: debateId,
+        data: { topic: opts.topic, debateId },
+    });
+    // Build the debate system prompt context — this is prepended to each
+    // agent's goal on every turn so they know their role and the debate rules.
+    const debateContextIntro = [
+        "# Dual-AI Debate: Sumurai vs Ninj",
+        `Topic: ${opts.topic}`,
+        "",
+        "You are participating in a structured debate. Rules:",
+        "1. Each turn you speak, address the topic AND respond to your opponent's last argument.",
+        "2. Be substantive — cite evidence from the workspace, files you've read, or logical reasoning.",
+        "3. When you believe the debate has reached a natural resolution, include a summary in your final_answer.",
+        "4. Keep each response focused — this is a debate, not a monologue.",
+        "",
+    ].join("\n");
+    // We create two agents with different system-prompt configurations.
+    // They share the same LlmClient and workspace but get distinct agent names.
+    const sumuraiAgent = new SamuraiAgent({
+        workspaceRoot: opts.workspaceRoot,
+        llm: opts.llm,
+        maxIterations: 20, // Each turn gets its own ReAct loop
+        model: opts.model,
+        packageJsonContext: null,
+    });
+    const ninjAgent = new SamuraiAgent({
+        workspaceRoot: opts.workspaceRoot,
+        llm: opts.llm,
+        maxIterations: 20,
+        model: opts.model,
+        packageJsonContext: null,
+    });
+    // Accumulated debate transcript — each agent sees the full history
+    let debateTranscript = debateContextIntro;
+    try {
+        for (let exchange = 0; exchange < maxExchanges; exchange++) {
+            // Sumurai's turn
+            const sumuraiTurnNumber = exchange * 2 + 1;
+            emitXcoderEvent({
+                type: "debate:turn-start",
+                taskId: debateId,
+                data: { agent: "Sumurai", turnNumber: sumuraiTurnNumber, role: exchange === 0 ? "opening" : "response" },
+            });
+            const sumuraiGoal = buildTurnGoal("Sumurai", opts.topic, debateTranscript, exchange, exchange === 0 ? "opening" : "response");
+            let sumuraiResult;
+            try {
+                sumuraiResult = await sumuraiAgent.runOnce(sumuraiGoal, {
+                    onStep: (step) => {
+                        if (step.action) {
+                            emitXcoderEvent({
+                                type: "debate:agent-action",
+                                taskId: debateId,
+                                data: { agent: "Sumurai", turnNumber: sumuraiTurnNumber, tool: step.action.tool, input: step.action.input },
+                            });
+                        }
+                        else if (step.observation === "final_answer submitted") {
+                            emitXcoderEvent({
+                                type: "debate:agent-final",
+                                taskId: debateId,
+                                data: { agent: "Sumurai", turnNumber: sumuraiTurnNumber, summary: step.thought },
+                            });
+                        }
+                        // Always emit thought
+                        emitXcoderEvent({
+                            type: "debate:agent-thought",
+                            taskId: debateId,
+                            data: { agent: "Sumurai", turnNumber: sumuraiTurnNumber, thought: step.thought },
+                        });
+                        // Emit observation if any
+                        if (step.action) {
+                            emitXcoderEvent({
+                                type: "debate:agent-observation",
+                                taskId: debateId,
+                                data: { agent: "Sumurai", turnNumber: sumuraiTurnNumber, ok: step.observation !== undefined, observation: step.observation },
+                            });
+                        }
+                    },
+                    onTokens: (cumulative) => {
+                        emitXcoderEvent({
+                            type: "debate:agent-tokens",
+                            taskId: debateId,
+                            data: { agent: "Sumurai", turnNumber: sumuraiTurnNumber, cumulative },
+                        });
+                    },
+                });
+            }
+            catch (e) {
+                emitXcoderEvent({
+                    type: "debate:outro",
+                    taskId: debateId,
+                    data: { status: "error", errorMessage: `Sumurai crashed on exchange ${exchange + 1}: ${e.message}`, totalTokenUsage, turns: turns.length },
+                });
+                return {
+                    topic: opts.topic,
+                    turns,
+                    status: "error",
+                    errorMessage: `Sumurai crashed on exchange ${exchange + 1}: ${e.message}`,
+                    totalTokenUsage,
+                    startedAt,
+                    endedAt: new Date().toISOString(),
+                };
+            }
+            totalTokenUsage.inputTokens += sumuraiResult.tokenUsage.inputTokens;
+            totalTokenUsage.outputTokens += sumuraiResult.tokenUsage.outputTokens;
+            const sumuraiTurn = {
+                agent: "Sumurai",
+                turnNumber: sumuraiTurnNumber,
+                raoTrace: sumuraiResult.raoTrace,
+                finalAnswer: sumuraiResult.summary,
+                tokenUsage: sumuraiResult.tokenUsage,
+            };
+            turns.push(sumuraiTurn);
+            // Append Sumurai's contribution to debate transcript
+            debateTranscript += `\n\n## Sumurai (turn ${sumuraiTurnNumber})\n${sumuraiResult.summary}\n`;
+            // Ninj's turn
+            const ninjTurnNumber = exchange * 2 + 2;
+            emitXcoderEvent({
+                type: "debate:turn-start",
+                taskId: debateId,
+                data: { agent: "Ninj", turnNumber: ninjTurnNumber, role: "response" },
+            });
+            const ninjGoal = buildTurnGoal("Ninj", opts.topic, debateTranscript, exchange, "response");
+            let ninjResult;
+            try {
+                ninjResult = await ninjAgent.runOnce(ninjGoal, {
+                    onStep: (step) => {
+                        if (step.action) {
+                            emitXcoderEvent({
+                                type: "debate:agent-action",
+                                taskId: debateId,
+                                data: { agent: "Ninj", turnNumber: ninjTurnNumber, tool: step.action.tool, input: step.action.input },
+                            });
+                        }
+                        else if (step.observation === "final_answer submitted") {
+                            emitXcoderEvent({
+                                type: "debate:agent-final",
+                                taskId: debateId,
+                                data: { agent: "Ninj", turnNumber: ninjTurnNumber, summary: step.thought },
+                            });
+                        }
+                        emitXcoderEvent({
+                            type: "debate:agent-thought",
+                            taskId: debateId,
+                            data: { agent: "Ninj", turnNumber: ninjTurnNumber, thought: step.thought },
+                        });
+                        if (step.action) {
+                            emitXcoderEvent({
+                                type: "debate:agent-observation",
+                                taskId: debateId,
+                                data: { agent: "Ninj", turnNumber: ninjTurnNumber, ok: step.observation !== undefined, observation: step.observation },
+                            });
+                        }
+                    },
+                    onTokens: (cumulative) => {
+                        emitXcoderEvent({
+                            type: "debate:agent-tokens",
+                            taskId: debateId,
+                            data: { agent: "Ninj", turnNumber: ninjTurnNumber, cumulative },
+                        });
+                    },
+                });
+            }
+            catch (e) {
+                emitXcoderEvent({
+                    type: "debate:outro",
+                    taskId: debateId,
+                    data: { status: "error", errorMessage: `Ninj crashed on exchange ${exchange + 1}: ${e.message}`, totalTokenUsage, turns: turns.length },
+                });
+                return {
+                    topic: opts.topic,
+                    turns,
+                    status: "error",
+                    errorMessage: `Ninj crashed on exchange ${exchange + 1}: ${e.message}`,
+                    totalTokenUsage,
+                    startedAt,
+                    endedAt: new Date().toISOString(),
+                };
+            }
+            totalTokenUsage.inputTokens += ninjResult.tokenUsage.inputTokens;
+            totalTokenUsage.outputTokens += ninjResult.tokenUsage.outputTokens;
+            const ninjTurn = {
+                agent: "Ninj",
+                turnNumber: ninjTurnNumber,
+                raoTrace: ninjResult.raoTrace,
+                finalAnswer: ninjResult.summary,
+                tokenUsage: ninjResult.tokenUsage,
+            };
+            turns.push(ninjTurn);
+            // Append Ninj's contribution to debate transcript
+            debateTranscript += `\n\n## Ninj (turn ${ninjTurnNumber})\n${ninjResult.summary}\n`;
+            // Convergence check: do both agents' summaries indicate resolution?
+            if (detectConvergence(sumuraiResult.summary, ninjResult.summary)) {
+                emitXcoderEvent({
+                    type: "debate:outro",
+                    taskId: debateId,
+                    data: { status: "resolved", totalTokenUsage, turns: turns.length },
+                });
+                return {
+                    topic: opts.topic,
+                    turns,
+                    status: "resolved",
+                    totalTokenUsage,
+                    startedAt,
+                    endedAt: new Date().toISOString(),
+                };
+            }
+        }
+        // Exhausted max exchanges without convergence
+        emitXcoderEvent({
+            type: "debate:outro",
+            taskId: debateId,
+            data: { status: "unresolved", totalTokenUsage, turns: turns.length },
+        });
+        return {
+            topic: opts.topic,
+            turns,
+            status: "unresolved",
+            totalTokenUsage,
+            startedAt,
+            endedAt: new Date().toISOString(),
+        };
+    }
+    catch (e) {
+        // Catch-all for unexpected errors during the debate orchestration itself
+        emitXcoderEvent({
+            type: "debate:outro",
+            taskId: debateId,
+            data: { status: "error", errorMessage: `Debate orchestration failed: ${e.message}`, totalTokenUsage, turns: turns.length },
+        });
+        return {
+            topic: opts.topic,
+            turns,
+            status: "error",
+            errorMessage: `Debate orchestration failed: ${e.message}`,
+            totalTokenUsage,
+            startedAt,
+            endedAt: new Date().toISOString(),
+        };
+    }
+}
+/**
+ * Builds the goal string for a single debate turn.
+ * Includes the full debate transcript so far and instructions specific
+ * to whether this is an opening or response turn.
+ */
+function buildTurnGoal(agentName, topic, transcript, exchange, role) {
+    const turnInstruction = role === "opening"
+        ? `You are ${agentName}, opening the debate. Present your initial position on the topic.`
+        : `You are ${agentName}, responding in the debate. Address your opponent's last points and strengthen your position.`;
+    return [
+        turnInstruction,
+        "",
+        "Debate transcript so far:",
+        `${transcript}`,
+        "",
+        `Exchange ${exchange + 1}: It is your turn to speak as ${agentName}. Provide your argument.`,
+    ].join("\n");
+}
+/**
+ * Simple heuristic for convergence detection: both agents' final summaries
+ * contain keywords indicating they've reached a conclusion.
+ */
+function detectConvergence(sumuraiSummary, ninjSummary) {
+    const resolutionKeywords = [
+        "summary",
+        "conclusion",
+        "resolution",
+        "agreed",
+        "consensus",
+        "final",
+        "closing",
+        "settled",
+    ];
+    const sumuraiLower = sumuraiSummary.toLowerCase();
+    const ninjLower = ninjSummary.toLowerCase();
+    const sumuraiHasResolution = resolutionKeywords.some((kw) => sumuraiLower.includes(kw));
+    const ninjHasResolution = resolutionKeywords.some((kw) => ninjLower.includes(kw));
+    return sumuraiHasResolution && ninjHasResolution;
+}

package/dist/agents/ai-chat-report-writer.d.ts

@@ -0,0 +1,7 @@
+import type { DebateResult } from "./ai-chat-debate.js";
+/**
+ * Formats a DebateResult into a timestamped Markdown report file and writes
+ * it to disk. If a partial error occurred, writes whatever turns were
+ * completed plus an error note at the end.
+ */
+export declare function writeReport(result: DebateResult, outputDir: string): Promise<string>;

package/dist/agents/ai-chat-report-writer.js

@@ -0,0 +1,100 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+/**
+ * Formats a DebateResult into a timestamped Markdown report file and writes
+ * it to disk. If a partial error occurred, writes whatever turns were
+ * completed plus an error note at the end.
+ */
+export async function writeReport(result, outputDir) {
+    await fs.mkdir(outputDir, { recursive: true });
+    const ts = new Date()
+        .toISOString()
+        .replace(/[-:]/g, "")
+        .replace(/\..+/, "");
+    const filename = `ai-chat-report-${ts}.md`;
+    const filePath = path.join(outputDir, filename);
+    const md = formatReport(result);
+    await fs.writeFile(filePath, md, "utf-8");
+    return filePath;
+}
+/**
+ * Formats a DebateResult into Markdown.
+ */
+function formatReport(result) {
+    const lines = [];
+    // Header
+    lines.push(`# AI Chat Debate Report: ${result.topic}`);
+    lines.push("");
+    lines.push(`- **Status**: ${result.status}`);
+    lines.push(`- **Started**: ${result.startedAt}`);
+    lines.push(`- **Ended**: ${result.endedAt}`);
+    lines.push(`- **Turns**: ${result.turns.length}`);
+    lines.push(`- **Total Token Usage**: ${result.totalTokenUsage.inputTokens} input / ${result.totalTokenUsage.outputTokens} output`);
+    if (result.errorMessage) {
+        lines.push(`- **Error**: ${result.errorMessage}`);
+    }
+    lines.push("");
+    lines.push("---");
+    lines.push("");
+    // Transcript
+    if (result.turns.length === 0) {
+        lines.push("_No debate turns were recorded._");
+        lines.push("");
+    }
+    else {
+        lines.push("## Debate Transcript");
+        lines.push("");
+        for (const turn of result.turns) {
+            lines.push(`### ${turn.agent} — Turn ${turn.turnNumber}`);
+            lines.push("");
+            if (turn.finalAnswer) {
+                lines.push(`**Final Answer:** ${turn.finalAnswer}`);
+                lines.push("");
+            }
+            else {
+                lines.push(`**Final Answer:** _(no final answer produced)_`);
+                lines.push("");
+            }
+            lines.push(`**Token Usage:** ${turn.tokenUsage.inputTokens} input / ${turn.tokenUsage.outputTokens} output`);
+            lines.push("");
+            // ReAct trace details
+            if (turn.raoTrace.length > 0) {
+                lines.push("<details>");
+                lines.push("<summary>ReAct Trace (click to expand)</summary>");
+                lines.push("");
+                lines.push("| # | Thought | Action | Observation |");
+                lines.push("|---|---------|--------|-------------|");
+                for (let i = 0; i < turn.raoTrace.length; i++) {
+                    const step = turn.raoTrace[i];
+                    const thought = escapeMarkdown(truncate(step.thought, 200));
+                    const action = step.action
+                        ? escapeMarkdown(`${step.action.tool}(${truncate(JSON.stringify(step.action.input), 100)})`)
+                        : "—";
+                    const observation = escapeMarkdown(truncate(step.observation, 200));
+                    lines.push(`| ${i + 1} | ${thought} | ${action} | ${observation} |`);
+                }
+                lines.push("");
+                lines.push("</details>");
+                lines.push("");
+            }
+            lines.push("---");
+            lines.push("");
+        }
+    }
+    // Error note
+    if (result.errorMessage) {
+        lines.push("## Error");
+        lines.push("");
+        lines.push(`The debate did not complete successfully: ${result.errorMessage}`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+function escapeMarkdown(text) {
+    return text.replace(/[|\\`*_{}[\]()#+\-.!]/g, "\\$&");
+}
+function truncate(text, maxLen) {
+    if (text.length <= maxLen)
+        return text;
+    return text.slice(0, maxLen - 3) + "...";
+}

package/dist/agents/duplicate-detector.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Built directly from real evidence, not speculation: a production run's
+ * `code` subtask re-read the same design document 11 times across its
+ * attempts (multiple times WITHIN a single attempt, not just once per
+ * fresh retry) and repeatedly re-checked for files it hadn't created yet,
+ * leaving almost none of its 25-iteration budget for actual file writing.
+ * That pattern — the exact same (thought, action) pair recurring — is
+ * cheap to detect and, left unflagged, silently burns the entire
+ * iteration budget on zero net progress.
+ *
+ * Scope: per SubAgent.run() call (one attempt), not persisted across
+ * healing retries — a fresh attempt gets a fresh detector, since a brand
+ * new transcript legitimately has no memory of the previous attempt's
+ * actions anyway (that's `sdlc-orchestrator.ts`'s file-carryover
+ * healing hint's job, not this one's).
+ */
+export interface DuplicateCheckResult {
+    isDuplicate: boolean;
+    priorIterations: number[];
+    /** True once total duplicate incidents in this attempt cross the abort threshold — the caller should stop the attempt rather than keep burning budget. */
+    stuck: boolean;
+    /** Non-null whenever isDuplicate is true — meant to be surfaced back to the model as part of the observation. */
+    warning: string | null;
+}
+export declare function actionKey(tool: string, input: unknown): string;
+export declare class DuplicateActionDetector {
+    private abortAfterTotalDuplicates;
+    private seen;
+    private totalDuplicates;
+    /**
+     * @param abortAfterTotalDuplicates total duplicate incidents (not
+     *   necessarily of the same action — any repeats, summed) across the
+     *   whole attempt before it's treated as a stuck loop. 5 is deliberately
+     *   generous: a couple of legitimate re-checks shouldn't trip this, but
+     *   the 11-repeat pattern that motivated this class would trip it early
+     *   instead of running to the full 25-iteration cap.
+     */
+    constructor(abortAfterTotalDuplicates?: number);
+    check(thought: string, tool: string, input: unknown, iteration: number): DuplicateCheckResult;
+    get duplicateCount(): number;
+}