@0xgeorgemathew/zcode 0.4.4 → 0.5.1

package/lib/commands/sessions.js

@@ -1,8 +1,9 @@
 'use strict';
-// lib/commands/sessions.js — status | wait | cancel. Read-only views over
+// lib/commands/sessions.js — status | wait | result | cancel. Read-only views over
 // the session store (plus a signal for cancel); none of them spawns the
 // engine or needs the API key, so they are instant and safe to poll.
 const store = require('../store.js');
+const { buildBrief } = require('../brief.js');
 const { formatResult, formatSessionRow, formatSessionView, useColor } = require('../ui.js');
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
@@ -82,9 +83,35 @@ function summaryOf(s) {
   };
 }
 
+const isDone = (view) => view.state === 'finished' || view.state === 'interrupted';
+
+// `12m`, `45s`, `1h05m`: how long a session has been alive, for one-line views.
+function formatElapsed(ms) {
+  const s = Math.max(0, Math.round(ms / 1000));
+  if (s < 60) return `${s}s`;
+  if (s < 3600) return `${Math.floor(s / 60)}m`;
+  return `${Math.floor(s / 3600)}h${String(Math.floor((s % 3600) / 60)).padStart(2, '0')}m`;
+}
+
+// What a still-running session costs the reader on a wait timeout: exactly
+// one line, nothing else.
+function pendingLine(view, json) {
+  const elapsedMs = Math.max(0, Date.now() - Date.parse(view.createdAt || view.updatedAt || Date.now()));
+  if (json) return JSON.stringify({ type: 'pending', id: view.id, state: view.state, phase: view.phase, elapsedMs });
+  return `${view.id} ${view.state} ${view.phase} ${formatElapsed(elapsedMs)}`;
+}
+
+// A finished session's handback in the requested form.
+function printResult(result, { json, full }) {
+  if (json) process.stdout.write(JSON.stringify(full ? result : buildBrief(result)) + '\n');
+  else process.stdout.write(formatResult(result, { color: useColor(process.stdout) }));
+}
+
 // Blocks until every id is finished (or interrupted), printing each
