@syntax-syllogism/aloop 0.6.2 → 0.8.1

package/src/publish.mjs

@@ -25,7 +25,8 @@ export function parsePullRequestDescription(contents) {
   return { title, body };
 }
 
-export function githubBackend({ cwd, git = new GitFacade(cwd), runner = runCommand, env } = {}) {
+export function githubBackend(options = {}) {
+  const { cwd, git = new GitFacade(cwd), runner = runCommand, env } = /** @type {any} */ (options);
   const repositories = new Map();
 
   async function resolveRepository(remote) {
@@ -128,17 +129,8 @@ function assertVerifiedPullRequest(pullRequest, { base, branch, localSha, draft
  * backend is GitHub's `gh` CLI; other remotes can supply the same precheck,
  * view, create, and update operations without changing this use case.
  */
-export async function publish({
-  git,
-  remote,
-  branch,
-  base,
-  prBodyPath,
-  draft = true,
-  backend = 'github',
-  approvedSha = null,
-  env,
-}) {
+export async function publish(options = {}) {
+  const { git, remote, branch, base, prBodyPath, draft = true, backend = 'github', approvedSha = null, env } = /** @type {any} */ (options);
   if (!git || typeof git.push !== 'function' || typeof git.lsRemote !== 'function') {
     throw new PublishError('Publish requires a GitFacade with push and lsRemote operations.');
   }

package/src/reporter.mjs

@@ -1,14 +1,49 @@
 import { createReadStream } from 'node:fs';
 import { createInterface } from 'node:readline/promises';
 
+// Renderer seam: `log`/`banner` fan out to whichever renderer is active so a
+// second renderer (e.g. the TUI in tui.mjs) can slot in without runner.mjs or
+// pipeline.mjs knowing which one is live. `report` is deliberately left alone
+// — callers stop the alternate renderer and reset to plain before calling it,
+// so the final summary always prints as normal scrollback text.
+let activeRenderer = null;
+
+export function setRenderer(renderer) {
+  activeRenderer = renderer;
+}
+
+export function resetRenderer() {
+  activeRenderer = null;
+}
+
 export function log(message) {
+  if (activeRenderer) {
+    activeRenderer.log(message);
+    return;
+  }
   console.log(message);
 }
 
 export function banner(text) {
+  if (activeRenderer) {
+    activeRenderer.banner(text);
+    return;
+  }
   log(`\n── ${text} ${'─'.repeat(Math.max(0, 60 - text.length))}`);
 }
 
+// Raw child-process/engine output (gate commands, setup commands, agent
+// streams) goes through this seam too, not straight to process.stdout: a
+// renderer that repaints the screen (the TUI) needs to be the only writer,
+// or its repaints interleave with the raw bytes into a garbled display.
+export function writeOutput(text) {
+  if (activeRenderer) {
+    activeRenderer.output?.(text);
+    return;
+  }
+  process.stdout.write(text);
+}
+
 export function describeAgent(agent) {
   return `${agent.name}${agent.model ? ` model=${agent.model}` : ''}${agent.effort ? ` effort=${agent.effort}` : ''}`;
 }
@@ -18,7 +53,8 @@ export function formatPhase(phase) {
   return `  ✓ ${phase.name}${detail}`;
 }
 
-export function openTerminalInput({ platform = process.platform, input = process.stdin, createInput = createReadStream } = {}) {
+export function openTerminalInput(options = {}) {
+  const { platform = process.platform, input = process.stdin, createInput = createReadStream } = /** @type {any} */ (options);
   if (platform === 'win32' && input.isTTY) return Promise.resolve(input);
   const terminalPath = platform === 'win32' ? '\\\\.\\CONIN$' : '/dev/tty';
   return new Promise((resolveInput, rejectInput) => {

package/src/runner.mjs

@@ -1,3 +1,8 @@
+/** @typedef {import('./types.js').Config} Config */
+/** @typedef {import('./types.js').Operations} Operations */
+/** @typedef {import('./types.js').RunState} RunState */
+/** @typedef {import('./types.js').Summary} Summary */
+
 import { stat, unlink } from 'node:fs/promises';
 import { join } from 'node:path';
 import { codePhasePostcondition, hasPostcondition, phaseIsSkippable, publishingAttestation } from './policy.mjs';
@@ -60,12 +65,33 @@ async function invalidateGateCompletion(state, reviewedSha) {
   await state.record({ completed: state.data.completed.filter((name) => name !== gate.phase) });
 }
 
-async function runRepairs(phase, ctx, baseVariables, pending, operations) {
+async function invalidateFollowingPhaseState(state, phases, phaseName) {
+  const phaseIndex = phases.findIndex((phase) => phase.name === phaseName);
+  const followingNames = new Set(phases.slice(phaseIndex + 1).map((phase) => phase.name));
+  if (!followingNames.size) return;
+
+  const completed = state.data.completed.filter((name) => !followingNames.has(name));
+  const phaseState = Object.fromEntries(
+    Object.entries(state.data.phases ?? {}).filter(([name]) => !followingNames.has(name)),
+  );
+  const pendingRepairs = Object.fromEntries(
+    Object.entries(state.data.pendingRepairs ?? {}).filter(([name]) => !followingNames.has(name)),
+  );
+  const rounds = Object.fromEntries(
+    Object.entries(state.data.rounds ?? {}).filter(([name]) => !followingNames.has(name)),
+  );
+  const reviewedShas = Object.fromEntries(
+    Object.entries(state.data.reviewedShas ?? {}).filter(([name]) => !followingNames.has(name)),
+  );
+  await state.record({ completed, phases: phaseState, pendingRepairs, rounds, reviewedShas });
+}
+
+async function runRepairs(phase, ctx, baseVariables, pending, operations, { retainCheckpoint = false } = {}) {
   const {
     budgetStatus, manifestEntry, recordBudgetStall, recordManifest, runAgent, runGate, withRetries,
   } = operations;
-  let gateOk = true;
-  let gateFailure = null;
+  let gateOk = pending.gateOk ?? true;
+  let gateFailure = pending.gateFailure ?? null;
   for (let index = pending.nextRepair; index < phase.repair.length; index += 1) {
     const repair = phase.repair[index];
     const budget = budgetStatus(ctx);
@@ -108,12 +134,15 @@ async function runRepairs(phase, ctx, baseVariables, pending, operations) {
       const headBefore = !ctx.dryRun && (hasPostcondition(repair, 'head-advanced') || hasPostcondition(repair, 'head-advanced-or-rebuttal'))
         ? await ctx.git.revParse()
         : null;
-      const result = await withRetries(repair, () => runAgent(repair, ctx, {
+      const repairCtx = ctx.note?.targetPhase === phase.name
+        ? { ...ctx, note: { ...ctx.note, repairPhase: repair.name } }
+        : ctx;
+      const result = await withRetries(repair, () => runAgent(repair, repairCtx, {
         ...baseVariables,
         ROUND: pending.round,
         MAX_ROUNDS: phase.maxRounds,
         VERDICT_FILE: ctx.state.verdictPath(pending.round),
-        FINDINGS: formatFindings(pending.verdict.blocking),
+        FINDINGS: formatFindings(pending.verdict?.blocking ?? []),
         SINCE_SHA: pending.reviewedSha,
         GATE_STATUS: gateOk ? 'passing' : `FAILING\n${gateFailure}`,
       }));
@@ -144,10 +173,77 @@ async function runRepairs(phase, ctx, baseVariables, pending, operations) {
       },
     });
   }
-  await clearPendingRepair(phase, ctx.state);
+  if (!retainCheckpoint) await clearPendingRepair(phase, ctx.state);
   return { gateOk, gateFailure };
 }
 
+async function runGateAttempt(phase, ctx, operations, options = {}) {
+  const { round } = /** @type {any} */ (options);
+  const { manifestEntry, recordManifest, runGate, withRetries } = operations;
+  const startedAt = new Date().toISOString();
+  const inputSha = await ctx.git.revParse();
+  const result = await withRetries(phase, () => runGate(phase, ctx), { failed: (attempt) => !attempt.ok });
+  await recordManifest(ctx, manifestEntry(phase, ctx, {
+    inputSha,
+    outputSha: await ctx.git.revParse(),
+    artifacts: [`${phase.name}.log`],
+    gateReceipts: result.gateReceipts,
+    execution: result.execution,
+    startedAt,
+    completedAt: new Date().toISOString(),
+    durationMs: result.durationMs,
+    status: result.ok ? 'completed' : 'stalled',
+    ...(round === undefined ? {} : { round }),
+  }));
+  return result;
+}
+
+async function runGateRepairLoop(phase, ctx, variables, operations) {
+  let result = null;
+  let pending = ctx.resume ? ctx.state.data.pendingRepairs?.[phase.name] : null;
+  let round = pending?.round ?? 1;
+
+  while (round <= phase.maxRounds) {
+    if (pending) {
+      result = {
+        ok: false,
+        command: phase.name,
+        output: pending.gateFailure ?? '',
+      };
+      const repairResult = await runRepairs(phase, ctx, variables, pending, operations, { retainCheckpoint: true });
+      if (repairResult.stalled) {
+        return { result, stalled: repairResult.stalled, stalledPhase: repairResult.stalledPhase, budgetStall: repairResult.budgetStall };
+      }
+      // The checkpoint's repairs have completed, so re-gate deliberately before
+      // deciding whether another repair round is needed.
+      result = await runGateAttempt(phase, ctx, operations, { round });
+      if (result.ok) {
+        await clearPendingRepair(phase, ctx.state);
+        return { result };
+      }
+      pending = null;
+      round += 1;
+      continue;
+    }
+
+    result ??= await runGateAttempt(phase, ctx, operations);
+    if (result.ok) return { result };
+
+    pending = {
+      round,
+      reviewedSha: await ctx.git.revParse(),
+      verdict: { blocking: [] },
+      gateOk: false,
+      gateFailure: `${result.command}\n${result.output}`,
+      nextRepair: 0,
+    };
+    await ctx.state.record({
+      pendingRepairs: { ...ctx.state.data.pendingRepairs, [phase.name]: pending },
+    });
+  }
+  return { result };
+}
+
 /**
  * Run a verdict phase and its repair phases until the verdict clears.
  *
@@ -327,7 +423,16 @@ async function runVerdictLoop(phase, ctx, baseVariables, operations) {
   }
 }
 
-/** Drive phase descriptors using operations supplied by the composition root. */
+/**
+ * Drive phase descriptors using operations supplied by the composition root.
+ *
+ * @param {{
+ *   args: Record<string, any>, config: Config, state: RunState, ctx: any,
+ *   variables: Record<string, unknown>, summary: Summary, remote: string,
+ *   branch: string, baseBranch: string, confirmInput: any,
+ *   terminalOpener: any, operations: Operations,
+ * }} input
+ */
 export async function runPhases({
   args, config, state, ctx, variables, summary, remote, branch, baseBranch,
   confirmInput, terminalOpener, operations,
@@ -343,9 +448,22 @@ export async function runPhases({
   }
 
   const phasesToRun = config.resolvedPhases.slice(startIndex);
+  const noteTarget = args.from ?? (args.resume
+    ? phasesToRun.find((phase) => !state.isComplete(phase.name))?.name
+    : phasesToRun[0]?.name);
+  if (ctx.note) {
+    const target = config.resolvedPhases.find((phase) => phase.name === noteTarget);
+    if (!target) throw new Error('--note needs a phase to run; use --from to target a completed phase.');
+    const hasAgentRepair = target.kind === 'gate' && target.repair?.some((repair) => repair.kind === 'agent');
+    if (target.kind !== 'agent' && !hasAgentRepair) {
+      throw new Error(`--note cannot target ${target.kind} phase "${target.name}" without an agent repair phase.`);
+    }
+    ctx.note = { ...ctx.note, targetPhase: target.name };
+  }
   for (const [phaseIndex, phase] of phasesToRun.entries()) {
     const isFinalPhase = phaseIndex === phasesToRun.length - 1;
-    if (args.resume && state.data.phases?.[phase.name]?.budgetExhausted) {
+    const forceNotedPhase = args.resume && args.from === phase.name && ctx.note?.targetPhase === phase.name;
+    if (args.resume && state.data.phases?.[phase.name]?.budgetExhausted && !forceNotedPhase) {
       const budget = budgetStatus(ctx);
       if (budget) {
         summary.stalled = await recordBudgetStall(ctx, phase, budget);
@@ -356,7 +474,7 @@ export async function runPhases({
       summary.phases.push({ name: phase.name, ok: true });
       continue;
     }
-    if (args.resume && state.isComplete(phase.name)) {
+    if (args.resume && state.isComplete(phase.name) && !forceNotedPhase) {
       log(`\n── ${phase.name}: already complete, skipping`);
       await recordManifest(ctx, manifestEntry(phase, ctx, { status: 'skipped' }));
       continue;
@@ -393,6 +511,9 @@ export async function runPhases({
         continue;
       }
     }
+    if (forceNotedPhase) {
+      await invalidateFollowingPhaseState(state, config.resolvedPhases, phase.name);
+    }
     if (!phase.verdict) banner(phase.name);
     if (phase.requiresCleanTree && !ctx.dryRun) {
       const pending = await ctx.git.status();
@@ -439,18 +560,29 @@ export async function runPhases({
         log(`  would run: ${(phase.commands ?? config.gate).join(' && ')}`);
         continue;
       }
-      const startedAt = new Date().toISOString();
-      const inputSha = await ctx.git.revParse();
-      const result = await withRetries(phase, () => runGate(phase, ctx), { failed: (attempt) => !attempt.ok });
-      await recordManifest(ctx, manifestEntry(phase, ctx, {
-        inputSha, outputSha: await ctx.git.revParse(), artifacts: [`${phase.name}.log`],
-        gateReceipts: result.gateReceipts, startedAt, completedAt: new Date().toISOString(),
-        execution: result.execution,
-        durationMs: result.durationMs, status: result.ok ? 'completed' : 'stalled',
-      }));
-      if (!result.ok) {
-        summary.stalled = { phase: phase.name, reason: `gate failed: ${result.command}`, output: result.output };
-        break;
+      if (phase.repair?.length) {
+        const repaired = await runGateRepairLoop(phase, ctx, variables, operations);
+        if (repaired.stalled) {
+          if (!repaired.budgetStall) {
+            await markStalledManifest(ctx, phase, repaired, state.manifest.entries.length - 1);
+          }
+          summary.stalled = {
+            phase: repaired.stalledPhase ?? phase.name,
+            reason: repaired.stalled,
+            output: repaired.result.output,
+          };
+          break;
+        }
+        if (!repaired.result.ok) {
+          summary.stalled = { phase: phase.name, reason: `gate failed: ${repaired.result.command}`, output: repaired.result.output };
+          break;
+        }
+      } else {
+        const result = await runGateAttempt(phase, ctx, operations);
+        if (!result.ok) {
+          summary.stalled = { phase: phase.name, reason: `gate failed: ${result.command}`, output: result.output };
+          break;
+        }
       }
       if (isFinalPhase) {
         const budget = budgetStatus(ctx);

package/src/state.mjs

@@ -1,3 +1,6 @@
+/** @typedef {import('./types.js').RunData} RunData */
+/** @typedef {import('./types.js').ManifestEntry} ManifestEntry */
+
 import { randomUUID } from 'node:crypto';
 import { access, mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
 import { readdirSync, renameSync, rmSync } from 'node:fs';
@@ -145,6 +148,7 @@ export function slugFor(input) {
 }
 
 export class RunState {
+  /** @param {string} dir @param {RunData} data @param {boolean} [readOnly] */
   constructor(dir, data, readOnly = false, manifest = new Manifest(), lockToken = null, manifestMetadata = {}) {
     this.dir = dir;
     this.data = data;
@@ -210,7 +214,7 @@ export class RunState {
       if (create) {
         try {
           const saved = JSON.parse(await readFile(join(dir, 'manifest.json'), 'utf8'));
-          manifest = new Manifest(saved.phases ?? []);
+          manifest = new Manifest(/** @type {ManifestEntry[]} */ (saved.phases ?? []));
           manifestMetadata = saved;
         } catch (error) {
           if (error.code !== 'ENOENT') throw error;

package/src/tui.mjs

@@ -0,0 +1,171 @@
+import { spawnSync } from 'node:child_process';
+import { computeRunMetrics } from './metrics.mjs';
+import { formatFindings } from './verdict.mjs';
+
+const ESC = '\x1b';
+const CLEAR_SCREEN = `${ESC}[2J${ESC}[H`;
+const HIDE_CURSOR = `${ESC}[?25l`;
+const SHOW_CURSOR = `${ESC}[?25h`;
+const RECENT_LOG_LIMIT = 8;
+
+/**
+ * A live TUI is only a view over the same run; it never changes what the run
+ * does. It is therefore only worth showing where someone can watch it, and
+ * must get out of the way the moment that stops being true (piped output/CI, or
+ * an explicit `--no-tui`). `--yes` only skips per-phase confirmation, so an
+ * unattended run on a real terminal can still be watched live.
+ */
+export function tuiEnabled(options = {}) {
+  const { isTTY, noTui } = /** @type {any} */ (options);
+  return Boolean(isTTY) && !noTui;
+}
+
+function statusSymbol(status) {
+  if (status === 'completed') return '✓';
+  if (status === 'stalled') return '✗';
+  if (status === 'active') return '▶';
+  return ' ';
+}
+
+function matchPhaseName(resolvedPhases, text) {
+  const found = resolvedPhases.find((phase) => text === phase.name || text.startsWith(`${phase.name} (`));
+  return found ? found.name : null;
+}
+
+function phaseRows(resolvedPhases, manifestEntries, completed, activeName) {
+  return resolvedPhases.map((phase) => {
+    const entries = manifestEntries.filter((entry) => entry.phase === phase.name);
+    const last = entries.at(-1);
+    let status = 'pending';
+    if (last?.status === 'stalled') status = 'stalled';
+    else if (completed.includes(phase.name)) status = 'completed';
+    else if (phase.name === activeName) status = 'active';
+    const rounds = entries.filter((entry) => Number.isInteger(entry.round)).length;
+    return { name: phase.name, status, rounds, verdict: last?.verdict?.verdict ?? null };
+  });
+}
+
+export function defaultDiffStat(worktree) {
+  if (!worktree) return '';
+  try {
+    const result = spawnSync('git', ['-C', worktree, 'diff', '--stat', 'HEAD'], { encoding: 'utf8' });
+    if (result.status !== 0 || result.error) return '';
+    return result.stdout.trim();
+  } catch {
+    return '';
+  }
+}
+
+function formatValue(value) {
+  return value === null || value === undefined ? '?' : String(value);
+}
+
+function latestVerdictEntry(manifestEntries) {
+  return [...manifestEntries].reverse().find((entry) => entry.verdict);
+}
+
+function renderFrame({ config, summary, state, activeName, recentLog, diff }) {
+  const manifestEntries = state.manifest.entries;
+  const completed = state.data.completed ?? [];
+  const rows = phaseRows(config.resolvedPhases, manifestEntries, completed, activeName);
+  const metrics = computeRunMetrics(state.manifest);
+  const artifacts = [...new Set(manifestEntries.flatMap((entry) => entry.artifacts ?? []))];
+  const verdictEntry = latestVerdictEntry(manifestEntries);
+
+  const lines = [];
+  lines.push(`aloop · ${summary.task}  branch=${summary.branch}`);
+  lines.push('');
+  lines.push('Phases:');
+  for (const row of rows) {
+    const roundDetail = row.rounds ? ` (round ${row.rounds}${row.verdict ? `, ${row.verdict}` : ''})` : '';
+    lines.push(`  ${statusSymbol(row.status)} ${row.name}${roundDetail}`);
+  }
+  lines.push('');
+  lines.push(
+    `Cost: duration=${formatValue(metrics.total.durationMs)}ms tokens=${formatValue(metrics.total.tokens)} cost=${formatValue(metrics.total.cost)}`,
+  );
+  if (diff) {
+    lines.push('');
+    lines.push('Diff:');
+    lines.push(...diff.split('\n'));
+  }
+  if (verdictEntry) {
+    lines.push('');
+    lines.push(`Findings (${verdictEntry.phase}, ${verdictEntry.verdict.verdict}):`);
+    lines.push(formatFindings([...(verdictEntry.verdict.blocking ?? []), ...(verdictEntry.verdict.nits ?? [])]));
+  }
+  if (artifacts.length) {
+    lines.push('');
+    lines.push(`Artifacts: ${artifacts.join(', ')}`);
+  }
+  if (recentLog.length) {
+    lines.push('');
+    lines.push('Recent:');
+    for (const entry of recentLog) lines.push(`  ${entry}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * A second renderer behind the `banner`/`log` seam in reporter.mjs. It reads
+ * the same manifest/state the run already persists after every phase, so it
+ * needs no separate event stream — just a repaint on every `banner`/`log`
+ * call, which is exactly when the run's visible state can have changed.
+ *
+ * `git diff --stat` is a subprocess spawn, not free, and the diff it reports
+ * only changes between phases (each phase is what edits the worktree) — so
+ * it's computed once per `banner` and reused by every repaint until the next
+ * one, instead of being re-spawned on every `log`/`output` call.
+ */
+export function createTuiRenderer(options = {}) {
+  const { config, state, summary, output = process.stdout, diffStat = defaultDiffStat } = /** @type {any} */ (options);
+  let activeName = null;
+  const recentLog = [];
+  let pendingLine = '';
+  let cachedDiff = '';
+
+  function repaint() {
+    const frame = renderFrame({ config, summary, state, activeName, recentLog, diff: cachedDiff });
+    output.write(`${HIDE_CURSOR}${CLEAR_SCREEN}${frame}\n`);
+  }
+
+  function pushRecent(text) {
+    const trimmed = text.trim();
+    if (!trimmed) return;
+    recentLog.push(trimmed);
+    if (recentLog.length > RECENT_LOG_LIMIT) recentLog.shift();
+  }
+
+  return {
+    banner(text) {
+      activeName = matchPhaseName(config.resolvedPhases, text) ?? activeName;
+      recentLog.length = 0;
+      recentLog.push(text.trim());
+      cachedDiff = diffStat(summary.worktree);
+      repaint();
+    },
+    log(message) {
+      pushRecent(message);
+      repaint();
+    },
+    // Raw engine/gate/setup output arrives in arbitrary chunks, not lines;
+    // buffer until a newline so the "Recent" pane shows whole lines instead
+    // of chopped fragments, then fold it into the same repaint the other
+    // renderer calls use so nothing else writes to the terminal directly.
+    // A chunk with no newline yet changes nothing visible (the fragment
+    // isn't shown until it completes a line), so it's buffered without
+    // triggering a repaint.
+    output(text) {
+      pendingLine += text;
+      const lines = pendingLine.split('\n');
+      pendingLine = lines.pop();
+      if (lines.length === 0) return;
+      for (const line of lines) pushRecent(line);
+      repaint();
+    },
+    stop() {
+      repaint();
+      output.write(SHOW_CURSOR);
+    },
+  };
+}