factoryhub 0.0.0-stage → 0.1.0

package/packages/engine/src/factory-engine.mjs

@@ -0,0 +1,1762 @@
+// quantum_posture: run receipts are signed with classical Ed25519, which is not post-quantum. They attest what a run did at the time; nothing long-lived or secret is protected by the signature.
+// The factory engine: reads a factory bundle, runs its flow, writes a receipt.
+// One file, no dependencies. The same code runs on factory.mindburn.org, in the
+// browser with your own model, and from `node run.mjs` on your machine.
+// SPDX-License-Identifier: Apache-2.0. The format is specified in spec/ of the factoryhub repository.
+
+export const FLOW_VERSION = 'mindburn.flow/v1';
+export const BUNDLE_FORMAT = 'mindburn.factory.bundle/v1';
+export const REQUIRED_FEATURES = ['scoped-context', 'multiple-outputs'];
+export const STEP_KINDS = ['work', 'check', 'approve', 'deliver'];
+export const TOOLS = ['web_search', 'web_fetch'];
+export const INPUT_TYPES = ['text', 'longtext', 'url'];
+export const INPUT_LIMITS = { text: 2000, longtext: 40000, url: 2000, total: 80000 };
+// What a step may say in flow.yaml, and the names other harnesses use for
+// tools and connections: those count as tools this runner would have to have.
+const STEP_FIELDS = ['title', 'agent', 'kind', 'needs', 'checks', 'shows', 'tools', 'task', 'rounds', 'context', 'criteria'];
+const NEEDS_FIELDS = ['mcp', 'mcpServers', 'mcp_servers', 'connectors', 'plugins', 'skills'];
+const EXECUTION_FIELDS = [...NEEDS_FIELDS, 'tools', 'secrets', 'networkPolicy', 'extends', 'params', 'runner', 'environmentId', 'workerHost', 'credentialStrategy', 'required_repos', 'spawnableBy', 'repositories', 'cloudProviders', 'providers', 'integrations'];
+const hasRequirement = value => value !== undefined && value !== null && value !== ''
+  && !(Array.isArray(value) && value.length === 0)
+  && !(typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === 0);
+// How a tool asked for under one of those fields is named in a step's `missing`.
+const neededName = (field, item) => `${field}: ${typeof item === 'string' ? item : JSON.stringify(item)}`.slice(0, 80);
+
+// Takes one tool, named as a step's `tools` or `missing` names it, out of that
+// step's entry in flow.yaml, whichever field asks for it. A field left empty goes.
+export function dropTool(spec, tool) {
+  for (const field of ['tools', ...NEEDS_FIELDS]) {
+    const items = [].concat(spec[field] ?? []);
+    const left = items.filter((item) => (field === 'tools' ? String(item).trim() : neededName(field, item)) !== tool);
+    if (left.length === items.length) continue;
+    if (left.length) spec[field] = left;
+    else delete spec[field];
+  }
+  return spec;
+}
+
+export function slugify(text) {
+  return String(text || '').toLowerCase().normalize('NFKD').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 64);
+}
+const idOf = (text) => slugify(text).replace(/-/g, '_');
+
+// ------------------------------------------------------------------ yaml ----
+// The YAML a factory uses: nested maps, lists, inline lists, quoted and plain
+// scalars, comments, and block text under `|` or `>`. Anchors, tags and
+// multi-document files are not supported and are reported as errors.
+
+function scalar(text) {
+  const value = text.trim();
+  if (value === '' || value === '~' || value === 'null') return null;
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  if (/^-?\d+(\.\d+)?$/.test(value)) return Number(value);
+  if (value.startsWith('"') && value.endsWith('"') && value.length > 1) { try { return JSON.parse(value); } catch { return value.slice(1, -1); } }
+  if (value.startsWith("'") && value.endsWith("'") && value.length > 1) return value.slice(1, -1).replace(/''/g, "'");
+  if (value === '[]') return [];
+  if (value === '{}') return {};
+  if (value.startsWith('[') && value.endsWith(']')) return splitInline(value.slice(1, -1)).map(scalar);
+  if (value.startsWith('{') && value.endsWith('}')) {
+    const entries = splitInline(value.slice(1, -1)).map((pair) => { const at = pair.indexOf(':'); if (at < 0) throw new Error('An inline YAML map needs key: value entries.'); return [String(scalar(pair.slice(0, at))), scalar(pair.slice(at + 1))]; });
+    if (new Set(entries.map(([key]) => key)).size !== entries.length) throw new Error('An inline YAML map repeats a key.');
+    return Object.fromEntries(entries);
+  }
+  if (/^[&*!]/.test(value)) throw new Error(`YAML anchors and tags are not supported: ${value.slice(0, 30)}`);
+  return value;
+}
+
+function splitInline(text) {
+  const parts = [];
+  let depth = 0;
+  let quote = '';
+  let current = '';
+  for (const char of text) {
+    if (quote) { current += char; if (char === quote) quote = ''; continue; }
+    if (char === '"' || char === "'") { quote = char; current += char; continue; }
+    if (char === '[' || char === '{') depth += 1;
+    if (char === ']' || char === '}') depth -= 1;
+    if (char === ',' && depth === 0) { parts.push(current); current = ''; continue; }
+    current += char;
+  }
+  if (current.trim()) parts.push(current);
+  return parts;
+}
+
+function stripComment(line) {
+  let quote = '';
+  for (let i = 0; i < line.length; i += 1) {
+    const char = line[i];
+    if (quote) { if (char === quote) quote = ''; continue; }
+    if (char === '"' || char === "'") quote = char;
+    else if (char === '#' && (i === 0 || /\s/.test(line[i - 1]))) return line.slice(0, i);
+  }
+  return line;
+}
+
+// How many lines of a YAML file carry a comment.
+export const countComments = (text) => String(text || '').split('\n').filter((line) => stripComment(line) !== line).length;
+
+export function parseYaml(text) {
+  const lines = String(text || '').replace(/\r\n/g, '\n').replace(/\t/g, '  ').split('\n');
+  let at = 0;
+  const indentOf = (line) => line.match(/^ */)[0].length;
+  const blank = (line) => !stripComment(line).trim();
+  const skip = () => { while (at < lines.length && blank(lines[at])) at += 1; };
+
+  function block(parentIndent, style) {
+    const collected = [];
+    let indent = null;
+    while (at < lines.length) {
+      const line = lines[at];
+      if (!line.trim()) { collected.push(''); at += 1; continue; }
+      const current = indentOf(line);
+      if (current <= parentIndent) break;
+      if (indent === null) indent = current;
+      collected.push(line.slice(Math.min(indent, current)));
+      at += 1;
+    }
+    while (collected.length && collected[collected.length - 1] === '') collected.pop();
+    const joined = style[0] === '|' ? collected.join('\n') : collected.join('\n').replace(/([^\n])\n(?!\n)/g, '$1 ').replace(/\n\n/g, '\n');
+    return style.endsWith('-') ? joined : `${joined}\n`;
+  }
+
+  function value(rest, indent) {
+    const trimmed = stripComment(rest).trim();
+    if (/^[|>][+-]?$/.test(trimmed)) return block(indent, trimmed);
+    if (trimmed === '') {
+      skip();
+      if (at < lines.length && (indentOf(lines[at]) > indent || (indentOf(lines[at]) === indent && lines[at].trim().startsWith('- ')))) return node(indentOf(lines[at]));
+      return null;
+    }
+    return scalar(trimmed);
+  }
+
+  function node(indent) {
+    skip();
+    if (at >= lines.length) return null;
+    if (lines[at].trim().startsWith('- ') || lines[at].trim() === '-') {
+      const list = [];
+      while (at < lines.length) {
+        skip();
+        if (at >= lines.length || indentOf(lines[at]) !== indent || !/^-( |$)/.test(lines[at].trim())) break;
+        const rest = lines[at].slice(indent + 1);
+        const inner = rest.replace(/^ /, '');
+        if (/^[A-Za-z0-9_."'-]+:( |$)/.test(stripComment(inner).trim()) && !/^["'].*["']$/.test(stripComment(inner).trim())) {
+          lines[at] = `${' '.repeat(indent + 2)}${inner}`;
+          list.push(node(indent + 2));
+        } else {
+          at += 1;
+          list.push(value(inner, indent));
+        }
+      }
+      return list;
+    }
+    const map = {};
+    while (at < lines.length) {
+      skip();
+      if (at >= lines.length || indentOf(lines[at]) !== indent) break;
+      if (lines[at] === '...') break;
+      if (lines[at] === '---') throw new Error('Multiple YAML documents are not supported. Use one document per file.');
+      const line = lines[at].slice(indent);
+      const match = line.match(/^("[^"]*"|'[^']*'|[^:#]+?):( |$)(.*)$/);
+      if (!match) throw new Error(`Line ${at + 1} is not "key: value": ${line.trim().slice(0, 60)}`);
+      at += 1;
+      const key = String(scalar(match[1]));
+      if (Object.hasOwn(map, key)) throw new Error(`Line ${at} repeats the key "${key}": each name can appear once.`);
+      Object.defineProperty(map, key, { value: value(match[3] || '', indent), enumerable: true, configurable: true, writable: true });
+    }
+    return map;
+  }
+
+  skip();
+  if (lines[at] === '---') { at += 1; skip(); }
+  const result = node(at < lines.length ? indentOf(lines[at]) : 0);
+  skip();
+  if (lines[at] === '...') { at += 1; skip(); }
+  if (at < lines.length) throw new Error(`Line ${at + 1} has unexpected indentation: ${lines[at].trim().slice(0, 60)}`);
+  return result;
+}
+
+const plainSafe = (text) => /^[A-Za-z0-9_./@()+-][A-Za-z0-9_./@ ()+'-]*$/.test(text) && !/^(true|false|null|~|-?\d+(\.\d+)?)$/.test(text) && !text.endsWith(' ') && !text.includes(': ') && !text.startsWith('- ');
+
+export function toYaml(value, indent = 0) {
+  const pad = ' '.repeat(indent);
+  const inline = (item) => {
+    if (item === null || item === undefined) return 'null';
+    if (typeof item === 'string') return plainSafe(item) ? item : JSON.stringify(item);
+    if (Array.isArray(item)) return `[${item.map(inline).join(', ')}]`;
+    return String(item);
+  };
+  if (Array.isArray(value)) {
+    if (!value.length) return `${pad}[]\n`;
+    return value.map((item) => (item && typeof item === 'object' && !Array.isArray(item)
+      ? `${pad}- ${toYaml(item, indent + 2).trimStart()}`
+      : `${pad}- ${inline(item)}\n`)).join('');
+  }
+  if (value && typeof value === 'object') {
+    return Object.entries(value).filter(([, item]) => item !== undefined).map(([key, item]) => {
+      const name = /^[A-Za-z_][A-Za-z0-9_.-]*$/.test(key) && !/^(true|false|null)$/.test(key) ? key : JSON.stringify(key);
+      // Text over several lines is written as a block; `|-` when it does not
+      // end with a line break, so it reads back exactly as it was.
+      if (typeof item === 'string' && item.includes('\n') && !/^\s/.test(item) && !/\n\n$/.test(item) && !/[ \t]\n/.test(item)) {
+        const ends = item.endsWith('\n');
+        return `${pad}${name}: ${ends ? '|' : '|-'}\n${(ends ? item.slice(0, -1) : item).split('\n').map((line) => (line ? `${pad}  ${line}` : '')).join('\n')}\n`;
+      }
+      if (typeof item === 'string' && item.includes('\n')) return `${pad}${name}: ${JSON.stringify(item)}\n`;
+      if (Array.isArray(item)) {
+        if (item.every((entry) => entry === null || typeof entry !== 'object') && item.join(', ').length < 70 && item.every((entry) => typeof entry !== 'string' || plainSafe(entry))) return `${pad}${name}: ${inline(item)}\n`;
+        return `${pad}${name}:\n${toYaml(item, indent + 2)}`;
+      }
+      if (item && typeof item === 'object') return Object.keys(item).length ? `${pad}${name}:\n${toYaml(item, indent + 2)}` : `${pad}${name}: {}\n`;
+      return `${pad}${name}: ${inline(item)}\n`;
+    }).join('');
+  }
+  return `${pad}${inline(value)}\n`;
+}
+
+// ---------------------------------------------------------------- format ----
+// A factory is a bundle of text files:
+//   factory.yaml                 name, description, default harness
+//   agents/<name>/agent.md       one file per agent: its role and standing instructions
+//   flow.yaml                    the steps, who does each, what each needs, and the inputs
+
+export function parseFrontmatter(text) {
+  const normalized = String(text || '').replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
+  const match = normalized.match(/^---\n((?:[^\n]*\n)*?)---(?:\n|$)/);
+  if (!match) return { meta: {}, body: normalized.trim(), ...(normalized.startsWith('---\n') ? { error: 'Agent settings need a closing --- delimiter.' } : {}) };
+  let meta = {};
+  try { meta = parseYaml(match[1]) || {}; } catch {
+    return { meta: {}, body: normalized.slice(match[0].length).trim(), error: 'Agent settings contain invalid or unsupported YAML.' };
+  }
+  return { meta, body: normalized.slice(match[0].length).trim() };
+}
+
+export const AGENT_PATH = /^agents\/([a-z0-9][a-z0-9_-]{0,40})\/agent\.md$/;
+
+export function normalizeFiles(files) {
+  const out = {};
+  for (const [path, content] of Object.entries(files || {})) out[path] = String(content ?? '').replace(/\r\n/g, '\n');
+  return Object.fromEntries(Object.keys(out).sort().map((path) => [path, out[path]]));
+}
+
+function levelsOf(steps) {
+  const byId = Object.fromEntries(steps.map((step) => [step.id, step]));
+  const level = {};
+  const visit = (id, trail) => {
+    if (level[id] !== undefined) return level[id];
+    if (trail.has(id)) throw new Error(`Steps depend on each other in a circle through "${id}".`);
+    trail.add(id);
+    const value = byId[id].needs.length ? Math.max(...byId[id].needs.map((need) => visit(need, trail))) + 1 : 0;
+    trail.delete(id);
+    level[id] = value;
+    return value;
+  };
+  steps.forEach((step) => visit(step.id, new Set()));
+  return level;
+}
+
+export function ancestorsOf(factory, id) {
+  const byId = Object.fromEntries(factory.steps.map((step) => [step.id, step]));
+  const seen = new Set();
+  const walk = (current) => { for (const need of byId[current]?.needs || []) { if (!seen.has(need)) { seen.add(need); walk(need); } } };
+  walk(id);
+  return factory.steps.filter((step) => seen.has(step.id)).map((step) => step.id);
+}
+
+export function dependentsOf(factory, id) {
+  return factory.steps.filter((step) => step.id !== id && ancestorsOf(factory, step.id).includes(id)).map((step) => step.id);
+}
+
+export function parseBundle(input) {
+  const files = normalizeFiles(input);
+  const errors = [];
+  const warnings = [];
+  const factory = { name: '', description: '', title: '', author: '', version: '1.0.0', license: '', tags: [], time: '', harness: null, inputs: [], steps: [], agents: {}, done: [], blockers: [], flowValid: false, runnable: false, files };
+  factory.unsupportedRequirements = [];
+  const requirements = (settings, source, prefix = '') => {
+    if (!settings || typeof settings !== 'object') return;
+    for (const field of EXECUTION_FIELDS) {
+      // An explicitly empty network policy still restricts egress. Never
+      // mistake it for an absent requirement. Do not expose configured values.
+      if ((['networkPolicy', 'spawnableBy'].includes(field) && Object.hasOwn(settings, field)) || hasRequirement(settings[field])) {
+        factory.unsupportedRequirements.push({ source, setting: prefix + field });
+      }
+    }
+    if (hasRequirement(settings.harness?.auth)) factory.unsupportedRequirements.push({ source, setting: `${prefix}harness.auth` });
+  };
+  const agentSettings = new Map();
+
+  let config = null;
+  if (!files['factory.yaml']) errors.push('The bundle needs a factory.yaml file.');
+  else {
+    try { config = parseYaml(files['factory.yaml']); } catch (error) { errors.push(`factory.yaml: ${error.message}`); }
+  }
+  if (config && typeof config === 'object') {
+    factory.name = slugify(config.name);
+    // A wrapped description reads as paragraphs, not as line breaks.
+    factory.description = String(config.description || '').trim().replace(/([^\n])\n(?!\n)/g, '$1 ');
+    factory.harness = config.agentDefaults?.harness || (config.agentDefaults?.model ? { model: config.agentDefaults.model } : null);
+    requirements(config, 'factory.yaml');
+    requirements(config.agentDefaults, 'factory.yaml', 'agentDefaults.');
+    if (!config.schemaVersion) errors.push('factory.yaml needs `schemaVersion: v1alpha1`.');
+    if (!config.name) errors.push('factory.yaml needs a `name`.');
+    else if (String(config.name) !== factory.name) errors.push(`factory.yaml \`name\` must be lowercase letters, digits and hyphens: try \`${factory.name}\`.`);
+    if (!factory.description) errors.push('factory.yaml needs a `description`: what the factory produces and when to use it.');
+  }
+
+  for (const [path, content] of Object.entries(files)) {
+    const match = path.match(AGENT_PATH);
+    if (!match) continue;
+    const { meta, body, error } = parseFrontmatter(content);
+    if (error) errors.push(`${path}: ${error}`);
+    agentSettings.set(match[1], { meta, path });
+    factory.agents[match[1]] = { name: match[1], description: String(meta.description || ''), type: String(meta.agentType || 'CUSTOM').toUpperCase(), body };
+  }
+  if (Object.keys(factory.agents).length > 40) errors.push('A factory has at most 40 agents.');
+
+  let flow = null;
+  if (files['flow.yaml']) {
+    try { flow = parseYaml(files['flow.yaml']); } catch (error) { errors.push(`flow.yaml: ${error.message}`); }
+  } else {
+    warnings.push('This bundle has no flow.yaml, so it can be read, shared and taken away, but the hub cannot run it. Add a flow to make it runnable.');
+  }
+
+  if (flow && typeof flow === 'object') {
+    if (flow.requires !== undefined && (!Array.isArray(flow.requires) || flow.requires.some((feature) => !REQUIRED_FEATURES.includes(feature)))) errors.push('This flow requires unsupported execution features. Use a compatible runner.');
+    factory.title = String(flow.title || '');
+    factory.author = String(flow.author || '');
+    factory.version = String(flow.version ?? '1.0.0');
+    factory.license = String(flow.license || '');
+    factory.time = String(flow.time || '');
+    factory.tags = (Array.isArray(flow.tags) ? flow.tags : String(flow.tags || '').split(',')).map((tag) => String(tag).trim().toLowerCase()).filter(Boolean);
+    factory.done = (Array.isArray(flow.done) ? flow.done : []).map((item) => (item && typeof item === 'object' ? Object.entries(item).map(([key, value]) => `${key}: ${value}`).join(', ') : String(item)));
+    if (flow.flow && flow.flow !== FLOW_VERSION) warnings.push(`flow.yaml says "${flow.flow}"; this runner reads ${FLOW_VERSION}.`);
+
+    if (flow.inputs && (typeof flow.inputs !== 'object' || Array.isArray(flow.inputs))) errors.push('flow.yaml inputs must be a map of named inputs.');
+    const inputIds = new Set();
+    for (const [key, spec] of Object.entries(flow.inputs || {})) {
+      const detail = spec && typeof spec === 'object' ? spec : { help: String(spec || '') };
+      const type = INPUT_TYPES.includes(detail.type) ? detail.type : 'text';
+      const id = idOf(key);
+      if (!id) errors.push(`Input "${key}" needs a name containing letters or digits.`);
+      else if (inputIds.has(id)) errors.push(`Input "${key}" repeats the normalized input name "${id}".`);
+      inputIds.add(id);
+      factory.inputs.push({ key: id, label: String(detail.label || key).replace(/_/g, ' ').replace(/^./, (c) => c.toUpperCase()), type, required: detail.optional !== true && detail.required !== false, help: String(detail.help || ''), ...(detail.visibility !== undefined ? { visibility: detail.visibility } : {}) });
+      if (detail.visibility !== undefined && !['public', 'private'].includes(detail.visibility)) errors.push(`Input "${key}" visibility must be public or private.`);
+    }
+    if (factory.inputs.length > 8) errors.push('A factory asks for at most 8 inputs.');
+
+    const entries = Object.entries(flow.steps || {});
+    if (!entries.length) errors.push('flow.yaml needs at least one step under `steps:`.');
+    if (entries.length > 24) errors.push('A flow has at most 24 steps. Split bigger work into two factories.');
+    let previous = null;
+    for (const [key, raw] of entries) {
+      const spec = raw && typeof raw === 'object' ? raw : {};
+      const id = idOf(key);
+      if (!id) errors.push(`Step "${key}" needs a name containing letters or digits.`);
+      const kind = String(spec.kind || 'work').toLowerCase();
+      const needs = spec.needs === undefined || spec.needs === null ? (previous ? [previous] : []) : (Array.isArray(spec.needs) ? spec.needs : [spec.needs]).map(idOf);
+      // Every tool the step asks for, however it is written. The ones this
+      // runner has go in `tools`; the rest stay visible in `missing`.
+      const asked = [].concat(spec.tools ?? []).map((tool) => String(tool).trim()).filter(Boolean);
+      // A step can also name what it needs under another harness's words.
+      for (const field of NEEDS_FIELDS) for (const item of [].concat(spec[field] ?? [])) asked.push(neededName(field, item));
+      const unread = Object.keys(spec).filter((field) => !STEP_FIELDS.includes(field) && !NEEDS_FIELDS.includes(field));
+      if (unread.length) warnings.push(`The step "${String(spec.title || key)}" has settings this runner does not read: ${unread.join(', ')}. They are kept in the file and have no effect here.`);
+      const step = {
+        id,
+        title: String(spec.title || key).replace(/_/g, ' '),
+        agent: spec.agent ? slugify(spec.agent) : (kind === 'approve' ? 'owner' : ''),
+        kind,
+        needs,
+        target: spec.checks || spec.shows ? idOf(spec.checks || spec.shows) : null,
+        tools: asked.filter((tool) => TOOLS.includes(tool)),
+        missing: [...new Set(asked.filter((tool) => !TOOLS.includes(tool)))],
+        task: String(spec.task || '').trim(),
+        rounds: Number.isInteger(spec.rounds) ? Math.max(0, Math.min(5, spec.rounds)) : (kind === 'approve' ? 3 : 1),
+      };
+      if (spec.context !== undefined) {
+        const context = spec.context;
+        const map = (value) => value && typeof value === 'object' && !Array.isArray(value);
+        if (!map(context) || Object.keys(context).some((key) => !['inputs', 'artifacts', 'public'].includes(key)) || (context.public !== undefined && typeof context.public !== 'boolean')) errors.push(`Step "${id}" has an invalid context.`);
+        else {
+          step.context = { inputs: {}, artifacts: {}, ...(context.public !== undefined ? { public: context.public } : {}) };
+          for (const field of ['inputs', 'artifacts']) {
+            if (context[field] !== undefined && !map(context[field])) { errors.push(`Step "${id}" context.${field} must map names to references.`); continue; }
+            for (const [alias, ref] of Object.entries(context[field] || {})) {
+              if (!/^[a-z][a-z0-9_]{0,63}$/.test(alias) || typeof ref !== 'string' || ref !== idOf(ref)) errors.push(`Step "${id}" has an invalid ${field} binding.`);
+              else step.context[field][alias] = ref;
+            }
+          }
+          if (Object.keys(step.context.inputs).some((key) => Object.hasOwn(step.context.artifacts, key))) errors.push(`Step "${id}" repeats a context binding name.`);
+        }
+      }
+      if (spec.criteria !== undefined) {
+        if (!Array.isArray(spec.criteria) || spec.criteria.some((item) => typeof item !== 'string' || !item.trim())) errors.push(`Step "${id}" criteria must be a list of text.`);
+        else step.criteria = [...spec.criteria];
+      }
+      factory.steps.push(step);
+      previous = id;
+    }
+
+    const ids = factory.steps.map((step) => step.id);
+    if (new Set(ids).size !== ids.length) errors.push('Two steps share the same name.');
+    for (const step of factory.steps) {
+      if (!STEP_KINDS.includes(step.kind)) errors.push(`Step "${step.id}" has kind "${step.kind}". Use one of: ${STEP_KINDS.join(', ')}.`);
+      for (const need of step.needs) if (!ids.includes(need)) errors.push(`Step "${step.id}" needs "${need}", which is not a step.`);
+      if ((step.kind === 'work' || step.kind === 'deliver') && !step.task) errors.push(`Step "${step.id}" needs a \`task\`: what to do, in plain words.`);
+      if (step.kind !== 'approve') {
+        if (!step.agent) errors.push(`Step "${step.id}" needs an \`agent\`.`);
+        else if (!factory.agents[step.agent]) errors.push(`Step "${step.id}" is done by "${step.agent}", but there is no agents/${step.agent}/agent.md.`);
+      }
+    }
+    if (!errors.length) {
+      try { levelsOf(factory.steps); } catch (error) { errors.push(error.message); }
+    }
+    if (!errors.length) {
+      for (const step of factory.steps) {
+        if (step.kind !== 'check' && step.kind !== 'approve') continue;
+        const upstream = ancestorsOf(factory, step.id).filter((id) => ['work', 'deliver'].includes(factory.steps.find((item) => item.id === id).kind));
+        if (!step.target) step.target = step.needs.find((need) => upstream.includes(need)) || upstream[upstream.length - 1] || null;
+        if (!step.target) errors.push(`Step "${step.id}" (${step.kind}) has no earlier work to ${step.kind === 'check' ? 'check' : 'show'}.`);
+        else if (!upstream.includes(step.target)) errors.push(`Step "${step.id}" points at "${step.target}", which does not come before it.`);
+      }
+      if (!factory.steps.some((step) => step.kind === 'deliver' || step.kind === 'work')) errors.push('A flow needs at least one work or deliver step.');
+    }
+    if (!errors.length) {
+      for (const step of factory.steps) {
+        if (!step.context) continue;
+        for (const ref of Object.values(step.context.inputs)) if (!inputIds.has(ref)) errors.push(`Step "${step.id}" binds unknown input "${ref}".`);
+        const ancestors = ancestorsOf(factory, step.id);
+        for (const ref of Object.values(step.context.artifacts)) {
+          if (!ancestors.includes(ref) || !['work', 'deliver'].includes(factory.steps.find((item) => item.id === ref)?.kind)) errors.push(`Step "${step.id}" artifact "${ref}" must be earlier work in its dependencies.`);
+        }
+      }
+    }
+    if (!errors.length) {
+      const privateSteps = new Set();
+      const sources = new Map();
+      for (const step of factory.steps) {
+        const inputs = step.context ? Object.values(step.context.inputs) : factory.inputs.map((item) => item.key);
+        const artifacts = step.context ? Object.values(step.context.artifacts) : ancestorsOf(factory, step.id);
+        if (step.target) artifacts.push(step.target);
+        sources.set(step.id, artifacts);
+        // A person's revision note has no public-data declaration.
+        if (step.kind === 'approve' || inputs.some((key) => factory.inputs.find((item) => item.key === key)?.visibility !== 'public')) privateSteps.add(step.id);
+      }
+      // Reviews and owner revisions feed their subject back. These data edges
+      // form cycles, so propagate privacy to a fixed point instead of assuming
+      // the execution DAG alone describes every route data can take.
+      for (const step of factory.steps) if (step.target) sources.get(step.target).push(step.id);
+      let changed;
+      do {
+        changed = false;
+        for (const step of factory.steps) {
+          if (!privateSteps.has(step.id) && sources.get(step.id).some((id) => privateSteps.has(id))) { privateSteps.add(step.id); changed = true; }
+        }
+      } while (changed);
+      const isPublic = (id) => !privateSteps.has(id);
+      for (const step of factory.steps) {
+        if (step.context?.public && !isPublic(step.id)) errors.push(`Public step "${step.id}" cannot receive private inputs or artifacts.`);
+        if (step.kind === 'check' && factory.steps.find((item) => item.id === step.target)?.context?.public && !isPublic(step.id)) errors.push(`Reviewer "${step.id}" cannot send private feedback to public work.`);
+      }
+    }
+    if (flow.outputs !== undefined) {
+      factory.outputs = [];
+      if (!Array.isArray(flow.outputs) || !flow.outputs.length || flow.outputs.length > 24) errors.push('outputs must declare between 1 and 24 artifacts.');
+      else for (const output of flow.outputs) {
+        if (!output || typeof output !== 'object' || Object.keys(output).some((key) => !['step', 'title'].includes(key)) || typeof output.title !== 'string' || !output.title.trim() || output.title.length > 200 || !factory.steps.some((step) => step.id === output.step && ['work', 'deliver'].includes(step.kind)) || factory.outputs.some((item) => item.step === output.step)) errors.push('Each output needs a unique work or deliver step and a title.');
+        else factory.outputs.push({ step: output.step, title: output.title });
+      }
+    }
+    if (flow.composition !== undefined) {
+      const value = flow.composition;
+      if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some((key) => !['compiler', 'intent', 'sources', 'unmetCapabilities'].includes(key)) || value.compiler !== 'mindburn.compose/v1' || typeof value.intent !== 'string' || !Array.isArray(value.sources) || value.sources.some((source) => !source || typeof source.id !== 'string' || typeof source.name !== 'string' || typeof source.version !== 'string' || !/^[a-f0-9]{64}$/.test(source.sha256)) || !Array.isArray(value.unmetCapabilities) || value.unmetCapabilities.some((item) => typeof item !== 'string')) errors.push('Composition metadata must preserve a supported compiler, original intent, source hashes and unmet capabilities.');
+      else factory.composition = value;
+    }
+    // A flow that reads correctly but asks for a tool this runner does not
+    // have is valid source and is not run: a run without the tool would be a
+    // different factory from the one its author wrote.
+    factory.flowValid = errors.length === 0;
+    const usedAgents = new Set(factory.steps.map(step => step.agent));
+    for (const name of usedAgents) {
+      const settings = agentSettings.get(name);
+      if (settings) requirements(settings.meta, settings.path);
+    }
+    for (const path of Object.keys(files)) {
+      const skill = path.match(/^(?:agents\/([^/]+)\/)?skills\/[^/]+(?:\/(?:.*\/)?SKILL\.md|\.ya?ml)$/);
+      if (skill && (!skill[1] || usedAgents.has(skill[1]))) factory.unsupportedRequirements.push({ source: path, setting: 'skill' });
+    }
+    for (const step of factory.steps) {
+      if (step.missing.length) factory.blockers.push(`The step "${step.title}" needs ${step.missing.map((tool) => `\`${tool}\``).join(' and ')}, which this runner does not have (it has ${TOOLS.join(' and ')}). It can be read, shared and taken to a harness that has ${step.missing.length === 1 ? 'that tool' : 'those tools'}; to run it here, change the step.`);
+    }
+    for (const { source, setting } of factory.unsupportedRequirements) factory.blockers.push(`This factory requires \`${setting}\` in \`${source}\`, which this runner cannot apply. The source is preserved for a compatible runtime.`);
+    warnings.push(...factory.blockers);
+    factory.runnable = factory.flowValid && factory.blockers.length === 0;
+    if (files['agents/foreman/agent.md'] !== undefined && !isGeneratedForeman(files['agents/foreman/agent.md'])) warnings.push('agents/foreman/agent.md was written by the author, so it is kept as it is and is not rewritten from the flow. A harness without a flow file follows it; check that it still describes these steps.');
+  }
+  if (!factory.title) factory.title = factory.name.replace(/-/g, ' ').replace(/^./, (c) => c.toUpperCase());
+  return { ok: errors.length === 0, errors, warnings, factory };
+}
+
+// The step whose result is the deliverable: the last deliver step, or the last
+// work step when the flow has no deliver.
+export function finalStep(factory) {
+  const reversed = [...factory.steps].reverse();
+  return reversed.find((step) => step.kind === 'deliver') || reversed.find((step) => step.kind === 'work') || null;
+}
+
+// Positions for drawing the flow: a column per level, parallel steps stacked.
+export function layout(factory) {
+  const level = levelsOf(factory.steps);
+  const columns = [];
+  for (const step of factory.steps) (columns[level[step.id]] ||= []).push(step.id);
+  return { level, columns };
+}
+
+// The foreman's instructions, written from the flow, so a harness that has no
+// flow.yaml can read the workflow's instructions from prose.
+export function foremanText(factory) {
+  const last = finalStep(factory);
+  const lines = factory.steps.map((step, index) => {
+    const scope = step.context ? ` Share only these bindings: inputs ${JSON.stringify(step.context.inputs)}, artifacts ${JSON.stringify(step.context.artifacts)}.${step.context.public ? ' This is public research: never add private facts.' : ''}` : '';
+    const after = (step.needs.length ? ` After ${step.needs.join(' and ')}.` : '') + scope;
+    if (step.kind === 'approve') return `${index + 1}. **${step.title}** (the owner decides). Show the owner the result of "${step.target}" and stop. Continue only when they approve; if they ask for changes, redo "${step.target}" with their note.${after}`;
+    if (step.kind === 'check') return `${index + 1}. **${step.title}** (agent: ${step.agent}). Review the result of "${step.target}" strictly against this: ${step.task || 'it does what was asked, with no invented facts.'} If it fails, send it back to be redone ${step.rounds === 1 ? 'once' : `up to ${step.rounds} times`} with the reasons.${after}`;
+    return `${index + 1}. **${step.title}** (agent: ${step.agent}${step.tools.length + (step.missing || []).length ? `; tools: ${[...step.tools, ...(step.missing || [])].join(', ')}` : ''}). ${step.task.split('\n')[0]}${after}`;
+  });
+  const parallel = factory.steps.filter((step) => factory.steps.some((other) => other.id !== step.id && other.needs.join() === step.needs.join() && other.needs.length)).length;
+  return `---
+description: Coordinates the ${factory.name} factory from its flow.
+agentType: FOREMAN
+---
+
+# ${factory.title}
+
+${factory.description}
+
+You coordinate this factory. Hand each step to the agent named for it, ${factory.steps.some((step) => step.context) ? 'share only its declared context bindings (checks also receive their exact subject), and collect its result. A dependency alone does not authorize sharing its text.' : 'give that agent the inputs and the results of the steps it needs, and collect its result.'}${parallel ? ' Steps that need the same earlier steps can run at the same time.' : ''} Never invent facts: agents use only the inputs, earlier results and pages they actually read.
+
+## What to ask the person for
+
+${factory.inputs.map((input) => `- **${input.key}**${input.required ? '' : ' (optional)'}: ${input.help}`).join('\n') || 'Nothing.'}
+
+## Steps
+
+${lines.join('\n')}
+
+${factory.outputs ? `Return each declared output unchanged: ${factory.outputs.map((item) => `${item.title} from ${item.step}`).join('; ')}. Combine them deterministically in declaration order; never rewrite them.` : last ? `Return the result of "${last.id}" (${last.title}) unchanged as the deliverable after all steps finish.` : 'There is no work or deliver step to return.'}${factory.done.length ? `\n\n## Done when\n\n${factory.done.map((line) => `- ${line}`).join('\n')}` : ''}
+
+The exact, executable version of these steps is flow.yaml. To run it as written, with a receipt of every step: \`node run.mjs\` in this folder, or open the factory on https://factory.mindburn.org.
+`;
+}
+
+export function toEnvelope(files, { status = 'existing-source', project = '', warnings = [], leftOut = [] } = {}) {
+  const normal = normalizeFiles(files);
+  return { format: BUNDLE_FORMAT, status, source: { project, factory_path: 'factory.yaml' }, files: Object.entries(normal).map(([path, content]) => ({ path, content })), ...(leftOut.length ? { left_out: leftOut } : {}), warnings, review_required: true, meta: { file_count: Object.keys(normal).length } };
+}
+
+const RESOURCE_NAME = '[a-z0-9][a-z0-9_-]{0,40}';
+const SOURCE_PART = '[A-Za-z0-9][A-Za-z0-9_.-]{0,80}';
+// Companion definitions travel with a factory; admitting a file grants no
+// permission to execute it. Hidden paths, traversal and executable code stay out.
+export const ALLOWED_PATH = new RegExp(`^(?:${[
+  'factory\\.yaml', 'flow\\.yaml', 'mindburn\\.(?:package|requirements|tests|company|lock)\\.yaml', 'layout\\.json', '(?:README|LICENSE|LICENCE|NOTICE|CHANGELOG)(?:\\.(?:md|txt))?',
+  `agents/${RESOURCE_NAME}/agent\\.md`, `automations/${RESOURCE_NAME}/automation\\.md`, `scorers/${RESOURCE_NAME}/scorer\\.md`,
+  `(?:runners|routers|webhooks)/${RESOURCE_NAME}\\.yaml`,
+  `benchmarks/${RESOURCE_NAME}/(?:suite\\.yaml|tasks/${RESOURCE_NAME}\\.yaml)`,
+  `(?:agents/${RESOURCE_NAME}/)?skills/${RESOURCE_NAME}/(?:${SOURCE_PART}/){0,6}${SOURCE_PART}\\.md`,
+  `(?:agents/${RESOURCE_NAME}/)?skills/${RESOURCE_NAME}\\.ya?ml`, 'self-improvement/agent\\.md',
+  `(?:profiles|flows|schemas|prompts|assets|examples|checks|fixtures|capabilities|policies|adapters|ui)/(?:${SOURCE_PART}/){0,6}${SOURCE_PART}\\.(?:yaml|yml|json|md|txt|csv|svg)`,
+].join('|')})(?![\\s\\S])`);
+
+// Reads a transfer bundle (from the import skill or a hub export) into files,
+// checking paths, sizes and each file's recorded SHA-256.
+export async function fromEnvelope(envelope) {
+  const problems = [];
+  if (!envelope || envelope.format !== BUNDLE_FORMAT || !Array.isArray(envelope.files)) return { files: {}, problems: [`This is not a ${BUNDLE_FORMAT} file.`], leftOut: [], status: null, warnings: [] };
+  const validWarnings = envelope.warnings === undefined || (Array.isArray(envelope.warnings) && envelope.warnings.every((warning) => typeof warning === 'string'));
+  if (!validWarnings) problems.push('Bundle warnings must be a list of text messages.');
+  const validLeftOut = envelope.left_out === undefined || (Array.isArray(envelope.left_out) && envelope.left_out.every((path) => typeof path === 'string'));
+  if (!validLeftOut) problems.push('Left-out paths must be a list of text paths.');
+  if (envelope.source?.project !== undefined && typeof envelope.source.project !== 'string') problems.push('The source project name must be text.');
+  const files = {};
+  // Files of the project that are not part of the factory: named by the
+  // exporter, or sent anyway. They are listed for the person, never stored.
+  const leftOut = (validLeftOut ? envelope.left_out || [] : []).slice(0, 60).map((path) => path.slice(0, 120));
+  let total = 0;
+  const seen = new Set();
+  if (envelope.files.length > 60) problems.push(`The bundle has ${envelope.files.length} files; a factory bundle has at most 60.`);
+  for (const entry of envelope.files.slice(0, 60)) {
+    if (!entry || typeof entry.path !== 'string' || typeof entry.content !== 'string') { problems.push('Every source entry needs a text path and text content.'); continue; }
+    const { path, content } = entry;
+    const bytes = new TextEncoder().encode(content).length;
+    total += bytes;
+    if (seen.has(path)) { problems.push(`"${path.slice(0, 80)}" appears more than once. Each file needs one exact version.`); continue; }
+    seen.add(path);
+    if (!ALLOWED_PATH.test(path)) {
+      if (!path || /^\/|(^|\/)\.\.?(\/|$)|\\|[\u0000-\u001f]/.test(path)) problems.push(`"${path.slice(0, 80)}" is not a file a factory bundle may contain.`);
+      else if (!leftOut.includes(path.slice(0, 120))) leftOut.push(path.slice(0, 120));
+      continue;
+    }
+    if (entry.sha256 !== undefined && (typeof entry.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(entry.sha256) || (await sha256(content)) !== entry.sha256)) { problems.push(`"${path}" does not match its recorded checksum.`); continue; }
+    if (entry.bytes !== undefined && entry.bytes !== bytes) { problems.push(`"${path}" does not match its recorded byte length.`); continue; }
+    files[path] = content;
+  }
+  if (total > 400000) problems.push('The bundle is larger than 400,000 UTF-8 bytes.');
+  return { files: normalizeFiles(files), problems, leftOut, status: envelope.status === 'inferred-draft' ? 'inferred-draft' : 'existing-source', warnings: validWarnings ? (envelope.warnings || []).slice(0, 10) : [] };
+}
+
+// ------------------------------------------------------------- hashing ----
+
+const encoder = new TextEncoder();
+
+export function toBase64Url(bytes) {
+  let binary = '';
+  for (const byte of new Uint8Array(bytes)) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+export function fromBase64Url(text) {
+  const binary = atob(text.replace(/-/g, '+').replace(/_/g, '/'));
+  return Uint8Array.from(binary, (char) => char.charCodeAt(0));
+}
+
+export async function sha256(text) {
+  const digest = await crypto.subtle.digest('SHA-256', encoder.encode(String(text)));
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+
+// Canonical JSON: object keys sorted at every level, no whitespace.
+export function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().filter((key) => value[key] !== undefined).map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value ?? null);
+}
+
+// A bundle's identity: the hash of its files, whatever order they came in.
+export async function bundleHash(files) {
+  return sha256(canonical(normalizeFiles(files)));
+}
+
+export async function factoryId(files) {
+  const parsed = parseBundle(files);
+  return `${parsed.factory.name || 'factory'}-${(await bundleHash(files)).slice(0, 10)}`;
+}
+
+// Verifies a receipt against the hub's published Ed25519 keys and, when the
+// deliverable text is given, against its recorded hash.
+export async function verifyReceipt(receipt, keys, deliverable) {
+  const result = { signed: false, signatureValid: false, deliverableMatches: null, keyId: null, problems: [] };
+  if (!receipt || receipt.kind !== 'factory-run-receipt') {
+    result.problems.push('This is not a factory run receipt.');
+    return result;
+  }
+  if (typeof deliverable === 'string') {
+    result.deliverableMatches = (await sha256(deliverable)) === receipt.deliverable_sha256;
+    if (!result.deliverableMatches) result.problems.push('The deliverable text does not match the hash in the receipt.');
+  }
+  const signature = receipt.signature;
+  if (!signature) {
+    result.problems.push('The receipt is not signed: it was written by a local run and is self-attested.');
+    return result;
+  }
+  result.signed = true;
+  result.keyId = signature.key_id;
+  const key = (keys || []).find((candidate) => candidate.key_id === signature.key_id);
+  if (!key) {
+    result.problems.push(`No published key with id ${signature.key_id}.`);
+    return result;
+  }
+  const { signature: _omit, ...unsigned } = receipt;
+  try {
+    const publicKey = await crypto.subtle.importKey('raw', fromBase64Url(key.public_key), { name: 'Ed25519' }, false, ['verify']);
+    result.signatureValid = await crypto.subtle.verify({ name: 'Ed25519' }, publicKey, fromBase64Url(signature.sig), encoder.encode(canonical(unsigned)));
+  } catch (error) {
+    result.problems.push(`Signature check could not run: ${error.message}`);
+  }
+  if (result.signed && !result.signatureValid && !result.problems.length) result.problems.push('The signature does not match the receipt contents.');
+  return result;
+}
+
+// ------------------------------------------------------------ web pages ----
+
+const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ', mdash: '—', ndash: '–', hellip: '…', rsquo: '’', lsquo: '‘', rdquo: '”', ldquo: '“', copy: '©', reg: '®', trade: '™' };
+
+function decodeEntities(text) {
+  return text
+    .replace(/&#(\d+);/g, (_, code) => String.fromCodePoint(Number(code)))
+    .replace(/&#x([0-9a-f]+);/gi, (_, code) => String.fromCodePoint(parseInt(code, 16)))
+    .replace(/&([a-z]+);/gi, (whole, name) => ENTITIES[name.toLowerCase()] ?? whole);
+}
+
+// Turns a web page into the text a reader would see, with headings and links
+// kept, so a station can quote and cite it.
+export function htmlToText(html, baseUrl, limit = 14000) {
+  let page = String(html || '');
+  const title = decodeEntities((page.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1] || '').trim());
+  const description = decodeEntities(page.match(/<meta[^>]+name=["']description["'][^>]*content=["']([^"']*)["']/i)?.[1]
+    || page.match(/<meta[^>]+content=["']([^"']*)["'][^>]*name=["']description["']/i)?.[1] || '');
+  page = page
+    .replace(/<!--[\s\S]*?-->/g, ' ')
+    .replace(/<(script|style|noscript|svg|template|iframe|canvas)\b[\s\S]*?<\/\1>/gi, ' ')
+    .replace(/<h([1-6])[^>]*>([\s\S]*?)<\/h\1>/gi, (_, level, inner) => `\n\n${'#'.repeat(Number(level))} ${inner.replace(/<[^>]+>/g, ' ')}\n\n`)
+    .replace(/<a\b[^>]*href=["']([^"'#][^"']*)["'][^>]*>([\s\S]*?)<\/a>/gi, (_, href, inner) => {
+      const label = inner.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim();
+      if (!label) return ' ';
+      let target = href;
+      try { target = new URL(href, baseUrl).href; } catch { /* keep as written */ }
+      return /^https?:/.test(target) ? ` [${label}](${target}) ` : ` ${label} `;
+    })
+    .replace(/<li[^>]*>/gi, '\n- ')
+    .replace(/<(br|\/p|\/div|\/tr|\/section|\/article|\/header|\/footer|\/li|\/ul|\/ol|\/table)\b[^>]*>/gi, '\n')
+    .replace(/<\/t[dh]>/gi, ' | ')
+    .replace(/<[^>]+>/g, ' ');
+  page = decodeEntities(page).replace(/[ \t\f\v ]+/g, ' ').replace(/ ?\n ?/g, '\n').replace(/\n{3,}/g, '\n\n').trim();
+  const head = [title && `Title: ${title}`, description && `Description: ${decodeEntities(description)}`].filter(Boolean).join('\n');
+  const text = `${head}\n\n${page}`.trim();
+  return text.length > limit ? `${text.slice(0, limit)}\n\n[Page cut here: ${text.length - limit} more characters not shown]` : text;
+}
+
+export function normalizeUrl(value) {
+  let text = String(value || '').trim();
+  if (!text) return null;
+  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(text)) text = `https://${text}`;
+  try {
+    const url = new URL(text);
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') return null;
+    if (!url.hostname.includes('.')) return null;
+    return url.href;
+  } catch {
+    return null;
+  }
+}
+
+// True for an address a factory may read: a public http(s) host on a normal
+// port. Local, private and literal-IP addresses are refused, so a factory (or a
+// page it read) cannot make the runner fetch from the machine it runs on.
+export function isPublicAddress(value) {
+  let url;
+  try { url = new URL(value); } catch { return false; }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') return false;
+  if (url.port && !['80', '443'].includes(url.port)) return false;
+  if (url.username || url.password) return false;
+  const host = url.hostname.toLowerCase();
+  if (!host.includes('.') || host.endsWith('.')) return false;
+  if (/^[\d.]+$/.test(host) || host.includes(':') || host.startsWith('[')) return false;
+  return !/(^|\.)(localhost|local|internal|lan|home|corp|test|invalid|onion)$/.test(host);
+}
+
+// ------------------------------------------------------------ providers ----
+
+// How long one model call may take before it is given up. Answers arrive
+// whole, not streamed, and a long deliverable or a search turn takes minutes,
+// so the limit is generous: it exists to end a call that will never answer.
+// A model on someone's own machine may be slower still.
+export const MODEL_TIMEOUT_MS = 300000;
+
+const FAILURE_CODES = new Set(['provider_timeout', 'provider_network', 'provider_unavailable', 'provider_auth', 'provider_request', 'provider_response', 'output_limit', 'context_limit', 'call_limit', 'inputs', 'tools', 'flow', 'execution_failed', 'runner_failed']);
+export function failureDetails(error) {
+  const code = FAILURE_CODES.has(error?.code) ? error.code : 'execution_failed';
+  const status = error?.status;
+  return { code, ...(Number.isInteger(status) && status >= 400 && status <= 599 ? { httpStatus: status } : {}) };
+}
+const failure = (code, message, status) => Object.assign(new Error(message), { code, ...(status ? { status } : {}) });
+
+async function postJson(fetchImpl, url, headers, body, timeoutMs = MODEL_TIMEOUT_MS, attempt = 0) {
+  let response;
+  try {
+    response = await fetchImpl(url, { method: 'POST', headers: { 'content-type': 'application/json', ...headers }, body: JSON.stringify(body), signal: AbortSignal.timeout(timeoutMs) });
+  } catch (error) {
+    if (error?.name !== 'TimeoutError' && error?.name !== 'AbortError') throw failure('provider_network', 'The connection to the model provider failed. Try again.');
+    throw failure('provider_timeout', `The model did not answer within ${Math.round(timeoutMs / 1000)} seconds.`, 504);
+  }
+  if ((response.status === 429 || response.status >= 500) && attempt < 2) {
+    await new Promise((resolve) => setTimeout(resolve, 1500 * (attempt + 1)));
+    return postJson(fetchImpl, url, headers, body, timeoutMs, attempt + 1);
+  }
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    const message = payload?.error?.message || payload?.error || `HTTP ${response.status}`;
+    const code = [401, 403].includes(response.status) ? 'provider_auth' : response.status === 429 || response.status >= 500 ? 'provider_unavailable' : 'provider_request';
+    throw failure(code, `The model provider answered ${response.status}: ${typeof message === 'string' ? message : JSON.stringify(message)}`, response.status);
+  }
+  return payload;
+}
+
+// Provider token counters stay separate: cache creation is part of input,
+// but has a different price from uncached input and cache reads.
+const tokenCount = (value) => Number.isSafeInteger(value) && value >= 0;
+const modelName = (value) => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,159}$/.test(value) ? value : null;
+const usageCategory = (value, allowed) => value == null ? null : allowed.includes(value) ? value : 'unknown';
+function providerUsage(payload, anthropic) {
+  const u = payload?.usage || {};
+  const input = anthropic ? u.input_tokens : u.prompt_tokens;
+  const output = anthropic ? u.output_tokens : u.completion_tokens;
+  const cacheReadInput = (anthropic ? u.cache_read_input_tokens : u.prompt_tokens_details?.cached_tokens) ?? 0;
+  const cacheWriteInput = anthropic ? u.cache_creation_input_tokens ?? 0 : 0;
+  const invalid = [input, output, cacheReadInput, cacheWriteInput].some((value) => value != null && !tokenCount(value));
+  return {
+    input: invalid ? NaN : (input ?? 0) + (anthropic ? cacheReadInput + cacheWriteInput : 0), output: invalid ? NaN : output ?? 0,
+    measured: tokenCount(input) && tokenCount(output) && tokenCount(cacheReadInput) && tokenCount(cacheWriteInput) && (anthropic || cacheReadInput <= input),
+    uncachedInput: input === undefined ? null : anthropic ? input : input - cacheReadInput,
+    cacheReadInput, cacheWriteInput,
+    cacheWrite5mInput: anthropic ? u.cache_creation?.ephemeral_5m_input_tokens ?? (cacheWriteInput ? null : 0) : 0,
+    cacheWrite1hInput: anthropic ? u.cache_creation?.ephemeral_1h_input_tokens ?? (cacheWriteInput ? null : 0) : 0,
+    searchRequests: anthropic ? u.server_tool_use?.web_search_requests ?? (Array.isArray(payload?.content) && payload.content.some((block) => block?.type === 'server_tool_use' && block.name === 'web_search') ? null : 0) : 0,
+    serviceTier: usageCategory(u.service_tier, ['standard', 'priority', 'batch']),
+    speed: usageCategory(u.speed, ['standard', 'fast']),
+    inferenceGeo: usageCategory(u.inference_geo, ['global', 'us']),
+  };
+}
+
+// Anthropic Messages API. Messages stay in this block format inside the engine.
+export function anthropicProvider({ apiKey, model, workspaceId, fetchImpl = fetch, browser = false, baseUrl = 'https://api.anthropic.com', timeoutMs = MODEL_TIMEOUT_MS }) {
+  return {
+    name: 'anthropic',
+    billing: baseUrl.replace(/\/$/, '') === 'https://api.anthropic.com' ? 'anthropic-direct' : null,
+    model,
+    serverSearch: true,
+    async call({ system, messages, tools = [], search = 0, forceTool, maxTokens = 4096 }) {
+      const toolList = tools.map((tool) => ({ name: tool.name, description: tool.description, input_schema: tool.input_schema }));
+      if (search > 0) toolList.push({ type: 'web_search_20250305', name: 'web_search', max_uses: search });
+      const body = { model, max_tokens: maxTokens, system, messages };
+      if (toolList.length) body.tools = toolList;
+      if (forceTool) body.tool_choice = { type: 'tool', name: forceTool };
+      const headers = { 'x-api-key': apiKey, 'anthropic-version': '2023-06-01' };
+      if (workspaceId) headers['anthropic-workspace-id'] = workspaceId;
+      if (browser) headers['anthropic-dangerous-direct-browser-access'] = 'true';
+      let payload;
+      try {
+        payload = await postJson(fetchImpl, `${baseUrl}/v1/messages`, headers, body, timeoutMs);
+      } catch (error) {
+        // Some models refuse a forced tool: ask for it in words instead.
+        if (!forceTool || error.status !== 400 || !/tool_choice/.test(error.message)) throw error;
+        delete body.tool_choice;
+        body.system = `${system}\n\nAnswer only by calling the \`${forceTool}\` tool.`;
+        payload = await postJson(fetchImpl, `${baseUrl}/v1/messages`, headers, body, timeoutMs);
+      }
+      const usage = providerUsage(payload, true);
+      try {
+        if (!Array.isArray(payload?.content)) throw failure('provider_response', 'The model returned no message content.');
+        const content = payload.content;
+        return {
+          content,
+          stop: payload.stop_reason,
+          toolCalls: content.filter((block) => block.type === 'tool_use').map((block) => ({ id: block.id, name: block.name, input: block.input || {} })),
+          searches: content.filter((block) => block.type === 'server_tool_use' && block.name === 'web_search').map((block) => block.input?.query || ''),
+          model: modelName(payload.model), usage,
+        };
+      } catch (error) { error.providerUsage = usage; error.providerModel = modelName(payload?.model); throw error; }
+    },
+  };
+}
+
+// Any OpenAI-compatible chat completions endpoint: OpenAI, OpenRouter, Ollama,
+// LM Studio, vLLM and the rest.
+export function openaiProvider({ apiKey, model, baseUrl = 'https://api.openai.com/v1', fetchImpl = fetch, timeoutMs = 600000 }) {
+  const convert = (system, messages) => {
+    const out = [{ role: 'system', content: system }];
+    for (const message of messages) {
+      const blocks = typeof message.content === 'string' ? [{ type: 'text', text: message.content }] : message.content;
+      if (message.role === 'assistant') {
+        const calls = blocks.filter((block) => block.type === 'tool_use');
+        const entry = { role: 'assistant', content: blocks.filter((block) => block.type === 'text').map((block) => block.text).join('\n') || null };
+        if (calls.length) entry.tool_calls = calls.map((call) => ({ id: call.id, type: 'function', function: { name: call.name, arguments: JSON.stringify(call.input || {}) } }));
+        out.push(entry);
+      } else {
+        for (const block of blocks.filter((item) => item.type === 'tool_result')) {
+          out.push({ role: 'tool', tool_call_id: block.tool_use_id, content: typeof block.content === 'string' ? block.content : JSON.stringify(block.content) });
+        }
+        const text = blocks.filter((block) => block.type === 'text').map((block) => block.text).join('\n');
+        if (text) out.push({ role: 'user', content: text });
+      }
+    }
+    return out;
+  };
+  return {
+    name: 'openai-compatible',
+    model,
+    serverSearch: false,
+    async call({ system, messages, tools = [], forceTool, maxTokens = 4096 }) {
+      const body = { model, messages: convert(system, messages), max_completion_tokens: maxTokens };
+      if (tools.length) body.tools = tools.map((tool) => ({ type: 'function', function: { name: tool.name, description: tool.description, parameters: tool.input_schema } }));
+      if (forceTool) body.tool_choice = { type: 'function', function: { name: forceTool } };
+      const headers = apiKey ? { authorization: `Bearer ${apiKey}` } : {};
+      let payload;
+      try {
+        payload = await postJson(fetchImpl, `${baseUrl.replace(/\/$/, '')}/chat/completions`, headers, body, timeoutMs);
+      } catch (error) {
+        // Older servers only know `max_tokens`.
+        if (error.status !== 400 || !/max_completion_tokens/.test(error.message)) throw error;
+        delete body.max_completion_tokens;
+        body.max_tokens = maxTokens;
+        payload = await postJson(fetchImpl, `${baseUrl.replace(/\/$/, '')}/chat/completions`, headers, body, timeoutMs);
+      }
+      const usage = providerUsage(payload, false);
+      try {
+        const message = payload?.choices?.[0]?.message;
+        if (!message || (message.content != null && typeof message.content !== 'string') || (message.tool_calls != null && !Array.isArray(message.tool_calls))) throw failure('provider_response', 'The model returned an invalid message.');
+        const content = [];
+        if (message.content) content.push({ type: 'text', text: message.content });
+        for (const call of message.tool_calls || []) {
+          let input = {};
+          try { input = JSON.parse(call.function?.arguments || '{}'); } catch { throw failure('provider_response', 'The model returned invalid tool arguments.'); }
+          content.push({ type: 'tool_use', id: call.id, name: call.function?.name, input });
+        }
+        return {
+          content,
+          stop: payload.choices?.[0]?.finish_reason,
+          toolCalls: content.filter((block) => block.type === 'tool_use').map((block) => ({ id: block.id, name: block.name, input: block.input })),
+          searches: [],
+          model: modelName(payload.model), usage,
+        };
+      } catch (error) { error.providerUsage = usage; error.providerModel = modelName(payload?.model); throw error; }
+    },
+  };
+}
+
+// --------------------------------------------------------------- prompts ----
+
+const FETCH_TOOL = {
+  name: 'web_fetch',
+  description: 'Read one public web page and get its text, headings and links. Use it for every page you rely on. Give a full URL.',
+  input_schema: { type: 'object', properties: { url: { type: 'string', description: 'The full address of the page, starting with https://' } }, required: ['url'] },
+};
+
+const VERDICT_TOOL = {
+  name: 'verdict',
+  description: 'Record whether the result passes this check.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      pass: { type: 'boolean', description: 'True only if every criterion is met.' },
+      issues: { type: 'array', items: { type: 'string' }, description: 'One short, concrete sentence per clear breach that must be fixed, naming where it is. Never list points that are acceptable. Empty when it passes.' },
+      note: { type: 'string', description: 'One sentence a non-technical person can read: what was checked and the result.' },
+    },
+    required: ['pass', 'issues', 'note'],
+  },
+};
+
+const HOUSE_RULES = `Rules for every agent in this factory:
+- Use only the inputs, the results of earlier steps and pages you actually read. Never invent facts, names, numbers, quotes, prices or URLs.
+- When something cannot be found or a page cannot be read, say so in the result in one plain sentence and carry on with what you have.
+- When a claim comes from a web page, put the page address next to it as a Markdown link.
+- Write for a busy person who is not technical: short sentences, plain words, specifics instead of generalities.
+- Output only this step's result, in Markdown. No preamble, no sign-off, no remarks about yourself, the other agents or the process.`;
+
+function clip(text, limit) {
+  const value = String(text ?? '');
+  return value.length > limit ? `${value.slice(0, limit)}\n[cut: ${value.length - limit} more characters]` : value;
+}
+
+function inputsBlock(factory, inputs) {
+  const lines = factory.inputs.map((input) => `### ${input.label}\n${inputs[input.key] || '(not given)'}`);
+  return lines.length ? `## What the person gave\n\n${lines.join('\n\n')}` : '## What the person gave\n\n(nothing: this factory takes no inputs)';
+}
+
+// Both writers and reviewers use exactly this scope. Dependencies control
+// ordering and invalidation; a context binding controls what text is shared.
+export function resolveContext(state, step, exclude = null) {
+  if (!step.context) {
+    const artifacts = ancestorsOf(state.factory, step.id).filter((id) => id !== exclude && state.artifacts[id] !== undefined).map((id) => ({ alias: id, id, title: state.factory.steps.find((item) => item.id === id).title, text: state.artifacts[id] }));
+    return { inputs: { ...state.inputs }, fields: state.factory.inputs, artifacts, explicit: false };
+  }
+  const inputs = {};
+  const fields = [];
+  for (const [alias, key] of Object.entries(step.context.inputs)) {
+    inputs[alias] = state.inputs[key] || '';
+    fields.push({ key: alias, label: alias });
+  }
+  const artifacts = Object.entries(step.context.artifacts).filter(([, id]) => id !== exclude).map(([alias, id]) => {
+    if (typeof state.artifacts[id] !== 'string' || state.steps[id]?.status !== 'done') throw new Error(`The bound artifact "${alias}" is unavailable or awaits revision.`);
+    return { alias, id, title: alias, text: state.artifacts[id] };
+  });
+  return { inputs, fields, artifacts, explicit: true };
+}
+
+function contextBlocks(context) {
+  return [inputsBlock({ inputs: context.fields }, context.inputs), context.artifacts.length ? `## Results from earlier steps\n\n${context.artifacts.map((item) => `### ${item.title} (${item.id})\n\n${item.text}`).join('\n\n')}` : ''];
+}
+
+function agentSystem(state, step, host) {
+  const { factory } = state;
+  const agent = factory.agents[step.agent];
+  const tools = [];
+  if (step.tools.includes('web_fetch')) tools.push('You can read public web pages with the web_fetch tool.');
+  if (step.tools.includes('web_search')) {
+    tools.push(host.provider.serverSearch
+      ? 'You can search the web with the web_search tool. Search first when you need to find pages, then read the best ones.'
+      : 'Web search is not available on this runner: work from the addresses in the inputs and the links on pages you read, and say so when that limits the result.');
+  }
+  return [
+    `You are "${step.agent}", one agent in the factory "${factory.title}". ${step.context ? 'Use only this step’s declared context.' : `The factory's promised outcome: ${factory.description}`}`,
+    agent?.body ? `## Your role\n\n${agent.body}` : '',
+    `Today is ${new Date(host.now()).toISOString().slice(0, 10)}.`,
+    step.kind === 'deliver'
+      ? factory.outputs ? 'This step writes one artifact in connected work. Complete this step’s task; do not rewrite other declared outputs.' : 'This step writes the final deliverable the person receives. It must be complete and stand on its own: they will not see the earlier steps.'
+      : 'You do exactly this step and hand the result to the agents that come after you.',
+    tools.join(' '),
+    HOUSE_RULES,
+    (step.criteria || (!factory.outputs && step.kind === 'deliver' ? factory.done : [])).length ? `Done when:\n${(step.criteria || factory.done).map((line) => `- ${line}`).join('\n')}` : '',
+  ].filter(Boolean).join('\n\n');
+}
+
+const FORMAT_GUIDE = `A factory is a small organisation of AI agents that turns what a person gives into a finished deliverable. You write it as files.
+
+=== factory.yaml ===
+name: lowercase-words-with-hyphens
+description: One or two sentences. What finished thing the person gets, and when to use it.
+
+=== flow.yaml ===
+flow: mindburn.flow/v1
+title: Short human title
+author: Community
+version: "1.0.0"
+license: MIT
+tags: [one, two]
+time: about 3 minutes
+inputs:
+  input_name:
+    type: url            # text, longtext or url
+    help: What to put here, with an example.
+  another_input:
+    type: text
+    optional: true
+    help: ...
+steps:
+  step_name:
+    title: Verb-first step title
+    agent: researcher
+    kind: work
+    tools: [web_search, web_fetch]
+    task: |
+      What to do, in plain language: what to look at, what to produce, in what
+      shape, and what to do when something is missing.
+  other_step:
+    title: ...
+    agent: analyst
+    kind: work
+    needs: [step_name]
+    task: |
+      ...
+  write_it:
+    title: ...
+    agent: writer
+    kind: deliver
+    needs: [other_step]
+    task: |
+      Exactly what the final deliverable contains, section by section.
+  check_it:
+    title: Check the final document
+    agent: reviewer
+    kind: check
+    needs: [write_it]
+    checks: write_it
+    task: |
+      Concrete criteria for the entire final document, compared with inputs and earlier evidence.
+done:
+  - A checkable statement about the deliverable.
+
+=== agents/researcher/agent.md ===
+---
+description: One line: what this agent is responsible for.
+agentType: CUSTOM
+---
+
+Who this agent is and how it works, in a short paragraph and a few standing rules. Role, not task: the task for each step is in flow.yaml.
+
+RULES:
+- Step kinds: work (an agent does a job), check (a strict reviewer that sends weak work back to be redone), approve (the line stops and the person agrees or says what to change; use only where a human decision really matters, at most once), deliver (writes the final deliverable; exactly one, followed by its final check).
+- \`needs\` lists the steps whose results this step uses. Steps that need the same earlier steps run in parallel: use this when two pieces of work do not depend on each other (for example researching two sources, or writing two different pieces from the same brief). A step that needs several steps waits for all of them.
+- \`checks\` names the work or deliver step a check reviews; \`shows\` names the one an approve step shows the person. A failed check or a requested change sends that step back to be redone, and everything after it runs again.
+- Every agent named in a step needs its own agents/<name>/agent.md. Use 2 to 5 agents with distinct roles (for example researcher, analyst, writer, reviewer). The same agent can do several steps. Approve steps need no agent.
+- agentType is REVIEW for an agent that only checks, CUSTOM otherwise.
+- Tools exist only for work and deliver steps and only these two: web_search (find pages), web_fetch (read a page). Leave \`tools\` out when a step needs none. There is no email, file, CRM, calendar or code tool: design the factory so its deliverable is a document the person can use or send themselves.
+- 3 to 8 steps. Each does one job. Put one check after the final deliverable. Add an earlier check only when it prevents costly downstream work.
+- 1 to 4 inputs. Ask only for what the steps truly need.
+- Every task must be specific to this outcome: name the sections, the counts, the columns. Never write generic filler such as "analyze thoroughly".
+- Tasks must forbid invented facts wherever facts matter and say what to do when information is missing.
+- Do not promise anything the agents cannot do with text, web search and web reading.
+- Output only the files, each starting with its "=== path ===" line. No code fences, no commentary.`;
+
+export function composePrompt(outcome, examples = []) {
+  const system = `You design factories.\n\n${FORMAT_GUIDE}`;
+  const user = `${examples.length ? `Here ${examples.length === 1 ? 'is a good factory' : 'are good factories'} to learn the level of specificity from:\n\n${examples.map((example) => `<example>\n${example}\n</example>`).join('\n\n')}\n\n` : ''}Design a factory for this outcome, in the person's own words:\n\n<outcome>\n${clip(outcome, 2000)}\n</outcome>`;
+  return { system, user };
+}
+
+export function filesToText(files, only) {
+  return Object.entries(normalizeFiles(files)).filter(([path]) => path !== 'agents/foreman/agent.md' && path !== 'README.md' && (!only || only(path))).map(([path, content]) => `=== ${path} ===\n${content.trim()}`).join('\n\n');
+}
+
+export function improvePrompt(files, request, context = '', focus = '') {
+  return {
+    system: `You revise factories.\n\n${FORMAT_GUIDE}\n\nYou are revising an existing factory. Keep everything that works, change only what the request needs, keep the same \`name\`, and raise the version in flow.yaml (1.0.0 becomes 1.1.0). Output only the files you change, each in full; a file you leave out stays exactly as it is. Never drop a tool, an input or a comment the request did not ask you to change, even a tool this format does not list. To remove an agent, output its file header followed by the single line (removed). After the files, add a line containing only %%% and then one or two plain sentences saying what you changed and why.`,
+    user: `<factory>\n${filesToText(files)}\n</factory>\n\n${focus ? `<selected>\nThe person has this part selected: ${focus}\n</selected>\n\n` : ''}${context ? `<what_happened_in_a_run>\n${clip(context, 6000)}\n</what_happened_in_a_run>\n\n` : ''}<request>\n${clip(request, 2000)}\n</request>`,
+  };
+}
+
+export function explainPrompt(files, question, focus = '') {
+  return {
+    system: 'You explain a factory (a small organisation of AI agents defined by factory.yaml, flow.yaml and one agent.md per agent) to its owner, who may not be technical. Answer the question in plain words, in at most six short sentences or a short list. Refer to steps and agents by their titles. Do not propose rewriting files unless asked.',
+    user: `<factory>\n${filesToText(files)}\n</factory>\n\n${focus ? `<selected>\n${focus}\n</selected>\n\n` : ''}<question>\n${clip(question, 2000)}\n</question>`,
+  };
+}
+
+// factory.yaml with a new description, changed as text: every other line,
+// comments and quoting included, stays as the author wrote it, and so does
+// the key, quoted or not. Null when the result would not read back as the
+// same fields with that description.
+function withDescription(source, description) {
+  // Every file leaves cleanComposed with LF line ends (normalizeFiles).
+  const text = source.replace(/\r\n/g, '\n');
+  const lines = text.split('\n');
+  // Measured as parseYaml reads indentation: a tab counts as two spaces.
+  const indentOf = (line) => line.replace(/\t/g, '  ').match(/^ */)[0].length;
+  const first = lines.find((line) => stripComment(line).trim() && line.trim() !== '---');
+  const root = first === undefined ? 0 : indentOf(first);
+  const written = toYaml({ description: `${description}\n` }, root).replace(/\n$/, '').split('\n');
+  // The key as parseYaml matches one: description, "description" or 'description'.
+  const keyOf = (line) => (indentOf(line) === root && /^ *[^ \t]/.test(line) ? line.slice(root).match(/^("[^"]*"|'[^']*'|[^:#]+?):( |$)(.*)$/) : null);
+  const at = lines.findIndex((line) => { const match = keyOf(line); return Boolean(match) && scalar(match[1]) === 'description'; });
+  let out;
+  if (at < 0) out = `${text.replace(/\n*$/, '\n')}${written.join('\n')}\n`;
+  else {
+    const key = keyOf(lines[at]);
+    const value = stripComment(key[3]).trim();
+    let end = at + 1;
+    if (/^[|>][+-]?$/.test(value)) {
+      while (end < lines.length && (!lines[end].trim() || indentOf(lines[end]) > root)) end += 1;
+      while (end > at + 1 && !lines[end - 1].trim()) end -= 1;
+    } else {
+      // A value written under its key: a list or a mapping.
+      while (end < lines.length && indentOf(lines[end]) > root && stripComment(lines[end]).trim()) end += 1;
+    }
+    written[0] = `${lines[at].slice(0, root)}${key[1]}:${written[0].slice(root + 'description:'.length)}`;
+    // A comment after the old value stays on the line.
+    written[0] += lines[at].slice(stripComment(lines[at]).trimEnd().length);
+    out = [...lines.slice(0, at), ...written, ...lines.slice(end)].join('\n');
+  }
+  return readsAs(out, { ...parseYaml(text), description: `${description}\n` }) ? out : null;
+}
+
+const readsAs = (text, fields) => { try { return canonical(parseYaml(text)) === canonical(fields); } catch { return false; } };
+
+// Turns a model's "=== path ===" answer into bundle files. A new factory gets
+// the fixed parts of factory.yaml filled in. A revision (`base` given) is a
+// patch: a file the model did not return stays exactly as it was, factory.yaml
+// keeps every field and line but the description, and only an agent file can
+// be removed, by returning it with the single line "(removed)". A tool the
+// base asks for and the Hub lacks is its author's requirement: a patch that
+// takes one out says so in its summary, and lists it in `dropped`.
+export function cleanComposed(text, base = null) {
+  const [body, summary = ''] = String(text || '').split(/\n%%%\s*\n?/);
+  const files = {};
+  let current = null;
+  for (const line of body.replace(/\r\n/g, '\n').split('\n')) {
+    const header = line.match(/^=== *([A-Za-z0-9_./-]+) *===\s*$/);
+    if (header) { current = header[1]; files[current] = []; continue; }
+    if (current) files[current].push(line);
+  }
+  const out = {};
+  const removed = [];
+  for (const [path, lines] of Object.entries(files)) {
+    const content = lines.join('\n').replace(/^```[a-z]*\n/i, '').replace(/\n```\s*$/, '').trim();
+    if (!ALLOWED_PATH.test(path) || !content) continue;
+    if (base && content === '(removed)') { if (AGENT_PATH.test(path) && path !== 'agents/foreman/agent.md') removed.push(path); continue; }
+    // A file returned as it was is not a change, whatever the model did to its last line break.
+    out[path] = base && base[path] !== undefined && base[path].trim() === content ? base[path] : `${content}\n`;
+  }
+  const notes = [];
+  if (out['factory.yaml']) {
+    let config = {};
+    try { config = parseYaml(out['factory.yaml']) || {}; } catch { /* reported by parseBundle */ }
+    if (base && base['factory.yaml'] !== undefined) {
+      const before = base['factory.yaml'];
+      let kept = null;
+      try { kept = parseYaml(before); } catch { /* reported by parseBundle */ }
+      const mapping = Boolean(kept) && typeof kept === 'object' && !Array.isArray(kept);
+      const description = String(config.description || '').trim();
+      // The author's factory.yaml is theirs: repositories, harness, comments
+      // and any field this runner does not read stay. Only the description can
+      // change: in place, or else by writing the file again from its fields.
+      // The summary says what did not come through, so it never claims a
+      // change the files do not have.
+      out['factory.yaml'] = before;
+      if (description && (!mapping || String(kept.description || '').trim() !== description)) {
+        const fields = mapping ? { ...kept, description: `${description}\n` } : null;
+        const inPlace = fields && withDescription(before, description);
+        const rewritten = fields && !inPlace ? toYaml(fields) : null;
+        if (inPlace) out['factory.yaml'] = inPlace;
+        else if (rewritten && readsAs(rewritten, fields)) {
+          out['factory.yaml'] = rewritten;
+          if (countComments(before)) notes.push('factory.yaml was written again to change its description, so its comments were not kept.');
+        } else notes.push('The description in factory.yaml could not be changed, so it stays as it was.');
+      }
+      // A field the answer gives another value is a change that does not come through.
+      const asked = config && typeof config === 'object' && !Array.isArray(config) ? Object.keys(config).filter((key) => key !== 'description') : [];
+      if (mapping && asked.some((key) => canonical(config[key]) !== canonical(kept[key]))) notes.push('Only the description of factory.yaml changes in a revision: its other fields stay as they were.');
+    } else {
+      out['factory.yaml'] = toYaml({ schemaVersion: 'v1alpha1', name: slugify(config.name), description: String(config.description || '').trim(), repositories: [], agentDefaults: config.agentDefaults || { harness: { type: 'claude', model: 'sonnet' } } });
+    }
+  }
+  const merged = base ? { ...normalizeFiles(base), ...out } : out;
+  for (const path of removed) delete merged[path];
+  const dropped = [];
+  if (base) {
+    const before = parseBundle(base).factory;
+    const after = parseBundle(merged).factory;
+    const kept = new Set(after.steps.flatMap((step) => step.missing || []));
+    for (const step of before.steps) {
+      const gone = (step.missing || []).filter((tool) => !kept.has(tool));
+      if (!gone.length) continue;
+      dropped.push(...gone);
+      notes.push(`This change also removes ${gone.join(' and ')} from the step "${step.title}". The Hub does not have ${gone.length === 1 ? 'that tool' : 'those tools'}, so the step will run without ${gone.length === 1 ? 'it' : 'them'}.`);
+    }
+    for (const requirement of before.unsupportedRequirements) {
+      if (after.unsupportedRequirements.some(item => item.source === requirement.source && item.setting === requirement.setting)) continue;
+      const name = `${requirement.setting} (${requirement.source})`;
+      dropped.push(name);
+      notes.push(`This change also removes the requirement ${name}. Review the changed behavior before running.`);
+    }
+  }
+  return { files: withForeman(merged), summary: [summary.trim(), ...notes].filter(Boolean).join(' '), removed, dropped };
+}
+
+// The Hub writes agents/foreman/agent.md from the flow and marks it with these
+// two lines. A foreman without them was written by the author.
+export function isGeneratedForeman(text) {
+  const value = String(text || '');
+  return /^description: Coordinates the .* factory from its flow\.$/m.test(value) && value.includes('The exact, executable version of these steps is flow.yaml.');
+}
+
+// Rewrites the Hub's own foreman from the flow. An author's foreman is never
+// replaced: it stays byte for byte, and parseBundle says it may not match the flow.
+export function withForeman(files) {
+  if (files['agents/foreman/agent.md'] !== undefined && !isGeneratedForeman(files['agents/foreman/agent.md'])) return normalizeFiles(files);
+  const out = { ...files };
+  delete out['agents/foreman/agent.md'];
+  const parsed = parseBundle(out);
+  if (parsed.factory.steps.length && !parsed.errors.length) out['agents/foreman/agent.md'] = foremanText(parsed.factory);
+  else if (files['agents/foreman/agent.md']) out['agents/foreman/agent.md'] = files['agents/foreman/agent.md'];
+  return normalizeFiles(out);
+}
+
+// ------------------------------------------------------------------ run ----
+
+export const DEFAULT_LIMITS = { llmCalls: 60, fetches: 20, searchesPerStep: 4, turnsPerStep: 8, parallel: 4, contextChars: 160000 };
+
+export function newRun({ id, factory, inputs, runner }) {
+  return {
+    v: 2,
+    executionVersion: 1,
+    id,
+    factory,
+    inputs: inputs || {},
+    runner: runner || { mode: 'local' },
+    status: 'running',
+    steps: Object.fromEntries(factory.steps.map((step) => [step.id, { status: 'pending', attempts: 0, fails: 0, feedback: null }])),
+    artifacts: {},
+    approval: null,
+    records: [],
+    usage: { input: 0, output: 0, llmCalls: 0, fetches: 0, searches: 0 },
+    started: null,
+    finished: null,
+    deliverable: null,
+    error: null,
+  };
+}
+
+// JSON Schema covers the shape; the annotations retain normalization and
+// UTF-16/combined limits enforced by checkInputs, which remains authoritative.
+export function inputSchema(factory) {
+  return {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    title: `${factory.title} inputs`,
+    type: 'object',
+    additionalProperties: false,
+    properties: Object.fromEntries(factory.inputs.map((input) => [input.key, {
+      type: 'string', title: input.label,
+      ...(input.help ? { description: input.help } : {}),
+      maxLength: INPUT_LIMITS[input.type],
+      ...(input.required ? { pattern: '\\S' } : {}),
+      'x-factory-input-type': input.type,
+      ...(input.visibility ? { 'x-factory-visibility': input.visibility } : {}),
+      ...(input.type === 'url' ? { 'x-factory-normalize': 'An HTTP(S) address; bare domains are accepted. Validated by checkInputs. Public-address restrictions apply when fetching.' } : {}),
+    }])),
+    required: factory.inputs.filter((input) => input.required).map((input) => input.key),
+    'x-factory-validation': { function: 'checkInputs', lengthUnit: 'UTF-16 code units', maxTotalLength: INPUT_LIMITS.total },
+  };
+}
+
+export function checkInputs(factory, inputs) {
+  const problems = [];
+  const clean = {};
+  if (!inputs || typeof inputs !== 'object' || Array.isArray(inputs)) return { ok: false, problems: ['Inputs must be named text fields.'], inputs: clean };
+  const keys = new Set(factory.inputs.map((input) => input.key));
+  for (const key of Object.keys(inputs)) if (!keys.has(key)) problems.push(`Unknown input "${key}".`);
+  let total = 0;
+  for (const input of factory.inputs) {
+    const value = Object.hasOwn(inputs, input.key) ? inputs[input.key] : '';
+    if (typeof value !== 'string') { problems.push(`"${input.label}" must be text.`); continue; }
+    total += value.length;
+    if (value.length > INPUT_LIMITS[input.type]) { problems.push(`"${input.label}" is limited to ${INPUT_LIMITS[input.type].toLocaleString('en-US')} characters. Shorten it; nothing has been cut.`); continue; }
+    if (!value.trim()) {
+      if (input.required) problems.push(`"${input.label}" is needed.`);
+      continue;
+    }
+    if (input.type === 'url') {
+      const url = normalizeUrl(value);
+      if (!url) { problems.push(`"${input.label}" should be a website address, like example.com.`); continue; }
+      clean[input.key] = url;
+    } else {
+      clean[input.key] = value;
+    }
+  }
+  if (total > INPUT_LIMITS.total) problems.push(`Inputs together are limited to ${INPUT_LIMITS.total.toLocaleString('en-US')} characters. Shorten them; nothing has been cut.`);
+  return { ok: problems.length === 0, problems, inputs: clean };
+}
+
+function finalText(content) {
+  let lastTool = -1;
+  content.forEach((block, index) => { if (block.type !== 'text') lastTool = index; });
+  return content.slice(lastTool + 1).filter((block) => block.type === 'text').map((block) => block.text).join('').trim()
+    || content.filter((block) => block.type === 'text').map((block) => block.text).join('\n').trim();
+}
+
+async function callModel(state, host, request, provider = host.provider) {
+  if (request.system.length + JSON.stringify(request.messages).length > (host.limits.contextChars ?? DEFAULT_LIMITS.contextChars)) throw failure('context_limit', 'The full inputs and evidence exceed this runner’s context limit. Shorten the inputs or split the factory; no text was cut.');
+  if (state.usage.llmCalls >= host.limits.llmCalls) throw failure('call_limit', 'This run reached its step budget before finishing.');
+  // A resumed older run retains its unrecorded calls instead of pretending
+  // that a new per-call ledger describes the whole run.
+  state.usage.metering ||= { version: 1, unrecorded: state.usage.llmCalls, calls: [] };
+  const entry = { provider: ['anthropic', 'openai-compatible'].includes(provider.name) ? provider.name : 'other',
+    billing: provider.billing === 'anthropic-direct' ? provider.billing : null, requestedModel: modelName(provider.model), model: null, measured: false, input: null, output: null };
+  state.usage.metering.calls.push(entry);
+  state.usage.llmCalls += 1;
+  const record = (usage, model) => {
+    entry.model = modelName(model);
+    if (usage && [usage.input, usage.output].every(tokenCount)) {
+      state.usage.input += usage.input; state.usage.output += usage.output;
+      entry.input = usage.input; entry.output = usage.output; entry.measured = usage.measured !== false;
+    }
+    for (const key of ['uncachedInput', 'cacheReadInput', 'cacheWriteInput', 'cacheWrite5mInput', 'cacheWrite1hInput', 'searchRequests']) entry[key] = tokenCount(usage?.[key]) ? usage[key] : null;
+    entry.serviceTier = usageCategory(usage?.serviceTier, ['standard', 'priority', 'batch']);
+    entry.speed = usageCategory(usage?.speed, ['standard', 'fast']);
+    entry.inferenceGeo = usageCategory(usage?.inferenceGeo, ['global', 'us']);
+  };
+  let response;
+  try { response = await provider.call(request); }
+  catch (error) { record(error?.providerUsage, error?.providerModel); throw error; }
+  // Rejected and malformed answers still cost tokens. Count the reported
+  // usage before validating their contents; absent usage stays unknown.
+  record(response?.usage, response?.model);
+  if (!response || !Array.isArray(response.content) || !Array.isArray(response.toolCalls) || !Array.isArray(response.searches)) throw failure('provider_response', 'The model returned an invalid response.');
+  if (!['end_turn', 'stop', 'stop_sequence', 'tool_use', 'tool_calls', 'pause_turn'].includes(response.stop)) throw failure(['length', 'max_tokens'].includes(response.stop) ? 'output_limit' : 'provider_response', `The model did not finish its response (${response.stop || 'missing completion reason'}). No completed result was accepted.`);
+  if (response.content.some((block) => !block || typeof block.type !== 'string' || (block.type === 'text' && typeof block.text !== 'string'))) throw failure('provider_response', 'The model returned invalid content.');
+  if (response.toolCalls.some((call) => !call || typeof call.id !== 'string' || !call.id || typeof call.name !== 'string' || !call.input || typeof call.input !== 'object' || Array.isArray(call.input))) throw failure('provider_response', 'The model returned invalid tool arguments.');
+  if (new Set(response.toolCalls.map((call) => call.id)).size !== response.toolCalls.length) throw failure('provider_response', 'The model repeated a tool call identifier.');
+  if (response.toolCalls.some((call) => !(request.tools || []).some((tool) => tool.name === call.name))) throw failure('provider_response', 'The model requested a tool that this step did not offer.');
+  if (response.toolCalls.some((call) => call.name === 'web_fetch' && (typeof call.input.url !== 'string' || !call.input.url.trim()))) throw failure('provider_response', 'The model returned a page request without a text URL.');
+  if (response.searches.length > (request.search || 0)) throw failure('provider_response', 'The model searched beyond the tools or search budget offered by this step.');
+  if (['tool_use', 'tool_calls'].includes(response.stop) && !response.toolCalls.length) throw failure('provider_response', 'The model stopped for a tool without a valid tool call.');
+  if (response.toolCalls.length && !['tool_use', 'tool_calls'].includes(response.stop)) throw failure('provider_response', 'The model returned tools with an inconsistent completion reason.');
+  if (response.stop === 'pause_turn' && !provider.serverSearch) throw failure('provider_response', 'This model returned an unsupported paused response.');
+  if (!response.usage || ![response.usage.input, response.usage.output].every(tokenCount)) throw failure('provider_response', 'The model returned invalid usage accounting.');
+  return response;
+}
+
+async function doWork(state, step, host, record) {
+  const feedback = state.steps[step.id].feedback;
+  const context = resolveContext(state, step);
+  if (context.explicit) for (const artifact of context.artifacts) {
+    const evidence = latestRecords(state).filter((item) => item.id === artifact.id || item.review?.target === artifact.id);
+    if (evidence.some((item) => item.limitations?.length || (item.review && (item.status !== 'passed' || !item.review.complete)))) record.limitations.push(`Bound evidence "${artifact.alias}" has unresolved review or evidence limitations.`);
+  }
+  const parts = [...contextBlocks(context), `## Your step: ${step.title}\n\n${step.task}`];
+  if (feedback) {
+    parts.push(`## Your earlier result was sent back\n\n${feedback.from === 'person' ? 'The person asked for this change' : 'The reviewer found these problems'}:\n\n${feedback.text}\n\nYour earlier result:\n\n${feedback.previous}\n\nWrite the full corrected result.`);
+  }
+  const messages = [{ role: 'user', content: [{ type: 'text', text: parts.filter(Boolean).join('\n\n') }] }];
+  const tools = step.tools.includes('web_fetch') ? [FETCH_TOOL] : [];
+  const search = step.tools.includes('web_search') && host.provider.serverSearch ? host.limits.searchesPerStep : 0;
+  if (step.tools.includes('web_search') && !host.provider.serverSearch) record.limitations.push('Web search was unavailable on this runner.');
+  const system = agentSystem(state, step, host);
+  const maxTokens = step.kind === 'deliver' ? 8000 : 5000;
+
+  let searched = 0;
+  for (let turn = 0; turn < host.limits.turnsPerStep; turn += 1) {
+    const last = turn === host.limits.turnsPerStep - 1;
+    const response = await callModel(state, host, last ? { system, messages: [...messages, { role: 'user', content: [{ type: 'text', text: 'Write the step result now with what you have.' }] }], maxTokens } : { system, messages, tools, search: Math.max(0, search - searched), maxTokens });
+    for (const query of response.searches) {
+      searched += 1;
+      state.usage.searches += 1;
+      record.tools.push({ tool: 'web_search', target: query });
+      await host.emit({ type: 'tool', step: step.id, tool: 'web_search', target: query });
+    }
+    if (last && (response.stop === 'pause_turn' || response.toolCalls.length)) throw new Error('The model did not finish within this step’s turn limit.');
+    if (response.stop !== 'pause_turn' && !response.toolCalls.length) return finalText(response.content);
+    messages.push({ role: 'assistant', content: response.content });
+    if (response.stop === 'pause_turn') continue;
+    const results = [];
+    for (const call of response.toolCalls) {
+      let output;
+      if (call.name !== 'web_fetch') {
+        output = 'That tool does not exist in this factory.';
+      } else if (state.usage.fetches >= host.limits.fetches) {
+        output = 'The page budget for this run is used up. Work with what you have.';
+        record.limitations.push(output);
+      } else {
+        const url = normalizeUrl(call.input?.url);
+        state.usage.fetches += 1;
+        await host.emit({ type: 'tool', step: step.id, tool: 'web_fetch', target: url || String(call.input?.url || '') });
+        if (!url) {
+          output = 'That is not a public web address.';
+          record.limitations.push('A requested page address was invalid.');
+        } else {
+          try {
+            output = await host.fetchPage(url);
+            if (/\[Page cut here:/.test(output)) record.limitations.push(`Only part of ${url} was available to read.`);
+            record.tools.push({ tool: 'web_fetch', target: url, ok: true });
+          } catch (error) {
+            output = `The page could not be read: ${error.message}`;
+            record.limitations.push(`The page ${url} could not be read.`);
+            record.tools.push({ tool: 'web_fetch', target: url, ok: false });
+          }
+        }
+      }
+      results.push({ type: 'tool_result', tool_use_id: call.id, content: output });
+    }
+    messages.push({ role: 'user', content: results });
+  }
+  return '';
+}
+
+const latestRecords = (state) => [...new Map(state.records.map((record) => [record.id, record])).values()];
+
+async function doCheck(state, step, host, record) {
+  const subject = state.factory.steps.find((item) => item.id === step.target);
+  const agent = state.factory.agents[step.agent];
+  const subjectText = state.artifacts[subject.id];
+  if (typeof subjectText !== 'string' || !subjectText) throw new Error('The review has no subject text to check.');
+  const context = resolveContext(state, step, subject.id);
+  const earlier = [...new Set(context.artifacts.map((item) => item.id))];
+  const ancestorIds = new Set(context.explicit ? [subject.id, ...earlier] : ancestorsOf(state.factory, step.id));
+  const limitations = [...new Set(latestRecords(state).filter((item) => ancestorIds.has(item.id)).flatMap((item) => item.limitations || []))];
+  for (const item of state.factory.steps.filter((item) => ancestorIds.has(item.id) && ['work', 'deliver'].includes(item.kind))) {
+    if (typeof state.artifacts[item.id] !== 'string') limitations.push(`Evidence from "${item.title}" is unavailable.`);
+  }
+  if (!state.executionVersion) limitations.push('Earlier work used a runner that did not record complete evidence coverage.');
+  const reviewer = host.checkProvider || host.provider;
+  record.review = { target: subject.id, checked_sha256: await sha256(subjectText), provider: reviewer.name || null, model: reviewer.model || null,
+    inputs_sha256: await sha256(canonical(context.inputs)), evidence: await Promise.all(earlier.map(async (id) => ({ id, sha256: await sha256(state.artifacts[id]) }))), complete: limitations.length === 0, limitations };
+  const system = [
+    `You are "${step.agent}", the reviewer for the step "${step.title}" in the factory "${state.factory.title}". ${step.context ? 'Use only the declared review context.' : `The factory's promised outcome: ${state.factory.description}`}`,
+    agent?.body ? `## Your role\n\n${agent.body}` : '',
+    `${(state.factory.outputs ? state.factory.outputs.some((output) => output.step === subject.id) : subject.id === finalStep(state.factory)?.id) ? 'This is an exact final output the person will receive.' : 'This is an intermediate result: later steps add the rest.'} Judge the result strictly against its task and the criteria you are given, comparing it with the original inputs and earlier evidence. You cannot browse; earlier results are supplied evidence, not independent verification of the web. Respect disclosed missing evidence: require honest limitations rather than invented facts. Pass work that meets every criterion even if you would have written it differently. Fail it only for a clear, specific breach you can point to. Then call the verdict tool.`,
+  ].filter(Boolean).join('\n\n');
+  const text = [
+    ...contextBlocks(context),
+    limitations.length ? `## Evidence limitations\n\n${limitations.map((item) => `- ${item}`).join('\n')}` : '',
+    `## What the subject step was asked to do\n\n${subject.task}`,
+    `## The result to check (from the step "${subject.title}")\n\n${subjectText}`,
+    `## Criteria\n\n${step.task || 'The result does what its step was asked to do, with no invented facts.'}`,
+    // Only the final deliverable answers for the factory-wide promises.
+    (subject.criteria || (!state.factory.outputs && subject.id === finalStep(state.factory)?.id ? state.factory.done : [])).length ? `## Done when\n\n${(subject.criteria || state.factory.done).map((line) => `- ${line}`).join('\n')}` : '',
+  ].filter(Boolean).join('\n\n');
+  const read = (response) => {
+    if (response.stop === 'pause_turn') throw new Error('The reviewer did not finish its response.');
+    if (response.toolCalls.length > 1) return null;
+    let parsed = response.toolCalls[0]?.input;
+    try {
+      if (!parsed) parsed = JSON.parse(finalText(response.content));
+      if (!parsed || typeof parsed.pass !== 'boolean' || !Array.isArray(parsed.issues) || parsed.issues.length > 8 || parsed.issues.some((issue) => typeof issue !== 'string' || !issue.trim()) || typeof parsed.note !== 'string' || !parsed.note.trim() || (parsed.pass && parsed.issues.length)) return null;
+      return { pass: parsed.pass, issues: parsed.issues, note: parsed.note };
+    } catch { return null; }
+  };
+  const messages = [{ role: 'user', content: [{ type: 'text', text }] }];
+  const request = { system, messages, tools: [VERDICT_TOOL], forceTool: 'verdict', maxTokens: 1500 };
+  record.review.context_sha256 = await sha256(canonical(request));
+  const first = await callModel(state, host, request, reviewer);
+  let verdict = read(first);
+  if (!verdict) {
+    // A reviewer that wrote prose instead of a verdict is asked once more.
+    const retryRequest = { system, messages: [...messages, { role: 'assistant', content: [{ type: 'text', text: finalText(first.content) || 'I have reviewed the result.' }] }, { role: 'user', content: [{ type: 'text', text: 'Now give your verdict as JSON only, with no other text: {"pass": true or false, "issues": ["one sentence per clear breach"], "note": "one sentence"}' }] }], maxTokens: 1000 };
+    record.review.context_sha256 = await sha256(canonical(retryRequest));
+    const again = await callModel(state, host, retryRequest, reviewer);
+    verdict = read(again);
+  }
+  return verdict || { pass: null, issues: [], note: 'The reviewer did not return a valid verdict; this result is unreviewed.', unreviewed: true };
+}
+
+// Sends a step back to be redone: it and everything built on it run again.
+function sendBack(state, target, feedback) {
+  for (const id of [target, ...dependentsOf(state.factory, target)]) {
+    if (state.steps[id].status !== 'pending') state.steps[id].status = 'pending';
+  }
+  // Two reviewers can send the same work back in one round: keep both sets of reasons.
+  const pending = state.steps[target].feedback;
+  state.steps[target].feedback = pending && pending.previous === state.artifacts[target]
+    ? { ...pending, text: `${pending.text}\n${feedback.text}`, from: pending.from === 'person' || feedback.from === 'person' ? 'person' : 'check' }
+    : { ...feedback, previous: state.artifacts[target] };
+}
+
+async function runStep(state, step, host) {
+  const slot = state.steps[step.id];
+  slot.status = 'running';
+  slot.attempts += 1;
+  const record = { id: step.id, title: step.title, agent: step.agent, kind: step.kind, attempt: slot.attempts, started: host.now(), tools: [], limitations: [] };
+  const outcome = { step, record, sendBack: null, error: null };
+  try {
+    if (step.kind === 'check') {
+      await host.emit({ type: 'step_started', step: step.id, kind: 'check', title: step.title, agent: step.agent, attempt: slot.attempts });
+      const verdict = await doCheck(state, step, host, record);
+      record.verdict = verdict;
+      if (verdict.unreviewed) record.status = 'unreviewed';
+      else if (verdict.pass) record.status = 'passed';
+      else if (slot.fails < step.rounds) {
+        slot.fails += 1;
+        record.status = 'sent_back';
+        outcome.sendBack = { target: step.target, from: 'check', text: verdict.issues.map((issue) => `- ${issue}`).join('\n') || verdict.note };
+      } else record.status = 'flagged';
+      await host.emit({ type: 'check', step: step.id, target: step.target, pass: verdict.pass, status: record.status, issues: verdict.issues, note: verdict.note });
+    } else {
+      await host.emit({ type: 'step_started', step: step.id, kind: step.kind, title: step.title, agent: step.agent, attempt: slot.attempts, redo: Boolean(slot.feedback) });
+      const output = await doWork(state, step, host, record);
+      if (!output) throw new Error(`The step "${step.title}" produced nothing.`);
+      state.artifacts[step.id] = output;
+      slot.feedback = null;
+      record.status = 'done';
+      record.output_sha256 = await sha256(output);
+      await host.emit({ type: 'step_done', step: step.id, kind: step.kind, chars: output.length });
+    }
+  } catch (error) {
+    record.status = 'failed';
+    outcome.error = String(error.message || error);
+    outcome.failure = failureDetails(error);
+  }
+  record.finished = host.now();
+  return outcome;
+}
+
+// Moves the factory forward by one round: every step that is ready runs, in
+// parallel. `host` supplies: provider, fetchPage(url), emit(event), now(), limits.
+export async function advance(state, host) {
+  if (state.status !== 'running') return state;
+  // Re-read preserved source even for restored runs parsed by an older engine.
+  // UI admission and a cached runnable flag are not execution boundaries.
+  const source = parseBundle(state.factory.files);
+  if (!source.ok) return fail(state, host, null, source.errors.join(' '), { code: 'invalid_factory' });
+  if (!state.started) {
+    state.started = host.now();
+    await host.emit({ type: 'run_started', factory: state.factory.name, steps: state.factory.steps.length });
+    const checked = checkInputs(state.factory, state.inputs);
+    if (!checked.ok) return fail(state, host, null, checked.problems.join(' '), { code: 'inputs' });
+    state.inputs = checked.inputs;
+    // Checked again here, whoever started the run: a factory that asks for a
+    // tool this runner lacks is not run at all, since without it the run
+    // would be a different factory from the one its author wrote.
+    const lacking = state.factory.steps.find((step) => step.missing?.length);
+    if (lacking) return fail(state, host, lacking.id, `The step "${lacking.title}" needs ${lacking.missing.join(' and ')}, which this runner does not have. Nothing was run.`, { code: 'tools' });
+  }
+  if (source.factory.unsupportedRequirements.length) return fail(state, host, null, source.factory.blockers.join(' '), { code: 'requirements' });
+  const { steps } = state.factory;
+  const ready = steps.filter((step) => state.steps[step.id].status === 'pending' && step.needs.every((need) => state.steps[need].status === 'done'));
+  if (!ready.length) {
+    if (steps.every((step) => state.steps[step.id].status === 'done')) return finish(state, host);
+    return fail(state, host, null, 'The flow cannot continue: a step is waiting on work that will never finish.', { code: 'flow' });
+  }
+
+  const working = ready.filter((step) => step.kind !== 'approve').slice(0, host.limits.parallel || 4);
+  if (working.length) {
+    const outcomes = await Promise.all(working.map((step) => runStep(state, step, host)));
+    for (const outcome of outcomes) state.records.push(outcome.record);
+    const failed = outcomes.find((outcome) => outcome.error);
+    if (failed) return fail(state, host, failed.step.id, failed.error, failed.failure);
+    for (const outcome of outcomes) if (!outcome.sendBack) state.steps[outcome.step.id].status = 'done';
+    for (const outcome of outcomes) if (outcome.sendBack) { state.steps[outcome.step.id].status = 'pending'; sendBack(state, outcome.sendBack.target, outcome.sendBack); }
+    return state;
+  }
+
+  const step = ready[0];
+  const slot = state.steps[step.id];
+  const decision = state.approval && state.approval.step === step.id ? state.approval.decision : null;
+  if (!decision) {
+    state.status = 'waiting';
+    state.approval = { step: step.id, title: step.title, ask: step.task, artifact: step.target, artifact_sha256: await sha256(state.artifacts[step.target] || ''), decision: null, revisionsLeft: Math.max(0, step.rounds - slot.fails) };
+    await ensureApprovalIdentity(state);
+    await host.emit({ type: 'approval_needed', step: step.id, title: step.title, artifact: step.target });
+    return state;
+  }
+  slot.attempts += 1;
+  const record = { id: step.id, title: step.title, agent: 'owner', kind: 'approve', attempt: slot.attempts, started: host.now(), finished: host.now(), tools: [], decision: decision.action };
+  // What the person had in front of them when they decided.
+  if (decision.seen) record.seen_sha256 = decision.seen;
+  if (decision.approvalId) record.approval_id = decision.approvalId;
+  state.approval = null;
+  if (decision.action === 'reject') {
+    record.status = 'rejected';
+    record.note = String(decision.note || '').slice(0, 4000);
+    state.records.push(record);
+    state.status = 'stopped';
+    state.stopped = { step: step.id, title: step.title, note: record.note };
+    state.finished = host.now();
+    await host.emit({ type: 'approval', step: step.id, status: record.status });
+    await host.emit({ type: 'run_stopped', step: step.id, title: step.title });
+    return state;
+  }
+  if (decision.action === 'revise') {
+    slot.fails += 1;
+    record.status = 'revision_asked';
+    sendBack(state, step.target, { from: 'person', text: String(decision.note || '').slice(0, 4000) });
+  } else {
+    record.status = 'approved';
+    record.output_sha256 = await sha256(state.artifacts[step.target]);
+    slot.status = 'done';
+  }
+  state.records.push(record);
+  await host.emit({ type: 'approval', step: step.id, status: record.status });
+  return state;
+}
+
+export const DECISIONS = ['approve', 'revise', 'reject'];
+
+// Stable across reads/restarts, different for each review occurrence even if
+// a revision returns identical text. Restored pending runs need no storage
+// migration: their persisted step attempt identifies the same occurrence.
+export async function ensureApprovalIdentity(state) {
+  if (state.status === 'waiting' && state.approval && !state.approval.id) {
+    state.approval.id = await sha256(canonical([state.id, state.approval.step, (state.steps[state.approval.step]?.attempts || 0) + 1]));
+  }
+}
+
+// Why a decision cannot be taken, or '' when it can. A decision is one of
+// approve, revise or reject and nothing else: an empty or misspelt answer is
+// never read as approval. It names the hash of the text the person was shown
+// (`seen`) and the review occurrence (`approvalId`), so a delayed decision
+// cannot approve a later review of identical text.
+export function decisionProblem(state, decision) {
+  if (state.status !== 'waiting' || !state.approval) return 'not_waiting';
+  if (!decision || !DECISIONS.includes(decision.action)) return 'bad_action';
+  if (state.approval.artifact_sha256) {
+    if (!decision.seen) return 'unseen';
+    if (decision.seen !== state.approval.artifact_sha256) return 'stale';
+  }
+  if (state.approval.id && decision.approvalId !== state.approval.id) return 'stale';
+  if (decision.action === 'revise' && state.approval.revisionsLeft === 0) return 'no_revisions';
+  return '';
+}
+
+// Records the person's decision and lets the run continue. Returns false, and
+// leaves the run waiting, when decisionProblem names a reason.
+export function resume(state, decision) {
+  if (decisionProblem(state, decision)) return false;
+  state.approval.decision = { action: decision.action, note: decision.note || '', seen: decision.seen || null, approvalId: decision.approvalId || null };
+  state.status = 'running';
+  return true;
+}
+
+async function fail(state, host, step, message, detail = { code: 'execution_failed' }) {
+  state.status = 'failed';
+  state.error = message;
+  state.failure = { ...detail, step };
+  state.finished = host.now();
+  await host.emit({ type: 'run_failed', step, error: message });
+  return state;
+}
+
+async function finish(state, host) {
+  const last = finalStep(state.factory);
+  state.deliverable = state.factory.outputs ? state.factory.outputs.map((output) => `# ${output.title}\n\n${state.artifacts[output.step]}`).join('\n\n---\n\n') : last ? state.artifacts[last.id] || '' : '';
+  state.status = 'done';
+  state.finished = host.now();
+  state.receipt = await buildReceipt(state);
+  await host.emit({ type: 'run_done', chars: state.deliverable.length });
+  return state;
+}
+
+export async function buildReceipt(state) {
+  const deliveredHash = await sha256(state.deliverable);
+  const current = latestRecords(state);
+  const checks = current.filter((record) => record.kind === 'check' && record.review?.target === finalStep(state.factory)?.id && record.review.checked_sha256 === deliveredHash);
+  let reviewStatus = !checks.length ? 'not_checked' : checks.some((record) => record.status === 'flagged') ? 'flagged' : checks.some((record) => record.status !== 'passed') ? 'unreviewed' : checks.some((record) => !record.review.complete) ? 'limited' : 'passed';
+  const outputs = state.factory.outputs ? await Promise.all(state.factory.outputs.map(async (output) => {
+    const hash = await sha256(state.artifacts[output.step]);
+    const reviews = current.filter((record) => record.kind === 'check' && record.review?.target === output.step && record.review.checked_sha256 === hash);
+    const status = !reviews.length ? 'not_checked' : reviews.some((record) => record.status === 'flagged') ? 'flagged' : reviews.some((record) => record.status !== 'passed') ? 'unreviewed' : reviews.some((record) => !record.review.complete) ? 'limited' : 'passed';
+    return { ...output, sha256: hash, review: { status, checks: reviews.map((record) => ({ id: record.id, attempt: record.attempt })) } };
+  })) : null;
+  if (outputs) reviewStatus = ['flagged', 'unreviewed', 'not_checked', 'limited', 'passed'].find((status) => outputs.some((output) => output.review.status === status));
+  const flags = current.filter((record) => record.status === 'flagged' || record.status === 'unreviewed').map((record) => `${record.title}: ${record.status === 'flagged' ? 'the check still failed after the allowed redo' : 'the reviewer returned no valid verdict'}`);
+  flags.push(...new Set(current.flatMap((record) => [...(record.limitations || []), ...(record.review?.limitations || [])])));
+  if (reviewStatus === 'not_checked') flags.push('The final deliverable was not checked.');
+  return {
+    v: 2,
+    kind: 'factory-run-receipt',
+    run: state.id,
+    issuer: state.runner.mode === 'hosted' ? 'factory.mindburn.org' : 'self',
+    factory: { name: state.factory.name, version: state.factory.version, sha256: await bundleHash(state.factory.files) },
+    inputs_sha256: await sha256(canonical(state.inputs)),
+    runner: { mode: state.runner.mode, provider: state.runner.provider || null, model: state.runner.model || null },
+    started: new Date(state.started).toISOString(),
+    finished: new Date(state.finished).toISOString(),
+    steps: state.records.map((record) => ({
+      id: record.id,
+      title: record.title,
+      agent: record.agent,
+      kind: record.kind,
+      attempt: record.attempt,
+      status: record.status,
+      tools: record.tools.map((tool) => ({ tool: tool.tool, target: tool.target })),
+      note: record.verdict?.note,
+      verdict: record.verdict,
+      review: record.review,
+      limitations: record.limitations,
+      decision: record.decision,
+      seen_sha256: record.seen_sha256,
+      approval_id: record.approval_id,
+      output_sha256: record.output_sha256,
+      started: new Date(record.started).toISOString(),
+      finished: new Date(record.finished).toISOString(),
+    })),
+    flags,
+    ...(outputs ? { outputs } : {}),
+    deliverable_review: { status: reviewStatus, sha256: deliveredHash, checks: outputs ? outputs.flatMap((output) => output.review.checks) : checks.map((record) => ({ id: record.id, attempt: record.attempt })) },
+    deliverable_sha256: deliveredHash,
+    usage: { ...state.usage },
+  };
+}
+
+// Runs a factory until it ends or needs a person. `onApproval(approval,
+// artifactText, problem)` resolves to { action: 'approve' | 'revise' |
+// 'reject', note?, seen, approvalId } where approvalId is approval.id and
+// `seen` is approval.artifact_sha256, the hash of
+// the text it was given. A decision never carries replacement text: what is
+// approved is what the line made. Nothing here decides for the person: with no
+// onApproval, or an answer that is not a decision, the run is returned still
+// waiting. A refused decision is asked again with the reason.
+export async function runToEnd(state, host, onApproval) {
+  for (let guard = 0; guard < 120; guard += 1) {
+    await advance(state, host);
+    if (state.status === 'waiting') {
+      await ensureApprovalIdentity(state);
+      if (!onApproval) return state;
+      let problem = '';
+      for (let asked = 0; asked < 3 && state.status === 'waiting'; asked += 1) {
+        const decision = await onApproval(state.approval, state.artifacts[state.approval.artifact], problem);
+        if (!decision) return state;
+        problem = decisionProblem(state, decision);
+        if (!problem) resume(state, decision);
+      }
+      if (state.status === 'waiting') return state;
+    } else if (state.status !== 'running') {
+      return state;
+    }
+  }
+  state.status = 'failed';
+  state.error = 'The factory did not finish within its step budget.';
+  return state;
+}