@syntax-syllogism/aloop 0.6.2 → 0.8.1

package/src/config.mjs

@@ -1,3 +1,6 @@
+/** @typedef {import('./types.js').Config} Config */
+/** @typedef {import('./types.js').PhaseDescriptor} PhaseDescriptor */
+
 import { access } from 'node:fs/promises';
 import { constants } from 'node:fs';
 import { join, resolve } from 'node:path';
@@ -184,6 +187,7 @@ function toPhase(entry, index) {
  * A custom verdict phase must declare its own `repair` list; merely placing a
  * repair phase after it no longer changes control flow.
  */
+/** @returns {PhaseDescriptor[]} */
 export function normalizePhases(entries, { maxRounds }) {
   const list = entries.map(toPhase);
   const phaseIndexes = new Map();
@@ -215,7 +219,7 @@ export function normalizePhases(entries, { maxRounds }) {
 
   for (let index = 0; index < list.length; index += 1) {
     const phase = list[index];
-    if (!phase.verdict) continue;
+    if (!phase.verdict && !(phase.kind === 'gate' && phase.repair)) continue;
     const repair = phase.repair ?? [];
     if (!Array.isArray(repair)) {
       throw new Error(`Phase "${phase.name}" has an invalid repair transition; expected an array.`);
@@ -233,7 +237,7 @@ export function normalizePhases(entries, { maxRounds }) {
   for (let index = 0; index < list.length; index += 1) {
     const phase = list[index];
     if (phase.role === 'repair' && !consumedRepairs.has(index)) {
-      throw new Error(`Phase "${phase.name}" is a repair phase and must be declared by a phase that emits a verdict.`);
+      throw new Error(`Phase "${phase.name}" is a repair phase and must be declared by a phase that emits a verdict or gate repair transition.`);
     }
     if (!consumedRepairs.has(index)) result.push(phase);
   }
@@ -356,6 +360,7 @@ export async function loadRunsDir(cwd, configPath) {
   return runsDir;
 }
 
+/** @returns {Promise<Config>} */
 export async function loadConfig(cwd, overrides = {}, configPath) {
   const configured = await importConfigFile(cwd, configPath);
   const merged = {

package/src/eval.mjs

@@ -0,0 +1,217 @@
+/** @typedef {import('./types.js').Summary} Summary */
+
+import { execFile } from 'node:child_process';
+import { mkdir, mkdtemp, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { promisify } from 'node:util';
+import { computeRunMetrics, readRunManifest } from './metrics.mjs';
+import { runLoop } from './pipeline.mjs';
+
+const exec = promisify(execFile);
+
+/**
+ * A task corpus entry: a self-contained repo fixture plus a task description
+ * and (optionally) a held-out check that never appears in the visible gate.
+ * Escaped defects are the gap between what the gate/review approved and what
+ * the held-out check demands.
+ *
+ * @typedef {Object} EvalTask
+ * @property {string} id
+ * @property {Record<string, string>} [files] - initial repo contents, relative to the fixture root
+ * @property {string} [task] - inline task text written to the run's task file
+ * @property {string[]} [gate] - visible gate commands (what the loop enforces)
+ * @property {string[]} [heldOutCheck] - hidden verification commands run after approval
+ * @property {string[]} [phases] - phase list override (default: implement, gate, review)
+ */
+
+/**
+ * A matrix cell: a model/engine/config to run every task under. `configSource`
+ * gives full control over the generated `loop.config.mjs` (needed for custom
+ * adapters, e.g. a fake engine in tests); when omitted, a minimal config is
+ * generated from `engine`, `phases`, and `configExtra`.
+ *
+ * @typedef {Object} EvalConfig
+ * @property {string} name
+ * @property {string} [engine]
+ * @property {string[]} [phases]
+ * @property {Record<string, unknown>} [configExtra]
+ * @property {((task: EvalTask) => string)|string} [configSource]
+ * @property {Record<string, unknown>} [runArgs]
+ */
+
+async function git(cwd, ...args) {
+  return (await exec('git', args, { cwd })).stdout.trim();
+}
+
+async function writeTaskFiles(root, files) {
+  for (const [relPath, contents] of Object.entries(files ?? {})) {
+    const full = join(root, relPath);
+    await mkdir(dirname(full), { recursive: true });
+    await writeFile(full, contents);
+  }
+}
+
+async function runShellChecks(cwd, commands) {
+  for (const command of commands ?? []) {
+    try {
+      await exec('sh', ['-c', command], { cwd });
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}
+
+function defaultConfigSource(task, config) {
+  const body = {
+    gate: task.gate ?? [],
+    worktrees: false,
+    phases: config.phases ?? task.phases ?? ['implement', 'gate', 'review'],
+    engines: { default: config.engine ?? 'claude' },
+    ...(config.configExtra ?? {}),
+  };
+  return `export default ${JSON.stringify(body, null, 2)};\n`;
+}
+
+function resolveConfigSource(task, config) {
+  if (typeof config.configSource === 'function') return config.configSource(task);
+  if (typeof config.configSource === 'string') return config.configSource;
+  return defaultConfigSource(task, config);
+}
+
+/**
+ * Run one task through the loop under one config, in a throwaway repo, and
+ * report completion, escaped defects (via the held-out check), convergence,
+ * cost, and time — reading cost/convergence from the run's own manifest so the
+ * numbers are exactly what {@link computeRunMetrics} would report for a single
+ * real run.
+ *
+ * @param {{ task: EvalTask, config: EvalConfig, baseDir?: string }} options
+ */
+export async function runEvalCell({ task, config, baseDir }) {
+  const root = await mkdtemp(join(baseDir ?? tmpdir(), 'aloop-eval-'));
+  await git(root, 'init', '--initial-branch=master');
+  await git(root, 'config', 'user.email', 'eval@example.com');
+  await git(root, 'config', 'user.name', 'Eval Harness');
+  await writeTaskFiles(root, task.files);
+  // The loop writes its run state (manifest, logs, lock files) under .loop/
+  // inside the repo it's driving; without ignoring it, that bookkeeping shows
+  // up as untracked changes and trips the implement/review clean-tree check.
+  if (!task.files?.['.gitignore']) await writeFile(join(root, '.gitignore'), '.loop/\n');
+  await git(root, 'add', '.');
+  await git(root, 'commit', '-m', 'chore: init eval fixture');
+
+  await writeFile(join(root, 'loop.config.mjs'), resolveConfigSource(task, config));
+  const taskFile = join(root, 'TASK.md');
+  await writeFile(taskFile, task.task ?? '');
+
+  let summary = null;
+  let error = null;
+  try {
+    summary = await runLoop({ args: { taskFile, cwd: root, name: task.id, yes: true, ...(config.runArgs ?? {}) } });
+  } catch (caught) {
+    error = caught;
+  }
+
+  const completed = Boolean(summary && summary.stalled === null);
+  const manifest = summary ? await readRunManifest(summary.runDir) : null;
+  const metrics = manifest ? computeRunMetrics(manifest) : null;
+
+  let escapedDefect = null;
+  if (completed && task.heldOutCheck?.length) {
+    escapedDefect = !(await runShellChecks(summary.worktree, task.heldOutCheck));
+  }
+
+  const approvedSha = completed ? await git(summary.worktree, 'rev-parse', 'HEAD').catch(() => null) : null;
+
+  return {
+    task: task.id,
+    config: config.name,
+    completed,
+    stalled: summary?.stalled ?? null,
+    escapedDefect,
+    roundsToConverge: metrics?.convergence.roundsToConverge ?? null,
+    cost: metrics?.total.cost ?? null,
+    durationMs: metrics?.total.durationMs ?? null,
+    approvedSha,
+    runDir: summary?.runDir ?? null,
+    snapshotPath: summary ? join(summary.runDir, 'snapshot.json') : null,
+    error: error ? error.message : null,
+  };
+}
+
+/**
+ * Run every task × config cell in the matrix.
+ *
+ * @param {{ corpus: EvalTask[], matrix: EvalConfig[], baseDir?: string }} options
+ */
+export async function runEval({ corpus, matrix, baseDir }) {
+  const results = [];
+  for (const task of corpus) {
+    for (const config of matrix) {
+      results.push(await runEvalCell({ task, config, baseDir }));
+    }
+  }
+  return results;
+}
+
+/** Aggregate per-config totals across every task cell. */
+export function summarizeEval(results) {
+  const byConfig = new Map();
+  for (const cell of results) {
+    if (!byConfig.has(cell.config)) byConfig.set(cell.config, []);
+    byConfig.get(cell.config).push(cell);
+  }
+  return [...byConfig.entries()].map(([config, cells]) => {
+    const escapedChecked = cells.filter((cell) => cell.escapedDefect !== null);
+    const escaped = escapedChecked.filter((cell) => cell.escapedDefect).length;
+    const converged = cells.filter((cell) => cell.roundsToConverge !== null);
+    const costKnown = cells.length > 0 && cells.every((cell) => cell.cost !== null);
+    return {
+      config,
+      cells: cells.length,
+      completionRate: cells.length ? cells.filter((cell) => cell.completed).length / cells.length : null,
+      escapedDefectRate: escapedChecked.length ? escaped / escapedChecked.length : null,
+      avgRoundsToConverge: converged.length
+        ? converged.reduce((total, cell) => total + cell.roundsToConverge, 0) / converged.length
+        : null,
+      totalCost: costKnown ? cells.reduce((total, cell) => total + cell.cost, 0) : null,
+      totalDurationMs: cells.reduce((total, cell) => total + (cell.durationMs ?? 0), 0),
+    };
+  });
+}
+
+function fmt(value) {
+  return value === null || value === undefined ? 'unknown' : String(value);
+}
+
+/** Render per-cell results as a tab-separated table. */
+export function formatEvalTable(results) {
+  const header = ['TASK', 'CONFIG', 'COMPLETED', 'ESCAPED_DEFECT', 'ROUNDS', 'COST', 'DURATION_MS'];
+  const rows = results.map((cell) => [
+    cell.task,
+    cell.config,
+    String(cell.completed),
+    cell.escapedDefect === null ? 'n/a' : String(cell.escapedDefect),
+    fmt(cell.roundsToConverge),
+    fmt(cell.cost),
+    fmt(cell.durationMs),
+  ]);
+  return [header, ...rows].map((row) => row.join('\t')).join('\n');
+}
+
+/** Render per-config aggregate summaries as a tab-separated table. */
+export function formatEvalSummaryTable(summaries) {
+  const header = ['CONFIG', 'CELLS', 'COMPLETION_RATE', 'ESCAPED_DEFECT_RATE', 'AVG_ROUNDS', 'TOTAL_COST', 'TOTAL_DURATION_MS'];
+  const rows = summaries.map((summary) => [
+    summary.config,
+    String(summary.cells),
+    fmt(summary.completionRate),
+    fmt(summary.escapedDefectRate),
+    fmt(summary.avgRoundsToConverge),
+    fmt(summary.totalCost),
+    String(summary.totalDurationMs),
+  ]);
+  return [header, ...rows].map((row) => row.join('\t')).join('\n');
+}

package/src/index.mjs

@@ -23,5 +23,12 @@ export {
   cleanRuns,
   doctor,
 } from './operations.mjs';
+export {
+  runEval,
+  runEvalCell,
+  summarizeEval,
+  formatEvalTable,
+  formatEvalSummaryTable,
+} from './eval.mjs';
 export { githubBackend } from './publish.mjs';
 export { gitlabBackend, glabTransport, parseGitLabRemoteUrl } from './backends/gitlab.mjs';

package/src/manifest.mjs

@@ -1,3 +1,5 @@
+/** @typedef {import('./types.js').ManifestEntry} ManifestEntry */
+
 import { createHash } from 'node:crypto';
 import { rename, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
@@ -40,10 +42,12 @@ export function hashConfig(config) {
 }
 
 export class Manifest {
+  /** @param {ManifestEntry[]} [entries] */
   constructor(entries = []) {
     this.entries = [...entries];
   }
 
+  /** @param {ManifestEntry} entry @returns {ManifestEntry} */
   append(entry) {
     const now = new Date().toISOString();
     const recorded = {

package/src/operations.mjs

@@ -1,6 +1,6 @@
-import { access, readFile, readdir, rm, stat } from 'node:fs/promises';
+import { access, copyFile, mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
 import { constants } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { dirname, join, relative, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { adapterFor, agentForPhase } from './adapters.mjs';
 import { runCommand, signalProcessGroup } from './command.mjs';
@@ -8,9 +8,44 @@ import { defaults, loadConfig, loadRunsDir } from './config.mjs';
 import { GitFacade } from './git.mjs';
 import { computeAggregateMetrics, computeRunMetrics, readRunManifests } from './metrics.mjs';
 import { RunState, slugFor } from './state.mjs';
+import { packagePrompts } from './prompts.mjs';
 
 const PULL_REQUEST_URL = /https?:\/\/[^\s"'`<>]+(?:\/pull\/\d+|\/merge_requests\/\d+)[^\s"'`<>]*/i;
 
+const packagePresets = join(dirname(packagePrompts), 'presets');
+
+const CONFIG_HEADER = `// aloop configuration — see docs/loop.md for the full reference.
+//
+// REVIEW THESE before your first run:
+//   baseBranch     the branch you merge into (for example, 'main' or 'master')
+//   remote         set this when your repository has more than one remote
+//   engines        choose the agent that runs each phase
+//
+// SAFE TO CHANGE anytime:
+//   phases         the pipeline stages and their order
+//   gate           commands that must pass before review
+//   branchPrefix, maxRounds, timeoutMs
+//
+// Prompts live in .loop/prompts/ — edit any *.md there to change what each
+// phase tells the agent. Delete a file to fall back to the packaged default.
+`;
+
+const CONFIG_FOOTER = '// happy agentic looping :)\n';
+
+const EMBEDDED_STARTER = `export default {
+  baseBranch: 'master',   // <- set to your default branch
+  branchPrefix: 'feat/',
+  remote: null,           // <- set this if you have more than one remote
+  engines: {
+    default: { name: 'claude' },
+    // review: { name: 'codex' },  // optional: use a different reviewer
+  },
+  phases: ['implement', 'docs', 'gate', 'review', 'address', 'pr-description', 'publish'],
+  gate: [],               // <- e.g. ['npm test'] before review
+  maxRounds: 3,
+};
+`;
+
 async function readJson(path, { optional = true } = {}) {
   try {
     return JSON.parse(await readFile(path, 'utf8'));
@@ -417,7 +452,8 @@ async function operationalContext(cwd, configPath, { validate = false } = {}) {
   return { config, repoRoot, rootGit, runsDir: resolve(repoRoot, config.runsDir) };
 }
 
-export async function listRuns({ cwd = process.cwd(), configPath } = {}) {
+export async function listRuns(options = {}) {
+  const { cwd = process.cwd(), configPath } = /** @type {any} */ (options);
   const context = await operationalContext(cwd, configPath);
   let entries;
   try {
@@ -434,7 +470,8 @@ export async function listRuns({ cwd = process.cwd(), configPath } = {}) {
   return runs.sort((a, b) => (b.updatedAt ?? b.startedAt ?? '').localeCompare(a.updatedAt ?? a.startedAt ?? ''));
 }
 
-export async function getRun(name, { cwd = process.cwd(), configPath } = {}) {
+export async function getRun(name, options = {}) {
+  const { cwd = process.cwd(), configPath } = /** @type {any} */ (options);
   const slug = slugFor(name);
   if (!slug) throw new Error('A run name is required.');
   const context = await operationalContext(cwd, configPath);
@@ -453,7 +490,8 @@ export async function inspectRun(name, options = {}) {
   };
 }
 
-export async function cancelRun(name, { cwd = process.cwd(), configPath } = {}) {
+export async function cancelRun(name, options = {}) {
+  const { cwd = process.cwd(), configPath } = /** @type {any} */ (options);
   const context = await operationalContext(cwd, configPath);
   const slug = slugFor(name);
   if (!slug) throw new Error('A run name is required.');
@@ -570,7 +608,8 @@ async function stopProcesses(targets) {
   return waitForProcessesToStop(watched, 5000);
 }
 
-export async function cleanRuns({ cwd = process.cwd(), configPath, olderThanDays = 30, dryRun = false, yes = false } = {}) {
+export async function cleanRuns(options = {}) {
+  const { cwd = process.cwd(), configPath, olderThanDays = 30, dryRun = false, yes = false } = /** @type {any} */ (options);
   const context = await operationalContext(cwd, configPath);
   const runs = await listRuns({ cwd, configPath });
   const cutoff = Date.now() - olderThanDays * 24 * 60 * 60 * 1000;
@@ -603,6 +642,79 @@ export async function cleanRuns({ cwd = process.cwd(), configPath, olderThanDays
   };
 }
 
+async function promptFilesIn(directory) {
+  const entries = await readdir(directory, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
+    .map((entry) => entry.name)
+    .sort();
+}
+
+async function bundledPresets() {
+  const entries = await readdir(packagePresets, { withFileTypes: true });
+  const presets = new Map();
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const root = join(packagePresets, entry.name);
+    if (await pathExists(join(root, 'loop.config.mjs')) && await isDirectory(join(root, 'prompts'))) {
+      presets.set(entry.name, root);
+    }
+  }
+  return presets;
+}
+
+async function resolvePresetRoot(name) {
+  if (typeof name !== 'string' || !name.trim()) throw new Error('--preset requires a name.');
+  const presets = await bundledPresets();
+  const root = presets.get(name);
+  if (root) return root;
+  const available = [...presets.keys()].sort().join(', ') || '(none)';
+  throw new Error(`Unknown preset "${name}". Available: ${available}.`);
+}
+
+async function renderInitConfig(presetRoot) {
+  const body = presetRoot
+    ? await readFile(join(presetRoot, 'loop.config.mjs'), 'utf8')
+    : EMBEDDED_STARTER;
+  return `${CONFIG_HEADER}\n${body.trimEnd()}\n\n${CONFIG_FOOTER}`;
+}
+
+/**
+ * Scaffold a self-contained aloop configuration and editable prompt overrides.
+ */
+export async function init({ cwd = process.cwd(), preset = null, force = false } = {}) {
+  const presetRoot = preset === null || preset === undefined ? null : await resolvePresetRoot(preset);
+  const promptTargetDir = join(cwd, '.loop', 'prompts');
+  const promptSources = [packagePrompts, ...(presetRoot ? [join(presetRoot, 'prompts')] : [])];
+  const prompts = new Map();
+  for (const sourceDir of promptSources) {
+    for (const name of await promptFilesIn(sourceDir)) prompts.set(name, join(sourceDir, name));
+  }
+
+  const plan = /** @type {any[]} */ ([
+    { target: join(cwd, 'loop.config.mjs'), kind: 'config' },
+    ...[...prompts.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([name, source]) => ({
+      target: join(promptTargetDir, name), source, kind: 'prompt',
+    })),
+  ]);
+  const existing = [];
+  for (const item of plan) {
+    if (await pathExists(item.target)) existing.push(relative(cwd, item.target));
+  }
+  if (existing.length && !force) {
+    const error = new Error(`Refusing to overwrite existing files:\n  ${existing.join('\n  ')}\nRe-run with --force to overwrite.`);
+    error.command = true;
+    throw error;
+  }
+
+  await mkdir(promptTargetDir, { recursive: true });
+  for (const item of plan) {
+    if (item.kind === 'config') await writeFile(item.target, await renderInitConfig(presetRoot), 'utf8');
+    else await copyFile(item.source, item.target);
+  }
+  return { preset: presetRoot ? preset : null, created: plan.map((item) => relative(cwd, item.target)), skipped: [] };
+}
+
 async function checkCommand(command, args, cwd) {
   try {
     await runCommand(command, args, { cwd });
@@ -612,7 +724,8 @@ async function checkCommand(command, args, cwd) {
   }
 }
 
-export async function doctor({ cwd = process.cwd(), configPath } = {}) {
+export async function doctor(options = {}) {
+  const { cwd = process.cwd(), configPath } = /** @type {any} */ (options);
   const checks = [];
   let context;
   try {

package/src/pipeline.mjs

@@ -1,4 +1,8 @@
-import { appendFile, mkdtemp, rm, stat, writeFile } from 'node:fs/promises';
+/** @typedef {import('./types.js').Config} Config */
+/** @typedef {import('./types.js').Operations} Operations */
+/** @typedef {import('./types.js').Summary} Summary */
+
+import { appendFile, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import packageJson from '../package.json' with { type: 'json' };
@@ -11,9 +15,10 @@ import { canonicalizeConfig, hashConfig, hashText } from './manifest.mjs';
 import { computeRunMetrics } from './metrics.mjs';
 import { publish } from './publish.mjs';
 import { renderPrompt } from './prompts.mjs';
-import { banner, describeAgent, ensureConfirmationAvailable, log, openTerminalInput, report } from './reporter.mjs';
+import { banner, describeAgent, ensureConfirmationAvailable, log, openTerminalInput, report, resetRenderer, setRenderer, writeOutput } from './reporter.mjs';
 import { RunState, slugFor } from './state.mjs';
 import { runPhases } from './runner.mjs';
+import { createTuiRenderer, tuiEnabled } from './tui.mjs';
 import { formatFindings } from './verdict.mjs';
 import { planWorktree, resumedWorktree, setupWorktree } from './worktree.mjs';
 
@@ -61,6 +66,18 @@ function configOverrideRecord(config, path) {
   };
 }
 
+async function resolveOperatorNote(args, cwd) {
+  const text = args.note ?? (args.noteFile ? await readFile(resolve(cwd, args.noteFile), 'utf8') : null);
+  if (text !== null && !text.trim()) {
+    throw new Error('--note and --note-file must contain non-whitespace text.');
+  }
+  return text === null ? null : { text };
+}
+
+function operatorNoteBlock(text) {
+  return `## Operator note (read this first)\n\nAn operator is resuming this phase and has provided the following instruction. Treat it as authoritative for what remains to be done. Do not redo or revert work that is already complete; do only what is needed to satisfy it and the phase's postconditions.\n\n${text}\n\n---\n\n`;
+}
+
 async function fileExists(path) {
   try {
     return (await stat(path)).isFile();
@@ -133,6 +150,7 @@ function engineRecord(agent) {
   };
 }
 
+/** @returns {import('./types.js').ManifestEntry} */
 function manifestEntry(phase, ctx, values = {}) {
   return {
     phase: phase.name,
@@ -273,7 +291,7 @@ async function runGate(phase, ctx) {
         timeoutMs: ctx.config.timeoutMs,
         activeProcessPath: ctx.activeProcessPath,
         onOutput: (text) => {
-          process.stdout.write(text);
+          writeOutput(text);
           void tee(logFile, text);
         },
       });
@@ -344,7 +362,7 @@ async function runPublish(phase, ctx, { remote, branch, base, approvedSha }) {
   return { ok: Boolean(result), result, manifest, failure };
 }
 
-async function withRetries(phase, operation, { failed = () => false } = {}) {
+async function withRetries(phase, operation, { failed = /** @type {(value: any) => boolean} */ (() => false) } = {}) {
   const maxAttempts = phase.retry?.maxAttempts ?? 1;
   for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
     try {
@@ -369,7 +387,7 @@ async function runSetup(commands, ctx) {
         timeoutMs: ctx.config.timeoutMs,
         activeProcessPath: ctx.activeProcessPath,
         onOutput: (text) => {
-          process.stdout.write(text);
+          writeOutput(text);
           void tee(logFile, text);
         },
       });
@@ -450,12 +468,16 @@ async function runAgent(phase, ctx, variables) {
   const agentRepo = sourceSnapshot?.path ?? ctx.worktree;
 
   try {
-  const { prompt, path } = await renderPrompt(phase.prompt, {
+  const rendered = await renderPrompt(phase.prompt, {
     ...variables,
     ...(sourceSnapshot ? { REPO: agentRepo } : {}),
   }, {
     projectPromptDir: ctx.promptDir,
   });
+  const receivesOperatorNote = ctx.note
+    && (ctx.note.targetPhase === phase.name || ctx.note.repairPhase === phase.name);
+  const prompt = receivesOperatorNote ? `${operatorNoteBlock(ctx.note.text)}${rendered.prompt}` : rendered.prompt;
+  const { path } = rendered;
   const promptHash = hashText(prompt);
   log(`  engine: ${agent.name}${agent.model ? `   model: ${agent.model}` : ''}${agent.effort ? `   effort: ${agent.effort}` : ''}   prompt: ${path}`);
   if (engineOverride) log(`  resumed override: ${describeAgent(engineOverride.from)} → ${describeAgent(engineOverride.to)}`);
@@ -507,7 +529,7 @@ async function runAgent(phase, ctx, variables) {
   const emit = (text) => {
     if (!text) return;
     bytesEmitted += Buffer.byteLength(text);
-    process.stdout.write(text);
+    writeOutput(text);
     pendingLogWrites.push(tee(logFile, text));
   };
   let commandError;
@@ -573,10 +595,12 @@ export async function runLoop(options = {}) {
   const cwd = args.cwd ?? process.cwd();
   const rootGit = new GitFacade(cwd);
   const repoRoot = await rootGit.toplevel();
+  const operatorNote = await resolveOperatorNote(args, cwd);
 
   if (args.config && args.overrideEngine) {
     throw new Error('--config and --override-engine cannot be used together; configure engines in the supplied config file.');
   }
+  /** @type {Config} */
   const config = await loadConfig(repoRoot, {
     ...(args.maxRounds ? { maxRounds: args.maxRounds } : {}),
     ...(args.phases ? { phases: args.phases } : {}),
@@ -616,6 +640,7 @@ export async function runLoop(options = {}) {
   );
 
   let runStarted = false;
+  let tuiRenderer = null;
   try {
   const persistedName = args.resume ? state.data.name : null;
   if (persistedName && args.name && slugFor(args.name) !== persistedName) {
@@ -787,6 +812,7 @@ export async function runLoop(options = {}) {
     engineOverrides,
     budgetWarnings: new Set(),
     configHash: hashConfig(config),
+    note: operatorNote,
     resume: Boolean(args.resume),
     dryRun: args.dryRun,
     remote,
@@ -835,6 +861,7 @@ export async function runLoop(options = {}) {
   log(`run dir   : ${state.dir}`);
   log(`phases    : ${config.resolvedPhases.map((phase) => phase.name).join(' → ')}`);
 
+  /** @type {Summary} */
   const summary = {
     phases: [],
     stalled: null,
@@ -849,6 +876,24 @@ export async function runLoop(options = {}) {
     pullRequest: state.data.pullRequest ?? state.manifestMetadata.pullRequest ?? null,
   };
 
+  if (!args.dryRun && tuiEnabled({ isTTY: process.stdout.isTTY, noTui: args.noTui })) {
+    tuiRenderer = createTuiRenderer({ config, state, summary });
+    setRenderer(tuiRenderer);
+  }
+
+  const operations = /** @satisfies {Operations} */ ({
+    budgetStatus,
+    markBudgetExhaustedComplete,
+    manifestEntry,
+    markStalledManifest,
+    recordBudgetStall,
+    recordManifest,
+    runAgent,
+    runGate,
+    runPublish,
+    withRetries,
+  });
+
   await runPhases({
     args,
     config,
@@ -861,24 +906,18 @@ export async function runLoop(options = {}) {
     baseBranch,
     confirmInput,
     terminalOpener,
-    operations: {
-      budgetStatus,
-      markBudgetExhaustedComplete,
-      manifestEntry,
-      markStalledManifest,
-      recordBudgetStall,
-      recordManifest,
-      runAgent,
-      runGate,
-      runPublish,
-      withRetries,
-    },
+    operations,
   });
 
   await state.record({
     status: summary.stalled ? 'stalled' : 'completed',
     ...(summary.stalled ? { stalled: summary.stalled } : {}),
   });
+  if (tuiRenderer) {
+    tuiRenderer.stop();
+    resetRenderer();
+    tuiRenderer = null;
+  }
   report(summary, formatFindings);
   return summary;
 
@@ -886,6 +925,10 @@ export async function runLoop(options = {}) {
     if (runStarted && !args.dryRun) await state.record({ status: 'stalled' }).catch(() => {});
     throw error;
   } finally {
+    if (tuiRenderer) {
+      tuiRenderer.stop();
+      resetRenderer();
+    }
     await state.release();
   }
 }