specrails-desktop 2.64.1 → 2.65.0

package/server/dist/modules/specs/runtime/spec-generation.js

@@ -0,0 +1,431 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpecGenerationToolPolicyError = exports.GENERATE_SPEC_TIMEOUT_MS = void 0;
+exports.resolveSpecGenerationToolPolicy = resolveSpecGenerationToolPolicy;
+exports.buildSpecGenerationPrompts = buildSpecGenerationPrompts;
+exports.persistGeneratedSpec = persistGeneratedSpec;
+exports.startSpecGeneration = startSpecGeneration;
+exports.generateSpecFromText = generateSpecFromText;
+/**
+ * Spec generation use case — turns free text (an idea, a derived proposal, a
+ * conversation summary) into a structured Specrails spec through one
+ * provider `spec-gen` spawn, then persists it as a NEW ticket or REWRITES an
+ * existing ticket in place (same id; title, description incl. acceptance
+ * criteria, labels, priority and short summary replaced in the same format).
+ *
+ * `startSpecGeneration` spawns synchronously (so argument/adapter failures
+ * surface to the caller before it acknowledges anything) and returns a `done`
+ * promise; `generateSpecFromText` is the awaitable form. Transport concerns —
+ * HTTP validation, `spec_gen_*` / `ticket_*` WebSocket messages, attachment
+ * migration, Jira promotion — stay with the caller through `hooks`.
+ *
+ * Contract Layer: when `contractRefine` is set, `runContractRefineForQuick`
+ * is scheduled on the same provider after the ticket is persisted and the
+ * `onPersisted` hook has run, exactly as Quick Add Spec does.
+ */
+const crypto_1 = require("crypto");
+const readline_1 = require("readline");
+const tree_kill_1 = __importDefault(require("tree-kill"));
+const providers_1 = require("../../../providers");
+const runtime_1 = require("../../../providers/runtime");
+const project_env_1 = require("../../../project-env");
+const project_repositories_1 = require("../../../project-repositories");
+const workspace_resolution_1 = require("../../../workspace-resolution");
+const cli_prompt_1 = require("../../../util/cli-prompt");
+const transient_children_1 = require("../../../transient-children");
+const attachment_manager_1 = require("../../../attachment-manager");
+const ai_invocations_1 = require("../../accounting/runtime/ai-invocations");
+const result_event_1 = require("../../accounting/runtime/result-event");
+const context_scope_1 = require("../../conversations/runtime/context-scope");
+const contract_refine_runner_1 = require("./contract-refine-runner");
+const generated_spec_parser_1 = require("./generated-spec-parser");
+const ticket_store_1 = require("./ticket-store");
+/** Wall-clock cap: 'full' scope can legitimately run minutes; --max-turns
+ *  bounds turns, not time. */
+exports.GENERATE_SPEC_TIMEOUT_MS = 8 * 60 * 1000;
+class SpecGenerationToolPolicyError extends Error {
+    provider;
+    requiredPolicy;
+    code = 'provider_tool_policy_unsupported';
+    constructor(provider, requiredPolicy) {
+        super(`Provider ${provider} cannot run spec generation with a ${requiredPolicy} tool policy`);
+        this.provider = provider;
+        this.requiredPolicy = requiredPolicy;
+        this.name = 'SpecGenerationToolPolicyError';
+    }
+}
+exports.SpecGenerationToolPolicyError = SpecGenerationToolPolicyError;
+/** Tool policy for a spec-gen spawn, or null when the adapter cannot honour it. */
+function resolveSpecGenerationToolPolicy(provider, scope) {
+    const adapter = (0, providers_1.getAdapter)(provider);
+    return scope.full
+        ? ((0, runtime_1.supportsToolPolicy)(adapter, 'read-only') ? 'read-only' : null)
+        : (0, runtime_1.pureOutputToolPolicy)(adapter);
+}
+function buildSpecGenerationPrompts(input) {
+    const { project, scope } = input;
+    let hasAttachments = false;
+    let userPrompt = `Generate a spec for the following idea:\n\n${input.text.trim()}`;
+    if (input.attachments && input.attachments.textBlocks.length > 0) {
+        hasAttachments = true;
+        userPrompt = `${userPrompt}\n\n## Attached Resources\n\n${input.attachments.textBlocks.join('\n\n')}`;
+    }
+    // Relocate-artifacts: tickets read from the workspace when relocated.
+    const specRoot = (() => {
+        const e = (0, workspace_resolution_1.resolveProjectExecution)({ slug: project.slug, path: project.path });
+        return e.relocated && e.workspaceDir ? e.workspaceDir : project.path;
+    })();
+    const specsPrefix = (0, context_scope_1.buildScopedSystemPromptPrefix)(scope, project.path, specRoot);
+    const codebaseRule = scope.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 (scope.specrails) dumps every ticket into the
+    // prompt as informational context; without an explicit dedup instruction the
+    // model still proposes near-duplicates. Gated on the toggle.
+    const dedupRule = scope.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 = scope.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 systemPrompt = `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 of 1-5 non-goals: what this spec deliberately does NOT change or deliver, so implementers do not widen it. Never empty — name at least one adjacent thing left out.]\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)
+        systemPrompt = `${systemPrompt}\n\n${attachment_manager_1.USER_ATTACHMENT_SYSTEM_NOTE}`;
+    const repositories = (0, project_repositories_1.getProjectRepositories)(project);
+    if (repositories.length > 1) {
+        systemPrompt += `\n\nThis logical project has one shared backlog across these repositories: ${JSON.stringify(repositories.map(({ id, name, path, isPrimary, kind }) => ({ id, name, path, isPrimary, kind })))}.\nThis spec targets repository IDs: ${JSON.stringify(input.repositoryIds ?? [repositories.find((repo) => repo.isPrimary).id])}. Describe cross-repository contracts when selected; do not create separate tickets per repository.`;
+    }
+    return { systemPrompt, userPrompt, hasAttachments };
+}
+/**
+ * Persist a generated spec: create a new `propose-spec` ticket, or rewrite
+ * `ticketId` in place keeping its id, status, metadata, comments, ownership
+ * and attachments. Returns null when the ticket to rewrite does not exist.
+ */
+function persistGeneratedSpec(deps, spec, target) {
+    const now = new Date().toISOString();
+    let persisted;
+    let kind = 'created';
+    const store = (0, ticket_store_1.mutateStore)(deps.ticketStorePath, (s) => {
+        if (target.ticketId !== undefined) {
+            const existing = s.tickets[String(target.ticketId)];
+            if (!existing)
+                return;
+            const rewritten = {
+                ...existing,
+                title: spec.title,
+                description: spec.description,
+                priority: spec.priority,
+                labels: spec.labels,
+                short_summary: spec.shortSummary,
+                // A rewrite without an Out of Scope section keeps the spec's non-goals.
+                ...(spec.nonGoals.length ? { nonGoals: spec.nonGoals } : {}),
+                updated_at: now,
+            };
+            s.tickets[String(target.ticketId)] = rewritten;
+            persisted = rewritten;
+            kind = 'rewritten';
+            return;
+        }
+        const id = s.next_id++;
+        const ticket = {
+            ...(target.repositoryScope ?? {}),
+            id,
+            title: spec.title,
+            description: spec.description,
+            status: 'todo',
+            priority: spec.priority,
+            labels: spec.labels,
+            assignee: null,
+            prerequisites: [],
+            metadata: {},
+            comments: [],
+            origin_conversation_id: null,
+            is_epic: false,
+            parent_epic_id: null,
+            execution_order: null,
+            short_summary: spec.shortSummary,
+            ...(spec.nonGoals.length ? { nonGoals: spec.nonGoals } : {}),
+            created_at: now,
+            updated_at: now,
+            created_by: 'sr-product-engineer',
+            source: 'propose-spec',
+        };
+        s.tickets[String(id)] = ticket;
+        persisted = ticket;
+    });
+    if (!persisted)
+        return null;
+    deps.ticketWatcher.notifyDesktopWrite(store.revision);
+    return { ticket: persisted, kind };
+}
+/**
+ * Spawn the provider `spec-gen` run. Synchronous up to the spawn: a throw here
+ * means nothing was started. `done` always resolves (never rejects).
+ */
+function startSpecGeneration(deps, input) {
+    const { project, admission } = deps;
+    const projectId = project.id;
+    const provider = input.provider;
+    const requestId = input.requestId ?? (0, crypto_1.randomUUID)();
+    const hooks = input.hooks ?? {};
+    const scope = input.scope;
+    const adapter = (0, providers_1.getAdapter)(provider);
+    const toolPolicy = resolveSpecGenerationToolPolicy(provider, scope);
+    if (!toolPolicy)
+        throw new SpecGenerationToolPolicyError(provider, scope.full ? 'read-only' : 'pure-output');
+    const { systemPrompt, userPrompt, hasAttachments } = buildSpecGenerationPrompts({
+        project, text: input.text, scope, repositoryIds: input.repositoryIds, attachments: input.attachments,
+    });
+    const imageFlags = input.attachments?.imageFlags ?? [];
+    const imagePaths = input.attachments?.imagePaths ?? [];
+    // Spawn args are adapter-driven. For Claude the `--tools` flag set comes from
+    // `toolFlagsForScope(scope)` which the adapter doesn't model — pass them
+    // through `extraArgs` after COMMON_FLAGS, with `imageFlags` (Claude-only).
+    const toolFlags = provider === 'claude' ? (0, context_scope_1.toolFlagsForScope)(scope) : { args: [] };
+    // Full scope grants Read/Grep/Glob; 15 turns leaves headroom for exploring
+    // before writing while --max-turns still bounds runaway loops.
+    const claudeMaxTurns = scope.full ? 15 : (hasAttachments ? 3 : 1);
+    const specGenOptions = {
+        prompt: userPrompt,
+        systemPrompt,
+        model: input.model,
+        toolPolicy,
+        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). Project `.mcp.json` is
+        // discovered natively from the spawn cwd.
+        loadUserEnv: adapter.capabilities.userMcp === true && scope.userMcp,
+        imagePaths: adapter.capabilities.supportsImageInput ? imagePaths : undefined,
+    };
+    const args = adapter.buildArgs('spec-gen', specGenOptions);
+    const binary = adapter.binary;
+    // Relocate-artifacts gate: spawn from the workspace + SPECRAILS_REPO_DIR when
+    // relocated, else cwd = project.path + process.env (byte-identical legacy).
+    const specGenExec = (0, workspace_resolution_1.resolveProjectExecution)({ slug: project.slug, path: project.path });
+    let specGenEnv = process.env;
+    if (specGenExec.relocated) {
+        specGenEnv = { ...process.env, ...specGenExec.env };
+        if (adapter.id === 'gemini')
+            specGenEnv = { ...specGenEnv, GEMINI_CLI_TRUST_WORKSPACE: 'true' };
+    }
+    // spawnAiCli reroutes multi-line argv values through stdin on Windows.
+    console.log(`[project-router] spec-gen spawn: ${binary} (cwd=${specGenExec.cwd}, requestId=${requestId})`);
+    const child = (0, cli_prompt_1.spawnAiCli)(binary, args, {
+        env: (0, runtime_1.buildProviderEnv)(adapter, specGenOptions, (0, project_env_1.projectAgentSourceEnv)(deps.db, (0, runtime_1.providerEnvAllowlist)(adapter), specGenEnv)),
+        stdio: ['ignore', 'pipe', 'pipe'],
+        cwd: specGenExec.cwd,
+    });
+    // Register so removeProject()/shutdown() can tree-kill this otherwise
+    // untracked child (auto-unregisters on close/error).
+    (0, transient_children_1.trackTransientChild)(projectId, child);
+    let resolveDone;
+    const done = new Promise((resolve) => { resolveDone = resolve; });
+    let failure = null;
+    const fail = (error) => {
+        failure = error;
+        hooks.onError?.(error);
+    };
+    // Watchdog: a hung CLI would otherwise leak this child + its readline.
+    let watchdog = setTimeout(() => {
+        watchdog = null;
+        if (child.pid) {
+            try {
+                (0, tree_kill_1.default)(child.pid, 'SIGTERM');
+            }
+            catch { /* best-effort */ }
+        }
+        if (!admission.isCurrent())
+            return;
+        fail(`Spec generation timed out after ${Math.round(exports.GENERATE_SPEC_TIMEOUT_MS / 1000)}s`);
+    }, exports.GENERATE_SPEC_TIMEOUT_MS);
+    if (typeof watchdog.unref === 'function')
+        watchdog.unref();
+    const clearWatchdog = () => {
+        if (watchdog) {
+            clearTimeout(watchdog);
+            watchdog = null;
+        }
+    };
+    let stderrBuf = '';
+    /* c8 ignore start -- diagnostic-only; fires only when the CLI 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 propagates as an unhandled 'error' event and
+    // crashes the app process.
+    /* c8 ignore start -- spawn-failure path; exercised manually, not in CI */
+    child.on('error', (err) => {
+        clearWatchdog();
+        console.error(`[project-router] spec-gen spawn failed (${binary}): ${err.message}`);
+        if (!admission.isCurrent())
+            return;
+        fail(`Failed to launch ${binary}: ${err.message}`);
+        resolveDone({ ok: false, requestId, error: failure });
+    });
+    /* c8 ignore stop */
+    let buffer = '';
+    let lastResultEvent = null;
+    // Canonical adapter events feed finaliseInvocationResult on close.
+    const adapterEvents = [];
+    const turnStartedAt = new Date().toISOString();
+    const stdoutReader = (0, readline_1.createInterface)({ input: child.stdout, crlfDelay: Infinity });
+    stdoutReader.on('line', (line) => {
+        if (!admission.isCurrent())
+            return;
+        const eventsForLine = (0, runtime_1.parseStreamEvents)(adapter, line);
+        adapterEvents.push(...eventsForLine);
+        let parsed = null;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch { /* skip */ }
+        if (parsed && eventsForLine.some((event) => event.kind === 'result')) {
+            lastResultEvent = parsed;
+        }
+        for (const event of eventsForLine) {
+            if (event.kind !== 'text-delta' || !event.text)
+                continue;
+            buffer += event.text;
+            hooks.onDelta?.(event.text);
+        }
+    });
+    child.on('close', async (code) => {
+        clearWatchdog();
+        if (!admission.isCurrent()) {
+            resolveDone({ ok: false, requestId, error: 'Project is being removed' });
+            return;
+        }
+        let persistedTicketId = null;
+        let outcome = null;
+        // A claude run that burns --max-turns exits non-zero with subtype
+        // error_max_turns but may already have emitted a complete spec: salvage it.
+        const resultSubtype = lastResultEvent?.subtype ?? null;
+        const hasUsableSpec = buffer.trim().length > 0 && (0, generated_spec_parser_1.hasGeneratedSpecTitle)(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`);
+            }
+            const spec = (0, generated_spec_parser_1.parseGeneratedSpec)(buffer, input.text.trim().slice(0, 80));
+            try {
+                const repositoryScope = input.ticketId === undefined ? input.resolveRepositoryScope?.() : undefined;
+                const persisted = persistGeneratedSpec(deps, spec, { ticketId: input.ticketId, repositoryScope });
+                if (!persisted)
+                    throw new Error(`Ticket ${input.ticketId} not found`);
+                persistedTicketId = persisted.ticket.id;
+                const next = await hooks.onPersisted?.(persisted.ticket, persisted.kind);
+                if (next === 'abort') {
+                    resolveDone({ ok: true, requestId, ticket: persisted.ticket, kind: persisted.kind, spec });
+                    return;
+                }
+                outcome = { ok: true, requestId, ticket: persisted.ticket, kind: persisted.kind, spec };
+                // Contract Layer runs on the same selected provider.
+                if (input.contractRefine) {
+                    const refineTicketId = persisted.ticket.id;
+                    const refineTitle = persisted.ticket.title;
+                    const refineDescription = persisted.ticket.description;
+                    const refineModel = input.contractRefine.model;
+                    if (input.contractRefine.await) {
+                        if (admission.isCurrent())
+                            await scheduleContractLayer(deps, provider, refineTicketId, refineTitle, refineDescription, refineModel);
+                    }
+                    else
+                        process.nextTick(() => {
+                            if (!admission.isCurrent())
+                                return;
+                            void scheduleContractLayer(deps, provider, refineTicketId, refineTitle, refineDescription, refineModel);
+                        });
+                }
+            }
+            catch (err) {
+                console.error('[project-router] generate-spec ticket creation error:', err);
+                fail(input.ticketId === undefined ? 'Failed to create ticket' : 'Failed to rewrite ticket');
+            }
+        }
+        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)}` : ''));
+            fail(reason);
+        }
+        // ai_invocations capture. Always emit a row, success or fail.
+        try {
+            // Adapter-driven finalisation: claude passes its native total_cost_usd
+            // through; codex (nativeCostUsd:false) gets a pricing-table estimate.
+            const { result: normalised, estimated } = (0, result_event_1.finaliseInvocationResult)(adapter, adapterEvents, { fallbackModel: input.model });
+            const wallMs = Date.now() - new Date(turnStartedAt).getTime();
+            (0, ai_invocations_1.recordInvocation)(deps.db, {
+                id: (0, crypto_1.randomUUID)(),
+                project_id: projectId,
+                provider: adapter.id,
+                surface: input.surface ?? 'quick-spec',
+                surface_ref_id: requestId,
+                ticket_id: persistedTicketId,
+                // A delivered ticket (clean or error_max_turns salvage) is 'success'.
+                status: persistedTicketId !== null ? 'success' : 'failed',
+                started_at: turnStartedAt,
+                finished_at: new Date().toISOString(),
+                total_cost_usd_estimated: estimated,
+                ...normalised,
+                duration_ms: normalised.duration_ms ?? wallMs,
+            });
+            deps.broadcast({ type: 'spending.invalidated', projectId });
+        }
+        catch (err) {
+            console.error('[project-router] generate-spec recordInvocation failed:', err);
+        }
+        resolveDone(outcome ?? { ok: false, requestId, error: failure ?? 'Spec generation failed' });
+    });
+    return { requestId, done };
+}
+function scheduleContractLayer(deps, provider, ticketId, title, description, model) {
+    return (0, contract_refine_runner_1.runContractRefineForQuick)({
+        db: deps.db,
+        projectId: deps.project.id,
+        projectSlug: deps.project.slug,
+        projectPath: deps.project.path,
+        projectName: deps.project.name,
+        providerId: provider,
+        broadcast: deps.broadcast,
+    }, ticketId, title, description, model).catch((err) => {
+        console.error('[project-router] runContractRefineForQuick error:', err);
+    });
+}
+/** Awaitable spec generation: create a new spec ticket, or rewrite `ticketId`
+ *  in place. Throws only when the spawn cannot start. */
+function generateSpecFromText(deps, input) {
+    return startSpecGeneration(deps, input).done;
+}

package/server/dist/modules/specs/runtime/spec-handoff.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildHandoffModel = buildHandoffModel;
+exports.renderHandoff = renderHandoff;
+exports.parseHandoffFormat = parseHandoffFormat;
+exports.parsePlanProviders = parsePlanProviders;
+/**
+ * Hand-off export: builds the model from a spec's history and renders it.
+ *
+ * Effects stay out: the caller injects the diff reader (git) and the set of
+ * plan-billed providers (known to the client's subscription snapshot), so this
+ * file is a deterministic function of its inputs and easy to test.
+ */
+const audit_1 = require("../../audit");
+const spec_addenda_core_1 = require("./spec-addenda-core");
+const handoff_1 = require("../domain/handoff");
+const timeline_1 = require("../domain/timeline");
+const handoff_labels_1 = require("../domain/handoff-labels");
+const OPEN_DELIVERY_DECISIONS = new Set(['merged', 'completed', 'discarded', 'superseded', 'no_changes']);
+function verdictOf(d) {
+    const r = d.review;
+    if (!r)
+        return null;
+    if (r.approved === true)
+        return 'approved';
+    if (r.approved === false)
+        return 'changes_requested';
+    if (r.sentinel === 'fail')
+        return 'failed';
+    return 'recorded';
+}
+async function buildHandoffModel(input) {
+    const { ticket, history } = input;
+    const addenda = (0, spec_addenda_core_1.readSpecAddenda)(ticket.addenda);
+    const decisions = addenda
+        .filter((a) => a.status !== 'dismissed')
+        .map((a) => ({ kind: a.kind, at: (0, timeline_1.utc)(a.created_at), title: a.title, body: a.body, status: a.status }));
+    for (const d of history.deliveries) {
+        const verdict = verdictOf(d);
+        if (!d.review || !verdict)
+            continue;
+        decisions.push({ kind: 'verdict', at: d.review.harvestedAt, title: `${verdict}${d.review.findings.length > 0 ? ` (${d.review.findings.length})` : ''}`, body: d.review.summary ?? d.review.sentinelDetail, status: verdict });
+    }
+    decisions.sort((a, b) => (a.at < b.at ? -1 : 1));
+    const deliveries = [];
+    for (const d of history.deliveries) {
+        const stat = await input.diffFor(d).catch(() => null);
+        const verdict = verdictOf(d);
+        deliveries.push({
+            id: d.id, loop: d.loopName, decision: d.decision, branch: d.branch, base: d.baseBranch, prNumber: d.prNumber, prUrl: d.prUrl,
+            createdAt: d.createdAt, mergedAt: d.mergedAt,
+            diff: stat ? { available: true, ...stat } : { available: false },
+            review: d.review && verdict ? { verdict, findings: d.review.findings.length } : null,
+        });
+    }
+    const unresolvedFindings = history.deliveries
+        .filter((d) => d.review && d.review.findings.length > 0 && !OPEN_DELIVERY_DECISIONS.has(d.decision))
+        .flatMap((d) => d.review.findings.map((f) => ({ text: f.text, location: f.location, deliveryId: d.id })));
+    return {
+        generatedAt: input.now.toISOString(),
+        spec: {
+            id: ticket.id, title: ticket.title, status: ticket.status, priority: ticket.priority, labels: ticket.labels ?? [],
+            summary: ticket.short_summary, description: ticket.description ?? '',
+            nonGoals: ticket.nonGoals && ticket.nonGoals.length > 0 ? ticket.nonGoals.map((g) => `- ${g}`).join('\n') : null,
+            jiraKey: ticket.jira_key ?? null,
+        },
+        decisions,
+        deliveries,
+        cost: (0, handoff_1.summarizeCost)(history.invocations.map((i) => ({ provider: i.provider, costUsd: i.costUsd, estimated: i.estimated, turns: i.turns })), input.planProviders),
+        followUps: {
+            openAddenda: addenda.filter((a) => a.status === 'open' || a.status === 'in_flight').map((a) => ({ title: a.title, kind: a.kind, status: a.status })),
+            unresolvedFindings,
+        },
+    };
+}
+/** Redact, localize and render. The finished document is redacted once more (idempotent). */
+function renderHandoff(model, format, localeInput) {
+    const locale = (0, handoff_labels_1.resolveHandoffLocale)(localeInput);
+    const labels = (0, handoff_labels_1.handoffLabels)(locale);
+    const { model: clean, redactions } = (0, handoff_1.redactModel)(model, audit_1.redactProse);
+    const variant = format === 'pr' ? 'pr' : 'full';
+    const rendered = format === 'html' ? (0, handoff_1.renderHandoffHtml)(clean, labels, locale) : (0, handoff_1.renderHandoffMarkdown)(clean, labels, variant);
+    const body = (0, audit_1.redactProse)(rendered);
+    const slug = `spec-${model.spec.id}-handoff`;
+    return {
+        format,
+        filename: format === 'html' ? `${slug}.html` : format === 'pr' ? `spec-${model.spec.id}-pr-description.md` : `${slug}.md`,
+        contentType: format === 'html' ? 'text/html; charset=utf-8' : 'text/markdown; charset=utf-8',
+        body,
+        redactions,
+        locale,
+    };
+}
+function parseHandoffFormat(raw) {
+    if (raw === undefined || raw === '')
+        return 'md';
+    return raw === 'md' || raw === 'html' || raw === 'pr' ? raw : null;
+}
+function parsePlanProviders(raw) {
+    if (typeof raw !== 'string')
+        return new Set();
+    return new Set(raw.split(',').map((p) => p.trim()).filter((p) => /^[a-z0-9._-]{1,40}$/i.test(p)));
+}