@akira-tl/forgerelay 0.8.10 → 0.9.1

package/CHANGELOG.md

@@ -4,6 +4,27 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.9.1] - 2026-09-04
+
+### Added
+
+- Added the low-frequency `workspace.recovery` Capability for ForgeRelay-managed worktrees. `status` reports the existing recovery model; `repair` can recreate missing active execution backing only from the surviving ForgeRelay managed branch; and Workspace-scoped `cleanup` removes only proven stale worktree registration or an already-integrated closed-Workspace managed branch. Workspace identity and Task state are preserved, active/unique/ambiguous Git state is never force-deleted, Relay executes recovery on the owning Execution ForgeRelay, and Composite use remains explicit-member scoped.
+
+## [0.9.0] - 2026-09-04
+
+### Added
+
+- Added bounded read-only managed-worktree recovery diagnostics to `open_workspace` inventory and inspection, distinguishing healthy, recoverable, and manual-intervention states across missing backing/source/branches, stale Git worktree registration, and branch mismatches. Relayed inspection carries the sanitized diagnostic facts from the Execution ForgeRelay without mutating Git state.
+
+### Changed
+
+- Aligned current roadmap and product documentation with already-shipped first-class Subagent delegation, Hook-backed managed-worktree close verification, and explicitly authorized live managed TypeScript/Pyright installation. The 0.9 line is now defined as recovery diagnostics/repair, Workspace checkpoints/restore, and owner-facing retention maintenance.
+- Added managed-worktree recovery/inventory tests to the regular release test suite so the diagnostic contract is exercised on every cloud platform.
+
+### Fixed
+
+- Canonicalized managed-worktree registration paths through their real filesystem location, preventing macOS `/var/...` and `/private/var/...` aliases (and equivalent symlink aliases) from being misreported as missing Git worktree registration.
+
 ## [0.8.10] - 2026-09-03
 
 ### Added

package/README.md

@@ -165,10 +165,13 @@ symbols, workspace symbols, and diagnostics. Results use ForgeRelay-owned normal
 locations, ranges, symbols, hover content, and diagnostic shapes rather than raw LSP
 wire unions.
 
-Language servers remain external dependencies. ForgeRelay can discover
-`typescript-language-server`, `pyright-langserver`, `rust-analyzer`, `gopls`, and
-`clangd` when they already exist on `PATH`, or use structured project/global
-configuration, but it never installs a server automatically. See
+Language servers are never installed automatically or without user authorization.
+ForgeRelay can discover configured or `PATH`-available servers, and `forgerelay init`
+can optionally enable Agent-managed installation of TypeScript/JavaScript and Pyright
+inside ForgeRelay's private config directory. That permission is disabled by default;
+a successful managed install becomes available to the same running ForgeRelay process
+on the next semantic request without a restart. `rust-analyzer`, `gopls`, and `clangd`
+remain external toolchain/system installations. See
 [Configuration Reference](docs/configuration.md#lsp-code-intelligence) and
 [`examples/language-servers.json`](examples/language-servers.json).
 
@@ -297,13 +300,13 @@ forgerelay doctor
 
 ## Where ForgeRelay is going
 
-With LSP code intelligence established in the 0.4 line, the next additions remain
-focused on making the local execution layer more useful, not on turning ForgeRelay
-into another all-in-one agent framework:
+With persistent Workspace lifecycle, first-class Subagent delegation, managed-LSP
+support, and worktree-close verification already shipped, the 0.9 line focuses on
+Workspace recovery and history without expanding the canonical Core tool surface:
 
-1. first-class MCP subagent delegation;
-2. stronger worktree verification and recovery;
-3. checkpoint/rewind and retention improvements.
+1. read-only managed-worktree recovery diagnostics, followed by safe repair/cleanup;
+2. persistent Workspace checkpoints and concurrency-safe restore;
+3. owner-facing retention inspection and explicitly authorized maintenance.
 
 ForgeRelay does not plan to add its own shell sandbox, long-term memory system,
 or plugin marketplace. Conversation, planning, web access, and other host-native

package/capabilities/workspace/managed-worktrees/GUIDE.md

@@ -45,4 +45,26 @@ Managed worktree finalize：
 
 source checkout 可能被用户或其他 Agent 修改。关闭前不要假设 target branch 仍停留在创建 worktree 时的状态；让 ForgeRelay 的 close 检查决定是否可以安全集成。遇到 diverged target、dirty source、忙碌 workspace 或 cleanup warning 时，保留现有 worktree 状态并向用户说明真实失败点，不要自行强制 reset、merge 或删除 worktree。
 
-如果需要继续工作，复用原 `workspaceId` 或已知 worktree path；不要因为一次关闭失败就创建新的隔离副本。
+如果 active managed-worktree Workspace 的物理 backing 丢失，先用 `open_workspace action="inspect"` 或 `workspace.recovery` 的 `status` 查看恢复分类。只有 Capability 返回 `recoverable` 时，才考虑 `workspace.recovery { operation: "repair" }`。
+
+`workspace.recovery` 的 repair 规则：
+
+- 只恢复当前 persistent `workspaceId`，不会创建新的 Workspace identity；
+- 必须从持久化记录中的原 `forgerelay/*` managed branch 恢复，绝不从 target branch 重新创建替代工作；
+- managed branch、target branch、source repository identity、worktree ownership 任一无法证明时返回 `manual-intervention`，不猜测；
+- 若同一 managed branch 已出现另一个 worktree candidate，拒绝自动恢复；
+- recovery backing 创建后必须重新验证 branch、HEAD、Git registration 和工作树健康状态，验证失败时仅回滚 ForgeRelay 本次创建的临时 backing；
+- repair 不 merge、不 rebase、不 reset、不删除 managed branch，也不移动 target branch。
+
+`workspace.recovery { operation: "cleanup" }` 只清理当前 persistent Workspace 能证明归属的 Git administrative residue：
+
+- backing 已不存在且 stale registration 仍精确对应持久化 managed branch 时，可只移除该 registration；不执行 repository-wide `git worktree prune`；
+- active Workspace 的 managed branch 始终保留，即使 stale registration 已被清掉，避免 cleanup 把仍需恢复的 Workspace 变成不可恢复状态；
+- closed Workspace 的残留 `forgerelay/*` branch 只有在没有任何 worktree registration 或其他 persistent Workspace identity 持有它、source checkout 仍位于持久化 target branch、且 Git 证明该 branch 已完整并入 target 时才允许删除；
+- unique/unmerged commits、branch ownership mismatch、active backing、缺失 target、source/target identity 不可证明等情况返回 `manual-intervention`，不强制删除；
+- cleanup 返回 `cleaned`、`nothing-to-clean` 或 `manual-intervention` 分类；对 active Workspace 成功清理 registration 后同时返回更新后的 recovery projection；
+- cleanup 不 reopen、close、delete Workspace，也不改变 persistent Workspace lifecycle state。
+
+Relay Workspace 的 recovery 在 Execution ForgeRelay 上执行；Composite Workspace 必须显式指定实际拥有该 worktree 的 member。不要在 Gateway 或 Composite identity 上自行解释/修改成员 Git 状态。
+
+如果需要继续工作，复用原 `workspaceId`；不要因为 backing 丢失、一次关闭失败或一次恢复失败就创建新的隔离副本来绕过原状态。

package/dist/mcp/server/core/capabilities.js

@@ -95,6 +95,7 @@ export function buildCapabilityFingerprint(config, version, context = {}) {
         "capability-guides.read",
         "code.intelligence",
         "workspace.tasks",
+        "workspace.recovery",
     ];
     if (config.toolMode !== "codex") {
         capabilities.push("batch.execute");

package/dist/mcp/server/core/capability-registry.js

@@ -190,6 +190,11 @@ export function createCapabilityRegistry(dependencies) {
             taskId: z.string().min(1),
         }).strict(),
     ]);
