@0xgeorgemathew/zcode 0.4.1 → 0.5.0

package/lib/executor.js

@@ -19,9 +19,11 @@ const { resolveRuntime, makeClient } = require('./bootstrap.js');
 const { buildEngineHome, rootDir, liveDir } = require('./isolation.js');
 const { openSession, runTurn, TurnError } = require('./appserver.js');
 const { runChecks } = require('./checks.js');
+const { reservePort } = require('./ports.js');
 const {
   workspaceRoot,
   isOwned,
+  isZcodePath,
   acquireLease,
   liveLeases,
   snapshot,
@@ -34,6 +36,9 @@ const {
   HANDBACK_REQUEST,
   parseHandback,
   deriveStatus,
+  unmetVisual,
+  visualGaps,
+  buildVisualReportRequest,
 } = require('./contract.js');
 
 const RESULT_SCHEMA = 'zcode.result/1';
@@ -52,7 +57,7 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 // Settings a session keeps across invocations (stored as invocation.json).
 const SETTING_KEYS = [
   'kind', 'label', 'cwd', 'model', 'effort', 'timeoutMs', 'maxRepairs', 'checkTimeoutMs',
-  'checks', 'owns', 'ownsDisplay', 'acceptanceDeclared', 'mcpSpecs', 'mcpInherit',
+  'checks', 'preflight', 'owns', 'ownsDisplay', 'touch', 'touchDisplay', 'acceptanceDeclared', 'mcpSpecs', 'mcpInherit', 'noBrowser',
   'skillsDirs', 'noSkills', 'profile', 'includeReasoning', 'allowOverlap', 'stream',
 ];
 
@@ -159,6 +164,8 @@ function prepareSession(inv, env = process.env) {
     workspaceRoot: workspaceRoot(inv.cwd),
     owns: inv.ownsDisplay || [],
     ownsRoot: inv.owns || [],
+    touch: inv.touchDisplay || [],
+    preflight: Boolean(inv.preflight),
     checks: inv.checks || [],
     model: inv.model,
     effort: inv.effort,
@@ -210,7 +217,13 @@ async function execute(inv, opts = {}) {
     if (releaseSlot) releaseSlot();
     releaseOwner();
   };
+  // Resuming a preflight session proceeds to the real task: answers + the
+  // full protocol, checks and visual verification from here on.
+  const leavingPreflight = resuming && Boolean(inv.preflight);
+  if (leavingPreflight) inv.preflight = false;
+  const preflight = Boolean(inv.preflight);
   if (resuming) writeSettings(id, inv, env);
+  if (leavingPreflight) store.updateSession(id, { preflight: false }, env);
   const isFirstInvocation = !record.engineSessionId;
   const update = (patch) => store.updateSession(id, patch, env);
 
@@ -285,14 +298,19 @@ async function execute(inv, opts = {}) {
   }
 
   // --- lease ------------------------------------------------------------------
-  const lease = acquireLease({ id, root, owns: inv.owns || [], allowOverlap: inv.allowOverlap, env });
+  // A preflight is read-only: it reserves nothing and conflicts with nobody.
+  const lease = preflight
+    ? { ok: true, conflicts: [], others: [], release() {} }
+    : acquireLease({ id, root, owns: inv.owns || [], touch: inv.touch || [], allowOverlap: inv.allowOverlap, env });
   if (!lease.ok) {
     const names = lease.conflicts
       .map((c) => `${c.id} (owns ${c.owns && c.owns.length ? c.owns.join(', ') : 'the whole workspace'})`)
       .join('; ');
-    const message =
-      `workspace conflict in ${root}: overlapping ownership with running session(s) ${names}. ` +
-      'Declare disjoint --owns paths, use a separate worktree, wait for them, or pass --allow-overlap.';
+    const message = lease.touch
+      ? `workspace conflict in ${root}: --touch ${(inv.touchDisplay || []).join(', ')} is owned by running session(s) ${names}. ` +
+        'Wait for them, touch something else, or pass --allow-overlap.'
+      : `workspace conflict in ${root}: overlapping ownership with running session(s) ${names}. ` +
+        'Declare disjoint --owns paths, use a separate worktree, wait for them, or pass --allow-overlap.';
     if (inv.adopt) {
       // A detached worker: the caller is polling this id, so leave a result.
       store.writeResult(id, {
@@ -323,6 +341,9 @@ async function execute(inv, opts = {}) {
   let subagentNote = null;
   let built = null;
   let before = null;
+  let releasePort = null;
+  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 invocationStart = new Date(started).toISOString();
@@ -331,6 +352,23 @@ async function execute(inv, opts = {}) {
     if (signal && signal.aborted) throw new TurnError('cancelled', { kind: 'cancelled' });
     if (!releaseSlot) throw new TurnError('run exceeded --timeout-ms while queued', { kind: 'timeout' });
 
+    // Per-session environment for the executor AND the checks: a port no
+    // other live session holds, plus output and scratch dirs of its own.
+    const reserved = await reservePort({ env, preferred: record.port });
+    if (!reserved) throw new ExecError('no free port for ZCODE_PORT in 41000-48999', { exitCode: 5, kind: 'no_port' });
+    releasePort = reserved.release;
+    const outDir = path.join(record.cwd, '.zcode', 'out', id);
+    const tmpDir = path.join(dir, 'tmp');
+    fs.mkdirSync(outDir, { recursive: true });
+    fs.mkdirSync(tmpDir, { recursive: true, mode: 0o700 });
+    sessionEnv = {
+      ZCODE_SESSION_ID: id,
+      ZCODE_PORT: String(reserved.port),
+      ZCODE_OUT: outDir,
+      ZCODE_TMP: tmpDir,
+    };
+    update({ port: reserved.port, out: outDir, tmp: tmpDir });
+
     built = buildEngineHome({
       home,
       root: rootDir(env),
@@ -338,6 +376,7 @@ async function execute(inv, opts = {}) {
       live: liveDir(env),
       mcpSpecs: inv.mcpSpecs || [],
       mcpInherit: inv.mcpInherit,
+      browser: !inv.noBrowser,
       skillsDirs: inv.skillsDirs || [],
       noSkills: inv.noSkills,
     });
@@ -347,7 +386,7 @@ async function execute(inv, opts = {}) {
     // nothing has been sent to the model yet).
     setPhase('starting');
     for (let attempt = 1; ; attempt++) {
-      client = makeClient(runtime, { home, cwd: record.cwd });
+      client = makeClient(runtime, { home, cwd: record.cwd, sessionEnv });
       client.start();
       update({ enginePid: client.child.pid });
       try {
@@ -372,10 +411,21 @@ async function execute(inv, opts = {}) {
     // First prompt for this invocation.
     let prompt;
     if (inv.kind === 'task') {
-      prompt = isFirstInvocation
-        ? buildTaskPrompt(inv.contract, { ownsDisplay: inv.ownsDisplay || [] }) +
+      const taskPrompt = () => buildTaskPrompt(inv.contract, {
+        ownsDisplay: inv.ownsDisplay || [],
+        session: { id, port: sessionEnv.ZCODE_PORT, out: sessionEnv.ZCODE_OUT, tmp: sessionEnv.ZCODE_TMP },
+        preflight,
+      });
+      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`)'}`
+        : isFirstInvocation
+        ? taskPrompt() +
           (resuming && inv.resume.message ? `\n\n## Message from the orchestrator\n${inv.resume.message}` : '')
-        : buildResumePrompt(inv.resume ? inv.resume.message : '', { kind: 'task' });
+        : buildResumePrompt(inv.resume ? inv.resume.message : '', {
+          kind: 'task',
+          // The port is the one thing that may have changed since the first prompt.
+          portChange: record.port && String(record.port) !== sessionEnv.ZCODE_PORT ? sessionEnv.ZCODE_PORT : null,
+        });
     } else if (inv.kind === 'agent') {
       prompt =
         `You MUST use the Agent tool (profileId: "${inv.profile}") to accomplish the ` +
@@ -386,6 +436,7 @@ async function execute(inv, opts = {}) {
     }
 
     let askedForHandback = false;
+    let askedForVisual = false;
     let phase = 'executing';
     for (;;) {
       setPhase(phase, phase === 'repairing' ? { attempt: repairs, of: inv.maxRepairs } : {});
@@ -411,28 +462,44 @@ async function execute(inv, opts = {}) {
         phase = 'reporting';
         continue;
       }
+      if (preflight) break; // read-only: zcode runs nothing
       if (parsed.handback && parsed.handback.status === 'blocked') break;
-      if (!inv.checks.length) break;
-
-      setPhase('checking', { count: inv.checks.length });
-      const preChecks = before ? snapshot(root) : null;
-      checks = await runChecks(inv.checks, {
-        cwd: record.cwd,
-        timeoutMs: Math.max(1000, Math.min(inv.checkTimeoutMs, deadline - Date.now())),
-        signal,
-        onEvent: relay,
-      });
-      if (preChecks) {
-        for (const f of diffSnapshots(preChecks, snapshot(root)) || []) checkTouched.add(f.path);
-      }
-      if (Date.now() >= deadline && checks.some((c) => c.timedOut)) {
-        throw new TurnError('run exceeded --timeout-ms during acceptance checks', { kind: 'timeout' });
+      if (!inv.checks.length && !visualDeclared.length) break;
+
+      if (inv.checks.length) {
+        setPhase('checking', { count: inv.checks.length });
+        const preChecks = before ? snapshot(root) : null;
+        checks = await runChecks(inv.checks, {
+          cwd: record.cwd,
+          env: { ...env, ...sessionEnv },
+          timeoutMs: Math.max(1000, Math.min(inv.checkTimeoutMs, deadline - Date.now())),
+          signal,
+          onEvent: relay,
+        });
+        if (preChecks) {
+          for (const f of diffSnapshots(preChecks, snapshot(root)) || []) checkTouched.add(f.path);
+        }
+        if (Date.now() >= deadline && checks.some((c) => c.timedOut)) {
+          throw new TurnError('run exceeded --timeout-ms during acceptance checks', { kind: 'timeout' });
+        }
       }
       const failures = checks.filter((c) => !c.ok);
-      if (!failures.length || repairs >= inv.maxRepairs) break;
+      // 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
+          && !(signal && signal.aborted) && Date.now() < deadline) {
+        askedForVisual = true;
+        prompt = buildVisualReportRequest(gaps.missing);
+        phase = 'reporting';
+        continue;
+      }
+      const visualUnmet = unmetVisual(parsed.handback, visualDeclared);
+      if ((!failures.length && !visualUnmet.length) || repairs >= inv.maxRepairs) break;
       if ((signal && signal.aborted) || Date.now() >= deadline) break;
       repairs++;
-      prompt = buildRepairPrompt(failures, { attempt: repairs, maxRepairs: inv.maxRepairs });
+      prompt = buildRepairPrompt(failures, { attempt: repairs, maxRepairs: inv.maxRepairs, visual: visualUnmet });
       phase = 'repairing';
     }
 
@@ -450,6 +517,7 @@ async function execute(inv, opts = {}) {
     error = err;
   } finally {
     if (client) client.kill();
+    if (releasePort) releasePort();
     lease.release();
     releaseClaims();
   }
@@ -474,21 +542,38 @@ async function execute(inv, opts = {}) {
   const after = before ? snapshot(root) : null;
   const diff = before ? diffSnapshots(before, after) : null;
   const owns = inv.owns || [];
+  const touch = inv.touch || [];
   const files = (diff || [])
-    .filter((f) => !f.path.startsWith('.zcode/'))
+    .filter((f) => !isZcodePath(f.path))
     .map((f) => {
       const owned = isOwned(f.path, owns);
-      const by = owned
+      // --touch: edits allowed but reported, never a scope violation.
+      const touchedByDesign = !owned && touch.length > 0 && isOwned(f.path, touch);
+      const by = owned || touchedByDesign
         ? null
         : [...concurrent.entries()].find(([, o]) => o.length && isOwned(f.path, o));
-      const fromChecks = !owned && !by && checkTouched.has(f.path);
-      return { ...f, owned, ...(by ? { concurrentSession: by[0] } : {}), ...(fromChecks ? { fromChecks: true } : {}) };
+      const fromChecks = !owned && !touchedByDesign && !by && checkTouched.has(f.path);
+      return {
+        ...f,
+        owned,
+        ...(touchedByDesign ? { touched: true } : {}),
+        ...(by ? { concurrentSession: by[0] } : {}),
+        ...(fromChecks ? { fromChecks: true } : {}),
+      };
     });
+  const touched = files.filter((f) => f.touched).map((f) => f.path);
   const scopeViolations = files
-    .filter((f) => !f.owned && !f.concurrentSession && !f.fromChecks)
+    .filter((f) => !f.owned && !f.touched && !f.concurrentSession && !f.fromChecks)
     .map((f) => f.path);
 
   const handback = parsed.handback;
+  // Preflight is read-only: anything it changed (that no concurrent session
+  // owns) is a protocol breach.
+  const preflightWrote = preflight
+    ? files
+      .filter((f) => ![...concurrent.values()].some((o) => o.length && isOwned(f.path, o)))
+      .map((f) => f.path)
+    : [];
   let { status, issues } = deriveStatus({
     kind: inv.kind,
     error: error && !cancelled && error.kind !== 'user_input' ? error : null,
@@ -497,12 +582,16 @@ async function execute(inv, opts = {}) {
     handback,
     handbackError: parsed.error,
     checks,
-    scopeViolations,
+    scopeViolations: preflight ? [] : scopeViolations,
+    preflight,
+    preflightWrote,
+    visualDeclared,
   });
 
   let errorOut = null;
   if (status === 'failed') {
     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') {
     errorOut = { kind: 'cancelled', message: 'cancelled' };
@@ -520,10 +609,19 @@ async function execute(inv, opts = {}) {
   }
 
   const notVerified = [];
-  if (inv.kind === 'task') {
+  if (inv.kind === 'task' && preflight) {
+    notVerified.push('preflight: the questions come from reading only; nothing was built, run or checked');
+  } else if (inv.kind === 'task') {
     if (!inv.checks.length) notVerified.push('no acceptance checks were declared; nothing was executed by zcode to verify the work');
     if (inv.acceptanceDeclared) notVerified.push('prose acceptance criteria are confirmed only by the executor\'s own report');
     if (subagents && subagents.length) notVerified.push('subagent "success" means the subagent returned; only the integrated result is verified');
+    if (handback && handback.units.length) {
+      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`);
+    }
   }
   if (before && !diff) notVerified.push('changed files could not be tracked in this workspace');
   if (subagentNote) issues.push(subagentNote);
@@ -541,7 +639,9 @@ async function execute(inv, opts = {}) {
     id,
     kind: inv.kind,
     label: inv.label || null,
-    summary: handback && handback.summary ? handback.summary : '',
+    summary: preflight && status === 'completed'
+      ? 'no open questions'
+      : handback && handback.summary ? handback.summary : '',
     response: inv.kind === 'task' ? parsed.report : response,
     issues,
     questions,
@@ -552,6 +652,14 @@ async function execute(inv, opts = {}) {
       files,
     },
     scopeViolations,
+    touched,
+    ...(preflight ? { preflight: true } : {}),
+    decisions: handback ? handback.decisions : [],
+    visual: handback ? handback.visual : [],
+    units: handback ? handback.units : [],
+    sessionEnv: sessionEnv
+      ? { port: Number(sessionEnv.ZCODE_PORT), out: sessionEnv.ZCODE_OUT, tmp: sessionEnv.ZCODE_TMP }
+      : null,
     checks: checks.map((c) => ({
       command: c.command,
       ok: c.ok,

package/lib/isolation.js

@@ -142,8 +142,18 @@ function liveMcpServers(live = LIVE_ZCODE) {
 // base (specs still win by name). Hermetic default is deliberate: the
 // desktop set includes OAuth servers that can never complete headless and
 // stall the engine's connect pool.
-function effectiveMcpServers({ inherit = false, mcpSpecs = [], live = LIVE_ZCODE } = {}) {
-  const servers = inherit ? liveMcpServers(live) : {};
+// Exception: the desktop's local browser server (stdio, no OAuth) is always
+// inherited, so browser prompts open the same Playwright window the desktop
+// opens. --no-browser drops it.
+const BROWSER_SERVERS = ['playwright'];
+
+function effectiveMcpServers({ inherit = false, browser = true, mcpSpecs = [], live = LIVE_ZCODE } = {}) {
+  const liveSet = liveMcpServers(live);
+  const servers = inherit ? liveSet : {};
+  for (const name of BROWSER_SERVERS) {
+    if (!browser) delete servers[name];
+    else if (liveSet[name]) servers[name] = liveSet[name];
+  }
   for (const spec of mcpSpecs) {
     for (const [name, def] of Object.entries(spec)) servers[name] = def;
   }
@@ -200,6 +210,11 @@ function isDanglingLink(p) {
 // sources + this invocation's flags; engine state under the HOME (cli/db,
 // cli/agents, cli/rollout, logs, memories) is never touched, so a session
 // stays resumable across invocations. Returns facts for reporting.
+// Desktop skills that drive the app's own UI (the built-in browser pane).
+// The CLI cannot serve them, and loading one steers the agent away from
+// Playwright into a dead end.
+const HOST_ONLY_SKILLS = new Set(['control-browser']);
+
 function buildEngineHome({
   home,
   root,
@@ -207,6 +222,7 @@ function buildEngineHome({
   live = LIVE_ZCODE,
   mcpSpecs = [],
   mcpInherit = false,
+  browser = true,
   skillsDirs = [],
   noSkills = false,
 }) {
@@ -237,7 +253,7 @@ function buildEngineHome({
     zai.options = zai.options || {};
     zai.options.apiKey = key;
   }
-  const servers = effectiveMcpServers({ inherit: mcpInherit, mcpSpecs, live });
+  const servers = effectiveMcpServers({ inherit: mcpInherit, browser, mcpSpecs, live });
   cfg.mcp = { ...(cfg.mcp || {}), servers };
   writeJson600(path.join(cliDir, 'config.json'), cfg);
 
@@ -268,6 +284,7 @@ function buildEngineHome({
     for (const entry of listDir(liveSkills)) {
       if (!entry.isDirectory()) continue;
       if (!fs.existsSync(path.join(liveSkills, entry.name, 'SKILL.md'))) continue;
+      if (HOST_ONLY_SKILLS.has(entry.name)) continue;
       fs.cpSync(path.join(liveSkills, entry.name), path.join(skillsDir, entry.name), {
         recursive: true,
       });
@@ -343,8 +360,22 @@ function migrateRoot(env = process.env) {
 
 // Env for the engine child process (§6.3): HOME=scratch, pinned builtin
 // config, and the uncontrolled overrides deleted. cwd is set by the caller.
-function engineEnv({ home, builtinProviderConfig, parentEnv = process.env }) {
+// `sessionEnv` (ZCODE_SESSION_ID, ZCODE_PORT, …) is applied last so nothing
+// inherited can shadow it; the engine's tools inherit it.
+function engineEnv({ home, builtinProviderConfig, parentEnv = process.env, sessionEnv = {} }) {
   const childEnv = { ...parentEnv };
+  const realHome = parentEnv.HOME || os.homedir();
+  // The scratch HOME hides the user's tool caches. Point Playwright and npm
+  // back at the real ones so installed browsers and packages are found.
+  if (!childEnv.PLAYWRIGHT_BROWSERS_PATH) {
+    const cache = process.platform === 'darwin'
+      ? path.join(realHome, 'Library', 'Caches', 'ms-playwright')
+      : path.join(realHome, '.cache', 'ms-playwright');
+    if (fs.existsSync(cache)) childEnv.PLAYWRIGHT_BROWSERS_PATH = cache;
+  }
+  if (!childEnv.npm_config_cache && !childEnv.NPM_CONFIG_CACHE) {
+    childEnv.npm_config_cache = path.join(realHome, '.npm');
+  }
   childEnv.HOME = home;
   childEnv.ZCODE_BUILTIN_PROVIDER_CONFIG_FILE = builtinProviderConfig;
   for (const name of [
@@ -356,6 +387,7 @@ function engineEnv({ home, builtinProviderConfig, parentEnv = process.env }) {
   ]) {
     delete childEnv[name];
   }
+  Object.assign(childEnv, sessionEnv);
   return childEnv;
 }
 

package/lib/models.js

@@ -3,6 +3,8 @@
 // every engine request itself, so nothing outside this allowlist can reach
 // the wire.
 
+const fs = require('node:fs');
+
 const DEFAULT_MODEL = 'GLM-5.3-Flash';
 
 // Case-insensitive aliases → official ids (exact ids pass through verbatim;
@@ -43,7 +45,89 @@ function unknownModelMessage(input) {
   );
 }
 
+// --- supported effort levels per model ---------------------------------------
+//
+// The engine rejects an unsupported reasoning level only after it has been
+// spawned and a session opened (GLM-5.3 refused `medium` that way in a real
+// run). The levels live in the engine's builtin provider config
+// (config/provider/zcode-builtin.json, the path `zcode doctor` reports):
+// modelConfigRules.modelRules[] = {modelMatch: <regex>, config:
+// {optionSpecs: {reasoningLevel: {values: […]}}}}. Later rules refine
+// earlier ones (a generic `glm-5` rule lists disabled/enabled; the
+// `glm-5.3(-flash)?` rule after it lists low/high/max), so the LAST matching
+// rule that lists values wins. Unreadable or unmatched → the table below
+// (observed in zcode-builtin.json shipped with ZCode 0.16.x).
+const FALLBACK_LEVELS = {
+  'GLM-5.3': ['low', 'high', 'max'],
+  'GLM-5.3-Flash': ['low', 'high', 'max'],
+};
+const OFFICIAL_IDS = Object.keys(FALLBACK_LEVELS);
+
+const levelCache = new Map(); // path:mtime:size → parsed rules
+
+function readRules(file) {
+  try {
+    const st = fs.statSync(file);
+    const key = `${file}:${st.mtimeMs}:${st.size}`;
+    if (!levelCache.has(key)) {
+      const json = JSON.parse(fs.readFileSync(file, 'utf8'));
+      const rules = json && json.config && json.config.modelConfigRules && json.config.modelConfigRules.modelRules;
+      levelCache.set(key, Array.isArray(rules) ? rules : []);
+    }
+    return levelCache.get(key);
+  } catch {
+    return [];
+  }
+}
+
+function builtinConfigPath(env) {
+  try {
+    const { resolveEngine, resolveBuiltinProviderConfig } = require('./engine.js');
+    return resolveBuiltinProviderConfig(resolveEngine(env), env);
+  } catch {
+    return null;
+  }
+}
+
+// Efforts (a subset of EFFORT_LEVELS, in enum order) the model accepts.
+function supportedEfforts(model, { env = process.env, builtinConfig } = {}) {
+  const file = builtinConfig || builtinConfigPath(env);
+  let values = 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 */
+      }
+      const v = match && rule.config && rule.config.optionSpecs && rule.config.optionSpecs.reasoningLevel
+        && rule.config.optionSpecs.reasoningLevel.values;
+      if (Array.isArray(v)) values = v;
+    }
+  }
+  const levels = values ? EFFORT_LEVELS.filter((l) => values.includes(l)) : [];
+  return levels.length ? levels : FALLBACK_LEVELS[model] || [];
+}
+
+// {modelId: [levels]} for every supported model (doctor).
+function modelLevels(opts) {
+  return Object.fromEntries(OFFICIAL_IDS.map((id) => [id, supportedEfforts(id, opts)]));
+}
+
+// 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 } = {}) {
+  const levels = supportedEfforts(model, opts);
+  if (levels.includes(effort)) return null;
+  return `${source} ${effort} is not supported by ${model} (supported: ${levels.join(', ')}).`;
+}
+
 module.exports = {
+  supportedEfforts,
+  modelLevels,
+  effortProblem,
+  FALLBACK_LEVELS,
   DEFAULT_MODEL,
   normalizeModel,
   unknownModelMessage,