@worca/ui 0.22.0 → 0.23.0

package/server/integrations/commands/fleet.js

@@ -0,0 +1,266 @@
+/**
+ * Fleet-scoped chat commands.
+ *
+ *   /fleets                      list active fleets (running + paused)
+ *   /fleet [id|last]             show one fleet's status
+ *   /fleet-children <id|last>    per-child status table
+ *   /fleet-halt <id>             graceful halt (in-flight finish naturally)
+ *   /fleet-stop <id> [--force]   hard stop (SIGTERM + control file), with confirmation
+ *   /fleet-pause <id>            pause every in-flight child
+ *   /fleet-resume <id>           resume paused/interrupted children, re-dispatch failed
+ *
+ * Authz: every handler runs *after* the inbound allowlist gate in
+ * index.js — same gate that already guards /pause, /resume, /stop.
+ *
+ * Destructive actions (/fleet-stop) require a confirmation token written
+ * into chat_context with a 60s expiry. The token mechanism is local to
+ * this module so we don't bloat chat_context.js's public API for what is
+ * really a per-command UX concern.
+ *
+ * @module commands/fleet
+ */
+
+import { statusEmoji } from './global.js';
+
+const CONFIRM_TTL_MS = 60_000;
+
+/** Pick the most recent fleet from a list (created_at desc). */
+function pickLatest(fleets) {
+  if (!fleets || fleets.length === 0) return null;
+  return [...fleets].sort((a, b) => {
+    const at = a.created_at || '';
+    const bt = b.created_at || '';
+    return bt.localeCompare(at);
+  })[0];
+}
+
+async function fetchFleets(restClient) {
+  const resp = await restClient.get('/api/fleet-runs');
+  const data = resp.data;
+  if (!data || data.ok === false) return [];
+  return Array.isArray(data.fleets) ? data.fleets : [];
+}
+
+async function fetchFleetById(restClient, id) {
+  const resp = await restClient.get(
+    `/api/fleet-runs/${encodeURIComponent(id)}`,
+  );
+  const data = resp.data;
+  if (!data || data.ok === false) return null;
+  return data.fleet ?? null;
+}
+
+/**
+ * Resolve "last" / short-suffix / full-id into a fleet manifest object.
+ * Returns { fleet, disambig } — exactly one of them populated.
+ */
+async function resolveFleet(restClient, idArg, command) {
+  if (!idArg || idArg === 'last') {
+    const all = await fetchFleets(restClient);
+    const latest = pickLatest(all);
+    if (!latest) return { disambig: 'No fleets found.' };
+    return { fleet: latest };
+  }
+  if (idArg.startsWith('f_')) {
+    const fleet = await fetchFleetById(restClient, idArg);
+    if (!fleet) return { disambig: `Fleet \`${idArg}\` not found.` };
+    return { fleet };
+  }
+  // Short suffix match — `4318dbf9` matches `f_..._4318dbf9`.
+  const all = await fetchFleets(restClient);
+  const matches = all.filter((f) => f.fleet_id?.endsWith(idArg));
+  if (matches.length === 0) {
+    return { disambig: `No fleet matches \`${idArg}\`.` };
+  }
+  if (matches.length > 1) {
+    const lines = matches.map((f) => `   • \`${f.fleet_id}\` — ${f.status}`);
+    return {
+      disambig:
+        `Multiple fleets match \`${idArg}\`:\n${lines.join('\n')}\n\n` +
+        `Usage: /${command} <fleet_id>`,
+    };
+  }
+  return { fleet: matches[0] };
+}
+
+function fmtFleetSummary(fleet) {
+  const id = fleet.fleet_id;
+  const title = fleet.work_request?.title || '(no title)';
+  const status = fleet.status || 'unknown';
+  const reason = fleet.halt_reason ? ` (${fleet.halt_reason})` : '';
+  const childCount = fleet.children_count ?? fleet.children?.length ?? 0;
+  const completed = (fleet.children || []).filter(
+    (c) => c.status === 'completed',
+  ).length;
+  const failed = (fleet.children || []).filter(
+    (c) => c.status === 'failed' || c.status === 'setup_failed',
+  ).length;
+  const parts = [`${statusEmoji(status)} **Fleet:** \`${id}\``];
+  parts.push(`   **Title:** ${title}`);
+  parts.push(`   **Status:** ${status}${reason}`);
+  parts.push(
+    `   **Children:** ${completed}/${childCount} completed${failed ? `, ${failed} failed` : ''}`,
+  );
+  if (fleet.cost_usd != null) {
+    parts.push(`   **Cost:** $${Number(fleet.cost_usd).toFixed(2)}`);
+  }
+  return parts.join('\n');
+}
+
+function fmtChildrenTable(fleet) {
+  const children = fleet.children || [];
+  if (children.length === 0) return '   (no children dispatched yet)';
+  return children
+    .map((c) => {
+      const project =
+        (c.project_path || '').split('/').filter(Boolean).pop() || '(?)';
+      const st = c.status || 'unknown';
+      const rid = c.run_id ? ` \`${c.run_id}\`` : '';
+      return `   ${statusEmoji(st)} **${project}** — ${st}${rid}`;
+    })
+    .join('\n');
+}
+
+/**
+ * Creates handlers for the /fleet… commands.
+ *
+ * The chatContext is used for /fleet-stop confirmation tokens — we store
+ * a `pending_fleet_stop = { fleet_id, expires_at }` shape on the chat key
+ * and clear it after the confirming message comes in.
+ *
+ * @param {{ chatContext, restClient }} deps
+ */
+export function createFleetHandlers({ chatContext, restClient }) {
+  async function fleets() {
+    const all = await fetchFleets(restClient);
+    const active = all.filter((f) => {
+      const s = f.status;
+      return s === 'running' || s === 'paused' || s === 'resuming';
+    });
+    if (active.length === 0) return 'No active fleets.';
+    const lines = active.map((f) => {
+      const childCount = f.children_count ?? f.children?.length ?? 0;
+      const title = f.work_request?.title || '(no title)';
+      const reason = f.halt_reason ? ` (${f.halt_reason})` : '';
+      return [
+        `${statusEmoji(f.status)} **Fleet:** \`${f.fleet_id}\``,
+        `   **Title:** ${title}`,
+        `   **Status:** ${f.status}${reason} | **Children:** ${childCount}`,
+      ].join('\n');
+    });
+    return `Active fleets:\n\n${lines.join('\n')}`;
+  }
+
+  async function fleet(_chatKey, args) {
+    const resolved = await resolveFleet(restClient, args[0], 'fleet');
+    if (resolved.disambig) return resolved.disambig;
+    return fmtFleetSummary(resolved.fleet);
+  }
+
+  async function fleetChildren(_chatKey, args) {
+    const resolved = await resolveFleet(restClient, args[0], 'fleet-children');
+    if (resolved.disambig) return resolved.disambig;
+    const f = resolved.fleet;
+    return `Children of \`${f.fleet_id}\`:\n\n` + fmtChildrenTable(f);
+  }
+
+  async function fleetHalt(_chatKey, args) {
+    const resolved = await resolveFleet(restClient, args[0], 'fleet-halt');
+    if (resolved.disambig) return resolved.disambig;
+    const id = resolved.fleet.fleet_id;
+    const resp = await restClient.delete(
+      `/api/fleet-runs/${encodeURIComponent(id)}`,
+    );
+    if (!resp.data || resp.data.ok === false) {
+      return `Failed to halt fleet \`${id}\` (${resp.status}).`;
+    }
+    return `\u{1F7E1} Halted fleet \`${id}\`.\nIn-flight children will finish naturally.`;
+  }
+
+  async function fleetStop(chatKey, args) {
+    const isForce = args.includes('--force') || args.includes('YES');
+    const cleanArgs = args.filter((a) => a !== '--force' && a !== 'YES');
+    const resolved = await resolveFleet(restClient, cleanArgs[0], 'fleet-stop');
+    if (resolved.disambig) return resolved.disambig;
+    const id = resolved.fleet.fleet_id;
+
+    const ctx = chatContext.get(chatKey) || {};
+    const pending = ctx.pending_fleet_stop;
+
+    if (!isForce) {
+      // Issue / refresh a confirmation token.
+      chatContext.set(chatKey, {
+        pending_fleet_stop: {
+          fleet_id: id,
+          expires_at: new Date(Date.now() + CONFIRM_TTL_MS).toISOString(),
+        },
+      });
+      const child_count =
+        resolved.fleet.children_count ?? (resolved.fleet.children || []).length;
+      return (
+        `⚠ \`/fleet-stop\` will SIGTERM every in-flight child of fleet \`${id}\` (${child_count} children).\n` +
+        `Confirm with \`/fleet-stop ${id} YES\` within 60s, or pass \`--force\`.`
+      );
+    }
+
+    // --force or YES path. Either matches a fresh confirmation token, or
+    // the caller is bypassing the gate entirely with --force.
+    if (
+      args.includes('YES') &&
+      (!pending ||
+        pending.fleet_id !== id ||
+        new Date(pending.expires_at).getTime() < Date.now())
+    ) {
+      return `Confirmation expired or never issued for fleet \`${id}\`. Re-run \`/fleet-stop ${id}\` to get a fresh token.`;
+    }
+
+    chatContext.set(chatKey, { pending_fleet_stop: null });
+    const resp = await restClient.post(
+      `/api/fleet-runs/${encodeURIComponent(id)}/stop`,
+    );
+    if (!resp.data || resp.data.ok === false) {
+      return `Failed to stop fleet \`${id}\` (${resp.status}).`;
+    }
+    const count = resp.data.stopped_count ?? '?';
+    return `\u{1F534} Stopped fleet \`${id}\`. SIGTERM sent to ${count} child(ren).`;
+  }
+
+  async function fleetPause(_chatKey, args) {
+    const resolved = await resolveFleet(restClient, args[0], 'fleet-pause');
+    if (resolved.disambig) return resolved.disambig;
+    const id = resolved.fleet.fleet_id;
+    const resp = await restClient.post(
+      `/api/fleet-runs/${encodeURIComponent(id)}/pause`,
+    );
+    if (!resp.data || resp.data.ok === false) {
+      return `Failed to pause fleet \`${id}\` (${resp.status}).`;
+    }
+    const count = resp.data.paused_count ?? '?';
+    return `\u{1F7E1} Paused fleet \`${id}\`. ${count} child(ren) will pause at their next iteration boundary.`;
+  }
+
+  async function fleetResume(_chatKey, args) {
+    const resolved = await resolveFleet(restClient, args[0], 'fleet-resume');
+    if (resolved.disambig) return resolved.disambig;
+    const id = resolved.fleet.fleet_id;
+    const resp = await restClient.post(
+      `/api/fleet-runs/${encodeURIComponent(id)}/resume`,
+    );
+    if (!resp.data || resp.data.ok === false) {
+      return `Failed to resume fleet \`${id}\` (${resp.status}).`;
+    }
+    const continued = resp.data.continued_count ?? 0;
+    const redispatched = resp.data.redispatched_count ?? 0;
+    return `\u{1F7E2} Resumed fleet \`${id}\`. ${continued} continued in-place, ${redispatched} re-dispatched.`;
+  }
+
+  return {
+    fleets,
+    fleet,
+    'fleet-children': fleetChildren,
+    'fleet-halt': fleetHalt,
+    'fleet-stop': fleetStop,
+    'fleet-pause': fleetPause,
+    'fleet-resume': fleetResume,
+  };
+}

