@worca/ui 0.13.0 → 0.14.0

package/server/project-routes.js

@@ -19,12 +19,17 @@ import {
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { Router } from 'express';
+import lockfile from 'proper-lockfile';
 import { actionAllowed } from '../app/utils/state-actions.js';
+import { atomicWriteSync } from './atomic-write.js';
 import { dbExists, getIssue, listIssues } from './beads-reader.js';
 import { dispatchExternal } from './dispatch-external.js';
 import { ensureWebhookForUi } from './ensure-webhook.js';
+import { extractAndStripGlobalKeys } from './global-keys.js';
+import { LaunchLock } from './launch-lock.js';
 import { readPreferences } from './preferences.js';
 import { ProcessManager } from './process-manager.js';
+import { countRunningPipelinesAcrossProjects } from './process-registry.js';
 import {
   getMaxProjects,
   readProjects,
@@ -35,10 +40,12 @@ import {
   writeProject,
 } from './project-registry.js';
 import {
+  deepMerge,
   localPathFor,
   readLocalSettings,
   readMergedSettings,
 } from './settings-merge.js';
+import { readGlobalSettings, writeGlobalSettings } from './settings-reader.js';
 import { validateSettingsPayload } from './settings-validator.js';
 import { isVersionBehind } from './version-check.js';
 import { getVersionInfo } from './versions.js';
@@ -61,22 +68,11 @@ function validateRunId(runId) {
   );
 }
 
-/**
- * Find the status.json path for a given run ID.
- * Searches: runs/{id}/status.json → results/{id}/status.json → results/{id}.json
- * Returns the first existing path, or null if none found.
- */
-export function findRunStatusPath(worcaDir, runId) {
-  const candidates = [
-    join(worcaDir, 'runs', runId, 'status.json'),
-    join(worcaDir, 'results', runId, 'status.json'),
-    join(worcaDir, 'results', `${runId}.json`),
-  ];
-  for (const p of candidates) {
-    if (existsSync(p)) return p;
-  }
-  return null;
-}
+// Re-exported from run-dir-resolver so callers (including older tests) can
+// continue importing from project-routes. The implementation now overlays
+// worktree runs registered in <worcaDir>/multi/pipelines.d/.
+import { findRunStatusPath } from './run-dir-resolver.js';
+export { findRunStatusPath };
 
 /** Validate a branch name — alphanumeric, dots, hyphens, underscores, slashes */
 const BRANCH_RE = /^[\w.\-/]+$/;
@@ -139,6 +135,7 @@ export function projectResolver({ prefsDir, projectRoot }) {
         settingsPath:
           project.settingsPath ||
           join(project.path, '.claude', 'settings.json'),
+        prefsDir,
       }),
     };
     next();
