ccjk 14.0.0 → 14.1.0

package/dist/chunks/research.mjs

@@ -2,14 +2,19 @@ import a from './index5.mjs';
 import { existsSync, readFileSync, appendFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { n as nanoid } from '../shared/ccjk.BoApaI4j.mjs';
-import { T as TaskPersistence } from '../shared/ccjk.BOO14f66.mjs';
+import { T as TaskPersistence } from '../shared/ccjk.CNhnT6uQ.mjs';
 import { e as executeCommand } from '../shared/ccjk.BnsY5WxD.mjs';
 import { j as join, d as dirname } from '../shared/ccjk.bQ7Dh1g4.mjs';
+import { m as matter } from '../shared/ccjk.y-a_1vK4.mjs';
+import { writeFile, readFile } from './fs-operations.mjs';
 import '../shared/ccjk.BAGoDD49.mjs';
 import 'node:crypto';
 import 'better-sqlite3';
 import 'node:child_process';
 import 'node:util';
+import 'fs';
+import '../shared/ccjk.COweQ1RR.mjs';
+import 'node:fs/promises';
 
 class TaskQueue {
   queue = [];
@@ -270,7 +275,7 @@ class ResearchCommandError extends Error {
     this.name = "ResearchCommandError";
   }
 }
-function createPersistence(dbPath) {
+function createPersistence$1(dbPath) {
   return new TaskPersistence(dbPath);
 }
 function getResearchDataDir(dbPath) {
@@ -580,7 +585,7 @@ function normalizeRunOptions(options) {
 }
 async function runResearchExperiment(options) {
   const normalized = normalizeRunOptions(options);
-  const persistence = createPersistence(normalized.dbPath);
+  const persistence = createPersistence$1(normalized.dbPath);
   const queue = new TaskQueue({
     concurrency: 1,
     defaultTimeout: normalized.budgetMs,
@@ -802,7 +807,7 @@ async function runResearchExperiment(options) {
   };
 }
 function listResearchSessions(limit = DEFAULT_SESSION_LIMIT, dbPath) {
-  const persistence = createPersistence(dbPath);
+  const persistence = createPersistence$1(dbPath);
   return persistence.listSessions(Math.max(limit * 5, 50)).filter((session) => session.metadata?.kind === RESEARCH_SESSION_KIND).slice(0, limit).map((session) => ({
     id: session.id,
     createdAt: session.createdAt,
@@ -821,7 +826,7 @@ function getLatestResearchSession(dbPath) {
   return listResearchSessions(1, dbPath)[0];
 }
 function getResearchSessionStatus(sessionId, dbPath) {
-  const persistence = createPersistence(dbPath);
+  const persistence = createPersistence$1(dbPath);
   const restored = persistence.restoreContext(sessionId);
   if (!restored) {
     return null;
@@ -926,6 +931,618 @@ function getResearchReport(sessionId, dbPath) {
   };
 }
 
+const DEFAULT_RESEARCH_PROGRAM_PATH = ".ccjk/research/program.md";
+const DEFAULT_RESEARCH_MAX_ROUNDS = 10;
+const DEFAULT_RESEARCH_MAX_NO_IMPROVE_ROUNDS = 3;
+const DEFAULT_RESEARCH_BUDGET_MS = 5 * 60 * 1e3;
+function normalizePositiveInteger(value, fallback) {
+  if (typeof value === "number" && Number.isInteger(value) && value > 0) {
+    return value;
+  }
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number.parseInt(value.trim(), 10);
+    if (Number.isInteger(parsed) && parsed > 0) {
+      return parsed;
+    }
+  }
+  return fallback;
+}
+function normalizeOptionalNumber(value) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number.parseFloat(value.trim());
+    if (Number.isFinite(parsed)) {
+      return parsed;
+    }
+  }
+  return void 0;
+}
+function normalizeObjective(value) {
+  return value === "maximize" || value === "minimize" || value === "auto" ? value : "auto";
+}
+function normalizeString(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  return trimmed || void 0;
+}
+function resolveResearchProgramPath(programPath, cwd) {
+  return programPath ? join(cwd || process.cwd(), programPath) : join(cwd || process.cwd(), DEFAULT_RESEARCH_PROGRAM_PATH);
+}
+function createDefaultResearchProgramTemplate(cwd) {
+  const workingDirectory = cwd || process.cwd();
+  return `---
+name: repo-research
+metric: test_pass_rate
+objective: maximize
+baselineCommand: pnpm test:run
+candidateCommand: pnpm test:run
+cwd: ${workingDirectory}
+maxRounds: ${DEFAULT_RESEARCH_MAX_ROUNDS}
+maxNoImproveRounds: ${DEFAULT_RESEARCH_MAX_NO_IMPROVE_ROUNDS}
+budgetMs: ${DEFAULT_RESEARCH_BUDGET_MS}
+targetMetric:
+---
+
+# Research Goal
+
+Describe the optimization target for this repository.
+
+## Guardrails
+
+- Keep changes scoped and measurable.
+- Prefer one candidate change per round.
+- Stop when the target metric is reached or repeated no-improvement rounds occur.
+
+## Notes
+
+Document hypotheses, constraints, and any files or modules that must not change.
+`;
+}
+function parseResearchProgram(content, programPath = DEFAULT_RESEARCH_PROGRAM_PATH) {
+  const parsed = matter(content);
+  const data = parsed.data || {};
+  const baselineCommand = normalizeString(data.baselineCommand);
+  if (!baselineCommand) {
+    throw new Error(`Missing required 'baselineCommand' in ${programPath}`);
+  }
+  const candidateCommand = normalizeString(data.candidateCommand);
+  if (!candidateCommand) {
+    throw new Error(`Missing required 'candidateCommand' in ${programPath}`);
+  }
+  return {
+    name: normalizeString(data.name) || "repo-research",
+    metric: normalizeString(data.metric),
+    objective: normalizeObjective(data.objective),
+    baselineCommand,
+    candidateCommand,
+    cwd: normalizeString(data.cwd) || process.cwd(),
+    maxRounds: normalizePositiveInteger(data.maxRounds, DEFAULT_RESEARCH_MAX_ROUNDS),
+    maxNoImproveRounds: normalizePositiveInteger(data.maxNoImproveRounds, DEFAULT_RESEARCH_MAX_NO_IMPROVE_ROUNDS),
+    budgetMs: normalizePositiveInteger(data.budgetMs, DEFAULT_RESEARCH_BUDGET_MS),
+    targetMetric: normalizeOptionalNumber(data.targetMetric),
+    notes: parsed.content.trim(),
+    programPath
+  };
+}
+function readResearchProgram(programPath, cwd) {
+  const resolvedPath = resolveResearchProgramPath(programPath, cwd);
+  const content = readFile(resolvedPath);
+  return parseResearchProgram(content, resolvedPath);
+}
+function initResearchProgram(programPath, cwd) {
+  const resolvedPath = resolveResearchProgramPath(programPath, cwd);
+  const content = createDefaultResearchProgramTemplate(cwd);
+  writeFile(resolvedPath, content);
+  return {
+    programPath: resolvedPath,
+    content
+  };
+}
+
+const RESEARCH_LOOP_SESSION_KIND = "research-loop";
+const DEFAULT_FAILURE_STREAK_LIMIT = 2;
+function createPersistence(dbPath) {
+  return new TaskPersistence(dbPath);
+}
+function toPositiveInteger(value, fallback) {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : fallback;
+}
+function toOptionalFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function applyProgramOverrides(program, overrides = {}) {
+  return {
+    ...program,
+    cwd: overrides.cwd || program.cwd,
+    budgetMs: toPositiveInteger(overrides.budgetMs, program.budgetMs),
+    maxRounds: toPositiveInteger(overrides.maxRounds, program.maxRounds),
+    maxNoImproveRounds: toPositiveInteger(overrides.maxNoImproveRounds, program.maxNoImproveRounds),
+    targetMetric: toOptionalFiniteNumber(overrides.targetMetric) ?? program.targetMetric
+  };
+}
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function toObjective(value, metricName) {
+  if (value === "maximize" || value === "minimize") {
+    return value;
+  }
+  const normalized = (metricName || "").toLowerCase();
+  if (!normalized) {
+    return "maximize";
+  }
+  const lowerIsBetter = ["loss", "error", "bpb", "perplexity", "ppl", "latency", "duration", "time", "cost", "price", "wer", "cer"];
+  return lowerIsBetter.some((keyword) => normalized.includes(keyword)) ? "minimize" : "maximize";
+}
+function isAcceptedResult(result) {
+  return result.verdict === "PASS";
+}
+function cloneLoopMetadata(metadata, patch = {}) {
+  return {
+    ...metadata,
+    ...patch,
+    acceptedRoundSessionIds: patch.acceptedRoundSessionIds || [...metadata.acceptedRoundSessionIds],
+    rejectedRoundSessionIds: patch.rejectedRoundSessionIds || [...metadata.rejectedRoundSessionIds],
+    roundSessionIds: patch.roundSessionIds || [...metadata.roundSessionIds],
+    updatedAt: patch.updatedAt || nowIso()
+  };
+}
+function ensureLoopMetadata(raw, sessionId) {
+  const createdAt = typeof raw.createdAt === "string" && raw.createdAt ? raw.createdAt : nowIso();
+  return {
+    kind: "research-loop",
+    name: typeof raw.name === "string" && raw.name ? raw.name : sessionId,
+    programPath: typeof raw.programPath === "string" ? raw.programPath : ".ccjk/research/program.md",
+    metric: typeof raw.metric === "string" && raw.metric ? raw.metric : void 0,
+    objective: raw.objective === "maximize" || raw.objective === "minimize" || raw.objective === "auto" ? raw.objective : "auto",
+    cwd: typeof raw.cwd === "string" && raw.cwd ? raw.cwd : process.cwd(),
+    budgetMs: toPositiveInteger(raw.budgetMs, 5 * 60 * 1e3),
+    maxRounds: toPositiveInteger(raw.maxRounds, 10),
+    maxNoImproveRounds: toPositiveInteger(raw.maxNoImproveRounds, 3),
+    targetMetric: typeof raw.targetMetric === "number" && Number.isFinite(raw.targetMetric) ? raw.targetMetric : void 0,
+    status: raw.status === "running" || raw.status === "stopped" || raw.status === "completed" || raw.status === "failed" ? raw.status : "running",
+    baselineSessionId: typeof raw.baselineSessionId === "string" && raw.baselineSessionId ? raw.baselineSessionId : void 0,
+    currentRound: toPositiveInteger(raw.currentRound, 0) - 1 >= 0 ? toPositiveInteger(raw.currentRound, 0) : 0,
+    bestSessionId: typeof raw.bestSessionId === "string" && raw.bestSessionId ? raw.bestSessionId : void 0,
+    bestMetricValue: typeof raw.bestMetricValue === "number" && Number.isFinite(raw.bestMetricValue) ? raw.bestMetricValue : void 0,
+    acceptedRoundSessionIds: Array.isArray(raw.acceptedRoundSessionIds) ? raw.acceptedRoundSessionIds.filter((value) => typeof value === "string") : [],
+    rejectedRoundSessionIds: Array.isArray(raw.rejectedRoundSessionIds) ? raw.rejectedRoundSessionIds.filter((value) => typeof value === "string") : [],
+    roundSessionIds: Array.isArray(raw.roundSessionIds) ? raw.roundSessionIds.filter((value) => typeof value === "string") : [],
+    noImproveStreak: typeof raw.noImproveStreak === "number" && raw.noImproveStreak >= 0 ? raw.noImproveStreak : 0,
+    failureStreak: typeof raw.failureStreak === "number" && raw.failureStreak >= 0 ? raw.failureStreak : 0,
+    stopReason: raw.stopReason,
+    createdAt,
+    updatedAt: typeof raw.updatedAt === "string" && raw.updatedAt ? raw.updatedAt : createdAt,
+    lastRoundSessionId: typeof raw.lastRoundSessionId === "string" && raw.lastRoundSessionId ? raw.lastRoundSessionId : void 0,
+    notes: typeof raw.notes === "string" && raw.notes ? raw.notes : void 0
+  };
+}
+function getLoopSessionRecord(sessionId, dbPath) {
+  const persistence = createPersistence(dbPath);
+  const session = persistence.getSession(sessionId);
+  if (!session || session.metadata?.kind !== RESEARCH_LOOP_SESSION_KIND) {
+    return null;
+  }
+  return {
+    id: session.id,
+    createdAt: session.createdAt,
+    updatedAt: session.updatedAt,
+    metadata: ensureLoopMetadata(session.metadata, session.id)
+  };
+}
+function getLatestLoopSession(dbPath) {
+  const persistence = createPersistence(dbPath);
+  const session = persistence.listSessions(100).find((item) => item.metadata?.kind === RESEARCH_LOOP_SESSION_KIND);
+  if (!session) {
+    return null;
+  }
+  return {
+    id: session.id,
+    createdAt: session.createdAt,
+    metadata: ensureLoopMetadata(session.metadata, session.id)
+  };
+}
+function getResolvedLoopSessionId(sessionId, dbPath) {
+  return sessionId || getLatestLoopSession(dbPath)?.id;
+}
+function saveLoopMetadata(sessionId, metadata, dbPath) {
+  const persistence = createPersistence(dbPath);
+  const normalized = ensureLoopMetadata({ ...metadata, updatedAt: nowIso() }, sessionId);
+  persistence.saveSession(sessionId, normalized);
+  return normalized;
+}
+function buildRoundRecord(round, result) {
+  return {
+    round,
+    sessionId: result.sessionId,
+    name: result.name,
+    status: result.status,
+    verdict: result.verdict,
+    metricName: result.metricName,
+    metricValue: result.metricValue,
+    accepted: isAcceptedResult(result),
+    objective: result.objective,
+    command: result.command,
+    reason: result.verdictReason,
+    baselineSessionId: result.baselineSessionId,
+    comparison: result.comparison,
+    createdAt: result.createdAt
+  };
+}
+function getRoundRecords(metadata, dbPath) {
+  return metadata.roundSessionIds.map((sessionId, index) => {
+    const report = getResearchReport(sessionId, dbPath);
+    if (!report) {
+      return null;
+    }
+    const record = {
+      round: index + 1,
+      sessionId,
+      name: report.name,
+      status: report.status,
+      verdict: report.verdict,
+      metricName: report.metricName,
+      metricValue: report.metricValue,
+      accepted: metadata.acceptedRoundSessionIds.includes(sessionId),
+      objective: report.objective || toObjective(metadata.objective, metadata.metric),
+      command: report.command,
+      reason: report.verdictReason,
+      baselineSessionId: report.baselineSessionId,
+      comparison: report.comparison,
+      createdAt: report.createdAt
+    };
+    return record;
+  }).filter((value) => value !== null);
+}
+function isTargetReached(metricValue, objective, targetMetric) {
+  if (metricValue === void 0 || targetMetric === void 0) {
+    return false;
+  }
+  return objective === "minimize" ? metricValue <= targetMetric : metricValue >= targetMetric;
+}
+function evaluateLoopStopCondition(input) {
+  const objective = toObjective(input.metadata.objective, input.metadata.metric);
+  if (input.metadata.status === "completed" || input.metadata.status === "failed") {
+    return { shouldStop: true, reason: input.metadata.stopReason, status: input.metadata.status };
+  }
+  if (input.metadata.status === "stopped") {
+    return { shouldStop: true, reason: input.metadata.stopReason || "manual-stop", status: "stopped" };
+  }
+  if (input.phase === "baseline" && input.latestResult && !input.latestResult.success) {
+    return { shouldStop: true, reason: "baseline-failed", status: "failed" };
+  }
+  if (input.metadata.currentRound >= input.program.maxRounds) {
+    return { shouldStop: true, reason: "max-rounds-reached", status: "completed" };
+  }
+  if (input.metadata.noImproveStreak >= input.program.maxNoImproveRounds) {
+    return { shouldStop: true, reason: "max-no-improve-rounds-reached", status: "completed" };
+  }
+  if (isTargetReached(input.metadata.bestMetricValue, objective, input.program.targetMetric)) {
+    return { shouldStop: true, reason: "target-metric-reached", status: "completed" };
+  }
+  if (input.phase === "round" && input.metadata.failureStreak >= DEFAULT_FAILURE_STREAK_LIMIT) {
+    return { shouldStop: true, reason: "candidate-failed-repeatedly", status: "failed" };
+  }
+  return { shouldStop: false };
+}
+function createLoopSession(program, dbPath) {
+  const sessionId = `research-loop-${Date.now()}-${nanoid(6)}`;
+  const createdAt = nowIso();
+  const metadata = {
+    kind: "research-loop",
+    name: program.name,
+    programPath: program.programPath,
+    metric: program.metric,
+    objective: program.objective,
+    cwd: program.cwd,
+    budgetMs: program.budgetMs,
+    maxRounds: program.maxRounds,
+    maxNoImproveRounds: program.maxNoImproveRounds,
+    targetMetric: program.targetMetric,
+    status: "running",
+    baselineSessionId: void 0,
+    currentRound: 0,
+    bestSessionId: void 0,
+    bestMetricValue: void 0,
+    acceptedRoundSessionIds: [],
+    rejectedRoundSessionIds: [],
+    roundSessionIds: [],
+    noImproveStreak: 0,
+    failureStreak: 0,
+    createdAt,
+    updatedAt: createdAt,
+    notes: program.notes
+  };
+  return {
+    sessionId,
+    metadata: saveLoopMetadata(sessionId, metadata, dbPath)
+  };
+}
+async function ensureBaseline(sessionId, metadata, program, dbPath) {
+  if (metadata.baselineSessionId) {
+    const report = getResearchReport(metadata.baselineSessionId, dbPath);
+    if (report) {
+      return {
+        metadata,
+        baseline: {
+          sessionId: report.sessionId,
+          taskId: "",
+          name: report.name,
+          command: report.command,
+          cwd: report.cwd,
+          metricName: report.metricName,
+          metricValue: report.metricValue,
+          success: report.status === "completed",
+          status: report.status,
+          exitCode: report.exitCode,
+          stdout: "",
+          stderr: "",
+          durationMs: report.durationMs,
+          phase: "baseline",
+          objective: report.objective || toObjective(program.objective, program.metric),
+          verdict: report.verdict,
+          verdictReason: report.verdictReason,
+          baselineSessionId: report.baselineSessionId,
+          comparison: report.comparison,
+          phaseHistory: report.phaseHistory,
+          createdAt: report.createdAt
+        }
+      };
+    }
+  }
+  const baseline = await runResearchExperiment({
+    name: `${program.name}-baseline`,
+    command: program.baselineCommand,
+    metricName: program.metric,
+    budgetMs: program.budgetMs,
+    cwd: program.cwd,
+    objective: program.objective,
+    dbPath
+  });
+  const nextMetadata = cloneLoopMetadata(metadata, {
+    baselineSessionId: baseline.sessionId,
+    bestSessionId: baseline.sessionId,
+    bestMetricValue: baseline.metricValue,
+    failureStreak: baseline.success ? 0 : metadata.failureStreak + 1
+  });
+  return {
+    metadata: saveLoopMetadata(sessionId, nextMetadata, dbPath),
+    baseline
+  };
+}
+async function executeResearchRound(sessionId, metadata, program, dbPath) {
+  const roundNumber = metadata.currentRound + 1;
+  const baselineSessionId = metadata.bestSessionId || metadata.baselineSessionId;
+  const result = await runResearchExperiment({
+    name: `${program.name}-round-${roundNumber}`,
+    command: program.candidateCommand,
+    metricName: program.metric,
+    budgetMs: program.budgetMs,
+    cwd: program.cwd,
+    objective: program.objective,
+    baselineSessionId,
+    dbPath
+  });
+  const accepted = isAcceptedResult(result);
+  const acceptedRoundSessionIds = accepted ? [...metadata.acceptedRoundSessionIds, result.sessionId] : [...metadata.acceptedRoundSessionIds];
+  const rejectedRoundSessionIds = accepted ? [...metadata.rejectedRoundSessionIds] : [...metadata.rejectedRoundSessionIds, result.sessionId];
+  const bestSessionId = accepted ? result.sessionId : metadata.bestSessionId;
+  const bestMetricValue = accepted ? result.metricValue : metadata.bestMetricValue;
+  const nextMetadata = cloneLoopMetadata(metadata, {
+    currentRound: roundNumber,
+    bestSessionId,
+    bestMetricValue,
+    roundSessionIds: [...metadata.roundSessionIds, result.sessionId],
+    acceptedRoundSessionIds,
+    rejectedRoundSessionIds,
+    noImproveStreak: accepted ? 0 : metadata.noImproveStreak + 1,
+    failureStreak: result.success ? 0 : metadata.failureStreak + 1,
+    lastRoundSessionId: result.sessionId
+  });
+  return {
+    metadata: saveLoopMetadata(sessionId, nextMetadata, dbPath),
+    result,
+    round: buildRoundRecord(roundNumber, result)
+  };
+}
+function getResearchLoopStatusInternal(sessionId, dbPath) {
+  const loopSession = getLoopSessionRecord(sessionId, dbPath);
+  if (!loopSession) {
+    return null;
+  }
+  const baselineReport = loopSession.metadata.baselineSessionId ? getResearchReport(loopSession.metadata.baselineSessionId, dbPath) : null;
+  const rounds = getRoundRecords(loopSession.metadata, dbPath);
+  return {
+    sessionId,
+    metadata: loopSession.metadata,
+    baseline: baselineReport ? {
+      sessionId: baselineReport.sessionId,
+      taskId: "",
+      name: baselineReport.name,
+      command: baselineReport.command,
+      cwd: baselineReport.cwd,
+      metricName: baselineReport.metricName,
+      metricValue: baselineReport.metricValue,
+      success: baselineReport.status === "completed",
+      status: baselineReport.status,
+      exitCode: baselineReport.exitCode,
+      stdout: "",
+      stderr: "",
+      durationMs: baselineReport.durationMs,
+      phase: "baseline",
+      objective: baselineReport.objective || toObjective(loopSession.metadata.objective, loopSession.metadata.metric),
+      verdict: baselineReport.verdict,
+      verdictReason: baselineReport.verdictReason,
+      baselineSessionId: baselineReport.baselineSessionId,
+      comparison: baselineReport.comparison,
+      phaseHistory: baselineReport.phaseHistory,
+      createdAt: baselineReport.createdAt
+    } : null,
+    latestRound: rounds[rounds.length - 1],
+    rounds
+  };
+}
+async function startResearchLoop(options = {}) {
+  const program = applyProgramOverrides(readResearchProgram(options.programPath, options.cwd), options.overrides);
+  const { sessionId } = createLoopSession(program, options.dbPath);
+  return await resumeResearchLoop({ ...options, sessionId });
+}
+async function runResearchRound(options = {}) {
+  const resolvedSessionId = getResolvedLoopSessionId(options.sessionId, options.dbPath);
+  if (!resolvedSessionId) {
+    throw new Error("No research loop session found.");
+  }
+  const loopSession = getLoopSessionRecord(resolvedSessionId, options.dbPath);
+  if (!loopSession) {
+    throw new Error(`Research loop session not found: ${resolvedSessionId}`);
+  }
+  const program = applyProgramOverrides(readResearchProgram(loopSession.metadata.programPath, options.cwd), options.overrides);
+  let metadata = saveLoopMetadata(resolvedSessionId, cloneLoopMetadata(loopSession.metadata, { status: "running", stopReason: void 0 }), options.dbPath);
+  const baselineState = await ensureBaseline(resolvedSessionId, metadata, program, options.dbPath);
+  metadata = baselineState.metadata;
+  const stopAfterBaseline = evaluateLoopStopCondition({ metadata, latestResult: baselineState.baseline, program, phase: "baseline" });
+  if (stopAfterBaseline.shouldStop) {
+    metadata = saveLoopMetadata(resolvedSessionId, cloneLoopMetadata(metadata, {
+      status: stopAfterBaseline.status || metadata.status,
+      stopReason: stopAfterBaseline.reason
+    }), options.dbPath);
+    return getResearchLoopStatusInternal(resolvedSessionId, options.dbPath);
+  }
+  const roundState = await executeResearchRound(resolvedSessionId, metadata, program, options.dbPath);
+  metadata = roundState.metadata;
+  const stopState = evaluateLoopStopCondition({ metadata, latestResult: roundState.result, program, phase: "round" });
+  if (stopState.shouldStop) {
+    metadata = saveLoopMetadata(resolvedSessionId, cloneLoopMetadata(metadata, {
+      status: stopState.status || metadata.status,
+      stopReason: stopState.reason
+    }), options.dbPath);
+  }
+  return getResearchLoopStatusInternal(resolvedSessionId, options.dbPath);
+}
+async function resumeResearchLoop(options = {}) {
+  const resolvedSessionId = getResolvedLoopSessionId(options.sessionId, options.dbPath);
+  if (!resolvedSessionId) {
+    throw new Error("No research loop session found.");
+  }
+  const loopSession = getLoopSessionRecord(resolvedSessionId, options.dbPath);
+  if (!loopSession) {
+    throw new Error(`Research loop session not found: ${resolvedSessionId}`);
+  }
+  const program = applyProgramOverrides(readResearchProgram(loopSession.metadata.programPath, options.cwd), options.overrides);
+  let metadata = saveLoopMetadata(resolvedSessionId, cloneLoopMetadata(loopSession.metadata, {
+    status: loopSession.metadata.status === "completed" || loopSession.metadata.status === "failed" ? loopSession.metadata.status : "running",
+    stopReason: loopSession.metadata.status === "stopped" ? void 0 : loopSession.metadata.stopReason
+  }), options.dbPath);
+  const baselineState = await ensureBaseline(resolvedSessionId, metadata, program, options.dbPath);
+  metadata = baselineState.metadata;
+  while (true) {
+    const stopBeforeRound = evaluateLoopStopCondition({ metadata, program });
+    if (stopBeforeRound.shouldStop) {
+      metadata = saveLoopMetadata(resolvedSessionId, cloneLoopMetadata(metadata, {
+        status: stopBeforeRound.status || metadata.status,
+        stopReason: stopBeforeRound.reason
+      }), options.dbPath);
+      return getResearchLoopStatusInternal(resolvedSessionId, options.dbPath);
+    }
+    const roundState = await executeResearchRound(resolvedSessionId, metadata, program, options.dbPath);
+    metadata = roundState.metadata;
+    const stopAfterRound = evaluateLoopStopCondition({ metadata, latestResult: roundState.result, program, phase: "round" });
+    if (stopAfterRound.shouldStop) {
+      metadata = saveLoopMetadata(resolvedSessionId, cloneLoopMetadata(metadata, {
+        status: stopAfterRound.status || metadata.status,
+        stopReason: stopAfterRound.reason || "resume-complete"
+      }), options.dbPath);
+      return getResearchLoopStatusInternal(resolvedSessionId, options.dbPath);
+    }
+  }
+}
+function stopResearchLoop(options = {}) {
+  const resolvedSessionId = getResolvedLoopSessionId(options.sessionId, options.dbPath);
+  if (!resolvedSessionId) {
+    return null;
+  }
+  const loopSession = getLoopSessionRecord(resolvedSessionId, options.dbPath);
+  if (!loopSession) {
+    return null;
+  }
+  saveLoopMetadata(resolvedSessionId, cloneLoopMetadata(loopSession.metadata, {
+    status: "stopped",
+    stopReason: "manual-stop"
+  }), options.dbPath);
+  return getResearchLoopStatusInternal(resolvedSessionId, options.dbPath);
+}
+function getResearchLoopStatus(sessionId, dbPath) {
+  const resolvedSessionId = getResolvedLoopSessionId(sessionId, dbPath);
+  if (!resolvedSessionId) {
+    return null;
+  }
+  return getResearchLoopStatusInternal(resolvedSessionId, dbPath);
+}
+function getResearchLoopReport(sessionId, dbPath) {
+  const status = getResearchLoopStatus(sessionId, dbPath);
+  if (!status) {
+    return null;
+  }
+  const lines = [];
+  lines.push("# CCJK Research Loop Report");
+  lines.push("");
+  lines.push(`**Session**: ${status.sessionId}`);
+  lines.push(`**Name**: ${status.metadata.name}`);
+  lines.push(`**Status**: ${status.metadata.status}`);
+  lines.push(`**Stop Reason**: ${status.metadata.stopReason || "running"}`);
+  lines.push(`**Rounds**: ${status.metadata.currentRound}/${status.metadata.maxRounds}`);
+  lines.push(`**No-Improve Streak**: ${status.metadata.noImproveStreak}/${status.metadata.maxNoImproveRounds}`);
+  lines.push(`**Metric**: ${status.metadata.metric || "not configured"}`);
+  lines.push(`**Objective**: ${status.metadata.objective}`);
+  lines.push(`**Target Metric**: ${status.metadata.targetMetric ?? "not configured"}`);
+  lines.push(`**Best Session**: ${status.metadata.bestSessionId || "none"}`);
+  lines.push(`**Best Metric**: ${status.metadata.bestMetricValue ?? "not found"}`);
+  lines.push(`**Created**: ${status.metadata.createdAt}`);
+  lines.push(`**Updated**: ${status.metadata.updatedAt}`);
+  if (status.baseline) {
+    lines.push("");
+    lines.push("## Baseline");
+    lines.push("");
+    lines.push(`- Session: ${status.baseline.sessionId}`);
+    lines.push(`- Verdict: ${status.baseline.verdict}`);
+    lines.push(`- Metric: ${status.baseline.metricName ? `${status.baseline.metricName}=${status.baseline.metricValue ?? "not found"}` : "not configured"}`);
+    lines.push(`- Reason: ${status.baseline.verdictReason}`);
+  }
+  if (status.rounds.length > 0) {
+    lines.push("");
+    lines.push("## Rounds");
+    lines.push("");
+    for (const round of status.rounds) {
+      lines.push(`- Round ${round.round}: ${round.sessionId} \xB7 ${round.verdict} \xB7 ${round.metricName ? `${round.metricName}=${round.metricValue ?? "not found"}` : "no metric"} \xB7 ${round.accepted ? "accepted" : "rejected"}`);
+    }
+  }
+  return {
+    sessionId: status.sessionId,
+    name: status.metadata.name,
+    status: status.metadata.status,
+    stopReason: status.metadata.stopReason,
+    currentRound: status.metadata.currentRound,
+    maxRounds: status.metadata.maxRounds,
+    noImproveStreak: status.metadata.noImproveStreak,
+    maxNoImproveRounds: status.metadata.maxNoImproveRounds,
+    acceptedRounds: status.metadata.acceptedRoundSessionIds.length,
+    rejectedRounds: status.metadata.rejectedRoundSessionIds.length,
+    bestSessionId: status.metadata.bestSessionId,
+    bestMetricValue: status.metadata.bestMetricValue,
+    metric: status.metadata.metric,
+    objective: status.metadata.objective,
+    targetMetric: status.metadata.targetMetric,
+    baselineSessionId: status.metadata.baselineSessionId,
+    createdAt: status.metadata.createdAt,
+    updatedAt: status.metadata.updatedAt,
+    content: lines.join("\n")
+  };
+}
+
 function printDivider() {
   console.log(a.dim("\u2500".repeat(60)));
 }
@@ -958,11 +1575,56 @@ function getLatestTaskData(status) {
   const latestTask = status.tasks[status.tasks.length - 1];
   return latestTask?.output?.data || {};
 }
+function getLoopOverrides(options) {
+  return {
+    cwd: options.cwd,
+    budgetMs: options.budgetMs,
+    maxRounds: options.maxRounds,
+    maxNoImproveRounds: options.maxNoImproveRounds,
+    targetMetric: options.targetMetric
+  };
+}
+function printResearchLoopStatus(status) {
+  console.log("");
+  console.log(a.bold.cyan("\u{1F501} Research Loop Status"));
+  printDivider();
+  console.log(a.gray(`Session:   ${status.sessionId}`));
+  console.log(a.gray(`Name:      ${status.metadata.name}`));
+  console.log(a.gray(`Status:    ${status.metadata.status}`));
+  console.log(a.gray(`Stop:      ${status.metadata.stopReason || "running"}`));
+  console.log(a.gray(`Rounds:    ${status.metadata.currentRound}/${status.metadata.maxRounds}`));
+  console.log(a.gray(`Objective: ${status.metadata.objective}`));
+  console.log(a.gray(`Metric:    ${formatMetric(status.metadata.metric, status.metadata.bestMetricValue)}`));
+  console.log(a.gray(`Baseline:  ${status.metadata.baselineSessionId || "none"}`));
+  console.log(a.gray(`Best:      ${status.metadata.bestSessionId || "none"}`));
+  console.log(a.gray(`Accepted:  ${status.metadata.acceptedRoundSessionIds.length}`));
+  console.log(a.gray(`Rejected:  ${status.metadata.rejectedRoundSessionIds.length}`));
+  console.log(a.gray(`Streak:    ${status.metadata.noImproveStreak}/${status.metadata.maxNoImproveRounds}`));
+  if (status.latestRound) {
+    console.log(a.gray(`Latest:    round ${status.latestRound.round} \xB7 ${status.latestRound.verdict} \xB7 ${formatMetric(status.latestRound.metricName, status.latestRound.metricValue)}`));
+  }
+  console.log("");
+}
 async function researchCommand(action, args = [], options = {}) {
   switch (action) {
     case "run":
       await runResearchCommand(options);
       return;
+    case "init":
+      await initResearchCommand(options);
+      return;
+    case "loop":
+      await startResearchLoopCommand(options);
+      return;
+    case "round":
+      await runResearchRoundCommand(args[0] || void 0, options);
+      return;
+    case "resume":
+      await resumeResearchLoopCommand(args[0] || void 0, options);
+      return;
+    case "stop":
+      await stopResearchLoopCommand(args[0] || void 0, options);
+      return;
     case "status":
       await showResearchStatus(args[0] || void 0, options);
       return;
@@ -1033,7 +1695,56 @@ async function runResearchCommand(options) {
   }
   console.log("");
 }
+async function initResearchCommand(options) {
+  const { programPath } = initResearchProgram(options.program, options.cwd);
+  console.log("");
+  console.log(a.bold.cyan("\u{1F9ED} Research Program"));
+  printDivider();
+  console.log(a.gray(`Program:   ${programPath}`));
+  console.log("");
+}
+async function startResearchLoopCommand(options) {
+  const status = await startResearchLoop({
+    programPath: options.program,
+    cwd: options.cwd,
+    dbPath: options.dbPath,
+    overrides: getLoopOverrides(options)
+  });
+  printResearchLoopStatus(status);
+}
+async function runResearchRoundCommand(sessionId, options) {
+  const status = await runResearchRound({
+    sessionId,
+    cwd: options.cwd,
+    dbPath: options.dbPath,
+    overrides: getLoopOverrides(options)
+  });
+  printResearchLoopStatus(status);
+}
+async function resumeResearchLoopCommand(sessionId, options) {
+  const status = await resumeResearchLoop({
+    sessionId,
+    cwd: options.cwd,
+    dbPath: options.dbPath,
+    overrides: getLoopOverrides(options)
+  });
+  printResearchLoopStatus(status);
+}
+async function stopResearchLoopCommand(sessionId, options) {
+  const status = stopResearchLoop({ sessionId, dbPath: options.dbPath });
+  if (!status) {
+    console.log(a.yellow(sessionId ? `Research loop session not found: ${sessionId}` : "No research loop sessions found."));
+    console.log("");
+    return;
+  }
+  printResearchLoopStatus(status);
+}
 async function showResearchStatus(sessionId, options) {
+  const loopStatus = getResearchLoopStatus(sessionId, options.dbPath);
+  if (loopStatus) {
+    printResearchLoopStatus(loopStatus);
+    return;
+  }
   const resolvedSessionId = sessionId || getLatestResearchSession(options.dbPath)?.id;
   if (!resolvedSessionId) {
     console.log(a.yellow("No research sessions found."));
@@ -1128,6 +1839,15 @@ async function showResearchResults(options) {
   console.log("");
 }
 async function showResearchReport(sessionId, options) {
+  const loopReport = getResearchLoopReport(sessionId, options.dbPath);
+  if (loopReport) {
+    console.log("");
+    console.log(a.bold.cyan("\u{1F4DD} Research Loop Report"));
+    printDivider();
+    console.log(loopReport.content);
+    console.log("");
+    return;
+  }
   const report = getResearchReport(sessionId, options.dbPath);
   if (!report) {
     console.log(a.yellow(sessionId ? `Research session not found: ${sessionId}` : "No research sessions found."));
@@ -1162,14 +1882,21 @@ function showResearchHelp() {
   console.log("");
   console.log(a.bold.cyan("ccjk research"));
   printDivider();
+  console.log("  init     Create a research program template");
+  console.log("  loop     Start a persisted research loop");
+  console.log("  round    Run one candidate round for a loop");
+  console.log("  resume   Continue a persisted research loop until stop");
+  console.log("  stop     Stop a running research loop");
   console.log("  run      Run a persisted research experiment with optional baseline comparison");
   console.log("  status   Show the latest or selected research session status");
   console.log("  sessions List recent research sessions");
   console.log("  results  Show recent result rows and the current best run");
   console.log("  report   Render a compact persisted research report");
   console.log("");
+  console.log(a.dim("Example: ccjk research init"));
+  console.log(a.dim("Example: ccjk research loop --program .ccjk/research/program.md"));
+  console.log(a.dim("Example: ccjk research round research-loop-123"));
   console.log(a.dim('Example: ccjk research run --name baseline --cmd "python train.py" --metric val_bpb --objective minimize'));
-  console.log(a.dim('Example: ccjk research run --name candidate --cmd "python train.py --lr 1e-4" --metric val_bpb --baseline research-123'));
   console.log(a.dim("Example: ccjk research report research-123"));
   console.log("");
 }