@exaudeus/workrail 3.7.2 → 3.7.3

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: {

package/dist/v2/infra/local/session-summary-provider/index.js

@@ -7,6 +7,7 @@ const enumerate_sessions_js_1 = require("../../../usecases/enumerate-sessions.js
 const session_health_js_1 = require("../../../projections/session-health.js");
 const run_dag_js_1 = require("../../../projections/run-dag.js");
 const node_outputs_js_1 = require("../../../projections/node-outputs.js");
+const run_context_js_1 = require("../../../projections/run-context.js");
 const snapshot_state_js_1 = require("../../../durable-core/projections/snapshot-state.js");
 const index_js_1 = require("../../../durable-core/ids/index.js");
 const constants_js_1 = require("../../../durable-core/constants.js");
@@ -17,6 +18,7 @@ const EMPTY_OBSERVATIONS = {
     gitBranch: null,
     repoRootHash: null,
 };
+const TITLE_CONTEXT_KEYS = ['goal', 'taskDescription', 'mrTitle', 'prTitle', 'ticketTitle', 'problem'];
 class LocalSessionSummaryProviderV2 {
     constructor(ports) {
         this.ports = ports;
@@ -99,6 +101,7 @@ function projectSessionSummary(sessionId, truth, mtimeMs) {
             recapSnippet,
             observations: extractObservations(truth.events),
             workflow,
+            sessionTitle: deriveSessionTitle(truth.events, bestRun.run.runId),
             lastModifiedMs: mtimeMs,
             pendingStepId: null,
             isComplete: false,
@@ -145,6 +148,80 @@ function extractWorkflowIdentity(events, runId) {
         workflowHash: (0, index_js_1.asWorkflowHash)((0, index_js_1.asSha256Digest)(event.data.workflowHash)),
     };
 }
+function deriveSessionTitle(events, runId) {
+    const contextRes = (0, run_context_js_1.projectRunContextV2)(events);
+    if (contextRes.isOk()) {
+        const runCtx = contextRes.value.byRunId[runId];
+        if (runCtx) {
+            for (const key of TITLE_CONTEXT_KEYS) {
+                const val = runCtx.context[key];
+                if (typeof val === 'string' && val.trim().length > 0) {
+                    return truncateTitle(val.trim());
+                }
+            }
+        }
+    }
+    return extractTitleFromFirstRecap(events);
+}
+function extractTitleFromFirstRecap(events) {
+    const outputsRes = (0, node_outputs_js_1.projectNodeOutputsV2)(events);
+    if (outputsRes.isErr())
+        return null;
+    let rootNodeId = null;
+    let minIndex = Infinity;
+    for (const e of events) {
+        if (e.kind === constants_js_1.EVENT_KIND.NODE_CREATED && e.eventIndex < minIndex) {
+            minIndex = e.eventIndex;
+            rootNodeId = e.scope.nodeId;
+        }
+    }
+    if (!rootNodeId)
+        return null;
+    const nodeOutputs = outputsRes.value.nodesById[rootNodeId];
+    if (!nodeOutputs)
+        return null;
+    const recaps = nodeOutputs.currentByChannel[constants_js_1.OUTPUT_CHANNEL.RECAP];
+    const first = recaps?.[0];
+    if (!first || first.payload.payloadKind !== constants_js_1.PAYLOAD_KIND.NOTES)
+        return null;
+    return extractDescriptiveText(first.payload.notesMarkdown);
+}
+function extractDescriptiveText(markdown) {
+    const lines = markdown
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    for (const line of lines) {
+        if (/^#{1,3}\s/.test(line))
+            continue;
+        if (/^[-_*]{3,}$/.test(line))
+            continue;
+        if (line.startsWith('|'))
+            continue;
+        const boldLabel = line.match(/^\*{2}[^*]+\*{2}:?\s*(.*)/);
+        if (boldLabel) {
+            const value = boldLabel[1]?.trim();
+            if (value && value.length > 10)
+                return truncateTitle(value);
+            continue;
+        }
+        const listBoldLabel = line.match(/^-\s+\*{2}[^*]+\*{2}:?\s*(.*)/);
+        if (listBoldLabel) {
+            const value = listBoldLabel[1]?.trim();
+            if (value && value.length > 10)
+                return truncateTitle(value);
+            continue;
+        }
+        if (line.length > 10)
+            return truncateTitle(line);
+    }
+    return null;
+}
+function truncateTitle(text, maxLen = 120) {
+    if (text.length <= maxLen)
+        return text;
+    return text.slice(0, maxLen - 1) + '…';
+}
 function collectAncestorNodeIds(nodesById, nodeId, remainingDepth) {
     if (remainingDepth === 0)
         return [nodeId];

package/dist/v2/infra/local/workspace-anchor/index.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.LocalWorkspaceAnchorV2 = void 0;
 const neverthrow_1 = require("neverthrow");
 const child_process_1 = require("child_process");
+const crypto_1 = require("crypto");
 const util_1 = require("util");
 const url_1 = require("url");
 const execAsync = (0, util_1.promisify)(child_process_1.exec);
@@ -32,6 +33,13 @@ class LocalWorkspaceAnchorV2 {
     }
     async runGitCommands(cwd) {
         const anchors = [];
+        const repoRoot = await this.gitCommand('git rev-parse --show-toplevel', cwd);
+        if (!repoRoot)
+            return anchors;
+        const repoRootHash = hashRepoRoot(repoRoot);
+        if (repoRootHash) {
+            anchors.push({ key: 'repo_root_hash', value: repoRootHash });
+        }
         const branch = await this.gitCommand('git rev-parse --abbrev-ref HEAD', cwd);
         if (branch && branch !== 'HEAD') {
             anchors.push({ key: 'git_branch', value: branch });
@@ -57,6 +65,21 @@ class LocalWorkspaceAnchorV2 {
     }
 }
 exports.LocalWorkspaceAnchorV2 = LocalWorkspaceAnchorV2;
+function hashRepoRoot(repoRoot) {
+    try {
+        const normalized = repoRoot.trim();
+        if (!normalized)
+            return null;
+        const digest = createSha256Hex(normalized);
+        return `sha256:${digest}`;
+    }
+    catch {
+        return null;
+    }
+}
+function createSha256Hex(input) {
+    return (0, crypto_1.createHash)('sha256').update(input).digest('hex');
+}
 function uriToFsPath(uri) {
     if (!uri.startsWith('file://'))
         return null;

package/dist/v2/projections/resume-ranking.d.ts

@@ -28,32 +28,33 @@ export interface HealthySessionSummary {
     readonly recapSnippet: RecapSnippet | null;
     readonly observations: SessionObservations;
     readonly workflow: IdentifiedWorkflow;
+    readonly sessionTitle: string | null;
     readonly lastModifiedMs: number | null;
     readonly pendingStepId: string | null;
     readonly isComplete: boolean;
 }
-export type WhyMatched = 'matched_exact_id' | 'matched_head_sha' | 'matched_branch' | 'matched_notes' | 'matched_notes_partial' | 'matched_workflow_id' | 'recency_fallback';
+export type WhyMatched = 'matched_exact_id' | 'matched_head_sha' | 'matched_repo_root' | 'matched_branch' | 'matched_notes' | 'matched_notes_partial' | 'matched_workflow_id' | 'recency_fallback';
 export type TierAssignment = {
     readonly tier: 0;
     readonly kind: 'matched_exact_id';
     readonly matchField: 'runId' | 'sessionId';
 } | {
     readonly tier: 1;
-    readonly kind: 'matched_head_sha';
+    readonly kind: 'matched_notes';
 } | {
     readonly tier: 2;
-    readonly kind: 'matched_branch';
-    readonly matchType: 'exact' | 'prefix';
+    readonly kind: 'matched_notes_partial';
+    readonly matchRatio: number;
 } | {
     readonly tier: 3;
-    readonly kind: 'matched_notes';
+    readonly kind: 'matched_workflow_id';
 } | {
     readonly tier: 4;
-    readonly kind: 'matched_notes_partial';
-    readonly matchRatio: number;
+    readonly kind: 'matched_head_sha';
 } | {
     readonly tier: 5;
-    readonly kind: 'matched_workflow_id';
+    readonly kind: 'matched_branch';
+    readonly matchType: 'exact' | 'prefix';
 } | {
     readonly tier: 6;
     readonly kind: 'recency_fallback';
@@ -66,10 +67,13 @@ export declare function fuzzyQueryTokenMatchRatio(queryTokens: ReadonlySet<strin
 export interface ResumeQuery {
     readonly gitHeadSha?: string;
     readonly gitBranch?: string;
+    readonly repoRootHash?: string;
+    readonly sameWorkspaceOnly?: boolean;
     readonly freeTextQuery?: string;
     readonly runId?: string;
     readonly sessionId?: string;
 }
+export declare function computeQueryRelevanceScore(summary: HealthySessionSummary, query: ResumeQuery): number;
 export declare function assignTier(summary: HealthySessionSummary, query: ResumeQuery): TierAssignment;
 export interface RankedResumeCandidate {
     readonly sessionId: SessionId;
@@ -81,9 +85,13 @@ export interface RankedResumeCandidate {
     readonly lastActivityEventIndex: number;
     readonly workflowHash: WorkflowHash;
     readonly workflowId: WorkflowId;
+    readonly sessionTitle: string | null;
+    readonly gitBranch: string | null;
     readonly pendingStepId: string | null;
     readonly isComplete: boolean;
     readonly lastModifiedMs: number | null;
+    readonly confidence: 'strong' | 'medium' | 'weak';
+    readonly matchExplanation: string;
 }
 export declare const MAX_RESUME_CANDIDATES = 5;
 export declare function rankResumeCandidates(summaries: readonly HealthySessionSummary[], query: ResumeQuery): readonly RankedResumeCandidate[];

package/dist/v2/projections/resume-ranking.js

@@ -7,6 +7,7 @@ exports.allQueryTokensMatch = allQueryTokensMatch;
 exports.queryTokenMatchRatio = queryTokenMatchRatio;
 exports.fuzzyTokenMatch = fuzzyTokenMatch;
 exports.fuzzyQueryTokenMatchRatio = fuzzyQueryTokenMatchRatio;
+exports.computeQueryRelevanceScore = computeQueryRelevanceScore;
 exports.assignTier = assignTier;
 exports.rankResumeCandidates = rankResumeCandidates;
 const constants_js_1 = require("../durable-core/constants.js");
@@ -71,6 +72,159 @@ function fuzzyQueryTokenMatchRatio(queryTokens, candidateTokens) {
     return matched / queryTokens.size;
 }
 const MIN_PARTIAL_MATCH_RATIO = 0.4;
+const LOW_SIGNAL_QUERY_TOKENS = new Set([
+    'task',
+    'dev',
+    'work',
+    'workflow',
+    'coding',
+    'feature',
+    'phase',
+    'implement',
+    'implementation',
+    'review',
+    'fix',
+    'bug',
+]);
+function tokenSpecificityWeight(token) {
+    if (token.length <= 2)
+        return 0.2;
+    if (LOW_SIGNAL_QUERY_TOKENS.has(token))
+        return 0.35;
+    return Math.min(2.5, 1 + Math.max(0, token.length - 4) * 0.18);
+}
+function weightedFuzzyQueryTokenMatchRatio(queryTokens, candidateTokens) {
+    if (queryTokens.size === 0 || candidateTokens.size === 0)
+        return 0;
+    let matchedWeight = 0;
+    let totalWeight = 0;
+    for (const qt of queryTokens) {
+        const weight = tokenSpecificityWeight(qt);
+        totalWeight += weight;
+        if (candidateTokens.has(qt) || fuzzyTokenMatch(qt, candidateTokens)) {
+            matchedWeight += weight;
+        }
+    }
+    return totalWeight === 0 ? 0 : matchedWeight / totalWeight;
+}
+function repoScopeMatches(summary, query) {
+    return Boolean(query.repoRootHash &&
+        summary.observations.repoRootHash &&
+        query.repoRootHash === summary.observations.repoRootHash);
+}
+function shouldKeepSummary(summary, query) {
+    if (!query.sameWorkspaceOnly)
+        return true;
+    if (!query.repoRootHash)
+        return true;
+    return repoScopeMatches(summary, query);
+}
+function buildSearchableSessionText(summary) {
+    return [summary.sessionTitle, summary.recapSnippet]
+        .filter((part) => Boolean(part && part.trim().length > 0))
+        .join('\n\n');
+}
+function collectMatchReasons(summary, query, tier) {
+    const reasons = [tierToWhyMatched(tier)];
+    if (repoScopeMatches(summary, query) && !reasons.includes('matched_repo_root')) {
+        reasons.push('matched_repo_root');
+    }
+    if (query.gitHeadSha &&
+        summary.observations.gitHeadSha === query.gitHeadSha &&
+        !reasons.includes('matched_head_sha')) {
+        reasons.push('matched_head_sha');
+    }
+    if (query.gitBranch &&
+        summary.observations.gitBranch &&
+        (summary.observations.gitBranch === query.gitBranch ||
+            summary.observations.gitBranch.startsWith(query.gitBranch) ||
+            query.gitBranch.startsWith(summary.observations.gitBranch)) &&
+        !reasons.includes('matched_branch')) {
+        reasons.push('matched_branch');
+    }
+    return reasons;
+}
+function buildPreviewSnippet(summary, query) {
+    const previewSource = buildSearchableSessionText(summary);
+    if (!previewSource)
+        return '';
+    const queryTokens = query.freeTextQuery ? [...normalizeToTokens(query.freeTextQuery)] : [];
+    if (queryTokens.length === 0)
+        return summary.recapSnippet ?? previewSource;
+    const lower = previewSource.toLowerCase();
+    let bestIndex = -1;
+    for (const token of queryTokens) {
+        if (token.length < 3)
+            continue;
+        const idx = lower.indexOf(token);
+        if (idx !== -1 && (bestIndex === -1 || idx < bestIndex))
+            bestIndex = idx;
+    }
+    if (bestIndex === -1)
+        return summary.recapSnippet ?? previewSource;
+    const start = Math.max(0, bestIndex - 100);
+    const end = Math.min(previewSource.length, bestIndex + 180);
+    const slice = previewSource.slice(start, end).trim();
+    const prefix = start > 0 ? '...' : '';
+    const suffix = end < previewSource.length ? '...' : '';
+    return `${prefix}${slice}${suffix}`;
+}
+function deriveConfidence(tier, reasons) {
+    if (tier.kind === 'matched_exact_id' || tier.kind === 'matched_notes')
+        return 'strong';
+    if (tier.kind === 'matched_notes_partial' || tier.kind === 'matched_workflow_id')
+        return 'medium';
+    if (reasons.includes('matched_repo_root') || reasons.includes('matched_head_sha') || reasons.includes('matched_branch')) {
+        return 'medium';
+    }
+    return 'weak';
+}
+function buildMatchExplanation(tier, reasons, summary) {
+    const parts = [];
+    switch (tier.kind) {
+        case 'matched_exact_id':
+            parts.push(`Exact ${tier.matchField} match`);
+            break;
+        case 'matched_notes':
+            parts.push('Strong text match against session title/notes');
+            break;
+        case 'matched_notes_partial':
+            parts.push(`Partial text match (${Math.round(tier.matchRatio * 100)}%) against session title/notes`);
+            break;
+        case 'matched_workflow_id':
+            parts.push('Matched workflow type');
+            break;
+        case 'matched_head_sha':
+            parts.push('Matched current git commit');
+            break;
+        case 'matched_branch':
+            parts.push(tier.matchType === 'exact' ? 'Matched current git branch' : 'Partially matched current git branch');
+            break;
+        case 'recency_fallback':
+            parts.push('Recent session with no stronger explicit match');
+            break;
+    }
+    if (reasons.includes('matched_repo_root'))
+        parts.push('same workspace');
+    if (summary.isComplete)
+        parts.push('completed');
+    return parts.join('; ');
+}
+function computeQueryRelevanceScore(summary, query) {
+    const queryTokens = query.freeTextQuery ? normalizeToTokens(query.freeTextQuery) : null;
+    const repoBonus = repoScopeMatches(summary, query) ? 0.2 : 0;
+    if (!queryTokens || queryTokens.size === 0)
+        return repoBonus;
+    const sessionText = buildSearchableSessionText(summary);
+    const sessionTextRatio = sessionText
+        ? weightedFuzzyQueryTokenMatchRatio(queryTokens, normalizeToTokens(sessionText))
+        : 0;
+    const workflowRatio = weightedFuzzyQueryTokenMatchRatio(queryTokens, normalizeToTokens(String(summary.workflow.workflowId)));
+    const branchRatio = summary.observations.gitBranch
+        ? weightedFuzzyQueryTokenMatchRatio(queryTokens, normalizeToTokens(summary.observations.gitBranch))
+        : 0;
+    return Math.max(sessionTextRatio + repoBonus, workflowRatio * 0.75 + repoBonus, branchRatio * 0.5 + repoBonus);
+}
 function assignTier(summary, query) {
     if (query.runId && summary.runId === query.runId) {
         return { tier: 0, kind: 'matched_exact_id', matchField: 'runId' };
@@ -78,37 +232,38 @@ function assignTier(summary, query) {
     if (query.sessionId && String(summary.sessionId) === query.sessionId) {
         return { tier: 0, kind: 'matched_exact_id', matchField: 'sessionId' };
     }
+    const queryTokens = query.freeTextQuery ? normalizeToTokens(query.freeTextQuery) : null;
+    if (queryTokens && queryTokens.size > 0) {
+        const sessionText = buildSearchableSessionText(summary);
+        if (sessionText) {
+            const sessionTextTokens = normalizeToTokens(sessionText);
+            if (allQueryTokensMatch(queryTokens, sessionTextTokens)) {
+                return { tier: 1, kind: 'matched_notes' };
+            }
+            const ratio = weightedFuzzyQueryTokenMatchRatio(queryTokens, sessionTextTokens);
+            if (ratio >= MIN_PARTIAL_MATCH_RATIO) {
+                return { tier: 2, kind: 'matched_notes_partial', matchRatio: ratio };
+            }
+        }
+        const workflowTokens = normalizeToTokens(String(summary.workflow.workflowId));
+        if (allQueryTokensMatch(queryTokens, workflowTokens)) {
+            return { tier: 3, kind: 'matched_workflow_id' };
+        }
+        const workflowRatio = weightedFuzzyQueryTokenMatchRatio(queryTokens, workflowTokens);
+        if (workflowRatio >= MIN_PARTIAL_MATCH_RATIO) {
+            return { tier: 3, kind: 'matched_workflow_id' };
+        }
+    }
     if (query.gitHeadSha && summary.observations.gitHeadSha === query.gitHeadSha) {
-        return { tier: 1, kind: 'matched_head_sha' };
+        return { tier: 4, kind: 'matched_head_sha' };
     }
     if (query.gitBranch && summary.observations.gitBranch) {
         if (summary.observations.gitBranch === query.gitBranch) {
-            return { tier: 2, kind: 'matched_branch', matchType: 'exact' };
+            return { tier: 5, kind: 'matched_branch', matchType: 'exact' };
         }
         if (summary.observations.gitBranch.startsWith(query.gitBranch) ||
             query.gitBranch.startsWith(summary.observations.gitBranch)) {
-            return { tier: 2, kind: 'matched_branch', matchType: 'prefix' };
-        }
-    }
-    const queryTokens = query.freeTextQuery ? normalizeToTokens(query.freeTextQuery) : null;
-    if (queryTokens && queryTokens.size > 0 && summary.recapSnippet) {
-        const noteTokens = normalizeToTokens(summary.recapSnippet);
-        if (allQueryTokensMatch(queryTokens, noteTokens)) {
-            return { tier: 3, kind: 'matched_notes' };
-        }
-        const ratio = fuzzyQueryTokenMatchRatio(queryTokens, noteTokens);
-        if (ratio >= MIN_PARTIAL_MATCH_RATIO) {
-            return { tier: 4, kind: 'matched_notes_partial', matchRatio: ratio };
-        }
-    }
-    if (queryTokens && queryTokens.size > 0 && summary.workflow.kind === 'identified') {
-        const workflowTokens = normalizeToTokens(String(summary.workflow.workflowId));
-        if (allQueryTokensMatch(queryTokens, workflowTokens)) {
-            return { tier: 5, kind: 'matched_workflow_id' };
-        }
-        const ratio = fuzzyQueryTokenMatchRatio(queryTokens, workflowTokens);
-        if (ratio >= MIN_PARTIAL_MATCH_RATIO) {
-            return { tier: 5, kind: 'matched_workflow_id' };
+            return { tier: 5, kind: 'matched_branch', matchType: 'prefix' };
         }
     }
     return { tier: 6, kind: 'recency_fallback' };
@@ -126,16 +281,25 @@ function tierToWhyMatched(tier) {
 }
 exports.MAX_RESUME_CANDIDATES = 5;
 function rankResumeCandidates(summaries, query) {
-    const withTier = summaries.map((summary) => ({
+    const withTier = summaries
+        .filter((summary) => shouldKeepSummary(summary, query))
+        .map((summary) => ({
         summary,
         tier: assignTier(summary, query),
+        queryScore: computeQueryRelevanceScore(summary, query),
     }));
     const sorted = [...withTier].sort((a, b) => {
         if (a.tier.tier !== b.tier.tier)
             return a.tier.tier - b.tier.tier;
+        const aSameRepo = repoScopeMatches(a.summary, query);
+        const bSameRepo = repoScopeMatches(b.summary, query);
+        if (aSameRepo !== bSameRepo)
+            return aSameRepo ? -1 : 1;
         if (a.summary.isComplete !== b.summary.isComplete) {
             return a.summary.isComplete ? 1 : -1;
         }
+        if (a.queryScore !== b.queryScore)
+            return b.queryScore - a.queryScore;
         if (a.tier.kind === 'matched_notes_partial' && b.tier.kind === 'matched_notes_partial') {
             if (a.tier.matchRatio !== b.tier.matchRatio)
                 return b.tier.matchRatio - a.tier.matchRatio;
@@ -146,18 +310,25 @@ function rankResumeCandidates(summaries, query) {
             return actB - actA;
         return String(a.summary.sessionId).localeCompare(String(b.summary.sessionId));
     });
-    return sorted.slice(0, exports.MAX_RESUME_CANDIDATES).map(({ summary, tier }) => ({
-        sessionId: summary.sessionId,
-        runId: summary.runId,
-        preferredTipNodeId: summary.preferredTip.nodeId,
-        snippet: summary.recapSnippet ?? '',
-        whyMatched: [tierToWhyMatched(tier)],
-        tierAssignment: tier,
-        lastActivityEventIndex: summary.preferredTip.lastActivityEventIndex,
-        workflowHash: summary.workflow.workflowHash,
-        workflowId: summary.workflow.workflowId,
-        pendingStepId: summary.pendingStepId,
-        isComplete: summary.isComplete,
-        lastModifiedMs: summary.lastModifiedMs,
-    }));
+    return sorted.slice(0, exports.MAX_RESUME_CANDIDATES).map(({ summary, tier }) => {
+        const whyMatched = collectMatchReasons(summary, query, tier);
+        return {
+            sessionId: summary.sessionId,
+            runId: summary.runId,
+            preferredTipNodeId: summary.preferredTip.nodeId,
+            snippet: buildPreviewSnippet(summary, query),
+            whyMatched,
+            tierAssignment: tier,
+            lastActivityEventIndex: summary.preferredTip.lastActivityEventIndex,
+            workflowHash: summary.workflow.workflowHash,
+            workflowId: summary.workflow.workflowId,
+            sessionTitle: summary.sessionTitle,
+            gitBranch: summary.observations.gitBranch,
+            pendingStepId: summary.pendingStepId,
+            isComplete: summary.isComplete,
+            lastModifiedMs: summary.lastModifiedMs,
+            confidence: deriveConfidence(tier, whyMatched),
+            matchExplanation: buildMatchExplanation(tier, whyMatched, summary),
+        };
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exaudeus/workrail",
-  "version": "3.7.2",
+  "version": "3.7.3",
   "description": "Step-by-step workflow enforcement for AI agents via MCP",
   "license": "MIT",
   "repository": {