@akira-tl/forgerelay 0.8.1 → 0.8.3

package/dist/server.js

@@ -21,7 +21,7 @@ import { HostTurnStore } from "./activity/host-turn-store.js";
 import { registerActivityQueryTools } from "./activity/mcp-query-tools.js";
 import { ActivityLifecycle, } from "./activity/lifecycle.js";
 import { ActivityQueryService } from "./activity/query-service.js";
-import { buildCapabilityFingerprint } from "./capabilities.js";
+import { buildCapabilityFingerprint, loadCapabilityGuides } from "./capabilities.js";
 import { CapabilityError, createCapabilityRegistry, } from "./capability-registry.js";
 import { deletePath, renamePath } from "./file-mutations.js";
 import { downloadIncomingArtifact, isArtifactDownloadSupportedPlatform, } from "./artifact-tools.js";
@@ -53,6 +53,7 @@ import { ACTIVITY_PANEL_APP_LEGACY_URI, ACTIVITY_PANEL_APP_URI_TEMPLATE, MCP_APP
 import { shutdownHttpServer } from "./server-shutdown.js";
 import { formatPathForPrompt } from "./skills.js";
 import { createWorkspaceStore } from "./workspace-store.js";
+import { WorkspaceTaskStore } from "./workspace-tasks.js";
 import { formatAgentsPath, WorkspaceRegistry } from "./workspaces.js";
 import { formatAvailableSubagentProfile, summarizeSubagentProfile } from "./subagents/profiles.js";
 import { formatSubagentProviderAvailabilitySummary, formatUnavailableSubagentProvider, getSubagentProviderAvailabilitySnapshot, } from "./subagents/providers/availability.js";
@@ -821,6 +822,7 @@ function workspaceHookInvocation(workspace) {
 function capabilityContextFor(workspace) {
     return {
         workspaceId: workspace.id,
+        workspaceKind: "workspace",
         workspaceRoot: workspace.root,
         guides: workspace.capabilityGuides.map((guide) => ({
             name: guide.name,
@@ -830,6 +832,56 @@ function capabilityContextFor(workspace) {
         })),
     };
 }
+function compositeCapabilityContext(workspaceId, guides) {
+    return {
+        workspaceId,
+        workspaceKind: "composite",
+        guides: guides.map((guide) => ({
+            name: guide.name,
+            description: guide.description,
+            whenToRead: guide.whenToRead,
+            path: formatPathForPrompt(guide.filePath),
+        })),
+    };
+}
+function requireCapabilityWorkspaceRoot(context) {
+    if (!context.workspaceRoot) {
+        throw new CapabilityError("capability_unavailable", `Capability execution requires a filesystem-backed Workspace; ${context.workspaceId} is ${context.workspaceKind}.`);
+    }
+    return context.workspaceRoot;
+}
+function runWorkspaceTasksCapability(store, workspaceId, input) {
+    switch (input.operation) {
+        case "get":
+            return store.read(workspaceId);
+        case "list.create":
+            return store.createList(workspaceId, { name: input.name, position: input.position });
+        case "list.update":
+            return store.updateList(workspaceId, input.listId, {
+                name: input.name,
+                state: input.state,
+                position: input.position,
+            });
+        case "list.delete":
+            return store.deleteList(workspaceId, input.listId);
+        case "task.create":
+            return store.createTask(workspaceId, input.listId, {
+                subject: input.subject,
+                content: input.content,
+                status: input.status,
+                position: input.position,
+            });
+        case "task.update":
+            return store.updateTask(workspaceId, input.listId, input.taskId, {
+                subject: input.subject,
+                content: input.content,
+                status: input.status,
+                position: input.position,
+            });
+        case "task.delete":
+            return store.deleteTask(workspaceId, input.listId, input.taskId);
+    }
+}
 async function reviewWorkspaceChanges(reviewCheckpoints, workspace) {
     return reviewCheckpoints.reviewChanges({
         workspaceId: workspace.id,
@@ -1192,6 +1244,8 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
     const connectionScopeId = `mcp-connection:${randomUUID()}`;
     const remoteWorkspaces = new RemoteWorkspaceRelay(config.configDir, config.stateDir);
     const compositeWorkspaces = new CompositeWorkspaceRegistry(config.stateDir);
+    const workspaceTasks = new WorkspaceTaskStore(config.stateDir);
+    const compositeTaskGuides = loadCapabilityGuides(config).filter((guide) => guide.name === "workspace-tasks");
     const compositeActivity = new CompositeActivityCoordinator(compositeWorkspaces, activityQueries, remoteWorkspaces);
     const resolveExecutionTarget = (workspaceId, memberName) => {
         if (!compositeWorkspaces.has(workspaceId)) {
@@ -1248,6 +1302,12 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
     const capabilityRegistry = createCapabilityRegistry({
         inspectHooks: (workspaceRoot) => checkHookConfiguration(workspaceRoot, config.hooks),
         ...subagentMcp.registryDependencies,
+        workspaceTasks: {
+            available: true,
+            run: async (input, context) => ({
+                value: runWorkspaceTasksCapability(workspaceTasks, context.workspaceId, input),
+            }),
+        },
         batchExecute: {
             available: batchExecuteAvailable,
             unavailableReason: batchExecuteAvailable
@@ -1270,7 +1330,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             run: async (input, context, options) => {
                 try {
                     return {
-                        value: await codeIntelligence.run(context.workspaceRoot, input, { signal: options.signal }),
+                        value: await codeIntelligence.run(requireCapabilityWorkspaceRoot(context), input, { signal: options.signal }),
                     };
                 }
                 catch (error) {
@@ -1289,7 +1349,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             run: async (context) => {
                 const review = await reviewWorkspaceChanges(reviewCheckpoints, {
                     id: context.workspaceId,
-                    root: context.workspaceRoot,
+                    root: requireCapabilityWorkspaceRoot(context),
                 });
                 return {
                     value: {
@@ -1317,7 +1377,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     const downloaded = await downloadIncomingArtifact({
                         registry: incomingArtifactRegistry,
                         workspaceId: context.workspaceId,
-                        workspaceRoot: context.workspaceRoot,
+                        workspaceRoot: requireCapabilityWorkspaceRoot(context),
                         maxFileBytes: config.artifactMaxFileBytes,
                         file: input.file,
                         path: input.path,
@@ -2078,6 +2138,8 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             memberAction: z.enum(["add", "update", "remove"]).optional(),
             kind: z.enum(["workspace", "composite"]).optional(),
             name: z.string().optional(),
+            status: z.string().optional(),
+            state: z.enum(["active", "stale", "invalid", "closed"]).optional(),
             members: z.array(z.object({
                 name: z.string(),
                 purpose: z.string(),
@@ -2134,6 +2196,8 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 workspaceId: z.string(),
                 kind: z.literal("composite"),
                 name: z.string(),
+                status: z.enum(["active", "closed"]),
+                state: z.enum(["active", "closed"]),
                 members: z.array(z.object({
                     name: z.string(),
                     purpose: z.string(),
@@ -2161,6 +2225,9 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             if (!workspaceId || !compositeWorkspaces.has(workspaceId)) {
                 throw new Error("open_workspace action=member requires an existing Composite Workspace workspaceId.");
             }
+            if (!compositeWorkspaces.isActive(workspaceId)) {
+                throw new Error(`Composite Workspace ${workspaceId} is closed. Reopen it with open_workspace before changing members.`);
+            }
             if (!memberAction || !member) {
                 throw new Error("open_workspace action=member requires memberAction and member.");
             }
@@ -2294,25 +2361,30 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 newWorkspace !== undefined || context !== undefined) {
                 throw new Error("open_workspace action=list does not accept path, relay, name, memberName, baseRef, newWorktree, newWorkspace, or context. Use kind/root/workspaceId/mode/status/state/staleOnly for inventory filters.");
             }
+            const compositeInventory = () => compositeWorkspaces.list()
+                .filter((entry) => workspaceId === undefined || entry.id === workspaceId)
+                .filter((entry) => status === undefined || entry.status === status)
+                .filter((entry) => state === undefined || entry.status === state)
+                .map((entry) => ({
+                workspaceId: entry.id,
+                kind: entry.kind,
+                name: entry.name,
+                status: entry.status,
+                state: entry.status,
+                members: entry.members,
+                createdAt: entry.createdAt,
+                lastUsedAt: entry.lastUsedAt,
+            }));
             if (kind === "composite") {
-                if (root !== undefined || mode !== undefined || status !== undefined || state !== undefined ||
-                    staleOnly !== undefined || offset !== undefined || limit !== undefined) {
-                    throw new Error("Composite Workspace inventory does not accept root/mode/status/state/staleOnly/offset/limit filters; use workspaceId when selecting one Composite Workspace.");
+                if (root !== undefined || mode !== undefined || staleOnly !== undefined ||
+                    offset !== undefined || limit !== undefined) {
+                    throw new Error("Composite Workspace inventory does not accept root/mode/staleOnly/offset/limit filters; use workspaceId/status/state when selecting Composite Workspaces.");
                 }
-                const composites = compositeWorkspaces.list()
-                    .filter((entry) => workspaceId === undefined || entry.id === workspaceId)
-                    .map((entry) => ({
-                    workspaceId: entry.id,
-                    kind: entry.kind,
-                    name: entry.name,
-                    members: entry.members,
-                    createdAt: entry.createdAt,
-                    lastUsedAt: entry.lastUsedAt,
-                }));
-                const instruction = "Resume a Composite Workspace with open_workspace(action=\"open\", workspaceId=...). Use close_workspace only when the user chooses to dissolve it.";
+                const composites = compositeInventory();
+                const instruction = "Open a Composite Workspace by workspaceId to resume or reopen it. close_workspace preserves its identity; action=delete permanently dissolves only Composite-owned state.";
                 const result = [
                     `Composite Workspace inventory: ${composites.length} matching record${composites.length === 1 ? "" : "s"}.`,
-                    ...composites.map((entry) => `${entry.name} [${entry.workspaceId}] members=${entry.members.length} last-used=${entry.lastUsedAt}`),
+                    ...composites.map((entry) => `${entry.name} [${entry.workspaceId}] state=${entry.state} members=${entry.members.length} last-used=${entry.lastUsedAt}`),
                     instruction,
                 ].join("\n");
                 return {
@@ -2325,20 +2397,13 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 };
             }
             const inventory = await workspaces.listWorkspaces({ workspaceId, mode, root, status, state, staleOnly, offset, limit }, { conversationScopeId, protectedWorkspaceIds });
-            const composites = kind === "workspace"
+            const composites = kind === "workspace" || root !== undefined || mode !== undefined || staleOnly
                 ? []
-                : compositeWorkspaces.list().map((entry) => ({
-                    workspaceId: entry.id,
-                    kind: entry.kind,
-                    name: entry.name,
-                    members: entry.members,
-                    createdAt: entry.createdAt,
-                    lastUsedAt: entry.lastUsedAt,
-                }));
+                : compositeInventory();
             const nextOffset = inventory.page.offset + inventory.page.limit;
             const instruction = [
                 "Resume a selected workspaceId with open_workspace(action=\"open\", workspaceId=...).",
-                "Use close_workspace only after the user chooses cleanup or Composite dissolution; never close inventory entries automatically.",
+                "Use close_workspace only after the user chooses cleanup; Composite close preserves identity, while action=delete dissolves only Composite-owned state. Never close inventory entries automatically.",
                 inventory.page.hasMore
                     ? `More matching workspaces are available; continue with offset=${nextOffset}.`
                     : undefined,
@@ -2356,7 +2421,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     `root=${entry.root}`,
                     `last-used=${entry.lastUsedAt}`,
                 ].filter(Boolean).join(" ")),
-                ...composites.map((entry) => `${entry.name} [${entry.workspaceId}] kind=composite members=${entry.members.length}`),
+                ...composites.map((entry) => `${entry.name} [${entry.workspaceId}] kind=composite state=${entry.state} members=${entry.members.length}`),
                 instruction,
             ].join("\n");
             logToolCall(config, {
@@ -2393,6 +2458,15 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             const composite = workspaceId !== undefined
                 ? compositeWorkspaces.open(workspaceId)
                 : compositeWorkspaces.create(name ?? "");
+            workspaceTasks.initializeWorkspace(composite.id);
+            const compositeTaskContext = compositeCapabilityContext(composite.id, compositeTaskGuides);
+            const compositeCapabilityCatalog = capabilityRegistry.catalog(compositeTaskContext);
+            const compositeCapabilityGuides = compositeTaskGuides.map((guide) => ({
+                name: guide.name,
+                description: guide.description,
+                whenToRead: guide.whenToRead,
+                path: formatPathForPrompt(guide.filePath),
+            }));
             const memberContext = memberName
                 ? await loadCompositeMemberContext(composite.id, memberName, context ?? "auto", conversationScopeId, protectedWorkspaceIds)
                 : undefined;
@@ -2403,10 +2477,13 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     ? `Members: ${composite.members.map((member) => `${member.name} — ${member.purpose}`).join("; ")}.`
                     : "This Composite Workspace currently has no members.",
                 "Member names and purposes are structural context and are always returned when this Composite Workspace is opened. context=auto/full/none controls only heavy member bootstrap context, not this Composite identity.",
+                compositeCapabilityCatalog.length > 0
+                    ? `Composite-owned capabilities: ${compositeCapabilityCatalog.map((entry) => entry.name).join(", ")}. Use these without member because their state belongs to the Composite Workspace itself.`
+                    : undefined,
                 composite.members.length > 0
                     ? "Before first work on a member, reopen this Composite Workspace with memberName=<member> and context=auto to receive that member's project bootstrap without creating an implicit current member."
                     : undefined,
-                "Use close_workspace only when the user chooses to dissolve this Composite Workspace; dissolution does not close or clean up member Workspaces.",
+                "close_workspace preserves this Composite identity for later reopen. Use action=delete only when the user explicitly wants to dissolve the Composite relationship; neither operation closes or cleans up member Workspaces.",
             ].join("\n\n");
             const response = {
                 content: [textBlock(instruction)],
@@ -2419,7 +2496,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                         path: composite.name,
                         members: composite.members,
                         instruction,
-                        summary: { members: composite.members.length },
+                        summary: { members: composite.members.length, status: composite.status },
                     },
                 },
                 structuredContent: {
@@ -2427,7 +2504,11 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     workspaceId: composite.id,
                     kind: "composite",
                     name: composite.name,
+                    status: composite.status,
+                    state: composite.status,
                     members: composite.members,
+                    capabilityCatalog: compositeCapabilityCatalog,
+                    capabilityGuides: compositeCapabilityGuides,
                     ...(memberContext ? { memberContext } : {}),
                     instruction,
                 },
@@ -2540,6 +2621,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             conversationScopeId,
             protectedWorkspaceIds,
         });
+        workspaceTasks.initializeWorkspace(workspace.id);
         const knownWorktrees = await workspaces.listKnownWorktrees(workspace);
         const staleWorkspaces = await workspaces.listStaleWorkspaces(workspace);
         const capabilityFingerprint = buildCapabilityFingerprint(config, FORGERELAY_VERSION, {
@@ -2801,6 +2883,74 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             openWorldHint: true,
         },
     }, async ({ workspaceId, member, name, action, arguments: capabilityArguments, file }, extra) => {
+        if (name === "workspace.tasks" && compositeWorkspaces.has(workspaceId)) {
+            if (member !== undefined) {
+                throw new Error(`workspace.tasks belongs to Composite Workspace ${workspaceId} itself and does not accept member.`);
+            }
+            if (!compositeWorkspaces.isActive(workspaceId)) {
+                throw new Error(`Composite Workspace ${workspaceId} is closed. Reopen it with open_workspace before use.`);
+            }
+            const startedAt = performance.now();
+            const context = compositeCapabilityContext(workspaceId, compositeTaskGuides);
+            try {
+                if (action === "run") {
+                    const execution = await capabilityRegistry.run(name, capabilityArguments ?? {}, context, {
+                        nativeFile: file,
+                        signal: extra.signal,
+                        requestMeta: extra._meta,
+                        sessionId: extra.sessionId,
+                    });
+                    const result = {
+                        content: [textBlock(`Capability ${name} completed.\n${JSON.stringify(execution.value, null, 2)}`)],
+                        structuredContent: { name, action, result: execution.value },
+                    };
+                    logToolCall(config, {
+                        tool: toolNames.capability,
+                        capability: name,
+                        action,
+                        success: true,
+                        durationMs: Math.round(performance.now() - startedAt),
+                    });
+                    return result;
+                }
+                const capability = capabilityRegistry.describe(name, context);
+                const result = {
+                    content: [textBlock([
+                            `${capability.name}: ${capability.description}`,
+                            `Available: ${capability.available}`,
+                            `Guide: ${capability.guide.path}`,
+                            capability.guide.readBeforeFirstUse
+                                ? "Read the guide before first use when this contract is unfamiliar."
+                                : undefined,
+                        ].filter(Boolean).join("\n"))],
+                    structuredContent: { name, action, capability },
+                };
+                logToolCall(config, {
+                    tool: toolNames.capability,
+                    capability: name,
+                    action,
+                    success: true,
+                    durationMs: Math.round(performance.now() - startedAt),
+                });
+                return result;
+            }
+            catch (error) {
+                if (extra.signal.aborted)
+                    throw error;
+                const capabilityError = error instanceof CapabilityError
+                    ? error
+                    : new CapabilityError("execution_failed", error instanceof Error ? error.message : String(error));
+                return {
+                    content: [textBlock(`${capabilityError.code}: ${capabilityError.message}`)],
+                    structuredContent: {
+                        name,
+                        action,
+                        error: { code: capabilityError.code, message: capabilityError.message },
+                    },
+                    isError: true,
+                };
+            }
+        }
         const target = resolveExecutionTarget(workspaceId, member);
         const executionWorkspaceId = target.executionWorkspaceId;
         const executionContext = await prepareExecutionContext(target, extra._meta, extra.signal, extra.sessionId);
@@ -2921,13 +3071,13 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
     });
     registerAppTool(server, toolNames.closeWorkspace, {
         title: "Close workspace",
-        description: "Close or explicitly delete one Workspace after the user chooses cleanup. action=close (default) preserves checkout identity for later reopen. action=delete permanently removes ForgeRelay-owned checkout state but never project files. Managed-worktree-backed Workspaces still use the safe finalize lifecycle and require commitMessage; Composite and relayed delete semantics are not available in this stage.",
+        description: "Close or explicitly delete one Workspace after the user chooses cleanup. action=close (default) preserves checkout, managed-worktree, and Composite identity for later reopen. action=delete permanently removes ForgeRelay-owned state. Managed-worktree-backed Workspaces still finalize safely when active and require commitMessage. Composite delete dissolves only Composite-owned state and never closes member Workspaces. Checkout project files are never deleted; relayed delete remains unavailable.",
         inputSchema: {
             workspaceId: z.string().describe("Workspace identifier to close or delete."),
             action: z
                 .enum(["close", "delete"])
                 .optional()
-                .describe("Defaults to close. close preserves checkout identity for later reopen; delete permanently removes ForgeRelay-owned checkout state without deleting project files."),
+                .describe("Defaults to close. close preserves checkout identity, managed-worktree identity, and Composite identity for later reopen; delete removes ForgeRelay-owned state. Composite delete dissolves only the Composite relationship. Active managed worktrees still require safe finalization and commitMessage; checkout project files are never deleted."),
             commitMessage: z
                 .string()
                 .min(1)
@@ -2945,6 +3095,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 purpose: z.string(),
                 workspaceId: z.string(),
             })).optional(),
+            status: z.enum(["active", "closed"]).optional(),
             dissolved: z.boolean().optional(),
             sourceRoot: z.string().optional(),
             branch: z.string().optional(),
@@ -2958,21 +3109,24 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         annotations: WRITE_TOOL_ANNOTATIONS,
     }, async ({ workspaceId, action = "close", commitMessage }, extra) => {
         if (compositeWorkspaces.has(workspaceId)) {
-            if (action === "delete") {
-                throw new Error("close_workspace action=delete is not available for Composite Workspaces until the Composite persistent lifecycle stage.");
-            }
             if (commitMessage !== undefined) {
-                throw new Error("close_workspace commitMessage is not valid when dissolving a Composite Workspace.");
+                throw new Error("close_workspace commitMessage is not valid for a Composite Workspace.");
             }
-            const composite = compositeWorkspaces.dissolve(workspaceId);
+            const composite = action === "delete"
+                ? compositeWorkspaces.dissolve(workspaceId)
+                : compositeWorkspaces.close(workspaceId);
+            if (action === "delete")
+                workspaceTasks.deleteWorkspace(workspaceId);
             compositeActivity.forgetComposite(workspaceId);
             workspacePanelStates.delete(workspaceId);
             const result = [
-                `Dissolved Composite Workspace ${composite.name} (${workspaceId}).`,
+                action === "delete"
+                    ? `Deleted Composite Workspace ${composite.name} (${workspaceId}); its Composite relationship and ForgeRelay-owned Composite state were dissolved.`
+                    : `Closed Composite Workspace ${composite.name} (${workspaceId}); its identity and member topology were preserved for later reopen.`,
                 composite.members.length > 0
                     ? `Preserved member Workspaces: ${composite.members.map((member) => `${member.name} [${member.workspaceId}]`).join(", ")}.`
                     : "The Composite Workspace had no members.",
-                "Member Workspace handles, managed worktrees, processes, files, and Workspace Relay routes were not closed or cleaned up.",
+                "Member Workspace handles, managed worktrees, processes, files, and Workspace Relay routes were not closed, finalized, deleted, or otherwise mutated.",
             ].join("\n");
             return {
                 content: [textBlock(result)],
@@ -2980,22 +3134,24 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     tool: toolNames.closeWorkspace,
                     card: {
                         workspaceId,
-                        action: "close",
+                        action,
                         kind: "composite",
                         name: composite.name,
                         members: composite.members,
-                        dissolved: true,
+                        ...(action === "close" ? { status: "closed" } : {}),
+                        dissolved: action === "delete",
                         payload: { content: [textBlock(result)] },
                     },
                 },
                 structuredContent: {
                     result,
                     workspaceId,
-                    action: "close",
+                    action,
                     kind: "composite",
                     name: composite.name,
                     members: composite.members,
-                    dissolved: true,
+                    ...(action === "close" ? { status: "closed" } : {}),
+                    dissolved: action === "delete",
                 },
             };
         }
@@ -3007,14 +3163,11 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             workspacePanelStates.delete(workspaceId);
             return response;
         }
-        if (action === "delete") {
+        const session = workspaces.getWorkspaceSession(workspaceId);
+        if (action === "delete" && session.mode === "checkout") {
             if (commitMessage !== undefined) {
                 throw new Error("close_workspace commitMessage is not valid with action=delete for a checkout Workspace.");
             }
-            const session = workspaces.getWorkspaceSession(workspaceId);
-            if (session.mode !== "checkout") {
-                throw new Error("close_workspace action=delete is not available for managed-worktree-backed Workspaces until their persistent lifecycle stage.");
-            }
             if (processSessions.activeWorkspaceIds().has(session.id)) {
                 throw new Error(`Workspace ${session.id} still owns a running process. Poll, interrupt, or wait for it before deleting this Workspace.`);
             }
@@ -3030,6 +3183,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 payload: { workspaceId: session.id, action: "delete", mode: session.mode },
                 operation: async () => {
                     workspaces.deleteWorkspace(session.id);
+                    workspaceTasks.deleteWorkspace(session.id);
                     await reviewCheckpoints.releaseWorkspace(session.id);
                     const result = `Deleted ForgeRelay Workspace ${session.id}. Physical project files were not removed.`;
                     return {
@@ -3055,12 +3209,59 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             workspacePanelStates.delete(session.id);
             return response;
         }
-        const workspace = workspaces.getWorkspace(workspaceId);
+        if (action === "delete" && session.mode === "worktree" && session.status === "closed") {
+            if (commitMessage !== undefined) {
+                throw new Error("close_workspace commitMessage is not needed when deleting an already-closed managed-worktree Workspace.");
+            }
+            const hookRoot = session.sourceRoot ?? session.root;
+            const response = await runToolWithHooks(hooks, {
+                signal: extra.signal,
+                tool: toolNames.closeWorkspace,
+                invocation: {
+                    workspaceId: session.id,
+                    workspaceRoot: hookRoot,
+                    workspaceMode: session.mode,
+                    sourceRoot: session.sourceRoot,
+                },
+                payload: { workspaceId: session.id, action: "delete", mode: session.mode },
+                operation: async () => {
+                    workspaces.deleteWorkspace(session.id);
+                    workspaceTasks.deleteWorkspace(session.id);
+                    await reviewCheckpoints.releaseWorkspace(session.id);
+                    const result = `Deleted closed managed-worktree Workspace ${session.id}. Its already-removed worktree backing was not recreated.`;
+                    return {
+                        content: [textBlock(result)],
+                        _meta: {
+                            tool: toolNames.closeWorkspace,
+                            card: {
+                                workspaceId: session.id,
+                                action: "delete",
+                                mode: "worktree",
+                                sourceRoot: session.sourceRoot,
+                                targetBranch: session.targetBranch,
+                                payload: { content: [textBlock(result)] },
+                            },
+                        },
+                        structuredContent: {
+                            result,
+                            workspaceId: session.id,
+                            action: "delete",
+                            mode: "worktree",
+                            sourceRoot: session.sourceRoot,
+                            targetBranch: session.targetBranch,
+                        },
+                    };
+                },
+            });
+            workspacePanelStates.delete(session.id);
+            return response;
+        }
+        const workspace = workspaces.getWorkspace(session.id);
         const response = await runToolWithHooks(hooks, {
             signal: extra.signal,
             tool: toolNames.closeWorkspace,
             invocation: workspaceHookInvocation(workspace),
-            payload: { workspaceId, action: "close", commitMessage, mode: workspace.mode },
+            payload: { workspaceId: workspace.id, action, commitMessage, mode: workspace.mode },
             afterCwd: (response) => "sourceRoot" in response.structuredContent &&
                 typeof response.structuredContent.sourceRoot === "string"
                 ? response.structuredContent.sourceRoot
@@ -3068,7 +3269,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             operation: async () => {
                 if (workspace.mode === "worktree") {
                     if (!commitMessage) {
-                        throw new Error(`Managed-worktree-backed workspace ${workspaceId} requires commitMessage when closing.`);
+                        throw new Error(`Managed-worktree-backed Workspace ${workspace.id} requires commitMessage when ${action === "delete" ? "deleting active work" : "closing"}.`);
                     }
                     const physicalWorkspaceIds = workspaces.workspaceIdsForPhysicalWorkspace(workspace);
                     const busyWorkspaceIds = physicalWorkspaceIds
@@ -3080,14 +3281,20 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     const retirement = await codeIntelligence.retireWorkspaceRoot(workspace.root);
                     let closed;
                     try {
-                        closed = await workspaces.closeWorktree(workspaceId, commitMessage);
+                        closed = await workspaces.closeWorktree(workspace.id, commitMessage);
                     }
                     finally {
                         codeIntelligence.restoreWorkspaceRoot(retirement.root);
                     }
                     await Promise.all(physicalWorkspaceIds.map((id) => reviewCheckpoints.releaseWorkspace(id)));
+                    if (action === "delete") {
+                        workspaces.deleteWorkspace(workspace.id);
+                        workspaceTasks.deleteWorkspace(workspace.id);
+                    }
                     const result = [
-                        `Closed managed-worktree-backed workspace ${workspaceId}.`,
+                        action === "delete"
+                            ? `Safely finalized and deleted managed-worktree Workspace ${workspace.id}.`
+                            : `Closed managed-worktree-backed Workspace ${workspace.id}; its identity was preserved for later reopen.`,
                         `Merged ${closed.branch} into ${closed.targetBranch} by fast-forward.`,
                         `Source checkout: ${closed.sourceRoot}`,
                         `Commit: ${closed.commitSha}`,
@@ -3107,8 +3314,8 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                         _meta: {
                             tool: toolNames.closeWorkspace,
                             card: {
-                                workspaceId,
-                                action: "close",
+                                workspaceId: workspace.id,
+                                action,
                                 mode: "worktree",
                                 sourceRoot: closed.sourceRoot,
                                 branch: closed.branch,
@@ -3122,8 +3329,8 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                         },
                         structuredContent: {
                             result,
-                            workspaceId,
-                            action: "close",
+                            workspaceId: workspace.id,
+                            action,
                             mode: "worktree",
                             sourceRoot: closed.sourceRoot,
                             branch: closed.branch,
@@ -3178,7 +3385,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             member: z
                 .string()
                 .optional()
-                .describe("Required for a Composite Workspace; explicit member name that owns this operation."),
+                .describe("Required for Composite member-scoped file reads. Omit only when reading an advertised Composite-owned capability guide."),
             path: z
                 .string()
                 .optional()
@@ -3220,6 +3427,29 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         if ((path === undefined) === (paths === undefined)) {
             throw new Error("read requires exactly one of path or paths.");
         }
+        if (compositeWorkspaces.has(workspaceId) && member === undefined && path !== undefined) {
+            const guide = compositeTaskGuides.find((candidate) => formatPathForPrompt(candidate.filePath) === path || candidate.filePath === path);
+            if (guide) {
+                if (!compositeWorkspaces.isActive(workspaceId)) {
+                    throw new Error(`Composite Workspace ${workspaceId} is closed. Reopen it with open_workspace before use.`);
+                }
+                const startedAt = performance.now();
+                const raw = readFileSync(guide.filePath, "utf8");
+                const start = (offset ?? 1) - 1;
+                const end = limit === undefined ? undefined : start + limit;
+                const result = raw.split("\n").slice(start, end).join("\n");
+                logToolCall(config, {
+                    tool: toolNames.read,
+                    path: formatPathForPrompt(guide.filePath),
+                    success: true,
+                    durationMs: Math.round(performance.now() - startedAt),
+                });
+                return {
+                    content: [textBlock(result)],
+                    structuredContent: { result },
+                };
+            }
+        }
         const target = resolveExecutionTarget(workspaceId, member);
         const executionWorkspaceId = target.executionWorkspaceId;
         const executionContext = await prepareExecutionContext(target, extra._meta, extra.signal, extra.sessionId);

package/dist/subagents/sessions/capability.js

@@ -19,6 +19,9 @@ export class SubagentSessionCapability {
         this.ownerAliveOverride = options.ownerAlive;
     }
     async run(input, context, options) {
+        if (!context.workspaceRoot) {
+            throw new CapabilityError("capability_unavailable", "subagent.session requires a filesystem-backed Workspace.");
+        }
         const manager = new SubagentSessionManager(this.config, {
             launch: (request) => this.launch(request),
         });