specrails-desktop 2.18.2 → 2.19.1

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

@@ -4,6 +4,45 @@ exports.metaTools = metaTools;
 const zod_1 = require("zod");
 const guide_1 = require("../guide");
 const types_1 = require("./types");
+/**
+ * Serialize a raw-shape zod field into `{ name, description, type, enumValues?,
+ * optional }`. Unwraps optional/default/nullable wrappers (keeping the OUTERMOST
+ * `.describe()` string, the convention across the tool files) down to the base
+ * type so the model sees the real type + enum values instead of a bare key name.
+ */
+function describeZodField(name, field) {
+    let current = field;
+    let optional = false;
+    let nullable = false;
+    let description;
+    for (;;) {
+        if (description === undefined && current.description !== undefined)
+            description = current.description;
+        const def = current._def;
+        const typeName = def?.typeName;
+        if ((typeName === 'ZodOptional' || typeName === 'ZodDefault') && def?.innerType) {
+            optional = true;
+            current = def.innerType;
+            continue;
+        }
+        if (typeName === 'ZodNullable' && def?.innerType) {
+            nullable = true;
+            current = def.innerType;
+            continue;
+        }
+        break;
+    }
+    const baseName = (current._def?.typeName ?? 'ZodUnknown')
+        .replace(/^Zod/, '')
+        .toLowerCase();
+    const type = nullable ? `${baseName} | null` : baseName;
+    const out = { name, type, optional };
+    if (description !== undefined)
+        out.description = description;
+    if (current instanceof zod_1.z.ZodEnum)
+        out.enumValues = [...current.options];
+    return out;
+}
 /**
  * Meta tools that teach the platform and aid discovery.
  * `getSpecs` returns the full catalog (passed lazily to avoid a cycle).
@@ -13,7 +52,8 @@ function metaTools(getSpecs) {
         {
             name: 'specrails_guide',
             title: 'Platform guide',
-            description: 'Returns a self-contained guide to Specrails: concepts, workflow, invariants, and how to use these tools. Read this first.',
+            description: 'Returns a self-contained guide to Specrails: concepts, workflow, invariants, and how to use these tools. ' +
+                'Read this first — call once per session before your first domain call.',
             tier: 'read',
             inputSchema: {},
             handler: () => guide_1.SPECRAILS_GUIDE,
@@ -45,7 +85,7 @@ function metaTools(getSpecs) {
         {
             name: 'specrails_describe',
             title: 'Describe a tool',
-            description: 'Return the full description and input schema summary for a named Specrails tool.',
+            description: 'Return the full description and per-field input schema (name, description, type, enum values, optionality) for a named Specrails tool.',
             tier: 'read',
             inputSchema: {
                 name: zod_1.z.string().describe('Tool name, e.g. "specrails_rails"'),
@@ -59,7 +99,7 @@ function metaTools(getSpecs) {
                     name: spec.name,
                     title: spec.title,
                     description: spec.description,
-                    inputFields: Object.keys(spec.inputSchema),
+                    inputFields: Object.entries(spec.inputSchema).map(([fieldName, field]) => describeZodField(fieldName, field)),
                 };
             },
         },

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

@@ -72,19 +72,19 @@ function railsTools() {
                 mode: zod_1.z
                     .enum(['implement', 'batch-implement', 'ultracode', 'loop'])
                     .optional()
-                    .describe('Launch mode (launch; default "implement"). ultracode is Claude-only and runs one job per ticket; loop runs an app-driven loop per ticket.'),
+                    .describe('Launch mode (launch; default "implement"). "ultracode" is the wire value for Freestyle mode — hands the spec straight to the model, Claude-only, one job per ticket; loop runs an app-driven loop per ticket.'),
                 model: zod_1.z
-                    .enum(['haiku', 'sonnet', 'opus'])
+                    .string()
                     .optional()
-                    .describe('Ultracode Claude model (launch, ultracode mode only). For loop mode, a provider-valid model string.'),
+                    .describe('Model for launch. Freestyle mode (wire value \'ultracode\') is Claude-only and takes a Claude alias (haiku | sonnet | opus | fable). For loop mode, any model string valid for the rail\'s provider (claude/codex/gemini).'),
                 interactive: zod_1.z
                     .boolean()
                     .optional()
-                    .describe('Interactive ultracode session (launch, ultracode + Claude only; requires the interactive-jobs feature)'),
+                    .describe('DEPRECATED — accepted and ignored: Freestyle jobs are interactive by default whenever the interactive-jobs feature is enabled'),
                 loopId: zod_1.z
                     .string()
                     .optional()
-                    .describe('Loop id to run (launch). Factory ids (e.g. "factory:implement") map to a legacy mode; a custom published loop id keeps mode="loop".'),
+                    .describe('Loop id to run (launch). Factory ids (e.g. "factory:implement") map to a legacy mode; a custom published loop id keeps mode="loop". Browse/author loops with specrails_loops; the loop must be Published.'),
                 reasoning_effort: zod_1.z
                     .enum(['low', 'medium', 'high'])
                     .optional()
@@ -165,7 +165,7 @@ function railsTools() {
                         const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/${railIndex}/launch`, body);
                         return {
                             ...r,
-                            hint: 'Launch accepted (202). Use specrails_watch with the returned jobId/jobIds (or loopRunIds for loop mode) to await completion. Live output streams over the job WS.',
+                            hint: 'Launch accepted (202). Use specrails_watch with the returned jobId/jobIds (or loopRunIds for loop mode) to await completion. Live output streams over the job WS. Rails run for minutes; pass untilMs up to 600000 and re-watch on timeout.',
                         };
                     }
                     case 'stop': {

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

@@ -36,7 +36,8 @@ function setupTools() {
                 'Per-project actions: install_config (persist install-config.yaml), install (spawn offline framework scaffold — async/202), ' +
                 'checkpoints (poll live setup/install state — the canonical completion signal when not streaming WS), ' +
                 'abort (SIGTERM/SIGKILL the in-progress install child), integration_contract (read the ticket-provider contract). ' +
-                'Install is QUICK-only and provisions every registered provider in one shot; the legacy full/enrich AI flow is not exposed here.',
+                'Install is QUICK-only and provisions every registered provider in one shot; the legacy full/enrich AI flow is not exposed here. ' +
+                'Lifecycle: 1) prerequisites 2) add_project(path, providers) 3) install_config per provider 4) ONE install (provisions ALL chosen providers; quick-only, offline) 5) poll checkpoints until isInstalling === false.',
             hintTier: 'read',
             tier: (a) => {
                 const action = a.action;

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

@@ -25,7 +25,12 @@ function resolveSpecsTier(action) {
 }
 const WATCH_HINT = 'Returns 202 immediately; the actual result streams over the WebSocket. ' +
     'Use specrails_watch with the returned requestId/scheduled ref to await completion ' +
-    '(WS events: spec_gen_*, ticket_ai_edit_*, explore.contract_refine_*, smash.*).';
+    '(WS events: spec_gen_*, ticket_ai_edit_*, smash.*).';
+// Contract Refine settles asymmetrically: only FAILURE emits a watch-terminal
+// event (explore.contract_refine_failed); success lands as a plain
+// ticket_updated broadcast, which watch does not treat as terminal.
+const CONTRACT_REFINE_HINT = 'Returns 202 immediately. Failure settles via specrails_watch (explore.contract_refine_failed); ' +
+    "success arrives as ticket_updated — poll specrails_specs(get) for the '## Contract Layer' section.";
 function specsTools() {
     return [
         {
@@ -35,9 +40,16 @@ function specsTools() {
                 'Actions: list, get, ' +
                 'create (ai-spawn — THE way to add a spec: routes through Quick Add Spec, so the specrails agent generates a structured spec with AI from the user request, exactly matching the app\'s "Add Spec → Quick" flow; pass the request as title/description, it becomes the idea; async), ' +
                 'update, delete (destructive), ' +
-                'from_prompt (verbatim insert, no AI — use ONLY when you already have a complete finished spec to store as-is), ' +
-                'save_draft (persist an Explore conversation as a draft), commit_draft (flip a draft to a real spec), ' +
-                'generate (alias of create — Quick AI spec generation), ai_edit (ai-spawn, AI-edit a ticket title+description), ' +
+                'from_prompt (verbatim insert, no AI — use ONLY when you already have a complete finished spec to store as-is; ' +
+                'cannot set acceptanceCriteria or shortSummary — prefer commit_draft for structured specs), ' +
+                'save_draft (persist an Explore conversation as a draft), ' +
+                'commit_draft (write, no AI — TWO uses: (a) flip an Explore draft to a real spec, passing conversationId from ' +
+                'specrails_chat and/or draftTicketId; (b) with NO conversationId/draftTicketId, insert a COMPLETE spec you ' +
+                'authored in ONE call: title (required), description, acceptanceCriteria, priority, labels, shortSummary, ' +
+                'assignee, prerequisites, metadata. THE canonical way to persist a spec refined in conversation — do NOT route ' +
+                'a finished spec through create/generate, which re-generate the content with AI and lossily rewrite it), ' +
+                'generate (same as create but takes a pre-formed idea string; both accept contextScope/attachments/createLocal), ' +
+                'ai_edit (ai-spawn, AI-edit a ticket title+description), ' +
                 'cancel_ai_edit (abort an in-flight ai-edit), contract_refine (ai-spawn, append a Contract Layer — Claude-only), ' +
                 'smash (ai-spawn, decompose a spec into N child sub-specs under an epic — Claude-only), ' +
                 'smash_undo (destructive, reverse a prior SMASH), delete_epic_children (destructive, delete all children of an epic), ' +
@@ -81,7 +93,7 @@ function specsTools() {
                 status: zod_1.z
                     .string()
                     .optional()
-                    .describe('list: filter by status (CSV: draft|todo|in_progress|done|cancelled). create/update: set ticket status'),
+                    .describe('list: CSV status filter (draft|todo|in_progress|done|cancelled). update: set ticket status — note job outcomes set in_progress/done automatically; do not fight the pipeline.'),
                 label: zod_1.z.string().optional().describe('list: filter by label (CSV)'),
                 q: zod_1.z.string().optional().describe('list: free-text search over title + description'),
                 // ── create / update / from_prompt / commit_draft fields ──────────
@@ -92,13 +104,13 @@ function specsTools() {
                     .describe('Ticket description. For ai_edit this is the REQUIRED current baseline description'),
                 priority: zod_1.z
                     .enum(['critical', 'high', 'medium', 'low'])
+                    .nullable()
                     .optional()
-                    .describe('Ticket priority (defaults to medium; may be null only for drafts)'),
-                labels: zod_1.z.array(zod_1.z.string()).optional().describe('Labels array'),
-                assignee: zod_1.z.string().optional().describe('create/update: assignee'),
-                prerequisites: zod_1.z.array(zod_1.z.number().int()).optional().describe('create/update: prerequisite ticket ids'),
-                metadata: zod_1.z.record(zod_1.z.unknown()).optional().describe('create/update: free-form metadata object'),
-                source: zod_1.z.string().optional().describe('create: source tag'),
+                    .describe('update/from_prompt/commit_draft: ticket priority. update: null allowed only for drafts'),
+                labels: zod_1.z.array(zod_1.z.string()).optional().describe('update/from_prompt/save_draft/commit_draft: labels array'),
+                assignee: zod_1.z.string().optional().describe('update/commit_draft: assignee'),
+                prerequisites: zod_1.z.array(zod_1.z.number().int()).optional().describe('update/commit_draft: prerequisite ticket ids'),
+                metadata: zod_1.z.record(zod_1.z.unknown()).optional().describe('update/commit_draft: free-form metadata object (update merges keys)'),
                 acceptanceCriteria: zod_1.z
                     .array(zod_1.z.string())
                     .optional()
@@ -106,31 +118,31 @@ function specsTools() {
                 shortSummary: zod_1.z.string().optional().describe('commit_draft: explicit short summary (camelCase key)'),
                 short_summary: zod_1.z.string().optional().describe('update: explicit short summary (snake_case key; null clears)'),
                 structured: zod_1.z.boolean().optional().describe('from_prompt: lightly structure the verbatim prompt'),
-                createLocal: zod_1.z.boolean().optional().describe('commit_draft/generate: keep the spec local (skip Jira promote)'),
+                createLocal: zod_1.z.boolean().optional().describe('create/generate/commit_draft: keep the spec local (skip Jira promote)'),
                 // ── draft linkage ────────────────────────────────────────────────
                 conversationId: zod_1.z
                     .string()
                     .optional()
-                    .describe('save_draft (required) / commit_draft: origin Explore conversation id'),
+                    .describe("save_draft (required) / commit_draft: origin Explore conversation id — obtained from specrails_chat(create kind:'explore'); NEVER an agent/desktop conversation id"),
                 draftTicketId: zod_1.z.number().int().optional().describe('commit_draft: explicit draft ticket id to flip in place'),
                 editTicketId: zod_1.z.number().int().optional().describe('save_draft: existing ticket id to demote to a draft in place'),
                 pendingSpecId: zod_1.z
                     .string()
                     .optional()
-                    .describe('generate/from_prompt/commit_draft: pending-spec UUID owning pre-creation attachments'),
-                // ── generate (Quick AI spec) ─────────────────────────────────────
+                    .describe('create/generate/from_prompt/commit_draft: pending-spec UUID owning pre-creation attachments'),
+                // ── create / generate (Quick AI spec) ────────────────────────────
                 idea: zod_1.z.string().optional().describe('generate: the idea/prompt to turn into a spec (required)'),
-                model: zod_1.z.string().optional().describe('generate/smash: model override (validated against the provider catalog)'),
+                model: zod_1.z.string().optional().describe('create/generate/smash: model override (validated against the provider catalog)'),
                 aiEngine: zod_1.z
                     .string()
                     .optional()
-                    .describe('generate: provider/engine override (must be an installed provider; defaults to primary)'),
+                    .describe('create/generate: provider/engine override (must be an installed provider; defaults to primary)'),
                 contextScope: zod_1.z
                     .record(zod_1.z.unknown())
                     .optional()
-                    .describe('generate: context-awareness flags {specrails,openspec,full,mcp,userMcp,contractRefine}'),
-                contractRefine: zod_1.z.boolean().optional().describe('generate: enrich the spec with a Contract Layer (Claude-only)'),
-                attachmentIds: zod_1.z.array(zod_1.z.string()).optional().describe('generate: attachment ids (requires pendingSpecId)'),
+                    .describe('create/generate: context-awareness flags {specrails,openspec,full,mcp,userMcp,contractRefine}'),
+                contractRefine: zod_1.z.boolean().optional().describe('create/generate: enrich the spec with a Contract Layer (Claude-only)'),
+                attachmentIds: zod_1.z.array(zod_1.z.string()).optional().describe('create/generate/ai_edit: attachment ids (create/generate require pendingSpecId)'),
                 // ── ai_edit ──────────────────────────────────────────────────────
                 instructions: zod_1.z.string().optional().describe('ai_edit: natural-language editing instructions (required)'),
                 priorInstructions: zod_1.z.array(zod_1.z.string()).optional().describe('ai_edit: prior refinement turns for an iterative edit'),
@@ -156,6 +168,20 @@ function specsTools() {
                     }
                     return id;
                 };
+                // Shared body builder for the two Quick Add Spec entry points
+                // (POST /tickets/generate-spec): `create` derives the idea from
+                // title/description, `generate` takes it pre-formed. Both forward the
+                // full option set (undefined fields are dropped by JSON.stringify).
+                const buildGenerateSpecBody = (idea) => ({
+                    idea,
+                    model: args.model,
+                    aiEngine: args.aiEngine,
+                    contextScope: args.contextScope,
+                    contractRefine: args.contractRefine,
+                    attachmentIds: args.attachmentIds,
+                    pendingSpecId: args.pendingSpecId,
+                    createLocal: args.createLocal,
+                });
                 switch (action) {
                     // ── reads ──────────────────────────────────────────────────────
                     case 'list': {
@@ -198,19 +224,21 @@ function specsTools() {
                         // following the project's conventions, instead of a raw insert of
                         // whatever the external LLM wrote. The user's request becomes the
                         // `idea`. For a verbatim insert with no AI, use `from_prompt`.
+                        // generate-spec accepts none of labels/priority/status/assignee —
+                        // throwing turns the likeliest silent misuse into a self-correcting error.
+                        if (args.labels !== undefined ||
+                            args.priority !== undefined ||
+                            args.status !== undefined ||
+                            args.assignee !== undefined) {
+                            throw new Error('create generates the spec with AI and cannot set labels/priority directly — use commit_draft (you control everything) or update after generation.');
+                        }
                         const idea = [args.title, args.description]
                             .filter((v) => typeof v === 'string' && v.trim().length > 0)
                             .join('\n\n')
                             .trim();
                         if (!idea)
                             throw new Error('create requires a "title" and/or "description" to use as the spec idea.');
-                        const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/tickets/generate-spec`, {
-                            idea,
-                            model: args.model,
-                            aiEngine: args.aiEngine,
-                            provider: args.provider,
-                            contractRefine: args.contractRefine,
-                        });
+                        const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/tickets/generate-spec`, buildGenerateSpecBody(idea));
                         return { ...r, hint: WATCH_HINT };
                     }
                     case 'update':
@@ -257,6 +285,9 @@ function specsTools() {
                             acceptanceCriteria: args.acceptanceCriteria,
                             priority: args.priority,
                             shortSummary: args.shortSummary,
+                            assignee: args.assignee,
+                            prerequisites: args.prerequisites,
+                            metadata: args.metadata,
                             createLocal: args.createLocal,
                         });
                     case 'cancel_ai_edit': {
@@ -280,16 +311,7 @@ function specsTools() {
                     case 'generate': {
                         if (!args.idea)
                             throw new Error('generate requires an "idea".');
-                        const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/tickets/generate-spec`, {
-                            idea: args.idea,
-                            model: args.model,
-                            aiEngine: args.aiEngine,
-                            contextScope: args.contextScope,
-                            contractRefine: args.contractRefine,
-                            attachmentIds: args.attachmentIds,
-                            pendingSpecId: args.pendingSpecId,
-                            createLocal: args.createLocal,
-                        });
+                        const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/tickets/generate-spec`, buildGenerateSpecBody(args.idea));
                         return { ...r, hint: WATCH_HINT };
                     }
                     case 'ai_edit': {
@@ -309,7 +331,7 @@ function specsTools() {
                     }
                     case 'contract_refine': {
                         const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/tickets/${requireId()}/contract-refine`);
-                        return { ...r, hint: WATCH_HINT };
+                        return { ...r, hint: CONTRACT_REFINE_HINT };
                     }
                     case 'smash': {
                         const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/tickets/${requireId()}/smash`, {

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

@@ -56,13 +56,17 @@ function requireProject(ctx, projectId) {
     return pc;
 }
 // ── Active-project stickiness (per server process) ────────────────────────────
-// The active project is a soft default; an explicit projectId always wins.
+// The active project is a soft default; an explicit projectId always wins, and
+// a per-request pin (ctx.requestProjectId, from the in-app agent's loopback
+// header) wins over the process-wide selection. `setActiveProject` remains for
+// `specrails_select_project` (and, fallback-only, the agent-chat manager's
+// per-turn pin) — request headers must never mutate this global.
 let _activeProjectId = null;
 function setActiveProject(id) {
     _activeProjectId = id;
 }
-function getActiveProject(_ctx) {
-    return _activeProjectId;
+function getActiveProject(ctx) {
+    return ctx.requestProjectId ?? _activeProjectId;
 }
 function tierAnnotations(tier) {
     switch (tier) {
@@ -93,7 +97,9 @@ function errorResult(message) {
  */
 function emitMcpActivity(ctx, spec, args, tier) {
     try {
-        const affectedProjectId = (typeof args.projectId === 'string' ? args.projectId : null) ?? getActiveProject(ctx);
+        const affectedProjectId = (typeof args.projectId === 'string' ? args.projectId : null) ??
+            ctx.requestProjectId ??
+            getActiveProject(ctx);
         ctx.broadcast({
             type: 'mcp.activity',
             tool: spec.name,
@@ -123,12 +129,15 @@ function registerTieredTool(server, ctx, spec) {
     }, async (args, extra) => {
         // In-app agent: a per-request active-project header (loopback-only, set by
         // the agent's bridge from the Cursor-style selector) pins the project for
-        // this call so project-scoped tools resolve without specrails_select_project.
+        // THIS CALL ONLY via a per-call ctx copy — it must never mutate the
+        // process-wide active project, or a concurrent external MCP client and the
+        // in-app agent would clobber each other (wrong-project delete/launch).
         const projectHeader = extra?.requestInfo?.headers?.[agent_tier_1.AGENT_PROJECT_HEADER];
+        let callCtx = ctx;
         if (projectHeader != null) {
             const pid = Array.isArray(projectHeader) ? projectHeader[0] : projectHeader;
             if (typeof pid === 'string' && pid.trim())
-                setActiveProject(pid.trim());
+                callCtx = { ...ctx, requestProjectId: pid.trim() };
         }
         const tier = typeof spec.tier === 'function' ? spec.tier(args ?? {}) : spec.tier;
         // In-app agent: when the request carries the loopback-only agent-tier header,
@@ -144,9 +153,9 @@ function registerTieredTool(server, ctx, spec) {
             return errorResult((0, mcp_tiers_1.tierRefusalMessage)(tier));
         }
         try {
-            const data = await spec.handler(ctx, args ?? {});
+            const data = await spec.handler(callCtx, args ?? {});
             if (tier !== 'read')
-                emitMcpActivity(ctx, spec, args ?? {}, tier);
+                emitMcpActivity(callCtx, spec, args ?? {}, tier);
             return toResult(data);
         }
         catch (err) {

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

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.watchTool = watchTool;
 const zod_1 = require("zod");
+const types_1 = require("./types");
 // Event `type` suffixes/strings that mean an async operation has settled.
 const TERMINAL_PATTERNS = [
     'job.finalized',
@@ -17,12 +18,25 @@ const TERMINAL_PATTERNS = [
     'agent_refine_error',
     'smash.completed',
     'smash.failed',
+    'smash.undone',
     'loop.run_completed',
     'loop.run_stopped',
     'explore.contract_refine_failed',
     'file.summary_updated',
     'file.summary_failed',
+    'setup_install_done',
+    'setup_error',
+    'plugin.installed',
+    'plugin.degraded',
 ];
+// Job statuses that mean a polled job has settled (see project-router-jobs.ts).
+const TERMINAL_JOB_STATUSES = new Set(['completed', 'failed', 'canceled']);
+// Jobs are identified by UUIDs (server/ids.ts newId → randomUUID). When the ref
+// looks like one, the wait loop also polls the job read as a fallback for jobs
+// that never emit a watch-terminal event (e.g. rail-bypass `spawn` jobs).
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const JOB_POLL_INTERVAL_MS = 5000;
+const TIMEOUT_SUGGESTION = 'timeout ≠ failure — the operation may still be running. Re-watch with the same ref, or poll specrails_jobs(get)/specrails_specs(get) for current state.';
 function isTerminal(type) {
     return TERMINAL_PATTERNS.some((p) => type === p || type.endsWith(p));
 }
@@ -40,19 +54,35 @@ function watchTool() {
     return {
         name: 'specrails_watch',
         title: 'Watch async result',
-        description: 'Wait for an asynchronous operation (rail launch, spec generation, chat turn, agent refine, SMASH, loop run) to settle ' +
-            'and return its events. Pass the projectId and the reference (jobId / requestId) returned by the action. ' +
-            'Resolves when a terminal event for that reference is seen, or after untilMs.',
+        description: 'Wait for an asynchronous operation (rail launch, spec generation, chat turn, agent refine, SMASH, loop run, plugin install, setup install) to settle ' +
+            'and return its events. Pass the reference (jobId / requestId / conversationId / loopRunId) returned by the action; projectId is optional ' +
+            '(defaults to the active project; app-level operations need none). ' +
+            'Resolves when a terminal event for that reference is seen, or after untilMs. ' +
+            'When the ref is a jobId (or kind:"job" is passed), the job status is also polled every 5s so jobs settle even without a watch-terminal event. ' +
+            'Default untilMs 120000 is often shorter than a rail run (max 600000). ' +
+            'settled:false means TIMEOUT, not failure — re-watch or poll the domain read (specrails_jobs(get) / specrails_specs(get) / specrails_plugins(health)).',
         tier: 'read',
         inputSchema: {
-            projectId: zod_1.z.string().describe('Project id the operation runs in'),
-            ref: zod_1.z.string().describe('jobId / requestId / loopRunId returned by the async action'),
+            projectId: zod_1.z
+                .string()
+                .optional()
+                .describe('Project id the operation runs in (defaults to the active project; omit for app-level operations)'),
+            ref: zod_1.z.string().describe('jobId / requestId / conversationId / loopRunId returned by the async action'),
             untilMs: zod_1.z.number().int().min(1000).max(600000).default(120000).describe('Max time to wait (ms)'),
+            kind: zod_1.z
+                .enum(['job'])
+                .optional()
+                .describe('Force the ref to be treated as a jobId (enables the 5s job-status poll fallback even for non-UUID ids)'),
         },
         handler: (ctx, args) => {
-            const projectId = args.projectId;
+            // Optional + active-project resolution: an explicit projectId wins, else
+            // the active project. When neither exists, project filtering is skipped —
+            // the ref-substring match is discriminating enough, and app-level agent
+            // operations carry no projectId at all.
+            const projectId = args.projectId ?? (0, types_1.getActiveProject)(ctx) ?? undefined;
             const ref = args.ref;
             const untilMs = args.untilMs ?? 120000;
+            const pollAsJob = args.kind === 'job' || UUID_RE.test(ref);
             return new Promise((resolve) => {
                 const events = [];
                 let done = false;
@@ -61,20 +91,23 @@ function watchTool() {
                         return;
                     done = true;
                     clearTimeout(timer);
+                    if (poller)
+                        clearInterval(poller);
                     unsub();
                     resolve({
                         settled,
                         reason,
                         ref,
-                        projectId,
+                        projectId: projectId ?? null,
                         eventCount: events.length,
                         terminalEvent: settled ? events[events.length - 1] : null,
                         events: events.slice(-50),
+                        ...(settled ? {} : { suggestion: TIMEOUT_SUGGESTION }),
                     });
                 };
                 const unsub = ctx.eventBus.onMessage((msg) => {
                     const msgProjectId = msg.projectId;
-                    if (msgProjectId && msgProjectId !== projectId)
+                    if (projectId && msgProjectId && msgProjectId !== projectId)
                         return;
                     if (!mentionsRef(msg, ref))
                         return;
@@ -83,6 +116,36 @@ function watchTool() {
                     if (isTerminal(type))
                         finish(true, `terminal:${type}`);
                 });
+                // Job-status poll fallback: some jobs (rail-bypass spawn) never emit a
+                // watch-terminal event; poll the job read every 5s and settle when its
+                // status is terminal. Polling needs a resolvable project; errors (e.g.
+                // the ref is not a job in this project) are ignored and the wait
+                // continues on the event path.
+                let poller;
+                if (pollAsJob && projectId) {
+                    let polling = false;
+                    poller = setInterval(() => {
+                        if (done || polling)
+                            return;
+                        polling = true;
+                        (0, types_1.apiCall)(ctx, 'GET', `/projects/${encodeURIComponent(projectId)}/jobs/${encodeURIComponent(ref)}`)
+                            .then((r) => {
+                            const status = r?.job?.status;
+                            if (typeof status === 'string' && TERMINAL_JOB_STATUSES.has(status)) {
+                                events.push({ type: 'job.poll_settled', projectId, jobId: ref, status });
+                                finish(true, `poll:job:${status}`);
+                            }
+                        })
+                            .catch(() => {
+                            /* not a job / transient error — keep waiting on events */
+                        })
+                            .finally(() => {
+                            polling = false;
+                        });
+                    }, JOB_POLL_INTERVAL_MS);
+                    if (typeof poller.unref === 'function')
+                        poller.unref();
+                }
                 const timer = setTimeout(() => finish(false, 'timeout'), untilMs);
                 // Do not keep the event loop alive solely for this watch.
                 if (typeof timer.unref === 'function')

package/server/dist/project-router-helpers.js

@@ -55,7 +55,7 @@ function serializeInstallConfigYaml(config) {
     return lines.join('\n');
 }
 // ─── Agent model helpers ──────────────────────────────────────────────────────
-const VALID_MODEL_ALIASES = ['sonnet', 'opus', 'haiku'];
+const VALID_MODEL_ALIASES = ['sonnet', 'fable', 'opus', 'haiku'];
 exports.VALID_MODEL_ALIASES = VALID_MODEL_ALIASES;
 /**
  * Relocate-artifacts: where the agent `.claude/agents/*.md` files live. When the

package/server/dist/project-router-tickets.js

@@ -802,6 +802,27 @@ function registerTicketsRoutes(deps) {
                 .filter((c) => c.length > 0)
             : [];
         const priority = (0, ticket_store_1.isValidPriority)(body.priority) ? body.priority : 'medium';
+        // Optional assignee/prerequisites/metadata (same normalization as the
+        // PATCH /tickets/:id route) so an MCP commit_draft is a true one-shot
+        // insert — no follow-up update call needed for these fields.
+        const hasAssignee = body.assignee !== undefined;
+        const assignee = typeof body.assignee === 'string' ? body.assignee : null;
+        const hasPrerequisites = Array.isArray(body.prerequisites);
+        const prerequisites = hasPrerequisites
+            ? body.prerequisites.filter((p) => typeof p === 'number')
+            : [];
+        const hasMetadata = typeof body.metadata === 'object' && body.metadata !== null;
+        const metadata = hasMetadata ? body.metadata : {};
+        // A supplied conversationId must reference a REAL chat conversation in this
+        // project (an Explore row in chat_conversations). Agent/desktop conversation
+        // ids are NOT valid origins — stamping one would corrupt the ticket's origin
+        // linkage ("Continue Explore") and mis-schedule Contract Refine.
+        if (conversationId && !(0, db_1.getConversation)(ctx(req).db, conversationId)) {
+            res.status(400).json({
+                error: "conversationId not found in this project's chat conversations — agent conversations are not valid origins; omit conversationId",
+            });
+            return;
+        }
         // Compose the final ticket body. The title is already its own ticket
         // field, so we deliberately do NOT echo it as a `## Spec Title` heading
         // inside the description. The body is just the structured sections from
@@ -865,6 +886,14 @@ function registerTicketsRoutes(deps) {
                     flipTarget.description = descriptionForStore;
                     if (labels.length > 0)
                         flipTarget.labels = labels;
+                    // PATCH-route semantics: apply only when the field was supplied;
+                    // metadata merges keys instead of replacing the object.
+                    if (hasAssignee)
+                        flipTarget.assignee = assignee;
+                    if (hasPrerequisites)
+                        flipTarget.prerequisites = prerequisites;
+                    if (hasMetadata)
+                        flipTarget.metadata = { ...flipTarget.metadata, ...metadata };
                     flipTarget.updated_at = now;
                     // Preserve prior short_summary on flip when the model/body omits one;
                     // overwrite only when a non-null value is provided.
@@ -898,9 +927,9 @@ function registerTicketsRoutes(deps) {
                     status: 'todo',
                     priority,
                     labels,
-                    assignee: null,
-                    prerequisites: [],
-                    metadata: {},
+                    assignee,
+                    prerequisites,
+                    metadata,
                     comments: [],
                     origin_conversation_id: conversationId,
                     is_epic: false,
@@ -1884,7 +1913,17 @@ function registerTicketsRoutes(deps) {
         // non-ASCII names survive.
         const asciiName = meta.filename.replace(/[\r\n"]/g, '_');
         res.setHeader('Content-Disposition', `inline; filename="${asciiName}"; filename*=UTF-8''${encodeURIComponent(meta.filename)}`);
-        fs_1.default.createReadStream(abs).pipe(res);
+        // The exists check above is not atomic with the stream's async open — a
+        // concurrent attachment DELETE can rm the file in between, and an unhandled
+        // ReadStream 'error' would take down the sidecar.
+        const stream = fs_1.default.createReadStream(abs);
+        stream.on('error', () => {
+            if (!res.headersSent)
+                res.status(404).json({ error: 'Attachment not found' });
+            else
+                res.destroy();
+        });
+        stream.pipe(res);
     });
     router.delete('/:projectId/tickets/:ticketId/attachments/:attachmentId', async (req, res) => {
         const parsed = parseTicketKey(req.params.ticketId);

package/server/dist/providers/claude-adapter.js

@@ -13,6 +13,7 @@ const child_process_1 = require("child_process");
 const WHICH_CMD = process.platform === 'win32' ? 'where' : 'which';
 const CLAUDE_MODELS = [
     { value: 'sonnet', label: 'Claude Sonnet', default: true },
+    { value: 'fable', label: 'Claude Fable' },
     { value: 'opus', label: 'Claude Opus' },
     { value: 'haiku', label: 'Claude Haiku' },
 ];
@@ -20,11 +21,14 @@ const CLAUDE_MODELS = [
  *  CLI accepts collapse to the short alias. */
 function normaliseModel(model) {
     switch (model) {
+        case 'claude-sonnet-5':
         case 'claude-sonnet-4-6':
         case 'claude-sonnet-4-5':
         case 'claude-sonnet-4-0':
         case 'claude-sonnet-4-20250514':
             return 'sonnet';
+        case 'claude-fable-5':
+            return 'fable';
         case 'claude-opus-4-8':
         case 'claude-opus-4-5':
         case 'claude-opus-4-1-20250805':
@@ -317,6 +321,8 @@ exports.claudeAdapter = {
         systemPromptArg: true,
         persistentStdin: true,
         supportsReasoningEffort: true,
+        reasoningEfforts: ['low', 'medium', 'high', 'xhigh'], // claude-code --effort tiers
+        supportsImageInput: true, // images ride as `@<abs-path>` prompt refs
     },
     modelCatalog: () => CLAUDE_MODELS,
     defaultModel: () => 'sonnet',