@loucompanion/forge-bridge 0.1.3-dev.f66395c3ac21 → 0.1.4-dev.1ff37038366e

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/story-qa-reference-hydrator.d.ts

@@ -0,0 +1,4 @@
+import { GitClient } from "../shared/git/git.js";
+import type { WorktreePrepareRequest } from "./worktree.types.js";
+export declare function storyQaReferenceRoot(storyId: string, runId: string): string;
+export declare function materializeStoryQaReferences(worktreePath: string, request: WorktreePrepareRequest, git?: GitClient): Promise<void>;

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-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,17 +1,30 @@
 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 registeredManagedWorktreePath;
+    private repoCreationCoordinationPath;
     release(handle: WorktreeHandle): Promise<void>;
+    private restoreOrphanedWorktree;
     private resolveRepoPath;
+    private managedRepoPath;
     private findExistingRepoPath;
     private resolveMatchingRepo;
-    private ensureBaseBranch;
+    private resolveBaseStartPoint;
+    private resetWorktreeToBase;
     private gitRefExists;
     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 {};