@akira-tl/forgerelay 0.8.1 → 0.8.2

package/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.8.2] - 2026-08-31
+
+### Changed
+
+- Managed-worktree Workspace close now preserves the same identity for later reopen with fresh backing; explicit delete safely finalizes active work before removing ForgeRelay-owned state.
+- Composite Workspace close now preserves identity and member topology for later reopen; explicit delete dissolves only the Composite relationship and leaves member Workspaces untouched.
+
 ## [0.8.1] - 2026-08-30
 
 ### Added

package/README.md

@@ -136,8 +136,10 @@ ForgeRelay does not merge member filesystems, Git state, Hooks, Skills, processe
 or audit facts, and it never infers a member from the tool type or purpose text.
 The Composite Activity Panel presents member operations in one Host Turn while the
 actual facts remain owned by the member Workspace. `close_workspace` on a Composite
-Workspace means **dissolve**: the Composite identity and membership are removed, but
-member Workspaces, worktrees, running jobs, files, and relay routes are preserved.
+Workspace now preserves the Composite identity and member topology as `closed`; a
+later `open_workspace` restores the same `cws_...` identity. `action="delete"` is the
+explicit dissolve operation. Neither close nor delete closes member Workspaces,
+finalizes their worktrees, stops their jobs, changes their files, or removes relay routes.
 
 ### Progressive MCP context
 

package/dist/composite-activity.js

