@0xgeorgemathew/zcode 0.5.0 → 0.6.0

package/lib/isolation.js

@@ -19,6 +19,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
+const { DEFAULT_MODEL } = require('./models.js');
 
 // The desktop app's live directory. ZAI_CODE_LIVE_DIR points elsewhere
 // (e.g. a second desktop profile, or a fixture in tests).
@@ -215,6 +216,19 @@ function isDanglingLink(p) {
 // Playwright into a dead end.
 const HOST_ONLY_SKILLS = new Set(['control-browser']);
 
+// Rewrites the frontmatter `model:` of an agent profile when it names
+// GLM-5.3 / GLM-5.3-Flash (any prefix: "account:x/GLM-5.3",
+// "custom:account%3Ax:GLM-5.3") so its model part is `model`.
+function pinAgentModel(text, model) {
+  const m = /^(---\r?\n)([\s\S]*?)(\r?\n---)/.exec(text);
+  if (!m) return text;
+  const front = m[2].replace(/^(\s*model\s*:\s*["']?)([^\n"']*?)(?:\/|:)GLM-5\.3(?:-Flash)?(["']?\s*)$/im, (all, a, prefix, tail) => {
+    const sep = all.slice(a.length + prefix.length, a.length + prefix.length + 1);
+    return `${a}${prefix}${sep}${model}${tail}`;
+  });
+  return m[1] + front + text.slice(m[0].length - m[3].length);
+}
+
 function buildEngineHome({
   home,
   root,
@@ -225,6 +239,7 @@ function buildEngineHome({
   browser = true,
   skillsDirs = [],
   noSkills = false,
+  model = DEFAULT_MODEL,
 }) {
   const zdir = path.join(home, '.zcode');
   const v2 = path.join(zdir, 'v2');
@@ -263,7 +278,10 @@ function buildEngineHome({
   for (const entry of listDir(path.join(live, 'agents'))) {
     if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
     fs.mkdirSync(agentsDir, { recursive: true });
-    fs.copyFileSync(path.join(live, 'agents', entry.name), path.join(agentsDir, entry.name));
+    // Profiles pinning a GLM-5.3 id would silently run another model than
+    // the session's: the copy follows the session (the live file is never edited).
+    const text = fs.readFileSync(path.join(live, 'agents', entry.name), 'utf8');
+    fs.writeFileSync(path.join(agentsDir, entry.name), pinAgentModel(text, model));
   }
   const agentsMd = path.join(zdir, 'AGENTS.md');
   if (fs.existsSync(path.join(live, 'AGENTS.md'))) {
@@ -393,6 +411,7 @@ function engineEnv({ home, builtinProviderConfig, parentEnv = process.env, sessi
 
 module.exports = {
   buildEngineHome,
+  pinAgentModel,
   engineEnv,
   rootDir,
   liveDir,

package/lib/models.js

@@ -115,6 +115,45 @@ function modelLevels(opts) {
   return Object.fromEntries(OFFICIAL_IDS.map((id) => [id, supportedEfforts(id, opts)]));
 }
 
+// --- image input per model ---------------------------------------------------
+//
+// Same resolution as reasoning levels: modelRules[].config.properties
+// .inputFormat.supportsImage, last matching rule that sets it wins (the
+// generic `glm-5.3(-flash)?` rule says false, the later `glm-5.3-flash` rule
+// true). GLM-5.3 cannot see images: reading a PNG returns only an upload
+// confirmation, so it must never be the judge of a screenshot.
+const FALLBACK_IMAGES = { 'GLM-5.3': false, 'GLM-5.3-Flash': true };
+
+function supportsImage(model, { env = process.env, builtinConfig } = {}) {
+  const file = builtinConfig || builtinConfigPath(env);
+  let value = null;
+  if (file) {
+    for (const rule of readRules(file)) {
+      let match = false;
+      try {
+        match = new RegExp(`^(?:${rule.modelMatch})$`, 'i').test(model);
+      } catch {
+        /* a malformed pattern matches nothing */
+      }
+      if (!match) continue;
+      const v = rule.config && rule.config.properties && rule.config.properties.inputFormat
+        && rule.config.properties.inputFormat.supportsImage;
+      if (typeof v === 'boolean') value = v;
+    }
+  }
+  return value === null ? FALLBACK_IMAGES[model] === true : value;
+}
+
+// {modelId: bool} for every supported model (doctor).
+function modelVision(opts) {
+  return Object.fromEntries(OFFICIAL_IDS.map((id) => [id, supportsImage(id, opts)]));
+}
+
+// The first image-capable model: judges screenshots for the visual verifier.
+function visionModel(opts) {
+  return OFFICIAL_IDS.find((id) => supportsImage(id, opts)) || DEFAULT_MODEL;
+}
+
 // null when `effort` is usable with `model`, else the one-line refusal.
 // `source` names where the value came from ("--effort", "contract effort").
 function effortProblem(model, effort, { source = '--effort', ...opts } = {}) {
@@ -124,6 +163,9 @@ function effortProblem(model, effort, { source = '--effort', ...opts } = {}) {
 }
 
 module.exports = {
+  supportsImage,
+  modelVision,
+  visionModel,
   supportedEfforts,
   modelLevels,
   effortProblem,

package/lib/plan.js

@@ -22,7 +22,7 @@ const { normalizeModel, normalizeEffort, effortProblem, unknownModelMessage, DEF
 const { buildBrief } = require('./brief.js');
 
 const BIN = path.join(__dirname, '..', 'bin', 'zcode.js');
-const PLAN_KEYS = ['cwd', 'decisions', 'context', 'files', 'model', 'effort', 'sessions'];
+const PLAN_KEYS = ['cwd', 'decisions', 'context', 'files', 'model', 'effort', 'limits', 'sessions'];
 const POLL_MS = 500;
 
 class PlanError extends Error {}
@@ -65,10 +65,10 @@ const sessionList = (plan) => (Array.isArray(plan.sessions) ? plan.sessions.filt
 const afterOf = (s) => toArray(s.after).map(String);
 
 // The session's contract object: top-level decisions/context/files first,
-// the plan's model/effort as defaults. `id` and `after` are plan keys, not
-// contract keys.
+// the plan's model/effort/limits as defaults (a session's own limits win per
+// key). `id`, `after` and `label` are plan keys, not contract keys.
 function sessionBase(r, s) {
-  const { id, after, ...rest } = s;
+  const { id, after, label, ...rest } = s;
   const top = r.plan;
   const base = { ...rest };
   for (const key of ['decisions', 'context', 'files']) {
@@ -78,6 +78,9 @@ function sessionBase(r, s) {
   for (const key of ['model', 'effort']) {
     if (base[key] === undefined && top[key] !== undefined) base[key] = top[key];
   }
+  if (top.limits && typeof top.limits === 'object' && !Array.isArray(top.limits)) {
+    base.limits = { ...top.limits, ...(rest.limits && typeof rest.limits === 'object' ? rest.limits : {}) };
+  }
   return base;
 }
 
@@ -88,6 +91,9 @@ function checkPlan(r, { name, state } = {}) {
   const { plan } = r;
   const unknown = Object.keys(plan).filter((k) => !PLAN_KEYS.includes(k));
   if (unknown.length) problems.push(`unknown plan key(s): ${unknown.join(', ')}. Accepted: ${PLAN_KEYS.join(', ')}`);
+  if (plan.limits !== undefined && (!plan.limits || typeof plan.limits !== 'object' || Array.isArray(plan.limits))) {
+    problems.push('plan "limits" must be an object (timeoutMs, maxRepairs, checkTimeoutMs).');
+  }
   if (!Array.isArray(plan.sessions) || plan.sessions.length === 0) {
     problems.push('plan needs a non-empty "sessions" array.');
     return problems;
@@ -115,6 +121,7 @@ function checkPlan(r, { name, state } = {}) {
       problems.push(`duplicate session id "${s.id}".`);
     }
     if (typeof s.id === 'string') ids.push(s.id);
+    if (s.label !== undefined && typeof s.label !== 'string') problems.push(`${label}: "label" must be a string.`);
     if (s.after !== undefined && !toArray(s.after).every((a) => typeof a === 'string')) {
       problems.push(`${label}: "after" must be a list of session ids.`);
     }
@@ -212,11 +219,16 @@ function checkPlan(r, { name, state } = {}) {
 
   // Ids already taken by sessions that are not this plan's.
   const mine = new Set(state && Array.isArray(state.sessions) ? state.sessions : []);
+  let taken = false;
   for (const id of known) {
     if (store.readSession(id) && !mine.has(id)) {
-      problems.push(`session "${id}" already exists (zcode status ${id}); a plan needs new ids, or continue its own sessions with "zcode plan resume ${name || '<name>'}".`);
+      taken = true;
+      problems.push(`session "${id}" already exists (zcode status ${id}).`);
     }
   }
+  if (taken) {
+    problems.push(`hint: use a fresh id prefix for a new run (e.g. "<prefix>-<id>"), or "zcode plan resume ${name || '<name>'}" to continue that plan's sessions.`);
+  }
   return problems;
 }
 
@@ -289,7 +301,10 @@ function planReport(name, r, state, { briefs = true } = {}) {
     type: 'plan',
     name,
     status,
-    sessions: sessionList(r.plan).map((s) => ({ id: s.id, status: statuses.get(s.id).status })),
+    sessions: sessionList(r.plan).map((s) => {
+      const e = statuses.get(s.id);
+      return { id: s.id, status: e.status, ...(e.view ? store.idleInfo(e.view) : null) };
+    }),
   };
   if (briefs) {
     payload.briefs = [];
@@ -309,13 +324,32 @@ function exec() {
   return require('./commands/exec.js');
 }
 
+// Preflights run all at once on the current workspace, so a session with
+// `after` would see none of its prerequisites' files. This paragraph tells it
+// to assume them (ids + clipped objectives) instead of asking about them.
+function preflightContext(r, s) {
+  const upstream = afterOf(s).map((a) => sessionList(r.plan).find((x) => x.id === a)).filter(Boolean);
+  if (!upstream.length) return null;
+  const clip = (t) => {
+    const x = String(t || '').replace(/\s+/g, ' ').trim();
+    return x.length <= 200 ? x : `${x.slice(0, 199)}…`;
+  };
+  const list = upstream.map((u) => `- ${u.id}: ${clip(sessionBase(r, u).objective) || '(no objective)'}`).join('\n');
+  return `This is a plan preflight. Sessions ${upstream.map((u) => u.id).join(', ')} run before you and have not run yet; their files will exist when you execute. Assume they deliver what the binding decisions and their objectives say:\n${list}\nDo not ask about their absence; ask only about what the decisions leave open for YOUR scope.`;
+}
+
 // The detached-start invocation for one plan session (id overrides the plan
-// id: preflight uses "<id>.pre").
+// id: preflight uses "<id>.pre"). The label is `plan:<name>` plus the
+// session's own `label`, if any.
 function sessionInvocation(r, name, s, { id = s.id, preflight = false } = {}) {
   const { parseArgv } = require('../bin/zcode.js');
-  const argv = ['task', '--id', id, '--cwd', r.cwd, '--label', `plan:${name}`];
+  const label = `plan:${name}${typeof s.label === 'string' && s.label.trim() ? ` ${s.label.trim()}` : ''}`;
+  const argv = ['task', '--id', id, '--cwd', r.cwd, '--label', label];
   if (preflight) argv.push('--preflight');
-  return exec().buildInvocation(parseArgv(argv), { base: sessionBase(r, s), dir: r.dir });
+  const base = sessionBase(r, s);
+  const note = preflight ? preflightContext(r, s) : null;
+  if (note) base.context = [...toArray(base.context), note];
+  return exec().buildInvocation(parseArgv(argv), { base, dir: r.dir });
 }
 
 function launchSession(r, name, s) {
@@ -415,6 +449,7 @@ module.exports = {
   planReport,
   launchFailure,
   sessionInvocation,
+  preflightContext,
   launchSession,
   resumeSession,
   supervise,

package/lib/store.js

@@ -175,6 +175,18 @@ function viewSession(record) {
   return { ...record, live: ACTIVE_STATES.has(record.state) };
 }
 
+// How long a running session has gone without any engine event
+// ({idleMs, stalled?}); null unless it is running. Informational only: zcode
+// never acts on it. The same rule everywhere (status, wait, watch).
+const STALL_MIN = 8;
+function idleInfo(view, { stallMin = STALL_MIN, now = Date.now() } = {}) {
+  if (!view || view.state !== 'running') return null;
+  const t = Date.parse((view.activity && view.activity.lastEventAt) || view.updatedAt);
+  if (!Number.isFinite(t)) return null;
+  const idleMs = Math.max(0, now - t);
+  return idleMs >= stallMin * 60000 ? { idleMs, stalled: true } : { idleMs };
+}
+
 function listSessions(env = process.env) {
   let names = [];
   try {
@@ -312,6 +324,8 @@ module.exports = {
   readEvents,
   pidAlive,
   viewSession,
+  idleInfo,
+  STALL_MIN,
   listSessions,
   resolveSessionId,
   claimSession,

package/lib/taskspec.js

@@ -61,38 +61,45 @@ function validateUnits(contract, cwd) {
 }
 
 // base: parsed contract object; baseDir: where its "@file" entries resolve
-// (the contract file's directory, else cwd). additions: the CLI flags
+// (the contract file's directory, else cwd), then `cwd` when not found there. additions: the CLI flags
 // (strings; "@file" resolves against the process cwd). cwd: --cwd.
 function buildContract({ base = {}, baseDir = process.cwd(), objective = '', additions = {}, cwd = process.cwd() }) {
   const inlined = new Set();
-  const inline = (list, dir, label) =>
+  // dirs are tried in order; the error names every path tried.
+  const inline = (list, dirs, label) =>
     toArray(list).map((item) => {
       const text = String(item).trim();
       const m = FILE_REF.exec(text);
       if (!m) return text;
-      const file = path.resolve(dir, m[1]);
-      try {
-        const body = fs.readFileSync(file, 'utf8');
-        inlined.add(canon(file));
-        return body;
-      } catch {
-        throw new ContractError(`${label} file "${m[1]}" could not be read.`);
+      const tried = [];
+      for (const dir of dirs) {
+        const file = path.resolve(dir, m[1]);
+        if (tried.includes(file)) continue;
+        tried.push(file);
+        try {
+          const body = fs.readFileSync(file, 'utf8');
+          inlined.add(canon(file));
+          return body;
+        } catch {
+          /* try the next directory */
+        }
       }
+      throw new ContractError(`${label} file "${m[1]}" could not be read (tried ${tried.join(', ')}).`);
     });
 
   let b = base;
   if (b && typeof b === 'object' && !Array.isArray(b)) {
     b = { ...b };
     for (const key of ['context', 'decisions']) {
-      if (b[key] !== undefined) b[key] = inline(b[key], baseDir, `contract ${key}`);
+      if (b[key] !== undefined) b[key] = inline(b[key], [baseDir, cwd], `contract ${key}`);
     }
   }
   const flagDir = process.cwd();
   const contract = normalizeContract(b, {
     ...additions,
     objective,
-    context: inline(additions.context, flagDir, '--context'),
-    decisions: inline(additions.decisions, flagDir, '--decisions'),
+    context: inline(additions.context, [flagDir], '--context'),
+    decisions: inline(additions.decisions, [flagDir], '--decisions'),
   });
   // A file the executor already gets inlined is not also listed to read.
   if (inlined.size) {

package/lib/ui.js

@@ -84,6 +84,7 @@ function makeReporter({ quiet = false, thinking = true, stream = process.stderr,
         const extra =
           ev.phase === 'repairing' ? ` ${ev.attempt}/${ev.of}`
             : ev.phase === 'checking' ? ` ${ev.count}`
+              : ev.phase === 'verifying' ? ` round ${ev.round}`
               : ev.reason ? ` (${ev.reason})` : '';
         line(`${c.cyan('●')} ${ev.phase}${extra}`);
         return;
@@ -186,7 +187,7 @@ function formatResult(r, { color = false } = {}) {
     ['questions', (r.questions || []).map(questionText)],
     ['decisions', (r.decisions || []).map((d) => `${d.what}${d.why ? ` (${d.why})` : ''}`)],
     ['units', (r.units || []).map((u) => `${u.name}: ${u.status || '?'}${u.note ? ` - ${u.note}` : ''}`)],
-    ['visual', (r.visual || []).map((v) => `${v.met === true ? 'met' : 'UNMET'} ${v.criterion || ''}${v.viewport ? ` @${v.viewport}` : ''}${v.note ? ` - ${v.note}` : ''}`)],
+    ['visual', (r.visual || []).map((v) => `${v.met === true ? 'met' : v.met === null ? 'NOT VERIFIED' : 'UNMET'} ${v.criterion || ''}${v.viewport ? ` @${v.viewport}` : ''}${v.note ? ` - ${v.note}` : ''}`)],
     ['unresolved', r.unresolved],
     ['not verified', r.notVerified],
   ]) {
@@ -211,17 +212,26 @@ function formatSessionRow(s) {
   return `${s.id.padEnd(18)} ${String(state).padEnd(11)} ${String(s.kind || '').padEnd(5)} ${when}  ${s.label || s.cwd || ''}`;
 }
 
+// `repairing 1/2`, `verifying round 2`, or the bare phase.
+function phaseText(v) {
+  const d = v.phaseDetail;
+  if (d && d.attempt !== undefined) return `${v.phase} ${d.attempt}/${d.of}`;
+  if (d && d.round !== undefined) return `${v.phase} round ${d.round}`;
+  return v.phase;
+}
+
 function formatSessionView(v, { events = [] } = {}) {
   const L = [];
   const state = v.state === 'finished' ? `finished (${v.status})` : v.state;
   L.push(`${v.id}  ${v.kind}${v.label ? `  ${v.label}` : ''}`);
-  L.push(`  state    ${state}${v.live ? `  ·  phase ${v.phase}  ·  pid ${v.pid}` : ''}`);
+  L.push(`  state    ${state}${v.live ? `  ·  phase ${phaseText(v)}  ·  pid ${v.pid}` : ''}`);
   L.push(`  cwd      ${v.cwd}`);
   if (v.owns && v.owns.length) L.push(`  owns     ${v.owns.join(', ')}`);
   L.push(`  model    ${v.model} · effort ${v.effort}  ·  turns ${v.turns || 0}`);
   if (v.activity) {
     L.push(`  activity ${v.activity.toolCalls || 0} tool calls · ${v.activity.subagentsStarted || 0} subagents${v.activity.lastTool ? ` · last ${v.activity.lastTool}` : ''} · ${v.activity.lastEventAt || ''}`);
   }
+  if (v.idleMs !== undefined) L.push(`  idle     ${Math.round(v.idleMs / 1000)}s since the last engine event${v.stalled ? '  STALLED?' : ''}`);
   if (v.state === 'interrupted') L.push(`  the owning process is gone; continue with: zcode resume ${v.id}`);
   if (events.length) {
     L.push('  recent');
@@ -236,4 +246,4 @@ function formatSessionView(v, { events = [] } = {}) {
   return L.join('\n') + '\n';
 }
 
-module.exports = { makeReporter, formatResult, formatSessionRow, formatSessionView, useColor };
+module.exports = { phaseText, makeReporter, formatResult, formatSessionRow, formatSessionView, useColor };

package/lib/verify.js

@@ -0,0 +1,98 @@
+'use strict';
+// The independent visual verifier (v0.6). The implementer never decides
+// `visual`: after its turn zcode opens a fresh engine session on an
+// image-capable model that did not build the result, has it screenshot the
+// running app and LOOK at the pixels, and parses its `zcode-visual` block.
+// This file is the prompt and the (lenient) parser; the orchestration is in
+// lib/executor.js.
+const { DEFAULT_VIEWPORTS } = require('./contract.js');
+
+// Always judged in addition to the declared criteria.
+const BUILTIN_CRITERION =
+  'All text the page means to show is readable after animations finish: not clipped, hidden, transparent, off-screen or overlapped.';
+
+const bullets = (items) => items.map((i) => `- ${i}`).join('\n');
+
+const clip = (text, max) => {
+  const s = String(text ?? '').replace(/\s+/g, ' ').trim();
+  return s.length <= max ? s : `${s.slice(0, max - 1)}…`;
+};
+
+const WAIT_SCRIPT =
+  'await document.fonts.ready; await Promise.all(document.getAnimations().map(a => a.finished.catch(() => {})))';
+
+// contract: the task contract; session: {id, port, out, tmp}; round: 1-based.
+function buildVerifierPrompt(contract, { session, round = 1 }) {
+  const viewports = contract.viewports && contract.viewports.length ? contract.viewports : DEFAULT_VIEWPORTS;
+  const dir = `${session.out}/verify/${round}`;
+  return [
+    'You are an independent visual verifier. You did not build this and have not seen it. Assume it is broken until the pixels prove otherwise. DOM or text presence is NOT evidence: only what you can see in a screenshot counts.',
+    '',
+    `## What was built\n${clip(contract.objective, 500)}`,
+    '',
+    '## Criteria',
+    bullets([...contract.visual, BUILTIN_CRITERION]),
+    '',
+    '## How',
+    contract.serve
+      ? `- Serve the app with \`${contract.serve}\` on $ZCODE_PORT=${session.port} (build first if it needs one; put build output under $ZCODE_OUT=${session.out}, not in the workspace).`
+      : `- Serve the app on $ZCODE_PORT=${session.port} (pick the dev/preview command from package.json, build first if needed; put build output under $ZCODE_OUT=${session.out}, not in the workspace).`,
+    `- For every viewport (${viewports.join(', ')}): navigate, wait for fonts and for all animations to finish (\`${WAIT_SCRIPT}\`, capped at about 8 s) plus 500 ms, then capture a viewport screenshot and a full-page screenshot into ${dir}/ (names <viewport>-<n>.png, plus a named screenshot for every state a criterion requires).`,
+    '- Then LOOK at each image (read the PNG file). Judge every criterion at every viewport. For each verdict QUOTE the text you can actually read in the relevant region (`seen`); if you read none, say so.',
+    `- Make NO edits: write only files under ${session.out}. Stop any server you started.`,
+    '',
+    '## Reply',
+    'End with exactly one fenced block, a JSON array with one entry per criterion per viewport:',
+    '```zcode-visual',
+    '[{"criterion": "text of the criterion", "viewport": "1440x900", "met": true, "seen": "text you read there", "note": "what is wrong, if anything", "shot": "path of the screenshot"}]',
+    '```',
+  ].join('\n');
+}
+
+const BLOCK_RE = /```zcode-visual[^\n]*\n([\s\S]*?)```/g;
+
+function normMet(v) {
+  if (v === true || v === false) return v;
+  if (typeof v === 'string') {
+    const t = v.trim().toLowerCase();
+    if (['true', 'yes', 'met', 'pass'].includes(t)) return true;
+    if (['false', 'no', 'unmet', 'not met', 'fail'].includes(t)) return false;
+  }
+  return null;
+}
+
+// {entries: [{criterion, viewport?, met: true|false|null, seen, note, shot}],
+// error}. The LAST block wins; an unparsable or empty block is an error.
+function parseVisualBlock(text) {
+  const matches = [...String(text || '').matchAll(BLOCK_RE)];
+  if (!matches.length) return { entries: [], error: 'no zcode-visual block' };
+  let raw;
+  try {
+    raw = JSON.parse(matches[matches.length - 1][1]);
+  } catch (err) {
+    return { entries: [], error: `invalid JSON: ${err.message}` };
+  }
+  if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+    raw = Array.isArray(raw.visual) ? raw.visual : Array.isArray(raw.entries) ? raw.entries : [raw];
+  }
+  if (!Array.isArray(raw)) return { entries: [], error: 'not a JSON array' };
+  const entries = raw
+    .filter((e) => e && typeof e === 'object' && !Array.isArray(e) && e.criterion !== undefined)
+    .map((e) => ({
+      criterion: String(e.criterion),
+      ...(e.viewport ? { viewport: String(e.viewport) } : {}),
+      met: normMet(e.met),
+      seen: e.seen === undefined || e.seen === null ? '' : String(e.seen),
+      note: e.note === undefined || e.note === null ? '' : String(e.note),
+      ...(e.shot ? { shot: String(e.shot) } : {}),
+    }));
+  return entries.length ? { entries, error: null } : { entries: [], error: 'no usable entries' };
+}
+
+// Entries for criteria that could not be judged: met:null, never met:false
+// (a verifier failure is not the implementer's fault).
+function notVerified(criteria, why) {
+  return criteria.map((criterion) => ({ criterion, met: null, seen: '', note: `not verified: ${why}` }));
+}
+
+module.exports = { buildVerifierPrompt, parseVisualBlock, notVerified, BUILTIN_CRITERION };

package/lib/workspace.js

@@ -337,7 +337,37 @@ function diffSnapshots(before, after) {
   return out;
 }
 
+// Keeps zcode's own scratch dirs out of the target repo's `git status`:
+// appends missing entries to the repo-local exclude file (never .gitignore;
+// `--git-path info/exclude` also resolves for worktrees). Idempotent,
+// append-only, silent: every error is ignored.
+const LOCAL_EXCLUDES = ['.zcode/', '.playwright-mcp/'];
+function ensureLocalExclude(cwd) {
+  try {
+    const rel = execFileSync('git', ['-C', cwd, 'rev-parse', '--git-path', 'info/exclude'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    if (!rel) return;
+    const file = path.resolve(cwd, rel);
+    let text = '';
+    try {
+      text = fs.readFileSync(file, 'utf8');
+    } catch {
+      /* no exclude file yet */
+    }
+    const have = new Set(text.split(/\r?\n/).map((l) => l.trim().replace(/^\//, '').replace(/\/$/, '')));
+    const missing = LOCAL_EXCLUDES.filter((e) => !have.has(e.replace(/\/$/, '')));
+    if (!missing.length) return;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, `${text && !text.endsWith('\n') ? '\n' : ''}${missing.join('\n')}\n`);
+  } catch {
+    /* hygiene is best-effort */
+  }
+}
+
 module.exports = {
+  ensureLocalExclude,
   OwnershipError,
   workspaceRoot,
   normalizeOwns,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0xgeorgemathew/zcode",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Lean GLM-5.3 execution engine for orchestrator agents: task contracts, independent sessions, zcode-run verification, structured handbacks, subagents, MCP, skills. Wraps the ZCode engine. Zero dependencies.",
   "license": "MIT",
   "private": false,

package/skills/claude-code/zcode/SKILL.md

@@ -1,22 +1,22 @@
 ---
 name: zcode
-description: Delegate scoped implementation work to the zcode CLI (GLM-5.3 executor, vision-capable, has Playwright) and consume its compact verified handback. Use when you are orchestrating: you make the product, design and logic decisions once, then zcode implements, tests, visually verifies and repairs — in one session with subagent units, several parallel sessions, or a dependency plan — while you spend tokens only on decisions and exceptions.
+description: Delegate scoped implementation work to the zcode CLI (GLM-5.3-Flash executor: sees images, has Playwright; an independent vision verifier judges UI) and consume its compact verified handback. Use when you are orchestrating: you make the product, design and logic decisions once, then zcode implements, tests, visually verifies and repairs — in one session with subagent units, several parallel sessions, or a dependency plan — while you spend tokens only on decisions and exceptions.
 ---
 
 # Operating zcode as an executor
 
-zcode is a CLI execution engine. You decide; it builds. It implements a scoped task in its own session, runs your checks itself, screenshots and judges UI with its own vision when you ask, repairs failures within a budget, and returns a small structured handback.
+zcode is a CLI execution engine. You decide; it builds. It implements a scoped task in its own session, runs your checks itself, has a fresh, independent vision verifier screenshot and judge UI when you ask, repairs failures within a budget, and returns a small structured handback.
 
 **The point is token economy.** Your tokens go to decisions and exceptions. Everything mechanical — writing code, running builds and tests, reading diffs, looking at screenshots, fixing small failures — is zcode's. If you are doing any of that after dispatch, you are paying twice.
 
-Check readiness once per machine: `zcode doctor` (exit 3 → `zcode login`; exit 4 → engine missing). Don't run `--help`: everything you need is here.
+Check readiness once per machine: `zcode doctor` (exit 3 → `zcode login`; exit 4 → engine missing). Don't run `--help` or a bare `zcode status`: everything you need is here.
 
 ## The workflow
 
 1. **Read** the codebase as much as you need to plan. This is the one phase where reading files is expected.
 2. **Decide** everything a user could see or a system depends on (checklists below). Write the decisions down once, as decisions — a file such as `docs/decisions.md` that sessions receive with `--decisions @file`.
 3. **Shape** the work: one session with units, several sessions, or a plan (next section).
-4. **Preflight** (optional, recommended for anything large or ambiguous): `--preflight` makes zcode list every question it would otherwise guess. Answer them all in one edit to the decisions file.
+4. **Preflight** (optional): `--preflight` makes zcode list every question it would otherwise guess; answer them all in one edit to the decisions file. It costs you a round trip, so use it only when your decisions have known gaps or the work is large and novel; skip it when the checklists below are fully covered.
 5. **Dispatch and wait** with `--detach` + `zcode wait`, or `zcode plan run` + `zcode plan wait`.
 6. **Handle exceptions only.** `completed` → move on. Anything else → read only what the brief shows, answer or adjust in one line with `zcode resume`.
 
@@ -30,7 +30,7 @@ The executor implements binding decisions exactly and is told not to invent anyt
 
 **Boundaries:** what the executor may choose freely (internal names, file structure, helpers) and what it must ask about.
 
-Write decisions as statements, not wishes: "Reveal: opacity 0→1 and translateY 16px→0, 400 ms, cubic-bezier(.2,.7,.2,1), 60 ms stagger, at 20% visibility; reduced motion: opacity only."
+Keep the decisions file dense: tables and one-line statements, no prose, no rationale the executor doesn't need (aim for a few thousand tokens for a one-page site). Write decisions as statements, not wishes: "Reveal: opacity 0→1 and translateY 16px→0, 400 ms, cubic-bezier(.2,.7,.2,1), 60 ms stagger, at 20% visibility; reduced motion: opacity only."
 
 ## Shaping the work
 
@@ -40,7 +40,7 @@ Pick the cheapest shape that keeps each session finishable without you.
 - **Several sessions** when pieces are independent and own disjoint paths. Launch them `--detach` in parallel; each may have its own units.
 - **A plan** when there are dependencies (scaffold → parallel features → integration). `zcode plan run plan.json` sequences and parallelises for you; you wait once.
 
-Parallel safety is automatic: each session gets `ZCODE_PORT`, `ZCODE_OUT`, `ZCODE_TMP` and `ZCODE_SESSION_ID`. Tell the first (scaffold) session to make dev-server ports, build output dirs and test artifacts honour them. Target repos should ignore `.zcode/`.
+Parallel safety is automatic: each session gets `ZCODE_PORT`, `ZCODE_OUT`, `ZCODE_TMP` and `ZCODE_SESSION_ID`. Tell the first (scaffold) session to make dev-server ports, build output dirs and test artifacts honour them. zcode keeps `.zcode/` and `.playwright-mcp/` out of git via the repo's local `.git/info/exclude`; you don't need to touch `.gitignore` for them.
 
 ## The handoff
 
@@ -49,7 +49,7 @@ Parallel safety is automatic: each session gets `ZCODE_PORT`, `ZCODE_OUT`, `ZCOD
 | objective | positional text | always: the outcome, not the steps |
 | decisions | `--decision "…"`, `--decisions @file` | always for anything user-visible or behavioural |
 | checks | `--check "cmd"` | always: build, typecheck, tests, lint, greps — zcode runs them itself |
-| visual | `--visual "criterion"`, `--viewport WxH`, `--serve "cmd"` | any UI work: zcode serves on $ZCODE_PORT, screenshots, judges and repairs |
+| visual | `--visual "criterion"`, `--viewport WxH`, `--serve "cmd"` | any UI work: after the build, a fresh vision verifier serves on $ZCODE_PORT, waits for animations to finish, screenshots each viewport, quotes the text it can actually see, judges each criterion (plus "all intended text is readable"), and unmet ones go back to the implementer for repair. Phrase criteria as what must be visible: "hero headline 'Your money, simplified' is fully readable at 390 and 1440" |
 | units | `--unit "name: objective [owns a,b]"` | one session should fan out to subagents |
 | owns | `--owns path/glob` | always when other sessions may run in the same repo |
 | touch | `--touch path` | a small edit to a shared file no running session owns |
@@ -58,7 +58,7 @@ Parallel safety is automatic: each session gets `ZCODE_PORT`, `ZCODE_OUT`, `ZCOD
 | acceptance | `--accept "…"` | criteria beyond checks and visuals |
 | everything | `--task contract.json` | keys: objective, scope, constraints, decisions, design, acceptance, checks, visual, viewports, units, files, references, context, owns, touch, limits, model, effort |
 
-Model and effort: `--model glm-5.3` for real work (`flash` for trivial edits); `--effort low|high|max` (default `max`). Other values are refused before anything starts.
+Model and effort: don't pass `--model`. Everything runs on GLM-5.3-Flash by default (it sees images): sessions, units, plans, the verifier. Use `--model glm-5.3` only when the user asks for it; it can't see images. `--effort low|high|max` (default `max`). Other values are refused before anything starts.
 
 ## Running
 
@@ -81,13 +81,17 @@ zcode plan resume <name> ["<message>"]              # resume failed/partial, rel
 zcode plan resume <name> --session <id> "<answer>"  # answer one blocked session
 ```
 
-`plan.json`: `{"cwd"?, "decisions"?, "context"?, "files"?, "model"?, "effort"?, "sessions": [{"id", "after"?: [ids], ...contract keys}]}`. Top-level decisions/context/files go to every session; `@` entries are files relative to the plan. The plan name is the file basename (or `--id`). Sessions that can run at the same time must own disjoint paths; `plan check` enforces it. When an upstream session ends non-completed, its dependants are `skipped` until you `plan resume`.
+`plan.json`: `{"cwd"?, "decisions"?, "context"?, "files"?, "model"?, "effort"?, "limits"?, "sessions": [{"id", "after"?: [ids], "label"?, ...contract keys}]}`. Top-level decisions/context/files/limits go to every session; `@` entries resolve against the plan file's directory, then the plan's cwd. Don't also list the decisions file under `files`: it is already inlined. The plan name is the file basename (or `--id`). Sessions that can run at the same time must own disjoint paths; `plan check` enforces it. When an upstream session ends non-completed, its dependants are `skipped` until you `plan resume`.
+
+Session ids are global and permanent: give every new run a fresh prefix (`wc3-scaffold`, …) so `plan check` passes first time. A task session may run 2 h by default; a big session (a whole page, a whole flow) can set `"limits": {"timeoutMs": 10800000}`. If one still times out, `zcode plan resume <name> "continue"` picks up from the files it already wrote.
+
+While sessions run, the user can watch them with `zcode watch` (live phase, last tool, model requests, `STALLED?` after 8 idle minutes); you never run it. `wait` timeout lines carry `idleMs`/`stalled`: a stalled session is the one case to `cancel` + `resume` early.
 
 Your Bash tool times out at 10 minutes; always wait in bounded slices. Run the wait with `run_in_background` if you have other planning to do.
 
 ## Reading the brief
 
-`--json` prints one compact line: `status`, `summary`, `files`, failing check tails, `questions`, `issues`, `unresolved`, `scopeViolations`, `touched`, `decisions`, `visual`, `units`, and `result` (path to the full record).
+`--json` prints one compact line: `status`, `summary`, `files`, failing `checks` with tails (`checksPassed` counts the rest), `questions`, `issues`, `unresolved`, `scopeViolations`, `touched`, the first `decisions` (`decisionsMore` counts the rest), unmet `visual` with what the verifier actually `seen` (`visualMet` is "met/total"), `units`, and `result` (path to the full record). Read it straight from the command output; don't pipe it through jq, python or tail.
 
 | status | exit | do |
 |---|---|---|
@@ -101,7 +105,7 @@ Your Bash tool times out at 10 minutes; always wait in bounded slices. Run the w
 ## Hard rules after dispatch
 
 - Don't open files a `completed` session changed. Don't re-run checks it ran. Don't look at its screenshots.
-- Don't poll `status`; use `wait`.
+- Don't poll `status`; use `wait` (or `plan wait`) once, in the background if you like, and act on its exit.
 - Don't fix code yourself; `resume` the session with one line.
 - Need to know something about the result? `zcode result <id> --full` first; read code only as a last resort.
 - Don't ask zcode to commit, push, publish or deploy unless the user asked; when they did, make it its own final session gated on everything else being `completed`.
@@ -113,7 +117,7 @@ You read the empty repo, decide the design system, copy, motion, form logic and
 ```json
 {
   "decisions": ["@docs/decisions.md"],
-  "model": "glm-5.3", "effort": "high",
+  "effort": "high",
   "sessions": [
     {"id": "scaffold", "owns": ["package.json", "package-lock.json", "index.html", "*.config.*", "tsconfig*.json", "src/app/**", "src/styles/**", "src/components/**", "e2e/smoke.spec.ts", ".gitignore"],
      "objective": "Vite + React + TS scaffold, tokens, shared shell, stubs for src/landing and src/apply; dev/preview/e2e honour ZCODE_PORT and ZCODE_OUT",
@@ -135,7 +139,7 @@ You read the empty repo, decide the design system, copy, motion, form logic and
 }
 ```
 
-`zcode plan check plan.json` → `zcode plan run plan.json --preflight` (read-only `<id>.pre` sessions; prints only the questions) → answer them once in the decisions file → `zcode plan run plan.json --detach` → `zcode plan wait plan --timeout-ms 540000 --json`. Your total involvement: the decisions, one answer pass, one summary.
+`zcode plan check plan.json` → `zcode plan run plan.json --preflight` (read-only `<id>.pre` sessions, all at once; downstream sessions are told their upstream hasn't run yet; prints only the questions) → answer them once in the decisions file → `zcode plan run plan.json --detach` → `zcode plan wait plan --timeout-ms 540000 --json`. Your total involvement: the decisions, one answer pass, one summary.
 
 ## Exit codes