claude-flow 3.19.0 → 3.21.0

package/v3/@claude-flow/cli/dist/src/ruvector/index.d.ts

@@ -18,7 +18,7 @@ export { DiffClassifier, createDiffClassifier, analyzeDiff, analyzeDiffSync, ass
 export { CoverageRouter, createCoverageRouter, coverageRoute, coverageSuggest, coverageGaps, clearCoverageCache, getCoverageCacheStats, type CoverageRouterConfig, type FileCoverage, type CoverageReport, type CoverageRouteResult, type CoverageSuggestResult, type CoverageGapsResult, type CoverageRouteOptions, type CoverageSuggestOptions, type CoverageGapsOptions, } from './coverage-router.js';
 export { coverageRouterTools, hooksCoverageRoute, hooksCoverageSuggest, hooksCoverageGaps } from './coverage-tools.js';
 export { buildDependencyGraph, analyzeGraph, analyzeMinCutBoundaries, analyzeModuleCommunities, detectCircularDependencies, exportToDot, loadRuVector, fallbackMinCut, fallbackLouvain, clearGraphCaches, getGraphCacheStats, type GraphNode, type GraphEdge, type DependencyGraph, type MinCutBoundary, type ModuleCommunity, type CircularDependency, type GraphAnalysisResult, } from './graph-analyzer.js';
-export { LoRAAdapter, getLoRAAdapter, resetLoRAAdapter, createLoRAAdapter, adaptEmbedding, trainLoRA, getLoRAStats, DEFAULT_RANK, DEFAULT_ALPHA, INPUT_DIM as LORA_INPUT_DIM, OUTPUT_DIM as LORA_OUTPUT_DIM, type LoRAConfig, type LoRAWeights, type AdaptationResult, type LoRAStats, } from './lora-adapter.js';
+export { LoRAAdapter, getLoRAAdapter, resetLoRAAdapter, createLoRAAdapter, adaptEmbedding, trainLoRA, getLoRAStats, loadLatestCheckpoint, latestCheckpointInfo, formatCheckpointAge, DEFAULT_RANK, DEFAULT_ALPHA, INPUT_DIM as LORA_INPUT_DIM, OUTPUT_DIM as LORA_OUTPUT_DIM, type LoRAConfig, type LoRAWeights, type AdaptationResult, type LoRAStats, type CheckpointInfo, } from './lora-adapter.js';
 export { ModelRouter, getModelRouter, resetModelRouter, createModelRouter, routeToModel, routeToModelFull, analyzeTaskComplexity, getModelRouterStats, recordModelOutcome, MODEL_CAPABILITIES, COMPLEXITY_INDICATORS, type ClaudeModel, type ModelRouterConfig, type ModelRoutingResult, type ComplexityAnalysis, } from './model-router.js';
 export { SemanticRouter, createSemanticRouter, type Intent, type RouteResult, type RouterConfig, } from './semantic-router.js';
 export { isRuvllmWasmAvailable, initRuvllmWasm, getRuvllmStatus, createHnswRouter, createSonaInstant, createMicroLora, formatChat, createKvCache, createGenerateConfig, createBufferPool, createInferenceArena, HNSW_MAX_SAFE_PATTERNS, type HnswRouterConfig, type HnswPattern, type HnswRouteResult, type SonaConfig, type MicroLoraConfig, type ChatMessage, type GenerateOptions, type RuvllmStatus, } from './ruvllm-wasm.js';

package/v3/@claude-flow/cli/dist/src/ruvector/index.js

@@ -36,7 +36,7 @@ clearGraphCaches, getGraphCacheStats, } from './graph-analyzer.js';
 // consumers (hooks-tools.ts, neural-tools.ts) import from '@claude-flow/neural'
 // explicitly; re-exporting through this barrel pulls the package's
 // transitive @ruvector/sona dep into vitest's eager resolution.
