@worca/app 1.3.0 → 1.4.0

package/src/core/graph/executor.mjs

@@ -2,7 +2,7 @@
 //
 // The generic execution layer of the node-graph engine: output allocation from
 // filename templates, the "## Ports (this run)" prompt block, prompt assembly, the
-// clarifier gate, and the five flow-node executors.
+// clarifier gate, the script dispatch and the five flow-node executors.
 //
 // GENERICITY CHARTER (hard rule for this module): there is NO agent-key branch
 // anywhere. Executor selection is `node.kind` + `meta.runnerType`; renderer selection
@@ -32,22 +32,25 @@
 // input left UNBOUND. The composite DRIVER is scheduler.mjs; this module owns the
 // document — including the prompt block that tells a producer where to write the
 // task files and what the manifest looks like.
-import { join, dirname, relative, basename } from 'node:path';
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join, dirname, relative } from 'node:path';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 
 import {
   runClaude, MOCK_WRITER_ROLES, MOCK_ROLE_CLARIFY, MOCK_ROLE_DECOMPOSER,
 } from '../claude-runner.mjs';
 import { planPath, reviewPath, writeStepQuestions, writeClarify } from '../artifacts.mjs';
-import { readReview, normalizeClarify, normalizeReview, safeParseJson } from '../protocol.mjs';
+import { readReview, classifyAskPayload } from '../protocol.mjs';
+import { prepareFormAsk, formAnswerValidator, downgradeQuestion } from '../ask-forms.mjs';
 import {
   taskHeader, buildSystemPrompt, resolveAgentBody, mockMarkers, runOpts,
   fanOutDirective, ctxFanOut, ctxSubagentModel, ctxEndpointRouted, workspaceFanOutDirective, workspaceDiffInstruction,
   renderAnswers, siblingsBlock, diffInstruction, READ_WRITE_TOOLS, IMPLEMENTER_TOOLS, MEMORY_TOOLS,
+  askFormsBlock,
 } from '../phases.mjs';
 import { SUBAGENT_MODELS } from '../model-env.mjs';
 import { AWAIT_PORT } from '../../shared/graph/constants.mjs';
+import { runScriptExecution } from './script-runner.mjs';
 
 /** The reserved synthesized gate input. Scheduler-only: it never reaches `bindings`,
  *  is never listed in the Ports block, selects no mode, and carries no renderer. */
