claude-flow 3.20.0 → 3.21.1

package/v3/@claude-flow/cli/dist/src/memory/memory-bridge.js

@@ -680,6 +680,31 @@ export async function bridgeStoreEntry(options) {
         catch { /* vector_indexes may not exist on legacy DBs — fall through */ }
         const stmt = ctx.db.prepare(insertSql);
         stmt.run(id, key, namespace, value, embeddingJson, dimensions || null, model, tags.length > 0 ? JSON.stringify(tags) : null, '{}', now, now, ttl ? now + (ttl * 1000) : null);
+        // #2558: keep `vector_indexes.total_vectors` accurate so status/tooling
+        // stop reporting "HNSW index: 0 vectors" while embedded entries exist.
+        try {
+            ctx.db
+                .prepare(`UPDATE vector_indexes SET
+             total_vectors = (SELECT COUNT(*) FROM memory_entries
+                              WHERE namespace = ? AND embedding IS NOT NULL),
+             updated_at = ?
+           WHERE name = ?`)
+                .run(namespace, now, namespace);
+        }
+        catch { /* vector_indexes may not exist on legacy DBs — non-fatal */ }
+        // #2558: better-sqlite3 opens the DB in WAL mode and, for the small write
+        // volumes typical of CLI usage, may never reach the auto-checkpoint
+        // threshold — leaving committed rows only in the -wal file. WAL-blind
+        // readers (the sql.js fallback search path; the statusline's read-only
+        // `sqlite3` vector count) then see a stale/empty main DB file and report
+        // "0 vectors" / empty search. A PASSIVE checkpoint flushes committed pages
+        // into the main file without blocking writers. Best-effort, never fatal.
+        try {
+            if (typeof ctx.db.pragma === 'function') {
+                ctx.db.pragma('wal_checkpoint(PASSIVE)');
+            }
+        }
+        catch { /* non-WAL, busy, or unsupported — non-fatal */ }
         // Phase 2: Write-through to TieredCache
         const safeNs = String(namespace).replace(/:/g, '_');
         const safeKey = String(key).replace(/:/g, '_');
@@ -770,17 +795,33 @@ export async function bridgeSearchEntries(options) {
                 // Normalize BM25 to 0-1 range (cap at 10 for normalization)
                 bm25ScoreVal = Math.min(bm25ScoreVal / 10, 1.0);
             }
-            // Reciprocal rank fusion: combine semantic and BM25
-            // Weight: 0.7 semantic + 0.3 BM25 when both embeddings present
-            // Fall back to BM25-only when either query or row lacks an embedding
-            const score = semanticScore > 0
-                ? (0.7 * semanticScore + 0.3 * bm25ScoreVal)
-                : bm25ScoreVal;
+            // #2558: keyword-coverage floor for the lexical signal.
+            // BM25's IDF collapses toward zero when a term appears in most/all
+            // documents (routine on small memory corpora), and the /10 normalization
+            // crushed exact-keyword hits well below the default 0.3 threshold — so
+            // `memory search` recalled NOTHING even when the content literally
+            // contained the query term (issue #2558: "keyword recall random"). The
+            // pre-BM25 fallback guaranteed keyword recall via matchCount/words*0.5;
+            // this restores that guarantee. `coverage` is the fraction of query
+            // terms present in the document — a full-coverage hit must always be
+            // recallable regardless of IDF.
+            const contentLower = String(row.content || '').toLowerCase();
+            const matchedTerms = queryTerms.filter(t => contentLower.includes(t)).length;
+            const coverage = queryTerms.length > 0 ? matchedTerms / queryTerms.length : 0;
+            const lexicalScore = Math.max(bm25ScoreVal, coverage);
+            // Recall-friendly fusion: a strong semantic OR lexical signal alone must
+            // clear the threshold. `blended` (0.6 semantic + 0.4 lexical) drives
+            // ranking; taking max() with the raw semantic score means (a) a genuinely
+            // similar entry is never dropped just because it lacks the query's exact
+            // words, and (b) a full-coverage keyword hit (lexical=1 → blended≥0.4) is
+            // never dropped just because its embedding cosine is low or negative.
+            const blended = 0.6 * Math.max(0, semanticScore) + 0.4 * lexicalScore;
+            const score = Math.max(blended, semanticScore);
             if (score >= threshold) {
                 // Phase 4: ExplainableRecall provenance
                 const provenance = queryEmbedding
-                    ? `semantic:${semanticScore.toFixed(3)}+bm25:${bm25ScoreVal.toFixed(3)}`
-                    : `bm25:${bm25ScoreVal.toFixed(3)}`;
+                    ? `semantic:${semanticScore.toFixed(3)}+lexical:${lexicalScore.toFixed(3)}`
+                    : `lexical:${lexicalScore.toFixed(3)}`;
                 results.push({
                     id: String(row.id).substring(0, 12),
                     key: row.key || String(row.id).substring(0, 15),

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

package/v3/@claude-flow/cli/dist/src/services/checkpoint-gate.d.ts

@@ -0,0 +1,140 @@
+/**
+ * CheckpointGate — agenticow-backed checkpoint/rollback gate for autopilot
+ * loops and long-horizon workflows (agenticow integration, step 3).
+ *
+ * ── The pattern ───────────────────────────────────────────────────────────
+ * Before a risky loop tick that mutates `.rvf` memory, take an O(1) agenticow
+ * checkpoint (162 bytes, fixed cost — see mcp-tools/agenticow-tools.ts). Run
+ * the tick. If it regresses — throws, or the caller's verdict says the outcome
+ * got worse (verifier fail / error / worse metric) — roll the memory back to
+ * the checkpoint. Rollback is O(edits-since-checkpoint), NOT an O(N) rebuild,
+ * and the earlier history stays intact via the `.agenticow.json` lineage
+ * manifest. On success the checkpoint is simply kept as the new good baseline.
+ *
+ * The three lifecycle verbs (checkpoint / rollback / promote) already exist in
+ * the `agenticow` package and are surfaced as MCP tools in
+ * `mcp-tools/agenticow-tools.ts`. This module is the *orchestration hook* that
+ * calls them from inside a loop — the MCP surface is for agents, this is for
+ * the in-process loop.
+ *
+ * ── Architectural constraint (ADR-150) ────────────────────────────────────
+ * `agenticow` lives in `optionalDependencies` and must NEVER be a hard runtime
+ * dependency. This gate degrades gracefully in three ways, each of which runs
+ * the tick UNGUARDED rather than failing:
+ *   1. package missing            → { degraded: true, reason: 'agenticow-not-found' }
+ *   2. kill-switch env set         → { degraded: true, reason: 'kill-switch' }
+ *   3. no memory path configured   → { degraded: true, reason: 'no-memory-path' }
+ * The package is lazy-loaded on the first guard() call, so importing this
+ * module has zero startup cost.
+ *
+ * The optional-dep loader + path/label/lineage helpers are the canonical ones
+ * from `mcp-tools/agenticow-loader.ts` — one implementation shared across every
+ * agenticow consumer (verbs, swarm branches, speculative, oracle, this gate).
+ *
+ * @module @claude-flow/cli/services/checkpoint-gate
+ */
+/**
+ * Env var pointing at the `.rvf` memory file that a long-horizon loop mutates.
+ * When set, the autopilot loop opts in to checkpoint/rollback around each tick.
+ * When unset, the gate is a transparent pass-through.
+ */
+export declare const CHECKPOINT_MEM_ENV = "CLAUDE_FLOW_AUTOPILOT_CHECKPOINT_MEM";
+/**
+ * Kill switch. When truthy (`1`/`true`/`yes`), the gate never touches agenticow
+ * and every guard() runs the tick unguarded. Lets an operator disable the
+ * feature without changing config or code.
+ */
+export declare const KILL_SWITCH_ENV = "CLAUDE_FLOW_AGENTICOW_DISABLE";
+/** Outcome of a guarded tick. `result` is undefined only when the tick threw
+ *  AND `rethrow` was disabled. */
+export interface CheckpointGuardResult<T> {
+    /** The value fn() returned (undefined if it threw with rethrow:false). */
+    result: T | undefined;
+    /** True when a checkpoint was actually taken before running fn. */
+    checkpointed: boolean;
+    /** True when memory was rolled back to the checkpoint (throw or regression). */
+    rolledBack: boolean;
+    /** True when the gate could not engage agenticow and ran fn unguarded. */
+    degraded: boolean;
+    /** Machine-readable reason for degraded / rollback. */
+    reason?: string;
+    /** The checkpoint label, when one was taken. */
+    checkpointLabel?: string;
+    /** The error fn() threw, when rethrow was disabled. */
+    error?: unknown;
+}
+export interface GuardOptions<T> {
+    /**
+     * Verdict function: return true when `result` represents a regression that
+     * should trigger a rollback. Defaults to treating `{success:false}` /
+     * `{ok:false}` / `{regressed:true}` as regressions.
+     */
+    isRegression?: (result: T) => boolean;
+    /**
+     * When the tick throws: roll back, then re-throw the original error
+     * (default true). Set false to swallow the error and return it on the
+     * result object instead — useful when the loop must never crash.
+     */
+    rethrow?: boolean;
+    /** Optional checkpoint id to roll back to (defaults to most recent). */
+    checkpointId?: string;
+}
+export declare class CheckpointGate {
+    /** True when the kill-switch env is set to a truthy value. */
+    static isKillSwitchSet(): boolean;
+    /** The configured loop memory path, or undefined when the feature is off. */
+    static configuredMemPath(): string | undefined;
+    /**
+     * Lazy-load agenticow. Returns null when the package is absent (optional dep)
+     * or the kill switch is set. Any *other* import error is re-thrown — a broken
+     * install should be loud, a missing optional dep should be silent.
+     */
+    private load;
+    /** True when agenticow can be engaged (present + not killed). */
+    available(): Promise<boolean>;
+    /**
+     * Take a checkpoint on the given `.rvf` memory file. Non-throwing except for
+     * validation errors (path traversal, bad label) — those are surfaced so a
+     * misconfiguration is caught early.
+     */
+    checkpoint(memPath: string, label: string): Promise<{
+        ok: boolean;
+        degraded: boolean;
+        reason?: string;
+        checkpoint?: unknown;
+    }>;
+    /**
+     * Roll the given `.rvf` memory file back to a checkpoint. Discards edits made
+     * since (O(edits-since-checkpoint)). Omit `checkpointId` to target the most
+     * recent checkpoint.
+     */
+    rollback(memPath: string, checkpointId?: string): Promise<{
+        ok: boolean;
+        degraded: boolean;
+        reason?: string;
+        result?: unknown;
+    }>;
+    /**
+     * Guard a risky loop tick with a checkpoint/rollback bracket.
+     *
+     *   const outcome = await gate.guard(memPath, 'iter-7', async () => runTick());
+     *
+     * Behaviour:
+     *   - No memPath / kill-switch / agenticow-absent → run fn unguarded, degraded:true.
+     *   - Checkpoint fails to engage (degraded) → run fn unguarded, degraded:true.
+     *   - fn throws → roll back to checkpoint, then re-throw (unless rethrow:false).
+     *   - fn returns a regression verdict → roll back, return result with rolledBack:true.
+     *   - fn succeeds → keep the checkpoint, return result with rolledBack:false.
+     *
+     * The gate is non-fatal: an internal agenticow failure never masks fn()'s own
+     * result — if checkpointing throws, fn still runs unguarded.
+     */
+    guard<T>(memPath: string | undefined, label: string, fn: () => Promise<T>, opts?: GuardOptions<T>): Promise<CheckpointGuardResult<T>>;
+    /** Roll back without throwing — used on the failure path so a rollback error
+     *  never masks the original tick failure. */
+    private safeRollback;
+}
+export declare function getCheckpointGate(): CheckpointGate;
+/** Reset the lazy-load cache — test-only. */
+export declare function __resetCheckpointGateForTests(): void;
+//# sourceMappingURL=checkpoint-gate.d.ts.map