@kognai/orchestrator-core 0.1.0

package/dist/lib/failure-library.js

@@ -0,0 +1,349 @@
+"use strict";
+/**
+ * Failure Library Consumer — TICKET-152 Gap 2.
+ *
+ * `code-failure-logger.ts` WRITES rejection records to
+ * `<root>/data/failure-library/code/fail-*.json`. Until now nothing READ them
+ * back, so a task could be rejected for the same reason on every attempt and the
+ * agent never saw its own history — e.g. `ksl_batch_runner` accumulated 75 failure
+ * records and still never converged. This module closes that loop.
+ *
+ * Three surfaces:
+ *   1. aggregateCodeFailures()  — collapse the raw log into per-task summaries
+ *                                 (how deep it stuck, what kind of failure, the
+ *                                 recurring theme). The analytics view.
+ *   2. promoteLessons()         — write a human/agent-readable LESSONS.md to the
+ *                                 failure-library root. The promotion view; this
+ *                                 is the `learnings_ref` decomposer-feedback points at.
+ *   3. retrieveTaskFailures()   — retry-aware retrieval for ONE task: a compact
+ *                                 "here is what your last N attempts were rejected
+ *                                 for, do not repeat it" brief, ready to inject
+ *                                 into the next attempt's prompt. The feedback view.
+ *
+ * Stdlib only: fs, path. Read failures degrade to empty results — a missing or
+ * corrupt library must never throw into a running sprint.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_THRESHOLDS = void 0;
+exports.projectCodeFailureToBase = projectCodeFailureToBase;
+exports.readAllCodeFailures = readAllCodeFailures;
+exports.failureSignature = failureSignature;
+exports.aggregateCodeFailures = aggregateCodeFailures;
+exports.retrieveTaskFailures = retrieveTaskFailures;
+exports.retrieveAgentFailures = retrieveAgentFailures;
+exports.renderLessons = renderLessons;
+exports.promoteLessons = promoteLessons;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const engine_paths_1 = require("./engine-paths");
+exports.DEFAULT_THRESHOLDS = {
+    recurring: 3,
+    noConvergeAttempt: 3,
+    noConvergeVolume: 10,
+};
+function codeFailureDir(root) {
+    return (0, path_1.join)((0, engine_paths_1.resolveEnginePaths)(root).failureLibrary, 'code');
+}
+/** Project a raw code-failure record onto FailureEntryBase (see contract conformance). */
+function projectCodeFailureToBase(e) {
+    return {
+        entry_id: e.entry_id,
+        filed_at: e.filed_at,
+        subject_ref: e.task_id,
+        failure_class: e.fail_type,
+        score: typeof e.score === 'number' ? e.score : null,
+        filed_by: e.agent_id,
+    };
+}
+/**
+ * Read every fail-*.json under data/failure-library/code/. Corrupt or partial
+ * files are skipped, never thrown — the writer and readers run concurrently, so a
+ * half-written file is expected and must not break a read.
+ */
+function readAllCodeFailures(root) {
+    const dir = codeFailureDir(root);
+    if (!(0, fs_1.existsSync)(dir))
+        return [];
+    let names;
+    try {
+        names = (0, fs_1.readdirSync)(dir).filter((n) => n.startsWith('fail-') && n.endsWith('.json'));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names) {
+        try {
+            const raw = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(dir, name), 'utf8'));
+            if (raw && typeof raw.task_id === 'string')
+                out.push(raw);
+        }
+        catch {
+            // Skip unreadable/half-written entry.
+        }
+    }
+    return out;
+}
+/**
+ * Reduce a rejection to a coarse, deterministic signature so recurring themes
+ * surface across attempts. No LLM — keyword heuristics over the reason + issues.
+ */
+function failureSignature(entry) {
+    const text = `${entry.rejection_reason || ''} ${(entry.issues || [])
+        .map((i) => i.description)
+        .join(' ')}`.toLowerCase();
+    if (/truncat/.test(text))
+        return 'truncation';
+    if (/destructive|wholesale rewrite|deleted (the|existing)/.test(text))
+        return 'destructive rewrite';
+    if (/typecheck failed|tsc|ts\d{3,5}|is not assignable|does not exist on type/.test(text))
+        return 'typecheck / compile error';
+    if (/unused import|no-unused-vars|ts6133|imported but never/.test(text))
+        return 'unused / dangling import';
+    if (/partial|half-applied|skipped entirely|edit \(2\)|never rendered|not performed/.test(text))
+        return 'partial / incomplete edit';
+    if (/no files|empty diff|nothing changed/.test(text))
+        return 'no files written';
+    if (/meta-?commentary|self-justifying|comment claiming|refusal/.test(text))
+        return 'commentary instead of implementation';
+    if (/spec non-compliance|task spec|did not follow|out of scope/.test(text))
+        return 'spec non-compliance';
+    return entry.fail_type || 'unknown';
+}
+function bump(map, key) {
+    map[key] = (map[key] || 0) + 1;
+}
+/**
+ * Collapse the raw log into one summary per task_id, sorted most-failed first.
+ */
+function aggregateCodeFailures(root, thresholds = exports.DEFAULT_THRESHOLDS) {
+    const byTask = new Map();
+    for (const e of readAllCodeFailures(root)) {
+        const list = byTask.get(e.task_id) || [];
+        list.push(e);
+        byTask.set(e.task_id, list);
+    }
+    const summaries = [];
+    for (const [taskId, entries] of byTask) {
+        entries.sort((a, b) => String(a.filed_at).localeCompare(String(b.filed_at)));
+        const latest = entries[entries.length - 1];
+        const fail_types = {};
+        const models = {};
+        const signatures = {};
+        const sprints = new Set();
+        let maxAttempt = 0;
+        for (const e of entries) {
+            bump(fail_types, e.fail_type || 'unknown');
+            bump(models, e.model || 'unknown');
+            bump(signatures, failureSignature(e));
+            if (e.sprint_id)
+                sprints.add(e.sprint_id);
+            if (typeof e.attempt_num === 'number' && e.attempt_num > maxAttempt)
+                maxAttempt = e.attempt_num;
+        }
+        summaries.push({
+            task_id: taskId,
+            total_failures: entries.length,
+            max_attempt: maxAttempt,
+            fail_types,
+            models,
+            signatures,
+            sprint_ids: [...sprints],
+            latest_score: latest.score ?? 0,
+            latest_reason: latest.rejection_reason || '',
+            latest_filed_at: latest.filed_at || '',
+            recurring: entries.length >= thresholds.recurring,
+            no_converge: maxAttempt >= thresholds.noConvergeAttempt || entries.length >= thresholds.noConvergeVolume,
+        });
+    }
+    summaries.sort((a, b) => b.total_failures - a.total_failures || b.max_attempt - a.max_attempt);
+    return summaries;
+}
+function truncate(s, n) {
+    if (!s)
+        return '';
+    const clean = s.replace(/\s+/g, ' ').trim();
+    return clean.length <= n ? clean : `${clean.slice(0, n - 1)}…`;
+}
+/**
+ * Retrieve everything the library knows about ONE task and synthesize a compact
+ * avoidance brief. This is the piece that was missing: call it before re-running a
+ * rejected task and prepend `.brief` to the agent's prompt so attempt N+1 can see
+ * why attempts 1..N were rejected.
+ */
+function retrieveTaskFailures(taskId, opts = {}) {
+    const maxAttempts = opts.maxAttempts ?? 5;
+    const maxReasonChars = opts.maxReasonChars ?? 240;
+    const maxIssues = opts.maxIssuesPerAttempt ?? 3;
+    const all = readAllCodeFailures(opts.root)
+        .filter((e) => e.task_id === taskId)
+        .sort((a, b) => String(a.filed_at).localeCompare(String(b.filed_at)));
+    if (all.length === 0) {
+        return { task_id: taskId, prior_attempts: 0, entries: [], themes: [], brief: '' };
+    }
+    // Theme ranking across the FULL history (not just the windowed entries).
+    const sigCounts = {};
+    for (const e of all)
+        bump(sigCounts, failureSignature(e));
+    const themes = Object.entries(sigCounts)
+        .sort((a, b) => b[1] - a[1])
+        .map(([sig]) => sig);
+    // Most-recent window for the per-attempt detail.
+    const window = all.slice(-maxAttempts);
+    const lines = [];
+    lines.push(`⚠️ PRIOR FAILURES for "${taskId}" — ${all.length} rejected attempt(s) on record. ` +
+        `Do NOT repeat these mistakes:`);
+    for (const e of window) {
+        const score = typeof e.score === 'number' ? `${e.score}/100` : 'n/a';
+        lines.push(`  • attempt ${e.attempt_num} (${e.fail_type}, ${score}): ${truncate(e.rejection_reason, maxReasonChars)}`);
+        const issues = (e.issues || []).filter((i) => i && i.description).slice(0, maxIssues);
+        for (const i of issues) {
+            lines.push(`      - ${i.severity}: ${truncate(`${i.file ? i.file + ' — ' : ''}${i.description}`, maxReasonChars)}`);
+        }
+    }
+    if (all.length > window.length) {
+        lines.push(`  • (…${all.length - window.length} earlier attempt(s) omitted)`);
+    }
+    lines.push(`Recurring theme${themes.length > 1 ? 's' : ''}: ${themes.slice(0, 3).join('; ')}.`);
+    return {
+        task_id: taskId,
+        prior_attempts: all.length,
+        entries: window,
+        themes,
+        brief: lines.join('\n'),
+    };
+}
+/**
+ * Match an entry's stored agent id against a queried id, tolerating the Gap-1
+ * transition: new entries carry `did:kognai:coder`, historical ones the bare
+ * role `coder`. A query for either form matches both.
+ */
+function agentMatches(entryAgentId, queryAgentId) {
+    if (!entryAgentId)
+        return false;
+    if (entryAgentId === queryAgentId)
+        return true;
+    const strip = (s) => s.replace(/^did:kognai:(?:[^:]+:)?/, '');
+    return strip(entryAgentId) === strip(queryAgentId);
+}
+/**
+ * "Failures attributed to agent_id X over the last N days." Powers SOP-GEN-013
+ * Improve-mode and the per-agent AIC curve in TICKET-110. `nowISO` is injected
+ * (callers pass new Date().toISOString()) to keep this deterministic/testable.
+ */
+function retrieveAgentFailures(agentId, nowISO, opts = {}) {
+    const sinceDays = opts.sinceDays ?? 14;
+    const maxEntries = opts.maxEntries ?? 20;
+    const cutoff = Date.parse(nowISO) - sinceDays * 86_400_000;
+    const matched = readAllCodeFailures(opts.root)
+        .filter((e) => agentMatches(e.agent_id, agentId))
+        .filter((e) => {
+        const t = Date.parse(e.filed_at);
+        return Number.isNaN(t) ? true : t >= cutoff; // keep undated rather than drop
+    })
+        .sort((a, b) => String(b.filed_at).localeCompare(String(a.filed_at)));
+    const by_signature = {};
+    const taskCounts = {};
+    for (const e of matched) {
+        bump(by_signature, failureSignature(e));
+        bump(taskCounts, e.task_id);
+    }
+    const by_task = Object.entries(taskCounts)
+        .sort((a, b) => b[1] - a[1])
+        .map(([task_id, count]) => ({ task_id, count }));
+    const weakest = Object.entries(by_signature).sort((a, b) => b[1] - a[1])[0];
+    const lines = [];
+    if (matched.length === 0) {
+        lines.push(`No failures attributed to "${agentId}" in the last ${sinceDays} day(s).`);
+    }
+    else {
+        lines.push(`📉 IMPROVE-MODE: "${agentId}" — ${matched.length} failure(s) in the last ${sinceDays} day(s).`);
+        lines.push(`Weakest area: ${weakest[0]} (${weakest[1]}). Recurring across:`);
+        for (const t of by_task.slice(0, 8))
+            lines.push(`  • ${t.task_id} ×${t.count}`);
+        const themeList = Object.entries(by_signature)
+            .sort((a, b) => b[1] - a[1])
+            .map(([s, n]) => `${s} (${n})`)
+            .join(', ');
+        lines.push(`Themes: ${themeList}.`);
+    }
+    return {
+        agent_id: agentId,
+        window_days: sinceDays,
+        total: matched.length,
+        by_signature,
+        by_task,
+        weakest_signature: weakest ? weakest[0] : '',
+        entries: matched.slice(0, maxEntries),
+        brief: lines.join('\n'),
+    };
+}
+function topEntries(map, n = 3) {
+    return Object.entries(map)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, n)
+        .map(([k, v]) => `${k} (${v})`)
+        .join(', ');
+}
+/**
+ * Render LESSONS.md content from the aggregate. Pure (no I/O) so it's testable.
+ */
+function renderLessons(summaries, generatedAt) {
+    const promoted = summaries.filter((s) => s.recurring || s.no_converge);
+    const lines = [];
+    lines.push('# Failure Library — LESSONS');
+    lines.push('');
+    lines.push('> Auto-generated by `failure-library.ts` (TICKET-152 Gap 2) from ' +
+        '`data/failure-library/code/`. Do not edit by hand — re-run the promoter.');
+    lines.push(`> Generated: ${generatedAt} · ${summaries.length} task(s) with failures · ${promoted.length} promoted.`);
+    lines.push('');
+    if (promoted.length === 0) {
+        lines.push('_No recurring or non-converging tasks above threshold._');
+        lines.push('');
+        return lines.join('\n');
+    }
+    lines.push('## Chronic tasks (recurring or never converged)');
+    lines.push('');
+    lines.push('| Task | Fails | Max attempt | Converged? | Recurring theme |');
+    lines.push('|------|------:|------------:|:----------:|-----------------|');
+    for (const s of promoted) {
+        const theme = topEntries(s.signatures, 1) || '—';
+        const converged = s.no_converge ? '❌' : '—';
+        lines.push(`| \`${s.task_id}\` | ${s.total_failures} | ${s.max_attempt} | ${converged} | ${theme} |`);
+    }
+    lines.push('');
+    lines.push('## Details');
+    lines.push('');
+    for (const s of promoted) {
+        lines.push(`### \`${s.task_id}\``);
+        lines.push('');
+        lines.push(`- Total failures: **${s.total_failures}** · max attempt: **${s.max_attempt}**`);
+        lines.push(`- Fail types: ${topEntries(s.fail_types)}`);
+        lines.push(`- Themes: ${topEntries(s.signatures)}`);
+        lines.push(`- Models: ${topEntries(s.models)}`);
+        lines.push(`- Sprints: ${s.sprint_ids.join(', ') || 'n/a'}`);
+        lines.push(`- Latest (${s.latest_filed_at}, ${s.latest_score}/100): ${truncate(s.latest_reason, 280)}`);
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+/**
+ * Build the aggregate and write LESSONS.md to the failure-library root.
+ * `generatedAt` is injected (callers pass new Date().toISOString()) so this stays
+ * deterministic and testable.
+ */
+function promoteLessons(generatedAt, opts = {}) {
+    const thresholds = opts.thresholds ?? exports.DEFAULT_THRESHOLDS;
+    const summaries = aggregateCodeFailures(opts.root, thresholds);
+    const content = renderLessons(summaries, generatedAt);
+    const dir = (0, engine_paths_1.resolveEnginePaths)(opts.root).failureLibrary;
+    (0, fs_1.mkdirSync)(dir, { recursive: true });
+    const path = (0, path_1.join)(dir, 'LESSONS.md');
+    (0, fs_1.writeFileSync)(path, content);
+    return {
+        path,
+        promoted: summaries.filter((s) => s.recurring || s.no_converge).length,
+        totalTasks: summaries.length,
+        content,
+    };
+}

package/dist/lib/ksl/error-log.d.ts

@@ -0,0 +1,28 @@
+/**
+ * KSL structured error log — appends typed error entries to
+ * <root>/workspace/ksl/errors/<month>.jsonl. Capture is best-effort and
+ * silent on disk failure so it can never break sprint execution.
+ *
+ * TICKET-215 Phase 3b-3 (Wave B): ERROR_ROOT now resolves via engine-paths
+ * (KOGNAI_ROOT / cwd) instead of process.cwd() directly, so the KSL capture
+ * layer is location-independent and ships in @kognai/orchestrator-core.
+ * resolveEnginePaths().root === the old cwd when KOGNAI_ROOT is unset.
+ */
+export type ErrorKind = 'llm_error' | 'tool_failure' | 'budget_exceeded' | 'guardrail_triggered' | 'timeout' | 'agent_disagreement' | 'compile_error' | 'test_failure' | 'cerberus_block' | 'unknown';
+export interface ErrorContext {
+    sprint_id: string;
+    task_id: string;
+    attempt: number;
+    agent: string;
+    recovered?: boolean;
+    retry_count?: number;
+}
+export interface ErrorLogEntry extends ErrorContext {
+    ts: string;
+    kind: ErrorKind;
+    message: string;
+    stack?: string;
+    recovered: boolean;
+    retry_count: number;
+}
+export declare function record(err: unknown, ctx: ErrorContext, kind?: ErrorKind): void;

package/dist/lib/ksl/error-log.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * KSL structured error log — appends typed error entries to
+ * <root>/workspace/ksl/errors/<month>.jsonl. Capture is best-effort and
+ * silent on disk failure so it can never break sprint execution.
+ *
+ * TICKET-215 Phase 3b-3 (Wave B): ERROR_ROOT now resolves via engine-paths
+ * (KOGNAI_ROOT / cwd) instead of process.cwd() directly, so the KSL capture
+ * layer is location-independent and ships in @kognai/orchestrator-core.
+ * resolveEnginePaths().root === the old cwd when KOGNAI_ROOT is unset.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.record = record;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const engine_paths_1 = require("../engine-paths");
+const ERROR_ROOT = (0, path_1.join)((0, engine_paths_1.resolveEnginePaths)().root, 'workspace/ksl/errors');
+function record(err, ctx, kind = 'unknown') {
+    try {
+        const ts = new Date().toISOString();
+        const month = ts.slice(0, 7);
+        (0, fs_1.mkdirSync)(ERROR_ROOT, { recursive: true });
+        const e = err;
+        const message = (e && e.message) ? String(e.message).slice(0, 1000) : String(err).slice(0, 1000);
+        const stack = (e && e.stack) ? String(e.stack).slice(0, 4000) : undefined;
+        const entry = {
+            ts,
+            sprint_id: ctx.sprint_id,
+            task_id: ctx.task_id,
+            attempt: ctx.attempt,
+            agent: ctx.agent,
+            kind,
+            message,
+            ...(stack ? { stack } : {}),
+            recovered: ctx.recovered ?? false,
+            retry_count: ctx.retry_count ?? 0,
+        };
+        (0, fs_1.appendFileSync)((0, path_1.join)(ERROR_ROOT, `${month}.jsonl`), JSON.stringify(entry) + '\n');
+    }
+    catch {
+        // Silent on disk failure.
+    }
+}

package/dist/lib/ksl/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * KSL (Knowledge/Session Ledger) capture cluster — Phase 3b-3 Wave B.
+ * Structured per-attempt session records + typed error log + the tap that
+ * the orchestrator calls on every agent attempt. Best-effort, kill-switchable
+ * (SPRINT_NO_KSL_CAPTURE=1), never breaks sprint execution.
+ */
+export * from './record-writer';
+export * from './error-log';
+export * from './orchestrator-tap';

package/dist/lib/ksl/index.js

@@ -0,0 +1,25 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * KSL (Knowledge/Session Ledger) capture cluster — Phase 3b-3 Wave B.
+ * Structured per-attempt session records + typed error log + the tap that
+ * the orchestrator calls on every agent attempt. Best-effort, kill-switchable
+ * (SPRINT_NO_KSL_CAPTURE=1), never breaks sprint execution.
+ */
+__exportStar(require("./record-writer"), exports);
+__exportStar(require("./error-log"), exports);
+__exportStar(require("./orchestrator-tap"), exports);

package/dist/lib/ksl/orchestrator-tap.d.ts

@@ -0,0 +1,16 @@
+import { type KSLError, type KSLToolUse } from './record-writer';
+export interface TapInput {
+    sprint_id: string;
+    task_id: string;
+    attempt: number;
+    agent: string;
+    model: string;
+    prompt: string;
+    reply: string;
+    tools_used?: KSLToolUse[];
+    errors?: KSLError[];
+    cost_usd?: number;
+    duration_ms: number;
+    signal_strength?: 'low' | 'medium' | 'high';
+}
+export declare function tapAttempt(input: TapInput): void;

package/dist/lib/ksl/orchestrator-tap.js

@@ -0,0 +1,85 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tapAttempt = tapAttempt;
+const record_writer_1 = require("./record-writer");
+const errorLog = __importStar(require("./error-log"));
+const KILL = () => process.env.SPRINT_NO_KSL_CAPTURE === '1';
+function pickSignal(input) {
+    if (input.signal_strength)
+        return input.signal_strength;
+    // Heuristic: long reply + no errors → high; errors → low; else medium.
+    if ((input.errors?.length ?? 0) > 0)
+        return 'low';
+    if (input.reply && input.reply.length > 4000)
+        return 'high';
+    return 'medium';
+}
+function tapAttempt(input) {
+    if (KILL())
+        return;
+    try {
+        const record = {
+            run_id: (0, record_writer_1.makeRunId)(input.sprint_id, input.task_id, input.attempt),
+            sprint_id: input.sprint_id,
+            task_id: input.task_id,
+            attempt: input.attempt,
+            agent: input.agent,
+            candidate_id: input.model || 'unknown',
+            resolution: null,
+            constitutional_score: 0,
+            pact_score: null,
+            signal_strength: pickSignal(input),
+            prompt: input.prompt || '',
+            reply: input.reply || '',
+            tools_used: input.tools_used || [],
+            errors: input.errors || [],
+            cost_usd: input.cost_usd ?? 0,
+            duration_ms: input.duration_ms,
+            justification: null,
+            judged_at: null,
+            ts: new Date().toISOString(),
+        };
+        (0, record_writer_1.writeRecord)(record);
+        // Mirror errors into the structured error log.
+        for (const e of record.errors) {
+            const kind = e.kind && e.kind.length > 0 ? e.kind : 'unknown';
+            errorLog.record(new Error(e.message), { sprint_id: input.sprint_id, task_id: input.task_id, attempt: input.attempt, agent: input.agent }, kind);
+        }
+    }
+    catch {
+        // Capture must not break sprint execution. Swallow.
+    }
+}

package/dist/lib/ksl/record-writer.d.ts

@@ -0,0 +1,46 @@
+/**
+ * KSL session record writer — persists one JSON record per task attempt to
+ * <root>/workspace/ksl/sessions/<sprint>/<task>.<attempt>.json (atomic,
+ * idempotent by run_id).
+ *
+ * TICKET-215 Phase 3b-3 (Wave B): KSL_ROOT now resolves via engine-paths
+ * (KOGNAI_ROOT / cwd) instead of process.cwd() directly, so KSL capture is
+ * location-independent and ships in @kognai/orchestrator-core.
+ * resolveEnginePaths().root === the old cwd when KOGNAI_ROOT is unset.
+ */
+export type Resolution = 'A' | 'B' | 'C';
+export interface KSLToolUse {
+    skill_id: string;
+    args_hash: string;
+    ok: boolean;
+    ms: number;
+}
+export interface KSLError {
+    kind: string;
+    message: string;
+    stack?: string;
+}
+export interface KSLRecord {
+    run_id: string;
+    sprint_id: string;
+    task_id: string;
+    attempt: number;
+    agent: string;
+    candidate_id: string;
+    resolution: Resolution | null;
+    constitutional_score: number;
+    pact_score: number | null;
+    signal_strength: 'low' | 'medium' | 'high';
+    prompt: string;
+    reply: string;
+    tools_used: KSLToolUse[];
+    errors: KSLError[];
+    cost_usd: number;
+    duration_ms: number;
+    justification: string | null;
+    judged_at: string | null;
+    ts: string;
+}
+export declare function pathForRecord(r: Pick<KSLRecord, 'sprint_id' | 'task_id' | 'attempt'>): string;
+export declare function writeRecord(r: KSLRecord): string;
+export declare function makeRunId(sprintId: string, taskId: string, attempt: number): string;

package/dist/lib/ksl/record-writer.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * KSL session record writer — persists one JSON record per task attempt to
+ * <root>/workspace/ksl/sessions/<sprint>/<task>.<attempt>.json (atomic,
+ * idempotent by run_id).
+ *
+ * TICKET-215 Phase 3b-3 (Wave B): KSL_ROOT now resolves via engine-paths
+ * (KOGNAI_ROOT / cwd) instead of process.cwd() directly, so KSL capture is
+ * location-independent and ships in @kognai/orchestrator-core.
+ * resolveEnginePaths().root === the old cwd when KOGNAI_ROOT is unset.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pathForRecord = pathForRecord;
+exports.writeRecord = writeRecord;
+exports.makeRunId = makeRunId;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const crypto_1 = require("crypto");
+const engine_paths_1 = require("../engine-paths");
+const KSL_ROOT = (0, path_1.join)((0, engine_paths_1.resolveEnginePaths)().root, 'workspace/ksl/sessions');
+function pathForRecord(r) {
+    return (0, path_1.join)(KSL_ROOT, r.sprint_id, `${r.task_id}.${r.attempt}.json`);
+}
+function writeRecord(r) {
+    if (!r.run_id || !r.sprint_id || !r.task_id || typeof r.attempt !== 'number') {
+        throw new Error('writeRecord: missing required fields run_id|sprint_id|task_id|attempt');
+    }
+    const out = pathForRecord(r);
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(out), { recursive: true });
+    if ((0, fs_1.existsSync)(out)) {
+        try {
+            const existing = JSON.parse((0, fs_1.readFileSync)(out, 'utf-8'));
+            if (existing.run_id === r.run_id)
+                return out;
+        }
+        catch { /* corrupt — overwrite */ }
+    }
+    const tmp = `${out}.${(0, crypto_1.randomBytes)(6).toString('hex')}.tmp`;
+    (0, fs_1.writeFileSync)(tmp, JSON.stringify(r, null, 2));
+    (0, fs_1.renameSync)(tmp, out);
+    return out;
+}
+function makeRunId(sprintId, taskId, attempt) {
+    return `${sprintId}:${taskId}:attempt-${attempt}`;
+}