@0xgeorgemathew/zcode 0.5.0 → 0.6.0

package/lib/contract.js

@@ -189,21 +189,35 @@ function unitsSection(units) {
   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) {
+// Only rendered when the contract declares visual criteria. zcode itself
+// decides `visual`: an independent image-capable verifier judges the result
+// from its own screenshots after the work (lib/verify.js).
+function visualSection(contract, { canSee = true } = {}) {
   if (!contract.visual || !contract.visual.length) return '';
   const viewports = contract.viewports && contract.viewports.length ? contract.viewports : DEFAULT_VIEWPORTS;
+  const serve = contract.serve
+    ? `- Make sure the app serves with \`${contract.serve}\` on $ZCODE_PORT (it must honour that port).`
+    : '- Make sure the app serves on $ZCODE_PORT (pick the dev/preview command from package.json; no other port).';
+  if (!canSee) {
+    return [
+      '## Visual verification',
+      'You cannot see images. Do not judge screenshots or report `visual`; an independent vision verifier will.',
+      serve,
+      '- Self-check visibility in the DOM: key text must have a non-zero box inside the viewport, not clipped by an overflow ancestor, computed opacity > 0, visibility visible, after animations finish.',
+      `Viewports: ${viewports.join(', ')}. Criteria the verifier will judge:`,
+      bullets(contract.visual),
+      '',
+    ].join('\n');
+  }
   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).',
+    'Verify the rendered result yourself with Playwright; you can look at screenshots. An independent verifier will re-judge it from its own screenshots afterwards.',
+    serve,
     `- 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.',
+    'You may report handback `visual`: [{"criterion", "viewport", "met", "note", "shot"}]; it is not required.',
     '',
   ].join('\n');
 }
@@ -215,7 +229,7 @@ const PREFLIGHT_SECTION = [
 ].join('\n');
 
 // `ownsDisplay` are the patterns as the caller wrote them (relative to cwd).
-function buildTaskPrompt(contract, { ownsDisplay = contract.owns, session = null, preflight = false } = {}) {
+function buildTaskPrompt(contract, { ownsDisplay = contract.owns, session = null, preflight = false, canSeeImages = true } = {}) {
   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.',
     '',
@@ -235,7 +249,7 @@ function buildTaskPrompt(contract, { ownsDisplay = contract.owns, session = null
       ? `## 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),
+    visualSection(contract, { canSee: canSeeImages }),
     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`
@@ -251,11 +265,12 @@ function buildTaskPrompt(contract, { ownsDisplay = contract.owns, session = null
       '- 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}${contract.visual && contract.visual.length ? '\nThe handback MUST include a `visual` entry for every declared visual criterion.' : ''}`,
+    `## Handback\n${HANDBACK_SPEC}`,
   ];
   return parts.filter(Boolean).join('\n');
 }
 
