@worca/app 1.2.0-rc.1 → 1.2.0-rc.3

package/ui/server.mjs

@@ -42,7 +42,10 @@ import {
   askMaxTurns, askMaxBudgetUsd, setAskMaxTurns, setAskMaxBudgetUsd, assertAskLimitInputs,
   chatPrefs, setChatPrefs,
   debugSpawnEnabled as storedDebugSpawnEnabled, effectiveDebugSpawn, setDebugSpawnEnabled, assertDebugSpawnInput, SETTINGS_POST_KEYS,
+  titleModel as storedTitleModel, setTitleModel, assertTitleModelInput,
+  hideBuiltinModels, setHideBuiltinModels, assertHideBuiltinModelsInput,
 } from '../src/core/settings.mjs';
+import { describeTitleModel } from '../src/core/title.mjs';
 import {
   ASK_ID_RE, createThread as askCreateThread, getThread as askGetThread,
   listThreads as askListThreads, updateThread as askUpdateThread,
@@ -85,7 +88,7 @@ import { pickFolderNative } from '../src/core/folder-dialog.mjs';
 import { listFolders } from '../src/core/fs-browse.mjs';
 import {
   readConfig, setStep, addCustomModel, removeCustomModel, listModels,
-  PREDEFINED_MODELS, agentSteps, EFFORTS,
+  PREDEFINED_MODELS, agentSteps, EFFORTS, catalogHasModel,
   readRunConfig, setNodeModel, setFeedbackCycles, setWireCycles, setActiveWorkflow, resetWorkflowConfig,
   globalModelRefs, removeGlobalModelAndRefs, promoteCustomModel, costUnreliableModelIds,
 } from '../src/core/config.mjs';
@@ -93,6 +96,9 @@ import { listGlobalModels, addGlobalModel, updateGlobalModel } from '../src/core
 import { modelEnvRef, maskModelEnvValue, SUBAGENT_MODEL_VALUES, subagentModelIssue } from '../src/core/model-env.mjs';
 import { listPluginModels, modelSecretsSchema, pluginModelSecretStatus } from '../src/core/plugin-models.mjs';
 import { testModel } from '../src/core/model-test.mjs';
+import {
+  DEFAULT_UI_PORT, UI_HEALTH_NAME, newUiToken, writeUiInstance, removeUiInstance, uiUrl,
+} from '../src/core/ui-instance.mjs';
 import { validateGuardrails } from '../src/core/guardrails.mjs';
 import {
   listBuiltinGuardrailSets, listGuardrailSets, readGuardrailSet,
@@ -104,7 +110,10 @@ import {
 } from '../src/core/workflows.mjs';
 import { registryPortsFn } from '../src/core/graph/registry-ports.mjs';
 import { sweepV1Runs, V1_RUN_RETIRED } from '../src/core/db.mjs';
-import { validateGraph, AGENT_TUNABLES } from '../src/shared/graph/validate.mjs';
+import { exportWorkflow, exportWorkflowPlugin, ON_CONFLICT_MODES, RESOLUTION_CHOICES } from '../src/core/workflow-export.mjs';
+import {
+  saveGraphWorkflow, importGraphWorkflow, exportGraphJson, workflowFileSlug, nodeDefaultsError,
+} from '../src/core/workflow-share.mjs';
 import { loadAgentRegistry } from '../src/core/agent-registry.mjs';
 import {
   listLocalBranches, currentBranch, isValidSourceRef, sweepRunRoots, sweepLegacyWorktreesAll,
@@ -123,7 +132,7 @@ import { createAgentGen } from '../src/core/agent-gen.mjs';
 import { listAgents, readAgent, createAgent, updateAgent, deleteAgent, AGENT_KEY_RE } from '../src/core/agent-store.mjs';
 import {
   listInstalledPlugins, installPlugin, updatePlugin, uninstallPlugin,
-  setPluginEnabled, doctorPlugin,
+  setPluginEnabled, doctorPlugin, linkPlugin,
   listOrphanPluginData, purgePluginData,
 } from '../src/core/plugin-store.mjs';
 import { fetchCandidate } from '../src/core/plugin-repo.mjs';
@@ -146,7 +155,7 @@ import { createNotifier } from '../src/core/chat/notifier.mjs';
 import { TokenBucket } from '../src/core/chat/rate-limiter.mjs';
 import { renderTest } from '../src/core/chat/renderers.mjs';
 import { readPluginsLock, pluginCurrentDir } from '../src/core/plugins-lock.mjs';
-import { normalizeManifest, PLUGIN_NAME_RE as MANIFEST_PLUGIN_NAME_RE } from '../src/core/plugin-manifest.mjs';
+import { normalizeManifest, validatePluginDir, PLUGIN_NAME_RE as MANIFEST_PLUGIN_NAME_RE } from '../src/core/plugin-manifest.mjs';
 import { listTaskSources, retryWriteback } from '../src/core/sources.mjs';
 import { callSource, PluginOpError } from '../src/core/plugin-shim.mjs';
 import { HLJS_GRAMMAR_IDS } from './public/hljs-loader.mjs';
@@ -174,6 +183,7 @@ const PUBLIC_DIR = path.join(__dirname, 'public');
 const AGENTS_DIR = path.join(PROJECT_ROOT, 'agents');
 const SKILLS_DIR = path.join(PROJECT_ROOT, 'skills');
 const require = createRequire(import.meta.url);
+const PKG_VERSION = require('../package.json').version;
 const HLJS_LANGUAGE_FILE_RE = /^[a-z0-9][a-z0-9-]{0,63}\.min\.js$/;
 // Primaries plus the sub-language grammars their instances register
 // (hljs-loader.mjs); a shipped but unmapped grammar stays a plain 404.
@@ -212,7 +222,7 @@ const ASK_VENDOR_ASSETS = {
   dompurify: resolveEsmAsset('dompurify'),
 };
 
-const PORT = Number(process.env.PORT) || 4317;
+const PORT = Number(process.env.PORT) || DEFAULT_UI_PORT;
 // Bind to loopback by default (S1). Power users who knowingly want LAN exposure
 // can set WORCA_HOST=0.0.0.0, but the localhost-only Host/Origin guard still
 // applies unless they also front it with auth.
@@ -275,6 +285,11 @@ const MAX_BUFFER = 5000;
 const app = express();
 const server = http.createServer(app);
 const wss = new WebSocketServer({ server, path: '/ws' });
+// ws re-emits the http server's 'error' on the WebSocketServer. With no listener
+// here, an EADDRINUSE on listen() became an unhandled 'error' event and a full
+// stack trace; the http server's own handler (isMain below) is the one that
+// reports it, so this side of the pair only has to not throw.
+wss.on('error', () => {});
 
 /** All currently connected sockets. */
 const sockets = new Set();
@@ -2469,9 +2484,11 @@ app.delete('/api/projects', async (req, res) => {
 // user's machine); when it reports `unsupported` the UI falls back to an
 // in-app modal fed by GET /api/fs/dirs. Localhost-only like every route here
 // (global isLocalRequest middleware).
-app.post('/api/fs/pick-folder', async (_req, res) => {
+app.post('/api/fs/pick-folder', async (req, res) => {
   try {
-    res.json(await pickFolderNative());
+    // `purpose` only picks the dialog title from a closed set (folder-dialog.mjs).
+    const purpose = typeof req.body?.purpose === 'string' ? req.body.purpose : undefined;
+    res.json(await pickFolderNative({ purpose }));
   } catch (err) {
     res.status(500).json({ error: err && err.message ? err.message : String(err) });
   }
@@ -2779,6 +2796,52 @@ const settingsState = () => ({
   askMaxBudgetUsd: askMaxBudgetUsd(),
   debugSpawnEnabled: storedDebugSpawnEnabled(),          // what is STORED (the checkbox)
   debugSpawnEffective: effectiveDebugSpawn(),             // what the next spawn will DO, and why
+  titleModel: storedTitleModel(),                         // the STORED id (the select), null = run's model
+  titleModelEffective: describeTitleModel(),              // env override / stale id, for the hint line (#422)
+  hideBuiltinModels: hideBuiltinModels(),
+});
+
+// ---------------------------------------------------------------------------
+// Instance lifecycle (`worca ui status|stop|restart`, src/core/ui-instance.mjs)
+// ---------------------------------------------------------------------------
+// `uiControl` is set by the boot block below when the server owns a port. Under
+// test (app imported, no bind) it stays empty: /api/health still answers, and
+// /api/shutdown refuses with 503 rather than exiting the test runner.
+const uiControl = { token: null, onShutdown: null, startedAt: null };
+const startedAtIso = () => uiControl.startedAt || null;
+
+app.get('/api/health', (req, res) => {
+  const addr = req.socket && req.socket.localPort;
+  res.json({
+    name: UI_HEALTH_NAME,
+    version: PKG_VERSION,
+    pid: process.pid,
+    host: HOST,
+    port: addr || PORT,
+    startedAt: startedAtIso(),
+  });
+});
+
+/** Constant-time bearer check; `expected` is the boot-time token from ui.json. */
+function bearerMatches(header, expected) {
+  if (!expected || typeof header !== 'string') return false;
+  const m = /^Bearer\s+(\S+)$/i.exec(header.trim());
+  if (!m) return false;
+  const a = Buffer.from(m[1]);
+  const b = Buffer.from(expected);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+app.post('/api/shutdown', (req, res) => {
+  if (!uiControl.token || typeof uiControl.onShutdown !== 'function') {
+    return res.status(503).json({ error: 'shutdown is only available on a server started with `worca ui`' });
+  }
+  if (!bearerMatches(req.headers.authorization, uiControl.token)) {
+    return res.status(401).json({ error: 'shutdown requires the bearer token from the instance file' });
+  }
+  res.status(202).json({ ok: true, pid: process.pid });
+  // Answer first, exit on the next tick so the 202 actually leaves the socket.
+  setImmediate(() => uiControl.onShutdown('request'));
 });
 
 app.get('/api/settings', (_req, res) => {
@@ -2795,6 +2858,12 @@ app.post('/api/settings', async (req, res) => {
   const hasBudgetKey = has('pipelineCostLimitUsd') || has('totalCostLimitUsd') || has('costLimitResetPeriod');
   const hasAskKey = has('askMaxTurns') || has('askMaxBudgetUsd');
   const hasDebugSpawnKey = has('debugSpawnEnabled');
+  const hasTitleModelKey = has('titleModel');
+  const hasHideBuiltinKey = has('hideBuiltinModels');
+  // #422: the title model is a SELECT over the catalog, so an id that is not a
+  // catalog member is a client bug (or a stale option) — refuse it here rather
+  // than store an id resolveModelEnv could never route.
+  const titleModelInput = hasTitleModelKey ? (body.titleModel ?? '') : undefined;
   // Normalize the budget keys first, then validate them as a SET before ANY write.
   // Each setter persists on its own, so a two-key POST whose second key is invalid
   // used to answer 400 with the first key already on disk, no budget-changed
@@ -2816,6 +2885,13 @@ app.post('/api/settings', async (req, res) => {
     assertCostLimitInputs(budget);
     assertAskLimitInputs(ask);
     if (hasDebugSpawnKey) assertDebugSpawnInput(body.debugSpawnEnabled);
+    if (hasTitleModelKey) {
+      assertTitleModelInput(titleModelInput);
+      if (titleModelInput !== '' && titleModelInput !== null && !catalogHasModel(titleModelInput)) {
+        throw new Error(`unknown model ${JSON.stringify(String(titleModelInput))} — pick one from the catalog`);
+      }
+    }
+    if (hasHideBuiltinKey) assertHideBuiltinModelsInput(body.hideBuiltinModels);
     // Root first: it is the one key whose setter can still fail AFTER the asserts
     // above (an unusable path), so every other key's write must come after it or
     // a mixed POST would answer 400 with those keys already applied on disk.
@@ -2834,10 +2910,12 @@ app.post('/api/settings', async (req, res) => {
     if (has('askMaxTurns')) await setAskMaxTurns(ask.askMaxTurns);
     if (has('askMaxBudgetUsd')) await setAskMaxBudgetUsd(ask.askMaxBudgetUsd);
     if (hasDebugSpawnKey) await setDebugSpawnEnabled(body.debugSpawnEnabled);
+    if (hasTitleModelKey) await setTitleModel(titleModelInput);
+    if (hasHideBuiltinKey) await setHideBuiltinModels(body.hideBuiltinModels);
     if (hasBudgetKey) emitChanged('budget-changed');
     // Other open tabs repaint their Settings cards (a stale tab could otherwise
     // "save" its old checkbox state over this one with no feedback to either).
-    if (hasAskKey || hasDebugSpawnKey) emitChanged('settings-changed');
+    if (hasAskKey || hasDebugSpawnKey || hasTitleModelKey || hasHideBuiltinKey) emitChanged('settings-changed');
     res.json({ ...settingsState(), chat: chatPrefs() });
   } catch (err) {
     // The setters throw only on an unusable path -> client error (400).
@@ -3058,7 +3136,10 @@ const pluginModelsPayload = () => {
 };
 
 app.get('/api/models', (req, res) => {
-  res.json({ models: maskedGlobalModels(), plugin: pluginModelsPayload(), predefined: PREDEFINED_MODELS, efforts: EFFORTS });
+  res.json({
+    models: maskedGlobalModels(), plugin: pluginModelsPayload(), predefined: PREDEFINED_MODELS, efforts: EFFORTS,
+    hideBuiltinModels: hideBuiltinModels(),   // the Models-view checkbox (#422)
+  });
 });
 
 app.post('/api/models', async (req, res) => {
@@ -3271,7 +3352,10 @@ app.post('/api/models/:id/test', async (req, res) => {
   const lc = id.toLowerCase();
   const global = listGlobalModels().find((m) => m.id.toLowerCase() === lc);
   const plugin = global ? null : listPluginModels().find((m) => m.id.toLowerCase() === lc);
-  if (!global && !plugin) return res.status(404).json({ error: `unknown model id ${JSON.stringify(id)}` });
+  // A built-in is testable too (#422): the Title-generation card offers it, and
+  // a first-party id with no routing env is exactly the spawn a run would make.
+  const builtin = !global && !plugin && PREDEFINED_MODELS.some((m) => m.id.toLowerCase() === lc);
+  if (!global && !plugin && !builtin) return res.status(404).json({ error: `unknown model id ${JSON.stringify(id)}` });
   if (plugin && plugin.secrets.length) {
     // Don't burn a spawn guaranteed to fail — resolveModelEnv drops unset secrets.
     const unset = pluginModelSecretStatus(plugin.plugin)
@@ -3295,25 +3379,35 @@ app.post('/api/models/:id/test', async (req, res) => {
 // /api/projects + /api/config delegation pattern: thin handlers, validation and
 // atomic persistence owned by src/core/workflows.mjs + workflow-validator.mjs.
 // ---------------------------------------------------------------------------
-// Validate one node-defaults block against the project-less catalog. Returns an
-// error message, or '' when the block is acceptable. Mirrors setStep's rules so a
-// workflow default can never name something a per-project override could not.
-function nodeDefaultsError(raw, models, where) {
-  if (raw == null) return '';
-  if (typeof raw !== 'object' || Array.isArray(raw)) return `defaults for ${where} must be an object`;
-  const model = typeof raw.model === 'string' ? raw.model.trim() : '';
-  const effort = typeof raw.effort === 'string' ? raw.effort.trim() : '';
-  const entry = model ? models.find((m) => m.id === model) : null;
-  if (model && !entry) return `unknown model "${model}"`;
-  // subagentModel is a fixed alias enum, NOT a catalog id: validated via the
-  // shared helper so a typo is a 400 with the same message every writer uses.
-  const subIssue = subagentModelIssue(raw.subagentModel);
-  if (subIssue) return subIssue;
-  if (!effort) return '';
-  if (!EFFORTS.includes(effort)) return `unknown effort "${effort}"`;
-  if (!entry) return 'select a model before choosing an effort';
-  if (!entry.efforts.includes(effort)) return `model "${model}" does not support effort "${effort}"`;
-  return '';
+// nodeDefaultsError (one node-defaults block vs the project-less catalog) lives
+// in src/core/workflow-share.mjs now, so `worca workflow import` applies the
+// same gate as the routes below.
+
+/** Error -> HTTP for the shared save/import/JSON path (workflow-share.mjs codes). */
+function sendWorkflowShareError(res, err) {
+  const code = err && err.code;
+  const message = err && err.message ? err.message : String(err);
+  if (code === 'BAD_REQUEST' || code === 'UNSUPPORTED') return badRequest(res, message);
+  // The 422 body is the SHARED validator's issue list, by construction: the
+  // composer renders exactly what it would have computed locally, so the server
+  // and the client can never disagree about why a graph is illegal. `summary`
+  // is the one-line V4 fold for surfaces with no issue list (the Import button).
+  if (code === 'INVALID_GRAPH') {
+    return res.status(422).json({
+      error: message, errors: err.errors || [], warnings: err.warnings || [],
+      ...(err.summary ? { summary: err.summary } : {}),
+    });
+  }
+  // C-3: a name that slugs onto the reserved wf_default is a caller error, not
+  // a server fault — 422, the same code the validator's refusal uses. MAJ-5: a
+  // minted id already in use is a 409 carrying that id, so the dialog can offer
+  // rename/overwrite. Both bodies carry NO issues/errors array on purpose:
+  // app.js's saveWorkflow maps `error` straight into the save dialog's message
+  // line, verbatim.
+  if (code === 'RESERVED_NAME') return res.status(422).json({ error: message });
+  if (code === 'ID_TAKEN') return res.status(409).json({ error: message, id: err.id });
+  if (code === 'NOT_FOUND') return res.status(404).json({ error: message });
+  return res.status(500).json({ error: message });
 }
 
 app.get('/api/workflows', async (req, res) => {
@@ -3342,63 +3436,61 @@ app.get('/api/workflows/:id', async (req, res) => {
     if (err && (err.code === 'NOT_FOUND' || err.code === 'ARCHIVED')) {
       return res.status(404).json({ error: err.message });
     }
+    // The row exists but its plugin is disabled: a conflict with the plugin's
+    // state, not a missing row — the message names the fix.
+    if (err && err.code === 'PLUGIN_DISABLED') return res.status(409).json({ error: err.message });
     res.status(500).json({ error: err && err.message ? err.message : String(err) });
   }
 });
 
 app.post('/api/workflows', async (req, res) => {
-  const body = req.body || {};
   // The v1 pipeline format is RETIRED: only graphs are accepted (spec §10.2).
   // The whole v1 arm (its steps-borne node defaults, validateWorkflow and
   // writeWorkflow) died with it — nothing reaches the v1 store through the API.
-  if (body.version !== 2) {
-    return badRequest(res, 'v1 pipeline templates are no longer accepted — save a graph (version 2)');
-  }
   // ── v2 graph save ──────────────────────────────────────────────────────────
-  // The 422 body is the SHARED validator's issue list, by construction: the
-  // composer renders exactly what it would have computed locally, so the server
-  // and the client can never disagree about why a graph is illegal.
-  const graph = {
-    id: typeof body.id === 'string' ? body.id : undefined,
-    name: typeof body.name === 'string' ? body.name.trim() : '',
-    domain: typeof body.domain === 'string' ? body.domain : undefined,
-    nodes: Array.isArray(body.nodes) ? body.nodes : [],
-    wires: Array.isArray(body.wires) ? body.wires : [],
-    ...(body.canvas && typeof body.canvas === 'object' ? { canvas: body.canvas } : {}),
-  };
-  if (!graph.name) return badRequest(res, 'name is required');
-  try {
-    // Catalog validation FIRST: a v2 node's `config` IS its defaults block (§4),
-    // so a value the per-project override could not name must not ride in
-    // through a template save. nodeDefaultsError checks the tunables (model +
-    // effort against the catalog, subagentModel against the alias enum), so
-    // only AGENT_TUNABLES are handed to it — topology keys (awaitAll, arity,
-    // planStoreSeed) never are.
-    const models = await listModels('');
-    for (const n of graph.nodes) {
-      if (!n || n.kind !== 'agent' || !n.config || typeof n.config !== 'object') continue;
-      const picked = Object.fromEntries(
-        AGENT_TUNABLES.filter((k) => k in n.config).map((k) => [k, n.config[k]]));
-      const bad = nodeDefaultsError(picked, models, `node "${n.id}"`);
-      if (bad) return badRequest(res, bad);
-    }
-    const portsFn = registryPortsFn(loadAgentRegistry(AGENTS_DIR));
-    const { errors, warnings } = validateGraph({ ...graph, version: 2 }, portsFn);
-    if (errors.length) return res.status(422).json({ error: 'invalid graph', errors, warnings });
-    // rejectCollision (MAJ-5): the body carried no id, so wf_<slug(name)> is a
-    // GUESS — it must never silently replace a pipeline the user can see.
-    const workflow = await writeGraphWorkflow(graph, { rejectCollision: true });
+  // Catalog check + shared validator + rejectCollision persistence live in
+  // workflow-share.mjs (saveGraphWorkflow): the SAME path the JSON import
+  // route and `worca workflow import` take, so they can never drift. A body
+  // WITHOUT an id mints wf_<slug(name)> — a GUESS that must never silently
+  // replace a pipeline the user can see (MAJ-5 -> 409).
+  try {
+    const { workflow, warnings } = await saveGraphWorkflow(req.body || {}, { agentsDir: AGENTS_DIR });
     return res.status(201).json({ workflow, warnings });
   } catch (err) {
-    // C-3: a name that slugs onto the reserved wf_default is a caller error, not
-    // a server fault — 422, the same code the validator's refusal uses. MAJ-5: a
-    // minted id already in use is a 409 carrying that id, so the dialog can offer
-    // rename/overwrite. Both bodies carry NO issues/errors array on purpose:
-    // app.js's saveWorkflow maps `error` straight into the save dialog's message
-    // line, verbatim.
-    if (err && err.code === 'RESERVED_NAME') return res.status(422).json({ error: err.message });
-    if (err && err.code === 'ID_TAKEN') return res.status(409).json({ error: err.message, id: err.id });
-    return res.status(500).json({ error: err && err.message ? err.message : String(err) });
+    return sendWorkflowShareError(res, err);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Share a workflow as JSON (issue #421). GET .../json is the unstamped v2 graph
+// of the STORED row (no id/origin/timestamps; `canvas` kept), served as a
+// download; POST /import-json feeds one back through the shared validator,
+// minting an id and suffixing the name (`Name (2)`) on a collision — never
+// overwrite. Registered BEFORE the /:id routes so the segment can never be read
+// as an id. (Not `/import`: test/shared-graph-purity.test.mjs scans ui/public
+// for `import '<spec>'` and a bare `import'` in app.js's fetch URL trips it.)
+// ---------------------------------------------------------------------------
+app.post('/api/workflows/import-json', async (req, res) => {
+  const body = req.body || {};
+  const src = body.workflow && typeof body.workflow === 'object' && !Array.isArray(body.workflow) ? body.workflow : null;
+  if (!src) return badRequest(res, 'workflow (the exported JSON object) is required');
+  try {
+    const r = await importGraphWorkflow(src, {
+      name: typeof body.name === 'string' ? body.name : undefined, agentsDir: AGENTS_DIR,
+    });
+    return res.status(201).json(r);
+  } catch (err) {
+    return sendWorkflowShareError(res, err);
+  }
+});
+
+app.get('/api/workflows/:id/json', async (req, res) => {
+  try {
+    const payload = await exportGraphJson(req.params.id);
+    res.setHeader('Content-Disposition', `attachment; filename="${workflowFileSlug(req.params.id)}.json"`);
+    res.type('application/json').send(JSON.stringify(payload, null, 2) + '\n');
+  } catch (err) {
+    sendWorkflowShareError(res, err);
   }
 });
 
@@ -3446,6 +3538,72 @@ app.delete('/api/workflows/:id', async (req, res) => {
   }
 });
 
+function workflowExportErrorStatus(code) {
+  if (code === 'NOT_FOUND') return 404;
+  if (code === 'BAD_REQUEST' || code === 'UNSUPPORTED' || code === 'MISSING_SKILL') return 400;
+  if (code === 'INVALID_GRAPH') return 422;
+  if (code === 'CONFLICT' || code === 'CANCELLED') return 409;
+  return 500;
+}
+
+app.post('/api/workflows/:id/export', async (req, res) => {
+  const body = req.body || {};
+  const destination = body.destination;
+  if (destination !== 'global' && destination !== 'project' && destination !== 'plugin') {
+    return badRequest(res, "destination must be 'global', 'project' or 'plugin'");
+  }
+  // ── destination 'plugin' (#421): a plugin folder the recipient links/reimports.
+  //    Same Plan/Apply shape as the Claude Code export, so the modal renders both.
+  if (destination === 'plugin') {
+    const pluginDir = resolveProjectDir(body.pluginDir);
+    if (!pluginDir) return badRequest(res, 'pluginDir is required for a plugin export');
+    try {
+      const result = await exportWorkflowPlugin({
+        workflowId: req.params.id, targetDir: pluginDir,
+        pluginName: typeof body.pluginName === 'string' ? body.pluginName : undefined,
+        keepVersion: !!body.keepVersion, dryRun: !!body.dryRun,
+      });
+      return res.json(result);
+    } catch (err) {
+      return res.status(workflowExportErrorStatus(err && err.code)).json({
+        error: err && err.message ? err.message : String(err),
+        ...(Array.isArray(err?.errors) ? { errors: err.errors } : {}),
+      });
+    }
+  }
+  let projectDir;
+  if (destination === 'project') {
+    projectDir = resolveProjectDir(body.projectDir);
+    if (!projectDir) return badRequest(res, 'projectDir is required for a project export');
+  }
+  // Validate conflict handling the same way the CLI does — the write loop only fails safe if
+  // it never sees a bogus value. An unrecognized onConflict/resolution is a caller error, not
+  // a silent overwrite.
+  if (body.onConflict !== undefined && !ON_CONFLICT_MODES.includes(body.onConflict)) {
+    return badRequest(res, `onConflict must be one of: ${ON_CONFLICT_MODES.join(', ')}`);
+  }
+  if (body.resolutions !== undefined) {
+    if (!body.resolutions || typeof body.resolutions !== 'object' || Array.isArray(body.resolutions)) {
+      return badRequest(res, 'resolutions must be an object keyed by path');
+    }
+    for (const [path, choice] of Object.entries(body.resolutions)) {
+      if (!RESOLUTION_CHOICES.includes(choice)) {
+        return badRequest(res, `invalid resolution ${JSON.stringify(choice)} for ${path} (allowed: ${RESOLUTION_CHOICES.join(', ')})`);
+      }
+    }
+  }
+  try {
+    const result = await exportWorkflow({
+      workflowId: req.params.id, destination, projectDir,
+      slug: body.slug, includeAgents: body.includeAgents !== false,
+      dryRun: !!body.dryRun, onConflict: body.onConflict, resolutions: body.resolutions,
+    });
+    res.json(result); // Plan {created,noop,updated,conflicts,warnings,orphans} OR Apply {written,skipped,...}
+  } catch (err) {
+    res.status(workflowExportErrorStatus(err && err.code)).json({ error: err && err.message ? err.message : String(err) });
+  }
+});
+
 // ---------------------------------------------------------------------------
 // Guardrail sets (global store, table guardrail_sets). The built-ins
 // Permissive / Normal / Strict are VIRTUAL (GUARDRAIL_PRESETS) — the server
@@ -4558,12 +4716,45 @@ app.get('/api/marketplaces', (req, res) => {
   } catch (err) { sendPluginError(res, err); }
 });
 
+// Dev-mode link of a LOCAL plugin folder — the `worca plugin link <dir>` path
+// (validate, symlink current/, import its workflow templates). Reached directly
+// via POST /api/plugins/link, and by POST /api/marketplaces when the "marketplace"
+// handed in turns out to be a single plugin folder (the natural thing to paste
+// after `Export… → Worca plugin`, issue #421).
+async function linkPluginDir(dir) {
+  const abs = resolveProjectDir(dir);
+  if (!abs) throw Object.assign(new Error('dir is required'), { code: 'BAD_REQUEST' });
+  const v = validatePluginDir(abs);
+  if (!v.ok || !v.manifest) {
+    const lines = v.problems.filter((p) => p.level === 'error').map((p) => p.message);
+    throw Object.assign(new Error(`cannot link ${abs}: ${lines.join('; ') || 'not a valid plugin folder'}`), { code: 'BAD_REQUEST' });
+  }
+  let out;
+  try { out = await linkPlugin(v.manifest.name, abs); }
+  catch (err) { throw Object.assign(err instanceof Error ? err : new Error(String(err)), { code: err?.code || 'BAD_REQUEST' }); }
+  reloadChatWorkers(v.manifest.name);
+  return out; // { ok, name, dir, workflows: { imported, skipped } }
+}
+
+app.post('/api/plugins/link', async (req, res) => {
+  try {
+    res.json(await linkPluginDir(req.body && typeof req.body.dir === 'string' ? req.body.dir : ''));
+  } catch (err) { sendPluginError(res, err); }
+});
+
 app.post('/api/marketplaces', async (req, res) => {
   const url = req.body && typeof req.body.url === 'string' ? req.body.url.trim() : '';
   if (!url) return badRequest(res, 'url is required');
   try {
     res.json({ ok: true, marketplace: withInstalled([await addMarketplace(url)])[0] });
-  } catch (err) { sendPluginError(res, err); }
+  } catch (err) {
+    if (err && err.code === 'PLUGIN_FOLDER') {
+      // Not a marketplace but a plugin folder: link it, and SAY that is what happened.
+      try { return res.json({ ok: true, linked: true, plugin: await linkPluginDir(err.dir) }); }
+      catch (e) { return sendPluginError(res, e); }
+    }
+    sendPluginError(res, err);
+  }
 });
 
 // refresh-all (a distinct path from :id/refresh, so registration order is irrelevant).
@@ -5364,30 +5555,53 @@ if (isMain) {
     console.error(`[worca-ui] boot maintenance failed: ${err && err.message ? err.message : err}`);
   });
 
+  // A port that is already taken is an EXPECTED state (the UI is usually already
+  // up), not a crash: one line, no stack, exit 1. `worca ui` probes the port
+  // before spawning this process and prints the friendlier "already running"
+  // block itself; this branch is for `node ui/server.mjs` run by hand or a race.
   server.on('error', (err) => {
+    if (err && err.code === 'EADDRINUSE') {
+      console.error(`[worca-ui] port ${PORT} is already in use — is the UI already running?`);
+      console.error(`[worca-ui] check with \`worca ui status\`, restart with \`worca ui restart\`, or pick a port: \`worca ui --port <n>\``);
+      process.exit(1);
+    }
     console.error(`[worca-ui] server error: ${err && err.message ? err.message : err}`);
   });
 
+  // Channel workers must die with the server (design §9: persistent-process
+  // hygiene). Graceful shutdown frame -> 5s grace -> SIGKILL, then exit. The
+  // same path serves POST /api/shutdown (`worca ui stop`), which exits 0.
+  let shuttingDown = false;
+  let wroteInstanceFile = false;
+  const exitCodeFor = (signal) => (signal === 'SIGINT' ? 130 : signal === 'SIGTERM' ? 143 : 0);
+  const shutdown = (signal) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    channelHost.stop().finally(() => process.exit(exitCodeFor(signal)));
+  };
+  process.on('SIGINT', () => shutdown('SIGINT'));
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+  // 'exit' handlers must be synchronous; removeUiInstance is. `ifPid` keeps an
+  // old server exiting late from deleting the file a newer one just wrote.
+  process.on('exit', () => { if (wroteInstanceFile) removeUiInstance({ ifPid: process.pid }); });
+
   server.listen(PORT, HOST, () => {
-    const shown = HOST === '127.0.0.1' || HOST === '::1' ? 'localhost' : HOST;
-    const url = `http://${shown}:${PORT}`;
+    const port = server.address().port;
+    const url = uiUrl({ host: HOST, port });
     console.log(`[worca-ui] listening on ${url} (bound to ${HOST})`);
-    console.log(`[worca-ui] WebSocket on ws://${shown}:${PORT}/ws`);
+    uiControl.token = newUiToken();
+    uiControl.onShutdown = shutdown;
+    uiControl.startedAt = new Date().toISOString();
+    writeUiInstance({
+      pid: process.pid, host: HOST, port, token: uiControl.token,
+      version: PKG_VERSION, startedAt: uiControl.startedAt,
+    }).then(() => { wroteInstanceFile = true; }, (err) => {
+      console.error(`[worca-ui] could not write the instance file (\`worca ui stop\` will fall back to a signal): ${err && err.message ? err.message : err}`);
+    });
     try { channelHost.start(); } catch (err) {
       console.error(`[worca-ui] chat channel host failed to start: ${err && err.message ? err.message : err}`);
     }
   });
-
-  // Channel workers must die with the server (design §9: persistent-process
-  // hygiene). Graceful shutdown frame -> 5s grace -> SIGKILL, then exit.
-  let shuttingDown = false;
-  const shutdownChat = (signal) => {
-    if (shuttingDown) return;
-    shuttingDown = true;
-    channelHost.stop().finally(() => process.exit(signal === 'SIGINT' ? 130 : 143));
-  };
-  process.on('SIGINT', () => shutdownChat('SIGINT'));
-  process.on('SIGTERM', () => shutdownChat('SIGTERM'));
 }
 
 export { app, server, runs };
@@ -5396,4 +5610,5 @@ export const _testing = {
   chatActions, chatRouter, channelHost, handleChatInbound, enqueueChatWork,
   chatNotifier, resumeRun, resolveHljsAssets, resolveEsmAsset, askJobs, askFollowers, askDeleting, resolveAskContext, flipCard,
   emitDiffCommentsChanged, emitAskWorktrees, askWorktreesEnvelope, deleteAskThreadFully,
+  uiControl, bearerMatches,
 };