@worca/app 1.3.0 → 1.4.0

package/src/core/phases.mjs

@@ -14,7 +14,7 @@
 // prompt so the system prompt is never empty. Interface is locked by docs/ARCHITECTURE.md §3.5.
 
 import { runClaude } from './claude-runner.mjs';
-import { resolveModelEnv } from './config.mjs';
+import { resolveModelEnv, bridgedModelInfo } from './config.mjs';
 import { SUBAGENT_AUTO, SUBAGENT_INHERIT, SUBAGENT_MODELS, effectiveSubagentModel } from './model-env.mjs';
 import { readClarify, readReview } from './protocol.mjs';
 import { writeClarify, readClarifyRow } from './artifacts.mjs';
@@ -83,6 +83,22 @@ export function ctxFanOut(ctx) {
  * ctx — from modelHasBaseUrlRouting(effective model), so this stays pure.
  * A present node wins, mirroring ctxFanOut. Pure + exported for testing.
  */
+/**
+ * The model env for a dispatched node: resolveModelEnv tagged with the
+ * execution id (the bridge books its calls per tag). A bridged model whose
+ * provider is not usable makes resolveModelEnv throw (fail fast, model-bridge
+ * design §8.5) — except under the offline mock, which spawns nothing and must
+ * keep running for a catalog that names a Copilot model nobody signed in to.
+ */
+function resolveDispatchModelEnv(c, ctx) {
+  try {
+    return resolveModelEnv(c.model, { tag: ctx.executionId });
+  } catch (err) {
+    if (c.mock && err && err.bridgeReason) return undefined;
+    throw err;
+  }
+}
+
 export function ctxEndpointRouted(ctx) {
   if (!ctx || typeof ctx !== 'object') return false;
   return !!(ctx.node ? ctx.node.endpointRouted : ctx.endpointRouted);
@@ -429,6 +445,55 @@ export const RESUME_HEADER =
   'state of your previous work (files/artifacts you already wrote), then continue the\n' +
   'ORIGINAL task below to completion. Do not redo work that is already done.\n\n';
 
+/**
+ * The per-agent forms section (spec §4): every form the agent may ask with, its
+ * data schema, its answer schema and its example. Returns '' for an agent that
+ * declares none, which is what keeps every prompt that exists today byte-identical.
+ * `path` is the file to write the payload to; omitted for a clarifier, whose
+ * Ports block already names its answers port. PURE.
+ * @param {Record<string, object>|null|undefined} forms
+ * @param {{path?: string}} [opts]
+ */
+export function askFormsBlock(forms, { path: askPath } = {}) {
+  const entries = Object.entries(forms || {});
+  if (!entries.length) return '';
+  const body = entries.map(([id, def]) => (
+    `### \`${id}\` — ${def.title || id} (version ${Number.isInteger(def.version) ? def.version : 1})\n\n` +
+    'data you must supply:\n```json\n' + JSON.stringify(def.data, null, 2) + '\n```\n\n' +
+    'answer you will receive:\n```json\n' + JSON.stringify(def.answer, null, 2) + '\n```\n\n' +
+    'example data:\n```json\n' + JSON.stringify(def.example, null, 2) + '\n```\n'
+  )).join('\n');
+  return (
+    '## Forms you may ask with\n\n' +
+    (askPath ? `Instead of the questions shape, write {"form":"<id>","data":{…}} to: ${askPath}\n` : '') +
+    'A `file` value is a path relative to your working directory or the pipeline dir. ' +
+    'You will be resumed with {"form","version","values"}.\n\n' +
+    body
+  );
+}
+
+/**
+ * The one repair round a refused form ask gets (spec §5 gate 2): the exact error
+ * list plus the data schema, and the SAME file to rewrite. Rendered by runOpts
+ * for BOTH engines — a clarifier never has questionsEnabled, so it could not
+ * ride questionsPromptBlock. '' when nothing is being repaired, which is what
+ * keeps every other prompt byte-identical. PURE.
+ * @param {{formRepair?: {form: string, errors: Array, schema: object|null, file: string}}} ctx
+ */
+export function formRepairBlock(ctx) {
+  const r = ctx && ctx.formRepair;
+  if (!r) return '';
+  const lines = (Array.isArray(r.errors) ? r.errors : [])
+    .map((e) => `- ${e && e.path ? `${e.path}: ` : ''}${(e && e.message) || 'invalid'}`)
+    .join('\n');
+  return (
+    '\n\n## Your form ask was refused\n\n' +
+    `Form \`${r.form}\`:\n${lines || '- invalid'}\n\n` +
+    (r.schema ? 'data schema:\n```json\n' + JSON.stringify(r.schema, null, 2) + '\n```\n\n' : '') +
+    `Write a corrected {"form","data"} to: ${r.file}\n`
+  );
+}
+
 /**
  * Ask-then-resume prompt block for a questions-enabled node (spec 2026-07-11).
  * Appended by runOpts, so EVERY producer/verifier runner inherits it with no
@@ -447,16 +512,28 @@ export function questionsPromptBlock(ctx) {
   const answered = prior.length
     ? '## Already answered — DO NOT ask these again\n\n' + renderAnswers(prior) + '\n'
     : '';
+  // Form answers already collected for this node, in the exact shape the agent
+  // receives them (spec §4). '' when there are none, so the legacy block is
+  // byte-identical.
+  const priorForms = Array.isArray(ctx.formAnswers) ? ctx.formAnswers : [];
+  const formAnswered = priorForms.length
+    ? '## Your form answers\n\n' + priorForms
+      .map((f) => '```json\n' + JSON.stringify({ form: f.form, version: f.version, values: f.values }, null, 2) + '\n```')
+      .join('\n\n') + '\n\n'
+    : '';
+  const forms = askFormsBlock(ctx.askForms, { path: ctx.questionsFile });
   if (!ctx.questionsFile) {
     return (
-      '\n\n' + answered +
+      '\n\n' + answered + formAnswered +
       '## Asking the user\n\n' +
       'No more question rounds are available this run — proceed with reasonable assumptions.\n'
     );
   }
-  const mock = prior.length ? '' : mockMarkers({ MOCK_ASK: ctx.questionsFile }) + '\n';
+  // MOCK_ASK only while NOTHING has been answered yet — legacy OR form: a resume that
+  // re-emitted it would make the offline mock re-ask every round until the cap.
+  const mock = (prior.length || priorForms.length) ? '' : mockMarkers({ MOCK_ASK: ctx.questionsFile }) + '\n';
   return (
-    '\n\n' + answered +
+    '\n\n' + answered + formAnswered +
     '## Asking the user (enabled)\n\n' +
     'If a decision materially shapes the outcome and you cannot resolve it from the task, ' +
     'the inputs, or the codebase — including anything material you are about to silently ' +
@@ -466,6 +543,7 @@ export function questionsPromptBlock(ctx) {
     '2. STOP immediately — do no further work. You will be resumed with the answers.\n' +
     'Assume freely on minor choices; on material ones, ask instead of assuming. Never pad, ' +
     'and never re-ask an answered question.\n\n' +
+    (forms ? forms + '\n' : '') +
     mock
   );
 }
@@ -495,7 +573,8 @@ export function runOpts(ctx, { role, prompt, systemPrompt, allowedTools }) {
   return {
     cwd: ctx.projectDir,
     systemPrompt,
-    prompt: (ctx.resumeSessionId ? RESUME_HEADER + prompt : prompt) + questionsPromptBlock(ctx),
+    prompt: (ctx.resumeSessionId ? RESUME_HEADER + prompt : prompt)
+      + questionsPromptBlock(ctx) + formRepairBlock(ctx),
     resumeSessionId: ctx.resumeSessionId,
     // Grant the role's baseline tools PLUS whatever the agent declared in its
     // frontmatter (e.g. the Playwright MCP browser_* tools). ctx.node is present
@@ -515,6 +594,12 @@ export function runOpts(ctx, { role, prompt, systemPrompt, allowedTools }) {
     // by the real runner (it is never a spawn flag).
     workspaceWriteTargets: workspaceWriteTargetsFor(ctx),
     permissionMode: c.permissionMode || 'acceptEdits',
+    // Agent memory (memory-write-split design D4): the writable copy lives OUTSIDE the cwd, so it
+    // rides --add-dir — acceptEdits auto-approves edits "inside your working directory or
+    // additionalDirectories" (documented), nothing else about the spawn changes, and the CLI loads
+    // nothing from that dir (CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD is never set here).
+    // undefined when the run has no mount ⇒ buildClaudeArgs emits nothing and the argv is byte-identical.
+    addDirs: typeof ctx.memoryMount === 'string' && ctx.memoryMount ? [ctx.memoryMount] : undefined,
     model: c.model,
     effort: c.effort,          // per-role effort from the orchestrator
     // Per-model routing env (design §4.4), resolved HERE — the one funnel every
@@ -524,7 +609,11 @@ export function runOpts(ctx, { role, prompt, systemPrompt, allowedTools }) {
     // env byte-identical. The sub-agent model policy deliberately does NOT
     // touch this env: its only wire is the prompt block (subagentModelDirective),
     // and CLAUDE_CODE_SUBAGENT_MODEL is a reserved model-env key.
-    modelEnv: resolveModelEnv(c.model),
+    modelEnv: resolveDispatchModelEnv(c, ctx),
+    // Model bridge (model-bridge-design.md §5.3): a translated model has no
+    // server-side web tools, so the runner withholds them. undefined for every
+    // non-bridged model ⇒ nothing emitted ⇒ argv byte-identical.
+    disallowedTools: bridgedModelInfo(c.model)?.excludeTools,
     // Agent memory (§4.3): Task-tool sub-agents inherit the rules natively but not
     // --append-system-prompt, so the pointer block rides the sub-agent flag. undefined when the
     // run has no mount ⇒ buildClaudeArgs emits nothing and legacy argv stays byte-identical.

package/src/core/plugin-api.mjs

@@ -9,10 +9,27 @@
 //
 // API 2 adds the chatChannels contribution + persistent channel worker
 // protocol; API 3 changes the DATA contract: agent sidecars are meta v2 (typed
-// ports) and workflows/*.json are v2 graphs. The task-source connector and the
-// channel-worker protocols are unchanged across 1 -> 2 -> 3, so a connector-only
-// ">=1 <2" plugin and a chat plugin's ">=2 <3" keep negotiating 1 and 2 and keep
-// working untouched. The set is what makes that possible: never collapse it to a
-// single integer.
-export const WORCA_PLUGIN_API = 3;
-export const WORCA_PLUGIN_APIS = [1, 2, 3];
+// ports) and workflows/*.json are v2 graphs. API 4 adds ONE thing: an agent
+// sidecar's `ask` block (declared question forms) is honoured. It does NOT
+// touch the sidecar or template contract, which is why WORCA_AGENT_DATA_API
+// exists and is 3 — comparing the data contract against WORCA_PLUGIN_API would
+// silently demote every current ">=3 <4" plugin's v1 sidecars from error to
+// warning on this bump. The task-source connector and the channel-worker
+// protocols are unchanged across 1 -> 2 -> 3 -> 4, so a connector-only
+// ">=1 <2" plugin and a chat plugin's ">=2 <3" keep negotiating 1 and 2 and
+// keep working untouched. The set is what makes that possible: never collapse
+// it to a single integer.
+export const WORCA_PLUGIN_API = 4;
+export const WORCA_PLUGIN_APIS = [1, 2, 3, 4];
+
+/** The API whose DATA contract agent sidecars and pipeline templates must meet:
+ *  meta v2 (typed ports) + version-2 graphs. Introduced by API 3, UNCHANGED by
+ *  4. `validatePluginDir`'s hard/soft split and the apiMismatch sentence are
+ *  about THIS, never about the newest host API. */
+export const WORCA_AGENT_DATA_API = 3;
+
+/** The API a plugin must NEGOTIATE (highest member its range admits) for the
+ *  `ask` blocks of the agents it ships to be honoured. Below it the block is
+ *  stripped at load and reported as an ignored contribution; the agent keeps
+ *  working with generic questions (ask-forms spec §10). */
+export const WORCA_ASK_FORMS_API = 4;

package/src/core/plugin-manifest.mjs

@@ -6,11 +6,15 @@
 import { readFileSync, readdirSync, readlinkSync, existsSync } from 'node:fs';
 import { join, resolve, dirname, sep, isAbsolute } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { WORCA_PLUGIN_API, WORCA_PLUGIN_APIS } from './plugin-api.mjs';
-import { EFFORTS, isReservedModelEnvKey, assertModelCost } from './model-env.mjs';
+import { WORCA_PLUGIN_API, WORCA_PLUGIN_APIS, WORCA_AGENT_DATA_API, WORCA_ASK_FORMS_API } from './plugin-api.mjs';
+import { EFFORTS, isReservedModelEnvKey, assertModelCost, assertModelUpstream, upstreamEnvConflict } from './model-env.mjs';
 import { validateMetaV2, normalizeAgentMeta, indexByKey } from '../shared/graph/agent-meta.mjs';
 import { portsFnFor } from '../shared/graph/ports.mjs';
 import { validateGraph } from '../shared/graph/validate.mjs';
+import { validateScriptMetaV2, normalizeScriptMeta } from '../shared/graph/script-meta.mjs';
+import { normalizeCases } from '../shared/graph/script-cases.mjs';
+import { normalizeAskBlock, validateFormDef } from '../shared/forms/form-def.mjs';
+import { ASK_LIMITS } from '../shared/forms/catalog.mjs';
 
 /** Plugin names are kebab-case, machine-unique, dir-name safe (spec §4.1). */
 export const PLUGIN_NAME_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
@@ -51,12 +55,32 @@ export function builtinAgentMetas(dir = BUILTIN_AGENTS_DIR) {
   }
   return out;
 }
+/** The built-in script layer (repo scripts/, D20). Same URL math as script-registry's DEFAULT_SCRIPTS_DIR. */
+const BUILTIN_SCRIPTS_DIR = fileURLToPath(new URL('../../scripts/', import.meta.url));
+
+/** Normalized built-in script sidecars, for the plugin-template isolation rule: a
+ *  template may reference built-in scripts (present on every host) plus the plugin's own. */
+export function builtinScriptMetas(dir = BUILTIN_SCRIPTS_DIR) {
+  const out = [];
+  let files = [];
+  try { files = readdirSync(dir).filter((f) => f.endsWith('.meta.json')); } catch { return out; }
+  for (const f of files.sort()) {
+    let meta = null;
+    try { meta = JSON.parse(readFileSync(join(dir, f), 'utf8')); } catch { continue; }
+    if (Number(meta?.metaVersion) !== 2 || !KEY_RE.test(String(meta.key || ''))) continue;
+    const { meta: norm, errors } = normalizeScriptMeta(meta);
+    if (errors.length) continue;
+    out.push(norm);
+  }
+  return out;
+}
+
 const KNOWN_SOURCE = new Set(['id', 'displayName', 'module', 'configSchema', 'inputs', 'multiProfile']);
 const KNOWN_CHANNEL = new Set(['id', 'displayName', 'platform', 'module', 'ingress', 'capabilities', 'configSchema']);
 const CHANNEL_INGRESS = new Set(['connect', 'webhook']);
 const KNOWN_FIELD = new Set(['key', 'type', 'label', 'secret', 'required', 'default', 'help', 'options']);
 const KNOWN_INPUT = new Set(['key', 'type', 'label', 'default', 'optionsFrom', 'options']);
-const KNOWN_MODEL = new Set(['id', 'label', 'efforts', 'env', 'cost']);
+const KNOWN_MODEL = new Set(['id', 'label', 'efforts', 'env', 'cost', 'upstream']);
 const KNOWN_MODEL_SECRET = new Set(['key', 'label']);
 /** A manifest env value that defers to the plugin's secrets store (design §9.1). */
 const isSecretRef = (v) => !!v && typeof v === 'object' && !Array.isArray(v)
@@ -110,6 +134,13 @@ export function negotiatedApi(range, apis = WORCA_PLUGIN_APIS) {
 export const NOT_META_V2 = 'not a meta v2 sidecar (declare "metaVersion": 2 with typed inputs/outputs) — plugin API 3 no longer reads channel sidecars';
 export const NOT_GRAPH_V2 = 'not a version-2 graph template (nodes/wires) — port the "steps" pipeline';
 
+/** The ONE sentence for a plugin that ships agent ask forms without negotiating
+ *  the API that honours them. Used verbatim by `agent-registry.scanLayer` (the
+ *  load-time strip) and by `validatePluginDir` (the author-time warning), so the
+ *  two can never drift — never re-word it in a second place. */
+export const ASK_NEEDS_API_4 = `ask forms need plugin API ${WORCA_ASK_FORMS_API}`
+  + ' (declare "engines": { "worca-cc-api": ">=4 <5" }) — the ask block is ignored and the agent keeps generic questions';
+
 /** The host API a range was BUILT FOR: the lowest integer it accepts. ">=1 <2"
  *  and "1" both answer 1; an unconstrained range answers 0; null when nothing
  *  satisfies it (an unparseable range fails closed in apiSatisfies too).
@@ -128,6 +159,7 @@ export function declaredApi(range) {
 export function dataContractIssues(absDir) {
   const agentsV1 = [];
   const workflowsV1 = [];
+  const scriptsV1 = [];
   const read = (p) => { try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return null; } };
   const agentsDir = join(absDir, 'agents');
   if (existsSync(agentsDir)) {
@@ -136,6 +168,13 @@ export function dataContractIssues(absDir) {
       if (raw && Number(raw.metaVersion) !== 2) agentsV1.push(f);
     }
   }
+  const scDir = join(absDir, 'scripts');
+  if (existsSync(scDir)) {
+    for (const f of readdirSync(scDir).filter((x) => x.endsWith('.meta.json')).sort()) {
+      const raw = read(join(scDir, f));
+      if (raw && Number(raw.metaVersion) !== 2) scriptsV1.push(f);
+    }
+  }
   const wfDir = join(absDir, 'workflows');
   if (existsSync(wfDir)) {
     for (const f of readdirSync(wfDir).filter((x) => x.endsWith('.json')).sort()) {
@@ -143,7 +182,7 @@ export function dataContractIssues(absDir) {
       if (raw && Number(raw.version) !== 2) workflowsV1.push(f);
     }
   }
-  return { agentsV1, workflowsV1 };
+  return { agentsV1, workflowsV1, scriptsV1 };
 }
 
 /**
@@ -159,10 +198,11 @@ export function dataContractIssues(absDir) {
 export function apiMismatch(range, issues) {
   const agents = (issues && issues.agentsV1 ? issues.agentsV1 : []).length;
   const workflows = (issues && issues.workflowsV1 ? issues.workflowsV1 : []).length;
-  if (!agents && !workflows) return null;
+  const scripts = (issues && issues.scriptsV1 ? issues.scriptsV1 : []).length;
+  if (!agents && !workflows && !scripts) return null;
   // declaredApi('') is 0 (an unconstrained range accepts everything); report that
   // as null so the message reads "built for an older version", never "API 0".
-  const mismatch = { builtFor: declaredApi(range) || null, host: WORCA_PLUGIN_API, agents, workflows };
+  const mismatch = { builtFor: declaredApi(range) || null, host: WORCA_PLUGIN_API, agents, workflows, ...(scripts ? { scripts } : {}) };
   mismatch.message = apiMismatchMessage(mismatch);
   return mismatch;
 }
@@ -176,10 +216,10 @@ export function apiMismatch(range, issues) {
  */
 export function apiMismatchMessage(mismatch) {
   if (!mismatch) return '';
-  const { builtFor, agents, workflows } = mismatch;
+  const { builtFor, agents, workflows, scripts } = mismatch;
   return `built for plugin API ${builtFor ?? 'an older version'}; this version of worca requires `
-    + `plugin API ${WORCA_PLUGIN_API} for agents and pipeline templates — update or reinstall the plugin `
-    + `(${agents} agent(s), ${workflows} template(s) ignored)`;
+    + `plugin API ${WORCA_AGENT_DATA_API} for agents and pipeline templates — update or reinstall the plugin `
+    + `(${agents} agent(s), ${scripts ? `${scripts} script(s), ` : ''}${workflows} template(s) ignored)`;
 }
 
 const str = (v, d = '') => (typeof v === 'string' ? v.trim() : d);
@@ -467,11 +507,28 @@ export function normalizeManifest(raw, { dir = '' } = {}) {
         errors.push(`${at} ("${id}"): ${e.message}`);
         return;
       }
+      // A bridged model (model-bridge-design.md §6.4): same shape and validator
+      // as a global entry. A plugin cannot ship provider credentials — a
+      // `copilot` entry resolves against the user's own sign-in, and an
+      // `openai`/`anthropic` apiKey may only be a ${VAR} ref, never a literal.
+      let upstream;
+      try {
+        upstream = assertModelUpstream(m.upstream);
+        if (upstream && upstream.apiKey && !/^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/.test(upstream.apiKey)) {
+          throw new Error('upstream.apiKey in a plugin must be a ${VAR} reference, never a literal key');
+        }
+        const clash = upstream ? upstreamEnvConflict(env) : null;
+        if (clash) { warnings.push(`${at} ("${id}"): env key ${JSON.stringify(clash)} is set by the bridge for an upstream entry — ignored`); delete env[clash]; }
+      } catch (e) {
+        errors.push(`${at} ("${id}"): ${e.message}`);
+        return;
+      }
       models.push({
         id, label: str(m.label) || id,
         efforts: efforts.length ? efforts : [...EFFORTS],
         ...(Object.keys(env).length ? { env } : {}),
         ...(cost ? { cost } : {}),
+        ...(upstream ? { upstream } : {}),
       });
     });
     const mids = models.map((m) => m.id.toLowerCase());
