@penclipai/server 2026.704.0 → 2026.714.0-canary.0

package/dist/services/execution-workspaces.js

@@ -1,15 +1,22 @@
 import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { promisify } from "node:util";
-import { and, asc, desc, eq, inArray, isNull, ne, sql } from "drizzle-orm";
-import { executionWorkspaces, issues, projects, projectWorkspaces } from "@penclipai/db";
+import { and, asc, desc, eq, inArray, isNull, ne, or, sql } from "drizzle-orm";
+import { executionWorkspaces, heartbeatRuns, issueComments, issues, projects, projectWorkspaces, workspaceRuntimeServices } from "@penclipai/db";
 import { deriveProjectUrlKey, WORKSPACE_OVERVIEW_LINKED_ISSUE_LIMIT } from "@penclipai/shared";
+import { conflict, notFound, unprocessable } from "../errors.js";
+import { applyIssueExecutionPolicyTransition, normalizeIssueExecutionPolicy, parseIssueExecutionState, } from "./issue-execution-policy.js";
 import { parseProjectExecutionWorkspacePolicy } from "./execution-workspace-policy.js";
+import { issueRecoveryActionService } from "./issue-recovery-actions.js";
+import { visibleIssueCondition } from "./issue-visibility.js";
 import { readProjectWorkspaceRuntimeConfig } from "./project-workspace-runtime-config.js";
 import { listCurrentRuntimeServicesForExecutionWorkspaces, listCurrentRuntimeServicesForProjectWorkspaces, } from "./workspace-runtime-read-model.js";
 const execFileAsync = promisify(execFile);
 const TERMINAL_ISSUE_STATUSES = new Set(["done", "cancelled"]);
+const WORKSPACE_BRANCH_INCOHERENCE_REASON = "git_worktree_branch_incoherence";
+const WORKSPACE_VALIDATION_RECOVERY_CAUSE = "workspace_validation_failed";
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -24,6 +31,26 @@ function cloneRecord(value) {
         return null;
     return { ...value };
 }
+function assigneeMatchesExecutionPrincipal(input, principal) {
+    if (!principal)
+        return false;
+    if (principal.type === "agent") {
+        return input.assigneeAgentId === principal.agentId && input.assigneeUserId === null;
+    }
+    if (principal.type === "user") {
+        return input.assigneeAgentId === null && input.assigneeUserId === principal.userId;
+    }
+    return false;
+}
+function quarantineRestoreRequestedSourceStatus(input) {
+    const state = parseIssueExecutionState(input.executionState);
+    if (state?.status === "pending" &&
+        input.status === "in_review" &&
+        assigneeMatchesExecutionPrincipal(input, state.currentParticipant)) {
+        return undefined;
+    }
+    return "todo";
+}
 function readDesiredState(value) {
     return value === "running" || value === "stopped" || value === "manual" ? value : null;
 }
