@exaudeus/workrail 1.4.0 → 1.5.0

package/dist/manifest.json

@@ -593,6 +593,14 @@
       "sha256": "561e34c59e1640dd419644b1abc750b2750e8a99bce000abef593e5047badc23",
       "bytes": 50334
     },
+    "mcp/handlers/v2-resume.d.ts": {
+      "sha256": "d88f6c35bcaf946666c837b72fda3702a2ebab5e478eb90f7b4b672a0e5fa24f",
+      "bytes": 471
+    },
+    "mcp/handlers/v2-resume.js": {
+      "sha256": "b4ce6f9cc3dffef91ca7da2e428d659c4ff79ceaf984c87d672290215936db97",
+      "bytes": 2771
+    },
     "mcp/handlers/v2-state-conversion.d.ts": {
       "sha256": "e8d70753ed1b83d9396864ef50929ba32cb008bda24bcb2ce624df24adb72570",
       "bytes": 1988
@@ -634,20 +642,20 @@
       "bytes": 7535
     },
     "mcp/output-schemas.d.ts": {
-      "sha256": "ae6188036f2e379c9f5498f7256f658e5bdd5301024e7bd863d02ca3dfad9f41",
-      "bytes": 43607
+      "sha256": "f18366a180449212d9a2b280dc9706f4f96a77ccead38bf11035c3859121fd84",
+      "bytes": 45137
     },
     "mcp/output-schemas.js": {
-      "sha256": "3ad98beeb67c03622651e100e8a4c02374318e1967fa062335d6dda80664ad8e",
-      "bytes": 10889
+      "sha256": "e7aeb43d06950e4a9ed1fa4ecd56418dc7eb32f54453634701b5dc39456eb3e8",
+      "bytes": 11565
     },
     "mcp/server.d.ts": {
       "sha256": "bec49b8d07e189a53db7100d2f0e1e84ffe03150f04e1b06908ee3282982b4a2",
       "bytes": 168
     },
     "mcp/server.js": {
-      "sha256": "8c7afb047807dd5fcd461b813b7bc714ea375d0999dfe9a7c901bf1462798455",
-      "bytes": 9940
+      "sha256": "37ab570be76b379a4076e78e5bc82a06b7ee1fc73d3d5010ad48b5650e54365a",
+      "bytes": 10631
     },
     "mcp/tool-description-provider.d.ts": {
       "sha256": "1d46abc3112e11b68e57197e846f5708293ec9b2281fa71a9124ee2aad71e41b",
@@ -662,8 +670,8 @@
       "bytes": 132
     },
     "mcp/tool-descriptions.js": {
-      "sha256": "e5f98cd0791507b87b3d0883155e74aaf4a9f03fd17b795195f21835962bd4cf",
-      "bytes": 15369
+      "sha256": "76d25a3a2bba38227ad199c4d1240769b6b14411ebecf965e9e00eaac2f2e01c",
+      "bytes": 16389
     },
     "mcp/tool-factory.d.ts": {
       "sha256": "0fe3c6b863b2d7aef0c3d659ff54f3a9ee8a0a3c2005b6565d2f8ad517bc7211",
@@ -678,28 +686,28 @@
       "bytes": 5976
     },
     "mcp/tools.js": {
-      "sha256": "813dad3f02046e200d99c2228cbf53ad9de58a79e609356730c93b75903d4c01",
-      "bytes": 8198
+      "sha256": "aa364f3e613fc61a39fc7336a723231da06852d92ec7840a95327aa370e42e1c",
+      "bytes": 8360
     },
     "mcp/types.d.ts": {
-      "sha256": "9e29d5ae4ec1f80640f073f0d58b603158fe5b22897f44c1c77ed4abaef374f9",
-      "bytes": 3638
+      "sha256": "564136878ad3e71300d5e82913590b1f43d3dfbafab36479c9a590853cd07a0a",
+      "bytes": 4050
     },
     "mcp/types.js": {
       "sha256": "0c12576fd0053115ff096fe26b38f77f1e830b7ec4781aaf94564827c4c9e81a",
       "bytes": 1253
     },
     "mcp/types/tool-description-types.d.ts": {
-      "sha256": "41e31c87b6d5b2e0fb4b66b1e8fac3f74c9769c3ded8a26577804aeccb79ae7b",
-      "bytes": 805
+      "sha256": "80984afa5283a0d651ff22c0c9b2d3ff14c85087aeaf735d306ae291d8cdfe4d",
+      "bytes": 823
     },
     "mcp/types/tool-description-types.js": {
-      "sha256": "689e74ea09e25e51de6020e42de42c37965e55980635d8739fc9ad19ba341955",
-      "bytes": 777
+      "sha256": "40c1e5f76edcbfbdf18f203dae2f295cce191b6af670436aeff5bc65d74d1a6b",
+      "bytes": 799
     },
     "mcp/types/workflow-tool-edition.d.ts": {
-      "sha256": "e7228be685155777e3035963056edd503e6660985fe7b5f17032402ca6582c8c",
-      "bytes": 1494
+      "sha256": "ebde63f0ea9de501946d75e050c9676c03d08b77b27ad858d88600249e480f6c",
+      "bytes": 1513
     },
     "mcp/types/workflow-tool-edition.js": {
       "sha256": "2dfd26acd3da2c249b728e7fc48c7eab3dc675f786e7689dbdeec53c25589369",
@@ -718,16 +726,16 @@
       "bytes": 408
     },
     "mcp/v2/tool-registry.js": {
-      "sha256": "719429102bc33c9e5bcd7cf38b0242ecc038484de4159811fbe9b0efa2ebc460",
-      "bytes": 2623
+      "sha256": "4b192604ddafd986416865041db7e395d205da6fa1d398bec07646900f6ce28c",
+      "bytes": 3078
     },
     "mcp/v2/tools.d.ts": {
-      "sha256": "8fba15da4a60a46ed803046f9b61ea0b8947967880563562473d8a87de68d27c",
-      "bytes": 3600
+      "sha256": "5da50237fcbce6240737441d134c8070256a23649b387d5c3438b41b2705905e",
+      "bytes": 4156
     },
     "mcp/v2/tools.js": {
-      "sha256": "93f33152aebe0cbeb92daa727a3dc43ccb3f4cc1001e7564fdd7b31ee78b2475",
-      "bytes": 5743
+      "sha256": "5c9b958f1a9eb609557ed5867fc9ea131a2a0a4aaf52ff05a38246dffe2b359d",
+      "bytes": 6435
     },
     "mcp/validation/bounded-json.d.ts": {
       "sha256": "82203ac6123d5c6989606c3b5405aaea99ab829c8958835f9ae3ba45b8bc8fd5",
@@ -1529,13 +1537,21 @@
       "sha256": "02d0ad7e3b8c615c6fa3fead6698664d282b2375ea3fc8bd563c12cc7853691c",
       "bytes": 3012
     },
