specrails-desktop 2.64.2 → 2.65.1

package/server/dist/modules/flow/adapters/bindings.js

@@ -0,0 +1,1089 @@
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.systemClock = exports.FLOW_FAILURE_RETURN_TURN_TEXT = exports.FLOW_RETURN_TURN_TEXT = void 0;
+exports.deliveryFailureOf = deliveryFailureOf;
+exports.isCrashedFlowDelivery = isCrashedFlowDelivery;
+exports.railOfTicket = railOfTicket;
+exports.createFlowTickets = createFlowTickets;
+exports.launchOptionsOf = launchOptionsOf;
+exports.createFlowWorktrees = createFlowWorktrees;
+exports.createFlowPorts = createFlowPorts;
+exports.createFlowHandOffAuthority = createFlowHandOffAuthority;
+exports.createFlowTurnContext = createFlowTurnContext;
+exports.flowConversationSummary = flowConversationSummary;
+exports.changeNameFromArchive = changeNameFromArchive;
+exports.readDerivedChange = readDerivedChange;
+exports.createFlowPublication = createFlowPublication;
+exports.startFlowSettlementScheduler = startFlowSettlementScheduler;
+/**
+ * Production bindings of the Flow ports onto the other capabilities: delivery
+ * (worktree machinery, rail launch), specs (placeholder ticket), missions/Core
+ * agent sessions, accounting and the project's WebSocket. Bound to ONE project
+ * context at composition (project-registry); the application never sees them.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const ids_1 = require("../../../ids");
+const internal_api_1 = require("../../../internal-api");
+const desktop_db_1 = require("../../../desktop-db");
+const repo_lock_1 = require("../../../repo-lock");
+const worktree_manager_1 = require("../../../worktree-manager");
+const worktree_overlay_1 = require("../../../worktree-overlay");
+const worktree_node_modules_1 = require("../../../worktree-node-modules");
+const agent_store_1 = require("../../agents/runtime/agent-store");
+const project_repositories_1 = require("../../../project-repositories");
+const workspace_resolution_1 = require("../../../workspace-resolution");
+const jira_db_1 = require("../../../jira/jira-db");
+const providers_1 = require("../../../providers");
+const provider_selection_1 = require("../../../provider-selection");
+const runtime_1 = require("../../../providers/runtime");
+const process_admission_1 = require("../../../process-admission");
+const project_router_helpers_1 = require("../../../project-router-helpers");
+const agent_runtime_controls_router_1 = require("../../agent-runtime/runtime/agent-runtime-controls-router");
+const delivery_evidence_1 = require("../../delivery/runtime/delivery-evidence");
+const flow_review_outcome_1 = require("../../delivery/runtime/flow-review-outcome");
+const rail_pr_store_1 = require("../../delivery/runtime/rail-pr-store");
+const flow_worktree_return_1 = require("../../delivery/runtime/flow-worktree-return");
+const spec_generation_1 = require("../../specs/runtime/spec-generation");
+const isolated_worktree_1 = require("../../delivery/runtime/isolated-worktree");
+const flow_worktree_handoff_1 = require("../../delivery/runtime/flow-worktree-handoff");
+const rails_store_1 = require("../../delivery/runtime/rails-store");
+const agent_flow_prompt_1 = require("../../missions/runtime/agent-flow-prompt");
+const agent_failure_briefing_1 = require("../../missions/runtime/agent-failure-briefing");
+const flow_turn_context_1 = require("../../missions/runtime/flow-turn-context");
+const ticket_store_1 = require("../../specs/runtime/ticket-store");
+const spec_addenda_1 = require("../../specs/runtime/spec-addenda");
+const spec_addenda_core_1 = require("../../specs/runtime/spec-addenda-core");
+const rails_store_2 = require("../../delivery/runtime/rails-store");
+const rail_pr_store_2 = require("../../delivery/runtime/rail-pr-store");
+const domain_1 = require("../domain");
+/** The automatic turn after Back to Flow (the briefing itself rides the Flow turn). */
+exports.FLOW_RETURN_TURN_TEXT = 'Back to Flow: the Flow → Spec run came back with the findings above. In at most 2 short lines say what you will fix, then start fixing it in this worktree. If a finding leaves a genuine decision to me (for example removing behaviour nobody asked for versus recording it as a requirement), offer it as an `options` block before editing and wait for my answer.';
+/** The automatic turn after a Flow → Spec run failed outright and came back on its own. */
+exports.FLOW_FAILURE_RETURN_TURN_TEXT = 'Back to Flow: the Flow → Spec run failed with the error above and the worktree came back to this Flow intact. In at most 2 short lines tell me what failed in plain words and what you will do. If the cause is in this worktree, fix it here; if it is outside it (a tool version, the environment, credentials), tell me exactly what to change instead of working around it.';
+/** Status codes of a Flow → Spec run that stopped for review reasons (never a crash). */
+const FLOW_REVIEW_STATUS_CODES = new Set(['review_changes_requested', 'returned_to_flow']);
+/** The delivery codes of a Flow → Spec run that failed outright (null for a review outcome). */
+function deliveryFailureOf(snap) {
+    if (snap.flowReview)
+        return null;
+    // After the return, the delivery's own codes say `returned_to_flow`: the crash codes are gone.
+    const returned = snap.statusCode === 'returned_to_flow';
+    return {
+        stepId: null,
+        cause: null,
+        statusCode: returned ? null : snap.statusCode ?? null,
+        failureCode: snap.units.find((unit) => unit.failureCode)?.failureCode ?? null,
+        statusDetail: returned ? null : snap.statusDetail ?? null,
+    };
+}
+/** Whether a Flow → Spec delivery failed outright and is idle (the automatic return may take its worktree). */
+function isCrashedFlowDelivery(snap) {
+    return snap.loopId === flow_review_outcome_1.FLOW_SPEC_DELIVERY_LOOP_ID
+        && snap.decision === 'implementation_failed'
+        && !snap.flowReview
+        && !FLOW_REVIEW_STATUS_CODES.has(snap.statusCode ?? '')
+        && !snap.operation;
+}
+exports.systemClock = { now: () => new Date().toISOString() };
+function canonical(value) {
+    try {
+        return fs.realpathSync.native(value);
+    }
+    catch {
+        return path.resolve(value);
+    }
+}
+function isInside(child, parent) {
+    const relative = path.relative(canonical(parent), canonical(child));
+    return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
+}
+/** The rail of a spec from the project's rails and their live deliveries. */
+function railOfTicket(db) {
+    return (ticketId) => {
+        const rail = (0, rails_store_2.getRails)(db).find((candidate) => candidate.ticketIds.includes(ticketId));
+        if (!rail)
+            return null;
+        return { railIndex: rail.railIndex, running: Boolean((0, rail_pr_store_2.getActivePrDeliveryByRail)(db, rail.railIndex)) };
+    };
+}
+const CLOSED_SPEC_STATUSES = new Set(['done', 'cancelled']);
+/** The open addenda of a spec, as the first Flow turn lists them. */
+function renderOpenAddenda(ticket) {
+    const open = (0, spec_addenda_core_1.openAddenda)(ticket.addenda);
+    if (!open.length)
+        return '';
+    return ['## Open addenda (iterations requested on this spec)', '', ...open.slice(0, 20).map((addendum, index) => `${index + 1}. [${addendum.kind}] ${addendum.title}${addendum.body.trim() ? `\n   ${addendum.body.trim().slice(0, 600).replace(/\n/g, '\n   ')}` : ''}`)].join('\n');
+}
+function snapshotOf(ticket) {
+    return {
+        id: ticket.id,
+        title: ticket.title,
+        description: ticket.description ?? '',
+        status: ticket.status,
+        nonGoals: Array.isArray(ticket.nonGoals) ? ticket.nonGoals.filter((goal) => typeof goal === 'string') : [],
+        repositoryIds: Array.isArray(ticket.repositoryIds) ? ticket.repositoryIds.filter((id) => typeof id === 'string') : [],
+        addenda: renderOpenAddenda(ticket),
+    };
+}
+/** Why this spec cannot start a Flow now (null ⇒ it can). `flowId`: the Flow re-checking its own adoption. */
+function existingSpecBlocker(ticket, railOf, flowId) {
+    if (!ticket)
+        return { code: 'spec_not_found', message: 'This spec no longer exists' };
+    if (CLOSED_SPEC_STATUSES.has(ticket.status))
+        return { code: 'spec_closed', message: `Spec #${ticket.id} is ${ticket.status === 'done' ? 'done' : 'cancelled'}; reopen it to work on it in Flow` };
+    if ((0, ticket_store_1.isFlowHeldTicket)(ticket) && ticket.metadata?.flow?.flowId !== flowId)
+        return { code: 'spec_in_flow', message: `Spec #${ticket.id} is already in Flow` };
+    const rail = railOf?.(ticket.id) ?? null;
+    if (rail?.running)
+        return { code: 'spec_running', message: `Spec #${ticket.id} is running on Rail ${rail.railIndex + 1}` };
+    if (rail)
+        return { code: 'spec_on_rail', message: `Spec #${ticket.id} is on Rail ${rail.railIndex + 1}; take it off the rail to start it in Flow` };
+    return null;
+}
+function createFlowTickets(ctx, clock = exports.systemClock, railOf) {
+    const file = () => (0, spec_addenda_1.ticketStorePathForProject)(ctx.project);
+    const announce = (revision, message) => {
+        try {
+            ctx.ticketWatcher.notifyDesktopWrite(revision);
+        }
+        catch { /* watcher is advisory */ }
+        try {
+            ctx.broadcast(message);
+        }
+        catch { /* clients rehydrate */ }
+    };
+    return {
+        createPlaceholder(input) {
+            let created;
+            // The non-promoting path: a plain local spec write. Jira sees nothing
+            // until the Flow -> Spec rail settles (isFlowHeldTicket guards promotion).
+            const store = (0, ticket_store_1.mutateStore)(file(), (s) => {
+                const id = s.next_id++;
+                created = {
+                    id,
+                    title: input.title,
+                    description: input.description,
+                    status: 'in_progress',
+                    priority: 'medium',
+                    labels: [],
+                    assignee: null,
+                    prerequisites: [],
+                    metadata: {
+                        flow: { conversationId: input.conversationId, flowId: input.flowId, worktreeId: input.flowId, startedAt: input.startedAt, state: 'active', chosenMode: 'flow' },
+                    },
+                    // A Flow in a non-primary repository: the spec targets exactly it, so
+                    // the hand-off and every later launch run in that repository.
+                    ...(input.repositoryIds?.length ? { repositoryIds: [...input.repositoryIds] } : {}),
+                    comments: [],
+                    origin_conversation_id: null,
+                    is_epic: false,
+                    parent_epic_id: null,
+                    execution_order: null,
+                    short_summary: null,
+                    created_at: input.startedAt,
+                    updated_at: input.startedAt,
+                    created_by: 'flow',
+                    source: 'flow',
+                };
+                s.tickets[String(id)] = created;
+            });
+            announce(store.revision, { type: 'ticket_created', ticket: created, projectId: ctx.project.id, timestamp: clock.now() });
+            return created.id;
+        },
+        setFlowState(ticketId, state) {
+            let updated;
+            const store = (0, ticket_store_1.mutateStore)(file(), (s) => {
+                const ticket = s.tickets[String(ticketId)];
+                if (!ticket?.metadata?.flow || ticket.metadata.flow.state === state)
+                    return;
+                ticket.metadata.flow = { ...ticket.metadata.flow, state };
+                ticket.updated_at = clock.now();
+                updated = ticket;
+            });
+            if (updated)
+                announce(store.revision, { type: 'ticket_updated', ticket: updated, projectId: ctx.project.id, timestamp: clock.now() });
+        },
+        deletePlaceholder(ticketId) {
+            let deleted = false;
+            const store = (0, ticket_store_1.mutateStore)(file(), (s) => {
+                const ticket = s.tickets[String(ticketId)];
+                // Only a Flow placeholder is ever deleted by Flow: never the person's own spec.
+                if (!ticket?.metadata?.flow || ticket.metadata.flow.origin === 'existing')
+                    return;
+                delete s.tickets[String(ticketId)];
+                deleted = true;
+            });
+            if (deleted)
+                announce(store.revision, { type: 'ticket_deleted', ticketId, projectId: ctx.project.id, timestamp: clock.now() });
+        },
+        markDelivered(ticketId, input) {
+            let updated;
+            const store = (0, ticket_store_1.mutateStore)(file(), (s) => {
+                const ticket = s.tickets[String(ticketId)];
+                if (!ticket?.metadata?.flow)
+                    return;
+                const changeName = input.openspecChangeName ?? (typeof ticket.metadata.openspecChangeName === 'string' ? ticket.metadata.openspecChangeName : null);
+                const unchanged = ticket.metadata.flow.state === 'delivered' && ticket.metadata.openspecChangeName === (changeName ?? undefined)
+                    && ticket.status !== 'in_progress' && ticket.status !== 'todo';
+                if (unchanged)
+                    return;
+                ticket.metadata = { ...ticket.metadata, flow: { ...ticket.metadata.flow, state: 'delivered' }, ...(changeName ? { openspecChangeName: changeName } : {}) };
+                // The delivery is on review; never pull back a ticket that moved on (done, cancelled).
+                if (ticket.status === 'in_progress' || ticket.status === 'todo')
+                    ticket.status = 'on_review';
+                ticket.updated_at = clock.now();
+                updated = ticket;
+            });
+            if (updated)
+                announce(store.revision, { type: 'ticket_updated', ticket: updated, projectId: ctx.project.id, timestamp: clock.now() });
+        },
+        read(ticketId) {
+            const ticket = (0, ticket_store_1.readStore)(file()).tickets[String(ticketId)];
+            if (!ticket)
+                return null;
+            const spec = snapshotOf(ticket);
+            return { title: spec.title, description: spec.description, status: spec.status, repositoryIds: [...spec.repositoryIds], nonGoals: [...spec.nonGoals] };
+        },
+        inspectExisting(ticketId) {
+            const ticket = (0, ticket_store_1.readStore)(file()).tickets[String(ticketId)];
+            return { spec: ticket ? snapshotOf(ticket) : null, blocker: existingSpecBlocker(ticket, railOf) };
+        },
+        adoptExisting(input) {
+            let adopted;
+            let blocker = null;
+            const store = (0, ticket_store_1.mutateStore)(file(), (s) => {
+                const ticket = s.tickets[String(input.ticketId)];
+                blocker = existingSpecBlocker(ticket, railOf, input.flowId);
+                if (blocker || !ticket)
+                    return;
+                const current = ticket.metadata?.flow;
+                // Idempotent: this Flow already holds the spec.
+                if (current?.flowId === input.flowId && current.origin === 'existing') {
+                    adopted = ticket;
+                    return;
+                }
+                const previousStatus = ticket.status;
+                ticket.metadata = {
+                    ...ticket.metadata,
+                    flow: {
+                        conversationId: input.conversationId, flowId: input.flowId, worktreeId: input.flowId, startedAt: input.startedAt,
+                        state: 'active', chosenMode: 'flow', origin: 'existing', previousStatus,
+                    },
+                };
+                // The same "in progress, In Flow" a placeholder spec shows.
+                ticket.status = 'in_progress';
+                ticket.updated_at = clock.now();
+                adopted = ticket;
+            });
+            if (blocker) {
+                const reason = blocker;
+                if (reason.code === 'spec_not_found')
+                    throw new domain_1.FlowValidationError(reason.code, reason.message);
+                throw new domain_1.FlowConflictError(reason.code, reason.message);
+            }
+            announce(store.revision, { type: 'ticket_updated', ticket: adopted, projectId: ctx.project.id, timestamp: clock.now() });
+            return snapshotOf(adopted);
+        },
+        restoreExisting(ticketId, flowId) {
+            let updated;
+            const store = (0, ticket_store_1.mutateStore)(file(), (s) => {
+                const ticket = s.tickets[String(ticketId)];
+                const flow = ticket?.metadata?.flow;
+                // Only the spec THIS Flow holds; an existing spec is never deleted.
+                if (!ticket || !flow || flow.flowId !== flowId || flow.origin !== 'existing')
+                    return;
+                const { flow: _held, ...metadata } = ticket.metadata ?? {};
+                ticket.metadata = metadata;
+                // Its own status comes back unless it moved on meanwhile (done, cancelled…).
+                if (ticket.status === 'in_progress' && flow.previousStatus)
+                    ticket.status = flow.previousStatus;
+                ticket.updated_at = clock.now();
+                updated = ticket;
+            });
+            if (updated)
+                announce(store.revision, { type: 'ticket_updated', ticket: updated, projectId: ctx.project.id, timestamp: clock.now() });
+        },
+        preserveOriginal(ticketId, flowId) {
+            let updated;
+            const store = (0, ticket_store_1.mutateStore)(file(), (s) => {
+                const ticket = s.tickets[String(ticketId)];
+                const flow = ticket?.metadata?.flow;
+                if (!ticket || !flow || flow.flowId !== flowId)
+                    return;
+                const comments = Array.isArray(ticket.comments) ? ticket.comments : [];
+                // Idempotent: the original was already kept for this Flow.
+                if (typeof flow.originalCommentId === 'number' && comments.some((comment) => comment.id === flow.originalCommentId))
+                    return;
+                const id = comments.reduce((max, comment) => Math.max(max, typeof comment.id === 'number' ? comment.id : 0), 0) + 1;
+                const now = clock.now();
+                ticket.comments = [...comments, {
+                        id,
+                        body: (0, domain_1.buildOriginalSpecComment)({ title: ticket.title, description: ticket.description ?? '', nonGoals: Array.isArray(ticket.nonGoals) ? ticket.nonGoals : [], flowId }),
+                        created_at: now,
+                        created_by: 'flow',
+                    }];
+                ticket.metadata = { ...ticket.metadata, flow: { ...flow, originalCommentId: id } };
+                ticket.updated_at = now;
+                updated = ticket;
+            });
+            if (updated)
+                announce(store.revision, { type: 'ticket_updated', ticket: updated, projectId: ctx.project.id, timestamp: clock.now() });
+        },
+        applyAddenda(ticketId, flowId, causalId) {
+            // Read-only probe first: a spec without live addenda (or a replay) never rewrites the store.
+            const probe = (0, ticket_store_1.readStore)(file()).tickets[String(ticketId)];
+            if (probe?.metadata?.flow?.flowId !== flowId || !(0, spec_addenda_core_1.readSpecAddenda)(probe.addenda).some((a) => a.status === 'open' || a.status === 'in_flight'))
+                return;
+            let updated;
+            const store = (0, ticket_store_1.mutateStore)(file(), (s) => {
+                const ticket = s.tickets[String(ticketId)];
+                // Only the spec this Flow holds (the label stays through settlement).
+                if (!ticket || ticket.metadata?.flow?.flowId !== flowId)
+                    return;
+                if ((0, spec_addenda_1.applyFlowSpecAddenda)(s, ticketId, causalId, clock.now()))
+                    updated = ticket;
+            });
+            if (updated)
+                announce(store.revision, { type: 'ticket_updated', ticket: updated, projectId: ctx.project.id, timestamp: clock.now() });
+        },
+        reopen(ticketId) {
+            let updated;
+            const store = (0, ticket_store_1.mutateStore)(file(), (s) => {
+                const ticket = s.tickets[String(ticketId)];
+                if (!ticket?.metadata?.flow)
+                    return;
+                // A failed run moved the spec back to todo; Back to Flow works on it again.
+                // Never pull back a ticket that moved on (done, cancelled).
+                const status = ticket.status === 'todo' || ticket.status === 'on_review' ? 'in_progress' : ticket.status;
+                if (status === ticket.status && ticket.metadata.flow.state === 'paused')
+                    return;
+                ticket.status = status;
+                ticket.metadata = { ...ticket.metadata, flow: { ...ticket.metadata.flow, state: 'paused' } };
+                ticket.updated_at = clock.now();
+                updated = ticket;
+            });
+            if (updated)
+                announce(store.revision, { type: 'ticket_updated', ticket: updated, projectId: ctx.project.id, timestamp: clock.now() });
+        },
+    };
+}
+/** The engine choices a stopped Flow → Spec launch used (Relaunch repeats them). */
+function launchOptionsOf(raw) {
+    let config = {};
+    try {
+        const parsed = raw ? JSON.parse(raw) : null;
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+            config = parsed;
+    }
+    catch { /* defaults */ }
+    const text = (value) => typeof value === 'string' && value.trim() && value.length <= 200 ? value.trim() : undefined;
+    const loopId = text(config.loopId), aiEngine = text(config.aiEngine), model = text(config.model), reasoningEffort = text(config.reasoning_effort ?? config.reasoningEffort);
+    return { ...(loopId ? { loopId } : {}), ...(aiEngine ? { aiEngine } : {}), ...(model ? { model } : {}), ...(reasoningEffort ? { reasoningEffort } : {}) };
+}
+// ─── Worktree reservation (delivery's single machinery) ───────────────────────
+function readOverlayManifest(worktreePath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(worktreePath, worktree_overlay_1.OVERLAY_MANIFEST), 'utf8'));
+        return Array.isArray(parsed.paths) ? parsed.paths.filter((entry) => typeof entry === 'string') : [];
+    }
+    catch {
+        return [];
+    }
+}
+async function forkPoint(git, worktreePath, repo) {
+    const branch = await git.run(['symbolic-ref', '--quiet', '--short', 'HEAD'], repo);
+    if (branch.code !== 0 || !branch.stdout.trim())
+        return null;
+    const base = await git.run(['merge-base', 'HEAD', branch.stdout.trim()], worktreePath);
+    const sha = base.code === 0 ? base.stdout.trim() : '';
+    return /^[0-9a-f]{40,64}$/i.test(sha) ? sha : null;
+}
+function excludedFromDiff(file, overlay) {
+    if (file === worktree_overlay_1.OVERLAY_MANIFEST)
+        return true;
+    if (file === 'node_modules' || file.startsWith('node_modules/') || file.includes('/node_modules/'))
+        return true;
+    const roots = [...worktree_manager_1.PR_NEVER_STAGE_PATHSPEC_ROOTS, ...overlay];
+    return roots.some((root) => file === root || file.startsWith(`${root.replace(/\/$/, '')}/`));
+}
+const STATUS = { A: 'added', M: 'modified', D: 'deleted', R: 'renamed', T: 'modified', C: 'added' };
+function createFlowWorktrees(ctx, deps = { providerFor: () => 'claude' }) {
+    const git = deps.git ?? worktree_manager_1.defaultGitRunner;
+    // The Flow's repository: the project root for the primary (unchanged), or a
+    // non-primary Git member's own checkout and per-repository mount root.
+    const repositoryTarget = (repositoryId) => {
+        try {
+            return (0, isolated_worktree_1.isolatedRepositoryTarget)(ctx.project, repositoryId);
+        }
+        catch (error) {
+            throw new domain_1.FlowConflictError('flow_repository_missing', `The Flow's repository is no longer usable: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    };
+    const flowRoot = (flowId, repositoryId) => path.join(repositoryTarget(repositoryId).worktreesRoot, flowId);
+    return {
+        async reserve(input) {
+            let prepared;
+            repositoryTarget(input.repositoryId);
+            try {
+                prepared = await (deps.prepare ?? isolated_worktree_1.prepareIsolatedWorktree)({
+                    ctx: ctx,
+                    ticketId: input.ticketId,
+                    provider: deps.providerFor(input.conversationId),
+                    // The Flow id is the mount id: the worktree path is provably Flow-owned.
+                    runId: input.flowId,
+                    ...(input.repositoryId ? { repositoryId: input.repositoryId } : {}),
+                }, { git });
+            }
+            catch (error) {
+                if (error instanceof isolated_worktree_1.RepositoryHasNoCommitsError)
+                    throw new domain_1.FlowConflictError(error.code, error.message);
+                throw error;
+            }
+            // The Flow's base is the reservation SHA; never leave it unknown (a null
+            // base would measure the diff against HEAD and lose committed work).
+            return { branch: prepared.branch, worktreePath: prepared.worktreePath, baseSha: prepared.baseSha ?? prepared.initialSha, headSha: prepared.initialSha };
+        },
+        async release(input) {
+            const repo = repositoryTarget(input.repositoryId).path;
+            const root = flowRoot(input.flowId, input.repositoryId);
+            const target = input.worktreePath ?? (0, worktree_manager_1.worktreePath)(root, input.ticketId);
+            // Never remove anything outside the Flow's own mount root.
+            if (!isInside(target, root))
+                throw new Error(`Refusing to remove ${target}: it is not a Flow-owned worktree`);
+            await (0, repo_lock_1.withRepoLock)(repo, async () => {
+                const mounted = (await (0, worktree_manager_1.listWorktrees)(git, repo)).some((entry) => canonical(entry) === canonical(target));
+                let branch = input.branch;
+                if (mounted && !branch) {
+                    const head = await git.run(['rev-parse', '--abbrev-ref', 'HEAD'], target);
+                    branch = head.code === 0 && head.stdout.trim() !== 'HEAD' ? head.stdout.trim() : null;
+                }
+                if (mounted) {
+                    await (0, worktree_manager_1.removeWorktree)(git, { repoDir: repo, worktreePath: target, branch: branch ?? '', deleteBranch: Boolean(branch), force: true });
+                }
+                else if (branch) {
+                    // The mount is gone but the Flow-created branch may remain.
+                    await git.run(['branch', '-D', branch], repo).catch(() => undefined);
+                }
+                try {
+                    fs.rmSync(root, { recursive: true, force: true });
+                }
+                catch { /* best effort: empty mount root */ }
+            });
+        },
+        async freeze(input) {
+            const { path: repo, primary } = repositoryTarget(input.repositoryId);
+            return (0, repo_lock_1.withRepoLock)(repo, async () => {
+                // Same never-commit set the rail uses: overlay links and warm node_modules.
+                const sources = (0, isolated_worktree_1.resolveOverlaySources)({ slug: ctx.project.slug, baseRepo: repo, provider: deps.providerFor(input.conversationId) }, primary ? undefined : () => (0, workspace_resolution_1.resolveProjectExecution)(ctx.project));
+                const overlay = (0, worktree_overlay_1.applyWorktreeOverlay)({ worktreePath: input.worktreePath, ...sources });
+                const warm = (0, worktree_node_modules_1.linkNodeModulesIntoWorktree)(repo, input.worktreePath);
+                const excludes = [...new Set([...overlay.createdPaths, ...(warm.authenticated ?? warm.linked ?? [])])];
+                const title = ctx.getTicketSpec(input.ticketId)?.title ?? `Flow ${input.flowId}`;
+                // The Flow's own derived change (a returned Flow → Spec run left it
+                // active) is intended; any other new active change still blocks.
+                // Everything in a Flow worktree is the Flow's own work. A single active
+                // change the Flow does not know yet (an earlier Flow -> Spec run named
+                // it differently) is adopted as its derived change; several are
+                // ambiguous and still block, with a message the agent can act on.
+                const unknown = await unknownActiveChanges(git, input.worktreePath, input.baseSha, input.allowedChanges);
+                if (unknown.length > 1) {
+                    throw new domain_1.FlowConflictError('flow_freeze_failed', `This Flow has ${unknown.length} open spec changes (${unknown.join(', ')}); keep one and archive or remove the others, then hand off again`, input.flowId);
+                }
+                const adoptedChange = unknown.length === 1 && !input.allowedChanges.some((name) => fs.existsSync(path.join(input.worktreePath, 'openspec', 'changes', name))) ? unknown[0] : undefined;
+                if (unknown.length === 1 && !adoptedChange) {
+                    throw new domain_1.FlowConflictError('flow_freeze_failed', `This Flow has two open spec changes (${[...input.allowedChanges.filter((name) => fs.existsSync(path.join(input.worktreePath, 'openspec', 'changes', name))), unknown[0]].join(', ')}); keep one and archive or remove the other, then hand off again`, input.flowId);
+                }
+                const allowed = adoptedChange ? [...input.allowedChanges, adoptedChange] : input.allowedChanges;
+                const commit = await (0, worktree_manager_1.commitWorktreeAndVerify)(git, input.worktreePath, `Flow #${input.ticketId}: ${title}`, excludes, input.baseSha ?? undefined, { allowedActiveChanges: allowed });
+                if (!commit.clean) {
+                    throw new domain_1.FlowConflictError('flow_freeze_failed', `The Flow worktree could not be committed: ${commit.error ?? commit.dirty.slice(0, 5).join(', ')}`, input.flowId);
+                }
+                const headSha = await (0, isolated_worktree_1.readHeadSha)(git, input.worktreePath);
+                if (!headSha)
+                    throw new domain_1.FlowConflictError('flow_freeze_failed', 'The Flow worktree HEAD could not be verified', input.flowId);
+                return adoptedChange ? { headSha, adoptedChange } : { headSha };
+            });
+        },
+        exists(worktreePath) {
+            return fs.existsSync(path.join(worktreePath, '.git'));
+        },
+        async diff(input) {
+            const overlay = readOverlayManifest(input.worktreePath);
+            // Legacy sessions without a recorded base: the fork point from the
+            // project's checked-out branch, never HEAD (frozen commits would vanish).
+            const base = input.baseSha ?? await forkPoint(git, input.worktreePath, repositoryTarget(input.repositoryId).path) ?? 'HEAD';
+            const files = new Map();
+            const nameStatus = await git.run(['-c', 'core.quotepath=false', 'diff', '--no-renames', '--name-status', base, '--'], input.worktreePath);
+            if (nameStatus.code === 0) {
+                for (const line of nameStatus.stdout.split('\n')) {
+                    const [code, file] = line.split('\t');
+                    if (!file || excludedFromDiff(file, overlay))
+                        continue;
+                    files.set(file, { path: file, status: STATUS[code?.[0] ?? 'M'] ?? 'modified', additions: null, deletions: null });
+                }
+            }
+            const numstat = await git.run(['-c', 'core.quotepath=false', 'diff', '--no-renames', '--numstat', base, '--'], input.worktreePath);
+            if (numstat.code === 0) {
+                for (const line of numstat.stdout.split('\n')) {
+                    const [added, removed, file] = line.split('\t');
+                    const entry = file ? files.get(file) : undefined;
+                    if (!entry)
+                        continue;
+                    entry.additions = added === '-' ? null : Number(added);
+                    entry.deletions = removed === '-' ? null : Number(removed);
+                }
+            }
+            const untracked = await git.run(['-c', 'core.quotepath=false', 'ls-files', '--others', '--exclude-standard'], input.worktreePath);
+            if (untracked.code === 0) {
+                for (const file of untracked.stdout.split('\n').map((line) => line.trim()).filter(Boolean)) {
+                    if (excludedFromDiff(file, overlay) || files.has(file))
+                        continue;
+                    files.set(file, { path: file, status: 'untracked', additions: null, deletions: null });
+                }
+            }
+            const list = [...files.values()].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+            return {
+                branch: input.branch,
+                baseSha: input.baseSha,
+                headSha: await (0, isolated_worktree_1.readHeadSha)(git, input.worktreePath),
+                files: list,
+                totals: {
+                    files: list.length,
+                    additions: list.reduce((sum, file) => sum + (file.additions ?? 0), 0),
+                    deletions: list.reduce((sum, file) => sum + (file.deletions ?? 0), 0),
+                },
+            };
+        },
+    };
+}
+function createFlowPorts(deps) {
+    const { ctx, repository } = deps;
+    const clock = deps.clock ?? exports.systemClock;
+    const providerFor = (conversationId) => (0, agent_store_1.getAgentConversation)(ctx.desktopDb, conversationId)?.provider ?? ctx.project.provider ?? 'claude';
+    const host = () => {
+        const agentHost = deps.agentHost();
+        if (!agentHost)
+            throw new domain_1.FlowUnavailableError('Flow needs the mission agent chat, which is disabled');
+        return agentHost;
+    };
+    return {
+        repository,
+        // Target triage: a workspace or multi-repository project names the Git
+        // member a Flow runs in; a single repository is never triaged.
+        repositories: {
+            list: () => (0, project_repositories_1.getProjectRepositories)(ctx.project).map((member) => ({
+                id: member.id, name: member.name, isPrimary: member.isPrimary, kind: member.kind, ...(member.available === false ? { available: false } : {}),
+            })),
+        },
+        tickets: createFlowTickets(ctx, clock, railOfTicket(ctx.db)),
+        worktrees: createFlowWorktrees(ctx, { git: deps.git, providerFor }),
+        agent: {
+            async assertReady({ conversationId }) {
+                const conversation = (0, agent_store_1.getAgentConversation)(ctx.desktopDb, conversationId);
+                if (!conversation)
+                    throw new domain_1.FlowValidationError('conversation_not_found', 'The mission conversation does not exist');
+                if (conversation.pinned_project_id !== ctx.project.id) {
+                    throw new domain_1.FlowValidationError('conversation_not_pinned', 'Pin the mission to this project before starting a Flow');
+                }
+                try {
+                    await host().assertFlowSupport(conversationId);
+                }
+                catch (error) {
+                    if (error instanceof domain_1.FlowUnavailableError)
+                        throw error;
+                    throw new domain_1.FlowUnavailableError(error instanceof Error ? error.message : String(error));
+                }
+            },
+            async open({ flowId, renew }) {
+                // The Core session itself opens lazily on the first Flow turn (cwd = worktree).
+                // A resume never reuses a closed session: it gets a new generation.
+                return { coreSessionId: renew ? (0, domain_1.nextFlowCoreSessionId)(flowId, Date.now()) : (0, domain_1.flowCoreSessionId)(flowId) };
+            },
+            async close({ conversationId, coreSessionId }) {
+                const agentHost = deps.agentHost();
+                if (agentHost)
+                    await agentHost.closeFlowSession(conversationId, coreSessionId, 'flow_closed');
+            },
+            launchEngine(conversationId) {
+                const conversation = (0, agent_store_1.getAgentConversation)(ctx.desktopDb, conversationId);
+                if (!conversation?.provider || !(0, provider_selection_1.isProviderEnabled)(ctx.project, conversation.provider))
+                    return null;
+                return {
+                    aiEngine: conversation.provider,
+                    ...(conversation.model ? { model: conversation.model } : {}),
+                    ...(conversation.reasoning_effort ? { reasoningEffort: conversation.reasoning_effort } : {}),
+                };
+            },
+        },
+        rails: {
+            async launch({ flowId, conversationId, ticketId, railIndex, options, repositoryId }) {
+                const rail = (0, rails_store_1.getRail)(ctx.db, railIndex);
+                if (rail.ticketIds.length > 0 && !(rail.ticketIds.length === 1 && rail.ticketIds[0] === ticketId)) {
+                    throw new domain_1.FlowConflictError('rail_not_empty', `Rail ${railIndex} already carries other specs; pick a free rail`, flowId);
+                }
+                const base = `/projects/${encodeURIComponent(ctx.project.id)}/rails/${railIndex}`;
+                if (rail.ticketIds.length === 0) {
+                    const assigned = await deps.internalApi.call('PUT', `${base}/tickets`, { ticketIds: [ticketId] });
+                    if (!assigned.ok) {
+                        const reason = (0, internal_api_1.internalApiError)(assigned);
+                        throw new domain_1.FlowLaunchRejectedError(assigned.status, reason.error, reason.detail ?? reason.error);
+                    }
+                }
+                const launched = await deps.internalApi.call('POST', `${base}/launch`, {
+                    flowId,
+                    originSurface: 'agent-chat',
+                    originConversationId: conversationId,
+                    // Never fall back to the rail's default loop: Flow hands off to Flow -> Spec unless told otherwise.
+                    loopId: options.loopId ?? domain_1.FLOW_SPEC_LOOP_ID,
+                    // A Flow in a non-primary repository launches exactly that repository.
+                    ...(repositoryId ? { repositoryIds: [repositoryId] } : {}),
+                    ...(options.aiEngine ? { aiEngine: options.aiEngine } : {}),
+                    ...(options.model ? { model: options.model } : {}),
+                    ...(options.reasoningEffort ? { reasoning_effort: options.reasoningEffort } : {}),
+                });
+                if (!launched.ok) {
+                    const reason = (0, internal_api_1.internalApiError)(launched);
+                    throw new domain_1.FlowLaunchRejectedError(launched.status, reason.error, reason.detail ?? reason.error);
+                }
+                const body = (launched.body ?? {});
+                return {
+                    loopRunIds: Array.isArray(body.loopRunIds) ? body.loopRunIds.filter((id) => typeof id === 'string') : [],
+                    deliveryId: typeof body.prDeliveryId === 'string' ? body.prDeliveryId : null,
+                };
+            },
+            stoppedDelivery(deliveryId) {
+                const row = (0, rail_pr_store_1.getPrDelivery)(ctx.db, deliveryId);
+                if (!row)
+                    return null;
+                const derivation = (0, delivery_evidence_1.readSettleEvidence)(row.settle_evidence)?.units[0]?.runtime?.derivation ?? null;
+                const snap = (0, rail_pr_store_1.toPrDeliverySnapshot)(row);
+                return {
+                    railIndex: row.rail_index, options: launchOptionsOf(row.launch_config_json), findings: snap.flowReview ?? null,
+                    derivation: derivation ? { change: derivation.change, files: derivation.files, explained: derivation.explained, unexplainedFiles: derivation.unexplainedFiles.slice(0, domain_1.FLOW_UNEXPLAINED_FILES_CAP), unexplainedOmitted: derivation.unexplainedOmitted + Math.max(0, derivation.unexplainedFiles.length - domain_1.FLOW_UNEXPLAINED_FILES_CAP) } : null,
+                    failure: deliveryFailureOf(snap),
+                };
+            },
+            async runFailure(deliveryId) {
+                try {
+                    const row = (0, rail_pr_store_1.getPrDelivery)(ctx.db, deliveryId);
+                    const runId = row ? (0, rail_pr_store_1.toPrDeliverySnapshot)(row).runIds[0] : undefined;
+                    if (!runId)
+                        return null;
+                    // The runtime's own record: the step it stopped at and its error
+                    // (the same source the mission run card shows).
+                    const summary = await (0, agent_runtime_controls_router_1.runtimeRunSummary)(ctx, runId);
+                    if (!summary)
+                        return null;
+                    return {
+                        stepId: summary.pendingApproval?.stepId ?? summary.nextStep ?? null,
+                        cause: summary.status === 'failed' ? (0, domain_1.firstErrorLine)(summary.error) : null,
+                    };
+                }
+                catch {
+                    return null;
+                }
+            },
+            returnWorktree({ deliveryId, worktreePath, detail, commit }) {
+                try {
+                    const closed = (0, flow_worktree_return_1.returnFlowWorktree)(ctx.db, { deliveryId, worktreePath, detail }, commit);
+                    (0, flow_worktree_return_1.announceReturnedDelivery)(ctx.project.id, closed, (message) => ctx.broadcast(message));
+                }
+                catch (error) {
+                    if (error instanceof flow_worktree_return_1.FlowReturnRejectedError)
+                        throw new domain_1.FlowConflictError(error.code, error.message);
+                    throw error;
+                }
+            },
+        },
+        conversation: {
+            postReturnCard({ conversationId, flowId, deliveryId, findings, derivation, failure }) {
+                deps.agentHost()?.postSystemRow?.(conversationId, {
+                    kind: 'flow-return-briefing', flowId, deliveryId,
+                    reason: findings?.reason ?? null, score: findings?.score ?? null, summary: findings?.summary ?? null,
+                    issues: findings?.issues ?? [], issuesOmitted: findings?.issuesOmitted ?? 0, failingChecks: findings?.failingChecks ?? [],
+                    derivation,
+                    // A run that failed outright: the client localizes the step and keeps the codes as technical details.
+                    ...(!findings && failure ? { failure } : {}),
+                    at: clock.now(),
+                }, `flow-return-briefing:${deliveryId}`);
+            },
+            async startReturnTurn({ conversationId, deliveryId, failure }) {
+                await deps.agentHost()?.startAutomaticTurn?.(conversationId, failure ? exports.FLOW_FAILURE_RETURN_TURN_TEXT : exports.FLOW_RETURN_TURN_TEXT, { turnKey: `flow-return:${deliveryId}`, label: 'Back to Flow' });
+            },
+            postDeliveredSummary({ conversationId, flowId, deliveryId, ticketId, settlement }) {
+                const row = deliveryId ? (0, rail_pr_store_1.getPrDelivery)(ctx.db, deliveryId) : undefined;
+                const ticket = (0, ticket_store_1.readStore)((0, spec_addenda_1.ticketStorePathForProject)(ctx.project)).tickets[String(ticketId)];
+                const changeName = typeof ticket?.metadata?.openspecChangeName === 'string' ? ticket.metadata.openspecChangeName : null;
+                let jiraKey = null;
+                try {
+                    const link = (0, jira_db_1.getLinkByLocalId)(ctx.db, ticketId);
+                    jiraKey = link && !link.tombstoned ? link.jiraKey : null;
+                }
+                catch {
+                    jiraKey = null;
+                }
+                deps.agentHost()?.postSystemRow?.(conversationId, {
+                    kind: 'flow-delivered', flowId, deliveryId, ticketId,
+                    prUrl: row?.pr_url ?? null, prNumber: row?.pr_number ?? null,
+                    // Flow → Spec archives the change before it delivers (its `archive` step).
+                    changeName, changeArchived: Boolean(changeName),
+                    specRewrite: settlement.specRewrite, jiraCreate: settlement.jiraCreate, jiraKey,
+                    at: clock.now(),
+                }, `flow-delivered:${flowId}`);
+            },
+            postBoundary({ conversationId, flowId, event, reason, branch }) {
+                const at = clock.now();
+                deps.agentHost()?.postSystemRow?.(conversationId, {
+                    kind: 'flow-boundary', flowId, event, reason, branch, at,
+                }, `flow-boundary:${flowId}:${event}:${reason}:${at}`);
+            },
+        },
+        processes: deps.processes ?? { stop: async () => { } },
+        effects: deps.effects,
+        publication: createFlowPublication(ctx, { git: deps.git }),
+        usage: { costSoFar: (input) => (0, desktop_db_1.sumFlowInvocations)(ctx.desktopDb, input) },
+        notifier: {
+            changed(session) {
+                try {
+                    ctx.broadcast({ type: 'flow.state', projectId: ctx.project.id, conversationId: session.conversationId, flowId: session.id, flow: session, timestamp: clock.now() });
+                }
+                catch { /* clients rehydrate through GET */ }
+            },
+        },
+        clock,
+        ids: ids_1.newId,
+        availability: deps.availability,
+    };
+}
+/**
+ * The rails launch route's view of Flow (delivery never imports this module).
+ * `adopt` and `release` run inside delivery's SQLite transaction on the same
+ * project connection, so the ownership transfer is atomic.
+ */
+function createFlowHandOffAuthority(repository, clock = exports.systemClock, onChanged, summarize) {
+    return {
+        resolve(flowId) {
+            const session = repository.get(flowId);
+            if (!session || session.step !== 'handoff:launch' || !session.worktreePath || !session.branch || !session.headSha || session.ticketId === null) {
+                throw new flow_worktree_handoff_1.FlowHandOffNotReadyError('This Flow is not waiting for a rail launch; end it from the Flow bar');
+            }
+            return {
+                flowId,
+                ticketId: session.ticketId,
+                conversationId: session.conversationId,
+                ...(session.repositoryId ? { repositoryId: session.repositoryId } : {}),
+                branch: session.branch,
+                worktreePath: session.worktreePath,
+                headSha: session.headSha,
+                baseSha: session.baseSha,
+                // A re-derivation updates the Flow's own change in place (null ⇒ named after the spec).
+                changeId: (0, domain_1.currentDerivedChange)(session),
+                // A summary failure never blocks the hand-off: Core derives from the diff alone.
+                summary: (() => { try {
+                    return summarize?.(session) ?? '';
+                }
+                catch {
+                    return '';
+                } })(),
+                adopt(adoption) {
+                    const current = repository.get(flowId);
+                    if (!current)
+                        throw new flow_worktree_handoff_1.FlowHandOffNotReadyError('The Flow disappeared during the hand-off');
+                    repository.save((0, domain_1.transition)(current, { type: 'handed-off', railIndex: adoption.railIndex, deliveryId: adoption.deliveryId, headSha: adoption.headSha, now: clock.now() }).session);
+                    // Announce the hand-off as soon as the delivery's transaction commits,
+                    // so the hand-off card gives way to the run card that appears with it
+                    // instead of waiting for the rest of the launch.
+                    setImmediate(() => {
+                        // Best effort: the connection may be gone (project closed) by then.
+                        try {
+                            const adopted = repository.get(flowId);
+                            if (adopted?.state === 'handed_off' && adopted.deliveryId === adoption.deliveryId)
+                                onChanged?.(adopted);
+                        }
+                        catch { /* clients rehydrate through GET */ }
+                    });
+                },
+                release() {
+                    const current = repository.get(flowId);
+                    if (!current)
+                        return;
+                    const reverted = (0, domain_1.transition)(current, { type: 'adoption-reverted', now: clock.now() }).session;
+                    repository.save(reverted);
+                    onChanged?.(reverted);
+                },
+            };
+        },
+    };
+}
+/** The turn of an active Flow with a session (null otherwise). */
+function toFlowTurn(session) {
+    if (!session || session.state !== 'active' || session.step !== null || !session.worktreePath || !session.coreSessionId)
+        return null;
+    return {
+        flowId: session.id,
+        cwd: session.worktreePath,
+        branch: session.branch,
+        coreSessionId: session.coreSessionId,
+        systemPrompt: (0, agent_flow_prompt_1.buildFlowSystemPrompt)(),
+        policy: flow_turn_context_1.FLOW_SESSION_BOUNDARY,
+        ...(session.returnBriefing ? { briefing: session.returnBriefing } : {}),
+    };
+}
+/**
+ * Missions' FlowTurnContext, bound app-wide: a conversation is in Flow while
+ * the Flow of its pinned project is `active` with an open session.
+ */
+function createFlowTurnContext(deps) {
+    return {
+        async offerable(conversationId) {
+            const projectId = deps.conversationProject(conversationId);
+            if (!projectId || !deps.availability)
+                return false;
+            const service = deps.flowServiceFor(projectId);
+            if (!service)
+                return false;
+            const open = service.getByConversation(conversationId);
+            if (open && (open.state === 'active' || open.state === 'paused'))
+                return false;
+            return (await deps.availability()).available;
+        },
+        forConversation(conversationId) {
+            const projectId = deps.conversationProject(conversationId);
+            if (!projectId)
+                return null;
+            return toFlowTurn(deps.flowServiceFor(projectId)?.getByConversation(conversationId) ?? null);
+        },
+        async renewSession(conversationId, flowId) {
+            const projectId = deps.conversationProject(conversationId);
+            const service = projectId ? deps.flowServiceFor(projectId) : null;
+            if (!service?.renewSession)
+                return null;
+            return toFlowTurn(await service.renewSession(flowId));
+        },
+        async briefingDelivered(conversationId, flowId) {
+            const projectId = deps.conversationProject(conversationId);
+            if (!projectId)
+                return;
+            await deps.flowServiceFor(projectId)?.briefingDelivered?.(flowId);
+        },
+    };
+}
+// ─── Settlement publication (arch section 4.6) ───────────────────────────────
+/** Decisions that mean the delivery reached review (or went beyond it). */
+const DELIVERED_DECISIONS = new Set(['on_review', 'pr_draft', 'pr_ready', 'completed', 'merged']);
+const ARCHIVED_CHANGE = /^openspec\/changes\/archive\/([^/]+)\/(proposal|design)\.md$/;
+const ACTIVE_CHANGE = /^openspec\/changes\/(?!archive\/)([^/]+)\/(proposal|design)\.md$/;
+const TEXT_CAP = 64 * 1024;
+/**
+ * The bounded summary of a Flow conversation: the person's messages since the
+ * Flow started (automatic briefings excluded), the first line of each final
+ * agent reply and the recorded decisions. Message times (SQLite) and Flow times
+ * (ISO) are compared as instants, never as strings.
+ */
+function flowConversationSummary(desktopDb, input) {
+    const messages = (0, agent_store_1.listAgentMessages)(desktopDb, input.conversationId)
+        .filter((message) => (0, domain_1.inFlowWindow)(message.created_at, input.from, input.to))
+        .map((message) => ({
+        role: message.role,
+        content: message.content,
+        ...(message.context_refs.some((ref) => ref.kind === agent_failure_briefing_1.FAILURE_BRIEFING_REF_KIND) ? { automated: true } : {}),
+    }));
+    return (0, domain_1.buildFlowSummary)({ idea: input.idea, messages });
+}
+/** Strip OpenSpec's `YYYY-MM-DD-` archive prefix. */
+function changeNameFromArchive(directory) {
+    return directory.replace(/^\d{4}-\d{2}-\d{2}-/, '');
+}
+/**
+ * Read the derived OpenSpec change from the delivered commit: the archived
+ * (or still active) change directory the run added since the Flow base, its
+ * proposal and design, and a bounded diffstat. Pure Git reads; never mutates.
+ */
+async function readDerivedChange(git, repo, input) {
+    const base = input.baseSha ?? `${input.ref}~1`;
+    const added = await git.run(['-c', 'core.quotepath=false', 'diff', '--name-only', '--diff-filter=A', base, input.ref, '--', 'openspec/changes'], repo);
+    if (added.code !== 0)
+        throw new Error(`git diff failed: ${added.stderr.trim() || added.code}`);
+    const candidates = added.stdout.split('\n').map((line) => line.trim()).filter(Boolean);
+    const directories = new Map();
+    for (const file of candidates) {
+        const archived = ARCHIVED_CHANGE.exec(file);
+        const active = archived ? null : ACTIVE_CHANGE.exec(file);
+        const match = archived ?? active;
+        if (!match)
+            continue;
+        const dir = file.slice(0, file.lastIndexOf('/'));
+        const entry = directories.get(dir) ?? { name: archived ? changeNameFromArchive(match[1]) : match[1], files: new Map() };
+        entry.files.set(match[2], file);
+        directories.set(dir, entry);
+    }
+    const ranked = [...directories.entries()].sort(([a], [b]) => Number(b.includes('/archive/')) - Number(a.includes('/archive/')));
+    const chosen = ranked.find(([, entry]) => input.changeName && entry.name === input.changeName) ?? ranked[0];
+    const show = async (file) => {
+        if (!file)
+            return null;
+        const result = await git.run(['show', `${input.ref}:${file}`], repo);
+        return result.code === 0 ? result.stdout.slice(0, TEXT_CAP) : null;
+    };
+    const stat = await git.run(['diff', '--stat=120', base, input.ref, '--'], repo);
+    return {
+        changeName: chosen?.[1].name ?? input.changeName,
+        proposal: await show(chosen?.[1].files.get('proposal')),
+        design: await show(chosen?.[1].files.get('design')),
+        diffstat: stat.code === 0 ? stat.stdout.slice(0, 8000) : null,
+    };
+}
+function createFlowPublication(ctx, deps = {}) {
+    const git = deps.git ?? worktree_manager_1.defaultGitRunner;
+    const ticketFile = () => (0, spec_addenda_1.ticketStorePathForProject)(ctx.project);
+    const readTicket = (ticketId) => (0, ticket_store_1.readStore)(ticketFile()).tickets[String(ticketId)];
+    return {
+        deliveryState(deliveryId) {
+            const row = (0, rail_pr_store_1.getPrDelivery)(ctx.db, deliveryId);
+            if (!row)
+                return null;
+            const delivered = DELIVERED_DECISIONS.has(row.decision) && row.implementation_outcome === 'succeeded';
+            return { delivered, crashed: !delivered && isCrashedFlowDelivery((0, rail_pr_store_1.toPrDeliverySnapshot)(row)) };
+        },
+        async derivedChange(input) {
+            const row = input.deliveryId ? (0, rail_pr_store_1.getPrDelivery)(ctx.db, input.deliveryId) : undefined;
+            let units = [];
+            try {
+                units = row ? JSON.parse(row.branches) : [];
+            }
+            catch {
+                units = [];
+            }
+            const unit = units.find((entry) => entry.ticketId === input.ticketId) ?? units[0];
+            const ref = unit?.finalSha ?? unit?.branch ?? row?.branch ?? input.branch;
+            if (!ref)
+                throw new Error('The delivered branch of this Flow is unknown');
+            const metadata = readTicket(input.ticketId)?.metadata;
+            const changeName = typeof metadata?.openspecChangeName === 'string' ? metadata.openspecChangeName : null;
+            // The delivered branch lives in the Flow's repository (the project root for the primary).
+            const repo = input.repositoryId ? (0, project_repositories_1.getProjectRepositories)(ctx.project).find((member) => member.id === input.repositoryId)?.path : ctx.project.path;
+            if (!repo)
+                throw new Error(`The Flow's repository ${input.repositoryId} is no longer registered`);
+            return readDerivedChange(git, repo, { ref, baseSha: input.baseSha, changeName });
+        },
+        conversationSummary(input) {
+            return flowConversationSummary(ctx.desktopDb, { conversationId: input.conversationId, idea: readTicket(input.ticketId)?.description ?? null, from: input.from, to: input.to });
+        },
+        async rewriteSpec({ ticketId, text }) {
+            const provider = (ctx.project.provider ?? 'claude');
+            const scope = { specrails: false, openspec: false, full: false, mcp: false, contractRefine: true, userMcp: false };
+            if (!(0, spec_generation_1.resolveSpecGenerationToolPolicy)(provider, scope))
+                return { ok: false, error: `Provider ${provider} cannot run spec generation` };
+            const model = (0, project_router_helpers_1.resolveDefaultSpecModel)({ projectPath: ctx.project.path, slug: ctx.project.slug, provider });
+            const outcome = await (deps.generate ?? spec_generation_1.generateSpecFromText)({
+                db: ctx.db,
+                project: ctx.project,
+                ticketStorePath: ticketFile(),
+                ticketWatcher: ctx.ticketWatcher,
+                broadcast: ctx.broadcast,
+                admission: (0, process_admission_1.captureProcessAdmission)(ctx.project.id),
+            }, {
+                text, provider, model, scope, ticketId, surface: 'flow',
+                // Contract Layer always (feedback-2026-10 decision 6.2), awaited so the
+                // Jira issue that follows is born with the complete spec.
+                contractRefine: (0, runtime_1.supportsContractRefine)((0, providers_1.getAdapter)(provider)) ? { model: null, await: true } : null,
+                hooks: {
+                    onPersisted: (ticket) => {
+                        try {
+                            ctx.broadcast({ type: 'ticket_updated', ticket: ticket, projectId: ctx.project.id, timestamp: new Date().toISOString() });
+                        }
+                        catch { /* clients rehydrate */ }
+                    },
+                },
+            });
+            return outcome.ok ? { ok: true } : { ok: false, error: outcome.error };
+        },
+        jira: {
+            connected: () => { try {
+                return ctx.jiraSyncManager.isActive();
+            }
+            catch {
+                return false;
+            } },
+            enqueueCreate: (ticketId, key) => ctx.jiraSyncManager.enqueuePromote(ticketId, key),
+            enqueueUpdate: (ticketId, key) => ctx.jiraSyncManager.enqueueSpecUpdate(ticketId, key),
+            linked: (ticketId) => { try {
+                const link = (0, jira_db_1.getLinkByLocalId)(ctx.db, ticketId);
+                return Boolean(link && !link.tombstoned);
+            }
+            catch {
+                return false;
+            } },
+            enqueueReview: (ticketId, refId) => ctx.jiraSyncManager.onRailReview([ticketId], refId),
+        },
+    };
+}
+/** Periodic retry of due settlement effects (backoff lives in the rows). */
+function startFlowSettlementScheduler(service, intervalMs = 30_000) {
+    let running = false;
+    const timer = setInterval(() => {
+        if (running)
+            return;
+        running = true;
+        void service.runDueSettlements().catch(() => undefined).finally(() => { running = false; });
+    }, intervalMs);
+    timer.unref?.();
+    return { stop: () => clearInterval(timer) };
+}
+/** Active OpenSpec changes in the worktree that are neither in the base commit nor already the Flow's. */
+async function unknownActiveChanges(git, worktreePath, baseSha, known) {
+    let names;
+    try {
+        names = fs.readdirSync(path.join(worktreePath, 'openspec', 'changes'), { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && entry.name !== 'archive' && (0, domain_1.isOpenSpecChangeId)(entry.name))
+            .map((entry) => entry.name);
+    }
+    catch {
+        return [];
+    }
+    if (!names.length)
+        return [];
+    const baseline = new Set();
+    if (baseSha) {
+        const listed = await git.run(['ls-tree', '-d', '--name-only', `${baseSha}:openspec/changes`], worktreePath).catch(() => null);
+        if (listed?.code === 0)
+            for (const name of listed.stdout.split('\n'))
+                if (name.trim())
+                    baseline.add(name.trim());
+    }
+    return names.filter((name) => !baseline.has(name) && !known.includes(name));
+}