@worca/app 1.3.0 → 1.4.0

package/src/core/stats.mjs

@@ -16,6 +16,8 @@ import {
   budgetStatus, costWindowStart, costWindowEnd, allTimeTotals, roundUsd,
   askWindowedSpendUsd,
 } from './cost-budget.mjs';
+import { savedUsd } from '../shared/human-estimate.mjs';
+import { effectiveHumanRateUsd } from './human-rate.mjs';
 
 const RANGES = ['today', 'week', 'month', 'all'];
 
@@ -33,7 +35,8 @@ const TOTALS_SELECT = `
       COALESCE(SUM(pr_url IS NOT NULL), 0)                                   AS prsOpened,
       COALESCE(SUM(pr_state = 'MERGED'), 0)                                  AS prsMerged,
       COALESCE(SUM(CASE WHEN p.total_cost_usd  > 0 THEN p.total_cost_usd  ELSE COALESCE(s.sc, 0) END), 0) AS spend,
-      COALESCE(SUM(CASE WHEN p.total_active_ms > 0 THEN p.total_active_ms ELSE COALESCE(s.sa, 0) END), 0) AS active
+      COALESCE(SUM(CASE WHEN p.total_active_ms > 0 THEN p.total_active_ms ELSE COALESCE(s.sa, 0) END), 0) AS active,
+      COALESCE(SUM(p.human_hours), 0) AS humanHours
     FROM pipelines p
     LEFT JOIN (SELECT pipeline_id, SUM(cost_usd) sc, SUM(active_ms) sa
                FROM pipeline_steps GROUP BY pipeline_id) s ON s.pipeline_id = p.id`;
@@ -46,6 +49,7 @@ function totalsRow(sql, isoA, isoB) {
     prsOpened: row.prsOpened, prsMerged: row.prsMerged,
     workedMs: Number(row.active || 0),
     cohortSpendUsd: roundUsd(row.spend || 0),
+    humanHours: Math.round(Number(row.humanHours || 0) * 100) / 100,
   };
 }
 
@@ -97,6 +101,28 @@ function askTotals(fromMs, toMs) {
   return { spendUsd: roundUsd(row?.s || 0), sessions: row?.sessions || 0, turns: row?.turns || 0 };
 }
 
