@akira-tl/forgerelay 0.8.1 → 0.8.3

package/CHANGELOG.md

@@ -4,6 +4,19 @@ 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
+
+- Managed-worktree Workspace close now preserves the same identity for later reopen with fresh backing; explicit delete safely finalizes active work before removing ForgeRelay-owned state.
+- Composite Workspace close now preserves identity and member topology for later reopen; explicit delete dissolves only the Composite relationship and leaves member Workspaces untouched.
+
 ## [0.8.1] - 2026-08-30
 
 ### Added

package/README.md

@@ -136,8 +136,10 @@ ForgeRelay does not merge member filesystems, Git state, Hooks, Skills, processe
 or audit facts, and it never infers a member from the tool type or purpose text.
 The Composite Activity Panel presents member operations in one Host Turn while the
 actual facts remain owned by the member Workspace. `close_workspace` on a Composite
-Workspace means **dissolve**: the Composite identity and membership are removed, but
-member Workspaces, worktrees, running jobs, files, and relay routes are preserved.
+Workspace now preserves the Composite identity and member topology as `closed`; a
+later `open_workspace` restores the same `cws_...` identity. `action="delete"` is the
+explicit dissolve operation. Neither close nor delete closes member Workspaces,
+finalizes their worktrees, stops their jobs, changes their files, or removes relay routes.
 
 ### Progressive MCP context
 

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/composite-activity.js

