@exaudeus/workrail 3.11.2 → 3.13.0

package/dist/mcp/handler-factory.js

@@ -4,6 +4,7 @@ exports.toMcpResult = toMcpResult;
 exports.createHandler = createHandler;
 exports.createValidatingHandler = createValidatingHandler;
 const types_js_1 = require("./types.js");
+const boundary_coercion_js_1 = require("./boundary-coercion.js");
 const index_js_1 = require("./validation/index.js");
 const bounded_json_js_1 = require("./validation/bounded-json.js");
 const v2_execution_helpers_js_1 = require("./handlers/v2-execution-helpers.js");
@@ -56,12 +57,15 @@ function toMcpResult(result) {
 }
 function createHandler(schema, handler, shapeSchema, aliasMap) {
     return async (args, ctx) => {
-        const parseResult = schema.safeParse(args);
+        const normalizedArgs = shapeSchema !== undefined
+            ? (0, boundary_coercion_js_1.coerceJsonStringObjectFields)(args, shapeSchema, aliasMap)
+            : args;
+        const parseResult = schema.safeParse(normalizedArgs);
         if (!parseResult.success) {
             const introspectionSchema = shapeSchema ?? schema;
-            const suggestionResult = (0, index_js_1.generateSuggestions)(args, introspectionSchema, index_js_1.DEFAULT_SUGGESTION_CONFIG, aliasMap);
+            const suggestionResult = (0, index_js_1.generateSuggestions)(normalizedArgs, introspectionSchema, index_js_1.DEFAULT_SUGGESTION_CONFIG, aliasMap);
             const suggestionDetails = (0, index_js_1.formatSuggestionDetails)(suggestionResult);
-            const patchedTemplate = (0, index_js_1.patchTemplateForFailedOptionals)(suggestionDetails.correctTemplate ?? null, args, parseResult.error.errors, introspectionSchema, index_js_1.DEFAULT_SUGGESTION_CONFIG.maxTemplateDepth);
+            const patchedTemplate = (0, index_js_1.patchTemplateForFailedOptionals)(suggestionDetails.correctTemplate ?? null, normalizedArgs, parseResult.error.errors, introspectionSchema, index_js_1.DEFAULT_SUGGESTION_CONFIG.maxTemplateDepth);
             const patchedDetails = patchedTemplate !== suggestionDetails.correctTemplate
                 ? { ...suggestionDetails, correctTemplate: patchedTemplate }
                 : suggestionDetails;
@@ -82,9 +86,12 @@ function createHandler(schema, handler, shapeSchema, aliasMap) {
         }
     };
 }
-function createValidatingHandler(schema, preValidate, handler) {
+function createValidatingHandler(schema, preValidate, handler, shapeSchema, aliasMap) {
     return async (args, ctx) => {
-        const pre = preValidate(args);
+        const normalizedArgs = shapeSchema !== undefined
+            ? (0, boundary_coercion_js_1.coerceJsonStringObjectFields)(args, shapeSchema, aliasMap)
+            : args;
+        const pre = preValidate(normalizedArgs);
         if (!pre.ok) {
             const error = pre.error;
             const details = error.details && typeof error.details === 'object' ? error.details : {};
@@ -103,6 +110,6 @@ function createValidatingHandler(schema, preValidate, handler) {
             }
             return toMcpResult(error);
         }
-        return createHandler(schema, handler)(args, ctx);
+        return createHandler(schema, handler, shapeSchema, aliasMap)(normalizedArgs, ctx);
     };
 }

package/dist/mcp/handlers/shared/request-workflow-reader.d.ts

@@ -18,5 +18,13 @@ export declare function resolveRequestWorkspaceDirectory(options: {
     readonly serverCwd?: string;
 }): string;
 export declare function toProjectWorkflowDirectory(workspaceDirectory: string): string;
-export declare function discoverRootedWorkflowDirectories(roots: readonly string[]): Promise<readonly string[]>;
-export declare function createWorkflowReaderForRequest(options: RequestWorkflowReaderOptions): Promise<IWorkflowReader>;
+export interface WorkflowRootDiscoveryResult {
+    readonly discovered: readonly string[];
+    readonly stale: readonly string[];
+}
+export declare function discoverRootedWorkflowDirectories(roots: readonly string[]): Promise<WorkflowRootDiscoveryResult>;
+export interface WorkflowReaderForRequestResult {
+    readonly reader: IWorkflowReader;
+    readonly stalePaths: readonly string[];
+}
+export declare function createWorkflowReaderForRequest(options: RequestWorkflowReaderOptions): Promise<WorkflowReaderForRequestResult>;

package/dist/mcp/handlers/shared/request-workflow-reader.js

@@ -37,10 +37,15 @@ function toProjectWorkflowDirectory(workspaceDirectory) {
 async function discoverRootedWorkflowDirectories(roots) {
     const discoveredByPath = new Set();
     const discoveredPaths = [];
+    const stalePaths = [];
     for (const root of roots) {
         const rootPath = path_1.default.resolve(root);
-        const nextPaths = await discoverWorkflowDirectoriesUnderRoot(rootPath);
-        for (const nextPath of nextPaths) {
+        const result = await discoverWorkflowDirectoriesUnderRoot(rootPath);
+        if (result.stale) {
+            stalePaths.push(rootPath);
+            continue;
+        }
+        for (const nextPath of result.discovered) {
             const normalizedPath = path_1.default.resolve(nextPath);
             if (discoveredByPath.has(normalizedPath))
                 continue;
@@ -48,19 +53,20 @@ async function discoverRootedWorkflowDirectories(roots) {
             discoveredPaths.push(normalizedPath);
         }
     }
-    return discoveredPaths;
+    return { discovered: discoveredPaths, stale: stalePaths };
 }
 async function createWorkflowReaderForRequest(options) {
     const workspaceDirectory = resolveRequestWorkspaceDirectory(options);
     const projectWorkflowDirectory = toProjectWorkflowDirectory(workspaceDirectory);
     const rememberedRoots = await listRememberedRoots(options.rememberedRootsStore);
-    const rootedWorkflowDirectories = await discoverRootedWorkflowDirectories(rememberedRoots);
+    const { discovered: rootedWorkflowDirectories, stale: stalePaths } = await discoverRootedWorkflowDirectories(rememberedRoots);
     const customPaths = rootedWorkflowDirectories.filter((directory) => directory !== projectWorkflowDirectory);
-    const storage = new enhanced_multi_source_workflow_storage_js_1.EnhancedMultiSourceWorkflowStorage({
+    const storage = (0, enhanced_multi_source_workflow_storage_js_1.createEnhancedMultiSourceWorkflowStorage)({
         customPaths,
         projectPath: projectWorkflowDirectory,
-    }, options.featureFlags);
-    return new schema_validating_workflow_storage_js_1.SchemaValidatingCompositeWorkflowStorage(storage);
+    }, options.featureFlags ?? undefined);
+    const reader = new schema_validating_workflow_storage_js_1.SchemaValidatingCompositeWorkflowStorage(storage);
+    return { reader, stalePaths };
 }
 async function listRememberedRoots(rememberedRootsStore) {
     if (!rememberedRootsStore)
@@ -74,8 +80,16 @@ async function listRememberedRoots(rememberedRootsStore) {
 }
 async function discoverWorkflowDirectoriesUnderRoot(rootPath) {
     const discoveredPaths = [];
-    await walkForRootedWorkflowDirectories(rootPath, discoveredPaths);
-    return discoveredPaths;
+    try {
+        await walkForRootedWorkflowDirectories(rootPath, discoveredPaths);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            return { discovered: [], stale: true };
+        }
+        throw err;
+    }
+    return { discovered: discoveredPaths, stale: false };
 }
 async function walkForRootedWorkflowDirectories(currentDirectory, discoveredPaths) {
     const entries = await promises_1.default.readdir(currentDirectory, { withFileTypes: true });
@@ -93,7 +107,10 @@ async function walkForRootedWorkflowDirectories(currentDirectory, discoveredPath
             }
             continue;
         }
-        await walkForRootedWorkflowDirectories(entryPath, discoveredPaths);
+        await walkForRootedWorkflowDirectories(entryPath, discoveredPaths).catch((err) => {
+            if (err.code !== 'ENOENT')
+                throw err;
+        });
     }
 }
 function shouldSkipDirectory(name) {

package/dist/mcp/handlers/shared/workflow-source-visibility.d.ts

@@ -1,5 +1,5 @@
 import type { Workflow, WorkflowSourceInfo } from '../../../types/workflow.js';
-import type { IWorkflowReader } from '../../../types/storage.js';
+import type { ICompositeWorkflowStorage, IWorkflowReader } from '../../../types/storage.js';
 import type { RememberedRootRecordV2 } from '../../../v2/ports/remembered-roots-store.port.js';
 export interface PublicWorkflowSource {
     readonly kind: WorkflowSourceInfo['kind'];
@@ -31,3 +31,5 @@ export declare function detectWorkflowMigrationGuidance(options: {
     readonly workflowReader: IWorkflowReader;
     readonly rememberedRoots: readonly RememberedRootRecordV2[];
 }): Promise<WorkflowMigrationGuidance | undefined>;
+export declare function isCompositeWorkflowReader(reader: unknown): reader is ICompositeWorkflowStorage;
+export declare function deriveGroupLabel(rootPath: string, sourcePath: string): string;

package/dist/mcp/handlers/shared/workflow-source-visibility.js

@@ -5,6 +5,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toWorkflowVisibility = toWorkflowVisibility;
 exports.detectWorkflowMigrationGuidance = detectWorkflowMigrationGuidance;
+exports.isCompositeWorkflowReader = isCompositeWorkflowReader;
+exports.deriveGroupLabel = deriveGroupLabel;
 const path_1 = __importDefault(require("path"));
 function toWorkflowVisibility(workflow, rememberedRoots, options = {}) {
     const source = {
@@ -56,9 +58,11 @@ async function detectWorkflowMigrationGuidance(options) {
     }
     return undefined;
 }
-function isCompositeWorkflowReader(workflowReader) {
-    return (workflowReader.kind === 'composite' &&
-        typeof workflowReader.getStorageInstances === 'function');
+function isCompositeWorkflowReader(reader) {
+    return (typeof reader === 'object' &&
+        reader !== null &&
+        reader.kind === 'composite' &&
+        typeof reader.getStorageInstances === 'function');
 }
 function deriveRootedSharingContext(workflow, rememberedRoots) {
     if (workflow.source.kind !== 'custom')

package/dist/mcp/handlers/v2-execution/replay.js

@@ -14,8 +14,9 @@ const v2_token_ops_js_1 = require("../v2-token-ops.js");
 const v2_state_conversion_js_1 = require("../v2-state-conversion.js");
 const constants_js_1 = require("../../../v2/durable-core/constants.js");
 const index_js_2 = require("./index.js");
+const assessments_js_1 = require("../../../v2/projections/assessments.js");
 function buildAdvancedReplayResponse(args) {
-    const { sessionId, runId, toNodeId, attemptId, toSnapshot, workflow, truth, workflowHash, ports, sha256, aliasStore, entropy } = args;
+    const { sessionId, runId, fromNodeId, toNodeId, attemptId, toSnapshot, workflow, truth, workflowHash, ports, sha256, aliasStore, entropy } = args;
     const toNodeIdBranded = (0, index_js_1.asNodeId)(String(toNodeId));
     const pending = (0, snapshot_state_js_1.derivePendingStep)(toSnapshot.enginePayload.engineState);
     const isComplete = (0, snapshot_state_js_1.deriveIsComplete)(toSnapshot.enginePayload.engineState);
@@ -116,6 +117,7 @@ function buildAdvancedReplayResponse(args) {
     }
     const preferences = (0, v2_execution_helpers_js_1.derivePreferencesOrDefault)({ truth, runId, nodeId: toNodeIdBranded });
     const nextIntent = (0, v2_state_conversion_js_1.deriveNextIntent)({ rehydrateOnly: false, isComplete, pending: okMeta });
+    const stepContext = buildStepContext(truth.events, fromNodeId);
     return nextTokensMint.andThen((nextTokens) => (0, neverthrow_1.okAsync)(output_schemas_js_1.V2ContinueWorkflowOutputSchema.parse({
         kind: 'ok',
         continueToken: pending ? nextTokens.continueToken : undefined,
@@ -125,8 +127,30 @@ function buildAdvancedReplayResponse(args) {
         preferences,
         nextIntent,
         nextCall: (0, index_js_2.buildNextCall)({ continueToken: pending ? nextTokens.continueToken : undefined, isComplete, pending: okMeta }),
+        stepContext,
     })));
 }
+function buildStepContext(events, completedNodeId) {
+    const projection = (0, assessments_js_1.projectAssessmentsV2)(events);
+    if (projection.isErr()) {
+        console.warn(`[workrail:replay] stepContext projection failed for node '${String(completedNodeId)}' — stepContext will be absent: ${projection.error.message}`);
+        return undefined;
+    }
+    const recorded = (0, assessments_js_1.getLatestAssessmentForNode)(projection.value, String(completedNodeId));
+    if (!recorded)
+        return undefined;
+    return {
+        assessments: {
+            assessmentId: recorded.assessmentId,
+            dimensions: recorded.dimensions.map((d) => ({
+                dimensionId: d.dimensionId,
+                level: d.level,
+                ...(d.rationale !== undefined ? { rationale: d.rationale } : {}),
+            })),
+            normalizationNotes: recorded.normalizationNotes,
+        },
+    };
+}
 function replayFromRecordedAdvance(args) {
     const { recordedEvent, truth, sessionId, runId, nodeId, workflowHash, attemptId, pinnedWorkflow, snapshotStore, sha256, tokenCodecPorts, aliasStore, entropy, } = args;
     if (recordedEvent.data.outcome.kind === 'blocked') {

package/dist/mcp/handlers/v2-execution/start.js

@@ -216,23 +216,28 @@ function executeStartWorkflow(input, ctx) {
         workspacePath: input.workspacePath,
         resolvedRootUris: ctx.v2.resolvedRootUris,
     });
-    const workflowReader = shouldUseRequestReader
-        ? {
-            getWorkflowById: async (workflowId) => {
-                const requestReader = await (0, request_workflow_reader_js_1.createWorkflowReaderForRequest)({
-                    featureFlags: ctx.featureFlags,
-                    workspacePath: input.workspacePath,
-                    resolvedRootUris: ctx.v2.resolvedRootUris,
-                    rememberedRootsStore: ctx.v2.rememberedRootsStore,
-                });
-                const requestResult = await requestReader.getWorkflowById(workflowId);
-                if (requestResult != null)
-                    return requestResult;
-                return ctx.workflowService.getWorkflowById(workflowId);
+    const readerRA = shouldUseRequestReader
+        ? neverthrow_1.ResultAsync.fromPromise((0, request_workflow_reader_js_1.createWorkflowReaderForRequest)({
+            featureFlags: ctx.featureFlags,
+            workspacePath: input.workspacePath,
+            resolvedRootUris: ctx.v2.resolvedRootUris,
+            rememberedRootsStore: ctx.v2.rememberedRootsStore,
+        }), (err) => ({
+            kind: 'precondition_failed',
+            message: `Failed to initialize workflow reader: ${String(err)}`,
+        })).map(({ reader, stalePaths }) => ({
+            workflowReader: {
+                getWorkflowById: async (workflowId) => {
+                    const requestResult = await reader.getWorkflowById(workflowId);
+                    if (requestResult != null)
+                        return requestResult;
+                    return ctx.workflowService.getWorkflowById(workflowId);
+                },
             },
-        }
-        : ctx.workflowService;
-    return loadAndPinWorkflow({
+            stalePaths,
+        }))
+        : (0, neverthrow_1.okAsync)({ workflowReader: ctx.workflowService, stalePaths: [] });
+    return readerRA.andThen(({ workflowReader, stalePaths }) => loadAndPinWorkflow({
         workflowId: input.workflowId,
         workflowReader,
         crypto,
@@ -345,10 +350,11 @@ function executeStartWorkflow(input, ctx) {
                 preferences,
                 nextIntent,
                 nextCall: (0, index_js_2.buildNextCall)({ continueToken: tokens.continueToken, isComplete: false, pending }),
+                ...(stalePaths.length > 0 ? { staleRoots: [...stalePaths] } : {}),
             });
             return (0, neverthrow_1.okAsync)({ response: parsed, contentEnvelope });
         });
-    });
+    }));
 }
 function enrichPinnedSnapshotWithResolvedReferences(snapshot, references, workspacePath) {
     if (references.length === 0) {

package/dist/mcp/handlers/v2-manage-workflow-source.d.ts

@@ -0,0 +1,7 @@
+import type { ToolContext, ToolResult } from '../types.js';
+import type { V2ManageWorkflowSourceInput } from '../v2/tools.js';
+export interface ManageWorkflowSourceOutput {
+    readonly action: 'attach' | 'detach';
+    readonly path: string;
+}
+export declare function handleV2ManageWorkflowSource(input: V2ManageWorkflowSourceInput, ctx: ToolContext): Promise<ToolResult<ManageWorkflowSourceOutput>>;

package/dist/mcp/handlers/v2-manage-workflow-source.js

@@ -0,0 +1,50 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleV2ManageWorkflowSource = handleV2ManageWorkflowSource;
+const path_1 = __importDefault(require("path"));
+const assert_never_js_1 = require("../../runtime/assert-never.js");
+const types_js_1 = require("../types.js");
+function mapManagedSourceErrorToToolError(error) {
+    switch (error.code) {
+        case 'MANAGED_SOURCE_BUSY':
+            return (0, types_js_1.errRetryAfterMs)('INTERNAL_ERROR', 'WorkRail is temporarily busy updating managed workflow sources.', error.retry.afterMs, {
+                suggestion: 'Wait a moment and retry. Another WorkRail process may be updating managed workflow sources.',
+            });
+        case 'MANAGED_SOURCE_IO_ERROR':
+            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', 'WorkRail could not update the managed workflow sources store.', {
+                suggestion: 'Fix WorkRail local storage access and retry. Check that the ~/.workrail data directory exists and is writable.',
+                details: { errorMessage: error.message },
+            });
+        case 'MANAGED_SOURCE_CORRUPTION':
+            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', 'WorkRail managed workflow sources store is corrupted.', {
+                suggestion: 'The managed sources file may need to be deleted and re-created. Check the ~/.workrail/data/managed-sources directory.',
+                details: { errorMessage: error.message },
+            });
+        default: {
+            const _exhaustive = error;
+            return (0, assert_never_js_1.assertNever)(_exhaustive);
+        }
+    }
+}
+async function handleV2ManageWorkflowSource(input, ctx) {
+    const guard = (0, types_js_1.requireV2Context)(ctx);
+    if (!guard.ok)
+        return guard.error;
+    const { managedSourceStore } = guard.ctx.v2;
+    if (!managedSourceStore) {
+        return (0, types_js_1.errNotRetryable)('PRECONDITION_FAILED', 'Managed workflow source store is not available.', {
+            suggestion: 'Ensure WorkRail v2 is fully initialized. The managedSourceStore dependency may not be wired in this environment.',
+        });
+    }
+    const operation = input.action === 'attach'
+        ? managedSourceStore.attach(input.path)
+        : managedSourceStore.detach(input.path);
+    const result = await operation;
+    if (result.isErr()) {
+        return mapManagedSourceErrorToToolError(result.error);
+    }
+    return (0, types_js_1.success)({ action: input.action, path: path_1.default.resolve(input.path) });
+}

package/dist/mcp/handlers/v2-workflow.js

@@ -1,7 +1,11 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleV2ListWorkflows = handleV2ListWorkflows;
 exports.handleV2InspectWorkflow = handleV2InspectWorkflow;
+const path_1 = __importDefault(require("path"));
 const neverthrow_1 = require("neverthrow");
 const types_js_1 = require("../types.js");
 const error_mapper_js_1 = require("../error-mapper.js");
@@ -29,7 +33,7 @@ async function handleV2ListWorkflows(input, ctx) {
         return rememberedRootRecordsResult;
     const rememberedRootRecords = rememberedRootRecordsResult;
     const { crypto, pinnedStore } = guard.ctx.v2;
-    const workflowReader = (0, request_workflow_reader_js_1.hasRequestWorkspaceSignal)({
+    const readerResult = (0, request_workflow_reader_js_1.hasRequestWorkspaceSignal)({
         workspacePath: input.workspacePath,
         resolvedRootUris: guard.ctx.v2.resolvedRootUris,
     })
@@ -39,7 +43,9 @@ async function handleV2ListWorkflows(input, ctx) {
             resolvedRootUris: guard.ctx.v2.resolvedRootUris,
             rememberedRootsStore: guard.ctx.v2.rememberedRootsStore,
         })
-        : ctx.workflowService;
+        : { reader: ctx.workflowService, stalePaths: [] };
+    const workflowReader = readerResult.reader;
+    const stalePaths = readerResult.stalePaths;
     return neverthrow_1.ResultAsync.fromPromise((0, with_timeout_js_1.withTimeout)(workflowReader.listWorkflowSummaries(), TIMEOUT_MS, 'list_workflows'), (err) => (0, error_mapper_js_1.mapUnknownErrorToToolError)(err))
         .andThen((summaries) => neverthrow_1.ResultAsync.combine(summaries.map((s) => neverthrow_1.ResultAsync.fromPromise(buildV2WorkflowListItem({
         summary: s,
@@ -48,11 +54,30 @@ async function handleV2ListWorkflows(input, ctx) {
         crypto,
         pinnedStore,
     }), (err) => (0, error_mapper_js_1.mapUnknownErrorToToolError)(err)))))
-        .map((compiled) => {
-        const payload = output_schemas_js_1.V2WorkflowListOutputSchema.parse({
-            workflows: compiled.sort((a, b) => a.workflowId.localeCompare(b.workflowId)),
+        .andThen((compiled) => {
+        if (!input.includeSources) {
+            const payload = output_schemas_js_1.V2WorkflowListOutputSchema.parse({
+                workflows: compiled.sort((a, b) => a.workflowId.localeCompare(b.workflowId)),
+                ...(stalePaths.length > 0 ? { staleRoots: [...stalePaths] } : {}),
+            });
+            return (0, neverthrow_1.okAsync)((0, types_js_1.success)(payload));
+        }
+        if (!(0, workflow_source_visibility_js_1.isCompositeWorkflowReader)(workflowReader)) {
+            const payload = output_schemas_js_1.V2WorkflowListOutputSchema.parse({
+                workflows: compiled.sort((a, b) => a.workflowId.localeCompare(b.workflowId)),
+                ...(stalePaths.length > 0 ? { staleRoots: [...stalePaths] } : {}),
+                sources: [],
+            });
+            return (0, neverthrow_1.okAsync)((0, types_js_1.success)(payload));
+        }
+        return neverthrow_1.ResultAsync.fromPromise((0, with_timeout_js_1.withTimeout)(buildSourceCatalog(workflowReader, rememberedRootRecords), TIMEOUT_MS, 'list_workflow_sources'), (err) => (0, error_mapper_js_1.mapUnknownErrorToToolError)(err)).map((sources) => {
+            const payload = output_schemas_js_1.V2WorkflowListOutputSchema.parse({
+                workflows: compiled.sort((a, b) => a.workflowId.localeCompare(b.workflowId)),
+                ...(stalePaths.length > 0 ? { staleRoots: [...stalePaths] } : {}),
+                sources,
+            });
+            return (0, types_js_1.success)(payload);
         });
-        return (0, types_js_1.success)(payload);
     })
         .match((result) => Promise.resolve(result), (err) => Promise.resolve(err));
 }
@@ -68,7 +93,7 @@ async function handleV2InspectWorkflow(input, ctx) {
         return rememberedRootRecordsResult;
     const rememberedRootRecords = rememberedRootRecordsResult;
     const { crypto, pinnedStore } = guard.ctx.v2;
-    const workflowReader = (0, request_workflow_reader_js_1.hasRequestWorkspaceSignal)({
+    const readerResult = (0, request_workflow_reader_js_1.hasRequestWorkspaceSignal)({
         workspacePath: input.workspacePath,
         resolvedRootUris: guard.ctx.v2.resolvedRootUris,
     })
@@ -78,7 +103,9 @@ async function handleV2InspectWorkflow(input, ctx) {
             resolvedRootUris: guard.ctx.v2.resolvedRootUris,
             rememberedRootsStore: guard.ctx.v2.rememberedRootsStore,
         })
-        : ctx.workflowService;
+        : { reader: ctx.workflowService, stalePaths: [] };
+    const workflowReader = readerResult.reader;
+    const stalePaths = readerResult.stalePaths;
     return neverthrow_1.ResultAsync.fromPromise((0, with_timeout_js_1.withTimeout)(workflowReader.getWorkflowById(input.workflowId), TIMEOUT_MS, 'inspect_workflow'), (err) => (0, error_mapper_js_1.mapUnknownErrorToToolError)(err))
         .andThen((workflow) => {
         if (!workflow) {
@@ -113,6 +140,7 @@ async function handleV2InspectWorkflow(input, ctx) {
                 mode: input.mode,
                 compiled: body,
                 ...(visibility ? { visibility } : {}),
+                ...(stalePaths.length > 0 ? { staleRoots: [...stalePaths] } : {}),
                 ...(references != null && references.length > 0 ? { references } : {}),
             });
             return (0, neverthrow_1.okAsync)((0, types_js_1.success)(payload));
@@ -181,3 +209,90 @@ async function buildV2WorkflowListItem(options) {
         visibility,
     };
 }
+async function buildSourceCatalog(workflowReader, rememberedRootRecords) {
+    const instances = workflowReader.getStorageInstances();
+    const seenIds = new Set();
+    const sourceEntryDataReversed = [];
+    for (let i = instances.length - 1; i >= 0; i--) {
+        const instance = instances[i];
+        const summaries = await instance.listWorkflowSummaries();
+        const allIds = summaries.map((s) => s.id);
+        const effectiveIds = allIds.filter((id) => !seenIds.has(id));
+        for (const id of allIds)
+            seenIds.add(id);
+        sourceEntryDataReversed.push({ source: instance.source, allIds, effectiveIds });
+    }
+    const sourceEntryData = sourceEntryDataReversed.reverse();
+    return sourceEntryData.map((data) => deriveSourceCatalogEntry({ ...data, rememberedRootRecords, sourceEntryData }));
+}
+function deriveSourceCatalogEntry(options) {
+    const { source, allIds, effectiveIds, rememberedRootRecords, sourceEntryData } = options;
+    const total = allIds.length;
+    const effective = effectiveIds.length;
+    const shadowed = total - effective;
+    const sourceKey = deriveSourceKey(source);
+    const displayName = deriveDisplayName(source);
+    switch (source.kind) {
+        case 'bundled':
+            return { sourceKey, category: 'built_in', source: { kind: source.kind, displayName }, sourceMode: 'built_in', effectiveWorkflowCount: effective, totalWorkflowCount: total, shadowedWorkflowCount: shadowed };
+        case 'user':
+            return { sourceKey, category: 'personal', source: { kind: source.kind, displayName }, sourceMode: 'personal', effectiveWorkflowCount: effective, totalWorkflowCount: total, shadowedWorkflowCount: shadowed };
+        case 'project': {
+            const thisIds = new Set(allIds);
+            const hasMigrationOverlap = sourceEntryData.some((e) => {
+                if (e.source === source || e.source.kind !== 'custom')
+                    return false;
+                const rootedSharing = deriveRootedSharingForPath(e.source.directoryPath, rememberedRootRecords);
+                return rootedSharing != null && e.allIds.some((id) => thisIds.has(id));
+            });
+            const migration = hasMigrationOverlap
+                ? { preferredSource: 'rooted_sharing', currentSource: 'legacy_project', reason: 'legacy_project_precedence', summary: 'Project-scoped ./workflows currently overrides rooted .workrail/workflows during migration. Prefer rooted sharing for new team-shared workflows.' }
+                : undefined;
+            return { sourceKey, category: 'legacy_project', source: { kind: source.kind, displayName }, sourceMode: 'legacy_project', effectiveWorkflowCount: effective, totalWorkflowCount: total, shadowedWorkflowCount: shadowed, ...(migration ? { migration } : {}) };
+        }
+        case 'custom': {
+            const rootedSharing = deriveRootedSharingForPath(source.directoryPath, rememberedRootRecords);
+            const category = rootedSharing ? 'rooted_sharing' : 'external';
+            const sourceMode = rootedSharing ? 'rooted_sharing' : 'live_directory';
+            return { sourceKey, category, source: { kind: source.kind, displayName }, sourceMode, effectiveWorkflowCount: effective, totalWorkflowCount: total, shadowedWorkflowCount: shadowed, ...(rootedSharing ? { rootedSharing } : {}) };
+        }
+        case 'git':
+        case 'remote':
+        case 'plugin':
+            return { sourceKey, category: 'external', source: { kind: source.kind, displayName }, sourceMode: 'live_directory', effectiveWorkflowCount: effective, totalWorkflowCount: total, shadowedWorkflowCount: shadowed };
+    }
+}
+function deriveSourceKey(source) {
+    switch (source.kind) {
+        case 'bundled': return 'built_in';
+        case 'user': return `user:${source.directoryPath}`;
+        case 'project': return `project:${source.directoryPath}`;
+        case 'custom': return `custom:${source.directoryPath}`;
+        case 'git': return `git:${source.repositoryUrl}`;
+        case 'remote': return `remote:${source.registryUrl}`;
+        case 'plugin': return `plugin:${source.pluginName}`;
+    }
+}
+function deriveDisplayName(source) {
+    switch (source.kind) {
+        case 'bundled': return 'Built-in';
+        case 'user': return 'User Library';
+        case 'project': return 'Project';
+        case 'custom': return source.label ?? path_1.default.basename(source.directoryPath);
+        case 'git': return source.repositoryUrl;
+        case 'remote': return source.registryUrl;
+        case 'plugin': return source.pluginName;
+    }
+}
+function deriveRootedSharingForPath(sourcePath, rememberedRoots) {
+    const resolved = path_1.default.resolve(sourcePath);
+    for (const record of rememberedRoots) {
+        const rootPath = path_1.default.resolve(record.path);
+        const relative = path_1.default.relative(rootPath, resolved);
+        const isUnderRoot = relative.length === 0 || (!relative.startsWith('..') && !path_1.default.isAbsolute(relative));
+        if (!isUnderRoot)
+            continue;
+        return { kind: 'remembered_root', rootPath, groupLabel: (0, workflow_source_visibility_js_1.deriveGroupLabel)(rootPath, resolved) };
+    }
+    return undefined;
+}