@loucompanion/forge-bridge 0.1.3-dev.fbe15023cdfe → 0.1.4-dev.04a1e5b9e484

package/dist/worktree/story-qa-reference-hydrator.js

@@ -0,0 +1,253 @@
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { GitClient } from "../shared/git/git.js";
+import { isSubPath } from "../shared/path/path.js";
+import { stableStringify } from "../session/phase-completion.helpers.js";
+const MAX_FILES = 128;
+const MAX_FILE_BYTES = 2 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 16 * 1024 * 1024;
+const hash = (body) => createHash("sha256").update(body).digest("hex");
+const fail = (reason) => new Error(`qa_handoff_invalid: ${reason}`);
+const segment = (value) => {
+    if (!/^[a-zA-Z0-9_-]{1,128}$/.test(value))
+        throw fail("invalid reference identity");
+    return value;
+};
+export function storyQaReferenceRoot(storyId, runId) {
+    return `.forge/work-items/${segment(storyId)}/qa-inputs/${segment(runId)}`;
+}
+// All inputs are reference-only. No phase verdict is created, promoted or replaced here.
+export async function materializeStoryQaReferences(worktreePath, request, git = new GitClient()) {
+    const story = request.storyQa;
+    const bundle = story?.references;
+    if (!bundle)
+        return;
+    if (!request.referenceRunId || bundle.schemaVersion !== 1 || bundle.storyWorkItemId !== request.workItem.id
+        || bundle.cycleRunId !== request.referenceCycleRunId || bundle.storyWorkItemId !== request.ownerId
+        || bundle.storyWorkItemId !== story.storyWorkItemId || bundle.repoId !== request.repo.id
+        || bundle.projectId !== request.workItem.projectId || bundle.effectiveAmendmentHash !== request.effectivePlanAmendmentHash
+        || bundle.planId !== story.planId || bundle.planContentHash !== story.planContentHash || story.worktreeKey !== request.worktreeKey
+        || !/^[a-f0-9]{64}$/i.test(bundle.effectiveAmendmentHash))
+        throw fail("reference owner/plan identity mismatch");
+    const relativeRoot = storyQaReferenceRoot(bundle.storyWorkItemId, request.referenceRunId);
+    const root = path.resolve(worktreePath, relativeRoot);
+    await safePath(worktreePath, root);
+    const files = [...bundle.files];
+    validateFiles(files);
+    const checkpoint = await captureCheckpoint(worktreePath, bundle, git);
+    if (checkpoint)
+        files.push(checkpoint);
+    validateFiles(files);
+    const manifest = JSON.stringify({ ...bundle, files: files.map(({ body: _body, ...file }) => file),
+        notice: "Reference input only. Historical PASS and repair checkpoint status are unchanged. Fresh QA is still required." }, null, 2) + "\n";
+    // Prepare a sibling directory and publish by rename; never leave a partially written manifest.
+    await fs.mkdir(path.dirname(root), { recursive: true });
+    await safePath(worktreePath, path.dirname(root));
+    const existing = await fs.stat(root).catch(error => { if (error.code === "ENOENT")
+        return null; throw error; });
+    if (existing) {
+        // A resumed cycle may reuse only its exact immutable reference snapshot.
+        await safePath(worktreePath, path.join(root, "manifest.json"));
+        const previous = JSON.parse(await fs.readFile(path.join(root, "manifest.json"), "utf8"));
+        const current = JSON.parse(manifest);
+        delete previous.capturedAt;
+        delete current.capturedAt;
+        if (stableStringify(previous) !== stableStringify(current))
+            throw fail("reference snapshot changed for this run");
+        for (const file of files) {
+            await safePath(worktreePath, path.join(root, file.path));
+            if (hash(await fs.readFile(path.join(root, file.path))) !== file.contentHash.toLowerCase())
+                throw fail("existing reference hash mismatch");
+        }
+        return;
+    }
+    const staging = `${root}.tmp-${randomUUID()}`;
+    await fs.mkdir(staging);
+    try {
+        for (const file of files) {
+            const target = path.join(staging, file.path);
+            await safePath(worktreePath, target);
+            await fs.mkdir(path.dirname(target), { recursive: true });
+            await fs.writeFile(target, file.body, { encoding: "utf8", flag: "wx", mode: 0o600 });
+        }
+        await fs.writeFile(path.join(staging, "manifest.json"), manifest, { flag: "wx", mode: 0o600 });
+        await safePath(worktreePath, root);
+        await fs.rename(staging, root);
+    }
+    finally {
+        await fs.rm(staging, { recursive: true, force: true });
+    }
+}
+function validateFiles(files) {
+    if (files.length === 0 || files.length > MAX_FILES)
+        throw fail("reference file count exceeds bounds");
+    const paths = new Set();
+    let total = 0;
+    for (const file of files) {
+        if (!/^(original|effective|children|amendments|checkpoint)\/[a-zA-Z0-9_./-]+$/.test(file.path)
+            || file.path.split("/").some(part => !part || part === "." || part === ".." || part.endsWith(".")))
+            throw fail("unsafe reference path");
+        const key = file.path.toLowerCase();
+        if (paths.has(key))
+            throw fail("duplicate reference path");
+        paths.add(key);
+        const bytes = Buffer.byteLength(file.body, "utf8");
+        total += bytes;
+        if (bytes > MAX_FILE_BYTES || total > MAX_TOTAL_BYTES)
+            throw fail("reference size exceeds bounds");
+        if (!/^[a-f0-9]{64}$/i.test(file.contentHash) || hash(file.body) !== file.contentHash.toLowerCase())
+            throw fail("reference content hash mismatch");
+        if (!file.provenance.trim())
+            throw fail("reference provenance missing");
+    }
+}
+async function captureCheckpoint(worktreePath, bundle, git) {
+    const storyId = bundle.storyWorkItemId;
+    const originalPath = path.join(worktreePath, ".forge", "work-items", segment(storyId), "artifacts", "comment-repair.handoff.json");
+    await safePath(worktreePath, originalPath);
+    let sourcePath = originalPath;
+    let archivedManifestPath;
+    let stat = await fs.stat(sourcePath).catch(error => { if (error.code === "ENOENT")
+        return null; throw error; });
+    if (!stat) {
+        // A previous QA already cleared outputs. A preserved input is not a new output:
+        // validate its immutable snapshot before deciding whether it still describes this tree.
+        const historyRoot = path.join(worktreePath, ".forge", "work-items", segment(storyId), "qa-inputs");
+        await safePath(worktreePath, historyRoot);
+        const entries = await fs.readdir(historyRoot, { withFileTypes: true }).catch(error => { if (error.code === "ENOENT")
+            return []; throw error; });
+        const candidates = [];
+        if (entries.length > MAX_FILES)
+            throw fail("checkpoint reference history exceeds bounds");
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.name.includes(".tmp-"))
+                continue;
+            const candidate = path.join(historyRoot, segment(entry.name), "checkpoint", "comment-repair.handoff.json");
+            await safePath(worktreePath, candidate);
+            const candidateStat = await fs.stat(candidate).catch(error => { if (error.code === "ENOENT")
+                return null; throw error; });
+            if (candidateStat)
+                candidates.push({ path: candidate, modified: candidateStat.mtimeMs });
+        }
+        candidates.sort((a, b) => b.modified - a.modified);
+        if (!candidates[0])
+            return null;
+        sourcePath = candidates[0].path;
+        archivedManifestPath = path.join(path.dirname(path.dirname(sourcePath)), "manifest.json");
+        stat = await fs.stat(sourcePath);
+    }
+    if (!stat.isFile() || stat.size > MAX_FILE_BYTES)
+        throw fail("checkpoint size exceeds bounds");
+    const body = await fs.readFile(sourcePath, "utf8");
+    const checkpoint = JSON.parse(body);
+    const recordedHash = checkpoint.content_hash;
+    const withoutHash = { ...checkpoint };
+    delete withoutHash.content_hash;
+    if (typeof recordedHash !== "string" || hash(stableStringify(withoutHash)) !== recordedHash.toLowerCase())
+        throw fail("checkpoint content hash mismatch");
+    const legacyOwner = checkpoint.owner_id === undefined && checkpoint.owner_type === undefined;
+    if (checkpoint.phase !== "comment_repair" || checkpoint.work_item_id !== storyId
+        || (!legacyOwner && (checkpoint.owner_id !== storyId || !["work_item", "story"].includes(String(checkpoint.owner_type))))
+        || !["pass", "needs_rework", "blocked"].includes(String(checkpoint.status))
+        || !Array.isArray(checkpoint.changed_files))
+        throw fail("checkpoint provenance mismatch");
+    // Ordinary repair artifacts describe paths/summaries but do not certify current bytes.
+    // Preserve them only as historical claims; extended checkpoints must pass every exact-tree fence.
+    const extended = checkpoint.attempt_dispatch_id !== undefined
+        || checkpoint.changed_files.some(value => value && typeof value === "object" && "sha256" in value);
+    const ordinaryProvenance = `historical-local-repair-claim:status=${checkpoint.status};not-current-tree-validation;not-authoritative-validation`;
+    const exactProvenance = `preserved-local-agent-claim:${checkpoint.attempt_dispatch_id}:HEAD=${checkpoint.repair_head_sha}:status=${checkpoint.status};not-authoritative-validation`;
+    const historicalProvenance = `historical-local-repair-claim:${checkpoint.attempt_dispatch_id}:recordedHEAD=${checkpoint.repair_head_sha}:status=${checkpoint.status};not-current-tree-validation;not-authoritative-validation`;
+    const archivedProvenance = archivedManifestPath
+        ? await validateArchivedCheckpoint(worktreePath, archivedManifestPath, bundle, body, extended ? [exactProvenance, historicalProvenance] : [ordinaryProvenance])
+        : undefined;
+    if (!extended)
+        return { path: "checkpoint/comment-repair.handoff.json", body, contentHash: hash(body), provenance: ordinaryProvenance };
+    if (typeof checkpoint.attempt_dispatch_id !== "string" || !/^[a-zA-Z0-9_-]{1,128}$/.test(checkpoint.attempt_dispatch_id))
+        throw fail("checkpoint attempt identity missing");
+    if (typeof checkpoint.repair_head_sha !== "string" || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/i.test(checkpoint.repair_head_sha))
+        throw fail("checkpoint HEAD invalid");
+    if (checkpoint.changed_files.length > 512)
+        throw fail("checkpoint file count exceeds bounds");
+    const recorded = new Set();
+    for (const value of checkpoint.changed_files) {
+        if (!value || typeof value !== "object")
+            throw fail("invalid checkpoint file");
+        const file = value;
+        if (typeof file.path !== "string" || file.path.includes("\\") || file.path.split("/").some(part => !part || part === "." || part === "..")
+            || path.isAbsolute(file.path) || file.path.includes(":") || [...file.path].some(character => character.charCodeAt(0) <= 31)
+            || typeof file.sha256 !== "string" || !/^[a-f0-9]{64}$/i.test(file.sha256))
+            throw fail("unsafe checkpoint file");
+        const filePath = file.path;
+        if ([...recorded].some(value => value.toLowerCase() === filePath.toLowerCase()))
+            throw fail("duplicate checkpoint file");
+        recorded.add(filePath);
+    }
+    const head = (await git.run(worktreePath, ["rev-parse", "HEAD"])).trim();
+    if (archivedProvenance && (checkpoint.repair_head_sha !== head || archivedProvenance === historicalProvenance)) {
+        // Publication (and later repair) may legitimately advance the owned branch. This
+        // snapshot remains an unchanged historical claim, NEVER proof of the new tree.
+        // Do not apply this path to fresh outputs or infer a PASS/publication receipt.
+        await git.run(worktreePath, ["merge-base", "--is-ancestor", checkpoint.repair_head_sha, head])
+            .catch(() => { throw fail("checkpoint history is not an ancestor of the prepared HEAD"); });
+        if ((await git.run(worktreePath, ["rev-parse", "HEAD"])).trim() !== head)
+            throw fail("checkpoint HEAD changed during verification");
+        return { path: "checkpoint/comment-repair.handoff.json", body, contentHash: hash(body), provenance: historicalProvenance };
+    }
+    if (checkpoint.repair_head_sha !== head)
+        throw fail("checkpoint HEAD changed");
+    for (const value of checkpoint.changed_files) {
+        const file = value;
+        const target = path.resolve(worktreePath, file.path);
+        await safePath(worktreePath, target);
+        const fileStat = await fs.stat(target);
+        if (!fileStat.isFile() || fileStat.size > 32 * 1024 * 1024 || hash(await fs.readFile(target)) !== file.sha256.toLowerCase())
+            throw fail("checkpoint changed-file hash mismatch");
+    }
+    const tracked = (await git.run(worktreePath, ["diff", "--name-only", "-z", "HEAD"])).split("\0").filter(Boolean);
+    const untracked = (await git.run(worktreePath, ["ls-files", "--others", "--exclude-standard", "-z"])).split("\0")
+        .filter(file => file && !/^\.forge\/(work-items|stories)\//.test(file));
+    const changed = new Set([...tracked, ...untracked]);
+    if (recorded.size !== changed.size || [...changed].some(file => !recorded.has(file)))
+        throw fail("checkpoint does not cover the complete prepared diff");
+    if ((await git.run(worktreePath, ["rev-parse", "HEAD"])).trim() !== head)
+        throw fail("checkpoint HEAD changed during verification");
+    return { path: "checkpoint/comment-repair.handoff.json", body, contentHash: hash(body),
+        provenance: exactProvenance };
+}
+async function validateArchivedCheckpoint(worktreePath, manifestPath, bundle, body, allowedProvenance) {
+    await safePath(worktreePath, manifestPath);
+    const stat = await fs.stat(manifestPath).catch(() => { throw fail("checkpoint reference manifest missing"); });
+    if (!stat.isFile() || stat.size > MAX_TOTAL_BYTES)
+        throw fail("checkpoint reference manifest exceeds bounds");
+    const manifest = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+    if (manifest?.schemaVersion !== 1 || manifest.storyWorkItemId !== bundle.storyWorkItemId
+        || manifest.projectId !== bundle.projectId || manifest.repoId !== bundle.repoId
+        || manifest.planId !== bundle.planId || manifest.planContentHash !== bundle.planContentHash
+        || manifest.effectiveAmendmentHash !== bundle.effectiveAmendmentHash
+        || typeof manifest.cycleRunId !== "string" || !/^[a-zA-Z0-9_-]{1,128}$/.test(manifest.cycleRunId)
+        || !Array.isArray(manifest.files) || manifest.files.length > MAX_FILES)
+        throw fail("checkpoint reference identity mismatch");
+    const files = manifest.files.filter((file) => typeof file?.path === "string" && file.path.toLowerCase() === "checkpoint/comment-repair.handoff.json");
+    if (files.length !== 1 || files[0].path !== "checkpoint/comment-repair.handoff.json"
+        || files[0].contentHash !== hash(body) || !allowedProvenance.includes(files[0].provenance))
+        throw fail("checkpoint reference integrity mismatch");
+    return files[0].provenance;
+}
+async function safePath(root, target) {
+    if (!isSubPath(root, target))
+        throw fail("reference path escapes worktree");
+    let current = path.resolve(root);
+    for (const part of path.relative(current, target).split(path.sep)) {
+        if (!part)
+            continue;
+        current = path.join(current, part);
+        const stat = await fs.lstat(current).catch(error => { if (error.code === "ENOENT")
+            return null; throw error; });
+        if (!stat)
+            return;
+        if (stat.isSymbolicLink())
+            throw fail("reference path traverses symlink");
+    }
+}

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

