xcoder-dna 0.0.0-stage → 1.3.0

package/dist/events/bus.js

@@ -0,0 +1,18 @@
+// xcoder:version 1 | xcoder:task task-4f2baf | xcoder:updated 2026-08-05T05:48:22.242Z | xcoder:subtask code-st-11b531
+import { EventEmitter } from "node:events";
+/**
+ * A single EventEmitter every RAO-producing part of the system emits to —
+ * `agents/sub-agent.ts`, `orchestrator/swarm.ts`, `orchestrator/
+ * sdlc-orchestrator.ts`. Two things consume it today: `util/terminal.ts`
+ * (indirectly — those modules still call `term.*` directly for the CLI's
+ * colored output) and `xcoder observe --json`, which prints every event as
+ * a JSON line. Adding another
+ * consumer (a plain JSON event log, a metrics exporter) means subscribing
+ * here, not threading a new parameter through every function that produces
+ * an event.
+ */
+export const xcoderEvents = new EventEmitter();
+xcoderEvents.setMaxListeners(200);
+export function emitXcoderEvent(ev) {
+    xcoderEvents.emit("event", { ...ev, ts: new Date().toISOString() });
+}

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+export { runDebate } from "./agents/ai-chat-debate.js";
+export { writeReport } from "./agents/ai-chat-report-writer.js";
+export { DuplicateActionDetector } from "./agents/duplicate-detector.js";
+export { GenesisReActOrchestrator, type OrchestratorState } from "./agents/genesis-agent.js";
+export { SamuraiAgent } from "./agents/samurai-agent.js";
+export { SubAgent } from "./agents/sub-agent.js";
+export { addBacklogItem, updateBacklogItem, listBacklogItems, getBacklogItem } from "./backlog/backlog-store.js";
+export { runPoPick } from "./backlog/po-agent.js";
+export { runBenchmark, compareReports } from "./bench/run.js";
+export { registerSwarmCommand } from "./cli/swarm.js";
+export { registerTaskCommand } from "./cli/task.js";
+export { extractWbcArg } from "./cli/wbc-arg.js";
+export { capturedWbc, runCapturedWbc, setWbcSourcePath } from "./cli/wbc.js";
+export { registerLicenseCommand } from "./commands/license.js";
+export { runRelease } from "./commands/release.js";
+export { registerTestCommand } from "./commands/test.js";
+export { type AgentRole } from "./config/loadConfig.js";
+export { applyUserConfig, extractConfigArg, formatUserConfig, parseConfigArg, readUserConfig, saveUserConfig, userConfigPath } from "./config/user-config.js";
+export { getOrchestratorEngine } from "./engine/reasoning-engine.js";
+export { xcoderEvents, type XcoderEvent, emitXcoderEvent } from "./events/bus.js";
+export { InstanceSwarmOrchestrator } from "./instance-swarm/instance-swarm-orchestrator.js";
+export { LICENSE_REQUIRED_EXIT_CODE, isLicensedFeature, maybeRefreshLicense, requireLicense, createDefaultLicenseManager } from "./license/gate.js";
+export { requestScope } from "./llm/budget.js";
+export { LlmClient, type LlmMessage } from "./llm/client.js";
+export { createLlmClient } from "./llm/factory.js";
+export { logDefectEvent } from "./orchestrator/defect-logger.js";
+export { scanForDefects, classifyDefectRouting, buildFixDefectNode, resolveDefect, recordFixAttempt } from "./orchestrator/defect-manager.js";
+export { migrateLegacyDefects } from "./orchestrator/defect-migration.js";
+export { loadDefectsIndex, upsertDefect } from "./orchestrator/defect-store.js";
+export { decideHealing } from "./orchestrator/healing.js";
+export { InteractiveSteeringManager, type SteeringInjection } from "./orchestrator/interactive-steering.js";
+export { type InterruptAction, computeInterruptAction } from "./orchestrator/interrupt-handler.js";
+export { resolveLessonFlag, loadLessons, checkLessonFileSize, recordLesson } from "./orchestrator/lesson-manager.js";
+export { buildProgressSummaryMarkdown } from "./orchestrator/progress-summary.js";
+export { computeReasoningScore, efficiencyHint } from "./orchestrator/reasoning-score.js";
+export { dispatchSwarm } from "./orchestrator/swarm.js";
+export { deliverableFor, acceptanceCriteriaFor, buildInitialPlan, isConversation, buildTaskSpec } from "./orchestrator/task-factory.js";
+export { validateSubtask, type ValidationOutcome } from "./orchestrator/validation-gate.js";
+export { type WksProtocolMap, parseWksProtocol } from "./protocol/wks-protocol-manager.js";
+export { SdlcOrchestrator } from "./sdlc-runtime/sdlc-orchestrator.js";
+export { classifyIntake, INTAKE_RULES, STAGE_ROLE } from "./sdlc-runtime/sdlc-skill.js";
+export { BYLAW_SECTION_HEADER } from "./skills/bylaw-context.js";
+export { reviewDeliverable } from "./skills/bylaw-review.js";
+export { BA_REQUIREMENTS_DIRECTIVE, ROLE_DIRECTIVES } from "./skills/directives.js";
+export { maybeSeedSkillsHome } from "./skills/first-run-seed.js";
+export { inferLayers, renderBylaws, type BylawFinding, type BylawLayer, type ReviewResult } from "./skills/secure-architect.bylaws.js";
+export { sprintStart, sprintStatus, sprintRetro, sprintAbort } from "./sprint/controller.js";
+export { saveTaskRun, loadTaskRun, reconcileOrphanedTasks, saveProgressSummary, listTaskRuns, findResumableTasks, detectResumableTask, isResumableRun, saveTaskRunSync, RESUMABLE_STATUSES } from "./store/task-store.js";
+export { parseStepSpec, runBrowse, type BrowseResult } from "./tools/browse-tool.js";
+export { redact } from "./tools/credential.js";
+export { ensureFreshIndex } from "./tools/index-freshness.js";
+export { type ToolManifestEntry } from "./tools/tool-registry.js";
+export { getOrBuildIndex, buildIndex, type WorkspaceIndex } from "./tools/workspace-index.js";
+export { type SubtaskNode, type TokenUsage, type Role, type SdlcStage, type TaskRun, type TaskSpec, type SubtaskResult, type LessonEntry, type SubtaskStatus, type TaskInputs } from "./types.js";
+export { maybePrintBanner } from "./util/banner.js";
+export { suggestCommands } from "./util/command-suggester.js";
+export { confirmInterrupt } from "./util/confirm-interrupt.js";
+export { isContinueTrigger } from "./util/continue-trigger.js";
+export { logFileAccess, logIndexRefresh } from "./util/file-access-log.js";
+export { FooterManager } from "./util/footer-manager.js";
+export { titleField, sanitizeTitle, versionLabel, FOOTER_TITLE_MAX } from "./util/footer-text.js";
+export { shortId } from "./util/ids.js";
+export { log } from "./util/logger.js";
+export { appendSys, appendScore, taskLogDir } from "./util/logs.js";
+export { getOutputHandler } from "./util/output-handler.js";
+export { getOutputPaths } from "./util/output-paths.js";
+export { killProcessTree, killTrackedPids } from "./util/process-kill.js";
+export { enableProtocolErrorLogging } from "./util/protocol-error-logger.js";
+export { redactSecrets } from "./util/redact.js";
+export { setSpinnerStyle, getSpinnerStyle, createSpinner, type SpinnerHandle, AVAILABLE_SPINNER_STYLES } from "./util/spinner.js";
+export { taskIntro, taskOutro, orchestratorNote, printCrash, printInterruptSummary } from "./util/terminal.js";
+export { sanitizeForTerminal } from "./util/text-sanitize.js";
+export { enableToolErrorLogging } from "./util/tool-error-logger.js";
+export { isInteractiveStdout } from "./util/tty.js";
+export { createXcoderPaths } from "./util/xcoder-paths.js";
+export { XCODER_VERSION } from "./version.js";
+export { WorkerOrchestrator, type WorkerRunReport, type WorkerSubtask, type WorkerRunRequest, type WorkerSubtaskReport } from "./worker-agent/worker-orchestrator.js";
+export { inlineIntoDependents, dagSnapshot, recomputeReady } from "./sdlc-runtime/dag-utils.js";
+export { getStageRole, classifyDesignRole, isInternalRole, SDLC_STAGES, STAGE_ROLE as SDLC_STAGE_ROLE, INTERNAL_ROLES, CONVERSATION_RULE } from "./sdlc-runtime/sdlc-skill.js";

