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

package/dist/worktree/worktree.service.js

@@ -1,61 +1,110 @@
+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 { materializeStoryQaReferences } from "./story-qa-reference-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);
-        await this.ensureBaseBranch(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, baseBranch]);
-            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}.`);
+            }
+            let selectedWorktreePath = worktreePath;
+            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"]);
+                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(selectedWorktreePath);
+            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 (!request.preserveExistingState && shouldResetExistingWorktree(request)) {
+                await this.resetWorktreeToBase(existingWorktreePath, baseStartPoint);
             }
+            return existingWorktreePath;
+        });
+        // 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);
         }
-        await this.ensureGitIdentity(resolvedWorktreePath);
-        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,
@@ -63,19 +112,88 @@ 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("\\", "/")));
+    }
+    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);
+        }
+        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) {
@@ -93,7 +211,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) {
@@ -124,6 +242,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();
@@ -164,21 +285,34 @@ export class GitWorktreeService {
         const resolved = await resolveExistingDirectoryPath(candidate);
         return isSubPath(allowedRoot, resolved) ? resolved : null;
     }
-    async ensureBaseBranch(repoPath, baseBranch) {
-        if (await this.gitRefExists(repoPath, `refs/heads/${baseBranch}`)) {
-            return;
+    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(() => "");
-        if (origin.trim().length === 0) {
-            throw new Error(`Base branch '${baseBranch}' was not found in the local checkout.`);
+        if (origin.trim().length > 0) {
+            const fetched = await this.git.run(repoPath, ["fetch", "--prune", "origin"])
+                .then(() => true)
+                .catch(() => false);
+            if (fetched && await this.gitRefExists(repoPath, remoteRef)) {
+                return remoteRef;
+            }
         }
-        await this.git.run(repoPath, ["fetch", "origin", `${baseBranch}:refs/remotes/origin/${baseBranch}`]).catch(() => "");
-        if (await this.gitRefExists(repoPath, `refs/remotes/origin/${baseBranch}`)) {
-            await this.git.run(repoPath, ["branch", baseBranch, `refs/remotes/origin/${baseBranch}`]);
-            return;
+        if (await this.gitRefExists(repoPath, localRef)) {
+            return localRef;
         }
         throw new Error(`Base branch '${baseBranch}' was not found locally or on origin.`);
     }
+    async resetWorktreeToBase(worktreePath, baseStartPoint) {
+        await this.git.run(worktreePath, ["reset", "--hard", baseStartPoint]);
+        await this.git.run(worktreePath, ["clean", "-fd"]);
+    }
     async gitRefExists(repoPath, gitRef) {
         return this.git.run(repoPath, ["show-ref", "--verify", "--quiet", gitRef]).then(() => true).catch(() => false);
     }
@@ -190,14 +324,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() ?? "";
@@ -206,9 +357,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) {
@@ -269,6 +423,132 @@ function normalizeOwnerType(value) {
     }
     return null;
 }
+function shouldResetExistingWorktree(request) {
+    const lane = request.lane.trim().toLowerCase();
+    const phase = request.phase.trim().toLowerCase().replace(/-/g, "_");
+    if (lane === "develop" && (phase === "implementation" || phase === "self_review" || phase === "validation")) {
+        return false;
+    }
+    if (lane === "qa" || phase === "qa") {
+        return false;
+    }
+    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, 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;
@@ -12,8 +12,15 @@ export interface WorktreePrepareRequest {
     readonly allowedRepoRoot: string;
     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;
@@ -23,4 +30,5 @@ export interface WorktreeHandle {
     readonly cleanupWorktrees: boolean;
     readonly dependencyWarm?: WarmDependenciesResult;
     readonly qaReworkPacketPath?: string;
+    readonly hydratedPriorPhaseArtifactCount?: number;
 }

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@loucompanion/forge-bridge",
-  "version": "0.1.3-dev.f66395c3ac21",
+  "version": "0.1.4-dev.04a1e5b9e484",
   "description": "Forge runner bridge CLI for connecting local developer machines to Forge dispatch.",
   "license": "UNLICENSED",
   "type": "module",
   "bin": {
+    "forge": "dist/cli/bin.js",
     "forge-bridge": "dist/cli/bin.js"
   },
   "main": "./dist/index.js",
@@ -18,6 +19,7 @@
   },
   "files": [
     "dist",
+    "runtime",
     "README.md"
   ],
   "repository": {
@@ -30,20 +32,22 @@
     "url": "https://github.com/coleman399/Forge/issues"
   },
   "engines": {
-    "node": ">=22.13.0"
+    "node": "^22.13.0 || >=24.0.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "vitest run",
+    "test": "node scripts/run-owned-tests.mjs",
+    "test:residue": "node scripts/run-owned-residue-gate.mjs",
     "test:watch": "vitest",
-    "smoke:package": "npm run build && node scripts/smoke-package.mjs",
-    "lint": "eslint \"src/**/*.ts\" \"scripts/**/*.mjs\" \"vitest.config.ts\""
+    "smoke:package": "tsc -p tsconfig.json && node scripts/smoke-package.mjs",
+    "lint": "eslint \"src/**/*.ts\" \"scripts/**/*.mjs\" \"vitest.config.ts\" \"vitest.setup.ts\""
   },
   "dependencies": {
-    "@microsoft/signalr": "^8.0.17"
+    "@microsoft/signalr": "^8.0.17",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
@@ -52,6 +56,7 @@
     "globals": "^17.6.0",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.61.1",
-    "vitest": "^3.2.3"
+    "vite": "^7.3.7",
+    "vitest": "^4.1.12"
   }
 }