+/** "Saved this month/week" for the sidebar spend indicator (money-saved design §10): human
+ *  hours × rate − spent over the budget's own reset window. The same cohort (runs STARTED in
+ *  [windowStartMs, windowEndMs), archived included), the same rate and the same spend as the
+ *  Statistics "Saved" tile for the matching range, so the sidebar and the tile never disagree.
+ *  A lean SUM rather than cohortTotals(): /api/budget is refetched on every tick while runs
+ *  are live, and the pipeline_steps join TOTALS_SELECT carries is dead weight for one column.
+ *  @param {{windowStartMs:number, windowEndMs:number, windowSpendUsd:number}} budget  budgetStatus()
+ *  @returns {{windowHumanHours:number, windowSavedUsd:number}} */
+export function budgetWindowSavings(budget) {
+  const row = prepare(`
+    SELECT COALESCE(SUM(p.human_hours), 0) AS humanHours
+    FROM pipelines p
+    WHERE COALESCE(p.started_at, p.updated_at) >= ?
+      AND COALESCE(p.started_at, p.updated_at) <  ?`)
+    .get(new Date(budget.windowStartMs).toISOString(), new Date(budget.windowEndMs).toISOString());
+  const windowHumanHours = Math.round(Number(row?.humanHours || 0) * 100) / 100;
+  return {
+    windowHumanHours,
+    windowSavedUsd: savedUsd(windowHumanHours, effectiveHumanRateUsd(), budget.windowSpendUsd),
+  };
+}
+
 /** Build zero-filled buckets [{startMs, endMs}] from windowStart through `now`. */
 function buildBuckets(windowStart, now, bucket) {
   const out = [];
@@ -122,6 +148,7 @@ function buildBuckets(windowStart, now, bucket) {
 export function getStats({ range = 'month', now = new Date() } = {}) {
   if (!RANGES.includes(range)) throw new RangeError(`unknown stats range: ${range}`);
   const budget = budgetStatus(now);
+  const rate = effectiveHumanRateUsd();
 
   let windowStart, windowEnd, prevStart, prevEnd, bucket;
   if (range === 'today') {
@@ -155,6 +182,8 @@ export function getStats({ range = 'month', now = new Date() } = {}) {
     return {
       spentUsd: roundUsd(pipelineSpendUsd + ask.spendUsd),
       pipelineSpendUsd, ask,
+      humanHours: c.humanHours,
+      savedUsd: savedUsd(c.humanHours, rate, roundUsd(pipelineSpendUsd + ask.spendUsd)),
       workedMs: c.workedMs,
       runs: c.runs, finished: c.finished, stopped: c.stopped, failed: c.failed,
       paused: c.paused, running: c.running,
@@ -170,6 +199,8 @@ export function getStats({ range = 'month', now = new Date() } = {}) {
     totals = {
       spentUsd: roundUsd(at.spendUsd + ask.spendUsd),
       pipelineSpendUsd: at.spendUsd, ask,
+      humanHours: at.humanHours,
+      savedUsd: savedUsd(at.humanHours, rate, roundUsd(at.spendUsd + ask.spendUsd)),
       workedMs: at.activeMs,
       runs: c.runs, finished: c.finished, stopped: c.stopped, failed: c.failed,
       paused: c.paused, running: c.running,
@@ -196,6 +227,6 @@ export function getStats({ range = 'month', now = new Date() } = {}) {
   return {
     range, bucket,
     windowStartMs: windowStart.getTime(), windowEndMs: windowEnd.getTime(),
-    totals, prev, budget, series,
+    totals, prev, budget, series, humanRateUsd: rate,
   };
 }

package/src/core/workflow-export.mjs

@@ -23,6 +23,8 @@ import { registryPortsFn } from './graph/registry-ports.mjs';
 import { validateGraph, formatIssue } from '../shared/graph/validate.mjs';
 import { EFFORTS as EFFORT_LIST } from './model-env.mjs';
 import { loadAgentRegistry } from './agent-registry.mjs';
+import { loadScriptRegistry } from './script-registry.mjs';
+import { normalizeCases, CASES_VERSION } from '../shared/graph/script-cases.mjs';
 import { slugify } from './artifacts.mjs';
 import { isValidSkillName, collectRequiredSkills, resolveSkill, pluginSkillDirs } from './skills.mjs';
 import { normalizeProjectPath } from './projects.mjs';
@@ -396,6 +398,15 @@ async function buildExportSet({ workflowId, destination, projectDir, slug, inclu
   //    its consumes/produces (derived from ports + wires, §2). Flow cards (task/end/
   //    and/or/combine) are NOT dispatched — only agent nodes become steps.
   const graph = await resolveGraph(destination === 'project' ? projectDir : null, workflowId, registry);
+  // D19: the exported skill tree simulates the graph in Claude Code; a child-process
+  // card has no rendering there yet. Refuse loudly rather than export a skill that
+  // silently skips the gate.
+  const scriptNodes = (graph.template.nodes || []).filter((n) => n && n.kind === 'script');
+  if (scriptNodes.length) {
+    const names = scriptNodes.map((n) => `${graph.nodes[n.id]?.meta?.displayName || n.key} (${n.id})`);
+    throw Object.assign(err(`export to Claude Code does not carry script cards yet: ${names.join(', ')}`, 'UNSUPPORTED'),
+      { nodes: scriptNodes.map((n) => n.id) });
+  }
   const manifest = buildGraphManifest(graph.template, graph.agentsByKey,
     { overlays: { nodes: graph.nodes, wires: graph.wires } });
   const tnodeById = new Map((graph.template.nodes || []).map((n) => [n.id, n]));
@@ -431,6 +442,18 @@ async function buildExportSet({ workflowId, destination, projectDir, slug, inclu
       const declared = Array.isArray(node.tools) ? node.tools : [];
       const stripped = declared.filter((t) => STRIPPED_TOOLS.has(t) && t !== 'AskUserQuestion');
       if (stripped.length) warnings.push(`node "${node.key}": dropped subagent-incompatible tool(s): ${stripped.join(', ')}`);
+      // Ask forms (spec §8) do not travel: a Claude Code subagent has no worca form
+      // host, so the exported agent falls back to generic questions — which it
+      // already does structurally (makeAgentMd emits frontmatter + the markdown BODY
+      // and never reads the sidecar the `ask` block lives in). Say so, or an author
+      // ships a workflow believing their form travelled with it. The PLUGIN export
+      // is different on purpose: it copies the sidecar byte-identically, because a
+      // plugin is re-imported into worca where forms work.
+      const formIds = Object.keys((registry[node.key] && registry[node.key].ask && registry[node.key].ask.forms) || {});
+      if (formIds.length) {
+        warnings.push(`node "${node.key}": ask form(s) ${formIds.join(', ')} are not exported — `
+          + 'a console subagent has no worca form host and falls back to generic questions.');
+      }
     }
   }
 
@@ -1052,7 +1075,8 @@ export async function exportWorkflowPlugin({ workflowId, targetDir, pluginName,
   // ── The stored graph must be runnable HERE before it is shared: a stranded
   //    key (deleted agent) would only surface at the recipient's link.
   const registry = loadAgentRegistry();
-  const { errors } = validateGraph({ ...payload, id: tpl.id }, registryPortsFn(registry));
+  const scripts = loadScriptRegistry({ agentKeys: Object.keys(registry) });
+  const { errors } = validateGraph({ ...payload, id: tpl.id }, registryPortsFn(registry, scripts));
   if (errors.length) {
     const summary = summarizeUnknownAgents(errors);
     throw Object.assign(
@@ -1081,6 +1105,27 @@ export async function exportWorkflowPlugin({ workflowId, targetDir, pluginName,
   }
   if (builtins.length) warnings.push(`built-in agent(s) not bundled (present on every Worca host): ${builtins.join(', ')}`);
 
+  // ── Scripts: user-owned are bundled, built-ins never, another plugin's
+  //    refused — the same ownership rule the agents block above applies (§8.3).
+  const scriptKeys = [...new Set(payload.nodes.filter((n) => n && n.kind === 'script' && n.key).map((n) => n.key))].sort();
+  const userScripts = [];
+  const foreignScripts = [];
+  const builtinScripts = [];
+  for (const key of scriptKeys) {
+    const meta = scripts[key];
+    if (!meta) continue;                                          // validateGraph refused above
+    const origin = String(meta.origin || '');
+    if (origin === 'builtin') builtinScripts.push(key);
+    else if (origin.startsWith('plugin:')) foreignScripts.push({ key, plugin: origin.slice('plugin:'.length) });
+    else userScripts.push({ key, meta });
+  }
+  if (foreignScripts.length) {
+    const list = foreignScripts.map((f) => `"${f.key}" (owned by plugin "${f.plugin}")`).join(', ');
+    throw err(`cannot bundle ${list} — a shared workflow bundles only your own scripts; `
+      + 'the recipient installs that plugin alongside, or you duplicate the script under your own name', 'UNSUPPORTED');
+  }
+  if (builtinScripts.length) warnings.push(`built-in script(s) not bundled (present on every worca host): ${builtinScripts.join(', ')}`);
+
   // ── Skills the bundled agents require: filled from global/project/other-plugin
   //    sources; a Worca-shipped (bundle) skill is skipped, like a built-in agent.
   const depSkills = resolveDepSkills(registry, userAgents.map((a) => a.key), dir, 'plugin', null, repoRoot,
@@ -1100,6 +1145,51 @@ export async function exportWorkflowPlugin({ workflowId, targetDir, pluginName,
     targets.push({ path: join(dir, 'agents', `${key}.md`), text: await readFile(mdPath, 'utf8') });
     targets.push({ path: join(dir, 'agents', `${key}.meta.json`), text: await readFile(sidecarPath, 'utf8') });
   }
+  // Scripts ride like agents: byte-identical sidecar + program. EVERY platform
+  // entry of `file` travels, host platform irrelevant — the recipient may be on
+  // Windows and need the .cmd half (spec §10).
+  const bundledScripts = [];
+  for (const { key, meta } of userScripts) {
+    const srcDir = meta.scriptsDir || (meta.scriptPath ? dirname(meta.scriptPath) : null);
+    const sidecar = srcDir ? join(srcDir, `${key}.meta.json`) : null;
+    if (!sidecar || !existsSync(sidecar)) throw err(`script sidecar not found for "${key}" (${sidecar || key})`, 'NOT_FOUND');
+    targets.push({ path: join(dir, 'scripts', `${key}.meta.json`), text: await readFile(sidecar, 'utf8') });
+    const rels = [...new Set((typeof meta.file === 'string' ? [meta.file] : Object.values(meta.file || {})).filter(Boolean))];
+    for (const rel of rels) {
+      const from = join(srcDir, rel);
+      if (!existsSync(from)) throw err(`script source not found for "${key}" (${from})`, 'NOT_FOUND');
+      targets.push({ path: join(dir, 'scripts', rel), text: await readFile(from, 'utf8') });
+    }
+    // Cases travel too, minus any that name a project folder: a scratch case is
+    // the only kind the recipient can run (W9, §8.3).
+    const casesPath = join(srcDir, `${key}.tests.json`);
+    const casesTarget = join(dir, 'scripts', `${key}.tests.json`);
+    let scratchCases = [];
+    if (existsSync(casesPath)) {
+      let raw = null;
+      try { raw = JSON.parse(await readFile(casesPath, 'utf8')); }
+      catch (e) { warnings.push(`script "${key}" cases: ${e.message}`); }
+      const { cases, errors } = normalizeCases(raw, meta);
+      for (const e of errors) warnings.push(`script "${key}" cases: ${e}`);
+      scratchCases = cases.filter((k) => k.cwd && k.cwd.kind === 'scratch');
+      const dropped = cases.length - scratchCases.length;
+      if (dropped) {
+        warnings.push(`script "${key}": ${dropped} test case(s) that run in a project folder were not bundled `
+          + '— a shared case runs in a scratch folder');
+      }
+    }
+    // The shipped set FOLLOWS the author's: a file an earlier export wrote is
+    // overwritten even with the empty set (the exporter never deletes), so a case
+    // the author removed — or one a port edit made invalid, which would fail the
+    // folder's own validation — does not live on in the plugin.
+    if (scratchCases.length || existsSync(casesTarget)) {
+      targets.push({
+        path: casesTarget,
+        text: JSON.stringify({ version: CASES_VERSION, cases: scratchCases }, null, 2) + '\n',
+      });
+    }
+    bundledScripts.push({ key, runtime: meta.runtime, files: [`${key}.meta.json`, ...rels] });
+  }
   for (const s of depSkills) {
     const skillMd = join(dir, 'skills', s.skill, 'SKILL.md');
     if (s.skipped) skipped.push({ path: skillMd, reason: `skill "${s.skill}" ships with Worca (${s.resolvedFrom}) — not bundled` });
@@ -1124,7 +1214,7 @@ export async function exportWorkflowPlugin({ workflowId, targetDir, pluginName,
   const manifest = existing ? { ...existing } : {
     name, version: '0.1.0',
     description: `Workflows shared from Worca — ${tpl.name}`,
-    engines: { 'worca-cc-api': '>=3 <4' },
+    engines: { 'worca-cc-api': '>=4 <5' },
   };
   if (!manifest.name) manifest.name = name;
   let version = typeof manifest.version === 'string' ? manifest.version : '';
@@ -1149,7 +1239,8 @@ export async function exportWorkflowPlugin({ workflowId, targetDir, pluginName,
 
   const plan = {
     dir, name, slug, version: manifest.version || null,
-    created, updated, noop, skipped, conflicts: [], warnings, orphans: [], written: [], validation: null,
+    created, updated, noop, skipped, conflicts: [], warnings, orphans: [], written: [],
+    scripts: bundledScripts, validation: null,
   };
   if (dryRun) return plan;
 

package/src/core/workflow-share.mjs

@@ -9,17 +9,21 @@
 //   exportGraphJson(id)                -> { version:2, name, domain, nodes, wires, canvas? }
 //   saveGraphWorkflow(body)            -> composer semantics: keeps a legal `id`, 409 on a minted collision
 //   importGraphWorkflow(body, opts)    -> import semantics: id/origin ignored, name suffixed on collision
+//   listScriptNodes(graph, scripts)    -> the command/code values an import must show first (D18)
+//   formatScriptNodes(list)            -> SCRIPT_IMPORT_NOTICE + those values, for the CLI
 //   nodeDefaultsError(raw, models, at) -> '' | reason  (per-node tunables vs the project-less catalog)
 //
 // Errors carry `.code` so surfaces map them to HTTP / exit codes:
 //   BAD_REQUEST | INVALID_GRAPH (+ .errors/.warnings/.summary) | RESERVED_NAME |
-//   ID_TAKEN (+ .id) | NOT_FOUND | UNSUPPORTED
+//   ID_TAKEN (+ .id) | NOT_FOUND | UNSUPPORTED | SCRIPTS_UNCONFIRMED (+ .scriptNodes)
 
 import { listModels } from './config.mjs';
 import { EFFORTS, subagentModelIssue } from './model-env.mjs';
 import { loadAgentRegistry, DEFAULT_AGENTS_DIR } from './agent-registry.mjs';
+import { loadScriptRegistry } from './script-registry.mjs';
 import { registryPortsFn } from './graph/registry-ports.mjs';
 import { validateGraph, AGENT_TUNABLES } from '../shared/graph/validate.mjs';
+import { effectiveScriptParams, CONFIRM_PARAM_TYPES } from '../shared/graph/script-meta.mjs';
 import { readWorkflow, writeGraphWorkflow } from './workflows.mjs';
 
 /** How many `Name (n)` retries an import makes before giving up. */
@@ -27,6 +31,39 @@ export const SUFFIX_CAP = 20;
 
 function err(message, code, extra = {}) { return Object.assign(new Error(message), { code, ...extra }); }
 
+/** D18: the one sentence the CLI prints and the Import dialog shows above the commands. */
+export const SCRIPT_IMPORT_NOTICE = "These commands run on this machine with worca's privileges when the workflow runs.";
+
+/** The script nodes an import must show first (D18): every node whose EFFECTIVE
+ *  params include a command- or code-typed value, with those values. */
+export function listScriptNodes(graph, scripts) {
+  const out = [];
+  for (const n of Array.isArray(graph?.nodes) ? graph.nodes : []) {
+    if (!n || n.kind !== 'script' || !n.key) continue;
+    const meta = scripts?.[n.key];
+    if (!meta) continue;                                          // V4 reports it; nothing to show
+    const values = effectiveScriptParams(meta, n.config);
+    const params = {};
+    for (const p of meta.params || []) {
+      if (CONFIRM_PARAM_TYPES.includes(p.type) && typeof values[p.id] === 'string') params[p.id] = values[p.id];
+    }
+    if (Object.keys(params).length) out.push({ nodeId: n.id, key: n.key, displayName: meta.displayName || n.key, runtime: meta.runtime, params });
+  }
+  return out;
+}
+
+/** The CLI block: the notice, then one indented value per command/code param. */
+export function formatScriptNodes(list) {
+  const lines = [SCRIPT_IMPORT_NOTICE];
+  for (const n of list) {
+    for (const [id, value] of Object.entries(n.params)) {
+      lines.push(`- ${n.displayName} (${n.nodeId}, ${n.runtime}) ${id}:`);
+      for (const l of String(value).split('\n')) lines.push(`    ${l}`);
+    }
+  }
+  return lines.join('\n') + '\n';
+}
+
 /**
  * Validate one node-defaults block against the project-less catalog. Returns an
  * error message, or '' when the block is acceptable. Mirrors setStep's rules so a
@@ -120,8 +157,8 @@ function prepareGraph(body, { keepId, name }) {
   return graph;
 }
 
-/** Catalog + structural validation. Throws BAD_REQUEST / INVALID_GRAPH; returns warnings. */
-async function validateForSave(graph, { registry, agentsDir }) {
+/** Catalog + structural validation. Throws BAD_REQUEST / INVALID_GRAPH; returns the warnings and the script registry it used. */
+async function validateForSave(graph, { registry, scripts, agentsDir }) {
   // Catalog validation FIRST: a v2 node's `config` IS its defaults block (§4),
   // so a value the per-project override could not name must not ride in
   // through a template save. Only AGENT_TUNABLES are handed to nodeDefaultsError —
@@ -133,15 +170,14 @@ async function validateForSave(graph, { registry, agentsDir }) {
     const bad = nodeDefaultsError(picked, models, `node "${n.id}"`);
     if (bad) throw err(bad, 'BAD_REQUEST');
   }
-  const portsFn = registryPortsFn(registry || loadAgentRegistry(agentsDir || DEFAULT_AGENTS_DIR));
-  const { errors, warnings } = validateGraph({ ...graph, version: 2 }, portsFn);
-  if (errors.length) {
-    // The message stays the composer's verbatim 'invalid graph' (app.js renders
-    // the issue list); `summary` is the one-line V4 fold for the CLI and the
-    // import button, which have no issue list to show.
-    throw err('invalid graph', 'INVALID_GRAPH', { errors, warnings, summary: summarizeUnknownAgents(errors) });
-  }
-  return warnings;
+  const reg = registry || loadAgentRegistry(agentsDir || DEFAULT_AGENTS_DIR);
+  const scr = scripts && typeof scripts === 'object' ? scripts : loadScriptRegistry({ agentKeys: Object.keys(reg) });
+  const { errors, warnings } = validateGraph({ ...graph, version: 2 }, registryPortsFn(reg, scr));
+  // The message stays the composer's verbatim 'invalid graph' (app.js renders
+  // the issue list); `summary` is the one-line V4 fold for the CLI and the
+  // import button, which have no issue list to show.
+  if (errors.length) throw err('invalid graph', 'INVALID_GRAPH', { errors, warnings, summary: summarizeUnknownAgents(errors) });
+  return { warnings, scripts: scr };
 }
 
 /**
@@ -152,7 +188,7 @@ async function validateForSave(graph, { registry, agentsDir }) {
  */
 export async function saveGraphWorkflow(body, { registry, agentsDir } = {}) {
   const graph = prepareGraph(body || {}, { keepId: true });
-  const warnings = await validateForSave(graph, { registry, agentsDir });
+  const { warnings } = await validateForSave(graph, { registry, agentsDir });
   const workflow = await writeGraphWorkflow(graph, { rejectCollision: true });
   return { workflow, warnings };
 }
@@ -164,13 +200,26 @@ const SUFFIX_RE = /\s\((\d+)\)$/;
  * importer mints), `name` overrides the file's name, and a collision with a live
  * row retries as `Name (2)`, `Name (3)`… up to SUFFIX_CAP — never overwrite.
  * @param {object} body  the exportGraphJson shape
- * @param {{name?: string, registry?: object, agentsDir?: string}} [opts]
- * @returns {Promise<{workflow: object, warnings: Array, requestedName: string, renamed: boolean}>}
+ * @param {{name?: string, registry?: object, scripts?: object, agentsDir?: string, dryRun?: boolean, acceptScripts?: boolean}} [opts]
+ *   dryRun: validate and list the script nodes (D18) WITHOUT writing — the Import
+ *   dialog and the CLI confirm from this before the real import.
+ *   acceptScripts: the caller SHOWED the user every command/code value and the user
+ *   agreed. Anything but the literal `true` refuses a graph that carries one (P10):
+ *   the default is the safe one, so a caller that never heard of scripts cannot
+ *   import a command by accident.
+ * @returns {Promise<{workflow: object|null, warnings: Array, requestedName: string, renamed: boolean, scriptNodes: Array}>}
+ * @throws code 'SCRIPTS_UNCONFIRMED' (`.scriptNodes`) — nothing was written
  */
-export async function importGraphWorkflow(body, { name, registry, agentsDir } = {}) {
+export async function importGraphWorkflow(body, { name, registry, scripts, agentsDir, dryRun = false, acceptScripts = false } = {}) {
   const graph = prepareGraph(body || {}, { keepId: false, name });
-  const warnings = await validateForSave(graph, { registry, agentsDir });
+  const { warnings, scripts: scr } = await validateForSave(graph, { registry, scripts, agentsDir });
+  const scriptNodes = listScriptNodes(graph, scr);
   const requestedName = graph.name;
+  if (dryRun) return { workflow: null, warnings, requestedName, renamed: false, scriptNodes };
+  if (scriptNodes.length && acceptScripts !== true) {
+    throw err(`this workflow runs commands on this machine (${scriptNodes.map((n) => `${n.displayName} · ${n.nodeId}`).join(', ')}) — review them, then import again with the scripts accepted`,
+      'SCRIPTS_UNCONFIRMED', { scriptNodes });
+  }
   const m = SUFFIX_RE.exec(requestedName);
   const base = m ? requestedName.slice(0, m.index) : requestedName;
   let n = m ? Number(m[1]) : 1;
@@ -178,7 +227,7 @@ export async function importGraphWorkflow(body, { name, registry, agentsDir } =
   for (let attempt = 0; attempt <= SUFFIX_CAP; attempt++) {
     try {
       const workflow = await writeGraphWorkflow({ ...graph, name: candidate }, { rejectCollision: true });
-      return { workflow, warnings, requestedName, renamed: candidate !== requestedName };
+      return { workflow, warnings, requestedName, renamed: candidate !== requestedName, scriptNodes };
     } catch (e) {
       if (e?.code === 'RESERVED_NAME') {
         throw err(`${e.message} (pass a different name to import it)`, 'RESERVED_NAME');

package/src/core/workflows.mjs

@@ -22,9 +22,13 @@ import { isSubagentModelValue } from './model-env.mjs';
 const validSubagentModel = (v) => (isSubagentModelValue(v) ? v : undefined);
 import { slugify } from './artifacts.mjs';
 import { DEFAULT_AGENTS_DIR, loadAgentRegistry } from './agent-registry.mjs'; // fileURLToPath-based (Windows-safe)
+import { loadScriptRegistry } from './script-registry.mjs';
 import { readPluginsLock } from './plugins-lock.mjs';                 // a DISABLED plugin's rows are hidden
+import { teamDefault } from './policy/cache.mjs';                     // team-policy models.steps defaults
 import { validateGraph, formatIssue, AGENT_TUNABLES } from '../shared/graph/validate.mjs';
 import { classifyLoops } from '../shared/graph/loops.mjs';
+import { KEYED_KINDS } from '../shared/graph/constants.mjs';
+import { scriptNodeCtx } from '../shared/graph/script-meta.mjs';
 import {
   GRAPH_DEFAULT_WORKFLOW, AUTO_WORKFLOW_ID, AUTO_WORKFLOW_NAME, AUTO_WORKFLOW_STUB,
   GRAPH_MEMORY_DEFRAG_WORKFLOW, MEMORY_DEFRAG_WORKFLOW_ID, MEMORY_DEFRAG_WORKFLOW_NAME, isReservedWorkflowId,
@@ -409,11 +413,13 @@ export async function listWorkflows({ includeArchived = false, includeDisabled =
  * and must never refuse a run.
  * @param {object} tpl a version-2 template
  * @param {Record<string,object>} [registry] injected registry; the live one otherwise
+ * @param {Record<string,object>} [scripts] injected script registry; the live one otherwise
  * @throws {Error} code 'INVALID_GRAPH', `issues` = the validator's error list
  */
-function assertValidGraph(tpl, registry) {
+function assertValidGraph(tpl, registry, scripts) {
   const reg = registry && typeof registry === 'object' ? registry : loadAgentRegistry();
-  const { ok, errors } = validateGraph(tpl, registryPortsFn(reg));
+  const scr = scripts && typeof scripts === 'object' ? scripts : loadScriptRegistry({ agentKeys: Object.keys(reg) });
+  const { ok, errors } = validateGraph(tpl, registryPortsFn(reg, scr));
   if (ok) return;
   throw Object.assign(
     new Error(`workflow "${tpl.id}" no longer matches the agents it uses: `
@@ -428,9 +434,9 @@ function assertValidGraph(tpl, registry) {
  *  `checkGraph:false` is the READ escape hatch (GET /api/workflows/:id): a
  *  stale template must still open in the Composer, or it can never be repaired.
  *  @param {string} id
- *  @param {{registry?:Record<string,object>, checkGraph?:boolean}} [opts]
+ *  @param {{registry?:Record<string,object>, scripts?:Record<string,object>, checkGraph?:boolean}} [opts]
  */
-export async function assertRunnableWorkflow(id, { registry, checkGraph = true } = {}) {
+export async function assertRunnableWorkflow(id, { registry, scripts, checkGraph = true } = {}) {
   const wanted = typeof id === 'string' && id.trim() ? id.trim() : GRAPH_DEFAULT_WORKFLOW.id;
   // The Auto entry has no graph to check: the run decides one (spec §5.1).
   if (wanted === AUTO_WORKFLOW_ID) return AUTO_WORKFLOW_STUB;
@@ -445,7 +451,7 @@ export async function assertRunnableWorkflow(id, { registry, checkGraph = true }
         + `enable the plugin (Plugins view, or: worca plugin enable ${plugin}) to use it`), { code: 'PLUGIN_DISABLED' });
     }
     // A v1 row is not a graph: engine-select owns its refusal (V1_RUN_RETIRED).
-    if (checkGraph && live.version === 2) assertValidGraph(live, registry);
+    if (checkGraph && live.version === 2) assertValidGraph(live, registry, scripts);
     return live;
   }
   const archived = await readWorkflow(wanted, { includeArchived: true });
@@ -603,6 +609,7 @@ export async function resolveGraph(projectDir, workflowId, registry, agentsDir =
   // constant) whose agent nodes carry the RESOLVED key after workspace substitution.
   const tpl = structuredClone(stored);
   const reg = registry && typeof registry === 'object' ? registry : {};
+  const scripts = opts.scripts && typeof opts.scripts === 'object' ? opts.scripts : loadScriptRegistry({ agentKeys: Object.keys(reg) });
   const isWorkspace = !!opts.isWorkspace;
   const variants = isWorkspace ? workspaceVariants(reg) : {};
   // Per-project overlays. An Auto run owns its tuning (spec D7/D9): with
@@ -627,11 +634,39 @@ export async function resolveGraph(projectDir, workflowId, registry, agentsDir =
   // store (projectKey(null) throws); its legacy per-role layer is empty by definition.
   const stepsCfg = (!ignore && workflowId === GRAPH_DEFAULT_WORKFLOW.id && projectDir) ? (await readConfig(projectDir)).steps : {};
   const firstDefined = (...vals) => vals.find((v) => v !== undefined);
+  // Team policy `models.steps` (a default, team-policy design §8): model and effort per ROLE for
+  // roles the project has not configured — below the project's own node and per-role config,
+  // above the template's authored config. Cache-only read; absent without a policy.
+  const teamSteps = (!ignore && projectDir) ? (teamDefault(projectDir, 'models.steps') || {}) : {};
+  // Memory defragment (Settings › Memory, memory-defrag-model.mjs): the run's model/effort PAIR —
+  // named at start, else the global setting. The one layer that beats even the project's own node
+  // pick (the setting is global by design: no per-project override), and it carries its own
+  // effort, so no lower layer's effort rides under a model it was not chosen for. Absent (every
+  // other caller, and a defragment run with nothing named or stored) → the layers below, unchanged.
+  const pair = opts.agentPair && typeof opts.agentPair.model === 'string' && opts.agentPair.model.trim()
+    ? {
+      model: opts.agentPair.model.trim(),
+      effort: typeof opts.agentPair.effort === 'string' && opts.agentPair.effort ? opts.agentPair.effort : undefined,
+    }
+    : null;
 
   const nodes = {};
   const agentsByKey = {};
   const agentKeys = new Set();
+  const scriptsByKey = {};
+  const scriptKeys = new Set();
   for (const node of Array.isArray(tpl.nodes) ? tpl.nodes : []) {
+    if (node.kind === 'script') {
+      const meta = scripts[node.key];
+      if (!meta) throw new Error(`unknown script "${node.key}" — no such key in the registry`);
+      if (meta.placeable === false) throw new Error(`script "${node.key}" declares placeable: false and cannot be a graph node`);
+      // v4 T5: ONE builder for the run-time facts of a placed card — the resume path (Task 9), the offline runner
+      // (Task 13) and P1c's bench build the same object from the same function, so they cannot drift apart.
+      nodes[node.id] = scriptNodeCtx(node, meta);
+      scriptsByKey[node.key] = meta;
+      scriptKeys.add(node.key);
+      continue;
+    }
     if (node.kind !== 'agent') {
       nodes[node.id] = { nodeId: node.id, kind: node.kind, key: null, config: { ...(node.config || {}) } };
       continue;
@@ -653,6 +688,7 @@ export async function resolveGraph(projectDir, workflowId, registry, agentsDir =
     // Legacy per-role config is keyed by the AUTHORED key, so a substituted
     // variant still inherits the user's model/effort for that role.
     const legacy = stepsCfg[authored] || {};
+    const team = (sel.model || sel.effort || legacy.model || legacy.effort) ? {} : (teamSteps[authored] || {});
     const cfg = node.config && typeof node.config === 'object' ? node.config : {};
     nodes[node.id] = {
       nodeId: node.id,
@@ -666,10 +702,10 @@ export async function resolveGraph(projectDir, workflowId, registry, agentsDir =
       promptHints: typeof meta.promptHints === 'string' ? meta.promptHints : '',
       tools,
       config: { ...cfg },
-      model: firstDefined(sel.model, legacy.model, cfg.model),
+      model: pair ? pair.model : firstDefined(sel.model, legacy.model, team.model, cfg.model),
       // An effort only travels with the model that advertises it: an override
       // naming its own model must not inherit the lower layer's effort.
-      effort: firstDefined(sel.effort, legacy.effort, (sel.model || legacy.model) ? undefined : cfg.effort),
+      effort: pair ? pair.effort : firstDefined(sel.effort, legacy.effort, team.effort, (sel.model || legacy.model || team.model) ? undefined : cfg.effort),
       // workspaceFanOut forces fan-out on a workspace run (the generic
       // replacement for the v1 FANOUT_ELIGIBLE key list).
       fanOut: isWorkspace && meta.workspaceFanOut
@@ -699,13 +735,13 @@ export async function resolveGraph(projectDir, workflowId, registry, agentsDir =
 
   // Two nodes sharing one agent key prefix their run-store outputs (executor dupPrefix).
   const keyCount = new Map();
-  for (const nc of Object.values(nodes)) if (nc.kind === 'agent') keyCount.set(nc.key, (keyCount.get(nc.key) || 0) + 1);
-  for (const nc of Object.values(nodes)) if (nc.kind === 'agent') nc.duplicateKey = (keyCount.get(nc.key) || 0) > 1;
+  for (const nc of Object.values(nodes)) if (KEYED_KINDS.includes(nc.kind)) keyCount.set(nc.key, (keyCount.get(nc.key) || 0) + 1);
+  for (const nc of Object.values(nodes)) if (KEYED_KINDS.includes(nc.kind)) nc.duplicateKey = (keyCount.get(nc.key) || 0) > 1;
 
   // Budgets ride LOOP wires only: overlay > authored > DEFAULT_MAX_CYCLES.
   // portsFn + loops are computed ONCE here and RETURNED — P4 hands them to the
   // scheduler and the manifest builder instead of re-deriving them.
-  const portsFn = registryPortsFn(agentsByKey);
+  const portsFn = registryPortsFn(agentsByKey, scriptsByKey);
   const loops = classifyLoops(tpl, portsFn);
   const { loopWireIds } = loops;
   const wires = {};
@@ -714,5 +750,5 @@ export async function resolveGraph(projectDir, workflowId, registry, agentsDir =
     const raw = Number(wireCfg[w.id]?.maxCycles ?? w.config?.maxCycles);
     wires[w.id] = { maxCycles: Number.isInteger(raw) && raw >= 1 ? raw : DEFAULT_MAX_CYCLES };
   }
-  return { template: tpl, ports: portsFn, loops, nodes, wires, agentsByKey, agentKeys };
+  return { template: tpl, ports: portsFn, loops, nodes, wires, agentsByKey, agentKeys, scriptsByKey, scriptKeys };
 }

package/src/core/workspaces.mjs

@@ -42,14 +42,14 @@ function err(message, code) { return Object.assign(new Error(message), { code })
  * @returns {string|null}
  * @throws err(code: BAD_REQUEST)
  */
-function memberPathFor(paths, candidate) {
+function memberPathFor(paths, candidate, field = 'metricsProject') {
   if (candidate == null || candidate === '') return null;
-  if (typeof candidate !== 'string') throw err('metricsProject must be a project path or null', 'BAD_REQUEST');
+  if (typeof candidate !== 'string') throw err(`${field} must be a project path or null`, 'BAD_REQUEST');
   const want = normalizeProjectPath(candidate);
   // normalizeProjectPath('   ') -> null; canonicalProjectRoot(null) would throw ERR_INVALID_ARG_TYPE -> 500.
-  if (!want) throw err('metricsProject must be a project path or null', 'BAD_REQUEST');
+  if (!want) throw err(`${field} must be a project path or null`, 'BAD_REQUEST');
   const hit = paths.find((p) => p === want || canonicalProjectRoot(p) === canonicalProjectRoot(want));
-  if (!hit) throw err('metricsProject must be one of the workspace projects', 'BAD_REQUEST');
+  if (!hit) throw err(`${field} must be one of the workspace projects`, 'BAD_REQUEST');
   return hit;
 }
 
@@ -130,6 +130,7 @@ function annotate(entry) {
     projectKeys: pairs.map((x) => x.key),
     exists: pairs.map((x) => isDir(x.path)),
     metricsProject: entry.metricsProject ?? null,
+    policyProject: entry.policyProject ?? null,
     createdAt: entry.createdAt,
     updatedAt: entry.updatedAt,
   };
@@ -150,6 +151,7 @@ function rowToEntry(r) {
     description: typeof r.description === 'string' ? r.description : '',
     projectPaths: memberPaths(r.id),
     metricsProject: r.metrics_project ?? null,
+    policyProject: r.policy_project ?? null,
     createdAt: typeof r.created_at === 'string' ? r.created_at : '',
     updatedAt: typeof r.updated_at === 'string' ? r.updated_at : '',
   };
@@ -159,7 +161,7 @@ function rowToEntry(r) {
 function readEntry(id) {
   getDb();
   const r = prepare(
-    'SELECT id, name, description, metrics_project, created_at, updated_at FROM workspaces WHERE id = ?'
+    'SELECT id, name, description, metrics_project, policy_project, created_at, updated_at FROM workspaces WHERE id = ?'
   ).get(id);
   return r ? rowToEntry(r) : null;
 }
@@ -171,7 +173,7 @@ function readEntry(id) {
 export async function listWorkspaces() {
   getDb();
   const rows = prepare(
-    'SELECT id, name, description, metrics_project, created_at, updated_at FROM workspaces ORDER BY created_at, name'
+    'SELECT id, name, description, metrics_project, policy_project, created_at, updated_at FROM workspaces ORDER BY created_at, name'
   ).all();
   return rows.map(rowToEntry).map(annotate);
 }
@@ -242,6 +244,7 @@ export async function createWorkspace(input = {}) {
   }
 
   const metricsProject = memberPathFor(members, input.metricsProject ?? null);
+  const policyProject = memberPathFor(members, input.policyProject ?? null, 'policyProject');
   const id = workspaceKey({ name, projectPaths: members });
   const hash = rootsHash(members);
   const now = new Date().toISOString();
@@ -259,8 +262,8 @@ export async function createWorkspace(input = {}) {
       }
     }
     prepare(
-      'INSERT INTO workspaces (id, name, description, metrics_project, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)'
-    ).run(id, name, description, metricsProject, now, now);
+      'INSERT INTO workspaces (id, name, description, metrics_project, policy_project, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?)'
+    ).run(id, name, description, metricsProject, policyProject, now, now);
     const insMember = prepare(
       'INSERT INTO workspace_projects (workspace_id, project_key, ordinal) VALUES (?, ?, ?)'
     );
@@ -270,7 +273,7 @@ export async function createWorkspace(input = {}) {
 
   // Return the annotated entry (derived fields recomputed from the persisted paths).
   return annotate({
-    id, name, description, projectPaths: members, metricsProject, createdAt: now, updatedAt: now,
+    id, name, description, projectPaths: members, metricsProject, policyProject, createdAt: now, updatedAt: now,
   });
 }
 
@@ -299,6 +302,9 @@ export async function updateWorkspace(id, patch = {}) {
   const metricsProject = Object.prototype.hasOwnProperty.call(patch || {}, 'metricsProject')
     ? memberPathFor(entry.projectPaths, patch.metricsProject)
     : entry.metricsProject ?? null;
+  const policyProject = Object.prototype.hasOwnProperty.call(patch || {}, 'policyProject')
+    ? memberPathFor(entry.projectPaths, patch.policyProject, 'policyProject')
+    : entry.policyProject ?? null;
   const now = new Date().toISOString();
 
   tx(() => {
@@ -308,11 +314,11 @@ export async function updateWorkspace(id, patch = {}) {
     ).get(name, id);
     if (clash) throw err(`a workspace named "${name}" already exists`, 'DUPLICATE_NAME');
     prepare(
-      'UPDATE workspaces SET name = ?, description = ?, metrics_project = ?, updated_at = ? WHERE id = ?'
-    ).run(name, description, metricsProject, now, id);
+      'UPDATE workspaces SET name = ?, description = ?, metrics_project = ?, policy_project = ?, updated_at = ? WHERE id = ?'
+    ).run(name, description, metricsProject, policyProject, now, id);
   });
 
-  return annotate({ ...entry, name, description, metricsProject, updatedAt: now });
+  return annotate({ ...entry, name, description, metricsProject, policyProject, updatedAt: now });
 }
 
 /** Thin setter: edit only the description. */