@paperclipai/server 2026.824.0 → 2026.825.0-beta.1

package/dist/services/workspace-runtime.js

@@ -12,16 +12,19 @@ import { and, desc, eq, gte, inArray, isNull, lte, ne, or } from "drizzle-orm";
 import { asNumber, asString, parseObject, renderTemplate } from "../adapters/utils.js";
 import { conflict } from "../errors.js";
 import { resolveHomeAwarePath } from "../home-paths.js";
-import { createLocalServiceKey, findLocalServiceRegistryRecordByRuntimeServiceId, findAdoptableLocalService, isLocalServiceProcessOwnedBy, isLocalServiceProcessInWorkspace, readLocalServiceProcessCwd, readLocalServicePortOwner, removeLocalServiceRegistryRecord, terminateLocalService, touchLocalServiceRegistryRecord, writeLocalServiceRegistryRecord, } from "./local-service-supervisor.js";
+import { hasVerifiedWorktreeSeedManifest, isVerifiedWorktreeSeedManifest } from "../worktree-seed-manifest.js";
+import { buildManagedWorkspaceGuestEnv, logManagedWorkspaceReadinessRejection, probeManagedWorkspaceHandoffSubjects, probeManagedWorkspaceReadiness, resolveManagedWorkspaceIdentity, shouldBlockPublicationOnReadiness, waitForManagedWorkspaceReadiness, } from "./managed-workspace-identity.js";
+import { createLocalServiceKey, findLocalServiceRegistryRecordByRuntimeServiceId, findAdoptableLocalService, isLocalServiceProcessOwnedBy, isLocalServiceProcessInWorkspace, openLocalServiceLogFile, readLocalServiceProcessCwd, readLocalServiceProcessGroupId, readLocalServicePortOwner, removeLocalServiceRegistryRecord, terminateLocalService, touchLocalServiceRegistryRecord, writeLocalServiceRegistryRecord, } from "./local-service-supervisor.js";
 import { workspaceOperationService } from "./workspace-operations.js";
 import { executionWorkspaceService, readExecutionWorkspaceConfig } from "./execution-workspaces.js";
+import { isRuntimeOwnedGitBranch } from "./execution-workspace-branch-ownership.js";
 import { logActivity } from "./activity-log.js";
 import { readProjectWorkspaceRuntimeConfig } from "./project-workspace-runtime-config.js";
 import { workspaceGitOperationScheduler } from "./workspace-git-operation-scheduler.js";
 import { cleanupWorktreeInstanceArtifacts, deriveWorktreeInstanceId, readWorktreeInstancePointer, WORKTREE_INSTANCE_ROOT_METADATA_KEY, } from "./workspace-instance-cleanup.js";
 import { UnixBrokerClient } from "./runtime-exposure/broker-client.js";
 import { deprovisionExposure, provisionExposure, reserveExposure, } from "./runtime-exposure/exposure-manager.js";
-import { diagnoseRuntimeListenerBinds } from "./runtime-exposure/loopback-listener.js";
+import { diagnoseRuntimeListenerBinds, readListenerBindFacts } from "./runtime-exposure/loopback-listener.js";
 import { allocateExposurePortPair } from "./runtime-exposure/port-pair.js";
 import { buildExposureReservationLedger, collectRowExposurePorts, describeExposureReservationDrift, ExposurePortOwnershipConflictError, ExposurePortPairClaims, findExposurePairConflict, findExposureReservationDrift, isExposureAdoptionPermitted, } from "./runtime-exposure/port-reservation.js";
 import { resolveTailscaleDnsName } from "./runtime-exposure/tailscale-hostname.js";
@@ -47,6 +50,8 @@ const runtimeServicesById = new Map();
 const runtimeServicesByReuseKey = new Map();
 const runtimeServiceLeasesByRun = new Map();
 const runtimeProvisionByWorkspace = new Map();
+const runtimeControlStartByOwner = new Map();
+const runtimeReplacementClaimsByReuseKey = new Map();
 const quarantinedRuntimeExposurePorts = new Set();
 /**
  * Pair-atomic in-process claims for exposure allocations that have not bound a
@@ -67,10 +72,24 @@ const ACTIVE_RUNTIME_PORT_RESERVATION_STATUSES = ["provisioning", "starting", "r
 const DEFAULT_TAILSCALE_BROKER_SOCKET = "/run/paperclip-tailscale-broker/broker.sock";
 class RuntimeServicePortBindCollision extends Error {
     port;
-    constructor(port) {
-        super(`Runtime service could not bind allocated port ${port}`);
+    /**
+     * Who held the port when the collision was seen, captured at failure time.
+     * Null when no owner remained (a transient racer that already released it).
+     */
+    diagnosis;
+    /**
+     * True when the port is only a preference and the caller may re-allocate a
+     * different one. Exposed runtimes always draw from the dedicated broker range,
+     * so a collision on the assigned port is recoverable by taking the next pair.
+     */
+    exposureReallocatable;
+    constructor(port, diagnosis = null, exposureReallocatable = false) {
+        super(`Runtime service could not bind allocated port ${port}` +
+            (diagnosis ? ` (${diagnosis})` : ""));
         this.name = "RuntimeServicePortBindCollision";
         this.port = port;
+        this.diagnosis = diagnosis;
+        this.exposureReallocatable = exposureReallocatable;
     }
 }
 async function isLoopbackPortAvailable(port) {
@@ -221,11 +240,20 @@ export async function resetRuntimeServicesForTests(opts = {}) {
     }
     for (const record of runtimeServicesById.values()) {
         clearIdleTimer(record);
+        if (opts.simulateSupervisorExit) {
+            // A real supervisor exit closes its side of every inherited pipe. Tests
+            // use this to prove surviving request-logging services do not depend on
+            // Paperclip keeping an anonymous stdio peer alive.
+            record.child?.stdout?.destroy();
+            record.child?.stderr?.destroy();
+        }
     }
     runtimeServicesById.clear();
     runtimeServicesByReuseKey.clear();
     runtimeServiceLeasesByRun.clear();
     runtimeProvisionByWorkspace.clear();
+    runtimeControlStartByOwner.clear();
+    runtimeReplacementClaimsByReuseKey.clear();
     quarantinedRuntimeExposurePorts.clear();
     exposurePortPairClaims.clear();
     workspaceRuntimeExposureDeps = defaultWorkspaceRuntimeExposureDeps();
@@ -1709,20 +1737,83 @@ export async function ensureGitWorktreeBranchCoherent(input) {
         ],
     };
 }
+// A configured base ref that does not resolve to a commit, even after an
+// authenticated fetch of its `origin/<branch>` counterpart. The caller must
+// stop before `git worktree add` and raise a pre-dispatch configuration
+// failure. `requestedRef` keeps the operator spelling for the human notice.
+// `recoveryIdentityRef` is the canonical remote ref the resolver probed, so two
+// equivalent spellings of one remote branch map to one recovery identity.
+// `attemptedRefs` names each ref the resolver tried, and `fetchError` carries
+// the first fetch warning (masked) when the fetch itself failed.
+export class UnresolvedWorkspaceBaseRefError extends Error {
+    requestedRef;
+    recoveryIdentityRef;
+    attemptedRefs;
+    fetchError;
+    constructor(input) {
+        super(`Configured workspace base ref "${input.requestedRef}" did not resolve to a commit on origin after an authenticated fetch.`);
+        this.name = "UnresolvedWorkspaceBaseRefError";
+        this.requestedRef = input.requestedRef;
+        this.recoveryIdentityRef = input.recoveryIdentityRef;
+        this.attemptedRefs = input.attemptedRefs;
+        this.fetchError = input.fetchError ?? null;
+    }
+}
+export function isUnresolvedWorkspaceBaseRefError(error) {
+    return error instanceof UnresolvedWorkspaceBaseRefError;
+}
 // Resolve the authoritative base ref for a fresh worktree. A configured local
 // branch is mapped to its `origin/<branch>` counterpart so unpushed local
