@akira-tl/forgerelay 0.8.2 → 0.8.3

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.8.3] - 2026-08-31
+
+### Added
+
+- Added `workspace.tasks` with private file-backed Task Lists per persistent Workspace, preserving Task state across restart, close/reopen, managed-worktree backing replacement, and Composite close while keeping Task data out of project Git contents.
+
 ## [0.8.2] - 2026-08-31
 
 ### Changed

package/capabilities/workspace-tasks/GUIDE.md

@@ -0,0 +1,29 @@
+# Workspace Tasks
+
+`workspace.tasks` 维护当前 Workspace 自己的持久 Task Lists。它是轻量工作续接状态，不是执行队列、Subagent Session、Activity 或依赖图。
+
+## 使用边界
+
+- 只操作当前调用上下文中的 Workspace；参数中没有目标 `workspaceId`。
+- Task state 由 ForgeRelay 保存在私有 state directory，不写入 checkout 或 managed worktree。
+- 一个 Workspace 可以有多个 Task List；List 可为 `active` 或 `archived`。
+- Task 状态只有 `pending`、`in_progress`、`completed`。`content` 保存继续工作真正需要的要求、阻塞点、结论或下一步，而不是日志或对话转录。
+- Task/List ID 创建后保持稳定。完成 Task 不会删除它；删除必须显式执行。
+
+## 操作
+
+先用 `operation="get"` 读取当前 Task state。
+
+List 操作：
+
+- `list.create`：创建具名 List，可指定 `position`。
+- `list.update`：修改 `name`、`state` 或 `position`；`state="archived"` 用于归档，改回 `active` 即重新激活。
+- `list.delete`：显式删除 List 及其 Tasks。
+
+Task 操作：
+
+- `task.create`：在一个 List 中创建 Task；需要 `subject`，可提供 `content`、`status`、`position`。
+- `task.update`：修改 `subject`、`content`、`status` 或 `position`；至少提供一个变更字段。
+- `task.delete`：显式删除 Task。
+
+Task 修改使用独立的 revision/fingerprint 域；它不改变 Workspace bootstrap `contextFingerprint`。

package/dist/capabilities.js

@@ -39,6 +39,11 @@ const CAPABILITY_GUIDE_DEFINITIONS = [
         description: "Read-only semantic code navigation backed by external Language servers.",
         whenToRead: "Read before using code.intelligence or configuring Language servers.",
     },
