xcoder-dna 0.0.0-stage → 1.3.0

package/dist/orchestrator/defect-migration.js

@@ -0,0 +1,174 @@
+// xcoder:version 2 | xcoder:task swarm-swarm-is-b22287 | xcoder:updated 2026-08-04T12:12:06.562Z | xcoder:subtask swarm-swarm-is-b22287/1
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { loadDefectsIndex, saveDefectsIndex } from "./defect-store.js";
+import { logMigration } from "./defect-logger.js";
+import { createXcoderPaths } from "../util/xcoder-paths.js";
+// ---------------------------------------------------------------------------
+// Path resolution
+// ---------------------------------------------------------------------------
+const DEFECT_FILE_RE = /^defect(\d{4})\.md$/;
+function sentinelPath(workspaceRoot) {
+    return path.join(createXcoderPaths(workspaceRoot).root, ".migrated");
+}
+function legacyDefectsDir(workspaceRoot) {
+    return path.join(workspaceRoot, "defects");
+}
+function newDefectsDir(workspaceRoot) {
+    return createXcoderPaths(workspaceRoot).defectsDir();
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * One-time auto-detection and migration of a legacy `defects/` directory
+ * into `.xcoder/defects/`. Runs once per workspace lifetime (guarded by a
+ * `.xcoder/.migrated` sentinel file).
+ *
+ * If the sentinel is absent, checks for a `defects/` directory. If found,
+ * moves all `defect*.md` files to `.xcoder/defects/`, writes a
+ * `_defects.json` with `status: 'open'` for each, writes
+ * `.log/migration.log`, creates the sentinel, and returns the migrated
+ * records. If `defects/` doesn't exist, still creates the sentinel to
+ * avoid future checks.
+ */
+export async function migrateLegacyDefects(workspaceRoot) {
+    // Guard: check for sentinel file.
+    try {
+        await fs.access(sentinelPath(workspaceRoot));
+    }
+    catch {
+        // Sentinel doesn't exist — proceed with migration.
+        return runMigration(workspaceRoot);
+    }
+    // Sentinel exists — migration already performed.
+    return [];
+}
+// ---------------------------------------------------------------------------
+// Internal
+// ---------------------------------------------------------------------------
+async function runMigration(workspaceRoot) {
+    const migrationEntries = [];
+    const timestamp = new Date().toISOString();
+    const migrated = [];
+    // Check for legacy defects/ directory.
+    let entries = [];
+    try {
+        entries = await fs.readdir(legacyDefectsDir(workspaceRoot));
+    }
+    catch {
+        // No legacy defects/ directory — nothing to migrate. Still create
+        // the sentinel so we don't check again.
+        await touchSentinel(workspaceRoot);
+        return [];
+    }
+    // Ensure target directory exists.
+    await fs.mkdir(newDefectsDir(workspaceRoot), { recursive: true });
+    for (const entry of entries) {
+        const match = entry.match(DEFECT_FILE_RE);
+        if (!match) {
+            migrationEntries.push({
+                timestamp,
+                oldPath: `defects/${entry}`,
+                newPath: "",
+                defectId: "",
+                status: "skipped",
+                reason: `File "${entry}" does not match defect pattern (defectNNNN.md).`,
+            });
+            continue;
+        }
+        const numericId = match[1];
+        const defectId = `DEFECT-${numericId}`;
+        const oldAbs = path.join(legacyDefectsDir(workspaceRoot), entry);
+        const newAbs = path.join(newDefectsDir(workspaceRoot), entry);
+        const oldRel = `defects/${entry}`;
+        const newRel = `.xcoder/defects/${entry}`;
+        // Only migrate regular files — skip directories, symlinks, etc.
+        let stat;
+        try {
+            stat = await fs.stat(oldAbs);
+        }
+        catch {
+            migrationEntries.push({
+                timestamp,
+                oldPath: oldRel,
+                newPath: newRel,
+                defectId,
+                status: "failed",
+                reason: `Cannot stat entry: may not exist or be inaccessible.`,
+            });
+            continue;
+        }
+        if (!stat.isFile()) {
+            migrationEntries.push({
+                timestamp,
+                oldPath: oldRel,
+                newPath: "",
+                defectId,
+                status: "skipped",
+                reason: `Entry "${entry}" matched defect pattern but is not a regular file (type: ${stat.isDirectory() ? 'directory' : 'other'}).`,
+            });
+            continue;
+        }
+        try {
+            await fs.rename(oldAbs, newAbs);
+            migrationEntries.push({
+                timestamp,
+                oldPath: oldRel,
+                newPath: newRel,
+                defectId,
+                status: "migrated",
+                reason: "Successfully moved from legacy defects/ to .xcoder/defects/.",
+            });
+            migrated.push({
+                id: defectId,
+                path: newRel,
+                status: "open",
+                discoveredAt: timestamp,
+                lastUpdated: timestamp,
+                severity: "medium",
+                fixAttempts: [],
+            });
+        }
+        catch (e) {
+            migrationEntries.push({
+                timestamp,
+                oldPath: oldRel,
+                newPath: newRel,
+                defectId,
+                status: "failed",
+                reason: `Rename failed: ${e.message}`,
+            });
+        }
+    }
+    // Write migration log.
+    if (migrationEntries.length > 0) {
+        await logMigration(workspaceRoot, migrationEntries);
+    }
+    // Write _defects.json with migrated records merged into existing index.
+    const index = await loadDefectsIndex(workspaceRoot);
+    for (const record of migrated) {
+        // Only add if not already present (shouldn't happen, but defensive).
+        if (!(record.id in index)) {
+            index[record.id] = record;
+        }
+    }
+    await saveDefectsIndex(workspaceRoot, index);
+    // Touch sentinel.
+    await touchSentinel(workspaceRoot);
+    // Cleanup: remove the legacy defects/ directory if it's now empty.
+    try {
+        const remaining = await fs.readdir(legacyDefectsDir(workspaceRoot));
+        if (remaining.length === 0) {
+            await fs.rmdir(legacyDefectsDir(workspaceRoot));
+        }
+    }
+    catch {
+        // Directory already gone or unreadable — nothing to clean up.
+    }
+    return migrated;
+}
+async function touchSentinel(workspaceRoot) {
+    await fs.mkdir(path.dirname(sentinelPath(workspaceRoot)), { recursive: true });
+    await fs.writeFile(sentinelPath(workspaceRoot), `${new Date().toISOString()}\n`, "utf-8");
+}

package/dist/orchestrator/defect-store.d.ts

@@ -0,0 +1,48 @@
+export type DefectStatus = "open" | "in_progress" | "resolved" | "closed";
+export interface FixAttempt {
+    attemptNumber: number;
+    fixNodeId: string;
+    startedAt: string;
+    completedAt?: string;
+    passed: boolean;
+    notes?: string;
+}
+export interface DefectRecord {
+    id: string;
+    path: string;
+    status: DefectStatus;
+    discoveredAt: string;
+    lastUpdated: string;
+    severity: "low" | "medium" | "high" | "critical";
+    fixAttempts: FixAttempt[];
+    resolvedAt?: string;
+    resolvedBy?: string;
+}
+/** Flat map keyed by defect id (e.g., "DEFECT-0001"). */
+export type DefectsIndex = Record<string, DefectRecord>;
+/**
+ * Reads and parses `_defects.json` from the Xcoder SDLC data directory.
+ * Returns an empty object if the file doesn't exist or is malformed.
+ */
+export declare function loadDefectsIndex(workspaceRoot: string): Promise<DefectsIndex>;
+/**
+ * Writes the full index atomically (temp file + rename) to
+ * `.xcoder/_defects.json`. Matches the same pattern from `task-store.ts`.
+ */
+export declare function saveDefectsIndex(workspaceRoot: string, index: DefectsIndex): Promise<void>;
+/**
+ * Loads the index, upserts the record by defect id, saves. Returns the
+ * fresh index. Used after discovery, status changes, and resolution.
+ */
+export declare function upsertDefect(workspaceRoot: string, record: DefectRecord): Promise<DefectsIndex>;
+/**
+ * Loads the index, returns only entries whose status is "open". Used by
+ * the orchestrator to answer "what open defects exist?" without a
+ * file-system scan.
+ */
+export declare function getOpenDefects(workspaceRoot: string): Promise<DefectRecord[]>;
+/**
+ * Quick check whether a defect id is in the index (any status) — replaces
+ * the old fs.access() check for resolution logic.
+ */
+export declare function defectExists(workspaceRoot: string, defectId: string): Promise<boolean>;

package/dist/orchestrator/defect-store.js

@@ -0,0 +1,76 @@
+// xcoder:version 3 | xcoder:task task-12fb57 | xcoder:updated 2026-08-04T14:29:08.438Z | xcoder:subtask test-st-0a9eed
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { createXcoderPaths } from "../util/xcoder-paths.js";
+// ---------------------------------------------------------------------------
+// Path resolution
+// ---------------------------------------------------------------------------
+function indexFilePath(workspaceRoot) {
+    return path.join(createXcoderPaths(workspaceRoot).root, "_defects.json");
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Reads and parses `_defects.json` from the Xcoder SDLC data directory.
+ * Returns an empty object if the file doesn't exist or is malformed.
+ */
+export async function loadDefectsIndex(workspaceRoot) {
+    try {
+        const raw = await fs.readFile(indexFilePath(workspaceRoot), "utf-8");
+        const parsed = JSON.parse(raw);
+        // Basic structural validation: must be an object.
+        if (typeof parsed !== "object" || Array.isArray(parsed) || parsed === null) {
+            return {};
+        }
+        // Filter out any non-object entries (shouldn't happen, but defensive).
+        const index = {};
+        for (const [id, record] of Object.entries(parsed)) {
+            if (record && typeof record === "object" && !Array.isArray(record)) {
+                index[id] = record;
+            }
+        }
+        return index;
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Writes the full index atomically (temp file + rename) to
+ * `.xcoder/_defects.json`. Matches the same pattern from `task-store.ts`.
+ */
+export async function saveDefectsIndex(workspaceRoot, index) {
+    const file = indexFilePath(workspaceRoot);
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    const tmp = `${file}.tmp`;
+    await fs.writeFile(tmp, JSON.stringify(index, null, 2), "utf8");
+    await fs.rename(tmp, file);
+}
+/**
+ * Loads the index, upserts the record by defect id, saves. Returns the
+ * fresh index. Used after discovery, status changes, and resolution.
+ */
+export async function upsertDefect(workspaceRoot, record) {
+    const index = await loadDefectsIndex(workspaceRoot);
+    index[record.id] = record;
+    await saveDefectsIndex(workspaceRoot, index);
+    return index;
+}
+/**
+ * Loads the index, returns only entries whose status is "open". Used by
+ * the orchestrator to answer "what open defects exist?" without a
+ * file-system scan.
+ */
+export async function getOpenDefects(workspaceRoot) {
+    const index = await loadDefectsIndex(workspaceRoot);
+    return Object.values(index).filter((r) => r.status === "open");
+}
+/**
+ * Quick check whether a defect id is in the index (any status) — replaces
+ * the old fs.access() check for resolution logic.
+ */
+export async function defectExists(workspaceRoot, defectId) {
+    const index = await loadDefectsIndex(workspaceRoot);
+    return defectId in index;
+}

package/dist/orchestrator/healing.d.ts

@@ -0,0 +1,14 @@
+import type { SubtaskNode } from "../types.js";
+/**
+ * The healing loop from the original brief had no attempt cap — "self
+ * healing kicks in and corrects the situation" with no bound is exactly
+ * the runaway-retry risk called out in review. This is the fix: every
+ * subtask carries `healing.maxAttempts` (from `TaskSpec.constraints`,
+ * default 2), and once exhausted the subtask is escalated, never retried
+ * again silently.
+ */
+export interface HealingDecision {
+    action: "retry" | "escalate";
+    hint?: string;
+}
+export declare function decideHealing(node: SubtaskNode, failureReport: string): HealingDecision;

package/dist/orchestrator/healing.js

@@ -0,0 +1,11 @@
+export function decideHealing(node, failureReport) {
+    node.healing.log.push(failureReport);
+    if (node.healing.attempts >= node.healing.maxAttempts) {
+        return { action: "escalate" };
+    }
+    node.healing.attempts += 1;
+    return {
+        action: "retry",
+        hint: `Attempt ${node.healing.attempts}/${node.healing.maxAttempts}. Previous failure: ${failureReport}`,
+    };
+}

package/dist/orchestrator/interactive-steering.d.ts

@@ -0,0 +1,64 @@
+import { EventEmitter } from "node:events";
+import type { SubtaskNode } from "../types.js";
+/** A single interactive steering event — serialisable so it can be persisted in a TaskRun. */
+export interface SteeringInjection {
+    /** Raw text the user typed. */
+    userInput: string;
+    /** ISO-8601 timestamp captured at injection time. */
+    capturedAt: string;
+    /** Node ids that were still pending/ready/in_progress (or healing/validating/blocked) when the pause was triggered — i.e. all nodes NOT already done, failed, or escalated. */
+    affectedNodeIds: string[];
+}
+/**
+ * InteractiveSteeringManager encapsulates the pause/resolve lifecycle for
+ * user steering injection into the DAG. It owns NO I/O (stdin, readline,
+ * keypress) — it is a pure logical controller driven by the orchestrator
+ * loop and the CLI keypress handler.
+ *
+ * Pattern: identical to genesis-agent's `GenesisReActOrchestrator`
+ * pause/inject lifecycle (triggerInterrupt → handleInterruptPause →
+ * injectUserInput), but extracted into a composable manager so the
+ * SdlcOrchestrator can own one without mixing TTY concerns into its
+ * module.
+ */
+export declare class InteractiveSteeringManager extends EventEmitter {
+    private _isPauseRequested;
+    private _resolveWait;
+    private _lastInjection;
+    /** True after requestPause() is called and before injectAndResume() resolves the pause. */
+    get isPauseRequested(): boolean;
+    /** The most recent injection, or null if none has happened yet. */
+    get lastInjection(): SteeringInjection | null;
+    /**
+     * Call from the keypress handler (or any external trigger). Sets the
+     * pause flag; the executeLoop checks this at the next round boundary.
+     *
+     * Idempotent — subsequent calls while already paused are no-ops,
+     * handling debounce/re-entrancy (AC3).
+     */
+    requestPause(): void;
+    /**
+     * Called by executeLoop at the round boundary when isPauseRequested is
+     * true. Returns a Promise that resolves only after `injectAndResume()`
+     * is called (from the CLI layer, after the user has typed their input).
+     *
+     * Emits the "paused" event so external listeners (CLI, UI) can prompt
+     * the user.
+     */
+    waitForInjection(): Promise<SteeringInjection>;
+    /**
+     * Call from the CLI layer after the user has entered their steering
+     * text. Mutates the DAG in place (see Tradeoff 1 in the design doc) and
+     * resolves the promise returned by waitForInjection().
+     *
+     * For every node in `dag` whose status is NOT `done`, `failed`, or
+     * `escalated`:
+     *  1. Appends `[USER STEERING — injected at <ISO>]: <text>` to `goal`.
+     *  2. Sets/updates `upstreamContext.user_steering` with the structured record.
+     *
+     * @param userInput  The raw text the user typed (may be empty).
+     * @param dag        The live DAG array — mutated in place.
+     * @returns The SteeringInjection record (also pushed to run.steeringLog by the caller).
+     */
+    injectAndResume(userInput: string, dag: SubtaskNode[]): SteeringInjection;
+}

package/dist/orchestrator/interactive-steering.js

@@ -0,0 +1,107 @@
+import { EventEmitter } from "node:events";
+/**
+ * InteractiveSteeringManager encapsulates the pause/resolve lifecycle for
+ * user steering injection into the DAG. It owns NO I/O (stdin, readline,
+ * keypress) — it is a pure logical controller driven by the orchestrator
+ * loop and the CLI keypress handler.
+ *
+ * Pattern: identical to genesis-agent's `GenesisReActOrchestrator`
+ * pause/inject lifecycle (triggerInterrupt → handleInterruptPause →
+ * injectUserInput), but extracted into a composable manager so the
+ * SdlcOrchestrator can own one without mixing TTY concerns into its
+ * module.
+ */
+export class InteractiveSteeringManager extends EventEmitter {
+    _isPauseRequested = false;
+    _resolveWait = null;
+    _lastInjection = null;
+    // ── Read-only flags ──
+    /** True after requestPause() is called and before injectAndResume() resolves the pause. */
+    get isPauseRequested() {
+        return this._isPauseRequested;
+    }
+    /** The most recent injection, or null if none has happened yet. */
+    get lastInjection() {
+        return this._lastInjection;
+    }
+    // ── Pause lifecycle ──
+    /**
+     * Call from the keypress handler (or any external trigger). Sets the
+     * pause flag; the executeLoop checks this at the next round boundary.
+     *
+     * Idempotent — subsequent calls while already paused are no-ops,
+     * handling debounce/re-entrancy (AC3).
+     */
+    requestPause() {
+        if (this._isPauseRequested)
+            return; // already paused — debounce
+        this._isPauseRequested = true;
+    }
+    /**
+     * Called by executeLoop at the round boundary when isPauseRequested is
+     * true. Returns a Promise that resolves only after `injectAndResume()`
+     * is called (from the CLI layer, after the user has typed their input).
+     *
+     * Emits the "paused" event so external listeners (CLI, UI) can prompt
+     * the user.
+     */
+    waitForInjection() {
+        this.emit("paused");
+        return new Promise((resolve) => {
+            this._resolveWait = resolve;
+        });
+    }
+    // ── Injection & resume ──
+    /**
+     * Call from the CLI layer after the user has entered their steering
+     * text. Mutates the DAG in place (see Tradeoff 1 in the design doc) and
+     * resolves the promise returned by waitForInjection().
+     *
+     * For every node in `dag` whose status is NOT `done`, `failed`, or
+     * `escalated`:
+     *  1. Appends `[USER STEERING — injected at <ISO>]: <text>` to `goal`.
+     *  2. Sets/updates `upstreamContext.user_steering` with the structured record.
+     *
+     * @param userInput  The raw text the user typed (may be empty).
+     * @param dag        The live DAG array — mutated in place.
+     * @returns The SteeringInjection record (also pushed to run.steeringLog by the caller).
+     */
+    injectAndResume(userInput, dag) {
+        const capturedAt = new Date().toISOString();
+        const affectedNodeIds = [];
+        const STEERING_PREFIX = `\n\n[USER STEERING — injected at ${capturedAt}]: ${userInput}`;
+        for (const node of dag) {
+            // Skip nodes that are already finished or permanently failed.
+            if (node.status === "done" || node.status === "failed" || node.status === "escalated") {
+                continue;
+            }
+            affectedNodeIds.push(node.id);
+            // 1. Goal append (see Tradeoff 2).
+            node.goal += STEERING_PREFIX;
+            // 2. Structured upstreamContext entry.
+            const existing = node.upstreamContext["user_steering"];
+            if (Array.isArray(existing)) {
+                existing.push({ userInput, capturedAt, affectedNodeIds });
+            }
+            else if (existing) {
+                node.upstreamContext["user_steering"] = [
+                    existing,
+                    { userInput, capturedAt, affectedNodeIds },
+                ];
+            }
+            else {
+                node.upstreamContext["user_steering"] = { userInput, capturedAt, affectedNodeIds };
+            }
+        }
+        const injection = { userInput, capturedAt, affectedNodeIds };
+        this._lastInjection = injection;
+        // Resolve the wait promise.
+        if (this._resolveWait) {
+            this._resolveWait(injection);
+            this._resolveWait = null;
+        }
+        // Clear the pause flag — execution can continue.
+        this._isPauseRequested = false;
+        return injection;
+    }
+}

package/dist/orchestrator/interrupt-handler.d.ts

@@ -0,0 +1,30 @@
+import type { SubtaskNode } from "../types.js";
+export interface InterruptContext {
+    taskId: string;
+    dag: SubtaskNode[];
+    totalSubtasks: number;
+    doneCount: number;
+    workspaceRoot: string;
+    signal: "SIGINT" | "INTERACTIVE";
+    isDoubleInterrupt: boolean;
+}
+export interface InterruptAction {
+    kind: "halt" | "force_exit" | "interactive_pause";
+    rolledBackNodeIds: string[];
+    updatedDag: SubtaskNode[];
+    summary: {
+        taskId: string;
+        doneCount: number;
+        totalCount: number;
+        resumeCommand: string;
+        taskFilePath: string;
+    };
+    exitCode: 0 | 1;
+    stderrWarning?: string;
+}
+/**
+ * Pure function that computes the state transition for an interrupt.
+ * Callers pass the live state; it returns what to do.  The orchestrator
+ * is responsible for persisting (saveTaskRun) and printing (terminal).
+ */
+export declare function computeInterruptAction(ctx: InterruptContext): InterruptAction;

package/dist/orchestrator/interrupt-handler.js

@@ -0,0 +1,70 @@
+/** Statuses that should be rolled back to "ready" on interrupt. */
+const ROLLBACK_STATUSES = new Set([
+    "in_progress",
+    "healing",
+    "validating",
+]);
+/**
+ * Pure function that computes the state transition for an interrupt.
+ * Callers pass the live state; it returns what to do.  The orchestrator
+ * is responsible for persisting (saveTaskRun) and printing (terminal).
+ */
+export function computeInterruptAction(ctx) {
+    // Double-interrupt: force exit, no graceful save.
+    if (ctx.isDoubleInterrupt) {
+        return {
+            kind: "force_exit",
+            rolledBackNodeIds: [],
+            updatedDag: ctx.dag,
+            summary: {
+                taskId: ctx.taskId,
+                doneCount: ctx.doneCount,
+                totalCount: ctx.totalSubtasks,
+                resumeCommand: `xcoder resume ${ctx.taskId}`,
+                taskFilePath: `.xcoder/tasks/${ctx.taskId}.json`,
+            },
+            exitCode: 1,
+            stderrWarning: `Force exit after second interrupt — in-flight work may not be fully saved. ` +
+                `Use "xcoder resume ${ctx.taskId}" to recover.`,
+        };
+    }
+    // Interactive pause: no rollback — in-flight nodes stay as they are.
+    if (ctx.signal === "INTERACTIVE") {
+        return {
+            kind: "interactive_pause",
+            rolledBackNodeIds: [],
+            updatedDag: ctx.dag,
+            summary: {
+                taskId: ctx.taskId,
+                doneCount: ctx.doneCount,
+                totalCount: ctx.totalSubtasks,
+                resumeCommand: `xcoder resume ${ctx.taskId}`,
+                taskFilePath: `.xcoder/tasks/${ctx.taskId}.json`,
+            },
+            exitCode: 0,
+        };
+    }
+    // Normal interrupt: roll back in_progress / healing / validating → ready.
+    const rolledBackNodeIds = [];
+    const updatedDag = ctx.dag.map((node) => {
+        if (ROLLBACK_STATUSES.has(node.status)) {
+            rolledBackNodeIds.push(node.id);
+            return { ...node, status: "ready" };
+        }
+        return node;
+    });
+    const actualDoneCount = updatedDag.filter((n) => n.status === "done").length;
+    return {
+        kind: "halt",
+        rolledBackNodeIds,
+        updatedDag,
+        summary: {
+            taskId: ctx.taskId,
+            doneCount: actualDoneCount,
+            totalCount: ctx.totalSubtasks,
+            resumeCommand: `xcoder resume ${ctx.taskId}`,
+            taskFilePath: `.xcoder/tasks/${ctx.taskId}.json`,
+        },
+        exitCode: 0,
+    };
+}

package/dist/orchestrator/lesson-manager.d.ts

@@ -0,0 +1,25 @@
+import type { LessonEntry } from "../types.js";
+/**
+ * Resolve whether lesson-learned is enabled from CLI option + env var.
+ * CLI flag "--lesson-learned" → true; "--no-lesson-learned" → false.
+ * If neither is passed, check XCODER_LESSON_LEARNED ("true" → true).
+ * Default: false.
+ */
+export declare function resolveLessonFlag(cliFlag: boolean | undefined, env: typeof process.env): boolean;
+/**
+ * Read the full contents of .xcoder/lesson.md.
+ * Returns the raw Markdown string (empty string if the file doesn't exist).
+ */
+export declare function loadLessons(workspaceRoot: string): Promise<string>;
+/**
+ * Check if the lessons file exceeds 64 KB.
+ * Returns a warning string if it does, or null if it's within bounds.
+ */
+export declare function checkLessonFileSize(workspaceRoot: string): Promise<string | null>;
+/**
+ * Record a lesson into .xcoder/lesson.md with an atomic write.
+ * Uses temp-file + rename for concurrency safety.
+ * Creates .xcoder/ dir and lesson.md on first write.
+ * Non-fatal: if the write fails, the caller logs a warning and continues.
+ */
+export declare function recordLesson(workspaceRoot: string, entry: LessonEntry): Promise<void>;