+    const workspaceRecoveryInput = z.discriminatedUnion("operation", [
+        z.object({ operation: z.literal("status") }).strict(),
+        z.object({ operation: z.literal("repair") }).strict(),
+        z.object({ operation: z.literal("cleanup") }).strict(),
+    ]);
     const subagentSessionInput = z.discriminatedUnion("operation", [
         z.object({
             operation: z.literal("start"),
@@ -287,6 +292,18 @@ export function createCapabilityRegistry(dependencies) {
                     run: async (input, context, options) => dependencies.codeIntelligence.run(input, context, options),
                 }]
             : []),
+        ...(dependencies.workspaceRecovery
+            ? [{
+                    name: "workspace.recovery",
+                    description: "Inspect or safely repair the current managed-worktree Workspace when ForgeRelay can prove the surviving managed branch and execution backing ownership.",
+                    guideName: "managed-worktrees",
+                    readGuideBeforeFirstUse: true,
+                    batchPolicy: "unsupported",
+                    inputSchema: workspaceRecoveryInput,
+                    availability: (context) => managedWorktreeAvailability(context, dependencies.workspaceRecovery?.available ?? false, dependencies.workspaceRecovery?.unavailableReason),
+                    run: async (input, context, options) => dependencies.workspaceRecovery.run(input, context, options),
+                }]
+            : []),
         ...(dependencies.workspaceTasks
             ? [{
                     name: "workspace.tasks",
@@ -360,6 +377,17 @@ function filesystemWorkspaceAvailability(context, available = true, reason) {
     }
     return { available, ...(reason ? { reason } : {}) };
 }
+function managedWorktreeAvailability(context, available = true, reason) {
+    if (context.workspaceKind !== "workspace" ||
+        context.workspaceMode !== "worktree" ||
+        context.workspaceManaged !== true) {
+        return {
+            available: false,
+            reason: "This capability is available only for a ForgeRelay-managed worktree Workspace.",
+        };
+    }
+    return { available, ...(reason ? { reason } : {}) };
+}
 function requireWorkspaceRoot(context) {
     if (context.workspaceKind !== "workspace" || !context.workspaceRoot) {
         throw new CapabilityError("capability_unavailable", "This capability requires a filesystem-backed Workspace.");

package/dist/mcp/server/core/capability-support.js

@@ -1,3 +1,4 @@
+import { loadCapabilityGuides } from "./capabilities.js";
 import { CapabilityError } from "./capability-registry.js";
 import { formatPathForPrompt } from "../../../workspaces/resources/skills.js";
 export function workspaceHookInvocation(workspace) {
@@ -13,6 +14,8 @@ export function capabilityContextFor(workspace) {
         workspaceId: workspace.id,
         workspaceKind: "workspace",
         workspaceRoot: workspace.root,
+        workspaceMode: workspace.mode,
+        workspaceManaged: workspace.worktree?.managed ?? false,
         guides: workspace.capabilityGuides.map((guide) => ({
             name: guide.name,
             description: guide.description,
@@ -21,6 +24,20 @@ export function capabilityContextFor(workspace) {
         })),
     };
 }
+export function managedWorktreeRecoveryCapabilityContext(session, config) {
+    return {
+        workspaceId: session.id,
+        workspaceKind: "workspace",
+        workspaceMode: session.mode,
+        workspaceManaged: session.managed,
+        guides: loadCapabilityGuides(config).map((guide) => ({
+            name: guide.name,
+            description: guide.description,
+            whenToRead: guide.whenToRead,
+            path: formatPathForPrompt(guide.filePath),
+        })),
+    };
+}
 export function compositeCapabilityContext(workspaceId, guides) {
     return {
         workspaceId,

package/dist/mcp/server/core/schemas.js

@@ -94,6 +94,26 @@ export const workspaceSubagentProviderOutputSchema = z.object({
 export const workspaceAvailableAgentsFileOutputSchema = z.object({
     path: z.string(),
 });
+export const managedWorktreeRecoveryOutputSchema = z.object({
+    classification: z.enum(["healthy", "recoverable", "manual-intervention"]),
+    conditions: z.array(z.enum([
+        "backing-missing",
+        "managed-branch-missing",
+        "git-registration-stale",
+        "git-registration-missing",
+        "git-registration-unavailable",
+        "branch-mismatch",
+        "source-missing",
+        "source-unavailable",
+        "target-branch-missing",
+    ])),
+    backing: z.enum(["present", "missing"]),
+    source: z.enum(["available", "missing", "unavailable"]),
+    gitRegistration: z.enum(["registered", "stale", "missing", "unavailable"]),
+    managedBranch: z.enum(["present", "missing", "unknown"]),
+    targetBranch: z.enum(["present", "missing", "unknown"]),
+    backingBranch: z.enum(["matching", "mismatched", "unavailable"]),
+});
 export const workspaceInventoryEntryOutputSchema = z.object({
     label: z.string(),
     workspaceId: z.string(),
@@ -109,6 +129,7 @@ export const workspaceInventoryEntryOutputSchema = z.object({
     lastUsedAt: z.string(),
     idleMs: z.number().nonnegative(),
     rootValid: z.boolean(),
+    recovery: managedWorktreeRecoveryOutputSchema.optional(),
     current: z.boolean(),
 });
 export const workspaceInventorySummaryOutputSchema = z.object({
@@ -167,6 +188,7 @@ export const workspaceInspectionOutputSchema = z.union([
         lastUsedAt: z.string(),
         idleMs: z.number().nonnegative(),
         rootValid: z.boolean(),
+        recovery: managedWorktreeRecoveryOutputSchema.optional(),
         taskSummary: workspaceTaskInspectionSummaryOutputSchema.optional(),
     }),
     z.object({
@@ -186,6 +208,7 @@ export const workspaceInspectionOutputSchema = z.union([
         lastUsedAt: z.string().optional(),
         idleMs: z.number().nonnegative().optional(),
         rootValid: z.boolean().optional(),
+        recovery: managedWorktreeRecoveryOutputSchema.optional(),
         taskSummary: workspaceTaskInspectionSummaryOutputSchema.optional(),
         relay: z.string(),
         executionLocation: z.string(),

package/dist/mcp/server/operations/runtime/operation-runtime.js

@@ -10,7 +10,7 @@ import { formatAgentsPath } from "../../../../workspaces.js";
 import { markReturnedOutput, processActivityOutcome, processToolResponse, } from "../../../process/runtime.js";
 import { capabilityActivityAuditRequest, capabilityActivityAuditResult } from "../../../../subagents/sessions/mcp/audit.js";
 import { activityRelationFor, activityRequestFor, runActivityTool, runActivityToolWithHooks, standardActivityOutcome, } from "../../core/activity-support.js";
-import { capabilityContextFor, workspaceHookInvocation } from "../../core/capability-support.js";
+import { capabilityContextFor, managedWorktreeRecoveryCapabilityContext, workspaceHookInvocation, } from "../../core/capability-support.js";
 import { assertWorkspaceInstructionsLoadedBeforeSideEffect, contentLineCount, contentText, countDiffStats, formatDiscoveredWorkspaceInstructions, logFailedToolResponse, logToolCall, newFilePatch, textBlock, textSummary, toolResultContent, toolResultIsError, toolResultText, workspaceLogContext, } from "../../core/tool-support.js";
 import { appendAutomaticMutationDiagnostics } from "./mutation-diagnostics.js";
 export function createOperationRuntime(options) {
@@ -429,6 +429,58 @@ export function createOperationRuntime(options) {
         },
         capabilityRun: async (input, context) => {
             const { workspaceId, name, arguments: capabilityArguments, file } = input;
+            if (name === "workspace.recovery") {
+                const session = workspaces.getWorkspaceSession(workspaceId);
+                if (session.status === "closed") {
+                    const startedAt = performance.now();
+                    try {
+                        const execution = await capabilityRegistry.run(name, capabilityArguments ?? {}, managedWorktreeRecoveryCapabilityContext(session, config), {
+                            nativeFile: file,
+                            signal: context.signal,
+                            requestMeta: context.requestMeta,
+                            sessionId: context.sessionId,
+                            batch: context.batch,
+                        });
+                        const result = {
+                            content: [textBlock(`Capability ${name} completed.\n${JSON.stringify(execution.value, null, 2)}`)],
+                            structuredContent: { name, action: "run", result: execution.value },
+                        };
+                        logToolCall(config, {
+                            tool: toolNames.capability,
+                            workspaceId: session.id,
+                            capability: name,
+                            action: "run",
+                            success: true,
+                            durationMs: Math.round(performance.now() - startedAt),
+                        });
+                        return result;
+                    }
+                    catch (error) {
+                        const capabilityError = error instanceof CapabilityError
+                            ? error
+                            : new CapabilityError("execution_failed", error instanceof Error ? error.message : String(error));
+                        const result = {
+                            content: [textBlock(`${capabilityError.code}: ${capabilityError.message}`)],
+                            structuredContent: {
+                                name,
+                                action: "run",
+                                error: { code: capabilityError.code, message: capabilityError.message },
+                            },
+                            isError: true,
+                        };
+                        logToolCall(config, {
+                            tool: toolNames.capability,
+                            workspaceId: session.id,
+                            capability: name,
+                            action: "run",
+                            success: false,
+                            durationMs: Math.round(performance.now() - startedAt),
+                            error: capabilityError.message,
+                        });
+                        return result;
+                    }
+                }
+            }
             const workspace = workspaces.getWorkspace(workspaceId);
             let changedPaths = [];
             return runActivityTool(activityLifecycle, workspace, hostScopeIdFor(context.requestMeta, context.sessionId), toolNames.capability, activityRequestFor(capabilityActivityAuditRequest(input), context), (activityContext) => runToolWithHooks(hooks, {
@@ -438,6 +490,7 @@ export function createOperationRuntime(options) {
                 payload: { name, action: "run" },
                 isFailure: toolResultIsError,
                 changedPaths: () => changedPaths,
+                afterCwd: () => workspaces.getWorkspaceSession(workspaceId).root,
                 operation: async () => {
                     const startedAt = performance.now();
                     try {

package/dist/server.js

@@ -131,6 +131,12 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
     const capabilityRegistry = createCapabilityRegistry({
         inspectHooks: (workspaceRoot) => checkHookConfiguration(workspaceRoot, config.hooks),
         ...subagentMcp.registryDependencies,
+        workspaceRecovery: {
+            available: true,
+            run: async (input, context) => ({
+                value: await workspaces.runManagedWorktreeRecovery(context.workspaceId, input.operation),
+            }),
+        },
         workspaceTasks: {
             available: true,
             run: async (input, context) => {

package/dist/workspaces/git/git-worktrees.js

@@ -228,7 +228,7 @@ async function isAncestor(ancestor, descendant, cwd) {
         return false;
     }
 }
-function managedWorktreePath(input) {
+export function managedWorktreePath(input) {
     const repoName = sanitizePathSegment(basename(input.repoRoot)) || "repo";
     return join(input.worktreeRoot, `${repoName}-${input.worktreeId}`);
 }

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

@@ -0,0 +1,518 @@
+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" ||
+        session.mode !== "worktree" ||
+        !session.managed)
+        return undefined;
+    const backing = await directoryState(session.root, [config.worktreeRoot]);
+    const source = await sourceState(session.sourceRoot, config.allowedRoots);
+    const conditions = [];
+    if (source === "missing")
+        conditions.push("source-missing");
+    else if (source === "unavailable")
+        conditions.push("source-unavailable");
+    if (backing === "missing")
+        conditions.push("backing-missing");
+    if (source !== "available" || !session.sourceRoot) {
+        return {
+            classification: "manual-intervention",
+            conditions,
+            backing,
+            source,
+            gitRegistration: "unavailable",
+            managedBranch: "unknown",
+            targetBranch: "unknown",
+            backingBranch: "unavailable",
+        };
+    }
+    const sourceRoot = assertAllowedPath(session.sourceRoot, config.allowedRoots);
+    const [managedBranch, targetBranch, registration] = await Promise.all([
+        branchState(sourceRoot, session.branch),
+        branchState(sourceRoot, session.targetBranch),
+        registrationState(sourceRoot, session.root),
+    ]);
+    if (managedBranch === "missing")
+        conditions.push("managed-branch-missing");
+    if (targetBranch === "missing")
+        conditions.push("target-branch-missing");
+    if (registration === "stale")
+        conditions.push("git-registration-stale");
+    else if (registration === "missing")
+        conditions.push("git-registration-missing");
+    else if (registration === "unavailable")
+        conditions.push("git-registration-unavailable");
+    const backingBranch = backing === "present"
+        ? await backingBranchState(session.root, session.branch)
+        : "unavailable";
+    if (backingBranch === "mismatched")
+        conditions.push("branch-mismatch");
+    const recoverable = backing === "missing" &&
+        managedBranch === "present" &&
+        targetBranch === "present" &&
+        (registration === "stale" || registration === "missing") &&
+        conditions.every((condition) => condition === "backing-missing" ||
+            condition === "git-registration-stale" ||
+            condition === "git-registration-missing");
+    return {
+        classification: conditions.length === 0
+            ? "healthy"
+            : recoverable
+                ? "recoverable"
+                : "manual-intervention",
+        conditions,
+        backing,
+        source,
+        gitRegistration: registration,
+        managedBranch,
+        targetBranch,
+        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 {
+        return (await stat(allowedPath)).isDirectory() ? "present" : "missing";
+    }
+    catch (error) {
+        if (isMissingPath(error))
+            return "missing";
+        throw error;
+    }
+}
+async function sourceState(sourceRoot, allowedRoots) {
+    if (!sourceRoot)
+        return "unavailable";
+    let sourcePath;
+    try {
+        sourcePath = assertAllowedPath(sourceRoot, allowedRoots);
+    }
+    catch {
+        return "unavailable";
+    }
+    try {
+        if (!(await stat(sourcePath)).isDirectory())
+            return "missing";
+    }
+    catch (error) {
+        return isMissingPath(error) ? "missing" : "unavailable";
+    }
+    try {
+        const gitRoot = (await git(sourcePath, ["rev-parse", "--show-toplevel"])).stdout.trim();
+        const [canonicalGitRoot, canonicalSource] = await Promise.all([realpath(gitRoot), realpath(sourcePath)]);
+        return pathKey(canonicalGitRoot) === pathKey(canonicalSource) ? "available" : "unavailable";
+    }
+    catch {
+        return "unavailable";
+    }
+}
+async function branchState(sourceRoot, branch) {
+    if (!branch)
+        return "missing";
+    try {
+        await git(sourceRoot, ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`]);
+        return "present";
+    }
+    catch {
+        return "missing";
+    }
+}
+async function registrationState(sourceRoot, worktreePath) {
+    let registrations;
+    try {
+        registrations = parseWorktreeRegistrations((await git(sourceRoot, ["worktree", "list", "--porcelain"])).stdout);
+    }
+    catch {
+        return "unavailable";
+    }
+    const worktreeKey = await registrationPathKey(worktreePath);
+    for (const registration of registrations) {
+        if (await registrationPathKey(registration.path) !== worktreeKey)
+            continue;
+        return registration.prunable ? "stale" : "registered";
+    }
+    return "missing";
+}
+async function backingBranchState(worktreeRoot, expectedBranch) {
+    if (!expectedBranch)
+        return "mismatched";
+    try {
+        const actual = (await git(worktreeRoot, ["symbolic-ref", "--quiet", "--short", "HEAD"])).stdout.trim();
+        return actual === expectedBranch ? "matching" : "mismatched";
+    }
+    catch {
+        return "mismatched";
+    }
+}
+function parseWorktreeRegistrations(output) {
+    return output
+        .trim()
+        .split(/\n\n+/)
+        .map((block) => {
+        const lines = block.split("\n");
+        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 {
+        return pathKey(await realpath(resolved));
+    }
+    catch (error) {
+        if (!isMissingPath(error))
+            return pathKey(resolved);
+        try {
+            return pathKey(join(await realpath(dirname(resolved)), basename(resolved)));
+        }
+        catch {
+            return pathKey(resolved);
+        }
+    }
+}
+function pathKey(path) {
+    const resolved = resolve(path);
+    return platform() === "win32" ? resolved.toLowerCase() : resolved;
+}
+function isMissingPath(error) {
+    return error instanceof Error && "code" in error &&
+        (error.code === "ENOENT" || error.code === "ENOTDIR");
+}

package/dist/workspaces/inventory.js

@@ -1,6 +1,7 @@
 import { basename, resolve } from "node:path";
 import { assertAllowedPath } from "../mcp/filesystem/roots.js";
 import { canonicalPath } from "./paths.js";
+import { inspectManagedWorktreeRecovery } from "./git/worktree-recovery.js";
 const WORKSPACE_STALE_REMINDER_MS = 2 * 24 * 60 * 60 * 1_000;
 /** Build bounded read-only projections over persistent Workspace sessions. */
 export class WorkspaceInventoryService {
@@ -84,11 +85,12 @@ export class WorkspaceInventoryService {
     }
     async inventoryEntryForSession(session, now, current) {
         const rootValid = await this.sessions.validSessionRoot(session) !== undefined;
+        const recovery = await inspectManagedWorktreeRecovery(session, this.config);
         const lastUsedAt = Date.parse(session.lastUsedAt);
         const idleMs = Number.isFinite(lastUsedAt) ? Math.max(0, now - lastUsedAt) : 0;
         const state = session.status !== "active"
             ? "closed"
-            : !rootValid
+            : !rootValid || (recovery !== undefined && recovery.classification !== "healthy")
                 ? "invalid"
                 : idleMs >= WORKSPACE_STALE_REMINDER_MS
                     ? "stale"
@@ -109,6 +111,7 @@ export class WorkspaceInventoryService {
             lastUsedAt: session.lastUsedAt,
             idleMs,
             rootValid,
+            ...(recovery ? { recovery } : {}),
             current,
         };
     }

package/dist/workspaces/relay/result-support.js

@@ -25,6 +25,42 @@ export function copyNumberField(source, target, field) {
     if (typeof value === "number" && Number.isFinite(value) && value >= 0)
         target[field] = value;
 }
+export function safeManagedWorktreeRecovery(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const recovery = value;
+    const classifications = new Set(["healthy", "recoverable", "manual-intervention"]);
+    const conditions = new Set([
+        "backing-missing",
+        "managed-branch-missing",
+        "git-registration-stale",
+        "git-registration-missing",
+        "git-registration-unavailable",
+        "branch-mismatch",
+        "source-missing",
+        "source-unavailable",
+        "target-branch-missing",
+    ]);
+    if (typeof recovery.classification !== "string" || !classifications.has(recovery.classification) ||
+        !Array.isArray(recovery.conditions) || recovery.conditions.some((condition) => typeof condition !== "string" || !conditions.has(condition)) ||
+        (recovery.backing !== "present" && recovery.backing !== "missing") ||
+        (recovery.source !== "available" && recovery.source !== "missing" && recovery.source !== "unavailable") ||
+        (recovery.gitRegistration !== "registered" && recovery.gitRegistration !== "stale" && recovery.gitRegistration !== "missing" && recovery.gitRegistration !== "unavailable") ||
+        (recovery.managedBranch !== "present" && recovery.managedBranch !== "missing" && recovery.managedBranch !== "unknown") ||
+        (recovery.targetBranch !== "present" && recovery.targetBranch !== "missing" && recovery.targetBranch !== "unknown") ||
+        (recovery.backingBranch !== "matching" && recovery.backingBranch !== "mismatched" && recovery.backingBranch !== "unavailable"))
+        return undefined;
+    return {
+        classification: recovery.classification,
+        conditions: [...recovery.conditions],
+        backing: recovery.backing,
+        source: recovery.source,
+        gitRegistration: recovery.gitRegistration,
+        managedBranch: recovery.managedBranch,
+        targetBranch: recovery.targetBranch,
+        backingBranch: recovery.backingBranch,
+    };
+}
 export function safeTaskSummary(value) {
     if (!value || typeof value !== "object")
         return undefined;

package/dist/workspaces/relay/workspace-relay.js

@@ -7,7 +7,7 @@ import { RemoteMcpConnectionPool } from "./transport/remote-mcp-connection-pool.
 import { withFileLock } from "../../runtime/state/lock/file-lock.js";
 import { withRemoteServiceEndpoint } from "./transport/remote-transport.js";
 import { loadForgeRelayFiles, writeForgeRelayRemote, } from "../../runtime/config/user-config.js";
-import { assertRemoteToolSucceeded, stringField, copyStringField, copyBooleanField, copyNumberField, safeTaskSummary, toolResultText, remapToolResultWorkspaceId, replaceExactWorkspaceId, sanitizedRemoteError, errorMessage } from "./result-support.js";
+import { assertRemoteToolSucceeded, copyBooleanField, copyNumberField, copyStringField, errorMessage, remapToolResultWorkspaceId, replaceExactWorkspaceId, safeManagedWorktreeRecovery, safeTaskSummary, sanitizedRemoteError, stringField, toolResultText, } from "./result-support.js";
 export class RemoteWorkspaceRelay {
     routes = new Map();
     turnRoutes = new Map();
@@ -77,6 +77,9 @@ export class RemoteWorkspaceRelay {
         copyStringField(remoteInspection, projection, "lastUsedAt");
         copyNumberField(remoteInspection, projection, "idleMs");
         copyBooleanField(remoteInspection, projection, "rootValid");
+        const recovery = safeManagedWorktreeRecovery(remoteInspection.recovery);
+        if (recovery)
+            projection.recovery = recovery;
         const taskSummary = safeTaskSummary(remoteInspection.taskSummary);
         if (taskSummary)
             projection.taskSummary = taskSummary;

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)

package/dist/workspaces.js

@@ -316,6 +316,9 @@ export class WorkspaceRegistry {
     getWorkspace(workspaceId) {
         return this.sessions.getWorkspace(workspaceId);
     }
+    runManagedWorktreeRecovery(workspaceId, operation) {
+        return this.sessions.runManagedWorktreeRecovery(workspaceId, operation);
+    }
     fileToolRoots(workspace) {
         return this.context.fileToolRoots(workspace);
     }

package/docs/configuration.md

@@ -338,23 +338,30 @@ inventory is paginated (50 records by default, at most 100) and can filter by Wo
 ID, persisted status, derived state, mode, canonical root/source root, or stale-only
 state. Reading inventory does not refresh `lastUsedAt`. Persisted `status="active"`
 means the record has not been explicitly closed; the derived `state` distinguishes
-`active`, `stale`, `invalid`, and `closed`. A missing checkout or externally removed
-managed-worktree root can therefore remain diagnostically `status="active"` while
-appearing as `state="invalid"`. Canonical identity means ordinary same-target opens no
-longer accumulate duplicate inventory rows; `action="list"` remains the formal
-on-demand inventory path.
+`active`, `stale`, `invalid`, and `closed`. Active managed-worktree entries also expose
+a bounded `recovery` projection: ForgeRelay observes backing/source availability, the
+recorded managed and target branches, Git worktree registration, and the backing's
+current branch, then classifies the result as `healthy`, `recoverable`, or
+`manual-intervention`. A missing checkout or externally damaged managed worktree can
+therefore remain diagnostically `status="active"` while appearing as `state="invalid"`.
+This projection is observation only: inventory never runs `git worktree prune`, creates
+or removes worktrees/branches, or otherwise repairs Git state. Canonical identity means
+ordinary same-target opens no longer accumulate duplicate inventory rows;
+`action="list"` remains the formal on-demand inventory path.
 
 `open_workspace(action="inspect", workspaceId="...")` is the bounded read-only detail
 path for one known Workspace. It uses an explicit allowlist and never opens/resumes the
 target, changes conversation bindings or bootstrap-delivery records, refreshes
 `lastUsedAt`, or grants file/process/Git/Capability authority. Safe projections include
-ordinary/worktree lifecycle metadata, Composite member availability summaries, Relay
-alias/execution-location presentation metadata, and an already-existing Task List
-summary. Inspection never returns AGENTS/CLAUDE contents, Skills, Capability-guide
-paths or contents, Subagent bodies/sessions, files, Git diffs, process/Activity output,
-Hook/review artifacts, credentials, network/SSH routes, or Task bodies. Relay inspection
-reports only that the Gateway route is known; it does not probe or claim the remote
-Workspace lifecycle state.
+ordinary/worktree lifecycle metadata, managed-worktree recovery observations,
+Composite member availability summaries, Relay alias/execution-location presentation
+metadata, and an already-existing Task List summary. Inspection never returns
+AGENTS/CLAUDE contents, Skills, Capability-guide paths or contents, Subagent
+bodies/sessions, files, Git diffs, process/Activity output, Hook/review artifacts,
+credentials, network/SSH routes, or Task bodies. For Relay Workspaces the Gateway asks
+the Execution ForgeRelay for this same bounded inspection and forwards sanitized
+lifecycle/recovery facts under the Gateway Workspace identity; the Gateway does not
+inspect or mutate the remote Git repository itself.
 
 For checkout-backed Workspaces, `close_workspace` defaults to `action="close"`:
 it marks the persistent Workspace closed, removes current conversation bindings, and

package/docs/roadmap.md

@@ -38,7 +38,7 @@ ForgeRelay does not plan to add:
 - a plugin marketplace/runtime;
 - a second conversation/session runtime;
 - host-owned commands such as plan mode, context inspection, or model selection;
-- automatic installation and management of language servers.
+- automatic or unapproved language-server installation. Agent-managed TypeScript/JavaScript and Pyright installs require explicit user opt-in and remain disabled by default; Rust Analyzer, `gopls`, and `clangd` stay external toolchain/system dependencies.
 
 Shell execution remains a trusted local-user capability. Workspace filesystem
 containment must not be described as a shell sandbox.
@@ -197,11 +197,12 @@ capability
 
 ## 0.4 — LSP code intelligence v1
 
-LSP is moderate implementation complexity if ForgeRelay does not become a
-language-server installer.
-
-The first version should launch only language servers already available on the
-user's machine or explicitly configured by the user/project.
+LSP v1 was designed around language servers already available on the user's machine
+or explicitly configured by the user/project. ForgeRelay later added a narrow managed
+installation path for TypeScript/JavaScript and Pyright: it is disabled by default,
+requires explicit user authorization during setup, installs only into ForgeRelay's
+private config directory, and refreshes live without a server restart. This does not
+turn arbitrary language-server installation into an implicit Agent capability.
 
 During 0.4 development, MCP App UI hardening can land alongside the LSP work when
 it does not distort the code-intelligence scope. In particular, evaluate a more
@@ -245,9 +246,10 @@ and verify publication before work begins on the next boundary:
 The shipping 0.4 LSP v1 contract keeps the canonical nine Core MCP tools unchanged
 and exposes semantic operations only through `code.intelligence`. Deterministic
 fake-LSP coverage remains the primary cross-platform protocol/lifecycle gate, while
-`npm run lsp:interop` exercises `typescript-language-server`, Pyright,
-`rust-analyzer`, `gopls`, and `clangd` only when those external executables are
-already present and otherwise reports explicit skips without installing them.
+`npm run lsp:interop` exercises detected servers only when executables are already
+present and never downloads them. The later managed TypeScript/Pyright installation
+path is a separate explicitly authorized runtime capability and does not change that
+interop-test contract.
 
 ## 0.5 — Durable Activity and batch execution
 
@@ -315,32 +317,40 @@ milestone: the next stage remains blocked until the previous version's tag-trigg
 release workflow has completed successfully. Runtime acceptance uses only the
 reserved 7677/7678 debug instances and never touches the normal 7676 installation.
 
-## Later: first-class subagent MCP
-
-ForgeRelay already owns provider adapters and resumable local agent sessions. A
-future release may remove the current `bash -> forgerelay agents ...` indirection
-for MCP hosts.
-
-First-class subagent operations should reuse the Capability Gateway rather than
-add another top-level MCP tool. The parent agent should continue choosing from
-available provider/profile metadata while ForgeRelay owns provider-backed worker
-lifecycle state. This remains provider-backed delegation, not an attempt to
-emulate a Host-native subagent implementation.
-
-## Worktree and history refinements
-
-These can land alongside the main release lines when the underlying interfaces
-are ready:
-
-- `.worktreeinclude`-style explicit copying of selected gitignored files;
-- hook-backed worktree close verification;
-- stale managed-worktree recovery and cleanup;
-- checkpoint/list/restore primitives based on the existing Git snapshot engine;
-- retention/GC for stale workspace sessions, conversation bindings, and review
-  refs.
-
-Checkpoint restore must protect concurrent/external user edits rather than
-blindly overwriting a working tree.
+## 0.9 — Workspace Recovery & History
+
+0.9 builds on persistent Workspace identity, first-class `subagent.session`, and the
+existing Hook-backed managed-worktree finalize lifecycle. It does not add another Core
+MCP tool. Each stage is release-gated: the following stage begins only after the prior
+version's tag-triggered Linux/macOS/Windows verification and publication succeed.
+
+- **0.9.0** — add bounded read-only managed-worktree recovery observations to
+  `open_workspace(action="list"|"inspect")`, distinguishing healthy, recoverable,
+  and manual-intervention states without repairing or pruning Git state; align current
+  Roadmap/product documentation with already-shipped Subagent, worktree verification,
+  and explicitly authorized managed-LSP behavior;
+- **0.9.1** — add Workspace-scoped safe managed-worktree repair and cleanup through
+  the Capability Gateway. Recovery must preserve surviving managed-branch work and
+  refuse ambiguous ownership rather than guessing;
+- **0.9.2** — add persistent Workspace checkpoints with explicit create/list/inspect/
+  delete lifecycle, stored outside normal project history and surviving Workspace
+  close/reopen;
+- **0.9.3** — add checkpoint restore with optimistic-concurrency preflight so external
+  or user edits made after inspection cannot be silently overwritten. Restore changes
+  working-tree content without moving branch HEAD or using `git reset --hard`;
+- **0.9.4** — add owner-facing retention inspection and explicitly authorized prune
+  through the CLI. Audit retention remains unlimited by default, persistent Workspace
+  identity/Tasks are not ordinary GC targets, and destructive global maintenance is
+  not exposed as an ordinary Agent MCP Capability.
+
+Workspace Relay continues to treat the Execution ForgeRelay as the owner of Git,
+recovery, checkpoint, and retention facts; the Gateway only routes and presents bounded
+results. Development acceptance remains on isolated 7677/7678 instances and never uses
+the normal 7676 installation.
+
+Later refinements may add `.worktreeinclude`-style explicit copying of selected
+Git-ignored files. Native PowerShell/`cmd.exe` shell execution is also a separate
+compatibility decision rather than part of the 0.9 recovery/history line.
 
 ## Workspace Task Lists
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.8.10",
+  "version": "0.9.1",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",
@@ -52,7 +52,7 @@
     "release:push-ready": "node scripts/release/push-ready.mjs",
     "postinstall": "node scripts/fix-node-pty-permissions.mjs",
     "start": "node dist/cli.js serve",
-    "test": "node --test scripts/debug/runtime.test.mjs scripts/release-proof.test.mjs scripts/release/release-gate.test.mjs scripts/release/push-ready.test.mjs scripts/release/release-version.test.mjs && tsx src/mcp/oauth/router.test.ts && tsx src/workspaces/relay/auth/remote-auth-cli.test.ts && tsx src/workspaces/relay/auth/remote-ssh-auth-cli.test.ts && tsx src/workspaces/relay/tests/lifecycle.test.ts && tsx src/workspaces/relay/tests/routing.test.ts && tsx src/workspaces/relay/tests/ssh.test.ts && tsx src/workspaces/relay/tests/process.test.ts && tsx src/runtime/config/config.test.ts && tsx src/lsp/language-server-config.test.ts && tsx src/lsp/runtime/managed-language-servers.test.ts && tsx src/lsp/normalization/hover.test.ts && tsx src/lsp/references.server.test.ts && tsx src/lsp/operations/document-symbols.server.test.ts && tsx src/lsp/operations/workspace-symbols.server.test.ts && tsx src/lsp/operations/diagnostics-push.server.test.ts && tsx src/lsp/operations/diagnostics-pull.server.test.ts && tsx src/lsp/operations/request-hardening.server.test.ts && tsx src/lsp/operations/recovery.server.test.ts && tsx src/lsp/operations/lifecycle.server.test.ts && tsx src/lsp/runtime/semantic-requests.test.ts && tsx src/runtime/logging/logger.test.ts && tsx src/runtime/logging/proxy-trust.test.ts && tsx src/runtime/state/lock/file-lock.test.ts && tsx src/mcp/panel/mcp-app-template.test.ts && tsx src/mcp/hooks/hooks.test.ts && tsx src/mcp/server/core/capability-registry.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/mcp/request-meta.test.ts && tsx src/mcp/artifacts/incoming-artifacts.test.ts && tsx src/mcp/artifacts/artifact-download.test.ts && tsx src/ui/core/card-types.test.ts && tsx src/ui/activity/model.test.ts && tsx src/ui/activity/detail-card.test.ts && tsx src/ui/review/patch-display.test.ts && tsx src/ui/core/tool-display.test.ts && tsx src/mcp/filesystem/apply-patch.test.ts && tsx src/mcp/process/process-platform.test.ts && tsx src/mcp/process/process-sessions.test.ts && tsx src/mcp/server/transport/mcp-sessions.test.ts && tsx src/mcp/server/transport/server-shutdown.test.ts && tsx src/mcp/server/operations/mutation-diagnostics.test.ts && tsx src/subagents/providers/adapters/codex.test.ts && tsx src/subagents/providers/adapters/pi.test.ts && tsx src/subagents/providers/registry.test.ts && tsx src/subagents/providers/availability.test.ts && tsx src/subagents/profiles.test.ts && tsx src/subagents/cli-target.test.ts && tsx src/subagents/sessions/store.test.ts && tsx src/subagents/sessions/manager.test.ts && tsx src/subagents/sessions/mcp/capability.server.test.ts && tsx src/subagents/sessions/mcp/continuation.server.test.ts && tsx src/subagents/sessions/mcp/lifecycle.server.test.ts && tsx src/subagents/sessions/mcp/reconciliation.server.test.ts && tsx src/subagents/sessions/mcp/routing.server.test.ts && tsx src/mcp/filesystem/roots.test.ts && tsx src/mcp/filesystem/file-mutations.test.ts && tsx src/mcp/operations/edit-preflight.test.ts && tsx src/workspaces/resources/skills.test.ts && tsx src/runtime/state/db/migrations.test.ts && tsx src/workspaces/state/workspace-store.test.ts && tsx src/workspaces/tasks/workspace-tasks.test.ts && tsx src/workspaces/tasks/workspace-task-reminders.test.ts && tsx src/activity/history/audit-store.test.ts && tsx src/activity/history/bash-output-store.test.ts && tsx src/activity/runtime/lifecycle.test.ts && tsx src/activity/history/query-service.test.ts && tsx src/mcp/operations/core-operation-executor.test.ts && tsx src/mcp/operations/bulk-mutation.test.ts && tsx src/mcp/operations/batch/scheduler.test.ts && tsx src/mcp/operations/batch/executor-policy.test.ts && tsx src/workspaces.test.ts && tsx src/workspaces/conversation-checkout.test.ts && tsx src/workspaces/conversation-worktree.test.ts && tsx src/workspaces/review/review-checkpoints.test.ts && tsx src/lsp/code-intelligence.server.test.ts && npm run build:app && tsx src/mcp/process/server.test.ts && tsx src/mcp/panel/server.test.ts && tsx src/mcp/server/server.test.ts && tsx src/mcp/oauth/oauth-store.test.ts && tsx src/cli/cli.test.ts",
+    "test": "node --test scripts/debug/runtime.test.mjs scripts/release-proof.test.mjs scripts/release/release-gate.test.mjs scripts/release/push-ready.test.mjs scripts/release/release-version.test.mjs && tsx src/mcp/oauth/router.test.ts && tsx src/workspaces/relay/auth/remote-auth-cli.test.ts && tsx src/workspaces/relay/auth/remote-ssh-auth-cli.test.ts && tsx src/workspaces/relay/tests/lifecycle.test.ts && tsx src/workspaces/relay/tests/routing.test.ts && tsx src/workspaces/relay/tests/ssh.test.ts && tsx src/workspaces/relay/tests/process.test.ts && tsx src/workspaces/relay/tests/recovery.test.ts && tsx src/runtime/config/config.test.ts && tsx src/lsp/language-server-config.test.ts && tsx src/lsp/runtime/managed-language-servers.test.ts && tsx src/lsp/normalization/hover.test.ts && tsx src/lsp/references.server.test.ts && tsx src/lsp/operations/document-symbols.server.test.ts && tsx src/lsp/operations/workspace-symbols.server.test.ts && tsx src/lsp/operations/diagnostics-push.server.test.ts && tsx src/lsp/operations/diagnostics-pull.server.test.ts && tsx src/lsp/operations/request-hardening.server.test.ts && tsx src/lsp/operations/recovery.server.test.ts && tsx src/lsp/operations/lifecycle.server.test.ts && tsx src/lsp/runtime/semantic-requests.test.ts && tsx src/runtime/logging/logger.test.ts && tsx src/runtime/logging/proxy-trust.test.ts && tsx src/runtime/state/lock/file-lock.test.ts && tsx src/mcp/panel/mcp-app-template.test.ts && tsx src/mcp/hooks/hooks.test.ts && tsx src/mcp/server/core/capability-registry.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/mcp/request-meta.test.ts && tsx src/mcp/artifacts/incoming-artifacts.test.ts && tsx src/mcp/artifacts/artifact-download.test.ts && tsx src/ui/core/card-types.test.ts && tsx src/ui/activity/model.test.ts && tsx src/ui/activity/detail-card.test.ts && tsx src/ui/review/patch-display.test.ts && tsx src/ui/core/tool-display.test.ts && tsx src/mcp/filesystem/apply-patch.test.ts && tsx src/mcp/process/process-platform.test.ts && tsx src/mcp/process/process-sessions.test.ts && tsx src/mcp/server/transport/mcp-sessions.test.ts && tsx src/mcp/server/transport/server-shutdown.test.ts && tsx src/mcp/server/operations/mutation-diagnostics.test.ts && tsx src/subagents/providers/adapters/codex.test.ts && tsx src/subagents/providers/adapters/pi.test.ts && tsx src/subagents/providers/registry.test.ts && tsx src/subagents/providers/availability.test.ts && tsx src/subagents/profiles.test.ts && tsx src/subagents/cli-target.test.ts && tsx src/subagents/sessions/store.test.ts && tsx src/subagents/sessions/manager.test.ts && tsx src/subagents/sessions/mcp/capability.server.test.ts && tsx src/subagents/sessions/mcp/continuation.server.test.ts && tsx src/subagents/sessions/mcp/lifecycle.server.test.ts && tsx src/subagents/sessions/mcp/reconciliation.server.test.ts && tsx src/subagents/sessions/mcp/routing.server.test.ts && tsx src/mcp/filesystem/roots.test.ts && tsx src/mcp/filesystem/file-mutations.test.ts && tsx src/mcp/operations/edit-preflight.test.ts && tsx src/workspaces/resources/skills.test.ts && tsx src/runtime/state/db/migrations.test.ts && tsx src/workspaces/state/workspace-store.test.ts && tsx src/workspaces/tasks/workspace-tasks.test.ts && tsx src/workspaces/tasks/workspace-task-reminders.test.ts && tsx src/activity/history/audit-store.test.ts && tsx src/activity/history/bash-output-store.test.ts && tsx src/activity/runtime/lifecycle.test.ts && tsx src/activity/history/query-service.test.ts && tsx src/mcp/operations/core-operation-executor.test.ts && tsx src/mcp/operations/bulk-mutation.test.ts && tsx src/mcp/operations/batch/scheduler.test.ts && tsx src/mcp/operations/batch/executor-policy.test.ts && tsx src/workspaces.test.ts && tsx src/workspaces/conversation-checkout.test.ts && tsx src/workspaces/conversation-worktree.test.ts && tsx src/workspaces/git/worktree-recovery.test.ts && tsx src/mcp/server/workspace/workspace-inventory.test.ts && tsx src/mcp/server/workspace/workspace-recovery.test.ts && tsx src/workspaces/review/review-checkpoints.test.ts && tsx src/lsp/code-intelligence.server.test.ts && npm run build:app && tsx src/mcp/process/server.test.ts && tsx src/mcp/panel/server.test.ts && tsx src/mcp/server/server.test.ts && tsx src/mcp/oauth/oauth-store.test.ts && tsx src/cli/cli.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "release:check": "node scripts/release-version.mjs check",
     "release:tag-check": "node scripts/release-version.mjs tag",