package/dist/index.js

@@ -0,0 +1,77 @@
+// Public barrel — the only import path other packages may use.
+export { runDebate } from "./agents/ai-chat-debate.js";
+export { writeReport } from "./agents/ai-chat-report-writer.js";
+export { DuplicateActionDetector } from "./agents/duplicate-detector.js";
+export { GenesisReActOrchestrator } from "./agents/genesis-agent.js";
+export { SamuraiAgent } from "./agents/samurai-agent.js";
+export { SubAgent } from "./agents/sub-agent.js";
+export { addBacklogItem, updateBacklogItem, listBacklogItems, getBacklogItem } from "./backlog/backlog-store.js";
+export { runPoPick } from "./backlog/po-agent.js";
+export { runBenchmark, compareReports } from "./bench/run.js";
+export { registerSwarmCommand } from "./cli/swarm.js";
+export { registerTaskCommand } from "./cli/task.js";
+export { extractWbcArg } from "./cli/wbc-arg.js";
+export { capturedWbc, runCapturedWbc, setWbcSourcePath } from "./cli/wbc.js";
+export { registerLicenseCommand } from "./commands/license.js";
+export { runRelease } from "./commands/release.js";
+export { registerTestCommand } from "./commands/test.js";
+export { applyUserConfig, extractConfigArg, formatUserConfig, parseConfigArg, readUserConfig, saveUserConfig, userConfigPath } from "./config/user-config.js";
+export { getOrchestratorEngine } from "./engine/reasoning-engine.js";
+export { xcoderEvents, emitXcoderEvent } from "./events/bus.js";
+export { InstanceSwarmOrchestrator } from "./instance-swarm/instance-swarm-orchestrator.js";
+export { LICENSE_REQUIRED_EXIT_CODE, isLicensedFeature, maybeRefreshLicense, requireLicense, createDefaultLicenseManager } from "./license/gate.js";
+export { requestScope } from "./llm/budget.js";
+export { LlmClient } from "./llm/client.js";
+export { createLlmClient } from "./llm/factory.js";
+export { logDefectEvent } from "./orchestrator/defect-logger.js";
+export { scanForDefects, classifyDefectRouting, buildFixDefectNode, resolveDefect, recordFixAttempt } from "./orchestrator/defect-manager.js";
+export { migrateLegacyDefects } from "./orchestrator/defect-migration.js";
+export { loadDefectsIndex, upsertDefect } from "./orchestrator/defect-store.js";
+export { decideHealing } from "./orchestrator/healing.js";
+export { InteractiveSteeringManager } from "./orchestrator/interactive-steering.js";
+export { computeInterruptAction } from "./orchestrator/interrupt-handler.js";
+export { resolveLessonFlag, loadLessons, checkLessonFileSize, recordLesson } from "./orchestrator/lesson-manager.js";
+export { buildProgressSummaryMarkdown } from "./orchestrator/progress-summary.js";
+export { computeReasoningScore, efficiencyHint } from "./orchestrator/reasoning-score.js";
+export { dispatchSwarm } from "./orchestrator/swarm.js";
+export { deliverableFor, acceptanceCriteriaFor, buildInitialPlan, isConversation, buildTaskSpec } from "./orchestrator/task-factory.js";
+export { validateSubtask } from "./orchestrator/validation-gate.js";
+export { parseWksProtocol } from "./protocol/wks-protocol-manager.js";
+export { SdlcOrchestrator } from "./sdlc-runtime/sdlc-orchestrator.js";
+export { classifyIntake, INTAKE_RULES, STAGE_ROLE } from "./sdlc-runtime/sdlc-skill.js";
+export { BYLAW_SECTION_HEADER } from "./skills/bylaw-context.js";
+export { reviewDeliverable } from "./skills/bylaw-review.js";
+export { BA_REQUIREMENTS_DIRECTIVE, ROLE_DIRECTIVES } from "./skills/directives.js";
+export { maybeSeedSkillsHome } from "./skills/first-run-seed.js";
+export { inferLayers, renderBylaws } from "./skills/secure-architect.bylaws.js";
+export { sprintStart, sprintStatus, sprintRetro, sprintAbort } from "./sprint/controller.js";
+export { saveTaskRun, loadTaskRun, reconcileOrphanedTasks, saveProgressSummary, listTaskRuns, findResumableTasks, detectResumableTask, isResumableRun, saveTaskRunSync, RESUMABLE_STATUSES } from "./store/task-store.js";
+export { parseStepSpec, runBrowse } from "./tools/browse-tool.js";
+export { redact } from "./tools/credential.js";
+export { ensureFreshIndex } from "./tools/index-freshness.js";
+export { getOrBuildIndex, buildIndex } from "./tools/workspace-index.js";
+export { maybePrintBanner } from "./util/banner.js";
+export { suggestCommands } from "./util/command-suggester.js";
+export { confirmInterrupt } from "./util/confirm-interrupt.js";
+export { isContinueTrigger } from "./util/continue-trigger.js";
+export { logFileAccess, logIndexRefresh } from "./util/file-access-log.js";
+export { FooterManager } from "./util/footer-manager.js";
+export { titleField, sanitizeTitle, versionLabel, FOOTER_TITLE_MAX } from "./util/footer-text.js";
+export { shortId } from "./util/ids.js";
+export { log } from "./util/logger.js";
+export { appendSys, appendScore, taskLogDir } from "./util/logs.js";
+export { getOutputHandler } from "./util/output-handler.js";
+export { getOutputPaths } from "./util/output-paths.js";
+export { killProcessTree, killTrackedPids } from "./util/process-kill.js";
+export { enableProtocolErrorLogging } from "./util/protocol-error-logger.js";
+export { redactSecrets } from "./util/redact.js";
+export { setSpinnerStyle, getSpinnerStyle, createSpinner, AVAILABLE_SPINNER_STYLES } from "./util/spinner.js";
+export { taskIntro, taskOutro, orchestratorNote, printCrash, printInterruptSummary } from "./util/terminal.js";
+export { sanitizeForTerminal } from "./util/text-sanitize.js";
+export { enableToolErrorLogging } from "./util/tool-error-logger.js";
+export { isInteractiveStdout } from "./util/tty.js";
+export { createXcoderPaths } from "./util/xcoder-paths.js";
+export { XCODER_VERSION } from "./version.js";
+export { WorkerOrchestrator } from "./worker-agent/worker-orchestrator.js";
+export { inlineIntoDependents, dagSnapshot, recomputeReady } from "./sdlc-runtime/dag-utils.js";
+export { getStageRole, classifyDesignRole, isInternalRole, SDLC_STAGES, STAGE_ROLE as SDLC_STAGE_ROLE, INTERNAL_ROLES, CONVERSATION_RULE } from "./sdlc-runtime/sdlc-skill.js";

