@akira-tl/forgerelay 0.7.4 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-08-30
+
+### Changed
+
+- Workspace identity is now canonical per physical checkout or managed worktree, so different Host conversations reuse one persistent `workspaceId`; legacy duplicate IDs remain compatible aliases, and `newWorkspace` no longer creates same-target duplicates.
+
+### Fixed
+
+- Composite member bootstrap now preserves capability guides and subagent provider/profile context exposed by the underlying Workspace.
+- Composite member `context="none"` now truthfully reports suppressed bootstrap instead of claiming it was already delivered.
+
 ## [0.7.4] - 2026-08-30
 
 ### Added

package/dist/db/migrations.js

@@ -74,6 +74,11 @@ const migrations = [
         name: "subagent-run-ownership",
         up: migrateSubagentRunOwnership,
     },
+    {
+        version: 16,
+        name: "workspace-session-aliases",
+        up: migrateWorkspaceSessionAliases,
+    },
 ];
 export function migrateDatabase(sqlite) {
     const migrate = sqlite.transaction(() => {
@@ -368,6 +373,20 @@ function migrateSubagentRunOwnership(sqlite) {
     addColumnIfMissing(sqlite, "local_agent_sessions", "active_owner_id", "text");
     addColumnIfMissing(sqlite, "local_agent_sessions", "active_owner_pid", "integer");
 }
+function migrateWorkspaceSessionAliases(sqlite) {
+    sqlite.exec(`
+    create table if not exists workspace_session_aliases (
+      alias_id text primary key,
+      workspace_session_id text not null,
+      foreign key (workspace_session_id)
+        references workspace_sessions(id)
+        on delete cascade
+    );
+
+    create index if not exists workspace_session_aliases_workspace_idx
+      on workspace_session_aliases(workspace_session_id);
+  `);
+}
 function migrateActivityHostTurnWorkspace(sqlite) {
     migrateActivityHostTurns(sqlite);
     addColumnIfMissing(sqlite, "activity_host_turns", "workspace_id", "text");

package/dist/db/schema.js

@@ -16,6 +16,14 @@ export const workspaceSessions = sqliteTable("workspace_sessions", {
     index("workspace_sessions_root_idx").on(table.root, table.lastUsedAt),
     index("workspace_sessions_status_idx").on(table.status, table.lastUsedAt),
 ]);
+export const workspaceSessionAliases = sqliteTable("workspace_session_aliases", {
+    aliasId: text("alias_id").primaryKey(),
+    workspaceSessionId: text("workspace_session_id")
+        .notNull()
+        .references(() => workspaceSessions.id, { onDelete: "cascade" }),
+}, (table) => [
+    index("workspace_session_aliases_workspace_idx").on(table.workspaceSessionId),
+]);
 export const loadedAgentFiles = sqliteTable("loaded_agent_files", {
     workspaceSessionId: text("workspace_session_id")
         .notNull()

package/dist/server.js

@@ -1362,6 +1362,22 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         const skills = workspace.skills
             .filter((skill) => !skill.disableModelInvocation)
             .map((skill) => ({ name: skill.name, description: skill.description }));
+        const capabilityGuides = workspace.capabilityGuides.map((guide) => ({
+            name: guide.name,
+            description: guide.description,
+            whenToRead: guide.whenToRead,
+            path: formatPathForPrompt(guide.filePath),
+        }));
+        const agentProviders = config.subagents ? subagentProviders : [];
+        const agents = workspace.agentProfiles.map((profile) => {
+            const summary = summarizeSubagentProfile(profile);
+            const availability = agentProviders.find((provider) => provider.name === summary.provider);
+            return {
+                ...summary,
+                providerAvailable: availability?.available,
+                providerUnavailableReason: availability?.reason,
+            };
+        });
         return {
             member: memberName,
             workspaceId: compositeWorkspaceId,
@@ -1373,15 +1389,20 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             includeBootstrapContext: opened.includeBootstrapContext,
             ...(opened.includeBootstrapContext
                 ? {
+                    capabilityGuides,
                     agentsFiles,
                     availableAgentsFiles,
                     skills,
+                    agentProviders,
+                    agents,
                     skillDiagnostics: redactSkillDiagnosticPaths(workspace.skillDiagnostics),
                 }
                 : {}),
             instruction: opened.includeBootstrapContext
                 ? `Bootstrap context for Composite member ${memberName}. Keep using Composite workspaceId ${compositeWorkspaceId} and pass member=${memberName} for work operations.`
-                : `Composite member ${memberName} context was already delivered for this Host context; keep using Composite workspaceId ${compositeWorkspaceId} with member=${memberName}.`,
+                : contextPolicy === "none"
+                    ? `Bootstrap context for Composite member ${memberName} was intentionally suppressed by context=none. Keep using Composite workspaceId ${compositeWorkspaceId} with member=${memberName}; request context=auto or context=full when member bootstrap is needed.`
+                    : `Composite member ${memberName} context was already delivered for this Host context; keep using Composite workspaceId ${compositeWorkspaceId} with member=${memberName}.`,
         };
     };
     const coreOperations = createCoreOperationExecutor({
@@ -1960,7 +1981,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             action: z
                 .enum(["open", "list", "member"])
                 .optional()
-                .describe("Defaults to open. Use list to inspect logical workspaces. Use member to add/remove a named execution member on an existing Composite Workspace."),
+                .describe("Defaults to open. Use list to inspect known Workspaces. Use member to add/remove a named execution member on an existing Composite Workspace."),
             memberAction: z
                 .enum(["add", "update", "remove"])
                 .optional()
@@ -2000,7 +2021,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             workspaceId: z
                 .string()
                 .optional()
-                .describe("For action=open, an existing logical workspace ID to resume in this conversation. For action=list, filters inventory to one workspace ID."),
+                .describe("For action=open, an existing Workspace ID to resume or reuse. Historical duplicate IDs from earlier ForgeRelay versions may resolve to the canonical Workspace ID. For action=list, filters inventory to one Workspace ID."),
             mode: z
                 .enum(["checkout", "worktree"])
                 .optional()
@@ -2016,7 +2037,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             newWorkspace: z
                 .boolean()
                 .optional()
-                .describe("When true, allocate a fresh logical workspaceId for the same physical checkout or worktree and bind this conversation to it. Use only after the user explicitly requests a new logical workspace."),
+                .describe("Deprecated compatibility flag. It no longer creates another Workspace identity for the same physical checkout or managed worktree; ForgeRelay reuses that target's canonical Workspace. Use newWorktree=true when the user explicitly needs separate Git isolation."),
             context: z
                 .enum(["auto", "full", "none"])
                 .optional()
@@ -2036,7 +2057,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             staleOnly: z
                 .boolean()
                 .optional()
-                .describe("For action=list, return only active logical workspaces idle for more than two days."),
+                .describe("For action=list, return only active Workspaces idle for more than two days."),
             offset: z
                 .number()
                 .int()
@@ -2570,7 +2591,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         const loadedAgentsFiles = includeBootstrapContext ? cardAgentsFiles : [];
         const availableAgentsFileOutputs = includeBootstrapContext ? cardAvailableAgentsFiles : [];
         const workspaceContextInstruction = "For later open_workspace calls, context=\"auto\" avoids repeating unchanged bootstrap context; use context=\"none\" when only the workspace handle/metadata is needed, or context=\"full\" to force a refresh.";
-        const workspaceManagementInstruction = "When you need to continue an earlier logical workspace or organize workspace state, use open_workspace(action=\"list\") to inspect candidates, then resume a selected workspaceId or ask the user before close_workspace cleanup.";
+        const workspaceManagementInstruction = "When you need to inspect known Workspaces, continue earlier work, or organize Workspace state, use open_workspace(action=\"list\") to inspect candidates, then resume a selected workspaceId or ask the user before close_workspace cleanup.";
         const cardInstruction = config.skillsEnabled
             ? `Use this workspaceId in all subsequent tool calls for this project. Follow loaded agentsFiles instructions. Read an availableAgentsFiles path before working under it. When a task matches an available skill, load it with read(path=\"skills://<name>\") before proceeding. When a task matches a capability guide, read its advertised path before proceeding. ${workspaceContextInstruction} ${workspaceManagementInstruction}`
             : `Use this workspaceId in all subsequent tool calls for this project. Follow loaded agentsFiles instructions. Read an availableAgentsFiles path before working under it. When a task matches a capability guide, read its advertised path before proceeding. ${workspaceContextInstruction} ${workspaceManagementInstruction}`;
@@ -2632,7 +2653,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                         ? `Known worktrees: ${knownWorktrees.map((worktree) => `${worktree.path} [${worktree.workspaceId}]${worktree.branch ? ` branch=${worktree.branch}` : ""}${worktree.targetBranch ? ` target=${worktree.targetBranch}` : ""}${worktree.current ? " (current)" : ""}`).join(", ")}`
                         : undefined,
                     staleWorkspaces.length > 0
-                        ? `Idle logical workspaces for this same physical workspace (>2 days): ${staleWorkspaces.map((stale) => `${stale.workspaceId} last-used=${stale.lastUsedAt}`).join(", ")}. Tell the user these are available to resume or explicitly close; do not clean them up automatically.`
+                        ? `This Workspace has been idle for more than 2 days: ${staleWorkspaces.map((stale) => `${stale.workspaceId} last-used=${stale.lastUsedAt}`).join(", ")}. It remains available to resume or explicitly close; do not clean it up automatically.`
                         : undefined,
                     `ForgeRelay ${capabilityFingerprint.version} capabilities: ${capabilityFingerprint.capabilities.join(", ")}`,
                     instruction,
@@ -2900,7 +2921,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
     });
     registerAppTool(server, toolNames.closeWorkspace, {
         title: "Close workspace",
-        description: "Close one workspace after the user chooses cleanup. Composite Workspaces dissolve here: only the Composite identity and member links are removed; member Workspaces, files, processes, worktrees, and relay routes remain intact. Checkout-backed workspaces release only the logical handle. Managed-worktree-backed workspaces run the safe finalize lifecycle (hooks, commit, fast-forward integration, cleanup) and require commitMessage. Running processes block ordinary Workspace closure.",
+        description: "Close one Workspace after the user chooses cleanup. In v0.8.0, Composite close still dissolves only the Composite identity/member links. Checkout close removes ForgeRelay state but never project files. Managed-worktree-backed Workspaces run the safe finalize lifecycle (hooks, commit, fast-forward integration, cleanup) and require commitMessage. Running processes block ordinary Workspace closure.",
         inputSchema: {
             workspaceId: z.string().describe("Workspace identifier to close."),
             commitMessage: z
@@ -2992,7 +3013,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     const busyWorkspaceIds = physicalWorkspaceIds
                         .filter((id) => processSessions.activeWorkspaceIds().has(id));
                     if (busyWorkspaceIds.length > 0) {
-                        throw new Error(`Cannot close this worktree-backed workspace while logical workspace processes are still running: ${busyWorkspaceIds.join(", ")}.`);
+                        throw new Error(`Cannot close this worktree-backed Workspace while Workspace processes are still running: ${busyWorkspaceIds.join(", ")}.`);
                     }
                     const startedAt = performance.now();
                     const retirement = await codeIntelligence.retireWorkspaceRoot(workspace.root);

package/dist/workspace-store.js

@@ -1,6 +1,6 @@
 import { and, desc, eq } from "drizzle-orm";
 import { openDatabase } from "./db/client.js";
-import { workspaceContextDeliveries, workspaceConversationBindings, workspaceSessions, } from "./db/schema.js";
+import { workspaceContextDeliveries, workspaceConversationBindings, workspaceSessionAliases, workspaceSessions, } from "./db/schema.js";
 const DEFAULT_TOUCH_FLUSH_INTERVAL_MS = 5 * 60 * 1_000;
 export class SqliteWorkspaceStore {
     database;
@@ -61,24 +61,33 @@ export class SqliteWorkspaceStore {
         return session;
     }
     getSession(id) {
+        const sessionId = this.resolveSessionId(id);
+        if (!sessionId)
+            return undefined;
         const row = this.database.db
             .select()
             .from(workspaceSessions)
-            .where(eq(workspaceSessions.id, id))
+            .where(eq(workspaceSessions.id, sessionId))
             .get();
         if (!row)
             return undefined;
-        return applySessionTouch(rowToWorkspaceSession(row), this.pendingSessionTouches.get(id));
+        return applySessionTouch(rowToWorkspaceSession(row), this.pendingSessionTouches.get(sessionId));
     }
     touchSession(id) {
-        this.pendingSessionTouches.set(id, this.now().toISOString());
+        const sessionId = this.resolveSessionId(id);
+        if (!sessionId)
+            return;
+        this.pendingSessionTouches.set(sessionId, this.now().toISOString());
     }
     setSessionStatus(id, status) {
-        this.pendingSessionTouches.delete(id);
+        const sessionId = this.resolveSessionId(id);
+        if (!sessionId)
+            return;
+        this.pendingSessionTouches.delete(sessionId);
         this.database.db
             .update(workspaceSessions)
             .set({ status, lastUsedAt: this.now().toISOString() })
-            .where(eq(workspaceSessions.id, id))
+            .where(eq(workspaceSessions.id, sessionId))
             .run();
     }
     listSessions(input = {}) {
@@ -100,11 +109,56 @@ export class SqliteWorkspaceStore {
             .map((session) => applySessionTouch(session, this.pendingSessionTouches.get(session.id)))
             .sort((left, right) => right.lastUsedAt.localeCompare(left.lastUsedAt));
     }
+    foldSessions(input) {
+        const aliases = input.aliasIds.filter((id) => id !== input.canonicalId);
+        if (aliases.length === 0)
+            return;
+        const fold = this.database.sqlite.transaction(() => {
+            this.database.sqlite.prepare(`
+        update workspace_sessions
+           set created_at = ?, last_used_at = ?, status = ?
+         where id = ?
+      `).run(input.createdAt, input.lastUsedAt, input.status, input.canonicalId);
+            const rebindConversation = this.database.sqlite.prepare(`
+        update workspace_conversation_bindings
+           set workspace_session_id = ?
+         where workspace_session_id = ?
+      `);
+            const rebindSubagents = this.database.sqlite.prepare(`
+        update local_agent_sessions
+           set workspace_id = ?
+         where workspace_id = ?
+      `);
+            const rebindAliases = this.database.sqlite.prepare(`
+        update workspace_session_aliases
+           set workspace_session_id = ?
+         where workspace_session_id = ?
+      `);
+            const deleteSession = this.database.sqlite.prepare("delete from workspace_sessions where id = ?");
+            const rememberAlias = this.database.sqlite.prepare(`
+        insert into workspace_session_aliases (alias_id, workspace_session_id)
+        values (?, ?)
+        on conflict(alias_id) do update set workspace_session_id = excluded.workspace_session_id
+      `);
+            for (const aliasId of aliases) {
+                rebindConversation.run(input.canonicalId, aliasId);
+                rebindSubagents.run(input.canonicalId, aliasId);
+                rebindAliases.run(input.canonicalId, aliasId);
+                deleteSession.run(aliasId);
+                rememberAlias.run(aliasId, input.canonicalId);
+                this.pendingSessionTouches.delete(aliasId);
+            }
+        });
+        fold.immediate();
+    }
     deleteSession(id) {
-        this.pendingSessionTouches.delete(id);
+        const sessionId = this.resolveSessionId(id);
+        if (!sessionId)
+            return;
+        this.pendingSessionTouches.delete(sessionId);
         this.database.db
             .delete(workspaceSessions)
-            .where(eq(workspaceSessions.id, id))
+            .where(eq(workspaceSessions.id, sessionId))
             .run();
     }
     listConversationBindings() {
@@ -212,6 +266,21 @@ export class SqliteWorkspaceStore {
             .where(and(eq(workspaceContextDeliveries.conversationScopeId, conversationScopeId), eq(workspaceContextDeliveries.targetKey, targetKey)))
             .run();
     }
+    resolveSessionId(id) {
+        const direct = this.database.db
+            .select({ id: workspaceSessions.id })
+            .from(workspaceSessions)
+            .where(eq(workspaceSessions.id, id))
+            .get();
+        if (direct)
+            return direct.id;
+        return this.database.db
+            .select({ workspaceSessionId: workspaceSessionAliases.workspaceSessionId })
+            .from(workspaceSessionAliases)
+            .where(eq(workspaceSessionAliases.aliasId, id))
+            .get()
+            ?.workspaceSessionId;
+    }
     get pendingTouchCount() {
         return this.pendingSessionTouches.size + this.pendingConversationTouches.size;
     }

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());
@@ -205,22 +207,23 @@ 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 instead of releasing the physical target as a separate handle.`);
             }
         }
         if (this.store) {
             for (const binding of this.store.listConversationBindings()) {
-                if (binding.workspaceSessionId === workspaceId) {
+                if (binding.workspaceSessionId === canonicalWorkspaceId) {
                     this.store.deleteConversationBinding(binding.conversationScopeId, binding.targetKey);
                 }
             }
-            this.store.deleteSession(workspaceId);
+            this.store.deleteSession(canonicalWorkspaceId);
         }
-        this.workspaces.delete(workspaceId);
+        this.workspaces.delete(canonicalWorkspaceId);
     }
     workspaceIdsForPhysicalWorkspace(workspace) {
         const root = resolve(workspace.root);
@@ -325,30 +328,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 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");
             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 +352,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 +375,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 +420,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,10 +512,41 @@ export class WorkspaceRegistry {
                 worktreeAnchors.get(resolve(session.root))?.id === session.id) {
                 continue;
             }
-            this.store.deleteSession(session.id);
             this.workspaces.delete(session.id);
         }
     }
+    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) {
         for (const session of this.activeSessions(mode)) {
             const root = await this.validSessionRoot(session);
@@ -623,14 +616,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);
@@ -1036,6 +1021,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,20 @@ 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.
+
+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.
 
 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,20 +327,21 @@ 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.
+`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.
 
-`close_workspace` removes a checkout-backed logical handle without deleting checkout
-files. For a managed-worktree-backed workspace, `close_workspace` requires
+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
@@ -366,7 +370,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

package/docs/roadmap.md

@@ -284,6 +284,34 @@ Git state, processes, Hooks, Skills, Language services, Activity, and Audit fact
 Workspace Relay is not file synchronization or failover, and Composite Workspace
 never silently chooses a member.
 
+## 0.8 — Persistent Workspace lifecycle and Task Lists
+
+0.8 turns Workspace identity from a disposable logical handle into a persistent
+ForgeRelay work boundary, then layers lightweight Workspace-owned Task Lists and
+safe cross-Workspace inspection on top. Development is release-gated: each stage
+must be published successfully before work begins on the next stage.
+
+- **0.8.0** — fix Composite bootstrap correctness and establish one canonical,
+  persistent Workspace identity per physical checkout/worktree target, including
+  migration compatibility for legacy aliases;
+- **0.8.1** — make checkout close non-destructive and reversible, add explicit
+  Workspace deletion, and prevent GC from deleting persistent Workspace identity;
+- **0.8.2** — carry the persistent lifecycle through managed worktrees and Composite
+  Workspaces, preserving state across close/reopen while keeping safe worktree
+  finalize semantics;
+- **0.8.3** — add versioned file-backed Task Lists in ForgeRelay-owned Workspace
+  state, with mutations scoped to the current Workspace;
+- **0.8.4** — add progressive Task disclosure, forgotten-update reminders, and
+  allowlist-based read-only inspection of other Workspaces and their safe Task
+  projections;
+- **0.8.5** — verify the complete contract across Workspace Relay and publish the
+  accepted 0.8 lifecycle/Task model.
+
+The release boundary is part of the dependency graph, not just a documentation
+milestone: the next stage remains blocked until the previous version's tag-triggered
+release workflow has completed successfully. Runtime acceptance uses only the
+reserved 7677/7678 debug instances and never touches the normal 7676 installation.
+
 ## Later: first-class subagent MCP
 
 ForgeRelay already owns provider adapters and resumable local agent sessions. A
@@ -311,20 +339,20 @@ are ready:
 Checkpoint restore must protect concurrent/external user edits rather than
 blindly overwriting a working tree.
 
-## Later: task orchestration
+## Workspace Task Lists
 
-After first-class subagents are stable, ForgeRelay may add a small persistent
-task graph for parent/worker coordination:
+ForgeRelay may provide persistent, lightweight Task Lists owned by a Workspace for
+work that should survive Host Turns, conversation changes, and Workspace close.
+Task is a checklist/continuation primitive rather than an execution scheduler:
 
-- task identity/title/status;
-- dependencies;
-- assigned local-agent session;
-- workspace/worktree association;
-- structured result/error state.
+- one Workspace may own multiple named Task Lists;
+- a Task records a work requirement, lightweight progress state, and Agent-managed continuation text;
+- Task does not imply a Queue, Goal object, dependency graph, Subagent assignment, Run binding, or autonomous execution policy;
+- current-Workspace Task state may be mutated through a Capability, while information about another Workspace, including Task projections, is exposed only through the read-only Workspace inspection path;
+- Task state is durable Workspace-owned local state and is not deleted by ordinary Workspace close or GC.
 
-Start with DAG-style parent/child orchestration. Peer-to-peer agent-team messaging
-should only be added if real workflows demonstrate that the simpler task model is
-insufficient.
+Subagent coordination can reference Task content when useful, but ForgeRelay does
+not bind Tasks to Subagent Sessions or infer Task completion from execution facts.
 
 ## Compatibility policy
 

package/docs/security.md

@@ -144,10 +144,10 @@ process lifetime. When `bash` is still running after that window, ForgeRelay
 returns a canonical `processId` and leaves the process alive. Regular tool modes
 reuse `bash(action="process")` to poll, wait, write input, resize a PTY, or
 explicitly interrupt that process. An asynchronously completed process
-is reported on a later tool result for the same logical workspace ID, including
-error-result paths, and is never broadcast to another workspace ID. Explicitly
-resuming the same workspace ID in another conversation intentionally transfers
-that completion scope as well. Hook handlers keep their separate bounded timeout
+is reported on a later tool result for the same persistent Workspace ID, including
+error-result paths, and is never broadcast to another Workspace ID. Reusing that
+Workspace from another conversation intentionally shares the same completion scope
+as well. Hook handlers keep their separate bounded timeout
 policy because they are lifecycle gates rather than user-command execution.
 
 ## Lifecycle hooks

package/package.json

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