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

package/README.md

@@ -90,6 +90,15 @@ and durations, the clarify Q&A, agent transcripts, and logs:
   runs out). Flow cards — **Task** (the run's request), **End** (the result),
   **AND**, **OR**, **Combine** — express joins, choices and merges without any
   code. Saved pipelines appear in the New Pipeline picker.
+- **Share a pipeline** — *Export…* on a saved pipeline offers three formats.
+  A *JSON file* passes it to another Worca user, who picks it up with
+  *Import…* (a taken name gets a ` (2)` suffix; nothing is ever overwritten).
+  A *Claude Code skill* turns it into a runnable `/command` under `.claude/`
+  so it runs without Worca. A *Worca plugin* folder bundles the pipeline with
+  your own agents it uses and the skills they need, so the recipient runs
+  `worca plugin link <folder>` and updates later with `worca plugin reimport`.
+  Built-in agents are never copied — a plugin pipeline may reference them
+  directly. The saved list is tabbed by domain; click a card to open it.
 
 ![Workflow Composer — drag agents into steps, groups, and feedback loops](docs/screenshots/composer.png)
 
@@ -143,6 +152,12 @@ and durations, the clarify Q&A, agent transcripts, and logs:
   per-model routing environment (e.g. `ANTHROPIC_BASE_URL`) that is merged
   into that model's agent spawns. Share a model catalog as a plugin, with
   secrets required at install time.
+- **No first-party account needed** — run and chat titles are written by the
+  model the run or chat itself uses (Settings › General › Title generation picks
+  a fixed one instead), endpoint-routed models carry Claude Code's internal
+  haiku/sonnet/opus/fable tier keys so nothing falls back to the Anthropic API,
+  and *Hide built-in models* (Settings › Models) drops the built-ins from every
+  picker.
 
 ### Storage
 
@@ -177,7 +192,7 @@ Requirements:
 ### Web UI
 
 ```bash
-worca --ui
+worca ui            # start it (worca --ui does the same)
 ```
 
 Open the printed URL (default `http://localhost:4317`), add a project, and
@@ -186,6 +201,20 @@ a task from a plugin source like GitHub Issues), pick a workflow and
 guardrails, and run. Answer clarify questions and loop gates as they come —
 in the browser or from chat.
 
+The UI is one process per machine. Starting it while it is already up is not
+an error — Worca prints the URL and how to restart it, and exits 0:
+
+```bash
+worca ui status                 # is it running? (exit 0 = yes, 1 = no)
+worca ui restart                # stop the running one, start it again
+worca ui stop                   # stop it gracefully
+worca ui --port 4318 --open     # another port; open the browser when up
+```
+
+`--port` (or the `PORT` env var) picks the port; `stop`, `restart` and
+`status` remember the port of the last started UI, so they usually need no
+flag. See `worca ui help`.
+
 ### CLI
 
 ```bash
@@ -200,10 +229,15 @@ worca resume <pipelineId>
 
 # offline demo — full pipeline, no tokens
 worca --project /path/to/your/project --prompt "demo task" --mock --yes
+
+# share a saved pipeline: as JSON, or as a plugin folder bundling your agents + skills
+worca workflow export wf_my-flow --format json --out my-flow.json
+worca workflow import my-flow.json
+worca workflow export wf_my-flow --format plugin --target ./my-flow-plugin
 ```
 
 Run `worca --help` for all subcommands (projects, plugins, marketplaces,
-config, doctor) and flags.
+workflows, config, doctor) and flags.
 
 Exit codes, for scripts and CI wrappers: `0` the run finished (or an
 interactive run paused and you can resume it); `1` a hard error, a stop, or an

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@worca/app",
-  "version": "1.2.0-rc.1",
+  "version": "1.2.0-rc.3",
   "description": "Worca — deterministic multi-agent pipeline that drives Claude Code (headless) through Plan -> Refine -> Implement -> Review, with a CLI, an installable /worca skill, and a web UI.",
   "license": "MIT",
   "author": "Sinisha Djukic",

package/src/cli/worca-cc.mjs

