@akira-tl/forgerelay 0.7.4 → 0.8.1

package/dist/workspaces.js

@@ -1,4 +1,5 @@
 import { createHash, randomBytes } from "node:crypto";
+import { realpathSync } from "node:fs";
 import { mkdir, opendir, readFile, realpath, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
@@ -23,6 +24,7 @@ export class WorkspaceRegistry {
         this.config = config;
         this.store = store;
         this.hooks = new HookRunner(config.hooks, config.logging);
+        this.foldLegacyWorkspaceSessions();
         this.pruneIdleWorkspaceSessions(new Set(), true);
     }
     get cachedWorkspaceCount() {
@@ -42,7 +44,7 @@ export class WorkspaceRegistry {
         if (mode === "worktree") {
             return this.openReusableWorktree(workspaceInput, openOptions.conversationScopeId);
         }
-        return this.openReusableCheckout(workspaceInput.path, openOptions.conversationScopeId, workspaceInput.newWorkspace ?? false, bootstrapContext);
+        return this.openReusableCheckout(workspaceInput.path, openOptions.conversationScopeId, bootstrapContext);
     }
     async listWorkspaces(input = {}, openOptions = {}) {
         this.pruneIdleWorkspaceSessions(openOptions.protectedWorkspaceIds ?? new Set());
@@ -69,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;
@@ -108,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;
@@ -147,7 +152,7 @@ export class WorkspaceRegistry {
         };
     }
     async resumeWorkspace(workspaceId, conversationScopeId, bootstrapContext = "auto") {
-        const workspace = this.getWorkspace(workspaceId);
+        const workspace = this.workspaceForOpen(workspaceId);
         const context = await this.reusedWorkspaceContext(workspace);
         if (!conversationScopeId || !this.store) {
             return {
@@ -205,22 +210,24 @@ export class WorkspaceRegistry {
     }
     closeWorkspace(workspaceId) {
         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 ${workspaceId} is the last active handle for a worktree. Use close_worktree to finalize and remove the physical worktree, or keep this handle as its anchor.`);
-            }
+            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 === workspaceId) {
-                    this.store.deleteConversationBinding(binding.conversationScopeId, binding.targetKey);
-                }
-            }
-            this.store.deleteSession(workspaceId);
+            this.deleteConversationBindingsForWorkspace(canonicalWorkspaceId);
+            this.store.setSessionStatus(canonicalWorkspaceId, "closed");
         }
-        this.workspaces.delete(workspaceId);
+        this.workspaces.delete(canonicalWorkspaceId);
+    }
+    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.`);
+        }
+        this.deleteConversationBindingsForWorkspace(session.id);
+        this.store?.deleteSession(session.id);
+        this.workspaces.delete(session.id);
     }
     workspaceIdsForPhysicalWorkspace(workspace) {
         const root = resolve(workspace.root);
@@ -325,30 +332,18 @@ export class WorkspaceRegistry {
         }
         return { ...result, hookReports };
     }
-    async openReusableCheckout(path, conversationScopeId, newWorkspace, bootstrapContext) {
+    async openReusableCheckout(path, conversationScopeId, bootstrapContext) {
         const allowedPath = assertAllowedPath(path, this.config.allowedRoots);
         const projectKey = await canonicalPath(allowedPath);
         const targetKey = JSON.stringify(["checkout", projectKey, null]);
-        if (!newWorkspace) {
-            const boundContext = await this.boundConversationContext(conversationScopeId, targetKey, "checkout", async (session, root) => session.mode === "checkout" && await canonicalPath(root) === projectKey, bootstrapContext);
-            if (boundContext)
-                return boundContext;
-        }
-        if (newWorkspace) {
-            const reusableWorkspace = await this.findReusableWorkspaceByDirectory(projectKey, "checkout");
-            const freshContext = reusableWorkspace
-                ? await this.cloneWorkspaceContext(reusableWorkspace)
-                : await this.openCheckoutWorkspace(path);
-            return this.withConversationContext(freshContext, conversationScopeId, targetKey, bootstrapContext);
-        }
-        const operationKey = this.conversationOpenKey(targetKey, conversationScopeId);
-        const context = await this.openOnce(operationKey, async () => {
-            const reusableWorkspace = await this.findReusableWorkspaceByDirectory(projectKey, "checkout");
+        const boundContext = await this.boundConversationContext(conversationScopeId, targetKey, "checkout", async (session, root) => session.mode === "checkout" && await canonicalPath(root) === projectKey, bootstrapContext);
+        if (boundContext)
+            return boundContext;
+        const context = await this.openOnce(targetKey, async () => {
+            const reusableWorkspace = await this.findReusableWorkspaceByDirectory(projectKey, "checkout", true);
             if (!reusableWorkspace)
                 return this.openCheckoutWorkspace(path);
-            return conversationScopeId && this.store
-                ? this.cloneWorkspaceContext(reusableWorkspace)
-                : this.reusedWorkspaceContext(reusableWorkspace);
+            return this.reusedWorkspaceContext(reusableWorkspace);
         });
         return this.withConversationContext(context, conversationScopeId, targetKey, bootstrapContext);
     }
@@ -361,27 +356,15 @@ export class WorkspaceRegistry {
         if (managedPath) {
             const worktreeKey = await canonicalPath(managedPath);
             const targetKey = JSON.stringify(["worktree-path", worktreeKey]);
-            if (!input.newWorkspace) {
-                const boundContext = await this.boundConversationContext(conversationScopeId, targetKey, "worktree", async (session, root) => session.mode === "worktree" && await canonicalPath(root) === worktreeKey, bootstrapContext);
-                if (boundContext)
-                    return boundContext;
-            }
-            if (input.newWorkspace) {
-                const reusableWorkspace = await this.findReusableWorkspaceByDirectory(worktreeKey, "worktree");
-                if (!reusableWorkspace) {
-                    throw new Error(`Managed worktree is not registered as an active ForgeRelay workspace: ${managedPath}. Open the source project in worktree mode to create or recover a managed worktree first.`);
-                }
-                return this.withConversationContext(await this.cloneWorkspaceContext(reusableWorkspace), conversationScopeId, targetKey, bootstrapContext);
-            }
-            const operationKey = this.conversationOpenKey(targetKey, conversationScopeId);
-            const context = await this.openOnce(operationKey, async () => {
+            const boundContext = await this.boundConversationContext(conversationScopeId, targetKey, "worktree", async (session, root) => session.mode === "worktree" && await canonicalPath(root) === worktreeKey, bootstrapContext);
+            if (boundContext)
+                return boundContext;
+            const context = await this.openOnce(targetKey, async () => {
                 const reusableWorkspace = await this.findReusableWorkspaceByDirectory(worktreeKey, "worktree");
                 if (!reusableWorkspace) {
                     throw new Error(`Managed worktree is not registered as an active ForgeRelay workspace: ${managedPath}. Open the source project in worktree mode to create or recover a managed worktree first.`);
                 }
-                return conversationScopeId && this.store
-                    ? this.cloneWorkspaceContext(reusableWorkspace)
-                    : this.reusedWorkspaceContext(reusableWorkspace);
+                return this.reusedWorkspaceContext(reusableWorkspace);
             });
             return this.withConversationContext(context, conversationScopeId, targetKey, bootstrapContext);
         }
@@ -396,29 +379,17 @@ export class WorkspaceRegistry {
             const context = await this.openWorktreeWorkspace(path, input.baseRef);
             return this.withConversationContext(context, conversationScopeId, targetKey, bootstrapContext);
         }
-        if (!input.newWorkspace) {
-            const boundContext = await this.boundConversationContext(conversationScopeId, targetKey, "worktree", async (session) => session.mode === "worktree" &&
-                session.sourceRoot !== undefined &&
-                await canonicalPath(session.sourceRoot) === sourceKey &&
-                session.targetBranch === resolvedBase.targetBranch, bootstrapContext);
-            if (boundContext)
-                return boundContext;
-        }
-        if (input.newWorkspace) {
-            const reusableWorkspace = await this.findReusableWorktreeBySource(sourceKey, resolvedBase.targetBranch);
-            const freshContext = reusableWorkspace
-                ? await this.cloneWorkspaceContext(reusableWorkspace)
-                : await this.openWorktreeWorkspace(path, input.baseRef);
-            return this.withConversationContext(freshContext, conversationScopeId, targetKey, bootstrapContext);
-        }
-        const operationKey = this.conversationOpenKey(targetKey, conversationScopeId);
-        const context = await this.openOnce(operationKey, async () => {
+        const boundContext = await this.boundConversationContext(conversationScopeId, targetKey, "worktree", async (session) => session.mode === "worktree" &&
+            session.sourceRoot !== undefined &&
+            await canonicalPath(session.sourceRoot) === sourceKey &&
+            session.targetBranch === resolvedBase.targetBranch, bootstrapContext);
+        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 conversationScopeId && this.store
-                ? this.cloneWorkspaceContext(reusableWorkspace)
-                : this.reusedWorkspaceContext(reusableWorkspace);
+            return this.reusedWorkspaceContext(reusableWorkspace);
         });
         return this.withConversationContext(context, conversationScopeId, targetKey, bootstrapContext);
     }
@@ -453,11 +424,6 @@ export class WorkspaceRegistry {
         }
         return keys;
     }
-    conversationOpenKey(targetKey, conversationScopeId) {
-        return conversationScopeId && this.store
-            ? JSON.stringify(["conversation", conversationScopeId, targetKey])
-            : targetKey;
-    }
     async boundConversationContext(conversationScopeId, targetKey, mode, matches, bootstrapContext) {
         if (!conversationScopeId || !this.store)
             return undefined;
@@ -550,17 +516,62 @@ export class WorkspaceRegistry {
                 worktreeAnchors.get(resolve(session.root))?.id === session.id) {
                 continue;
             }
-            this.store.deleteSession(session.id);
             this.workspaces.delete(session.id);
         }
     }
-    async findReusableWorkspaceByDirectory(directoryKey, mode) {
-        for (const session of this.activeSessions(mode)) {
+    foldLegacyWorkspaceSessions() {
+        if (!this.store)
+            return;
+        const groups = new Map();
+        for (const session of this.store.listSessions()) {
+            const targetPath = canonicalPersistedWorkspacePath(session.root);
+            const key = JSON.stringify([session.mode, targetPath]);
+            const group = groups.get(key) ?? [];
+            group.push(session);
+            groups.set(key, group);
+        }
+        for (const sessions of groups.values()) {
+            if (sessions.length < 2)
+                continue;
+            const ordered = [...sessions].sort((left, right) => left.createdAt.localeCompare(right.createdAt) || left.id.localeCompare(right.id));
+            const canonical = ordered[0];
+            if (!canonical)
+                continue;
+            const createdAt = ordered.reduce((earliest, session) => session.createdAt < earliest ? session.createdAt : earliest, canonical.createdAt);
+            const lastUsedAt = ordered.reduce((latest, session) => session.lastUsedAt > latest ? session.lastUsedAt : latest, canonical.lastUsedAt);
+            const status = ordered.some((session) => session.status === "active")
+                ? "active"
+                : canonical.status;
+            this.store.foldSessions({
+                canonicalId: canonical.id,
+                aliasIds: ordered.slice(1).map((session) => session.id),
+                createdAt,
+                lastUsedAt,
+                status,
+            });
+        }
+    }
+    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;
@@ -623,14 +634,6 @@ export class WorkspaceRegistry {
             throw error;
         }
     }
-    async cloneWorkspaceContext(workspace) {
-        return this.createWorkspaceContext({
-            root: workspace.root,
-            mode: workspace.mode,
-            sourceRoot: workspace.sourceRoot,
-            worktree: workspace.worktree ? { ...workspace.worktree } : undefined,
-        });
-    }
     async reusedWorkspaceContext(workspace) {
         Object.assign(workspace, this.loadSkillsForWorkspace(workspace.root));
         workspace.capabilityGuides = loadCapabilityGuides(this.config);
@@ -651,6 +654,50 @@ export class WorkspaceRegistry {
             includeBootstrapContext: true,
         };
     }
+    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);
+    }
+    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) {
@@ -1036,6 +1083,25 @@ function bootstrapContextFingerprint(workspace, agentsFiles, availableAgentsFile
     };
     return createHash("sha256").update(JSON.stringify(payload)).digest("hex");
 }
+function canonicalPersistedWorkspacePath(path) {
+    const missingSegments = [];
+    let candidate = path;
+    while (true) {
+        try {
+            return resolve(realpathSync(candidate), ...missingSegments.slice().reverse());
+        }
+        catch (error) {
+            if (!isErrnoException(error) || (error.code !== "ENOENT" && error.code !== "ENOTDIR")) {
+                return resolve(path);
+            }
+            const parent = dirname(candidate);
+            if (parent === candidate)
+                return resolve(path);
+            missingSegments.push(basename(candidate));
+            candidate = parent;
+        }
+    }
+}
 async function canonicalPath(path) {
     const missingSegments = [];
     let candidate = path;

package/docs/chatgpt-coding-workflow.md

@@ -9,14 +9,17 @@ checkout.
 `open_workspace` returns a `workspaceId`. Continue using that ID for later tools
 in the same directory.
 
-`workspaceId` is a logical conversation handle, not the physical-directory
-identity. Reopening the same checkout in the same conversation keeps that
-logical ID stable. A different conversation normally receives a different
-`workspaceId` even when it points at the same checkout or worktree; pass an
-existing ID explicitly when the user wants to resume that logical workspace.
-
-A Git worktree directory is a separate physical workspace target from its source
-checkout, and each conversation can still have its own logical handle for it.
+`workspaceId` identifies a persistent ForgeRelay Workspace rather than a
+conversation-scoped handle. A canonical checkout path maps to one checkout
+Workspace, and a managed worktree path maps to one managed-worktree Workspace.
+Different Host conversations may bind to and reuse the same `workspaceId`; pass a
+known ID explicitly when the user wants to resume that Workspace. Historical
+duplicate IDs created by older ForgeRelay versions are accepted during migration
+and resolve to the canonical Workspace identity.
+
+A Git worktree directory is a separate physical Workspace target from its source
+checkout. Separate parallel identities require separate managed worktrees rather
+than multiple logical handles pointing at one physical target.
 
 ### Bootstrap context and workspace inventory
 
@@ -28,12 +31,11 @@ open_workspace(path="~/project")
 
 The default `context="auto"` keeps the first useful bootstrap while avoiding
 replay. ForgeRelay tracks delivered context by conversation plus canonical
-workspace target and a content fingerprint, not by logical `workspaceId`. If the
-same conversation opens or resumes another logical handle for the same physical
-project and the fingerprint is unchanged, the response keeps only lightweight
-workspace metadata. If loaded instruction contents or relevant Skill, Capability
-guide, profile, diagnostic, or nested-instruction metadata changes, the next
-automatic open returns the refreshed bootstrap.
+Workspace target and a content fingerprint, independently from persistent
+Workspace identity. Different conversations may reuse the same `workspaceId` while
+each receives the current bootstrap once. If loaded instruction contents or
+relevant Skill, Capability guide, profile, diagnostic, or nested-instruction
+metadata changes, the next automatic open returns the refreshed bootstrap.
 
 Two explicit controls are available for exceptional cases:
 
@@ -42,15 +44,14 @@ open_workspace(workspaceId="ws_...", context="full")
 open_workspace(workspaceId="ws_...", context="none")
 ```
 
-`full` forces a bootstrap refresh. `none` opens/resumes the workspace without
+`full` forces a bootstrap refresh. `none` opens/resumes the Workspace without
 returning the full project context and does not record the current fingerprint as
-already delivered. Context-delivery state is independent from logical-workspace
-selection, so closing or switching one handle does not make the conversation
-forget unchanged project context it already received.
+already delivered. Context-delivery state remains conversation-scoped and does not
+change the persistent Workspace identity.
 
-Do not enumerate workspace state on every normal open. When the user wants to
-continue an earlier task, choose among logical workspaces, or clean up accumulated
-state, use the same Core tool in inventory mode:
+Do not enumerate Workspace state on every normal open. When the user wants to
+continue earlier work, inspect known Workspaces, or clean up accumulated state, use
+the same Core tool in inventory mode:
 
 ```text
 open_workspace(action="list")
@@ -62,7 +63,7 @@ Inventory is paginated, defaults to 50 entries, and caps each page at 100. It ca
 filter by `workspaceId`, persisted `status`, derived `state`, `mode`, canonical
 root/source root, or stale-only state. Entries include a compact label such as
 `project/ws_...`, checkout/worktree backing metadata, timestamps, idle duration,
-root validity, and whether that logical workspace is currently selected by this
+root validity, and whether that Workspace is currently selected by this
 conversation. Listing is observational and does not refresh `lastUsedAt`.
 
 Treat persisted status and derived state separately. `status="active"` means the
@@ -278,18 +279,24 @@ surface, including direct `rename`/`delete` path mutations alongside `apply_patc
 unified move/rename primitive for both files and directories; ForgeRelay does not
 expose a separate `move` tool.
 
-Workspace IDs are logical conversation handles rather than physical-directory
-identities. The same conversation keeps a stable ID for a project, while another
-conversation normally receives a different ID pointing at the same checkout or
-worktree. `open_workspace` can explicitly resume a known `workspaceId`, and a
-fresh logical ID is created only when the user asks for one. The normal open path
-may still include `staleWorkspaces` as a passive reminder for same-target handles
-idle for more than two days; use `open_workspace(action="list")` for complete,
-filtered inventory when continuation or cleanup actually requires it.
-`close_workspace` is the single public close operation: checkout-backed workspaces
-release the logical handle, while managed-worktree-backed workspaces require
-`commitMessage` and run the safe commit / fast-forward-only integration / cleanup
-lifecycle.
+Workspace IDs are persistent ForgeRelay identities. The same canonical checkout
+or managed worktree is reused across conversations; older duplicate IDs remain
+compatibility aliases that resolve to the canonical Workspace. `newWorkspace` is
+deprecated and no longer allocates a second identity for the same physical target;
+use `newWorktree=true` when genuinely separate Git isolation is required. The
+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.
+
+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; managed-worktree, Composite, and
+relayed delete semantics are completed by their later lifecycle stages.
 
 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

@@ -286,24 +286,27 @@ is no separate `move` MCP tool.
 Codex-mode commands run without a PTY by default. `tty: true` enables interactive
 programs when the optional `node-pty` dependency is available.
 
-Logical workspace IDs are conversation-scoped handles. Reopening the same project
-from the same conversation keeps its ID stable; a different conversation normally
-receives a different ID for the same physical checkout/worktree. Pass
-`workspaceId` to `open_workspace` to explicitly resume an existing handle in the
-current conversation. `newWorkspace: true` allocates a new logical handle without
-creating another checkout or Git worktree and should be used only on explicit user
-request.
-
-Bootstrap delivery is tracked separately from the selected logical workspace.
+Workspace IDs identify persistent ForgeRelay Workspaces rather than individual
+conversation handles. A canonical checkout path maps to one checkout Workspace, and
+a managed worktree path maps to one managed-worktree Workspace; different Host
+conversations can bind to and reuse the same `workspaceId`. Pass `workspaceId` to
+`open_workspace` to resume that known Workspace explicitly. Historical duplicate
+IDs created by older ForgeRelay versions remain accepted during migration and
+resolve to the canonical Workspace. `newWorkspace: true` is retained only as a
+deprecated compatibility input and no longer allocates another identity for the
+same physical target; use `newWorktree: true` for genuinely separate Git isolation.
+
+Bootstrap delivery is tracked separately from Workspace identity.
 `open_workspace` defaults to `context="auto"`: ForgeRelay fingerprints the current
 project context and returns the full AGENTS/Skills/Capability-guide/profile bootstrap
 only when that conversation has not already received the current fingerprint for
 the canonical workspace target. `context="full"` forces a refresh;
-`context="none"` opens or resumes the logical workspace without returning the full
-bootstrap and does not mark the current fingerprint as delivered. Closing or
-switching a logical workspace therefore does not by itself cause unchanged project
-context to be injected again, while changed context produces a new fingerprint and
-is delivered on the next `auto` open.
+`context="none"` opens or resumes the Workspace without returning the full bootstrap
+and does not mark the current fingerprint as delivered. Conversation-scoped
+bootstrap delivery therefore remains independent from the persistent Workspace
+identity: another conversation may reuse the same Workspace while independently
+receiving the current bootstrap once, and changed context produces a new fingerprint
+for the next `auto` open.
 
 Composite Workspaces use the same `open_workspace` entry point with
 `kind="composite"` and a human-readable `name`. They have no filesystem root of
@@ -324,26 +327,29 @@ Hooks, Skills, language services, and Activity facts remain owned by the underly
 Workspace. The Composite Activity Panel only aggregates their presentation into one
 Host Turn.
 
-Use `open_workspace(action="list")` only when the Agent needs to continue an older
-logical workspace, choose among multiple handles, or organize workspace state. The
-inventory is paginated (50 records by default, at most 100) and can filter by
-workspace ID, persisted status, derived state, mode, canonical root/source root, or
-stale-only state. Reading inventory does not refresh `lastUsedAt`. Persisted
+Use `open_workspace(action="list")` only when the Agent needs to inspect known
+Workspaces, continue earlier work, or organize Workspace state. The inventory is
+paginated (50 records by default, at most 100) and can filter by Workspace 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"`. The existing
-`staleWorkspaces` field remains a passive same-workspace reminder for old handles;
-`action="list"` is the formal on-demand inventory path.
-
-`close_workspace` removes a checkout-backed logical handle without deleting checkout
-files. 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.
+`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.
+
+For checkout-backed Workspaces, `close_workspace` now 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.
 
 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
@@ -366,7 +372,7 @@ the initial run request terminates a not-yet-handed-off process so ForgeRelay do
 not leave an orphan process whose `processId` the Agent never received.
 
 Completed background processes are delivered once with a later tool result for the
-same logical workspace ID. Full buffered completion output is retained for five
+same Workspace ID. Full buffered completion output is retained for five
 minutes; after that ForgeRelay compacts the completion to a bounded head/tail record
 and keeps it deliverable for up to 24 hours, still subject to the global completed
 process count bound. Completed processes no longer prevent `close_workspace`; the