@@ -382,68 +385,31 @@ export function resolveMockRole({ meta, expandsPort = null }) {
 
 // ── verdicts ──────────────────────────────────────────────────────────────────
 
-/** The text every unparseable verdict file fails with. */
-const BAD_VERDICT_TAIL = 'expected { "issues": [ \u2026 ] }';
-
-/**
- * Read a node's verdict JSON back through the protocol normalizer.
- *
- * Two degenerate cases, deliberately split (they are NOT the same failure):
- *  - the file was NEVER WRITTEN -> `{issues: [], summary: '', missing: true}`: a clean
- *    pass, v1 parity, because an agent that declares a verdict and writes none must not
- *    fail a run. `missing` is the flag the caller turns into a warning (and the reason
- *    the reviews table skips the row) instead of a phantom zero-issue review.
- *  - the file EXISTS but does not parse, or carries no `issues` array -> THROW. The
- *    verifier wrote garbage, and on every shipped seed the clean side is wired straight
- *    to End, so "no issues" there is indistinguishable from an approval. Fail-fast owns
- *    the rest.
- *
- * `readReview` is untouched for its other callers (it is v1 code with its own tolerant
- * contract); the existsSync + parse-failure branch lives here.
- */
-export async function readVerdict(verdictPath) {
-  if (!verdictPath) return { issues: [], summary: '' };
-  if (!existsSync(verdictPath)) return { issues: [], summary: '', missing: true };
-  let text;
-  try {
-    text = await readFile(verdictPath, 'utf8');
-  } catch (err) {
-    throw Object.assign(new Error(`verdict file unreadable: ${verdictPath} — ${err?.message || err}`),
-      { code: 'BAD_VERDICT' });
-  }
-  const data = safeParseJson(text);
-  if (!data || typeof data !== 'object' || !Array.isArray(data.issues)) {
-    throw Object.assign(new Error(`verdict file is not a review JSON: ${verdictPath} — ${BAD_VERDICT_TAIL}`),
-      { code: 'BAD_VERDICT' });
-  }
-  return normalizeReview(data);
-}
-
-/** The warning line a missing verdict raises, relative to the pipeline dir so the
- *  run log stays readable. */
-function missingVerdictWarning(ctx, verdictPath) {
-  const rel = ctx?.pipelineDir ? relative(ctx.pipelineDir, verdictPath) : basename(verdictPath);
-  return `verdict file missing: ${ctx?.nodeId || ctx?.node?.id || '?'} ${rel} — treated as clean`;
-}
+import { readVerdict, missingVerdictWarning, publishable } from './exec-io.mjs';
+export { readVerdict, publishable };
 
 // ── prompt assembly ───────────────────────────────────────────────────────────
 
 /** The role-free base instruction, keyed by runnerType — never by an agent key. The
  *  producer/verifier sentences are v1's generic runners (phases.mjs:1207-1209 /
  *  :1245-1246); the clarifier sentence is v1's buildClarifyPrompt (:581-587) minus
- *  its parenthetical aside that named two builtin agents a generic graph need not have. */
-function baseInstruction(runnerType) {
+ *  its parenthetical aside that named two builtin agents a generic graph need not have.
+ *  §4: a clarifier that declares ask forms gets the forms section appended; one that
+ *  declares none returns today's string byte for byte. */
+function baseInstruction(runnerType, meta = null) {
   if (runnerType === 'verifier') {
     return 'You are a verifier. Inspect the inputs below exactly as your role instructions describe, ' +
       'then write a human-readable review markdown AND a machine-readable review JSON.';
   }
   if (runnerType === 'clarifier') {
-    return 'Identify the decisions you cannot safely resolve from the task text or the real ' +
+    const clarify = 'Identify the decisions you cannot safely resolve from the task text or the real ' +
       'codebase — including things a downstream agent would otherwise silently assume. For ' +
       'each, produce one conceptual question with 2 to 4 options and a free-text fallback. Ask ' +
       'only what materially changes the plan (up to 8 questions); never pad, and never split one ' +
       'decision. For low-impact details, pick a sensible default rather than asking. If you have ' +
       'no material open questions, write { "questions": [] } to that same path.';
+    const forms = askFormsBlock(meta?.ask?.forms);
+    return forms ? `${clarify}\n\n${forms}` : clarify;
   }
   return 'You are a pipeline agent. Read every input below, do your job exactly as your role ' +
     'instructions describe, and write EVERY declared output to its exact path.';
@@ -544,7 +510,7 @@ export function buildAgentPrompt(ctx) {
   return (
     taskHeader(headerCtx, title) +
     '\n## What to do\n\n' +
-    baseInstruction(meta.runnerType) + '\n\n' +
+    baseInstruction(meta.runnerType, meta) + '\n\n' +
     (hints ? hints + '\n\n' : '') +
     modeBlock(selectMode({ ports, bindings, freshPorts: trigger.freshPorts })) +
     fanOutDirective(ctxFanOut(ctx), { omitProjectAgents: relative, subagentModel: ctxSubagentModel(ctx), endpointRouted: routed }) +
@@ -575,6 +541,16 @@ async function readPriorAnswers(ports, bindings = {}) {
   const path = port ? bindings[port.id]?.path : null;
   if (!path) return [];
   const json = await readJsonMaybe(path);
+  // A clarifier that answered with a FORM writes {form, version, values}; project
+  // it mechanically so a downstream `as:'answers'` port still renders something
+  // (E18). P4 may replace this with the shared text projection.
+  if (json && typeof json === 'object' && typeof json.form === 'string' && json.values && typeof json.values === 'object') {
+    return Object.entries(json.values).map(([field, value]) => ({
+      id: field,
+      question: field,
+      choice: typeof value === 'string' ? value : JSON.stringify(value),
+    }));
+  }
   return Array.isArray(json?.answers) ? json.answers : [];
 }
 
@@ -645,18 +621,6 @@ async function spawnAgent(full, { role, prompt, systemPrompt, allowedTools }) {
   return { text, sessionId };
 }
 
-/** The output map the scheduler publishes from: an entry per declared port, with a
- *  path where one was allocated and an empty payload for void ports. Exported for
- *  P4's composite `finish` arm. */
-export function publishable(ports, outputs) {
-  const out = {};
-  for (const port of ports?.outputs || []) {
-    if (!port) continue;
-    out[port.id] = outputs[port.id]?.path ? { path: outputs[port.id].path } : {};
-  }
-  return out;
-}
-
 /**
  * The ONE generic agent executor — the generalization of v1's runGenericProducer and
  * runGenericVerifier and of the nine bespoke runners they replace. Selected for
@@ -690,6 +654,9 @@ export async function runAgentExecution(ctx) {
  * row and the History UI render the full Q&A without a join.
  */
 function normalizeAnswers(payload, questions) {
+  // A form answer is `{form, version, values}` and is NEVER flattened here: the
+  // "fill with the first option" fallback below is legacy-kind only (spec §5).
+  if (payload && typeof payload === 'object' && typeof payload.form === 'string' && payload.values) return [];
   const arr = Array.isArray(payload?.answers) ? payload.answers : Array.isArray(payload) ? payload : [];
   const byId = new Map();
   for (const a of arr) if (a && a.id != null) byId.set(String(a.id), String(a.choice ?? ''));
@@ -700,6 +667,52 @@ function normalizeAnswers(payload, questions) {
   }));
 }
 
+/**
+ * Gate 2 for a clarifier's `{form,data}` ask (spec §5). One repair spawn on a
+ * refusal — resumed on the SAME session (`sessionId` is the id captured off the
+ * FIRST spawn; the repair re-attaches it exactly as _questionsLoop resumes a
+ * producer), with formRepairBlock rendering the error list and the schema through
+ * runOpts — then a downgrade to one generic free-text question. Never throws. The
+ * returned `sessionId` is the repair's own when it reported one, else the first's.
+ * @returns {Promise<{ask:object|null, autoValues:object|null, questions:Array, sessionId:string|null}>}
+ */
+async function prepareClarifierForm({ full, meta, node, ordinal, answersPath, payload, warnings, spawn, sessionId: first = null }) {
+  const askId = `${CLARIFY_ASK_KIND}-${node.id}-${ordinal}`;
+  let current = payload;
+  let sessionId = first || null;
+  for (let attempt = 1; attempt <= 2; attempt++) {
+    const prepared = await prepareFormAsk({
+      agentMeta: meta,
+      payload: { form: current.form, data: current.data },
+      cwd: full.projectDir,
+      pipelineDir: full.runCtx?.pipelineDir || full.pipelineDir,
+      askId,
+    });
+    if (prepared.ok) return { ask: prepared.ask, autoValues: prepared.autoValues, questions: [], sessionId };
+    const why = prepared.errors.map((e) => `${e.path ? `${e.path}: ` : ''}${e.message}`).join('; ');
+    warnings.push(`${meta.displayName || node.key}: form "${current.form}" was refused — ${why}`);
+    if (attempt === 2) break;
+    const repairCtx = {
+      ...full,
+      resumeSessionId: sessionId || full.resumeSessionId,
+      formRepair: {
+        form: current.form, errors: prepared.errors,
+        schema: meta?.ask?.forms?.[current.form]?.data || null, file: answersPath,
+      },
+    };
+    const again = await spawnAgent(repairCtx, spawn);
+    sessionId = again.sessionId ?? sessionId;
+    const retry = classifyAskPayload(await readJsonMaybe(answersPath));
+    if (retry.kind !== 'form') {
+      return { ask: null, autoValues: null, questions: retry.kind === 'questions' ? retry.questions : [], sessionId };
+    }
+    current = retry;
+  }
+  const title = meta?.ask?.forms?.[current.form]?.title || '';
+  warnings.push(`${meta.displayName || node.key}: form "${current.form}" downgraded to a free-text question after two refusals.`);
+  return { ask: null, autoValues: null, questions: [downgradeQuestion({ form: current.form, title })], sessionId };
+}
+
 /**
  * The clarifier executor — selected by `meta.runnerType === 'clarifier'`, NEVER by an
  * agent key, so any number of clarifier nodes per graph is legal. Spawn → read the
@@ -716,12 +729,64 @@ export async function runClarifierExecution(ctx) {
   const answersPath = outputs[answersPort?.id]?.path;
   if (!answersPath) throw new Error(`clarifier node "${node?.id}": no json output port to write the questions to`);
 
-  const { sessionId } = await spawnAgent(full, { role, prompt, systemPrompt, allowedTools });
+  let sessionId;
+  ({ sessionId } = await spawnAgent(full, { role, prompt, systemPrompt, allowedTools }));
 
-  const { questions } = normalizeClarify(await readJsonMaybe(answersPath));
+  const raw = await readJsonMaybe(answersPath);
+  const payload = classifyAskPayload(raw);
   // Non-interactive default (v1 `_ask` auto): no gate ⇒ every question takes its first
   // option (normalizeAnswers' fallback). The scheduler's onAsk never sees clarify asks.
-  const ask = typeof ctx.ask === 'function' ? ctx.ask : async () => ({ answers: [] });
+  const ask = typeof ctx.ask === 'function' ? ctx.ask : null;
+  const warnings = pinIgnoredWarning ? [pinIgnoredWarning] : [];
+  let questions = payload.kind === 'questions' ? payload.questions : [];
+
+  if (payload.kind === 'form') {
+    // Gate 2 (spec §5), with the ONE repair spawn the producer loop also gets —
+    // a clarifier has no _questionsLoop, so the repair is a resumed spawn here.
+    const gate = await prepareClarifierForm({
+      full, meta, node, ordinal, answersPath, payload, warnings,
+      spawn: { role, systemPrompt, allowedTools, prompt },
+      sessionId,                                // E6: the repair RESUMES the first spawn's session
+    });
+    if (gate.ask) {
+      const answered = await (ask
+        ? ask({
+          // `id` is the QUESTION id — the same string the legacy arm below uses,
+          // so `orch.answer(id, …)` is uniform. `askId` is the route token
+          // prepareFormAsk minted from it, which may differ whenever a node id
+          // carries a character outside [A-Za-z0-9_-] (ruling X1).
+          id: `${CLARIFY_ASK_KIND}-${node.id}-${ordinal}`,
+          kind: 'form', nodeId: node.id, agent: meta.displayName || node.key,
+          askId: gate.ask.askId, form: gate.ask.form, version: gate.ask.version, title: gate.ask.title,
+          surface: gate.ask.surface,
+          data: gate.ask.data, layout: gate.ask.layout, answerSchema: gate.ask.answerSchema,
+          fileRefs: gate.ask.fileRefs, files: gate.ask.files,
+          autoValues: gate.autoValues, validate: formAnswerValidator(gate.ask),
+        })
+        // No gate at all (auto): D10's auto answer, exactly what _ask would return.
+        : Promise.resolve({ form: gate.ask.form, version: gate.ask.version, values: gate.autoValues || {} }));
+      const values = (answered && typeof answered === 'object' && answered.values) || {};
+      if (ctx.pipelineId) {
+        await writeStepQuestions(ctx.pipelineId, ctx.executionId, ordinal, {
+          agentKey: node?.key, nodeId: node?.id, questions: gate.ask,
+        });
+        await writeClarify(ctx.pipelineId, { questions: gate.ask });
+        const answerRow = { kind: 'form', form: gate.ask.form, version: gate.ask.version, values };
+        await writeStepQuestions(ctx.pipelineId, ctx.executionId, ordinal, {
+          agentKey: node?.key, nodeId: node?.id, answers: answerRow,
+        });
+        await writeClarify(ctx.pipelineId, { answers: answerRow });
+      }
+      await mkdir(dirname(answersPath), { recursive: true }).catch(() => {});
+      await writeFile(answersPath, JSON.stringify({ form: gate.ask.form, version: gate.ask.version, values }, null, 2) + '\n', 'utf8');
+      return { outputs: publishable(ports, outputs), questions: [], answers: [],
+        form: gate.ask.form, version: gate.ask.version, values,
+        sessionId: gate.sessionId ?? sessionId, prompt, warnings };
+    }
+    questions = gate.questions;               // the downgrade takes the legacy arm below
+    sessionId = gate.sessionId ?? sessionId;
+  }
+
   let answers = [];
   if (questions.length) {
     if (ctx.pipelineId) {
@@ -730,14 +795,14 @@ export async function runClarifierExecution(ctx) {
       });
       await writeClarify(ctx.pipelineId, { questions: { questions } });
     }
-    const payload = await ask({
+    const answerPayload = await (ask || (async () => ({ answers: [] })))({
       id: `${CLARIFY_ASK_KIND}-${node.id}-${ordinal}`,
       kind: CLARIFY_ASK_KIND,
       nodeId: node.id,
       agent: meta.displayName || node.key,
       questions,
     });
-    answers = normalizeAnswers(payload, questions);
+    answers = normalizeAnswers(answerPayload, questions);
     if (ctx.pipelineId) {
       await writeStepQuestions(ctx.pipelineId, ctx.executionId, ordinal, {
         agentKey: node?.key, nodeId: node?.id, answers: { answers },
@@ -748,8 +813,7 @@ export async function runClarifierExecution(ctx) {
 
   await mkdir(dirname(answersPath), { recursive: true }).catch(() => {});
   await writeFile(answersPath, JSON.stringify({ questions, answers }, null, 2) + '\n', 'utf8');
-  return { outputs: publishable(ports, outputs), questions, answers, sessionId, prompt,
-    warnings: pinIgnoredWarning ? [pinIgnoredWarning] : [] };
+  return { outputs: publishable(ports, outputs), questions, answers, sessionId, prompt, warnings };
 }
 
 // ── flow executors (pure engine: instant, $0, no process spawn) ───────────────
@@ -891,6 +955,11 @@ export function runExecution(ctx, opts = {}) {
     case 'end': return runEndExecution(ctx);
     case 'combine':
       return runCombineExecution({ ...ctx, names: ctx.names || combineNames(ctx.template, node.id) });
+    case 'script': {
+      // A child process, not a Claude spawn (spec §6.1). `runners.script` is the test seam.
+      const injectedScript = (opts.runners || ctx.runners || {}).script;
+      return typeof injectedScript === 'function' ? injectedScript(ctx) : runScriptExecution(ctx);
+    }
     case 'agent': break;
     default:
       throw new Error(`node "${node.id}": unknown kind "${node.kind}"`);

package/src/core/graph/human-evidence.mjs

@@ -0,0 +1,131 @@
+// src/core/graph/human-evidence.mjs
+// Per-execution EVIDENCE for the human-hours estimate (money-saved design §3). Agent-agnostic
+// by construction: it reads node.kind, the meta's runnerType/sideEffect/humanEffort, the port
+// TYPES and filename templates, the allocated output paths, the bound input paths and the
+// worktree — never an agent key. All file reads are best-effort: a missing or unreadable file
+// contributes nothing.
+import { readFile } from 'node:fs/promises';
+import { proseWords, jsonItems } from '../../shared/human-estimate.mjs';
+
+const REVISION_RE = /-v\d+\.md$/i;   // `{vsuffix}` renders as `-vN` for N > 1 (executor.mjs resolveTemplate)
+
+/**
+ * A promise chain: `run(fn)` runs fn after every earlier fn has settled and returns fn's own
+ * promise. A rejection reaches that caller only; the chain itself never rejects. The
+ * orchestrator puts every cursor measurement of a run through one queue, so two fan-out
+ * slices ending together cannot both read the same cursor and credit one delta twice.
+ */
+export function serialQueue() {
+  let tail = Promise.resolve();
+  return (fn) => {
+    const next = tail.then(fn);
+    tail = next.catch(() => {});
+    return next;
+  };
+}
+
+/**
+ * Cumulative numstat over every member work dir against its checkpoint ref. `null` when no
+ * member has a checkpoint. `stage` (optional) runs ONCE before measuring: `git diff
+ * <checkpoint>` never lists an untracked file, so the caller passes the harness's intent-to-add
+ * staging (`_stageWorkingTree`) — the same staging the reviewer's diff relies on. The exclude
+ * pathspecs are the set `_buildResults` / `_commitWork` use, so the cursor and results.json agree.
+ * @param {{workDirs: Map<string,string>, checkpointRefs: Record<string,string>, excludeFor:(key:string)=>string[], numstat:Function, stage?:Function}} o
+ * @returns {Promise<{files:number, insertions:number, deletions:number}|null>}
+ */
+export async function measureCodeCursor({ workDirs, checkpointRefs, excludeFor, numstat, stage = null }) {
+  if (typeof stage === 'function') { try { await stage(); } catch { /* best-effort: measure what is visible */ } }
+  let seen = false;
+  const out = { files: 0, insertions: 0, deletions: 0 };
+  for (const [key, dir] of workDirs?.entries?.() || []) {
+    const base = checkpointRefs?.[key];
+    if (!base) continue;
+    seen = true;
+    let m;
+    try { m = await numstat(dir, base, undefined, excludeFor(key) || []); } catch { continue; }
+    for (const row of m.values()) {
+      if (row.binary) continue;
+      out.files += 1;
+      out.insertions += row.added | 0;
+      out.deletions += row.removed | 0;
+    }
+  }
+  return seen ? out : null;
+}
+
+/** now − prev, each component clamped at 0. `prev` null means "from zero". `now` null → null. */
+export function codeDelta(now, prev) {
+  if (!now) return null;
+  const p = prev || { files: 0, insertions: 0, deletions: 0 };
+  return {
+    files: Math.max(0, (now.files | 0) - (p.files | 0)),
+    insertions: Math.max(0, (now.insertions | 0) - (p.insertions | 0)),
+    deletions: Math.max(0, (now.deletions | 0) - (p.deletions | 0)),
+  };
+}
+
+async function readText(read, path) {
+  if (!path) return null;
+  try { return await read(path, 'utf8'); } catch { return null; }
+}
+
+function jsonItemsOf(text) {
+  try { return jsonItems(JSON.parse(text)); } catch { return 0; }
+}
+
+/**
+ * @param {{ctx: object, cursorPrev: object|null, cursorNow: object|null, read?: Function}} o
+ *   ctx is the orchestrator's execution ctx (_execCtx): node, ordinal, meta, ports, outputs,
+ *   bindings, verdict. cursorPrev = the cumulative cursor at the previous terminal (this step's
+ *   start), cursorNow = the cursor measured at this step's terminal.
+ */
+export async function collectStepEvidence({ ctx, cursorPrev = null, cursorNow = null, read = readFile }) {
+  const nodeKind = ctx?.node?.kind || 'agent';
+  const isAgent = nodeKind === 'agent';
+  const meta = ctx?.meta || {};
+  const cycle = Number.isInteger(ctx?.ordinal) && ctx.ordinal > 0 ? ctx.ordinal : 1;
+  const agent = isAgent ? { runnerType: meta.runnerType, sideEffect: meta.sideEffect, humanEffort: meta.humanEffort } : null;
+
+  // Outputs: one entry per DISTINCT allocated path (a refiner's plan/revise pair is one file).
+  const outputs = [];
+  const seen = new Set();
+  for (const port of ctx?.ports?.outputs || []) {
+    if (!port || (port.type !== 'md' && port.type !== 'json')) continue;
+    const path = ctx?.outputs?.[port.id]?.path;
+    if (!path || seen.has(path)) continue;
+    seen.add(path);
+    const text = await readText(read, path);
+    if (text == null) continue;                          // not produced (a `when`-gated port, or the step died early)
+    if (port.type === 'md') {
+      // A revision: this port versions its file ({vsuffix}) AND the allocated name carries -vN,
+      // or the execution itself is a re-run (cycle > 1). The template check keeps a base name
+      // that merely ends in "-v2" from reading as a revision.
+      const versioned = String(port.filename || '').includes('{vsuffix}') && REVISION_RE.test(path);
+      outputs.push({ type: 'md', words: proseWords(text), revision: versioned || cycle > 1 });
+    } else {
+      outputs.push({ type: 'json', items: jsonItemsOf(text) });
+    }
+  }
+  const verdictPath = ctx?.verdict?.path;
+  if (verdictPath && !seen.has(verdictPath)) {
+    const text = await readText(read, verdictPath);
+    if (text != null) outputs.push({ type: 'json', items: jsonItemsOf(text) });
+  }
+
+  // Reads: verifiers only — the diff as it stood when the step STARTED plus every md input.
+  let reads = null;
+  if (isAgent && meta.runnerType === 'verifier') {
+    const inputs = ctx?.ports?.inputs || [];
+    const readsWorktree = inputs.some((p) => p && p.as === 'worktree');
+    const diffLines = readsWorktree && cursorPrev ? (cursorPrev.insertions | 0) + (cursorPrev.deletions | 0) : 0;
+    let words = 0;
+    for (const port of inputs) {
+      if (!port || port.type !== 'md') continue;
+      const text = await readText(read, ctx?.bindings?.[port.id]?.path);
+      if (text != null) words += proseWords(text);
+    }
+    reads = { diffLines, words };
+  }
+
+  return { nodeKind, agent, cycle, code: isAgent ? codeDelta(cursorNow, cursorPrev) : null, outputs, reads };
+}

package/src/core/graph/python-probe.mjs

@@ -0,0 +1,172 @@
+// src/core/graph/python-probe.mjs
+// Can this host run a python script card? (scripts-workbench spec §7.) ONE answer,
+// read by everything: the runner before it spawns, the run preflight, the bench,
+// GET /api/scripts/runtimes and the Scripts page picker. Nothing else probes.
+//
+// Each candidate runs a stdlib one-liner and must print a parseable version
+// array, so the Windows Store stub — an app-execution alias named python.exe that
+// prints nothing and exits 9009 (or pops the Store) — fails the parse and is
+// skipped instead of being reported as a working interpreter.
+//
+// Every seam is injectable (env, platform, spawn, settings, timeoutMs) so the
+// Windows candidate order is unit-tested on macOS and Linux with no python
+// installed. The 60 s cache covers the BARE call only: a unit test that injects a
+// fake spawn can never poison what the server reads next.
+import { spawn as nodeSpawn } from 'node:child_process';
+import path from 'node:path';
+import { pythonPath } from '../settings.mjs';
+
+/** 3.8 is the floor: importlib.util.spec_from_file_location + asyncio.run + f-strings. */
+export const PYTHON_MIN = Object.freeze([3, 8]);
+export const PROBE_TIMEOUT_MS = 5000;
+export const PROBE_CACHE_MS = 60000;
+/** The version answer is ~12 bytes. Anything that prints more than this is not a python, and an unbounded
+ *  accumulator here is a HOST crash: `yes` fills a V8 string ("Invalid string length") well inside the 5 s window. */
+export const PROBE_OUTPUT_MAX = 4096;
+/** Standard library, one line, no f-string: it must at least PARSE on whatever the user points at. */
+export const VERSION_SCRIPT = 'import sys,json;print(json.dumps(list(sys.version_info[:3])))';
+
+const blank = (v) => typeof v !== 'string' || v.trim() === '';
+
+/**
+ * An explicit interpreter with a directory part is made ABSOLUTE here, once. The
+ * probe spawns from the server's cwd and the runner spawns from the RUN's cwd (a
+ * worktree somewhere else), so a relative `.venv/bin/python` would pass the probe
+ * and then fail every execution with ENOENT. A bare name (`python3.12`) has no
+ * directory part and stays a PATH lookup, which is cwd-independent.
+ */
+function explicitCommand(value, platform, cwd) {
+  const v = value.trim();
+  const p = platform === 'win32' ? path.win32 : path.posix;
+  const hasDir = platform === 'win32' ? /[\\/]/.test(v) : v.includes('/');
+  return [hasDir && !p.isAbsolute(v) ? p.resolve(cwd, v) : v];
+}
+const label = (command) => command.join(' ');
+
+/**
+ * The candidates, in order (§7). An EXPLICIT interpreter is AUTHORITATIVE: with
+ * WORCA_PYTHON (or the pythonPath setting) set, that one is tried and the probe
+ * stops — the failure sentence tells the user to set WORCA_PYTHON, so a silent
+ * fall-through to some other python would make that advice a lie, and a venv
+ * pointer must never be quietly replaced by the system interpreter. The value is
+ * ONE executable path, used verbatim (`C:\Program Files\Python312\python.exe`).
+ * @param {{env?:object, platform?:string, settings?:object|null, cwd?:string}} [o] `settings` is a test seam; null reads the store
+ */
+export function pythonCandidates({ env = process.env, platform = process.platform, settings = null, cwd = process.cwd() } = {}) {
+  if (!blank(env.WORCA_PYTHON)) return [{ command: explicitCommand(env.WORCA_PYTHON, platform, cwd), source: 'WORCA_PYTHON' }];
+  const configured = settings ? settings.pythonPath : pythonPath();
+  if (!blank(configured)) return [{ command: explicitCommand(configured, platform, cwd), source: 'pythonPath' }];
+  if (platform === 'win32') {
+    return [{ command: ['py', '-3'], source: 'path' }, { command: ['python'], source: 'path' }, { command: ['python3'], source: 'path' }];
+  }
+  return [{ command: ['python3'], source: 'path' }, { command: ['python'], source: 'path' }];
+}
+
+/** `[3, 12, 4]` from the version script's stdout; null for anything else (the Store stub prints nothing). */
+export function parseVersion(text) {
+  const lines = String(text || '').trim().split('\n');
+  const last = lines[lines.length - 1].trim();
+  if (!last) return null;
+  let v;
+  try { v = JSON.parse(last); } catch { return null; }
+  if (!Array.isArray(v) || v.length !== 3 || !v.every((n) => Number.isInteger(n) && n >= 0)) return null;
+  return v;
+}
+
+export const meetsFloor = (v) => v[0] > PYTHON_MIN[0] || (v[0] === PYTHON_MIN[0] && v[1] >= PYTHON_MIN[1]);
+
+/**
+ * Ask ONE candidate for its version. Never throws, never rejects.
+ * Windows: `py.exe` launches `python.exe` as a child, so the timeout kill reaches
+ * the launcher only — acceptable for a one-liner that exits immediately, and a
+ * tree kill here would mean importing script-runner.mjs, which imports this module.
+ * @returns {Promise<{version:number[]}|{error:string}>}
+ */
+function askVersion(command, { spawn, timeoutMs }) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(command[0], [...command.slice(1), '-c', VERSION_SCRIPT], { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+    } catch (err) {
+      resolve({ error: err?.message || String(err) });
+      return;
+    }
+    let out = '';
+    let settled = false;
+    const done = (v) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try { child.kill('SIGKILL'); } catch { /* already gone */ }
+      resolve(v);
+    };
+    const timer = setTimeout(() => done({ error: `no answer in ${Math.round(timeoutMs / 1000)} s` }), timeoutMs);
+    child.stdout?.setEncoding('utf8').on('data', (c) => {
+      if (settled) return;
+      out += c;
+      if (out.length > PROBE_OUTPUT_MAX) done({ error: 'printed more than a version' });
+    });
+    child.stderr?.resume();                    // drained, never read: a stub's banner is not an answer
+    child.on('error', (err) => done({ error: err?.message || String(err) }));
+    child.on('close', (code) => {
+      const version = parseVersion(out);
+      done(version ? { version } : { error: `exit ${code} with no version` });
+    });
+  });
+}
+
+/** The one sentence the picker shows as its `title` and the run/bench repeat. */
+function failureReason(candidates, tried, tooOld) {
+  if (tooOld) return `python ${tooOld.version.join('.')} at "${label(tooOld.command)}" is older than 3.8 — point WORCA_PYTHON at a newer interpreter`;
+  const first = candidates[0];
+  if (first?.source === 'WORCA_PYTHON') return `WORCA_PYTHON "${label(first.command)}" is not a working python`;
+  if (first?.source === 'pythonPath') return `the pythonPath setting "${label(first.command)}" is not a working python`;
+  return `no python 3.8 or newer found (tried ${tried.join(', ')})`;
+}
+
+async function runProbe({ env, platform, spawn, settings, timeoutMs, cwd }) {
+  const candidates = pythonCandidates({ env, platform, settings, cwd });
+  const tried = [];
+  let tooOld = null;
+  for (const c of candidates) {
+    const r = await askVersion(c.command, { spawn, timeoutMs });
+    tried.push(label(c.command));
+    if (r.version && meetsFloor(r.version)) return { ok: true, command: c.command, version: r.version };
+    if (r.version && !tooOld) tooOld = { command: c.command, version: r.version };
+  }
+  return { ok: false, reason: failureReason(candidates, tried, tooOld) };
+}
+
+let cached = null;                              // { at, promise } — the BARE call only
+
+/**
+ * The host's python (§7). Cached 60 s per process when called with NO options;
+ * any option at all (a test seam) bypasses and never fills the cache.
+ * @returns {Promise<{ok:true, command:string[], version:number[]}|{ok:false, reason:string}>}
+ */
+export function probePython(opts = {}) {
+  const bare = Object.keys(opts).length === 0;
+  if (bare && cached && Date.now() - cached.at < PROBE_CACHE_MS) return cached.promise;
+  // NEVER rejects: express 4 does not catch an async handler's rejection, the bare promise is CACHED for 60 s,
+  // and an unhandled rejection takes the server down. Whatever goes wrong here is "no python", with the reason.
+  const promise = runProbe({
+    env: opts.env || process.env,
+    platform: opts.platform || process.platform,
+    spawn: opts.spawn || nodeSpawn,
+    settings: opts.settings || null,
+    timeoutMs: Number.isInteger(opts.timeoutMs) ? opts.timeoutMs : PROBE_TIMEOUT_MS,
+    cwd: opts.cwd,
+  }).catch((err) => ({ ok: false, reason: `the python probe failed: ${err?.message || err}` }));
+  if (bare) cached = { at: Date.now(), promise };
+  return promise;
+}
+
+/** Drop the 60 s cache. Tests only — product code never calls it. */
+export function resetPythonProbe() { cached = null; }
+
+/** The `python` arm of GET /api/scripts/runtimes (spec §3.4). */
+export function pythonRuntimeState(probe) {
+  return probe?.ok
+    ? { ok: true, version: probe.version.join('.'), command: probe.command }
+    : { ok: false, reason: probe?.reason || 'python was not probed' };
+}