package/server/integrations/commands/global.js

@@ -115,6 +115,15 @@ const HELP_TEXT = `/start \u2014 show your chat ID
 /resume [run_id] \u2014 resume paused run
 /stop [run_id] \u2014 stop run
 
+Fleet commands (cross-project):
+/fleets \u2014 list active fleets
+/fleet [id|last] \u2014 fleet status
+/fleet-children <id|last> \u2014 per-child status
+/fleet-halt <id> \u2014 graceful halt (in-flight finish naturally)
+/fleet-stop <id> [--force] \u2014 SIGTERM every in-flight child (confirms first)
+/fleet-pause <id> \u2014 pause every in-flight child
+/fleet-resume <id> \u2014 resume paused/interrupted, re-dispatch failed
+
 Commands with [run_id] auto-resolve to the active run if omitted.
 Use \`*suffix\` to match by ending, e.g. /status \`*2db5\`
 Project commands require /use first.`;

package/server/integrations/commands/parser.js

@@ -1,6 +1,9 @@
 const MENTION_RE = /^@\S+$/i;
 
-const COMMAND_RE = /^\/([a-z_]+)(?:@\S+)?$/i;
+// Allow `-` so namespaced commands like /fleet-halt and /fleet-resume parse.
+// Hyphens must appear inside the name, not lead or trail. Backwards-compatible
+// — every existing underscore-only command still matches.
+const COMMAND_RE = /^\/([a-z_][a-z0-9_-]*)(?:@\S+)?$/i;
 
 /**
  * Parses a chat message into a command name and argument list.

package/server/integrations/index.js

@@ -12,6 +12,7 @@ import { createWebhookOutAdapter } from './adapters/webhook_out.js';
 import { createAllowlistGuard } from './allowlist.js';
 import { createChatContext } from './chat_context.js';
 import { createControlHandlers } from './commands/control.js';
+import { createFleetHandlers } from './commands/fleet.js';
 import { createGlobalHandlers } from './commands/global.js';
 import { parseCommand } from './commands/parser.js';
 import { createProjectHandlers } from './commands/project.js';
@@ -65,10 +66,12 @@ export function createIntegrations({
   });
   const projectHandlers = createProjectHandlers({ chatContext, restClient });
   const controlHandlers = createControlHandlers({ chatContext, restClient });
+  const fleetHandlers = createFleetHandlers({ chatContext, restClient });
   const allHandlers = {
     ...globalHandlers,
     ...projectHandlers,
     ...controlHandlers,
+    ...fleetHandlers,
   };
 
   // Mutable adapter registry — keyed by adapter name

package/server/integrations/renderers.js

@@ -154,6 +154,90 @@ function renderCostBudgetWarning(envelope) {
   return mdMsg(parts.join('\n'), 'warning');
 }
 
+// ---------------------------------------------------------------------------
+// Fleet event renderers
+// ---------------------------------------------------------------------------
+// Mirror the run-event renderers' shape: short title line + indented meta
+// rows. fleet_id replaces run_id as the primary key; envelopes are
+// fleet-shaped (top-level fleet_id, no `pipeline` wrapper). See
+// src/worca/events/fleet_emitter.py for the envelope schema.
+
+function fleetId(envelope) {
+  return envelope.fleet_id ?? 'fleet';
+}
+
+function projectBasename(p) {
+  if (!p) return '';
+  const parts = p.split('/').filter(Boolean);
+  return parts[parts.length - 1] || p;
+}
+
+function renderFleetLaunched(envelope) {
+  const p = envelope.payload ?? {};
+  const projects = Array.isArray(p.projects) ? p.projects : [];
+  const projectsLabel = projects.length
+    ? projects.slice(0, 5).map(projectBasename).join(', ') +
+      (projects.length > 5 ? `, +${projects.length - 5} more` : '')
+    : '(none)';
+  const parts = [`\u{1F680} **Fleet launched:** \`${fleetId(envelope)}\``];
+  parts.push(`   **Projects:** ${projects.length} — ${projectsLabel}`);
+  if (p.plan_mode && p.plan_mode !== 'none') {
+    parts.push(`   **Plan mode:** ${p.plan_mode}`);
+  }
+  if (p.guide_attached) parts.push('   **Guide:** attached');
+  if (p.base_branch) parts.push(`   **Base:** ${p.base_branch}`);
+  return mdMsg(parts.join('\n'), 'info');
+}
+
+function renderFleetHalted(envelope) {
+  const p = envelope.payload ?? {};
+  const reason = p.halt_reason || 'unknown';
+  // Severity matches the reason: circuit_breaker is an error, user/stopped is
+  // a warning. Keeps Slack/Discord colour coding consistent with the per-run
+  // pipeline.run.interrupted vs pipeline.circuit_breaker.tripped split.
+  const sev = reason === 'circuit_breaker' ? 'error' : 'warning';
+  const parts = [`\u{1F6D1} **Fleet halted:** \`${fleetId(envelope)}\``];
+  parts.push(`   **Reason:** ${reason}`);
+  if (p.in_flight_count != null) {
+    parts.push(`   **In-flight at halt:** ${p.in_flight_count}`);
+  }
+  if (p.pending_count != null && p.pending_count > 0) {
+    parts.push(`   **Pending (not dispatched):** ${p.pending_count}`);
+  }
+  return mdMsg(parts.join('\n'), sev);
+}
+
+function renderFleetCompleted(envelope) {
+  const p = envelope.payload ?? {};
+  const parts = [`✅ **Fleet completed:** \`${fleetId(envelope)}\``];
+  if (p.child_count != null) {
+    parts.push(
+      `   **Children:** ${p.completed_count ?? p.child_count}/${p.child_count} completed`,
+    );
+  }
+  if (p.duration_ms != null) {
+    parts.push(`   **Duration:** ${fmtMs(p.duration_ms)}`);
+  }
+  return mdMsg(parts.join('\n'), 'success');
+}
+
+function renderFleetFailed(envelope) {
+  const p = envelope.payload ?? {};
+  const parts = [`❌ **Fleet failed:** \`${fleetId(envelope)}\``];
+  if (p.child_count != null) {
+    const failed = p.failed_count ?? 0;
+    const interrupted = p.interrupted_count ?? 0;
+    const completed = p.completed_count ?? 0;
+    parts.push(
+      `   **Children:** ${completed}/${p.child_count} completed, ${failed} failed, ${interrupted} interrupted`,
+    );
+  }
+  if (p.duration_ms != null) {
+    parts.push(`   **Duration:** ${fmtMs(p.duration_ms)}`);
+  }
+  return mdMsg(parts.join('\n'), 'error');
+}
+
 // ---------------------------------------------------------------------------
 // Registry
 // ---------------------------------------------------------------------------
@@ -173,6 +257,20 @@ const EVENT_RENDERERS = {
   'pipeline.git.pr_merged': renderGitPrMerged,
   'pipeline.circuit_breaker.tripped': renderCbTripped,
   'pipeline.cost.budget_warning': renderCostBudgetWarning,
+  // fleet.launched is intentionally NOT in this map by default — projects
+  // that launch many fleets per day would find it noisy. Opt-in callers
+  // can register it themselves via renderEvent's renderer override (or
+  // by extending TIER1_EVENTS in a future per-project config).
+  'fleet.halted': renderFleetHalted,
+  'fleet.completed': renderFleetCompleted,
+  'fleet.failed': renderFleetFailed,
+};
+
+// fleet.launched ships as an opt-in renderer rather than a Tier-1 default —
+// see comment above. Callers that want it can pull it from this export and
+// register it in their own pipeline.
+export const OPT_IN_RENDERERS = {
+  'fleet.launched': renderFleetLaunched,
 };
 
 export const TIER1_EVENTS = Object.keys(EVENT_RENDERERS);

package/server/integrations/rest_client.js

@@ -13,5 +13,12 @@ export function createRestClient({ host, port }) {
       });
       return { status: r.status, data: r.ok ? await r.json() : null };
     },
+    // DELETE used by /fleet-halt (DELETE /api/fleet-runs/:id) — added when
+    // chat fleet commands landed. Mirrors the get/post pair: no body, returns
+    // parsed JSON on 2xx, null on error status.
+    async delete(path) {
+      const r = await fetch(`${base}${path}`, { method: 'DELETE' });
+      return { status: r.status, data: r.ok ? await r.json() : null };
+    },
   };
 }

package/server/worktrees-routes.js

@@ -262,6 +262,17 @@ function _patchRegistry(worcaDir, runId, patch) {
   }
 }
 
+function _isPidAlive(pid) {
+  if (!pid || typeof pid !== 'number') return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    if (err.code === 'EPERM') return true;
+    return false;
+  }
+}
+
 async function _listWorktrees(worcaDir) {
   const pipelinesDir = join(worcaDir, 'multi', 'pipelines.d');
   if (!existsSync(pipelinesDir)) return [];
@@ -290,6 +301,29 @@ async function _listWorktrees(worcaDir) {
       if (actual) status = actual;
     }
 
+    // Stale-registry reconciliation: a child can die before ever writing
+    // status.json (e.g. fleet halt right after dispatch, preflight crash,
+    // SIGKILL). In that case the worktree exists but .worca/runs/ doesn't,
+    // _readWorktreeStatus returns null, and we'd fall back to reg.status
+    // which may still say "running" with a dead pid. Treat that as
+    // "interrupted" and patch the registry so this only happens once.
+    //
+    // Only reconcile when reg.pid is present — a missing pid means the
+    // entry is either from a non-standard registration path (e.g. test
+    // fixtures) or pre-dates the pid-on-registration contract, so we
+    // can't make liveness claims about it.
+    if (
+      status === 'running' &&
+      typeof reg.pid === 'number' &&
+      !_isPidAlive(reg.pid)
+    ) {
+      status = 'interrupted';
+      _patchRegistry(worcaDir, reg.run_id, {
+        status: 'interrupted',
+        interrupted_reason: 'stale_pid',
+      });
+    }
+
     let ageSeconds = 0;
     if (reg.started_at) {
       const started = new Date(reg.started_at).getTime();

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

@@ -0,0 +1,130 @@
+/**
+ * Fleet manifest watcher — monitors ~/.worca/fleet-runs/<fleet_id>.json for changes.
+ * Emits fleet-update WS events when a fleet manifest is written (§13.5).
+ */
+
+import { existsSync, readFileSync, watch } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { effectiveFleetStatus } from './fleet-routes.js';
+
+const FLEET_DEBOUNCE_MS = 200;
+const DEFAULT_FLEET_RUNS_DIR = join(homedir(), '.worca', 'fleet-runs');
+
+const FAILURE_STATES = new Set(['failed', 'setup_failed', 'unrecoverable']);
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function resolveChildStatus(child) {
+  const { project_path, run_id } = child;
+  if (!project_path || !run_id) return 'running';
+  const registryPath = join(
+    project_path,
+    '.worca',
+    'multi',
+    'pipelines.d',
+    `${run_id}.json`,
+  );
+  const entry = readJson(registryPath);
+  return entry?.status ?? 'running';
+}
+
+/**
+ * @param {{ broadcaster: { broadcast: Function }, fleetRunsDir?: string }} deps
+ */
+export function createFleetManifestWatcher({
+  broadcaster,
+  fleetRunsDir = DEFAULT_FLEET_RUNS_DIR,
+}) {
+  let fsWatcher = null;
+  /** @type {Map<string, ReturnType<typeof setTimeout>>} */
+  const debounceTimers = new Map();
+
+  function broadcastFleetUpdate(fleetId, manifestPath) {
+    const manifest = readJson(manifestPath);
+    if (!manifest) return;
+
+    const rawChildren = Array.isArray(manifest.children)
+      ? manifest.children
+      : [];
+    const children = rawChildren.map((child) => ({
+      run_id: child.run_id,
+      project_path: child.project_path,
+      status: resolveChildStatus(child),
+    }));
+
+    const completed_children = children.filter(
+      (c) => c.status === 'completed',
+    ).length;
+    const failed_children = children.filter((c) =>
+      FAILURE_STATES.has(c.status),
+    ).length;
+
+    // Derive the effective status (same rules as REST) instead of broadcasting
+    // raw manifest.status — otherwise cards stay "running" forever, because
+    // run_fleet.py never writes a terminal status after it exits. Pure
+    // function: persists nothing, so we don't trigger a watch→write→watch loop.
+    const { status, halt_reason } = effectiveFleetStatus(
+      manifest,
+      children.map((c) => c.status),
+    );
+
+    broadcaster.broadcast('fleet-update', {
+      fleet_id: fleetId,
+      status,
+      halt_reason,
+      completed_children,
+      failed_children,
+      children,
+    });
+  }
+
+  function scheduleUpdate(fleetId, manifestPath) {
+    const existing = debounceTimers.get(fleetId);
+    if (existing) clearTimeout(existing);
+    debounceTimers.set(
+      fleetId,
+      setTimeout(() => {
+        debounceTimers.delete(fleetId);
+        broadcastFleetUpdate(fleetId, manifestPath);
+      }, FLEET_DEBOUNCE_MS),
+    );
+  }
+
+  try {
+    if (existsSync(fleetRunsDir)) {
+      fsWatcher = watch(
+        fleetRunsDir,
+        { persistent: false },
+        (_event, filename) => {
+          if (!filename?.endsWith('.json')) return;
+          const fleetId = filename.slice(0, -5);
+          scheduleUpdate(fleetId, join(fleetRunsDir, filename));
+        },
+      );
+    }
+  } catch {
+    // fs.watch unsupported or dir unavailable — skip silently
+  }
+
+  function destroy() {
+    if (fsWatcher) {
+      try {
+        fsWatcher.close();
+      } catch {
+        /* ignore */
+      }
+      fsWatcher = null;
+    }
+    for (const timer of debounceTimers.values()) clearTimeout(timer);
+    debounceTimers.clear();
+  }
+
+  return { destroy };
+}

