@penclipai/server 2026.704.0 → 2026.714.0

package/dist/services/workspace-runtime.js

@@ -5,13 +5,14 @@ import net from "node:net";
 import { createHash, randomUUID } from "node:crypto";
 import path from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
-import { executionWorkspaces, projectWorkspaces, workspaceRuntimeServices } from "@penclipai/db";
+import { executionWorkspaces, issueComments, issues, projectWorkspaces, workspaceRuntimeServices } from "@penclipai/db";
 import { listWorkspaceServiceCommandDefinitions, } from "@penclipai/shared";
-import { and, desc, eq, inArray } from "drizzle-orm";
+import { and, desc, eq, inArray, ne } from "drizzle-orm";
 import { asNumber, asString, parseObject, renderTemplate } from "../adapters/utils.js";
 import { resolveHomeAwarePath } from "../home-paths.js";
-import { createLocalServiceKey, findLocalServiceRegistryRecordByRuntimeServiceId, findAdoptableLocalService, readLocalServicePortOwner, removeLocalServiceRegistryRecord, terminateLocalService, touchLocalServiceRegistryRecord, writeLocalServiceRegistryRecord, } from "./local-service-supervisor.js";
-import { readExecutionWorkspaceConfig } from "./execution-workspaces.js";
+import { createLocalServiceKey, findLocalServiceRegistryRecordByRuntimeServiceId, findAdoptableLocalService, isLocalServiceProcessInWorkspace, readLocalServiceProcessCwd, readLocalServicePortOwner, removeLocalServiceRegistryRecord, terminateLocalService, touchLocalServiceRegistryRecord, writeLocalServiceRegistryRecord, } from "./local-service-supervisor.js";
+import { executionWorkspaceService, readExecutionWorkspaceConfig } from "./execution-workspaces.js";
+import { logActivity } from "./activity-log.js";
 import { readProjectWorkspaceRuntimeConfig } from "./project-workspace-runtime-config.js";
 export function resolveShell() {
     const windowsGitBash = "C:\\Program Files\\Git\\bin\\bash.exe";
@@ -466,6 +467,150 @@ const GIT_WORKTREE_BRANCH_INCOHERENCE_REASON = "git_worktree_branch_incoherence"
 function formatBranchForMessage(branch) {
     return branch && branch.length > 0 ? branch : "<detached>";
 }
+const GIT_IN_PROGRESS_OPERATION_MARKERS = [
+    { operation: "rebase", marker: "rebase-merge" },
+    { operation: "rebase", marker: "rebase-apply" },
+    { operation: "merge", marker: "MERGE_HEAD" },
+    { operation: "cherry_pick", marker: "CHERRY_PICK_HEAD" },
+    { operation: "revert", marker: "REVERT_HEAD" },
+    { operation: "bisect", marker: "BISECT_LOG" },
+];
+const GIT_IN_PROGRESS_OPERATION_LABELS = {
+    rebase: "rebase",
+    merge: "merge",
+    cherry_pick: "cherry-pick",
+    revert: "revert",
+    bisect: "bisect",
+};
+// `--quit` clears the interrupted operation's state directory without touching
+// the working tree or moving HEAD, unlike `--abort` which resets both.
+const GIT_IN_PROGRESS_OPERATION_QUIT_ARGS = {
+    rebase: ["rebase", "--quit"],
+    merge: ["merge", "--quit"],
+    cherry_pick: ["cherry-pick", "--quit"],
+    revert: ["revert", "--quit"],
+    bisect: ["bisect", "reset", "HEAD"],
+};
+async function detectGitWorktreeInProgressOperation(worktreePath) {
+    for (const { operation, marker } of GIT_IN_PROGRESS_OPERATION_MARKERS) {
+        const markerPath = await runGit(["rev-parse", "--git-path", marker], worktreePath).catch(() => null);
+        if (!markerPath)
+            continue;
+        if (existsSync(path.resolve(worktreePath, markerPath)))
+            return operation;
+    }
+    return null;
+}
+const DIRTY_PATH_SAMPLE_LIMIT = 5;
+function parseGitPorcelainPath(line) {
+    const raw = line.trimEnd();
+    if (raw.trim().length <= 3)
+        return raw.trim();
+    if (raw[1] === " " && raw[2] !== " ")
+        return raw.slice(2).trim();
+    return raw.slice(3).trim();
+}
+function sampleDirtyStatusPaths(statusLines) {
+    return (statusLines ?? [])
+        .map(parseGitPorcelainPath)
+        .filter((value) => value.length > 0)
+        .slice(0, DIRTY_PATH_SAMPLE_LIMIT);
+}
+function formatUtcBranchTimestamp(date = new Date()) {
+    return date.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
+}
+function buildDirtyQuarantineRescueBranch(sourceIssue) {
+    const issueComponent = sanitizeBranchName(sourceIssue?.identifier ?? sourceIssue?.id ?? "issue");
+    return sanitizeBranchName(`paperclip/rescue/${issueComponent}/${formatUtcBranchTimestamp()}`);
+}
+function formatIssueReference(issueId, identifier) {
+    if (!identifier)
+        return issueId ? `\`${issueId}\`` : "`unknown`";
+    const match = identifier.match(/^([A-Z]+)-\d+$/);
+    if (!match)
+        return `\`${identifier}\``;
+    return `[${identifier}](/${match[1]}/issues/${identifier})`;
+}
+async function readIssueCompanyId(db, issueId) {
+    if (!issueId)
+        return null;
+    return db
+        .select({ companyId: issues.companyId })
+        .from(issues)
+        .where(eq(issues.id, issueId))
+        .then((rows) => rows[0]?.companyId ?? null);
+}
+async function findGitWorktreeBranchContention(input) {
+    if (!input.db)
+        return null;
+    const companyId = await readIssueCompanyId(input.db, input.sourceIssue?.id);
+    if (!companyId)
+        return null;
+    return executionWorkspaceService(input.db).findGitWorktreeContention({
+        companyId,
+        worktreePath: input.worktreePath,
+        liveBranchName: input.actualBranchName,
+        excludingExecutionWorkspaceId: input.executionWorkspaceId,
+    });
+}
+function executionWorkspaceUsesInheritedProjectRuntimeServices(row) {
+    if (row.mode !== "shared_workspace" || !row.projectWorkspaceId)
+        return false;
+    return !readExecutionWorkspaceConfig(row.metadata ?? null)?.workspaceRuntime;
+}
+async function findActiveRuntimeServiceBlockingDirtyQuarantine(input) {
+    const inheritedProjectWorkspaceId = executionWorkspaceUsesInheritedProjectRuntimeServices(input.workspace)
+        ? input.workspace.projectWorkspaceId
+        : null;
+    const serviceScopeCondition = inheritedProjectWorkspaceId
+        ? and(eq(workspaceRuntimeServices.companyId, input.workspace.companyId), eq(workspaceRuntimeServices.projectWorkspaceId, inheritedProjectWorkspaceId), eq(workspaceRuntimeServices.scopeType, "project_workspace"))
+        : and(eq(workspaceRuntimeServices.companyId, input.workspace.companyId), eq(workspaceRuntimeServices.executionWorkspaceId, input.workspace.id));
+    const [service] = await input.db
+        .select({
+        id: workspaceRuntimeServices.id,
+        serviceName: workspaceRuntimeServices.serviceName,
+        status: workspaceRuntimeServices.status,
+        scopeType: workspaceRuntimeServices.scopeType,
+    })
+        .from(workspaceRuntimeServices)
+        .where(and(serviceScopeCondition, ne(workspaceRuntimeServices.status, "stopped")))
+        .orderBy(desc(workspaceRuntimeServices.updatedAt), desc(workspaceRuntimeServices.createdAt))
+        .limit(1);
+    return service ?? null;
+}
+async function assertDirtyQuarantineRuntimeServicesStopped(input) {
+    if (!input.executionWorkspaceId) {
+        input.evidence.safeRepair.eligible = false;
+        input.evidence.safeRepair.reason = "dirty quarantine repair requires an execution workspace id for runtime-service checks";
+        throw branchIncoherenceValidationFailure(input.evidence);
+    }
+    const [workspace] = await input.db
+        .select()
+        .from(executionWorkspaces)
+        .where(eq(executionWorkspaces.id, input.executionWorkspaceId));
+    if (!workspace) {
+        input.evidence.safeRepair.eligible = false;
+        input.evidence.safeRepair.reason = "dirty quarantine repair requires a persisted execution workspace for runtime-service checks";
+        throw branchIncoherenceValidationFailure(input.evidence);
+    }
+    const activeService = await findActiveRuntimeServiceBlockingDirtyQuarantine({
+        db: input.db,
+        workspace,
+    });
+    if (!activeService)
+        return;
+    input.evidence.safeRepair.eligible = false;
+    input.evidence.safeRepair.reason =
+        `dirty quarantine repair requires runtime service "${activeService.serviceName}" (${activeService.id}) to be stopped; current status is ${activeService.status}`;
+    throw branchIncoherenceValidationFailure(input.evidence);
+}
+async function assertGitIndexIsUnlocked(worktreePath) {
+    const indexLockPath = await runGit(["rev-parse", "--git-path", "index.lock"], worktreePath)
+        .catch(() => null);
+    if (indexLockPath && existsSync(indexLockPath)) {
+        throw new Error(`git index lock exists at ${indexLockPath}`);
+    }
+}
 function fingerprintWorkspaceBranchIncoherence(input) {
     const digest = createHash("sha256")
         .update(stableStringify({
@@ -483,12 +628,46 @@ function fingerprintWorkspaceBranchIncoherence(input) {
         .digest("hex");
     return `workspace_incoherence:v1:sha256:${digest}`;
 }
+async function getGitWorktreeBranchAncestryVerdict(input) {
+    if (!input.expectedHeadSha || !input.actualHeadSha)
+        return "unknown";
+    const proc = await executeProcess({
+        command: "git",
+        args: ["merge-base", "--is-ancestor", input.expectedHeadSha, input.actualHeadSha],
+        cwd: input.repoRoot,
+    }).catch(() => null);
+    if (!proc)
+        return "unknown";
+    if (proc.code === 0)
+        return "ancestor";
+    if (proc.code === 1)
+        return "diverged";
+    return "unknown";
+}
+function explainGitWorktreeBranchIncoherence(input) {
+    const actualBranch = formatBranchForMessage(input.actualBranchName);
+    if (!input.expectedHeadSha || !input.actualHeadSha) {
+        return `Paperclip could not determine branch ancestry because the recorded branch "${input.expectedBranchName}" or checked-out branch "${actualBranch}" is missing a resolvable HEAD commit.`;
+    }
+    if (input.sameHead) {
+        return `The recorded branch "${input.expectedBranchName}" and checked-out branch "${actualBranch}" resolve to the same commit, so the mismatch is branch metadata rather than commit divergence.`;
+    }
+    if (input.ancestryVerdict === "ancestor") {
+        return `The recorded branch "${input.expectedBranchName}" is an ancestor of the checked-out branch "${actualBranch}", so the checked-out branch is forward of the recorded branch.`;
+    }
+    if (input.ancestryVerdict === "diverged") {
+        return `The recorded branch "${input.expectedBranchName}" is not an ancestor of the checked-out branch "${actualBranch}", so Paperclip cannot prove a forward-only reconciliation.`;
+    }
+    return `Paperclip could not determine whether the checked-out branch "${actualBranch}" is forward of the recorded branch "${input.expectedBranchName}".`;
+}
 async function inspectGitWorktreeBranchIncoherence(input) {
     const status = await runGit(["status", "--porcelain", "--untracked-files=all"], input.worktreePath).catch(() => null);
     const statusLines = status === null
         ? null
-        : status.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+        : status.split(/\r?\n/).map((line) => line.trimEnd()).filter((line) => line.trim().length > 0);
+    const dirtyPathSample = sampleDirtyStatusPaths(statusLines);
     const cleanliness = status === null ? "unknown" : status.trim().length > 0 ? "dirty" : "clean";
+    const inProgressOperation = await detectGitWorktreeInProgressOperation(input.worktreePath);
     const expectedHeadSha = await runGit(["rev-parse", "--verify", `refs/heads/${input.expectedBranchName}^{commit}`], input.repoRoot).catch(() => null);
     const actualHeadSha = await runGit(["rev-parse", "HEAD"], input.worktreePath).catch(() => null);
     const actualBranchExists = input.actualBranchName
@@ -500,11 +679,46 @@ async function inspectGitWorktreeBranchIncoherence(input) {
     const registeredBranchMatchesHead = Boolean(registered && registeredBranchRef === actualBranchRef);
     const sameHead = Boolean(expectedHeadSha && actualHeadSha && expectedHeadSha === actualHeadSha);
     const expectedBranchExists = Boolean(expectedHeadSha);
-    const eligible = cleanliness === "clean" && expectedBranchExists && sameHead && registeredBranchMatchesHead;
+    const ancestryVerdict = await getGitWorktreeBranchAncestryVerdict({
+        repoRoot: input.repoRoot,
+        expectedHeadSha,
+        actualHeadSha,
+    });
+    const basePlainLanguageReason = explainGitWorktreeBranchIncoherence({
+        expectedBranchName: input.expectedBranchName,
+        actualBranchName: input.actualBranchName,
+        expectedHeadSha,
+        actualHeadSha,
+        sameHead,
+        ancestryVerdict,
+    });
+    const plainLanguageReason = inProgressOperation
+        ? `${basePlainLanguageReason} An interrupted git ${GIT_IN_PROGRESS_OPERATION_LABELS[inProgressOperation]} is still in progress in this worktree.`
+        : basePlainLanguageReason;
+    const canCheckoutRecordedBranch = cleanliness === "clean" && expectedBranchExists && sameHead && registeredBranchMatchesHead;
+    const canAdoptForwardActualBranch = cleanliness === "clean" &&
+        expectedBranchExists &&
+        actualBranchExists === true &&
+        ancestryVerdict === "ancestor" &&
+        !sameHead &&
+        registeredBranchMatchesHead;
+    const canAttachRecordedBranchToDetachedHead = cleanliness === "clean" &&
+        expectedBranchExists &&
+        input.actualBranchName === null &&
+        ancestryVerdict === "ancestor" &&
+        !sameHead &&
+        registeredBranchMatchesHead;
+    const eligible = canCheckoutRecordedBranch || canAdoptForwardActualBranch || canAttachRecordedBranchToDetachedHead;
     const safeRepairReason = eligible
-        ? "clean worktree and expected branch points at the current HEAD"
+        ? canCheckoutRecordedBranch
+            ? "clean worktree and expected branch points at the current HEAD"
+            : canAdoptForwardActualBranch
+                ? "clean worktree and checked-out branch is forward of the recorded branch"
+                : "clean detached worktree HEAD is forward of the recorded branch"
         : cleanliness !== "clean"
-            ? "worktree is not clean"
+            ? inProgressOperation
+                ? `worktree is not clean and a git ${GIT_IN_PROGRESS_OPERATION_LABELS[inProgressOperation]} is in progress`
+                : "worktree is not clean"
             : !registered
                 ? "worktree path is not registered"
                 : !registeredBranchMatchesHead
@@ -524,6 +738,13 @@ async function inspectGitWorktreeBranchIncoherence(input) {
         expectedHeadSha,
         actualHeadSha,
     });
+    const contention = await findGitWorktreeBranchContention({
+        db: input.db ?? null,
+        sourceIssue: input.sourceIssue,
+        executionWorkspaceId: input.executionWorkspaceId ?? null,
+        worktreePath: input.worktreePath,
+        actualBranchName: input.actualBranchName,
+    });
     return {
         reason: GIT_WORKTREE_BRANCH_INCOHERENCE_REASON,
         fingerprint,
@@ -535,7 +756,10 @@ async function inspectGitWorktreeBranchIncoherence(input) {
         expectedBranch: input.expectedBranchName,
         actualBranch: input.actualBranchName,
         cleanliness,
+        inProgressOperation,
         statusEntryCount: statusLines?.length ?? null,
+        dirtyPathSample,
+        contention,
         provenance: {
             expectedBranchRef: `refs/heads/${input.expectedBranchName}`,
             actualBranchRef,
@@ -547,6 +771,8 @@ async function inspectGitWorktreeBranchIncoherence(input) {
             expectedHeadSha,
             actualHeadSha,
             sameHead,
+            ancestryVerdict,
+            plainLanguageReason,
         },
         safeRepair: {
             eligible,
@@ -561,16 +787,465 @@ function branchIncoherenceValidationFailure(evidence) {
         workspaceValidation: evidence,
     });
 }
+function formatDirtyQuarantineContentionRefusal(contention) {
+    const activeRunText = contention.activeRun
+        ? ` with active run ${contention.activeRun.id}`
+        : " with no active run";
+    return `dirty quarantine repair refused because workspace ${contention.claimedByWorkspaceId} already claims the live branch${activeRunText}`;
+}
+function formatDirtyQuarantineFailure(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (gitErrorIncludes(error, "index.lock") ||
+        gitErrorIncludes(error, "index lock") ||
+        gitErrorIncludes(error, "another git process") ||
+        gitErrorIncludes(error, "Unable to create")) {
+        return `dirty quarantine repair aborted because git reported index contention: ${message}`;
+    }
+    return `dirty quarantine repair failed: ${message}`;
+}
+function formatDirtyQuarantineAuditComment(input) {
+    const dirtySample = input.evidence.dirtyPathSample.length > 0
+        ? input.evidence.dirtyPathSample.map((entry) => `\`${entry}\``).join(", ")
+        : "`none captured`";
+    return [
+        "Execution workspace dirty worktree quarantined before restore.",
+        "",
+        `- Source issue: ${formatIssueReference(input.evidence.sourceIssueId, input.evidence.sourceIdentifier ?? input.sourceIssue?.identifier ?? null)}`,
+        `- Workspace: \`${input.evidence.executionWorkspaceId ?? "unpersisted"}\``,
+        `- Worktree: \`${input.evidence.worktreePath}\``,
+        `- Recorded branch: \`${input.evidence.expectedBranch}\``,
+        `- Live branch: \`${formatBranchForMessage(input.evidence.actualBranch)}\``,
+        `- Rescue branch: \`${input.rescueBranch}\``,
+        `- Rescue commit: \`${input.rescueCommitSha}\``,
+        `- Dirty file count: \`${input.fileCount}\``,
+        `- Dirty path sample: ${dirtySample}`,
+        ...(input.evidence.inProgressOperation
+            ? [`- Interrupted operation: \`git ${GIT_IN_PROGRESS_OPERATION_LABELS[input.evidence.inProgressOperation]}\` (state cleared after rescue; resolution preserved on the rescue branch)`]
+            : []),
+        `- Fingerprint: \`${input.evidence.fingerprint}\``,
+        input.claimant
+            ? `- Claimant: workspace \`${input.claimant.claimedByWorkspaceId}\` on issue ${formatIssueReference(input.claimant.claimedByIssueId, input.claimant.claimedByIssueIdentifier)}${input.claimant.activeRun ? ` with active run \`${input.claimant.activeRun.id}\`` : " with no active run"}`
+            : "- Claimant: none",
+    ].join("\n");
+}
+async function writeDirtyQuarantineAuditComments(input) {
+    const body = formatDirtyQuarantineAuditComment({
+        evidence: input.evidence,
+        rescueBranch: input.rescueBranch,
+        rescueCommitSha: input.rescueCommitSha,
+        fileCount: input.fileCount,
+        sourceIssue: input.sourceIssue,
+        claimant: input.evidence.contention,
+    });
+    let sourceAuditCommentId = null;
+    let claimantAuditCommentId = null;
+    const now = new Date();
+    if (input.evidence.sourceIssueId) {
+        const [sourceComment] = await input.db
+            .insert(issueComments)
+            .values({
+            companyId: input.companyId,
+            issueId: input.evidence.sourceIssueId,
+            authorAgentId: null,
+            authorUserId: null,
+            authorType: "system",
+            createdByRunId: input.heartbeatRunId,
+            body,
+        })
+            .returning({ id: issueComments.id });
+        sourceAuditCommentId = sourceComment?.id ?? null;
+        await input.db
+            .update(issues)
+            .set({ updatedAt: now })
+            .where(eq(issues.id, input.evidence.sourceIssueId));
+    }
+    const claimantIssueId = input.evidence.contention?.claimedByIssueId ?? null;
+    if (claimantIssueId && claimantIssueId !== input.evidence.sourceIssueId) {
+        const [claimantComment] = await input.db
+            .insert(issueComments)
+            .values({
+            companyId: input.companyId,
+            issueId: claimantIssueId,
+            authorAgentId: null,
+            authorUserId: null,
+            authorType: "system",
+            createdByRunId: input.heartbeatRunId,
+            body,
+        })
+            .returning({ id: issueComments.id });
+        claimantAuditCommentId = claimantComment?.id ?? null;
+        await input.db
+            .update(issues)
+            .set({ updatedAt: now })
+            .where(eq(issues.id, claimantIssueId));
+    }
+    return { sourceAuditCommentId, claimantAuditCommentId };
+}
+async function logDirtyQuarantineActivity(input) {
+    await logActivity(input.db, {
+        companyId: input.companyId,
+        actorType: "system",
+        actorId: "workspace_runtime",
+        runId: input.heartbeatRunId,
+        action: "execution_workspace.dirty_worktree_quarantined",
+        entityType: input.evidence.executionWorkspaceId ? "execution_workspace" : "issue",
+        entityId: input.evidence.executionWorkspaceId ?? input.evidence.sourceIssueId ?? input.companyId,
+        details: {
+            reason: GIT_WORKTREE_BRANCH_INCOHERENCE_REASON,
+            sourceIssueId: input.evidence.sourceIssueId,
+            executionWorkspaceId: input.evidence.executionWorkspaceId,
+            worktreePath: input.evidence.worktreePath,
+            expectedBranch: input.evidence.expectedBranch,
+            actualBranch: input.evidence.actualBranch,
+            rescueBranch: input.rescueBranch,
+            rescueCommitSha: input.rescueCommitSha,
+            fileCount: input.fileCount,
+            dirtyPathSample: input.evidence.dirtyPathSample,
+            fingerprint: input.evidence.fingerprint,
+            contention: input.evidence.contention,
+            sourceAuditCommentId: input.sourceAuditCommentId,
+            claimantAuditCommentId: input.claimantAuditCommentId,
+            actor: {
+                type: "system",
+                id: "workspace_runtime",
+                source: "workspace_runtime",
+            },
+        },
+    });
+}
+async function recordDirtyQuarantineOperation(input) {
+    if (!input.recorder)
+        return;
+    await input.recorder.recordOperation({
+        phase: input.phase ?? "worktree_prepare",
+        cwd: input.cwd,
+        metadata: {
+            repoRoot: input.evidence.repoRoot,
+            worktreePath: input.evidence.worktreePath,
+            expectedBranchName: input.evidence.expectedBranch,
+            actualBranchName: input.evidence.actualBranch,
+            branchIncoherenceDirtyQuarantineRepair: true,
+            rescueBranch: input.rescueBranch,
+            rescueCommitSha: input.rescueCommitSha,
+            fileCount: input.fileCount,
+            dirtyPathSample: input.evidence.dirtyPathSample,
+            fingerprint: input.evidence.fingerprint,
+            sourceIssueId: input.evidence.sourceIssueId,
+            executionWorkspaceId: input.evidence.executionWorkspaceId,
+            sourceAuditCommentId: input.sourceAuditCommentId,
+            claimantAuditCommentId: input.claimantAuditCommentId,
+        },
+        run: async () => ({
+            status: "succeeded",
+            system: `Quarantined dirty git worktree state on ${input.rescueBranch} (${formatShortSha(input.rescueCommitSha)}) and restored recorded branch ${input.evidence.expectedBranch}.\n`,
+        }),
+    });
+}
+async function quarantineDirtyWorktreeBranchIncoherence(input) {
+    const companyId = await readIssueCompanyId(input.db, input.evidence.sourceIssueId);
+    if (!companyId) {
+        input.evidence.safeRepair.eligible = false;
+        input.evidence.safeRepair.reason = "dirty quarantine repair requires a source issue company for audit";
+        throw branchIncoherenceValidationFailure(input.evidence);
+    }
+    const freshContention = await findGitWorktreeBranchContention({
+        db: input.db,
+        sourceIssue: input.sourceIssue,
+        executionWorkspaceId: input.executionWorkspaceId,
+        worktreePath: input.worktreePath,
+        actualBranchName: input.evidence.actualBranch,
+    });
+    input.evidence.contention = freshContention;
+    if (freshContention) {
+        input.evidence.safeRepair.eligible = false;
+        input.evidence.safeRepair.reason = formatDirtyQuarantineContentionRefusal(freshContention);
+        throw branchIncoherenceValidationFailure(input.evidence);
+    }
+    const rescueBranch = buildDirtyQuarantineRescueBranch(input.sourceIssue);
+    const fileCount = input.evidence.statusEntryCount ?? input.evidence.dirtyPathSample.length;
+    const baseMetadata = {
+        repoRoot: input.repoRoot,
+        worktreePath: input.worktreePath,
+        expectedBranchName: input.expectedBranchName,
+        actualBranchName: input.evidence.actualBranch,
+        branchIncoherenceDirtyQuarantineRepair: true,
+        rescueBranch,
+        fingerprint: input.evidence.fingerprint,
+        sourceIssueId: input.evidence.sourceIssueId,
+        executionWorkspaceId: input.evidence.executionWorkspaceId,
+        fileCount,
+        dirtyPathSample: input.evidence.dirtyPathSample,
+        contention: input.evidence.contention,
+    };
+    let rescueBranchCreated = false;
+    let expectedBranchRestored = false;
+    try {
+        await assertGitIndexIsUnlocked(input.worktreePath);
+        await recordGitOperation(input.recorder, {
+            phase: input.phase ?? "worktree_prepare",
+            args: ["checkout", "-b", rescueBranch],
+            cwd: input.worktreePath,
+            metadata: baseMetadata,
+            successMessage: `Created rescue branch ${rescueBranch} for dirty git worktree state at ${input.worktreePath}\n`,
+            failureLabel: `git checkout -b ${rescueBranch}`,
+        });
+        rescueBranchCreated = true;
+        await recordGitOperation(input.recorder, {
+            phase: input.phase ?? "worktree_prepare",
+            args: ["add", "-A"],
+            cwd: input.worktreePath,
+            metadata: baseMetadata,
+            successMessage: `Staged dirty git worktree state for rescue branch ${rescueBranch}\n`,
+            failureLabel: "git add -A",
+        });
+        await recordGitOperation(input.recorder, {
+            phase: input.phase ?? "worktree_prepare",
+            args: [
+                "commit",
+                "-m",
+                "Paperclip dirty workspace rescue",
+                "-m",
+                [
+                    `Source-Issue: ${input.evidence.sourceIdentifier ?? input.evidence.sourceIssueId ?? "unknown"}`,
+                    `Run-Id: ${input.heartbeatRunId ?? "unknown"}`,
+                    `Recorded-Branch: ${input.expectedBranchName}`,
+                    `Live-Branch: ${formatBranchForMessage(input.evidence.actualBranch)}`,
+                    `Fingerprint: ${input.evidence.fingerprint}`,
+                ].join("\n"),
+            ],
+            cwd: input.worktreePath,
+            metadata: baseMetadata,
+            successMessage: `Committed dirty git worktree state to rescue branch ${rescueBranch}\n`,
+            failureLabel: "git commit dirty workspace rescue",
+        });
+        const rescueCommitSha = await runGit(["rev-parse", "HEAD"], input.worktreePath);
+        await recordGitOperation(input.recorder, {
+            phase: input.phase ?? "worktree_prepare",
+            args: ["checkout", input.expectedBranchName],
+            cwd: input.worktreePath,
+            metadata: {
+                ...baseMetadata,
+                rescueCommitSha,
+            },
+            successMessage: `Restored recorded branch ${input.expectedBranchName} after dirty workspace rescue ${rescueBranch}\n`,
+            failureLabel: `git checkout ${input.expectedBranchName}`,
+        });
+        expectedBranchRestored = true;
+        // A run that died mid-rebase (or mid-merge/cherry-pick/revert/bisect)
+        // leaves the operation's state directory behind even after the recorded
+        // branch is checked out, which wedges the next git command in the
+        // worktree. The rescue commit above already preserved the in-flight
+        // resolution, so clearing the state metadata here loses nothing.
+        let clearedInProgressOperation = null;
+        const lingeringOperation = await detectGitWorktreeInProgressOperation(input.worktreePath);
+        if (lingeringOperation) {
+            const operationLabel = GIT_IN_PROGRESS_OPERATION_LABELS[lingeringOperation];
+            const quitArgs = GIT_IN_PROGRESS_OPERATION_QUIT_ARGS[lingeringOperation];
+            await recordGitOperation(input.recorder, {
+                phase: input.phase ?? "worktree_prepare",
+                args: quitArgs,
+                cwd: input.worktreePath,
+                metadata: {
+                    ...baseMetadata,
+                    clearedInProgressOperation: lingeringOperation,
+                },
+                successMessage: `Cleared interrupted git ${operationLabel} state after dirty workspace rescue ${rescueBranch}\n`,
+                failureLabel: `git ${quitArgs.join(" ")}`,
+            });
+            const stillInProgress = await detectGitWorktreeInProgressOperation(input.worktreePath);
+            if (stillInProgress) {
+                input.evidence.safeRepair.succeeded = false;
+                input.evidence.safeRepair.reason =
+                    `dirty quarantine repair could not clear the interrupted git ${GIT_IN_PROGRESS_OPERATION_LABELS[stillInProgress]} state`;
+                throw branchIncoherenceValidationFailure(input.evidence);
+            }
+            clearedInProgressOperation = lingeringOperation;
+        }
+        const repairedBranch = await runGit(["symbolic-ref", "--quiet", "--short", "HEAD"], input.worktreePath)
+            .catch(() => null);
+        if (repairedBranch !== input.expectedBranchName) {
+            input.evidence.safeRepair.succeeded = false;
+            input.evidence.safeRepair.reason =
+                `dirty quarantine repair checked out ${formatBranchForMessage(repairedBranch)} instead of ${input.expectedBranchName}`;
+            throw branchIncoherenceValidationFailure(input.evidence);
+        }
+        const repairedStatus = await runGit(["status", "--porcelain", "--untracked-files=all"], input.worktreePath);
+        if (repairedStatus.trim().length > 0) {
+            input.evidence.safeRepair.succeeded = false;
+            input.evidence.safeRepair.reason = "dirty quarantine repair completed but the worktree is still dirty";
+            throw branchIncoherenceValidationFailure(input.evidence);
+        }
+        const comments = await writeDirtyQuarantineAuditComments({
+            db: input.db,
+            companyId,
+            evidence: input.evidence,
+            sourceIssue: input.sourceIssue,
+            rescueBranch,
+            rescueCommitSha,
+            fileCount,
+            heartbeatRunId: input.heartbeatRunId,
+        });
+        await logDirtyQuarantineActivity({
+            db: input.db,
+            companyId,
+            evidence: input.evidence,
+            rescueBranch,
+            rescueCommitSha,
+            fileCount,
+            heartbeatRunId: input.heartbeatRunId,
+            sourceAuditCommentId: comments.sourceAuditCommentId,
+            claimantAuditCommentId: comments.claimantAuditCommentId,
+        });
+        await recordDirtyQuarantineOperation({
+            recorder: input.recorder,
+            phase: input.phase,
+            cwd: input.worktreePath,
+            evidence: input.evidence,
+            rescueBranch,
+            rescueCommitSha,
+            fileCount,
+            sourceAuditCommentId: comments.sourceAuditCommentId,
+            claimantAuditCommentId: comments.claimantAuditCommentId,
+        });
+        return {
+            rescueBranch,
+            rescueCommitSha,
+            fileCount,
+            clearedInProgressOperation,
+            ...comments,
+        };
+    }
+    catch (error) {
+        if (rescueBranchCreated && !expectedBranchRestored) {
+            await runGit(["checkout", input.expectedBranchName], input.worktreePath).catch(() => null);
+        }
+        if (error instanceof WorkspaceRuntimeValidationFailure)
+            throw error;
+        input.evidence.safeRepair.succeeded = false;
+        input.evidence.safeRepair.reason = formatDirtyQuarantineFailure(error);
+        throw branchIncoherenceValidationFailure(input.evidence);
+    }
+}
+async function recordForwardBranchReconcileOperation(input) {
+    if (!input.recorder)
+        return;
+    await input.recorder.recordOperation({
+        phase: input.phase ?? "worktree_prepare",
+        cwd: input.cwd,
+        metadata: {
+            repoRoot: input.repoRoot,
+            worktreePath: input.worktreePath,
+            expectedBranchName: input.expectedBranchName,
+            actualBranchName: input.actualBranchName,
+            branchIncoherenceReconcileForward: true,
+            reconcileMode: input.mode,
+            fingerprint: input.fingerprint,
+            sourceIssueId: input.sourceIssueId,
+            executionWorkspaceId: input.executionWorkspaceId,
+            expectedHeadSha: input.expectedHeadSha,
+            actualHeadSha: input.actualHeadSha,
+            ancestryVerdict: input.ancestryVerdict,
+            auditCommentId: input.auditCommentId ?? null,
+            recoveryActionId: input.recoveryActionId ?? null,
+        },
+        run: async () => ({
+            status: "succeeded",
+            system: input.mode === "record_updated"
+                ? `Reconciled execution workspace branch record from ${input.expectedBranchName} to ${input.actualBranchName}; worktree left unchanged.\n`
+                : `Adopted live git worktree branch ${input.actualBranchName} for this execution workspace realization; worktree left unchanged.\n`,
+        }),
+    });
+}
+async function logForwardBranchReconcileActivity(input) {
+    await logActivity(input.db, {
+        companyId: input.companyId,
+        actorType: "system",
+        actorId: "workspace_runtime",
+        runId: input.runId,
+        action: "execution_workspace.branch_reconciled",
+        entityType: "execution_workspace",
+        entityId: input.executionWorkspaceId,
+        details: {
+            mode: input.mode,
+            reason: input.reason,
+            fromBranch: input.fromBranch,
+            toBranch: input.toBranch,
+            fromSha: input.fromSha,
+            toSha: input.toSha,
+            ancestryVerdict: input.ancestryVerdict,
+            fingerprint: input.fingerprint,
+            sourceIssueId: input.sourceIssueId,
+            auditCommentId: input.auditCommentId,
+            recoveryActionId: input.recoveryActionId,
+            actor: {
+                type: "system",
+                id: "workspace_runtime",
+                source: "workspace_runtime",
+            },
+        },
+    });
+}
+export async function reconcilePendingForwardBranchAfterPersistence(input) {
+    const result = await executionWorkspaceService(input.db).reconcileExecutionWorkspaceBranch(input.executionWorkspaceId, {
+        mode: "forward",
+        reason: input.pending.reason,
+        alternateRecoveryFingerprints: [input.pending.prePersistenceFingerprint],
+        actor: {
+            actorType: "system",
+            actorId: "workspace_runtime",
+            agentId: null,
+            runId: input.heartbeatRunId ?? null,
+        },
+    });
+    await logForwardBranchReconcileActivity({
+        db: input.db,
+        companyId: result.workspace.companyId,
+        executionWorkspaceId: result.workspace.id,
+        sourceIssueId: result.workspace.sourceIssueId,
+        runId: input.heartbeatRunId ?? null,
+        mode: "forward",
+        reason: input.pending.reason,
+        fromBranch: result.inspection.fromBranch,
+        toBranch: result.inspection.toBranch,
+        fromSha: result.inspection.fromSha,
+        toSha: result.inspection.toSha,
+        ancestryVerdict: result.inspection.ancestryVerdict,
+        fingerprint: result.inspection.fingerprint,
+        auditCommentId: result.auditCommentId,
+        recoveryActionId: result.recoveryAction?.id ?? null,
+    });
+    await recordForwardBranchReconcileOperation({
+        recorder: input.recorder,
+        phase: input.reconcileOperationPhase,
+        cwd: result.inspection.worktreePath,
+        repoRoot: result.inspection.repoRoot,
+        worktreePath: result.inspection.worktreePath,
+        expectedBranchName: result.inspection.fromBranch,
+        actualBranchName: result.inspection.toBranch,
+        executionWorkspaceId: result.workspace.id,
+        sourceIssueId: result.workspace.sourceIssueId,
+        fingerprint: result.inspection.fingerprint,
+        expectedHeadSha: result.inspection.fromSha,
+        actualHeadSha: result.inspection.toSha,
+        ancestryVerdict: result.inspection.ancestryVerdict,
+        mode: "adopt_for_realize",
+        auditCommentId: result.auditCommentId,
+        recoveryActionId: result.recoveryAction?.id ?? null,
+    });
+    return result;
+}
 export async function ensureGitWorktreeBranchCoherent(input) {
     const expectedBranchName = input.expectedBranchName?.trim();
     if (!expectedBranchName)
-        return;
+        return { branchName: null, reconciledForward: false, warnings: [] };
     const currentBranch = input.actualBranchName !== undefined
         ? input.actualBranchName
         : await runGit(["symbolic-ref", "--quiet", "--short", "HEAD"], input.worktreePath).catch(() => null);
-    if (currentBranch === expectedBranchName)
-        return;
+    if (currentBranch === expectedBranchName) {
+        return { branchName: expectedBranchName, reconciledForward: false, warnings: [] };
+    }
     const evidence = await inspectGitWorktreeBranchIncoherence({
+        db: input.db ?? null,
         repoRoot: input.repoRoot,
         worktreePath: input.worktreePath,
         expectedBranchName,
@@ -578,10 +1253,203 @@ export async function ensureGitWorktreeBranchCoherent(input) {
         sourceIssue: input.sourceIssue,
         executionWorkspaceId: input.executionWorkspaceId ?? null,
     });
+    if (evidence.cleanliness === "dirty" && input.enableWorkspaceDirtyQuarantineRepair === true) {
+        if (!input.db) {
+            evidence.safeRepair.reason = "dirty quarantine repair requires database access for claimant checks and audit";
+            throw branchIncoherenceValidationFailure(evidence);
+        }
+        if (!evidence.provenance.registeredPathFound) {
+            evidence.safeRepair.reason = "dirty quarantine repair requires a registered git worktree path";
+            throw branchIncoherenceValidationFailure(evidence);
+        }
+        if (!evidence.provenance.expectedBranchExists) {
+            evidence.safeRepair.reason = "dirty quarantine repair requires the recorded branch to exist";
+            throw branchIncoherenceValidationFailure(evidence);
+        }
+        if (evidence.contention) {
+            evidence.safeRepair.eligible = false;
+            evidence.safeRepair.reason = formatDirtyQuarantineContentionRefusal(evidence.contention);
+            throw branchIncoherenceValidationFailure(evidence);
+        }
+        await assertDirtyQuarantineRuntimeServicesStopped({
+            db: input.db,
+            executionWorkspaceId: input.executionWorkspaceId ?? null,
+            evidence,
+        });
+        evidence.safeRepair.eligible = true;
+        evidence.safeRepair.attempted = true;
+        evidence.safeRepair.reason = "dirty worktree can be quarantined on a rescue branch before restoring the recorded branch";
+        const result = await quarantineDirtyWorktreeBranchIncoherence({
+            db: input.db,
+            repoRoot: input.repoRoot,
+            worktreePath: input.worktreePath,
+            expectedBranchName,
+            sourceIssue: input.sourceIssue,
+            executionWorkspaceId: input.executionWorkspaceId ?? null,
+            heartbeatRunId: input.heartbeatRunId ?? null,
+            evidence,
+            phase: input.reconcileOperationPhase,
+            recorder: input.recorder ?? null,
+        });
+        evidence.safeRepair.succeeded = true;
+        evidence.safeRepair.reason = result.clearedInProgressOperation
+            ? `dirty worktree quarantined on ${result.rescueBranch} at ${formatShortSha(result.rescueCommitSha)}; interrupted git ${GIT_IN_PROGRESS_OPERATION_LABELS[result.clearedInProgressOperation]} state cleared`
+            : `dirty worktree quarantined on ${result.rescueBranch} at ${formatShortSha(result.rescueCommitSha)}`;
+        return {
+            branchName: expectedBranchName,
+            reconciledForward: false,
+            dirtyQuarantineRepair: result,
+            warnings: [
+                `Execution workspace dirty worktree state was quarantined on rescue branch "${result.rescueBranch}" (${formatShortSha(result.rescueCommitSha)}; ${result.fileCount} ${result.fileCount === 1 ? "file" : "files"}) before restoring recorded branch "${expectedBranchName}".${result.clearedInProgressOperation ? ` An interrupted git ${GIT_IN_PROGRESS_OPERATION_LABELS[result.clearedInProgressOperation]} was also cleared; its in-flight state is preserved on the rescue branch.` : ""}`,
+            ],
+        };
+    }
+    if (input.enableWorkspaceBranchReconcileForward === true &&
+        evidence.provenance.ancestryVerdict === "ancestor" &&
+        !evidence.provenance.sameHead &&
+        evidence.cleanliness === "clean" &&
+        currentBranch) {
+        const reason = "Automatic forward reconciliation: recorded branch is an ancestor of the checked-out branch.";
+        if (input.executionWorkspaceId && input.persistForwardReconcile !== false) {
+            if (!input.db) {
+                evidence.safeRepair.reason = "forward reconciliation requires database access to update the execution workspace record";
+                throw branchIncoherenceValidationFailure(evidence);
+            }
+            try {
+                const result = await executionWorkspaceService(input.db).reconcileExecutionWorkspaceBranch(input.executionWorkspaceId, {
+                    mode: "forward",
+                    reason,
+                    actor: {
+                        actorType: "system",
+                        actorId: "workspace_runtime",
+                        agentId: null,
+                        runId: input.heartbeatRunId ?? null,
+                    },
+                });
+                await logForwardBranchReconcileActivity({
+                    db: input.db,
+                    companyId: result.workspace.companyId,
+                    executionWorkspaceId: result.workspace.id,
+                    sourceIssueId: result.workspace.sourceIssueId ?? evidence.sourceIssueId ?? null,
+                    runId: input.heartbeatRunId ?? null,
+                    mode: "forward",
+                    reason,
+                    fromBranch: result.inspection.fromBranch,
+                    toBranch: result.inspection.toBranch,
+                    fromSha: result.inspection.fromSha,
+                    toSha: result.inspection.toSha,
+                    ancestryVerdict: result.inspection.ancestryVerdict,
+                    fingerprint: result.inspection.fingerprint,
+                    auditCommentId: result.auditCommentId,
+                    recoveryActionId: result.recoveryAction?.id ?? null,
+                });
+                await recordForwardBranchReconcileOperation({
+                    recorder: input.recorder,
+                    phase: input.reconcileOperationPhase,
+                    cwd: input.worktreePath,
+                    repoRoot: result.inspection.repoRoot,
+                    worktreePath: result.inspection.worktreePath,
+                    expectedBranchName: result.inspection.fromBranch,
+                    actualBranchName: result.inspection.toBranch,
+                    executionWorkspaceId: result.workspace.id,
+                    sourceIssueId: result.workspace.sourceIssueId ?? evidence.sourceIssueId ?? null,
+                    fingerprint: result.inspection.fingerprint,
+                    expectedHeadSha: result.inspection.fromSha,
+                    actualHeadSha: result.inspection.toSha,
+                    ancestryVerdict: result.inspection.ancestryVerdict,
+                    mode: "record_updated",
+                    auditCommentId: result.auditCommentId,
+                    recoveryActionId: result.recoveryAction?.id ?? null,
+                });
+                return { branchName: result.inspection.toBranch, reconciledForward: true, warnings: [] };
+            }
+            catch (error) {
+                evidence.safeRepair.reason =
+                    `forward reconciliation failed: ${error instanceof Error ? error.message : String(error)}`;
+                throw branchIncoherenceValidationFailure(evidence);
+            }
+        }
+        if (!input.db) {
+            evidence.safeRepair.reason = "forward reconciliation adoption requires database access to audit after workspace realization";
+            throw branchIncoherenceValidationFailure(evidence);
+        }
+        return {
+            branchName: currentBranch,
+            reconciledForward: true,
+            warnings: [],
+            pendingForwardBranchReconcile: {
+                recordedBranchName: expectedBranchName,
+                adoptedBranchName: currentBranch,
+                prePersistenceFingerprint: evidence.fingerprint,
+                reason,
+            },
+        };
+    }
     if (!evidence.safeRepair.eligible) {
         throw branchIncoherenceValidationFailure(evidence);
     }
     evidence.safeRepair.attempted = true;
+    const warningPrefix = `Execution workspace branch metadata was self-healed from "${expectedBranchName}" to "${formatBranchForMessage(currentBranch)}" at ${input.worktreePath}.`;
+    if (currentBranch &&
+        evidence.provenance.actualBranchExists === true &&
+        evidence.provenance.ancestryVerdict === "ancestor" &&
+        !evidence.provenance.sameHead) {
+        evidence.safeRepair.succeeded = true;
+        evidence.safeRepair.reason = "clean worktree adopted the checked-out branch because it is forward of the recorded branch";
+        return {
+            branchName: currentBranch,
+            reconciledForward: false,
+            warnings: [
+                `${warningPrefix} The checked-out branch contains the recorded branch plus newer commits, so Paperclip adopted it for subsequent runs.`,
+            ],
+        };
+    }
+    if (currentBranch === null &&
+        evidence.provenance.ancestryVerdict === "ancestor" &&
+        !evidence.provenance.sameHead &&
+        evidence.provenance.actualHeadSha) {
+        try {
+            await recordGitOperation(input.recorder, {
+                phase: "worktree_prepare",
+                args: ["checkout", "-B", expectedBranchName, evidence.provenance.actualHeadSha],
+                cwd: input.worktreePath,
+                metadata: {
+                    repoRoot: input.repoRoot,
+                    worktreePath: input.worktreePath,
+                    expectedBranchName,
+                    actualBranchName: currentBranch,
+                    branchIncoherenceRepair: true,
+                    detachedHeadRepair: true,
+                    fingerprint: evidence.fingerprint,
+                    sourceIssueId: evidence.sourceIssueId,
+                    executionWorkspaceId: evidence.executionWorkspaceId,
+                },
+                successMessage: `Reattached detached git worktree HEAD at ${input.worktreePath} to ${expectedBranchName}\n`,
+                failureLabel: `git checkout -B ${expectedBranchName} ${formatShortSha(evidence.provenance.actualHeadSha)}`,
+            });
+        }
+        catch (error) {
+            evidence.safeRepair.succeeded = false;
+            evidence.safeRepair.reason = `safe detached HEAD reattachment failed: ${error instanceof Error ? error.message : String(error)}`;
+            throw branchIncoherenceValidationFailure(evidence);
+        }
+        const repairedBranch = await runGit(["symbolic-ref", "--quiet", "--short", "HEAD"], input.worktreePath)
+            .catch(() => null);
+        if (repairedBranch !== expectedBranchName) {
+            evidence.safeRepair.succeeded = false;
+            evidence.safeRepair.reason = `reattach completed but HEAD is ${formatBranchForMessage(repairedBranch)}`;
+            throw branchIncoherenceValidationFailure(evidence);
+        }
+        evidence.safeRepair.succeeded = true;
+        evidence.safeRepair.reason = "clean detached worktree HEAD was reattached to the recorded branch";
+        return {
+            branchName: expectedBranchName,
+            reconciledForward: false,
+            warnings: [
+                `${warningPrefix} The detached HEAD contained the recorded branch plus newer commits, so Paperclip moved the recorded branch to that HEAD.`,
+            ],
+        };
+    }
     try {
         await recordGitOperation(input.recorder, {
             phase: "worktree_prepare",
@@ -615,6 +1483,13 @@ export async function ensureGitWorktreeBranchCoherent(input) {
     }
     evidence.safeRepair.succeeded = true;
     evidence.safeRepair.reason = "clean worktree checked out the recorded branch";
+    return {
+        branchName: expectedBranchName,
+        reconciledForward: false,
+        warnings: [
+            `Execution workspace branch metadata was self-healed by checking out recorded branch "${expectedBranchName}" at ${input.worktreePath}.`,
+        ],
+    };
 }
 // Resolve the authoritative base ref for a fresh worktree. A configured local
 // branch is mapped to its `origin/<branch>` counterpart so unpushed local
@@ -1165,12 +2040,13 @@ export async function realizeExecutionWorkspace(input) {
         projectId: input.base.projectId,
         repoRef: input.base.repoRef,
     });
-    const branchName = sanitizeBranchName(renderedBranch);
+    let branchName = sanitizeBranchName(renderedBranch);
     const configuredParentDir = asString(rawStrategy.worktreeParentDir, "");
     const worktreeParentDir = configuredParentDir
         ? resolveConfiguredPath(configuredParentDir, repoRoot)
         : path.join(repoRoot, ".paperclip", "worktrees");
     const worktreePath = path.join(worktreeParentDir, branchName);
+    let pendingForwardBranchReconcile = null;
     const configuredBaseRef = typeof rawStrategy.baseRef === "string" && rawStrategy.baseRef.length > 0
         ? rawStrategy.baseRef
         : input.base.repoRef ?? null;
@@ -1181,12 +2057,12 @@ export async function realizeExecutionWorkspace(input) {
     ];
     const currentBaseRefSha = await resolveBaseRefSha(repoRoot, baseRef);
     await fs.mkdir(worktreeParentDir, { recursive: true });
-    async function reuseExistingWorktree(reusablePath) {
+    async function reuseExistingWorktree(reusablePath, effectiveBranchName = branchName, extraWarnings = []) {
         const refresh = currentBaseRefSha
             ? await refreshUnstartedWorktreeToBase({
                 repoRoot,
                 worktreePath: reusablePath,
-                branchName,
+                branchName: effectiveBranchName,
                 baseRef,
                 currentBaseRefSha,
                 recorder: input.recorder ?? null,
@@ -1207,7 +2083,7 @@ export async function realizeExecutionWorkspace(input) {
                 metadata: {
                     repoRoot,
                     worktreePath: reusablePath,
-                    branchName,
+                    branchName: effectiveBranchName,
                     baseRef,
                     currentBaseRefSha: baseDrift.currentBaseRefSha,
                     branchBaseRefSha: baseDrift.branchBaseRefSha,
@@ -1226,7 +2102,7 @@ export async function realizeExecutionWorkspace(input) {
             base: input.base,
             repoRoot,
             worktreePath: reusablePath,
-            branchName,
+            branchName: effectiveBranchName,
             issue: input.issue,
             agent: input.agent,
             created: false,
@@ -1237,11 +2113,12 @@ export async function realizeExecutionWorkspace(input) {
             repoRef: baseRef,
             strategy: "git_worktree",
             cwd: reusablePath,
-            branchName,
+            branchName: effectiveBranchName,
             worktreePath: reusablePath,
-            warnings: [...baseRefreshWarnings, ...baseDrift.warnings],
+            warnings: [...extraWarnings, ...baseRefreshWarnings, ...baseDrift.warnings],
             created: false,
             baseRefSha: refresh.baseRefSha ?? baseDrift.branchBaseRefSha ?? baseDrift.currentBaseRefSha,
+            pendingForwardBranchReconcile,
         };
     }
     async function validateReusableWorktree(reusablePath) {
@@ -1251,38 +2128,55 @@ export async function realizeExecutionWorkspace(input) {
             expectedBranchName: branchName,
         }).catch(() => null);
         if (validation && !validation.valid && validation.reasonCode === "branch_mismatch") {
-            await ensureGitWorktreeBranchCoherent({
+            const coherence = await ensureGitWorktreeBranchCoherent({
+                db: input.db ?? null,
                 repoRoot,
                 worktreePath: reusablePath,
                 expectedBranchName: branchName,
                 actualBranchName: validation.actualBranchName ?? null,
                 sourceIssue: input.issue,
                 executionWorkspaceId: null,
+                heartbeatRunId: input.heartbeatRunId ?? null,
+                enableWorkspaceBranchReconcileForward: input.enableWorkspaceBranchReconcileForward === true,
+                enableWorkspaceDirtyQuarantineRepair: input.enableWorkspaceDirtyQuarantineRepair === true,
+                reconcileOperationPhase: "worktree_prepare",
                 recorder: input.recorder ?? null,
             });
-            return await validateLinkedGitWorktree({
+            const effectiveBranchName = coherence.branchName ?? branchName;
+            if (coherence.reconciledForward) {
+                branchName = effectiveBranchName;
+                pendingForwardBranchReconcile = coherence.pendingForwardBranchReconcile ?? null;
+            }
+            const nextValidation = await validateLinkedGitWorktree({
                 repoRoot,
                 worktreePath: reusablePath,
-                expectedBranchName: branchName,
+                expectedBranchName: effectiveBranchName,
             }).catch(() => null);
+            return {
+                validation: nextValidation,
+                branchName: effectiveBranchName,
+                warnings: coherence.warnings,
+            };
         }
-        return validation;
+        return { validation, branchName, warnings: [] };
     }
     const existingWorktree = await directoryExists(worktreePath);
     if (existingWorktree) {
-        const validation = await validateReusableWorktree(worktreePath);
-        if (validation?.valid) {
-            return await reuseExistingWorktree(worktreePath);
+        const reusable = await validateReusableWorktree(worktreePath);
+        if (reusable.validation?.valid) {
+            return await reuseExistingWorktree(worktreePath, reusable.branchName, reusable.warnings);
         }
+        const validation = reusable.validation;
         const reason = validation && !validation.valid ? ` (${validation.reason})` : "";
         throw new Error(`Configured worktree path "${worktreePath}" already exists and is not a reusable git worktree${reason}.`);
     }
     const registeredBranchWorktree = await findRegisteredGitWorktreeByBranch(repoRoot, branchName);
     if (registeredBranchWorktree) {
-        const validation = await validateReusableWorktree(registeredBranchWorktree);
-        if (validation?.valid) {
-            return await reuseExistingWorktree(registeredBranchWorktree);
+        const reusable = await validateReusableWorktree(registeredBranchWorktree);
+        if (reusable.validation?.valid) {
+            return await reuseExistingWorktree(registeredBranchWorktree, reusable.branchName, reusable.warnings);
         }
+        const validation = reusable.validation;
         const reason = validation && !validation.valid ? ` (${validation.reason})` : "";
         throw new Error(`Registered worktree for branch "${branchName}" at "${registeredBranchWorktree}" is not reusable${reason}.`);
     }
@@ -1391,15 +2285,29 @@ export async function ensurePersistedExecutionWorkspaceAvailable(input) {
     if (await directoryExists(cwd)) {
         const reuseBaseRef = input.workspace.baseRef ?? input.base.repoRef ?? null;
         const reuseWorktreePath = realized.worktreePath ?? cwd;
+        const repairWarnings = [];
         if (await isGitCheckout(reuseWorktreePath)) {
-            await ensureGitWorktreeBranchCoherent({
+            const coherence = await ensureGitWorktreeBranchCoherent({
+                db: input.db ?? null,
                 repoRoot,
                 worktreePath: reuseWorktreePath,
                 expectedBranchName: realized.branchName,
                 sourceIssue: input.issue,
                 executionWorkspaceId: input.workspace.id ?? null,
+                heartbeatRunId: input.heartbeatRunId ?? null,
+                enableWorkspaceBranchReconcileForward: input.enableWorkspaceBranchReconcileForward === true,
+                enableWorkspaceDirtyQuarantineRepair: input.enableWorkspaceDirtyQuarantineRepair === true,
+                persistForwardReconcile: false,
+                reconcileOperationPhase: "worktree_prepare",
                 recorder: input.recorder ?? null,
             });
+            if (coherence.branchName) {
+                realized.branchName = coherence.branchName;
+            }
+            if (coherence.reconciledForward) {
+                realized.pendingForwardBranchReconcile = coherence.pendingForwardBranchReconcile ?? null;
+            }
+            repairWarnings.push(...coherence.warnings);
         }
         const validation = await validateLinkedGitWorktree({
             repoRoot,
@@ -1438,7 +2346,7 @@ export async function ensurePersistedExecutionWorkspaceAvailable(input) {
             recordedBaseRefSha,
             skipRefresh: true,
         });
-        realized.warnings = [...baseRefreshWarnings, ...baseDrift.warnings];
+        realized.warnings = [...repairWarnings, ...baseRefreshWarnings, ...baseDrift.warnings];
         realized.baseRefSha = refresh.baseRefSha ?? recordedBaseRefSha ?? baseDrift.branchBaseRefSha ?? baseDrift.currentBaseRefSha;
         if (provisionCommand) {
             await provisionExecutionWorktree({
@@ -1870,13 +2778,20 @@ async function waitForReadiness(input) {
     const readinessType = asString(readiness.type, "");
     if (readinessType !== "http" || !input.url)
         return;
+    const readinessUrl = resolveRuntimeServiceHealthUrl(input.url, {
+        serviceName: input.serviceName,
+        command: input.command,
+    });
+    if (!readinessUrl) {
+        throw new Error(`Readiness check failed: could not resolve health URL for ${input.url}`);
+    }
     const timeoutSec = resolveWorkspaceRuntimeReadinessTimeoutSec(input.service);
     const intervalMs = Math.max(100, asNumber(readiness.intervalMs, 500));
     const deadline = Date.now() + timeoutSec * 1000;
     let lastError = "service did not become ready";
     while (Date.now() < deadline) {
         try {
-            const response = await fetch(input.url);
+            const response = await fetch(readinessUrl);
             if (response.ok)
                 return;
             lastError = `received HTTP ${response.status}`;
@@ -1886,7 +2801,7 @@ async function waitForReadiness(input) {
         }
         await delay(intervalMs);
     }
-    throw new Error(`Readiness check failed for ${input.url}: ${lastError}`);
+    throw new Error(`Readiness check failed for ${readinessUrl}: ${lastError}`);
 }
 function isPaperclipDevRuntimeService(input) {
     const serviceName = (input.serviceName ?? "").trim().toLowerCase();
@@ -1917,7 +2832,7 @@ async function isRuntimeServiceUrlHealthy(url, input) {
         return true;
     const healthUrl = resolveRuntimeServiceHealthUrl(url, input);
     if (!healthUrl)
-        return true;
+        return false;
     try {
         const response = await fetch(healthUrl, { signal: AbortSignal.timeout(2_000) });
         return response.ok;
@@ -2071,7 +2986,7 @@ export function normalizeAdapterManagedRuntimeServices(input) {
         };
     });
 }
-async function startLocalRuntimeService(input) {
+async function spawnLocalRuntimeService(input) {
     const leaseRunId = input.leaseRunId === undefined ? input.runId : input.leaseRunId;
     const startedByRunId = input.startedByRunId === undefined ? input.runId : input.startedByRunId;
     const identity = resolveRuntimeServiceReuseIdentity({
@@ -2168,47 +3083,58 @@ async function startLocalRuntimeService(input) {
         }
         else {
             return {
-                id: adoptedRecord.runtimeServiceId ?? randomUUID(),
-                companyId: input.agent.companyId,
-                projectId: input.workspace.projectId,
-                projectWorkspaceId: input.workspace.workspaceId,
-                executionWorkspaceId: input.executionWorkspaceId ?? null,
-                issueId: input.issue?.id ?? null,
-                serviceName,
-                status: "running",
-                lifecycle,
-                scopeType: input.scopeType,
-                scopeId: input.scopeId,
-                reuseKey: input.reuseKey,
-                command,
-                cwd: serviceCwd,
-                port: adoptedRecord.port ?? port,
-                url: adoptedRecord.url ?? url,
-                provider: "local_process",
-                providerRef: String(adoptedRecord.pid),
-                ownerAgentId: input.agent.id ?? null,
-                startedByRunId,
-                lastUsedAt: new Date().toISOString(),
-                startedAt: adoptedRecord.startedAt,
-                stoppedAt: null,
-                stopPolicy,
-                healthStatus: "healthy",
-                reused: true,
-                db: input.db,
-                child: null,
-                leaseRunIds: leaseRunId ? new Set([leaseRunId]) : new Set(),
-                idleTimer: null,
-                envFingerprint,
-                serviceKey,
-                profileKind: "workspace-runtime",
-                processGroupId: adoptedRecord.processGroupId ?? null,
+                record: {
+                    id: adoptedRecord.runtimeServiceId ?? randomUUID(),
+                    companyId: input.agent.companyId,
+                    projectId: input.workspace.projectId,
+                    projectWorkspaceId: input.workspace.workspaceId,
+                    executionWorkspaceId: input.executionWorkspaceId ?? null,
+                    issueId: input.issue?.id ?? null,
+                    serviceName,
+                    status: "running",
+                    lifecycle,
+                    scopeType: input.scopeType,
+                    scopeId: input.scopeId,
+                    reuseKey: input.reuseKey,
+                    command,
+                    cwd: serviceCwd,
+                    port: adoptedRecord.port ?? port,
+                    url: adoptedRecord.url ?? url,
+                    provider: "local_process",
+                    providerRef: String(adoptedRecord.pid),
+                    ownerAgentId: input.agent.id ?? null,
+                    startedByRunId,
+                    lastUsedAt: new Date().toISOString(),
+                    startedAt: adoptedRecord.startedAt,
+                    stoppedAt: null,
+                    stopPolicy,
+                    healthStatus: "healthy",
+                    reused: true,
+                    db: input.db,
+                    child: null,
+                    leaseRunIds: leaseRunId ? new Set([leaseRunId]) : new Set(),
+                    idleTimer: null,
+                    envFingerprint,
+                    serviceKey,
+                    profileKind: "workspace-runtime",
+                    processGroupId: adoptedRecord.processGroupId ?? null,
+                },
+                readiness: Promise.resolve(),
             };
         }
     }
     if (identityPort) {
         const ownerPid = await readLocalServicePortOwner(identityPort);
         if (ownerPid) {
-            throw new Error(`Runtime service "${serviceName}" could not start because port ${identityPort} is already in use by pid ${ownerPid}`);
+            const ownerCwd = await readLocalServiceProcessCwd(ownerPid);
+            const ownerIsInWorkspace = ownerCwd
+                ? await isLocalServiceProcessInWorkspace(ownerCwd, serviceCwd)
+                : null;
+            const ownerDescription = ownerCwd ? `pid ${ownerPid} (cwd: ${ownerCwd})` : `pid ${ownerPid} (cwd unavailable)`;
+            if (ownerIsInWorkspace === false) {
+                throw new Error(`Runtime service "${serviceName}" could not start because port ${identityPort} has a cross-workspace port conflict with ${ownerDescription}; requested workspace: ${serviceCwd}. Stop the other service or configure a different port.`);
+            }
+            throw new Error(`Runtime service "${serviceName}" could not start because port ${identityPort} is already in use by ${ownerDescription}`);
         }
     }
     await ensureServerWorkspaceLinksCurrent(serviceCwd, {
@@ -2240,16 +3166,7 @@ async function startLocalRuntimeService(input) {
         if (input.onLog)
             await input.onLog("stderr", `[service:${serviceName}] ${text}`);
     });
-    try {
-        await Promise.race([
-            waitForReadiness({ service: input.service, url }),
-            spawnErrorPromise,
-        ]);
-    }
-    catch (err) {
-        terminateChildProcess(child);
-        throw new Error(`Failed to start runtime service "${serviceName}": ${err instanceof Error ? err.message : String(err)}${stderrExcerpt ? ` | stderr: ${stderrExcerpt.trim()}` : ""}`);
-    }
+    const nowIso = new Date().toISOString();
     const record = {
         id: stoppedReuseCandidate?.id ?? randomUUID(),
         companyId: input.agent.companyId,
@@ -2258,7 +3175,7 @@ async function startLocalRuntimeService(input) {
         executionWorkspaceId: input.executionWorkspaceId ?? null,
         issueId: input.issue?.id ?? null,
         serviceName,
-        status: "running",
+        status: "starting",
         lifecycle,
         scopeType: input.scopeType,
         scopeId: input.scopeId,
@@ -2271,11 +3188,11 @@ async function startLocalRuntimeService(input) {
         providerRef: child.pid ? String(child.pid) : null,
         ownerAgentId: input.agent.id ?? null,
         startedByRunId,
-        lastUsedAt: new Date().toISOString(),
-        startedAt: new Date().toISOString(),
+        lastUsedAt: nowIso,
+        startedAt: nowIso,
         stoppedAt: null,
         stopPolicy,
-        healthStatus: "healthy",
+        healthStatus: "unknown",
         reused: false,
         db: input.db,
         child,
@@ -2314,7 +3231,33 @@ async function startLocalRuntimeService(input) {
             },
         });
     }
-    return record;
+    const readinessPromise = Promise.race([
+        waitForReadiness({ service: input.service, serviceName, command, url }),
+        spawnErrorPromise,
+    ]).then(async () => {
+        record.status = "running";
+        record.healthStatus = "healthy";
+        record.lastUsedAt = new Date().toISOString();
+        record.stoppedAt = null;
+        await touchLocalServiceRegistryRecord(record.serviceKey, {
+            runtimeServiceId: record.id,
+            lastSeenAt: record.lastUsedAt,
+        });
+    }).catch(async (err) => {
+        terminateChildProcess(child);
+        record.status = "stopped";
+        record.healthStatus = "unhealthy";
+        record.lastUsedAt = new Date().toISOString();
+        record.stoppedAt = new Date().toISOString();
+        await removeLocalServiceRegistryRecord(record.serviceKey).catch(() => undefined);
+        throw new Error(`Failed to start runtime service "${serviceName}": ${err instanceof Error ? err.message : String(err)}${stderrExcerpt ? ` | stderr: ${stderrExcerpt.trim()}` : ""}`);
+    });
+    return { record, readiness: readinessPromise };
+}
+async function startLocalRuntimeService(input) {
+    const started = await spawnLocalRuntimeService(input);
+    await started.readiness;
+    return started.record;
 }
 function scheduleIdleStop(record) {
     clearIdleTimer(record);
@@ -2533,16 +3476,10 @@ export async function ensureRuntimeServicesForRun(input) {
     }
     return refs;
 }
-export async function startRuntimeServicesForWorkspaceControl(input) {
-    const rawServices = selectRuntimeServiceEntries({
-        config: input.config,
-        serviceIndex: input.serviceIndex,
-        respectDesiredStates: input.respectDesiredStates,
-        defaultDesiredState: readDesiredRuntimeState(input.config.desiredState) ?? "stopped",
-        serviceStates: readConfiguredServiceStates(input.config),
-    });
+async function startRuntimeServicesForWorkspaceControlUnlocked(input, rawServices, invocationId, persistenceDb = input.db, registryDb = input.db, options) {
     const refs = [];
-    const invocationId = input.invocationId ?? randomUUID();
+    const pendingReadiness = [];
+    const startedServiceIds = [];
     for (const service of rawServices) {
         const { scopeType, scopeId } = resolveServiceScopeId({
             service,
@@ -2572,15 +3509,13 @@ export async function startRuntimeServicesForWorkspaceControl(input) {
                     runtimeServiceId: existing.id,
                     lastSeenAt: existing.lastUsedAt,
                 });
-                await persistRuntimeServiceRecord(input.db, existing);
+                await persistRuntimeServiceRecord(persistenceDb, existing);
                 refs.push(toRuntimeServiceRef(existing, { reused: true }));
                 continue;
             }
         }
-        // Manually controlled services are not tied to a heartbeat run lifecycle, so they do not
-        // retain a run lease and never persist a startedByRunId foreign key.
-        const record = await startLocalRuntimeService({
-            db: input.db,
+        const startInput = {
+            db: persistenceDb,
             runId: invocationId,
             leaseRunId: null,
             startedByRunId: null,
@@ -2594,12 +3529,93 @@ export async function startRuntimeServicesForWorkspaceControl(input) {
             reuseKey,
             scopeType,
             scopeId,
+        };
+        // Manually controlled services are not tied to a heartbeat run lifecycle, so they do not
+        // retain a run lease and never persist a startedByRunId foreign key.
+        const started = options?.deferReadiness
+            ? await spawnLocalRuntimeService(startInput)
+            : {
+                record: await startLocalRuntimeService(startInput),
+                readiness: Promise.resolve(),
+            };
+        registerRuntimeService(registryDb, started.record);
+        await persistRuntimeServiceRecord(persistenceDb, started.record);
+        refs.push(toRuntimeServiceRef(started.record));
+        if (options?.deferReadiness && !started.record.reused) {
+            // Attach a rejection handler immediately; the caller awaits the same promise after
+            // the DB transaction commits, but transaction failures may skip that wait path.
+            started.readiness.catch(() => undefined);
+            pendingReadiness.push(started);
+            startedServiceIds.push(started.record.id);
+        }
+    }
+    return { refs, pendingReadiness, startedServiceIds };
+}
+export async function startRuntimeServicesForWorkspaceControl(input) {
+    const rawServices = selectRuntimeServiceEntries({
+        config: input.config,
+        serviceIndex: input.serviceIndex,
+        respectDesiredStates: input.respectDesiredStates,
+        defaultDesiredState: readDesiredRuntimeState(input.config.desiredState) ?? "stopped",
+        serviceStates: readConfiguredServiceStates(input.config),
+    });
+    const invocationId = input.invocationId ?? randomUUID();
+    if (rawServices.length === 0 || !input.db || (!input.executionWorkspaceId && !input.workspace.workspaceId)) {
+        const batch = await startRuntimeServicesForWorkspaceControlUnlocked(input, rawServices, invocationId);
+        return batch.refs;
+    }
+    let startBatch = {
+        refs: [],
+        pendingReadiness: [],
+        startedServiceIds: [],
+    };
+    try {
+        await input.db.transaction(async (tx) => {
+            const txDb = tx;
+            if (input.executionWorkspaceId) {
+                const [lockedExecutionWorkspace] = await tx
+                    .select({ id: executionWorkspaces.id })
+                    .from(executionWorkspaces)
+                    .where(and(eq(executionWorkspaces.id, input.executionWorkspaceId), eq(executionWorkspaces.companyId, input.actor.companyId)))
+                    .for("update");
+                if (!lockedExecutionWorkspace)
+                    throw new Error("Execution workspace not found before starting runtime services");
+            }
+            if (input.workspace.workspaceId) {
+                const [lockedProjectWorkspace] = await tx
+                    .select({ id: projectWorkspaces.id })
+                    .from(projectWorkspaces)
+                    .where(and(eq(projectWorkspaces.id, input.workspace.workspaceId), eq(projectWorkspaces.companyId, input.actor.companyId)))
+                    .for("update");
+                if (!lockedProjectWorkspace)
+                    throw new Error("Project workspace not found before starting runtime services");
+            }
+            // Branch reconciliation takes these same parent row locks before mutating
+            // a recorded branch. Persisting a `starting` service row before commit closes
+            // the process-start window without holding the DB transaction for readiness.
+            startBatch = await startRuntimeServicesForWorkspaceControlUnlocked({ ...input, db: txDb }, rawServices, invocationId, txDb, input.db, { deferReadiness: true });
+        });
+        for (const pending of startBatch.pendingReadiness) {
+            try {
+                await pending.readiness;
+                await persistRuntimeServiceRecord(input.db, pending.record);
+            }
+            catch (error) {
+                await persistRuntimeServiceRecord(input.db, pending.record).catch(() => undefined);
+                throw error;
+            }
+        }
+        return startBatch.refs.map((ref) => {
+            const record = runtimeServicesById.get(ref.id);
+            return record ? toRuntimeServiceRef(record, { reused: ref.reused }) : ref;
         });
-        registerRuntimeService(input.db, record);
-        await persistRuntimeServiceRecord(input.db, record);
-        refs.push(toRuntimeServiceRef(record));
     }
-    return refs;
+    catch (error) {
+        for (const serviceId of startBatch.startedServiceIds) {
+            await stopRuntimeService(serviceId).catch(() => undefined);
+        }
+        throw error;
+    }
 }
 export async function releaseRuntimeServicesForRun(runId) {
     const acquired = runtimeServiceLeasesByRun.get(runId) ?? [];
@@ -3006,6 +4022,9 @@ export function buildWorkspaceReadyComment(input) {
     if (input.workspace.worktreePath && input.workspace.worktreePath !== input.workspace.cwd) {
         lines.push(`- Worktree: \`${input.workspace.worktreePath}\``);
     }
+    for (const warning of input.workspace.warnings) {
+        lines.push(`- Warning: ${warning}`);
+    }
     for (const service of input.runtimeServices) {
         const detail = service.url ? `${service.serviceName}: ${service.url}` : `${service.serviceName}: running`;
         const suffix = service.reused ? " (reused)" : "";