@@ -7,8 +7,10 @@ export declare class GitWorktreeService implements WorktreeService {
     constructor(git?: GitClient, coordinator?: WorktreeLifecycleCoordinator);
     prepare(request: WorktreePrepareRequest): Promise<WorktreeHandle>;
     private trackedForgePaths;
+    private registeredManagedWorktreePath;
     private repoCreationCoordinationPath;
     release(handle: WorktreeHandle): Promise<void>;
+    private restoreOrphanedWorktree;
     private resolveRepoPath;
     private managedRepoPath;
     private findExistingRepoPath;
@@ -19,5 +21,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,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { RepositoryCoordinatorLock } from "../sandbox/repository-lock.js";
@@ -5,6 +6,7 @@ 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 { materializeStoryQaReferences } from "./story-qa-reference-hydrator.js";
 import { warmWorktreeDependencies } from "./dependency-warmer.js";
 import { defaultWorktreeCoordinatorStateRoot, managedRepoRoot, resolveManagedWorktreeRoot, } from "./worktree-paths.js";
 export class GitWorktreeService {
@@ -36,37 +38,73 @@ export class GitWorktreeService {
             if (!isSubPath(allowedRoot, resolvedWorktreeParent)) {
                 throw new Error(`Worktree path must stay under ${allowedRoot}.`);
             }
+            let selectedWorktreePath = worktreePath;
             if (!(await directoryExists(worktreePath))) {
-                await this.git.run(repoPath, ["worktree", "add", "-B", branchName, worktreePath, baseStartPoint]);
-                return await resolveExistingDirectoryPath(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"]);
+                const registeredWorktreePath = await this.registeredManagedWorktreePath(repoPath, branchName, allowedRoot, worktreeSegments);
+                if (!registeredWorktreePath) {
+                    const branchRef = `refs/heads/${branchName}`;
+                    if (request.preserveExistingState && await this.gitRefExists(repoPath, branchRef)) {
+                        // The checkout directory can disappear while its branch still
+                        // contains completed agent work. Reattach that branch verbatim;
+                        // `-B ... baseStartPoint` would silently reset it and lose progress.
+                        await this.git.run(repoPath, ["worktree", "add", worktreePath, branchName]);
+                    }
+                    else {
+                        await this.git.run(repoPath, ["worktree", "add", "-B", branchName, worktreePath, baseStartPoint]);
+                    }
+                    return await resolveExistingDirectoryPath(worktreePath);
+                }
+                // The selected checkout can change when a Bridge reconnects or a local
+                // runner takes over. Its managed root therefore changes even though the
+                // deterministic lease branch does not. Reattach to the registered,
+                // Forge-owned worktree instead of trying to check out that branch twice.
+                selectedWorktreePath = registeredWorktreePath;
             }
-            const existingWorktreePath = await resolveExistingDirectoryPath(worktreePath);
+            const existingWorktreePath = await resolveExistingDirectoryPath(selectedWorktreePath);
             if (!isSubPath(allowedRoot, existingWorktreePath)) {
                 throw new Error(`Worktree path must stay under ${allowedRoot}.`);
             }
+            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 ${existingWorktreePath} is on branch '${currentBranch}', expected '${branchName}'.`);
             }
-            if (shouldResetExistingWorktree(request)) {
+            if (!request.preserveExistingState && shouldResetExistingWorktree(request)) {
                 await this.resetWorktreeToBase(existingWorktreePath, baseStartPoint);
             }
             return existingWorktreePath;
         });
-        await this.ensureGitIdentity(resolvedWorktreePath);
-        await clearRunArtifactRoots(resolvedWorktreePath, request);
+        // Reference inputs and an exact-tree local repair checkpoint must survive output cleanup.
+        await materializeStoryQaReferences(resolvedWorktreePath, request, this.git);
+        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 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,
@@ -82,6 +120,19 @@ export class GitWorktreeService {
         const output = await this.git.run(worktreePath, ["ls-files", "-z", "--", ".forge"]);
         return new Set(output.split("\0").filter(Boolean).map(value => value.replaceAll("\\", "/")));
     }
+    async registeredManagedWorktreePath(repoPath, branchName, allowedRoot, worktreeSegments) {
+        const listing = await this.git.run(repoPath, ["worktree", "list", "--porcelain", "-z"]);
+        const registered = parseRegisteredWorktrees(repoPath, listing)
+            .find(entry => entry.branchName === `refs/heads/${branchName}`);
+        if (!registered) {
+            return null;
+        }
+        const resolved = await resolveExistingDirectoryPath(registered.worktreePath);
+        if (!isManagedLeaseWorktreePath(allowedRoot, resolved, worktreeSegments)) {
+            throw new Error(`Branch '${branchName}' is already checked out outside its Forge-managed lease path at ${resolved}.`);
+        }
+        return resolved;
+    }
     repoCreationCoordinationPath(repo, allowedRoot) {
         if (repo.serverLocalPath && repo.serverLocalPath.trim().length > 0) {
             return path.resolve(repo.serverLocalPath);
@@ -93,18 +144,58 @@ export class GitWorktreeService {
             return;
         }
         await this.coordinator.withLock(handle.repoPath, async () => {
-            if (!(await directoryExists(handle.worktreePath))) {
-                return;
-            }
-            try {
-                await this.git.run(handle.repoPath, ["worktree", "remove", "--force", handle.worktreePath]);
-                await this.git.run(handle.repoPath, ["worktree", "prune"]);
-            }
-            catch {
-                await fs.rm(handle.worktreePath, { recursive: true, force: true });
+            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(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 (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) {
         if (repo.serverLocalPath && repo.serverLocalPath.trim().length > 0) {
             const requestedPath = await resolveExistingDirectoryPath(repo.serverLocalPath);
@@ -233,6 +324,32 @@ export class GitWorktreeService {
         await this.git.run(repoPath, ["config", "user.name", "Forge Bridge"]);
     }
 }
+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 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() ?? "";
     if (trimmed.length === 0 || trimmed.startsWith("local://")) {
@@ -317,6 +434,121 @@ function shouldResetExistingWorktree(request) {
     }
     return true;
 }
+function parseRegisteredWorktrees(repoPath, output) {
+    const worktrees = [];
+    let current = null;
+    for (const field of output.split("\0")) {
+        if (field.startsWith("worktree ")) {
+            if (current)
+                worktrees.push(current);
+            const rawPath = field.slice("worktree ".length);
+            current = {
+                worktreePath: path.resolve(path.isAbsolute(rawPath) ? rawPath : path.join(repoPath, rawPath)),
+                branchName: null,
+            };
+        }
+        else if (field.startsWith("branch ") && current) {
+            current.branchName = field.slice("branch ".length).trim();
+        }
+    }
+    if (current)
+        worktrees.push(current);
+    return worktrees;
+}
+function isManagedLeaseWorktreePath(allowedRoot, candidate, worktreeSegments) {
+    if (!isSubPath(allowedRoot, candidate)) {
+        return false;
+    }
+    const relativeSegments = path.relative(path.resolve(allowedRoot), path.resolve(candidate))
+        .split(path.sep)
+        .filter(Boolean);
+    const normalize = (value) => process.platform === "win32" ? value.toLowerCase() : value;
+    if (normalize(relativeSegments[0] ?? "") !== ".forge-worktrees"
+        || relativeSegments.length !== 2 + worktreeSegments.length) {
+        return false;
+    }
+    const suffix = relativeSegments.slice(-worktreeSegments.length).map(normalize);
+    return suffix.every((segment, index) => segment === normalize(worktreeSegments[index] ?? ""));
+}
+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, DispatchPriorPhaseArtifact, DispatchRepo, DispatchWorkItem, DispatchResolvedArtifact } from "../session/session.types.js";
+import type { DispatchQaReworkContext, DispatchPriorPhaseArtifact, DispatchRepo, DispatchWorkItem, DispatchResolvedArtifact, DispatchStoryQaContext } from "../session/session.types.js";
 import type { WarmDependenciesResult } from "./dependency-warmer.js";
 export interface WorktreePrepareRequest {
     readonly repo: DispatchRepo;
@@ -13,8 +13,14 @@ export interface WorktreePrepareRequest {
     readonly cleanupWorktrees: boolean;
     readonly artifacts: readonly DispatchResolvedArtifact[];
     readonly priorPhaseArtifacts?: readonly DispatchPriorPhaseArtifact[];
+    readonly storyQa?: DispatchStoryQaContext | null;
+    readonly referenceRunId?: string;
+    readonly referenceCycleRunId?: string;
+    readonly effectivePlanAmendmentHash?: string | null;
     readonly qaRework?: DispatchQaReworkContext | null;
     readonly warmPathOverrides?: readonly string[];
+    readonly applicationRuntimeRequired?: boolean;
+    readonly preserveExistingState?: boolean;
 }
 export interface WorktreeHandle {
     readonly repoPath: string;