package/dist/indexing/ignoreRules.d.ts

@@ -0,0 +1 @@
+export declare function loadIgnoreRules(cwd?: string): string[];

package/dist/indexing/ignoreRules.js

@@ -0,0 +1,53 @@
+import fs from "node:fs";
+import path from "node:path";
+const IGNORE_FILES = [".agent/.agentignore", ".gitignore", ".dockerignore"];
+const ALWAYS_IGNORE = ["**/node_modules/**", ".git/**", "dist/**", ".agent/index/**", ".log/**"];
+/**
+ * Converts a single ignore-line pattern into a glob-compatible pattern.
+ *
+ * - Trailing slash means directory only -> prefix with double-star-slash and
+ *   append double-star so it matches at any depth.
+ * - Bare directory name (no path separators, no dots, no glob chars) -> prefix
+ *   with double-star-slash and append slash-double-star so it matches the
+ *   directory and everything inside at any depth.
+ * - Patterns already starting with double-star-slash are left as-is.
+ * - Everything else is treated as a literal file/glob pattern.
+ */
+function normalizePattern(line) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#"))
+        return trimmed;
+    // Already a recursive glob -- use as-is
+    if (trimmed.startsWith("**/"))
+        return trimmed;
+    // Directory-only pattern: "node_modules/" -> "**/node_modules/**"
+    if (trimmed.endsWith("/"))
+        return `**/${trimmed}**`;
+    // Bare directory name (no path separators, no dots, no glob chars):
+    // e.g. "dist" -> "**/dist/**", but "Thumbs.db" stays as-is (has a dot)
+    if (!trimmed.includes("/") &&
+        !trimmed.includes("\\") &&
+        !trimmed.includes(".") &&
+        !trimmed.includes("*") &&
+        !trimmed.includes("?")) {
+        return `**/${trimmed}/**`;
+    }
+    return trimmed;
+}
+export function loadIgnoreRules(cwd = process.cwd()) {
+    const rules = new Set(ALWAYS_IGNORE);
+    for (const rel of IGNORE_FILES) {
+        const p = path.join(cwd, rel);
+        if (!fs.existsSync(p))
+            continue;
+        const lines = fs
+            .readFileSync(p, "utf-8")
+            .split("\n")
+            .map((l) => l.trim())
+            .filter((l) => l && !l.startsWith("#"));
+        for (const line of lines) {
+            rules.add(normalizePattern(line));
+        }
+    }
+    return [...rules];
+}