@@ -4,7 +4,8 @@
 // CLI entry point. Parses flags, creates a core orchestrator, subscribes to its events,
 // renders a phase tracker + streamed agent logs to the terminal, and drives interactive
 // Q&A (clarify) and loop gates via node:readline. Supports --yes (auto), --mock,
-// --install <dir> (delegates to scripts/install.mjs), --ui (spawns ui/server.mjs),
+// --install <dir> (delegates to scripts/install.mjs), ui start|stop|restart|status
+// (--ui is an alias of `ui start`; see cmdUi),
 // and -v/-V/--version (also the bare word `version`).
 //
 // ESM, no external dependencies.
@@ -28,6 +29,10 @@ import {
 import { projectKey } from '../core/store.mjs';
 import { formatExecLine, formatGateHeader, formatRunSummary } from './render.mjs';
 import { pauseExitCode, describePauseReason, promptOptions, REASON } from '../core/failure-policy.mjs';
+import { effectiveDebugSpawn } from '../core/settings.mjs';
+import {
+  DEFAULT_UI_HOST, DEFAULT_UI_PORT, probeUi, stopUi, readUiInstance, uiUrl, waitForUiState,
+} from '../core/ui-instance.mjs';
 
 // ── node:sqlite runtime guard + warning filter ──────────────────────────────────
 // Drop ONLY the one-time ExperimentalWarning emitted by node:sqlite (the module is
@@ -204,7 +209,7 @@ Usage:
   worca --prompt "<task>" [--project <dir>] [options]
   worca --file <task.md> [--project <dir>] [options]
   worca "<task>" [--project <dir>] [options]   (bare prompt; quote it)
-  worca --ui
+  worca ui [start|stop|restart|status] [--port <n>] [--open]
   worca --install <targetDir> [--force]
 
 Subcommands:
@@ -218,6 +223,9 @@ Subcommands:
                               disable|doctor|link|reimport|init|validate|exec. See: worca plugin help
   marketplace <cmd> [...]     Manage plugin marketplaces: add|list|refresh|remove. See: worca marketplace help
   config [get|set|unset]      Budget & cost-limit settings
+  ui [start|stop|restart|status]
+                              Run the web UI (default http://localhost:4317). See: worca ui help
+  workflow <cmd> [...]        Export a workflow (Claude Code skill, JSON, or plugin) / import JSON: list|export|import. See: worca workflow help
   help                        Print this help (same as --help).
   version                     Print the version (same as --version).
 
@@ -236,7 +244,7 @@ Options:
   --branch <name>          Feature branch name (default: claude proposes one)
   --mock                   Offline mock mode (no claude, no tokens)
   --yes, --non-interactive Auto-answer clarify (first option) and gates (continue)
-  --ui                     Launch the web UI (ui/server.mjs) and exit
+  --ui                     Same as "worca ui start" (accepts --port, --open, --mock)
   --install <targetDir>    Copy agents + /worca skill into <targetDir>/.claude
   -h, --help               Show this help
   -v, -V, --version        Print the version (worca <semver>) and exit
@@ -629,11 +637,97 @@ async function attachAndDrive(orch, flags, start) {
 
 // ── subcommands ──────────────────────────────────────────────────────────────────
 
-/** Spawn the web UI server and inherit its stdio. Resolves when it exits. */
-function launchUi() {
+// ── web UI lifecycle ─────────────────────────────────────────────────────────────
+//
+// The UI is a singleton over the machine-wide store, so `worca ui` never blindly
+// binds: it probes the port first (src/core/ui-instance.mjs). A Worca UI already
+// answering there is the EXPECTED state — print where it is and how to restart
+// it, exit 0. Only a port held by some other program is an error (exit 1).
+
+const UI_HELP = `worca ui — the web UI server
+
+Usage:
+  worca ui [start] [--port <n>] [--open] [--mock]   Start the UI (default http://localhost:${DEFAULT_UI_PORT})
+  worca ui stop [--port <n>]                        Stop the running UI gracefully
+  worca ui restart [--port <n>] [--open] [--mock]   Stop it if running, then start it again
+  worca ui status [--port <n>]                      Report whether it is running (exit 0 = running, 1 = not)
+  worca ui help                                     Show this help
+
+Options:
+  --port <n>   Port to bind (start) or to look at (stop/restart/status).
+               Default: the PORT env var, then ${DEFAULT_UI_PORT}. stop/restart/status
+               also read the port of the last started UI (<worca home>/ui.json).
+  --open       Open the UI in your browser once it is up
+  --mock       Start in offline mock mode (same as WORCA_MOCK=1)
+
+\`worca --ui\` is an alias of \`worca ui start\`.
+`;
+
+/** Bind/probe port for a `worca ui` verb: --port > (instance file) > PORT env > default. */
+function resolveUiPort(a, { preferInstanceFile = false } = {}) {
+  if (a.port !== undefined) {
+    const n = Number(a.port);
+    if (!Number.isInteger(n) || n < 1 || n > 65535) fail(`--port must be an integer between 1 and 65535, got: ${a.port}`);
+    return { port: n, host: process.env.WORCA_HOST || DEFAULT_UI_HOST };
+  }
+  if (preferInstanceFile) {
+    const inst = readUiInstance();
+    if (inst) return { port: inst.port, host: inst.host || process.env.WORCA_HOST || DEFAULT_UI_HOST };
+  }
+  const env = Number(process.env.PORT);
+  const port = Number.isInteger(env) && env > 0 ? env : DEFAULT_UI_PORT;
+  return { port, host: process.env.WORCA_HOST || DEFAULT_UI_HOST };
+}
+
+/** Best-effort `open`/`start`/`xdg-open`; never throws, never keeps the CLI alive. */
+function openBrowser(url) {
+  const [cmd, args] = process.platform === 'darwin' ? ['open', [url]]
+    : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]]
+    : ['xdg-open', [url]];
+  try {
+    const p = spawn(cmd, args, { stdio: 'ignore', detached: true });
+    p.on('error', () => {});
+    p.unref();
+  } catch { /* no browser opener on this box — the URL is printed anyway */ }
+}
+
+/** Spawn ui/server.mjs on `port` and inherit its stdio. Resolves with its exit code. */
+async function uiStart(a) {
+  const { port, host } = resolveUiPort(a);
+  const url = uiUrl({ host, port });
+  const probe = await probeUi({ host, port });
+  if (probe.state === 'worca') {
+    out(`Worca UI is already running at ${c('bold', url)}`);
+    out('');
+    out(`  Open it:       ${url}`);
+    out(`  Restart it:    ${c('bold', 'worca ui restart')}`);
+    out(`  Another port:  ${c('bold', `worca ui --port ${port + 1}`)}`);
+    if (a.open) openBrowser(url);
+    return 0;
+  }
+  if (probe.state === 'busy') {
+    process.stderr.write(`worca: port ${port} is in use by another program, so the Worca UI cannot start.\n\n`
+      + `  Pick a free port:  worca ui --port ${port + 1}   (or set PORT)\n`);
+    return 1;
+  }
+  // A UI started earlier on some OTHER port is worth a note, not a refusal.
+  const inst = readUiInstance();
+  if (inst && inst.port !== port) {
+    const other = await probeUi({ host: inst.host, port: inst.port });
+    if (other.state === 'worca') out(c('gray', `Note: another Worca UI is running at ${uiUrl({ host: inst.host, port: inst.port })}`));
+  }
+
   const server = join(REPO_ROOT, 'ui', 'server.mjs');
-  out(c('cyan', `Launching web UI: node ${server}`));
-  const child = spawn(process.execPath, [server], { stdio: 'inherit' });
+  out(c('cyan', `Starting Worca UI on ${url}`));
+  if (effectiveDebugSpawn().enabled) out(c('gray', `  node ${server}`));
+  const env = { ...process.env, PORT: String(port) };
+  if (a.mock) env.WORCA_MOCK = '1';
+  const child = spawn(process.execPath, [server], { stdio: 'inherit', env });
+  if (a.open) {
+    waitForUiState({ host, port, states: ['worca'], timeoutMs: 20000 })
+      .then((r) => { if (r) openBrowser(url); })
+      .catch(() => {});
+  }
   return new Promise((res) => {
     child.on('exit', (code) => res(code ?? 0));
     child.on('error', (err) => {
@@ -643,6 +737,75 @@ function launchUi() {
   });
 }
 
+/** Stop the UI on the resolved port. Idempotent: "not running" exits 0. */
+async function uiStop(a, { quiet = false } = {}) {
+  const { port, host } = resolveUiPort(a, { preferInstanceFile: true });
+  const r = await stopUi({ host, port });
+  switch (r.status) {
+    case 'stopped':
+      out(`Stopped Worca UI on port ${port}${r.pid ? ` (pid ${r.pid})` : ''}.`);
+      return 0;
+    case 'not-running':
+      if (!quiet) out(`Worca UI is not running on port ${port}.`);
+      return 0;
+    case 'busy':
+      process.stderr.write(`worca: port ${port} is in use by another program, not a Worca UI — nothing to stop.\n`);
+      return 1;
+    case 'timeout':
+      process.stderr.write(`worca: the Worca UI on port ${port}${r.pid ? ` (pid ${r.pid})` : ''} did not exit in time.\n`);
+      return 1;
+    default:
+      process.stderr.write(`worca: could not stop the Worca UI on port ${port}: ${r.reason || r.status}\n`);
+      return 1;
+  }
+}
+
+async function uiStatus(a) {
+  const { port, host } = resolveUiPort(a, { preferInstanceFile: true });
+  const probe = await probeUi({ host, port });
+  if (probe.state === 'worca') {
+    const info = probe.info || {};
+    const detail = [info.pid ? `pid ${info.pid}` : null, info.version ? `v${info.version}` : null].filter(Boolean).join(', ');
+    out(`Worca UI is running at ${c('bold', uiUrl({ host, port }))}${detail ? ` (${detail})` : ''}`);
+    return 0;
+  }
+  if (probe.state === 'busy') {
+    out(`Worca UI is not running on port ${port} (the port is in use by another program).`);
+    return 1;
+  }
+  out(`Worca UI is not running on port ${port}.`);
+  return 1;
+}
+
+/** `worca ui [start|stop|restart|status|help] [--port <n>] [--open] [--mock]` */
+async function cmdUi(argv) {
+  const verbs = new Set(['start', 'stop', 'restart', 'status']);
+  let verb = 'start';
+  let rest = argv;
+  if (argv[0] === 'help' || argv[0] === '--help' || argv[0] === '-h') {
+    process.stdout.write(UI_HELP);
+    return 0;
+  }
+  if (argv[0] && !argv[0].startsWith('-')) {
+    if (!verbs.has(argv[0])) fail(`unknown ui command "${argv[0]}" — expected one of: start, stop, restart, status (see: worca ui help)`);
+    verb = argv[0];
+    rest = argv.slice(1);
+  }
+  const a = pluginArgs(rest, ['--port'], ['--open', '--mock']);
+  if (a._.length) fail(`unexpected argument: ${a._[0]} (see: worca ui help)`);
+  if (verb === 'stop') return uiStop(a);
+  if (verb === 'status') return uiStatus(a);
+  if (verb === 'restart') {
+    // Pin the port stop resolved (possibly from the instance file) so start reuses it.
+    const { port } = resolveUiPort(a, { preferInstanceFile: true });
+    a.port = String(port);
+    const code = await uiStop(a, { quiet: true });
+    if (code !== 0) return code;
+    return uiStart(a);
+  }
+  return uiStart(a);
+}
+
 /** Delegate to scripts/install.mjs, forwarding the target dir and any passthrough args. */
 function runInstall(targetDir, passthrough) {
   const script = join(REPO_ROOT, 'scripts', 'install.mjs');
@@ -1041,6 +1204,43 @@ working, including updates (install provenance lives in plugins.lock.json).
 Exit codes: 0 ok, 1 failure, 2 usage/validation errors.
 `;
 
+const WORKFLOW_HELP = `worca workflow — export a saved Composer workflow (as a Claude Code skill, as
+shareable JSON, or as a Worca plugin) and import one shared as JSON
+
+Usage:
+  worca workflow list                                List workflows (id, name, domain)
+  worca workflow export <id> [options]               Export a workflow (see --format)
+  worca workflow import <file> [--name <name>]       Import a JSON export into your library ('-' = stdin)
+
+Export formats (--format):
+  claude (default)         A runnable Claude Code skill tree under <dest>/.claude/
+  json                     The shareable v2 graph, to stdout (or --out <file>)
+  plugin                   A Worca plugin folder (--target <dir>) bundling the workflow,
+                           your own agents it uses and the skills they require; the
+                           recipient runs: worca plugin link <dir>
+
+Options (claude):
+  --global                 Export to the home dir (~/.claude), not a project
+  --target <dir>           Export into <dir>/.claude (default: cwd)
+  --slug <name>            Skill slug (default: slugified workflow name)
+  --dry-run                Show the classification (create/update/no-op/conflict); write nothing
+  --on-conflict <mode>     skip (default) | overwrite | namespace conflicting files
+Options (json):
+  --out <file>             Write to <file> instead of stdout
+Options (plugin):
+  --target <dir>           The plugin folder (created, or updated in place)
+  --name <plugin>          Plugin name (default: an existing manifest's name, else the folder name)
+  --keep-version           Do not patch-bump the manifest version on an update
+  --dry-run                Show the classification; write nothing
+
+Import: the id is minted from the name; a name already in use gets a " (2)" suffix —
+nothing is ever overwritten. A workflow that needs agents you do not have is refused;
+ask its author for the plugin export instead.
+
+Export always prints the plan first, then applies (unless --dry-run). A re-export
+of an unchanged workflow is an all-no-op. Exit codes: 0 ok, 1 failure, 2 usage/validation errors.
+`;
+
 /** Tiny per-verb arg parser: positionals plus declared --value / --bool flags. */
 function pluginArgs(argv, valueFlags = [], boolFlags = []) {
   const out = { _: [] };
@@ -1058,7 +1258,7 @@ function pluginArgs(argv, valueFlags = [], boolFlags = []) {
       out[a.slice(2)] = v;
     } else if (boolFlags.includes(a)) {
       out[a.slice(2)] = true;
-    } else if (a.startsWith('-')) {
+    } else if (a.startsWith('-') && a !== '-') {                 // a lone '-' is the stdin positional
       fail(`Unknown flag: ${a}`);
     } else {
       out._.push(a);
@@ -1143,9 +1343,8 @@ async function pluginInit(rest) {
   for (const part of withParts) {
     if (!INIT_PARTS.includes(part)) fail(`unknown --with part "${part}" (known: ${INIT_PARTS.join(', ')})`);
   }
-  if (withParts.includes('workflows') && !withParts.includes('agents')) {
-    fail('--with workflows requires agents (templates may only reference the plugin\'s own agent keys)');
-  }
+  // `--with workflows` no longer requires `agents`: a plugin template may reference
+  // built-in agents (#421), so a workflow-only plugin scaffolds a built-in chain.
   const target = resolve(process.cwd(), a.dir || name);
   const { mkdir, writeFile, chmod, readdir } = await import('node:fs/promises');
   try {
@@ -1254,19 +1453,24 @@ async function pluginInit(rest) {
   }
   if (withParts.includes('workflows')) {
     // A v2 graph: the Task and End cards are mandatory (V20/V21) and every input
-    // takes exactly one wire (V7). Ports come from the sidecar above.
+    // takes exactly one wire (V7). With agents, ports come from the sidecar above;
+    // without, the chain runs the built-in planner (a plugin template may
+    // reference built-ins — they are on every host).
+    const withAgent = withParts.includes('agents');
+    const key = withAgent ? agentKey : 'planner';
+    const outPort = withAgent ? 'notes' : 'plan';
     files.set('workflows/example-flow.json', JSON.stringify({
       name: `${name} example flow`,
       version: 2,
       domain: 'general',
       nodes: [
         { id: 'n_task', kind: 'task', x: 40, y: 200, config: {} },
-        { id: 'n_helper', kind: 'agent', key: agentKey, x: 320, y: 200, config: {} },
+        { id: 'n_helper', kind: 'agent', key, x: 320, y: 200, config: {} },
         { id: 'n_end', kind: 'end', x: 600, y: 200, config: {} },
       ],
       wires: [
         { id: 'w1', from: { node: 'n_task', port: 'task' }, to: { node: 'n_helper', port: 'task' } },
-        { id: 'w2', from: { node: 'n_helper', port: 'notes' }, to: { node: 'n_end', port: 'result' } },
+        { id: 'w2', from: { node: 'n_helper', port: outPort }, to: { node: 'n_end', port: 'result' } },
       ],
     }, null, 2) + '\n');
   }
@@ -1676,9 +1880,141 @@ async function cmdMarketplace(argv) {
   }
 }
 
+async function cmdWorkflow(argv) {
+  const verb = argv[0];
+  const rest = argv.slice(1);
+  if (!verb || verb === 'help') { process.stdout.write(WORKFLOW_HELP); return 0; }
+  const wf = await import('../core/workflows.mjs');
+  const xp = await import('../core/workflow-export.mjs');
+  const share = await import('../core/workflow-share.mjs');
+  const { formatIssue } = await import('../shared/graph/validate.mjs');
+  try {
+    switch (verb) {
+      case 'list': {
+        // GRAPH_DEFAULT_WORKFLOW (the built-in default) is not in the user store, so
+        // prepend it — mirrors the server/UI, which always show it first.
+        const items = [wf.GRAPH_DEFAULT_WORKFLOW, ...(await wf.listWorkflows())];
+        for (const w of items) out(`${w.id}\t${w.name}\t${(w.domain || 'general')}`);
+        return 0;
+      }
+      case 'import': {
+        const a = pluginArgs(rest, ['--name'], []);
+        const file = a._[0];
+        if (!file) fail('Usage: worca workflow import <file> [--name <name>]');
+        const { readFile } = await import('node:fs/promises');
+        let text;
+        try {
+          text = file === '-'
+            ? await new Promise((res, rej) => { let s = ''; process.stdin.setEncoding('utf8'); process.stdin.on('data', (c) => (s += c)); process.stdin.on('end', () => res(s)); process.stdin.on('error', rej); })
+            : await readFile(resolve(process.cwd(), file), 'utf8');
+        } catch (e) { process.stderr.write(`worca workflow import: cannot read ${file}: ${e.message}\n`); return 1; }
+        let obj;
+        try { obj = JSON.parse(text); } catch (e) { process.stderr.write(`worca workflow import: ${file} is not valid JSON (${e.message})\n`); return 2; }
+        try {
+          const r = await share.importGraphWorkflow(obj, { name: a.name });
+          out(`imported\t${r.workflow.id}\t${r.workflow.name}`);
+          if (r.renamed) out(c('yellow', `renamed: "${r.requestedName}" was already taken — saved as "${r.workflow.name}"`));
+          for (const w of r.warnings || []) out(`${c('yellow', 'warn')}\t${formatIssue(w)}`);
+          return 0;
+        } catch (e) {
+          if (e && e.code === 'INVALID_GRAPH') {
+            process.stderr.write(`worca workflow import: ${e.summary || 'invalid graph'}\n`);
+            for (const issue of e.errors || []) process.stderr.write(`  - ${formatIssue(issue)}\n`);
+            return 2;
+          }
+          if (e && (e.code === 'BAD_REQUEST' || e.code === 'RESERVED_NAME')) { process.stderr.write(`worca workflow import: ${e.message}\n`); return 2; }
+          throw e;
+        }
+      }
+      case 'export': {
+        const a = pluginArgs(rest, ['--target', '--slug', '--on-conflict', '--format', '--out', '--name'], ['--global', '--dry-run', '--keep-version']);
+        const id = a._[0];
+        if (!id) fail('Usage: worca workflow export <id> [--format claude|json|plugin] [--global | --target <dir>] [--slug <name>] [--out <file>] [--name <plugin>] [--keep-version] [--dry-run] [--on-conflict=skip|overwrite|namespace]');
+        const format = a.format || 'claude';
+        if (!['claude', 'json', 'plugin'].includes(format)) fail(`--format must be claude|json|plugin (got ${format})`);
+
+        if (format === 'json') {
+          const payload = await share.exportGraphJson(id);
+          const text = JSON.stringify(payload, null, 2) + '\n';
+          if (a.out) {
+            const { writeFile } = await import('node:fs/promises');
+            const dest = resolve(process.cwd(), a.out);
+            await writeFile(dest, text, 'utf8');
+            out(`${c('green', 'wrote')}\t${dest}`);
+          } else {
+            process.stdout.write(text);
+          }
+          return 0;
+        }
+
+        if (format === 'plugin') {
+          if (!a.target) fail('--format plugin requires --target <dir> (the plugin folder)');
+          if (a.global) fail('--global does not apply to --format plugin');
+          const r = await xp.exportWorkflowPlugin({
+            workflowId: id, targetDir: resolve(process.cwd(), a.target), pluginName: a.name,
+            keepVersion: !!a['keep-version'], dryRun: !!a['dry-run'],
+          });
+          for (const p of r.created) out(`${c('green', 'create')}\t${p}`);
+          for (const p of r.updated) out(`${c('cyan', 'update')}\t${p}`);
+          for (const p of r.noop) out(`${c('gray', 'no-op')}\t${p}`);
+          for (const s of r.skipped) out(`${c('gray', 'skip')}\t${s.path}\t(${s.reason})`);
+          for (const w of r.warnings || []) out(`${c('yellow', 'warn')}\t${w}`);
+          for (const p of r.written) out(`${c('green', 'wrote')}\t${p}`);
+          if (r.validation && !r.validation.ok) {
+            out(c('yellow', `\nthe plugin folder does not validate — fix the errors above before sharing it`));
+            return 1;
+          }
+          if (!a['dry-run']) {
+            out(`\nplugin "${r.name}" v${r.version} at ${r.dir}`);
+            out(`share the folder; the recipient runs: worca plugin link ${r.dir}`);
+          }
+          return 0;
+        }
+
+        if (a.global && a.target) fail('--global and --target are mutually exclusive');
+        const onConflict = a['on-conflict'] || 'skip';
+        if (!xp.ON_CONFLICT_MODES.includes(onConflict)) fail(`--on-conflict must be ${xp.ON_CONFLICT_MODES.join('|')} (got ${onConflict})`);
+        const destination = a.global ? 'global' : 'project';
+        const projectDir = a.global ? undefined : (a.target || process.cwd());
+        const common = { workflowId: id, destination, projectDir, slug: a.slug };
+
+        // Always show the classification first. A dry-run stops at planExport (writes nothing);
+        // an apply reuses the buckets applyExport already computes, so the full resolve+classify
+        // pipeline runs ONCE, not twice.
+        const printPlan = (p) => {
+          for (const path of p.created) out(`${c('green', 'create')}\t${path}`);
+          for (const path of p.updated) out(`${c('cyan', 'update')}\t${path}`);
+          for (const path of p.noop) out(`${c('gray', 'no-op')}\t${path}`);
+          for (const cf of p.conflicts) out(`${c('yellow', 'conflict')}\t${cf.path}\t(${cf.reason})`);
+          for (const w of p.warnings || []) out(`${c('yellow', 'warn')}\t${w}`);
+          for (const o of p.orphans || []) out(`${c('gray', 'orphan')}\t${o}`);
+        };
+
+        if (a['dry-run']) { printPlan(await xp.planExport(common)); return 0; }
+
+        const applied = await xp.applyExport({ ...common, onConflict });
+        printPlan(applied);
+        for (const p of applied.written) out(`${c('green', 'wrote')}\t${p}`);
+        for (const p of applied.skipped) out(`${c('gray', 'skip')}\t${p}`);
+        if (applied.conflicts.length) {
+          // A partial export (conflicts skipped) can leave a non-runnable skill on disk. Warn AND
+          // exit non-zero so a CI/script that only checks the exit code does not treat it as success.
+          out(c('yellow', `\n${applied.conflicts.length} conflict(s) left unresolved (--on-conflict=${onConflict}). Re-run with --on-conflict=overwrite|namespace.`));
+          return 1;
+        }
+        return 0;
+      }
+      default: fail(`unknown workflow verb "${verb}" — see: worca workflow help`);
+    }
+  } catch (err) {
+    process.stderr.write(`worca workflow ${verb}: ${err && err.message ? err.message : err}\n`);
+    return 1;
+  }
+}
+
 // ── main ──────────────────────────────────────────────────────────────────────────
 
-const SUBCOMMANDS = new Set(['add', 'list', 'remove', 'resume', 'doctor', 'plugin', 'marketplace', 'config']);
+const SUBCOMMANDS = new Set(['add', 'list', 'remove', 'resume', 'doctor', 'plugin', 'marketplace', 'config', 'ui', 'workflow']);
 
 /** Levenshtein distance, two-row. Only ever called on short argv tokens. */
 function editDistance(a, b) {
@@ -1736,6 +2072,13 @@ async function main() {
     if (sub === 'plugin') return cmdPlugin(rest);
     if (sub === 'marketplace') return cmdMarketplace(rest);
     if (sub === 'config') return cmdConfig(rest);
+    if (sub === 'ui') return cmdUi(rest);
+    if (sub === 'workflow') return cmdWorkflow(rest);
+  }
+  // `worca --ui [...]` is the historical spelling of `worca ui start [...]`; hand the
+  // remaining tokens to the ui parser so --port/--open/--mock work with either.
+  if (process.argv.slice(2).includes('--ui')) {
+    return cmdUi(process.argv.slice(2).filter((t) => t !== '--ui'));
   }
 
   const flags = parseArgs(process.argv.slice(2));
@@ -1752,10 +2095,6 @@ async function main() {
     return runInstall(flags.install, passthrough);
   }
 
-  if (flags.ui) {
-    return launchUi();
-  }
-
   if (flags.mock) {
     process.env.WORCA_MOCK = '1';
   }

package/src/core/ask/models.mjs

@@ -47,7 +47,12 @@ export function createAskModels({
   /** The D8 initial pick, validated against the live catalog (D5). */
   function pickDefault(models) {
     const want = String(defaults.defaultModel || '').toLowerCase();
-    const hit = models.find((m) => m.id.toLowerCase() === want) || models[0] || null;
+    // Hidden built-ins (#422) are never the initial pick: on an install that
+    // hides them the default is the first model the user actually owns. They
+    // stay in `models` so a stored thread on one keeps validating.
+    const visible = models.filter((m) => !m.hidden);
+    const pool = visible.length ? visible : models;
+    const hit = pool.find((m) => m.id.toLowerCase() === want) || pool[0] || null;
     if (!hit) return null;
     const efforts = hit.efforts.length ? hit.efforts : [...EFFORTS];
     const effort = efforts.includes(defaults.defaultEffort)
@@ -83,6 +88,7 @@ export function createAskModels({
         hasEnv: m.hasEnv === true,
       };
       if (custom === 'plugin' && typeof m.plugin === 'string' && m.plugin) entry.plugin = m.plugin;
+      if (m.hidden === true) entry.hidden = true;   // the picker skips it; validation does not (#422)
       // Only globals and plugin entries can arrive flagged: composeCatalog emits an
       // UNSHADOWED built-in as {...m, custom:false, hasEnv:false} with no
       // ...unreliable(lc) (src/core/config.mjs:200), so a built-in in model_cost_flags

package/src/core/ask/turn.mjs

@@ -439,6 +439,11 @@ class AskTurn extends EventEmitter {
         tools: [], strictMcpConfig: true, settingSources: ['project'],
         disableSlashCommands: true, envScrub: true, envAllowlist: [],
         permissionMode: 'dontAsk',
+        // The chat's own model is the title default (#422) — a chat on a
+        // custom endpoint titles itself there, not on a first-party Haiku.
+        runModel: this.model,
+        onError: ({ model, error }) => console.warn(
+          `[worca-ask] thread ${this.threadId}: title generation failed (model ${model}): ${error?.message || error} — keeping the fallback title`),
       }))
       .then((generated) => {
         // The route stamps NOTHING before the 202 (the header reads "Ask Worca"