@akira-tl/forgerelay 0.8.0 → 0.8.2

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";
@@ -71,6 +71,9 @@ export class WorkspaceRegistry {
                 .filter((binding) => binding.conversationScopeId === openOptions.conversationScopeId)
                 .map((binding) => binding.workspaceSessionId)
             : []);
+        const workspaceIdFilter = input.workspaceId
+            ? this.store?.getSession(input.workspaceId)?.id ?? input.workspaceId
+            : undefined;
         const rootKey = input.root
             ? await canonicalPath(assertAllowedPath(input.root, [...this.config.allowedRoots, this.config.worktreeRoot]))
             : undefined;
@@ -110,7 +113,7 @@ export class WorkspaceRegistry {
             const entry = entries[index];
             if (!session || !entry)
                 continue;
-            if (input.workspaceId && entry.workspaceId !== input.workspaceId)
+            if (workspaceIdFilter && entry.workspaceId !== workspaceIdFilter)
                 continue;
             if (input.status && entry.status !== input.status)
                 continue;
@@ -149,8 +152,11 @@ export class WorkspaceRegistry {
         };
     }
     async resumeWorkspace(workspaceId, conversationScopeId, bootstrapContext = "auto") {
-        const workspace = this.getWorkspace(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,
@@ -209,22 +215,23 @@ export class WorkspaceRegistry {
         const workspace = this.getWorkspace(workspaceId);
         const canonicalWorkspaceId = workspace.id;
         if (workspace.mode === "worktree") {
-            const aliases = this.activeSessions("worktree")
-                .filter((session) => resolve(session.root) === resolve(workspace.root));
-            if (aliases.length <= 1) {
-                throw new Error(`Workspace ${canonicalWorkspaceId} is backed by a managed worktree. Use close_workspace with its managed-worktree finalize lifecycle instead of releasing the physical target as a separate handle.`);
-            }
+            throw new Error(`Workspace ${canonicalWorkspaceId} is backed by a managed worktree. Use close_workspace with its managed-worktree finalize lifecycle.`);
         }
         if (this.store) {
-            for (const binding of this.store.listConversationBindings()) {
-                if (binding.workspaceSessionId === canonicalWorkspaceId) {
-                    this.store.deleteConversationBinding(binding.conversationScopeId, binding.targetKey);
-                }
-            }
-            this.store.deleteSession(canonicalWorkspaceId);
+            this.deleteConversationBindingsForWorkspace(canonicalWorkspaceId);
+            this.store.setSessionStatus(canonicalWorkspaceId, "closed");
         }
         this.workspaces.delete(canonicalWorkspaceId);
     }
+    deleteWorkspace(workspaceId) {
+        const session = this.getWorkspaceSession(workspaceId);
+        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);
+        this.workspaces.delete(session.id);
+    }
     workspaceIdsForPhysicalWorkspace(workspace) {
         const root = resolve(workspace.root);
         return this.activeSessions(workspace.mode)
@@ -323,6 +330,7 @@ export class WorkspaceRegistry {
             },
         }));
         for (const aliasedWorkspaceId of aliasedWorkspaceIds) {
+            this.deleteConversationBindingsForWorkspace(aliasedWorkspaceId);
             this.store?.setSessionStatus(aliasedWorkspaceId, "closed");
             this.workspaces.delete(aliasedWorkspaceId);
         }
@@ -336,7 +344,7 @@ export class WorkspaceRegistry {
         if (boundContext)
             return boundContext;
         const context = await this.openOnce(targetKey, async () => {
-            const reusableWorkspace = await this.findReusableWorkspaceByDirectory(projectKey, "checkout");
+            const reusableWorkspace = await this.findReusableWorkspaceByDirectory(projectKey, "checkout", true);
             if (!reusableWorkspace)
                 return this.openCheckoutWorkspace(path);
             return this.reusedWorkspaceContext(reusableWorkspace);
@@ -382,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);
     }
@@ -547,27 +553,55 @@ export class WorkspaceRegistry {
             });
         }
     }