package/dist/instance-swarm/instance-swarm-orchestrator.d.ts

@@ -0,0 +1,57 @@
+import type { TokenUsage } from "../types.js";
+import type { SwarmDispatchResult } from "../orchestrator/swarm.js";
+import { LlmClient } from "../llm/client.js";
+export interface InstanceSwarmResult {
+    instanceId: string;
+    status: "completed" | "failed" | "timeout";
+    results: SwarmDispatchResult[];
+    errors: string[];
+    totalTokenUsage: TokenUsage;
+    outputDir: string;
+}
+export interface InstanceSwarmOrchestratorHooks {
+    /** Called when a worker starts processing its goal */
+    onWorkerStart?: (workerIndex: number, workerId: string) => void;
+    /** Called when a worker completes with a result */
+    onWorkerFinish?: (workerIndex: number, workerId: string, crashed: boolean, summary: string) => void;
+    /** Called when a worker fails with an error */
+    onWorkerError?: (workerIndex: number, workerId: string, error: string) => void;
+    /** Called when the swarm run completes */
+    onSwarmComplete?: (result: InstanceSwarmResult) => void;
+}
+export interface InstanceSwarmOrchestratorOptions {
+    workspaceRoot: string;
+    llm: LlmClient;
+    /** Worker (instance_agent role) client — defaults to `llm`. */
+    agentClient?: LlmClient;
+    concurrency?: number;
+    maxIterations?: number;
+    outputDir?: string;
+    instanceId?: string;
+    hooks?: InstanceSwarmOrchestratorHooks;
+}
+/**
+ * Instance Samurai Swarm Orchestrator.
+ *
+ * Creates and dispatches one or more SubAgents with a given goal and
+ * protocol section injected into their system prompts. Multiple instances
+ * run concurrently with full isolation — the orchestrator never throws,
+ * it returns a structured result.
+ */
+export declare class InstanceSwarmOrchestrator {
+    private opts;
+    constructor(opts: InstanceSwarmOrchestratorOptions);
+    /**
+     * Dispatches SubAgents (one or a bounded pool) against the goal, with
+     * protocol section from wks_protocol.md injected. Returns a structured
+     * InstanceSwarmResult — NEVER throws.
+     */
+    run(goal: string, protocolName: string): Promise<InstanceSwarmResult>;
+    /**
+     * Builds a synthetic SubtaskNode suitable for SubAgent consumption.
+     * This avoids coupling to the Master Orchestrator's DAG lifecycle —
+     * we create self-contained nodes with the goal and protocol overrides
+     * already baked in.
+     */
+    private buildSyntheticNode;
+}

