specrails-desktop 2.55.0 → 2.55.1

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

@@ -0,0 +1,425 @@
+"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.runRecoverAndRetry = runRecoverAndRetry;
+const fs = __importStar(require("fs"));
+const worktree_manager_1 = require("../../../../worktree-manager");
+const rail_pr_store_1 = require("../../runtime/rail-pr-store");
+const rail_worktrees_store_1 = require("../../runtime/rail-worktrees-store");
+const pr_lifecycle_1 = require("../../runtime/pr-lifecycle");
+const rail_pr_recovery_git_1 = require("../../runtime/rail-pr-recovery-git");
+const transitions_1 = require("./transitions");
+const observations_1 = require("./observations");
+const evidence_1 = require("./evidence");
+const retry_1 = require("./retry");
+/**
+ * Explicit recovery for a legacy successful continuation whose automatic
+ * causal scan could not freeze a commit. Unlike Checkout, this operates only
+ * on the delivery-owned isolated worktree/branch and never changes the user's
+ * main checkout. The user's confirmation authorizes adopting already-committed
+ * progress on that exact branch, but only as a non-force fast-forward of the
+ * live PR head.
+ */
+async function runRecoverAndRetry(deps, row) {
+    if (!row.pr_url || !row.branch || !row.operation_token)
+        return (0, transitions_1.illegalAction)(row.decision);
+    const snap = (0, rail_pr_store_1.toPrDeliverySnapshot)(row);
+    const runIds = [...new Set(snap.runIds.filter((runId) => typeof runId === 'string' && runId.length > 0))];
+    if (runIds.length !== 1) {
+        return (0, observations_1.persistRecoveryBlocked)(deps, row, `Commit & retry push requires exactly one recorded implementation run; found ${runIds.length}. No local evidence was changed.`);
+    }
+    const runId = runIds[0];
+    const matchingUnitIndexes = snap.branches
+        .map((branch, index) => branch.branch === row.branch && branch.runId === runId ? index : -1)
+        .filter((index) => index >= 0);
+    if (matchingUnitIndexes.length === 0) {
+        return (0, observations_1.persistRecoveryBlocked)(deps, row, 'Commit & retry push could not prove an exact recorded unit for this run and PR branch. No local evidence was changed.');
+    }
+    const matchingUnits = matchingUnitIndexes.map((index) => snap.branches[index]);
+    const recordedFinalValues = matchingUnits.map((unit) => unit.finalSha);
+    const hasAnyRecordedFinal = recordedFinalValues.some((sha) => sha != null);
+    const recordedFinalShas = [...new Set(recordedFinalValues
+            .filter((sha) => typeof sha === 'string' && evidence_1.COMMIT_SHA_RE.test(sha))
+            .map((sha) => sha.toLowerCase()))];
+    const recordedFinalEvidenceUnsafe = hasAnyRecordedFinal && (recordedFinalValues.some((sha) => typeof sha !== 'string' || !evidence_1.COMMIT_SHA_RE.test(sha)) ||
+        recordedFinalShas.length !== 1);
+    // Durable final evidence is one sufficient ownership proof, not a veto over
+    // the independent exact run-marker proof. Incomplete/disagreeing migrated
+    // unit fields are ignored here; a unique causal commit may still recover the
+    // result without adopting any of those disputed SHAs.
+    const recordedFinalSha = recordedFinalEvidenceUnsafe ? null : recordedFinalShas[0] ?? null;
+    let discovery = null;
+    const discoverCandidate = async () => {
+        if (!discovery) {
+            discovery = await (0, rail_pr_recovery_git_1.discoverRunMarkedCommit)(deps.git, deps.project.path, runId);
+        }
+        return discovery;
+    };
+    const ownedWorktrees = snap.worktreeIds
+        .map((worktreeId) => (0, rail_worktrees_store_1.getRailWorktree)(deps.db, worktreeId))
+        .filter((worktree) => Boolean(worktree && worktree.branch === row.branch && worktree.run_id === runId));
+    const presentWorktrees = ownedWorktrees.filter((worktree) => {
+        try {
+            fs.lstatSync(worktree.worktree_path);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+    const worktree = presentWorktrees[0] ?? null;
+    let preprotectedCandidateSha = null;
+    let preprotectedCandidateSource = null;
+    // Discover and pin an exact object before any network dependency, even when
+    // a ledger path still exists. A recreated/unsafe/dirty path must not hide an
+    // older run-owned orphan or leave it exposed to Git GC.
+    {
+        if (recordedFinalSha && await (0, evidence_1.commitObjectExists)(deps, recordedFinalSha)) {
+            preprotectedCandidateSha = recordedFinalSha;
+            preprotectedCandidateSource = 'recorded-final';
+        }
+        else {
+            const found = await discoverCandidate();
+            if (found.kind === 'ambiguous') {
+                return (0, observations_1.persistRecoveryBlocked)(deps, row, `Git found ${found.count} different run-marked commits. No ambiguous object, branch, or worktree was changed.`);
+            }
+            if (found.kind === 'scan_failed') {
+                return (0, observations_1.persistRecoveryBlocked)(deps, row, `${found.detail}. No branch, worktree, or object was changed.`);
+            }
+            if (found.kind === 'unique') {
+                preprotectedCandidateSha = found.sha;
+                preprotectedCandidateSource = 'run-marker';
+            }
+        }
+        if (preprotectedCandidateSha) {
+            const protection = await (0, rail_pr_recovery_git_1.protectRecoveryCommit)(deps.git, deps.project.path, row.id, preprotectedCandidateSha);
+            if (!protection.ok) {
+                return (0, observations_1.persistRecoveryBlocked)(deps, row, `${protection.detail}. The candidate object and every user-visible branch were left unchanged.`);
+            }
+        }
+    }
+    if (presentWorktrees.length > 1) {
+        return (0, observations_1.persistRecoveryBlocked)(deps, row, 'Multiple live worktrees claim this run and branch, so Specrails refused to choose one. Every local result remains intact.', preprotectedCandidateSha);
+    }
+    const observed = await (0, pr_lifecycle_1.observePrLifecycle)(deps.exec, deps.project.path, row.pr_url, preprotectedCandidateSha);
+    if (!observed.ok) {
+        if (preprotectedCandidateSha) {
+            if (worktree) {
+                return (0, observations_1.persistRecoveryBlocked)(deps, row, `Protected an exact run-owned commit, but a live worktree also exists and the PR could not be observed: ${observed.detail}. Both local results were preserved and neither was selected or pushed.`, preprotectedCandidateSha);
+            }
+            const durablyProvenNoChange = row.implementation_outcome === 'succeeded' &&
+                matchingUnitIndexes.length === snap.branches.length &&
+                matchingUnits.every((unit) => (unit.changed === false &&
+                    unit.initialSha?.toLowerCase() === preprotectedCandidateSha.toLowerCase() &&
+                    unit.finalSha?.toLowerCase() === preprotectedCandidateSha.toLowerCase()));
+            const detail = `Recovered and protected the exact run-owned commit, but the recorded PR could not be observed: ${observed.detail}; retry will revalidate before any push.`;
+            if (durablyProvenNoChange) {
+                return (0, observations_1.persistRecoveryBlocked)(deps, row, detail, preprotectedCandidateSha);
+            }
+            return (0, observations_1.persistProtectedRecoveryRetry)(deps, row, snap, matchingUnitIndexes, runId, preprotectedCandidateSha, detail);
+        }
+        return (0, observations_1.persistRecoveryBlocked)(deps, row, `The existing PR could not be verified before local recovery: ${observed.detail}. No local evidence was changed.`);
+    }
+    if (!(0, pr_lifecycle_1.isExactOpenPr)(observed, row.branch, row.base_branch) || !observed.headRefOid) {
+        if (preprotectedCandidateSha) {
+            if (worktree) {
+                return (0, observations_1.persistRecoveryBlocked)(deps, row, 'A protected run-owned commit and a live worktree both exist while the recorded PR lifecycle changed. Specrails preserved both and refused to choose or push either automatically.', preprotectedCandidateSha);
+            }
+            const frozen = (0, observations_1.persistProtectedRecoveryRetry)(deps, row, snap, matchingUnitIndexes, runId, preprotectedCandidateSha, 'Protected the exact run-owned commit; revalidating the changed PR lifecycle before any push.');
+            if (frozen.status !== 200 || frozen.body.decision !== 'pr_failed')
+                return frozen;
+            const recoveredRow = (0, rail_pr_store_1.getPrDelivery)(deps.db, row.id);
+            if (!recoveredRow || recoveredRow.operation_token !== row.operation_token) {
+                return (0, transitions_1.staleDecision)(recoveredRow?.decision ?? row.decision);
+            }
+            return (0, retry_1.retryExistingPrFollowupPush)(deps, recoveredRow);
+        }
+        return (0, observations_1.persistRecoveryBlocked)(deps, row, 'The recorded PR is no longer an exact open head/base recovery target. No local evidence was changed.');
+    }
+    const baselineSha = observed.headRefOid;
+    // Ensure the live remote baseline object is available for the ancestry proof
+    // without advancing any local branch or touching the main checkout.
+    if (!(await (0, evidence_1.commitObjectExists)(deps, baselineSha))) {
+        try {
+            await deps.git.run(['fetch', 'origin', `refs/heads/${row.branch}`], deps.project.path);
+        }
+        catch { /* the exact object check below remains authoritative */ }
+    }
+    if (!(await (0, evidence_1.commitObjectExists)(deps, baselineSha))) {
+        return (0, observations_1.persistRecoveryBlocked)(deps, row, 'The live PR head object is unavailable locally, so fast-forward recovery cannot be proven. No local evidence was changed.', preprotectedCandidateSha);
+    }
+    let candidateSha = preprotectedCandidateSha;
+    let candidateOwned = preprotectedCandidateSha !== null;
+    let candidateSource = preprotectedCandidateSource ?? 'baseline';
+    let committed = false;
+    if (worktree) {
+        const authenticated = await (0, evidence_1.authenticateRecoveryWorktree)(deps, worktree.worktree_path, row.branch);
+        if (!authenticated.ok) {
+            return (0, observations_1.persistRecoveryBlocked)(deps, row, `The preserved path at ${worktree.worktree_path} could not be authenticated safely: ${authenticated.detail}. Nothing was staged, pushed, or removed.`, preprotectedCandidateSha);
+        }
+        const authenticatedPath = authenticated.realPath;
+        const [actualBranch, worktreeHead, branchHead] = await Promise.all([
+            deps.git.run(['rev-parse', '--abbrev-ref', 'HEAD'], authenticatedPath).catch(() => ({ code: 1, stdout: '', stderr: '' })),
+            (0, evidence_1.exactRefSha)(deps, authenticatedPath, 'HEAD'),
+            (0, evidence_1.exactRefSha)(deps, deps.project.path, `refs/heads/${row.branch}`),
+        ]);
+        if (actualBranch.code !== 0 || actualBranch.stdout.trim() !== row.branch ||
+            !worktreeHead || !branchHead || worktreeHead !== branchHead ||
+            authenticated.head.toLowerCase() !== worktreeHead.toLowerCase()) {
+            return (0, observations_1.persistRecoveryBlocked)(deps, row, `The preserved worktree at ${worktree.worktree_path} is not on the exact recorded branch/HEAD. It was left untouched.`, preprotectedCandidateSha);
+        }
+        if (preprotectedCandidateSha &&
+            worktreeHead.toLowerCase() !== preprotectedCandidateSha.toLowerCase()) {
+            return (0, observations_1.persistRecoveryBlocked)(deps, row, `A protected run-owned commit and a different live worktree result both exist. Specrails preserved both and refused to choose or bundle them automatically. Inspect ${worktree.worktree_path} before retrying or discarding either result.`, preprotectedCandidateSha);
+        }
+        if (!(await (0, evidence_1.isFastForwardCandidate)(deps, baselineSha, worktreeHead))) {
+            return (0, observations_1.persistRecoveryBlocked)(deps, row, `The preserved branch diverges from the live PR head. The worktree at ${worktree.worktree_path} was left untouched.`, preprotectedCandidateSha);
+        }
+        let skipWorktreeCommit = false;
+        if (worktreeHead === baselineSha) {
+            candidateOwned = true;
+            candidateSource = 'baseline';
+        }
+        else if (recordedFinalSha && worktreeHead.toLowerCase() === recordedFinalSha) {
+            candidateOwned = true;
+            candidateSource = 'recorded-final';
+        }
+        else {
+            const found = await discoverCandidate();
+            if (found.kind === 'unique' && found.sha === worktreeHead.toLowerCase()) {
+                candidateOwned = true;
+                candidateSource = 'run-marker';
+            }
+            else if (found.kind === 'unique') {
+                // A later/unrelated checked-out tip must not be bundled into the
+                // recovered result. Preserve it untouched and use only the exact
+                // run-owned object discovered independently.
+                candidateSha = found.sha;
+                candidateOwned = true;
+                candidateSource = 'run-marker';
+                skipWorktreeCommit = true;
+            }
+            else {
+                const reason = found.kind === 'ambiguous'
+                    ? `Git found ${found.count} run-marked commits, so no unique worktree baseline could be chosen.`
+                    : found.kind === 'scan_failed'
+                        ? `${found.detail}.`
+                        : 'The preserved worktree branch advanced beyond every delivery-owned commit.';
+                return (0, observations_1.persistRecoveryBlocked)(deps, row, `${reason} The worktree at ${worktree.worktree_path} was left untouched.`);
+            }
+        }
+        if (!skipWorktreeCommit) {
+            deps.assertAdmission?.();
+            const reauthenticated = await (0, evidence_1.authenticateRecoveryWorktree)(deps, worktree.worktree_path, row.branch, worktreeHead);
+            if (!reauthenticated.ok || reauthenticated.realPath !== authenticatedPath) {
+                const detail = reauthenticated.ok
+                    ? 'the canonical worktree path changed before staging'
+                    : reauthenticated.detail;
+                return (0, observations_1.persistRecoveryBlocked)(deps, row, `The preserved path at ${worktree.worktree_path} failed final authentication: ${detail}. Nothing was staged, pushed, or removed.`);
+            }
+            deps.assertAdmission?.();
+            const overlayExcludes = [...new Set(matchingUnits.flatMap((unit) => unit.overlayExcludes ?? []))];
+            const commit = await (0, worktree_manager_1.commitWorktreeAndVerify)(deps.git, reauthenticated.realPath, `specrails: recovered follow-up (run ${runId})`, overlayExcludes);
+            if (!commit.clean) {
+                return (0, observations_1.persistRecoveryBlocked)(deps, row, `The preserved worktree could not be committed safely: ${commit.error ?? (commit.dirty.join(', ') || 'deliverable changes remain')}. It was left intact at ${worktree.worktree_path}.`);
+            }
+            committed = commit.committed;
+            const [afterBranch, afterHead, afterBranchHead] = await Promise.all([
+                deps.git.run(['rev-parse', '--abbrev-ref', 'HEAD'], reauthenticated.realPath).catch(() => ({ code: 1, stdout: '', stderr: '' })),
+                (0, evidence_1.exactRefSha)(deps, reauthenticated.realPath, 'HEAD'),
+                (0, evidence_1.exactRefSha)(deps, deps.project.path, `refs/heads/${row.branch}`),
+            ]);
+            if (afterBranch.code !== 0 || afterBranch.stdout.trim() !== row.branch ||
+                !afterHead || afterHead !== afterBranchHead) {
+                return (0, observations_1.persistRecoveryBlocked)(deps, row, `The recovery commit exists, but final branch verification failed. It remains preserved at ${worktree.worktree_path}.`);
+            }
+            candidateSha = afterHead;
+            if (committed) {
+                candidateOwned = true;
+                candidateSource = 'worktree';
+            }
+            if (candidateSource === 'baseline' && recordedFinalSha && afterHead.toLowerCase() === recordedFinalSha) {
+                candidateSource = 'recorded-final';
+            }
+            candidateOwned = candidateOwned || committed || candidateSource !== 'baseline' || afterHead === baselineSha;
+        }
+    }
+    else {
+        candidateSha ??= await (0, evidence_1.exactRefSha)(deps, deps.project.path, `refs/heads/${row.branch}`);
+    }
+    // A consistent durable final SHA outranks a mutable branch name. This also
+    // lets another checkout recover an object whose branch was later reset.
+    if (!committed && recordedFinalSha &&
+        await (0, evidence_1.commitObjectExists)(deps, recordedFinalSha) &&
+        (!candidateOwned || candidateSha === baselineSha)) {
+        candidateSha = recordedFinalSha;
+        candidateOwned = true;
+        candidateSource = 'recorded-final';
+    }
+    // Before claiming absence, inspect the same complete causal surface as
+    // startup. A unique run-marked object may survive after both the worktree and
+    // visible branch were removed.
+    const baselineHasDurableFinalProof = candidateSha === baselineSha && recordedFinalSha === baselineSha;
+    if (!candidateSha || (candidateSha === baselineSha && !baselineHasDurableFinalProof) || !candidateOwned) {
+        const found = await discoverCandidate();
+        if (found.kind === 'ambiguous') {
+            return (0, observations_1.persistRecoveryBlocked)(deps, row, `Git found ${found.count} different run-marked commits. No ambiguous object, branch, or worktree was changed.`);
+        }
+        if (found.kind === 'scan_failed') {
+            return (0, observations_1.persistRecoveryBlocked)(deps, row, `${found.detail}. No branch, worktree, or object was changed.`);
+        }
+        if (found.kind === 'unique') {
+            candidateSha = found.sha;
+            candidateOwned = true;
+            candidateSource = 'run-marker';
+        }
+        else if (candidateSha && candidateSha !== baselineSha && !candidateOwned) {
+            return (0, observations_1.persistRecoveryBlocked)(deps, row, 'The recorded local branch advanced beyond the run-owned result. The later branch tip was preserved and was not committed or pushed.');
+        }
+    }
+    if (!candidateSha || !(await (0, evidence_1.commitObjectExists)(deps, candidateSha))) {
+        return (0, observations_1.persistRecoveryBlocked)(deps, row, 'No delivery-owned commit is available in this clone’s refs, reflogs, worktrees, or unreachable objects. The result may still exist on the computer where the run executed; nothing here was changed or removed.');
+    }
+    if (candidateSha === baselineSha) {
+        const provesNoChanges = row.implementation_outcome === 'succeeded' &&
+            matchingUnitIndexes.length === snap.branches.length &&
+            matchingUnits.every((unit) => (unit.changed === false &&
+                unit.initialSha?.toLowerCase() === baselineSha.toLowerCase() &&
+                unit.finalSha?.toLowerCase() === baselineSha.toLowerCase()));
+        if (provesNoChanges) {
+            const noChangeIndexes = new Set(matchingUnitIndexes);
+            const noChangeBranches = snap.branches.map((unit, index) => noChangeIndexes.has(index)
+                ? {
+                    ...unit,
+                    succeeded: true,
+                    implementationOutcome: 'succeeded',
+                    deliveryOutcome: 'no_changes',
+                    initialSha: baselineSha,
+                    finalSha: baselineSha,
+                    changed: false,
+                    failureCode: null,
+                }
+                : unit);
+            const conflict = (0, transitions_1.casTransition)(deps, row, 'no_changes', {
+                branches: noChangeBranches,
+                deliverySha: baselineSha,
+                deliveryOutcome: 'no_changes',
+                statusCode: 'no_changes',
+                statusDetail: null,
+                isContinuation: true,
+            });
+            if (conflict)
+                return conflict;
+            await (0, evidence_1.releaseDeliveredRecoveryLineage)(deps, row, baselineSha);
+            (0, transitions_1.finalizeTransition)(deps, row.id);
+            return {
+                status: 200,
+                body: {
+                    ok: true,
+                    decision: 'no_changes',
+                    prUrl: row.pr_url,
+                    noChanges: true,
+                    deliveryVerified: true,
+                    verifiedSha: baselineSha,
+                    pushed: false,
+                },
+            };
+        }
+        const alreadyDelivered = recordedFinalSha === baselineSha || candidateSource === 'run-marker';
+        if (!alreadyDelivered) {
+            return (0, observations_1.persistRecoveryBlocked)(deps, row, 'This clone contains only the current PR head and no additional run-owned result. The original execution computer may still retain its worktree or orphan commit; nothing here was changed or removed.');
+        }
+    }
+    else {
+        const protection = preprotectedCandidateSha &&
+            preprotectedCandidateSha.toLowerCase() !== candidateSha.toLowerCase()
+            ? await (0, rail_pr_recovery_git_1.advanceRecoveryCommitProtection)(deps.git, deps.project.path, row.id, preprotectedCandidateSha, candidateSha)
+            : await (0, rail_pr_recovery_git_1.protectRecoveryCommit)(deps.git, deps.project.path, row.id, candidateSha);
+        if (!protection.ok) {
+            return (0, observations_1.persistRecoveryBlocked)(deps, row, `${protection.detail}. The candidate object and every user-visible branch were left unchanged.`, preprotectedCandidateSha);
+        }
+    }
+    if (!(await (0, evidence_1.isFastForwardCandidate)(deps, baselineSha, candidateSha))) {
+        return (0, observations_1.persistRecoveryBlocked)(deps, row, 'The exact run-owned recovery commit is not a fast-forward of the live PR head. It remains protected locally and nothing was pushed or removed.', candidateSha);
+    }
+    const recoveredIndexes = new Set(matchingUnitIndexes);
+    const recoveredBranches = snap.branches.map((unit, index) => recoveredIndexes.has(index)
+        ? {
+            ...unit,
+            runId,
+            branch: row.branch,
+            succeeded: true,
+            implementationOutcome: 'succeeded',
+            deliveryOutcome: 'ready',
+            // Equality with the live PR head can mean the exact run commit was
+            // already delivered; it is not no-change evidence. Preserve a durable
+            // initial SHA when available and infer the observed baseline only for
+            // a still-missing descendant. The proven no-change branch returned
+            // above before reaching this mapping.
+            initialSha: unit.initialSha ?? (candidateSha !== baselineSha ? baselineSha : null),
+            finalSha: candidateSha,
+            changed: true,
+            failureCode: null,
+            branchOwnership: 'borrowed-pr',
+            ...(worktree ? { worktreePath: worktree.worktree_path } : {}),
+        }
+        : unit);
+    // Freeze before the network mutation. A crash after this write leaves a
+    // normal immutable Retry push card; a crash before it leaves the run-marked
+    // commit discoverable by startup recovery.
+    if (!(0, rail_pr_store_1.transitionClaimedDecision)(deps.db, row.id, row.decision, 'pr_failed', row.operation_token, {
+        branches: recoveredBranches,
+        deliverySha: candidateSha,
+        deliveryOutcome: 'retryable_failure',
+        statusCode: 'settlement_interrupted',
+        statusDetail: candidateSource === 'worktree'
+            ? `Committed the preserved worktree as ${candidateSha.slice(0, 8)}; validating the exact PR before push.`
+            : candidateSource === 'run-marker'
+                ? `Protected the unique run-owned commit ${candidateSha.slice(0, 8)}; validating the exact PR before push.`
+                : `Recovered the durable final commit ${candidateSha.slice(0, 8)}; validating the exact PR before push.`,
+        isContinuation: true,
+    })) {
+        const current = (0, rail_pr_store_1.getPrDelivery)(deps.db, row.id);
+        return (0, transitions_1.staleDecision)(current?.decision ?? row.decision);
+    }
+    if (worktree)
+        (0, rail_worktrees_store_1.updateRailWorktreeState)(deps.db, worktree.id, 'built');
+    const recoveredRow = (0, rail_pr_store_1.getPrDelivery)(deps.db, row.id);
+    if (!recoveredRow || recoveredRow.operation_token !== row.operation_token) {
+        return (0, transitions_1.staleDecision)(recoveredRow?.decision ?? row.decision);
+    }
+    deps.assertAdmission?.();
+    return (0, retry_1.retryExistingPrFollowupPush)(deps, recoveredRow);
+}

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

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retryExistingPrFollowupPush = retryExistingPrFollowupPush;
+const pr_publisher_1 = require("../../runtime/pr-publisher");
+const pr_lifecycle_1 = require("../../runtime/pr-lifecycle");
+const transitions_1 = require("./transitions");
+const observations_1 = require("./observations");
+const evidence_1 = require("./evidence");
+async function retryExistingPrFollowupPush(deps, row) {
+    if (!row.branch || !row.pr_url)
+        return { status: 502, body: { error: 'push_failed', detail: 'missing PR branch/url' } };
+    if (!row.delivery_sha) {
+        const detail = 'missing verified delivery SHA; refusing to resolve a mutable branch for retry';
+        const conflict = (0, transitions_1.casTransition)(deps, row, 'pr_failed', {
+            deliveryOutcome: 'blocked',
+            statusCode: 'branch_verification_failed',
+            statusDetail: detail,
+        });
+        if (conflict)
+            return conflict;
+        (0, transitions_1.finalizeTransition)(deps, row.id);
+        return { status: 409, body: { error: 'missing_verified_sha', decision: 'pr_failed', prUrl: row.pr_url, detail } };
+    }
+    const beforePush = await (0, pr_lifecycle_1.observePrLifecycle)(deps.exec, deps.project.path, row.pr_url, row.delivery_sha);
+    if (!beforePush.ok) {
+        return (0, observations_1.persistRetryablePrObservationFailure)(deps, row, `could not confirm the existing PR is open before retry: ${beforePush.detail}`);
+    }
+    if (!(0, pr_lifecycle_1.isExactOpenPr)(beforePush, row.branch, row.base_branch)) {
+        const identityMatches = (0, pr_lifecycle_1.matchesRecordedPrIdentity)(beforePush, row.branch, row.base_branch);
+        if (beforePush.state === 'MERGED' && identityMatches && beforePush.includesExpectedSha === true) {
+            return (0, observations_1.settleMergedPr)(deps, row);
+        }
+        if (beforePush.state === 'MERGED') {
+            return (0, observations_1.rerouteFromStalePr)(deps, row, identityMatches ? (0, observations_1.mergedEvidenceDetail)(beforePush) : 'the previous PR merged after its recorded head/base identity changed', false);
+        }
+        if (beforePush.state === 'CLOSED') {
+            if (identityMatches && beforePush.includesExpectedSha === true) {
+                return (0, observations_1.settleObservedClosedPr)(deps, row, beforePush);
+            }
+            return (0, observations_1.rerouteFromStalePr)(deps, row, 'the previous PR closed before this implementation was delivered', false);
+        }
+        return (0, observations_1.rerouteFromStalePr)(deps, row, 'the existing open PR no longer matches its recorded head/base identity', false);
+    }
+    if (beforePush.includesExpectedSha === true) {
+        return (0, observations_1.settleObservedExistingPr)(deps, row, beforePush, false);
+    }
+    if (!beforePush.headRefOid) {
+        return (0, observations_1.persistRetryablePrObservationFailure)(deps, row, 'the open PR did not expose a verifiable head commit; Retry push will revalidate before mutation');
+    }
+    if (!(await (0, evidence_1.commitObjectExists)(deps, beforePush.headRefOid))) {
+        try {
+            await deps.git.run(['fetch', 'origin', `refs/heads/${row.branch}`], deps.project.path);
+        }
+        catch { /* the immutable object check below remains authoritative */ }
+    }
+    if (!(await (0, evidence_1.commitObjectExists)(deps, beforePush.headRefOid))) {
+        return (0, observations_1.persistRetryablePrObservationFailure)(deps, row, 'the live PR head object is unavailable locally; Retry push will revalidate before mutation');
+    }
+    if (!(await (0, evidence_1.isFastForwardCandidate)(deps, beforePush.headRefOid, row.delivery_sha))) {
+        const detail = 'the exact delivery commit is not a fast-forward of the live PR head; it was not pushed';
+        return row.is_continuation === 1
+            ? (0, observations_1.persistRecoveryBlocked)(deps, row, `${detail} and remains protected`, row.delivery_sha)
+            : (0, observations_1.persistMovedPrHead)(deps, row, detail);
+    }
+    const remote = await (0, pr_lifecycle_1.verifyPushRemoteForPr)(deps.exec, deps.project.path, row.pr_url);
+    if (!remote.ok) {
+        return (0, observations_1.persistRetryablePrObservationFailure)(deps, row, `refusing to push until the PR repository and origin are proven identical: ${remote.detail}`);
+    }
+    const pushed = await (0, pr_publisher_1.pushBranch)(deps.exec, {
+        repoDir: deps.project.path,
+        branch: row.branch,
+        baseBranch: row.base_branch,
+        remote: remote.pushTarget,
+        sourceSha: row.delivery_sha,
+    });
+    if (pushed.state === 'local-only') {
+        const conflict = (0, transitions_1.casTransition)(deps, row, 'pr_failed', {
+            prState: 'local-only',
+            deliveryOutcome: 'retryable_failure',
+            statusCode: 'push_failed',
+            statusDetail: pushed.reason,
+        });
+        if (conflict)
+            return conflict;
+        (0, transitions_1.finalizeTransition)(deps, row.id);
+        return { status: 200, body: { ok: true, decision: 'pr_failed', prUrl: row.pr_url, detail: pushed.reason } };
+    }
+    const afterPush = await (0, pr_lifecycle_1.observePrLifecycle)(deps.exec, deps.project.path, row.pr_url, row.delivery_sha);
+    if (!afterPush.ok) {
+        return (0, observations_1.persistRetryablePrObservationFailure)(deps, row, `exact commit was pushed, but the PR lifecycle could not be confirmed: ${afterPush.detail}`);
+    }
+    if ((0, pr_lifecycle_1.isExactOpenPr)(afterPush, row.branch, row.base_branch)) {
+        if (afterPush.includesExpectedSha !== true) {
+            return (0, observations_1.persistRetryablePrObservationFailure)(deps, row, 'the exact push completed, but the PR does not yet expose the verified commit as its head; Retry push remains safe and uses the preserved SHA');
+        }
+        return (0, observations_1.settleObservedExistingPr)(deps, row, afterPush, true);
+    }
+    const identityMatches = (0, pr_lifecycle_1.matchesRecordedPrIdentity)(afterPush, row.branch, row.base_branch);
+    if (afterPush.state === 'MERGED' && identityMatches && afterPush.includesExpectedSha === true) {
+        return (0, observations_1.settleMergedPr)(deps, row);
+    }
+    if (afterPush.state === 'MERGED') {
+        return (0, observations_1.rerouteFromStalePr)(deps, row, identityMatches ? (0, observations_1.mergedEvidenceDetail)(afterPush) : 'the previous PR merged after its recorded head/base identity changed', true);
+    }
+    if (afterPush.state === 'CLOSED') {
+        if (identityMatches && afterPush.includesExpectedSha === true) {
+            return (0, observations_1.settleObservedClosedPr)(deps, row, afterPush);
+        }
+        return (0, observations_1.rerouteFromStalePr)(deps, row, 'the previous PR closed before this implementation was delivered', true);
+    }
+    return (0, observations_1.rerouteFromStalePr)(deps, row, 'the existing open PR no longer matches its recorded head/base identity after the exact push', true);
+}

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

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deferredFinalizations = void 0;
+exports.staleDecision = staleDecision;
+exports.illegalAction = illegalAction;
+exports.ghFailed = ghFailed;
+exports.safetyArchiveRecorder = safetyArchiveRecorder;
+exports.casTransition = casTransition;
+exports.casTransitionWithTicketEffect = casTransitionWithTicketEffect;
+exports.applyTerminalTicketEffect = applyTerminalTicketEffect;
+exports.finalizeTransition = finalizeTransition;
+const rail_pr_store_1 = require("../../runtime/rail-pr-store");
+const agent_chat_registry_1 = require("../../../missions/runtime/agent-chat-registry");
+const rail_pr_ticket_effects_1 = require("../../runtime/rail-pr-ticket-effects");
+// Action handlers keep using one finalization helper, but the operation lease
+// 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();
+function staleDecision(current) {
+    return { status: 409, body: { error: 'stale_decision', current } };
+}
+function illegalAction(current) {
+    return { status: 409, body: { error: 'stale_decision', current, reason: 'illegal_action' } };
+}
+function ghFailed(r) {
+    const detail = (r.stderr.trim() || r.stdout.trim()).split('\n')[0] || `exit ${r.code}`;
+    return { status: 502, body: { error: 'gh_failed', detail } };
+}
+function safetyArchiveRecorder(deps, row) {
+    return (archive) => {
+        if (!(0, rail_pr_store_1.appendPrDeliverySafetyArchive)(deps.db, row.id, archive)) {
+            throw new Error(`delivery ${row.id} disappeared while recording safety archive ${archive}`);
+        }
+    };
+}
+/**
+ * Atomic CAS transition; a `false` return means a concurrent mutation raced us
+ * between the pre-check and here — surface the same 409 with the fresh state.
+ */
+function casTransition(deps, row, next, patch = {}) {
+    if (row.operation_token && (0, rail_pr_store_1.transitionClaimedDecision)(deps.db, row.id, row.decision, next, row.operation_token, patch))
+        return null;
+    const current = (0, rail_pr_store_1.getPrDelivery)(deps.db, row.id);
+    return staleDecision(current?.decision ?? row.decision);
+}
+function casTransitionWithTicketEffect(deps, row, next, patch, effect) {
+    if (deps.repositoryChildOf)
+        return casTransition(deps, row, next, patch);
+    if (row.operation_token &&
+        (0, rail_pr_ticket_effects_1.transitionClaimedDecisionWithTicketEffect)(deps.db, row.id, row.decision, next, row.operation_token, patch, effect))
+        return null;
+    const current = (0, rail_pr_store_1.getPrDelivery)(deps.db, row.id);
+    return staleDecision(current?.decision ?? row.decision);
+}
+function applyTerminalTicketEffect(deps, row, terminalDecision, cleanupWarnings) {
+    if (deps.repositoryChildOf)
+        return;
+    const result = (0, rail_pr_ticket_effects_1.applyRailPrTicketEffect)(deps, row.id);
+    if (result.ok)
+        return;
+    cleanupWarnings.push(`ticket status update pending: ${result.error ?? 'unknown ticket-store error'}`);
+    if (!row.operation_token)
+        return;
+    (0, rail_pr_store_1.transitionClaimedDecision)(deps.db, row.id, terminalDecision, terminalDecision, row.operation_token, {
+        statusCode: 'cleanup_incomplete',
+        cleanupWarnings,
+    });
+}
+/**
+ * Post-transition fan-out: re-broadcast the durable rail.pr_state snapshot
+ * (both surfaces converge on it) and, for agent-chat-originated launches,
+ * update the persisted inline card in place.
+ */
+function finalizeTransition(deps, id) {
+    const row = (0, rail_pr_store_1.getPrDelivery)(deps.db, id);
+    if (!row)
+        return undefined;
+    const snap = (0, rail_pr_store_1.toPrDeliverySnapshot)(row);
+    if (row.operation_token) {
+        exports.deferredFinalizations.add(id);
+        return snap;
+    }
+    if (deps.repositoryChildOf)
+        return snap;
+    deps.broadcast((0, rail_pr_store_1.toRailPrStateMessage)(deps.project.id, snap));
+    if (row.origin_conversation_id) {
+        const agent = (deps.agentChat ?? agent_chat_registry_1.getAgentChatManager)();
+        // Shared mapper (rail-pr-store.toPrDecisionCardEnvelope) — the SAME shape
+        // rail-isolated-launch's origin-card sync posts, so the two card-writing
+        // sites (incl. the runIds chip data) can never drift.
+        agent?.updatePrDecisionCard(row.origin_conversation_id, (0, rail_pr_store_1.toPrDecisionCardEnvelope)(deps.project.id, snap));
+    }
+    return snap;
+}