@loucompanion/forge-bridge 0.1.3-dev.9bc5014a2270 → 0.1.3-dev.a58d7cd1092f

package/dist/worktree/index.d.ts

@@ -1,4 +1,5 @@
 export { GitWorktreeService } from "./worktree.service.js";
+export { managedRepoRoot, resolveManagedWorktreeRoot, resolveManagedWorktreeRootForRepo, } from "./worktree-paths.js";
 export { detectWarmPaths, warmWorktreeDependencies, createDirectoryLink, lockfilesDiffer, requiresInstallFallback } from "./dependency-warmer.js";
-export type { WarmDependenciesResult, WarmPathEntry, InstallFallbackResult } from "./dependency-warmer.js";
+export type { WarmDependenciesResult, WarmPathEntry, InstallFallbackResult, DependencyPreparationPolicy, DependencyPreparationReceiptResult, } from "./dependency-warmer.js";
 export type { WorktreeService } from "./worktree.base.js";

package/dist/worktree/index.js

@@ -1,2 +1,3 @@
 export { GitWorktreeService } from "./worktree.service.js";
+export { managedRepoRoot, resolveManagedWorktreeRoot, resolveManagedWorktreeRootForRepo, } from "./worktree-paths.js";
 export { detectWarmPaths, warmWorktreeDependencies, createDirectoryLink, lockfilesDiffer, requiresInstallFallback } from "./dependency-warmer.js";

package/dist/worktree/prior-phase-artifact-hydrator.d.ts

@@ -0,0 +1,2 @@
+import type { DispatchPriorPhaseArtifact } from "../session/session.types.js";
+export declare function hydratePriorPhaseArtifacts(worktreePath: string, artifacts?: readonly DispatchPriorPhaseArtifact[]): Promise<number>;

package/dist/worktree/prior-phase-artifact-hydrator.js

