@claude-flow/cli 3.32.3 → 3.32.4

package/dist/src/ruvector/router-trajectory.js

@@ -0,0 +1,281 @@
+/**
+ * router-trajectory.ts — Opt-in DRACO-shaped trajectory recorder for the
+ * cost-optimal model router (ADR-148, phase 5).
+ *
+ * Writes one JSON-line per routing decision and one per outcome to a
+ * shared `.swarm/model-router-trajectories.jsonl`. Outcome rows are
+ * matched to their decision via `task_hash` (FNV-1a-32 of the task text).
+ *
+ * Gated behind `CLAUDE_FLOW_ROUTER_TRAJECTORY=1`. Default: **off** — rows
+ * carry full task text + raw embeddings, which is a PII/retention surface
+ * we do not enable without explicit consent.
+ *
+ * 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';
+import { dirname, join, resolve as resolvePath } from 'node:path';
+import { costUsd } from './model-prices.js';
+// ============================================================================
+// FNV-1a-32 (matches scripts/gen-seed-corpus.mjs)
+// ============================================================================
+export function taskHash(task) {
+    let h = 0x811c9dc5 >>> 0;
+    for (let i = 0; i < task.length; i++) {
+        h ^= task.charCodeAt(i);
+        h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+    }
+    return h.toString(16).padStart(8, '0');
+}
+let _cfg = null;
+/** Cached size of the current file; updated incrementally on each append to
+ *  avoid a `statSync` per write. -1 means "unknown, probe on next append". */
+let _cachedSize = -1;
+function getConfig() {
+    if (_cfg !== null)
+        return _cfg;
+    const enabled = process.env.CLAUDE_FLOW_ROUTER_TRAJECTORY === '1';
+    const swarmDir = process.env.CLAUDE_FLOW_SWARM_DIR
+        ?? resolvePath(process.cwd(), '.swarm');
+    _cfg = {
+        enabled,
+        path: process.env.CLAUDE_FLOW_ROUTER_TRAJECTORY_PATH
+            ?? join(swarmDir, 'model-router-trajectories.jsonl'),
+        taskCharLimit: parseInt(process.env.CLAUDE_FLOW_ROUTER_TRAJECTORY_TASKLEN ?? '500', 10) || 500,
+        maxSizeBytes: parseInt(process.env.CLAUDE_FLOW_ROUTER_TRAJECTORY_MAXSIZE ?? `${10 * 1024 * 1024}`, 10) | 0,
+        maxRotations: Math.max(0, parseInt(process.env.CLAUDE_FLOW_ROUTER_TRAJECTORY_MAXROTATIONS ?? '3', 10) || 3),
+    };
+    return _cfg;
+}
+/** Rotate `path` → `path.1`, `path.1` → `path.2`, ..., dropping the oldest. */
+function rotate(cfg) {
+    if (!existsSync(cfg.path))
+        return;
+    try {
+        // Walk from oldest to newest so each rename has a free target.
+        if (cfg.maxRotations === 0) {
+            // No history kept — just truncate by deleting.
+            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 {
+        // If rotation fails (permissions, race), drop back to overwriting the
+        // active file by truncating its handle. Worst case we lose history.
+        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 });
+        // Probe size lazily on first call this process, then track incrementally.
+        if (_cachedSize < 0) {
+            _cachedSize = existsSync(cfg.path) ? statSync(cfg.path).size : 0;
+        }
+        // One JSON object per line, newline-terminated. No leading whitespace —
+        // we want the file to be `jq -c`-friendly.
+        const line = JSON.stringify(row) + '\n';
+        const bytes = Buffer.byteLength(line, 'utf8');
+        // Rotate BEFORE writing if this row would push us past the cap.
+        if (cfg.maxSizeBytes > 0 && _cachedSize + bytes > cfg.maxSizeBytes) {
+            rotate(cfg);
+        }
+        appendFileSync(cfg.path, line);
+        _cachedSize += bytes;
+    }
+    catch {
+        // Silent: trajectory collection must never break routing.
+    }
+}
+// ============================================================================
+// Public API
+// ============================================================================
+/** Record one decision. Cheap — a single appendFileSync of a JSONL row. */
+export function recordDecision(args) {
+    const cfg = getConfig();
+    if (!cfg.enabled)
+        return;
+    const row = {
+        v: 1, type: 'decision',
+        ts: new Date().toISOString(),
+        task_hash: taskHash(args.task),
+        task: args.task.length > cfg.taskCharLimit ? args.task.slice(0, cfg.taskCharLimit) : args.task,
+        embedding: args.embedding,
+        complexity: args.complexity,
+        model: args.model,
+        confidence: args.confidence,
+        uncertainty: args.uncertainty,
+        routed_by: args.routedBy,
+        ...(args.neuralBackend ? { neural_backend: args.neuralBackend } : {}),
+        ...(args.abPair ? { ab_pair: args.abPair } : {}),
+        ...(args.provider ? { provider: args.provider } : {}),
+        ...(args.openrouterModel ? { openrouter_model: args.openrouterModel } : {}),
+        ...(args.ensembleDisagreement !== undefined ? { ensemble_disagreement: args.ensembleDisagreement } : {}),
+    };
+    appendRow(row);
+}
+/** Record one outcome. Join to a decision by `task_hash`. */
+export function recordTrajectoryOutcome(args) {
+    const cfg = getConfig();
+    if (!cfg.enabled)
+        return;
+    // iter 31 — compute USD spend at write time using the canonical price
+    // table. Cost is a first-class field so consumers don't need to JOIN
+    // against the decision row (which may live in a rotated file).
+    const cost_usd = args.tokens && (args.tokens.input > 0 || args.tokens.output > 0)
+        ? costUsd(args.modelId, args.tokens.input, args.tokens.output)
+        : undefined;
+    const row = {
+        v: 1, type: 'outcome',
+        ts: new Date().toISOString(),
+        task_hash: taskHash(args.task),
+        quality: args.quality,
+        scores: args.scores,
+        source: args.source,
+        ...(args.tokens ? { tokens: args.tokens } : {}),
+        ...(cost_usd != null ? { cost_usd } : {}),
+        ...(args.modelId ? { model_id: args.modelId } : {}),
+    };
+    appendRow(row);
+}
+/** Diagnostic for status/CLI. */
+export function trajectoryRecorderStatus() {
+    return { ...getConfig() };
+}
+/** Map decision-side complexity ∈ [0,1] back to the corpus tier label. The
+ *  buckets are deliberately the same boundaries the bandit uses so a pair
+ *  drawn from production lands in the same KRR specialist that served it. */
+export function tierFromComplexity(complexity) {
+    if (complexity < 0.34)
+        return 'cheap';
+    if (complexity < 0.67)
+        return 'mid';
+    return 'strong';
+}
+/** Pair decision+outcome rows by task_hash. Returns the rebuilt training rows
+ *  + diagnostics so the caller (script or test) can report what was dropped
+ *  and why. */
+export function pairTrajectoryRows(rows) {
+    const decisions = new Map();
+    const outcomes = new Map();
+    // Latest-wins per hash. Production may re-run the same task — using the most
+    // recent outcome avoids polluting the corpus with stale judgments.
+    let dCount = 0, oCount = 0;
+    for (const row of rows) {
+        if (row.type === 'decision') {
+            dCount++;
+            const prev = decisions.get(row.task_hash);
+            if (!prev || row.ts > prev.ts)
+                decisions.set(row.task_hash, row);
+        }
+        else if (row.type === 'outcome') {
+            oCount++;
+            const prev = outcomes.get(row.task_hash);
+            if (!prev || row.ts > prev.ts)
+                outcomes.set(row.task_hash, row);
+        }
+    }
+    const pairs = [];
+    const bySource = {};
+    const byTier = {};
+    let droppedNoEmbedding = 0;
+    let droppedNoMatch = 0;
+    for (const [hash, dec] of decisions) {
+        const out = outcomes.get(hash);
+        if (!out) {
+            droppedNoMatch++;
+            continue;
+        }
+        if (!dec.embedding || dec.embedding.length === 0) {
+            droppedNoEmbedding++;
+            continue;
+        }
+        // scores map: prefer the outcome's full per-model map (set by callers who
+        // ran multi-model comparisons); fall back to a single-model entry derived
+        // from the model the decision actually dispatched.
+        const scores = out.scores
+            ?? { [dec.openrouter_model ?? dec.model]: out.quality };
+        const tier = tierFromComplexity(dec.complexity);
+        const source = out.source ?? 'unknown';
+        pairs.push({
+            task: dec.task,
+            embedding: dec.embedding,
+            scores,
+            tier,
+            source,
+            ts: out.ts,
+        });
+        bySource[source] = (bySource[source] ?? 0) + 1;
+        byTier[tier] = (byTier[tier] ?? 0) + 1;
+    }
+    return {
+        pairs,
+        stats: {
+            totalRows: rows.length,
+            decisions: dCount,
+            outcomes: oCount,
+            paired: pairs.length,
+            droppedNoEmbedding,
+            droppedNoMatch,
+            bySource,
+            byTier,
+        },
+    };
+}
+/** Test seam — reset cached config so unit tests can change env vars between cases. */
+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/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/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