@worca/app 1.0.0 → 1.2.0-rc.1

package/src/core/plugin-store.mjs

@@ -11,24 +11,30 @@ import { promisify } from 'node:util';
 import { createHash } from 'node:crypto';
 import {
   existsSync, readdirSync, readFileSync, readlinkSync,
-  mkdirSync, rmSync, symlinkSync, renameSync,
+  mkdirSync, rmSync, symlinkSync, renameSync, unlinkSync,
 } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { join, resolve, isAbsolute, sep } from 'node:path';
 import { WORCA_PLUGIN_APIS } from './plugin-api.mjs';
-import { normalizeManifest, validatePluginDir, apiSatisfies } from './plugin-manifest.mjs';
+import { normalizeManifest, validatePluginDir, apiSatisfies, dataContractIssues, apiMismatch } from './plugin-manifest.mjs';
 import {
   pluginsRoot, pluginDir, pluginCurrentDir, pluginDataDir, readPluginsLock, writePluginsLock,
   DIR_NAME_RE,
 } from './plugins-lock.mjs';
 import { addPluginRepo, fetchCandidate, exportVersion, repoCacheDir } from './plugin-repo.mjs';
-import { importPluginWorkflows, removePluginWorkflows, referencedPluginAgents } from './plugin-workflows.mjs';
+import {
+  importPluginWorkflows, readPluginWorkflows, removePluginWorkflows, referencedPluginAgents,
+} from './plugin-workflows.mjs';
+import { loadAgentRegistry } from './agent-registry.mjs';
 import { pluginModelSecretStatus } from './plugin-models.mjs';
 import { referencedPluginModels } from './config.mjs';
+import { clearBindingsForPlugin } from './source-bindings.mjs';
 
 const execFileP = promisify(execFile);
 const defaultExec = (cmd, args, opts = {}) =>
   execFileP(cmd, args, { maxBuffer: 16 * 1024 * 1024, ...opts });
 