@@ -0,0 +1,136 @@
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { isSubPath } from "../shared/path/path.js";
+const MAX_ARTIFACT_COUNT = 128;
+const MAX_CONTENT_BYTES = 2 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 12 * 1024 * 1024;
+const phaseFiles = {
+    implementation: {
+        verdict: "implementation.completeness.json",
+        report: "implementation.report.md"
+    },
+    self_review: {
+        verdict: "self-review.report.json",
+        report: "self-review.summary.md"
+    },
+    validation: {
+        verdict: "validation.verdict.json",
+        report: "validation.report.md"
+    }
+};
+export async function hydratePriorPhaseArtifacts(worktreePath, artifacts = []) {
+    if (artifacts.length === 0)
+        return 0;
+    if (artifacts.length > MAX_ARTIFACT_COUNT) {
+        throw new Error(`Prior phase artifact handoff exceeds ${MAX_ARTIFACT_COUNT} artifacts.`);
+    }
+    const targets = new Set();
+    let totalBytes = 0;
+    for (const artifact of artifacts) {
+        const workItemId = safeArtifactSegment(artifact.workItemId, "work item id");
+        const files = phaseFiles[artifact.phase];
+        if (!files) {
+            throw new Error(`Unsupported prior phase artifact phase '${artifact.phase}'.`);
+        }
+        const verdictBytes = Buffer.byteLength(artifact.verdictJson, "utf8");
+        const reportBytes = Buffer.byteLength(artifact.report, "utf8");
+        if (verdictBytes > MAX_CONTENT_BYTES || reportBytes > MAX_CONTENT_BYTES) {
+            throw new Error(`Prior phase artifact '${artifact.artifactId}' exceeds the per-file hydration limit.`);
+        }
+        totalBytes += verdictBytes + reportBytes;
+        if (totalBytes > MAX_TOTAL_BYTES) {
+            throw new Error("Prior phase artifact handoff exceeds the total hydration limit.");
+        }
+        verifyContentHash(artifact.verdictJson, artifact.verdictContentHash, artifact.artifactId, "verdict");
+        verifyContentHash(artifact.report, artifact.reportContentHash, artifact.artifactId, "report");
+        validateVerdict(artifact);
+        const artifactRoot = path.resolve(worktreePath, ".forge", "work-items", workItemId, "artifacts");
+        if (!isSubPath(worktreePath, artifactRoot)) {
+            throw new Error("Prior phase artifact target must stay under the worktree.");
+        }
+        await ensureNoSymlinkPathSegments(worktreePath, artifactRoot);
+        await fs.mkdir(artifactRoot, { recursive: true });
+        await ensureNoSymlinkPathSegments(worktreePath, artifactRoot);
+        const verdictPath = path.join(artifactRoot, files.verdict);
+        const reportPath = path.join(artifactRoot, files.report);
+        const targetKey = verdictPath.toLowerCase();
+        if (targets.has(targetKey)) {
+            throw new Error(`Duplicate prior phase artifact target for work item '${workItemId}' phase '${artifact.phase}'.`);
+        }
+        targets.add(targetKey);
+        await writeAtomic(verdictPath, artifact.verdictJson);
+        await writeAtomic(reportPath, artifact.report);
+    }
+    return artifacts.length;
+}
+function validateVerdict(artifact) {
+    let parsed;
+    try {
+        parsed = JSON.parse(artifact.verdictJson);
+    }
+    catch {
+        throw new Error(`Prior phase artifact '${artifact.artifactId}' verdict is not valid JSON.`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`Prior phase artifact '${artifact.artifactId}' verdict must be a JSON object.`);
+    }
+    const recordedPhase = parsed["phase"];
+    const normalizedPhase = typeof recordedPhase === "string"
+        ? recordedPhase.trim().toLowerCase().replace(/-/g, "_")
+        : "";
+    if (normalizedPhase !== artifact.phase) {
+        throw new Error(`Prior phase artifact '${artifact.artifactId}' phase does not match its verdict.`);
+    }
+}
+function verifyContentHash(content, expected, artifactId, label) {
+    const normalizedExpected = expected.trim().toLowerCase().replace(/^sha256:/, "");
+    if (!/^[0-9a-f]{64}$/.test(normalizedExpected)) {
+        throw new Error(`Prior phase artifact '${artifactId}' ${label} hash is invalid.`);
+    }
+    const actual = createHash("sha256").update(content, "utf8").digest("hex");
+    if (actual !== normalizedExpected) {
+        throw new Error(`Prior phase artifact '${artifactId}' ${label} content_hash mismatch.`);
+    }
+}
+function safeArtifactSegment(value, label) {
+    const trimmed = value.trim();
+    if (!/^[a-zA-Z0-9_-]{1,128}$/.test(trimmed)) {
+        throw new Error(`Prior phase artifact ${label} is not a safe path segment.`);
+    }
+    return trimmed;
+}
+async function writeAtomic(targetPath, content) {
+    const temporaryPath = `${targetPath}.tmp-${randomUUID()}`;
+    try {
+        await fs.writeFile(temporaryPath, content, { encoding: "utf8", mode: 0o600, flag: "wx" });
+        await fs.rename(temporaryPath, targetPath);
+    }
+    finally {
+        await fs.rm(temporaryPath, { force: true }).catch(() => undefined);
+    }
+}
+async function ensureNoSymlinkPathSegments(root, targetPath) {
+    const resolvedRoot = path.resolve(root);
+    const resolvedTarget = path.resolve(targetPath);
+    const relative = path.relative(resolvedRoot, resolvedTarget);
+    if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new Error("Prior phase artifact path must stay under the worktree.");
+    }
+    let current = resolvedRoot;
+    for (const segment of relative.split(path.sep)) {
+        if (!segment)
+            continue;
+        current = path.join(current, segment);
+        const stat = await fs.lstat(current).catch((error) => {
+            if (error.code === "ENOENT")
+                return null;
+            throw error;
+        });
+        if (!stat)
+            return;
+        if (stat.isSymbolicLink()) {
+            throw new Error("Prior phase artifact path must not traverse symlinked path segments.");
+        }
+    }
+}

package/dist/worktree/worktree-paths.d.ts

@@ -0,0 +1,4 @@
+export declare function managedRepoRoot(allowedRoot: string): string;
+export declare function resolveManagedWorktreeRoot(allowedRoot: string, repoPath: string): string;
+export declare function resolveManagedWorktreeRootForRepo(repoPath: string, allowedRoot?: string): string;
+export declare function defaultWorktreeCoordinatorStateRoot(): string;

package/dist/worktree/worktree-paths.js

