@exaudeus/workrail 3.16.0 → 3.17.0

package/dist/mcp/handler-factory.d.ts

@@ -2,6 +2,6 @@ import { z } from 'zod';
 import type { ToolContext, ToolResult } from './types.js';
 import type { PreValidateResult } from './validation/workflow-next-prevalidate.js';
 import type { WrappedToolHandler, McpCallToolResult } from './types/workflow-tool-edition.js';
-export declare function toMcpResult<T>(result: ToolResult<T>): McpCallToolResult;
+export declare function toMcpResult<T>(result: ToolResult<T>, ctx?: ToolContext): McpCallToolResult;
 export declare function createHandler<TInput extends z.ZodType, TOutput>(schema: TInput, handler: (input: z.infer<TInput>, ctx: ToolContext) => Promise<ToolResult<TOutput>>, shapeSchema?: z.ZodObject<z.ZodRawShape>, aliasMap?: Readonly<Record<string, string>>): WrappedToolHandler;
 export declare function createValidatingHandler<TInput extends z.ZodType, TOutput>(schema: TInput, preValidate: (args: unknown) => PreValidateResult, handler: (input: z.infer<TInput>, ctx: ToolContext) => Promise<ToolResult<TOutput>>, shapeSchema?: z.ZodObject<z.ZodRawShape>, aliasMap?: Readonly<Record<string, string>>): WrappedToolHandler;

package/dist/mcp/handler-factory.js

@@ -11,11 +11,12 @@ const v2_execution_helpers_js_1 = require("./handlers/v2-execution-helpers.js");
 const v2_response_formatter_js_1 = require("./v2-response-formatter.js");
 const render_envelope_js_1 = require("./render-envelope.js");
 const jsonResponsesOverride = process.env.WORKRAIL_JSON_RESPONSES === 'true';
-function toMcpResult(result) {
+function toMcpResult(result, ctx) {
     switch (result.type) {
         case 'success': {
+            const cleanResponseFormat = ctx?.featureFlags.isEnabled('cleanResponseFormat') ?? false;
             if (!jsonResponsesOverride) {
-                const formatted = (0, v2_response_formatter_js_1.formatV2ExecutionResponse)(result.data) ?? (0, v2_response_formatter_js_1.formatV2ResumeResponse)(result.data);
+                const formatted = (0, v2_response_formatter_js_1.formatV2ExecutionResponse)(result.data, cleanResponseFormat) ?? (0, v2_response_formatter_js_1.formatV2ResumeResponse)(result.data);
                 if (formatted !== null) {
                     const content = [{ type: 'text', text: formatted.primary }];
                     if (formatted.references != null) {
@@ -76,14 +77,14 @@ function createHandler(schema, handler, shapeSchema, aliasMap) {
                     message: e.message,
                 })),
                 ...patchedDetails,
-            }));
+            }), ctx);
         }
         try {
-            return toMcpResult(await handler(parseResult.data, ctx));
+            return toMcpResult(await handler(parseResult.data, ctx), ctx);
         }
         catch (err) {
             console.error('[WorkRail] Unhandled exception in tool handler:', err);
-            return toMcpResult((0, types_js_1.errNotRetryable)('INTERNAL_ERROR', 'WorkRail encountered an unexpected error. This is not caused by your input.', { suggestion: (0, v2_execution_helpers_js_1.internalSuggestion)('Retry the call.', 'WorkRail has an internal error.') }));
+            return toMcpResult((0, types_js_1.errNotRetryable)('INTERNAL_ERROR', 'WorkRail encountered an unexpected error. This is not caused by your input.', { suggestion: (0, v2_execution_helpers_js_1.internalSuggestion)('Retry the call.', 'WorkRail has an internal error.') }), ctx);
         }
     };
 }
@@ -109,9 +110,9 @@ function createValidatingHandler(schema, preValidate, handler, shapeSchema, alia
                     ...error,
                     details: boundedDetails,
                 };
-                return toMcpResult(boundedError);
+                return toMcpResult(boundedError, ctx);
             }
-            return toMcpResult(error);
+            return toMcpResult(error, ctx);
         }
         return innerHandler(normalizedArgs, ctx);
     };

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

@@ -2,6 +2,7 @@ import type { IWorkflowReader } from '../../../types/storage.js';
 import type { IFeatureFlagProvider } from '../../../config/feature-flags.js';
 import type { RememberedRootsStorePortV2 } from '../../../v2/ports/remembered-roots-store.port.js';
 import type { ManagedSourceRecordV2, ManagedSourceStorePortV2 } from '../../../v2/ports/managed-source-store.port.js';
