specrails-desktop 2.64.2 → 2.65.0

package/server/dist/modules/delivery/adapters/decisions/local-changes.js

@@ -0,0 +1,427 @@
+"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.localChangesBody = localChangesBody;
+exports.buildLocalChangesBriefing = buildLocalChangesBriefing;
+exports.briefAgentOnLocalChanges = briefAgentOnLocalChanges;
+exports.waitForLocalRestores = waitForLocalRestores;
+exports.startLocalRestoreBranch = startLocalRestoreBranch;
+exports.handleConflictingRestore = handleConflictingRestore;
+exports.runBringBackLocalChanges = runBringBackLocalChanges;
+exports.runDiscardRestoreBranch = runDiscardRestoreBranch;
+exports.runRestoreLocalChanges = runRestoreLocalChanges;
+exports.recoverLocalStashes = recoverLocalStashes;
+/**
+ * The person's uncommitted work saved by "Integrate locally"
+ * (proactive-local-integration): the response body, the server-side
+ * restoration of a conflicting stash on its own branch + worktree (never
+ * delegated to the read-only mission agent, which is only informed), the
+ * "Restore my changes" / "Bring them back" / "Discard the restored branch"
+ * actions and startup recovery.
+ *
+ * Every effect runs under the repository lock and refuses while a decision
+ * lease is held, so it never interleaves with another delivery operation.
+ */
+const repo_lock_1 = require("../../../../repo-lock");
+const agent_chat_registry_1 = require("../../../missions/runtime/agent-chat-registry");
+const rail_pr_store_1 = require("../../runtime/rail-pr-store");
+const local_stash_1 = require("../../runtime/local-stash");
+const local_restore_branch_1 = require("../../runtime/local-restore-branch");
+const metadata_1 = require("./metadata");
+const transitions_1 = require("./transitions");
+/** What the decision response tells the surfaces about the saved work. */
+function localChangesBody(record) {
+    const restore = record.restore ? (({ worktreePath: _worktreePath, ...wire }) => wire)(record.restore) : null;
+    return {
+        state: record.state,
+        stashName: record.name,
+        stashSha: record.sha,
+        branch: record.branch,
+        restoreBranch: record.restoreBranch,
+        conflictPaths: record.conflictPaths,
+        ...(restore ? { restore } : {}),
+    };
+}
+/**
+ * The automatic turn's text (agent-facing, English like every briefing).
+ * Mission agents are read-only: this only REPORTS what happened and what
+ * Specrails is doing — it never asks the agent to write, apply or commit.
+ */
+function buildLocalChangesBriefing(input) {
+    const { record } = input;
+    const restoreBranch = record.restoreBranch ?? (0, local_stash_1.restoreBranchName)(record.sha);
+    const tickets = input.ticketIds.length > 0 ? input.ticketIds.map((id) => `#${id}`).join(', ') : 'this delivery';
+    const files = record.conflictPaths.length > 0 ? record.conflictPaths.map((p) => `- ${p}`).join('\n') : '- (git reported no unmerged path)';
+    return [
+        `[Specrails] Status report — no action needed from you. Integrated ${tickets} into \`${input.branch}\` locally (delivery ${input.deliveryId}).`,
+        `The person's uncommitted changes on \`${input.branch}\` were saved as a git stash before integrating ("${record.name}"). Re-applying them on top of the integrated result conflicted, so \`${input.branch}\` was left exactly as integrated and the stash is kept safe. Conflicting files:`,
+        files,
+        '',
+        `Specrails itself is restoring those changes on the new branch \`${restoreBranch}\` in its own separate worktree and resolving the conflicts there. Nothing touches \`${input.branch}\` until the person clicks "Bring them back" on the delivery card, which also shows the restored files for review.`,
+        'Report this status to the person in one or two sentences. You are read-only here: do not run git commands, do not suggest shell commands, and never suggest dropping, popping or clearing the stash.',
+    ].join('\n');
+}
+function originConversation(deps, row) {
+    if (row.origin_conversation_id)
+        return row.origin_conversation_id;
+    if (row.parent_delivery_id)
+        return (0, rail_pr_store_1.getPrDelivery)(deps.db, row.parent_delivery_id)?.origin_conversation_id ?? null;
+    return null;
+}
+/** Hand a conflicting restore to the delivery's origin mission agent. One turn
+ * per delivery (durable turn key); fire-and-forget, never throws. */
+function briefAgentOnLocalChanges(deps, row, record, branch) {
+    try {
+        const conversationId = originConversation(deps, row);
+        if (!conversationId)
+            return;
+        const agent = (deps.missionAgent ?? agent_chat_registry_1.getAgentChatManager)();
+        if (!agent)
+            return;
+        const text = buildLocalChangesBriefing({ deliveryId: row.id, ticketIds: (0, rail_pr_store_1.toPrDeliverySnapshot)(row).ticketIds, record, branch });
+        void agent.startAutomaticTurn(conversationId, text, { turnKey: `local-changes:${row.id}`, label: 'Restore local changes' })
+            .catch((err) => console.error('[safe-pr] local-changes briefing failed:', err));
+    }
+    catch (err) {
+        console.error('[safe-pr] local-changes briefing failed:', err);
+    }
+}
+function broadcastDelivery(deps, row) {
+    try {
+        (0, transitions_1.finalizeTransition)(deps, row.parent_delivery_id ?? row.id);
+    }
+    catch { /* the durable row stays authoritative */ }
+}
+/** Persist one restore attempt; leaves `local_changes_attention` once nothing is held. */
+function persistRestore(deps, row, next) {
+    const settled = next.state === 'restored' || next.state === 'released';
+    const warnings = (0, rail_pr_store_1.toPrDeliverySnapshot)(row).cleanupWarnings;
+    (0, rail_pr_store_1.setPrDeliveryLocalStash)(deps.db, row.id, next, settled
+        ? { from: 'local_changes_attention', to: warnings.length > 0 ? 'cleanup_incomplete' : 'merged' }
+        : next.state === 'needs_attention' && row.decision === 'merged'
+            ? { from: 'merged', to: 'local_changes_attention' }
+            : undefined);
+}
+/** In-flight server-side restorations (tests and shutdown can await them). */
+const inFlightRestores = new Set();
+/** Resolve once every in-flight branch restoration has settled. */
+async function waitForLocalRestores() {
+    while (inFlightRestores.size > 0)
+        await Promise.allSettled([...inFlightRestores]);
+}
+function restoreRoot(deps) {
+    return deps.assemblyRoot ?? (0, metadata_1.batchWorktreeRoot)(deps.project.slug);
+}
+/** Fold a restore-branch change into the record and persist it (lease-independent). */
+function saveRestore(deps, rowId, restore) {
+    const row = (0, rail_pr_store_1.getPrDelivery)(deps.db, rowId);
+    const current = row ? (0, rail_pr_store_1.readLocalStash)(row.local_stash) : null;
+    if (!row || !current)
+        return null;
+    const next = { ...current, restoreBranch: restore.branch, restore, updatedAt: restore.updatedAt };
+    (0, rail_pr_store_1.setPrDeliveryLocalStash)(deps.db, row.id, next);
+    broadcastDelivery(deps, row);
+    return next;
+}
+function restoreRecord(base) {
+    return {
+        worktreePath: '', baseSha: null, commitSha: null, resolvedBy: null, managedPaths: [], conflictPaths: [], files: [], detail: null,
+        ...base, updatedAt: new Date().toISOString(),
+    };
+}
+async function resolveWith(deps) {
+    if (deps.localRestoreResolver)
+        return deps.localRestoreResolver;
+    // Lazy: the AI executor stack loads only when a restore actually conflicts.
+    const { defaultLocalRestoreResolver } = await Promise.resolve().then(() => __importStar(require('../../runtime/local-restore-resolver')));
+    return defaultLocalRestoreResolver;
+}
+/**
+ * Restore a conflicting stash server-side: new branch + worktree from the
+ * integrated target, `git stash apply` there, managed files take the
+ * integrated version, a clean result is committed at once; otherwise the
+ * write-capable resolver runs confined to that worktree (outside the
+ * repository lock) and Specrails verifies + commits. The target branch and
+ * the stash are never touched. Fire-and-forget; never throws.
+ */
+function startLocalRestoreBranch(deps, rowId) {
+    const run = runLocalRestoreBranch(deps, rowId).catch((err) => {
+        console.error('[safe-pr] local-changes branch restore failed:', err);
+    });
+    inFlightRestores.add(run);
+    void run.finally(() => inFlightRestores.delete(run));
+    return run;
+}
+async function runLocalRestoreBranch(deps, rowId) {
+    const initial = (0, rail_pr_store_1.getPrDelivery)(deps.db, rowId);
+    if (!initial)
+        return;
+    const lockPath = initial.repository_path ?? deps.project.path;
+    const job = await (0, repo_lock_1.withRepoLock)(lockPath, async () => {
+        const row = (0, rail_pr_store_1.getPrDelivery)(deps.db, rowId);
+        const record = row ? (0, rail_pr_store_1.readLocalStash)(row.local_stash) : null;
+        if (!row || !record || record.state !== 'needs_attention')
+            return null;
+        const existing = record.restore;
+        if (existing && (existing.status === 'resolving' || existing.status === 'ready'))
+            return null;
+        const repo = record.checkoutPath;
+        if (existing?.status === 'failed') {
+            // A failed attempt is Specrails' own scratch branch; the stash still
+            // holds the person's work, so a retry starts from a clean slate.
+            await (0, local_restore_branch_1.removeRestoreBranch)(deps.git, repo, existing.worktreePath, existing.branch, true);
+        }
+        const ticketIds = (0, rail_pr_store_1.toPrDeliverySnapshot)(row).ticketIds;
+        const message = (0, local_restore_branch_1.restoreCommitMessage)(ticketIds);
+        const prepared = await (0, local_restore_branch_1.prepareRestoreBranch)(deps.git, {
+            repo, sha: record.sha, targetBranch: record.branch, worktreesRoot: restoreRoot(deps), ticketId: ticketIds[0] ?? 0,
+        });
+        if (!prepared.ok) {
+            saveRestore(deps, row.id, restoreRecord({ status: 'failed', branch: prepared.branch, worktreePath: prepared.worktreePath ?? '', detail: prepared.detail }));
+            return null;
+        }
+        const base = { branch: prepared.branch, worktreePath: prepared.worktreePath, baseSha: prepared.baseSha, managedPaths: prepared.managedPaths, conflictPaths: prepared.conflictPaths };
+        if (prepared.conflictPaths.length === 0) {
+            // It applied cleanly on the integrated tree (or only managed files
+            // conflicted): commit now, no resolver needed.
+            const committed = await (0, local_restore_branch_1.commitRestoreBranch)(deps.git, { ...base, message });
+            saveRestore(deps, row.id, committed.ok
+                ? restoreRecord({ ...base, status: 'ready', resolvedBy: 'clean', commitSha: committed.commitSha, files: committed.files })
+                : restoreRecord({ ...base, status: 'failed', detail: committed.detail, conflictPaths: committed.conflictPaths ?? [] }));
+            return null;
+        }
+        saveRestore(deps, row.id, restoreRecord({ ...base, status: 'resolving' }));
+        return { ...base, targetBranch: record.branch, stashName: record.name, message };
+    });
+    if (!job)
+        return;
+    let resolverError = null;
+    try {
+        const resolver = await resolveWith(deps);
+        await resolver({ worktreePath: job.worktreePath, branch: job.branch, targetBranch: job.targetBranch, conflictPaths: job.conflictPaths, stashName: job.stashName });
+    }
+    catch (err) {
+        resolverError = err instanceof Error ? err.message : String(err);
+    }
+    await (0, repo_lock_1.withRepoLock)(lockPath, async () => {
+        const row = (0, rail_pr_store_1.getPrDelivery)(deps.db, rowId);
+        const record = row ? (0, rail_pr_store_1.readLocalStash)(row.local_stash) : null;
+        // Discarded / restarted meanwhile: that newer state wins.
+        if (!row || !record?.restore || record.restore.status !== 'resolving' || record.restore.branch !== job.branch)
+            return;
+        const base = { branch: job.branch, worktreePath: job.worktreePath, baseSha: job.baseSha, managedPaths: job.managedPaths, conflictPaths: job.conflictPaths };
+        const committed = await (0, local_restore_branch_1.commitRestoreBranch)(deps.git, { ...base, message: job.message });
+        saveRestore(deps, row.id, committed.ok
+            ? restoreRecord({ ...base, status: 'ready', resolvedBy: 'resolver', commitSha: committed.commitSha, files: committed.files })
+            : restoreRecord({
+                ...base, status: 'failed',
+                conflictPaths: committed.conflictPaths ?? job.conflictPaths,
+                detail: resolverError ? `The conflict resolver failed: ${resolverError}` : committed.detail,
+            }));
+    });
+}
+/** A conflicting restore: inform the mission (report only) and restore server-side. */
+function handleConflictingRestore(deps, row, record, branch) {
+    briefAgentOnLocalChanges(deps, row, record, branch);
+    void startLocalRestoreBranch(deps, row.id);
+}
+async function underDeliveryLock(deps, prDeliveryId, fn) {
+    const initial = (0, rail_pr_store_1.getPrDelivery)(deps.db, prDeliveryId);
+    if (!initial)
+        return { status: 404, body: { error: 'Unknown prDeliveryId' } };
+    return (0, repo_lock_1.withRepoLock)(initial.repository_path ?? deps.project.path, async () => {
+        deps.assertAdmission?.();
+        const row = (0, rail_pr_store_1.getPrDelivery)(deps.db, prDeliveryId);
+        if (!row)
+            return { status: 404, body: { error: 'Unknown prDeliveryId' } };
+        const parent = row.parent_delivery_id ? (0, rail_pr_store_1.getPrDelivery)(deps.db, row.parent_delivery_id) : null;
+        if (row.operation_token || parent?.operation_token) {
+            return { status: 409, body: { error: 'operation_in_progress', current: row.decision, operation: row.operation ?? parent?.operation ?? null } };
+        }
+        const record = (0, rail_pr_store_1.readLocalStash)(row.local_stash);
+        if (!record)
+            return { status: 404, body: { error: 'no_local_changes' } };
+        return fn(row, record);
+    });
+}
+/**
+ * "Bring them back to <target>": fast-forward the person's checkout to the
+ * reviewed restore commit (merging a moved target into the restore branch
+ * first, in its worktree), then drop the stash — the person confirmed — and
+ * remove the restore worktree/branch.
+ */
+async function runBringBackLocalChanges(deps, prDeliveryId) {
+    return underDeliveryLock(deps, prDeliveryId, async (row, record) => {
+        const restore = record.restore;
+        if (restore?.status === 'brought_back')
+            return { status: 200, body: { ok: true, localChanges: localChangesBody(record) } };
+        if (!restore || restore.status !== 'ready' || !restore.commitSha) {
+            return { status: 409, body: { error: 'restore_not_ready', localChanges: localChangesBody(record) } };
+        }
+        const result = await (0, local_restore_branch_1.bringBackRestoreBranch)(deps.git, {
+            checkout: record.checkoutPath, repo: record.checkoutPath, targetBranch: record.branch,
+            branch: restore.branch, worktreePath: restore.worktreePath, commitSha: restore.commitSha,
+        });
+        if (!result.ok) {
+            return {
+                status: 409,
+                body: { error: 'local_restore_blocked', reason: result.reason, detail: result.detail, current: result.current ?? null, base: record.branch, localChanges: localChangesBody(record) },
+            };
+        }
+        const warnings = [...result.warnings];
+        const dropped = await (0, local_stash_1.dropBySha)(deps.git, record.checkoutPath, record.sha);
+        if (dropped)
+            warnings.push(dropped);
+        const at = new Date().toISOString();
+        const next = { ...record, state: 'restored', restore: { ...restore, status: 'brought_back', commitSha: result.commitSha, updatedAt: at }, updatedAt: at };
+        persistRestore(deps, row, next);
+        broadcastDelivery(deps, row);
+        return { status: 200, body: { ok: true, localChanges: localChangesBody(next), ...(warnings.length > 0 ? { warnings } : {}) } };
+    });
+}
+/** "Discard the restored branch": remove the restore worktree + branch. The stash is KEPT. */
+async function runDiscardRestoreBranch(deps, prDeliveryId) {
+    return underDeliveryLock(deps, prDeliveryId, async (row, record) => {
+        const restore = record.restore;
+        if (!restore || restore.status === 'discarded' || restore.status === 'brought_back') {
+            return { status: 200, body: { ok: true, localChanges: localChangesBody(record) } };
+        }
+        if (restore.status === 'resolving') {
+            return { status: 409, body: { error: 'restore_in_progress', localChanges: localChangesBody(record) } };
+        }
+        const warnings = await (0, local_restore_branch_1.removeRestoreBranch)(deps.git, record.checkoutPath, restore.worktreePath, restore.branch, true);
+        const next = saveRestore(deps, row.id, { ...restore, status: 'discarded', updatedAt: new Date().toISOString() }) ?? record;
+        return { status: 200, body: { ok: true, localChanges: localChangesBody(next), ...(warnings.length > 0 ? { warnings } : {}) } };
+    });
+}
+/**
+ * "Restore my changes": re-attempt applying the recorded stash. A clean apply
+ * drops it; a conflict restores the integrated tree again and keeps it.
+ */
+async function runRestoreLocalChanges(deps, prDeliveryId) {
+    return underDeliveryLock(deps, prDeliveryId, async (row, record) => {
+        if (record.state === 'restored' || record.state === 'released') {
+            return { status: 200, body: { ok: true, localChanges: localChangesBody(record) } };
+        }
+        const result = await (0, local_stash_1.restoreLocalChanges)(deps.git, record);
+        const next = (0, local_stash_1.recordAfterRestore)(record, result);
+        persistRestore(deps, row, next);
+        broadcastDelivery(deps, row);
+        if (result.state === 'blocked') {
+            return {
+                status: 409,
+                body: { error: 'local_restore_blocked', reason: result.reason, detail: result.detail, current: result.current ?? null, base: record.branch, localChanges: localChangesBody(next) },
+            };
+        }
+        // Still conflicting: Specrails restores it on its own branch (idempotent
+        // while one is resolving or ready for review).
+        if (next.state === 'needs_attention')
+            void startLocalRestoreBranch(deps, row.id);
+        return { status: 200, body: { ok: true, localChanges: localChangesBody(next), ...(result.warnings.length > 0 ? { warnings: result.warnings } : {}) } };
+    });
+}
+/**
+ * Startup recovery (admission still closed, leases already cleared): every
+ * `saved` stash is re-applied; a Specrails stash whose record never landed
+ * (crash between `git stash push` and the write) is adopted from its message
+ * first. Conflicts follow the same keep-the-stash path: the mission is informed and
+ * Specrails restores the stash on its own branch.
+ * Returns the delivery ids it touched. Never throws.
+ */
+async function recoverLocalStashes(deps) {
+    const touched = [];
+    try {
+        const repos = new Set([deps.project.path]);
+        for (const row of (0, rail_pr_store_1.listPrDeliveriesWithLocalStash)(deps.db)) {
+            const record = (0, rail_pr_store_1.readLocalStash)(row.local_stash);
+            if (record?.checkoutPath)
+                repos.add(record.checkoutPath);
+        }
+        // Adopt orphaned Specrails stashes (message carries the delivery id).
+        for (const repo of repos) {
+            for (const found of await (0, local_stash_1.findSpecrailsStashes)(deps.git, repo)) {
+                const row = (0, rail_pr_store_1.getPrDelivery)(deps.db, found.deliveryId);
+                if (!row || (0, rail_pr_store_1.readLocalStash)(row.local_stash) || !found.branch)
+                    continue;
+                const at = new Date().toISOString();
+                (0, rail_pr_store_1.setPrDeliveryLocalStash)(deps.db, row.id, {
+                    sha: found.sha, name: found.name, checkoutPath: repo, branch: found.branch, state: 'saved',
+                    restoreBranch: null, conflictPaths: [], savedAt: at, updatedAt: at,
+                });
+            }
+        }
+        for (const candidate of (0, rail_pr_store_1.listPrDeliveriesWithLocalStash)(deps.db)) {
+            const record = (0, rail_pr_store_1.readLocalStash)(candidate.local_stash);
+            if (!record || record.state !== 'saved')
+                continue;
+            await (0, repo_lock_1.withRepoLock)(candidate.repository_path ?? deps.project.path, async () => {
+                const row = (0, rail_pr_store_1.getPrDelivery)(deps.db, candidate.id);
+                const current = row ? (0, rail_pr_store_1.readLocalStash)(row.local_stash) : null;
+                if (!row || !current || current.state !== 'saved' || row.operation_token)
+                    return;
+                const result = await (0, local_stash_1.restoreLocalChanges)(deps.git, current);
+                if (result.state === 'blocked') {
+                    console.warn(`[safe-pr] local changes of ${row.id} not restored at startup: ${result.detail}`);
+                    return;
+                }
+                const next = (0, local_stash_1.recordAfterRestore)(current, result);
+                persistRestore(deps, row, next);
+                touched.push(row.id);
+                if (next.state === 'needs_attention')
+                    handleConflictingRestore(deps, row, next, current.branch);
+            });
+        }
+        // Branch restorations: a resolver interrupted by the restart is settled
+        // `failed` (its worktree is kept for Discard / retry); a conflicting
+        // stash that never got one (e.g. recorded before this existed) starts now.
+        const conflictedNow = new Set(touched);
+        for (const candidate of (0, rail_pr_store_1.listPrDeliveriesWithLocalStash)(deps.db)) {
+            const record = (0, rail_pr_store_1.readLocalStash)(candidate.local_stash);
+            if (!record || record.state !== 'needs_attention' || conflictedNow.has(candidate.id))
+                continue;
+            if (record.restore?.status === 'resolving') {
+                saveRestore(deps, candidate.id, { ...record.restore, status: 'failed', detail: 'Interrupted by a restart before the conflicts were resolved.', updatedAt: new Date().toISOString() });
+                touched.push(candidate.id);
+            }
+            else if (!record.restore) {
+                void startLocalRestoreBranch(deps, candidate.id);
+            }
+        }
+    }
+    catch (err) {
+        console.error('[safe-pr] local-changes recovery failed:', err);
+    }
+    return touched;
+}