-export { LoRAAdapter, getLoRAAdapter, resetLoRAAdapter, createLoRAAdapter, adaptEmbedding, trainLoRA, getLoRAStats, DEFAULT_RANK, DEFAULT_ALPHA, INPUT_DIM as LORA_INPUT_DIM, OUTPUT_DIM as LORA_OUTPUT_DIM, } from './lora-adapter.js';
+export { LoRAAdapter, getLoRAAdapter, resetLoRAAdapter, createLoRAAdapter, adaptEmbedding, trainLoRA, getLoRAStats, loadLatestCheckpoint, latestCheckpointInfo, formatCheckpointAge, DEFAULT_RANK, DEFAULT_ALPHA, INPUT_DIM as LORA_INPUT_DIM, OUTPUT_DIM as LORA_OUTPUT_DIM, } from './lora-adapter.js';
 export { ModelRouter, getModelRouter, resetModelRouter, createModelRouter, routeToModel, routeToModelFull, analyzeTaskComplexity, getModelRouterStats, recordModelOutcome, MODEL_CAPABILITIES, COMPLEXITY_INDICATORS, } from './model-router.js';
 export { SemanticRouter, createSemanticRouter, } from './semantic-router.js';
 // ── RuVector LLM WASM (inference utilities) ─────────────────

package/v3/@claude-flow/cli/dist/src/ruvector/lora-adapter.d.ts

@@ -213,6 +213,41 @@ export declare class LoRAAdapter {
         scaling: number;
     }): boolean;
 }
+/**
+ * Info about the newest on-disk training checkpoint.
+ */
+export interface CheckpointInfo {
+    /** Absolute path to the checkpoint file */
+    path: string;
+    /** Basename, e.g. lora-checkpoint-1712345678901.json */
+    filename: string;
+    /** Age in ms derived from the filename timestamp (falls back to mtime) */
+    ageMs: number;
+    /** Human-friendly age, e.g. "2h ago" */
+    ageLabel: string;
+}
+/** Compact relative-age label. Most-significant unit only. */
+export declare function formatCheckpointAge(ms: number): string;
+/**
+ * Find the newest `lora-checkpoint-<ts>.json` without loading it. Pure disk
+ * scan — safe to call from read-only status surfaces. Returns null when no
+ * checkpoint exists or the directory is unreadable.
+ */
+export declare function latestCheckpointInfo(): CheckpointInfo | null;
+/**
+ * Flywheel entry point: locate the newest trained checkpoint and load it into
+ * `adapter` via the adapter's existing loadCheckpoint path, so routing /
+ * adaptation benefits from prior `neural train` runs.
+ *
+ * Contract: lazy (call on first adaptation use, never at CLI startup),
+ * non-fatal on any failure, and kill-switchable via
+ * CLAUDE_FLOW_NO_CHECKPOINT_AUTOLOAD=1.
+ */
+export declare function loadLatestCheckpoint(adapter: LoRAAdapter): Promise<{
+    loaded: boolean;
+    path?: string;
+    ageMs?: number;
+}>;
 /**
  * Get or create singleton LoRA adapter instance
  */

package/v3/@claude-flow/cli/dist/src/ruvector/lora-adapter.js

@@ -17,7 +17,7 @@
  *
  * @module lora-adapter
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'fs';
 import { dirname, join } from 'path';
 import { createRequire } from 'module';
 // ============================================================================
@@ -527,6 +527,105 @@ export class LoRAAdapter {
         }
     }
 }
