@10et/cli 1.0.0

package/dist/lib/agent-session.js

@@ -0,0 +1,954 @@
+/**
+ * Agent Session
+ *
+ * Session lifecycle management following Karpathy's autoresearch loop:
+ * branch → change → eval → keep|revert → repeat
+ *
+ * Git as state machine: keep = advance branch, discard = git reset --hard HEAD~1
+ * results.tsv is NOT committed (append-only local log)
+ *
+ * @purpose Manage scoped agent session lifecycle with git-based state tracking
+ */
+import { existsSync, mkdirSync, appendFileSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+import { spawnSync, spawn } from "child_process";
+import { createHash } from "crypto";
+import { createEvalSnapshot, freezeEvalSnapshot, runEvalSnapshot } from "./eval-snapshot.js";
+import { signedAgentCommit } from "../utils/provenance.js";
+import { tenetEnvBool } from "../utils/tenet-env.js";
+/**
+ * Build experiment history markdown for the agent to read.
+ * This is the KEY missing piece — agents need memory of past experiments.
+ *
+ * Following Karpathy's autoresearch pattern: agent sees program.md with
+ * instructions + history of past experiments so it knows what to try next.
+ */
+export function buildExperimentHistory(session, transitions, currentMetric) {
+    const config = session.config;
+    const direction = config.direction === "minimize" ? "lower is better" : "higher is better";
+    // Get scope_files from constraints if available
+    const scopeFiles = (() => {
+        try {
+            const raw = config.constraints?.scope_files || config.constraints?.files_in_scope || [];
+            return Array.isArray(raw) ? raw : typeof raw === 'string' ? [raw] : [];
+        }
+        catch {
+            return [];
+        }
+    })();
+    const lines = [
+        `# Experiment History — ${session.agentName}`,
+        "",
+        `## Goal`,
+        `Optimize metric: **${config.metric}** (${direction})`,
+        `Current value: **${currentMetric.toFixed(4)}**`,
+        `Baseline: ${session.baselineMetric.toFixed(4)}`,
+        "",
+        `## Files to Modify`,
+        `Focus your changes on these specific files:`,
+        ...scopeFiles.map((f) => `- ${f}`),
+        "",
+        `## Constraints`,
+        `- Max files per change: ${config.constraints.max_file_changes}`,
+        `- Read-only: ${config.constraints.files_readonly.join(", ")}`,
+        "",
+        `## Past Experiments`,
+        ""
+    ];
+    // Include eval diagnostics — agent needs to see WHAT is failing
+    const rawEvalOutput = session.lastEvalOutput || "";
+    if (rawEvalOutput) {
+        try {
+            const evalJson = JSON.parse(rawEvalOutput);
+            if (evalJson.failed_queries && evalJson.failed_queries.length > 0) {
+                lines.push(`## Eval Diagnostics — WHAT IS FAILING`);
+                lines.push(`These queries/tests are failing. Fix them to improve the metric:`);
+                lines.push("");
+                for (const q of evalJson.failed_queries.slice(0, 10)) {
+                    lines.push(`- ✗ ${q}`);
+                }
+                lines.push("");
+            }
+            if (evalJson.per_query) {
+                const failing = evalJson.per_query.filter((q) => q.hits < q.expected);
+                if (failing.length > 0) {
+                    lines.push(`## Detailed Failures`);
+                    for (const q of failing.slice(0, 8)) {
+                        lines.push(`- Query: "${q.query}" — found [${(q.found || []).join(",")}] but expected IDs [${(q.expected_ids || []).join(",")}]`);
+                    }
+                    lines.push("");
+                }
+            }
+            // Dimension breakdowns
+            const dimKeys = Object.keys(evalJson).filter(k => k.endsWith("_recall") || k.endsWith("_score") || k.endsWith("_pct"));
+            if (dimKeys.length > 0) {
+                lines.push(`## Metric Breakdown`);
+                for (const k of dimKeys) {
+                    lines.push(`- ${k}: ${evalJson[k]}`);
+                }
+                lines.push("");
+            }
+        }
+        catch {
+            // Not JSON — try to extract failure lines
+            const failLines = rawEvalOutput.split("\n").filter((l) => l.includes("✗") || l.toLowerCase().includes("fail"));
+            if (failLines.length > 0) {
+                lines.push(`## Eval Diagnostics`);
+                for (const l of failLines.slice(0, 8))
+                    lines.push(`- ${l.trim()}`);
+                lines.push("");
+            }
+        }
+    }
+    // Include code snippets — agent must READ code before modifying (autoresearch pattern)
+    lines.push(`## Code Context — READ BEFORE MODIFYING`);
+    lines.push(`The following are the first 100 lines of each scope file. Understand the code before making changes.`);
+    lines.push("");
+    for (const scopeFile of scopeFiles.slice(0, 3)) {
+        const filePath = join(session.worktreePath, scopeFile);
+        try {
+            if (existsSync(filePath)) {
+                const content = readFileSync(filePath, "utf-8");
+                const codeLines = content.split("\n").slice(0, 100);
+                lines.push("```typescript");
+                lines.push(`// ${scopeFile}`);
+                lines.push(...codeLines);
+                lines.push("```");
+                lines.push("");
+            }
+        }
+        catch { }
+    }
+    if (transitions.length === 0) {
+        lines.push("## Past Experiments");
+        lines.push("No experiments yet. This is round 1.");
+        lines.push("");
+        lines.push("Read the eval diagnostics above. Identify WHY queries fail. Make ONE targeted change to the code.");
+    }
+    else {
+        // Group by kept/rejected
+        const kept = transitions.filter(t => t.reward > 0);
+        const rejected = transitions.filter(t => t.reward <= 0);
+        lines.push(`### Kept (${kept.length} experiments that improved the metric):`);
+        if (kept.length === 0) {
+            lines.push("None yet.");
+        }
+        else {
+            for (const t of kept.slice(-10)) { // Last 10 kept
+                const files = t.action.files_affected.join(", ") || "unknown";
+                lines.push(`- R${t.state.trajectory_length}: "${t.action.description.slice(0, 60)}" → +${t.reward.toFixed(4)} (files: ${files})`);
+            }
+        }
+        lines.push("");
+        lines.push(`### Rejected (${rejected.length} experiments that did NOT improve):`);
+        if (rejected.length === 0) {
+            lines.push("None yet.");
+        }
+        else {
+            for (const t of rejected.slice(-10)) { // Last 10 rejected
+                lines.push(`- R${t.state.trajectory_length}: "${t.action.description.slice(0, 60)}" → ${t.reward.toFixed(4)}`);
+            }
+        }
+        lines.push("");
+        lines.push(`## What to Do`);
+        lines.push(`1. DO NOT repeat rejected experiments`);
+        lines.push(`2. BUILD on kept experiments — they worked`);
+        lines.push(`3. Make ONE small, focused change`);
+        lines.push(`4. Prefer modifying existing code over adding new files`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Write experiment history to the worktree as EXPERIMENTS.md.
+ * Claude Code will read this file to understand what has been tried.
+ */
+export function writeExperimentHistory(session, transitions, currentMetric) {
+    const content = buildExperimentHistory(session, transitions, currentMetric);
+    const historyPath = join(session.worktreePath, "EXPERIMENTS.md");
+    try {
+        writeFileSync(historyPath, content);
+    }
+    catch (err) {
+        console.error(`  Warning: Could not write experiment history: ${err}`);
+    }
+}
+/**
+ * Read experiment history from the worktree.
+ * Returns empty string if file doesn't exist.
+ */
+export function readExperimentHistory(session) {
+    const historyPath = join(session.worktreePath, "EXPERIMENTS.md");
+    try {
+        if (existsSync(historyPath)) {
+            return readFileSync(historyPath, "utf-8");
+        }
+    }
+    catch { }
+    return "";
+}
+// ============================================================================
+// Git Helpers
+// ============================================================================
+function gitExec(args, cwd) {
+    const result = spawnSync("git", args, { cwd, encoding: "utf-8", stdio: "pipe" });
+    return { ok: result.status === 0, output: (result.stdout || "").trim() };
+}
+function getCurrentBranch(cwd) {
+    const result = gitExec(["branch", "--show-current"], cwd);
+    return result.output;
+}
+function hasUncommittedChanges(cwd) {
+    const diff = gitExec(["diff", "--quiet", "HEAD"], cwd);
+    const untracked = spawnSync("git", ["ls-files", "--others", "--exclude-standard"], {
+        cwd, encoding: "utf-8", stdio: "pipe",
+    });
+    return !diff.ok || (untracked.stdout || "").trim().length > 0;
+}
+function getGitDiff(cwd) {
+    const result = gitExec(["diff", "HEAD"], cwd);
+    return result.output;
+}
+// ============================================================================
+// Scope Impact Emission
+// ============================================================================
+function emitScopeImpact(session, pattern, delta, summary) {
+    // Write scope:impact event to service-events.jsonl for the hub to pick up
+    const eventsPath = join(session.projectRoot, ".jfl", "service-events.jsonl");
+    const event = {
+        type: "scope:impact",
+        source: `agent:${session.agentName}`,
+        data: {
+            agent: session.agentName,
+            pattern,
+            metric: session.config.metric,
+            delta,
+            direction: session.config.direction,
+            session_id: session.id,
+            baseline: summary.baseline,
+            final: summary.finalMetric,
+            rounds: summary.rounds,
+            improved_rounds: summary.improvedRounds,
+            pr_url: summary.prUrl,
+            branch_url: summary.branchUrl,
+            produces: session.config.context_scope.produces,
+            consumes: session.config.context_scope.consumes,
+        },
+        ts: new Date().toISOString(),
+    };
+    try {
+        appendFileSync(eventsPath, JSON.stringify(event) + "\n");
+    }
+    catch {
+        // Non-fatal — hub may not be running
+    }
+    // Also try to POST to hub if running
+    try {
+        const tokenPath = join(session.projectRoot, ".jfl", "context-hub.token");
+        if (existsSync(tokenPath)) {
+            const token = readFileSync(tokenPath, "utf-8").trim();
+            const http = require("http");
+            const postData = JSON.stringify(event);
+            const req = http.request({
+                hostname: "localhost",
+                port: 4242,
+                path: "/api/events",
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "Authorization": `Bearer ${token}`,
+                    "Content-Length": Buffer.byteLength(postData),
+                },
+            });
+            req.write(postData);
+            req.end();
+        }
+    }
+    catch {
+        // Non-fatal
+    }
+}
+// ============================================================================
+// Session Management
+// ============================================================================
+export function startSession(config, projectRoot, baseBranch = "main") {
+    // Generate unique session ID
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const hashPart = createHash("sha256")
+        .update(`${config.name}-${timestamp}-${Math.random()}`)
+        .digest("hex")
+        .slice(0, 8);
+    const sessionId = `${config.name}-${hashPart}-${Date.now()}`;
+    // Create session branch
+    const branch = `session/${config.name}-${hashPart}-${timestamp.slice(0, 10)}`;
+    // Create isolated worktree in /tmp — never touch the main working directory
+    const worktreePath = join("/tmp", `jfl-agent-${config.name}-${hashPart}`);
+    // Resolve target repo — agents can target a different service repo than the GTM root
+    const repoRoot = config.target_repo
+        ? join(projectRoot, config.target_repo)
+        : projectRoot;
+    // Clean up stale worktree at this path (from crashed/killed sessions)
+    // Without this, git worktree add fails and falls back to main — breaking auto-PR
+    if (existsSync(worktreePath)) {
+        console.log(`  Cleaning stale worktree: ${worktreePath}`);
+        gitExec(["worktree", "remove", worktreePath, "--force"], repoRoot);
+    }
+    gitExec(["worktree", "prune"], repoRoot);
+    // Delete stale session branch if it exists (from a previous crashed session with same hash)
+    const branchCheck = gitExec(["rev-parse", "--verify", branch], repoRoot);
+    if (branchCheck.ok) {
+        console.log(`  Deleting stale branch: ${branch}`);
+        gitExec(["branch", "-D", branch], repoRoot);
+    }
+    // Fetch latest base branch
+    gitExec(["fetch", "origin", baseBranch], repoRoot);
+    // Build agents branch from HEAD (inherits previously merged work).
+    // RL agents branch from origin/baseBranch (clean baseline for each experiment).
+    const isBuildAgent = config.scope === "build";
+    const branchBase = isBuildAgent ? "HEAD" : `origin/${baseBranch}`;
+    // Create worktree with new branch
+    let wt = gitExec(["worktree", "add", worktreePath, "-b", branch, branchBase], repoRoot);
+    if (!wt.ok && !isBuildAgent) {
+        // Fallback: try local baseBranch (only for RL agents)
+        wt = gitExec(["worktree", "add", worktreePath, "-b", branch, baseBranch], repoRoot);
+    }
+    if (!wt.ok) {
+        throw new Error(`Failed to create worktree for ${branch}: ${wt.output}`);
+    }
+    // Create eval snapshot — eval scripts live in GTM (projectRoot), not the service worktree
+    // Copy eval files into the worktree so they're available during agent runs
+    const evalSnapshot = createEvalSnapshot(projectRoot, config.eval.script, config.eval.data);
+    freezeEvalSnapshot(evalSnapshot);
+    // Results persist in main repo (survives worktree cleanup)
+    const resultsDir = join(projectRoot, ".jfl", "sessions", sessionId);
+    mkdirSync(resultsDir, { recursive: true });
+    const resultsPath = join(resultsDir, "results.tsv");
+    // Write TSV header
+    writeFileSync(resultsPath, "round\ttask\tbaseline\tmetric\tdelta\tkept\tduration_ms\terror\ttimestamp\n");
+    // Run baseline eval
+    const session = {
+        id: sessionId,
+        agentName: config.name,
+        config,
+        projectRoot,
+        evalRoot: projectRoot,
+        worktreePath,
+        branch,
+        baseBranch,
+        evalSnapshot,
+        baselineMetric: 0,
+        startedAt: new Date().toISOString(),
+        resultsPath,
+        round: 0,
+        status: "active",
+    };
+    return session;
+}
+export async function runBaseline(session) {
+    // Eval scripts live in GTM (evalRoot), not the service worktree
+    const result = await runEvalSnapshot(session.evalSnapshot, session.evalRoot, session.config.time_budget_seconds * 1000);
+    if (!result.success) {
+        throw new Error(`Baseline eval failed: ${result.error}`);
+    }
+    session.baselineMetric = result.metric;
+    session.lastEvalOutput = result.raw_output || "";
+    return result.metric;
+}
+export async function runRound(session, round, task, hypothesis, previousTransitions = []) {
+    const startTime = Date.now();
+    session.round = round;
+    // Capture state before changes
+    const stateBefore = {
+        composite_score: session.baselineMetric,
+        dimension_scores: {},
+        tests_passing: 0,
+        tests_total: 1,
+        trajectory_length: round,
+        recent_deltas: previousTransitions.slice(-5).map(t => t.reward),
+        agent: session.agentName,
+    };
+    const stateHash = createHash("sha256")
+        .update(JSON.stringify(stateBefore))
+        .digest("hex")
+        .slice(0, 12);
+    // Write experiment history BEFORE running Claude Code
+    // This is the Karpathy pattern: agent sees history + instructions
+    writeExperimentHistory(session, previousTransitions, session.baselineMetric);
+    // Run Claude Code with fixed time budget
+    await runClaudeCode(session, task);
+    // Check if any changes were made (in the worktree)
+    const hasChanges = hasUncommittedChanges(session.worktreePath);
+    if (!hasChanges) {
+        const noChangeResult = {
+            round,
+            task,
+            hypothesis,
+            metricBefore: session.baselineMetric,
+            metricAfter: session.baselineMetric,
+            delta: 0,
+            kept: false,
+            duration_ms: Date.now() - startTime,
+            error: "No changes made",
+        };
+        const noChangeTransition = {
+            agent: session.agentName,
+            session_id: session.id,
+            state_hash: stateHash,
+            state: stateBefore,
+            action_diff: "",
+            action: {
+                type: "experiment",
+                description: task,
+                files_affected: [],
+                scope: "small",
+                branch: session.branch,
+            },
+            hypothesis,
+            reward: 0,
+            timestamp: new Date().toISOString(),
+        };
+        logResult(session, noChangeResult);
+        return { result: noChangeResult, transition: noChangeTransition };
+    }
+    // Capture the diff before committing
+    const diff = getGitDiff(session.worktreePath);
+    // Get changed files
+    const changedFilesResult = spawnSync("git", ["diff", "--name-only", "HEAD"], {
+        cwd: session.worktreePath,
+        encoding: "utf-8",
+        stdio: "pipe",
+    });
+    const changedFiles = (changedFilesResult.stdout || "")
+        .trim()
+        .split("\n")
+        .filter(Boolean);
+    // ── Guard check: must pass before eval (T1.2) ──
+    // e.g. "cd ${AGENT_WORKTREE} && npx tsc --noEmit" catches type errors
+    const guardCmd = session.config.eval.guard;
+    if (guardCmd) {
+        const expandedGuard = guardCmd.replace(/\$\{AGENT_WORKTREE\}/g, session.worktreePath);
+        console.log(`  Running guard: ${expandedGuard.slice(0, 80)}...`);
+        const guardResult = spawnSync("bash", ["-c", expandedGuard], {
+            cwd: session.worktreePath,
+            encoding: "utf-8",
+            stdio: "pipe",
+            timeout: 60000, // 60s max for guard
+        });
+        if (guardResult.status !== 0) {
+            console.log(`  ✗ Guard FAILED — reverting changes`);
+            const guardError = (guardResult.stderr || guardResult.stdout || "").trim().split("\n").slice(-5).join("\n");
+            if (guardError)
+                console.log(`    ${guardError.split("\n").join("\n    ")}`);
+            // Revert: discard all changes in worktree
+            gitExec(["checkout", "--", "."], session.worktreePath);
+            gitExec(["clean", "-fd"], session.worktreePath);
+            const guardFailResult = {
+                round,
+                task,
+                hypothesis,
+                metricBefore: session.baselineMetric,
+                metricAfter: session.baselineMetric,
+                delta: 0,
+                kept: false,
+                duration_ms: Date.now() - startTime,
+                error: `Guard failed: ${guardError.slice(0, 200)}`,
+            };
+            const guardFailTransition = {
+                agent: session.agentName,
+                session_id: session.id,
+                state_hash: stateHash,
+                state: stateBefore,
+                action_diff: diff,
+                action: {
+                    type: "experiment",
+                    description: task,
+                    files_affected: changedFiles,
+                    scope: changedFiles.length <= 1 ? "small" : changedFiles.length <= 3 ? "medium" : "large",
+                    branch: session.branch,
+                },
+                hypothesis,
+                reward: -0.001, // Small negative signal — guard failures are worse than no-ops
+                timestamp: new Date().toISOString(),
+            };
+            logResult(session, guardFailResult);
+            return { result: guardFailResult, transition: guardFailTransition };
+        }
+        console.log(`  ✓ Guard passed`);
+    }
+    // Commit changes in worktree with provenance signing
+    signedAgentCommit(session.worktreePath, `agent(${session.agentName}): round ${round} - ${task.slice(0, 50)}`, {
+        agentId: session.agentName,
+        sessionId: session.id,
+    });
+    // Run frozen eval — pass worktree path so eval scripts can test agent's changes
+    process.env.AGENT_WORKTREE = session.worktreePath;
+    const evalResult = await runEvalSnapshot(session.evalSnapshot, session.evalRoot, session.config.time_budget_seconds * 1000);
+    delete process.env.AGENT_WORKTREE;
+    const metricAfter = evalResult.success ? evalResult.metric : 0;
+    const delta = metricAfter - session.baselineMetric;
+    // Decide: keep or discard
+    // For maximize: keep if delta > 0
+    // For minimize: keep if delta < 0
+    const improved = session.config.direction === "maximize"
+        ? delta > 0
+        : delta < 0;
+    if (improved) {
+        // Keep: advance baseline
+        session.baselineMetric = metricAfter;
+    }
+    else {
+        // Discard: git reset --hard HEAD~1 (in worktree only)
+        gitExec(["reset", "--hard", "HEAD~1"], session.worktreePath);
+    }
+    const result = {
+        round,
+        task,
+        hypothesis,
+        metricBefore: session.baselineMetric,
+        metricAfter,
+        delta,
+        kept: improved,
+        duration_ms: Date.now() - startTime,
+        error: evalResult.success ? undefined : evalResult.error,
+    };
+    const action = {
+        type: "experiment",
+        description: task,
+        files_affected: changedFiles,
+        scope: changedFiles.length <= 2 ? "small" : changedFiles.length <= 5 ? "medium" : "large",
+        branch: session.branch,
+    };
+    const transition = {
+        agent: session.agentName,
+        session_id: session.id,
+        state_hash: stateHash,
+        state: stateBefore,
+        action_diff: diff,
+        action,
+        hypothesis,
+        reward: improved ? Math.abs(delta) : -Math.abs(delta), // Positive reward = improvement, regardless of direction
+        timestamp: new Date().toISOString(),
+    };
+    logResult(session, result);
+    return { result, transition };
+}
+async function runClaudeCode(session, task) {
+    const timeout = session.config.time_budget_seconds * 1000;
+    // Write all context to files — Karpathy pattern
+    // EXPERIMENTS.md has: eval diagnostics, code context, experiment history
+    // AGENT.md has: task, constraints, scope files
+    // CLAUDE.md has: minimal "read files, edit code, stop" instructions
+    writeAgentMd(session, task);
+    writeAgentClaudeMd(session);
+    // Task prompt is deliberately tiny — all context is in files.
+    // Long prompts waste tokens and slow down time-to-first-edit.
+    const tinyTask = `Read EXPERIMENTS.md then AGENT.md. Make ONE edit to improve ${session.config.metric}. Stop after editing.`;
+    // API-based runtime: zero memory churn. Single process, HTTP calls per round.
+    // Falls back to claude CLI spawn only if no API key is available.
+    if ((process.env.ANTHROPIC_API_KEY || process.env.OPENROUTER_API_KEY) && !tenetEnvBool('AGENT_USE_SPAWN')) {
+        try {
+            const { runAgentViaAPI } = await import("./agent-runtime-api.js");
+            // Build agents need more turns (creating multiple files) vs RL agents (one small edit)
+            const isBuildAgent = session.config.scope === "build";
+            await runAgentViaAPI({ task: tinyTask, cwd: session.worktreePath, timeoutMs: timeout, maxTurns: isBuildAgent ? 40 : 15 });
+            return;
+        }
+        catch (err) {
+            if (err.message?.includes("ANTHROPIC_API_KEY")) {
+                console.log("  ⚠ No ANTHROPIC_API_KEY — falling back to claude CLI spawn");
+            }
+            else {
+                console.error(`  ⚠ API runtime failed: ${err.message} — falling back to claude CLI spawn`);
+            }
+        }
+    }
+    // Legacy fallback: spawns a new process per round (~300MB each).
+    // macOS compresses dead pages — 20 rounds = 6GB unreclaimable without reboot.
+    // Set ANTHROPIC_API_KEY to avoid this. Set JFL_AGENT_USE_SPAWN=1 to force this path.
+    return new Promise((resolve) => {
+        spawnAgentRuntime(tinyTask, session.worktreePath, timeout, resolve);
+    });
+}
+/**
+ * Write AGENT.md to the worktree — focused instructions for RL agents.
+ * Contains: task, scope, eval diagnostics, code context, constraints.
+ * This is what the agent reads instead of CLAUDE.md.
+ */
+function writeAgentMd(session, task) {
+    const scopeFiles = (() => { const raw = session.config.constraints?.scope_files || session.config.constraints.files_in_scope || []; return Array.isArray(raw) ? raw : [String(raw)]; })();
+    const agentMd = `# Agent: ${session.agentName}
+
+## Task
+${task}
+
+## Constraints
+- **Modify ONLY these files:** ${scopeFiles.join(", ")}
+- **Do NOT modify:** AGENT.md, EXPERIMENTS.md, eval scripts, node_modules, dist
+- **Max file changes:** ${session.config.constraints.max_file_changes || 2}
+- **Time budget:** ${session.config.time_budget_seconds}s
+
+## How to Succeed
+1. Read EXPERIMENTS.md — it shows what failed and the actual source code
+2. Make ONE small, targeted change to a source file
+3. Stop after making the change — the eval runs automatically
+
+## What NOT to Do
+- Do not add new files
+- Do not modify test files or eval scripts
+- Do not just add comments or documentation
+- Do not repeat experiments listed as REJECTED in EXPERIMENTS.md
+`;
+    writeFileSync(join(session.worktreePath, "AGENT.md"), agentMd);
+}
+/**
+ * Write a minimal CLAUDE.md to the worktree for RL agents.
+ * Karpathy pattern: agent gets focused instructions, no ceremony.
+ * Claude CLI reads CLAUDE.md automatically — this replaces the full project CLAUDE.md.
+ */
+function writeAgentClaudeMd(session) {
+    const scopeFiles = (() => { const raw = session.config.constraints?.scope_files || session.config.constraints.files_in_scope || []; return Array.isArray(raw) ? raw : [String(raw)]; })();
+    const claudeMd = `You improve code metrics. Read EXPERIMENTS.md, make ONE edit, stop.
+
+Files you can edit: ${scopeFiles.join(", ")}
+Do NOT edit: AGENT.md, EXPERIMENTS.md, eval scripts, tests
+
+Use bash for everything — cat to read, sed -i to edit, grep to search.
+Make your edit, then stop. The eval runs automatically after you exit.
+`;
+    writeFileSync(join(session.worktreePath, "CLAUDE.md"), claudeMd);
+}
+/**
+ * Spawn agent runtime — uses claude CLI for lightweight execution.
+ * Karpathy pattern: agent is just an LLM with file tools, all context in files.
+ * ~50MB per process vs ~500MB for full Pi with JFL extension.
+ * Use TENET_AGENT_USE_PI=1 to force Pi runtime (for debugging).
+ */
+function spawnAgentRuntime(task, cwd, timeout, resolve) {
+    const usePi = tenetEnvBool('AGENT_USE_PI'); // Opt-in to Pi (heavy), default is claude CLI (light)
+    if (usePi) {
+        console.log("  Spawning Pi agent (heavy — use for debugging only)...");
+        const child = spawn("pi", [
+            "--print", task,
+            "--no-session",
+            "--no-skills",
+            "--no-prompt-templates",
+            "--no-themes",
+        ], {
+            cwd,
+            stdio: "inherit",
+            env: {
+                ...process.env,
+                JFL_AGENT_MODE: "1",
+                JFL_PP_SPAWNED: "1",
+                CLAUDECODE: undefined,
+                CLAUDE_CODE: undefined,
+            },
+        });
+        const timeoutId = setTimeout(() => {
+            child.kill("SIGTERM");
+            setTimeout(() => {
+                if (!child.killed)
+                    child.kill("SIGKILL");
+            }, 5000);
+        }, timeout);
+        child.on("error", (err) => {
+            console.error(`  Pi agent error: ${err.message}`);
+            clearTimeout(timeoutId);
+            console.log("  Falling back to claude CLI...");
+            spawnClaudeCli(task, cwd, timeout, resolve);
+        });
+        child.on("exit", (code, signal) => {
+            if (code !== null) {
+                console.log(`  Pi agent exit: code=${code}`);
+            }
+            else if (signal) {
+                console.log(`  Pi agent killed: signal=${signal}`);
+            }
+            clearTimeout(timeoutId);
+            resolve();
+        });
+    }
+    else {
+        spawnClaudeCli(task, cwd, timeout, resolve);
+    }
+}
+/**
+ * Spawn claude CLI — lightweight agent runtime (~50MB).
+ * Karpathy pattern: LLM reads files, edits code, exits.
+ * CLAUDE.md in worktree provides focused instructions.
+ * EXPERIMENTS.md has all context (eval diagnostics, code, history).
+ */
+function spawnClaudeCli(task, cwd, timeout, resolve) {
+    console.log("  Spawning claude CLI (lightweight, Karpathy-style)...");
+    const child = spawn("claude", [
+        "--dangerously-skip-permissions",
+        "-p", task,
+        "--output-format", "text",
+    ], {
+        cwd,
+        stdio: "inherit",
+        env: {
+            ...process.env,
+            CLAUDECODE: undefined,
+            CLAUDE_CODE: undefined,
+        },
+    });
+    const timeoutId = setTimeout(() => {
+        child.kill("SIGTERM");
+        setTimeout(() => {
+            if (!child.killed)
+                child.kill("SIGKILL");
+        }, 5000);
+    }, timeout);
+    child.on("error", (err) => {
+        console.error(`  Claude CLI error: ${err.message}`);
+        clearTimeout(timeoutId);
+        resolve();
+    });
+    child.on("exit", (code, signal) => {
+        console.error(`  Claude CLI exit: code=${code} signal=${signal}`);
+        clearTimeout(timeoutId);
+        resolve();
+    });
+}
+function logResult(session, result) {
+    const line = [
+        result.round,
+        result.task.replace(/\t/g, " ").slice(0, 100),
+        result.metricBefore.toFixed(6),
+        result.metricAfter.toFixed(6),
+        result.delta.toFixed(6),
+        result.kept ? "1" : "0",
+        result.duration_ms,
+        (result.error || "").replace(/\t/g, " ").slice(0, 100),
+        new Date().toISOString(),
+    ].join("\t");
+    appendFileSync(session.resultsPath, line + "\n");
+    // Remove EXPERIMENTS.md from git tracking (it's ephemeral, regenerated each round)
+    const experimentsPath = join(session.worktreePath, "EXPERIMENTS.md");
+    if (existsSync(experimentsPath)) {
+        gitExec(["reset", "HEAD", "EXPERIMENTS.md"], session.worktreePath);
+        // Don't delete — keep it for reference, just don't commit
+    }
+}
+export async function endSession(session, transitions) {
+    session.status = "completed";
+    // Calculate summary statistics
+    let improvedRounds = 0;
+    let bestDelta = 0;
+    let totalDelta = 0;
+    for (const t of transitions) {
+        if (t.reward > 0)
+            improvedRounds++;
+        if (t.reward > bestDelta)
+            bestDelta = t.reward;
+        totalDelta += t.reward;
+    }
+    const summary = {
+        session_id: session.id,
+        agentName: session.agentName,
+        rounds: transitions.length,
+        baseline: session.baselineMetric - totalDelta, // Reconstruct original baseline
+        finalMetric: session.baselineMetric,
+        totalDelta,
+        bestDelta,
+        improvedRounds,
+        transitions,
+    };
+    // Write transitions to training buffer WITH diffs (for code-policy training)
+    try {
+        const { TrainingBuffer } = await import("./training-buffer.js");
+        const tb = new TrainingBuffer(session.projectRoot);
+        for (const t of transitions) {
+            tb.append({
+                agent: t.agent,
+                state: t.state,
+                action: {
+                    ...t.action,
+                    // Include the actual code diff for code-policy training (AutoHarness pattern)
+                    code_diff: t.action_diff?.slice(0, 10000) || "", // Cap at 10KB
+                },
+                reward: {
+                    composite_delta: t.reward,
+                    dimension_deltas: {},
+                    tests_added: 0,
+                    quality_score: t.reward > 0 ? 1 : 0,
+                    improved: t.reward > 0,
+                },
+                metadata: {
+                    branch: session.branch,
+                    source: "autoresearch",
+                    session_id: session.id,
+                    round: t.state?.trajectory_length || 0,
+                    hypothesis: t.hypothesis,
+                },
+            });
+        }
+    }
+    catch { }
+    // If we improved, push the branch and create a PR for review
+    // T1.4: Auto-create PR from kept improvement
+    if (improvedRounds > 0) {
+        // Push the branch so it's available for review
+        const push = gitExec(["push", "-u", "origin", session.branch], session.worktreePath);
+        if (push.ok) {
+            summary.branchUrl = `https://github.com/402goose/${session.worktreePath.split('/').pop()}/tree/${session.branch}`;
+            // Auto-create PR with improvement summary
+            const prTitle = `agent(${session.agentName}): ${session.config.metric} ${totalDelta > 0 ? "+" : ""}${totalDelta.toFixed(4)} (${improvedRounds}/${transitions.length} rounds kept)`;
+            const prBody = [
+                `## Agent Improvement: ${session.agentName}`,
+                "",
+                `**Metric:** ${session.config.metric} (${session.config.direction})`,
+                `**Baseline:** ${(session.baselineMetric - totalDelta).toFixed(4)}`,
+                `**Final:** ${session.baselineMetric.toFixed(4)}`,
+                `**Delta:** ${totalDelta > 0 ? "+" : ""}${totalDelta.toFixed(4)}`,
+                `**Rounds:** ${improvedRounds} kept / ${transitions.length} total`,
+                "",
+                "### Kept Changes",
+                ...transitions.filter(t => t.reward > 0).map(t => `- **+${t.reward.toFixed(4)}**: ${t.action.description.slice(0, 100)} (${t.action.files_affected.join(", ")})`),
+                "",
+                "### Rejected Changes",
+                `${transitions.filter(t => t.reward <= 0).length} experiments reverted (no improvement).`,
+                "",
+                `---`,
+                `Session: \`${session.id}\``,
+                `Branch: \`${session.branch}\``,
+                `Guard: ${session.config.eval.guard ? "✅ " + session.config.eval.guard.slice(0, 60) : "none"}`,
+            ].join("\n");
+            const prResult = spawnSync("gh", [
+                "pr", "create",
+                "--title", prTitle,
+                "--body", prBody,
+                "--base", session.baseBranch,
+                "--head", session.branch,
+            ], {
+                cwd: session.worktreePath,
+                encoding: "utf-8",
+                stdio: "pipe",
+                timeout: 30000,
+            });
+            if (prResult.status === 0) {
+                const prUrl = (prResult.stdout || "").trim();
+                summary.prUrl = prUrl;
+                console.log(`  PR created: ${prUrl}`);
+            }
+            else {
+                // PR creation failed — branch is still pushed for manual review
+                const err = (prResult.stderr || "").trim();
+                if (err.includes("already exists")) {
+                    console.log(`  PR already exists for ${session.branch}`);
+                }
+                else {
+                    console.log(`  PR creation failed: ${err.slice(0, 100)}`);
+                }
+            }
+        }
+        // Emit scope:impact events for each produces pattern
+        // This triggers downstream agents that consume these patterns
+        for (const pattern of session.config.context_scope.produces) {
+            emitScopeImpact(session, pattern, totalDelta, summary);
+        }
+    }
+    // Clean up worktree — the branch persists on remote for review
+    gitExec(["worktree", "remove", session.worktreePath, "--force"], session.projectRoot);
+    gitExec(["worktree", "prune"], session.projectRoot);
+    return summary;
+}
+async function createPR(session, summary) {
+    // Push branch from worktree
+    const push = gitExec(["push", "-u", "origin", session.branch], session.worktreePath);
+    if (!push.ok) {
+        return undefined;
+    }
+    // Create PR
+    const title = `Agent(${session.agentName}): +${summary.totalDelta.toFixed(4)} ${session.config.metric}`;
+    const body = [
+        `## Scoped Agent Result`,
+        "",
+        `**Agent:** ${session.agentName}`,
+        `**Metric:** ${session.config.metric}`,
+        `**Baseline:** ${summary.baseline.toFixed(4)}`,
+        `**Final:** ${summary.finalMetric.toFixed(4)}`,
+        `**Delta:** +${summary.totalDelta.toFixed(4)}`,
+        "",
+        `### Rounds`,
+        `- Total: ${summary.rounds}`,
+        `- Improved: ${summary.improvedRounds}`,
+        `- Best delta: +${summary.bestDelta.toFixed(4)}`,
+        "",
+        "---",
+        "*Generated by JFL scoped agent*",
+    ].join("\n");
+    const prResult = spawnSync("gh", [
+        "pr", "create",
+        "--title", title,
+        "--body", body,
+        "--base", session.baseBranch,
+        "--head", session.branch,
+        "--label", "agent-generated",
+    ], {
+        cwd: session.worktreePath,
+        encoding: "utf-8",
+        stdio: "pipe",
+    });
+    if (prResult.status === 0) {
+        return prResult.stdout.trim();
+    }
+    // Try without label
+    const prRetry = spawnSync("gh", [
+        "pr", "create",
+        "--title", title,
+        "--body", body,
+        "--base", session.baseBranch,
+        "--head", session.branch,
+    ], {
+        cwd: session.worktreePath,
+        encoding: "utf-8",
+        stdio: "pipe",
+    });
+    return prRetry.status === 0 ? prRetry.stdout.trim() : undefined;
+}
+// ============================================================================
+// Session Recovery
+// ============================================================================
+export function loadSessionState(projectRoot, sessionId) {
+    const sessionDir = join(projectRoot, ".jfl", "sessions", sessionId);
+    const statePath = join(sessionDir, "state.json");
+    if (!existsSync(statePath))
+        return null;
+    try {
+        const state = JSON.parse(readFileSync(statePath, "utf-8"));
+        return state;
+    }
+    catch {
+        return null;
+    }
+}
+export function saveSessionState(session) {
+    const sessionDir = join(session.projectRoot, ".jfl", "sessions", session.id);
+    if (!existsSync(sessionDir)) {
+        mkdirSync(sessionDir, { recursive: true });
+    }
+    const statePath = join(sessionDir, "state.json");
+    writeFileSync(statePath, JSON.stringify(session, null, 2));
+}
+export function listActiveSessions(projectRoot) {
+    const sessionsDir = join(projectRoot, ".jfl", "sessions");
+    if (!existsSync(sessionsDir))
+        return [];
+    const { readdirSync } = require("fs");
+    const sessions = [];
+    for (const entry of readdirSync(sessionsDir)) {
+        const statePath = join(sessionsDir, entry, "state.json");
+        if (existsSync(statePath)) {
+            try {
+                const state = JSON.parse(readFileSync(statePath, "utf-8"));
+                if (state.status === "active") {
+                    sessions.push(entry);
+                }
+            }
+            catch { }
+        }
+    }
+    return sessions;
+}
+//# sourceMappingURL=agent-session.js.map