package/dist/instance-swarm/instance-swarm-orchestrator.js

@@ -0,0 +1,204 @@
+import { SubAgent } from "../agents/sub-agent.js";
+import { parseWksProtocol } from "../protocol/wks-protocol-manager.js";
+import { resolveRole, resolveSectionKey } from "./protocol-name-resolver.js";
+import { shortId } from "../util/ids.js";
+import { getOutputPaths } from "../util/output-paths.js";
+import path from "node:path";
+import { promises as fs } from "node:fs";
+// (end of options interface)
+/**
+ * Instance Samurai Swarm Orchestrator.
+ *
+ * Creates and dispatches one or more SubAgents with a given goal and
+ * protocol section injected into their system prompts. Multiple instances
+ * run concurrently with full isolation — the orchestrator never throws,
+ * it returns a structured result.
+ */
+export class InstanceSwarmOrchestrator {
+    opts;
+    constructor(opts) {
+        const now = new Date().toISOString().replace(/[:.]/g, "-");
+        const instanceId = opts.instanceId ?? `swarm-${shortId("is")}`;
+        const outputDir = opts.outputDir ??
+            getOutputPaths({ cwd: opts.workspaceRoot }).instanceSwarmDir(`${instanceId}-${now}`);
+        this.opts = {
+            workspaceRoot: opts.workspaceRoot,
+            llm: opts.llm,
+            agentClient: opts.agentClient,
+            concurrency: opts.concurrency ?? 1,
+            maxIterations: opts.maxIterations ?? 200,
+            outputDir,
+            instanceId,
+            hooks: opts.hooks ?? {},
+        };
+    }
+    /**
+     * Dispatches SubAgents (one or a bounded pool) against the goal, with
+     * protocol section from wks_protocol.md injected. Returns a structured
+     * InstanceSwarmResult — NEVER throws.
+     */
+    async run(goal, protocolName) {
+        const { instanceId, outputDir, workspaceRoot, llm, agentClient, concurrency, maxIterations } = this.opts;
+        const errors = [];
+        const results = [];
+        const totalTokenUsage = { inputTokens: 0, outputTokens: 0 };
+        // Ensure output directory exists
+        try {
+            await fs.mkdir(outputDir, { recursive: true });
+        }
+        catch (e) {
+            errors.push(`failed to create output directory ${outputDir}: ${e.message}`);
+        }
+        // Load protocol map
+        let protocolMap = {};
+        try {
+            const filePath = path.join(this.opts.workspaceRoot, "wks_protocol.md");
+            const content = await fs.readFile(filePath, "utf-8");
+            protocolMap = parseWksProtocol(content);
+        }
+        catch {
+            // File missing or unreadable — proceed without protocol overrides
+        }
+        // Resolve protocol name to role + section key
+        const role = resolveRole(protocolName);
+        const sectionKey = resolveSectionKey(protocolName);
+        // Build protocol overrides for the resolved role
+        let protocolOverrides;
+        if (sectionKey && protocolMap[sectionKey] !== undefined) {
+            protocolOverrides = { [role]: protocolMap[sectionKey] };
+        }
+        // Resolve the section content for logging/debugging
+        const sectionBody = sectionKey ? protocolMap[sectionKey] : undefined;
+        const hasProtocolSection = sectionBody !== undefined && sectionBody !== "";
+        // Build synthetic subtask nodes — one per concurrent worker.
+        // Each worker gets the same goal and protocol overrides, and they
+        // operate independently (no shared state).
+        const taskId = `swarm-${instanceId}`;
+        const maxConcurrency = Math.max(1, concurrency);
+        const nodes = Array.from({ length: maxConcurrency }, (_, i) => this.buildSyntheticNode({
+            taskId,
+            workerIndex: i,
+            goal,
+            role,
+            hasProtocolSection,
+            sectionBody,
+        }));
+        // Run workers concurrently with bounded pool (same pattern as dispatchSwarm)
+        const queue = [...nodes];
+        const { hooks } = this.opts;
+        async function worker() {
+            while (queue.length) {
+                const node = queue.shift();
+                if (!node)
+                    return;
+                // Extract worker index from synthetic node id (format: taskId/index)
+                const workerIndex = parseInt(node.id.split("/").pop() ?? "0", 10);
+                hooks.onWorkerStart?.(workerIndex, node.id);
+                const agent = new SubAgent({
+                    taskId: node.id.split("/")[0],
+                    workspaceRoot,
+                    llm: agentClient ?? llm,
+                    maxIterations,
+                    protocolOverrides,
+                });
+                let result;
+                try {
+                    result = await agent.run(node);
+                }
+                catch (e) {
+                    const message = e.stack ?? String(e);
+                    errors.push(`worker for ${node.id} crashed: ${message}`);
+                    hooks.onWorkerError?.(workerIndex, node.id, message);
+                    result = {
+                        summary: `Sub Agent crashed unexpectedly: ${e.message}`,
+                        deliverable: null,
+                        filesTouched: [],
+                        raoTrace: [],
+                        tokenUsage: { inputTokens: 0, outputTokens: 0 },
+                        iterations: 0,
+                        crashed: true,
+                    };
+                }
+                hooks.onWorkerFinish?.(workerIndex, node.id, result.crashed ?? false, result.summary);
+                results.push({ subtaskId: node.id, result });
+                totalTokenUsage.inputTokens += result.tokenUsage.inputTokens;
+                totalTokenUsage.outputTokens += result.tokenUsage.outputTokens;
+            }
+        }
+        try {
+            const workerCount = Math.min(maxConcurrency, nodes.length);
+            const workerPromises = [];
+            for (let i = 0; i < workerCount; i++) {
+                workerPromises.push(worker());
+            }
+            await Promise.all(workerPromises);
+        }
+        catch (e) {
+            errors.push(`orchestrator worker pool failed: ${e.message}`);
+        }
+        const allCrashed = results.length > 0 && results.every((r) => r.result.crashed);
+        const anyTimeout = results.some((r) => !r.result.crashed &&
+            !r.result.stuckLoop &&
+            r.result.iterations >= maxIterations);
+        let status = "completed";
+        if (allCrashed && results.length > 0) {
+            status = "failed";
+        }
+        else if (anyTimeout) {
+            status = "timeout";
+        }
+        else if (errors.length > 0 && results.length === 0) {
+            status = "failed";
+        }
+        const finalResult = {
+            instanceId,
+            status,
+            results,
+            errors,
+            totalTokenUsage,
+            outputDir,
+        };
+        hooks.onSwarmComplete?.(finalResult);
+        return finalResult;
+    }
+    /**
+     * Builds a synthetic SubtaskNode suitable for SubAgent consumption.
+     * This avoids coupling to the Master Orchestrator's DAG lifecycle —
+     * we create self-contained nodes with the goal and protocol overrides
+     * already baked in.
+     */
+    buildSyntheticNode(params) {
+        const nodeId = `${params.taskId}/${params.workerIndex}`;
+        const protocolNote = params.hasProtocolSection
+            ? `\nThe wks_protocol.md section for role "${params.role}" has been injected into your system prompt.`
+            : "";
+        return {
+            id: nodeId,
+            stage: "code", // Default stage — the orchestrator runs isolated from the WBS DAG
+            role: params.role,
+            engine: "react-v1",
+            dependsOn: [],
+            goal: `${params.goal}${protocolNote}`,
+            upstreamContext: {},
+            deliverableSpec: "Working implementation matching the goal, with files_touched listing every file written.",
+            acceptanceCriteria: [
+                {
+                    id: "AC1",
+                    type: "schema",
+                    description: "Every file referenced in the goal was actually written (files_touched is non-empty).",
+                },
+                {
+                    id: "AC2",
+                    type: "command",
+                    description: "The project's own build/typecheck command exits 0.",
+                },
+            ],
+            status: "ready",
+            healing: {
+                attempts: 0,
+                maxAttempts: 2,
+                log: [],
+            },
+        };
+    }
+}