+    "v2/infra/local/directory-listing/index.d.ts": {
+      "sha256": "18fd3d9d74c5541fe95f01be6dd276c6cf6ecf1426fcd0ad1e695d756d9ef93e",
+      "bytes": 429
+    },
+    "v2/infra/local/directory-listing/index.js": {
+      "sha256": "1930cb982b9034f46751a000011ea069b6e03becd898973afad4b74e6ebc1759",
+      "bytes": 566
+    },
     "v2/infra/local/fs/index.d.ts": {
-      "sha256": "d830aed74ebb3372ea5efa21ec96680cd188fc76dea6078286f5788b3736d2bf",
-      "bytes": 1252
+      "sha256": "fe3f06badea2d62e9ade3954f716d0b7aa4778c4d49e5fb9f6f58db6d2e9429a",
+      "bytes": 1323
     },
     "v2/infra/local/fs/index.js": {
-      "sha256": "97ce973a4bd48aa43e890fb18dc7b8c8b3f8451400539bf15b4c79f3680e2ba3",
-      "bytes": 7045
+      "sha256": "05fcd1345b3f003c19a13ee8db4ef657f23815c253e4fa36fa4bd7092f0a0b68",
+      "bytes": 7179
     },
     "v2/infra/local/hmac-sha256/index.d.ts": {
       "sha256": "dda3865510dfaf2f13947410d998da6ffecc9a2e728b3574f81e69d5db859815",
@@ -1593,6 +1609,14 @@
       "sha256": "53b9ee8545d99e23cfeecb12b39d202fc552c3e89de9fe71b5d1aaaf9afa6d95",
       "bytes": 29559
     },
+    "v2/infra/local/session-summary-provider/index.d.ts": {
+      "sha256": "8843c26694d12147c322a4ff1f220cef53774c1ea7087241cb6badd12a360fda",
+      "bytes": 1069
+    },
+    "v2/infra/local/session-summary-provider/index.js": {
+      "sha256": "d75b34ff09b4e5b0e4cd1b75b67c4efe643db0231afc919da54c29034c1c5c1d",
+      "bytes": 5566
+    },
     "v2/infra/local/sha256/index.d.ts": {
       "sha256": "8a727b7e54a38275ca6f9f1b8730f97cfc0a212df035df1bdc58e716e6824230",
       "bytes": 246
@@ -1665,9 +1689,17 @@
       "sha256": "d43aa81f5bc89faa359e0f97c814ba25155591ff078fbb9bfd40f8c7c9683230",
       "bytes": 77
     },
+    "v2/ports/directory-listing.port.d.ts": {
+      "sha256": "3184229b7793bbd3100611c6308d33a96145c4dc63ba451d8c29ff507084e7b4",
+      "bytes": 207
+    },
+    "v2/ports/directory-listing.port.js": {
+      "sha256": "d43aa81f5bc89faa359e0f97c814ba25155591ff078fbb9bfd40f8c7c9683230",
+      "bytes": 77
+    },
     "v2/ports/fs.port.d.ts": {
-      "sha256": "e752765aa1154de19c720590410a370c3ae485d73363dd66cf9cc17fcf75c103",
-      "bytes": 1534
+      "sha256": "e4d80716cbfe86352f9017480af31f21e25dfea97c7449b384fe64237bba961d",
+      "bytes": 1605
     },
     "v2/ports/fs.port.js": {
       "sha256": "d43aa81f5bc89faa359e0f97c814ba25155591ff078fbb9bfd40f8c7c9683230",
@@ -1721,6 +1753,14 @@
       "sha256": "d43aa81f5bc89faa359e0f97c814ba25155591ff078fbb9bfd40f8c7c9683230",
       "bytes": 77
     },
+    "v2/ports/session-summary-provider.port.d.ts": {
+      "sha256": "41861cb0e70ca81e0d931d9f504226c9c7361f59db21a8beab95c2b8ed13cb57",
+      "bytes": 400
+    },
+    "v2/ports/session-summary-provider.port.js": {
+      "sha256": "d43aa81f5bc89faa359e0f97c814ba25155591ff078fbb9bfd40f8c7c9683230",
+      "bytes": 77
+    },
     "v2/ports/sha256.port.d.ts": {
       "sha256": "2ca3e0558992a96614d005582e1f38435de4335df82f8231f69eabf191272022",
       "bytes": 145
@@ -1817,6 +1857,14 @@
       "sha256": "c8190e4899ba9695c7c7a9e58e872d4a56c90dcb4dfde659d6c2801a8cb895a7",
       "bytes": 732
     },
+    "v2/projections/resume-ranking.d.ts": {
+      "sha256": "50ef48d0b195f89f01c0051be453666e6a680e356ca9c328a754aced90ee8d7a",
+      "bytes": 2337
+    },
+    "v2/projections/resume-ranking.js": {
+      "sha256": "4253bd05c81e4b5a95b3472cca9ea3c2d7e9e28fdaabe95c984a1165ecc3a69c",
+      "bytes": 4232
+    },
     "v2/projections/run-context.d.ts": {
       "sha256": "7bdc4b2bacfb4b42005b7a83d7ddaf8a8d414bed90b948c02dbeeacd741b31cc",
       "bytes": 909
@@ -1857,6 +1905,14 @@
       "sha256": "6ea788b80605db6d2057b3d5e520be48ace8afe6d8f37bf55cef00ba1471a6b7",
       "bytes": 1935
     },
+    "v2/usecases/enumerate-sessions.d.ts": {
+      "sha256": "6043d64b45360dfc6a15b822d9f013a0832127596706bf81569dfce256236d2d",
+      "bytes": 499
+    },
+    "v2/usecases/enumerate-sessions.js": {
+      "sha256": "99e135a7c7411ce850c9dd89963ef6a05d3488078d6c6b2c540cb2d2043a2e89",
+      "bytes": 526
+    },
     "v2/usecases/execution-session-gate.d.ts": {
       "sha256": "339c4a8e02a77416e725e063a57d39a20788244498ae2c7a31dc48d111af6280",
       "bytes": 2084
@@ -1880,6 +1936,14 @@
     "v2/usecases/import-session.js": {
       "sha256": "9b9c8922cc2e6d6904f564c35ff0e402a2e755187f36ee7e54e76826f51bed5c",
       "bytes": 2788
+    },
+    "v2/usecases/resume-session.d.ts": {
+      "sha256": "02eec4908e02dc591bff06b0d38d686aad64719694fd353670b2b1d17d8f9543",
+      "bytes": 434
+    },
+    "v2/usecases/resume-session.js": {
+      "sha256": "db50776bbbd18f0a07c0c1b0d94689f78596d980824f4fe73f5cbe47a62d0d60",
+      "bytes": 393
     }
   }
 }

package/dist/mcp/handlers/v2-resume.d.ts

