@worca/app 1.0.0 → 1.1.1

package/src/core/pipeline-delete.mjs

@@ -30,6 +30,7 @@ import {
 } from './run-manifest.mjs';
 import { branchExists, hasGh, findPrForBranch } from './git-info.mjs';
 import { retainedWorkPatchName } from './results.mjs';
+import { deleteCommentsForRun } from './diff-comments.mjs';
 
 // Statuses for which deletion is refused (the entry is or may be live).
 const ACTIVE = new Set(['running', 'starting', 'created', 'pausing']);
@@ -60,8 +61,12 @@ function lookupRow(storeKey, id) {
  */
 function artifactAbsPath(relPath, pipelineDir, storeRootDir) {
   if (isAbsolute(relPath)) return relPath;
-  if (relPath.startsWith('plans/') || relPath.startsWith('reviews/')) return join(storeRootDir, relPath);
-  return join(pipelineDir, relPath);
+  // Rows are indexed with '/' (see _recordArtifact); rows written by earlier
+  // Windows builds carry '\\' — normalise before the layout check so those
+  // shared plan/review files are still re-rooted (and unlinked) correctly.
+  const rel = relPath.replace(/\\/g, '/');
+  if (rel.startsWith('plans/') || rel.startsWith('reviews/')) return join(storeRootDir, rel);
+  return join(pipelineDir, rel);
 }
 
 /**
@@ -252,6 +257,12 @@ export async function archivePipeline({ projectDir = null, key = null, workspace
   //    pipeline_steps and the other children stay: stats fallback sums need them.
   tx(() => {
     getDb().prepare('DELETE FROM artifacts WHERE pipeline_id = ?').run(row.id);
+    // The run dir (and with it diff-patch.patch) was just removed, so nothing could
+    // re-anchor these comments and creation is refused from here on. They die with
+    // the artifacts index rather than lingering as unreachable rows — the declared
+    // pipelines cascade cannot do it, because the pipelines row is never DELETEd
+    // (see this file's header).
+    deleteCommentsForRun(row.id);
     getDb().prepare('UPDATE pipelines SET archived_at = ? WHERE id = ?')
       .run(new Date().toISOString(), row.id);
   });

package/src/core/plugin-api.mjs

@@ -8,6 +8,11 @@
 // core graph.
 //
 // API 2 adds the chatChannels contribution + persistent channel worker
-// protocol; the task-source connector contract is unchanged between 1 and 2.
-export const WORCA_PLUGIN_API = 2;
-export const WORCA_PLUGIN_APIS = [1, 2];
+// 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];

package/src/core/plugin-config.mjs

@@ -1,8 +1,19 @@
 // src/core/plugin-config.mjs
 // Per-plugin settings/secrets/state under <pluginDir>/data (spec §5, §7.6).
-// Secrets: data/secrets.json, mode 0600, atomic temp+rename (settings.mjs:89-92
-// idiom), {"$env":"VAR"} indirection resolved at READ time only — stored
-// verbatim so the value never touches disk. Explicitly NOT in worca-cc.db.
+//
+// PROFILES: every file is keyed by profile id, so one plugin can hold several
+// complete, independent setups — two Jira servers, two GitHub orgs — instead of
+// one that gets overwritten each time you switch. A source that does not declare
+// multiProfile simply never uses more than the DEFAULT_PROFILE bucket, which is
+// created implicitly, so single-profile plugins need no special handling here.
+//
+//   config.json  { "$format": "profiles/1", "profiles": { "<id>": { key: value } } }
+//   secrets.json { "$format": "profiles/1", "profiles": { "<id>": { … } } }   mode 0600
+//   state.json   { "$format": "profiles/1", "profiles": { "<id>": { … } } }
+//
+// Secrets: mode 0600, atomic temp+rename (settings.mjs:89-92 idiom),
+// {"$env":"VAR"} indirection resolved at READ time only — stored verbatim so the
+// value never touches disk. Explicitly NOT in worca-cc.db.
 // All functions are sync (contract; callers are the shim + server routes).
 
 import { readFileSync, writeFileSync, renameSync, mkdirSync, chmodSync } from 'node:fs';
@@ -10,6 +21,24 @@ import { join, dirname } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { pluginDataDir } from './plugins-lock.mjs';
 
+/** The bucket every source gets for free; the only one a single-profile source uses. */
+export const DEFAULT_PROFILE = 'default';
+
+/** Profile ids are directory-safe and URL-safe: they become path segments in a
+ *  connector's own storage (jira-source hangs a $JTR_CONFIG_DIR off one) and
+ *  route params on /api/plugins/:name/profiles/:id. */
+export const PROFILE_ID_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+export function isValidProfileId(id) {
+  return PROFILE_ID_RE.test(String(id ?? ''));
+}
+
+function profileId(id) {
+  const p = id == null || id === '' ? DEFAULT_PROFILE : String(id);
+  if (!isValidProfileId(p)) throw new Error(`invalid profile id "${p}" (lowercase letters, digits and dashes)`);
+  return p;
+}
+
 function readJson(file) {
   try {
     const v = JSON.parse(readFileSync(file, 'utf8'));
@@ -19,6 +48,36 @@ function readJson(file) {
   }
 }
 
+/** In-band format marker for the profile envelope. No shape heuristic can be
+ *  exact here: config keys come from configSchema, but STATE keys are whatever
+ *  a connector passed to ctx.state.set(), so a legacy flat file may legally be
+ *  { "profiles": { <id>: {...} } } byte-for-byte — data, not envelope. Only the
+ *  marker distinguishes the two, and only writeBucket/deleteProfile emit it. */
+const ENVELOPE_FORMAT = 'profiles/1';
+
+const isBag = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+
+/** The marked { $format, profiles: {...} } envelope, tolerant of a
+ *  missing/garbage file. A file WITHOUT the marker is a pre-profiles flat bag
+ *  ({ key: value } at the top level) — read it, whole and unjudged, as the
+ *  implicit DEFAULT_PROFILE bucket so an upgrade never orphans stored
+ *  config/secrets/state; the next writeBucket persists the marked envelope. */
+function readBuckets(file) {
+  const raw = readJson(file);
+  if (raw.$format === ENVELOPE_FORMAT && isBag(raw.profiles)) {
+    return Object.fromEntries(
+      Object.entries(raw.profiles).filter(([id, bag]) => isValidProfileId(id) && isBag(bag)),
+    );
+  }
+  return Object.keys(raw).length ? { [DEFAULT_PROFILE]: raw } : {};
+}
+
+/** One profile's bag from a file. */
+function readBucket(file, profile) {
+  const b = readBuckets(file)[profile];
+  return b && typeof b === 'object' && !Array.isArray(b) ? b : {};
+}
+
 function writeJsonAtomic(file, obj, { mode } = {}) {
   mkdirSync(dirname(file), { recursive: true });
   const tmp = `${file}.${randomBytes(4).toString('hex')}.tmp`;
@@ -27,20 +86,101 @@ function writeJsonAtomic(file, obj, { mode } = {}) {
   renameSync(tmp, file);
 }
 
+/** Replace one profile's bag inside a file, leaving every other profile alone. */
+function writeBucket(file, profile, bucket, opts) {
+  const all = readBuckets(file);
+  all[profile] = bucket;
+  writeJsonAtomic(file, { $format: ENVELOPE_FORMAT, profiles: all }, opts);
+}
+
 const isEnvRef = (v) => !!v && typeof v === 'object' && !Array.isArray(v) && typeof v.$env === 'string';
 /** The exact redaction marker redactedConfig emits — must never be persisted. */
 const isSetMarker = (v) => !!v && typeof v === 'object' && v.set === true && Object.keys(v).length === 1;
 
 function files(name) {
   const dir = pluginDataDir(name);
-  return { config: join(dir, 'config.json'), secrets: join(dir, 'secrets.json'), state: join(dir, 'state.json') };
+  return {
+    config: join(dir, 'config.json'),
+    secrets: join(dir, 'secrets.json'),
+    state: join(dir, 'state.json'),
+    profiles: join(dir, 'profiles.json'),
+  };
 }
 
-/** Merged config.json + secrets.json (secrets win), schema defaults applied,
- *  {"$env":"VAR"} resolved (unset env -> null). */
-export function readPluginConfig(name, configSchema = []) {
+// ── profiles ──────────────────────────────────────────────────────────────────
+// The roster lives in its own file rather than being inferred from config.json's
+// keys: a profile is real the moment it is created, BEFORE anything is saved into
+// it, and it keeps a human label the id cannot carry.
+
+/**
+ * Every profile of a plugin, in creation order.
+ * @returns {Array<{id:string, label:string}>}
+ */
+export function listProfiles(name) {
+  const raw = readJson(files(name).profiles);
+  const list = Array.isArray(raw.profiles) ? raw.profiles : [];
+  return list
+    .filter((p) => p && isValidProfileId(p.id))
+    .map((p) => ({ id: String(p.id), label: String(p.label || p.id) }));
+}
+
+/** Just the ids — the shape resolveProfile()/the UI gate want. */
+export function listProfileIds(name) {
+  return listProfiles(name).map((p) => p.id);
+}
+
+/**
+ * Create a profile. Idempotent on the id (a repeat call updates the label only),
+ * so a caller that ensures DEFAULT_PROFILE on every save cannot duplicate it.
+ * @returns {{id:string, label:string}}
+ */
+export function createProfile(name, id, label) {
+  const pid = profileId(id);
+  // The default bucket is shared plumbing, not a profile: chat channels, model
+  // secrets and migrated pre-profiles config all live in it via profile-less
+  // reads. Enrolling "default" in the roster would make that shared bucket
+  // deletable like any member — one Remove click away from wiping them all.
+  if (pid === DEFAULT_PROFILE) throw new Error(`profile id "${DEFAULT_PROFILE}" is reserved`);
+  const list = listProfiles(name);
+  const at = list.findIndex((p) => p.id === pid);
+  const entry = { id: pid, label: String(label || (at >= 0 ? list[at].label : pid)) };
+  if (at >= 0) list[at] = entry;
+  else list.push(entry);
+  writeJsonAtomic(files(name).profiles, { profiles: list });
+  return entry;
+}
+
+/**
+ * Delete a profile and everything stored under it (config, secrets, state).
+ * Callers are responsible for the bindings that named it — see
+ * source-bindings.mjs#clearBindingsForProfile.
+ */
+export function deleteProfile(name, id) {
+  const pid = profileId(id);
+  // Same reservation as createProfile — and a backstop for a roster that
+  // enrolled "default" before the reservation existed: deleting it would strip
+  // the shared bucket (chat-channel config, model secrets, migrated legacy
+  // data) out of all three files.
+  if (pid === DEFAULT_PROFILE) throw new Error(`profile id "${DEFAULT_PROFILE}" is reserved — its bucket backs every profile-less read`);
   const f = files(name);
-  const raw = { ...readJson(f.config), ...readJson(f.secrets) };
+  writeJsonAtomic(f.profiles, { profiles: listProfiles(name).filter((p) => p.id !== pid) });
+  for (const [file, opts] of [[f.config, undefined], [f.secrets, { mode: 0o600 }], [f.state, undefined]]) {
+    const all = readBuckets(file);
+    if (!(pid in all)) continue;
+    delete all[pid];
+    writeJsonAtomic(file, { $format: ENVELOPE_FORMAT, profiles: all }, opts);
+  }
+  return { ok: true };
+}
+
+// ── config ────────────────────────────────────────────────────────────────────
+
+/** Merged config.json + secrets.json for ONE profile (secrets win), schema
+ *  defaults applied, {"$env":"VAR"} resolved (unset env -> null). */
+export function readPluginConfig(name, configSchema = [], profile) {
+  const pid = profileId(profile);
+  const f = files(name);
+  const raw = { ...readBucket(f.config, pid), ...readBucket(f.secrets, pid) };
   const out = {};
   for (const field of configSchema) {
     let v = raw[field.key];
@@ -51,13 +191,15 @@ export function readPluginConfig(name, configSchema = []) {
   return out;
 }
 
-/** Route values by schema: secret:true -> secrets.json (0600), else config.json.
- *  undefined / redaction-marker values keep the prior stored value; null clears.
- *  $env refs are stored verbatim. Both writes are temp+rename atomic. */
-export function writePluginConfig(name, configSchema = [], values = {}) {
+/** Route values by schema: secret:true -> secrets.json (0600), else config.json,
+ *  both inside `profile`'s bucket. undefined / redaction-marker values keep the
+ *  prior stored value; null clears. $env refs are stored verbatim. Both writes
+ *  are temp+rename atomic. */
+export function writePluginConfig(name, configSchema = [], values = {}, profile) {
+  const pid = profileId(profile);
   const f = files(name);
-  const config = readJson(f.config);
-  const secrets = readJson(f.secrets);
+  const config = readBucket(f.config, pid);
+  const secrets = readBucket(f.secrets, pid);
   const secretKeys = new Set(configSchema.filter((x) => x && x.secret).map((x) => x.key));
   for (const [k, v] of Object.entries(values && typeof values === 'object' ? values : {})) {
     if (v === undefined || isSetMarker(v)) continue; // absent / echoed marker -> keep prior
@@ -67,17 +209,19 @@ export function writePluginConfig(name, configSchema = [], values = {}) {
     if (v === null) delete bucket[k];
     else bucket[k] = v;
   }
-  writeJsonAtomic(f.config, config);
-  writeJsonAtomic(f.secrets, secrets, { mode: 0o600 });
+  writeBucket(f.config, pid, config);
+  writeBucket(f.secrets, pid, secrets, { mode: 0o600 });
   return { ok: true };
 }
 
-/** UI echo shape: secrets -> { set: true|false } markers, non-secrets verbatim
- *  (with defaults). Secret VALUES never reach the browser after save (§7.6). */
-export function redactedConfig(name, configSchema = []) {
+/** UI echo shape for ONE profile: secrets -> { set: true|false } markers,
+ *  non-secrets verbatim (with defaults). Secret VALUES never reach the browser
+ *  after save (§7.6). */
+export function redactedConfig(name, configSchema = [], profile) {
+  const pid = profileId(profile);
   const f = files(name);
-  const config = readJson(f.config);
-  const secrets = readJson(f.secrets);
+  const config = readBucket(f.config, pid);
+  const secrets = readBucket(f.secrets, pid);
   const out = {};
   for (const field of configSchema) {
     if (field.secret) out[field.key] = { set: secrets[field.key] !== undefined };
@@ -86,15 +230,21 @@ export function redactedConfig(name, configSchema = []) {
   return out;
 }
 
-/** Connector KV (cursors, etags) — host-persisted ctx.state backing (§7.1). */
-export function readPluginState(name) {
-  return readJson(files(name).state);
+// ── connector state ───────────────────────────────────────────────────────────
+
+/** Connector KV for ONE profile (cursors, etags) — host-persisted ctx.state
+ *  backing (§7.1). Per-profile so two instances of the same source cannot read
+ *  back each other's cached cursors. */
+export function readPluginState(name, profile) {
+  return readBucket(files(name).state, profileId(profile));
 }
 
-/** Shallow-merge patch into state.json, atomic write. Returns the new state. */
-export function writePluginState(name, patch = {}) {
+/** Shallow-merge patch into one profile's state, atomic write. Returns the new
+ *  bag for that profile. */
+export function writePluginState(name, patch = {}, profile) {
+  const pid = profileId(profile);
   const f = files(name);
-  const next = { ...readJson(f.state), ...(patch && typeof patch === 'object' ? patch : {}) };
-  writeJsonAtomic(f.state, next);
+  const next = { ...readBucket(f.state, pid), ...(patch && typeof patch === 'object' ? patch : {}) };
+  writeBucket(f.state, pid, next);
   return next;
 }

package/src/core/plugin-inventory.mjs

@@ -29,8 +29,12 @@ export async function inventoryFromCache(repoUrl, sha, subdir, { exec = defaultE
     // be parsed as a git option (defense layer 2; the parser rejects it too).
     await exec('git', ['--git-dir', repoCacheDir(repoUrl), 'archive', '--format=tar', '-o', tar,
       ...(subdir ? [sha, '--', subdir] : [sha])]);
-    await exec('tar', ['-xf', tar, '-C', tmp,
-      ...(subdir ? ['--strip-components', String(subdir.split('/').length)] : [])]);
+    // Extract with cwd = tmp (the destination) so tar never receives a native
+    // Windows path: Git-for-Windows GNU tar reads a colon in `-f` as a `host:path`
+    // remote spec ("cannot connect to C:") and cannot parse backslash separators.
+    // A relative `-f` and no `-C` sidesteps both; the archive lands in cwd.
+    await exec('tar', ['-xf', 'x.tar',
+      ...(subdir ? ['--strip-components', String(subdir.split('/').length)] : [])], { cwd: tmp });
     await rm(tar, { force: true });
     // Defense-in-depth for the consent display: strip any symlink that escapes the
     // export root before inventorying (the tmp dir is deleted in finally regardless).

package/src/core/plugin-manifest.mjs

@@ -5,8 +5,11 @@
 
 import { readFileSync, readdirSync, readlinkSync, existsSync } from 'node:fs';
 import { join, resolve, dirname, sep, isAbsolute } from 'node:path';
-import { WORCA_PLUGIN_APIS } from './plugin-api.mjs';
-import { EFFORTS, isReservedModelEnvKey } from './model-env.mjs';
+import { WORCA_PLUGIN_API, WORCA_PLUGIN_APIS } from './plugin-api.mjs';
+import { EFFORTS, isReservedModelEnvKey, assertModelCost } 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';
 
 /** 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]+)*$/;
@@ -17,12 +20,12 @@ const SOURCE_ID_RE = /^[a-z][a-z0-9-]{0,63}$/;
 const FIELD_TYPES = new Set(['text', 'select']);
 const INPUT_TYPES = new Set(['text', 'select', 'remote-select', 'task-browser']);
 const KNOWN_TOP = new Set(['name', 'version', 'description', 'author', 'homepage', 'license', 'engines', 'taskSources', 'chatChannels', 'setup', 'models', 'modelSecrets']);
-const KNOWN_SOURCE = new Set(['id', 'displayName', 'module', 'configSchema', 'inputs']);
+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']);
+const KNOWN_MODEL = new Set(['id', 'label', 'efforts', 'env', 'cost']);
 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)
@@ -68,6 +71,86 @@ export function negotiatedApi(range, apis = WORCA_PLUGIN_APIS) {
   return best;
 }
 
+/** The ONE per-file sentence for each half of the data contract. `validatePluginDir`
+ *  prefixes `agents/<f>: ` / `workflows/<f>: `; `agent-registry.scanLayer` prefixes the
+ *  layer and appends ` — ignored`; `plugin-workflows` uses NOT_GRAPH_V2 verbatim as a
+ *  skip reason. Exported so those three sites can never drift apart — never re-word
+ *  either string in a second place. */
+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 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).
+ *  @param {string} range  @returns {number|null} */
+export function declaredApi(range) {
+  for (let n = 0; n <= 99; n += 1) if (apiSatisfies(range, n)) return n;
+  return null;
+}
+
+/** Which files in a plugin dir are still on the API-2 data contract: sidecars
+ *  without metaVersion 2, templates without version 2. Pure fs read; an absent
+ *  or unreadable dir/file contributes nothing (validatePluginDir reports those
+ *  separately as parse errors). Basenames only — the caller prefixes them.
+ *  @param {string} absDir
+ *  @returns {{agentsV1: string[], workflowsV1: string[]}} */
+export function dataContractIssues(absDir) {
+  const agentsV1 = [];
+  const workflowsV1 = [];
+  const read = (p) => { try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return null; } };
+  const agentsDir = join(absDir, 'agents');
+  if (existsSync(agentsDir)) {
+    for (const f of readdirSync(agentsDir).filter((x) => x.endsWith('.meta.json')).sort()) {
+      const raw = read(join(agentsDir, f));
+      if (raw && Number(raw.metaVersion) !== 2) agentsV1.push(f);
+    }
+  }
+  const wfDir = join(absDir, 'workflows');
+  if (existsSync(wfDir)) {
+    for (const f of readdirSync(wfDir).filter((x) => x.endsWith('.json')).sort()) {
+      const raw = read(join(wfDir, f));
+      if (raw && Number(raw.version) !== 2) workflowsV1.push(f);
+    }
+  }
+  return { agentsV1, workflowsV1 };
+}
+
+/**
+ * The Plugins-view / doctor payload for a plugin whose DATA is still on the old
+ * contract, or null when it has nothing the host would ignore. The bump is
+ * gated by CONTENT, not by the range: a connector-only plugin declaring
+ * ">=1 <2" ships no agents and no templates, so it is never "incompatible" —
+ * it simply keeps negotiating API 1.
+ * @param {string} range   engines['worca-cc-api']
+ * @param {{agentsV1: string[], workflowsV1: string[]}} issues
+ * @returns {{builtFor: number|null, host: number, agents: number, workflows: number, message: string}|null}
+ */
+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;
+  // 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 };
+  mismatch.message = apiMismatchMessage(mismatch);
+  return mismatch;
+}
+
+/**
+ * THE per-plugin sentence (spec §9 wording, "worca" is the product name) —
+ * rendered verbatim by the Plugins view (`p.apiMismatch.message`), the doctor's
+ * `agents-api` check and `worca plugin list`. An API-outdated plugin is NOT
+ * corrupt: it installed fine and its connector or chat channel still works —
+ * worca simply ignores the agents and pipeline templates it ships.
+ */
+export function apiMismatchMessage(mismatch) {
+  if (!mismatch) return '';
+  const { builtFor, agents, workflows } = 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)`;
+}
+
 const str = (v, d = '') => (typeof v === 'string' ? v.trim() : d);
 
 function normOptions(raw) {
@@ -117,6 +200,31 @@ function badModulePath(mod) {
   return null;
 }
 
+/**
+ * `agentFile` is a PATH, not a label: agent-registry.mjs stamps
+ * `agentPath = join(<layer>/agents, meta.agentFile)` and workflows.mjs reads
+ * THAT file as the agent's system prompt AND for its `tools:` frontmatter. So
+ * it is gated exactly like `module` — relative, no "..", and it must still
+ * resolve inside the agents dir. Absent/empty is legal (the agent then has no
+ * prompt file). Returns a reason clause or null, like badModulePath.
+ */
+function badAgentFile(agentFile, agentsDir) {
+  if (agentFile === undefined || agentFile === null || agentFile === '') return null;
+  if (typeof agentFile !== 'string') return 'must be a string';
+  const af = agentFile.trim();                       // the normalizer trims: judge the string the runtime will use
+  if (!af) return null;
+  if (isAbsolute(af) || /\\/.test(af)) return 'must be a relative path inside agents/';
+  if (af.split('/').includes('..')) return 'must not contain ".."';
+  const root = resolve(agentsDir);
+  if (!resolve(root, af).startsWith(root + sep)) return 'must be a relative path inside agents/';
+  // A contained agentFile must also EXIST: consent and the runtime both read it,
+  // so a name with no file behind it says one thing at consent time ("none
+  // declared") and another at run time (workflows.loadAgentFile used to fall
+  // back into the BUILT-IN agents dir for the same basename).
+  if (!existsSync(join(root, af))) return `${af} not found in agents/`;
+  return null;
+}
+
 /**
  * Normalize a parsed worca-cc-plugin.json (spec §4.1). Only `name` is required.
  * Unknown fields are ignored and collected as warnings (validatePluginDir
@@ -195,7 +303,14 @@ export function normalizeManifest(raw, { dir = '' } = {}) {
       if (browsers !== 1) {
         errors.push(`${at} ("${id}"): must declare exactly ONE input of type "task-browser" (found ${browsers}) — it is what produces the task (spec §7.4)`);
       }
-      taskSources.push({ id, displayName: str(s.displayName) || id, module, configSchema, inputs });
+      // multiProfile: the source can hold several independent configurations
+      // (two Jira servers, two GitHub orgs), each bound to a project/workspace.
+      // Opt-in, because it changes the settings UI from one form to a roster —
+      // a single-instance source should not pay that.
+      taskSources.push({
+        id, displayName: str(s.displayName) || id, module, configSchema, inputs,
+        multiProfile: s.multiProfile === true,
+      });
     });
   }
   const ids = taskSources.map((s) => s.id);
@@ -293,7 +408,13 @@ export function normalizeManifest(raw, { dir = '' } = {}) {
         return;
       }
       for (const [k, v] of Object.entries(envRaw)) {
-        if (isReservedModelEnvKey(k)) { errors.push(`${at} ("${id}"): env key ${JSON.stringify(k)} is reserved and cannot be set on a model`); continue; }
+        // Reserved keys degrade, never reject: a published manifest is a
+        // third-party artifact its user cannot edit, and the spawn-time filter
+        // (model-env.mjs prepareModelEnv) drops these defensively anyway — so a
+        // host that grows the reserved list (e.g. CLAUDE_CODE_SUBAGENT_MODEL)
+        // must not retroactively brick installed/marketplace plugins. The
+        // user's own catalog (settings.mjs) still hard-rejects: that author CAN fix it.
+        if (isReservedModelEnvKey(k)) { warnings.push(`${at} ("${id}"): env key ${JSON.stringify(k)} is reserved — ignored`); continue; }
         if (isSecretRef(v)) {
           if (!secretKeys.has(v.secret)) { errors.push(`${at} ("${id}"): env ${k} references undeclared modelSecrets key ${JSON.stringify(v.secret)}`); continue; }
           env[k] = { secret: v.secret };
@@ -303,10 +424,23 @@ export function normalizeManifest(raw, { dir = '' } = {}) {
           errors.push(`${at} ("${id}"): env value for ${JSON.stringify(k)} must be a non-empty string or {"secret": "<key>"}`);
         }
       }
+      // A plugin that ships a model routed at its OWN endpoint is exactly the
+      // case that needs a price pinned (the CLI would price it by NAME), so a
+      // manifest may carry `cost` — same shape, same validator as a global
+      // catalog entry (model-env.mjs). A user's global entry for the same id
+      // still wins, as it does for label/efforts/env (§9.3).
+      let cost;
+      try {
+        cost = assertModelCost(m.cost);
+      } 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 } : {}),
       });
     });
     const mids = models.map((m) => m.id.toLowerCase());
@@ -392,8 +526,26 @@ export function validatePluginDir(absDir, { strict = false } = {}) {
     }
   }
 
-  // agents/: <key>.md + <key>.meta.json pairs, existing dual-file format (§4.2)
+  // agents/: <key>.md + <key>.meta.json pairs, existing dual-file format (§4.2).
+  // API 3: the sidecar must pass the SAME meta v2 gate the agent-store save path
+  // applies, every failed rule named. ALL capability fields are open to plugins
+  // (verdict, sideEffect, mockRole, workspace*, placeable, …) — the gate is the
+  // schema, not an allow-list.
   const agentKeys = new Set();
+  // Keys whose sidecar EXISTS but was rejected by a gate below. They are not
+  // shipped (no ports), yet they are not foreign either — the workflows block
+  // owes a template that references one a single accurate cause rather than
+  // "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.
+  const hardData = raw !== null
+    && (strict || negotiatedApi(raw && raw.engines ? raw.engines['worca-cc-api'] : '') === WORCA_PLUGIN_API);
+  const dataLevel = hardData ? 'error' : 'warn';
   const agentsDir = join(absDir, 'agents');
   if (existsSync(agentsDir)) {
     const files = readdirSync(agentsDir);
@@ -406,7 +558,19 @@ export function validatePluginDir(absDir, { strict = false } = {}) {
       if (!KEY_RE.test(key)) { push('error', `agents/${f}: "${key}" must be a valid agent key (letters/digits/_-)`); continue; }
       if (key !== stem) push('error', `agents/${f}: key "${key}" must match the filename stem "${stem}"`);
       if (!files.includes(`${stem}.md`)) push('error', `agents/${f}: missing sibling ${stem}.md`);
+      // Path traversal is never softened by dataLevel: an escaping agentFile is
+      // a security defect in a v1 sidecar exactly as in a v2 one, and it is
+      // checked BEFORE the meta gate so exactly one cause is reported.
+      const afErr = badAgentFile(meta.agentFile, agentsDir);
+      if (afErr) { push('error', `agents/${f}: "agentFile" ${afErr}`); ungatedKeys.add(key); continue; }
+      if (Number(meta.metaVersion) !== 2) { push(dataLevel, `agents/${f}: ${NOT_META_V2}`); ungatedKeys.add(key); continue; }
+      const { errors } = validateMetaV2(meta);
+      for (const e of errors) push('error', `agents/${f}: ${e}`);
+      if (errors.length) { ungatedKeys.add(key); continue; }
+      // BELOW every gate: a rejected sidecar ships no ports, so counting its key
+      // as shipped is what let a ports-less node reach validateGraph.
       agentKeys.add(key);
+      ownMetas.push(normalizeAgentMeta(meta).meta);
     }
     for (const f of files.filter((x) => x.endsWith('.md'))) {
       const stem = f.slice(0, -3);
@@ -426,18 +590,42 @@ export function validatePluginDir(absDir, { strict = false } = {}) {
     }
   }
 
-  // workflows/*.json may reference ONLY the plugin's own agent keys (§9.3)
+  // workflows/*.json are v2 GRAPHS (API 3), validated by the SAME shared
+  // validator the composer and POST /api/workflows use, over a ports function
+  // built from this plugin's OWN sidecars plus the engine's flow-card ports.
+  // The isolation rule stays: a template may reference only keys this plugin
+  // ships, so a host rename or a deleted user agent can never break it.
   const wfDir = join(absDir, 'workflows');
   if (existsSync(wfDir)) {
+    const portsFn = portsFnFor(indexByKey(ownMetas));
     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 (!Array.isArray(tpl?.steps)) { push('error', `workflows/${f}: "steps" must be an array`); continue; }
-      const keys = tpl.steps.flat().map((n) => n?.key).filter(Boolean);
+      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);
+      let unresolved = false;
       for (const k of new Set(keys)) {
-        if (!agentKeys.has(k)) push('error', `workflows/${f}: references agent key "${k}" which this plugin does not ship`);
+        if (agentKeys.has(k)) continue;
+        if (ungatedKeys.has(k)) {
+          // The sidecar is this plugin's, it just did not pass. Report at the
+          // DATA level so an API-1 plugin keeps installing (spec §9) instead of
+          // being refused for a template that is fine.
+          push(dataLevel, `workflows/${f}: references agent key "${k}" whose sidecar is not a valid meta v2 sidecar`);
+        } else {
+          push('error', `workflows/${f}: references agent key "${k}" which this plugin does not ship`);
+        }
+        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;
+      const { errors, warnings } = validateGraph(
+        { ...tpl, nodes, wires: Array.isArray(tpl.wires) ? tpl.wires : [] }, portsFn,
+      );
+      for (const e of errors) push('error', `workflows/${f}: ${e.code}: ${e.message}`);
+      for (const w of warnings) push('warn', `workflows/${f}: ${w.code}: ${w.message}`);
     }
   }
 

package/src/core/plugin-models.mjs

@@ -49,6 +49,7 @@ export function allPluginModels() {
       out.push({
         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)
         secrets: [...new Set(secrets)],
       });
     }