@@ -49,6 +76,274 @@ async function pathExists(value) {
 async function runGit(args, cwd) {
     return await execFileAsync("git", ["-C", cwd, ...args], { cwd });
 }
+async function readGitStdout(args, cwd) {
+    const output = await runGit(args, cwd);
+    return output.stdout.trim() || null;
+}
+function stableStringify(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
+    }
+    if (value && typeof value === "object") {
+        const rec = value;
+        return `{${Object.keys(rec).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(rec[key])}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+function formatBranchForMessage(branch) {
+    return branch && branch.length > 0 ? branch : "<detached>";
+}
+function fingerprintWorkspaceBranchIncoherence(input) {
+    const digest = createHash("sha256")
+        .update(stableStringify({
+        version: 1,
+        reason: WORKSPACE_BRANCH_INCOHERENCE_REASON,
+        sourceIssueId: input.sourceIssueId,
+        executionWorkspaceId: input.executionWorkspaceId,
+        worktreePath: path.resolve(input.worktreePath),
+        expectedBranch: input.expectedBranch,
+        actualBranch: input.actualBranch,
+        cleanliness: input.cleanliness,
+        expectedHeadSha: input.expectedHeadSha,
+        actualHeadSha: input.actualHeadSha,
+    }))
+        .digest("hex");
+    return `workspace_incoherence:v1:sha256:${digest}`;
+}
+async function getGitWorktreeBranchAncestryVerdict(input) {
+    if (!input.expectedHeadSha || !input.actualHeadSha)
+        return "unknown";
+    try {
+        await runGit(["merge-base", "--is-ancestor", input.expectedHeadSha, input.actualHeadSha], input.repoRoot);
+        return "ancestor";
+    }
+    catch (error) {
+        const code = typeof error === "object" && error && "code" in error
+            ? error.code
+            : null;
+        return code === 1 ? "diverged" : "unknown";
+    }
+}
+function explainGitWorktreeBranchReconcileInspection(input) {
+    if (!input.fromSha || !input.toSha) {
+        return `Paperclip could not determine branch ancestry because "${input.fromBranch}" or "${input.toBranch}" is missing a resolvable HEAD commit.`;
+    }
+    if (input.fromSha === input.toSha) {
+        return `The recorded branch "${input.fromBranch}" and checked-out branch "${input.toBranch}" resolve to the same commit.`;
+    }
+    if (input.ancestryVerdict === "ancestor") {
+        return `The recorded branch "${input.fromBranch}" is an ancestor of the checked-out branch "${input.toBranch}".`;
+    }
+    if (input.ancestryVerdict === "diverged") {
+        return `The recorded branch "${input.fromBranch}" is not an ancestor of the checked-out branch "${input.toBranch}".`;
+    }
+    return `Paperclip could not determine whether "${input.toBranch}" is forward of "${input.fromBranch}".`;
+}
+async function inspectExecutionWorkspaceBranchForReconcile(workspace) {
+    const fromBranch = readNullableString(workspace.branchName);
+    if (!fromBranch) {
+        throw unprocessable("Execution workspace has no recorded branch to reconcile");
+    }
+    const worktreePath = readNullableString(workspace.providerRef) ?? readNullableString(workspace.cwd);
+    if (!worktreePath) {
+        throw unprocessable("Execution workspace needs a local worktree path before Paperclip can reconcile its branch record");
+    }
+    const repoRoot = await readGitStdout(["rev-parse", "--show-toplevel"], worktreePath).catch(() => null);
+    if (!repoRoot) {
+        throw unprocessable("Execution workspace path is not inside a git repository");
+    }
+    const toBranch = await readGitStdout(["symbolic-ref", "--quiet", "--short", "HEAD"], worktreePath).catch(() => null);
+    if (!toBranch) {
+        throw unprocessable("Execution workspace is detached; Paperclip cannot reconcile it to a branch name");
+    }
+    const status = await runGit(["status", "--porcelain", "--untracked-files=all"], worktreePath)
+        .then((output) => output.stdout)
+        .catch(() => null);
+    const statusLines = status === null
+        ? null
+        : status.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+    const cleanliness = status === null ? "unknown" : status.trim().length > 0 ? "dirty" : "clean";
+    const fromSha = await readGitStdout(["rev-parse", "--verify", `refs/heads/${fromBranch}^{commit}`], repoRoot)
+        .catch(() => null);
+    const toSha = await readGitStdout(["rev-parse", "HEAD"], worktreePath).catch(() => null);
+    const ancestryVerdict = await getGitWorktreeBranchAncestryVerdict({
+        repoRoot,
+        expectedHeadSha: fromSha,
+        actualHeadSha: toSha,
+    });
+    return {
+        fingerprint: fingerprintWorkspaceBranchIncoherence({
+            sourceIssueId: workspace.sourceIssueId ?? null,
+            executionWorkspaceId: workspace.id,
+            worktreePath,
+            expectedBranch: fromBranch,
+            actualBranch: toBranch,
+            cleanliness,
+            expectedHeadSha: fromSha,
+            actualHeadSha: toSha,
+        }),
+        worktreePath: path.resolve(worktreePath),
+        repoRoot: path.resolve(repoRoot),
+        fromBranch,
+        toBranch,
+        fromSha,
+        toSha,
+        ancestryVerdict,
+        cleanliness,
+        statusEntryCount: statusLines?.length ?? null,
+        plainLanguageReason: explainGitWorktreeBranchReconcileInspection({
+            fromBranch,
+            toBranch,
+            fromSha,
+            toSha,
+            ancestryVerdict,
+        }),
+    };
+}
+function formatBranchReconcileAuditComment(input) {
+    return [
+        "Execution workspace branch reconciled.",
+        "",
+        `- Workspace: \`${input.workspaceId}\``,
+        `- Mode: \`${input.mode}\``,
+        `- From branch: \`${formatBranchForMessage(input.inspection.fromBranch)}\``,
+        `- To branch: \`${formatBranchForMessage(input.inspection.toBranch)}\``,
+        `- From SHA: \`${input.inspection.fromSha ?? "unknown"}\``,
+        `- To SHA: \`${input.inspection.toSha ?? "unknown"}\``,
+        `- Verdict: \`${input.inspection.ancestryVerdict}\``,
+        `- Fingerprint: \`${input.inspection.fingerprint}\``,
+        `- Recovery action: ${input.recoveryActionId ? `\`${input.recoveryActionId}\`` : "none matched"}`,
+        ...(input.rescueRef
+            ? [
+                `- Rescue ref: \`${input.rescueRef.branchName}\``,
+                `- Rescue commit: \`${input.rescueRef.commitSha}\``,
+                `- Rescued file count: \`${input.rescueRef.fileCount}\``,
+            ]
+            : []),
+        ...(input.reason ? [`- Operator reason: ${input.reason}`] : []),
+    ].join("\n");
+}
+function isWorkspaceRuntimeValidationFailure(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const maybe = error;
+    return maybe.code === "workspace_validation_failed" &&
+        typeof maybe.message === "string" &&
+        Boolean(maybe.resultJson) &&
+        typeof maybe.resultJson === "object" &&
+        !Array.isArray(maybe.resultJson);
+}
+function assertBranchReconcileWorkspaceIsSafe(input) {
+    const allowedStatuses = input.allowActiveWorkspace ? ["idle", "active"] : ["idle"];
+    if (!allowedStatuses.includes(input.workspaceStatus)) {
+        throw unprocessable("Execution workspace branch reconciliation requires the workspace to be idle", {
+            workspaceStatus: input.workspaceStatus,
+            inspection: input.inspection,
+        });
+    }
+    if (input.inspection.cleanliness !== "clean") {
+        throw unprocessable("Execution workspace branch reconciliation requires a clean worktree", {
+            inspection: input.inspection,
+        });
+    }
+    assertBranchReconcileRuntimeServicesStopped({
+        inspection: input.inspection,
+        runtimeServices: input.runtimeServices,
+    });
+}
+function assertBranchReconcileRuntimeServicesStopped(input) {
+    const activeRuntimeServices = input.runtimeServices.filter((service) => service.status !== "stopped");
+    if (activeRuntimeServices.length > 0) {
+        throw unprocessable("Execution workspace branch reconciliation requires all runtime services to be stopped", {
+            inspection: input.inspection,
+            runtimeServices: activeRuntimeServices.map((service) => ({
+                id: service.id,
+                serviceName: service.serviceName,
+                status: service.status,
+            })),
+        });
+    }
+}
+function assertLockedBranchReconcileWorkspaceStillMatchesInspection(input) {
+    const lockedPath = readNullableString(input.lockedRow.providerRef) ?? readNullableString(input.lockedRow.cwd);
+    const lockedBranch = readNullableString(input.lockedRow.branchName);
+    const currentPath = lockedPath ? path.resolve(lockedPath) : null;
+    if (input.lockedRow.sourceIssueId !== input.inspectedRow.sourceIssueId ||
+        input.lockedRow.projectWorkspaceId !== input.inspectedRow.projectWorkspaceId ||
+        lockedBranch !== input.inspection.fromBranch ||
+        currentPath !== input.inspection.worktreePath) {
+        throw conflict("Execution workspace changed during branch reconciliation; retry with the latest workspace state", {
+            workspaceId: input.lockedRow.id,
+            expected: {
+                status: input.inspectedRow.status,
+                sourceIssueId: input.inspectedRow.sourceIssueId,
+                projectWorkspaceId: input.inspectedRow.projectWorkspaceId,
+                branchName: input.inspection.fromBranch,
+                worktreePath: input.inspection.worktreePath,
+            },
+            current: {
+                status: input.lockedRow.status,
+                sourceIssueId: input.lockedRow.sourceIssueId,
+                projectWorkspaceId: input.lockedRow.projectWorkspaceId,
+                branchName: lockedBranch,
+                worktreePath: currentPath,
+            },
+        });
+    }
+}
+async function quarantineRestoreDirtyWorkspaceBranch(input) {
+    const sourceIssue = await input.db
+        .select({
+        id: issues.id,
+        identifier: issues.identifier,
+        title: issues.title,
+        workMode: issues.workMode,
+    })
+        .from(issues)
+        .where(eq(issues.id, input.workspace.sourceIssueId))
+        .then((rows) => rows[0] ?? null);
+    if (!sourceIssue)
+        throw notFound("Source issue not found");
+    const { ensureGitWorktreeBranchCoherent } = await import("./workspace-runtime.js");
+    try {
+        const result = await ensureGitWorktreeBranchCoherent({
+            db: input.db,
+            repoRoot: input.inspection.repoRoot,
+            worktreePath: input.inspection.worktreePath,
+            expectedBranchName: input.inspection.fromBranch,
+            actualBranchName: input.inspection.toBranch,
+            sourceIssue,
+            executionWorkspaceId: input.workspace.id,
+            heartbeatRunId: input.actor.runId,
+            enableWorkspaceBranchReconcileForward: false,
+            enableWorkspaceDirtyQuarantineRepair: true,
+            persistForwardReconcile: false,
+            reconcileOperationPhase: "worktree_prepare",
+            recorder: null,
+        });
+        if (!result.dirtyQuarantineRepair) {
+            throw unprocessable("Quarantine restore requires a dirty foreign-branch worktree to repair", {
+                inspection: input.inspection,
+            });
+        }
+        return {
+            branchName: result.dirtyQuarantineRepair.rescueBranch,
+            commitSha: result.dirtyQuarantineRepair.rescueCommitSha,
+            fileCount: result.dirtyQuarantineRepair.fileCount,
+            sourceAuditCommentId: result.dirtyQuarantineRepair.sourceAuditCommentId,
+            claimantAuditCommentId: result.dirtyQuarantineRepair.claimantAuditCommentId,
+        };
+    }
+    catch (error) {
+        if (isWorkspaceRuntimeValidationFailure(error)) {
+            throw unprocessable(error.message, {
+                code: error.code,
+                ...error.resultJson,
+            });
+        }
+        throw error;
+    }
+}
 async function inspectGitCloseReadiness(workspace) {
     const warnings = [];
     const workspacePath = readNullableString(workspace.providerRef) ?? readNullableString(workspace.cwd);
@@ -342,6 +637,13 @@ function usesInheritedProjectRuntimeServices(row) {
         return false;
     return !readExecutionWorkspaceConfig(row.metadata ?? null)?.workspaceRuntime;
 }
+function noActiveRuntimeServicesForWorkspaceCondition(row) {
+    const inheritedProjectWorkspaceId = usesInheritedProjectRuntimeServices(row) ? row.projectWorkspaceId : null;
+    const activeServiceConditions = inheritedProjectWorkspaceId
+        ? and(eq(workspaceRuntimeServices.companyId, row.companyId), eq(workspaceRuntimeServices.projectWorkspaceId, inheritedProjectWorkspaceId), eq(workspaceRuntimeServices.scopeType, "project_workspace"), ne(workspaceRuntimeServices.status, "stopped"))
+        : and(eq(workspaceRuntimeServices.companyId, row.companyId), eq(workspaceRuntimeServices.executionWorkspaceId, row.id), ne(workspaceRuntimeServices.status, "stopped"));
+    return sql `not exists (select 1 from ${workspaceRuntimeServices} where ${activeServiceConditions})`;
+}
 async function loadEffectiveRuntimeServicesByExecutionWorkspace(db, companyId, rows) {
     const executionRuntimeServices = await listCurrentRuntimeServicesForExecutionWorkspaces(db, companyId, rows.map((row) => row.id));
     const projectWorkspaceIds = rows
@@ -357,6 +659,7 @@ async function loadEffectiveRuntimeServicesByExecutionWorkspace(db, companyId, r
     ]));
 }
 export function executionWorkspaceService(db) {
+    const recoveryActionsSvc = issueRecoveryActionService(db);
     function buildListConditions(companyId, filters) {
         const conditions = [eq(executionWorkspaces.companyId, companyId)];
         if (filters?.projectId)
@@ -463,7 +766,7 @@ export function executionWorkspaceService(db) {
                     count: sql `count(*)::int`,
                 })
                     .from(issues)
-                    .where(and(eq(issues.companyId, companyId), isNull(issues.hiddenAt), inArray(issues.executionWorkspaceId, workspaceIds)))
+                    .where(and(eq(issues.companyId, companyId), visibleIssueCondition(), inArray(issues.executionWorkspaceId, workspaceIds)))
                     .groupBy(issues.executionWorkspaceId),
                 db.execute(sql `
           select
@@ -587,6 +890,92 @@ export function executionWorkspaceService(db) {
                 .orderBy(desc(executionWorkspaces.lastUsedAt), desc(executionWorkspaces.createdAt));
             return rows.map((row) => toExecutionWorkspaceSummary(row));
         },
+        findGitWorktreeContention: async (input) => {
+            const resolvedWorktreePath = path.resolve(input.worktreePath);
+            const pathOrBranchConditions = [
+                eq(executionWorkspaces.providerRef, input.worktreePath),
+                eq(executionWorkspaces.cwd, input.worktreePath),
+            ];
+            if (input.liveBranchName) {
+                pathOrBranchConditions.push(eq(executionWorkspaces.branchName, input.liveBranchName));
+            }
+            const candidates = await db
+                .select({
+                id: executionWorkspaces.id,
+                cwd: executionWorkspaces.cwd,
+                providerRef: executionWorkspaces.providerRef,
+                branchName: executionWorkspaces.branchName,
+                sourceIssueId: executionWorkspaces.sourceIssueId,
+                sourceIssueIdentifier: issues.identifier,
+            })
+                .from(executionWorkspaces)
+                .leftJoin(issues, and(eq(issues.companyId, executionWorkspaces.companyId), eq(issues.id, executionWorkspaces.sourceIssueId)))
+                .where(and(eq(executionWorkspaces.companyId, input.companyId), isNull(executionWorkspaces.closedAt), ne(executionWorkspaces.status, "archived"), input.excludingExecutionWorkspaceId
+                ? ne(executionWorkspaces.id, input.excludingExecutionWorkspaceId)
+                : sql `true`, or(...pathOrBranchConditions)))
+                .orderBy(desc(executionWorkspaces.lastUsedAt), desc(executionWorkspaces.updatedAt))
+                .limit(20);
+            for (const candidate of candidates) {
+                const candidatePath = readNullableString(candidate.providerRef) ?? readNullableString(candidate.cwd);
+                const matchesPath = candidatePath ? path.resolve(candidatePath) === resolvedWorktreePath : false;
+                const matchesBranch = Boolean(input.liveBranchName && candidate.branchName === input.liveBranchName);
+                if (!matchesPath && !matchesBranch)
+                    continue;
+                const linkedIssueConditions = [eq(issues.executionWorkspaceId, candidate.id)];
+                if (candidate.sourceIssueId)
+                    linkedIssueConditions.push(eq(issues.id, candidate.sourceIssueId));
+                const linkedIssueRows = await db
+                    .select({
+                    id: issues.id,
+                    identifier: issues.identifier,
+                    checkoutRunId: issues.checkoutRunId,
+                    executionRunId: issues.executionRunId,
+                })
+                    .from(issues)
+                    .where(and(eq(issues.companyId, input.companyId), isNull(issues.hiddenAt), linkedIssueConditions.length === 1 ? linkedIssueConditions[0] : or(...linkedIssueConditions)))
+                    .orderBy(desc(issues.updatedAt))
+                    .limit(20);
+                const runToIssue = new Map();
+                for (const issue of linkedIssueRows) {
+                    if (issue.executionRunId)
+                        runToIssue.set(issue.executionRunId, { id: issue.id, identifier: issue.identifier ?? null });
+                    if (issue.checkoutRunId)
+                        runToIssue.set(issue.checkoutRunId, { id: issue.id, identifier: issue.identifier ?? null });
+                }
+                let activeRun = null;
+                const runIds = [...runToIssue.keys()];
+                if (runIds.length > 0) {
+                    const [row] = await db
+                        .select({
+                        id: heartbeatRuns.id,
+                        status: heartbeatRuns.status,
+                    })
+                        .from(heartbeatRuns)
+                        .where(and(eq(heartbeatRuns.companyId, input.companyId), inArray(heartbeatRuns.id, runIds), inArray(heartbeatRuns.status, ["queued", "running"])))
+                        .orderBy(desc(heartbeatRuns.startedAt), desc(heartbeatRuns.createdAt))
+                        .limit(1);
+                    if (row && (row.status === "queued" || row.status === "running")) {
+                        const issue = runToIssue.get(row.id) ?? null;
+                        activeRun = {
+                            id: row.id,
+                            status: row.status,
+                            issueId: issue?.id ?? null,
+                            issueIdentifier: issue?.identifier ?? null,
+                        };
+                    }
+                }
+                const claimedIssue = linkedIssueRows.find((issue) => issue.id === candidate.sourceIssueId)
+                    ?? linkedIssueRows[0]
+                    ?? null;
+                return {
+                    claimedByWorkspaceId: candidate.id,
+                    claimedByIssueId: claimedIssue?.id ?? candidate.sourceIssueId ?? null,
+                    claimedByIssueIdentifier: claimedIssue?.identifier ?? candidate.sourceIssueIdentifier ?? null,
+                    activeRun,
+                };
+            }
+            return null;
+        },
         getById: async (id) => {
             const row = await db
                 .select()
@@ -822,6 +1211,248 @@ export function executionWorkspaceService(db) {
                 .then((rows) => rows[0] ?? null);
             return row ? toExecutionWorkspace(row) : null;
         },
+        reconcileExecutionWorkspaceBranch: async (id, input) => {
+            const existingRow = await db
+                .select()
+                .from(executionWorkspaces)
+                .where(eq(executionWorkspaces.id, id))
+                .then((rows) => rows[0] ?? null);
+            if (!existingRow)
+                throw notFound("Execution workspace not found");
+            const existing = toExecutionWorkspace(existingRow);
+            if (!existing.sourceIssueId) {
+                throw unprocessable("Execution workspace needs a source issue before Paperclip can audit branch reconciliation");
+            }
+            const inspection = await inspectExecutionWorkspaceBranchForReconcile(existing);
+            if (input.mode === "forward" && inspection.ancestryVerdict !== "ancestor") {
+                throw unprocessable("Forward branch reconciliation requires the recorded branch to be an ancestor of the checked-out branch", { inspection });
+            }
+            const reason = readNullableString(input.reason);
+            const rescueRef = input.mode === "quarantine_restore"
+                ? await (async () => {
+                    const runtimeServicesByWorkspaceId = await loadEffectiveRuntimeServicesByExecutionWorkspace(db, existing.companyId, [existingRow]);
+                    assertBranchReconcileRuntimeServicesStopped({
+                        inspection,
+                        runtimeServices: (runtimeServicesByWorkspaceId.get(existing.id) ?? []).map(toRuntimeService),
+                    });
+                    // The git rescue has to happen before the DB transaction because the
+                    // transaction may be retried/rolled back, while git side effects cannot.
+                    // The preflight runtime-service guard above keeps known local services
+                    // from holding files open during the non-transactional git sequence.
+                    return quarantineRestoreDirtyWorkspaceBranch({
+                        db,
+                        workspace: existing,
+                        inspection,
+                        actor: input.actor,
+                    });
+                })()
+                : null;
+            const now = new Date();
+            const allowActiveWorkspace = input.mode === "forward" &&
+                input.actor.actorType === "system" &&
+                input.actor.actorId === "workspace_runtime" &&
+                Boolean(input.actor.runId);
+            return db.transaction(async (tx) => {
+                const txDb = tx;
+                // Runtime-service activation takes this same row lock before spawning
+                // local services and persists a `starting` row before releasing it.
+                const lockedRow = await tx
+                    .select()
+                    .from(executionWorkspaces)
+                    .where(eq(executionWorkspaces.id, existing.id))
+                    .for("update")
+                    .then((rows) => rows[0] ?? null);
+                if (!lockedRow)
+                    throw notFound("Execution workspace not found");
+                assertLockedBranchReconcileWorkspaceStillMatchesInspection({
+                    lockedRow,
+                    inspectedRow: existingRow,
+                    inspection,
+                });
+                if (usesInheritedProjectRuntimeServices(lockedRow)) {
+                    await tx
+                        .select({ id: projectWorkspaces.id })
+                        .from(projectWorkspaces)
+                        .where(and(eq(projectWorkspaces.companyId, lockedRow.companyId), eq(projectWorkspaces.id, lockedRow.projectWorkspaceId)))
+                        .for("update");
+                }
+                await tx
+                    .select({ id: workspaceRuntimeServices.id })
+                    .from(workspaceRuntimeServices)
+                    .where(usesInheritedProjectRuntimeServices(lockedRow)
+                    ? and(eq(workspaceRuntimeServices.companyId, lockedRow.companyId), eq(workspaceRuntimeServices.projectWorkspaceId, lockedRow.projectWorkspaceId), eq(workspaceRuntimeServices.scopeType, "project_workspace"))
+                    : and(eq(workspaceRuntimeServices.companyId, lockedRow.companyId), eq(workspaceRuntimeServices.executionWorkspaceId, lockedRow.id)))
+                    .for("update");
+                const lockedRuntimeServicesByWorkspaceId = await loadEffectiveRuntimeServicesByExecutionWorkspace(txDb, lockedRow.companyId, [lockedRow]);
+                const lockedRuntimeServices = (lockedRuntimeServicesByWorkspaceId.get(lockedRow.id) ?? []).map(toRuntimeService);
+                const lockedWorkspace = toExecutionWorkspace(lockedRow, lockedRuntimeServices);
+                if (!lockedWorkspace.sourceIssueId) {
+                    throw unprocessable("Execution workspace needs a source issue before Paperclip can audit branch reconciliation");
+                }
+                let updatedRow = lockedRow;
+                if (input.mode !== "quarantine_restore") {
+                    assertBranchReconcileWorkspaceIsSafe({
+                        workspaceStatus: lockedWorkspace.status,
+                        inspection,
+                        runtimeServices: lockedRuntimeServices,
+                        allowActiveWorkspace,
+                    });
+                    if (lockedWorkspace.branchName !== inspection.fromBranch) {
+                        throw unprocessable("Execution workspace branch changed during reconciliation; retry with a fresh inspection", {
+                            workspaceBranch: lockedWorkspace.branchName,
+                            inspection,
+                        });
+                    }
+                    const updatePatch = {
+                        branchName: inspection.toBranch,
+                        updatedAt: now,
+                    };
+                    if (lockedWorkspace.name === inspection.fromBranch) {
+                        updatePatch.name = inspection.toBranch;
+                    }
+                    const [branchUpdatedRow] = await tx
+                        .update(executionWorkspaces)
+                        .set(updatePatch)
+                        .where(and(eq(executionWorkspaces.id, lockedWorkspace.id), allowActiveWorkspace
+                        ? inArray(executionWorkspaces.status, ["idle", "active"])
+                        : eq(executionWorkspaces.status, "idle"), eq(executionWorkspaces.branchName, inspection.fromBranch), noActiveRuntimeServicesForWorkspaceCondition(lockedRow)))
+                        .returning();
+                    if (!branchUpdatedRow) {
+                        const latestRuntimeServicesByWorkspaceId = await loadEffectiveRuntimeServicesByExecutionWorkspace(txDb, lockedRow.companyId, [lockedRow]);
+                        const latestRuntimeServices = (latestRuntimeServicesByWorkspaceId.get(lockedRow.id) ?? []).map(toRuntimeService);
+                        assertBranchReconcileWorkspaceIsSafe({
+                            workspaceStatus: lockedWorkspace.status,
+                            inspection,
+                            runtimeServices: latestRuntimeServices,
+                            allowActiveWorkspace,
+                        });
+                        throw unprocessable("Execution workspace branch reconciliation requires the workspace to stay idle with stopped runtime services during the update", {
+                            inspection,
+                        });
+                    }
+                    updatedRow = branchUpdatedRow;
+                }
+                let recoveryAction = await recoveryActionsSvc.resolveActiveForIssue({
+                    companyId: lockedWorkspace.companyId,
+                    sourceIssueId: lockedWorkspace.sourceIssueId,
+                    kind: "workspace_validation",
+                    cause: WORKSPACE_VALIDATION_RECOVERY_CAUSE,
+                    fingerprint: inspection.fingerprint,
+                    status: "resolved",
+                    outcome: "restored",
+                    resolutionNote: input.mode === "quarantine_restore" && rescueRef
+                        ? `Execution workspace dirty worktree quarantined on "${rescueRef.branchName}" and restored recorded branch "${inspection.fromBranch}".`
+                        : `Execution workspace branch record reconciled from "${inspection.fromBranch}" to "${inspection.toBranch}".`,
+                }, tx);
+                if (!recoveryAction) {
+                    for (const alternateFingerprint of input.alternateRecoveryFingerprints ?? []) {
+                        if (!alternateFingerprint || alternateFingerprint === inspection.fingerprint)
+                            continue;
+                        recoveryAction = await recoveryActionsSvc.resolveActiveForIssue({
+                            companyId: existing.companyId,
+                            sourceIssueId: existing.sourceIssueId,
+                            kind: "workspace_validation",
+                            cause: WORKSPACE_VALIDATION_RECOVERY_CAUSE,
+                            fingerprint: alternateFingerprint,
+                            status: "resolved",
+                            outcome: "restored",
+                            resolutionNote: input.mode === "quarantine_restore" && rescueRef
+                                ? `Execution workspace dirty worktree quarantined on "${rescueRef.branchName}" and restored recorded branch "${inspection.fromBranch}".`
+                                : `Execution workspace branch record reconciled from "${inspection.fromBranch}" to "${inspection.toBranch}".`,
+                        }, tx);
+                        if (recoveryAction)
+                            break;
+                    }
+                }
+                let restoredSourceIssue = null;
+                let sourceIssueStatusChanged = false;
+                if (input.mode === "quarantine_restore") {
+                    const [sourceBefore] = await tx
+                        .select({
+                        id: issues.id,
+                        companyId: issues.companyId,
+                        status: issues.status,
+                        assigneeAgentId: issues.assigneeAgentId,
+                        assigneeUserId: issues.assigneeUserId,
+                        executionPolicy: issues.executionPolicy,
+                        executionState: issues.executionState,
+                        monitorNextCheckAt: issues.monitorNextCheckAt,
+                        monitorWakeRequestedAt: issues.monitorWakeRequestedAt,
+                        monitorLastTriggeredAt: issues.monitorLastTriggeredAt,
+                        monitorAttemptCount: issues.monitorAttemptCount,
+                        monitorNotes: issues.monitorNotes,
+                        monitorScheduledBy: issues.monitorScheduledBy,
+                    })
+                        .from(issues)
+                        .where(eq(issues.id, lockedWorkspace.sourceIssueId))
+                        .for("update");
+                    if (!sourceBefore)
+                        throw notFound("Source issue not found");
+                    const requestedStatus = quarantineRestoreRequestedSourceStatus(sourceBefore);
+                    const policy = normalizeIssueExecutionPolicy(sourceBefore.executionPolicy ?? null);
+                    const transition = applyIssueExecutionPolicyTransition({
+                        issue: sourceBefore,
+                        policy,
+                        previousPolicy: policy,
+                        requestedStatus,
+                        requestedAssigneePatch: {},
+                        actor: {
+                            agentId: input.actor.agentId ?? null,
+                            userId: input.actor.actorType === "user" ? input.actor.actorId : null,
+                        },
+                        commentBody: null,
+                    });
+                    const { issueService } = await import("./issues.js");
+                    const updatedIssue = await issueService(db).update(lockedWorkspace.sourceIssueId, {
+                        ...(requestedStatus ? { status: requestedStatus } : {}),
+                        ...transition.patch,
+                        actorAgentId: input.actor.agentId ?? null,
+                        actorUserId: input.actor.actorType === "user" ? input.actor.actorId : null,
+                    }, tx);
+                    if (!updatedIssue)
+                        throw notFound("Source issue not found");
+                    restoredSourceIssue = {
+                        id: updatedIssue.id,
+                        companyId: updatedIssue.companyId,
+                        status: updatedIssue.status,
+                        assigneeAgentId: updatedIssue.assigneeAgentId,
+                    };
+                    sourceIssueStatusChanged = sourceBefore.status !== updatedIssue.status;
+                }
+                const [auditComment] = await tx
+                    .insert(issueComments)
+                    .values({
+                    companyId: lockedWorkspace.companyId,
+                    issueId: lockedWorkspace.sourceIssueId,
+                    authorAgentId: input.actor.actorType === "agent" ? input.actor.agentId : null,
+                    authorUserId: input.actor.actorType === "user" ? input.actor.actorId : null,
+                    authorType: input.actor.actorType,
+                    createdByRunId: input.actor.runId,
+                    body: formatBranchReconcileAuditComment({
+                        mode: input.mode,
+                        reason,
+                        workspaceId: existing.id,
+                        inspection,
+                        recoveryActionId: recoveryAction?.id ?? null,
+                        rescueRef,
+                    }),
+                })
+                    .returning({ id: issueComments.id });
+                await tx
+                    .update(issues)
+                    .set({ updatedAt: now })
+                    .where(eq(issues.id, lockedWorkspace.sourceIssueId));
+                return {
+                    workspace: toExecutionWorkspace(updatedRow, lockedRuntimeServices),
+                    inspection,
+                    recoveryAction,
+                    auditCommentId: auditComment?.id ?? null,
+                    rescueRef,
+                    restoredSourceIssue,
+                    sourceIssueStatusChanged,
+                };
+            });
+        },
         clearEnvironmentSelection: async (companyId, environmentId) => {
             return db.transaction(async (tx) => {
                 const rows = await tx