@@ -12,7 +12,7 @@ export class CompositeActivityCoordinator {
         return this.composites.has(workspaceId);
     }
     beginPanel(workspaceId, conversationScopeId) {
-        this.composites.open(workspaceId);
+        this.composites.touchActive(workspaceId);
         const snapshot = this.queries.beginTurn(conversationScopeId, workspaceId);
         this.turns.set(snapshot.turnId, {
             compositeWorkspaceId: workspaceId,

package/dist/composite-workspaces.js

@@ -13,16 +13,20 @@ export class CompositeWorkspaceRegistry {
     has(workspaceId) {
         return this.records.has(workspaceId);
     }
+    isActive(workspaceId) {
+        return this.records.get(workspaceId)?.status === "active";
+    }
     create(name) {
         const normalized = normalizeName(name);
         const existing = [...this.records.values()].find((record) => record.name === normalized);
         if (existing)
-            return this.touch(existing.id);
+            return this.open(existing.id);
         const now = new Date().toISOString();
         const record = {
             id: `cws_${randomBytes(5).toString("hex")}`,
             kind: "composite",
             name: normalized,
+            status: "active",
             members: [],
             createdAt: now,
             lastUsedAt: now,
@@ -38,7 +42,17 @@ export class CompositeWorkspaceRegistry {
         return cloneRecord(record);
     }
     open(workspaceId) {
-        return this.touch(workspaceId);
+        const record = this.requireRecord(workspaceId);
+        record.status = "active";
+        return this.touchRecord(record);
+    }
+    close(workspaceId) {
+        const record = this.requireActive(workspaceId);
+        record.status = "closed";
+        return this.touchRecord(record);
+    }
+    touchActive(workspaceId) {
+        return this.touchRecord(this.requireActive(workspaceId));
     }
     list() {
         return [...this.records.values()]
@@ -46,7 +60,7 @@ export class CompositeWorkspaceRegistry {
             .sort((left, right) => right.lastUsedAt.localeCompare(left.lastUsedAt));
     }
     addMember(workspaceId, input) {
-        const record = this.requireRecord(workspaceId);
+        const record = this.requireActive(workspaceId);
         const name = normalizeMemberName(input.name);
         const purpose = input.purpose.trim();
         if (!purpose)
@@ -64,7 +78,7 @@ export class CompositeWorkspaceRegistry {
         return cloneRecord(record);
     }
     updateMember(workspaceId, memberName, input) {
-        const record = this.requireRecord(workspaceId);
+        const record = this.requireActive(workspaceId);
         const currentName = normalizeMemberName(memberName);
         const index = record.members.findIndex((member) => member.name === currentName);
         if (index < 0)
@@ -94,7 +108,7 @@ export class CompositeWorkspaceRegistry {
         return cloneRecord(record);
     }
     removeMember(workspaceId, memberName) {
-        const record = this.requireRecord(workspaceId);
+        const record = this.requireActive(workspaceId);
         const name = normalizeMemberName(memberName);
         const index = record.members.findIndex((member) => member.name === name);
         if (index < 0)
@@ -105,7 +119,7 @@ export class CompositeWorkspaceRegistry {
         return cloneRecord(record);
     }
     member(workspaceId, memberName) {
-        const record = this.requireRecord(workspaceId);
+        const record = this.requireActive(workspaceId);
         const name = normalizeMemberName(memberName);
         const member = record.members.find((entry) => entry.name === name);
         if (!member)
@@ -118,12 +132,18 @@ export class CompositeWorkspaceRegistry {
         this.persist();
         return cloneRecord(record);
     }
-    touch(workspaceId) {
-        const record = this.requireRecord(workspaceId);
+    touchRecord(record) {
         record.lastUsedAt = new Date().toISOString();
         this.persist();
         return cloneRecord(record);
     }
+    requireActive(workspaceId) {
+        const record = this.requireRecord(workspaceId);
+        if (record.status !== "active") {
+            throw new Error(`Composite Workspace ${workspaceId} is closed. Reopen it with open_workspace before use.`);
+        }
+        return record;
+    }
     requireRecord(workspaceId) {
         const record = this.records.get(workspaceId);
         if (!record)
@@ -140,7 +160,7 @@ export class CompositeWorkspaceRegistry {
                 return;
             throw new Error(`Failed to load Composite Workspace state: ${errorMessage(error)}`);
         }
-        if (parsed?.version !== 1 || !Array.isArray(parsed.workspaces)) {
+        if ((parsed?.version !== 1 && parsed?.version !== 2) || !Array.isArray(parsed.workspaces)) {
             throw new Error("Composite Workspace state has an unsupported format.");
         }
         for (const record of parsed.workspaces) {
@@ -148,6 +168,7 @@ export class CompositeWorkspaceRegistry {
                 continue;
             this.records.set(record.id, {
                 ...record,
+                status: record.status === "closed" ? "closed" : "active",
                 members: Array.isArray(record.members) ? record.members.map((member) => ({ ...member })) : [],
             });
         }
@@ -155,7 +176,7 @@ export class CompositeWorkspaceRegistry {
     persist() {
         mkdirSync(this.stateDir, { recursive: true });
         const state = {
-            version: 1,
+            version: 2,
             workspaces: [...this.records.values()].map(cloneRecord),
         };
         const tempPath = `${this.statePath}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;

package/dist/git-worktrees.js

@@ -57,6 +57,28 @@ export async function createManagedWorktree(input) {
         managed: true,
     };
 }
+export async function discardFreshManagedWorktree(input) {
+    const sourceRoot = assertAllowedPath(input.worktree.sourceRoot, input.config.allowedRoots);
+    const worktreePath = assertAllowedPath(input.worktree.path, [input.config.worktreeRoot]);
+    const worktreeBranch = await currentBranch(worktreePath);
+    if (worktreeBranch !== input.worktree.branch) {
+        throw new GitWorktreeError("GIT_WORKTREE_CLOSE_FAILED", `Cannot roll back reopened worktree because it is on branch ${JSON.stringify(worktreeBranch)} instead of ${JSON.stringify(input.worktree.branch)}.`);
+    }
+    if ((await git(["status", "--porcelain=v1"], worktreePath)).trim().length > 0) {
+        throw new GitWorktreeError("GIT_WORKTREE_CLOSE_FAILED", "Cannot roll back reopened worktree because it acquired uncommitted changes during reopen.");
+    }
+    const worktreeHead = (await git(["rev-parse", "HEAD"], worktreePath)).trim();
+    if (worktreeHead !== input.worktree.baseSha) {
+        throw new GitWorktreeError("GIT_WORKTREE_CLOSE_FAILED", "Cannot roll back reopened worktree because its branch advanced during reopen.");
+    }
+    try {
+        await git(["worktree", "remove", worktreePath], sourceRoot);
+        await git(["branch", "-D", input.worktree.branch], sourceRoot);
+    }
+    catch (error) {
+        throw new GitWorktreeError("GIT_WORKTREE_CLOSE_FAILED", `Git failed to remove the temporary managed worktree created for a failed reopen. ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
 export async function closeManagedWorktree(input) {
     const sourceRoot = assertAllowedPath(input.worktree.sourceRoot, input.config.allowedRoots);
     const worktreePath = assertAllowedPath(input.worktree.path, [input.config.worktreeRoot]);

package/dist/mcp/server-instructions.js

@@ -38,7 +38,7 @@ function capabilityContractInstructions(config) {
     const staleWorkspacePolicy = config.toolMode === "codex"
         ? ""
         : ` If ${toolNames.openWorkspace} reports stale workspaces, let the user choose resume or ${toolNames.closeWorkspace}; never auto-close.`;
-    const workspaceLifecycle = `Use ForgeRelay as a local coding workspace. Default to the user's existing checkout. Reuse workspaceId from ${toolNames.openWorkspace}; change it only when asked.${staleWorkspacePolicy} Only open mode=\"worktree\" when the user explicitly asks for isolated or parallel Git work. ${toolNames.closeWorkspace} defaults to closing checkout Workspaces for later reopen; action=delete removes only ForgeRelay-owned checkout state, never project files. Managed close finalizes the worktree and requires commitMessage.`;
+    const workspaceLifecycle = `Default to the user's existing checkout. Reuse workspaceId from ${toolNames.openWorkspace}; change it only when asked.${staleWorkspacePolicy} Only open mode=\"worktree\" when the user explicitly asks for isolated or parallel Git work. ${toolNames.closeWorkspace} preserves Workspace identity. Managed close finalizes backing and needs commitMessage. Composite close preserves members; delete removes only Composite state. Active worktree delete still finalizes safely; checkout files are never deleted.`;
     const activityPanel = `Project-work order: ${toolNames.openWorkspace} if needed → activity_panel(workspaceId) once → work tools. activity_panel is the single ForgeRelay UI render tool: Workspace above Activity. A new workspaceId creates a new card. Never call activity_panel before needed ${toolNames.openWorkspace}.`;
     const agents = `Follow instructions returned by ${toolNames.openWorkspace}. Read an availableAgentsFiles path before working under it.`;
     const capabilityGuides = `For optional capabilities from ${toolNames.openWorkspace}, use ${toolNames.capability}; if unfamiliar, describe first and read its advertised capability guide with ${toolNames.read}.`;