@@ -12,7 +12,7 @@ export class CompositeActivityCoordinator {
         return this.composites.has(workspaceId);
     }
     beginPanel(workspaceId, conversationScopeId) {
-        this.composites.open(workspaceId);
+        this.composites.touchActive(workspaceId);
         const snapshot = this.queries.beginTurn(conversationScopeId, workspaceId);
         this.turns.set(snapshot.turnId, {
             compositeWorkspaceId: workspaceId,

package/dist/composite-workspaces.js

@@ -13,16 +13,20 @@ export class CompositeWorkspaceRegistry {
     has(workspaceId) {
         return this.records.has(workspaceId);
     }
+    isActive(workspaceId) {
+        return this.records.get(workspaceId)?.status === "active";
+    }
     create(name) {
         const normalized = normalizeName(name);
         const existing = [...this.records.values()].find((record) => record.name === normalized);
         if (existing)
-            return this.touch(existing.id);
+            return this.open(existing.id);
         const now = new Date().toISOString();
         const record = {
             id: `cws_${randomBytes(5).toString("hex")}`,
             kind: "composite",
             name: normalized,
+            status: "active",
             members: [],
             createdAt: now,
             lastUsedAt: now,
@@ -38,7 +42,17 @@ export class CompositeWorkspaceRegistry {
         return cloneRecord(record);
     }
     open(workspaceId) {
-        return this.touch(workspaceId);
+        const record = this.requireRecord(workspaceId);
+        record.status = "active";
+        return this.touchRecord(record);
+    }
+    close(workspaceId) {
+        const record = this.requireActive(workspaceId);
+        record.status = "closed";
+        return this.touchRecord(record);
+    }
+    touchActive(workspaceId) {
+        return this.touchRecord(this.requireActive(workspaceId));
     }
     list() {
         return [...this.records.values()]
@@ -46,7 +60,7 @@ export class CompositeWorkspaceRegistry {
             .sort((left, right) => right.lastUsedAt.localeCompare(left.lastUsedAt));
     }
     addMember(workspaceId, input) {
-        const record = this.requireRecord(workspaceId);
+        const record = this.requireActive(workspaceId);
         const name = normalizeMemberName(input.name);
         const purpose = input.purpose.trim();
         if (!purpose)
@@ -64,7 +78,7 @@ export class CompositeWorkspaceRegistry {
         return cloneRecord(record);
     }
     updateMember(workspaceId, memberName, input) {
-        const record = this.requireRecord(workspaceId);
+        const record = this.requireActive(workspaceId);
         const currentName = normalizeMemberName(memberName);
         const index = record.members.findIndex((member) => member.name === currentName);
         if (index < 0)
@@ -94,7 +108,7 @@ export class CompositeWorkspaceRegistry {
         return cloneRecord(record);
     }
     removeMember(workspaceId, memberName) {
-        const record = this.requireRecord(workspaceId);
+        const record = this.requireActive(workspaceId);
         const name = normalizeMemberName(memberName);
         const index = record.members.findIndex((member) => member.name === name);
         if (index < 0)
@@ -105,7 +119,7 @@ export class CompositeWorkspaceRegistry {
         return cloneRecord(record);
     }
     member(workspaceId, memberName) {
-        const record = this.requireRecord(workspaceId);
+        const record = this.requireActive(workspaceId);
         const name = normalizeMemberName(memberName);
         const member = record.members.find((entry) => entry.name === name);
         if (!member)
@@ -118,12 +132,18 @@ export class CompositeWorkspaceRegistry {
         this.persist();
         return cloneRecord(record);
     }
-    touch(workspaceId) {
-        const record = this.requireRecord(workspaceId);
+    touchRecord(record) {
         record.lastUsedAt = new Date().toISOString();
         this.persist();
         return cloneRecord(record);
     }
+    requireActive(workspaceId) {
+        const record = this.requireRecord(workspaceId);
+        if (record.status !== "active") {
+            throw new Error(`Composite Workspace ${workspaceId} is closed. Reopen it with open_workspace before use.`);
+        }
+        return record;
+    }
     requireRecord(workspaceId) {
         const record = this.records.get(workspaceId);
         if (!record)
@@ -140,7 +160,7 @@ export class CompositeWorkspaceRegistry {
                 return;
             throw new Error(`Failed to load Composite Workspace state: ${errorMessage(error)}`);
         }
-        if (parsed?.version !== 1 || !Array.isArray(parsed.workspaces)) {
+        if ((parsed?.version !== 1 && parsed?.version !== 2) || !Array.isArray(parsed.workspaces)) {
             throw new Error("Composite Workspace state has an unsupported format.");
         }
         for (const record of parsed.workspaces) {
@@ -148,6 +168,7 @@ export class CompositeWorkspaceRegistry {
                 continue;
             this.records.set(record.id, {
                 ...record,
+                status: record.status === "closed" ? "closed" : "active",
                 members: Array.isArray(record.members) ? record.members.map((member) => ({ ...member })) : [],
             });
         }
@@ -155,7 +176,7 @@ export class CompositeWorkspaceRegistry {
     persist() {
         mkdirSync(this.stateDir, { recursive: true });
         const state = {
-            version: 1,
+            version: 2,
             workspaces: [...this.records.values()].map(cloneRecord),
         };
         const tempPath = `${this.statePath}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;

package/dist/git-worktrees.js

@@ -57,6 +57,28 @@ export async function createManagedWorktree(input) {
         managed: true,
     };
 }
+export async function discardFreshManagedWorktree(input) {
+    const sourceRoot = assertAllowedPath(input.worktree.sourceRoot, input.config.allowedRoots);
+    const worktreePath = assertAllowedPath(input.worktree.path, [input.config.worktreeRoot]);
+    const worktreeBranch = await currentBranch(worktreePath);
+    if (worktreeBranch !== input.worktree.branch) {
+        throw new GitWorktreeError("GIT_WORKTREE_CLOSE_FAILED", `Cannot roll back reopened worktree because it is on branch ${JSON.stringify(worktreeBranch)} instead of ${JSON.stringify(input.worktree.branch)}.`);
+    }
+    if ((await git(["status", "--porcelain=v1"], worktreePath)).trim().length > 0) {
+        throw new GitWorktreeError("GIT_WORKTREE_CLOSE_FAILED", "Cannot roll back reopened worktree because it acquired uncommitted changes during reopen.");
+    }
+    const worktreeHead = (await git(["rev-parse", "HEAD"], worktreePath)).trim();
+    if (worktreeHead !== input.worktree.baseSha) {
+        throw new GitWorktreeError("GIT_WORKTREE_CLOSE_FAILED", "Cannot roll back reopened worktree because its branch advanced during reopen.");
+    }
+    try {
+        await git(["worktree", "remove", worktreePath], sourceRoot);
+        await git(["branch", "-D", input.worktree.branch], sourceRoot);
+    }
+    catch (error) {
+        throw new GitWorktreeError("GIT_WORKTREE_CLOSE_FAILED", `Git failed to remove the temporary managed worktree created for a failed reopen. ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
 export async function closeManagedWorktree(input) {
     const sourceRoot = assertAllowedPath(input.worktree.sourceRoot, input.config.allowedRoots);
     const worktreePath = assertAllowedPath(input.worktree.path, [input.config.worktreeRoot]);

package/dist/mcp/server-instructions.js

@@ -38,7 +38,7 @@ function capabilityContractInstructions(config) {
     const staleWorkspacePolicy = config.toolMode === "codex"
         ? ""
         : ` If ${toolNames.openWorkspace} reports stale workspaces, let the user choose resume or ${toolNames.closeWorkspace}; never auto-close.`;
-    const workspaceLifecycle = `Use ForgeRelay as a local coding workspace. Default to the user's existing checkout. Reuse workspaceId from ${toolNames.openWorkspace}; change it only when asked.${staleWorkspacePolicy} Only open mode=\"worktree\" when the user explicitly asks for isolated or parallel Git work. ${toolNames.closeWorkspace} defaults to closing checkout Workspaces for later reopen; action=delete removes only ForgeRelay-owned checkout state, never project files. Managed close finalizes the worktree and requires commitMessage.`;
+    const workspaceLifecycle = `Default to the user's existing checkout. Reuse workspaceId from ${toolNames.openWorkspace}; change it only when asked.${staleWorkspacePolicy} Only open mode=\"worktree\" when the user explicitly asks for isolated or parallel Git work. ${toolNames.closeWorkspace} preserves Workspace identity. Managed close finalizes backing and needs commitMessage. Composite close preserves members; delete removes only Composite state. Active worktree delete still finalizes safely; checkout files are never deleted.`;
     const activityPanel = `Project-work order: ${toolNames.openWorkspace} if needed → activity_panel(workspaceId) once → work tools. activity_panel is the single ForgeRelay UI render tool: Workspace above Activity. A new workspaceId creates a new card. Never call activity_panel before needed ${toolNames.openWorkspace}.`;
     const agents = `Follow instructions returned by ${toolNames.openWorkspace}. Read an availableAgentsFiles path before working under it.`;
     const capabilityGuides = `For optional capabilities from ${toolNames.openWorkspace}, use ${toolNames.capability}; if unfamiliar, describe first and read its advertised capability guide with ${toolNames.read}.`;

package/dist/server.js

@@ -2078,6 +2078,8 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             memberAction: z.enum(["add", "update", "remove"]).optional(),
             kind: z.enum(["workspace", "composite"]).optional(),
             name: z.string().optional(),
+            status: z.string().optional(),
+            state: z.enum(["active", "stale", "invalid", "closed"]).optional(),
             members: z.array(z.object({
                 name: z.string(),
                 purpose: z.string(),
@@ -2134,6 +2136,8 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 workspaceId: z.string(),
                 kind: z.literal("composite"),
                 name: z.string(),
+                status: z.enum(["active", "closed"]),
+                state: z.enum(["active", "closed"]),
                 members: z.array(z.object({
                     name: z.string(),
                     purpose: z.string(),
@@ -2161,6 +2165,9 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             if (!workspaceId || !compositeWorkspaces.has(workspaceId)) {
                 throw new Error("open_workspace action=member requires an existing Composite Workspace workspaceId.");
             }
+            if (!compositeWorkspaces.isActive(workspaceId)) {
+                throw new Error(`Composite Workspace ${workspaceId} is closed. Reopen it with open_workspace before changing members.`);
+            }
             if (!memberAction || !member) {
                 throw new Error("open_workspace action=member requires memberAction and member.");
             }
@@ -2294,25 +2301,30 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 newWorkspace !== undefined || context !== undefined) {
                 throw new Error("open_workspace action=list does not accept path, relay, name, memberName, baseRef, newWorktree, newWorkspace, or context. Use kind/root/workspaceId/mode/status/state/staleOnly for inventory filters.");
             }
+            const compositeInventory = () => compositeWorkspaces.list()
+                .filter((entry) => workspaceId === undefined || entry.id === workspaceId)
+                .filter((entry) => status === undefined || entry.status === status)
+                .filter((entry) => state === undefined || entry.status === state)
+                .map((entry) => ({
+                workspaceId: entry.id,
+                kind: entry.kind,
+                name: entry.name,
+                status: entry.status,
+                state: entry.status,
+                members: entry.members,
+                createdAt: entry.createdAt,
+                lastUsedAt: entry.lastUsedAt,
+            }));
             if (kind === "composite") {
-                if (root !== undefined || mode !== undefined || status !== undefined || state !== undefined ||
-                    staleOnly !== undefined || offset !== undefined || limit !== undefined) {
-                    throw new Error("Composite Workspace inventory does not accept root/mode/status/state/staleOnly/offset/limit filters; use workspaceId when selecting one Composite Workspace.");
+                if (root !== undefined || mode !== undefined || staleOnly !== undefined ||
+                    offset !== undefined || limit !== undefined) {
+                    throw new Error("Composite Workspace inventory does not accept root/mode/staleOnly/offset/limit filters; use workspaceId/status/state when selecting Composite Workspaces.");
                 }
-                const composites = compositeWorkspaces.list()
-                    .filter((entry) => workspaceId === undefined || entry.id === workspaceId)
-                    .map((entry) => ({
-                    workspaceId: entry.id,
-                    kind: entry.kind,
-                    name: entry.name,
-                    members: entry.members,
-                    createdAt: entry.createdAt,
-                    lastUsedAt: entry.lastUsedAt,
-                }));
-                const instruction = "Resume a Composite Workspace with open_workspace(action=\"open\", workspaceId=...). Use close_workspace only when the user chooses to dissolve it.";
+                const composites = compositeInventory();
+                const instruction = "Open a Composite Workspace by workspaceId to resume or reopen it. close_workspace preserves its identity; action=delete permanently dissolves only Composite-owned state.";
                 const result = [
                     `Composite Workspace inventory: ${composites.length} matching record${composites.length === 1 ? "" : "s"}.`,
-                    ...composites.map((entry) => `${entry.name} [${entry.workspaceId}] members=${entry.members.length} last-used=${entry.lastUsedAt}`),
+                    ...composites.map((entry) => `${entry.name} [${entry.workspaceId}] state=${entry.state} members=${entry.members.length} last-used=${entry.lastUsedAt}`),
                     instruction,
                 ].join("\n");
                 return {
@@ -2325,20 +2337,13 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 };
             }
             const inventory = await workspaces.listWorkspaces({ workspaceId, mode, root, status, state, staleOnly, offset, limit }, { conversationScopeId, protectedWorkspaceIds });
-            const composites = kind === "workspace"
+            const composites = kind === "workspace" || root !== undefined || mode !== undefined || staleOnly
                 ? []
-                : compositeWorkspaces.list().map((entry) => ({
-                    workspaceId: entry.id,
-                    kind: entry.kind,
-                    name: entry.name,
-                    members: entry.members,
-                    createdAt: entry.createdAt,
-                    lastUsedAt: entry.lastUsedAt,
-                }));
+                : compositeInventory();
             const nextOffset = inventory.page.offset + inventory.page.limit;
             const instruction = [
                 "Resume a selected workspaceId with open_workspace(action=\"open\", workspaceId=...).",
-                "Use close_workspace only after the user chooses cleanup or Composite dissolution; never close inventory entries automatically.",
+                "Use close_workspace only after the user chooses cleanup; Composite close preserves identity, while action=delete dissolves only Composite-owned state. Never close inventory entries automatically.",
                 inventory.page.hasMore
                     ? `More matching workspaces are available; continue with offset=${nextOffset}.`
                     : undefined,
@@ -2356,7 +2361,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     `root=${entry.root}`,
                     `last-used=${entry.lastUsedAt}`,
                 ].filter(Boolean).join(" ")),
-                ...composites.map((entry) => `${entry.name} [${entry.workspaceId}] kind=composite members=${entry.members.length}`),
+                ...composites.map((entry) => `${entry.name} [${entry.workspaceId}] kind=composite state=${entry.state} members=${entry.members.length}`),
                 instruction,
             ].join("\n");
             logToolCall(config, {
@@ -2406,7 +2411,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 composite.members.length > 0
                     ? "Before first work on a member, reopen this Composite Workspace with memberName=<member> and context=auto to receive that member's project bootstrap without creating an implicit current member."
                     : undefined,
-                "Use close_workspace only when the user chooses to dissolve this Composite Workspace; dissolution does not close or clean up member Workspaces.",
+                "close_workspace preserves this Composite identity for later reopen. Use action=delete only when the user explicitly wants to dissolve the Composite relationship; neither operation closes or cleans up member Workspaces.",
             ].join("\n\n");
             const response = {
                 content: [textBlock(instruction)],
@@ -2419,7 +2424,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                         path: composite.name,
                         members: composite.members,
                         instruction,
-                        summary: { members: composite.members.length },
+                        summary: { members: composite.members.length, status: composite.status },
                     },
                 },
                 structuredContent: {
@@ -2427,6 +2432,8 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     workspaceId: composite.id,
                     kind: "composite",
                     name: composite.name,
+                    status: composite.status,
+                    state: composite.status,
                     members: composite.members,
                     ...(memberContext ? { memberContext } : {}),
                     instruction,
@@ -2921,13 +2928,13 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
     });
     registerAppTool(server, toolNames.closeWorkspace, {
         title: "Close workspace",
-        description: "Close or explicitly delete one Workspace after the user chooses cleanup. action=close (default) preserves checkout identity for later reopen. action=delete permanently removes ForgeRelay-owned checkout state but never project files. Managed-worktree-backed Workspaces still use the safe finalize lifecycle and require commitMessage; Composite and relayed delete semantics are not available in this stage.",
+        description: "Close or explicitly delete one Workspace after the user chooses cleanup. action=close (default) preserves checkout, managed-worktree, and Composite identity for later reopen. action=delete permanently removes ForgeRelay-owned state. Managed-worktree-backed Workspaces still finalize safely when active and require commitMessage. Composite delete dissolves only Composite-owned state and never closes member Workspaces. Checkout project files are never deleted; relayed delete remains unavailable.",
         inputSchema: {
             workspaceId: z.string().describe("Workspace identifier to close or delete."),
             action: z
                 .enum(["close", "delete"])
                 .optional()
-                .describe("Defaults to close. close preserves checkout identity for later reopen; delete permanently removes ForgeRelay-owned checkout state without deleting project files."),
+                .describe("Defaults to close. close preserves checkout identity, managed-worktree identity, and Composite identity for later reopen; delete removes ForgeRelay-owned state. Composite delete dissolves only the Composite relationship. Active managed worktrees still require safe finalization and commitMessage; checkout project files are never deleted."),
             commitMessage: z
                 .string()
                 .min(1)
@@ -2945,6 +2952,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 purpose: z.string(),
                 workspaceId: z.string(),
             })).optional(),
+            status: z.enum(["active", "closed"]).optional(),
             dissolved: z.boolean().optional(),
             sourceRoot: z.string().optional(),
             branch: z.string().optional(),
@@ -2958,21 +2966,22 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         annotations: WRITE_TOOL_ANNOTATIONS,
     }, async ({ workspaceId, action = "close", commitMessage }, extra) => {
         if (compositeWorkspaces.has(workspaceId)) {
-            if (action === "delete") {
-                throw new Error("close_workspace action=delete is not available for Composite Workspaces until the Composite persistent lifecycle stage.");
-            }
             if (commitMessage !== undefined) {
-                throw new Error("close_workspace commitMessage is not valid when dissolving a Composite Workspace.");
+                throw new Error("close_workspace commitMessage is not valid for a Composite Workspace.");
             }
-            const composite = compositeWorkspaces.dissolve(workspaceId);
+            const composite = action === "delete"
+                ? compositeWorkspaces.dissolve(workspaceId)
+                : compositeWorkspaces.close(workspaceId);
             compositeActivity.forgetComposite(workspaceId);
             workspacePanelStates.delete(workspaceId);
             const result = [
-                `Dissolved Composite Workspace ${composite.name} (${workspaceId}).`,
+                action === "delete"
+                    ? `Deleted Composite Workspace ${composite.name} (${workspaceId}); its Composite relationship and ForgeRelay-owned Composite state were dissolved.`
+                    : `Closed Composite Workspace ${composite.name} (${workspaceId}); its identity and member topology were preserved for later reopen.`,
                 composite.members.length > 0
                     ? `Preserved member Workspaces: ${composite.members.map((member) => `${member.name} [${member.workspaceId}]`).join(", ")}.`
                     : "The Composite Workspace had no members.",
-                "Member Workspace handles, managed worktrees, processes, files, and Workspace Relay routes were not closed or cleaned up.",
+                "Member Workspace handles, managed worktrees, processes, files, and Workspace Relay routes were not closed, finalized, deleted, or otherwise mutated.",
             ].join("\n");
             return {
                 content: [textBlock(result)],
@@ -2980,22 +2989,24 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     tool: toolNames.closeWorkspace,
                     card: {
                         workspaceId,
-                        action: "close",
+                        action,
                         kind: "composite",
                         name: composite.name,
                         members: composite.members,
-                        dissolved: true,
+                        ...(action === "close" ? { status: "closed" } : {}),
+                        dissolved: action === "delete",
                         payload: { content: [textBlock(result)] },
                     },
                 },
                 structuredContent: {
                     result,
                     workspaceId,
-                    action: "close",
+                    action,
                     kind: "composite",
                     name: composite.name,
                     members: composite.members,
-                    dissolved: true,
+                    ...(action === "close" ? { status: "closed" } : {}),
+                    dissolved: action === "delete",
                 },
             };
         }
@@ -3007,14 +3018,11 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             workspacePanelStates.delete(workspaceId);
             return response;
         }
-        if (action === "delete") {
+        const session = workspaces.getWorkspaceSession(workspaceId);
+        if (action === "delete" && session.mode === "checkout") {
             if (commitMessage !== undefined) {
                 throw new Error("close_workspace commitMessage is not valid with action=delete for a checkout Workspace.");
             }
-            const session = workspaces.getWorkspaceSession(workspaceId);
-            if (session.mode !== "checkout") {
-                throw new Error("close_workspace action=delete is not available for managed-worktree-backed Workspaces until their persistent lifecycle stage.");
-            }
             if (processSessions.activeWorkspaceIds().has(session.id)) {
                 throw new Error(`Workspace ${session.id} still owns a running process. Poll, interrupt, or wait for it before deleting this Workspace.`);
             }
@@ -3055,12 +3063,58 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             workspacePanelStates.delete(session.id);
             return response;
         }
-        const workspace = workspaces.getWorkspace(workspaceId);
+        if (action === "delete" && session.mode === "worktree" && session.status === "closed") {
+            if (commitMessage !== undefined) {
+                throw new Error("close_workspace commitMessage is not needed when deleting an already-closed managed-worktree Workspace.");
+            }
+            const hookRoot = session.sourceRoot ?? session.root;
+            const response = await runToolWithHooks(hooks, {
+                signal: extra.signal,
+                tool: toolNames.closeWorkspace,
+                invocation: {
+                    workspaceId: session.id,
+                    workspaceRoot: hookRoot,
+                    workspaceMode: session.mode,
+                    sourceRoot: session.sourceRoot,
+                },
+                payload: { workspaceId: session.id, action: "delete", mode: session.mode },
+                operation: async () => {
+                    workspaces.deleteWorkspace(session.id);
+                    await reviewCheckpoints.releaseWorkspace(session.id);
+                    const result = `Deleted closed managed-worktree Workspace ${session.id}. Its already-removed worktree backing was not recreated.`;
+                    return {
+                        content: [textBlock(result)],
+                        _meta: {
+                            tool: toolNames.closeWorkspace,
+                            card: {
+                                workspaceId: session.id,
+                                action: "delete",
+                                mode: "worktree",
+                                sourceRoot: session.sourceRoot,
+                                targetBranch: session.targetBranch,
+                                payload: { content: [textBlock(result)] },
+                            },
+                        },
+                        structuredContent: {
+                            result,
+                            workspaceId: session.id,
+                            action: "delete",
+                            mode: "worktree",
+                            sourceRoot: session.sourceRoot,
+                            targetBranch: session.targetBranch,
+                        },
+                    };
+                },
+            });
+            workspacePanelStates.delete(session.id);
+            return response;
+        }
+        const workspace = workspaces.getWorkspace(session.id);
         const response = await runToolWithHooks(hooks, {
             signal: extra.signal,
             tool: toolNames.closeWorkspace,
             invocation: workspaceHookInvocation(workspace),
-            payload: { workspaceId, action: "close", commitMessage, mode: workspace.mode },
+            payload: { workspaceId: workspace.id, action, commitMessage, mode: workspace.mode },
             afterCwd: (response) => "sourceRoot" in response.structuredContent &&
                 typeof response.structuredContent.sourceRoot === "string"
                 ? response.structuredContent.sourceRoot
@@ -3068,7 +3122,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             operation: async () => {
                 if (workspace.mode === "worktree") {
                     if (!commitMessage) {
-                        throw new Error(`Managed-worktree-backed workspace ${workspaceId} requires commitMessage when closing.`);
+                        throw new Error(`Managed-worktree-backed Workspace ${workspace.id} requires commitMessage when ${action === "delete" ? "deleting active work" : "closing"}.`);
                     }
                     const physicalWorkspaceIds = workspaces.workspaceIdsForPhysicalWorkspace(workspace);
                     const busyWorkspaceIds = physicalWorkspaceIds
@@ -3080,14 +3134,19 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     const retirement = await codeIntelligence.retireWorkspaceRoot(workspace.root);
                     let closed;
                     try {
-                        closed = await workspaces.closeWorktree(workspaceId, commitMessage);
+                        closed = await workspaces.closeWorktree(workspace.id, commitMessage);
                     }
                     finally {
                         codeIntelligence.restoreWorkspaceRoot(retirement.root);
                     }
                     await Promise.all(physicalWorkspaceIds.map((id) => reviewCheckpoints.releaseWorkspace(id)));
+                    if (action === "delete") {
+                        workspaces.deleteWorkspace(workspace.id);
+                    }
                     const result = [
-                        `Closed managed-worktree-backed workspace ${workspaceId}.`,
+                        action === "delete"
+                            ? `Safely finalized and deleted managed-worktree Workspace ${workspace.id}.`
+                            : `Closed managed-worktree-backed Workspace ${workspace.id}; its identity was preserved for later reopen.`,
                         `Merged ${closed.branch} into ${closed.targetBranch} by fast-forward.`,
                         `Source checkout: ${closed.sourceRoot}`,
                         `Commit: ${closed.commitSha}`,
@@ -3107,8 +3166,8 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                         _meta: {
                             tool: toolNames.closeWorkspace,
                             card: {
-                                workspaceId,
-                                action: "close",
+                                workspaceId: workspace.id,
+                                action,
                                 mode: "worktree",
                                 sourceRoot: closed.sourceRoot,
                                 branch: closed.branch,
@@ -3122,8 +3181,8 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                         },
                         structuredContent: {
                             result,
-                            workspaceId,
-                            action: "close",
+                            workspaceId: workspace.id,
+                            action,
                             mode: "worktree",
                             sourceRoot: closed.sourceRoot,
                             branch: closed.branch,

package/dist/workspace-store.js

@@ -90,6 +90,31 @@ export class SqliteWorkspaceStore {
             .where(eq(workspaceSessions.id, sessionId))
             .run();
     }
+    replaceWorktreeBacking(input) {
+        const sessionId = this.resolveSessionId(input.id);
+        if (!sessionId)
+            throw new Error(`Unknown workspace session: ${input.id}`);
+        this.pendingSessionTouches.delete(sessionId);
+        const row = this.database.db
+            .update(workspaceSessions)
+            .set({
+            root: input.root,
+            status: "active",
+            sourceRoot: input.sourceRoot,
+            baseRef: input.baseRef,
+            baseSha: input.baseSha,
+            branch: input.branch,
+            targetBranch: input.targetBranch,
+            managed: "true",
+            lastUsedAt: this.now().toISOString(),
+        })
+            .where(eq(workspaceSessions.id, sessionId))
+            .returning()
+            .get();
+        if (!row)
+            throw new Error(`Unknown workspace session: ${input.id}`);
+        return rowToWorkspaceSession(row);
+    }
     listSessions(input = {}) {
         const conditions = [
             input.status ? eq(workspaceSessions.status, input.status) : undefined,

package/dist/workspaces.js

@@ -5,7 +5,7 @@ import { tmpdir } from "node:os";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { loadCapabilityGuides, markCapabilityGuideActivated, resolveCapabilityGuideReadPath, } from "./capabilities.js";
 import { HookRunner } from "./hooks.js";
-import { closeManagedWorktree, createManagedWorktree, resolveManagedWorktreeBase, } from "./git-worktrees.js";
+import { closeManagedWorktree, createManagedWorktree, discardFreshManagedWorktree, resolveManagedWorktreeBase, } from "./git-worktrees.js";
 import { AccessDeniedError, assertAllowedPath, isPathInsideRoot, resolveAllowedPath, } from "./roots.js";
 import { loadWorkspaceSkills, markSkillActivated, resolveSkillReadPath, } from "./skills.js";
 import { loadSubagentProfiles, } from "./subagents/profiles.js";
@@ -152,8 +152,11 @@ export class WorkspaceRegistry {
         };
     }
     async resumeWorkspace(workspaceId, conversationScopeId, bootstrapContext = "auto") {
-        const workspace = this.workspaceForOpen(workspaceId);
-        const context = await this.reusedWorkspaceContext(workspace);
+        const session = this.store?.getSession(workspaceId);
+        const context = session?.status === "closed" && session.mode === "worktree"
+            ? await this.reopenClosedManagedWorktreeContext(session)
+            : await this.reusedWorkspaceContext(await this.workspaceForOpen(workspaceId));
+        const workspace = context.workspace;
         if (!conversationScopeId || !this.store) {
             return {
                 ...context,
@@ -222,8 +225,8 @@ export class WorkspaceRegistry {
     }
     deleteWorkspace(workspaceId) {
         const session = this.getWorkspaceSession(workspaceId);
-        if (session.mode !== "checkout") {
-            throw new Error(`Workspace ${session.id} is not a checkout Workspace. Delete semantics for ${session.mode} Workspaces are handled by their own lifecycle.`);
+        if (session.mode === "worktree" && session.status === "active") {
+            throw new Error(`Workspace ${session.id} is an active managed-worktree Workspace. Finalize it safely before deleting its persistent identity.`);
         }
         this.deleteConversationBindingsForWorkspace(session.id);
         this.store?.deleteSession(session.id);
@@ -327,6 +330,7 @@ export class WorkspaceRegistry {
             },
         }));
         for (const aliasedWorkspaceId of aliasedWorkspaceIds) {
+            this.deleteConversationBindingsForWorkspace(aliasedWorkspaceId);
             this.store?.setSessionStatus(aliasedWorkspaceId, "closed");
             this.workspaces.delete(aliasedWorkspaceId);
         }
@@ -386,10 +390,8 @@ export class WorkspaceRegistry {
         if (boundContext)
             return boundContext;
         const context = await this.openOnce(targetKey, async () => {
-            const reusableWorkspace = await this.findReusableWorktreeBySource(sourceKey, resolvedBase.targetBranch);
-            if (!reusableWorkspace)
-                return this.openWorktreeWorkspace(path, input.baseRef);
-            return this.reusedWorkspaceContext(reusableWorkspace);
+            const reusableContext = await this.findReusableWorktreeContextBySource(sourceKey, resolvedBase.targetBranch);
+            return reusableContext ?? this.openWorktreeWorkspace(path, input.baseRef);
         });
         return this.withConversationContext(context, conversationScopeId, targetKey, bootstrapContext);
     }
@@ -576,16 +578,30 @@ export class WorkspaceRegistry {
         }
         return undefined;
     }
-    async findReusableWorktreeBySource(sourceKey, targetBranch) {
-        for (const session of this.activeSessions("worktree")) {
+    async findReusableWorktreeContextBySource(sourceKey, targetBranch) {
+        const sessions = this.store
+            ? this.store.listSessions({ mode: "worktree" })
+            : this.activeSessions("worktree");
+        const closedMatches = [];
+        for (const session of sessions) {
             if (!session.sourceRoot || session.targetBranch !== targetBranch)
                 continue;
             if (await canonicalPath(session.sourceRoot) !== sourceKey)
                 continue;
+            if (session.status === "closed") {
+                if (session.managed)
+                    closedMatches.push(session);
+                continue;
+            }
+            if (session.status !== "active")
+                continue;
             const root = await this.validSessionRoot(session);
             if (!root)
                 continue;
-            return this.workspaceFromSession(session, false);
+            return this.reusedWorkspaceContext(this.workspaceFromSession(session, false));
+        }
+        if (closedMatches.length === 1) {
+            return this.reopenClosedManagedWorktreeContext(closedMatches[0]);
         }
         return undefined;
     }
@@ -654,7 +670,7 @@ export class WorkspaceRegistry {
             includeBootstrapContext: true,
         };
     }
-    workspaceForOpen(workspaceId) {
+    async workspaceForOpen(workspaceId) {
         const session = this.store?.getSession(workspaceId);
         if (session?.status === "closed" && session.mode === "checkout") {
             this.store?.setSessionStatus(session.id, "active");
@@ -666,6 +682,72 @@ export class WorkspaceRegistry {
         }
         return this.getWorkspace(workspaceId);
     }
+    async reopenClosedManagedWorktreeContext(session) {
+        const operationKey = JSON.stringify(["worktree-reopen", session.id]);
+        return this.openOnce(operationKey, async () => {
+            const current = this.store?.getSession(session.id);
+            if (!current) {
+                throw new Error(`Unknown workspaceId: ${session.id}. Call open_workspace first.`);
+            }
+            if (current.status === "active") {
+                return this.reusedWorkspaceContext(this.getWorkspace(current.id));
+            }
+            if (current.status !== "closed" || current.mode !== "worktree") {
+                throw new Error(`Workspace ${current.id} is not a closed managed-worktree Workspace.`);
+            }
+            return this.reopenClosedManagedWorktreeContextUnlocked(current);
+        });
+    }
+    async reopenClosedManagedWorktreeContextUnlocked(session) {
+        if (!this.store) {
+            throw new Error(`Workspace ${session.id} cannot be reopened without persistent Workspace state.`);
+        }
+        if (!session.managed || !session.sourceRoot || !session.targetBranch) {
+            throw new Error(`Workspace ${session.id} does not have enough managed-worktree metadata to recreate its execution backing.`);
+        }
+        const worktree = await createManagedWorktree({
+            sourcePath: session.sourceRoot,
+            baseRef: session.targetBranch,
+            config: this.config,
+        });
+        const candidateSession = {
+            ...session,
+            root: worktree.path,
+            status: "active",
+            sourceRoot: worktree.sourceRoot,
+            baseRef: worktree.baseRef,
+            baseSha: worktree.baseSha,
+            branch: worktree.branch,
+            targetBranch: worktree.targetBranch,
+            managed: true,
+        };
+        const workspace = this.workspaceFromSession(candidateSession, false);
+        try {
+            const context = await this.reusedWorkspaceContext(workspace);
+            this.store.replaceWorktreeBacking({
+                id: session.id,
+                root: worktree.path,
+                sourceRoot: worktree.sourceRoot,
+                baseRef: worktree.baseRef,
+                baseSha: worktree.baseSha,
+                branch: worktree.branch,
+                targetBranch: worktree.targetBranch,
+            });
+            return context;
+        }
+        catch (error) {
+            this.workspaces.delete(session.id);
+            try {
+                await discardFreshManagedWorktree({ worktree, config: this.config });
+            }
+            catch (cleanupError) {
+                const original = error instanceof Error ? error.message : String(error);
+                const cleanup = cleanupError instanceof Error ? cleanupError.message : String(cleanupError);
+                throw new Error(`${original} Reopen rollback also failed: ${cleanup}`);
+            }
+            throw error;
+        }
+    }
     getWorkspaceSession(workspaceId) {
         const session = this.store?.getSession(workspaceId);
         if (session)

package/docs/chatgpt-coding-workflow.md

@@ -139,6 +139,19 @@ If histories diverge, close is refused and the worktree is preserved. Rebase and
 verify inside the worktree, then retry. The source checkout is not intentionally
 placed into a merge-conflict state.
 
+A successful managed close now preserves the Workspace identity as `closed` even
+though the physical worktree and managed branch are removed. Reopen that Workspace
+with `open_workspace(workspaceId="ws_...")`; ForgeRelay creates fresh worktree
+backing from the recorded source/target relationship and returns the same Workspace
+ID. If the source checkout or target branch can no longer provide valid backing, the
+open fails and the durable Workspace record remains closed.
+
+`close_workspace(action="delete")` is never an implicit discard for active isolated
+work. An active managed worktree still requires `commitMessage` and completes the
+same safe finalize/integrate/cleanup lifecycle before ForgeRelay deletes its identity.
+For an already-closed managed-worktree Workspace, delete removes only ForgeRelay-owned
+state and does not recreate the physical backing.
+
 Legacy `devspace/*` managed branches remain closable when they are already stored
 in workspace metadata; only new managed branches use `forgerelay/*`.
 
@@ -295,8 +308,10 @@ until `open_workspace` reactivates the same ID by path or by `workspaceId`.
 `close_workspace(action="delete")` is the explicit permanent checkout cleanup path:
 it removes ForgeRelay-owned Workspace state but never deletes or mutates project
 files. Managed-worktree close still requires `commitMessage` and runs the safe commit /
-fast-forward-only integration / cleanup lifecycle; managed-worktree, Composite, and
-relayed delete semantics are completed by their later lifecycle stages.
+fast-forward-only integration / cleanup lifecycle. Composite close preserves the same
+`cws_...` identity and member topology; Composite `action="delete"` dissolves only
+Composite-owned state without touching member Workspaces. Relayed delete remains a later
+lifecycle stage.
 
 Shell commands are allowed to modify ordinary project files when that is a
 natural part of the user's requested development task; ForgeRelay does not apply

package/docs/configuration.md

@@ -339,17 +339,32 @@ or externally removed managed-worktree root can therefore remain diagnostically
 ordinary same-target opens no longer accumulate duplicate inventory rows;
 `action="list"` remains the formal on-demand inventory path.
 
-For checkout-backed Workspaces, `close_workspace` now defaults to `action="close"`:
+For checkout-backed Workspaces, `close_workspace` defaults to `action="close"`:
 it marks the persistent Workspace closed, removes current conversation bindings, and
 keeps the same Workspace identity available for later `open_workspace` by path or ID.
 Closed Workspaces remain visible in inventory but ordinary execution tools reject them
 until reopened. `action="delete"` permanently removes ForgeRelay-owned checkout
 identity/state while never deleting or mutating the user's checkout directory.
-Managed-worktree close still requires `commitMessage` and runs the existing safe
-finalize lifecycle; managed-worktree delete semantics land in the next lifecycle
-stage. Composite close still dissolves in this stage, and Composite delete remains
-unavailable until its persistent lifecycle stage. Relayed delete is likewise deferred
-to Workspace Relay lifecycle parity.
+
+Managed-worktree close also preserves the Workspace identity. It still requires
+`commitMessage` and runs the existing BeforeWorktreeClose / commit / fast-forward-only
+integration / physical cleanup / AfterWorktreeClose lifecycle, then leaves the
+Workspace closed after its old worktree path and managed branch are removed. Reopening
+the closed Workspace by ID recreates fresh managed-worktree backing from its recorded
+source/target branch relationship while keeping the same `workspaceId`; an
+unambiguous repeated source/target open can reuse the same closed identity as well.
+If backing recreation fails, the record remains closed and unchanged.
+
+`action="delete"` on an active managed-worktree Workspace is not a discard operation:
+it requires `commitMessage`, completes the same safe finalize lifecycle, and only then
+removes the persistent ForgeRelay identity. Deleting an already-closed worktree
+Workspace removes only ForgeRelay-owned state and does not recreate backing.
+Composite close now marks only the Composite record closed while preserving its identity,
+name, members, and coordination metadata. Closed Composites remain inspectable and reject
+member routing or mutation until reopened with the same `cws_...` ID. Composite
+`action="delete"` permanently dissolves only Composite-owned state; it never closes,
+finalizes, deletes, or otherwise mutates member Workspaces. Relayed delete remains
+deferred to Workspace Relay lifecycle parity.
 
 Hot workspace/session activity timestamps are coalesced in memory and flushed to the
 SQLite state database in a transaction at most every five minutes; normal shutdown

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",

package/scripts/debug/accept.mjs

@@ -644,9 +644,124 @@ try {
     readFileSync(join(gitProject, "feature.txt"), "utf8").replace(/\r\n/g, "\n"),
     "debug worktree acceptance\n",
   );
+  const closedWorktreeInventory = callTool(oauth.accessToken, sessionId, 110, "open_workspace", {
+    action: "list",
+    workspaceId: worktreeWorkspaceId,
+  });
+  assert.equal(closedWorktreeInventory.structuredContent.workspaces.length, 1);
+  assert.equal(closedWorktreeInventory.structuredContent.workspaces[0].state, "closed");
+
+  const reopenedWorktree = callTool(oauth.accessToken, sessionId, 111, "open_workspace", {
+    workspaceId: worktreeWorkspaceId,
+    context: "none",
+  });
+  assert.equal(reopenedWorktree.structuredContent.workspaceId, worktreeWorkspaceId);
+  const reopenedWorktreePath = reopenedWorktree.structuredContent.worktree.path;
+  assert.notEqual(reopenedWorktreePath, managedWorktreePath);
+  assert.ok(existsSync(reopenedWorktreePath));
+
+  callTool(oauth.accessToken, sessionId, 112, "write", {
+    workspaceId: worktreeWorkspaceId,
+    path: "delete-feature.txt",
+    content: "debug worktree delete acceptance\n",
+  });
+  const deletedWorktree = callTool(oauth.accessToken, sessionId, 113, "close_workspace", {
+    workspaceId: worktreeWorkspaceId,
+    action: "delete",
+    commitMessage: "test(debug): verify 7677 worktree delete lifecycle",
+  });
+  assert.equal(deletedWorktree.structuredContent.action, "delete");
+  assert.equal(existsSync(reopenedWorktreePath), false);
+  assert.equal(
+    readFileSync(join(gitProject, "delete-feature.txt"), "utf8").replace(/\r\n/g, "\n"),
+    "debug worktree delete acceptance\n",
+  );
+  const deletedWorktreeInventory = callTool(oauth.accessToken, sessionId, 114, "open_workspace", {
+    action: "list",
+    workspaceId: worktreeWorkspaceId,
+  });
+  assert.equal(deletedWorktreeInventory.structuredContent.workspaces.length, 0);
+  pass(
+    "managed worktree lifecycle",
+    `${worktreeWorkspaceId} close -> closed inventory -> same-id reopen with fresh backing -> safe delete`,
+  );
+
+  callTool(oauth.accessToken, sessionId, 115, "write", {
+    workspaceId,
+    path: "composite-sentinel.txt",
+    content: "debug composite member acceptance\n",
+  });
+  const compositeOpened = callTool(oauth.accessToken, sessionId, 116, "open_workspace", {
+    kind: "composite",
+    name: "debug-lifecycle-composite",
+    context: "none",
+  });
+  const compositeWorkspaceId = compositeOpened.structuredContent.workspaceId;
+  callTool(oauth.accessToken, sessionId, 117, "open_workspace", {
+    action: "member",
+    workspaceId: compositeWorkspaceId,
+    memberAction: "add",
+    member: {
+      name: "code",
+      purpose: "Debug lifecycle member",
+      workspaceId,
+    },
+  });
+  const closedComposite = callTool(oauth.accessToken, sessionId, 118, "close_workspace", {
+    workspaceId: compositeWorkspaceId,
+  });
+  assert.equal(closedComposite.structuredContent.action, "close");
+  assert.equal(closedComposite.structuredContent.status, "closed");
+  assert.equal(closedComposite.structuredContent.dissolved, false);
+  const closedCompositeInventory = callTool(oauth.accessToken, sessionId, 119, "open_workspace", {
+    action: "list",
+    kind: "composite",
+    workspaceId: compositeWorkspaceId,
+    status: "closed",
+  });
+  assert.equal(closedCompositeInventory.structuredContent.compositeWorkspaces.length, 1);
+  assert.equal(closedCompositeInventory.structuredContent.compositeWorkspaces[0].state, "closed");
+  const closedCompositeRead = callTool(oauth.accessToken, sessionId, 120, "read", {
+    workspaceId: compositeWorkspaceId,
+    member: "code",
+    path: "composite-sentinel.txt",
+  });
+  assert.equal(closedCompositeRead.isError, true);
+
+  const reopenedComposite = callTool(oauth.accessToken, sessionId, 121, "open_workspace", {
+    workspaceId: compositeWorkspaceId,
+    context: "none",
+  });
+  assert.equal(reopenedComposite.structuredContent.workspaceId, compositeWorkspaceId);
+  assert.equal(reopenedComposite.structuredContent.status, "active");
+  assert.equal(reopenedComposite.structuredContent.members[0].workspaceId, workspaceId);
+  const reopenedCompositeRead = callTool(oauth.accessToken, sessionId, 122, "read", {
+    workspaceId: compositeWorkspaceId,
+    member: "code",
+    path: "composite-sentinel.txt",
+  });
+  assert.match(reopenedCompositeRead.structuredContent.result, /debug composite member acceptance/);
+
+  const deletedComposite = callTool(oauth.accessToken, sessionId, 123, "close_workspace", {
+    workspaceId: compositeWorkspaceId,
+    action: "delete",
+  });
+  assert.equal(deletedComposite.structuredContent.action, "delete");
+  assert.equal(deletedComposite.structuredContent.dissolved, true);
+  const memberAfterCompositeDelete = callTool(oauth.accessToken, sessionId, 124, "read", {
+    workspaceId,
+    path: "composite-sentinel.txt",
+  });
+  assert.match(memberAfterCompositeDelete.structuredContent.result, /debug composite member acceptance/);
+  const deletedCompositeInventory = callTool(oauth.accessToken, sessionId, 125, "open_workspace", {
+    action: "list",
+    kind: "composite",
+    workspaceId: compositeWorkspaceId,
+  });
+  assert.equal(deletedCompositeInventory.structuredContent.compositeWorkspaces.length, 0);
   pass(
-    "managed worktree workspace close",
-    `${closed.structuredContent.branch} -> ${closed.structuredContent.targetBranch}`,
+    "Composite lifecycle",
+    `${compositeWorkspaceId} close -> closed/non-routable -> same-id reopen -> delete; member Workspace preserved`,
   );
 
   exerciseReleaseTagHooks(oauth.accessToken, sessionId);