@@ -569,13 +626,13 @@ export function validatePluginDir(absDir, { strict = false, builtinMetas } = {})
   // "this plugin does not ship it" or the derived V4/V5/V20/V21 cascade.
   const ungatedKeys = new Set();
   const ownMetas = [];
-  // A range that admits the CURRENT API (or no engines at all) claims to be an
-  // API-3 plugin, so v1-shaped data is a hard error; --strict promotes it for
-  // everyone else, because that flag is the plugin AUTHOR's gate. A manifest
-  // that did not PARSE fails SOFT: its declared API is unknowable, and the JSON
-  // error above is already the only actionable line.
+  // A range that admits the DATA-CONTRACT API (or no engines at all) claims to
+  // ship meta v2 sidecars and v2 graphs, so v1-shaped data is a hard error;
+  // --strict promotes it for everyone else, because that flag is the plugin
+  // AUTHOR's gate. Compared against WORCA_AGENT_DATA_API, never the newest host
+  // API: an API-5 host must not make today's ">=3 <4" plugins soft again.
   const hardData = raw !== null
-    && (strict || negotiatedApi(raw && raw.engines ? raw.engines['worca-cc-api'] : '') === WORCA_PLUGIN_API);
+    && (strict || (negotiatedApi(raw && raw.engines ? raw.engines['worca-cc-api'] : '') ?? -1) >= WORCA_AGENT_DATA_API);
   const dataLevel = hardData ? 'error' : 'warn';
   const agentsDir = join(absDir, 'agents');
   if (existsSync(agentsDir)) {
@@ -602,6 +659,51 @@ export function validatePluginDir(absDir, { strict = false, builtinMetas } = {})
       // as shipped is what let a ports-less node reach validateGraph.
       agentKeys.add(key);
       ownMetas.push(normalizeAgentMeta(meta).meta);
+
+      // ── ask forms (spec §10) ────────────────────────────────────────────────
+      // The SAME gate 1 the registry, the agent store and the Agents view run.
+      // Level: a bad form is a WARNING, because the host's behaviour for one is
+      // already defined (it is dropped at load and the agent keeps generic
+      // questions), and a plugin whose connector is fine must stay installable.
+      // --strict is the AUTHOR's gate, so there it is an error. This split is
+      // keyed on `strict` alone, NOT on dataLevel: a form's validity has nothing
+      // to do with which API the plugin negotiates.
+      if (meta.ask !== undefined && meta.ask !== null) {
+        const askLevel = strict ? 'error' : 'warn';
+        // normalizeAskBlock is used ONLY for what it alone knows: a whole-block
+        // refusal (id '*'). Its per-form `reason` is a collapsed one-liner of the
+        // first three errors — right for a registry log line, wrong here, where
+        // the author wants every failed rule with its path. So each form goes
+        // through validateFormDef directly.
+        const blockDrops = normalizeAskBlock(meta.ask).dropped.filter((d) => d.id === '*');
+        let declaredForms = 0;
+        if (blockDrops.length) {
+          for (const d of blockDrops) push(askLevel, `agents/${f}: ask: ${d.reason}`);
+        } else {
+          const declared = meta.ask.forms && typeof meta.ask.forms === 'object' ? meta.ask.forms : {};
+          const ids = Object.keys(declared);
+          declaredForms = ids.length;
+          if (ids.length > ASK_LIMITS.formsPerAgent) {
+            push(askLevel, `agents/${f}: ask.forms: at most ${ASK_LIMITS.formsPerAgent} forms per agent`);
+          }
+          for (const id of ids) {
+            // P1 addresses layout items as `layout#<n>` (depth-first, 1-based);
+            // print the path exactly as it comes so the Plugins card, the 422
+            // body and this line all name the same item.
+            for (const e of validateFormDef(declared[id], { id }).errors) {
+              push(askLevel, `agents/${f}: ask.forms."${id}"${e.path ? ` ${e.path}` : ''}: ${e.message}`);
+            }
+          }
+        }
+        // A plugin may ship forms it knows an older host will ignore; say so
+        // once, by name, and never fail the validate for it. ONE sentence,
+        // exported so the load-time strip and this line can never drift. Only
+        // when the block DECLARES a form: an empty `forms` map loads as "no
+        // forms" (normalizeAgentMeta drops it) and the host ignores nothing.
+        if (declaredForms && !(Number(negotiatedApi(raw && raw.engines ? raw.engines['worca-cc-api'] : '')) >= WORCA_ASK_FORMS_API)) {
+          push('warn', `agents/${f}: ${ASK_NEEDS_API_4}`);
+        }
+      }
     }
     for (const f of files.filter((x) => x.endsWith('.md'))) {
       const stem = f.slice(0, -3);
@@ -611,6 +713,61 @@ export function validatePluginDir(absDir, { strict = false, builtinMetas } = {})
     }
   }
 
