@worca/ui 0.33.0 → 0.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@worca/ui",
-  "version": "0.33.0",
+  "version": "0.35.0",
   "description": "Pipeline monitoring UI for worca-cc",
   "license": "MIT",
   "author": "Sinisha Djukic",

package/server/dispatch-defaults.js

@@ -64,8 +64,12 @@ export const DISPATCH_DEFAULTS = {
     },
   },
   subagents: {
-    always_disallowed: ['general-purpose'],
-    default_denied: [],
+    always_disallowed: [],
+    // general-purpose spawns an unconstrained full-tool Claude session, so it
+    // stays denied under the '*' wildcard — but as default_denied (not
+    // always_disallowed) a project can re-allow it per agent by naming it in
+    // per_agent_allow.
+    default_denied: ['general-purpose'],
     per_agent_allow: { _defaults: ['*'] },
   },
 };

package/server/dispatch-migration.js

@@ -60,7 +60,10 @@ function _absorbFlatDispatchKeys(dispatch) {
 // Mirror of normalize_dispatch_defaults() in src/worca/hooks/tracking.py.
 // Bumped when a new one-time normalization is added; stamped onto
 // governance.dispatch_migration_version so it runs exactly once per config.
-export const DISPATCH_MIGRATION_VERSION = 1;
+//   v1: collapse stale Explore-only subagent default; narrow worca-* skills glob.
+//   v2: move general-purpose from subagents.always_disallowed to default_denied
+//       (still denied by default, but allowable per-agent).
+export const DISPATCH_MIGRATION_VERSION = 2;
 
 // Pre-W-054 (W-038-era) shipped subagent default: every pipeline agent capped
 // to Explore-only. coordinator:[] / empty lists fall through to _defaults and
@@ -151,6 +154,36 @@ export function adoptNarrowedSkillsDenylist(skillsCfg) {
   return true;
 }
 
+/**
+ * Move general-purpose from subagents.always_disallowed to default_denied so
+ * it is allowable per-agent (still denied under the '*' wildcard). Only fires
+ * on an untouched denylist (exactly `['general-purpose']`); a customized list
+ * is left alone. Preserves existing default_denied entries. Returns true if
+ * changed. Mirror of adopt_general_purpose_allowable() in tracking.py.
+ *
+ * @param {object} subagentsCfg
+ * @returns {boolean}
+ */
+export function adoptGeneralPurposeAllowable(subagentsCfg) {
+  if (!subagentsCfg || typeof subagentsCfg !== 'object') return false;
+  const current = subagentsCfg.always_disallowed;
+  if (
+    !Array.isArray(current) ||
+    current.length !== 1 ||
+    current[0] !== 'general-purpose'
+  ) {
+    return false;
+  }
+  const denied = Array.isArray(subagentsCfg.default_denied)
+    ? subagentsCfg.default_denied
+    : [];
+  subagentsCfg.always_disallowed = [];
+  subagentsCfg.default_denied = denied.includes('general-purpose')
+    ? denied
+    : [...denied, 'general-purpose'];
+  return true;
+}
+
 /**
  * Apply one-time dispatch-default normalizations, gated by a version stamp.
  * Brings an *untouched* config up to current shipped defaults for the two
@@ -177,6 +210,11 @@ export function normalizeDispatchDefaults(governanceCfg) {
       'governance.dispatch.skills.always_disallowed: narrowed legacy "worca-*" glob to the current must-disallow set',
     );
   }
+  if (adoptGeneralPurposeAllowable(dispatch.subagents)) {
+    changes.push(
+      'governance.dispatch.subagents: moved general-purpose from always_disallowed to default_denied (now allowable per-agent)',
+    );
+  }
   governanceCfg.dispatch_migration_version = DISPATCH_MIGRATION_VERSION;
   return changes;
 }

package/server/project-routes.js

@@ -1587,9 +1587,9 @@ export function createProjectScopedRoutes({
   router.get('/templates', (req, res) => {
     const root = req.project.projectRoot;
     const tiers = [
-      { tier: 'worca', dir: join(root, '.claude', 'worca', 'templates') },
-      { tier: 'project', dir: join(root, '.claude', 'templates') },
       { tier: 'user', dir: templatesDir() },
+      { tier: 'project', dir: join(root, '.claude', 'templates') },
+      { tier: 'worca', dir: join(root, '.claude', 'worca', 'templates') },
     ];
 
     const templates = [];

package/server/safe-watch.js

@@ -0,0 +1,11 @@
+import { watch } from 'node:fs';
+
+export function safeWatch(...args) {
+  const w = watch(...args);
+  w.on('error', (err) => {
+    if (err && err.code !== 'EPERM' && err.code !== 'ENOENT') {
+      console.error('[safeWatch] watcher error:', err);
+    }
+  });
+  return w;
+}

package/server/watcher.js

@@ -1,11 +1,13 @@
 import { createHash } from 'node:crypto';
-import { existsSync, readdirSync, readFileSync, watch } from 'node:fs';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import {
   assignEventsToIterations,
   readDispatchEventsFromJsonl,
 } from './dispatch-events-aggregator.js';
+import { readPipelineOverlay } from './run-dir-resolver.js';
+import { safeWatch } from './safe-watch.js';
 
 /**
  * Enrich a status object with dispatch events read from events.jsonl in the
@@ -45,7 +47,137 @@ function isTerminal(status) {
   );
 }
 
+const _discoverRunsCache = new Map(); // worcaDir → { ts, runs }
+// TTL defaults to 0 under vitest (NODE_ENV=test) so the cache is a no-op in
+// tests — they build fixture dirs from Date.now() and a shared path could
+// otherwise serve a stale cached scan across tests. Production uses 1500ms;
+// _setDiscoverRunsTtlForTest lets the dedicated cache test exercise real TTL.
+let _discoverRunsTtlMs = process.env.NODE_ENV === 'test' ? 0 : 1500;
+
+/** Test hook: override the discoverRuns cache TTL in ms. */
+export function _setDiscoverRunsTtlForTest(ms) {
+  _discoverRunsTtlMs = ms;
+}
+
+/**
+ * Cached wrapper around the run-discovery scan. The scan reads + JSON-parses
+ * every run's status.json across runs/, results/, and pipelines.d/ worktree
+ * overlays — hundreds of ms on a large project. Whole-list callers (list-runs,
+ * REST /runs) hit this; a short TTL collapses repeated calls in a burst into a
+ * single scan. Per-run handlers use findRun() instead. Live status changes
+ * still reach clients via the statusWatcher broadcast, so TTL-window staleness
+ * here is invisible in the UI.
+ */
 export function discoverRuns(worcaDir) {
+  const cached = _discoverRunsCache.get(worcaDir);
+  if (cached && Date.now() - cached.ts < _discoverRunsTtlMs) {
+    return cached.runs;
+  }
+  const runs = _discoverRunsUncached(worcaDir);
+  _discoverRunsCache.set(worcaDir, { ts: Date.now(), runs });
+  return runs;
+}
+
+/** Clear the discoverRuns TTL cache (tests, or explicit invalidation). */
+export function clearDiscoverRunsCache() {
+  _discoverRunsCache.clear();
+}
+
+/**
+ * Resolve a SINGLE run by id without scanning every run on disk — the O(1)
+ * counterpart to discoverRuns().find(r => r.id === runId), for hot WS handlers
+ * (subscribe-run, get-agent-prompt) that need exactly one run. Mirrors
+ * discoverRuns' per-source shaping: dispatch-event enrichment for runs/ and
+ * worktree sources (not results/), plus the worktree registry fields. The
+ * findRun-vs-discoverRuns parity test keeps the two aligned.
+ *
+ * Falls back to a (TTL-cached) discoverRuns scan for legacy layouts where the
+ * on-disk name doesn't equal the computed id (flat `.worca/status.json`, hashed
+ * legacy ids), so it never resolves fewer runs than discoverRuns().find().
+ *
+ * @returns {object|null} a run record shaped like a discoverRuns entry, or null
+ */
+export function findRun(worcaDir, runId) {
+  if (!worcaDir || !runId) return null;
+
+  // 1. Local active: runs/<id>/status.json (enriched)
+  const localRunDir = join(worcaDir, 'runs', runId);
+  if (existsSync(join(localRunDir, 'status.json'))) {
+    return _shapeRunFromFile(join(localRunDir, 'status.json'), {
+      enrich: true,
+      runDir: localRunDir,
+    });
+  }
+
+  // 2. Local archived dir: results/<id>/status.json (not enriched)
+  const resultsDirStatus = join(worcaDir, 'results', runId, 'status.json');
+  if (existsSync(resultsDirStatus)) {
+    return _shapeRunFromFile(resultsDirStatus, { enrich: false });
+  }
+
+  // 2b. Legacy archived file: results/<id>.json (not enriched)
+  const legacyFile = join(worcaDir, 'results', `${runId}.json`);
+  if (existsSync(legacyFile)) {
+    return _shapeRunFromFile(legacyFile, {
+      enrich: false,
+      requireStartedAt: true,
+    });
+  }
+
+  // 3. Worktree overlay: pipelines.d/<id>.json → <worktree>/.worca/runs/<id>
+  const reg = readPipelineOverlay(worcaDir, runId);
+  if (reg?.worktree_path) {
+    const wtRunDir = join(reg.worktree_path, '.worca', 'runs', runId);
+    if (existsSync(join(wtRunDir, 'status.json'))) {
+      return _shapeRunFromFile(join(wtRunDir, 'status.json'), {
+        enrich: true,
+        runDir: wtRunDir,
+        worktreeReg: reg,
+      });
+    }
+  }
+
+  // Fallback for legacy layouts where the on-disk name != the computed id
+  // (flat .worca/status.json, hashed legacy ids). Rare — pay one (TTL-cached)
+  // full scan rather than regress correctness vs discoverRuns().find().
+  return discoverRuns(worcaDir).find((r) => r.id === runId) || null;
+}
+
+function _shapeRunFromFile(
+  statusPath,
+  {
+    enrich = false,
+    runDir = null,
+    worktreeReg = null,
+    requireStartedAt = false,
+  } = {},
+) {
+  try {
+    let status = JSON.parse(readFileSync(statusPath, 'utf8'));
+    if (requireStartedAt && !status.started_at) return null;
+    if (enrich && runDir) status = enrichWithDispatchEvents(status, runDir);
+    const id = createRunId(status);
+    const active = !isTerminal(status) && status.pipeline_status === 'running';
+    const base = { id, active, ...status };
+    if (worktreeReg) {
+      return {
+        ...base,
+        worktree_worca_dir: join(worktreeReg.worktree_path, '.worca'),
+        is_worktree_run: true,
+        head_branch: worktreeReg.branch || null,
+        fleet_id: worktreeReg.fleet_id || null,
+        workspace_id: worktreeReg.workspace_id || null,
+        group_type: worktreeReg.group_type || null,
+        target_branch: worktreeReg.target_branch || null,
+      };
+    }
+    return base;
+  } catch {
+    return null;
+  }
+}
+
+function _discoverRunsUncached(worcaDir) {
   const runs = [];
   const seenIds = new Set();
 
@@ -366,7 +498,7 @@ export function watchEvents(runDir, callback) {
   function startFileWatcher() {
     if (closed || fileWatcher) return;
     try {
-      fileWatcher = watch(eventsPath, (eventType) => {
+      fileWatcher = safeWatch(eventsPath, (eventType) => {
         if (eventType === 'change') {
           processNewContent();
         } else if (eventType === 'rename') {
@@ -405,7 +537,7 @@ export function watchEvents(runDir, callback) {
   // Watch the run directory so we detect events.jsonl being created
   if (existsSync(runDir)) {
     try {
-      dirWatcher = watch(
+      dirWatcher = safeWatch(
         runDir,
         { recursive: false },
         (_eventType, filename) => {

package/server/ws-beads-watcher.js

@@ -4,13 +4,14 @@
  * because fs.watch on macOS misses SQLite WAL writes done via mmap.
  */
 
-import { existsSync, statSync, unwatchFile, watch, watchFile } from 'node:fs';
+import { existsSync, statSync, unwatchFile, watchFile } from 'node:fs';
 import { join, resolve } from 'node:path';
 import {
   countIssuesByRunLabel,
   enrichIssuesWithDeps,
   listIssuesShallow,
 } from './beads-reader.js';
+import { safeWatch } from './safe-watch.js';
 
 const BEADS_DEBOUNCE_MS = 500;
 const BEADS_POLL_MS = 2000;
@@ -132,7 +133,7 @@ export function createBeadsWatcher({ worcaDir, broadcaster, projectId }) {
   if (existsSync(beadsDir)) {
     // fs.watch for directory-level events (checkpoint writes to main db)
     try {
-      fsWatcher = watch(beadsDir, (_event, filename) => {
+      fsWatcher = safeWatch(beadsDir, (_event, filename) => {
         if (filename?.startsWith('beads.db')) scheduleBeadsRefresh();
       });
     } catch {

package/server/ws-fleet-manifest-watcher.js

@@ -3,10 +3,11 @@
  * Emits fleet-update WS events when a fleet manifest is written (§13.5).
  */
 
-import { existsSync, readFileSync, watch } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { effectiveFleetStatus } from './fleet-routes.js';
 import { fleetRunsDir as resolveFleetRunsDir } from './paths.js';
+import { safeWatch } from './safe-watch.js';
 
 const FLEET_DEBOUNCE_MS = 200;
 
@@ -100,7 +101,7 @@ export function createFleetManifestWatcher({
 
   try {
     if (existsSync(fleetRunsDir)) {
-      fsWatcher = watch(
+      fsWatcher = safeWatch(
         fleetRunsDir,
         { persistent: false },
         (_event, filename) => {

package/server/ws-log-watcher.js

@@ -3,7 +3,7 @@
  * Owns logWatchers map and logLineCounts tracking.
  */
 
-import { existsSync, readdirSync, statSync, watch } from 'node:fs';
+import { existsSync, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import {
   fileByteLength,
@@ -13,6 +13,7 @@ import {
   readNewLines,
   resolveLogPath,
 } from './log-tailer.js';
+import { safeWatch } from './safe-watch.js';
 
 /**
  * @param {{
@@ -69,7 +70,7 @@ export function createLogWatcher({
       if (!existsSync(filePath)) return;
       logByteOffsets.set(key, fileByteLength(filePath));
       const watcherRunId = explicitRunId || currentActiveRunId();
-      const watcher = watch(filePath, (eventType) => {
+      const watcher = safeWatch(filePath, (eventType) => {
         if (eventType === 'change') {
           try {
             const prevOffset = logByteOffsets.get(key) || 0;
@@ -109,7 +110,7 @@ export function createLogWatcher({
     const dirKey = _watcherKey(explicitRunId, stage, null, '__dir');
     if (logWatchers.has(dirKey)) return;
     try {
-      const dirWatcher = watch(stageDir, (_eventType, filename) => {
+      const dirWatcher = safeWatch(stageDir, (_eventType, filename) => {
         if (filename && /^iter-\d+\.log$/.test(filename)) {
           const iterNum = parseInt(filename.match(/\d+/)[0], 10);
           const iterPath = join(stageDir, filename);
@@ -167,7 +168,7 @@ export function createLogWatcher({
     if (logWatchers.has(dirKey)) return;
     if (!existsSync(logsDir)) return;
     try {
-      const dirWatcher = watch(logsDir, (_eventType, filename) => {
+      const dirWatcher = safeWatch(logsDir, (_eventType, filename) => {
         if (!filename) return;
         if (filename.endsWith('.log')) {
           const stage = filename.replace('.log', '');

package/server/ws-message-router.js

@@ -33,7 +33,7 @@ import {
 } from './process-manager.js';
 import { resolveRunDir } from './run-dir-resolver.js';
 import { readSettings } from './settings-reader.js';
-import { discoverRuns } from './watcher.js';
+import { discoverRuns, findRun } from './watcher.js';
 import { resolveBeadsCounts } from './ws-beads-watcher.js';
 
 /**
@@ -165,8 +165,7 @@ export function createMessageRouter({
       }
       _adoptProjectFromPayload(ws, req.payload);
       const proj = resolveProject(ws, req.payload);
-      const runs = discoverRuns(proj.worcaDir);
-      const run = runs.find((r) => r.id === runId);
+      const run = findRun(proj.worcaDir, runId);
       if (!run) {
         ws.send(
           JSON.stringify(makeError(req, 'NOT_FOUND', `Run ${runId} not found`)),
@@ -321,8 +320,7 @@ export function createMessageRouter({
       }
       const s = clientManager.ensureSubs(ws);
       s.runId = runId;
-      const runs = discoverRuns(proj.worcaDir);
-      const run = runs.find((r) => r.id === runId);
+      const run = findRun(proj.worcaDir, runId);
       if (run) {
         if (
           run.pipeline_status !== undefined &&

package/server/ws-modular.js

@@ -6,11 +6,12 @@
  * Supports dynamic project add/remove via fs.watch on projects.d/.
  */
 
-import { existsSync, watch } from 'node:fs';
+import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { WebSocketServer } from 'ws';
 import { fleetRunsDir, workspaceRunsDir } from './paths.js';
 import { readProjects, synthesizeDefaultProject } from './project-registry.js';
+import { safeWatch } from './safe-watch.js';
 import { TIER_FULL, TIER_POLLING, WatcherSet } from './watcher-set.js';
 import { readProjectWorcaVersion } from './worca-setup.js';
 import { peekBeadsCounts } from './ws-beads-watcher.js';
@@ -40,6 +41,10 @@ export function attachWsServer(httpServer, config) {
   } = config;
   const wss = new WebSocketServer({ server: httpServer, path: '/ws' });
 
+  // WSS created with an external server does not auto-close when the server
+  // closes — explicitly bridge the lifecycle so watchers are torn down.
+  httpServer.on('close', () => wss.close());
+
   // 1. Client manager — owns subs WeakMap and heartbeat
   const clientManager = createClientManager({ wss });
 
@@ -115,7 +120,7 @@ export function attachWsServer(httpServer, config) {
     const projectsDir = join(prefsDir, 'projects.d');
     try {
       if (existsSync(projectsDir)) {
-        dirWatcher = watch(projectsDir, { persistent: false }, () => {
+        dirWatcher = safeWatch(projectsDir, { persistent: false }, () => {
           if (debounceTimer) clearTimeout(debounceTimer);
           debounceTimer = setTimeout(() => {
             debounceTimer = null;

package/server/ws-status-watcher.js

@@ -3,14 +3,9 @@
  * Owns refresh scheduling, lastPipelineStatus tracking, and the status/runsDirWatcher FSWatchers.
  */
 
-import {
-  existsSync,
-  mkdirSync,
-  readdirSync,
-  readFileSync,
-  watch,
-} from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { safeWatch } from './safe-watch.js';
 import { readSettings } from './settings-reader.js';
 import { discoverRunsAsync } from './watcher.js';
 
@@ -225,7 +220,7 @@ export function createStatusWatcher({
       const wtRunsDir = join(reg.worktree_path, '.worca', 'runs');
       if (!existsSync(wtRunsDir)) continue;
       try {
-        const w = watch(
+        const w = safeWatch(
           wtRunsDir,
           { recursive: true },
           (_eventType, filename) => {
@@ -322,7 +317,7 @@ export function createStatusWatcher({
           // rename-over) replace the inode.  After one 'rename' event the
           // watcher goes dead because it tracked the old inode.  We
           // re-establish the watcher on the new file after a short delay.
-          statusWatcher = watch(statusFile, (eventType) => {
+          statusWatcher = safeWatch(statusFile, (eventType) => {
             scheduleRefresh();
             if (eventType === 'rename') {
               // File replaced (atomic write) — re-watch the new inode
@@ -338,7 +333,7 @@ export function createStatusWatcher({
         } else if (existsSync(runDir)) {
           // status.json doesn't exist yet — watch the directory for its creation,
           // then switch to watching the file once it appears.
-          statusWatcher = watch(
+          statusWatcher = safeWatch(
             runDir,
             { recursive: false },
             (_eventType, filename) => {
@@ -373,7 +368,7 @@ export function createStatusWatcher({
   // Watch worcaDir for legacy status.json changes
   try {
     if (existsSync(worcaDir)) {
-      activeRunWatcher = watch(
+      activeRunWatcher = safeWatch(
         worcaDir,
         { recursive: false },
         (_eventType, filename) => {
@@ -395,7 +390,7 @@ export function createStatusWatcher({
   const runsDir = join(worcaDir, 'runs');
   try {
     if (existsSync(runsDir)) {
-      runsDirWatcher = watch(
+      runsDirWatcher = safeWatch(
         runsDir,
         { recursive: true },
         (_eventType, filename) => {
@@ -414,7 +409,7 @@ export function createStatusWatcher({
   const pipelinesDirPath = join(worcaDir, 'multi', 'pipelines.d');
   try {
     mkdirSync(pipelinesDirPath, { recursive: true });
-    pipelinesDirWatcher = watch(
+    pipelinesDirWatcher = safeWatch(
       pipelinesDirPath,
       { recursive: false },
       (_eventType, filename) => {

package/server/ws-workspace-manifest-watcher.js

@@ -6,9 +6,10 @@
  * Separate from fleet-update per W-040 §13.5 — never multiplexed.
  */
 
-import { existsSync, readFileSync, watch } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { workspaceRunsDir as resolveWorkspaceRunsDir } from './paths.js';
+import { safeWatch } from './safe-watch.js';
 
 const WS_DEBOUNCE_MS = 200;
 
@@ -102,7 +103,7 @@ export function createWorkspaceManifestWatcher({
 
   try {
     if (existsSync(workspaceRunsDir)) {
-      fsWatcher = watch(
+      fsWatcher = safeWatch(
         workspaceRunsDir,
         { persistent: false },
         (_event, filename) => {