@@ -0,0 +1,8 @@
+import type { z } from 'zod';
+import type { V2ResumeSessionInput } from '../v2/tools.js';
+import type { ToolContext, ToolResult } from '../types.js';
+import { V2ResumeSessionOutputSchema } from '../output-schemas.js';
+type ResumeInput = z.infer<typeof V2ResumeSessionInput>;
+type ResumeOutput = z.infer<typeof V2ResumeSessionOutputSchema>;
+export declare function handleV2ResumeSession(input: ResumeInput, ctx: ToolContext): Promise<ToolResult<ResumeOutput>>;
+export {};

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

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleV2ResumeSession = handleV2ResumeSession;
+const types_js_1 = require("../types.js");
+const output_schemas_js_1 = require("../output-schemas.js");
+const v2_token_ops_js_1 = require("./v2-token-ops.js");
+const index_js_1 = require("../../v2/durable-core/ids/index.js");
+const resume_session_js_1 = require("../../v2/usecases/resume-session.js");
+function anchorValue(anchors, key) {
+    const anchor = anchors.find((a) => a.key === key);
+    return anchor?.value;
+}
+async function handleV2ResumeSession(input, ctx) {
+    const v2 = ctx.v2;
+    if (!v2) {
+        return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', 'v2 dependencies not available');
+    }
+    if (!v2.sessionSummaryProvider) {
+        return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', 'resume_session requires sessionSummaryProvider port');
+    }
+    let anchors = [];
+    if (v2.workspaceAnchor) {
+        const anchorRes = await v2.workspaceAnchor.resolveAnchors();
+        if (anchorRes.isOk()) {
+            anchors = anchorRes.value;
+        }
+    }
+    const query = {
+        gitHeadSha: input.gitHeadSha ?? anchorValue(anchors, 'git_head_sha'),
+        gitBranch: input.gitBranch ?? anchorValue(anchors, 'git_branch'),
+        freeTextQuery: input.query,
+    };
+    const resumeResult = await (0, resume_session_js_1.resumeSession)(query, v2.sessionSummaryProvider);
+    if (resumeResult.isErr()) {
+        return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', `Resume failed: ${resumeResult.error.message}`);
+    }
+    const candidates = resumeResult.value;
+    const outputCandidates = [];
+    for (const candidate of candidates) {
+        const stateTokenRes = (0, v2_token_ops_js_1.signTokenOrErr)({
+            payload: {
+                tokenVersion: 1,
+                tokenKind: 'state',
+                sessionId: candidate.sessionId,
+                runId: (0, index_js_1.asRunId)(candidate.runId),
+                nodeId: (0, index_js_1.asNodeId)(candidate.preferredTipNodeId),
+                workflowHashRef: (0, index_js_1.asWorkflowHashRef)(''),
+            },
+            ports: v2.tokenCodecPorts,
+        });
+        if (stateTokenRes.isErr()) {
+            continue;
+        }
+        outputCandidates.push({
+            sessionId: candidate.sessionId,
+            runId: candidate.runId,
+            stateToken: stateTokenRes.value,
+            snippet: candidate.snippet,
+            whyMatched: [...candidate.whyMatched],
+        });
+    }
+    const output = output_schemas_js_1.V2ResumeSessionOutputSchema.parse({
+        candidates: outputCandidates,
+        totalEligible: candidates.length,
+    });
+    return {
+        type: 'success',
+        data: output,
+    };
+}

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

@@ -1067,6 +1067,46 @@ export declare const V2ContinueWorkflowOutputSchema: z.ZodEffects<z.ZodDiscrimin
     retryable?: boolean | undefined;
     retryAckToken?: string | undefined;
 }>;