+/**
+ * Directories `neural train` writes checkpoints to. It only ever writes to
+ * `<cwd>/.claude-flow/neural` (see commands/neural.ts + services/native-training.ts),
+ * so that is the single source of truth — kept in a helper so the discovery
+ * and status surfaces stay consistent.
+ */
+function checkpointDirs() {
+    return [join(process.cwd(), '.claude-flow', 'neural')];
+}
+/** Compact relative-age label. Most-significant unit only. */
+export function formatCheckpointAge(ms) {
+    const s = Math.floor(ms / 1000);
+    if (s < 60)
+        return `${s}s ago`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m ago`;
+    const h = Math.floor(m / 60);
+    if (h < 24)
+        return `${h}h ago`;
+    const d = Math.floor(h / 24);
+    return `${d}d ago`;
+}
+/**
+ * Find the newest `lora-checkpoint-<ts>.json` without loading it. Pure disk
+ * scan — safe to call from read-only status surfaces. Returns null when no
+ * checkpoint exists or the directory is unreadable.
+ */
+export function latestCheckpointInfo() {
+    try {
+        let best = null;
+        for (const dir of checkpointDirs()) {
+            if (!existsSync(dir))
+                continue;
+            for (const f of readdirSync(dir)) {
+                const match = /^lora-checkpoint-(\d+)\.json$/.exec(f);
+                if (!match)
+                    continue;
+                const ts = Number(match[1]);
+                if (!Number.isFinite(ts))
+                    continue;
+                if (!best || ts > best.ts)
+                    best = { path: join(dir, f), filename: f, ts };
+            }
+        }
+        if (!best)
+            return null;
+        const ageMs = Math.max(0, Date.now() - best.ts);
+        return { path: best.path, filename: best.filename, ageMs, ageLabel: formatCheckpointAge(ageMs) };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Validate a file looks like a ruvllm training checkpoint before loading it,
+ * so a stray/corrupt JSON in the neural dir can't poison routing weights.
+ * Accepts both the JS-fallback envelope ({A,B,scaling}) and native ruvllm
+ * checkpoint shapes (weights/adapter/epoch/step/loss/version/index markers).
+ */
+function isCheckpointEnvelope(path) {
+    try {
+        const data = JSON.parse(readFileSync(path, 'utf-8'));
+        if (!data || typeof data !== 'object')
+            return false;
+        const obj = data;
+        if (Array.isArray(obj.A) && Array.isArray(obj.B))
+            return true;
+        return ['weights', 'adapter', 'epoch', 'step', 'loss', 'version', 'index'].some((k) => k in obj);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Flywheel entry point: locate the newest trained checkpoint and load it into
+ * `adapter` via the adapter's existing loadCheckpoint path, so routing /
+ * adaptation benefits from prior `neural train` runs.
+ *
+ * Contract: lazy (call on first adaptation use, never at CLI startup),
+ * non-fatal on any failure, and kill-switchable via
+ * CLAUDE_FLOW_NO_CHECKPOINT_AUTOLOAD=1.
+ */
+export async function loadLatestCheckpoint(adapter) {
+    if (process.env.CLAUDE_FLOW_NO_CHECKPOINT_AUTOLOAD === '1')
+        return { loaded: false };
+    try {
+        const info = latestCheckpointInfo();
+        if (!info)
+            return { loaded: false };
+        if (!isCheckpointEnvelope(info.path))
+            return { loaded: false, path: info.path, ageMs: info.ageMs };
+        const loaded = await adapter.loadCheckpoint(info.path);
+        return { loaded, path: info.path, ageMs: info.ageMs };
+    }
+    catch {
+        return { loaded: false };
+    }
+}
 // ============================================================================
 // Singleton & Factory Functions
 // ============================================================================
@@ -545,6 +644,14 @@ export async function getLoRAAdapter() {
     initPromise = (async () => {
         const adapter = new LoRAAdapter();
         await adapter.initialize();
+        // Flywheel: fold in the newest trained checkpoint so routing/adaptation
+        // benefits from prior `neural train` runs. This singleton is constructed
+        // lazily on first adaptation use (NOT at CLI startup), so the checkpoint
+        // scan + ruvllm load stay off the hot `--help` path. Non-fatal.
+        try {
+            await loadLatestCheckpoint(adapter);
+        }
+        catch { /* auto-load is best-effort — never block adaptation */ }
         loraInstance = adapter;
         return adapter;
     })();

package/v3/@claude-flow/cli/dist/src/ruvector/router-trajectory.d.ts

@@ -13,6 +13,19 @@
  * Schema is versioned (`"v": 1`). New required fields bump the version;
  * additive optional fields do not.
  *
+ * COMPANION: run-transcript-recorder.ts (weight-eft capture path)
+ * --------------------------------------------------------------
+ * This recorder captures the routing DECISION only (task, embedding, scalar
+ * quality, tokens, cost) — enough to retrain the router. It deliberately does
+ * NOT carry the full message transcript, the produced patch, or a resolved
+ * boolean. `@metaharness/weight-eft` needs those to build SFT/DPO training
+ * rows, so a SEPARATE opt-in recorder — `run-transcript-recorder.ts` — captures
+ * the full run transcript to `.swarm/run-transcripts.jsonl`. Both share the
+ * `taskHash()` below as their join key, and both are off-by-default for the
+ * same PII/retention reason. Use `unifiedRecorderStatus()` (bottom of this
+ * file) to inspect both at once. Keeping them as two files keeps the routing
+ * hot path free of the heavier transcript payload.
+ *
  * @module router-trajectory
  */
 import type { ClaudeModel } from './model-router.js';
@@ -158,4 +171,24 @@ export declare function pairTrajectoryRows(rows: TrajectoryRow[]): {
 };
 /** Test seam — reset cached config so unit tests can change env vars between cases. */
 export declare function __resetTrajectoryRecorderForTests(): void;
+/**
+ * Unified status for BOTH the routing-decision recorder (this module) and the
+ * companion run-transcript recorder (the weight-eft capture path). The
+ * run-transcript recorder is loaded dynamically so this module has no static
+ * dependency on it (the reverse edge — run-transcript-recorder → taskHash —
+ * is the only static link, keeping the import acyclic).
+ */
+export declare function unifiedRecorderStatus(): Promise<{
+    routerTrajectory: {
+        enabled: boolean;
+        path: string;
+        taskCharLimit: number;
+    };
+    runTranscripts: {
+        enabled: boolean;
+        path: string;
+    } | {
+        unavailable: true;
+    };
+}>;
 //# sourceMappingURL=router-trajectory.d.ts.map

package/v3/@claude-flow/cli/dist/src/ruvector/router-trajectory.js

@@ -13,6 +13,19 @@
  * Schema is versioned (`"v": 1`). New required fields bump the version;
  * additive optional fields do not.
  *
+ * COMPANION: run-transcript-recorder.ts (weight-eft capture path)
+ * --------------------------------------------------------------
+ * This recorder captures the routing DECISION only (task, embedding, scalar
+ * quality, tokens, cost) — enough to retrain the router. It deliberately does
+ * NOT carry the full message transcript, the produced patch, or a resolved
+ * boolean. `@metaharness/weight-eft` needs those to build SFT/DPO training
+ * rows, so a SEPARATE opt-in recorder — `run-transcript-recorder.ts` — captures
+ * the full run transcript to `.swarm/run-transcripts.jsonl`. Both share the
+ * `taskHash()` below as their join key, and both are off-by-default for the
+ * same PII/retention reason. Use `unifiedRecorderStatus()` (bottom of this
+ * file) to inspect both at once. Keeping them as two files keeps the routing
+ * hot path free of the heavier transcript payload.
+ *
  * @module router-trajectory
  */
 import { appendFileSync, mkdirSync, existsSync, statSync, renameSync, unlinkSync } from 'node:fs';
@@ -247,4 +260,22 @@ export function __resetTrajectoryRecorderForTests() {
     _cfg = null;
     _cachedSize = -1;
 }
+/**
+ * Unified status for BOTH the routing-decision recorder (this module) and the
+ * companion run-transcript recorder (the weight-eft capture path). The
+ * run-transcript recorder is loaded dynamically so this module has no static
+ * dependency on it (the reverse edge — run-transcript-recorder → taskHash —
+ * is the only static link, keeping the import acyclic).
+ */
+export async function unifiedRecorderStatus() {
+    const routerTrajectory = trajectoryRecorderStatus();
+    try {
+        const mod = await import('./run-transcript-recorder.js');
+        const s = mod.runTranscriptRecorderStatus();
+        return { routerTrajectory, runTranscripts: { enabled: s.enabled, path: s.path } };
+    }
+    catch {
+        return { routerTrajectory, runTranscripts: { unavailable: true } };
+    }
+}
 //# sourceMappingURL=router-trajectory.js.map

package/v3/@claude-flow/cli/dist/src/ruvector/run-transcript-recorder.d.ts

@@ -0,0 +1,154 @@
+/**
+ * run-transcript-recorder.ts — Opt-in FULL run-transcript recorder for the
+ * weight-eft training-data export path (agenticow / ADR-150 weight-eft slice).
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * The existing `router-trajectory.ts` recorder captures only the ROUTING
+ * DECISION for a task: task text, embedding, scalar quality, tokens, cost.
+ * `@metaharness/weight-eft` needs something the routing recorder never had —
+ * the full ReAct message TRANSCRIPT, the produced patch, and a resolved
+ * boolean — to build SFT/DPO training rows. This module is that missing
+ * capture surface. It writes one JSON-line per completed run to
+ * `.swarm/run-transcripts.jsonl`, in a shape the archive-builder in
+ * `services/weight-eft.ts` maps directly to `DarwinTrajectory[]`.
+ *
+ * OFF BY DEFAULT (PII / RETENTION SURFACE)
+ * ----------------------------------------
+ * Rows carry the FULL prompt + assistant transcript + patch — a much larger
+ * PII/retention surface than the routing recorder. Mirroring why
+ * router-trajectory.ts is off-by-default, every write goes through the
+ * `CLAUDE_FLOW_RUN_TRANSCRIPTS=1` env gate. When unset (the default),
+ * `recordRunTranscript()` is a no-op. There is no way to enable it implicitly.
+ *
+ * HONESTY: `resolved` IS A PROXY
+ * ------------------------------
+ * `DarwinTrajectory.resolved` is meant to be GOLD-resolved status from the
+ * official SWE-bench harness. Ruflo has NO SWE-bench oracle. Every record
+ * therefore stamps `resolved_source` describing where the boolean actually
+ * came from, so no downstream consumer can mistake a proxy for gold:
+ *   - 'gold-oracle'      — a real conformant gold eval supplied it (never
+ *                          ruflo today; reserved for an external caller)
+ *   - 'output-verifier'  — ruflo's structural output-verifier confidence,
+ *                          thresholded — an EXPLICIT proxy
+ *   - 'api-success'      — the model returned without an API error — the
+ *                          weakest proxy (says nothing about correctness)
+ *   - 'external'         — supplied verbatim by the caller, provenance unknown
+ *
+ * ARCHITECTURAL CONSTRAINTS (mirror router-trajectory.ts / ADR-150)
+ * -----------------------------------------------------------------
+ * 1. OPT-IN — gated behind CLAUDE_FLOW_RUN_TRANSCRIPTS=1; default off.
+ * 2. NEVER THROWS — every fs op is try/caught at the append boundary; a
+ *    failed write is silent (DEBUG-logged) and never breaks the run.
+ * 3. NO metaharness COUPLING — this module imports nothing from
+ *    `@metaharness/*`; it only defines a portable record shape. The
+ *    services/weight-eft.ts archive-builder does the (optional) mapping.
+ *
+ * SCHEMA (versioned, additive) — one JSONL row per completed run:
+ *   { v, ts, instance_id, task_hash, model, tier, resolved, resolved_source,
+ *     messages[], model_patch, sample?, source?, tokens?, cost_usd? }
+ *
+ * @module run-transcript-recorder
+ */
+/** An OpenAI-style tool call (the ReAct action). Mirrors weight-eft's ToolCall. */
+export interface ToolCallLite {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/** A chat message in an OpenAI-compatible transcript. Mirrors weight-eft's ChatMessage. */
+export interface ChatMessageLite {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string | null;
+    tool_calls?: ToolCallLite[];
+    tool_call_id?: string;
+    name?: string;
+}
+/** Where a `resolved` boolean actually came from (never silently "gold"). */
+export type ResolvedSource = 'gold-oracle' | 'output-verifier' | 'api-success' | 'external';
+/** Ruflo's cascade tier. haiku → 'cheap' (first tier), sonnet/opus → 'frontier'. */
+export type RunTier = 'cheap' | 'frontier';
+/** One persisted run transcript. Maps 1:1 to a DarwinTrajectory (+ provenance). */
+export interface RunTranscriptRecord {
+    v: 1;
+    ts: string;
+    instance_id: string;
+    task_hash: string;
+    model: string;
+    tier: RunTier;
+    resolved: boolean;
+    resolved_source: ResolvedSource;
+    messages: ChatMessageLite[];
+    model_patch: string;
+    sample?: number;
+    source?: string;
+    tokens?: {
+        input: number;
+        output: number;
+    };
+    cost_usd?: number;
+}
+/**
+ * Record one completed run transcript. Cheap — a single appendFileSync of a
+ * JSONL row. No-op when CLAUDE_FLOW_RUN_TRANSCRIPTS is unset (the default).
+ * Never throws.
+ *
+ * `resolvedSource` is REQUIRED so a proxy can never masquerade as gold. If you
+ * only have "the API returned", pass 'api-success' — the honest weakest label.
+ */
+export declare function recordRunTranscript(args: {
+    /** Task/issue text — used for the FNV hash + default instance id. */
+    task: string;
+    /** Concrete model id that produced the run (e.g. "claude-haiku-4"). */
+    model: string;
+    /** Ruflo cascade tier of `model`. */
+    tier: RunTier;
+    /** The resolved boolean (see resolvedSource for what it actually means). */
+    resolved: boolean;
+    /** Provenance of `resolved`. Never omit — honesty is the point. */
+    resolvedSource: ResolvedSource;
+    /** OpenAI-shaped message transcript (system/user/assistant/tool). */
+    messages: ChatMessageLite[];
+    /** Unified diff the run produced. '' when the path produces no patch. */
+    modelPatch?: string;
+    /** Override the default "run-<hash>" instance id (contamination key). */
+    instanceId?: string;
+    /** Best-of-N sample index on the same instance (default 0). */
+    sample?: number;
+    /** Provenance tag, e.g. "agent-execute", "autopilot". */
+    source?: string;
+    tokens?: {
+        input: number;
+        output: number;
+    };
+    costUsd?: number;
+}): {
+    recorded: boolean;
+    instanceId: string;
+    taskHash: string;
+};
+/**
+ * Read + parse the run-transcript JSONL back into records. Used by the
+ * archive-builder (`services/weight-eft.ts`). Malformed lines are skipped and
+ * counted, never thrown. Returns `[]` if the file is absent.
+ */
+export declare function readRunTranscripts(path?: string): {
+    records: RunTranscriptRecord[];
+    malformed: number;
+    path: string;
+};
+/** Map a ruflo model tier label to the weight-eft policy tier. */
+export declare function tierForModel(model: string | undefined): RunTier;
+/** Diagnostic for status/CLI. */
+export declare function runTranscriptRecorderStatus(): {
+    enabled: boolean;
+    path: string;
+    maxSizeBytes: number;
+    maxRotations: number;
+};
+/** @internal — test seam: reset cached config so tests can flip env vars. */
+export declare function __resetRunTranscriptRecorderForTests(): void;
+//# sourceMappingURL=run-transcript-recorder.d.ts.map

package/v3/@claude-flow/cli/dist/src/ruvector/run-transcript-recorder.js

@@ -0,0 +1,209 @@
+/**
+ * run-transcript-recorder.ts — Opt-in FULL run-transcript recorder for the
+ * weight-eft training-data export path (agenticow / ADR-150 weight-eft slice).
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * The existing `router-trajectory.ts` recorder captures only the ROUTING
+ * DECISION for a task: task text, embedding, scalar quality, tokens, cost.
+ * `@metaharness/weight-eft` needs something the routing recorder never had —
+ * the full ReAct message TRANSCRIPT, the produced patch, and a resolved
+ * boolean — to build SFT/DPO training rows. This module is that missing
+ * capture surface. It writes one JSON-line per completed run to
+ * `.swarm/run-transcripts.jsonl`, in a shape the archive-builder in
+ * `services/weight-eft.ts` maps directly to `DarwinTrajectory[]`.
+ *
+ * OFF BY DEFAULT (PII / RETENTION SURFACE)
+ * ----------------------------------------
+ * Rows carry the FULL prompt + assistant transcript + patch — a much larger
+ * PII/retention surface than the routing recorder. Mirroring why
+ * router-trajectory.ts is off-by-default, every write goes through the
+ * `CLAUDE_FLOW_RUN_TRANSCRIPTS=1` env gate. When unset (the default),
+ * `recordRunTranscript()` is a no-op. There is no way to enable it implicitly.
+ *
+ * HONESTY: `resolved` IS A PROXY
+ * ------------------------------
+ * `DarwinTrajectory.resolved` is meant to be GOLD-resolved status from the
+ * official SWE-bench harness. Ruflo has NO SWE-bench oracle. Every record
+ * therefore stamps `resolved_source` describing where the boolean actually
+ * came from, so no downstream consumer can mistake a proxy for gold:
+ *   - 'gold-oracle'      — a real conformant gold eval supplied it (never
+ *                          ruflo today; reserved for an external caller)
+ *   - 'output-verifier'  — ruflo's structural output-verifier confidence,
+ *                          thresholded — an EXPLICIT proxy
+ *   - 'api-success'      — the model returned without an API error — the
+ *                          weakest proxy (says nothing about correctness)
+ *   - 'external'         — supplied verbatim by the caller, provenance unknown
+ *
+ * ARCHITECTURAL CONSTRAINTS (mirror router-trajectory.ts / ADR-150)
+ * -----------------------------------------------------------------
+ * 1. OPT-IN — gated behind CLAUDE_FLOW_RUN_TRANSCRIPTS=1; default off.
+ * 2. NEVER THROWS — every fs op is try/caught at the append boundary; a
+ *    failed write is silent (DEBUG-logged) and never breaks the run.
+ * 3. NO metaharness COUPLING — this module imports nothing from
+ *    `@metaharness/*`; it only defines a portable record shape. The
+ *    services/weight-eft.ts archive-builder does the (optional) mapping.
+ *
+ * SCHEMA (versioned, additive) — one JSONL row per completed run:
+ *   { v, ts, instance_id, task_hash, model, tier, resolved, resolved_source,
+ *     messages[], model_patch, sample?, source?, tokens?, cost_usd? }
+ *
+ * @module run-transcript-recorder
+ */
+import { appendFileSync, mkdirSync, existsSync, statSync, renameSync, unlinkSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve as resolvePath } from 'node:path';
+import { taskHash } from './router-trajectory.js';
+let _cfg = null;
+let _cachedSize = -1;
+function getConfig() {
+    if (_cfg !== null)
+        return _cfg;
+    const swarmDir = process.env.CLAUDE_FLOW_SWARM_DIR ?? resolvePath(process.cwd(), '.swarm');
+    _cfg = {
+        enabled: process.env.CLAUDE_FLOW_RUN_TRANSCRIPTS === '1',
+        path: process.env.CLAUDE_FLOW_RUN_TRANSCRIPTS_PATH ?? join(swarmDir, 'run-transcripts.jsonl'),
+        maxSizeBytes: parseInt(process.env.CLAUDE_FLOW_RUN_TRANSCRIPTS_MAXSIZE ?? `${25 * 1024 * 1024}`, 10) | 0,
+        maxRotations: Math.max(0, parseInt(process.env.CLAUDE_FLOW_RUN_TRANSCRIPTS_MAXROTATIONS ?? '3', 10) || 3),
+    };
+    return _cfg;
+}
+function rotate(cfg) {
+    if (!existsSync(cfg.path))
+        return;
+    try {
+        if (cfg.maxRotations === 0) {
+            unlinkSync(cfg.path);
+            return;
+        }
+        const oldest = `${cfg.path}.${cfg.maxRotations}`;
+        if (existsSync(oldest))
+            unlinkSync(oldest);
+        for (let i = cfg.maxRotations - 1; i >= 1; i--) {
+            const src = `${cfg.path}.${i}`;
+            if (existsSync(src))
+                renameSync(src, `${cfg.path}.${i + 1}`);
+        }
+        renameSync(cfg.path, `${cfg.path}.1`);
+    }
+    catch {
+        try {
+            unlinkSync(cfg.path);
+        }
+        catch { /* */ }
+    }
+    _cachedSize = 0;
+}
+function appendRow(row) {
+    const cfg = getConfig();
+    if (!cfg.enabled)
+        return;
+    try {
+        const dir = dirname(cfg.path);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        if (_cachedSize < 0) {
+            _cachedSize = existsSync(cfg.path) ? statSync(cfg.path).size : 0;
+        }
+        const line = JSON.stringify(row) + '\n';
+        const bytes = Buffer.byteLength(line, 'utf8');
+        if (cfg.maxSizeBytes > 0 && _cachedSize + bytes > cfg.maxSizeBytes)
+            rotate(cfg);
+        appendFileSync(cfg.path, line);
+        _cachedSize += bytes;
+    }
+    catch (e) {
+        if (process.env.DEBUG) {
+            // eslint-disable-next-line no-console
+            console.error('run-transcript: appendRow failed:', e.message);
+        }
+        // Never throw — transcript collection must never break a run.
+    }
+}
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Record one completed run transcript. Cheap — a single appendFileSync of a
+ * JSONL row. No-op when CLAUDE_FLOW_RUN_TRANSCRIPTS is unset (the default).
+ * Never throws.
+ *
+ * `resolvedSource` is REQUIRED so a proxy can never masquerade as gold. If you
+ * only have "the API returned", pass 'api-success' — the honest weakest label.
+ */
+export function recordRunTranscript(args) {
+    const cfg = getConfig();
+    const hash = taskHash(args.task);
+    const instanceId = args.instanceId ?? `run-${hash}`;
+    if (!cfg.enabled)
+        return { recorded: false, instanceId, taskHash: hash };
+    const row = {
+        v: 1,
+        ts: new Date().toISOString(),
+        instance_id: instanceId,
+        task_hash: hash,
+        model: args.model,
+        tier: args.tier,
+        resolved: args.resolved,
+        resolved_source: args.resolvedSource,
+        messages: args.messages,
+        model_patch: args.modelPatch ?? '',
+        ...(args.sample !== undefined ? { sample: args.sample } : {}),
+        ...(args.source ? { source: args.source } : {}),
+        ...(args.tokens ? { tokens: args.tokens } : {}),
+        ...(args.costUsd != null ? { cost_usd: args.costUsd } : {}),
+    };
+    appendRow(row);
+    return { recorded: true, instanceId, taskHash: hash };
+}
+/**
+ * Read + parse the run-transcript JSONL back into records. Used by the
+ * archive-builder (`services/weight-eft.ts`). Malformed lines are skipped and
+ * counted, never thrown. Returns `[]` if the file is absent.
+ */
+export function readRunTranscripts(path) {
+    const p = path ?? getConfig().path;
+    if (!existsSync(p))
+        return { records: [], malformed: 0, path: p };
+    const records = [];
+    let malformed = 0;
+    try {
+        for (const line of readFileSync(p, 'utf8').split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                const r = JSON.parse(line);
+                if (r && typeof r === 'object' && r.v === 1 && r.instance_id && Array.isArray(r.messages)) {
+                    records.push(r);
+                }
+                else {
+                    malformed++;
+                }
+            }
+            catch {
+                malformed++;
+            }
+        }
+    }
+    catch {
+        // unreadable file — treat as empty, never throw
+    }
+    return { records, malformed, path: p };
+}
+/** Map a ruflo model tier label to the weight-eft policy tier. */
+export function tierForModel(model) {
+    // haiku (and any explicitly-cheap label) → 'cheap' (cascade first tier).
+    // sonnet / opus / everything else → 'frontier' (the escalation tier).
+    if (!model)
+        return 'frontier';
+    return /haiku/i.test(model) ? 'cheap' : 'frontier';
+}
+/** Diagnostic for status/CLI. */
+export function runTranscriptRecorderStatus() {
+    return { ...getConfig() };
+}
+/** @internal — test seam: reset cached config so tests can flip env vars. */
+export function __resetRunTranscriptRecorderForTests() {
+    _cfg = null;
+    _cachedSize = -1;
+}
+//# sourceMappingURL=run-transcript-recorder.js.map