@exaudeus/workrail 3.15.0 → 3.17.0

package/dist/v2/usecases/console-routes.js

@@ -8,32 +8,18 @@ const express_1 = __importDefault(require("express"));
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
 const worktree_service_js_1 = require("./worktree-service.js");
-const sseClients = new Set();
-let sseDebounceTimer = null;
-function broadcastChange() {
-    if (sseDebounceTimer !== null)
-        return;
-    sseDebounceTimer = setTimeout(() => {
-        sseDebounceTimer = null;
-        for (const client of sseClients) {
-            try {
-                client.write('data: {"type":"change"}\n\n');
-            }
-            catch {
-                sseClients.delete(client);
-            }
-        }
-    }, 200);
-}
-function watchSessionsDir(sessionsDir) {
+const dev_mode_js_1 = require("../../mcp/dev-mode.js");
+function watchSessionsDir(sessionsDir, onChanged) {
     try {
         fs_1.default.mkdirSync(sessionsDir, { recursive: true });
     }
     catch { }
     let watcher = null;
     try {
-        watcher = fs_1.default.watch(sessionsDir, { recursive: true }, () => {
-            broadcastChange();
+        watcher = fs_1.default.watch(sessionsDir, { recursive: true }, (_eventType, filename) => {
+            if (filename !== null && filename.endsWith('.jsonl')) {
+                onChanged();
+            }
         });
         watcher.on('error', () => { });
     }
@@ -53,9 +39,38 @@ function resolveConsoleDist() {
         return legacyConsoleDist;
     return null;
 }
-function mountConsoleRoutes(app, consoleService) {
-    const stopWatcher = watchSessionsDir(consoleService.getSessionsDir());
-    process.once('exit', stopWatcher);
+let cachedWorkflowTags = null;
+function loadWorkflowTags() {
+    if (cachedWorkflowTags !== null)
+        return cachedWorkflowTags;
+    const tagsPath = path_1.default.resolve(__dirname, '../../../spec/workflow-tags.json');
+    try {
+        cachedWorkflowTags = JSON.parse(fs_1.default.readFileSync(tagsPath, 'utf8'));
+        return cachedWorkflowTags;
+    }
+    catch {
+        return { version: 0, tags: [], workflows: {} };
+    }
+}
+function mountConsoleRoutes(app, consoleService, workflowService, timingRingBuffer) {
+    const sseClients = new Set();
+    let sseDebounceTimer = null;
+    function broadcastChange() {
+        if (sseDebounceTimer !== null)
+            return;
+        sseDebounceTimer = setTimeout(() => {
+            sseDebounceTimer = null;
+            for (const client of sseClients) {
+                try {
+                    client.write('data: {"type":"change"}\n\n');
+                }
+                catch {
+                    sseClients.delete(client);
+                }
+            }
+        }, 200);
+    }
+    const stopWatcher = watchSessionsDir(consoleService.getSessionsDir(), broadcastChange);
     app.get('/api/v2/workspace/events', (req, res) => {
         res.setHeader('Content-Type', 'text/event-stream');
         res.setHeader('Cache-Control', 'no-cache');
@@ -67,12 +82,23 @@ function mountConsoleRoutes(app, consoleService) {
         req.on('close', () => { sseClients.delete(res); });
         res.on('close', () => { sseClients.delete(res); });
     });
+    const devMode = (0, dev_mode_js_1.isDevMode)();
+    if (devMode) {
+        app.get('/api/v2/perf/tool-calls', (req, res) => {
+            const rawLimit = req.query['limit'];
+            const limit = typeof rawLimit === 'string' ? parseInt(rawLimit, 10) : undefined;
+            const safeLimit = (limit !== undefined && Number.isFinite(limit) && limit > 0) ? limit : undefined;
+            const observations = timingRingBuffer ? timingRingBuffer.recent(safeLimit) : [];
+            res.json({ success: true, data: { observations, total: timingRingBuffer?.size ?? 0, devMode } });
+        });
+    }
     app.get('/api/v2/sessions', async (_req, res) => {
         const result = await consoleService.getSessionList();
         result.match((data) => res.json({ success: true, data }), (error) => res.status(500).json({ success: false, error: error.message }));
     });
     let cwdRepoRootPromise = null;
     const REPO_ROOTS_TTL_MS = 60000;
+    const REPO_ROOT_SESSION_STALENESS_MS = 30 * 24 * 60 * 60 * 1000;
     let cachedRepoRoots = [];
     let repoRootsExpiresAt = 0;
     app.get('/api/v2/worktrees', async (_req, res) => {
@@ -83,7 +109,11 @@ function mountConsoleRoutes(app, consoleService) {
             if (Date.now() > repoRootsExpiresAt) {
                 cwdRepoRootPromise ?? (cwdRepoRootPromise = (0, worktree_service_js_1.resolveRepoRoot)(process.cwd()));
                 const cwdRoot = await cwdRepoRootPromise;
-                const rawRoots = sessions.map(s => s.repoRoot).filter((r) => r !== null);
+                const cutoffMs = Date.now() - REPO_ROOT_SESSION_STALENESS_MS;
+                const rawRoots = sessions
+                    .filter(s => s.lastModifiedMs >= cutoffMs)
+                    .map(s => s.repoRoot)
+                    .filter((r) => r !== null);
                 const resolvedRoots = await Promise.all(rawRoots.map(r => (0, worktree_service_js_1.resolveRepoRoot)(r)));
                 const repoRootSet = new Set(resolvedRoots.filter((r) => r !== null));
                 if (cwdRoot !== null)
@@ -116,10 +146,78 @@ function mountConsoleRoutes(app, consoleService) {
             res.status(status).json({ success: false, error: error.message });
         });
     });
+    if (workflowService) {
+        app.get('/api/v2/workflows', async (_req, res) => {
+            try {
+                const tagsFile = loadWorkflowTags();
+                const allWorkflows = await workflowService.loadAllWorkflows();
+                const workflows = allWorkflows
+                    .filter((w) => !tagsFile.workflows[w.definition.id]?.hidden)
+                    .map((w) => {
+                    const { definition, source } = w;
+                    const tagEntry = tagsFile.workflows[definition.id];
+                    return {
+                        id: definition.id,
+                        name: definition.name,
+                        description: definition.description,
+                        version: definition.version,
+                        tags: tagEntry?.tags ?? [],
+                        source,
+                        ...(definition.about !== undefined ? { about: definition.about } : {}),
+                        ...(definition.examples?.length ? { examples: [...definition.examples] } : {}),
+                    };
+                });
+                res.json({ success: true, data: { workflows } });
+            }
+            catch (e) {
+                res.status(500).json({ success: false, error: e instanceof Error ? e.message : String(e) });
+            }
+        });
+        app.get('/api/v2/workflows/:workflowId', async (req, res) => {
+            const { workflowId } = req.params;
+            try {
+                const workflow = await workflowService.getWorkflowById(workflowId);
+                if (!workflow) {
+                    return res.status(404).json({ success: false, error: `Workflow not found: ${workflowId}` });
+                }
+                const tagsFile = loadWorkflowTags();
+                if (tagsFile.workflows[workflowId]?.hidden) {
+                    return res.status(404).json({ success: false, error: `Workflow not found: ${workflowId}` });
+                }
+                const { definition, source } = workflow;
+                const tagEntry = tagsFile.workflows[workflowId];
+                return res.json({
+                    success: true,
+                    data: {
+                        id: definition.id,
+                        name: definition.name,
+                        description: definition.description,
+                        version: definition.version,
+                        tags: tagEntry?.tags ?? [],
+                        source,
+                        stepCount: definition.steps.length,
+                        ...(definition.about !== undefined ? { about: definition.about } : {}),
+                        ...(definition.examples?.length ? { examples: [...definition.examples] } : {}),
+                        ...(definition.preconditions?.length ? { preconditions: [...definition.preconditions] } : {}),
+                    },
+                });
+            }
+            catch (e) {
+                return res.status(500).json({ success: false, error: e instanceof Error ? e.message : String(e) });
+            }
+        });
+    }
     const consoleDist = resolveConsoleDist();
     if (consoleDist) {
-        app.use('/console', express_1.default.static(consoleDist));
+        app.use('/console', express_1.default.static(consoleDist, {
+            setHeaders(res, filePath) {
+                if (path_1.default.basename(filePath) === 'index.html') {
+                    res.setHeader('Cache-Control', 'no-cache');
+                }
+            }
+        }));
         app.get('/console/*path', (_req, res) => {
+            res.setHeader('Cache-Control', 'no-cache');
             res.sendFile(path_1.default.join(consoleDist, 'index.html'));
         });
         console.error(`[Console] UI serving from ${consoleDist}`);
@@ -133,4 +231,5 @@ function mountConsoleRoutes(app, consoleService) {
         });
         console.error('[Console] UI not found (run: cd console && npm run build)');
     }
+    return stopWatcher;
 }

package/dist/v2/usecases/console-service.d.ts

@@ -15,6 +15,7 @@ export interface ConsoleServicePorts {
 export declare class ConsoleService {
     private readonly ports;
     constructor(ports: ConsoleServicePorts);
+    private readonly _summaryCache;
     getSessionsDir(): string;
     getSessionList(): ResultAsync<ConsoleSessionListResponse, ConsoleServiceError>;
     getSessionDetail(sessionIdStr: string): ResultAsync<ConsoleSessionDetail, ConsoleServiceError>;

package/dist/v2/usecases/console-service.js

@@ -11,6 +11,8 @@ const node_outputs_js_1 = require("../projections/node-outputs.js");
 const advance_outcomes_js_1 = require("../projections/advance-outcomes.js");
 const artifacts_js_1 = require("../projections/artifacts.js");
 const run_context_js_1 = require("../projections/run-context.js");
+const sorted_event_log_js_1 = require("../durable-core/sorted-event-log.js");
+const run_execution_trace_js_1 = require("../projections/run-execution-trace.js");
 const constants_js_1 = require("../durable-core/constants.js");
 const index_js_1 = require("../durable-core/ids/index.js");
 const MAX_SESSIONS_TO_LOAD = 500;
@@ -18,6 +20,7 @@ const DORMANCY_THRESHOLD_MS = 3 * 24 * 60 * 60 * 1000;
 class ConsoleService {
     constructor(ports) {
         this.ports = ports;
+        this._summaryCache = new Map();
     }
     getSessionsDir() {
         return this.ports.dataDir.sessionsDir();
@@ -103,6 +106,10 @@ class ConsoleService {
         });
     }
     loadSessionSummary(sessionId, lastModifiedMs, nowMs) {
+        const cached = this._summaryCache.get(sessionId);
+        if (cached !== undefined && cached.mtime === lastModifiedMs) {
+            return (0, neverthrow_2.okAsync)(cached.summary);
+        }
         return this.ports.sessionStore
             .load(sessionId)
             .andThen((truth) => {
@@ -110,10 +117,22 @@ class ConsoleService {
             const workflowNamesRA = dagRes.isOk()
                 ? resolveWorkflowNames(dagRes.value, this.ports.pinnedWorkflowStore)
                 : (0, neverthrow_2.okAsync)({});
+            const completionRA = dagRes.isOk()
+                ? resolveRunCompletionFromDag(dagRes.value, this.ports.snapshotStore)
+                : (0, neverthrow_2.okAsync)({});
             return neverthrow_1.ResultAsync.combine([
-                resolveRunCompletion(truth.events, this.ports.snapshotStore),
+                completionRA,
                 workflowNamesRA,
-            ]).map(([completionMap, workflowNames]) => projectSessionSummary(sessionId, truth, completionMap, workflowNames, lastModifiedMs, nowMs));
+            ]).map(([completionMap, workflowNames]) => {
+                const dag = dagRes.isOk() ? dagRes.value : undefined;
+                return projectSessionSummary(sessionId, truth, completionMap, workflowNames, lastModifiedMs, nowMs, dag);
+            });
+        })
+            .map((summary) => {
+            if (summary !== null && summary.status !== 'in_progress') {
+                this._summaryCache.set(sessionId, { mtime: lastModifiedMs, summary });
+            }
+            return summary;
         })
             .orElse(() => (0, neverthrow_2.okAsync)(null));
     }
@@ -239,8 +258,8 @@ function extractStepTitlesFromCompiled(compiled) {
     return titles;
 }
 const TITLE_CONTEXT_KEYS = ['goal', 'taskDescription', 'mrTitle', 'prTitle', 'ticketTitle', 'problem'];
-function deriveSessionTitle(events) {
-    const contextRes = (0, run_context_js_1.projectRunContextV2)(events);
+function deriveSessionTitle(sortedEvents) {
+    const contextRes = (0, run_context_js_1.projectRunContextV2)(sortedEvents);
     if (contextRes.isOk()) {
         for (const runCtx of Object.values(contextRes.value.byRunId)) {
             for (const key of TITLE_CONTEXT_KEYS) {
@@ -251,7 +270,7 @@ function deriveSessionTitle(events) {
             }
         }
     }
-    const title = extractTitleFromFirstRecap(events);
+    const title = extractTitleFromFirstRecap(sortedEvents);
     if (title)
         return title;
     return null;
@@ -333,19 +352,26 @@ function truncateTitle(text, maxLen = 120) {
         return text;
     return text.slice(0, maxLen - 1) + '…';
 }
-function projectSessionSummary(sessionId, truth, completionByRunId, workflowNames, lastModifiedMs, nowMs) {
+function projectSessionSummary(sessionId, truth, completionByRunId, workflowNames, lastModifiedMs, nowMs, precomputedDag) {
     const { events } = truth;
     const health = (0, session_health_js_1.projectSessionHealthV2)(truth);
     if (health.isErr())
         return null;
     const sessionHealth = health.value.kind === 'healthy' ? 'healthy' : 'corrupt';
-    const dagRes = (0, run_dag_js_1.projectRunDagV2)(events);
-    if (dagRes.isErr())
+    let dag;
+    if (precomputedDag !== undefined) {
+        dag = precomputedDag;
+    }
+    else {
+        const res = (0, run_dag_js_1.projectRunDagV2)(events);
+        dag = res.isOk() ? res.value : null;
+    }
+    if (dag === null)
         return null;
-    const dag = dagRes.value;
-    const statusRes = (0, run_status_signals_js_1.projectRunStatusSignalsV2)(events);
-    const gapsRes = (0, gaps_js_1.projectGapsV2)(events);
-    const sessionTitle = deriveSessionTitle(events);
+    const sortedEventsRes = (0, sorted_event_log_js_1.asSortedEventLog)(events);
+    const statusRes = sortedEventsRes.isOk() ? (0, run_status_signals_js_1.projectRunStatusSignalsV2)(sortedEventsRes.value) : (0, neverthrow_2.err)(sortedEventsRes.error);
+    const gapsRes = sortedEventsRes.isOk() ? (0, gaps_js_1.projectGapsV2)(sortedEventsRes.value) : (0, neverthrow_2.err)(sortedEventsRes.error);
+    const sessionTitle = sortedEventsRes.isOk() ? deriveSessionTitle(sortedEventsRes.value) : null;
     const gitBranch = extractGitBranch(events);
     const repoRoot = extractRepoRoot(events);
     const runs = Object.values(dag.runsById);
@@ -418,26 +444,52 @@ function projectSessionDetail(sessionId, truth, completionByRunId, stepLabels, w
     const { events } = truth;
     const health = (0, session_health_js_1.projectSessionHealthV2)(truth);
     const sessionHealth = health.isOk() && health.value.kind === 'healthy' ? 'healthy' : 'corrupt';
-    const sessionTitle = deriveSessionTitle(events);
+    const sortedEventsRes = (0, sorted_event_log_js_1.asSortedEventLog)(events);
+    const sessionTitle = sortedEventsRes.isOk() ? deriveSessionTitle(sortedEventsRes.value) : null;
     const dagRes = (0, run_dag_js_1.projectRunDagV2)(events);
     if (dagRes.isErr()) {
         return { sessionId, sessionTitle, health: sessionHealth, runs: [] };
     }
-    const statusRes = (0, run_status_signals_js_1.projectRunStatusSignalsV2)(events);
-    const gapsRes = (0, gaps_js_1.projectGapsV2)(events);
+    const statusRes = sortedEventsRes.isOk() ? (0, run_status_signals_js_1.projectRunStatusSignalsV2)(sortedEventsRes.value) : (0, neverthrow_2.err)(sortedEventsRes.error);
+    const gapsRes = sortedEventsRes.isOk() ? (0, gaps_js_1.projectGapsV2)(sortedEventsRes.value) : (0, neverthrow_2.err)(sortedEventsRes.error);
+    const executionTraceRes = (0, run_execution_trace_js_1.projectRunExecutionTraceV2)(events);
+    const outputsRes = (0, node_outputs_js_1.projectNodeOutputsV2)(events);
+    const artifactsRes = (0, artifacts_js_1.projectArtifactsV2)(events);
+    const failedValidationNodeIds = new Set();
+    for (const e of events) {
+        if (e.kind !== constants_js_1.EVENT_KIND.VALIDATION_PERFORMED)
+            continue;
+        if (!e.data.result.valid) {
+            failedValidationNodeIds.add(e.scope.nodeId);
+        }
+    }
+    const gapNodeIds = new Set();
+    if (gapsRes.isOk()) {
+        for (const gap of Object.values(gapsRes.value.byGapId)) {
+            gapNodeIds.add(gap.nodeId);
+        }
+    }
     const runs = Object.values(dagRes.value.runsById).map((run) => {
         const statusSignals = statusRes.isOk() ? statusRes.value.byRunId[run.runId] : undefined;
         const status = deriveRunStatus(statusSignals?.isBlocked ?? false, statusSignals?.hasUnresolvedCriticalGaps ?? false, completionByRunId[run.runId] ?? false);
         const tipSet = new Set(run.tipNodeIds);
-        const nodes = Object.values(run.nodesById).map((node) => ({
-            nodeId: node.nodeId,
-            nodeKind: node.nodeKind,
-            parentNodeId: node.parentNodeId,
-            createdAtEventIndex: node.createdAtEventIndex,
-            isPreferredTip: node.nodeId === run.preferredTipNodeId,
-            isTip: tipSet.has(node.nodeId),
-            stepLabel: stepLabels[node.nodeId] ?? null,
-        }));
+        const nodes = Object.values(run.nodesById).map((node) => {
+            const nodeOutputs = outputsRes.isOk() ? outputsRes.value.nodesById[node.nodeId] : undefined;
+            const nodeArtifacts = artifactsRes.isOk() ? artifactsRes.value.byNodeId[node.nodeId] : undefined;
+            return {
+                nodeId: node.nodeId,
+                nodeKind: node.nodeKind,
+                parentNodeId: node.parentNodeId,
+                createdAtEventIndex: node.createdAtEventIndex,
+                isPreferredTip: node.nodeId === run.preferredTipNodeId,
+                isTip: tipSet.has(node.nodeId),
+                stepLabel: stepLabels[node.nodeId] ?? null,
+                hasRecap: (nodeOutputs?.currentByChannel.recap.length ?? 0) > 0,
+                hasFailedValidations: failedValidationNodeIds.has(node.nodeId),
+                hasGaps: gapNodeIds.has(node.nodeId),
+                hasArtifacts: (nodeArtifacts?.artifacts.length ?? 0) > 0,
+            };
+        });
         const edges = run.edges.map((edge) => ({
             edgeKind: edge.edgeKind,
             fromNodeId: edge.fromNodeId,
@@ -459,6 +511,9 @@ function projectSessionDetail(sessionId, truth, completionByRunId, stepLabels, w
             hasUnresolvedCriticalGaps: gapsRes.isOk()
                 ? (gapsRes.value.unresolvedCriticalByRunId[run.runId]?.length ?? 0) > 0
                 : false,
+            executionTraceSummary: executionTraceRes.isOk()
+                ? (executionTraceRes.value.byRunId[run.runId] ?? null)
+                : null,
         };
     });
     return { sessionId, sessionTitle, health: sessionHealth, runs };
@@ -566,7 +621,10 @@ function extractValidations(events, nodeId) {
     return results;
 }
 function extractGaps(events, nodeId) {
-    const gapsRes = (0, gaps_js_1.projectGapsV2)(events);
+    const sortedEventsRes = (0, sorted_event_log_js_1.asSortedEventLog)(events);
+    if (sortedEventsRes.isErr())
+        return [];
+    const gapsRes = (0, gaps_js_1.projectGapsV2)(sortedEventsRes.value);
     if (gapsRes.isErr())
         return [];
     const gaps = [];

package/dist/v2/usecases/console-types.d.ts

@@ -31,6 +31,10 @@ export interface ConsoleDagNode {
     readonly isPreferredTip: boolean;
     readonly isTip: boolean;
     readonly stepLabel: string | null;
+    readonly hasRecap: boolean;
+    readonly hasFailedValidations: boolean;
+    readonly hasGaps: boolean;
+    readonly hasArtifacts: boolean;
 }
 export interface ConsoleDagEdge {
     readonly edgeKind: 'acked_step' | 'checkpoint';
@@ -38,6 +42,25 @@ export interface ConsoleDagEdge {
     readonly toNodeId: string;
     readonly createdAtEventIndex: number;
 }
+export type ConsoleExecutionTraceItemKind = 'selected_next_step' | 'evaluated_condition' | 'entered_loop' | 'exited_loop' | 'detected_non_tip_advance' | 'context_fact' | 'divergence';
+export interface ConsoleExecutionTraceRef {
+    readonly kind: 'node_id' | 'step_id' | 'loop_id' | 'condition_id';
+    readonly value: string;
+}
+export interface ConsoleExecutionTraceItem {
+    readonly kind: ConsoleExecutionTraceItemKind;
+    readonly summary: string;
+    readonly recordedAtEventIndex: number;
+    readonly refs: readonly ConsoleExecutionTraceRef[];
+}
+export interface ConsoleExecutionTraceFact {
+    readonly key: string;
+    readonly value: string;
+}
+export interface ConsoleExecutionTraceSummary {
+    readonly items: readonly ConsoleExecutionTraceItem[];
+    readonly contextFacts: readonly ConsoleExecutionTraceFact[];
+}
 export interface ConsoleDagRun {
     readonly runId: string;
     readonly workflowId: string | null;
@@ -49,6 +72,7 @@ export interface ConsoleDagRun {
     readonly tipNodeIds: readonly string[];
     readonly status: ConsoleRunStatus;
     readonly hasUnresolvedCriticalGaps: boolean;
+    readonly executionTraceSummary: ConsoleExecutionTraceSummary | null;
 }
 export interface ConsoleSessionDetail {
     readonly sessionId: string;
@@ -128,3 +152,32 @@ export interface ConsoleNodeDetail {
     readonly validations: readonly ConsoleValidationResult[];
     readonly gaps: readonly ConsoleNodeGap[];
 }
+export interface ConsoleWorkflowSourceInfo {
+    readonly kind: 'bundled' | 'user' | 'project' | 'custom' | 'git' | 'remote' | 'plugin';
+    readonly displayName: string;
+}
+export interface ConsoleWorkflowSummary {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly version: string;
+    readonly tags: readonly string[];
+    readonly source: ConsoleWorkflowSourceInfo;
+    readonly about?: string;
+    readonly examples?: readonly string[];
+}
+export interface ConsoleWorkflowListResponse {
+    readonly workflows: readonly ConsoleWorkflowSummary[];
+}
+export interface ConsoleWorkflowDetail {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly version: string;
+    readonly tags: readonly string[];
+    readonly source: ConsoleWorkflowSourceInfo;
+    readonly stepCount: number;
+    readonly about?: string;
+    readonly examples?: readonly string[];
+    readonly preconditions?: readonly string[];
+}

package/dist/v2/usecases/worktree-service.js

@@ -44,6 +44,29 @@ function parseWorktreePorcelain(raw) {
     }
     return entries;
 }
+const MAX_CONCURRENT_ENRICHMENTS = 8;
+let activeEnrichments = 0;
+const enrichmentQueue = [];
+function acquireEnrichmentSlot() {
+    return new Promise((resolve) => {
+        if (activeEnrichments < MAX_CONCURRENT_ENRICHMENTS) {
+            activeEnrichments++;
+            resolve();
+        }
+        else {
+            enrichmentQueue.push(() => { activeEnrichments++; resolve(); });
+        }
+    });
+}
+function releaseEnrichmentSlot() {
+    const next = enrichmentQueue.shift();
+    if (next) {
+        next();
+    }
+    else {
+        activeEnrichments--;
+    }
+}
 function parseFileStatus(xy) {
     if (xy === '??')
         return 'untracked';
@@ -113,7 +136,15 @@ async function enrichRepo(repoRoot, activeSessions) {
     if (porcelain === null)
         return null;
     const rawWorktrees = parseWorktreePorcelain(porcelain);
-    const results = await Promise.allSettled(rawWorktrees.map(wt => enrichWorktree(wt)));
+    const results = await Promise.allSettled(rawWorktrees.map(async (wt) => {
+        await acquireEnrichmentSlot();
+        try {
+            return await enrichWorktree(wt);
+        }
+        finally {
+            releaseEnrichmentSlot();
+        }
+    }));
     const worktrees = rawWorktrees.flatMap((wt, i) => {
         const result = results[i];
         if (result.status === 'rejected') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exaudeus/workrail",
-  "version": "3.15.0",
+  "version": "3.17.0",
   "description": "Step-by-step workflow enforcement for AI agents via MCP",
   "license": "MIT",
   "repository": {
@@ -77,7 +77,8 @@
     "codemod:v2-contexts": "npx ts-node scripts/codemods/run.ts --mod v2-contexts --tsconfig tsconfig.test.json --write",
     "codemod:v2-prune": "npx ts-node scripts/codemods/run.ts --mod v2-prune --tsconfig tsconfig.test.json --write",
     "codemod:guard": "npx ts-node scripts/codemods/run.ts --mod guard --tsconfig tsconfig.test.json",
-    "codemod:test-platform-guard": "npx ts-node scripts/codemods/run.ts --mod test-platform-guard --tsconfig tsconfig.test.json"
+    "codemod:test-platform-guard": "npx ts-node scripts/codemods/run.ts --mod test-platform-guard --tsconfig tsconfig.test.json",
+    "prepare": "bash scripts/setup-hooks.sh"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.24.0",
@@ -89,7 +90,7 @@
     "dotenv": "^17.2.0",
     "express": "^5.1.0",
     "neverthrow": "^8.2.0",
-    "open": "^10.2.0",
+    "open": "^11.0.0",
     "reflect-metadata": "^0.2.0",
     "semver": "^7.7.2",
     "tsconfig-paths": "^4.2.0",
@@ -121,8 +122,8 @@
     "happy-dom": "^20.0.11",
     "jsdom": "^27.0.0",
     "lit": "^3.3.1",
-    "node-fetch": "^2.7.0",
-    "semantic-release": "^24.2.0",
+    "node-fetch": "^3.3.2",
+    "semantic-release": "^25.0.3",
     "ts-morph": "^27.0.2",
     "typescript": "^5.9.3",
     "vite": "^7.1.9",

package/spec/workflow.schema.json

@@ -182,6 +182,24 @@
       "type": "integer",
       "minimum": 1,
       "description": "The authoring spec version this workflow was last validated against."
+    },
+    "about": {
+      "type": "string",
+      "description": "Human-readable overview for display in the console and other UIs. Markdown is supported. Write for a user deciding whether to use this workflow: what it does, when to use it, what it produces, and how to get good results. User-facing surface -- not an agent instruction (use metaGuidance for that).",
+      "minLength": 1,
+      "maxLength": 4096
+    },
+    "examples": {
+      "type": "array",
+      "description": "Short illustrative goal strings showing what this workflow is used for. Write for humans browsing the catalog and for agents selecting the right workflow. Each item should be concrete and specific enough to be informative.",
+      "items": {
+        "type": "string",
+        "minLength": 10,
+        "maxLength": 120
+      },
+      "minItems": 1,
+      "maxItems": 6,
+      "uniqueItems": true
     }
   },
   "required": [