@@ -0,0 +1,30 @@
+import os from "node:os";
+import path from "node:path";
+import { isSubPath } from "../shared/path/path.js";
+export function managedRepoRoot(allowedRoot) {
+    return path.join(path.resolve(allowedRoot), ".forge-worktrees", "_repos");
+}
+export function resolveManagedWorktreeRoot(allowedRoot, repoPath) {
+    const resolvedAllowedRoot = path.resolve(allowedRoot);
+    const resolvedRepoPath = path.resolve(repoPath);
+    const baseName = path.basename(resolvedRepoPath);
+    return isSubPath(managedRepoRoot(resolvedAllowedRoot), resolvedRepoPath)
+        ? path.join(resolvedAllowedRoot, ".forge-worktrees", baseName)
+        : path.join(path.dirname(resolvedRepoPath), ".forge-worktrees", baseName);
+}
+export function resolveManagedWorktreeRootForRepo(repoPath, allowedRoot) {
+    const resolvedRepoPath = path.resolve(repoPath);
+    if (allowedRoot && isSubPath(path.resolve(allowedRoot), resolvedRepoPath)) {
+        return resolveManagedWorktreeRoot(allowedRoot, resolvedRepoPath);
+    }
+    const repoParent = path.dirname(resolvedRepoPath);
+    const managedRoot = path.dirname(repoParent);
+    if (path.basename(repoParent) === "_repos" && path.basename(managedRoot) === ".forge-worktrees") {
+        return path.join(managedRoot, path.basename(resolvedRepoPath));
+    }
+    return path.join(repoParent, ".forge-worktrees", path.basename(resolvedRepoPath));
+}
+export function defaultWorktreeCoordinatorStateRoot() {
+    return process.env.FORGE_SANDBOX_STATE_ROOT
+        ?? path.join(os.homedir(), ".forge", "bridge", "sandboxes");
+}

package/dist/worktree/worktree.base.d.ts

@@ -3,3 +3,6 @@ export interface WorktreeService {
     prepare(request: WorktreePrepareRequest): Promise<WorktreeHandle>;
     release(handle: WorktreeHandle): Promise<void>;
 }
+export interface WorktreeLifecycleCoordinator {
+    withLock<T>(repoPath: string, action: () => Promise<T>, signal?: AbortSignal): Promise<T>;
+}

package/dist/worktree/worktree.service.d.ts

@@ -1,12 +1,17 @@
 import { GitClient } from "../shared/git/git.js";
