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

package/README.md

@@ -177,7 +177,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 +186,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@worca/app",
-  "version": "1.2.0-rc.1",
+  "version": "1.2.0-rc.2",
   "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,8 @@ 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
   help                        Print this help (same as --help).
   version                     Print the version (same as --version).
 
@@ -236,7 +243,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 +636,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 +736,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');
@@ -1678,7 +1840,7 @@ async function cmdMarketplace(argv) {
 
 // ── 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']);
 
 /** Levenshtein distance, two-row. Only ever called on short argv tokens. */
 function editDistance(a, b) {
@@ -1736,6 +1898,12 @@ 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);
+  }
+  // `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 +1920,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/ui-instance.mjs

@@ -0,0 +1,235 @@
+// src/core/ui-instance.mjs
+// The web UI is a singleton over the machine-wide store, so `worca ui` needs to
+// know whether one is already up before it spawns another — and needs a way to
+// stop the one that is. This module is the CLI side of that lifecycle; the server
+// side (GET /api/health, POST /api/shutdown, the instance file) lives in
+// ui/server.mjs.
+//
+// Discovery is the Jupyter runtime-file pattern: the server writes
+// <worcaHome>/ui.json ({ pid, host, port, token, version, startedAt }) once it is
+// listening and removes it on exit. The file is a HINT, never the truth — a
+// crashed server leaves it behind, so every decision re-probes the port:
+//
+//   probeUi({ port })  -> { state: 'worca', info }   a Worca UI answered /api/health
+//                      -> { state: 'busy' }          something else owns the port
+//                      -> { state: 'free' }          nothing is listening
+//
+// Stopping goes through POST /api/shutdown with the file's bearer token so the
+// server runs its graceful path (chat channel workers die cleanly) on every
+// platform — a bare signal is a hard kill on Windows. The signal is the fallback
+// when the token is unavailable (file missing, or a server too old to have one).
+
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import process from 'node:process';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+import { worcaHome } from './projects.mjs';
+
+export const DEFAULT_UI_PORT = 4317;
+export const DEFAULT_UI_HOST = '127.0.0.1';
+/** What GET /api/health must report as `name` for the occupant to count as a Worca UI. */
+export const UI_HEALTH_NAME = '@worca/app';
+
+/** Absolute path of the instance file for the current worcaHome. */
+export function uiInstanceFile() {
+  return join(worcaHome(), 'ui.json');
+}
+
+/** A fresh shutdown token (hex, 32 bytes of entropy). */
+export function newUiToken() {
+  return randomBytes(32).toString('hex');
+}
+
+/**
+ * Persist the running instance's coordinates. Atomic (tmp + rename) and 0600:
+ * the token authorizes a shutdown, so it must not be world-readable.
+ */
+export async function writeUiInstance({ pid, host, port, token, version, startedAt }) {
+  const file = uiInstanceFile();
+  await fsp.mkdir(join(file, '..'), { recursive: true });
+  const tmp = `${file}.${pid}.tmp`;
+  const body = JSON.stringify({ pid, host, port, token, version, startedAt }, null, 2) + '\n';
+  await fsp.writeFile(tmp, body, { mode: 0o600 });
+  await fsp.rename(tmp, file);
+  return file;
+}
+
+/** The instance file's contents, or null when missing/corrupt/not an object. */
+export function readUiInstance() {
+  try {
+    const data = JSON.parse(fs.readFileSync(uiInstanceFile(), 'utf8'));
+    if (!data || typeof data !== 'object' || Array.isArray(data)) return null;
+    const port = Number(data.port);
+    if (!Number.isInteger(port) || port <= 0) return null;
+    return { ...data, port, pid: Number(data.pid) || null };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Remove the instance file. With `ifPid`, only when the file still belongs to
+ * that process — an old server exiting late must not delete the file a newer
+ * one just wrote. Synchronous so it is usable from a process 'exit' handler.
+ */
+export function removeUiInstance({ ifPid } = {}) {
+  const file = uiInstanceFile();
+  try {
+    if (ifPid !== undefined) {
+      const cur = readUiInstance();
+      if (cur && cur.pid && cur.pid !== ifPid) return false;
+    }
+    fs.unlinkSync(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Host as it appears inside a URL (IPv6 literals need brackets). */
+export function urlHost(host) {
+  if (!host) return 'localhost';
+  if (host === '127.0.0.1' || host === '::1' || host === '[::1]' || host === 'localhost') return 'localhost';
+  return host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
+}
+
+/** The URL a browser should open for a UI bound to host:port. */
+export function uiUrl({ host = DEFAULT_UI_HOST, port = DEFAULT_UI_PORT } = {}) {
+  return `http://${urlHost(host)}:${port}`;
+}
+
+/** Host to CONNECT to (bind-any addresses are not dialable). */
+function dialHost(host) {
+  if (!host || host === '0.0.0.0' || host === '::') return DEFAULT_UI_HOST;
+  return host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
+}
+
+/** Every error code nested in a fetch failure (Node wraps them in `cause`, sometimes an AggregateError). */
+function errorCodes(err) {
+  const out = new Set();
+  const walk = (e, depth) => {
+    if (!e || depth > 4) return;
+    if (typeof e.code === 'string') out.add(e.code);
+    if (e.cause) walk(e.cause, depth + 1);
+    if (Array.isArray(e.errors)) for (const inner of e.errors) walk(inner, depth + 1);
+  };
+  walk(err, 0);
+  return out;
+}
+
+/** GET a JSON object from the UI, or null (non-2xx, non-JSON, non-object). Network errors propagate. */
+async function getJson(url, signal) {
+  const res = await fetch(url, { signal, headers: { accept: 'application/json' } });
+  if (!res.ok) return null;
+  try {
+    const data = await res.json();
+    return data && typeof data === 'object' && !Array.isArray(data) ? data : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Ask host:port whether a Worca UI is listening there.
+ *
+ * @returns {Promise<{state:'worca', info:object} | {state:'busy'} | {state:'free'}>}
+ *   'busy' covers every occupant that is not a Worca UI: a non-JSON answer, a
+ *   different `name`, a hang (timeout) or a reset. Only a clean connection
+ *   refusal is 'free'. A Worca UI from before /api/health existed is recognised
+ *   by its settings route and reported with `info.legacy = true` (no pid, no
+ *   token — it cannot be stopped from here, only from its own terminal).
+ */
+export async function probeUi({ host = DEFAULT_UI_HOST, port = DEFAULT_UI_PORT, timeoutMs = 1500 } = {}) {
+  const ctl = new AbortController();
+  const timer = setTimeout(() => ctl.abort(), timeoutMs);
+  const base = `http://${dialHost(host)}:${port}`;
+  try {
+    const info = await getJson(`${base}/api/health`, ctl.signal);
+    if (info) return info.name === UI_HEALTH_NAME ? { state: 'worca', info } : { state: 'busy' };
+    const legacy = await getJson(`${base}/api/settings`, ctl.signal);
+    if (legacy && typeof legacy.projectsRootDefault === 'string' && 'askMaxTurns' in legacy) {
+      return { state: 'worca', info: { name: UI_HEALTH_NAME, legacy: true } };
+    }
+    return { state: 'busy' };
+  } catch (err) {
+    const codes = errorCodes(err);
+    if (codes.has('ECONNREFUSED')) return { state: 'free' };
+    return { state: 'busy' };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** Poll until probeUi reports `state` (or any of `states`), or give up after timeoutMs. */
+export async function waitForUiState({ host, port, states, timeoutMs = 10000, intervalMs = 100 } = {}) {
+  const want = new Set(Array.isArray(states) ? states : [states]);
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const r = await probeUi({ host, port, timeoutMs: Math.min(1500, Math.max(200, deadline - Date.now())) });
+    if (want.has(r.state)) return r;
+    if (Date.now() >= deadline) return null;
+    await sleep(intervalMs);
+  }
+}
+
+/** True when a process with that pid exists (signal 0 probes without killing). */
+export function processAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (err) { return err && err.code === 'EPERM'; }
+}
+
+/**
+ * Stop the Worca UI on host:port, gracefully when possible.
+ *
+ * Order: (1) POST /api/shutdown with the instance file's token — the server
+ * answers 202 and exits through its signal path; (2) if that is refused or no
+ * token is known, SIGTERM the pid the health probe reported; (3) wait for the
+ * port to free up. Idempotent: a port with no Worca UI is `notRunning`, not an
+ * error. The instance file is cleaned up whenever the port ends up free.
+ *
+ * @returns {Promise<{status:'stopped', method:'request'|'signal', pid:number|null}
+ *                  |{status:'not-running'}
+ *                  |{status:'busy'}
+ *                  |{status:'failed', pid:number|null, reason:string}
+ *                  |{status:'timeout', pid:number|null}>}
+ */
+export async function stopUi({ host = DEFAULT_UI_HOST, port = DEFAULT_UI_PORT, token, timeoutMs = 10000 } = {}) {
+  const probe = await probeUi({ host, port });
+  if (probe.state === 'free') { removeUiInstance(); return { status: 'not-running' }; }
+  if (probe.state === 'busy') return { status: 'busy' };
+  if (probe.info.legacy) {
+    return { status: 'failed', pid: null, reason: 'it is an older Worca UI without shutdown support — stop it from its own terminal (Ctrl+C) and start again' };
+  }
+  const pid = Number(probe.info.pid) || null;
+
+  const file = readUiInstance();
+  const bearer = token || (file && file.port === port ? file.token : null);
+  let method = null;
+
+  if (bearer) {
+    try {
+      const res = await fetch(`http://${dialHost(host)}:${port}/api/shutdown`, {
+        method: 'POST',
+        headers: { authorization: `Bearer ${bearer}`, accept: 'application/json' },
+        signal: AbortSignal.timeout(3000),
+      });
+      if (res.status === 202 || res.status === 200) method = 'request';
+    } catch {
+      // The server may drop the connection while exiting — the wait below decides.
+      method = 'request';
+    }
+  }
+  if (!method && pid) {
+    try { process.kill(pid, 'SIGTERM'); method = 'signal'; } catch { /* already gone, or not ours */ }
+  }
+  if (!method) return { status: 'failed', pid, reason: 'no shutdown token in the instance file and no pid to signal' };
+
+  const freed = await waitForUiState({ host, port, states: ['free'], timeoutMs });
+  if (!freed) return { status: 'timeout', pid };
+  removeUiInstance();
+  return { status: 'stopped', method, pid };
+}

package/ui/server.mjs

@@ -93,6 +93,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,
@@ -174,6 +177,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 +216,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 +279,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();
@@ -2781,6 +2790,49 @@ const settingsState = () => ({
   debugSpawnEffective: effectiveDebugSpawn(),             // what the next spawn will DO, and why
 });
 
+// ---------------------------------------------------------------------------
+// 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) => {
   res.json({ ...settingsState(), chat: chatPrefs() });
 });
@@ -5364,30 +5416,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 +5471,5 @@ export const _testing = {
   chatActions, chatRouter, channelHost, handleChatInbound, enqueueChatWork,
   chatNotifier, resumeRun, resolveHljsAssets, resolveEsmAsset, askJobs, askFollowers, askDeleting, resolveAskContext, flipCard,
   emitDiffCommentsChanged, emitAskWorktrees, askWorktreesEnvelope, deleteAskThreadFully,
+  uiControl, bearerMatches,
 };