@worca/app 0.0.1

package/src/core/agent-gen.mjs

@@ -0,0 +1,206 @@
+// src/core/agent-gen.mjs
+// The agent-creation wizard's builder engine. An AgentGen is an EventEmitter the
+// server wires onto the WS bus exactly like wireScan wires a WorkspaceScan:
+//   agentgen-progress { genId, phase, message }                       (many)
+//   agentgen-done     { genId, draft: { meta, markdown } }            (terminal)
+//   agentgen-error    { genId, message }                              (terminal)
+// run() NEVER throws. The draft is NOT saved — saving is the wizard's explicit
+// POST /api/agents. Mode A (no userMarkdown): one runClaude writes BOTH the .md
+// body and the meta JSON draft. Mode B (userMarkdown given): the body is the
+// user's verbatim; the LLM writes ONLY the meta JSON, inferred from the body +
+// the neighbors' produces/consumes. Files are read back as authoritative
+// (phases.mjs runWorkspaceScan pattern) then normalized via normalizeMeta.
+
+import { EventEmitter } from 'node:events';
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { mkdir, rm, readFile, writeFile } from 'node:fs/promises';
+import { worcaHome } from './projects.mjs';
+import { runClaude } from './claude-runner.mjs';
+import { resolveModelEnv } from './config.mjs';
+import { normalizeMeta } from './agent-registry.mjs';
+
+const SYSTEM_PROMPT =
+  'You are an expert at writing agent system prompts and machine-readable agent metadata ' +
+  'for worca-cc, a deterministic multi-agent pipeline. Write files exactly where asked. ' +
+  'Metadata must be a single valid JSON object.';
+
+export function createAgentGen(opts = {}) { return new AgentGen(opts); }
+
+class AgentGen extends EventEmitter {
+  constructor(opts = {}) {
+    super();
+    this.name = (typeof opts.name === 'string' && opts.name.trim()) || 'Custom Agent';
+    this.purpose = String(opts.purpose || '');
+    this.details = String(opts.details || '');
+    this.expectedBefore = Array.isArray(opts.expectedBefore) ? opts.expectedBefore : [];
+    this.expectedAfter = Array.isArray(opts.expectedAfter) ? opts.expectedAfter : [];
+    this.userMarkdown = typeof opts.userMarkdown === 'string' && opts.userMarkdown.trim() ? opts.userMarkdown : '';
+    this.channels = Array.isArray(opts.channels) ? opts.channels : [];
+    this.claude = opts.claude || {};
+    this.genId = `agen_${randomUUID()}`;
+    this.scratchDir = join(worcaHome(), 'tmp', 'agent-gen', this.genId.slice(5, 13));
+    this.mdPath = join(this.scratchDir, 'agent.md');
+    this.metaPath = join(this.scratchDir, 'agent.meta.json');
+    this.abort = new AbortController();
+    this.phase = 'draft';
+    this.message = 'preparing…';
+    this.status = 'created';
+    this._terminal = false;
+  }
+
+  getState() {
+    return { genId: this.genId, phase: this.phase, message: this.message, status: this.status };
+  }
+
+  stop() {
+    if (this.status === 'done' || this.status === 'stopped' || this.status === 'error') return;
+    this.status = 'stopped';
+    try { this.abort.abort(); } catch { /* ignore */ }
+  }
+
+  async run() {
+    try {
+      this.status = 'running';
+      this._checkAbort();
+      await mkdir(this.scratchDir, { recursive: true });
+      const metaOnly = !!this.userMarkdown;
+      this._setPhase('draft', metaOnly
+        ? `inferring metadata for "${this.name}" from your markdown…`
+        : `drafting agent + metadata for "${this.name}"…`);
+      if (metaOnly) await writeFile(this.mdPath, this.userMarkdown, 'utf8'); // the LLM reads it
+      await runClaude({
+        cwd: this.scratchDir,
+        systemPrompt: SYSTEM_PROMPT,
+        prompt: metaOnly ? this._metaPrompt() : this._fullPrompt(),
+        allowedTools: ['Read', 'Write'],
+        permissionMode: this.claude.permissionMode || 'acceptEdits',
+        model: this.claude.model,
+        modelEnv: resolveModelEnv(this.claude.model), // catalog routing env (design §4.8)
+        bin: this.claude.bin,
+        mock: this.claude.mock,
+        signal: this.abort.signal,
+        onEvent: (e) => this._onAgentEvent(e),
+      });
+      this._checkAbort();
+      this._setPhase('finalize', 'validating the draft…');
+      // Authoritative read-back (runWorkspaceScan pattern, phases.mjs:803-809).
+      const markdown = metaOnly ? this.userMarkdown : await readFile(this.mdPath, 'utf8');
+      const rawMeta = JSON.parse(await readFile(this.metaPath, 'utf8'));
+      if (!Number.isFinite(Number(rawMeta?.order))) rawMeta.order = 99;
+      const meta = normalizeMeta(rawMeta);
+      if (!meta) throw new Error('the generator produced unusable metadata');
+      if (!String(markdown || '').trim()) throw new Error('the generator produced an empty agent body');
+      this.status = 'done';
+      const draft = { meta, markdown };
+      this._emitTerminal('agentgen-done', { draft });
+      return { status: 'done', draft };
+    } catch (err) {
+      if (isAbort(err) || this.status === 'stopped') {
+        this.status = 'stopped';
+        this._emitTerminal('agentgen-error', { message: 'stopped' });
+        return { status: 'stopped' };
+      }
+      this.status = 'error';
+      const message = (err && err.message) || String(err);
+      this._emitTerminal('agentgen-error', { message });
+      return { status: 'error', message };
+    } finally {
+      await rm(this.scratchDir, { recursive: true, force: true }).catch(() => {});
+    }
+  }
+
+  _neighborBlock() {
+    const j = (list) => JSON.stringify(list.map((m) => ({
+      key: m.key, displayName: m.displayName, produces: m.produces || [],
+      consumes: m.consumes || [], optionalConsumes: m.optionalConsumes || [],
+    })), null, 2);
+    return (
+      `## Pipeline neighbors\n\n` +
+      `Agents expected to run BEFORE this one (their produces are this agent's likely consumes):\n${j(this.expectedBefore)}\n\n` +
+      `Agents expected to run AFTER this one (their consumes are this agent's likely produces):\n${j(this.expectedAfter)}\n\n` +
+      `## Channel vocabulary\n\nconsumes/optionalConsumes/produces MUST use ONLY these ids: ` +
+      `${this.channels.join(', ') || '(see neighbors)'}\n\n`
+    );
+  }
+
+  _metaSchemaBlock() {
+    return (
+      `Write the metadata JSON to: ${this.metaPath}\n` +
+      'EXACT shape (one JSON object): { "key": "<lowerCamel>", "displayName", "description", ' +
+      '"color": "green|peach|red|blue|violet|amber", "runnerType": "producer|verifier", ' +
+      '"loopSource": bool, "fanOut": bool, "asksQuestions": bool, "questionsLocked": bool, ' +
+      '"questionsDefault": bool, "consumes": [..], "optionalConsumes": [..], ' +
+      '"produces": [..], "connectsTo": "*"|["key",..], "order": number }\n' +
+      '"description" is the palette blurb: 1-2 plain sentences, max 160 chars total and the ' +
+      'FIRST sentence max 75 chars (the palette card clamps at 1-2 short lines). It is shown under ' +
+      'the agent name in the composer palette — say what the agent does and what it reads/produces.\n' +
+      'Questions flags: asksQuestions=true if the agent may need a user decision mid-task ' +
+      '(the orchestrator pauses it and resumes it with the answers). questionsLocked=true ONLY if ' +
+      "asking the user is the agent's whole purpose (the user then cannot toggle it in the " +
+      'pipeline menu). questionsDefault=true only for locked-on agents; every other agent ' +
+      'starts OFF and the user opts in per pipeline.\n\n'
+    );
+  }
+
+  _fullPrompt() {
+    return (
+      `# Task: Build a worca-cc agent — ${this.name}\n\n` +
+      `## Purpose\n${this.purpose}\n\n## Detailed description\n${this.details}\n\n` +
+      this._neighborBlock() +
+      '## What to write\n\n' +
+      `1. The agent's system-prompt markdown (role, inputs, outputs, method, output contract) to: ${this.mdPath}\n` +
+      `2. ${this._metaSchemaBlock()}` +
+      'Announce progress with lines starting `DRAFTING `.\n\n' +
+      `MOCK_ROLE: agent-gen\nMOCK_OUT: ${this.mdPath}\nMOCK_JSON: ${this.metaPath}\nMOCK_BASE: ${this.name}\n`
+    );
+  }
+
+  _metaPrompt() {
+    return (
+      `# Task: Infer worca-cc agent metadata — ${this.name}\n\n` +
+      `The user wrote the agent system prompt themselves. Read it at: ${this.mdPath}\n` +
+      'Do NOT modify that file. Derive the metadata from its content and the neighbors below.\n\n' +
+      this._neighborBlock() +
+      `## What to write\n\n${this._metaSchemaBlock()}` +
+      'Announce progress with lines starting `DRAFTING `.\n\n' +
+      `MOCK_ROLE: agent-gen\nMOCK_JSON: ${this.metaPath}\nMOCK_BASE: ${this.name}\n`
+    );
+  }
+
+  _onAgentEvent(e) {
+    const text = typeof e?.text === 'string' ? e.text : '';
+    const m = text.match(/DRAFTING\s+(.{0,80})/i);
+    if (m) this._progress(`drafting ${m[1].trim()}…`);
+  }
+
+  _setPhase(phase, message) { this.phase = phase; this._progress(message); }
+
+  _progress(message) {
+    if (this._terminal) return;
+    if (message) this.message = message;
+    this.emit('agentgen-progress', { genId: this.genId, phase: this.phase, message: this.message });
+  }
+
+  _emitTerminal(type, payload) {
+    if (this._terminal) return;
+    this._terminal = true;
+    this.emit(type, { genId: this.genId, ...payload });
+  }
+
+  _checkAbort() {
+    if (this.abort.signal.aborted || this.status === 'stopped') {
+      const err = new Error('stopped');
+      err.name = 'AbortError';
+      throw err;
+    }
+  }
+}
+
+function isAbort(err) {
+  // NAME only, matching orchestrator.isAbort (kept local: importing it would
+  // create an import cycle). _checkAbort stamps name='AbortError'; a message
+  // sniff also matched real failures mentioning "aborted"/"stopped" and would
+  // end agent generation silently.
+  return !!err && err.name === 'AbortError';
+}