package/server/dist/modules/delivery/adapters/decisions/merge-local.js

@@ -39,6 +39,8 @@ exports.runMergeLocalIntoCheckout = runMergeLocalIntoCheckout;
 const path = __importStar(require("path"));
 const rail_worktree_release_1 = require("../../runtime/rail-worktree-release");
 const rail_pr_store_1 = require("../../runtime/rail-pr-store");
+const local_stash_1 = require("../../runtime/local-stash");
+const local_changes_1 = require("./local-changes");
 const ids_1 = require("../../../../ids");
 const repo_lock_1 = require("../../../../repo-lock");
 const integration_branch_1 = require("../../../../integration-branch");
@@ -119,7 +121,9 @@ async function runMergeLocalIntoCheckout(deps, row, targetRepo, integrationTarge
     const cleanupWarnings = [];
     // Snapshot branch/HEAD before assembly. Local edits are allowed: the final
     // non-forced fast-forward leaves unrelated work intact and Git atomically
-    // refuses any overwrite, including ignored files.
+    // refuses any overwrite, including ignored files. Uncommitted work that
+    // overlaps the delivery is saved as a stash first and restored afterwards
+    // (proactive-local-integration) — never discarded.
     const head = await deps.git.run(['symbolic-ref', '--quiet', 'HEAD'], targetRepo);
     const currentBranch = head.code === 0 ? head.stdout.trim().replace(/^refs\/heads\//, '') : '';
     if (currentBranch !== integrationTarget) {
@@ -257,15 +261,61 @@ async function runMergeLocalIntoCheckout(deps, row, targetRepo, integrationTarge
             }
             return { status: 409, body: { error: 'merge_local_blocked', reason: changedReason, base: integrationTarget } };
         }
-        const advanced = await deps.git.run(['merge', '--ff-only', '--no-overwrite-ignore', assembledSha], targetRepo);
+        // The person's uncommitted work that overlaps the delivery is saved as a
+        // stash (by commit sha, recorded durably BEFORE the branch moves) so the
+        // fast-forward can run; it is re-applied right after.
+        let stash = null;
+        const saveStash = async () => {
+            const saved = await (0, local_stash_1.saveLocalChanges)({ git: deps.git, repo: targetRepo, branch: integrationTarget, deliveryId: row.id, ticketIds: snap.ticketIds });
+            if (!saved.ok) {
+                return { status: 409, body: { error: 'merge_local_blocked', reason: 'dirty', base: integrationTarget, detail: saved.detail } };
+            }
+            stash = saved.record;
+            (0, rail_pr_store_1.setPrDeliveryLocalStash)(deps.db, row.id, saved.record);
+            return null;
+        };
+        const dirty = await (0, local_stash_1.listUserDirtyPaths)(deps.git, targetRepo);
+        if (dirty && dirty.length > 0) {
+            const changed = await (0, local_stash_1.changedPathsBetween)(deps.git, targetRepo, startingSha, assembledSha);
+            if (!changed || (0, local_stash_1.pathsOverlap)(dirty, changed)) {
+                const blocked = await saveStash();
+                if (blocked) {
+                    await removeAssembly();
+                    return blocked;
+                }
+            }
+        }
+        const fastForward = () => deps.git.run(['merge', '--ff-only', '--no-overwrite-ignore', assembledSha], targetRepo);
+        const refusedByLocalChanges = (r) => /would be overwritten|local changes|untracked working tree/i.test(`${r.stderr}\n${r.stdout}`);
+        let advanced = await fastForward();
+        if (advanced.code !== 0 && !stash && refusedByLocalChanges(advanced) && (dirty === null || dirty.length > 0)) {
+            // Git saw an overlap the path comparison did not (e.g. case folding):
+            // take the same stash path, then retry once.
+            const blocked = await saveStash();
+            if (blocked) {
+                await removeAssembly();
+                return blocked;
+            }
+            advanced = await fastForward();
+        }
         if (advanced.code !== 0) {
             await removeAssembly();
-            if (/would be overwritten|local changes|untracked working tree/i.test(`${advanced.stderr}\n${advanced.stdout}`)) {
+            // The branch did not move: put the saved work straight back.
+            let localChanges;
+            const failedStash = stash;
+            if (failedStash) {
+                const current = failedStash;
+                const next = (0, local_stash_1.recordAfterRestore)(current, await (0, local_stash_1.restoreLocalChanges)(deps.git, current));
+                (0, rail_pr_store_1.setPrDeliveryLocalStash)(deps.db, row.id, next);
+                localChanges = (0, local_changes_1.localChangesBody)(next);
+            }
+            if (refusedByLocalChanges(advanced)) {
                 return {
                     status: 409,
                     body: {
                         error: 'merge_local_blocked', reason: 'dirty', base: integrationTarget,
                         detail: (advanced.stderr.trim() || advanced.stdout.trim()).slice(0, 1200),
+                        ...(localChanges ? { localChanges } : {}),
                     },
                 };
             }
@@ -273,7 +323,7 @@ async function runMergeLocalIntoCheckout(deps, row, targetRepo, integrationTarge
             const conflict = persistAssemblyFailure(`advancing '${integrationTarget}': ${detail}`);
             if (conflict)
                 return conflict;
-            return { status: 502, body: { error: 'merge_failed', detail: `advancing '${integrationTarget}': ${detail}` } };
+            return { status: 502, body: { error: 'merge_failed', detail: `advancing '${integrationTarget}': ${detail}`, ...(localChanges ? { localChanges } : {}) } };
         }
         const [acceptedBranch, acceptedHead, acceptedBase] = await Promise.all([
             deps.git.run(['symbolic-ref', '--quiet', 'HEAD'], targetRepo),
@@ -291,6 +341,11 @@ async function runMergeLocalIntoCheckout(deps, row, targetRepo, integrationTarge
             (0, transitions_1.safetyArchiveRecorder)(deps, row)(assemblyPath);
             const detail = `The integration checkout changed during the final advance. The assembled result is preserved at ${assemblyPath}.`;
             cleanupWarnings.push(detail);
+            // Never re-apply onto a checkout someone else just moved: the saved
+            // work stays recorded (`saved`) for Restore / startup recovery.
+            const savedStash = stash;
+            if (savedStash)
+                cleanupWarnings.push(`Your local changes are saved as the stash "${savedStash.name}".`);
             const conflict = (0, transitions_1.casTransition)(deps, row, row.decision, { cleanupWarnings, statusCode: 'delivery_failed', statusDetail: detail });
             if (conflict)
                 return conflict;
@@ -298,6 +353,19 @@ async function runMergeLocalIntoCheckout(deps, row, targetRepo, integrationTarge
             return { status: 409, body: { error: 'merge_local_blocked', reason: 'head_changed', base: integrationTarget, detail } };
         }
         await removeAssembly();
+        // Re-apply the saved work onto the integrated tree. A conflict rolls back
+        // only the stash's own paths and KEEPS the stash; Specrails then restores
+        // it on its own branch + worktree (the mission is only informed).
+        let restoredStash = null;
+        const advancedStash = stash;
+        if (advancedStash) {
+            const restore = await (0, local_stash_1.restoreLocalChanges)(deps.git, advancedStash);
+            if (restore.state !== 'blocked')
+                cleanupWarnings.push(...restore.warnings);
+            restoredStash = (0, local_stash_1.recordAfterRestore)(advancedStash, restore);
+            (0, rail_pr_store_1.setPrDeliveryLocalStash)(deps.db, row.id, restoredStash);
+        }
+        const localChangesNeedAttention = !!restoredStash && (restoredStash.state === 'needs_attention' || restoredStash.state === 'saved');
         // Post-advance sweep: the work now lives on
         // the integration branch, so the launch's worktrees + branches are spent.
         cleanupWarnings.push(...await (0, rail_worktree_release_1.releaseRailWorktrees)({
@@ -313,8 +381,12 @@ async function runMergeLocalIntoCheckout(deps, row, targetRepo, integrationTarge
         }));
         await (0, ownership_1.deleteOwnedBranchesIfUnchanged)(deps, row, snap, cleanupWarnings);
         const conflict = (0, transitions_1.casTransitionWithTicketEffect)(deps, row, 'merged', {
+            // Local merge is both the human decision (admitted at the lease claim)
+            // and the merge itself; first write wins for each instant.
+            decidedAt: (0, transitions_1.decisionInstant)(row),
+            mergedAt: new Date().toISOString(),
             deliveryOutcome: 'delivered',
-            statusCode: cleanupWarnings.length > 0 ? 'cleanup_incomplete' : 'merged',
+            statusCode: localChangesNeedAttention ? 'local_changes_attention' : cleanupWarnings.length > 0 ? 'cleanup_incomplete' : 'merged',
             cleanupWarnings,
         }, {
             deliveryId: row.id,
@@ -328,7 +400,9 @@ async function runMergeLocalIntoCheckout(deps, row, targetRepo, integrationTarge
         (0, transitions_1.applyTerminalTicketEffect)(deps, row, 'merged', cleanupWarnings);
         (0, transitions_1.finalizeTransition)(deps, row.id);
         await (0, chains_1.sweepMergedChainAncestors)(deps, row);
-        return { status: 200, body: { ok: true, decision: 'merged', merged: true, local: true } };
+        if (restoredStash?.state === 'needs_attention')
+            (0, local_changes_1.handleConflictingRestore)(deps, row, restoredStash, integrationTarget);
+        return { status: 200, body: { ok: true, decision: 'merged', merged: true, local: true, ...(restoredStash ? { localChanges: (0, local_changes_1.localChangesBody)(restoredStash) } : {}) } };
     }
     finally {
         // Runner exceptions (spawn failures/timeouts) must release the temporary

package/server/dist/modules/delivery/adapters/decisions/observations.js

@@ -71,6 +71,9 @@ async function settleObservedExistingPr(deps, row, observation, pushed) {
         onSafetyArchive: (0, transitions_1.safetyArchiveRecorder)(deps, row),
     });
     const conflict = (0, transitions_1.casTransition)(deps, row, next, {
+        // Publishing (draft → ready, in-app or observed on GitHub) is stamped once;
+        // an already-ready row keeps its unknown/recorded instant untouched.
+        ...(next === 'pr_ready' && row.decision !== 'pr_ready' ? { publishedAt: new Date().toISOString() } : {}),
         prState: 'pr-created',
         deliveryOutcome: 'delivered',
         statusCode: cleanupWarnings.length > 0 ? 'cleanup_incomplete' : next === 'pr_ready' ? 'pr_ready' : 'existing_pr_updated',
@@ -226,6 +229,8 @@ async function settleMergedPr(deps, row) {
     });
     await (0, ownership_1.deleteOwnedBranchesIfUnchanged)(deps, row, snap, cleanupWarnings);
     const conflict = (0, transitions_1.casTransitionWithTicketEffect)(deps, row, 'merged', {
+        // Observed (poll-merge / publish re-observation) merge instant; first write wins.
+        mergedAt: new Date().toISOString(),
         deliveryOutcome: 'delivered',
         statusCode: cleanupWarnings.length > 0 ? 'cleanup_incomplete' : 'merged',
         statusDetail: null,

package/server/dist/modules/delivery/adapters/decisions/ownership.js

@@ -24,7 +24,8 @@ function ownedDeliveryBranches(row, snap, cleanupWarnings) {
         cleanupWarnings.push(`branch cleanup preserved ${unknownOwnership.length} legacy ${unknownOwnership.length === 1 ? 'branch' : 'branches'} because ownership was not recorded`);
     }
     const owned = new Set(snap.branches
-        .filter((unit) => unit.branchOwnership === 'created' && unitWasDelivered(unit))
+        // An adopted Flow branch is the rail's from the hand-off on (release treats it like created).
+        .filter((unit) => (unit.branchOwnership === 'created' || unit.branchOwnership === 'adopted') && unitWasDelivered(unit))
         .map((unit) => unit.branch));
     if (row.is_continuation !== 1 && snap.branches.length > 1 && row.branch &&
         !snap.branches.some((unit) => unit.branch === row.branch))

package/server/dist/modules/delivery/adapters/decisions/transitions.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.deferredFinalizations = void 0;
+exports.decisionInstant = decisionInstant;
 exports.staleDecision = staleDecision;
 exports.illegalAction = illegalAction;
 exports.ghFailed = ghFailed;
@@ -16,6 +17,14 @@ const rail_pr_ticket_effects_1 = require("../../runtime/rail-pr-ticket-effects")
 // must be absent from every emitted snapshot. Calls made while a lease is held
 // are deferred until executePrDecision's finally releases that exact token.
 exports.deferredFinalizations = new Set();
+/** Instant a human decision was admitted: the operation lease's start (the
+ * claim precedes every Git/GitHub effect), so slow effects never inflate the
+ * measured time to decision. Falls back to now for an unleased caller. Stored
+ * first-write-wins (`decided_at`); see rail-pr-store `lifecycleStamps`. */
+function decisionInstant(row, now = Date.now()) {
+    const ms = row.operation_started_at_ms;
+    return new Date(typeof ms === 'number' && Number.isFinite(ms) && ms > 0 ? ms : now).toISOString();
+}
 function staleDecision(current) {
     return { status: 409, body: { error: 'stale_decision', current } };
 }