specrails-desktop 2.2.1 → 2.4.0

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

@@ -0,0 +1,1815 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerTicketsRoutes = registerTicketsRoutes;
+// Domain routes extracted from project-router.ts (tickets).
+// Registered on the shared router by createProjectRouter — behaviour-preserving.
+const fs_1 = __importDefault(require("fs"));
+const ids_1 = require("./ids");
+const db_1 = require("./db");
+const providers_1 = require("./providers");
+const contract_refine_runner_1 = require("./contract-refine-runner");
+const explore_contract_refine_1 = require("./explore-contract-refine");
+const smash_runner_1 = require("./smash-runner");
+const explore_smash_1 = require("./explore-smash");
+const ai_invocations_1 = require("./ai-invocations");
+const context_scope_1 = require("./context-scope");
+const result_event_1 = require("./result-event");
+const crypto_1 = require("crypto");
+const spec_models_1 = require("./spec-models");
+const provider_selection_1 = require("./provider-selection");
+const ticket_store_1 = require("./ticket-store");
+const explore_draft_title_1 = require("./explore-draft-title");
+const cli_prompt_1 = require("./util/cli-prompt");
+const readline_1 = require("readline");
+const tree_kill_1 = __importDefault(require("tree-kill"));
+const multer_1 = __importDefault(require("multer"));
+const attachment_manager_1 = require("./attachment-manager");
+const project_router_helpers_1 = require("./project-router-helpers");
+/**
+ * Add Spec on a Jira-backed project: promote the freshly-created LOCAL ticket to
+ * a Jira issue (best-effort, server-side). The per-spec `createLocal` escape
+ * hatch keeps it local. On any failure the ticket simply stays local and a
+ * non-fatal warning is broadcast — a spec is never lost to a Jira error.
+ */
+async function maybePromoteSpecToJira(c, ticketId, createLocal, broadcast) {
+    // jiraSyncManager is always present in production (constructed per project);
+    // guard defensively so partial test contexts and a disabled feature are no-ops.
+    if (createLocal || !c.jiraSyncManager?.isActive())
+        return;
+    try {
+        const r = await c.jiraSyncManager.promoteTicketToJira(ticketId);
+        if (!r.ok) {
+            broadcast({ type: 'jira.sync_error', projectId: c.project.id, reason: `Kept as a local spec — couldn't create it in Jira: ${r.error}` });
+        }
+    }
+    catch (err) {
+        console.error('[project-router] jira promote failed:', err);
+    }
+}
+function registerTicketsRoutes(deps) {
+    const { router, registry, ctx, ticketPath } = deps;
+    // ─── Tickets ──────────────────────────────────────────────────────────────────
+    /** Resolve the ticket storage file path for a project */
+    // GET /:projectId/tickets — List all tickets with optional filters
+    router.get('/:projectId/tickets', (req, res) => {
+        try {
+            const filePath = ticketPath(req);
+            const store = (0, ticket_store_1.readStore)(filePath);
+            const allTickets = Object.values(store.tickets);
+            const filtered = (0, ticket_store_1.filterTickets)(allTickets, {
+                status: req.query.status,
+                label: req.query.label,
+                q: req.query.q,
+            });
+            // Sort by updated_at descending
+            filtered.sort((a, b) => (b.updated_at || '').localeCompare(a.updated_at || ''));
+            res.json({ tickets: filtered, revision: store.revision, total: allTickets.length });
+        }
+        catch (err) {
+            console.error('[project-router] ticket list error:', err);
+            res.status(500).json({ error: 'Failed to read tickets' });
+        }
+    });
+    // GET /:projectId/tickets/:id — Get single ticket
+    router.get('/:projectId/tickets/:id', (req, res) => {
+        const ticketId = req.params.id;
+        if (!/^\d+$/.test(ticketId)) {
+            res.status(400).json({ error: 'Invalid ticket ID' });
+            return;
+        }
+        try {
+            const store = (0, ticket_store_1.readStore)(ticketPath(req));
+            const ticket = store.tickets[ticketId];
+            if (!ticket) {
+                res.status(404).json({ error: 'Ticket not found' });
+                return;
+            }
+            res.json({ ticket, revision: store.revision });
+        }
+        catch (err) {
+            console.error('[project-router] ticket get error:', err);
+            res.status(500).json({ error: 'Failed to read ticket' });
+        }
+    });
+    // POST /:projectId/tickets/generate-spec — Fast AI spec generation (no codebase exploration)
+    router.post('/:projectId/tickets/generate-spec', async (req, res) => {
+        const idea = req.body?.idea;
+        if (!idea?.trim()) {
+            res.status(400).json({ error: 'idea is required' });
+            return;
+        }
+        const attachmentIds = Array.isArray(req.body?.attachmentIds)
+            ? req.body.attachmentIds.filter((x) => typeof x === 'string')
+            : [];
+        const pendingSpecId = typeof req.body?.pendingSpecId === 'string' ? req.body.pendingSpecId : null;
+        if (attachmentIds.length > 0 && !pendingSpecId) {
+            res.status(400).json({ error: 'pendingSpecId is required when attachmentIds are provided' });
+            return;
+        }
+        const { project, broadcast, ticketWatcher } = ctx(req);
+        // Multi-provider: optional aiEngine (alias provider) picks the engine for
+        // this Quick spec; must be installed on the project. Omitting it uses the
+        // primary provider.
+        const requestedEngine = req.body?.aiEngine ?? req.body?.provider;
+        const engineCheck = (0, provider_selection_1.validateRequestedProvider)(project, requestedEngine);
+        if (!engineCheck.ok) {
+            res.status(400).json({ error: engineCheck.error });
+            return;
+        }
+        const provider = engineCheck.provider;
+        // Resolve and validate the model. Order:
+        //   - Body had a `model` and it's valid → use it.
+        //   - Body had a `model` and it's invalid → 400 with the allow-list.
+        //   - Body had no `model` → fall back to project default.
+        const rawModel = req.body?.model;
+        let resolvedModel;
+        if (rawModel === undefined || rawModel === null || rawModel === '') {
+            resolvedModel = (0, project_router_helpers_1.resolveDefaultSpecModel)({ projectPath: project.path, provider });
+        }
+        else if ((0, spec_models_1.isValidModelForProvider)(rawModel, provider)) {
+            resolvedModel = rawModel;
+        }
+        else {
+            res.status(400).json({
+                error: `Invalid model "${String(rawModel)}" for provider "${provider}"`,
+                allowed: (0, spec_models_1.getModelsForProvider)(provider).map((m) => m.value),
+            });
+            return;
+        }
+        const requestId = (0, ids_1.newId)();
+        const projectId = project.id;
+        const filePath = ticketPath(req);
+        let hasAttachments = false;
+        let baseUserPrompt = `Generate a spec for the following idea:\n\n${idea.trim()}`;
+        let imageFlags = [];
+        if (attachmentIds.length > 0 && pendingSpecId) {
+            try {
+                const extracted = await attachment_manager_1.attachmentManager.getClaudeArgs(project.slug, pendingSpecId, attachmentIds);
+                imageFlags = extracted.imageFlags;
+                if (extracted.textBlocks.length > 0) {
+                    hasAttachments = true;
+                    baseUserPrompt = `${baseUserPrompt}\n\n## Attached Resources\n\n${extracted.textBlocks.join('\n\n')}`;
+                }
+            }
+            catch (err) {
+                console.error('[project-router] generate-spec attachment extraction error:', err);
+            }
+        }
+        // Parse contextScope from body. Quick and Explore share the same Context
+        // Awareness controls; Quick still keeps Contract Refine as a top-level
+        // field for the refine scheduler.
+        const rawScope = req.body?.contextScope;
+        // Contract Layer is Claude-only — force it off for any non-claude engine
+        // (defence-in-depth; the Quick UI hides the toggle for those).
+        const quickContractRefine = provider !== 'claude'
+            ? false
+            : typeof req.body?.contractRefine === 'boolean'
+                ? req.body.contractRefine
+                : typeof rawScope?.contractRefine === 'boolean'
+                    ? rawScope.contractRefine
+                    : false;
+        const quickScope = {
+            specrails: typeof rawScope?.specrails === 'boolean' ? rawScope.specrails : false,
+            openspec: typeof rawScope?.openspec === 'boolean' ? rawScope.openspec : false,
+            full: typeof rawScope?.full === 'boolean' ? rawScope.full : false,
+            // Quick spawns from project.path, so project `.mcp.json` (the `mcp`
+            // toggle) is discovered natively. `userMcp` additionally loads the
+            // developer's user-scope/plugin/connector MCP servers via the claude
+            // adapter's `loadUserEnv` (see below).
+            mcp: typeof rawScope?.mcp === 'boolean' ? rawScope.mcp : false,
+            contractRefine: quickContractRefine,
+            userMcp: typeof rawScope?.userMcp === 'boolean' ? rawScope.userMcp : false,
+        };
+        // Persist Quick mode Contract Refine choice (per-project last value).
+        (0, db_1.setQuickContractRefineLast)(ctx(req).db, quickContractRefine);
+        const specsPrefix = (0, context_scope_1.buildScopedSystemPromptPrefix)(quickScope, project.path);
+        const codebaseRule = quickScope.full
+            ? `- You MAY use Read, Grep, and Glob to inspect the project codebase. Bash is not available.`
+            : hasAttachments
+                ? `- Do NOT explore the project codebase. The resources inside <user-attachment> blocks below are pre-loaded context the user intentionally provided — read and use them freely.`
+                : `- Do NOT read any files or explore the codebase. Work purely from the user's description.`;
+        // The specrails-tickets prefix (when scope.specrails is toggled on)
+        // dumps every ticket into the prompt as informational context. Without
+        // an explicit dedup instruction the model treats it as background and
+        // still proposes a near-duplicate of something already in the backlog.
+        // Adding the rule here, gated on `quickScope.specrails`, keeps the
+        // "toggle is the only gate" contract the user asked for.
+        const dedupRule = quickScope.specrails
+            ? `- The "Specrails Tickets" section above lists every ticket already in the backlog. Do NOT propose a duplicate or a near-duplicate of any of them. If the user's idea is already covered by an existing ticket, say so in "Problem Statement" and pick a *different* angle / sub-feature / next step that builds on the existing one — do not repeat it.\n`
+            : '';
+        const backlogRecommendationRule = quickScope.specrails
+            ? `- If the user's idea asks for the "next best spec" or a backlog recommendation, use the existing tickets and OpenSpec context to choose one concrete next spec. Do not respond with generic product directions.\n`
+            : '';
+        let baseSystemPrompt = `You are a senior product engineer generating a structured spec proposal.\n\n` +
+            (specsPrefix ? `${specsPrefix}\n\n` : '') +
+            `RULES:\n` +
+            `${codebaseRule}\n` +
+            dedupRule +
+            backlogRecommendationRule +
+            `- Do NOT create files, tickets, or issues.\n` +
+            `- Output ONLY the structured markdown below. No preamble, no explanation.\n\n` +
+            `REQUIRED FORMAT:\n` +
+            `## Spec Title\n[Concise, action-oriented title]\n\n` +
+            `## Labels\n[2-4 short kebab-case tags categorising the spec — comma-separated on one line, e.g. "ui, settings, dark-mode". Lowercase, no spaces inside a tag.]\n\n` +
+            `## Problem Statement\n[2-3 sentences]\n\n` +
+            `## Proposed Solution\n[3-5 sentences]\n\n` +
+            `## Out of Scope\n[Bullet list]\n\n` +
+            `## Acceptance Criteria\n[Numbered list of testable outcomes]\n\n` +
+            `## Technical Considerations\n[Bullet list]\n\n` +
+            `## Estimated Complexity\n[Low/Medium/High/Very High + one sentence justification]\n\n` +
+            `## Short Summary\n[One or two plain-language sentences, max 120 characters total, that capture the essence of this spec for a dashboard postit. No markdown, no bullets, no headings.]`;
+        if (hasAttachments)
+            baseSystemPrompt = `${baseSystemPrompt}\n\n${attachment_manager_1.USER_ATTACHMENT_SYSTEM_NOTE}`;
+        const systemPrompt = baseSystemPrompt;
+        const userPrompt = baseUserPrompt;
+        // Generate-spec spawn args are adapter-driven. For Claude the `--tools`
+        // flag set comes from `toolFlagsForScope(quickScope)` which the adapter
+        // doesn't model — pass them through `extraArgs` so they slot in after
+        // the standard COMMON_FLAGS. `imageFlags` (also Claude-only) goes the
+        // same way. For codex the system prompt folds into the user prompt
+        // (no --system-prompt flag) and the extra Claude-only flags are ignored
+        // by the codex adapter (it doesn't read extraArgs that don't apply).
+        const adapter = (0, providers_1.getAdapter)(provider);
+        const toolFlags = provider === 'claude' ? (0, context_scope_1.toolFlagsForScope)(quickScope) : { args: [] };
+        // Full scope grants Read/Grep/Glob. The model spends turns exploring the
+        // repo before it writes the spec; 6 was too tight (a few tool calls on a
+        // sparse/empty repo hit error_max_turns → exit 1 → opaque failure). 15
+        // leaves comfortable headroom while --max-turns still bounds runaway loops.
+        const claudeMaxTurns = quickScope.full ? 15 : (hasAttachments ? 3 : 1);
+        const args = adapter.buildArgs('spec-gen', {
+            prompt: userPrompt,
+            systemPrompt,
+            model: resolvedModel,
+            maxTurns: provider === 'claude' ? claudeMaxTurns : undefined,
+            extraArgs: provider === 'claude' ? [...toolFlags.args, ...imageFlags] : undefined,
+            // "My approved MCPs" (scope.userMcp) loads the developer's user-scope,
+            // plugin, and connector MCP servers (claude-only). Quick already spawns
+            // from project.path so project `.mcp.json` is discovered without a flag.
+            loadUserEnv: provider === 'claude' && quickScope.userMcp,
+        });
+        const binary = adapter.binary;
+        // spawnAiCli reroutes multi-line argv values through stdin on Windows;
+        // POSIX argv path unchanged.
+        console.log(`[project-router] spec-gen spawn: ${binary} (cwd=${project.path}, requestId=${requestId})`);
+        const child = (0, cli_prompt_1.spawnAiCli)(binary, args, {
+            env: process.env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            cwd: project.path,
+        });
+        // Watchdog: unlike ai-edit, generate-spec keeps no cancellable handle, so a
+        // hung CLI (network stall, model never emitting a terminating event) would
+        // otherwise leak this child + its readline for the app's lifetime. Cap is
+        // generous — the 'full' scope can legitimately run minutes and --max-turns
+        // bounds turns, not wall-clock. Cleared on close/error.
+        const GENERATE_SPEC_TIMEOUT_MS = 8 * 60 * 1000;
+        let specGenWatchdog = setTimeout(() => {
+            specGenWatchdog = null;
+            if (child.pid) {
+                try {
+                    (0, tree_kill_1.default)(child.pid, 'SIGTERM');
+                }
+                catch { /* best-effort */ }
+            }
+            broadcast({
+                type: 'spec_gen_error', projectId, requestId,
+                error: `Spec generation timed out after ${Math.round(GENERATE_SPEC_TIMEOUT_MS / 1000)}s`,
+                timestamp: new Date().toISOString(),
+            });
+        }, GENERATE_SPEC_TIMEOUT_MS);
+        if (typeof specGenWatchdog.unref === 'function')
+            specGenWatchdog.unref();
+        const clearSpecGenWatchdog = () => {
+            if (specGenWatchdog) {
+                clearTimeout(specGenWatchdog);
+                specGenWatchdog = null;
+            }
+        };
+        // Capture stderr so failures (auth missing, model errors, etc.) surface
+        // in the server log instead of being swallowed.
+        let stderrBuf = '';
+        /* c8 ignore start -- diagnostic-only; fires only when claude writes stderr */
+        child.stderr?.on('data', (chunk) => {
+            const s = chunk.toString();
+            stderrBuf += s;
+            console.error(`[project-router] spec-gen stderr (${requestId}): ${s.trimEnd()}`);
+        });
+        /* c8 ignore stop */
+        // Without this listener, ENOENT (binary missing on PATH) propagates as
+        // an unhandled 'error' event and crashes the entire app process.
+        /* c8 ignore start -- spawn-failure path; exercised manually, not in CI */
+        child.on('error', (err) => {
+            clearSpecGenWatchdog();
+            console.error(`[project-router] spec-gen spawn failed (${binary}): ${err.message}`);
+            const errMsg = {
+                type: 'spec_gen_error', projectId, requestId,
+                error: `Failed to launch ${binary}: ${err.message}`,
+                timestamp: new Date().toISOString(),
+            };
+            broadcast(errMsg);
+        });
+        /* c8 ignore stop */
+        res.status(202).json({ requestId });
+        let buffer = '';
+        let lastResultEvent = null;
+        // Canonical adapter events feed finaliseInvocationResult on close, giving
+        // codex a real pricing-table cost estimate (+ estimated flag) and tokens,
+        // instead of the legacy hardcoded $0. Accumulated ALONGSIDE the existing
+        // buffer/delta plumbing below — never in place of it.
+        const adapterEvents = [];
+        const turnStartedAt = new Date().toISOString();
+        const stdoutReader = (0, readline_1.createInterface)({ input: child.stdout, crlfDelay: Infinity });
+        stdoutReader.on('line', (line) => {
+            const adapterEv = adapter.parseStreamLine(line);
+            if (adapterEv)
+                adapterEvents.push(adapterEv);
+            let parsed = null;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch { /* skip */ }
+            if (!parsed)
+                return;
+            if (provider === 'codex') {
+                // Codex `exec --json` emits one event per line. Capture the final
+                // `turn.completed` for usage extraction, and accumulate ONLY the
+                // assistant_message text — never the command_execution items or
+                // wrapper events, otherwise the raw JSONL ends up in the ticket
+                // description.
+                if (parsed.type === 'turn.completed') {
+                    lastResultEvent = parsed;
+                    return;
+                }
+                if (parsed.type !== 'item.completed')
+                    return;
+                const item = parsed.item;
+                if (!item || item.type !== 'agent_message')
+                    return;
+                const newText = (item.text ?? '').trim();
+                if (!newText)
+                    return;
+                // Each agent_message is a complete chunk — separate with a blank
+                // line so the parser regexes match cleanly across chunks.
+                buffer += (buffer.endsWith('\n') || buffer.length === 0 ? '' : '\n') + newText + '\n';
+                const msg = {
+                    type: 'spec_gen_stream', projectId, requestId,
+                    delta: newText + '\n', timestamp: new Date().toISOString(),
+                };
+                broadcast(msg);
+                return;
+            }
+            // Claude path.
+            if (parsed.type === 'result') {
+                lastResultEvent = parsed;
+            }
+            if (parsed.type === 'assistant') {
+                const msg = parsed.message;
+                const texts = (msg?.content ?? [])
+                    .filter((c) => c.type === 'text')
+                    .map((c) => c.text ?? '');
+                const newText = texts.join('');
+                if (newText) {
+                    buffer += newText;
+                    const wsMsg = {
+                        type: 'spec_gen_stream', projectId, requestId,
+                        delta: newText, timestamp: new Date().toISOString(),
+                    };
+                    broadcast(wsMsg);
+                }
+            }
+        });
+        child.on('close', async (code) => {
+            clearSpecGenWatchdog();
+            let createdTicketId = null;
+            // When claude burns its whole --max-turns budget it exits non-zero with
+            // a result event of subtype:error_max_turns — but it may already have
+            // emitted a complete spec. Salvage that usable output instead of failing
+            // the whole request on an exit code.
+            const resultSubtype = lastResultEvent?.subtype ?? null;
+            const hasUsableSpec = buffer.trim().length > 0 && /##\s*Spec Title/i.test(buffer);
+            const salvageMaxTurns = code !== 0 && resultSubtype === 'error_max_turns' && hasUsableSpec;
+            if ((code === 0 && buffer.trim()) || salvageMaxTurns) {
+                if (salvageMaxTurns) {
+                    console.warn(`[project-router] spec-gen salvaged partial output after error_max_turns (${requestId}); ` +
+                        `consider raising --max-turns if this recurs`);
+                }
+                // Extract title from generated spec
+                const titleMatch = buffer.match(/##\s*Spec Title\s*\n+(.+)/);
+                const specTitle = titleMatch ? titleMatch[1].trim() : idea.trim().slice(0, 80);
+                // Extract complexity for priority mapping
+                const complexityMatch = buffer.match(/##\s*Estimated Complexity\s*\n+(\w+)/);
+                const complexity = complexityMatch ? complexityMatch[1].toLowerCase() : 'medium';
+                const priority = complexity === 'low' ? 'low' : complexity === 'high' || complexity === 'very' ? 'high' : 'medium';
+                // Extract labels from the `## Labels` section. Comma- or
+                // newline-separated tags, normalised to lowercase kebab-case.
+                // `spec-proposal` is always retained as the marker label.
+                const labelsMatch = buffer.match(/##\s*Labels\s*\n+([^\n]+(?:\n(?!##)[^\n]+)*)/);
+                const claudeLabels = labelsMatch
+                    ? labelsMatch[1]
+                        .replace(/[\[\]]/g, '')
+                        .split(/[,\n]/)
+                        .map((s) => s.trim().toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, ''))
+                        .filter((s) => s.length > 0 && s.length <= 32)
+                        .slice(0, 6)
+                    : [];
+                const finalLabels = Array.from(new Set(['spec-proposal', ...claudeLabels]));
+                const shortSummary = (0, ticket_store_1.clampShortSummary)((0, project_router_helpers_1.extractShortSummary)(buffer));
+                const description = (0, project_router_helpers_1.stripSpecMetadataSections)(buffer);
+                // Create ticket directly
+                try {
+                    const now = new Date().toISOString();
+                    let created;
+                    const store = (0, ticket_store_1.mutateStore)(filePath, (s) => {
+                        const id = s.next_id++;
+                        const ticket = {
+                            id,
+                            title: specTitle,
+                            description,
+                            status: 'todo',
+                            priority: priority,
+                            labels: finalLabels,
+                            assignee: null,
+                            prerequisites: [],
+                            metadata: {},
+                            comments: [],
+                            origin_conversation_id: null,
+                            is_epic: false,
+                            parent_epic_id: null,
+                            execution_order: null,
+                            short_summary: shortSummary,
+                            created_at: now,
+                            updated_at: now,
+                            created_by: 'sr-product-engineer',
+                            source: 'propose-spec',
+                        };
+                        s.tickets[String(id)] = ticket;
+                        created = ticket;
+                    });
+                    ticketWatcher.notifyDesktopWrite(store.revision);
+                    if (created)
+                        createdTicketId = created.id;
+                    // Migrate attachments from pendingSpecId → real ticket id (if any were uploaded).
+                    // Must complete BEFORE broadcasting ticket_created so WS listeners see the populated attachments[].
+                    if (pendingSpecId && created) {
+                        try {
+                            const migrated = await attachment_manager_1.attachmentManager.renameTicketDir({
+                                slug: project.slug,
+                                pendingId: pendingSpecId,
+                                realTicketId: created.id,
+                                projectPath: project.path,
+                            });
+                            if (migrated.length > 0) {
+                                created.attachments = migrated;
+                            }
+                        }
+                        catch (err) {
+                            console.error('[project-router] generate-spec attachment migration error:', err);
+                        }
+                    }
+                    const ticketMsg = {
+                        type: 'ticket_created', ticket: created,
+                        projectId, timestamp: new Date().toISOString(),
+                    };
+                    broadcast(ticketMsg);
+                    const doneMsg = {
+                        type: 'spec_gen_done', projectId, requestId,
+                        ticket: created, timestamp: new Date().toISOString(),
+                    };
+                    broadcast(doneMsg);
+                    // Add Spec → Jira: promote the new ticket to a Jira issue when the
+                    // project is Jira-backed (unless the user opted to keep it local).
+                    void maybePromoteSpecToJira(ctx(req), created.id, req.body?.createLocal === true, broadcast);
+                    // Quick mode Contract Refine: when toggle is on in the request body
+                    // AND the project setting + kill switch permit it, fire the no-resume
+                    // Quick refine path asynchronously. Claude-only today — codex
+                    // contract refine isn't wired (the spawn hardcodes the `claude`
+                    // binary). Skip silently on codex projects so the ticket lands
+                    // without the misleading "Contract layer skipped — model_error"
+                    // toast that the refine kill-switch would otherwise emit.
+                    if (quickContractRefine && created && provider === 'claude') {
+                        const refineTicketId = created.id;
+                        const refineTitle = created.title;
+                        const refineDescription = created.description;
+                        const refineModel = req.body?.model ?? null;
+                        process.nextTick(() => {
+                            void (0, contract_refine_runner_1.runContractRefineForQuick)({
+                                db: ctx(req).db,
+                                projectId: project.id,
+                                projectSlug: project.slug,
+                                projectPath: project.path,
+                                projectName: project.name,
+                                broadcast: broadcast,
+                            }, refineTicketId, refineTitle, refineDescription, refineModel).catch((err) => {
+                                console.error('[project-router] runContractRefineForQuick error:', err);
+                            });
+                        });
+                    }
+                    else if (quickContractRefine && created && provider === 'codex') {
+                        console.log(`[project-router] quick contract refine skipped for codex project (ticket #${created.id}); ` +
+                            `feature is claude-only today`);
+                    }
+                }
+                catch (err) {
+                    console.error('[project-router] generate-spec ticket creation error:', err);
+                    const errMsg = {
+                        type: 'spec_gen_error', projectId, requestId,
+                        error: 'Failed to create ticket', timestamp: new Date().toISOString(),
+                    };
+                    broadcast(errMsg);
+                }
+            }
+            else {
+                const reason = code === 0
+                    ? 'Empty response from AI'
+                    : resultSubtype === 'error_max_turns'
+                        ? 'AI hit its turn limit before finishing the spec. Try again, or narrow the idea / turn off full-codebase context.'
+                        : `Process exited with code ${code}`;
+                console.error(`[project-router] spec-gen failed (${requestId}): ${reason}` +
+                    (stderrBuf.trim() ? `\n  stderr: ${stderrBuf.trim()}` : '') +
+                    (buffer.trim() ? `\n  stdout-buffer: ${buffer.trim().slice(0, 500)}` : ''));
+                const msg = {
+                    type: 'spec_gen_error', projectId, requestId,
+                    error: reason,
+                    timestamp: new Date().toISOString(),
+                };
+                broadcast(msg);
+            }
+            // ai_invocations capture (surface='quick-spec'). Always emit a row, success or fail.
+            try {
+                // Adapter-driven finalisation: claude passes its native total_cost_usd
+                // through untouched; codex (nativeCostUsd:false) gets a pricing-table
+                // estimate from its captured token usage + estimated=true. This
+                // replaces the legacy normaliseResultEvent path that hardcoded codex
+                // cost to $0 and never set the estimated flag.
+                const { result: normalised, estimated } = (0, result_event_1.finaliseInvocationResult)(adapter, adapterEvents, { fallbackModel: resolvedModel });
+                // extractCodexResult does not surface duration (codex stream carries
+                // none); stamp wall-clock so the row's duration isn't lost. Claude's
+                // result event already provides duration_ms, so prefer it.
+                const wallMs = Date.now() - new Date(turnStartedAt).getTime();
+                (0, ai_invocations_1.recordInvocation)(ctx(req).db, {
+                    id: (0, crypto_1.randomUUID)(),
+                    project_id: projectId,
+                    provider: adapter.id,
+                    surface: 'quick-spec',
+                    surface_ref_id: requestId,
+                    ticket_id: createdTicketId,
+                    status: code === 0 && buffer.trim() ? 'success' : 'failed',
+                    started_at: turnStartedAt,
+                    finished_at: new Date().toISOString(),
+                    total_cost_usd_estimated: estimated,
+                    ...normalised,
+                    duration_ms: normalised.duration_ms ?? wallMs,
+                });
+                broadcast({ type: 'spending.invalidated', projectId });
+            }
+            catch (err) {
+                console.error('[project-router] generate-spec recordInvocation failed:', err);
+            }
+        });
+    });
+    // POST /:projectId/tickets/save-as-draft — Persist an in-progress Explore session as a draft ticket
+    router.post('/:projectId/tickets/save-as-draft', (req, res) => {
+        const body = req.body ?? {};
+        const conversationId = typeof body.conversationId === 'string' ? body.conversationId.trim() : '';
+        if (!conversationId) {
+            res.status(400).json({ error: 'conversationId is required' });
+            return;
+        }
+        const providedTitle = typeof body.title === 'string' ? body.title.trim() : '';
+        const labels = Array.isArray(body.labels)
+            ? body.labels.filter((l) => typeof l === 'string')
+            : [];
+        const description = typeof body.description === 'string' ? body.description : '';
+        // Optional editTicketId — when present, demote that specific ticket in
+        // place instead of looking up by conversationId. Drives the
+        // Continue-Editing-on-non-draft flow.
+        let editTicketId;
+        if (body.editTicketId !== undefined && body.editTicketId !== null) {
+            if (typeof body.editTicketId !== 'number' || !Number.isFinite(body.editTicketId)) {
+                res.status(400).json({ error: 'editTicketId must be a number' });
+                return;
+            }
+            editTicketId = body.editTicketId;
+        }
+        try {
+            const { db, project, broadcast, ticketWatcher } = ctx(req);
+            // Require at least one user-submitted turn before accepting a save
+            const messages = (0, db_1.getMessages)(db, conversationId);
+            const hasUserTurn = messages.some((m) => m.role === 'user' && (m.content ?? '').trim().length > 0);
+            if (!hasUserTurn) {
+                res.status(400).json({ error: 'conversation has no user-submitted turn yet' });
+                return;
+            }
+            const filePath = ticketPath(req);
+            const now = new Date().toISOString();
+            let saved;
+            let flippedInPlace = false;
+            let notFound = false;
+            const store = (0, ticket_store_1.mutateStore)(filePath, (s) => {
+                if (editTicketId !== undefined) {
+                    const target = s.tickets[String(editTicketId)];
+                    if (!target) {
+                        notFound = true;
+                        return;
+                    }
+                    const title = providedTitle || target.title || (0, explore_draft_title_1.generateAutoTitle)(messages.map((m) => ({ role: m.role, content: m.content ?? '' })));
+                    target.title = title;
+                    if (description)
+                        target.description = description;
+                    if (labels.length > 0)
+                        target.labels = labels;
+                    target.status = 'draft';
+                    target.priority = null;
+                    target.origin_conversation_id = conversationId;
+                    target.updated_at = now;
+                    saved = target;
+                    flippedInPlace = true;
+                    return;
+                }
+                // Idempotent on conversationId: if a draft ticket already references this
+                // conversation, update in place rather than create a second one.
+                const existing = Object.values(s.tickets).find((t) => t.origin_conversation_id === conversationId && t.status === 'draft');
+                const title = providedTitle || existing?.title || (0, explore_draft_title_1.generateAutoTitle)(messages.map((m) => ({ role: m.role, content: m.content ?? '' })));
+                if (existing) {
+                    existing.title = title;
+                    if (description)
+                        existing.description = description;
+                    if (labels.length > 0)
+                        existing.labels = labels;
+                    existing.updated_at = now;
+                    saved = existing;
+                    return;
+                }
+                const id = s.next_id++;
+                const ticket = {
+                    id,
+                    title,
+                    description,
+                    status: 'draft',
+                    priority: null,
+                    labels,
+                    assignee: null,
+                    prerequisites: [],
+                    metadata: {},
+                    comments: [],
+                    origin_conversation_id: conversationId,
+                    is_epic: false,
+                    parent_epic_id: null,
+                    execution_order: null,
+                    short_summary: null,
+                    created_at: now,
+                    updated_at: now,
+                    created_by: 'sr-explore-spec',
+                    source: 'explore-draft',
+                };
+                s.tickets[String(id)] = ticket;
+                saved = ticket;
+            });
+            if (notFound) {
+                res.status(404).json({ error: 'ticket not found' });
+                return;
+            }
+            ticketWatcher.notifyDesktopWrite(store.revision);
+            if (flippedInPlace) {
+                const msg = {
+                    type: 'ticket_updated',
+                    ticket: saved,
+                    projectId: project.id,
+                    timestamp: now,
+                };
+                broadcast(msg);
+                res.status(200).json({ ticket: saved, revision: store.revision });
+                return;
+            }
+            const msg = saved.created_at === saved.updated_at
+                ? { type: 'ticket_created', ticket: saved, projectId: project.id, timestamp: now }
+                : { type: 'ticket_updated', ticket: saved, projectId: project.id, timestamp: now };
+            broadcast(msg);
+            res.status(201).json({ ticket: saved, revision: store.revision });
+        }
+        catch (err) {
+            console.error('[project-router] save-as-draft error:', err);
+            res.status(500).json({ error: 'Failed to save draft' });
+        }
+    });
+    // POST /:projectId/tickets/from-draft — Commit an Explore Spec draft as a real ticket
+    // Two paths:
+    //   (1) Legacy: payload has no `draftTicketId` → create a brand-new ticket (status='todo').
+    //   (2) Flip in place: payload has `draftTicketId` referencing an existing
+    //       status='draft' ticket → update that ticket in place to status='todo',
+    //       set priority, replace title/description, preserve origin_conversation_id.
+    router.post('/:projectId/tickets/from-draft', async (req, res) => {
+        const body = req.body ?? {};
+        const rawTitle = typeof body.title === 'string' ? body.title.trim() : '';
+        if (!rawTitle) {
+            res.status(400).json({ error: 'title is required' });
+            return;
+        }
+        const draftTicketId = typeof body.draftTicketId === 'number' ? body.draftTicketId : null;
+        const pendingSpecId = typeof body.pendingSpecId === 'string' ? body.pendingSpecId : null;
+        const conversationId = typeof body.conversationId === 'string' ? body.conversationId : null;
+        const baseDescription = typeof body.description === 'string' ? body.description.trim() : '';
+        const labels = Array.isArray(body.labels)
+            ? body.labels.filter((l) => typeof l === 'string')
+            : [];
+        const acceptanceCriteria = Array.isArray(body.acceptanceCriteria)
+            ? body.acceptanceCriteria
+                .filter((c) => typeof c === 'string')
+                .map((c) => c.trim())
+                .filter((c) => c.length > 0)
+            : [];
+        const priority = (0, ticket_store_1.isValidPriority)(body.priority) ? body.priority : 'medium';
+        // 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
+        // Claude (Problem Statement / Proposed Solution / Out of Scope /
+        // Technical Considerations / Estimated Complexity) followed by the
+        // Acceptance Criteria bullets.
+        const description = (0, project_router_helpers_1.formatDescriptionWithCriteria)(baseDescription, acceptanceCriteria);
+        // Short summary: explicit body field wins; otherwise try extracting a
+        // `## Short Summary` section from the description and stripping it.
+        let bodyShortSummary = null;
+        let descriptionForStore = description;
+        if (typeof body.shortSummary === 'string') {
+            bodyShortSummary = (0, ticket_store_1.clampShortSummary)(body.shortSummary);
+        }
+        else {
+            const extracted = (0, project_router_helpers_1.extractShortSummary)(description);
+            if (extracted !== null) {
+                bodyShortSummary = (0, ticket_store_1.clampShortSummary)(extracted);
+                descriptionForStore = description
+                    .replace(/##\s*Short Summary\s*\n+(?:[^\n]+(?:\n(?!##)[^\n]+)*)\n*/i, '')
+                    .trim();
+            }
+        }
+        if (bodyShortSummary === null) {
+            bodyShortSummary = (0, project_router_helpers_1.deriveFallbackShortSummary)(rawTitle, descriptionForStore);
+        }
+        try {
+            const filePath = ticketPath(req);
+            const now = new Date().toISOString();
+            let created;
+            let wasFlip = false;
+            let explicitDraftMissing = false;
+            const store = (0, ticket_store_1.mutateStore)(filePath, (s) => {
+                // Resolve flip target: explicit `draftTicketId` wins; otherwise look up
+                // an existing draft ticket whose origin_conversation_id matches the
+                // current conversation so a resumed session commits in place even when
+                // the client doesn't track the draft id explicitly.
+                let flipTarget;
+                if (draftTicketId !== null) {
+                    flipTarget = s.tickets[String(draftTicketId)];
+                    if (!flipTarget || flipTarget.status !== 'draft') {
+                        explicitDraftMissing = true;
+                        return;
+                    }
+                }
+                else if (conversationId) {
+                    flipTarget = Object.values(s.tickets).find((t) => t.origin_conversation_id === conversationId && t.status === 'draft');
+                }
+                if (flipTarget) {
+                    flipTarget.status = 'todo';
+                    flipTarget.priority = priority;
+                    flipTarget.title = rawTitle;
+                    flipTarget.description = descriptionForStore;
+                    if (labels.length > 0)
+                        flipTarget.labels = labels;
+                    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.
+                    if (bodyShortSummary !== null) {
+                        flipTarget.short_summary = bodyShortSummary;
+                    }
+                    // origin_conversation_id is intentionally preserved
+                    created = flipTarget;
+                    wasFlip = true;
+                    return;
+                }
+                // B62: from-draft is idempotent only while the ticket is still a draft.
+                // After a successful commit the draft is 'todo', so the draft lookup above
+                // no longer matches and a second from-draft for the same conversation
+                // would insert a DUPLICATE ticket. If a (now non-draft) ticket already
+                // originates from this conversation, return it instead of re-inserting.
+                if (conversationId) {
+                    const alreadyCommitted = Object.values(s.tickets).find((t) => t.origin_conversation_id === conversationId);
+                    if (alreadyCommitted) {
+                        created = alreadyCommitted;
+                        wasFlip = true; // treat as in-place: broadcast ticket_updated, not created
+                        return;
+                    }
+                }
+                // Legacy: insert new ticket
+                const id = s.next_id++;
+                const ticket = {
+                    id,
+                    title: rawTitle,
+                    description: descriptionForStore,
+                    status: 'todo',
+                    priority,
+                    labels,
+                    assignee: null,
+                    prerequisites: [],
+                    metadata: {},
+                    comments: [],
+                    origin_conversation_id: conversationId,
+                    is_epic: false,
+                    parent_epic_id: null,
+                    execution_order: null,
+                    short_summary: bodyShortSummary,
+                    created_at: now,
+                    updated_at: now,
+                    created_by: 'sr-explore-spec',
+                    source: 'propose-spec',
+                };
+                s.tickets[String(id)] = ticket;
+                created = ticket;
+            });
+            if (explicitDraftMissing) {
+                res.status(404).json({ error: 'Draft ticket not found or not in draft status' });
+                return;
+            }
+            const { broadcast, ticketWatcher, project } = ctx(req);
+            ticketWatcher.notifyDesktopWrite(store.revision);
+            // Migrate attachments from pendingSpecId → real ticket id (mirrors the
+            // generate-spec flow). Must complete before broadcasting ticket_created
+            // so listeners see the populated attachments[].
+            if (pendingSpecId && created) {
+                try {
+                    const migrated = await attachment_manager_1.attachmentManager.renameTicketDir({
+                        slug: project.slug,
+                        pendingId: pendingSpecId,
+                        realTicketId: created.id,
+                        projectPath: project.path,
+                    });
+                    if (migrated.length > 0) {
+                        created.attachments = migrated;
+                    }
+                }
+                catch (err) {
+                    console.error('[project-router] from-draft attachment migration error:', err);
+                }
+            }
+            const msg = wasFlip
+                ? {
+                    type: 'ticket_updated',
+                    ticket: created,
+                    projectId: project.id,
+                    timestamp: new Date().toISOString(),
+                }
+                : {
+                    type: 'ticket_created',
+                    ticket: created,
+                    projectId: project.id,
+                    timestamp: new Date().toISOString(),
+                };
+            broadcast(msg);
+            // Back-fill ticket_id on the conversation's prior ai_invocations rows.
+            if (conversationId && created) {
+                try {
+                    const changes = (0, ai_invocations_1.updateTicketIdForConversation)(ctx(req).db, conversationId, created.id);
+                    if (changes > 0) {
+                        broadcast({ type: 'spending.invalidated', projectId: project.id });
+                    }
+                }
+                catch (err) {
+                    console.error('[project-router] from-draft ai_invocations back-fill failed:', err);
+                }
+            }
+            res.status(201).json({ ticket: created, revision: store.revision });
+            // Add Spec (Explore) → Jira: promote the committed ticket to a Jira issue
+            // when the project is Jira-backed (unless the user opted to keep it local).
+            void maybePromoteSpecToJira(ctx(req), created.id, body.createLocal === true, broadcast);
+            // Fire Contract Refine post-commit (fire-and-forget). Toggle + kill-switch
+            // are checked inside runContractRefine. Claude-only today — codex
+            // contract refine isn't wired (the spawn hardcodes the `claude`
+            // binary). Skip silently on codex projects.
+            if (conversationId && created && project.provider === 'claude') {
+                const createdTicketId = created.id;
+                const convoId = conversationId;
+                console.log(`[project-router] from-draft hook: scheduling refine ticket=${createdTicketId} conv=${convoId}`);
+                process.nextTick(() => {
+                    void (0, contract_refine_runner_1.runContractRefine)({
+                        db: ctx(req).db,
+                        projectId: project.id,
+                        projectSlug: project.slug,
+                        projectPath: project.path,
+                        projectName: project.name,
+                        broadcast: broadcast,
+                    }, convoId, createdTicketId).catch((err) => {
+                        console.error('[project-router] runContractRefine error:', err);
+                    });
+                });
+            }
+            else if (conversationId && created && project.provider === 'codex') {
+                console.log(`[project-router] from-draft contract refine skipped for codex project (ticket #${created.id})`);
+            }
+        }
+        catch (err) {
+            console.error('[project-router] from-draft create error:', err);
+            res.status(500).json({ error: 'Failed to create ticket' });
+        }
+    });
+    // POST /:projectId/tickets/from-prompt — Create a spec directly from a
+    // free-form prompt (the "Raw" Add-Spec mode). NO AI is invoked: the user's
+    // text becomes the ticket description verbatim. The ticket lands as
+    // status='todo' (ready for rails) with source='free-prompt'. There is no
+    // ai_invocations row (nothing was billed) and no contract-refine (no origin
+    // conversation, no description format to refine).
+    router.post('/:projectId/tickets/from-prompt', async (req, res) => {
+        const body = req.body ?? {};
+        const rawDescription = typeof body.description === 'string' ? body.description.trim() : '';
+        if (!rawDescription) {
+            res.status(400).json({ error: 'description is required' });
+            return;
+        }
+        // Optional light-structuring (v1: the client always sends `false`; the flag
+        // keeps the contract stable for a future non-generative structuring pass).
+        const structured = body.structured === true;
+        const description = structured ? (0, project_router_helpers_1.lightlyStructurePrompt)(rawDescription) : rawDescription;
+        // Title: explicit value wins; otherwise derive a single-line summary from
+        // the body (reusing the deterministic Explore-draft summarizer).
+        const providedTitle = typeof body.title === 'string' ? body.title.trim() : '';
+        const title = providedTitle || (0, explore_draft_title_1.generateAutoTitle)([{ role: 'user', content: rawDescription }]);
+        const labels = Array.isArray(body.labels)
+            ? body.labels.filter((l) => typeof l === 'string')
+            : [];
+        // Priority: validate against the allowed set; default 'medium'. A
+        // status='todo' ticket MUST carry a non-null priority (see
+        // validatePriorityForStatus), so we never accept null here.
+        const priority = (0, ticket_store_1.isValidPriority)(body.priority) ? body.priority : 'medium';
+        const validationError = (0, ticket_store_1.validatePriorityForStatus)('todo', priority);
+        if (validationError) {
+            res.status(400).json({ error: validationError });
+            return;
+        }
+        const pendingSpecId = typeof body.pendingSpecId === 'string' ? body.pendingSpecId : null;
+        const shortSummary = (0, project_router_helpers_1.deriveFallbackShortSummary)(title, description);
+        try {
+            const filePath = ticketPath(req);
+            const now = new Date().toISOString();
+            let created;
+            const store = (0, ticket_store_1.mutateStore)(filePath, (s) => {
+                const id = s.next_id++;
+                const ticket = {
+                    id,
+                    title,
+                    description,
+                    status: 'todo',
+                    priority,
+                    labels,
+                    assignee: null,
+                    prerequisites: [],
+                    metadata: {},
+                    comments: [],
+                    origin_conversation_id: null,
+                    is_epic: false,
+                    parent_epic_id: null,
+                    execution_order: null,
+                    short_summary: shortSummary,
+                    created_at: now,
+                    updated_at: now,
+                    created_by: 'hub', // legacy on-disk wire value (tickets.json, shared with specrails-core) — do not rename
+                    source: 'free-prompt',
+                };
+                s.tickets[String(id)] = ticket;
+                created = ticket;
+            });
+            const { broadcast, ticketWatcher, project } = ctx(req);
+            ticketWatcher.notifyDesktopWrite(store.revision);
+            // Migrate attachments from pendingSpecId → real ticket id (mirrors the
+            // generate-spec / from-draft flow). Must complete before broadcasting so
+            // listeners see the populated attachments[].
+            if (pendingSpecId && created) {
+                try {
+                    const migrated = await attachment_manager_1.attachmentManager.renameTicketDir({
+                        slug: project.slug,
+                        pendingId: pendingSpecId,
+                        realTicketId: created.id,
+                        projectPath: project.path,
+                    });
+                    if (migrated.length > 0) {
+                        created.attachments = migrated;
+                    }
+                }
+                catch (err) {
+                    console.error('[project-router] from-prompt attachment migration error:', err);
+                }
+            }
+            const msg = {
+                type: 'ticket_created',
+                ticket: created,
+                projectId: project.id,
+                timestamp: new Date().toISOString(),
+            };
+            broadcast(msg);
+            res.status(201).json({ ticket: created, revision: store.revision });
+        }
+        catch (err) {
+            console.error('[project-router] from-prompt create error:', err);
+            res.status(500).json({ error: 'Failed to create ticket' });
+        }
+    });
+    // POST /:projectId/tickets/:id/contract-refine — Manually re-fire refine
+    router.post('/:projectId/tickets/:id/contract-refine', async (req, res) => {
+        const ticketId = Number.parseInt(String(req.params.id ?? ''), 10);
+        if (!Number.isFinite(ticketId)) {
+            res.status(400).json({ error: 'invalid ticket id' });
+            return;
+        }
+        const { project, db, broadcast } = ctx(req);
+        if ((0, explore_contract_refine_1.isExploreContractRefineKillSwitchActive)()) {
+            res.status(409).json({ error: 'feature_disabled_by_env' });
+            return;
+        }
+        if (project.provider === 'codex') {
+            res.status(409).json({ error: 'contract_refine_unsupported_for_codex' });
+            return;
+        }
+        // Validate the ticket exists.
+        try {
+            const filePath = ticketPath(req);
+            const { withLock } = await Promise.resolve().then(() => __importStar(require('./ticket-store')));
+            const ticket = withLock(filePath, (s) => s.tickets[String(ticketId)]);
+            if (!ticket) {
+                res.status(404).json({ error: 'ticket not found' });
+                return;
+            }
+            if (!ticket.origin_conversation_id) {
+                res.status(409).json({ error: 'ticket has no origin conversation' });
+                return;
+            }
+            const convoId = ticket.origin_conversation_id;
+            res.status(202).json({ scheduled: true });
+            process.nextTick(() => {
+                void (0, contract_refine_runner_1.runContractRefine)({
+                    db,
+                    projectId: project.id,
+                    projectSlug: project.slug,
+                    projectPath: project.path,
+                    projectName: project.name,
+                    broadcast: broadcast,
+                    ignoreConversationScope: true,
+                }, convoId, ticketId).catch((err) => {
+                    console.error('[project-router] retry runContractRefine error:', err);
+                });
+            });
+        }
+        catch (err) {
+            console.error('[project-router] retry endpoint error:', err);
+            res.status(500).json({ error: 'Failed to schedule retry' });
+        }
+    });
+    // POST /:projectId/tickets/:id/smash — Decompose ticket into N children
+    router.post('/:projectId/tickets/:id/smash', async (req, res) => {
+        const ticketId = Number.parseInt(String(req.params.id ?? ''), 10);
+        if (!Number.isFinite(ticketId)) {
+            res.status(400).json({ error: 'invalid ticket id' });
+            return;
+        }
+        if ((0, explore_smash_1.isSpecsSmashKillSwitchActive)()) {
+            res.status(409).json({ error: 'feature_disabled_by_env', reason: 'disabled' });
+            return;
+        }
+        const { project, db, broadcast } = ctx(req);
+        try {
+            const filePath = ticketPath(req);
+            const { readStore } = await Promise.resolve().then(() => __importStar(require('./ticket-store')));
+            const store = readStore(filePath);
+            const gate = (0, smash_runner_1.checkSmashEligibility)(store, ticketId);
+            if (!gate.ok) {
+                const statusCode = gate.reason === 'ticket-not-found' ? 404 : 409;
+                res.status(statusCode).json({ error: 'ineligible', reason: gate.reason });
+                return;
+            }
+            const rawMode = typeof req.body?.mode === 'string' ? req.body.mode : 'simple';
+            const mode = rawMode === 'full' ? 'full' : 'simple';
+            const model = typeof req.body?.model === 'string' && req.body.model.length > 0 ? req.body.model : null;
+            res.status(202).json({ scheduled: true, mode });
+            process.nextTick(() => {
+                void (0, smash_runner_1.runSmash)({
+                    db,
+                    projectId: project.id,
+                    projectSlug: project.slug,
+                    projectPath: project.path,
+                    projectName: project.name,
+                    broadcast: broadcast,
+                    mode,
+                    model,
+                }, ticketId).catch((err) => {
+                    console.error('[project-router] runSmash error:', err);
+                });
+            });
+        }
+        catch (err) {
+            console.error('[project-router] smash endpoint error:', err);
+            res.status(500).json({ error: 'Failed to schedule SMASH' });
+        }
+    });
+    // POST /:projectId/tickets/:id/smash/undo — Reverse a prior SMASH
+    router.post('/:projectId/tickets/:id/smash/undo', async (req, res) => {
+        const ticketId = Number.parseInt(String(req.params.id ?? ''), 10);
+        if (!Number.isFinite(ticketId)) {
+            res.status(400).json({ error: 'invalid ticket id' });
+            return;
+        }
+        if ((0, explore_smash_1.isSpecsSmashKillSwitchActive)()) {
+            res.status(409).json({ error: 'feature_disabled_by_env', reason: 'disabled' });
+            return;
+        }
+        const smashedAt = typeof req.body?.smashedAt === 'string' ? req.body.smashedAt : null;
+        if (!smashedAt) {
+            res.status(400).json({ error: 'smashedAt timestamp required' });
+            return;
+        }
+        const { project, db, broadcast } = ctx(req);
+        try {
+            const result = await (0, smash_runner_1.runSmashUndo)({
+                db,
+                projectId: project.id,
+                projectSlug: project.slug,
+                projectPath: project.path,
+                projectName: project.name,
+                broadcast: broadcast,
+            }, ticketId, smashedAt);
+            if (!result.ok) {
+                const statusCode = result.reason === 'ticket-not-found' ? 404 : 409;
+                res.status(statusCode).json({ error: 'undo_failed', reason: result.reason });
+                return;
+            }
+            res.json({ ok: true, deletedChildren: result.deletedChildren });
+        }
+        catch (err) {
+            console.error('[project-router] smash/undo endpoint error:', err);
+            res.status(500).json({ error: 'Failed to undo SMASH' });
+        }
+    });
+    // DELETE /:projectId/tickets/:id/children — Delete all children of an épica
+    router.delete('/:projectId/tickets/:id/children', (req, res) => {
+        const ticketId = Number.parseInt(String(req.params.id ?? ''), 10);
+        if (!Number.isFinite(ticketId)) {
+            res.status(400).json({ error: 'invalid ticket id' });
+            return;
+        }
+        if ((0, explore_smash_1.isSpecsSmashKillSwitchActive)()) {
+            res.status(409).json({ error: 'feature_disabled_by_env', reason: 'disabled' });
+            return;
+        }
+        const { project, broadcast, ticketWatcher } = ctx(req);
+        try {
+            const filePath = ticketPath(req);
+            const result = (0, smash_runner_1.applyDeleteEpicChildren)(filePath, ticketId);
+            // Pass the real post-write revision (not 0) so the chokidar echo is
+            // suppressed; a hardcoded 0 never matches the on-disk revision and
+            // triggers a spurious full-refresh broadcast to every client.
+            ticketWatcher.notifyDesktopWrite(result.revision);
+            const now = new Date().toISOString();
+            for (const id of result.deletedChildren) {
+                broadcast({
+                    type: 'ticket_deleted',
+                    ticketId: id,
+                    projectId: project.id,
+                    timestamp: now,
+                });
+            }
+            res.json({ ok: true, deletedChildren: result.deletedChildren });
+        }
+        catch (err) {
+            console.error('[project-router] delete-children error:', err);
+            res.status(500).json({ error: 'Failed to delete children' });
+        }
+    });
+    // POST /:projectId/tickets — Create new ticket
+    router.post('/:projectId/tickets', (req, res) => {
+        const { title, description, status, priority, labels, assignee, prerequisites, metadata, source } = req.body ?? {};
+        if (!title || typeof title !== 'string' || !title.trim()) {
+            res.status(400).json({ error: 'title is required' });
+            return;
+        }
+        if (status !== undefined && !(0, ticket_store_1.isValidStatus)(status)) {
+            res.status(400).json({ error: 'status must be one of: draft, todo, in_progress, done, cancelled' });
+            return;
+        }
+        const finalStatus = (status ?? 'todo');
+        const finalPriority = priority === undefined ? (finalStatus === 'draft' ? null : 'medium') : (priority === null ? null : priority);
+        const priorityError = (0, ticket_store_1.validatePriorityForStatus)(finalStatus, finalPriority);
+        if (priorityError) {
+            res.status(400).json({ error: priorityError });
+            return;
+        }
+        try {
+            const filePath = ticketPath(req);
+            const now = new Date().toISOString();
+            let created;
+            const store = (0, ticket_store_1.mutateStore)(filePath, (s) => {
+                const id = s.next_id++;
+                const ticket = {
+                    id,
+                    title: title.trim(),
+                    description: typeof description === 'string' ? description : '',
+                    status: finalStatus,
+                    priority: finalPriority,
+                    labels: Array.isArray(labels) ? labels.filter((l) => typeof l === 'string') : [],
+                    assignee: typeof assignee === 'string' ? assignee : null,
+                    prerequisites: Array.isArray(prerequisites) ? prerequisites.filter((p) => typeof p === 'number') : [],
+                    metadata: typeof metadata === 'object' && metadata !== null ? metadata : {},
+                    comments: [],
+                    origin_conversation_id: null,
+                    is_epic: false,
+                    parent_epic_id: null,
+                    execution_order: null,
+                    short_summary: null,
+                    created_at: now,
+                    updated_at: now,
+                    created_by: 'hub', // legacy on-disk wire value (tickets.json, shared with specrails-core) — do not rename
+                    source: source === 'product-backlog' || source === 'propose-spec' || source === 'manual' ? source : 'hub', // legacy on-disk wire value — do not rename
+                };
+                s.tickets[String(id)] = ticket;
+                created = ticket;
+            });
+            const { broadcast, ticketWatcher } = ctx(req);
+            ticketWatcher.notifyDesktopWrite(store.revision);
+            const msg = { type: 'ticket_created', ticket: created, projectId: ctx(req).project.id, timestamp: new Date().toISOString() };
+            broadcast(msg);
+            res.status(201).json({ ticket: created, revision: store.revision });
+        }
+        catch (err) {
+            console.error('[project-router] ticket create error:', err);
+            res.status(500).json({ error: 'Failed to create ticket' });
+        }
+    });
+    // PATCH /:projectId/tickets/:id — Update ticket fields
+    router.patch('/:projectId/tickets/:id', (req, res) => {
+        const ticketId = req.params.id;
+        if (!/^\d+$/.test(ticketId)) {
+            res.status(400).json({ error: 'Invalid ticket ID' });
+            return;
+        }
+        const { title, description, status, priority, labels, assignee, prerequisites, metadata, acceptanceCriteria, short_summary } = req.body ?? {};
+        if (status !== undefined && !(0, ticket_store_1.isValidStatus)(status)) {
+            res.status(400).json({ error: 'status must be one of: draft, todo, in_progress, done, cancelled' });
+            return;
+        }
+        if (priority !== undefined && priority !== null && !(0, ticket_store_1.isValidPriority)(priority)) {
+            res.status(400).json({ error: 'priority must be one of: critical, high, medium, low' });
+            return;
+        }
+        if (title !== undefined && (typeof title !== 'string' || !title.trim())) {
+            res.status(400).json({ error: 'title cannot be empty' });
+            return;
+        }
+        if (acceptanceCriteria !== undefined) {
+            if (!Array.isArray(acceptanceCriteria) || !acceptanceCriteria.every((c) => typeof c === 'string')) {
+                res.status(400).json({ error: 'acceptanceCriteria must be an array of strings' });
+                return;
+            }
+        }
+        try {
+            const filePath = ticketPath(req);
+            let updated;
+            let validationError = null;
+            const store = (0, ticket_store_1.mutateStore)(filePath, (s) => {
+                const ticket = s.tickets[ticketId];
+                if (!ticket)
+                    return;
+                const nextStatus = (status ?? ticket.status);
+                const nextPriority = priority === undefined ? ticket.priority : (priority === null ? null : priority);
+                const err = (0, ticket_store_1.validatePriorityForStatus)(nextStatus, nextPriority);
+                if (err) {
+                    validationError = err;
+                    return;
+                }
+                if (title !== undefined)
+                    ticket.title = title.trim();
+                if (description !== undefined)
+                    ticket.description = description;
+                if (acceptanceCriteria !== undefined) {
+                    // Fold criteria into the description body under a `## Acceptance Criteria`
+                    // section, replacing any existing one. Use the just-set description if
+                    // present, otherwise the ticket's current description.
+                    ticket.description = (0, project_router_helpers_1.formatDescriptionWithCriteria)(ticket.description ?? '', acceptanceCriteria);
+                }
+                if (status !== undefined)
+                    ticket.status = status;
+                if (priority !== undefined)
+                    ticket.priority = nextPriority;
+                if (labels !== undefined && Array.isArray(labels))
+                    ticket.labels = labels.filter((l) => typeof l === 'string');
+                if (assignee !== undefined)
+                    ticket.assignee = typeof assignee === 'string' ? assignee : null;
+                if (prerequisites !== undefined && Array.isArray(prerequisites))
+                    ticket.prerequisites = prerequisites.filter((p) => typeof p === 'number');
+                if (metadata !== undefined && typeof metadata === 'object' && metadata !== null) {
+                    ticket.metadata = { ...ticket.metadata, ...metadata };
+                }
+                // Short summary: explicit non-empty overwrites; explicit null clears;
+                // omitted leaves the existing value untouched (preserves prior summary
+                // when AI Refine omits it for a partial edit).
+                if (short_summary === null) {
+                    ticket.short_summary = null;
+                }
+                else if (typeof short_summary === 'string') {
+                    ticket.short_summary = (0, ticket_store_1.clampShortSummary)(short_summary);
+                }
+                ticket.updated_at = new Date().toISOString();
+                updated = ticket;
+            });
+            if (validationError) {
+                res.status(400).json({ error: validationError });
+                return;
+            }
+            if (!updated) {
+                res.status(404).json({ error: 'Ticket not found' });
+                return;
+            }
+            const { broadcast, ticketWatcher, jiraSyncManager } = ctx(req);
+            ticketWatcher.notifyDesktopWrite(store.revision);
+            const msg = { type: 'ticket_updated', ticket: updated, projectId: ctx(req).project.id, timestamp: new Date().toISOString() };
+            broadcast(msg);
+            // Write the edited fields back to Jira for Jira-backed specs (no-op
+            // otherwise). Uses the FINAL stored values (e.g. acceptance-criteria
+            // folding) for the fields that were actually changed. Never breaks the
+            // local save — a Jira hiccup only fails the enqueue, which is caught.
+            try {
+                const u = updated;
+                const changes = {};
+                if (title !== undefined)
+                    changes.title = u.title;
+                if (description !== undefined || acceptanceCriteria !== undefined)
+                    changes.description = u.description;
+                if (priority !== undefined)
+                    changes.priority = u.priority ?? null;
+                if (labels !== undefined)
+                    changes.labels = u.labels;
+                if (Object.keys(changes).length > 0)
+                    jiraSyncManager?.onSpecEdited(Number(ticketId), changes);
+            }
+            catch (e) {
+                console.error('[project-router] jira write-back enqueue failed:', e);
+            }
+            res.json({ ticket: updated, revision: store.revision });
+        }
+        catch (err) {
+            console.error('[project-router] ticket update error:', err);
+            res.status(500).json({ error: 'Failed to update ticket' });
+        }
+    });
+    // POST /:projectId/tickets/:id/ai-edit — AI-powered description editing
+    const _aiEditProcesses = new Map();
+    router.post('/:projectId/tickets/:id/ai-edit', async (req, res) => {
+        const ticketId = req.params.id;
+        if (!/^\d+$/.test(ticketId)) {
+            res.status(400).json({ error: 'Invalid ticket ID' });
+            return;
+        }
+        const instructions = req.body?.instructions;
+        const currentDescription = req.body?.description;
+        const currentTitle = typeof req.body?.title === 'string' ? req.body.title : '';
+        if (!instructions?.trim()) {
+            res.status(400).json({ error: 'instructions is required' });
+            return;
+        }
+        if (!currentDescription) {
+            res.status(400).json({ error: 'description is required' });
+            return;
+        }
+        const attachmentIds = Array.isArray(req.body?.attachmentIds)
+            ? req.body.attachmentIds.filter((x) => typeof x === 'string')
+            : [];
+        const priorInstructions = Array.isArray(req.body?.priorInstructions)
+            ? req.body.priorInstructions.filter((x) => typeof x === 'string')
+            : [];
+        const priorProposalRaw = req.body?.priorProposal;
+        const priorProposal = typeof priorProposalRaw === 'string' && priorProposalRaw.length > 0 ? priorProposalRaw : null;
+        const isRefinement = priorProposal !== null;
+        const { project, broadcast } = ctx(req);
+        const provider = project.provider ?? 'claude';
+        const requestId = (0, ids_1.newId)();
+        const projectId = project.id;
+        // Build the focused pre-prompt
+        const baseRules = `- Output format MUST be exactly:\n` +
+            `    TITLE: <one-line spec title>\n` +
+            `    SHORT-SUMMARY: <one or two plain-language sentences, max 120 chars, summarising the spec for a dashboard postit. No markdown, no bullets.>\n` +
+            `    \n` +
+            `    <markdown description body>\n` +
+            `  The first line MUST start with "TITLE: " followed by the refined title.\n` +
+            `  The second line MUST start with "SHORT-SUMMARY: " followed by the summary.\n` +
+            `  Then exactly one blank line. Then the markdown description.\n` +
+            `- Keep the title concise (under 80 characters) and reflective of the latest description.\n` +
+            `  If the user's refinement does not affect the title's intent, you may keep it unchanged — but always emit the TITLE line.\n` +
+            `- The SHORT-SUMMARY line MUST always be present. If the user's refinement does not change what the spec is about, keep the previous summary verbatim. Never omit the line.\n` +
+            `- After the SHORT-SUMMARY line and blank line, output ONLY the modified description in markdown. No preamble, no explanation, no wrapping.\n` +
+            `- Preserve the existing markdown structure and section headings in the description.\n` +
+            `- If the user asks to add technical details, briefly check CLAUDE.md and the project directory structure (ls, not deep reads) to ground your edits.\n` +
+            `- Keep it concise and actionable.\n` +
+            `- Do NOT create files, tickets, or issues. Only output text.`;
+        const refinementRule = isRefinement
+            ? `\n- You are editing an in-progress draft, not the saved description. Apply the new refinement to the Latest Draft below.`
+            : '';
+        let systemPrompt = `You are a spec editor. You will receive a ticket title and description plus user instructions for how to modify them. ` +
+            `Your job is to produce an improved version of BOTH the title and the description.\n\n` +
+            `RULES:\n` +
+            `${baseRules}${refinementRule}`;
+        let userPrompt = isRefinement
+            ? `## Current Title (saved baseline)\n\n${currentTitle}\n\n` +
+                `## Current Description (saved baseline — do not rewrite)\n\n${currentDescription}\n\n` +
+                `## Prior Refinement Turns\n\n${priorInstructions.map((s, i) => `${i + 1}. ${s}`).join('\n')}\n\n` +
+                `## Latest Draft (from previous turn — apply the new refinement to this; the draft already includes a TITLE: line)\n\n${priorProposal}\n\n` +
+                `## New Refinement\n\n${instructions.trim()}\n\n` +
+                `Output the updated TITLE line followed by the updated description now.`
+            : `## Current Title\n\n${currentTitle}\n\n` +
+                `## Current Description\n\n${currentDescription}\n\n` +
+                `## User Instructions\n\n${instructions.trim()}\n\n` +
+                `Output the modified TITLE line followed by the modified description now.`;
+        let imageFlags = [];
+        if (attachmentIds.length > 0) {
+            try {
+                const extracted = await attachment_manager_1.attachmentManager.getClaudeArgs(project.slug, ticketId, attachmentIds);
+                imageFlags = extracted.imageFlags;
+                if (extracted.textBlocks.length > 0) {
+                    systemPrompt = `${systemPrompt}\n\n${attachment_manager_1.USER_ATTACHMENT_SYSTEM_NOTE}`;
+                    userPrompt = `${userPrompt}\n\n## Attached Files\n\n${extracted.textBlocks.join('\n\n')}`;
+                }
+            }
+            catch (err) {
+                console.error('[project-router] ai-edit attachment extraction error:', err);
+            }
+        }
+        let binary;
+        let args;
+        if (provider === 'codex') {
+            binary = 'codex';
+            // Use gpt-5.5 (default for Codex per CODEX_MODELS/PRESET_DEFAULTS in ModelSelector); never hardcode o4-mini
+            args = ['exec', `${systemPrompt}\n\n${userPrompt}`, '--model', 'gpt-5.5'];
+        }
+        else {
+            binary = 'claude';
+            args = [
+                '--dangerously-skip-permissions',
+                '--tools', 'default',
+                '--output-format', 'stream-json',
+                '--verbose',
+                '--max-turns', '4',
+                ...imageFlags,
+                '--system-prompt', systemPrompt,
+                '-p', userPrompt,
+            ];
+        }
+        // spawnAiCli reroutes multi-line argv values through stdin on Windows.
+        console.log(`[project-router] ai-edit spawn: ${binary} (cwd=${project.path}, requestId=${requestId})`);
+        const child = (0, cli_prompt_1.spawnAiCli)(binary, args, {
+            env: process.env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            cwd: project.path,
+        });
+        _aiEditProcesses.set(requestId, child);
+        // Pipe stderr to server log so failures surface for debugging.
+        let aiEditStderrBuf = '';
+        /* c8 ignore start -- diagnostic-only; fires only when claude writes stderr */
+        child.stderr?.on('data', (chunk) => {
+            const s = chunk.toString();
+            aiEditStderrBuf += s;
+            console.error(`[project-router] ai-edit stderr (${requestId}): ${s.trimEnd()}`);
+        });
+        /* c8 ignore stop */
+        // Without this listener, ENOENT (binary missing on PATH) propagates as
+        // an unhandled 'error' event and crashes the entire app process.
+        /* c8 ignore start -- spawn-failure path; exercised manually, not in CI */
+        child.on('error', (err) => {
+            console.error(`[project-router] ai-edit spawn failed (${binary}): ${err.message}`);
+            _aiEditProcesses.delete(requestId);
+            const errMsg = {
+                type: 'ticket_ai_edit_error', projectId, ticketId: Number(ticketId),
+                requestId, error: `Failed to launch ${binary}: ${err.message}`,
+                timestamp: new Date().toISOString(),
+            };
+            broadcast(errMsg);
+        });
+        /* c8 ignore stop */
+        res.status(202).json({ requestId });
+        let buffer = '';
+        const stdoutReader = (0, readline_1.createInterface)({ input: child.stdout, crlfDelay: Infinity });
+        stdoutReader.on('line', (line) => {
+            if (provider === 'codex') {
+                if (line) {
+                    buffer += line + '\n';
+                    const msg = {
+                        type: 'ticket_ai_edit_stream', projectId, ticketId: Number(ticketId),
+                        requestId, delta: line + '\n', timestamp: new Date().toISOString(),
+                    };
+                    broadcast(msg);
+                }
+            }
+            else {
+                let parsed = null;
+                try {
+                    parsed = JSON.parse(line);
+                }
+                catch { /* skip */ }
+                if (!parsed)
+                    return;
+                if (parsed.type === 'assistant') {
+                    const msg = parsed.message;
+                    const texts = (msg?.content ?? [])
+                        .filter((c) => c.type === 'text')
+                        .map((c) => c.text ?? '');
+                    const newText = texts.join('');
+                    if (newText) {
+                        buffer += newText;
+                        const wsMsg = {
+                            type: 'ticket_ai_edit_stream', projectId, ticketId: Number(ticketId),
+                            requestId, delta: newText, timestamp: new Date().toISOString(),
+                        };
+                        broadcast(wsMsg);
+                    }
+                }
+            }
+        });
+        child.on('close', (code) => {
+            _aiEditProcesses.delete(requestId);
+            if (code === 0 && buffer.trim()) {
+                const msg = {
+                    type: 'ticket_ai_edit_done', projectId, ticketId: Number(ticketId),
+                    requestId, fullText: buffer.trim(), timestamp: new Date().toISOString(),
+                };
+                broadcast(msg);
+            }
+            else {
+                const reason = code === 0 ? 'Empty response from AI' : `Process exited with code ${code}`;
+                console.error(`[project-router] ai-edit failed (${requestId}): ${reason}` +
+                    (aiEditStderrBuf.trim() ? `\n  stderr: ${aiEditStderrBuf.trim()}` : '') +
+                    (buffer.trim() ? `\n  stdout-buffer: ${buffer.trim().slice(0, 500)}` : ''));
+                const msg = {
+                    type: 'ticket_ai_edit_error', projectId, ticketId: Number(ticketId),
+                    requestId, error: reason,
+                    timestamp: new Date().toISOString(),
+                };
+                broadcast(msg);
+            }
+        });
+    });
+    router.delete('/:projectId/tickets/:id/ai-edit', (req, res) => {
+        const requestId = req.query.requestId;
+        if (!requestId) {
+            res.status(400).json({ error: 'requestId query param required' });
+            return;
+        }
+        const child = _aiEditProcesses.get(requestId);
+        if (!child?.pid) {
+            res.status(404).json({ error: 'No active AI edit for this request' });
+            return;
+        }
+        (0, tree_kill_1.default)(child.pid, 'SIGTERM');
+        _aiEditProcesses.delete(requestId);
+        res.json({ ok: true });
+    });
+    // DELETE /:projectId/tickets/:id — Delete ticket
+    router.delete('/:projectId/tickets/:id', (req, res) => {
+        const ticketId = req.params.id;
+        if (!/^\d+$/.test(ticketId)) {
+            res.status(400).json({ error: 'Invalid ticket ID' });
+            return;
+        }
+        try {
+            const filePath = ticketPath(req);
+            let found = false;
+            let orphanedConversationId = null;
+            const orphanedChildren = [];
+            const numericId = Number(ticketId);
+            const store = (0, ticket_store_1.mutateStore)(filePath, (s) => {
+                const t = s.tickets[ticketId];
+                if (!t)
+                    return;
+                // If this is a draft and no other ticket references the same
+                // origin_conversation_id, mark it for cascade delete.
+                if (t.status === 'draft' && t.origin_conversation_id) {
+                    const otherRefs = Object.values(s.tickets).some((other) => other.id !== t.id && other.origin_conversation_id === t.origin_conversation_id);
+                    if (!otherRefs)
+                        orphanedConversationId = t.origin_conversation_id;
+                }
+                // SMASH: when deleting an épica, orphan its children (set
+                // parent_epic_id/execution_order to null) rather than cascade-delete.
+                if (t.is_epic) {
+                    const now = new Date().toISOString();
+                    for (const childId of Object.keys(s.tickets)) {
+                        const child = s.tickets[childId];
+                        if (child.parent_epic_id === numericId) {
+                            child.parent_epic_id = null;
+                            child.execution_order = null;
+                            child.updated_at = now;
+                            orphanedChildren.push(child);
+                        }
+                    }
+                }
+                delete s.tickets[ticketId];
+                found = true;
+            });
+            if (!found) {
+                res.status(404).json({ error: 'Ticket not found' });
+                return;
+            }
+            const { broadcast, ticketWatcher, db, chatManager } = ctx(req);
+            ticketWatcher.notifyDesktopWrite(store.revision);
+            // Cascade-delete attachments for this ticket
+            attachment_manager_1.attachmentManager.deleteAll(ctx(req).project.slug, ticketId).catch((e) => {
+                console.error('[project-router] attachment cascade delete failed:', e);
+            });
+            // Cascade-delete the orphaned Explore conversation, if any.
+            if (orphanedConversationId) {
+                try {
+                    const conv = (0, db_1.getConversation)(db, orphanedConversationId);
+                    if (conv && conv.kind === 'explore') {
+                        (0, db_1.deleteConversation)(db, orphanedConversationId);
+                        chatManager?.forgetSpecDraft(orphanedConversationId);
+                        chatManager?.forgetExploreLifecycle(orphanedConversationId);
+                    }
+                }
+                catch (err) {
+                    console.error('[project-router] orphan conversation cleanup failed:', err);
+                }
+            }
+            // Broadcast ticket_updated for each orphaned child so observers see them
+            // as regular tickets (no longer attached to the deleted épica).
+            for (const child of orphanedChildren) {
+                broadcast({
+                    type: 'ticket_updated',
+                    ticket: child,
+                    projectId: ctx(req).project.id,
+                    timestamp: new Date().toISOString(),
+                });
+            }
+            const msg = { type: 'ticket_deleted', ticketId: Number(ticketId), projectId: ctx(req).project.id, timestamp: new Date().toISOString() };
+            broadcast(msg);
+            res.json({ ok: true, revision: store.revision });
+        }
+        catch (err) {
+            console.error('[project-router] ticket delete error:', err);
+            res.status(500).json({ error: 'Failed to delete ticket' });
+        }
+    });
+    // ─── Ticket attachments ─────────────────────────────────────────────────────
+    const attachmentUpload = (0, multer_1.default)({
+        storage: multer_1.default.memoryStorage(),
+        limits: { fileSize: 25 * 1024 * 1024 }, // 25 MB per file
+        fileFilter: (_req, file, cb) => {
+            if ((0, attachment_manager_1.isSupportedUploadedFile)({ mimetype: file.mimetype, originalname: file.originalname }))
+                cb(null, true);
+            else
+                cb(null, false);
+        },
+    });
+    /** A ticket key is either a numeric real id or a UUID (pendingSpecId). */
+    function parseTicketKey(raw) {
+        if (/^\d+$/.test(raw))
+            return { key: raw, isPending: false };
+        if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(raw)) {
+            return { key: raw, isPending: true };
+        }
+        return null;
+    }
+    router.post('/:projectId/tickets/:ticketId/attachments', attachmentUpload.single('file'), async (req, res) => {
+        const parsed = parseTicketKey(req.params.ticketId);
+        if (!parsed) {
+            res.status(400).json({ error: 'Invalid ticketId (must be numeric id or UUID)' });
+            return;
+        }
+        const file = req.file;
+        if (!file) {
+            res.status(400).json({ error: 'No file uploaded or file type unsupported' });
+            return;
+        }
+        if (!parsed.isPending) {
+            const store = (0, ticket_store_1.readStore)(ticketPath(req));
+            if (!store.tickets[parsed.key]) {
+                res.status(404).json({ error: 'Ticket not found' });
+                return;
+            }
+        }
+        try {
+            const attachment = await attachment_manager_1.attachmentManager.upload({
+                slug: ctx(req).project.slug,
+                ticketKey: parsed.key,
+                projectPath: parsed.isPending ? null : ctx(req).project.path,
+                file: {
+                    buffer: file.buffer,
+                    originalname: file.originalname,
+                    mimetype: file.mimetype,
+                    size: file.size,
+                },
+            });
+            res.status(201).json({ attachment });
+        }
+        catch (err) {
+            const status = err.status ?? 500;
+            const message = err instanceof Error ? err.message : 'Upload failed';
+            console.error('[project-router] attachment upload error:', err);
+            res.status(status).json({ error: message });
+        }
+    });
+    router.get('/:projectId/tickets/:ticketId/attachments', (req, res) => {
+        const parsed = parseTicketKey(req.params.ticketId);
+        if (!parsed) {
+            res.status(400).json({ error: 'Invalid ticketId' });
+            return;
+        }
+        const attachments = attachment_manager_1.attachmentManager.list(ctx(req).project.slug, parsed.key);
+        res.json({ attachments });
+    });
+    router.get('/:projectId/tickets/:ticketId/attachments/:attachmentId', (req, res) => {
+        const parsed = parseTicketKey(req.params.ticketId);
+        if (!parsed) {
+            res.status(400).json({ error: 'Invalid ticketId' });
+            return;
+        }
+        const attachmentId = req.params.attachmentId;
+        const slug = ctx(req).project.slug;
+        const meta = attachment_manager_1.attachmentManager.getMeta(slug, parsed.key, attachmentId);
+        const abs = meta ? attachment_manager_1.attachmentManager.getFilePath(slug, parsed.key, attachmentId) : null;
+        if (!meta || !abs) {
+            res.status(404).json({ error: 'Attachment not found' });
+            return;
+        }
+        res.setHeader('Content-Type', meta.mimeType);
+        // Strip quotes AND CR/LF: a newline in the stored (raw) original filename
+        // makes Node's setHeader throw ERR_INVALID_CHAR after Content-Type is
+        // already set, 500-ing the download. Also emit an RFC 5987 filename* so
+        // 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);
+    });
+    router.delete('/:projectId/tickets/:ticketId/attachments/:attachmentId', async (req, res) => {
+        const parsed = parseTicketKey(req.params.ticketId);
+        if (!parsed) {
+            res.status(400).json({ error: 'Invalid ticketId' });
+            return;
+        }
+        const attachmentId = req.params.attachmentId;
+        try {
+            const ok = await attachment_manager_1.attachmentManager.delete({
+                slug: ctx(req).project.slug,
+                ticketKey: parsed.key,
+                attachmentId,
+                projectPath: parsed.isPending ? null : ctx(req).project.path,
+            });
+            if (!ok) {
+                res.status(404).json({ error: 'Attachment not found' });
+                return;
+            }
+            res.status(204).end();
+        }
+        catch (err) {
+            console.error('[project-router] attachment delete error:', err);
+            res.status(500).json({ error: 'Delete failed' });
+        }
+    });
+    router.delete('/:projectId/tickets/:ticketId/attachments', async (req, res) => {
+        const parsed = parseTicketKey(req.params.ticketId);
+        if (!parsed) {
+            res.status(400).json({ error: 'Invalid ticketId' });
+            return;
+        }
+        try {
+            await attachment_manager_1.attachmentManager.deleteAll(ctx(req).project.slug, parsed.key);
+            res.status(204).end();
+        }
+        catch (err) {
+            console.error('[project-router] attachment bulk delete error:', err);
+            res.status(500).json({ error: 'Bulk delete failed' });
+        }
+    });
+}