xcoder-dna 0.0.0-stage → 1.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Neural Node Labs
+
+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

@@ -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;
+}

package/dist/agents/duplicate-detector.js

@@ -0,0 +1,65 @@
+/**
+ * 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).
+ */
+/** Recursively sorts object keys before stringifying, so two structurally-identical inputs compare equal regardless of key order the model happened to emit them in. */
+function stableStringify(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    const keys = Object.keys(value).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(",")}}`;
+}
+function normalizeThought(thought) {
+    return thought.trim().toLowerCase().replace(/\s+/g, " ");
+}
+export function actionKey(tool, input) {
+    return `${tool}::${stableStringify(input)}`;
+}
+export class DuplicateActionDetector {
+    abortAfterTotalDuplicates;
+    seen = new Map(); // "thought|||tool::input" -> iteration numbers where it occurred
+    totalDuplicates = 0;
+    /**
+     * @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 = 5) {
+        this.abortAfterTotalDuplicates = abortAfterTotalDuplicates;
+    }
+    check(thought, tool, input, iteration) {
+        const key = `${normalizeThought(thought)}|||${actionKey(tool, input)}`;
+        const prior = this.seen.get(key) ?? [];
+        const isDuplicate = prior.length > 0;
+        if (isDuplicate)
+            this.totalDuplicates++;
+        this.seen.set(key, [...prior, iteration]);
+        const stuck = this.totalDuplicates >= this.abortAfterTotalDuplicates;
+        const warning = isDuplicate
+            ? `duplicate detected: this exact reasoning + action ("${tool}") was already tried at iteration ${prior.at(-1)}` +
+                `${prior.length > 1 ? ` (and ${prior.length - 1} time(s) before that)` : ""} — it produced no new information ` +
+                `last time. Try a genuinely different approach instead of repeating it.`
+            : null;
+        return { isDuplicate, priorIterations: prior, stuck, warning };
+    }
+    get duplicateCount() {
+        return this.totalDuplicates;
+    }
+}