+  // scripts/: <key>.meta.json + the program it names (spec §9.3). The SAME meta
+  // v2 gate the registry loader applies, every failed rule named; every platform
+  // entry of `file` must exist inside scripts/ and never escape it.
+  const scriptKeys = new Set();
+  const ungatedScriptKeys = new Set();
+  const ownScriptMetas = [];
+  const scriptsDir = join(absDir, 'scripts');
+  if (existsSync(scriptsDir)) {
+    const files = readdirSync(scriptsDir);
+    for (const f of files.filter((x) => x.endsWith('.meta.json'))) {
+      const stem = f.slice(0, -'.meta.json'.length);
+      let meta = null;
+      try { meta = JSON.parse(readFileSync(join(scriptsDir, f), 'utf8')); }
+      catch { push('error', `scripts/${f}: invalid JSON`); continue; }
+      const key = typeof meta?.key === 'string' ? meta.key : '';
+      if (!KEY_RE.test(key)) { push('error', `scripts/${f}: "${key}" must be a valid script key (letters/digits/_-)`); continue; }
+      if (key !== stem) push('error', `scripts/${f}: key "${key}" must match the filename stem "${stem}"`);
+      if (Number(meta.metaVersion) !== 2) { push(dataLevel, `scripts/${f}: ${NOT_META_V2}`); ungatedScriptKeys.add(key); continue; }
+      const { errors } = validateScriptMetaV2(meta);
+      for (const e of errors) push('error', `scripts/${f}: ${e}`);
+      if (errors.length) { ungatedScriptKeys.add(key); continue; }
+      const norm = normalizeScriptMeta(meta).meta;
+      // Every platform's program must be a contained, existing file.
+      const entries = typeof norm.file === 'string' ? [norm.file] : norm.file ? Object.values(norm.file) : [];
+      let fileOk = true;
+      for (const rel of entries) {
+        if (isAbsolute(rel) || /[\\/]/.test(rel) || rel.includes('..') || !resolve(scriptsDir, rel).startsWith(resolve(scriptsDir) + sep)) {
+          push('error', `scripts/${f}: file must be a plain basename inside scripts/ (got "${rel}")`); fileOk = false; continue;
+        }
+        if (!existsSync(join(scriptsDir, rel))) { push('error', `scripts/${f}: file "${rel}" not found in scripts/`); fileOk = false; }
+      }
+      if (!fileOk) { ungatedScriptKeys.add(key); continue; }
+      scriptKeys.add(key);
+      ownScriptMetas.push(norm);
+      // <key>.tests.json is optional; when it ships it goes through the SAME
+      // normalizer the store, the bench and the UI use, as a SHIPPED set — a
+      // case that names a project folder cannot travel to a recipient (W9).
+      const casesFile = join(scriptsDir, `${key}.tests.json`);
+      if (existsSync(casesFile)) {
+        let rawCases = null;
+        try { rawCases = JSON.parse(readFileSync(casesFile, 'utf8')); }
+        catch { push('error', `scripts/${key}.tests.json: invalid JSON`); continue; }
+        for (const e of normalizeCases(rawCases, norm, { shipped: true }).errors) {
+          push('error', `scripts/${key}.tests.json: ${e}`);
+        }
+      }
+    }
+    // A tests file with no sidecar beside it: the W18 overlay is a USER-layer
+    // idea, so inside a plugin it is a file nothing will ever read.
+    for (const f of files.filter((x) => x.endsWith('.tests.json'))) {
+      const stem = f.slice(0, -'.tests.json'.length);
+      if (!files.includes(`${stem}.meta.json`)) push('error', `scripts/${f}: no ${stem}.meta.json beside it`);
+    }
+  }
+
   // skills/<name>/SKILL.md required (rides the existing injection mechanism, §9.2)
   const skillsDir = join(absDir, 'skills');
   if (existsSync(skillsDir)) {
@@ -634,16 +791,19 @@ export function validatePluginDir(absDir, { strict = false, builtinMetas } = {})
   if (existsSync(wfDir)) {
     const hostMetas = Array.isArray(builtinMetas) ? builtinMetas : builtinAgentMetas();
     const hostKeys = new Set(hostMetas.map((m) => m.key));
-    const portsFn = portsFnFor(indexByKey([...hostMetas, ...ownMetas]));
+    const hostScriptMetas = builtinScriptMetas();
+    const hostScriptKeys = new Set(hostScriptMetas.map((m) => m.key));
+    const portsFn = portsFnFor(indexByKey([...hostMetas, ...ownMetas]), indexByKey([...hostScriptMetas, ...ownScriptMetas]));
     for (const f of readdirSync(wfDir).filter((x) => x.endsWith('.json'))) {
       let tpl = null;
       try { tpl = JSON.parse(readFileSync(join(wfDir, f), 'utf8')); }
       catch { push('error', `workflows/${f}: invalid JSON`); continue; }
       if (Number(tpl?.version) !== 2) { push(dataLevel, `workflows/${f}: ${NOT_GRAPH_V2}`); continue; }
       const nodes = Array.isArray(tpl.nodes) ? tpl.nodes : [];
-      const keys = nodes.filter((n) => n && n.kind === 'agent').map((n) => n.key).filter(Boolean);
+      const agentRefs = nodes.filter((n) => n && n.kind === 'agent').map((n) => n.key).filter(Boolean);
+      const scriptRefs = nodes.filter((n) => n && n.kind === 'script').map((n) => n.key).filter(Boolean);
       let unresolved = false;
-      for (const k of new Set(keys)) {
+      for (const k of new Set(agentRefs)) {
         if (agentKeys.has(k) || hostKeys.has(k)) continue;
         if (ungatedKeys.has(k)) {
           // The sidecar is this plugin's, it just did not pass. Report at the
@@ -655,6 +815,12 @@ export function validatePluginDir(absDir, { strict = false, builtinMetas } = {})
         }
         unresolved = true;
       }
+      for (const k of new Set(scriptRefs)) {
+        if (scriptKeys.has(k) || hostScriptKeys.has(k)) continue;
+        if (ungatedScriptKeys.has(k)) push(dataLevel, `workflows/${f}: references script key "${k}" whose sidecar is not a valid meta v2 sidecar`);
+        else push('error', `workflows/${f}: references script key "${k}" which is neither a built-in nor shipped by this plugin`);
+        unresolved = true;
+      }
       // An unresolved key has no ports, so every wire touching it would also
       // fire V4/V5 — one clear cause beats five derived ones.
       if (unresolved) continue;

package/src/core/plugin-models.mjs

@@ -50,6 +50,7 @@ export function allPluginModels() {
         plugin: name, id: m.id, label: m.label, efforts: [...m.efforts],
         ...(m.env ? { env: m.env } : {}),
         ...(m.cost ? { cost: m.cost } : {}),   // manifest-pinned pricing (config.mjs modelCostConfig)
+        ...(m.upstream ? { upstream: m.upstream } : {}),   // bridged entry (bridge/registry.mjs)
         secrets: [...new Set(secrets)],
       });
     }

package/src/core/plugin-script-cases.mjs

@@ -0,0 +1,118 @@
+// src/core/plugin-script-cases.mjs
+// `worca plugin validate <dir> --run-cases` (spec §8.1): run every case a plugin
+// dir SHIPS through the one bench the app and the CLI use, against the dir's own
+// scripts and a scratch cwd. Deliberately NOT inside plugin-manifest.mjs:
+// validatePluginDir is the cheap synchronous gate every install path calls, and
+// it must never spawn a child process.
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { loadScriptRegistry } from './script-registry.mjs';
+import { runBenchOnce } from './script-bench.mjs';
+import { normalizeCases, evaluateExpect } from '../shared/graph/script-cases.mjs';
+
+/** One case through the bench: the dir's registry, a scratch cwd, always. */
+async function runOneCase(key, kase, registry, deps) {
+  const request = {
+    key,
+    params: kase.params || {},
+    inputs: kase.inputs || {},
+    cwd: { kind: 'scratch' },
+    ...(kase.ports ? { ports: kase.ports } : {}),
+    ...(kase.timeoutMs ? { timeoutMs: kase.timeoutMs } : {}),
+  };
+  const benchDeps = { registry, agentKeys: [] };
+  // The caller's hooks, per case: the live bench (so a signal can stop the child
+  // tree) and the streamed lines, tagged with the script the case belongs to.
+  if (typeof deps.onBench === 'function') benchDeps.onBench = deps.onBench;
+  if (typeof deps.onLine === 'function') {
+    benchDeps.onLine = (ev) => deps.onLine({ key, caseId: kase.id, stream: ev && ev.stream, text: ev && ev.text });
+  }
+  if (deps.runner) benchDeps.runner = deps.runner;
+  if (deps.home) benchDeps.home = deps.home;
+  if (deps.platform) benchDeps.platform = deps.platform;
+  try {
+    return await runBenchOnce(request, benchDeps);
+  } catch (e) {
+    // A transport-level refusal (a bad request, the bench cap) IS this case's
+    // result: --run-cases reports per case and never throws at the caller.
+    return {
+      status: 'error', exitCode: null, runtime: null, durationMs: 0, summary: '', warnings: [],
+      fired: [], outputs: {}, verdict: null, envelopePath: null,
+      error: { message: e && e.message ? e.message : String(e), tail: [] },
+      expect: null, draft: false,
+    };
+  }
+}
+
+/**
+ * Run every shipped case of every script under `<absDir>/scripts`.
+ * @param {string} absDir the plugin folder
+ * @param {{runner?: Function, home?: string, platform?: string,
+ *   onBench?: (bench: object) => void,
+ *   onLine?: (ev: {key: string, caseId: string, stream: string, text: string}) => void,
+ *   stopRequested?: () => boolean}} [deps]
+ *   onBench receives each case's live bench (call `stop()` on it); stopRequested is
+ *   asked before every case. A STOPPED case fails and ends the batch: `stopped` is
+ *   true and the cases not reached are absent from the rows.
+ * @returns {Promise<{scripts: Array<{key: string, runtime: string, cases: Array<{
+ *   caseId: string, name: string, status: string, checked: boolean, pass: boolean,
+ *   diffs: string[], durationMs: number}>}>, passed: number, failed: number,
+ *   unchecked: number, stopped: boolean, problems: string[]}>}
+ */
+export async function runPluginScriptCases(absDir, deps = {}) {
+  const dir = join(absDir, 'scripts');
+  const out = { scripts: [], passed: 0, failed: 0, unchecked: 0, stopped: false, problems: [] };
+  const stopRequested = typeof deps.stopRequested === 'function' ? deps.stopRequested : () => false;
+  if (!existsSync(dir)) return out;
+  // The plugin dir IS the registry for this run: its scripts load as the only
+  // layer. agentKeys is empty on purpose — D16 drops a script whose key a HOST
+  // agent holds, which says nothing about a folder that is only being linted.
+  const registry = loadScriptRegistry({
+    scriptsDir: dir, userScriptsDir: null, includePlugins: false, agentKeys: [],
+  });
+  for (const f of readdirSync(dir).filter((x) => x.endsWith('.meta.json')).sort()) {
+    const key = f.slice(0, -'.meta.json'.length);
+    const meta = registry[key];
+    if (!meta) continue;                                  // validatePluginDir already named it
+    const casesFile = join(dir, `${key}.tests.json`);
+    if (!existsSync(casesFile)) continue;
+    let raw = null;
+    try { raw = JSON.parse(readFileSync(casesFile, 'utf8')); }
+    catch (e) { out.problems.push(`scripts/${key}.tests.json: invalid JSON (${e.message})`); continue; }
+    const { cases, errors } = normalizeCases(raw, meta, { shipped: true });
+    for (const e of errors) out.problems.push(`scripts/${key}.tests.json: ${e}`);
+    if (!cases.length) continue;
+    const row = { key, runtime: meta.runtime, cases: [] };
+    for (const kase of cases) {
+      if (stopRequested()) { out.stopped = true; break; }
+      const result = await runOneCase(key, kase, registry, deps);
+      const ev = evaluateExpect(kase.expect, result);
+      const checked = !!ev;
+      // `stopped` verified nothing either: it fails, and it ends the batch below.
+      const broke = result.status === 'error' || result.status === 'timeout' || result.status === 'stopped';
+      // An UNCHECKED case that could not run is still a failure: a shipped
+      // script that throws is broken whether or not it declared an expectation.
+      // A STOPPED case never passes, checked or not: an expectation that names no
+      // verdict (`{ fired: [] }`) is SATISFIED by a run that was cut short.
+      const stopped = result.status === 'stopped';
+      const pass = !stopped && (checked ? ev.pass : !broke);
+      // WHY it broke rides along either way: "expected clean, got error" alone sends
+      // the author to the bench to learn that python is missing on the CI host.
+      const why = broke ? [result.error ? result.error.message : result.status] : [];
+      const diffs = checked ? [...ev.diffs, ...(ev.pass && !stopped ? [] : why)] : why;
+      if (!pass) out.failed += 1;
+      else if (checked) out.passed += 1;
+      else out.unchecked += 1;
+      row.cases.push({
+        caseId: kase.id, name: kase.name, status: result.status,
+        checked, pass, diffs, durationMs: result.durationMs || 0,
+      });
+      if (result.status === 'stopped') { out.stopped = true; break; }
+    }
+    if (row.cases.length) out.scripts.push(row);
+    if (out.stopped) break;
+  }
+  return out;
+}