-    async findReusableWorkspaceByDirectory(directoryKey, mode) {
-        for (const session of this.activeSessions(mode)) {
+    async findReusableWorkspaceByDirectory(directoryKey, mode, reopenClosedCheckout = false) {
+        const sessions = this.store
+            ? this.store.listSessions({ mode })
+            : this.activeSessions(mode);
+        for (const session of sessions) {
+            const reusable = session.status === "active" ||
+                (reopenClosedCheckout && mode === "checkout" && session.status === "closed");
+            if (!reusable)
+                continue;
             const root = await this.validSessionRoot(session);
             if (!root)
                 continue;
             if (await canonicalPath(root) !== directoryKey)
                 continue;
+            if (session.status === "closed") {
+                this.store?.setSessionStatus(session.id, "active");
+                const reopened = this.store?.getSession(session.id);
+                if (!reopened)
+                    continue;
+                return this.workspaceFromSession(reopened, false);
+            }
             return this.workspaceFromSession(session, false);
         }
         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;
     }
@@ -636,6 +670,116 @@ export class WorkspaceRegistry {
             includeBootstrapContext: true,
         };
     }
+    async workspaceForOpen(workspaceId) {
+        const session = this.store?.getSession(workspaceId);
+        if (session?.status === "closed" && session.mode === "checkout") {
+            this.store?.setSessionStatus(session.id, "active");
+            const reopened = this.store?.getSession(session.id);
+            if (!reopened) {
+                throw new Error(`Unknown workspaceId: ${workspaceId}. Call open_workspace first.`);
+            }
+            return this.workspaceFromSession(reopened, true);
+        }
+        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)
+            return session;
+        const workspace = this.workspaces.get(workspaceId);
+        if (!workspace) {
+            throw new Error(`Unknown workspaceId: ${workspaceId}. Call open_workspace first.`);
+        }
+        return {
+            id: workspace.id,
+            root: workspace.root,
+            status: "active",
+            mode: workspace.mode,
+            sourceRoot: workspace.sourceRoot,
+            baseRef: workspace.worktree?.baseRef,
+            baseSha: workspace.worktree?.baseSha,
+            branch: workspace.worktree?.branch,
+            targetBranch: workspace.worktree?.targetBranch,
+            managed: workspace.worktree?.managed ?? false,
+            createdAt: "",
+            lastUsedAt: "",
+        };
+    }
+    deleteConversationBindingsForWorkspace(workspaceId) {
+        if (!this.store)
+            return;
+        for (const binding of this.store.listConversationBindings()) {
+            if (binding.workspaceSessionId === workspaceId) {
+                this.store.deleteConversationBinding(binding.conversationScopeId, binding.targetKey);
+            }
+        }
+    }
     getWorkspace(workspaceId) {
         const workspace = this.workspaces.get(workspaceId);
         if (workspace) {

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/*`.
 
@@ -288,11 +301,17 @@ normal open path may still include `staleWorkspaces` for an idle persistent
 Workspace; use `open_workspace(action="list")` for complete, filtered inventory
 when continuation or cleanup actually requires it.
 
-In v0.8.0, `close_workspace` is still the existing public close operation:
-checkout-backed Workspaces remove their ForgeRelay record without deleting project
-files, while managed-worktree-backed Workspaces require `commitMessage` and run the
-safe commit / fast-forward-only integration / cleanup lifecycle. Persistent
-closed/reopen semantics land in the following lifecycle stage.
+For checkout-backed Workspaces, `close_workspace` defaults to `action="close"` and
+preserves the Workspace identity for later reopen. A closed Workspace stays visible
+through `open_workspace(action="list")`, while ordinary execution tools reject it
+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. 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,15 +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.
 
-In v0.8.0, `close_workspace` still removes a checkout-backed Workspace record without
-deleting checkout files; the persistent closed/reopen lifecycle is introduced by
-the next lifecycle stage. For a managed-worktree-backed Workspace, `close_workspace` requires
-`commitMessage` and runs the existing safe worktree finalize lifecycle: close Hooks,
-commit when needed, fast-forward-only integration, cleanup, and alias invalidation.
-For a Composite Workspace, the same tool means dissolve: it removes only the
-Composite identity, membership, and Composite-facing panel/lifecycle state. It does
-not close members, finalize member worktrees, interrupt member processes, delete
-files, or remove remote registrations and relayed Workspace routes.
+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 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.0",
+  "version": "0.8.2",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",