package/dist/instance-swarm/protocol-name-resolver.d.ts

@@ -0,0 +1,23 @@
+import type { Role } from "../types.js";
+import type { WksProtocolKey } from "../protocol/wks-protocol-manager.js";
+/**
+ * Maps user-visible protocol names (e.g. 'coder', 'secops', 'ui ux') to
+ * canonical Role values already defined in the Role union type.
+ *
+ * This avoids adding new Role values (which would require new directives
+ * and break the closed Role union) while still giving users the protocol
+ * sections they expect from wks_protocol.md.
+ */
+export declare const ALIAS_MAP: Record<string, Role>;
+/**
+ * Returns the canonical Role for a given protocol name. Falls back to the
+ * protocol name itself if it's a recognised WksProtocolKey but not a Role
+ * (i.e. 'master-orchestrator'). Returns 'conversation' as ultimate fallback.
+ */
+export declare function resolveRole(protocolName: string): Role;
+/**
+ * Returns the WksProtocolKey to look up in the parsed wks_protocol.md.
+ * Returns undefined if no mapping exists — in which case the SubAgent runs
+ * without a protocol section override.
+ */
+export declare function resolveSectionKey(protocolName: string): WksProtocolKey | undefined;

package/dist/instance-swarm/protocol-name-resolver.js