-import type { WorktreeService } from "./worktree.base.js";
+import type { WorktreeLifecycleCoordinator, WorktreeService } from "./worktree.base.js";
 import type { WorktreeHandle, WorktreePrepareRequest } from "./worktree.types.js";
 export declare class GitWorktreeService implements WorktreeService {
     private readonly git;
-    constructor(git?: GitClient);
+    private readonly coordinator;
+    constructor(git?: GitClient, coordinator?: WorktreeLifecycleCoordinator);
     prepare(request: WorktreePrepareRequest): Promise<WorktreeHandle>;
+    private trackedForgePaths;
+    private repoCreationCoordinationPath;
     release(handle: WorktreeHandle): Promise<void>;
+    private restoreOrphanedWorktree;
     private resolveRepoPath;
+    private managedRepoPath;
     private findExistingRepoPath;
     private resolveMatchingRepo;
     private resolveBaseStartPoint;
@@ -15,4 +20,10 @@ export declare class GitWorktreeService implements WorktreeService {
     private currentBranch;
     private ensureGitIdentity;
 }
+type WorktreeRename = (source: string, destination: string) => Promise<void>;
+type WorktreeRenameDelay = (milliseconds: number) => Promise<void>;
+export declare function renameWorktreeForRelease(source: string, destination: string, rename?: WorktreeRename, wait?: WorktreeRenameDelay, maxAttempts?: number): Promise<void>;
+export declare function requiresMutableEnvironmentPreparation(request: Pick<WorktreePrepareRequest, "applicationRuntimeRequired">): boolean;
+export declare function clearRunArtifactRoots(worktreePath: string, request: WorktreePrepareRequest): Promise<void>;
 export declare function normalizeBranchName(value: string | null | undefined, fallback: string): string;
+export {};

package/dist/worktree/worktree.service.js

@@ -1,64 +1,90 @@
+import { randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { RepositoryCoordinatorLock } from "../sandbox/repository-lock.js";
 import { GitClient } from "../shared/git/git.js";
 import { ensureDirectory, isSubPath, resolveExistingDirectoryPath, safeSegment } from "../shared/path/path.js";
 import { filterArtifactsForLane, injectWorktreeArtifacts } from "./artifact-injector.js";
+import { hydratePriorPhaseArtifacts } from "./prior-phase-artifact-hydrator.js";
 import { warmWorktreeDependencies } from "./dependency-warmer.js";
+import { defaultWorktreeCoordinatorStateRoot, managedRepoRoot, resolveManagedWorktreeRoot, } from "./worktree-paths.js";
 export class GitWorktreeService {
     git;
-    constructor(git = new GitClient()) {
+    coordinator;
+    constructor(git = new GitClient(), coordinator = new RepositoryCoordinatorLock(defaultWorktreeCoordinatorStateRoot())) {
         this.git = git;
+        this.coordinator = coordinator;
     }
     async prepare(request) {
         const allowedRoot = await ensureDirectory(request.allowedRepoRoot);
         const baseBranch = normalizeBranchName(request.baseBranch, "develop");
-        const repoPath = await this.resolveRepoPath(request.repo, allowedRoot, baseBranch);
-        await this.ensureGitIdentity(repoPath);
-        const baseStartPoint = await this.resolveBaseStartPoint(repoPath, baseBranch);
         const shortId = request.workItem.id.replace(/-/g, "").slice(0, 12);
         const kind = safeSegment(request.workItem.kind, "work-item");
         const fallbackWorktreeKey = `${kind}/${shortId}`;
         const worktreeKey = request.worktreeKey?.trim() || fallbackWorktreeKey;
         const worktreeSegments = worktreeKeySegments(worktreeKey, kind, shortId);
         const branchName = normalizeBranchName(worktreeSegments.join("/"), "work-item/unknown");
-        const worktreeRoot = resolveWorktreeRoot(allowedRoot, repoPath);
-        const worktreePath = path.join(worktreeRoot, ...worktreeSegments);
-        const resolvedWorktreeParent = await ensureDirectory(path.dirname(worktreePath));
-        if (!isSubPath(allowedRoot, resolvedWorktreeParent)) {
-            throw new Error(`Worktree path must stay under ${allowedRoot}.`);
-        }
-        const exists = await directoryExists(worktreePath);
-        let resolvedWorktreePath;
-        if (!exists) {
-            await this.git.run(repoPath, ["worktree", "add", "-B", branchName, worktreePath, baseStartPoint]);
-            resolvedWorktreePath = await resolveExistingDirectoryPath(worktreePath);
-        }
-        else {
-            resolvedWorktreePath = await resolveExistingDirectoryPath(worktreePath);
-            if (!isSubPath(allowedRoot, resolvedWorktreePath)) {
+        const creationCoordinationPath = this.repoCreationCoordinationPath(request.repo, allowedRoot);
+        const repoPath = await this.coordinator.withLock(creationCoordinationPath, async () => {
+            return await this.resolveRepoPath(request.repo, allowedRoot, baseBranch);
+        });
+        const resolvedWorktreePath = await this.coordinator.withLock(repoPath, async () => {
+            await this.ensureGitIdentity(repoPath);
+            const baseStartPoint = await this.resolveBaseStartPoint(repoPath, baseBranch);
+            const worktreeRoot = resolveManagedWorktreeRoot(allowedRoot, repoPath);
+            const worktreePath = path.join(worktreeRoot, ...worktreeSegments);
+            const resolvedWorktreeParent = await ensureDirectory(path.dirname(worktreePath));
+            if (!isSubPath(allowedRoot, resolvedWorktreeParent)) {
+                throw new Error(`Worktree path must stay under ${allowedRoot}.`);
+            }
+            if (!(await directoryExists(worktreePath))) {
+                // A prior runner can disappear after Git registers its worktree but before
+                // normal cleanup completes. Release that missing-directory registration
+                // immediately so retrying the same lease remains idempotent.
+                await this.git.run(repoPath, ["worktree", "prune", "--expire", "now"]);
+                await this.git.run(repoPath, ["worktree", "add", "-B", branchName, worktreePath, baseStartPoint]);
+                return await resolveExistingDirectoryPath(worktreePath);
+            }
+            const existingWorktreePath = await resolveExistingDirectoryPath(worktreePath);
+            if (!isSubPath(allowedRoot, existingWorktreePath)) {
                 throw new Error(`Worktree path must stay under ${allowedRoot}.`);
             }
-            const currentBranch = await this.currentBranch(resolvedWorktreePath);
+            if (!(await gitMetadataExists(existingWorktreePath, allowedRoot))) {
+                await this.restoreOrphanedWorktree({
+                    repoPath,
+                    worktreePath: existingWorktreePath,
+                    branchName,
+                    baseStartPoint,
+                    allowedRoot,
+                });
+            }
+            const currentBranch = await this.currentBranch(existingWorktreePath);
             if (currentBranch !== branchName) {
-                throw new Error(`Existing worktree ${resolvedWorktreePath} is on branch '${currentBranch}', expected '${branchName}'.`);
+                throw new Error(`Existing worktree ${existingWorktreePath} is on branch '${currentBranch}', expected '${branchName}'.`);
             }
-            if (shouldResetExistingWorktree(request)) {
-                await this.resetWorktreeToBase(resolvedWorktreePath, baseStartPoint);
+            if (!request.preserveExistingState && shouldResetExistingWorktree(request)) {
+                await this.resetWorktreeToBase(existingWorktreePath, baseStartPoint);
             }
-        }
+            return existingWorktreePath;
+        });
         await this.ensureGitIdentity(resolvedWorktreePath);
-        await clearRunArtifactRoots(resolvedWorktreePath, request);
+        if (!request.preserveExistingState) {
+            await clearRunArtifactRoots(resolvedWorktreePath, request);
+        }
+        const hydratedPriorPhaseArtifactCount = await hydratePriorPhaseArtifacts(resolvedWorktreePath, request.priorPhaseArtifacts);
         const qaReworkPacketPath = await materializeQaReworkPacket(resolvedWorktreePath, request);
         const artifacts = filterArtifactsForLane(request.artifacts, request.lane, request.phase);
         if (artifacts.length > 0) {
-            await injectWorktreeArtifacts(resolvedWorktreePath, artifacts);
+            await injectWorktreeArtifacts(resolvedWorktreePath, artifacts, await this.trackedForgePaths(resolvedWorktreePath));
         }
-        const dependencyWarm = await warmWorktreeDependencies({
-            baseCheckoutPath: repoPath,
-            worktreePath: resolvedWorktreePath,
-            allowedRoot,
-            warmPathOverrides: request.warmPathOverrides
-        });
+        const dependencyWarm = requiresMutableEnvironmentPreparation(request)
+            ? await warmWorktreeDependencies({
+                baseCheckoutPath: repoPath,
+                worktreePath: resolvedWorktreePath,
+                allowedRoot,
+                warmPathOverrides: request.warmPathOverrides
+            })
+            : undefined;
         return {
             repoPath,
             worktreePath: resolvedWorktreePath,
@@ -66,19 +92,75 @@ export class GitWorktreeService {
             baseBranch,
             cleanupWorktrees: request.cleanupWorktrees,
             dependencyWarm,
-            qaReworkPacketPath
+            qaReworkPacketPath,
+            hydratedPriorPhaseArtifactCount
         };
     }
+    async trackedForgePaths(worktreePath) {
+        const output = await this.git.run(worktreePath, ["ls-files", "-z", "--", ".forge"]);
+        return new Set(output.split("\0").filter(Boolean).map(value => value.replaceAll("\\", "/")));
+    }
+    repoCreationCoordinationPath(repo, allowedRoot) {
+        if (repo.serverLocalPath && repo.serverLocalPath.trim().length > 0) {
+            return path.resolve(repo.serverLocalPath);
+        }
+        return this.managedRepoPath(repo, allowedRoot);
+    }
     async release(handle) {
-        if (!handle.cleanupWorktrees || !(await directoryExists(handle.worktreePath))) {
+        if (!handle.cleanupWorktrees) {
             return;
         }
+        await this.coordinator.withLock(handle.repoPath, async () => {
+            if (await directoryExists(handle.worktreePath)) {
+                // On Windows, `git worktree remove` can delete the `.git` link and then
+                // fail on a locked build output. That leaves a full source tree which is
+                // no longer a Git worktree and makes every retry fail during prepare.
+                // Move the tree out of its stable lease path first. If the rename fails,
+                // leave the valid worktree untouched rather than partially unregistering it.
+                const releasePath = `${handle.worktreePath}.forge-release-${randomUUID()}`;
+                await renameWorktreeForRelease(handle.worktreePath, releasePath);
+                await this.git.run(handle.repoPath, ["worktree", "prune", "--expire", "now"]);
+                await fs.rm(releasePath, {
+                    recursive: true,
+                    force: true,
+                    maxRetries: 10,
+                    retryDelay: 100,
+                }).catch(() => undefined);
+            }
+            // The process can disappear after Git registers a worktree but before the
+            // directory is fully materialized (or after an external cleanup removes it).
+            // Always prune so those missing-directory registrations do not accumulate.
+            await this.git.run(handle.repoPath, ["worktree", "prune", "--expire", "now"]).catch(() => undefined);
+        });
+    }
+    async restoreOrphanedWorktree(input) {
+        const orphanStat = await fs.lstat(input.worktreePath);
+        if (orphanStat.isSymbolicLink() || !orphanStat.isDirectory()) {
+            throw new Error(`Refusing to recover redirected or non-directory worktree ${input.worktreePath}.`);
+        }
+        const quarantinePath = `${input.worktreePath}.forge-orphan-${randomUUID()}`;
+        if (!isSubPath(input.allowedRoot, quarantinePath)) {
+            throw new Error(`Worktree recovery path must stay under ${input.allowedRoot}.`);
+        }
+        await fs.rename(input.worktreePath, quarantinePath);
         try {
-            await this.git.run(handle.repoPath, ["worktree", "remove", "--force", handle.worktreePath]);
-            await this.git.run(handle.repoPath, ["worktree", "prune"]);
+            await this.git.run(input.repoPath, ["worktree", "prune", "--expire", "now"]);
+            await this.git.run(input.repoPath, [
+                "worktree",
+                "add",
+                "-B",
+                input.branchName,
+                input.worktreePath,
+                input.baseStartPoint,
+            ]);
+            await overlayOrphanedWorktree(input.worktreePath, quarantinePath);
+            await fs.rm(quarantinePath, { recursive: true, force: true });
         }
-        catch {
-            await fs.rm(handle.worktreePath, { recursive: true, force: true });
+        catch (error) {
+            await this.git.run(input.repoPath, ["worktree", "remove", "--force", input.worktreePath]).catch(() => undefined);
+            await fs.rm(input.worktreePath, { recursive: true, force: true }).catch(() => undefined);
+            await fs.rename(quarantinePath, input.worktreePath).catch(() => undefined);
+            throw new Error(`Failed to recover orphaned worktree ${input.worktreePath}.`, { cause: error });
         }
     }
     async resolveRepoPath(repo, allowedRoot, baseBranch) {
@@ -96,7 +178,7 @@ export class GitWorktreeService {
         if (discovered) {
             return discovered;
         }
-        const repoPath = path.join(managedRepoRoot(allowedRoot), `${safeSegment(repo.name, "repo")}-${repo.id.replace(/-/g, "")}`);
+        const repoPath = this.managedRepoPath(repo, allowedRoot);
         if (!(await gitMetadataExists(repoPath, allowedRoot))) {
             const repoPathExists = await pathExists(repoPath);
             if (repoPathExists) {
@@ -127,6 +209,9 @@ export class GitWorktreeService {
         }
         return resolved;
     }
+    managedRepoPath(repo, allowedRoot) {
+        return path.join(managedRepoRoot(allowedRoot), `${safeSegment(repo.name, "repo")}-${repo.id.replace(/-/g, "")}`);
+    }
     async findExistingRepoPath(repo, allowedRoot) {
         const expectedRemote = normalizeRemote(repo.remoteUrl);
         const rawName = repo.name.trim();
@@ -168,6 +253,13 @@ export class GitWorktreeService {
         return isSubPath(allowedRoot, resolved) ? resolved : null;
     }
     async resolveBaseStartPoint(repoPath, baseBranch) {
+        if (baseBranch === "HEAD") {
+            const head = (await this.git.run(repoPath, ["rev-parse", "--verify", "HEAD^{commit}"])).trim();
+            if (!/^[0-9a-f]{40,64}$/iu.test(head)) {
+                throw new Error("The repository checkout does not have a valid committed HEAD revision.");
+            }
+            return head;
+        }
         const localRef = `refs/heads/${baseBranch}`;
         const remoteRef = `refs/remotes/origin/${baseBranch}`;
         const origin = await this.git.run(repoPath, ["remote", "get-url", "origin"]).catch(() => "");
@@ -199,14 +291,31 @@ export class GitWorktreeService {
         await this.git.run(repoPath, ["config", "user.name", "Forge Bridge"]);
     }
 }
-function managedRepoRoot(allowedRoot) {
-    return path.join(allowedRoot, ".forge-worktrees", "_repos");
+export async function renameWorktreeForRelease(source, destination, rename = fs.rename, wait = milliseconds => new Promise(resolve => setTimeout(resolve, milliseconds)), maxAttempts = 8) {
+    const attempts = Number.isFinite(maxAttempts) && maxAttempts > 0
+        ? Math.max(1, Math.floor(maxAttempts))
+        : 1;
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+        try {
+            await rename(source, destination);
+            return;
+        }
+        catch (error) {
+            if (!isTransientWorktreeRenameError(error) || attempt === attempts)
+                throw error;
+            await wait(Math.min(1_000, 100 * (2 ** (attempt - 1))));
+        }
+    }
 }
-function resolveWorktreeRoot(allowedRoot, repoPath) {
-    const baseName = path.basename(repoPath);
-    return isSubPath(managedRepoRoot(allowedRoot), repoPath)
-        ? path.join(allowedRoot, ".forge-worktrees", baseName)
-        : path.join(path.dirname(repoPath), ".forge-worktrees", baseName);
+function isTransientWorktreeRenameError(error) {
+    if (!error || typeof error !== "object" || !("code" in error))
+        return false;
+    const code = String(error.code ?? "").toUpperCase();
+    return code === "EPERM" || code === "EACCES" || code === "EBUSY" || code === "ENOTEMPTY";
+}
+export function requiresMutableEnvironmentPreparation(request) {
+    // Missing runtime intent is treated conservatively for older dispatch packets.
+    return request.applicationRuntimeRequired !== false;
 }
 function isCloneableRemote(remoteUrl) {
     const trimmed = remoteUrl?.trim() ?? "";
@@ -215,9 +324,12 @@ function isCloneableRemote(remoteUrl) {
     }
     return trimmed.startsWith("git@") || trimmed.includes("://") || path.isAbsolute(trimmed);
 }
-async function clearRunArtifactRoots(worktreePath, request) {
+export async function clearRunArtifactRoots(worktreePath, request) {
     const roots = new Set();
     roots.add(workItemArtifactRoot(worktreePath, request.workItem.id));
+    for (const artifact of request.priorPhaseArtifacts ?? []) {
+        roots.add(workItemArtifactRoot(worktreePath, artifact.workItemId));
+    }
     const ownerType = normalizeOwnerType(request.ownerType);
     const ownerId = request.ownerId?.trim();
     if (ownerType && ownerId) {
@@ -289,6 +401,85 @@ function shouldResetExistingWorktree(request) {
     }
     return true;
 }
+async function overlayOrphanedWorktree(worktreePath, orphanPath) {
+    // A failed Windows cleanup can remove only part of a worktree before its
+    // `.git` link disappears. Start from Git's clean checkout so missing tracked
+    // files are restored, then overlay every surviving agent file. Moving entries
+    // on the same volume preserves pnpm junctions without requiring symlink
+    // privileges, unlike fs.cp.
+    const backupRoot = `${worktreePath}.forge-base-${randomUUID()}`;
+    const moves = [];
+    try {
+        await fs.mkdir(backupRoot, { recursive: true });
+        const orphanEntries = await fs.readdir(orphanPath, { withFileTypes: true });
+        for (const entry of orphanEntries) {
+            if (entry.name === ".git") {
+                continue;
+            }
+            await overlayEntry({
+                sourcePath: path.join(orphanPath, entry.name),
+                destinationPath: path.join(worktreePath, entry.name),
+                backupPath: path.join(backupRoot, entry.name),
+                moves,
+            });
+        }
+        await fs.rm(backupRoot, { recursive: true, force: true });
+    }
+    catch (error) {
+        for (const move of moves.reverse()) {
+            await fs.mkdir(path.dirname(move.sourcePath), { recursive: true }).catch(() => undefined);
+            await fs.rename(move.destinationPath, move.sourcePath).catch(() => undefined);
+            if (move.backupPath) {
+                await fs.mkdir(path.dirname(move.destinationPath), { recursive: true }).catch(() => undefined);
+                await fs.rename(move.backupPath, move.destinationPath).catch(() => undefined);
+            }
+        }
+        await fs.rm(backupRoot, { recursive: true, force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+async function overlayEntry(input) {
+    const sourceStat = await fs.lstat(input.sourcePath);
+    const destinationStat = await fs.lstat(input.destinationPath).catch(() => null);
+    if (sourceStat.isDirectory() &&
+        !sourceStat.isSymbolicLink() &&
+        destinationStat?.isDirectory() &&
+        !destinationStat.isSymbolicLink()) {
+        const entries = await fs.readdir(input.sourcePath, { withFileTypes: true });
+        for (const entry of entries) {
+            await overlayEntry({
+                sourcePath: path.join(input.sourcePath, entry.name),
+                destinationPath: path.join(input.destinationPath, entry.name),
+                backupPath: path.join(input.backupPath, entry.name),
+                moves: input.moves,
+            });
+        }
+        return;
+    }
+    let preservedBasePath;
+    if (destinationStat) {
+        await fs.mkdir(path.dirname(input.backupPath), { recursive: true });
+        await fs.rename(input.destinationPath, input.backupPath);
+        preservedBasePath = input.backupPath;
+    }
+    else {
+        await fs.mkdir(path.dirname(input.destinationPath), { recursive: true });
+    }
+    try {
+        await fs.rename(input.sourcePath, input.destinationPath);
+    }
+    catch (error) {
+        if (preservedBasePath) {
+            await fs.rename(preservedBasePath, input.destinationPath).catch(() => undefined);
+        }
+        throw error;
+    }
+    input.moves.push({
+        sourcePath: input.sourcePath,
+        destinationPath: input.destinationPath,
+        backupPath: preservedBasePath,
+    });
+}
 function qaReworkPacketFileName(packetPath) {
     const normalized = packetPath.trim().replace(/\\/g, "/");
     const fileName = normalized.split("/").filter(Boolean).at(-1) ?? "";

package/dist/worktree/worktree.types.d.ts

@@ -1,4 +1,4 @@
-import type { DispatchQaReworkContext, DispatchRepo, DispatchWorkItem, DispatchResolvedArtifact } from "../session/session.types.js";
+import type { DispatchQaReworkContext, DispatchPriorPhaseArtifact, DispatchRepo, DispatchWorkItem, DispatchResolvedArtifact } from "../session/session.types.js";
 import type { WarmDependenciesResult } from "./dependency-warmer.js";
 export interface WorktreePrepareRequest {
     readonly repo: DispatchRepo;
@@ -12,8 +12,11 @@ export interface WorktreePrepareRequest {
     readonly allowedRepoRoot: string;
     readonly cleanupWorktrees: boolean;
     readonly artifacts: readonly DispatchResolvedArtifact[];
+    readonly priorPhaseArtifacts?: readonly DispatchPriorPhaseArtifact[];
     readonly qaRework?: DispatchQaReworkContext | null;
     readonly warmPathOverrides?: readonly string[];
+    readonly applicationRuntimeRequired?: boolean;
+    readonly preserveExistingState?: boolean;
 }
 export interface WorktreeHandle {
     readonly repoPath: string;
@@ -23,4 +26,5 @@ export interface WorktreeHandle {
     readonly cleanupWorktrees: boolean;
     readonly dependencyWarm?: WarmDependenciesResult;
     readonly qaReworkPacketPath?: string;
+    readonly hydratedPriorPhaseArtifactCount?: number;
 }