+    {
+        name: "workspace-tasks",
+        description: "Persistent Task Lists owned by the current Workspace.",
+        whenToRead: "Read before creating or maintaining Workspace Tasks.",
+    },
     {
         name: "batch-execution",
         description: "One-call execution of multiple independent ForgeRelay core operations.",
@@ -87,6 +92,7 @@ export function buildCapabilityFingerprint(config, version, context = {}) {
         "hooks.lifecycle",
         "capability-guides.read",
         "code.intelligence",
+        "workspace.tasks",
     ];
     if (config.toolMode !== "codex") {
         capabilities.push("batch.execute");

package/dist/capability-registry.js

@@ -130,6 +130,52 @@ export function createCapabilityRegistry(dependencies) {
         line: z.number().int(),
         column: z.number().int(),
     };
+    const workspaceTaskStatus = z.enum(["pending", "in_progress", "completed"]);
+    const workspaceTaskListState = z.enum(["active", "archived"]);
+    const workspaceTasksInput = z.union([
+        z.object({ operation: z.literal("get") }).strict(),
+        z.object({
+            operation: z.literal("list.create"),
+            name: z.string().trim().min(1),
+            position: z.number().int().min(0).optional(),
+        }).strict(),
+        z.object({
+            operation: z.literal("list.update"),
+            listId: z.string().min(1),
+            name: z.string().trim().min(1).optional(),
+            state: workspaceTaskListState.optional(),
+            position: z.number().int().min(0).optional(),
+        }).strict().refine((input) => input.name !== undefined || input.state !== undefined || input.position !== undefined, { message: "list.update requires at least one field to change" }),
+        z.object({
+            operation: z.literal("list.delete"),
+            listId: z.string().min(1),
+        }).strict(),
+        z.object({
+            operation: z.literal("task.create"),
+            listId: z.string().min(1),
+            subject: z.string().trim().min(1),
+            content: z.string().optional(),
+            status: workspaceTaskStatus.optional(),
+            position: z.number().int().min(0).optional(),
+        }).strict(),
+        z.object({
+            operation: z.literal("task.update"),
+            listId: z.string().min(1),
+            taskId: z.string().min(1),
+            subject: z.string().trim().min(1).optional(),
+            content: z.string().optional(),
+            status: workspaceTaskStatus.optional(),
+            position: z.number().int().min(0).optional(),
+        }).strict().refine((input) => input.subject !== undefined
+            || input.content !== undefined
+            || input.status !== undefined
+            || input.position !== undefined, { message: "task.update requires at least one field to change" }),
+        z.object({
+            operation: z.literal("task.delete"),
+            listId: z.string().min(1),
+            taskId: z.string().min(1),
+        }).strict(),
+    ]);
     const subagentSessionInput = z.discriminatedUnion("operation", [
         z.object({
             operation: z.literal("start"),
@@ -190,11 +236,11 @@ export function createCapabilityRegistry(dependencies) {
             readGuideBeforeFirstUse: true,
             batchPolicy: "parallel",
             inputSchema: hooksCheckInput,
-            availability: () => ({ available: true }),
+            availability: (context) => filesystemWorkspaceAvailability(context),
             run: async (_input, context) => ({
                 value: {
                     ok: true,
-                    ...await dependencies.inspectHooks(context.workspaceRoot),
+                    ...await dependencies.inspectHooks(requireWorkspaceRoot(context)),
                 },
             }),
         },
@@ -206,10 +252,7 @@ export function createCapabilityRegistry(dependencies) {
                     readGuideBeforeFirstUse: true,
                     batchPolicy: "serial",
                     inputSchema: z.object({}).strict(),
-                    availability: () => ({
-                        available: dependencies.reviewChanges?.available ?? false,
-                        reason: dependencies.reviewChanges?.unavailableReason,
-                    }),
+                    availability: (context) => filesystemWorkspaceAvailability(context, dependencies.reviewChanges?.available ?? false, dependencies.reviewChanges?.unavailableReason),
                     run: async (_input, context) => dependencies.reviewChanges.run(context),
                 }]
             : []),
@@ -221,11 +264,23 @@ export function createCapabilityRegistry(dependencies) {
                     readGuideBeforeFirstUse: true,
                     batchPolicy: "parallel",
                     inputSchema: codeIntelligenceInput,
+                    availability: (context) => filesystemWorkspaceAvailability(context, dependencies.codeIntelligence?.available ?? false, dependencies.codeIntelligence?.unavailableReason),
+                    run: async (input, context, options) => dependencies.codeIntelligence.run(input, context, options),
+                }]
+            : []),
+        ...(dependencies.workspaceTasks
+            ? [{
+                    name: "workspace.tasks",
+                    description: "Maintain persistent Task Lists owned by the current Workspace.",
+                    guideName: "workspace-tasks",
+                    readGuideBeforeFirstUse: true,
+                    batchPolicy: "serial",
+                    inputSchema: workspaceTasksInput,
                     availability: () => ({
-                        available: dependencies.codeIntelligence?.available ?? false,
-                        reason: dependencies.codeIntelligence?.unavailableReason,
+                        available: dependencies.workspaceTasks?.available ?? false,
+                        reason: dependencies.workspaceTasks?.unavailableReason,
                     }),
-                    run: async (input, context, options) => dependencies.codeIntelligence.run(input, context, options),
+                    run: async (input, context, options) => dependencies.workspaceTasks.run(input, context, options),
                 }]
             : []),
         ...(dependencies.subagentSession
@@ -236,10 +291,7 @@ export function createCapabilityRegistry(dependencies) {
                     readGuideBeforeFirstUse: true,
                     batchPolicy: "unsupported",
                     inputSchema: subagentSessionInput,
-                    availability: () => ({
-                        available: dependencies.subagentSession?.available ?? false,
-                        reason: dependencies.subagentSession?.unavailableReason,
-                    }),
+                    availability: (context) => filesystemWorkspaceAvailability(context, dependencies.subagentSession?.available ?? false, dependencies.subagentSession?.unavailableReason),
                     run: async (input, context, options) => dependencies.subagentSession.run(input, context, options),
                 }]
             : []),
@@ -251,10 +303,7 @@ export function createCapabilityRegistry(dependencies) {
                     readGuideBeforeFirstUse: true,
                     batchPolicy: "unsupported",
                     inputSchema: batchExecuteInputSchema,
-                    availability: () => ({
-                        available: dependencies.batchExecute?.available ?? false,
-                        reason: dependencies.batchExecute?.unavailableReason,
-                    }),
+                    availability: (context) => filesystemWorkspaceAvailability(context, dependencies.batchExecute?.available ?? false, dependencies.batchExecute?.unavailableReason),
                     run: async (input, context, options) => dependencies.batchExecute.run(input, context, options),
                 }]
             : []),
@@ -277,15 +326,27 @@ export function createCapabilityRegistry(dependencies) {
                         path: z.string().min(1),
                     }).strict(),
                     nativeFileArgument: "file",
-                    availability: () => ({
-                        available: dependencies.downloadArtifact?.available ?? false,
-                        reason: dependencies.downloadArtifact?.unavailableReason,
-                    }),
+                    availability: (context) => filesystemWorkspaceAvailability(context, dependencies.downloadArtifact?.available ?? false, dependencies.downloadArtifact?.unavailableReason),
                     run: async (input, context) => dependencies.downloadArtifact.run(input, context),
                 }]
             : []),
     ]);
 }
+function filesystemWorkspaceAvailability(context, available = true, reason) {
+    if (context.workspaceKind !== "workspace" || !context.workspaceRoot) {
+        return {
+            available: false,
+            reason: "This capability requires a filesystem-backed Workspace.",
+        };
+    }
+    return { available, ...(reason ? { reason } : {}) };
+}
+function requireWorkspaceRoot(context) {
+    if (context.workspaceKind !== "workspace" || !context.workspaceRoot) {
+        throw new CapabilityError("capability_unavailable", "This capability requires a filesystem-backed Workspace.");
+    }
+    return context.workspaceRoot;
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }

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,
@@ -2398,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;
@@ -2408,6 +2477,9 @@ 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,
@@ -2435,6 +2507,8 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     status: composite.status,
                     state: composite.status,
                     members: composite.members,
+                    capabilityCatalog: compositeCapabilityCatalog,
+                    capabilityGuides: compositeCapabilityGuides,
                     ...(memberContext ? { memberContext } : {}),
                     instruction,
                 },
@@ -2547,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, {
@@ -2808,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);
@@ -2972,6 +3115,8 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             const composite = action === "delete"
                 ? compositeWorkspaces.dissolve(workspaceId)
                 : compositeWorkspaces.close(workspaceId);
