@exaudeus/workrail 3.7.2 → 3.7.4

package/dist/engine/engine-factory.js

@@ -240,7 +240,8 @@ async function createWorkRailEngine(config = {}) {
     engineActive = true;
     const engine = {
         async startWorkflow(workflowId) {
-            const result = await (0, start_js_1.executeStartWorkflow)({ workflowId }, v2Ctx);
+            const workspacePath = process.cwd();
+            const result = await (0, start_js_1.executeStartWorkflow)({ workflowId, workspacePath }, v2Ctx);
             if (result.isErr()) {
                 return (0, types_js_1.engineErr)(mapStartError(result.error));
             }
@@ -248,9 +249,11 @@ async function createWorkRailEngine(config = {}) {
         },
         async continueWorkflow(stateToken, ackToken, output, context) {
             const intent = ackToken ? 'advance' : 'rehydrate';
+            const workspacePath = process.cwd();
             const input = {
                 continueToken: (0, types_js_1.unwrapToken)(stateToken),
                 intent: intent,
+                ...(intent === 'rehydrate' ? { workspacePath } : {}),
                 ...(output ? {
                     output: {
                         notesMarkdown: output.notesMarkdown,

package/dist/manifest.json

@@ -438,8 +438,8 @@
       "bytes": 213
     },
     "engine/engine-factory.js": {
-      "sha256": "07d88be2ab8488615871ae363b9db4fc23caebba8231c8c2aaa2f97da2b18fdd",
-      "bytes": 13658
+      "sha256": "5461827b470642059198115f5248e97463db9bfb012f63971a4c7f69acda5b7c",
+      "bytes": 13841
     },
     "engine/index.d.ts": {
       "sha256": "91e12882c565e96a9809fdf43a0dc0a77fdffdfd562aaf43d2e86e6590ed0b16",
@@ -838,8 +838,8 @@
       "bytes": 3422
     },
     "mcp/handlers/v2-execution/start.js": {
-      "sha256": "593edf798bb1d2d0011ec81e4f170e4f4003b978cd9900fd785b583d15cd1085",
-      "bytes": 18014
+      "sha256": "e572eb50c6a0a30aa138620f32b04702727f07ce2570c29022d1027981c4bcef",
+      "bytes": 18496
     },
     "mcp/handlers/v2-reference-resolver.d.ts": {
       "sha256": "0b1d2640306b6a0c1067ca66bb20e6ec35d291b33dc328a78d5bfa8006394234",
@@ -862,8 +862,8 @@
       "bytes": 471
     },
     "mcp/handlers/v2-resume.js": {
-      "sha256": "780e4611d4fb7d7f7fac8cddf576ada1e9ba752f167a678ebd03d94ee518e298",
-      "bytes": 3828
+      "sha256": "536ba5db0c8fedf8a55c63a59eae4da5ad1cc793e4abf137a5ac9536e6514f68",
+      "bytes": 4140
     },
     "mcp/handlers/v2-state-conversion.d.ts": {
       "sha256": "94bd06904ef58dd210ff17ffb75c2492beea8937eb06d99749e5d860c0e0d96b",
@@ -914,12 +914,12 @@
       "bytes": 7991
     },
     "mcp/output-schemas.d.ts": {
-      "sha256": "b33bd6e889811ee4de7bd3b4b4fd6d52042cb7a6bdd23c8bd38baa42775e39c3",
-      "bytes": 52320
+      "sha256": "191d696fd1c8d7dc8f1908c903f84117ceaed6c0aa323fb7606dd3566d739689",
+      "bytes": 53246
     },
     "mcp/output-schemas.js": {
-      "sha256": "ba7dda4faec5a8bc1e497b41966b5033ab2930c9cae7b46e85ea1d25b39f79fa",
-      "bytes": 13715
+      "sha256": "28aa9b75ef6c21522b458bd4d05c55e28673510356f8f7e56eb1304544d35132",
+      "bytes": 14384
     },
     "mcp/render-envelope.d.ts": {
       "sha256": "22e83e1aba52968a7136cf289125a217b5f462a5a66a1eebe4669006e3326fdb",
@@ -1062,8 +1062,8 @@
       "bytes": 527
     },
     "mcp/v2-response-formatter.js": {
-      "sha256": "f8a8cb5c1fe1b081eca9228a09732dde7247aaf396ff14556cc721c66eee5ab8",
-      "bytes": 21118
+      "sha256": "308cc7c1fedd491f5d38607869d4b4e1196bfcf450835a53d52154827b323e23",
+      "bytes": 22402
     },
     "mcp/v2/tool-registry.d.ts": {
       "sha256": "d4d4927728c3cab1c014661d499dd0119538371bc6c5e821a4cd31df7abebedf",
@@ -1074,12 +1074,12 @@
       "bytes": 3276
     },
     "mcp/v2/tools.d.ts": {
-      "sha256": "89fff4db9e2b8f734d7453801fbc404a1518fccafce2a942af6656a6cdc2dc1e",
-      "bytes": 7228
+      "sha256": "93f1eac69e9d2be8ca354d714fbc64e3cea0e235e6669847677071d83a66450f",
+      "bytes": 7288
     },
     "mcp/v2/tools.js": {
-      "sha256": "c8bfc63a04911d44f13e62c0d9357dacf62ec437dd21f5b6f09c289a973687cb",
-      "bytes": 9406
+      "sha256": "2b5d12d4de385ca8c530532d12467f113d58a09a808fe075896d2b1c0caa52ae",
+      "bytes": 10071
     },
     "mcp/validation/bounded-json.d.ts": {
       "sha256": "82203ac6123d5c6989606c3b5405aaea99ab829c8958835f9ae3ba45b8bc8fd5",
@@ -1150,8 +1150,8 @@
       "bytes": 1863
     },
     "mcp/workflow-protocol-contracts.js": {
-      "sha256": "8da5f9dfb6f87ec12de5f6e925ae25b022a91432c430738bff1ba14fafeb03fb",
-      "bytes": 13357
+      "sha256": "250fb814372bbf75a4cff9adc2d257da4cf0f4f480dac263860e74ebdd405246",
+      "bytes": 13981
     },
     "mcp/workflow-tool-edition-selector.d.ts": {
       "sha256": "75194908a89aaf7dc48fb661aea099827e7032ec76daf8f2de91bd59d46764ef",
@@ -2118,8 +2118,8 @@
       "bytes": 1136
     },
     "v2/infra/local/session-summary-provider/index.js": {
-      "sha256": "93ca7df8ae1ae5e29c29470a6fb947e05b2def481c2b3d8decf4a5dbe8fd8e1c",
-      "bytes": 7611
+      "sha256": "504d432a35b3ceb75697c00b5db1576570b38c1415304f903ba77d0dfed04ce7",
+      "bytes": 10452
     },
     "v2/infra/local/sha256/index.d.ts": {
       "sha256": "8a727b7e54a38275ca6f9f1b8730f97cfc0a212df035df1bdc58e716e6824230",
@@ -2166,8 +2166,8 @@
       "bytes": 537
     },
     "v2/infra/local/workspace-anchor/index.js": {
-      "sha256": "a0fe032a9205606c6d592221f1300a3113c7d0cb3e126e458fef3dc8fa6e823c",
-      "bytes": 2272
+      "sha256": "d76172ecbe3457760abc0b6f0032eb4089758fb3c9ed473ba0f134ac57d37c1a",
+      "bytes": 2993
     },
     "v2/ports/base32.port.d.ts": {
       "sha256": "64aa2f2003a552917cbf71474472fc5e4afffaa29577204bbcbe5ffa989ceb82",
@@ -2386,12 +2386,12 @@
       "bytes": 732
     },
     "v2/projections/resume-ranking.d.ts": {
-      "sha256": "5f15f10b632b8e771c74e1f3823616f761be4142493d1142176583e6495528b2",
-      "bytes": 3531
+      "sha256": "b1d9e7d6fb3e59ced42f7c2e5fd9d8f9a18308aa6f4411a8aabf5dc174aa8dad",
+      "bytes": 3960
     },
     "v2/projections/resume-ranking.js": {
-      "sha256": "b9d48c8e08ae8b794771b44fc592158422e832ff64633817fa11093f64282715",
-      "bytes": 6782
+      "sha256": "1b256c992ded9ec52150b229799716d118ca2a3659a0cc523e727cde2ebf7b0c",
+      "bytes": 13660
     },
     "v2/projections/run-context.d.ts": {
       "sha256": "a4d57470a435ac9860f60b3244d1b828853995027cd510d8da42762d21b2a687",

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

@@ -212,15 +212,24 @@ function mintStartTokens(args) {
 }
 function executeStartWorkflow(input, ctx) {
     const { gate, sessionStore, snapshotStore, pinnedStore, crypto, tokenCodecPorts, idFactory, validationPipelineDeps, tokenAliasStore, entropy } = ctx.v2;
-    const workflowReader = (0, request_workflow_reader_js_1.hasRequestWorkspaceSignal)({
+    const shouldUseRequestReader = ctx.featureFlags != null && (0, request_workflow_reader_js_1.hasRequestWorkspaceSignal)({
         workspacePath: input.workspacePath,
         resolvedRootUris: ctx.v2.resolvedRootUris,
-    })
-        ? (0, request_workflow_reader_js_1.createWorkflowReaderForRequest)({
-            featureFlags: ctx.featureFlags,
-            workspacePath: input.workspacePath,
-            resolvedRootUris: ctx.v2.resolvedRootUris,
-        })
+    });
+    const workflowReader = shouldUseRequestReader
+        ? {
+            getWorkflowById: async (workflowId) => {
+                const requestReader = (0, request_workflow_reader_js_1.createWorkflowReaderForRequest)({
+                    featureFlags: ctx.featureFlags,
+                    workspacePath: input.workspacePath,
+                    resolvedRootUris: ctx.v2.resolvedRootUris,
+                });
+                const requestResult = await requestReader.getWorkflowById(workflowId);
+                if (requestResult != null)
+                    return requestResult;
+                return ctx.workflowService.getWorkflowById(workflowId);
+            },
+        }
         : ctx.workflowService;
     return loadAndPinWorkflow({
         workflowId: input.workflowId,

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

@@ -24,6 +24,8 @@ async function handleV2ResumeSession(input, ctx) {
     const query = {
         gitHeadSha: input.gitHeadSha ?? anchorValue(anchors, 'git_head_sha'),
         gitBranch: input.gitBranch ?? anchorValue(anchors, 'git_branch'),
+        repoRootHash: anchorValue(anchors, 'repo_root_hash'),
+        sameWorkspaceOnly: input.sameWorkspaceOnly,
         freeTextQuery: input.query,
         runId: input.runId,
         sessionId: input.sessionId,
@@ -74,9 +76,13 @@ function mintCandidateTokens(candidates, ports) {
             sessionId: candidate.sessionId,
             runId: candidate.runId,
             workflowId: candidate.workflowId,
+            sessionTitle: candidate.sessionTitle,
+            gitBranch: candidate.gitBranch,
             resumeToken: resumeTokenRes.value,
             snippet: candidate.snippet,
             whyMatched: [...candidate.whyMatched],
+            confidence: candidate.confidence,
+            matchExplanation: candidate.matchExplanation,
             pendingStepId: candidate.pendingStepId,
             isComplete: candidate.isComplete,
             lastModifiedMs: candidate.lastModifiedMs,

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

@@ -1160,12 +1160,16 @@ export declare const V2ResumeSessionOutputSchema: z.ZodObject<{
         sessionId: z.ZodString;
         runId: z.ZodString;
         workflowId: z.ZodString;
+        sessionTitle: z.ZodNullable<z.ZodString>;
+        gitBranch: z.ZodNullable<z.ZodString>;
         resumeToken: z.ZodString;
         snippet: z.ZodString;
+        confidence: z.ZodEnum<["strong", "medium", "weak"]>;
+        matchExplanation: z.ZodString;
         pendingStepId: z.ZodNullable<z.ZodString>;
         isComplete: z.ZodBoolean;
         lastModifiedMs: z.ZodNullable<z.ZodNumber>;
-        whyMatched: z.ZodArray<z.ZodEnum<["matched_exact_id", "matched_head_sha", "matched_branch", "matched_notes", "matched_notes_partial", "matched_workflow_id", "recency_fallback"]>, "many">;
+        whyMatched: z.ZodArray<z.ZodEnum<["matched_exact_id", "matched_notes", "matched_notes_partial", "matched_workflow_id", "matched_head_sha", "matched_branch", "matched_repo_root", "recency_fallback"]>, "many">;
         nextCall: z.ZodObject<{
             tool: z.ZodLiteral<"continue_workflow">;
             params: z.ZodObject<{
@@ -1192,9 +1196,11 @@ export declare const V2ResumeSessionOutputSchema: z.ZodObject<{
             tool: "continue_workflow";
         }>;
     }, "strip", z.ZodTypeAny, {
+        confidence: "strong" | "weak" | "medium";
         workflowId: string;
         runId: string;
         sessionId: string;
+        gitBranch: string | null;
         isComplete: boolean;
         nextCall: {
             params: {
@@ -1203,15 +1209,19 @@ export declare const V2ResumeSessionOutputSchema: z.ZodObject<{
             };
             tool: "continue_workflow";
         };
+        sessionTitle: string | null;
         resumeToken: string;
         snippet: string;
+        matchExplanation: string;
         pendingStepId: string | null;
         lastModifiedMs: number | null;
-        whyMatched: ("matched_exact_id" | "matched_head_sha" | "matched_branch" | "matched_notes" | "matched_notes_partial" | "matched_workflow_id" | "recency_fallback")[];
+        whyMatched: ("matched_exact_id" | "matched_notes" | "matched_notes_partial" | "matched_workflow_id" | "matched_head_sha" | "matched_branch" | "matched_repo_root" | "recency_fallback")[];
     }, {
+        confidence: "strong" | "weak" | "medium";
         workflowId: string;
         runId: string;
         sessionId: string;
+        gitBranch: string | null;
         isComplete: boolean;
         nextCall: {
             params: {
@@ -1220,18 +1230,22 @@ export declare const V2ResumeSessionOutputSchema: z.ZodObject<{
             };
             tool: "continue_workflow";
         };
+        sessionTitle: string | null;
         resumeToken: string;
         snippet: string;
+        matchExplanation: string;
         pendingStepId: string | null;
         lastModifiedMs: number | null;
-        whyMatched: ("matched_exact_id" | "matched_head_sha" | "matched_branch" | "matched_notes" | "matched_notes_partial" | "matched_workflow_id" | "recency_fallback")[];
+        whyMatched: ("matched_exact_id" | "matched_notes" | "matched_notes_partial" | "matched_workflow_id" | "matched_head_sha" | "matched_branch" | "matched_repo_root" | "recency_fallback")[];
     }>, "many">;
     totalEligible: z.ZodNumber;
 }, "strip", z.ZodTypeAny, {
     candidates: {
+        confidence: "strong" | "weak" | "medium";
         workflowId: string;
         runId: string;
         sessionId: string;
+        gitBranch: string | null;
         isComplete: boolean;
         nextCall: {
             params: {
@@ -1240,18 +1254,22 @@ export declare const V2ResumeSessionOutputSchema: z.ZodObject<{
             };
             tool: "continue_workflow";
         };
+        sessionTitle: string | null;
         resumeToken: string;
         snippet: string;
+        matchExplanation: string;
         pendingStepId: string | null;
         lastModifiedMs: number | null;
-        whyMatched: ("matched_exact_id" | "matched_head_sha" | "matched_branch" | "matched_notes" | "matched_notes_partial" | "matched_workflow_id" | "recency_fallback")[];
+        whyMatched: ("matched_exact_id" | "matched_notes" | "matched_notes_partial" | "matched_workflow_id" | "matched_head_sha" | "matched_branch" | "matched_repo_root" | "recency_fallback")[];
     }[];
     totalEligible: number;
 }, {
     candidates: {
+        confidence: "strong" | "weak" | "medium";
         workflowId: string;
         runId: string;
         sessionId: string;
+        gitBranch: string | null;
         isComplete: boolean;
         nextCall: {
             params: {
@@ -1260,11 +1278,13 @@ export declare const V2ResumeSessionOutputSchema: z.ZodObject<{
             };
             tool: "continue_workflow";
         };
+        sessionTitle: string | null;
         resumeToken: string;
         snippet: string;
+        matchExplanation: string;
         pendingStepId: string | null;
         lastModifiedMs: number | null;
-        whyMatched: ("matched_exact_id" | "matched_head_sha" | "matched_branch" | "matched_notes" | "matched_notes_partial" | "matched_workflow_id" | "recency_fallback")[];
+        whyMatched: ("matched_exact_id" | "matched_notes" | "matched_notes_partial" | "matched_workflow_id" | "matched_head_sha" | "matched_branch" | "matched_repo_root" | "recency_fallback")[];
     }[];
     totalEligible: number;
 }>;

package/dist/mcp/output-schemas.js

@@ -242,23 +242,29 @@ exports.V2ResumeSessionOutputSchema = zod_1.z.object({
         sessionId: zod_1.z.string().min(1),
         runId: zod_1.z.string().min(1),
         workflowId: zod_1.z.string().min(1),
+        sessionTitle: zod_1.z.string().nullable().describe('Human-readable task/session title derived from persisted workflow context or early recap text.'),
+        gitBranch: zod_1.z.string().nullable().describe('Git branch associated with the session, if available.'),
         resumeToken: zod_1.z.string().regex(token_patterns_js_1.STATE_TOKEN_PATTERN, 'Invalid resumeToken format'),
         snippet: zod_1.z.string().max(1024),
+        confidence: zod_1.z.enum(['strong', 'medium', 'weak']).describe('Coarse confidence band for how likely this candidate is the intended session.'),
+        matchExplanation: zod_1.z.string().min(1).describe('Short natural-language explanation of why this candidate ranked here.'),
         pendingStepId: zod_1.z.string().nullable().describe('The current pending step ID (e.g. "phase-3-implement") if the workflow is in progress. ' +
             'Null if the workflow is complete or the step could not be determined.'),
         isComplete: zod_1.z.boolean().describe('Whether the workflow run has completed. Completed sessions are deprioritized in ranking.'),
         lastModifiedMs: zod_1.z.number().nullable().describe('Filesystem modification time (epoch ms) of the session. Null if unavailable.'),
         whyMatched: zod_1.z.array(zod_1.z.enum([
             'matched_exact_id',
-            'matched_head_sha',
-            'matched_branch',
             'matched_notes',
             'matched_notes_partial',
             'matched_workflow_id',
+            'matched_head_sha',
+            'matched_branch',
+            'matched_repo_root',
             'recency_fallback',
         ])).describe('Match signals explaining why this candidate was ranked. ' +
-            'matched_exact_id/head_sha/branch/notes = strong signal. ' +
-            'matched_notes_partial = moderate signal (some query words matched). ' +
+            'matched_exact_id and matched_notes are strongest. ' +
+            'matched_notes_partial/matched_workflow_id are moderate text signals. ' +
+            'matched_repo_root/head_sha/branch are workspace-context signals. ' +
             'recency_fallback = no strong signal; inspect the snippet before resuming.'),
         nextCall: exports.V2ResumeNextCallSchema,
     })).max(5),

package/dist/mcp/v2/tools.d.ts

@@ -24,13 +24,13 @@ export declare const V2InspectWorkflowInput: z.ZodObject<{
 export type V2InspectWorkflowInput = z.infer<typeof V2InspectWorkflowInput>;
 export declare const V2StartWorkflowInput: z.ZodObject<{
     workflowId: z.ZodString;
-    workspacePath: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    workspacePath: z.ZodEffects<z.ZodString, string, string>;
 }, "strip", z.ZodTypeAny, {
     workflowId: string;
-    workspacePath?: string | undefined;
+    workspacePath: string;
 }, {
     workflowId: string;
-    workspacePath?: string | undefined;
+    workspacePath: string;
 }>;
 export type V2StartWorkflowInput = z.infer<typeof V2StartWorkflowInput>;
 export declare const V2ContinueWorkflowInputShape: z.ZodObject<{
@@ -151,21 +151,24 @@ export declare const V2ResumeSessionInput: z.ZodObject<{
     sessionId: z.ZodOptional<z.ZodString>;
     gitBranch: z.ZodOptional<z.ZodString>;
     gitHeadSha: z.ZodOptional<z.ZodString>;
-    workspacePath: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    workspacePath: z.ZodEffects<z.ZodString, string, string>;
+    sameWorkspaceOnly: z.ZodOptional<z.ZodBoolean>;
 }, "strict", z.ZodTypeAny, {
-    workspacePath?: string | undefined;
+    workspacePath: string;
     query?: string | undefined;
     runId?: string | undefined;
     sessionId?: string | undefined;
     gitBranch?: string | undefined;
     gitHeadSha?: string | undefined;
+    sameWorkspaceOnly?: boolean | undefined;
 }, {
-    workspacePath?: string | undefined;
+    workspacePath: string;
     query?: string | undefined;
     runId?: string | undefined;
     sessionId?: string | undefined;
     gitBranch?: string | undefined;
     gitHeadSha?: string | undefined;
+    sameWorkspaceOnly?: boolean | undefined;
 }>;
 export type V2ResumeSessionInput = z.infer<typeof V2ResumeSessionInput>;
 export declare const V2CheckpointWorkflowInput: z.ZodObject<{

package/dist/mcp/v2/tools.js

@@ -1,26 +1,33 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.V2_TOOL_ANNOTATIONS = exports.V2_TOOL_TITLES = exports.V2CheckpointWorkflowInput = exports.V2ResumeSessionInput = exports.V2ContinueWorkflowInput = exports.V2ContinueWorkflowInputShape = exports.V2StartWorkflowInput = exports.V2InspectWorkflowInput = exports.V2ListWorkflowsInput = void 0;
+const path_1 = __importDefault(require("path"));
 const zod_1 = require("zod");
 const workflow_protocol_contracts_js_1 = require("../workflow-protocol-contracts.js");
+function isAbsoluteWorkspacePath(p) {
+    return path_1.default.isAbsolute(p);
+}
 const workspacePathField = zod_1.z.string()
-    .refine((p) => p.startsWith('/'), 'workspacePath must be an absolute path (starting with /)')
-    .optional()
+    .refine((p) => isAbsoluteWorkspacePath(p), 'workspacePath must be an absolute path')
     .describe('Absolute path to your current workspace directory (e.g. the "Workspace:" value from your system parameters). Used to resolve project-scoped workflow variants against the correct workspace. If omitted, WorkRail uses MCP roots when available, then falls back to the server process directory.');
+const optionalWorkspacePathField = workspacePathField.optional();
 exports.V2ListWorkflowsInput = zod_1.z.object({
-    workspacePath: workspacePathField,
+    workspacePath: optionalWorkspacePathField,
 });
 exports.V2InspectWorkflowInput = zod_1.z.object({
     workflowId: zod_1.z.string().min(1).regex(/^[A-Za-z0-9_-]+$/, 'Workflow ID must contain only letters, numbers, hyphens, and underscores').describe('The workflow ID to inspect'),
     mode: zod_1.z.enum(['metadata', 'preview']).default('preview').describe('Detail level: metadata (name and description only) or preview (full step-by-step breakdown, default)'),
-    workspacePath: workspacePathField,
+    workspacePath: optionalWorkspacePathField,
 });
 exports.V2StartWorkflowInput = zod_1.z.object({
     workflowId: zod_1.z.string().min(1).regex(/^[A-Za-z0-9_-]+$/, 'Workflow ID must contain only letters, numbers, hyphens, and underscores').describe('The workflow ID to start'),
-    workspacePath: workspacePathField.describe('Absolute path to your current workspace directory (e.g. the "Workspace:" value from your system parameters). Used to resolve the correct project-scoped workflow variant and to anchor this session to your workspace for future resume_session discovery. Pass this on every start_workflow call. If omitted, WorkRail uses MCP roots when available, then falls back to the server process directory.'),
+    workspacePath: workspacePathField.describe('Required. Absolute path to your current workspace directory (e.g. the "Workspace:" value from your system parameters). WorkRail uses this to resolve the correct project-scoped workflow variant and to anchor the session to the correct repo for future resume_session discovery. Shared MCP servers cannot infer this safely.'),
 });
 exports.V2ContinueWorkflowInputShape = zod_1.z.object({
-    workspacePath: workspacePathField,
+    workspacePath: optionalWorkspacePathField,
     continueToken: zod_1.z.string().min(1).describe('The token for your next continue_workflow call. Two valid token kinds: ' +
         '(1) A continueToken (ct_...) from start_workflow or a previous continue_workflow — carries session identity AND advance authority. ' +
         '(2) A resumeToken (st_...) from resume_session or checkpoint_workflow — carries session identity only; valid for intent: "rehydrate", not "advance". ' +
@@ -69,6 +76,13 @@ exports.V2ContinueWorkflowInput = exports.V2ContinueWorkflowInputShape
                 'Rehydration is read-only state recovery — it does not accept output.',
         });
     }
+    if (data.intent === 'rehydrate' && data.workspacePath === undefined) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['workspacePath'],
+            message: 'workspacePath is required for rehydration. Shared WorkRail servers cannot safely infer your current workspace, so pass the absolute "Workspace:" path from your system parameters.',
+        });
+    }
 })
     .transform((data) => {
     const normalized = workflow_protocol_contracts_js_1.CONTINUE_WORKFLOW_PROTOCOL.aliasMap
@@ -93,10 +107,9 @@ exports.V2ResumeSessionInput = zod_1.z.object({
         'When provided, the matching session is returned as the sole top-priority candidate.'),
     gitBranch: zod_1.z.string().max(256).optional().describe('Git branch name to match against session observations. Overrides auto-detected branch.'),
     gitHeadSha: zod_1.z.string().regex(/^[0-9a-f]{40}$/).optional().describe('Git HEAD SHA to match against session observations. Overrides auto-detected HEAD.'),
-    workspacePath: zod_1.z.string()
-        .refine((p) => p.startsWith('/'), 'workspacePath must be an absolute path (starting with /)')
-        .optional()
-        .describe('Absolute path to your current workspace directory (e.g. the "Workspace:" value from your system parameters). Used to resolve your git branch and HEAD SHA for workspace-aware session matching. Pass the same path used in the original start_workflow call. If omitted, WorkRail uses the server process directory which may not match your workspace.'),
+    workspacePath: workspacePathField.describe('Required. Absolute path to your current workspace directory (e.g. the "Workspace:" value from your system parameters). WorkRail uses this to identify the current repo and resume the correct session on shared MCP servers.'),
+    sameWorkspaceOnly: zod_1.z.boolean().optional().describe('If true, only sessions from the same repo/workspace are considered when repo_root_hash is available. ' +
+        'Use this when the user clearly means "resume work from this repo only".'),
 }).strict();
 exports.V2CheckpointWorkflowInput = zod_1.z.object({
     checkpointToken: zod_1.z.string().min(1).describe('The checkpoint token from the most recent start_workflow or continue_workflow response. ' +

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

@@ -400,11 +400,12 @@ function isResumeSessionResponse(data) {
 }
 const WHY_MATCHED_LABELS = {
     matched_exact_id: 'Exact ID match',
-    matched_head_sha: 'Same git commit (HEAD SHA)',
-    matched_branch: 'Same git branch',
     matched_notes: 'Query matched session notes',
     matched_notes_partial: 'Query partially matched session notes',
     matched_workflow_id: 'Query matched workflow type',
+    matched_head_sha: 'Same git commit (HEAD SHA)',
+    matched_branch: 'Same git branch',
+    matched_repo_root: 'Same workspace/repository',
     recency_fallback: 'No strong match signal (recent session)',
 };
 function formatRelativeTime(epochMs) {
@@ -433,10 +434,21 @@ function formatResumeCandidate(c, index) {
     const matchLabel = c.whyMatched.map(w => WHY_MATCHED_LABELS[w] ?? w).join(', ');
     const isWeak = c.whyMatched.every(w => w === 'recency_fallback');
     const statusTag = c.isComplete ? ' (completed)' : '';
-    lines.push(`### Candidate ${index + 1}: \`${c.workflowId}\`${statusTag}${isWeak ? ' (weak match)' : ''}`);
+    const heading = c.sessionTitle?.trim() || c.workflowId;
+    lines.push(`### Candidate ${index + 1}: \`${heading}\`${statusTag}${isWeak ? ' (weak match)' : ''}`);
     lines.push(`- **Session**: \`${c.sessionId}\``);
     lines.push(`- **Run**: \`${c.runId}\``);
+    lines.push(`- **Workflow**: \`${c.workflowId}\``);
     lines.push(`- **Match reason**: ${matchLabel}`);
+    if (c.confidence) {
+        lines.push(`- **Confidence**: ${c.confidence}`);
+    }
+    if (c.matchExplanation) {
+        lines.push(`- **Why this ranked here**: ${c.matchExplanation}`);
+    }
+    if (c.gitBranch) {
+        lines.push(`- **Branch**: \`${c.gitBranch}\``);
+    }
     if (c.pendingStepId) {
         lines.push(`- **Current step**: \`${c.pendingStepId}\``);
     }
@@ -458,10 +470,11 @@ function formatResumeCandidate(c, index) {
         lines.push('> This workflow has already completed. Resuming it will show the final state.');
     }
     lines.push('');
-    lines.push('To resume, call `continue_workflow` with:');
+    lines.push('To inspect or resume this candidate, call `continue_workflow` with:');
     lines.push('```json');
     lines.push(JSON.stringify(c.nextCall.params, null, 2));
     lines.push('```');
+    lines.push('This `rehydrate` call restores the exact workflow state and shows the current step/context.');
     return lines.join('\n');
 }
 const SEARCH_PARAMS_HELP = [
@@ -470,6 +483,7 @@ const SEARCH_PARAMS_HELP = [
     '- `runId`: Exact run ID if the user has one (e.g. "run_abc123def456")',
     '- `sessionId`: Exact session ID if the user has one (e.g. "sess_abc123")',
     '- `workspacePath`: Absolute path to the workspace (helps match by git branch/commit)',
+    '- `sameWorkspaceOnly`: Restrict results to the current repo/workspace when that is clearly what the user means',
 ].join('\n');
 function formatV2ResumeResponse(data) {
     if (!isResumeSessionResponse(data))
@@ -514,6 +528,12 @@ function formatV2ResumeResponse(data) {
         lines.push('');
         lines.push(`Found **${totalEligible}** session(s) total. Showing the top ${candidates.length} ranked by match strength.`);
         lines.push('');
+        const allWorkspaceDriven = candidates.every((c) => c.whyMatched.every((w) => w === 'matched_head_sha' || w === 'matched_branch'));
+        if (allWorkspaceDriven) {
+            lines.push('**Note**: These candidates are ranked primarily from current workspace git context (branch/commit), not from a strong text match on your query.');
+            lines.push('If the previews do not clearly match the user\'s request, inspect a candidate with `continue_workflow(..., intent: "rehydrate")` or ask for a more specific phrase / session ID.');
+            lines.push('');
+        }
         const best = candidates[0];
         const bestIsExact = best.whyMatched.includes('matched_exact_id');
         if (bestIsExact) {

package/dist/mcp/workflow-protocol-contracts.js

@@ -46,8 +46,8 @@ function findAliasFieldConflicts(value, aliasMap) {
 }
 exports.START_WORKFLOW_PROTOCOL = {
     canonicalParams: {
-        required: ['workflowId'],
-        optional: ['workspacePath'],
+        required: ['workflowId', 'workspacePath'],
+        optional: [],
     },
     descriptions: {
         standard: {
@@ -56,6 +56,7 @@ exports.START_WORKFLOW_PROTOCOL = {
             rules: [
                 'Follow the returned step exactly; treat it as the user\'s current instruction.',
                 'When the step is done, call continue_workflow with the returned continueToken.',
+                'Always pass workspacePath. Shared MCP servers cannot safely infer which repo/workspace you mean.',
                 'Only pass context on later continue_workflow calls if facts changed.',
             ],
             examplePayload: {
@@ -70,7 +71,7 @@ exports.START_WORKFLOW_PROTOCOL = {
             rules: [
                 'Execute the returned step exactly as written.',
                 'When the step is complete, call continue_workflow with the returned continueToken.',
-                'Pass workspacePath when available so WorkRail anchors the session to the correct workspace.',
+                'Pass workspacePath on every call. Shared MCP servers cannot safely infer the correct workspace.',
             ],
             examplePayload: {
                 workflowId: 'coding-task-workflow-agentic',
@@ -83,7 +84,7 @@ exports.START_WORKFLOW_PROTOCOL = {
 exports.CONTINUE_WORKFLOW_PROTOCOL = {
     canonicalParams: {
         required: ['continueToken'],
-        optional: ['intent', 'context', 'output'],
+        optional: ['intent', 'context', 'output', 'workspacePath'],
     },
     aliasMap: {
         contextVariables: 'context',
@@ -95,6 +96,7 @@ exports.CONTINUE_WORKFLOW_PROTOCOL = {
             rules: [
                 'Advance by sending output (and intent: "advance" if you want to be explicit).',
                 'Rehydrate by omitting output (and intent: "rehydrate" if you want to be explicit).',
+                'When rehydrating, always pass workspacePath so WorkRail can restore the correct repo/workspace context on shared servers.',
                 'Put changed facts under context only.',
                 'Round-trip continueToken exactly as returned by WorkRail; use the single-token API only.',
                 'Notes (output.notesMarkdown): write for a human reader. Include what you did and key decisions, what you produced (files, tests, numbers), and anything notable (risks, open questions, deliberate omissions). Use markdown headings, bullets, bold, code refs. Be specific. Scope: THIS step only (WorkRail concatenates automatically). 10-30 lines ideal. Omitting notes blocks the step.',
@@ -114,6 +116,7 @@ exports.CONTINUE_WORKFLOW_PROTOCOL = {
                 'Use continueToken exactly as returned by WorkRail.',
                 'Use the single-token API only.',
                 'Advance by sending output; rehydrate by omitting output.',
+                'For rehydrate calls, pass workspacePath so WorkRail can restore the correct workspace context.',
                 'Put updated facts in context only.',
                 'Notes (output.notesMarkdown): write for a human reader. Include what you did and key decisions, what you produced (files, tests, numbers), and anything notable (risks, open questions, deliberate omissions). Use markdown headings, bullets, bold, code refs. Be specific. Scope: THIS step only (WorkRail concatenates automatically). 10-30 lines ideal. Omitting notes blocks the step.',
             ],
@@ -164,8 +167,8 @@ exports.CHECKPOINT_WORKFLOW_PROTOCOL = {
 };
 exports.RESUME_SESSION_PROTOCOL = {
     canonicalParams: {
-        required: [],
-        optional: ['query', 'runId', 'sessionId', 'gitBranch', 'gitHeadSha', 'workspacePath'],
+        required: ['workspacePath'],
+        optional: ['query', 'runId', 'sessionId', 'gitBranch', 'gitHeadSha'],
     },
     descriptions: {
         standard: {
@@ -174,9 +177,9 @@ exports.RESUME_SESSION_PROTOCOL = {
             rules: [
                 'If the user provides a run ID (run_...) or session ID (sess_...), pass it as runId or sessionId for an exact match. This is the most reliable way to find a specific session.',
                 'If the user describes what they were working on (e.g. "the mr ownership task"), pass their words as query. This searches session recap notes and workflow IDs for matching keywords.',
-                'Always pass workspacePath (from your system parameters) so WorkRail can also match by git context (branch, commit).',
+                'Always pass workspacePath (from your system parameters). Shared MCP servers cannot safely infer the current workspace, and resume quality depends on the current repo identity.',
                 'The response includes ranked candidates with match explanations and ready-to-use continuation templates. Present the top candidates to the user if there is ambiguity.',
-                'To resume a candidate: call continue_workflow with the candidate\'s nextCall.params (continueToken and intent: "rehydrate"). The response will give you the full session context.',
+                'To inspect or resume a candidate: call continue_workflow with the candidate\'s nextCall.params (continueToken and intent: "rehydrate"). This is the correct inspection path for v2 sessions and restores the full session context.',
                 'If no candidates match, ask the user for more details or suggest starting a fresh workflow with start_workflow.',
             ],
             examplePayload: {
@@ -191,9 +194,9 @@ exports.RESUME_SESSION_PROTOCOL = {
             rules: [
                 'If the user provides a run ID (run_...) or session ID (sess_...), pass it as runId or sessionId for exact lookup.',
                 'If the user describes their task, pass their words as query to search session notes.',
-                'Always pass workspacePath from your system parameters for git-context matching.',
+                'Always pass workspacePath from your system parameters. Shared MCP servers cannot safely infer the current workspace.',
                 'Present candidates to the user when there is ambiguity. The response explains match strength.',
-                'To resume: call continue_workflow with the chosen candidate\'s nextCall.params (continueToken + intent: "rehydrate").',
+                'To inspect or resume: call continue_workflow with the chosen candidate\'s nextCall.params (continueToken + intent: "rehydrate"). Do NOT use legacy session tools to inspect a v2 workflow resume candidate.',
                 'If no candidates match, ask for more details or start a fresh workflow.',
             ],
             examplePayload: {