package/server/ws-message-router.js

@@ -80,6 +80,22 @@ export function createMessageRouter({
     };
   }
 
+  // When a run-scoped subscribe arrives with a `payload.projectId` that
+  // differs from the client's currently-bound subs.projectId, re-bind the
+  // WS to that project. Without this, the targeted project's WatcherSet
+  // stays in POLLING tier (no logWatcher / no live updates), and the
+  // backfill / live stream silently never arrive — symptoms reported by
+  // the user as "no logs / no agent prompts" on the run-detail page in
+  // global mode. We keep the previous projectId reference so demotion
+  // still happens via the normal client-count mechanism.
+  function _adoptProjectFromPayload(ws, payload) {
+    const requested = payload?.projectId;
+    if (!requested || !watcherSets.has(requested)) return;
+    const subs = clientManager.getSubs(ws);
+    if (subs?.projectId === requested) return;
+    clientManager.setProtocol(ws, subs?.protocolVersion ?? 1, requested);
+  }
+
   async function handleMessage(ws, data) {
     let json;
     try {
@@ -147,6 +163,7 @@ export function createMessageRouter({
         );
         return;
       }
+      _adoptProjectFromPayload(ws, req.payload);
       const proj = resolveProject(ws, req.payload);
       const runs = discoverRuns(proj.worcaDir);
       const run = runs.find((r) => r.id === runId);
@@ -294,6 +311,7 @@ export function createMessageRouter({
         );
         return;
       }
+      _adoptProjectFromPayload(ws, req.payload);
       const proj = resolveProject(ws, req.payload);
       if (!proj) {
         ws.send(
@@ -336,6 +354,7 @@ export function createMessageRouter({
     // subscribe-log
     if (req.type === 'subscribe-log') {
       const { stage, runId, iteration } = req.payload || {};
+      _adoptProjectFromPayload(ws, req.payload);
       const proj = resolveProject(ws, req.payload);
       const s = clientManager.ensureSubs(ws);
       s.logStage = stage || '*';
@@ -652,6 +671,7 @@ export function createMessageRouter({
         );
         return;
       }
+      _adoptProjectFromPayload(ws, req.payload);
       const proj = resolveProject(ws, req.payload);
       if (!proj.wset.beadsWatcher) {
         ws.send(JSON.stringify(makeOk(req, { issues: [], runId })));