@@ -0,0 +1,64 @@
+/**
+ * Maps user-visible protocol names (e.g. 'coder', 'secops', 'ui ux') to
+ * canonical Role values already defined in the Role union type.
+ *
+ * This avoids adding new Role values (which would require new directives
+ * and break the closed Role union) while still giving users the protocol
+ * sections they expect from wks_protocol.md.
+ */
+export const ALIAS_MAP = {
+    coder: "programmer",
+    secops: "defect-manager",
+    "ui ux": "ui-api-tester",
+    "ui/ux": "ui-api-tester",
+};
+/**
+ * Returns the canonical Role for a given protocol name. Falls back to the
+ * protocol name itself if it's a recognised WksProtocolKey but not a Role
+ * (i.e. 'master-orchestrator'). Returns 'conversation' as ultimate fallback.
+ */
+export function resolveRole(protocolName) {
+    const normalised = protocolName.toLowerCase().trim();
+    // 1. Explicit alias?
+    if (ALIAS_MAP[normalised])
+        return ALIAS_MAP[normalised];
+    // 2. Already a known Role?
+    const KNOWN_ROLES = new Set([
+        "requirements-analyst",
+        "architect",
+        "programmer",
+        "refactorer",
+        "tester",
+        "ui-api-tester",
+        "technical-writer",
+        "devops",
+        "conversation",
+        "business-analyst",
+        "defect-manager",
+    ]);
+    if (KNOWN_ROLES.has(normalised))
+        return normalised;
+    // 3. Ultimate fallback.
+    return "conversation";
+}
+/**
+ * Returns the WksProtocolKey to look up in the parsed wks_protocol.md.
+ * Returns undefined if no mapping exists — in which case the SubAgent runs
+ * without a protocol section override.
+ */
+export function resolveSectionKey(protocolName) {
+    const normalised = protocolName.toLowerCase().trim();
+    // 1. Explicit alias mapping
+    if (ALIAS_MAP[normalised])
+        return ALIAS_MAP[normalised];
+    // 2. Direct Role match
+    const role = resolveRole(normalised);
+    if (role !== "conversation")
+        return role;
+    // 3. If the original string matches a known wks protocol key pattern but isn't a Role,
+    //    return it directly (e.g. 'master-orchestrator').
+    if (normalised === "master-orchestrator")
+        return "master-orchestrator";
+    // 4. Not a recognised key — no override
+    return undefined;
+}