@@ -323,13 +320,17 @@ export function createProjectRoutes({
 /**
  * Router for project-scoped sub-routes.
  * The projectResolver middleware must run before this to set req.project.
- * @param {{ prefsDir?: string|null }} [options] — prefsDir enables active
- *   worca-cc version lookup for /worca-status' `outdated` flag.
+ * @param {{ prefsDir?: string|null, launchLock?: LaunchLock }} [options] —
+ *   prefsDir enables active worca-cc version lookup for /worca-status'
+ *   `outdated` flag and gates the global max_concurrent_pipelines check.
+ *   launchLock should be injected by createApp so all routers share the
+ *   same mutex; falls back to a per-router instance if omitted (tests).
  */
 export function createProjectScopedRoutes({
   prefsDir = null,
   serverHost,
   serverPort,
+  launchLock = new LaunchLock(),
 } = {}) {
   const router = Router({ mergeParams: true });
   const prefsPath = prefsDir ? join(prefsDir, 'preferences.json') : null;
@@ -447,7 +448,7 @@ export function createProjectScopedRoutes({
   });
 
   // POST /api/projects/:projectId/settings
-  router.post('/settings', (req, res) => {
+  router.post('/settings', async (req, res) => {
     const { settingsPath } = req.project;
     if (!settingsPath) {
       return res.status(501).json({
@@ -481,25 +482,87 @@ export function createProjectScopedRoutes({
     }
 
     try {
-      const lp = localPathFor(settingsPath);
-      const local = readLocalSettings(settingsPath);
+      let baseChanged = false;
+      let base = {};
+      try {
+        if (existsSync(settingsPath)) {
+          base = JSON.parse(readFileSync(settingsPath, 'utf8'));
+        }
+      } catch {
+        base = {};
+      }
 
       if (body.worca && typeof body.worca === 'object') {
-        if (!local.worca) local.worca = {};
-        for (const key of Object.keys(body.worca)) {
-          local.worca[key] = body.worca[key];
+        if (!base.worca || typeof base.worca !== 'object') base.worca = {};
+        base.worca = deepMerge(base.worca, body.worca);
+
+        if (
+          body.worca.governance &&
+          typeof body.worca.governance === 'object' &&
+          body.worca.governance.subagent_dispatch !== undefined &&
+          base.worca.governance &&
+          typeof base.worca.governance === 'object' &&
+          'dispatch' in base.worca.governance
+        ) {
+          delete base.worca.governance.dispatch;
+        }
+        baseChanged = true;
+      }
+
+      // STEP 1: extract misplaced global keys + inert milestone keys
+      const autoMigrated = extractAndStripGlobalKeys(base);
+
+      // STEP 2: write extracted global keys to ~/.worca/settings.json
+      const globalSettingsPath = prefsDir
+        ? join(prefsDir, 'settings.json')
+        : null;
+
+      if (
+        globalSettingsPath &&
+        Object.keys(autoMigrated.globalExtracted).length > 0
+      ) {
+        let release;
+        try {
+          release = await lockfile.lock(globalSettingsPath, {
+            retries: { retries: 5, minTimeout: 50, maxTimeout: 500 },
+            realpath: false,
+          });
+          writeGlobalSettings(globalSettingsPath, {
+            worca: autoMigrated.globalExtracted,
+          });
+        } catch (err) {
+          return res.status(500).json({
+            error: {
+              code: 'global_write_error',
+              message:
+                'Failed to migrate global keys; project settings not saved.',
+              detail: err.message,
+            },
+          });
+        } finally {
+          if (release) await release();
         }
       }
+
+      // STEP 3: atomic project write
+      if (baseChanged) {
+        mkdirSync(dirname(settingsPath), { recursive: true });
+        atomicWriteSync(settingsPath, `${JSON.stringify(base, null, 2)}\n`);
+      }
+
       if (body.permissions !== undefined) {
+        const lp = localPathFor(settingsPath);
+        const local = readLocalSettings(settingsPath);
         local.permissions = body.permissions;
+        mkdirSync(dirname(lp), { recursive: true });
+        writeFileSync(lp, `${JSON.stringify(local, null, 2)}\n`, 'utf8');
       }
 
-      writeFileSync(lp, `${JSON.stringify(local, null, 2)}\n`, 'utf8');
-
       const merged = readMergedSettings(settingsPath);
       res.json({
         worca: merged.worca || {},
         permissions: merged.permissions || {},
+        autoMigrated,
       });
     } catch (err) {
       res
@@ -540,17 +603,52 @@ export function createProjectScopedRoutes({
     }
 
     try {
+      // Mirror the persistence split used in POST: worca-namespace keys live
+      // in settings.json; top-level keys (permissions) live in
+      // settings.local.json. Reset removes from both as needed and also
+      // clears any legacy worca-namespace overrides that may still exist in
+      // settings.local.json from before the split.
       const lp = localPathFor(settingsPath);
       const local = readLocalSettings(settingsPath);
+      let baseChanged = false;
+      let base = {};
+      try {
+        if (existsSync(settingsPath)) {
+          base = JSON.parse(readFileSync(settingsPath, 'utf8'));
+        }
+      } catch {
+        base = {};
+      }
 
-      if (mapping.worca && local.worca) {
-        for (const key of mapping.worca) delete local.worca[key];
-        if (Object.keys(local.worca).length === 0) delete local.worca;
+      if (mapping.worca) {
+        if (base.worca) {
+          for (const key of mapping.worca) {
+            if (key in base.worca) {
+              delete base.worca[key];
+              baseChanged = true;
+            }
+          }
+          if (Object.keys(base.worca).length === 0) delete base.worca;
+        }
+        // Strip any legacy local override at the same paths.
+        if (local.worca) {
+          for (const key of mapping.worca) delete local.worca[key];
+          if (Object.keys(local.worca).length === 0) delete local.worca;
+        }
       }
       if (mapping.top) {
         for (const key of mapping.top) delete local[key];
       }
 
+      if (baseChanged) {
+        mkdirSync(dirname(settingsPath), { recursive: true });
+        writeFileSync(
+          settingsPath,
+          `${JSON.stringify(base, null, 2)}\n`,
+          'utf8',
+        );
+      }
+
       if (Object.keys(local).length === 0) {
         try {
           unlinkSync(lp);
@@ -725,26 +823,47 @@ export function createProjectScopedRoutes({
         ? Math.max(1, Math.min(10, Math.round(Number(mloops))))
         : 1;
 
-    try {
-      const result = await req.project.pm.startPipeline({
-        sourceType,
-        sourceValue: hasSource ? sourceValue : undefined,
-        prompt: hasPrompt ? prompt : undefined,
-        msize: msizeVal,
-        mloops: mloopsVal,
-        planFile: hasPlan ? planFile.trim() : undefined,
-        branch: branch || undefined,
-        template: template || undefined,
-      });
-      const { broadcast } = req.app.locals;
-      if (broadcast) broadcast('run-started', { pid: result.pid });
-      res.json({ ok: true, pid: result.pid, sourceType, prompt });
-    } catch (err) {
-      if (err.code === 'already_running') {
-        return res.status(409).json({ ok: false, error: err.message });
+    // Atomically check global cap and start pipeline under lock
+    await launchLock.withLock(async () => {
+      if (prefsDir) {
+        const globalSettings = readGlobalSettings(
+          join(prefsDir, 'settings.json'),
+        );
+        const cap =
+          globalSettings.worca?.parallel?.max_concurrent_pipelines ?? 10;
+        const totalRunning = countRunningPipelinesAcrossProjects(prefsDir);
+        if (totalRunning >= cap) {
+          res.status(409).json({
+            ok: false,
+            error: `Maximum concurrent pipelines reached (${cap}). Stop a running pipeline or increase the limit in global preferences.`,
+            code: 'max_concurrent_exceeded',
+          });
+          return;
+        }
       }
-      res.status(500).json({ ok: false, error: err.message });
-    }
+
+      try {
+        const result = await req.project.pm.startPipeline({
+          sourceType,
+          sourceValue: hasSource ? sourceValue : undefined,
+          prompt: hasPrompt ? prompt : undefined,
+          msize: msizeVal,
+          mloops: mloopsVal,
+          planFile: hasPlan ? planFile.trim() : undefined,
+          branch: branch || undefined,
+          template: template || undefined,
+        });
+        const { broadcast } = req.app.locals;
+        if (broadcast) broadcast('run-started', { pid: result.pid });
+        res.json({ ok: true, pid: result.pid, sourceType, prompt });
+      } catch (err) {
+        if (err.code === 'already_running') {
+          res.status(409).json({ ok: false, error: err.message });
+          return;
+        }
+        res.status(500).json({ ok: false, error: err.message });
+      }
+    });
   });
 
   // POST /api/projects/:projectId/runs/:id/pause
@@ -986,6 +1105,57 @@ export function createProjectScopedRoutes({
     }
   });
 
+  // POST /api/projects/:projectId/runs/:id/control — generic run control action
+  const VALID_CONTROL_ACTIONS = new Set(['approve', 'reject']);
+  router.post('/runs/:id/control', requireWorcaDir, (req, res) => {
+    const runId = req.params.id;
+    if (!validateRunId(runId)) {
+      return res.status(400).json({ ok: false, error: 'Invalid runId' });
+    }
+    const { action, source } = req.body || {};
+    if (!action || !VALID_CONTROL_ACTIONS.has(action)) {
+      return res.status(400).json({
+        ok: false,
+        error: `Invalid action. Must be one of: ${[...VALID_CONTROL_ACTIONS].join(', ')}`,
+      });
+    }
+    const { worcaDir } = req.project;
+    const statusPath = findRunStatusPath(worcaDir, runId);
+    if (!statusPath) {
+      return res
+        .status(404)
+        .json({ ok: false, error: `Run "${runId}" not found` });
+    }
+    try {
+      const st = JSON.parse(readFileSync(statusPath, 'utf8'));
+      if (st.pipeline_status !== 'paused') {
+        return res.status(409).json({
+          ok: false,
+          error: 'Run is not paused',
+          pipeline_status: st.pipeline_status,
+        });
+      }
+      const controlDir = join(worcaDir, 'runs', runId);
+      mkdirSync(controlDir, { recursive: true });
+      writeFileSync(
+        join(controlDir, 'control.json'),
+        `${JSON.stringify(
+          {
+            action,
+            requested_at: new Date().toISOString(),
+            source: source || 'ui',
+          },
+          null,
+          2,
+        )}\n`,
+        'utf8',
+      );
+      res.json({ ok: true, action, runId });
+    } catch (err) {
+      res.status(500).json({ ok: false, error: err.message });
+    }
+  });
+
   // POST /api/projects/:projectId/runs/:id/archive
   router.post('/runs/:id/archive', requireWorcaDir, (req, res) => {
     const runId = req.params.id;
@@ -1250,100 +1420,10 @@ export function createProjectScopedRoutes({
     res.json({ ok: true, runId, pid: child.pid });
   });
 
-  // POST /api/projects/:projectId/pipelines/:runId/stop — stop a worktree pipeline
-  router.post('/pipelines/:runId/stop', requireWorcaDir, (req, res) => {
-    const runId = req.params.runId;
-    if (!validateRunId(runId)) {
-      return res.status(400).json({ ok: false, error: 'Invalid runId' });
-    }
-    const { worcaDir } = req.project;
-
-    const pipelineFile = join(
-      worcaDir,
-      'multi',
-      'pipelines.d',
-      `${runId}.json`,
-    );
-    if (!existsSync(pipelineFile)) {
-      return res
-        .status(404)
-        .json({ ok: false, error: `Pipeline ${runId} not found` });
-    }
-
-    let pipeline;
-    try {
-      pipeline = JSON.parse(readFileSync(pipelineFile, 'utf8'));
-    } catch {
-      return res
-        .status(500)
-        .json({ ok: false, error: 'Failed to read pipeline registry' });
-    }
-
-    if (!pipeline.worktree_path) {
-      return res
-        .status(400)
-        .json({ ok: false, error: 'Pipeline has no worktree path' });
-    }
-
-    const worktreePm = new ProcessManager({
-      worcaDir: join(pipeline.worktree_path, '.worca'),
-    });
-    try {
-      const result = worktreePm.stopPipeline(runId);
-      res.json({ ok: true, stopped: true, runId, pid: result.pid });
-    } catch (err) {
-      if (err.code === 'not_running') {
-        return res.status(404).json({ ok: false, error: err.message });
-      }
-      res.status(500).json({ ok: false, error: err.message });
-    }
-  });
-
-  // POST /api/projects/:projectId/pipelines/:runId/pause — pause a worktree pipeline
-  router.post('/pipelines/:runId/pause', requireWorcaDir, (req, res) => {
-    const runId = req.params.runId;
-    if (!validateRunId(runId)) {
-      return res.status(400).json({ ok: false, error: 'Invalid runId' });
-    }
-    const { worcaDir } = req.project;
-
-    const pipelineFile = join(
-      worcaDir,
-      'multi',
-      'pipelines.d',
-      `${runId}.json`,
-    );
-    if (!existsSync(pipelineFile)) {
-      return res
-        .status(404)
-        .json({ ok: false, error: `Pipeline ${runId} not found` });
-    }
-
-    let pipeline;
-    try {
-      pipeline = JSON.parse(readFileSync(pipelineFile, 'utf8'));
-    } catch {
-      return res
-        .status(500)
-        .json({ ok: false, error: 'Failed to read pipeline registry' });
-    }
-
-    if (!pipeline.worktree_path) {
-      return res
-        .status(400)
-        .json({ ok: false, error: 'Pipeline has no worktree path' });
-    }
-
-    const worktreePm = new ProcessManager({
-      worcaDir: join(pipeline.worktree_path, '.worca'),
-    });
-    try {
-      const result = worktreePm.pausePipeline(runId);
-      res.json({ ok: true, ...result });
-    } catch (err) {
-      res.status(500).json({ ok: false, error: err.message });
-    }
-  });
+  // NOTE: The /pipelines/:runId/{stop,pause} routes were removed in favor of
+  // unifying on /runs/:id/{stop,pause,cancel,resume}. The ProcessManager now
+  // overlays worktree pipelines via pipelines.d/, so the same /runs/:id/*
+  // family handles both local and worktree-hosted runs.
 
   // GET /api/projects/:projectId/templates — list available pipeline templates
   router.get('/templates', (req, res) => {

package/server/run-dir-resolver.js

@@ -0,0 +1,79 @@
+/**
+ * Resolve a runId to its on-disk run directory and status file path.
+ *
+ * Worktree runs live under `<worktree_path>/.worca/runs/<runId>/`, but they
+ * are registered in the parent project's `<worcaDir>/multi/pipelines.d/<runId>.json`.
+ * Callers that only know the parent worcaDir + runId need this overlay to
+ * find the actual run files. Local (non-worktree) runs continue to live in
+ * `<worcaDir>/runs/<runId>/` or `<worcaDir>/results/<runId>/`.
+ *
+ * Resolution order:
+ *   1. `<worcaDir>/runs/<runId>/`       (local active)
+ *   2. `<worcaDir>/results/<runId>/`    (local archived)
+ *   3. `<worcaDir>/multi/pipelines.d/<runId>.json` → `<worktree_path>/.worca/runs/<runId>/`
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Resolve a runId to its on-disk run directory.
+ * @param {string} worcaDir - the parent project's .worca directory
+ * @param {string} runId
+ * @returns {string|null} absolute path to the run dir, or null if not found
+ */
+export function resolveRunDir(worcaDir, runId) {
+  if (!worcaDir || !runId) return null;
+
+  const localRunDir = join(worcaDir, 'runs', runId);
+  if (existsSync(localRunDir)) return localRunDir;
+
+  const localResultsDir = join(worcaDir, 'results', runId);
+  if (existsSync(localResultsDir)) return localResultsDir;
+
+  const overlay = readPipelineOverlay(worcaDir, runId);
+  if (overlay) {
+    const wtRunDir = join(overlay.worktree_path, '.worca', 'runs', runId);
+    if (existsSync(wtRunDir)) return wtRunDir;
+  }
+
+  return null;
+}
+
+/**
+ * Resolve a runId to its status.json path.
+ * @param {string} worcaDir
+ * @param {string} runId
+ * @returns {string|null} absolute path to status.json, or null
+ */
+export function findRunStatusPath(worcaDir, runId) {
+  const runDir = resolveRunDir(worcaDir, runId);
+  if (runDir) {
+    const sp = join(runDir, 'status.json');
+    if (existsSync(sp)) return sp;
+  }
+
+  // Legacy file format: results/<id>.json
+  const legacyPath = join(worcaDir, 'results', `${runId}.json`);
+  if (existsSync(legacyPath)) return legacyPath;
+
+  return null;
+}
+
+/**
+ * Read the worktree overlay for a runId, if registered.
+ * @param {string} worcaDir
+ * @param {string} runId
+ * @returns {{ run_id: string, worktree_path: string, pid?: number } | null}
+ */
+export function readPipelineOverlay(worcaDir, runId) {
+  const regPath = join(worcaDir, 'multi', 'pipelines.d', `${runId}.json`);
+  if (!existsSync(regPath)) return null;
+  try {
+    const data = JSON.parse(readFileSync(regPath, 'utf8'));
+    if (!data || typeof data.worktree_path !== 'string') return null;
+    return data;
+  } catch {
+    return null;
+  }
+}

package/server/settings-reader.js

@@ -1,4 +1,7 @@
-import { readMergedSettings } from './settings-merge.js';
+import { readFileSync } from 'node:fs';
+import { atomicWriteSync } from './atomic-write.js';
+import { GLOBAL_DEFAULTS } from './keys-schema.js';
+import { deepMerge, readMergedSettings } from './settings-merge.js';
 
 export function readSettings(path) {
   try {
@@ -21,3 +24,30 @@ export function readSettings(path) {
     };
   }
 }
+
+export function readGlobalSettings(globalSettingsPath) {
+  let raw = {};
+  try {
+    raw = JSON.parse(readFileSync(globalSettingsPath, 'utf-8'));
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      // First-run: file doesn't exist yet — return defaults
+    } else if (err instanceof SyntaxError) {
+      console.error(
+        `Invalid JSON in ${globalSettingsPath}: ${err.message}; falling back to defaults`,
+      );
+    } else {
+      throw err;
+    }
+  }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) raw = {};
+  raw.worca = deepMerge(GLOBAL_DEFAULTS, raw.worca || {});
+  return raw;
+}
+
+export function writeGlobalSettings(globalSettingsPath, partial) {
+  const existing = readGlobalSettings(globalSettingsPath);
+  const merged = deepMerge(existing, partial);
+  atomicWriteSync(globalSettingsPath, `${JSON.stringify(merged, null, 2)}\n`);
+  return merged;
+}