package/src/core/graph/registry-ports.mjs

@@ -1,12 +1,16 @@
 // src/core/graph/registry-ports.mjs
-// Engine-side glue: a loaded agent registry -> the shared portsFn. Lives in
-// src/core (not src/shared) because it exists only to bridge the Node-side
-// registry shape; the resolution logic itself is shared.
+// Engine-side glue: the loaded agent registry AND the loaded script registry ->
+// the shared portsFn. Lives in src/core (not src/shared) because it exists only
+// to bridge the Node-side registry shapes; the resolution logic itself is shared.
 import { portsFnFor } from '../../shared/graph/ports.mjs';
 import { indexByKey } from '../../shared/graph/agent-meta.mjs';
 
-/** @param {Record<string,object>|object[]} registry loadAgentRegistry() output (or a list) */
-export function registryPortsFn(registry) {
+/**
+ * @param {Record<string,object>|object[]} registry loadAgentRegistry() output (or a list)
+ * @param {Record<string,object>|object[]} [scripts] loadScriptRegistry() output (or a list); absent = no scripts resolve
+ */
+export function registryPortsFn(registry, scripts = {}) {
   const list = Array.isArray(registry) ? registry : Object.values(registry || {});
-  return portsFnFor(indexByKey(list));
+  const scriptList = Array.isArray(scripts) ? scripts : Object.values(scripts || {});
+  return portsFnFor(indexByKey(list), indexByKey(scriptList));
 }