+export declare function clearWalkCacheForTesting(): void;
 export interface RequestWorkflowReaderOptions {
     readonly featureFlags: IFeatureFlagProvider;
     readonly workspacePath?: string;

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

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.clearWalkCacheForTesting = clearWalkCacheForTesting;
 exports.hasRequestWorkspaceSignal = hasRequestWorkspaceSignal;
 exports.resolveRequestWorkspaceDirectory = resolveRequestWorkspaceDirectory;
 exports.toProjectWorkflowDirectory = toProjectWorkflowDirectory;
@@ -13,6 +14,27 @@ const path_1 = __importDefault(require("path"));
 const url_1 = require("url");
 const enhanced_multi_source_workflow_storage_js_1 = require("../../../infrastructure/storage/enhanced-multi-source-workflow-storage.js");
 const schema_validating_workflow_storage_js_1 = require("../../../infrastructure/storage/schema-validating-workflow-storage.js");
+const with_timeout_js_1 = require("./with-timeout.js");
+const SKIP_DIRS = new Set([
+    '.git', 'node_modules',
+    'build', 'dist', 'out', 'target',
+    '.gradle', '.gradle-cache', '.cache',
+    'DerivedData', 'Pods',
+    'vendor',
+    '__pycache__', '.venv', 'venv',
+    '.next', '.nuxt', '.turbo', '.parcel-cache',
+    '.claude', '.claude-worktrees', '.firebender',
+    'coverage', '.nyc_output',
+]);
+const MAX_WALK_DEPTH = 5;
+const WALK_CACHE_TTL_MS = 300000;
+const walkCache = new Map();
+const walkInFlight = new Map();
+function clearWalkCacheForTesting() {
+    walkCache.clear();
+    walkInFlight.clear();
+}
+const DISCOVERY_TIMEOUT_MS = 10000;
 function hasRequestWorkspaceSignal(options) {
     return Boolean(options.workspacePath) || (options.resolvedRootUris?.length ?? 0) > 0;
 }
@@ -34,18 +56,38 @@ function toProjectWorkflowDirectory(workspaceDirectory) {
         ? workspaceDirectory
         : path_1.default.join(workspaceDirectory, 'workflows');
 }
-async function discoverRootedWorkflowDirectories(roots) {
+function discoverRootedWorkflowDirectories(roots) {
+    const cacheKey = roots.map((r) => path_1.default.resolve(r)).sort().join('\0');
+    const now = Date.now();
+    const cached = walkCache.get(cacheKey);
+    if (cached && cached.expiresAt > now) {
+        return Promise.resolve(cached.result);
+    }
+    const inFlight = walkInFlight.get(cacheKey);
+    if (inFlight)
+        return inFlight;
+    const promise = _doWalk(cacheKey, roots, now);
+    walkInFlight.set(cacheKey, promise);
+    promise.then(() => walkInFlight.delete(cacheKey), () => walkInFlight.delete(cacheKey));
+    return promise;
+}
+async function _doWalk(cacheKey, roots, now) {
     const discoveredByPath = new Set();
     const discoveredPaths = [];
     const stalePaths = [];
-    for (const root of roots) {
-        const rootPath = path_1.default.resolve(root);
-        const result = await discoverWorkflowDirectoriesUnderRoot(rootPath);
-        if (result.stale) {
+    const resolvedRoots = roots.map((r) => path_1.default.resolve(r));
+    const rootResults = await Promise.allSettled(resolvedRoots.map((rootPath) => discoverWorkflowDirectoriesUnderRoot(rootPath)));
+    for (let i = 0; i < resolvedRoots.length; i++) {
+        const rootPath = resolvedRoots[i];
+        const rootResult = rootResults[i];
+        if (rootResult.status === 'rejected') {
+            throw rootResult.reason;
+        }
+        if (rootResult.value.stale) {
             stalePaths.push(rootPath);
             continue;
         }
-        for (const nextPath of result.discovered) {
+        for (const nextPath of rootResult.value.discovered) {
             const normalizedPath = path_1.default.resolve(nextPath);
             if (discoveredByPath.has(normalizedPath))
                 continue;
@@ -53,13 +95,22 @@ async function discoverRootedWorkflowDirectories(roots) {
             discoveredPaths.push(normalizedPath);
         }
     }
-    return { discovered: discoveredPaths, stale: stalePaths };
+    const result = { discovered: discoveredPaths, stale: stalePaths };
+    walkCache.set(cacheKey, { result, expiresAt: now + WALK_CACHE_TTL_MS });
+    return result;
 }
 async function createWorkflowReaderForRequest(options) {
     const workspaceDirectory = resolveRequestWorkspaceDirectory(options);
     const projectWorkflowDirectory = toProjectWorkflowDirectory(workspaceDirectory);
     const rememberedRoots = await listRememberedRoots(options.rememberedRootsStore);
-    const { discovered: rootedWorkflowDirectories, stale: stalePaths } = await discoverRootedWorkflowDirectories(rememberedRoots);
+    let discoveryResult;
+    try {
+        discoveryResult = await (0, with_timeout_js_1.withTimeout)(discoverRootedWorkflowDirectories(rememberedRoots), DISCOVERY_TIMEOUT_MS, 'workflow_root_discovery');
+    }
+    catch {
+        discoveryResult = { discovered: [], stale: [] };
+    }
+    const { discovered: rootedWorkflowDirectories, stale: stalePaths } = discoveryResult;
     const rootedCustomPaths = rootedWorkflowDirectories.filter((directory) => directory !== projectWorkflowDirectory);
     const { records: allManagedRecords, storeError: managedStoreError } = await listManagedSourceRecords(options.managedSourceStore);
     const envCustomPaths = parseWorkflowStoragePathEnv();
@@ -70,17 +121,30 @@ async function createWorkflowReaderForRequest(options) {
     const additionalManagedPaths = [];
     const activeManagedRecords = [];
     const staleManagedRecords = [];
+    const alreadyCovered = [];
+    const needsStatCheck = [];
     for (const record of allManagedRecords) {
         if (normalizedCustom.has(path_1.default.resolve(record.path))) {
-            activeManagedRecords.push(record);
-            continue;
-        }
-        if (await isDirectory(record.path)) {
-            additionalManagedPaths.push(record.path);
-            activeManagedRecords.push(record);
+            alreadyCovered.push(record);
         }
         else {
-            staleManagedRecords.push(record);
+            needsStatCheck.push(record);
+        }
+    }
+    activeManagedRecords.push(...alreadyCovered);
+    if (needsStatCheck.length > 0) {
+        const statResults = await (0, with_timeout_js_1.withTimeout)(Promise.allSettled(needsStatCheck.map((record) => isDirectory(record.path))), DISCOVERY_TIMEOUT_MS, 'managed_source_stat').catch(() => null);
+        for (let i = 0; i < needsStatCheck.length; i++) {
+            const record = needsStatCheck[i];
+            const result = statResults?.[i];
+            const isDir = result?.status === 'fulfilled' && result.value === true;
+            if (isDir) {
+                additionalManagedPaths.push(record.path);
+                activeManagedRecords.push(record);
+            }
+            else {
+                staleManagedRecords.push(record);
+            }
         }
     }
     const customPaths = [...rootedCustomPaths, ...additionalManagedPaths];
@@ -118,8 +182,8 @@ async function listRememberedRoots(rememberedRootsStore) {
         return [];
     const result = await rememberedRootsStore.listRoots();
     if (result.isErr()) {
-        const error = result.error;
-        throw new Error(`Failed to load remembered workflow roots: ${error.code}: ${error.message}`);
+        console.error(`[workrail] Failed to load remembered workflow roots: ${result.error.code}: ${result.error.message}`);
+        return [];
     }
     return result.value.map((root) => path_1.default.resolve(root));
 }
@@ -136,7 +200,7 @@ async function discoverWorkflowDirectoriesUnderRoot(rootPath) {
     }
     return { discovered: discoveredPaths, stale: false };
 }
-async function walkForRootedWorkflowDirectories(currentDirectory, discoveredPaths) {
+async function walkForRootedWorkflowDirectories(currentDirectory, discoveredPaths, depth = 0) {
     const entries = await promises_1.default.readdir(currentDirectory, { withFileTypes: true });
     const sortedEntries = [...entries].sort((a, b) => a.name.localeCompare(b.name));
     for (const entry of sortedEntries) {
@@ -152,14 +216,20 @@ async function walkForRootedWorkflowDirectories(currentDirectory, discoveredPath
             }
             continue;
         }
-        await walkForRootedWorkflowDirectories(entryPath, discoveredPaths).catch((err) => {
+        if (depth >= MAX_WALK_DEPTH) {
+            if (process.env['WORKRAIL_DEV'] === '1') {
+                console.error(`[workrail] walk depth limit (${MAX_WALK_DEPTH}) reached at: ${entryPath}`);
+            }
+            continue;
+        }
+        await walkForRootedWorkflowDirectories(entryPath, discoveredPaths, depth + 1).catch((err) => {
             if (err.code !== 'ENOENT')
                 throw err;
         });
     }
 }
 function shouldSkipDirectory(name) {
-    return name === '.git' || name === 'node_modules';
+    return SKIP_DIRS.has(name);
 }
 async function isDirectory(targetPath) {
     try {

package/dist/mcp/handlers/v2-execution/continue-advance.d.ts

@@ -28,4 +28,5 @@ export declare function handleAdvanceIntent(args: {
     readonly sha256: Sha256PortV2;
     readonly aliasStore: import('../../../v2/ports/token-alias-store.port.js').TokenAliasStorePortV2;
     readonly entropy: import('../../../v2/ports/random-entropy.port.js').RandomEntropyPortV2;
+    readonly cleanResponseFormat?: boolean;
 }): RA<z.infer<typeof V2ContinueWorkflowOutputSchema>, ContinueWorkflowError>;

package/dist/mcp/handlers/v2-execution/continue-advance.js

@@ -11,7 +11,7 @@ const advance_js_1 = require("./advance.js");
 const sorted_event_log_js_1 = require("../../../v2/durable-core/sorted-event-log.js");
 const session_index_js_1 = require("../../../v2/durable-core/session-index.js");
 function handleAdvanceIntent(args) {
-    const { input, sessionId, runId, nodeId, attemptId, workflowHashRef, truth, gate, sessionStore, snapshotStore, pinnedStore, tokenCodecPorts, idFactory, sha256, aliasStore, entropy } = args;
+    const { input, sessionId, runId, nodeId, attemptId, workflowHashRef, truth, gate, sessionStore, snapshotStore, pinnedStore, tokenCodecPorts, idFactory, sha256, aliasStore, entropy, cleanResponseFormat } = args;
     const dedupeKey = `advance_recorded:${sessionId}:${nodeId}:${attemptId}`;
     const preLockSortedResult = (0, sorted_event_log_js_1.asSortedEventLog)(truth.events);
     if (preLockSortedResult.isErr()) {
@@ -101,6 +101,7 @@ function handleAdvanceIntent(args) {
                 tokenCodecPorts,
                 aliasStore,
                 entropy,
+                cleanResponseFormat,
             });
         }
         return gate
@@ -198,6 +199,7 @@ function handleAdvanceIntent(args) {
                 tokenCodecPorts,
                 aliasStore,
                 entropy,
+                cleanResponseFormat,
             });
         });
     });

package/dist/mcp/handlers/v2-execution/continue-rehydrate.d.ts

@@ -27,4 +27,5 @@ export declare function handleRehydrateIntent(args: {
     readonly aliasStore: import('../../../v2/ports/token-alias-store.port.js').TokenAliasStorePortV2;
     readonly entropy: import('../../../v2/ports/random-entropy.port.js').RandomEntropyPortV2;
     readonly resolvedRootUris?: readonly string[];
+    readonly cleanResponseFormat?: boolean;
 }): RA<RehydrateResult, ContinueWorkflowError>;

package/dist/mcp/handlers/v2-execution/continue-rehydrate.js

@@ -20,7 +20,7 @@ const index_js_2 = require("./index.js");
 const step_content_envelope_js_1 = require("../../step-content-envelope.js");
 const assert_output_js_1 = require("../../assert-output.js");
 function handleRehydrateIntent(args) {
-    const { input, sessionId, runId, nodeId, workflowHashRef, truth, tokenCodecPorts, pinnedStore, snapshotStore, idFactory, aliasStore, entropy, resolvedRootUris } = args;
+    const { input, sessionId, runId, nodeId, workflowHashRef, truth, tokenCodecPorts, pinnedStore, snapshotStore, idFactory, aliasStore, entropy, resolvedRootUris, cleanResponseFormat } = args;
     const runStarted = truth.events.find((e) => e.kind === constants_js_1.EVENT_KIND.RUN_STARTED && e.scope.runId === String(runId));
     const workflowId = runStarted?.data.workflowId;
     if (!runStarted || typeof workflowId !== 'string' || workflowId.trim() === '') {
@@ -124,6 +124,7 @@ function handleRehydrateIntent(args) {
                     runId: (0, index_js_1.asRunId)(String(runId)),
                     nodeId: (0, index_js_1.asNodeId)(String(nodeId)),
                     rehydrateOnly: true,
+                    cleanResponseFormat,
                 });
                 if (metaRes.isErr()) {
                     return (0, neverthrow_1.errAsync)({

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

@@ -75,6 +75,7 @@ function loadAndRehydrate(args) {
         aliasStore: tokenAliasStore,
         entropy,
         resolvedRootUris: args.ctx.v2.resolvedRootUris,
+        cleanResponseFormat: args.ctx.featureFlags?.isEnabled('cleanResponseFormat') ?? false,
     }));
 }
 function executeContinueWorkflow(input, ctx) {
@@ -140,6 +141,7 @@ function executeContinueWorkflow(input, ctx) {
                     sha256,
                     aliasStore: tokenAliasStore,
                     entropy,
+                    cleanResponseFormat: ctx.featureFlags?.isEnabled('cleanResponseFormat') ?? false,
                 }))
                     .map((response) => ({ response }));
             });

package/dist/mcp/handlers/v2-execution/replay.d.ts

@@ -25,6 +25,7 @@ export declare function buildAdvancedReplayResponse(args: {
     readonly aliasStore: import('../../../v2/ports/token-alias-store.port.js').TokenAliasStorePortV2;
     readonly entropy: import('../../../v2/ports/random-entropy.port.js').RandomEntropyPortV2;
     readonly precomputedIndex?: import('../../../v2/durable-core/session-index.js').SessionIndex;
+    readonly cleanResponseFormat?: boolean;
 }): RA<z.infer<typeof V2ContinueWorkflowOutputSchema>, ContinueWorkflowError>;
 export declare function replayFromRecordedAdvance(args: {
     readonly recordedEvent: Extract<DomainEventV1, {
@@ -43,4 +44,5 @@ export declare function replayFromRecordedAdvance(args: {
     readonly aliasStore: import('../../../v2/ports/token-alias-store.port.js').TokenAliasStorePortV2;
     readonly entropy: import('../../../v2/ports/random-entropy.port.js').RandomEntropyPortV2;
     readonly precomputedIndex?: import('../../../v2/durable-core/session-index.js').SessionIndex;
+    readonly cleanResponseFormat?: boolean;
 }): RA<z.infer<typeof V2ContinueWorkflowOutputSchema>, ContinueWorkflowError>;

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

@@ -78,6 +78,7 @@ function buildAdvancedReplayResponse(args) {
                 nodeId: (0, index_js_1.asNodeId)(String(toNodeIdBranded)),
                 rehydrateOnly: false,
                 precomputedIndex: args.precomputedIndex,
+                cleanResponseFormat: args.cleanResponseFormat,
             });
             if (result.isErr()) {
                 return (0, neverthrow_1.errAsync)({ kind: 'prompt_render_failed', message: result.error.message });
@@ -116,6 +117,7 @@ function buildAdvancedReplayResponse(args) {
             nodeId: (0, index_js_1.asNodeId)(String(toNodeIdBranded)),
             rehydrateOnly: false,
             precomputedIndex: args.precomputedIndex,
+            cleanResponseFormat: args.cleanResponseFormat,
         });
         if (result.isErr()) {
             return (0, neverthrow_1.errAsync)({ kind: 'prompt_render_failed', message: result.error.message });
@@ -208,6 +210,7 @@ function replayFromRecordedAdvance(args) {
             aliasStore,
             entropy,
             precomputedIndex: args.precomputedIndex,
+            cleanResponseFormat: args.cleanResponseFormat,
         });
     });
 }

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

@@ -26,6 +26,8 @@ const request_workflow_reader_js_1 = require("../shared/request-workflow-reader.
 const step_content_envelope_js_1 = require("../../step-content-envelope.js");
 const v2_workspace_resolution_js_2 = require("../v2-workspace-resolution.js");
 const v2_reference_resolver_js_1 = require("../v2-reference-resolver.js");
+const with_timeout_js_1 = require("../shared/with-timeout.js");
+const REFERENCE_RESOLUTION_TIMEOUT_MS = 5000;
 function loadAndPinWorkflow(args) {
     const { workflowId, workflowReader, crypto, pinnedStore, validationPipelineDeps, workspacePath, resolvedRootUris } = args;
     return neverthrow_1.ResultAsync.fromPromise(workflowReader.getWorkflowById(workflowId), (e) => ({
@@ -77,7 +79,7 @@ function loadAndPinWorkflow(args) {
                 }
                 return pinnedStore.put(workflowHash, enrichedCompiled)
                     .mapErr((cause) => ({ kind: 'pinned_workflow_store_failed', cause }))
-                    .andThen(() => pinnedStore.get(workflowHash).mapErr((cause) => ({ kind: 'pinned_workflow_store_failed', cause })));
+                    .map(() => enrichedCompiled);
             })
                 .andThen((pinned) => {
                 if (!pinned || pinned.sourceKind !== 'v1_pinned' || !(0, workflow_definition_js_1.hasWorkflowDefinitionShape)(pinned.definition)) {
@@ -239,10 +241,11 @@ function executeStartWorkflow(input, ctx) {
             workspacePath: input.workspacePath,
             resolvedRootUris: ctx.v2.resolvedRootUris,
             rememberedRootsStore: ctx.v2.rememberedRootsStore,
+            managedSourceStore: ctx.v2.managedSourceStore,
         }), (err) => ({
             kind: 'precondition_failed',
             message: `Failed to initialize workflow reader: ${String(err)}`,
-        })).map(({ reader, stalePaths }) => ({
+        })).map(({ reader, stalePaths, managedStoreError }) => ({
             workflowReader: {
                 getWorkflowById: async (workflowId) => {
                     const requestResult = await reader.getWorkflowById(workflowId);
@@ -252,21 +255,24 @@ function executeStartWorkflow(input, ctx) {
                 },
             },
             stalePaths,
+            managedStoreError,
         }))
-        : (0, neverthrow_1.okAsync)({ workflowReader: ctx.workflowService, stalePaths: [] });
-    return readerRA.andThen(({ workflowReader, stalePaths }) => loadAndPinWorkflow({
-        workflowId: input.workflowId,
-        workflowReader,
-        crypto,
-        pinnedStore,
-        validationPipelineDeps,
-        workspacePath: input.workspacePath,
-        resolvedRootUris: ctx.v2.resolvedRootUris,
-    })
-        .andThen(({ workflow, firstStep, workflowHash, pinnedWorkflow, resolvedReferences }) => {
-        const anchorsRA = (0, v2_workspace_resolution_js_1.resolveWorkspaceAnchors)(ctx.v2, input.workspacePath)
-            .map((anchors) => (0, observation_builder_js_1.anchorsToObservations)(anchors));
-        return anchorsRA.andThen((observations) => {
+        : (0, neverthrow_1.okAsync)({ workflowReader: ctx.workflowService, stalePaths: [], managedStoreError: undefined });
+    const anchorsRA = (0, v2_workspace_resolution_js_1.resolveWorkspaceAnchors)(ctx.v2, input.workspacePath)
+        .map((anchors) => (0, observation_builder_js_1.anchorsToObservations)(anchors))
+        .mapErr((x) => x);
+    return readerRA.andThen(({ workflowReader, stalePaths, managedStoreError }) => {
+        const pinnedRA = loadAndPinWorkflow({
+            workflowId: input.workflowId,
+            workflowReader,
+            crypto,
+            pinnedStore,
+            validationPipelineDeps,
+            workspacePath: input.workspacePath,
+            resolvedRootUris: ctx.v2.resolvedRootUris,
+        });
+        return neverthrow_1.ResultAsync.combine([pinnedRA, anchorsRA])
+            .andThen(([{ workflow, firstStep, workflowHash, pinnedWorkflow, resolvedReferences }, observations]) => {
             const sessionId = idFactory.mintSessionId();
             const runId = idFactory.mintRunId();
             const nodeId = idFactory.mintNodeId();
@@ -314,11 +320,11 @@ function executeStartWorkflow(input, ctx) {
                     snapshotPins: [{ snapshotRef, eventIndex: 2, createdByEventId: events[2].eventId }],
                 }, emptyTruth))
                     .mapErr((cause) => ({ kind: 'session_append_failed', cause }))
-                    .map(() => ({ workflow, firstStep, workflowHash, pinnedWorkflow, resolvedReferences, sessionId, runId, nodeId }));
+                    .map(() => ({ workflow, firstStep, workflowHash, pinnedWorkflow, resolvedReferences, sessionId, runId, nodeId, stalePaths, managedStoreError }));
             });
         });
     })
-        .andThen(({ pinnedWorkflow, firstStep, workflowHash, sessionId, runId, nodeId, resolvedReferences }) => {
+        .andThen(({ pinnedWorkflow, firstStep, workflowHash, sessionId, runId, nodeId, resolvedReferences, stalePaths, managedStoreError }) => {
         const wfRefRes = (0, workflow_hash_ref_js_1.deriveWorkflowHashRef)(workflowHash);
         if (wfRefRes.isErr()) {
             return (0, neverthrow_1.errAsync)({
@@ -346,6 +352,7 @@ function executeStartWorkflow(input, ctx) {
                 runId: (0, index_js_1.asRunId)(String(runId)),
                 nodeId: (0, index_js_1.asNodeId)(String(nodeId)),
                 rehydrateOnly: false,
+                cleanResponseFormat: ctx.featureFlags?.isEnabled('cleanResponseFormat') ?? false,
             });
             if (metaResult.isErr()) {
                 return (0, neverthrow_1.errAsync)({
@@ -361,6 +368,9 @@ function executeStartWorkflow(input, ctx) {
                 meta,
                 references: resolvedReferences,
             });
+            const startWarnings = managedStoreError !== undefined
+                ? [`Managed workflow source store was temporarily unavailable (${managedStoreError}). Managed sources were not loaded.`]
+                : undefined;
             const parsed = {
                 continueToken: tokens.continueToken,
                 checkpointToken: tokens.checkpointToken,
@@ -370,16 +380,34 @@ function executeStartWorkflow(input, ctx) {
                 nextIntent,
                 nextCall: (0, index_js_2.buildNextCall)({ continueToken: tokens.continueToken, isComplete: false, pending }),
                 ...(stalePaths.length > 0 ? { staleRoots: [...stalePaths] } : {}),
+                ...(startWarnings !== undefined ? { warnings: startWarnings } : {}),
             };
             return (0, neverthrow_1.okAsync)({ response: parsed, contentEnvelope });
         });
-    }));
+    });
 }
 function enrichPinnedSnapshotWithResolvedReferences(snapshot, references, workspacePath) {
     if (references.length === 0) {
         return (0, neverthrow_1.okAsync)({ snapshot, resolvedReferences: [] });
     }
-    return neverthrow_1.ResultAsync.fromPromise((0, v2_reference_resolver_js_1.resolveWorkflowReferences)(references, workspacePath), () => ({ kind: 'reference_resolution_failed' })).map((result) => {
+    const allUnresolved = references.map((ref) => ({
+        id: ref.id,
+        title: ref.title,
+        source: ref.source,
+        purpose: ref.purpose,
+        authoritative: ref.authoritative,
+        resolveFrom: (ref.resolveFrom ?? 'workspace'),
+        status: 'unresolved',
+    }));
+    const resolutionPromise = (0, with_timeout_js_1.withTimeout)((0, v2_reference_resolver_js_1.resolveWorkflowReferences)(references, workspacePath), REFERENCE_RESOLUTION_TIMEOUT_MS, 'reference_resolution').catch(() => null);
+    return neverthrow_1.ResultAsync.fromPromise(resolutionPromise, () => ({ kind: 'reference_resolution_failed' })).map((result) => {
+        if (result === null) {
+            console.warn('[workrail:reference-resolution] timed out; all references marked unresolved');
+            return {
+                snapshot: { ...snapshot, resolvedReferences: [...allUnresolved] },
+                resolvedReferences: allUnresolved,
+            };
+        }
         for (const warning of result.warnings) {
             console.warn(`[workrail:reference-resolution] ${warning.message}`);
         }

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

@@ -15,6 +15,7 @@ const neverthrow_1 = require("neverthrow");
 const types_js_1 = require("../types.js");
 const error_mapper_js_1 = require("../error-mapper.js");
 const v2_execution_helpers_js_1 = require("./v2-execution-helpers.js");
+const assert_never_js_1 = require("../../runtime/assert-never.js");
 const v1_to_v2_shim_js_1 = require("../../v2/read-only/v1-to-v2-shim.js");
 const hashing_js_1 = require("../../v2/durable-core/canonical/hashing.js");
 const TIMEOUT_MS = 30000;
@@ -35,8 +36,7 @@ function readCurrentSpecVersion() {
     }
 }
 const CURRENT_SPEC_VERSION = readCurrentSpecVersion();
-const DEV_STALENESS = process.env['WORKRAIL_DEV_STALENESS'] === '1';
-function shouldShowStaleness(category, devMode = DEV_STALENESS) {
+function shouldShowStaleness(category, devMode = (0, dev_mode_js_1.isDevMode)()) {
     if (devMode)
         return true;
     return category === 'personal' || category === 'rooted_sharing' || category === 'external';
@@ -96,6 +96,7 @@ function computeWorkflowStaleness(stamp, currentVersion) {
         specVersionAtLastReview: stamp,
     };
 }
+const dev_mode_js_1 = require("../dev-mode.js");
 const with_timeout_js_1 = require("./shared/with-timeout.js");
 const request_workflow_reader_js_1 = require("./shared/request-workflow-reader.js");
 const remembered_roots_js_1 = require("./shared/remembered-roots.js");
@@ -443,6 +444,7 @@ function deriveSourceCatalogEntry(options) {
         case 'plugin':
             return { sourceKey, category: 'external', source: { kind: source.kind, displayName }, sourceMode: 'live_directory', effectiveWorkflowCount: effective, totalWorkflowCount: total, shadowedWorkflowCount: shadowed };
     }
+    (0, assert_never_js_1.assertNever)(source);
 }
 function deriveSourceKey(source) {
     switch (source.kind) {

package/dist/mcp/output-schemas.d.ts

@@ -2443,6 +2443,7 @@ export declare const V2StartWorkflowOutputSchema: z.ZodEffects<z.ZodObject<{
         tool: "continue_workflow";
     }>>;
     staleRoots: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
     pending: {
         stepId: string;
@@ -2462,6 +2463,7 @@ export declare const V2StartWorkflowOutputSchema: z.ZodEffects<z.ZodObject<{
         };
         tool: "continue_workflow";
     } | null;
+    warnings?: string[] | undefined;
     continueToken?: string | undefined;
     checkpointToken?: string | undefined;
     staleRoots?: string[] | undefined;
@@ -2484,6 +2486,7 @@ export declare const V2StartWorkflowOutputSchema: z.ZodEffects<z.ZodObject<{
         };
         tool: "continue_workflow";
     } | null;
+    warnings?: string[] | undefined;
     continueToken?: string | undefined;
     checkpointToken?: string | undefined;
     staleRoots?: string[] | undefined;
@@ -2506,6 +2509,7 @@ export declare const V2StartWorkflowOutputSchema: z.ZodEffects<z.ZodObject<{
         };
         tool: "continue_workflow";
     } | null;
+    warnings?: string[] | undefined;
     continueToken?: string | undefined;
     checkpointToken?: string | undefined;
     staleRoots?: string[] | undefined;
@@ -2528,6 +2532,7 @@ export declare const V2StartWorkflowOutputSchema: z.ZodEffects<z.ZodObject<{
         };
         tool: "continue_workflow";
     } | null;
+    warnings?: string[] | undefined;
     continueToken?: string | undefined;
     checkpointToken?: string | undefined;
     staleRoots?: string[] | undefined;

package/dist/mcp/output-schemas.js

@@ -392,6 +392,8 @@ exports.V2StartWorkflowOutputSchema = zod_1.z.object({
     staleRoots: zod_1.z.array(zod_1.z.string()).optional().describe('Workflow source paths that were inaccessible during discovery (missing remembered roots or missing managed source directories). ' +
         'Workflows from these paths were not included in this response. ' +
         'These paths will be rechecked on the next call.'),
+    warnings: zod_1.z.array(zod_1.z.string()).optional().describe('Non-fatal warnings about workflow source availability. ' +
+        'The workflow was started successfully but some sources may have been unavailable (e.g., managed source store temporarily inaccessible).'),
 }).refine((data) => (data.pending ? data.continueToken != null : true), { message: 'continueToken is required when a pending step exists' });
 exports.CreateSessionOutputSchema = zod_1.z.object({
     sessionId: zod_1.z.string().min(1),

package/dist/mcp/server.js

@@ -217,10 +217,11 @@ async function composeServer() {
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools,
     }));
-    const timingSink = dev_mode_js_1.DEV_MODE
+    const devMode = (0, dev_mode_js_1.isDevMode)();
+    const timingSink = devMode
         ? (0, tool_call_timing_js_1.composeSinks)((0, tool_call_timing_js_1.createRingBufferSink)(timingRingBuffer), (0, tool_call_timing_js_1.createDevPerfSink)())
         : (0, tool_call_timing_js_1.createRingBufferSink)(timingRingBuffer);
-    if (dev_mode_js_1.DEV_MODE) {
+    if (devMode) {
         console.error('[PerfTrace] WORKRAIL_DEV=1 -- tool call timing active');
     }
     server.setRequestHandler(CallToolRequestSchema, async (request) => {

package/dist/mcp/v2-response-formatter.d.ts

@@ -8,5 +8,5 @@ export interface FormattedResponse {
     readonly references?: FormattedReferences;
     readonly supplements?: readonly FormattedSupplement[];
 }
-export declare function formatV2ExecutionResponse(data: unknown): FormattedResponse | null;
+export declare function formatV2ExecutionResponse(data: unknown, cleanResponseFormat: boolean): FormattedResponse | null;
 export declare function formatV2ResumeResponse(data: unknown): FormattedResponse | null;

package/dist/mcp/v2-response-formatter.js

@@ -4,7 +4,6 @@ exports.formatV2ExecutionResponse = formatV2ExecutionResponse;
 exports.formatV2ResumeResponse = formatV2ResumeResponse;
 const render_envelope_js_1 = require("./render-envelope.js");
 const response_supplements_js_1 = require("./response-supplements.js");
-const env_flags_js_1 = require("../env-flags.js");
 function isV2ExecutionResponse(data) {
     if (typeof data !== 'object' || data === null)
         return false;
@@ -348,11 +347,11 @@ function renderReferencesSection(contentEnvelope, lifecycle) {
             return null;
     }
 }
-function formatV2ExecutionResponse(data) {
+function formatV2ExecutionResponse(data, cleanResponseFormat) {
     const renderInput = deriveRenderInput(data);
     if (!renderInput)
         return null;
-    const cleanFormat = env_flags_js_1.CLEAN_RESPONSE_FORMAT;
+    const cleanFormat = cleanResponseFormat;
     const { response, lifecycle, contentEnvelope } = renderInput;
     const references = renderReferencesSection(contentEnvelope, lifecycle);
     if (cleanFormat) {