+// `visual`: the verifier's unmet entries {criterion, viewport, seen, note, shot}.
 function buildRepairPrompt(failures, { attempt, maxRepairs, visual = [] }) {
   const blocks = failures.map((f) => {
     const why = f.timedOut ? 'timed out' : `exit ${f.exitCode}`;
@@ -263,14 +278,21 @@ function buildRepairPrompt(failures, { attempt, maxRepairs, visual = [] }) {
   });
   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}).`;
+    : `An independent visual verifier, looking at screenshots of the running app, found 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.'
+      'Visual criteria the verifier found unmet:',
+      ...visual.map((v) => {
+        const text = [
+          v.seen ? `saw: ${JSON.stringify(String(v.seen).slice(0, 300))}` : null,
+          v.note ? String(v.note).slice(0, 300) : null,
+          v.shot ? `shot: ${v.shot}` : null,
+        ].filter(Boolean).join(' | ');
+        return `- ${v.criterion || '(unnamed)'}${v.viewport ? ` @${v.viewport}` : ''}${text ? ` - ${text}` : ''}`;
+      }),
+      'Fix the cause. Zcode will re-run the checks and the verifier will look again; its screenshots are the evidence, not DOM presence.'
     );
   }
   lines.push(
@@ -286,12 +308,6 @@ 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;
 
-// 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.';
@@ -336,27 +352,29 @@ 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 || [];
+// Visual verdicts (zcode's verifier entries) against the declared criteria.
+// `failed`: entries judged unmet (met:false); `unverified`: entries the
+// verifier could not judge (met:null); `missing`: declared criteria no entry
+// covers. Entries not met:true include the built-in readability criterion.
+function visualGaps(entries, declared) {
+  const list = Array.isArray(entries) ? entries : [];
   const norm = (x) => String(x || '').trim().toLowerCase();
-  const covered = (c) => entries.some((v) => {
+  const covered = (c) => list.some((v) => {
     const a = norm(v.criterion);
     return a && (a === norm(c) || a.includes(norm(c)) || norm(c).includes(a));
   });
+  const label = (v) => `${v.criterion || '(unnamed)'}${v.viewport ? ` @${v.viewport}` : ''}`;
   return {
-    missing: declared.filter((c) => !covered(c)),
-    failed: entries
-      .filter((v) => v.met !== true)
-      .map((v) => `${v.criterion || '(unnamed)'}${v.viewport ? ` @${v.viewport}` : ''}`),
+    missing: (declared || []).filter((c) => !covered(c)),
+    failed: list.filter((v) => v.met === false),
+    unverified: list.filter((v) => v.met === null).map(label),
   };
 }
 
-function unmetVisual(handback, declared) {
-  const { missing, failed } = visualGaps(handback, declared);
-  return [...failed, ...missing.map((c) => `${c} (not reported)`)];
+// Strings for what is unmet: failed entries and declared criteria nobody judged.
+function unmetVisual(entries, declared) {
+  const { missing, failed } = visualGaps(entries, declared);
+  return [...failed.map((v) => `${v.criterion || '(unnamed)'}${v.viewport ? ` @${v.viewport}` : ''}`), ...missing.map((c) => `${c} (not reported)`)];
 }
 
 // Returns {handback, report, error}: the LAST block wins; `report` is the
@@ -422,6 +440,7 @@ function deriveStatus({
   preflight = false,
   preflightWrote = [],
   visualDeclared = [],
+  visual = [],
 }) {
   const issues = [];
   if (cancelled) return { status: 'cancelled', issues: ['cancelled before completion'] };
@@ -461,10 +480,17 @@ 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 (handback && visualDeclared.length) {
+    const gaps = visualGaps(visual, visualDeclared);
+    const unmet = unmetVisual(visual, visualDeclared);
+    if (unmet.length) {
+      partial = true;
+      issues.push(`visual criteria unmet: ${unmet.join('; ')}`);
+    }
+    if (gaps.unverified.length) {
+      partial = true;
+      issues.push(`visual not verified: ${gaps.unverified.join('; ')}`);
+    }
   }
   if (scopeViolations.length) {
     partial = true;
@@ -493,7 +519,6 @@ module.exports = {
   questionText,
   unmetVisual,
   visualGaps,
-  buildVisualReportRequest,
   normalizeContract,
   buildTaskPrompt,
   buildRepairPrompt,

package/lib/executor.js

@@ -28,6 +28,7 @@ const {
   liveLeases,
   snapshot,
   diffSnapshots,
+  ensureLocalExclude,
 } = require('./workspace.js');
 const {
   buildTaskPrompt,
@@ -36,10 +37,10 @@ const {
   HANDBACK_REQUEST,
   parseHandback,
   deriveStatus,
-  unmetVisual,
   visualGaps,
-  buildVisualReportRequest,
 } = require('./contract.js');
+const { buildVerifierPrompt, parseVisualBlock, notVerified: notVerifiedEntries } = require('./verify.js');
+const { visionModel, supportsImage } = require('./models.js');
 
 const RESULT_SCHEMA = 'zcode.result/1';
 const SUBAGENT_TOOLS = new Set(['Agent', 'Task']);
@@ -131,6 +132,31 @@ function sumUsage(turns) {
   return input === null && output === null ? null : { inputTokens: input, outputTokens: output };
 }
 
+// Model requests and tokens over every turn of an invocation, failed ones
+// included (their usage never arrived: `incomplete`). null = nothing ran.
+function usageOf(turns, failedTurns) {
+  const all = [...turns, ...failedTurns];
+  if (!all.length) return null;
+  const base = sumUsage(turns) || { inputTokens: null, outputTokens: null };
+  const incomplete = all.some((t) => !t.usage);
+  return {
+    ...base,
+    modelRequests: all.reduce((n, t) => n + (t.modelRequests || 0), 0),
+    ...(incomplete ? { incomplete: true } : {}),
+  };
+}
+
+// Running totals across invocations (resumes) kept on the session record.
+function addUsageTotal(prior, usage) {
+  const p = prior || {};
+  const u = usage || {};
+  return {
+    inputTokens: (p.inputTokens || 0) + (u.inputTokens || 0),
+    outputTokens: (p.outputTokens || 0) + (u.outputTokens || 0),
+    modelRequests: (p.modelRequests || 0) + (u.modelRequests || 0),
+  };
+}
+
 function exitCodeFor(result) {
   switch (result.status) {
     case 'completed':
@@ -231,31 +257,42 @@ async function execute(inv, opts = {}) {
   let lastWrite = 0;
   let toolCalls = record.activity ? record.activity.toolCalls || 0 : 0;
   let subagentsStarted = record.activity ? record.activity.subagentsStarted || 0 : 0;
+  let modelRequests = record.activity ? record.activity.modelRequests || 0 : 0;
+  let subagentsRunning = 0;
   let lastTool = null;
+  let lastToolAt = null;
+  let lastEventAt = null;
+  const activity = () => ({
+    toolCalls, subagentsStarted, subagentsRunning, modelRequests, lastTool, lastToolAt,
+    lastEventAt: lastEventAt || new Date().toISOString(),
+  });
   const relay = (ev) => {
     emit(ev);
-    if (ev.type === 'stream') return;
+    const now = Date.now();
+    lastEventAt = new Date(now).toISOString(); // any engine event counts as life
+    if (ev.type === 'model_request_started') modelRequests++;
     if (ev.type === 'tool') {
       if (ev.phase === 'started') {
         toolCalls++;
         lastTool = ev.name;
+        lastToolAt = new Date(now).toISOString();
         if (SUBAGENT_TOOLS.has(ev.name)) {
           subagentsStarted++;
+          subagentsRunning++;
           emit({ type: 'subagent', phase: 'started', toolCallId: ev.id });
         }
       } else if ((ev.phase === 'result' || ev.phase === 'error') && SUBAGENT_TOOLS.has(ev.name)) {
+        subagentsRunning = Math.max(0, subagentsRunning - 1);
         emit({ type: 'subagent', phase: ev.phase === 'result' ? 'returned' : 'error', toolCallId: ev.id });
       }
     }
-    if (ev.type === 'model_request_started' || ev.type === 'state' || ev.type === 'turn') return;
     try {
-      store.appendEvent(id, ev, env);
-      const now = Date.now();
+      if (!(ev.type === 'stream' || ev.type === 'model_request_started' || ev.type === 'state' || ev.type === 'turn')) {
+        store.appendEvent(id, ev, env);
+      }
       if (now - lastWrite > 1000) {
         lastWrite = now;
-        update({
-          activity: { toolCalls, subagentsStarted, lastTool, lastEventAt: new Date(now).toISOString() },
-        });
+        update({ activity: activity() });
       }
     } catch {
       /* activity is best-effort; never fail the run over it */
@@ -266,7 +303,8 @@ async function execute(inv, opts = {}) {
     emit(ev);
     try {
       store.appendEvent(id, ev, env);
-      update({ phase, activity: { toolCalls, subagentsStarted, lastTool, lastEventAt: new Date().toISOString() } });
+      lastEventAt = new Date().toISOString();
+      update({ phase, phaseDetail: Object.keys(detail).length ? detail : null, activity: activity() });
     } catch {
       /* best-effort */
     }
@@ -328,10 +366,13 @@ async function execute(inv, opts = {}) {
   }
 
   update({ state: 'running', phase: 'starting' });
+  ensureLocalExclude(record.cwd);
 
   let client = null;
   let session = null;
   const turns = [];
+  const vturns = []; // independent verifier turns (never the implementer's)
+  const failedTurns = []; // turns that threw: only their partial facts survive
   let checks = [];
   let repairs = 0;
   let parsed = { handback: null, report: '', error: 'missing' };
@@ -345,7 +386,11 @@ async function execute(inv, opts = {}) {
   let sessionEnv = null;
   const visualDeclared = (inv.contract && inv.contract.visual) || [];
   const concurrent = new Map(lease.others.map((o) => [o.id, o.owns || []]));
-  const checkTouched = new Set(); // files written by zcode's own check runs
+  const checkTouched = new Set(); // files written by zcode's own check runs and the verifier
+  const verifierEdits = new Set();
+  let verifierModel = null;
+  let verifyRounds = 0;
+  let visualEntries = null; // the verifier's verdicts: authoritative `visual`
   const invocationStart = new Date(started).toISOString();
 
   try {
@@ -379,6 +424,7 @@ async function execute(inv, opts = {}) {
       browser: !inv.noBrowser,
       skillsDirs: inv.skillsDirs || [],
       noSkills: inv.noSkills,
+      model: inv.model,
     });
     before = snapshot(root);
 
@@ -415,6 +461,7 @@ async function execute(inv, opts = {}) {
         ownsDisplay: inv.ownsDisplay || [],
         session: { id, port: sessionEnv.ZCODE_PORT, out: sessionEnv.ZCODE_OUT, tmp: sessionEnv.ZCODE_TMP },
         preflight,
+        canSeeImages: supportsImage(inv.model, { env, builtinConfig: runtime.builtinConfig }),
       });
       prompt = leavingPreflight
         ? `${taskPrompt()}\n\n## Answers to your preflight questions\nThe preflight is over: implement the task now (edits are allowed). The orchestrator's answers are binding:\n${(inv.resume.message || '').trim() || '(none: take the most conservative choice for anything open and list it in handback `decisions`)'}`
@@ -435,8 +482,67 @@ async function execute(inv, opts = {}) {
       prompt = inv.resume ? buildResumePrompt(inv.resume.message, { kind: 'run' }) : inv.prompt;
     }
 
+    // One verifier round: a NEW engine session (own client: fresh context,
+    // separate from the implementer's) on the first image-capable model.
+    // Returns an entry per criterion; failures become met:null, never false.
+    const verifyVisual = async (round) => {
+      verifierModel = visionModel({ env, builtinConfig: runtime.builtinConfig });
+      verifyRounds = round;
+      setPhase('verifying', { round });
+      const vprompt = buildVerifierPrompt(inv.contract, {
+        session: { id, port: sessionEnv.ZCODE_PORT, out: sessionEnv.ZCODE_OUT, tmp: sessionEnv.ZCODE_TMP },
+        round,
+      });
+      const preSnap = before ? snapshot(root) : null;
+      let entries = null;
+      let why = 'verifier did not run';
+      for (let attempt = 1; attempt <= 2 && !entries; attempt++) {
+        if ((signal && signal.aborted) || Date.now() >= deadline) break;
+        let vclient = null;
+        try {
+          vclient = makeClient(runtime, { home, cwd: record.cwd, sessionEnv });
+          vclient.start();
+          const vsession = await openSession(vclient, {
+            workspacePath: record.cwd,
+            modelId: verifierModel,
+            effort: 'high',
+            requiredMcp: built.mcp.added,
+            onEvent: relay,
+          });
+          const vturn = await runTurn(vclient, vsession, {
+            modelId: verifierModel,
+            effort: 'high',
+            prompt: vprompt,
+            deadline,
+            signal,
+            onEvent: relay,
+          });
+          vturns.push(vturn);
+          const p = parseVisualBlock(vturn.response);
+          if (p.error) why = `the verifier gave no usable zcode-visual block (${p.error})`;
+          else entries = p.entries;
+        } catch (err) {
+          if (err && err.turn) failedTurns.push(err.turn);
+          if (err && (err.kind === 'timeout' || err.kind === 'cancelled')) throw err;
+          why = `verifier failed: ${scrub(err && err.message ? err.message : String(err)).slice(0, 200)}`;
+        } finally {
+          if (vclient) vclient.kill();
+        }
+      }
+      if (preSnap) {
+        const owned = (p) => [...concurrent.values()].some((o) => o.length && isOwned(p, o));
+        for (const f of diffSnapshots(preSnap, snapshot(root)) || []) {
+          if (isZcodePath(f.path) || owned(f.path)) continue;
+          verifierEdits.add(f.path);
+          checkTouched.add(f.path); // verifier edits are an issue, not a task scope violation
+        }
+      }
+      const got = entries || [];
+      const gaps = visualGaps(got, visualDeclared);
+      return [...got, ...notVerifiedEntries(gaps.missing, entries ? 'the verifier did not report it' : why)];
+    };
+
     let askedForHandback = false;
-    let askedForVisual = false;
     let phase = 'executing';
     for (;;) {
       setPhase(phase, phase === 'repairing' ? { attempt: repairs, of: inv.maxRepairs } : {});
@@ -484,18 +590,15 @@ async function execute(inv, opts = {}) {
         }
       }
       const failures = checks.filter((c) => !c.ok);
-      // Unmet visual criteria share the repair budget with failing checks.
-      const gaps = visualGaps(parsed.handback, visualDeclared);
-      // Criteria merely left out of the handback get one cheap report-only
-      // follow-up that does not consume the repair budget.
-      if (!failures.length && gaps.missing.length && !gaps.failed.length && !askedForVisual
+      // zcode, not the implementer, judges the visual criteria. Unmet ones
+      // share the repair budget with failing checks; a verifier that could
+      // not run (met:null) is reported, not repaired.
+      let visualUnmet = [];
+      if (visualDeclared.length && !failures.length && parsed.handback
           && !(signal && signal.aborted) && Date.now() < deadline) {
-        askedForVisual = true;
-        prompt = buildVisualReportRequest(gaps.missing);
-        phase = 'reporting';
-        continue;
+        visualEntries = await verifyVisual(verifyRounds + 1);
+        visualUnmet = visualEntries.filter((v) => v.met === false);
       }
-      const visualUnmet = unmetVisual(parsed.handback, visualDeclared);
       if ((!failures.length && !visualUnmet.length) || repairs >= inv.maxRepairs) break;
       if ((signal && signal.aborted) || Date.now() >= deadline) break;
       repairs++;
@@ -515,6 +618,7 @@ async function execute(inv, opts = {}) {
     }
   } catch (err) {
     error = err;
+    if (err && err.turn) failedTurns.push(err.turn);
   } finally {
     if (client) client.kill();
     if (releasePort) releasePort();
@@ -586,11 +690,20 @@ async function execute(inv, opts = {}) {
     preflight,
     preflightWrote,
     visualDeclared,
+    visual: visualEntries || [],
   });
 
   let errorOut = null;
   if (status === 'failed') {
-    if (error) errorOut = { kind: error.kind || 'error', message: scrub(error.message) };
+    if (error && error.kind === 'timeout') {
+      // The work already on disk is kept; resuming continues from it.
+      const plan = /^plan:(\S+)/.exec(inv.label || record.label || '');
+      const cmd = plan ? `zcode plan resume ${plan[1]} "continue"` : `zcode resume ${id} "continue"`;
+      errorOut = {
+        kind: 'timeout',
+        message: `timed out after ${Math.round(inv.timeoutMs / 60000)} min; "${cmd}" picks up from the current files`,
+      };
+    } else if (error) errorOut = { kind: error.kind || 'error', message: scrub(error.message) };
     else if (preflightWrote.length) errorOut = { kind: 'preflight_wrote', message: issues[0] };
     else if (checks.some((c) => !c.ok)) errorOut = { kind: 'checks_failed', message: issues[0] };
   } else if (status === 'cancelled') {
@@ -619,18 +732,23 @@ async function execute(inv, opts = {}) {
       notVerified.push(`unit results are executor claims: ${handback.units.map((u) => `${u.name} ${u.status || '?'}`).join(', ')}; only the integrated result is verified`);
     }
     if (visualDeclared.length) {
-      const reported = handback ? handback.visual : [];
-      notVerified.push(`visual criteria are the executor's judgement from its own screenshots (${reported.filter((v) => v.met === true).length} of ${reported.length} reported met); zcode ran no pixel check`);
+      const judged = visualEntries || [];
+      notVerified.push(visualEntries
+        ? `visual criteria judged by an independent ${verifierModel} verifier from its own screenshots (${judged.filter((v) => v.met === true).length} of ${judged.length} met)`
+        : 'visual criteria were not judged: the independent verifier did not run');
     }
   }
   if (before && !diff) notVerified.push('changed files could not be tracked in this workspace');
   if (subagentNote) issues.push(subagentNote);
+  if (verifierEdits.size) issues.push(`verifier edited files: ${[...verifierEdits].join(', ')}`);
 
   const last = turns[turns.length - 1] || null;
   const response = last ? last.response : '';
   const questions = [...(handback ? handback.questions : [])];
   if (userInput) questions.push(userInput);
 
+  const usage = usageOf([...turns, ...vturns], failedTurns);
+  const usageTotal = addUsageTotal(record.usageTotal, usage);
   const result = {
     type: 'result',
     schema: RESULT_SCHEMA,
@@ -655,7 +773,9 @@ async function execute(inv, opts = {}) {
     touched,
     ...(preflight ? { preflight: true } : {}),
     decisions: handback ? handback.decisions : [],
-    visual: handback ? handback.visual : [],
+    visual: visualEntries || [],
+    executorVisual: handback ? handback.visual : [],
+    ...(visualDeclared.length ? { verifier: { model: verifierModel, rounds: verifyRounds } } : {}),
     units: handback ? handback.units : [],
     sessionEnv: sessionEnv
       ? { port: Number(sessionEnv.ZCODE_PORT), out: sessionEnv.ZCODE_OUT, tmp: sessionEnv.ZCODE_TMP }
@@ -684,7 +804,8 @@ async function execute(inv, opts = {}) {
     effort: (last && last.engineReasoningLevel) || inv.effort,
     effortRequested: inv.effort,
     mode: session ? session.mode : null,
-    usage: sumUsage(turns),
+    usage,
+    usageTotal,
     reasoningChars: turns.reduce((n, t) => n + t.reasoningChars, 0),
     toolCalls: turns.some((t) => typeof t.toolCallCount === 'number')
       ? turns.reduce((n, t) => n + (t.toolCallCount || 0), 0)
@@ -709,7 +830,9 @@ async function execute(inv, opts = {}) {
     state: 'finished',
     phase: 'done',
     status,
-    activity: { toolCalls, subagentsStarted, lastTool, lastEventAt: new Date().toISOString() },
+    usageTotal,
+    phaseDetail: null,
+    activity: activity(),
     outcome: {
       status,
       summary: result.summary,

package/lib/help.js

@@ -0,0 +1,111 @@
+'use strict';
+// Per-command help: `zcode <command> --help` prints the command's usage and
+// only the flags that apply to it (each text <= 2000 bytes). The full text
+// (bin/zcode.js USAGE) is for `zcode --help` with no command.
+const SESSION = `  --id <id>        name the session (existing id is never re-run: use resume)
+  --label <text>   free-form label shown in status
+  --detach         start in the background, print the id, exit 0
+  --cwd <dir>      workspace (default: current dir)
+  --owns <path>    repeatable: paths this session may change (default: whole workspace)
+  --allow-overlap  start despite overlapping ownership`;
+const EXEC = `  --model <id>     glm-5.3 | glm-5.3-flash (default glm-5.3-flash)
+  --effort <lvl>   low | high | max (default max)
+  --mcp <json|@f>  add MCP servers (repeatable)   --mcp-inherit   --no-browser
+  --skills <dir>   add skills (repeatable)        --no-skills
+  --json           NDJSON events; last line is the compact brief (--full: whole record)
+  --quiet          no progress feed; with --json only the result line`;
+
+const HELP = {
+  task: `usage: zcode task [options] <objective...>
+Execute a task contract, verify it with zcode-run checks, hand back.
+
+contract:
+  --task <file|->       JSON contract or markdown brief (- = stdin)
+  --accept <text>       repeatable acceptance criterion
+  --check <command>     repeatable shell check zcode runs after the work
+  --file <path>         repeatable file to read first
+  --context <text|@f>   repeatable context   --decision <text> / --decisions <@f>
+  --touch <path>        repeatable minimal edits allowed outside --owns
+  --unit "n: goal [owns a,b]"  repeatable subagent unit
+  --visual <criterion>  repeatable   --viewport <WxH>   --serve <cmd>
+  --preflight           read-only: list open questions, no edits
+  --max-repairs <n>     default 2     --check-timeout-ms <n>  default 300000
+session:
+${SESSION}
+  --timeout-ms <n>      whole invocation (default 7200000 = 2 h)
+${EXEC}
+Full reference: zcode --help`,
+  run: `usage: zcode [run] [options] <prompt...>
+One-shot turn (prompt via stdin when piped).
+  --session <id>   continue a session
+  --timeout-ms <n> default 600000
+  --thinking | --no-thinking   mirror reasoning to stderr
+${SESSION}
+${EXEC}
+Full reference: zcode --help`,
+  agent: `usage: zcode agent [options] <instructions...>
+Turn that MUST dispatch a subagent.
+  --profile <name> subagent profile (default general-purpose)
+  --timeout-ms <n> default 600000
+${SESSION}
+${EXEC}
+Full reference: zcode --help`,
+  resume: `usage: zcode resume <id> [message...]
+Continue a session: answer questions, follow up, or retry after a timeout.
+Pass "-" as the message to read it from stdin.
+  --timeout-ms <n>  --max-repairs <n>  --check-timeout-ms <n>
+  --model <id>  --effort <lvl>
+  --json  --full  --quiet  --include-reasoning
+Start-time flags (--id, --owns, --cwd, ...) cannot change on resume.`,
+  status: `usage: zcode status [<id>] [--all] [--json]
+One session in detail, or the 15 most recent (--all: every session).
+  --json   machine-readable list or detail`,
+  wait: `usage: zcode wait <id...> [--any] [--json] [--full] [--timeout-ms n]
+Block until sessions finish; print each handback.
+  --any            return when the FIRST id finishes
+  --timeout-ms <n> one line per pending session, exit 124
+  --json           briefs   --full  full records`,
+  watch: `usage: zcode watch [<id>… | --plan <name>] [--stall-min n]
+Live view of sessions, no model tokens. One line each:
+  id  state phase[ n/m]  elapsed  last: <tool> <age> ago  req <n>  sub <running>
+STALLED? is appended when a running session has had no engine event for
+--stall-min minutes (default 8). Nothing is done automatically.
+  <id…>        the sessions to watch
+  --plan name  every session of a plan
+  (no args)    live sessions and those finished in the last 10 minutes
+TTY: redraws every 2 s. Piped: a line is printed only when a session changes.
+Exits 0 when every watched session has finished; Ctrl-C exits 0.`,
+  result: `usage: zcode result <id> [--json] [--full]
+Print a finished session's handback without waiting (exit 7 if running).
+  --json  compact brief   --full  the whole record`,
+  cancel: `usage: zcode cancel <id> [--json]
+Stop a running session (SIGTERM, SIGKILL after 15 s). No-op when finished.`,
+  plan: `usage: zcode plan <subcommand>
+  zcode plan check <file>              validate (ids, after, cycles, owns, effort)
+  zcode plan run <file> [--preflight] [--detach] [--timeout-ms n] [--id name] [--json]
+  zcode plan wait|status <name> [--timeout-ms n] [--json]
+  zcode plan resume <name> [message...] [--session <id>]
+plan file: {cwd?, decisions?, context?, files?, model?, effort?, limits?,
+  sessions:[{id, after?:[ids], label?, ...task contract keys}]}
+  top-level decisions/context/files are prepended to every session; limits
+  ({timeoutMs,maxRepairs,checkTimeoutMs}) default every session; "@file"
+  resolves next to the plan file, then against its cwd.
+  --preflight  read-only preflight of every session (sessions with "after"
+               are told to assume their prerequisites)
+  --detach     supervise in a background process
+  --id <name>  plan name (default: file basename)
+  --cwd <dir>  workspace override
+Exit: 0 completed, 10 blocked, 8 partial/failed, 124 timeout.`,
+  login: `usage: zcode login
+Read the API key from stdin and store it in the credentials file.`,
+  doctor: `usage: zcode doctor [--json]
+Engine, isolation and key report.`,
+  skills: `usage: zcode skills [install|uninstall] [claude|codex]
+Install the orchestrator skills (default: show status).`,
+};
+
+function commandHelp(command) {
+  return HELP[command] || null;
+}
+
+module.exports = { commandHelp };