+export declare const V2ResumeSessionOutputSchema: z.ZodObject<{
+    candidates: z.ZodArray<z.ZodObject<{
+        sessionId: z.ZodString;
+        runId: z.ZodString;
+        stateToken: z.ZodString;
+        snippet: z.ZodString;
+        whyMatched: z.ZodArray<z.ZodEnum<["matched_head_sha", "matched_branch", "matched_notes", "matched_workflow_id", "recency_fallback"]>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        sessionId: string;
+        runId: string;
+        stateToken: string;
+        snippet: string;
+        whyMatched: ("matched_head_sha" | "matched_branch" | "matched_notes" | "matched_workflow_id" | "recency_fallback")[];
+    }, {
+        sessionId: string;
+        runId: string;
+        stateToken: string;
+        snippet: string;
+        whyMatched: ("matched_head_sha" | "matched_branch" | "matched_notes" | "matched_workflow_id" | "recency_fallback")[];
+    }>, "many">;
+    totalEligible: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    candidates: {
+        sessionId: string;
+        runId: string;
+        stateToken: string;
+        snippet: string;
+        whyMatched: ("matched_head_sha" | "matched_branch" | "matched_notes" | "matched_workflow_id" | "recency_fallback")[];
+    }[];
+    totalEligible: number;
+}, {
+    candidates: {
+        sessionId: string;
+        runId: string;
+        stateToken: string;
+        snippet: string;
+        whyMatched: ("matched_head_sha" | "matched_branch" | "matched_notes" | "matched_workflow_id" | "recency_fallback")[];
+    }[];
+    totalEligible: number;
+}>;
 export declare const V2CheckpointWorkflowOutputSchema: z.ZodObject<{
     checkpointNodeId: z.ZodString;
     stateToken: z.ZodString;

package/dist/mcp/output-schemas.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OpenDashboardOutputSchema = exports.ReadSessionSchemaOutputSchema = exports.ReadSessionOutputSchema = exports.UpdateSessionOutputSchema = exports.CreateSessionOutputSchema = exports.V2StartWorkflowOutputSchema = exports.V2CheckpointWorkflowOutputSchema = exports.V2ContinueWorkflowOutputSchema = exports.V2BlockerReportSchema = exports.V2NextCallSchema = exports.V2NextIntentSchema = exports.V2PreferencesSchema = exports.V2PendingStepSchema = exports.V2WorkflowInspectOutputSchema = exports.V2WorkflowListOutputSchema = exports.V2WorkflowListItemSchema = exports.WorkflowGetSchemaOutputSchema = exports.WorkflowValidateJsonOutputSchema = exports.WorkflowNextOutputSchema = exports.WorkflowGetOutputSchema = exports.WorkflowListOutputSchema = exports.WorkflowSummarySchema = exports.JsonValueSchema = void 0;
+exports.OpenDashboardOutputSchema = exports.ReadSessionSchemaOutputSchema = exports.ReadSessionOutputSchema = exports.UpdateSessionOutputSchema = exports.CreateSessionOutputSchema = exports.V2StartWorkflowOutputSchema = exports.V2CheckpointWorkflowOutputSchema = exports.V2ResumeSessionOutputSchema = exports.V2ContinueWorkflowOutputSchema = exports.V2BlockerReportSchema = exports.V2NextCallSchema = exports.V2NextIntentSchema = exports.V2PreferencesSchema = exports.V2PendingStepSchema = exports.V2WorkflowInspectOutputSchema = exports.V2WorkflowListOutputSchema = exports.V2WorkflowListItemSchema = exports.WorkflowGetSchemaOutputSchema = exports.WorkflowValidateJsonOutputSchema = exports.WorkflowNextOutputSchema = exports.WorkflowGetOutputSchema = exports.WorkflowListOutputSchema = exports.WorkflowSummarySchema = exports.JsonValueSchema = void 0;
 const zod_1 = require("zod");
 const state_js_1 = require("../domain/execution/state.js");
 const JsonPrimitiveSchema = zod_1.z.union([zod_1.z.string(), zod_1.z.number(), zod_1.z.boolean(), zod_1.z.null()]);
@@ -204,6 +204,22 @@ exports.V2ContinueWorkflowOutputSchema = zod_1.z.discriminatedUnion('kind', [
     V2ContinueWorkflowOkSchema,
     V2ContinueWorkflowBlockedSchema,
 ]).refine((data) => (data.pending ? data.ackToken != null : true), { message: 'ackToken is required when a pending step exists' });
+exports.V2ResumeSessionOutputSchema = zod_1.z.object({
+    candidates: zod_1.z.array(zod_1.z.object({
+        sessionId: zod_1.z.string().min(1),
+        runId: zod_1.z.string().min(1),
+        stateToken: zod_1.z.string().regex(/^st1[023456789acdefghjklmnpqrstuvwxyz]+$/, 'Invalid stateToken format'),
+        snippet: zod_1.z.string().max(1024),
+        whyMatched: zod_1.z.array(zod_1.z.enum([
+            'matched_head_sha',
+            'matched_branch',
+            'matched_notes',
+            'matched_workflow_id',
+            'recency_fallback',
+        ])),
+    })).max(5),
+    totalEligible: zod_1.z.number().int().min(0),
+});
 exports.V2CheckpointWorkflowOutputSchema = zod_1.z.object({
     checkpointNodeId: zod_1.z.string().min(1),
     stateToken: zod_1.z.string().regex(/^st1[023456789acdefghjklmnpqrstuvwxyz]+$/, 'Invalid stateToken format'),

package/dist/mcp/server.js

@@ -41,6 +41,8 @@ const tokens_js_1 = require("../di/tokens.js");
 const assert_never_js_1 = require("../runtime/assert-never.js");
 const token_codec_ports_js_1 = require("../v2/durable-core/tokens/token-codec-ports.js");
 const index_js_1 = require("../v2/infra/local/workspace-anchor/index.js");
+const index_js_2 = require("../v2/infra/local/directory-listing/index.js");
+const index_js_3 = require("../v2/infra/local/session-summary-provider/index.js");
 const tool_factory_js_1 = require("./tool-factory.js");
 const handler_factory_js_1 = require("./handler-factory.js");
 const workflow_tool_edition_selector_js_1 = require("./workflow-tool-edition-selector.js");
@@ -87,6 +89,9 @@ async function createToolContext() {
                 base32,
                 bech32m,
             });
+            const dataDir = container_js_1.container.resolve(tokens_js_1.DI.V2.DataDir);
+            const fsPort = container_js_1.container.resolve(tokens_js_1.DI.V2.FileSystem);
+            const directoryListing = new index_js_2.LocalDirectoryListingV2(fsPort);
             v2 = {
                 gate,
                 sessionStore,
@@ -97,6 +102,13 @@ async function createToolContext() {
                 idFactory,
                 tokenCodecPorts,
                 workspaceAnchor: new index_js_1.LocalWorkspaceAnchorV2(process.cwd()),
+                dataDir,
+                directoryListing,
+                sessionSummaryProvider: new index_js_3.LocalSessionSummaryProviderV2({
+                    directoryListing,
+                    dataDir,
+                    sessionStore,
+                }),
             };
             console.error('[FeatureFlags] v2 tools enabled');
         }

package/dist/mcp/tool-descriptions.js

@@ -123,6 +123,18 @@ Requires: checkpointToken (from the most recent start_workflow or continue_workf
 Idempotent: calling with the same checkpointToken multiple times is safe and returns the same result.
 
 Returns: checkpointNodeId + a fresh stateToken.`,
+        resume_session: `Find and reconnect to an existing workflow session (WorkRail v2, feature-flagged).
+
+Use this when you need to resume a previously started workflow but don't have the stateToken (e.g., new chat, lost context).
+
+WorkRail ranks sessions using a 5-tier matching algorithm:
+1. Exact git HEAD SHA match
+2. Git branch match (exact or prefix)
+3. Free text match against session notes
+4. Free text match against workflow ID
+5. Recency fallback
+
+Returns: Up to 5 ranked candidates, each with a stateToken you can use with continue_workflow.`,
     },
     authoritative: {
         discover_workflows: `Check for workflows that apply to the user's request. Workflows are the user's pre-defined instructions that you MUST follow when they exist.
@@ -268,5 +280,15 @@ Creates a durable checkpoint without advancing. Use for long-running steps to sa
 Requires: checkpointToken from the most recent response. Idempotent.
 
 Returns: checkpointNodeId + fresh stateToken.`,
+        resume_session: `Find and reconnect to an existing workflow session (WorkRail v2, feature-flagged).
+
+Call this when resuming a workflow without a stateToken. WorkRail ranks sessions deterministically:
+1. Exact git HEAD SHA match (tier 1)
+2. Git branch match (tier 2)
+3. Notes content match (tier 3)
+4. Workflow ID match (tier 4)
+5. Recency (tier 5)
+
+Returns: Up to 5 candidates with stateTokens. Use the best match's stateToken with continue_workflow.`,
     },
 };

package/dist/mcp/tools.js

@@ -87,6 +87,11 @@ exports.WORKFLOW_TOOL_ANNOTATIONS = {
         destructiveHint: false,
         idempotentHint: true,
     },
+    resume_session: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+    },
 };
 exports.WORKFLOW_TOOL_TITLES = {
     discover_workflows: 'Discover Available Workflows',
@@ -99,6 +104,7 @@ exports.WORKFLOW_TOOL_TITLES = {
     start_workflow: 'Start Workflow (v2)',
     continue_workflow: 'Continue Workflow (v2)',
     checkpoint_workflow: 'Checkpoint Workflow (v2)',
+    resume_session: 'Resume Session (v2)',
 };
 exports.CreateSessionInput = zod_1.z.object({
     workflowId: zod_1.z

package/dist/mcp/types/tool-description-types.d.ts

@@ -1,6 +1,6 @@
 export declare const DESCRIPTION_MODES: readonly ["standard", "authoritative"];
 export type DescriptionMode = typeof DESCRIPTION_MODES[number];
-export declare const WORKFLOW_TOOL_NAMES: readonly ["discover_workflows", "preview_workflow", "advance_workflow", "validate_workflow", "get_workflow_schema", "list_workflows", "inspect_workflow", "start_workflow", "continue_workflow", "checkpoint_workflow"];
+export declare const WORKFLOW_TOOL_NAMES: readonly ["discover_workflows", "preview_workflow", "advance_workflow", "validate_workflow", "get_workflow_schema", "list_workflows", "inspect_workflow", "start_workflow", "continue_workflow", "checkpoint_workflow", "resume_session"];
 export type WorkflowToolName = typeof WORKFLOW_TOOL_NAMES[number];
 export type ToolDescriptionMap = Readonly<Record<WorkflowToolName, string>>;
 export type DescriptionsByMode = Readonly<Record<DescriptionMode, ToolDescriptionMap>>;

package/dist/mcp/types/tool-description-types.js

@@ -18,6 +18,7 @@ exports.WORKFLOW_TOOL_NAMES = [
     'start_workflow',
     'continue_workflow',
     'checkpoint_workflow',
+    'resume_session',
 ];
 function isDescriptionMode(value) {
     return exports.DESCRIPTION_MODES.includes(value);

package/dist/mcp/types/workflow-tool-edition.d.ts

@@ -2,7 +2,7 @@ import type { z } from 'zod';
 import type { ToolDefinition } from '../tool-factory.js';
 import type { ToolContext } from '../types.js';
 export type V1WorkflowToolName = 'discover_workflows' | 'preview_workflow' | 'advance_workflow' | 'validate_workflow' | 'get_workflow_schema';
-export type V2WorkflowToolName = 'list_workflows' | 'inspect_workflow' | 'start_workflow' | 'continue_workflow' | 'checkpoint_workflow';
+export type V2WorkflowToolName = 'list_workflows' | 'inspect_workflow' | 'start_workflow' | 'continue_workflow' | 'checkpoint_workflow' | 'resume_session';
 export type McpCallToolResult = {
     readonly content: ReadonlyArray<{
         readonly type: 'text';

package/dist/mcp/types.d.ts

@@ -13,6 +13,9 @@ import type { IdFactoryV2 } from '../v2/infra/local/id-factory/index.js';
 import type { JsonValue } from './output-schemas.js';
 import type { TokenCodecPorts } from '../v2/durable-core/tokens/token-codec-ports.js';
 import type { WorkspaceAnchorPortV2 } from '../v2/ports/workspace-anchor.port.js';
+import type { DataDirPortV2 } from '../v2/ports/data-dir.port.js';
+import type { DirectoryListingPortV2 } from '../v2/ports/directory-listing.port.js';
+import type { SessionSummaryProviderPortV2 } from '../v2/ports/session-summary-provider.port.js';
 export interface SessionHealthDetails {
     readonly health: SessionHealthV2;
 }
@@ -53,6 +56,9 @@ export interface V2Dependencies {
     readonly idFactory: IdFactoryV2;
     readonly tokenCodecPorts: TokenCodecPorts;
     readonly workspaceAnchor?: WorkspaceAnchorPortV2;
+    readonly dataDir?: DataDirPortV2;
+    readonly directoryListing?: DirectoryListingPortV2;
+    readonly sessionSummaryProvider?: SessionSummaryProviderPortV2;
 }
 export interface ToolContext {
     readonly workflowService: WorkflowService;

package/dist/mcp/v2/tool-registry.js

@@ -6,6 +6,7 @@ const tools_js_1 = require("./tools.js");
 const v2_execution_js_1 = require("../handlers/v2-execution.js");
 const v2_workflow_js_1 = require("../handlers/v2-workflow.js");
 const v2_checkpoint_js_1 = require("../handlers/v2-checkpoint.js");
+const v2_resume_js_1 = require("../handlers/v2-resume.js");
 function buildV2ToolRegistry(buildTool) {
     const tools = [
         buildTool({
@@ -38,6 +39,12 @@ function buildV2ToolRegistry(buildTool) {
             inputSchema: tools_js_1.V2CheckpointWorkflowInput,
             annotations: tools_js_1.V2_TOOL_ANNOTATIONS.checkpoint_workflow,
         }),
+        buildTool({
+            name: 'resume_session',
+            title: tools_js_1.V2_TOOL_TITLES.resume_session,
+            inputSchema: tools_js_1.V2ResumeSessionInput,
+            annotations: tools_js_1.V2_TOOL_ANNOTATIONS.resume_session,
+        }),
     ];
     const handlers = {
         list_workflows: (0, handler_factory_js_1.createHandler)(tools_js_1.V2ListWorkflowsInput, v2_workflow_js_1.handleV2ListWorkflows),
@@ -45,6 +52,7 @@ function buildV2ToolRegistry(buildTool) {
         start_workflow: (0, handler_factory_js_1.createHandler)(tools_js_1.V2StartWorkflowInput, v2_execution_js_1.handleV2StartWorkflow),
         continue_workflow: (0, handler_factory_js_1.createHandler)(tools_js_1.V2ContinueWorkflowInput, v2_execution_js_1.handleV2ContinueWorkflow),
         checkpoint_workflow: (0, handler_factory_js_1.createHandler)(tools_js_1.V2CheckpointWorkflowInput, v2_checkpoint_js_1.handleV2CheckpointWorkflow),
+        resume_session: (0, handler_factory_js_1.createHandler)(tools_js_1.V2ResumeSessionInput, v2_resume_js_1.handleV2ResumeSession),
     };
     return { tools, handlers };
 }

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

@@ -77,6 +77,20 @@ export declare const V2ContinueWorkflowInput: z.ZodEffects<z.ZodObject<{
     ackToken?: string | undefined;
 }>;
 export type V2ContinueWorkflowInput = z.infer<typeof V2ContinueWorkflowInput>;
+export declare const V2ResumeSessionInput: z.ZodObject<{
+    query: z.ZodOptional<z.ZodString>;
+    gitBranch: z.ZodOptional<z.ZodString>;
+    gitHeadSha: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    query?: string | undefined;
+    gitBranch?: string | undefined;
+    gitHeadSha?: string | undefined;
+}, {
+    query?: string | undefined;
+    gitBranch?: string | undefined;
+    gitHeadSha?: string | undefined;
+}>;
+export type V2ResumeSessionInput = z.infer<typeof V2ResumeSessionInput>;
 export declare const V2CheckpointWorkflowInput: z.ZodObject<{
     checkpointToken: z.ZodString;
 }, "strict", z.ZodTypeAny, {
@@ -91,5 +105,6 @@ export declare const V2_TOOL_TITLES: {
     readonly start_workflow: "Start Workflow (v2)";
     readonly continue_workflow: "Continue Workflow (v2)";
     readonly checkpoint_workflow: "Checkpoint Workflow (v2)";
+    readonly resume_session: "Resume Session (v2)";
 };
 export declare const V2_TOOL_ANNOTATIONS: Readonly<Record<keyof typeof V2_TOOL_TITLES, ToolAnnotations>>;

package/dist/mcp/v2/tools.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.V2_TOOL_ANNOTATIONS = exports.V2_TOOL_TITLES = exports.V2CheckpointWorkflowInput = exports.V2ContinueWorkflowInput = exports.V2StartWorkflowInput = exports.V2InspectWorkflowInput = exports.V2ListWorkflowsInput = void 0;
+exports.V2_TOOL_ANNOTATIONS = exports.V2_TOOL_TITLES = exports.V2CheckpointWorkflowInput = exports.V2ResumeSessionInput = exports.V2ContinueWorkflowInput = exports.V2StartWorkflowInput = exports.V2InspectWorkflowInput = exports.V2ListWorkflowsInput = void 0;
 const zod_1 = require("zod");
 exports.V2ListWorkflowsInput = zod_1.z.object({});
 exports.V2InspectWorkflowInput = zod_1.z.object({
@@ -54,6 +54,11 @@ exports.V2ContinueWorkflowInput = zod_1.z.object({
         });
     }
 });
+exports.V2ResumeSessionInput = zod_1.z.object({
+    query: zod_1.z.string().max(256).optional().describe('Free text search to find a relevant session. Matches against recap notes and workflow IDs.'),
+    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.'),
+}).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. ' +
         'Creates a checkpoint on the current step without advancing. Idempotent — calling with the same token is safe.'),
@@ -64,6 +69,7 @@ exports.V2_TOOL_TITLES = {
     start_workflow: 'Start Workflow (v2)',
     continue_workflow: 'Continue Workflow (v2)',
     checkpoint_workflow: 'Checkpoint Workflow (v2)',
+    resume_session: 'Resume Session (v2)',
 };
 exports.V2_TOOL_ANNOTATIONS = {
     list_workflows: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
@@ -71,4 +77,5 @@ exports.V2_TOOL_ANNOTATIONS = {
     start_workflow: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
     continue_workflow: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
     checkpoint_workflow: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+    resume_session: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
 };

package/dist/v2/infra/local/directory-listing/index.d.ts

@@ -0,0 +1,8 @@
+import type { ResultAsync } from 'neverthrow';
+import type { FsError, FileSystemPortV2 } from '../../../ports/fs.port.js';
+import type { DirectoryListingPortV2 } from '../../../ports/directory-listing.port.js';
+export declare class LocalDirectoryListingV2 implements DirectoryListingPortV2 {
+    private readonly fs;
+    constructor(fs: FileSystemPortV2);
+    readdir(dirPath: string): ResultAsync<readonly string[], FsError>;
+}

package/dist/v2/infra/local/directory-listing/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalDirectoryListingV2 = void 0;
+const neverthrow_1 = require("neverthrow");
+class LocalDirectoryListingV2 {
+    constructor(fs) {
+        this.fs = fs;
+    }
+    readdir(dirPath) {
+        return this.fs.readdir(dirPath).orElse((e) => {
+            if (e.code === 'FS_NOT_FOUND') {
+                return (0, neverthrow_1.okAsync)([]);
+            }
+            return (0, neverthrow_1.errAsync)(e);
+        });
+    }
+}
+exports.LocalDirectoryListingV2 = LocalDirectoryListingV2;

package/dist/v2/infra/local/fs/index.d.ts

@@ -23,4 +23,5 @@ export declare class NodeFileSystemV2 implements FileSystemPortV2 {
     stat(filePath: string): ResultAsync<{
         readonly sizeBytes: number;
     }, FsError>;
+    readdir(dirPath: string): ResultAsync<readonly string[], FsError>;
 }

package/dist/v2/infra/local/fs/index.js

@@ -159,5 +159,8 @@ class NodeFileSystemV2 {
     stat(filePath) {
         return neverthrow_1.ResultAsync.fromPromise(fs.stat(filePath), (e) => mapFsError(e, filePath)).map((s) => ({ sizeBytes: s.size }));
     }
+    readdir(dirPath) {
+        return neverthrow_1.ResultAsync.fromPromise(fs.readdir(dirPath), (e) => mapFsError(e, dirPath));
+    }
 }
 exports.NodeFileSystemV2 = NodeFileSystemV2;

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

@@ -0,0 +1,18 @@
+import type { ResultAsync } from 'neverthrow';
+import type { DirectoryListingPortV2 } from '../../../ports/directory-listing.port.js';
+import type { DataDirPortV2 } from '../../../ports/data-dir.port.js';
+import type { SessionEventLogReadonlyStorePortV2 } from '../../../ports/session-event-log-store.port.js';
+import type { SessionSummaryProviderPortV2, SessionSummaryError } from '../../../ports/session-summary-provider.port.js';
+import type { HealthySessionSummary } from '../../../projections/resume-ranking.js';
+export interface LocalSessionSummaryProviderPorts {
+    readonly directoryListing: DirectoryListingPortV2;
+    readonly dataDir: DataDirPortV2;
+    readonly sessionStore: SessionEventLogReadonlyStorePortV2;
+}
+export declare class LocalSessionSummaryProviderV2 implements SessionSummaryProviderPortV2 {
+    private readonly ports;
+    constructor(ports: LocalSessionSummaryProviderPorts);
+    loadHealthySummaries(): ResultAsync<readonly HealthySessionSummary[], SessionSummaryError>;
+    private collectHealthySummaries;
+    private tryLoadSummary;
+}

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

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalSessionSummaryProviderV2 = void 0;
+const neverthrow_1 = require("neverthrow");
+const resume_ranking_js_1 = require("../../../projections/resume-ranking.js");
+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 MAX_SESSIONS_TO_SCAN = 50;
+class LocalSessionSummaryProviderV2 {
+    constructor(ports) {
+        this.ports = ports;
+    }
+    loadHealthySummaries() {
+        return (0, enumerate_sessions_js_1.enumerateSessions)({
+            directoryListing: this.ports.directoryListing,
+            dataDir: this.ports.dataDir,
+        })
+            .mapErr((fsErr) => ({
+            code: 'SESSION_SUMMARY_ENUMERATION_FAILED',
+            message: `Failed to enumerate sessions: ${fsErr.message}`,
+        }))
+            .andThen((sessionIds) => {
+            const capped = sessionIds.slice(0, MAX_SESSIONS_TO_SCAN);
+            return this.collectHealthySummaries(capped);
+        });
+    }
+    collectHealthySummaries(sessionIds) {
+        const summaries = [];
+        let chain = (0, neverthrow_1.okAsync)(undefined);
+        for (const sessionId of sessionIds) {
+            chain = chain.andThen(() => this.tryLoadSummary(sessionId).map((summary) => {
+                if (summary !== null) {
+                    summaries.push(summary);
+                }
+            }));
+        }
+        return chain.map(() => summaries);
+    }
+    tryLoadSummary(sessionId) {
+        return this.ports.sessionStore
+            .load(sessionId)
+            .map((truth) => {
+            const healthRes = (0, session_health_js_1.projectSessionHealthV2)(truth);
+            if (healthRes.isErr())
+                return null;
+            if (healthRes.value.kind !== 'healthy')
+                return null;
+            const dagRes = (0, run_dag_js_1.projectRunDagV2)(truth.events);
+            if (dagRes.isErr())
+                return null;
+            const runs = Object.values(dagRes.value.runsById);
+            if (runs.length === 0)
+                return null;
+            const runsWithActivity = runs
+                .filter((r) => r.preferredTipNodeId !== null)
+                .map((r) => {
+                const tipNode = r.nodesById[r.preferredTipNodeId];
+                const maxEventIndex = tipNode ? tipNode.createdAtEventIndex : 0;
+                return { run: r, lastActivityEventIndex: maxEventIndex };
+            })
+                .sort((a, b) => b.lastActivityEventIndex - a.lastActivityEventIndex);
+            if (runsWithActivity.length === 0)
+                return null;
+            const bestRun = runsWithActivity[0];
+            const run = bestRun.run;
+            const outputsRes = (0, node_outputs_js_1.projectNodeOutputsV2)(truth.events);
+            const recapSnippet = outputsRes.isOk() && run.preferredTipNodeId
+                ? extractRecapFromOutputs(outputsRes.value, run.preferredTipNodeId)
+                : null;
+            const observations = extractObservations(truth.events);
+            const workflow = extractWorkflowIdentity(truth.events, run.runId);
+            return {
+                sessionId,
+                runId: run.runId,
+                preferredTip: {
+                    nodeId: run.preferredTipNodeId,
+                    lastActivityEventIndex: bestRun.lastActivityEventIndex,
+                },
+                recapSnippet,
+                observations,
+                workflow,
+            };
+        })
+            .orElse(() => (0, neverthrow_1.okAsync)(null));
+    }
+}
+exports.LocalSessionSummaryProviderV2 = LocalSessionSummaryProviderV2;
+function extractRecapFromOutputs(outputs, nodeId) {
+    const nodeView = outputs.nodesById[nodeId];
+    if (!nodeView)
+        return null;
+    const recapOutputs = nodeView.currentByChannel['recap'];
+    if (!recapOutputs || recapOutputs.length === 0)
+        return null;
+    const latest = recapOutputs[recapOutputs.length - 1];
+    if (latest.payload.payloadKind !== 'notes')
+        return null;
+    const markdown = latest.payload.notesMarkdown;
+    if (!markdown || typeof markdown !== 'string')
+        return null;
+    return (0, resume_ranking_js_1.asRecapSnippet)(markdown);
+}
+function extractObservations(events) {
+    let gitHeadSha = null;
+    let gitBranch = null;
+    let repoRootHash = null;
+    for (const event of events) {
+        if (event.kind !== 'observation_recorded')
+            continue;
+        const data = event.data;
+        switch (data.key) {
+            case 'git_head_sha':
+                gitHeadSha = data.value.value;
+                break;
+            case 'git_branch':
+                gitBranch = data.value.value;
+                break;
+            case 'repo_root_hash':
+                repoRootHash = data.value.value;
+                break;
+        }
+    }
+    return { gitHeadSha, gitBranch, repoRootHash };
+}
+function extractWorkflowIdentity(events, runId) {
+    for (const event of events) {
+        if (event.kind !== 'run_started')
+            continue;
+        const scope = event.scope;
+        if (scope?.runId !== runId)
+            continue;
+        const data = event.data;
+        return {
+            workflowId: data.workflowId ?? null,
+            workflowName: null,
+        };
+    }
+    return { workflowId: null, workflowName: null };
+}

package/dist/v2/ports/directory-listing.port.d.ts

@@ -0,0 +1,5 @@
+import type { ResultAsync } from 'neverthrow';
+import type { FsError } from './fs.port.js';
+export interface DirectoryListingPortV2 {
+    readdir(dirPath: string): ResultAsync<readonly string[], FsError>;
+}

package/dist/v2/ports/directory-listing.port.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/v2/ports/fs.port.d.ts

@@ -38,4 +38,5 @@ export interface FileSystemPortV2 {
     stat(filePath: string): ResultAsync<{
         readonly sizeBytes: number;
     }, FsError>;
+    readdir(dirPath: string): ResultAsync<readonly string[], FsError>;
 }

package/dist/v2/ports/session-summary-provider.port.d.ts

@@ -0,0 +1,9 @@
+import type { ResultAsync } from 'neverthrow';
+import type { HealthySessionSummary } from '../projections/resume-ranking.js';
+export interface SessionSummaryError {
+    readonly code: 'SESSION_SUMMARY_ENUMERATION_FAILED';
+    readonly message: string;
+}
+export interface SessionSummaryProviderPortV2 {
+    loadHealthySummaries(): ResultAsync<readonly HealthySessionSummary[], SessionSummaryError>;
+}

package/dist/v2/ports/session-summary-provider.port.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,62 @@
+import type { SessionId } from '../durable-core/ids/index.js';
+export type RecapSnippet = string & {
+    readonly __brand: 'RecapSnippet';
+};
+export declare function asRecapSnippet(raw: string): RecapSnippet;
+export interface SessionObservations {
+    readonly gitHeadSha: string | null;
+    readonly gitBranch: string | null;
+    readonly repoRootHash: string | null;
+}
+export interface WorkflowIdentity {
+    readonly workflowId: string | null;
+    readonly workflowName: string | null;
+}
+export interface HealthySessionSummary {
+    readonly sessionId: SessionId;
+    readonly runId: string;
+    readonly preferredTip: {
+        readonly nodeId: string;
+        readonly lastActivityEventIndex: number;
+    };
+    readonly recapSnippet: RecapSnippet | null;
+    readonly observations: SessionObservations;
+    readonly workflow: WorkflowIdentity;
+}
+export type WhyMatched = 'matched_head_sha' | 'matched_branch' | 'matched_notes' | 'matched_workflow_id' | 'recency_fallback';
+export type TierAssignment = {
+    readonly tier: 1;
+    readonly kind: 'matched_head_sha';
+} | {
+    readonly tier: 2;
+    readonly kind: 'matched_branch';
+    readonly matchType: 'exact' | 'prefix';
+} | {
+    readonly tier: 3;
+    readonly kind: 'matched_notes';
+} | {
+    readonly tier: 4;
+    readonly kind: 'matched_workflow_id';
+} | {
+    readonly tier: 5;
+    readonly kind: 'recency_fallback';
+};
+export declare function normalizeToTokens(text: string): ReadonlySet<string>;
+export declare function allQueryTokensMatch(queryTokens: ReadonlySet<string>, candidateTokens: ReadonlySet<string>): boolean;
+export interface ResumeQuery {
+    readonly gitHeadSha?: string;
+    readonly gitBranch?: string;
+    readonly freeTextQuery?: string;
+}
+export declare function assignTier(summary: HealthySessionSummary, query: ResumeQuery): TierAssignment;
+export interface RankedResumeCandidate {
+    readonly sessionId: SessionId;
+    readonly runId: string;
+    readonly preferredTipNodeId: string;
+    readonly snippet: string;
+    readonly whyMatched: readonly WhyMatched[];
+    readonly tierAssignment: TierAssignment;
+    readonly lastActivityEventIndex: number;
+}
+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

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_RESUME_CANDIDATES = void 0;
+exports.asRecapSnippet = asRecapSnippet;
+exports.normalizeToTokens = normalizeToTokens;
+exports.allQueryTokensMatch = allQueryTokensMatch;
+exports.assignTier = assignTier;
+exports.rankResumeCandidates = rankResumeCandidates;
+const MAX_SNIPPET_BYTES = 1024;
+const TRUNCATION_MARKER = '\n\n[TRUNCATED]';
+function asRecapSnippet(raw) {
+    const stripped = raw.endsWith(TRUNCATION_MARKER)
+        ? raw.slice(0, -TRUNCATION_MARKER.length)
+        : raw;
+    const encoder = new TextEncoder();
+    const bytes = encoder.encode(stripped);
+    if (bytes.length <= MAX_SNIPPET_BYTES) {
+        return stripped;
+    }
+    const decoder = new TextDecoder('utf-8', { fatal: false });
+    const truncated = decoder.decode(bytes.slice(0, MAX_SNIPPET_BYTES));
+    return truncated;
+}
+const TOKEN_REGEX = /[a-z0-9_-]+/g;
+function normalizeToTokens(text) {
+    const normalized = text.normalize('NFKC').toLowerCase();
+    const matches = normalized.match(TOKEN_REGEX);
+    return new Set(matches ?? []);
+}
+function allQueryTokensMatch(queryTokens, candidateTokens) {
+    if (queryTokens.size === 0)
+        return false;
+    for (const token of queryTokens) {
+        if (!candidateTokens.has(token))
+            return false;
+    }
+    return true;
+}
+function assignTier(summary, query) {
+    if (query.gitHeadSha && summary.observations.gitHeadSha === query.gitHeadSha) {
+        return { tier: 1, kind: 'matched_head_sha' };
+    }
+    if (query.gitBranch && summary.observations.gitBranch) {
+        if (summary.observations.gitBranch === query.gitBranch) {
+            return { tier: 2, 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' };
+        }
+    }
+    if (query.freeTextQuery && summary.recapSnippet) {
+        const queryTokens = normalizeToTokens(query.freeTextQuery);
+        const noteTokens = normalizeToTokens(summary.recapSnippet);
+        if (allQueryTokensMatch(queryTokens, noteTokens)) {
+            return { tier: 3, kind: 'matched_notes' };
+        }
+    }
+    if (query.freeTextQuery) {
+        const queryTokens = normalizeToTokens(query.freeTextQuery);
+        const workflowText = [
+            summary.workflow.workflowId ?? '',
+            summary.workflow.workflowName ?? '',
+        ].join(' ');
+        const workflowTokens = normalizeToTokens(workflowText);
+        if (allQueryTokensMatch(queryTokens, workflowTokens)) {
+            return { tier: 4, kind: 'matched_workflow_id' };
+        }
+    }
+    return { tier: 5, kind: 'recency_fallback' };
+}
+function tierToWhyMatched(tier) {
+    switch (tier.kind) {
+        case 'matched_head_sha': return 'matched_head_sha';
+        case 'matched_branch': return 'matched_branch';
+        case 'matched_notes': return 'matched_notes';
+        case 'matched_workflow_id': return 'matched_workflow_id';
+        case 'recency_fallback': return 'recency_fallback';
+    }
+}
+exports.MAX_RESUME_CANDIDATES = 5;
+function rankResumeCandidates(summaries, query) {
+    const withTier = summaries.map((summary) => ({
+        summary,
+        tier: assignTier(summary, query),
+    }));
+    const sorted = [...withTier].sort((a, b) => {
+        if (a.tier.tier !== b.tier.tier)
+            return a.tier.tier - b.tier.tier;
+        const actA = a.summary.preferredTip.lastActivityEventIndex;
+        const actB = b.summary.preferredTip.lastActivityEventIndex;
+        if (actA !== actB)
+            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,
+    }));
+}

package/dist/v2/usecases/enumerate-sessions.d.ts

@@ -0,0 +1,9 @@
+import type { ResultAsync } from 'neverthrow';
+import type { DirectoryListingPortV2 } from '../ports/directory-listing.port.js';
+import type { DataDirPortV2 } from '../ports/data-dir.port.js';
+import type { FsError } from '../ports/fs.port.js';
+import { type SessionId } from '../durable-core/ids/index.js';
+export declare function enumerateSessions(ports: {
+    readonly directoryListing: DirectoryListingPortV2;
+    readonly dataDir: DataDirPortV2;
+}): ResultAsync<readonly SessionId[], FsError>;

package/dist/v2/usecases/enumerate-sessions.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enumerateSessions = enumerateSessions;
+const index_js_1 = require("../durable-core/ids/index.js");
+const SESSION_DIR_PATTERN = /^sess_[a-zA-Z0-9_]+$/;
+function enumerateSessions(ports) {
+    return ports.directoryListing
+        .readdir(ports.dataDir.sessionsDir())
+        .map((entries) => entries
+        .filter((entry) => SESSION_DIR_PATTERN.test(entry))
+        .sort()
+        .map((entry) => (0, index_js_1.asSessionId)(entry)));
+}

package/dist/v2/usecases/resume-session.d.ts

@@ -0,0 +1,4 @@
+import type { ResultAsync } from 'neverthrow';
+import type { SessionSummaryProviderPortV2, SessionSummaryError } from '../ports/session-summary-provider.port.js';
+import { type ResumeQuery, type RankedResumeCandidate } from '../projections/resume-ranking.js';
+export declare function resumeSession(query: ResumeQuery, summaryProvider: SessionSummaryProviderPortV2): ResultAsync<readonly RankedResumeCandidate[], SessionSummaryError>;

package/dist/v2/usecases/resume-session.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resumeSession = resumeSession;
+const resume_ranking_js_1 = require("../projections/resume-ranking.js");
+function resumeSession(query, summaryProvider) {
+    return summaryProvider
+        .loadHealthySummaries()
+        .map((summaries) => (0, resume_ranking_js_1.rankResumeCandidates)(summaries, query));
+}

package/package.json

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