-// divergence never leaks into the task branch; remote-tracking refs, SHAs, and
-// tags are used verbatim, and an unset/`HEAD` base falls back to the detected
-// default branch (which already prefers `origin/master`).
+// divergence never leaks into the task branch; SHAs and tags are used verbatim,
+// and an unset/`HEAD` base falls back to the detected default branch (which
+// already prefers `origin/master`).
+//
+// A remote-only feature branch never has a local ref or a remote-tracking ref
+// yet. The resolver fetches `origin/<branch>` with the authenticated helper,
+// then re-checks the commit. This covers both the unqualified form (`fix/foo`)
+// and the remote-tracking form (`origin/fix/foo`). A ref that still does not
+// resolve returns `resolved: false`, so the caller stops before the worktree
+// add instead of passing an invalid reference to git.
 async function resolveAuthoritativeBaseRef(repoRoot, configuredBaseRef, resolveGitAuth) {
     const warnings = [];
     const detectOrHead = async () => (await detectDefaultBranch(repoRoot, resolveGitAuth)) ?? "HEAD";
     const configured = configuredBaseRef?.trim();
     if (!configured || configured === "HEAD") {
-        return { baseRef: await detectOrHead(), warnings, refreshed: false };
+        return { resolved: true, baseRef: await detectOrHead(), warnings, refreshed: false };
     }
-    if (parseRemoteTrackingRef(configured)) {
-        return { baseRef: configured, warnings, refreshed: false };
+    // A remote-tracking ref supplied directly (for example `origin/fix/foo`).
+    // Use it verbatim when it already resolves. When it does not, fetch it once
+    // and re-check, then stop if it is still absent on the remote.
+    //
+    // `parseRemoteTrackingRef` only checks the `remote/branch` shape. An
+    // unqualified branch name that contains a slash (for example `fix/foo`) has
+    // the same shape but names no real remote, so it is not a remote-tracking
+    // ref. Gate this branch on the first segment naming an existing remote, and
+    // let a name like `fix/foo` fall through to the remote-only branch handling
+    // below.
+    const remoteTracking = parseRemoteTrackingRef(configured);
+    if (remoteTracking && await resolveBaseRefSha(repoRoot, configured)) {
+        return { resolved: true, baseRef: configured, warnings, refreshed: false };
+    }
+    if (remoteTracking && await remoteExists(repoRoot, remoteTracking.remote)) {
+        const fetchWarnings = await refreshRemoteTrackingBaseRef(repoRoot, configured, resolveGitAuth);
+        warnings.push(...fetchWarnings);
+        if (await resolveBaseRefSha(repoRoot, configured)) {
+            return { resolved: true, baseRef: configured, warnings, refreshed: true };
+        }
+        // Build the recovery identity from the parsed remote and branch. The raw
+        // ref and its remote-tracking spelling (`origin/fix/foo` and
+        // `refs/remotes/origin/fix/foo`) then share one recovery fingerprint, so
+        // recovery treats them as one identity instead of two.
+        const canonicalRemoteRef = `${remoteTracking.remote}/${remoteTracking.branch}`;
+        return {
+            resolved: false,
+            requestedRef: configured,
+            recoveryIdentityRef: canonicalRemoteRef,
+            attemptedRefs: [configured],
+            warnings,
+            fetchError: fetchWarnings[0] ?? null,
+        };
     }
     if (await localBranchExists(repoRoot, configured)) {
         const remoteCandidate = `origin/${configured}`;
@@ -1730,14 +1821,34 @@ async function resolveAuthoritativeBaseRef(repoRoot, configuredBaseRef, resolveG
         // the returned ref (see `refreshed`) so we never fetch the same ref twice.
         warnings.push(...await refreshRemoteTrackingBaseRef(repoRoot, remoteCandidate, resolveGitAuth));
         if (await resolveBaseRefSha(repoRoot, remoteCandidate)) {
-            return { baseRef: remoteCandidate, warnings, refreshed: true };
+            return { resolved: true, baseRef: remoteCandidate, warnings, refreshed: true };
         }
         if (await remoteExists(repoRoot, "origin")) {
             warnings.push(`Configured base ref "${configured}" is a local branch with no matching origin/${configured}; basing the execution workspace on the local ref, which may include unpushed commits.`);
         }
-        return { baseRef: configured, warnings, refreshed: false };
+        return { resolved: true, baseRef: configured, warnings, refreshed: false };
     }
-    return { baseRef: configured, warnings, refreshed: false };
+    // Fall-through: an unqualified ref (for example `fix/foo`) that is not `HEAD`,
+    // not a remote-tracking ref, and not a local branch. A full SHA or a tag that
+    // already resolves stays verbatim. Otherwise treat it as a remote-only branch
+    // name: fetch `origin/<ref>` and base the worktree on the remote counterpart.
+    if (await resolveBaseRefSha(repoRoot, configured)) {
+        return { resolved: true, baseRef: configured, warnings, refreshed: false };
+    }
+    const remoteCandidate = `origin/${configured}`;
+    const fetchWarnings = await refreshRemoteTrackingBaseRef(repoRoot, remoteCandidate, resolveGitAuth);
+    warnings.push(...fetchWarnings);
+    if (await resolveBaseRefSha(repoRoot, remoteCandidate)) {
+        return { resolved: true, baseRef: remoteCandidate, warnings, refreshed: true };
+    }
+    return {
+        resolved: false,
+        requestedRef: configured,
+        recoveryIdentityRef: remoteCandidate,
+        attemptedRefs: [remoteCandidate],
+        warnings,
+        fetchError: fetchWarnings[0] ?? null,
+    };
 }
 // Auto-refresh a reused worktree to the latest base only when it is provably
 // unstarted: no task commits past the base and a clean tree (including untracked
@@ -2026,6 +2137,15 @@ function buildWorkspaceCommandEnv(input) {
 function quoteShellArg(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
+const BUILTIN_WORKSPACE_PROVISION_COMMAND = "bash ./scripts/provision-worktree.sh";
+function resolveWorkspaceProvisionCommand(strategy, repoRoot) {
+    const configuredCommand = asString(strategy.provisionCommand, "").trim();
+    if (configuredCommand)
+        return configuredCommand;
+    return existsSync(path.join(repoRoot, "scripts", "provision-worktree.sh"))
+        ? BUILTIN_WORKSPACE_PROVISION_COMMAND
+        : "";
+}
 function resolveRepoManagedWorkspaceCommand(command, repoRoot) {
     const patterns = [
         /^(?<prefix>(?:bash|sh|zsh)\s+)(?<quote>["']?)(?<relative>\.\/[^"'\s]+)\k<quote>(?<suffix>(?:\s.*)?)$/s,
@@ -2131,27 +2251,33 @@ async function recordWorkspaceCommandOperation(recorder, input) {
                 cwd: input.cwd,
                 env: input.env,
             });
+            const seedEvidence = input.phase === "workspace_seed"
+                ? readWorkspaceSeedOperationEvidence(input.cwd)
+                : null;
             stdout = result.stdout;
-            stderr = result.stderr;
-            code = result.code;
+            stderr = [result.stderr, seedEvidence?.error].filter(Boolean).join("\n");
+            code = result.code === 0 && seedEvidence && !seedEvidence.verified ? 1 : result.code;
             if (result.stdout && input.onLog)
                 await input.onLog("stdout", `[runtime-provision] ${result.stdout}`);
-            if (result.stderr && input.onLog)
-                await input.onLog("stderr", `[runtime-provision] ${result.stderr}`);
+            if (stderr && input.onLog)
+                await input.onLog("stderr", `[runtime-provision] ${stderr}`);
+            const truncationMetadata = result.stdoutTruncated || result.stderrTruncated
+                ? {
+                    stdoutTruncated: result.stdoutTruncated,
+                    stderrTruncated: result.stderrTruncated,
+                    stdoutBytes: result.stdoutBytes,
+                    stderrBytes: result.stderrBytes,
+                }
+                : null;
             return {
-                status: result.code === 0 ? "succeeded" : "failed",
-                exitCode: result.code,
+                status: code === 0 ? "succeeded" : "failed",
+                exitCode: code,
                 stdout: result.stdout,
-                stderr: result.stderr,
-                system: result.code === 0 ? input.successMessage ?? null : null,
-                metadata: result.stdoutTruncated || result.stderrTruncated
-                    ? {
-                        stdoutTruncated: result.stdoutTruncated,
-                        stderrTruncated: result.stderrTruncated,
-                        stdoutBytes: result.stdoutBytes,
-                        stderrBytes: result.stderrBytes,
-                    }
-                    : null,
+                stderr,
+                system: code === 0 ? input.successMessage ?? null : null,
+                metadata: seedEvidence
+                    ? { ...seedEvidence.metadata, ...(truncationMetadata ?? {}) }
+                    : truncationMetadata,
             };
         },
     });
@@ -2163,7 +2289,7 @@ async function recordWorkspaceCommandOperation(recorder, input) {
         : `${input.label} failed with exit code ${code ?? -1}`);
 }
 async function provisionExecutionWorktree(input) {
-    const provisionCommand = asString(input.strategy.provisionCommand, "").trim();
+    const provisionCommand = resolveWorkspaceProvisionCommand(input.strategy, input.repoRoot);
     if (!provisionCommand)
         return;
     const resolvedProvisionCommand = resolveRepoManagedWorkspaceCommand(provisionCommand, input.repoRoot);
@@ -2227,7 +2353,17 @@ async function resolveGitRepoRootForWorkspaceCleanup(worktreePath, projectWorksp
 export async function realizeExecutionWorkspace(input) {
     const rawStrategy = parseObject(input.config.workspaceStrategy);
     const strategyType = asString(rawStrategy.type, "project_primary");
+    const requestedExistingBranch = asString(rawStrategy.existingBranch, "").trim();
     if (strategyType !== "git_worktree") {
+        if (requestedExistingBranch) {
+            throw new WorkspaceRuntimeValidationFailure(`Workspace strategy pins existing branch "${requestedExistingBranch}" but has type "${strategyType}"; an exact-branch workspace requires strategy type "git_worktree". Set workspaceStrategy.type to "git_worktree" or remove existingBranch.`, {
+                workspaceValidation: {
+                    reason: "existing_branch_requires_git_worktree",
+                    requestedExistingBranch,
+                    strategyType,
+                },
+            });
+        }
         return {
             ...input.base,
             strategy: "project_primary",
@@ -2236,28 +2372,66 @@ export async function realizeExecutionWorkspace(input) {
             worktreePath: null,
             warnings: [],
             created: false,
+            branchCreatedByRuntime: false,
             baseRefSha: null,
         };
     }
     const repoRoot = await resolveGitOwnerRepoRoot(input.base.baseCwd);
-    const branchTemplate = asString(rawStrategy.branchTemplate, "{{issue.identifier}}-{{slug}}");
-    const renderedBranch = renderWorkspaceTemplate(branchTemplate, {
-        issue: input.issue,
-        agent: input.agent,
-        projectId: input.base.projectId,
-        repoRef: input.base.repoRef,
-    });
-    let branchName = sanitizeBranchName(renderedBranch);
+    let branchName;
+    if (requestedExistingBranch) {
+        // Exact-branch mode: attach the requested pre-existing branch verbatim.
+        // The branch must already exist; realization never creates, renames, or
+        // resets it, and any mismatch below fails closed instead of falling back
+        // to a derived branch or the shared checkout.
+        const existingBranchSha = await runGit(["rev-parse", "--verify", "--quiet", `refs/heads/${requestedExistingBranch}`], repoRoot).catch(() => null);
+        if (!existingBranchSha) {
+            throw new WorkspaceRuntimeValidationFailure(`Workspace strategy pins existing branch "${requestedExistingBranch}", but no local branch with that name exists in "${repoRoot}". Create or fetch the branch first, or remove workspaceStrategy.existingBranch; exact-branch realization never creates a branch.`, {
+                workspaceValidation: {
+                    reason: "existing_branch_not_found",
+                    requestedExistingBranch,
+                    repoRoot,
+                },
+            });
+        }
+        branchName = requestedExistingBranch;
+    }
+    else {
+        const branchTemplate = asString(rawStrategy.branchTemplate, "{{issue.identifier}}-{{slug}}");
+        const renderedBranch = renderWorkspaceTemplate(branchTemplate, {
+            issue: input.issue,
+            agent: input.agent,
+            projectId: input.base.projectId,
+            repoRef: input.base.repoRef,
+        });
+        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);
+    if (path.relative(worktreeParentDir, worktreePath).startsWith("..")) {
+        throw new WorkspaceRuntimeValidationFailure(`Workspace branch "${branchName}" resolves to a worktree path outside the managed worktree parent directory "${worktreeParentDir}".`, {
+            workspaceValidation: {
+                reason: "worktree_path_escapes_parent_dir",
+                branchName,
+                worktreeParentDir,
+            },
+        });
+    }
     let pendingForwardBranchReconcile = null;
     const configuredBaseRef = typeof rawStrategy.baseRef === "string" && rawStrategy.baseRef.length > 0
         ? rawStrategy.baseRef
         : input.base.repoRef ?? null;
-    const { baseRef, warnings: baseRefResolutionWarnings, refreshed: baseRefAlreadyRefreshed, } = await resolveAuthoritativeBaseRef(repoRoot, configuredBaseRef, input.resolveGitAuth);
+    const baseRefResolution = await resolveAuthoritativeBaseRef(repoRoot, configuredBaseRef, input.resolveGitAuth);
+    // Keep a usable base ref for the reuse and drift paths even when the ref is
+    // unresolved: those paths tolerate a null base-ref SHA and never run
+    // `git worktree add -b <branch> <baseRef>`. Only the fresh-create path below
+    // stops on an unresolved ref. `baseRefAlreadyRefreshed` is true for the
+    // unresolved case because the resolver already attempted the fetch.
+    const baseRef = baseRefResolution.resolved ? baseRefResolution.baseRef : baseRefResolution.requestedRef;
+    const baseRefResolutionWarnings = baseRefResolution.warnings;
+    const baseRefAlreadyRefreshed = baseRefResolution.resolved ? baseRefResolution.refreshed : true;
     const baseRefreshWarnings = [
         ...baseRefResolutionWarnings,
         ...(baseRefAlreadyRefreshed ? [] : await refreshRemoteTrackingBaseRef(repoRoot, baseRef, input.resolveGitAuth)),
@@ -2265,7 +2439,9 @@ export async function realizeExecutionWorkspace(input) {
     const currentBaseRefSha = await resolveBaseRefSha(repoRoot, baseRef);
     await fs.mkdir(worktreeParentDir, { recursive: true });
     async function reuseExistingWorktree(reusablePath, effectiveBranchName = branchName, extraWarnings = []) {
-        const refresh = currentBaseRefSha
+        // An exact-branch attach must never move the requested branch, so skip
+        // the unstarted-worktree fast-forward that template-derived reuse gets.
+        const refresh = currentBaseRefSha && !requestedExistingBranch
             ? await refreshUnstartedWorktreeToBase({
                 repoRoot,
                 worktreePath: reusablePath,
@@ -2324,6 +2500,14 @@ export async function realizeExecutionWorkspace(input) {
             worktreePath: reusablePath,
             warnings: [...extraWarnings, ...baseRefreshWarnings, ...baseDrift.warnings],
             created: false,
+            // A fresh realization may still land on the worktree recorded by a
+            // previous heartbeat. Preserve that branch's ownership only when the
+            // recorded branch matches the checkout being reused. Exact-branch mode
+            // remains operator-owned by contract; every mismatch likewise fails
+            // safe and leaves the branch behind during terminal cleanup.
+            branchCreatedByRuntime: !requestedExistingBranch
+                && input.recordedBranchOwnership?.branchName === effectiveBranchName
+                && input.recordedBranchOwnership.createdByRuntime === true,
             baseRefSha: refresh.baseRefSha ?? baseDrift.branchBaseRefSha ?? baseDrift.currentBaseRefSha,
             pendingForwardBranchReconcile,
         };
@@ -2335,6 +2519,11 @@ export async function realizeExecutionWorkspace(input) {
             expectedBranchName: branchName,
         }).catch(() => null);
         if (validation && !validation.valid && validation.reasonCode === "branch_mismatch") {
+            if (requestedExistingBranch) {
+                // Exact-branch mode never reconciles a mismatched checkout onto
+                // another branch; the caller fails closed with the mismatch reason.
+                return { validation, branchName, warnings: [] };
+            }
             const coherence = await ensureGitWorktreeBranchCoherent({
                 db: input.db ?? null,
                 repoRoot,
@@ -2375,6 +2564,16 @@ export async function realizeExecutionWorkspace(input) {
         }
         const validation = reusable.validation;
         const reason = validation && !validation.valid ? ` (${validation.reason})` : "";
+        if (requestedExistingBranch) {
+            throw new WorkspaceRuntimeValidationFailure(`Workspace strategy pins existing branch "${requestedExistingBranch}", but the worktree path "${worktreePath}" already exists and is not a reusable checkout of that branch${reason}. Repair or remove that worktree, then retry; exact-branch realization never reconciles it onto another branch.`, {
+                workspaceValidation: {
+                    reason: "existing_branch_worktree_not_reusable",
+                    reasonCode: validation && !validation.valid ? validation.reasonCode : null,
+                    requestedExistingBranch,
+                    worktreePath,
+                },
+            });
+        }
         throw new Error(`Configured worktree path "${worktreePath}" already exists and is not a reusable git worktree${reason}.`);
     }
     const registeredBranchWorktree = await findRegisteredGitWorktreeByBranch(repoRoot, branchName);
@@ -2385,8 +2584,86 @@ export async function realizeExecutionWorkspace(input) {
         }
         const validation = reusable.validation;
         const reason = validation && !validation.valid ? ` (${validation.reason})` : "";
+        if (requestedExistingBranch) {
+            throw new WorkspaceRuntimeValidationFailure(`Workspace strategy pins existing branch "${requestedExistingBranch}", which is already checked out at "${registeredBranchWorktree}", but that worktree is not reusable${reason}. Repair or remove that worktree, then retry.`, {
+                workspaceValidation: {
+                    reason: "existing_branch_worktree_not_reusable",
+                    reasonCode: validation && !validation.valid ? validation.reasonCode : null,
+                    requestedExistingBranch,
+                    worktreePath: registeredBranchWorktree,
+                },
+            });
+        }
         throw new Error(`Registered worktree for branch "${branchName}" at "${registeredBranchWorktree}" is not reusable${reason}.`);
     }
+    if (requestedExistingBranch) {
+        try {
+            await recordGitOperation(input.recorder, {
+                phase: "worktree_prepare",
+                args: ["worktree", "add", worktreePath, branchName],
+                cwd: repoRoot,
+                metadata: {
+                    repoRoot,
+                    worktreePath,
+                    branchName,
+                    baseRef,
+                    baseRefSha: currentBaseRefSha,
+                    created: false,
+                    attachedExistingBranch: true,
+                },
+                successMessage: `Attached existing branch ${branchName} at ${worktreePath}\n`,
+                failureLabel: `git worktree add ${worktreePath}`,
+            });
+        }
+        catch (attachError) {
+            const message = attachError instanceof Error ? attachError.message : String(attachError);
+            throw new WorkspaceRuntimeValidationFailure(`Could not attach existing branch "${requestedExistingBranch}" as a git worktree at "${worktreePath}": ${message}`, {
+                workspaceValidation: {
+                    reason: "existing_branch_attach_failed",
+                    requestedExistingBranch,
+                    worktreePath,
+                },
+            });
+        }
+        await provisionExecutionWorktree({
+            strategy: rawStrategy,
+            base: input.base,
+            repoRoot,
+            worktreePath,
+            branchName,
+            issue: input.issue,
+            agent: input.agent,
+            created: true,
+            recorder: input.recorder ?? null,
+        });
+        return {
+            ...input.base,
+            repoRef: baseRef,
+            strategy: "git_worktree",
+            cwd: worktreePath,
+            branchName,
+            worktreePath,
+            warnings: baseRefreshWarnings,
+            // The worktree is new, but the pinned branch pre-existed: it stays
+            // operator-owned so terminal cleanup never deletes it.
+            created: true,
+            branchCreatedByRuntime: false,
+            baseRefSha: currentBaseRefSha,
+        };
+    }
+    // No reusable worktree exists, so a fresh `git worktree add -b <branch> <baseRef>`
+    // must run next. An unresolved base ref would make git fail with
+    // `fatal: invalid reference`. Stop here instead and raise a pre-dispatch
+    // configuration failure that the setup catch routes to a human owner.
+    if (!baseRefResolution.resolved) {
+        throw new UnresolvedWorkspaceBaseRefError({
+            requestedRef: baseRefResolution.requestedRef,
+            recoveryIdentityRef: baseRefResolution.recoveryIdentityRef,
+            attemptedRefs: baseRefResolution.attemptedRefs,
+            fetchError: baseRefResolution.fetchError,
+        });
+    }
+    let branchCreatedByRuntime = true;
     try {
         await recordGitOperation(input.recorder, {
             phase: "worktree_prepare",
@@ -2425,6 +2702,9 @@ export async function realizeExecutionWorkspace(input) {
                 successMessage: `Attached existing branch ${branchName} at ${worktreePath}\n`,
                 failureLabel: `git worktree add ${worktreePath}`,
             });
+            // The template rendered to a branch that already existed, so this
+            // attach did not create the branch and cleanup must not delete it.
+            branchCreatedByRuntime = false;
         }
         catch (attachError) {
             if (!gitErrorIncludes(attachError, "already checked out")) {
@@ -2457,6 +2737,7 @@ export async function realizeExecutionWorkspace(input) {
         worktreePath,
         warnings: baseRefreshWarnings,
         created: true,
+        branchCreatedByRuntime,
         baseRefSha: currentBaseRefSha,
     };
 }
@@ -2479,6 +2760,11 @@ export async function ensurePersistedExecutionWorkspaceAvailable(input) {
         worktreePath: strategy === "git_worktree" ? (input.workspace.providerRef ?? cwd) : null,
         warnings: [],
         created: false,
+        // Only the versioned ownership record introduced with branch-level
+        // ownership semantics can authorize branch recreation or deletion. Older
+        // createdByRuntime=true rows described worktree ownership, so trusting
+        // them here could recreate or later delete an operator-owned branch.
+        branchCreatedByRuntime: isRuntimeOwnedGitBranch(input.workspace.metadata),
         baseRefSha: readRecordedBaseRefSha(input.workspace.metadata),
     };
     const provisionCommand = asString(input.workspace.config?.provisionCommand, "").trim();
@@ -2507,7 +2793,12 @@ export async function ensurePersistedExecutionWorkspaceAvailable(input) {
         const reuseBaseRef = input.workspace.baseRef ?? input.base.repoRef ?? null;
         const reuseWorktreePath = realized.worktreePath ?? cwd;
         const repairWarnings = [];
-        if (await isGitCheckout(reuseWorktreePath)) {
+        if (await isGitCheckout(reuseWorktreePath) && realized.branchCreatedByRuntime) {
+            // Branch-coherence repair may check out another branch, adopt a forward
+            // branch, or move the recorded ref from a detached HEAD. Those repairs
+            // are valid only for a branch that this runtime created. An attached
+            // operator-owned branch must retain its exact identity and tip; the
+            // validation below rejects any mismatch without mutating Git state.
             const coherence = await ensureGitWorktreeBranchCoherent({
                 db: input.db ?? null,
                 repoRoot,
@@ -2549,7 +2840,9 @@ export async function ensurePersistedExecutionWorkspaceAvailable(input) {
             ? await refreshRemoteTrackingBaseRef(repoRoot, reuseBaseRef, input.resolveGitAuth)
             : [];
         const currentBaseRefSha = reuseBaseRef ? await resolveBaseRefSha(repoRoot, reuseBaseRef) : null;
-        const refresh = reuseBaseRef && currentBaseRefSha
+        // An unstarted-worktree refresh can fast-forward the checked-out branch.
+        // Never run it for an attached operator-owned ref.
+        const refresh = realized.branchCreatedByRuntime && reuseBaseRef && currentBaseRefSha
             ? await refreshUnstartedWorktreeToBase({
                 repoRoot,
                 worktreePath: reuseWorktreePath,
@@ -2569,22 +2862,20 @@ export async function ensurePersistedExecutionWorkspaceAvailable(input) {
         });
         realized.warnings = [...repairWarnings, ...baseRefreshWarnings, ...baseDrift.warnings];
         realized.baseRefSha = refresh.baseRefSha ?? recordedBaseRefSha ?? baseDrift.branchBaseRefSha ?? baseDrift.currentBaseRefSha;
-        if (provisionCommand) {
-            await provisionExecutionWorktree({
-                strategy: {
-                    type: "git_worktree",
-                    provisionCommand,
-                },
-                base: input.base,
-                repoRoot,
-                worktreePath: realized.worktreePath ?? cwd,
-                branchName: realized.branchName ?? "",
-                issue: input.issue,
-                agent: input.agent,
-                created: false,
-                recorder: input.recorder ?? null,
-            });
-        }
+        await provisionExecutionWorktree({
+            strategy: {
+                type: "git_worktree",
+                ...(provisionCommand ? { provisionCommand } : {}),
+            },
+            base: input.base,
+            repoRoot,
+            worktreePath: realized.worktreePath ?? cwd,
+            branchName: realized.branchName ?? "",
+            issue: input.issue,
+            agent: input.agent,
+            created: false,
+            recorder: input.recorder ?? null,
+        });
         return realized;
     }
     const worktreePath = realized.worktreePath ?? cwd;
@@ -2624,6 +2915,9 @@ export async function ensurePersistedExecutionWorkspaceAvailable(input) {
             && !gitErrorIncludes(error, "unknown revision")) {
             throw error;
         }
+        if (!realized.branchCreatedByRuntime) {
+            throw new Error(`Execution workspace "${worktreePath}" cannot be restored because its operator-owned branch "${branchName}" no longer exists.`);
+        }
         const baseRef = input.workspace.baseRef ?? await detectDefaultBranch(repoRoot) ?? "HEAD";
         const recreatedBaseRefSha = await resolveBaseRefSha(repoRoot, baseRef);
         await recordGitOperation(input.recorder, {
@@ -2672,6 +2966,7 @@ export async function ensurePersistedExecutionWorkspaceAvailable(input) {
         worktreePath,
         warnings: [...restoreRefreshWarnings, ...baseDrift.warnings],
         created,
+        branchCreatedByRuntime: realized.branchCreatedByRuntime || created,
         baseRefSha: recordedBaseRefSha
             ?? (created ? restoreCurrentBaseRefSha : baseDrift.branchBaseRefSha)
             ?? baseDrift.currentBaseRefSha,
@@ -2789,7 +3084,12 @@ export async function cleanupExecutionWorkspaceArtifacts(input) {
             warnings.push(`Could not read worktree instance pointer: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    // Local-directory ownership keeps the historical createdByRuntime signal.
+    // Git branch deletion additionally requires the version marker introduced
+    // with branch-level ownership semantics. Unmarked legacy rows fail closed:
+    // their worktrees are removable, but their branch refs are operator-owned.
     const createdByRuntime = input.workspace.metadata?.createdByRuntime === true;
+    const branchCreatedByRuntime = isRuntimeOwnedGitBranch(input.workspace.metadata);
     const cleanupCommands = input.runCleanupCommands === false
         ? []
         : [
@@ -2877,7 +3177,7 @@ export async function cleanupExecutionWorkspaceArtifacts(input) {
                 }
             }
         }
-        if (createdByRuntime && input.workspace.branchName) {
+        if (branchCreatedByRuntime && input.workspace.branchName) {
             if (!repoRoot) {
                 warnings.push(`Could not resolve git repo root to delete branch "${input.workspace.branchName}".`);
             }
@@ -3269,6 +3569,83 @@ async function canBindRuntimePort(port) {
         });
     });
 }
+/**
+ * True when a loopback listener is present on the port, read WITHOUT binding it.
+ *
+ * The readiness wait must never bind the exact port the guest is about to bind.
+ * A probe `listen()` holds the port for the length of one bind/close, and if the
+ * guest's own `listen()` lands in that window the guest fails with EADDRINUSE on
+ * its assigned port. That self-inflicted race is the runtime exposure port flake
+ * (a slow guest under load loses the race to the parent probe). A `/proc` read
+ * carries the same "a listener appeared" signal with no bind. Where `/proc` is
+ * absent (non-Linux dev hosts), fall back to the bind probe; those hosts do not
+ * run the concurrent managed lanes that expose the race.
+ */
+async function hasLoopbackPortListener(port) {
+    const facts = await readListenerBindFacts(port).catch(() => null);
+    if (facts)
+        return facts.present;
+    return !(await canBindRuntimePort(port));
+}
+/**
+ * True when one line of the failure text reports an EADDRINUSE bind conflict on
+ * the given port.
+ *
+ * Node prints the failing bind on a single line, for example
+ * `Error: listen EADDRINUSE: address already in use 127.0.0.1:42000`. The match
+ * requires the EADDRINUSE marker and the port on the SAME line. So an
+ * auxiliary-port conflict on one line cannot combine with an unrelated
+ * assigned-port mention on a different, benign line and trigger a wrong
+ * quarantine.
+ *
+ * Node formats a bind address as `host:port`, so the failing port always
+ * follows a colon (for example `127.0.0.1:42000` or `:::42000`). The match
+ * requires that colon and a full-number boundary. So a different port in the
+ * same line cannot look like the assigned app or HMR port, and port 4200 never
+ * matches `:42000`.
+ */
+function eaddrinuseTextNamesPort(text, port) {
+    const eaddrinusePattern = /EADDRINUSE|address already in use/i;
+    const portPattern = new RegExp(`:${port}(?![0-9])`);
+    return text
+        .split(/\r?\n/)
+        .some((line) => eaddrinusePattern.test(line) && portPattern.test(line));
+}
+/**
+ * Decide which assigned exposure ports a real host listener owns after a guest
+ * start failure.
+ *
+ * The guest owns its own output, so an assigned-port EADDRINUSE line is a claim,
+ * not proof. A managed guest can print a synthetic EADDRINUSE line for its
+ * assigned port with no host listener behind it. A quarantine on that text alone
+ * would drain the shared exposure-port pool across repeated starts. So a port
+ * counts as a host collision only when all of the following hold:
+ * - the failure text names the port with EADDRINUSE, and
+ * - a real listener is present on the port now, and
+ * - the listener owner is not the guest process the runtime just launched, nor a
+ *   descendant of it.
+ *
+ * The runtime launches the guest as a shell process group leader, so the real dev
+ * server usually binds the port from a descendant, not the shell pid itself. The
+ * ownership test therefore matches the shell pid against both the owner pid and
+ * the owner process group id. This is the same process-group attribution that
+ * `isLocalServiceProcessOwnedBy` applies on the host platform. A raw pid equality
+ * would treat a guest descendant as an external owner and quarantine a valid pair.
+ *
+ * An unknown owner with a present listener counts as a host owner: the /proc read
+ * proves a listener, and a guest that lost its assigned port does not hold it.
+ */
+export function classifyExposureHostCollisions(input) {
+    const hostCollisionPorts = [];
+    for (const state of input.ports) {
+        const guestOwnsPort = input.childPid != null &&
+            (state.ownerPid === input.childPid || state.ownerProcessGroupId === input.childPid);
+        if (state.named && state.listenerPresent && !guestOwnsPort) {
+            hostCollisionPorts.push(state.port);
+        }
+    }
+    return { hostCollisionPorts, hostCollision: hostCollisionPorts.length > 0 };
+}
 async function readReservedRuntimePorts(input) {
     if (!input.db || input.ports.length === 0)
         return new Set();
@@ -3373,6 +3750,14 @@ export async function allocateRuntimeServicePort(overrides) {
     for (let attempt = 0; attempt < PORT_ALLOCATION_ATTEMPTS; attempt += 1) {
         const candidate = await probe();
         lastCandidate = candidate;
+        // Never hand back a port inside the runtime exposure app-port range. The
+        // reconciler classifies a persisted row by its port. A port in that range
+        // marks the row as an exposure reservation, not a managed auto port. An auto
+        // port from that range makes the reconciler read a stopped managed row as an
+        // exposure reservation and report drift instead of the adoption. The kernel
+        // can hand out an ephemeral port in that band, so skip the candidate here.
+        if (isRuntimeExposureAppPort(candidate))
+            continue;
         if (!reservePortIfFree(candidate))
             continue;
         const ownerPid = await portOwnerLookup(candidate);
@@ -3614,9 +3999,10 @@ async function waitForAllocatedPortBind(input) {
             }
             return;
         }
-        // A failed bind probe proves only that some listener appeared. If listener ownership cannot
+        // A present listener proves only that some listener appeared. If listener ownership cannot
         // be attributed to this child after a stability delay, retry instead of accepting a sibling.
-        if (!(await canBindRuntimePort(input.port))) {
+        // The presence read never binds the port, so it cannot steal the port from the child.
+        if (await hasLoopbackPortListener(input.port)) {
             await delay(250);
             if (input.child.exitCode !== null || input.child.signalCode !== null) {
                 throw new Error("service process exited after losing its allocated port");
@@ -3655,15 +4041,73 @@ function resolveRuntimeServiceHealthUrl(url, input) {
     }
     return url;
 }
+/**
+ * Whether a managed workspace runtime satisfies the *user* readiness contract.
+ *
+ * Returns null when this service is not an identity-resolvable managed workspace
+ * runtime, so non-workspace services keep their existing behavior.
+ *
+ * For a workspace runtime this *replaces* the semantic transport check rather
+ * than adding to it. The probe reads the same `/api/health` response the legacy
+ * check read, so every legacy verdict is already implied: reaching
+ * `readiness_missing` means the response was `200` with `status: ok` (exactly
+ * what the legacy check asserted), and every other rejection means it was not.
+ * Stacking a second request on top would double the latency of every reuse
+ * decision for no extra information.
+ */
+async function probeManagedWorkspaceRuntimeReadiness(healthUrl, input) {
+    if (!isPaperclipDevRuntimeService(input))
+        return null;
+    const identity = resolveManagedWorkspaceIdentity({
+        workspaceCwd: input.cwd ?? null,
+        executionWorkspaceId: input.executionWorkspaceId ?? null,
+        companyId: input.companyId ?? null,
+    });
+    if (!identity)
+        return null;
+    const result = await probeManagedWorkspaceReadiness({ healthUrl, identity });
+    const verified = !result.ok
+        ? result
+        : input.db
+            ? await probeManagedWorkspaceHandoffSubjects({ db: input.db, healthUrl, identity })
+            : {
+                ok: false,
+                reason: "not_ready",
+                readiness: result.readiness,
+                detail: "control-plane database is unavailable for board identity verification",
+            };
+    if (verified.ok)
+        return true;
+    logManagedWorkspaceReadinessRejection({
+        executionWorkspaceId: identity.executionWorkspaceId,
+        healthUrl,
+        result: verified,
+    });
+    // A guest that does not implement the readiness contract yet is not evidence of
+    // an unhealthy clone; it is only evidence that the contract cannot be checked.
+    return !shouldBlockPublicationOnReadiness(verified);
+}
 async function isRuntimeServiceUrlHealthy(url, input) {
-    if (!url)
+    const localProbeUrl = input?.provider === "local_process" && input.port && isPaperclipDevRuntimeService(input)
+        ? `http://127.0.0.1:${input.port}`
+        : null;
+    const probeUrl = localProbeUrl ?? url;
+    if (!probeUrl)
         return true;
-    const healthUrl = resolveRuntimeServiceHealthUrl(url, input);
+    const healthUrl = resolveRuntimeServiceHealthUrl(probeUrl, input);
     if (!healthUrl)
         return false;
+    const readiness = await probeManagedWorkspaceRuntimeReadiness(healthUrl, input ?? {});
+    if (readiness !== null)
+        return readiness;
     try {
         const response = await fetch(healthUrl, { signal: AbortSignal.timeout(2_000) });
-        return response.ok;
+        if (!response.ok)
+            return false;
+        if (!isPaperclipDevRuntimeService(input ?? {}))
+            return true;
+        const payload = await response.json().catch(() => null);
+        return payload?.status === "ok";
     }
     catch {
         return false;
@@ -3845,6 +4289,42 @@ function readRuntimeProvisionCommand(config) {
     const workspaceStrategy = parseObject(config.workspaceStrategy);
     return asString(config.runtimeProvisionCommand, asString(workspaceStrategy.runtimeProvisionCommand, "")).trim();
 }
+const BUILTIN_WORKSPACE_SEED_COMMAND = "bash ./scripts/provision-worktree-runtime.sh";
+function readWorkspaceSeedOperationEvidence(worktreePath) {
+    const manifestPath = path.join(worktreePath, ".paperclip", "seed-manifest.json");
+    try {
+        const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+        const state = typeof manifest.state === "string" ? manifest.state : "unknown";
+        const phase = typeof manifest.phase === "string" ? manifest.phase : null;
+        const verified = isVerifiedWorktreeSeedManifest(manifest);
+        return {
+            verified,
+            error: verified
+                ? null
+                : phase
+                    ? `Workspace seed command returned without a verified manifest (state: ${state}, phase: ${phase}).`
+                    : `Workspace seed command returned without a verified manifest (state: ${state}).`,
+            metadata: {
+                provisionKind: "workspace_seed",
+                seedState: state,
+                seedPhase: phase,
+                seedFailurePhase: state === "failed" ? phase : null,
+            },
+        };
+    }
+    catch {
+        return {
+            verified: false,
+            error: "Workspace seed command returned without a readable seed manifest.",
+            metadata: {
+                provisionKind: "workspace_seed",
+                seedState: existsSync(manifestPath) ? "unreadable" : "absent",
+                seedPhase: null,
+                seedFailurePhase: "seed_manifest_unreadable",
+            },
+        };
+    }
+}
 export function resolveRuntimeProvisionCommand(input) {
     const configuredCommand = readRuntimeProvisionCommand(input.config);
     if (configuredCommand)
@@ -3852,15 +4332,24 @@ export function resolveRuntimeProvisionCommand(input) {
     if (input.workspace.strategy !== "git_worktree")
         return "";
     const stateDir = path.join(input.workspace.cwd, ".paperclip");
-    const pendingMarker = path.join(stateDir, "seed-pending");
-    const completeMarker = path.join(stateDir, "seed-complete");
+    const manifestPath = path.join(stateDir, "seed-manifest.json");
     const provisionScript = path.join(input.workspace.baseCwd, "scripts", "provision-worktree-runtime.sh");
-    if (!existsSync(pendingMarker)
-        || existsSync(completeMarker)
-        || !existsSync(provisionScript)) {
+    const needsSeed = !existsSync(manifestPath) || !hasVerifiedWorktreeSeedManifest(manifestPath);
+    if (!needsSeed || !existsSync(provisionScript)) {
         return "";
     }
-    return "bash ./scripts/provision-worktree-runtime.sh";
+    return BUILTIN_WORKSPACE_SEED_COMMAND;
+}
+function resolveRuntimeProvision(input) {
+    const command = resolveRuntimeProvisionCommand(input);
+    if (!command)
+        return { command, kind: null };
+    return {
+        command,
+        kind: readRuntimeProvisionCommand(input.config)
+            ? "runtime_dependencies"
+            : "workspace_seed",
+    };
 }
 function runtimeProvisionWorkspaceKey(input) {
     return input.executionWorkspaceId
@@ -3888,8 +4377,9 @@ async function runRuntimeProvisionWithWorkspaceMutex(input) {
         })
         : null);
     const resolvedCommand = resolveRepoManagedWorkspaceCommand(command, input.workspace.baseCwd);
+    const workspaceSeed = input.runtimeProvisionKind === "workspace_seed";
     const promise = recordWorkspaceCommandOperation(recorder, {
-        phase: "workspace_runtime_provision",
+        phase: workspaceSeed ? "workspace_seed" : "workspace_runtime_provision",
         command,
         resolvedCommand,
         cwd: input.workspace.cwd,
@@ -3902,14 +4392,19 @@ async function runRuntimeProvisionWithWorkspaceMutex(input) {
             agent: input.agent,
             created: input.workspace.created,
         }),
-        label: `Runtime provision command "${command}"`,
+        label: workspaceSeed
+            ? `Workspace seed command "${command}"`
+            : `Runtime provision command "${command}"`,
         metadata: {
             executionWorkspaceId: input.executionWorkspaceId ?? null,
             projectWorkspaceId: input.workspace.workspaceId,
             serviceName: asString(input.service.name, "service"),
+            provisionKind: workspaceSeed ? "workspace_seed" : "runtime_dependencies",
             resolvedCommand: resolvedCommand === command ? null : resolvedCommand,
         },
-        successMessage: `Provisioned runtime dependencies for ${input.workspace.cwd}\n`,
+        successMessage: workspaceSeed
+            ? `Verified the workspace database seed for ${input.workspace.cwd}\n`
+            : `Provisioned runtime dependencies for ${input.workspace.cwd}\n`,
         onLog: input.onLog,
     }).then(() => undefined);
     runtimeProvisionByWorkspace.set(workspaceKey, promise);
@@ -4192,12 +4687,26 @@ async function spawnLocalRuntimeService(input) {
         const portEnvKey = asString(portConfig.envKey, "PORT");
         env[portEnvKey] = String(port);
     }
+    // Per-workspace handoff key, readiness token, and workspace id. Injected for
+    // the Paperclip dev runtime whether or not it is HTTPS-exposed, because the
+    // password-independent login handoff and the protected readiness probe are
+    // both needed for a plain-HTTP loopback workspace too (PAP-17572).
+    const managedWorkspaceIdentity = isPaperclipDevRuntimeService({ serviceName, command })
+        ? resolveManagedWorkspaceIdentity({
+            workspaceCwd: input.workspace.cwd,
+            executionWorkspaceId: input.executionWorkspaceId ?? null,
+            companyId: input.agent.companyId,
+        })
+        : null;
+    if (managedWorkspaceIdentity) {
+        Object.assign(env, buildManagedWorkspaceGuestEnv(managedWorkspaceIdentity));
+    }
     if (exposureConfig) {
         // Paperclip dev-runtime-specific hardening. Other managed processes are
         // still rejected by the broker unless /proc proves loopback-only listeners.
         //
         // Three independent layers force the loopback bind, because a guest checkout
-        // can be arbitrarily old (PAP-17256): the `--bind custom --bind-host` argv
+        // can be arbitrarily old (PAP-17256): the `--bind loopback` argv
         // added above, these env vars for a runner that reads them, and HOST for one
         // old enough to ignore both and infer its bind mode from HOST alone.
         env.PAPERCLIP_BIND = RUNTIME_EXPOSURE_BIND_MODE;
@@ -4245,7 +4754,14 @@ async function spawnLocalRuntimeService(input) {
     });
     if (adoptedRecord) {
         const adoptedUrl = adoptedRecord.url ?? backendUrl;
-        if (!(await isRuntimeServiceUrlHealthy(adoptedUrl, { serviceName, command }))) {
+        if (!(await isRuntimeServiceUrlHealthy(adoptedUrl, {
+            db: input.db,
+            serviceName,
+            command,
+            cwd: input.workspace.cwd,
+            executionWorkspaceId: input.executionWorkspaceId ?? null,
+            companyId: input.agent.companyId,
+        }))) {
             await terminateLocalService(adoptedRecord);
             await removeLocalServiceRegistryRecord(adoptedRecord.serviceKey);
         }
@@ -4396,12 +4912,22 @@ async function spawnLocalRuntimeService(input) {
         throw error;
     }
     const shell = resolveShell();
-    const child = spawn(shell, ["-lc", command], {
-        cwd: serviceCwd,
-        env,
-        detached: process.platform !== "win32",
-        stdio: ["ignore", "pipe", "pipe"],
-    });
+    const serviceLog = await openLocalServiceLogFile(serviceKey);
+    let child;
+    try {
+        child = spawn(shell, ["-lc", command], {
+            cwd: serviceCwd,
+            env,
+            detached: process.platform !== "win32",
+            // The service receives duplicate append-only file descriptors. Closing
+            // Paperclip (or this parent handle below) cannot strand a request logger
+            // on an orphaned socketpair during startup reconciliation.
+            stdio: ["ignore", serviceLog.handle.fd, serviceLog.handle.fd],
+        });
+    }
+    finally {
+        await serviceLog.handle.close();
+    }
     record.child = child;
     record.providerRef = child.pid ? String(child.pid) : null;
     record.processGroupId = child.pid ?? null;
@@ -4411,24 +4937,22 @@ async function spawnLocalRuntimeService(input) {
         });
     });
     const earlyExitPromise = new Promise((_, reject) => {
-        child.once("exit", (code, signal) => {
+        // `close` follows `exit` after the child's inherited stdout/stderr file
+        // descriptors are closed. Waiting for it makes the startup log excerpt
+        // deterministic instead of racing the final validation line.
+        child.once("close", (code, signal) => {
             reject(new Error(`service process exited before readiness (code ${code ?? "unknown"}, signal ${signal ?? "none"})`));
         });
     });
-    let stderrExcerpt = "";
-    let stdoutExcerpt = "";
-    child.stdout?.on("data", async (chunk) => {
-        const text = String(chunk);
-        stdoutExcerpt = (stdoutExcerpt + text).slice(-4096);
-        if (input.onLog)
-            await input.onLog("stdout", `[service:${serviceName}] ${text}`);
-    });
-    child.stderr?.on("data", async (chunk) => {
-        const text = String(chunk);
-        stderrExcerpt = (stderrExcerpt + text).slice(-4096);
-        if (input.onLog)
-            await input.onLog("stderr", `[service:${serviceName}] ${text}`);
-    });
+    const readServiceOutputExcerpt = async () => {
+        try {
+            const contents = await fs.readFile(serviceLog.logPath);
+            return contents.subarray(Math.max(serviceLog.startOffset, contents.length - 4096)).toString("utf8");
+        }
+        catch {
+            return "";
+        }
+    };
     if (child.pid) {
         await writeLocalServiceRegistryRecord({
             version: 1,
@@ -4506,10 +5030,48 @@ async function spawnLocalRuntimeService(input) {
                 throw new Error(`HTTPS exposure failed: ${code}${provisioned.errorDetail ? ` — ${provisioned.errorDetail}` : ""}`);
             }
         }
+        // Transport readiness only proves a listener answered. A managed workspace
+        // must additionally satisfy the protected readiness contract — own database,
+        // cloned rows, login handoff, and matching instance/workspace identity —
+        // before it may be published as running/healthy (PAP-17572).
+        if (managedWorkspaceIdentity) {
+            const publishHealthUrl = resolveRuntimeServiceHealthUrl(record.port ? `http://127.0.0.1:${record.port}` : rewriteUrlHostToLoopback(record.url ?? backendUrl), { serviceName, command });
+            if (!publishHealthUrl) {
+                throw new Error("Managed workspace readiness gate could not resolve a health URL");
+            }
+            let gate = await waitForManagedWorkspaceReadiness({
+                healthUrl: publishHealthUrl,
+                identity: managedWorkspaceIdentity,
+            });
+            if (gate.ok) {
+                if (!record.db) {
+                    throw new Error("Managed workspace readiness gate could not resolve the control-plane database");
+                }
+                gate = await probeManagedWorkspaceHandoffSubjects({
+                    db: record.db,
+                    healthUrl: publishHealthUrl,
+                    identity: managedWorkspaceIdentity,
+                });
+            }
+            if (!gate.ok) {
+                logManagedWorkspaceReadinessRejection({
+                    executionWorkspaceId: managedWorkspaceIdentity.executionWorkspaceId,
+                    healthUrl: publishHealthUrl,
+                    result: gate,
+                });
+                if (shouldBlockPublicationOnReadiness(gate)) {
+                    throw new Error(`Workspace is not ready to publish (${gate.reason}${gate.detail ? `: ${gate.detail}` : ""})`);
+                }
+            }
+        }
         record.status = "running";
         record.healthStatus = "healthy";
         record.lastUsedAt = new Date().toISOString();
         record.stoppedAt = null;
+        const serviceOutputExcerpt = await readServiceOutputExcerpt();
+        if (serviceOutputExcerpt && input.onLog) {
+            await input.onLog("stdout", `[service:${serviceName}] ${serviceOutputExcerpt}`);
+        }
         await touchLocalServiceRegistryRecord(record.serviceKey, {
             runtimeServiceId: record.id,
             lastSeenAt: record.lastUsedAt,
@@ -4518,13 +5080,70 @@ async function spawnLocalRuntimeService(input) {
         releasePortReservation(reservedPort);
         releasePortReservation(claimedIdentityPort);
         const failureMessage = err instanceof Error ? err.message : String(err);
+        const serviceOutputExcerpt = await readServiceOutputExcerpt();
         const bindCollision = !exposureConfig && (err instanceof RuntimeServicePortBindCollision || Boolean(port
             && (input.allowFixedPortFallback || portType === "auto")
-            && /(?:EADDRINUSE|address already in use)/i.test(`${failureMessage}\n${stderrExcerpt}`)));
+            && /(?:EADDRINUSE|address already in use)/i.test(`${failureMessage}\n${serviceOutputExcerpt}`)));
+        // An exposed guest that exits with EADDRINUSE on its ASSIGNED port lost the
+        // port after allocation. Only the assigned app or HMR port is re-allocatable
+        // from the dedicated broker range, so quarantine and re-allocation apply only
+        // when the failure names one of those ports. An unrelated auxiliary-port
+        // conflict (a different port the guest also bound) leaves the valid pair
+        // intact and surfaces as a terminal error, not a quarantine that burns the
+        // bounded retries.
+        const exposureAssignedPorts = exposureConfig && port
+            ? [port, ...(exposureConfig.includePaperclipViteHmr ? [deriveViteHmrPort(port)] : [])]
+            : [];
+        const collisionText = `${failureMessage}\n${serviceOutputExcerpt}`;
+        const exposureNamedPorts = exposureAssignedPorts.filter((candidate) => eaddrinuseTextNamesPort(collisionText, candidate));
+        // The guest owns its own output, so an assigned-port EADDRINUSE line is a
+        // claim, not proof. A managed guest can print a synthetic EADDRINUSE line for
+        // its assigned port with no host listener behind it. A quarantine on that text
+        // alone would burn the shared exposure-port pool across repeated starts. So the
+        // runtime reads live host listener state and quarantines only after it confirms
+        // that a real host listener owns the port.
+        const exposureTextNamesAssignedPort = Boolean(exposureConfig && port && exposureNamedPorts.length > 0);
+        let exposureCollisionDiagnosis = null;
+        let exposureHostCollision = false;
+        if (exposureTextNamesAssignedPort) {
+            const facts = [];
+            const hostStates = [];
+            for (const collisionPort of exposureAssignedPorts) {
+                // `readLocalServicePortOwner` reads lsof and returns the listener pid, so a
+                // non-null pid also proves a present listener. `readListenerBindFacts` reads
+                // /proc for the same presence signal and the bound addresses.
+                const ownerPid = await readLocalServicePortOwner(collisionPort).catch(() => null);
+                const bind = await readListenerBindFacts(collisionPort).catch(() => null);
+                // Read the owner process group id too. The guest runs as a shell process
+                // group leader, so the real dev server usually binds the port from a
+                // descendant. The classify step matches the shell pid against the owner pgid
+                // to keep a guest descendant from looking like an external owner.
+                const ownerProcessGroupId = ownerPid != null ? await readLocalServiceProcessGroupId(ownerPid).catch(() => null) : null;
+                hostStates.push({
+                    port: collisionPort,
+                    named: exposureNamedPorts.includes(collisionPort),
+                    listenerPresent: Boolean(bind?.present) || ownerPid != null,
+                    ownerPid,
+                    ownerProcessGroupId,
+                });
+                const boundTo = bind?.present ? bind.addresses.join(", ") : "no listener";
+                facts.push(`port ${collisionPort} bound to ${boundTo}, owner pid ${ownerPid ?? "none"}`);
+            }
+            exposureHostCollision = classifyExposureHostCollisions({
+                childPid: child.pid ?? null,
+                ports: hostStates,
+            }).hostCollision;
+            exposureCollisionDiagnosis = facts.join("; ");
+        }
+        // Quarantine the whole assigned pair, not only the named port. The broker
+        // allocates the app and HMR ports as one unit, so a re-allocation must skip
+        // both to land on the next free pair.
+        const exposureCollisionPorts = exposureHostCollision ? exposureAssignedPorts : [];
         if (child.pid) {
             await terminateLocalService({
                 pid: child.pid,
                 processGroupId: child.pid,
+                port,
             });
         }
         await cleanupRecordExposure(record, { preserveFailure: true });
@@ -4538,7 +5157,33 @@ async function spawnLocalRuntimeService(input) {
         }
         if (bindCollision && port)
             throw new RuntimeServicePortBindCollision(port);
-        throw new Error(`Failed to start runtime service "${serviceName}": ${failureMessage}${stderrExcerpt ? ` | stderr: ${stderrExcerpt.trim()}` : ""}`);
+        if (exposureHostCollision && port) {
+            // A verified host listener holds the assigned exposure port. Quarantine the
+            // pair so the bounded re-allocation never re-offers it, then throw a retryable
+            // collision. `startLocalRuntimeService` re-runs allocation, which skips the
+            // quarantined pair and takes the next free pair inside the dedicated range.
+            // This hardens a real host that races an external process for a range port.
+            for (const collisionPort of exposureCollisionPorts) {
+                quarantinedRuntimeExposurePorts.add(collisionPort);
+            }
+            if (input.onLog) {
+                await input.onLog("stderr", `[service:${serviceName}] exposure port ${port} collided during startup (EADDRINUSE); `
+                    + `${exposureCollisionDiagnosis ?? "owner unavailable"}. `
+                    + `Quarantined pair ${exposureCollisionPorts.join("/")} and reallocating.\n`).catch(() => undefined);
+            }
+            throw new RuntimeServicePortBindCollision(port, exposureCollisionDiagnosis, true);
+        }
+        const deploymentBindConflict = /local_trusted requires server\.bind=loopback/i.test(`${failureMessage}\n${serviceOutputExcerpt}`);
+        // The guest reported an assigned-port EADDRINUSE, but no host listener owned
+        // the port. Explain that the runtime did not quarantine the pair, so a future
+        // occurrence needs no diagnostic cycle and the pool stays intact.
+        const unverifiedExposureCollision = exposureTextNamesAssignedPort && !exposureHostCollision;
+        const actionableFailure = deploymentBindConflict
+            ? `${failureMessage} | deployment/bind conflict: local_trusted requires server.bind=loopback; the managed runtime requested an incompatible bind mode`
+            : unverifiedExposureCollision
+                ? `${failureMessage} | exposure port collision not verified: the guest reported EADDRINUSE on assigned port ${exposureNamedPorts.join("/")}, but no host listener owns it (${exposureCollisionDiagnosis ?? "owner unavailable"}); the runtime did not quarantine the pair`
+                : failureMessage;
+        throw new Error(`Failed to start runtime service "${serviceName}": ${actionableFailure}${serviceOutputExcerpt ? ` | output: ${serviceOutputExcerpt.trim()}` : ""}`);
     });
     return { record, readiness: readinessPromise };
 }
@@ -4623,8 +5268,10 @@ async function startLocalRuntimeService(input, options) {
                 return started;
             }
             catch (error) {
-                if (!(error instanceof RuntimeServicePortBindCollision) || !retryBindCollisions)
+                if (!(error instanceof RuntimeServicePortBindCollision)
+                    || !(retryBindCollisions || error.exposureReallocatable)) {
                     throw error;
+                }
                 excludedPorts.add(error.port);
                 started = null;
             }
@@ -4708,19 +5355,14 @@ async function stopRuntimeService(serviceId) {
     if (!record)
         return;
     clearIdleTimer(record);
-    record.status = "stopped";
-    record.healthStatus = "unknown";
-    record.lastUsedAt = new Date().toISOString();
-    record.stoppedAt = new Date().toISOString();
-    runtimeServicesById.delete(serviceId);
-    if (record.reuseKey && runtimeServicesByReuseKey.get(record.reuseKey) === record.id) {
-        runtimeServicesByReuseKey.delete(record.reuseKey);
-    }
+    // Remove any public exposure first, but keep the process registered and the
+    // row non-stopped until verified termination succeeds.
     await cleanupRecordExposure(record);
     if (record.child && record.child.pid) {
         await terminateLocalService({
             pid: record.child.pid,
             processGroupId: record.processGroupId ?? record.child.pid,
+            port: record.port,
         });
     }
     else if (record.providerRef) {
@@ -4729,12 +5371,57 @@ async function stopRuntimeService(serviceId) {
             await terminateLocalService({
                 pid,
                 processGroupId: record.processGroupId,
+                port: record.port,
             });
         }
     }
+    record.status = "stopped";
+    record.healthStatus = "unknown";
+    record.lastUsedAt = new Date().toISOString();
+    record.stoppedAt = new Date().toISOString();
+    runtimeServicesById.delete(serviceId);
+    if (record.reuseKey && runtimeServicesByReuseKey.get(record.reuseKey) === record.id) {
+        runtimeServicesByReuseKey.delete(record.reuseKey);
+    }
     await removeLocalServiceRegistryRecord(record.serviceKey);
     await persistRuntimeServiceRecord(record.db, record);
 }
+async function findHealthyRunningRuntimeService(reuseKey) {
+    const existingId = reuseKey ? runtimeServicesByReuseKey.get(reuseKey) : null;
+    const existing = existingId ? runtimeServicesById.get(existingId) : null;
+    if (!existing || existing.status !== "running")
+        return null;
+    const healthInput = {
+        db: existing.db,
+        serviceName: existing.serviceName,
+        command: existing.command,
+        provider: existing.provider,
+        port: existing.port,
+        cwd: existing.cwd,
+        executionWorkspaceId: existing.executionWorkspaceId,
+        companyId: existing.companyId,
+    };
+    let healthy = await isRuntimeServiceUrlHealthy(existing.url, healthInput);
+    if (!healthy) {
+        // A single timeout or connection reset is not enough evidence to destroy a
+        // shared runtime that active runs may still use. Confirm the failure after
+        // a short bounded delay before entering the destructive replacement path.
+        await delay(250);
+        healthy = await isRuntimeServiceUrlHealthy(existing.url, healthInput);
+    }
+    if (healthy)
+        return existing;
+    if (existing.leaseRunIds.size > 0) {
+        existing.healthStatus = "unhealthy";
+        if (reuseKey && runtimeServicesByReuseKey.get(reuseKey) === existing.id) {
+            runtimeServicesByReuseKey.delete(reuseKey);
+        }
+        await persistRuntimeServiceRecord(existing.db, existing);
+        return null;
+    }
+    await stopRuntimeService(existing.id);
+    return null;
+}
 async function markPersistedRuntimeServicesStoppedForExecutionWorkspace(input) {
     const now = new Date();
     const exposureRows = await input.db
@@ -4893,9 +5580,21 @@ function registerRuntimeService(db, record) {
             runtimeServicesByReuseKey.delete(current.reuseKey);
         }
         void (async () => {
-            await cleanupRecordExposure(current);
-            await removeLocalServiceRegistryRecord(current.serviceKey);
-            await persistRuntimeServiceRecord(db, current);
+            // The child exited on its own. Record the terminal status as best effort.
+            // The persist can fail when a parent row is already gone: a caller can
+            // delete the project or the company while this service still runs, and the
+            // `project_id` foreign key then rejects the write. Catch every error here,
+            // or the detached persist becomes an unhandled rejection and crashes the
+            // host. This path runs off the child `exit` event, so no caller awaits it.
+            try {
+                await cleanupRecordExposure(current);
+                await removeLocalServiceRegistryRecord(current.serviceKey);
+                await persistRuntimeServiceRecord(db, current);
+            }
+            catch (err) {
+                const detail = err instanceof Error ? err.message : String(err);
+                console.warn(`[workspace-runtime] runtime service exit cleanup failed for ${current.id}: ${detail}`);
+            }
         })();
     });
 }
@@ -4977,7 +5676,7 @@ async function isPersistedIsolatedExecutionWorkspace(input) {
         .then((rows) => rows[0] ?? null);
     return row?.mode === "isolated_workspace";
 }
-export async function ensureRuntimeServicesForRun(input) {
+async function ensureRuntimeServicesForRunInvocation(input) {
     const rawServices = selectRuntimeServiceEntries({
         config: input.config,
         respectDesiredStates: true,
@@ -4986,7 +5685,8 @@ export async function ensureRuntimeServicesForRun(input) {
     });
     const acquiredServiceIds = [];
     const refs = [];
-    const runtimeProvisionCommand = resolveRuntimeProvisionCommand(input);
+    const runtimeProvision = resolveRuntimeProvision(input);
+    const runtimeProvisionCommand = runtimeProvision.command;
     const provisionCoordinator = createRuntimeProvisionCoordinator();
     const allowFixedPortFallback = await isPersistedIsolatedExecutionWorkspace({
         db: input.db,
@@ -5014,9 +5714,8 @@ export async function ensureRuntimeServicesForRun(input) {
                 scopeId,
             }).reuseKey;
             if (reuseKey) {
-                const existingId = runtimeServicesByReuseKey.get(reuseKey);
-                const existing = existingId ? runtimeServicesById.get(existingId) : null;
-                if (existing && existing.status === "running") {
+                const existing = await findHealthyRunningRuntimeService(reuseKey);
+                if (existing) {
                     existing.leaseRunIds.add(input.runId);
                     existing.lastUsedAt = new Date().toISOString();
                     existing.stoppedAt = null;
@@ -5042,6 +5741,7 @@ export async function ensureRuntimeServicesForRun(input) {
                 service,
                 onLog: input.onLog,
                 runtimeProvisionCommand,
+                runtimeProvisionKind: runtimeProvision.kind,
                 recorder: input.recorder,
                 provisionCoordinator,
                 allowFixedPortFallback,
@@ -5062,6 +5762,104 @@ export async function ensureRuntimeServicesForRun(input) {
     }
     return refs;
 }
+async function withRuntimeStartMutex(ownerKey, start) {
+    const previous = runtimeControlStartByOwner.get(ownerKey) ?? Promise.resolve();
+    let release;
+    const current = new Promise((resolve) => {
+        release = resolve;
+    });
+    const queued = previous.then(() => current);
+    runtimeControlStartByOwner.set(ownerKey, queued);
+    await previous;
+    try {
+        return await start();
+    }
+    finally {
+        release();
+        if (runtimeControlStartByOwner.get(ownerKey) === queued)
+            runtimeControlStartByOwner.delete(ownerKey);
+    }
+}
+function resolveRuntimeStartMutexPlan(input) {
+    const fallbackOwnerId = input.executionWorkspaceId
+        ?? input.workspace.workspaceId
+        ?? path.resolve(input.workspace.cwd);
+    const replacementReuseKeys = [];
+    const keys = input.services.map((service) => {
+        const { scopeType, scopeId } = resolveServiceScopeId({
+            service,
+            workspace: input.workspace,
+            executionWorkspaceId: input.executionWorkspaceId,
+            issue: input.issue,
+            runId: input.runId,
+            agent: input.agent,
+        });
+        const reuseKey = resolveRuntimeServiceReuseIdentity({
+            service,
+            workspace: input.workspace,
+            agent: input.agent,
+            issue: input.issue,
+            adapterEnv: input.adapterEnv,
+            scopeType,
+            scopeId,
+        }).reuseKey;
+        // Converge all callers that can replace an existing shared runtime on its
+        // reuse identity. For an initial start, retain owner-level concurrency so
+        // the exposure allocator's in-flight pair claims remain authoritative.
+        if (reuseKey
+            && (runtimeServicesByReuseKey.has(reuseKey) || runtimeReplacementClaimsByReuseKey.has(reuseKey))) {
+            runtimeReplacementClaimsByReuseKey.set(reuseKey, (runtimeReplacementClaimsByReuseKey.get(reuseKey) ?? 0) + 1);
+            replacementReuseKeys.push(reuseKey);
+            return `reuse:${reuseKey}`;
+        }
+        return `${input.agent.companyId}:owner:${fallbackOwnerId}`;
+    });
+    return {
+        ownerKeys: [...new Set(keys)].sort(),
+        replacementReuseKeys,
+    };
+}
+function releaseRuntimeReplacementClaims(reuseKeys) {
+    for (const reuseKey of reuseKeys) {
+        const next = (runtimeReplacementClaimsByReuseKey.get(reuseKey) ?? 1) - 1;
+        if (next <= 0)
+            runtimeReplacementClaimsByReuseKey.delete(reuseKey);
+        else
+            runtimeReplacementClaimsByReuseKey.set(reuseKey, next);
+    }
+}
+async function withRuntimeStartMutexes(ownerKeys, start) {
+    const acquire = async (index) => {
+        const ownerKey = ownerKeys[index];
+        if (!ownerKey)
+            return await start();
+        return await withRuntimeStartMutex(ownerKey, () => acquire(index + 1));
+    };
+    return await acquire(0);
+}
+export async function ensureRuntimeServicesForRun(input) {
+    const services = selectRuntimeServiceEntries({
+        config: input.config,
+        respectDesiredStates: true,
+        defaultDesiredState: readDesiredRuntimeState(input.config.desiredState) ?? "running",
+        serviceStates: readConfiguredServiceStates(input.config),
+    });
+    const mutexPlan = resolveRuntimeStartMutexPlan({
+        services,
+        workspace: input.workspace,
+        executionWorkspaceId: input.executionWorkspaceId,
+        issue: input.issue,
+        runId: input.runId,
+        agent: input.agent,
+        adapterEnv: input.adapterEnv,
+    });
+    try {
+        return await withRuntimeStartMutexes(mutexPlan.ownerKeys, () => ensureRuntimeServicesForRunInvocation(input));
+    }
+    finally {
+        releaseRuntimeReplacementClaims(mutexPlan.replacementReuseKeys);
+    }
+}
 async function startRuntimeServicesForWorkspaceControlUnlocked(input, rawServices, invocationId, persistenceDb = input.db, registryDb = input.db, options) {
     const refs = [];
     const pendingReadiness = [];
@@ -5085,9 +5883,8 @@ async function startRuntimeServicesForWorkspaceControlUnlocked(input, rawService
             scopeId,
         }).reuseKey;
         if (reuseKey) {
-            const existingId = runtimeServicesByReuseKey.get(reuseKey);
-            const existing = existingId ? runtimeServicesById.get(existingId) : null;
-            if (existing && existing.status === "running") {
+            const existing = await findHealthyRunningRuntimeService(reuseKey);
+            if (existing) {
                 const prepared = options?.preparedProvisioning;
                 if (prepared?.service === service && prepared.record.id !== existing.id && persistenceDb) {
                     await persistenceDb
@@ -5119,6 +5916,7 @@ async function startRuntimeServicesForWorkspaceControlUnlocked(input, rawService
             service,
             onLog: input.onLog,
             runtimeProvisionCommand: options?.runtimeProvisionCommand,
+            runtimeProvisionKind: options?.runtimeProvisionKind,
             recorder: input.recorder,
             provisionCoordinator: options?.provisionCoordinator,
             preparedProvisioningRecord: options?.preparedProvisioning?.service === service
@@ -5187,7 +5985,7 @@ async function discardFailedDeferredRuntimeStart(db, record) {
     await removeLocalServiceRegistryRecord(record.serviceKey).catch(() => undefined);
     await persistRuntimeServiceRecord(db, record);
 }
-export async function startRuntimeServicesForWorkspaceControl(input) {
+async function startRuntimeServicesForWorkspaceControlInvocation(input) {
     const rawServices = selectRuntimeServiceEntries({
         config: input.config,
         serviceIndex: input.serviceIndex,
@@ -5196,7 +5994,8 @@ export async function startRuntimeServicesForWorkspaceControl(input) {
         serviceStates: readConfiguredServiceStates(input.config),
     });
     const invocationId = input.invocationId ?? randomUUID();
-    const runtimeProvisionCommand = resolveRuntimeProvisionCommand(input);
+    const runtimeProvision = resolveRuntimeProvision(input);
+    const runtimeProvisionCommand = runtimeProvision.command;
     const provisionCoordinator = createRuntimeProvisionCoordinator();
     const hasHttpsExposure = await anyRuntimeServiceUsesHttpsExposure(rawServices);
     if (rawServices.length === 0
@@ -5206,7 +6005,11 @@ export async function startRuntimeServicesForWorkspaceControl(input) {
         // path outside the parent-row transaction avoids a crash window where the
         // broker lease exists but the DB transaction has not committed its handle.
         || hasHttpsExposure) {
-        const batch = await startRuntimeServicesForWorkspaceControlUnlocked(input, rawServices, invocationId, input.db, input.db, { runtimeProvisionCommand, provisionCoordinator });
+        const batch = await startRuntimeServicesForWorkspaceControlUnlocked(input, rawServices, invocationId, input.db, input.db, {
+            runtimeProvisionCommand,
+            runtimeProvisionKind: runtimeProvision.kind,
+            provisionCoordinator,
+        });
         return batch.refs;
     }
     let startBatch = {
@@ -5236,9 +6039,8 @@ export async function startRuntimeServicesForWorkspaceControl(input) {
                     scopeType,
                     scopeId,
                 }).reuseKey;
-                const existingId = reuseKey ? runtimeServicesByReuseKey.get(reuseKey) : null;
-                const existing = existingId ? runtimeServicesById.get(existingId) : null;
-                if (existing?.status === "running")
+                const existing = await findHealthyRunningRuntimeService(reuseKey);
+                if (existing)
                     continue;
                 const record = await prepareRuntimeProvisioning({
                     db: input.db,
@@ -5253,6 +6055,7 @@ export async function startRuntimeServicesForWorkspaceControl(input) {
                     service,
                     onLog: input.onLog,
                     runtimeProvisionCommand,
+                    runtimeProvisionKind: runtimeProvision.kind,
                     recorder: input.recorder,
                     provisionCoordinator,
                     reuseKey,
@@ -5274,6 +6077,7 @@ export async function startRuntimeServicesForWorkspaceControl(input) {
                 deferReadiness: true,
                 allowFixedPortFallback,
                 runtimeProvisionCommand,
+                runtimeProvisionKind: runtimeProvision.kind,
                 provisionCoordinator,
                 preparedProvisioning,
             });
@@ -5370,6 +6174,31 @@ export async function startRuntimeServicesForWorkspaceControl(input) {
         throw error;
     }
 }
+export async function startRuntimeServicesForWorkspaceControl(input) {
+    const services = selectRuntimeServiceEntries({
+        config: input.config,
+        serviceIndex: input.serviceIndex,
+        respectDesiredStates: input.respectDesiredStates,
+        defaultDesiredState: readDesiredRuntimeState(input.config.desiredState) ?? "stopped",
+        serviceStates: readConfiguredServiceStates(input.config),
+    });
+    const invocationId = input.invocationId ?? "workspace_control";
+    const mutexPlan = resolveRuntimeStartMutexPlan({
+        services,
+        workspace: input.workspace,
+        executionWorkspaceId: input.executionWorkspaceId,
+        issue: input.issue,
+        runId: invocationId,
+        agent: input.actor,
+        adapterEnv: input.adapterEnv,
+    });
+    try {
+        return await withRuntimeStartMutexes(mutexPlan.ownerKeys, () => startRuntimeServicesForWorkspaceControlInvocation(input));
+    }
+    finally {
+        releaseRuntimeReplacementClaims(mutexPlan.replacementReuseKeys);
+    }
+}
 export async function releaseRuntimeServicesForRun(runId) {
     const acquired = runtimeServiceLeasesByRun.get(runId) ?? [];
     runtimeServiceLeasesByRun.delete(runId);
@@ -5382,7 +6211,12 @@ export async function releaseRuntimeServicesForRun(runId) {
         const stopType = asString(record.stopPolicy?.type, record.lifecycle === "ephemeral" ? "on_run_finish" : "manual");
         await persistRuntimeServiceRecord(record.db, record);
         if (record.leaseRunIds.size === 0) {
-            if (record.lifecycle === "ephemeral" || stopType === "on_run_finish") {
+            const detachedUnhealthySharedRuntime = record.healthStatus === "unhealthy"
+                && Boolean(record.reuseKey)
+                && runtimeServicesByReuseKey.get(record.reuseKey) !== record.id;
+            if (record.lifecycle === "ephemeral"
+                || stopType === "on_run_finish"
+                || detachedUnhealthySharedRuntime) {
                 await stopRuntimeService(serviceId);
                 continue;
             }
@@ -5571,6 +6405,45 @@ async function buildPersistedRuntimeExposureIntentLookup(db) {
         return readRuntimeExposureIntent(parseObject(entry.expose));
     };
 }
+export async function refreshPersistedRuntimeServiceHealth(input) {
+    const ownershipCondition = input.projectWorkspaceId
+        ? or(eq(workspaceRuntimeServices.executionWorkspaceId, input.executionWorkspaceId), and(eq(workspaceRuntimeServices.projectWorkspaceId, input.projectWorkspaceId), eq(workspaceRuntimeServices.scopeType, "project_workspace")))
+        : eq(workspaceRuntimeServices.executionWorkspaceId, input.executionWorkspaceId);
+    const rows = await input.db
+        .select({
+        id: workspaceRuntimeServices.id,
+        serviceName: workspaceRuntimeServices.serviceName,
+        command: workspaceRuntimeServices.command,
+        provider: workspaceRuntimeServices.provider,
+        port: workspaceRuntimeServices.port,
+        url: workspaceRuntimeServices.url,
+        healthStatus: workspaceRuntimeServices.healthStatus,
+        cwd: workspaceRuntimeServices.cwd,
+        executionWorkspaceId: workspaceRuntimeServices.executionWorkspaceId,
+        companyId: workspaceRuntimeServices.companyId,
+    })
+        .from(workspaceRuntimeServices)
+        .where(and(eq(workspaceRuntimeServices.companyId, input.companyId), eq(workspaceRuntimeServices.provider, "local_process"), eq(workspaceRuntimeServices.status, "running"), ownershipCondition));
+    const results = await Promise.all(rows.map(async (row) => ({
+        row,
+        healthStatus: await isRuntimeServiceUrlHealthy(row.url, { ...row, db: input.db })
+            ? "healthy"
+            : "unhealthy",
+    })));
+    await Promise.all(results.map(async ({ row, healthStatus }) => {
+        const liveRecord = runtimeServicesById.get(row.id);
+        if (liveRecord)
+            liveRecord.healthStatus = healthStatus;
+        if (row.healthStatus === healthStatus)
+            return;
+        await input.db.update(workspaceRuntimeServices).set({ healthStatus, updatedAt: new Date() }).where(and(eq(workspaceRuntimeServices.id, row.id), eq(workspaceRuntimeServices.companyId, input.companyId), eq(workspaceRuntimeServices.status, "running")));
+    }));
+    return {
+        checked: results.length,
+        healthy: results.filter((result) => result.healthStatus === "healthy").length,
+        unhealthy: results.filter((result) => result.healthStatus === "unhealthy").length,
+    };
+}
 export async function reconcilePersistedRuntimeServicesOnStartup(db) {
     const rows = await db
         .select()
@@ -5724,9 +6597,28 @@ export async function reconcilePersistedRuntimeServicesOnStartup(db) {
         }
         if (adoptedRecord) {
             const adoptedUrl = adoptedRecord.url ?? row.backendUrl ?? row.url ?? null;
+            const adoptedHealthInput = {
+                db,
+                serviceName: row.serviceName,
+                command: row.command,
+                provider: "local_process",
+                port: adoptedRecord.port ?? row.port,
+                cwd: row.cwd,
+                executionWorkspaceId: row.executionWorkspaceId ?? null,
+                companyId: row.companyId,
+            };
+            // A surviving service can be slow to answer one probe when the host is
+            // busy at startup. One timeout is not enough evidence to terminate it.
+            // Confirm an unhealthy verdict with a second probe after a short bounded
+            // delay, the same way the reuse path protects a shared runtime.
+            let adoptedHealthy = await isRuntimeServiceUrlHealthy(adoptedUrl, adoptedHealthInput);
+            if (!adoptedHealthy) {
+                await delay(250);
+                adoptedHealthy = await isRuntimeServiceUrlHealthy(adoptedUrl, adoptedHealthInput);
+            }
             if (backfillDecision.action === "reprovision"
                 || !exposureHealthMatches
-                || !(await isRuntimeServiceUrlHealthy(adoptedUrl, { serviceName: row.serviceName, command: row.command }))) {
+                || !adoptedHealthy) {
                 if (backfillDecision.action === "reprovision")
                     backfilled += 1;
                 await terminateLocalService(adoptedRecord);
@@ -5885,6 +6777,7 @@ export async function restartDesiredRuntimeServicesOnStartup(db) {
                     worktreePath: null,
                     warnings: [],
                     created: false,
+                    branchCreatedByRuntime: false,
                 },
                 config: {
                     workspaceRuntime: runtimeConfig.workspaceRuntime,
@@ -5937,6 +6830,7 @@ export async function restartDesiredRuntimeServicesOnStartup(db) {
                     worktreePath: row.strategyType === "git_worktree" ? row.cwd : null,
                     warnings: [],
                     created: false,
+                    branchCreatedByRuntime: isRuntimeOwnedGitBranch(row.metadata),
                 },
                 executionWorkspaceId: row.id,
                 config: {