+const IS_WINDOWS = process.platform === 'win32';
+
 function readManifestAt(dir) {
   try {
     const res = normalizeManifest(JSON.parse(readFileSync(join(dir, 'worca-cc-plugin.json'), 'utf8')), { dir });
@@ -42,6 +48,13 @@ function sha256File(file) {
   try { return createHash('sha256').update(readFileSync(file)).digest('hex'); } catch { return null; }
 }
 
+/** True when the relative path `rel` still resolves INSIDE `dir`. */
+function insideDir(dir, rel) {
+  if (isAbsolute(rel) || /\\/.test(rel)) return false;
+  const root = resolve(dir);
+  return resolve(root, rel).startsWith(root + sep);
+}
+
 /** Private copy of workflows.mjs:66-77 parseFrontmatterTools (module-private there). */
 function frontmatterTools(text) {
   const m = /^---\s*\n([\s\S]*?)\n---/.exec(text);
@@ -64,8 +77,19 @@ export function buildInstallInventory(versionDir) {
   if (existsSync(aDir)) {
     for (const f of readdirSync(aDir).filter((x) => x.endsWith('.meta.json')).sort()) {
       const key = f.slice(0, -'.meta.json'.length);
+      // Consent must describe the bytes the RUNTIME will read: agent-registry
+      // stamps agentPath = join(<layer>/agents, meta.agentFile), so reading
+      // `${key}.md` here showed a DECOY for any sidecar naming another file
+      // (C-1). Containment is re-checked because this also runs on an
+      // unvalidated dir (the pre-install preview); an escaping agentFile falls
+      // back to the sibling and validatePluginDir refuses the install anyway.
+      let mdFile = `${key}.md`;
+      try {
+        const af = JSON.parse(readFileSync(join(aDir, f), 'utf8'))?.agentFile;
+        if (typeof af === 'string' && af.trim() && insideDir(aDir, af.trim())) mdFile = af.trim();
+      } catch { /* unreadable sidecar: fall back to the sibling */ }
       let tools = [];
-      try { tools = frontmatterTools(readFileSync(join(aDir, `${key}.md`), 'utf8')); } catch { /* md missing */ }
+      try { tools = frontmatterTools(readFileSync(join(aDir, mdFile), 'utf8')); } catch { /* md missing */ }
       agents.push({ key, tools });
     }
   }
@@ -113,6 +137,45 @@ export function buildInstallInventory(versionDir) {
   return { agents, taskSources, chatChannels, models, modelSecrets, skills: skills.sort(), workflows, depCount, setupCommands };
 }
 
+/**
+ * Contributions a plugin SHIPS but worca IGNORED, as `[{ file, reason }]` sorted
+ * by file (`agents/<sidecar>.meta.json`, `workflows/<template>.json`). The two
+ * drop sites — the agent registry and the workflow importer — reach only
+ * console.warn on their own, so every reporting surface (install receipt,
+ * Plugins card, doctor) was free to claim a contribution that does not exist.
+ *
+ * Generic by construction: nothing here is keyed on an agent key or a plugin
+ * name — the drop reasons are authored at the drop sites and carried verbatim.
+ *
+ * @param {string} name
+ * @param {string} dir  the plugin's current/ (or version) dir
+ * @param {{registry?: object, drops?: Array<{origin:string,file:string,reason:string}>,
+ *          workflowSkips?: Array<{file:string, errors:string[]}>}} [opts]
+ *        registry/drops: reuse ONE registry load across plugins; workflowSkips:
+ *        the importer's OWN result, when the caller just ran it.
+ * @returns {Array<{file: string, reason: string}>}
+ */
+export function ignoredContributions(name, dir, opts = {}) {
+  const out = [];
+  let drops = opts.drops;
+  let registry = opts.registry;
+  if (!drops) {
+    drops = [];
+    try { registry = loadAgentRegistry(undefined, { onDrop: (d) => drops.push(d) }); }
+    catch { /* no resolvable home: report what the files alone can say */ }
+  }
+  for (const d of drops) {
+    if (d.origin === `plugin:${name}`) out.push({ file: `agents/${d.file}`, reason: d.reason });
+  }
+  const skips = opts.workflowSkips
+    ?? (() => {
+      try { return readPluginWorkflows(name, dir, { registry, quiet: true }).skipped; }
+      catch { return []; }
+    })();
+  for (const s of skips) out.push({ file: `workflows/${s.file}`, reason: `invalid template (${s.errors.join('; ')})` });
+  return out.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
+}
+
 /** Declared setup FACTS only (spec §4.1): setup.node -> npm ci (lockfile
  *  required, scripts ignored); setup.python 'pyproject' -> uv sync. */
 export async function runSetup(versionDir, manifest, { exec = defaultExec } = {}) {
@@ -121,11 +184,17 @@ export async function runSetup(versionDir, manifest, { exec = defaultExec } = {}
     if (!existsSync(join(versionDir, 'package-lock.json'))) {
       throw new Error(`setup.node declared but ${join(versionDir, 'package-lock.json')} is missing (npm ci requires a lockfile)`);
     }
-    await exec('npm', ['ci', '--prefix', versionDir, '--ignore-scripts', '--omit=dev']);
+    // cwd instead of --prefix so no native path is passed as an argument: on
+    // Windows npm is `npm.cmd`, which needs a shell (bare `npm` -> ENOENT, and
+    // execFile of a `.cmd` -> EINVAL on modern Node), and shell:true does NOT
+    // quote args — a `--prefix C:\…` path would be mangled. With the dir as cwd
+    // the only args left are flag literals, safe through the shell.
+    await exec('npm', ['ci', '--ignore-scripts', '--omit=dev'],
+      { cwd: versionDir, shell: IS_WINDOWS });
     commands.push('npm ci');
   }
   if (manifest?.setup?.python === 'pyproject') {
-    await exec('uv', ['sync', '--project', versionDir]);
+    await exec('uv', ['sync'], { cwd: versionDir });
     commands.push('uv sync');
   }
   return { commands };
@@ -152,12 +221,35 @@ function currentTarget(name) {
   try { return readlinkSync(pluginCurrentDir(name)); } catch { return null; }
 }
 
-/** Atomic swap (§6.1 step 3): write current.tmp symlink, rename(2) over current. */
+// rmSync is the wrong primitive for a POSIX path that may be a symlink: it
+// stats THROUGH the link, so a link to a directory throws ERR_FS_EISDIR and a
+// DANGLING link reads as "already gone" and survives force:true (Node 23).
+// unlink removes the link itself; the fallback covers a real directory
+// (test fixtures build `current` as a plain dir).
+const rmLink = (path) => {
+  try { unlinkSync(path); return; } catch (err) {
+    if (err.code === 'ENOENT') return;
+  }
+  rmSync(path, { recursive: true, force: true });
+};
+
+/** Atomic swap (§6.1 step 3): write current.tmp symlink, rename(2) over current.
+ *  Windows can't create a plain symlink without elevated privileges/Developer
+ *  Mode, and can't rename() a directory reparse point over an existing one
+ *  (EPERM). It CAN create a directory JUNCTION unprivileged, so there we
+ *  remove-then-create a junction in place. A junction needs an ABSOLUTE target
+ *  (POSIX keeps the relative "versions/<sha7>" so the link survives a moved
+ *  plugin dir); rmSync on a junction drops only the link, never the target. */
 function swapCurrent(name, target) {
   const current = pluginCurrentDir(name);
-  const tmp = `${current}.tmp`;
-  rmSync(tmp, { force: true });
   mkdirSync(pluginDir(name), { recursive: true });
+  if (IS_WINDOWS) {
+    rmSync(current, { force: true });
+    symlinkSync(resolve(pluginDir(name), target), current, 'junction');
+    return;
+  }
+  const tmp = `${current}.tmp`;
+  rmLink(tmp);
   symlinkSync(target, tmp);
   renameSync(tmp, current);
 }
@@ -166,19 +258,27 @@ function swapCurrent(name, target) {
  *  dir, restore/remove current, tidy now-empty dirs. Prior state untouched. */
 function cleanupFailedVersion(name, versionDir, prevCurrent) {
   rmSync(versionDir, { recursive: true, force: true });
-  rmSync(`${pluginCurrentDir(name)}.tmp`, { force: true });
+  rmLink(`${pluginCurrentDir(name)}.tmp`);
   if (prevCurrent) { try { swapCurrent(name, prevCurrent); } catch { /* best effort */ } }
-  else rmSync(pluginCurrentDir(name), { force: true });
+  else rmLink(pluginCurrentDir(name));
   for (const d of [join(pluginDir(name), 'versions'), pluginDir(name)]) {
     try { if (readdirSync(d).length === 0) rmSync(d, { recursive: true, force: true }); } catch { /* absent */ }
   }
 }
 
+/** Problem lines for a refusal message. `level` is a REPORTING axis, not a
+ *  cause axis — a plugin whose declared API makes its data problems WARNINGS
+ *  must never be refused with an empty body, so fall back to every problem when
+ *  no error line exists. */
+function refusalLines(problems, prefix = '  - ') {
+  const errorsOnly = problems.filter((p) => p.level === 'error');
+  return (errorsOnly.length ? errorsOnly : problems).map((p) => `${prefix}${p.message}`);
+}
+
 function validated(name, versionDir) {
   const v = validatePluginDir(versionDir);
   if (!v.ok) {
-    const lines = v.problems.filter((p) => p.level === 'error').map((p) => `  - ${p.message}`);
-    throw new Error(`plugin "${name}" failed validation:\n${lines.join('\n')}`);
+    throw new Error(`plugin "${name}" failed validation:\n${refusalLines(v.problems).join('\n')}`);
   }
   return v.manifest;
 }
@@ -222,15 +322,20 @@ export async function installPlugin({ repoUrl, subdir = '', name, sha, marketpla
     // reach installPlugin's catch — cleanupFailedVersion would delete the version
     // dir a just-written lock entry points at. The install itself already
     // succeeded; warn and continue (re-import happens on the next update).
+    let workflowSkips = null;
     try {
       const wf = await importPluginWorkflows(name, versionDir);
+      workflowSkips = wf.skipped;
       for (const s of wf.skipped) {
         console.warn(`[plugin-store] ${name}: workflow ${s.file} not imported (${s.errors.join('; ')})`);
       }
     } catch (err) {
       console.warn(`[plugin-store] ${name}: workflow import failed (${err?.message || err}) — plugin installed; re-import via update`);
     }
-    return { ok: true, inventory, warnings };
+    // The receipt says what actually landed: `inventory` is what the plugin
+    // SHIPS, `ignored` is the subset worca refused to load (spec §9.3 drops).
+    const ignored = ignoredContributions(name, versionDir, workflowSkips ? { workflowSkips } : {});
+    return { ok: true, inventory, warnings, ignored };
   } catch (err) {
     cleanupFailedVersion(name, versionDir, prevCurrent);
     throw err;
@@ -270,15 +375,18 @@ export async function updatePlugin(name, { exec = defaultExec } = {}) {
     // §6.2(3): workflow re-import (upsert) after swap + lock update — same
     // isolation rationale as installPlugin: an import failure must not reach
     // this catch (cleanupFailedVersion would tear down the now-live version).
+    let workflowSkips = null;
     try {
       const wf = await importPluginWorkflows(name, versionDir);
+      workflowSkips = wf.skipped;
       for (const s of wf.skipped) {
         console.warn(`[plugin-store] ${name}: workflow ${s.file} not imported (${s.errors.join('; ')})`);
       }
     } catch (err) {
       console.warn(`[plugin-store] ${name}: workflow import failed (${err?.message || err}) — plugin updated; re-import via update`);
     }
-    return { ok: true, updated: true, inventory, warnings, ...cand };
+    const ignored = ignoredContributions(name, versionDir, workflowSkips ? { workflowSkips } : {});
+    return { ok: true, updated: true, inventory, warnings, ignored, ...cand };
   } catch (err) {
     cleanupFailedVersion(name, versionDir, prevCurrent);
     throw err;
@@ -326,7 +434,13 @@ export async function uninstallPlugin(name, { purge = false } = {}) {
     );
   }
   await removePluginWorkflows(name); // throws its ReferencedError with the referencing list
-  rmSync(pluginCurrentDir(name), { force: true });
+  // Bindings live in the DB, not in the plugin's data dir, so they would
+  // outlive the uninstall: a stale row silently rebinds a project the moment
+  // the plugin is reinstalled with a same-named profile — possibly pointing at
+  // a different tracker. Cleared HERE (not only in the server's DELETE route)
+  // so the CLI's `worca plugin remove` drops them too.
+  clearBindingsForPlugin(name);
+  rmLink(pluginCurrentDir(name)); // symlink in real installs, a plain dir in test fixtures
   rmSync(join(pluginDir(name), 'versions'), { recursive: true, force: true });
   delete lock[name];
   writePluginsLock(lock);
@@ -388,11 +502,23 @@ export function setPluginEnabled(name, enabled) {
 /** Lock + current-manifest merge for the Plugins view / CLI list. */
 export function listInstalledPlugins() {
   const lock = readPluginsLock();
+  // ONE registry load for the whole list: it is the only place that knows which
+  // sidecars were dropped, and re-scanning per plugin would be N full scans.
+  const drops = [];
+  let registry = null;
+  try { registry = loadAgentRegistry(undefined, { onDrop: (d) => drops.push(d) }); }
+  catch { /* no resolvable home: fall back to the file-derived view */ }
   return Object.keys(lock).sort().map((name) => {
     const e = lock[name] || {};
     const cur = pluginCurrentDir(name);
     const manifest = existsSync(cur) ? readManifestAt(cur) : null; // existsSync follows the symlink
     const inv = manifest ? buildInstallInventory(cur) : null;
+    // Read from the raw dir, not the manifest: the mismatch is about the DATA
+    // the plugin ships, not about whether its manifest normalized. A plugin
+    // whose manifest did not normalize is `broken`, which outranks this.
+    const mismatch = manifest
+      ? apiMismatch(manifest.engines?.worcaApi ?? '', dataContractIssues(cur))
+      : null;
     return {
       name,
       version: e.version ?? null,
@@ -403,9 +529,15 @@ export function listInstalledPlugins() {
       enabled: e.enabled !== false,
       linked: e.linked === true,
       broken: !manifest,
+      apiMismatch: mismatch,
       contributions: inv
         ? { agents: inv.agents.length, taskSources: inv.taskSources.length, chatChannels: inv.chatChannels.length, models: inv.models.length, skills: inv.skills.length, workflows: inv.workflows.length }
         : { agents: 0, taskSources: 0, chatChannels: 0, models: 0, skills: 0, workflows: 0 },
+      // `contributions` counts what the plugin SHIPS (files on disk); `ignored`
+      // names the ones worca refused to load, so the card can stop claiming them.
+      // A disabled plugin contributes nothing BY CHOICE — its agents are not in the
+      // registry, so its templates would misreport V4.
+      ignored: manifest && e.enabled !== false ? ignoredContributions(name, cur, { registry, drops }) : [],
     };
   });
 }
@@ -429,6 +561,26 @@ export async function doctorPlugin(name) {
   if (!resolves) return { ok: false, checks };
   const manifest = readManifestAt(cur);
   checks.push(...dirChecks(cur, manifest));
+  // The DATA contract check is ADVISORY, so it lives HERE and never in
+  // dirChecks: dirChecks also feeds the install precheck, which THROWS on any
+  // failing check, and an outdated data contract must never block an install —
+  // the plugin's connector/chat channel still works untouched, worca simply
+  // ignores the agents and pipeline templates it ships (spec §9, P7.2).
+  if (manifest) {
+    const mismatch = apiMismatch(manifest.engines?.worcaApi ?? '', dataContractIssues(cur));
+    checks.push({ id: 'agents-api', ok: !mismatch,
+      detail: mismatch ? mismatch.message : 'agents and pipeline templates are plugin API 3 (meta v2 + graph templates)' });
+  }
+  // Same gate as the card: a disabled plugin contributes nothing BY CHOICE — its
+  // agents are not in the registry, so its templates would misreport V4 and this
+  // check would fail a plugin that is merely switched off.
+  if (manifest && entry.enabled !== false) {
+    const ignored = ignoredContributions(name, cur);
+    c('contributions', ignored.length === 0,
+      ignored.length
+        ? `${ignored.length} ignored: ${ignored.map((i) => `${i.file} — ${i.reason}`).join('; ')}`
+        : 'every shipped contribution loaded');
+  }
   if (manifest?.setup?.node && !entry.linked) {
     const h = sha256File(join(cur, 'package-lock.json'));
     c('lock-hash', !entry.lockfileHash || h === entry.lockfileHash,
@@ -449,12 +601,28 @@ export async function doctorPlugin(name) {
     try { shim = await import('./plugin-shim.mjs'); } // Task 11 module — may not exist yet
     catch (err) { if (err?.code !== 'ERR_MODULE_NOT_FOUND') throw err; }
     if (shim) {
+      const { listProfileIds } = await import('./plugin-config.mjs');
       for (const s of manifest.taskSources) {
-        try {
-          const r = await shim.callSource({ plugin: name, sourceId: s.id, op: 'validateConfig' });
-          c(`config:${s.id}`, r?.ok !== false, r?.ok === false ? JSON.stringify(r.errors ?? r) : 'validateConfig ok');
-        } catch (err) {
-          c(`config:${s.id}`, false, String(err?.message || err));
+        // A multi-profile source stores nothing in the implicit default bucket;
+        // validating that would flag a fully configured plugin as broken. Check
+        // each roster profile instead. An EMPTY roster is not healthy-by-vacuity
+        // either: every run of the source is rejected ("profile is required")
+        // until one exists, and validating the default bucket instead can even
+        // report green off legacy config migrated under 'default' after an
+        // upgrade flipped the source to multiProfile — a plugin nothing can run.
+        const profiles = s.multiProfile ? listProfileIds(name) : [];
+        if (s.multiProfile && !profiles.length) {
+          c(`config:${s.id}`, false, 'no profiles yet — create one in Plugins settings (every run is rejected until then)');
+          continue;
+        }
+        for (const profile of profiles.length ? profiles : [undefined]) {
+          const id = profile ? `config:${s.id}@${profile}` : `config:${s.id}`;
+          try {
+            const r = await shim.callSource({ plugin: name, sourceId: s.id, op: 'validateConfig', profile });
+            c(id, r?.ok !== false, r?.ok === false ? JSON.stringify(r.errors ?? r) : 'validateConfig ok');
+          } catch (err) {
+            c(id, false, String(err?.message || err));
+          }
         }
       }
     }
@@ -462,14 +630,20 @@ export async function doctorPlugin(name) {
   return { ok: checks.every((x) => x.ok), checks };
 }
 
-/** Dev mode (spec §6.6): current -> absolute working dir; lock { linked: true }. */
-export function linkPlugin(name, absDir) {
+/**
+ * Dev mode (spec §6.6): current -> absolute working dir; lock { linked: true }.
+ * ASYNC because linking, like installing, ends with the workflow-template
+ * import: `plugin link` is the documented author loop (SKILL.md) and
+ * `updatePlugin` refuses a linked plugin, so without this a linked plugin's
+ * templates could reach the store by NO path at all. A linked dir is
+ * live-edited, so the refresh path afterwards is `worca plugin reimport <name>`.
+ * @returns {Promise<{ok:true, name:string, dir:string,
+ *   workflows:{imported:string[], skipped:Array<{file:string, errors:string[]}>}}>}
+ */
+export async function linkPlugin(name, absDir) {
   const dir = resolve(absDir);
   const v = validatePluginDir(dir);
-  if (!v.ok) {
-    const lines = v.problems.filter((p) => p.level === 'error').map((p) => p.message);
-    throw new Error(`cannot link: ${lines.join('; ')}`);
-  }
+  if (!v.ok) throw new Error(`cannot link: ${refusalLines(v.problems, '').join('; ')}`);
   if (v.manifest.name !== name) {
     throw new Error(`manifest name "${v.manifest.name}" does not match "${name}"`);
   }
@@ -481,5 +655,38 @@ export function linkPlugin(name, absDir) {
     installedAt: new Date().toISOString(), linked: true,
   };
   writePluginsLock(lock);
-  return { ok: true, name, dir };
+  // Same isolation as installPlugin: an import failure must not undo a link
+  // that already landed — the lock and the symlink are correct either way.
+  let workflows = { imported: [], skipped: [] };
+  try {
+    workflows = await importPluginWorkflows(name, dir);
+    for (const s of workflows.skipped) {
+      console.warn(`[plugin-store] ${name}: workflow ${s.file} not imported (${s.errors.join('; ')})`);
+    }
+  } catch (err) {
+    console.warn(`[plugin-store] ${name}: workflow import failed (${err?.message || err}) — plugin linked; re-import with \`worca plugin reimport ${name}\``);
+  }
+  return { ok: true, name, dir, workflows };
+}
+
+/**
+ * Re-run the workflow-template import for an INSTALLED OR LINKED plugin
+ * (spec §6.6). A linked dir is live-edited and `updatePlugin` refuses linked
+ * plugins, so this is the only refresh path a plugin author has; for an
+ * installed plugin it is the cheap way to retry an import that failed.
+ * Upsert-only: a template file the author DELETED keeps its row until the
+ * plugin is removed.
+ * @returns {Promise<{ok:true, name:string,
+ *   workflows:{imported:string[], skipped:Array<{file:string, errors:string[]}>},
+ *   ignored:Array<{file:string, reason:string}>}>}
+ */
+export async function reimportPlugin(name) {
+  if (!readPluginsLock()[name]) throw new Error(`plugin "${name}" is not installed`);
+  const cur = pluginCurrentDir(name);
+  if (!existsSync(cur)) throw new Error(`plugin "${name}": current symlink missing or dangling`);
+  const workflows = await importPluginWorkflows(name, cur);
+  for (const s of workflows.skipped) {
+    console.warn(`[plugin-store] ${name}: workflow ${s.file} not imported (${s.errors.join('; ')})`);
+  }
+  return { ok: true, name, workflows, ignored: ignoredContributions(name, cur, { workflowSkips: workflows.skipped }) };
 }

package/src/core/plugin-workflows.mjs

@@ -11,7 +11,9 @@ import { join, basename } from 'node:path';
 import { getDb, prepare, tx } from './db.mjs';
 import { slugify } from './artifacts.mjs';
 import { loadAgentRegistry } from './agent-registry.mjs';
-import { validateWorkflow } from './workflow-validator.mjs';
+import { registryPortsFn } from './graph/registry-ports.mjs';
+import { validateGraph } from '../shared/graph/validate.mjs';
+import { NOT_GRAPH_V2 } from './plugin-manifest.mjs';
 import { pluginCurrentDir } from './plugins-lock.mjs';
 
 /** Uninstall guard error: plugin workflows are still referenced by project state. */
@@ -31,60 +33,102 @@ const normDomain = (raw) => {
 };
 
 /**
- * Upsert every <versionDir>/workflows/*.json into the workflows table.
- * id = wfp_<plugin>_<slug(filename)>, origin = 'plugin:<plugin>'. Each template
- * is validated (workflow-validator) against the MERGED registry — importing runs
- * AFTER the symlink swap + lock write, so the plugin's own agents resolve. An
- * invalid/unreadable template is skipped with a warning, never thrown (spec §9.3).
- * No workflows/ dir => { imported: [], skipped: [] } (feature-off no-op).
- * @param {string} name       plugin name (kebab-case; id stays SAFE_WORKFLOW_ID-legal)
- * @param {string} versionDir the exported version dir (or current/ — same tree)
- * @returns {Promise<{imported: string[], skipped: Array<{file:string, errors:string[]}>}>}
+ * READ + VALIDATE every <versionDir>/workflows/*.json WITHOUT touching the DB.
+ * Split out of importPluginWorkflows so the Plugins card, the doctor and the
+ * install receipt can name a skipped template with the SAME reason the importer
+ * logged — a second, re-derived reader would be free to disagree with it.
+ * @param {string} name
+ * @param {string} versionDir
+ * @param {{registry?: object, quiet?: boolean}} [opts] registry: reuse ONE
+ *        loadAgentRegistry() across plugins; quiet: no console.warn (read-only
+ *        callers must not re-log what the importer already logged).
+ * @returns {{ready: Array<object>, skipped: Array<{file:string, errors:string[]}>}}
  */
-export async function importPluginWorkflows(name, versionDir) {
+export function readPluginWorkflows(name, versionDir, { registry = null, quiet = false } = {}) {
   const origin = `plugin:${name}`;
   const dir = join(versionDir, 'workflows');
   let files = [];
   try { files = readdirSync(dir).filter((f) => f.endsWith('.json')).sort(); } catch { /* no workflows/ */ }
-  const imported = [];
+  const ready = [];
   const skipped = [];
-  if (!files.length) return { imported, skipped };
-  getDb(); // open + migrate: workflows.origin exists (SCHEMA_V13, Task 10)
-  const registry = loadAgentRegistry(); // merged builtin+user+plugin (Task 6)
-  const now = new Date().toISOString();
+  if (!files.length) return { ready, skipped };
+  // ONE registry load for the whole read, and the SHARED port synthesis over
+  // it: agent meta ports plus the universal `await` gate and the flow-card
+  // table. The templates are not in the DB yet, so resolveGraph is unavailable —
+  // registryPortsFn exists for exactly this caller and the server's save route.
+  const portsFn = registryPortsFn(registry || loadAgentRegistry());
+  const warn = (msg) => { if (!quiet) console.warn(msg); };
+  const skip = (f, errors) => {
+    skipped.push({ file: f, errors });
+    warn(`[plugin-workflows] ${name}/${f}: invalid template — skipped (${errors.join('; ')})`);
+  };
   for (const f of files) {
     let raw;
     try {
       raw = JSON.parse(readFileSync(join(dir, f), 'utf8'));
     } catch (err) {
       skipped.push({ file: f, errors: [`unreadable JSON: ${err.message}`] });
-      console.warn(`[plugin-workflows] ${name}/${f}: unreadable JSON — skipped`);
-      continue;
-    }
-    const tpl = {
-      steps: Array.isArray(raw?.steps) ? raw.steps : [],
-      feedbacks: Array.isArray(raw?.feedbacks) ? raw.feedbacks : [],
-    };
-    const v = validateWorkflow(tpl, registry);
-    if (!v.ok) {
-      skipped.push({ file: f, errors: v.errors });
-      console.warn(`[plugin-workflows] ${name}/${f}: invalid template — skipped (${v.errors.join('; ')})`);
+      warn(`[plugin-workflows] ${name}/${f}: unreadable JSON — skipped`);
       continue;
     }
+    // A v1 `steps` template is called out by name rather than left to V1's
+    // generic "version must be 2": the plugin author needs to know their
+    // template needs porting, not that a field is off by one. Same clause the
+    // validator prints, imported so the two can never drift.
+    if (Number(raw?.version) !== 2) { skip(f, [NOT_GRAPH_V2]); continue; }
     const id = `wfp_${name}_${slugify(basename(f, '.json'))}`;
     const rowName = typeof raw.name === 'string' && raw.name.trim() ? raw.name.trim() : basename(f, '.json');
+    const domain = normDomain(raw.domain);
+    const nodes = Array.isArray(raw.nodes) ? raw.nodes : [];
+    const wires = Array.isArray(raw.wires) ? raw.wires : [];
+    // The FULL kind set {agent, task, and, or, combine, end} and every rule
+    // V1-V21 — including V20/V21's mandatory Task + End cards and V7's
+    // one-wire-per-input — apply to a plugin template exactly as they do to a
+    // hand-composed one. Warnings never block an import (they do not block a
+    // save either); they are logged so a template that will misbehave at run
+    // time says so at install.
+    const { errors, warnings } = validateGraph({ id, name: rowName, version: 2, domain, nodes, wires }, portsFn);
+    if (errors.length) { skip(f, errors.map((e) => `${e.code}: ${e.message}`)); continue; }
+    for (const w of warnings) warn(`[plugin-workflows] ${name}/${f}: ${w.code}: ${w.message}`);
+    // graph holds {nodes, wires, canvas?} ONLY — id/name/domain/origin are row
+    // columns, so a rename can never drift between the two.
+    const graph = { nodes, wires };
+    if (raw.canvas && typeof raw.canvas === 'object') graph.canvas = raw.canvas; // accepted, engine-ignored
+    ready.push({ file: f, id, rowName, domain, graph, origin });
+  }
+  return { ready, skipped };
+}
+
+/**
+ * Upsert every <versionDir>/workflows/*.json into the workflows table.
+ * id = wfp_<plugin>_<slug(filename)>, origin = 'plugin:<plugin>'. Each template
+ * is validated by the SHARED `validateGraph` over `registryPortsFn(loadAgentRegistry())`
+ * — importing runs AFTER the symlink swap + lock write, so the plugin's own agents resolve. An
+ * invalid/unreadable template is skipped with a warning, never thrown (spec §9.3).
+ * No workflows/ dir => { imported: [], skipped: [] } (feature-off no-op).
+ * @param {string} name       plugin name (kebab-case; id stays SAFE_WORKFLOW_ID-legal)
+ * @param {string} versionDir the exported version dir (or current/ — same tree)
+ * @returns {Promise<{imported: string[], skipped: Array<{file:string, errors:string[]}>}>}
+ */
+export async function importPluginWorkflows(name, versionDir) {
+  const { ready, skipped } = readPluginWorkflows(name, versionDir);
+  const imported = [];
+  if (!ready.length && !skipped.length) return { imported, skipped };
+  getDb(); // open + migrate: workflows.origin/graph/archived_at exist (V13/V23)
+  const now = new Date().toISOString();
+  for (const r of ready) {
     tx(() => {
       prepare(`
-        INSERT INTO workflows (id, name, version, domain, steps, feedbacks, origin, created_at, updated_at)
-        VALUES (?, ?, 1, ?, ?, ?, ?, ?, ?)
+        INSERT INTO workflows (id, name, version, domain, graph, steps, feedbacks, origin, created_at, updated_at, archived_at)
+        VALUES (?, ?, 2, ?, ?, '[]', '[]', ?, ?, ?, NULL)
         ON CONFLICT(id) DO UPDATE SET
-          name = excluded.name, version = 1, domain = excluded.domain,
-          steps = excluded.steps, feedbacks = excluded.feedbacks,
-          origin = excluded.origin, updated_at = excluded.updated_at
-      `).run(id, rowName, normDomain(raw.domain), JSON.stringify(tpl.steps),
-             JSON.stringify(tpl.feedbacks), origin, now, now);
+          name = excluded.name, version = 2, domain = excluded.domain,
+          graph = excluded.graph, steps = '[]', feedbacks = '[]',
+          origin = excluded.origin, updated_at = excluded.updated_at,
+          archived_at = NULL
+      `).run(r.id, r.rowName, r.domain, JSON.stringify(r.graph), r.origin, now, now);
     });
-    imported.push(id);
+    imported.push(r.id);
   }
   return { imported, skipped };
 }
@@ -163,15 +207,20 @@ export function referencedPluginAgents(name) {
   getDb();
   const out = [];
   for (const row of prepare(
-    'SELECT id, name, steps FROM workflows WHERE origin IS NULL OR origin != ?',
+    'SELECT id, name, steps, graph FROM workflows WHERE origin IS NULL OR origin != ?',
   ).all(`plugin:${name}`)) {
-    let steps;
-    try { steps = JSON.parse(row.steps); } catch { continue; }
     const found = new Set();
+    let steps;
+    try { steps = JSON.parse(row.steps); } catch { steps = null; }
     for (const group of Array.isArray(steps) ? steps : []) {
-      for (const node of Array.isArray(group) ? group : []) {
-        if (node && keys.has(node.key)) found.add(node.key);
-      }
+      for (const node of Array.isArray(group) ? group : []) if (node && keys.has(node.key)) found.add(node.key);
+    }
+    let graph;
+    try { graph = JSON.parse(row.graph || 'null'); } catch { graph = null; }
+    // v2 rows: only kind 'agent' nodes carry a key (a task/end/and/or/combine
+    // card never does), so the walk is narrowed rather than key-only.
+    for (const node of Array.isArray(graph?.nodes) ? graph.nodes : []) {
+      if (node && node.kind === 'agent' && keys.has(node.key)) found.add(node.key);
     }
     if (found.size) out.push({ workflowId: row.id, name: row.name, keys: [...found].sort() });
   }