package/src/core/agent-registry.mjs

@@ -0,0 +1,417 @@
+// src/core/agent-registry.mjs
+// Data-driven agent registry. Scans agents/*.meta.json into an in-memory map
+// keyed by agent key, sorted by `.order`. This replaces what used to be hardcoded
+// across AGENT_FILES (orchestrator.mjs) and AGENT_STEPS (config.mjs): adding an
+// agent is now "drop agents/<key>.md + agents/<key>.meta.json", no core edit.
+//
+// Read synchronously so it can back a synchronous AGENT_STEPS constant in
+// config.mjs. Tolerant: a malformed sidecar, or one missing `key`/`order`, is
+// skipped rather than throwing (mirrors the tolerant readers elsewhere).
+
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { CHANNEL_IDS as CHANNEL_ID_LIST } from './channels.mjs'; // single source (m2)
+import { worcaHome } from './projects.mjs'; // user agent layer root (read fresh per call)
+import { readPluginsLock, pluginCurrentDir } from './plugins-lock.mjs'; // plugin layer roots (Task 2)
+
+/** Default location of the agent metadata sidecars, relative to this module. */
+const DEFAULT_AGENTS_DIR = new URL('../../agents/', import.meta.url).pathname;
+
+const COLORS = new Set(['green', 'peach', 'red', 'blue', 'violet', 'amber']);
+const RUNNER_TYPES = new Set(['producer', 'verifier', 'clarifier']);
+const CHANNEL_IDS = new Set(CHANNEL_ID_LIST);
+
+/** Organizational-only domain tag (coding, marketing, financing, …): lowercase
+ *  kebab, ≤32 chars. 'shared' is a recognized sentinel that passes this regex and
+ *  is stored verbatim; the palette injects it into every section. */
+const DOMAIN_RE = /^[a-z][a-z0-9-]{0,31}$/;
+
+/** Coerce a raw domain to a valid tag; absent/malformed fails safe to the VISIBLE
+ *  'general' default. Does NOT trim (meta-file input is authored). */
+function normalizeDomain(raw) {
+  return typeof raw === 'string' && DOMAIN_RE.test(raw) ? raw : 'general';
+}
+
+/**
+ * Built-in channel/governance spec per agent key. Used when a sidecar omits the
+ * fields, so the six shipped agents behave byte-identically to today's _nodeIo
+ * switch and every saved pipeline stays connectsTo-legal.
+ */
+const DEFAULT_SPEC = {
+  clarify:              { consumes: ['userPrompt'],                       produces: ['clarify'],         connectsTo: ['planner'] },
+  planner:              { consumes: ['userPrompt', 'clarify', 'review'],  optionalConsumes: ['clarify', 'review'], produces: ['plan'], connectsTo: ['refiner', 'implementer', 'planReviewer', 'decomposer'] },
+  refiner:              { consumes: ['plan'],              produces: ['plan', 'review'],  connectsTo: ['implementer', 'refiner', 'decomposer'] },
+  decomposer:           { consumes: ['plan'],              produces: ['decomposition'],   connectsTo: ['implementer'] },
+  implementer:          { consumes: ['plan', 'review'],    optionalConsumes: ['review'],  produces: ['code'], connectsTo: ['reviewer', 'manualTestsChecklist'] },
+  reviewer:             { consumes: ['plan', 'code'],      produces: ['review'],          connectsTo: ['implementer', 'manualTestsChecklist'] },
+  manualTestsChecklist: { consumes: ['plan', 'code'],      produces: ['checklist'],       connectsTo: ['manualWebUiTesting'] },
+  manualWebUiTesting:   { consumes: ['checklist', 'code'], produces: ['review'],          connectsTo: ['implementer'] },
+  planReviewer:         { consumes: ['plan'],              produces: ['review'],          connectsTo: ['planner', 'implementer', 'decomposer'] },
+  // Workspace agents (scope:'workspace-only', §6.2). The scanner is off-pipeline
+  // (connectsTo:[] -> non-composable); the reviewer slots into the code->review->
+  // implementer loop exactly like `reviewer`.
+  workspaceScanner:     { consumes: ['userPrompt'],        produces: ['workspace'],       connectsTo: [] },
+  workspaceReviewer:    { consumes: ['plan', 'code'],      produces: ['review'],          connectsTo: ['implementer'] },
+};
+
+/** Channel ids: built-ins or any well-formed CUSTOM id (open vocabulary, m1-v2).
+ *  Only a malformed id is warned on and dropped — a typo of a built-in becomes a
+ *  custom channel. Consumed ids are surfaced by the validator's reachability
+ *  warning; a typo'd pre-seeded id in `produces` has no warning net — the
+ *  artifact simply lands on the typo'd channel. */
+const CUSTOM_CHANNEL_ID_RE = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+function channelList(raw, key, field) {
+  if (!Array.isArray(raw)) return undefined;
+  const out = [];
+  for (const s of raw) {
+    const id = String(s || '').trim();
+    if (!id) continue;
+    if (CHANNEL_IDS.has(id) || CUSTOM_CHANNEL_ID_RE.test(id)) out.push(id);
+    else console.warn(`[agent-registry] ${key}.${field}: malformed channel id "${id}" ignored`);
+  }
+  return out;
+}
+
+/** Normalize connectsTo: '*' | string[] of agent keys. Anything else => fallback.
+ * A raw value of '*' is treated as "unset" so DEFAULT_SPEC can override it. */
+function normalizeConnectsTo(raw, fallback) {
+  if (Array.isArray(raw)) {
+    const out = raw.map((s) => String(s || '').trim()).filter(Boolean);
+    return out.length ? out : (fallback ?? '*');
+  }
+  // raw === '*' or anything else: use the fallback (spec array or '*')
+  return fallback ?? '*';
+}
+
+/**
+ * Legacy short labels for the original four roles, so the derived AGENT_STEPS is
+ * byte-identical to the hardcoded one the UI/orchestrator have always used. New
+ * agents fall back to their `displayName`.
+ */
+const LEGACY_LABELS = {
+  planner: 'Plan',
+  refiner: 'Refine',
+  implementer: 'Implement',
+  reviewer: 'Review',
+};
+
+const CHANNEL_DEF_KINDS = new Set(['md', 'json']);
+
+/** Normalize a sidecar's channelDefs: well-formed custom ids only, kind md|json
+ *  (default md), filename a plain basename (default <id>.<ext>); built-in channel
+ *  ids cannot be redefined. */
+function normalizeChannelDefs(raw, key) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  const seen = new Set();
+  for (const d of raw) {
+    if (!d || typeof d !== 'object') continue;
+    const id = typeof d.id === 'string' ? d.id.trim() : '';
+    if (!CUSTOM_CHANNEL_ID_RE.test(id)) {
+      if (id) console.warn(`[agent-registry] ${key}.channelDefs: bad channel id "${id}" ignored`);
+      continue;
+    }
+    if (CHANNEL_IDS.has(id)) {
+      console.warn(`[agent-registry] ${key}.channelDefs: "${id}" is a built-in channel and cannot be redefined`);
+      continue;
+    }
+    if (seen.has(id)) continue;
+    seen.add(id);
+    const kind = CHANNEL_DEF_KINDS.has(d.kind) ? d.kind : 'md';
+    const fnRaw = typeof d.filename === 'string' ? d.filename.trim() : '';
+    // basename only: a def must never escape the pipeline dir
+    const pathSafe = fnRaw && !/[\\/]/.test(fnRaw) && !fnRaw.includes('..');
+    if (fnRaw && !pathSafe) {
+      console.warn(`[agent-registry] ${key}.channelDefs: filename "${fnRaw}" is not a plain basename; using "${id}.${kind}"`);
+    }
+    const filename = pathSafe ? fnRaw : `${id}.${kind}`;
+    out.push({ id, kind, filename });
+  }
+  return out;
+}
+
+/**
+ * Registry-level channel definition collection: merge every agent's channelDefs
+ * into { [channelId]: {id, kind, filename} }. Registry order (sorted by .order)
+ * makes "first definition wins" deterministic; conflicts warn.
+ * @param {Record<string, object>} registry
+ */
+export function collectChannelDefs(registry) {
+  const defs = {};
+  for (const m of Object.values(registry || {})) {
+    for (const d of m.channelDefs || []) {
+      if (Object.hasOwn(defs, d.id)) {
+        if (defs[d.id].kind !== d.kind || defs[d.id].filename !== d.filename) {
+          console.warn(`[agent-registry] channel "${d.id}" redefined by "${m.key}"; first definition wins`);
+        }
+        continue;
+      }
+      defs[d.id] = { ...d };
+    }
+  }
+  return defs;
+}
+
+/**
+ * Ordered unique domain list for UI section headers. Registry is already sorted
+ * by .order (loadAgentRegistry sorts at line 260), so first-seen order is stable.
+ * 'general' is pinned LAST (fail-safe bucket renders last); 'shared' is EXCLUDED —
+ * it is injected into every section, never a header of its own. 'general' is always
+ * present so the fail-safe bucket is reachable.
+ * @param {Record<string, object>} registry
+ */
+export function collectDomains(registry) {
+  const seen = [];
+  for (const meta of Object.values(registry || {})) {
+    const d = meta && meta.domain;
+    if (!d || d === 'shared' || d === 'general' || seen.includes(d)) continue;
+    seen.push(d);
+  }
+  seen.push('general');   // always present, always last
+  return seen;
+}
+
+/** Agent keys become filename stems (review basenames, config keys); keep them
+ *  identifier-shaped so a key can never escape a directory. */
+const AGENT_KEY_RE = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+
+/** Coerce one parsed sidecar into a normalized AgentMeta, or null if unusable. */
+export function normalizeMeta(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  const key = typeof raw.key === 'string' ? raw.key.trim() : '';
+  if (!key) return null;
+  if (!AGENT_KEY_RE.test(key)) {
+    console.warn(`[agent-registry] sidecar key "${key}" is not a valid agent key; skipped`);
+    return null;
+  }
+  const order = Number(raw.order);
+  if (!Number.isFinite(order)) return null;
+  const color = COLORS.has(raw.color) ? raw.color : 'amber';
+  const runnerType = RUNNER_TYPES.has(raw.runnerType) ? raw.runnerType : 'producer';
+  // §6.6 scope coercion (fail-safe, mirrors color): anything but the explicit
+  // 'workspace-only' marker is a normal 'project'-scope agent, so a typo fails
+  // safe to a VISIBLE project agent (surfaced by the palette test) rather than a
+  // silently-hidden one.
+  const scope = raw.scope === 'workspace-only' ? 'workspace-only' : 'project';
+  // Per-agent user questions (spec 2026-07-11): capability + lock + default.
+  // Coherence is forced HERE (single source of truth): an agent that cannot ask
+  // can be neither locked nor default-on, so UI/agent-gen never validate this.
+  const asksQuestions = !!raw.asksQuestions;
+  const spec = DEFAULT_SPEC[key] || {};
+  const rtFallbackConsumes = runnerType === 'verifier' ? ['code'] : ['userPrompt'];
+  const consumes = channelList(raw.consumes, key, 'consumes') || spec.consumes || rtFallbackConsumes;
+  const produces = channelList(raw.produces, key, 'produces') || spec.produces || (runnerType === 'verifier' ? ['review'] : []);
+  const optionalConsumes = channelList(raw.optionalConsumes, key, 'optionalConsumes') || spec.optionalConsumes || [];
+  const connectsTo = normalizeConnectsTo(raw.connectsTo, spec.connectsTo || '*');
+  return {
+    key,
+    displayName: typeof raw.displayName === 'string' && raw.displayName.trim()
+      ? raw.displayName.trim()
+      : key,
+    description: typeof raw.description === 'string' ? raw.description : '',
+    color,
+    icon: typeof raw.icon === 'string' ? raw.icon : '',
+    agentFile: typeof raw.agentFile === 'string' && raw.agentFile.trim() ? raw.agentFile.trim() : null,
+    runnerType,
+    scope,
+    domain: normalizeDomain(raw.domain),   // always set; fail-safe VISIBLE default 'general'
+    loopSource: !!raw.loopSource,
+    fanOut: !!raw.fanOut,
+    asksQuestions,
+    questionsLocked: asksQuestions && !!raw.questionsLocked,
+    questionsDefault: asksQuestions && !!raw.questionsDefault,
+    consumes,
+    optionalConsumes,
+    produces,
+    connectsTo,
+    order,
+    // ── schema v2 (all optional; absent => safe defaults; origin/agentPath are
+    //    stamped by scanLayer as COMPUTED fields, never read from the sidecar) ──
+    uiPhase: typeof raw.uiPhase === 'string' && raw.uiPhase.trim() ? raw.uiPhase.trim() : null,
+    promptHints: typeof raw.promptHints === 'string' ? raw.promptHints : '',
+    version: typeof raw.version === 'string' || typeof raw.version === 'number' ? String(raw.version) : '1',
+    channelDefs: normalizeChannelDefs(raw.channelDefs, key),
+    requiresSkills: Array.isArray(raw.requiresSkills)
+      ? raw.requiresSkills.filter((s) => typeof s === 'string' && s.trim()).map((s) => s.trim())
+      : [],
+  };
+}
+
+/**
+ * Directory of USER agents: <worcaHome()>/agents (~/.worca-cc/agents). Resolved
+ * fresh on every call (mirrors worcaHome's read-fresh contract). Returns null
+ * when the home cannot be resolved (e.g. under the node:test runner with no
+ * WORCA_HOME — projects.mjs throws there to protect the real store), so module
+ * import and registry loads never throw.
+ */
+export function userAgentsDir() {
+  try { return join(worcaHome(), 'agents'); } catch { return null; }
+}
+
+/**
+ * Third registry layer (spec §9.1): every ENABLED installed plugin's
+ * current/agents dir, in lexicographic plugin-name order — the deterministic
+ * collision winner among plugins. An entry is skipped when disabled
+ * (enabled === false in the lock) or broken (existsSync follows the current/
+ * symlink, so a missing or dangling symlink — and a version dir without
+ * agents/ — drops out). Wrapped in try/catch like userAgentsDir(): with no
+ * resolvable worca-cc home (bare node:test runner) or an unreadable lock this
+ * returns [] and registry loads never throw.
+ * @returns {Array<{plugin: string, dir: string}>}
+ */
+export function pluginAgentLayers() {
+  try {
+    const lock = readPluginsLock();
+    return Object.keys(lock)
+      .sort()
+      .filter((name) => lock[name] && lock[name].enabled !== false)
+      .map((name) => ({ plugin: name, dir: join(pluginCurrentDir(name), 'agents') }))
+      .filter(({ dir }) => existsSync(dir));
+  } catch {
+    return []; // no home / unreadable lock => no plugin layer (fails safe)
+  }
+}
+
+/**
+ * Fallback palette blurb: the agent .md's YAML frontmatter `description:` line,
+ * stored VERBATIM (clarify 2026-08-09: the UI clamps, the bubble wants the full
+ * text — never truncate here). Single-line values only (plain or quoted);
+ * folded/multi-line scalars are out of scope by design (spec 2026-08-09; every
+ * shipped .md uses a single-line scalar) and degrade to '' — the block-scalar
+ * indicator is detected, never stored. Any read/parse failure returns '' so
+ * scanLayer never throws because of the fallback.
+ */
+function frontmatterDescription(mdPath) {
+  let text;
+  try { text = readFileSync(mdPath, 'utf8'); } catch { return ''; }
+  const fm = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fm) return '';
+  const line = fm[1].match(/^description:[ \t]*(.+)$/m);
+  if (!line) return '';
+  let v = line[1].trim();
+  // Folded/literal block scalars ('>', '>-', '|', '|+', …): the captured value
+  // is just the indicator, not the text — degrade to '' rather than store junk.
+  if (/^[>|][+-]?$/.test(v)) return '';
+  if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+    v = v.slice(1, -1).trim();
+  }
+  return v;
+}
+
+/** Scan one layer dir for *.meta.json; stamps the COMPUTED origin/agentPath/
+ *  descriptionDerived fields (none of which normalizeMeta returns, so none can
+ *  be persisted back into a sidecar). */
+function scanLayer(dir, origin) {
+  let files;
+  try {
+    files = readdirSync(dir);
+  } catch {
+    return []; // missing layer dir => empty layer (fails safe)
+  }
+  const metas = [];
+  for (const f of files) {
+    if (!f.endsWith('.meta.json')) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(readFileSync(join(dir, f), 'utf8'));
+    } catch {
+      continue; // skip unreadable / malformed sidecars
+    }
+    const meta = normalizeMeta(parsed);
+    if (!meta) continue;
+    meta.origin = origin;                                              // computed, never stored
+    meta.agentPath = meta.agentFile ? join(dir, meta.agentFile) : null; // layer-correct abs path
+    // Description fallback (spec 2026-08-09): empty sidecar description →
+    // the .md frontmatter description. Only costs a file read when empty.
+    // descriptionDerived marks the RESOLVED description as computed too: unlike
+    // origin/agentPath, `description` has a slot in normalizeMeta, so without
+    // this flag every write path would bake the fallback into the sidecar and
+    // the blurb would stop tracking the .md (and could never be cleared).
+    if (!meta.description && meta.agentPath) {
+      meta.description = frontmatterDescription(meta.agentPath);
+      if (meta.description) meta.descriptionDerived = true;             // computed, never stored
+    }
+    metas.push(meta);
+  }
+  return metas;
+}
+
+/**
+ * Scan the built-in layer (`agentsDir`) AND the user layer (~/.worca-cc/agents) and
+ * build the merged registry. Built-ins are IMMUTABLE: a user sidecar whose key
+ * collides with a built-in is skipped with a warning. Re-scans both layers on
+ * every call (no module-level cache), so the registry is always reloadable.
+ * @param {string} [agentsDir]   built-in layer (repo agents/)
+ * @param {{userAgentsDir?: string|null}} [opts]  user layer override; null disables
+ * @returns {Record<string, object>} agent key -> AgentMeta, sorted by `.order`
+ */
+export function loadAgentRegistry(agentsDir = DEFAULT_AGENTS_DIR, opts = {}) {
+  const builtins = scanLayer(agentsDir, 'builtin');
+  const builtinKeys = new Set(builtins.map((m) => m.key));
+  const userDir = opts.userAgentsDir === undefined ? userAgentsDir() : opts.userAgentsDir;
+  const users = [];
+  if (userDir) {
+    for (const m of scanLayer(userDir, 'user')) {
+      if (builtinKeys.has(m.key)) {
+        console.warn(
+          `[agent-registry] user agent "${m.key}" shadows a built-in and was skipped (built-ins are immutable)`,
+        );
+        continue;
+      }
+      users.push(m);
+    }
+  }
+  // Plugin layer (spec §9.1): builtin > user > plugin; among plugins the
+  // lexicographic name order of pluginAgentLayers() decides. Same skip-on-
+  // collision + warning contract as the user layer above. scanLayer stamps the
+  // COMPUTED origin ('plugin:<name>') and agentPath (through current/, so a
+  // version swap retargets every path atomically). opts.includePlugins=false is
+  // the escape hatch for callers that must not see plugins (default true).
+  // Zero plugins installed => pluginAgentLayers() === [] => byte-identical merge.
+  const plugins = [];
+  if (opts.includePlugins !== false) {
+    const taken = new Set([...builtinKeys, ...users.map((m) => m.key)]);
+    for (const { plugin, dir } of pluginAgentLayers()) {
+      for (const m of scanLayer(dir, `plugin:${plugin}`)) {
+        if (taken.has(m.key)) {
+          console.warn(
+            `[agent-registry] plugin agent "${m.key}" (plugin "${plugin}") collides with an existing agent and was skipped`,
+          );
+          continue;
+        }
+        taken.add(m.key);
+        plugins.push(m);
+      }
+    }
+  }
+  const metas = [...builtins, ...users, ...plugins].sort((a, b) => a.order - b.order); // stable sort
+  const registry = {};
+  for (const m of metas) registry[m.key] = m;
+  return registry;
+}
+
+/**
+ * Derive the legacy `[{key,label}]` step list from a registry (replacement source
+ * for the hardcoded AGENT_STEPS). The original four roles keep their short legacy
+ * labels; any additional agent uses its `displayName`.
+ *
+ * §6.6/C9: `scope:'workspace-only'` agents are EXCLUDED — they are not part of the
+ * single-project UI stepper / per-step config keyspace that AGENT_STEPS drives, so
+ * this returns the 9 built-in project-scope steps plus any user-layer project
+ * agents (without the exclusion the two workspace sidecars would add 2 more).
+ * @param {Record<string, object>} registry
+ * @returns {Array<{key:string,label:string,fanOut:boolean,asksQuestions:boolean,questionsLocked:boolean,questionsDefault:boolean}>}
+ */
+export function registryToSteps(registry) {
+  return Object.values(registry || {})
+    .filter((m) => m.scope !== 'workspace-only')
+    .sort((a, b) => a.order - b.order)
+    .map((m) => ({
+      key: m.key,
+      label: LEGACY_LABELS[m.key] || m.displayName,
+      fanOut: !!m.fanOut,
+      asksQuestions: !!m.asksQuestions,
+      questionsLocked: !!m.questionsLocked,
+      questionsDefault: !!m.questionsDefault,
+    }));
+}