specrails-desktop 2.36.0 → 2.42.2

package/server/dist/mcp/tools/meta.js

@@ -1,7 +1,12 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.metaTools = metaTools;
 const zod_1 = require("zod");
+const node_path_1 = __importDefault(require("node:path"));
+const zod_json_schema_compat_js_1 = require("@modelcontextprotocol/sdk/server/zod-json-schema-compat.js");
 const guide_1 = require("../guide");
 const types_1 = require("./types");
 /**
@@ -43,6 +48,32 @@ function describeZodField(name, field) {
         out.enumValues = [...current.options];
     return out;
 }
+function permissions(ctx, spec, args) {
+    const tier = typeof spec.tier === 'function' ? spec.tier(args) : spec.tier;
+    return { tier, allowed: (0, types_1.toolTierAllowed)(ctx, tier) };
+}
+function actions(ctx, spec) {
+    const field = spec.inputSchema.action;
+    if (!(field instanceof zod_1.z.ZodEnum))
+        return [];
+    return field.options.map(action => ({ action, ...permissions(ctx, spec, { action }) }));
+}
+const STOP_WORDS = new Set('a an the to for of in and or with how do i my this el la los las un una de del en y o con como que quiero para mi por'.split(' '));
+const INTENTS = {
+    proyecto: ['project', 'context'], proyectos: ['projects'], contexto: ['context', 'overview'],
+    codigo: ['code', 'search'], buscar: ['search', 'find'], archivo: ['file'], archivos: ['file', 'tree'],
+    implementar: ['launch', 'run', 'implement'], implementacion: ['implement', 'run'], lanzar: ['launch', 'run'],
+    ejecucion: ['job', 'run'], ejecuciones: ['jobs', 'runs'], fallida: ['failed', 'logs'], error: ['error', 'logs'],
+    mision: ['conversation'], conversar: ['chat'], especificaciones: ['specs'], especificacion: ['spec'],
+    revisar: ['review', 'packet'], cambios: ['diff', 'git'], rama: ['branch', 'git'], ramas: ['branch'],
+    esperar: ['watch', 'wait'], estado: ['status', 'context'], bucle: ['loop'], bucles: ['loops'],
+    herramientas: ['tools'], permisos: ['tier', 'permissions'], configurar: ['settings'],
+};
+const normalize = (text) => text.toLowerCase().normalize('NFD').replace(/[\u0300-\u036f]/g, '');
+function intentTerms(query) {
+    const words = normalize(query).split(/[^a-z0-9_]+/).filter(word => word.length > 1 && !STOP_WORDS.has(word));
+    return [...new Set(words.flatMap(word => [word, ...(INTENTS[word] ?? [])]))];
+}
 /**
  * Meta tools that teach the platform and aid discovery.
  * `getSpecs` returns the full catalog (passed lazily to avoid a cycle).
@@ -61,20 +92,26 @@ function metaTools(getSpecs) {
         {
             name: 'specrails_search',
             title: 'Search tools',
-            description: 'Find the right Specrails tool/action for an intent. Returns matching tools with their descriptions.',
+            description: 'Find the right Specrails tool/action for an English or Spanish intent. Searches tool descriptions, actions and input fields; returns current permissions. Follow with describe for exact arguments.',
             tier: 'read',
             inputSchema: {
-                query: zod_1.z.string().describe('Natural-language intent, e.g. "launch the pipeline for a ticket"'),
+                query: zod_1.z.string().trim().min(1).max(500).describe('Natural-language intent, e.g. "launch the pipeline for a ticket" or "buscar código del proyecto"'),
             },
-            handler: (_ctx, args) => {
-                const q = String(args.query ?? '').toLowerCase().trim();
-                const terms = q.split(/\s+/).filter(Boolean);
+            handler: (ctx, args) => {
+                const terms = intentTerms(String(args.query ?? ''));
                 const scored = getSpecs()
                     .filter((s) => s.name !== 'specrails_search')
                     .map((s) => {
-                    const hay = `${s.name} ${s.title} ${s.description}`.toLowerCase();
-                    const score = terms.reduce((acc, t) => acc + (hay.includes(t) ? 1 : 0), 0);
-                    return { name: s.name, title: s.title, description: s.description, score };
+                    const actionList = actions(ctx, s);
+                    const name = normalize(`${s.name} ${s.title}`);
+                    const description = normalize(s.description);
+                    const schema = normalize(JSON.stringify((0, zod_json_schema_compat_js_1.toJsonSchemaCompat)(zod_1.z.object(s.inputSchema))));
+                    const score = terms.reduce((acc, term) => acc + (name.includes(term) ? 8 : 0) +
+                        (actionList.some(item => item.action.includes(term)) ? 5 : 0) +
+                        (description.includes(term) ? 2 : 0) + (schema.includes(term) ? 1 : 0), 0);
+                    return { name: s.name, title: s.title, description: s.description, score,
+                        actions: actionList, ...(actionList.length ? {} : permissions(ctx, s, {})),
+                        permissionNote: 'Action previews use default arguments. Describe with arguments for the exact tier; execution rechecks current permissions.' };
                 })
                     .filter((r) => r.score > 0)
                     .sort((a, b) => b.score - a.score)
@@ -85,20 +122,30 @@ function metaTools(getSpecs) {
         {
             name: 'specrails_describe',
             title: 'Describe a tool',
-            description: 'Return the full description and per-field input schema (name, description, type, enum values, optionality) for a named Specrails tool.',
+            description: 'Return a tool\'s complete JSON input schema, including nested objects, arrays, required fields, enums and bounds, plus per-action permissions. Optionally validate prospective arguments and preview their tier without executing anything.',
             tier: 'read',
             inputSchema: {
                 name: zod_1.z.string().describe('Tool name, e.g. "specrails_rails"'),
+                arguments: zod_1.z.record(zod_1.z.unknown()).optional().describe('Optional prospective tool arguments to validate and preview permissions; never executes the tool'),
             },
-            handler: (_ctx, args) => {
+            handler: (ctx, args) => {
                 const name = String(args.name ?? '');
                 const spec = getSpecs().find((s) => s.name === name);
                 if (!spec)
                     throw new Error(`Unknown tool "${name}". Use specrails_search to find one.`);
+                const schema = zod_1.z.object(spec.inputSchema);
+                const prospective = args.arguments;
+                const validation = prospective === undefined ? undefined : schema.safeParse(prospective);
                 return {
                     name: spec.name,
                     title: spec.title,
                     description: spec.description,
+                    inputSchema: (0, zod_json_schema_compat_js_1.toJsonSchemaCompat)(schema),
+                    actions: actions(ctx, spec),
+                    permissionNote: 'Action previews use default arguments. Validation checks the shared JSON schema only; action-specific requirements and backend state are checked at execution. No tool is executed here.',
+                    ...(validation ? { validation: validation.success
+                            ? { valid: true, ...permissions(ctx, spec, validation.data) }
+                            : { valid: false, issues: validation.error.issues.map(issue => ({ path: issue.path, message: issue.message })) } } : {}),
                     inputFields: Object.entries(spec.inputSchema).map(([fieldName, field]) => describeZodField(fieldName, field)),
                 };
             },
@@ -106,30 +153,30 @@ function metaTools(getSpecs) {
         {
             name: 'specrails_select_project',
             title: 'Select active project',
-            description: 'Set the active project so subsequent per-project tools may omit projectId. Pass an id or a path. Pass null to clear.',
+            description: 'Set this MCP session\'s active project so per-project tools may omit projectId. Pass an id or path, or null to clear. A mission\'s project pin is controlled by the conversation UI; this tool cannot override it.',
             tier: 'read',
             inputSchema: {
                 projectId: zod_1.z.string().nullable().optional().describe('Project id to make active, or null to clear'),
                 path: zod_1.z.string().optional().describe('Resolve+select a project by filesystem path instead of id'),
             },
             handler: (ctx, args) => {
-                if (args.path) {
-                    const pc = ctx.registry.getContextByPath(String(args.path));
-                    if (!pc)
-                        throw new Error(`No project registered at path "${args.path}".`);
-                    (0, types_1.setActiveProject)(pc.project.id);
-                    return { active: pc.project.id, name: pc.project.name };
-                }
-                if (args.projectId === null) {
-                    (0, types_1.setActiveProject)(null);
-                    return { active: null };
-                }
-                const id = args.projectId;
-                if (!id)
+                if (args.path !== undefined && args.projectId !== undefined)
+                    throw new Error('Provide either path or projectId, not both.');
+                const project = args.path
+                    ? ctx.registry.listProjects().find(p => node_path_1.default.resolve(p.path) === node_path_1.default.resolve(String(args.path)))
+                    : typeof args.projectId === 'string' ? ctx.registry.getProjectRow(args.projectId) : undefined;
+                if (args.path && !project)
+                    throw new Error(`No project registered at path "${args.path}".`);
+                if (args.projectId && !project)
+                    throw new Error(`Unknown projectId "${args.projectId}".`);
+                if (!project && args.projectId !== null)
                     throw new Error('Provide a projectId, a path, or null.');
-                const pc = (0, types_1.requireProject)(ctx, id);
-                (0, types_1.setActiveProject)(pc.project.id);
-                return { active: pc.project.id, name: pc.project.name };
+                const id = project?.id ?? null;
+                if (ctx.requestProjectId !== undefined && ctx.requestProjectId !== id) {
+                    throw new Error('This mission uses its conversation project pin. Change the pin in the mission UI, or pass projectId explicitly for an intentional cross-project operation; selecting a default here cannot change the pin.');
+                }
+                (0, types_1.setActiveProject)(ctx, id);
+                return project ? { active: id, name: project.name, available: !!ctx.registry.getContext(project.id) } : { active: null };
             },
         },
     ];

package/server/dist/mcp/tools/mission.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.missionTools = missionTools;
+const zod_1 = require("zod");
+function missionTools() {
+    return [{
+            name: 'specrails_mission',
+            title: 'Mission user updates',
+            description: 'First-party mission only: acknowledge authenticated user updates received during the current running turn. For MCP mission_user_updates, read every block, replan, and acknowledge_updates with the exact latest revision in a separate call before invoking other tools. For the initial Mission input ID or native user messages carrying queueId, acknowledge_inputs with those inputIds only after reading them; this records a read receipt and does not release the MCP revision gate. Does not execute, retry or undo any action and cannot change permissions, provider or project pin.',
+            tier: 'read',
+            inputSchema: {
+                action: zod_1.z.enum(['acknowledge_updates', 'acknowledge_inputs']),
+                revision: zod_1.z.number().int().positive().max(Number.MAX_SAFE_INTEGER).optional().describe('Required for acknowledge_updates: exact latest revision delivered in mission_user_updates. Never guess; an older acknowledgement cannot release newer messages.'),
+                inputIds: zod_1.z.array(zod_1.z.string().min(1).max(200)).min(1).max(50).optional().describe('Required for acknowledge_inputs: exact initial Mission input ID or queueId values from native user messages you have read in this invocation.'),
+            },
+            handler: (ctx, args) => {
+                if (args.action === 'acknowledge_inputs') {
+                    if (!ctx.firstPartyAgent || !ctx.acknowledgeAgentInputsRead)
+                        throw new Error('This action requires an active first-party mission turn.');
+                    return ctx.acknowledgeAgentInputsRead(args.inputIds);
+                }
+                if (args.action !== 'acknowledge_updates')
+                    throw new Error(`Unknown action: ${String(args.action)}`);
+                if (!ctx.firstPartyAgent || !ctx.acknowledgeAgentUpdates)
+                    throw new Error('This action requires an active first-party mission turn.');
+                return ctx.acknowledgeAgentUpdates(args.revision);
+            },
+        }];
+}

package/server/dist/mcp/tools/projects.js

@@ -4,12 +4,15 @@ exports.serializeProject = serializeProject;
 exports.projectsTools = projectsTools;
 const zod_1 = require("zod");
 const types_1 = require("./types");
+const project_repositories_1 = require("../../project-repositories");
 function serializeProject(p) {
     return {
         id: p.id,
         slug: p.slug,
         name: p.name,
         path: p.path,
+        primaryRepositoryId: (0, project_repositories_1.getProjectRepositories)(p).find(repository => repository.isPrimary)?.id,
+        repositories: (0, project_repositories_1.getProjectRepositories)(p),
         provider: p.provider,
         providers: p.providers,
         addedAt: p.added_at,
@@ -34,21 +37,34 @@ function projectsTools() {
                 const action = args.action;
                 switch (action) {
                     case 'list':
-                        return ctx.registry.listContexts().map((c) => serializeProject(c.project));
-                    case 'get':
-                        return serializeProject((0, types_1.requireProject)(ctx, args.projectId).project);
+                        return ctx.registry.listProjects().map((p) => ({ ...serializeProject(p), available: !!ctx.registry.getContext(p.id) }));
+                    case 'get': {
+                        const id = args.projectId ?? (0, types_1.getActiveProject)(ctx);
+                        if (!id)
+                            throw new Error('No project selected. Provide projectId or use specrails_select_project.');
+                        const p = ctx.registry.getProjectRow(id);
+                        if (!p)
+                            throw new Error(`Unknown projectId "${id}".`);
+                        return { ...serializeProject(p), available: !!ctx.registry.getContext(id) };
+                    }
                     case 'resolve': {
                         const p = args.path;
                         if (!p)
                             throw new Error('resolve requires a "path".');
-                        const pc = ctx.registry.getContextByPath(p);
-                        return pc ? serializeProject(pc.project) : { resolved: false };
+                        const selected = args.projectId;
+                        const key = (0, project_repositories_1.repositoryPathKey)((0, project_repositories_1.canonicalRepositoryPath)(p));
+                        const matches = ctx.registry.listProjects().filter(row => !selected || row.id === selected).flatMap(project => (0, project_repositories_1.getProjectRepositories)(project).filter(repository => (0, project_repositories_1.repositoryPathKey)((0, project_repositories_1.canonicalRepositoryPath)(repository.path)) === key)
+                            .map(repository => ({ project, repository })));
+                        if (matches.length > 1)
+                            return { resolved: false, ambiguous: true, matches: matches.map(({ project, repository }) => ({ projectId: project.id, projectName: project.name, repositoryId: repository.id, repositoryName: repository.name })) };
+                        const match = matches[0];
+                        return match ? { ...serializeProject(match.project), repositoryId: match.repository.id, available: !!ctx.registry.getContext(match.project.id) } : { resolved: false };
                     }
                     case 'unregister': {
                         const id = args.projectId;
                         if (!id)
                             throw new Error('unregister requires a "projectId".');
-                        if (!ctx.registry.getContext(id))
+                        if (!ctx.registry.getProjectRow(id))
                             throw new Error(`Unknown projectId "${id}".`);
                         ctx.registry.removeProject(id);
                         return { ok: true, unregistered: id };

package/server/dist/mcp/tools/rails.js

@@ -39,14 +39,14 @@ function railsTools() {
             title: 'Rails',
             description: 'List and configure a project\'s rail launch slots, then launch or stop the AI pipeline for a rail. ' +
                 'A rail holds assigned ticket IDs plus a mode/profile/engine/name. Rails are DYNAMIC: create_rail adds a new slot (up to 12), so when every rail is busy or holds other work, create a fresh one and proceed — never wait for a slot. ' +
-                'Launching several rails in parallel is safe and normal: each launch runs in its own isolated git worktree. ' +
-                'Actions: list (rails + active jobs/loop runs), create_rail (add a new rail slot; returns its railIndex), set_tickets (assign ticket IDs), set_profile (default agent profile, null=legacy), ' +
+                'Parallel launches normally run in isolated git worktrees; verify the returned isolated flag. Legacy or non-git runs may use shared project files and have no delivery card. ' +
+                'Actions: list (rails + active jobs/loop runs), pr_candidates (read compatible open PR targets for railIndex), review_packet (read durable evidence, verification and acceptance capability by prDeliveryId), create_rail (add a new rail slot; returns its railIndex), set_tickets (assign ticket IDs), set_profile (default agent profile, null=legacy), ' +
                 'set_engine (provider override, null=primary), set_name (display label, null clears), ' +
                 'launch (ai-spawn — spawns the selected installed provider CLI job(s), including Kimi when installed, that WRITE CODE, RUN TESTS, COMMIT, and INCUR TOKEN COST; returns 202 with jobId/jobIds/loopRunIds), ' +
                 'launch_all (ai-spawn — launches EVERY rail that has tickets and no active run/uncontinuable pending PR decision, in parallel, using each rail\'s stored mode/engine/profile; returns per-rail outcomes with skip reasons), ' +
                 'stop (destructive — kills all active jobs and loop runs for the rail). ' +
                 'For on_review tickets with an already-open GitHub PR (including a published pr_ready delivery), launch automatically tries to continue that PR head branch; Jira-linked in_progress tickets can do the same when the PR match is explicit; fresh tickets still start from the project integration branch. ' +
-                'When launched from the in-app agent chat without an explicit aiEngine, the engine defaults to your conversation\'s provider (pass aiEngine to override; launch_all always uses each rail\'s stored engine). ' +
+                'When launched from the in-app agent chat without an explicit aiEngine, the engine defaults to your conversation\'s provider. On that same provider, an omitted model inherits the conversation model; an explicit model wins (pass aiEngine to override; launch_all always uses each rail\'s stored engine). ' +
                 'User-facing naming: call the free-form autonomous mode "Freestyle"; use "freestyle" as the canonical API enum value for that same capability. ' +
                 'For small OpenSpec-governed work, recommend "SDD Quick (OpenSpec)" and launch with mode "loop" plus loopId "factory:sdd-quick-openspec"; keep Freestyle for ticket-local implementation-only work. ' +
                 'NAMING: railIndex is the 0-BASED internal identity; the dashboard shows rails 1-based ("Rail N" = railIndex N-1). When talking to the user, ALWAYS say "Rail <railIndex + 1>" (or the rail\'s custom name) — results include railLabel with the correct user-facing label.',
@@ -63,15 +63,18 @@ function railsTools() {
             },
             inputSchema: {
                 action: zod_1.z
-                    .enum(['list', 'create_rail', 'set_tickets', 'set_profile', 'set_engine', 'set_name', 'launch', 'launch_all', 'stop'])
+                    .enum(['list', 'pr_candidates', 'review_packet', 'create_rail', 'set_tickets', 'set_profile', 'set_engine', 'set_name', 'launch', 'launch_all', 'stop'])
                     .describe('Operation to perform'),
                 projectId: zod_1.z.string().optional().describe('Project id (defaults to the active project)'),
+                repositoryIds: zod_1.z.array(zod_1.z.string().min(1)).min(1).max(50).optional().describe('launch only: explicit affected repository memberships for the coordinated run; must include every repository required by the assigned specs. Omission uses the assigned specs\' repository selections.'),
+                repositoryId: zod_1.z.string().min(1).optional().describe('review_packet only: member of a grouped delivery to inspect; omission returns the public parent with grouped outcomes.'),
                 railIndex: zod_1.z
                     .number()
                     .int()
                     .min(0)
                     .optional()
-                    .describe('Rail slot index, 0-BASED (required for every action except list). The dashboard labels rails 1-based: UI "Rail N" = railIndex N-1.'),
+                    .describe('Rail slot index, 0-BASED (required except list, create_rail, launch_all and review_packet). The dashboard labels rails 1-based: UI "Rail N" = railIndex N-1.'),
+                prDeliveryId: zod_1.z.string().optional().describe('Delivery id returned by list/prDeliveries (required for review_packet)'),
                 // set_tickets
                 ticketIds: zod_1.z
                     .array(zod_1.z.number().int())
@@ -103,7 +106,7 @@ function railsTools() {
                 model: zod_1.z
                     .string()
                     .optional()
-                    .describe('Model for launch. For Freestyle or loop mode, pass a model string valid for the selected installed provider; Kimi preserves configured model aliases. Freestyle availability is capability-gated by provider.'),
+                    .describe('Model for launch. Defaults to the launching conversation model when the engine matches; an explicit model wins. For Freestyle or loop mode, pass a model string valid for the selected installed provider; Kimi preserves configured model aliases. Freestyle availability is capability-gated by provider.'),
                 interactive: zod_1.z
                     .boolean()
                     .optional()
@@ -130,6 +133,10 @@ function railsTools() {
                     .string()
                     .optional()
                     .describe('What to change, in the user\'s own words (required with revisionOfDeliveryId). It is injected into the revision run and shown on the updated review packet as "what you asked to change".'),
+                baseBranch: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Local branch to base the isolated worktree on instead of the integration branch (launch). Used to STACK work on a previous delivery\'s branch (the milestone launch chain does this automatically for chunk 2+). Must resolve locally and requires worktree isolation; rejected with invalid_base_branch / base_branch_requires_isolation otherwise.'),
             },
             async handler(ctx, args) {
                 const base = `${(0, types_1.projectPath)(ctx, args.projectId)}/rails`;
@@ -144,6 +151,15 @@ function railsTools() {
                 switch (action) {
                     case 'list':
                         return (0, types_1.apiCall)(ctx, 'GET', base);
+                    case 'pr_candidates':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/${requireRailIndex()}/pr-candidates`);
+                    case 'review_packet': {
+                        if (typeof args.prDeliveryId !== 'string' || !args.prDeliveryId.trim()) {
+                            throw new Error('review_packet requires "prDeliveryId" from list/prDeliveries.');
+                        }
+                        const query = args.repositoryId === undefined ? '' : `?${new URLSearchParams({ repositoryId: args.repositoryId })}`;
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/pr-deliveries/${encodeURIComponent(args.prDeliveryId)}/packet${query}`);
+                    }
                     case 'create_rail': {
                         const body = {};
                         if (typeof args.name === 'string' && args.name.trim())
@@ -218,6 +234,10 @@ function railsTools() {
                             body.reasoning_effort = args.reasoning_effort;
                         if (args.targetPrNumber !== undefined)
                             body.targetPrNumber = args.targetPrNumber;
+                        if (args.repositoryIds !== undefined)
+                            body.repositoryIds = args.repositoryIds;
+                        if (args.baseBranch !== undefined)
+                            body.baseBranch = args.baseBranch;
                         // Revision of a delivery already awaiting the user's decision: the
                         // ONE launch allowed against an undecided delivery. The route
                         // re-validates the exemption (must be the rail's active delivery and
@@ -247,10 +267,16 @@ function railsTools() {
                         if (body.aiEngine === undefined && defaults.provider) {
                             body.aiEngine = defaults.provider;
                         }
+                        if (body.model === undefined && defaults.model && body.aiEngine === defaults.provider) {
+                            body.model = defaults.model;
+                        }
                         if (body.reasoning_effort === undefined &&
                             defaults.reasoningEffort &&
                             defaults.provider &&
-                            body.aiEngine === defaults.provider) {
+                            body.aiEngine === defaults.provider &&
+                            // Effort is model-specific (Astra's ultra is not valid for
+                            // GPT-5.5). An explicit different model gets its own default.
+                            (!defaults.model || body.model === defaults.model)) {
                             body.reasoning_effort = defaults.reasoningEffort;
                         }
                         const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/${railIndex}/launch`, body);
@@ -277,10 +303,17 @@ function railsTools() {
                                 hint: `Launch accepted (202) on ${railLabel}, but WORKTREE ISOLATION IS UNAVAILABLE because ${why}. The run proceeds on the SHARED working tree and writes changes DIRECTLY into the user's files — there is NO PR-decision/implementation card and NO branch. Do NOT tell the user to look for a PR card; tell them the run writes to their files in place, and explain why. ${fix} When it finishes, the spec parks at on_review — the user accepts it by moving it to Done on the board (the changes are already in their files) or reverts the spec's status (which does NOT undo the file changes).`,
                             };
                         }
+                        if (r.isolated !== true) {
+                            return {
+                                ...r,
+                                railLabel,
+                                hint: `Launch accepted (202) on ${railLabel}. The server did not report worktree isolation (the legacy/shared checkout path may be enabled); do not promise a separate branch or delivery card. Read the returned jobId/jobIds with specrails_jobs(get) or use specrails_watch(ref:jobId, kind:"job"); for loopRunIds use kind:"loop_run".`,
+                            };
+                        }
                         return {
                             ...r,
                             railLabel,
-                            hint: `Launch accepted (202) on ${railLabel} (isolated worktree, PR flow active) — tell the user it runs on "${railLabel}" (UI labels are 1-based). If the assigned spec is on_review with a matching open PR, including an already-published pr_ready PR, or is Jira-linked in_progress with an explicit PR match, Specrails continues that PR branch automatically; otherwise it starts a fresh branch from the integration branch. The PR-decision card will appear here and on the rail header when it settles. Use specrails_watch with the returned loopRunIds to await completion only if asked. Rails run for minutes; pass untilMs up to 600000 and re-watch on timeout.`,
+                            hint: `Launch accepted (202) on ${railLabel} (isolated worktree, PR flow active) — tell the user it runs on "${railLabel}" (UI labels are 1-based). If the assigned spec is on_review with a matching open PR, including an already-published pr_ready PR, or is Jira-linked in_progress with an explicit PR match, Specrails continues that PR branch automatically; otherwise it starts a fresh branch from the integration branch. The PR-decision card will appear here and on the rail header when it settles. Use specrails_watch(ref:loopRunId, kind:"loop_run") for each returned loopRunId to inspect completion. Rails run for minutes; pass untilMs up to 600000 and re-watch on timeout. Settled does not imply successful delivery: read rails(list) and review_packet for verification and blockers.`,
                         };
                     }
                     case 'launch_all': {
@@ -332,16 +365,20 @@ function railsTools() {
                                     ...(typeof data.jobId === 'string' ? { jobId: data.jobId } : {}),
                                     ...(Array.isArray(data.jobIds) ? { jobIds: data.jobIds } : {}),
                                     ...(Array.isArray(data.loopRunIds) ? { loopRunIds: data.loopRunIds } : {}),
+                                    ...(typeof data.isolationUnavailable === 'string' ? { isolationUnavailable: data.isolationUnavailable } : {}),
+                                    ...(typeof data.isolationUnavailableDetail === 'string' ? { isolationUnavailableDetail: data.isolationUnavailableDetail } : {}),
+                                    ...(typeof data.prDeliveryId === 'string' ? { prDeliveryId: data.prDeliveryId } : {}),
+                                    ...(typeof data.isolated === 'boolean' ? { isolated: data.isolated } : {}),
                                 });
                             })
                                 .catch((err) => {
                                 // Race-safe: a 409 raised between the snapshot and the launch
                                 // maps back to its skip reason instead of a hard failure.
                                 const message = err instanceof Error ? err.message : String(err);
-                                if (message.includes('pr_decision_pending')) {
+                                if (err instanceof types_1.McpApiError && err.status === 409 && err.code === 'pr_decision_pending') {
                                     results.push({ railIndex: idx, outcome: 'skipped', reason: 'pr-decision-pending', ticketIds });
                                 }
-                                else if (message.includes('tickets_in_flight')) {
+                                else if (err instanceof types_1.McpApiError && err.status === 409 && err.code === 'tickets_in_flight') {
                                     results.push({ railIndex: idx, outcome: 'skipped', reason: 'tickets-in-flight', ticketIds });
                                 }
                                 else {
@@ -359,7 +396,7 @@ function railsTools() {
                         return {
                             launched, skipped, failed, results,
                             hint: launched > 0
-                                ? 'Launches accepted (202) and running IN PARALLEL in isolated worktrees. Report the per-rail ids verbatim and release the turn — progress streams live; re-check later with specrails_jobs(get) or specrails_watch on request.'
+                                ? 'Launches accepted (202) and running in parallel. Check each result: isolationUnavailable means that rail writes directly into project files and has NO delivery card; explain that limitation. Report the per-rail ids verbatim; progress streams live. Use specrails_watch(kind:"loop_run", ref:loopRunId) or specrails_jobs(get) to inspect completion.'
                                 : 'No rail was launched — see per-rail reasons. Assign tickets with set_tickets (create_rail if no free rail) and retry.',
                         };
                     }