package/dist/license/gate.d.ts

@@ -0,0 +1,31 @@
+import { type LicenseStore } from "./store.js";
+import { type LicenseApi } from "./http-client.js";
+import { type LicenseManager } from "./manager.js";
+import { type TrustAnchor } from "./trust-anchor.js";
+import { type LicenseGateResult } from "./types.js";
+/** Exit code for "this command needs an active license". */
+export declare const LICENSE_REQUIRED_EXIT_CODE = 4;
+export declare function isLicensedFeature(commandPath: string): boolean;
+/**
+ * The hint a denial prints. Per-tree, so a v1 user is told v1's own binary
+ * name rather than another tree's command.
+ */
+export declare const ACTIVATE_COMMAND = "xcoder license activate";
+/**
+ * Decide whether a licensed feature may run.
+ *
+ * Never throws, never touches the network. Returns the verified claims on
+ * success so the caller does not have to re-read the store.
+ */
+export declare function requireLicense(opts?: {
+    now?: () => number;
+    store?: LicenseStore;
+    anchor?: TrustAnchor;
+}): LicenseGateResult;
+/**
+ * Opportunity-refresh after a successful gate. Best-effort by contract: any
+ * failure is swallowed so an offline machine still runs the command.
+ */
+export declare function maybeRefreshLicense(mgr: LicenseManager, now?: () => number): Promise<void>;
+/** Build a manager with production wiring (used by licensed call sites). */
+export declare function createDefaultLicenseManager(api?: LicenseApi, store?: LicenseStore): LicenseManager;