+            if (action === "delete")
+                workspaceTasks.deleteWorkspace(workspaceId);
             compositeActivity.forgetComposite(workspaceId);
             workspacePanelStates.delete(workspaceId);
             const result = [
@@ -3038,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 {
@@ -3080,6 +3226,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 closed managed-worktree Workspace ${session.id}. Its already-removed worktree backing was not recreated.`;
                     return {
@@ -3142,6 +3289,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     await Promise.all(physicalWorkspaceIds.map((id) => reviewCheckpoints.releaseWorkspace(id)));
                     if (action === "delete") {
                         workspaces.deleteWorkspace(workspace.id);
+                        workspaceTasks.deleteWorkspace(workspace.id);
                     }
                     const result = [
                         action === "delete"
@@ -3237,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()
@@ -3279,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),
         });

package/dist/workspace-tasks.js

@@ -0,0 +1,351 @@
+import { createHash, randomBytes } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, rmSync, rmdirSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import * as z from "zod/v4";
+const TASK_STATE_VERSION = 1;
+const MAX_TASK_STATE_BYTES = 2 * 1024 * 1024;
+const MAX_TASK_LISTS = 100;
+const MAX_TASKS_PER_LIST = 500;
+const MAX_LIST_NAME_LENGTH = 120;
+const MAX_TASK_SUBJECT_LENGTH = 240;
+const MAX_TASK_CONTENT_LENGTH = 64 * 1024;
+const workspaceTaskSchema = z.object({
+    id: z.string().regex(/^tsk_[a-f0-9]{10}$/),
+    status: z.enum(["pending", "in_progress", "completed"]),
+    subject: z.string().min(1).max(MAX_TASK_SUBJECT_LENGTH),
+    content: z.string().max(MAX_TASK_CONTENT_LENGTH),
+}).strict();
+const workspaceTaskListSchema = z.object({
+    id: z.string().regex(/^tl_[a-f0-9]{10}$/),
+    name: z.string().min(1).max(MAX_LIST_NAME_LENGTH),
+    state: z.enum(["active", "archived"]),
+    revision: z.number().int().positive(),
+    tasks: z.array(workspaceTaskSchema).max(MAX_TASKS_PER_LIST),
+}).strict();
+const workspaceTaskStateSchema = z.object({
+    version: z.literal(TASK_STATE_VERSION),
+    revision: z.number().int().nonnegative(),
+    lists: z.array(workspaceTaskListSchema).max(MAX_TASK_LISTS),
+}).strict().superRefine((state, context) => {
+    const listIds = new Set();
+    const taskIds = new Set();
+    state.lists.forEach((list, listIndex) => {
+        if (listIds.has(list.id)) {
+            context.addIssue({
+                code: "custom",
+                path: ["lists", listIndex, "id"],
+                message: `Duplicate Task List id ${list.id}.`,
+            });
+        }
+        listIds.add(list.id);
+        list.tasks.forEach((task, taskIndex) => {
+            if (taskIds.has(task.id)) {
+                context.addIssue({
+                    code: "custom",
+                    path: ["lists", listIndex, "tasks", taskIndex, "id"],
+                    message: `Duplicate Task id ${task.id}.`,
+                });
+            }
+            taskIds.add(task.id);
+        });
+    });
+});
+export class WorkspaceTaskStore {
+    stateDir;
+    constructor(stateDir) {
+        this.stateDir = stateDir;
+    }
+    ensureWorkspace(workspaceId) {
+        const id = normalizeWorkspaceId(workspaceId);
+        const loaded = this.tryReadState(id);
+        if (loaded)
+            return snapshot(loaded.state, loaded.fingerprint);
+        return this.writeState(id, emptyState());
+    }
+    initializeWorkspace(workspaceId) {
+        const id = normalizeWorkspaceId(workspaceId);
+        const directory = this.workspaceStateDir(id);
+        mkdirSync(directory, { recursive: true, mode: 0o700 });
+        try {
+            writeFileSync(this.statePath(id), `${JSON.stringify(emptyState(), null, 2)}\n`, {
+                mode: 0o600,
+                flag: "wx",
+            });
+        }
+        catch (error) {
+            if (!isErrno(error, "EEXIST"))
+                throw error;
+        }
+    }
+    read(workspaceId) {
+        return this.ensureWorkspace(workspaceId);
+    }
+    createList(workspaceId, input) {
+        return this.mutate(workspaceId, (state) => {
+            if (state.lists.length >= MAX_TASK_LISTS) {
+                throw new Error(`Workspace Task List limit is ${MAX_TASK_LISTS}.`);
+            }
+            const list = {
+                id: `tl_${randomBytes(5).toString("hex")}`,
+                name: normalizeListName(input.name),
+                state: "active",
+                revision: 1,
+                tasks: [],
+            };
+            const position = normalizeInsertPosition(input.position, state.lists.length, "Task List");
+            state.lists.splice(position, 0, list);
+            return true;
+        });
+    }
+    updateList(workspaceId, listId, input) {
+        return this.mutate(workspaceId, (state) => {
+            const index = requireListIndex(state, listId);
+            const list = state.lists[index];
+            const nextName = input.name === undefined ? list.name : normalizeListName(input.name);
+            const nextState = input.state ?? list.state;
+            const nextPosition = input.position === undefined
+                ? index
+                : normalizeMovePosition(input.position, state.lists.length, "Task List");
+            const metadataChanged = nextName !== list.name || nextState !== list.state;
+            const positionChanged = nextPosition !== index;
+            if (!metadataChanged && !positionChanged)
+                return false;
+            list.name = nextName;
+            list.state = nextState;
+            list.revision += 1;
+            if (positionChanged)
+                moveArrayEntry(state.lists, index, nextPosition);
+            return true;
+        });
+    }
+    deleteList(workspaceId, listId) {
+        return this.mutate(workspaceId, (state) => {
+            state.lists.splice(requireListIndex(state, listId), 1);
+            return true;
+        });
+    }
+    createTask(workspaceId, listId, input) {
+        return this.mutate(workspaceId, (state) => {
+            const list = requireList(state, listId);
+            if (list.tasks.length >= MAX_TASKS_PER_LIST) {
+                throw new Error(`Task limit per Task List is ${MAX_TASKS_PER_LIST}.`);
+            }
+            const task = {
+                id: `tsk_${randomBytes(5).toString("hex")}`,
+                status: input.status ?? "pending",
+                subject: normalizeTaskSubject(input.subject),
+                content: normalizeTaskContent(input.content ?? ""),
+            };
+            const position = normalizeInsertPosition(input.position, list.tasks.length, "Task");
+            list.tasks.splice(position, 0, task);
+            list.revision += 1;
+            return true;
+        });
+    }
+    updateTask(workspaceId, listId, taskId, input) {
+        return this.mutate(workspaceId, (state) => {
+            const list = requireList(state, listId);
+            const index = requireTaskIndex(list, taskId);
+            const task = list.tasks[index];
+            const nextStatus = input.status ?? task.status;
+            const nextSubject = input.subject === undefined ? task.subject : normalizeTaskSubject(input.subject);
+            const nextContent = input.content === undefined ? task.content : normalizeTaskContent(input.content);
+            const nextPosition = input.position === undefined
+                ? index
+                : normalizeMovePosition(input.position, list.tasks.length, "Task");
+            const fieldsChanged = nextStatus !== task.status || nextSubject !== task.subject || nextContent !== task.content;
+            const positionChanged = nextPosition !== index;
+            if (!fieldsChanged && !positionChanged)
+                return false;
+            task.status = nextStatus;
+            task.subject = nextSubject;
+            task.content = nextContent;
+            if (positionChanged)
+                moveArrayEntry(list.tasks, index, nextPosition);
+            list.revision += 1;
+            return true;
+        });
+    }
+    deleteTask(workspaceId, listId, taskId) {
+        return this.mutate(workspaceId, (state) => {
+            const list = requireList(state, listId);
+            list.tasks.splice(requireTaskIndex(list, taskId), 1);
+            list.revision += 1;
+            return true;
+        });
+    }
+    deleteWorkspace(workspaceId) {
+        const id = normalizeWorkspaceId(workspaceId);
+        rmSync(this.statePath(id), { force: true });
+        try {
+            rmdirSync(this.workspaceStateDir(id));
+        }
+        catch (error) {
+            if (!isErrno(error, "ENOENT") && !isErrno(error, "ENOTEMPTY") && !isErrno(error, "EEXIST")) {
+                throw error;
+            }
+        }
+    }
+    mutate(workspaceId, mutateState) {
+        const id = normalizeWorkspaceId(workspaceId);
+        const loaded = this.tryReadState(id);
+        const state = loaded ? cloneState(loaded.state) : emptyState();
+        if (!mutateState(state)) {
+            return loaded
+                ? snapshot(loaded.state, loaded.fingerprint)
+                : this.writeState(id, state);
+        }
+        state.revision += 1;
+        return this.writeState(id, state);
+    }
+    tryReadState(workspaceId) {
+        const path = this.statePath(workspaceId);
+        let raw;
+        try {
+            raw = readFileSync(path);
+        }
+        catch (error) {
+            if (isErrno(error, "ENOENT"))
+                return undefined;
+            throw error;
+        }
+        if (raw.byteLength > MAX_TASK_STATE_BYTES) {
+            throw new Error(`Workspace Task state exceeds ${MAX_TASK_STATE_BYTES} bytes.`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw.toString("utf8"));
+        }
+        catch (error) {
+            throw new Error(`Workspace Task state is not valid JSON: ${errorMessage(error)}`);
+        }
+        const validated = workspaceTaskStateSchema.safeParse(parsed);
+        if (!validated.success) {
+            const details = validated.error.issues
+                .map((issue) => `${issue.path.length > 0 ? issue.path.join(".") : "state"}: ${issue.message}`)
+                .join("; ");
+            throw new Error(`Workspace Task state has an unsupported or invalid format: ${details}`);
+        }
+        return {
+            state: cloneState(validated.data),
+            fingerprint: fingerprint(raw),
+        };
+    }
+    writeState(workspaceId, state) {
+        const workspaceDir = this.workspaceStateDir(workspaceId);
+        mkdirSync(workspaceDir, { recursive: true, mode: 0o700 });
+        const validated = workspaceTaskStateSchema.parse(state);
+        const serialized = `${JSON.stringify(validated, null, 2)}\n`;
+        if (Buffer.byteLength(serialized, "utf8") > MAX_TASK_STATE_BYTES) {
+            throw new Error(`Workspace Task state exceeds ${MAX_TASK_STATE_BYTES} bytes.`);
+        }
+        const statePath = this.statePath(workspaceId);
+        const tempPath = `${statePath}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+        try {
+            writeFileSync(tempPath, serialized, { mode: 0o600 });
+            renameSync(tempPath, statePath);
+        }
+        finally {
+            rmSync(tempPath, { force: true });
+        }
+        return snapshot(validated, fingerprint(Buffer.from(serialized, "utf8")));
+    }
+    workspaceStateDir(workspaceId) {
+        return join(this.stateDir, "workspaces", workspaceId);
+    }
+    statePath(workspaceId) {
+        return join(this.workspaceStateDir(workspaceId), "tasks.json");
+    }
+}
+function emptyState() {
+    return { version: TASK_STATE_VERSION, revision: 0, lists: [] };
+}
+function snapshot(state, stateFingerprint) {
+    return {
+        ...cloneState(state),
+        fingerprint: stateFingerprint,
+    };
+}
+function cloneState(state) {
+    return {
+        version: state.version,
+        revision: state.revision,
+        lists: state.lists.map((list) => ({
+            ...list,
+            tasks: list.tasks.map((task) => ({ ...task })),
+        })),
+    };
+}
+function requireList(state, listId) {
+    return state.lists[requireListIndex(state, listId)];
+}
+function requireListIndex(state, listId) {
+    const index = state.lists.findIndex((list) => list.id === listId);
+    if (index < 0)
+        throw new Error(`Unknown Task List ${listId}.`);
+    return index;
+}
+function requireTaskIndex(list, taskId) {
+    const index = list.tasks.findIndex((task) => task.id === taskId);
+    if (index < 0)
+        throw new Error(`Task List ${list.id} has no Task ${taskId}.`);
+    return index;
+}
+function normalizeWorkspaceId(workspaceId) {
+    const value = workspaceId.trim();
+    if (!/^[a-z][a-z0-9_-]{1,127}$/.test(value)) {
+        throw new Error("Workspace ID is not valid for Workspace Task state.");
+    }
+    return value;
+}
+function normalizeListName(name) {
+    const value = name.trim();
+    if (!value)
+        throw new Error("Task List name must not be empty.");
+    if (value.length > MAX_LIST_NAME_LENGTH) {
+        throw new Error(`Task List name must be at most ${MAX_LIST_NAME_LENGTH} characters.`);
+    }
+    return value;
+}
+function normalizeTaskSubject(subject) {
+    const value = subject.trim();
+    if (!value)
+        throw new Error("Task subject must not be empty.");
+    if (value.length > MAX_TASK_SUBJECT_LENGTH) {
+        throw new Error(`Task subject must be at most ${MAX_TASK_SUBJECT_LENGTH} characters.`);
+    }
+    return value;
+}
+function normalizeTaskContent(content) {
+    if (content.length > MAX_TASK_CONTENT_LENGTH) {
+        throw new Error(`Task content must be at most ${MAX_TASK_CONTENT_LENGTH} characters.`);
+    }
+    return content;
+}
+function normalizeInsertPosition(position, length, label) {
+    if (position === undefined)
+        return length;
+    if (!Number.isInteger(position) || position < 0 || position > length) {
+        throw new Error(`${label} position must be an integer between 0 and ${length}.`);
+    }
+    return position;
+}
+function normalizeMovePosition(position, length, label) {
+    if (!Number.isInteger(position) || position < 0 || position >= length) {
+        throw new Error(`${label} position must be an integer between 0 and ${Math.max(0, length - 1)}.`);
+    }
+    return position;
+}
+function moveArrayEntry(values, from, to) {
+    const [value] = values.splice(from, 1);
+    values.splice(to, 0, value);
+}
+function fingerprint(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+function isErrno(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",
@@ -47,7 +47,7 @@
     "release:publish": "node scripts/release/publish.mjs",
     "postinstall": "node scripts/fix-node-pty-permissions.mjs",
     "start": "node dist/cli.js serve",
-    "test": "node --test scripts/debug/runtime.test.mjs scripts/release-proof.test.mjs scripts/release/release-gate.test.mjs scripts/release/release-version.test.mjs && tsx src/oauth/router.test.ts && tsx src/remote-auth-cli.test.ts && tsx src/remote-ssh-auth-cli.test.ts && tsx src/remote-workspace-relay.test.ts && tsx src/remote-workspace-relay-process.test.ts && tsx src/config.test.ts && tsx src/lsp/language-server-config.test.ts && tsx src/lsp/normalization/hover.test.ts && tsx src/lsp/references.server.test.ts && tsx src/lsp/operations/document-symbols.server.test.ts && tsx src/lsp/operations/workspace-symbols.server.test.ts && tsx src/lsp/operations/diagnostics-push.server.test.ts && tsx src/lsp/operations/diagnostics-pull.server.test.ts && tsx src/lsp/operations/request-hardening.server.test.ts && tsx src/lsp/operations/recovery.server.test.ts && tsx src/lsp/operations/lifecycle.server.test.ts && tsx src/lsp/runtime/semantic-requests.test.ts && tsx src/logger.test.ts && tsx src/proxy-trust.test.ts && tsx src/mcp-app-template.test.ts && tsx src/hooks.test.ts && tsx src/capability-registry.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/request-meta.test.ts && tsx src/incoming-artifacts.test.ts && tsx src/artifact-download.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/workspace-lifecycle-app.test.ts && tsx src/ui/activity/model.test.ts && tsx src/ui/patch-display.test.ts && tsx src/ui/tool-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/mcp-sessions.test.ts && tsx src/server-shutdown.test.ts && tsx src/subagents/providers/adapters/codex.test.ts && tsx src/subagents/providers/registry.test.ts && tsx src/subagents/providers/availability.test.ts && tsx src/subagents/profiles.test.ts && tsx src/subagents/cli-target.test.ts && tsx src/subagents/sessions/store.test.ts && tsx src/subagents/sessions/manager.test.ts && tsx src/subagents/sessions/mcp/capability.server.test.ts && tsx src/subagents/sessions/mcp/continuation.server.test.ts && tsx src/subagents/sessions/mcp/lifecycle.server.test.ts && tsx src/subagents/sessions/mcp/reconciliation.server.test.ts && tsx src/subagents/sessions/mcp/routing.server.test.ts && tsx src/roots.test.ts && tsx src/file-mutations.test.ts && tsx src/operations/edit-preflight.test.ts && tsx src/skills.test.ts && tsx src/db/migrations.test.ts && tsx src/workspace-store.test.ts && tsx src/activity/audit-store.test.ts && tsx src/activity/bash-output-store.test.ts && tsx src/activity/lifecycle.test.ts && tsx src/activity/query-service.test.ts && tsx src/operations/core-operation-executor.test.ts && tsx src/operations/bulk-mutation.test.ts && tsx src/operations/batch/scheduler.test.ts && tsx src/operations/batch/executor-policy.test.ts && tsx src/workspaces.test.ts && tsx src/workspace-conversation.test.ts && tsx src/review-checkpoints.test.ts && tsx src/lsp/code-intelligence.server.test.ts && npm run build:app && tsx src/server.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
+    "test": "node --test scripts/debug/runtime.test.mjs scripts/release-proof.test.mjs scripts/release/release-gate.test.mjs scripts/release/release-version.test.mjs && tsx src/oauth/router.test.ts && tsx src/remote-auth-cli.test.ts && tsx src/remote-ssh-auth-cli.test.ts && tsx src/remote-workspace-relay.test.ts && tsx src/remote-workspace-relay-process.test.ts && tsx src/config.test.ts && tsx src/lsp/language-server-config.test.ts && tsx src/lsp/normalization/hover.test.ts && tsx src/lsp/references.server.test.ts && tsx src/lsp/operations/document-symbols.server.test.ts && tsx src/lsp/operations/workspace-symbols.server.test.ts && tsx src/lsp/operations/diagnostics-push.server.test.ts && tsx src/lsp/operations/diagnostics-pull.server.test.ts && tsx src/lsp/operations/request-hardening.server.test.ts && tsx src/lsp/operations/recovery.server.test.ts && tsx src/lsp/operations/lifecycle.server.test.ts && tsx src/lsp/runtime/semantic-requests.test.ts && tsx src/logger.test.ts && tsx src/proxy-trust.test.ts && tsx src/mcp-app-template.test.ts && tsx src/hooks.test.ts && tsx src/capability-registry.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/request-meta.test.ts && tsx src/incoming-artifacts.test.ts && tsx src/artifact-download.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/workspace-lifecycle-app.test.ts && tsx src/ui/activity/model.test.ts && tsx src/ui/patch-display.test.ts && tsx src/ui/tool-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/mcp-sessions.test.ts && tsx src/server-shutdown.test.ts && tsx src/subagents/providers/adapters/codex.test.ts && tsx src/subagents/providers/registry.test.ts && tsx src/subagents/providers/availability.test.ts && tsx src/subagents/profiles.test.ts && tsx src/subagents/cli-target.test.ts && tsx src/subagents/sessions/store.test.ts && tsx src/subagents/sessions/manager.test.ts && tsx src/subagents/sessions/mcp/capability.server.test.ts && tsx src/subagents/sessions/mcp/continuation.server.test.ts && tsx src/subagents/sessions/mcp/lifecycle.server.test.ts && tsx src/subagents/sessions/mcp/reconciliation.server.test.ts && tsx src/subagents/sessions/mcp/routing.server.test.ts && tsx src/roots.test.ts && tsx src/file-mutations.test.ts && tsx src/operations/edit-preflight.test.ts && tsx src/skills.test.ts && tsx src/db/migrations.test.ts && tsx src/workspace-store.test.ts && tsx src/workspace-tasks.test.ts && tsx src/activity/audit-store.test.ts && tsx src/activity/bash-output-store.test.ts && tsx src/activity/lifecycle.test.ts && tsx src/activity/query-service.test.ts && tsx src/operations/core-operation-executor.test.ts && tsx src/operations/bulk-mutation.test.ts && tsx src/operations/batch/scheduler.test.ts && tsx src/operations/batch/executor-policy.test.ts && tsx src/workspaces.test.ts && tsx src/workspace-conversation.test.ts && tsx src/review-checkpoints.test.ts && tsx src/lsp/code-intelligence.server.test.ts && npm run build:app && tsx src/server.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "release:check": "node scripts/release-version.mjs check",
     "release:tag-check": "node scripts/release-version.mjs tag",

package/scripts/debug/accept.mjs

@@ -265,6 +265,7 @@ try {
       "hooks.lifecycle",
       "capability-guides.read",
       "code.intelligence",
+      "workspace.tasks",
       "batch.execute",
       ...(process.platform === "linux" ? ["artifact.native-download"] : []),
       "ui.mcp-app",
@@ -276,12 +277,55 @@ try {
     "hooks.check",
     "review.changes",
     "code.intelligence",
+    "workspace.tasks",
     "batch.execute",
     ...(process.platform === "linux" ? ["artifact.download"] : []),
   ]);
   assert.equal(capabilityCatalog[0].available, true);
   assert.equal(capabilityCatalog[0].guide.name, "lifecycle-hooks");
 
+  const checkoutTaskStatePath = join(stateDir, "workspaces", workspaceId, "tasks.json");
+  assert.ok(existsSync(checkoutTaskStatePath));
+  const checkoutTaskList = callTool(oauth.accessToken, sessionId, 130, "capability", {
+    workspaceId,
+    name: "workspace.tasks",
+    action: "run",
+    arguments: { operation: "list.create", name: "7677 release tasks" },
+  });
+  assert.equal(checkoutTaskList.isError, undefined);
+  const checkoutListId = checkoutTaskList.structuredContent.result.lists[0].id;
+  const checkoutTask = callTool(oauth.accessToken, sessionId, 131, "capability", {
+    workspaceId,
+    name: "workspace.tasks",
+    action: "run",
+    arguments: {
+      operation: "task.create",
+      listId: checkoutListId,
+      subject: "Verify v0.8.3 Task persistence",
+      content: "created through real MCP",
+      status: "in_progress",
+    },
+  });
+  assert.equal(checkoutTask.isError, undefined);
+  const checkoutTaskId = checkoutTask.structuredContent.result.lists[0].tasks[0].id;
+  const taskFingerprintBeforeExternal = checkoutTask.structuredContent.result.fingerprint;
+  const externalTaskState = JSON.parse(readFileSync(checkoutTaskStatePath, "utf8"));
+  externalTaskState.lists[0].tasks[0].content = "reloaded external task edit";
+  writeFileSync(checkoutTaskStatePath, `${JSON.stringify(externalTaskState, null, 2)}\n`);
+  const reloadedCheckoutTasks = callTool(oauth.accessToken, sessionId, 132, "capability", {
+    workspaceId,
+    name: "workspace.tasks",
+    action: "run",
+    arguments: { operation: "get" },
+  });
+  assert.equal(reloadedCheckoutTasks.isError, undefined);
+  assert.equal(reloadedCheckoutTasks.structuredContent.result.lists[0].tasks[0].id, checkoutTaskId);
+  assert.equal(
+    reloadedCheckoutTasks.structuredContent.result.lists[0].tasks[0].content,
+    "reloaded external task edit",
+  );
+  assert.notEqual(reloadedCheckoutTasks.structuredContent.result.fingerprint, taskFingerprintBeforeExternal);
+
   const repeatedOpen = callTool(oauth.accessToken, sessionId, 84, "open_workspace", {
     path: checkoutWorkspace,
     newWorkspace: true,
@@ -312,6 +356,13 @@ try {
   assert.equal(closedWorkspace.isError, undefined);
   assert.equal(closedWorkspace.structuredContent.workspaceId, workspaceId);
   assert.equal(closedWorkspace.structuredContent.action, "close");
+  const closedCheckoutTasks = callTool(oauth.accessToken, sessionId, 133, "capability", {
+    workspaceId,
+    name: "workspace.tasks",
+    action: "run",
+    arguments: { operation: "get" },
+  });
+  assert.equal(closedCheckoutTasks.isError, true);
 
   const closedInventory = callTool(oauth.accessToken, sessionId, 87, "open_workspace", {
     action: "list",
@@ -336,12 +387,34 @@ try {
     resumedOriginal.structuredContent.contextFingerprint,
     opened.structuredContent.contextFingerprint,
   );
+  const resumedCheckoutTasks = callTool(oauth.accessToken, sessionId, 134, "capability", {
+    workspaceId,
+    name: "workspace.tasks",
+    action: "run",
+    arguments: { operation: "get" },
+  });
+  assert.equal(resumedCheckoutTasks.isError, undefined);
+  assert.equal(resumedCheckoutTasks.structuredContent.result.lists[0].tasks[0].id, checkoutTaskId);
+  assert.equal(
+    resumedCheckoutTasks.structuredContent.result.lists[0].tasks[0].content,
+    "reloaded external task edit",
+  );
+  assert.equal(resumedOriginal.structuredContent.contextFingerprint, opened.structuredContent.contextFingerprint);
 
   const deleteOpened = callTool(oauth.accessToken, sessionId, 91, "open_workspace", {
     path: lifecycleDeleteWorkspace,
     context: "none",
   }, { "openai/session": "acceptance-workspace-delete" });
   const deleteWorkspaceId = deleteOpened.structuredContent.workspaceId;
+  const deleteTaskStatePath = join(stateDir, "workspaces", deleteWorkspaceId, "tasks.json");
+  const deleteTaskList = callTool(oauth.accessToken, sessionId, 135, "capability", {
+    workspaceId: deleteWorkspaceId,
+    name: "workspace.tasks",
+    action: "run",
+    arguments: { operation: "list.create", name: "delete with workspace" },
+  });
+  assert.equal(deleteTaskList.isError, undefined);
+  assert.ok(existsSync(deleteTaskStatePath));
   const deleteClosed = callTool(oauth.accessToken, sessionId, 92, "close_workspace", {
     workspaceId: deleteWorkspaceId,
   });
@@ -353,12 +426,17 @@ try {
   assert.equal(deletedWorkspace.isError, undefined);
   assert.equal(deletedWorkspace.structuredContent.workspaceId, deleteWorkspaceId);
   assert.equal(deletedWorkspace.structuredContent.action, "delete");
+  assert.equal(existsSync(deleteTaskStatePath), false);
   assert.equal(readFileSync(join(lifecycleDeleteWorkspace, "keep.txt"), "utf8"), "keep checkout files\n");
   const deletedInventory = callTool(oauth.accessToken, sessionId, 94, "open_workspace", {
     action: "list",
     workspaceId: deleteWorkspaceId,
   });
   assert.equal(deletedInventory.structuredContent.workspaces.length, 0);
+  pass(
+    "workspace tasks",
+    `${workspaceId} create -> external reload -> close/reopen; explicit delete removed ${deleteWorkspaceId} Task state`,
+  );
 
   pass(
     "workspace lifecycle + inventory",
@@ -440,6 +518,7 @@ try {
     "host-integration",
     "shell-processes",
     "code-intelligence",
+    "workspace-tasks",
     "batch-execution",
   ]);
   const hooksGuide = callTool(oauth.accessToken, sessionId, 78, "read", {
@@ -697,6 +776,33 @@ try {
     context: "none",
   });
   const compositeWorkspaceId = compositeOpened.structuredContent.workspaceId;
+  assert.deepEqual(
+    compositeOpened.structuredContent.capabilityCatalog.map((entry) => entry.name),
+    ["workspace.tasks"],
+  );
+  const compositeTaskStatePath = join(stateDir, "workspaces", compositeWorkspaceId, "tasks.json");
+  assert.ok(existsSync(compositeTaskStatePath));
+  const compositeTaskList = callTool(oauth.accessToken, sessionId, 136, "capability", {
+    workspaceId: compositeWorkspaceId,
+    name: "workspace.tasks",
+    action: "run",
+    arguments: { operation: "list.create", name: "Composite release tasks" },
+  });
+  assert.equal(compositeTaskList.isError, undefined);
+  const compositeTaskListId = compositeTaskList.structuredContent.result.lists[0].id;
+  const compositeTask = callTool(oauth.accessToken, sessionId, 137, "capability", {
+    workspaceId: compositeWorkspaceId,
+    name: "workspace.tasks",
+    action: "run",
+    arguments: {
+      operation: "task.create",
+      listId: compositeTaskListId,
+      subject: "Preserve Composite Task state",
+      content: "Composite-owned state",
+    },
+  });
+  assert.equal(compositeTask.isError, undefined);
+  const compositeTaskId = compositeTask.structuredContent.result.lists[0].tasks[0].id;
   callTool(oauth.accessToken, sessionId, 117, "open_workspace", {
     action: "member",
     workspaceId: compositeWorkspaceId,
@@ -707,6 +813,14 @@ try {
       workspaceId,
     },
   });
+  const memberScopedCompositeTasks = callTool(oauth.accessToken, sessionId, 138, "capability", {
+    workspaceId: compositeWorkspaceId,
+    member: "code",
+    name: "workspace.tasks",
+    action: "run",
+    arguments: { operation: "get" },
+  });
+  assert.equal(memberScopedCompositeTasks.isError, true);
   const closedComposite = callTool(oauth.accessToken, sessionId, 118, "close_workspace", {
     workspaceId: compositeWorkspaceId,
   });
@@ -727,6 +841,13 @@ try {
     path: "composite-sentinel.txt",
   });
   assert.equal(closedCompositeRead.isError, true);
+  const closedCompositeTasks = callTool(oauth.accessToken, sessionId, 139, "capability", {
+    workspaceId: compositeWorkspaceId,
+    name: "workspace.tasks",
+    action: "run",
+    arguments: { operation: "get" },
+  });
+  assert.equal(closedCompositeTasks.isError, true);
 
   const reopenedComposite = callTool(oauth.accessToken, sessionId, 121, "open_workspace", {
     workspaceId: compositeWorkspaceId,
@@ -735,6 +856,18 @@ try {
   assert.equal(reopenedComposite.structuredContent.workspaceId, compositeWorkspaceId);
   assert.equal(reopenedComposite.structuredContent.status, "active");
   assert.equal(reopenedComposite.structuredContent.members[0].workspaceId, workspaceId);
+  const reopenedCompositeTasks = callTool(oauth.accessToken, sessionId, 140, "capability", {
+    workspaceId: compositeWorkspaceId,
+    name: "workspace.tasks",
+    action: "run",
+    arguments: { operation: "get" },
+  });
+  assert.equal(reopenedCompositeTasks.isError, undefined);
+  assert.equal(reopenedCompositeTasks.structuredContent.result.lists[0].tasks[0].id, compositeTaskId);
+  assert.equal(
+    reopenedCompositeTasks.structuredContent.result.lists[0].tasks[0].content,
+    "Composite-owned state",
+  );
   const reopenedCompositeRead = callTool(oauth.accessToken, sessionId, 122, "read", {
     workspaceId: compositeWorkspaceId,
     member: "code",
@@ -748,6 +881,7 @@ try {
   });
   assert.equal(deletedComposite.structuredContent.action, "delete");
   assert.equal(deletedComposite.structuredContent.dissolved, true);
+  assert.equal(existsSync(compositeTaskStatePath), false);
   const memberAfterCompositeDelete = callTool(oauth.accessToken, sessionId, 124, "read", {
     workspaceId,
     path: "composite-sentinel.txt",
@@ -759,6 +893,10 @@ try {
     workspaceId: compositeWorkspaceId,
   });
   assert.equal(deletedCompositeInventory.structuredContent.compositeWorkspaces.length, 0);
+  pass(
+    "Composite workspace tasks",
+    `${compositeWorkspaceId} self-owned Task state -> close/reopen -> delete cleanup; member-scoped Task access rejected`,
+  );
   pass(
     "Composite lifecycle",
     `${compositeWorkspaceId} close -> closed/non-routable -> same-id reopen -> delete; member Workspace preserved`,