-// handback as it lands. Exit 0 iff all completed; otherwise the exit code
-// of the first one that did not (124 when --timeout-ms elapses first).
+// handback as it lands (--any: until the FIRST one finishes; the rest keep
+// running). Exit 0 iff all completed; otherwise the exit code of the first
+// one that did not (--any: that of the one reported). On --timeout-ms: one
+// line per pending session and exit 124.
 async function wait(parsed) {
   const { flags, prompts, given } = parsed;
   if (prompts.length === 0) {
@@ -97,22 +124,22 @@ async function wait(parsed) {
   const pending = new Set(ids);
   let code = 0;
   for (;;) {
-    for (const id of [...pending]) {
+    for (const id of ids) {
+      if (!pending.has(id)) continue;
       const view = store.viewSession(store.readSession(id));
-      if (view.state !== 'finished' && view.state !== 'interrupted') continue;
+      if (!isDone(view)) continue;
       pending.delete(id);
       const result = finalResult(view);
       const c = exitCodeFor(result);
+      printResult(result, { json: flags.json, full: flags.full });
+      if (flags.any) process.exit(c);
       if (c !== 0 && code === 0) code = c;
-      if (flags.json) process.stdout.write(JSON.stringify(result) + '\n');
-      else process.stdout.write(formatResult(result, { color: useColor(process.stdout) }));
     }
     if (pending.size === 0) process.exit(code);
     if (Date.now() >= deadline) {
-      for (const id of pending) {
-        const view = store.viewSession(store.readSession(id));
-        if (flags.json) process.stdout.write(JSON.stringify(statusPayload(view, { events: 3 })) + '\n');
-        else process.stderr.write(`zcode: ${id} still ${view.state} (phase ${view.phase})\n`);
+      for (const id of ids) {
+        if (!pending.has(id)) continue;
+        process.stdout.write(pendingLine(store.viewSession(store.readSession(id)), flags.json) + '\n');
       }
       process.exit(124);
     }
@@ -120,6 +147,27 @@ async function wait(parsed) {
   }
 }
 
+// result <id>: the handback of a finished session, without waiting. Brief
+// as JSON with --json, the human view otherwise; --full prints the full
+// record (JSON).
+async function result(parsed) {
+  const { flags, prompts } = parsed;
+  if (prompts.length !== 1) {
+    process.stderr.write('zcode: result needs exactly one session id.\n');
+    process.exit(2);
+  }
+  const id = resolveOrExit(prompts[0], flags.json);
+  const view = store.viewSession(store.readSession(id));
+  if (!isDone(view)) {
+    process.stderr.write(`zcode: ${id} is still ${view.state} (phase ${view.phase}); use "zcode wait ${id}".\n`);
+    process.exit(7);
+  }
+  const r = finalResult(view);
+  if (flags.full) process.stdout.write(JSON.stringify(r) + '\n');
+  else printResult(r, { json: flags.json, full: false });
+  process.exit(0);
+}
+
 // SIGTERM to the owning process; it stops the engine turn, kills checks,
 // records "cancelled". Escalates to SIGKILL after 15 s and records the
 // cancellation itself. Idempotent: cancelling a finished session is a no-op.
@@ -175,6 +223,7 @@ async function cancel(parsed) {
 module.exports = async function sessions(parsed) {
   if (parsed.command === 'status') return status(parsed);
   if (parsed.command === 'wait') return wait(parsed);
+  if (parsed.command === 'result') return result(parsed);
   return cancel(parsed);
 };
 

package/lib/contract.js

@@ -19,12 +19,18 @@ const CONTRACT_KEYS = [
   'scope',
   'constraints',
   'design',
+  'decisions',
+  'units',
+  'visual',
+  'viewports',
+  'serve',
   'acceptance',
   'checks',
   'files',
   'references',
   'context',
   'owns',
+  'touch',
   'limits',
   'model',
   'effort',
@@ -36,6 +42,43 @@ const asList = (v) =>
     ? []
     : (Array.isArray(v) ? v : [v]).map((x) => String(x).trim()).filter(Boolean);
 
+const uniq = (items) => [...new Set(items)];
+const VIEWPORT_RE = /^\d{2,5}x\d{2,5}$/;
+const DEFAULT_VIEWPORTS = ['390x844', '1440x900'];
+const UNIT_KEYS = ['name', 'objective', 'owns'];
+
+// "name: objective [owns a,b]" -> {name, objective, owns?}
+function parseUnit(spec) {
+  const m = /^\s*([^:]+?)\s*:\s*([\s\S]*?)\s*(?:\[owns\s+([^\]]*)\])?\s*$/.exec(String(spec));
+  if (!m || !m[1].trim() || !m[2].trim()) {
+    throw new ContractError(`unit "${String(spec).slice(0, 60)}" must look like "name: objective" (optionally "[owns a,b]")`);
+  }
+  const owns = (m[3] || '').split(',').map((x) => x.trim()).filter(Boolean);
+  return { name: m[1].trim(), objective: m[2].trim(), ...(owns.length ? { owns } : {}) };
+}
+
+function normalizeUnits(items) {
+  const units = items.map((raw) => {
+    if (typeof raw === 'string') return parseUnit(raw);
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+      throw new ContractError('contract "units" entries must be {name, objective, owns?} objects or "name: objective" strings');
+    }
+    const bad = Object.keys(raw).filter((k) => !UNIT_KEYS.includes(k));
+    if (bad.length) throw new ContractError(`unknown unit key(s): ${bad.join(', ')}. Accepted: ${UNIT_KEYS.join(', ')}`);
+    const name = String(raw.name ?? '').trim();
+    const objective = String(raw.objective ?? '').trim();
+    if (!name || !objective) throw new ContractError('every unit needs a name and an objective');
+    const owns = asList(raw.owns);
+    return { name, objective, ...(owns.length ? { owns } : {}) };
+  });
+  const seen = new Set();
+  for (const u of units) {
+    if (seen.has(u.name)) throw new ContractError(`duplicate unit name "${u.name}"`);
+    seen.add(u.name);
+  }
+  return units;
+}
+
 // Builds a contract from an optional base object (JSON file / markdown
 // brief) plus CLI additions. Throws ContractError on unknown keys or a
 // missing objective — before any engine spawn.
@@ -62,6 +105,11 @@ function normalizeContract(base = {}, additions = {}) {
       throw new ContractError(`contract limits.${k} must be a non-negative number`);
     }
   }
+  const viewports = uniq([...asList(base.viewports), ...asList(additions.viewports)]);
+  for (const v of viewports) {
+    if (!VIEWPORT_RE.test(v)) throw new ContractError(`viewport "${v}" must look like 390x844`);
+  }
+  const serve = String(additions.serve ?? base.serve ?? '').trim();
   const objective = [String(base.objective ?? '').trim(), String(additions.objective ?? '').trim()]
     .filter(Boolean)
     .join('\n\n');
@@ -73,12 +121,21 @@ function normalizeContract(base = {}, additions = {}) {
     scope: asList(base.scope),
     constraints: asList(base.constraints),
     design: asList(base.design),
-    acceptance: [...asList(base.acceptance), ...asList(additions.acceptance)],
+    decisions: uniq([...asList(base.decisions), ...asList(additions.decisions)]),
+    units: normalizeUnits([
+      ...(Array.isArray(base.units) ? base.units : base.units === undefined ? [] : [base.units]),
+      ...(additions.units || []),
+    ]),
+    visual: uniq([...asList(base.visual), ...asList(additions.visual)]),
+    viewports,
+    serve,
+    acceptance: uniq([...asList(base.acceptance), ...asList(additions.acceptance)]),
     checks: [...asList(base.checks), ...asList(additions.checks)],
-    files: [...asList(base.files), ...asList(additions.files)],
+    files: uniq([...asList(base.files), ...asList(additions.files)]),
     references: asList(base.references),
-    context: [...asList(base.context), ...asList(additions.context)],
+    context: uniq([...asList(base.context), ...asList(additions.context)]),
     owns: [...asList(base.owns), ...asList(additions.owns)],
+    touch: [...asList(base.touch), ...asList(additions.touch)],
     limits: { ...limits },
     model: base.model ?? null,
     effort: base.effort ?? null,
@@ -103,33 +160,90 @@ const HANDBACK_SPEC = [
   ' "criteria": [{"criterion": "acceptance criterion", "met": true, "evidence": "short"}],',
   ' "unresolved": ["problems inside your scope that remain unfixed"],',
   ' "questions": ["what you need from the orchestrator (only when blocked)"],',
+  ' "decisions": [{"what": "choice you made in scope", "why": "short"}],',
   ' "notes": "risks or follow-ups the orchestrator should know"}',
   '```',
   '"done" means every acceptance criterion is met and verified; "partial" means some work remains; "blocked" means you cannot proceed without the orchestrator.',
+  'A question may be {"q": "...", "options": ["A ...", "B ..."], "recommend": "A"}.',
+].join('\n');
+
+// Rendered on every task prompt, so it stays tiny (<= 400 bytes with
+// realistic paths; scripts/measure.js budgets for it). `session` is
+// {id, port, out, tmp}: the environment zcode gives the executor and the
+// checks so parallel sessions cannot collide.
+function sessionSection(session) {
+  if (!session) return '';
+  return [
+    '## Session environment',
+    'Parallel sessions share this machine. Use these, never fixed values:',
+    `- ZCODE_PORT=${session.port}: the only port to bind (dev/preview servers)`,
+    `- ZCODE_OUT=${session.out}: build output dirs (e.g. --outDir) and test artifacts`,
+    `- ZCODE_TMP=${session.tmp}: scratch files`,
+    '',
+  ].join('\n');
+}
+
+function unitsSection(units) {
+  if (!units || !units.length) return '';
+  const lines = units.map((u) => `${u.name}: ${u.objective}${u.owns && u.owns.length ? ` (owns: ${u.owns.join(', ')})` : ''}`);
+  return `## Units\nDispatch each unit below to its own subagent (Agent tool) with that unit's objective, the binding decisions above and its owns. Run independent units in parallel, then integrate and verify the whole. Report each in handback \`units\`: [{"name", "status", "note"}].\n${bullets(lines)}\n`;
+}
+
+// Only rendered when the contract declares visual criteria.
+function visualSection(contract) {
+  if (!contract.visual || !contract.visual.length) return '';
+  const viewports = contract.viewports && contract.viewports.length ? contract.viewports : DEFAULT_VIEWPORTS;
+  return [
+    '## Visual verification',
+    'Verify the rendered result yourself with Playwright; you can look at screenshots.',
+    contract.serve
+      ? `- Serve the app with \`${contract.serve}\` on $ZCODE_PORT (it must honour that port).`
+      : '- Serve the app on $ZCODE_PORT (pick the dev/preview command from package.json; no other port).',
+    `- At each viewport (${viewports.join(', ')}) capture screenshots into $ZCODE_OUT/shots: the full page plus every key state a criterion names.`,
+    '- Look at the screenshots and judge each criterion. Fix failures, re-capture, judge again. Stop the server when done.',
+    'Criteria:',
+    bullets(contract.visual),
+    'Report in handback `visual`: [{"criterion", "viewport", "met", "note", "shot"}] (shot = screenshot path); it MUST include an entry for every criterion above.',
+    '',
+  ].join('\n');
+}
+
+const PREFLIGHT_SECTION = [
+  '## Preflight (read-only)',
+  'This turn is a preflight, not the task. Make NO edits: do not create, modify or delete files, and run nothing with side effects. Read what you need, then list every open question you would otherwise have to guess (user-visible or behavioural choices the binding decisions and context do not settle) in handback `questions`, each as {"q": "...", "options": ["A ...", "B ..."], "recommend": "A"}. Report status "blocked" with those questions, or "done" with summary "no open questions" if there are none. The orchestrator will answer, then continue this session.',
+  '',
 ].join('\n');
 
 // `ownsDisplay` are the patterns as the caller wrote them (relative to cwd).
-function buildTaskPrompt(contract, { ownsDisplay = contract.owns } = {}) {
+function buildTaskPrompt(contract, { ownsDisplay = contract.owns, session = null, preflight = false } = {}) {
   const parts = [
     'You are Zcode, an execution engine invoked by an orchestrator agent. The orchestrator owns product decisions, design direction, planning and task boundaries. You own implementation and verification inside the scope of this task. Work autonomously: there is no human watching and nobody reviews your intermediate steps.',
     '',
     `## Objective\n${contract.objective}\n`,
     section('Scope', contract.scope),
     section('Constraints', contract.constraints),
-    section('Design decisions (supplied by the orchestrator: implement them exactly; do not change them)', contract.design),
+    section('Binding decisions (made by the orchestrator: implement exactly)', [...(contract.decisions || []), ...contract.design]),
     section('Relevant files (read these first)', contract.files),
     section('References', contract.references),
     section('Context', contract.context),
     section('Acceptance criteria', contract.acceptance),
+    unitsSection(contract.units),
     ownsDisplay.length
       ? `## Workspace ownership\nYou may create, modify or delete ONLY these paths (relative to the working directory):\n${bullets(ownsDisplay)}\nOther sessions may be working in this workspace at the same time: do not touch anything else, and do not run formatters or code generators over the whole repository.\n`
       : '',
-    contract.checks.length
+    contract.touch && contract.touch.length
+      ? `## Also allowed\nYou may also make minimal edits to:\n${bullets(contract.touch)}\nReport each such edit in your handback \`changes\`. Do not use this to widen the task.\n`
+      : '',
+    sessionSection(session),
+    visualSection(contract),
+    preflight ? PREFLIGHT_SECTION : '',
+    contract.checks.length && !preflight
       ? `## Acceptance checks\nAfter you finish, Zcode will run these commands in the working directory and treat any non-zero exit as a failure. Run them yourself before you finish:\n${bullets(contract.checks.map((c) => `\`${c}\``))}\n`
       : '',
     [
       '## How to work',
       '- Make routine implementation decisions yourself. Do not stop to ask for approval of intermediate steps.',
+      '- Where the binding decisions and context leave something user-visible or behavioural open, do not guess: if it blocks the work, report "blocked" with a structured question; otherwise take the most conservative choice and list it in handback `decisions`.',
       '- Do not make product or design decisions the orchestrator has not made. If one is consequential and cannot be resolved from this task, report status "blocked" with your questions instead of guessing.',
       '- You may use the Agent tool for independent units of work. Give each subagent a bounded objective and an explicit list of files it may change; never let two subagents change the same file. A subagent reporting success is a claim: inspect its changes and verify the integrated result yourself.',
       '- Verify every acceptance criterion against the actual result. When something fails, diagnose and fix it, then verify again.',
@@ -137,37 +251,56 @@ function buildTaskPrompt(contract, { ownsDisplay = contract.owns } = {}) {
       '- Report "blocked" only when you lack information or authority that this task does not provide (for example a missing credential, a required change outside your ownership, or a consequential ambiguity).',
       '',
     ].join('\n'),
-    `## Handback\n${HANDBACK_SPEC}`,
+    `## Handback\n${HANDBACK_SPEC}${contract.visual && contract.visual.length ? '\nThe handback MUST include a `visual` entry for every declared visual criterion.' : ''}`,
   ];
   return parts.filter(Boolean).join('\n');
 }
 
-function buildRepairPrompt(failures, { attempt, maxRepairs }) {
+function buildRepairPrompt(failures, { attempt, maxRepairs, visual = [] }) {
   const blocks = failures.map((f) => {
     const why = f.timedOut ? 'timed out' : `exit ${f.exitCode}`;
     return `### \`${f.command}\` (${why})\n\`\`\`\n${f.output.trim().slice(-3000) || '(no output)'}\n\`\`\``;
   });
-  return [
-    `Zcode ran the acceptance checks and ${failures.length === 1 ? 'one failed' : `${failures.length} failed`} (repair attempt ${attempt} of ${maxRepairs}):`,
-    '',
-    ...blocks,
+  const head = failures.length
+    ? `Zcode ran the acceptance checks and ${failures.length === 1 ? 'one failed' : `${failures.length} failed`} (repair attempt ${attempt} of ${maxRepairs}):`
+    : `Your visual verification left criteria unmet (repair attempt ${attempt} of ${maxRepairs}).`;
+  const lines = [head, '', ...blocks];
+  if (visual.length) {
+    lines.push(
+      failures.length ? '' : null,
+      'Visual criteria not met (or not reported):',
+      ...visual.map((v) => `- ${v}`),
+      'Serve the app on $ZCODE_PORT again, fix the cause, re-capture the screenshots, judge them again and report `visual` for every criterion.'
+    );
+  }
+  lines.push(
     '',
-    'Diagnose the root cause and fix it within your ownership, run the checks again yourself, then finish with a fresh zcode-handback block. If the failure is outside your scope or cannot be fixed, report status "partial" or "blocked" and explain why.',
-  ].join('\n');
+    failures.length
+      ? 'Diagnose the root cause and fix it within your ownership, run the checks again yourself, then finish with a fresh zcode-handback block. If the failure is outside your scope or cannot be fixed, report status "partial" or "blocked" and explain why.'
+      : 'Finish with a fresh zcode-handback block. If a criterion cannot be met within your scope, report status "partial" or "blocked" and explain why.'
+  );
+  return lines.filter((l) => l !== null).join('\n');
 }
 
 const HANDBACK_REQUEST =
   'Your previous message did not end with a valid zcode-handback block. Do not redo any work. Reply with only the handback block describing the current state.\n\n' +
   HANDBACK_SPEC;
 
-function buildResumePrompt(message, { kind }) {
+// Cheap report-only follow-up when declared visual criteria were left out of
+// the handback (no redo, no repair budget).
+function buildVisualReportRequest(missing) {
+  return `Do not redo any work. Reply with only the handback block, including \`visual\` for every criterion: ${missing.join('; ')}\n\n` + HANDBACK_SPEC;
+}
+
+function buildResumePrompt(message, { kind, portChange = null }) {
   const note =
     'Work from earlier in this session is already applied to the workspace. Inspect the current state before repeating any step, and do not repeat external side effects.';
   if (kind !== 'task') return message;
   const body = message && message.trim()
     ? `Message from the orchestrator:\n\n${message.trim()}`
     : 'Continue the task from where you stopped.';
-  return `${body}\n\n${note}\n\n${HANDBACK_SPEC}`;
+  const env = portChange ? `\n\nZCODE_PORT is now ${portChange} (the previous port was taken); bind that one.` : '';
+  return `${body}\n\n${note}${env}\n\n${HANDBACK_SPEC}`;
 }
 
 // --- handback -------------------------------------------------------------------
@@ -184,6 +317,48 @@ const STATUS_ALIASES = new Map([
   ['blocked', 'blocked'],
 ]);
 
+const isObject = (v) => v && typeof v === 'object' && !Array.isArray(v);
+
+// Plain-string questions stay strings; structured ones are {q, options?, recommend?}.
+function question(q) {
+  if (!isObject(q) || typeof q.q !== 'string') return isObject(q) ? JSON.stringify(q) : String(q);
+  const options = Array.isArray(q.options) ? q.options.map(String) : [];
+  return {
+    q: q.q,
+    ...(options.length ? { options } : {}),
+    ...(q.recommend !== undefined && q.recommend !== null && q.recommend !== '' ? { recommend: String(q.recommend) } : {}),
+  };
+}
+
+const questionText = (q) => (typeof q === 'string' ? q : [q.q, ...(q.options || []).map((o) => `  - ${o}`), q.recommend ? `  recommend: ${q.recommend}` : null].filter(Boolean).join('\n'));
+
+function decision(d) {
+  return isObject(d) ? { what: String(d.what ?? '').trim(), why: String(d.why ?? '').trim() } : { what: String(d ?? '').trim(), why: '' };
+}
+
+// Declared visual criteria the executor did not meet. An absent report counts
+// as unmet; an entry without met:true does too.
+function visualGaps(handback, declared) {
+  if (!declared || !declared.length || !handback || handback.status === 'blocked') return { missing: [], failed: [] };
+  const entries = handback.visual || [];
+  const norm = (x) => String(x || '').trim().toLowerCase();
+  const covered = (c) => entries.some((v) => {
+    const a = norm(v.criterion);
+    return a && (a === norm(c) || a.includes(norm(c)) || norm(c).includes(a));
+  });
+  return {
+    missing: declared.filter((c) => !covered(c)),
+    failed: entries
+      .filter((v) => v.met !== true)
+      .map((v) => `${v.criterion || '(unnamed)'}${v.viewport ? ` @${v.viewport}` : ''}`),
+  };
+}
+
+function unmetVisual(handback, declared) {
+  const { missing, failed } = visualGaps(handback, declared);
+  return [...failed, ...missing.map((c) => `${c} (not reported)`)];
+}
+
 // Returns {handback, report, error}: the LAST block wins; `report` is the
 // response text with the block removed.
 function parseHandback(text) {
@@ -211,7 +386,10 @@ function parseHandback(text) {
       checks: arr(raw.checks),
       criteria: arr(raw.criteria),
       unresolved: arr(raw.unresolved).map(String),
-      questions: arr(raw.questions).map(String),
+      questions: arr(raw.questions).map(question),
+      decisions: arr(raw.decisions).map(decision).filter((d) => d.what),
+      units: arr(raw.units).filter(isObject),
+      visual: arr(raw.visual).filter(isObject),
       notes: typeof raw.notes === 'string' ? raw.notes : '',
     },
     report,
@@ -241,6 +419,9 @@ function deriveStatus({
   handbackError = null,
   checks = [],
   scopeViolations = [],
+  preflight = false,
+  preflightWrote = [],
+  visualDeclared = [],
 }) {
   const issues = [];
   if (cancelled) return { status: 'cancelled', issues: ['cancelled before completion'] };
@@ -250,6 +431,16 @@ function deriveStatus({
   if (error) return { status: 'failed', issues: [error.message || String(error)] };
   if (kind !== 'task') return { status: 'completed', issues };
 
+  if (preflight) {
+    if (preflightWrote.length) {
+      return { status: 'failed', issues: [`preflight must be read-only but changed: ${preflightWrote.join(', ')}`] };
+    }
+    if (!handback) return { status: 'unverified', issues: [`no usable handback from the executor (${handbackError || 'missing'})`] };
+    if (handback.status === 'blocked' || handback.questions.length) {
+      return { status: 'blocked', issues: ['preflight found open questions (see questions)'] };
+    }
+    return { status: 'completed', issues };
+  }
   if (handback && handback.status === 'blocked') {
     return { status: 'blocked', issues: ['the executor reported it is blocked (see questions)'] };
   }
@@ -270,6 +461,11 @@ function deriveStatus({
     partial = true;
     issues.push(`unmet acceptance criteria: ${unmet.map((c) => c.criterion).join('; ')}`);
   }
+  const visualUnmet = unmetVisual(handback, visualDeclared);
+  if (visualUnmet.length) {
+    partial = true;
+    issues.push(`visual criteria unmet: ${visualUnmet.join('; ')}`);
+  }
   if (scopeViolations.length) {
     partial = true;
     issues.push(`changed files outside the owned scope: ${scopeViolations.join(', ')}`);
@@ -290,7 +486,14 @@ function deriveStatus({
 
 module.exports = {
   ContractError,
+  sessionSection,
   CONTRACT_KEYS,
+  DEFAULT_VIEWPORTS,
+  parseUnit,
+  questionText,
+  unmetVisual,
+  visualGaps,
+  buildVisualReportRequest,
   normalizeContract,
   buildTaskPrompt,
   buildRepairPrompt,