@akira-tl/forgerelay 0.9.0 → 0.9.2

package/dist/workspaces/git/worktree-recovery.js

@@ -1,7 +1,9 @@
-import { realpath, stat } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { mkdir, realpath, rm, stat } from "node:fs/promises";
 import { platform } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { assertAllowedPath } from "../../mcp/filesystem/roots.js";
+import { managedWorktreePath } from "./git-worktrees.js";
 import { git } from "./git.js";
 export async function inspectManagedWorktreeRecovery(session, config) {
     if (session.status !== "active" ||
@@ -72,6 +74,233 @@ export async function inspectManagedWorktreeRecovery(session, config) {
         backingBranch,
     };
 }
+export async function prepareManagedWorktreeRepair(session, config) {
+    const recovery = await inspectManagedWorktreeRecovery(session, config);
+    if (!recovery) {
+        throw new Error(`Workspace ${session.id} is not an active managed-worktree Workspace.`);
+    }
+    if (recovery.classification !== "recoverable") {
+        return {
+            prepared: false,
+            recovery,
+            reason: "The Workspace is not in a provably recoverable managed-worktree state.",
+        };
+    }
+    if (!session.sourceRoot ||
+        !session.branch ||
+        !session.targetBranch ||
+        !session.baseRef ||
+        !session.baseSha ||
+        !session.branch.startsWith("forgerelay/")) {
+        return {
+            prepared: false,
+            recovery: manualRecovery(recovery),
+            reason: "Persisted managed-worktree ownership metadata is incomplete or cannot prove ForgeRelay branch ownership.",
+        };
+    }
+    const sourceRoot = assertAllowedPath(session.sourceRoot, config.allowedRoots);
+    const head = (await git(sourceRoot, ["rev-parse", `refs/heads/${session.branch}`])).stdout.trim();
+    const beforeRegistrations = await worktreeRegistrations(sourceRoot);
+    const persistedRegistrations = await matchingPathRegistrations(beforeRegistrations, session.root);
+    if (recovery.gitRegistration === "stale" &&
+        (persistedRegistrations.length !== 1 ||
+            persistedRegistrations[0]?.prunable !== true ||
+            persistedRegistrations[0]?.branch !== `refs/heads/${session.branch}` ||
+            (persistedRegistrations[0]?.head !== undefined && persistedRegistrations[0].head !== head))) {
+        return {
+            prepared: false,
+            recovery: manualRecovery(recovery),
+            reason: "The stale Git worktree registration does not prove ownership of the persisted ForgeRelay managed branch.",
+        };
+    }
+    const beforeConflicts = await conflictingBranchRegistrations(beforeRegistrations, session.branch, session.root);
+    if (beforeConflicts.length > 0) {
+        return {
+            prepared: false,
+            recovery: manualRecovery(recovery),
+            reason: `Managed branch ${session.branch} is already associated with another worktree candidate.`,
+        };
+    }
+    const root = await allocateManagedWorktreeRecoveryPath(sourceRoot, config);
+    try {
+        await git(sourceRoot, ["worktree", "add", "--force", root, session.branch]);
+    }
+    catch (error) {
+        await rm(root, { recursive: true, force: true });
+        const afterFailureConflicts = await conflictingBranchRegistrations(await worktreeRegistrations(sourceRoot), session.branch, session.root);
+        if (afterFailureConflicts.length > 0) {
+            return {
+                prepared: false,
+                recovery: manualRecovery(recovery),
+                reason: `Managed branch ${session.branch} acquired another worktree candidate while repair was starting.`,
+            };
+        }
+        throw new Error(`Git could not recreate managed-worktree backing from ${session.branch}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const preparation = {
+        prepared: true,
+        previousRoot: session.root,
+        root,
+        sourceRoot,
+        branch: session.branch,
+        targetBranch: session.targetBranch,
+        baseRef: session.baseRef,
+        baseSha: session.baseSha,
+        head,
+        recovery,
+    };
+    try {
+        const afterRegistrations = await worktreeRegistrations(sourceRoot);
+        const afterConflicts = await conflictingBranchRegistrations(afterRegistrations, session.branch, session.root, root);
+        if (afterConflicts.length > 0) {
+            await rollbackManagedWorktreeRepair(preparation, config);
+            return {
+                prepared: false,
+                recovery: manualRecovery(recovery),
+                reason: `Managed branch ${session.branch} has ambiguous worktree ownership after repair preflight.`,
+            };
+        }
+        const rootKey = await registrationPathKey(root);
+        const repairedRegistration = await firstMatchingRegistration(afterRegistrations, `refs/heads/${session.branch}`, rootKey);
+        if (!repairedRegistration || repairedRegistration.prunable) {
+            throw new Error("Git did not register the newly created recovery backing as an active worktree.");
+        }
+        const actualBranch = (await git(root, ["symbolic-ref", "--quiet", "--short", "HEAD"])).stdout.trim();
+        if (actualBranch !== session.branch) {
+            throw new Error(`Recovery backing opened branch ${actualBranch} instead of ${session.branch}.`);
+        }
+        const repairedHead = (await git(root, ["rev-parse", "HEAD"])).stdout.trim();
+        const managedHead = (await git(sourceRoot, ["rev-parse", `refs/heads/${session.branch}`])).stdout.trim();
+        if (repairedHead !== managedHead) {
+            throw new Error("Recovery backing HEAD does not match the surviving managed branch.");
+        }
+        if ((await git(root, ["status", "--porcelain=v1"])).stdout.trim().length > 0) {
+            throw new Error("Recovery backing is not clean immediately after reconstruction.");
+        }
+        const candidateRecovery = await inspectManagedWorktreeRecovery({ ...session, root }, config);
+        if (!candidateRecovery || candidateRecovery.classification !== "healthy") {
+            await rollbackManagedWorktreeRepair({ ...preparation, head: repairedHead }, config);
+            return {
+                prepared: false,
+                recovery: candidateRecovery ? manualRecovery(candidateRecovery) : manualRecovery(recovery),
+                reason: "The reconstructed backing did not pass the managed-worktree recovery health check.",
+            };
+        }
+        return { ...preparation, head: repairedHead, recovery: candidateRecovery };
+    }
+    catch (error) {
+        try {
+            await rollbackManagedWorktreeRepair(preparation, config);
+        }
+        catch (rollbackError) {
+            throw new Error(`${error instanceof Error ? error.message : String(error)} Recovery rollback also failed; the temporary backing was preserved for inspection: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`);
+        }
+        throw error;
+    }
+}
+export async function rollbackManagedWorktreeRepair(preparation, config) {
+    const sourceRoot = assertAllowedPath(preparation.sourceRoot, config.allowedRoots);
+    const root = assertAllowedPath(preparation.root, [config.worktreeRoot]);
+    const actualBranch = (await git(root, ["symbolic-ref", "--quiet", "--short", "HEAD"])).stdout.trim();
+    if (actualBranch !== preparation.branch) {
+        throw new Error(`Cannot roll back recovery backing because it is on ${actualBranch} instead of ${preparation.branch}.`);
+    }
+    if ((await git(root, ["status", "--porcelain=v1"])).stdout.trim().length > 0) {
+        throw new Error("Cannot roll back recovery backing because it acquired working-tree changes.");
+    }
+    const head = (await git(root, ["rev-parse", "HEAD"])).stdout.trim();
+    if (head !== preparation.head) {
+        throw new Error("Cannot roll back recovery backing because its managed branch advanced after reconstruction.");
+    }
+    await git(sourceRoot, ["worktree", "remove", root]);
+}
+export async function cleanupManagedWorktreeState(session, config, options = {}) {
+    if (session.mode !== "worktree" || !session.managed || (session.status !== "active" && session.status !== "closed")) {
+        throw new Error(`Workspace ${session.id} is not an active or closed ForgeRelay-managed worktree Workspace.`);
+    }
+    let recoveryBefore;
+    try {
+        recoveryBefore = await inspectManagedWorktreeRecovery(session, config);
+    }
+    catch {
+        recoveryBefore = undefined;
+    }
+    if (!session.sourceRoot || !session.branch || !session.targetBranch || !session.branch.startsWith("forgerelay/")) {
+        return cleanupResult(session, recoveryBefore, false, false, "manual-intervention", "Persisted managed-worktree ownership metadata is incomplete or cannot prove ForgeRelay branch ownership.");
+    }
+    let backing;
+    try {
+        backing = await directoryState(session.root, [config.worktreeRoot]);
+    }
+    catch {
+        return cleanupResult(session, recoveryBefore, false, false, "manual-intervention", "The persisted managed-worktree backing path is outside the trusted ForgeRelay worktree root or otherwise unavailable.");
+    }
+    if (backing === "present") {
+        return cleanupResult(session, recoveryBefore, false, false, "nothing-to-clean", "The managed worktree backing is still present; cleanup will not mutate an active or residual physical backing.");
+    }
+    const source = await sourceState(session.sourceRoot, config.allowedRoots);
+    if (source !== "available") {
+        return cleanupResult(session, recoveryBefore, false, false, "manual-intervention", "The persisted source repository is unavailable, so cleanup cannot prove Git ownership safely.");
+    }
+    const sourceRoot = assertAllowedPath(session.sourceRoot, config.allowedRoots);
+    const branchRef = `refs/heads/${session.branch}`;
+    let registrations = await worktreeRegistrations(sourceRoot);
+    const persistedRegistrations = await matchingPathRegistrations(registrations, session.root);
+    if (persistedRegistrations.length > 1) {
+        return cleanupResult(session, recoveryBefore, false, false, "manual-intervention", "Multiple Git worktree registrations match the persisted backing; cleanup requires manual intervention.");
+    }
+    let registrationRemoved = false;
+    const persistedRegistration = persistedRegistrations[0];
+    if (persistedRegistration) {
+        if (!persistedRegistration.prunable) {
+            return cleanupResult(session, recoveryBefore, false, false, "manual-intervention", "The persisted backing still has an active Git worktree registration; cleanup will not remove it.");
+        }
+        if (persistedRegistration.branch !== branchRef) {
+            return cleanupResult(session, recoveryBefore, false, false, "manual-intervention", "The stale Git worktree registration no longer proves ownership of the persisted ForgeRelay managed branch.");
+        }
+        try {
+            await git(sourceRoot, ["worktree", "remove", persistedRegistration.path]);
+            registrationRemoved = true;
+        }
+        catch {
+            return cleanupResult(session, recoveryBefore, false, false, "manual-intervention", "Git did not confirm safe removal of the stale worktree registration; no cleanup mutation was forced.");
+        }
+        registrations = await worktreeRegistrations(sourceRoot);
+    }
+    if (session.status === "active") {
+        const recovery = await inspectManagedWorktreeRecovery(session, config);
+        return cleanupResult(session, recovery, registrationRemoved, false, registrationRemoved ? "cleaned" : "nothing-to-clean", registrationRemoved
+            ? "Stale Git worktree registration removed; the managed branch is preserved because the Workspace remains active."
+            : "No stale registration is safe to remove; the managed branch is preserved because the Workspace remains active.");
+    }
+    const managedBranch = await branchState(sourceRoot, session.branch);
+    if (managedBranch === "missing") {
+        return cleanupResult(session, undefined, registrationRemoved, false, registrationRemoved ? "cleaned" : "nothing-to-clean", registrationRemoved ? undefined : "No stale registration or managed branch remains to clean.");
+    }
+    if (registrations.some((registration) => registration.branch === branchRef)) {
+        return cleanupResult(session, undefined, registrationRemoved, false, "manual-intervention", "The managed branch is still associated with a Git worktree registration and was preserved.");
+    }
+    if (options.managedBranchOwnedByOtherWorkspace) {
+        return cleanupResult(session, undefined, registrationRemoved, false, "manual-intervention", "Another persistent Workspace still references the managed branch, so it was preserved.");
+    }
+    if (await branchState(sourceRoot, session.targetBranch) !== "present") {
+        return cleanupResult(session, undefined, registrationRemoved, false, "manual-intervention", "The intended target branch is missing, so the managed branch was preserved.");
+    }
+    const sourceBranch = await currentBranchName(sourceRoot);
+    if (sourceBranch !== session.targetBranch) {
+        return cleanupResult(session, undefined, registrationRemoved, false, "manual-intervention", "The source checkout is not on the persisted target branch, so the managed branch was preserved.");
+    }
+    if (!await branchIsAncestorOfTarget(sourceRoot, session.branch, session.targetBranch)) {
+        return cleanupResult(session, undefined, registrationRemoved, false, "manual-intervention", "The managed branch contains commits not integrated into the intended target branch and was preserved.");
+    }
+    try {
+        await git(sourceRoot, ["branch", "-d", session.branch]);
+    }
+    catch {
+        return cleanupResult(session, undefined, registrationRemoved, false, "manual-intervention", "Git did not confirm safe managed-branch deletion at cleanup time; the branch was preserved.");
+    }
+    return cleanupResult(session, undefined, registrationRemoved, true, "cleaned");
+}
 async function directoryState(path, allowedRoots) {
     const allowedPath = assertAllowedPath(path, allowedRoots);
     try {
@@ -156,13 +385,113 @@ function parseWorktreeRegistrations(output) {
         const path = lines.find((line) => line.startsWith("worktree "))?.slice("worktree ".length);
         if (!path)
             return undefined;
+        const branch = lines.find((line) => line.startsWith("branch "))?.slice("branch ".length);
+        const head = lines.find((line) => line.startsWith("HEAD "))?.slice("HEAD ".length);
         return {
             path,
             prunable: lines.some((line) => line.startsWith("prunable ")),
+            ...(branch ? { branch } : {}),
+            ...(head ? { head } : {}),
         };
     })
         .filter((entry) => entry !== undefined);
 }
+async function worktreeRegistrations(sourceRoot) {
+    return parseWorktreeRegistrations((await git(sourceRoot, ["worktree", "list", "--porcelain"])).stdout);
+}
+async function conflictingBranchRegistrations(registrations, branch, previousRoot, repairedRoot) {
+    const branchRef = `refs/heads/${branch}`;
+    const previousKey = await registrationPathKey(previousRoot);
+    const repairedKey = repairedRoot ? await registrationPathKey(repairedRoot) : undefined;
+    const conflicts = [];
+    for (const registration of registrations) {
+        if (registration.branch !== branchRef)
+            continue;
+        const key = await registrationPathKey(registration.path);
+        if (key === previousKey && registration.prunable)
+            continue;
+        if (repairedKey !== undefined && key === repairedKey && !registration.prunable)
+            continue;
+        conflicts.push(registration);
+    }
+    return conflicts;
+}
+async function matchingPathRegistrations(registrations, path) {
+    const expectedKey = await registrationPathKey(path);
+    const matches = [];
+    for (const registration of registrations) {
+        if (await registrationPathKey(registration.path) === expectedKey)
+            matches.push(registration);
+    }
+    return matches;
+}
+async function firstMatchingRegistration(registrations, branchRef, pathKeyValue) {
+    for (const registration of registrations) {
+        if (registration.branch !== branchRef)
+            continue;
+        if (await registrationPathKey(registration.path) === pathKeyValue)
+            return registration;
+    }
+    return undefined;
+}
+async function allocateManagedWorktreeRecoveryPath(sourceRoot, config) {
+    await mkdir(config.worktreeRoot, { recursive: true });
+    for (let attempt = 0; attempt < 16; attempt += 1) {
+        const path = managedWorktreePath({
+            worktreeRoot: config.worktreeRoot,
+            repoRoot: sourceRoot,
+            worktreeId: randomBytes(4).toString("hex"),
+        });
+        assertAllowedPath(path, [config.worktreeRoot]);
+        try {
+            await stat(path);
+        }
+        catch (error) {
+            if (isMissingPath(error))
+                return path;
+            throw error;
+        }
+    }
+    throw new Error("Could not allocate a unique managed-worktree recovery path.");
+}
+function manualRecovery(recovery) {
+    return recovery.classification === "manual-intervention"
+        ? recovery
+        : { ...recovery, classification: "manual-intervention" };
+}
+function cleanupResult(session, recovery, registrationRemoved, managedBranchRemoved, classification, reason) {
+    return {
+        classification,
+        cleaned: registrationRemoved || managedBranchRemoved,
+        registrationRemoved,
+        managedBranchRemoved,
+        status: session.status,
+        ...(recovery ? { recovery } : {}),
+        ...(reason ? { reason } : {}),
+    };
+}
+async function currentBranchName(cwd) {
+    try {
+        return (await git(cwd, ["symbolic-ref", "--quiet", "--short", "HEAD"])).stdout.trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function branchIsAncestorOfTarget(sourceRoot, branch, targetBranch) {
+    try {
+        await git(sourceRoot, [
+            "merge-base",
+            "--is-ancestor",
+            `refs/heads/${branch}`,
+            `refs/heads/${targetBranch}`,
+        ]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 async function registrationPathKey(path) {
     const resolved = resolve(path);
     try {

package/dist/workspaces/sessions.js

@@ -2,6 +2,7 @@ import { stat } from "node:fs/promises";
 import { resolve } from "node:path";
 import { loadCapabilityGuides } from "../mcp/server/core/capabilities.js";
 import { createManagedWorktree, discardFreshManagedWorktree, } from "./git/git-worktrees.js";
+import { cleanupManagedWorktreeState, inspectManagedWorktreeRecovery, prepareManagedWorktreeRepair, rollbackManagedWorktreeRepair, } from "./git/worktree-recovery.js";
 import { AccessDeniedError, assertAllowedPath } from "../mcp/filesystem/roots.js";
 import { loadSubagentProfiles } from "../subagents/profiles.js";
 import { BOOTSTRAP_CONTEXT_COMPONENTS, bootstrapContextFingerprints, resolveBootstrapContextComponents, } from "./bootstrap.js";
@@ -371,6 +372,98 @@ export class WorkspaceSessionService {
             throw error;
         }
     }
+    async runManagedWorktreeRecovery(workspaceId, operation) {
+        const store = this.store;
+        if (!store) {
+            throw new Error(`Workspace ${workspaceId} cannot use managed-worktree recovery without persistent Workspace state.`);
+        }
+        const session = store.getSession(workspaceId);
+        if (!session)
+            throw new Error(`Unknown workspaceId: ${workspaceId}. Call open_workspace first.`);
+        if (operation === "cleanup") {
+            let managedBranchOwnedByOtherWorkspace = false;
+            if (session.sourceRoot && session.branch) {
+                const sourceKey = canonicalPersistedWorkspacePath(session.sourceRoot);
+                for (const candidate of store.listSessions({ mode: "worktree" })) {
+                    if (candidate.id === session.id ||
+                        !candidate.managed ||
+                        candidate.branch !== session.branch ||
+                        !candidate.sourceRoot)
+                        continue;
+                    if (canonicalPersistedWorkspacePath(candidate.sourceRoot) === sourceKey) {
+                        managedBranchOwnedByOtherWorkspace = true;
+                        break;
+                    }
+                }
+            }
+            return {
+                workspaceId: session.id,
+                ...await cleanupManagedWorktreeState(session, this.config, { managedBranchOwnedByOtherWorkspace }),
+            };
+        }
+        const recovery = await inspectManagedWorktreeRecovery(session, this.config);
+        if (!recovery) {
+            throw new Error(`Workspace ${session.id} is not an active managed-worktree Workspace.`);
+        }
+        if (operation === "status") {
+            return {
+                workspaceId: session.id,
+                repaired: false,
+                recovery,
+            };
+        }
+        const prepared = await prepareManagedWorktreeRepair(session, this.config);
+        if (!prepared.prepared) {
+            return {
+                workspaceId: session.id,
+                repaired: false,
+                recovery: prepared.recovery,
+                reason: prepared.reason,
+            };
+        }
+        const cachedWorkspace = this.workspaces.get(session.id);
+        try {
+            this.context.forgetWorkspaceResources(session.id);
+            this.workspaces.delete(session.id);
+            const candidateSession = {
+                ...session,
+                root: prepared.root,
+            };
+            const candidateWorkspace = this.workspaceFromSession(candidateSession, false);
+            await this.reusedWorkspaceContext(candidateWorkspace);
+            store.replaceWorktreeBacking({
+                id: session.id,
+                root: prepared.root,
+                sourceRoot: prepared.sourceRoot,
+                baseRef: prepared.baseRef,
+                baseSha: prepared.baseSha,
+                branch: prepared.branch,
+                targetBranch: prepared.targetBranch,
+            });
+            return {
+                workspaceId: session.id,
+                repaired: true,
+                previousRoot: prepared.previousRoot,
+                root: prepared.root,
+                branch: prepared.branch,
+                targetBranch: prepared.targetBranch,
+                recovery: prepared.recovery,
+            };
+        }
+        catch (error) {
+            this.context.forgetWorkspaceResources(session.id);
+            this.workspaces.delete(session.id);
+            if (cachedWorkspace)
+                this.workspaces.set(session.id, cachedWorkspace);
+            try {
+                await rollbackManagedWorktreeRepair(prepared, this.config);
+            }
+            catch (rollbackError) {
+                throw new Error(`${error instanceof Error ? error.message : String(error)} Recovery rollback also failed; the temporary backing was preserved for inspection: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`);
+            }
+            throw error;
+        }
+    }
     getWorkspaceSession(workspaceId) {
         const session = this.store?.getSession(workspaceId);
         if (session)